Signoff

落印 / SignOff

包名 4.0.0 起为 `signoff-cli`（曾用名 dsh-signoff，旧包已标记 deprecated）。

命令仍是 signoff；仓库地址仍是 ayuanxx-max/signoff-cli。DSH 只是它最早的使用场景，

任意 git 仓库、任意语言都可以直接用。

中文名「落印」：印落纸面才算数，对应英文名 SignOff。曾用名「一诺过五关」「执印」。命令是 signoff；

包名 4.0.0 起为 signoff-cli，仓库 4.1.0 起为 ayuanxx-max/signoff-cli（由 dsh-signoff 改名，老地址 301）。

签下的那句“做完了”，得自己走过五道关才算数。

五道关卡，五条命令，退出码即判决；发版另加第六道 signoff release（见文末）。每一关都对应 agent 交付时的一种失败方式：靠记忆跑测试、把“有开发页”当验证、多个 agent 撞同一文件、危险动作做过就忘、文档里塞空话。SignOff 把这五种失败变成五个可执行的检查。

npm i -g signoff-cli      # 或 npx signoff-cli

signoff p1 # 一关一关过 signoff all # p1 + p2 + p5 + p4 verify

一张图看懂

六个层次从左到右：入口（CLI / git 钩子 / CI / Agent 面）都走同一个 guard.js；调度决定跑哪几关、 谁算通过；五关每关都写清“读什么、判什么、怎么修”；状态机说明一次提交里 marker 与 trailer 是怎么产生的； 产物是判断留下的证据；最右是外部依赖——只有 Node ≥18 与 git 是硬要求，其余都可缺。 判定没有“部分通过”：退出码 0 通过、1 任一关判红、2 用法或环境错。

上半部分按 0→5 的先后排：前置检查 → 安装 → 初始化 → 日常提交 → 红了怎么办 → 升级与卸载。 红框是必做，黄框是最容易踩的坑（--chain、--lock-test、npm proxy）。 下半部分三块是“不改你的流程、但会改变你看到的现象”：平台差异、环境差异，以及三条红线 （--no-verify、SIGNOFF_SKIP=1、调阈值让红变绿）。

两张图都由 Mermaid 生成，源文件在 docs/diagrams/src/，改文案重渲一次即可， 不用重画。

零接触：装一次，之后不用管

目标是一条命令之后不再需要任何操作：npm i -g signoff-cli 装完即生效，之后每次 git commit 都自动受五关约束。

npm i -g signoff-cli      # 一次；postinstall 自动装好机器层 + 当前仓库

signoff ensure # 换个仓库想把五关都装上，跑这一条（幂等） signoff ensure --global # 只重装/修复机器层 signoff ensure --json # 给脚本看的结构化结果

npm 11 会把 postinstall 放进 allowlist 提示，可能不执行——所以还有一层兜底：在该仓库里第一次跑任何一关（比如 signoff p5 README.md）会自动把五关装好。 要放行安装脚本就加 npm i -g signoff-cli --allow-scripts=signoff-cli。

行为约定：

• 已 opt-in（有 .signoff/config.json）：pre-commit 跑全套五关，PASS 才写 marker 和 trailer。
• 未 opt-in：只跑 P1（有测试才跑，没测试就明说"没检测到测试运行器"后放行），不写 .signoff 配置、不带 trailer。
• 仓库自带的钩子不会被绕过：机器层先执行 .git/hooks/ ，它若是 signoff 的钩子就直接以它的判决为准。
• 提交 signoff.json 等于「这个仓库同意 P1–P5」：.signoff/ 是 gitignore 的，声明文件进 git， 所以别人克隆下来第一次 commit 就会把 hooks / config / CI 自己补上。字段见 docs/signoff.schema.json。
• 临时退出：SIGNOFF_NO_BOOTSTRAP=1（不做自动安装）、SIGNOFF_NO_MACHINE=1（不跑机器层的轻量关）。
• 撤销机器层：signoff uninstall --global。

一、案例：本次 DSH 2.0.22-next升级后在修复（dsh-session-fork-tree 0.9.34）bug里，五关各自做了什么？

这次修的是“升级 DSH 后，点侧栏「···」菜单，菜单闪一下就消失”。五关实际起了什么作用，逐条列出，包括没发挥作用的那一关。

一句话：P2 决定“修好没有”，P5 决定“我有没有说大话”，P1 只证明没弄坏别处，P4 事后抓住了我自己的一笔脏账，P3 全程没上场。 这个结论本身就是 SignOff 想要的输出：每一关都要能回答“发挥了没有”，不能只说“流程走过了”。

你不需要做什么，照常进行任务，由它来守护这个过程；

二、自动守护：装一次，之后不用记

signoff init 把五关接进 git 与 CI，一次安装，之后正常 git commit / git push / 开 PR 都由它先查：

只依赖 Node 18+：闸门本身是 Node 实现（lib/p*.js），没有 Python 也能跑完整五关，不存在降级模式。

三条稳定性措施：同一份暂存内容只判一次（命中缓存约 0 ms，反复 git commit --amend 不重复付时间）；失败只打印失败那一关的尾部（完整日志在 .signoff/hook.log）；超预算直接判红（默认 180 秒，--budget 可改）。

绕过的路仍然有，但不再无痕：signoff audit --range origin/main..HEAD 逐个提交核对标记与提交树——缺失就是绕过（git commit --no-verify），判红；SIGNOFF_SKIP=1 的提交写成 Signoff-Skip: 并记进 .signoff/skips.log，--strict 下同样判红。生成的 CI 里已经带这一步。

队友为什么也会被守住：先把 signoff-cli 放进 devDependencies（npm i -D signoff-cli），再 signoff init --prepare，它会把 signoff init --quiet 并进 package.json 的 prepare，队友 npm install 完钩子就有了。没这个依赖时 --prepare 会拒绝写入并提示——否则 npm install 会因为找不到 CLI 直接失败。

signoff init                 # 装钩子 + CI + 配置

signoff init --chain # 已有钩子保留：存为 .local，先跑它 signoff init --prepare # 同时写进 package.json，队友 npm install 即装钩子 signoff status # 这个仓库现在守不守？ signoff doctor # 为什么没按预期生效（只读） signoff doctor --fix # 让它把能证明的修掉：重装缺失钩子、补执行位、清掉没暂存的标记 signoff guard --full # 手动跑同一套（钩子调的就是它） signoff audit --range origin/main..HEAD # 这些提交真过过闸门吗？ signoff audit --since-install # 只看装钩子之后的提交（安装点不在 HEAD 祖先里会直接拒绝） signoff init --reset-install # 历史被改写或换了克隆后，把安装点挪到当前 HEAD signoff init --lock-test # 把识别到的测试命令写进配置，换机器不再漂移 signoff uninstall --all # 卸掉钩子 + CI + 配置 signoff uninstall --keep-config # 卸掉钩子 + CI + 运行时状态，保留配置与账本 signoff p4 export --merge ../other/.signoff/audit.log # 多仓库合并成一张表 signoff p4 export --format json --out ledger.json # 也可以导出 json / csv signoff explain p2 # 这一关到底查什么、怎么判的 signoff secrets # 只扫暂存区的密钥泄露（钩子里自动先跑） signoff secrets --all --json # 全仓库扫一遍，一条 JSON 判决

密钥扫描与提速（3.12.0 起）

• P1 之前先扫密钥：内置 16 条高信号规则（AWS / GitHub / GitLab / OpenAI / Google / Slack / Stripe / npm / SendGrid / 私钥块 / Azure / Discord webhook / 带密码的数据库 URL / 通用凭证）。 命中即失败；装了 gitleaks 可用 --engine gitleaks 换全套规则，没装也不影响（纯 Node，无需二进制）。
• 值不会原样打印：只显示 AKIA…EF 这种前缀 + 规则名 + 行号，避免把日志变成二次泄露。放行写在 .signoff/config.json 的 secrets.allow。
• 未 opt-in 的仓库也扫：机器层守护走 --no-state，扫完不留任何文件。
• 运行器探测扩了 9 种：go / cargo / maven / gradle / dotnet / ruby / elixir / php / make（tests/ 与 package.json 仍在最前）。
• 同一暂存树结果缓存：重复跑 0 ms；纯文档提交跳过测试。两个开关都可关：SIGNOFF_NO_CACHE=1 / SIGNOFF_NO_FAST=1。

签名与增量覆盖率（3.13.0 起）

• 提交自带签名：signoff init --sign 生成仓库本地 ed25519 密钥，commit-msg 在 Signoff-Pass: 之外再写 Signoff-Key: + Signoff-Sig:（对完整 tree 签名，单行 base64）。没有密钥就只写未签名的 Signoff-Pass，不阻塞提交。
• 可以复核：signoff audit --verify 逐个提交验签，--require-signed 把未签名也算失败。身份锚点是 仓库里提交的 .signoff/allowed_signers（或 signoff.json 的 allowed_signers）：不在名单里只报 self-signed，绝不报 verified。
• 增量行覆盖率：signoff cov --diff --min 80 只算这次改动新增的行，读项目已有的 coverage/lcov.info / coverage-final.json / python coverage json，不额外装运行器；没有覆盖率文件时报"没测过"，不会假装通过。
• CI 直接标到行：GITHUB_ACTIONS=true 时，密钥/覆盖率发现输出 ::error file=…,line=… 注解并写步骤摘要， PR 页面直接看到，不用翻日志。

可核对的凭证（3.15.0 起）

signoff p4 checkpoint 给账本签一个检查点，signoff p4 anchor 打出一行可以贴到发版说明里的锚点：

signoff1:12:9f2c1ab34d0e:71b0c9d2e4a85f61

事后 signoff p4 verify --checkpoint --anchor <那一行> 能分辨四种情况：账本被截断、内容被改、 签名不属于受信 key、锚点与本机不一致。细节与边界（它不证明什么）见 docs/trust.md。

3.15.2 起还补了三件事：signoff p4 path 打印账本与检查点的真实位置（脚本不用猜）； guard 通过后自动续签检查点（同一份账本不重复签，不产生无意义改动）；账本读取容忍 BOM （Windows 编辑器与 Set-Content -Encoding utf8 的常见产物）。

能力矩阵与匿名竞品（3.15.2）

同一张表看"谁有什么"。竞品按类型匿名（不点名，避免把对比写成广告），对应关系与星标/下载数据 记录在 docs/signoff-positioning-3.15.2.md。

结论放在表后面而不是前面：前七行是它和其他工具的分野，最后两行是它的短板——托管面没有， 生态采用量也还没起来（1 star、周下载三位数），所以六维里"生态"给 3 分，不是 5 分。

上图是一次提交的完整路径：入口（git commit / 命令 / CI）→ 三层零接触 → guard 固定顺序跑 secrets → p5 → p1 → p2 → p4 → cov（opt-in）→ 判决 → 四层证据（marker → trailer → 账本 → 检查点 → 锚点）。红一关即停，退出码就是判决。

上图横轴是生态采用度，纵轴是覆盖广度。落印落在左上角——功能全、采用低，这是它的真实位置： 它不在右上角跟平台级产品比采用，差异在"判决可以带走、可以事后核对"。

规则包、预设与编辑器（3.14.0 起）

• P5 规则包：--pack zh|en|both。中文词表是默认值，行为不变；en 用词边界匹配 （very 不会命中 delivery），both 两套一起跑并按行去重。--rules rules.json 追加自定义词表 （ai_words / absolute / adverbs / claims / placeholder），也可写进 .signoff/config.json 的 p5 或 signoff.json 的 p5。
• 场景预设：signoff init --preset node|python|go|java，一次给出预算、文档目录、覆盖率阈值和规则包； test_cmd 仍交给自动探测，克隆到没有该脚本的机器也不会锁死。
• VS Code：signoff init --editor vscode 写 .vscode/tasks.json（guard / all / secrets / cov / audit / status） 与 problem matcher，失败直接落到 Problems 面板；已存在的任务只合并不覆盖。

三、在其它代码过程里能干什么

四、在 DSH 任务里能干什么

• 发 npm / 改 profile / 改 cordis 配置：P4 先 ask 取票（单次、10 分钟过期、绑定动作类别），再 confirm 落账，账里带回滚点；回滚点必须是真的 git ref，写一句“npm deprecate …”会被 verify 拒绝。
• 插件发版：P1 跑三套真实 DOM fixture，P2 把结果记进覆盖率表，P5 保证发布说明里没有绝对化的收尾句。
• 长任务 / 跨天任务：P3 的卡片就是断点续传的凭据——scope、验收、回滚点三样齐了，换会话也能接上。
• 多分叉并行：不同分叉各拿一张卡，plan 先算出不会撞文件的波次，避免两个 agent 同时改同一处。
• 收尾：P5 的六条规则让“完成”这句话可以被机器反驳：无数字的已验证、TODO、绝对化断言、AI 味词表（赋能 / 闭环 / 抓手…），命中即失败。
• 插件回归：verify/scenarios/*.json 是 P2 的输入格式，把 fixture 的 checks 数量直接变成覆盖率数字，不需要另写报表。

五、命令速查

# 自动守护：装一次，之后不用记

signoff init signoff status signoff guard --full signoff uninstall --all

P1：跑检查；默认 tests/ 用 pytest，否则 npm test

signoff p1 --run "pytest -q" --run "npm run lint" --budget 120 signoff p1 --install-hook # 写入 .git/hooks/pre-commit

P2：覆盖分级 + 阈值

signoff p2 --strict --min-scenario 4 --min-assertions 60 --md docs/coverage.md

P3：卡片校验 / 波次规划 / 收集核对

signoff p3 validate --