kenaz 0.3.21 → 0.3.23

package/core/dev/design/dashboard_docs_integration_PLAN.md

@@ -1,388 +0,0 @@
-# Dashboard 文檔整合方案
-
-**任務**: TASK_146 - Dashboard 整合統一文檔模組
-**優先級**: P0
-**預估時間**: 32 小時
-**日期**: 2026-02-09
-
----
-
-## 📋 方案概述
-
-將統一文檔整合進 Dashboard，提供**互動式學習體驗**，取代原本的 VitePress 獨立網站方案。
-
-### 為什麼改變方案？
-
-| 問題 | VitePress 獨立網站 | Dashboard 整合 |
-|------|------------------|---------------|
-| **體驗** | ❌ 需要切換兩個系統 | ✅ 統一介面 |
-| **互動性** | ❌ 靜態文檔 | ✅ API Playground、範例執行器 |
-| **即時性** | ❌ 無法顯示實際狀態 | ✅ 即時任務狀態、WebSocket 更新 |
-| **維護成本** | ❌ 兩套系統 | ✅ 單一技術棧（Next.js） |
-| **搜尋** | ❌ 獨立搜尋 | ✅ 統一搜尋所有內容 |
-
----
-
-## 🎯 核心目標
-
-1. **5 分鐘快速開始**：互動式教學，從安裝到執行第一個任務
-2. **即時測試**：API Playground 可直接測試 Team API
-3. **一鍵執行**：範例執行器可運行所有範例代碼
-4. **可視化**：Team 系統結構圖、工作流程動畫
-5. **即時狀態**：顯示當前專案的實際任務進度
-
----
-
-## 🏗️ 技術架構
-
-### 方案選擇：Next.js + Nextra（推薦）
-
-```
-優點：
-✅ 完整的文檔框架（內建搜尋、深色模式、MDX）
-✅ 與 Dashboard 共用 Next.js 環境
-✅ 社群活躍，維護良好
-✅ 支援 Server Components
-
-安裝：
-npm install nextra nextra-theme-docs
-```
-
-### 目錄結構
-
-```
-dashboard/
-├── src/
-│   ├── app/
-│   │   ├── docs/                           # 文檔路由 ⭐
-│   │   │   ├── layout.tsx                  # Docs 佈局
-│   │   │   ├── page.tsx                    # /docs 首頁
-│   │   │   ├── quick-start/
-│   │   │   │   └── page.tsx                # /docs/quick-start
-│   │   │   ├── api/
-│   │   │   │   ├── playground/
-│   │   │   │   │   └── page.tsx            # API Playground
-│   │   │   │   └── reference/
-│   │   │   │       └── page.tsx            # API 參考
-│   │   │   ├── examples/
-│   │   │   │   ├── runner/
-│   │   │   │   │   └── page.tsx            # 範例執行器
-│   │   │   │   └── [slug]/
-│   │   │   │       └── page.tsx            # 單個範例頁面
-│   │   │   └── team/
-│   │   │       └── visualizer/
-│   │   │           └── page.tsx            # Team 可視化
-│   │   └── api/
-│   │       └── docs/
-│   │           ├── execute-example/        # 執行範例 API
-│   │           └── team-status/            # 即時 Team 狀態
-│   ├── components/
-│   │   └── docs/                           # 文檔專用組件 ⭐
-│   │       ├── CodeRunner.tsx              # 代碼執行組件
-│   │       ├── APIPlayground.tsx           # API 測試組件
-│   │       ├── TeamVisualizer.tsx          # Team 圖表組件
-│   │       ├── ExampleRunner.tsx           # 範例執行器
-│   │       ├── SearchBar.tsx               # 搜尋組件
-│   │       ├── TableOfContents.tsx         # 目錄組件
-│   │       └── InteractiveGuide.tsx        # 互動式教學
-│   └── lib/
-│       └── docs/                           # 文檔工具函數 ⭐
-│           ├── content-loader.ts           # MDX 內容載入
-│           ├── search-index.ts             # 搜尋索引
-│           └── example-runner.ts           # 範例執行邏輯
-└── content/
-    └── docs/                               # MDX 文檔內容 ⭐
-        ├── getting-started/
-        │   ├── installation.mdx
-        │   ├── quick-start.mdx
-        │   └── first-task.mdx
-        ├── guides/
-        │   ├── team-system.mdx
-        │   ├── pipeline.mdx
-        │   └── agents.mdx
-        ├── api/
-        │   ├── team-api.mdx
-        │   ├── cli.mdx
-        │   └── hooks.mdx
-        └── examples/
-            ├── basic-usage.mdx
-            ├── multi-agent.mdx
-            └── advanced.mdx
-```
-
----
-
-## ✨ 核心功能設計
-
-### 1. API Playground（互動式 API 測試）
-
-**功能**：
-- 即時測試 Team API（`/api/team/execute`）
-- 顯示請求/回應
-- 支援認證
-- 預填範例參數
-
-**UI 設計**：
-```tsx
-<APIPlayground
-  endpoint="/api/team/execute"
-  method="POST"
-  defaultBody={{
-    team_id: "product_manager",
-    workflow_name: "task_creation",
-    user_input: "建立新功能：用戶儀表板"
-  }}
-  showAuth={true}
-  showResponse={true}
-/>
-```
-
-**技術實現**：
-- 使用 Monaco Editor 編輯 JSON
-- 語法高亮
-- 自動補全
-- 錯誤提示
-
-### 2. 範例執行器（一鍵運行）
-
-**功能**：
-- 一鍵運行範例代碼
-- 即時顯示輸出
-- 可修改參數
-- 儲存運行歷史
-
-**UI 設計**：
-```tsx
-<ExampleRunner
-  exampleId="quick-start-basic"
-  code={`
-    // 調用 Product Manager Team
-    const result = await fetch('/api/team/execute', {
-      method: 'POST',
-      body: JSON.stringify({
-        team_id: 'product_manager',
-        workflow_name: 'task_creation',
-        user_input: '建立新功能：用戶儀表板'
-      })
-    });
-  `}
-  language="javascript"
-  runnable={true}
-/>
-```
-
-### 3. Team 可視化（結構圖）
-
-**功能**：
-- 展示 5 個團隊的成員結構
-- 互動式成員關係圖
-- 工作流程動畫
-- 點擊成員查看詳細信息
-
-**技術選型**：
-- **D3.js**：力導向圖（Force-Directed Graph）
-- **Recharts**：簡單圖表
-- **React Flow**：流程圖
-
-**UI 設計**：
-```tsx
-<TeamVisualizer
-  teamId="product_manager"
-  showMembers={true}
-  showWorkflows={true}
-  interactive={true}
-/>
-```
-
-### 4. 即時狀態顯示
-
-**功能**：
-- 顯示當前專案的實際任務狀態
-- 即時更新（WebSocket）
-- 進度條動畫
-- 成員狀態（running/idle）
-
-**UI 設計**：
-```tsx
-<LiveStatus
-  projectPath="/path/to/project"
-  showTasks={true}
-  showTeams={true}
-  autoRefresh={true}
-/>
-```
-
----
-
-## 📝 文檔內容規劃
-
-### Getting Started（5 分鐘快速開始）
-
-1. **Installation（安裝）**
-   - 系統需求
-   - 一鍵安裝腳本
-   - RAG 引擎設置
-   - 常見問題
-
-2. **Quick Start（快速開始）**
-   - 3 步驟上手（安裝 → 配置 → 執行）
-   - 互動式教學（點擊下一步）
-   - 3 種工作模式（單 Agent、Team、Multi-Agent）
-
-3. **First Task（第一個任務）**
-   - 實戰教學（從 PRD 到完成）
-   - 完整操作步驟
-   - 成功標準檢查
-
-### Guides（使用指南）
-
-1. **Team System（.team 系統）**
-   - Leader + Worker 模式
-   - 5 個團隊詳解
-   - 團隊調用方式
-   - 最佳實踐
-
-2. **Pipeline Management（Pipeline 管理）**
-   - 任務生命週期
-   - 優先級管理
-   - 依賴關係
-   - 多 Agent 並行
-
-3. **Agents（Agent 使用）**
-   - 8 個 Agent 介紹
-   - Skill 定義
-   - 自定義 Agent
-
-### API Reference（API 參考）
-
-1. **Team API**
-   - `/api/team/execute`
-   - `/api/team/status`
-   - Python API
-
-2. **CLI Commands**
-   - `/產品`、`/dev`、`/後端`
-   - 排程腳本
-
-3. **Hooks**
-   - Session hooks
-   - Git hooks
-
-### Examples（範例庫）
-
-1. **Basic Usage（基礎使用）**
-   - 12 個實際範例
-   - 完整代碼
-   - 可一鍵運行
-
-2. **Multi-Agent（多 Agent）**
-   - 並行開發
-   - 任務分配
-   - 衝突處理
-
-3. **Advanced（進階）**
-   - 自定義 Team
-   - 工作流引擎
-   - RAG 整合
-
----
-
-## 🔗 整合點
-
-### 1. 導航欄
-
-```tsx
-// dashboard/src/components/Navbar.tsx
-<NavLink href="/docs" icon={BookOpenIcon}>
-  Docs
-</NavLink>
-```
-
-### 2. 搜尋整合
-
-```tsx
-// 統一搜尋（Projects + Agents + Docs）
-<SearchBar
-  sources={['projects', 'agents', 'docs']}
-  placeholder="搜尋專案、Agent 或文檔..."
-/>
-```
-
-### 3. 主題同步
-
-```tsx
-// 使用 Dashboard 的主題系統
-import { useTheme } from '@/hooks/useTheme';
-
-function DocsPage() {
-  const { theme } = useTheme(); // 'light' | 'dark'
-  return <div className={theme === 'dark' ? 'dark' : ''}>...</div>;
-}
-```
-
-### 4. 狀態共享
-
-```tsx
-// 使用 Dashboard 的狀態管理
-import { useProjectStore } from '@/stores/projectStore';
-
-function LiveStatus() {
-  const { currentProject, tasks } = useProjectStore();
-  // 顯示實際任務狀態
-}
-```
-
----
-
-## ✅ 驗收標準（8 項）
-
-| AC | 標準 | 驗證方式 |
-|----|------|---------|
-| AC-146-1 | 新用戶可在 Dashboard 內 5 分鐘完成環境設置並執行第一個任務 | 計時測試 + 用戶回饋 |
-| AC-146-2 | 所有主要功能都有互動式文檔（.team, Pipeline, 至少 2 個 Agent） | 檢查文檔完整性 |
-| AC-146-3 | 整合 Dashboard 搜尋，可搜尋文檔內容 | 測試搜尋功能 |
-| AC-146-4 | 文檔結構清晰，包含 Quick Start, Guides, API, Examples, Playground | 檢查目錄結構 |
-| AC-146-5 | API Playground 可測試至少 3 個 Team API 端點 | 測試 API 調用 |
-| AC-146-6 | 範例執行器可一鍵運行至少 5 個範例 | 執行所有範例 |
-| AC-146-7 | Team 可視化展示 5 個團隊的成員與工作流程 | 檢查視覺化圖表 |
-| AC-146-8 | Dashboard /docs 路由可正常訪問 | 訪問 http://localhost:3000/docs |
-
----
-
-## 📈 實施計劃（32 小時）
-
-### Phase 1: 基礎架構（8 小時）
-- [ ] 安裝 Nextra（1h）
-- [ ] 建立 `/docs` 路由和佈局（2h）
-- [ ] 設置 MDX 支援（2h）
-- [ ] 整合導航欄和搜尋（3h）
-
-### Phase 2: 文檔內容（8 小時）
-- [ ] Getting Started 文檔（3h）
-- [ ] Guides 文檔（3h）
-- [ ] API Reference（2h）
-
-### Phase 3: 互動功能（12 小時）
-- [ ] API Playground（4h）
-- [ ] 範例執行器（4h）
-- [ ] Team 可視化（4h）
-
-### Phase 4: 即時功能（4 小時）
-- [ ] 即時狀態顯示（2h）
-- [ ] WebSocket 整合（2h）
-
----
-
-## 🚀 下一步
-
-1. **開始執行 TASK_146**（使用 `/dev` 或 Developer Team）
-2. **設計 UI Mockup**（可選，使用 Figma）
-3. **選擇 Team 可視化庫**（D3.js vs React Flow）
-4. **建立 API Playground 原型**
-
----
-
-**建立者**: Claude Sonnet 4.5
-**日期**: 2026-02-09
-**相關任務**: TASK_146
-**Git Commits**: 88d659d (Revert), db1b6b6 (更新定義), e05428a (更新佇列)