get-shit-done /gsd:ingest-docs 文档导入实战从 ADR/PRD/SPEC 一键合成 .planning 规划体系【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-doneget-shit-doneGSD的/gsd:ingest-docs命令用于把仓库中已经沉淀的架构决策ADR、产品需求PRD、技术规格SPEC/RFC与通用文档DOC一次性反向吸收进规范化的.planning/规划体系没有.planning/时做全新初始化new已有规划时做增量合并merge。读完本文你将掌握该命令的完整参数用法、目录约定与 manifest 清单两种发现机制、ADR SPEC PRD DOC 的冲突裁决优先级以及贯穿全程的三级冲突报告与 BLOCKER 安全门禁机制。/gsd:ingest-docs的命令定义位于 commands/gsd/ingest-docs.md真正承载执行步骤的是 get-shit-done/workflows/ingest-docs.md。它属于 GSD规格驱动开发 上下文工程体系中对存量资产的回填入口与/gsd:import外部项目迁移互补与/gsd:new-project从零启动并列。一、命令职责一次通过地构建完整.planning/布局/gsd:ingest-docs的核心目标在命令 frontmatter 的description中定义得十分明确Bootstrap or merge a.planning/setup from existing ADRs, PRDs, SPECs, and docs in a repo.即从多份既有规划文档中一次调用便产出完整的.planning/体系而不是要求你把旧文档中的内容手工逐条搬进新模板。它支持两种运行形态由命令目标自动决定形态触发条件产出全新初始化new.planning/目录不存在默认基于合成的文档内容生成PROJECT.mdREQUIREMENTS.mdROADMAP.mdSTATE.md最终产出委托给gsd-roadmapper合并进已有规划merge.planning/目录已存在默认把来自被摄入文档的阶段phases与需求requirements追加进现有文件对与既有锁定决策冲突的内容硬阻断hard-block两种模式有一个共同的安全底座当存在未解决的矛盾时任何目标文件都不得被写入。这条 BLOCKER 门禁来自 GSD 共享的冲突引擎契约 get-shit-done/references/doc-conflict-engine.mdingest-docs的ingest是它的操作名词operation noun之一。输入侧同样提供双通道既可以通过目录约定自动发现docs/adr/、docs/prd/、docs/specs/、docs/rfc/以及仓库根目录下的{ADR,PRD,SPEC,RFC}-*.md也可以通过显式--manifest fileYAML 清单逐份声明{path, type, precedence?}。v1 的硬性限制是单次调用最多摄入 50 份文档--resolve interactive交互式冲突解决预留给未来版本当前只支持auto。二、参数速览与执行流程命令的argument-hint声明了完整的入参形态[path] [--mode new|merge] [--manifest file] [--resolve auto|interactive]2.1 参数解析parse_arguments第一个位置参数若不以-开头→SCAN_PATH默认.仓库根。--mode new|merge→MODE默认自动探测。--manifest file→MANIFEST_PATH可选。--resolve auto|interactive→RESOLVE_MODE默认autov1 中传入interactive会直接以interactive resolution is planned for a future release拒绝。2.2 路径校验两重防线workflow 里对用户提供的路径做了严格安全校验这是任何会扫描文件树的命令都不可省的一步case {SCAN_PATH} in *..*) echo SECURITY_ERROR: path contains traversal sequence; exit 1 ;; esac test -d {SCAN_PATH} || echo PATH_NOT_FOUND if [ -n {MANIFEST_PATH} ]; then case {MANIFEST_PATH} in *..*) echo SECURITY_ERROR: manifest path contains traversal; exit 1 ;; esac test -f {MANIFEST_PATH} || echo MANIFEST_NOT_FOUND fi第一重防线用case拒绝路径穿越序列..第二重包含性校验containment要求在解析完相对路径后对SCAN_PATH与MANIFEST_PATH分别执行realpath或平台等价物归一化并断言结果必须落在realpath($REPO_ROOT)之下。即使路径不含..只要解析后指向仓库之外例如/tmp、C:\Windows一律拒绝。这两重校验也被 tests/ingest-docs.test.cjs 的结构化测试锁定为契约的一部分断言 workflow 必须包含traversal或case ... *..*模式。2.3 初始化与模式自动探测init_and_mode_detectworkflow 通过 GSD 工具入口查询当前项目状态INIT$(node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs init ingest-docs) if [[ $INIT file:* ]]; then INIT$(cat ${INIT#file:}); fi从返回的 INIT 中解析project_exists、planning_exists、has_git、git_worktree_root、in_nested_subdir、project_path等字段进而自动决定 MODEplanning_exists: true→MODEmergeplanning_exists: false→MODEnew一个值得注意的工程细节这条init ingest-docs分发链路本身就是一次 bug 修复的产物。回归测试 tests/bug-2801-ingest-docs-handler.test.cjs 记录了 bug #2801——此前 workflow 调用了不存在的gsd-sdk query init.ingest-docs实际安装的二进制是gsd-tools且gsd-tools init的分发 switch 缺少ingest-docs分支。修复方式是在gsd-tools.cjs的 init switch 中新增case ingest-docs、从 init 模块导出cmdInitIngestDocs并把 workflow 改为规范形式的node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs init ingest-docs调用。测试用node:test断言了该命令退出码为 0、返回 JSON 包含project_exists/planning_exists/has_git/project_path字段并锁定 bash 代码块内不得再出现gsd-sdk字样的回归条件。Git 初始化逻辑还专门规避了 bug #3491 的教训绝不在已存在的外层 worktree 内创建嵌套.git。若has_git: true且处于嵌套子目录只提示规划文件将由外层仓库在git_worktree_root追踪不执行git init。运行时runtime探测复用new-project的模式执行上下文路径含/.codex/判定为 codex、/.gemini/为 gemini、/.opencode/或/.config/opencode/为 opencode否则默认 claude上下文不可用时回退到CODEX_HOME、GEMINI_CONFIG_DIR、OPENCODE_CONFIG_DIR环境变量。2.4 发现文档discover_docs文档清单从三个来源按顺序构建命中即止① manifest若提供——权威来源。预期 YAML 形态docs: - path: docs/adr/0001-db.md type: ADR precedence: 0 # optional, lower higher precedence - path: docs/prd/auth.md type: PRD每条目包含path必填相对仓库根、type必填取 ADR|PRD|SPEC|DOC、precedence可选整数。manifest 由用户显式给出因而被视作对启发式分类的权威覆盖。② 目录约定提供 manifest 时跳过。workflow 内建了四条find规则# ADRs find {SCAN_PATH} -type f \( -path */adr/* -o -path */adrs/* -o -name ADR-*.md -o -regex .*/[0-9]\{4\}-.*\.md \) 2/dev/null # PRDs find {SCAN_PATH} -type f \( -path */prd/* -o -path */prds/* -o -name PRD-*.md \) 2/dev/null # SPECs / RFCs find {SCAN_PATH} -type f \( -path */spec/* -o -path */specs/* -o -path */rfc/* -o -path */rfcs/* -o -name SPEC-*.md -o -name RFC-*.md \) 2/dev/null # Generic docs (fall-through candidates) find {SCAN_PATH} -type f -path */docs/* -name *.md 2/dev/null多规则命中的同一文件在并集去重后只计一份。③ 内容启发式在分类阶段执行对于未命中任何约定的文档由分类器检查 frontmattertype:字段与 H1 标题来兜底归类。50 份上限在发现完成后强制执行超出即输出引导并退出GSD Discovered {N} docs, which exceeds the v1 cap of 50. Use --manifest to narrow the set to ≤ 50 files, or run /gsd:ingest-docs again with a narrower path.发现结果会以NADR |NPRD |NSPEC |NDOC |Nunclassified的清单展示给用户并经由AskUserQuestionapprove-revise-abort 模式征得批准后才进入分类阶段——用户必须在分类器启动前看到完整的文档分类列表。Abort 干净退出Ingest cancelled.Revise 则引导用--manifest或收窄路径重新运行。三、并行分类gsd-doc-classifier 如何判定一份文档确认清单后workflow 创建暂存目录.planning/intel/classifications/然后为每份文档并行派生gsd-doc-classifier子代理agent 定义见 agents/gsd-doc-classifier.md。Claude Code 中通过在单条消息内发出多个 Task 工具调用来实现并发Copilot 等顺序型运行时则回退为串行分发。每个分类器只处理分配到的一个文件产出结构化 JSON 并返回一行确认绝不越界读取被分配文档的传递引用。分类器维护五种类型的固定分类学taxonomy类型判定依据产出物与优先级ADR一次架构/技术决策Status: Accepted\|Proposed\|Superseded编号文件名0001-、ADR-001-含 Context/Decision/Consequences 小节锁定决策locked decisions默认最高优先级PRD从用户/业务视角描述产品行为user stories、验收标准、成功指标、goals/non-goals、as a user…需求requirements中优先级SPEC实现契约——API、schema、SLO、协议、数据模型端点表、请求/响应 schema技术约束constraints次于 ADRDOC通用说明性文档指南、教程、设计缘由、onboarding、runbook仅上下文context最低优先级UNKNOWN无法置信地归入以上任何类型记录信号交由合成器或用户裁决判定路径分为三层置信度依次递减先做快速启发式路径/文件名约定再读文件解析 frontmatter 与正文信号最后给出high|medium|low置信度。歧义规则是两种类型信号强度相当难以取舍时选取优先级更高的信号ADR SPEC PRD DOC并把歧义记录进notes。只有状态为Accepted的 ADR 才置locked: true——Proposed/Draft一律不算锁定这一约束被测试显式锁定only marks Accepted ADRs as locked。分类 JSON 会写入{OUTPUT_DIR}/{slug}-{source_hash}.json其中source_hash是对完整源文件路径POSIX 风格取 SHA-256 的前 8 个十六进制字符目的是让并行的多个分类器在处理同名文件如各处散落的README.md时互不冲突{ source_path: {FILEPATH}, type: ADR|PRD|SPEC|DOC|UNKNOWN, confidence: high|medium|low, manifest_override: false, title: ..., summary: ..., scope: [..., ...], cross_refs: [path/to/other.md, ...], locked: true, precedence: null, notes: Only populated when confidence is low or ambiguity was resolved }字段规则同样严格manifest_override: true仅在提供MANIFEST_TYPE时成立precedence默认为null仅在 manifest 声明后才填入整数文件必须用 Write 工具创建禁止用 heredoc 或Bash(cat EOF)。若任一分类器报错编排器立即中止且不再触碰.planning/。四、合成与优先级裁决gsd-doc-synthesizer当所有分类完成后workflow 派生一次gsd-doc-synthesizer子代理见 agents/gsd-doc-synthesizer.md。编排器传给它的核心上下文包括CLASSIFICATIONS_DIR: .planning/intel/classifications/ INTEL_DIR: .planning/intel/ CONFLICTS_PATH: .planning/INGEST-CONFLICTS.md MODE: {MODE} EXISTING_CONTEXT: {existing .planning files, merge 模式才填} PRECEDENCE: {默认 [ADR,SPEC,PRD,DOC] 或 manifest 覆盖}合成器不面向用户提问也不直接写PROJECT.md/REQUIREMENTS.md/ROADMAP.md那是gsd-roadmapper的职责它的工作只有两件合成 冲突浮出。产出四份分类型 intel 文件加两份报告.planning/intel/decisions.md—— 来自 ADR每份 ADR 一个条目保留标题、来源路径、状态locked/proposed、决策陈述与 scope每条必须带source:溯源.planning/intel/requirements.md—— 来自 PRD一条需求一个 ID按REQ-{slug}派生一份 PRD 通常产出多条需求.planning/intel/constraints.md—— 来自 SPEC约束按api-contract | schema | nfr | protocol分类.planning/intel/context.md—— 来自 DOC按主题追加、注明来源.planning/intel/SYNTHESIS.md—— 人读汇总作为下游gsd-roadmapper的唯一入口.planning/INGEST-CONFLICTS.md—— 三桶冲突报告。ORCHESTRATOR RULECodex 运行时调用Agent()之后编排器必须立即停止本任务不得在子代理活跃期间自行阅读或合成已分类文档等待子代理返回结果后再继续——这是为了防止重复劳动、互相冲突的编辑与上下文浪费。4.1 优先级规则precedence_rules合成器是优先级强制层precedence-enforcing layer其反模式列表明确写着静默合并、丢失锁定决策、幼稚去重都会污染下游每一个规划拿不准时浮出冲突而不是替你挑一个。核心裁决规则如下默认排序ADR SPEC PRD DOC当内容相互矛盾时优先级更高的来源胜出。per-doc 覆盖某分类带非空整数precedence时仅对该文档覆盖默认值数值越小优先级越高。锁定决策locked: true的 ADR 产出的决策任何来源包括另一份 LOCKED ADR都不能自动覆盖。LOCKED vs LOCKED摄入集中两把互相矛盾的锁 → 硬 BLOCKERnew与merge两种模式都一样绝不自动裁决。LOCKED vs 非 LOCKEDLOCKED 胜出记入 auto-resolved 桶并附理由。merge 模式的 LOCKED in ingest vs 既有锁定决策硬 BLOCKER。同一需求、跨 PRD 验收标准分歧不得二选一视为一条需求携带多份竞争验收变体competing acceptance variants全部写进competing-variants桶交由用户裁决。4.2 交叉引用环检测cycle_detection合成器会用cross_refs构建有向图并跑三色标记DFS环检测。发现环时每个环记录为一条 unresolved-blocker且不继续对成环集合做合成循环合成只会产出垃圾环外文档仍可继续合成。引用图遍历深度上限为 50一旦超出就以 BLOCKER 条目中止引导用户用--manifest收窄输入。4.3 七轮冲突探测 pass 与三桶归类合成器在提取出的 intel 上跑七类冲突检查每类都会落进三桶之一#检查项落桶1两把 LOCKED ADR 在同一 scope 上决策矛盾unresolved-blockers2merge 模式摄入决策与既有 CONTEXT.md 中标记 locked 的decisions矛盾unresolved-blockers3两份 PRD 在同一 scope 上需求重叠但验收标准不同competing-variants保留全部变体4SPEC 断言与更高优先级 ADR 决策矛盾auto-resolvedADR 胜记录理由5低优先级与非锁定高优先级矛盾auto-resolved6UNKNOWN 低置信度文档unresolved-blockers用户须重新打标7环检测阻断见上unresolved-blockers桶与共享冲突引擎的严重级别映射是固定的unresolved-blockers→[BLOCKER]门禁工作流、competing-variants→[WARNING]路由前必须由用户挑选、auto-resolved→[INFO]仅记录透明。五、三级冲突报告与 BLOCKER 安全门禁/gsd:ingest-docs依赖的共享契约 get-shit-done/references/doc-conflict-engine.md 被/gsd:import等同样向.planning/摄入外部内容的工作流复用因此把严重级别语义、报告格式与安全门禁统一定义为三方约定ingest-docs只负责声明自己的检查清单、加载的上下文与操作名词。5.1 严重级别语义[BLOCKER] — 不安全不得继续。工作流必须在不写任何目标文件的前提下退出。用于锁定决策矛盾、前置条件缺失、不可能达成的目标。[WARNING] — 歧义或部分重叠。工作流必须浮出警告并取得用户显式批准后才能写入绝不自动放行。[INFO] — 纯信息无门禁、无需提示写入报告仅为透明。5.2 报告格式纯文本禁 markdown 表格## Conflict Detection Report ### BLOCKERS ({N}) [BLOCKER] {Short title} Found: {what the incoming content says} Expected: {what existing project context requires} → {Specific action to resolve} ### WARNINGS ({N}) [WARNING] {Short title} Found: {what was detected} Impact: {what could go wrong} → {Suggested action} ### INFO ({N}) [INFO] {Short title} Note: {relevant information}每条目必须有Found:外加Expected:/Impact:/Note:之一BLOCKER 与 WARNING 还必须有→修复行。报告直接原样呈现给用户因此禁用 markdown 表格|---|。合成器给出了示例形态——例如 BLOCKER 条目可能同时声明docs/adr/0004-db.md选择 Postgres 而docs/adr/0011-db.md同为 Accepted、scope 同为 primary datastore选择 DynamoDB修复方向是将其中一份标记为 Superseded或在--manifest中显式设 precedence。5.3 门禁判定conflict_gateworkflow 的冲突门禁读取.planning/INGEST-CONFLICTS.md解析### BLOCKERS ({N})、### WARNINGS ({N})、### INFO ({N})三行统计后分支处理BLOCKERS 0呈现报告后显示GSD BLOCKED: {N} blockers must be resolved before ingest can proceed.不写PROJECT.md、REQUIREMENTS.md、ROADMAP.md、STATE.md中的任何一个暂存 intel 文件保留待检。WARNINGS 0 且 BLOCKERS 0呈现报告用AskUserQuestionapprove/abort询问用户是否手动解决竞争变体后继续Abort 则以 Ingest cancelled. Staged intel preserved at.planning/intel/. 干净退出。两者皆 0静默进入路由或可选显示GSD No conflicts. Auto-resolved: {N}.这条门禁在 tests/ingest-docs.test.cjs 中被系统性锁定测试断言 workflow 必须包含 BLOCKER/WARNING/INFO 三标签、必须包含no destination files/without writing类阻止性措辞、报告位置固定为INGEST-CONFLICTS.md并验证 shared reference 自身禁止 markdown 表格 BLOCKER 存在时退出不写的契约。同一测试文件还确认import命令同样消费这份共享引用佐证了它是跨工作流的统一契约。六、路由new 与 merge 的两种收敛路径6.1 new 模式委托 gsd-roadmapper 落盘通过门禁后若为 new 模式workflow 先审计gsd-roadmapper期望的PROJECT.md字段需求凡能从.planning/intel/SYNTHESIS.md推导出的项目 scope、goals/non-goals、约束、锁定决策一律从 intel 合成无法推导的项目名、面向开发者的成功指标、目标运行时则通过AskUserQuestion逐项最小化提问不做盘问式收集。随后把最终产出委托给gsd-roadmapper子代理Agent({ subagent_type: gsd-roadmapper, prompt: Mode: new-project-from-ingest Intel: .planning/intel/SYNTHESIS.md (entry point) Per-type intel: .planning/intel/{decisions,requirements,constraints,context}.md User-supplied fields: {collected in previous step} Produce: - .planning/PROJECT.md - .planning/REQUIREMENTS.md - .planning/ROADMAP.md - .planning/STATE.md Treat ADR-locked decisions as locked in PROJECT.md decisions blocks. })这里又一次出现 Codex 运行时的 ORCHESTRATOR RULE子代理活跃期间编排器不得自行读更多 intel、写规划工件或创建ROADMAP.md。6.2 merge 模式增量追加、先预览后落盘merge 模式先加载既有.planning/ROADMAP.md、.planning/PROJECT.md、.planning/REQUIREMENTS.md与.planning/phases/下所有CONTEXT.md。由于合成器在 ingest-vs-existing 的锁定矛盾上已经硬阻断能走到这一步即代表没有剩余 BLOCKER。合并计划按三类增量执行新需求.planning/intel/requirements.md中与既有REQUIREMENTS.md条目不重叠的 → 追加进REQUIREMENTS.md新决策.planning/intel/decisions.md中与既有CONTEXT.mddecisions块不重叠的 → 写入新 phase 的CONTEXT.md或追加到下一里程碑的需求新 scope按new-milestone.md模式派生出 phase 增补并追加进.planning/ROADMAP.md。落盘前merge 的差异预览会展示给用户并经 approve-revise-abort 门禁把关——沿用 get-shit-done/references/gate-prompts.md 中定义的问询模式。6.3 finalize提交与完成播报最终提交摄入结果merge 模式替换为实际变更文件集合node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs commit \ docs: ingest {N} docs from {SCAN_PATH} (#2387) --files \ .planning/PROJECT.md \ .planning/REQUIREMENTS.md \ .planning/ROADMAP.md \ .planning/STATE.md \ .planning/intel/ \ .planning/INGEST-CONFLICTS.md完成后显示 GSD ► INGEST DOCS COMPLETE 横幅并汇报运行的模式new/merge、摄入文档数与类型明细、锁定的决策/创建的需求/捕获的约束、冲突报告路径以及下一步指引——new 模式指向/gsd:plan-phase 1merge 模式指向首个新增 phase 对应的/gsd:plan-phase N。七、v1 边界与反模式清单ingest-docs 的 v1 实现主动划定了能力边界workflow 末尾的 Anti-Patterns 就是一份显式禁止清单值得使用者与维护者共同记住不得违反共享冲突引擎契约不使用 markdown 表格、不引入新严重级别标签、不可绕过 BLOCKER 门禁存在 BLOCKER 时绝不写PROJECT.md/REQUIREMENTS.md/ROADMAP.md/STATE.md不得跳过 50 份文档上限——更大的集合必须用--manifest收窄绝不自动裁决 LOCKED-vs-LOCKED 的 ADR 矛盾——两种模式下这都是 BLOCKER不得把多份竞争 PRD 验收变体拼成一个合并标准——全部保留给用户裁决不得绕过发现批准门禁——分类器派生前用户必须看到分类清单不得跳过SCAN_PATH/MANIFEST_PATH的路径校验不得在本 v1 实现--resolve interactive——该旗标预留须以未来版本提示拒绝。这些约束大多被 tests/ingest-docs.test.cjs 逐条以结构断言固化文件存在性、命令 frontmatter 含--mode/--manifest/--resolve、allowed-tools 含AskUserQuestion与Agent、必需引用已接线、50上限、BLOCKER 语义、gsd-doc-classifier/gsd-doc-synthesizer/gsd-roadmapper 的派生、v1 拒绝 interactive 等维护者可借此放心演进而无需担心破坏契约。八、实践建议何时用、怎么用综合命令语义与 workflow 细节/gsd:ingest-docs适合三类典型场景存量仓库启航 GSD代码与文档ADR/PRD/SPEC早已沉淀多年、但从未建立.planning/。此时无需手工搬运直接/gsd:ingest-docs以 new 模式初始化把历史决策自动映射为锁定决策与需求基线。持续吸收增量规划文档.planning/已存在、团队又习惯在docs/prd/、docs/specs/直接写新文档时用 merge 模式把新文档合成追加为新需求与新 phase保持规划体系与文档流同步。精确控制摄入集合当仓库文档量大、目录约定命中过多或存在歧义文档时编写--manifestYAML 显式声明path/type/precedence既能绕开 50 份上限收窄到 ≤50也能覆盖启发式分类结果。而interactive冲突解决、超出 50 份的更大规模摄入在 v1 中并未实现——设计上选择宁可阻断不可错写。这条取舍贯穿了/gsd:ingest-docs的每个环节从路径包含性校验、发现批准门禁、分类置信度建模、LOCKED 锁的强语义到最终的三桶冲突报告本质都是在为把自由文档安全地折叠进受控规划体系这一动作提供工程化护栏。对于希望深度定制或审计行为的人来说入口集中在三个文件命令契约 commands/gsd/ingest-docs.md、可执行步骤 get-shit-done/workflows/ingest-docs.md、以及共享语义 get-shit-done/references/doc-conflict-engine.md配套的分类器与合成器 Agent 定义位于 agents/gsd-doc-classifier.md 与 agents/gsd-doc-synthesizer.md行为契约则由 tests/ingest-docs.test.cjs 与 tests/bug-2801-ingest-docs-handler.test.cjs 守护。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 get-shit-done /gsd:ingest-docs 文档导入实战：从 ADR/PRD/SPEC 一键合成 .planning 规划体系
get-shit-done /gsd:ingest-docs 文档导入实战从 ADR/PRD/SPEC 一键合成 .planning 规划体系【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-doneget-shit-doneGSD的/gsd:ingest-docs命令用于把仓库中已经沉淀的架构决策ADR、产品需求PRD、技术规格SPEC/RFC与通用文档DOC一次性反向吸收进规范化的.planning/规划体系没有.planning/时做全新初始化new已有规划时做增量合并merge。读完本文你将掌握该命令的完整参数用法、目录约定与 manifest 清单两种发现机制、ADR SPEC PRD DOC 的冲突裁决优先级以及贯穿全程的三级冲突报告与 BLOCKER 安全门禁机制。/gsd:ingest-docs的命令定义位于 commands/gsd/ingest-docs.md真正承载执行步骤的是 get-shit-done/workflows/ingest-docs.md。它属于 GSD规格驱动开发 上下文工程体系中对存量资产的回填入口与/gsd:import外部项目迁移互补与/gsd:new-project从零启动并列。一、命令职责一次通过地构建完整.planning/布局/gsd:ingest-docs的核心目标在命令 frontmatter 的description中定义得十分明确Bootstrap or merge a.planning/setup from existing ADRs, PRDs, SPECs, and docs in a repo.即从多份既有规划文档中一次调用便产出完整的.planning/体系而不是要求你把旧文档中的内容手工逐条搬进新模板。它支持两种运行形态由命令目标自动决定形态触发条件产出全新初始化new.planning/目录不存在默认基于合成的文档内容生成PROJECT.mdREQUIREMENTS.mdROADMAP.mdSTATE.md最终产出委托给gsd-roadmapper合并进已有规划merge.planning/目录已存在默认把来自被摄入文档的阶段phases与需求requirements追加进现有文件对与既有锁定决策冲突的内容硬阻断hard-block两种模式有一个共同的安全底座当存在未解决的矛盾时任何目标文件都不得被写入。这条 BLOCKER 门禁来自 GSD 共享的冲突引擎契约 get-shit-done/references/doc-conflict-engine.mdingest-docs的ingest是它的操作名词operation noun之一。输入侧同样提供双通道既可以通过目录约定自动发现docs/adr/、docs/prd/、docs/specs/、docs/rfc/以及仓库根目录下的{ADR,PRD,SPEC,RFC}-*.md也可以通过显式--manifest fileYAML 清单逐份声明{path, type, precedence?}。v1 的硬性限制是单次调用最多摄入 50 份文档--resolve interactive交互式冲突解决预留给未来版本当前只支持auto。二、参数速览与执行流程命令的argument-hint声明了完整的入参形态[path] [--mode new|merge] [--manifest file] [--resolve auto|interactive]2.1 参数解析parse_arguments第一个位置参数若不以-开头→SCAN_PATH默认.仓库根。--mode new|merge→MODE默认自动探测。--manifest file→MANIFEST_PATH可选。--resolve auto|interactive→RESOLVE_MODE默认autov1 中传入interactive会直接以interactive resolution is planned for a future release拒绝。2.2 路径校验两重防线workflow 里对用户提供的路径做了严格安全校验这是任何会扫描文件树的命令都不可省的一步case {SCAN_PATH} in *..*) echo SECURITY_ERROR: path contains traversal sequence; exit 1 ;; esac test -d {SCAN_PATH} || echo PATH_NOT_FOUND if [ -n {MANIFEST_PATH} ]; then case {MANIFEST_PATH} in *..*) echo SECURITY_ERROR: manifest path contains traversal; exit 1 ;; esac test -f {MANIFEST_PATH} || echo MANIFEST_NOT_FOUND fi第一重防线用case拒绝路径穿越序列..第二重包含性校验containment要求在解析完相对路径后对SCAN_PATH与MANIFEST_PATH分别执行realpath或平台等价物归一化并断言结果必须落在realpath($REPO_ROOT)之下。即使路径不含..只要解析后指向仓库之外例如/tmp、C:\Windows一律拒绝。这两重校验也被 tests/ingest-docs.test.cjs 的结构化测试锁定为契约的一部分断言 workflow 必须包含traversal或case ... *..*模式。2.3 初始化与模式自动探测init_and_mode_detectworkflow 通过 GSD 工具入口查询当前项目状态INIT$(node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs init ingest-docs) if [[ $INIT file:* ]]; then INIT$(cat ${INIT#file:}); fi从返回的 INIT 中解析project_exists、planning_exists、has_git、git_worktree_root、in_nested_subdir、project_path等字段进而自动决定 MODEplanning_exists: true→MODEmergeplanning_exists: false→MODEnew一个值得注意的工程细节这条init ingest-docs分发链路本身就是一次 bug 修复的产物。回归测试 tests/bug-2801-ingest-docs-handler.test.cjs 记录了 bug #2801——此前 workflow 调用了不存在的gsd-sdk query init.ingest-docs实际安装的二进制是gsd-tools且gsd-tools init的分发 switch 缺少ingest-docs分支。修复方式是在gsd-tools.cjs的 init switch 中新增case ingest-docs、从 init 模块导出cmdInitIngestDocs并把 workflow 改为规范形式的node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs init ingest-docs调用。测试用node:test断言了该命令退出码为 0、返回 JSON 包含project_exists/planning_exists/has_git/project_path字段并锁定 bash 代码块内不得再出现gsd-sdk字样的回归条件。Git 初始化逻辑还专门规避了 bug #3491 的教训绝不在已存在的外层 worktree 内创建嵌套.git。若has_git: true且处于嵌套子目录只提示规划文件将由外层仓库在git_worktree_root追踪不执行git init。运行时runtime探测复用new-project的模式执行上下文路径含/.codex/判定为 codex、/.gemini/为 gemini、/.opencode/或/.config/opencode/为 opencode否则默认 claude上下文不可用时回退到CODEX_HOME、GEMINI_CONFIG_DIR、OPENCODE_CONFIG_DIR环境变量。2.4 发现文档discover_docs文档清单从三个来源按顺序构建命中即止① manifest若提供——权威来源。预期 YAML 形态docs: - path: docs/adr/0001-db.md type: ADR precedence: 0 # optional, lower higher precedence - path: docs/prd/auth.md type: PRD每条目包含path必填相对仓库根、type必填取 ADR|PRD|SPEC|DOC、precedence可选整数。manifest 由用户显式给出因而被视作对启发式分类的权威覆盖。② 目录约定提供 manifest 时跳过。workflow 内建了四条find规则# ADRs find {SCAN_PATH} -type f \( -path */adr/* -o -path */adrs/* -o -name ADR-*.md -o -regex .*/[0-9]\{4\}-.*\.md \) 2/dev/null # PRDs find {SCAN_PATH} -type f \( -path */prd/* -o -path */prds/* -o -name PRD-*.md \) 2/dev/null # SPECs / RFCs find {SCAN_PATH} -type f \( -path */spec/* -o -path */specs/* -o -path */rfc/* -o -path */rfcs/* -o -name SPEC-*.md -o -name RFC-*.md \) 2/dev/null # Generic docs (fall-through candidates) find {SCAN_PATH} -type f -path */docs/* -name *.md 2/dev/null多规则命中的同一文件在并集去重后只计一份。③ 内容启发式在分类阶段执行对于未命中任何约定的文档由分类器检查 frontmattertype:字段与 H1 标题来兜底归类。50 份上限在发现完成后强制执行超出即输出引导并退出GSD Discovered {N} docs, which exceeds the v1 cap of 50. Use --manifest to narrow the set to ≤ 50 files, or run /gsd:ingest-docs again with a narrower path.发现结果会以NADR |NPRD |NSPEC |NDOC |Nunclassified的清单展示给用户并经由AskUserQuestionapprove-revise-abort 模式征得批准后才进入分类阶段——用户必须在分类器启动前看到完整的文档分类列表。Abort 干净退出Ingest cancelled.Revise 则引导用--manifest或收窄路径重新运行。三、并行分类gsd-doc-classifier 如何判定一份文档确认清单后workflow 创建暂存目录.planning/intel/classifications/然后为每份文档并行派生gsd-doc-classifier子代理agent 定义见 agents/gsd-doc-classifier.md。Claude Code 中通过在单条消息内发出多个 Task 工具调用来实现并发Copilot 等顺序型运行时则回退为串行分发。每个分类器只处理分配到的一个文件产出结构化 JSON 并返回一行确认绝不越界读取被分配文档的传递引用。分类器维护五种类型的固定分类学taxonomy类型判定依据产出物与优先级ADR一次架构/技术决策Status: Accepted\|Proposed\|Superseded编号文件名0001-、ADR-001-含 Context/Decision/Consequences 小节锁定决策locked decisions默认最高优先级PRD从用户/业务视角描述产品行为user stories、验收标准、成功指标、goals/non-goals、as a user…需求requirements中优先级SPEC实现契约——API、schema、SLO、协议、数据模型端点表、请求/响应 schema技术约束constraints次于 ADRDOC通用说明性文档指南、教程、设计缘由、onboarding、runbook仅上下文context最低优先级UNKNOWN无法置信地归入以上任何类型记录信号交由合成器或用户裁决判定路径分为三层置信度依次递减先做快速启发式路径/文件名约定再读文件解析 frontmatter 与正文信号最后给出high|medium|low置信度。歧义规则是两种类型信号强度相当难以取舍时选取优先级更高的信号ADR SPEC PRD DOC并把歧义记录进notes。只有状态为Accepted的 ADR 才置locked: true——Proposed/Draft一律不算锁定这一约束被测试显式锁定only marks Accepted ADRs as locked。分类 JSON 会写入{OUTPUT_DIR}/{slug}-{source_hash}.json其中source_hash是对完整源文件路径POSIX 风格取 SHA-256 的前 8 个十六进制字符目的是让并行的多个分类器在处理同名文件如各处散落的README.md时互不冲突{ source_path: {FILEPATH}, type: ADR|PRD|SPEC|DOC|UNKNOWN, confidence: high|medium|low, manifest_override: false, title: ..., summary: ..., scope: [..., ...], cross_refs: [path/to/other.md, ...], locked: true, precedence: null, notes: Only populated when confidence is low or ambiguity was resolved }字段规则同样严格manifest_override: true仅在提供MANIFEST_TYPE时成立precedence默认为null仅在 manifest 声明后才填入整数文件必须用 Write 工具创建禁止用 heredoc 或Bash(cat EOF)。若任一分类器报错编排器立即中止且不再触碰.planning/。四、合成与优先级裁决gsd-doc-synthesizer当所有分类完成后workflow 派生一次gsd-doc-synthesizer子代理见 agents/gsd-doc-synthesizer.md。编排器传给它的核心上下文包括CLASSIFICATIONS_DIR: .planning/intel/classifications/ INTEL_DIR: .planning/intel/ CONFLICTS_PATH: .planning/INGEST-CONFLICTS.md MODE: {MODE} EXISTING_CONTEXT: {existing .planning files, merge 模式才填} PRECEDENCE: {默认 [ADR,SPEC,PRD,DOC] 或 manifest 覆盖}合成器不面向用户提问也不直接写PROJECT.md/REQUIREMENTS.md/ROADMAP.md那是gsd-roadmapper的职责它的工作只有两件合成 冲突浮出。产出四份分类型 intel 文件加两份报告.planning/intel/decisions.md—— 来自 ADR每份 ADR 一个条目保留标题、来源路径、状态locked/proposed、决策陈述与 scope每条必须带source:溯源.planning/intel/requirements.md—— 来自 PRD一条需求一个 ID按REQ-{slug}派生一份 PRD 通常产出多条需求.planning/intel/constraints.md—— 来自 SPEC约束按api-contract | schema | nfr | protocol分类.planning/intel/context.md—— 来自 DOC按主题追加、注明来源.planning/intel/SYNTHESIS.md—— 人读汇总作为下游gsd-roadmapper的唯一入口.planning/INGEST-CONFLICTS.md—— 三桶冲突报告。ORCHESTRATOR RULECodex 运行时调用Agent()之后编排器必须立即停止本任务不得在子代理活跃期间自行阅读或合成已分类文档等待子代理返回结果后再继续——这是为了防止重复劳动、互相冲突的编辑与上下文浪费。4.1 优先级规则precedence_rules合成器是优先级强制层precedence-enforcing layer其反模式列表明确写着静默合并、丢失锁定决策、幼稚去重都会污染下游每一个规划拿不准时浮出冲突而不是替你挑一个。核心裁决规则如下默认排序ADR SPEC PRD DOC当内容相互矛盾时优先级更高的来源胜出。per-doc 覆盖某分类带非空整数precedence时仅对该文档覆盖默认值数值越小优先级越高。锁定决策locked: true的 ADR 产出的决策任何来源包括另一份 LOCKED ADR都不能自动覆盖。LOCKED vs LOCKED摄入集中两把互相矛盾的锁 → 硬 BLOCKERnew与merge两种模式都一样绝不自动裁决。LOCKED vs 非 LOCKEDLOCKED 胜出记入 auto-resolved 桶并附理由。merge 模式的 LOCKED in ingest vs 既有锁定决策硬 BLOCKER。同一需求、跨 PRD 验收标准分歧不得二选一视为一条需求携带多份竞争验收变体competing acceptance variants全部写进competing-variants桶交由用户裁决。4.2 交叉引用环检测cycle_detection合成器会用cross_refs构建有向图并跑三色标记DFS环检测。发现环时每个环记录为一条 unresolved-blocker且不继续对成环集合做合成循环合成只会产出垃圾环外文档仍可继续合成。引用图遍历深度上限为 50一旦超出就以 BLOCKER 条目中止引导用户用--manifest收窄输入。4.3 七轮冲突探测 pass 与三桶归类合成器在提取出的 intel 上跑七类冲突检查每类都会落进三桶之一#检查项落桶1两把 LOCKED ADR 在同一 scope 上决策矛盾unresolved-blockers2merge 模式摄入决策与既有 CONTEXT.md 中标记 locked 的decisions矛盾unresolved-blockers3两份 PRD 在同一 scope 上需求重叠但验收标准不同competing-variants保留全部变体4SPEC 断言与更高优先级 ADR 决策矛盾auto-resolvedADR 胜记录理由5低优先级与非锁定高优先级矛盾auto-resolved6UNKNOWN 低置信度文档unresolved-blockers用户须重新打标7环检测阻断见上unresolved-blockers桶与共享冲突引擎的严重级别映射是固定的unresolved-blockers→[BLOCKER]门禁工作流、competing-variants→[WARNING]路由前必须由用户挑选、auto-resolved→[INFO]仅记录透明。五、三级冲突报告与 BLOCKER 安全门禁/gsd:ingest-docs依赖的共享契约 get-shit-done/references/doc-conflict-engine.md 被/gsd:import等同样向.planning/摄入外部内容的工作流复用因此把严重级别语义、报告格式与安全门禁统一定义为三方约定ingest-docs只负责声明自己的检查清单、加载的上下文与操作名词。5.1 严重级别语义[BLOCKER] — 不安全不得继续。工作流必须在不写任何目标文件的前提下退出。用于锁定决策矛盾、前置条件缺失、不可能达成的目标。[WARNING] — 歧义或部分重叠。工作流必须浮出警告并取得用户显式批准后才能写入绝不自动放行。[INFO] — 纯信息无门禁、无需提示写入报告仅为透明。5.2 报告格式纯文本禁 markdown 表格## Conflict Detection Report ### BLOCKERS ({N}) [BLOCKER] {Short title} Found: {what the incoming content says} Expected: {what existing project context requires} → {Specific action to resolve} ### WARNINGS ({N}) [WARNING] {Short title} Found: {what was detected} Impact: {what could go wrong} → {Suggested action} ### INFO ({N}) [INFO] {Short title} Note: {relevant information}每条目必须有Found:外加Expected:/Impact:/Note:之一BLOCKER 与 WARNING 还必须有→修复行。报告直接原样呈现给用户因此禁用 markdown 表格|---|。合成器给出了示例形态——例如 BLOCKER 条目可能同时声明docs/adr/0004-db.md选择 Postgres 而docs/adr/0011-db.md同为 Accepted、scope 同为 primary datastore选择 DynamoDB修复方向是将其中一份标记为 Superseded或在--manifest中显式设 precedence。5.3 门禁判定conflict_gateworkflow 的冲突门禁读取.planning/INGEST-CONFLICTS.md解析### BLOCKERS ({N})、### WARNINGS ({N})、### INFO ({N})三行统计后分支处理BLOCKERS 0呈现报告后显示GSD BLOCKED: {N} blockers must be resolved before ingest can proceed.不写PROJECT.md、REQUIREMENTS.md、ROADMAP.md、STATE.md中的任何一个暂存 intel 文件保留待检。WARNINGS 0 且 BLOCKERS 0呈现报告用AskUserQuestionapprove/abort询问用户是否手动解决竞争变体后继续Abort 则以 Ingest cancelled. Staged intel preserved at.planning/intel/. 干净退出。两者皆 0静默进入路由或可选显示GSD No conflicts. Auto-resolved: {N}.这条门禁在 tests/ingest-docs.test.cjs 中被系统性锁定测试断言 workflow 必须包含 BLOCKER/WARNING/INFO 三标签、必须包含no destination files/without writing类阻止性措辞、报告位置固定为INGEST-CONFLICTS.md并验证 shared reference 自身禁止 markdown 表格 BLOCKER 存在时退出不写的契约。同一测试文件还确认import命令同样消费这份共享引用佐证了它是跨工作流的统一契约。六、路由new 与 merge 的两种收敛路径6.1 new 模式委托 gsd-roadmapper 落盘通过门禁后若为 new 模式workflow 先审计gsd-roadmapper期望的PROJECT.md字段需求凡能从.planning/intel/SYNTHESIS.md推导出的项目 scope、goals/non-goals、约束、锁定决策一律从 intel 合成无法推导的项目名、面向开发者的成功指标、目标运行时则通过AskUserQuestion逐项最小化提问不做盘问式收集。随后把最终产出委托给gsd-roadmapper子代理Agent({ subagent_type: gsd-roadmapper, prompt: Mode: new-project-from-ingest Intel: .planning/intel/SYNTHESIS.md (entry point) Per-type intel: .planning/intel/{decisions,requirements,constraints,context}.md User-supplied fields: {collected in previous step} Produce: - .planning/PROJECT.md - .planning/REQUIREMENTS.md - .planning/ROADMAP.md - .planning/STATE.md Treat ADR-locked decisions as locked in PROJECT.md decisions blocks. })这里又一次出现 Codex 运行时的 ORCHESTRATOR RULE子代理活跃期间编排器不得自行读更多 intel、写规划工件或创建ROADMAP.md。6.2 merge 模式增量追加、先预览后落盘merge 模式先加载既有.planning/ROADMAP.md、.planning/PROJECT.md、.planning/REQUIREMENTS.md与.planning/phases/下所有CONTEXT.md。由于合成器在 ingest-vs-existing 的锁定矛盾上已经硬阻断能走到这一步即代表没有剩余 BLOCKER。合并计划按三类增量执行新需求.planning/intel/requirements.md中与既有REQUIREMENTS.md条目不重叠的 → 追加进REQUIREMENTS.md新决策.planning/intel/decisions.md中与既有CONTEXT.mddecisions块不重叠的 → 写入新 phase 的CONTEXT.md或追加到下一里程碑的需求新 scope按new-milestone.md模式派生出 phase 增补并追加进.planning/ROADMAP.md。落盘前merge 的差异预览会展示给用户并经 approve-revise-abort 门禁把关——沿用 get-shit-done/references/gate-prompts.md 中定义的问询模式。6.3 finalize提交与完成播报最终提交摄入结果merge 模式替换为实际变更文件集合node $HOME/.claude/get-shit-done/bin/gsd-tools.cjs commit \ docs: ingest {N} docs from {SCAN_PATH} (#2387) --files \ .planning/PROJECT.md \ .planning/REQUIREMENTS.md \ .planning/ROADMAP.md \ .planning/STATE.md \ .planning/intel/ \ .planning/INGEST-CONFLICTS.md完成后显示 GSD ► INGEST DOCS COMPLETE 横幅并汇报运行的模式new/merge、摄入文档数与类型明细、锁定的决策/创建的需求/捕获的约束、冲突报告路径以及下一步指引——new 模式指向/gsd:plan-phase 1merge 模式指向首个新增 phase 对应的/gsd:plan-phase N。七、v1 边界与反模式清单ingest-docs 的 v1 实现主动划定了能力边界workflow 末尾的 Anti-Patterns 就是一份显式禁止清单值得使用者与维护者共同记住不得违反共享冲突引擎契约不使用 markdown 表格、不引入新严重级别标签、不可绕过 BLOCKER 门禁存在 BLOCKER 时绝不写PROJECT.md/REQUIREMENTS.md/ROADMAP.md/STATE.md不得跳过 50 份文档上限——更大的集合必须用--manifest收窄绝不自动裁决 LOCKED-vs-LOCKED 的 ADR 矛盾——两种模式下这都是 BLOCKER不得把多份竞争 PRD 验收变体拼成一个合并标准——全部保留给用户裁决不得绕过发现批准门禁——分类器派生前用户必须看到分类清单不得跳过SCAN_PATH/MANIFEST_PATH的路径校验不得在本 v1 实现--resolve interactive——该旗标预留须以未来版本提示拒绝。这些约束大多被 tests/ingest-docs.test.cjs 逐条以结构断言固化文件存在性、命令 frontmatter 含--mode/--manifest/--resolve、allowed-tools 含AskUserQuestion与Agent、必需引用已接线、50上限、BLOCKER 语义、gsd-doc-classifier/gsd-doc-synthesizer/gsd-roadmapper 的派生、v1 拒绝 interactive 等维护者可借此放心演进而无需担心破坏契约。八、实践建议何时用、怎么用综合命令语义与 workflow 细节/gsd:ingest-docs适合三类典型场景存量仓库启航 GSD代码与文档ADR/PRD/SPEC早已沉淀多年、但从未建立.planning/。此时无需手工搬运直接/gsd:ingest-docs以 new 模式初始化把历史决策自动映射为锁定决策与需求基线。持续吸收增量规划文档.planning/已存在、团队又习惯在docs/prd/、docs/specs/直接写新文档时用 merge 模式把新文档合成追加为新需求与新 phase保持规划体系与文档流同步。精确控制摄入集合当仓库文档量大、目录约定命中过多或存在歧义文档时编写--manifestYAML 显式声明path/type/precedence既能绕开 50 份上限收窄到 ≤50也能覆盖启发式分类结果。而interactive冲突解决、超出 50 份的更大规模摄入在 v1 中并未实现——设计上选择宁可阻断不可错写。这条取舍贯穿了/gsd:ingest-docs的每个环节从路径包含性校验、发现批准门禁、分类置信度建模、LOCKED 锁的强语义到最终的三桶冲突报告本质都是在为把自由文档安全地折叠进受控规划体系这一动作提供工程化护栏。对于希望深度定制或审计行为的人来说入口集中在三个文件命令契约 commands/gsd/ingest-docs.md、可执行步骤 get-shit-done/workflows/ingest-docs.md、以及共享语义 get-shit-done/references/doc-conflict-engine.md配套的分类器与合成器 Agent 定义位于 agents/gsd-doc-classifier.md 与 agents/gsd-doc-synthesizer.md行为契约则由 tests/ingest-docs.test.cjs 与 tests/bug-2801-ingest-docs-handler.test.cjs 守护。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考