# 狀態與記憶工具

搜尋聊天、錯誤與動作歷史的工具。

| 工具 | 說明 |
|---|---|
| `chat_history` | 本 session 自己的行為紀錄。`mode=list` 列出近期執行，每筆一行並附 `task_id`；`mode=read` 完整展開一或多次執行 —— 當時的任務、呼叫過的每個工具與其回傳、最後的回覆（`scope=reference` 只保留昂貴的 payload，`scope=full` 全留）；`mode=tool_list` 把最近 16 次執行中值得重用的呼叫攤平，讓已付過成本的抓取在重跑前先被找到，`mode=tool` 則以 `task_id` + `name` 取回該次呼叫的原始輸出；`mode=search` 搜尋過往訊息，`match=semantic` 在近期訊息中比對語意、`match=keyword` 在含封存的完整歷史中比對文字（SQLite FTS5，trigram tokenizer），並以 `time_range` 限制範圍。這些紀錄存放於 daemon 自己的儲存層，檔案工具無法觸及 |
| `error_history` | 跨 session 保留的工具失敗紀錄。`mode=search` 以關鍵字查詢過往紀錄 —— 每筆都附有有效的修正方式；`mode=read` 以 8 碼 hash 讀取單筆（工具回傳 `no data: {hash}` 時使用）；`mode=write` 記錄一筆錯誤，含 `tool`、關鍵字、觀察到的行為、根因、採取的作法與 `outcome`。只有 `outcome=resolved` 會被儲存 —— `failed` 與 `abandoned` 可傳入但會被丟棄。search 上限 16 筆 |
| `reasoning_guide` | 一次取得本 turn 需要的所有 topic 規則集 —— 自 v1.0.26 起參數改為 `topics`（陣列，至少一個）取代單一 `topic`，結果以 `## <topic>` 標題串接各份規則。Topic：`tool_generate`、`tool_error`、`rag_web`、`market_analysis`、`targeted_read`、`ask_user`、`subagent_dispatch`、`write_todo`、`html_render`、`office`（建立或修改 `.docx` / `.xlsx` / `.pptx` 的規則，確保 Office 與 iWork 應用程式能開啟檔案）。取代原本各自獨立的 per-topic guide 工具 |
| `write_result` | v1.0.17 由 `write_report` 改名並新增 HTML 輸出。把單一長篇產出寫成輸出目錄下的 `report-YYYYMMDD-HHMMSS.md` 或 `.html`，並回傳含路徑的寫入回執 —— 也就是回覆只做摘要、不重印的研究 / 分析 / 比較本文，或一份完成的 HTML 頁面。`content` 為完整檔案內容；`format` 為 `md`（預設）或 `html`。輸出目錄為 `config.json` 的 `output_dir`（以 `/config` 設定），未設定時用 `~/Downloads`（存在時），否則為 `~/.config/agenvoy/download/`。其他檔案或既有檔案的修改 → `edit_file` |