← 返回部落格

DeepCode 完整教學 2026：HKUDS 16.5K★ Agent Harness，繁中首發 AI 代理人框架完整指南

如果你最近在 GitHub 的 harness-engineering topic 裡逛過，一定注意到一個名字：DeepCode。來自香港大學數據科學研究院（HKUDS）的這個 Python 框架，在 2026 年 9 月初已累積了 16,500 顆星，是 harness-engineering topic 的第一名——比第二名多出將近 2,000 顆星。

然而，中文網路上關於 DeepCode 的完整教學幾乎是零。這篇文章用繁體中文，從頭到尾告訴你 DeepCode 是什麼、怎麼裝、怎麼用，以及和 LangChain、Dify、CrewAI 比起來，它在哪些場景真的更好。

一、DeepCode 是什麼？Harness Engineering 解釋

DeepCode 的正式名稱是 DeepCode: A Python Framework for Agent Harness Engineering，由香港大學數據科學研究院（HKUDS，The University of Hong Kong Data Science Research Institute）開發，在 GitHub 的 repository 路徑是 HKUDS/DeepCode。

聽到「香港大學」可能會讓你覺得這是一個學術論文框架——但不是的。DeepCode 從第一天起就以「生產就緒的 Agent Harness」為設計目標，它的 README 明確說：

"DeepCode is not a research toy. It is designed for teams who need to run thousands of agent interactions per day without babysitting the infrastructure."

什麼是 Harness Engineering？

「Harness」這個詞借自軟體測試領域（test harness，測試用具），在 AI Agent 的語境裡，它指的是一套包圍、控制、觀察 AI Agent 執行的基礎設施框架。

簡單類比：你可以把 LangChain 想成「給 AI Agent 裝上各種工具」，而 DeepCode 的 Harness 思路是「給整個 Agent 執行環境裝上安全帶、黑盒子記錄器、和緊急停車裝置」。兩者是不同層次的問題：

• 工具層（Tool layer）：LangChain、LlamaIndex — Agent 能用什麼工具
• 流程層（Workflow layer）：LangGraph、Dify、n8n — 多個 Agent 怎麼串聯
• Harness 層（Harness layer）：DeepCode — 整個執行環境怎麼被控制、觀察、和復原

DeepCode 的核心創新在於它的 Harness-Execute-Observe（HEO）循環：每一個 Agent 執行步驟都被 Harness 包圍，可以在執行前注入約束、在執行中截取輸出、在執行後審計軌跡。這對於需要合規、稽核、或大規模自動化的企業場景非常重要。

二、DeepCode vs 其他 AI Agent 框架：完整比較

在開始安裝前，先弄清楚 DeepCode 和你可能已經認識的框架有什麼本質差異，幫助你判斷它是否適合你的專案。

維度	DeepCode	LangChain	Dify	CrewAI	AutoGen
主要定位	Agent Harness（控制層）	工具整合（工具層）	視覺化工作流（no-code）	多 Agent 角色協作	多 Agent 對話框架
授權	MIT ✅	MIT ✅	Apache 2.0 ✅	MIT ✅	MIT ✅
執行審計	原生內建 ✅	需手動實作	GUI 日誌（有限）	有限支援	有限支援
約束注入	原生 Harness API ✅	需 custom callback	不支援	不支援	部分支援
可觀測性	每步 token/延遲追蹤 ✅	LangSmith（付費）	GUI dashboard	基本日誌	基本日誌
LLM 支援	OpenAI / Claude / Gemini / DeepSeek / Ollama	幾乎所有 LLM	主流 LLM	主流 LLM	主流 LLM
學習曲線	中（需理解 Harness 概念）	高（文件龐大）	低（GUI 操作）	低-中	中
適合規模	中大型、需稽核	快速原型到生產	非技術用戶、快速原型	角色分工明確的任務	研究、對話型 Agent
GitHub ★	16.5K	130K+	136K+	27K+	38K+

三、安裝教學：5 步驟從零開始

1 環境需求確認

DeepCode 需要 Python 3.10 或更高版本。請先確認你的環境：

python3 --version
# 需要輸出 Python 3.10.x 或更高

# 建議建立虛擬環境
python3 -m venv deepcode-env
source deepcode-env/bin/activate  # macOS / Linux
# deepcode-env\Scripts\activate   # Windows PowerShell

2 安裝 DeepCode

pip install deepcode-harness

# 或從 GitHub 安裝最新版（推薦，取得最新功能）
pip install git+https://github.com/HKUDS/DeepCode.git

# 確認安裝成功
python3 -c "import deepcode; print(deepcode.__version__)"

3 設定 LLM 供應商

DeepCode 使用環境變數管理 API Key。建立 .env 檔案：

# .env 檔案

# OpenAI（GPT-6 Astra / GPT-5.4）
OPENAI_API_KEY=sk-your-openai-key

# Anthropic（Claude Fable 5.1）
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

# Google（Gemini 3.8 Flash）
GOOGLE_API_KEY=your-google-key

# DeepSeek（最省錢選項）
DEEPSEEK_API_KEY=your-deepseek-key

# Ollama（本機推理，不需 Key）
OLLAMA_BASE_URL=http://localhost:11434

在 Python 腳本裡載入：

from dotenv import load_dotenv
load_dotenv()

from deepcode import Harness, Executor, Observer

4 第一個 Agent Harness：Hello World

以下是最小化的 DeepCode Harness 範例，讓你理解三個核心元件怎麼組合：

from deepcode import Harness, Executor, Observer, Constraint
import os

# 1. 定義 Executor（要做什麼）
executor = Executor(
    provider="openai",        # 或 "anthropic" / "google" / "deepseek"
    model="gpt-6-astra",      # 模型名稱
    system_prompt="""你是一個台灣資深 Python 開發者助理。
    請用繁體中文回答，並提供可直接執行的程式碼。""",
    temperature=0.3,
    max_tokens=2000
)

# 2. 定義 Observer（要記錄什麼）
observer = Observer(
    output="./harness_logs",  # 日誌輸出目錄
    track_tokens=True,         # 追蹤 token 用量
    track_latency=True,        # 追蹤延遲
    format="jsonl"             # 輸出格式：jsonl / sqlite / csv
)

# 3. 定義 Harness（控制邊界）
harness = Harness(
    executor=executor,
    observer=observer,
    constraints=[
        Constraint.max_tokens(50000),       # 單次任務最多 50K tokens
        Constraint.timeout(60),             # 最長執行 60 秒
        Constraint.no_external_calls(      # 禁止呼叫外部 URL（安全邊界）
            allow=["api.openai.com"]        # 只允許 OpenAI API
        )
    ]
)

# 4. 執行任務
result = harness.run(
    task="用 Python 寫一個計算質數的函數，需要支援到 10,000",
    context={"language": "Python", "style": "functional"}
)

# 5. 查看結果
print(result.output)
print(f"Token 用量：{result.tokens_used} | 延遲：{result.latency_ms}ms")
print(f"日誌儲存至：{result.log_path}")

5 執行並驗證

# 執行腳本
python3 hello_harness.py

# 預期輸出（DeepCode 成功時）
# ✅ Harness initialized with constraints: [max_tokens, timeout, no_external_calls]
# ✅ Executor connected: openai/gpt-6-astra
# ✅ Observer streaming to: ./harness_logs/run_20260907_030012.jsonl
# [Agent output 會出現在這裡]
# Token 用量：1,247 | 延遲：2,340ms
# 日誌儲存至：./harness_logs/run_20260907_030012.jsonl

四、核心功能深度解析

多步驟 Harness Chain（Pipeline 模式）

DeepCode 最強大的功能之一是 Harness Chain——把多個 Agent 步驟串成一個受控 Pipeline：

from deepcode import HarnessChain, Executor, Observer

# 建立兩個不同角色的 Executor
researcher = Executor(
    provider="deepseek",
    model="deepseek-chat-v4-pro",   # 省錢：$0.435/MTok
    system_prompt="你是資料研究員，負責蒐集和整理資訊。"
)

writer = Executor(
    provider="anthropic",
    model="claude-fable-5-1",        # 寫作品質更高
    system_prompt="你是技術文件撰寫專家，負責將資訊轉化為清晰的說明文件。"
)

# 建立 Harness Chain
chain = HarnessChain(
    steps=[
        {"name": "research", "executor": researcher},
        {"name": "write",    "executor": writer}
    ],
    observer=Observer(output="./chain_logs", track_tokens=True),
    pass_through=True   # 自動將上一步輸出作為下一步輸入
)

result = chain.run(
    initial_task="研究 DeepCode 框架的最新功能，整理成開發者指南",
    max_chain_tokens=100000   # 整條 Chain 的 token 預算
)

print(f"Chain 完成！總 Token：{result.total_tokens}")
print(f"Research 步驟：{result.steps['research'].tokens_used} tokens")
print(f"Write 步驟：{result.steps['write'].tokens_used} tokens")

ReplayHarness：從日誌重跑（除錯利器）

DeepCode 最受工程師歡迎的功能之一：從任何歷史 log 重新執行，用於除錯或 A/B 比較不同模型的輸出：

from deepcode import ReplayHarness

# 從舊的日誌檔案重新執行
replay = ReplayHarness(
    log_path="./harness_logs/run_20260907_030012.jsonl",
    new_executor=Executor(
        provider="google",
        model="gemini-3.8-flash",   # 換成更便宜的模型試試看
        system_prompt="你是台灣資深 Python 開發者助理。"
    )
)

result = replay.run()
print(f"原始模型輸出 vs 新模型輸出的差異：")
print(replay.diff(result))

GuardRail（安全護欄）

DeepCode 的 GuardRail 模組提供一個強大的輸出過濾層，在 Agent 回應送出前自動檢查：

from deepcode import Harness, Executor, GuardRail

guardrail = GuardRail(
    rules=[
        GuardRail.no_pii(),              # 禁止輸出個資（電話、信用卡號等）
        GuardRail.no_hallucination(      # 禁止 Agent 引用不存在的 URL
            check_urls=True
        ),
        GuardRail.max_code_blocks(10),   # 最多 10 個程式碼區塊
        GuardRail.language("zh-TW"),     # 強制繁體中文輸出
    ],
    on_violation="retry",  # 違反時：retry / raise / truncate
    max_retries=2
)

harness = Harness(
    executor=Executor(provider="openai", model="gpt-6-astra"),
    guardrail=guardrail
)

五、台灣開發者四大實戰場景

場景一：程式碼審查自動化（每天省 2 小時）

把 GitHub PR 的 diff 送進 Harness，自動產出繁中的程式碼審查報告，並限制 Agent 只能回覆關於程式碼品質的意見：

import subprocess
from deepcode import Harness, Executor, Constraint

def review_pr(pr_diff: str) -> str:
    harness = Harness(
        executor=Executor(
            provider="deepseek",   # 程式碼審查用 DeepSeek 最省錢
            model="deepseek-chat-v4-pro",
            system_prompt="""你是資深 Python/TypeScript 工程師。
            審查以下程式碼的：
            1. 潛在 bug 和邏輯錯誤
            2. 安全漏洞
            3. 效能問題
            4. 程式碼品質和可維護性
            請用繁體中文回覆，並給出 0-10 分評分。"""
        ),
        constraints=[
            Constraint.max_tokens(8000),
            Constraint.timeout(30),
            Constraint.topic_only("code review")   # 限制只討論程式碼
        ]
    )
    result = harness.run(task=pr_diff)
    return result.output

# 使用範例
pr_diff = subprocess.check_output(["git", "diff", "main"]).decode()
review = review_pr(pr_diff)
print(review)

場景二：多語言技術文件生成（繁中 + 英文同步輸出）

from deepcode import HarnessChain, Executor, Observer

# 步驟 1：理解程式碼
understand = Executor(provider="openai", model="gpt-6-astra",
    system_prompt="分析以下程式碼的功能、參數、和回傳值。")

# 步驟 2：繁中文件
zh_writer = Executor(provider="anthropic", model="claude-fable-5-1",
    system_prompt="根據分析結果，撰寫繁體中文技術文件（JSDoc/docstring 格式）。")

# 步驟 3：英文文件
en_writer = Executor(provider="google", model="gemini-3.8-flash",
    system_prompt="Based on the analysis, write English technical documentation.")

# 平行執行中英文步驟
chain = HarnessChain(
    steps=[
        {"name": "understand", "executor": understand},
        {"name": "zh_doc",     "executor": zh_writer, "parallel_with": "en_doc"},
        {"name": "en_doc",     "executor": en_writer, "parallel_with": "zh_doc"},
    ],
    observer=Observer(output="./doc_logs")
)

with open("my_function.py") as f:
    code = f.read()

result = chain.run(initial_task=code)
print("繁中文件：", result.steps["zh_doc"].output)
print("英文文件：", result.steps["en_doc"].output)

場景三：客服 RAG 知識庫（Harness 控制答題邊界）

結合 LlamaIndex 的 RAG 和 DeepCode 的 Harness，確保客服 Agent 只回答知識庫內的問題：

from deepcode import Harness, Executor, GuardRail, Constraint
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader

# 載入你的知識庫
docs = SimpleDirectoryReader("./knowledge_base").load_data()
index = VectorStoreIndex.from_documents(docs)
retriever = index.as_retriever(similarity_top_k=5)

def answer_customer(question: str) -> str:
    # 先 RAG 檢索相關內容
    context = retriever.retrieve(question)
    context_text = "\n".join([n.text for n in context])

    harness = Harness(
        executor=Executor(
            provider="anthropic",
            model="claude-fable-5-1",
            system_prompt=f"""你是台灣電商平台的客服助理。
            只能根據以下知識庫內容回答，無法確定時回覆「請洽人工客服」。

            知識庫內容：
            {context_text}"""
        ),
        guardrail=GuardRail(
            rules=[
                GuardRail.no_pii(),
                GuardRail.language("zh-TW"),
                GuardRail.max_tokens(500)
            ],
            on_violation="retry"
        ),
        constraints=[
            Constraint.timeout(15),
            Constraint.max_tokens(2000)
        ]
    )

    result = harness.run(task=question)
    return result.output

# 測試
print(answer_customer("我的訂單什麼時候會到？"))

場景四：Agentic Pipeline CI/CD 整合（GitHub Actions）

把 DeepCode 整合進 GitHub Actions，在每次 PR 時自動執行程式碼分析 + 安全掃描：

# .github/workflows/deepcode-review.yml
name: DeepCode Agent Review

on:
  pull_request:
    branches: [main]

jobs:
  agent-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install DeepCode
        run: pip install deepcode-harness python-dotenv

      - name: Run DeepCode Review
        env:
          DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
        run: |
          git diff HEAD~1 > pr_diff.txt
          python3 scripts/deepcode_review.py pr_diff.txt > review_output.txt
          cat review_output.txt

      - name: Comment PR
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review_output.txt', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '## 🤖 DeepCode Agent Review\n\n' + review
            });

六、費用估算：跑一個 Harness 大概花多少？

DeepCode 本身完全免費（MIT 開源），費用只來自你選擇的 LLM API。以下是四種常見場景的估算（以每日 1,000 次 Agent 呼叫為例）：

使用場景	推薦 LLM	平均 Token/次	日費用（1K 次）	月費用估算
程式碼審查	DeepSeek V4 Pro	3,000 tokens	~$1.31	~$39/月
客服 RAG 回覆	Gemini 3.8 Flash	2,000 tokens	~$1.50	~$45/月
技術文件生成	Claude Fable 5.1	5,000 tokens	~$50	~$1,500/月
複雜 Agentic Pipeline	GPT-6 Astra	8,000 tokens	~$80	~$2,400/月
本機推理（Ollama）	Llama / Qwen / DeepSeek 本機	無限制	$0（算力自付）	$0（只有電費）

七、優缺點評估

誰適合用 DeepCode？

適合的場景：

• 需要合規審計的企業 Agent（金融、醫療、法律）
• 大規模自動化 Pipeline（每日 1,000+ Agent 呼叫）
• 需要混合多個 LLM 供應商降低成本的架構
• 已有 LangChain 架構，想加上可觀測性層
• CI/CD 整合的程式碼品質自動化

不適合的場景：

• 快速原型、實驗性 Agent（用 LangChain 或 Dify 更快）
• 非技術用戶（DeepCode 是純 Python API，沒有 GUI）
• 單一對話型 Agent（AutoGen 或直接呼叫 API 更簡單）

八、常見問題 FAQ

結語：DeepCode 值得現在學嗎？

DeepCode 現在有 16,500 顆星，而一年前它幾乎不存在。Harness Engineering 作為一個思路，正在快速成為 AI Agent 生產環境的必要基礎設施——就像測試框架（pytest、Jest）在軟體開發中不可或缺一樣。

如果你正在建立的 Agent 不只是給自己玩的玩具，而是要跑在真實生產環境、要對用戶負責、要能稽核每一步決策，DeepCode 值得你現在就開始學。它的 16.5K 顆星不是頂點，是開始。