npm - better-dsh - Versions diffs - 0.2.5 → 0.3.0 - Mend

better-dsh 0.2.5 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (999) hide show

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

@@ -1,420 +0,0 @@
-# 会话存储
-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 DELETED Viewed

@@ -1,236 +0,0 @@
----
-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)