[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-85165":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":15,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":16,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":10,"pushedAt":10,"updatedAt":37,"readmeContent":38,"aiSummary":10,"trendingCount":15,"starSnapshotCount":15,"syncStatus":39,"lastSyncTime":40,"discoverSource":41},85165,"Code-Agent-plusplus","whut09\u002FCode-Agent-plusplus","whut09","Code Agent++  面向 AI 编程 Agent 的外挂式增强与可靠性工程层。  Code Agent++ 不做另一个代码生成 Agent，也不替代 Codex、OpenCode、Claude Code、Cursor、MiMoCode 写代码。它的定位是 Code Agent Enhancement Layer：围绕 Code Agent 在真实工程中的常见问题，提供上下文、边界、验证、回归防护、幻觉抑制、影响分析和修复闭环等外挂式增强能力。","",null,"TypeScript",106,11,10,0,36.24,false,"main",true,[21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36],"agent","claude-code","codex","cursor","harness","harness-ai","harness-engineering","loop-engineering","mcp","mcp-tools","mimo-code","mimocode","opencode","opencode-ai","opencode-plugin","vscode-extension","2026-06-15 10:05:05","# Code Agent++\n\n中文 | [English](README.en.md)\n\n**Code Agent++：面向 Code Agent 的外挂式增强与可靠性工程层。**\n\nCode Agent++ 不做另一个代码生成 Agent，也不替代 Codex、OpenCode、Claude Code、Cursor、MiMoCode 写代码。它的定位是 **Code Agent Enhancement Layer \u002F Agent Reliability Layer**：围绕 Code Agent 在真实工程中的常见失败模式，提供上下文、边界、验证、回归防护、幻觉抑制、影响分析和修复闭环等外挂式增强能力。\n\nCode Agent 本身已经具备较强的读代码、改代码、跑命令能力，但在复杂仓库中仍然容易出现工程问题：\n\n- 缺少准确上下文，靠猜测定位文件和模块。\n- 修改范围失控，误改无关文件或 protected path。\n- 生成不存在的 API、配置、命令或项目约定，产生工程幻觉。\n- 测试证据不可信，先测试通过后又继续改代码。\n- 改动影响范围不可见，review 风险难以判断。\n- 曾经修复过的问题，在后续修改中被重新引入。\n- repair loop 反复执行，无法判断该继续、回滚还是收口。\n- `AGENTS.md`、`CLAUDE.md`、Cursor rules 等上下文文件过大、过旧或互相冲突。\n\nCode Agent++ 的目标不是让 Agent “更会生成代码”，而是让 Agent 的修改过程 **更有边界、更有证据、更可验证、更少回归**。\n\n```txt\nCode Agent 负责写代码\nCode Agent++ 负责约束、验证、记录、纠偏和防回归\n```\n\n核心闭环：\n\n```txt\nContext -> Agent -> Execution -> Trace -> Evaluation -> Context Update -> Loop\n```\n\n当前实现更准确地说是 Context \u002F Policy \u002F Trace 报告系统 + 显式 runtime 状态机 + 半自动 loop 建议器：它不会自主调用 Agent 改代码，但会消费 trace evidence、policy、contracts、impact 和 freshness，更新 `.agent-context\u002Fruns\u002F\u003Ctask-id>\u002Fstate.json`，并生成下一步优先动作。目标形态是有状态、自主推进、证据驱动的 Agent Harness Runtime。\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fcontext-pack-demo.svg\" width=\"900\" alt=\"Code Agent++ 输出效果动画\">\n\u003C\u002Fp>\n\n## 通过 AI Agent 使用\n\n这个项目的主要用户就是 AI 编程工具。你可以直接在 Codex、Claude Code、Cursor、OpenCode、MiMoCode 或其他 Agent 里说：\n\n```txt\n使用 https:\u002F\u002Fgithub.com\u002Fwhut09\u002FCode-Agent-plusplus 对 xxx 项目生成 Code Agent++ 上下文与可靠性增强包。\n请先检查目标仓库结构，再按需安装或克隆该工具。\n请强制启用 LLM 摘要：在目标仓库创建或更新 code-agent-plusplus.local.yml，不要提交该文件，优先使用当前 AI 工具环境里可用的模型 API 配置，或我提供的 key\u002FbaseUrl\u002Fmodel；如果缺少配置，请先问我。\n然后运行 code-agent-plusplus build \u003C目标仓库> --target codex --llm，再运行 code-agent-plusplus validate \u003C目标仓库>，最后说明生成了哪些文件、哪些 Guard 能力可用，以及 LLM 摘要模式是否成功。\n```\n\n把 `xxx 项目` 换成本地路径、GitHub 仓库或当前工作区名称即可。真实 key 只写入 `code-agent-plusplus.local.yml`，不要提交。\n\n## 核心理念\n\nCode Agent++ 采用问题驱动的外挂式架构：\n\n```txt\nCode Agent 出现什么类型的问题\n  -> Code Agent++ 挂载对应的 Guard \u002F Enhancer 模块\n```\n\n典型映射：\n\n| Code Agent 失败模式                | Code Agent++ 模块                   |\n| ---------------------------------- | ----------------------------------- |\n| 上下文不准、乱搜文件               | Context Guard                       |\n| 幻觉 API \u002F 幻觉命令 \u002F 幻觉项目约定 | Hallucination Guard                 |\n| 修改范围失控                       | Boundary Guard                      |\n| 重复引入历史 bug                   | Regression Guard                    |\n| 测试证据不可信                     | Evidence Guard                      |\n| 改动影响范围不可见                 | Impact Guard                        |\n| 修复循环无法收口                   | Loop Guard                          |\n| 多种 Agent 输出格式不统一          | Executor Adapter + Trace Normalizer |\n\n`AGENTS.md` 只是 Context Guard 的一种输出形式。Code Agent++ 更大的目标，是成为 Codex \u002F OpenCode \u002F Claude Code \u002F Cursor \u002F MiMoCode 的外挂可靠性层。\n\n## 技术路线\n\nCode Agent++ 的技术路线分为三层：执行前增强、执行中约束、执行后验证。\n\n### 1. 执行前：让 Agent 少猜\n\n在 Code Agent 开始改代码之前，Code Agent++ 先对仓库进行结构化分析，生成任务级上下文和工程边界。\n\n主要能力：\n\n- 仓库结构分析。\n- 模块关系分析。\n- 任务相关文件检索。\n- task-aware context pack。\n- `AGENTS.md` \u002F `CLAUDE.md` \u002F Cursor rules \u002F OpenCode instructions 导出。\n- 编辑边界生成。\n- protected path 识别。\n- 历史修复记录、known issues、anti-regression notes 注入。\n- 推荐测试路径和验证命令。\n\n这一层解决：Agent 不知道该看哪里、不知道哪里不能动、不知道历史上踩过哪些坑、不知道改完该怎么验证。\n\n### 2. 执行中：让 Agent 有边界\n\nCode Agent++ 不直接替代 Agent 写代码，而是通过 Executor Adapter 外挂到不同 Code Agent：\n\n- OpenCode Executor\n- Codex CLI Executor\n- Claude Code Executor\n- Cursor Executor\n- MiMoCode Executor\n- Mock Executor\n\n典型流程：\n\n```txt\nCode Agent++ plan\n  -> Code Agent++ pack\n  -> 调用 OpenCode \u002F Codex \u002F Claude Code \u002F Cursor \u002F MiMoCode 执行修改\n  -> 收集 diff、命令、日志、事件流\n  -> 进入验证和决策\n```\n\n关键原则：**Code Agent 可以自主改代码，但不能自主宣布完成。** Agent 是否真的完成任务，要由 Code Agent++ 根据证据、diff、测试和策略门禁来判断。\n\n### 3. 执行后：让修改可验证、可审计、少回归\n\nAgent 修改完成后，Code Agent++ 进入验证与决策阶段。\n\n主要能力：\n\n- diff changed files 分析。\n- allowed \u002F denied edit boundary 检查。\n- protected path 检查。\n- dependency impact \u002F blast radius 分析。\n- 测试推荐与测试执行。\n- command trace 记录。\n- exit code、timestamp、working tree hash 校验。\n- 测试证据是否晚于最后一次编辑。\n- 回归风险检测。\n- 历史 bug \u002F known issue 对照。\n- repair \u002F repack \u002F rerun tests \u002F finalize 决策。\n\n这一层解决：Agent 说完成了到底有没有完成、测试证据可信吗、有没有越界修改、有没有引入旧 bug、影响了哪些下游模块、现在该继续修还是等待人工 review。\n\n## Guard 模块\n\n### Context Guard\n\n负责任务级上下文增强。输出包括 `AGENTS.md`、`CLAUDE.md`、Cursor rules、OpenCode instructions、task pack、module map、relevant files 和 validation hints。目标是减少上下文丢失、无效搜索和 token 浪费。\n\n### Hallucination Guard\n\n负责降低工程幻觉。检查 Agent 是否使用了仓库中不存在的文件、API、函数、配置项、CLI 命令、测试命令、项目约定、依赖包或环境变量。目标是把“模型觉得应该有”变成“仓库证据证明真的有”。\n\n### Boundary Guard\n\n负责约束修改范围。生成并检查 allowed edit paths、denied edit paths、protected paths、generated files、lockfiles、migration files、CI \u002F deploy \u002F infra 配置。目标是防止 Agent 为了完成局部任务而扩大修改面。\n\n### Regression Guard\n\n负责防止旧问题被重新引入。维护 fix history、known issues、previous bug patterns、regression notes、anti-regression tests、fragile modules 和 historical failure cases。目标是让 Agent 在新任务中记住过去已经修复过的问题。\n\n### Evidence Guard\n\n负责验证测试证据是否可信。它不只看 Agent 的自然语言总结，而是检查实际执行过什么命令、exit code 是否为 0、测试输出是否存在、测试时间是否晚于最后一次编辑、测试时的 working tree hash 是否匹配，以及是否存在“测试后又改代码”的证据污染。\n\n### Impact Guard\n\n负责分析 diff 的工程影响范围。检查 changed files、affected modules、downstream dependencies、tests to run、review risk、unexpected file changes 和 scope expansion。目标是让 Agent 的修改不只是能跑，还能被 review 和合并。\n\n### Loop Guard\n\n负责控制 repair\u002Ffinalize 闭环。它会根据策略、测试、影响分析和证据验证结果，决定下一步应该 finalize、rerun tests、repair code、repair tests、repack context、block、rollback 或 require human review。\n\n更多实现细节见 [Guard Modules](docs\u002Fguard-modules.zh-CN.md)。\n\n## 30 秒怎么用？\n\n```bash\nnpx code-agent-plusplus build .\ncode-agent-plusplus plan \"fix login timeout bug\" .\ncode-agent-plusplus pack \"fix login timeout bug\" .\n```\n\n`code-agent-plusplus` 是唯一推荐的 CLI 命令；MCP server 使用 `code-agent-plusplus-mcp`。\n\n本地源码运行：\n\n```bash\nnpm install\nnpm run build\nnode dist\u002Fcli\u002Findex.js build .\n```\n\n常用闭环：\n\n```bash\ncode-agent-plusplus run \"fix login timeout bug\" . --type bugfix\ncode-agent-plusplus orchestrate \"fix login timeout bug\" . --executor mock --fail-on required\ncode-agent-plusplus agent run \"fix login timeout bug\" . --executor opencode --executor-command \"opencode run --format json {prompt}\"\ncode-agent-plusplus trace run fix-login-timeout-bug . --action run-test --command \"npm test -- auth\"\ncode-agent-plusplus policy . --base main --trace fix-login-timeout-bug --fail-on required\ncode-agent-plusplus impact . --base main\ncode-agent-plusplus verify --diff .\ncode-agent-plusplus freshness .\ncode-agent-plusplus drift .\n```\n\n## 当前状态\n\n| 能力                                                 | 状态                   |\n| ---------------------------------------------------- | ---------------------- |\n| `build` \u002F `AGENTS.md` \u002F `.agent-context`             | implemented            |\n| task plan \u002F pack \u002F run                               | implemented            |\n| TypeScript Compiler API analyzer                     | implemented            |\n| Python AST \u002F optional Tree-sitter analyzer           | implemented            |\n| token savings estimated + actual output tokens       | implemented            |\n| readiness 分维度评分和硬上限                         | implemented            |\n| Context \u002F Boundary \u002F Evidence \u002F Impact \u002F Loop Guards | implemented foundation |\n| Hallucination \u002F Regression Guards                    | planned                |\n| harness orchestrator \u002F `orchestrate`                 | implemented            |\n| `agent run` executor wrapper                         | implemented            |\n| mock executor                                        | implemented            |\n| generic executor command adapter                     | implemented            |\n| OpenCode \u002F MiMoCode 原生事件 normalizer              | planned                |\n| runtime state machine \u002F `state.json`                 | implemented            |\n| policy engine                                        | implemented            |\n| context delta analysis                               | implemented            |\n| tests \u002F impact \u002F verify                              | implemented            |\n| freshness \u002F drift \u002F manifest                         | implemented            |\n| MCP server scaffold                                  | implemented            |\n| Agent Native Runtime loop tools                      | experimental           |\n| benchmark harness                                    | experimental           |\n| direct LightRAG server sync                          | planned                |\n\n## 输出内容\n\n```txt\nAGENTS.md\nAGENTS.manual.md\n.agent-context\u002F\n  AGENTS.generated.md\n  manifest.json\n  repo-summary.md\n  key-files.md\n  module-map.md\n  dependency-graph.md\n  readiness.md\n  token-savings.md\n  contracts\u002F\n  tasks\u002F\n  runs\u002F\n  loops\u002F\n  traces\u002F\n  delta\u002F\n  rag\u002F\n  evidence\u002F\n  index\u002F\n  graphs\u002F\n```\n\n根目录 `AGENTS.md` 默认保持很短，只放必须遵守的操作约束和深层上下文索引。更长的模块图、依赖图、readiness、token 报告、证据索引和任务包都放在 `.agent-context\u002F`。\n\n## AGENTS.md 会被自动读取吗？\n\n取决于编程 Agent 客户端，而不是大模型本身。\n\n- Codex：会读取 `AGENTS.md`。\n- Claude Code：默认读取 `CLAUDE.md`；可以创建 `CLAUDE.md` 并写入 `@AGENTS.md` 来复用。\n- Cursor：可把 `AGENTS.md` 放在项目根目录作为项目规则；复杂规则建议使用 `.cursor\u002Frules`。\n- 其他工具：支持情况不同；不支持自动加载时，把 `AGENTS.md` 手动附到 prompt 里。\n\n详细说明见 [docs\u002Fagents-md.zh-CN.md](docs\u002Fagents-md.zh-CN.md)。\n\n## 核心命令\n\n```bash\ncode-agent-plusplus build [repo]\ncode-agent-plusplus plan \"\u003Ctask>\" [repo]\ncode-agent-plusplus pack \"\u003Ctask>\" [repo]\ncode-agent-plusplus run \"\u003Ctask>\" [repo]\ncode-agent-plusplus orchestrate \"\u003Ctask>\" [repo] --executor mock --fail-on required\ncode-agent-plusplus agent run \"\u003Ctask>\" [repo] --executor opencode --executor-command \"opencode run --format json {prompt}\"\ncode-agent-plusplus trace start \"\u003Ctask>\" [repo] --agent codex\ncode-agent-plusplus trace run \u003Ctrace-id> [repo] --action run-test --command \"npm test -- auth\"\ncode-agent-plusplus policy [repo] --base main --trace \u003Ctrace-id> --fail-on required\ncode-agent-plusplus tests [repo] --diff --base main\ncode-agent-plusplus impact [repo] --base main\ncode-agent-plusplus verify --diff [repo]\ncode-agent-plusplus delta [repo] --base main\ncode-agent-plusplus evolve [repo] --base main\ncode-agent-plusplus loop \"\u003Ctask>\" [repo] --phase after-edit\ncode-agent-plusplus validate [repo]\ncode-agent-plusplus validate-contracts [repo]\ncode-agent-plusplus freshness [repo]\ncode-agent-plusplus drift [repo]\ncode-agent-plusplus benchmark [benchmarkDir] --top-k 8\ncode-agent-plusplus retrieve \"\u003Ctask>\" [repo] --provider hybrid\ncode-agent-plusplus-mcp\n```\n\n`policy --fail-on` 支持三档 CI 阈值：\n\n- `forbidden`：只让 forbidden edits 失败，适合本地探索。\n- `required`：forbidden + missing required actions 失败，是默认值，适合 PR 检查。\n- `risk`：forbidden + required + risk warnings 都失败，适合 main 分支或发布门禁。\n\n## Code Agent 集成\n\nCode Agent++ 的定位是面向 code agent 的 External Agent Harness Control Plane。Codex \u002F Claude Code \u002F Cursor \u002F OpenCode \u002F MiMoCode 负责实际读代码、改代码和跑命令；Code Agent++ 负责任务上下文、编辑边界、执行证据和验证闭环。\n\n```txt\nCodex \u002F Claude Code \u002F Cursor \u002F OpenCode \u002F MiMoCode\n  -> 负责读代码、改代码、跑命令、调用工具\n\nCode Agent++\n  -> 负责 context、boundary、trace、policy、impact、tests、verify、repair\u002Ffinalize 决策\n```\n\n项目支持两种工作模式：\n\n- Code Agent 主导，Code Agent++ 约束：Agent 调用 CLI \u002F MCP 工具，但最终是否遵守 gate 由宿主 Agent 决定。\n- Code Agent++ 主导，Code Agent 作为 executor：Code Agent++ 负责 plan \u002F pack \u002F execute \u002F collect evidence \u002F policy \u002F verify \u002F decision，外部 Agent 只作为可替换编码执行器。\n\n详细入口隔离说明见 [docs\u002Fintegration-modes.zh-CN.md](docs\u002Fintegration-modes.zh-CN.md)。\n\n## MCP \u002F Agent Native Runtime\n\n`code-agent-plusplus-mcp` 当前提供 stdio MCP server 和一组工具定义。它已经可以被支持 MCP 的客户端或自研 Agent 接入；Codex CLI、Claude Code、Cursor、OpenCode、MiMoCode、LibreChat、OpenHands 等端到端集成仍按客户端逐个验证。\n\n```txt\ncode_agent_plusplus_start_loop\ncode_agent_plusplus_step\ncode_agent_plusplus_evaluate\ncode_agent_plusplus_repair\ncode_agent_plusplus_finalize\n```\n\n实验性 runtime loop 工具包括：`start_loop` 生成任务运行目录和 trace，`step` 记录编辑\u002F测试\u002F验证动作，`evaluate` 汇总 delta、loop、policy、verify 信号，`repair` 产出修复动作，`finalize` 在测试和 contract 证据齐全后收口。\n\n## LLM 摘要配置\n\n默认离线可用；需要 LLM 摘要时，本地创建 `code-agent-plusplus.local.yml`：\n\n```yaml\nllm:\n  enabled: true\n  provider: openai-compatible\n  baseUrl: xx\n  apiKey: xx\n  model: xx\n```\n\n提交到仓库的配置只保留 `xx` 占位符。真实 key、URL、model 只放本地文件。\n\n```bash\ncode-agent-plusplus build . --llm\n```\n\n## 文档\n\n- [架构设计](docs\u002Farchitecture.md)\n- [Guard Modules](docs\u002Fguard-modules.zh-CN.md)\n- [Loop Engineering 源码链路](docs\u002Floop-engineering.zh-CN.md)\n- [AGENTS.md 使用说明](docs\u002Fagents-md.zh-CN.md)\n- [Roadmap](docs\u002Froadmap.md)\n- [Benchmark](benchmarks\u002FREADME.md)\n\n## 开发\n\n```bash\nnpm run check\nnpm run lint\nnpm run format:check\nnpm test\nnpm run benchmark\nnpm run build\nnpm run pack:dry-run\n```\n",2,"2026-06-15 02:30:12","CREATED_QUERY"]