plan-page

计划页面

用户阅读的是页面，而非回复；区块的 Plan pages 规则规定了何时发布，以及回复中应包含什么。主题是工作会改变的一件事，并且有一个对应页面。其文件 <plans>/topics/<slug>.md 保存当前状态。每个延续该主题的计划都是一次迭代，只包含其变更内容。node .agents/pstack/plan-page.mjs <plan> 会根据计划和主题文件生成页面，保存到 <plans>/artifacts/；这是本地副本，会根据已提交的计划和主题文件重新生成，而这两个文件才是记录。node .agents/pstack/plan-page.mjs --index 会在此处生成每个主题的页面，以及一个链接到这些页面的索引。已发布的 claude.ai 页面是用户对一次交接内容发表评论的地方；它不是记录。sync-pstack 会将该渲染器和 status.mjs 部署到它管理的每个项目中。

编写计划或主题文件前，请阅读 references/shape.md。其中列出了所有文件格式、页面顺序以及渲染器会拒绝的情况。

模式	用途
渲染	在区块的 Plan pages 规则列出的每个停点发布页面
刷新	当计划尚未完成时，使用渲染步骤 5、7 和 8 再次生成指定计划的页面；若未指定计划，则使用会话正在处理的主题对应的开放计划；若没有，请先询问
检查	将页面交接前，审查计划及其主题
修复	修正格式错误的页面
PR	将 PR 正文写成该 PR 对应计划的页面，或在他人的 PR 上评论你的提交
更改	更改页面格式、渲染器或操作手册的页面章节

渲染

1. 写计划前先选定主题。继续使用工作所改变对象所属的主题。只有要反复跟进的新对象才新建主题。一次性计划（例如评审结论的计划）没有主题，应保留在自己的页面上。尚无计划的评审结论或“下一步”答复现在就要写计划，可以写之后停止继续的迭代计划，也可以写一次性计划。根据区块的 Plans and trails 规则不保留计划的工作（例如单项修复），不写计划，并在答复中交接。只读请求仍有主题。从仓库外的副本生成计划，并发布到该主题的 Page: URL，绝不要发布到第二个页面。
2. 在 Status: 下用 Topic: <slug> 指定主题，或通过项目在 pageTopic.field 中指定的 frontmatter 列表首项来指定；因此，要先列出负责此次更改的范围。若列表指定的主题尚无文件，计划就暂时保留在自己的页面上；在该文件创建前，渲染器会拒绝没有对应文件的 Topic: 行。
3. 在 Status: 下用 Playbook: <name> 指定 poteto-mode 选用的 playbook，让导航栏显示它。若计划由 .agents/playbooks/ 中的项目 playbook 编写，就指定该 playbook，这样页面会优先显示它的章节，并应用其必需章节；否则指定 pstack 的 playbook，例如 feature 或 bug-fix。渲染器会拒绝无效名称。
4. 按照 references/shape.md，先写计划开头的 ## Brief，再写 ## Teach。所有者会先读这两部分。加载 pstack:teach 并遵循其中的 Teach 方法，复用本次运行的 how 和 why 工作已有发现，不要重复执行。含有 brief 的页面接着会显示 How it works、Demo、Needs you、Picked for you、计划中的更改、计划完成后的 Verification，以及 Open work；计划文件则保留步骤和历史记录。PR 正文也按相同顺序组织。
5. 首次发布前和每次修订后，都要按照 Check 的阅读清单检查，然后运行 node .agents/pstack/plan-page.mjs <plan>。它会拒绝所有可检查的格式问题，并指出如何修复。修改计划或主题文件，绝不要修改 HTML。
6. 如果工作成果可供所有者试用，交接前要按照 references/shape.md 编写计划的 ## Demo，复用 Verification 记录的步骤。结束时，渲染前要先写计划的 ## Close：说明已完成的内容、证据及其局限、区块的 Todo 列表和结束规则要求的计数、优先说明撤销和偏差，以及包含负责人和停止条件的未完成工作。页面显示 brief，不显示 Close，因此要重写 Changes 和 Risks，让所有者了解 Close 中的内容。
7. 页面属于某个主题时，运行 node .agents/pstack/plan-page.mjs --index，然后重新渲染计划。--index 会在本地渲染每个主题的页面和索引，并在每个页面开头列出最新的未结束迭代。第二次渲染会恢复此次停止所对应计划的页面。索引绝不发布。
8. 发布到主题的 Page: URL；一次性计划则发布到其自己的页面，方便用户评论。在 Claude Code 中，发布必须通过 page-stop.mjs 完成，具体按 Plan pages 规则操作：完整阅读它指定的每个文件，然后发送它输出的内容；绝不要发布渲染器输出的整页内容。如果某个 checkout 的 Page: 行在从 origin/<branch> 分出后发生过变化，就发布到该行指定的位置；否则发布到 origin/<branch> 的行所指向的位置，渲染结果会显示该行。首次发布主题时会创建其页面，随后 helper 会提示负责人在主题文件标题下添加 Page: <url>；若为一次性计划，则添加在其 Status: 行下方。当该链接无法打开（因为页面已被删除或属于其他账号）时，发布到另一个 worktree 中渲染器指定的链接；否则运行带 --new 的 helper 创建新页面并替换该行。所有者可能是有意删除页面，因此答复链接指向的计划中也要添加一条 Defaults 行，注明新旧链接，保留新页面，并写明移除新页面所需的词语。要阅读页面，请打开 plans 目录下渲染后的文件，或计划和主题文件；绝不要打开已发布的页面。区块的 Plan pages 规则说明答复中应包含什么，以及 Codex 会话应如何处理。在主题页面首次发布时，询问一次是否要置顶。如果所有者在聊天中询问页面位置，请回复链接并再次提供置顶选项。

检查

运行 node .agents/pstack/plan-page.mjs <plan> --check。该命令会运行所有拒绝检查，且不会写入任何内容。然后阅读计划及其主题，检查渲染器无法判断的内容：

• 页面展示的每句话都要符合 pstack:bro 的语气。先运行计划的文案润色步骤，例如 unslop。然后，作为最后一步，加载 pstack:bro，通过它改写简介、Teach、每个待解决问题、每行 Defaults，以及每组前后对比上方的句子，确保之后的步骤不会推翻这些改写。保留更直白的版本；如果计划的其他部分已包含某项细节，就删掉负责人不需要的细节。这一步可以改变表述，但绝不能改变主张的范围，因此要保留所有数字和限定主张的条件，例如尝试过哪些情况。完成后，将每条改写后的主张与被替换的原句以及记录该主张的日志行逐一比较。有一次 bro 润色把“在已尝试的任务上没有更好”改成了“没有任何帮助”，还把两次试验改成了三次。
• 每个 before 代码围栏都必须是计划之前提交中的真实调用点；每个 after 代码围栏都必须是检出版本中的同一调用，或计划尚未实现时计划中的调用。每个围栏都要在注释中注明路径，并在这组对比上方加一句话。
• 计划尚未完成时，主题文件必须展示计划开始前的状态。即使主题文件是由计划创建的，也不例外。
• 计划更改的每个主题章节都必须有一个按主题行标识的 Delta 表。否则，页面会将该章节标记为未更改。
• Main changes 只列出会改变代码工作方式的非公开变更。
• 自上次渲染以来关闭的每个事项，都必须与其获批的 Proof: 条款一致，且字节完全相同，并位于证明运行的位置。只有项目从已推送的提交同步了共享源代码后，该变更才算在该项目中生效。
• 自上次提交以来更改的计划行中出现的每个全称量词，例如 all、each 或 every，都必须与枚举该集合的日志行或检查相符。
• 本次运行发现的、已确定的构建输入如果只存在于运行目录中，例如请求格式、存储路径、环境变量名称或文档 URL，必须在需要它的步骤之前复制到计划或其主题文件中；绝不能复制机密值或真实载荷。
• 项目的文档检查可能会把计划或主题文件中的每个反引号括起的 .md 名称都当作文档链接，并拒绝指向被忽略运行目录中的链接。此时，应按该区块的 Plans and trails 规则，将指针移至某条决策日志行的 proof: 标签中，绝不能用普通文本替代。
• Status: 必须是一行简短文字：先写状态词，再写计划正在等待什么。待办事项应放在单独的章节中，每项都注明负责人、跟踪位置和阻塞原因。
• 如果多个主题都在等待负责人的回复，那么简介、问题或回复中的每个答复词都必须注明对应主题，例如“go model”，以免单独的“go”落到错误的页面上。

修复

1. 重写前，将每个文件复制到运行目录，并保留副本，作为任何本应触发拒绝的检查所用的必须拒绝测试样本。
2. 运行 检查，并从源头修复每个发现的问题。如果主题文件展示了计划的差异，而其所有步骤均已关闭且证明已完成，那么这是一个已完成但尚未翻转 Status: 的折叠；应翻转状态，而不是还原。对于提前折叠的情况，根据计划中的 before 代码围栏和 git show <base>:<path>，将主题文件还原至未完成计划开始前的状态，并将差异移入计划。
3. 为此次修复记录一条决策日志。
4. 绑定计划字节内容的台账记录会因编辑而失效。按项目的记录规则重新绑定。
5. 渲染并重新发布到同一 URL。

PR

PR 正文就是计划页面以 GitHub Markdown 渲染后的内容，因此，审阅者看到的简介、rail、models、How it works、Demo、picks 和 API 对比，与负责人看到的完全相同。

1. 选择 PR 的计划。如果一个计划涵盖整个差异，就使用它。如果 PR 包含多个计划，或有更改未被任何计划涵盖，就编写 PR 计划：这是一次性计划，其 Status: 下的 Plans: 行会列出它包含的每个计划（路径相对于该计划）。按更改命名，标题采用 PR 标题的写法；渲染器会拒绝标题中出现 PR 编号，因为它无法说明 PR 中的内容。按照 Render 步骤 3 到 6 编写计划，让其中的 brief、Teach、Demo、Public API 配对项和 Defaults 涵盖整个差异，并在这些部分中为每项未被任何计划涵盖的更改安排位置。无论 PR 使用哪个计划，都要在 PR 阶段为审阅者重写 Changes 和 Risks，因为执行中途编写的 brief 是写给负责人的；渲染器会拒绝 brief 中出现 PR 编号。Demo 针对审阅者可见的每项更改各写一个步骤，并以该更改的前后片段作为帧，在步骤中注明片段的任何限制。其 ## Verification 最多用三个项目列出每次运行及证据的范围，其 ## Open work 列出 PR 未涵盖的内容。删除 PR 展示的所有部分中的本地运行文件夹路径，因为这些路径在 GitHub 上无法打开。对其运行 Check，并将 pstack:bro 放在最后。
2. 最后一次推送后，从仓库根目录运行 node .agents/pstack/plan-page.mjs <plan> --pr，这样其中的链接会指向已推送的提交。它会执行页面渲染时的所有拒绝检查；无论计划处于什么状态，如果没有 brief，也会拒绝，并写入 <plans>/artifacts/<name>.pr.md。它会打印该路径，随后为正文尚未上传的每个本地 Demo 或 Teach 帧各打印一行 --attach <file>。
3. 在通过 land.mjs 合并的项目中，land.mjs 会渲染此正文并自行创建新的 PR，且其防护会拒绝 Agent 使用自己的 gh pr create 将更改合入主干分支。其他情况下，创建新 PR 时运行 gh pr create --body-file <file>，并附上打印出的 --attach 行。更新 PR 时，使用 gh pr view <number> --json body --jq .body > <run directory>/body.md 保存正文，以 --into <run directory>/body.md 进行渲染，然后运行 gh pr edit <number> --body-file <file>，并附上打印出的 --attach 行。gh 会上传每个附加帧并重写其引用。渲染只会替换正文中 plan-page 标记之间的文本，保留正文其余内容，例如发布说明区块或手动附加的视频，并复用正文中已上传的每一帧。每次推送更改计划或其差异后都要重新渲染，让正文与已推送的差异保持一致。

如果 PR 是由其他人创建的，请不要改动其描述。你只需留一条评论，内容仅涵盖你在其提交之上所做的提交：

1. 编写这些提交的计划。其中的 Brief 和 Teach 与任何页面一样，面向项目所有者；评论则会省略这两部分。Public API 和 playbook 设计章节的每个代码围栏前，都是作者在你提交更改之前的最后一次提交中的代码。Demo 只包含你的提交在屏幕上造成的变化。如果用户看不到任何变化，计划就不包含 Demo。添加 ## On top of the PR 章节，列出你保留、修改和删除了他们版本中的哪些内容。评论没有其他列表说明你的提交改了什么，因此渲染器会拒绝缺少此章节的评论。计划的 Verification 会指出你的提交的验证证据止于何处，例如某种情况仅由一次临时探测检查过，因为评论不会显示 Risks。
2. 推送后，从 PR 已推送的 HEAD 所在的工作区保存说明：gh pr view <number> --json body --jq .body > <run directory>/description.md。然后运行 node .agents/pstack/plan-page.mjs <plan> --comment <author's last commit> --against <run directory>/description.md。它会写入 <plans>/artifacts/<name>.comment.md，并链接到 DiffsHub 中从该提交到你的 HEAD 的比较视图。评论包含该链接、On top of the PR、Demo、Public API、playbook 设计章节和 Verification。它会省略作者已经知道或只有项目所有者会看的内容：Brief、How it works、此次运行的模型和阶段、未解决的问题、Defaults、待办工作和计划链接。它也会省略说明中已经展示的每段 Demo 视频，以及其所有步骤都已有视频的步骤。
3. 使用 gh pr comment <number> --body-file <file> 和打印出的 --attach 行发布评论。之后再次推送时，将该评论正文保存到运行目录，同时使用 --into 渲染到该文件中；只要它仍是你最后发布的评论，就用 gh pr comment <number> --edit-last --body-file <file> 更新它。有人在其下回复后，发布一条新评论。

变更

渲染器源码位于 dotai 检出目录中的 skills/sync-pstack/assets/pstack/plan-page.mjs，同目录还有 status.mjs。相关测试是 skills/sync-pstack/scripts/sync-pstack.test.mjs 中的 plan-page 测试。仅属于某个项目计划的章节应写在该项目的 playbook frontmatter 中，绝不能写在渲染器里。

运行 sync-pstack 的 Lesson 模式，它负责管理门槛、语料库规则和交付。该模式会在各步骤中加入渲染器的具体要求：

1. 在 Lesson 第 2 步中，编辑 main 分支上的 dotai 检出目录，绝不要使用工作树；即使另一个会话在那里持有未提交的编辑也一样，dotai 的 AGENTS.md 有此规定。
2. 在 Lesson 第 3 步中，为每项新的拒绝规则或行为添加测试，确保旧渲染器会因对应缺陷而无法通过。对于比较文本的拒绝规则，在打开任何面板前，每个维度都要有一个必须通过的用例和一个必须拒绝的用例：大小写、缩进、字面量内部的空格、仅含标点的行、行顺序、与另一轮迭代的部分重叠，以及缺少章节。
3. 在 Lesson 第 4 步中，将每个受管理项目的计划、主题文件、中心文件、.agents/pstack.json 和 playbook 复制到临时目录一次，作为旧渲染器的测试副本；然后对该副本执行 cp -R，并在新副本上应用此变更的迁移，之后再比较两个计划列表，尚未比较任何正文时即可完成。若现有目录树中没有某种会触发拒绝规则的状态，还要回放迭代处于开放状态时的历史提交中的主题文件，以及 Repair 保留的临时副本。为早于 --check 的渲染器提供一个适配器，确保它在写入前退出。让两个渲染器遍历每个计划，列出每个新被拒绝计划及其所属项目，然后使用两个渲染器渲染每个计划并比较正文，忽略 Updated 行。
4. 还要在 Lesson 第 4 步中，为渲染器分支判断的每种模式各渲染一个真实计划：单次计划、主题含有开放迭代的计划、主题没有开放迭代的计划，以及在另一轮迭代开放时渲染的已执行计划。当现有主题没有某种模式时，使用将 Status: 翻转后的临时副本。发布两个版本供项目负责人比较。在提交 dotai 之前，还要在其真实主题页面上以关闭状态渲染此变更自己的计划。
5. 在计划中使用渲染器会解析的新标题、字段或状态词之前，先统计它在所有受管理项目计划中的现有用例，避免已在使用的词意外改变旧页面。

Playbook 章节

项目 playbook 位于 .agents/playbooks/<name>.md，其 frontmatter 在 extends 和 when 旁以逗号分隔的列表指定计划会写入的评审章节：

page-lead: What other editors do, Document shape, Layer and owner
page-pairs: Document shape
page-require: What other editors do
page-pr: What other editors do, Document shape

• page-lead 章节会紧接 Public API 渲染，优先采用主计划的 playbook。
• page-pairs 章节包含 before 和 after 配对，与 Public API 类似。
• 只要该项目为主题配置了 pageTopic.hub 文件，page-require 章节就必须存在于主题文件中；如果引领页面的计划带有简报，也可以存在于该计划中。
• page-pr 章节是评审者用来判断设计的 page-lead 章节。PR 正文会在 Public API 之后按 page-lead 顺序显示这些章节。PR 会显示其所含任一计划的 playbook 所指定的每个章节；未指定 playbook 的 PR 计划，则会在该计划标题下显示所携带的每个计划对应的章节。如果标题未列入同一 playbook 的 page-lead，则会被拒绝。

当主计划未指定 playbook 时，每个 playbook 的章节和要求均适用。playbook 或其指定的技能会定义各章节的内容。