关键词：多智能体协作、RLCR 迭代审查（Ralph-Loop with Codex Review）、AI 编程治理、Claude 插件、代码质量闭环

?

Humanize 是 UCLA 的刘思皓博士发起和维护的一个 Harness框架。

一言以蔽之：Humanize 帮助开发者生成可量化、可验证的设计目标，然后让一个 code agent 写代码，然后一个 review agent 负责批判，多轮迭代直至完成所有目标且 review agent 没有分析出潜在 bug。

鉴于该项目在 github 上是较为优秀的harness 框架, 已经有 shinezyy, Lyken17, zevorn  等知名开源社区成员参与贡献,短时间收获 700+star。

开芯院与IEEE CS TFDC 联合举办的活动上，该工作组执委会秘书长谢志勇出席活动并发言。张宇鑫、徐岩作相关技术分享，现场超150人参与讨论。

本文将基于 Humanzie 的框架,以香山在长程任务上的探索举例，分享实践经验。

<<< 左右滑动见更多 >>>

摘要

一 、 写在文前: 为什么 Vibe Coding 到了复杂任务会失效?

Vibe Coding 在小任务上非常高效。比如:写一个脚本、解释一段代码、补一个简单函数，开发者可以用自然语言描述需求，AI 很快给出结果。但是，问题在于，一旦任务变成长周期、多模块、多阶段、需要测试验证的工程项目，这种“边聊边改”的模式很快会遇到上限。

1.1 Context Window 不是无限工作记忆

长上下文给了模型更多输入空间，但不等于模型能稳定利用全部信息。随着对话变长、文件变多、历史决策增加，关键约束可能被埋在上下文中间。PPT 中提到的 “Lost in the Middle” 现象可以概括为：模型往往更关注上下文开头和结尾，对中间信息更容易忽略。

在工程任务中，这会带来几个直接后果： 早期确定的边界条件在后续实现中被忘掉。 已经修复的问题在新一轮修改中被重新引入。模型记得“当前正在做什么”，但忘了“为什么这么做”。对话里出现太多日志、代码和解释后，真正的验收标准被稀释。

所以，复杂任务需要的不只是更大的上下文，而是外部记忆：把目标、计划、摘要、审查结果和经验教训持久化到文件，让下一轮执行可以重新读取关键状态。

1.2 人工干预成为主要瓶颈

传统 AI 编程流程中，人要频繁承担调度员角色：告诉模型下一步做什么、检查是否偏题、发现工具失败、判断结果是否可接受。常见中断场景包括：

1. 权限、网络、依赖安装或命令执行失败。

2. 模型陷入无效方向，消耗 token 但没有推进主线。

3. 代码写完后没有自动跑测试，也没有质量审查。

一个阶段结束后等待用户继续发指令。模型为了修一个 bug 改动过大，引入新的风险。这意味着，AI 能写代码并不等于 AI 能完成工程任务。真正的瓶颈从“生成能力”转移到了“流程闭环能力”。

1.3 开环控制无法保证收敛

普通 Prompt → Code 的模式本质上是开环控制：人给需求，模型给结果。结果是否正确，依赖人来检查；如果不正确，人再补充 Prompt。复杂项目需要的是闭环控制：每轮输出都被验证和审查，发现问题后自动回流到下一轮，直到验收条件满足。

Humanize 的设计正是把 AI 编程从开环控制变成闭环控制。它不假设 AI 第一次就做对，而是把“做错后如何发现、如何修正、如何证明已经完成”变成系统能力。

二 、Humanize 是什么

Humanize 的一句话定义可以是：Humanize 是一套让 AI 根据结构化计划自主实现、接受独立审查、持续修复并最终满足验收标准的工程闭环框架。

它的关键不是“换一个更强模型”，而是在模型外部增加一整套工程 Harness：计划生成、计划精炼、Hook 生命周期、文件记忆、独立审查、质量门禁、进度监控和子代理并行。

2.1 四个核心理念

Humanize 的理念可以归纳为四点：

1. Iteration over Perfection：不要期待单次输出完美，而是通过多轮反馈逐步收敛。

2. One Build + One Review：一个模型负责实现，另一个模型独立审查，减少同质化盲区。

3. Begin with the End in Mind：人类仍然是架构师，必须先理解计划、目标和验收标准。

4. Ralph Loop with Swarm Mode：在闭环基础上支持 SubAgent / Agent Teams 并行推进复杂任务。

三 、Harness 与 Skill：模型之外的工程基础设施

Harness 是模型之外的全部基础设施，包括运行环境、工具链、记忆系统与反馈机制。模型负责推理和生成，但 Harness 决定模型能不能在真实工程现场长期稳定地工作。

3.1 Harness 包含什么

一个完整的 Agentic Coding Harness 至少包含以下部分：

• 工具接入：让模型可以读写文件、执行命令、访问测试和日志。

• 上下文管理：控制哪些信息进入当前上下文，哪些信息放到外部文件。

• Skill 机制：把复杂流程封装成可复用能力，比如生成计划、启动循环、调用审查。

• Hook 机制：在生命周期关键点拦截，例如写文件前、执行命令后、退出前。

• 记忆系统：用 Markdown、状态文件、日志或向量库保存长期信息。

• 验证系统：运行单测、集成测试、静态检查和代码审查。

• 任务分发：通过 SubAgent 把独立子任务并行执行。

Humanize 的源码结构能看到这些组件的对应关系：commands/ 定义用户入口；skills/ 提供 Codex/Kimi 可用的 Skill；scripts/ 负责循环、安装、监控和模型调用；hooks/ 负责生命周期门禁；templates/ 和 prompt-template/ 负责稳定输出格式。

3.2 Skill 为什么比“大 Prompt”更适合复杂工作流

把所有规则写进一个超长 Prompt 看似简单，但很快会遇到两个问题：上下文浪费和规则漂移。Skill 的优势是渐进式加载：只有当用户调用某个能力时，才加载对应的 SKILL.md、脚本和模板。这样既节省 Context，又能让每个 Skill 聚焦一件事。

Humanize 中几个核心 Skill 的分工大致如下：

• humanize-gen-plan：从粗略 draft 生成结构化计划。

• humanize-refine-plan：处理计划批注，生成干净计划和 QA ledger。

• humanize-rlcr：启动 RLCR 循环，根据计划执行并接受审查。

• humanize：提供通用工作流说明、脚本和运行时依赖。

这种分工让 Humanize 既能被 Claude Code 插件使用，也能安装到 Codex Skills 目录中，成为 Codex CLI 的本地能力。

四 、Humanize 的端到端工作流

Humanize 的完整工作流可以分成三个阶段：计划、执行、观察。

4.1 计划阶段：从想法到可执行 plan

复杂任务不能直接交给 Agent “自由发挥”。Humanize 推荐先把想法写成 draft.md，再通过 gen-plan 生成结构化计划。一个好计划通常包括：

• Goal Description：任务最终要达成什么。

• Acceptance Criteria：AC-X 验收标准。

• Positive Tests：应该通过的正例。

• Negative Tests：应该失败或被拒绝的反例。

• Path Boundaries：上界、下界、允许选择和禁止选择。

• Dependencies and Sequence：里程碑、依赖关系、执行顺序。

• Implementation Notes：实现提示和注意事项。

这一步的意义不是写文档本身，而是把“模糊愿望”变成“可执行合同”。RLCR 会忠实执行这个合同,如果计划错了，循环会把错误放大。因此计划质量直接决定自动执行质量。

4.2 refine-plan：把批注变成可执行变更

在真实团队中，计划往往需要评审。Humanize 支持在计划里写批注，例如 CMT: / ENDCMT、<cmt> / </cmt>、<comment> / </comment> 等格式。refine-plan 会读取这些批注等格式。refine-plan 会读取这些批注，将它们分类为问题回答、变更请求、研究请求或待决事项，并生成 QA ledger。

这个设计很工程化：它不只是“根据评论改一下”，而是把每条评论的处理状态记录下来。这样后续执行时，团队可以追踪哪些意见已采纳、哪些被延后、哪些需要用户进一步决策。

4.3 Plan Compliance Pre-Check：防止一开始就跑偏

start-rlcr-loop 启动前会做计划合规检查。根据命令文档，它会尝试判断：

• 计划文件是否与当前仓库相关。

• 计划里是否包含不兼容的切分支指令。

• 计划路径是否安全。

• 计划内容是否能被读取和解析。

这个检查看起来简单，但很关键。长循环最怕启动时方向就是错的。Humanize 通过前置检查尽早失败，避免 40 轮循环后才发现 plan 与仓库无关。

4.4 Plan Understanding Quiz：防止 wishful coding

Humanize 文档里把一种失败模式称为 “wishful coding”：把 AI 生成的计划当作愿望清单，自己没读懂就启动自动执行，然后希望它最好能成功。这在长周期任务中非常危险，因为 RLCR 是放大器：正确计划会放大执行效率，错误计划会放大错误。

因此 Humanize 在启动前会生成两个关于计划技术细节的选择题，让用户确认自己理解计划。这个 Quiz 默认是 advisory check，不是为了考试，而是提醒人类：你仍然是架构师，不能把架构判断完全外包给模型。

4.5 执行阶段：Implementation Phase

RLCR 的第一阶段是 Implementation Phase。执行 Agent 会根据 plan.md 修改代码、添加测试、运行验证，并在认为整个计划已经完成时写 round-N-summary.md。

这里有一个容易误解的点：Humanize 中的 round 不是一个任务、一个 milestone 或一次小修改，而是“Agent 认为全部计划已经完成”的边界。也就是说，如果计划包含多个阶段，Agent 应该在同一 round 中尽力全部完成，然后再写 summary 退出。中间如果需要询问 Codex，可以用 ask-codex 做一次性咨询，而不是把每个阶段都当作 round 边界。

round-N-summary.md 通常需要说明：

• 本轮完成了哪些实现。

• 修改了哪些文件。

• 新增或运行了哪些测试。

• 哪些验收标准已满足。

• 是否有剩余风险或延后事项。

• BitLesson 是否需要新增或更新。

4.6 Summary Review：独立审查实现是否真正完成

当 Agent 尝试退出时，Stop Hook 会触发 Codex 审查 summary。如果 Codex 认为还有遗漏、测试不足、计划未满足或描述不清，它会把反馈写入 round-N-review-result.md，并阻止循环结束。执行 Agent 必须读取反馈并继续修复。

只有当 Codex 输出 COMPLETE，Humanize 才会进入 Review Phase。这一步解决的是“实现者自我感觉良好”的问题。实现模型不能自己宣布胜利，必须接受独立审查。

4.7 Code Review Phase：从功能完成到质量过关

Implementation Phase 关注“计划是否完成”，而 Code Review Phase 关注“代码质量是否过关”。这一阶段会调用 codex review --base <branch>，由 Codex 对当前分支相对 base 分支的改动做代码审查。审查问题会带有 [P0-9] 严重级别标记。

如果存在阻塞问题，循环会回到实现阶段继续修复；如果没有阻塞问题，则进入 Finalize Phase。这样，Humanize 把“功能验收”和“代码审查”分成两个层次，避免只满足表面功能却留下明显质量问题。

4.8 观察阶段：monitor 让人从陪跑变成旁观控制

长周期自动任务不能靠盲等。Humanize 提供多种监控方式：

• humanize monitor rlcr：查看最新 RLCR 循环日志。

• humanize monitor skill：查看所有 Skill 调用。

• humanize monitor codex：查看 Codex 调用。

• humanize monitor gemini：查看 Gemini 调用。

• humanize monitor web：启动浏览器 dashboard。

这些监控读取 .humanize/rlcr/<timestamp>/ 和缓存日志。人不必每一步都介入，但可以随时了解当前 round、审查结果、失败原因和最终状态。

五 、Stop Hook 与 Gates：自动化不是放权，而是加约束

Humanize 能让 AI 自主推进，不是因为它降低了安全要求，而是因为它把安全要求自动化。源码中的 hooks/hooks.json配置了多个生命周期拦截点：

• UserPromptSubmit：用户提交 Prompt 时检查计划文件。

• PreToolUse：在写文件、编辑、读取、执行 Bash 前进行验证。

• PostToolUse：在 Bash 后处理命令结果。

• Stop：Agent 尝试退出时触发 RLCR stop gate。

其中 Stop Hook 最关键。它把“退出”变成一个受控事件：不是 Agent 说完成就完成，而是必须经过状态检查、摘要检查、分支检查、计划检查和 Codex 审查。

5.1 Gates 解决哪些风险

PPT 和源码中体现的 Gates 可以理解为一组工程护栏：

• Branch Consistency：循环开始时记录分支，防止中途切换导致审查基线混乱。

• Plan Integrity：计划文件是合同，执行过程中不能随意修改计划来降低验收难度。

• Summary File：每轮必须写 summary，否则审查器不知道实现了什么。

• Git Clean / Push Every Round：可要求每轮提交或推送，避免未记录改动丢失。

• Large File：过大的文件需要拆分，避免模型生成难维护的巨型文件。

• Max Iterations：默认最多 42 轮，防止无限循环。

• State Schema Validation：状态文件缺字段或被破坏时，循环应 fail closed。

这些 Gates 让自动化开发更像 CI/CD：不是放任执行，而是在关键节点持续校验。

5.2 为什么必须有独立模型审查

让同一个模型实现、解释、审查自己的代码，容易出现一致性幻觉：它会沿着自己的假设继续证明自己是对的。Humanize 采用 “One Build + One Review”，例如 Claude 实现、Codex 审查，目的就是引入异质视角。

独立审查的价值包括：

• 发现实现者遗漏的 AC。

• 发现测试未覆盖的边界。

• 发现代码质量或架构问题。

• 识别计划执行中的目标漂移。

• 给出下一轮明确修复方向。

这不是传统意义上的“多一个模型投票”，而是把 Builder 和 Reviewer 的职责拆开，形成工程制衡。

六 、文件记忆：突破 Context Window 的关键

Humanize 不试图把所有历史都塞回上下文，而是把长期信息放进 .humanize/ 目录。这样即使对话 compact、Agent 重启或进入新 round，关键状态仍然可以恢复。

6.1 .humanize/rlcr/ timestamp/ 保存什么

每次 RLCR 循环都会创建一个 session 目录。典型文件包括：

• plan.md：本轮循环使用的计划备份。

• state.md：当前 round、最大迭代数、模型配置、base branch、start branch 等状态。

• goal-tracker.md：目标、验收标准、任务状态和计划演化记录。

• round-N-summary.md：执行 Agent 每轮写的工作摘要。

• round-N-review-result.md：Codex 对 summary 的审查结果。

• finalize-state.md / complete-state.md：最终阶段和完成状态。

这些文件共同构成了外部记忆。模型不需要记住所有历史，只需要在合适的时候读这些文件。

6.2 Goal Tracker：防止目标漂移

长任务中最危险的问题之一是目标漂移。AI 可能在修复一个小问题时开始大范围重构，或把非阻塞优化当成主线目标。Humanize 用 goal-tracker.md 固定目标。

Goal Tracker 分成两部分：

• Immutable Section：Ultimate Goal 和 Acceptance Criteria，初始化后保持不变。

• Mutable Section：Active Tasks、Completed Items、Deferred Items、Plan Evolution Log，用来记录执行进展和合理变化。

这个设计让每轮实现都能回答三个问题：现在的主线目标是什么？哪些验收标准还没满足？本轮新增的发现是否改变计划，为什么？

6.3 主支线管理：blocking、mainline、queued

Humanize 还引入了主支线管理思想，把任务分成：

• blocking：阻塞主线完成的问题，必须优先处理。

• mainline：直接推进验收标准的任务。

• queued：非阻塞优化或后续事项，不应抢占当前目标。

优先级通常是 blocking > mainline > queued。这看似简单，但对长周期 Agent 很重要。没有这个分类，模型很容易被旁支问题吸引，越修越远。

6.4 BitLesson：把多轮踩坑变成项目经验

每个项目可以维护 .humanize/bitlesson.md。如果某个问题经过多轮才解决，Humanize 会要求把“具体问题 + 具体解决方式”沉淀为 lesson。后续执行时，selector 会选择相关 lesson，帮助 Agent 避免重复踩坑。

BitLesson 的意义在于，它不是泛泛的“最佳实践”，而是项目局部经验。例如某个测试框架的固定启动顺序、某个仓库的特殊构建参数、某类生成文件不能直接编辑等，都可以沉淀为 lesson。

七、案例：XS-UT 验证框架搭建

XS-UT 案例是香山验证团队使用长程任务开发的代表场景。任务目标是为 XS-UT 使用 ucagent 进行验证框架适配，覆盖验证基础设施、测试点、测试用例、错误分析和错误修复。

XS-UT 验证框架任务有几个特点：

• 目标明确：构建验证框架并生成可运行测试。

• 过程复杂：需要理解模块、生成测试点、写测试代码、运行验证、分析失败。

• 可验收：测试是否能运行、是否覆盖边界、是否能复现 bug 都可以验证。

• 可并行：不同模块、不同测试点可以拆给 SubAgent。

• 需要反复修正：测试生成、运行失败、bug 复现都需要多轮反馈。

7.1 如何真实推进这个任务

结合上文的介绍,在真实推进验证任务落地时，案例大致路径如下：

1. 撰写 Draft：人先描述测试需求、覆盖范围、模块边界和期望结果。

2. Gen Plan：Humanize 从 draft 生成结构化 plan.md，包含 AC-N 验收标准、里程碑和实现顺序。

3. Brainstorming：通过多轮问答澄清模糊点，把计划打磨到可以执行。

4. RLCR 执行：Humanize 启动循环，主 Agent 分解任务，SubAgent 并行工作。

5. 生成 YAML 测试计划：为模块生成测试点、参数组合和覆盖策略。

6. 生成 Python 测试代码：根据 YAML 计划生成可执行测试用例。

7. 运行验证并发现 bug：通过测试暴露前端、后端等模块中的真实问题。

8. 复现与修复：围绕失败用例进行定位、复现和修复，再进入审查循环。

7.2 具体来说 先花时间写好 draft

Humanize 的自动执行能力依赖计划质量。一个好的 draft 不需要非常正式，但要说明：目标是什么、不要做什么、哪些文件或模块相关、如何判断完成、有哪些已知风险。

可以把 draft 写成以下结构：

标题：为某模块补充回归测试

背景：
当前模块在边界输入下容易出现错误，但缺少系统测试。

目标：
补充测试计划、生成用例、接入现有测试命令，并修复暴露出的真实问题。

范围：
- 允许修改 tests/ 和必要的测试辅助脚本
- 不允许重构核心业务逻辑，除非测试证明存在 bug

验收：
- 新测试可通过现有命令运行
- 至少覆盖正常输入、边界输入、非法输入
- 如发现 bug，需要给出复现用例和修复说明

7.3 AC 要可验证，不要写成愿望

坏的 AC：

• “代码质量要好。”

• “尽量覆盖完整。”

• “实现一个稳定方案。”

好的 AC：

• “运行 pytest tests/foo 通过，且新增测试至少覆盖空输入、最大长度输入和非法格式输入。”

• “当配置文件缺失时，CLI 返回非 0 状态码并输出明确错误信息。”

• “不修改公共 API，除非计划变更记录中说明原因并通过审查。”

Humanize 可以自动审查，但前提是验收标准足够具体。

7.4 把非阻塞事项放入 queued

长任务中经常会发现很多“顺手可以优化”的点。不要让这些点抢占主线。应该把它们写入 queued，等主线完成后再处理。这样可以防止 AI 在优化中迷路。

7.5 让测试成为闭环的一部分

如果一个任务没有测试或验证命令，Humanize 的闭环会弱很多。最好在计划中明确：

• 应该运行哪些测试。

• 测试失败时如何定位。

• 哪些失败属于已知问题，哪些是阻塞问题。

• 没有测试时是否允许新增测试。

这能帮助 Codex Reviewer 判断实现是否真正完成。

7.6 写在案例的最后

这一节主要以验证 Agent 举例,这个开源项目在实际使用中产生了真实的业务价值。

Token消耗约 1B Token · 一人一天 的规模。

"通俗来讲 按照 ai native的标准,这是一个人的脑力上限的token临界点,当跨过该临界点,必然就要在细节掌控上 做取舍"

对于该开源框架在芯片验证任务上的提效,我有以下几点想法来分析验证任务提效的底层原因:

1. Humanize 的核心价值不是少写几行代码，而是把原本需要持续人工调度的长流程变成可监控的自动执行。

2. 它适合任何具备“计划—生成—验证—反馈”结构的工程任务。硬件验证、编译器测试、基础设施迁移、接口适配、测试框架搭建等，都可以套用类似方法。

3. 验证本质是一个语义对齐的工作,测试用例与测试点是建立统一需求的不同形式的等价性证明,而AI天然适合这件事情

八、结语

Humanize 给 AI 编程提供了一种更工程化的方法论：用计划替代临场 Prompt，用文件记忆替代超长上下文，用 Hook 替代人工催促，用独立审查替代自我确认，用 Gates 替代裸奔自动化，用 SubAgent 替代单线程执行。

它承认 AI 会犯错，也承认单个模型无法在复杂工程中长期保持完美状态。但它通过闭环机制让错误可以被发现、被反馈、被修复，直到系统收敛到验收标准。

九、广告

开芯院现有LLM for 芯片验证的实习岗位^[1]