better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/developer-guide/session-storage.md

@@ -0,0 +1,420 @@
+# 会话存储
+
+Hermes Agent 使用 SQLite 数据库（`~/.hermes/state.db`）跨 CLI 和 gateway 会话持久化会话元数据、完整消息历史及模型配置。这替代了早期的逐会话 JSONL 文件方案。
+
+源文件：`hermes_state.py`
+
+## Hermes home 与 profile 隔离
+
+`get_hermes_home()` 是状态与配置的权威文件系统解析器。它依次使用上下文本地覆盖、`HERMES_HOME`
+环境变量，最后才是平台默认值（macOS 和 Linux 上为 `~/.hermes`；Windows 上为
+`%LOCALAPPDATA%/hermes`）。因此默认数据库始终是 `get_hermes_home() / "state.db"`，
+调用方不应硬编码 `~/.hermes/state.db`。
+
+命名 profile 是相互隔离的目录：例如名为 `coder` 的 profile 使用
+`<默认 Hermes 根目录>/profiles/coder/`，拥有自己的 `state.db`、配置、日志和其他 profile 级状态。
+为某个 profile 创建数据库、读取配置或启动子进程的进程必须保留或传递该 profile 的
+`HERMES_HOME`；回退到默认根目录会把错误 profile 的状态混入操作中。
+
+CLI 启动流程在导入 Hermes 其余部分之前调用 `_apply_profile_override()`。显式的
+`--profile`/`-p` 会解析该 profile 并把解析后的目录写入 `HERMES_HOME`。没有显式选择器时，
+指向 profile 的 `HERMES_HOME` 会被保留；否则启动流程可以使用默认根目录中的 active-profile
+选择。`HOME` 只决定在没有上下文覆盖和 `HERMES_HOME` 时使用的平台默认值，修改 `HOME`
+不是选择命名 profile 的安全方式。特别地，丢弃了 `HERMES_HOME` 的子进程即使在另一个 profile
+处于激活状态时也可能回退到默认 profile，因此子进程的启动方应显式传递 `HERMES_HOME`。
+
+`display_hermes_home()` 仅用于面向用户的文本：它在可能时把解析出的 home 格式化为相对用户主目录
+的形式（例如 `~/.hermes/profiles/coder`），并不提供另一套解析规则。
+
+### 测试隔离守卫
+
+测试必须使用临时 `HERMES_HOME` 或显式的临时数据库路径。实时系统守卫会在测试上下文进程打开
+真实默认 Hermes 根目录或真实命名 profile 下的生产 `state.db` 之前抛出异常，防止 fixture 数据或
+SQLite 副作用触及正在使用的安装。
+
+`HERMES_STATE_DB_GUARD_BYPASS=1` 是仅供测试使用的逃生口，用于确实必须访问实时数据库的派生子进程。
+进程内的等价逃生口是 `@pytest.mark.live_system_guard_bypass`。不要在普通 Hermes 命令、开发 shell
+或应用配置中设置任一绕过：它会禁用保护实时会话历史的守卫（一个硬性的 `RuntimeError`），而导出了
+它的 shell 会把该绕过传给之后的每一次 pytest 运行。
+
+
+## 架构概览
+
+```
+~/.hermes/state.db (SQLite, WAL mode)
+├── sessions              — 会话元数据、token 计数、计费信息
+├── messages              — 每个会话的完整消息历史
+├── messages_fts          — FTS5 虚拟表（content + tool_name + tool_calls）
+├── messages_fts_trigram  — 使用 trigram tokenizer 的 FTS5 虚拟表（CJK / 子串搜索）
+├── state_meta            — 键值元数据表
+└── schema_version        — 单行表，跟踪迁移状态
+```
+
+关键设计决策：
+- **WAL 模式**：支持并发读取 + 单写入（gateway 多平台）
+- **FTS5 虚拟表**：跨所有会话消息的快速全文搜索
+- **会话血缘**：通过 `parent_session_id` 链实现（压缩触发的会话分割）
+- **来源标记**（`cli`、`telegram`、`discord` 等）：用于平台过滤
+- 批量运行器和 RL 轨迹不存储于此（独立系统）
+
+
+## SQLite Schema
+
+### Sessions 表
+
+```sql
+CREATE TABLE IF NOT EXISTS sessions (
+    id TEXT PRIMARY KEY,
+    source TEXT NOT NULL,
+    user_id TEXT,
+    model TEXT,
+    model_config TEXT,
+    system_prompt TEXT,
+    parent_session_id TEXT,
+    started_at REAL NOT NULL,
+    ended_at REAL,
+    end_reason TEXT,
+    message_count INTEGER DEFAULT 0,
+    tool_call_count INTEGER DEFAULT 0,
+    input_tokens INTEGER DEFAULT 0,
+    output_tokens INTEGER DEFAULT 0,
+    cache_read_tokens INTEGER DEFAULT 0,
+    cache_write_tokens INTEGER DEFAULT 0,
+    reasoning_tokens INTEGER DEFAULT 0,
+    billing_provider TEXT,
+    billing_base_url TEXT,
+    billing_mode TEXT,
+    estimated_cost_usd REAL,
+    actual_cost_usd REAL,
+    cost_status TEXT,
+    cost_source TEXT,
+    pricing_version TEXT,
+    title TEXT,
+    api_call_count INTEGER DEFAULT 0,
+    FOREIGN KEY (parent_session_id) REFERENCES sessions(id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_source ON sessions(source);
+CREATE INDEX IF NOT EXISTS idx_sessions_parent ON sessions(parent_session_id);
+CREATE INDEX IF NOT EXISTS idx_sessions_started ON sessions(started_at DESC);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_sessions_title_unique
+    ON sessions(title) WHERE title IS NOT NULL;
+```
+
+### Messages 表
+
+```sql
+CREATE TABLE IF NOT EXISTS messages (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT NOT NULL REFERENCES sessions(id),
+    role TEXT NOT NULL,
+    content TEXT,
+    tool_call_id TEXT,
+    tool_calls TEXT,
+    tool_name TEXT,
+    timestamp REAL NOT NULL,
+    token_count INTEGER,
+    finish_reason TEXT,
+    reasoning TEXT,
+    reasoning_content TEXT,
+    reasoning_details TEXT,
+    codex_reasoning_items TEXT,
+    codex_message_items TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_messages_session ON messages(session_id, timestamp);
+CREATE INDEX IF NOT EXISTS idx_messages_session_id ON messages(session_id, id);
+```
+
+说明：
+- `tool_calls` 以 JSON 字符串存储（序列化的 tool call 对象列表）
+- `reasoning_details`、`codex_reasoning_items` 和 `codex_message_items` 以 JSON 字符串存储
+- `reasoning` 存储提供商暴露的原始推理文本
+- 时间戳为 Unix epoch 浮点数（`time.time()`）
+
+### FTS5 全文搜索
+
+```sql
+CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(
+    content,
+    content=messages,
+    content_rowid=id
+);
+```
+
+FTS5 表通过三个触发器与 `messages` 表保持同步，分别在 INSERT、UPDATE 和 DELETE 时触发：
+
+```sql
+CREATE TRIGGER IF NOT EXISTS messages_fts_insert AFTER INSERT ON messages BEGIN
+    INSERT INTO messages_fts(rowid, content) VALUES (new.id, new.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS messages_fts_delete AFTER DELETE ON messages BEGIN
+    INSERT INTO messages_fts(messages_fts, rowid, content)
+        VALUES('delete', old.id, old.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS messages_fts_update AFTER UPDATE ON messages BEGIN
+    INSERT INTO messages_fts(messages_fts, rowid, content)
+        VALUES('delete', old.id, old.content);
+    INSERT INTO messages_fts(rowid, content) VALUES (new.id, new.content);
+END;
+```
+
+
+## Schema 版本与迁移
+
+当前 schema 版本：**11**
+
+`schema_version` 表存储单个整数。简单的列添加由 `_reconcile_columns()` 声明式处理（对比实时列与 `SCHEMA_SQL` 并 ADD 缺失列）。版本门控链保留用于无法声明式表达的数据迁移及索引/FTS 变更：
+
+| 版本 | 变更 |
+|------|------|
+| 1 | 初始 schema（sessions、messages、FTS5） |
+| 2 | 向 messages 添加 `finish_reason` 列 |
+| 3 | 向 sessions 添加 `title` 列 |
+| 4 | 在 `title` 上添加唯一索引（允许 NULL，非 NULL 必须唯一） |
+| 5 | 添加计费列：`cache_read_tokens`、`cache_write_tokens`、`reasoning_tokens`、`billing_provider`、`billing_base_url`、`billing_mode`、`estimated_cost_usd`、`actual_cost_usd`、`cost_status`、`cost_source`、`pricing_version` |
+| 6 | 向 messages 添加推理列：`reasoning`、`reasoning_details`、`codex_reasoning_items` |
+| 7 | 向 messages 添加 `reasoning_content` 列 |
+| 8 | 向 sessions 添加 `api_call_count` 列 |
+| 9 | 向 messages 添加 `codex_message_items` 列，用于 Codex Responses 消息 id/phase 重放 |
+| 10 | 添加 `messages_fts_trigram` 虚拟表（trigram tokenizer，用于 CJK / 子串搜索）并回填现有行 |
+| 11 | 重新索引 `messages_fts` 和 `messages_fts_trigram` 以覆盖 `tool_name` + `tool_calls`，从外部内容模式切换为内联模式；删除旧触发器并回填所有消息行 |
+
+声明式列添加使用 `ALTER TABLE ADD COLUMN`，包裹在 try/except 中以处理列已存在的情况（幂等）。每个成功的迁移块完成后版本号递增。
+
+
+## 写入竞争处理
+
+多个 hermes 进程（gateway + CLI 会话 + worktree agent）共享同一个 `state.db`。`SessionDB` 类通过以下方式处理写入竞争：
+
+- **短 SQLite 超时**（1 秒），而非默认的 30 秒
+- **应用层重试**，带随机抖动（20–150ms，最多 15 次重试）
+- **BEGIN IMMEDIATE** 事务，在事务开始时暴露锁竞争
+- **定期 WAL checkpoint**，每 50 次成功写入执行一次（PASSIVE 模式）
+
+这避免了"护卫效应"——SQLite 确定性内部退避会导致所有竞争写入者在相同间隔重试。
+
+```
+_WRITE_MAX_RETRIES = 15
+_WRITE_RETRY_MIN_S = 0.020   # 20ms
+_WRITE_RETRY_MAX_S = 0.150   # 150ms
+_CHECKPOINT_EVERY_N_WRITES = 50
+```
+
+
+## 常用操作
+
+### 初始化
+
+```python
+from hermes_state import SessionDB
+
+db = SessionDB()                           # 默认：~/.hermes/state.db
+db = SessionDB(db_path=Path("/tmp/test.db"))  # 自定义路径
+```
+
+### 创建和管理会话
+
+```python
+# 创建新会话
+db.create_session(
+    session_id="sess_abc123",
+    source="cli",
+    model="anthropic/claude-sonnet-4.6",
+    user_id="user_1",
+    parent_session_id=None,  # 或用于血缘追踪的上一个会话 ID
+)
+
+# 结束会话
+db.end_session("sess_abc123", end_reason="user_exit")
+
+# 重新打开会话（清除 ended_at/end_reason）
+db.reopen_session("sess_abc123")
+```
+
+### 存储消息
+
+```python
+msg_id = db.append_message(
+    session_id="sess_abc123",
+    role="assistant",
+    content="Here's the answer...",
+    tool_calls=[{"id": "call_1", "function": {"name": "terminal", "arguments": "{}"}}],
+    token_count=150,
+    finish_reason="stop",
+    reasoning="Let me think about this...",
+)
+```
+
+### 检索消息
+
+```python
+# 包含所有元数据的原始消息
+messages = db.get_messages("sess_abc123")
+
+# OpenAI 对话格式（用于 API 重放）
+conversation = db.get_messages_as_conversation("sess_abc123")
+# 返回：[{"role": "user", "content": "..."}, {"role": "assistant", ...}]
+```
+
+### 会话标题
+
+```python
+# 设置标题（非 NULL 标题中必须唯一）
+db.set_session_title("sess_abc123", "Fix Docker Build")
+
+# 按标题解析（返回血缘中最新的）
+session_id = db.resolve_session_by_title("Fix Docker Build")
+
+# 自动生成血缘中的下一个标题
+next_title = db.get_next_title_in_lineage("Fix Docker Build")
+# 返回："Fix Docker Build #2"
+```
+
+
+## 全文搜索
+
+`search_messages()` 方法支持 FTS5 查询语法，并自动对用户输入进行清理。
+
+### 基本搜索
+
+```python
+results = db.search_messages("docker deployment")
+```
+
+### FTS5 查询语法
+
+| 语法 | 示例 | 含义 |
+|------|------|------|
+| 关键词 | `docker deployment` | 两个词均包含（隐式 AND） |
+| 引号短语 | `"exact phrase"` | 精确短语匹配 |
+| 布尔 OR | `docker OR kubernetes` | 任一词 |
+| 布尔 NOT | `python NOT java` | 排除词 |
+| 前缀 | `deploy*` | 前缀匹配 |
+
+### 过滤搜索
+
+```python
+# 仅搜索 CLI 会话
+results = db.search_messages("error", source_filter=["cli"])
+
+# 排除 gateway 会话
+results = db.search_messages("bug", exclude_sources=["telegram", "discord"])
+
+# 仅搜索用户消息
+results = db.search_messages("help", role_filter=["user"])
+```
+
+### 搜索结果格式
+
+每条结果包含：
+- `id`、`session_id`、`role`、`timestamp`
+- `snippet` — FTS5 生成的片段，带 `>>>match<<<` 标记
+- `context` — 匹配前后各 1 条消息（内容截断至 200 字符）
+- `source`、`model`、`session_started` — 来自父会话
+
+`_sanitize_fts5_query()` 方法处理边缘情况：
+- 去除不匹配的引号和特殊字符
+- 将含连字符的词包裹在引号中（`chat-send` → `"chat-send"`）
+- 移除悬空的布尔运算符（`hello AND` → `hello`）
+
+
+## 会话血缘
+
+会话可通过 `parent_session_id` 形成链。这发生在 gateway 中上下文压缩触发会话分割时。
+
+### 查询：查找会话血缘
+
+```sql
+-- 查找会话的所有祖先
+WITH RECURSIVE lineage AS (
+    SELECT * FROM sessions WHERE id = ?
+    UNION ALL
+    SELECT s.* FROM sessions s
+    JOIN lineage l ON s.id = l.parent_session_id
+)
+SELECT id, title, started_at, parent_session_id FROM lineage;
+
+-- 查找会话的所有后代
+WITH RECURSIVE descendants AS (
+    SELECT * FROM sessions WHERE id = ?
+    UNION ALL
+    SELECT s.* FROM sessions s
+    JOIN descendants d ON s.parent_session_id = d.id
+)
+SELECT id, title, started_at FROM descendants;
+```
+
+### 查询：带预览的最近会话
+
+```sql
+SELECT s.*,
+    COALESCE(
+        (SELECT SUBSTR(m.content, 1, 63)
+         FROM messages m
+         WHERE m.session_id = s.id AND m.role = 'user' AND m.content IS NOT NULL
+         ORDER BY m.timestamp, m.id LIMIT 1),
+        ''
+    ) AS preview,
+    COALESCE(
+        (SELECT MAX(m2.timestamp) FROM messages m2 WHERE m2.session_id = s.id),
+        s.started_at
+    ) AS last_active
+FROM sessions s
+ORDER BY s.started_at DESC
+LIMIT 20;
+```
+
+### 查询：Token 使用统计
+
+```sql
+-- 按模型统计总 token 数
+SELECT model,
+       COUNT(*) as session_count,
+       SUM(input_tokens) as total_input,
+       SUM(output_tokens) as total_output,
+       SUM(estimated_cost_usd) as total_cost
+FROM sessions
+WHERE model IS NOT NULL
+GROUP BY model
+ORDER BY total_cost DESC;
+
+-- token 使用量最高的会话
+SELECT id, title, model, input_tokens + output_tokens AS total_tokens,
+       estimated_cost_usd
+FROM sessions
+ORDER BY total_tokens DESC
+LIMIT 10;
+```
+
+
+## 导出与清理
+
+```python
+# 导出单个会话及其消息
+data = db.export_session("sess_abc123")
+
+# 导出所有会话（含消息）为字典列表
+all_data = db.export_all(source="cli")
+
+# 删除旧会话（仅删除已结束的会话）
+deleted_count = db.prune_sessions(older_than_days=90)
+deleted_count = db.prune_sessions(older_than_days=30, source="telegram")
+
+# 清除消息但保留会话记录
+db.clear_messages("sess_abc123")
+
+# 删除会话及所有消息
+db.delete_session("sess_abc123")
+```
+
+
+## 数据库位置
+
+默认路径：`~/.hermes/state.db`
+
+该路径由 `hermes_constants.get_hermes_home()` 推导，默认解析为 `~/.hermes/`，或 `HERMES_HOME` 环境变量的值。
+
+数据库文件、WAL 文件（`state.db-wal`）和共享内存文件（`state.db-shm`）均创建于同一目录。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/developer-guide/tools-runtime.md

@@ -0,0 +1,236 @@
+---
+sidebar_position: 9
+title: "工具运行时"
+description: "工具注册表、toolset、调度及终端环境的运行时行为"
+---
+
+# 工具运行时
+
+Hermes 工具是自注册函数，按 toolset（工具集）分组，并通过中央注册表/调度系统执行。
+
+主要文件：
+
+- `tools/registry.py`
+- `model_tools.py`
+- `toolsets.py`
+- `tools/terminal_tool.py`
+- `tools/environments/*`
+
+## 工具注册模型
+
+每个工具模块在导入时调用 `registry.register(...)`。
+
+`model_tools.py` 负责导入/发现工具模块，并构建供模型使用的 schema 列表。
+
+### `registry.register()` 的工作原理
+
+`tools/` 中的每个工具文件在模块级别调用 `registry.register()` 来声明自身。函数签名如下：
+
+```python
+registry.register(
+    name="terminal",               # 唯一工具名称（用于 API schema）
+    toolset="terminal",            # 该工具所属的 toolset
+    schema={...},                  # 面向模型的 schema（描述、参数）
+    handler=handle_terminal,       # 工具被调用时执行的函数
+    check_fn=check_terminal,       # 可选：返回 True/False 表示是否可用
+    requires_env=["SOME_VAR"],     # 可选：所需的环境变量（用于 UI 显示）
+    is_async=False,                # handler 是否为异步协程
+    description="Run commands",    # 可选的 ToolEntry 注册表元数据
+    emoji="💻",                    # 用于 spinner/进度显示的 emoji
+)
+```
+
+每次调用都会创建一个 `ToolEntry`，以工具名称为键存储在单例 `ToolRegistry._tools` 字典中。若不同 toolset 之间出现名称冲突，会记录警告，后注册的条目覆盖前者。
+
+`schema["description"]` 是面向模型的权威描述。独立的 `description=` 参数用于填充 `ToolEntry.description`；省略该参数时，注册表元数据会回退到 schema 中的描述。`get_definitions()` 根据 `entry.schema` 构建 OpenAI function definition，并不会在 schema 缺少 `description` 时把 `entry.description` 复制进去。因此，只提供 `description=` 不会向模型描述该工具；如果两个值不同，模型看到的是 schema 中的值。除非某个注册表消费者确实需要不同的元数据，否则应只在 schema 中定义一次描述。
+
+### 发现机制：`discover_builtin_tools()`
+
+当 `model_tools.py` 被导入时，会调用 `tools/registry.py` 中的 `discover_builtin_tools()`。该函数使用 AST 解析扫描所有 `tools/*.py` 文件，找出包含顶层 `registry.register()` 调用的模块，然后导入它们：
+
+```python
+# tools/registry.py（简化版）
+def discover_builtin_tools(tools_dir=None):
+    tools_path = Path(tools_dir) if tools_dir else Path(__file__).parent
+    for path in sorted(tools_path.glob("*.py")):
+        if path.name in {"__init__.py", "registry.py", "mcp_tool.py"}:
+            continue
+        if _module_registers_tools(path):  # AST 检查顶层 registry.register()
+            importlib.import_module(f"tools.{path.stem}")
+```
+
+这种自动发现机制意味着新工具文件会被自动识别——无需手动维护列表。AST 检查只匹配顶层的 `registry.register()` 调用（不匹配函数内部的调用），因此 `tools/` 中的辅助模块不会被导入。
+
+每次导入都会触发模块的 `registry.register()` 调用。可选工具中的错误（例如图像生成工具缺少 `fal_client`）会被捕获并记录——不会阻止其他工具加载。
+
+核心工具发现完成后，还会发现 MCP 工具和插件工具：
+
+1. **MCP 工具** — `tools.mcp_tool.discover_mcp_tools()` 读取 MCP 服务器配置，并注册来自外部服务器的工具。
+2. **插件工具** — `hermes_cli.plugins.discover_plugins()` 加载用户/项目/pip 插件，这些插件可能注册额外的工具。
+
+## 工具可用性检查（`check_fn`）
+
+每个工具可以选择性地提供一个 `check_fn`——一个可调用对象，在工具可用时返回 `True`，否则返回 `False`。典型的检查包括：
+
+- **API 密钥是否存在** — 例如，`lambda: bool(os.environ.get("SERP_API_KEY"))` 用于网络搜索
+- **服务是否运行** — 例如，检查 Honcho 服务器是否已配置
+- **二进制文件是否已安装** — 例如，验证浏览器工具的 `playwright` 是否可用
+
+当 `registry.get_definitions()` 为模型构建 schema 列表时，会运行每个工具的 `check_fn()`：
+
+```python
+# 简化自 registry.py
+if entry.check_fn:
+    try:
+        available = bool(entry.check_fn())
+    except Exception:
+        available = False   # 异常 = 不可用
+    if not available:
+        continue            # 完全跳过该工具
+```
+
+关键行为：
+- 检查结果**按调用缓存**——若多个工具共享同一个 `check_fn`，只运行一次。
+- `check_fn()` 中的异常被视为"不可用"（故障安全）。
+- `is_toolset_available()` 方法检查某个 toolset 的 `check_fn` 是否通过，用于 UI 显示和 toolset 解析。
+
+## Toolset 解析
+
+Toolset 是工具的命名集合。Hermes 通过以下方式解析它们：
+
+- 显式启用/禁用的 toolset 列表
+- 平台预设（`hermes-cli`、`hermes-telegram` 等）
+- 动态 MCP toolset
+- 精选的特殊用途集合，如 `hermes-acp`
+
+### `get_tool_definitions()` 如何过滤工具
+
+主入口点为 `model_tools.get_tool_definitions(enabled_toolsets, disabled_toolsets, quiet_mode)`：
+
+1. **若提供了 `enabled_toolsets`** — 仅包含这些 toolset 中的工具。每个 toolset 名称通过 `resolve_toolset()` 解析，将复合 toolset 展开为单个工具名称。
+
+2. **若提供了 `disabled_toolsets`** — 从所有 toolset 开始，减去已禁用的。
+
+3. **若两者均未提供** — 包含所有已知 toolset。
+
+4. **注册表过滤** — 解析后的工具名称集合传递给 `registry.get_definitions()`，后者应用 `check_fn` 过滤并返回 OpenAI 格式的 schema。
+
+5. **动态 schema 修补** — 过滤后，`execute_code` 和 `browser_navigate` 的 schema 会被动态调整，仅引用实际通过过滤的工具（防止模型幻觉出不可用的工具）。
+
+### 旧版 toolset 名称
+
+带有 `_tools` 后缀的旧版 toolset 名称（例如 `web_tools`、`terminal_tools`）通过 `_LEGACY_TOOLSET_MAP` 映射到其现代工具名称，以保持向后兼容性。
+
+## 调度
+
+运行时，工具通过中央注册表调度，但部分 agent 级别的工具（如 memory/todo/session-search 处理）由 agent 循环直接处理。
+
+### 调度流程：模型 tool_call → handler 执行
+
+当模型返回 `tool_call` 时，流程如下：
+
+```
+模型响应包含 tool_call
+    ↓
+run_agent.py agent 循环
+    ↓
+model_tools.handle_function_call(name, args, task_id, user_task)
+    ↓
+[Agent 循环工具？] → 由 agent 循环直接处理（todo、memory、session_search、delegate_task）
+    ↓
+[插件 pre-hook] → invoke_hook("pre_tool_call", ...)
+    ↓
+registry.dispatch(name, args, **kwargs)
+    ↓
+按名称查找 ToolEntry
+    ↓
+[异步 handler？] → 通过 _run_async() 桥接
+[同步 handler？]  → 直接调用
+    ↓
+返回结果字符串（或 JSON 错误）
+    ↓
+[插件 post-hook] → invoke_hook("post_tool_call", ...)
+```
+
+### 错误包装
+
+所有工具执行在两个层级进行错误处理：
+
+1. **`registry.dispatch()`** — 捕获 handler 抛出的任何异常，并以 JSON 形式返回 `{"error": "Tool execution failed: ExceptionType: message"}`。
+
+2. **`handle_function_call()`** — 将整个调度包裹在次级 try/except 中，返回 `{"error": "Error executing tool_name: message"}`。
+
+这确保模型始终收到格式正确的 JSON 字符串，而不会遇到未处理的异常。
+
+### Agent 循环工具
+
+以下四个工具在注册表调度之前被拦截，因为它们需要 agent 级别的状态（TodoStore、MemoryStore 等）：
+
+- `todo` — 规划/任务跟踪
+- `memory` — 持久化 memory 写入
+- `session_search` — 跨会话召回
+- `delegate_task` — 生成子 agent 会话
+
+这些工具的 schema 仍在注册表中注册（供 `get_tool_definitions` 使用），但若调度以某种方式直接到达它们，其 handler 会返回一个存根错误。
+
+### 异步桥接
+
+当工具 handler 为异步时，`_run_async()` 将其桥接到同步调度路径：
+
+- **CLI 路径（无运行中的事件循环）** — 使用持久化事件循环以保持缓存的异步客户端存活
+- **Gateway 路径（有运行中的事件循环）** — 使用 `asyncio.run()` 启动一个一次性线程
+- **工作线程（并行工具）** — 使用存储在线程本地存储中的每线程持久化循环
+
+## DANGEROUS_PATTERNS 审批流程
+
+终端工具集成了定义在 `tools/approval.py` 中的危险命令审批系统：
+
+1. **模式检测** — `DANGEROUS_PATTERNS` 是一个 `(regex, description)` 元组列表，涵盖破坏性操作：
+   - 递归删除（`rm -rf`）
+   - 文件系统格式化（`mkfs`、`dd`）
+   - SQL 破坏性操作（`DROP TABLE`、不带 `WHERE` 的 `DELETE FROM`）
+   - 系统配置覆写（`> /etc/`）
+   - 服务操控（`systemctl stop`）
+   - 远程代码执行（`curl | sh`）
+   - Fork bomb、进程终止等
+
+2. **检测** — 在执行任何终端命令之前，`detect_dangerous_command(command)` 会对所有模式进行检查。
+
+3. **审批提示** — 若发现匹配：
+   - **CLI 模式** — 交互式提示要求用户批准、拒绝或永久允许
+   - **Gateway 模式** — 异步审批回调将请求发送至消息平台
+   - **智能审批** — 可选地，辅助 LLM 可自动批准匹配模式但风险较低的命令（例如，`rm -rf node_modules/` 是安全的，但匹配"递归删除"模式）
+
+4. **会话状态** — 审批按会话跟踪。一旦在某个会话中批准了"递归删除"，后续的 `rm -rf` 命令不会再次提示。
+
+5. **永久允许列表** — "永久允许"选项会将该模式写入 `config.yaml` 的 `command_allowlist`，跨会话持久化。
+
+## 终端/运行时环境
+
+终端系统支持多种后端：
+
+- local
+- docker
+- ssh
+- singularity
+- modal
+- daytona
+- vercel_sandbox
+
+还支持：
+
+- 按任务的 cwd 覆盖
+- 后台进程管理
+- PTY 模式
+- 危险命令的审批回调
+
+## 并发
+
+工具调用可以顺序执行，也可以并发执行，具体取决于工具组合和交互需求。
+
+## 相关文档
+
+- [Toolsets 参考](../reference/toolsets-reference.md)
+- [内置工具参考](../reference/tools-reference.md)
+- [Agent 循环内部机制](./agent-loop.md)
+- [ACP 内部机制](./acp-internals.md)