vima-tech/Innate

層級角色

Innate 是輔助性工具 — 絕不能阻礙主任務。所有 Innate 的操作均為盡力而為。 若任何工具發生錯誤：以修正後的呼叫重試一次，若仍失敗則放棄並繼續執行。

何時回憶

僅在任務開始時且滿足以下條件才進行回憶：

• 任務領域具有已知的週期性模式（例如，特定程式碼庫、框架或協定）
• 任務涉及除錯或修復可能曾遇過的問題
• 架構/設計相關 — 先前的決策至關重要

跳過回憶的情況：快速的一次性指令、答案明確的問題、使用者已界定為全新領域且無先前脈絡的任務。

查詢表述

使用規範意圖，而非使用者的字面用詞。跨對話階段保持查詢一致性 — 同一類問題應始終使用相同的規範形式，因為 Innate 會針對每個查詢模式累積 情境統計資料。

使用者說	良好查詢	不良查詢
"為什麼啟動時會崩潰？"	startup crash sqlite init	為什麼啟動時會崩潰
"重構驗證流程"	auth flow session token handling	重構驗證流程
"為 API 加入速率限制"	rate limiting middleware pattern	"加入速率限制"
"除錯不穩定的測試"	flaky test race condition timing	"除錯不穩定測試"

呼叫：innate_recall(query=<規範意圖>, budget=4000, source="mcp")

將回憶到的知識片段注入您的工作脈絡。向使用者提及找到了哪些（如果有的話）相關 的先前知識 — 一句話即可。

自動回憶鉤子

當 Innate 透過鉤子安裝時，UserPromptSubmit 鉤子可能會自動將 一個 <innate-recall> 區塊注入對話中 — 它已經針對提示執行了相關性門檻檢查 的回憶，並帶有一個 trace_id。當您看到該區塊時：

• 重複使用其 trace_id 來執行後續的 innate_record — 不要 再次為同一任務呼叫 innate_recall（這會建立重複且懸空的追蹤）。
• 將其區塊視為您自己回憶的內容：應用有幫助的部分，然後以逐區塊的 判決（見下文）結束。
• 如果該區塊不存在且任務需要，請按照上述方式手動回憶。

該鉤子受相關性門檻控制，因此它的沉默意味著「沒有足夠高分的內容」— 並非「沒有 知識存在」。如果您懷疑鉤子可能遺漏了相關的先前知識，請手動回憶。

何時記錄

在產生實際成果（成功或失敗）的任務之後進行記錄。跳過記錄的情況：

• 探索性的來回討論，沒有明確結果
• 使用者中斷執行而尚未完成的任務
• 純粹的資訊檢索（使用者僅提出問題，未建置或更改任何內容）

結果規則

情況	結果
任務完成，使用者確認或接受結果	ok
任務失敗，方法錯誤，使用者不得不修正方向	fail
對話中斷，結果不明確	unknown

逐區塊判決 — 強制執行

這是 Innate 中最重要的合約：信心排名的好壞取決於您在此報告的精確度。 每次浮現區塊的回憶（無論手動或鉤子注入）都必須以逐區塊判決結束。 對於每個提供給您的區塊，它恰好屬於以下三類之一：

判決	含義	歸屬
已使用且有幫助	您應用了它，且它節省了時間 / 防止了錯誤	used=[id] 且 feedback_up=[id]
已使用但誤導	您應用了它，但它是錯誤的或誤導了您	used=[id] 且 feedback_down=[id]
未使用	已回憶但從未應用	完全省略（不要在 used 中列出）

保持訊號純淨的規則：

• used 僅列出您主動在推理或輸出中參考的區塊 — 通常 一到三個。切勿塞入僅被回憶的區塊。
• 如果您什麼都沒應用，這是一個真實且有價值的訊號：請明確設為 used=[] （已知無用）。不要跳過記錄 — 沉默不等於「沒有幫助」。
• 您 used 的區塊幾乎都應該同時帶有正向 或 負向訊號。一個已使用但沒有判決的區塊 浪費了您能提供的最強排名輸入。
• 對 feedback_down 誠實。您標記為負面的錯誤區塊會被審查和歸檔； 一個未被標記的錯誤區塊則會持續誤導未來的對話。

輸出摘要 — 結構化格式

撰寫一個自成一體且簡潔的句子，讓未來的代理能直接根據它採取行動。 使用以下結構：

<完成或學到的事> — <關鍵限制或方法> — <適用時機>

良好範例：

• 透過檢查 PRAGMA journal_mode 回應而非假設 WAL，修復了 SQLite WAL 模式檢測問題 — 在多進程設定的任何新資料庫連線時觸發
• 透過注入時鐘模擬解決了不穩定的驗證測試 — 真實系統時間會在令牌過期檢查中造成競爭條件
• 速率限制必須在驗證中介軟體之前套用，而非之後 — 否則未經認證的請求會繞過限制器

不良範例（過於模糊，無法重複使用）：

• 修復了錯誤
• 我幫助使用者處理了驗證問題
• 問題是時間點

output_summary 會成為可重複使用的知識區塊。如果它讀起來像一個故事，請將其 改寫為一個原則。偏好通用、可轉移的形式 — 移除儲存庫/檔案/函式名稱和 一次性識別碼，並將經驗教訓表達為下一個專案也能重複使用的形式；僅在 經驗教訓在沒有具體專案細節的情況下無法保留其意義時，才保留這些細節。 如果您無法寫出有用的摘要，請設定 output="unknown" 並跳過記錄。

呼叫：innate_record(trace_id=<id>, outcome=<ok|fail|unknown>, used=[<chunk_ids>], output_summary=<句子>)

明確回饋 — 為何重要

來自上述判決表的 feedback_up / feedback_down 列表是知識品質最快的訊號， 它們直接驅動排名和生命週期：同一個區塊上收到兩次負向訊號會觸發治理審查； 五次則會觸發自動歸檔。反之，重複的 used + feedback_up 是將 pending 區塊 提升為 active 的方式。不提供回饋會凍結知識庫；提供回饋則能讓好的知識上升， 壞的知識被淘汰。

提名 — 罕用且明確

僅對真正可推廣的經驗教訓使用 nomination 欄位 — 這些模式在下次出現這類問題時 將節省大量時間。少用。不用於每個任務。

提名格式（自成一體的原則）：

<原則> — <適用時機> — <應避免的事>

範例：

innate_record(..., nomination="SQLite 在部分 WHERE 子句上的 UNIQUE 索引需要在 ON CONFLICT 中使用完全相符的 WHERE — 適用於所有 upsert 模式；不含 WHERE 的簡潔 ON CONFLICT 會靜默跳過 upsert")

MCP 工具參考

工具	用途	備註
innate_recall	任務開始時（相關時）	使用規範查詢形式 — 一致的措辭會累積情境統計資料
innate_record	任務結束時（有實際成果時）	結構化的 output_summary + 精確的 used ID
innate_add	擷取已確認的洞見	始終使用 source="mcp"；進入 pending 狀態，等待審查
innate_spark	快速記錄稍後處理的想法	簡短的精煉形式；無需審查
innate_evolve	對話階段結束時	trigger="manual"；提煉日誌並整理知識庫
innate_inspect	健康檢查	區塊數量、債務比率、重建佇列
innate_appraise	在風險較高的步驟前進行直覺評估	僅供參考訊號 — 直覺，非精確答案。將其視為其中一個輸入；切勿讓它凌駕於您自己的分析之上。abstained=true 表示無依據 — 這是正確的，並非失敗

未經使用者明確要求，切勿呼叫：innate_approve、innate_archive、 innate_invalidate、innate_restore、innate_mature_spark、 innate_promote_spark、innate_drop_spark。

寫回決策

在結束長時間對話階段前，請執行此檢查清單：

1. 是否發現了非顯而易見的解決方案？（如：解決方案、隱藏限制、微妙的錯誤模式）
2. 是否浮現了通用、可轉移的技能、方法或技術？（偏好這些 — 將 專案特定的經驗教訓抽象為可重複使用的形式；僅在經驗教訓確實 無法通用化時，才保留專案特定的規則）
3. 使用者是否糾正了我可能重複犯下的錯誤假設？
4. 是否在多次失敗嘗試後，才艱難地獲得了一個洞見？
5. 回憶到的區塊是否主動提供了幫助？（記錄 feedback_up）
6. 回憶到的區塊是否有誤導？（記錄 feedback_down）

如果任何 1-4 項為「是」 → 向使用者提議：

"此對話階段發現了[一行描述]。要將其儲存到 Innate 嗎？"

僅在使用者確認後才呼叫 innate_spark 或 innate_add。絕不靜默寫入。

反逐字原則

嚴禁儲存原始對話文字。始終提煉為可重複使用的原則形式：

<原則> — <觸發情境> — <應避免的事>

❌ 逐字	✅ 精煉後
"使用者告訴我使用 WAL 模式，我透過更改 pragma 修復了它"	"SQLite WAL 模式必須透過 PRAGMA 回應驗證，而非假設 — 在寫入密集的多進程設定中開啟任何資料庫時觸發"
"我們因為時鐘偏差花了 2 小時除錯驗證問題"	"JWT 驗證必須考慮時鐘偏差容許值（≥30 秒）— 在擁有獨立系統時鐘的服務之間進行分散式驗證時觸發"

偏好通用而非專案特定

Innate 偏重於通用、可轉移的技能、方法和技術 — 這些知識能夠 跨專案產生回報，而不僅限於當前程式碼庫。當一項經驗教訓是專案特定的：

1. 嘗試將其抽象化 — 移除儲存庫/檔案/函式/路徑名稱和一次性識別碼，並重新 表述為下一個專案可以重複使用的原則。
2. 儲存抽象化後的形式。僅在經驗教訓確實無法通用化且不失去其意義時， 才保留具體的專案特定細節。

❌ 僅限專案	✅ 通用化後
"在此儲存庫中，record() 必須在 BEGIN IMMEDIATE 內執行"	"必須保持原子性的多步驟狀態變更應屬於一個獨占事務，而非逐步提交 — 適用於任何具有並發程序的 SQLite 寫入器"
"在 meta 表中設定 recall.budget=4000"	"將檢索預算暴露為可調參數而非硬編碼 — 讓回憶能隨脈絡視窗擴展而無需程式碼更改"

火花 vs. 筆記

使用 innate_spark	使用 innate_add
快速想法、未成形的直覺	已確認的可重複使用原則
尚未驗證	已在當前對話階段驗證
使用者說「先記下來」	使用者說「記住這個規則」

CLI 備用方案（若 MCP 未設定）

# 回憶
innate recall "<規範意圖>" --top 5 --format json --source cli

# 記錄結構化摘要
innate record <trace_id> --outcome ok \
  --used <id1>,<id2> \
  --output-summary "透過執行 Y 修復了 X — 適用於 Z 的情況" \
  --feedback up  # 或 down

# 擷取洞見
innate add "<原則> — <觸發> — <應避免的事>" \
  --trigger "<2-5 字的情境>" \
  --source agent

# 快速火花
innate spark "<1-2 句精煉的想法>"

# 對話階段結束
innate evolve --trigger manual
innate inspect

指令

以下斜線指令由 innate install 自動安裝到 ~/.claude/commands/， 並在每次重新執行 innate install 時更新。每個 command 區塊定義一個指令： --- 之前是中繼資料，--- 之後是指令主體（代理提示詞）。

name: innate-recall
description: 回憶與當前任務情境相關的先前 Innate 知識
---
為當前任務情境執行 innate_recall，並將結果注入此對話。

如果使用者在指令後提供了查詢，請完全使用該查詢進行回憶。
如果未提供查詢（$ARGUMENTS 為空），請從最近的
使用者訊息或當前任務意圖推斷查詢 — 使用**規範意圖**（例如 `sqlite wal mode init`，
而非 "為什麼這個會崩潰"）。保持查詢形式與您未來表述同一類問題的方式一致。

步驟：
1. 擬定規範查詢字串（從 $ARGUMENTS 或推斷的意圖）。
2. 使用 `query=<查詢>`, `budget=4000`, `source="mcp"` 呼叫 `innate_recall`。
3. 如果返回了知識：用一句話總結找到了什麼，然後將相關的
   區塊注入脈絡。
4. 如果為空：說「未找到與 "<查詢>" 相關的先前知識」— 不要編造。
5. 儲存 `trace_id` 以供稍後在 `/innate-record` 中使用。

name: innate-record
description: 以結果和結構化摘要關閉當前的 Innate 追蹤
---
以結果和摘要關閉當前的 Innate 追蹤。

從 $ARGUMENTS 解析：
- outcome：`ok`、`fail`、`unknown` 其中之一（若未指定，預設為 `ok`）
- 任何剩餘文字將成為 output_summary 的覆蓋值

步驟：
1. 從本次對話階段最近的 `innate_recall` 呼叫中識別出活躍的 trace_id。
   如果沒有可用的 trace_id，說「無活躍追蹤 — 請先執行 /innate-recall」。
2. 確定哪些被回憶的區塊 ID 在最終回應中**實際使用**（不僅是
   被回憶的候選項）。請精確 — 未使用的回憶區塊**不應**被列出。
3. 為未來直接閱讀此記錄的代理撰寫結構化的 output_summary：
   格式：`<完成了什麼> — <關鍵限制/方法> — <適用時機>`
   如果使用者在 $ARGUMENTS 中提供了摘要文字，請使用該文字。
4. 評估回饋：
   - 如果任何區塊直接有幫助 → 包含 `feedback_up=[chunk_id]`
   - 如果任何區塊有誤/誤導 → 包含 `feedback_down=[chunk_id]`
5. 使用 `trace_id`、`outcome`、`used=[<chunk_ids>]`、`output_summary` 以及適用的回饋，呼叫 `innate_record`。
6. 確認：「已記錄追蹤 <trace_id> 為 <outcome>。」

name: innate-save
description: 將已確認的洞見作為待審查知識區塊儲存到 Innate
---
將已確認的洞見作為待審查知識區塊儲存到 Innate。

$ARGUMENTS 是要儲存的洞見文字（必要）。如果為空，請詢問：「您想儲存什麼洞見？」

步驟：
1. 將 $ARGUMENTS 解析為洞見內容。
2. 判斷它是否為已確認的原則（使用 `innate_add`）或僅是稍後處理的想法（使用 `innate_spark`）。
3. 如果是已確認的原則，將其格式化為 `<原則> — <觸發情境> — <應避免的事>` 形式。
4. 使用適當的工具儲存。
5. 確認：「已儲存洞見。」