get-shit-done(GSD)手动更新完全指南:从源码仓库构建 hooks 与离线重装运行时 📅 发布时间:2026/9/9 20:32:29 👁 浏览次数: get-shit-doneGSD手动更新完全指南从源码仓库构建 hooks 与离线重装运行时【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-doneget-shit-done下文简称 GSD默认通过npx get-shit-done-cclatest完成安装与升级但 npm 发布异常、内网离线环境或需要跟随源码仓库开发分支时该通道可能不可用。本文基于仓库 docs/manual-update.md 的核心流程结合 bin/install.js、scripts/build-hooks.js 等源码实现完整讲解“从本地源码仓库手动更新 GSD”的五步操作、安装器对运行时目录的 wipe-and-replace 语义、本地修改的保护与回放机制帮助你在无 npm 依赖的情况下把 GSD 升级到最新版本。一、什么时候需要“手动更新”npx get-shit-done-cclatest是 GSD 日常安装/升级的标准入口它会从 npm registry 拉取最新包并执行安装器。以下场景需要切换到本文的手动流程npm 发布窗口不可用publish outage最新版本尚未发布或 registry 暂时不可访问直接基于源码仓库工作你在本地克隆了本仓库即把仓库本身作为 GSD 的“源”需要跟随main分支的迭代公司内网/离线环境无法访问外网 npm但仓库源码可以同步到本地。核心思路把“从 npm 取包”替换为“从本地仓库取文件”即git pull拉最新源码 → 构建 hooks 产物 → 直接用仓库内的bin/install.js跑安装器 → 清理更新缓存 → 重启运行时。二、前置条件PrerequisitesNode.js 已安装安装器与 hooks 构建脚本均为 Node.js 实现bin/install.js 以#!/usr/bin/env node直接执行仓库已克隆到本地确保你手头有一份仓库源码的本地克隆例如git clone https://gitcode.com/GitHub_Trending/getshi/get-shit-done.git已克隆的读者跳过此步直接使用你本地的仓库目录即可后续所有命令均假设当前工作目录位于该仓库根目录。三、五步完成手动更新Step 1 —— 拉取最新代码git pull --rebase origin main使用--rebase而非git merge可以将本地未提交/基于旧提交的改动线性地重放到远端最新提交之上避免产生无意义的 merge commit让仓库保持干净可追溯。这是进入后续步骤的前提只有源码是最新的构建与安装出来的才是最新版。Step 2 —— 构建 hooks 的 dist 产物必需步骤node scripts/build-hooks.js这一步不可省略hooks/dist/属于“生成产物”并不作为源码检入仓库。这一点在仓库.gitignore中明确体现——.gitignore 同时忽略了hooks/dist/与构建用的hooks/.dist-staging-*/临时目录。因此从源码直接安装前必须先构建出安装器所要拷贝的 hooks 产物。该构建脚本scripts/build-hooks.js值得关注几个实现细节明确的拷贝清单脚本用HOOKS_TO_COPY数组scripts/build-hooks.js固定列出要打包的 hooks包括gsd-check-update.js、gsd-statusline.js、gsd-prompt-guard.js等 JS hooks以及若干社区 bash hooksgsd-session-state.sh、gsd-validate-commit.sh、gsd-phase-boundary.sh等同时会把hooks/lib/子目录整体拷贝进 dist供被安装的.shhooks 解析相对依赖拷贝前语法校验对每个.js文件脚本先用vm.Script编译校验语法scripts/build-hooks.js防止把存在重复const声明、括号缺失等语法错误的 hook 拷进 dist。脚本注释表明这类事故曾真实发生过并导致所有用户的 PostToolUse hook 报错issue #1107/#1109/#1125/#1161这是该校验存在的原因原子写入构建采用“按进程 PID 建独立 staging 目录 → 写入 →rename原子替换”的策略scripts/build-hooks.js避免并行构建或安装器读文件时读到写了一半的文件Windows 下还针对EPERM/EBUSY做了带退避的重试与 copy 兜底。构建成功后控制台会输出每个 hook 的✓ Copying ...与最终Build complete.若有语法错误则以非零码退出并提示先修复。Step 3 —— 直接运行安装器node bin/install.js --claude --global此时安装的不是 npm 包而是当前仓库源码。安装器入口 bin/install.js 会按参数解析出目标运行时与安装作用域再执行一整套安装流程。先不深究机制参数替换规则见下文第四节作用域含义见第五节。Step 4 —— 清理更新缓存重置状态栏提示rm -f ~/.cache/gsd/gsd-update-check.jsonGSD 的会话启动 hookhooks/gsd-check-update.js会在每次会话启动时检查 npm 最新版本并把结果写入缓存文件供状态栏显示类似“有新版本可更新”的提示。手动升级完成后这条缓存记录指向的是旧版本比对结果若不清理状态栏会继续显示过期的“可更新”标记造成误导。仓库的/gsd:update正式更新工作流在清理缓存时覆盖更广见 get-shit-done/workflows/update.md除了共享的~/.cache/gsd/gsd-update-check.json还会按检测到的各运行时缓存目录逐一清理cache/gsd-update-check.json并遍历.claude、.config/opencode、.codex等默认目录对应回归测试见 bug-2784-update-cache-clear-path.test.cjs。手动场景只装单一运行时清理上面一条共享缓存通常已足够若状态栏仍残留旧提示可按该工作流的逻辑一并清理对应运行时目录下的 cache 文件。Step 5 —— 重启你的运行时# 重启 Claude Code / Gemini CLI / OpenCode 等运行时必须重启才能加载新安装的 commands 与 agents运行时如 Claude Code通常在启动时扫描命令目录与 agent 目录、注册斜杠命令升级过程中写入的新文件不会在已运行会话中被热加载。四、按运行时选择安装标志Runtime flags上文 Step 3 中的--claude是目标运行时的标志按需替换为下表即可RuntimeFlagClaude Code--claudeGemini CLI--geminiOpenCode--opencodeKilo--kiloCodex--codexCopilot--copilotCursor--cursorWindsurf--windsurfAugment--augment所有运行时--all从安装器源码看仓库实际支持的运行时比上表更全参数解析段bin/install.js还识别--antigravity、--trae、--qwen、--hermes、--codebuddy、--cline--all会一次性安装到全部 15 个运行时bin/install.js--both作为兼容遗留标志等价于 Claude OpenCode。即# 例如同时安装到 Gemini CLI 与 Kilo node bin/install.js --gemini --kilo --global各运行时的配置文件目录并不统一。安装器中的getGlobalDir()bin/install.js按运行时解析出目标目录Claude Code 默认~/.claudeOpenCode 走 XDG 规范为~/.config/opencodeKilo 为~/.config/kiloCodex 为~/.codexWindsurf 为~/.codeium/windsurf等并支持CLAUDE_CONFIG_DIR、GEMINI_CONFIG_DIR、CODEX_HOME这类环境变量覆盖以及优先级最高的--config-dir path参数。目录不符时可先用这些机制核对安装落点。五、作用域--global与--local--global短写-g安装到上述运行时配置文件目录对所有项目生效--local短写-l项目级安装。把 GSD 装进当前项目目录如.claude/、.codex/等只对该项目生效适合团队仓库内固定版本场景。安装器参数解析段bin/install.js对--global/-g、--local/-l均做识别。手动从源码升级时务必与最初安装的作用域保持一致原全局装就--global原项目装就--local否则会出现“全局升级了、项目里仍是旧版”这类版本漂移。六、安装器到底替换了什么wipe-and-replace 边界手动更新本质上重放了完整的安装流程而 GSD 安装器对既有安装执行的是受管目录的“擦除-重建”。以 Claude Code 全局安装为例被整目录/整集合替换的是替换对象安装路径workflows / references / templates~/.claude/get-shit-done/斜杠命令~/.claude/commands/gsd/GSD agents~/.claude/agents/gsd-*.md编译后的 hooks~/.claude/hooks/dist/注意边界替换动作只作用于“GSD 受管文件”而非整个运行时目录。以下内容会被原样保留非gsd-前缀的自定义 agentscommands/gsd/之外的其它自定义命令你自己的CLAUDE.md文件自定义 hooks。这一语义在源码中有多处支撑安装器通过gsd-file-manifest.json清单记录每个受管文件的 SHA256 哈希见 bin/install.js区分“GSD 写过的文件”与“用户自建文件”清理时只按受管前缀/集合移除 GSD 条目并在擦除前先快照用户自建产物、擦除后恢复源码注释中 #1423 等一系列“preserve user artifacts”机制。七、本地修改保护与回放gsd-local-patches如果你直接改动过 GSD 自带的文件安装器不会默默覆盖后让你丢失这些改动自动备份安装器在擦除前逐文件比对gsd-file-manifest.json中的原哈希与磁盘当前哈希bin/install.js把“内容已被修改”的文件拷贝到配置目录下的gsd-local-patches/并额外生成backup-meta.json记录备份时间、来源版本与原始哈希bin/install.js生成 pristine 基线对每个被修改文件安装器还通过安装变换管线重建一份“若未被修改时本应是什么样”的gsd-pristine/副本bin/install.js用于后续做三路对比安装后提示安装结束时会检测gsd-local-patches/backup-meta.json提示存在本地补丁并给出回放命令bin/install.js。升级完成后用回放命令把改动合并回新版本/gsd-update --reapply该命令由 commands/gsd/update.md 路由到 reapply-patches 工作流get-shit-done/workflows/reapply-patches.md。其合并采用三路比较以gsd-pristine/原版基线、gsd-local-patches/你改过的版本、新安装的版本三者为输入区分“你的自定义行”与“上游版本漂移”从而可靠地把你的定制内容合并进新版。回放工作流有一个关键约束值得了解凡是进入gsd-local-patches/的文件必然是安装器哈希比对认定“被改动过”的因此该工作流绝不应对任何已备份文件得出“没有自定义内容”的结论——无法确证时一律按冲突交回用户人工审核而不是静默跳过。对非 Claude 运行时命令形态略有不同安装器会按运行时输出对应的--reapply调用形式如gsd-update --reapply、$gsd-update --reapply等执行前以实际提示为准。八、注意事项与排错避免 dev 版本与 npm 版本互相“降级”仓库的更新工作流会区分“已安装版本 最新版 / 已安装版本 最新版”两种情况。若你是源码开发安装本地产物版本号领先于 npm 发布版看到状态栏出现“dev install — re-run installer to sync hooks”之类提示时应通过重跑本地安装器node bin/install.js --global --claude来对齐 hooks而不要执行基于 npm 的/gsd:update否则会把开发版本“降级”回 npm 版见 get-shit-done/workflows/update.md 的 compare_versions 步骤WSL Windows 原生 Node.js安装器检测到该组合时会直接终止并建议安装 Linux 原生 Node因为路径解析差异会让安装落点出错bin/install.js定制配置文件目录若当初使用--config-dir或CLAUDE_CONFIG_DIR等环境变量指定过非默认目录升级时需保持同一目标否则新版会装到默认目录造成“双份安装”困惑构建失败时scripts/build-hooks.js任一 JS 文件语法校验不过即以非零退出请先修复 hooks 源码再重新构建、继续后续安装步骤。九、相关文档与源码索引docs/manual-update.md——本文对应的原始官方流程文档bin/install.js——安装器实现参数解析、运行时目录解析、清单哈希比对、gsd-local-patches/备份与提示scripts/build-hooks.js——hooks dist 构建器拷贝清单、语法校验、原子写入.gitignore——hooks/dist/与 staging 目录为生成产物的依据commands/gsd/update.md——/gsd-update命令及--sync/--reapply子模式路由get-shit-done/workflows/update.md——完整更新工作流版本检测、npm 比对、变更日志展示、缓存清理get-shit-done/workflows/reapply-patches.md——三路合并回放本地补丁的实现hooks/gsd-check-update.js——写入更新缓存、驱动状态栏提示的会话启动 hooktests/bug-2784-update-cache-clear-path.test.cjs——更新缓存清理路径的回归测试docs/CONFIGURATION.md、docs/USER-GUIDE.md——GSD 配置与整体使用说明可作延伸阅读。总结手动更新本质上是“跳过 npm 拉包、直接用本地仓库源码重放一次安装”。记住链路git pull --rebase→node scripts/build-hooks.js生成被 git 忽略的 hooks/dist→node bin/install.js --runtime --global|--local→ 清理~/.cache/gsd/gsd-update-check.json→ 重启运行时即可在任意无 npm 发布通道的环境里安全跟进 GSD 最新版本并借助gsd-local-patches//gsd-update --reapply保住你对受管文件的本地定制。【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考