setup-pstack

设置 pstack

对于仅涉及 PR 模板的请求，只运行步骤 0e。完整设置需运行以下所有适用步骤。

编写 pstack models 配置文件，用于按角色设置 pstack 的模型和推理强度。Agent 会通过此技能的解析器按角色解析配置。工作区中的 .agents/pstack-models.md 优先于用户的 ~/.agents/pstack-models.md；任一文件中，针对特定框架的配置段优先于普通配置行；两个文件都未指定的角色则回退到随附的默认配置 examples/pstack-models.md。因此，这是一个覆盖层，而非必需配置。

内联默认值使用简短的模型别名（fable、opus、sonnet、haiku），在 Codex 上会转换为 gpt-6 模型，在 Grok Build 上则转换为 grok-4.7。如果框架不接受你为子 Agent 指定的其他值，则会使用 inherit-parent：该角色使用会话模型运行，多模型面板也会变成同模型面板。条目可以用 model@effort 固定推理强度；## codex、## claude-code、## grok 或 ## hermes 段则包含仅适用于相应框架的配置行。语法、分层规则和推理强度策略统一定义于 references/models-config.md，而 scripts/check-models-config.py --resolve 会应用这些规则。

步骤

0a. 检查角色配置和可选的原生注册

阅读 pstack-harness 技能的注册参考。通过 portable-paths.md 解析其逻辑安装技能根目录，然后运行：

python3 "${PSTACK_SKILLS_ROOT:?}/pstack-harness/scripts/subagents.py" check

失败信号：退出码非零。报告角色配置就绪情况前，先修复缺失的负载或同级技能。负载就绪后，通用委托即可获得完整角色配置，无需原生注册。

此项检查只涵盖负载，并会将每个原生文件都报告为 not-requested。如果角色配置或工作量 Agent 已注册，还应对包含 poteto-agent、comment-sicko 或 pstack-effort-<level> 文件的每个 CLI 和范围运行注册参考中的原生 check：~/.claude/agents、~/.codex/agents，或项目的 .claude/agents、.codex/agents。当某一行报告 outdated-generated 时，为相应的 CLI 和范围提供参考中的 install。如果同组的另一行报告 conflict，则报告冲突，而不是安装，因为安装不会写入该组。角色配置和工作量 Agent 分属不同组，因此一组中的冲突不会阻止另一组。更新技能不会刷新已注册的角色配置或工作量 Agent。

如果用户需要，为 Claude Code 或 Codex 提供原生注册。如果会话已提供授权范围，则使用该范围；否则询问一次用户要用项目范围还是用户范围。根据注册参考，如果用户通过赋予 Codex 自有 CODEX_HOME 的包装器运行 Codex，建议使用项目范围，可单独使用，也可与用户范围一起使用。使用所选绝对根目录运行参考中的 install 命令。切勿覆盖冲突，也不要更改模型设置来注册角色配置。对于 Hermes，通过委托上下文提供完整说明；不要创建原生 Agent 文件。Grok Build 没有自己的注册机制。它会加载 Claude Code 包装器，但其生成工具无法指定 Agent 类型，因此委托会在提示词中收到完整说明。

对于 Claude Code，说明注册会添加什么：两个角色配置和五个 pstack-effort-<level> Agent，让书面指定的 @effort 能应用于此处的子 Agent。安装 Claude Code 前，按照步骤 2 读取两个配置层，并列出所有为此运行环境写明工作量的角色及其工作量。说明这些角色会在 Agent 加载后按该工作量运行，其他所有角色则沿用会话工作量。将 roles 行和 efforts 行分别与实时加载情况分开报告。如果安装报告显示 agents_directory: created，Agent 只会在新会话中加载，因此要告知用户启动新会话。否则，正在运行的会话会加载这些 Agent，除非会话是通过 --disable-slash-commands 启动，或者目录来自 --add-dir。无论哪种情况，在声称某项工作量已生效前，都要检查实时目录。

分别报告负载就绪情况、原生文件状态和实时 Agent 加载情况。声称原生可用前，先检查指定目标并查看实时 Agent 目录。文件系统输出始终无法验证是否已激活。Codex 项目注册需要项目受信任。不要自动修改信任设置。注册更改后检查新会话；如果加载器需要重启，要说明这一点，并在确认加载前通过完整说明进行委托。将这些观察与下方的模型选择分开。

0b. 检查结构化任务工具

poteto-mode 会在该工具启用时，将工作清单保存在运行环境的结构化任务工具中。无论通过哪个 CLI 运行此技能，都要检查下面两个开关，并分别报告为开启或关闭。更改从下一个会话开始生效。只有用户同意后才能编辑文件。然后将该键添加到现有文件中，并保留其他所有键。

• Claude Code 在所有模型上都启用了任务工具，条件是环境变量或 ~/.claude/settings.json、.claude/settings.json 或 .claude/settings.local.json 的 env 块中，CLAUDE_CODE_ENABLE_TODO_TOOLS 为 1；或者启动命令在 --allowedTools 中指定了某个任务工具。开关关闭时，建议在适用于所有项目的 ~/.claude/settings.json 或仅适用于当前项目的 .claude/settings.local.json 中设置 "env": {"CLAUDE_CODE_ENABLE_TODO_TOOLS": "1"}，并说明手动创建的 settings.local.json 需要添加一行 .gitignore 规则。还要说明：默认情况下，启用工具搜索时，任务工具会延迟加载；在针对同一任务的 4 次 /poteto-mode 运行中，Sonnet 都没有保留工作清单，而在针对每个 playbook 步骤各运行 2 次、设置 ENABLE_TOOL_SEARCH=false 的情况下，Sonnet 保留了工作清单。该设置在 2026-09 的 2.1.284 版本中，使一个简单首轮的输入令牌数从 25,770 增至 45,907，因此应由用户决定是否启用。
• Codex 在 $CODEX_HOME 或 ~/.codex/ 下的 config.toml 包含 [tools.update_plan]，且其后有 enabled = true 时，启用计划工具。Codex 发布的配置参考文档没有提及此键；截至 0.158.0-alpha.2.1，其随附的 codex-rs/core/config.schema.json 将此键定义为默认值为 false。开关关闭时，建议添加这两行。Codex 不接受单独的 update_plan = true。
• Hermes 没有已知开关。报告无需更改。
• Grok Build 随附的 todo_write 工具没有已知开关。报告无需更改。

0c. 检查 Claude Code 技能列表

每当用户在 Claude Code 上运行 pstack 时，都要执行此检查。Codex 会通过 agents/openai.yaml 阻止某些 pstack 技能被隐式调用，而 Claude Code 会忽略该文件。如果没有覆盖设置，这些技能会以完整描述列出，并从描述中加载。如果在 ~/.claude/settings.json 中设置 "skillOverrides": {"<skill>": "name-only"}，Claude Code 会仅列出每项技能的名称。此时，只有在用户输入 /name 或某个 pstack 技能指示 Agent 使用它时，技能才会加载，不会通过描述加载。

按照步骤 0a 的方法解析已安装技能的根目录，然后运行：

python3 "${PSTACK_SKILLS_ROOT:?}/setup-pstack/scripts/skill-listing.py" check

失败信号：退出码为 2。设置文件无法读取或格式错误，或者技能根目录有误。报告 stderr 中的那一行，并保持文件不变。退出码为 1 表示列表已过时，stdout 中的 JSON 会在 missing 和 extra 中列出技能。退出码为 0 表示列表是最新的。报告所有 kept_off 技能，说明这是用户自行选择关闭的，并指出任何引用此类技能的 pstack 技能都无法加载它。此检查仅读取用户文件。如果项目的 .claude/settings.json 或 .claude/settings.local.json 中存在针对 pstack 技能的 skillOverrides 条目，也要报告该条目，因为项目条目可以覆盖用户文件中的设置。

如果列表已过时，请提供 install 选项，并说明它会更改什么。只有用户同意后，才用 install 替换 check，运行相同命令。该命令会为每个缺失的技能设置 name-only，替换值为 on 或 user-invocable-only 的条目；它会删除集合以外任意 pstack 技能的 name-only 条目，即使该条目是用户手动添加的也不例外。它会保留其他所有键和用户的 off 条目，并且只修改 pstack 自己的技能，因此其他套件技能的条目会保持不变。报告 added、removed 和最终的 state，并说明更改从下一个会话开始生效。

0d. 检查 Codex 子 Agent

在 Codex 上，pstack 通过 spawn_agent 原生创建角色。如果该工具不可用，pstack-harness 技能会回退到 codex exec 子进程，或逐个以内联方式运行分支；内联审查并非独立审查。如果此技能在 Codex 上运行，或用户也在 Codex 上运行 pstack，请执行此检查。

会话是否具有 spawn_agent，取决于配置之外的多个因素。自 Codex 0.160.0 起，还取决于所选模型自身的多 Agent 设置、启动标志、生成深度，以及此技能无法读取的配置层。因此，配置只能显示相关信号，只有 Codex 会话能给出答案。

• 在 Codex 会话中，答案取决于能否调用 spawn_agent。如果会话将工具隐藏在工具搜索之后，请先搜索该工具，再判断它是否缺失。如果缺失，请列出你无法排除的原因：

  • 一个配置键
  • 会话启动时使用的 -c 标志
  • 所选模型
  • 生成深度
  • 一个你无法读取的配置层

  没有证据时，不要擅自认定其中任何一个原因。

• 配置相关信号。 在项目根目录、用户启动 Codex 时所处的环境中运行 codex features list，包括任何包装器的 CODEX_HOME，并报告 multi_agent 和 multi_agent_v2 两行。然后读取 $CODEX_HOME 或 ~/.codex/ 下 config.toml 中 [agents] 的 enabled，以及项目受信任时项目的 .codex/config.toml 中的对应设置。由于 codex features list 不会报告该设置，因此还需报告这些配置项。将它们报告为信号，而非对能否生成 Agent 的定论。

• 当 codex 不在 PATH 中时，例如此技能从另一个 CLI 或应用内置的 Codex 运行时，应报告配置相关信号未经验证。实时会话的答案仍然有效。

你读取的文件中的键可能是原因，但并不能证明它就是原因，因为 multi_agent_v2 或你无法读取的配置层可能会覆盖它。只有在 Codex 会话确认 spawn_agent 缺失，且配置文件显示某个可能的原因时，才提出修改建议：

• 你读取的文件中存在 [agents] enabled = false，而 multi_agent_v2 行显示为 false，且没有更高优先级的可读文件将其设为 true（受信任项目的文件优先于用户配置）：建议删除该行或将其设为 true。如果有可读配置层覆盖了它，或相关行未经验证，则报告该键未经验证，不提供修改建议。在 Codex 0.160.0 上，即使 multi_agent 行显示为 true，此键也会移除 spawn_agent。启用 multi_agent_v2 后，此键不会阻止生成，因此不要针对它提出修改建议。
• 两个功能行均显示为 false，且你读取的文件关闭了该功能，例如 [features] multi_agent = false、带点号的 features.multi_agent = false，或旧版 [features] collab = false：建议在该文件中将其设为 true。如果该键位于用户配置中，codex features enable multi_agent 可以修复上述任一设置。如果你读取的文件中没有关闭该功能的设置，则原因在于你无法读取的配置层；应指出这一点，而非建议修改。

[features]
multi_agent = true

只有在用户同意后才能编辑文件，并保留其他所有键。修改将在下次会话生效。如果没有会话可供确认，请报告相关信号和可能原因，说明生成能力未经验证，且不要提供修改建议。

0e. 设置仓库 PR 模板

如需在 Git 仓库中完成完整设置，请遵循 references/pr-template.md。保留现有仓库模板和明确指定的选项。如果没有现有模板，则安装随附的 poteto 模板；如果已配置 no-mistakes，则通过 pr.template 选择该模板。报告更改的文件，以及受信任的默认分支激活是否仍待处理。若不在仓库中，或请求仅修改模型、预算或主机设置，则跳过此步骤。

1. 检测可用模型和推理力度

枚举当前会话的生成机制接受的模型值，以及每次生成可接受的推理力度值（使用 pstack-harness 技能查找该机制）。在 Claude Code 中，每次生成可用的推理力度，是实时目录列出的 pstack-effort-<level> Agent 所对应的级别；如果没有加载任何推理力度 Agent，则没有可用级别。这是可靠的信息来源。如果你的 CLI 还提供模型 API 或命令（例如 codex debug models 或 grok models）来列出用户有权限使用的模型，则优先使用，以确保完整性。如果无法检测到任何模型，请让用户粘贴他们有权限使用的模型标识。切勿填写尚未确认可用的真实模型标识。别名 inherit-parent 和 auto 始终有效，即使它们不是检测到的模型标识。

2. 加载当前状态

默认映射位于此技能旁边的 examples/pstack-models.md。如果两个配置层都存在，请读取两者及其 harness 部分：先读取工作区的 .agents/pstack-models.md，再读取 ~/.agents/pstack-models.md；并将每个角色的配置行以及正在配置的文件中的 # budget 行视为当前选项。--resolve --harness <this CLI> 会打印各角色在此处的运行方式。否则，请从默认配置开始。除非用户要求按仓库覆盖，否则应配置用户级文件。按照模型配置语法，在预算和映射步骤中保留 trail reviewer step 设置。删除 examples/pstack-models.md 中不存在的角色配置行，例如 how critics。

3. 预算、映射并确认

(a) 询问预算。 优先使用 AskQuestion，而非自由文本。提供以下五个选项，标签必须完全一致，并在文件记录了当前预算时指出该预算。如果没有文件，请说明 default 会保留随附的默认设置。第一个选项是新增的移植选项，其他四个与上游一致。

• default — keep as written
• unlimited — max reasoning
• large — xhigh reasoning
• medium — high reasoning
• small — medium reasoning

在 Claude Code 中，将 default — keep as written 描述为“未明确设置推理力度的角色会使用当前会话的推理力度”，并在询问时说明：加载推理力度 Agent 后，预算后缀会覆盖当前会话的推理力度，既可调高，也可调低。

(b) 应用预算。 根据 examples/pstack-models.md 构建工作表；重新运行时，保留用户通过模型、推理力度、列表、别名（inherit-parent、auto）或 harness 部分修改过的任何角色。default 不应用预算：每个已写入的 @effort 后缀都保持不变；未带后缀的条目则遵循 references/models-config.md 中的推理力度策略，在 Claude Code 中即使用当前会话的推理力度。unlimited、large、medium 和 small 会将每个实际条目（包括面板条目和 harness 部分）的 @effort 分别设为 max、xhigh、high 或 medium；如果条目没有后缀，则添加后缀。如果第 4 步中的 lint 不接受该模型的此推理力度，则使用该模型所支持且不高于目标的最高推理力度。lint 无法识别模型的条目保留原有推理力度，或继续不带后缀；第 (c) 步会将其列为未修改。带后缀的别名（例如 auto@max）也会按相同规则改写后缀，因为 Codex 支持别名后缀。单独使用的 inherit-parent 或 auto 不变。任何预算都不会更改模型或列表长度。因此，small 会将 fable 改为 fable@medium，并将 gpt-6-sol@max 改为 gpt-6-sol@medium；unlimited 则会将二者都改回 fable@max 和 gpt-6-sol@max。在 Claude Code 中，只有加载了推理力度 Agent 时，已写入的后缀才会生效。如果实时目录中没有这些 Agent，请说明这一点。这些后缀仍会对读取同一文件的 Codex 和 Hermes 生效；在此处，子 Agent 会使用当前会话的推理力度，直到注册这些 Agent 且目录将其列出为止。 (c) 展示各角色并确认。 该文件由多个 CLI 共用，因此此运行环境无法验证的值并不代表它有误——那可能是另一个运行环境的选择（在此处显示为 inherit-parent）。展示此运行环境中的每个角色及其模型和 effort；对于不在检测到的集合中的值，标注为“（为另一个运行环境设置——除非你修改，否则予以保留）”，而不是提示用户需要选择。在 Claude Code 中，如果角色没有写明 effort，则显示为 session；如果实时目录中没有该角色的 agent，则将写明的 effort 标注为“（effort agent 加载前不会生效）”。同时列出第 2 步删掉的每一行。询问用户是接受当前设置，还是修改特定角色；提供检测到的模型，以及 inherit-parent 和 auto 作为选项（两者都表示：该角色使用父级聊天模型运行，这是 Auto 用户保持使用 Auto 的方式）。优先使用 AskQuestion，而不是自由文本。对于面板角色（arena runners、architect runners、interrogate reviewers），值是一个列表，每个子 Agent 条目（包括别名条目）运行一个，因此列表长度决定数量。arena cross-judge pool 也是一个列表，但 Arena 会尽可能从中选择一个模型系列或能力等级与父级不同的值。除非竞速或比较任务为每个分支指定了其他模型，否则 swarm workers 会按 swarm 技能运行所有会执行任务的 swarm worker。trail reviewer 会运行 show-me-your-work reviewer，以及每个独立的 verdict 和 review，包括 swarm 的审计通道。除非调用它的技能指定了其他角色，否则 routine 会运行所有只读扫描、解析或监视子 Agent，并返回精简后的发现结果。其适用范围请参阅模型配置参考。从工作表中展示它的模型和 effort。关于 reviewer 的解析和模型选择，请参阅模型配置规则 7。同时展示工作执行时会运行的 reviewer。解析 feature 和 refactoring，并根据打印出的每个分支构造一个 <model>@<effort>。如果模型是 inherit-parent（auto 打印出的值），则使用会话模型，也就是系统提示词或此 CLI 的配置为该会话指定的模型 ID，例如 claude-opus-5-5。如果 effort 是 inherit-parent，则使用会话 effort；如果无法确定，则省略 @<effort>。保留写明的 effort，例如 auto@max 中的 max。完成这些替换后，删除重复项。然后，对于每个剩余值，运行一次 python3 <this skill's directory>/scripts/check-models-config.py --resolve --harness <this CLI> --work-model '<model>@<effort>' "trail reviewer"；每次运行只使用一个 --work-model 标志，因为解析器只保留最后一个标志。如果某次运行在 --work-model 上以 2 退出，则根据生成角色第 2 步修正该值，例如删除 [1m] 后缀，并重新运行。如果仍以 2 退出，则不带 --work-model 运行，并说明预览中没有步骤，因为解析器拒绝了会话模型。每次运行对应的行都以 when work runs on <value> 结尾，其中 <value> 是传入的确切值。如果模型来自会话，则在后面添加 (session model)。如果分支带有 step，则同时显示写明的值和经过 step 处理的值，例如 trail reviewer: gpt-6.1-sol@xhigh → gpt-6-astra@high when work runs on gpt-6-sol@high，并转述其说明。否则，只显示该分支。使用模型配置规则 7解释 effort 和固定模型的行为。只有当用户想固定 reviewer 时，才提供 trail reviewer step: off。关于执行身份披露，请遵循生成角色。default 是任何未由技能指定角色的 spawn 所使用的条目；除非用户希望未映射的 spawn 使用特定模型，否则将其保留为 inherit-parent。

4. 验证

写入文件前，先对准备写入的文件运行 lint：python3 <this skill's directory>/scripts/check-models-config.py <file>。任何 error: 行（未知角色、无效的 effort、不受模型支持的 effort、重复的角色或章节、## claude-code 下的 none 或 ultra）都会阻止写入；请修正该行并重新运行。notice: 行表示固定使用 max 或 ultra，而单独一行的 none 或 ultra 表示 Claude Code 会在本次会话中使用该 effort。逐条向用户复述每一项，让用户明确选择高成本档位或 Claude Code 回退方案。每个新选定的有效 slug 都必须在检测到的集合中。inherit-parent 和 auto 始终通过检查，其他执行框架中保留的值不受此限制。如果选定的有效 slug 不可用，请停下并再次询问。Lint 通过后，在此处向用户展示每个角色将使用的配置。对于用户级文件，从项目根目录运行 python3 <this skill's directory>/scripts/check-models-config.py --resolve --harness <this CLI> --user-file <file>，该命令也会应用其中的工作区文件。对于仓库级覆盖，将草稿复制到 <temp>/.agents/pstack-models.md，并传入 --project <temp>，这样实际的用户级文件就会保留在下层。接着，对于步骤 3c 会针对该文件传入的每个 --work-model 值，分别运行一次 "trail reviewer"；按照步骤 3c 的说明展示每一行，让用户在写入前了解该行的作用。

5. 写入配置

目标文件为 ~/.agents/pstack-models.md；如果用户要求仓库级覆盖，则目标为工作区中的 .agents/pstack-models.md（只写入用户确实想为此仓库固定使用的角色——工作区中的每一行都会覆盖用户级对应配置）。工作区文件中的 # budget 行只适用于该文件中写出的角色。仍从 ~/.agents/pstack-models.md 解析的角色沿用该文件中的预算。如果文件工具无法写入目标位置（例如执行框架将写入范围限制在工作区内），请依次尝试：通过 shell 工具写入；否则写入工作区文件，并说明该配置仅适用于当前项目，直到复制到 ~/.agents/；否则打印最终内容供用户保存。绝不能悄悄放弃写入。

写入文件时，包含一行 # budget，其中注明选定的标签及其目标 effort，并为每个角色各写一行，使用 poteto-mode 使用的相同标签。以该技能旁边的 examples/pstack-models.md 为基础，并保留其中的标头注释，只替换预算行的值。重写整个文件，以确保重复运行时结果一致；但要保留用户未更改的所有现有行，包括此执行框架无法验证的章节和值。覆盖其他 CLI 的选择并将其改为 inherit-parent 是唯一必须避免的失败情况。删去步骤 2 已移除的退役角色行。将针对特定执行框架的选项放在其 ## <harness> 章节下，并保留供其他 CLI 使用的单独行。格式示例（节选）：

# budget: default (keep as written)
feature, refactoring: sonnet
bug-fix: sonnet

## codex
feature, refactoring: gpt-6-sol@high
bug-fix: gpt-6-sol@xhigh

6. 确认

告知用户配置已写入，技能会在下次运行时读取该配置。再次运行此技能即可更新配置。

7. 提供验证技能（可选）

检查项目是否有方法驱动真实应用进行验证（verify-* 技能或现有执行框架）。如果没有，只询问一次：“想要一个项目级验证技能，让 Agent 能像用户一样操作应用并验证更改是否生效吗？我可以用 /create-verification-skill 生成一个。”如果用户同意，请使用 create-verification-skill 技能。如果用户拒绝，就继续，不要施压。

8. 提供形式化验证技能（可选）

检查项目是否已有形式化验证技能（即对代码运行模型检查器、证明或其他验证器的项目技能）。如果没有，只询问一次：“想要一个形式化验证技能吗？这样，Agent 就能证明代码的某项关键属性在范围内的所有情况下都成立，而不只是测试覆盖到的情况。我可以用 /create-formal-verification-skill 生成一个。”如果对方同意，请使用 create-formal-verification-skill 技能。如果对方不同意，就继续，不要再劝。