Auto_AICoding_Harness给 AI Coding 套上一层“工程安全壳”朋友们最近新弄了一个 Harness 框架工具有兴趣的朋友可以star 试试哦~项目地址https://github.com/yu20120707/Auto_AICoding_Harness1. 项目一句话介绍Auto_AICoding_Harness是一个面向 AI 编程场景的轻量级 Harness 仓库。它不直接参与业务代码运行也不是某个 C 项目的框架库而是用一组脚本、模板、规则文档和 profile把一个普通代码仓库接入到“可规划、可验证、可审核、可接力”的 AI Coding 流程中。更具体一点说它解决的是这样一个问题AI 直接改代码很快但如果没有任务边界、状态记录、人工审查、验证证据和交接材料复杂任务很容易变成不可复盘、不可控、不可继续的黑盒操作。这个仓库的作用就是给 AI Coding 加一层工程控制面用户需求 ↓ 任务分级 small / large ↓ 生成或读取目标项目中的 AGENTS.md、docs/ai、.ai ↓ AI 按文档和状态机执行 ↓ 生成 spec / plan / diff / final review ↓ 人工 approve / reject ↓ 记录 context-pack / handoff ↓ 下一个会话继续接力所以它本质上不是“让 AI 更聪明”的模型层项目而是“让 AI 更可控”的工程流程项目。2. 为什么需要这个项目直接让 AI 修改项目代码短任务通常问题不大比如修一个 typo、补一个小函数、改一处局部 bug。但当任务变复杂后问题会迅速暴露上下文会丢失AI 知道当前对话里的内容但下一轮会话可能忘记之前做了什么为什么这么做哪些地方不能动。修改范围容易膨胀原本只要改一个函数AI 可能顺手重构一堆文件造成不可控 diff。验证证据不稳定AI 很容易说“已验证”“应该没问题”但实际没有记录构建命令、测试命令、失败项和未验证项。人工审核缺少固定入口人想审代码时需要知道改了哪些文件风险在哪里是否影响 API/ABI有没有并发问题有没有性能影响是否真的跑了测试复杂任务难以接力一旦任务跨会话、跨 agent、跨子任务缺少handoff和context-pack就会导致后续 agent 重新读一遍仓库甚至重复犯错。Auto_AICoding_Harness的设计目标就是把这些“不稳定的人机协作行为”变成“文件化、状态化、可审计的工程流程”。3. 项目的核心定位这个仓库可以理解为三层结构层级作用典型内容core控制流程不关心具体语言状态机、安全写入、review gate、handoff、context-packprofile定义工程策略C / Linux / 后端 / 系统工程检查项templates生成目标项目文件AGENTS.md、docs/ai/*、.ai/*、脚本模板最重要的边界是core 管流程 profile 管工程规范 templates 管生成物 .ai 管任务运行时 docs/ai 管长期项目知识这个边界非常关键。因为如果把 CMake、ctest、clang-tidy 这类 C 项目策略硬编码进 core那么这个 harness 很快就会变成一个不可复用、难迁移的专用脚本堆。现在的设计是core 只负责“什么时候进入哪个状态、什么时候需要人工 gate、什么时候允许覆盖文件”具体工程判断交给 profile。4. 仓库结构拆解仓库大致可以拆成这些部分Auto_AICoding_Harness/ ├── bin/ # 用户直接调用的命令入口 ├── core/ # 命令背后的通用逻辑 ├── docs/ │ ├── design/ # 设计契约、状态机、边界文档 │ ├── usage/ # 使用说明和生成结构说明 │ └── release/ # release checklist ├── templates/ # base 模板源 ├── profiles/ │ └── cpp-linux-backend-system # C/Linux/后端/系统工程 profile ├── prompts/ # bootstrap/local agent prompt ├── scripts/ # 脚本说明不是 CLI 实现 ├── skills/ # 可安装到 Codex/global skills 的技能源 ├── examples/ # small/large 生成结果示例 └── tests/ # Python 回归测试这里有几个设计点值得注意。第一bin/是命令入口但真正的实现不应塞在命令文件里。命令入口只是解析参数、调用 core、打印结果。第二core/是这个项目的稳定内核。比如状态读写在state.py安全写入在safe_write.py模板物化在template.pyreview 生成在review.py审批 gate 在approval.py上下文打包和 handoff 在context.py。第三templates/是目标项目生成文件的唯一事实源。也就是说目标项目里生成出来的AGENTS.md、docs/ai/workflow.md、.github/copilot-instructions.md、scripts/ai_check.sh等文件不应该在仓库其他地方再维护一份副本否则会出现“模板 A 说一套文档 B 说一套”的漂移。第四profiles/cpp-linux-backend-system是当前首发 profile里面主要约束 C 系统工程问题例如生命周期、并发、网络、Linux 调试、性能、API/ABI、构建和测试。5. small 和 large不是两个系统而是两种控制强度这个项目把任务分为不同控制强度其中最核心的是small和large。small 模式small是轻量模式适合低风险、局部、容易回滚、容易验证的任务。典型命令python3 bin/ai-init small执行后目标项目会被写入基础 AI 协作结构例如target-repo/ ├── AGENTS.md ├── docs/ai/ │ ├── README.md │ └── workflow.md ├── scripts/ │ ├── ai_build.sh │ ├── ai_test.sh │ └── ai_check.sh └── .ai/ ├── state.json └── templates/small 模式强调的是先建立最小协作协议 再让 AI 在明确边界内工作 最后通过 diff review / final review 收口它不要求一开始就写完整 spec 和 plan适合简单修复、局部文档调整、小范围功能补丁。large 模式large是强控制模式适合复杂任务比如跨模块改动、架构调整、公共接口变更、构建系统变更、并发/网络/性能相关修改。典型命令python3 bin/ai-upgrade largelarge 模式会增加更完整的运行时结构.ai/ ├── spec.md ├── scope.md ├── implementation-plan.md ├── affected-files.md ├── run-trace.md ├── verification.md ├── evaluation.md ├── context-pack.md ├── handoff.md ├── reviews/ ├── approvals/ ├── backups/ └── subagent-packets/large 模式不是换了一套系统而是在同一个 workflow 上加更强的 gatespec gate ↓ plan gate ↓ diff gate ↓ final gate每个 gate 都可以被人工 approve 或 reject。这样可以避免 AI 一路自动冲到底把复杂任务做成不可控的黑盒。6. 状态机把 AI 任务变成可恢复的流程项目的核心状态文件是.ai/state.json它是目标项目的任务状态源。典型结构类似{schema_version:1,mode:large,profile:cpp-linux-backend-system,status:PLAN_APPROVED,current_gate:null,approved_gates:[spec,plan],created_by:Auto_AICoding_Harness,task_id:init-small,task_title:Initialize harness in small mode,updated_at:2026-06-08T12:00:0008:00}这个状态机有几个关键状态状态含义INIT已初始化WAITING_HUMAN_SPEC_APPROVAL等待人工审核需求规格SPEC_APPROVEDspec 已批准WAITING_HUMAN_PLAN_APPROVAL等待人工审核实现计划PLAN_APPROVEDplan 已批准WAITING_HUMAN_DIFF_APPROVAL等待人工审核 diffDIFF_APPROVEDdiff 已批准WAITING_HUMAN_FINAL_APPROVAL等待最终验收DONE任务完成NEEDS_REPLAN需求或计划被打回NEEDS_FIXdiff 被打回需要修复NEEDS_MORE_TESTS最终验收缺少验证证据状态机的价值不是“复杂”而是把 AI 任务的每个关键转折点固定下来。否则复杂任务跑到一半下一个会话只看到一堆改动却不知道当前到底是“计划已批准但还没实现”还是“实现已完成但还没测试”还是“diff 已被打回”。7. Review GateAI 生成材料人做最终决策这个项目的 review 设计很直接ai-review 生成审查材料 ai-approve / ai-reject 改变状态例如 diff 审查python3 bin/ai-reviewdiff这个命令会要求目标仓库必须是 git repo并且必须存在真实 working-tree diff。然后它会收集git status --short git diff --stat git diff --name-only git diff生成.ai/reviews/diff-review.md这个 review 文档不只是把 diff 贴出来还会带上检查清单例如Scope Check: - 只改了预期文件吗 - 有没有无关格式化 - 有没有误提交运行时文件 - 有没有未经批准的 public API 变更 - 有没有隐藏的大重构 C / System Risk Check: - ownership/lifetime 安全吗 - error handling 完整吗 - 有没有引入 data race - API/ABI 兼容性检查了吗 - timeout/retry 语义有没有变化 - 测试是否更新然后人工可以执行python3 bin/ai-approvediff或python3 bin/ai-rejectdiff这两个命令才会真正推进状态。这种设计的重点是AI 可以生成审查材料但不能替代人工 gate。8. 安全写入默认不覆盖覆盖必须备份Auto_AICoding_Harness的文件写入策略很保守文件不存在CREATED 文件已存在且无 --forceSKIPPED 文件已存在且有 --forceOVERWRITTEN并备份旧文件备份路径一般在.ai/backups/timestamp/这个策略解决了一个很现实的问题AI 工具经常会“初始化一下”就把已有配置覆盖掉。对于真实项目来说这非常危险因为AGENTS.md、.github/copilot-instructions.md、docs/ai/*可能已经被团队手动维护过。所以这个项目默认不覆盖已有文件。你必须显式传入python3 bin/ai-init small--force或python3 bin/ai-upgrade large--force才会覆盖并且覆盖前会备份。这就是工程里常见的“默认安全显式破坏性操作”的设计。另外safe_write.py还禁止写入一些业务源目录例如src、include、tests。这说明 harness 命令默认只应该管理 AI 协作文件而不是直接修改业务代码。9. context-pack 和 handoff解决长任务接力问题AI Coding 最大的问题之一是长上下文污染。一个任务跑久了以后对话里会混入大量历史讨论、失败尝试、过期假设和无关信息。继续在原上下文里做容易导致判断质量下降。这个项目用两个文件解决接力问题.ai/context-pack.md .ai/handoff.mdcontext-packcontext-pack是紧凑上下文包适合“下一轮继续干”。它会总结当前 mode 当前 profile 当前 status 当前 gate 已批准 gate 关键文件是否存在 git status diff stat changed files 最近 review 最近 approval spec / plan / affected-files 摘要 verification 摘要 下一步建议命令python3 bin/ai-context-pack这个命令只生成上下文材料不推进状态。handoffhandoff更偏交接文档适合“换一个 agent 或换一个干净会话继续”。它会记录当前状态 已经完成了什么 修改过哪些文件 验证和 review 证据在哪里 当前 blocker / gate 下一步动作 禁止做什么命令python3 bin/ai-handoff它也不推进状态。这两个命令的意义是把会话记忆从聊天窗口里抽出来落到项目文件里。10. C / Linux / 后端 / 系统工程 profile当前默认 profile 是cpp-linux-backend-system这个 profile 对目标项目生成一组docs/ai/*长期工程知识文档例如docs/ai/cpp-system.md docs/ai/linux-debug.md docs/ai/network.md docs/ai/concurrency.md docs/ai/api-abi.md docs/ai/performance.md docs/ai/observability.md docs/ai/cmake.md docs/ai/build.md docs/ai/testing.md docs/ai/verification-matrix.md这套 profile 的设计明显偏系统工程而不是普通 CRUD 后端。它关注的问题包括方向关注点C 对象模型ownership、lifetime、RAII、异常安全并发lock scope、data race、atomic、线程生命周期网络socket、epoll、timeout、retry、backpressureLinux 调试process、signal、fd、strace、core dump、perfAPI/ABIpublic header、协议兼容、二进制兼容性能profile 证据、热点路径、benchmark可观测性log、metric、diagnostic、failure evidence构建测试CMake、compile_commands、unit/integration/regression这对 C 后端/基础架构项目很重要。因为这类项目的风险通常不在“代码能不能编译”而在生命周期是否安全 并发路径是否竞态 网络异常是否覆盖 超时重试是否改变语义 ABI 是否破坏 性能是否退化 日志指标是否足够排障把这些检查项写进 profile本质上是在给 AI 添加“工程审查视角”。11. subagent目前是协议不是自动执行框架项目里有 large-mode subagent role templates例如.codex/agents/planner.md .codex/agents/explorer.md .codex/agents/implementer.md .codex/agents/reviewer.md .codex/agents/evaluator.md还有.ai/subagent-packets/角色大致分工是角色职责planner规划范围、步骤、gate 和验证策略explorer只读扫描代码和证据不编辑implementer按 scope 做实现reviewer审 diff、契约、回归风险evaluator验证命令、证据和残余风险但这里有一个重要边界subagent 不是 correctness dependency也不是自动调度系统。换句话说项目提供的是 role template 和 dispatch record不是一个真正的多 agent runtime。如果当前 AI 编程工具支持 subagent可以把 packet 作为上下文交给子 agent。如果不支持主 agent 就按同样的角色契约顺序执行。这其实是一个比较稳的设计。因为不同 AI Coding 工具对 subagent 的支持差异很大。如果项目强依赖某个平台的自动 subagent 调度迁移成本会非常高。而现在的做法是把 subagent 抽象成“可选加速层”。12. skills可安装但不能成为正确性依赖仓库还提供 skills 体系用来沉淀可复用方法论。例如methodology/design-before-code methodology/systematic-debugging methodology/verification-before-completion methodology/human-in-loop-development system/cpp-system-dev system/linux-debug system/network-programming system/concurrency-review system/performance-analysis system/cpp-api-abi-reviewai-install-skills可以把这些 skills 安装到 Codex 的全局 skills 目录python3 bin/ai-install-skills --dry-run python3 bin/ai-install-skills python3 bin/ai-install-skills--force它的默认目标大致是$CODEX_HOME/skills 或 ~/.codex/skills设计上也保留了安全策略dry-run 只预览不写入 默认存在则跳过 --force 才覆盖 覆盖前备份不过 skills 仍然不是正确性依赖。没有 skills 时AI 应该直接读AGENTS.md和docs/ai/*。skills 的角色是提升执行质量而不是让流程成立的必要条件。13. 典型使用流程一个完整 large-mode 任务可以这样走# 1. 查看状态python3 bin/ai-status# 2. 初始化目标项目python3 bin/ai-init small# 3. 升级到 large 模式python3 bin/ai-upgrade large# 4. 填写或修改 .ai/spec.mdpython3 bin/ai-review spec python3 bin/ai-approve spec# 5. 填写或修改 .ai/implementation-plan.mdpython3 bin/ai-review plan python3 bin/ai-approve plan# 6. 实际修改业务代码# ...# 7. 生成 diff reviewpython3 bin/ai-reviewdiffpython3 bin/ai-approvediff# 8. 生成上下文包和交接文档python3 bin/ai-context-pack python3 bin/ai-handoff# 9. 最终验收python3 bin/ai-review final python3 bin/ai-approve final# 10. 查看最终状态python3 bin/ai-status最后目标状态应该进入DONE并且.ai/state.json中应该能看到approved_gates:[spec,plan,diff,final]这就把一次 AI Coding 任务从“聊天式执行”变成了“有状态、有证据、有审查、有交接”的工程流程。14. 这个项目的工程亮点亮点一边界清晰它没有把所有东西混成一个大 prompt而是明确区分全局行为 项目行为 项目事实 任务运行时 复用方法 平台适配对应文件路径是global/AGENTS.md.template # 全局行为基线 AGENTS.md # 项目入口规则 docs/ai/* # 项目长期知识 .ai/* # 当前任务运行态 skills/* # 可复用技能 prompts/* # 一次性 setup prompt这种分层能显著降低上下文污染。亮点二状态机足够小状态机没有做成复杂工作流引擎而是只控制关键 gatespec plan diff final状态数量不多但覆盖了复杂任务最关键的风险点。这符合工程工具设计原则流程控制应该足够强但不能重到没人愿意用。亮点三默认安全写入默认SKIPPED显式--force才覆盖而且覆盖前备份。这对真实项目很重要尤其是.github、AGENTS.md、docs/ai这类容易被人手动维护的文件。亮点四适合 C 系统方向默认 profile 不是泛泛的“代码质量检查”而是围绕 C / Linux / 后端 / 系统工程展开。这让它比普通 AI Coding prompt 更接近真实基础架构开发场景。亮点五可接力context-pack和handoff解决的是长任务续跑问题。这点在 AI Coding 里非常关键因为真实复杂任务经常不是一轮对话能做完的。15. 当前不足和风险这个项目当前也有明显不足。1. 文档和实现有漂移风险部分文档中提到的命令面、版本 baseline、release phase 并不完全一致。例如 README 中强调 phase10而 release/checklist 和部分测试又出现更靠后的能力描述。这说明项目处于快速演进阶段需要一个更严格的能力清单生成机制。建议后续把命令清单变成机器生成例如bin/* 自动扫描 ↓ 生成 docs/design/current-capabilities.md ↓ 测试校验 README 是否同步2. 目前还不是完整 AI Agent Runtime它不负责真正调用模型也不负责执行 subagent。它更像是 workflow harness而不是 agent framework。这不是缺点但对外介绍时要讲清楚否则别人可能误以为它是类似 Devin/Codex CLI 的自动编程执行器。3. scripts 还是 placeholderai_build.sh、ai_test.sh、ai_check.sh当前是安全占位模板需要目标项目自己替换。这意味着它能建立流程但不能自动理解每个项目的真实构建链路。4. profile 目前单一当前默认 profile 是cpp-linux-backend-system。如果要扩展到 Java 后端、前端、数据工程、嵌入式、Android、Rust 系统开发就需要新增 profile overlay。5..ai的 git 策略需要更细.ai/state.json、reviews、approvals、backups 大多属于运行时不一定应该提交。但.ai/templates、.ai/.gitkeep又可能需要保留。对真实团队使用来说最好生成一份更精细的.gitignore建议。16. 可以怎么继续升级如果继续迭代我认为优先级可以这样排P0统一版本和命令面把 README、current-capabilities、release checklist、tests 中的命令面彻底对齐。当前最重要的是避免使用者看到不同文档得出不同结论。P1补一个ai doctor增加python3 bin/ai-doctor检查目标项目是否满足 harness 运行条件是否 git repo 是否存在 .ai/state.json AGENTS.md 是否存在 docs/ai 是否存在 scripts/ai_check.sh 是否已替换 placeholder 当前 state 是否和文件结构一致 是否存在未批准 gate 是否存在 stale reviewP2让 verification 更结构化当前.ai/verification.md是 markdown 证据。可以进一步增加.ai/verification.json让机器能可靠读取{commands:[{cmd:cmake --build build,exit_code:0,duration_ms:12345,log:.ai/logs/build.log}],not_run:[{item:benchmark,reason:no benchmark target}]}这样 final gate 就能更严格地判断“是否真的验证过”。P3增加 profile marketplace 但不急可以新增profiles/java-backend profiles/rust-system profiles/android-aosp profiles/python-agent但不建议太早做成 marketplace。当前项目的最大价值是自用稳定流程而不是泛化成大而全平台。P4接入真实项目 examplesexamples 目前更像生成结构样例。后续可以提供几个真实任务样例example-task-fix-build/ example-task-refactor-api/ example-task-performance-regression/ example-task-network-timeout-bug/每个样例包含spec plan diff-review approval verification handoff这比单纯文档更能说明 harness 的价值。17. 总结Auto_AICoding_Harness的核心价值不是“自动写代码”而是“把 AI 写代码这件事变成可控工程流程”。它用很轻的 Python 命令和 markdown 模板建立了几条关键约束任务要分级 上下文要落盘 长期知识和运行态要分离 复杂任务要有 spec / plan / diff / final gate 人工审批不能被 AI 绕过 验证必须有证据 handoff 必须可接力 覆盖文件必须显式且可回滚如果用一句工程化的话概括这个项目不是 AI Coding 的发动机而是 AI Coding 的刹车、仪表盘、行车记录仪和交接单。
Auto_AICoding_Harness：给 AI Coding 套上一层“工程安全壳”
发布时间：2026/6/12 7:31:26
Auto_AICoding_Harness给 AI Coding 套上一层“工程安全壳”朋友们最近新弄了一个 Harness 框架工具有兴趣的朋友可以star 试试哦~项目地址https://github.com/yu20120707/Auto_AICoding_Harness1. 项目一句话介绍Auto_AICoding_Harness是一个面向 AI 编程场景的轻量级 Harness 仓库。它不直接参与业务代码运行也不是某个 C 项目的框架库而是用一组脚本、模板、规则文档和 profile把一个普通代码仓库接入到“可规划、可验证、可审核、可接力”的 AI Coding 流程中。更具体一点说它解决的是这样一个问题AI 直接改代码很快但如果没有任务边界、状态记录、人工审查、验证证据和交接材料复杂任务很容易变成不可复盘、不可控、不可继续的黑盒操作。这个仓库的作用就是给 AI Coding 加一层工程控制面用户需求 ↓ 任务分级 small / large ↓ 生成或读取目标项目中的 AGENTS.md、docs/ai、.ai ↓ AI 按文档和状态机执行 ↓ 生成 spec / plan / diff / final review ↓ 人工 approve / reject ↓ 记录 context-pack / handoff ↓ 下一个会话继续接力所以它本质上不是“让 AI 更聪明”的模型层项目而是“让 AI 更可控”的工程流程项目。2. 为什么需要这个项目直接让 AI 修改项目代码短任务通常问题不大比如修一个 typo、补一个小函数、改一处局部 bug。但当任务变复杂后问题会迅速暴露上下文会丢失AI 知道当前对话里的内容但下一轮会话可能忘记之前做了什么为什么这么做哪些地方不能动。修改范围容易膨胀原本只要改一个函数AI 可能顺手重构一堆文件造成不可控 diff。验证证据不稳定AI 很容易说“已验证”“应该没问题”但实际没有记录构建命令、测试命令、失败项和未验证项。人工审核缺少固定入口人想审代码时需要知道改了哪些文件风险在哪里是否影响 API/ABI有没有并发问题有没有性能影响是否真的跑了测试复杂任务难以接力一旦任务跨会话、跨 agent、跨子任务缺少handoff和context-pack就会导致后续 agent 重新读一遍仓库甚至重复犯错。Auto_AICoding_Harness的设计目标就是把这些“不稳定的人机协作行为”变成“文件化、状态化、可审计的工程流程”。3. 项目的核心定位这个仓库可以理解为三层结构层级作用典型内容core控制流程不关心具体语言状态机、安全写入、review gate、handoff、context-packprofile定义工程策略C / Linux / 后端 / 系统工程检查项templates生成目标项目文件AGENTS.md、docs/ai/*、.ai/*、脚本模板最重要的边界是core 管流程 profile 管工程规范 templates 管生成物 .ai 管任务运行时 docs/ai 管长期项目知识这个边界非常关键。因为如果把 CMake、ctest、clang-tidy 这类 C 项目策略硬编码进 core那么这个 harness 很快就会变成一个不可复用、难迁移的专用脚本堆。现在的设计是core 只负责“什么时候进入哪个状态、什么时候需要人工 gate、什么时候允许覆盖文件”具体工程判断交给 profile。4. 仓库结构拆解仓库大致可以拆成这些部分Auto_AICoding_Harness/ ├── bin/ # 用户直接调用的命令入口 ├── core/ # 命令背后的通用逻辑 ├── docs/ │ ├── design/ # 设计契约、状态机、边界文档 │ ├── usage/ # 使用说明和生成结构说明 │ └── release/ # release checklist ├── templates/ # base 模板源 ├── profiles/ │ └── cpp-linux-backend-system # C/Linux/后端/系统工程 profile ├── prompts/ # bootstrap/local agent prompt ├── scripts/ # 脚本说明不是 CLI 实现 ├── skills/ # 可安装到 Codex/global skills 的技能源 ├── examples/ # small/large 生成结果示例 └── tests/ # Python 回归测试这里有几个设计点值得注意。第一bin/是命令入口但真正的实现不应塞在命令文件里。命令入口只是解析参数、调用 core、打印结果。第二core/是这个项目的稳定内核。比如状态读写在state.py安全写入在safe_write.py模板物化在template.pyreview 生成在review.py审批 gate 在approval.py上下文打包和 handoff 在context.py。第三templates/是目标项目生成文件的唯一事实源。也就是说目标项目里生成出来的AGENTS.md、docs/ai/workflow.md、.github/copilot-instructions.md、scripts/ai_check.sh等文件不应该在仓库其他地方再维护一份副本否则会出现“模板 A 说一套文档 B 说一套”的漂移。第四profiles/cpp-linux-backend-system是当前首发 profile里面主要约束 C 系统工程问题例如生命周期、并发、网络、Linux 调试、性能、API/ABI、构建和测试。5. small 和 large不是两个系统而是两种控制强度这个项目把任务分为不同控制强度其中最核心的是small和large。small 模式small是轻量模式适合低风险、局部、容易回滚、容易验证的任务。典型命令python3 bin/ai-init small执行后目标项目会被写入基础 AI 协作结构例如target-repo/ ├── AGENTS.md ├── docs/ai/ │ ├── README.md │ └── workflow.md ├── scripts/ │ ├── ai_build.sh │ ├── ai_test.sh │ └── ai_check.sh └── .ai/ ├── state.json └── templates/small 模式强调的是先建立最小协作协议 再让 AI 在明确边界内工作 最后通过 diff review / final review 收口它不要求一开始就写完整 spec 和 plan适合简单修复、局部文档调整、小范围功能补丁。large 模式large是强控制模式适合复杂任务比如跨模块改动、架构调整、公共接口变更、构建系统变更、并发/网络/性能相关修改。典型命令python3 bin/ai-upgrade largelarge 模式会增加更完整的运行时结构.ai/ ├── spec.md ├── scope.md ├── implementation-plan.md ├── affected-files.md ├── run-trace.md ├── verification.md ├── evaluation.md ├── context-pack.md ├── handoff.md ├── reviews/ ├── approvals/ ├── backups/ └── subagent-packets/large 模式不是换了一套系统而是在同一个 workflow 上加更强的 gatespec gate ↓ plan gate ↓ diff gate ↓ final gate每个 gate 都可以被人工 approve 或 reject。这样可以避免 AI 一路自动冲到底把复杂任务做成不可控的黑盒。6. 状态机把 AI 任务变成可恢复的流程项目的核心状态文件是.ai/state.json它是目标项目的任务状态源。典型结构类似{schema_version:1,mode:large,profile:cpp-linux-backend-system,status:PLAN_APPROVED,current_gate:null,approved_gates:[spec,plan],created_by:Auto_AICoding_Harness,task_id:init-small,task_title:Initialize harness in small mode,updated_at:2026-06-08T12:00:0008:00}这个状态机有几个关键状态状态含义INIT已初始化WAITING_HUMAN_SPEC_APPROVAL等待人工审核需求规格SPEC_APPROVEDspec 已批准WAITING_HUMAN_PLAN_APPROVAL等待人工审核实现计划PLAN_APPROVEDplan 已批准WAITING_HUMAN_DIFF_APPROVAL等待人工审核 diffDIFF_APPROVEDdiff 已批准WAITING_HUMAN_FINAL_APPROVAL等待最终验收DONE任务完成NEEDS_REPLAN需求或计划被打回NEEDS_FIXdiff 被打回需要修复NEEDS_MORE_TESTS最终验收缺少验证证据状态机的价值不是“复杂”而是把 AI 任务的每个关键转折点固定下来。否则复杂任务跑到一半下一个会话只看到一堆改动却不知道当前到底是“计划已批准但还没实现”还是“实现已完成但还没测试”还是“diff 已被打回”。7. Review GateAI 生成材料人做最终决策这个项目的 review 设计很直接ai-review 生成审查材料 ai-approve / ai-reject 改变状态例如 diff 审查python3 bin/ai-reviewdiff这个命令会要求目标仓库必须是 git repo并且必须存在真实 working-tree diff。然后它会收集git status --short git diff --stat git diff --name-only git diff生成.ai/reviews/diff-review.md这个 review 文档不只是把 diff 贴出来还会带上检查清单例如Scope Check: - 只改了预期文件吗 - 有没有无关格式化 - 有没有误提交运行时文件 - 有没有未经批准的 public API 变更 - 有没有隐藏的大重构 C / System Risk Check: - ownership/lifetime 安全吗 - error handling 完整吗 - 有没有引入 data race - API/ABI 兼容性检查了吗 - timeout/retry 语义有没有变化 - 测试是否更新然后人工可以执行python3 bin/ai-approvediff或python3 bin/ai-rejectdiff这两个命令才会真正推进状态。这种设计的重点是AI 可以生成审查材料但不能替代人工 gate。8. 安全写入默认不覆盖覆盖必须备份Auto_AICoding_Harness的文件写入策略很保守文件不存在CREATED 文件已存在且无 --forceSKIPPED 文件已存在且有 --forceOVERWRITTEN并备份旧文件备份路径一般在.ai/backups/timestamp/这个策略解决了一个很现实的问题AI 工具经常会“初始化一下”就把已有配置覆盖掉。对于真实项目来说这非常危险因为AGENTS.md、.github/copilot-instructions.md、docs/ai/*可能已经被团队手动维护过。所以这个项目默认不覆盖已有文件。你必须显式传入python3 bin/ai-init small--force或python3 bin/ai-upgrade large--force才会覆盖并且覆盖前会备份。这就是工程里常见的“默认安全显式破坏性操作”的设计。另外safe_write.py还禁止写入一些业务源目录例如src、include、tests。这说明 harness 命令默认只应该管理 AI 协作文件而不是直接修改业务代码。9. context-pack 和 handoff解决长任务接力问题AI Coding 最大的问题之一是长上下文污染。一个任务跑久了以后对话里会混入大量历史讨论、失败尝试、过期假设和无关信息。继续在原上下文里做容易导致判断质量下降。这个项目用两个文件解决接力问题.ai/context-pack.md .ai/handoff.mdcontext-packcontext-pack是紧凑上下文包适合“下一轮继续干”。它会总结当前 mode 当前 profile 当前 status 当前 gate 已批准 gate 关键文件是否存在 git status diff stat changed files 最近 review 最近 approval spec / plan / affected-files 摘要 verification 摘要 下一步建议命令python3 bin/ai-context-pack这个命令只生成上下文材料不推进状态。handoffhandoff更偏交接文档适合“换一个 agent 或换一个干净会话继续”。它会记录当前状态 已经完成了什么 修改过哪些文件 验证和 review 证据在哪里 当前 blocker / gate 下一步动作 禁止做什么命令python3 bin/ai-handoff它也不推进状态。这两个命令的意义是把会话记忆从聊天窗口里抽出来落到项目文件里。10. C / Linux / 后端 / 系统工程 profile当前默认 profile 是cpp-linux-backend-system这个 profile 对目标项目生成一组docs/ai/*长期工程知识文档例如docs/ai/cpp-system.md docs/ai/linux-debug.md docs/ai/network.md docs/ai/concurrency.md docs/ai/api-abi.md docs/ai/performance.md docs/ai/observability.md docs/ai/cmake.md docs/ai/build.md docs/ai/testing.md docs/ai/verification-matrix.md这套 profile 的设计明显偏系统工程而不是普通 CRUD 后端。它关注的问题包括方向关注点C 对象模型ownership、lifetime、RAII、异常安全并发lock scope、data race、atomic、线程生命周期网络socket、epoll、timeout、retry、backpressureLinux 调试process、signal、fd、strace、core dump、perfAPI/ABIpublic header、协议兼容、二进制兼容性能profile 证据、热点路径、benchmark可观测性log、metric、diagnostic、failure evidence构建测试CMake、compile_commands、unit/integration/regression这对 C 后端/基础架构项目很重要。因为这类项目的风险通常不在“代码能不能编译”而在生命周期是否安全 并发路径是否竞态 网络异常是否覆盖 超时重试是否改变语义 ABI 是否破坏 性能是否退化 日志指标是否足够排障把这些检查项写进 profile本质上是在给 AI 添加“工程审查视角”。11. subagent目前是协议不是自动执行框架项目里有 large-mode subagent role templates例如.codex/agents/planner.md .codex/agents/explorer.md .codex/agents/implementer.md .codex/agents/reviewer.md .codex/agents/evaluator.md还有.ai/subagent-packets/角色大致分工是角色职责planner规划范围、步骤、gate 和验证策略explorer只读扫描代码和证据不编辑implementer按 scope 做实现reviewer审 diff、契约、回归风险evaluator验证命令、证据和残余风险但这里有一个重要边界subagent 不是 correctness dependency也不是自动调度系统。换句话说项目提供的是 role template 和 dispatch record不是一个真正的多 agent runtime。如果当前 AI 编程工具支持 subagent可以把 packet 作为上下文交给子 agent。如果不支持主 agent 就按同样的角色契约顺序执行。这其实是一个比较稳的设计。因为不同 AI Coding 工具对 subagent 的支持差异很大。如果项目强依赖某个平台的自动 subagent 调度迁移成本会非常高。而现在的做法是把 subagent 抽象成“可选加速层”。12. skills可安装但不能成为正确性依赖仓库还提供 skills 体系用来沉淀可复用方法论。例如methodology/design-before-code methodology/systematic-debugging methodology/verification-before-completion methodology/human-in-loop-development system/cpp-system-dev system/linux-debug system/network-programming system/concurrency-review system/performance-analysis system/cpp-api-abi-reviewai-install-skills可以把这些 skills 安装到 Codex 的全局 skills 目录python3 bin/ai-install-skills --dry-run python3 bin/ai-install-skills python3 bin/ai-install-skills--force它的默认目标大致是$CODEX_HOME/skills 或 ~/.codex/skills设计上也保留了安全策略dry-run 只预览不写入 默认存在则跳过 --force 才覆盖 覆盖前备份不过 skills 仍然不是正确性依赖。没有 skills 时AI 应该直接读AGENTS.md和docs/ai/*。skills 的角色是提升执行质量而不是让流程成立的必要条件。13. 典型使用流程一个完整 large-mode 任务可以这样走# 1. 查看状态python3 bin/ai-status# 2. 初始化目标项目python3 bin/ai-init small# 3. 升级到 large 模式python3 bin/ai-upgrade large# 4. 填写或修改 .ai/spec.mdpython3 bin/ai-review spec python3 bin/ai-approve spec# 5. 填写或修改 .ai/implementation-plan.mdpython3 bin/ai-review plan python3 bin/ai-approve plan# 6. 实际修改业务代码# ...# 7. 生成 diff reviewpython3 bin/ai-reviewdiffpython3 bin/ai-approvediff# 8. 生成上下文包和交接文档python3 bin/ai-context-pack python3 bin/ai-handoff# 9. 最终验收python3 bin/ai-review final python3 bin/ai-approve final# 10. 查看最终状态python3 bin/ai-status最后目标状态应该进入DONE并且.ai/state.json中应该能看到approved_gates:[spec,plan,diff,final]这就把一次 AI Coding 任务从“聊天式执行”变成了“有状态、有证据、有审查、有交接”的工程流程。14. 这个项目的工程亮点亮点一边界清晰它没有把所有东西混成一个大 prompt而是明确区分全局行为 项目行为 项目事实 任务运行时 复用方法 平台适配对应文件路径是global/AGENTS.md.template # 全局行为基线 AGENTS.md # 项目入口规则 docs/ai/* # 项目长期知识 .ai/* # 当前任务运行态 skills/* # 可复用技能 prompts/* # 一次性 setup prompt这种分层能显著降低上下文污染。亮点二状态机足够小状态机没有做成复杂工作流引擎而是只控制关键 gatespec plan diff final状态数量不多但覆盖了复杂任务最关键的风险点。这符合工程工具设计原则流程控制应该足够强但不能重到没人愿意用。亮点三默认安全写入默认SKIPPED显式--force才覆盖而且覆盖前备份。这对真实项目很重要尤其是.github、AGENTS.md、docs/ai这类容易被人手动维护的文件。亮点四适合 C 系统方向默认 profile 不是泛泛的“代码质量检查”而是围绕 C / Linux / 后端 / 系统工程展开。这让它比普通 AI Coding prompt 更接近真实基础架构开发场景。亮点五可接力context-pack和handoff解决的是长任务续跑问题。这点在 AI Coding 里非常关键因为真实复杂任务经常不是一轮对话能做完的。15. 当前不足和风险这个项目当前也有明显不足。1. 文档和实现有漂移风险部分文档中提到的命令面、版本 baseline、release phase 并不完全一致。例如 README 中强调 phase10而 release/checklist 和部分测试又出现更靠后的能力描述。这说明项目处于快速演进阶段需要一个更严格的能力清单生成机制。建议后续把命令清单变成机器生成例如bin/* 自动扫描 ↓ 生成 docs/design/current-capabilities.md ↓ 测试校验 README 是否同步2. 目前还不是完整 AI Agent Runtime它不负责真正调用模型也不负责执行 subagent。它更像是 workflow harness而不是 agent framework。这不是缺点但对外介绍时要讲清楚否则别人可能误以为它是类似 Devin/Codex CLI 的自动编程执行器。3. scripts 还是 placeholderai_build.sh、ai_test.sh、ai_check.sh当前是安全占位模板需要目标项目自己替换。这意味着它能建立流程但不能自动理解每个项目的真实构建链路。4. profile 目前单一当前默认 profile 是cpp-linux-backend-system。如果要扩展到 Java 后端、前端、数据工程、嵌入式、Android、Rust 系统开发就需要新增 profile overlay。5..ai的 git 策略需要更细.ai/state.json、reviews、approvals、backups 大多属于运行时不一定应该提交。但.ai/templates、.ai/.gitkeep又可能需要保留。对真实团队使用来说最好生成一份更精细的.gitignore建议。16. 可以怎么继续升级如果继续迭代我认为优先级可以这样排P0统一版本和命令面把 README、current-capabilities、release checklist、tests 中的命令面彻底对齐。当前最重要的是避免使用者看到不同文档得出不同结论。P1补一个ai doctor增加python3 bin/ai-doctor检查目标项目是否满足 harness 运行条件是否 git repo 是否存在 .ai/state.json AGENTS.md 是否存在 docs/ai 是否存在 scripts/ai_check.sh 是否已替换 placeholder 当前 state 是否和文件结构一致 是否存在未批准 gate 是否存在 stale reviewP2让 verification 更结构化当前.ai/verification.md是 markdown 证据。可以进一步增加.ai/verification.json让机器能可靠读取{commands:[{cmd:cmake --build build,exit_code:0,duration_ms:12345,log:.ai/logs/build.log}],not_run:[{item:benchmark,reason:no benchmark target}]}这样 final gate 就能更严格地判断“是否真的验证过”。P3增加 profile marketplace 但不急可以新增profiles/java-backend profiles/rust-system profiles/android-aosp profiles/python-agent但不建议太早做成 marketplace。当前项目的最大价值是自用稳定流程而不是泛化成大而全平台。P4接入真实项目 examplesexamples 目前更像生成结构样例。后续可以提供几个真实任务样例example-task-fix-build/ example-task-refactor-api/ example-task-performance-regression/ example-task-network-timeout-bug/每个样例包含spec plan diff-review approval verification handoff这比单纯文档更能说明 harness 的价值。17. 总结Auto_AICoding_Harness的核心价值不是“自动写代码”而是“把 AI 写代码这件事变成可控工程流程”。它用很轻的 Python 命令和 markdown 模板建立了几条关键约束任务要分级 上下文要落盘 长期知识和运行态要分离 复杂任务要有 spec / plan / diff / final gate 人工审批不能被 AI 绕过 验证必须有证据 handoff 必须可接力 覆盖文件必须显式且可回滚如果用一句工程化的话概括这个项目不是 AI Coding 的发动机而是 AI Coding 的刹车、仪表盘、行车记录仪和交接单。
