minorcell · Dec 10, 2025 · Dec 10, 2025
diff --git a/docs/code-review.md b/docs/code-review.md
diff --git a/docs/memory.md b/docs/memory.md
diff --git a/docs/todo-write.md b/docs/todo-write.md
diff --git a/docs/tool/bash.md b/docs/tool/bash.md
@@ -0,0 +1,25 @@
+# Memo CLI `bash` 工具
+
+执行任意 bash 命令，返回 exit/stdout/stderr 结果，主要用于调试与脚本执行（安全性由上层控制）。
+
+## 基本信息
+- 工具名称：`bash`
+- 描述：在 shell 中执行命令，返回 exit/stdout/stderr
+- 文件：`packages/tools/src/tools/bash.ts`
+- 确认：否
+
+## 参数
+- `command`（字符串，必填）：要执行的完整命令。
+
+## 行为
+- 使用 `bash -lc <command>` 在当前环境中运行；继承进程 `env`。
+- 捕获 stdout/stderr，等待子进程退出。
+- 组装为单行文本返回：`exit=<code> stdout="<...>" stderr="<...>"`。
+- 任何异常（如 spawn 失败）返回错误消息，标记为 `isError=true`。
+
+## 输出示例
+`exit=0 stdout="hello\n" stderr=""`
+
+## 注意
+- 不做命令安全校验，请在上层控制可执行内容。
+- `command` 为空白时直接报错，不会执行。
diff --git a/docs/tool/edit.md b/docs/tool/edit.md
@@ -0,0 +1,29 @@
+# Memo CLI `edit` 工具
+
+在文件中替换指定文本，支持单次或全局替换。
+
+## 基本信息
+- 工具名称：`edit`
+- 描述：在文件中替换文本，支持 replace_all
+- 文件：`packages/tools/src/tools/edit.ts`
+- 确认：否
+
+## 参数
+- `file_path`（字符串，必填）：目标文件路径（标准化为绝对路径）。
+- `old_string`（字符串，必填）：要替换的原文本。
+- `new_string`（字符串，必填）：替换后的文本。
+- `replace_all`（布尔，可选）：是否替换所有出现，默认为单次替换。
+
+## 行为
+- 若文件不存在返回错误。
+- 读取全文，检查是否包含 `old_string`；未找到则报错。
+- `replace_all=true` 时按分割重组替换所有出现，计数为出现次数；否则仅替换首次匹配，计数为 1。
+- 若替换后内容未变化返回提示；否则覆盖写回并返回计数与路径。
+- 异常时返回错误消息。
+
+## 输出示例
+`替换完成: file=/abs/path/file.ts count=2`
+
+## 注意
+- 不校验唯一性，`replace_all=false` 也只替换首个匹配。
+- 不展示差异，也不处理编码/二进制文件。
diff --git a/docs/tool/glob.md b/docs/tool/glob.md
@@ -0,0 +1,28 @@
+# Memo CLI `glob` 工具
+
+按 glob 模式扫描目录并返回匹配的绝对路径列表。
+
+## 基本信息
+- 工具名称：`glob`
+- 描述：按 glob 模式匹配文件，返回绝对路径列表
+- 文件：`packages/tools/src/tools/glob.ts`
+- 确认：否
+
+## 参数
+- `pattern`（字符串，必填）：glob 模式（例如 `src/**/*.ts`）。
+- `path`（字符串，可选）：扫描起点目录；默认当前工作目录。
+
+## 行为
+- 使用 `Bun.Glob` 在指定 `cwd` 下扫描。
+- 将所有匹配项标准化为绝对路径，按发现顺序返回（以换行分隔）。
+- 无匹配时返回提示“未找到匹配文件”。
+- 执行异常时返回错误消息。
+
+## 输出示例
+```
+/abs/workspace/src/a.ts
+/abs/workspace/src/sub/b.ts
+```
+
+## 注意
+- 不会自动忽略 `node_modules` 等目录，需要在 pattern 中自行过滤。
diff --git a/docs/tool/grep.md b/docs/tool/grep.md
@@ -0,0 +1,34 @@
+# Memo CLI `grep` 工具
+
+基于 ripgrep 搜索文本，支持输出匹配内容、仅文件列表或计数。
+
+## 基本信息
+- 工具名称：`grep`
+- 描述：基于 ripgrep 查找文本，支持输出匹配内容、文件列表或计数
+- 文件：`packages/tools/src/tools/grep.ts`
+- 确认：否
+
+## 参数
+- `pattern`（字符串，必填）：要搜索的正则模式。
+- `path`（字符串，可选）：搜索起点目录，默认当前工作目录。
+- `output_mode`（枚举，可选）：`content`（默认，含行号）、`files_with_matches`（仅文件列表）、`count`（计数）。
+- `glob`（字符串，可选）：附加 `--glob` 过滤。
+- `-i`（布尔，可选）：忽略大小写。
+- `-A`/`-B`/`-C`（非负整数，可选）：上下文行数（后/前/两侧）。
+
+## 行为
+- 依赖系统 `rg`，未安装时直接报错。
+- 组装对应 `rg` 参数：`--line-number --no-heading`（content）、`-l`（files）、`-c`（count）；禁用颜色。
+- 将 `pattern` 与 `path` 传给 `rg` 执行，收集 stdout/stderr。
+- 退出码 2 视为错误；退出码 1 且无输出视为“未找到匹配”；否则返回命令输出。
+- 异常时返回错误消息。
+
+## 输出示例（content 模式）
+```
+src/index.ts:12: const x = 1;
+src/index.ts:18: console.log(x);
+```
+
+## 注意
+- 直接依赖外部 `rg`，需确保 PATH 可用。
+- 未做结果分页，大量匹配会一次性返回。
diff --git a/docs/tool/read.md b/docs/tool/read.md
@@ -0,0 +1,29 @@
+# Memo CLI `read` 工具
+
+读取指定文件内容，可按行号区间截取并附带行号输出。
+
+## 基本信息
+- 工具名称：`read`
+- 描述：读取指定文件内容，可按 offset/limit 截取并附带行号
+- 文件：`packages/tools/src/tools/read.ts`
+- 确认：否
+
+## 参数
+- `file_path`（字符串，必填）：目标文件路径（标准化为绝对路径）。
+- `offset`（正整数，可选）：起始行（1-based），默认 1。
+- `limit`（正整数，可选）：读取行数上限，默认读取至文件末尾。
+
+## 行为
+- 通过 `normalizePath` 生成绝对路径；文件不存在时返回错误。
+- 读取文本内容，按 `\r?\n` 分行。
+- 从 `offset` 开始截取至 `offset + limit`（不超出文件末尾），每行前加行号（1-based）。
+- 将结果拼成文本返回；异常时返回错误消息。
+
+## 输出示例
+```
+1: first line
+2: second line
+```
+
+## 注意
+- 未做二进制文件检测，二进制内容读取后仍按文本分行。
diff --git a/docs/tool/save_memory.md b/docs/tool/save_memory.md
@@ -0,0 +1,27 @@
+# Memo CLI `save_memory` 工具
+
+将简短事实/偏好追加到本地记忆文件（默认 `~/.memo/memo.md`），供后续会话注入系统提示词。
+
+## 基本信息
+- 工具名称：`save_memory`
+- 描述：保存一条简短事实/偏好，跨会话复用（写入 ~/.memo/memo.md）
+- 文件：`packages/tools/src/tools/save_memory.ts`
+- 确认：否
+
+## 参数
+- `fact`（字符串，必填）：要保存的简短事实，限制 ≤120 字符。
+
+## 行为
+- 清洗输入：替换换行为空格、压缩空白、trim；为空时报错。
+- 解析存储路径：优先 `MEMO_HOME` 环境变量，否则 `~/.memo/memo.md`；递归创建父目录。
+- 读取现有内容（若存在），截取 header `## Memo Added Memories` 之后的条目（前缀 `- `）。
+- 追加新 fact，保留最近 50 条，重新写入带 header 的列表。
+- 写入异常时返回错误；维护过程中的警告仅打印到控制台。
+- 成功返回写入路径。
+
+## 输出示例
+`已保存记忆到: /Users/you/.memo/memo.md`
+
+## 注意
+- 仅维护单一分节，不保留其它自定义内容。
+- 进程外共享文件，需确保对路径有写权限。
diff --git a/docs/tool/todo.md b/docs/tool/todo.md
@@ -0,0 +1,34 @@
+# Memo CLI `todo` 工具
+
+进程内维护的待办列表，支持新增、替换、更新、删除，最多 10 条，不持久化。
+
+## 基本信息
+- 工具名称：`todo`
+- 描述：管理待办列表（add/update/remove/replace），最多 10 条，不持久化
+- 文件：`packages/tools/src/tools/todo.ts`
+- 确认：否
+
+## 参数
+使用 discriminated union：
+- `type`：`add` / `replace` / `update` / `remove`。
+- 当 `type=add`：`todos` 为待添加任务数组，每项需提供 `content`、`status`（`pending`/`in_progress`/`completed`）、`activeForm`，长度 1–10。
+- 当 `type=replace`：同上，但会清空后替换全部任务。
+- 当 `type=update`：`todos` 项额外需要 `id`（存在的任务 id），不可重复，长度 1–10。
+- 当 `type=remove`：`ids` 字符串数组，长度 ≥1。
+- 字段约束：`content` 1–100 字符，`activeForm` 1–120 字符。
+
+## 行为
+- 全部状态存于进程内内存；进程退出即清空。
+- `add`：若超出上限 10 条返回错误；否则生成 `id` 并追加。
+- `replace`：清空并替换为新列表（仍受 10 条限制）。
+- `update`：校验 id 存在且不重复，逐项更新内容、状态、activeForm。
+- `remove`：删除给定 id；若无任何命中返回错误。
+- 返回 JSON 字符串，包含当前任务列表与操作信息（op/count/tasks/added/updated/removed/replaced）。
+- 异常或规则错误时返回错误消息。
+
+## 输出示例
+`{"op":"add","count":2,"tasks":[{"id":"...","content":"do A","status":"pending","activeForm":"task A"}],"added":[...],"updated":null,"removed":null,"replaced":false}`
+
+## 注意
+- 不做持久化，也无并发锁；适合单进程短期待办。
+- 上层应保存返回的 `id` 以便后续更新/删除。
diff --git a/docs/tool/webfetch.md b/docs/tool/webfetch.md
@@ -0,0 +1,32 @@
+# Memo CLI `webfetch` 工具
+
+受限 HTTP GET，返回处理后的纯文本正文（会自动剥离 HTML 标签），带超时与大小限制。
+
+## 基本信息
+- 工具名称：`webfetch`
+- 描述：HTTP GET 请求，返回处理后的纯文本正文（自动剥离 HTML 标签）
+- 文件：`packages/tools/src/tools/webfetch.ts`
+- 确认：否
+
+## 参数
+- `url`（字符串，必填）：请求的完整 URL，协议仅支持 `http: / https: / data:`。
+
+## 行为
+- 校验 URL 与协议；不支持的协议或无效 URL 直接报错。
+- 10s 超时，通过 AbortController 中止。
+- 响应体限制 512000 bytes：`content-length` 超限直接拒绝；流式读取时超限则中止。
+- 对 HTML 内容进行剥离：
+  - 去除 `<script>/<style>`，将块级元素/换行标签转换为换行，`<li>` 前置 `- `，去掉其他标签。
+  - 进行常见实体解码，压缩多余空白与空行。
+- 非 HTML 直接 `trim`。
+- 预览文本最长 4000 字符；超出时截断并标注 `text_truncated=true`。
+- 返回格式：`status=<code> bytes=<len> text_chars=<chars> text="<preview>" [text_truncated=true] [source=html_stripped]`。
+- 超时、中止或 fetch 异常返回错误消息并标记 `isError=true`。
+
+## 输出示例
+`status=200 bytes=10240 text_chars=3800 text="Example content..." source=html_stripped`
+
+## 注意
+- 仅 GET，不发送自定义头；未处理重定向/压缩细节。
+- 一律按 UTF-8 解码，非 UTF-8 站点可能乱码。
+- 大型 `data:` URL 仍需经过 fetch，可能受体积限制中止。
diff --git a/docs/tool/write.md b/docs/tool/write.md
@@ -0,0 +1,29 @@
+# Memo CLI `write` 工具
+
+创建或覆盖写入文件内容，必要时递归创建父目录。
+
+## 基本信息
+- 工具名称：`write`
+- 描述：创建或覆盖文件，传入 file_path 与 content
+- 文件：`packages/tools/src/tools/write.ts`
+- 确认：否
+
+## 参数
+- `file_path`（字符串，必填）：要写入的目标路径（标准化为绝对路径）。
+- `content`（可选）：写入内容，支持字符串、数字、布尔、null、数组、对象、`Uint8Array`、`ArrayBuffer`。
+
+## 行为
+- 通过 `normalizePath` 标准化路径；递归创建父目录。
+- 内容归一化：
+  - 字符串：按原文写入。
+  - `Uint8Array`/`ArrayBuffer`：按二进制写入。
+  - 其他类型：序列化为 JSON（带缩进）。
+- 调用 `Bun.write` 覆盖目标文件，返回写入信息（文本长度或字节数）。
+- 异常时返回错误消息。
+
+## 输出示例
+`已写入 /abs/path/file.txt (overwrite, text_length=12)`
+
+## 注意
+- 始终覆盖写入，不做差异检查。
+- `content` 省略时会写入序列化后的空字符串（JSON 结果）。