企业官网建设流程全解析

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用

这篇指南面向仍在使用原始 Get Shit Done（v1）/gsd-2仓库的开发者，讲解如何通过内置的/gsd migrate命令把旧式.planning目录一次性迁移为 GSD-2 的.gsd格式。读完本文你将掌握迁移命令的完整用法、迁移管线的内部实现（解析 → 转换 → 预览 → 写出 → 入库 → 审计）、各类 v1 文档变体的兼容处理，以及迁移后如何用/gsd doctor、/gsd inspect与/gsd recover验证和修复输出结果。

为什么需要迁移

GSD-2 的.gsd格式相比 v1 的.planning目录发生了结构性变化：规划层级从"phase / plan / summary"演进为"milestone / slice / task"，并且引入了 DB 驱动的状态推导（deriveState()）。迁移工具的价值在于：

• 保留原有项目的层级结构与完成状态，避免历史进度丢失；
• 将研究文档、需求、决策记录整合进新目录结构；
• 把写入的 markdown 投影重新导入数据库，使 GSD-2 的自动模式（auto-mode）可以立即在迁移后的项目上继续工作。

在命令目录中，迁移命令的注册说明为"Migrate a v1 .planning directory to DB-backed .gsd with backup + audit"（见 命令目录），可见它的定位是一次带备份与审计的"一次性迁移"（one-shot migration），而非持续同步工具。

运行迁移

在项目目录内执行：

# 在项目目录内执行（迁移当前目录下的 .planning） /gsd migrate # 或者显式指定路径 /gsd migrate ~/projects/my-old-project

路径解析规则

迁移的路径解析实现在 safety.ts 中，规则如下：

• 支持~家目录展开；
• 参数为空时默认为当前目录"."；
• 如果传入路径的最后一段目录名恰好是.planning，则直接把它当作源目录，其父目录作为目标项目根目录；
• 否则将传入路径视为项目根目录，源目录为<路径>/.planning，目标.gsd也写在该根目录下。

也就是说，/gsd migrate ~/projects/my-old-project会把.gsd/写到~/projects/my-old-project/.gsd。

入口与整体管线

命令的编排入口是 command.ts，实际执行的是如下五步管线（模块导出见 index.ts）：

1. 校验（validate）：validatePlanningDirectory()检查.planning目录的最小结构；
2. 解析（parse）：parsePlanningDirectory()将旧目录解析为类型化的PlanningProject；
3. 转换（transform）：transformToGSD()纯函数式映射为 GSD-2 的GSDProject；
4. 预览（preview）：generatePreview()无 I/O 地统计将写出的层级与完成度；
5. 写出（write）：确认后执行executeMigrationWrite()，依次完成写出、归档、入库、投影校验与审计。

会迁移什么

迁移工具会解析旧版的PROJECT.md、ROADMAP.md、REQUIREMENTS.md、STATE.md、config.json、phase 目录、plan、summary、研究文档（research）以及quick/目录下的快速任务。

层级映射关系

v1 → GSD-2 的映射在 transformer.ts 中实现：

完成状态的保留

• roadmap 中[x]勾选的 phase 迁移后 slice 的done标记为完成；
• task 的完成状态由是否存在对应的 summary 文件决定（见 transformer.ts）；
• 已完成的 slice 会聚合所有 plan summary，生成带provides、key-files、key-decisions、patterns-established、duration等 frontmatter 的 Slice Summary；
• 全部 slice 都完成的里程碑，迁移器会额外写出M001-VALIDATION.md（verdict: pass, migrated: true）与M001-SUMMARY.md，以避免deriveState()对这些历史里程碑进入 validating 阶段（见 writer.ts）。

需求与决策的处理

需求迁移会做两项规范化（transformer.ts）：

• 状态规范化：active/validated/deferred原样保留；complete、completed、done、shipped等别名统一归为validated；其余未知状态归为active；
• ID 规范化：R1会规范为R001；ID 冲突时自动分配新的R00X，并把原 ID 以Legacy ID: <原ID>的形式保留在描述中，确保追溯。

决策记录（DECISIONS.md）会从各 phase summary 的key-decisionsfrontmatter 中提取，生成符合 GSD-2 格式的追加型决策登记表。

研究文件的整合

研究文件按SUMMARY.md → ARCHITECTURE.md → STACK.md → FEATURES.md → PITFALLS.md的优先顺序排序后合并为单个研究内容块（见 transformer.ts），分别挂到里程碑级（M001-RESEARCH.md）或 slice 级（S01-RESEARCH.md）。

支持的 v1 格式变体

迁移器被设计为容忍多种 v1 文档变体，解析器相关实现见 parser.ts 与 parsers.ts，对应的回归测试见 migrate-parser.test.ts：

• 按 milestone 分段、带<details>块的 roadmap：每个 milestone 段落解析为一个 GSD-2 里程碑；
• 粗体 phase 条目：roadmap 中以**粗体**呈现的阶段条目可以正常解析；
• 列表格式的 requirements：支持R001 - 标题这类列表条目；
• 十进制 phase 编号：目录名01.2-setup这类带小数点的编号会被解析为parseFloat（见 parser.ts）；
• 跨不同 milestones 重复的 phase 编号：phase 目录以完整目录名作为键（如29-auth-system），不会因编号重复而互相覆盖；转换时还会通过 slug 相似度在多个同名 phase 中做最佳匹配（见 transformer.ts）。

此外解析器还处理了这些边界情况：

• 孤儿 summary：没有对应 plan 的 summary 文件也会被收集，不丢失；
• .archive/目录：默认跳过隐藏目录与归档目录；
• 字母后缀 plan 编号：支持29-01a-PLAN.md这类带字母后缀的编号，并按数值 + 字母排序；
• 非标准文件：phase 目录中未匹配任何已知模式的其余文件收集为 extra files；
• quick/ 快速任务：001-fix-login目录及其中的 plan/summary 会被单独解析。

前提条件与校验

迁移效果在项目包含ROADMAP.md时最好，因为 milestone 结构来自它。若缺失，系统会根据phases/目录推断单个 milestone（标题为Migration）。

迁移前的预检（validator.ts）将问题分为两级：

• fatal（阻断）：.planning目录不存在，迁移无法继续；
• warning（警告，不阻断）：ROADMAP.md、PROJECT.md、REQUIREMENTS.md、STATE.md或phases/缺失。此时迁移仍可进行，但相应数据为空或需要推断。

/gsd migrate还会在写入前执行两项硬性检查（safety.ts）：

• 零 slice 阻断：若迁移结果不产生任何 slice（既无 roadmap 也无 phases 内容），命令会拒绝执行；
• 目标可用性检查：若目标项目已存在.gsd/且带有 worktree 状态、存在 auto-mode 崩溃锁（PID 存活）、或存在 paused 的 auto-mode 会话，迁移都会被阻断，需先清理这些状态。

预览与安全备份

写入前的预览

generatePreview()（preview.ts）在不做任何 I/O的前提下统计出迁移预览，包含：

• Decisions 数量、Milestones 数量；
• Slices 总数与已完成数（含完成百分比）；
• Tasks 总数与已完成数（含完成百分比）；
• Requirements 总数（区分 active / validated / deferred）。

确认界面由showNextAction呈现（见 command.ts），提供Write .gsd directory与Cancel两个动作，只有明确确认后才会写出任何文件；取消则提示"Migration cancelled — no files were written."

备份与失败恢复

写入前如果目标已存在.gsd/，会先备份到.gsd-backups/migrate-YYYYMMDD-HHMMSS/（若同名已存在则追加-2、-3后缀），然后删除旧的.gsd/重建（safety.ts）。

整个执行过程包裹在 try/catch 中，任何一步失败都会调用restoreMigrationTarget()把备份的.gsd/完整还原（command.ts），并提示"Migration failed and the previous .gsd state was restored."。

数据库导入与投影校验

写出 markdown 后，迁移器会在单事务中清空引擎层级、artifacts、decisions、requirements，再通过migrateFromMarkdown()把投影导入数据库，并用预览统计做逐项核对（milestones/slices/tasks/decisions/requirements 计数必须一致，否则抛出"migration DB import verification failed"，见 command.ts）。

随后verifyMigrationProjection()（audit.ts）会从数据库重新渲染 markdown，并对比三方计数：DB 层级、markdown 投影层级、预览预期，任何不一致都会报错。

审计与归档产物

迁移完成后会留下三组可追溯的产物（audit.ts）：

• .gsd/migration/MIGRATION.md：人类可读的迁移审计报告（时间、源路径、备份位置、导入计数、投影校验结果）；
• .gsd/migration/manifest.json：机器可读的完整迁移清单；
• .gsd/migration/legacy/：完整保留旧.planning源码副本（full-source-copy 策略），确保任何没有 GSD-2 对应字段的旧内容都不会丢失。

这三类文件还会作为 artifacts（MIGRATION_AUDIT、MIGRATION_MANIFEST、MIGRATION_LEGACY_MANIFEST）写入数据库（audit.ts）。

可选的 agent 驱动质量审查

迁移写出完成后，命令会再次弹出确认，提供Review migration选项（推荐）。选择后，系统会加载审查提示词模板（review-migration.md），将源路径、目标.gsd路径与迁移统计注入模板，然后触发 agent 进行一次只读审查，覆盖六个方面：

1. 结构校验：在.gsd上运行deriveState()，确认阶段（phase）、activeMilestone/activeSlice/activeTask 合理，进度计数与预览一致；
2. Roadmap 质量：slice 标题是否语义化、[x]/[ ]标记是否正确、vision 是否非空；
3. 内容抽查：抽取 2～3 个任务最多的 slice，核对 plan 与 summary 内容是否有效迁移；
4. 需求：ID 是否无重复、状态是否合理（已完成应为validated，进行中应为active）；
5. PROJECT.md：是否保留了旧项目描述而非占位文本；
6. DECISIONS.md：确认提取的决策（或确认无决策时为空）。

审查结果以PASS / PASS WITH NOTES / FAIL汇总并给出修复建议，但不会就地修改文件——修复必须走 DB 备份的迁移修复路径。

迁移后的验证与修复

迁移完成后，用以下命令检查输出结果：

/gsd doctor

/gsd doctor会检查.gsd/的数据库与 markdown 投影完整性，并标出任何结构性问题。从实现看（commands-handlers.ts），它还支持丰富的参数：

• --json：输出机器可读的报告；
• --dry-run：只报告不修复；
• fix/heal/audit三种模式：fix/heal会实际修复或把可修复问题交给 LLM 处理，audit输出更全面的审计报告；
• --build、--test：把构建/测试也纳入检查范围。

需要更底层的数据库诊断时使用/gsd inspect。

数据库缺失或损坏时的恢复

如果旧项目已经迁移出了 markdown 产物，但数据库缺失或损坏，可以：

# 先启动一次 GSD，让数据库被打开初始化 # 然后执行恢复 /gsd recover

/gsd recover（commands-maintenance.ts）会在单个事务内清空引擎层级（milestones、slices、tasks 表），保留 decisions、requirements、artifacts 与 memories，然后从磁盘上的 markdown 重新执行migrateHierarchyToDb()重建层级，再运行deriveState()验证结果，最后输出恢复的Milestones/Slices/Tasks计数与当前阶段。

这是一个显式的破坏性恢复/导入操作：正常运行流程不会静默地从 markdown 推导状态，因此文档明确提醒，只有数据库确实损坏时才应执行。

源码索引与测试参考

如果你想深入迁移机制，可以从以下文件入手：

• 编排入口：migrate/command.ts
• 类型契约：migrate/types.ts
• 解析器：migrate/parser.ts、migrate/parsers.ts
• 转换器：migrate/transformer.ts
• 写出器：migrate/writer.ts
• 安全与备份：migrate/safety.ts
• 审计与归档：migrate/audit.ts
• 预览统计：migrate/preview.ts
• 校验器：migrate/validator.ts
• 审查提示词：prompts/review-migration.md

相关测试覆盖了解析、转换、写出、安全审计、层级与端到端迁移：

• migrate-parser.test.ts：各类 v1 文档变体与边界情况；
• migrate-transformer.test.ts：层级映射正确性；
• migrate-writer.test.ts 与 migrate-writer-integration.test.ts：写出文件结构；
• migrate-safety-audit.test.ts：备份与审计逻辑；
• migrate-command.test.ts：命令级集成；
• migration.e2e.test.ts：端到端迁移验证。

小结

/gsd migrate是 GSD-2 提供的一条完整、安全、可审计的升级通道：它先预览再写入、写入前自动备份、失败自动还原，写出后还会把 markdown 投影重新导入数据库并逐项核对计数，最后留下MIGRATION.md、manifest.json和完整旧源码归档。配合/gsd doctor做结构体检、/gsd inspect做数据库诊断、/gsd recover做损坏恢复，旧 v1 项目可以无缝过渡到 DB 驱动的.gsd工作流，让 GSD-2 的自动模式在历史项目上继续长周期自治运行。

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用