打造一个适合自己的workflows和skills的尝试

chahuajia
3 阅读18分钟

当生产免费，唯一稀缺的是判断

3 个仓库，129 条规范，一个压测项目。 结论：最值钱的不是collaboration那 129 条正文，而是 十几条判据 和一套 会否定自己的机制。

⏱ 文中数字是写作时（2026-09-26）的快照，它们会腐烂。 要当前值：collab validate（全部条目）· collab catalog（在路由里的）· npx vitest run（测试数）。 本文自己就抓到过这个病 —— 初稿有三个版本，三处数字各自腐烂（详见第四节判据 C′）。

起因：我不是想写规范，是想让 AI 别忘事

一开始只是个小麻烦：让对话式 AI 解释代码时，它有时会忘记约定的输出格式，或者漏掉我特意交代的规矩。

后来试了个笨办法 —— 把大佬们沉淀下来的 workflows / skills 直接喂给它。有效果。 更有意思的是：它在解读代码时，偶尔会冒出一些我自己没想到的判断（不是知识，而是"怎么判断"）。

于是就冒出一个念头：能不能不靠我手工搬运，让 AI 自己把这些有用的做法吸进去、总结出来、再迭代？

但真要动手，先要回答一个更根本的问题：什么东西值得留下、什么东西该被删掉 —— 凭什么？

这个仓库和这篇文，都是那个念头跑出来的副产品。三个仓库的分工：

仓库它是什么在本文里的角色
collaboration知识库本体（条目 + 两本账本 + 门禁）主角
collab-cli工具链（validate / catalog / retire / MCP）把"判断"变成会被执行的机器
evolutionary真实业务项目（换电平台演练；链接指向其中一条功能分支）试验场：本文所有"拦截"都发生在这里

以下是它跑起来的这阵子里撞到的墙，和为了不撞第二次而长出来的机制。

一、37 个文件，35 个是空的

有一次，AI 把一批规范"落盘"了。37 个文件。第二天核对：35 个是 0 字节。

没有人发现。因为校验器是绿的 —— 它只检查"文件在不在"，不检查"里面有没有东西"。

而真正完整的那一版，反而躺在一个 79KB 的单文件补丁里，不可检索、不可链接、不可删除。

这不是 AI 的错。这是环境的错：写下一条规范的成本趋近于零，而验证它、修剪它的成本没有变。

当生产免费，全部价值迁移到"选择"和"验证"。

二、我们以为在写知识，其实在建选择机制

三种生产成本，三次迁移，同一个规律：

生产成本趋近于零价值迁移到表现
写代码reviewAI 写完 → 人读代码，review 成为瓶颈
写测试规格规格先行，测试是规格的形式化
写条目修剪与验证条目无限膨胀，信噪比归零

怎么让"该留下什么"这件事，不依赖人的自觉？

三、先看证据，包括对我们不利的

下面是出现过的几个问题，第二个是反证。

问题 1：n=3 的自然实验

三个仓库里，只有一个被新鲜度脚本盯着。

仓库被仪器盯？状态
工具链仓是新鲜
知识库仓否落后 21 个提交
业务仓否根本没登记

100% 相关。 结论不是"这知识库有用"，而是：

规则有没有用，不取决于它写得多好，取决于它接在哪里。

问题 2：唯一干净的对照实验，测出零差异

在空项目里跑双臂（有库 / 无库）：代码结构无差异，读知识库那一路墙钟 +55%。

但它有边界：它测的是"模型知不知道正确答案"，而不是"模型会不会被本地代码带偏"。后者的证据在下一节。

问题 3：111 个波次，知识增量为 0

我们让 agent 集群在一个真实业务项目里连续跑了 111 个波次：前端测试从 35 涨到 185，代码一路推进。

知识库的增量为 0。

去看在做什么：把已经成熟的写法，一个域一个域地铺过去。

机械应用撞不到墙。撞不到墙，就产不出新知识。 而"跑得欢"和"走得远"，在仪表盘上长得一模一样。

四、可以搬走的判据

不是 129 条正文 —— 是这些。

判据 1：无机制的政策是负优化

加了规则却更慢，不是"还没优化够"。判定三问，任一答"否"就停下：

  1. 违反能否 60 秒内被外部观察到？
  2. 发现之后有强制动作吗？（"记一笔"不算）
  3. 执行面具备吗？（工具、脚本、约束）

我们在同一个流程上从 v5 写到 v9，每版都在加条文，吞吐反而变慢。

判据存在、可观察、但没有任何东西去数它 —— 等于没有。

判据 2：给停滞装仪器，测"产出为 0"，不要测"积压 > 0"

我们装过一台仪器：给"待处理候选"检查龄期，挂太久就报警。

装完跑一遍，绿的。一天后核对：那个队列里最新的记录是两天前的，中间一百多个波次，新增为零。

我假设的病是"东西堆积、没人处理"。 实际的病是"东西根本不产生"。 所以那台仪器永远不会亮 —— 它测的是一个不存在的病。

后来我们把仪器状态整理成一张表，越往下越贵：

状态结果
① 没仪器从未执行
② 有仪器、没接线也未执行（脚本写了两天没人跑）
③ 接了线、但测错了病恒绿 —— 比没装更危险，因为它看起来像在监控
④ 测对了、也红了、没人接仍不执行 ← 我们最近才发现这一档
⑤ 红了、且有强制动作真正生效（接线当天抓出 2/3 仓已烂）

第 ④ 态是最后才补上的：我们的工作记忆仪器当场报出 "7 个文件里 6 个需要处理"，红灯亮着 8 到 9 天，而唯一的响应是"知道了一件事"。

装仪器时，要同时写响应协议：红灯出现后只允许两个动作 —— 更新它，或降级归档。"知道了但不动"不是第三个选项，它是这台仪器失效的定义。

2026-09-26 又补一种 ③ 的变体：差值型仪器要先问"同源吗"。 这台仪器的判据是"自上次对账以来有几个提交"（git rev-list --count <基准>..HEAD）。 实测：人在 topic 分支上对账（基准 ac7aa6c），之后切回更旧的 main（dc3b366）—— 这个数返回 0，仪器报"新鲜"。不同源时，差值不是"零"，是"没测"。

判据 3：声称需要被强制，否则静默漂移

某段代码的注释写着"同事务双写"。听起来很可靠。

而整个仓库没有一处 @Transactional。

后果不是慢，是数据错：两次写各写各的，第二次失败时第一次已经提交 —— 货被取走了，账上没有记录。而用户那侧看起来一切正常。

修它的方式不是改注释，是先写一个会红的测试证明它现在不成立，再把机制补上。

代码里有一类注释，不描述"这段在做什么"，而是声称一个跨切面属性 —— 同事务、线程安全、已校验。 读到这种，先花五秒 grep 一句：谁在强制它？

判据 4：核实的范围，由你的想象决定

同一个动作，连续两次不同形态的错：

  • 第一次：下令"改成服务端渲染"，动手时才发现后端根本没有读接口；
  • 第二次：核实了生产实现，却漏了三个测试替身。

不是"没核实"，是"核实的范围不够"。

为什么：

测试里出现的形态，是作者脑子里的形态。 而作者脑子里的形态，正是他误解的那部分。 所以测试通过，不是因为东西对，是因为它和你的误解一致。

五、这套东西对 agent 的用处

  1. 它拦的是"恭顺"，不是"无知"。 这是最有价值的一条。16 条真实拦截记录里，5 条的原文写着"差点继续" —— 差点继续用字符串前缀判 HTTP 状态码、差点继续把首页写成纯客户端渲染。没有一条是"模型不知道"，每一条都是"模型知道，但它照着本地已有的坏代码写下去了"。 这个区分决定生死：拦无知的规范会随模型升级变成废纸；拦恭顺的规范永远不会贬值，因为项目里永远有旧代码。

  2. 它给 agent 一个"可以合法地说找不到"的位置。 路由表没有 → 用关键词检索 → 还是没有 → 报告"找不到"，不要凭空发明规范，并把这次检索记进"缺口账本"。结果是下一批 agent 不会在同一个地方再撞一次 —— 而"查过了、没有"和"根本没查"从此长得不一样。

  3. 它给发现一个落点。 业务仓记候选，通过复盘后只往知识库回填一行摘要，证据留在业务仓。没有这条，知识库会被项目日记淹死。

  4. 它让输出可判定。 校验器有一组结构规则（YAML、id、链接、章节、索引、生成物新鲜度、未声明目录…）；新条目入库必须回答 "不读它，模型会照着本地哪个模式写错？" 答不出来就不许进。

  5. 多 agent 派工有了契约。 真实踩过的坑：同一棵树四个写者互相覆盖、worktree 里"找不到刚写的文件"（分支分岔，且不报错）、派出去了没有回执、小切片派工是负吞吐。现在的前置条件写成两条：基线绿 + worktree 重新基线；且先问"这一波两路会不会改同一个方法体"。

六、它对 agent 的坏处

  1. 上下文税。 知识库的 markdown 一共 467 KB（167 个文件，2026-09-26 实测）——全量注入是十万 token 量级，直接吃掉大半窗口。用得好是 O(log n)（读入口 + 两三条），用不好就是把窗口捐给元讨论。

  2. 不可自证的规则会被"表演"。 "回答从 H2 开始""不改约定"这类能自查的规则会被真遵守；"给鼓励""递归两轮"这类无法证明的，只会被表演。规则必须写成"我能自证"的形式，否则它就是 token 成本。

  3. 错误的权威感 —— 最隐蔽的一害。 知识库错了，agent 会更自信地错。实测：校验器报 0 问题，而我自己写进条目的一个路径根本不存在。文档腐烂不可怕，腐烂的文档被信任才可怕。

  4. 窄化搜索。 "路由表没有 → 报告找不到"这条规则是对的，但它有个危险的下沉版本："库里没有 → 不做"。知识库会悄悄变成 agent 的世界边界。

  5. 维护成本转嫁给未来每一次会话。 每次新会话都要读入口、判新鲜度、维护两本账本。这不是免费的：实测里 7 个工作记忆文件 6 个过期，而 111 个波次中知识库产出为 0。做得好的时候它是引擎，做不好的时候它是图书馆。

七、所以值得使用吗

层值得使用？理由
机制（校验器 / 两本账本 / 入库门槛 / 毕业退役 / 仪器）✅有证据、可搬运、直接改变 agent 行为
判据（第四节四条 + 第十节那一批）✅可以脱离本仓库独立使用
30–40 条通用工程正文⚠️ 部分模型自带，且会随模型升级自动变好
治理形态（CODEOWNERS / RFC / 讨论期）❌一人规模下是空壳 —— 我们验证过，从未运行

判据只有一条：它是否改变 agent 在某个具体高代价场景下的行为。按这条筛，值得推广的东西不到全部内容的 10%。

八、如果你只想搬一样东西

搬两本账本，加一道门槛，加一根会亮的线。

interceptions.md   条目拦住了什么   → 决定留哪条
known-gaps.md      条目没能回答什么 → 决定补哪条

它们是一对。只有收益侧、没有缺口侧的账本，会变成一份功劳簿。

再加上那道入库门槛：

新增一条，必须能说出"不读它，模型会照着本地哪个模式写错"。说不出来，就别进库。

以及一根线：任何规则，先回答"它接在哪"。接不上的，现在别写。

九、最后

回到开头那个问题：生产变便宜之后，什么变贵了？

判断变贵了。

而判断有个特点：它不能靠"加东西"解决。 加条目、加规则、加 agent、加门禁 —— 全都在增加生产。

以上最有用的事，几乎都是减：

  • 删掉一个假绿灯的检查（它 echo 一行就算通过，五项校验一项没做）；
  • 删掉一个编造的数字（"边际价值增加 3-5 倍"，没有任何来源）；
  • 改掉一条与事实相反的规则（"AI 永远不持有写权限" —— 它有）；
  • 写一条规范，专门用来指控自己最近三个版本的负优化。

这套东西最像样的能力，是它否定自己的能力。

一个知识系统的价值，不在于它知道多少， 而在于它能不能在没有外部监督的情况下，抓住自己的错误。

十、第二轮：一次"合规表演"，和它逼出来的几条判据

第一轮结束时，我们以为判据差不多齐了。第二轮就撞上一件新事。

事故：模型学会了"表演合规"

我们把多文件输出的格式要求写进了一份约定（"请用 ===== FILE: <路径> ===== 分隔"）。

对话式 AI 的输出是这样的：

开场白 → ```text 围栏 → 真条目 → 一张"为什么这样符合约定"的对照表 → 一句追问

它遵守了分隔符，却把整件事包了起来，还额外写了一段解释自己如何遵守的文字。 解析器按既定规则严格拒收 —— 15 条 content outside any block。

这不是模型不听话，是约定的形状不对：那份约定规定的是"分隔符长什么样"， 没规定"整段输出的形状"。而模型会把"格式要求"当成它输出内容的一部分。

改成"内容自描述"之后——不再要任何人为分隔符，边界改从条目本来就有的 YAML frontmatter 里读 id / type——三种污染（围栏、开场白、合规说明表）同时消失。

判据 A：契约的形状不对时，补丁追不上。 外部输入反复以"多余包装"出现时，先问契约是不是在管包装，而不是再加一条宽容规则。

另外几条，是同一轮的具体缺陷逼出来的

#判据现场
B"跳过"必须配"出声"；成功路径也要能带 warningResult<T, E> 表达不了"成功但有警告"，于是"宽容"必然退化成"静默丢弃"
C能派生的别手写同一形状当场抓到五次：章节清单 / help 选项 / 目录清单（少了一个）/ 版本号 / 标题位规则
C′同一内容写两处，必然漂移本文曾有三个版本（叙事 / 说明 / 分享），三处数字各自腐烂过：条目数 126 与 129 互不一致、拦截数写 13 而实际 16、开放缺口写 3 而实际 0。已合并为一篇 —— 合并不是编辑偏好，是这条判据的执行。
D验收证据必须在仓里、在 CI 里把 D:\下载缓存\test.txt 当验收标准 = 借来的证据：今天比真的还真，明天随下载目录一起消失
E"这个文件如果写错了，谁会红？"scripts/*.mjs 既不在 typecheck、也不在 lint、也不在测试里，而它打印的正是"验过了 / 没验"的分界线
F深查要换维度，不是换样例同一维度加更多样例，盲区却在维度上：两条"代码写着支持、却从未端到端跑过"的分支
G生成物也要核实，不是只核实源源码全绿，但 dist/ 里旧模块还在，而发布白名单收整个 dist/ → 已发布的包里带着 5 个无源模块
H本地绿 ≠ CI 绿；"CI 绿"也不等于"CI 在跑"本仓 CI 从 #1 到 #38 38 次全红、一次没绿过，而本地 npm run check 一直是绿的。修好后的第一次绿之前，它先抓出一条只在真实 runner 上才暴露的缺陷：测试默默依赖"作者机器上恰好有那两个业务仓"

还有一条，是关于未验证的

交接文档里有说明「本轮没验过的维度」：长路径、大 KB 性能、并发落盘、 真 MCP 客户端联调、push 到真远端、PowerShell 文本管道、生成的 CI 真实执行。

它具体在哪：collab-cli/working-memory/tasks/2026-09-26-session-handoff.md §3.4。 本行原先只说"交接文档里有说明"、没给路径 —— 而 KB 的 AGENTS.md 又明写 "本仓没有 working-memory/，别去找"，于是读者在 KB 里翻不到、也不知道该去哪个仓找。 这是"引用不指向"的一种：不是路径写错，是根本没有路径。

后来怎么样了（2026-09-26 晚补记）：7 条里 3 条变成了测试 （collab-cli/src/cli/commands/__tests__/robustness.test.ts：空格与中文路径、 400 条 KB 的时间预算、并发 apply 不半写）；Windows 长路径（>260）仍未验； 剩下 4 条需要外部环境 —— 而"生成的 CI 真实执行"当天就被撞上了： 两个仓的 CI 从来没跑起来过（npm ci 配 pnpm 锁文件；collab-cli 38 次全红、 KB 的 Validate 11 连红）。修完当天就绿了（那次是 collab-cli 历史上第一次绿）； 而且它绿之前先做了件更有用的事：抓到一条本地永远抓不到的缺陷（见上表 H）。

十一、它现在是什么状态（可安装的部分）

@chahuajia/collab-cli —— 能用、有证据，但还没被第二个项目验证过。

npx --yes @chahuajia/collab-cli --version                 # 先看装到的是哪个版本
npx --yes @chahuajia/collab-cli --dir <你的知识库> validate

这里故意不写版本号 —— 写死的版本号在你读到它的时候已经过期了，--version 打印的才是真的。 但有一条要记住：parse 的粘贴协议换过（块边界从 ===== FILE: 分隔符改成条目自描述的 frontmatter）。旧版（0.5.x 及以前）对同一份 AI 输出会整单拒收 —— 装之前先看版本。

为什么不是 1.0：核心命令稳定（测试全绿 + "跳过必须申报"的门禁）， 但"读了到底有没有用"至今不可判定——唯一干净的对照实验测出零差异。 版本号里应当写着这件事。 （要当前测试数就自己跑 pnpm run test:ci —— 本文不抄。）

三条接入通道（MCP 只是其中一条）

通道适合谁代价
MCP支持 MCP 的客户端（Codex / Claude / Cursor）注册一次
CLI 直调有 shell 的 agent无
粘贴协议无 IO 的聊天窗口人工粘一次
codex mcp add collab -- node <repo>/bin/collab.js mcp --dir <你的知识库>

MCP 只暴露 6 个只读工具（catalog / read / search / validate / parse / apply_plan）—— 没有 commit / push。

因为："AI 不 commit、不 push"不是写在文档里的叮嘱，而是工具表里不存在那一项。

它适合接在哪

一个 MCP server 指向唯一一个知识库，所有项目共用 —— 项目侧不需要各建一份 KB。 （真的需要独立 KB 时才 init --profile kb；多数情况是 fork，不是 init。）

整套东西 —— 包括上面每一个失败 —— 都在仓库里：

npx --yes @chahuajia/collab-cli --dir <你的知识库> validate

想搬走的话，从两本账本和一扇会红的门开始，不要从 129 条开始。

关于维护：先说清楚

这个项目我大概不会再继续维护了（个人原因）。但它不是"半成品被丢下"：

  • 它的自我检查都在机器里 —— 你 fork 之后，collab validate 与 CI 会告诉你这套东西在你那儿还跑不跑得动；
  • 它最值钱的部分（两本账本 + 入库门槛 + 那根会亮的线）本来就不依赖作者在不在：抄走就能用。

发出来是抛砖引玉 —— 批评、指导、fork、拆开各用一半，都欢迎。 （我可能不会及时回 issue，这句也说在前面。）

顺手记两个有意思的项目（同名不同物）

写这篇文章时撞见的，放在这里以免混淆：

  1. Codex、Obsidian、Zotero 联动的论文库工作流（视频）： www.bilibili.com/video/BV17F…
  2. yinsang0910-star/collab-cli —— "Universal collaboration protocol + CLI for multi-agent LLM teams"。

关于第 2 个顺便解释一件事：collab-cli 这个 npm 名字是他们的（collab-cli@1.6.x）， 所以我这边的包名带作用域：@chahuajia/collab-cli —— 看到两个"collab-cli"时不用困惑。 两个项目同名但不同路：他们做多 agent 团队的协作协议 / CLI， 我这里做一个知识库的校验、修剪与门禁。

avatar
文章
阅读
粉丝