總字數：約12000字 | 預計閱讀時長：35分鐘​

一、Harness Engineering概述​

1.1 什麼是Harness Engineering​

Harness Engineering（駕馭工程） 是一個新興的AI Agent系統設計學科，其核心觀點是：AI Agent好不好用，不只取決於底層模型多強，更取決於圍繞模型搭建的那套系統有多好。​

這套圍繞模型搭建的系統叫做harness（駕馭層），就像賽車的底盤、懸掛、剎車系統——發動機再強，沒有好的底盤也跑不快。​

Harness的核心組成：​

​



| 元件 | 職責 | 類比 |
| --- | --- | --- |
| 工具呼叫 | Agent與外部世界的互動介面 | 賽車的輪胎 |
| 許可權控制 | 決定Agent能做什麼、不能做什麼 | 賽車的剎車系統 |
| 記憶管理 | 短期和長期資訊的儲存與檢索 | 賽車的資料記錄儀 |
| 上下文壓縮 | 管理有限的上下文視窗 | 賽車的燃油管理系統 |
| 安全護欄 | 防止Agent做出危險操作 | 賽車的安全帶和防滾架 |
| 多Agent協調 | 多個Agent之間的協作機制 | 車隊的無線電通訊 |



​

關鍵資料：根據Claude Code的原始碼分析，一個AI Agent系統的成功，60%靠模型能力，40%靠駕馭工程。這意味著即使使用相同的底層模型，不同的駕馭層設計會導致Agent表現天差地別。​

1.2 Harness Engineering的誕生背景​

在AI Agent發展的早期，開發者普遍認為"模型越強，Agent越好用"。但實踐證明，這個觀點過於簡單。​

三個關鍵發現：​

1）模型能力的邊際遞減​

•

GPT-3.5到GPT-4的提升巨大，但GPT-4到GPT-5的提升相對有限​

•

模型能力達到一定水平後，駕馭層設計成為決定性因素​

2）相同模型，不同表現​

•

Claude Code和Cursor都使用Claude模型，但使用者體驗差異明顯​

•

差異主要來自駕馭層設計：許可權系統、上下文管理、工具呼叫策略​

3）工程實踐的啟示​

•

早期Agent專案失敗的原因，80%是駕馭層設計問題，不是模型能力問題​

•

"模型能理解，但系統不支援"是最常見的痛點​

一個直觀的比喻：​

想象兩位廚師，用同樣的食材做菜。一位用專業的廚房裝置（好的駕馭層），另一位用簡陋的工具（差的駕馭層）。即使食材相同，做出的菜品質量也會天差地別。​

1.3 Harness Engineering與傳統軟體工程的區別​

​



| 對比維度 | 傳統軟體工程 | Harness Engineering |
| --- | --- | --- |
| 核心物件 | 確定性邏輯 | 機率性推理 |
| 輸入處理 | 結構化資料 | 自然語言指令 |
| 錯誤處理 | 異常捕獲 | 機率閾值判斷 |
| 效能最佳化 | 演算法複雜度 | 上下文視窗管理 |
| 安全模型 | 許可權控制 | 許可權+意圖理解 |
| 測試方法 | 單元測試 | 機率性驗證 |



​

Harness Engineering的獨特挑戰：​

1）不確定性管理：AI模型的輸出是機率性的，駕馭層需要處理這種不確定性​

2）上下文視窗限制：有限的上下文視窗要求精心設計資訊管理策略​

3）意圖理解：需要理解使用者的真實意圖，而不僅僅是字面意思​

4）安全邊界：在賦予Agent能力和限制Agent行為之間找到平衡​

二、Harness的核心架構​

2.1 雙層查詢引擎設計​

駕馭層的核心是雙層查詢引擎，將Agent的LLM互動分為兩層：​

​

Unable to print

![Feishu Docs - Image](images/img_1.png)

​

外層QueryEngine的職責：​

•

預算控制：跟蹤API呼叫成本，防止超支​

•

重試機制：處理API呼叫失敗的情況​

•

許可權檢查：在呼叫工具前驗證許可權​

•

輪次限制：防止Agent陷入無限迴圈​

內層query的職責：​

•

系統提示片語裝：構建完整的系統提示詞​

•

訊息歷史管理：維護對話上下文​

•

API流式傳輸：實時接收模型輸出​

•

工具結果收集：收集和處理工具呼叫結果​

程式碼示例：​

​

Code block​

TypeScript

// QueryEngine核心邏輯（簡化版）​

class QueryEngine {​

private budget: BudgetTracker;​

private permissionChecker: PermissionChecker;​

​

async run(task: string): Promise<QueryResult\> {​

const messages = \[{ role: 'user', content: task }\];​

​

while (true) {​

// 檢查預算​

if (this.budget.isExceeded()) {​

throw new Error('Budget exceeded');​

}​

​

// 呼叫內層查詢​

const response = await query({​

messages,​

system: this.buildSystemPrompt(),​

tools: this.tools,​

stream: true​

});​

​

// 處理工具呼叫​

if (response.toolCalls) {​

for (const toolCall of response.toolCalls) {​

// 許可權檢查​

await this.permissionChecker.check(toolCall);​

​

// 執行工具​

const result = await this.executeTool(toolCall);​

messages.push({​

role: 'tool',​

​

2.2 三層許可權系統​

駕馭層的許可權系統採用三層架構，在安全性和易用性之間找到平衡：​

​



| 層級 | 機制 | 說明 | 效能 |
| --- | --- | --- | --- |
| Tier 1 | 規則快速路徑 | 模式匹配（glob和正則），分類：always-allow、always-ask、always-deny | 毫秒級 |
| Tier 2 | ML分類器 | 呼叫Claude API判斷bash命令或檔案編輯是否危險 | 秒級 |
| Tier 3 | 使用者提示 | 互動式審批對話方塊，支援計劃模式預覽 | 人工介入 |



​

許可權檢查流程：​

​

Unable to print

![Feishu Docs - Image](images/img_2.png)

​

程式碼示例：​

​

Code block​

TypeScript

// 許可權檢查流程（簡化版）​

async function checkPermission(toolCall: ToolCall): Promise<boolean\> {​

// Tier 1: 規則快速路徑​

const ruleResult = await checkRules(toolCall);​

if (ruleResult !== 'ambiguous') {​

​

設計優勢：​

1）效能最佳化：Tier 1的規則匹配可以在毫秒內完成，覆蓋80%的常見操作​

2）智慧判斷：Tier 2的ML分類器處理複雜場景，減少使用者幹預​

3）使用者控制：Tier 3確保使用者對高風險操作有最終控制權​

2.3 上下文壓縮策略​

上下文視窗是Agent最寶貴的資源。駕馭層實現了三種壓縮策略：​

​



| 策略 | 觸發條件 | 預算 | 說明 |
| --- | --- | --- | --- |
| MicroCompact | 區域性清理 | \- | 清理區域性上下文，如工具呼叫的中間結果 |
| AutoCompact | 接近上下文限制 | 13K緩衝 + 20K摘要 | 摘要觸發，帶斷路器 |
| FullCompact | 緊急情況 | 50K預算 | 選擇性重新注入關鍵資訊 |



​

壓縮策略的實現邏輯：​

​

Code block​

TypeScript

// 上下文壓縮策略（簡化版）​

class ContextCompressor {​

async compress(messages: Message\[\]): Promise<Message\[\]> {​

const tokenCount = this.countTokens(messages);​

​

// MicroCompact: 清理區域性上下文​

if (this.shouldMicroCompact(messages)) {​

return this.microCompact(messages);​

}​

​

// AutoCompact: 摘要壓縮​

if (tokenCount > this.threshold - 13000) {​

return this.autoCompact(messages);​

}​

​

// FullCompact: 緊急壓縮​

if (tokenCount > this.threshold - 50000) {​

return this.fullCompact(messages);​

}​

​

return messages;​

}​

​

private async autoCompact(messages: Message\[\]): Promise<Message\[\]> {​

// 1. 保留最近的訊息​

const recentMessages = messages.slice(-5);​

​

// 2. 對早期訊息生成摘要​

​

壓縮策略的設計原則：​

1）漸進式壓縮：從輕量級清理到重度壓縮，逐步釋放空間​

2）資訊保真：保留關鍵資訊，壓縮冗餘細節​

3）斷路器機制：防止過度壓縮導致資訊丟失​

4）可配置性：允許使用者調整壓縮閾值和策略​

三、Harness的核心元件​

3.1 工具呼叫系統​

工具呼叫是駕馭層最核心的元件，它決定了Agent能"做"什麼。​

工具呼叫的設計原則：​

1）延遲執行：工具在流式傳輸完成前就開始執行，減少等待時間​

2）並行呼叫：多個獨立工具可以並行執行​

3）結果快取：相同引數的工具呼叫可以快取結果​

4）錯誤恢復：工具呼叫失敗時提供重試機制​

工具呼叫的實現：​

​

Code block​

TypeScript

// 工具呼叫系統（簡化版）​

class ToolExecutor {​

private tools: Map<string, Tool\>;​

private cache: ToolResultCache;​

​

async execute(toolCall: ToolCall): Promise<ToolResult\> {​

const tool = this.tools.get(toolCall.name);​

if (!tool) {​

throw new Error(\`Unknown tool: ${toolCall.name}\`);​

}​

​

// 檢查快取​

const cached = await this.cache.get(toolCall);​

if (cached) {​

return cached;​

}​

​

// 執行工具​

const result = await tool.execute(toolCall.parameters);​

​

// 快取結果​

await this.cache.set(toolCall, result);​

​

return result;​

}​

}​

​

工具呼叫的最佳實踐：​

​



| 實踐 | 說明 | 示例 |
| --- | --- | --- |
| 單一職責 | 每個工具只做一件事 | read\_file只讀取檔案，不修改 |
| 清晰命名 | 工具名直觀表達功能 | create\_pull\_request而非do\_thing |
| 詳盡描述 | 描述是AI決策的關鍵依據 | 包含引數說明、返回值、使用場景 |
| 結構化返回 | 返回JSON而非純文字 | 便於AI解析和後續處理 |



​

3.2 記憶管理系統​

記憶管理決定了Agent能"記"什麼。駕馭層採用分層記憶架構：​

​

Unable to print

![Feishu Docs - Image](images/img_3.jpg)

​

記憶管理的設計決策：​

​



| 決策 | 為什麼 |
| --- | --- |
| 只記偏好不記程式碼 | 程式碼變化快，記了反而有害 |
| Markdown格式儲存 | 人類可讀，便於手動編輯 |
| 自動清理過期記憶 | 防止記憶膨脹影響效能 |
| 使用者可控制記憶 | 使用者可以檢視、編輯、刪除記憶 |



​

記憶系統的實現：​

​

Code block​

TypeScript

// 記憶管理系統（簡化版）​

class MemoryManager {​

private shortTerm: ShortTermMemory;​

private longTerm: LongTermMemory;​

​

async remember(key: string, value: any, duration: 'short' | 'long') {​

if (duration === 'short') {​

await this.shortTerm.set(key, value);​

} else {​

​

3.3 安全護欄系統​

安全護欄是駕馭層的"剎車系統"，防止Agent做出危險操作。​

安全護欄的層次：​

​



| 層次 | 機制 | 說明 |
| --- | --- | --- |
| 輸入過濾 | 惡意指令檢測 | 檢測prompt注入、越獄嘗試 |
| 意圖分析 | 危險操作識別 | 識別刪除檔案、修改系統配置等操作 |
| 執行監控 | 實時行為監控 | 監控工具呼叫、檔案修改、網路請求 |
| 輸出過濾 | 敏感資訊過濾 | 防止洩露密碼、金鑰等敏感資訊 |



​

安全護欄的實現：​

​

Code block​

TypeScript

// 安全護欄系統（簡化版）​

class SafetyGuard {​

private inputFilter: InputFilter;​

private intentAnalyzer: IntentAnalyzer;​

private executionMonitor: ExecutionMonitor;​

private outputFilter: OutputFilter;​

​

async checkInput(userInput: string): Promise<SafetyCheckResult\> {​

// 檢測惡意指令​

const malicious = await this.inputFilter.detect(userInput);​

if (malicious) {​

return { safe: false, reason: 'Malicious instruction detected' };​

}​

​

// 分析意圖​

const intent = await this.intentAnalyzer.analyze(userInput);​

if (intent.dangerous) {​

return { safe: false, reason: \`Dangerous intent: ${intent.type}\` };​

​

3.4 多Agent協調系統​

多Agent協調是駕馭層的高階特性，允許多個Agent協作完成複雜任務。​

協調模式：​

​



| 模式 | 說明 | 適用場景 |
| --- | --- | --- |
| 主從模式 | 一個主Agent協調多個從Agent | 任務分解、並行執行 |
| 對等模式 | Agent之間平等協作 | 資訊共享、協同推理 |
| 層級模式 | Agent形成層級結構 | 大型專案、複雜工作流 |



​

協調系統的實現：​

​

Code block​

TypeScript

// 多Agent協調系統（簡化版）​

class AgentCoordinator {​

private agents: Map<string, Agent\>;​

private communicationBus: CommunicationBus;​

​

async coordinate(task: Task): Promise<Result\> {​

// 分解任務​

const subtasks = await this.decompose(task);​

​

// 分配任務​

const assignments = await this.assign(subtasks);​

​

// 並行執行​

const results = await Promise.all(​

assignments.map(assignment => ​

this.executeAssignment(assignment)​

)​

);​

​

// 合併結果​

return await this.merge(results);​

}​

​

private async decompose(task: Task): Promise<Subtask\[\]> {​

// 使用主Agent分解任務​

const mainAgent = this.agents.get('main');​

return await mainAgent.decompose(task);​

​

四、Harness的設計原則​

4.1 效能優先原則​

駕馭層的設計必須優先考慮效能，因為Agent的響應速度直接影響使用者體驗。​

效能最佳化策略：​

​



| 策略 | 說明 | 效果 |
| --- | --- | --- |
| 延遲執行 | 工具在流式傳輸完成前就開始執行 | 減少50%等待時間 |
| 並行呼叫 | 多個獨立工具並行執行 | 提升3倍吞吐量 |
| 快取機制 | 相同引數的工具呼叫快取結果 | 減少80%重複計算 |
| 增量更新 | 只更新變化的部分，而非全量重算 | 減少90%資料傳輸 |



​

效能最佳化的實現：​

​

Code block​

TypeScript

// 效能最佳化器（簡化版）​

class PerformanceOptimizer {​

private cache: ResultCache;​

private parallelExecutor: ParallelExecutor;​

​

async optimize(toolCalls: ToolCall\[\]): Promise<ToolResult\[\]> {​

// 檢查快取​

const cached = await this.cache.getBatch(toolCalls);​

const uncached = toolCalls.filter(tc => !cached.has(tc.id));​

​

// 並行執行未快取的工具呼叫​

const results = await this.parallelExecutor.execute(uncached);​

​

// 合併快取和新結果​

return toolCalls.map(tc => ​

cached.get(tc.id) || results.get(tc.id)​

);​

​

4.2 安全性原則​

安全性是駕馭層設計的核心約束，必須在賦予能力和限制行為之間找到平衡。​

安全性設計原則：​

1）最小許可權原則：Agent只擁有完成任務所需的最小許可權​

2）縱深防禦：多層安全機制，即使一層被突破，其他層仍能保護​

3）透明可控：使用者可以隨時檢視和控制Agent的行為​

4）安全預設：預設配置應該是安全的，危險操作需要顯式授權​

安全性的實現：​

​

Code block​

TypeScript

// 安全管理器（簡化版）​

class SecurityManager {​

private permissionSystem: PermissionSystem;​

private auditLogger: AuditLogger;​

​

async enforceSecurity(action: Action): Promise<void\> {​

// 檢查許可權​

const hasPermission = await this.permissionSystem.check(action);​

if (!hasPermission) {​

throw new PermissionDeniedError(action);​

}​

​

// 記錄審計日誌​

await this.auditLogger.log(action);​

​

// 執行安全檢查​

​

4.3 可擴充套件性原則​

駕馭層必須支援擴充套件，以適應不斷變化的Agent需求。​

可擴充套件性設計：​

1）外掛架構：透過外掛機制新增新功能​

2）配置驅動：行為透過配置檔案控制，而非硬編碼​

3）介面抽象：核心元件透過介面互動，便於替換實現​

4）版本相容：新版本必須向後相容，支援平滑升級​

可擴充套件性的實現：​

​

Code block​

TypeScript

// 外掛系統（簡化版）​

class PluginSystem {​

private plugins: Map<string, Plugin\>;​

private hooks: Map<string, Hook\[\]>;​

​

async register(plugin: Plugin): Promise<void\> {​

// 註冊外掛​

​

4.4 可觀測性原則​

駕馭層必須提供良好的可觀測性，便於除錯和最佳化。​

可觀測性的三個支柱：​

​



| 支柱 | 說明 | 工具 |
| --- | --- | --- |
| 日誌 | 記錄系統行為和事件 | 結構化日誌、日誌聚合 |
| 指標 | 量化系統效能和狀態 | Prometheus、Grafana |
| 追蹤 | 跟蹤請求的完整生命週期 | OpenTelemetry、Jaeger |



​

可觀測性的實現：​

​

Code block​

TypeScript

// 可觀測性系統（簡化版）​

class ObservabilitySystem {​

private logger: Logger;​

private metrics: MetricsCollector;​

private tracer: Tracer;​

​

async instrument(operation: string, fn: () => Promise<any\>): Promise<any\> {​

// 開始追蹤​

const span = this.tracer.startSpan(operation);​

​

// 記錄開始時間​

const startTime = Date.now();​

​

try {​

// 執行操作​

const result = await fn();​

​

// 記錄成功指標​

this.metrics.increment(\`${operation}.success\`);​

this.metrics.histogram(\`${operation}.duration\`, Date.now() - startTime);​

​

// 記錄日誌​

this.logger.info(\`${operation} completed\`, { duration: Date.now() - startTime });​

​

return result;​

} catch (error) {​

// 記錄失敗指標​

​

五、Harness的實踐應用​

5.1 Claude Code的Harness實現​

Claude Code是駕馭工程最成功的實踐案例。其原始碼揭示了駕馭層設計的精髓。​

Claude Code的駕馭層架構：​

​

Code block​

Plain Text

┌─────────────────────────────────────────────────────────┐​

│ Claude Code 駕馭層 │​

│ ┌─────────────────────────────────────────────────┐ │​

│ │ QueryEngine │ │​

│ │ • 預算控制 • 重試機制 • 許可權檢查 • 輪次限制 │ │​

│ └─────────────────────────────────────────────────┘ │​

​

Claude Code的關鍵設計決策：​

​



| 決策 | 為什麼 |
| --- | --- |
| 搜尋用grep不用RAG | LLM夠聰明，grep更快更可靠 |
| 記憶系統只記偏好不記程式碼 | 程式碼變化快，記了反而有害 |
| 許可權分類器用兩階段 | 第一階段用64 token就能放行大部分操作 |
| 選Bun不選Node.js | 啟動速度快，原生TypeScript支援 |
| 自定義終端渲染器 | 需要精細控制渲染效能和互動體驗 |



​

5.2 Hermes Agent的Harness實現​

Hermes Agent採用了不同的駕馭層策略，更注重自進化和學習。​

Hermes Agent的駕馭層特點：​

1）自進化閉環：從任務執行中學習，自動生成Skill​

2）四層記憶架構：短期工作記憶、長期知識沉澱、技能庫、使用者畫像​

3）預設審批機制：高風險操作需要使用者確認​

4）自動摘要：上下文接近限制時自動壓縮​

Hermes Agent的駕馭層架構：​

​

Code block​

Python

\# Hermes Agent的駕馭層（簡化版）​

class HermesHarness:​

def \_\_init\_\_(self):​

self.memory = FourLayerMemory()​

self.skill\_generator = SkillGenerator()​

self.approval\_system = ApprovalSystem()​

self.context\_compressor = ContextCompressor()​

​

async def run(self, task: str) -> Result:​

\# 檢索相關記憶​

memories = await self.memory.recall(task)​

​

\# 檢索相關技能​

skills = await self.skill\_generator.find\_relevant(task)​

​

\# 構建上下文​

context = self.build\_context(task, memories, skills)​

​

\# 壓縮上下文（如果需要）​

context = await self.context\_compressor.compress(context)​

​

\# 執行任務​

​

5.3 OpenClaw的Harness實現​

OpenClaw採用了Gateway閘道器架構，駕馭層設計更注重擴充套件性和生態整合。​

OpenClaw的駕馭層特點：​

1）Gateway架構：作為各種AI服務的統一閘道器​

2）13,700+技能：龐大的技能生態系統​

3）使用者配置許可權：許可權系統完全由使用者配置​

4）Markdown記憶：使用Markdown檔案儲存記憶​

OpenClaw的駕馭層架構：​

​

Code block​

TypeScript

​

六、Harness的未來發展趨勢​

6.1 自適應Harness​

未來的駕馭層將具備自適應能力，根據使用場景自動調整策略。​

自適應特性：​

1）效能自適應：根據系統負載自動調整併發度和快取策略​

2）安全自適應：根據風險等級自動調整許可權檢查嚴格程度​

3）上下文自適應：根據任務複雜度自動調整壓縮策略​

4）學習自適應：根據使用者反饋自動調整學習策略​

6.2 跨平臺Harness​

隨著AI Agent的普及，駕馭層需要支援跨平臺部署。​

跨平臺挑戰：​

1）一致性：確保不同平臺上的行為一致​

2）效能：針對不同平臺最佳化效能​

3）安全：適應不同平臺的安全模型​

4）整合：與不同平臺的原生功能整合​

6.3 社群驅動的Harness​

開源社群將推動駕馭工程的發展。​

社群貢獻方向：​

1）工具生態：開發更多高質量的工具​

2）最佳實踐：分享駕馭層設計的最佳實踐​

3）效能基準：建立駕馭層效能的基準測試​

4）安全審計：對駕馭層進行安全審計和漏洞修復​

七、總結與展望​

7.1 核心要點回顧​

本文系統介紹了駕馭工程的核心概念、架構設計和實踐應用：​

1）駕馭工程定義：圍繞AI模型搭建的系統工程，決定Agent的60%表現​

2）雙層查詢引擎：外層控制預算和許可權，內層實現機制和流式傳輸​

3）三層許可權系統：規則快速路徑、ML分類器、使用者提示，在安全性和易用性之間找到平衡​

4）上下文壓縮策略：MicroCompact、AutoCompact、FullCompact三種策略，管理有限的上下文視窗​

5）核心元件：工具呼叫、記憶管理、安全護欄、多Agent協調​

6）設計原則：效能優先、安全第一、可擴充套件、可觀測​

7.2 駕馭工程的價值​

駕馭工程為AI Agent開發提供了系統化的方法論：​

1）提升Agent表現：透過精心設計的駕馭層，相同模型可以表現更好​

2）降低開發成本：標準化的駕馭層元件可以複用，減少重複開發​

3）增強安全性：多層安全機制確保Agent行為可控​

4）改善使用者體驗：效能最佳化和智慧互動提升使用者滿意度​

7.3 與後續內容的銜接​

在掌握了駕馭工程之後，我們將繼續學習：​

1）Agent安全（第5章）：Agent系統面臨的安全威脅和防護措施​

2）Skill安全（第5.3節）：技能系統的安全風險和防護​

3）MCP安全（第5.4節）：MCP協議的安全機制和最佳實踐​

這些內容將幫助你構建更加安全、可靠的AI Agent系統。​

7.4 學習建議​

1）理論與實踐結合：在理解駕馭工程原理的同時，動手實現簡單的駕馭層系統​

2）分析開源專案：研究Claude Code、Hermes Agent、OpenClaw的原始碼，理解它們的駕馭層設計​

3）關注效能指標：建立效能基準，持續最佳化駕馭層的各個元件​

4）重視安全設計：安全是駕馭層設計的核心約束，必須在設計初期就考慮​

​

​

參考資料：​

1.

Claude Code原始碼分析（洩露版本，2026年3月）​

2.

Hermes Agent官方文件：[https://github.com/NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)​

3.

OpenClaw官方文件：[https://github.com/openclaw/openclaw](https://github.com/openclaw/openclaw)​

4.

Anthropic官方部落格：駕馭工程最佳實踐​

5.

AI Agent架構設計模式（O'Reilly，2026年）​