動態技能提煉與使用採納驗證
autoharness 聚焦解決 AI Agent 技能層長期膨脹與難以維護的難題。傳統自適應框架多仰賴昂貴的離線基準評測（Held-out Benchmark）或常駐後台計時器（Daemon），而 autoharness 選擇直接從使用者的真實會話中提煉技能，並以模型在後續實戰中的採納頻率作為留存依據。
系統設計秉持零侵入性原則：宿主既有的名稱與描述檢索機制維持不變，僅在每次會話啟動時主動於 Context 前端注入結構化技能索引。整個流程完全於本地端透過 Python 3.11 原生腳本驅動，無需外部常駐行程。
當遭遇相似情境時，反思器會主動將新教訓合併至既有技能，而非無限制堆疊相似文件；每項技能皆隨附不可竄改的追溯帳本，完整記錄決策依據與會話片段。
會話捕獲 (CAP)
背景反思 (REF)
提拔落盤 (Promoter)
啟動索引 (IDX)
依從率留存 (MNG)
全局整併 (Curator)
「The harness does much of the work, yet it's still rebuilt by hand every model generation. autoharness bets one slice of it — the skill layer — can maintain itself.」 模型外圍的 Harness 承擔了大量工作，卻在每代模型發布時都得手工重造。autoharness 的核心賭注是：其中的技能層具備自我維護的能力。
Python 3.11 環境與外掛市集部署
autoharness 完全由 Python 實作且零第三方依賴。系統 PATH 中的 python3 必須為 3.11 或以上版本；若環境誤用 macOS Xcode 內建之 Python 3.9.6，所有 Hook 與 MCP Server 將自動關閉並於 stderr 輸出警示。
| 依賴項目 | 最低版本 | 用途說明 |
|---|---|---|
Python 3.11+ | >= 3.11.0 | 執行 Hook 捕捉、Promoter 驗證與 MCP Server，零第三方 pip 套件 |
Claude Code | 支援 Plugin 體系 | 提供外掛市集管理與 Session 生命週期 Hook 注入介面 |
# 於 Claude Code 對話框直接輸入以下指令
/plugin marketplace add tigerless-labs/autoharness
/plugin install autoharness@autoharness
# 重新載入外掛（或重啟 Claude Code）
/reload-plugins版本更新與快取同步方式
於系統終端機執行更新，先重新整理遠端市集索引，再更新特定外掛並重啟 Claude Code：
# 1. 重新整理市集目錄快取
claude plugin marketplace update autoharness
# 2. 更新至最新快取副本
claude plugin update autoharness@autoharness
# 3. 重啟 Claude Code 套用新版六大核心組件與參數調優矩陣
autoharness 將技能自學習管線切分為職責分明的六大組件，外加帳本追蹤與手動觸發指令。各組件透過 Claude Code 的外掛 Hook 攔截器串接，在不阻塞前台對話的前提下於背景完成提煉、驗證與生命週期淘汰。
Capture · 01
CAP
交互軌跡攔截器
監控對話視窗與工具調用次數，維護確定性計數器，達到設定閥值時啟動背景提煉。
Reflect · 02
REF
唯讀提煉分析器
分析對話窗口與摘要，無檔案寫入權限，僅能透過 stage_skill 意圖工具提議新增、整併、修補或刪除。
Promote · 03
Promoter
唯一寫入驗證門戶
嚴格校驗 Schema、描述長度（≤1024 字元）與技能主體行數（≤25 行），寫入帳本後原子化重新命名落盤。
Surface · 04
IDX
動態上下文索引注入
會話啟動時將現存技能依專案與全域分組注入模型上下文，每條限制 60 字元以內，並附上上次執行摘要。
Lifecycle · 05
MNG
機會相對使用率排序器
依據調用率（loads / requests）評估留存價值，區分載入、目錄檢視與修補，超額時將低效技能歸檔至 .archive。
Consolidate · 06
Curator
全庫去重整併專家
長週期（預設每 250 次調用）執行全技能庫巡檢，建立快照後將相似度過高之技能整併為大傘技能。
Audit · 07
LED
循序追加稽核帳本
每一技能專屬獨立帳本，詳細記錄操作行為、觸發理由與內容定址之驗證切片（evidence-*.md）。
Trigger · 08
/learn
隨選即時手動提煉
使用者專屬斜線指令，無需等待 50 次調用門檻即可立即分析當前會話並提煉為專案技能。
核心環境變數與參數調優矩陣
所有參數均可透過系統環境變數或 .env 覆寫，數值於外掛載入時動態讀取：
| 環境變數名稱 | 預設值 | 功能說明與調優建議 |
|---|---|---|
AUTOHARNESS_REFLECT_EVERY_N | 50 | 工具調用次數門檻。對話較為瑣碎或除錯密集時可調低至 30。 |
AUTOHARNESS_CONSOLIDATE_EVERY_N | 250 | 全庫整併巡檢週期。大型專案累積大量微技能時可縮短為 150。 |
AUTOHARNESS_MATURITY_PROJECT | 100 | 專案級新技能試用保護期請求數。保護期內免受容量淘汰機制影響。 |
AUTOHARNESS_CAPACITY_PROJECT | 50 | 專案技能容量上限。達到上限後優先淘汰非保護期內使用率最低者。 |
AUTOHARNESS_CAPACITY_GLOBAL | 20 | 跨專案全域技能容量上限，保持全域 Context 精簡高質。 |
AUTOHARNESS_INDEX_DESC_MAX_CHARS | 60 | 會話啟動注入之單條技能描述長度上限，避免佔用過多初始 Context。 |
七大架構原則與實戰配置要訣
autoharness 擺脫傳統 Agent 自適應框架必須常駐背景守護行程（Daemon）與離線基準評測的包袱。以下彙整自 Tigerless Labs 官方設計規範與實務運行提煉出的七項關鍵架構原則：
確定性計數器驅動提煉節奏
拋棄計時器排程，改以嚴格的工具調用次數為計數基準（預設每 50 次調用觸發一次）。避免空轉並精準對齊實際程式碼修改強度。
架構規範 · CAP & Hook
使用採納驗證勝過離線基準
評估自學習技能的指標非離線 Benchmark，而是模型在後續實戰中是否主動遵循。零調用的技能會隨機會率下降而自動被冷落。
設計哲學 · Adherence Metric
嚴格區分 Load、View 與 Patch
帳本計數器精細記錄行為：真正的 Skill 調用（Load）權重最高，單純的檔案目錄檢視（View）不灌水，而修補（Patch）能重置維護指標。
狀態管理 · MNG 機制
成熟度保護期避免過早淘汰
新提煉技能擁有專案級 100 次請求或全域 300 次請求的試用保護期（Maturity Probation）。保護期內不受容量上限與低採納率淘汰機制清除。
生命週期 · Probation Policy
永久封存而非無聲抹除
當技能庫超過容量（預設專案 50 個 / 全域 20 個），淘汰的技能會被移動至 .archive/ 目錄保留完整歷史與帳本，絕不直接 rm。
安全設計 · Archive Strategy
專案與全域嚴格分層隔離
專案技能存於 .claude/skills/，全域通用技能存於 ~/.claude/skills/。兩者容量獨立計算，背景分析器嚴禁跨層越權混雜。
目錄結構 · State Isolation
零侵入原則與自身技能邊界
autoharness 只管理自身帶有 .ledger.jsonl 標記的自動產生物件。使用者自行手動編寫的自訂技能完全受到寫入豁免與保護。
合規保證 · Self-Authored Immunity
觸發線索前置抵抗長度截斷
注入 Context 的技能描述強制截斷為 60 字元以內。將最關鍵的觸發條件放在前 40 字元，避免重要語意在 Context 壓縮時遺失。
調優實務 · IDX Truncation
真實會話提煉與修補演化實錄
以下展示 Claude Code 結合 autoharness 的真實對話進程：會話啟動時自動注入現存技能索引，工程編程累積達到 50 次調用門檻時觸發背景唯讀分析，提煉出專案技能經 Promoter 嚴格校驗後原子化落盤，並於後續會話精準命中與修補。
· stripe-webhook-verify: Stripe 簽章校驗與重試等冪處理 (loads: 12)
· db-migration-dryrun: 執行 Alembic 前自動驗證 SQL 回滾路徑 (loads: 8)
· sentry-error-tagger: 為異常用戶標註 tenant_id 與 request_id (loads: 4)
· [global] commit-emoji-clean: 維護 Conventional Commits 格式 (loads: 42)
$ You ›
我們要把支付回調的重試延遲改為指數退避，另外新增對重複 webhook 的 409 冪等快取。
claude: Claude ›
收到。分析現有支付回調架構，檢測到現存專案技能 stripe-webhook-verify
我將依照該規範更新 Redis 冪等鎖與指數退避演算法，並加入 Alembic 資料庫防護。
ok: ✓ SKILL.md body line count: 21 lines (limit: ≤25 lines)
ok: ✓ description character count: 58 chars (limit: ≤1024 chars)
ok: ✓ evidence slice stored: references/evidence-20261002-patch.md
ok: ✓ atomic rename: .claude/skills/stripe-webhook-verify/SKILL.md
ok: ✓ appended ledger: .claude/skills/stripe-webhook-verify/.ledger.jsonl
claude: Claude ›
已完成指數退避與 409 冪等處理，測試均已通過。
hl: autoharness 背景分析器已同步將本次冪等最佳實踐修補回 stripe-webhook-verify 技能。
$ You › claude --resume
ok: · stripe-webhook-verify: Stripe 簽章校驗與重試指數退避冪等快取 (loads: 13, patched: 1)
自學習 Harness 的核心價值在於無聲運作：不打斷開發思維，卻能將每一次排錯與決策轉化為下一次對話的確定性護欄。
提煉與修補機制的設計精髓
傳統手動編寫 Skill 常面臨「寫完即遺忘」或「重複造輪子」的問題。autoharness 透過背景唯讀分析器與唯一的寫入門戶 Promoter，在維持零延遲體感的同時，確保每一個落地技能皆附帶可回溯的 .ledger.jsonl 歷史與證據切片。
當既有技能需要微調時，分析器優先選擇 patch 現有規則而非盲目新增，徹底杜絕了提示詞庫隨時間無限膨脹的惡性循環。
防禦邊界與運行環境約束
自動化整合與延伸玩法指引
autoharness 提供彈性鉤子與環境變數，方便開發者將技能自學習能力與既有的 CI/CD 流程、通知中心及外部自動化管線深層整合。
進階玩法與整合實踐
**1. 桌面與 Webhook 事件通知。**設定 AUTOHARNESS_NOTIFY=webhook 與 AUTOHARNESS_NOTIFY_CMD，在背景分析器提煉出新技能或完成全庫整併時，自動發送系統推播或通知至 Slack/Discord 頻道。
**2. Fork Carrier 快取預熱機制。**在高並發會話環境中，將 AUTOHARNESS_CARRIER=fork 啟用程序級分叉載入，大幅縮短每次會話啟動時讀取檔案系統索引與歷程的延遲至毫秒級。
**3. 提取 LED 證據切片合成測試套件。**利用 references/evidence-*.md 中記錄的真實對話輸入與失敗情境，作為離線單元測試與 Regression Test 的合成輸入素材。
**4. 定期手動整併與清理。**隨時執行 /learn compact 觸發 Curator 的全庫去重邏輯，檢視相似度高於 85% 的微技能並將其合併為結構化規則。
最該讀的三份官方資源
① README.md——架構總覽、Hook 生命週期與配置規格完整清單。 ② agents/reflector.md——背景提煉分析器之唯讀 Intent 生成原理與 Prompt 規範。 ③ agents/curator.md——週期性全庫去重整併演算法與快照備份機制。
讓 Agent 越用越懂你的專案，而不是越用越臃腫——真正的自動化不是生成更多程式碼，而是沉澱確定性的決策邊界。