用 `/gsd:config` 一处配齐全套 GSD 设置：模式路由、高级旋钮、集成与模型档位详解

2026-09-07 18:50:43作者：袁立春Spencer

导读：GSD（get-shit-done）是一个基于 Claude Code 的轻量级 meta-prompting、上下文工程与规范驱动开发系统，工程状态与运行偏好沉淀在项目级 .planning/config.json 中。本文以仓库中的 config.md 命令定义为骨架，串联它所调度的 settings、settings-advanced 与 settings-integrations 三个工作流，讲清楚一条 /gsd:config 命令如何按参数路由到四种配置入口，并深入到 gsd-sdk 的底层写入与校验机制。读完你将能独立完成：常见用例开关的交互式调优、高级旋钮的手动配置、第三方 API Key 与审查 CLI 路由的安全录入，以及一行命令完成模型档位切换。

一、命令全景：一条命令、四种模式、三个入口

/gsd:config 是 GSD 的统一配置入口。它的 frontmatter 明确声明了自己允许使用的工具面（Read、Write、Bash、AskUserQuestion），参数提示为：

[--advanced | --integrations | --profile <name>]

其核心定位是把分散在不同工作流里的配置能力收敛到单一命令上：默认不带参数时回答常见用例问题；--advanced 进入高级调优；--integrations 管理连接类配置；--profile 则是纯命令行、零交互的模型档位切换。命令还声明 requires: [code-review, review, settings]，即依赖 /gsd:code-review、/gsd:review 与 /gsd:settings 等命令族的就绪状态。

模式路由规则如下（对应 config.md 的 <routing> 段落）：

Flag	动作	目标工作流 / 执行方式
（无）	交互式常见用例配置（多问题提问）	settings
`--advanced`	高级旋钮：规划、执行、讨论、跨 AI、Git、运行时	settings-advanced
`--integrations`	API Key（Brave / Firecrawl / Exa）、review CLI 路由、agent skills	settings-integrations
`--profile <name>`	无交互切换模型档位	gsd-sdk `config-set-model-profile`

三个工作流文件以 @ 路径形式出现在 config.md 的 <execution_context> 中——它们在本仓库内对应的实际位置为 get-shit-done/workflows/settings.md、get-shit-done/workflows/settings-advanced.md 与 get-shit-done/workflows/settings-integrations.md（安装后会落到 ~/.claude/get-shit-done/workflows/ 下）。

命令行的解析逻辑（config.md <context> 段落）也很直接：

若第一个 token 是 --advanced：去掉该 flag 后整段执行 settings-advanced 工作流；
若第一个 token 是 --integrations：去掉该 flag 后整段执行 settings-integrations 工作流；
若以 --profile 开头：取出其后的档位名，走 gsd-sdk 内联命令（见第五节）；
其余情况：直接执行 settings 工作流。

一个值得注意的设计是：这些工作流是端到端加载执行的，命令本体不做决策，只是“分诊”到正确的目标工作流，并要求 Preserve all workflow gates from the target workflow（保留目标工作流自身的所有 gate）。

二、配置落盘：`.planning/config.json` 与工作流感知路径

2.1 配置文件的两层定位

三个工作流在 ensure_and_load_config 步骤中以完全相同的方式定位配置文件（issue #2282）：

gsd-sdk query config-ensure-section
if [[ -z "${GSD_CONFIG_PATH:-}" ]]; then
  if [[ -f .planning/active-workstream ]]; then
    WS=$(tr -d '\n\r' < .planning/active-workstream)
    GSD_CONFIG_PATH=".planning/workstreams/${WS}/config.json"
  else
    GSD_CONFIG_PATH=".planning/config.json"
  fi
fi

平面项目（flat）：配置文件固定为 .planning/config.json；
工作流（workstream）项目：当存在 .planning/active-workstream 时，读出的工作流名指向 .planning/workstreams/<slug>/config.json。

这就是为什么工作流反复强调 Never hardcode .planning/config.json——所有读写都必须经由 $GSD_CONFIG_PATH 解析后的路径，否则工作流安装会把配置写错文件。而 gsd-sdk query config-ensure-section 的作用是：若配置文件缺失则按默认值补齐骨架，保证后续读取永不落空。

2.2 写入走“中心 setter”，而非整文件覆盖

两份 settings 工作流都约定了同一个正确性不变量：更新配置时必须保留所有无关键，绝不覆盖兄弟节点。实现方式是把每个键值写入交给中心 setter：

gsd-sdk query config-set <key.path> <value>

config-set 在写入前会经过中心校验器（isValidConfigKey）校验键名合法性，再执行深合并。例如高级模式中的实际调用：

gsd-sdk query config-set workflow.plan_bounce_passes 5
gsd-sdk query config-set workflow.subagent_timeout 900
gsd-sdk query config-set git.base_branch main
gsd-sdk query config-set context_window 1000000

这也意味着只要走命令行，用户永远改不掉配置里未触及的部分——这是两个工作流与 config.md 共同守护的安全边界。

2.3 完整配置骨架

关于配置文件的完整字段与默认值，可直接查阅仓库中的权威参考 docs/CONFIGURATION.md（“Full Schema”一节给出了整份 config.json 骨架）。这里先给出与 /gsd:config 关系最密切的写入形态，即 settings 工作流合并后的概念结构：

{
  "...existing_config": "...",
  "model_profile": "quality",
  "commit_docs": true,
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "auto_advance": false,
    "nyquist_validation": true,
    "pattern_mapper": true,
    "ui_phase": true,
    "ui_safety_gate": true,
    "ai_integration_phase": true,
    "tdd_mode": false,
    "code_review": true,
    "code_review_depth": "standard",
    "ui_review": true,
    "text_mode": false,
    "research_before_questions": false,
    "discuss_mode": "discuss",
    "skip_discuss": false,
    "use_worktrees": true
  },
  "intel": { "enabled": false },
  "graphify": { "enabled": false, "auto_update": false },
  "git": {
    "branching_strategy": "none",
    "quick_branch_template": null,
    "create_tag": true
  },
  "hooks": { "context_warnings": true, "workflow_guard": false }
}

三、默认模式：常见用例的六组交互配置（settings 工作流）

不带 flag 调用 /gsd:config 时进入 settings 工作流。它的目标是对齐最常见的 23 项设置：model profile + 工作流开关 + 功能开关 + Git 分支 + Git tag + 上下文警告，用 AskUserQuestion 分六组逐题询问，且每个问题都会预选当前值。

3.1 六大分组与三处“条件可见性”

交互面板按视觉分组渲染（每组首个问题带 header 字段，AskUserQuestion 会渲染 ≤12 字符的简写分组标签）：

分组	覆盖问题
Planning	Research、Plan Checker、Pattern Mapper、Nyquist、UI Phase、UI Gate、AI Phase
Execution	Verifier、TDD Mode、Code Review、Code Review Depth（条件）、UI Review
Docs & Output	Commit Docs、Skip Discuss、Worktrees
Features	Intel、Graphify、Graph auto-update（条件）
Model & Pipeline	Model Profile、Auto-Advance、Branching
Misc	Context Warnings、Research Qs

需要特别留意的两处条件可见性逻辑：

code_review_depth 仅在 code_review=on 时出现。若用户选择关闭 code review，该问题从 AskUserQuestion 块中移除，同时保留 config 中已有的 workflow.code_review_depth 值（不做覆盖）。实现上先把 Model + Planning + Execution 问到 Code Review 为止，若答案为 on 则同批追加 depth 问题，否则跳过——本质上是对 code_review 答案做一次单分支分叉。
graphify.auto_update 仅在 graphify.enabled=on 时出现。先问 Graphify，只有启用后才追问是否在 main HEAD 前进后自动重建图（issue #3347）。

3.2 关键开关速查

settings 工作流的 <step name="read_current"> 明确列出了它读取并管理的键（缺省时按注释默认值兜底）：

配置键	缺省值	含义
`workflow.research`	`true`	plan-phase 时派发 domain researcher
`workflow.plan_check`	`true`	plan-phase 时派发 plan checker
`workflow.verifier`	`true`	execute-phase 后派发 verifier
`workflow.nyquist_validation`	`true`	plan-phase 中进行验证架构调研（决定测试覆盖策略）
`workflow.pattern_mapper`	`true`	research 与 planning 之间运行 gsd-pattern-mapper
`workflow.ui_phase`	`true`	前端阶段生成 UI-SPEC.md 设计契约
`workflow.ui_safety_gate`	`true`	规划前端阶段前提示先跑 `/gsd:ui-phase`
`workflow.ai_integration_phase`	`true`	AI 阶段执行框架选型 + eval 策略
`workflow.tdd_mode`	`false`	execute-phase 强制 RED/GREEN/REFACTOR 门序列
`workflow.code_review`	`true`	启用 `/gsd:code-review` 与 `--fix` 命令
`workflow.code_review_depth`	`"standard"`	默认审查深度（`quick`/`standard`/`deep`）
`workflow.ui_review`	`true`	自主模式下执行视觉质量审计
`commit_docs`	`true`	`.planning/` 是否纳入 git 版本控制
`intel.enabled`	`false`	启用 `/gsd:map-codebase --query` 可查询索引
`graphify.enabled`	`false`	启用项目知识图谱 `/gsd:graphify`
`graphify.auto_update`	`false`	main HEAD 前进后自动重建图谱
`model_profile`	`balanced`	各 agent 使用的模型档位
`git.branching_strategy`	`"none"`	分支策略
`workflow.use_worktrees`	`true`	并行 executor 是否在独立 worktree 中运行

3.3 有代表性的问题形态

Model Profile 问题是全流程第一个问题，预选当前值，四个选项分别刻画成本哲学：

Quality：除验证外全部使用 Opus（成本最高）；
Balanced（推荐）：规划用 Opus、研究/执行/验证用 Sonnet；
Budget：写作用 Sonnet、研究/验证用 Haiku（成本最低）；
Inherit：所有 agent 跟随当前会话模型（非 Claude 运行时必选）。

其它问题大同小异，均为“是否/选择”二分结构，例如：

Spawn Plan Researcher?（Researches domain before planning）
Spawn Plan Checker?（Verifies plans before execution）
Enable TDD Mode?（Planner 给业务逻辑/API/校验打 type:tdd，executor 强制门序列，阶段末审查合规）
Git branching strategy?（None / Per Phase（gsd/phase-{N}-{name}）/ Per Milestone（gsd/{version}-{name}））
Enable context window warnings?（超过 65% 时注入告警，避免上下文耗尽丢工作）

3.4 Text Mode：非 Claude 运行时的降级路径

settings 工作流支持文本模式：当 config 中 workflow.text_mode: true 或传入 --text flag 时，所有 AskUserQuestion 替换为纯文本编号列表，由用户输入编号作答。这是 OpenCode（原 Codex）、Gemini CLI 等不支持该 TUI 原语的运行时所必需的。若处于文本模式（即非 Claude 运行时），模型档位问题前还会插入一段说明：语义档位（Opus/Sonnet/Haiku）只在设置 runtime 后才会解析为运行时原生模型 ID，否则档位不生效，需选择 Inherit 或手工配置 model_overrides。

四、`--advanced`：七组高级旋钮与严格输入校验

/gsd:config --advanced 进入 settings-advanced 工作流，管理“除常见开关之外的一切用户可设项”。它被刻意设计成 settings（/gsd:settings）的伴生面板，两组合计覆盖全部用户可配置项。七个分组包括：Planning Tuning、Execution Tuning、Discussion Tuning、Cross-AI Execution、Git Customization、Runtime / Output、Runtime Model Tiers。

4.1 各组键与默认值总览

Planning Tuning：workflow.plan_bounce（false，外部校验脚本对 PLAN.md 二次把关）、workflow.plan_bounce_passes（2）、workflow.plan_bounce_script（null）、workflow.subagent_timeout（600 秒）、workflow.inline_plan_threshold（3，超过该任务数才拆分独立 PLAN.md）。

Execution Tuning：workflow.node_repair（true，验证失败后自动修复）、workflow.node_repair_budget（2）、workflow.auto_prune_state（false，阶段边界自动清理 STATE.md 过期条目）。

Discussion Tuning：workflow.max_discuss_passes（3，防无头模式下无限追问）。

Cross-AI Execution：workflow.cross_ai_execution（false，把阶段执行委托给外部 AI CLI）、workflow.cross_ai_command（null，从 stdin 收阶段提示、必须产出 SUMMARY.md 兼容输出）、workflow.cross_ai_timeout（300 秒）。

Git Customization：git.base_branch（main）、git.phase_branch_template（gsd/phase-{phase}-{slug}）、git.milestone_branch_template（gsd/{milestone}-{slug}）。

Runtime / Output：response_language（null）、context_window（200000，>=500000 时开启自适应上下文增强）、search_gitignored（false）、graphify.build_timeout（300 秒）。

4.2 三类严格的输入校验

settings-advanced 的交互对自由输入做了强约束，任何不符合规则的输入都会被拒绝并重新提问：

数值校验：*_passes、*_budget、*_timeout、*_threshold、context_window、graphify.build_timeout 必须是非负整数；plan_bounce_passes 与 max_discuss_passes 要求 >= 1，其余 >= 0。非数字绝不静默强转，空输入 = 保持现值。
分支模板校验：phase_branch_template / milestone_branch_template 的非默认值必须非空且至少含一个占位符（{phase}、{slug}、{milestone}），否则拒绝并提示可用变量。
可空字段：response_language、plan_bounce_script、cross_ai_command 允许“空输入即清空（写入 null）”。

4.3 Runtime Model Tiers：按运行时覆盖档位模型

第七组是本工作流最有深度的部分。它以“runtime”为坐标，展示内置的三档（opus / sonnet / haiku）模型默认值，并允许按 (runtime, tier) 写入覆盖键 model_profile_overrides.<runtime>.<tier>。内置档位默认值如下：

Runtime	`opus`	`sonnet`	`haiku`
`claude`	`claude-opus-4-7`	`claude-sonnet-4-6`	`claude-haiku-4-5`
`codex`	`gpt-5.4`	`gpt-5.3-codex`	`gpt-5.4-mini`
`gemini`	`gemini-3-pro`	`gemini-3-flash`	`gemini-2.5-flash-lite`
`qwen`	`qwen3-max-2026-01-23`	`qwen3-coder-plus`	`qwen3-coder-next`
`opencode`	`anthropic/claude-opus-4-7`	`anthropic/claude-sonnet-4-6`	`anthropic/claude-haiku-4-5`
`copilot`	`claude-opus-4-7`	`claude-sonnet-4-6`	`claude-haiku-4-5`
`hermes`	`anthropic/claude-opus-4-7`	`anthropic/claude-sonnet-4-6`	`anthropic/claude-haiku-4-5`
Group B（`kilo`、`cline`、`cursor`、`windsurf`、`augment`、`trae`、`codebuddy`、`antigravity`）	（无内置默认——由运行时自行处理模型选择）

界面先展示当前 runtime 与内置默认表，然后允许选择要配置的 runtime，最后对三个档位分别做 Keep current / Clear override / Enter model ID。落地命令即：

gsd-sdk query config-set runtime gemini
gsd-sdk query config-set model_profile_overrides.gemini.opus gemini-3-ultra
gsd-sdk query config-set model_profile_overrides.gemini.haiku null

“Keep current”一律跳过，绝不写入用户未明确改动的键。完整配置骨架与各字段行为可对照 docs/CONFIGURATION.md 中 “Runtime-Aware Profiles” 一节——其中内置档位表、优先级链（model_overrides[<agent>] → 运行时档位解析 → resolve_model_ids:"omit" → Claude 别名 → inherit）与此处完全一致，且权威档位目录位于 sdk/shared/model-catalog.json。

五、`--integrations`：连接类配置与密钥安全约定

/gsd:config --integrations 进入 settings-integrations 工作流。它被刻意与常见开关、高级调优分开，因为 API Key 与跨工具路由属于“连通性”问题而非工作流旋钮。它管理三块：搜索 API Key、code-review CLI 路由、agent-skill 注入。

5.1 搜索 API Key：掩码与安全边界

brave_search、firecrawl、exa_search 分别对应网页研究、深爬抓取与语义搜索，由工作流读取：

BRAVE=$(gsd-sdk query config-get brave_search --default null)
FIRECRAWL=$(gsd-sdk query config-get firecrawl --default null)
EXA=$(gsd-sdk query config-get exa_search --default null)

密钥的展示遵循统一掩码约定（实现见 get-shit-done/bin/lib/secrets.cjs）：≥8 字符渲染为 ****<last-4>，更短的渲染为 ****，空值渲染为 (unset)。明文只写入 .planning/config.json（该文件即安全边界），绝不回显到 AskUserQuestion 描述、确认表、日志或 config-set 输出。写入 / 清空分别为：

gsd-sdk query config-set brave_search "<value>"   # 输出自动掩码
gsd-sdk query config-set brave_search null        # 清空

5.2 Code-review CLI 路由：`review.models.<cli>`

review.models.<cli> 把“审查口味”映射为实际 shell 命令，code-review 工作流在请求匹配的口味时调用该命令。受支持的 cli slug 包括 claude（缺省使用会话模型）、codex（如 codex exec --model gpt-5）、gemini（如 gemini -m gemini-2.5-pro）、opencode（如 opencode run --model claude-sonnet-4）：

gsd-sdk query config-set review.models.<cli> "<command string>"

5.3 Agent-skill 注入：`agent_skills.<agent-type>`

agent_skills.<agent-type> 在 spawn agent 时向 frontmatter 注入额外技能名。agent-type slug 是可扩展的自由文本，但受正则 ^[a-zA-Z0-9_-]+$ 约束，任何含路径分隔符（/、\、..）、空白或 shell 元字符的输入都会被拒绝并重新提示——这是为了封死技能注入攻击面。内置快捷选项为 gsd-executor、gsd-planner、gsd-verifier，也支持 Custom 自定义 slug：

gsd-sdk query config-set agent_skills.gsd-executor "<skill-a,skill-b,skill-c>"

同样的校验也作用于 review.models.<cli>（动态键模式 ^review\.models\.[a-zA-Z0-9_-]+$）。完成时输出掩码化确认表，明文密钥在任何情况下都不出现。

六、`--profile <name>`：一行命令切换模型档位

这是四模式中唯一的纯内联命令入口：/gsd:config --profile <name> 不带任何交互直接切换模型档位。config.md 的 argument-hint 声明支持的档位为 quality | balanced | budget | inherit；从配置 schema 看，model_profile 字段还接受 adaptive 值（docs/CONFIGURATION.md），但交互选项以四种常规档位为准。

6.1 执行路径与 #2439 pre-flight 契约

命令行分支的执行序列如下（也是历史 bug #2439 修复后的契约形态）：

Pre-flight 检查（#2439）：先用 command -v gsd-sdk 确认 gsd-sdk 在 PATH 上；
缺失时的优雅降级：若未安装，输出安装提示 Install GSD via 'npm i -g get-shit-done' 后停止——绝不直接调用 gsd-sdk，避免用户只看到晦涩的 command not found: gsd-sdk；
正常执行：运行 gsd-sdk query config-set-model-profile <profile-name> --raw 并原样展示输出。

该契约同时被专门的回归测试锁住。在 tests/bug-2439-set-profile-gsd-sdk-preflight.test.cjs 中，测试断言 config.md 的 --profile 分支必须同时包含 command -v gsd-sdk 守卫与安装提示，且守卫文本必须出现在 gsd-sdk query config-set-model-profile 调用之前——否则回归会静默复发。

6.2 底层命令的行为（测试佐证）

config-set-model-profile 的语义由 tests/config.test.cjs（“config-set-model-profile command” describe 块）完整覆盖：

设置合法档位会更新 config 并返回 JSON 载荷：{ updated: true, profile: 'quality', previousProfile: '...', agentToModelMap: {...} }，其中 agentToModelMap 给出各 agent 在新档位下的模型解析结果；
档位名大小写不敏感（BALANCED → balanced）；
非法档位（如 turbo）被拒绝，报 Invalid profile；
未提供档位参数时报错；
config 缺失时先补建再写入（保证幂等可用）。

该命令同时接受 legacy gsd-tools.cjs 与 SDK 两套调用面，是“配置即命令、命令有输出”这一设计哲学的体现。

七、结果确认与保存为全局默认

无论走哪个交互模式，settings / settings-advanced / settings-integrations 收尾时都会打印一张更新确认表并给出后续快速命令提示。settings 的确认表形如：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► SETTINGS UPDATED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
| Setting              | Value |
|----------------------|-------|
| Model Profile        | balanced |
| Plan Researcher      | On     |
...

表中注明：“These settings apply to future /gsd:plan-phase and /gsd:execute-phase runs.”——即所有改动作用于后续规划与执行轮次，并列出快捷跳转：/gsd:config --integrations、/gsd:config --profile <profile>、/gsd:plan-phase --research | --skip-research | --skip-verify、/gsd:config --advanced。

交互收尾还会问一句“是否将当前设置存为所有新项目的默认值”。选 Yes 时，同样的配置对象（剔除 brave_search 这类项目专属字段）被写入 ~/.gsd/defaults.json：

mkdir -p ~/.gsd

写入的 defaults 结构包含 mode、granularity、model_profile、commit_docs、parallelization、branching_strategy、quick_branch_template、完整 workflow 块以及 intel / graphify 命名空间。此后 /gsd:new-project 创建新 config.json 时会读取全局默认值作为起始配置，项目级设置永远覆盖全局设置（参考 docs/CONFIGURATION.md 的 “Global Defaults” 一节）。

八、四模式速查卡

需求	命令	效果
调常见工作流开关 + 模型档位	`/gsd:config`	六组交互问题（settings）
规划回弹、超时、分支模板、跨 AI、上下文窗口	`/gsd:config --advanced`	七组高级面板（settings-advanced）
配 Brave/Firecrawl/Exa Key、审查 CLI、agent skills	`/gsd:config --integrations`	三块连接类配置（settings-integrations）
无交互切档位	`/gsd:config --profile balanced`	`gsd-sdk query config-set-model-profile`（含 #2439 pre-flight）
查看 / 手改任意键	`gsd-sdk query config-get / config-set <key.path> <value>`	中心校验 + 深合并，不触碰无关键

关键记忆点：① 配置文件在项目里可能是 .planning/config.json，也可能是 .planning/workstreams/<slug>/config.json，一切以 $GSD_CONFIG_PATH 解析结果为准；② 任何写入走 gsd-sdk query config-set，让中心校验器与深合并替你守住“不覆盖无关键”的不变量；③ API Key 明文只存在于 config.json，UI 永远只显示 ****<last-4>；④ --profile 是唯一零交互入口，且必须先过 command -v gsd-sdk 的 pre-flight 闸门。