類型: 深度規劃文件
基於: 十大行業框架調研 + 自身 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 | 啟動流程: |
邊界情況處理:
- 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 |
方案:
- 擴展事件 payload:
agent:task:completed加入costUsd欄位 - Emit 時附帶成本:worker-scheduler emit 完成事件時帶上
costUsd - Pipeline 累加:
handleTaskCompleted()中累加run.totalCostUsd - 預算閘門:
- Post-stage:累加成本,超過
maxTotalCostUsd時 abort - Pre-dispatch:剩餘預算 <= 0 時不再 dispatch 新 stage
- Per-stage:超過
perStageLimits時記錄警告(Phase 2 為 advisory,Phase 3 為 hard gate)
- Post-stage:累加成本,超過
- Failed stages 也追蹤:錢已經花了,即使失敗也要累計
1C. 指數退避重試
| 屬性 | 值 |
|---|---|
| 問題 | 3 次重試無延遲,2 個 transient error pattern |
| 參考 | 行業最佳實踐:exponential backoff with jitter |
| 複雜度 | S(小) |
| 修改檔案 | worker-scheduler.ts |
方案:
1 | 退避公式:delay = min(30s × 2^retryCount + random(0-10s), 300s) |
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 | Knowledge 生命週期: |
KnowledgeEntry 結構:
1 | { |
查詢邏輯: 複用 scoring.ts 的 recency decay 模式 + keyword overlap 計分。excludeAgent 避免自我引用。
2C. 自適應預算分配
| 屬性 | 值 |
|---|---|
| 問題 | dailyCostLimit 靜態值,高 ROI agent 被限制 |
| 參考 | 行業「智能預算分配」最佳實踐 |
| 複雜度 | S-M(中小) |
| 新增檔案 | budget-optimizer.ts |
| 修改檔案 | worker-scheduler.ts |
方案:
1 | 效率分 = valueScore × (1 - failureRate) / avgCostPerTask |
每日一次計算(或手動觸發 /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 | Phase 1C(指數退避)──┐ |
建議實作順序:
| 順序 | 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 完成後:
npx tsgo --noEmit— 型別檢查通過npm test— 全部測試通過(新增對應 unit tests)- Phase 1A 手動驗證:啟動 pipeline → 模擬進程重啟 → 驗證 pipeline 恢復
- Phase 1B 手動驗證:跑 content-pipeline → 檢查
totalCostUsd正確累加 - Phase 2B 手動驗證:跑 2 個不同 agent → 驗證知識自動 deposit + 後續 task 注入
- 最終確認:
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 |