gsd-core 安装器迁移模块：为每个受支持运行时接入基线扫描、原子回滚与锁保护的升级管线-平芜编程栈

【免费下载链接】gsd-core

Git. Ship. Done - Core

项目地址：https://gitcode.com/gh_mirrors/ge/gsd-core

本篇技术指南以 gsd-core 仓库中的安装器迁移（Installer Migration）模块为核心，讲解 GSD 如何把迁移机制接入所有受支持运行时的正常安装流程：首次安装基线扫描、折叠式操作报告、被阻止操作的防护、事务式回滚、安装状态持久化，以及在包物化之前用锁保护的执行。读完本文，你将掌握迁移记录（Migration Record）的编写契约、全部动作类型与作者护栏、执行引擎的调用链与锁/日志/回滚机制，并能在实际为 GSD 新增或维护迁移时直接上手。

背景：为什么安装器需要迁移层

GSD 安装器在模块落地之前已经处理多种升级行为：替换 GSD 托管的命令、技能、Agent、Hook 与引擎文件；替换前备份本地修改过的托管文件；保留已知的用户自有产物；清理旧 Hook 文件与注册；重写运行时特定的配置格式；回滚部分失败的 Codex 安装。这些行为分散在各安装分支中，可以处理孤立修复，但让功能退役变得危险：一次发布改动可能从包中移除某个文件，却在已安装目录留下过期副本；或者误删恰好位于 GSD 托管目录下的用户自建文件。

迁移层存在的意义正是把升级行为变得显式、可评审、可重复。它在每个受支持运行时的正常安装/更新入口接入统一的迁移运行器，在包物化之前完成规划、报告、安全应用与状态持久化。设计目标（见 docs/installer-migrations.md）包括：默认保护用户数据、退役时移除过期 GSD 托管文件、破坏性动作先展示再执行、记录已应用迁移避免重复执行、为每个运行时提供相同的安全模型、把迁移编写成本压到足够低以便贡献者使用。

模块有明确的非目标：它不是通用包管理器，不是数据库迁移系统，不会自动推断所有历史安装布局，不会删除任意用户文件，也不会一步替换现有安装变换。

核心概念与术语

迁移层建立在四类文件所有权判定之上：

托管文件（Managed file）：由 GSD 安装并记录在安装清单（gsd-file-manifest.json）中的文件。未改动时可自动替换；本地改动过则必须备份或合并。
用户自有文件（User-owned file）：由用户工作流或用户直接创建维护的文件。绝不能因为它位于 GSD 目录下就被删除。
未知文件（Unknown file）：位于安装根目录下、不在清单中、也无法归类为用户自有的文件。除非迁移用带证据的检测器证明它是过期 GSD 产物，否则一律保留。
迁移（Migration）：版本化的变更集，可检查当前安装、产出计划，并在安全检查通过后应用该计划。
计划（Plan）：提议的文件系统与配置动作列表，只描述将要发生什么及原因，不改写磁盘，因此可安全展示给用户。
日志（Journal）：每次运行的应用动作与回滚数据记录，用于失败安装尽量恢复运行前状态。

状态文件：清单与安装状态

迁移层复用既有文件清单，并新增一个安装状态记录。

文件清单（gsd-file-manifest.json）

清单保留为所有权基线，记录安装的 GSD 版本、安装模式、写入它的运行时与作用域，以及发行版自有文件的哈希：

{ "manifestVersion": 2, "version": "1.9.2", "timestamp": "2026-08-10T00:00:00.000Z", "mode": "full", "runtime": "claude", "scope": "local", "files": { "gsd-core/VERSION": "sha256-hex…", "commands/gsd-plan-phase.md": "sha256-hex…" } }

字段	含义
`manifestVersion`	本文档的 schema 版本。缺失 ⇒ 版本 1，即 #2872 之前写入的清单。
`version`	写入清单的 GSD包版本——不是 schema 版本，两者刻意分离。
`timestamp`	ISO-8601 写入时间。
`mode`	`full`或`minimal`。
`runtime`	本次安装目标运行时（`claude`、`codex`……），schema 2 新增。
`scope`	`global`或`local`，schema 2 新增。
`files`	相对路径 → SHA-256，仅发行版自有文件。

runtime与scope的引入（#2872）让读取方可以直接回答"哪些表面已安装、位于哪个作用域、属于哪个运行时"，而无需从文件所在目录反推。schema 2 之前，全局与本地安装会把两份清单写入两个永不合并、永不交叉读取的目录。

schema 1 清单被无错读取，且绝不要求重装。readInstallManifest会把manifestVersion: 1连同runtime: null、scope: null一并上报，所有消费方把字段缺失视为"未声明"而非"未安装"。新版本 GSD 写入的manifestVersion原样上报而不拒绝——一台机器上并存两个 GSD 版本是受支持状态——因此消费方应分支于>= 2，而非=== 2。该实现位于 readInstallManifest，其中normalizeManifestVersion只接受有限整数>= 1作为版本声明，其余一律读作1。

清单的不变式是严格的：发行版自有文件必须被清单追踪；用户自有文件被保留且不出现在清单哈希中；一个路径不能同时属于两者。

安装状态（gsd-install-state.json）

安装器在清单旁写入gsd-install-state.json，只承载迁移记账——运行时的版本、作用域、模式仍在清单中：

{ "schemaVersion": 1, "appliedMigrations": [ { "id": "2026-05-11-codex-hooks-layout", "packageVersion": "1.50.0", "checksum": "sha256:...", "appliedAt": "2026-05-11T00:00:00.000Z" } ] }

实现中InstallState仅包含{ schemaVersion, appliedMigrations }（camelCase），见 src/installer-migrations.cts。状态文件使用严格原子写入（atomicWriteInstallState）：先写临时文件再retryRenameSync改名落位，绝不留下半写状态。

校验和由迁移定义计算（migrationChecksum，缺省为sha256:前缀的序列化摘要）。已应用的迁移永不重跑，因此校验和漂移在运行时被容忍：收集进plan.checksumDrift并在下次写入状态时调和（reconcileDriftedChecksums），而不是中止用户升级（issue #670）。"已发布迁移体不可变"这一规则由 CI 中提交的校验和基线测试（tests/installer-migrations.test.cjs）强制执行；若要改变已发布迁移的行为，应新增 fix-forward 迁移 id，而不是编辑已发布体。

迁移记录：元数据契约与作者护栏

每个迁移导出一个普通记录加纯规划逻辑。必填字段（validateInstallerMigrationRecord 强制）：

module.exports = { id: '2026-05-11-runtime-layout-example', title: 'Move legacy commands into runtime skills', description: 'Move legacy runtime command files into the generated skill layout.', introducedIn: '1.50.0', runtimes: ['claude', 'codex', 'antigravity'], scopes: ['global', 'local'], destructive: true, plan(ctx) { return []; } };

安装器迁移作者护栏模块拒绝缺失id、title、description、introducedIn、scopes、destructive或plan的记录。runtimes仅对刻意全运行时共享的迁移保持可选，但scopes必须显式，防止作者无意中扩大本地/全局行为。

plan(ctx)接收安装上下文（运行时、作用域、目标目录、旧清单、安装状态、包清单与文件系统助手），返回动作数组，且不得改写磁盘。规划阶段可用的助手谓词包括：isManaged(relPath)、isUserOwned(relPath)、hashMatchesManifest(relPath)、exists(relPath)、readJson(relPath)、readToml(relPath)。

动作类型：执行器拥有的原语

迁移只产出少量动作类型，执行器统一拥有变更、备份、回滚与上报（支持的动作集合见 applyInstallerMigrationPlan 的白名单校验）。

remove-managed

仅当路径已知为 GSD 托管且与旧清单一致，或迁移提供了针对旧 GSD 属形状的专用检测器时才移除。作者护栏：每个remove-managed动作必须带ownershipEvidence，说明证明 GSD 所有权的清单条目、生成标记或专用检测器。用于退役 Hook、旧生成 Agent、废弃命令文件与过期运行时生成产物。

backup-and-remove

因文件与旧清单不一致而在删除前先备份托管路径，用户会得到清晰报告并可检查备份。用于退役用户可能打过补丁的托管文件。规划阶段会自动升级：当remove-managed遇到managed-modified分类时升级为backup-and-remove，遇到unknown分类时升级为preserve-user（planInstallerMigrations）。

remove-empty-dir

仅通过fs.rmdirSync移除目录节点——绝不用递归删除（fs.rmSync、{ recursive: true }、{ force: true }）。执行器在调用前立即重查空状态：仍含任何条目的目录按成功非错误结果skipped-not-empty原样保留，而不是被清扫。这是刻意弱于递归删除原语的实现（该框架刻意不提供递归删除，见 docs/adr/0008-installer-migration-module.md 的 2026-08-07 修订）。额外护栏：目标不得是符号链接（从不跟随、从不穿透删除）；目标 realpath 必须严格解析在配置目录 realpath 之内且不得等于配置目录本身；任何意外失败（EACCES、EBUSY、检查与调用之间被并发移除）都降级为left-in-place而非抛错。作者护栏同remove-managed：必须带ownershipEvidence。

该动作解决宿主运行时保留目录名字的场合（如 pi 的hooks/，#3023）：宿主检查的是目录存在本身而非内容，留一个空壳目录会让告警永远触发。实现见 evaluateRemoveEmptyDir。

move-managed

把托管路径移动到新的托管路径。若源文件被本地修改过，动作升级为backup-and-move或冲突。用于命令目录迁入技能等布局迁移。

rewrite-config / rewrite-json

通过解析器或既有结构助手重写结构化配置文件；字符串替换仅限有换行与排序变体测试的窄范围标记块。初始执行器支持rewrite-json：迁移用readJson(relPath)读取 JSON，在动作中返回下一个解析值，可设deleteIfEmpty: true让剩余结构为空时删除文件。执行器拥有磁盘写入、日志条目、回滚快照与运行时/作用域过滤。作者护栏：每个rewrite-json动作必须带ownershipEvidence，且迁移记录必须带runtimeContract引用运行时配置契约注册表。Codexhooks.json的清理（迁移 002）是典型用例——GSD 能证明单个生成 Hook 命令的所有权，却不能证明整个文件。

preserve-user / record-baseline / baseline-preserve-user / prompt-user

preserve-user：声明路径为用户自有并须在周边目录替换中存活；所有权未建立时非交互应用会阻塞，直到交互式基线迁移记录显式用户选择。
record-baseline：把清单托管文件记入首次基线而不改动它；仅首次基线扫描器可用。
baseline-preserve-user：把在已知安装表面发现的用户自有或未知文件记入基线而不改动；未知文件默认此动作，除非它们看起来像需要显式用户选择的退役 GSD 生成产物。
prompt-user：在交互模式下停止非交互破坏性迁移并询问；提示必须给出具体选择（保留、备份、移除、移动），默认保留。用于分类有歧义、猜测可能丢数据的场景。

执行流程：从规划到物化的调用链

安装器在物化新包载荷之前运行迁移。标准流程（docs/installer-migrations.md）：

构建安装上下文；
读取旧清单与安装状态；
为可能触及的路径构建运行前快照；
按运行时、作用域与应用状态发现待处理迁移；
向每个待处理迁移询问计划；
合并计划并校验；
以 dry-run 形式打印计划；
应用安全的非交互动作；
对歧义动作提示或停止；
写入新包载荷；
写入新清单与安装状态；
上报备份、保留文件、移除的过期文件与跳过的动作。

Phase 4 的安装集成把这个流程接入每个受支持运行时的正常安装/更新入口：Claude Code、Antigravity、Augment、Cline、CodeBuddy、Codex、Copilot、Cursor、Hermes Agent、Kilo、OpenCode、Qwen Code、Trae、Windsurf。安装器以baselineScan: true调用同一迁移运行器，上报计划动作行，在物化前应用安全非交互动作，仅在包物化与收尾成功后持久化安装状态；运行器返回被阻塞的用户选择动作时，在写入新包文件之前失败。

核心引擎位于 src/installer-migrations.cts（约 1200 行规划/应用/回滚/锁/日志引擎）。入口runInstallerMigrations（L1193-L1254）串起三段：先acquireInstallMigrationLock取锁；再planInstallerMigrations规划；无动作时仅markPendingMigrationsApplied落账，有阻塞动作时原样返回blocked列表，否则applyInstallerMigrationPlan执行并返回可调用的rollback句柄；finally中释放锁，释放失败按主错误路径压制或抛出。安装器侧的关键消费点包括 install-engine.cts（读清单files）、installed-surface-resolver.cts（读清单与清单名）、retired-artifact-cleanup.cts（退役产物清理）、runtime-artifact-layout.cts（按managed-pristine分类判断覆盖）与 user-artifact-staging.cts（复用符号链接保留复制原语）。

对 OpenCode 家族的既有安装，install-engine.cts 中的_migrateLegacyOpencodeCommandDir在物化前把旧单数command/目录迁往复数commands/（#2329）：仅删除旧清单中记录且未变或本地修改过的command/<file>，任何未能证明清单托管的用户内容原样保留，空目录只在无残留后才移除。

若任一应用步骤失败，执行器用日志恢复尽可能多的已修改路径（rollbackAppliedMigrationResult）：逆序遍历日志动作，用copyPreservingSymlink从回滚根恢复字节（符号链接快照按链接本身恢复，绝不读取被指内容），随后恢复安装状态字节并清理日志与备份树。回滚绝不删除本次运行未创建或未修改的文件。回滚是尽力而为，但不完整时必须响亮报错（rollbackFailures逐条列出）。

锁保护的执行

acquireInstallMigrationLock（src/installer-migrations.cts#L591-L676）以gsd-install-migration.lock为互斥点，默认超时 30 秒（DEFAULT_LOCK_TIMEOUT_MS）。要点：

以openSync(lockPath, 'wx')独占创建锁文件，负载通过该独占描述符写入{ pid, acquiredAt }，避免二次按路径打开造成的 TOCTOU（CWE-367）窗口；
写后立即关闭句柄，保证 Windows 上释放闭包能 unlink 未被占用句柄的文件；
遇到EEXIST时读锁内 PID 做陈旧锁回收：持有者死亡（ESRCH）或同进程重入则尝试 unlink 后重试，仅当 unlink 真正成功才继续，避免静默失败造成死循环；
超时后抛出installer migration lock is held，附持有 PID 与时间；
释放用unlinkSync而非rmSync({ force: true })，让 Windows EPERM 不被吞掉，失败以带failures数组的错误抛出。

测试侧对应断言包括 tests/installer-migrations.test.cjs：持有锁时拒绝运行（lockTimeoutMs: 0立即超时），以及模拟 unlink 失败后上报锁释放失败。

Dry run：同一个规划器

迁移运行器支持 dry-run：打印计划后不做任何更改退出。输出按风险分组：将保留、将替换未改托管文件、将移除过期托管文件、将备份本地修改文件、需要用户选择、被阻塞。同一规划器同时驱动 dry-run 与应用，不允许存在独立的"仅预览"代码路径——这保证了预览即真实。

首次基线迁移：分类旧安装的逃生通道

首个迁移应分类既有安装而非修复每种历史布局（docs/installer-migrations.md）。步骤：读当前清单（如有）→ 扫描已知运行时安装表面 → 把文件分类为托管/用户自有/未知 → 上报不在当前清单中的过期 GSD 形状文件 → 为歧义文件提供动作而非删除 → 分类成功后写入安装状态。

Phase 3 实现了门控基线记录2026-05-11-first-time-baseline-scan（src/installer-migrations/000-first-time-baseline.cts）。运行器仅在安装器传baselineScan: true时才触发首次扫描；不带该标志时，发现过程对普通迁移运行安全，基线记录规划零动作。基线动作契约：

record-baseline：清单托管文件；
baseline-preserve-user：已知用户自有文件与不像过期 GSD 生成产物的未知文件；
prompt-user：无法被清单证明的过期 GSD 形状产物。

实现细节值得注意：RUNTIME_SURFACES记录了每个运行时的安装表面（Claude 的commands/gsd、Codex 的config.toml、pi 的extensions等），scanBaselineFiles递归遍历表面目录，INTERNAL_TOP_LEVEL_NAMES跳过清单/状态/日志等内部文件；isUserOwnedBaselinePath把skills/与agents/下非gsd-前缀条目、USER_OWNED_PATHS中的偏好文件判为用户自有；isKnownGeneratedAgentPath对照仓库agents/目录里的gsd-*.md文件名集合判断生成 Agent；isStaleGsdLookingPath识别gsd[-_]前缀的疑似过期产物并投给prompt-user。动作按"record-baseline < baseline-preserve-user < 其余"排序后输出，保证基线可读。

运行时配置契约注册表

注册表是触及宿主运行时配置的迁移的事实来源（docs/installer-migrations.md）。每行记录：What（GSD 安装的调用、Agent、技能、规则、Hook 或配置表面）、Where（安装器瞄准的全局与本地根）、When（安装/升级/卸载/迁移触点）、Who（周边用户配置的所有权边界）、Why（上游加载器契约或当前 GSD 兼容垫片）。

迁移作者在产出rewrite-config、move-managed或破坏性清理动作前必须阅读对应行。注册表规则：

运行时提供 JSON/JSONC/TOML/YAML 时一律用结构化解析器；标记块重写需换行与排序测试；
不声称混合配置文件的所有权，只拥有生成条目、生成文件与显式标记块；
未知用户配置即使位于 GSD 托管运行时根内也要保留；
运行时文档/CLI schema/加载器行为变化时更新上游快照日期与版本注记；
源受限行按高风险处理，重写这些运行时的迁移需要新主源或带测试的安装器级探针。

已落地迁移一览

每个已落地迁移对应src/installer-migrations/中的一个记录（完整表见 docs/installer-migrations.md）：

ID	文件	引入版本	作用域	破坏性	摘要
`2026-05-11-first-time-baseline-scan`	`000-first-time-baseline.cts`	1.50.0	global, local	否	在破坏性迁移前记录既有安装的分类基线。
`2026-05-11-legacy-orphan-files`	`001-legacy-orphan-files.cts`	1.50.0	global, local	是	移除清单托管的旧孤儿 Hook 文件（`hooks/gsd-notify.sh`、`hooks/statusline.js`）。
`2026-05-11-codex-legacy-hooks-json`	`002-codex-legacy-hooks-json.cts`	1.50.0	global, local	是	在`config.toml`迁移后移除 Codex`hooks.json`中的旧 GSD Hook 注册。
`2026-06-02-rename-get-shit-done-to-gsd-core`	`003-rename-get-shit-done-to-gsd-core.cts`	1.2.0	global, local	是	重命名为`gsd-core/`（#604）后移除旧`get-shit-done/`目录中的托管文件；用户新增文件保留。
`2026-06-09-prune-stale-pristine-get-shit-done`	`004-prune-stale-pristine-snapshots.cts`	1.4.3	global, local	是	移除迁移 003 遗留的`gsd-pristine/get-shit-done/`快照（#934）。
`2026-07-17-opencode-baseline-commands-dir`	`005-opencode-baseline-commands-dir.cts`	1.7.0	global, local	否	首次扫描中把 OpenCode`commands/`（复数）既有文件纳入基线；修复 000 只覆盖旧`command/`别名的问题。
`2026-07-20-pi-extension-cjs-to-js`	`006-pi-extension-cjs-to-js.cts`	1.7.1	global, local	是	移除 #2470 前 pi 安装遗留的`extensions/gsd.cjs`；本地修改版备份而非删除，未入清单的`gsd.cjs`按用户文件保留。
`2026-07-28-retire-config-root-commonjs-marker`	`007-retire-config-root-commonjs-marker.cts`	1.8.0	global, local	是	当`<configRoot>/package.json`恰为 pre-#2544 的`{"type":"commonjs"}`标记时移除；以内容精确匹配而非清单证明所有权。
`2026-07-29-cursor-retire-commands-surface`	`008-cursor-retire-commands-surface.cts`	1.8.1	global, local	是	移除 Cursor 安装中清单托管的`commands/gsd-*.md`（#2644 重复条目）；修改版备份，未入清单文件保留。
`2026-08-07-pi-retire-reserved-hooks-dir`	`009-pi-retire-reserved-hooks-dir.cts`	1.9.2	global, local	是	移除 pi 旧`hooks/`下托管文件并在清空后移除目录本身（共享 Hook 包改装`gsd-hooks/`，#3023）；首个使用`remove-empty-dir`的迁移。
`2026-08-26-antigravity-retire-confighome-artifacts`	`010-antigravity-retire-confighome-artifacts.cts`	1.11.0	global	是	移除 Antigravity configHome（`~/.gemini/antigravity{,-ide,-cli}`）下清单托管的`skills/gsd-/`与`agents/gsd-.md`；仅全局作用域。

这些迁移的写法印证了动作类型护栏：例如 006 在头部逐条回答作者清单问题（退役对象、所有权证明、用户修改怎么办、缺失怎么办、影响运行时/作用域、非交互是否安全），而 009 用remove-empty-dir解决"目录名存在本身触发宿主告警"的场景，可对照 006-pi-extension-cjs-to-js.cts 与 009-pi-retire-reserved-hooks-dir.cts 阅读。

编写新迁移的实战流程

当特性移除或移动安装产物时，PR 必须包含（docs/installer-migrations.md）：

迁移记录；
dry-run 计划输出测试；
应用行为测试；
本地修改托管文件测试；
变更路径附近的用户自有文件测试；
若迁移影响用户可见安装行为，更新发布说明。

作者必须在迁移文件中回答：退役哪个旧产物/配置形状？如何证明它是 GSD 所有？用户修改过怎么办？缺失怎么办？影响哪个运行时与作用域？非交互安装中是否安全？

测试矩阵要求覆盖（docs/installer-migrations.md）：无旧状态的全新安装、清单匹配的重装、有待处理迁移的升级、本地修改托管文件、GSD 目录下的未知文件、被清空目录下的用户自有文件、失败应用回滚、全局/本地作用域（如适用）、路径序列化时的 Windows 分隔符、配置文件重写时的 CRLF 输入。核心断言可在 tests/installer-migrations.test.cjs 中找到：阻塞过期 GSD 形状基线产物（prompt-user）、未知文件默认保留、无阻塞计划的应用带日志与状态更新、回滚恢复文件与安装状态、锁占用拒绝运行、模拟 unlink 失败上报释放失败、应用失败清理回滚与备份产物。

实施顺序（docs/installer-migrations.md）：抽取清单与用户自有列表的所有权助手 → 安装状态读写 → 记录发现与校验和计算 → 仅规划器 dry-run → 带日志的 executor → 把孤儿 Hook/文件清理移植为首个显式迁移 → 移植一次结构化配置重写 → 既有安装基线分类器 → 要求影响安装的 PR 在移动/重命名/退役产物时带迁移。该序列保持首个实现小：既有安装器继续物化文件，迁移运行器接管清理、分类与可评审的破坏性变更。

安全模型：默认保护、显式删除

安全策略（docs/installer-migrations.md）可归纳为三条：

所有权：绝不删除未知文件，除非迁移含证明其为过期 GSD 产物的特定检测器。
修改检测：路径在旧清单中时，哈希匹配 = 未改托管文件，可替换；哈希不匹配 = 本地修改托管文件，须备份；缺失 = 用户已删，应保持删除除非迁移明确需要重建。
用户自有产物：定义一次，被保留逻辑与清单写入逻辑共同消费；新增用户自有产物必须带证明其跨重装保留且不出现在清单中的回归测试。
配置文件：运行时配置是混合所有权；GSD 可能拥有标记块、生成 Agent 段或 Hook 条目，但不拥有整个文件，除非文件是 GSD 专属创建。配置迁移只应移除或重写被拥有的部分。

路径安全上，所有动作路径先经normalizeRelPath拒绝绝对路径与任何..段，再由ensureInsideConfig用词法谓词tryWithinRootLexical做纵深防御（src/installer-migrations.cts）；符号链接托管路径被当作链接快照/恢复/备份，绝不解析被指内容（copyPreservingSymlink）。这解释了为何回滚即使对被替换为链接的托管路径也不会把链接目标字节泄入备份树。

结语

安装器迁移模块把 GSD 的升级安全从分散的一次性清理块收敛为可评审、可回滚、可复现的版本化管线：基线扫描负责把旧安装分类清楚，折叠式动作报告让破坏性动作在物化前可见，被阻塞动作以 fail-closed 保护用户数据，事务式回滚与安装状态持久化保证失败可恢复，锁保护确保多进程安装互斥。核心引擎与全部已落地迁移均可在仓库中直接阅读：src/installer-migrations.cts、src/installer-migration-authoring.cts、src/installer-migrations/、tests/installer-migrations.test.cjs，设计与契约见 docs/installer-migrations.md、docs/adr/0008-installer-migration-module.md 与 docs/features/installer-migrations.md。