docs(tools): cross-framework usage guide + refactor plan

tools.md additions:
- "跨框架使用（CLI/MCP）" section: design philosophy (stateless -> CLI,
  stateful -> MCP), CLI entry conventions, trace_id fallback pattern,
  double-JSON encoding avoidance, MCP integration via .mcp.json (not
  settings.json — Claude Code doesn't read mcpServers from there)
- New entries in the builtin tool table: read_images, toolhub_*, ask/
  upload_knowledge
- read_file vs read_images usage guidance with adaptive-layout table
- Skill installation convention (~/.claude/skills/<name>/SKILL.md) and
  the size distinction: SKILL.md is runtime-loaded, keep short; tools.md
  is for developers, can go long

tools-refactor-plan.md (new):
- Captures the discovery-pattern philosophy and per-family migration
  plans for two upcoming refactors that will happen in a later session:
  1. Content tools (search_posts / youtube_search / x_search) — merge
     into content_platforms() + content_search() + content_detail() in
     the same spirit as toolhub_search + toolhub_call
  2. Browser tools — collapse 28 @tool functions into ~11 verb-based
     tools using Literal enum actions. Browser is NOT a good fit for
     dynamic discovery since the differences are in parameters, not in
     capabilities
- Explicitly rejects "discovery-based browser tools" and "full MCP
  client wrapper" paths, with reasoning
- Lists all open design questions that must be decided before
  implementation starts

agent/docs/tools-refactor-plan.md

@@ -0,0 +1,474 @@
+# 工具体系改造方案（Refactor Plan）
+
+> 本文档是**未来规划**，不是现状描述。当前工具体系的状态请看 [`tools.md`](./tools.md)。
+>
+> 当方案落地后，记得把本文档对应的章节删除或合并到 `tools.md`。
+
+## 背景
+
+本框架的 `@tool` 注册体系经过一段时间的积累后，暴露了几个结构性问题：
+
+1. **工具粒度和组织方式是按"后端架构"而不是"任务语义"划分的**。典型表现：`search_posts`（聚合 9 个中文平台）和 `x_search`（独立）本质上是同一类任务，却因为后端一个统一 endpoint、一个独立 endpoint 就被分成了两个工具
+2. **浏览器工具有 28 个 @tool，LLM 选择负担严重超标**
+3. **沙箱工具已经不再需要**（原本是给运行工具准备的，但工具已经被提取出来单独处理）
+4. **同一套哲学没有贯彻到所有工具族**——toolhub 已经用了"动态发现"模式（search → call），但其他多后端的工具族还是"每个后端一个工具"
+
+本方案解决前两个问题（沙箱直接删除，不需要方案），确立一套**统一的工具设计哲学**供未来所有新工具族参考。
+
+---
+
+## 核心设计哲学：按任务语义划分 + 按规模选择模式
+
+### 哲学 1：LLM 心智负担分四类
+
+- **选择负担**：一堆工具中挑一个
+- **参数构造负担**：知道该工具要哪些参数
+- **流程负担**：需要按什么顺序调几次工具
+- **错误恢复负担**：失败时怎么修复
+
+工具设计要**平衡**这四类负担，而不是只优化其中一类。
+
+### 哲学 2：按"任务语义"而非"后端架构"划分工具
+
+工具的边界应该跟 LLM 的心智模型对齐，而不是跟后端服务的架构对齐。
+
+**反例（现状）**：LLM 看到 `search_posts` / `youtube_search` / `x_search` 三个并列工具，需要记住"中文平台用前者，YouTube 用中者，X 用后者"——这是后端知识泄露到工具层。
+
+**正确姿势**：LLM 看到一个统一的 `content_search(platform, keyword, ...)`，后端路由对 LLM 不可见。
+
+### 哲学 3：按"工具族规模"选择静态或动态模式
+
+| 场景 | 模式 | 代表 |
+|---|---|---|
+| 单一职责工具（正交能力） | 静态扁平 | `read_file` / `bash_command` |
+| 小规模异构工具族（3-10 个） | 静态扁平 + 良好命名 | `knowledge_*` / `sandbox_*` |
+| 中等规模异构工具族（10-20 个） | **语义合并**（Literal 枚举动词） | 浏览器工具 |
+| 大规模多实例工具族（20+ 个同类异质） | **动态发现**（toolhub 模式） | 内容搜索、远程工具库 |
+
+判断标准：**工具之间的差异主要在"参数"还是"能力"？**
+- 差异在参数（navigate/click/type 都是"DOM 操作"，只是参数不同）→ 静态合并，用 Literal 动词
+- 差异在能力（9 个平台各有各的搜索语义和专用参数）→ 动态发现
+
+---
+
+## 方案一：内容工具族 → 动态发现模式
+
+### 现状
+
+| 工具 | 后端 | 平台 |
+|---|---|---|
+| `search_posts(keyword, channel, ...)` | `aigc-channel.aiddit.com/data` | 9 个中文平台 |
+| `select_post(index)` | 内存缓存 | 同上 |
+| `get_search_suggestions(keyword, channel)` | `aigc-channel.aiddit.com/suggest` | 同上 |
+| `youtube_search(keyword)` | `crawler.aiddit.com/youtube/keyword` | YouTube |
+| `youtube_detail(content_id, ...)` | `crawler.aiddit.com/youtube/detail` + yt-dlp | YouTube |
+| `x_search(keyword)` | `crawler.aiddit.com/x/keyword` | X |
+| `import_content(plan, data)` | `aigc-channel.aiddit.com/weixin/auto_insert` | 长文导入（非搜索） |
+| `extract_video_clip(...)` | 本地 ffmpeg | 媒体处理（非搜索） |
+
+### 新方案
+
+**3 个统一入口 + N 个内部实现函数（非 @tool）**
+
+```python
+@tool()
+async def content_platforms() -> ToolResult:
+    """列出所有支持的内容平台及其搜索参数 schema。
+
+    建议在 session 开始时调一次，后续 content_search / content_detail 调用时
+    依据此返回构造参数。返回内容在 session 内可以缓存。
+    """
+    return ToolResult(output=json.dumps({
+        "xhs": {
+            "name": "小红书",
+            "backend": "aigc-channel",
+            "search_params": {
+                "sort_type": {
+                    "values": ["综合排序", "最新发布", "最多点赞"],
+                    "default": "综合排序"
+                },
+                "publish_time": {
+                    "values": ["不限", "近1天", "近7天", "近30天"],
+                    "default": "不限"
+                },
+                "content_type": {
+                    "values": ["不限", "图文", "视频", "文章"],
+                    "default": "不限"
+                },
+                "filter_note_range": {
+                    "values": ["不限", "1分钟以内", "1-5分钟", "5分钟以上"],
+                    "default": "不限",
+                    "note": "仅视频内容生效"
+                }
+            },
+            "detail_mode": "cache_index",
+            "extras_example": {
+                "sort_type": "最新发布",
+                "publish_time": "近7天"
+            }
+        },
+        "youtube": {
+            "name": "YouTube",
+            "backend": "crawler",
+            "search_params": {},
+            "detail_mode": "content_id",
+            "detail_extras": {
+                "include_captions": {"type": "bool", "default": True},
+                "download_video": {"type": "bool", "default": False}
+            },
+            "extras_example": {}
+        },
+        "x": {
+            "name": "X (Twitter)",
+            "backend": "crawler",
+            "search_params": {},
+            "detail_mode": "not_supported",
+            "extras_example": {}
+        },
+        # ... 9 个中文平台 + YouTube + X，总共 11 个
+    }))
+
+
+@tool()
+async def content_search(
+    platform: str,
+    keyword: str,
+    max_count: int = 20,
+    extras: Optional[Dict[str, Any]] = None,
+) -> ToolResult:
+    """跨平台内容搜索，返回带索引编号的封面拼图 + 结构化列表。
+
+    参数说明：
+        platform: 平台标识，如 'xhs'、'youtube'、'x'。完整列表见 content_platforms。
+        keyword: 搜索关键词。
+        max_count: 返回条数上限，默认 20。
+        extras: 平台专用参数。如果不清楚某平台支持什么，先调用 content_platforms
+                查看 search_params 字段。xhs 支持 sort_type / publish_time /
+                content_type / filter_note_range；YouTube / X 当前无额外参数。
+
+    返回：
+        ToolResult.images 含 1 张带索引编号的封面拼图；output 含列表和每条记录的
+        元数据。拼图遵循 read_images 的自适应布局规则（最多 12 张）。
+    """
+
+
+@tool()
+async def content_detail(
+    platform: str,
+    identifier: str,
+    extras: Optional[Dict[str, Any]] = None,
+) -> ToolResult:
+    """查看内容详情。identifier 的含义因平台而异（见 content_platforms 的 detail_mode）。
+
+    - xhs / gzh / douyin / ...: identifier 是 content_search 返回的索引（1-based），
+      从 session 级缓存取完整记录
+    - youtube: identifier 是 video_id；extras 可传 include_captions / download_video
+    - x: 当前不支持详情查看
+    """
+```
+
+### 内部实现（不注册给 LLM）
+
+```
+agent/tools/builtin/content/
+├── __init__.py           # 空
+├── tools.py              # 3 个 @tool 入口
+├── registry.py           # PLATFORM_IMPLS 路由表
+└── platforms/
+    ├── aigc_channel.py   # 9 个中文平台的 search / detail / suggest 实现
+    ├── youtube.py        # youtube_search / youtube_detail 纯函数
+    └── x.py              # x_search 纯函数
+```
+
+### 迁移步骤
+
+1. 新建 `agent/tools/builtin/content/` 目录结构
+2. 把 `search.py` 的 `search_posts` / `select_post` / `get_search_suggestions` 逻辑移到 `content/platforms/aigc_channel.py`，拆成按 channel 分的纯函数
+3. 把 `crawler.py` 的 `youtube_search` / `youtube_detail` / `x_search` 移到 `content/platforms/`
+4. 在 `content/tools.py` 写 3 个 @tool 入口，内部调用路由
+5. 从 `builtin/__init__.py` 删除旧的 `search_posts` / `youtube_search` / `x_search` 等导出
+6. 添加新的 `content_platforms` / `content_search` / `content_detail` 导出
+7. 更新现有 prompt 里对旧工具的引用（**破坏性改动**）
+8. `extract_video_clip` 和 `import_content` 不搬——它们不是搜索工具，保留在原位或移到 `content/media.py` / `content/ingestion.py`
+
+### 未决策的设计问题
+
+1. **`extras` 的 schema 怎么处理？**
+   - 方案 i：声明为 `Optional[Dict[str, Any]]`，LLM 从 `content_platforms()` 返回的 schema 文本里学参数——**推荐**
+   - 方案 ii：为每个平台单独生成 schema（discriminated union），本框架 `SchemaGenerator` 当前不支持
+   - 方案 iii：把常用的平台专用参数都显式列在 `content_search` 签名里，用 Optional——签名臃肿，不如方案 i
+
+2. **缓存 `_search_cache` 的生命周期**
+   - 现状：进程内字典，进程重启就丢
+   - 问题：CLI 模式下每次进程都是新的，`content_detail(platform="xhs", identifier=3)` 拿不到缓存
+   - 方案：用磁盘持久化缓存 `/tmp/content_cache_{trace_id}.json`，配合之前给 toolhub/librarian 做的 trace_id 三级回退机制，同 session 内 CLI 调用也能复用
+
+3. **拼图的图片数量是否和 `read_images` 一致（12 张上限）？**
+   - read_images 是"让 LLM 看清"，12 是硬上限
+   - 内容搜索是"让 LLM 浏览"，可能需要更多（20-30 条也常见）
+   - 建议：区分"详查模式"（layout=detail，≤12）和"概览模式"（layout=overview，≤25，每格更小）
+
+4. **X 的 `content_detail` 怎么处理？**
+   - 当前 `x_search` 没有配对的 detail 工具
+   - 要么 `content_platforms` 里标明 `detail_mode: "not_supported"`，要么后端补一个 X 详情接口
+
+### 新增后的用户流程
+
+```
+Step 0（session 开始时一次）: content_platforms() → 所有平台 schemas
+Step 1（每次任务）:          content_search(platform, keyword, extras)
+Step 2（需要细看时）:        content_detail(platform, id, extras)
+```
+
+---
+
+## 方案二：浏览器工具族 → 语义合并
+
+### 现状
+
+28 个 `@tool`（在 `agent/tools/builtin/browser/baseClass.py`），按任务语义分组：
+
+| 类别 | 数量 | 工具 |
+|---|---|---|
+| 导航 | 4 | `browser_navigate_to_url`、`browser_search_web`、`browser_go_back`、`browser_get_live_url` |
+| 等待 / 人机协同 | 2 | `browser_wait`、`browser_wait_for_user_action` |
+| 元素交互 | 6 | `browser_click_element`、`browser_input_text`、`browser_send_keys`、`browser_upload_file`、`browser_get_dropdown_options`、`browser_select_dropdown_option` |
+| 视口 / 查找 | 2 | `browser_scroll_page`、`browser_find_text` |
+| 内容读取 | 6 | `browser_screenshot`、`browser_get_visual_selector_map`、`browser_get_selector_map`、`browser_get_page_html`、`browser_read_long_content`、`browser_extract_content` |
+| 标签页管理 | 2 | `browser_switch_tab`、`browser_close_tab` |
+| Cookie / 登录 | 3 | `browser_ensure_login_with_cookies`、`browser_export_cookies`、`browser_load_cookies` |
+| 其他 | 3 | `browser_download_direct_url`、`browser_evaluate`、`browser_done` |
+
+### 与 browser-use MCP 的重叠分析
+
+约一半工具和 browser-use 原生 MCP 提供的能力重叠：
+
+| 你们的 @tool | browser-use MCP | 状态 |
+|---|---|---|
+| `browser_navigate_to_url` | `browser_navigate` | 重复 |
+| `browser_click_element` | `browser_click` | 重复 |
+| `browser_input_text` | `browser_type` | 重复 |
+| `browser_scroll_page` | `browser_scroll` | 重复 |
+| `browser_go_back` | `browser_go_back` | 重复 |
+| `browser_switch_tab` / `close_tab` | 同名 | 重复 |
+| `browser_extract_content` | 同名 | 重复 |
+| `browser_get_selector_map` | `browser_get_state` | 部分重复 |
+
+剩余 14 个是自研扩展（cookie 全家桶、upload、send_keys、dropdown、visual_selector_map、read_long_content、find_text、evaluate、download、done、wait_for_user_action、get_live_url、search_web、get_page_html）。
+
+### 新方案：语义合并（方案 A）
+
+采用"按动词合并 + Literal 枚举 action"模式，从 28 个 @tool 压缩到约 11 个。**不引入 MCP Client 基础设施**（那是未来的独立决策）。
+
+**目标签名：**
+
+```python
+@tool()
+async def browser_navigate(
+    target: str,
+    mode: Literal["url", "search", "back"] = "url",
+    engine: str = "bing",
+    new_tab: bool = False,
+) -> ToolResult:
+    """导航工具。
+    - mode="url": target 为 URL，直接访问
+    - mode="search": target 为搜索词，通过 engine 搜索
+    - mode="back": 浏览器后退，target 和 engine 忽略
+    """
+
+
+@tool()
+async def browser_interact(
+    action: Literal["click", "type", "send_keys", "upload", "dropdown_list", "dropdown_select"],
+    index: Optional[int] = None,
+    text: Optional[str] = None,
+    path: Optional[str] = None,
+    keys: Optional[str] = None,
+    clear: bool = True,
+) -> ToolResult:
+    """元素交互：
+    - click: 需要 index
+    - type: 需要 index + text
+    - send_keys: 需要 keys（如 'Enter'、'Ctrl+A'），不依赖 index
+    - upload: 需要 index + path
+    - dropdown_list: 需要 index（列出选项）
+    - dropdown_select: 需要 index + text（按文字选中）
+    """
+
+
+@tool()
+async def browser_screenshot(highlight_elements: bool = False) -> ToolResult:
+    """截图。
+    - highlight_elements=False: 纯截图
+    - highlight_elements=True: 带交互元素编号的标注截图（原 visual_selector_map）
+    """
+
+
+@tool()
+async def browser_elements() -> ToolResult:
+    """获取当前页面的可交互元素列表（文本版，不截图）。用于 LLM 按 index 与元素交互。"""
+
+
+@tool()
+async def browser_read(
+    mode: Literal["html", "find", "long_content", "extract"],
+    query: Optional[str] = None,
+    start_line: int = 0,
+    lines_per_page: int = 100,
+    extract_links: bool = False,
+) -> ToolResult:
+    """页面内容读取：
+    - html: 整页 HTML（大页面慎用）
+    - find: 在页面中查找 query 文本
+    - long_content: 分页读取长内容，配合 start_line / lines_per_page
+    - extract: 用 LLM 根据 query 抽取结构化信息，可选 extract_links
+    """
+
+
+@tool()
+async def browser_scroll(
+    down: bool = True,
+    pages: float = 1.0,
+    into_view_index: Optional[int] = None,
+) -> ToolResult:
+    """滚动页面。down=True 向下，pages 是滚动的页面数；
+    传 into_view_index 则滚动到指定元素可见（忽略 down 和 pages）。
+    """
+
+
+@tool()
+async def browser_tabs(
+    action: Literal["switch", "close", "list"],
+    tab_id: Optional[str] = None,
+) -> ToolResult:
+    """标签页管理。list 不需要 tab_id，switch 和 close 需要。"""
+
+
+@tool()
+async def browser_cookies(
+    action: Literal["load", "export", "ensure_login"],
+    name: str = "",
+    account: str = "",
+    url: str = "",
+    cookie_type: str = "",
+    auto_navigate: bool = True,
+) -> ToolResult:
+    """Cookie 管理：
+    - load: 加载已保存的 cookie（url + name, auto_navigate 控制是否自动导航）
+    - export: 导出当前 cookie 保存（name + account 标识）
+    - ensure_login: 检查登录状态，未登录时自动加载 cookie_type 对应的 cookie
+    """
+
+
+@tool()
+async def browser_wait(
+    seconds: Optional[int] = None,
+    user_action_message: Optional[str] = None,
+) -> ToolResult:
+    """等待：
+    - 传 seconds: 纯等待指定秒数
+    - 传 user_action_message: 暂停并提示用户在浏览器里手动操作，用户完成后 Agent 继续
+    - 两者都不传: 报错
+    """
+
+
+@tool()
+async def browser_evaluate(code: str) -> ToolResult:
+    """在当前页面上下文执行 JavaScript。"""
+
+
+@tool()
+async def browser_download(url: str, save_name: str = "") -> ToolResult:
+    """直接下载给定 URL 的文件到本地。"""
+```
+
+**可选保留（视使用频率决定）：**
+
+- `browser_get_live_url()` — 远程浏览器场景专用，可能删除
+- `browser_done(text, success)` — 任务完成信号，可能删除（让 agent 用普通 completion 输出）
+
+**28 → 约 11 个 @tool，下降 60%。**
+
+### 条件必填参数的处理
+
+Python 函数签名里所有参数都声明为 Optional，但某些组合是运行时强制的：
+
+```python
+async def browser_interact(action, index, text, path, keys, clear):
+    if action == "click" and index is None:
+        return ToolResult(error="click action requires index")
+    if action == "type" and (index is None or text is None):
+        return ToolResult(error="type action requires both index and text")
+    ...
+```
+
+静态 schema 表达不了这个，只能靠 docstring 说清楚 + 运行时 validate。
+
+### 迁移步骤
+
+1. 在 `baseClass.py` 里先保留所有现有的非 @tool 内部辅助函数（它们负责实际调用 browser-use）
+2. 把 30 个原 `@tool` 函数**去掉 @tool 装饰器**，降级为内部函数 `_navigate_to_url` / `_click_element` 等
+3. 在 `baseClass.py` 底部新增 11 个 @tool 入口函数，每个内部根据 action 路由到对应的内部函数
+4. 从 `browser/__init__.py` 更新导出列表
+5. 更新 `agent/docs/tools.md` 的浏览器工具小节
+6. 更新现有的浏览器 prompt（破坏性）
+
+### 未决策的设计问题
+
+1. **`browser_read` 的 4 个 mode 是否要再拆分？** `extract` 是 LLM 驱动的，和其他 3 个差异较大。可以拆成 `browser_read(mode="html|find|long")` + `browser_extract(query, ...)`。
+2. **`browser_interact` 的 6 个 action 都合并合适吗？** `dropdown_list` 和 `dropdown_select` 与其他 action 的参数差异较大，可以独立出 `browser_dropdown(index, select_text=None)`。
+3. **`browser_done` 的去留** — 这个是给上层 Agent 发任务完成信号的协议约定，不是浏览器操作。建议移到框架通用的 task 信号机制里，或删除。
+4. **`browser_search_web` 要不要作为 mode 合并到 `browser_navigate`？** 搜索引擎的具体实现（`engine: "bing"|"google"|...`）和 URL 导航差异较大，合并后签名变乱。可能独立保留更好。
+5. **重命名的破坏性改动** — 所有 `browser_navigate_to_url` 等现存引用都要更新。需要在 PR 描述里列出 before/after 对照表。
+
+---
+
+## 方案三（暂不采用）：引入 MCP Client 基础设施
+
+**思路：** 让本框架的 Agent Runner 作为 MCP Client 连接 browser-use 原生 MCP，**删除**所有与 browser-use MCP 重叠的 @tool，只保留自研扩展（cookie、wait_for_user_action、dropdown 等约 14 个）。
+
+**优点：** 消除代码重复；未来 browser-use 升级自动获益；和 Claude Code 的浏览器体验一致。
+
+**缺点：** 需要给框架的 Agent Runner 新增 MCP Client 基础设施；启动时需要管理 MCP server 进程生命周期；双路共存（部分本地 @tool + 部分远程 MCP）增加复杂度。
+
+**结论：** 当前不做，视未来框架是否引入通用 MCP Client 基础设施再议。方案二（语义合并）的收益已经够大，投入更小。
+
+---
+
+## 共同原则（所有工具族改造都要遵守）
+
+1. **破坏性改动集中做**——所有重命名、删除、合并都在同一个 PR 里完成，不要分期做。分期反而让用户迁移更痛苦
+2. **每个工具族都要有对应的 CLI 入口 + 自包含 `if __name__ == "__main__"`**——参考 toolhub / librarian 已有的模式
+3. **对应的 skill 写到 `~/.claude/skills/`**——让 Claude Code 等外部 Agent 能用
+4. **破坏性改动后同步更新 `agent/docs/tools.md` 和所有现存 prompt**
+
+---
+
+## 待决策清单（落地前必须定）
+
+### 内容工具族
+
+- [ ] `extras` schema 处理方式（推荐方案 i）
+- [ ] 缓存持久化方案（推荐磁盘 + trace_id）
+- [ ] 拼图上限策略（推荐分 detail/overview 两档）
+- [ ] X 是否补 detail 接口（取决于后端支持）
+
+### 浏览器工具族
+
+- [ ] `browser_read` 是否拆成 read + extract 两个
+- [ ] `browser_interact` 是否拆出 dropdown
+- [ ] `browser_done` 去留
+- [ ] `browser_search_web` 是否合并到 navigate
+- [ ] 重命名破坏性改动的迁移策略
+
+### 哲学选择
+
+- [ ] 是否未来引入 MCP Client 基础设施（影响浏览器工具的最终形态）
+
+---
+
+## 不做的事情
+
+- **沙箱工具**：直接删除，不改造（参考 `tools.md` 对应修改记录）
+- **文件工具、bash、skill 等正交单能力工具**：保持现状
+- **knowledge 工具族**：已经是 `ask_knowledge` / `upload_knowledge` 两个入口，规模小且清晰，无改造必要

agent/docs/tools.md

@@ -807,7 +807,8 @@ print(f"Success rate: {stats['success_rate']:.1%}")
 
 | 工具 | 功能 | 参考 |
 |------|------|------|
-| `read_file` | 读取文件内容（支持图片、PDF） | opencode read.ts |
+| `read_file` | 读取单个文件（文本 / 图片 / PDF） | opencode read.ts |
+| `read_images` | 批量读取图片，支持自动降采样和网格拼图 | 自研 |
 | `edit_file` | 智能文件编辑（多种匹配策略） | opencode edit.ts |
 | `write_file` | 写入文件（创建或覆盖） | opencode write.ts |
 | `bash_command` | 执行 shell 命令 | opencode bash.ts |
@@ -815,6 +816,39 @@ print(f"Success rate: {stats['success_rate']:.1%}")
 | `grep_content` | 内容搜索（正则表达式） | opencode grep.ts |
 | `agent` | 创建 Agent 执行任务（单任务 delegate / 多任务并行 explore） | 自研 |
 | `evaluate` | 评估目标执行结果是否满足要求 | 自研 |
+| `toolhub_health` | 检查 ToolHub 远程工具库服务状态 | 自研 |
+| `toolhub_search` | 搜索/发现 ToolHub 远程工具 | 自研 |
+| `toolhub_call` | 调用 ToolHub 远程工具（图片参数支持本地文件路径） | 自研 |
+| `ask_knowledge` | 向知识库查询信息（通过 KnowHub Librarian） | 自研 |
+| `upload_knowledge` | 上传调研结果到知识库 | 自研 |
+
+#### `read_file` vs `read_images`
+
+| 场景 | 工具 |
+|------|------|
+| 读取 **1 张**图片 / 文本 / PDF | `read_file` |
+| 批量读取 **2 张以上**图片 | `read_images` |
+| 需要 AI 对多张图做**对比选择**（选图、挑错、横向比较） | `read_images` 且 `layout="grid"` |
+| 需要对多张图**逐张独立分析** | `read_images` 且 `layout="separate"` |
+
+`read_images` 默认 `layout="grid"` — 多张图拼成一张**带索引编号**的网格图（1,2,3…），**省 token 的同时让 LLM 能在单次注视中做横向对比**。拼图和降采样在内部组合使用：先降采样每张缩略图，再拼成整图，最终图片大小约等于一张普通图的开销，而非所有原图的累积。
+
+**Grid 模式的 16 张硬上限：** grid 模式下单次调用最多 16 张图片。超过会报错，需要分批调用。上限来自于 LLM 内部图片缩放的物理限制——Claude/Qwen-VL 会把图片缩到长边约 1568 像素，当拼图里格子太多时，每格会糊到无法识别。16 张对应 4×4 布局，每格约 300px，缩放后仍能保持约 280px，人物和场景细节仍然可辨。如需处理更多图片，或切换到 `layout="separate"`（无数量限制但每张图都有独立的结构开销 token）。
+
+**自适应布局：** grid 模式下根据图片数量动态选择列数和缩略图尺寸，小批量时每张图更清晰：
+
+| 图片数 | 布局 | 每格大小 |
+|------|------|---------|
+| 2 张 | 2 列 | 500px |
+| 3-4 张 | 2 列 | 450px |
+| 5-6 张 | 3 列 | 400px |
+| 7-9 张 | 3 列 | 380px |
+| 10-12 张 | 4 列 | 320px |
+| 13-16 张 | 4 列 | 300px |
+
+**关于标签/标题：** `read_images` 的拼图**不显示文件名**，只显示索引序号——因为本地文件名（如 `IMG_1234.jpg`）对 LLM 理解内容没有帮助，而索引到原始路径的对照表通过返回文本提供，LLM 可以用"第 3 张"这种引用方式精确指代。对比之下 `search_posts` / `youtube_search` 的拼图**会**显示 label（帖子/视频标题），因为这些是内容型元数据，有实际信息量。这一差异反映在 `build_image_grid(labels=...)` 参数上：传 `None` 只画序号，传列表则在每格下方画标题。
+
+网格和降采样的实现在 `agent/tools/utils/image.py`，`search_posts` 和 `youtube_search` 等工具也复用同一套拼图逻辑。
 
 ### Agent 工具
 
@@ -1205,6 +1239,189 @@ async def search_notes(
 
 ---
 
+## 跨框架使用（CLI / MCP）
+
+工具设计为可跨 Agent 框架使用（本框架 Agent、Claude Code、其他 LLM IDE 等），遵循以下原则：
+
+- **无状态工具** → 自包含 CLI：每个工具文件可独立运行，零外部依赖
+- **有状态工具组**（浏览器、沙箱等需要持久 session） → MCP server：使用标准协议管理 session
+- **禁止中间态**：不造私有协议；简单就 CLI，复杂就 MCP
+
+### 判断标准
+
+| 问题 | 答案 | 选择 |
+|------|------|------|
+| 工具调用之间是否有进程内状态需要保持？（浏览器 session、数据库连接、缓存） | 否 | **CLI** |
+| 同上 | 是 | **MCP** |
+| 是否需要 Claude Desktop、Cursor 等客户端原生识别？ | 需要 | **MCP** |
+
+### 无状态 CLI 工具规范
+
+一个工具想同时作为 Agent tool（`@tool` 注册）和 CLI 工具使用，需要满足以下要求：
+
+**1. 文件末尾添加自包含的 `if __name__ == "__main__"` 块**
+
+参数解析、asyncio.run、结果输出这些 CLI 样板代码**直接内联**在工具文件里，不要抽取到共享 `cli.py` 模块——这样每个工具文件可以独立迁移到其他项目。
+
+```python
+# 示例：agent/tools/builtin/toolhub.py 末尾
+if __name__ == "__main__":
+    import sys, asyncio, os, uuid
+
+    COMMANDS = {"health": toolhub_health, "search": toolhub_search, "call": toolhub_call}
+
+    def _parse_args(argv):
+        kwargs = {}
+        for arg in argv:
+            if arg.startswith("--") and "=" in arg:
+                k, v = arg.split("=", 1)
+                k = k.lstrip("-").replace("-", "_")
+                try: v = json.loads(v)
+                except: pass
+                kwargs[k] = v
+        return kwargs
+
+    # trace_id 三级回退：CLI 参数 > 环境变量 > 自动生成
+    cmd = sys.argv[1]
+    kwargs = _parse_args(sys.argv[2:])
+    trace_id = kwargs.pop("trace_id", None) or os.getenv("TRACE_ID") or f"cli-{uuid.uuid4().hex[:8]}"
+    set_trace_context(trace_id)
+
+    result = asyncio.run(COMMANDS[cmd](**kwargs))
+    # 输出 JSON（注意 double-encoding 问题）
+    ...
+```
+
+**2. 输出统一为 JSON 格式**
+
+```json
+{
+  "trace_id": "...",
+  "output": "...",  // 原生 dict/list/str，不要预先 json.dumps
+  "error": "...",   // 可选
+  "metadata": {...}  // 可选
+}
+```
+
+**3. trace_id 三级回退策略**
+
+对于需要会话语义（同一 trace_id 内多次调用共享状态）的工具（librarian、toolhub 的图片输出目录等）：
+
+1. **CLI 参数** `--trace_id=xxx`（显式）
+2. **环境变量** `TRACE_ID`（同一 shell session 共享）
+3. **自动生成** `cli-{random}`（兜底）
+
+外部 Agent 只需 `export TRACE_ID=session-xxx` 一次，后续所有 CLI 调用自动归到同一会话。
+
+**4. 二进制产出写文件，JSON 返回路径**
+
+像 `read_images` 这种产出图片/大文件的工具，CLI 模式下**不要**把 base64 塞进 stdout（刷屏 + 调用方还要解码）。应该：
+- 要求用户显式传 `--out=<path>` 指定输出路径
+- 把文件写到 `<path>`
+- JSON 响应里返回 `out_path` 供调用方用 Read 工具查看
+
+**5. 避免双重 JSON 编码**
+
+如果工具内部已经 `json.dumps()` 把 result dict 塞进了 `ToolResult.output`，CLI 层再 `json.dumps(result.output)` 会产生双重转义（`"output": "{\"model\": ..."` 这种反人类形式）。CLI 层要在输出前检测并解码：
+
+```python
+output_value = result.output
+if isinstance(output_value, str):
+    stripped = output_value.lstrip()
+    if stripped.startswith(("{", "[")):
+        try:
+            output_value = json.loads(output_value)
+        except (json.JSONDecodeError, ValueError):
+            pass  # 非 JSON 文本，保持原样
+```
+
+### Skill 安装规范
+
+CLI 工具对外暴露给 Claude Code（或其他支持 skill 的客户端）时，需要配套写一个 `SKILL.md`：
+
+**位置：** `~/.claude/skills/<name>/SKILL.md`（用户全局）或项目级 `.claude/skills/<name>/SKILL.md`
+
+**格式：**
+
+```markdown
+---
+name: <skill-name>
+description: <一句话，描述用途和触发时机。这是 Claude Code 决定何时加载该 skill 的唯一依据>
+---
+
+# <Skill Name>
+
+<简短一段话介绍工具>
+
+## 用法
+
+```bash
+python <绝对路径>/tool.py <子命令> --key=value
+```
+
+- `--key=...` 参数说明
+- 关键约束（如数量上限）
+
+<调用后怎么解读输出，典型 workflow>
+```
+
+**尺寸原则：** SKILL.md **越短越好**。它每次触发时都会进入 context 占据 token。和 `agent/docs/tools.md` 的职责区分：
+
+| 文件 | 读者 | 触发 | 长度 |
+|------|------|------|------|
+| `SKILL.md` | **运行时的 Claude Code**（动态加载） | 每次匹配自动加载到 context | **短**（20 行以内为佳） |
+| `agent/docs/tools.md` | **开发者**（静态阅读） | 从不自动加载 | 长，可以详细展开原理、设计取舍 |
+
+SKILL.md 只写"调用这个工具所需的最小信息集"，原理和细节放到 docs。
+
+**当前已安装的 skill**（`~/.claude/skills/`）：
+- `toolhub/` — 搜索和调用 ToolHub 远程 AI 工具
+- `knowhub/` — 查询和上传 KnowHub 知识库
+- `stitch-images/` — 批量图片拼成网格供 Read 一次查看
+
+### ToolHub 图片管线
+
+`toolhub_call` 内置完整的图片处理管线，无需单独的上传/下载工具：
+
+- **输入**：`params` 中的图片参数（`image`、`image_url`、`mask_image`、`pose_image`、`images`）可直接传本地文件路径，系统自动上传
+- **输出**：生成的图片自动保存到 `outputs/` 目录，返回结果中 `saved_files` 包含本地路径
+
+### MCP 集成（有状态工具组）
+
+对于需要维持 session 的工具组，使用 MCP server。两种注册方式：
+
+**1. 使用现成的 MCP server**（推荐）
+
+例如浏览器工具直接用 browser-use 原生 MCP：
+
+```json
+// .mcp.json（项目根目录；不要写在 settings.json，Claude Code 不会从那里读 mcpServers）
+{
+  "mcpServers": {
+    "browser-use": {
+      "command": "/Users/sunlit/.pyenv/versions/3.13.1/bin/python",
+      "args": ["-m", "browser_use.skill_cli.main", "--mcp"],
+      "env": {
+        "OPENAI_API_KEY": "sk-...",
+        "OPENAI_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        "BROWSER_USE_LLM_MODEL": "qwen-plus"
+      }
+    }
+  }
+}
+```
+
+**注意事项：**
+- `command` 必须用**绝对路径**，不要用 pyenv shim（shim 在 Claude Code 子进程里无法正确解析）
+- MCP server 配置放 `.mcp.json`，**不是** `~/.claude/settings.json`（后者只管 permissions/outputStyle 等）
+- 第三方包的 LLM 配置如果 Pydantic schema 吞字段（比如 browser-use 的 `LLMEntry` 不支持 `base_url`），可以通过**环境变量**绕过（如 `OPENAI_BASE_URL` 是 OpenAI SDK 原生环境变量）
+
+**2. 为自研有状态工具组写 MCP server**
+
+当你有一组需要共享 session 的自研工具时，用 `mcp` Python SDK 写一个 server，每个工具作为 `@app.tool()` 暴露。server 进程内维护 session 状态。避免造私有 stdio 协议。
+
+---
+
 ## 总结
 
 | 特性 | 状态 | 说明 |
@@ -1224,3 +1441,4 @@ async def search_notes(
 3. **类型安全**：充分利用 Python 类型注解
 4. **灵活集成**：支持各种工具库（Browser-Use, MCP 等）
 5. **可观测性**：内建统计和监控能力
+6. **跨框架**：无状态工具自包含 CLI，有状态工具走 MCP 标准协议