【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载导读本文围绕 gsd-core 仓库中编号为#4760的 changeset 修复展开当 Codex 运行时执行 gsd-core 安装/升级失败时旧版安装器的回滚快照只覆盖config.toml、hooks.json、skills/、agents/与VERSION这几个条目导致失败安装留下的部分 payload如CHANGELOG.md、scripts/、.gsd-runtime、安装清单本身乃至整个hooks/目录残留在目标机器上环境无法恢复到真正安装前的状态。修复后的回滚快照改为以前一次安装清单install manifest记录的每一个文件为基准并额外覆盖整个hooks/目录。读完本文你将理解 gsd-core 安装器的清单驱动回滚模型、快照范围如何决定回滚保真度以及如何通过源码与测试验证这次修复。一、这次修复在修什么changeset 原文拆解关联文档.changeset/zesty-pumas-hum.md的完整内容是--- type: Fixed pr: 4760 --- **Codex rollback no longer leaves a partially-installed payload behind** — the installers rollback snapshot now covers every file the previous installs manifest recorded (CHANGELOG.md, scripts/, .gsd-runtime, the manifest itself) plus the whole hooks/ directory, instead of only config.toml, hooks.json, skills/, agents/ and VERSION, so a failed install reverts to the true pre-install state. (#4544)逐句拆解可得到三个核心事实缺陷issue#4544Codex 运行时场景下一次失败的安装会在磁盘上留下部分安装的 payloadpartially-installed payload。所谓 payload指安装器实际写盘的产物而不只是配置文件。旧回滚快照范围过窄此前回滚只保护config.toml、hooks.json、skills/、agents/与VERSION。这些恰恰是安装器看得见的常规条目但安装动作实际影响的文件远不止这些。修复后的快照范围PR#4760覆盖前一次安装清单manifest记录到的每一个文件——包括CHANGELOG.md、scripts/、.gsd-runtime、清单文件自身——再加上整个hooks/目录。这样失败安装能够回滚到真正的安装前状态true pre-install state。二、回滚快照的范围为什么决定是否真的回到安装前安装器的回滚rollback本质上是一个撤销动作把安装过程中被写入、覆盖或移动的文件恢复到动作发生之前的样子。要做到这一点安装器必须先知道两件事哪些路径被这次安装动过这些路径原来的内容是什么即快照。如果快照范围小于实际写盘范围那么回滚之后必然有文件残留——这就是部分安装的 payload 被留下的根源。旧版快照覆盖的是config.toml、hooks.json、skills/、agents/、VERSION。但从仓库的安装布局看一次安装还会触碰CHANGELOG.md安装/升级流程会更新版本说明文件scripts/安装器自带的脚本集会被写入该目录.gsd-runtime用于物化全局运行时表面Runtime Surface的目录源码注释称之为installation-owned input needed to re-materialize a global Runtime Surface见 src/install-engine.cts 中provisionRuntimeSurfaceCorpus的说明安装清单自身the manifest itself清单记录着本次安装的归属文件与哈希整个hooks/目录仓库中hooks/下实际包含gsd-prompt-guard.js、gsd-write-guard.js、gsd-workflow-guard.js等二十余个钩子脚本参见 hooks/它们是安装器复制到目标环境的核心执行代码。这些路径一旦写盘失败旧快照无法还原就会成为脏残留。三、修复后的快照范围清单全量 hooks/ 目录修复后的回滚快照范围可以精确表述为两个集合的并集rollback_snapshot every file recorded in the previous installs manifest the whole hooks/ directory其中前一次安装清单记录的每一个文件包括CHANGELOG.md、scripts/、.gsd-runtime与清单本身hooks/目录则被整体纳入不再只挑其中的hooks.json。这一设计的关键在于**以清单为唯一事实来源**安装器不再硬编码一份回滚白名单而是读取上一次安装留下的清单凡是清单证明归 GSD 所有的路径全部纳入回滚快照。清单中没有记录的路径比如用户自己放进目录的其他内容不会被误删也不会被回滚波及——这正是源码注释里强调的Preserve existing entries rather than guessing that they are stale见下文。四、源码级剖析清单如何驱动回滚4.1 读取前一次安装清单previousOwnedCorpusFiles在 src/install-engine.cts 中previousOwnedCorpusFiles(configDir, prefix)是这次修复的核心函数之一function previousOwnedCorpusFiles(configDir: string, prefix: string): string[] { try { const files installerMigrations.readInstallManifest(configDir).files; return Object.keys(files) .filter((entry) entry.startsWith(prefix)) .map((entry) entry.slice(prefix.length)) .filter((entry) entry ! !path.posix.isAbsolute(entry) !entry.split(/).some((part) part || part . || part ..)); } catch { // An absent or unreadable prior manifest provides no ownership evidence. // Preserve existing entries rather than guessing that they are stale. return []; } }要点数据来源是readInstallManifest(configDir)即仓库 src/installer-migrations.cts 中负责解析安装清单仓库内可见的产物名称为gsd-file-manifest.json在 src/install-engine.cts 的注释中被提及的接口过滤条件保证只返回清单证明属于 GSD、且位于受控前缀之下的合法相对路径若清单缺失或不可读函数返回空数组——此时安装器宁可保留现状也不猜测删除这是一种保守的失败模式fail-safe。4.2 只删清单证明归属的路径syncRuntimeSurfaceCorpussrc/install-engine.cts 的syncRuntimeSurfaceCorpus展示了清单驱动的清理在写盘前的实际形态// Remove only paths the previous manifest proves GSD owned and which the // executing package no longer ships. Unknown neighbouring files survive. for (const relative of previousOwnedCorpusFiles(configDir, manifestPrefix)) { const sourceEntry path.join(source, ...relative.split(/)); let sourceIsFile false; try { sourceIsFile installFs().lstatSync(sourceEntry).isFile(); } catch { sourceIsFile false; } if (sourceIsFile) continue; const target path.join(destination, ...relative.split(/)); if (!installFs().existsSync(target)) continue; const targetStat installFs().lstatSync(target); if (!targetStat.isFile()) { throw new Error(Runtime Surface corpus ownership conflict at ${target}); } installFs().rmSync(target, { force: true }); pruneEmptyCorpusParents(target, destination); }这段逻辑与本次修复遵循同一原则只有前一次清单能够证明归 GSD 所有的路径才允许被移除用户放入的无关文件unknown neighbouring files一律保留遇到归属冲突目标不是普通文件则直接抛错中止而不是强行删除。4.3 目录级深度快照_snapshotDir/_restoreDir回滚快照的底层实现位于 src/install-engine.cts一对配套函数负责把目录树深拷贝进内存、再按需还原// Deep-snapshot a directory tree into a MaprelPath, Buffer. function _snapshotDir(dir: string): Mapstring, Buffer { ... } // Restore a directory tree from a MaprelPath, Buffer produced by _snapshotDir. function _restoreDir(dir: string, snapshot: Mapstring, Buffer): void { for (const [relPath, buf] of snapshot) { ... } }_snapshotDir把目录树变成Map相对路径, Buffer_restoreDir再按这个映射逐项写回。这种先整体快照、失败后整体还原的模式正是覆盖清单每一个文件 整个 hooks/ 目录这类宽范围快照得以落地的机制。需要说明的是源码中还提到用户内容如skills/下的用户文件在清理前也会被_snapshotDir预快照见 src/install-engine.cts说明快照机制同时兼顾还原安装产物与保护用户数据两条线。4.4 迁移引擎中的回滚执行rollbackAppliedMigrationResult在迁移installer migration场景中回滚由 src/installer-migrations.cts 的rollbackAppliedMigrationResult执行每个将被修改的托管路径在应用前会被复制到回滚根目录rollbackRoot路径形态为gsd-migration-journal/runId-rollback见 src/installer-migrations.cts复制时使用copyPreservingSymlink其注释明确说明GSD 安装的产物不会是符号链接因此忠实快照restore 时重建同样的链接能在不读取链接目标内容的前提下保证回滚保真src/installer-migrations.cts应用失败时按逆序rollback.reverse()逐条还原src/installer-migrations.cts若回滚本身也有失败条目则抛出携带rollbackFailures明细的错误而不是静默吞掉成功后清理rollbackRoot与 journal 产物cleanupMigrationRunArtifacts回滚目录本身是临时产物不长期驻留。rollbackInstallerMigrations是安装结果对外暴露的回滚入口在 src/install-engine.cts 中被导出调用方拿到后可在安装失败时主动执行回滚。五、测试佐证回滚入口在异常路径上仍然可用仓库测试 tests/install.test.cjs 为该机制提供了直接佐证。其中一条测试名为malformed settings.local.json still returns configuredEntrypoints and a working rollbackInstallerMigrations它断言即便settings.local.json无法解析一次典型的安装失败前置条件install()返回结果中仍然带有configuredEntrypoints与可调用的rollbackInstallerMigrations并且调用rollbackInstallerMigrations()时不得抛出异常must not throw when called on this early-return path。注释还特别强调若该早期返回路径遗漏rollbackInstallerMigrations后续的rollbackFinalizedInstallerMigrations将无条件读取它从而静默丢失该运行时的回滚能力。这意味着回滚能力被视作安装契约的一部分只要安装入口被执行无论中途是否异常调用方都必须能拿到一个可用且可调用的回滚函数。这正是失败安装不能留下部分 payload这条修复目标的测试侧保障。六、如何在实际环境中验证这次修复如果你在部署或升级 gsd-core 后怀疑残留了失败安装的 payload可以按以下思路排查仓库为只读资源以下均为本地观察手段查看安装清单在配置目录下查找安装器写入的清单文件仓库内可见的产物名为gsd-file-manifest.json其解析入口为 src/installer-migrations.cts 的readInstallManifest清单中files键列出的路径即安装器认定归 GSD 所有的集合。核对回滚日志目录迁移运行期间回滚快照位于配置目录下gsd-migration-journal/runId-rollback路径拼接见 src/installer-migrations.cts若存在残留的 journal/rollback 目录说明上一次运行没有干净收尾。对比安装前快照修复后CHANGELOG.md、scripts/、.gsd-runtime、清单自身以及整个hooks/目录都应在回滚覆盖范围内如果失败后这些路径仍有改动痕迹而回滚已成功执行则属于异常应提交 issue。七、这次修复的工程启示从 changeset 到源码这次修复浓缩了三条可迁移的工程原则快照范围必须等于真实写盘范围。任何覆盖了常规条目却漏掉实际产物的快照在失败回滚时都会留下脏残留以安装清单为唯一事实来源枚举受影响路径比硬编码白名单更不容易腐化。清单缺失时的默认动作是保守保留。previousOwnedCorpusFiles在清单不可读时返回空集Preserve existing entries rather than guessing避免安装器在信息不足时误删用户数据。回滚能力是安装契约的一部分。rollbackInstallerMigrations必须在任何早期返回路径上都保持可调用tests/install.test.cjs否则回滚能力的静默丢失比安装失败本身更危险。本次修复同时更新了仓库内的迁移实现相关迁移文件可见 src/installer-migrations/003-rename-get-shit-done-to-gsd-core.cts 等它们在installer-migrations目录内统一演进从只还原配置升级为还原到真正的安装前状态——这正是Git. Ship. Done所要求的可失败、可恢复、可重试的安装体验。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐gsd-core 修复 Codex 安装兼容性TOML 浮点解析与五表面原子回滚详解gsd core 修复 Codex 安装兼容性TOML 浮点解析与五表面原子回滚详解 导读 本文深入剖析 gsd coreGit. Ship. Done —GSD-Core 仓库本地 Agent 安装检测--local 安装为何报 agents_installed 为 false 及其修复原理GSD Core 仓库本地 Agent 安装检测 local 安装为何报 agents_installed 为 false 及其修复原理 本篇以 kind m解决ASDF安装失败从错误排查到状态修复的终极指南解决ASDF安装失败从错误排查到状态修复的终极指南 ASDF Another System Definition Framework 是一个多语言版本管理器CLI开发工具上一篇Duix-Avatar 本地部署 4 步走免费跑虚拟形象视频合成实操教程下一篇终极指南10分钟掌握C语言自编译神器c4编译器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考