upstream-check

name	upstream-check
description	检查 Claude Code / Codex 上游版本变更，对比本地版本，识别协议/工具/用法相关更新并追加 TODO 提醒
version	1.0.0
author	https://github.com/BenedictKing/ccx/
allowed-tools	Bash, Read, Write, Edit
context	fork

上游版本检查技能

当用户输入包含以下关键词时，自动触发上游版本检查流程：

触发条件

• "检查上游版本"、"上游检查"、"检查更新"、"upstream check"、"check upstream"

执行步骤

1. 运行检查脚本

bash .claude/skills/upstream-check/scripts/upstream-check.sh

2. 读取当前状态

cat .claude/skills/upstream-check/scripts/upstream-state.json

3. AI 判断协议变更

重要：脚本的关键词匹配（matched_keywords）仅作为初步筛选，存在误报风险（如 "system clipboard" 误报为 system 协议变更）。

必须通过 AI 二次判断：

1. 读取脚本输出的 release_body_snippet（前 800 字符）
2. 如果 matched_keywords 非空，分析每个关键词的上下文：
   • 是否涉及协议格式变更（如消息结构、字段定义、请求/响应格式）
   • 是否涉及新工具/能力引入（如新的 API 端点、工具类型、功能模块）
   • 是否涉及核心用法变化（如参数行为调整、默认值改变、废弃警告）
3. 排除以下情况的误报：
   • Bug 修复中的偶然关键词（如 "system clipboard"、"session's model"）
   • UI/UX 改进（如 "environment variables" 在设置说明中）
   • 性能优化、日志调整、错误提示改进
4. 输出最终判断：真实协议变更 或 误报（仅 bug 修复/体验改进）

判断标准：

• ✅ 真实变更：影响 CCX 代理层协议转换、请求构造、响应解析的变更
• ❌ 误报：仅影响 Claude Code/Codex 客户端内部行为，不影响 API 协议的变更

4. 升级建议逻辑

条件	输出
up_to_date: true 且 protocol_changes: false	"✅ 已是最新版本，无需关注。"
up_to_date: true 且 protocol_changes: true	"✅ 版本已是最新。以下版本发布说明涉及协议/工具/用法变更，值得阅读了解：[关键字列表]"
up_to_date: false 且 protocol_changes: false	"⬆️ 有新版本 [remote_version] 可用（本地: [local_version]）。非紧急，可在方便时升级。"
up_to_date: false 且 protocol_changes: true	"⬆️ 有新版本 [remote_version] 可用（本地: [local_version]），涉及协议/工具/用法变更：[关键字列表]。建议关注并评估对 ccx 的影响。"

5. 更新 TODO.md

仅当 AI 判断为"真实协议变更"且远程 tag 不在 seen_tags 中时，追加 TODO 条目。

去重检查（必须）：

1. 读取 .claude/skills/upstream-check/scripts/upstream-state.json，检查远程 tag 是否已在 seen_tags 中
2. 如已在，跳过 TODO 追加
3. 追加后，将 tag 加入 seen_tags（上限 5 条，超出时删除最早的）

TODO.md 更新：

• 检查 TODO.md 是否已有 --- 分隔线 + > 上游版本变更 引用块标题，如无则追加
• 追加格式必须遵循仓库 TODO 规范：每个待办项前面都要有 [ ]
• 待办项统一使用 ## [ ] 二级标题，与 TODO.md 其他条目保持一致
• 分组标识使用分隔线 + 引用块，不使用 ## 标题，避免与待办项层级冲突
• 推荐追加格式：

---

> **上游版本变更**

## [ ] Claude Code vX.Y.Z 上游协议/工具变更评估

发现协议/工具/用法变更：keyword1, keyword2。请评估对 ccx Messages 渠道的影响。

## [ ] Codex rust-vX.Y.Z 上游协议/工具变更评估

发现协议/工具/用法变更：keyword1, keyword2。请评估对 ccx Responses 渠道的影响。

6. 更新状态文件

将新的远程 tag 追加到 .claude/skills/upstream-check/scripts/upstream-state.json 的 seen_tags 数组中：

{
  "last_checked_at": "2026-06-07T12:00:00Z",
  "claude_code": {
    "remote_tag": "v2.1.168",
    "local_version": "2.1.168",
    "seen_tags": ["v2.1.168"]
  },
  "codex": {
    "remote_tag": "rust-v0.137.0",
    "local_version": "0.137.0",
    "seen_tags": ["rust-v0.137.0"]
  }
}

7. 输出摘要报告

格式示例：

📋 上游版本检查结果

## Claude Code
- 本地版本: 2.1.168
- 远程版本: 2.1.168
- 状态: ✅ 已是最新
- 协议/工具变更: 无

## Codex
- 本地版本: 0.137.0
- 远程版本: 0.138.0
- 状态: ⬆️ 有新版本可用
- 协议/工具变更: 发现变更 - multi-agent, skills, plugins, web search

重要：协议/工具变更字段的逻辑：

• 仅当 up_to_date: false 且 AI 判断为"真实协议变更"时，显示"发现变更 - [变更要点简述]"
• 其他情况（版本一致、无关键词匹配或 AI 判断为误报），显示"无"

8. 输出功能与体验变更报告

在摘要报告之后，追加一份面向用户的功能与体验变更报告：

1. 通过 gh release view 获取本地版本到最新远程版本之间所有中间版本的 Release Notes
2. 从每个版本的 Release Notes 中筛选新增功能（New Features）和体验改进（Improvements / 性能优化 / UX 修复等）
3. 按 Claude Code / Codex 分类，以表格和列表结构化呈现
4. 末尾附「对 CCX 的潜在影响要点」，关联到 CCX 五类渠道（Messages / Chat / Responses / Gemini / Images）
5. 语调：技术导向但易读，面向开发者

仅当存在版本差异（up_to_date: false）时才生成此报告；版本一致时跳过。

说明

• 脚本只输出 JSON 到 stdout，不写磁盘
• 状态持久化由 skill 负责
• 脚本网络失败时（exit 1），不更新状态，仅输出错误
• matched_keywords 仅作为初步筛选，最终是否为协议变更由 AI 判断
• AI 判断时需排除 bug 修复、UI 改进中的偶然关键词匹配（如 "system clipboard"、"session's model"）