# 工具使用指南（Claude Code 风格精简版）

针对当前内置工具：`terminal`、`context_fetch`、`todo`、`note`、`memory`、`plan`。遵循“明确何时用 / 何时不用 / 如何用”，避免盲目调用。

## terminal
用途：只读检索与快速查看（ls/rg/cat/sed/head/tail/grep/git status/diff）。
- 何时用：定位文件/符号/报错；小范围查看片段；确认目录结构。
- 何时不用：写文件（用补丁）；大范围全库扫描（除非用户要求）；危险命令（rm/chmod/git reset --hard）。
- 调用示例：`terminal[{"command":"rg -n \"foo\" context/**/*.py","allow_dangerous":false}]`

## context_fetch
用途：聚合搜索（files/notes/memory/tests），自动摘要，控制预算。
- 何时用：需要“更多证据”时；搜类名/函数名/错误栈；需要相关笔记/记忆；比单独 note/memory 搜索更省步数。
- 何时不用：已经有足够证据；用户仅问对话历史。
- 调用示例：`context_fetch[{"sources":["files","notes"],"query":"ContextBuilder","paths":"context/**/*.py"}]`

## todo
用途：多步骤任务跟踪。状态：pending | in_progress（仅 1 个）| completed。
- 何时用：3 步以上或多文件/多特性；用户列出多项需求；跨回合/需确认的任务；开始工作前先标记 in_progress，完成后立即 completed。
- 何时不用：单一步、琐碎或纯问答。
- 示例：
  - `todo[{"action":"add","title":"设计简介页布局","desc":"头部/简介/技能","status":"pending"}]`
  - `todo[{"action":"update","id":1,"status":"in_progress"}]`
  - `todo[{"action":"update","id":1,"status":"completed"}]`
  - `todo[{"action":"list"}]`

## note
用途：结构化笔记（action/decision/blocker/task_state 等），Markdown 持久化。
- 何时用：记录关键结论/风险/阻塞；补丁成功/失败总结；阶段小结。
- 何时不用：临时想法可先留在对话，不必频繁写笔记。
- 示例：`note[{"action":"create","title":"Patch applied","content":"...","note_type":"action","tags":["patch"]}]`

## memory
用途：情景记忆（SQLite）；跨会话回忆“发生过什么”。默认不开自动写，需要显式添加。
- 何时用：需要在未来回忆本次决策/阻塞/结论；会话结束前写一条小结；复用过往经验时可先 search。
- 何时不用：即时对话短期内容已有 history；信息尚不确定。
- 示例：
  - `memory[{"action":"add","memory_type":"episodic","content":"完成 hello.html 样式改造，见补丁...","importance":0.7}]`
  - `memory[{"action":"search","query":"hello.html 样式","memory_types":["episodic"],"limit":5}]`

## plan
用途：显式规划工具，生成分步计划。
- 何时用：任务模糊或明显多步骤；用户要求出计划；执行前需要拆解。
- 何时不用：非常简单的一步任务。
- 示例：`:plan 添加 dark mode 开关` 或 `plan[{"goal":"优化渲染性能，先梳理瓶颈再改"}]`

## 重要提醒
- 写/改文件必须用补丁（*** Begin Patch ...），禁止 `cat > file` / Here-Doc / tee / 重定向写盘。
- 先用已有上下文推理，不足再调用工具；避免无端多次搜索。
- todo 只保持 1 个 in_progress；完成立刻标记完成；阻塞则新增一条说明阻塞。