DEEPSEEK HARNESS · MAINTENANCE · 0.1.11
维护承诺:这些包会被怎么对待
一个陌生人决定用你的工具时,问的不是「它能做什么」,而是「它明年还在不在」。这份文档回答后者。写它的人只有一个,所以里面关于风险的部分是实话,不是免责声明。
适用于 dsh-vertical-kit、dsh-verify-kit 和 dsh-review-outbox 下的全部 26 个包。
版本怎么走
0.1.x 阶段:次版本号表示可能破坏。在这个阶段我不会假装 semver 的稳定性——一个检查器的规则变严,输出就会变,那对下游是破坏性的,即使函数签名没动。
进入 1.0.0 的条件是三条同时成立:
- 规则集合稳定:连续两个版本没有新增 error 级规则(新增 warn 不算破坏,因为 warn 不改变出口码);
- 出口码语义冻结:
0干净 /1有发现 /2用法或读文件错误,这三个数字不再变; - 至少有一个外部使用者报告过它接进了 CI。
在那之前,升级方式是看 CHANGELOG 的「规则变化」一节,不是看版本号大小。
什么算破坏性变更
按影响排序,从最痛到最轻:
| 变更 | 破坏性 | 为什么 |
|---|---|---|
| 出口码语义改变 | 是 | CI 靠它判断 |
| 已有规则新增 error 级判定 | 是 | 昨天通过的文档今天失败 |
| 规则改名 | 是 | 按 rule 名字过滤的用户会静默漏掉 |
| 新增 warn 级规则 | 否 | 不改出口码,只看人读的输出 |
| 新增可选参数 | 否 | 默认行为不变 |
| 报告措辞改变 | 否 | 但会影响按文本匹配的用户,所以 CHANGELOG 里逐条列 |
规则变动一律写进 CHANGELOG 的「规则变化」表,包括哪条规则从 warn 升到 error、为什么。dsh-outline-lint 0.1.3 就是这么做的:结论规则收窄到报告类交付物,因为原来的域外误报让参考手册也失败。
规则改动的原则
一个检查器的价值在于它能被判定的部分可靠,不在于它抓得多。所以:
- 宁可漏,不可误报。 一条误报会让人关掉整个工具;漏报只是让人少省一次事。
- 域外误报必须发版修正,并且写清边界。
outline-lint的 README 现在写着「结论规则针对报告类交付物,参考文档不在域内」——这句话是修 bug 的产物,不是事后装饰。 - 启发式必须公开。
env-example-check认的占位符形态、spec-doc-check的愿望词表、license-check的 12 种许可证指纹,全部写在 README 里。基于启发式的检查如果把启发式藏起来,就是让人猜。
弃用怎么做
包被弃用(不再维护但不删)时:
- npm 上发一个次版本,README 顶部加一段
> **Deprecated.** 原因 … 取代方案 …; package.json加"deprecated"字段(npm 会在安装时显示);- 目录条目保留,不主动删除——删掉会让已经装了的人找不到文档;
- CHANGELOG 写清最后一个可用版本。
不删包、不改已发布版本的 tarball、不 unpublish。
如果我不再维护
只有一个维护者,这是真实风险,写清楚比藏着好。
已经成立的事实(不依赖我继续存在):
- 26 个包全部 MIT,源码在 GitHub,已发布的 tarball 在 npm 上永久可取;
- 每个检查器不联网判定、不调模型、无运行时依赖,只要 Node 22.19+ 在,
npx就能跑; - 规则全部在源码里,是纯函数,没有服务端、没有密钥、没有需要续期的证书;
- 站点是静态页,跑在 GitHub Pages 上;
- 测试是
node --test,不需要我的环境。
也就是说:代码可以死,工具不会。 一个不再更新的检查器仍然是它发布那天的那个检查器。
如果我消失:欢迎 fork。三件事值得先做——把 author/repository 字段改成你的、把站点的 ORIGIN 改成你的域名、跑一遍 npm test 确认基線。不需要我的许可,MIT 已经给了。
响应预期
现实:这是一个人的项目,没有 SLA,没有值班。下面是我会做的事,不是承诺:
| 情况 | 我的处理 |
|---|---|
| 误报(你的文件没问题却报错) | 最高优先。规则误报比漏报伤,会修 |
| 安装/构建失败 | 优先,通常是我漏了某个 Node 版本的差异 |
| 规则建议(想加一条判定) | 看它是否可从文件本身判定;需要判断力的不做 |
| 「能不能支持格式 X」 | 看有没有真实样本;没有样本的格式支持是猜 |
不做的:不做需要联网或调模型的判定;不做「建议怎么改」,只报「哪一行不符合哪条规则」;不为了抓得多而放宽误报。
怎么判断这些数字可信
这个项目自己的下载数不能当作采用证据——/reading-downloads/ 那页记着原因:26 个包的尾部速率落在彼此的 19% 以内,而目录头部跨 30 倍;均匀性是按作者批量拉取的特征,不是受众的特征。
唯一当作采用信号的是人工决策数(有人读完一份成果、写下证据、点了通过),以及验收单摘要可核对(导出的单子带 SHA-256,文件改动后同一份单子会提示重审)。
两者都不能自动化,也都不能靠下载刷出来。
原文:docs/MAINTENANCE.md