DEEPSEEK HARNESS · DECISION LOG · 0.1.11

决策记录

三条已经生效的决策。选这三条是因为它们都付出过代价:一条让下载数字变得不好看,一条让采纳指标长期停在 0,一条在落地当天推翻了自己四个包的结论。只写收益的决策记录是广告,所以每条都写了代价和当时被否掉的方案。

ADR-0001 每条检查规则必须在测试里被观察到两个方向

状态:已接受 日期:2026-11-19

背景

2026-11-19,把 vertical-kit 的二十个检查逐个指向本项目自己真的在发的文件。四个包报错了,而且都是同一个形状:规则对一切合法文档报错。

这四个包的单元测试全绿。原因是同一个:每条规则只在「坏文档让它报」这个方向被断言过,从来没有一条测试说「这是一份好文档,它必须什么都不报」。

决定

每条规则必须有两条测试:一条让坏文档触发它,一条让好文档不触发它。这条要求由 dsh-vertical-kit/scripts/audit-rules.mjs 自动执行,接在 npm run check 里,覆盖失败即阻断。

「不触发」的判定接受两种证据:一是针对该规则的否定断言(!findings.some(f => f.rule === 'x')),二是包级别的干净用例(deepEqual(findings, [])、errors, 0、ok, true),后者一次性覆盖全部规则。

后果

好处:

代价:

备选方案

备注

两条一起用:审计保证"每条规则双向有测试",dogfood 保证"真实文档上零报错"。前者管形状,后者管事实。


ADR-0002 下载量只读成底噪带,不读成用户数

状态:已接受 日期:2026-11-18

背景

本项目发布 26 个包之后,周下载数落在 1,755–1,997 之间。这个数字看起来像"有一千多人在用",值得先确认它是不是真的。

做法是把目录里所有条目的日下载序列拉下来,按形状分类。结果分三类:

关键的一步是离散度检查:如果多个包的日序列两两之间高度相关,它们就不是多群独立用户,而是一个客户端在按固定节奏请求。本项目的九个包尾巴是 117/119/121/122/164/171/178/180,变异系数 0.186;作为对照,目录头部十二个条目两两相关的中位数是 0.299,变异系数 1.617,只有 12.1% 的配对相关系数 ≥0.5。

决定

周下载数不解释为用户数。本项目自报的口径是:

  1. 停在底噪带的条目不算有人装,无论周数字是三位还是四位。
  2. 一个包的下载曲线如果和同作者其他包的高度同步(变异系数 < 0.25),按单一自动化客户端计算一次,不按包数累加。
  3. 真正的采纳指标不取下载量,取被人审阅并处置过的成果数(pending 队列里人类决策的条数)。这个数现在是 0。

后果

好处:

代价:

备选方案

备注

这条决策的检验方式是反向的:任何人可以对目录头部跑同一个脚本,如果头部也呈现出同样的高同步性,说明 0.25 这个阈值把真实用户也判成了机器人,结论要推翻。


ADR-0003 pending 队列不做批量处置,哪怕它会显示成零进展

状态:已接受 日期:2026-11-17

背景

review-outbox 有一个 pending 队列:成果交进来等人看,人看完处置(接受、打回、留意见)。当前状态是 99 条待处置,最老的一条 56 天,中位数 12 天,其中 47 条来自一个与本项目无关的项目。

北极星指标定的是"每周被真正审阅并处置的成果数"。围绕这 99 条,有两条被反复提出的捷径:

  1. 加一个 --approve-all,把队列清空,指标立刻从 0 变成 99。
  2. 把老条目批量标成 expired,让队列回到个位数,看起来健康。

这两条都能让面板好看,且都能自动化。

决定

不做批量处置,也不加 --approve-all。scripts/pending-triage.mjs 只做一件事:把 99 条按项目分组,让人能一次处理一批同类成果。它是只读的,没有任何写回路径,也不接受 --approve。

指标就保持 0,直到真的有人看。

后果

好处:

代价:

备选方案

备注

这条决策不是关于产品功能的,是关于指标能不能被自己污染的。一旦实现者可以随时清空分母,指标就只剩装饰作用。

原文:docs/adr/ · 每条都由 dsh-adr-check 校验(状态、背景、决定、含代价的后果、备选方案、日期),校验本身也在这份记录里(ADR-0001)。