【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载本文介绍 gsd-core 的Existing Code Onboarding Module现有代码接入模块它通过一个纯函数式、只读的投影projection模块确定性检测 brownfield既有代码仓库的文件系统状态并据此选择下一步该运行的接入原语/gsd:map-codebase、/gsd:ingest-docs、/gsd:new-project。读完本文你将理解/gsd:onboard的路由判定逻辑、状态检测规则、安全不变量以及它如何被 Init Command Module 和工作流渲染层消费。该模块的架构决策记录在 docs/adr/1990-existing-code-onboarding.mdADR-1990Issue #1990实现 PR #1994核心实现位于 src/onboard-projection.cts。背景为什么需要一个接入编排入口GSD 早已具备若干处理既有代码库的独立原语/gsd:map-codebase—— 并行代码库分析产出.planning/codebase/地图/gsd:ingest-docs—— 分类并整合仓库中已有的 ADR/PRD/SPEC/RFC 文档/gsd:new-project—— 规划初始化建立PROJECT.md/REQUIREMENTS.md/ROADMAP.md/STATE.md。问题在于缺少一个统一的引导入口告诉用户在某个 brownfield 仓库中哪一个原语应该先执行。如果只靠自然语言描述执行顺序是模糊且不安全的——用户可能在代码库地图尚未生成前就初始化规划、跳过相关设计文档、或者覆盖/重复.planning/上下文而不是复用它。ADR-1990 的核心判断是这个顺序问题不是口味偏好而是一个依赖图——地图应在规划之前存在已有设计文档应在全新/gsd:new-project之前被 ingest任何操作都不应破坏进行中的.planning/。而从文件系统状态决定下一步安全动作的依赖图本质上是一个投影projection——它无法被工作流中的自然语言指令可靠地求值或测试。三层架构投影、处理器与渲染该模块遵循 GSD 已有的两个投影模块先例——Planning Path Projection ModuleADR-0006负责.planning路径解析与Shell Command Projection ModuleADR-0009负责运行时感知的命令投影。如果/gsd:onboard以自由形式的工作流正文去内联扫描目录树就会把不可测试、不确定的文件系统逻辑塞进 markdown——这正是那些投影模块要防止的反模式。因此模块被切分为三个明确层次投影投影模块本身src/onboard-projection.cts 编译为gsd-core/bin/lib/onboard-projection.cjs。它是纯函数、无副作用的投影只读仓库状态计算next_action从不写入任何文件。处理器Init Command Modulesrc/init.cts 是init.*查询处理家族的所有者其 cmdInitOnboard 处理器L1865-L1881 调用buildOnboardProjection并合并getInitGitState的 Git 状态字段最终以与兄弟处理器相同的{ data: flat JSON }契约输出。命令路由在 src/init-command-router.cts 的 onboard: 分支L182-L185 中接线解析--fast/--text布尔标志后调用cmdInitOnboard。渲染工作流层gsd-core/workflows/onboard.md 只负责菜单/门禁呈现commands/gsd/onboard.md 及其技能镜像 skills/gsd-onboard/SKILL.md 负责委托。模块本身只拥有它们消费的状态 → 路由决策。在 CLI 层面你可以直接查看投影结果# 默认模式完整地图门槛 gsd_run --cwd $PWD init onboard --raw # 快速模式接受 fast map 用于轻量接入 gsd_run --cwd $PWD init onboard --fast --raw # 文本模式无交互选择器的运行时 gsd_run --cwd $PWD init onboard --text --raw--raw输出为扁平 JSON 结构如next_action.kind、is_brownfield、map_readiness、handoff_commands等字段供工作流解析渲染。状态检测投影的输入信号投影从仓库文件系统读取五类信号。下面的信号表来自 ADR-1990括号内为源码中的实际实现细节。信号规则 / 不变量Brownfield 代码存在深度受限的递归代码文件扫描hasCodeFilesInternal或识别到包清单hasPackageFileInternal生成 / vendor 目录排除扫描跳过CODE_SCAN_SKIP_DIRS避免 vendored 树产生错误的 brownfield 判定代码库地图完整性.planning/codebase/是否持有规范地图产物既有设计文档是否存在 ADR/PRD/SPEC/RFC 风格的候选根级、嵌套目录、以及路径段匹配部分规划状态PROJECT.md/REQUIREMENTS.md/ROADMAP.md/STATE.md是否只存在一部分深度受限的代码扫描与包清单hasCodeFilesInternalsrc/onboard-projection.cts L116-L133以深度上限 3递归扫描匹配 31 种源码扩展名.ts.tsx.js.jsx.mjs.cjs.py.go.rs.swift.java.kt.kts.c.cpp.cc.h.hpp.cs.rb.php.dart.m.mm.scala.groovy.lua.r.R.zig.ex.exs.clj。深度上限保证扫描成本可控不会遍历整个仓库。hasPackageFileInternalL135-L137检查 18 种常见包清单文件package.json、requirements.txt、pyproject.toml、Cargo.toml、go.mod、Package.swift、build.gradle、build.gradle.kts、pom.xml、Gemfile、composer.json、pubspec.yaml、CMakeLists.txt、Makefile、build.zig、mix.exs、project.clj。即使没有任何源码文件只要存在包清单也被视为 brownfield——这是测试中明确覆盖的语义见下文测试与回归。最终isBrownfield hasCode || hasPackageFileL345同时投影输出has_existing_code与has_package_file两个细分字段。生成 / vendor 目录排除ADR 中记录的CODE_SCAN_SKIP_DIRS为node_modules、dist、build、.next、.nuxt、.svelte-kit、coverage、vendor、.venv、venv源码中的实际集合L19-L22更完整还包含.git、.planning、.claude、.codex、__pycache__、target。这些目录在代码扫描与文档候选扫描中都会被跳过确保一个只有node_modules/dist的空仓库不会被误判为 brownfield——对应测试ignores generated and vendor directories when detecting existing code。代码库地图完整性完整地图与快速地图各有一套规范文件清单L31-L38模式必需文件完整地图REQUIRED_CODEBASE_MAP_FILES7 个STACK.md、ARCHITECTURE.md、STRUCTURE.md、CONVENTIONS.md、TESTING.md、INTEGRATIONS.md、CONCERNS.md快速地图FAST_CODEBASE_MAP_FILES4 个STACK.md、INTEGRATIONS.md、ARCHITECTURE.md、STRUCTURE.mdlistCodebaseMapFilesL202-L212只读取项目作用域下的.planning/codebase/注释标注了 Issue #3964扁平根读取会让GSD_PROJECT下的has_codebase_map/needs_codebase_map答错项目。由此得到三态map_readiness: none | fast | completeL214-L218。投影还会输出missing_codebase_map_files、missing_fast_codebase_map_files、codebase_map_summary_status、codebase_map_final_status等诊断字段。设计文档候选listPlanningDocCandidatesL139-L200在深度 ≤ 3 内识别设计文档命中规则为满足其一即算候选且仅限.md文件文件名匹配/(^|[-_ ])(ADR|PRD|SPEC|RFC)([-_ ]|\.)/i如ADR-001.md、0001-PRD.md文件名匹配/^\d{4}[-_].\.md$/i如0001-decision.md相对路径的某个路径段属于PLANNING_DOC_SEGMENTSadr/adrs/prd/prds/spec/specs/rfc/rfcs如docs/adr/0001-runtime.md文件名恰为REQUIREMENTS.md。扫描覆盖根级文件以及docs、adr、adrs、prd、prds、spec、specs、rfc、rfcs根目录L140同样跳过CODE_SCAN_SKIP_DIRS。规划状态投影逐一探测四个规划文档的存在性L352-L361PROJECT.md同时检查根级与项目作用域两个候选路径、REQUIREMENTS.md、ROADMAP.md、STATE.md并生成planningMissing缺失清单L232-L244。hasPlanningArtifacts为四者任一存在。同时探测.planning/config.json、.planning/onboarding/SUMMARY.md等辅助状态。路由选择依赖序优先于便利序ADR-1990 给出的路由选择输出按依赖序排列Brownfield 代码且.planning/codebase/地图不完整 → 交给/gsd:map-codebasefast 模式为/gsd:map-codebase --fast存在设计文档候选且尚无项目 → 在/gsd:new-project之前提供/gsd:ingest-docs否则 →/gsd:new-project。并且 ADR 强调partial-planning 与 fast-map-completeness 必须在 docs-ingest 分支之前求值这样半地图或半初始化的仓库永远不会被路由越过它尚欠的步骤。源码中nextActionsrc/onboard-projection.cts L246-L319实现了更细粒度的 8 分支判定顺序即优先级优先级条件next_action.kind含义1isBrownfield needsOnboardCodebaseMapmap-codebase检测到既有代码但缺必需地图fast 模式用map_codebase_fast2hasPlanningArtifacts missingPlanningFiles.length 0partial-planning规划存在但不完整列出missing3fastMode mapReadiness fast !projectExistscomplete-map-before-new-projectfast map 只够轻量接入项目初始化前仍需完整地图4hasDocsCandidates !projectExistsingest-docs项目建立前应先 ingest 已有设计文档5!isBrownfield !projectExists !hasDocsCandidatesnew-project未检测到代码或规划文档greenfield6!projectExistsnew-project代码库上下文已就绪可初始化项目7!onboardingSummaryExistswrite-summary缺少接入摘要8兜底ready接入摘要已存在fast 模式通过needsOnboardCodebaseMap options.fast ? needsFastCodebaseMap : needsCodebaseMapL351切换门槛fast 模式只要求 4 个快速地图文件齐全而非 7 个完整地图文件。但注意第 3 分支在项目建立前fast map 仍不足以放行new-project——只有当项目设置已完整时分支 7fast map 才足够推进到摘要阶段。这正是回归测试#1990中fast map gate misroute修正后的行为。每个分支都携带人类可读的reason例如Existing code was detected, but the required .planning/codebase/ map is missing.工作流直接将其呈现给用户。安全不变量为什么这是一个模块而非辅助函数ADR-1990 明确列出四条安全不变量全部由投影的只读设计保证幂等 / 无静默覆盖。接入过程绝不修改既有被跟踪的.planning/产物重复运行保持字节不变。测试reports complete codebase map and onboarding summary in existing planning在运行前后对PROJECT.md、ROADMAP.md、STATE.md、SUMMARY.md做字节级比对断言tests/onboard-command.test.cjs L114-L153。SUMMARY.md是尾随产物。.planning/onboarding/SUMMARY.md只在项目设置已存在且文件缺失时才写入工作流明确不覆盖已有摘要。完成是合取而非析取。只有PROJECT.md、REQUIREMENTS.md、ROADMAP.md、STATE.md全部存在才报告完成——不存在单文件短路。文本模式等价。--text渲染与交互式选择器完全相同的门禁决策为编号纯文本提示使没有交互选择器的运行时OpenAI Codex、Antigravity 等获得一致路由。运行时感知的 handoff 命令投影输出的handoff_commandsbuildHandoffCommandsL321-L331不是硬编码的/gsd:xxx字符串而是通过 src/runtime-slash.cts 的 formatGsdSlashL31-L74 按运行时解析格式resolveRuntime读取运行时身份formatGsdSlash依据能力注册表中的commandStyle决定输出——Claude 风格输出/gsd-cmdCodex 等 shell-var 运行时输出$gsd-cmd命令 token 小写。这样投影出的下一步命令对当前安装的运行时的斜杠语法总是正确的。{ handoff_commands: { map_codebase: /gsd-map-codebase, map_codebase_fast: /gsd-map-codebase --fast, ingest_docs: /gsd-ingest-docs, new_project: /gsd-new-project, manager: /gsd-manager, onboard: /gsd-onboard } }在GSD_RUNTIMEcodex环境下同样的命令会渲染为$gsd-map-codebase等对应测试formats onboard handoff commands for the resolved runtime。另外onboarding_summary_path使用锚定在 cwd/project_root 的绝对路径源码注释标注 Issue #2376避免派生子代理的 cwd 与编排者不一致导致路径错位。工作流渲染菜单、门禁与文本模式gsd-core/workflows/onboard.md 是围绕投影的薄渲染器它通过gsd_run自举解析器来自共享的references/gsd-run-resolver.md而非内联运行init onboard --raw/init onboard --fast --raw解析 JSON 字段后按next_action.kind分派map-codebase询问用户先映射代码库推荐或跳过映射。跳过路径仍有守卫若规划存在但不完整改走 partial-planning 守卫若存在文档候选且无项目改走 docs ingest否则提示跳过会削弱new-project的上下文。ingest-docs询问是否先 ingest 检测到的 N 个文档候选跳过则警告会遗漏既有文档上下文。complete-map-before-new-project/new-project/partial-planning直接打印下一步命令并要求在ONBOARDING_ROOT{git_worktree_root || _GSD_RUNTIME_ROOT}下运行后重跑/gsd:onboard。write-summary创建.planning/onboarding/SUMMARY.md不覆盖模板记录项目状态、代码库上下文、文档上下文与推荐下一步若commit_docs为真仅提交摘要路径query commit docs: create onboarding summary --files .planning/onboarding/SUMMARY.md。ready打印最终状态并结束。工作流同时处理response_language用户可见输出翻译为指定语言技术术语与路径保持英文、嵌套 Git worktree 警告has_git in_nested_subdir时提示产物归属外层 worktree 且不执行git init以及 Copilot 的vscode_askquestions等价适配。接入流程绝不执行实现阶段或 ship 工作——这也是命令契约测试断言!content.includes(execute-phase)与!content.includes(gsd:ship)的原因。模块边界什么留在模块之外ADR-1990 明确划定了边界防止模块膨胀原语本身/gsd:map-codebase、/gsd:ingest-docs、/gsd:new-project保持各自行为不变模块只选择并排序它们投影路由而不重实现目的地。写入规划产物所有.planning/写入仍归目的地命令与 Installer/规划模块所有投影是只读的。工作流的渲染菜单/门禁呈现归 gsd-core/workflows/onboard.md命令委托归 commands/gsd/onboard.md 及其技能镜像 skills/gsd-onboard/SKILL.md模块只拥有它们消费的状态→路由决策。测试与回归投影的负载行为全部由 tests/onboard-command.test.cjs约 25 KB覆盖主要用例包括brownfield 代码 / 文档 / 缺失规划状态的整体报告顶层ADR/PRD/RFC目录与根级设计文档的候选检测--text标志透传为text_mode: true完整地图与既有摘要下的幂等性无突变断言fast 地图就绪但缺完整地图时路由到complete-map-before-new-projectnext_action.command为/gsd-map-codebasepartial-planning 在 docs-ingest 与 complete-map 门禁之前求值——即回归测试#1990fast mode routes incomplete planning to partial-planning before the complete-map gate对全部状态code / docs / greenfield / partial planning / summary / ready的next_action精确断言vendor 目录排除与包清单 brownfield 判定运行时格式化GSD_RUNTIMEcodex→$gsd-*点号查询query init.onboard与直接init onboard的输出一致性命令契约测试工作流必须引用共享 resolver、渲染全部 7 种next_action.kind、跳过路径必须显式 handoff 且保持 partial-planning 先于 docs-ingest 的守卫顺序。后果与维护耦合ADR-1990 记录的后果包括Brownfield 接入从散文中的操作顺序民俗变为单一、可测试、确定性路由的入口。Init Command Module 新增一个重量级处理器initOnboard沿用与兄弟处理器相同的{ data: flat JSON }契约没有新的分发形态。新增的维护耦合已被显式记录模块的完整性检查必须跟随规范.planning/codebase/产物清单及路由目标的身份变化若三个目的地命令更改其入口契约投影必须跟进。ADR 将这一耦合记录为集中化路由决策的已知成本——与之相对的替代方案在每个原语内复制该决策更糟。无新增运行时依赖不改变既有命令语义纯增量。开放问题ADR-1990 留有两个开放问题供后续演进观察代码库地图完整性是否应改为从地图模块持有的单一共享谓词获取而非在本模块中重新编码以避免两处漂移/gsd:onboard工作流从共享的references/gsd-run-resolver.md片段获取gsd_run自举而非内联如果该委托模式被其他工作流采用可能值得单独成文一份简短 ADR——此处记录该先例使其可见而非悄然确立。快速上手对刚克隆的既有仓库接入流程是# 1. 从仓库根运行 onboard查看投影出的下一步 gsd_run --cwd $PWD init onboard --raw # 2. 按 next_action 指示执行 # - map-codebase → gsd_run --cwd $PWD init map-codebase --raw或带 --fast # - ingest-docs → gsd_run --cwd $PWD init ingest-docs --raw # - new-project → gsd_run --cwd $PWD init new-project --raw # - partial-planning → 补齐缺失的 PROJECT.md / REQUIREMENTS.md / ROADMAP.md / STATE.md # - write-summary/ready → 接入完成接下来运行 /gsd-manager # 3. 每个目的地命令执行完毕后重新运行 onboard直到 next_action.kind 变为 ready接入的终点是ready四份规划文档齐全、代码库地图完整fast 模式除外见上文第 3 分支约束、接入摘要已写入.planning/onboarding/SUMMARY.md系统推荐的下一步是/gsd-manager。整个过程不执行任何实现阶段不 ship 任何工作——/gsd:onboard只负责把你安全地领到正确的起点。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐GSD Core 既有代码库上手指南/gsd:onboard 一站式接入流程与底层路由原理GSD Core 既有代码库上手指南 /gsd:onboard 一站式接入流程与底层路由原理 本文聚焦 Git Ship DoneGSDCore 为“已有GSD Core 现有代码库接入指南/gsd-onboard 的 Brownfield 检测、安全交接与规划产物生成机制GSD Core 现有代码库接入指南/gsd onboard 的 Brownfield 检测、安全交接与规划产物生成机制 /gsd onboard 是 GSD如何把存量代码库接入GSD Core代码库映射与onboard技巧全清单如何把存量代码库接入GSD Core代码库映射与onboard技巧全清单 GSD Core Git. Ship. Done是一个面向 AI 编码代理的上下移动开发数据库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考