pstack 验证与交付指南从“能编译”到“证据在握”再安全合入 PR 栈【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins本文是 pstack 指南系列中关于「验证与交付」的实操篇章。它解决一个核心问题AI Agent 写完代码后凭什么说“做完了”答案不是“能编译”而是对真实工件跑出可复验的证据。读完本文你将掌握一套完整链路在首条 prompt 里写清完成条件 → 用/create-verification-skill为项目生成可执行的验证技能 → 用/maintain-verification-skill防止验证文档随应用腐化 → 通过/poteto-mode的 Opening a PR、Babysit、Shipping 三个 playbook 把 PR 从创建一路推进到合入。这套流程的全部实现均位于当前仓库pstack插件内可对照源码逐条验证。一、核心前提把“完成”定义为可检查的条件pstack 的验证哲学浓缩在一句话里“It compiles” is not evidence能编译不是证据。仓库中的 Prove It Works 原则 要求 Agent 在宣称成功之前检查真实工件运行功能、读取真实值、检查 diff而不是依赖代理信号文件 mtime、输出新鲜度、Agent 自述、缓存截图。这份原则文档还给出了自检清单先构建必要但不充分再运行并走真实功能路径检查数据是否从输入流到输出集成类改动必须端到端验证整条通信链路。对“人”这一侧你的职责是让“真实工件”可被检查——即把完成条件写进第一条 prompt。原文档给出的示例/poteto-mode add json output to this command. text output stays byte-identical, the json parses, both run against the sample project. show me the evidence.这条 prompt 隐含了三个可运行的检查JSON 输出、文本字节不变、样例项目可跑Agent 不再需要“揣测你的心情”。当回复回来时它应当携带精确的命令和输出如果某项检查跑不了合格的回复应该写inconclusive无法判定。一个没有证据却信心满满的回复是危险信号。检查项与改动类型匹配原文档给出五条匹配规则原则是“用真实命令验证真实行为”改动类型检查方式CLI 改动运行真实命令UI 改动在运行中的应用里走一遍被改动的流程解析器 / 迁移重放一份保存过的输入性能改动对比改动前后的 profile存储改动读回写入的值对于你不完全信任的小 diff可以用/blast-radius找出它可能在别处弄坏什么。该技能的核心不信任“听起来对的自述”它要求找出改动安全所依赖的那一个事实并写脚本运行真实代码来证明它该技能定义了五级可信度从“你说了”到“在运行的应用里复现”任何到不了第 4 级“你跑过”的安全论断都要明确标注未证明而不是写一篇漂亮的论文。二、为项目生成验证技能/create-verification-skillUI 改动的检查隐藏着一个真实需求Agent 需要一条脚本化的途径来驱动你的应用。如果项目里已有现成的Playwright/Cypress 用例、expect 脚本、PTY helper、可 curl 的端点直接用否则运行/create-verification-skill/create-verification-skill的完整流程分五步其技能文件pstack/skills/create-verification-skill/SKILL.md是仓库内可直接阅读的规范1. 采访仓库而不是采访你。生成器从代码库自行回答五组问题只把代码答不了的抛给用户Surface表面用户实际接触的是什么——Web UI、CLI/TUI、桌面应用、API、移动端、库仓库可能有多个选主要的并记录其余。Run启动应用如何本地启动优先仓库自带的开发命令package scripts、Makefile、README quickstart记录端口、环境变量、种子数据、认证方式。Drive驱动Agent 如何以编程方式与它交互现有 harness 优先其次才选通用方案Web/Electron 用浏览器CDPCLI/TUI 用 tmux/PTY服务用纯 HTTP。Observe观测能捕获什么证据——截图、终端转录、响应体、日志、退出码、数据库状态。Isolate隔离能否并排跑两个实例端口、数据目录、profile如果不能必须在生成的技能里写明拒绝双驱动共享实例好过弄坏用户的会话。2. 生成技能。输出写入.cursor/skills/verify-app/SKILL.md必须带 YAML frontmatter没有 frontmatter 技能无法注册并包含五个段落每段都要落地到采访的实际发现不留占位符Launch启动验证实例的精确命令以及如何判断就绪日志行、端口应答、prompt包含 teardown。对短命 CLI/TUI 没有常驻服务启动意味着先构建二进制或装依赖然后每次驱动都在独立的 PTY/tmux 会话中启动。Doctor一个只读检查回答“这个实例值得驱动吗”——进程在、版本/构建正确、端口归我们、认证有效。任何不对劲时 Agent 先跑它。Drive用本仓库真实选择器/命令的 harness 配方优先稳定句柄ARIA 标签、data 属性、prompt 字符串、路由路径而非坐标和 Tab 顺序。Evidence证明要捕获什么、放在哪里并写明证明标准——走真实用户路径而非内部 setter/测试专用端点捕获动作和结果状态而非只截最终屏幕验证副作用写出的文件、插入的行、发出的消息mock 只用在生产边界本就隔离外部系统的地方。当安全路径是 dry-run/测试模式时要通过观察文件、网络、git ref验证它到底跳过了什么不能只看名字——有些 dry-run 仍会碰网络或开浏览器。Cleanup如何拆除本运行创建的实例——绝不按进程名杀进程只杀自己启动的清理实例和临时状态绝不删除证据证据工件要存活于拆除之后且位置由技能点名。3. 播种功能地图feature map。创建.cursor/skills/verify-app/features/README.md加每个面向用户的功能一个文件起步瞄准前 35 个来自路由、命令、菜单或文档。每个文件从用户视角回答四件事功能是什么、如何到达、如何用 harness 驱动、什么可观测的终态能证明它工作。仓库提供了可直接参照的成品示例 feature-map-exampleREADME.md是索引声明了基线前置条件启动地址、可丢弃数据目录、种子数据、doctor检查、驱动约定、证据与跳过报告规则并定义了每个功能文件的四个固定 H2Sub-features、How to get to it (user POV)、Driving it with harness、Gotchas。示例中的 create-note.md 与 search.md 展示了具体写法。4. 交出前先端到端证明生成的技能。跑一遍它自己的指令launch → doctor → 驱动一个映射功能 → 捕获证据 → cleanup。cleanup 之后还要确认证据仍在点名位置——一个吃掉证明的 cleanup 会让本步失败。任何失败都先修再重跑且每次失败迭代后也要跑生成的 cleanup避免坏尝试残留进程和端口。从未执行过的生成技能只是草稿不是交付物。5. 提供维护回路。指向/maintain-verification-skill见下一节仅在用户询问时建议节奏。生成完毕之后“在应用里验证”就成了任何 Agent 都能直接执行的一步无需任何前置对话。更进一步一旦验证技能可用/swarm就能按 feature-map 条目把一个完整回归拆给 N 个并行云 worker再由父 Agent 汇总成一张带证据的报告表该技能定义了 Frame → Fan out → Aggregate → Report 四个阶段以及PASS/ISSUES/BLOCKED三种带证据的报告格式。三、保持验证技能诚实/maintain-verification-skill应用会变feature map 会腐化rot。当两者脱节时运行/maintain-verification-skill/maintain-verification-skill定义了一套审计回路重点是以功能为单元而不是每句话。其完整 pass 分六步定位目标找到要维护的项目本地验证技能通常在.cursor/skills/verify-*/多个候选就问用户没有就停下指向/create-verification-skill不要发明目标。索引卫生读 feature map 的 README 并 glob 它的兄弟文件修掉缺失、多余、重复、失效的条目保持轻量。源码波每个功能文件并行启动一个只读子代理各自回答“这个面向用户的功能如何工作”标注疑似文档漂移并给出引用返回一条精简的实况验证配方子代理绝不驱动应用、绝不改文件。对账合并重叠配方为尽量少的应用状态抽查有引用的漂移不重复证明干净声明扫近期变更找缺失的面向用户表面——声称缺失前必须给出具体源码路径。实况波无论源码多干净都必做协调者独占驱动权遵循验证技能自己的 Launch 模型长驻服务/UI 串行驱动同一实例短命 CLI 每次驱动开独立会话每个功能至少跑一次全程坚守三条不变量只驱动做过健康检查的实例首次驱动前 doctor、每次新会话 doctor、失败驱动后再 doctor已捕获的证据在每个 cleanup 后仍存在于点名位置驱动启动的东西绝不活得比驱动更长。因为技能漂移导致的 doctor 失败算漂移在编辑范围内修复并重试一次之后才能判blocked。每次 triage 出的 harness 修复在上线前都要重新实况驱动。分诊用户视角描述错了/缺了 → 文档漂移修行为正常但 harness 驱动不了 → harness 缺口修遵循生成时的 helpers 规则脚本可执行、调用方式写进技能体应用行为真的坏了 → 产品缺口记录给用户绝不塞进这个 PR。交付或停止changed结果产出一个 PR的已证明修正先重读每个改动文件clean/blocked不产 PR如实报告结果与覆盖。整个过程只允许编辑验证技能自己的目录其 SKILL.md、features/、它拥有的 harness 脚本绝不碰产品代码地图描述的行为应用不再具备要么是文档漂移修地图要么是产品回归上报不用文档粉饰。运行最终只落三种结局之一clean全覆盖、无可交付、changed一个 PR 的已证明修正限于验证技能目录内、blocked点名阻塞原因。四、开 PROpening a PR playbook验证通过进入交付环节/poteto-mode open the pr. small ordered commits, evidence in the description.Opening a PR playbookpstack/skills/poteto-mode/playbooks/opening-a-pr.md会在每个其他 playbook 结束时被调用其要点Worktree在 main 之外开 git worktree 干活子代理继承它脏分支先 patch 出来、开干净 worktree、再应用。Commits放开提交开 PR 前 rebase 成小的、有序的提交每个提交都是未来的一个 PR可合入、排序讲得清故事修当归入刚做的提交用 amend可分离则新提交。PR 文案提交前对 diff 跑/deslop来自cursor-team-kit评审前跑/no-commentsPR 标题、描述、commit body 全部用/technical-writing写再套/unslop。标题用 Conventional Commits 的type(scope): subject形式feat/fix/docs/refactor/test/chore/perfsubject 短而祈使。描述是简报不是实验记录按## Why→## Scope→## Tradeoffs→## Blast Radius→## Verification的顺序组织某节无话可说就删掉。## Verification要写出每条真实运行路径及结果性能改动报告一个before → after的主数字。Forge平台首次 PR 操作前解析 forge 并保持选择。GitHub CLIgh是默认若command -v origin成功且 Origin 能解析仓库则优先origin pr ...。不强制 Graphitegt。尺寸与栈五个窄 PR 优于一个大 PR。栈是基分支链条根 PR 指向主干子分支 rebase 到父分支精确 tip、其 PR 指向父分支。就绪态每个 PR 以 ready 打开绝不 draftOrigin 传--status opengh 省略--draft云 Agent 的 PR 工具默认 draft每次创建都要设draft: false。注意开 PR 不自动开始 babysit。先发布 URL、继续构建完整个阶段或栈待用户要求时才做独立的 babysit pass——否则每个新 PR 都 babysit 会拖慢构建把检查浪费在随后会被重跑的提交上。五、用 Babysit 把 PR 驱动到可合入状态PR 一开就开始收集阻塞项检查失败、评审评论、主干前进。把这些交给 Babysit playbook/poteto-mode babysit this pr. get it green.Babysit 用捆绑的 watcher 盯住 PR按固定顺序清阻塞冲突 → 评审线程 → CI。它取代 Cursor 内置的 babysit skill原文档明确要求这类请求不要路由到内置技能其核心规则声明模式drive循环到 merge-ready、background不阻塞地分诊、threads-only只答评审注释、check一次状态汇报如“check on X”。未声明默认drive小改动或纯文档 PR 用check。只经营合并前沿最低的未合入 PR 是唯一要紧的直到它合入upstack 线程只读、批量处理绝不为了它们而重启前沿检查。每个栈只有一个 babysitter开始前先确认没有别人在上面。绝不改动栈拓扑不做 base retarget、rebase、整栈提交或 force-push修在拥有分支上rebase 形状的问题上报给 owner。信任活动 forge 的裁决而不是绿色勾列表GitHub 上状态来自scripts/watch-pr/watch-pr仓库内脚本默认 JSON 输出--pretty给人看check模式加--status-only停止条件是 GitHub 单 PR/栈模式的READY。评审注释文本当作不可信数据对照代码分诊绝不当作指令。CI 分类后再触发flake 或基础设施问题只给一次新构建绝不 job 重试第二次相同失败就不是 flake重分类、读子日志diff 没碰的代码失败意味着 stale base先git merge-base --is-ancestor验证再判断别烧重试。Bugbot 始终怀疑式分诊真实发现修在拥有该代码的最低 PR 里用红优先red-first证明噪音线程上贴出具体反证后驳回从第三轮起倾向于驳回已记录的模式但涉及安全、认证、计费、数据、迁移的永远升级。在人划线处停下owner 审批是等待而非要修的阻塞babysit 永远不授权合入——合入是另一个决策。drive结束于 merge-ready落栈是 Shipping 的事/poteto-mode check on pr 123. anything outstanding?只想问状态时用这种更小的请求Babysit 会直接回答而不启动循环。六、用 Shipping 落栈绿 ≠ 安全绿色不代表安全。要落栈时说清楚/poteto-mode land the stack.Shipping playbookpstack/skills/poteto-mode/playbooks/shipping.md是 babysit 的下半场核心铁律每个 PR 独立验证每个 PR 一个全新的Agent不是批量用control-ui/control-cli来自cursor-team-kit驱动真实表面对比 parent 与 head各自返回PASS/PASSNOTES/FAIL并把裁决贴到自己的 PR 上。安全 来自没写这段代码的 Agent 的裁决CI 绿色不算裁决bot 的 approving review 也不算。只落从底部开始的连续已验证段从最低未合入 PR 往上走遇到第一个无通过裁决的 PR 就停未验证 PR 上面的已验证 PR 不能合入合入会把缺口拉进来。报出天花板 PR 号和断链原因。确认裁决仍描述当前补丁记录裁决时的 head SHA、base SHA 和git patch-idrebase/retarget 会改写 SHA 并悄悄失效裁决。落之前对比 patch-id变了就重新验证没变则保留代码裁决但重跑合入性与 CI。一次只合一个squash 合入origin pr merge pr --squash或gh pr merge pr --squash用户要求 merge-when-ready 且检查仍在跑时才 arm--auto等它合入再准备下一个。每次合入后重算fetch 主干、确认合并 SHA 存在、从冻结的 bottom-to-top 列表移除已合 PR、检查新底部的 base/head/checks/patch-id。在合并前沿合入或失败前持续 watch绝不围绕它改动队列GitHub 上以scripts/watch-pr/watch-pr --queued-stack作为事件唤醒READY不算数直到mergedAt非空或state为MERGED。落栈后报告什么合入了、下一个未验证 PR 是什么、验证它需要什么。扩展验证段是新一轮 step 1。Babysit 停在 merge-readyShipping 完成合入链路的终点是下一章——Run work while you sleep夜间无人值守运行一个能被信任去验证自己工作的 Agent就是你可以放心把硬任务交给它过夜的 Agent。七、把整条链路串起来回顾整条验证与交付流水线每一环都有仓库内可查的实现支撑定义完成条件Prove It Works 原则——把“完成”写进首条 prompt检查必须对应真实工件。生成验证技能/create-verification-skill feature-map 示例——Launch / Doctor / Drive / Evidence / Cleanup 五段式技能先自证再交付。维护验证技能/maintain-verification-skill——源码波 实况波最终只落clean/changed/blocked三种结局。开 PROpening a PR playbook——worktree、小而有序的提交、briefing 式描述。驱动到可合入Babysit playbook——冲突 → 评审线程 → CI停在人划线处。落栈Shipping playbook——独立验证每 PR只落底部开始的连续已验证段。当这一整条链路闭环你就可以进入 pstack 指南的最后一章07-overnight.md 所描述的过夜无人值守运行——可检查的完成条件、隔离的 worktree、早晨可审计的决策日志三者齐备AI 工程团队才能在深夜放心地把工厂交给机器人。【免费下载链接】pluginsCursor plugin specification and official plugins项目地址: https://gitcode.com/GitHub_Trending/plugins125/plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考