甘草工作流 (GC Workflow Helper)

专为 Gancao 团队定制的 Git 工作流辅助工具，提供 VS Code 插件入口和 CLI 入口。

项目定位

本扩展把团队常用 Git 工作流、版本发布和 Node/pnpm 声明标准化操作接入 VS Code 侧边栏，降低重复终端命令的使用成本。核心 Git 工作流逻辑位于 scripts/workflow.js，VS Code 扩展层负责命令注册、交互入口和终端命令触发。

技术栈

• VS Code Extension API
• TypeScript
• Node.js CLI script
• pnpm
• esbuild

功能特性

• ✨ 创建开发分支: 可从最新 Release 创建关联功能分支，也可从最新 master 创建普通分支。
• 🚀 快捷合并: 一键合并代码到 Test / Release / Pre / Develop 环境。
• 🔄 代码同步: 方便地同步 Release 或 Master 分支的最新代码。
• 📦 版本管理: 支持创建新版本、发布版本（自动打 Tag）以及清理旧版本分支。
• 💻 界面友好: 提供侧边栏视图，无需记忆复杂的 Git 命令参数。
• 🧰 常用工具: 支持标准化目标项目的 Node/pnpm 声明。
• ⚙️ 配置初始化: 支持创建默认 .gc-workflow.json，已存在时不会覆盖。
• 🧭 中断恢复: 支持查看、继续和中止由 gcw 接管的发布、合并、rebase 流程。
• 🏗️ 项目脚手架: 从团队 GitLab 公共模板快速初始化独立的本地项目仓库。
• 🤖 Agent 友好: 提供 gcw CLI，支持非交互参数、dry-run、JSON 输出和稳定退出码。

使用方法

1. 点击侧边栏的 GC Workflow 图标。
2. 在 开发工作台 中选择你需要的操作（如 "创建功能分支"）。
3. 根据顶部弹出的输入框提示进行操作。

CLI

团队成员推荐通过 gcw-setup 安装到固定目录，避免 fnm 切换 Node 后普通全局 bin 消失。首次使用前先配置内部 npm registry：

npm config set @gancao-web:registry=https://web-registry.igancao.com/ --location=user
npx -p @gancao-web/gc-workflow-helper@latest gcw-setup install
gcw --help

Agent 或一次性任务可通过 pnpm dlx 调用：

pnpm dlx --package @gancao-web/gc-workflow-helper@latest gcw merge test --dry-run --json

根包名 gc-workflow-helper 保留给 VS Code 插件身份；内网 CLI npm 包发布时使用 @gancao-web/gc-workflow-helper。

常用命令示例：

gcw merge test
gcw sync release
gcw create-version YGJ05.28.00
gcw create-version YGJ05.28.00 --gray
gcw create-version-gray YGJ05.28.00
gcw create-feature YGJ05.28.00/demo
gcw create-branch feat-order-mt-20260514
gcw revert a1b2c3d4e5f6
gcw create-project admin-template demo-admin
gcw publish patch --yes
gcw publish patch --no-interactive   # 强制关闭交互，缺参数时直接报错
gcw status
gcw continue
gcw abort
gcw standardize-node-pnpm --node 20 --package-manager --validate --commit --yes
gcw init-config

CLI 默认在 TTY 环境下补充缺失的业务参数；非 TTY 环境缺少必要参数时会直接失败并返回退出码 2，需要强制关闭交互时可显式传入 --no-interactive。

standardize-node-pnpm 用于把目标项目环境声明覆盖到本次选择的标准状态：

• .nvmrc 写入推荐开发 Node 大版本，例如 20。
• package.json.engines.node 写入最低安装兼容门槛，例如 Node 20 写入 >=20，Node 14 写入 >=14.18.0。
• package.json.engines 中除 node 外的其他字段会保留。
• 选择维护 packageManager 时会覆盖为对应 pnpm 版本；选择不维护时会删除已有 packageManager 字段。
• 已存在的 .husky/commit-msg 会覆盖为 pnpm exec commitlint 标准模板；文件不存在时不会创建。
• .husky/pre-commit 已存在且 scripts["lint:lint-staged"] 不存在时，标准模板直接使用 pnpm exec lint-staged，不会新增 package script。
• scripts["lint:lint-staged"] trim 后严格等于 lint-staged 时，命令会检查根 package 的其他内容、Git tracked 文件和未忽略 untracked 文本文件；没有其他引用时删除零逻辑别名，pre-commit 改用 pnpm exec lint-staged。
• 零逻辑别名仍被其他位置引用或引用检查无法完整执行时会保留并 warning；自定义、复合或带参数的 script 也会完整保留，pre-commit 继续使用 pnpm run lint:lint-staged。缺失的 .husky/pre-commit 不会创建。
• 使用 --commit 时，dirty 工作区会先被隔离；提交白名单为 .nvmrc、根 package.json、已存在的两个 Husky hooks，以及 --validate 实际更新的根 pnpm-lock.yaml。其他产物会在 commit 前阻止流程。

这些声明语义不同：.nvmrc 表达推荐开发版本，engines.node 表达安装兼容门槛，gcw 自身运行要求由 CLI 包独立声明为 Node.js >=14.18.0。

执行确认按使用环境和风险分层：

• 人类在 TTY 终端从干净工作区执行 merge、sync、创建分支等常规写操作时直接执行；dirty merge、sync 和创建分支会先展示 autostash action plan，并通过一次确认授权保护当前工作。
• 人类在 TTY 终端执行 publish、publish-ci、delete-version、rebase、revert、checkout、push-tags、standardize-node-pnpm 等高风险操作时，命令会先补齐参数并生成 action plan，再进入中文确认；也可传 --yes 跳过确认。
• 人类 action plan 只展示当前分支和工作区状态、核心业务动作及必要的删除、覆盖、force push、版本或远端风险；单一动作不显示编号。
• TTY action plan 使用少量标题装饰、结构空行和语义颜色增强层级，dirty 显示为红色、clean 显示为绿色；设置 NO_COLOR、TERM=dumb 或重定向输出时保持无 ANSI 的纯文本。
• TTY 确认步骤按 Enter 直接执行，输入 n / no 取消，y / yes 保持兼容；其他输入不会执行并会重新提示，Ctrl+C 以标准中断状态退出。
• fetch、checkpoint、stash apply/drop 和通用冲突处理不在确认前展开；实际失败后由错误输出和 gcw status 提供当前阶段的恢复指引。
• Agent、CI、--json 或非 TTY 环境执行任何非豁免的真实写操作时必须传 --yes。
• Agent、CI、--json 或非 TTY 环境从 dirty 工作区执行 merge、rebase、sync、revert、standardize-node-pnpm --commit、create-branch 或 create-feature 时，还必须显式传 --autostash；仅传 --yes 不会自动隐藏或迁移未提交内容。
• --dry-run 只预览，不要求 --yes。
• init-config 仅在配置不存在时创建默认文件，已有文件不会覆盖，因此豁免确认。
• --json 输出采用逐行 JSON（JSON Lines）事件；命令、业务消息及 Git/npm/SSH 子进程输出都可按行解析，action plan 保留完整参数、影响、警告和恢复字段供自动化消费。
• --json-summary 输出单个最终 JSON 文档，适合 Agent 直接根据 ok、error.code、退出码和 nextActions 判断下一步；业务成功和失败均只写 stdout，stderr 为空。
• --json 与 --json-summary 互斥；所有公开命令会在副作用前拒绝未知选项和多余位置参数。
• dry-run 输出只代表计划执行的动作，不表示分支、远端、版本或 Tag 已经发生变化；支持 action plan 的命令会在 dry-run 中输出与最终确认一致的计划摘要。

普通分支创建命令：

• gcw create-branch <branchName>：先获取最新远端状态，再从 origin/master 创建分支、推送到 origin 并设置 upstream。
• dirty 工作区经授权后先 push clean 分支，再把 staged、unstaged 和 untracked 内容恢复到新分支，不自动提交或再次推送。
• 本地或远端已存在同名分支时命令失败，不自动切换到旧分支。

生产回退 Git 准备命令：

• gcw revert <commit> 只接受一个明确的十六进制 commit ID。命令先 fetch 最新 origin/master，并要求目标位于其 first-parent 主线；不会推断 MR、Tag、commit range 或多个目标。
• 单父提交（包括 squash merge 后的主线提交）执行普通 git revert；双父 merge commit 固定以 parent 1 为 mainline 执行 git revert -m 1；根提交和三个及以上父提交的 commit 会被拒绝。
• 分支名固定为 revert-<shortsha>，short SHA 至少 12 位。本地或远端存在同名分支时直接失败，不复用、覆盖、强推或生成替代名称。
• 确认后始终从已确认的最新 origin/master 创建新分支，生成 revert commit 后才首次 push，并返回执行前原分支。dirty 工作区经授权后先 autostash，用户内容不会进入 revert commit 或远端分支，返回原分支后再恢复。
• 成功后会显式输出 GitLab 新建 MR 链接，并预填 revert-<shortsha> 为源分支、master 为目标分支；命令不会自动打开页面、创建或合并 MR。
• 命令只准备并推送 revert 分支，不修改本地或远端 master，不创建 Tag，不调用 CI/CD，也不部署或验证生产。若 origin 是本地路径等无法映射为 GitLab Web 地址的形式，分支 push 仍成功，但会明确提示无法生成 MR 链接。
• revert 冲突时解决冲突并执行 git add <文件>，再运行 gcw continue。gcw abort 只删除尚未形成 commit、没有远端副作用且身份可严格证明的空本地 revert 分支；已有 commit 或已 push 的分支会保留。

从团队模板初始化项目

gcw create-project [template] [targetDir] 从内部 GitLab frontend-web/templates Group 实时读取直属、未归档的项目模板。TTY 终端可省略参数，依次选择模板并输入目录名；参数完整时也可直接执行：

# TTY 交互选择模板和目标目录
gcw create-project

# Agent 单次读取实时模板目录；只读，无需 --yes
gcw create-project --list-templates --json-summary

# 在当前目录初始化
gcw create-project admin-template demo-admin

# 在指定的现有父目录初始化
gcw --cwd ~/workspace/projects create-project uniapp-template demo-uniapp

# Agent / CI 预检与真实执行
gcw --cwd /workspace create-project admin-template demo-admin --dry-run --json
gcw --cwd /workspace create-project admin-template demo-admin --yes --json

模板目录成功时，data.templates 按 path 稳定排序，每项只承诺 path 和 description：

{
  "schemaVersion": 1,
  "ok": true,
  "command": "create-project",
  "data": {
    "templates": [
      {
        "path": "admin-template",
        "description": "后台项目公共模板"
      }
    ]
  },
  "warnings": [],
  "error": null,
  "nextActions": []
}

目录调用每次实时访问 GitLab，不使用缓存或静态清单，也不要求 template、targetDir 或 --yes。它不会检查或创建目标目录，不会 clone、修改文件或执行 Git 写操作。--list-templates 不可与模板、目标目录位置参数混用。

使用前需要准备 glab >=1.92.0，gcw 只检查环境，不会自动安装、升级或登录：

# macOS Homebrew
brew install glab
brew upgrade glab

# 登录并验证内部 GitLab
glab auth login --hostname git.igancao.com
glab auth status --hostname git.igancao.com

其他系统按 glab 官方安装说明 安装。准备或目录读取失败时，JSON 输出分别提供 GLAB_NOT_FOUND、GLAB_VERSION_UNSUPPORTED、GLAB_AUTH_REQUIRED、GITLAB_TEMPLATE_API_FAILED 或 GITLAB_TEMPLATE_EMPTY。前三类和空目录要求 Agent 请求用户处理，API 失败可重跑同一条目录命令；gcw 不读取、保存或输出 GitLab Token。

初始化规则：

• template 必须精确匹配 GitLab 项目路径名；交互列表同时展示仓库维护的中文描述。
• targetDir 必须以小写英文字母开头，可包含数字，单词间使用横线分隔，例如 demo-admin；父目录通过 --cwd 指定，目标路径必须不存在。
• 只浅克隆模板默认分支的最新内容，只把根 package.json.name 改为 targetDir；嵌套包、lockfile、README 和业务配置保持原样。
• 模板 .git 会被删除，随后以 master 重新初始化本地仓库；模板历史和 origin 不保留。
• 可捕获的后处理失败会清理本次创建的目标目录；已有路径不会被覆盖、合并或自动清理。
• gcw 不安装依赖、不执行模板脚本、不创建提交、GitLab 远端项目、MR 或推送。

完成后仍需人工检查业务标识和环境配置，按项目原流程安装依赖、创建首次提交及远端仓库。tag、branch、commit 选择和通用模板变量替换暂不提供。

合并和发布安全保护：

• merge 刷新本地环境目标分支前会检查本地独有提交；存在未推送提交时拒绝覆盖和合并。
• merge/rebase 检测到 dirty 工作区时，TTY action plan 会明确说明未提交内容不参与本次操作；确认后保存已暂存、未暂存和未跟踪内容，完成 push、切回和清理后再恢复。
• merge/rebase 发生原生冲突或 push 失败时，autostash 保持隐藏并由 checkpoint 管理；解决问题后运行 gcw continue。stash 恢复冲突时会保留 stash，解决并 git add 后再次运行 gcw continue 完成清理。
• dirty sync 在原当前分支恢复用户改动；标准化提交在原分支的新提交之后恢复；create-branch 和新建型 create-feature 在目标分支恢复。dirty create-feature 命中既有目标时会在 checkpoint/stash 前拒绝。
• publish 会获取最新远端状态并对齐本地 master；本地 master 存在独有提交时拒绝发布。
• gcw publish patch|minor|major 会在 action plan 中展示 origin/master 基线版本、目标版本、计划 Tag 和目标远端；异常恢复提示在实际失败后展示。
• publish 检测到当前工作区 dirty 时，会在用户确认后创建带 gcw 标识的 autostash；未提交内容不参与本次发布，发布完成并切回原分支后再 stash apply --index，成功后删除该 stash。
• publish-ci 仅允许在工作区干净的 master 分支执行。

CI 自动发布使用 gcw publish-ci <patch|minor|major> --yes，该命令不作为 VS Code 插件入口。

workflow 中断恢复：

• 受 checkpoint 管理的流程包括 merge、sync、rebase、revert、publish、dirty create-branch/create-feature，以及带提交的 dirty standardize-node-pnpm。
• gcw status：查看当前 worktree 是否存在未完成的 gcw workflow，同时显示原分支、用户改动恢复目标、当前步骤、已完成步骤、最近失败摘要、当前 Git operation、工作区和 stash 身份。最近失败摘要区分 conflict、operation commit 待完成、validation、commit、push 和收尾失败；失败后人工改变现场时会同时显示历史快照与当前状态差异。
• gcw continue：继续受 checkpoint 管理的流程；它会在副作用前验证分支、HEAD、Git operation、stash、commit 或远端分支身份，不自动解决冲突、不使用 --no-verify，也不会只依据最近失败类别执行副作用。
• gcw abort：停止 gcw 对当前 workflow 的接管并清理 checkpoint。revert 使用专属安全收口：未形成 commit 且无远端副作用时可删除空分支，已有 commit 或已 push 的分支会保留；其他 workflow 默认保留 autostash，不自动回滚已完成副作用。
• checkpoint 写入当前 worktree 的 Git 私有路径，不出现在 git status，也不需要加入 .gitignore。
• Git、hook 和包管理器的具体错误仍以终端原始输出为准；checkpoint 只保留稳定的步骤、类别、退出码/信号、Git operation 和未解决文件摘要，不持久化完整 stdout/stderr。没有 active checkpoint 的命令失败时不会提供 gcw continue。

版本分支创建命令：

• gcw create-version <releaseId>：创建普通版本分支，只创建 release-<releaseId>。
• gcw create-version <releaseId> --gray：创建灰度版本分支，同时创建 release-<releaseId> 和 test-<releaseId>。
• gcw create-version <releaseId> --no-gray：显式声明不创建版本化测试分支。
• gcw create-version-gray <releaseId>：灰度版本分支的可读别名，等价于 create-version <releaseId> --gray。

Agent 需要观察完整过程时使用 --json JSONL；只需要最终判断时推荐 --json-summary：

gcw status --json-summary
gcw create-version YGJ05.28.00 --dry-run --json-summary
gcw create-branch feat/order-list --dry-run --json-summary

Agent 或 CI 执行真实操作时显式授权：

gcw merge test --yes --json-summary
gcw merge test --autostash --yes --json-summary # dirty 工作区
gcw rebase master --autostash --yes --json-summary # dirty 工作区
gcw revert a1b2c3d4e5f6 --yes --json-summary # clean 工作区；成功 data.mergeRequestUrl 可直接新建 MR
gcw revert a1b2c3d4e5f6 --autostash --yes --json-summary # dirty 工作区
gcw create-branch feat/order-list --yes --json-summary
gcw sync develop --autostash --yes --json-summary # dirty 工作区
gcw create-branch feat/order-list --autostash --yes --json-summary # dirty 工作区
gcw create-feature demo --autostash --yes --json-summary # dirty 工作区
gcw standardize-node-pnpm --node 20 --package-manager --commit --autostash --yes --json-summary
gcw publish patch --yes --json-summary # publish 自行保护 dirty 内容，无需显式 --autostash

--json-summary 公共信封固定为 schemaVersion、ok、command、data、warnings、error 和 nextActions。managed workflow 中断时，data.workflow.lastFailure 提供 step、category、command、exitCode、signal、operationState、unresolvedFiles 和 occurredAt；error.message 只供人阅读，Agent 使用稳定 error.code：

merge 及其 continue 通过 data.executionReceipt 返回实际完成回执；用它总结合并、推送、切回和工作区恢复，不需要再执行 Git 探测。coreActions、remoteEffects 的既有实现从计划事件派生，干净工作区成功时可以为空，失败或 dry-run 时也可能含有未执行动作；它们和 actionPlan 都不能作为已完成证明。完整字段、部分失败示例和本地验收命令见 merge 执行回执。回执只证明 Git 命令已成功返回，不证明流水线、部署或生产验收。

error.code	含义	退出码
ARGUMENT_REQUIRED	缺少必需参数	2
CONFIRMATION_REQUIRED	真实操作缺少 --yes	2
AUTOSTASH_AUTHORIZATION_REQUIRED	dirty 自动化命令缺少 --autostash --yes	2
TARGET_BRANCH_EXISTS	确定命名的 revert 分支已在本地或远端存在	2
REVERT_EMPTY	目标在最新 master 基线上没有可提交的反向变化	1
WORKFLOW_INTERRUPTED	已执行并留下可恢复 checkpoint	1
NO_ACTIVE_WORKFLOW	continue 时没有 active workflow	2
WORKFLOW_STATE_MISMATCH	checkpoint 与 Git 现场不一致	2
UNKNOWN_OPTION	包含未识别选项	2
JSON_MODE_CONFLICT	同时使用两种 JSON 模式	2

nextActions[].action 只使用 rerun、status、continue、abort 或 request-user；非空 command 可直接执行。status 没有 active workflow 时仍成功返回 data.active: false，abort 保持幂等成功。

退出码约定：

• 0: 执行成功。
• 1: 普通执行失败，或以 WORKFLOW_INTERRUPTED 保留了可恢复 workflow。
• 2: 参数、确认、授权或 workflow 状态错误。

本地开发

pnpm install
pnpm run check-types
pnpm run lint
pnpm run build
pnpm run test:workflow
pnpm run verify:cli-delivery

项目自身版本在内网 npm、Open VSX 和 VS Code Marketplace 均发布并验证后，由 Agent 自动完成 GitLab Release 最终收口。该维护命令不属于公开 gcw CLI：

pnpm run release:finalize -- v1.5.4 --dry-run --json-summary
pnpm run release:finalize -- v1.5.4 --yes --json-summary

Agent 先审查 dry-run 中的目标 Tag、上一 Tag、分组条目、完整说明、精确版本 VSIX 的大小/SHA-256 和既有 Release/asset 状态，再自动执行带 --yes 的命令。脚本默认使用根目录的 gc-workflow-helper-<version>.vsix，也可传 --vsix <path>；它会校验包内扩展身份和版本，创建或确认 Release 后上传缺失 VSIX，并重新读取 Release 与 asset。内容一致且 asset 已存在时幂等成功，内容不同则拒绝覆盖。它不会更新版本、创建或移动 Tag、修改工作区，也不会发布其他渠道。

常用脚本：

• pnpm run build：类型检查、Lint 并生成生产构建。
• pnpm run compile：类型检查、Lint 并生成开发构建。
• pnpm run test:workflow:unit：运行工作流单元测试。
• pnpm run test:workflow:isolated：在临时仓库和本地 bare remote 中运行隔离环境 CLI 测试。
• pnpm run test:workflow:e2e：在 mutong/test-project 的临时 clone 中运行全量真实 Git 环境端到端场景，并生成 20/20 公开命令覆盖清单；日常用法、清理和证据见 CLI 真实 Git 环境端到端验收手册。
• pnpm run test:workflow：兼容入口，运行单元测试与隔离环境 CLI 测试，不访问真实 GitLab 远端。
• pnpm run test:workflow:release：依次运行单元测试、隔离环境 CLI 测试和真实 Git 环境端到端验收。
• pnpm run verify:cli-delivery：Agent 的 CLI 本地交付入口；串行完成基线预检、构建、基础测试、全量真实 E2E、临时包和发布 dry-run，并汇总证据。
• pnpm test：运行 VS Code Extension 测试。
• pnpm run package：打包 .vsix。
• pnpm run prepare:npm-package：生成 .tmp/npm-package/ CLI 内网 npm 发布包。
• pnpm run pack:npm-package：生成临时包并执行 pnpm pack --dry-run，检查包内容。
• pnpm run publish:npm-package:dry-run：生成临时包并执行发布 dry-run。
• pnpm run publish:npm-package：生成临时包并发布到内网 Verdaccio，需要发布人本机已登录。
• pnpm run test:release-finalize：运行 GitLab Release 说明生成与创建/幂等/冲突保护专项测试，不运行公开 gcw 全量 E2E。
• pnpm run release:finalize -- <tag>：仓库维护者和 Agent 使用的发布收口命令；dry-run 不写入，真实创建或补传 VSIX 必须显式传入 --yes。

维护者或 Agent 执行正式版本发布时，按 版本发布手册 完成 OpenSpec 收口、Tag、内网 npm、Open VSX 和 VS Code Marketplace 发布及验证，并由 Agent 自动创建和复核 GitLab Release。GitLab Release Notes 是版本改动说明主真源，仓库不维护独立 CHANGELOG.md。

调试扩展：

• 在 VS Code 中选择 Run Extension 后按 F5。
• 调试宿主窗口默认打开 ${workspaceFolder}/../test-project，作为人工调试用的固定 checkout。自动端到端验收不会复用该目录，而是在 .tmp/e2e-runs/ 下创建新的临时 clone。
• --extensionDevelopmentPath=${workspaceFolder} 仍指向当前插件源码；宿主工作区只作为调试沙箱。
• 调试宿主默认带 --disable-extensions，用于减少用户已安装扩展对调试过程的干扰。
• 默认编译任务使用 .nvmrc 声明的 Node 20。根 package.json.engines.node 只表达 npm 安装兼容门槛，不作为实际开发版本来源。

注意：launch.json 的工作区参数必须指向真实 Git 仓库目录。若指向空目录，git 命令会向上冒泡到上层 .git，导致脚本作用在错误的仓库。

配置文件：

• .gc-workflow.json 位于目标项目根目录。
• gitWorkflow.grayTestEnv（已废弃）：仅作为 create-version 无显式入口时的兜底默认值。推荐使用侧边栏「创建灰度版本分支」显式表达灰度意图。
• 合并目标判断规则：提测时自动检测远端 test-<releaseId> 分支是否存在，存在则合并到该分支，否则合并到共享 test。
• 侧边栏“初始化配置文件”会创建默认配置；如果文件已存在，会跳过且不覆盖。

安装

下载 .vsix 文件后，在 VS Code 扩展面板右上角选择 "Install from VSIX..." 进行安装。

CLI 安装

CLI 内网 npm 包名为 @gancao-web/gc-workflow-helper，提供 gcw、gc-workflow 和 gcw-setup。

首次使用前先配置内部 npm registry：

npm config set @gancao-web:registry=https://web-registry.igancao.com/ --location=user

推荐团队本地使用固定目录安装：

npx -p @gancao-web/gc-workflow-helper@latest gcw-setup install

团队已有 pnpm 时也可以使用：

pnpm dlx --package @gancao-web/gc-workflow-helper@latest gcw-setup install

默认行为：

• macOS/Linux 安装到 $HOME/.local，命令位于 $HOME/.local/bin。
• Windows 安装到 %LOCALAPPDATA%\Gancao\gcw，通过 npm 生成 cmd/PowerShell shim。
• setup 会检查当前会话 PATH 和持久 PATH；人工安装时会幂等写入用户级 PATH 配置。
• gcw 使用调用时 PATH 中的当前 Node，要求 Node.js >=14.18.0，不会自动切换或安装 Node。
• 安装前如果目标命令目录已有非本工具管理的同名 gcw、gc-workflow 或 gcw-setup，setup 会拒绝覆盖并提示冲突路径。
• setup 目前支持 bash/zsh 的 profile 持久 PATH 配置；fish shell 用户需要手动将固定命令目录加入 fish_user_paths 或使用 --no-configure-path。

更新到最新版本：

gcw-setup update

卸载并清理由 setup 管理的 PATH 配置：

gcw-setup uninstall

卸载只移除本 CLI 和 setup 自己管理的 PATH 片段，不递归删除固定 prefix，也不删除用户原有 PATH。Windows PATH 所有权记录在 prefix 下的 setup state 文件；状态缺失或损坏时不会自动清理 PATH。

CI 或稳定 Agent 流程应固定 bootstrap 包版本、安装版本和 Job 级 prefix，避免并行任务共享用户目录：

npx -p @gancao-web/gc-workflow-helper@1.3.2 gcw-setup install \
  --version 1.3.2 \
  --prefix "$RUNNER_TEMP/gcw" \
  --no-configure-path

setup 会输出命令目录，流水线将该目录加入当前 Job 的 PATH 后即可调用 gcw。

普通全局安装仍然可用，但生命周期跟随当前 Node 环境；在 fnm 下切换到另一个未安装该包的 Node 版本后，命令可能不可用：

npm install -g @gancao-web/gc-workflow-helper
pnpm add -g @gancao-web/gc-workflow-helper

一次性调用可以继续使用 npx 或 pnpm dlx，适合不需要持久安装的 Agent 或临时任务。

CLI 启动更新

人工 TTY 执行工作流命令前，gcw 首次或缓存过期时最多等待约 1 秒查询内网 npm 的 latest 稳定版本。已是最新版时直接执行原命令；有新版本时显示当前版本、目标版本和安装 prefix，并询问是否更新：回车或 y 更新，n 跳过并继续原命令。成功、无更新与检测失败都缓存 24 小时；有效缓存期间不查询、不提示、不询问，直接执行原功能。离线、超时、异常元数据及缓存不可写时静默继续。

确认更新后，gcw 调用自身的 gcw-setup update 安装刚检测的精确版本，不修改 PATH。标准 npm prefix 安装会更新原 prefix；源码、一次性调用或其他布局使用 setup 默认固定 prefix，确认前会显示具体目录。更新成功并核验版本后，直接使用新包运行原命令，保留参数、cwd 和自动化环境语义。更新失败则停止本次命令并明确提示原命令尚未执行；请检查安装结果后重试。业务 Git 操作在更新结束后才开始。

CI、非 TTY、--yes、--no-interactive、JSON、help/version、dry-run、status、默认 cleanup 预览及模板列表不参与启动更新交互。检测沿用 npm 的凭据与代理配置，固定查询 CLI 分发使用的内网 registry。缓存位于 macOS ~/Library/Caches/gcw/、Linux ${XDG_CACHE_HOME:-~/.cache}/gcw/ 或 Windows %LOCALAPPDATA%\gcw\。

文档

• openspec/README.md：当前系统能力地图、主规格和历史变更入口。
• docs/archive/plans/：已完成或已被替代的历史计划，仅用于追溯背景。
• AGENTS.md：Agent 修改本项目时需要遵循的项目特异约束。
• CLAUDE.md：Claude Code 的项目规则入口。

Release 基线提醒与分支收尾

gcw merge test、gcw merge pre 或对应灰度 test 在 Release 进入环境前检查是否吸收最新 master。交互默认继续原请求，也可输入 s 先同步、n 取消；非交互/--yes 默认不额外同步，JSON 的 warnings/nextActions 给出提醒。明确需要同步时使用 gcw merge pre --sync-master --yes；dirty 自动化仍需 --autostash。同步冲突沿用 gcw status、解决并 git add 后 gcw continue 或 gcw abort，不后台修改别的版本。

gcw cleanup --json-summary                        # 汇总，无删除
gcw cleanup 1.0.0 --json-summary                  # 指定版本逐对象查看
gcw cleanup --execute --branch release-1.0.0 --dry-run --json-summary
gcw cleanup --execute --branch release-1.0.0 --yes --json-summary

--execute 只选择执行动作，不是第二次确认。TTY 可选择安全候选后一次确认；非交互执行需要明确 --branch（可重复）和 --yes。普通汇总会安全 fetch 刷新对象和跟踪引用，不 checkout、不改工作文件或本地分支 tip；dry-run 不更新 refs。默认/受保护/固定共享环境/被 worktree 使用分支不列为可执行候选；可在 .gc-workflow.json 的 gitWorkflow.sharedBranches 数组声明额外共享分支。

安全证据优先采用最新 master 提交包含关系；灰度 test 的额外 merge 只在贡献提交与合并结果均可证明已在 master 历史时列为候选。该规则可能漏报；unknown/retained 的分支显示需复核理由，不代表永远不可清理。保护信息尝试使用现有 glab 身份；只有 Git 身份而不能查询时会明确说明限制，不要求 Jenkins token。

gcw delete-version <ID> 保留明确删除废弃版本的用途。未合入对象会显示独有提交和范围风险，沿用一次准确确认，不将它伪称安全候选。确认后 SHA/master/保护状态变化时保留相应对象、重新判断，远端使用 SHA lease 防止竞态；部分失败返回非零和逐项结果。cleanup 保留本地副本；delete-version 仅在远端成功且本地 SHA 没变化、没有 worktree 占用时清理本地副本。

删除 test-ID 即要求独立 Jenkins 删除事件链销毁对应灰度环境；gcw 只报告 Git 删除结果，environmentCleanup: unverified，分支已经不存在不能证明资源已清。gcw 不调用 Jenkins、SSH 或 nginx。固定 test/pre 的发布后自动同步由已有 CI 承接，本命令不配置远程 CI。

gcw 提交归因

gcw新创建的提交在正文末尾写入 GCW-Command 和 GCW-Version，标题与作者保持原语义。覆盖merge、sync、publish/publish-ci、revert及带commit的standardize-node-pnpm；continue沿用原业务命令。版本提交保留npm message模板，Tag在创建时指向带尾注的提交。普通commit hooks仍会执行。

标记只说明客户端自报的提交来源，可手工伪造或因squash丢失，不证明审批、push或部署。noop、分支操作、推送既有Tag、模板git init和rebase重放不会为统计额外创建/改写提交；无标记的历史不能断言未使用gcw。完整操作统计仍需执行回执和服务端事件。本功能不改变MR合并责任或版本发布例外的授权条件。

GCW-Command展示提交创建时已解析的可读命令，如 gcw merge test --sync-master --autostash，配合 GCW-Version: 1.5.6，总共两行。必要参数采用引号及换行转义，仅供查看，不作为可执行或可完整重放的shell命令。不含确认/展示开关、cwd或环境变量。continue沿用原业务参数；旧checkpoint无法可靠还原参数时只展示gcw与命令名。后续交互选择只影响后续新提交，不回写此前提交。npm version还会将两行写入新建annotated tag注释，保留原Tag指向。旧三字段提交不改写，Release Notes仍兼容过滤。

editor路径遇core.commentChar=G会停止并保留现场；自定义footer长度hook仍可拒绝长参数，gcw不绕过hook或截断数据。根项目发布已验；workspace子包的npm配置读取若报ENOWORKSPACES，会提示在根目录执行，不猜测message来源，子包完整发布未承诺支持。