Workflow Update

workflow-update — 检查与更新插件

先判安装形态，再查版本。 插件有两条分发渠道，版本真值不是同一个：宿主托管安装（Claude Code marketplace）认公开仓的 plugin.json，手动安装（Codex / 官网脚本）认官网 version.json。两条渠道的发布节奏可以脱节，拿另一条渠道的版本号判自己，会得出「已是最新」甚至反向降级的错误结论。

1. 判断安装形态

看本技能所在路径，按下面的顺序判，先命中先算：

0. 源码态 —— 向上两级既是插件根、又带 .git 或 tests/（你在开发这个插件本身，不是在用它）→ 提示无需更新，结束。源码态归 git 管，不归本技能；这一条必须先判，否则插件仓库自己的工作副本会被下面的清单特征误判成宿主托管。

A. 宿主托管安装 —— 技能路径在 ~/.claude/plugins/cache 或其他客户端的插件缓存下 → 走第 2 节。 没有缓存路径特征、但向上两级是插件根（存在 plugin.json 或 .claude-plugin/plugin.json），且不在 B 列出的手动安装目录里，同样按 A 处理。

B. 手动安装 —— 技能目录直接落在 ~/.codex/skills、.agents/skills 或 ~/.claude/skills 下 → 走第 3 节。B 的路径特征优先于 A 的清单特征：项目里恰好放着一份 plugin.json，不改变这是手动安装的事实。

2. 宿主托管：交给宿主更新

这条路不读 version.json。 那份清单只服务手动安装渠道，可能滞后于 marketplace 发布；宿主托管的版本真值是 marketplace 公开仓里的 plugin.json，由宿主自己拉取比对。用官网清单判宿主托管安装，最常见的结果是误报「已是最新」，用户永远升不上去。

本技能不自改插件目录——宿主管理的目录由宿主维护，绕过它手改会造成状态不一致。改为提示用户走宿主自己的机制：

• Claude Code：先刷新 marketplace，再更新插件。

claude plugin marketplace update workflow-plugin
claude plugin update workflow@workflow-plugin --scope user

也可以用 /plugin 界面，或等 marketplace autoUpdate 自己生效。更新后必须重启会话才加载新版本——不提醒的话用户会以为没升成功。

• 其他 Agent Plugins 客户端：用各自的安装器重装（例如 npx plugins add 那条路径）。

收尾读 claude plugin list（或宿主对应的列表命令）确认版本已变，向用户报告新旧版本号。

3. 手动安装：比对官网版本

读本技能目录下的 VERSION 文件（安装包内由构建器生成，纯文本一行版本号）。

• 没有 VERSION 文件 = 你运行的是源码态（开发仓里直接用），提示无需更新，结束。

抓取：

https://workflow.games/plugin/version.json?cb=

必须带 cb 参数（当前时间戳）绕 CDN 缓存，否则可能拿到旧版本误判「已最新」。返回含 version、notes（更新说明）与 files（文件清单地址）。

按语义化版本逐段比大小，不做字符串相等判断（0.10.0 > 0.9.0，字符串比较会判反）：

• 线上 == 本地 → 报告「已是最新（）」，结束。
• 线上 **** 本地 → 才进入第 4 节。

4. 自更新流程（仅手动安装）

手动安装走插件自带的安装器，不要在技能扫描目录里改名备份。先判渠道（本节只服务手动安装；宿主托管见第 2 节），不要拿另一渠道的版本号决定升/降。

node /tools/workflow-install.mjs --from-dir 
# 官网（默认 --mode full）：
node /tools/workflow-install.mjs
# 兼容性诊断（只打印，不删 ADR / 历史计划）：
node /tools/workflow-install.mjs --doctor

1. 抓取 version.json 的 files 指向的文件清单（同样加 cb 参数）。full 要的是运行时清单；旧 files.json 只有技能 Markdown → 失败并说明缺运行时，不得标已完整安装。
2. 安装器下到临时目录（不直接写目标），逐一校验 sha256：任何一个不符 → 立即中止并报告，不落盘任何文件。
3. full（默认）：可执行文件必须命中 runtime-manifest.json 的 executableGlobs（清单内 .mjs / .sh），且 sha256 一致；不在白名单的可执行文件仍中止。
4. skills：仍只允许 .md 与 VERSION；清单里出现可执行文件 → 立即中止并告警。结束时打印能力边界（无规则/工具/reviewer）。
5. 备份落到 $XDG_DATA_HOME/workflow/backups/（不进 ~/.codex/skills）。扫描根里已有的 *.bak-* 迁到 backups。
6. 完整树换根到 $XDG_DATA_HOME/workflow/plugin，技能目录改为指向运行时的受管 symlink。
7. 读新 VERSION 确认版本已变，向用户转述 version.json 的 notes。

--doctor 即兼容性诊断：缺资源、断链、同名技能、入口/reviewer 缺失、lint 扩展 api≠1。默认只打印，不删 ADR / 历史计划。

安全边界

• 只从 workflow.games 域下载（或本地 --from-dir）。清单里出现任何其他域的地址 → 中止并告警。
• 技能渠道（--mode skills / 旧包）只应包含 .md 与 VERSION 纯文本。清单或下载内容里发现可执行文件（.sh、二进制等）→ 立即中止并告警，不安装。
• 完整运行时（--mode full）允许清单白名单内的 .mjs；不在 executableGlobs 里的可执行文件仍中止、不落盘。
• 宿主托管形态（第 2 节）不下载任何文件——它只调用宿主自己的命令，下载与落盘都由宿主负责。
• 更新绝不触碰 ~/.config/workflow/config.toml——凭证与插件更新无关；同样不得覆盖或删除

项目的 .workflow-policy、.workflow-drafts/（包括未完成的本地 bundle）。更新插件后若发现 草稿协议 schema 需要迁移，先备份并由 workflow-upload 按 checkpoint 迁移，不能静默丢弃草稿。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: LumioGames
• Source: LumioGames/workflow-plugin
• License: MIT
• Homepage: https://workflow.games

Install and usage instructions live in the source repository linked above.