holimart/langywrap

# langywrap 通用 AI 代理编排工具包。执行安全，ralph 循环， hyperagent 演化，复合工程，项目脚手架。 ## 快速开始 ``` # 安装（交互式向导） ./install.sh # 耦合下游项目 ./just couple /path/to/my-project # 从模板创建新项目 langywrap scaffold new /path/to/parent my-project ``` ## 安装 ### 交互式向导（推荐） ``` ./install.sh ``` 向导将引导您了解每项功能： | 功能 | 默认值 | 作用 | |---------|---------|-------------| | Python 包 | 是 | 通过 `uv` 以可编辑模式安装 `langywrap` | | RTK 压缩 | 是 | 从源代码构建 RTK（`cargo build --release`），可节省 60-90% 的 token | | 全局配置 | 是 | 通过符号链接管理 `~/.claude/` 的 hooks、设置、技能 | | ExecWrap | 是 | 针对 AI 工具的 5 层执行包装器 | | 安全 hooks | 是 | 按工具划分的命令阻止（Claude、OpenCode、Cursor、Cline） | | Git hooks | 是 | 提交前 Python 扫描 + 强制推送保护 | | 技能 | 是 | Claude Code 斜杠命令（`/ralph-loop`、`/compound` 等） | | HyperAgents | 是 | 代理演化框架 + 实验归档 | | 复合工程 | 是 | 跨项目经验教训中心 | ### 非交互式 ``` ./install.sh --defaults # Accept all defaults ./install.sh --dry-run # Preview without changes ``` ### 重新运行 随时再次运行 `./install.sh` 以更改您的设置。先前的选择将被 记住并显示为默认值。 ### 前置条件 | 工具 | 是否必需 | 用途 | |------|----------|---------| | Python >= 3.11 | 是 | 库运行时（通过 `.python-version` 固定为 3.12） | | git | 是 | 版本控制 | | uv | 推荐 | 包管理（回退到 pip） | | cargo (Rust) | RTK 需要 | 构建 RTK 输出压缩器 | | just | 推荐 | 任务运行器 | | jq | 配置合并需要 | 合并 settings.json | ## 运行 AI 工具 安装后，通过安全包装器运行 Claude Code 或 OpenCode： ``` # 使用 ExecWrap（完整的 5 层安全） /path/to/langywrap/execwrap/execwrap.bash claude /path/to/langywrap/execwrap/execwrap.bash opencode # 提示：将别名添加到你的 shell rc alias cw='/path/to/langywrap/execwrap/execwrap.bash claude' alias ow='/path/to/langywrap/execwrap/execwrap.bash opencode' ``` 在安装了 ExecWrap 的耦合项目中： ``` .exec/execwrap.bash claude .exec/execwrap.bash opencode ``` 如果没有 ExecWrap，全局 hooks 仍然通过 `~/.claude/hooks/` 提供安全性。 ## 耦合项目 ``` ./just couple /path/to/project # Interactive wizard ./just couple /path/to/project --full # All features ./just couple /path/to/project --minimal # Security only ./just couple /path/to/project --dry-run # Preview ``` 耦合会按项目安装以下内容： | 功能 | 安装的内容 | |---------|-------------------| | 安全 hooks | `.claude/hooks/`、`.opencode/plugins/`、`.cursor/hooks/` | | ExecWrap | `.exec/execwrap.bash` + 设置 + 预加载 | | Git hooks | `.githooks/pre-commit` + `pre-push` | | Ralph 循环 | `research/ralph/` 状态目录 + 提示词模板 | | HyperAgents | `.langywrap/router.yaml`（模型路由配置） | | 复合工程 | `docs/solutions/` + `_template.md` | | 质量门控 | 精简输出配置检查 | | 包装器 | `./just` + `./uv`（防止分页） | | 开发依赖 | `langywrap` 作为可编辑的 uv 开发依赖 | ### 耦合配置 耦合后，项目将包含 `.langywrap/` 目录，其中有： ``` .langywrap/ config.yaml # Project name, langywrap path, archive pointers router.yaml # ExecutionRouter model routing (HyperAgent-evolvable) ralph.yaml # Ralph loop settings (budget, gates, git paths) ``` ## 组件 ### ExecutionRouter 将工作流步骤路由到 AI 后端，支持重试、回退和演化。 ``` lib/langywrap/router/ backends.py — ClaudeBackend, OpenCodeBackend, OpenRouterBackend, DirectAPIBackend, MockBackend config.py — RouteConfig, RouteRule, StepRole, ModelTier router.py — ExecutionRouter (dispatch, retry, stats, dry-run) evolution.py — RouteEvolver (HyperAgent-driven config mutation) ``` 按项目配置在 `.langywrap/router.yaml` 中。默认路由： | 角色 | 模型 | 后端 | |------|-------|---------| | orient | claude-haiku-4-5 | claude | | plan | claude-sonnet-4-6 | claude | | execute | kimi-k2.6 | opencode (免费) | | critic | claude-haiku-4-5 | claude | | finalize | kimi-k2.6 | opencode (免费) | | review (每 10 次) | claude-opus-4-6 | claude | ### Ralph 循环 用于自主 AI 研究/工程循环的混合 Python 编排器。 5 步流水线：orient -> plan -> execute -> critic -> finalize。 ``` lib/langywrap/ralph/ config.py — RalphConfig, StepConfig, QualityGateConfig state.py — RalphState (tasks.md, progress.md, orient context compression) runner.py — RalphLoop (the main loop with quality gates + git commit) context.py — Template substitution, scope restriction injection prompts/ — Default step prompt templates ``` 核心特性：**Orient 上下文预消化** —— 在输入到 orient 模型之前，将大型状态文件 （tasks.md、progress.md）压缩约 11 倍。 #### 可选：knowledge-graph 丰富 Ralph 步骤可以通过在 `.langywrap/ralph.py` 中设置 `enrich=["graphify"]` 来将最新的代码图谱摘要拉取到其提示词中，并且循环可以通过 `post_cycle_commands` 保持图谱处于最新状态： ``` Step("orient", model="haiku", prompt="step1_orient.md", enrich=["graphify"]), # 在 gates 之后、commit 之前运行 — 非零退出被视为警告。 post_cycle_commands=[ "textify docs graphify-in/docs || true", # LLM-free doc flatten "graphify update .", # LLM-free code re-index ], ``` `graphify` 和 `textify` 作为子模块被提供，并通过 langywrap 的 `knowledge-graph` uv 扩展安装（`uv sync --extra knowledge-graph`， 或 `./just install-graphify` / `./just install-textify`）。在耦合仓库中 运行 `/graphify-setup` 可进行交互式设置，该设置会生成 `.graphifyignore` 并可选择接入 post-commit 钩子。如果在循环开始时 启用了丰富功能但没有安排重建，或者如果 使用了 `graphify .`（完整构建）但没有在它之前使用 `textify`（避免 在二进制文档上产生无声的 LLM 消耗），运行器会发出警告。 #### Dry-run 预检 `langywrap ralph --dry-run` 运行无 LLM 的 `MockBackend` 探测。它检查 工具发现和运行时连接是否一致，包括同级/可编辑安装： | 字段 | 含义 | |-------|---------| | `execwrap_applied` | 后端命令通过 execwrap 启动 | | `rtk_outer_applied` | 后端命令直接以 RTK 为前缀 | | `rtk_internal_applied` | execwrap shell 模式发出了内部 RTK 重写 | | `rtk_wired` | RTK 实际处于活动状态（外部或内部） | | `execwrap_project_dir_is_project` | 同级 execwrap 通过 `EXECWRAP_PROJECT_DIR` 使用目标项目 | 当 execwrap 存在时，预期 `rtk_outer_applied=false`。重要的 信号是 `rtk_wired=true`，它确认 execwrap 能够找到 RTK 并执行 重写后的 `rtk ...` 命令。 ### OpenWolf 集成 OpenWolf 作为运行时内存钩子接入，而不是作为命令包装器。使用： ``` langywrap integration openwolf status . langywrap integration openwolf wire . --init --langywrap-only ``` `--langywrap-only` 将 Claude hooks 和 OpenCode 插件限制在 `LANGYWRAP_OPENWOLF=1` 之后，因此除非 langywrap 设置了该环境变量，否则正常的直接工具启动不会激活 OpenWolf。 ### HyperAgents + Memento 技能 代理演化框架。每个耦合的仓库都通过 ralph 循环参与。 ``` lib/langywrap/hyperagents/ archive.py — AgentVariant, Archive (growing population of configs) mutations.py — Random + meta-mutations (LLM-guided optimization) engine.py — HyperAgentEngine (evolve, record, exploit/explore) skills.py — SkillLibrary (Memento pattern: utility-scored skills) experiments/ archive/ — Variant YAML files (git-versioned, nothing lost) meta/ — meta_agent.py (standalone evolution script) ``` ### 安全 来自 execsec 的合并权限。系统拒绝绝对不能被项目覆盖。 ``` lib/langywrap/security/ permissions.py — Load + merge YAML configs (KEY FIX: deny-at-any-level wins) engine.py — SecurityEngine (check, check_and_exec) audit.py — JSON-lines audit logging defaults/ — Bundled permissions.yaml + resources.yaml interceptors/ — intercept-enhanced.py (57-rule YAML interceptor) ``` ### MockBackend（测试） 用于集成测试的基于 Bash 的模拟 LLM。验证通过 ExecutionRouter 路由的命令是否受 SecurityEngine 检查的约束。 ``` from langywrap.router import Backend, BackendConfig, MockBackend config = BackendConfig(type=Backend.MOCK, env_overrides={"MOCK_RESPONSE": "test"}) backend = MockBackend(config) result = backend.run("prompt", "mock-v1", timeout=10) # 此外：run_with_security_check("rm -rf /", security_engine=engine) ``` ## 开发 ``` ./just sync # Install dependencies ./just check # Lint + typecheck + test ./just dev # Fix + check (full cycle) ./just test # pytest ./just lint # ruff check -q ./just typecheck # mypy ``` Pytest 收集被有意限制在 `tests/` 目录中；诸如 `graphify/` 之类的供应商子模块拥有自己的测试套件，否则会与 langywrap 的顶级 `tests` 包发生冲突。 有用的针对性测试命令： ``` uv run pytest tests/test_helpers/test_discovery.py uv run pytest tests/test_integrations/test_openwolf.py uv run pytest tests/test_ralph/test_dry_run_probe.py uv run pytest tests/test_execwrap/test_rtk_integration.py uv run --extra dev pytest --cov=langywrap --cov-report=term-missing ``` 测试覆盖的回归经验： | 领域 | 受保护的行为 | |------|--------------------| | 发现 | 项目本地、已配置的 hub、同级 langywrap、PATH 以及可操作的提示 | | execwrap + RTK | 同级 execwrap 找到 `../.exec/rtk`，将其放到 `PATH` 上，并在 shell 模式下进行重写 | | 质量门控 | 记录的 execwrap 命令保留失败的退出码（`pipefail`） | | dry-run 探测 | `rtk_wired` 检测实际内部的 RTK 重写，而不仅仅是发现 | | OpenWolf | Claude hooks 和 OpenCode 插件支持 `--langywrap-only` 门控 | ## 项目结构 ``` langywrap/ lib/langywrap/ Python library (pip-installable) security/ Execution security (permissions, audit, interceptors) router/ ExecutionRouter (model/backend routing, retry, evolution) ralph/ Ralph loop orchestration (hybrid Python/bash) hyperagents/ HyperAgent evolution + Memento Skills quality/ Quality gates (ruff, mypy, pytest, lean) compound/ Compound engineering (lessons learned flow) template/ Project scaffolding helpers/ Categorized helper scripts (python, bash, lean, data) hooks/ Per-tool security hooks execwrap/ Universal 5-layer execution wrapper harden/ Repo hardening installer rtk/ Output compression (git submodule, build from source) textify/ LLM-free doc extraction (git submodule, opt-in via knowledge-graph extra) graphify/ Code-graph skill (git submodule, opt-in via knowledge-graph extra) experiments/ HyperAgent archive + evolution configs skills/ Claude Code slash commands agents/ Sub-agent definitions configs/ Global config templates, semgrep, docker docs/solutions/ Compound engineering hub scripts/ Install, coupling, utility scripts tests/ 58 tests (security, ralph, router, scaffold, evolution) spec/ Design specs from initial creation ``` ## 许可证 MIT

标签：Agent框架, AI安全, AI开发工具, AI编排, API接口, Chat Copilot, Claude, CVE检测, DLL 劫持, Git钩子, HyperAgent, LLM, Python, Rust, Token压缩, Unmanaged PE, 可视化界面, 复合工程, 大语言模型, 安全封装, 安全规则引擎, 应用安全, 执行安全, 提示词工程, 搜索语句（dork）, 无后门, 策略决策点, 网络流量审计, 自动化运维, 逆向工具, 项目脚手架