gstack 中 Gemini 模型的行为覆盖层：model-overlays 机制与 Gemini 专属行为补丁解析
gstack 中 Gemini 模型的行为覆盖层model-overlays 机制与 Gemini 专属行为补丁解析【免费下载链接】gstackUse Garry Tans exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstackgstack 通过model-overlays/目录为不同模型家族注入专属行为补丁Behavioral Patch本文以 model-overlays/gemini.md 这一 Gemini 专属覆盖层为主体完整解读其中三条行为约束的设计意图并结合 scripts/resolvers/model-overlay.ts 与 scripts/models.ts 的源码讲清覆盖层的解析、注入与降级机制以及 gstack 如何用 A/B 试验框架量化验证每条 nudge 是否真正生效。读完本文你能掌握 gstack 模型轴model axis与宿主轴host axis分离的设计并知道如何为任意模型定制行为覆盖层。一、Gemini 覆盖层全文三条行为约束model-overlays/gemini.md 是 gstack 为 Gemini 模型家族准备的独立覆盖层全文只有三条精炼的行为指令。以下完整保留原文内容这也是该文件注入到会话系统提示词中的全部实质内容Conciseness constraint.Keep non-code text output short. Aim for under 3 lines for routine responses unless the user explicitly asks for detail. Code blocks and command output do not count toward the limit.Bias toward action.Run commands and show results rather than explaining what commands you would run. The user sees the command and the output — they dont need narration.Structured output when useful.Tables, bullet points, and code blocks beat prose for lists of things. Prose is for explaining; structure is for presenting.三条约束分别针对 Gemini 在实际使用中常见的三类表现偏差简洁性约束Conciseness constraint限定常规响应的非代码文本在 3 行以内除非用户明确要求细节代码块与命令输出不计入篇幅限制。它的效果是让 Gemini 在 gstack 技能会话中少说废话、直击结果同时不误伤代码类产出。行动优先Bias toward action要求直接执行命令并展示真实输出而不是解释我会执行什么命令。gstack 的 23 个技能CEO、设计、工程评审、QA 等都以给出可验证的结果为工作范式这条 nudge 让 Gemini 与该范式对齐——用户看到命令和输出不需要旁白。结构化输出优先Structured output when useful列表、对照、枚举类信息优先用表格、项目符号和代码块呈现散文只用于解释。这条约束提升的是输出的可扫描性方便人类和下游 Agent 快速解析。从文件结构看gemini.md 与同目录下 model-overlays/sonnet-5.md 形成对照后者首行带有{{INHERIT:claude}}指令、继承 model-overlays/claude.md 基座再叠加自己的条款而 gemini.md 没有任何 INHERIT 指令是一个完全独立的覆盖层——因为它面向非 Claude 家族模型不适合继承 Claude 基座的行为条款。二、覆盖层如何被解析与注入model-overlay 求解器覆盖层的实际生效由 scripts/resolvers/model-overlay.ts 完成。核心入口是generateModelOverlay(ctx)其解析优先级在源码头部注释中有明确定义精确匹配ctx.model gemini时读取model-overlays/gemini.mdINHERIT 指令若文件首个非空行是{{INHERIT:claude}}正则INHERIT_RE见 model-overlay.ts#L25先读取基座文件并拼接在本文件内容之前支持递归继承并带环检测守卫seen: Setstring防循环见 readOverlay文件缺失返回空字符串优雅降级不报错未设置模型ctx.model为空时直接返回空。注入时generateModelOverlay 会给覆盖层内容包上一层固定的从属声明subordination wrapper## Model-Specific Behavioral Patch (gemini) The following nudges are tuned for the gemini 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. gemini.md 的全文内容这层 wrapper 是 gstack 模型轴设计的关键覆盖层永远是偏好preferences不是规则rules。无论 gemini.md 里写什么它都从属于技能工作流、STOP 检查点、AskUserQuestion 门控、plan 模式安全与 /ship 评审门。换言之gemini.md 那三条行为约束可以调节表达风格但绝不能让模型跳过 gstack 技能里强制的安全或流程步骤——skill wins是硬性的优先级裁决。三、模型识别从 CLI 参数到 gemini 覆盖层覆盖层文件名为模型家族名那么 CLI 传入的具体模型 ID如gemini-2.5-pro、gemini-flash如何映射到gemini.md答案在 scripts/models.ts 的resolveModel()中models.ts#L51-L76其规则按优先级为精确匹配ALL_MODEL_NAMES白名单包含claude、opus-4-7、fable-5、opus-4-8、sonnet-5、gpt、gpt-5.4、gpt-5.6-sol、gemini、o-series共 10 个家族见 models.ts#L18-L29直接返回家族启发式/^gemini(-|$)/匹配gemini-*2.5-pro、flash 等任意变体归一为gemini家族models.ts#L73同类的还有gpt-5.4-*→gpt-5.4、o3/o1-mini等 →o-series、claude-sonnet-5→sonnet-5等未知输入返回null由调用方决定报错还是回退。模型轴与宿主轴在此模块中刻意解耦Claude Code 可以跑任何 Claude 模型Codex CLI 跑 GPT/o 系列Cursor/OpenCode 可以前置多供应商生成器不会从宿主自动推断模型用户可用--model显式指定否则由各宿主提供自己的默认值。validateModel()models.ts#L83-L86则供宿主配置校验defaultModel字段。四、覆盖层有效性不是口头承诺A/B 试验框架gstack 没有把覆盖层当成写了就算数的提示词装饰。test/fixtures/overlay-nudges.ts 定义了一个覆盖层功效夹具注册表overlay-efficacy fixture registry每条行为 nudge 对应一个可复现的 A/B 试验由 test/skill-e2e-overlay-harness.test.ts 中的 harness 遍历执行每个夹具跑trials轮校验规则要求不少于 3 轮见 validateFixtures并断言fixture.pass(arms)。该框架的判定谓词直接量化了行为差异overlay-nudges.ts#L128-L155fanoutPassoverlay 组首轮并行工具调用均值比基线高 0.5 以上且至少 3 轮出现 ≥2 个并行调用——同时抓住每轮都有轻微提升和偶尔触发真正的并行扇出两种情况lowerIsBetter20Pct/higherIsBetter20Pct均值需相对基线变化至少 20%避免把随机波动当成功效。现有的夹具覆盖了专用工具优于 Bash以bashToolCallCount为指标、effort-match以turnsToCompletion为指标、字面解读以uniqueFilesEdited为指标等 nudge并且为 Sonnet 复跑了 Opus 的整套试验以验证同一组 nudge 在不同强度模型上的差异。gemini.md 的三条约束目前尚无对应的 A/B 夹具条目——从源码结构看新增一条 Gemini 覆盖层试验只需在OVERLAY_FIXTURES中追加一个overlayPath: model-overlays/gemini.md、model: gemini-...的条目即可复用整套 harness臂接线、并发、产物存储、限流重试均由 harness 处理。在 Gemini 端到端一侧仓库另有 test/gemini-e2e.test.ts 与 test/helpers/gemini-session-runner.ts会话运行器、test/helpers/providers/gemini.ts供应商适配构成的验证链路以及 test/helpers/hermetic-env.ts 提供的密封测试环境保证 Gemini 路径下的技能会话可以在可控环境中被反复验证。五、实战要点如何应用 gemini 覆盖层启用方式以gemini家族模型运行 gstack 技能会话时模板解析阶段会自动调用generateModelOverlay将 gemini.md 内容连同从属声明注入提示词用户可用--model显式指定模型归一化走resolveModel未指定时回退宿主默认模型。适用前提与限制gemini.md 是家族级覆盖层gemini-2.5-pro、gemini-flash等变体共用同一套约束它只调整表达与行动风格不能覆盖技能流程——这是 wrapper 中skill wins条款的硬性边界。定制参考若要为某个模型新增覆盖层参照 model-overlays/ 目录下既有文件共 10 个家族的写法即可——独立条款直接书写需要叠加 Claude 基座时首行加{{INHERIT:claude}}如 model-overlays/sonnet-5.md行为变更的回归断言可参照 test/model-overlay-sonnet-5.test.ts 等既有测试对原始文件内容与解析后输出做双重断言例如验证某指令存在、旧指令已移除、INHERIT 基座条款被正确带入。六、小结model-overlays/gemini.md 用不到 10 行文本向 Gemini 传递了 gstack 最看重的三个行为特征常规响应 3 行以内的简洁、直接执行并展示输出的行动优先、以及面向列表信息的结构化输出。其工程价值不在这三条文本本身而在于 gstack 为它搭建的整套机制resolveModel的家族归一、generateModelOverlay的从属包装与 INHERIT 继承链、文件缺失时的优雅降级以及 overlay-nudges A/B 试验框架带来的可量化验证。这套模型轴独立于宿主轴、偏好从属于技能规则的架构是 gstack 能让同一组技能在 Claude、GPT、Gemini 等不同模型上保持行为一致性的基础。【免费下载链接】gstackUse Garry Tans exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考