fix(update): 先判安装形态再查版本——宿主托管不再被官网 version.json 误导 (0.6.1) - #6
Merged
Conversation
插件两条分发渠道的版本真值不是同一个：宿主托管（Claude Code marketplace） 认公开仓 plugin.json，手动安装（Codex / 官网脚本）认官网 version.json。 旧正文让所有形态先读 version.json 再分流，官网清单一旦滞后于 marketplace 发布，宿主托管用户就拿到「已是最新」的反向结论、永远升不上去。 2026-08-29 实测：官网停在 0.3.0，marketplace 已发 0.6.0。 - workflow-update 分流升为第 1 节；宿主托管明确不读 version.json，改走 claude plugin marketplace update + claude plugin update，并提醒需重启会话 - 手动安装分支保留 cb 绕缓存、语义化逐段比较与「线上 < 本地 绝不更新」红线 - 安全边界补：宿主托管形态不下载任何文件 - /workflow:update 命令描述与 README 中英更新表同步新次序 - 新增 workflow-update 契约测试 16 项，核心是分流先于抓取 version.json 的次序断言 - 版本五方一致升到 0.6.1 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Reviewer's Guide本 PR 修复了宿主托管安装使用滞后官网 version.json 判定更新状态的问题：更新技能、命令入口和文档均改为先判安装形态，再使用 marketplace 或官网渠道的正确更新机制，并通过 16 项契约测试锁定流程顺序、安全边界和防降级行为；版本统一升至 0.6.1。 Sequence diagram for host-managed plugin updatessequenceDiagram
actor User
participant Skill as workflow-update
participant Claude as Claude_Code
participant Marketplace as Marketplace
User->>Skill: Run /workflow:update
Skill->>Skill: Determine host-managed installation
Skill->>User: Show claude plugin marketplace update workflow-plugin
User->>Claude: claude plugin marketplace update workflow-plugin
Claude->>Marketplace: Refresh marketplace metadata
User->>Claude: claude plugin update workflow@workflow-plugin --scope user
Claude->>Marketplace: Update managed plugin
Skill->>User: Restart session before using new version
Sequence diagram for manual plugin version checkssequenceDiagram
actor User
participant Skill as workflow-update
participant Local as Local installation
participant Website as workflow.games
User->>Skill: Run /workflow:update
Skill->>Skill: Determine manual installation
Skill->>Local: Read VERSION
Skill->>Website: Fetch version.json?cb=epoch
Website-->>Skill: Published version
Skill->>Skill: Compare semantic versions
alt Online version equals local
Skill->>User: Report already latest
else Online version is lower
Skill->>User: Report lag, never downgrade
else Online version is higher
Skill->>Website: Download and verify update files
Skill->>Local: Install verified update
end
Flow diagram for installation-aware plugin updatesflowchart TD
A[Start workflow-update] --> B{Determine installation type}
B -->|Host-managed| C[Use host update mechanism]
C --> D[Refresh marketplace]
D --> E[Update plugin]
E --> F[Restart session]
B -->|Manual| G[Read local VERSION]
G --> H[Fetch version.json?cb=epoch]
H --> I{Compare semantic versions}
I -->|Equal| J[Report already latest]
I -->|Online lower| K[Stop; never downgrade]
I -->|Online higher| L[Verify and self-update]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 1 issue
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="skills/workflow-update/SKILL.md" line_range="14-16" />
<code_context>
+
+看**本技能所在路径**：
+
+**A. 宿主托管安装** —— 路径在 `~/.claude/plugins/cache` 或其他客户端的插件缓存下；或从本技能目录向上两级即为插件根，其中存在 `plugin.json` 或 `.claude-plugin/plugin.json` → 走**第 2 节**。
+
+**B. 手动安装** —— 技能目录直接落在 `~/.codex/skills`、`.agents/skills` 或 `~/.claude/skills` 下，同级没有插件清单 → 走**第 3 节**。
+
+## 2. 宿主托管：交给宿主更新
</code_context>
<issue_to_address>
**issue (bug_risk):** 手动安装到项目级 `.agents/skills`、`.claude/skills` 或源码仓库时，如果项目根目录包含 `plugin.json` 或 `.claude-plugin/plugin.json`，该规则会把它误判为宿主托管安装，因为“插件根存在清单”的条件使用了无条件的“或”。流程因此跳过本地 `VERSION`/官网版本检查，改为执行 Claude Code 宿主命令；仓库自身就是这种路径结构的例子。
**Triggers:** 当手动安装目录位于一个本身包含插件清单的项目或源码仓库中。
**Suggested fix:** 不要仅凭两级祖先存在插件清单判定宿主托管；应优先要求真实的宿主缓存路径或可靠的安装元数据，并让明确的手动安装路径优先走手动分支。
```suggestion
**A. 宿主托管安装** —— 明确位于 `~/.claude/plugins/cache` 或其他客户端的插件缓存下，或有可靠的安装元数据明确表明由宿主托管 → 走**第 2 节**。
**B. 手动安装** —— 技能目录直接落在 `~/.codex/skills`、`.agents/skills` 或 `~/.claude/skills` 下时，优先走**第 3 节**；不要因上两级存在 `plugin.json` 或 `.claude-plugin/plugin.json` 改判为宿主托管。
```
</issue_to_address>Sourcery assessment
Needs a human reviewer. 1 finding to address first, and 如果安装形态判定或宿主更新命令写错，用户可能更新到错误版本、无法更新，或让宿主插件目录与预期状态不一致；已经安装的版本不会因回滚本 PR 自动恢复，但可通过宿主或手动重装修复。.
Blocking findings: skills/workflow-update/SKILL.md:16
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Sourcery 在 PR #6 指出:手动安装到项目级目录、而项目根恰好带 plugin.json 时, 「向上两级是插件根」这条无条件的或会把它误判成宿主托管。插件仓库自己的工作副本 就是这种结构——技能目录向上两级就是仓库根,那里有 plugin.json 与 .claude-plugin/plugin.json。这条歧义旧正文就有,但分流提前之后不再被后面的 VERSION / 版本比对兜住,咬得更早。 - 分流改为三条按序判定、先命中先算:源码态 → 宿主托管 → 手动安装 - 新增源码态判定(向上两级既是插件根、又带 .git 或 tests/),开发者不再被指去跑宿主命令 - A 的清单特征显式让位:不在 B 列出的手动安装目录里才按 A 处理 - 契约测试补 2 项(共 18):三条判定的先后次序、B 优先于 A 的让位声明 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
问题
插件两条分发渠道的版本真值不是同一个：
plugin.jsonversion.jsonworkflow-update旧正文让所有形态先读version.json再分流。官网清单一旦滞后于 marketplace 发布，宿主托管用户就会拿到「已是最新」的反向结论，永远升不上去。2026-08-29 实测正是如此：官网
version.json停在 0.3.0，marketplace 已发 0.6.0。本地 0.5.0 的 Claude Code 用户跑/workflow:update，会命中「线上 < 本地」分支——技能虽然正确拦住了降级，但结论是「线上发布滞后」，用户因此放弃升级。改了什么
workflow-update改为「先判安装形态，再查版本」：version.json，并写明官网清单可能滞后的原因；改走宿主自己的机制，给出claude plugin marketplace update+claude plugin update两条命令，并提醒更新后需重启会话cb绕 CDN 缓存、语义化逐段比较、以及「线上 < 本地 → 绝不更新」的降级红线/workflow:update命令描述与 README 中英更新表同步新次序（原表只给了/plugin界面与 autoUpdate，非交互终端里两者都用不了）。测试
新增
tests/workflow-update-contract.test.mjs（16 项）。核心是次序断言——分流段落必须出现在抓取version.json?cb=之前，这是本次回归的根因守卫。其余覆盖：开篇声明两条渠道版本真值不同、两个分支的路径判定特征、宿主托管分支的五要素（不读 version.json / 说明滞后原因 / 宿主命令 / 重启提醒 / 不自改插件目录）、手动安装分支的cb与三分支比较与降级红线、安全边界四条、命令入口与技能同次序。全量 107 项通过（原 91 + 新 16）。
版本五方一致升到 0.6.1。
🤖 Generated with Claude Code
Summary by Sourcery
修正插件更新流程，使不同安装渠道使用正确的版本来源和更新机制，避免宿主托管安装被官网版本清单误导。
Bug Fixes:
Enhancements:
Documentation:
Tests:
Chores: