majiayu000 Harness Engineering 設計模式
Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions
基於 Claude Code v2.1.88（92,500 行 TypeScript）逆向分析。
1. Agent Loop：Async Generator 模式
Claude Code 的 agent loop 用 async generator 實作：
async function* queryModel(...): AsyncGenerator<StreamEvent | AssistantMessage> {
// yield 每個 stream event，呼叫端按需消費
}
核心循環：queryModel() → 檢查 stop_reason → tool_use 時呼叫 runTools() → 結果回注 messages → 再次 queryModel()
stop_reason 分支：end_turn（結束）、tool_use（執行工具）、max_tokens（context 滿了，觸發 compaction）
2. Tool Orchestration：讀寫分離
function isConcurrencySafe(input): boolean {
// 工具自己聲明是否可並行
}
partitionToolCalls()把一批工具呼叫分成可並行組和必須串行組- 讀工具自動合批並行（FileRead、Grep、Glob）
- 寫工具強制串行（FileEdit、FileWrite、Bash）
- 決策權在工具端（Single Responsibility），不在 orchestrator
3. 工具執行 7 層管道
Schema Validation → Custom validateInput() → Input Sanitization
→ PreToolUse Hooks → Permission Resolution → Execution → PostToolUse Hooks
每層只問一個問題：「能否拒絕？」拒絕即停，不往下走。執行邏輯永遠在最後一層。
4. Cache 穩定性模式
Sticky Latch：影響 cache key 的欄位一旦啟用就不在 session 內關閉。
if (!fastModeHeaderLatched && isFastMode) {
fastModeHeaderLatched = true // 永遠 latched
}
確定性 ID：注入 context 的 ID 從穩定輸入衍���，不隨機生成。
靜態/動態邊界：SYSTEM_PROMPT_DYNAMIC_BOUNDARY 把 prompt 分成可全域快取的靜態段和 session 特定的動態段，防 2^N 快取桶爆炸。
Attachment > Inline：動態 agent 列表從 tool description 移到 attachment message，避免 MCP 連接/plugin 載入導致 tool schema cache bust。省 fleet 10.2% cache creation tokens。
5. Context Engineering
原則：什麼進 context、什麼順序、何時壓縮。
- 訊息處理管道
normalizeMessagesForAPI：10 步處理（過濾空訊息、合併連續同角色、注入 system-reminder、truncate 過長結果...） - Compaction 三模式：BASE（全壓）、PARTIAL_FROM（從某點壓）、PARTIAL_UP_TO（壓到某點）
<analysis>草稿：讓模型在 scratchpad 思考，結果不進 context- Deferred Tool Loading：36 個工具不全塞 prompt，ToolSearch 按需載入 schema
6. Multi-session Continuity
- Forked Agent：子 agent 繼承父 session 的 prompt cache（Memory extraction、AgentSummary、Dream 都用此模式）
- progress log：跨 context window 的進度檔（claude-progress.txt）
- AutoDream：背景記憶整合，三層閘門（時間≥24h + session≥5 + 檔案鎖），四階段 consolidation prompt
7. Observability
- 三層追��：Analytics（業務事件）/ OpenTelemetry（效能）/ DiagnosticTracking（per-turn 計數器）
- PII 安全型別：
PiiSafeString<T>型別系統，編譯期防止 PII 進入遙測 - Frustration Signal：追蹤使用者 swearing、重複 "continue" prompt，路由至 Datadog
參考
詳見 references/design-principles.md。