完工证据门禁 rrrrrredy/beforedone

BeforeDone

确认你的检查是否仍然匹配代码。

BeforeDone 会运行你已有的验证命令，并记录这些命令检查了哪些文件。编码智能体结束工作前，BeforeDone 会检查这些结果是否仍然适用于当前的工作。先从命令行开始；想让完成检查自动运行，再接入智能体集成。调查失败的运行时，可以用事件报告和回放。

任务在验证之后还会继续，或者你想复用之前的结果、不想重跑开销大的检查时，它最有用。如果你的常规测试和 CI 工作流已经能说明这一点，这个额外工具带来的帮助可能不大。BeforeDone 跟踪的是配置好的验证；挑选能覆盖任务的检查，仍然是开发工作的一部分。

网站与指南

环境要求

- 一个 Git 仓库。BeforeDone 通过 Git 解析本地运行时。
- 文件系统要支持 Git 目录的同目录硬链接；在 Windows 上，把仓库放在 NTFS 上，不要放在 FAT/exFAT 可移动介质上。
- .beforedone.yaml 中指定的验证程序，例如 go、npm 或 pytest。
- 只有使用 Plugin、独立 Skills 或项目本地钩子时，才需要 Codex。
- 只有使用 dsh-beforedone 社区 Bundle 时，才需要 DeepSeek Harness 0.1.0-rc.6 和 Node.js 22.19+ 或 24+。
- 只有使用 Pi 集成时，才需要当前版本的 Pi，且要暴露 agent_settled、pi.exec、pi.appendEntry 和 pi.sendUserMessage。

1. 安装命令行

已安装 Go 时：

go install github.com/rrrrrredy/beforedone/cmd/beforedone@latest
beforedone version

也可以从 GitHub Releases 下载 Windows、macOS 或 Linux 的压缩包，用 checksums.txt 校验，再把 beforedone 可执行文件放到 PATH 上。

要用 Go 安装可复现的版本，把 @latest 换成发布标签，例如 @v1.1.1。

2. 初始化仓库

基于命令的初始化在开发源码中可用。下个版本发布前，先这样安装：

go install github.com/rrrrrredy/beforedone/cmd/beforedone@main

然后在目标 Git 仓库里接入已有的项目命令。以 Python 项目为例：

beforedone init --files "src//.py" --files "tests//" --files "pyproject.toml" -- python -m pytest
beforedone doctor

已发布的 v1.1.1 命令行可以用 beforedone init，再手动编辑生成的 YAML。它不接受新的初始化选项。

-- 之后的所有内容都会保存为 test 检查的 argv；初始化不会运行它。把 BeforeDone 的选项（包括 --json）放在 -- 之前。命令用到的输入，用 --files 重复指定。不写 --files 时，自定义命令默认使用 /；如果这个范围包含生成产物或已安装的依赖，就把它收窄。路径和命令都相对于仓库根目录。
init 会创建 .beforedone.yaml，并在 .git/beforedone 下生成本地运行时数据。裸跑 beforedone init 保持原有行为，可以重复执行，不会覆盖有效配置。如果配置已存在，要改命令或文件范围就手动编辑它；初始化选项不会覆盖已有配置。

跑检查之前，先审一遍生成的配置。命令是 argv 数组，不是 shell 命令字符串：

schema_version: 1
checks:
test:
argv: ["go", "test", "./..."]
relevant_files: ["/.go", "go.mod", "go.sum"]
working_directory: "."
timeout_seconds: 600
required: true
capture:
max_output_bytes: 1048576
redact_patterns:
- '(?i)(api[_-]?key|token|password|secret)\s[:=]\s[^\s]+'
reports:
retain: 20

选择可信的检查

新生成的 Receipt 只能证明：配置好的验证器对声明的文件跑通了。它不能证明验证器覆盖了每一条验收标准。用户不必诊断出确切的 bug，但任务仍然需要可观察的验收标准，以及一条能测这些标准的可信命令。

beforedone init 只是起点，不是自动测试设计器。它能识别 Go module，并提议 go test ./...；对其他仓库，它默认的 git status --short 只是脚手架，不能当作正确性证明。先审一遍现有的测试、构建、lint、类型检查、包脚本和 CI 命令，然后保留最小的一组，只要这组能可信地覆盖任务。如果覆盖有缺口，且改动在范围内，就补一条针对性的回归测试；否则把未覆盖的标准报告为未验证。

建议的 Codex 提示词

给仓库配置一次：

Connect this repository's existing verification command to BeforeDone. Reuse
the project's normal checks and include their source, tests, fixtures, and build
inputs in relevant_files. Use command-based init if supported by the installed
CLI; otherwise edit the generated YAML. Keep the setup small and explain any
task requirement the existing checks do not cover.

验证一个任务：

Use BeforeDone for this task. Run affected configured checks through BeforeDone
and reuse results that still match the files. At handoff, use one gate result
to confirm all required checks. Inspect individual receipts only if needed.
Report any acceptance criterion the configured checks do not cover.

这些提示词帮 Codex 提出并落实验证契约；它们不会把自然语言的信心变成 Receipt。依赖 .beforedone.yaml 之前，先审一遍。

不要把凭据放进验证器的命令行参数，也不要把敏感名称放进验证器路径。证据 receipt 会有意保留实际的 argv 和工作目录元数据，好让审阅者看到跑了什么；这些结构字段不会被输出脱敏改写。改用基于环境变量或原生的凭据机制，分享 receipt/report 元数据之前先审一遍。

日常工作流

通过 BeforeDone 运行受影响检查，然后确认完成：

beforedone check test
beforedone gate

gate 会列出每项必需检查的判定结果和新鲜度，但不运行验证器。如果之前的结果可能仍然适用，先运行 gate，只重跑需要新鲜证据的检查。检查文件范围之外的改动不需要重复该检查。

启用的智能体集成会自动提供最终 gate。走这条路线时，单独手动跑 gate 是可选的。查看 receipt 是为了获取细节或诊断，而不是每次检查后额外加的一步：

beforedone receipt test
beforedone gate --json

gate 同时返回 decision 和证据 verdict。必需证据缺失、失败、无效或过期，都会阻止完成。验证器 receipt 本身为 INCONCLUSIVE 时，保留现有的非阻塞警告行为：decision 为 allow，verdict 和进程退出码仍为 INCONCLUSIVE，由 system_message 说明不确定性。适配器必须读取 decision，不能只凭退出码推断。

进程成功时，会为当前相关文件指纹生成 PASS receipt。改动相关文件会让该 receipt 过期；改动检查配置模式之外的文件则不会。普通命令输出里的 PASS 字样，永远不能覆盖非零的进程退出码。

相关 glob 也会包含匹配的 Git 忽略文件，例如生成的 Go 源码，指纹还会包含可执行权限的变更。Git 在 BeforeDone 流式输出结果之前应用忽略文件路径规范，并设有硬性的文件数、列表大小和内容大小限制；超出限制时按失败处理（fail closed），而不是悄悄省略证据。v1 不对子模块内容计算指纹：如果 relevant_files 模式可能覆盖 Git 子模块或其下的路径，检查会按失败处理，不签发可复用的证据。

前瞻性研究计划和演化账本属于创建它们的研究、记忆或运行时演化系统。它们不会创建或刷新 Completion Receipt。BeforeDone 只负责最终配置的检查和当前相关文件指纹；参见演化研究边界。

一个产品，五种交付形态

- 命令行： 检查、receipt、incident、replay 和适配器校验的事实来源。
- Codex Git Marketplace 插件： 自动化的体验。它打包 Stop 钩子和两个 BeforeDone 技能，同时把所有证据决策交给命令行。
- 独立技能包： 同样的两个工作流，但不带生命周期钩子或 Stop 强制。
- DeepSeek Harness 社区 Bundle： 原生会话事件捕获，加上完成前 gate 和一次有界的纠正性续跑。
- 项目本地 Pi 扩展： 有界的 Pi 生命周期捕获，加上结算后的证据决策和一次纠正性续跑。
命令行工具是每个安装场景的必备项。Codex 需要从下面三条集成路线中只选一条：

1. 插件：提供钩子，外加两个内置技能；
2. 独立技能包：走手动工作流；
3. 用 beforedone setup codex 生成项目本地钩子，获得自动门禁，无需安装插件。

不要在同一个 Codex 环境里混用这些路线。插件加独立技能包会让工作流重复；插件加项目本地钩子会把生命周期集成跑两遍。

Pi 用 beforedone setup pi。不要在同一个 Pi 运行时里再加载一份生成的扩展。

DeepSeek Harness 把 dsh-beforedone 装进选定的配置档。不要在同一会话里再搭配其他 BeforeDone 生命周期适配器。

3. 选择智能体集成方式

路线 A：Codex Git Marketplace 插件

Git Marketplace 插件包含 Stop Hook 和两个技能。先安装命令行工具，再添加公开的 Git marketplace：

codex plugin marketplace add rrrrrredy/beforedone

重启 ChatGPT 桌面应用，在 Codex 里打开 Plugins Directory，选择 beforedone marketplace 源，打开 BeforeDone，点 Install。然后打开 /hooks，检查并信任 BeforeDone 的钩子，再新建一个任务，内置技能才会生效。插件不会静默下载或更新命令行工具；可执行文件缺失时会给出可操作的报错。

更新这条路线：

go install github.com/rrrrrredy/beforedone/cmd/beforedone@latest
codex plugin marketplace upgrade beforedone

然后在 Codex Plugins Directory 里打开 BeforeDone，应用它提供的更新。如果该界面不提供原地更新，就从刷新后的 marketplace 卸载插件再重新安装。

移除这条路线：在 Codex Plugins Directory 里打开 BeforeDone，选 Uninstall plugin。如果连仓库 marketplace 也不再需要，单独移除该源：

codex plugin marketplace remove beforedone

移除 marketplace 源不能代替在 Plugins Directory 里卸载插件。

路线 B：独立技能包

选这条路线，不要选插件。它安装同样的工作流，但无法观察生命周期事件，也无法强制执行 Stop Gate。

让 Codex 对每个精确路径各运行一次内置技能安装器：

$skill-installer install https://github.com/rrrrrredy/beforedone/tree/main/skills/verify-before-done

$skill-installer install https://github.com/rrrrrredy/beforedone/tree/main/skills/investigate-agent-incident

技能会在下一轮 Codex 对话中生效。要固定到 v1.1.1，把两个 URL 里的 /tree/main/ 换成 /tree/v1.1.1/。

也可以通过第三方 skills.sh 命令行工具安装这两个技能。BeforeDone 本身没有遥测，但 skills.sh 是独立工具，可能收集自己的使用数据。需要的话，显式关掉该安装器的遥测：

sh
DISABLE_TELEMETRY=1 npx skills add rrrrrredy/beforedone --skill verify-before-done --skill investigate-agent-incident --agent codex --global --yes

PowerShell： powershell $env:DISABLE_TELEMETRY = '1'
npx skills add rrrrrredy/beforedone --skill verify-before-done --skill investigate-agent-incident --agent codex --global --yes
Remove-Item Env:DISABLE_TELEMETRY

要更新由 $skill-installer 安装的技能，只需从 $CODEX_HOME/skills（默认是 ~/.codex/skills）中删除或备份 verify-before-done 和 investigate-agent-incident，重新执行那两条安装提示，然后开启新一轮对话。要卸载这条安装路径，同样只需删除这两个目录。

如果你用的是 skills.sh，后续生命周期管理也继续用它： sh
DISABLE_TELEMETRY=1 npx skills update --global verify-before-done investigate-agent-incident
DISABLE_TELEMETRY=1 npx skills remove --global verify-before-done investigate-agent-incident

路线 C：项目本地的 Codex 钩子

如果你不想用插件，也不想用独立技能，就选这条路线。它会把 BeforeDone 的生命周期处理器写入当前仓库的 .codex/hooks.json，并固定指向安装时找到的 CLI 可执行文件绝对路径： sh beforedone setup codex

打开 /hooks，检查并信任项目钩子，然后开始新任务。如果升级后 CLI 路径变了，重新执行 beforedone setup codex。要移除这些钩子，只删 BeforeDone 的项目钩子： sh beforedone setup codex --remove

DeepSeek Harness：社区 Bundle

先安装 BeforeDone CLI v1.1.1 或更新版本，初始化目标仓库，再把 Bundle 加到你在用的 Harness 配置档： sh
dsh plugin --profile headless add dsh-beforedone@0.1.0
dsh --profile headless --dump-config

Bundle 订阅原生的只追加会话日志，通过 Adapter Kit 输出规范化元数据，并在 agent/turn-stopping 时运行 beforedone gate --json。如果结果是阻断或不安全，就生成一条持久化的引导消息。下一次停止会重新评估，但同一轮对话绝不会被强制超过一次。

提示词文本、推理内容、工具参数和工具输出都不会复制进 .git/beforedone；规范化账本只包含本地会话工作目录、生命周期标识符、消息来源/插件名、工具名和结果状态。CLI 不支持、超时、输出截断、摄入不完整、JSON 损坏，这些情况都会显式报错，而不是悄悄当成成功。

完整的兼容性、配置、测试、隐私和卸载说明见 integrations/deepseek-harness/README.md。这是社区插件，不是 DeepSeek 官方插件。

Pi：项目本地扩展

如果仓库是通过 Pi 使用的，改跑这条命令： sh beforedone setup pi

命令会写入 .pi/extensions/beforedone.ts，并固定指向安装时找到的 BeforeDone 可执行文件绝对路径。检查该文件，批准 Pi 的项目信任提示词，并启动新的 Pi 会话。CLI 路径变化后重新运行 setup；只删除这个生成的扩展，用： sh beforedone setup pi --remove

扩展通过归一化的 Adapter 契约记录 session_start、输入元数据、工具启动/结束、agent_settled 和 session_shutdown。它刻意不持久化提示词文本、工具参数、工具输出或原始转录。它按分支区分的自定义条目最多允许一次自动纠正。交互式或 RPC 输入会重置守卫；扩展发起的输入共用现有守卫。

Pi 在自动重试、压缩和排队续接路径都耗尽后暴露 agent_settled。这让集成适合做纠正性后续动作，但它不等同于 Codex 的完成前 Stop 钩子：第一条不受支持的最终消息可能在 BeforeDone 发送纠正性用户消息之前就已可见。一次重试守卫随后允许下一个 settled 结果，不会造成无限循环。

进阶：事件与回放

从当前仓库证据创建自包含 HTML 报告、机器可读 JSON 和 Replay Case： sh beforedone incident beforedone incident --correction "The parser still mishandles escaped delimiters." beforedone incident --transcript path/to/codex-transcript.jsonl

报告包含时间线、Claim/Evidence Matrix、缺失或过期的证据，以及现有证据支持的最早分歧点。其精度恰好是 exact_event、time_window 或 unlocated 之一。精确事件要求与已验证的失败 Receipt 显式匹配；时间窗口必须由该检查周围观察到的事件界定。通用的非零工具退出和后续用户纠正不会制造位置。BeforeDone 不恢复隐藏推理或思维链。

可选转录是不稳定的叙述上下文，不是信任来源，也不是 First Observable Divergence 的输入。BeforeDone 最多接受 4 MiB，应用脱敏，只存储有界的 16 KiB 叙述摘录及其 SHA-256 摘要和截断标志；它不会把原始转录复制到事件中。

回放分析从不运行外部命令： sh beforedone replay analyze

验证默认也是试运行。它显示仅来自当前仓库配置的计划；导入的 Replay Case 中的 argv 会被忽略： sh beforedone replay verify beforedone replay verify --check test

只有显式 --execute 才会在临时分离的 Git worktree 中运行配置的检查： sh beforedone replay verify --check test --execute

BeforeDone 在创建该内部 worktree 时禁用仓库 Git 钩子。配置的验证器在检出后仍正常运行。

BeforeDone 不提供网络隔离。配置的验证器可以使用该进程可用的网络、凭据和其他资源。Replay 在脱敏和报告截断之前，按配置的 capture.max_output_bytes 上限捕获验证器输出，这样验证器即使没有输出上限，也不会在内存里生成无界结果。

命令与退出码 text beforedone init [--files <pattern>]... [-- <command> [args...]] beforedone doctor beforedone setup codex [--remove] beforedone setup pi [--remove] beforedone check <check-id> beforedone receipt [check-id] beforedone gate beforedone incident [--correction <text>] [--transcript <path>] beforedone replay analyze [replay-case.json] beforedone replay verify [replay-case.json] [--check <id>] [--execute] beforedone adapter ingest [file|-] beforedone adapter test [path] beforedone licenses

给任意公开命令加上 --json，即可输出 schema_version: 1 的机器可读结果。

| 退出码 | 含义 |
| 0 | 命令执行成功，或判定结果为 PASS |
| 1 | 判定结果为 FAIL |
| 2 | 判定结果为 INCONCLUSIVE |
| 64 | 调用或配置错误 |
| 70 | 内部错误 |

beforedone incident 即使成功写出产物，也可能以 1 或 2 退出，因为退出码代表的是该事件证据的判定结果。

本地数据、隐私与保留

.beforedone.yaml 是仓库配置，通常应纳入版本控制。运行时产物放在 .git/beforedone 下，不会污染工作区。这些产物包括：

- 本地 receipt 密钥、receipt、检查日志和 latest 别名；
- 规范化的事件账本，其中只保存有界摘要，不要求保存原始对话记录；
- 事件 JSON、自包含 HTML 报告、Replay Case，以及（如果提供）经过脱敏的有界叙述摘录和对话记录元数据。

BeforeDone 在持久化捕获的检查输出、事件摘要、replay 输出、用户更正和可选的对话记录摘录之前，会应用内置的敏感信息模式、capture.redact_patterns 和大小限制。内置模式覆盖敏感赋值、常见的 OpenAI/GitHub/Slack/Google token 形式、AWS 访问密钥 ID、PEM 私钥块和带凭据的 URI。脱敏只是尽力而为，并不保证万无一失，也无法覆盖所有服务商或编码方式。脱敏不会改写 receipt 的 argv 或路径元数据；绝不要把凭据放进命令行参数，分享产物前请先检查。

新建事件后，reports.retain 会清理较旧的事件目录。在 v1 中，它不会自动清理 receipt、日志或事件账本。要彻底清除本地 BeforeDone 证据，先卸载所选的智能体集成，再检查路径后手动删除 .git/beforedone。只有当仓库不再需要定义 BeforeDone 检查时，才单独删除 .beforedone.yaml。

命令行、插件、Bundle 和技能都不包含 BeforeDone 遥测、托管 API 或云账户。网站和第三方工具的边界另见隐私页面。
安全与信任边界

BeforeDone 用来在协作型或可能出错的智能体完成边界上，抓出缺失或过期的验证器证据。Codex 能拦住第一次 Stop 尝试；DeepSeek Harness 能在回合关闭前请求一次纠正；Pi 能在结算后请求一次纠正。它不是安全边界，挡不住恶意进程——只要该进程拥有相同的操作系统身份和仓库写权限。

这样的进程可以读取或替换 .git/beforedone/receipt.key，编辑 .beforedone.yaml，改动运行时产物，或运行一个轻松通过的允许检查。因此它能伪造出自洽的 PASS。回执签名只能发现受支持工作流内的损坏和不一致产物；它不是远程证明，也不会让同用户的不可信智能体变诚实。

把 BeforeDone 当作可检查的流程护栏。如果智能体本身就在威胁模型内，请使用操作系统隔离、最小权限凭据、受保护的配置，或外部验证器。在敌对环境中依赖回执之前，先读 SECURITY.md。

适配器

v1 规范化事件契约覆盖 SessionStarted、PromptSubmitted、ToolStarted、ToolFinished、AgentStopping 和 SessionEnded。Codex 和 dsh-beforedone 社区 Bundle 是受支持的完成前适配器；beforedone setup pi 提供 Pi 适配器，其 stop_retry 能力意味着结算后继续一次，而不是结算前拦截。公开 schema、fixture 和 beforedone adapter test 命令组成 Adapter Kit，供未来集成使用；它们的存在并不构成对其他智能体的兼容承诺。规范化事件在 JSON 编码后限制为 256 个属性和 1 MiB；本地事件账本一旦超过 64 MiB，读取就按失败关闭处理。如果长期运行的仓库产生大量事件，请在该边界之前审查并轮换账本。v1 写入器在每次追加前重新校验已提交段和 ID 声明；这偏向完整性而非恒定时间写入，所以如果超大账本上钩子延迟开始接近配置的超时，请更早轮换。事件 ID 在账本内必须唯一。BeforeDone 把写入器批次存为不可变、内容寻址的段，放在 .git/beforedone/events/ 下，用已提交段元数据校验哈希 ID 索引，并拒绝缺失或重复的声明，避免出现含糊的 Incident Timeline 或 Replay Case。v1 之前的 events.jsonl 只导入一次；如果迁移后旧版 BeforeDone 进程继续写该文件，读写会按失败关闭处理，直到版本不匹配解决。

升级与彻底移除

五种交付形式共享 BeforeDone 兼容边界。先升级命令行，再按上面的说明刷新所选集成。升级后，在每个已配置仓库中运行 beforedone doctor。

彻底移除：
1. 在插件目录里卸载插件，删掉两个独立的技能目录，运行 beforedone setup codex --remove，或运行 beforedone setup pi --remove，或运行 dsh plugin --profile <profile> remove dsh-beforedone——取决于你当初选了哪种集成方式；
2. 在 macOS/Linux 上用 command -v beforedone 定位命令行，在 PowerShell 里用 Get-Command beforedone，然后删掉你安装的二进制文件；
3. 先确认要删的内容，再按需从每个仓库里删掉 .git/beforedone 和 .beforedone.yaml；
4. 如果适用，运行 codex plugin marketplace remove beforedone 移除 Git 市场源。

证据与技术报告

实证技术报告冻结了协议、144 个符合条件的验证性结果、分析过程与可复现产物。有一次被取代的尝试没有产出任何结果，保留下来供审计，并从所有有效性分母中排除。在可支撑主张的子集里，每种条件都观察到 0/60 次无依据的完成，因此报告不主张优越性；它记录的是机制、可审计性与实测的验证器成本。

独立的 beforedone-paper 仓库包含完整协议、运行记录、分析代码与报告源文件。这样产品仓库只聚焦命令行，也让这项研究对照它所评估的确切实现得以保留。

阅读报告与产物

贡献与许可

BeforeDone 采用 Apache-2.0 许可。和 MIT 一样，它允许商业使用、修改与再分发，但额外给贡献者和用户明确的专利许可，并界定了贡献、NOTICE 与商标的边界。贡献采用 Developer Certificate of Origin，而非 CLA；提交时用 git commit -s 签名。参见 CONTRIBUTING.md、SECURITY.md、TRADEMARKS.md 和 THIRD_PARTY_NOTICES。