Auto_AICoding_Harness：给 AI Coding 套上一层“工程安全壳”-平芜编程栈

Auto_AICoding_Harness：给 AI Coding 套上一层“工程安全壳”

朋友们，最近新弄了一个 Harness 框架工具，有兴趣的朋友可以star 试试哦~
项目地址：https://github.com/yu20120707/Auto_AICoding_Harness

1. 项目一句话介绍

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-pack
`profile`	定义工程策略	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.py，review 生成在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 large

large 模式会增加更完整的运行时结构：

.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 上加更强的 gate：

spec 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:00+08:00"}

这个状态机有几个关键状态：

状态	含义
`INIT`	已初始化
`WAITING_HUMAN_SPEC_APPROVAL`	等待人工审核需求规格
`SPEC_APPROVED`	spec 已批准
`WAITING_HUMAN_PLAN_APPROVAL`	等待人工审核实现计划
`PLAN_APPROVED`	plan 已批准
`WAITING_HUMAN_DIFF_APPROVAL`	等待人工审核 diff
`DIFF_APPROVED`	diff 已批准
`WAITING_HUMAN_FINAL_APPROVAL`	等待最终验收
`DONE`	任务完成
`NEEDS_REPLAN`	需求或计划被打回
`NEEDS_FIX`	diff 被打回，需要修复
`NEEDS_MORE_TESTS`	最终验收缺少验证证据

状态机的价值不是“复杂”，而是把 AI 任务的每个关键转折点固定下来。否则复杂任务跑到一半，下一个会话只看到一堆改动，却不知道当前到底是“计划已批准但还没实现”，还是“实现已完成但还没测试”，还是“diff 已被打回”。

7. Review Gate：AI 生成材料，人做最终决策

这个项目的 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 文件已存在且无 --force：SKIPPED 文件已存在且有 --force：OVERWRITTEN，并备份旧文件

备份路径一般在：

.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.md

context-pack

context-pack是紧凑上下文包，适合“下一轮继续干”。它会总结：

当前 mode 当前 profile 当前 status 当前 gate 已批准 gate 关键文件是否存在 git status diff stat changed files 最近 review 最近 approval spec / plan / affected-files 摘要 verification 摘要 下一步建议

命令：

python3 bin/ai-context-pack

这个命令只生成上下文材料，不推进状态。

handoff

handoff更偏交接文档，适合“换一个 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、backpressure
Linux 调试	process、signal、fd、strace、core dump、perf
API/ABI	public 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-review

ai-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

这种分层能显著降低上下文污染。

亮点二：状态机足够小

状态机没有做成复杂工作流引擎，而是只控制关键 gate：

spec 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 还是 placeholder

ai_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 review

P2：让 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：接入真实项目 examples

examples 目前更像生成结构样例。后续可以提供几个真实任务样例：

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 的刹车、仪表盘、行车记录仪和交接单。