人工智能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点击查看免费下载这篇指南面向仍在使用原始 Get Shit Donev1/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校验validatevalidatePlanningDirectory()检查.planning目录的最小结构解析parseparsePlanningDirectory()将旧目录解析为类型化的PlanningProject转换transformtransformToGSD()纯函数式映射为 GSD-2 的GSDProject预览previewgeneratePreview()无 I/O 地统计将写出的层级与完成度写出write确认后执行executeMigrationWrite()依次完成写出、归档、入库、投影校验与审计。会迁移什么迁移工具会解析旧版的PROJECT.md、ROADMAP.md、REQUIREMENTS.md、STATE.md、config.json、phase 目录、plan、summary、研究文档research以及quick/目录下的快速任务。层级映射关系v1 → GSD-2 的映射在 transformer.ts 中实现v1 概念GSD-2 概念说明Milestone里程碑MilestoneM001、M002…来自 roadmap 的分段标题或从phases/推断Phase阶段目录SliceS01、S02…目录名29-auth-system会转为标题化名称Plan计划文件TaskT01、T02…来自 phase 目录下的NN-NN-PLAN.mdSummary总结文件Task/Slice 的 Summary带 YAML frontmatter 的总结文件Research研究文件Milestone/Slice 级研究文件多个研究文件按固定顺序合并RequirementsRequirements状态与 ID 规范化后写入REQUIREMENTS.md完成状态的保留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.mdverdict: pass, migrated: true与M001-SUMMARY.md以避免deriveState()对这些历史里程碑进入 validating 阶段见 writer.ts。需求与决策的处理需求迁移会做两项规范化transformer.ts状态规范化active/validated/deferred原样保留complete、completed、done、shipped等别名统一归为validated其余未知状态归为activeID 规范化R1会规范为R001ID 冲突时自动分配新的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 filesquick/ 快速任务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 对应字段的旧内容都不会丢失。这三类文件还会作为 artifactsMIGRATION_AUDIT、MIGRATION_MANIFEST、MIGRATION_LEGACY_MANIFEST写入数据库audit.ts。可选的 agent 驱动质量审查迁移写出完成后命令会再次弹出确认提供Review migration选项推荐。选择后系统会加载审查提示词模板review-migration.md将源路径、目标.gsd路径与迁移统计注入模板然后触发 agent 进行一次只读审查覆盖六个方面结构校验在.gsd上运行deriveState()确认阶段phase、activeMilestone/activeSlice/activeTask 合理进度计数与预览一致Roadmap 质量slice 标题是否语义化、[x]/[ ]标记是否正确、vision 是否非空内容抽查抽取 23 个任务最多的 slice核对 plan 与 summary 内容是否有效迁移需求ID 是否无重复、状态是否合理已完成应为validated进行中应为activePROJECT.md是否保留了旧项目描述而非占位文本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 recovercommands-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 编排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点击查看免费下载相关推荐源码解读Ramda如何用一个_curryN实现自动柯里化占位符算法逐步剖析源码解读Ramda如何用一个_curryN实现自动柯里化占位符算法逐步剖析 Ramda 是 JavaScript 生态中最流行的函数式编程库它的招牌能力是开发工具Multipass macOS 驱动迁移指南从 Hyperkit 平滑迁移到 QEMU 并保留实例Multipass macOS 驱动迁移指南从 Hyperkit 平滑迁移到 QEMU 并保留实例 本文基于 Multipass 官方 how to 指南 M虚拟化开发工具云原生Colly版本升级指南从v1到v2的平滑迁移Colly版本升级指南从v1到v2的平滑迁移 Colly是一个优雅的Golang网页爬虫框架为开发者提供强大的数据抓取能力。随着Colly从v1版本升级到v上一篇ESP32-P4 MIPI-DSI LCD 驱动详解从 D-PHY 协议到 esp-lcd 实战移植下一篇告别龟速下载用baidu-wangpan-parse实现百度网盘全速下载创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考