无人值守编程 zengfr/AutoCoding

UltraVibe v3 — 无人值守自动化编程工程化

Codex 会话主驱动 + TS 机械验证工具集。单会话自主推进 bugfix/feature/refactor/review 流程，零干预。

核心架构

Codex 会话(主驱动) → 读 SKILL.md → 执行 → 调工具验证 → 决策推进/重试/终止 ↓ TS 机械工具集(被调用方) run-tests / check-scope / validate-* / checkpoint

- Codex 是主驾：读指令、执行、调工具、决策，全在会话内完成
- TS 工具是仪表盘：机械验证 | 范围核验 | 引用真值，不控制流程
- 完成真值：run-tests 全绿 + check-scope 无蔓延 + validate-* 全 valid，绝不信任 LLM 自报

快速开始

安装依赖
npm install

跑通工具集
npm run check # tsc + vitest + eslint

实验:用沙箱跑一个 bugfix 流程
npx tsx src/index.ts run-tests --workdir experiments/bugfix-demo

工具命令

所有命令在项目根运行，--workdir 指向目标项目；输出 JSON 到 stdout，ok=true 为通过。

| 命令 | 用途 | 完成判定 |
| run-tests | vitest + tsc | passed 且无失败 |
| validate-spec | frozen-spec schema+scope | valid |
| validate-artifact | 通用产物 schema 校验 | valid |
| validate-citation | 引用真值(source_file:line 读真实代码) | valid |
| check-scope --spec | git diff + 白名单核验(非 git 返回 fatal) | 无未归属/受保护/禁止 |
| check-scope --whitelist a,b | 同上，手动指定白名单 | 同上 |
| check-static | 禁止模式扫描(@ts-ignore/eval/console.log) | 无 error 级 |
| snapshot --targets a,b | 记录基线(baseline.json) | ok |
| commit-check --message msg | 范围检查通过后 git add+commit | ok |
| checkpoint read / checkpoint write | 断点续跑读写 | ok |

流程

| 流程 | 阶段 | 说明 |
| bugfix | 5(BF-1→BF-2→BF-3→BF-4→BF-5) | 复现定位→修复验证→逆向验证→全局守卫→报告 |
| feature | 5(FE-1→FE-2→FE-3→FE-4→FE-5) | SpecLock→TDD实现→逆向验证→语义比对→全局守卫 |
| refactor | 4(RF-1→RF-2→RF-3→RF-4) | 基线快照→重构实施→全量回归→全局守卫 |
| review | 4(RV-1→RV-2→RV-3→RV-4) | 架构审查→缺陷扫描→安全合规→聚合报告(只读) |

无人值守护栏

| 风险 | 防护 | 工具 |
| LLM 幻觉(编造引用) | 真实文件读取+行号校验 | validate-citation |
| LLM 幻觉(自报完成) | 测试通过+diff全落白名单才是完成 | run-tests + check-scope |
| 范围蔓延(改不该改的) | git diff + 白名单机械核验 | check-scope |
| 无限循环 | 阶段迭代上限+全局时间上限 | SKILL.md 硬约束 |
| 上下文膨胀 | 阶段产物精简+checkpoint context_hints | checkpoint |
| 断点续跑 | checkpoint-summary 读写，spec_loaded 防重复冻结 | checkpoint |

产物契约

| 产物 | 阶段 | 位置 |
| frozen-spec.json | feature FE-1 | .reports/ |
| root-cause.json | bugfix BF-1 | .reports/ |
| baseline.json | refactor RF-1 | .reports/ |
| reverse-impl.json | bugfix BF-3 / feature FE-3 | .reports/ |
| guard-report.json | feature FE-5 | .reports/ |
| checkpoint-summary.json | 各阶段末 | .reports/ |

技术栈

TypeScript 5.5+，Node.js 20+，Vitest 2.0，Commander 12，Zod 3 — 无多余依赖。

里程碑

- [x] M0 骨架：git 底线 + CLI 工具集 + 24 测试
- [x] M1 bugfix 最小闭环：子代理零干预跑完 BF-1→BF-5
- [x] M2 断点续跑：checkpoint read/write + spec_loaded
- [x] M3 四大风险工具：validate-/check-/snapshot/commit-check
- [x] M4 流程 SKILL.md 全量重写
- [x] M5 无人值守演练：feature 沙箱实测 + bugfix 子代理实测
- [x] M6 收尾：架构文档+lessons+审批点