get-shit-done v1.41.0 技术解读：按阶段类型选模型、失败升级动态路由与 25+ 项正确性修复

get-shit-done（GSD）v1.41.0 是其发布到 npm latest 标签的稳定版本，核心定位是一个以 Claude Code 为主要运行环境、强调上下文工程与规范驱动开发的轻量级元提示系统。本版本在质量与基础设施层面集中发力：两条新增配置块（按阶段类型的模型选择 models、按失败档位升级的动态路由 dynamic_routing）让你无需学习任何 agent 分类学就能获得细粒度成本控制；同时交付了 MVP 模式的 SDK 解析层（三个标准化查询谓词）、面向非 statusline 用户的可选更新横幅，以及一份基于 Issue 驱动的编排指南。正文将以该版本官方发布说明为主干，结合仓库内的配置文档、模型目录与测试用例逐一展开。

---

1. 版本定位与安装方式

v1.41.0 属于稳定版（Stable release），发布于 npm latest 标签。可以从发布说明 docs/RELEASE-v1.41.0.md 看到它的三种标准安装路径：

# npm（全局安装）
npm install -g get-shit-done-cc@latest

# npx（一次性执行）
npx get-shit-done-cc@latest

# 锁定精确版本
npm install -g get-shit-done-cc@1.41.0

安装器是幂等的——对已存在的安装重复执行会在原位更新，同时保留你的 .planning/ 目录与本地补丁（gsd-local-patches/）。这对持续升级工作流很重要：升级不会触碰项目级规划状态。

从内容构成看，该版本是典型的“质量 + 基础设施”发布，主线如下：

• 按阶段类型选择模型（models 块）：两行配置表达“规划用 Opus、其余用 Sonnet”，完全向后兼容；
• 失败档位升级的动态路由（dynamic_routing 块）：先走廉价档位，仅在编排器检测到软失败时升级；
• MVP 模式 SDK 解析层：三个规范化查询动词，替代各工作流中重复的 bash 判断；
• 可选更新横幅：为非 GSD statusline 用户提供 SessionStart 级更新提醒；
• Issue 驱动编排指南：把 GitHub/Linear/Jira 的 tracker issue 映射到 GSD 既有原语。

---

2. 按阶段类型选择模型（models 块）

2.1 解决什么问题

GSD 内置了 33+ 个具名 agent（gsd-planner、gsd-executor、gsd-codebase-mapper……），每个 agent 在不同的 model_profile（quality/balanced/budget/adaptive/inherit）下有独立的 tier 指派。此前要做精细化成本控制，你必须记住 agent 分类（比如“gsd-codebase-mapper 属于 research 型 agent”），再逐个写 model_overrides。

models 块把配置粒度提升到**阶段类型（phase type）**这一层。你不再需要认识任何 agent 名字，只需要关心六个语义槽位。

2.2 六个槽位与取值

仓库内配置文档 docs/CONFIGURATION.md 对 models.<phase_type> 的定义是：取值只能是 tier 别名之一——opus / sonnet / haiku / inherit。六个合法槽位为：

槽位	说明
planning	规划类 agent（gsd-planner、gsd-roadmapper、gsd-pattern-mapper 等）
discuss	讨论槽位（保留位，当前无对应子 agent）
research	调研类 agent（phase/project/domain-researcher、codebase-mapper 等）
execution	执行类 agent（executor、debugger、doc-writer、code-fixer 等）
verification	验证类 agent（verifier、plan/integration-checker、各类 auditor、doc-verifier 等）
completion	完成槽位（保留位，当前无对应子 agent）

这条约束在测试里被锁死：特性测试 tests/feat-3023-model-phase-types.test.cjs 断言 VALID_PHASE_TYPES 恰好等于上述六个槽位，并断言 MODEL_PROFILES 中每个 agent 都有 phase-type 指派，且指派值必须落在六个合法槽位内。该目录文件的真实来源是 sdk/shared/model-catalog.json——sdk/src 之下与 get-shit-done/bin/lib/model-catalog.cjs 分别加载同一份目录数据，其中每条 agent 记录都带有 phaseType 与 routingTier 字段。

2.3 配置示例与解析优先级

示例（沿用官方发布说明中“规划用 Opus、其余用 Sonnet”的口吻）：

{
  "model_profile": "balanced",
  "models": {
    "planning": "opus",
    "discuss": "opus",
    "research": "sonnet",
    "execution": "opus",
    "verification": "sonnet",
    "completion": "sonnet"
  },
  "model_overrides": {
    "gsd-codebase-mapper": "haiku"
  }
}

模型解析的**优先级链（最高 → 最低）**为：

1. model_overrides[<agent>]：按 agent 定向例外，接受完整模型 ID；
2. models[<phase_type>]：按阶段类型的粗粒度 tier（本版本新增层）；
3. model_profile 各 agent 列（全局 tier 策略）；
4. 运行时默认值（兜底）。

2.4 解析实现的源码佐证

解析逻辑核心位于 get-shit-done/bin/lib/core.cjs 中的 resolveModelInternal(cwd, agentType)；而 AGENT_TO_PHASE_TYPE 与 VALID_PHASE_TYPES 等常量定义于 get-shit-done/bin/lib/model-catalog.cjs，由 get-shit-done/bin/lib/model-profiles.cjs 再导出供 core.cjs 与测试共用。它从 sdk/shared/model-catalog.json 的 agent 元数据中构造出“agent → phaseType”与“agent → routingTier”两张映射表。

从 tests/feat-3023-model-phase-types.test.cjs 可验证几个关键行为：

• 阶段类型高于 profile：model_profile: 'quality' 下 research agent 本应拿到 opus，但 models.research: 'haiku' 会把 gsd-phase-researcher、gsd-codebase-mapper 都压到 haiku；
• 按 agent 的 override 高于阶段类型：model_overrides['gsd-phase-researcher'] = 'opus' 只对该 agent 生效，同属 research 的 gsd-codebase-mapper 仍随 models.research；
• inherit 语义保留：models.research: 'inherit' 仍返回 inherit；
• 空 models 块或完全没有 models 块都是 no-op，保证向后兼容；
• 拼写容错：models.research: 'haiku3' 这类非法 tier 会落入 profile tier 而非污染运行时解析链；完整模型 ID（如 "openai/gpt-5"）不允许出现在 models.* 中——完整 ID 只属于 model_overrides；
• 与 profile=inherit 的组合：model_profile: 'inherit' + models.execution: 'opus' 时，执行类 agent 必须拿到 opus 而非 inherit（修复了 profile 短路优先导致的 CR Major bug）。

schema 侧，get-shit-done/bin/lib/config-schema.cjs 的 isValidConfigKey 会接受 models.planning 等六个槽位，拒绝 models.deployment 这种未知槽位、拒绝 models.gsd-planner 这种把 agent 名塞进 models.* 的写法，同时拒绝裸的 models（不通过 gsd-tools config-set 设置整个块）。

2.5 reasoning_effort 与 model 同源（Codex）

对支持 reasoning_effort 的运行时（Codex），core.cjs 里 resolveReasoningEffortInternal 会跟随同一 tier 源。测试锁定了这段关系：models.execution: 'opus' 必须同时让 model 变成 opus-tier、让 reasoning_effort 变成 opus 行对应的 effort 值，避免出现“model 已是 opus、effort 仍是 sonnet/medium”的错配；而 model_overrides 写入完整 ID 时会短路 effort 解析（返回 null，由调用方按 agent 设置）。

---

3. 动态路由：失败档位升级（dynamic_routing 块）

3.1 设计意图

dynamic_routing 是一个结构性成本杠杆：默认只付廉价档的钱，只有编排器检测到软失败（soft failure）——如验证无结论（verification inconclusive）、plan-check 返回 FLAG——时才升级到更贵档位。发布说明强调它默认关闭，并与 model_overrides、models.<phase_type> 走同一条优先级链。

3.2 配置结构与示例

{
  "dynamic_routing": {
    "enabled": true,
    "tier_models": {
      "light":    "haiku",
      "standard": "sonnet",
      "heavy":    "opus"
    },
    "escalate_on_failure": true,
    "max_escalations": 1
  }
}

字段语义（docs/CONFIGURATION.md 参数表）：

字段	类型	默认值	说明
dynamic_routing.enabled	boolean	false	总开关。true 时 resolver 才走 tier 映射与升级逻辑
dynamic_routing.tier_models.light/standard/heavy	enum	—	三个档位各自映射到的 tier 别名（典型为 haiku/sonnet/opus）
dynamic_routing.escalate_on_failure	boolean	true	为 false 时即使 enabled: true 也不升级，每次重试都用默认档位（kill-switch）
dynamic_routing.max_escalations	integer	1	单次 agent 调用的升级硬上限，防止失控循环

3.3 Agent 默认档位

每个 agent 在模型目录中声明一个默认档位（routingTier）。按 docs/CONFIGURATION.md 划分：

档位	代表 agent	用途
light	gsd-codebase-mapper、gsd-pattern-mapper、gsd-plan-checker、gsd-integration-checker、gsd-nyquist-auditor、gsd-doc-classifier、gsd-intel-updater、gsd-ui-checker/auditor 等	纯 mapper、扫描器、低风险审计——便宜且快
standard	gsd-executor、gsd-phase/project-researcher、gsd-verifier、gsd-code-fixer、gsd-doc-writer、gsd-domain-researcher、gsd-eval-auditor 等	默认主力——调研、写作、主验证
heavy	gsd-planner、gsd-roadmapper、gsd-debugger、gsd-framework-selector、gsd-eval-planner、gsd-security-auditor、gsd-user-profiler 等	深度推理——已在顶档，无法再升级

3.4 升级流程

1. 编排器以 attempt: 0 拉起 agent → resolver 返回 tier_models[默认档位]
2. 软失败？
   ├─ 否 → 完成（走廉价路径）
   └─ 是 → 编排器以 attempt+1 重拉
            → resolver 返回 tier_models[更高一档]
            → 封顶于 max_escalations
3. 硬失败（异常）不进入升级链，直接上抛

其中“升一档”的动作在 get-shit-done/bin/lib/model-catalog.cjs 中由 nextTier(currentTier) 实现：档位顺序 light → standard → heavy，heavy 再往上仍停留 heavy；传入非法值返回 null。resolver 入口是 get-shit-done/bin/lib/core.cjs 的 resolveModelForTier(cwd, agentType, attempt)——它先检查 per-agent override（永远优先），再依据 enabled 与 escalate_on_failure 决定走 tier 映射还是回落 resolveModelInternal。

3.5 与其它 tier 源的优先级（最高 → 最低）

1. model_overrides[<agent>]（完整 ID 恒胜出）；
2. dynamic_routing.tier_models[<升级后档位>]（enabled: true 时）；
3. models[<phase_type>]（#3023 粗粒度阶段级）；
4. model_profile（全局 tier 策略）；
5. 运行时默认。

行为均由特性测试 tests/feat-3024-dynamic-routing.test.cjs 锁定：

• 关闭模式是 no-op：无 dynamic_routing 块或 enabled: false 时，attempt 参数被忽略，返回结果与 resolveModelInternal 完全一致；
• 启用模式：attempt: 0 返回 tier_models[默认档位]；attempt: 1 升一档（light→sonnet、standard→opus）；
• 超过上限封顶：max_escalations: 1 时 attempt: 2 与 attempt: 5 都只给到 attempt=1 的档位模型；
• 省略 max_escalations 默认取 1；
• heavy 档 agent 无论 attempt 多高都停在 opus（没有更高档）；
• escalate_on_failure: false 是真正的总闸（CR Major）：即使编排器持续传入 attempt+1，每次重试也必须回落默认档位，不得悄悄升级；
• override 恒胜：model_overrides 在 attempt=0/1 下均返回完整 ID；dynamic_routing 也高于 models[phase_type]；
• schema 侧只接受 light/standard/heavy 三个档位键，拒绝 jumbo、medium 等未知 tier，拒绝裸 dynamic_routing 与未知子键。

---

4. MVP 模式 SDK 解析层：三个规范化查询动词

v1.41.0 把 MVP 模式此前散落各工作流的谓词逻辑收敛为 SDK 层的三个规范动词（由 gsd-sdk query 子命令暴露），消费方工作流统一调用动词，不再各自内联 4–8 行 bash：

动词	职责
gsd-sdk query phase.mvp-mode <N>	MVP 模式优先级解析器：--mvp CLI 标志 → ROADMAP.md **Mode:** mvp → workflow.mvp_mode 配置 → false
gsd-sdk query task.is-behavior-adding	Behavior-Adding Task 判定：三个检查（tdd=true 的 frontmatter + <behavior> 块 + <files> 中存在非测试源文件）
gsd-sdk query user-story.validate	User Story 正则校验：/^As a .+, I want to .+, so that .+\.$/

三者实现位于 sdk/src/query/mvp.ts。头文件注释明确点名了它替代的三处架构性重复：plan-phase.md、execute-phase.md、verify-work.md、progress.md 中近乎相同的 bash 块；此前仅以散文形式存在于 get-shit-done/references/execute-mvp-tdd.md 的 TDD 三检查；以及此前硬编码在 verify-work.md 散文里的 User Story 正则。消费方包括 gsd-executor agent（判定是否为 Behavior-Adding Task）与 verifier / /gsd-mvp-phase（做 phase-goal 守卫与交互式 prompt 校验）。

该版本还顺带修复了一个静默 SDK bug：此前 roadmap.get-phase --pick mode 对设置了 **Mode:** mvp 的阶段返回 null。MVP 模式的优先级链与 User Story 定义同时收录在 CONTEXT.md 的 MVP Mode / User Story 词条中；六个 MVP 参考文件的概念索引则落在新增的 get-shit-done/references/mvp-concepts.md。

---

5. 可选更新横幅与 graphify 新鲜度

5.1 非 statusline 用户的更新横幅

GSD 的 statusline 本身就带更新提示；但当安装器检测到没有 GSD statusline 时，v1.41.0 会提供一个可选加入的 SessionStart hook，通过既有缓存文件 ~/.cache/gsd/gsd-update-check.json 展示更新可用性：

• 最新版本时静默（不打扰每次会话）；
• 由 --uninstall 干净移除。

实现位于 hooks/gsd-update-banner.js，头注释点明关键设计：SessionStart 条目的存在本身就是 opt-in——没有额外的运行时开关；缓存由 hooks/gsd-check-update-worker.js 写入；当缓存缺失/损坏时按静默处理，避免每次会话骚扰。该横幅只负责“告知”，更新动作仍通过 /gsd-update 或 CLI 完成。

5.2 /gsd-graphify status 提交级陈旧度

/gsd-graphify status 现在会读取 graphify v0.7+ 图谱中的 built_at_commit，与 git HEAD 比较，并新增四个字段：

字段	含义
built_at_commit	图谱构建时记录的 commit（取前 7 位，无则 null）
current_commit	当前 git HEAD（前 7 位）
commits_behind	图谱落后当前 HEAD 的提交数
commit_stale	是否陈旧（tri-state：false= 新鲜；true= 落后；null= 不知道）

pre-v0.7 图谱没有 built_at_commit，此时 commit_stale 返回 null，回退到既有的 mtime 信号。实现位于 get-shit-done/bin/lib/graphify.cjs：对 built_at_commit 采用严格的 4–40 位十六进制护栏（超过即视为格式非法），随后与 HEAD 计算 commits_behind 并输出四个字段。

---

6. Issue 驱动编排指南（文档层新增）

v1.41.0 新增 docs/issue-driven-orchestration.md，把 tracker issue（GitHub / Linear / Jira）映射到 GSD 既有原语上：workspace → discuss → plan → execute → verify → review → ship。

核心概念映射（Symphony 风格编排概念 → GSD 原语）：

概念	GSD 原语
顶层意图工作流	ROADMAP.md（项目意图）、STATE.md（实时状态）、阶段 CONTEXT.md（阶段范围）、阶段 PLAN.md（可执行步骤）
每任务独立 agent 工作区	/gsd-workspace --new --strategy worktree
agent 分发与并发	/gsd-manager（交互仪表盘）、/gsd-autonomous（无人值守）
每阶段 plan/discuss	/gsd-discuss-phase → /gsd-plan-phase → /gsd-execute-phase
工作量证明/测试证据	/gsd-verify-work（UAT.md 跨 /clear 持久化）
对抗式评审	/gsd-review（跨 AI peer review 计划）
人类合并闸门	/gsd-ship（创建 PR、可选 code review、准备 merge）
后续项捕获	/gsd-capture、/gsd-capture --seed、/gsd-new-milestone 或手动开 tracker issue

该指南是纯文档：不新增命令、无 daemon、无 tracker 集成。四条安全不变式保证了闭环安全性：隔离 worktree（不碰 main）、显式人工评审（无自动 merge/自动 PR）、无自动公开发布（GSD 绝不未经显式命令去开/回/关 tracker issue）、验证先于 ship（verification_failed 应被视为 blocker）。指南亦明确列出非目标：不 vendor Symphony 代码、不引入长驻轮询 daemon、不强制 tracker 依赖、不绕过验证/评审/人工闸门、不扩张默认 skill/命令面。

---

7. 25+ 项正确性修复解析

发布说明中“Fixed”部分覆盖跨运行时与内部状态的正确性修复，按主题整理如下。

7.1 运行时与安装正确性

• Homebrew 下 Node 路径稳定：resolveNodeRunner() 现在把带版本的 Cellar 路径映射到稳定的 Homebrew 符号链接，防止 brew upgrade node 后出现 dyld: Library not loaded 错误（#3181）。
• 全局 skill 解析改用正确的运行时 home：buildAgentSkillsBlock() 此前对所有运行时硬编码 ~/.claude/skills；新模块 get-shit-done/bin/lib/runtime-homes.cjs 把全部 15 个受支持运行时映射到各自规范的 skills 目录（#3126）。
• --sdk 标志真正接线到 SDK 部署：hasSdk 此前被解析但从未传给 installSdkIfNeeded，导致 --sdk 静默跳过部署（#3033）。
• SDK shim 安装器 shell 路径探测：不再在用户交互 shell 无法触达 shim 时打印 “✓ GSD SDK ready”；改为探测 $SHELL -lc 'printf %s "$PATH"' 而非安装器子进程的 PATH（#3020）。
• Windows 更新检查不再静默失败：Windows 上补传 shell: true，让 npm.cmd 能经 PATHEXT 解析；否则 statusline 的 “⬆ /gsd-update” 指示器在 Windows 上永不渲染（#3103）。
• 社区 .sh hooks 改用 #!/usr/bin/env bash：原 #!/bin/bash shebang 在 NixOS、最小化 Alpine 镜像与部分容器运行时上会失败（#3194）。
• Codex SessionStart hook 使用绝对 Node 路径：config.toml 中裸 node 在 GUI / 最小 PATH 运行时下会以 exit 127 失败（#3017）。
• Gemini 本地安装不再重复 /gsd:* 命令：当 GSD 已按用户作用域安装、后续再执行 --gemini --local 时会跳过工作区作用域，避免 65 个命令文件双写后被 Gemini 冲突检测器全部改名（#3037）。
• /gsd-plan-phase 不再在 OpenCode 上自动派生子 agent：删除 agent: gsd-planner frontmatter 指令——它会让 OpenCode 在无 Agent 工具的上下文里运行编排器（#3156）。

7.2 状态与校验引擎

• state.begin-phase 幂等化：wave-resume 调用不再用上次 plan-phase 的过期值覆盖 Current Plan、stopped_at、Last Activity Description（#3127）。
• gsd-validate-commit.sh hook 捕获全部 git commit 形式：原 bash 正则漏掉 git -C /path commit、GIT_AUTHOR_NAME=x git commit、/usr/bin/git commit 等形式；新分类器 hooks/lib/git-cmd.js 用 token 遍历正确处理所有形式（#3129）。
• Milestone 归档布局支持：validate consistency、validate health、find-phase 除扁平 .planning/phases/ 布局外，也扫描 .planning/milestones/v*-phases/，消除假阳性 W006 告警（#3164）。
• gsd-health 不再对 RETROSPECTIVE.md 报 W019：RETROSPECTIVE.md 已注册进 artifact 表的 CANONICAL_EXACT，匹配其里程碑完成产物的既有地位（#3198）。
• secure-phase 对遗留阶段启用追溯 STRIDE 模式：无 <threat_model> 块的阶段不再橡皮图章式地通过 SECURITY.md；auditor 先依据实现文件构建 register，再核验缓解项（#3120）。
• Planner 指令语言恢复：v1.38.4 曾静默删除 gsd-planner.md 中 10 个 CRITICAL/MANDATORY/MUST 强调标记，削弱了 planner 对用户决策与需求覆盖的遵循，本版全部恢复（#3087）。
• /gsd-quick worktree 合并复活守卫：被反转的 PRE_MERGE_FILES grep 会误删新创建文件（含 SUMMARY.md）；改用 execute-phase.md 使用的 git 历史检查（#3195）。
• 状态栏渲染类型健壮且兼容 YAML 列表：milestone 完成度对数值型与字符串型 percent 都正常渲染；next_phases 同时解析 flow-array 与 block-list 两种 YAML（#3153）。

7.3 配置键与 workstream 解析

• config-set workflow._auto_chain_active 不再被拒：该键已加进 SDK schema 但未镜像到 get-shit-done/bin/lib/config-schema.cjs，经 gsd-tools 走查的用户会看到 “Unknown config key”（#3197）。
• config-set resolve_model_ids 与 workflow._auto_chain_active 放行：两者此前已被文档或内部工作流写入，但缺少在 allowlist 中（#3162）。
• workstream 解析纳入 init.milestone-op 与 roadmap.analyze：两个 handler 现在都尊重 --ws、GSD_WORKSTREAM 与 .planning/active-workstream，避免 workstream 作用域仓库因读取根 .planning/ 而误报 “Nothing left to do”（#3196、#3207）。

---

8. 变更小结与升级建议

Added（新增）：

• models 块（per-phase-type 模型选择，六个槽位，完全向后兼容）；
• dynamic_routing 块（默认关闭，软失败档位升级，max_escalations 默认 1）；
• 非 statusline 用户的 SessionStart 更新横幅；
• docs/issue-driven-orchestration.md 编排指南。

Changed（变更）：

• MVP 模式收敛到三个 SDK 查询动词 + 修复 roadmap.get-phase --pick mode 的静默 null bug；
• /gsd-graphify status 增加提交级陈旧度四字段；
• MVP 概念索引：CONTEXT.md 新增七个术语，新增 get-shit-done/references/mvp-concepts.md 索引六个 MVP 参考文件。

Fixed（修复）：25+ 项，覆盖 Homebrew Node 路径稳定性、planner 指令保真度、secure-phase 追溯审计、跨运行时安装、statusline 解析等（详见上一节）。

升级建议方面：由于安装器幂等且保留 .planning/，已在使用 v1.40 及以下版本的用户可直接执行 npm install -g get-shit-done-cc@latest 升级；希望评估两条新配置块但担心行为变化的用户，可以先把配置写好并保持 dynamic_routing.enabled: false（默认值），确认稳定后再打开开关。若想深入把玩这两个配置块，可对照 docs/CONFIGURATION.md 的「Per-Phase-Type Models」与「Dynamic Routing with Failure-Tier Escalation」两节，再结合 tests/feat-3023-model-phase-types.test.cjs 与 tests/feat-3024-dynamic-routing.test.cjs 理解每种配置组合的预期行为。