setup-pstack

设置 pstack

为当前父级运行环境配置一份可移植的模型表。在进行探测或写入前，请阅读 provider-dispatch.md 和模型目录。分发规则、描述符语法，以及目录中的模型矩阵、保留的前代版本和路由表共同构成约定。为分配到的每个矩阵系列选择一个所需的工作量级别。不要添加第二个配置文件、运行时解析器或较弱模型回退。

根据运行环境的 config-home 规则解析一次 <config-home>。所有当前状态读取、写入、快照、恢复和回读操作都使用它。

Claude Code 将 <config-home>/pstack-models.md 写入文件，并根据第 8 步的导入规则从 <config-home>/CLAUDE.md 加载它。当 <config-home> 是默认主目录时，必须准确写入以下旧版行：

@~/.claude/pstack-models.md

仅当 CLAUDE_CONFIG_DIR 重定向了主目录时，才准确写入 @./pstack-models.md，其路径相对于导入文件所在目录。

Codex 将 <config-home>/pstack-models.md 写入文件。Codex 不支持 @ 引入，因此要在 <config-home>/AGENTS.md 的一个有界代码块中镜像该表的精确字节，并保留该表作为可编辑的事实来源：

<exact contents of the resolved model sheet>

步骤

1. 确定父级运行环境

使用运行此技能的运行环境和工具界面：Claude Code 或 Codex。环境标记可用于佐证这一顶层判断，但不要启动子进程并询问它来自何处。记录父级运行环境，因为同一描述符在不同运行环境中会采用不同路由。

2. 加载当前状态

检查 <config-home>/pstack-models.md 和现有集成：解析 Claude 的单一模型表导入，或读取 Codex 的单个有界模型块；报告缺失的目标，并在状态不可读、格式错误或存在歧义时停止。使用唯一留存的配置；若两份配置一致，则使用可编辑的模型表；在 Codex 中，模型表仍是权威来源，而代码块是它的镜像；若模型表缺失，可从代码块恢复。如果留存的配置不一致，则显示两个来源及其不同的配置项，并要求明确选择来源，然后才能进行规范化或探测；不要自动合并。仅当两个来源都不包含可恢复的配置时，才使用首次运行默认值；随后对所选状态应用现有的规范化、角色补全和验证规则。在验证矩阵之前，仅规范化目录保留的前代版本与规范化中所列的滚动别名的带版本前代版本。按以下顺序匹配：精确的模型矩阵行、保留的前代版本、滚动别名修订版。模型若本身就是矩阵中的一行（例如已注册的精确固定版本），则绝不能迁移。任何其他带提供方限定符的 Claude 模型，只要其模型组成部分以某个滚动别名的带版本前代前缀开头，且其余修订部分仅包含数字和连字符，即可迁移。在内存中将该组成部分替换为别名，同时保留提供方、工作量级别、角色和通道顺序。记录每个原始描述符及规范化后的描述符，供第 7 步确认。这种迁移属于有效的已加载状态，无需操作员另行选择。

codex writer sandbox: full-access 或 codex writer sandbox: bounded 这一行是设置，不是角色；Codex writer sandbox 说明父级运行环境如何使用它。在角色叠加、已弃用角色规则和描述符验证之前，先将其单独处理，并在第 6 至第 8 步中保留它。出现第二行设置，或使用其他值，都表示状态不一致。 将规范化后的值视为当前的角色到系列分配。将这些行叠加到完整的首次运行角色映射上，即目录中的角色默认值。下次成功写入时，根据该映射补全任何缺失的已记录角色行。角色行重复属于不一致状态；报告并在探测前解决。如果某行的角色不在角色默认值中，例如 how critics，则该角色已弃用。删除该行，并在确认时列出。如果旧版表格中有不带提供商信息的原生主机 slug，同样无效，因为它没有说明归属哪个提供商。若某个带版本号的 Claude 模型与任何矩阵行、保留的前代模型或滚动别名都不匹配，则仍属于不一致状态。其 (provider, model) 是保留的前代模型的值不属于不一致状态。重新运行时，建议将每个出现的此类模型替换为该系列当前模型，并保持 effort 不变，然后询问是否同意。如果操作者拒绝，那么在步骤 3 到 7 中，该系列仍使用保留的前代模型：对其进行探测、渲染，并原样写入。如果表格不存在，则根据角色默认值初始化，其中的描述符沿用模型矩阵的 Default effort 单元格。

然后询问是保留这些角色到系列分配，还是更改指定角色。默认保留。仅应用操作者明确指定的角色更改；绝不要提出将自定义表格重置为首次运行分配。如果更改角色，它可以使用模型矩阵中的任何系列、inherit-parent 或 auto。

如果加载的状态没有设置行，则询问一次：外部运行器启动的 Codex writer lanes 是否应使用 Codex 的完整访问权限沙箱。说明完整访问权限允许 writer 启动浏览器并写入 .agents/ 等点目录，同时会移除所有沙箱限制，包括将文件系统访问限制在工作树内的约束。默认选择拒绝。如果操作者同意，则记录 codex writer sandbox: full-access；如果拒绝，则记录 codex writer sandbox: bounded，这样重新运行时就不会再次询问。如果该行已存在，则除非操作者明确要求更改，否则保持不变，并且不要询问。

3. 按模型系列整理工作量

阅读目录中的模型矩阵和保留的前代型号。每个非别名角色值都必须符合 <provider>:<model>@<effort>。根据 (provider, model) 将其精确映射到一个矩阵模型系列；如果匹配的是保留的前代型号，则映射到其所属系列；要求其工作量出现在该行或保留前代型号所在行的 Selectable efforts 单元格中，并收集该工作量。对于 Selectable efforts 单元格未列出 ultra 的所有行，拒绝 ultra。inherit-parent 和 auto 行不携带模型系列工作量。

以下角色对应的工作通道会写入文件：feature, refactoring、bug-fix、perf-issue 和 hillclimb，其操作手册会通过 isolated-write 委派；hardest tasks，负责处理最艰巨的代码更改；以及 arena runners、architect runners 和 swarm workers，它们会写入自己的工作树或输出目录。如果上述任何角色使用的提供商，其路由表中的 Access modes 单元格缺少 isolated-write，则拒绝该角色：指出角色和提供商，并说明原因。运行器会在启动前拒绝该提供商的写入通道，因此第 5 步中的只读探测会通过，但该角色会在分派时失败。请为该角色改用其他模型系列或别名，并在更改之前不要进行探测或写入。其他所有角色都可以使用只读提供商。

未匹配的提供商/模型、超出允许范围的工作量或重复角色都属于不一致状态。停止操作，逐字显示冲突行，并要求明确指定矩阵模型系列或替换别名。如果一个或多个模型系列的工作量不一致，显示每个冲突模型系列及其角色行，然后要求为每个模型系列选择一个可从其 Selectable efforts 单元格中找到的统一工作量。不要自行设定优先级规则。任何不一致尚未解决时，都不要探测或写入。

每个模型系列只有一个不同工作量时，该值即为当前值。没有非别名实例的模型系列为未分配：不要询问其工作量、检查其 CLI 或探测它。若第 2 步的角色更改新分配了某个模型系列，则以其矩阵中的 Default effort 作为建议值。

4. 为每个模型系列收集一个所需工作量

为每个已分配的模型系列询问一个工作量。注明每个模型、其当前值或建议值，以及其矩阵行中的 Selectable efforts。若某个模型系列唯一可选的工作量是 default，则不询问工作量。输入为空时保留该值。首次运行时，在提问前说明已分配模型系列的矩阵默认值。重新运行时，说明解析出的值，但不要提议重置已自定义的角色通道。

5. 探测所需的组合

在检查外部 CLI 的可用性/身份验证或探测模型之前，先通过此父级的路由表解析所选模型系列。对于 Codex 父级，列出已分配的外部模型系列，并检查父级的有效权限指令，确认网络访问权限，以及各提供商说明中列出的状态路径和主机前提条件，包括任何必需的工作区外写入。不要检查凭据内容，也不要尝试被拒绝的写入来确认权限。父级自身环境中的 CODEX_SANDBOX_NETWORK_DISABLED=1 表明外部 CLI 的网络访问已禁用；请在清理子环境变量之前检查此项。CODEX_SANDBOX 标识沙箱后端，不代表完整的权限策略。缺少标记、配置文件中的偏好设置，或仅有 workspace-write 这一名称，都不能证明权限充足。应依据有效会话权限和所需路径判断，不要一概禁止所有工作区外路径。

如果所需访问受阻，请在调用相应 CLI 之前说明受影响的已分配模型系列和限制。如果权限信息不可用或不完整，则将其标记为未知，说明哪些所需访问无法确认，并在进行外部检查或探测前解决该问题。如果访问受阻或仍属未知，恰好提供两种路径：

1. 由操作员审慎选择合适的权限重启父进程；停止本次设置，不写入任何内容。请参阅 provider-dispatch 的 主机和父进程前置条件，其中包括 Grok 的嵌套沙盒限制。
2. 明确为此父进程选择仅使用原生方式的角色分配。列出每个受影响的角色及建议的替代项，并获取操作员明确指定的变更，然后返回步骤 2–4，验证修订后的映射和工作量，再进行原生探测。在 Codex 上，codex 提供方的系列属于原生方式；inherit-parent 和 auto 也保持原生方式。不得自动更改任何通道、降低其工作量，也不得为现在未分配的系列启动外部 CLI。说明提供方多样性的任何降低。

如果所有选定系列都采用原生方式，则无需检查外部 CLI 权限或进行探测；但仍须单独进行最终写入检查。当有效权限允许所选的外部通道时，按现有路由和请求的工作量继续操作，不作更改。不得在设置过程中更改沙盒设置或提升权限。

只探测每个已分配系列所选的 provider:model@effort 组合。角色映射表中的每个系列运行一次探测，即使两个系列共用同一提供方也如此。不得枚举或提供较旧模型作为替代项。探测失败时不写入任何内容：报告失败的组合和提供方，然后停止，并保持活动工作表及父进程集成字节不变。首次运行失败时不会创建任何产物。

如果 Grok 探测因主机无法强制执行其有界沙盒而失败，请参阅主机和父进程前置条件；保持活动配置不变。

在路由表中查找该系列对应的提供方。原生路由使用原生单轮探测：在 Claude Code 上使用该系列的 pstack-<family>-<effort> 代理；在 Codex 上使用 spawn_agent，并设置描述符中的模型和 reasoning_effort。外部路由使用一次 pstack-runner 调用，并提供简短的只读探测提示词。运行器的预检会检查 CLI、登录状态和模型，其回执即为结果。

使用简短的只读探测，返回一个唯一标记。仅运行登录状态命令只能证明凭据有效，无法证明所请求的模型和工作量标志能够运行。分别记录原生和外部探测结果。绝不为父进程自身的提供方调用外部启动器。

回执和原生对话记录可证明所请求的工作量和路由，但无法证明提供方实际采用的隐藏推理深度。不会隐式设置超时、回退到较弱模型、回退到同一提供方的外部方式，也不会使用第二个可变配置源。

6. 渲染并保留角色系列

在内存中构建新工作表。暂不写入。

• 首次运行：从目录中的角色默认值开始，并应用步骤 2 中的角色变更。
• 重新运行：从步骤 2 得出的规范化完整角色映射开始，并应用步骤 2 中的角色变更，同时保留每一行已加载通道的顺序，以及各通道的系列（或别名）。

如果已加载的工作表中有步骤 2 的设置行，则保留该行的位置。若步骤 2 添加此设置行，则将其放在最后一条角色行之后。

将每个矩阵系列描述符重写为 provider:model@<该系列请求的工作量>，使用步骤 2 中为各系列选定的模型。保持 inherit-parent 和 auto 不变。仅更改工作量的重新运行不得更改角色所属系列。更改 Grok 的工作量时，需更新所有 Grok 条目，且不得将 Sol 角色移至 Grok。若提供的 slug 未限定、路由不可用、模型不在模型矩阵及其保留的前代版本中，或提供方与模型不匹配，则拒绝操作。

7. 确认并提交

将滚动别名迁移显示为原始描述符和规范化后的描述符，并显示步骤 2 中删除的所有已退役角色行。然后显示步骤 2 中读取的源文件、新目标 <config-home>/pstack-models.md、此父级的路由表、每个渲染后的角色和描述符，以及设置行。将已加载的分配沿用到新目标中；只有明确的角色或 effort 变更，以及文档记录的规范化操作可以更改这些分配。写入前请先征求确认。

Why 和 Reflect 需要父级的实时 MCP 接口。将它们的 investigator、reviewer 和 synthesizer 角色保持为 inherit-parent 或 auto；有界外部 runner 会有意省略环境 MCP。inherit-parent 和 auto 始终会通过验证，但如果它们降低了面板的提供方多样性，请予以说明。对于面板角色，每个条目运行一个 lane。列表长度就是 fan-out 数量。arena cross-judge pool 是一个列表，Arena 会从中选择与父级和基础候选项不同的提供方（如果可行）。swarm workers 是每个 worker 的默认值，除非某个 race 明确指定了其他描述符。

所有非别名角色值都必须符合 <provider>:<model>@<effort> 格式，并且必须已通过步骤 5 的验证。

操作员确认后，分别检查父级对两个实际目标（表格文件和父级集成，设置 CODEX_HOME 时需通过该变量解析）以及所需目录创建操作的有效写入权限。将两个产物渲染到内存中，并在首次写入或创建目录之前完成此检查。原生探测成功并不代表获得了配置写入权限。受限父级仍可能被允许在 CODEX_HOME 下写入；应评估每个解析后的目标，不要仅因其位于工作区之外就拒绝。如果任一目标被拒绝或权限仍未知，请针对该目标说明原因并停止：保留所有现有产物的字节内容不变；如果是首次运行，则不创建任何产物。不要通过覆盖目标来测试权限，不要只写入获准的产物，也不要自动请求权限提升。

只有在两个目标都获准后，才使用步骤 8 的快照和回读流程，写入步骤 6 中渲染到内存的内容。绝不要将角色默认值直接作为结果粘贴。这些默认值仅用于填充步骤 2；选定的 effort 和明确的角色变更必须始终在写入前替换对应值。

8. 写入配置

在写入任何一处之前，先在内存中渲染父级集成配置。

对于 Claude，集成配置是 <config-home>/CLAUDE.md 中唯一一行 @ 导入，其目标的 basename 为 pstack-models.md，无论其现有目录或路径写法如何。当 <config-home> 为默认主目录时，渲染为 @~/.claude/pstack-models.md，保留旧文本。只有在 CLAUDE_CONFIG_DIR 重定向了主目录时，才渲染为 @./pstack-models.md。此相对导入路径以导入文件所在目录为基准解析，模型表也位于该目录中，因此导入行不包含任何配置目录字符。重新运行时，在原位置替换该行，并保留所有无关字节。如果不存在匹配的导入行，则追加一行。如果存在多个匹配项，则在写入任何一处之前停止并报告状态不一致；不要再追加导入行，也不要猜测要替换哪一行。

对于 Codex，集成配置是 <config-home>/AGENTS.md 中位于一对 和 标记之间的完整模型表字节。重新运行时，替换整个标记块。首次运行时，在文件末尾插入一个块。如果任一标记缺失、重复或顺序颠倒，则停止并报告状态不一致，不要猜测边界。

对每个目标的当前字节创建快照。只有所有请求的模型对均通过且操作者确认后，才写入模型表和父级集成配置。写入后重新读取两个目标，并与内存中的渲染结果比较。如果任一写入或回读失败，则恢复所有快照并报告失败。经过规范化后，未发生变化的重新运行必须生成字节完全一致的模型表和集成配置内容。

不要在不同运行环境之间复制模型表而不重新执行特定于父级的探测；即使在同一主机上，路由可用性也可能不同。

9. 行为冒烟测试

在宣布设置完成之前，从此父级运行一个小型只读混合面板：包含每个不同的已选描述符、彼此不同的输出/回执路径，以及一个独立的交叉评审器。将 Claude 原生 Agent 和所有外部进程在后台启动并保留句柄，然后收集其结果。验证原生转录条目和每份外部回执。结构化配置检查或单元测试不能替代此步骤。

报告模型表路径、父级路由表、请求的工作量探测结果、冒烟测试结果，以及外部耗时／令牌／成本回执。重新运行此技能会重新探测并更新同一模型表。不要声称提供方暴露了隐藏的已应用工作量可观测性。