規劃文件

系統改善計畫：AI Agent Workflow 八項截長補短方案

類型: 深度規劃文件
基於: 十大行業框架調研 + 自身 8 子模組完整分析
狀態: 待審查

背景

基於對行業十大框架（LangGraph、CrewAI、AutoGen、OpenAI SDK、Anthropic Patterns、A2A、Dify、Coze、n8n、Flowise）的深度調研，以及對自身 8 個子模組的完整原始碼分析，識別出 8 項可截長補短的改進。

核心發現

領先行業的地方：

  • 安全治理（5 級漸進式響應 vs 行業常見 3 級）
  • 記憶完整性（Merkle Tree + Hash Chain + Inclusion Proof）
  • 自我演化（11 步管線，比 OpenAI 2026 初發布的 Self-Evolving Agents cookbook 更早）
  • Markdown Skills 系統（比 Anthropic 2025/12 發布的 Agent Skills 標準更早）

有明確差距的地方：

  • Pipeline 可靠性（崩潰後無法恢復）
  • 成本追蹤（定義了但未執行）
  • Agent 間知識共享（完全隔離）
  • 結果品質評估（純啟發式）

Phase 1：基礎層 — 可靠性與成本

三項改進，互相獨立，可並行實作。是所有後續改進的基礎。

1A. Pipeline Durable Execution（斷點續傳）

屬性 值
問題 activePipelines Map 僅存記憶體，進程崩潰後 Pipeline 成為孤兒
參考 LangGraph v1.0 的 Durable Execution
複雜度 M（中等）
修改檔案 pipeline-engine.ts, worker-scheduler.ts

現況分析： Pipeline JSON 已經被持久化到 soul/agent-tasks/pipelines/{runId}.json，但進程重啟後沒有任何程式碼載入它們。activePipelines Map 和 taskToPipeline Map 都是 in-memory only。

方案： 新增 rehydratePipelines() 函數：

1
2
3
4
5
6
7
8
9
10
11
12
13
啟動流程：
startWorkerScheduler()
  → cleanupStaleTasksOnStartup()     // 已有
  → rehydratePipelines()              // 新增
    → 掃描 soul/agent-tasks/pipelines/*.json
    → 篩選 status === 'running'
    → 重建 activePipelines Map
    → 重建 taskToPipeline mappings
    → 檢查 running stages 的 task 狀態
      → 已完成但未推進：重播 advancement
      → 遺失（不在 queue 也不在 history）：重新 dispatch
    → advancePipeline() 追趕
  → processQueue()

邊界情況處理：

  • Team template 被刪除 → abort pipeline with reason
  • Task 已 archive 到 history.jsonl → 查 history 確認已完成
  • Parallel layer 多個 running stages → 全部重建 mapping

1B. Pipeline 成本追蹤與預算執行

屬性 值
問題 totalCostUsd 永遠是 0，perStageLimits 從未執行
參考 行業 CLEAR 框架的 Cost 維度
複雜度 S（小）
修改檔案 event-bus.ts, worker-scheduler.ts, pipeline-engine.ts

方案：

  1. 擴展事件 payload：agent:task:completed 加入 costUsd 欄位
  2. Emit 時附帶成本：worker-scheduler emit 完成事件時帶上 costUsd
  3. Pipeline 累加：handleTaskCompleted() 中累加 run.totalCostUsd
  4. 預算閘門：
    • Post-stage：累加成本，超過 maxTotalCostUsd 時 abort
    • Pre-dispatch：剩餘預算 <= 0 時不再 dispatch 新 stage
    • Per-stage：超過 perStageLimits 時記錄警告（Phase 2 為 advisory，Phase 3 為 hard gate）
  5. Failed stages 也追蹤：錢已經花了，即使失敗也要累計

1C. 指數退避重試

屬性 值
問題 3 次重試無延遲，2 個 transient error pattern
參考 行業最佳實踐：exponential backoff with jitter
複雜度 S（小）
修改檔案 worker-scheduler.ts

方案：

1
2
3
4
5
退避公式：delay = min(30s × 2^retryCount + random(0-10s), 300s)

retry 1: ~30-40s
retry 2: ~60-70s
retry 3: ~120-130s（最長 5 分鐘）
  • AgentTask 新增 retryAfter?: string 欄位
  • processQueue() 過濾未到期的 retry 任務
  • 擴展 TRANSIENT_ERRORS：新增 ECONNRESET、ETIMEDOUT、socket hang up、overloaded_error

Phase 2：智能層 — 品質與知識

三項改進，依賴 Phase 1B 的成本數據。提升 Agent 輸出品質和團隊協作能力。

2A. LLM-as-Judge 結果品質評估

屬性 值
問題 assessResultConfidence() 純啟發式，長垃圾高分、短精華低分
參考 行業 CLEAR 框架的 Efficacy 維度
複雜度 M（中等）
新增檔案 result-assessor.ts
修改檔案 worker-scheduler.ts

方案： 雙層評估

層級 條件 方法 成本
快速啟發式 預設 現有文本分析邏輯 $0
LLM Judge costUsd > $0.10 或 failureCount7d >= 2 Haiku 品質評分 ~$0.002

四維評估（LLM Judge）：

  • relevance：是否回應 prompt？
  • completeness：是否完整？
  • accuracy：是否有依據？
  • structure：是否結構化？

LLM Judge 在 executeTask() 結果返回後、archive 前呼叫，不佔用額外 worker slot。失敗時降級到啟發式。

2B. Cross-Agent 知識轉移

屬性 值
問題 Agent 記憶完全隔離，洞見無法即時傳播
參考 CrewAI 的 Shared Memory 模式
複雜度 M（中等）
新增檔案 shared-knowledge.ts
修改檔案 worker-scheduler.ts

方案：

1
2
3
4
5
6
7
8
9
10
Knowledge 生命週期：

Agent 完成任務（confidence >= 0.6）
  → 自動提取關鍵字 + 摘要
  → deposit 到 shared-knowledge.jsonl（JSONL append-only）

另一個 Agent 開始新任務
  → query 相關知識（keyword overlap + recency decay）
  → 注入到 system prompt: "## 其他代理人的近期相關發現"
  → 上限 500 tokens

KnowledgeEntry 結構：

1
2
3
4
5
6
7
8
{
  id, agentName, taskId, timestamp,
  summary,          // 發現摘要
  keywords[],       // 檢索關鍵字
  importance: 1-5,
  category: finding | insight | warning | trend,
  ttlHours: 72      // 72 小時後過期
}

查詢邏輯： 複用 scoring.ts 的 recency decay 模式 + keyword overlap 計分。excludeAgent 避免自我引用。

2C. 自適應預算分配

屬性 值
問題 dailyCostLimit 靜態值，高 ROI agent 被限制
參考 行業「智能預算分配」最佳實踐
複雜度 S-M（中小）
新增檔案 budget-optimizer.ts
修改檔案 worker-scheduler.ts

方案：

1
2
3
4
5
6
7
效率分 = valueScore × (1 - failureRate) / avgCostPerTask

約束條件：
  - 全體 agent 日預算總和不變（守恆）
  - 單 agent 下限 $0.10/day
  - 單 agent 上限 3x 原配置
  - 變更記錄到 narrative.jsonl（透明度）

每日一次計算（或手動觸發 /budget optimize）。

Phase 3：進階能力

兩項改進，獨立於 Phase 1-2，可視需要插入。

3A. Discovery-Based Skill Loading

屬性 值
問題 Context weaver 載入 2 個完整 skill body（~1200 tokens）
參考 Anthropic 的 MCP Discovery-Based Loading
複雜度 S（小）
修改檔案 context-weaver.ts

方案： 載入 1 個最佳匹配 skill（完整 body）+ 所有 skill 的名稱清單（compact menu）

現況 改善後
注入策略 2 個完整 skill body 1 個最佳 + compact menu
Token 消耗 ~1200 ~400
節省 — ~67%

3B. Pipeline Event Replay

屬性 值
問題 Pipeline 失敗無法回顧執行路徑
參考 LangGraph 的 State Time-Travel
複雜度 S（小）
新增檔案 pipeline-replay.ts

方案： 從 pipelines/{id}.json + history.jsonl + agent-reports/ 重建執行時間線，輸出 Markdown。可用 /pipeline replay {id} 觸發。

依賴圖與實作順序

1
2
3
4
5
6
7
Phase 1C（指數退避）──┐
Phase 1B（成本追蹤）──┼── Phase 2A（LLM Judge）
Phase 1A（Pipeline 續傳）│  Phase 2B（知識轉移）
                      │  Phase 2C（預算優化）
                      │
                      └── Phase 3A（Skill Loading）
                          Phase 3B（Event Replay）

建議實作順序：

順序 ID 改進項 複雜度 檔案數 理由
1 1C 指數退避 S 1 最小改動，立即改善可靠性
2 1B 成本追蹤 S 3 小改動，解鎖 Phase 2
3 1A Pipeline 續傳 M 2 核心可靠性
4 2B 知識轉移 M 2 高用戶價值
5 2A LLM Judge M 2 品質提升
6 3A Skill Loading S 1 Token 節省
7 2C 預算優化 S-M 2 成本優化
8 3B Event Replay S 1 除錯輔助

關鍵檔案索引

檔案 涉及 Phase 類型 說明
src/agents/pipeline-engine.ts 1A, 1B 修改 rehydration + cost tracking
src/agents/worker-scheduler.ts 1A, 1B, 1C, 2A, 2B 修改 核心 dispatch 邏輯
src/core/event-bus.ts 1B 修改 擴展 event payload
src/agents/result-assessor.ts 2A 新建 LLM-as-Judge 評估器
src/agents/shared-knowledge.ts 2B 新建 跨 Agent 知識共享
src/agents/budget-optimizer.ts 2C 新建 自適應預算分配
src/identity/context-weaver.ts 3A 修改 Skill loading 優化
src/agents/pipeline-replay.ts 3B 新建 Pipeline 回放工具

驗證方式

每個 Phase 完成後：

  1. npx tsgo --noEmit — 型別檢查通過
  2. npm test — 全部測試通過（新增對應 unit tests）
  3. Phase 1A 手動驗證：啟動 pipeline → 模擬進程重啟 → 驗證 pipeline 恢復
  4. Phase 1B 手動驗證：跑 content-pipeline → 檢查 totalCostUsd 正確累加
  5. Phase 2B 手動驗證：跑 2 個不同 agent → 驗證知識自動 deposit + 後續 task 注入
  6. 最終確認：git diff --stat 確認改動範圍合理

預期影響

維度 改善幅度 來源
可靠性 Pipeline 崩潰恢復從 0% → ~95% 1A
成本可見度 從無追蹤 → 完整 pipeline/stage 級別 1B
重試效率 立即重試 → 智能退避（30s-5min） 1C
品質評估 啟發式 → 雙層（啟發式 + LLM Judge） 2A
知識利用 隔離 → 跨 Agent 即時共享 2B
預算效率 靜態 → ROI 驅動的動態分配 2C
Context token ~1200 → ~400（節省 67%） 3A
除錯能力 無回放 → 完整時間線重建 3B