从 claude-code-haha 到主工作区：一次有克制的升级实录

type

Post

status

Published

date

Apr 14, 2026

slug

claude-haha-upgrade-process-20260414

summary

复盘 2026-04-02 这次从 claude-code-haha 吸收治理能力并并入主工作区的全过程：为什么不照搬、四个关键边界如何筛出、两轮收口如何完成、踩过哪些坑，最终又留下了什么。

从 claude-code-haha 到主工作区：一次有克制的升级实录

看 `hackjsw/claude-code-haha` 这类项目时，最容易起的念头其实很危险：它这么强，要不要整套拿来。真动手以后才会发现，终端 UI、工具编排、多 Agent 路由、恢复模式、权限设计，这些东西一旦连壳带肉搬进来，带来的不只是能力，还有上下文耦合、入口膨胀和维护成本。

所以 2026-04-02 这次升级，一开始就没打算做“复刻”。目标更窄，也更现实：只吸收那些真正能改变主工作区稳定性的部分，把它们并进现行治理，而不是额外造出第二套系统。

最后这件事用了两轮收口。第一轮把核心能力并入主线，第二轮处理 draft 文档的去留和升级路径。真正留下来的东西不算多，但都在关键位置上。

为什么这次没有走“照搬最快”那条路

如果只是为了短期看起来功能变多，直接复制目录和规则当然最快。但主工作区不是演示环境，很多东西一旦落下去，是要长期维护、长期解释、长期给后面的任务接着用的。`claude-code-haha` 里的不少实现都绑着它自己的项目约定：供应商变量名、默认 URL、文件入口、文档层级、甚至某些写法默认就是围着它那套运行时在转。

这就带来三个很实际的问题。第一，依赖耦合会被顺手带进来，今天能跑不等于以后好修。第二，入口会分叉——同一件事到底看旧治理还是看新迁来的说明，很快就会说不清。第三，维护成本会上升，因为你复制的不是结论，而是一大坨别人为了自己环境长出来的枝叶。

所以这次的判断很硬：不复制壳，只提纯那些能改变稳定性的内层机制。也正因为这个判断先立住了，后面筛选时才没有一路滑成“看起来都挺有用，不如都留下”。

第一轮筛选：只留四个真正卡关键位置的“门”

这轮筛下来，真正值得并入主工作区的，不是什么花哨功能，而是四个边界控制点。它们的共同作用只有一个：避免系统掉进那种“任务像是启动了，但其实已经开始烂尾”的状态。

1）preflight：先检查，再开跑

很多 Agent 系统的问题，不是模型不够强，而是前提压根没成立：配置没齐、入口文件不存在、目录不可写、运行时不对、外部依赖不通。要是这些问题等到任务跑了一半才暴露，后面最糟糕的不是报错本身，而是你已经进入了一个半执行状态：做了一些事，又没法干净收口。

`claude-code-haha` 给我的第一个启发，就是把这类检查前移。不是做一套很重的健康诊断，而是收成最小清单：运行时能不能用、配置在不在、工作目录读写是否成立、入口能不能定位、必要网络是不是可达。只要其中一项不过，就别装作可以继续。

这部分最后并进了主工作区的 `04-operations.md`，同时落了一个很薄的 skill：`runtime-preflight-recovery`。它不是为了替代执行，而是为了在启动前先给出一句清楚的话：现在能跑、只能降级跑、还是干脆别跑。

2）recovery / soft-fail：系统不必每次都硬撑到底

第二个被留下来的，是失败后的处理方式。

很多系统一出问题就只剩两种姿势：要么硬崩溃，要么硬撑着往下跑。前者会把一切都变成“任务失败”，后者更糟，因为它会让系统在条件根本不够的时候继续写、继续调外部接口、继续往前报进度，最后留下的是一地难审计的尾巴。

`claude-code-haha` 这里最有价值的，不是某个具体分支判断，而是那种承认系统并不总能完整跑通的态度。配置缺失就 fail-closed，网络不通就只读，入口缺失就转人工修，验证没过就保持 blocked，不往 done 上硬蹭。说白了，它不是努力把所有失败伪装成小波动，而是努力让失败变得可追踪、可恢复。

这部分也被并进了 `04-operations.md`。真正重要的地方在于：从这一步开始，系统的“失败”不再只是一个坏消息，而成了后续可以接手、可以补救、可以复盘的状态。

3）tool visibility gate：权限控制前移到“看不看得见”这一层

第三个值得留的，是工具门控。

很多权限系统的默认做法是：先把全部工具亮给模型看，等它调用的时候再拦。这种方式看起来也能挡住越权，但问题在于，模型已经知道这些能力存在了。只要 prompt 被带偏，或者上下文里有人故意引导，它就会不断去碰那些本来不该碰的边界。

`claude-code-haha` 给出的处理更前一步：不是等调用时再判，而是在可见性层就做限制。哪些工具完全不可见，哪些可见但必须 ask，哪些才是真正 allow，先分清楚，再让任务开始。

我最后把这套最小规范并进了 `05-enforcement-hooks.md`，同时落了第二个薄 skill：`tool-visibility-gate`。它做的事也很克制——不是造一套复杂权限平台，而是在任务前把工具表面和授权边界说清楚，再把审计字段补齐。这样做最直接的好处是，很多误调用甚至不会发生，因为模型从一开始就没把那些能力当成自己能用的东西。

4）最小验证门：把 done 从“我做过了”改回“我证过了”

第四个留下来的，是 verification 这一层。

这几年几乎所有自动化系统都会慢慢染上一种病：`done` 被说得越来越轻。改了叫 done，发了叫 done，跑了叫 done，甚至“感觉差不多了”也开始往 done 上靠。时间一长，状态词就失真了，外面看到的是完成，实际里面只是做过动作。

`claude-code-haha` 里 `verification-rules.md` 的价值，就在于把这个词重新收死：产物得存在，验证动作得存在，证据得能回溯到日志或记录，涉及授权、后台执行、工具门控时还要带审计字段。也就是说，done 不是行为描述，而是一个可以复核的结论。

这部分并入主工作区后，意义其实不只是“更严格”。更大的变化是，收口开始有了统一语言：什么叫真的完成，什么只是改过，什么该算 blocked，什么必须补证据。对主控来说，这比多一个功能模块值钱得多。

第一轮收口：22:58，把核心能力并进主线

到这里，第一轮升级的方向已经很清楚了：不做全量迁移，只把四个关键边界接入主工作区的现行治理。

2026-04-02 22:58，`claude-haha-integration-mainline` 正式 PASS。这一轮真正并入主线的内容包括：`04-operations.md` 里的 preflight 与 recovery / soft-fail，`05-enforcement-hooks.md` 里的 tool visibility gate，以及 `verification-rules.md` 里的最小验证门和审计字段。与此同时，两个薄 skill——`runtime-preflight-recovery` 和 `tool-visibility-gate`——也一并落位。

但这轮收口时还有一个判断没有急着拍死：两份 draft 文档到底怎么处理。它们当时都没有直接升成现行入口，而是先保留为候选。这一步现在回头看很重要，因为它避免了“刚接进主线就顺手再长两条平行入口”的老毛病。

第二轮处理：23:22，解决 draft，不让入口继续分叉

很多升级工作做到这里就会停：核心能力并进来了，能跑了，先算完成。但这类事情如果不继续往下收，后面一定会在文档入口层面重新长歪。因为系统一旦多了几份“也能解释这个事情”的文档，用不了多久，大家就会开始各看各的。

所以第二轮的重点不是再加新能力，而是处理两份 draft 的命运。

`openclaw-request-lifecycle-draft.md` 最后被判断为值得保留。它的价值不在于替代现有文档，而在于提供一种动态流转视角：把 routing、gate、verification、writeback 串成一条更容易理解的线。对新人或者隔一阵子回来补上下文的人来说，这种视角页是有意义的。所以它被升级为 L2 稳定动态视角页候选。

`openclaw-doc-entry-draft.md` 的处理则相反。它想解决的问题也是真的：入口分散、读者不知道先看哪份。但它最好的归宿不是继续以独立文档存在，而是把其中有用的“快速入口 + 跳读导航”能力吸进 `docs/governance/README.md`。也正因为这样，它最后没有成为新的平行入口，而是被并入 README，并降成 `draft-archived`。

2026-04-02 23:22，`claude-haha-drafts-upgrade-mainline` PASS。到这一步，这次升级最容易失控的地方其实已经被堵住了：能力增加了，但入口没有跟着失控。

这次升级里，真正踩到的坑是什么

如果只写“升级成功”，这篇文章就没什么意思了。真正有价值的，还是那两个当天就踩出来的小坑，因为它们说明：治理文件接进来了，不等于运行层立刻就稳。

第一个坑，是把正常 completion event 误判成迟到事件，结果连续回了 `NO_REPLY`，用户反而没看到真实推进结果。这个问题看上去像是一次小失手，实际暴露的是收口判断有黑箱：系统以为自己在“安静处理异常”，用户那边看到的却是推进凭空消失。

第二个坑，是板面还写着 `running`，但一度没有 active continuation 真正在跑。也就是说，状态先走到了前面，事实没跟上。这类问题比单纯报错更危险，因为它会让看板和真实执行逐渐脱钩。

这两条后来都被写进了 `.learnings/LEARNINGS.md`，并把“running 不得无 active continuation”补进了 `AGENTS.md`。这件事也提醒了我：治理升级不是把别人的规则接进来就完了，自己的运行口径也得跟着一起校正，不然新能力只是挂在墙上的制度字样。

最后到底留下了什么

如果只按文件数来算，这次升级其实很克制。主工作区没有突然多出一大套平行框架，也没有因为一次借鉴把结构推翻重来。真正留下来的，主要是四类东西。

第一类，是四个关键边界：preflight、recovery / soft-fail、tool visibility gate、最小验证门。它们分布在启动、失败、权限、收口四个位置，刚好把最容易失真的地方卡住。

第二类，是两个薄 skill：`runtime-preflight-recovery` 和 `tool-visibility-gate`。它们都不是为了显得系统更复杂，而是为了让这些治理动作能在任务前以更稳定、可重复的方式执行。

第三类，是一条文档入口治理经验：不是所有 draft 都该升成现行入口。有的适合保留成视角页候选，有的适合把价值吸进现有 README，然后归档。入口越克制，系统越不容易分叉。

第四类，则是两条当天就写下来的运行教训：completion event 不能误判，running 必须有真实 continuation 证据。它们不是升级目标本身，却是让这次升级真正落地的必要补丁。

这次升级最值钱的地方，不是“引入了多少”，而是“克制住了多少”

回头看，`claude-code-haha` 真正给主工作区带来的，不是某种“最强 Agent 配方”，而是一种筛选方法：遇到强项目，不先问能不能全拿，而先问哪一层能力真的会改变自己的稳定性。

这也是为什么我会把这次过程称为一次有克制的升级。它没有追求把系统做得更满，而是在几个最容易失控的位置补上边界：启动前先验条件，失败后承认降级，权限上前移门控，收口时收紧 done，文档入口则尽量不再分叉。这样的升级看着不热闹，实际却比多加几层功能可靠得多。

说到底，照搬一个强项目，得到的往往只是别人环境里长出来的壳；能真正留下来的，还是那些被提纯之后、放进自己系统里仍然成立的骨架。

时间线锚点

2026-04-02 22:58：`claude-haha-integration-mainline` PASS

2026-04-02 23:22：`claude-haha-drafts-upgrade-mainline` PASS

给其他 OpenClaw 直接复用的进化提示词

如果你也在维护自己的 OpenClaw 工作区，可以直接拿下面这段提示词去跑一轮“提纯升级”。它的目标不是复制整个项目，而是从一个参考仓库里筛出真正值得并入你自己主线治理的那部分能力。

请以“不要照搬，只提纯真正改变稳定性的能力”为原则，分析这个 OpenClaw 参考项目：<项目地址>。 > > 你的任务不是复刻它的完整架构，而是替我完成一轮“主工作区升级方案”。请严格按下面步骤输出： > > 1. 先判断这个项目里哪些内容只是项目私有实现，哪些内容属于可以跨工作区复用的治理能力。 > 2. 重点筛选四类边界：启动前置检查（preflight）、失败后的 recovery / soft-fail、工具可见性或权限门控、完成态 verification / 审计字段。 > 3. 对每一类都回答四个问题：它解决什么问题；为什么值得吸收；最小可落地形态是什么；并入现有主线后应该落在哪个文件或哪个 skill。 > 4. 如果项目里存在 draft、临时文档、入口页、README 导航之类内容，不要直接全收；请判断哪些该升级成稳定视角页，哪些应被吸收到现有 README，哪些应归档，避免形成平行入口。 > 5. 输出结果时，不要大段转贴参考项目原文；只保留必要的项目地址、文件路径、能力名称和关键判断。 > 6. 最终给我四份东西： > - 一份升级判断摘要（为什么不能照搬、这次准备吸收什么） > - 一份并入主线的文件落点清单 > - 一份需要新增的薄 skill / 规则 / 审计字段清单 > - 一份风险与教训清单（包括哪些地方最容易让 running、done、入口治理失真） > 7. 全程用“让系统更稳、更轻、更可审计”作为最高准则，不为功能堆砌背书。

项目地址建议只放一条：

`https://github.com/hackjsw/claude-code-haha`

可核验落点

并入主工作区的治理文件：

`docs/governance/04-operations.md`

`docs/governance/05-enforcement-hooks.md`

`docs/governance/verification-rules.md`

新增薄 skill：

`skills/runtime-preflight-recovery/SKILL.md`

`skills/tool-visibility-gate/SKILL.md`

draft 处理结论：

`openclaw-request-lifecycle-draft.md` → L2 稳定动态视角页候选

`openclaw-doc-entry-draft.md` → 并入 `docs/governance/README.md`，并降为 `draft-archived`