人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载本指南以仓库 gitbook/configuration/preferences.md 为骨架结合src/resources/extensions/gsd/下的真实源码与测试系统讲解 GSD 的偏好Preferences体系配置文件存放位置、全局/项目合并规则、/gsd prefs向导命令以及models、token_profile、budget_ceiling、git、workspace、verification_commands等全部设置项的含义、取值与默认值。读完你可以从零写出一份可运行的PREFERENCES.md精确控制模型阶段路由、预算、超时、Git 策略与验证流程。一、什么是 GSD PreferencesGSD 的偏好配置是一组以 YAML frontmatter 形式存放在 Markdown 文件中的键值对用于控制自动模式auto mode与引导流程guided flow的默认行为。与直接修改源码或依赖交互式向导不同偏好文件是持久的、可版本化、可全局复用的配置载体。从源码看偏好体系的入口集中在 preferences.ts加载与合并、preferences-types.ts类型与已知键表、preferences-validation.ts校验TUI 向导实现在 commands-prefs-wizard.ts。PREFERENCES.md的解析采用严格的前置 frontmatter 格式文件以---开始配置内容写在---围栏内parsePreferencesMarkdown()也支持旧式「标题 列表」格式但官方推荐 YAML frontmatter。文件主体部分会原样保留可以作为备注说明。二、管理命令偏好向导与状态查看/gsd prefs # 打开全局偏好向导 /gsd prefs project # 打开项目偏好向导 /gsd prefs status # 显示当前生效值与来源无参数、global、wizard、setup均进入全局偏好向导project、wizard project、setup project进入项目偏好向导import-claude可带global/project可从 Claude 导入既有偏好status报告全局与项目偏好文件是否存在、加载路径含旧式 fallback、技能引用解析结果多少已解析、多少未解析。这些路由逻辑可以直接在 handlePrefs() 中看到。向导本身按类别分组Mode、Models、Timeouts、Git、Skills、Budget、Notifications、Parallelism、Verification、Hooks、Integrations 等每个类别都有「Add / Remove / Clear / Done」式的交互最终通过serializePreferencesToFrontmatter()写回文件。另外/gsd mode全局与/gsd mode project项目级可以快速设置工作流模式等价于在偏好文件中写入mode: solo或mode: team。三、偏好文件与合并规则作用域路径生效范围全局~/.gsd/PREFERENCES.md所有项目项目.gsd/PREFERENCES.md仅当前项目合并规则对应源码mergePreferences()与mergeStringLists()见 preferences.ts标量字段如budget_ceiling、token_profile项目定义则项目优先否则用全局值空值合并??语义数组字段如always_use_skills、prefer_skills、avoid_skills、custom_instructions、verification_commands直接拼接去重、过滤空值全局在前、项目在后对象字段如models、git、auto_supervisor、dynamic_routing、notifications浅合并项目按 key 覆盖。以models为例若全局设置planning: claude-opus-4-7项目只写了planning: claude-sonnet-4-6则planning以项目为准但项目未声明的research等阶段仍沿用全局值。还有两个更低优先级的默认层token_profile默认层当设置了token_profileGSD 会先按该 profile 生成模型与阶段跳过默认值再与用户显式偏好合并显式值永远覆盖 profile 默认。相关逻辑见loadEffectiveGSDPreferences()中的_resolveProfileDefaults()。mode模式默认层mode: solo或mode: team会按MODE_DEFAULTSpreferences-types.ts填充 Git 与里程碑 ID 默认值同样被任何显式设置覆盖。一个需要注意的细节planning_depth是项目级启动路由标记而非全局用户偏好。全局~/.gsd/PREFERENCES.md中写planning_depth: deep并不会让每个新仓库都进入深规划模式——loadEffectiveGSDPreferences()会在项目未显式声明时剥离该继承值stripInheritedPlanningDepth()。四、快速上手示例--- version: 1 # Model selection models: research: claude-sonnet-4-6 planning: claude-opus-4-7 execution: claude-sonnet-4-6 completion: claude-sonnet-4-6 # Token optimization token_profile: balanced # Project discovery planning_depth: deep # Budget budget_ceiling: 25.00 budget_enforcement: pause # Supervision auto_supervisor: soft_timeout_minutes: 15 hard_timeout_minutes: 25 # Git git: auto_push: true merge_strategy: squash isolation: none collapse_cadence: milestone # or slice — see Git Worktrees docs # milestone_resquash applies only when collapse_cadence: slice # milestone_resquash: true # collapse slice commits into one at milestone end # Verification verification_commands: - npm run lint - npm run test # Notifications notifications: on_milestone: true on_attention: true ---version: 1是当前唯一支持的 schema 版本校验器只接受 1其他值直接报unsupported version错误。collapse_cadence与milestone_resquash属于 Git 工作树相关细节完整说明见 git-settings.md。五、核心设置详解5.1models分阶段模型选择models是自动模式与引导流程中每个阶段使用的模型。支持三种写法models: research: claude-sonnet-4-6 # 简单字符串 planning: model: claude-opus-4-7 # 对象 fallbacks fallbacks: - openrouter/z-ai/glm-5 execution: claude-sonnet-4-6 execution_simple: claude-haiku-4-5 completion: claude-sonnet-4-6 subagent: claude-sonnet-4-6简单字符串单个模型无 fallbackProvider 限定字符串bedrock/claude-sonnet-4-6用于同一模型 ID 在多个 Provider 都存在时消除歧义对象格式{ model, provider?, fallbacks[] }主模型失败Provider 不可用、限流、额度耗尽时按序尝试 fallback 列表缺省行为省略某个阶段 key就使用当前激活模型。例外是discuss与validation——未设置时回退到planning。阶段 → 单元映射源码级在 preferences-models.ts 的resolveModelWithFallbacksForUnit()中可以看到具体路由research-milestone/research-slice/research-project→researchplan-milestone/plan-slice/refine-slice/replan-slice→planningdiscuss-milestone/discuss-slice/discuss-project/discuss-requirements/workflow-preferences/research-decision→discuss ?? planningexecute-task/reactive-execute→executionexecute-task-simple→execution_simple ?? executioncomplete-slice/complete-milestone/worktree-merge/run-uat→completionreassess-roadmap/rewrite-docs/gate-evaluate/validate-milestone→validation ?? planningsubagent及subagent/*→subagent另外当models.execution被配置时它会成为自动模式启动时的会话默认模型resolveDefaultSessionModel()优先级 execution → planning → 第一个已配置模型。更多选型思路参见 choosing-a-model.md。5.2token_profile成本/质量权衡token_profile协调模型选择、阶段跳过与上下文压缩可选值budget跳过 research/reassessment用更便宜的模型balanced默认为降低 token 消耗跳过 research/reassessmentquality偏好更高质量模型burn-max保持完整上下文默认、关闭降级路由、不跳过阶段。注意校验器认可的完整集合是budget / balanced / quality / burn-max见 preferences-validation.ts。详见 token-optimization.md。5.3planning_depth里程碑规划前的发现深度planning_depth: deep值行为light默认。走常规的里程碑讨论流程。deep在里程碑规划前依次运行 workflow preferences、.gsd/PROJECT.md、.gsd/REQUIREMENTS.md、research decision以及可选的 project research。启用 deep 模式有三种方式/gsd new-project --deep、/gsd new-milestone --deep或在项目级.gsd/PREFERENCES.md写入planning_depth: deep。research decision 记录在.gsd/runtime/research-decision.json选择执行研究时会生成.gsd/research/STACK.md、FEATURES.md、ARCHITECTURE.md、PITFALLS.md。源码层面planning-depth.ts 的setPlanningDepth()会把planning_depth持久化到项目偏好文件保留文件 body 与其他 frontmatter key并在 deep 模式时写入默认 research-decision。注意全局偏好文件中的planning_depth不会让每个新仓库自动进入 deep 模式。5.4 预算控制budget_ceiling/budget_enforcement/min_request_interval_msbudget_ceiling: 50.00budget_ceiling是自动模式的美元支出上限无默认上限。budget_enforcement决定到达上限后的行为值行为warn记录警告继续运行pause暂停自动模式默认halt完全停止自动模式min_request_interval_ms: 1000 # 两次 LLM 请求之间至少等待 1 秒min_request_interval_ms是自动模式 LLM 请求派发之间的最小毫秒间隔用于在限流 Provider 上主动放慢节奏、降低 429 错误。默认0禁用。非整数值向下取整如1000.9 → 1000。配套的成本管理能力如per_unit_cost_cap_usd单单元重试成本上限可参考 cost-management.md。5.5auto_supervisor自动模式监督超时auto_supervisor: soft_timeout_minutes: 20 # 警告 AI 尽快收尾 idle_timeout_minutes: 10 # 检测停滞 hard_timeout_minutes: 30 # 暂停自动模式soft_timeout_minutes默认 20到达后监督进程向 AI 发出软警告idle_timeout_minutes默认 10无活动时间超过该值视为停滞并干预hard_timeout_minutes默认 30到达后强制暂停自动模式model可选指定监督进程使用的模型缺省用当前激活模型。对应类型定义见 preferences-types.ts向导默认值见configureTimeouts()。5.6verification_commands任务后验证verification_commands: - npm run lint - npm run test verification_auto_fix: true # 失败后自动重试默认 verification_max_retries: 2 # 最大尝试次数默认2关键限制源码与文档共同确认验证命令必须是简单可执行命令支持管道|但拒绝逻辑或||拒绝重定向、、分号、反引号、命令替换$(...)——因为验证是以受控命令列表运行而非任意 shell 程序对任务级verify命令taskPlanVerifyGSD 按切分命令链并独立校验每段Unix 类系统按set -o pipefail语义运行管道中任一段失败都会导致整体失败。这条逻辑可在 verification-gate.ts 看到GSD 会先尝试bash -o pipefail -c失败后回退到sh -c。自动发现项目检查当verification_commands为空且没有任务级verify命令时GSD 自动发现项目检查——JavaScript 项目按package.jsonscripts 顺序尝试typecheck、lint、testPython 项目通过python-project发现源仅当存在明确的 pytest 证据时运行python3 -m pytest。pytest 证据包括pytest.ini、pyproject.toml中的[tool.pytest.ini_options]配置段或tests/下匹配 pytest 默认测试文件模式test_*.py或*_test.py的文件。5.7gitGit 行为与工作流模式git: auto_push: false merge_strategy: squash isolation: none commit_docs: true auto_pr: falseauto_push提交后自动 push 到远程默认falsepush_branches提交后把里程碑分支 push 到远程默认falseremotepush 目标 remote 名默认originsnapshots是否创建 WIP 快照提交如 pre-dispatch 与 doctor 发出的 stale-uncommitted 安全提交默认truepre_merge_checktrue总是运行、false从不运行、auto检测到 CI 时运行默认autocommit_type覆盖常规提交类型前缀合法值feat/fix/refactor/docs/test/chore/perf/ci/build/style默认按 diff 内容推断main_branch新仓库主分支名默认mainmerge_strategysquash合并为一个提交或merge保留单个提交默认squashisolationnone默认直接在当前分支工作适合 step-mode 热重载、worktree为里程碑创建工作树隔离、branch在项目根工作但创建里程碑分支适合 submodule 密集仓库。worktree模式要求存在已提交的HEAD在零提交仓库中 GSD 会临时按none处理直到首个提交存在。运行期解析在 getIsolationMode()manage_gitignorefalse时 GSD 完全不触碰.gitignore默认trueworktree_post_create工作树创建后运行的脚本接收SOURCE_DIR/WORKTREE_DIR环境变量30 秒超时失败仅告警auto_pr里程碑分支合并后自动创建 GitHub PR需要安装ghCLI默认falsepr_target_branch指定 PR 目标分支缺省为主分支已废弃commit_docs.gsd/始终被 gitignore、merge_to_main里程碑级合并总是启用。工作流模式速配与其逐项手写可用mode一键套用默认值最低优先级层显式设置永远覆盖设置soloteamgit.auto_pushtruefalsegit.push_branchesfalsetruegit.pre_merge_checkfalsetruegit.merge_strategysquashsquashgit.isolationnonenoneunique_milestone_idsfalsetrue完整字段清单见 git-settings.md。5.8workspace多仓库父工作区workspace: mode: parent repositories: frontend: path: apps/frontend role: web verification: - pnpm -C apps/frontend test commit_policy: auto backend: path: services/backend role: api verification: - pnpm -C services/backend test commit_policy: skip字段类型默认说明workspace.modeproject \| parentproject工作区运行模式workspace.repositoriesobject{}仓库 ID → 仓库配置映射workspace.repositories.id.pathstring必填子仓库路径相对项目根解析必须留在项目根内workspace.repositories.id.rolestring可选面向提示/报告的用途标签workspace.repositories.id.verificationstring[]可选该仓库的默认验证命令workspace.repositories.id.commit_policyauto \| skip可选每仓库的自动模式回合提交策略校验规则仓库 ID 必须匹配^[A-Za-z0-9][A-Za-z0-9._-]*$仓库路径会被规范化且必须唯一大小写不敏感解析后逃出项目根的路径被拒绝未知workspacekey 被忽略并产生警告隐式仓库project始终映射到项目根用户不能自定义workspace.repositories.project未指定targetRepositories时plan/task 默认[project]。5.9phases阶段粒度控制phases: skip_research: false skip_reassess: false skip_slice_research: true reassess_after_slice: true require_slice_discussion: falseskip_research跳过里程碑级研究默认falsereassess_after_slice每个 slice 完成后运行独立的路线图重估单元默认false对应 ADR-003 §4 的按需模式burn-maxprofile 会开启skip_reassess即使reassess_after_slice开启也强制禁用重估默认falseskip_slice_research跳过每个 slice 的研究默认false。通常这些标志由token_profile决定但可在此显式覆盖。5.10reactive_executionslice 内自动并行reactive_execution: enabled: false # 退出并行默认开启仅当任务计划 IO 注释产生无歧义图、且就绪的无冲突任务足够多时才派发并行批缺省时采用默认开启阈值 3 个就绪任务显式enabled: true使用更低的2 个就绪任务阈值可选字段max_parallel默认2范围1-8、isolation_mode: same-tree当前唯一支持值、subagent_modelreactive 子代理模型覆盖缺省走models.subagent。5.11skill_discovery与技能偏好值行为auto自动发现并应用技能suggest识别技能但不自动应用默认off完全禁用技能发现注意区分两件事skill_discovery决定 GSD是否在研究期间寻找相关技能解析见resolveSkillDiscoveryMode()always_use_skills/prefer_skills/avoid_skills/skill_rules决定用哪些技能。设置prefer_skills: []不会关闭技能发现只是没有偏好覆盖而已要彻底关闭需用skill_discovery: off。always_use_skills: - debug-like-expert skill_rules: - when: task involves Clerk authentication use: - clerk - clerk-setup其他技能相关字段skill_staleness_daysN 天未使用的技能降权0关闭默认60、custom_instructions追加到每次会话的持久指令。5.12dynamic_routing按复杂度动态选模型dynamic_routing: enabled: true escalate_on_failure: true budget_pressure: trueenabled启用动态路由默认falsetier_modelslight/standard/heavy三档模型覆盖escalate_on_failure当前模型失败时升档默认truebudget_pressure预算吃紧时降档默认truecross_provider允许跨 Provider 路由默认truehooks路由 hook 会话默认truecapability_routing同档内按能力画像打分选模型需enabled: true默认false。详见 dynamic-model-routing.md。5.13notifications桌面通知notifications: enabled: true on_complete: true on_error: true on_milestone: true on_attention: true各开关默认均为trueon_budget用于预算阈值到达时通知。终端自动循环的错误会持久化activity/*-auto-crash-note.json错误通知会带上崩溃记录路径并提示用/gsd auto恢复。详细说明见 notifications.md。5.14remote_questions把问题路由到聊天工具remote_questions: channel: discord channel_id: 1234567890123456789 timeout_minutes: 5channelslack/discord/telegramchannel_id字符串或数字timeout_minutes问题超时分钟数钳制到1-30poll_interval_seconds轮询间隔钳制到2-30。适用于 headless 自动模式下把交互式问题推送到 Slack/Discord/Telegram。详见 remote-questions.md。5.15parallel里程碑级并行编排parallel: enabled: false max_workers: 2 budget_ceiling: 50.00enabled启用并行默认falsemax_workers最大并发 worker1-4默认2budget_ceiling每次并行运行的独立预算上限merge_strategyper-slice或per-milestone默认per-milestoneauto_mergeauto立即合并/confirm先确认默认/manual保留分支给你处理worker_model并行 worker 的模型覆盖如claude-haiku-4-5适合执行密集型里程碑降本。解析默认值见 resolveParallelConfig()。详见 parallel.md。5.16 其他常用设置custom_instructions: - Always use TypeScript strict mode - Prefer functional patterns over classescustom_instructions追加到每个会话的持久指令。项目级持久知识建议用.gsd/KNOWLEDGE.md规则从文件读取模式与经验持久化到memories表并在下次会话开始时投影回KNOWLEDGE.mdcontext_pause_threshold上下文窗口使用率到达该百分比时暂停自动模式建议检查点默认0禁用。使用75这样的整数百分比不要用0.75show_token_cost在 footer 显示每次提示与累计会话 token 成本默认falselanguage所有 GSD 交互的响应语言接受任意语言名或代码Chinese、zh、German、de、日本語。设置后会在每个 agent 的系统提示注入 Always respond in language且/clear后依然生效。最快设置方式/gsd language name清除/gsd language off。六、校验、容错与最佳实践未知键处理GSD 维护了一张已知偏好键集合KNOWN_PREFERENCE_KEYSpreferences-types.ts。校验器对不在表内的 key 发出警告对常见的历史遗留写法如顶层isolation、auto_push、main_branch、taskIsolation给出迁移提示指向git.isolation、git.auto_push、git.main_branch等正确位置见 preferences-validation.ts。空数组语义空数组[]与完全省略等价。校验器在validatePreferences()中会删除空的always_use_skills、prefer_skills、avoid_skills、custom_instructions。建议不需要的字段直接省略空数组只会增加噪音而没有效果。解析容错frontmatter 解析失败或文件无---围栏时GSD 会按「标题 列表」旧格式尝试解析若仍失败则发出一次性警告并忽略该文件不会阻断运行见parsePreferencesMarkdown()与parseHeadingListFormat()。最佳实践汇总always_use_skills保持精简用skill_rules做场景化路由而不是宽泛的个性偏好内置技能优先用技能名本地个人技能优先用绝对路径省略不需要的字段需要验证配置是否生效时用/gsd prefs status查看当前生效值与来源。七、完整示例汇编模式 覆盖team 模式但显式开启 auto-push--- version: 1 mode: team git: auto_push: true ---带 fallback 的模型链主模型限流时自动切换--- version: 1 models: research: model: openrouter/deepseek/deepseek-r1 fallbacks: - openrouter/minimax/minimax-m2.5 planning: model: claude-opus-4-6 fallbacks: - openrouter/z-ai/glm-5 execution: model: openrouter/z-ai/glm-5 fallbacks: - openrouter/minimax/minimax-m2.5 completion: openrouter/minimax/minimax-m2.5 ---Provider 定位同一模型 ID 在多 Provider 存在时消除歧义--- version: 1 models: research: bedrock/claude-sonnet-4-6 planning: anthropic/claude-opus-4-6 execution: model: claude-sonnet-4-6 provider: bedrock fallbacks: - anthropic/claude-sonnet-4-6 ---预算与成本控制--- version: 1 budget_ceiling: 10.00 budget_enforcement: pause context_pause_threshold: 80 ---验证与钩子--- version: 1 verification_commands: - npm test - npm run lint verification_auto_fix: true verification_max_retries: 2 post_unit_hooks: - name: code-review after: - execute-task prompt: Review the code changes in {sliceId}/{taskId} for quality, security, and test coverage. max_cycles: 1 artifact: REVIEW.md ---更多字段级详解与示例含 pre-dispatch hooks 的 modify/skip/replace 三种动作、cmux、RTK 实验特性等见仓库内的 preferences-reference.md其覆盖的偏好键范围比本文更广是排查未知键、配置钩子与技能路由时的第一手权威参考。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐GSD 配置完全指南从偏好文件到模型路由、MCP 与自动模式调优GSD 配置完全指南从偏好文件到模型路由、MCP 与自动模式调优 GSDGitHub 加速计划下的 gsd 2 仓库是一个面向长时间自主运行的 meta人工智能AI Agent代码智能体Agent 编排CLIAI 应用GSD Preferences Wizard 完整指南用 /gsd prefs wizard 覆盖全部偏好字段告别手写 YAMLGSD Preferences Wizard 完整指南用 /gsd prefs wizard 覆盖全部偏好字段告别手写 YAML 导读 GSDGitHub人工智能AI Agent代码智能体Agent 编排CLIAI 应用GSD-2 的 Git 与 Worktree 配置全解隔离模式、Collapse Cadence 与自动化提交策略GSD 2 的 Git 与 Worktree 配置全解隔离模式、Collapse Cadence 与自动化提交策略 GSD 2GitHub 加速计划 / g人工智能AI Agent代码智能体Agent 编排CLIAI 应用上一篇如何高效保存B站视频BiliTools全能下载解决方案让你无忧离线观看下一篇ImageMagick 6还是7Imagick双版本兼容开发终极指南与shim层原理剖析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/6 7:41:12 · 阅读 1.2k GSD Preferences 完整指南：用 YAML frontmatter 精细配置 gsd-2 的自动模式、模型路由与执行策略
人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载本指南以仓库 gitbook/configuration/preferences.md 为骨架结合src/resources/extensions/gsd/下的真实源码与测试系统讲解 GSD 的偏好Preferences体系配置文件存放位置、全局/项目合并规则、/gsd prefs向导命令以及models、token_profile、budget_ceiling、git、workspace、verification_commands等全部设置项的含义、取值与默认值。读完你可以从零写出一份可运行的PREFERENCES.md精确控制模型阶段路由、预算、超时、Git 策略与验证流程。一、什么是 GSD PreferencesGSD 的偏好配置是一组以 YAML frontmatter 形式存放在 Markdown 文件中的键值对用于控制自动模式auto mode与引导流程guided flow的默认行为。与直接修改源码或依赖交互式向导不同偏好文件是持久的、可版本化、可全局复用的配置载体。从源码看偏好体系的入口集中在 preferences.ts加载与合并、preferences-types.ts类型与已知键表、preferences-validation.ts校验TUI 向导实现在 commands-prefs-wizard.ts。PREFERENCES.md的解析采用严格的前置 frontmatter 格式文件以---开始配置内容写在---围栏内parsePreferencesMarkdown()也支持旧式「标题 列表」格式但官方推荐 YAML frontmatter。文件主体部分会原样保留可以作为备注说明。二、管理命令偏好向导与状态查看/gsd prefs # 打开全局偏好向导 /gsd prefs project # 打开项目偏好向导 /gsd prefs status # 显示当前生效值与来源无参数、global、wizard、setup均进入全局偏好向导project、wizard project、setup project进入项目偏好向导import-claude可带global/project可从 Claude 导入既有偏好status报告全局与项目偏好文件是否存在、加载路径含旧式 fallback、技能引用解析结果多少已解析、多少未解析。这些路由逻辑可以直接在 handlePrefs() 中看到。向导本身按类别分组Mode、Models、Timeouts、Git、Skills、Budget、Notifications、Parallelism、Verification、Hooks、Integrations 等每个类别都有「Add / Remove / Clear / Done」式的交互最终通过serializePreferencesToFrontmatter()写回文件。另外/gsd mode全局与/gsd mode project项目级可以快速设置工作流模式等价于在偏好文件中写入mode: solo或mode: team。三、偏好文件与合并规则作用域路径生效范围全局~/.gsd/PREFERENCES.md所有项目项目.gsd/PREFERENCES.md仅当前项目合并规则对应源码mergePreferences()与mergeStringLists()见 preferences.ts标量字段如budget_ceiling、token_profile项目定义则项目优先否则用全局值空值合并??语义数组字段如always_use_skills、prefer_skills、avoid_skills、custom_instructions、verification_commands直接拼接去重、过滤空值全局在前、项目在后对象字段如models、git、auto_supervisor、dynamic_routing、notifications浅合并项目按 key 覆盖。以models为例若全局设置planning: claude-opus-4-7项目只写了planning: claude-sonnet-4-6则planning以项目为准但项目未声明的research等阶段仍沿用全局值。还有两个更低优先级的默认层token_profile默认层当设置了token_profileGSD 会先按该 profile 生成模型与阶段跳过默认值再与用户显式偏好合并显式值永远覆盖 profile 默认。相关逻辑见loadEffectiveGSDPreferences()中的_resolveProfileDefaults()。mode模式默认层mode: solo或mode: team会按MODE_DEFAULTSpreferences-types.ts填充 Git 与里程碑 ID 默认值同样被任何显式设置覆盖。一个需要注意的细节planning_depth是项目级启动路由标记而非全局用户偏好。全局~/.gsd/PREFERENCES.md中写planning_depth: deep并不会让每个新仓库都进入深规划模式——loadEffectiveGSDPreferences()会在项目未显式声明时剥离该继承值stripInheritedPlanningDepth()。四、快速上手示例--- version: 1 # Model selection models: research: claude-sonnet-4-6 planning: claude-opus-4-7 execution: claude-sonnet-4-6 completion: claude-sonnet-4-6 # Token optimization token_profile: balanced # Project discovery planning_depth: deep # Budget budget_ceiling: 25.00 budget_enforcement: pause # Supervision auto_supervisor: soft_timeout_minutes: 15 hard_timeout_minutes: 25 # Git git: auto_push: true merge_strategy: squash isolation: none collapse_cadence: milestone # or slice — see Git Worktrees docs # milestone_resquash applies only when collapse_cadence: slice # milestone_resquash: true # collapse slice commits into one at milestone end # Verification verification_commands: - npm run lint - npm run test # Notifications notifications: on_milestone: true on_attention: true ---version: 1是当前唯一支持的 schema 版本校验器只接受 1其他值直接报unsupported version错误。collapse_cadence与milestone_resquash属于 Git 工作树相关细节完整说明见 git-settings.md。五、核心设置详解5.1models分阶段模型选择models是自动模式与引导流程中每个阶段使用的模型。支持三种写法models: research: claude-sonnet-4-6 # 简单字符串 planning: model: claude-opus-4-7 # 对象 fallbacks fallbacks: - openrouter/z-ai/glm-5 execution: claude-sonnet-4-6 execution_simple: claude-haiku-4-5 completion: claude-sonnet-4-6 subagent: claude-sonnet-4-6简单字符串单个模型无 fallbackProvider 限定字符串bedrock/claude-sonnet-4-6用于同一模型 ID 在多个 Provider 都存在时消除歧义对象格式{ model, provider?, fallbacks[] }主模型失败Provider 不可用、限流、额度耗尽时按序尝试 fallback 列表缺省行为省略某个阶段 key就使用当前激活模型。例外是discuss与validation——未设置时回退到planning。阶段 → 单元映射源码级在 preferences-models.ts 的resolveModelWithFallbacksForUnit()中可以看到具体路由research-milestone/research-slice/research-project→researchplan-milestone/plan-slice/refine-slice/replan-slice→planningdiscuss-milestone/discuss-slice/discuss-project/discuss-requirements/workflow-preferences/research-decision→discuss ?? planningexecute-task/reactive-execute→executionexecute-task-simple→execution_simple ?? executioncomplete-slice/complete-milestone/worktree-merge/run-uat→completionreassess-roadmap/rewrite-docs/gate-evaluate/validate-milestone→validation ?? planningsubagent及subagent/*→subagent另外当models.execution被配置时它会成为自动模式启动时的会话默认模型resolveDefaultSessionModel()优先级 execution → planning → 第一个已配置模型。更多选型思路参见 choosing-a-model.md。5.2token_profile成本/质量权衡token_profile协调模型选择、阶段跳过与上下文压缩可选值budget跳过 research/reassessment用更便宜的模型balanced默认为降低 token 消耗跳过 research/reassessmentquality偏好更高质量模型burn-max保持完整上下文默认、关闭降级路由、不跳过阶段。注意校验器认可的完整集合是budget / balanced / quality / burn-max见 preferences-validation.ts。详见 token-optimization.md。5.3planning_depth里程碑规划前的发现深度planning_depth: deep值行为light默认。走常规的里程碑讨论流程。deep在里程碑规划前依次运行 workflow preferences、.gsd/PROJECT.md、.gsd/REQUIREMENTS.md、research decision以及可选的 project research。启用 deep 模式有三种方式/gsd new-project --deep、/gsd new-milestone --deep或在项目级.gsd/PREFERENCES.md写入planning_depth: deep。research decision 记录在.gsd/runtime/research-decision.json选择执行研究时会生成.gsd/research/STACK.md、FEATURES.md、ARCHITECTURE.md、PITFALLS.md。源码层面planning-depth.ts 的setPlanningDepth()会把planning_depth持久化到项目偏好文件保留文件 body 与其他 frontmatter key并在 deep 模式时写入默认 research-decision。注意全局偏好文件中的planning_depth不会让每个新仓库自动进入 deep 模式。5.4 预算控制budget_ceiling/budget_enforcement/min_request_interval_msbudget_ceiling: 50.00budget_ceiling是自动模式的美元支出上限无默认上限。budget_enforcement决定到达上限后的行为值行为warn记录警告继续运行pause暂停自动模式默认halt完全停止自动模式min_request_interval_ms: 1000 # 两次 LLM 请求之间至少等待 1 秒min_request_interval_ms是自动模式 LLM 请求派发之间的最小毫秒间隔用于在限流 Provider 上主动放慢节奏、降低 429 错误。默认0禁用。非整数值向下取整如1000.9 → 1000。配套的成本管理能力如per_unit_cost_cap_usd单单元重试成本上限可参考 cost-management.md。5.5auto_supervisor自动模式监督超时auto_supervisor: soft_timeout_minutes: 20 # 警告 AI 尽快收尾 idle_timeout_minutes: 10 # 检测停滞 hard_timeout_minutes: 30 # 暂停自动模式soft_timeout_minutes默认 20到达后监督进程向 AI 发出软警告idle_timeout_minutes默认 10无活动时间超过该值视为停滞并干预hard_timeout_minutes默认 30到达后强制暂停自动模式model可选指定监督进程使用的模型缺省用当前激活模型。对应类型定义见 preferences-types.ts向导默认值见configureTimeouts()。5.6verification_commands任务后验证verification_commands: - npm run lint - npm run test verification_auto_fix: true # 失败后自动重试默认 verification_max_retries: 2 # 最大尝试次数默认2关键限制源码与文档共同确认验证命令必须是简单可执行命令支持管道|但拒绝逻辑或||拒绝重定向、、分号、反引号、命令替换$(...)——因为验证是以受控命令列表运行而非任意 shell 程序对任务级verify命令taskPlanVerifyGSD 按切分命令链并独立校验每段Unix 类系统按set -o pipefail语义运行管道中任一段失败都会导致整体失败。这条逻辑可在 verification-gate.ts 看到GSD 会先尝试bash -o pipefail -c失败后回退到sh -c。自动发现项目检查当verification_commands为空且没有任务级verify命令时GSD 自动发现项目检查——JavaScript 项目按package.jsonscripts 顺序尝试typecheck、lint、testPython 项目通过python-project发现源仅当存在明确的 pytest 证据时运行python3 -m pytest。pytest 证据包括pytest.ini、pyproject.toml中的[tool.pytest.ini_options]配置段或tests/下匹配 pytest 默认测试文件模式test_*.py或*_test.py的文件。5.7gitGit 行为与工作流模式git: auto_push: false merge_strategy: squash isolation: none commit_docs: true auto_pr: falseauto_push提交后自动 push 到远程默认falsepush_branches提交后把里程碑分支 push 到远程默认falseremotepush 目标 remote 名默认originsnapshots是否创建 WIP 快照提交如 pre-dispatch 与 doctor 发出的 stale-uncommitted 安全提交默认truepre_merge_checktrue总是运行、false从不运行、auto检测到 CI 时运行默认autocommit_type覆盖常规提交类型前缀合法值feat/fix/refactor/docs/test/chore/perf/ci/build/style默认按 diff 内容推断main_branch新仓库主分支名默认mainmerge_strategysquash合并为一个提交或merge保留单个提交默认squashisolationnone默认直接在当前分支工作适合 step-mode 热重载、worktree为里程碑创建工作树隔离、branch在项目根工作但创建里程碑分支适合 submodule 密集仓库。worktree模式要求存在已提交的HEAD在零提交仓库中 GSD 会临时按none处理直到首个提交存在。运行期解析在 getIsolationMode()manage_gitignorefalse时 GSD 完全不触碰.gitignore默认trueworktree_post_create工作树创建后运行的脚本接收SOURCE_DIR/WORKTREE_DIR环境变量30 秒超时失败仅告警auto_pr里程碑分支合并后自动创建 GitHub PR需要安装ghCLI默认falsepr_target_branch指定 PR 目标分支缺省为主分支已废弃commit_docs.gsd/始终被 gitignore、merge_to_main里程碑级合并总是启用。工作流模式速配与其逐项手写可用mode一键套用默认值最低优先级层显式设置永远覆盖设置soloteamgit.auto_pushtruefalsegit.push_branchesfalsetruegit.pre_merge_checkfalsetruegit.merge_strategysquashsquashgit.isolationnonenoneunique_milestone_idsfalsetrue完整字段清单见 git-settings.md。5.8workspace多仓库父工作区workspace: mode: parent repositories: frontend: path: apps/frontend role: web verification: - pnpm -C apps/frontend test commit_policy: auto backend: path: services/backend role: api verification: - pnpm -C services/backend test commit_policy: skip字段类型默认说明workspace.modeproject \| parentproject工作区运行模式workspace.repositoriesobject{}仓库 ID → 仓库配置映射workspace.repositories.id.pathstring必填子仓库路径相对项目根解析必须留在项目根内workspace.repositories.id.rolestring可选面向提示/报告的用途标签workspace.repositories.id.verificationstring[]可选该仓库的默认验证命令workspace.repositories.id.commit_policyauto \| skip可选每仓库的自动模式回合提交策略校验规则仓库 ID 必须匹配^[A-Za-z0-9][A-Za-z0-9._-]*$仓库路径会被规范化且必须唯一大小写不敏感解析后逃出项目根的路径被拒绝未知workspacekey 被忽略并产生警告隐式仓库project始终映射到项目根用户不能自定义workspace.repositories.project未指定targetRepositories时plan/task 默认[project]。5.9phases阶段粒度控制phases: skip_research: false skip_reassess: false skip_slice_research: true reassess_after_slice: true require_slice_discussion: falseskip_research跳过里程碑级研究默认falsereassess_after_slice每个 slice 完成后运行独立的路线图重估单元默认false对应 ADR-003 §4 的按需模式burn-maxprofile 会开启skip_reassess即使reassess_after_slice开启也强制禁用重估默认falseskip_slice_research跳过每个 slice 的研究默认false。通常这些标志由token_profile决定但可在此显式覆盖。5.10reactive_executionslice 内自动并行reactive_execution: enabled: false # 退出并行默认开启仅当任务计划 IO 注释产生无歧义图、且就绪的无冲突任务足够多时才派发并行批缺省时采用默认开启阈值 3 个就绪任务显式enabled: true使用更低的2 个就绪任务阈值可选字段max_parallel默认2范围1-8、isolation_mode: same-tree当前唯一支持值、subagent_modelreactive 子代理模型覆盖缺省走models.subagent。5.11skill_discovery与技能偏好值行为auto自动发现并应用技能suggest识别技能但不自动应用默认off完全禁用技能发现注意区分两件事skill_discovery决定 GSD是否在研究期间寻找相关技能解析见resolveSkillDiscoveryMode()always_use_skills/prefer_skills/avoid_skills/skill_rules决定用哪些技能。设置prefer_skills: []不会关闭技能发现只是没有偏好覆盖而已要彻底关闭需用skill_discovery: off。always_use_skills: - debug-like-expert skill_rules: - when: task involves Clerk authentication use: - clerk - clerk-setup其他技能相关字段skill_staleness_daysN 天未使用的技能降权0关闭默认60、custom_instructions追加到每次会话的持久指令。5.12dynamic_routing按复杂度动态选模型dynamic_routing: enabled: true escalate_on_failure: true budget_pressure: trueenabled启用动态路由默认falsetier_modelslight/standard/heavy三档模型覆盖escalate_on_failure当前模型失败时升档默认truebudget_pressure预算吃紧时降档默认truecross_provider允许跨 Provider 路由默认truehooks路由 hook 会话默认truecapability_routing同档内按能力画像打分选模型需enabled: true默认false。详见 dynamic-model-routing.md。5.13notifications桌面通知notifications: enabled: true on_complete: true on_error: true on_milestone: true on_attention: true各开关默认均为trueon_budget用于预算阈值到达时通知。终端自动循环的错误会持久化activity/*-auto-crash-note.json错误通知会带上崩溃记录路径并提示用/gsd auto恢复。详细说明见 notifications.md。5.14remote_questions把问题路由到聊天工具remote_questions: channel: discord channel_id: 1234567890123456789 timeout_minutes: 5channelslack/discord/telegramchannel_id字符串或数字timeout_minutes问题超时分钟数钳制到1-30poll_interval_seconds轮询间隔钳制到2-30。适用于 headless 自动模式下把交互式问题推送到 Slack/Discord/Telegram。详见 remote-questions.md。5.15parallel里程碑级并行编排parallel: enabled: false max_workers: 2 budget_ceiling: 50.00enabled启用并行默认falsemax_workers最大并发 worker1-4默认2budget_ceiling每次并行运行的独立预算上限merge_strategyper-slice或per-milestone默认per-milestoneauto_mergeauto立即合并/confirm先确认默认/manual保留分支给你处理worker_model并行 worker 的模型覆盖如claude-haiku-4-5适合执行密集型里程碑降本。解析默认值见 resolveParallelConfig()。详见 parallel.md。5.16 其他常用设置custom_instructions: - Always use TypeScript strict mode - Prefer functional patterns over classescustom_instructions追加到每个会话的持久指令。项目级持久知识建议用.gsd/KNOWLEDGE.md规则从文件读取模式与经验持久化到memories表并在下次会话开始时投影回KNOWLEDGE.mdcontext_pause_threshold上下文窗口使用率到达该百分比时暂停自动模式建议检查点默认0禁用。使用75这样的整数百分比不要用0.75show_token_cost在 footer 显示每次提示与累计会话 token 成本默认falselanguage所有 GSD 交互的响应语言接受任意语言名或代码Chinese、zh、German、de、日本語。设置后会在每个 agent 的系统提示注入 Always respond in language且/clear后依然生效。最快设置方式/gsd language name清除/gsd language off。六、校验、容错与最佳实践未知键处理GSD 维护了一张已知偏好键集合KNOWN_PREFERENCE_KEYSpreferences-types.ts。校验器对不在表内的 key 发出警告对常见的历史遗留写法如顶层isolation、auto_push、main_branch、taskIsolation给出迁移提示指向git.isolation、git.auto_push、git.main_branch等正确位置见 preferences-validation.ts。空数组语义空数组[]与完全省略等价。校验器在validatePreferences()中会删除空的always_use_skills、prefer_skills、avoid_skills、custom_instructions。建议不需要的字段直接省略空数组只会增加噪音而没有效果。解析容错frontmatter 解析失败或文件无---围栏时GSD 会按「标题 列表」旧格式尝试解析若仍失败则发出一次性警告并忽略该文件不会阻断运行见parsePreferencesMarkdown()与parseHeadingListFormat()。最佳实践汇总always_use_skills保持精简用skill_rules做场景化路由而不是宽泛的个性偏好内置技能优先用技能名本地个人技能优先用绝对路径省略不需要的字段需要验证配置是否生效时用/gsd prefs status查看当前生效值与来源。七、完整示例汇编模式 覆盖team 模式但显式开启 auto-push--- version: 1 mode: team git: auto_push: true ---带 fallback 的模型链主模型限流时自动切换--- version: 1 models: research: model: openrouter/deepseek/deepseek-r1 fallbacks: - openrouter/minimax/minimax-m2.5 planning: model: claude-opus-4-6 fallbacks: - openrouter/z-ai/glm-5 execution: model: openrouter/z-ai/glm-5 fallbacks: - openrouter/minimax/minimax-m2.5 completion: openrouter/minimax/minimax-m2.5 ---Provider 定位同一模型 ID 在多 Provider 存在时消除歧义--- version: 1 models: research: bedrock/claude-sonnet-4-6 planning: anthropic/claude-opus-4-6 execution: model: claude-sonnet-4-6 provider: bedrock fallbacks: - anthropic/claude-sonnet-4-6 ---预算与成本控制--- version: 1 budget_ceiling: 10.00 budget_enforcement: pause context_pause_threshold: 80 ---验证与钩子--- version: 1 verification_commands: - npm test - npm run lint verification_auto_fix: true verification_max_retries: 2 post_unit_hooks: - name: code-review after: - execute-task prompt: Review the code changes in {sliceId}/{taskId} for quality, security, and test coverage. max_cycles: 1 artifact: REVIEW.md ---更多字段级详解与示例含 pre-dispatch hooks 的 modify/skip/replace 三种动作、cmux、RTK 实验特性等见仓库内的 preferences-reference.md其覆盖的偏好键范围比本文更广是排查未知键、配置钩子与技能路由时的第一手权威参考。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐GSD 配置完全指南从偏好文件到模型路由、MCP 与自动模式调优GSD 配置完全指南从偏好文件到模型路由、MCP 与自动模式调优 GSDGitHub 加速计划下的 gsd 2 仓库是一个面向长时间自主运行的 meta人工智能AI Agent代码智能体Agent 编排CLIAI 应用GSD Preferences Wizard 完整指南用 /gsd prefs wizard 覆盖全部偏好字段告别手写 YAMLGSD Preferences Wizard 完整指南用 /gsd prefs wizard 覆盖全部偏好字段告别手写 YAML 导读 GSDGitHub人工智能AI Agent代码智能体Agent 编排CLIAI 应用GSD-2 的 Git 与 Worktree 配置全解隔离模式、Collapse Cadence 与自动化提交策略GSD 2 的 Git 与 Worktree 配置全解隔离模式、Collapse Cadence 与自动化提交策略 GSD 2GitHub 加速计划 / g人工智能AI Agent代码智能体Agent 编排CLIAI 应用上一篇如何高效保存B站视频BiliTools全能下载解决方案让你无忧离线观看下一篇ImageMagick 6还是7Imagick双版本兼容开发终极指南与shim层原理剖析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考