Upstream Compare | 上游比較
讀取 custom-skills-upstream-sync 生成的結構化報告，使用 AI 生成自然語言分析與整合建議。 支援分析已註冊 repo 的更新，或評估全新 repo 的整合價值。
Quick Start
bash
# 前置作業：先執行 custom-skills-upstream-sync 生成報告 python skills/custom-skills-upstream-sync/scripts/analyze_upstream.py # 然後讓 AI 分析報告 /upstream-compare # 評估新 repo（需先用 --new-repo 生成評估報告） /upstream-compare --new-repo eval-awesome-skills-*.yaml
Workflow
模式 1：分析已註冊 repo 更新
code
┌─────────────────────────────────────────────────────────────────┐ │ Upstream Compare Workflow │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. [前置] custom-skills-upstream-sync │ │ └── 生成 upstream/reports/structured/analysis-*.yaml │ │ ↓ │ │ 2. AI 讀取結構化報告 │ │ ├── 解析 YAML 資料 │ │ ├── 理解各 repo 的變更內容 │ │ └── 評估整合建議等級 │ │ ↓ │ │ 3. AI 生成自然語言報告 │ │ ├── 執行摘要 │ │ ├── 各 repo 詳細分析 │ │ ├── 整合建議與優先級 │ │ └── 實作步驟 │ │ ↓ │ │ 4. [可選] 生成 OpenSpec proposal │ │ └── /openspec:proposal upstream-integration │ │ │ └─────────────────────────────────────────────────────────────────┘
模式 2：評估新 Repo
code
┌─────────────────────────────────────────────────────────────────┐ │ New Repo Evaluation Workflow │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. [前置] custom-skills-upstream-sync --new-repo /path/to/repo │ │ └── 生成 upstream/reports/new-repos/eval-*.yaml │ │ ↓ │ │ 2. AI 讀取評估報告 │ │ ├── 分析 repo 結構與內容 │ │ ├── 檢視 skills/agents/commands 列表 │ │ └── 評估內容品質與價值 │ │ ↓ │ │ 3. AI 生成詳細評估報告 │ │ ├── Repo 概覽 │ │ ├── 內容品質評估 │ │ ├── 與本專案的重疊/互補分析 │ │ ├── 整合建議（全部/部分/跳過） │ │ └── 推薦整合的具體項目 │ │ ↓ │ │ 4. [可選] 加入 sources.yaml 開始追蹤 │ │ └── 或建立 proposal 整合特定內容 │ │ │ └─────────────────────────────────────────────────────────────────┘
AI Analysis Guide
模式 1：分析已註冊 repo 更新
當執行 /upstream-compare 時，AI 會：
1. 讀取最新報告
yaml
# 讀取位置 upstream/reports/structured/analysis-YYYY-MM-DD.yaml
2. 分析結構
報告包含以下關鍵資訊：
| 欄位 | 說明 | 分析重點 |
|---|---|---|
recommendation | High/Medium/Low/Skip | 判斷優先級 |
reasoning | 建議原因 | 理解變更重要性 |
summary.by_type | 變更類型分布 | feat/fix 數量 |
summary.by_category | 檔案分類 | skills/agents/commands |
summary.novel_structures | 新架構偵測 | 重要！新框架/結構 |
commits | 近期 commit 列表 | 具體變更內容 |
file_changes | 檔案變更清單 | 影響範圍 |
3. 生成報告結構
markdown
# 上游整合分析報告 ## 執行摘要 - 分析了 N 個上游 repository - M 個建議優先整合（High） - K 個建議評估整合（Medium） - N 個包含新框架/架構（需特別關注） ## 詳細分析 ### [Repo Name] **整合建議**: High/Medium/Low/Skip **變更摘要**: - X 個新功能 - Y 個修復 - Z 個 skill 變更 **新架構/框架**:（若有偵測到） - [框架名稱]: [說明] - [是否採用] - [特殊模式]: [說明] - [是否採用] **重要變更**: 1. [commit subject] - [分析說明] 2. ... **整合建議**: - 建議整合原因 - 注意事項 - 實作步驟 ## 整合路線圖 ### 優先整合 (High) 1. ... ### 評估整合 (Medium) 1. ... ### 新架構採用建議 1. [框架名稱] - [採用建議與原因] ## 下一步行動 1. 建立 OpenSpec proposal 2. 執行整合 3. 更新 last-sync.yaml
模式 2：評估新 Repo
當執行 /upstream-compare --new-repo <report> 時，AI 會：
1. 讀取評估報告
yaml
# 讀取位置
upstream/reports/new-repos/eval-{repo-name}-{timestamp}.yaml
2. 分析內容
評估報告包含：
| 欄位 | 說明 | 分析重點 |
|---|---|---|
repo.name | Repo 名稱 | 識別來源 |
repo.remote_url | 遠端 URL | 確認來源可靠性 |
repo.recommendation | Evaluate/Review/Skip | 初步建議 |
repo.file_structure.skills | Skills 列表 | 核心整合目標 |
repo.file_structure.agents | Agents 列表 | 代理擴充 |
repo.file_structure.commands | Commands 列表 | 指令擴充 |
repo.recent_commits | 近期 commits | 活躍度與品質 |
repo.summary.novel_structures | 新架構偵測 | 重要！見下方說明 |
repo.overlap_analysis | 重疊偵測結果 | 重要！見下方說明 |
重疊偵測分析（重要）
報告中的 overlap_analysis（需使用 --detect-overlaps 參數）：
yaml
overlap_analysis:
# 名稱完全相同的項目
exact_matches:
- type: skills
name: tdd-workflow
local_name: tdd-workflow
similarity: 1.0
# 名稱相似的項目 (similarity > 0.7)
similar_names:
- type: skills
name: test-assistant
local_name: testing-guide
similarity: 0.85
# 功能關鍵字匹配
functional_overlaps:
- type: skills
name: testing-helper
category: tdd
local_similar: [testing-guide, tdd-workflow]
# 全新項目（無重疊）
new_items:
- type: skills
name: unique-skill
# 已在 overlaps.yaml 定義
already_defined:
- type: skills
name: commit-standards
note: 已在 overlaps.yaml 定義
# 建議的群組分類
suggested_groups:
tdd:
ecc:
- type: skills
name: testing-helper
AI 分析時必須評估：
- •完全匹配 - 這些是同名項目，需決定使用哪個版本
- •名稱相似 - 可能是功能相同但名稱不同，需比較內容
- •功能重疊 - 同類功能，需決定是否合併或選擇
- •全新項目 - 可直接整合，無衝突風險
- •建議群組 - 參考 suggested_groups 更新 overlaps.yaml
新架構/框架分析（重要）
報告中的 novel_structures 包含本專案沒有的新結構：
yaml
novel_structures:
# 新的框架/架構指標
framework_indicators:
- framework: "Claude Plugin System"
description: "支援 Claude Code Plugin 架構"
files: [...]
- framework: "OpenCode Support"
description: "支援 OpenCode 整合"
files: [...]
# 值得關注的特殊模式
notable_patterns:
- pattern: ".claude-plugin/"
description: "Claude Plugin 架構"
example_path: ".claude-plugin/plugin.json"
# 本專案沒有的新目錄
new_directories:
- name: "prompts"
example_files: [...]
# 新的檔案類型
new_file_types: [".codex", ".gitattributes"]
AI 分析時必須評估：
- •
框架指標 - 這些框架是否對本專案有價值？
- •Claude Plugin System：是否要支援作為獨立插件？
- •OpenCode Support：是否要支援 OpenCode？
- •Hook System：是否要採用其 hook 機制？
- •
特殊模式 - 這些配置/結構是否值得學習？
- •配置檔案格式（hooks.json, plugin.json）
- •腳本結構（run-hook.cmd, session-start.sh）
- •目錄組織方式
- •
新目錄結構 - 是否有值得採用的組織方式？
- •prompts/ - 是否需要獨立的 prompt 目錄？
- •examples/ - 是否需要範例目錄？
- •lib/ - 是否需要共用函式庫？
3. 生成評估報告
markdown
# 新 Repo 評估報告：[Repo Name] ## Repo 概覽 - **名稱**: [name] - **來源**: [remote_url] - **總檔案數**: [count] - **Skills 數量**: [count] - **Agents 數量**: [count] - **Commands 數量**: [count] ## 新架構/框架分析 ### 偵測到的框架 [列出 framework_indicators 並評估是否採用] | 框架 | 說明 | 建議 | |------|------|------| | Claude Plugin System | 支援作為獨立插件 | [採用/參考/跳過] | | OpenCode Support | 支援 OpenCode 整合 | [採用/參考/跳過] | | Hook System | 自動化 Hook 機制 | [採用/參考/跳過] | ### 特殊配置模式 [列出 notable_patterns 並評估] - **hooks.json**: Hook 配置檔案 - [是否採用類似設計] - **plugin.json**: Plugin 配置 - [是否需要] ### 新目錄結構 [列出 new_directories 並評估是否值得採用] - **prompts/**: Prompt 目錄 - [是否需要] - **examples/**: 範例目錄 - [是否需要] - **lib/**: 共用函式庫 - [是否需要] ## 內容品質評估 ### Skills 分析 [列出每個 skill 並簡短評估其價值] 1. **skill-name-1**: [功能描述] - [推薦/觀望/跳過] 2. **skill-name-2**: [功能描述] - [推薦/觀望/跳過] ... ### Agents 分析 [列出每個 agent 並評估] ### Commands 分析 [列出每個 command 並評估] ## 與本專案的關係 ### 重疊內容 [列出已有類似功能的項目] ### 互補內容 [列出可以補充本專案的項目] ### 衝突風險 [列出可能造成衝突的項目] ## 整合建議 **總體建議**: [全部整合 / 部分整合 / 僅參考 / 跳過] ### 推薦整合項目 #### 框架/架構 1. [framework-1] - [原因] #### Skills/Agents/Commands 1. [item-1] - [原因] 2. [item-2] - [原因] ### 不建議整合項目 1. [item-1] - [原因] ## 下一步行動 1. [具體行動項目] 2. 若決定整合： - 加入 sources.yaml 開始追蹤 - 或建立 OpenSpec proposal
Decision Criteria
已註冊 repo 更新
| 等級 | 條件 | 建議行動 |
|---|---|---|
| High | 多個新功能、重要修復、核心 skill 變更、新框架支援 | 優先整合，盡快處理 |
| Medium | 有價值的改進、文件更新、新配置模式 | 評估後決定是否整合 |
| Low | 小幅調整、維護性變更 | 可選擇性整合 |
| Skip | 無變更或僅微調 | 無需處理 |
新 repo 評估
| 等級 | 條件 | 建議行動 |
|---|---|---|
| Evaluate (高價值) | 包含新框架支援 + skills/agents/commands | 詳細評估，優先考慮 |
| Evaluate | 包含有價值的 skills/agents/commands | 詳細評估每個項目 |
| Review | 包含 hooks 或參考文件、有趣的配置模式 | 可參考部分內容 |
| Skip | 無可整合內容、無新架構 | 不適合整合 |
Install Method Awareness（重要）
分析報告時，必須先查看 upstream/sources.yaml 中每個 repo 的 install_method，
避免建議錯誤的同步方式：
| install_method | 正確的同步動作 | 常見誤判 |
|---|---|---|
plugin | claude plugin update <plugin_id> + 重啟 | 不需手動複製檔案，報告顯示 High 不代表要手動操作 |
ai-dev | ai-dev clone 已自動同步 | diff 可能已為零，僅需更新 last-sync.yaml |
standards | diff .standards/ 與上游，合併變更 | 需注意本地可能有超前版本或自訂修改 |
manual | 手動比對差異，選擇性採用 | 本專案自訂版本可能比上游更完整（如 ecc-hooks） |
分析報告撰寫時必須：
- •在每個 repo 分析段落標註其
install_method - •整合建議中說明正確的同步命令
- •對
manual類型，先比較本地 vs 上游功能完整度再建議
Analysis Priorities
整合評估時優先考慮：
- •新框架/架構 - 可能帶來全新能力（Plugin System, MCP, Hook System）
- •Skills 變更 - 直接影響 AI 行為
- •Agents 變更 - 影響子代理能力
- •Commands 變更 - 影響使用者指令
- •Hooks 變更 - 影響自動化流程
- •配置模式 - 新的配置檔案格式或目錄結構
- •Docs 變更 - 參考但通常不需整合
新架構評估指南
當發現 novel_structures 時，應評估：
| 框架類型 | 評估重點 | 整合難度 |
|---|---|---|
| Claude Plugin System | 是否要作為獨立插件發布？ | 中 |
| OpenCode Support | 是否需要支援 OpenCode 用戶？ | 低 |
| Codex Support | 是否需要支援 Codex CLI？ | 低 |
| Hook System | 現有 hook 機制是否足夠？ | 中 |
| MCP Integration | 是否需要 MCP 配置支援？ | 高 |
| Test Framework | 是否需要採用其測試結構？ | 低 |
Output Formats
1. 分析報告檔案（必須）
AI 必須將分析報告儲存至檔案：
code
upstream/reports/analysis/compare-YYYY-MM-DD.md
報告檔案包含：
- •執行摘要
- •各 repo 詳細分析
- •新框架採用建議
- •整合路線圖
- •下一步行動
執行步驟：
- •讀取結構化報告（
upstream/reports/structured/analysis-*.yaml） - •分析內容並生成 Markdown 報告
- •使用 Write 工具儲存報告檔案
- •在對話中輸出摘要並告知報告位置
2. 對話摘要
在對話中輸出精簡摘要，包含：
- •關鍵發現
- •優先行動項目
- •報告檔案位置連結
3. OpenSpec Proposal（可選）
若決定整合，生成提案：
yaml
title: "Upstream Integration: [repo-name]"
type: enhancement
priority: high|medium|low
background:
source: upstream-compare analysis
report_date: YYYY-MM-DD
changes:
- category: skills
items:
- name: skill-name
action: add|update|review
source_commit: abc1234
rationale: "..."
implementation:
- step: 1
description: "..."
- step: 2
description: "..."
risks:
- risk: "..."
mitigation: "..."
Related Commands
- •
/custom-skills-upstream-sync- 生成結構化分析報告（前置步驟） - •
/custom-skills-upstream-sync --new-repo- 評估新的本地 repo - •
/openspec:proposal- 建立整合提案 - •
ai-dev update- 拉取上游最新內容 - •
ai-dev clone- 分發 skills 到各工具目錄
References
- •Analysis Template - 報告結構範本
- •Quality Criteria - 品質評估標準