414960701/harness-distiller

Harness Distiller（Agent Harness 蒸餾器）

把公開證據蒸餾成可實現、可驗證、可升級的 Agent Harness。把產品名視為行為與能力配方，不複製品牌、專有提示詞、受保護素材或無法驗證的內部實現。

必須遵守

1. 區分 code、official-doc、protocol、behavior、inference；不得把閉源產品推斷寫成原始碼事實。
2. 四個成熟度等級共用同一協定、狀態模型和模組邊界；升級只增加能力與優化，不生成互不相容的四套工程。
3. 先打通垂直切片：模型 → Agent loop → 一個讀取工具 → 權限 → 執行 → 事件 → 狀態 → 介面。
4. 保持 runtime headless；CLI、TUI、IDE、桌面與 Web 只透過版本化 command/event 協定互動。
5. 把 approval policy 與 sandbox enforcement 分開；使用者批准不能代替 OS、容器、路徑或網路強制邊界。
6. 每項「已實現」都要有程式碼位置；每項「已驗證」都要有可執行的測試或可重複行為證據。
7. 不把模型能呼叫 shell 當成「完整 Harness」。必須實現取消、失敗、恢復、持久化、權限和介面狀態重建。

按需讀取

• 選擇產品和檢查目錄完整度：讀取 references/catalog.md。
• 選擇等級或跨級升級：讀取 references/levels.md。
• 判斷每個 capability 何時可標為 verified：讀取 references/capabilities.md。
• 判斷證據可靠性：讀取 references/evidence.md 和 references/source-registry.md。
• 理解共享邊界：讀取 references/architecture.md。
• 開始落程式碼前：必須讀取 references/implementation/index.md，再按其路由載入實作規範。
• 選擇共享能力：讀取 references/knowledge/index.md，只載入藍圖選中的知識模組。
• 復刻某個產品：讀取 references/products/<product>/index.md，並按索引指定順序載入該產品的 13 篇 dossier。
• 新建工程：讀取 references/workflows/build.md。
• 升級已有工程：讀取 references/workflows/upgrade.md。
• 驗收工程：讀取 references/workflows/validate.md。

解析請求

從使用者請求與目標儲存庫解析：

• recipe：一個產品、hybrid 或 custom；
• level：runnable、usable、productive 或 polished；
• surfaces：cli、tui、ide、desktop、web、sdk、headless；
• execution：local、container、remote 或組合；
• stack：優先沿用目標儲存庫；新專案按產品表面和安全要求選擇；
• providers：模型供應商、本地模型與能力降級要求；
• security：個人、團隊或企業威脅模型；
• distribution：原始碼、套件、擴充功能、桌面應用或託管服務。

使用者只說「做一個像 Codex/Claude Code/QoderWork 的產品」時，預設選擇對應 recipe、usable、產品主表面加 headless，並把假設寫入決策記錄。

缺少其它選擇時使用可回退預設值：execution=local、security=personal、distribution=source；Codex-like 預設 Rust + headless/TUI，Claude-Code-like 預設 TypeScript + headless/CLI，QoderWork-like 預設 TypeScript + Tauri/Rust executor + headless/Desktop，Aider-like 預設 Python + headless/CLI，OpenCode 預設 TypeScript/Bun + headless/TUI，OpenHands 預設 Python + TypeScript/React + headless/Web/SDK，AgentScope、LangGraph 與 Deep Agents 預設 Python + headless/SDK。Provider 未指定時先實現 provider-neutral contract、確定性 scripted fixture 和 OpenAI-compatible adapter 介面，不擅自綁定付費服務；真正聯調前再要求使用者提供 provider 配置。

生成流程

1. 檢查儲存庫、技術棧、現有指令、dirty changes 和可用執行環境。
2. 在 references/catalog.md 確認產品為實現級；計劃中但未完成 13 篇 dossier 的 recipe 不得生成產品復刻，先補 dossier 或顯式改用 hybrid/custom。再執行 scripts/new_blueprint.py 建立 .harness-distill/blueprint.yaml。
3. 讀取產品 index.md、product-contract.md、recipe.md、acceptance-tests.md。
4. 按 recipe 載入實作規範和共享知識文件，建立 capability 依賴閉包。
5. 寫 .harness-distill/evidence.md，記錄論斷、URL、日期、版本/commit、證據類型和置信度。
6. 寫 .harness-distill/decisions.md，記錄架構選擇、閉源推斷、非目標、風險和回滾點。
7. 先實現協定、狀態骨架和一個可執行垂直切片；儲存並重放其事件 trace。
8. 按 schema → protocol → runtime → executor/policy → surface → migration 順序補齊能力。
9. 同時新增 contract、scenario、security、recovery、migration 和產品黑盒測試。
10. 執行 scripts/validate_blueprint.py、目標儲存庫檢查和產品 acceptance-tests.md。
11. 只把具有實現位置和測試證據的 capability 標為 verified。

生成物最低合約

目標工程必須包含等價邊界：

.harness-distill/
  blueprint.yaml       # 選擇、等級、能力、狀態和合約版本
  evidence.md          # 公開證據與推論邊界
  decisions.md         # 架構決策、非目標、風險和遷移
src/
  protocol/            # command/event/error/schema/capability negotiation
  runtime/             # turn 狀態機、取消、重試、預算、steering
  model/               # provider adapter 與能力協商
  context/             # 指令、檢索、記憶、預算、壓縮、快取
  tools/               # schema、registry、router、lifecycle、artifact
  policy/              # allow/deny/ask/amend 與審批範圍
  execution/           # workspace、檔案、shell、patch、網路、sandbox
  state/               # thread/turn/item/event/checkpoint/migration
  surfaces/            # CLI/TUI/IDE/Desktop/Web adapter
tests/
  contracts/           # 協定、provider、tool 與儲存合約
  scenarios/           # 真實任務閉環
  security/            # 越界、注入、秘密、網路和逃逸
  recovery/            # 崩潰、重複投遞、斷線和遷移

允許按語言慣例改名，但不得合併掉策略與強制執行、領域狀態與 UI 投影、模型歷史與持久事實之間的邊界。

完整性閘門

滿足以下全部條件才稱為選定等級的完整 Harness：

• blueprint、產品合約和實現位置一致；
• runnable 的 thread/turn/item/event trace 可持久化並重放；usable 起支援分頁與行程重新啟動恢復；polished 再要求跨版本遷移；
• tool call/result 原子配對，取消、逾時和遲到結果語義明確；
• 選擇 context 壓縮後，不破壞工具呼叫原子性、指令層級和審計範圍；
• 受限動作先由策略決策，再由真實執行邊界強制；
• UI 可用 snapshot + event 重建，不依賴 runtime 記憶體物件；
• usable 及以上的崩潰恢復不會重複不可逆副作用；
• 產品 acceptance-tests.md 的目前等級場景通過；
• 交付說明列出未支援行為、證據缺口和直接升級路徑。

跨級升級

直接從任意低等級升級到高等級時：

1. 驗證目前 blueprint、協定和資料庫 schema；
2. 計算 capability delta 並展開中間依賴；
3. 先遷移 schema，再擴協定、runtime、執行器和介面；
4. 保持舊配置和舊事件至少一個相容遷移邊界；
5. 為不可逆外部動作建立 checkpoint、冪等鍵或人工確認；
6. 執行所有低等級回歸和新等級驗收；
7. 測試通過後再更新 capability 狀態。