Skip to content

Multi-Agent Research Framework - 多視角並行研究,智能匯總成完整報告

License

Notifications You must be signed in to change notification settings

miles990/multi-agent-workflow

Repository files navigation

Multi-Agent Workflow

Version License Claude Code

多視角並行工作流生態系:RESEARCH → PLAN → TASKS → IMPLEMENT → REVIEW → VERIFY

Architecture

┌──────────────────────────────────────────────────────────────────────────────┐
│                      multi-agent-workflow(統一專案)                         │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                               │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐ │
│  │RESEARCH │→ │  PLAN   │→ │  TASKS  │→ │IMPLEMENT│→ │ REVIEW  │→ │ VERIFY  │ │
│  │   ✅    │  │   ✅    │  │   ✅    │  │   ✅    │  │   ✅    │  │   ✅    │ │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘ │
│       ↓            ↓            ↓            ↓            ↓            ↓      │
│  research/     plans/       tasks/       code/       reviews/    verification/│
│                                                                               │
│  ┌────────────────────────────────────────────────────────────────────────┐  │
│  │                     🔗 ORCHESTRATE(編排器)✅                          │  │
│  │               串聯所有階段,自動流轉,智能回退                          │  │
│  └────────────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────────┘

Features

  • 6 階段完整工作流:研究 → 規劃 → 任務分解 → 實作 → 審查 → 驗證
  • 多視角並行處理:每個階段 4 個視角同時工作
  • Map-Reduce 協調:並行執行 → 交叉驗證 → 智能匯總
  • Git Worktree 隔離:IMPLEMENT/REVIEW/VERIFY 在隔離分支中執行
  • 零依賴設計:只使用 Claude Code 內建工具
  • Memory 整合:成果自動存檔,支持跨階段復用
  • 共用模組架構:避免重複程式碼
  • 指標收集系統:自動追蹤執行、品質、效率指標
  • 報告系統:單次報告、週報、基準線追蹤
  • 即時進度顯示:階段和視角狀態可視化
  • 結構化錯誤處理:標準化錯誤碼和排除指南

Installation

Via Plugin Marketplace (Recommended)

# 1. 添加 Marketplace
/plugin marketplace add miles990/multi-agent-workflow

# 2. 安裝 Plugin
/plugin install multi-agent-workflow@multi-agent-workflow

# 3. 重啟 Claude Code 載入新 Plugin

Direct Install

/plugin install miles990/multi-agent-workflow

Available Skills

Skill Command Description Status
research /multi-research 多視角並行研究 ✅ Ready
plan /multi-plan 多視角規劃設計 ✅ Ready
tasks /multi-tasks 多視角任務分解(v2.2 新增) ✅ Ready
implement /multi-implement 監督式並行實作 ✅ Ready
review /multi-review 多視角程式碼審查 ✅ Ready
verify /multi-verify 多視角驗證測試 ✅ Ready
orchestrate /orchestrate 端到端編排 ✅ Ready
plugin-dev /plugin-dev Plugin 開發工作流 ✅ Ready

Quick Start

Research

# 基本用法
/multi-research AI Agent 架構設計模式

# 快速模式(2 視角)
/multi-research --quick 技術選型問題

# 深度模式(6 視角)
/multi-research --deep 重大架構決策

Plan

# 基本用法
/multi-plan 建立用戶認證系統

# 從研究報告載入
/multi-plan --from-research user-auth

Tasks (v2.2 新增)

# 從計劃載入並分解任務
/multi-tasks user-auth

# 快速模式(2 視角)
/multi-tasks --quick user-auth

# 深度模式(6 視角)
/multi-tasks --deep user-auth

# 強制 TDD 順序
/multi-tasks --tdd user-auth

Implement

# 從計劃載入
/multi-implement --from-plan user-auth

# 快速模式(2 視角)
/multi-implement --quick --from-plan small-feature

Review

# 審查指定範圍
/multi-review src/auth/

# 審查 git diff
/multi-review --diff HEAD~3

Verify

# 驗證功能
/multi-verify user-auth

# 嚴格模式
/multi-verify --strict user-auth

Full Workflow

# 端到端編排(自動判斷起始點)
/orchestrate 新增用戶認證功能

# 從已有計劃開始
/orchestrate --from-plan user-auth

Git Worktree Mode

# 自動使用 worktree(預設)
/orchestrate 新增用戶認證功能

# 強制使用 worktree
/orchestrate --worktree 新增功能

# 禁用 worktree(直接在 main 工作)
/orchestrate --no-worktree 快速修復

# 恢復中斷的工作流
/orchestrate --resume user-auth

# 清理孤立的 worktrees
/orchestrate --cleanup-worktrees

Skill Perspectives

research

ID Name Focus
architecture 架構分析師 系統結構、設計模式、可擴展性
cognitive 認知科學研究員 方法論、思維模式、認知框架
workflow 工作流設計師 執行流程、整合策略、實作步驟
industry 業界實踐研究員 現有框架、案例研究、最佳實踐

plan

ID Name Focus
architect 系統架構師 技術可行性、組件設計、擴展性
risk-analyst 風險分析師 潛在風險、依賴問題、失敗場景
estimator 估算專家 工作量評估、優先順序、時程規劃
ux-advocate UX 倡導者 使用者體驗、API 設計、開發者體驗

implement

ID Name Focus
tdd-enforcer TDD 守護者 測試先行、覆蓋率、邊界案例
performance-optimizer 效能優化師 時間複雜度、記憶體、快取
security-auditor 安全審計員 OWASP、輸入驗證、授權
maintainer 維護性專家 可讀性、文檔、重構友善

review

ID Name Focus
code-quality 程式碼品質審查員 風格一致性、重複程式碼、設計模式
test-coverage 測試覆蓋審查員 測試品質、邊界案例、Mock 適當性
documentation 文檔審查員 API 文檔、註解、README
integration 整合審查員 向後相容、API 契約、依賴影響

tasks (v2.2 新增)

ID Name Focus
dependency-analyst 依賴分析師 依賴關係、執行順序、並行機會
task-decomposer 任務分解師 實作任務、估算、驗收標準
test-planner 測試規劃師 測試任務、TDD 案例、邊界條件
risk-preventor 風險預防師 風險任務、回退點、監控任務

verify

ID Name Focus
functional-tester 功能測試員 核心功能、Happy Path、使用者流程
edge-case-hunter 邊界獵人 極端輸入、錯誤處理、容錯
regression-checker 回歸檢查員 現有功能、API 相容、向後相容
acceptance-validator 驗收驗證員 需求符合度、Definition of Done

Memory Structure

.claude/memory/
├── research/           # research skill 產出
│   └── [topic-id]/
│       ├── meta.yaml
│       ├── overview.md
│       ├── perspectives/
│       └── synthesis.md
├── plans/              # plan skill 產出
│   └── [feature-id]/
│       ├── meta.yaml
│       ├── perspectives/
│       └── implementation-plan.md
├── tasks/              # tasks skill 產出
│   └── [feature-id]/
│       ├── meta.yaml
│       ├── perspectives/
│       ├── tasks.yaml
│       └── dependency-graph.md
├── implementations/    # implement skill 產出
├── reviews/            # review skill 產出
└── verifications/      # verify skill 產出

Project Structure

multi-agent-workflow/
├── skills/
│   ├── research/                 # ✅ Ready
│   │   ├── SKILL.md
│   │   ├── 00-quickstart/
│   │   └── 01-perspectives/
│   ├── plan/                     # ✅ Ready
│   ├── tasks/                    # ✅ Ready (v2.2 新增)
│   ├── implement/                # ✅ Ready
│   ├── review/                   # ✅ Ready
│   ├── verify/                   # ✅ Ready
│   └── orchestrate/              # ✅ Ready
├── scripts/                      # 開發工具
│   ├── create-skill.sh           # Skill 腳手架工具
│   └── validate-skills.sh        # Skill 結構驗證
├── shared/                       # 共用模組
│   ├── skill-structure/          # Skill 結構規範 (v2.3 新增)
│   │   ├── STANDARD.md           # 結構規範文件
│   │   ├── CLAUDE.md             # AI 自動載入說明
│   │   └── templates/            # 模板檔案
│   ├── coordination/
│   │   ├── map-phase.md          # 並行執行
│   │   └── reduce-phase.md       # 整合匯總
│   ├── synthesis/
│   │   ├── cross-validation.md   # 交叉驗證
│   │   └── conflict-resolution.md # 矛盾解決
│   ├── perspectives/
│   │   └── base-perspective.md   # 視角基礎結構
│   ├── isolation/                # Git Worktree 隔離
│   │   ├── worktree-setup.md     # Worktree 創建
│   │   ├── worktree-completion.md # Worktree 完成
│   │   └── path-resolution.md    # 路徑解析
│   ├── integration/
│   │   ├── evolve-checkpoints.md # CP 對應
│   │   └── memory-system.md      # Memory 寫入
│   ├── metrics/                  # 指標收集
│   │   ├── schema.yaml           # 指標定義
│   │   ├── collector.md          # 收集器
│   │   └── memory-structure.md   # Memory 結構
│   ├── reporting/                # 報告系統
│   │   ├── single-report.md      # 單次報告
│   │   ├── weekly-report.md      # 週報
│   │   └── baseline.md           # 基準線
│   ├── progress/                 # 進度顯示
│   │   └── display.md            # 進度模組
│   └── errors/                   # 錯誤處理
│       ├── error-codes.md        # 錯誤碼定義
│       └── formatter.md          # 錯誤格式化
├── docs/
│   └── troubleshooting/          # 錯誤排除指南
├── templates/                    # 共用模板
├── plugin.json                   # Plugin manifest
├── .claude-plugin/marketplace.json
├── LICENSE
└── README.md

Documentation

Module Description Link
research 多視角研究
orchestrate 端到端編排
Skill Structure Skill 結構規範
Map Phase 並行執行
Reduce Phase 整合匯總
Cross Validation 交叉驗證
Conflict Resolution 矛盾解決
Perspectives 視角配置
Git Worktree Worktree 隔離
Memory System 存儲系統
Checkpoints evolve 整合
Metrics Schema 指標定義
Metrics Collector 指標收集
Single Report 單次報告
Weekly Report 週報/趨勢
Baseline 基準線機制
Progress Display 進度顯示
Error Codes 錯誤碼定義
Troubleshooting 錯誤排除指南

Development Tools

建立新 Skill

使用腳手架工具快速建立符合規範的 Skill 結構:

# 互動模式(引導式)
./scripts/create-skill.sh

# 非互動模式(CI/自動化)
./scripts/create-skill.sh --non-interactive \
  --name my-skill \
  --desc "Skill 描述" \
  --version 1.0.0

產生的結構:

skills/my-skill/
├── SKILL.md                    # 主要定義檔(frontmatter)
├── 00-quickstart/
│   └── _base/usage.md          # 快速開始指南
└── 01-perspectives/
    └── _base/default-perspectives.md  # 視角定義

驗證 Skill 結構

使用驗證工具確保所有 Skills 符合標準:

# 驗證所有 Skills
./scripts/validate-skills.sh

# 驗證單一 Skill
./scripts/validate-skills.sh research

# CI 模式(嚴格,有退出碼)
./scripts/validate-skills.sh --ci

驗證項目:

  • SKILL.md 存在且 frontmatter 完整(name, description, version)
  • 00-quickstart/_base/usage.md 存在
  • 01-perspectives/_base/default-perspectives.md 存在

詳細規範請參考 Skill 結構標準

查詢視角定義

查詢集中管理的視角定義:

# 列出所有視角
./scripts/list-perspectives.sh

# 按類別過濾
./scripts/list-perspectives.sh --category plan

# 按 skill 過濾
./scripts/list-perspectives.sh --skill implement

# 顯示視角詳細資訊
./scripts/list-perspectives.sh --show tdd-enforcer

# 顯示預設組合
./scripts/list-perspectives.sh --preset standard

查詢配置索引

查詢集中管理的配置索引:

# 列出所有配置類別
./scripts/get-config.sh --list-categories

# 列出某類別的配置
./scripts/get-config.sh --category skill-config

# 搜尋配置
./scripts/get-config.sh --search "tdd"

# 顯示配置詳情
./scripts/get-config.sh --show skills/implement/SKILL.md

# 顯示配置間的引用關係
./scripts/get-config.sh --relations

For Plugin Developers

Development Setup

# Clone repository
git clone https://github.com/miles990/multi-agent-workflow.git
cd multi-agent-workflow

# Start development mode (hot-reload)
/plugin-dev watch
# Or: ./scripts/plugin/dev-watch.sh

Development Workflow (using /plugin-dev Skill)

# 1. Sync to Claude Code cache
/plugin-dev sync

# 2. Validate structure
/plugin-dev validate

# 3. Check status
/plugin-dev status

# 4. Start watch mode (auto-sync on file changes)
/plugin-dev watch

Release Workflow

# 1. Dry-run to preview
/plugin-dev release patch --dry-run

# 2. Release
/plugin-dev release patch   # Bug fixes
/plugin-dev release minor   # New features
/plugin-dev release major   # Breaking changes

# 3. Resume from interruption
/plugin-dev release --resume

Version Management

# Show current version
/plugin-dev version

# Bump version
/plugin-dev version bump patch

# Check consistency
/plugin-dev version check

Shell Scripts (Fallback)

# Sync
./scripts/plugin/sync-to-cache.sh

# Watch
./scripts/plugin/dev-watch.sh

# Release
./scripts/plugin/publish.sh patch

Testing

# Run all plugin tests
python -m pytest tests/plugin/ -v

# With coverage
python -m pytest tests/plugin/ --cov=cli/plugin

Project Structure

skills/plugin-dev/    # /plugin-dev Skill
├── SKILL.md          # Main definition
├── 00-quickstart/    # Quick start guide
├── 01-commands/      # Command documentation
└── config/           # Command config

cli/plugin/           # Python CLI modules
├── __main__.py       # CLI entry point
├── cache.py          # CacheManager
├── version.py        # VersionManager
├── dev.py            # DevCommands
└── release.py        # ReleaseCommands

scripts/plugin/       # Shell scripts
├── sync-to-cache.sh
├── dev-watch.sh
├── validate-plugin.sh
├── bump-version.sh
├── generate-changelog.sh
└── publish.sh

shared/plugin/        # Configuration
├── config.yaml
├── cache-policy.yaml
└── version-strategy.yaml

tests/plugin/         # Tests (73 tests)

Core Design Principles

Principle Description
Zero Dependencies 只使用 Task API + 內建工具,無外部 MCP 依賴
Multi-Perspective Map-Reduce 模式,4 視角同時工作
Cross Validation 共識識別 + 矛盾解決
Git Worktree Isolation main 穩定,feature 在隔離分支開發
Memory Integration 與 evolve Checkpoint 對應
Shared Modules shared/ 避免重複程式碼
Unified Entry 單一 plugin,7 個 skill
Standard Structure 所有 Skill 遵循統一結構規範

Related Projects

Changelog

v2.5.0 (2026-02-01)

  • plugin-dev Skill
    • 新增 /plugin-dev Skill:統一的 Plugin 開發工作流入口
    • 命令:sync, watch, validate, status, version, release
    • 統一 CLI 入口:python -m cli.plugin <command>
    • Skill + Python CLI 雙層架構(可測試、可 fallback)
    • Dogfooding:用 plugin-dev 開發 plugin-dev

v2.4.0 (2026-02-01)

  • Plugin 開發工作流系統
    • 新增 cli/plugin/ 模組:CacheManager, VersionManager, DevCommands, ReleaseCommands
    • 新增 scripts/plugin/ 腳本:sync-to-cache, dev-watch, validate, bump-version, changelog, publish
    • 新增 shared/plugin/ 配置:config.yaml, cache-policy.yaml, version-strategy.yaml
    • 熱載入開發模式(fswatch/inotifywait/polling)
    • 增量同步(Hash-based)
    • 語義化版本管理
    • 自動變更日誌生成
    • 一鍵發布流程
    • 73 個測試覆蓋

v2.3.2 (2026-02-01)

  • Git 操作統一模組
    • 新增 scripts/git_lib/ 模組,統一所有 Git 操作
    • 消除重複代碼(_get_current_workflow_id() 等 65 行重複)
    • 實作 Facade Pattern,簡化 Hook 開發
    • 55 個單元測試,覆蓋率 80%+
    • Hook 代碼減少 54%

v2.3.0 (2026-02-01)

  • Skill 結構規範化
    • 新增 shared/skill-structure/STANDARD.md 定義標準結構
    • 新增 scripts/create-skill.sh 腳手架工具(互動/非互動模式)
    • 新增 scripts/validate-skills.sh 驗證工具(含 CI 模式)
    • 統一所有 Skill 目錄結構

v2.2.0 (2026-01-25)

  • 新增 TASKS 階段(在 PLAN 和 IMPLEMENT 之間)
    • 4 視角任務分解:dependency-analyst, task-decomposer, test-planner, risk-preventor
    • tasks.yaml 結構化任務輸出
    • DAG 依賴分析和 Wave 分組
    • TDD 順序支持
  • 更新 ORCHESTRATE 支持 TASKS 階段
  • 工作流更新為 6 階段:RESEARCH → PLAN → TASKS → IMPLEMENT → REVIEW → VERIFY

v2.1.0 (2026-01-24)

  • 新增指標收集系統(Phase 1)
    • metrics schema 定義執行、品質、效率指標
    • metrics collector 標準化收集 API
    • 各 SKILL.md 嵌入指標收集點
  • 新增報告系統(Phase 2)
    • 單次執行報告:詳細分析和改善建議
    • 週報/趨勢報告:長期追蹤和趨勢分析
    • 基準線機制:滾動平均和目標管理
  • 新增進度和錯誤處理(Phase 3)
    • 即時進度顯示:階段和視角狀態可視化
    • 標準化錯誤碼:E-AGT, E-WKF, E-MEM, E-USR, E-GIT, E-ENV
    • 結構化錯誤訊息:可能原因 + 建議步驟
    • Troubleshooting 文檔:詳細錯誤排除指南

v2.0.0 (2025-01-24)

  • 重組專案為 multi-agent-workflow
  • 提取共用模組到 shared/
  • 更新 research skill 至 v2.0.0
  • 新增 plan skill:多視角規劃設計
  • 新增 implement skill:監督式並行實作(獨特設計)
  • 新增 review skill:多視角程式碼審查
  • 新增 verify skill:多視角驗證測試 + pass@k 機制
  • 新增 orchestrate skill:端到端編排 + 智能回退

v1.0.0 (2025-01-23)

  • 初始版本:multi-agent-research-skill

License

MIT

Author

miles990GitHub

About

Multi-Agent Research Framework - 多視角並行研究,智能匯總成完整報告

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Contributors 2

  •  
  •