Merge branch 'main' of https://git.yishihui.com/howard/Agent

.gitignore

@@ -74,6 +74,15 @@ frontend/react-template/node_modules/
 # Feishu 运行时聊天记录（自动维护，包含联系人 PII）
 agent/tools/builtin/feishu/chat_history/
 
+# Runtime artifacts (one-off scripts, data, cache)
+cache/
+pending_uploads/
+knowledge/
+knowledge_batch_*.json
+knowledge-*.json
+tools/image_gen/
+tools/upload/
+
 # data
 knowhub/knowhub.db
 knowhub/knowhub.db-shm

README.md

@@ -1,507 +0,0 @@
-# Reson Agent
-
-可扩展的 Agent 框架。支持多步工具调用、计划管理、子 Agent 协作、回溯重跑和上下文压缩。
-
-## Quick Start
-
-```bash
-pip install -r requirements.txt
-
-# 配置 LLM API Key
-cp .env.example .env  # 编辑填入 API Key
-```
-
-### 最小示例
-
-```python
-import asyncio
-from agent import AgentRunner, RunConfig
-from agent.trace import FileSystemTraceStore
-from agent.llm import create_openrouter_llm_call
-
-runner = AgentRunner(
-    trace_store=FileSystemTraceStore(base_path=".trace"),
-    llm_call=create_openrouter_llm_call(model="anthropic/claude-sonnet-4.5"),
-)
-
-async def main():
-    async for item in runner.run(
-        messages=[{"role": "user", "content": "列出当前目录的文件"}],
-        config=RunConfig(model="anthropic/claude-sonnet-4.5"),
-    ):
-        print(item)
-
-asyncio.run(main())
-```
-
-## 自定义工具
-
-用 `@tool` 装饰器注册。`RunConfig(tools=None)`（默认）时所有已注册工具自动对 LLM 可用，无需额外配置。
-
-```python
-from agent import tool, ToolResult
-
-@tool(description="查询产品库存")
-async def check_inventory(product_id: str, warehouse: str = "default") -> ToolResult:
-    """查询指定仓库的产品库存
-
-    Args:
-        product_id: 产品唯一标识符
-        warehouse: 仓库编码，默认为主仓库
-    """
-    stock = await query_db(product_id, warehouse)
-    return ToolResult(output=f"库存: {stock}")
-
-# 确保此模块在 runner.run() 之前被 import
-```
-
-**注意**: `@tool` 通过副作用注册到全局 registry，必须确保定义工具的模块在调用 `runner.run()` 前被 import。
-
-### 参数 Schema 生成
-
-框架从函数签名和 docstring 自动生成 OpenAI Tool Schema，无需手写 JSON：
-
-- **参数类型**：从类型注解推断（`str`/`int`/`float`/`bool`/`list`/`dict`，支持 `Optional`、`Literal`、`List[T]`）
-- **参数描述**：从 Google 风格 docstring 的 `Args:` 段提取
-- **必填/可选**：有默认值的参数为可选，否则为必填
-- **工具描述**：优先使用 `@tool(description=...)` 参数，其次取 docstring 首行
-- `uid` 和 `context` 参数由框架自动注入，不会出现在 Schema 中
-
-上面的 `check_inventory` 会生成：
-
-```json
-{
-  "type": "function",
-  "function": {
-    "name": "check_inventory",
-    "description": "查询产品库存",
-    "parameters": {
-      "type": "object",
-      "properties": {
-        "product_id": { "type": "string", "description": "产品唯一标识符" },
-        "warehouse": {
-          "type": "string",
-          "description": "仓库编码，默认为主仓库",
-          "default": "default"
-        }
-      },
-      "required": ["product_id"]
-    }
-  }
-}
-```
-
-### 限制工具范围
-
-```python
-# 只启用指定工具（在内置工具基础上追加）
-config = RunConfig(tools=["check_inventory", "another_tool"])
-```
-
-## 自定义 Skills
-
-Skills 是 Markdown 文件，提供领域知识，注入到 system prompt。
-
-```
-my_project/
-└── skills/
-    └── my_domain.md
-```
-
-```markdown
----
-name: my-domain-skill
-description: 领域专属知识
----
-
-## Guidelines
-
-- 规则 1
-- 规则 2
-```
-
-```python
-runner = AgentRunner(
-    llm_call=...,
-    trace_store=...,
-    skills_dir="./skills",  # 指向你的 skills 目录
-)
-```
-
-内置 skills（`agent/skill/skills/`）始终自动加载，`skills_dir` 的内容额外追加。
-
-## 知识管理系统（Knowledge Management）
-
-知识管理系统通过**提取、存储、注入**三个环节，让 Agent 积累和复用结构化知识。
-
-### 核心流程
-
-**1. 提取（Extract）**
-
-- **触发时机**：
-  - 压缩时提取：消息量超阈值触发压缩时，在 Level 1 过滤前用完整 history 反思
-  - 完成时提取：Agent 运行完成后（不代表任务完成，可能中途退出等待人工评估）
-- **提取方式**：调用 LLM 对执行过程进行反思，提取可复用的知识
-- **自定义 Prompt**：可通过配置自定义反思 prompt，空则使用默认（见 `agent/core/prompts/knowledge.py`）
-
-**2. 存储（Store）**
-
-- **存储位置**：KnowHub 服务（默认 `http://localhost:8765`）
-- **知识结构**：
-  - `title`: 知识标题
-  - `content`: 知识内容
-  - `type`: 知识类型（strategy/tool/pattern/pitfall 等）
-  - `tags`: 标签（键值对，用于分类和检索）
-  - `scopes`: 作用域（如 `org:cybertogether`）
-  - `owner`: 所有者（默认从 git config user.email 获取）
-  - `resource_ids`: 关联资源 ID 列表（代码片段、凭证、cookies 等）
-- **资源管理**：
-  - 知识可关联多个资源（通过 `resource_ids` 字段）
-  - 资源包含 `body`（公开内容）和 `secure_body`（加密内容）
-  - 支持代码片段、API 凭证、cookies 等多种资源类型
-
-**3. 注入（Inject）**
-
-- **触发时机**：Agent 切换当前工作的 Goal 时自动触发
-- **检索策略**：基于 Goal 描述和上下文，从知识库检索相关知识
-- **注入方式**：将检索到的知识注入到 Agent 的上下文中
-
-### 配置
-
-知识管理配置通过 `RunConfig.knowledge` 传递：
-
-```python
-from agent.core.runner import KnowledgeConfig, RunConfig
-
-run_config = RunConfig(
-    model="claude-sonnet-4.5",
-    temperature=0.3,
-    max_iterations=1000,
-
-    knowledge=KnowledgeConfig(
-        # 压缩时提取（消息量超阈值触发压缩时，用完整 history 反思）
-        enable_extraction=True,
-        reflect_prompt="",  # 空则使用默认，见 agent/core/prompts/knowledge.py:REFLECT_PROMPT
-
-        # agent运行完成后提取
-        enable_completion_extraction=True,
-        completion_reflect_prompt="",  # 空则使用默认
-
-        # 知识注入（agent切换当前工作的goal时，自动注入相关知识）
-        enable_injection=True,
-
-        # 默认字段（保存/搜索时自动注入）
-        owner="",  # 空则从 git config user.email 获取（隐藏参数，LLM 不可见）
-        default_tags={"project": "my_project"},  # 与 LLM 传递的 tags 合并
-        default_scopes=["org:cybertogether"],  # 与 LLM 传递的 scopes 合并
-        default_search_types=["strategy", "tool"],
-        default_search_owner=""  # 空则不过滤
-    )
-)
-```
-
-**参数注入规则**（通过框架 `inject_params` 机制实现，详见 `agent/docs/tools.md`）：
-
-- `owner`：隐藏参数，LLM 不可见，框架自动注入（`mode: default`）
-- `tags`：LLM 可追加新 key，框架默认 key 不可被覆盖（`mode: merge`）
-- `scopes`：LLM 可追加，与框架默认值合并去重（`mode: merge`）
-
-### 知识工具
-
-框架提供以下内置工具用于知识管理：
-
-- `knowledge_save`: 保存知识到知识库
-- `knowledge_search`: 搜索知识库
-- `knowledge_get`: 获取指定知识详情
-- `resource_save`: 保存资源（代码、凭证等）
-- `resource_get`: 获取资源内容
-
-这些工具会自动注入配置的默认字段（owner, tags, scopes 等）。
-
-## AgentRunner 参数
-
-```python
-AgentRunner(
-    llm_call,                # 必需：LLM 调用函数
-    trace_store=None,        # Trace 持久化（推荐 FileSystemTraceStore）
-    tool_registry=None,      # 工具注册表（默认：全局 registry）
-    skills_dir=None,         # 自定义 skills 目录
-    utility_llm_call=None,   # 轻量 LLM（生成任务标题等）
-    debug=False,             # 调试模式
-)
-```
-
-## RunConfig 参数
-
-```python
-RunConfig(
-    model="gpt-4o",          # 模型标识
-    temperature=0.3,
-    max_iterations=200,       # Agent loop 最大轮数
-    tools=None,               # None=全部已注册工具，List[str]=内置+指定工具
-    system_prompt=None,       # None=从 skills 自动构建
-    agent_type="default",     # 预设类型：default / explore / analyst
-    trace_id=None,            # 续跑/回溯时传入已有 trace ID
-    after_sequence=None,      # 从哪条消息后续跑（message sequence）
-    goal_compression="on_overflow",  # Goal 压缩模式：none / on_complete / on_overflow
-    knowledge=KnowledgeConfig(),  # 知识管理配置
-)
-```
-
-    system_prompt=None,       # None=从 skills 自动构建
-    agent_type="default",     # 预设类型：default / explore / analyst
-    trace_id=None,            # 续跑/回溯时传入已有 trace ID
-    after_sequence=None,      # 从哪条消息后续跑（message sequence）
-
-)
-
-````
-
-## LLM Providers
-
-框架内置两个 provider：
-
-```python
-from agent.llm import create_openrouter_llm_call, create_gemini_llm_call
-
-# OpenRouter（支持多种模型）
-llm = create_openrouter_llm_call(model="anthropic/claude-sonnet-4.5")
-
-# Google Gemini
-llm = create_gemini_llm_call(model="gemini-2.5-flash")
-````
-
-自定义 provider 只需实现签名：
-
-```python
-async def my_llm_call(messages, model, tools, temperature, **kwargs) -> dict:
-    # 调用你的 LLM
-    return {
-        "content": "...",
-        "tool_calls": [...] or None,
-        "prompt_tokens": 100,
-        "completion_tokens": 50,
-        "cost": 0.001,
-        "finish_reason": "stop",
-    }
-```
-
-## API Server
-
-```bash
-python api_server.py
-```
-
-| 方法 | 路径                        | 说明        |
-| ---- | --------------------------- | ----------- |
-| GET  | `/api/traces`               | 列出 Traces |
-| GET  | `/api/traces/{id}`          | Trace 详情  |
-| GET  | `/api/traces/{id}/messages` | 消息列表    |
-| POST | `/api/traces`               | 新建并执行  |
-| POST | `/api/traces/{id}/run`      | 续跑/回溯   |
-| POST | `/api/traces/{id}/stop`     | 停止        |
-| WS   | `/api/traces/{id}/watch`    | 实时事件    |
-
-需在 `api_server.py` 中配置 Runner 才能启用 POST 端点。
-
-## 项目结构
-
-```
-agent/
-├── core/           # AgentRunner + 预设
-├── tools/          # 工具系统（registry + 内置工具）
-├── trace/          # 执行追踪 + 计划（GoalTree）+ API
-├── skill/          # Skills（技能系统）
-└── llm/            # LLM Provider 适配
-```
-
-详细架构文档：[docs/README.md](./docs/README.md)
-
-## Agent 预设（Presets）
-
-预设定义不同类型 Agent 的配置模板（工具权限、system prompt、skills 等）。
-
-**项目级预设**：在项目目录创建 `presets.json`，支持从 `.prompt` 文件加载自定义 system prompt：
-
-```json
-{
-  "tool_research": {
-    "system_prompt_file": "tool_research.prompt",
-    "max_iterations": 50,
-    "skills": ["planning", "research", "browser"],
-    "description": "工具调研 Agent"
-  }
-}
-```
-
-**加载预设**：
-```python
-from agent.core.presets import load_presets_from_json
-
-load_presets_from_json("path/to/presets.json")
-```
-
-**使用预设**：LLM 调用 `agent` 工具时指定 `agent_type`：
-```python
-agent(task="调研视频生成工具", agent_type="tool_research")
-```
-
-详见 `examples/production/` 示例和 `agent/docs/architecture.md`。
-
-## 交互式 CLI（Interactive CLI）
-
-框架提供交互式控制器，支持实时监控、手动干预和经验总结。
-
-### 使用方式
-
-```python
-from agent.cli import InteractiveController
-
-# 创建交互控制器
-interactive = InteractiveController(
-    runner=runner,
-    store=store,
-    enable_stdin_check=True  # 启用标准输入检查
-)
-
-# 在执行循环中检查用户输入
-async for item in runner.run(messages=messages, config=config):
-    cmd = interactive.check_stdin()
-    if cmd == 'pause':
-        await runner.stop(trace_id)
-        menu_result = await interactive.show_menu(trace_id, current_sequence)
-        # 处理菜单结果...
-    elif cmd == 'quit':
-        await runner.stop(trace_id)
-        break
-```
-
-### 交互控制
-
-在执行过程中，可以通过命令行实时控制：
-
-| 按键          | 动作         | 说明                              |
-| ------------- | ------------ | --------------------------------- |
-| `p` / `pause` | **暂停执行** | 立即挂起 Agent 循环，进入交互菜单 |
-| `q` / `quit`  | **停止执行** | 安全停止并保存当前的执行状态      |
-
-### 交互菜单功能
-
-进入暂停模式后，系统提供以下操作：
-
-1. **插入干预消息**：直接向 Agent 下达新指令
-2. **触发经验总结 (Reflect)**：强制 Agent 对当前过程进行反思
-3. **查看 GoalTree**：可视化当前任务的拆解结构和完成进度
-4. **上下文压缩 (Compact)**：手动精简对话历史
-
-### 项目配置示例
-
-完整的项目配置示例见 `examples/research/config.py`：
-
-```python
-from agent.core.runner import KnowledgeConfig, RunConfig
-from agent.utils import setup_logging
-
-# Agent 运行配置
-RUN_CONFIG = RunConfig(
-    model="claude-sonnet-4.5",
-    temperature=0.3,
-    max_iterations=1000,
-    name="Research Agent",
-
-    knowledge=KnowledgeConfig(
-        enable_extraction=True,
-        enable_completion_extraction=True,
-        enable_injection=True,
-        owner="",  # 空则从 git config 获取
-        default_tags={"project": "research"},
-        default_scopes=["org:cybertogether"],
-        default_search_types=["strategy", "tool"],
-    )
-)
-
-# 基础设施配置
-SKILLS_DIR = "./skills"
-TRACE_STORE_PATH = ".trace"
-DEBUG = True
-LOG_LEVEL = "INFO"
-LOG_FILE = None  # 可设置为文件路径
-
-# 在 run.py 中使用
-setup_logging(level=LOG_LEVEL, file=LOG_FILE)
-
-runner = AgentRunner(
-    trace_store=FileSystemTraceStore(base_path=TRACE_STORE_PATH),
-    llm_call=create_openrouter_llm_call(model=f"anthropic/{RUN_CONFIG.model}"),
-    skills_dir=SKILLS_DIR,
-    debug=DEBUG
-)
-
-async for item in runner.run(messages=messages, config=RUN_CONFIG):
-    # 处理执行结果
-    pass
-```
-
-**配置说明**：
-
-- 直接使用框架的 `RunConfig` 和 `KnowledgeConfig`，不需要自定义配置类
-- 基础设施配置（skills_dir, trace_store_path 等）用简单变量定义
-- 使用 `agent.utils.setup_logging()` 配置日志
-
-## 任务可视化与调试
-
-框架在运行期间会生成唯一的 `trace_id`。
-
-- **本地日志**：所有的执行细节、工具调用和 Goal 状态均持久化在 `.trace/` 目录下。
-- **Web 可视化**：
-
-1. 启动服务器：`python api_server.py`
-2. 启动前端:
-
-```
-  cd frontend/react-template
-  yarn
-  yarn dev
-```
-
-3. 访问控制台：`http://localhost:3000`
-4. 在前端界面中切换任务，即直观追踪 Agent 的思考链路。
-5. 因为该可视化读取的是根目录下的.trace文件，建议运行项目时，可以在根目录下用命令行运行`python examples/[project_name]/run.py`，使运行得到的trace存放在根目录
-
-### 提示：目前前端可视化只供观看本地运行过的trace结果，新任务运行等功能正在开发中，运行可在命令行中执行
-
-### 绿色节点为整体的goal(目标)，蓝色节点为子goal(目标)，灰色节点为基础信息节点。点击蓝色边/绿色边会折叠节点，点击节点会在右侧显示详情。
-
----
-
-## 示例项目结构
-
-可以参考其他文件夹中的结构：
-
-```text
-examples/[your_example]/
-├── input/             # (可选)输入数据
-├── output_1/          # (可选)输出目录
-├── skills/            # (可选)领域专属 Skill (.md)
-├── tool/              # (可选)自定义工具
-├── presets.json       # (可选)预定义的子 Agent 配置
-├── config.py          # (推荐)项目配置
-├── [task].prompt      # (必须)任务 System Prompt 和 User Prompt
-└── run.py             # (必须)交互式运行入口
-```
-
----
-
-## 环境兼容性
-
-针对 Clash Verge / TUN 模式等网络环境，本项目已内置代理自动避让逻辑：
-
-- **代理优化**：通过 `no_proxy` 配置防止 `httpx` 错误引导流量。
-- **Browser 模式**：支持 `cloud` (远程) 和 `local` (本地) 模式切换。
-
-## 运行结果存储
-
-运行过程中，会自动存储以下内容：
-
-- **运行轨迹**：根目录下 `.trace/` 文件夹下的实际运行路径结果
-- **知识库**：KnowHub 服务中保存的知识条目（通过 API 访问）

add_knowledge.py

@@ -1,42 +0,0 @@
-#!/usr/bin/env python3
-import json
-
-# 读取现有文件
-with open('/root/Agent/pre_upload_list.json', 'r', encoding='utf-8') as f:
-    data = json.load(f)
-
-# 新的知识条目
-new_knowledge = [
-    {
-        "task": "在图生图任务中，当 nano_banana 工具无法处理本地路径时的降级策略",
-        "content": "当使用 nano_banana 进行图生图时，如果传入本地图片路径（如 examples/xxx.png）会报错「Base64 decoding failed」，因为 nano_banana 期望的是 Base64 编码或网络 URL。\n\n正确做法：\n1. 先用 image_uploader 将本地图片上传获取 CDN URL\n2. 或使用支持本地路径自动上传的工具（如 flux_generate、seedream_generate）\n\n工具选择优先级：\n- nano_banana：需要手动上传获取 CDN URL，但支持多图融合，效果最好\n- flux_generate：自动处理本地路径，图生图效果好，推荐作为备选\n- seedream_generate：自动处理本地路径，需要最小尺寸 3686400 像素\n\n案例：Stage 4 检查 img_3 花丛色彩时，nano_banana 传入本地路径报错，切换至 flux_generate 成功完成修复。",
-        "types": ["experience"],
-        "tags": {
-            "intent": "图生图/色彩修复",
-            "state": "nano_banana/flux_generate"
-        },
-        "score": 4,
-        "source": {"category": "research"}
-    },
-    {
-        "task": "在图生图色彩控制中，通过 prompt 明确指定色彩排除可有效降低干扰元素饱和度",
-        "content": "当需要降低画面中某元素的色彩饱和度或改变其色系时，在 prompt 中明确指定：\n- 目标色彩：\"should be green foliage plants or very subtle low-saturation green flowers\"\n- 排除色彩：\"not purple or blue\"\n- 整体色调：\"The overall color scheme should be white and green with minimal color accents\"\n\n配合 flux-kontext-max 模型的图生图模式，可有效实现色彩调整而不破坏原有构图。\n\n案例：img_3 花丛色彩修复，将蓝紫色花丛成功调整为淡紫色/白色，融入绿色背景。",
-        "types": ["experience"],
-        "tags": {
-            "intent": "色彩控制/图生图优化",
-            "state": "flux_generate"
-        },
-        "score": 4,
-        "source": {"category": "research"}
-    }
-]
-
-# 添加到 knowledge 数组
-data['knowledge'].extend(new_knowledge)
-
-# 写回文件
-with open('/root/Agent/pre_upload_list.json', 'w', encoding='utf-8') as f:
-    json.dump(data, f, ensure_ascii=False, indent=2)
-
-print(f"成功添加 {len(new_knowledge)} 条知识条目")
-print(f"当前 knowledge 总数：{len(data['knowledge'])}")

add_workflow_experience_knowledge.py

@@ -1,44 +0,0 @@
-#!/usr/bin/env python3
-import json
-
-# 读取现有文件
-with open('/root/Agent/pre_upload_list.json', 'r', encoding='utf-8') as f:
-    data = json.load(f)
-
-# 新的知识条目
-new_knowledge = [
-    {
-        "task": "在分析工作流文件时，当 glob 搜索找不到目标文件的有效定位策略",
-        "content": "当 glob_files 按模式匹配找不到目标文件时，应该：1) 使用 bash_command 执行 find 命令进行更广泛的文件系统搜索，支持通配符和路径遍历；2) 结合 grep 内容搜索，通过文件内容关键词定位（如工具名、方案名）；3) 检查相关目录结构，如 research/outputs/ 下的子目录。案例：本次任务中 glob_files 搜索\"*wf_005*\"未找到文件，但通过 find 命令搜索包含\"ComfyUI\"\"Nano Banana\"等关键词的 markdown 文件，成功在 outputs/04/ 目录下找到颗粒感纸张纹理插画风格工作流调研报告.md，该文件即为 wf_005 的 raw_markdown 内容。",
-        "types": ["experience"],
-        "tags": {
-            "intent": "工作流文件定位",
-            "state": "文件搜索",
-            "tools": "glob_files,bash_command"
-        },
-        "score": 4,
-        "source": {"category": "research"}
-    },
-    {
-        "task": "工作流意图归纳的粒度判断原则",
-        "content": "在将工作流技术步骤归纳为意图级描述时，粒度判断应遵循：1) 保留工具差异——相同意图但不同工具实现应分开记录，因为工具选择是工作流变体的关键信息；2) 合并连续子步骤——同一工具内的连续操作（如新建图层→填充→设置混合模式）可合并为一个意图；3) 跨方案可比较——意图描述应使不同工作流的相同功能模块可对比。案例：本次将 Photoshop 的 5 种颗粒添加方法分别记录为\"添加溶解颗粒效果\"\"手绘颗粒纹理\"\"滤镜添加全局杂色\"等，保留了方法差异；而将 ComfyUI 的分割 + 重排合并为\"创建四方连续布局\"。",
-        "types": ["experience"],
-        "tags": {
-            "intent": "工作流分析",
-            "state": "意图归纳",
-            "method": "语义聚类"
-        },
-        "score": 4,
-        "source": {"category": "research"}
-    }
-]
-
-# 添加到 knowledge 数组
-data['knowledge'].extend(new_knowledge)
-
-# 写回文件
-with open('/root/Agent/pre_upload_list.json', 'w', encoding='utf-8') as f:
-    json.dump(data, f, ensure_ascii=False, indent=2)
-
-print(f"成功添加 {len(new_knowledge)} 条知识条目")
-print(f"当前 knowledge 总数：{len(data['knowledge'])}")

agent/README.md

@@ -121,7 +121,8 @@ RunConfig(
     max_iterations=200,
     agent_type="default",           # Agent 预设（对应 presets.json）
     name="任务名称",
-    tools=["read_file", "bash"],    # 限制可用工具（None=全部）
+    tools=None,                      # 精确指定工具列表（优先于 tool_groups）
+    tool_groups=["core", "browser"], # 工具分组白名单，默认 ["core"]
     goal_compression="on_overflow", # Goal 压缩："none" / "on_complete" / "on_overflow"
     knowledge=KnowledgeConfig(...), # 知识提取配置
 )
@@ -203,3 +204,124 @@ examples/research/
 | POST | `/api/traces/{id}/stop` | 停止运行 |
 
 **实现**：`agent/trace/api.py`, `agent/trace/run_api.py`
+
+---
+
+## 附录：工具分组
+
+通过 `RunConfig(tool_groups=[...])` 控制 Agent 可用的工具范围。默认仅 `["core"]`。每个工具在 `@tool(groups=[...])` 中声明分组，支持多标签。
+
+机制详见 [docs/tools.md § 工具分组](./docs/tools.md#工具分组)。
+
+### core — 基础能力（13）
+
+| 工具 | 说明 |
+|------|------|
+| `read_file` | 读取单个文件（文本/图片/PDF） |
+| `read_images` | 批量读图 + 网格拼图 |
+| `edit_file` | 编辑文件 |
+| `write_file` | 写入文件 |
+| `glob_files` | 文件模式匹配 |
+| `grep_content` | 内容搜索（正则） |
+| `bash_command` | 执行 shell 命令 |
+| `skill` | 调用 skill |
+| `list_skills` | 列出可用 skill |
+| `agent` | 创建子 Agent |
+| `evaluate` | 评估执行结果 |
+| `goal` | 目标/计划管理 |
+| `get_current_context` | 获取当前执行上下文 |
+
+### browser — 浏览器自动化（14）
+
+| 工具 | 说明 |
+|------|------|
+| `browser_navigate` | 导航到 URL |
+| `browser_search` | 搜索引擎搜索 |
+| `browser_back` | 返回上一页 |
+| `browser_interact` | 元素交互（click/type/send_keys/upload/dropdown） |
+| `browser_scroll` | 滚动页面 |
+| `browser_screenshot` | 截图（可带元素编号标注） |
+| `browser_elements` | 获取可交互元素列表 |
+| `browser_read` | 读取页面内容（html/find/long） |
+| `browser_extract` | LLM 驱动的结构化数据提取 |
+| `browser_tabs` | 标签页管理（switch/close） |
+| `browser_cookies` | Cookie/登录态（load/export/ensure_login） |
+| `browser_wait` | 等待（定时/等用户操作） |
+| `browser_js` | 执行 JavaScript |
+| `browser_download` | 下载文件 |
+
+### content — 内容搜索（6）
+
+| 工具 | 说明 |
+|------|------|
+| `content_platforms` | 列出/查询平台及参数（支持模糊匹配） |
+| `content_search` | 跨 11 平台搜索（小红书/B站/知乎/GitHub/YouTube/X 等） |
+| `content_detail` | 查看内容详情（从搜索缓存按索引取） |
+| `content_suggest` | 搜索关键词补全建议 |
+| `extract_video_clip` | YouTube 视频片段截取 |
+| `import_content` | 批量导入文章到 CMS |
+
+### knowledge — 知识管理（2）
+
+| 工具 | 说明 |
+|------|------|
+| `ask_knowledge` | 向知识库查询（通过 Librarian Agent） |
+| `upload_knowledge` | 上传调研结果到知识库 |
+
+### toolhub — 远程工具库（3）
+
+| 工具 | 说明 |
+|------|------|
+| `toolhub_health` | 检查远程工具库状态 |
+| `toolhub_search` | 搜索远程 AI 工具 |
+| `toolhub_call` | 调用远程工具（图片参数支持本地路径） |
+
+### feishu — 飞书（4）
+
+| 工具 | 说明 |
+|------|------|
+| `feishu_get_contact_list` | 获取联系人列表 |
+| `feishu_send_message_to_contact` | 给联系人发消息 |
+| `feishu_get_contact_replies` | 获取联系人回复 |
+| `feishu_get_chat_history` | 获取聊天历史 |
+
+### im — IM 通信（8）
+
+| 工具 | 说明 |
+|------|------|
+| `im_setup` | 初始化 IM 连接 |
+| `im_send_message` | 发送消息 |
+| `im_receive_messages` | 接收消息 |
+| `im_check_notification` | 检查通知 |
+| `im_get_contacts` | 获取联系人 |
+| `im_get_chat_history` | 获取聊天历史 |
+| `im_open_window` | 打开 IM 窗口 |
+| `im_close_window` | 关闭 IM 窗口 |
+
+### resource — 资源查询（2）
+
+| 工具 | 说明 |
+|------|------|
+| `resource_list_tools` | 列出资源工具 |
+| `resource_get_tool` | 获取工具详情 |
+
+### knowledge_internal — 知识库内部操作（14）
+
+> 仅供 Librarian Agent 内部使用，普通 Agent 不可见。通过 `tools=[...]` 精确指定访问。
+
+| 工具 | 说明 |
+|------|------|
+| `knowledge_search` | 知识检索（语义 + 精排） |
+| `knowledge_save` | 保存知识条目 |
+| `knowledge_list` | 列出知识 |
+| `knowledge_update` | 更新知识反馈 |
+| `knowledge_batch_update` | 批量更新反馈 |
+| `knowledge_slim` | 知识瘦身 |
+| `resource_save` | 保存资源 |
+| `resource_get` | 获取资源 |
+| `tool_search` | 搜索工具记录 |
+| `tool_list` | 列出工具记录 |
+| `capability_search` | 搜索能力记录 |
+| `capability_list` | 列出能力记录 |
+| `requirement_search` | 搜索需求记录 |
+| `requirement_list` | 列出需求记录 |

agent/core/__init__.py

@@ -7,7 +7,7 @@ Agent Core - 核心引擎模块
 3. Agent 预设（AgentPreset）
 """
 
-from agent.core.runner import AgentRunner, BUILTIN_TOOLS, CallResult, RunConfig
+from agent.core.runner import AgentRunner, CallResult, RunConfig
 from agent.core.presets import (
     AgentPreset,
     AGENT_PRESETS,
@@ -19,7 +19,6 @@ from agent.core.presets import (
 
 __all__ = [
     "AgentRunner",
-    "BUILTIN_TOOLS",
     "CallResult",
     "RunConfig",
     "AgentPreset",

agent/core/runner.py

@@ -103,8 +103,8 @@ class RunConfig:
     model: str = "gpt-4o"
     temperature: float = 0.3
     max_iterations: int = 200
-    tools: Optional[List[str]] = None          # None = 全部已注册工具
-    exclude_tools: List[str] = field(default_factory=list)  # 从工具列表中排除的工具名
+    tools: Optional[List[str]] = None          # None = 按 tool_groups 过滤；显式列表 = 精确指定
+    tool_groups: Optional[List[str]] = field(default_factory=lambda: ["core"])  # 工具分组白名单；默认仅 core，项目按需追加
     side_branch_max_turns: int = 5             # 侧分支最大轮次（压缩/反思）
     goal_compression: Literal["none", "on_complete", "on_overflow"] = "on_overflow"  # Goal 压缩模式
 
@@ -142,89 +142,8 @@ class RunConfig:
     knowledge: KnowledgeConfig = field(default_factory=KnowledgeConfig)
 
 
-    # 内置工具列表（始终自动加载）
-BUILTIN_TOOLS = [
-    # 文件操作工具
-    "read_file",
-    "edit_file",
-    "write_file",
-    "glob_files",
-    "grep_content",
-
-    # 系统工具
-    "bash_command",
-
-    # 技能和目标管理
-    "skill",
-    "list_skills",
-    "goal",
-    "agent",
-    "evaluate",
-    "get_current_context",
-
-    # 搜索工具
-    "search_posts",
-    "select_post",
-    "get_search_suggestions",
-    "x_search",
-    "youtube_search",
-    "youtube_detail",
-    "import_content",
-
-    # 知识管理工具
-    "ask_knowledge",
-    "upload_knowledge",
-    # "knowledge_search",
-    # "knowledge_save",
-    # "knowledge_update",
-    # "knowledge_batch_update",
-    # "knowledge_list",
-    # "knowledge_slim",
-
-    # 浏览器工具
-    "browser_get_live_url",
-    "browser_navigate_to_url",
-    "browser_search_web",
-    "browser_go_back",
-    "browser_wait",
-    "browser_click_element",
-    "browser_input_text",
-    "browser_send_keys",
-    "browser_upload_file",
-    "browser_scroll_page",
-    "browser_find_text",
-    "browser_screenshot",
-    "browser_switch_tab",
-    "browser_close_tab",
-    "browser_get_dropdown_options",
-    "browser_select_dropdown_option",
-    "browser_extract_content",
-    "browser_read_long_content",
-    "browser_download_direct_url",
-    "browser_get_page_html",
-    "browser_get_visual_selector_map",
-    "browser_evaluate",
-    "browser_ensure_login_with_cookies",
-    # 可以暂时由飞书消息替代
-    #"browser_wait_for_user_action",
-    "browser_done",
-    "browser_export_cookies",
-    "browser_load_cookies",
-
-    # 飞书工具
-    "feishu_send_message_to_contact",
-    "feishu_get_chat_history",
-    "feishu_get_contact_replies",
-    "feishu_get_contact_list",
-
-    # IM 工具
-    "im_setup",
-    "im_check_notification",
-    "im_receive_messages",
-    "im_send_message",
-    "im_get_contacts",
-    "im_get_chat_history",
-]
+    # BUILTIN_TOOLS 硬编码列表已移除（2026-04）。
+    # 工具可用性现在由 @tool(groups=[...]) 声明 + RunConfig.tool_groups 过滤控制。
 
 
 @dataclass
@@ -552,7 +471,7 @@ class AgentRunner:
         task_name = config.name or await self._generate_task_name(messages)
 
         # 准备工具 Schema
-        tool_schemas = self._get_tool_schemas(config.tools, config.exclude_tools)
+        tool_schemas = self._get_tool_schemas(config.tools, config.tool_groups)
 
         trace_obj = Trace(
             trace_id=trace_id,
@@ -1086,7 +1005,7 @@ class AgentRunner:
     ) -> AsyncIterator[Union[Trace, Message]]:
         """ReAct 循环"""
         trace_id = trace.trace_id
-        tool_schemas = self._get_tool_schemas(config.tools, config.exclude_tools)
+        tool_schemas = self._get_tool_schemas(config.tools, config.tool_groups)
 
         # 当前主路径头节点的 sequence（用于设置 parent_sequence）
         head_seq = trace.head_sequence
@@ -2838,25 +2757,19 @@ class AgentRunner:
         )
         return messages
 
-    def _get_tool_schemas(self, tools: Optional[List[str]], exclude_tools: Optional[List[str]] = None) -> List[Dict]:
+    def _get_tool_schemas(self, tools: Optional[List[str]] = None, tool_groups: Optional[List[str]] = None) -> List[Dict]:
         """
         获取工具 Schema
 
-        - tools=None: 使用 registry 中全部已注册工具（含内置 + 外部注册的）
-        - tools=["a", "b"]: 在 BUILTIN_TOOLS 基础上追加指定工具
-        - exclude_tools=["x"]: 从最终列表中排除指定工具（防止递归调用等场景）
+        优先级：
+        - tools 非空: 精确指定工具列表（忽略 tool_groups）
+        - tool_groups 非空: 按分组白名单过滤
+        - 两者都为 None: 返回所有已注册工具
         """
-        if tools is None:
-            # 全部已注册工具
-            tool_names = self.tools.get_tool_names()
+        if tools is not None:
+            tool_names = list(tools)
         else:
-            # BUILTIN_TOOLS + 显式指定的额外工具
-            tool_names = BUILTIN_TOOLS.copy()
-            for t in tools:
-                if t not in tool_names:
-                    tool_names.append(t)
-        if exclude_tools:
-            tool_names = [t for t in tool_names if t not in exclude_tools]
+            tool_names = self.tools.get_tool_names(groups=tool_groups)
         return self.tools.get_schemas(tool_names)
 
     # 默认 system prompt 前缀（当 config.system_prompt 和前端都未提供 system message 时使用）

agent/docs/tools-refactor-plan.md

@@ -1,8 +1,9 @@
 # 工具体系改造方案（Refactor Plan）
 
-> 本文档是**未来规划**，不是现状描述。当前工具体系的状态请看 [`tools.md`](./tools.md)。
+> ✅ **方案一（内容工具族）** 和 **方案二（浏览器工具族）** 已于 2026-04-12 完成落地。
+> 下方保留原始方案文档供参考。沙箱工具已于此前删除。
 >
-> 当方案落地后，记得把本文档对应的章节删除或合并到 `tools.md`。
+> 当前工具体系的状态请看 [`tools.md`](./tools.md)。
 
 ## 背景
 

agent/docs/tools.md

@@ -11,7 +11,8 @@
 3. [ToolResult 和记忆管理](#toolresult-和记忆管理)
 4. [ToolContext 和依赖注入](#toolcontext-和依赖注入)
 5. [高级特性](#高级特性)
-6. [内置基础工具](#内置基础工具)
+6. [工具分组](#工具分组)
+7. [内置基础工具](#内置基础工具)
 7. [集成 Browser-Use](#集成-browser-use)
 8. [最佳实践](#最佳实践)
 
@@ -790,6 +791,50 @@ print(f"Success rate: {stats['success_rate']:.1%}")
 
 ---
 
+## 工具分组
+
+工具通过 `@tool(groups=[...])` 声明所属分组，`RunConfig.tool_groups` 控制 Agent 可用哪些分组。
+
+### 机制
+
+```python
+# 注册时声明分组
+@tool(groups=["browser"])
+async def browser_navigate(url: str) -> ToolResult: ...
+
+@tool(groups=["content", "media"])  # 支持多标签
+async def extract_video_clip(...) -> ToolResult: ...
+```
+
+```python
+# 配置时按分组过滤
+RunConfig(tool_groups=["core", "content"])        # 只用核心 + 内容工具
+RunConfig(tool_groups=["core", "browser"])         # 只用核心 + 浏览器工具
+RunConfig(tool_groups=None)                        # 全部工具（默认）
+RunConfig(tools=["knowledge_search", "read_file"]) # 精确指定（优先于 tool_groups）
+```
+
+### 过滤逻辑
+
+`_get_tool_schemas(tools, tool_groups)` 的优先级：
+
+1. `tools` 非空 → 精确使用指定列表（忽略 `tool_groups`）
+2. `tool_groups` 非空 → 按分组白名单过滤（工具的任一 group 命中即选中）
+3. 两者都为 None → 返回所有已注册工具
+
+### 实现位置
+
+- 分组声明：`@tool(groups=[...])` — `agent/tools/registry.py`
+- 分组存储：`ToolRegistry._tools[name]["groups"]`
+- 分组过滤：`ToolRegistry.get_tool_names(groups=[...])`
+- 配置入口：`RunConfig.tool_groups` — `agent/core/runner.py`
+
+### 分组一览
+
+完整的分组和工具列表见 [agent/README.md 附录](../README.md#附录工具分组)。
+
+---
+
 ## 内置基础工具
 
 > 参考 opencode 实现的文件操作和命令执行工具
@@ -819,6 +864,12 @@ print(f"Success rate: {stats['success_rate']:.1%}")
 | `toolhub_health` | 检查 ToolHub 远程工具库服务状态 | 自研 |
 | `toolhub_search` | 搜索/发现 ToolHub 远程工具 | 自研 |
 | `toolhub_call` | 调用 ToolHub 远程工具（图片参数支持本地文件路径） | 自研 |
+| `content_platforms` | 列出/查询内容平台及其搜索参数（支持模糊匹配） | 自研 |
+| `content_search` | 跨平台内容搜索（11 个平台统一入口） | 自研 |
+| `content_detail` | 查看内容详情（从搜索缓存按索引取） | 自研 |
+| `content_suggest` | 搜索关键词补全建议 | 自研 |
+| `extract_video_clip` | 截取已下载 YouTube 视频的片段 | 自研 |
+| `import_content` | 批量导入文章到 CMS | 自研 |
 | `ask_knowledge` | 向知识库查询信息（通过 KnowHub Librarian） | 自研 |
 | `upload_knowledge` | 上传调研结果到知识库 | 自研 |
 
@@ -846,9 +897,9 @@ print(f"Success rate: {stats['success_rate']:.1%}")
 | 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` 只画序号，传列表则在每格下方画标题。
+**关于标签/标题：** `read_images` 的拼图**不显示文件名**，只显示索引序号——因为本地文件名（如 `IMG_1234.jpg`）对 LLM 理解内容没有帮助，而索引到原始路径的对照表通过返回文本提供，LLM 可以用"第 3 张"这种引用方式精确指代。对比之下 `content_search` 的拼图**会**显示 label（帖子/视频标题），因为这些是内容型元数据，有实际信息量。这一差异反映在 `build_image_grid(labels=...)` 参数上：传 `None` 只画序号，传列表则在每格下方画标题。
 
-网格和降采样的实现在 `agent/tools/utils/image.py`，`search_posts` 和 `youtube_search` 等工具也复用同一套拼图逻辑。
+网格和降采样的实现在 `agent/tools/utils/image.py`，`content_search` 等内容工具也复用同一套拼图逻辑。
 
 ### Agent 工具
 

agent/skill/skills/browser.md

@@ -9,32 +9,38 @@ description: 浏览器自动化工具使用指南
 
 ### 基本工作流程
 
-1. **页面导航**: 使用 `browser_navigate_to_url` 或 `browser_search_web` 到达目标页面
+1. **页面导航**: 使用 `browser_navigate(url)` 或 `browser_search(query)` 到达目标页面
 2. **等待加载**: 页面跳转后调用 `browser_wait(seconds=2)` 等待内容加载
-3. **获取元素索引**: 调用 `browser_get_visual_selector_map` 获取可交互元素的索引映射和当前界面的截图
-4. **执行交互**: 使用 `browser_click_element`、`browser_input_text` 等工具操作页面
-5. **提取内容**: 使用 `browser_extract_content`, `browser_read_long_content`, `browser_get_page_html` 获取数据
+3. **获取元素索引**: 调用 `browser_screenshot(highlight_elements=True)` 获取带编号标注的截图 + 元素列表
+4. **执行交互**: 使用 `browser_interact(action, index, ...)` 操作页面（click / type / send_keys / upload / dropdown）
+5. **提取内容**: 使用 `browser_extract(query)` 让 LLM 提取结构化数据，或 `browser_read(mode="long")` 分页读取长内容
 
 ### 关键原则
 
 - **禁止模拟结果**：不要输出你认为的搜索结果，而是要调用工具获取真实结果
-- **必须先获取索引**: 所有 `index` 参数都需要先通过 `browser_get_selector_map` 获取
-- **高级工具**：优先使用 `browser_extract_content`, `browser_read_long_content` 等工具获取数据，而不是使用 `browser_get_selector_map` 获取索引后手动解析
-- **操作后等待**: 任何可能触发页面变化的操作（点击、输入、滚动）后都要调用 `browser_wait`
+- **必须先获取索引**: 所有 `index` 参数都需要先通过 `browser_screenshot(highlight_elements=True)` 或 `browser_elements()` 获取
+- **高级工具**：优先使用 `browser_extract` / `browser_read` 获取数据，而不是手动解析元素
+- **操作后等待**: 任何可能触发页面变化的操作后都要调用 `browser_wait`
 - **登录处理**:
-  - **正常登录**：当遇到需要登录的网页时，使用 `browser_load_cookies` 来登录
-  - **首次登录**：当没有该网站的 cookie 时，需要请求人类协助登录：
-    1. 调用 `browser_get_live_url` 获取云浏览器实时画面链接
-    2. 导航到目标网站的登录页面
-    3. 通过 `feishu_send_message_to_contact` 将 live URL 发送给相关人员，请求其在浏览器中完成登录
-    4. 使用 `feishu_get_contact_replies(contact_name="...", wait_time_seconds=300)` 等待对方回复确认登录完成
-    5. 收到回复后使用 `browser_export_cookies` 将登录态保存下来
-- **复杂操作用JS**: 当标准工具无法满足时，使用 `browser_evaluate` 执行 JavaScript 代码
-
-### 工具分类
-
-**导航**: browser_get_live_url, browser_navigate_to_url, browser_search_web, browser_go_back, browser_wait
-**交互**: browser_click_element, browser_input_text, browser_send_keys, browser_upload_file
-**视图**: browser_scroll_page, browser_find_text, browser_screenshot
-**提取**: browser_extract_content, browser_read_long_content, browser_get_page_html, browser_get_selector_map, browser_get_visual_selector_map
-**高级**: browser_evaluate, browser_load_cookies, browser_export_cookies, browser_wait_for_user_action, browser_download_direct_url
+  - **正常登录**：使用 `browser_cookies(action="load", url=...)` 注入已保存的 cookie
+  - **首次登录**：需要人类协助——导航到登录页，通过飞书发送链接，等待确认后 `browser_cookies(action="export")` 保存
+- **复杂操作用JS**: 当标准工具无法满足时，使用 `browser_js(code)` 执行 JavaScript
+
+### 工具一览
+
+| 工具 | 功能 |
+|------|------|
+| `browser_navigate(url)` | 导航到 URL |
+| `browser_search(query, engine)` | 搜索引擎搜索 |
+| `browser_back()` | 返回上一页 |
+| `browser_interact(action, ...)` | 元素交互（click/type/send_keys/upload/dropdown） |
+| `browser_scroll(down, pages)` | 滚动页面 |
+| `browser_screenshot(highlight)` | 截图（highlight=True 带元素编号标注） |
+| `browser_elements()` | 获取可交互元素列表（纯文本） |
+| `browser_read(mode)` | 读取页面（html/find/long） |
+| `browser_extract(query)` | LLM 驱动的结构化数据提取 |
+| `browser_tabs(action, tab_id)` | 标签页管理（switch/close） |
+| `browser_cookies(action, ...)` | Cookie/登录态管理（load/export/ensure_login） |
+| `browser_wait(seconds/user_message)` | 等待（定时 or 等用户操作） |
+| `browser_js(code)` | 执行 JavaScript |
+| `browser_download(url)` | 下载文件 |

agent/skill/skills/core.md

@@ -73,7 +73,7 @@ goal(abandon="方案A需要Redis，环境没有")
 
 ## 信息调研
 
-你可以通过联网搜索工具`search_posts`大概浏览来自Github、小红书、微信公众号、知乎等渠道的信息，并再使用`select_post`工具查看具体信息。
+你可以通过 `content_search(platform, keyword)` 搜索来自 GitHub、小红书、微信公众号、知乎、YouTube、X 等平台的信息，再用 `content_detail(platform, index)` 查看完整内容。不确定平台参数时先调 `content_platforms()` 查看。
 对于需要深度交互的网页内容，使用浏览器工具进行操作。
 
 调研过程可能需要多次搜索，比如基于搜索结果中获得的启发或信息启动新的搜索，直到得到令人满意的答案。你可以使用`goal`工具管理搜索的过程，或者使用文档记录搜索的中间或最终结果。
@@ -84,32 +84,38 @@ goal(abandon="方案A需要Redis，环境没有")
 
 ### 基本工作流程
 
-1. **页面导航**: 使用 `browser_navigate_to_url` 或 `browser_search_web` 到达目标页面
+1. **页面导航**: 使用 `browser_navigate(url)` 或 `browser_search(query)` 到达目标页面
 2. **等待加载**: 页面跳转后调用 `browser_wait(seconds=2)` 等待内容加载
-3. **获取元素索引**: 调用 `browser_get_visual_selector_map` 获取可交互元素的索引映射和当前界面的截图
-4. **执行交互**: 使用 `browser_click_element`、`browser_input_text` 等工具操作页面
-5. **提取内容**: 使用 `browser_extract_content`, `browser_read_long_content`, `browser_get_page_html` 获取数据
+3. **获取元素索引**: 调用 `browser_screenshot(highlight_elements=True)` 获取带编号标注的截图 + 元素列表
+4. **执行交互**: 使用 `browser_interact(action, index, ...)` 操作页面（click / type / send_keys / upload / dropdown）
+5. **提取内容**: 使用 `browser_extract(query)` 让 LLM 提取结构化数据，或 `browser_read(mode="long")` 分页读取长内容
 
 ### 关键原则
 
 - **禁止模拟结果**：不要输出你认为的搜索结果，而是要调用工具获取真实结果
-- **必须先获取索引**: 所有 `index` 参数都需要先通过 `browser_get_selector_map` 获取
-- **高级工具**：优先使用`browser_extract_content`, `browser_read_long_content`等工具获取数据，而不是使用`browser_get_selector_map`获取索引后手动解析
-- **操作后等待**: 任何可能触发页面变化的操作（点击、输入、滚动）后都要调用 `browser_wait`
+- **必须先获取索引**: 所有 `index` 参数都需要先通过 `browser_screenshot(highlight_elements=True)` 或 `browser_elements()` 获取
+- **高级工具**：优先使用 `browser_extract` / `browser_read` 获取数据，而不是手动解析元素
+- **操作后等待**: 任何可能触发页面变化的操作后都要调用 `browser_wait`
 - **登录处理**:
-  - **正常登录**：当遇到需要登录的网页时，使用`browser_load_cookies`来登录
-  - **首次登录**：当没有该网站的cookie时，需要请求人类协助登录：
-    1. 调用 `browser_get_live_url` 获取云浏览器实时画面链接
-    2. 导航到目标网站的登录页面
-    3. 通过 `feishu_send_message_to_contact` 将 live URL 发送给相关人员，请求其在浏览器中完成登录
-    4. 使用 `feishu_get_contact_replies(contact_name="...", wait_time_seconds=300)` 等待对方回复确认登录完成
-    5. 收到回复后使用 `browser_export_cookies` 将登录态保存下来
-- **复杂操作用JS**: 当标准工具无法满足时，使用 `browser_evaluate` 执行JavaScript代码
-
-### 工具分类
-
-**导航**: browser_get_live_url, browser_navigate_to_url, browser_search_web, browser_go_back, browser_wait
-**交互**: browser_click_element, browser_input_text, browser_send_keys, browser_upload_file
-**视图**: browser_scroll_page, browser_find_text, browser_screenshot
-**提取**: browser_extract_content, browser_read_long_content, browser_get_page_html, browser_get_selector_map, browser_get_visual_selector_map
-**高级**: browser_evaluate, browser_load_cookies, browser_export_cookies, browser_wait_for_user_action, browser_download_direct_url
+  - **正常登录**：使用 `browser_cookies(action="load", url=...)` 注入已保存的 cookie
+  - **首次登录**：需要人类协助——导航到登录页，通过飞书发送链接，等待确认后 `browser_cookies(action="export")` 保存
+- **复杂操作用JS**: 当标准工具无法满足时，使用 `browser_js(code)` 执行 JavaScript
+
+### 工具一览
+
+| 工具 | 功能 |
+|------|------|
+| `browser_navigate(url)` | 导航到 URL |
+| `browser_search(query, engine)` | 搜索引擎搜索 |
+| `browser_back()` | 返回上一页 |
+| `browser_interact(action, ...)` | 元素交互（click/type/send_keys/upload/dropdown） |
+| `browser_scroll(down, pages)` | 滚动页面 |
+| `browser_screenshot(highlight)` | 截图（highlight=True 带元素编号标注） |
+| `browser_elements()` | 获取可交互元素列表（纯文本） |
+| `browser_read(mode)` | 读取页面（html/find/long） |
+| `browser_extract(query)` | LLM 驱动的结构化数据提取 |
+| `browser_tabs(action, tab_id)` | 标签页管理（switch/close） |
+| `browser_cookies(action, ...)` | Cookie/登录态管理（load/export/ensure_login） |
+| `browser_wait(seconds/user_message)` | 等待（定时 or 等用户操作） |
+| `browser_js(code)` | 执行 JavaScript |
+| `browser_download(url)` | 下载文件 |

agent/skill/skills/research.md

@@ -5,7 +5,7 @@ description: 知识调研 - 根据目标和任务自动执行搜索，返回结
 
 ## 信息调研
 
-你可以通过联网搜索工具`search_posts`大概浏览来自Github、小红书、微信公众号、知乎等渠道的信息，并再使用`select_post`工具查看具体信息。
+你可以通过 `content_search` 工具搜索来自 GitHub、小红书、微信公众号、知乎、YouTube、X 等平台的信息，并使用 `content_detail` 查看具体内容。如不确定平台参数，先调 `content_platforms` 查看。
 
 ## 调研过程可能需要多次搜索，比如基于搜索结果中获得的启发或信息启动新的搜索，直到得到令人满意的答案。你可以使用 `goal` 工具管理搜索的过程，或者使用文档记录搜索的中间或最终结果。（可以着重参考browser的工具来辅助搜索）
 
@@ -26,10 +26,10 @@ goal(add="搜索工具, 搜索案例, 搜索方法论")
 
 **Step 2: 多维度搜索**
 
-- 搜索工具：`search_posts(query="PDF table extraction tool")`
-- 搜索案例：`search_posts(query="PDF table extraction usercase site:github.com")`
-- 搜索定义：`search_posts(query="PDF table extraction definition")`
-- 搜索方法：`search_posts(query="PDF table extraction best practice")`
+- 搜索工具：`content_search(platform="github", keyword="PDF table extraction tool")`
+- 搜索案例：`content_search(platform="xhs", keyword="PDF表格提取")`
+- 搜索定义：`content_search(platform="zhihu", keyword="PDF table extraction")`
+- 搜索方法：`content_search(platform="gzh", keyword="PDF table extraction best practice")`
 
 **Step 3: 结构化记录**
 每发现一条有价值的信息，立即保存为结构化知识：

agent/tools/builtin/__init__.py

@@ -16,14 +16,16 @@ from agent.tools.builtin.file.grep import grep_content
 from agent.tools.builtin.bash import bash_command
 from agent.tools.builtin.skill import skill, list_skills
 from agent.tools.builtin.subagent import agent, evaluate
-from agent.tools.builtin.search import search_posts, get_search_suggestions
-# sandbox 工具已废弃（2026-04）：原本是给"运行工具"场景准备的，但工具已被抽到 toolhub 单独处理
+# sandbox 工具已废弃（2026-04）；search.py / crawler.py 已重构为 content/ 工具族（2026-04）
 from agent.tools.builtin.knowledge import(knowledge_search,knowledge_save,knowledge_list,knowledge_update,knowledge_batch_update,knowledge_slim)
 from agent.tools.builtin.librarian import ask_knowledge, upload_knowledge
 from agent.tools.builtin.context import get_current_context
 from agent.tools.builtin.toolhub import toolhub_health, toolhub_search, toolhub_call
 from agent.tools.builtin.resource import resource_list_tools, resource_get_tool
-from agent.tools.builtin.crawler import youtube_search, youtube_detail, x_search, import_content, extract_video_clip
+from agent.tools.builtin.content import (
+    content_platforms, content_search, content_detail, content_suggest,
+    extract_video_clip, import_content,
+)
 from agent.trace.goal_tool import goal
 # 导入浏览器工具以触发注册
 import agent.tools.builtin.browser  # noqa: F401
@@ -55,9 +57,11 @@ __all__ = [
     "list_skills",
     "agent",
     "evaluate",
-    "search_posts",
-    "select_post",
-    "get_search_suggestions",
+    # 内容工具族（重构自 search.py + crawler.py）
+    "content_platforms",
+    "content_search",
+    "content_detail",
+    "content_suggest",
     # 上下文工具
     "get_current_context",
     # ToolHub 远程工具库
@@ -68,12 +72,9 @@ __all__ = [
     # 资源查询
     "resource_list_tools",
     "resource_get_tool",
-    # 爬虫工具
-    "youtube_search",
-    "youtube_detail",
-    "x_search",
-    "import_content",
+    # 媒体 / 导入
     "extract_video_clip",
+    "import_content",
     # Goal 管理
     "goal",
 ]

agent/tools/builtin/bash.py

@@ -158,7 +158,7 @@ def _kill_process_tree(pid: int) -> None:
         pass
 
 
-@tool(description="执行 bash 命令", hidden_params=["context"])
+@tool(description="执行 bash 命令", hidden_params=["context"], groups=["core"])
 async def bash_command(
     command: str,
     timeout: Optional[int] = None,

agent/tools/builtin/browser/__init__.py

@@ -2,63 +2,32 @@
 浏览器工具 - Browser-Use 原生工具适配器
 
 基于 browser-use 实现的浏览器自动化工具集。
+28 个原始工具已合并为 14 个语义化入口（2026-04 重构）。
 """
 
 from agent.tools.builtin.browser.baseClass import (
-    # 会话管理
+    # 会话管理（非 @tool，供框架内部调用）
     init_browser_session,
     get_browser_session,
     get_browser_live_url,
     cleanup_browser_session,
     kill_browser_session,
 
-    # 导航类工具
-    browser_get_live_url,
-    browser_navigate_to_url,
-    browser_search_web,
-    browser_go_back,
-    browser_wait,
-
-    # 元素交互工具
-    browser_click_element,
-    browser_input_text,
-    browser_send_keys,
-    browser_upload_file,
-
-    # 滚动和视图工具
-    browser_scroll_page,
-    browser_find_text,
+    # 14 个 @tool 入口
+    browser_navigate,
+    browser_search,
+    browser_back,
+    browser_interact,
+    browser_scroll,
     browser_screenshot,
-
-    # 标签页管理工具
-    browser_switch_tab,
-    browser_close_tab,
-
-    # 下拉框工具
-    browser_get_dropdown_options,
-    browser_select_dropdown_option,
-
-    # 内容提取工具
-    browser_extract_content,
-    browser_read_long_content,
-    browser_get_page_html,
-    browser_download_direct_url,
-    browser_get_selector_map,
-    browser_get_visual_selector_map,
-
-    # JavaScript 执行工具
-    browser_evaluate,
-    browser_ensure_login_with_cookies,
-
-    # 等待用户操作
-    browser_wait_for_user_action,
-
-    # 任务完成
-    browser_done,
-
-    # Cookie 持久化
-    browser_export_cookies,
-    browser_load_cookies,
+    browser_elements,
+    browser_read,
+    browser_extract,
+    browser_tabs,
+    browser_cookies,
+    browser_wait,
+    browser_js,
+    browser_download,
 )
 
 __all__ = [
@@ -69,51 +38,19 @@ __all__ = [
     'cleanup_browser_session',
     'kill_browser_session',
 
-    # 导航类工具
-    'browser_get_live_url',
-    'browser_navigate_to_url',
-    'browser_search_web',
-    'browser_go_back',
-    'browser_wait',
-
-    # 元素交互工具
-    'browser_click_element',
-    'browser_input_text',
-    'browser_send_keys',
-    'browser_upload_file',
-
-    # 滚动和视图工具
-    'browser_scroll_page',
-    'browser_find_text',
+    # @tool 入口
+    'browser_navigate',
+    'browser_search',
+    'browser_back',
+    'browser_interact',
+    'browser_scroll',
     'browser_screenshot',
-
-    # 标签页管理工具
-    'browser_switch_tab',
-    'browser_close_tab',
-
-    # 下拉框工具
-    'browser_get_dropdown_options',
-    'browser_select_dropdown_option',
-
-    # 内容提取工具
-    'browser_extract_content',
-    'browser_read_long_content',
-    'browser_download_direct_url',
-    'browser_get_page_html',
-    'browser_get_selector_map',
-    'browser_get_visual_selector_map',
-
-    # JavaScript 执行工具
-    'browser_evaluate',
-    'browser_ensure_login_with_cookies',
-
-    # 等待用户操作
-    'browser_wait_for_user_action',
-
-    # 任务完成
-    'browser_done',
-
-    # Cookie 持久化
-    'browser_export_cookies',
-    'browser_load_cookies',
+    'browser_elements',
+    'browser_read',
+    'browser_extract',
+    'browser_tabs',
+    'browser_cookies',
+    'browser_wait',
+    'browser_js',
+    'browser_download',
 ]

agent/tools/builtin/browser/baseClass.py

@@ -52,7 +52,7 @@ import aiohttp
 import re
 import base64
 from urllib.parse import urlparse, parse_qs, unquote
-from typing import Optional, List, Dict, Any, Tuple, Union
+from typing import Literal, Optional, List, Dict, Any, Tuple, Union
 from pathlib import Path
 from langchain_core.runnables import RunnableLambda
 from argparse import Namespace # 使用 Namespace 快速构造带属性的对象
@@ -548,7 +548,6 @@ def _fetch_profile_id(cookie_type: str) -> Optional[str]:
 # 导航类工具 (Navigation Tools)
 # ============================================================
 
-@tool()
 async def browser_get_live_url() -> ToolResult:
     """
     获取云浏览器的实时画面链接（Live URL），可用于在本地浏览器中查看或分享给他人操作。
@@ -567,7 +566,6 @@ async def browser_get_live_url() -> ToolResult:
     )
 
 
-@tool()
 async def browser_navigate_to_url(url: str, new_tab: bool = False) -> ToolResult:
     """
     导航到指定的 URL
@@ -607,7 +605,6 @@ async def browser_navigate_to_url(url: str, new_tab: bool = False) -> ToolResult
         )
 
 
-@tool()
 async def browser_search_web(query: str, engine: str = "bing") -> ToolResult:
     """
     使用搜索引擎搜索
@@ -644,7 +641,6 @@ async def browser_search_web(query: str, engine: str = "bing") -> ToolResult:
         )
 
 
-@tool()
 async def browser_go_back() -> ToolResult:
     """
     返回到上一个页面
@@ -671,10 +667,9 @@ async def browser_go_back() -> ToolResult:
         )
 
 
-@tool()
-async def browser_wait(seconds: int = 3) -> ToolResult:
+async def browser_wait_impl(seconds: int = 3) -> ToolResult:
     """
-    等待指定的秒数
+    等待指定的秒数（内部实现）
     Wait for a specified number of seconds
 
     用于等待页面加载、动画完成或其他异步操作。
@@ -732,7 +727,6 @@ class DownloadLinkCaptureHandler(logging.Handler):
                     self.captured_url = url
                     # print(f"🎯 成功锁定完整直链: {url[:50]}...") # 调试用
 
-@tool()
 async def browser_download_direct_url(url: str, save_name: str = "book.epub") -> ToolResult:
     save_dir = Path.cwd() / ".cache/.browser_use_files"
     save_dir.mkdir(parents=True, exist_ok=True)
@@ -797,7 +791,6 @@ async def browser_download_direct_url(url: str, save_name: str = "book.epub") ->
             long_term_memory=f"下载任务由于异常中断: {str(e)}"
         )
     
-@tool()
 async def browser_click_element(index: int) -> ToolResult:
     """
     点击页面元素，并自动通过拦截内部日志获取下载直链。
@@ -847,7 +840,6 @@ async def browser_click_element(index: int) -> ToolResult:
         logger.removeHandler(capture_handler)
 
 
-@tool()
 async def browser_input_text(index: int, text: str, clear: bool = True) -> ToolResult:
     """
     在指定元素中输入文本
@@ -885,7 +877,6 @@ async def browser_input_text(index: int, text: str, clear: bool = True) -> ToolR
         )
 
 
-@tool()
 async def browser_send_keys(keys: str) -> ToolResult:
     """
     发送键盘按键或快捷键
@@ -925,7 +916,6 @@ async def browser_send_keys(keys: str) -> ToolResult:
         )
 
 
-@tool()
 async def browser_upload_file(index: int, path: str) -> ToolResult:
     """
     上传文件到文件输入元素
@@ -968,7 +958,6 @@ async def browser_upload_file(index: int, path: str) -> ToolResult:
 # ============================================================
 # 滚动和视图工具 (Scroll & View Tools)
 # ============================================================
-@tool()
 async def browser_scroll_page(down: bool = True, pages: float = 1.0, index: Optional[int] = None) -> ToolResult:
     try:
         # 限制单次滚动幅度，避免 agent 一次滚 100 页
@@ -1028,7 +1017,6 @@ async def browser_scroll_page(down: bool = True, pages: float = 1.0, index: Opti
 
 
 
-@tool()
 async def browser_find_text(text: str) -> ToolResult:
     """
     查找页面中的文本并滚动到该位置
@@ -1063,7 +1051,6 @@ async def browser_find_text(text: str) -> ToolResult:
             long_term_memory=f"查找文本 '{text}' 失败"
         )
 
-@tool()
 async def browser_get_visual_selector_map() -> ToolResult:
     """
     获取当前页面的视觉快照和交互元素索引映射。
@@ -1160,10 +1147,9 @@ async def browser_get_visual_selector_map() -> ToolResult:
             long_term_memory="获取视觉元素映射失败"
         )
     
-@tool()
-async def browser_screenshot() -> ToolResult:
+async def browser_screenshot_impl() -> ToolResult:
     """
-    请求在下次观察中包含页面截图
+    请求在下次观察中包含页面截图（内部实现）
     Request a screenshot to be included in the next observation
 
     用于视觉检查页面状态，帮助理解页面布局和内容。
@@ -1197,7 +1183,6 @@ async def browser_screenshot() -> ToolResult:
 # 标签页管理工具 (Tab Management Tools)
 # ============================================================
 
-@tool()
 async def browser_switch_tab(tab_id: str) -> ToolResult:
     """
     切换到指定标签页
@@ -1232,7 +1217,6 @@ async def browser_switch_tab(tab_id: str) -> ToolResult:
         )
 
 
-@tool()
 async def browser_close_tab(tab_id: str) -> ToolResult:
     """
     关闭指定标签页
@@ -1271,7 +1255,6 @@ async def browser_close_tab(tab_id: str) -> ToolResult:
 # 下拉框工具 (Dropdown Tools)
 # ============================================================
 
-@tool()
 async def browser_get_dropdown_options(index: int) -> ToolResult:
     """
     获取下拉框的所有选项
@@ -1305,7 +1288,6 @@ async def browser_get_dropdown_options(index: int) -> ToolResult:
         )
 
 
-@tool()
 async def browser_select_dropdown_option(index: int, text: str) -> ToolResult:
     """
     选择下拉框选项
@@ -1408,7 +1390,6 @@ async def extraction_adapter(input_data):
     from argparse import Namespace
     return Namespace(completion=content)
 
-@tool()
 async def browser_extract_content(query: str, extract_links: bool = False,
                          start_from_char: int = 0) -> ToolResult:
     """
@@ -1550,7 +1531,6 @@ async def _detect_and_download_pdf_via_cdp(browser) -> Optional[str]:
         return None
 
 
-@tool()
 async def browser_read_long_content(
     goal: Union[str, dict],
     source: str = "page",
@@ -1609,7 +1589,6 @@ async def browser_read_long_content(
             error=f"Read long content failed: {str(e)}",
             long_term_memory="参数解析或校验失败，请检查输入"
         )
-@tool()
 async def browser_get_page_html() -> ToolResult:
     """
     获取当前页面的完整 HTML
@@ -1671,7 +1650,6 @@ async def browser_get_page_html() -> ToolResult:
         )
 
 
-@tool()
 async def browser_get_selector_map() -> ToolResult:
     """
     获取当前页面的元素索引映射
@@ -1743,7 +1721,6 @@ async def browser_get_selector_map() -> ToolResult:
 # JavaScript 执行工具 (JavaScript Tools)
 # ============================================================
 
-@tool()
 async def browser_evaluate(code: str) -> ToolResult:
     """
     在页面中执行 JavaScript 代码
@@ -1785,7 +1762,6 @@ async def browser_evaluate(code: str) -> ToolResult:
         )
 
 
-@tool()
 async def browser_ensure_login_with_cookies(cookie_type: str, url: str = "https://www.xiaohongshu.com") -> ToolResult:
     """
     检查登录状态并在需要时注入 cookies
@@ -1881,7 +1857,6 @@ async def browser_ensure_login_with_cookies(cookie_type: str, url: str = "https:
 # 等待用户操作工具 (Wait for User Action)
 # ============================================================
 
-@tool()
 async def browser_wait_for_user_action(message: str = "Please complete the action in browser",
                                timeout: int = 300) -> ToolResult:
     """
@@ -1953,7 +1928,6 @@ async def browser_wait_for_user_action(message: str = "Please complete the actio
 # 任务完成工具 (Task Completion)
 # ============================================================
 
-@tool()
 async def browser_done(text: str, success: bool = True,
               files_to_display: Optional[List[str]] = None) -> ToolResult:
     """
@@ -1998,7 +1972,6 @@ async def browser_done(text: str, success: bool = True,
 
 _COOKIES_DIR = Path(__file__).parent.parent.parent.parent.parent / ".cache/.cookies"
 
-@tool()
 async def browser_export_cookies(name: str = "", account: str = "") -> ToolResult:
     """
     导出当前浏览器的所有 Cookie 到本地 .cookies/ 目录。
@@ -2042,7 +2015,6 @@ async def browser_export_cookies(name: str = "", account: str = "") -> ToolResul
         return ToolResult(title="Cookie 导出失败", output="", error=str(e), long_term_memory="导出 Cookie 失败")
 
 
-@tool()
 async def browser_load_cookies(url: str, name: str = "", auto_navigate: bool = True) -> ToolResult:
     """
     根据目标 URL 自动查找本地 Cookie 文件，注入浏览器并导航到目标页面恢复登录态。
@@ -2178,60 +2150,345 @@ async def browser_load_cookies(url: str, name: str = "", auto_navigate: bool = T
 
 
 # ============================================================
-# 导出所有工具函数（供外部使用）
+# 新版统一入口（13 个 @tool，替代原来 28 个）
 # ============================================================
 
-__all__ = [
-    # 会话管理
-    'init_browser_session',
-    'get_browser_session',
-    'cleanup_browser_session',
-    'kill_browser_session',
 
-    # 导航类工具
-    'browser_navigate_to_url',
-    'browser_search_web',
-    'browser_go_back',
-    'browser_wait',
+@tool(groups=["browser"])
+async def browser_navigate(url: str, new_tab: bool = False) -> ToolResult:
+    """
+    导航到指定 URL。
 
-    # 元素交互工具
-    'browser_click_element',
-    'browser_input_text',
-    'browser_send_keys',
-    'browser_upload_file',
+    Args:
+        url: 目标 URL
+        new_tab: 是否在新标签页打开（默认 False）
+    """
+    return await browser_navigate_to_url(url=url, new_tab=new_tab)
 
-    # 滚动和视图工具
-    'browser_scroll_page',
-    'browser_find_text',
-    'browser_screenshot',
 
-    # 标签页管理工具
-    'browser_switch_tab',
-    'browser_close_tab',
+@tool(groups=["browser"])
+async def browser_search(query: str, engine: str = "bing") -> ToolResult:
+    """
+    使用搜索引擎搜索。
+
+    Args:
+        query: 搜索关键词
+        engine: 搜索引擎，可选 google / bing / duckduckgo，默认 bing
+    """
+    return await browser_search_web(query=query, engine=engine)
+
+
+@tool(groups=["browser"])
+async def browser_back() -> ToolResult:
+    """返回上一页。"""
+    return await browser_go_back()
+
+
+@tool(groups=["browser"])
+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:
+    """
+    与页面元素交互。根据 action 选择具体操作：
+
+    - click: 点击元素。需要 index。
+    - type: 在输入框输入文本。需要 index + text。clear 控制是否先清空。
+    - send_keys: 发送键盘按键（如 Enter、Control+A）。需要 keys，不需要 index。
+    - upload: 上传文件到文件输入框。需要 index + path（绝对路径）。
+    - dropdown_list: 列出下拉框选项。需要 index。
+    - dropdown_select: 选择下拉框选项。需要 index + text（选项文本）。
+
+    Args:
+        action: 交互类型
+        index: 元素索引（从 browser_elements 或 browser_screenshot(highlight=True) 获取）
+        text: 输入文本 / 下拉框选项文本
+        path: 上传文件的绝对路径
+        keys: 键盘按键字符串（如 "Enter"、"Control+A"）
+        clear: type 时是否先清空（默认 True）
+    """
+    if action == "click":
+        if index is None:
+            return ToolResult(title="参数错误", output="", error="click 需要 index 参数")
+        return await browser_click_element(index=index)
+
+    elif action == "type":
+        if index is None or text is None:
+            return ToolResult(title="参数错误", output="", error="type 需要 index 和 text 参数")
+        return await browser_input_text(index=index, text=text, clear=clear)
+
+    elif action == "send_keys":
+        if keys is None:
+            return ToolResult(title="参数错误", output="", error="send_keys 需要 keys 参数")
+        return await browser_send_keys(keys=keys)
+
+    elif action == "upload":
+        if index is None or path is None:
+            return ToolResult(title="参数错误", output="", error="upload 需要 index 和 path 参数")
+        return await browser_upload_file(index=index, path=path)
+
+    elif action == "dropdown_list":
+        if index is None:
+            return ToolResult(title="参数错误", output="", error="dropdown_list 需要 index 参数")
+        return await browser_get_dropdown_options(index=index)
+
+    elif action == "dropdown_select":
+        if index is None or text is None:
+            return ToolResult(title="参数错误", output="", error="dropdown_select 需要 index 和 text 参数")
+        return await browser_select_dropdown_option(index=index, text=text)
+
+    else:
+        return ToolResult(title="未知 action", output="", error=f"不支持的 action: {action}")
+
+
+@tool(groups=["browser"])
+async def browser_scroll(
+    down: bool = True,
+    pages: float = 1.0,
+    into_view_index: Optional[int] = None,
+) -> ToolResult:
+    """
+    滚动页面。
+
+    Args:
+        down: True 向下滚动，False 向上（默认 True）
+        pages: 滚动的页面数（默认 1.0）
+        into_view_index: 传入元素索引则滚动到该元素可见（忽略 down 和 pages）
+    """
+    return await browser_scroll_page(down=down, pages=pages, index=into_view_index)
+
+
+@tool(groups=["browser"])
+async def browser_screenshot(highlight_elements: bool = False) -> ToolResult:
+    """
+    截取当前页面。
+
+    Args:
+        highlight_elements: False 返回纯截图；True 返回带交互元素编号标注的截图
+                           + 元素列表（原 visual_selector_map 功能）
+    """
+    if highlight_elements:
+        return await browser_get_visual_selector_map()
+    else:
+        return await browser_screenshot_impl()
+
+
+@tool(groups=["browser"])
+async def browser_elements() -> ToolResult:
+    """
+    获取当前页面的可交互元素列表（纯文本，不截图）。
+    返回的 index 用于 browser_interact / browser_scroll 等操作。
+    """
+    return await browser_get_selector_map()
+
+
+@tool(groups=["browser"])
+async def browser_read(
+    mode: Literal["html", "find", "long"],
+    query: Optional[str] = None,
+    source: str = "page",
+    context: str = "",
+) -> ToolResult:
+    """
+    读取页面内容，三种模式：
+
+    - html: 获取当前页面的 HTML 源码（大页面会截断到 10000 字符）
+    - find: 在页面中查找文本。需要 query。
+    - long: 智能分页读取长内容（支持自动检测 PDF）。query 描述阅读目标。
+
+    Args:
+        mode: 读取模式
+        query: find 模式下的查找文本；long 模式下的阅读目标描述
+        source: long 模式的内容来源（"page" 或文件路径），默认 "page"
+        context: long 模式的业务背景（可选）
+    """
+    if mode == "html":
+        return await browser_get_page_html()
+
+    elif mode == "find":
+        if not query:
+            return ToolResult(title="参数错误", output="", error="find 模式需要 query 参数")
+        return await browser_find_text(text=query)
+
+    elif mode == "long":
+        return await browser_read_long_content(
+            goal=query or "阅读页面内容",
+            source=source,
+            context=context,
+        )
+
+    else:
+        return ToolResult(title="未知 mode", output="", error=f"不支持的 mode: {mode}")
+
+
+@tool(groups=["browser"])
+async def browser_extract(
+    query: str,
+    extract_links: bool = False,
+    start_from_char: int = 0,
+) -> ToolResult:
+    """
+    使用 LLM 从当前页面提取结构化数据。
+
+    与 browser_read 不同，此工具会调用 LLM 分析页面内容并返回结构化结果。
+    适合"提取所有产品价格"、"总结文章要点"等需要理解语义的场景。
+
+    Args:
+        query: 提取指令（如"提取页面上所有产品名称和价格"）
+        extract_links: 是否同时提取链接（默认 False）
+        start_from_char: 从第几个字符开始提取（用于分页处理大内容）
+    """
+    return await browser_extract_content(
+        query=query,
+        extract_links=extract_links,
+        start_from_char=start_from_char,
+    )
+
+
+@tool(groups=["browser"])
+async def browser_tabs(
+    action: Literal["switch", "close"],
+    tab_id: str = "",
+) -> ToolResult:
+    """
+    管理浏览器标签页。
+
+    Args:
+        action: "switch" 切换到指定标签页；"close" 关闭指定标签页
+        tab_id: 标签页 ID（4 字符）
+    """
+    if not tab_id:
+        return ToolResult(title="参数错误", output="", error="需要 tab_id 参数")
+
+    if action == "switch":
+        return await browser_switch_tab(tab_id=tab_id)
+    elif action == "close":
+        return await browser_close_tab(tab_id=tab_id)
+    else:
+        return ToolResult(title="未知 action", output="", error=f"不支持的 action: {action}")
+
+
+@tool(groups=["browser"])
+async def browser_cookies(
+    action: Literal["load", "export", "ensure_login"],
+    url: str = "",
+    name: str = "",
+    account: str = "",
+    cookie_type: str = "",
+    auto_navigate: bool = True,
+) -> ToolResult:
+    """
+    Cookie / 登录态管理：
+
+    - load: 从本地加载已保存的 cookie 并注入浏览器。需要 url（自动匹配 cookie 文件）。
+    - export: 导出当前浏览器 cookie 到本地。可选 name 和 account 标识。
+    - ensure_login: 检查登录状态，未登录时自动注入 cookie。需要 cookie_type 和 url。
+
+    Args:
+        action: 操作类型
+        url: 目标 URL（load / ensure_login 必填）
+        name: cookie 文件名（可选）
+        account: 账号名（export 时可选）
+        cookie_type: cookie 类型标识（ensure_login 必填）
+        auto_navigate: load 时找不到 cookie 是否自动导航到目标页面（默认 True）
+    """
+    if action == "load":
+        if not url:
+            return ToolResult(title="参数错误", output="", error="load 需要 url 参数")
+        return await browser_load_cookies(url=url, name=name, auto_navigate=auto_navigate)
+
+    elif action == "export":
+        return await browser_export_cookies(name=name, account=account)
+
+    elif action == "ensure_login":
+        if not cookie_type:
+            return ToolResult(title="参数错误", output="", error="ensure_login 需要 cookie_type 参数")
+        return await browser_ensure_login_with_cookies(
+            cookie_type=cookie_type,
+            url=url or "https://www.xiaohongshu.com",
+        )
+
+    else:
+        return ToolResult(title="未知 action", output="", error=f"不支持的 action: {action}")
 
-    # 下拉框工具
-    'browser_get_dropdown_options',
-    'browser_select_dropdown_option',
 
-    # 内容提取工具
-    'browser_extract_content',
-    'browser_get_page_html',
-    'browser_read_long_content',
-    'browser_download_direct_url',
-    'browser_get_selector_map',
-    'browser_get_visual_selector_map',
+@tool(groups=["browser"])
+async def browser_wait(
+    seconds: Optional[int] = None,
+    user_message: Optional[str] = None,
+    timeout: int = 300,
+) -> ToolResult:
+    """
+    等待。两种模式：
+
+    - 传 seconds: 纯等待指定秒数（默认 3 秒）
+    - 传 user_message: 暂停并提示用户在浏览器中完成操作（如登录、验证码），
+      用户完成后按回车继续。timeout 控制最长等待时间。
+    - 两者都不传: 默认等待 3 秒
+
+    Args:
+        seconds: 等待秒数
+        user_message: 用户操作提示消息
+        timeout: user_message 模式的最长等待（秒），默认 300
+    """
+    if user_message:
+        return await browser_wait_for_user_action(message=user_message, timeout=timeout)
+    else:
+        return await browser_wait_impl(seconds=seconds or 3)
+
+
+@tool(groups=["browser"])
+async def browser_js(code: str) -> ToolResult:
+    """
+    在当前页面执行 JavaScript 代码。
+
+    Args:
+        code: JavaScript 代码字符串。返回值会被自动序列化。
+    """
+    return await browser_evaluate(code=code)
+
 
-    # JavaScript 执行工具
-    'browser_evaluate',
-    'browser_ensure_login_with_cookies',
+@tool(groups=["browser"])
+async def browser_download(url: str, save_name: str = "") -> ToolResult:
+    """
+    下载指定 URL 的文件到本地。
+
+    Args:
+        url: 文件 URL
+        save_name: 保存文件名（可选，默认自动推断）
+    """
+    return await browser_download_direct_url(url=url, save_name=save_name or "download")
 
-    # 等待用户操作
-    'browser_wait_for_user_action',
 
-    # 任务完成
-    'browser_done',
+# ============================================================
+# 导出（供外部使用）
+# ============================================================
+
+__all__ = [
+    # 会话管理（非 @tool）
+    'init_browser_session',
+    'get_browser_session',
+    'get_browser_live_url',
+    'cleanup_browser_session',
+    'kill_browser_session',
 
-    # Cookie 持久化
-    'browser_export_cookies',
-    'browser_load_cookies',
+    # 13 个 @tool 入口
+    'browser_navigate',
+    'browser_search',
+    'browser_back',
+    'browser_interact',
+    'browser_scroll',
+    'browser_screenshot',
+    'browser_elements',
+    'browser_read',
+    'browser_extract',
+    'browser_tabs',
+    'browser_cookies',
+    'browser_wait',
+    'browser_js',
+    'browser_download',
 ]

agent/tools/builtin/content/__init__.py

@@ -0,0 +1,29 @@
+"""
+内容工具族 —— 统一的跨平台内容搜索/详情/建议词 + 媒体处理 + 内容导入
+
+@tool 入口：
+  content_platforms  - 查看平台及参数
+  content_search     - 跨平台搜索
+  content_detail     - 查看详情
+  content_suggest    - 搜索建议词
+  extract_video_clip - YouTube 视频片段截取
+  import_content     - 内容批量导入 CMS
+"""
+
+from agent.tools.builtin.content.tools import (
+    content_platforms,
+    content_search,
+    content_detail,
+    content_suggest,
+)
+from agent.tools.builtin.content.media import extract_video_clip
+from agent.tools.builtin.content.ingestion import import_content
+
+__all__ = [
+    "content_platforms",
+    "content_search",
+    "content_detail",
+    "content_suggest",
+    "extract_video_clip",
+    "import_content",
+]

agent/tools/builtin/content/cache.py

@@ -0,0 +1,86 @@
+"""
+内容搜索缓存（磁盘持久化）
+
+搜索结果按 trace_id 隔离，同一 Agent session 内的 CLI 多次调用也能复用。
+文件格式：/tmp/content_cache_{trace_id}.json
+"""
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+_CACHE_DIR = Path("/tmp")
+_CACHE_TTL = 3600  # 1 小时过期
+
+
+def _cache_path(trace_id: str) -> Path:
+    safe_id = trace_id.replace("/", "_").replace("..", "_")
+    return _CACHE_DIR / f"content_cache_{safe_id}.json"
+
+
+def _load_raw(trace_id: str) -> dict:
+    p = _cache_path(trace_id)
+    if not p.exists():
+        return {}
+    try:
+        data = json.loads(p.read_text("utf-8"))
+        # 检查过期
+        if time.time() - data.get("_ts", 0) > _CACHE_TTL:
+            p.unlink(missing_ok=True)
+            return {}
+        return data
+    except Exception:
+        return {}
+
+
+def _save_raw(trace_id: str, data: dict) -> None:
+    data["_ts"] = time.time()
+    try:
+        _cache_path(trace_id).write_text(
+            json.dumps(data, ensure_ascii=False), encoding="utf-8"
+        )
+    except Exception:
+        pass
+
+
+def save_search_results(
+    trace_id: str,
+    platform: str,
+    keyword: str,
+    posts: List[Dict[str, Any]],
+) -> None:
+    """保存搜索结果到磁盘缓存"""
+    data = _load_raw(trace_id)
+    # 每个 platform 只保留最近一次搜索
+    data[f"search:{platform}"] = {
+        "keyword": keyword,
+        "posts": posts,
+    }
+    _save_raw(trace_id, data)
+
+
+def get_cached_post(
+    trace_id: str,
+    platform: str,
+    index: int,
+) -> Optional[Dict[str, Any]]:
+    """按索引从缓存取一条完整记录（1-based）"""
+    data = _load_raw(trace_id)
+    entry = data.get(f"search:{platform}")
+    if not entry:
+        return None
+    posts = entry.get("posts", [])
+    if 1 <= index <= len(posts):
+        return posts[index - 1]
+    return None
+
+
+def get_cached_search_info(trace_id: str, platform: str) -> Optional[Dict[str, Any]]:
+    """获取缓存的搜索信息（keyword + 总条数），用于错误提示"""
+    data = _load_raw(trace_id)
+    entry = data.get(f"search:{platform}")
+    if not entry:
+        return None
+    return {"keyword": entry.get("keyword"), "total": len(entry.get("posts", []))}

agent/tools/builtin/content/ingestion.py

@@ -0,0 +1,46 @@
+"""
+内容导入工具
+
+将文章链接批量导入 AIGC CMS 系统。
+"""
+
+import json
+from typing import Any, Dict, List
+
+import httpx
+
+from agent.tools import tool, ToolResult
+
+AIGC_BASE_URL = "http://aigc-channel.aiddit.com/aigc/channel"
+DEFAULT_TIMEOUT = 60.0
+
+
+@tool(groups=["content"])
+async def import_content(plan_name: str, content_data: List[Dict[str, Any]]) -> ToolResult:
+    """
+    导入长文内容到 CMS（微信公众号、小红书、抖音等通用链接）。
+
+    Args:
+        plan_name: 计划名称
+        content_data: 内容数据列表，每项包含 channel、content_link、title 等字段
+    """
+    try:
+        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
+            response = await client.post(
+                f"{AIGC_BASE_URL}/weixin/auto_insert",
+                json={"plan_name": plan_name, "data": content_data},
+            )
+            response.raise_for_status()
+            data = response.json()
+
+        if data.get("code") == 0:
+            result_data = data.get("data", {})
+            return ToolResult(
+                title=f"内容导入: {plan_name}",
+                output=json.dumps(result_data, ensure_ascii=False, indent=2),
+                long_term_memory=f"Imported {len(content_data)} items to plan '{plan_name}'",
+            )
+        return ToolResult(title="导入失败", output="", error=f"导入失败: {data.get('msg', '未知错误')}")
+
+    except Exception as e:
+        return ToolResult(title="内容导入异常", output="", error=str(e))

agent/tools/builtin/content/media.py

@@ -0,0 +1,114 @@
+"""
+媒体处理工具
+
+- extract_video_clip: 从已下载的 YouTube 视频中截取片段
+- download_youtube_video / parse_srt_to_outline: 供 YouTube 详情调用的辅助函数
+"""
+
+import asyncio
+import json
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from agent.tools import tool, ToolResult
+
+VIDEO_DOWNLOAD_DIR = Path(tempfile.gettempdir()) / "youtube_videos"
+VIDEO_DOWNLOAD_DIR.mkdir(exist_ok=True)
+
+
+# ── 辅助函数（供 platforms/youtube.py 调用） ──
+
+def download_youtube_video(video_id: str) -> Optional[str]:
+    """使用 yt-dlp 下载 YouTube 视频，返回文件路径"""
+    try:
+        output_path = VIDEO_DOWNLOAD_DIR / f"{video_id}.mp4"
+        if output_path.exists():
+            return str(output_path)
+
+        cmd = [
+            "yt-dlp",
+            "-f", "best[ext=mp4]",
+            "-o", str(output_path),
+            f"https://www.youtube.com/watch?v={video_id}",
+        ]
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
+        if result.returncode == 0 and output_path.exists():
+            return str(output_path)
+        return None
+    except Exception:
+        return None
+
+
+def parse_srt_to_outline(srt_content: str) -> List[Dict[str, str]]:
+    """解析 SRT 字幕，生成带时间戳的大纲"""
+    if not srt_content:
+        return []
+    outline = []
+    blocks = srt_content.strip().split("\n\n")
+    for block in blocks:
+        lines = block.strip().split("\n")
+        if len(lines) >= 3:
+            timestamp_line = lines[1]
+            if "-->" in timestamp_line:
+                start_time = timestamp_line.split("-->")[0].strip()
+                text = " ".join(lines[2:])
+                outline.append({"timestamp": start_time, "text": text})
+    return outline
+
+
+# ── @tool ──
+
+@tool(groups=["content"])
+async def extract_video_clip(
+    video_id: str,
+    start_time: str,
+    end_time: str,
+    output_name: Optional[str] = None,
+) -> ToolResult:
+    """
+    从已下载的 YouTube 视频中截取指定时间段的片段。
+
+    必须先通过 content_detail(platform="youtube", index=..., extras={"download_video": true})
+    下载视频后才能使用。
+
+    Args:
+        video_id: YouTube 视频 ID
+        start_time: 开始时间，格式 HH:MM:SS 或 MM:SS
+        end_time: 结束时间，格式 HH:MM:SS 或 MM:SS
+        output_name: 输出文件名（可选，自动生成）
+    """
+    source_video = VIDEO_DOWNLOAD_DIR / f"{video_id}.mp4"
+    if not source_video.exists():
+        return ToolResult(
+            title="视频截取失败",
+            output="",
+            error="源视频不存在，请先使用 content_detail(platform='youtube', ..., extras={'download_video': true}) 下载",
+        )
+
+    if not output_name:
+        output_name = f"{video_id}_clip_{start_time.replace(':', '-')}_{end_time.replace(':', '-')}.mp4"
+    output_path = VIDEO_DOWNLOAD_DIR / output_name
+
+    cmd = ["ffmpeg", "-i", str(source_video), "-ss", start_time, "-to", end_time, "-c", "copy", "-y", str(output_path)]
+
+    try:
+        result = await asyncio.to_thread(subprocess.run, cmd, capture_output=True, text=True, timeout=60)
+    except subprocess.TimeoutExpired:
+        return ToolResult(title="视频截取超时", output="", error="ffmpeg 超时（60秒）")
+
+    if result.returncode == 0 and output_path.exists():
+        file_size = output_path.stat().st_size / (1024 * 1024)
+        return ToolResult(
+            title=f"视频片段: {start_time} - {end_time}",
+            output=json.dumps({
+                "video_id": video_id,
+                "clip_path": str(output_path),
+                "start_time": start_time,
+                "end_time": end_time,
+                "file_size_mb": round(file_size, 2),
+            }, ensure_ascii=False, indent=2),
+            long_term_memory=f"Extracted clip from {video_id}: {start_time}-{end_time}",
+        )
+    return ToolResult(title="视频截取失败", output="", error=f"ffmpeg 执行失败: {result.stderr}")

agent/tools/builtin/content/platforms/__init__.py

@@ -0,0 +1 @@
+"""内容平台实现模块"""

agent/tools/builtin/content/platforms/aigc_channel.py

@@ -0,0 +1,237 @@
+"""
+AIGC-Channel 平台实现（9 个中文平台）
+
+后端：aigc-channel.aiddit.com
+平台：xhs / gzh / sph / github / toutiao / douyin / bili / zhihu / weibo
+"""
+
+import json
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from agent.tools.models import ToolResult
+from agent.tools.utils.image import build_image_grid, encode_base64, load_images
+from agent.tools.builtin.content.registry import (
+    PlatformDef, ParamSpec, register_platform,
+)
+
+BASE_URL = "http://aigc-channel.aiddit.com/aigc/channel"
+DEFAULT_TIMEOUT = 60.0
+
+
+# ── 平台注册 ──
+
+_XHS_SEARCH_PARAMS = {
+    "sort_type": ParamSpec(
+        values=["综合排序", "最新发布", "最多点赞"],
+        default="综合排序",
+    ),
+    "publish_time": ParamSpec(
+        values=["不限", "近1天", "近7天", "近30天"],
+        default="不限",
+    ),
+    "content_type": ParamSpec(
+        values=["不限", "图文", "视频", "文章"],
+        default="不限",
+    ),
+    "filter_note_range": ParamSpec(
+        values=["不限", "1分钟以内", "1-5分钟", "5分钟以上"],
+        default="不限",
+        note="仅视频内容生效",
+    ),
+}
+
+_COMMON_CONTENT_TYPE = {
+    "content_type": ParamSpec(
+        values=["视频", "图文"],
+        default="",
+        note="留空不限",
+    ),
+}
+
+# 9 个中文平台定义
+_AIGC_PLATFORMS = [
+    PlatformDef(id="xhs",     name="小红书",   aliases=["RED", "xiaohongshu"], search_params=_XHS_SEARCH_PARAMS, supports_suggest=True),
+    PlatformDef(id="gzh",     name="公众号",   aliases=["微信公众号", "wechat"], search_params=_COMMON_CONTENT_TYPE),
+    PlatformDef(id="sph",     name="视频号",   aliases=["微信视频号"], search_params=_COMMON_CONTENT_TYPE),
+    PlatformDef(id="github",  name="GitHub",   aliases=["gh"], search_params=_COMMON_CONTENT_TYPE),
+    PlatformDef(id="toutiao", name="头条",     aliases=["今日头条", "toutiao"], search_params=_COMMON_CONTENT_TYPE, supports_suggest=True),
+    PlatformDef(id="douyin",  name="抖音",     aliases=["TikTok"], search_params=_COMMON_CONTENT_TYPE, supports_suggest=True),
+    PlatformDef(id="bili",    name="B站",      aliases=["哔哩哔哩", "bilibili"], search_params=_COMMON_CONTENT_TYPE, supports_suggest=True),
+    PlatformDef(id="zhihu",   name="知乎",     aliases=[], search_params=_COMMON_CONTENT_TYPE, supports_suggest=True),
+    PlatformDef(id="weibo",   name="微博",     aliases=["sina"], search_params=_COMMON_CONTENT_TYPE),
+]
+
+# suggest API 额外支持 wx（微信搜一搜），但它不是搜索平台
+_SUGGEST_ONLY_CHANNELS = {"wx": "微信"}
+
+
+# ── 搜索实现 ──
+
+async def search(
+    platform_id: str,
+    keyword: str,
+    max_count: int = 20,
+    cursor: str = "",
+    extras: Optional[Dict[str, Any]] = None,
+) -> ToolResult:
+    """AIGC-Channel 统一搜索"""
+    extras = extras or {}
+
+    if platform_id == "xhs":
+        payload = {
+            "type": platform_id,
+            "keyword": keyword,
+            "cursor": cursor,
+            "content_type": extras.get("content_type", "不限"),
+            "sort_type": extras.get("sort_type", "综合排序"),
+            "publish_time": extras.get("publish_time", "不限"),
+            "filter_note_range": extras.get("filter_note_range", "不限"),
+        }
+    else:
+        payload = {
+            "type": platform_id,
+            "keyword": keyword,
+            "cursor": cursor or "0",
+            "max_count": max_count,
+            "content_type": extras.get("content_type", ""),
+        }
+
+    try:
+        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
+            response = await client.post(
+                f"{BASE_URL}/data",
+                json=payload,
+                headers={"Content-Type": "application/json"},
+            )
+            response.raise_for_status()
+            data = response.json()
+    except httpx.HTTPStatusError as e:
+        return ToolResult(title="搜索失败", output="", error=f"HTTP {e.response.status_code}: {e.response.text}")
+    except Exception as e:
+        return ToolResult(title="搜索失败", output="", error=str(e))
+
+    posts = data.get("data", [])
+
+    # 构建概览摘要
+    summary_list = []
+    for idx, post in enumerate(posts, 1):
+        body = post.get("body_text", "") or ""
+        title = post.get("title") or body[:20] or ""
+        summary_list.append({
+            "index": idx,
+            "title": title,
+            "body_text": body[:100] + ("..." if len(body) > 100 else ""),
+            "like_count": post.get("like_count"),
+            "comment_count": post.get("comment_count"),
+            "channel": post.get("channel"),
+            "link": post.get("link"),
+            "content_type": post.get("content_type"),
+        })
+
+    # 封面拼图
+    images = []
+    try:
+        collage_b64 = await _build_collage(posts)
+        if collage_b64:
+            images.append({"type": "base64", "media_type": "image/png", "data": collage_b64})
+    except Exception:
+        pass
+
+    return ToolResult(
+        title=f"搜索: {keyword} ({platform_id})",
+        output=json.dumps({"data": summary_list}, ensure_ascii=False, indent=2),
+        long_term_memory=f"Searched '{keyword}' on {platform_id}, {len(posts)} results. Use content_detail to view full details.",
+        images=images,
+        metadata={"posts": posts},  # 完整数据传给上层缓存
+    )
+
+
+# ── 详情实现（从缓存获取，不需要额外 HTTP） ──
+
+async def detail(post: Dict[str, Any], extras: Optional[Dict[str, Any]] = None) -> ToolResult:
+    """返回单条帖子的完整内容"""
+    title = post.get("title") or post.get("body_text", "")[:30] or "无标题"
+
+    images = []
+    for img_url in post.get("images", []):
+        if img_url:
+            images.append({"type": "url", "url": img_url})
+
+    return ToolResult(
+        title=f"详情: {title}",
+        output=json.dumps(post, ensure_ascii=False, indent=2),
+        long_term_memory=f"Viewed detail: {title}",
+        images=images,
+    )
+
+
+# ── 建议词实现 ──
+
+async def suggest(channel: str, keyword: str) -> ToolResult:
+    """获取搜索建议词"""
+    try:
+        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
+            response = await client.post(
+                f"{BASE_URL}/suggest",
+                json={"type": channel, "keyword": keyword},
+                headers={"Content-Type": "application/json"},
+            )
+            response.raise_for_status()
+            data = response.json()
+    except Exception as e:
+        return ToolResult(title="建议词获取失败", output="", error=str(e))
+
+    suggestion_count = sum(len(item.get("list", [])) for item in data.get("data", []))
+    return ToolResult(
+        title=f"建议词: {keyword} ({channel})",
+        output=json.dumps(data, ensure_ascii=False, indent=2),
+        long_term_memory=f"Got {suggestion_count} suggestions for '{keyword}' on {channel}",
+    )
+
+
+# ── 拼图辅助 ──
+
+async def _build_collage(posts: List[Dict[str, Any]]) -> Optional[str]:
+    """封面图网格拼图"""
+    urls, titles = [], []
+    for post in posts:
+        imgs = post.get("images", [])
+        if imgs and imgs[0]:
+            urls.append(imgs[0])
+            titles.append(post.get("title", "") or "")
+
+    if not urls:
+        return None
+
+    loaded = await load_images(urls)
+    valid_images, valid_labels = [], []
+    for (_, img), title in zip(loaded, titles):
+        if img is not None:
+            valid_images.append(img)
+            valid_labels.append(title)
+
+    if not valid_images:
+        return None
+
+    grid = build_image_grid(images=valid_images, labels=valid_labels)
+    b64, _ = encode_base64(grid, format="PNG")
+    return b64
+
+
+# ── 注册所有 AIGC 平台 ──
+
+def _register_all():
+    for p in _AIGC_PLATFORMS:
+        p.search_impl = search
+        p.detail_impl = detail
+        if p.supports_suggest:
+            p.suggest_impl = suggest
+            p.suggest_channels = [p.id]
+        register_platform(p)
+
+    # wx 只有 suggest，没有搜索
+    # suggest 调用时 channel 传 "wx"，但不注册为独立平台
+
+_register_all()

agent/tools/builtin/content/platforms/x.py

@@ -0,0 +1,129 @@
+"""
+X (Twitter) 平台实现
+
+后端：crawler.aiddit.com/crawler/x
+"""
+
+import json
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from agent.tools.models import ToolResult
+from agent.tools.utils.image import build_image_grid, encode_base64, load_images
+from agent.tools.builtin.content.registry import PlatformDef, register_platform
+
+CRAWLER_URL = "http://crawler.aiddit.com/crawler/x/keyword"
+DEFAULT_TIMEOUT = 60.0
+
+
+async def search(
+    platform_id: str,
+    keyword: str,
+    max_count: int = 20,
+    cursor: str = "",
+    extras: Optional[Dict[str, Any]] = None,
+) -> ToolResult:
+    try:
+        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
+            response = await client.post(CRAWLER_URL, json={"keyword": keyword})
+            response.raise_for_status()
+            data = response.json()
+
+        if data.get("code") != 0:
+            return ToolResult(title="X 搜索失败", output="", error=data.get("msg", "未知错误"))
+
+        result_data = data.get("data", {})
+        tweets = result_data.get("data", []) if isinstance(result_data, dict) else []
+
+        summary_list = []
+        for idx, tweet in enumerate(tweets[:max_count], 1):
+            text = tweet.get("body_text", "")
+            summary_list.append({
+                "index": idx,
+                "author": tweet.get("channel_account_name", ""),
+                "body_text": text[:100] + ("..." if len(text) > 100 else ""),
+                "like_count": tweet.get("like_count"),
+                "comment_count": tweet.get("comment_count"),
+            })
+
+        # 拼图
+        images = []
+        collage_b64 = await _build_tweet_collage(tweets[:max_count])
+        if collage_b64:
+            images.append({"type": "base64", "media_type": "image/png", "data": collage_b64})
+
+        return ToolResult(
+            title=f"X: {keyword}",
+            output=json.dumps({"data": summary_list}, ensure_ascii=False, indent=2),
+            long_term_memory=f"Searched X for '{keyword}', {len(tweets)} results.",
+            images=images,
+            metadata={"posts": tweets[:max_count]},
+        )
+
+    except Exception as e:
+        return ToolResult(title="X 搜索异常", output="", error=str(e))
+
+
+async def detail(post: Dict[str, Any], extras: Optional[Dict[str, Any]] = None) -> ToolResult:
+    """X 的详情直接从缓存的搜索结果取完整数据"""
+    author = post.get("channel_account_name", "")
+    text = post.get("body_text", "")[:30]
+
+    all_images = []
+    for img_item in post.get("image_url_list", []):
+        url = img_item.get("image_url") if isinstance(img_item, dict) else img_item
+        if url:
+            all_images.append({"type": "url", "url": url})
+
+    return ToolResult(
+        title=f"X 详情: @{author}",
+        output=json.dumps(post, ensure_ascii=False, indent=2),
+        long_term_memory=f"Viewed X post by @{author}: {text}",
+        images=all_images,
+    )
+
+
+async def _build_tweet_collage(tweets: List[Dict[str, Any]]) -> Optional[str]:
+    urls, titles = [], []
+    for tweet in tweets:
+        thumb = None
+        for img_item in tweet.get("image_url_list", []):
+            url = img_item.get("image_url") if isinstance(img_item, dict) else img_item
+            if url:
+                thumb = url
+                break
+        if not thumb:
+            thumb = tweet.get("cover_url")
+        if thumb:
+            urls.append(thumb)
+            titles.append(f"@{tweet.get('channel_account_name', '')}")
+
+    if not urls:
+        return None
+
+    loaded = await load_images(urls)
+    valid_images, valid_labels = [], []
+    for (_, img), title in zip(loaded, titles):
+        if img is not None:
+            valid_images.append(img)
+            valid_labels.append(title)
+
+    if not valid_images:
+        return None
+
+    grid = build_image_grid(images=valid_images, labels=valid_labels)
+    b64, _ = encode_base64(grid, format="PNG")
+    return b64
+
+
+# ── 注册 ──
+
+_X = PlatformDef(
+    id="x",
+    name="X (Twitter)",
+    aliases=["twitter", "推特"],
+)
+_X.search_impl = search
+_X.detail_impl = detail
+register_platform(_X)

agent/tools/builtin/content/platforms/youtube.py

@@ -0,0 +1,203 @@
+"""
+YouTube 平台实现
+
+后端：crawler.aiddit.com/crawler/youtube
+"""
+
+import json
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from agent.tools.models import ToolResult
+from agent.tools.utils.image import build_image_grid, encode_base64, load_images
+from agent.tools.builtin.content.registry import (
+    PlatformDef, ParamSpec, register_platform,
+)
+
+CRAWLER_BASE_URL = "http://crawler.aiddit.com/crawler"
+DEFAULT_TIMEOUT = 60.0
+
+
+# ── 搜索 ──
+
+async def search(
+    platform_id: str,
+    keyword: str,
+    max_count: int = 20,
+    cursor: str = "",
+    extras: Optional[Dict[str, Any]] = None,
+) -> ToolResult:
+    try:
+        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
+            response = await client.post(
+                f"{CRAWLER_BASE_URL}/youtube/keyword",
+                json={"keyword": keyword},
+            )
+            response.raise_for_status()
+            data = response.json()
+
+        if data.get("code") != 0:
+            return ToolResult(title="YouTube 搜索失败", output="", error=data.get("msg", "未知错误"))
+
+        result_data = data.get("data", {})
+        videos = result_data.get("data", []) if isinstance(result_data, dict) else []
+
+        # 概览
+        summary_list = []
+        for idx, video in enumerate(videos[:max_count], 1):
+            summary_list.append({
+                "index": idx,
+                "title": video.get("title", ""),
+                "author": video.get("author", ""),
+                "video_id": video.get("video_id", ""),
+            })
+
+        # 拼图
+        images = []
+        collage_b64 = await _build_video_collage(videos[:max_count])
+        if collage_b64:
+            images.append({"type": "base64", "media_type": "image/png", "data": collage_b64})
+
+        return ToolResult(
+            title=f"YouTube: {keyword}",
+            output=json.dumps({"data": summary_list}, ensure_ascii=False, indent=2),
+            long_term_memory=f"Searched YouTube for '{keyword}', {len(videos)} results.",
+            images=images,
+            metadata={"posts": videos[:max_count]},
+        )
+
+    except Exception as e:
+        return ToolResult(title="YouTube 搜索异常", output="", error=str(e))
+
+
+# ── 详情 ──
+
+async def detail(post: Dict[str, Any], extras: Optional[Dict[str, Any]] = None) -> ToolResult:
+    """
+    YouTube 详情：需要额外 HTTP 调用获取字幕/下载等。
+    post 来自搜索缓存，extras 支持 include_captions / download_video。
+    """
+    extras = extras or {}
+    content_id = post.get("video_id", "")
+    include_captions = extras.get("include_captions", True)
+    download_video = extras.get("download_video", False)
+
+    try:
+        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
+            resp = await client.post(
+                f"{CRAWLER_BASE_URL}/youtube/detail",
+                json={"content_id": content_id},
+            )
+            resp.raise_for_status()
+            detail_data = resp.json()
+
+        if detail_data.get("code") != 0:
+            return ToolResult(title="详情获取失败", output="", error=detail_data.get("msg", "未知错误"))
+
+        result_data = detail_data.get("data", {})
+        video_info = result_data.get("data", {}) if isinstance(result_data, dict) else {}
+
+        # 字幕
+        captions_text = None
+        if include_captions or download_video:
+            try:
+                async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
+                    cap_resp = await client.post(
+                        f"{CRAWLER_BASE_URL}/youtube/captions",
+                        json={"content_id": content_id},
+                    )
+                    cap_resp.raise_for_status()
+                    cap_data = cap_resp.json()
+                    if cap_data.get("code") == 0:
+                        inner = cap_data.get("data", {})
+                        if isinstance(inner, dict):
+                            inner2 = inner.get("data", {})
+                            if isinstance(inner2, dict):
+                                captions_text = inner2.get("content")
+            except Exception:
+                pass
+
+        # 下载
+        video_path = None
+        video_outline = None
+        if download_video:
+            import asyncio
+            from agent.tools.builtin.content.media import download_youtube_video, parse_srt_to_outline
+            video_path = await asyncio.to_thread(download_youtube_video, content_id)
+            if captions_text:
+                video_outline = parse_srt_to_outline(captions_text)
+
+        output_data = {
+            "video_id": content_id,
+            "title": video_info.get("title", ""),
+            "channel": video_info.get("channel_account_name", ""),
+            "description": video_info.get("body_text", ""),
+            "like_count": video_info.get("like_count"),
+            "comment_count": video_info.get("comment_count"),
+            "content_link": video_info.get("content_link", ""),
+            "captions": captions_text,
+        }
+        if download_video:
+            output_data["video_path"] = video_path
+            output_data["video_outline"] = video_outline
+
+        return ToolResult(
+            title=f"YouTube 详情: {video_info.get('title', content_id)}",
+            output=json.dumps(output_data, ensure_ascii=False, indent=2),
+            long_term_memory=f"YouTube detail for {content_id}" + (" with captions" if captions_text else ""),
+        )
+
+    except Exception as e:
+        return ToolResult(title="YouTube 详情异常", output="", error=str(e))
+
+
+# ── 拼图 ──
+
+async def _build_video_collage(videos: List[Dict[str, Any]]) -> Optional[str]:
+    urls, titles = [], []
+    for video in videos:
+        thumb = None
+        if "thumbnails" in video and isinstance(video["thumbnails"], list) and video["thumbnails"]:
+            thumb = video["thumbnails"][0].get("url")
+        elif "thumbnail" in video:
+            thumb = video.get("thumbnail")
+        elif "cover_url" in video:
+            thumb = video.get("cover_url")
+
+        if thumb:
+            urls.append(thumb)
+            titles.append(video.get("title", ""))
+
+    if not urls:
+        return None
+
+    loaded = await load_images(urls)
+    valid_images, valid_labels = [], []
+    for (_, img), title in zip(loaded, titles):
+        if img is not None:
+            valid_images.append(img)
+            valid_labels.append(title)
+
+    if not valid_images:
+        return None
+
+    grid = build_image_grid(images=valid_images, labels=valid_labels)
+    b64, _ = encode_base64(grid, format="PNG")
+    return b64
+
+
+# ── 注册 ──
+
+_YOUTUBE = PlatformDef(
+    id="youtube",
+    name="YouTube",
+    aliases=["yt", "油管"],
+    detail_extras={
+        "include_captions": ParamSpec(note="是否获取字幕，默认 True"),
+        "download_video": ParamSpec(note="是否下载视频到本地，默认 False"),
+    },
+)
+_YOUTUBE.search_impl = search
+_YOUTUBE.detail_impl = detail
+register_platform(_YOUTUBE)

agent/tools/builtin/content/registry.py

@@ -0,0 +1,125 @@
+"""
+内容平台注册表
+
+定义所有支持的内容平台及其搜索参数 schema。
+供 content_platforms / content_search / content_detail 路由使用。
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Coroutine, Dict, List, Optional
+
+from agent.tools.models import ToolResult
+
+
+# ── 类型定义 ──
+
+@dataclass
+class ParamSpec:
+    """平台专属参数的描述"""
+    values: Optional[List[str]] = None   # 枚举值（None 表示自由文本）
+    default: Optional[str] = None
+    note: str = ""                       # 额外说明
+
+    def to_dict(self) -> dict:
+        d: dict = {}
+        if self.values is not None:
+            d["values"] = self.values
+            d["default"] = self.default
+        if self.note:
+            d["note"] = self.note
+        return d
+
+
+# 平台实现函数的签名
+SearchFunc = Callable[..., Coroutine[Any, Any, ToolResult]]
+DetailFunc = Callable[..., Coroutine[Any, Any, ToolResult]]
+SuggestFunc = Callable[..., Coroutine[Any, Any, ToolResult]]
+
+
+@dataclass
+class PlatformDef:
+    """一个内容平台的完整定义"""
+    id: str                                         # 唯一标识，如 "xhs"
+    name: str                                       # 显示名，如 "小红书"
+    aliases: List[str] = field(default_factory=list) # 模糊匹配别名，如 ["小红书", "RED"]
+    search_params: Dict[str, ParamSpec] = field(default_factory=dict)
+    detail_extras: Dict[str, ParamSpec] = field(default_factory=dict)
+    supports_suggest: bool = False
+    suggest_channels: Optional[List[str]] = None     # suggest API 的 channel 值（可能与 id 不同）
+
+    # 平台实现函数（运行时由 platforms/ 模块设置）
+    search_impl: Optional[SearchFunc] = None
+    detail_impl: Optional[DetailFunc] = None
+    suggest_impl: Optional[SuggestFunc] = None
+
+    def summary(self) -> dict:
+        """概要信息（不含参数细节）"""
+        d = {"id": self.id, "name": self.name}
+        if self.search_params:
+            d["has_search_params"] = True
+        if self.detail_extras:
+            d["has_detail_extras"] = True
+        if self.supports_suggest:
+            d["supports_suggest"] = True
+        return d
+
+    def detail(self) -> dict:
+        """完整参数说明"""
+        d = self.summary()
+        if self.search_params:
+            d["search_params"] = {k: v.to_dict() for k, v in self.search_params.items()}
+        if self.detail_extras:
+            d["detail_extras"] = {k: v.to_dict() for k, v in self.detail_extras.items()}
+        return d
+
+
+# ── 平台注册表 ──
+
+_PLATFORMS: Dict[str, PlatformDef] = {}
+
+
+def register_platform(p: PlatformDef) -> None:
+    _PLATFORMS[p.id] = p
+
+
+def get_platform(platform_id: str) -> Optional[PlatformDef]:
+    return _PLATFORMS.get(platform_id)
+
+
+def all_platforms() -> List[PlatformDef]:
+    return list(_PLATFORMS.values())
+
+
+def match_platforms(query: str) -> List[PlatformDef]:
+    """
+    模糊匹配平台：精确 ID > 别名包含 > token 交集。
+    空 query 返回全部。
+    """
+    if not query:
+        return all_platforms()
+
+    q = query.strip().lower()
+
+    # 1) 精确 ID 匹配
+    if q in _PLATFORMS:
+        return [_PLATFORMS[q]]
+
+    # 2) 别名 / 名称包含匹配
+    alias_hits = [
+        p for p in _PLATFORMS.values()
+        if q in p.name.lower() or any(q in a.lower() for a in p.aliases)
+    ]
+    if alias_hits:
+        return alias_hits
+
+    # 3) token 交集（把 query 拆成字符/词，看命中率）
+    q_tokens = set(q.replace("_", " ").replace("-", " ").split())
+    scored = []
+    for p in _PLATFORMS.values():
+        pool = {p.id, p.name.lower()} | {a.lower() for a in p.aliases}
+        pool_text = " ".join(pool)
+        hits = sum(1 for t in q_tokens if t in pool_text)
+        if hits > 0:
+            scored.append((hits, p))
+    scored.sort(key=lambda x: -x[0])
+    return [p for _, p in scored]

agent/tools/builtin/content/tools.py

@@ -0,0 +1,266 @@
+"""
+内容工具族 —— 统一入口
+
+4 个 @tool 注册给 LLM：
+  - content_platforms: 列出/查询平台及其参数
+  - content_search:    跨平台搜索
+  - content_detail:    查看详情
+  - content_suggest:   搜索建议词
+
+所有平台的具体实现在 platforms/ 子目录，按模块自注册到 registry。
+"""
+
+import json
+import os
+import uuid
+from typing import Any, Dict, Optional
+
+from agent.tools import tool, ToolResult, ToolContext
+from agent.tools.builtin.content.registry import (
+    all_platforms, get_platform, match_platforms,
+)
+from agent.tools.builtin.content import cache as _cache
+
+# 导入平台模块以触发自注册（副作用导入）
+import agent.tools.builtin.content.platforms.aigc_channel  # noqa: F401
+import agent.tools.builtin.content.platforms.youtube       # noqa: F401
+import agent.tools.builtin.content.platforms.x             # noqa: F401
+
+
+def _get_trace_id(context: Optional[ToolContext]) -> str:
+    """从 context 取 trace_id，回退到环境变量或自动生成"""
+    if context and hasattr(context, "trace_id") and context.trace_id:
+        return context.trace_id
+    return os.getenv("TRACE_ID") or f"anon-{uuid.uuid4().hex[:8]}"
+
+
+# ── content_platforms ──
+
+@tool(hidden_params=["context"], groups=["content"])
+async def content_platforms(
+    platform: str = "",
+    context: Optional[ToolContext] = None,
+) -> ToolResult:
+    """
+    列出支持的内容平台及其搜索参数。
+
+    不传 platform 时返回所有平台的概要列表（仅名称和 ID）。
+    传入 platform 时模糊匹配并返回匹配平台的详细参数说明（支持 ID、中文名、别名）。
+
+    建议在不熟悉平台参数时先调用此工具查看，再构造 content_search / content_detail 的参数。
+
+    Args:
+        platform: 可选，平台名称或关键词。支持模糊匹配（如 "xhs"、"小红书"、"youtube"）。
+                  留空返回全部平台概要。
+        context: 工具上下文（自动注入）
+    """
+    hits = match_platforms(platform)
+
+    if not hits:
+        all_ids = [p.id for p in all_platforms()]
+        return ToolResult(
+            title="未找到匹配平台",
+            output=f"没有匹配 '{platform}' 的平台。可用平台: {', '.join(all_ids)}",
+        )
+
+    if platform:
+        # 有 query：返回匹配平台的详细参数
+        result = [p.detail() for p in hits]
+    else:
+        # 无 query：返回概要列表
+        result = [p.summary() for p in hits]
+
+    return ToolResult(
+        title=f"内容平台" + (f" ({platform})" if platform else ""),
+        output=json.dumps(result, ensure_ascii=False, indent=2),
+    )
+
+
+# ── content_search ──
+
+@tool(hidden_params=["context"], groups=["content"])
+async def content_search(
+    platform: str,
+    keyword: str,
+    max_count: int = 20,
+    cursor: str = "",
+    extras: Optional[Dict[str, Any]] = None,
+    context: Optional[ToolContext] = None,
+) -> ToolResult:
+    """
+    跨平台内容搜索，返回带索引编号的封面拼图 + 概览列表。
+
+    返回的是摘要信息（标题 + 正文截断 + 互动数据），不含完整正文和所有图片。
+    如需查看某条内容的完整信息，请使用 content_detail。
+
+    Args:
+        platform: 平台标识，如 'xhs'、'youtube'、'x'。完整列表见 content_platforms。
+        keyword: 搜索关键词。
+        max_count: 返回条数上限，默认 20。
+        cursor: 分页游标，首次搜索留空，翻页时传入上次返回值。
+        extras: 平台专用参数（dict）。不同平台支持不同参数，
+                如 xhs 支持 sort_type / publish_time / content_type / filter_note_range。
+                不清楚可先调 content_platforms(platform) 查看。
+        context: 工具上下文（自动注入）
+    """
+    pdef = get_platform(platform)
+    if not pdef:
+        # 尝试模糊匹配
+        hits = match_platforms(platform)
+        if hits:
+            suggestions = ", ".join(f"{p.id}({p.name})" for p in hits[:3])
+            return ToolResult(title="平台不存在", output=f"未找到平台 '{platform}'。你是否想要: {suggestions}")
+        all_ids = [p.id for p in all_platforms()]
+        return ToolResult(title="平台不存在", output=f"未找到平台 '{platform}'。可用: {', '.join(all_ids)}")
+
+    if not pdef.search_impl:
+        return ToolResult(title="不支持搜索", output=f"平台 {pdef.name} 暂不支持搜索")
+
+    result = await pdef.search_impl(
+        platform_id=pdef.id,
+        keyword=keyword,
+        max_count=max_count,
+        cursor=cursor,
+        extras=extras,
+    )
+
+    # 持久化搜索结果到磁盘缓存
+    if not result.error:
+        posts = result.metadata.pop("posts", [])
+        trace_id = _get_trace_id(context)
+        _cache.save_search_results(trace_id, pdef.id, keyword, posts)
+
+    return result
+
+
+# ── content_detail ──
+
+@tool(hidden_params=["context"], groups=["content"])
+async def content_detail(
+    platform: str,
+    index: int,
+    extras: Optional[Dict[str, Any]] = None,
+    context: Optional[ToolContext] = None,
+) -> ToolResult:
+    """
+    查看内容详情。从最近一次 content_search 的结果中按索引取完整记录。
+
+    Args:
+        platform: 平台标识（必须和之前 content_search 用的一致）。
+        index: 内容序号（1-based），来自 content_search 返回的 index 字段。
+        extras: 平台专用详情参数。YouTube 支持 include_captions / download_video。
+                其他平台通常不需要。
+        context: 工具上下文（自动注入）
+    """
+    pdef = get_platform(platform)
+    if not pdef:
+        return ToolResult(title="平台不存在", output=f"未找到平台 '{platform}'")
+
+    trace_id = _get_trace_id(context)
+    post = _cache.get_cached_post(trace_id, pdef.id, index)
+
+    if not post:
+        info = _cache.get_cached_search_info(trace_id, pdef.id)
+        if info:
+            return ToolResult(
+                title="索引无效",
+                output=f"平台 {pdef.name} 上次搜索 '{info['keyword']}' 共 {info['total']} 条，"
+                       f"有效索引 1-{info['total']}，你传入了 {index}。",
+                error="Invalid index",
+            )
+        return ToolResult(
+            title="缓存未命中",
+            output=f"没有 {pdef.name} 的搜索缓存。请先调用 content_search(platform='{pdef.id}', keyword=...) 搜索。",
+            error="No cache",
+        )
+
+    if pdef.detail_impl:
+        return await pdef.detail_impl(post, extras)
+
+    # fallback：直接返回缓存的完整数据
+    return ToolResult(
+        title=f"详情 #{index}",
+        output=json.dumps(post, ensure_ascii=False, indent=2),
+    )
+
+
+# ── content_suggest ──
+
+@tool(hidden_params=["context"], groups=["content"])
+async def content_suggest(
+    platform: str,
+    keyword: str,
+    context: Optional[ToolContext] = None,
+) -> ToolResult:
+    """
+    获取搜索关键词补全建议。
+
+    仅部分平台支持（xhs、toutiao、douyin、bili、zhihu）。
+    用于辅助用户发现更精准的搜索词。
+
+    Args:
+        platform: 平台标识。
+        keyword: 搜索关键词（输入中的部分词即可）。
+        context: 工具上下文（自动注入）
+    """
+    pdef = get_platform(platform)
+    if not pdef:
+        return ToolResult(title="平台不存在", output=f"未找到平台 '{platform}'")
+
+    if not pdef.suggest_impl:
+        supported = [p.id for p in all_platforms() if p.supports_suggest]
+        return ToolResult(
+            title="不支持建议词",
+            output=f"平台 {pdef.name} 不支持建议词。支持的平台: {', '.join(supported)}",
+        )
+
+    channel = (pdef.suggest_channels or [pdef.id])[0]
+    return await pdef.suggest_impl(channel, keyword)
+
+
+# ── CLI 入口 ──
+
+def _parse_args(argv: list) -> dict:
+    """解析 --key=value 格式的 CLI 参数"""
+    kwargs = {}
+    for arg in argv:
+        if arg.startswith("--") and "=" in arg:
+            key, val = arg[2:].split("=", 1)
+            # 尝试 JSON 解析（dict / int / bool）
+            try:
+                val = json.loads(val)
+            except (json.JSONDecodeError, ValueError):
+                pass
+            kwargs[key] = val
+    return kwargs
+
+
+if __name__ == "__main__":
+    import sys
+    import asyncio
+
+    COMMANDS = {
+        "platforms": content_platforms,
+        "search": content_search,
+        "detail": content_detail,
+        "suggest": content_suggest,
+    }
+
+    if len(sys.argv) < 2 or sys.argv[1] not in COMMANDS:
+        print(f"Usage: python {sys.argv[0]} <{'|'.join(COMMANDS)}> [--key=value ...]")
+        sys.exit(1)
+
+    cmd = sys.argv[1]
+    kwargs = _parse_args(sys.argv[2:])
+
+    # trace_id：CLI 参数 > 环境变量 > 自动生成
+    trace_id = kwargs.pop("trace_id", None) or os.getenv("TRACE_ID") or f"cli-{uuid.uuid4().hex[:8]}"
+    os.environ["TRACE_ID"] = trace_id
+
+    result = asyncio.run(COMMANDS[cmd](**kwargs))
+
+    # 输出 JSON（与 toolhub CLI 格式一致）
+    out = {"trace_id": trace_id, "output": result.output, "error": result.error}
+    if result.metadata:
+        out["metadata"] = result.metadata
+    print(json.dumps(out, ensure_ascii=False, indent=2))

agent/tools/builtin/context.py

@@ -14,7 +14,8 @@ from agent.tools import tool, ToolResult, ToolContext
 
 @tool(
     description="获取当前执行上下文，包括计划状态、焦点提醒、协作者信息等。当你感到困惑或需要回顾当前任务状态时调用。",
-    hidden_params=["context"]
+    hidden_params=["context"],
+    groups=["core"],
 )
 async def get_current_context(
     context: ToolContext,

agent/tools/builtin/crawler.py

@@ -1,497 +0,0 @@
-"""
-爬虫服务工具模块
-
-提供 YouTube、X (Twitter) 和微信/通用链接的搜索和详情查询功能。
-"""
-
-import json
-import os
-import subprocess
-import tempfile
-from pathlib import Path
-from typing import Optional, List, Dict, Any
-
-import httpx
-
-from agent.tools import tool, ToolResult
-from agent.tools.utils.image import build_image_grid, encode_base64, load_images
-
-
-# API 配置
-CRAWLER_BASE_URL = "http://crawler.aiddit.com/crawler"
-AIGC_BASE_URL = "http://aigc-channel.aiddit.com/aigc/channel"
-DEFAULT_TIMEOUT = 60.0
-
-# 视频处理相关配置
-VIDEO_DOWNLOAD_DIR = Path(tempfile.gettempdir()) / "youtube_videos"
-VIDEO_DOWNLOAD_DIR.mkdir(exist_ok=True)
-
-
-async def _build_video_collage(videos: List[Dict[str, Any]]) -> Optional[str]:
-    """
-    将视频缩略图+序号+标题拼接成网格图，返回 base64 编码的 PNG。
-    复用 agent.tools.utils.image 中的共享拼图逻辑。
-    """
-    if not videos:
-        return None
-
-    urls: List[str] = []
-    titles: List[str] = []
-    for video in videos:
-        thumbnail = None
-        if "thumbnails" in video and isinstance(video["thumbnails"], list) and video["thumbnails"]:
-            thumbnail = video["thumbnails"][0].get("url")
-        elif "thumbnail" in video:
-            thumbnail = video.get("thumbnail")
-        elif "cover_url" in video:
-            thumbnail = video.get("cover_url")
-
-        title = video.get("title", "") or video.get("text", "")
-        if thumbnail:
-            urls.append(thumbnail)
-            titles.append(title)
-
-    if not urls:
-        return None
-
-    loaded = await load_images(urls)
-
-    valid_images = []
-    valid_labels = []
-    for (_, img), title in zip(loaded, titles):
-        if img is not None:
-            valid_images.append(img)
-            valid_labels.append(title)
-
-    if not valid_images:
-        return None
-
-    grid = build_image_grid(images=valid_images, labels=valid_labels)
-    b64, _ = encode_base64(grid, format="PNG")
-    return b64
-
-
-def _parse_srt_to_outline(srt_content: str) -> List[Dict[str, str]]:
-    """解析 SRT 字幕，生成带时间戳的大纲"""
-    if not srt_content:
-        return []
-
-    outline = []
-    blocks = srt_content.strip().split('\n\n')
-    for block in blocks:
-        lines = block.strip().split('\n')
-        if len(lines) >= 3:
-            timestamp_line = lines[1]
-            if '-->' in timestamp_line:
-                start_time = timestamp_line.split('-->')[0].strip()
-                text = ' '.join(lines[2:])
-                outline.append({'timestamp': start_time, 'text': text})
-    return outline
-
-
-def _download_youtube_video(video_id: str) -> Optional[str]:
-    """使用 yt-dlp 下载 YouTube 视频，返回文件路径"""
-    try:
-        output_path = VIDEO_DOWNLOAD_DIR / f"{video_id}.mp4"
-        if output_path.exists():
-            return str(output_path)
-
-        cmd = [
-            'yt-dlp',
-            '-f', 'best[ext=mp4]',
-            '-o', str(output_path),
-            f'https://www.youtube.com/watch?v={video_id}'
-        ]
-        result = subprocess.run(cmd, capture_output=True, text=True, timeout=300)
-
-        if result.returncode == 0 and output_path.exists():
-            return str(output_path)
-        return None
-    except Exception:
-        return None
-
-
-# ── YouTube 工具 ──
-
-@tool()
-async def youtube_search(keyword: str) -> ToolResult:
-    """
-    搜索 YouTube 视频
-
-    Args:
-        keyword: 搜索关键词
-
-    Returns:
-        搜索结果列表，包含视频标题、ID、频道等信息
-    """
-    try:
-        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
-            response = await client.post(
-                f"{CRAWLER_BASE_URL}/youtube/keyword",
-                json={"keyword": keyword}
-            )
-            response.raise_for_status()
-            data = response.json()
-
-            if data.get("code") == 0:
-                result_data = data.get("data", {})
-                videos = result_data.get("data", []) if isinstance(result_data, dict) else []
-
-                images = []
-                collage_b64 = await _build_video_collage(videos)
-                if collage_b64:
-                    images.append({
-                        "type": "base64",
-                        "media_type": "image/png",
-                        "data": collage_b64
-                    })
-
-                summary_list = []
-                for idx, video in enumerate(videos[:20], 1):
-                    title = video.get("title", "")
-                    author = video.get("author", "")
-                    video_id = video.get("video_id", "")
-                    summary_list.append(f"{idx}. {title} - {author} (ID: {video_id})")
-
-                output_data = {
-                    "keyword": keyword,
-                    "total": len(videos),
-                    "summary": summary_list,
-                    "data": videos
-                }
-
-                return ToolResult(
-                    title=f"YouTube 搜索: {keyword}",
-                    output=json.dumps(output_data, ensure_ascii=False, indent=2),
-                    long_term_memory=f"Searched YouTube for '{keyword}', found {len(videos)} videos",
-                    images=images
-                )
-            else:
-                return ToolResult(
-                    title="YouTube 搜索失败",
-                    output="",
-                    error=f"搜索失败: {data.get('msg', '未知错误')}"
-                )
-
-    except Exception as e:
-        return ToolResult(
-            title="YouTube 搜索异常",
-            output="",
-            error=str(e)
-        )
-
-
-@tool()
-async def youtube_detail(
-    content_id: str,
-    include_captions: bool = True,
-    download_video: bool = False
-) -> ToolResult:
-    """
-    获取 YouTube 视频详情（可选包含字幕、下载视频并生成大纲）
-
-    Args:
-        content_id: 视频 ID
-        include_captions: 是否包含字幕，默认 True
-        download_video: 是否下载视频并生成带时间戳的大纲，默认 False。
-            下载后可使用 extract_video_clip 截取视频片段观看。
-
-    Returns:
-        视频详细信息，包含字幕、视频大纲和本地文件路径
-    """
-    try:
-        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
-            detail_response = await client.post(
-                f"{CRAWLER_BASE_URL}/youtube/detail",
-                json={"content_id": content_id}
-            )
-            detail_response.raise_for_status()
-            detail_data = detail_response.json()
-
-            if detail_data.get("code") != 0:
-                return ToolResult(
-                    title="获取详情失败",
-                    output="",
-                    error=f"获取详情失败: {detail_data.get('msg', '未知错误')}"
-                )
-
-            result_data = detail_data.get("data", {})
-            video_info = result_data.get("data", {}) if isinstance(result_data, dict) else {}
-
-            # 获取字幕
-            captions_text = None
-            if include_captions or download_video:
-                try:
-                    captions_response = await client.post(
-                        f"{CRAWLER_BASE_URL}/youtube/captions",
-                        json={"content_id": content_id}
-                    )
-                    captions_response.raise_for_status()
-                    captions_data = captions_response.json()
-
-                    if captions_data.get("code") == 0:
-                        captions_result = captions_data.get("data", {})
-                        if isinstance(captions_result, dict):
-                            inner_data = captions_result.get("data", {})
-                            if isinstance(inner_data, dict):
-                                captions_text = inner_data.get("content")
-                except Exception:
-                    pass
-
-            # 下载视频并生成大纲
-            video_path = None
-            video_outline = None
-            if download_video:
-                video_path = await asyncio.to_thread(_download_youtube_video, content_id)
-                if captions_text:
-                    video_outline = _parse_srt_to_outline(captions_text)
-
-            # 合并数据
-            output_data = {
-                "video_id": content_id,
-                "title": video_info.get("title", ""),
-                "channel": video_info.get("channel_account_name", ""),
-                "description": video_info.get("body_text", ""),
-                "like_count": video_info.get("like_count"),
-                "comment_count": video_info.get("comment_count"),
-                "publish_timestamp": video_info.get("publish_timestamp"),
-                "content_link": video_info.get("content_link", ""),
-                "captions": captions_text,
-                "full_data": video_info
-            }
-
-            if download_video:
-                output_data["video_path"] = video_path
-                output_data["video_outline"] = video_outline
-                if not video_path:
-                    output_data["download_error"] = "视频下载失败，请检查 yt-dlp 是否可用"
-
-            memory = f"Retrieved YouTube video details for {content_id}"
-            if captions_text:
-                memory += " with captions"
-            if video_path:
-                memory += f", downloaded to {video_path}"
-
-            return ToolResult(
-                title=f"YouTube 视频详情: {content_id}",
-                output=json.dumps(output_data, ensure_ascii=False, indent=2),
-                long_term_memory=memory
-            )
-
-    except Exception as e:
-        return ToolResult(
-            title="YouTube 详情查询异常",
-            output="",
-            error=str(e)
-        )
-
-
-# ── X (Twitter) 工具 ──
-
-@tool()
-async def x_search(keyword: str) -> ToolResult:
-    """
-    搜索 X (Twitter) 内容（数据已结构化，无需访问详情页）
-
-    Args:
-        keyword: 搜索关键词
-
-    Returns:
-        搜索结果列表，包含推文内容、作者、互动数据等
-    """
-    try:
-        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
-            response = await client.post(
-                "http://crawler.aiddit.com/crawler/x/keyword",
-                json={"keyword": keyword}
-            )
-            response.raise_for_status()
-            data = response.json()
-
-            if data.get("code") == 0:
-                result_data = data.get("data", {})
-                tweets = result_data.get("data", []) if isinstance(result_data, dict) else []
-
-                # 构建拼接图
-                images = []
-                tweets_with_images = []
-                for tweet in tweets:
-                    image_list = tweet.get("image_url_list", [])
-                    if image_list:
-                        tweet["thumbnails"] = [{"url": image_list[0].get("image_url")}]
-                        tweets_with_images.append(tweet)
-
-                collage_b64 = await _build_video_collage(tweets_with_images if tweets_with_images else tweets)
-                if collage_b64:
-                    images.append({
-                        "type": "base64",
-                        "media_type": "image/png",
-                        "data": collage_b64
-                    })
-
-                summary_list = []
-                for idx, tweet in enumerate(tweets[:20], 1):
-                    text = tweet.get("body_text", "")[:100]
-                    author = tweet.get("channel_account_name", "")
-                    summary_list.append(f"{idx}. @{author}: {text}")
-
-                output_data = {
-                    "keyword": keyword,
-                    "total": len(tweets),
-                    "summary": summary_list,
-                    "data": tweets
-                }
-
-                return ToolResult(
-                    title=f"X 搜索: {keyword}",
-                    output=json.dumps(output_data, ensure_ascii=False, indent=2),
-                    long_term_memory=f"Searched X (Twitter) for '{keyword}', found {len(tweets)} tweets",
-                    images=images
-                )
-            else:
-                return ToolResult(
-                    title="X 搜索失败",
-                    output="",
-                    error=f"搜索失败: {data.get('msg', '未知错误')}"
-                )
-
-    except Exception as e:
-        return ToolResult(
-            title="X 搜索异常",
-            output="",
-            error=str(e)
-        )
-
-
-# ── 内容导入工具 ──
-
-@tool()
-async def import_content(plan_name: str, content_data: List[Dict[str, Any]]) -> ToolResult:
-    """
-    导入长文内容（微信公众号、小红书、抖音等通用链接）
-
-    Args:
-        plan_name: 计划名称
-        content_data: 内容数据列表，每项包含 channel、content_link、title 等字段
-
-    Returns:
-        导入结果，包含 plan_id
-    """
-    try:
-        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
-            response = await client.post(
-                f"{AIGC_BASE_URL}/weixin/auto_insert",
-                json={"plan_name": plan_name, "data": content_data}
-            )
-            response.raise_for_status()
-            data = response.json()
-
-            if data.get("code") == 0:
-                result_data = data.get("data", {})
-                return ToolResult(
-                    title=f"内容导入: {plan_name}",
-                    output=json.dumps(result_data, ensure_ascii=False, indent=2),
-                    long_term_memory=f"Imported {len(content_data)} items to plan '{plan_name}'"
-                )
-            else:
-                return ToolResult(
-                    title="导入失败",
-                    output="",
-                    error=f"导入失败: {data.get('msg', '未知错误')}"
-                )
-
-    except Exception as e:
-        return ToolResult(
-            title="内容导入异常",
-            output="",
-            error=str(e)
-        )
-
-
-# ── 视频截取工具 ──
-
-@tool()
-async def extract_video_clip(
-    video_id: str,
-    start_time: str,
-    end_time: str,
-    output_name: Optional[str] = None
-) -> ToolResult:
-    """
-    从已下载的 YouTube 视频中截取指定时间段的片段
-
-    Args:
-        video_id: YouTube 视频 ID（必须先通过 youtube_detail(download_video=True) 下载）
-        start_time: 开始时间，格式: HH:MM:SS 或 MM:SS
-        end_time: 结束时间，格式: HH:MM:SS 或 MM:SS
-        output_name: 输出文件名（可选）
-
-    Returns:
-        截取的视频片段路径
-
-    Example:
-        extract_video_clip("dQw4w9WgXcQ", "00:00:10", "00:00:30")
-    """
-    try:
-        source_video = VIDEO_DOWNLOAD_DIR / f"{video_id}.mp4"
-        if not source_video.exists():
-            return ToolResult(
-                title="视频截取失败",
-                output="",
-                error="源视频不存在，请先使用 youtube_detail(download_video=True) 下载视频"
-            )
-
-        if not output_name:
-            output_name = f"{video_id}_clip_{start_time.replace(':', '-')}_{end_time.replace(':', '-')}.mp4"
-
-        output_path = VIDEO_DOWNLOAD_DIR / output_name
-
-        cmd = [
-            'ffmpeg',
-            '-i', str(source_video),
-            '-ss', start_time,
-            '-to', end_time,
-            '-c', 'copy',
-            '-y',
-            str(output_path)
-        ]
-
-        result = await asyncio.to_thread(
-            subprocess.run, cmd, capture_output=True, text=True, timeout=60
-        )
-
-        if result.returncode == 0 and output_path.exists():
-            file_size = output_path.stat().st_size / (1024 * 1024)
-
-            output_data = {
-                "video_id": video_id,
-                "clip_path": str(output_path),
-                "start_time": start_time,
-                "end_time": end_time,
-                "file_size_mb": round(file_size, 2)
-            }
-
-            return ToolResult(
-                title=f"视频片段截取成功: {start_time} - {end_time}",
-                output=json.dumps(output_data, ensure_ascii=False, indent=2),
-                long_term_memory=f"Extracted video clip from {video_id}: {start_time} to {end_time}"
-            )
-        else:
-            return ToolResult(
-                title="视频截取失败",
-                output="",
-                error=f"ffmpeg 执行失败: {result.stderr}"
-            )
-
-    except subprocess.TimeoutExpired:
-        return ToolResult(
-            title="视频截取超时",
-            output="",
-            error="视频截取超时（60秒）"
-        )
-    except Exception as e:
-        return ToolResult(
-            title="视频截取异常",
-            output="",
-            error=str(e)
-        )

agent/tools/builtin/feishu/chat.py

@@ -133,6 +133,7 @@ def update_unread_count(contact_name: str, increment: int = 1, reset: bool = Fal
 
 @tool(
     hidden_params=["context"],
+    groups=["feishu"],
     display={
         "zh": {
             "name": "获取飞书联系人列表",
@@ -160,6 +161,7 @@ async def feishu_get_contact_list(context: Optional[ToolContext] = None) -> Tool
 
 @tool(
     hidden_params=["context"],
+    groups=["feishu"],
     display={
         "zh": {
             "name": "给飞书联系人发送消息",
@@ -293,6 +295,7 @@ async def feishu_send_message_to_contact(
 
 @tool(
     hidden_params=["context"],
+    groups=["feishu"],
     display={
         "zh": {
             "name": "获取飞书联系人回复",
@@ -409,6 +412,7 @@ def _convert_feishu_msg_to_openai_content(client: FeishuClient, msg: Dict[str, A
 
 @tool(
     hidden_params=["context"],
+    groups=["feishu"],
     display={
         "zh": {
             "name": "获取飞书聊天历史记录",

agent/tools/builtin/file/edit.py

@@ -17,7 +17,7 @@ import re
 from agent.tools import tool, ToolResult, ToolContext
 
 
-@tool(description="编辑文件，使用精确字符串替换。支持多种智能匹配策略。", hidden_params=["context"])
+@tool(description="编辑文件，使用精确字符串替换。支持多种智能匹配策略。", hidden_params=["context"], groups=["core"])
 async def edit_file(
     file_path: str,
     old_string: str,

agent/tools/builtin/file/grep.py

@@ -21,7 +21,7 @@ LIMIT = 100  # 最大返回匹配数（参考 opencode grep.ts:107）
 MAX_LINE_LENGTH = 2000  # 最大行长度（参考 opencode grep.ts:10）
 
 
-@tool(description="在文件内容中搜索模式", hidden_params=["context"])
+@tool(description="在文件内容中搜索模式", hidden_params=["context"], groups=["core"])
 async def grep_content(
     pattern: str,
     path: Optional[str] = None,

agent/tools/builtin/file/read.py

@@ -27,7 +27,7 @@ MAX_LINE_LENGTH = 2000
 MAX_BYTES = 50 * 1024  # 50KB
 
 
-@tool(description="读取单个文件内容，支持文本文件、图片、PDF 等多种格式，也支持 HTTP/HTTPS URL", hidden_params=["context"])
+@tool(description="读取单个文件内容，支持文本文件、图片、PDF 等多种格式，也支持 HTTP/HTTPS URL", hidden_params=["context"], groups=["core"])
 async def read_file(
     file_path: str,
     offset: int = 0,

agent/tools/builtin/file/read_images.py

@@ -71,6 +71,7 @@ def _adaptive_layout(count: int) -> Tuple[int, int]:
             },
         },
     },
+    groups=["core"],
 )
 async def read_images(
     paths: List[str],

agent/tools/builtin/file/write.py

@@ -16,7 +16,7 @@ import difflib
 from agent.tools import tool, ToolResult, ToolContext
 
 
-@tool(description="写入文件内容（创建新文件、覆盖现有文件或追加内容）", hidden_params=["context"])
+@tool(description="写入文件内容（创建新文件、覆盖现有文件或追加内容）", hidden_params=["context"], groups=["core"])
 async def write_file(
     file_path: str,
     content: str,

agent/tools/builtin/glob_tool.py

@@ -19,7 +19,7 @@ from agent.tools import tool, ToolResult, ToolContext
 LIMIT = 100  # 最大返回数量（参考 opencode glob.ts:35）
 
 
-@tool(description="使用 glob 模式匹配文件", hidden_params=["context"])
+@tool(description="使用 glob 模式匹配文件", hidden_params=["context"], groups=["core"])
 async def glob_files(
     pattern: str,
     path: Optional[str] = None,

agent/tools/builtin/im/chat.py

@@ -43,6 +43,7 @@ class _ToolNotifier(AgentNotifier):
 
 @tool(
     hidden_params=["context"],
+    groups=["im"],
     display={
         "zh": {"name": "初始化 IM 连接", "params": {"contact_id": "你的身份 ID", "server_url": "服务器地址"}},
         "en": {"name": "Setup IM Connection", "params": {"contact_id": "Your identity ID", "server_url": "Server URL"}},
@@ -80,6 +81,7 @@ async def im_setup(
 
 @tool(
     hidden_params=["context"],
+    groups=["im"],
     display={
         "zh": {"name": "打开 IM 窗口", "params": {"contact_id": "Agent ID", "chat_id": "窗口 ID"}},
         "en": {"name": "Open IM Window", "params": {"contact_id": "Agent ID", "chat_id": "Window ID"}},
@@ -109,6 +111,7 @@ async def im_open_window(
 
 @tool(
     hidden_params=["context"],
+    groups=["im"],
     display={
         "zh": {"name": "关闭 IM 窗口", "params": {"contact_id": "Agent ID", "chat_id": "窗口 ID"}},
         "en": {"name": "Close IM Window", "params": {"contact_id": "Agent ID", "chat_id": "Window ID"}},
@@ -138,6 +141,7 @@ async def im_close_window(
 
 @tool(
     hidden_params=["context"],
+    groups=["im"],
     display={
         "zh": {"name": "检查 IM 新消息通知", "params": {"contact_id": "Agent ID", "chat_id": "窗口 ID"}},
         "en": {"name": "Check IM Notifications", "params": {"contact_id": "Agent ID", "chat_id": "Window ID"}},
@@ -169,6 +173,7 @@ async def im_check_notification(
 
 @tool(
     hidden_params=["context"],
+    groups=["im"],
     display={
         "zh": {"name": "接收 IM 消息", "params": {"contact_id": "Agent ID", "chat_id": "窗口 ID"}},
         "en": {"name": "Receive IM Messages", "params": {"contact_id": "Agent ID", "chat_id": "Window ID"}},
@@ -213,6 +218,7 @@ async def im_receive_messages(
 
 @tool(
     hidden_params=["context"],
+    groups=["im"],
     display={
         "zh": {"name": "发送 IM 消息", "params": {"contact_id": "Agent ID", "chat_id": "窗口 ID", "receiver": "接收者 ID", "content": "消息内容"}},
         "en": {"name": "Send IM Message", "params": {"contact_id": "Agent ID", "chat_id": "Window ID", "receiver": "Receiver ID", "content": "Message content"}},
@@ -253,6 +259,7 @@ async def im_send_message(
 
 @tool(
     hidden_params=["context"],
+    groups=["im"],
     display={
         "zh": {"name": "查询 IM 联系人", "params": {"contact_id": "Agent ID", "server_http_url": "服务器 HTTP 地址"}},
         "en": {"name": "Get IM Contacts", "params": {"contact_id": "Agent ID", "server_http_url": "Server HTTP URL"}},
@@ -297,6 +304,7 @@ async def im_get_contacts(
 
 @tool(
     hidden_params=["context"],
+    groups=["im"],
     display={
         "zh": {"name": "查询 IM 聊天历史", "params": {"contact_id": "Agent ID", "chat_id": "窗口 ID", "peer_id": "联系人 ID", "limit": "最大条数"}},
         "en": {"name": "Get IM Chat History", "params": {"contact_id": "Agent ID", "chat_id": "Window ID", "peer_id": "Contact ID", "limit": "Max records"}},

agent/tools/builtin/knowledge.py

@@ -84,13 +84,7 @@ class KnowledgeConfig:
         return owner
 
 
-@tool(
-    hidden_params=["context"],
-    inject_params={
-        "types": {"mode": "default", "key": "knowledge_config.default_search_types"},
-        "owner": {"mode": "default", "key": "knowledge_config.default_search_owner"},
-    }
-)
+@tool(groups=["knowledge_internal"], hidden_params=["context"])
 async def knowledge_search(
     query: str,
     top_k: int = 5,
@@ -181,14 +175,7 @@ async def knowledge_search(
         )
 
 
-@tool(
-    hidden_params=["context", "owner"],
-    inject_params={
-        "owner": {"mode": "default", "key": "knowledge_config.resolved_owner"},
-        "tags": {"mode": "merge", "key": "knowledge_config.default_tags"},
-        "scopes": {"mode": "merge", "key": "knowledge_config.default_scopes"},
-    }
-)
+@tool(groups=["knowledge_internal"], hidden_params=["context"])
 async def knowledge_save(
     task: str,
     content: str,
@@ -283,7 +270,7 @@ async def knowledge_save(
         )
 
 
-@tool(hidden_params=["context"])
+@tool(groups=["knowledge_internal"], hidden_params=["context"])
 async def knowledge_update(
     knowledge_id: str,
     add_helpful_case: Optional[Dict] = None,
@@ -353,7 +340,7 @@ async def knowledge_update(
         )
 
 
-@tool(hidden_params=["context"])
+@tool(groups=["knowledge_internal"], hidden_params=["context"])
 async def knowledge_batch_update(
     feedback_list: List[Dict[str, Any]],
     context: Optional[ToolContext] = None,
@@ -403,7 +390,7 @@ async def knowledge_batch_update(
         )
 
 
-@tool(hidden_params=["context"])
+@tool(groups=["knowledge_internal"], hidden_params=["context"])
 async def knowledge_list(
     limit: int = 10,
     types: Optional[List[str]] = None,
@@ -477,7 +464,7 @@ async def knowledge_list(
         )
 
 
-@tool(hidden_params=["context"])
+@tool(groups=["knowledge_internal"], hidden_params=["context"])
 async def knowledge_slim(
     model: str = "google/gemini-2.0-flash-001",
     context: Optional[ToolContext] = None,
@@ -523,7 +510,7 @@ async def knowledge_slim(
 
 # ==================== Resource 资源管理工具 ====================
 
-@tool(hidden_params=["context"])
+@tool(groups=["knowledge_internal"], hidden_params=["context"])
 async def resource_save(
     resource_id: str,
     title: str,
@@ -582,7 +569,7 @@ async def resource_save(
         )
 
 
-@tool(hidden_params=["context"])
+@tool(groups=["knowledge_internal"], hidden_params=["context"])
 async def resource_get(
     resource_id: str,
     org_key: Optional[str] = None,
@@ -637,7 +624,7 @@ async def resource_get(
 
 # ==================== Tool 表查询工具 ====================
 
-@tool(hidden_params=["context"])
+@tool(groups=["knowledge_internal"], hidden_params=["context"])
 async def tool_search(
     query: str,
     top_k: int = 5,
@@ -662,7 +649,7 @@ async def tool_search(
         return ToolResult(title="❌ 工具检索失败", output=str(e), error=str(e))
 
 
-@tool(hidden_params=["context"])
+@tool(groups=["knowledge_internal"], hidden_params=["context"])
 async def tool_list(
     limit: int = 20,
     offset: int = 0,
@@ -684,7 +671,7 @@ async def tool_list(
 
 # ==================== Capability (原子能力) 表查询工具 ====================
 
-@tool(hidden_params=["context"])
+@tool(groups=["knowledge_internal"], hidden_params=["context"])
 async def capability_search(
     query: str,
     top_k: int = 5,
@@ -706,7 +693,7 @@ async def capability_search(
         return ToolResult(title="❌ 原子能力检索失败", output=str(e), error=str(e))
 
 
-@tool(hidden_params=["context"])
+@tool(groups=["knowledge_internal"], hidden_params=["context"])
 async def capability_list(
     limit: int = 20,
     offset: int = 0,
@@ -726,7 +713,7 @@ async def capability_list(
 
 # ==================== Requirement (需求) 表查询工具 ====================
 
-@tool(hidden_params=["context"])
+@tool(groups=["knowledge_internal"], hidden_params=["context"])
 async def requirement_search(
     query: str,
     top_k: int = 5,
@@ -744,7 +731,7 @@ async def requirement_search(
         return ToolResult(title="❌ 需求检索失败", output=str(e), error=str(e))
 
 
-@tool(hidden_params=["context"])
+@tool(groups=["knowledge_internal"], hidden_params=["context"])
 async def requirement_list(
     limit: int = 20,
     offset: int = 0,

agent/tools/builtin/librarian.py

@@ -24,7 +24,8 @@ KNOWHUB_API = os.getenv("KNOWHUB_API", "http://localhost:9999").rstrip("/")
     hidden_params=["context"],
     inject_params={
         "trace_id": {"mode": "default", "key": "trace_id"},
-    }
+    },
+    groups=["knowledge"],
 )
 async def ask_knowledge(
     query: str,
@@ -107,7 +108,8 @@ async def ask_knowledge(
     hidden_params=["context"],
     inject_params={
         "trace_id": {"mode": "default", "key": "trace_id"},
-    }
+    },
+    groups=["knowledge"],
 )
 async def upload_knowledge(
     data: Dict[str, Any],

agent/tools/builtin/resource.py

@@ -10,8 +10,9 @@ from agent.tools import tool, ToolResult
 KNOWHUB_API = os.getenv("KNOWHUB_API", "http://43.106.118.91:9999").rstrip("/")
 
 
-@tool(    
-    description="列出知识库中的所有工具资源"
+@tool(
+    description="列出知识库中的所有工具资源",
+    groups=["resource"],
 )
 def resource_list_tools(
     category: Optional[str] = None,
@@ -49,6 +50,7 @@ def resource_list_tools(
 
 @tool(
     description="获取指定工具的详细信息",
+    groups=["resource"],
 )
 def resource_get_tool(tool_id: str) -> ToolResult:
     """获取工具详情

agent/tools/builtin/search.py

@@ -1,420 +0,0 @@
-"""
-搜索工具模块
-
-提供帖子搜索、帖子详情查看和建议词搜索功能，支持多个渠道平台。
-
-主要功能：
-1. search_posts - 帖子搜索（浏览模式：封面图+标题+内容截断）
-2. select_post - 帖子详情（从搜索结果中选取单个帖子的完整内容）
-3. get_search_suggestions - 获取平台的搜索补全建议词
-"""
-
-import json
-from enum import Enum
-from typing import Any, Dict, List, Optional
-
-import httpx
-
-from agent.tools import tool, ToolResult
-from agent.tools.utils.image import build_image_grid, encode_base64, load_images
-
-
-# API 基础配置
-BASE_URL = "http://aigc-channel.aiddit.com/aigc/channel"
-DEFAULT_TIMEOUT = 60.0
-
-# 搜索结果缓存，以序号为 key
-_search_cache: Dict[int, Dict[str, Any]] = {}
-
-
-async def _build_collage(posts: List[Dict[str, Any]]) -> Optional[str]:
-    """
-    将帖子封面图+序号+标题拼接成网格图，返回 base64 编码的 PNG。
-    复用 agent.tools.utils.image 中的共享拼图逻辑。
-    """
-    if not posts:
-        return None
-
-    # 收集有封面图的帖子
-    urls: List[str] = []
-    titles: List[str] = []
-    for post in posts:
-        imgs = post.get("images", [])
-        cover_url = imgs[0] if imgs else None
-        if cover_url:
-            urls.append(cover_url)
-            titles.append(post.get("title", "") or "")
-
-    if not urls:
-        return None
-
-    # 并发加载图片
-    loaded = await load_images(urls)
-
-    # 过滤加载失败的（保持 url 和 title 对齐）
-    valid_images = []
-    valid_labels = []
-    for (_, img), title in zip(loaded, titles):
-        if img is not None:
-            valid_images.append(img)
-            valid_labels.append(title)
-
-    if not valid_images:
-        return None
-
-    grid = build_image_grid(images=valid_images, labels=valid_labels)
-    b64, _ = encode_base64(grid, format="PNG")
-    return b64
-
-
-class PostSearchChannel(str, Enum):
-    """
-    帖子搜索支持的渠道类型
-    """
-    XHS = "xhs"           # 小红书
-    GZH = "gzh"           # 公众号
-    SPH = "sph"           # 视频号
-    GITHUB = "github"     # GitHub
-    TOUTIAO = "toutiao"   # 头条
-    DOUYIN = "douyin"     # 抖音
-    BILI = "bili"         # B站
-    ZHIHU = "zhihu"       # 知乎
-    WEIBO = "weibo"       # 微博
-
-
-class SuggestSearchChannel(str, Enum):
-    """
-    建议词搜索支持的渠道类型
-    """
-    XHS = "xhs"           # 小红书
-    WX = "wx"             # 微信
-    GITHUB = "github"     # GitHub
-    TOUTIAO = "toutiao"   # 头条
-    DOUYIN = "douyin"     # 抖音
-    BILI = "bili"         # B站
-    ZHIHU = "zhihu"       # 知乎
-
-
-@tool(
-    display={
-        "zh": {
-            "name": "帖子搜索",
-            "params": {
-                "keyword": "搜索关键词",
-                "channel": "搜索渠道（xhs=小红书, gzh=公众号, sph=视频号, github, toutiao=头条, douyin=抖音, bili=B站, zhihu=知乎, weibo=微博）",
-                "cursor": "分页游标",
-                "max_count": "返回条数",
-                "content_type": "内容类型-视频/图文",
-                "sort_type": "排序方式（xhs专用）",
-                "publish_time": "发布时间筛选（xhs专用）",
-                "filter_note_range": "笔记时长筛选（xhs专用）"
-            }
-        },
-        "en": {
-            "name": "Search Posts",
-            "params": {
-                "keyword": "Search keyword",
-                "channel": "Search channel (xhs=XiaoHongShu, gzh=WeChat Official Account, sph=WeChat Channels, github, toutiao, douyin, bili, zhihu, weibo)",
-                "cursor": "Pagination cursor",
-                "max_count": "Max results",
-                "content_type": "content type-视频/图文",
-                "sort_type": "Sort type (xhs only)",
-                "publish_time": "Publish time filter (xhs only)",
-                "filter_note_range": "Note duration filter (xhs only)"
-            }
-        }
-    }
-)
-async def search_posts(
-    keyword: str,
-    channel: str = "xhs",
-    cursor: str = "",
-    max_count: int = 20,
-    content_type: str = "",
-    sort_type: str = "综合排序",
-    publish_time: str = "不限",
-    filter_note_range: str = "不限"
-) -> ToolResult:
-    """
-    帖子搜索（浏览模式）
-
-    根据关键词在指定渠道平台搜索帖子，返回封面图+标题+内容摘要，用于快速浏览。
-    如需查看某个帖子的完整内容，请使用 select_post 工具。
-
-    Args:
-        keyword: 搜索关键词
-        channel: 搜索渠道，支持的渠道有：
-            - xhs: 小红书
-            - gzh: 公众号
-            - sph: 视频号
-            - github: GitHub
-            - toutiao: 头条
-            - douyin: 抖音
-            - bili: B站
-            - zhihu: 知乎
-            - weibo: 微博
-        cursor: 分页游标，首次请求为空字符串，后续使用上次返回的 cursor
-        max_count: 返回的最大条数，默认为 20
-        content_type: 内容类型筛选，默认不限；
-            xhs 可选值：'不限' | '图文' | '视频' | '文章'；
-            其他渠道可选值：'视频' | '图文'
-        sort_type: 排序方式（仅 xhs 有效），可选值：'综合排序' | '最新发布' | '最多点赞'，默认'综合排序'
-        publish_time: 发布时间筛选（仅 xhs 有效），可选值：'不限' | '近30天' | '近7天' | '近1天'，默认'不限'
-        filter_note_range: 笔记时长筛选，视频内容有效（仅 xhs 有效），可选值：'不限' | '1分钟以内' | '1-5分钟' | '5分钟以上'，默认'不限'
-
-    Returns:
-        ToolResult 包含搜索结果摘要列表（封面图+标题+内容截断），
-        可通过 channel_content_id 调用 select_post 查看完整内容。
-    """
-    global _search_cache
-    try:
-        channel_value = channel.value if isinstance(channel, PostSearchChannel) else channel
-
-        url = f"{BASE_URL}/data"
-        if channel_value == "xhs":
-            payload = {
-                "type": channel_value,
-                "keyword": keyword,
-                "cursor": cursor,
-                "content_type": content_type if content_type else "不限",
-                "sort_type": sort_type,
-                "publish_time": publish_time,
-                "filter_note_range": filter_note_range,
-            }
-        else:
-            payload = {
-                "type": channel_value,
-                "keyword": keyword,
-                "cursor": cursor if cursor else "0",
-                "max_count": max_count,
-                "content_type": content_type,
-            }
-
-        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
-            response = await client.post(
-                url,
-                json=payload,
-                headers={"Content-Type": "application/json"},
-            )
-            response.raise_for_status()
-            data = response.json()
-
-        posts = data.get("data", [])
-
-        # 缓存完整结果（以序号为 key）
-        _search_cache.clear()
-        for idx, post in enumerate(posts):
-            _search_cache[idx + 1] = post
-
-        # 构建摘要列表（带序号）
-        summary_list = []
-        for idx, post in enumerate(posts):
-            body = post.get("body_text", "") or ""
-            title = post.get("title") or body[:20] or ""
-            summary_list.append({
-                "index": idx + 1,
-                "channel_content_id": post.get("channel_content_id"),
-                "title": title,
-                "body_text": body[:100] + ("..." if len(body) > 100 else ""),
-                "like_count": post.get("like_count"),
-                "collect_count": post.get("collect_count"),
-                "comment_count": post.get("comment_count"),
-                "channel": post.get("channel"),
-                "link": post.get("link"),
-                "content_type": post.get("content_type"),
-                "publish_timestamp": post.get("publish_timestamp"),
-            })
-
-        # 拼接封面图网格
-        images = []
-        try:
-            collage_b64 = await _build_collage(posts)
-            if collage_b64:
-                images.append({
-                    "type": "base64",
-                    "media_type": "image/png",
-                    "data": collage_b64
-                })
-        except Exception as collage_error:
-            # 图片拼接失败不影响主流程，记录错误但继续返回结果
-            import logging
-            logging.warning(f"Failed to build collage for {channel_value}: {collage_error}")
-
-        output_data = {
-            "code": data.get("code"),
-            "message": data.get("message"),
-            "data": summary_list
-        }
-
-        return ToolResult(
-            title=f"搜索结果: {keyword} ({channel_value})",
-            output=json.dumps(output_data, ensure_ascii=False, indent=2),
-            long_term_memory=f"Searched '{keyword}' on {channel_value}, found {len(posts)} posts. Use select_post(index) to view full details of a specific post.",
-            images=images
-        )
-    except httpx.HTTPStatusError as e:
-        return ToolResult(
-            title="搜索失败",
-            output="",
-            error=f"HTTP error {e.response.status_code}: {e.response.text}"
-        )
-    except Exception as e:
-        return ToolResult(
-            title="搜索失败",
-            output="",
-            error=str(e)
-        )
-
-
-@tool(
-    display={
-        "zh": {
-            "name": "帖子详情",
-            "params": {
-                "index": "帖子序号"
-            }
-        },
-        "en": {
-            "name": "Select Post",
-            "params": {
-                "index": "Post index"
-            }
-        }
-    }
-)
-async def select_post(
-    index: int,
-) -> ToolResult:
-    """
-    查看帖子详情
-
-    从最近一次 search_posts 的搜索结果中，根据序号选取指定帖子并返回完整内容（全部正文、全部图片、视频等）。
-    需要先调用 search_posts 进行搜索。
-
-    Args:
-        index: 帖子序号，来自 search_posts 返回结果中的 index 字段（从 1 开始）
-
-    Returns:
-        ToolResult 包含该帖子的完整信息和所有图片。
-    """
-    post = _search_cache.get(index)
-    if not post:
-        return ToolResult(
-            title="未找到帖子",
-            output="",
-            error=f"未找到序号 {index} 的帖子，请先调用 search_posts 搜索。"
-        )
-
-    # 返回所有图片
-    images = []
-    for img_url in post.get("images", []):
-        if img_url:
-            images.append({
-                "type": "url",
-                "url": img_url
-            })
-
-    return ToolResult(
-        title=f"帖子详情 #{index}: {post.get('title', '')}",
-        output=json.dumps(post, ensure_ascii=False, indent=2),
-        long_term_memory=f"Viewed post detail #{index}: {post.get('title', '')}",
-        images=images
-    )
-
-
-@tool(
-    display={
-        "zh": {
-            "name": "获取搜索关键词补全建议",
-            "params": {
-                "keyword": "搜索关键词",
-                "channel": "搜索渠道"
-            }
-        },
-        "en": {
-            "name": "Get Search Suggestions",
-            "params": {
-                "keyword": "Search keyword",
-                "channel": "Search channel"
-            }
-        }
-    }
-)
-async def get_search_suggestions(
-    keyword: str,
-    channel: str = "xhs",
-) -> ToolResult:
-    """
-    获取搜索关键词补全建议
-
-    根据关键词在指定渠道平台获取搜索建议词。
-
-    Args:
-        keyword: 搜索关键词
-        channel: 搜索渠道，支持的渠道有：
-            - xhs: 小红书
-            - wx: 微信
-            - github: GitHub
-            - toutiao: 头条
-            - douyin: 抖音
-            - bili: B站
-            - zhihu: 知乎
-
-    Returns:
-        ToolResult 包含建议词数据：
-        {
-            "code": 0,                    # 状态码，0 表示成功
-            "message": "success",         # 状态消息
-            "data": [                     # 建议词数据
-                {
-                    "type": "xhs",        # 渠道类型
-                    "list": [             # 建议词列表
-                        {
-                            "name": "彩虹染发"  # 建议词
-                        }
-                    ]
-                }
-            ]
-        }
-    """
-    try:
-        # 处理 channel 参数，支持枚举和字符串
-        channel_value = channel.value if isinstance(channel, SuggestSearchChannel) else channel
-
-        url = f"{BASE_URL}/suggest"
-        payload = {
-            "type": channel_value,
-            "keyword": keyword,
-        }
-
-        async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT) as client:
-            response = await client.post(
-                url,
-                json=payload,
-                headers={"Content-Type": "application/json"},
-            )
-            response.raise_for_status()
-            data = response.json()
-
-        # 计算建议词数量
-        suggestion_count = 0
-        for item in data.get("data", []):
-            suggestion_count += len(item.get("list", []))
-
-        return ToolResult(
-            title=f"建议词: {keyword} ({channel_value})",
-            output=json.dumps(data, ensure_ascii=False, indent=2),
-            long_term_memory=f"Got {suggestion_count} suggestions for '{keyword}' on {channel_value}"
-        )
-    except httpx.HTTPStatusError as e:
-        return ToolResult(
-            title="获取建议词失败",
-            output="",
-            error=f"HTTP error {e.response.status_code}: {e.response.text}"
-        )
-    except Exception as e:
-        return ToolResult(
-            title="获取建议词失败",
-            output="",
-            error=str(e)
-        )

agent/tools/builtin/skill.py

@@ -66,7 +66,8 @@ def _check_skill_setup(skill_name: str) -> Optional[str]:
 
 
 @tool(
-    description="加载指定的 skill 文档。Skills 提供领域知识和最佳实践指导。"
+    description="加载指定的 skill 文档。Skills 提供领域知识和最佳实践指导。",
+    groups=["core"],
 )
 async def skill(
     skill_name: str,
@@ -181,7 +182,8 @@ async def skill(
 
 
 @tool(
-    description="列出所有可用的 skills"
+    description="列出所有可用的 skills",
+    groups=["core"],
 )
 async def list_skills(
     skills_dir: Optional[str] = None,

agent/tools/builtin/subagent.py

@@ -610,7 +610,7 @@ async def _run_agents(
 
 # ===== 工具定义 =====
 
-@tool(description="创建 Agent 执行任务", hidden_params=["context"])
+@tool(description="创建 Agent 执行任务", hidden_params=["context"], groups=["core"])
 async def agent(
     task: Union[str, List[str]],
     messages: Optional[Union[Messages, List[Messages]]] = None,
@@ -677,7 +677,7 @@ async def agent(
     )
 
 
-@tool(description="评估目标执行结果是否满足要求", hidden_params=["context"])
+@tool(description="评估目标执行结果是否满足要求", hidden_params=["context"], groups=["core"])
 async def evaluate(
     messages: Optional[Messages] = None,
     target_goal_id: Optional[str] = None,

agent/tools/builtin/toolhub.py

@@ -250,7 +250,8 @@ async def _preprocess_params(params: Dict[str, Any]) -> Dict[str, Any]:
     display={
         "zh": {"name": "ToolHub 健康检查", "params": {}},
         "en": {"name": "ToolHub Health Check", "params": {}},
-    }
+    },
+    groups=["toolhub"],
 )
 async def toolhub_health() -> ToolResult:
     """检查 ToolHub 远程工具库服务是否可用
@@ -291,7 +292,8 @@ async def toolhub_health() -> ToolResult:
     display={
         "zh": {"name": "搜索 ToolHub 工具", "params": {"keyword": "搜索关键词"}},
         "en": {"name": "Search ToolHub", "params": {"keyword": "Search keyword"}},
-    }
+    },
+    groups=["toolhub"],
 )
 async def toolhub_search(keyword: Optional[str] = None) -> ToolResult:
     """搜索 ToolHub 远程工具库中可用的工具
@@ -456,7 +458,8 @@ async def toolhub_search(keyword: Optional[str] = None) -> ToolResult:
             "name": "Call ToolHub Tool",
             "params": {"tool_id": "Tool ID", "params": "Tool parameters"},
         },
-    }
+    },
+    groups=["toolhub"],
 )
 async def toolhub_call(
     tool_id: str,

agent/tools/registry.py

@@ -68,7 +68,8 @@ class ToolRegistry:
 		display: Optional[Dict[str, Dict[str, Any]]] = None,
 		url_patterns: Optional[List[str]] = None,
 		hidden_params: Optional[List[str]] = None,
-		inject_params: Optional[Dict[str, Any]] = None
+		inject_params: Optional[Dict[str, Any]] = None,
+		groups: Optional[List[str]] = None,
 	):
 		"""
 		注册工具
@@ -82,6 +83,7 @@ class ToolRegistry:
 			url_patterns: URL 模式列表（如 ["*.google.com"]，None = 无限制）
 			hidden_params: 隐藏参数列表（不生成 schema，LLM 看不到）
 			inject_params: 注入参数规则 {param_name: injector_func}
+			groups: 工具分组标签（如 ["core"]、["browser"]），用于 RunConfig.tool_groups 过滤
 		"""
 		func_name = func.__name__
 
@@ -100,6 +102,7 @@ class ToolRegistry:
 			"url_patterns": url_patterns,
 			"hidden_params": hidden_params or [],
 			"inject_params": inject_params or {},
+			"groups": groups or [],
 			"ui_metadata": {
 				"requires_confirmation": requires_confirmation,
 				"editable_params": editable_params or [],
@@ -166,27 +169,45 @@ class ToolRegistry:
 
 		return schemas
 
-	def get_tool_names(self, current_url: Optional[str] = None) -> List[str]:
+	def get_tool_names(self, current_url: Optional[str] = None, groups: Optional[List[str]] = None) -> List[str]:
 		"""
-		获取工具名称列表（可选 URL 过滤）
+		获取工具名称列表（可选 URL 过滤 + group 过滤）
 
 		Args:
-			current_url: 当前 URL（None = 返回所有工具）
+			current_url: 当前 URL（None = 不过滤 URL）
+			groups: 工具分组白名单（None = 不过滤 group，返回所有工具）
 
 		Returns:
 			工具名称列表
 		"""
+		# 1. group 过滤
+		if groups is not None:
+			group_set = set(groups)
+			candidates = {
+				name for name, tool in self._tools.items()
+				if group_set & set(tool.get("groups", []))
+			}
+		else:
+			candidates = set(self._tools.keys())
+
+		# 2. URL 过滤
 		if current_url is None:
-			return list(self._tools.keys())
+			return list(candidates)
 
-		# 过滤工具
 		tool_items = [
-			{"name": name, "url_patterns": tool["url_patterns"]}
-			for name, tool in self._tools.items()
+			{"name": name, "url_patterns": self._tools[name]["url_patterns"]}
+			for name in candidates
 		]
 		filtered = filter_by_url(tool_items, current_url, url_field="url_patterns")
 		return [item["name"] for item in filtered]
 
+	def get_available_groups(self) -> List[str]:
+		"""获取所有已注册的工具分组"""
+		groups = set()
+		for tool in self._tools.values():
+			groups.update(tool.get("groups", []))
+		return sorted(groups)
+
 	def get_schemas_for_url(self, current_url: Optional[str] = None) -> List[Dict]:
 		"""
 		根据当前 URL 获取匹配的工具 Schema
@@ -484,7 +505,8 @@ def tool(
 	display: Optional[Dict[str, Dict[str, Any]]] = None,
 	url_patterns: Optional[List[str]] = None,
 	hidden_params: Optional[List[str]] = None,
-	inject_params: Optional[Dict[str, Any]] = None
+	inject_params: Optional[Dict[str, Any]] = None,
+	groups: Optional[List[str]] = None,
 ):
 	"""
 	工具装饰器 - 自动注册工具并生成 Schema
@@ -498,6 +520,7 @@ def tool(
 		url_patterns: URL 模式列表（如 ["*.google.com"]，None = 无限制）
 		hidden_params: 隐藏参数列表（不生成 schema，LLM 看不到）
 		inject_params: 注入参数规则 {param_name: injector_func}
+		groups: 工具分组标签（如 ["core"]、["browser"]），用于 RunConfig.tool_groups 过滤
 
 	Example:
 		@tool(
@@ -531,7 +554,8 @@ def tool(
 			display=display,
 			url_patterns=url_patterns,
 			hidden_params=hidden_params,
-			inject_params=inject_params
+			inject_params=inject_params,
+			groups=groups,
 		)
 		return func
 

agent/tools/utils/image.py

@@ -1,8 +1,8 @@
 """
 图片处理共享工具
 
-提供批量读图、降采样、网格拼图等通用逻辑。供 read_images、search_posts、
-youtube_search 等工具共享，避免代码重复。
+提供批量读图、降采样、网格拼图等通用逻辑。供 read_images、content 工具族
+等共享，避免代码重复。
 
 核心函数：
 - load_image: 从本地路径或 URL 加载为 PIL Image

agent/trace/goal_tool.py

@@ -103,7 +103,7 @@ async def inject_knowledge_for_goal(
 
 # ===== LLM 可调用的 goal 工具 =====
 
-@tool(description="管理执行计划，添加/完成/放弃目标，切换焦点", hidden_params=["context"])
+@tool(description="管理执行计划，添加/完成/放弃目标，切换焦点", hidden_params=["context"], groups=["core"])
 async def goal(
     add: Optional[str] = None,
     reason: Optional[str] = None,

direct_insert.py

@@ -1,80 +0,0 @@
-#!/usr/bin/env python3
-"""
-直接插入知识到数据库的脚本
-"""
-import sys
-import os
-import uuid
-import time
-import asyncio
-from datetime import datetime, timezone
-
-sys.path.insert(0, '/root/Agent')
-
-# 设置环境变量
-os.environ['KNOWHUB_DB'] = 'gp-t4n72471pkmt4b9q7o-master.gpdbmaster.singapore.rds.aliyuncs.com'
-os.environ['KNOWHUB_PORT'] = '5432'
-os.environ['KNOWHUB_USER'] = 'aiddit_aigc'
-os.environ['KNOWHUB_PASSWORD'] = '%a&&yqNxg^V1$toJ*WOa^-b^X=QJ'
-os.environ['KNOWHUB_DB_NAME'] = 'knowhub'
-
-from knowhub.knowhub_db.pg_store import PostgreSQLStore
-from knowhub.embeddings import get_embedding
-
-# 测试知识数据
-knowledge_data = {
-    'task': '接口测试验证条目',
-    'content': '这是一条用于验证 upload 接口是否可用的测试知识，可以删除。',
-    'types': ['experience'],
-    'tags': {'source': 'api_test'},
-    'score': 1
-}
-
-async def main():
-    print('正在连接数据库...')
-    store = PostgreSQLStore()
-
-    # 生成 ID
-    now = datetime.now(timezone.utc)
-    knowledge_id = f'knowledge-{now.strftime("%Y%m%d")}-{uuid.uuid4().hex[:8]}'
-    message_id = f'msg-{uuid.uuid4().hex[:12]}'
-
-    # 生成 embedding
-    print('正在生成 embedding...')
-    task_embedding = await get_embedding(knowledge_data['task'])
-    content_embedding = await get_embedding(knowledge_data['content'])
-
-    # 构建知识记录
-    knowledge = {
-        'id': knowledge_id,
-        'message_id': message_id,
-        'task': knowledge_data['task'],
-        'content': knowledge_data['content'],
-        'types': knowledge_data['types'],
-        'tags': knowledge_data.get('tags', {}),
-        'tag_keys': list(knowledge_data.get('tags', {}).keys()),
-        'scopes': ['org:cybertogether'],
-        'owner': 'system',
-        'source': {'category': 'execution'},
-        'eval': {'score': knowledge_data.get('score', 3)},
-        'task_embedding': task_embedding,
-        'content_embedding': content_embedding,
-        'created_at': int(time.time()),
-        'updated_at': int(time.time()),
-        'status': 'approved',
-    }
-
-    print(f'正在插入知识条目...')
-    store.insert(knowledge)
-    store.close()
-
-    print(f'✅ 成功插入知识条目！')
-    print(f'  ID: {knowledge_id}')
-    print(f'  Task: {knowledge_data["task"]}')
-    print(f'  Types: {knowledge_data["types"]}')
-    
-    return knowledge_id
-
-if __name__ == '__main__':
-    knowledge_id = asyncio.run(main())
-    print(f'\n最终知识 ID: {knowledge_id}')

examples/mini_restore/config.py

@@ -11,6 +11,7 @@ RUN_CONFIG = RunConfig(
     model="qwen3.5-plus",
     temperature=0.3,
     max_iterations=200,
+    tool_groups=["core", "browser", "content", "knowledge", "toolhub", "feishu", "im"],
 
     extra_llm_params={"extra_body": {"enable_thinking": True}},
 

examples/mini_restore/workflow_loop.py

@@ -20,7 +20,7 @@ except ValueError as e:
     print(f"初始化 Gemini 失败: {e}，请检查 .env。")
     sys.exit(1)
 
-from agent.tools.builtin.search import search_posts
+from agent.tools.builtin.content import content_search
 
 # -----------------
 # Utility Functions
@@ -76,7 +76,7 @@ async def call_banana_tool(prompt: str, aspect_ratio: str = None, reference_imag
 async def search_tool(keyword: str) -> str:
     print(f"\n[Tool] 🔍 启动小红书调研, 关键词: {keyword}")
     try:
-        result = await search_posts(keyword=keyword, channel="xhs", max_count=3)
+        result = await content_search(platform="xhs", keyword=keyword, max_count=3)
         return result.output
     except Exception as e:
         return f"查询失败: {e}"

examples/production_restore/config.py

@@ -50,7 +50,7 @@ RUN_CONFIG = RunConfig(
 # ===== 任务配置 =====
 
 INPUT_DIR = "examples/production_restore/input"       # 输入目录（pipeline.json、analysis.json 等）
-OUTPUT_DIR = "examples/production_restore/output_feature"     # 输出目录
+OUTPUT_DIR = "examples/production_restore/output_origin"     # 输出目录
 FEATURES_DIR = "examples/production_restore/features"         # 素材目录
 
 

examples/production_restore/execution.prompt

@@ -18,17 +18,17 @@ $system$
 - Prompt 文本
 - 图生图配置（img2img_config）
 
-**参考源信息（raw_info 目录）**：
-在输入目录中有一个 `raw_info/` 文件夹，包含原始图片的源信息：
-- 每张图的制作表：`raw_info/写生油画__img_X_制作表.json`（对应 img_1 ~ img_5）
-- 通用创作信息：`raw_info/创作表.md`、`raw_info/制作点.md`、`raw_info/图片亮点.md`
+**参考源信息（输入目录）**：
+输入目录 `%input_dir%/` 中包含原始图片的源信息：
+- 每张图的制作表：`%input_dir%/写生油画__img_X_制作表.json`（对应 img_1 ~ img_5）
+- 通用创作信息：`%input_dir%/创作表.md`、`%input_dir%/制作点.md`、`%input_dir%/图片亮点.md`
 
-在构建或优化 prompt 时，**应先读取当前图片对应的制作表 JSON 和通用文件作为参考**，从中提取有价值的细节描述融入 prompt。raw_info 是辅助参考，最终 prompt 仍以任务指派中的要求为准。
+在构建或优化 prompt 时，**应先读取当前图片对应的制作表 JSON 和通用文件作为参考**，从中提取有价值的细节描述融入 prompt。这些源信息是辅助参考，最终 prompt 仍以任务指派中的要求为准。
 
 ### 第二步：验证素材可用性
 在执行生成前，先验证所需文件存在且可读：
 - 使用 `read_file` 工具检查各参考素材文件（**`read_file` 支持读取图片，会自动转为 base64 供你查看，无需打开浏览器**）
-- 读取 `raw_info/` 目录下对应的制作表 JSON（如生成 img_1 则读 `写生油画__img_1_制作表.json`）和通用文件（`创作表.md`、`图片亮点.md`），提取可用于 prompt 的细节
+- 读取 `%input_dir%/` 目录下对应的制作表 JSON（如生成 img_1 则读 `写生油画__img_1_制作表.json`）和通用文件（`创作表.md`、`图片亮点.md`），提取可用于 prompt 的细节
 - 如有素材缺失，立即在结果中标注（不要自行跳过）
 
 ### 第三步：通过 ToolHub 工具库执行生成
@@ -81,19 +81,21 @@ toolhub.py 内置了 `_preprocess_params` 函数，会自动将本地路径上
 
 **单图评估**：传入需求文档路径和单张图片路径
 ```json
-{"requirement_path": "%input_dir%/pipeline.json", "image_paths": "输出图片路径"}
+{"requirement_path": "%output_dir%/pipeline.json", "image_paths": "输出图片路径"}
 ```
 
 **多图一致性评估**：传入需求文档路径和多张图片路径列表，自动检查跨图一致性
 ```json
-{"requirement_path": "%input_dir%/pipeline.json", "image_paths": ["img_1路径", "img_2路径", "img_3路径"]}
+{"requirement_path": "%output_dir%/pipeline.json", "image_paths": ["img_1路径", "img_2路径", "img_3路径"]}
 ```
 
 - 单图模式：从姿态、服装、光影、背景、材质、构图 6 个维度打分（0-10）
 - 多图模式：从角色、服装、色调、光影、风格 5 个一致性维度打分，并逐图给分，指出不一致的图片
 - 根据评估结果判断是否需要重新生成或调整参数
 
-同时人工对照 output_spec 逐项检查：
+**人工对照制作表逐项检查（极其重要）**：
+
+自动评估工具只能给出维度打分，但无法判断是否符合原始制作表的具体要求。**你必须读取 `%input_dir%/` 下该图对应的制作表 JSON（如生成 img_1 则读 `写生油画__img_1_制作表.json`）**，对照其中的详细描述逐项检查：
 - 姿态是否符合需求描述（手臂位置、站/跪姿态）
 - 景深/散景效果是否达到要求
 - 人物参考是否注入（发型、服装款式）

examples/production_restore/input/analysis.json

@@ -1,100 +0,0 @@
-{
-  "category": {
-    "name": "户外白裙写生少女",
-    "traits": [
-      "穿着白色连衣裙的女性在户外草地进行油画写生",
-      "白绿配色为主，清新自然的森系视觉基调",
-      "包含画架、画布、调色板、画笔等写生道具",
-      "逆光/轮廓光与浅景深虚化营造梦幻氛围",
-      "画布内容与现实场景形成画中画呼应结构"
-    ],
-    "quality_challenges": [
-      "人物姿态自然度：需要呈现专注绘画的动态姿态，避免僵硬",
-      "白裙质感表现：轻薄面料的垂坠感、褶皱细节和透光效果",
-      "调色板颜料质感：厚重油画的 Impasto 堆叠感和色彩混合细节",
-      "光影层次：逆光下的轮廓光晕与主体细节的平衡",
-      "景深控制：前景清晰、背景虚化的自然过渡",
-      "画中画一致性：画布上的油画内容需与现实场景形成视觉呼应",
-      "发丝细节：逆光下头发边缘的光晕效果和发丝清晰度"
-    ],
-    "reasoning": "基于图片亮点.md 的 6 个聚类主题（优雅白裙少女、斑斓颜料、写生道具、白绿配色、光影景深、画中画结构）和制作点.md 的 6 大元素权重（女性 84.5、绘画工具 78.5、自然背景 74.0、画架画布 67.67、画架油画 60.97、女性衣物 44.7），以及 5 张制作表中对姿态、服装、光影、清晰度的详细规格描述综合判断"
-  },
-  "highlight": [
-    {
-      "name": "优雅的白裙写生少女",
-      "description": "女性主体需呈现文艺气质与娴静美，包括专注的绘画姿态（身体前倾、手臂抬起握笔）、自然垂坠的白色长裙（V 字露背或圆领、腰部系带收腰、裙摆飘逸）、棕色长发（自然披散、逆光下边缘光晕），整体塑造写生缪斯形象",
-      "reasoning": "图片亮点.md 中该聚类覆盖全部 5 张图片，制作点.md 中'女性'元素综合权重 84.5 为最高，5 张制作表中人物段落评分均在 0.745-0.858 之间，是画面核心主体",
-      "references": ["descriptions/图片亮点.md", "descriptions/制作点.md", "descriptions/写生油画__img_1_制作表.json#段落 1.1", "descriptions/写生油画__img_2_制作表.json#段落 2.1", "descriptions/写生油画__img_3_制作表.json#段落 3.1", "descriptions/写生油画__img_4_制作表.json#段落 4.1", "descriptions/写生油画__img_5_制作表.json#段落 5.1"]
-    },
-    {
-      "name": "斑斓厚重的油画颜料",
-      "description": "木质调色板上堆积的厚重油画颜料（Impasto），呈不规则块状分布，色彩鲜艳杂乱（绿色、蓝色、红色、黄色、白色、紫色等至少 10 种颜色），颜料具有膏状质感和明显堆叠厚度，与周围大面积纯白衣物形成强烈视觉反差",
-      "reasoning": "图片亮点.md 专门聚焦该实质物体，制作点.md 中'绘画工具'权重 78.5 排第二，img_1 和 img_5 制作表中调色板颜料细节描述详尽（颜色种类、分布模式、质地），img_5 中颜料段落评分达 0.754",
-      "references": ["descriptions/图片亮点.md", "descriptions/制作点.md", "descriptions/写生油画__img_1_制作表.json#段落 1.1.2.3", "descriptions/写生油画__img_5_制作表.json#段落 5.1.3.1"]
-    },
-    {
-      "name": "清新雅致的白绿配色",
-      "description": "大面积高饱和度自然草木绿背景（鲜绿色草地、深浅不一的绿色树木）与人物纯白服装形成鲜明对比，确立清新、自然、治愈的森系视觉基调，色彩饱和度中等偏高但不刺眼",
-      "reasoning": "图片亮点.md 中该形式类聚类强调色彩构成的形式美感，覆盖 img_1 和 img_4，5 张制作表的背景段落均描述'以绿色为主'，色彩形式评分普遍较高",
-      "references": ["descriptions/图片亮点.md", "descriptions/写生油画__img_1_制作表.json#段落 1.3", "descriptions/写生油画__img_4_制作表.json#段落 4.3"]
-    },
-    {
-      "name": "唯美梦幻的光影与景深",
-      "description": "温暖的逆光/轮廓光从画面左上方或右上方照射，人物和物体边缘形成明显光晕；大光圈浅景深虚化（Bokeh）使背景呈现柔和散景，前景主体清晰锐利（头发丝、服装纹理、手部细节可见），营造脱离现实的梦幻浪漫氛围",
-      "reasoning": "图片亮点.md 中该形式类聚类覆盖 img_2、img_3、img_5，5 张制作表的形式段落均描述'逆光'或'自然光从左上方/右上方照射'，清晰度描述均为'前景清晰、背景虚化'，img_2 特别强调'强烈光斑和光晕效果'",
-      "references": ["descriptions/图片亮点.md", "descriptions/写生油画__img_2_制作表.json#段落 2 形式", "descriptions/写生油画__img_3_制作表.json#段落 3 形式", "descriptions/写生油画__img_5_制作表.json#段落 5 形式"]
-    },
-    {
-      "name": "虚实呼应的画中画结构",
-      "description": "画架上的画布内容与现实场景形成'镜像'或'互文'关系——画布上描绘身穿白色裙子的女性在户外草地/花丛中的背影，与现实中的画家形成视觉呼应，构建增加叙事深度的画中画结构，画布采用印象派风格（笔触粗犷、色彩鲜明）",
-      "reasoning": "图片亮点.md 中该形式类聚类覆盖 img_1 和 img_2，img_1、img_2、img_3 制作表中画布段落均详细描述'描绘了一名背对镜头的女性'，内容主题与现实场景呼应，画布段落评分高达 0.891-0.958",
-      "references": ["descriptions/图片亮点.md", "descriptions/写生油画__img_1_制作表.json#段落 1.2.1", "descriptions/写生油画__img_2_制作表.json#段落 2.2.1", "descriptions/写生油画__img_3_制作表.json#段落 3.2.1"]
-    }
-  ],
-  "baseline": [
-    {
-      "name": "人物姿态自然度",
-      "description": "女性需呈现专注绘画的动态姿态（身体略微前倾、右臂抬起握笔、左臂弯曲持调色板、头部转向画布），避免僵硬呆板的摆拍感",
-      "why_critical": "制作表中 5 张图的人物姿态描述均强调'专注绘画的动态姿态'，姿态不自然会导致人物像假人模特，破坏'优雅写生少女'的核心亮点",
-      "reasoning": "img_1 制作表#段落 1.1.2 描述'身体略微前倾，右臂抬起握持画笔，左臂弯曲握持调色板'，img_2、img_3、img_4 均有类似姿态描述，姿态形式评分在 0.455-0.765 之间",
-      "references": ["descriptions/写生油画__img_1_制作表.json#段落 1.1.2", "descriptions/写生油画__img_2_制作表.json#段落 2.1.2", "descriptions/写生油画__img_3_制作表.json#段落 3.1.2", "descriptions/写生油画__img_4_制作表.json#段落 4.1.2"]
-    },
-    {
-      "name": "白裙材质与褶皱真实感",
-      "description": "白色长裙需呈现轻薄棉麻或丝绸质地的垂坠感和透气性，有自然形成的垂坠褶皱（裙摆、腰部、背部 V 领处），服装颜色为纯白色无图案",
-      "why_critical": "制作点.md 中'女性衣物'权重 44.7，5 张制作表的服装段落评分均高达 0.806-0.847，材质和褶皱描述详尽，做不好会导致服装像塑料或纸片，一眼假",
-      "reasoning": "img_1 制作表#段落 1.1.2.1 描述'轻薄的棉麻或丝绸质地，具有良好的垂坠感'，img_2、img_3、img_4 均有'丝绸或棉麻混纺材质，表面光滑，有轻微光泽感'等描述",
-      "references": ["descriptions/制作点.md", "descriptions/写生油画__img_1_制作表.json#段落 1.1.2.1", "descriptions/写生油画__img_2_制作表.json#段落 2.1.2.1", "descriptions/写生油画__img_3_制作表.json#段落 3.1.2.1", "descriptions/写生油画__img_4_制作表.json#段落 4.1.2.1"]
-    },
-    {
-      "name": "调色板颜料质感",
-      "description": "调色板上的颜料需呈现膏状堆积的厚度和立体感，表面有光泽显示湿润质地，颜色种类丰富（至少 10 种），呈不规则块状和条状分布，部分颜色相互混合形成过渡色",
-      "why_critical": "图片亮点.md 专门将'斑斓厚重的油画颜料'列为实质类亮点，img_5 制作表中颜料段落评分 0.754，质感描述详尽，做不好会像平面贴图而非真实颜料",
-      "reasoning": "img_5 制作表#段落 5.1.3.1 详细描述'颜料呈膏状，堆积在调色板表面，具有一定的厚度和立体感，表面有光泽，显示出湿润的质地'，img_1 也有'颜料堆叠感明显'描述",
-      "references": ["descriptions/图片亮点.md", "descriptions/写生油画__img_1_制作表.json#段落 1.1.2.3", "descriptions/写生油画__img_5_制作表.json#段落 5.1.3.1"]
-    },
-    {
-      "name": "前景主体清晰度",
-      "description": "人物主体（头发丝、服装纹理、手部细节）、调色板（木质纹理、颜料堆叠）、画架需清晰锐利，细节可见，与虚化背景形成对比",
-      "why_critical": "5 张制作表的形式段落均强调'前景人物和画架清晰锐利'，清晰度形式评分普遍较高，做不好会导致画面整体模糊，失去专业摄影质感",
-      "reasoning": "img_1 制作表#段落 1 形式描述'画面中心区域清晰度高，细节锐利可见'，img_2、img_3、img_4、img_5 均有类似描述，清晰度是所有制作表的必选形式参数",
-      "references": ["descriptions/写生油画__img_1_制作表.json#段落 1 形式", "descriptions/写生油画__img_2_制作表.json#段落 2 形式", "descriptions/写生油画__img_3_制作表.json#段落 3 形式", "descriptions/写生油画__img_4_制作表.json#段落 4 形式", "descriptions/写生油画__img_5_制作表.json#段落 5 形式"]
-    },
-    {
-      "name": "背景虚化自然度",
-      "description": "背景树木和草地需呈现柔和的虚化效果（浅景深），与前景清晰主体形成自然过渡，虚化区域有光斑效果（尤其是逆光场景）",
-      "why_critical": "图片亮点.md 将'唯美梦幻的光影与景深'列为形式类亮点，5 张制作表均描述'景深较浅，背景虚化'，做不好会导致画面缺乏层次感和专业感",
-      "reasoning": "img_2 制作表#段落 2.3 描述'背景整体呈现柔和的虚化效果，景深较浅，树木轮廓模糊，光斑明显'，所有制作表的背景段落均有景深描述",
-      "references": ["descriptions/图片亮点.md", "descriptions/写生油画__img_2_制作表.json#段落 2.3", "descriptions/写生油画__img_3_制作表.json#段落 3.3", "descriptions/写生油画__img_5_制作表.json#段落 5.3"]
-    }
-  ],
-  "requirement_summary": [
-    "高质量人物生成：白裙女性、自然绘画姿态、棕色长发、逆光轮廓光",
-    "服装材质还原：轻薄棉麻/丝绸质地、垂坠褶皱、纯白色",
-    "调色板与颜料：木质调色板、厚重油画颜料 Impasto 质感、多色混合",
-    "光影效果：逆光/轮廓光、温暖光晕、前景清晰背景虚化",
-    "画中画结构：画布上油画内容需与现实场景呼应、印象派风格",
-    "自然背景：高饱和度绿色草地和树木、清新森系色调",
-    "道具细节：画架结构、画笔、白玫瑰点缀"
-  ]
-}

examples/production_restore/input/pipeline.json

@@ -1,194 +0,0 @@
-{
-  "project": "户外白裙写生少女图像还原",
-  "category": "户外白裙写生少女",
-  "total_images": 5,
-  "stages": {
-    "stage_1": {
-      "name": "链式图生图生成",
-      "status": "pending",
-      "description": "以 features 目录中的参考素材为底图，按顺序逐张生成。从 img_1 开始，每张图生成后，将结果作为下一张图的额外参考（chain_from），确保角色、服装、色调的跨图一致性。必须严格按 img_1 → img_2 → img_3 → img_4 → img_5 的顺序串行执行，不可并行",
-      "images": ["img_1", "img_2", "img_3", "img_4", "img_5"],
-      "execution_order": "sequential_chain",
-      "tool_priority": ["nano_banana", "flux_generate", "seedream_generate"],
-      "fallback": "仅当端到端工具效果不足时，才考虑使用 liblibai_controlnet"
-    },
-    "stage_2": {
-      "name": "迭代优化",
-      "status": "pending",
-      "description": "以 Stage 1 生成的图像作为底图，再次图生图迭代优化，增强材质、光影、细节的真实感"
-    },
-    "stage_3": {
-      "name": "跨图一致性检查",
-      "status": "pending",
-      "description": "对比 5 张生成图，检查角色、服装、色彩、光影的一致性。对不一致的图以当前结果为底图重新图生图优化"
-    },
-    "stage_4": {
-      "name": "细节修复与输出",
-      "status": "pending",
-      "description": "逐项检查并修复细节问题，以当前结果为底图进行定向图生图修复，输出最终成品"
-    }
-  },
-  "images": {
-    "img_1": {
-      "required_spec": {
-        "pose": "侧身背对，站姿，身体前倾，右臂抬起握笔，左臂持调色板",
-        "服装": "白色长裙，V 字露背，腰部系带，轻薄棉麻质地，垂坠褶皱",
-        "光影": "逆光从左上方照射，轮廓光晕，发丝金边",
-        "背景": "高饱和度绿色草地和树木，浅景深虚化",
-        "道具": "木质画架，白色画布（有画中画内容），木质调色板（多色颜料）",
-        "画中画": "画布上描绘背对镜头的女性 + 草地 + 蓝花，印象派风格"
-      },
-      "input_from": {
-        "character_ref": "character_asset/character_ref_img1.png",
-        "background_ref": "background_asset/background_green_img1.png",
-        "palette_ref": "palette_asset/palette_impasto_img1_v2.png"
-      },
-      "img2img_config": {
-        "base_image": "character_ref",
-        "reference_images": ["background_ref", "palette_ref"],
-        "chain_from": null,
-        "note": "第 1 张图，无前序结果。以人物参考图为底图做图生图，prompt 中融合背景、道具、光影描述。此图确立角色基准外观"
-      },
-      "prompt": "一位穿着纯白色长裙的女性在户外草地写生，身体略微前倾专注绘画，右手持画笔左手持调色板，棕色长发自然披散在背部，轻薄棉麻质地的白色长裙，V 字露背设计，腰部系带收腰，裙摆自然垂坠有飘逸感，温暖的逆光从左上方照射，人物边缘形成金色轮廓光，发丝呈现明亮光晕，全画幅 85mm 人像定焦镜头，光圈 f/1.8 大光圈，浅景深效果，前景人物清晰锐利，背景草地和树木柔和虚化，高饱和度自然草木绿背景，纯白服装与绿色形成鲜明对比，清新森系色调，真实摄影风格",
-      "negative_prompt": "AI 假人感，塑料质感，过度修饰，模糊，低质量，变形，cgi，3d 渲染，平滑无纹理",
-      "output_spec": {
-        "file": "img_1_restored_v1.png",
-        "resolution": "1024x1365",
-        "critical_checks": ["人物姿态自然度", "白裙材质与褶皱真实感", "前景主体清晰度"],
-        "high_checks": ["逆光轮廓光效果", "背景虚化自然度", "调色板颜料质感"]
-      }
-    },
-    "img_2": {
-      "required_spec": {
-        "pose": "背对，逆光，半剪影效果，身体略微右倾",
-        "服装": "白色长裙，轻薄材质，逆光下透光效果",
-        "光影": "强烈逆光，明显光斑和光晕效果，发丝金边",
-        "背景": "绿色树木，柔和虚化，圆形光斑 (bokeh)",
-        "道具": "木质画架，白色画布（有画中画内容），调色板",
-        "画中画": "画布上描绘背对女性 + 植物 + 花朵 + 光斑，印象派风格"
-      },
-      "input_from": {
-        "character_ref": "character_asset/character_ref_back.png",
-        "background_ref": "background_asset/background_bokeh_img2.png"
-      },
-      "img2img_config": {
-        "base_image": "character_ref",
-        "reference_images": ["background_ref"],
-        "chain_from": "img_1",
-        "note": "以背影参考图为底图，同时将 img_1 的生成结果作为参考图传入，保持角色一致性。prompt 中强化逆光和散景效果"
-      },
-      "prompt": "一位穿着纯白色长裙的女性在户外草地写生，背对镜头，身体略微右倾，强烈逆光效果，人物呈半剪影，发丝边缘明亮金边，轻薄白裙在逆光下呈现透光效果，木质画架和画布，调色板，背景绿色树木柔和虚化，圆形光斑效果，梦幻浪漫氛围，85mm 镜头，f/1.8 大光圈，真实摄影风格",
-      "negative_prompt": "AI 假人感，塑料质感，过度修饰，模糊，低质量，变形，cgi，3d 渲染，光线平淡",
-      "output_spec": {
-        "file": "img_2_restored_v1.png",
-        "resolution": "1024x1365",
-        "critical_checks": ["逆光轮廓光效果", "人物姿态自然度", "前景主体清晰度"],
-        "high_checks": ["背景光斑效果", "白裙透光感", "发丝金边细节"]
-      }
-    },
-    "img_3": {
-      "required_spec": {
-        "pose": "跪坐姿态，身体前倾，左臂靠近地面调色板",
-        "服装": "白色长裙，跪坐时裙摆自然铺展",
-        "光影": "自然光从左上方照射，柔和轮廓光",
-        "背景": "绿色草地，蓝紫色花丛，浅景深",
-        "道具": "木质画架，白色画布（有画中画内容），地面调色板",
-        "画中画": "画布上描绘白裙女性 + 花丛 + 遮阳伞，印象派风格"
-      },
-      "input_from": {
-        "character_ref": "character_asset/character_ref_kneel.png",
-        "background_ref": "background_asset/background_green_img1.png"
-      },
-      "img2img_config": {
-        "base_image": "character_ref",
-        "reference_images": ["background_ref"],
-        "chain_from": "img_2",
-        "note": "以跪姿参考图为底图，将 img_2 的结果作为参考保持角色一致性"
-      },
-      "prompt": "一位穿着纯白色长裙的女性跪坐在户外草地写生，身体前倾专注绘画，左臂靠近地面调色板，棕色长发自然披散，轻薄棉麻质地白裙，裙摆自然铺展在草地上，自然光从左上方照射，柔和轮廓光，背景绿色草地和蓝紫色花丛，浅景深虚化，85mm 镜头，f/1.8 光圈，清新森系色调，真实摄影风格",
-      "negative_prompt": "AI 假人感，塑料质感，过度修饰，模糊，低质量，变形，cgi，3d 渲染，姿态僵硬",
-      "output_spec": {
-        "file": "img_3_restored_v1.png",
-        "resolution": "1024x1365",
-        "critical_checks": ["跪坐姿态自然度", "白裙材质与褶皱真实感", "前景主体清晰度"],
-        "high_checks": ["花丛背景虚化", "裙摆铺展效果", "光影柔和度"]
-      }
-    },
-    "img_4": {
-      "required_spec": {
-        "pose": "侧身面对镜头，仰望，右臂抬起握笔",
-        "服装": "白色长裙，侧身视角可见服装轮廓",
-        "光影": "自然光照射，柔和光影",
-        "背景": "高饱和度绿色草地和树木，浅景深",
-        "道具": "木质画架，空白白色画布（无内容），调色板",
-        "画中画": "空白画布，纯白色表面，无颜料痕迹"
-      },
-      "input_from": {
-        "character_ref": "character_asset/character_ref_side.png",
-        "background_ref": "background_asset/background_green_img4.png",
-        "easel_ref": "easel_asset/easel_blank_canvas_img4.png"
-      },
-      "img2img_config": {
-        "base_image": "character_ref",
-        "reference_images": ["background_ref", "easel_ref"],
-        "chain_from": "img_3",
-        "note": "以侧面参考图为底图，将 img_3 的结果作为参考保持角色一致性。prompt 中强化'空白画布无内容'"
-      },
-      "prompt": "一位穿着纯白色长裙的女性侧身站立面对镜头，头部仰望向左上方，右臂抬起握持画笔，左臂持调色板，轻薄棉麻质地白裙，自然光照射，柔和光影，背景高饱和度绿色草地和树木，浅景深虚化，木质画架上有空白白色画布，纯白色表面无颜料痕迹，85mm 镜头，f/1.8 光圈，清新森系色调，真实摄影风格",
-      "negative_prompt": "AI 假人感，塑料质感，过度修饰，模糊，低质量，变形，cgi，3d 渲染，画布上有内容，颜料痕迹",
-      "output_spec": {
-        "file": "img_4_restored_v1.png",
-        "resolution": "1024x1365",
-        "critical_checks": ["人物姿态自然度", "白裙材质真实感", "空白画布纯白无内容"],
-        "high_checks": ["仰望表情自然", "侧身轮廓清晰", "背景虚化"]
-      }
-    },
-    "img_5": {
-      "required_spec": {
-        "pose": "特写镜头，聚焦手部和调色板，上半身可见",
-        "服装": "白色长裙，特写可见材质细节",
-        "光影": "温暖逆光，调色板颜料光泽",
-        "背景": "绿色背景，强烈虚化",
-        "道具": "木质调色板（多色厚重颜料 Impasto 质感），画笔",
-        "画中画": "画布部分可见于背景，绿蓝色调，笔触粗犷"
-      },
-      "input_from": {
-        "character_ref": "character_asset/character_ref_main.png",
-        "palette_ref": "palette_asset/palette_impasto_img1_v2.png"
-      },
-      "img2img_config": {
-        "base_image": "character_ref",
-        "reference_images": ["palette_ref"],
-        "chain_from": "img_4",
-        "note": "以人物正面参考图为底图，将 img_4 的结果作为参考保持角色一致性。prompt 中强化特写镜头和 Impasto 颜料质感"
-      },
-      "prompt": "特写镜头，聚焦女性双手握持木质调色板和画笔，调色板上有厚重油画颜料 Impasto 质感，膏状堆积，多色混合（绿色、蓝色、红色、黄色、白色、紫色），颜料表面湿润光泽，立体厚度可见，女性穿着纯白色长裙，上半身可见，温暖逆光照射，颜料光泽反射，背景绿色强烈虚化，85mm 微距镜头，f/1.8 光圈，真实摄影风格",
-      "negative_prompt": "AI 假人感，塑料质感，平滑无纹理，模糊，低质量，变形，cgi，3d 渲染，颜料扁平无厚度",
-      "output_spec": {
-        "file": "img_5_restored_v1.png",
-        "resolution": "1024x1365",
-        "critical_checks": ["调色板颜料 Impasto 质感", "颜料湿润光泽", "特写清晰度"],
-        "high_checks": ["多色颜料混合", "手部细节", "背景虚化"]
-      }
-    }
-  },
-  "consistency_checks": {
-    "stage_3": {
-      "character_consistency": "5 张图中女性角色面部特征、发型、肤色应保持一致",
-      "costume_consistency": "白色长裙的材质、款式、颜色应 100% 一致（V 字露背、腰部系带、轻薄棉麻）",
-      "color_scheme": "白绿配色方案贯穿所有图像，绿色饱和度中等偏高，纯白服装",
-      "lighting_consistency": "逆光/轮廓光方向一致（左上方），光晕效果统一",
-      "style_consistency": "真实摄影风格，85mm 镜头，f/1.8 景深效果统一"
-    }
-  },
-  "repair_items": {
-    "stage_4": [
-      {"item": "人物面部细节", "check": "肌肤纹理清晰，无 AI 假人感", "repair_tool": "图生图局部重绘"},
-      {"item": "服装褶皱", "check": "白裙垂坠褶皱自然，材质真实", "repair_tool": "图生图局部重绘"},
-      {"item": "调色板颜料", "check": "Impasto 质感明显，膏状堆积，湿润光泽", "repair_tool": "图生图局部重绘"},
-      {"item": "画布内容", "check": "画中画结构清晰，印象派风格", "repair_tool": "图生图局部重绘"},
-      {"item": "光影效果", "check": "逆光轮廓光自然，发丝金边清晰", "repair_tool": "图生图局部重绘"},
-      {"item": "背景虚化", "check": "浅景深效果自然，光斑柔和", "repair_tool": "图生图局部重绘"}
-    ]
-  }
-}

examples/production_restore/input/strategy.json

@@ -1,44 +0,0 @@
-{
-  "selected_strategy": {
-    "name": "素材驱动端到端工作流：参考素材图生图 → 迭代优化 → 一致性检查 → 细节修复",
-    "workflow_outline": [
-      "阶段 1 - 素材驱动图生图：以 features 中的参考素材（人物参考图）为底图传入 image_url，配合详细 prompt 描述服装材质、光影效果、相机参数，通过 nano_banana / flux_generate / seedream_generate 从头生成图像",
-      "阶段 2 - 迭代优化：以阶段 1 生成结果为底图再次图生图，增强材质、光影、细节真实感",
-      "阶段 3 - 跨图一致性检查：对比 5 张生成图的角色、服装、色彩、光影一致性，对不一致的图重新图生图优化",
-      "阶段 4 - 细节修复与输出：以当前结果为底图，针对局部细节（面部、褶皱、颜料质感等）进行定向图生图修复"
-    ],
-    "tool_priority": [
-      "nano_banana — 首选，速度快、效果好",
-      "flux_generate — 备选，支持 image_url 图生图",
-      "seedream_generate — 备选，支持 image_url 图生图",
-      "liblibai_controlnet — 最后回退，仅当需要精细姿态/边缘/深度控制且端到端工具效果不足时使用"
-    ],
-    "highlight_coverage": [
-      "优雅的白裙写生少女：端到端图生图保留原型构图 + 增强材质真实感",
-      "斑斓厚重的油画颜料：通过 prompt 强化 Impasto 质感描述 + palette_ref 素材辅助",
-      "清新雅致的白绿配色：prompt 中控制色彩 + background_ref 素材引导",
-      "唯美梦幻的光影与景深：prompt 中描述逆光轮廓光 + 相机参数（85mm、f/1.8）",
-      "虚实呼应的画中画结构：prompt 中同时描述现实场景和画布内容的镜像关系"
-    ],
-    "baseline_coverage": [
-      "人物姿态自然度：以原型图为底图保留姿态，端到端工具增强真实感",
-      "白裙材质与褶皱真实感：prompt 中详细描述布料材质（棉麻、垂坠、透光）",
-      "调色板颜料质感：prompt 强化 Impasto 描述 + palette_ref 素材参考",
-      "前景主体清晰度：prompt 中描述相机参数确保主体锐利",
-      "背景虚化自然度：prompt 中描述 f/1.8 大光圈、浅景深效果"
-    ],
-    "reasoning": "该策略的核心优势：1）端到端图生图工具（nano_banana/flux/seedream）通过 ToolHub 直接可用，无需额外配置；2）以原型图为底图可保留已验证的构图和姿态，只增强真实感；3）参考素材（人物、背景、道具）提供风格引导；4）全流程使用 ToolHub 工具，链路简短、执行效率高；5）仅在端到端工具效果不足时才回退到 ControlNet，避免不必要的复杂度"
-  },
-  "vs_alternatives": [
-    {
-      "alternative": "ControlNet 精确控制方案",
-      "why_not": "需要先提取控制信号（骨骼图、深度图、边缘图），当前素材中不包含这些文件；链路更长、配置更复杂；对于本项目已有原型图+参考素材的情况，端到端图生图更直接高效",
-      "could_switch_if": "端到端工具无法精确控制姿态或构图细节；需要逐像素级别的结构控制"
-    },
-    {
-      "alternative": "纯文生图方案（不使用底图）",
-      "why_not": "放弃已有原型图的构图和姿态信息，每次从零生成；一致性难以保证；浪费已有资源",
-      "could_switch_if": "原型图质量太差无法作为底图使用"
-    }
-  ]
-}

examples/production_restore/presets.json

@@ -5,7 +5,7 @@
     "skills": ["planning"],
     "prompt_vars": {
       "input_dir": "examples/production_restore/input",
-      "output_dir": "examples/production_restore/output_feature",
+      "output_dir": "examples/production_restore/output_origin",
       "features_dir": "examples/production_restore/features"
     },
     "description": "Business Agent - 决策循环编排器，驱动 goal → evaluate → decide → dispatch 循环"
@@ -17,7 +17,7 @@
     "skills": ["planning"],
     "prompt_vars": {
       "input_dir": "examples/production_restore/input",
-      "output_dir": "examples/production_restore/output_feature",
+      "output_dir": "examples/production_restore/output_origin",
       "features_dir": "examples/production_restore/features"
     },
     "description": "Craftsman - 单步执行专家，调用 ToolHub 工具执行图像生成"
@@ -28,7 +28,7 @@
     "temperature": 0.3,
     "skills": ["planning"],
     "prompt_vars": {
-      "output_dir": "examples/production_restore/output_feature"
+      "output_dir": "examples/production_restore/output_origin"
     },
     "description": "Researcher - 外部知识获取专家，搜索线上教程和案例"
   }

examples/production_restore/requirement.prompt

@@ -13,6 +13,7 @@ $system$
 | 角色 | 调用方式 | 职责 |
 |------|---------|------|
 | **Librarian** | `ask_knowledge(query=...)` | 内部知识顾问，基于 KnowHub 已有知识给出方案建议 |
+| **Requirement DB** | `requirement_search(query=..., top_k=20)` | 需求库检索，查找已有的制作需求 |
 | **Craftsman** | `agent(task=..., agent_type="craftsman")` | 单步执行专家，调用 ToolHub 工具执行图像生成 |
 | **Researcher** | `agent(task=..., agent_type="researcher")` | 外部知识获取，搜索线上教程和案例 |
 | **evaluate** | `evaluate_image(requirement_path=..., image_paths=...)` | 质量评估工具，对照需求打分 |
@@ -22,7 +23,7 @@ $system$
 - 素材目录（参考图等素材）：`%features_dir%`
 - 输出目录：`%output_dir%`
 
-pipeline.json 中 `input_from` 字段的路径均相对于素材目录。**指派任务时必须将其展开为完整路径**，传给 Craftsman 的路径必须以 `%features_dir%/` 开头。
+`%output_dir%/pipeline.json` 中 `base_image` 和 `reference_images` 的路径必须以 `%features_dir%/` 开头。
 
 ### 素材目录结构
 ```
@@ -51,68 +52,236 @@ features/
 
 ## 工作流程
 
-### 第一步：读取还原方案
-读取 `%input_dir%/pipeline.json`，提取整体结构和每张图的规格。
+### 第零步：需求分析（从内容描述提取制作需求）
 
-### 第二步：问策 Librarian
-在开始生成前，先向 Librarian 咨询：
-```
-ask_knowledge(query="户外白裙写生少女图像还原，使用端到端图生图工具（nano_banana/flux/seedream），需要保持5张图的角色一致性，有什么推荐方案？")
-```
-- Librarian 会返回 KnowHub 中已有的策略经验、工具评估、工作流总结
-- 如果 Librarian 回复"知识不足"或建议不够具体 → 派发 Researcher 调研
+在开始执行前，先从输入目录的内容描述文件中提取制作层需求。
+
+**1. 读取内容描述文件**
+
+读取 `%input_dir%` 下的核心描述文件（文件名可能略有差异，按实际存在的读取）：
+- `制作点.md`：核心制作元素及权重
+- `图片亮点.md` 或 `制作亮点.md`：视觉亮点聚类
+- `创作表.md`：创作视角描述（可选）
+- `*_制作表.json`：各图的详细制作表（按需抽查 1-2 个了解细节）
+
+**2. 检索已有需求**
 
-### 第三步：按需调研
-如果 Librarian 的知识不足以决策：
+用 `requirement_search` 对每个核心制作元素和亮点主题分别检索需求库，了解已有哪些相关需求：
 ```
-agent(task="调研 nano_banana 图生图的最佳实践，特别是如何保持多图角色一致性...", agent_type="researcher")
+requirement_search(query="人物写生 白裙女性 角色一致性", top_k=20)
+requirement_search(query="油画颜料质感 Impasto厚涂", top_k=20)
+requirement_search(query="户外自然背景 逆光散景 浅景深虚化", top_k=20)
+```
+- **分词搜索**：不要把所有关键词拼成一个 query，而是对每个核心制作元素、亮点主题分别搜索
+- 对制作点中权重最高的元素、亮点中覆盖图片最多的聚类，分别发起检索
+- 了解已有哪些需求，避免重复提取；已有需求可直接引用而不重复创建
+
+**3. 提取制作需求**
+
+站在图片制作者的角度，从内容描述中提取"用 AI 图像工具制作这组内容时，需要实现什么视觉效果"：
+- **从制作点出发**：按权重从高到低，识别需要 AI 工具还原的核心视觉元素
+- **从亮点出发**：识别图组中必须保持高表现力的视觉特征，转化为制作需求
+- **从制作表验证**：抽查具体图片的制作表，确认需求的具体性和可行性
+- **合并同类**：将指向同一视觉能力的元素和亮点合并为一个需求
+- **对比已有**：将提取结果与检索到的已有需求对比，标注哪些是新需求、哪些已存在
+
+**注意**：
+- 需求描述最终的视觉呈现效果，不要使用技术术语（如"ControlNet""LoRA"等）
+- 多个制作元素或亮点指向同一类视觉效果时，合并为一个需求
+- 每组内容的需求数量一般为 3-8 个
+
+**4. 保存需求文件**
+
+将提取结果保存到 `%output_dir%/requirements.json`。
+
+**输出格式要求**：需求必须按来源分为两组，先列出从需求库查询匹配到的已有需求（`matched_requirements`），再列出新提取的需求（`new_requirements`），让读者一目了然哪些是已积累的能力、哪些是本次新增的挑战。
+
+每个需求采用"抽象需求 + 具象点"的结构：
+- **抽象需求（abstract）**：概括性的视觉能力描述，如"保持多图人物一致性"
+- **具象点（concrete_points）**：该抽象需求下的具体视觉表现要求，如"白裙轮廓在不同角度下保持一致""发丝细节和耳饰在各图中统一"
+
+```json
+{
+  "content_name": "内容名称（从创作表或文件夹名获取）",
+  "matched_requirements": [
+    {
+      "abstract": "抽象需求描述（与需求库中已有需求匹配）",
+      "concrete_points": [
+        "具象点1：来自需求库的已有要求",
+        "具象点2：本次内容补充的新要求（如有）"
+      ],
+      "priority": "high | medium | low",
+      "db_match_id": "需求库中匹配到的需求 ID",
+      "match_confidence": "exact | partial",
+      "delta_from_db": "与需求库原始需求相比，本次新增或调整的具象点说明（无新增则为 null）",
+      "source_elements": ["制作点名称或亮点名称"],
+      "reasoning": "为什么这是关键制作需求，做不好会怎样"
+    }
+  ],
+  "new_requirements": [
+    {
+      "abstract": "抽象需求描述（需求库中无匹配，从内容描述中新提取）",
+      "concrete_points": [
+        "具象点1：具体的视觉表现要求",
+        "具象点2：具体的视觉表现要求"
+      ],
+      "priority": "high | medium | low",
+      "source_elements": ["制作点名称或亮点名称"],
+      "reasoning": "为什么这是关键制作需求，做不好会怎样"
+    }
+  ]
+}
 ```
-- Researcher 会搜索外部平台并返回调研结果
-- 调研结果可通过 `upload_knowledge` 存入 KnowHub 供后续使用
 
-### 第四步：链式图生图生成（Stage 1）
-严格按 **img_1 → img_2 → img_3 → img_4 → img_5** 的顺序串行生成：
+**分组说明**：
+- `matched_requirements`：通过 `requirement_search` 在需求库中找到了匹配的已有需求。`match_confidence` 标注匹配程度（`exact`=完全匹配，`partial`=部分匹配需补充）。`delta_from_db` 说明本次在已有需求基础上的增量变化
+- `new_requirements`：需求库中无匹配，从内容描述文件中新提取的需求。这些需求后续应考虑入库积累
 
-**img_1（基准图）**：
-```
-agent(task="生成 img_1（基准图）：
-  底图: %features_dir%/character_asset/character_ref_img1.png
-  背景参考: %features_dir%/background_asset/background_green_img1.png
-  调色板参考: %features_dir%/palette_asset/palette_impasto_img1_v2.png
+### 第一步：基于需求问策 Librarian
 
-  底图使用方式：将 character_ref 作为 image_url 传入端到端工具做图生图
-  读取 raw_info 目录下对应的制作表（%input_dir%/raw_info/写生油画__img_1_制作表.json）和通用文件辅助 prompt
+读取 `%output_dir%/requirements.json`，按以下优先级逐层向 Librarian 查询：
 
-  Prompt: [从 pipeline.json 提取]
-  Negative Prompt: [从 pipeline.json 提取]
-  img2img_config: [从 pipeline.json 提取]
+**第一层：查关系表（已有需求 → 关联的工序和案例）**
 
-  此图确立角色基准外观，后续所有图以此为参考锚点。
-  输出保存到: %output_dir%/img_1_restored_v1.png", agent_type="craftsman")
+对 `matched_requirements` 中的需求，优先通过关系表查找已有的工序方案和用户案例：
+```
+ask_knowledge(query="需求[db_match_id]关联的工序方案和用户案例")
 ```
+- 关系表中可能已记录：该需求对应的工具链、参数配置、成功案例
+- 如果关系表有完整的工序 → 直接采纳，无需进一步查询
 
-**img_2 ~ img_5（链式传递）**：每张图的 `chain_from` 字段指向前一张。指派时必须将前一张的生成结果路径传给 Craftsman，说明"此为前序图的生成结果，请保持角色、服装、色调一致"。
+**第二层：查能力和知识**
 
-每张图生成后，立即用 evaluate_image 评估：
+对关系表未覆盖的需求（包括 `new_requirements` 中的新需求），查询相关的能力和通用知识：
 ```
-evaluate_image(requirement_path="%input_dir%/pipeline.json", image_paths="%output_dir%/img_1_restored_v1.png")
+ask_knowledge(query="AI图生图工具实现[抽象需求]的能力和方法，具体要求：[列出concrete_points]")
 ```
-- 评分 ≥ 7 → 通过，进入下一张
-- 评分 < 7 → 分析反馈，问策 Librarian 调整方案，重新派发 Craftsman（输出为 `img_X_restored_v2.png`，版本号递增，不覆盖上一版）
+- 查找 KnowHub 中是否有相关的工具能力评估、技巧总结、参数经验
+- 将抽象需求和具象点一起传入，让 Librarian 给出针对性建议
 
-### 第五步：迭代优化（Stage 2）
-Stage 1 全部完成后，对评分较低的图（<8 分），以 Stage 1 结果为底图再次图生图优化。
+**第三层：标记知识缺口**
 
-### 第六步：跨图一致性检查（Stage 3）
-用 evaluate_image 的多图模式检查所有图（使用每张图的最新版本）：
+经过前两层查询后，汇总哪些需求仍缺乏足够的工序或知识支撑，标记为待调研项，交给第三步处理。
+
+### 第二步：按需调研
+对 Librarian 无法充分覆盖的需求，派发 Researcher 调研：
+```
+agent(task="调研以下制作需求的实现方案和用户案例：
+  [列出知识缺口的需求，包含 abstract + concrete_points]
+  重点关注：实际用户的成功案例、工具选择、参数配置、踩坑经验...", agent_type="researcher")
 ```
-evaluate_image(requirement_path="%input_dir%/pipeline.json", image_paths=["%output_dir%/img_1_restored_v1.png", "%output_dir%/img_2_restored_v1.png", ...])
+- Researcher 会搜索外部平台并返回调研结果
+- **调研结果保存到 `%output_dir%/research_result.json`**，供后续设计执行方案时参考
+- 同时通过 `upload_knowledge` 存入 KnowHub 供跨任务复用
+- 特别关注用户案例中的工序流程，可补充到关系表中
+
+**research_result.json 结构**：
+```json
+{
+  "researched_requirements": [
+    {
+      "abstract": "对应的抽象需求",
+      "findings": [
+        {
+          "type": "workflow | case_study | tool_tip | parameter",
+          "summary": "发现摘要",
+          "source": "来源平台和链接",
+          "detail": "详细内容"
+        }
+      ],
+      "recommended_approach": "综合调研结果后的推荐方案"
+    }
+  ]
+}
+```
+
+### 第三步：设计执行方案（生成 pipeline.json）
+
+综合以下信息，自行设计 `pipeline.json` 并保存到 `%output_dir%/pipeline.json`：
+
+**输入**：
+- `%output_dir%/requirements.json`：制作需求（抽象需求 + 具象点）
+- `%output_dir%/research_result.json`：Researcher 调研结果（工序、案例、工具技巧）
+- `%input_dir%/` 下的制作表 JSON：每张图的详细描述和构图信息
+- `%input_dir%/创作表.md`：整体创作视角
+- `%features_dir%/`：可用素材清单
+- Librarian 返回的工序方案、用户案例、工具能力信息
+
+**设计要点**：
+1. **确定图片顺序和链式关系**：根据制作表中各图的角色、构图关系，决定生成顺序和 chain_from 依赖
+2. **为每张图规划生成配置**：底图选择、参考素材、prompt、negative prompt、img2img 参数（strength 等）
+3. **将需求映射到具体图片**：每个 requirement 的 concrete_points 落实到对应图片的生成配置中
+4. **采纳 Librarian 推荐的工序**：优先使用关系表中已验证的工具链和参数配置
+5. **规划修复项**：根据需求优先级，列出 repair_items（Stage 4 细节修复清单）
+
+**pipeline.json 结构**：
+
+pipeline 是一个有序的 steps 列表，每个 step 对应一个可执行的操作。agent 设计 pipeline 时，应将生成、评估、迭代优化、一致性检查、细节修复等阶段都编排为具体的 step。
+
+```json
+{
+  "content_name": "内容名称",
+  "steps": [
+    {
+      "step_id": "step_1",
+      "type": "generate | evaluate | consistency_check | repair | custom",
+      "description": "该步骤的目标描述",
+      "expected_effect": "该步骤完成后图片应达到的视觉效果描述（具体、可感知）",
+      "checkpoints": [
+        "核心检查点1：可评估的具体标准（如'人物白裙V字露背设计清晰可见'）",
+        "核心检查点2：可评估的具体标准（如'调色板颜料厚度感明显，有立体笔触纹理'）"
+      ],
+      "depends_on": ["前置 step_id，为空则无依赖"],
+      "config": {
+        "// type=generate 时": "",
+        "target": "img_1",
+        "base_image": "%features_dir%/...",
+        "reference_images": ["%features_dir%/..."],
+        "chain_from_step": "null 或前序 generate step_id",
+        "prompt": "生成 prompt",
+        "negative_prompt": "负面 prompt",
+        "img2img_config": { "strength": 0.6 },
+        "mapped_requirements": ["对应的抽象需求"],
+
+        "// type=evaluate 时": "",
+        "target_step": "要评估的 generate step_id",
+        "pass_threshold": 7,
+        "retry_strategy": "问策 Librarian 后重新生成",
+
+        "// type=consistency_check 时": "",
+        "target_steps": ["要对比的多个 generate step_id"],
+        "dimensions": ["character", "clothing", "color", "lighting", "style"],
+
+        "// type=repair 时": "",
+        "target_step": "要修复的 step_id",
+        "repair_items": ["修复项描述"]
+      },
+      "output_path": "%output_dir%/img_1_restored_v1.png"
+    }
+  ],
+  "strategy_source": "工序方案来源说明（Librarian/Researcher/自行设计）"
+}
 ```
-- 对不一致的图，以当前结果为底图重新图生图
-- 如一致性问题严重，问策 Librarian 是否需要调研新的一致性保持技巧
 
-### 第七步：细节修复与输出（Stage 4）
-按 pipeline.json 的 repair_items 逐项检查修复。最终成品保存至 `%output_dir%/`。
+**设计要点**：
+1. **steps 的编排顺序即执行顺序**，通过 `depends_on` 表达依赖关系
+2. **每个 generate step 后通常跟一个 evaluate step**，评估不通过时按 `retry_strategy` 处理
+3. **将需求映射到具体 step**：每个 requirement 的 concrete_points 落实到对应 generate step 的配置中
+4. **采纳 Librarian 推荐的工序**：优先使用关系表中已验证的工具链和参数配置
+5. 设计完成后 review：每个 high priority 需求是否都在至少一个 step 中有体现
+6. **每个 step 必须填写 `expected_effect` 和 `checkpoints`**：`expected_effect` 描述该步骤完成后图片应呈现的视觉效果；`checkpoints` 列出 2-5 个可评估的具体标准，确保 evaluate step 有明确的评判依据。检查点应来自 requirements.json 中对应需求的 concrete_points
+
+### 第四步：按 pipeline 逐步执行
+
+遍历 `%output_dir%/pipeline.json` 中的 `steps`，按顺序逐步执行：
+
+- **generate**：组装该 step 的完整配置，派发 Craftsman 执行。如有 `chain_from_step`，将该前序 step 的最新输出路径一并传入。**必须提醒 Craftsman 读取 `%input_dir%/` 下该图对应的制作表 JSON（如 `写生油画__img_1_制作表.json`），从中提取构图、姿态、道具位置等细节融入 prompt**
+- **evaluate**：调用 evaluate_image 评估目标 step 的输出，**同时对照 `%input_dir%/` 下该图的制作表 JSON 中的具体描述进行逐项检查**（如制作表中描述"左手持调色板"，则检查生成图是否符合）。未达 `pass_threshold` 则按 `retry_strategy` 处理（问策 Librarian → 调整配置 → 重新生成，版本号递增）
+- **consistency_check**：用 evaluate_image 多图模式检查 `target_steps` 的输出一致性。不一致的图重新生成
+- **repair**：按 `repair_items` 逐项修复目标 step 的输出
+- **custom**：按 description 描述的逻辑执行
+
+每个 step 完成后，记录结果到 `%output_dir%/generation_log.md`。
 
 ### 知识回流
 每个阶段完成后，将有价值的经验存入 KnowHub：
@@ -138,8 +307,8 @@ upload_knowledge(data="使用 nano_banana 图生图时，strength=0.6 + 链式
 2. **参考素材路径**（完整路径）
 3. **前序结果路径**（chain_from，如有）
 4. **素材使用方式**：底图 → image_url，参考素材 → 辅助 prompt
-5. **Prompt 和生成配置**
-6. **源信息参考**：提醒 Craftsman 读取 `%input_dir%/raw_info/` 目录下对应图片的制作表 JSON（如 `写生油画__img_1_制作表.json`）和通用文件（`创作表.md`、`图片亮点.md`）
+5. **Prompt 和生成配置**（从 `%output_dir%/pipeline.json` 中对应图片的配置提取）
+6. **源信息参考**：提醒 Craftsman 读取 `%input_dir%/` 目录下对应图片的制作表 JSON（如 `写生油画__img_1_制作表.json`）和通用文件（`创作表.md`、`图片亮点.md`）
 7. **输出路径**
 
 ## 评估原则
@@ -148,7 +317,7 @@ upload_knowledge(data="使用 nano_banana 图生图时，strength=0.6 + 链式
 3. **上限点**：尽力还原，接受次优（评分 ≥ 7）
 
 $user$
-请读取输入目录中的还原方案，开始执行完整的图像还原流程：
+请先从输入目录的内容描述文件中提取制作需求，然后将需求交给 Librarian 调研，最后执行完整的图像还原流程：
 %input_dir%
 
 输出目录：%output_dir%

insert_ai_workflow_capabilities.py

@@ -1,132 +0,0 @@
-#!/usr/bin/env python3
-"""
-插入 AI 创作工作流的 16 个通用能力模块知识条目
-"""
-import os
-import sys
-import json
-import uuid
-from datetime import datetime, timezone
-from pathlib import Path
-
-# 添加项目路径
-sys.path.insert(0, '/root/Agent')
-
-os.environ['OPEN_ROUTER_API_KEY'] = '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'
-os.environ['QWEN_API_KEY'] = 'sk-9453c827b9e14108b53d2b30ef7c75fe'
-os.environ['KNOWHUB_DB'] = 'gp-t4n72471pkmt4b9q7o-master.gpdbmaster.singapore.rds.aliyuncs.com'
-os.environ['KNOWHUB_PORT'] = '5432'
-os.environ['KNOWHUB_USER'] = 'aiddit_aigc'
-os.environ['KNOWHUB_PASSWORD'] = '%a&&yqNxg^V1$toJ*WOa^-b^X=QJ'
-os.environ['KNOWHUB_DB_NAME'] = 'knowhub'
-
-from knowhub.knowhub_db.pg_store import PostgreSQLStore
-from knowhub.embeddings import get_embedding
-
-# 知识数据 - AI 创作工作流的 16 个通用能力模块
-knowledge_data = {
-    "task": "AI 创作工作流的 16 个通用能力模块",
-    "content": """## 能力模块清单
-
-### 素材准备类
-1. **准备参考素材**：收集或生成用于后续创作的参考图像、纹理、角色基础等素材
-2. **生成参考图表**：生成角色参考表、多视角图、多表情图等参考资料
-
-### 角色定义类
-3. **定义角色特征**：设定人物面部特征、表情状态、身份一致性等角色属性
-
-### 场景构建类
-4. **构建场景环境**：创建或合成场景背景、虚拟环境、空间布局
-
-### 视觉控制类
-5. **配置光影效果**：设置光源方向、灯光类型、明暗对比等光照条件
-6. **控制姿态构图**：控制人物姿态、画面构图、视角、摄影参数
-7. **应用风格控制**：应用风格迁移、保持视觉一致性、注入特定美学风格
-8. **处理纹理效果**：添加纹理、颗粒、质感、色调等视觉效果
-9. **创建纹理布局**：创建四方连续、渐变网格、矢量图形等纹理布局
-
-### 生成执行类
-10. **执行内容生成**：执行核心的图像、视频、渲染生成操作
-11. **配置控制技术**：配置 ControlNet、深度图、姿态图等控制条件
-12. **配置工作流**：配置工具节点、构建流程、设置参数
-
-### 后期处理类
-13. **修复细节瑕疵**：对局部区域进行重绘、修复瑕疵、优化细节
-14. **增强图像质量**：提升图像分辨率、质量增强、最终精修
-15. **后期合成处理**：抠图、选区创建、图像合成、图层处理
-16. **视频后期处理**：视频剪辑、颜色分级、特效增强
-
-## 跨品类复用性
-以上模块均从 5 个不同品类的工作流（角色创作、人像精修、肖像摄影、光影控制、纹理设计）中抽象得出，可跨品类复用。""",
-    "types": ["strategy"],
-    "tags": {
-        "domain": "AI 创作",
-        "category": "能力模块",
-        "source": "工作流分析 pipeline"
-    },
-    "score": 5,
-    "source": {"category": "research"}
-}
-
-print("正在连接数据库...")
-store = PostgreSQLStore()
-
-# 生成 ID
-now = datetime.now(timezone.utc)
-knowledge_id = f"knowledge-{now.strftime('%Y%m%d')}-{uuid.uuid4().hex[:8]}"
-message_id = f"msg-{uuid.uuid4().hex[:12]}"
-
-# 生成 embedding
-print("正在生成 embedding...")
-task_embedding = get_embedding(knowledge_data["task"])
-content_embedding = get_embedding(knowledge_data["content"])
-
-# 构建知识记录
-knowledge = {
-    "id": knowledge_id,
-    "message_id": message_id,
-    "task": knowledge_data["task"],
-    "content": knowledge_data["content"],
-    "types": knowledge_data["types"],
-    "tags": knowledge_data["tags"],
-    "tag_keys": list(knowledge_data["tags"].keys()),
-    "scopes": [],
-    "owner": "librarian",
-    "source": knowledge_data["source"],
-    "eval": {"score": knowledge_data["score"]},
-    "created_at": now.isoformat(),
-    "updated_at": now.isoformat(),
-    "status": "approved",
-    "task_embedding": task_embedding,
-    "content_embedding": content_embedding,
-    "requirement_ids": [],
-    "capability_ids": [],
-    "tool_ids": [],
-    "resource_ids": [],
-}
-
-print(f"正在插入知识：{knowledge_id}")
-print(f"  Task: {knowledge['task']}")
-print(f"  Types: {knowledge['types']}")
-print(f"  Tags: {knowledge['tags']}")
-print(f"  Content 长度：{len(knowledge['content'])} 字符")
-
-store.insert(knowledge)
-
-print(f"\n✓ 知识已成功入库!")
-print(f"  ID: {knowledge_id}")
-print(f"  Message ID: {message_id}")
-
-# 验证插入
-retrieved = store.get_by_id(knowledge_id)
-if retrieved:
-    print(f"\n✓ 验证成功：已检索到刚插入的知识")
-    print(f"  Task: {retrieved['task']}")
-    print(f"  Content 长度：{len(retrieved['content'])} 字符")
-    print(f"  Types: {retrieved['types']}")
-    print(f"  Tags: {retrieved['tags']}")
-else:
-    print(f"\n✗ 验证失败：无法检索到刚插入的知识")
-
-store.close()
-print("\n数据库连接已关闭")

insert_knowledge.py

@@ -1,73 +0,0 @@
-#!/usr/bin/env python3
-"""
-插入知识条目到 PostgreSQL 数据库
-"""
-
-import asyncio
-import uuid
-import time
-import sys
-import os
-
-# 添加项目路径
-sys.path.insert(0, '/root/Agent')
-
-from knowhub.knowhub_db.pg_store import PostgreSQLStore
-from knowhub.embeddings import get_embedding
-
-
-async def main():
-    # 知识数据
-    task = "人物近景肖像"
-    content = "生成人物近景半身或胸部以上画面、突出面部表情和情绪、背景虚化的核心工序要素包括：1.近景/半身构图 2.面部表情细节 3.背景虚化效果 4.皮肤质感真实 5.眼神互动感"
-    types = ["strategy"]
-    tags = {"domain": "AI 生图", "source": "多渠调研汇总", "task": "人物近景肖像"}
-    score = 5
-    source = {"category": "research"}
-    
-    # 生成唯一 ID
-    knowledge_id = str(uuid.uuid4())
-    message_id = str(uuid.uuid4())
-    current_time = int(time.time())
-    
-    # 生成 embeddings
-    print(f"正在生成 task embedding...")
-    task_embedding = await get_embedding(task)
-    print(f"正在生成 content embedding...")
-    content_embedding = await get_embedding(content)
-    
-    # 构建知识对象
-    knowledge = {
-        'id': knowledge_id,
-        'message_id': message_id,
-        'task': task,
-        'content': content,
-        'types': types,
-        'tags': tags,
-        'tag_keys': list(tags.keys()),
-        'scopes': ['org:cybertogether'],  # 默认可见范围
-        'owner': 'system',  # 默认所有者
-        'source': source,
-        'eval': {'score': score},
-        'task_embedding': task_embedding,
-        'content_embedding': content_embedding,
-        'created_at': current_time,
-        'updated_at': current_time,
-        'status': 'approved',
-    }
-    
-    # 插入数据库
-    print(f"正在插入知识条目到 PostgreSQL...")
-    store = PostgreSQLStore()
-    store.insert(knowledge)
-    store.close()
-    
-    print(f"成功插入知识条目！")
-    print(f"  ID: {knowledge_id}")
-    print(f"  Task: {task}")
-    print(f"  Types: {types}")
-    print(f"  Score: {score}")
-
-
-if __name__ == '__main__':
-    asyncio.run(main())

insert_knowledge_direct.py

@@ -1,91 +0,0 @@
-import os
-import sys
-import json
-import uuid
-from datetime import datetime, timezone
-from pathlib import Path
-
-# 添加项目路径
-sys.path.insert(0, '/root/Agent')
-
-os.environ['OPEN_ROUTER_API_KEY'] = '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'
-os.environ['QWEN_API_KEY'] = 'sk-9453c827b9e14108b53d2b30ef7c75fe'
-os.environ['KNOWHUB_DB'] = 'gp-t4n72471pkmt4b9q7o-master.gpdbmaster.singapore.rds.aliyuncs.com'
-os.environ['KNOWHUB_PORT'] = '5432'
-os.environ['KNOWHUB_USER'] = 'aiddit_aigc'
-os.environ['KNOWHUB_PASSWORD'] = '%a&&yqNxg^V1$toJ*WOa^-b^X=QJ'
-os.environ['KNOWHUB_DB_NAME'] = 'knowhub'
-
-from knowhub.knowhub_db.pg_store import PostgreSQLStore
-from knowhub.embeddings import get_embedding
-
-# 知识数据
-knowledge_data = {
-    "task": "人物近景肖像",
-    "content": "生成人物近景半身或胸部以上画面、突出面部表情和情绪、背景虚化的核心工序要素包括：\n\n1. **近景/半身构图**：使用 tight medium close-up、extreme close-up、中近景半身等提示词；推荐 85mm 镜头视角；构图比例 2:3 或 9:16（竖版）、3:4（职业照）\n\n2. **面部表情细节**：使用锁脸技术（nano-banana 锁脸功能）、微表情描述（slightly parted lips、calm introspective expression）、多表情生成（3×3 网格生成 9 种表情）；关键提示词：direct steady eye contact、subtle catchlights in eyes\n\n3. **背景虚化效果**：推荐参数 85mm 镜头 + f/1.4-f/1.8 光圈；提示词：shallow depth of field、extremely shallow depth of field、soft bokeh blur、blurring out the neck, ear, and background completely；后期工具：Photoshop Lens Blur、DxO Photolab 9 Bokeh\n\n4. **皮肤质感真实**：避免塑料感的关键提示词：realistic skin texture with visible pores and natural imperfections、no plastic smoothing、dewy smooth texture；修复工具：Enhancor.ai Skin Realism\n\n5. **眼神互动感**：direct eye contact、catchlights in eyes、gentle and engaging eyes、looking directly at the camera",
-    "types": ["strategy"],
-    "tags": {
-        "domain": "AI 生图",
-        "source": "多渠调研汇总",
-        "task": "人物近景肖像"
-    },
-    "score": 5,
-    "source": {"category": "research"}
-}
-
-print("正在连接数据库...")
-store = PostgreSQLStore()
-
-# 生成 ID
-now = datetime.now(timezone.utc)
-knowledge_id = f"knowledge-{now.strftime('%Y%m%d')}-{uuid.uuid4().hex[:8]}"
-message_id = f"msg-{uuid.uuid4().hex[:12]}"
-
-# 生成 embedding
-print("正在生成 embedding...")
-task_embedding = get_embedding(knowledge_data["task"])
-content_embedding = get_embedding(knowledge_data["content"])
-
-# 构建知识记录
-knowledge = {
-    "id": knowledge_id,
-    "message_id": message_id,
-    "task": knowledge_data["task"],
-    "content": knowledge_data["content"],
-    "types": knowledge_data["types"],
-    "tags": knowledge_data["tags"],
-    "tag_keys": list(knowledge_data["tags"].keys()),
-    "scopes": [],
-    "owner": "librarian",
-    "source": knowledge_data["source"],
-    "eval": {"score": knowledge_data["score"]},
-    "created_at": now.isoformat(),
-    "updated_at": now.isoformat(),
-    "status": "approved",
-    "task_embedding": task_embedding,
-    "content_embedding": content_embedding,
-    "requirement_ids": [],
-    "capability_ids": [],
-    "tool_ids": [],
-    "resource_ids": [],
-}
-
-print(f"正在插入知识：{knowledge_id}")
-print(f"  Task: {knowledge['task']}")
-print(f"  Types: {knowledge['types']}")
-print(f"  Tags: {knowledge['tags']}")
-
-store.insert(knowledge)
-
-print(f"\n✓ 知识已成功入库!")
-print(f"  ID: {knowledge_id}")
-print(f"  Message ID: {message_id}")
-
-# 验证插入
-retrieved = store.get_by_id(knowledge_id)
-if retrieved:
-    print(f"\n✓ 验证成功：已检索到刚插入的知识")
-    print(f"  Task: {retrieved['task']}")
-    print(f"  Content 长度：{len(retrieved['content'])} 字符")
-else:
-    print(f"\n✗ 验证失败：无法检索到刚插入的知识")

pending_uploads/knowledge_batch_20260410_file_search.json

@@ -1,28 +0,0 @@
-{
-  "knowledge": [
-    {
-      "task": "在分析工作流文件时，当 glob 搜索找不到目标文件的有效定位策略",
-      "content": "当 glob_files 按模式匹配找不到目标文件时，应该：1) 使用 bash_command 执行 find 命令进行更广泛的文件系统搜索，支持通配符和路径遍历；2) 结合 grep 内容搜索，通过文件内容关键词定位（如工具名、方案名）；3) 检查相关目录结构，如 research/outputs/ 下的子目录。案例：本次任务中 glob_files 搜索\"*wf_005*\"未找到文件，但通过 find 命令搜索包含\"ComfyUI\"\"Nano Banana\"等关键词的 markdown 文件，成功在 outputs/04/ 目录下找到颗粒感纸张纹理插画风格工作流调研报告.md，该文件即为 wf_005 的 raw_markdown 内容。",
-      "types": ["experience"],
-      "tags": {
-        "intent": "工作流文件定位",
-        "state": "文件搜索",
-        "tools": "glob_files,bash_command"
-      },
-      "score": 4,
-      "source": {"category": "research"}
-    },
-    {
-      "task": "工作流意图归纳的粒度判断原则",
-      "content": "在将工作流技术步骤归纳为意图级描述时，粒度判断应遵循：1) 保留工具差异——相同意图但不同工具实现应分开记录，因为工具选择是工作流变体的关键信息；2) 合并连续子步骤——同一工具内的连续操作（如新建图层→填充→设置混合模式）可合并为一个意图；3) 跨方案可比较——意图描述应使不同工作流的相同功能模块可对比。案例：本次将 Photoshop 的 5 种颗粒添加方法分别记录为\"添加溶解颗粒效果\"\"手绘颗粒纹理\"\"滤镜添加全局杂色\"等，保留了方法差异；而将 ComfyUI 的分割 + 重排合并为\"创建四方连续布局\"。",
-      "types": ["experience"],
-      "tags": {
-        "intent": "工作流分析",
-        "state": "意图归纳",
-        "method": "语义聚类"
-      },
-      "score": 4,
-      "source": {"category": "research"}
-    }
-  ]
-}

process_upload.py

@@ -1,69 +0,0 @@
-#!/usr/bin/env python3
-"""
-处理上传的知识条目并添加到 pre_upload_list.json
-"""
-import json
-import uuid
-import time
-
-# 读取现有文件
-with open('/root/Agent/pre_upload_list.json', 'r', encoding='utf-8') as f:
-    data = json.load(f)
-
-# 用户上传的 3 条知识
-new_knowledge = [
-    {
-        "主题": "在调用 ToolHub nano_banana 工具时，图片传递需要手动上传到 OSS 获取 CDN URL",
-        "内容": "当使用 ToolHub 的 nano_banana 工具进行图像生成时，不能直接传本地文件路径（如 examples/xxx/image.png），因为 ToolHub 服务运行在远程服务器上，无法访问调用方的本地文件系统。\n\n正确做法：\n1. 先调用 image_uploader 工具将本地图片上传到 OSS\n2. 获取返回的 cdn_url（如 https://res.cybertogether.net/toolhub_images/xxx.png）\n3. 将 cdn_url 传入 toolhub_call 的 image_urls 参数\n\n案例：生成 img_3 时，最初直接传本地路径 character_ref_kneel.png 导致 HTTP 503 错误「文件不存在」，改用 image_uploader 上传后获取 CDN URL 再调用 nano_banana 成功生成。\n\n注意：虽然部分 ToolHub 工具文档声称支持自动上传本地路径，但 nano_banana 实际不支持此功能，需手动处理。",
-        "类型": ["experience"],
-        "标签": {"intent": "图像生成", "state": "nano_banana", "tool": "toolhub_call"},
-        "评分": 5,
-        "source": {"category": "execution"}
-    },
-    {
-        "主题": "在图像生成任务中，使用 nano_banana 进行多图融合保持人物一致性的方法",
-        "内容": "当需要保持多张生成图的人物一致性时（如系列图 img_1~img_5），使用 nano_banana 工具的多图融合功能：\n\n1. 在 image_urls 数组中传入多张参考图：\n   - 底图（当前姿态的 character_ref_*.png）\n   - 前序生成结果（如 img_1_restored_v1.png 用于链式一致性）\n2. 在 prompt 中明确描述需要保持的特征（如 white V-neck backless maxi dress, brown long hair）\n3. 使用 aspect_ratio 参数控制输出比例（如 3:4）\n\n案例：img_3 生成时传入 character_ref_kneel.png（跪坐姿态底图）和 img_1_restored_v1.png（前序结果），成功保持了白裙款式、发型、体态的一致性，评估得分 8.5/10。\n\n优势：nano_banana 基于 Gemini 多模态模型，对多图特征融合理解能力强，比传统 IP-Adapter 更灵活。",
-        "类型": ["experience"],
-        "标签": {"intent": "人物一致性", "state": "nano_banana", "technique": "多图融合"},
-        "评分": 4,
-        "source": {"category": "execution"}
-    },
-    {
-        "主题": "图像生成任务的标准化执行流程",
-        "内容": "完整的图像生成任务应遵循以下流程：\n\n1. **素材验证**：使用 read_file 检查所有参考素材文件存在且可读\n2. **源信息读取**：读取制作表 JSON 和通用创作文件，提取细节描述融入 prompt\n3. **ToolHub 检查**：调用 toolhub_health 确认服务可用，toolhub_search 查找合适工具\n4. **图片上传**：使用 image_uploader 将本地图片转为 CDN URL\n5. **执行生成**：调用 toolhub_call 执行生成，记录完整参数\n6. **结果验证**：使用 evaluate_image 进行自动化评估（单图 6 维度/多图 5 维度一致性）\n7. **日志记录**：追加 generation_log.md，包含素材验证、生成参数、验证结果、评估详情\n\n案例：img_3 任务按此流程执行，从素材验证到日志记录全程可追溯，评估 8.5/10 通过。\n\n关键点：每次生成都必须记录完整参数便于迭代优化；评估结果低于 7 分需调整配置重新生成。",
-        "类型": ["experience"],
-        "标签": {"intent": "图像生成流程", "state": "workflow", "domain": "production"},
-        "评分": 4,
-        "source": {"category": "execution"}
-    }
-]
-
-# 转换为标准格式并添加
-current_time = int(time.time())
-timestamp = time.strftime("%Y%m%d-%H%M%S", time.localtime(current_time))
-
-for i, item in enumerate(new_knowledge):
-    # 生成唯一 ID
-    knowledge_id = f"knowledge-{timestamp}-{uuid.uuid4().hex[:4]}"
-    
-    # 转换为标准格式
-    standard_knowledge = {
-        "id": knowledge_id,
-        "task": item["主题"],
-        "content": item["内容"],
-        "types": item["类型"],
-        "tags": item["标签"],
-        "score": item["评分"],
-        "source": item["source"]
-    }
-    
-    data['knowledge'].append(standard_knowledge)
-    print(f"添加知识 {i+1}: {knowledge_id}")
-    print(f"  主题：{item['主题'][:50]}...")
-
-# 写回文件
-with open('/root/Agent/pre_upload_list.json', 'w', encoding='utf-8') as f:
-    json.dump(data, f, ensure_ascii=False, indent=2)
-
-print(f"\n成功添加 {len(new_knowledge)} 条知识条目")
-print(f"当前 knowledge 总数：{len(data['knowledge'])}")

test_upload.py

@@ -1,72 +0,0 @@
-#!/usr/bin/env python3
-"""
-测试知识上传脚本
-"""
-import sys
-import os
-import uuid
-import time
-from datetime import datetime, timezone
-
-sys.path.insert(0, '/root/Agent')
-
-# 设置环境变量
-os.environ['KNOWHUB_DB'] = 'gp-t4n72471pkmt4b9q7o-master.gpdbmaster.singapore.rds.aliyuncs.com'
-os.environ['KNOWHUB_PORT'] = '5432'
-os.environ['KNOWHUB_USER'] = 'aiddit_aigc'
-os.environ['KNOWHUB_PASSWORD'] = '%a&&yqNxg^V1$toJ*WOa^-b^X=QJ'
-os.environ['KNOWHUB_DB_NAME'] = 'knowhub'
-
-from knowhub.knowhub_db.pg_store import PostgreSQLStore
-from knowhub.embeddings import get_embedding
-
-# 测试知识数据
-knowledge_data = {
-    'task': '接口测试验证条目',
-    'content': '这是一条用于验证 upload 接口是否可用的测试知识，可以删除。',
-    'types': ['experience'],
-    'tags': {'source': 'api_test'},
-    'score': 1
-}
-
-print('正在连接数据库...')
-store = PostgreSQLStore()
-
-# 生成 ID
-now = datetime.now(timezone.utc)
-knowledge_id = f'knowledge-{now.strftime("%Y%m%d")}-{uuid.uuid4().hex[:8]}'
-message_id = f'msg-{uuid.uuid4().hex[:12]}'
-
-# 生成 embedding
-print('正在生成 embedding...')
-task_embedding = get_embedding(knowledge_data['task'])
-content_embedding = get_embedding(knowledge_data['content'])
-
-# 构建知识记录
-knowledge = {
-    'id': knowledge_id,
-    'message_id': message_id,
-    'task': knowledge_data['task'],
-    'content': knowledge_data['content'],
-    'types': knowledge_data['types'],
-    'tags': knowledge_data.get('tags', {}),
-    'tag_keys': list(knowledge_data.get('tags', {}).keys()),
-    'scopes': ['org:cybertogether'],
-    'owner': 'system',
-    'source': {'category': 'execution'},
-    'eval': {'score': knowledge_data.get('score', 3)},
-    'task_embedding': task_embedding,
-    'content_embedding': content_embedding,
-    'created_at': int(time.time()),
-    'updated_at': int(time.time()),
-    'status': 'approved',
-}
-
-print(f'正在插入知识条目...')
-store.insert(knowledge)
-store.close()
-
-print(f'✅ 成功插入知识条目！')
-print(f'  ID: {knowledge_id}')
-print(f'  Task: {knowledge_data["task"]}')
-print(f'  Types: {knowledge_data["types"]}')

test_upload_sync.py

@@ -1,80 +0,0 @@
-#!/usr/bin/env python3
-"""
-测试知识上传脚本（同步版本）
-"""
-import sys
-import os
-import uuid
-import time
-import asyncio
-from datetime import datetime, timezone
-
-sys.path.insert(0, '/root/Agent')
-
-# 设置环境变量
-os.environ['KNOWHUB_DB'] = 'gp-t4n72471pkmt4b9q7o-master.gpdbmaster.singapore.rds.aliyuncs.com'
-os.environ['KNOWHUB_PORT'] = '5432'
-os.environ['KNOWHUB_USER'] = 'aiddit_aigc'
-os.environ['KNOWHUB_PASSWORD'] = '%a&&yqNxg^V1$toJ*WOa^-b^X=QJ'
-os.environ['KNOWHUB_DB_NAME'] = 'knowhub'
-
-from knowhub.knowhub_db.pg_store import PostgreSQLStore
-from knowhub.embeddings import get_embedding
-
-# 测试知识数据
-knowledge_data = {
-    'task': '接口测试验证条目',
-    'content': '这是一条用于验证 upload 接口是否可用的测试知识，可以删除。',
-    'types': ['experience'],
-    'tags': {'source': 'api_test'},
-    'score': 1
-}
-
-async def main():
-    print('正在连接数据库...')
-    store = PostgreSQLStore()
-
-    # 生成 ID
-    now = datetime.now(timezone.utc)
-    knowledge_id = f'knowledge-{now.strftime("%Y%m%d")}-{uuid.uuid4().hex[:8]}'
-    message_id = f'msg-{uuid.uuid4().hex[:12]}'
-
-    # 生成 embedding
-    print('正在生成 embedding...')
-    task_embedding = await get_embedding(knowledge_data['task'])
-    content_embedding = await get_embedding(knowledge_data['content'])
-
-    # 构建知识记录
-    knowledge = {
-        'id': knowledge_id,
-        'message_id': message_id,
-        'task': knowledge_data['task'],
-        'content': knowledge_data['content'],
-        'types': knowledge_data['types'],
-        'tags': knowledge_data.get('tags', {}),
-        'tag_keys': list(knowledge_data.get('tags', {}).keys()),
-        'scopes': ['org:cybertogether'],
-        'owner': 'system',
-        'source': {'category': 'execution'},
-        'eval': {'score': knowledge_data.get('score', 3)},
-        'task_embedding': task_embedding,
-        'content_embedding': content_embedding,
-        'created_at': int(time.time()),
-        'updated_at': int(time.time()),
-        'status': 'approved',
-    }
-
-    print(f'正在插入知识条目...')
-    store.insert(knowledge)
-    store.close()
-
-    print(f'✅ 成功插入知识条目！')
-    print(f'  ID: {knowledge_id}')
-    print(f'  Task: {knowledge_data["task"]}')
-    print(f'  Types: {knowledge_data["types"]}')
-    
-    return knowledge_id
-
-if __name__ == '__main__':
-    knowledge_id = asyncio.run(main())
-    print(f'\n最终知识 ID: {knowledge_id}')