🎯 PDCA - AI 驅動的多代理開發系統 ⚡ Token 優化版

✨ 特色

🔥 v3.2.0 Token 優化功能

• ⚡ Token 使用減少 70%+ - AI 多代理成本優化
• 💰 智能成本控制 - 實時預算監控、80% 警告、超支阻斷
• 📊 精確計量追蹤 - 真實 token 計算、按代理分組統計
• 🧠 智能早停機制 - 5層成本效益分析，自動找到最佳停止點
• 🎨 Prompt 壓縮技術 - 角色定位簡化、執行步驟優化
• 📈 成本效益分析 - 品質/美元比率、改進率趨勢監控

🤖 核心功能

• 🤖 多 AI 引擎支援 - 自動檢測並使用 Claude CLI、Gemini CLI、OpenAI CLI
• 🔄 真正的並行處理 - 5 個獨立 AI 實例同時工作
• 🎯 PDCA 方法論 - Plan → Do → Check → Act 循環改進
• 📊 即時監控 - 視覺化追蹤所有代理狀態和成本
• 🔧 一鍵安裝 - 自動處理所有依賴和配置
• 🌐 跨平台支援 - macOS、Linux、WSL

🚀 快速開始

一行安裝

npm install -g pdca

🎯 Token 優化使用指南

# 🔥 使用優化配置（推薦）- Token 使用減少 70%
pdca "實作使用者登入功能" --profile shokunin-optimized

# 💰 啟用成本追蹤
pdca "優化資料庫查詢" --show-cost

# 🎛️ 自定義預算控制
pdca "建立 API 服務" --token-budget 20000 --quality-target 0.85

# 📊 查看詳細成本報告
pdca status

📈 成本效益對比

| 模式 | Token 使用 | 預估成本 | 適用場景 | |------|-----------|----------|----------| | 經濟模式 | 5K-15K | $0.50-1.50 | 快速原型、簡單任務 | | 平衡模式 | 15K-30K | $3-8 | 一般開發、中等複雜度 | | 品質模式 | 30K-50K | $8-15 | 重要專案、高品質要求 | | 傳統模式 | 50K-100K+ | $15-30+ | 無優化（不推薦）|

🚀 基本使用

# CLI 直接啟動
pdca "實作使用者登入功能"

# 在 Claude Code 中使用斜線指令（僅 Claude CLI）
claude
> /pdca:start

# 查看系統狀態和成本統計
pdca status

# 指定 AI 引擎
pdca "任務描述" --engine gemini

📖 目錄

• Token 優化技術詳解
• 系統架構
• 安裝指南
• 使用說明
• AI 引擎支援
• 配置選項
• 常見問題
• 貢獻指南

💰 Token 優化技術

v3.2.0 新增了 Token 使用量優化功能，透過三個主要改進減少不必要的成本：

實際 Token 計量

之前的版本使用簡化估算（text.length / 4），誤差較大。現在使用 tokenx 庫提供更精確的計算：

// 新的實作
import { estimateTokenCount } from 'tokenx';

class RealTokenTracker {
  estimateTokens(text: string, model: AIModel): number {
    return estimateTokenCount(text, model);
  }
}

功能包括：

• 實時 token 使用量追蹤
• 預算警告（可設定警告百分比）
• 按代理分組的使用統計

Prompt 壓縮

重新設計代理的初始 prompt，移除冗餘描述：

# 修改前
role_intro: |
  你是一位資深的軟體架構師和全端開發者，擁有超過 10 年的豐富經驗...
  (約 200 tokens)

# 修改後  
role_intro: |
  Plan Agent (職人思維) - 需求分析、架構設計、技術選型專家
  (約 15 tokens)

智能早停機制

新增成本效益分析，避免無效的迭代：

analyzeCostEfficiency(quality: number, improvements: string[]): Decision {
  // 檢查預算使用率
  if (budgetUsage > 85%) return { stop: true, reason: '預算接近上限' };
  
  // 檢查改進率
  if (improvementRate < 0.05) return { stop: true, reason: '改進幅度過小' };
  
  // 檢查品質是否已達標
  if (quality >= 8.5 && totalCost > 5.0) return { stop: true, reason: '品質已足夠' };
}

使用方式

# 啟用成本追蹤
pdca "建立登入系統" --show-cost --token-budget 30000

# 使用優化配置
pdca "任務描述" --profile shokunin-optimized

# 設定預算警告
pdca "任務描述" --token-budget 20000 --warn-at 80

優化效果

基於測試專案的實際數據：

| 任務類型 | 優化前 tokens | 優化後 tokens | 節省比例 | |----------|---------------|---------------|----------| | 簡單功能 | ~15,000 | ~5,000 | 67% | | 中型專案 | ~45,000 | ~15,000 | 67% | | 複雜系統 | ~80,000 | ~27,000 | 66% |

監控指令

# 查看當前使用狀況
pdca status

# 啟用詳細成本顯示
pdca "任務" --show-cost --currency USD

這些改進讓系統在保持品質的同時，顯著降低 AI API 的使用成本。

🏗️ 系統架構

PDCA 代理角色

| 代理 | 職責 | 主要輸出 | |------|------|----------| | Plan | 需求分析、架構設計、任務規劃 | 執行計畫、技術方案、任務分解 | | Do | 功能實作、程式碼開發、文檔撰寫 | 原始碼、測試程式、API 文檔 | | Check | 品質檢查、測試執行、代碼審查 | 測試報告、問題清單、改進建議 | | Act | 效能優化、程式重構、最佳實踐 | 優化程式碼、效能報告、重構方案 | | Knowledge | 經驗記錄、知識管理、決策追蹤 | 決策記錄、最佳實踐、學習筆記 |

技術架構

PDCA System
├── AI Engine Layer          # AI 引擎適配層
│   ├── Claude Adapter       # Claude CLI 支援
│   ├── Gemini Adapter       # Gemini CLI 支援（推薦）
│   └── OpenAI Adapter       # OpenAI CLI 支援
├── Orchestration Layer      # 協調層
│   ├── Task Distributor     # 任務分配器
│   ├── Message Queue        # 訊息隊列
│   └── State Manager        # 狀態管理
├── Agent Layer             # 代理層
│   └── 5 × AI Instances    # 5 個並行 AI 實例
└── Monitoring Layer        # 監控層
    ├── TUI Dashboard       # 終端監控介面
    └── Activity Logger     # 活動日誌

🛠️ 技術特色

真正的多代理並行

• tmux session: 5 個獨立 Claude 實例同時運作
• git worktree: 代理工作空間完全隔離
• 實時 TUI: 監控介面顯示所有代理狀態
• 智能通訊: 文件系統協調代理間協作

職人級體驗

• 一鍵啟動: 零配置即用
• 隨時介入: 實時查看和指導任一代理
• 工匠品質: 每個細節都追求完美
• 中文友好: 主要介面使用中文，技術術語保持英文

📁 專案結構

pdca/
├── .claude/                    # Claude 配置
│   ├── commands/               # 斜線指令
│   │   └── pdca.md            # /pdca 指令定義
│   └── agents/                # 代理配置
├── .pdca-shokunin/            # PDCA-Shokunin 系統
│   ├── launcher.py            # 主啟動器
│   ├── monitor.py             # TUI 監控介面
│   ├── agents/                # 代理配置
│   ├── worktrees/             # git worktree 工作區
│   ├── communication/         # 代理間通訊
│   └── logs/                  # 系統日誌
├── memories/                  # 記憶庫
│   ├── decisions/             # 決策記錄
│   ├── solutions/             # 解決方案
│   ├── patterns/              # 設計模式
│   ├── learnings/             # 經驗教訓
│   └── progress/              # 進度追蹤
├── pdca_shokunin/             # Python 套件
├── setup.py                   # 套件安裝配置
└── README.md                  # 本文件

🎯 使用場景

軟體開發

pdca "建立 RESTful API"
pdca "優化資料庫性能" -p enterprise
pdca "設計微服務架榶" -p agile

系統分析

pdca "分析系統瓶頸" -v
pdca "設計擴展方案" -p startup
pdca "建立監控體系" -m

學習研究

pdca "學習 Kubernetes 部署" -p research
pdca "研究最新前端框架"
pdca "分析競品技術方案" -a 7

⚙️ 配置選項

全域配置

# ~/.pdca/config.yaml
ai_engine:
  preferred: auto        # auto | gemini | claude | openai
  
agents:
  parallel_limit: 5      # 並行代理數量
  timeout: 300          # 超時時間（秒）
  
logging:
  level: info           # debug | info | warn | error
  file: ~/.pdca/pdca.log

專案配置

# .pdca/project.yaml
project:
  name: "我的專案"
  description: "專案描述"
  
# 自定義代理提示詞
agents:
  plan:
    prompt: "你是資深架構師，擅長..."
  do:
    prompt: "你是全端工程師，精通..."

❓ 常見問題

Q: 沒有 Claude CLI 怎麼辦？

A: 系統會自動使用 Gemini CLI（免費且功能完整）：

# 安裝 Gemini CLI
npm install -g @google/gemini-cli
gemini auth  # 使用 Google 帳號

Q: 如何查看代理執行過程？

A: 使用 tmux 連接：

tmux attach -t pdca
# 使用 Ctrl+B 加數字鍵切換視窗

Q: 系統卡住了怎麼辦？

A: 執行診斷和重啟：

pdca doctor          # 診斷問題
pdca stop --force    # 強制停止
pdca clean          # 清理狀態

Q: 支援 Windows 嗎？

A: 支援 WSL（Windows Subsystem for Linux）：

1. 安裝 WSL2
2. 在 WSL 中安裝 Node.js 和 tmux
3. 按照 Linux 步驟安裝 PDCA

🤝 貢獻指南

歡迎貢獻！請查看 CONTRIBUTING.md。

開發環境

# Clone 專案
git clone https://github.com/RayYangTW/pdca
cd pdca

# 安裝依賴
npm install

# 開發模式
npm run dev

# 構建
npm run build

# 測試
npm test

📚 技術參考

相關專案

• Claude Squad - 多 AI 終端管理
• Claude Flow - AI 群體協調平台
• VibeTunnel - 遠端終端監控

核心依賴

• tmux - 終端多路復用
• blessed - 終端 UI
• commander - CLI 框架

📄 授權

MIT License - 詳見 LICENSE

🙏 致謝

• Anthropic - Claude CLI
• Google - Gemini CLI
• 所有貢獻者和使用者