用途
setup-pstack 用于为 pstack 工作流的各个角色配置所使用的宿主支持角色或模型。它遵循可移植运行时契约，检测当前宿主实际提供的模型与委托能力，并把可移植的项目本地配置写入文件。该配置是可选覆盖层，而非强制要求。
配置路径
当环境变量 PSTACK_CONFIG 被设置时，配置写入该变量指定的路径；否则使用当前项目下的 .pstack/config.md。技能明确要求不得写入厂商专属的 home 目录。
模型发现与模型分配是两种不同能力
被 pi --list-models 列出的模型对当前 Pi 进程可用，但这并不意味着某个工作流可以把工作发送给它。按角色分配还需要宿主提供接受模型选择的任务或子智能体设施。原生 Pi 有意不包含子智能体。当该设施缺失时，不要声称某角色已被分配。
委托前置条件
Pi 委托前置条件
对于原生 Pi，当用户需要并行 worker 或按角色指定模型时，推荐使用维护中的 pi-subagents 包：
pi install npm:pi-subagents
安装后告知用户重启 Pi，然后运行 /subagents-doctor。仅当子智能体工具与预期 agent 可见时才继续设置。该包提供委托设施，但它本身并不决定 pstack 的模型策略。
OpenCode 委托前置条件
OpenCode 有自己的原生 primary 和 subagent agent。当前宿主为 OpenCode 时，不要安装 pi-subagents，也不要写入 Pi 专属设置。使用 OpenCode 报告的 agent 和具体的 provider/model-id 选择，并将其模型配置保留在宿主的 opencode.json 或 opencode.jsonc 中。如果 OpenCode 未暴露可用的 subagent，应报告该限制，而不是替换为 Pi 专属机制。
步骤
1. 检测可用选项
分别独立检测以下两项：
- 当前宿主实际暴露的模型 ID。
- 当前宿主是否暴露可为每个子任务选择模型的任务或子智能体设施。
对于 Pi，pi --list-models 是模型清单，provider/model-id 形式是要记录的具体值。安装 pi-subagents 后，子智能体工具与 /subagents-doctor 确立委托清单。实时宿主清单是权威来源。绝不要从文字描述中复制厂商 slug，或猜测某模型可用。
如果宿主有任务设施但无法枚举模型，只使用该设施文档中记载的宿主角色映射。不要让用户凭空编造原始 slug。inherit-parent 仅当宿主能把当前模型传给子任务时才有效。
2. 加载当前状态
当所选配置路径存在时读取它，并将其中的具体值视为当前选择。如果它只包含来自不具备按子任务委托能力的宿主的可移植角色别名，应将这些别名视为失效的非活动状态，并从检测到的模型重新开始，而不是把它们带入 Pi 的 agent 覆盖中。
3. 映射并确认
如果模型清单与按子任务模型选择都可用，展示每个工作流角色及其当前的 provider/model-id 选择。将实时清单中不存在的显式模型标记为需要替换。请用户接受或更改选择，只提供检测到的模型 ID 以及（若支持）inherit-parent。可用时使用宿主的结构化交互工具；否则在普通对话中一次提出一个聚焦问题。
如果宿主暴露模型但没有任务或子智能体设施，应给出明确的能力报告并停止模型映射。对于原生 Pi，推荐 pi install npm:pi-subagents、重启以及 /subagents-doctor。对于 OpenCode，说明其原生 agent 不可见或未配置，并引导用户查看宿主的 agent 配置。对于其他任何宿主，指出缺失的能力，不要提出厂商专属替代方案。说明在此会话中没有 pstack 角色可以接收不同模型，且不要把可移植默认值呈现为已分配，也不要用非活动别名覆盖已有的角色配置。
对于 panel 角色（critics、arena runners、arena cross-judge pool、architect runners 和 interrogate reviewers），每个条目运行一个子任务，因此列表长度控制扇出。对判断敏感的 panel 优先考虑多样性。swarm workers 是每个 worker 的默认选择，除非某次竞速按 arm 指定了不同选择。
4. 校验
写入的每个显式模型都必须存在于检测到的宿主清单中。角色别名仅当宿主任务设施文档记载这些别名时才通过。inherit-parent 仅当宿主能把当前模型传给子任务时才通过。如果选定的显式模型不可用，停止并请求替换。绝不写入需要另一宿主的配置。
5. 写入配置
当宿主支持按子任务选择时，必要时创建父目录并覆盖所选文件，以使重复运行保持幂等。使用检测到的具体模型 ID，格式如下。将每个占位符替换为当前宿主报告的模型，并且仅在宿主支持时使用 inherit-parent：
# pstack role and model configuration
# Values are concrete provider/model-id choices confirmed by the host.
feature, refactoring: <implementer-model>
bug-fix: <reviewer-model>
perf-issue: <reviewer-model>
hillclimb: <implementer-model>
judgment and prose: <reviewer-model>
hardest tasks: inherit-parent
how explorer: <explorer-model>
how explainer: <synthesizer-model>
how critics: <reviewer-model>, <planner-model>, <designer-model>, inherit-parent
why investigators: <researcher-model>
why synthesizer: <synthesizer-model>
reflect tooling: <researcher-model>
reflect judgment: <reviewer-model>
reflect divergent: <designer-model>
reflect synthesizer: <synthesizer-model>
arena runners: <designer-model>, <planner-model>, <implementer-model>, inherit-parent
arena cross-judge pool: <reviewer-model>, <planner-model>, <designer-model>, inherit-parent
swarm workers: <implementer-model>
architect runners: <designer-model>, <planner-model>, <reviewer-model>, inherit-parent
interrogate reviewers: <reviewer-model>, <planner-model>, <designer-model>, inherit-parent
对于带 pi-subagents 的 Pi，还要保留无关键，并用发现到的子智能体名称对应的具体模型分配更新项目的 .pi/settings.json。除非用户选择不同 agent，否则使用以下映射：
| pstack role | pi-subagents agent |
|---|---|
| explorer, watcher | scout |
| researcher | researcher |
| implementer, mechanical | worker |
| reviewer | reviewer |
| planner, designer, synthesizer | oracle |
| owner | delegate |
将所选 ID 写入 subagents.agentOverrides.<agent>.model：
{
"subagents": {
"agentOverrides": {
"scout": { "model": "<explorer-model>" },
"researcher": { "model": "<researcher-model>" },
"worker": { "model": "<implementer-model>" },
"reviewer": { "model": "<reviewer-model>" },
"oracle": { "model": "<planner-model>" },
"delegate": { "model": "<owner-model>" }
}
}
}
对于 OpenCode，不要写入 .pi/settings.json。将具体模型选择保留在用户现有的 opencode.json 或 opencode.jsonc 中，并在 pstack 角色映射中使用实时 OpenCode agent 名称。保留无关配置。
6. 确认
如果写入了具体配置，告知用户确切的路径，并列出分配给各角色族的模型 ID。对于 Pi，同时指出 .pstack/config.md 和 .pi/settings.json，并告知用户运行 /subagents-models 以检查实时映射。对于 OpenCode，指出所用的 opencode.json 或 opencode.jsonc 路径。说明配置不会创建模型、子 agent、权限或委托设施。
如果宿主缺少按子任务模型选择，报告未写入或激活任何角色配置。告知用户当前处于活动状态的是哪个模型，以及如何切换单个 Pi 会话模型。
7. 提供验证技能（可选）
检查项目是否有驱动真实应用以进行证明的方式，例如 verify-* 技能或已有 harness。如果没有，提供一次调用同级 create-verification-skill 技能的机会。若用户拒绝，继续而不强推。
适用场景
- 需要在 Pi 或 OpenCode 上按 pstack 工作流角色分配不同模型的用户。
- 需要生成可移植、项目本地的 pstack 角色/模型配置文件。
- 需要根据宿主实时能力报告缺失的委托设施，而非凭空配置。
限制
- 不创建模型、子 agent、权限或委托设施。
- 不写入厂商专属 home 目录。
- 显式模型必须存在于检测到的宿主清单中。
- 原生 Pi 不包含子智能体，需额外安装 pi-subagents。
- 未提供的信息：具体支持的宿主机完整列表、pstack 本身的安装方式、各角色默认使用的模型名称、收费与价格信息暂未提供。