gstack o-series 模型行为覆盖层：为 OpenAI 推理模型定制的 SKILL 行为补丁

gstack 通过「模型行为覆盖层」（model overlay）机制，针对不同 LLM 家族向生成的 SKILL 文档注入行为校正指令。本文以 model-overlays/o-series.md 为核心，完整解读这三条面向 OpenAI o 系列推理模型（o1/o3/o4 等）的行为规则，并结合仓库源码说明覆盖层如何被解析、包裹和注入到每个生成技能中，读者最终能掌握 gstack 的 overlay 机制全貌，以及如何用 --model 参数为任意模型族生成定制化的技能文档。

一、o-series 覆盖层：三条行为规则

model-overlays/o-series.md 是纯 Markdown 文件，全文由三条加粗标题引导的行为指令组成。它们是「补丁」而非硬性规则——解析器在注入时会附带从属声明（见第二节），模型应将其视为偏好而非规则。以下逐条继承原文并展开。

1.1 Reasoning model behavior：用推理，但不暴露推理链

原文要求：

你有强大的内部推理能力。要使用它，但除非用户要求看到你的推理，否则不要在输出中暴露思维链（chain-of-thought）。给出结论加证据，而不是推理链本身。

这条规则针对 o 系列模型的核心特性——推理型（reasoning）模型在回答前会进行内部思考。gstack 的立场是：

• 内部推理照常进行：不剥夺模型的推理能力；
• 输出侧收敛：默认只呈现「结论 + 证据」，把推理链藏起来，避免终端用户在 SKILL 执行过程中被大段中间思考淹没；
• 用户主权保留：用户明确要求看推理时再展示，规则本身不是一刀切的静默要求。

这解释了为什么 o 系列模型在 gstack 技能中默认输出「结论先行」式的回答结构。

1.2 Structured outputs preferred：结构化输出优先于散文

原文要求：

呈现分析时，优先使用表格或要点列表，而非散文段落。散文用于解释和上下文；结构用于发现（findings）、选项（options）和对比（comparisons）。

这条规则给 o 系列的输出划定了一条文体分界线：

内容类型	推荐形式
发现、结论（findings）	表格 / 要点列表
选项（options）、对比（comparisons）	表格 / 要点列表
解释、上下文、背景	散文（prose）

这与 gstack 整体文档风格一致：SKILL 文档中大量使用表格组织决策矩阵和状态清单。对 o 系列模型而言，这条规则意在抑制其在分析性输出中倾向于长段落铺陈的倾向。

1.3 Completion bias：完成倾向，但服从安全门禁

原文要求：

当完整方案可达时，不要停留在部分方案上。但技能工作流的 STOP 点、AskUserQuestion 门禁和 /ship review 门禁，永远优先于完成倾向。

这条规则是三条中唯一带有优先级约束的，也是理解 gstack overlay 设计哲学的关键：

• 完成倾向（completion bias）：o 系列模型在 gstack 工作流中被鼓励「做到底」——不要交半个方案就结束回合；
• 但从属于（subordinate to）：技能工作流中显式的 STOP 点、AskUserQuestion 用户决策门禁、/ship 审查门禁。这三类门禁代表「用户决策点」或「安全边界」，一旦触发，完成倾向必须让位。

这种「倾向 + 从属」的写法与解析器注入的包裹文本（第二节）形成呼应：overlay 里的每条指令都可以被技能本身的工作流规则覆盖。

二、覆盖层如何被解析与注入（源码机制）

三条规则的生效路径完全由两个源码文件决定：模型族归一化 scripts/models.ts 和 overlay 解析器 scripts/resolvers/model-overlay.ts。

2.1 模型族归一化：o3、o1-pro 都能命中 o-series

scripts/models.ts 中的 resolveModel() 把 CLI 传入的模型名归一化为 overlay 文件名对应的「族名」。规则按优先级：

1. 精确匹配：输入与 ALL_MODEL_NAMES（含 'o-series'，见 scripts/models.ts）完全一致则直接返回；
2. 族启发式：正则 /^o[0-9]+(-|$)/ 把 o3、o4、o4-mini、o1、o1-mini、o1-pro 等一律归到 o-series（scripts/models.ts）；
3. 未知输入：返回 null，由调用方决定报错或回退。

文件头注释还点明了 o-series 的典型宿主场景：「Codex CLI 运行 GPT/o-series 模型」（scripts/models.ts）。也就是说，当 gstack 为 Codex 等宿主生成 SKILL 文档且目标模型是 o 系推理模型时，本文件即被选中。

2.2 解析器：读取、继承、包裹

scripts/resolvers/model-overlay.ts 的 readOverlay() 实现了三级优先级：

1. 精确匹配：ctx.model === 'o-series' → 读取 model-overlays/o-series.md；
2. {{INHERIT:...}} 指令：若文件首个非空白行是 {{INHERIT:claude}} 之类的继承声明，解析器先读基类文件并拼接在前，实现「子类 overlay 在父类之上叠加」（scripts/resolvers/model-overlay.ts）。注意 o-series.md 没有继承声明，它是独立的基础 overlay，不依赖其他文件；
3. 文件缺失或 ctx.model 未设置：返回空字符串，优雅降级，不报错。

generateModelOverlay() 随后把内容包裹成统一的注入段（scripts/resolvers/model-overlay.ts）：

## Model-Specific Behavioral Patch (o-series)

The following nudges are tuned for the o-series model family. They are
**subordinate** to skill workflow, STOP points, AskUserQuestion gates,
plan-mode safety, and /ship review gates. If a nudge below conflicts with
skill instructions, the skill wins. Treat these as preferences, not rules.

<o-series.md 的三条规则正文>

这段包裹文本是理解 o-series.md 第 1.3 条「subordinate to safety gates」写法的来源：从属声明是解析器强制注入的，与文件内容无关，无论 overlay 写了什么都会出现在每份生成文档中。仓库根目录已生成的 SKILL.md 展示了这一段的真实形态（当前默认生成的是 claude 族）。

2.3 注入位置：在 AskUserQuestion 格式之后

在 scripts/resolvers/preamble.ts 的前言段数组中，generateModelOverlay(ctx) 排在 generateAskUserFormat(ctx) 之后。源码注释解释了顺序的缘由：

AskUserQuestion Format renders BEFORE the model overlay so the pacing rule is the ambient default... reversing this order regresses plan-review cadence (v1.6.4.0 bug).

即节奏规则（pacing rule）必须作为环境默认先被模型读到，overlay 的行为倾向只能作为从属补丁落在后面；顺序颠倒曾导致 plan-review 节奏回归（v1.6.4.0 缺陷）。这从工程侧印证了 o-series.md 第 1.3 条「门禁优先于完成倾向」不是文档修辞，而是整个 preamble 装配顺序所保障的不变量。

三、实操：生成带 o-series 补丁的技能文档

仓库提供的生成入口在 package.json：

# 为 o 系推理模型重新生成全部技能文档
bun run gen:skill-docs --model o-series

# 变体名同样可用，resolveModel 会归一化到同一 overlay
bun run gen:skill-docs --model o3
bun run gen:skill-docs --model o1-pro

运行后，每个技能的 SKILL.md 中都会出现 ## Model-Specific Behavioral Patch (o-series) 段，前言行 MODEL_OVERLAY: {model} 会标明当前激活的 overlay（该机制由 CHANGELOG 记录的 v1.3 特性面引入）。overlay 文件是纯 Markdown，直接在 model-overlays/ 下原地编辑即可，无需改任何代码——这是仓库对 overlay 的维护约定。

生成时的行为矩阵：

输入场景	解析结果	生成文档中的效果
--model o-series	精确匹配	注入 o-series.md 三条规则
--model o3 / o1-pro 等	族启发式归一化	同上
--model gpt-5.4-mini	归一化到 gpt-5.4	走 model-overlays/gpt-5.4.md
未设置 model / 文件缺失	返回空字符串	不生成 Patch 段，技能照常生成
gpt-5.6-sol（特例）	精确匹配	使用专门的「作用域消歧」前言替代通用从属声明（scripts/resolvers/model-overlay.ts）

需要说明的适用前提：overlay 选择的是模型轴，与宿主（Claude Code、Codex CLI、Cursor 等）是正交的——scripts/models.ts 明确「host ≠ model」，生成器不会从宿主反推模型，除非显式传 --model 或 setup 流程探测（如从 ~/.codex/config.toml 探测 Codex 模型）。

四、横向对照：o-series 在 overlay 家族中的定位

当前 model-overlays/ 目录含 10 个 overlay 文件。CHANGELOG 在 v1.3 特性面中列出了首批五个的定位：claude（todo-list 纪律）、gpt（反提前终止 + 完整性）、gpt-5.4（反啰嗦，继承 gpt）、gemini（简洁性）、o-series（结构化输出）。三者对照可以看出 gstack 针对各模型族的「短板补强」思路：

overlay	核心补强点	与 o-series 的差异
model-overlays/gpt.md	完成倾向、先做后列、无客套开场	gpt 的 completion bias 是「无条件做到底」；o-series 的 completion bias 显式从属于安全门禁
model-overlays/gemini.md	简洁约束（常规回答 < 3 行）	同样要求结构化输出，但强调压缩而非结构化组织
model-overlays/claude.md	Todo 逐条销项、重操作前说明思路、专用工具优于 Bash	完全不涉及推理链与输出结构

o-series 的独特之处是把「推理模型」这一模型类别本身作为调校对象：其他 overlay 针对的是某家的行为偏差，o-series 针对的是「内部推理很强、但需要管理其输出形态（隐藏 CoT、结构化呈现）」这一类别特性。

五、验证与回归保障

围绕 overlay 机制，仓库提供了可查证的证据链：

• 归一化行为：test/model-overlay-gpt-5.6-sol.test.ts 直接对 resolveModel() 断言（如 gpt-5.6-sol 精确命中、gpt-5.6-terra 落入 gpt 族），同一套归一化路径覆盖 o 系变体；
• preamble 装配顺序：scripts/resolvers/preamble.ts 的注释把 overlay 必须晚于 AskUserQuestion 格式段的原因锚定到具体版本缺陷，属于「顺序即正确性」的强约束；
• CHANGELOG 追溯：CHANGELOG.md 记录了 o-series overlay 的引入（「o-series (structured output)」）、resolveModel() 的族启发式设计（o3 → o-series），以及 overlay 排序回归的修复过程；
• 生成产物：任意已生成的技能文档（如根目录 SKILL.md）尾部都带有 Model-Specific Behavioral Patch 段，可直接查看当前生效的 overlay 内容，验证注入是否符合预期。

小结

model-overlays/o-series.md 只有三条规则，但它示范了 gstack overlay 机制的完整闭环：纯 Markdown 的行为指令 → resolveModel() 模型名归一化 → readOverlay() 读取并（可选）继承拼接 → 解析器强制包裹从属声明 → 在 preamble 中按既定顺序注入。理解这一链路后，你可以直接阅读 scripts/models.ts 与 scripts/resolvers/model-overlay.ts 为新的模型族追加 overlay，或调整 o 系列三条规则中任何一条的措辞，而无需触碰任何 TypeScript 代码。