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 — 无多余依赖。

里程碑

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