企业官网建设流程全解析

• 人工智能
• AI 技能
• AI 插件
• 开发工具

本篇技术指南围绕 pstack（Poteto 的 pstack 在各 Agent 运行时上的移植版，覆盖 Claude Code、Codex、Copilot、Pi 等）中的原则技能principle-prove-it-works展开，讲清楚"在宣告任务完成之前，如何用真实工件而非代理信号证明它确实能工作"。读完本文，你将掌握 pstack 验证哲学的完整内容——为什么间接验证靠不住、如何正确解读一次失败检查、怎样把验证脚本化，以及该原则在测试、调试、逐单元交付和决策留痕等环节中的落地方式，并可直接迁移到自己的 Agent 工作流中。

原则定位：在宣告完成之前，先证明它真的能工作

principle-prove-it-works是 pstack 原则技能家族中"验证（Verification）"类目下的核心技能，定义于 plugins/pstack/skills/principle-prove-it-works/SKILL.md。其 frontmatter 明确了触发时机与适用范围：

Apply after completing a task, before declaring done. Verify against the real artifact (run the feature, read the actual value, inspect the diff), not a proxy, self-report, or "it compiles."

即：在任务完成之后、宣告"做完"之前应用，且user-invocable: false，表示它不是供用户手动调用的命令型技能，而是由 Agent 根据场景自动遵循的纪律性规范。它的验证对象是真实工件，并给出了三个可操作的具体动作：运行该功能（run the feature）、读取实际值（read the actual value）、检查差异（inspect the diff）；明确排除的则是代理信号（proxy）、自我汇报（self-report）和"它能编译"（it compiles）。

正文第一句即给出总纲：

Verify every task output by checking the real thing directly. Do not infer from proxies, self-reports, or "it compiles."

为什么必须直接观察真实工件

该原则对"为什么要这样做"给出了直白的论证：

Unverified work has unknown correctness. Indirect verification (file mtimes, output freshness, agent self-reports, cached screenshots) feels cheaper than direct observation. Acting on a wrong inference costs far more than checking the source.

核心逻辑有两点：

1. 未验证的工作正确性未知。没有经过直接检验的产出，其正确性在逻辑上是未知的，"看起来没问题"不等于"没问题"。
2. 间接验证是虚假的廉价。文件修改时间（file mtimes）、输出新鲜度（output freshness）、Agent 的自我汇报、缓存的截图，这些手段在感受上比直接观察更省事，但代价被推迟了：基于错误推断继续行动，其成本远高于一开始就去检查源头。

这一论证在 pstack 的整套验证体系中反复出现，例如 principle-build-the-lever 中的表述"Hand-done changes can only be re-verified by redoing them. A deterministic script turns 'trust me' into 'run this'"——手动改动只能靠重做来复核，确定性脚本则把"相信我"变成"你来跑"。两处强调的是同一件事：验证必须落到可重跑、可观察的真实对象上。

三个"检查真实事物，而非代理"的落点

原文档给出了三条可执行的分辨规则：

• 直接检查进程存活，而不是通过派生状态间接判断（Check process liveness directly, not indirectly through derived state）。例如要确认一个后台进程还活着，应直接探测进程本身（如 PID、进程表、健康检查端点），而不是根据某个由它派生的文件或日志时间戳来推断。
• 读取实际值，而不是缓存或派生的表示（Read the actual value, not a cached or derived representation）。要验证配置、计算结果或接口返回值，应读取真实数据源，而不是缓存快照、聚合视图或上一次运行的输出。
• 验证失败时，先怀疑观察方法，再怀疑系统（When verification fails, suspect the observation method before suspecting the system）。一次失败可能源于系统真的坏了，也可能源于你的观察手段本身不可靠（读错了文件、看错了快照、探测了错误的端点）。按此顺序排查，能避免把"测量错误"误判成"系统缺陷"。

验证结果，更要验证过程

原文档专门强调：不仅要验证结果，还要验证产生结果的流程（Verify the process as well as the outcome）：

A correct result can rest on a broken process, and a review that checks results passes it: a clause reconstructed from the user's paste instead of the durable record, a constraint honored by chance from a file never read. For each fact you relied on, name the record it came from and confirm that record is the one the project's rules point at.

这描述了两类典型事故：

• 正确结果建立在坏流程之上：比如某段承诺的条款其实是 Agent 根据用户粘贴的内容临时重建的，而不是来自持久化记录（durable record）；某项约束是碰巧被满足的，而相关的那个文件根本从未被读取过。此时结果正确，但流程是坏的，只检查结果的评审会直接放行。
• 必须对每个依赖的事实点名来源：对你所依赖的每一条事实，都要说出它出自哪份记录，并确认这份记录正是项目规则所指向的那一份。这一条与 pstack 的决策留痕机制（show-me-your-work 的 TSV 决策日志中"evidence 是指针而非散文"的要求）完全同构，详见后文。

红色不是测量：如何正确解读一次失败的检查

原文档用一句非常精炼的格言点破了一个常见误区：

Red is a colour, not a measurement.

失败输出本身不是测量结果，只有失败内容与你预测的分歧一致时，失败才能证明你的检查工具在正常工作。文档给出了三种"都打印红色"但含义截然不同的情形：

• 异常（exception）：可能只是环境或路径问题，与你的预测无关。
• 空集合对比非空字面量（an empty collection against a non-empty literal）：数据缺失导致的失败，未必说明被测行为真的错了。
• 真实不匹配（a real mismatch）：这才是你预测中的分歧真正出现。

因此，报告失败时要引用断言产生的差异（diff），而不是断言本身：

quote the assertion's diff (Extra items in the right set), never the assertion (assert {...} == {...})

即报告Extra items in the right set这类实际差异内容，而不是干巴巴地写assert {...} == {...}失败了。因为断言语句只说明"不相等"，而 diff 内容才说明"分歧是什么"，后者才是可判定、可复核的测量。

文档还警告了两个隐蔽的假验证场景：

• 收敛探针（convergence probe）必须锚定只有新工件才能产生的行为，绝不能锚定旧工件也会发出的同一标识字段（identity field），否则新旧实现都会让探针通过。
• 同 SHA 重启（a same-SHA restart）会让旧代码报告新的提交 SHA：如果你重启后看到"新 SHA"就认为新代码已生效，那么在同一个 SHA 上重启的旧代码同样能打印出这个新提交号——这又是一次把派生表示当真实值的间接验证陷阱。

这两条与"重启类故障先怀疑持久化状态"的 principle-fix-root-causes 形成呼应：故障排查时不要加nil守卫去压住崩溃，而是"插桩，不要猜测（add logging, read the actual error）"。

尽可能把检查脚本化

原文档对"验证强度"给出了明确排序：

The strongest proof is a deterministic script that re-runs the same comparison, not a one-time eyeball. Write the script, run it, and keep its output as an artifact a reviewer can re-run instead of trusting your word.

最强有力的证据是确定性脚本——它每次都以相同方式重跑同一比较，而不是一次性肉眼观察。做法是三步：写脚本、运行它、把输出作为工件保留下来，让评审者可以重跑验证，而不是相信你的一句话。这正对应 principle-build-the-lever 的核心主张："The tool is the artifact a reviewer can rerun"（工具本身就是评审者可以重跑的那个工件），以及"确定性杠杆胜过扇出（a deterministic lever beats fan-out）"——能用脚本一遍跑完的事，就不要派多个子 Agent 手工重复。

关于工件的可见性，原文档规定：

Keep the artifact visible for the human. Commit it only for large or complex work where the trail has to be auditable later, like a big port or migration (theshow-me-your-workskill).

即：默认让验证工件对人类可见即可，只有规模大或复杂度高、事后必须可审计的工作（如大型移植、迁移）才把验证脚本提交进仓库，此时应配合 show-me-your-work 技能保留可复核的决策轨迹。这一分寸感很重要：避免为每个小改动都引入永久性脚本负担，但在"赌注够大"时绝不省掉审计链路。

show-me-your-work 技能（plugins/pstack/skills/show-me-your-work/SKILL.md）正是这条"大工作可审计"落地的配套机制：它维护一份单文件 TSV 决策日志（decisions.tsv，多任务并发时放.audit/<task-slug>.tsv），每行一条决策，列为ts / phase / decision / why / evidence / result，其中evidence 必须是能证明它的链接或路径（commit SHA、PR 号、file:line、工件/轨迹/截图路径），"绝不允许是一段散文"。日志默认不提交（append-only，只追加不改写），只有当工作大到评审者需要轨迹才能信任结果时才提交。仓库为此提供了辅助脚本 scripts/log.sh，它会盖时间戳、首用时写入表头、剥离单元格中的制表符与换行，并为以=+-@"开头的单元格加前导单引号，防止生成内容污染表格格式。

从原则到实践：pstack 工作流中的落地证据

principle-prove-it-works不是孤立的教条，它被 pstack 的整套技能树和 playbook 反复引用和落实。以下是仓库中可查证的对应关系。

测试层：断言必须能捕获真实缺陷

principle-test-behavior-not-implementation 直接继承了"检查真实事物"的精神：保留一个测试之前，先命名一个相关缺陷，并确认整套测试布置能捕获它，可行时临时注入该缺陷、观察测试失败。要点包括：

• 契约要求结果时，toBeDefined能发现"结果缺失"，却会接受"错误的结果"，应强化为检查特定结果；
• 契约要求"缺席"时（如被拒绝的操作必须不发邮件），应执行拒绝路径并断言发件箱为空，且临时让该路径真的发信、确认测试确实失败；
• 固定值只有在构成对用户可见的契约（如承诺的默认值）时才应冻结，避免冻结偶然的常量或提示词；
• 期望值不能通过与被测路径相同的故障路径计算出来（那会自我确认），要用独立期望或真实被违反的关系；
• 要拒绝"没测任何相关东西、断言没有意义、只证明替身被调用却没检查实际效果"的测试。

它甚至指出"断言的语法本身无法告诉你它能否捕获缺陷（An assertion's syntax alone cannot tell you whether it detects a defect）"——这与 prove-it-works 中"红色不是测量"是同一条认识的两个侧面：形式上的通过/失败都不是测量，内容才是。

节奏层：把工作切成每个都能验证的小单元

principle-sequence-verifiable-units 开篇就声明自己是 prove-it-works 的"编排补足"：

The sequencing complement to theprove-it-worksprinciple skill, which keeps each check real, and thebuild-the-leverprinciple skill, which makes the per-unit check cheap.

它要求把工作组织成一系列以可检查状态结尾的小单元，当前单元未绿不得前进：每次改动是一个"前/后括号"（已知良好状态 → 一次改动 → 运行检查 → 继续），先在干净主干上 rebase 使每次检查都针对真实基线。交付时按"能证明工作的顺序"堆叠提交与 PR，规范形态是失败测试在前、修复叠加其上——bug-fix playbook 第 5 步正是如此要求："stage the commits so the failing repro lands before the fix in git history"。这样评审者看到的是"看着它变红，再变绿（watch it go red, then green）"，而不是一句"相信我"。

调试层：复现优先，同表面验证

principle-fix-root-causes 提供"先复现、追问 why 直到根因、不加守卫、检查模式而非个例、卡住就插桩"的调试纪律；而各 playbook 把"真实工件验证"落实为具体流程：

• bug-fix（playbooks/bug-fix.md）：第 1 步要求"在匹配的表面上亲自复现"；第 4 步要求"在同一表面上验证，原复现现在通过"，并明确"Inconclusive 或错误表面不算通过（'Inconclusive' or wrong-surface is not a pass）"——这正是"检查真实事物而非代理"在修复场景的具象化。
• visual-parity（playbooks/visual-parity.md）：像素级等价由图像差异（image diff）验证，而不是靠眼睛；"基线就是规格，不允许触碰"；每个组件对照基线做 image diff，非零差异即失败，调查像素差异直到 diff 为零。
• perf-issue（playbooks/perf-issue.md）：每一项修复都绑定一个测量，"不要靠读源码代替测量（don't read source instead of measuring）"；先采集基线轨迹，再比较前后工件，最后在 PR 里引用测量数据；同样规定"Inconclusive 或错误表面不是通过"。

这些 playbook 都要求"Reply"环节汇报可复核的证据（决定性输出、diff 结果、基线编号、前后数值与工件路径），即把验证结果本身作为交付物的一部分，而非一句"做完了"。

仓库自身的脚本化验证实例：pre-tool-use 钩子

pstack 仓库自身就是"把检查脚本化"的活例子。plugins/pstack/hooks/pre-tool-use.sh 是 GitHub Copilot 专用的工具调用前置钩子：它通过awk -f依次加载json.awk、sheet.awk、script-contracts.awk、pre-tool-use.awk多个脚本，由pre-tool-use.awk决定某次工具调用是放行、拒绝还是走正常权限流程（例如：批准查看本插件自身文件、批准严格形态的厂商脚本执行；拒绝用户在未保存的模型上派发 pstack Agent）。任何路径都exit 0（因为 Copilot 在钩子非零退出时会拒绝调用），脚本内部任何一次失败只向 stderr 打印错误、丢弃输出。可以看到：验证规则（放行/拒绝的判定）被编码进脚本和 awk 规则文件，而不是写成让 Agent"注意遵守"的文本——这正是 principle-encode-lessons-in-structure 所倡导的"把反复出现的指令编码进结构（lint、元数据、运行期检查、脚本），而不是更多文字"，与 prove-it-works 的"脚本化检查最强"形成闭环。

操作清单：把 Prove It Works 用起来

将原文档要点整理为可直接执行的核对清单，供在宣告任务完成前逐条自检：

1. 检查真实工件：运行该功能、读取实际值、检查 diff；不要依据文件 mtime、输出新鲜度、Agent 自我汇报或缓存截图。
2. 分辨代理：进程存活直接探测进程；数值直接读真实数据源；失败先怀疑观察方法再怀疑系统。
3. 结果与过程都验证：对每条依赖的事实，说出它出自哪份记录，并确认这份记录是项目规则指向的那一份。
4. 正确报告失败：引用断言的 diff（如Extra items in the right set），而不是断言本身；确认失败内容是"你预测的分歧"，异常与空集合失败不算数。
5. 警惕假验证：收敛探针必须只锚定新工件才有的行为；同 SHA 重启的"新版本号"不是新代码已生效的证据。
6. 脚本化检查：写确定性脚本、运行它、保留输出工件供评审重跑；只有大型/复杂工作（大移植、迁移）才提交脚本并配合 show-me-your-work 留下可审计轨迹。

这套原则的全部细节与配套技能都收录在当前仓库中，可对照阅读：原则本体、验证类原则家族（Prove It Works / Fix Root Causes / Sequence Work into Verifiable Units / Test Behavior, Not Implementation / Explain the Number 同属 Verification 分类）、测试行为断言、可验证单元序列、构建杠杆、决策留痕，以及 bug-fix、visual-parity、perf-issue 三个 playbook 中的验证纪律。

一句话收束全文：在宣告完成之前，让证据替你说话——证据要来自真实工件，且能被脚本重跑、被评审者复核。

• 人工智能
• AI 技能
• AI 插件
• 开发工具