MINARA已學習偏好
GET / POST /v1/preferences：列出、查看、批准、拒絕和棄用從用戶對話中提取的偏好。
偏好演進系統從對話中提取持久的用戶偏好（例如 “我從不交易迷因幣”、“簡潔回覆”、“優先鏈上數據而非 K 線”），並在它們生效前使其經過狀態機。
M1 提供只讀端點；M2 增加了 approve / reject / deprecate 變更操作及列表端點的 total 字段；M3 增加了 undo 端點和對 hard_constraint 記錄的工具級執行。
M4 增加橋接機制：每次遷移到 active 現在都會將偏好寫入相應下游存儲。對於命名有效 11 維標籤的硬約束寫入 user_tags；每條 personal_style 記錄寫入 memories 鏡像（使風格提示可被 FTS 索引）；目標為場景的 behavioral_preference 記錄寫入 scenario-classifier 增益；目標為 methodology ID 的記錄寫入方法論優先級乘數。離開 active（deprecate / reject）的遷移會反轉每一項寫入。橋接寫入盡力執行，絕不阻塞狀態遷移；失敗通過帶 learning/preference-bridge 的日誌暴露。完整寫入路徑圖請參閱自我改進系統。
每項偏好有三條分類軸：
kind：personal_style、behavioral_preference、hard_constraint之一。dimension：risk、chain、asset_class、timing、methodology、style、constraint之一。state：proposed、active、deprecated、rejected之一。
完整生命週期請參閱 ~/.claude/plans/autoclaw-agent-agent-lazy-lollipop.md 中的項目計劃。
GET /v1/preferences
使用可選篩選條件列出偏好。
| 方法 | GET |
| 路徑 | /v1/preferences |
| 認證 | 設置 GATEWAY_AUTH_TOKEN 時需要 Authorization: Bearer <token> |
| 查詢 | state、dimension、kind、limit（默認 100，最大 500） |
| 類別 | learning |
響應 200：
{
"ok": true,
"data": {
"items": [
{
"id": "pref_a1b2c3d4e5f6",
"user_id": "default",
"dimension": "asset_class",
"kind": "hard_constraint",
"statement": "Never trade meme coins",
"structured": { "operator": "exclude", "subjects": ["meme_coin"], "scope": ["buy", "swap"] },
"evidence": null,
"source": "manual",
"state": "active",
"confidence": 0.65,
"times_observed": 4,
"times_violated": 0,
"dedup_key": "asset_class:hard_constraint:never trade meme coins",
"bridges_user_tag": null,
"approved_at": "2026-04-15T08:00:00Z",
"last_ask_at": null,
"created_at": "2026-04-13T10:00:00Z",
"updated_at": "2026-04-15T08:00:00Z"
}
],
"count": 1,
"total": 1
}
}count 是本頁中的記錄數（≤ limit）；total 是整張表中符合篩選條件的記錄數。當 count == limit && total > limit 時，請縮小篩選條件或使用更小的 limit 值分頁，以查看其餘記錄。
state、dimension、kind 或 limit 無效時，響應 422。
GET /v1/preferences/:id
按 ID 獲取單個偏好。
| 方法 | GET |
| 路徑 | /v1/preferences/:id |
| 認證 | 設置 GATEWAY_AUTH_TOKEN 時需要 Authorization: Bearer <token> |
| 類別 | learning |
響應 200：形狀與上述 items[] 元素相同。
ID 不存在時，響應 404。
POST /v1/preferences/:id/approve
將 proposed 記錄提升為 active。如果尚未設置，則設置 approved_at。等同於 REPL /preferences approve 命令和 minara preferences approve <id>。
| 方法 | POST |
| 路徑 | /v1/preferences/:id/approve |
| 認證 | 設置 GATEWAY_AUTH_TOKEN 時需要 Authorization: Bearer <token> |
| 請求體 | 可選的 { "reason": "..." }（審計記錄，≤ 500 個字符） |
| 類別 | learning |
響應 200：標準封裝中的已更新偏好記錄。
ID 未找到時，響應 404。
響應 409：無效遷移（例如記錄已是 rejected），或其他寫入者搶先完成（CAS 丟失；重新 GET 查看當前狀態）。
POST /v1/preferences/:id/reject
將 proposed（或在退役現有偏好時的 active）提升為 rejected。形狀與上述 approve 相同；rejected 是終態，記錄作為審計軌跡保留，但不會再次浮現。
| 方法 | POST |
| 路徑 | /v1/preferences/:id/reject |
| 認證 | 設置 GATEWAY_AUTH_TOKEN 時需要 Authorization: Bearer <token> |
| 請求體 | 可選的 { "reason": "..." } |
| 類別 | learning |
POST /v1/preferences/:id/deprecate
將 active 提升為 deprecated。偏好不再注入系統提示詞，但記錄會保留，因此相似度閘門仍能將重新提議識別為重複項並跳過再次詢問。如果希望記錄永不作為相似陳述匹配再次出現，請使用 reject。
| 方法 | POST |
| 路徑 | /v1/preferences/:id/deprecate |
| 認證 | 設置 GATEWAY_AUTH_TOKEN 時需要 Authorization: Bearer <token> |
| 請求體 | 可選的 { "reason": "..." } |
| 類別 | learning |
POST /v1/preferences/:id/undo
在配置的撤銷窗口內撤回由強信號自動激活的 hard_constraint（默認 24 小時，參閱 PREFERENCE_HARD_UNDO_WINDOW_HOURS）。記錄遷移為 deprecated，工具級執行會立即停止，審計軌跡（auto_activated_at 時間戳、原始陳述）會被保留。這是 M3 引入的功能。
當以下任一情況成立時，請使用 deprecate：(a) 偏好是手動批准的（所以 auto_activated_at 為 null），或 (b) 窗口已過期。
| 方法 | POST |
| 路徑 | /v1/preferences/:id/undo |
| 認證 | 設置 GATEWAY_AUTH_TOKEN 時需要 Authorization: Bearer <token> |
| 請求體 | 可選的 { "reason": "..." }（≤ 500 個字符） |
| 類別 | learning |
響應 200：記錄已棄用。
響應 404：ID 未找到。
響應 410 Gone：記錄已自動激活但撤銷窗口已過期。請改用 deprecate。
響應 413：請求體大於 4 KB。
響應 422：記錄是手動批准的（沒有 auto_activated_at）。請改用 deprecate。
響應 409：CAS 丟失（其他寫入者先更改了記錄）或無效的結構遷移。