@zqagent/core 0.0.0-stage → 0.1.30

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# zqagent TS
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript 实现的 zqagent Agent 引擎核心（CLI），复刻 Python 版的核心机制：
+
+- **TurnEngine** — 异步生成器事件循环，驱动"思考 → 工具调用 → 观察"的迭代
+- **ToolRegistry** — 工具注册 / 执行 / 元数据管理
+- **PermissionEngine** — 工具风险分类 + 运行模式门控 + Y/N 交互审批
+- **OpenAIProvider** — 基于 OpenAI SDK 的流式 LLM 调用
+
+## 快速开始
+
+### 全局安装（推荐）
+
+```bash
+# 从私有仓库全局安装（其它机器需先配置该 registry，或加 --registry 参数）
+npm i -g @zqagent/core --registry=https://npm2.cd-zq.com/
+
+# 启动 CLI
+zqagent
+```
+
+启动后无需手动写 `.env`，输入 `/connect` 即可交互式配置 LLM 连接：
+选择 provider（DeepSeek / OpenAI / 自定义）→ 输入 API Key → 自动刷新模型列表并选择 →
+设置推理强度。API Key 会 AES-256-GCM 加密保存到本机 `~/.config/zqagent/`。
+
+### 本地开发
+
+```bash
+# 安装依赖
+npm install
+
+# 配置环境变量（复制为 .env 后填写），或启动后直接 /connect
+#   OPENAI_API_KEY=sk-...          # 必填（未用 /connect 时）
+#   OPENAI_MODEL=gpt-4o            # 可选，默认 gpt-4o
+#   OPENAI_BASE_URL=...            # 可选，自定义端点
+#   WORKSPACE=./                   # 可选，工作区根目录，默认当前目录
+cp .env.example .env
+
+# 启动 CLI
+npm run dev
+```
+
+## 使用
+
+启动后进入交互式 CLI，直接输入自然语言任务即可。内置命令：
+
+| 命令 | 说明 |
+| --- | --- |
+| `/plan` | 切换为计划模式（只读探索 + 计划提案） |
+| `/interactive` | 切换为交互式审批模式（默认） |
+| `/auto` | 切换为全自动模式（无需审批，高风险） |
+| `/discuss` | 切换为讨论模式（只读对话） |
+| `/mode` | 显示当前模式 |
+| `/connect` | 连接 LLM（选 provider → key → 刷新模型列表 → 推理强度） |
+| `/connect rm` | 清除连接配置（回退到环境变量） |
+| `/sessions` | 列出已保存会话并选择恢复（切换后回显最近消息） |
+| `/history` | 列出当前会话的用户指令 |
+| `/model <id>` | 切换 LLM 模型 |
+| `/agent <name>` | 切换 agent（Prompt + 可选模型同步） |
+| `/agents` | 列出所有 agent（当前高亮） |
+| `/agent add <name> <prompt...>` | 新增自定义 agent |
+| `/agent edit <name> <prompt...>` | 修改 agent 的 Prompt（当前 agent 即时热更新） |
+| `/agent rm <name>` | 删除 agent |
+| `/agent show [name]` | 查看 agent 详情 |
+| `/mcp` | 列出 MCP 服务器与连接状态 |
+| `/mcp add <name> stdio <cmd...>\|http <url>` | 添加并连接 MCP 服务器（工具自动注入） |
+| `/mcp rm\|enable\|disable\|refresh [name]` | 移除 / 启用 / 禁用 / 刷新工具列表 |
+| `/tools` | 列出所有工具（来源、风险、禁用状态） |
+| `/tool add <name> <cmd...>` | 添加命令工具（执行 shell 命令） |
+| `/tool rm\|disable\|enable <name>` | 移除 / 禁用 / 启用工具 |
+| `/clear` | 清空会话，重建引擎 |
+| `quit` / `exit` | 退出 |
+| `reset` | 重置会话 |
+
+> **Agent 机制**：内置 `code`（编程助手）/ `cowork`（通用协作）两个 agent。
+> 通过 `/agent add / edit / rm` 可运行时维护任意数量的 agent（名称 + Prompt + 可选模型）；
+> 定义持久化到项目内 `.agent/agents.json`（可提交 git，随项目共享）。
+> 切换 agent 时若其配置了 `model`，LLM 模型会同步切换；否则沿用当前模型。
+> 提示符以 `[模式][agent名] > ` 形式展示当前状态，如 `[plan][code] > `。
+
+> **MCP 与工具管理**：运行时可通过 `/mcp add` 注入外部 MCP 服务器
+> （stdio 本地进程或 http 远程端点），其工具自动以 `mcp__<server>__<tool>`
+> 前缀注册到工具表；`/tool add` 可创建执行 shell 命令的命令工具。
+> 引擎每次请求都实时拉取工具 schema，因此工具的新增 / 移除 / 禁用 / 替换
+> 对下一次 LLM 调用立即生效，无需重启。
+> MCP 服务器配置持久化到 `.agent/mcp.json`，命令工具到 `.agent/tools.json`
+> （均随项目走，可提交 git）；MCP 注入工具默认按高风险归类，交互模式下需逐次审批。
+
+### 运行模式
+
+| 模式 | 行为 |
+| --- | --- |
+| `discuss` | 只读，禁止一切写入与执行 |
+| `plan` | 只读，禁止一切写入与执行，面向计划提案 |
+| `interactive` | 有副作用的操作需用户逐次审批（默认） |
+| `auto` | 有副作用的操作全部放行（高风险，需自行承担） |
+
+交互模式下，审批卡片支持：`Y` 允许一次 / `A` 总是允许此工具 / `D` 拒绝；
+`run_shell` 额外支持 `C` 总是允许此命令（按具体命令白名单，比放行整个工具更安全）。
+
+## 内置工具（18 个）
+
+| 类别 | 工具 |
+| --- | --- |
+| 文件 | `read_file`, `write_file`, `replace_in_file`, `list_files`, `grep` |
+| Shell | `run_shell`（持久化 shell，命令白名单在 Auto 模式下自动放行） |
+| 网络 | `web_search`, `web_fetch` |
+| Git | `git_log`, `git_status`, `git_diff`（只读） |
+| 补丁 | `apply_patch`, `apply_unified_diff` |
+| 协作 | `ask_user`, `propose_plan`, `request_directory` |
+| 任务 | `todo_write`（共享进度状态） |
+| 子代理 | `explore`（独立 TurnEngine 实例，只读研究） |
+
+## 项目结构
+
+```
+src/
+├── index.ts                  # CLI 入口：装配组件、命令行审批器、事件渲染
+├── agents/
+│   └── AgentRegistry.ts      # Agent 注册表（运行时增删改查 / 切换 agent）
+├── mcp/
+│   ├── McpClient.ts          # 单个 MCP 服务器客户端（stdio / http）
+│   └── McpManager.ts         # 多服务器管理 + 工具动态注入 ToolRegistry
+├── engine/
+│   ├── TurnEngine.ts         # 异步生成器事件循环
+│   ├── events.ts             # 事件类型定义
+│   └── types.ts
+├── permissions/
+│   └── PermissionEngine.ts   # 风险分类 + 模式门控 + 审批决策
+├── providers/
+│   └── OpenAIProvider.ts     # 流式 LLM 调用
+├── prompts/
+│   └── index.ts              # 中文系统提示词模板
+└── tools/
+    ├── ToolRegistry.ts       # 工具注册表（注册/移除/禁用/替换）
+    ├── files.ts  shell.ts  search.ts  web.ts
+    ├── git.ts  diff.ts  todo.ts  explore.ts
+    └── ask.ts  plan.ts  directories.ts
+test/                         # Vitest 单元测试
+```
+
+## 开发
+
+```bash
+npm run build   # tsc 类型检查与构建
+npm test        # Vitest 运行测试
+```
+
+## 云端多租户 Server
+
+`src/server/` 提供多租户云端化 API（独立于 CLI）：每租户独立工作区/模型配置/状态存储，
+支持审批与提问的**挂起 → 持久化 → 超时回收 → resume 恢复**完整链路。
+
+```bash
+npm run server   # 启动（默认端口 8787，首次启动自动创建演示租户 demo/demo-key）
+```
+
+- 完整 curl 教程（审批/提问/超时回收/多租户隔离）：[docs/server-api.md](docs/server-api.md)
+- 一键测试：`bash scripts/test-server.sh`（无需 Key 的烟雾测试，18 项）；模型配置
+  （`OPENAI_API_KEY` 等）未显式设置时自动从项目 `.env` 读取，此时为完整链路测试
+  （真实对话 + 提问挂起 + 超时回收 + resume 恢复，24 项）
+
+## 桌面应用（macOS / Windows）
+
+`desktop/` 把 Server 打包成桌面应用：Tauri 2 外壳 + 内嵌 Node sidecar，前端复用
+`test_web/` 的 React 页面（本地引擎自动连接、托盘常驻、自动更新）。
+
+```bash
+# 开发调试
+cd desktop && npm install && npm run tauri dev
+
+# 一键构建
+./desktop/scripts/build_macos.sh          # macOS → DMG
+.\desktop\scripts\build_windows.ps1       # Windows → NSIS + MSI
+```
+
+详见 [desktop/README.md](desktop/README.md)。
+
+## 测试 Web 界面（test_web/）
+
+`test_web/` 是 Server 的 React 测试页：多租户 profile 管理、会话/审批/提问全链路。
+桌面壳会注入 `window.__ZQ_HTTP__/__ZQ_API_KEY__` 并自动注册「本地引擎」profile，
+浏览器模式（`npm run dev`）行为不变。

package/bin/zqagent

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli/index.js";

package/dist/ToolRegistry-BmvPxgMr.d.cts

@@ -0,0 +1,209 @@
+/**
+ * 基础类型定义
+ *
+ * 与 Python 版 zqagent 对齐的基础类型。这里定义了 Agent 引擎内部
+ * 流转的核心数据模型：LLM 工具调用、助手回复、Token 用量、流式 chunk、
+ * 对话消息以及 OpenAI 工具 Schema。
+ */
+/** LLM 请求的工具调用 */
+interface ToolCall {
+    /** 工具调用 ID（OpenAI 格式，用于把 tool 结果消息关联回对应的调用） */
+    id: string;
+    /** 工具名称 */
+    name: string;
+    /** 工具参数（已解析为对象的形态） */
+    arguments: Record<string, unknown>;
+}
+/** LLM 一次回复 */
+interface AssistantTurn {
+    /** 回复正文文本；无文本时为 null */
+    text: string | null;
+    /** 本次回复请求的工具调用列表（可能为空） */
+    toolCalls: ToolCall[];
+    /** 结束原因（stop / tool_calls / length 等），由 Provider 提供 */
+    finishReason: string | null;
+    /** 推理过程内容（如 OpenAI o 系列模型的 reasoning_content） */
+    reasoning: string | null;
+    /** 本次调用的 Token 用量统计 */
+    usage: TokenUsage | null;
+}
+/** 标准化的 Token 用量 */
+interface TokenUsage {
+    /** 输入 token 数 */
+    input: number;
+    /** 输出 token 数 */
+    output: number;
+    /** 命中缓存（缓存读取）的 token 数 */
+    cacheRead: number;
+    /** 写入缓存的 token 数 */
+    cacheWrite: number;
+}
+/** 流式输出的单个 chunk */
+interface StreamChunk {
+    /** 文本增量；该 chunk 无文本时为 null */
+    content: string | null;
+    /** 推理内容增量 */
+    reasoning: string | null;
+    /**
+     * 工具调用：流式过程中为 null；
+     * 流结束的最终 chunk 中，有工具调用时为完整列表，否则为 null
+     */
+    toolCalls: ToolCall[] | null;
+    /** 累计 Token 用量（OpenAI 在流结束前的最后一个 chunk 中返回） */
+    usage: TokenUsage | null;
+    /** 结束原因（仅在流结束 chunk 中出现） */
+    finishReason: string | null;
+}
+/** 对话消息 */
+interface Message {
+    /** 本轮任务ID */
+    taskId?: string;
+    /** 消息角色 */
+    role: "system" | "user" | "assistant" | "tool" | "notice";
+    /** 消息正文 */
+    content: string;
+    /** 附加来源信息（展示用） */
+    source?: Record<string, unknown>;
+    /** 展示用的替代文本（展示用） */
+    _display?: string;
+    /** 消息时间戳 */
+    ts?: number;
+    /** 推理过程文本（assistant 消息） */
+    reasoning?: string;
+    /** Token 用量（assistant 消息） */
+    usage?: Record<string, unknown>;
+    /** 关联的工具调用 ID（tool 消息回填用） */
+    tool_call_id?: string;
+    /** 工具调用名称（tool 消息回填用） */
+    tool_call_name?: string;
+    /** 工具调用列表（assistant 消息，OpenAI 格式） */
+    tool_calls?: {
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }[];
+    /** 通知类型：错误 / 中断 / 上下文压缩 / 模型切换 */
+    kind?: "error" | "interrupted" | "compacted" | "model_switch";
+    /** 通知附加文本 */
+    text?: string;
+}
+/**
+ * 推理强度（reasoning effort）
+ *
+ * 控制模型在生成答案前投入的推理计算量（OpenAI 的
+ * reasoning_effort / Responses 的 reasoning.effort 参数）。
+ * 仅对支持该参数的非 DeepSeek 模型生效（DeepSeek 用 thinking
+ * 布尔开关，不支持级别控制，Provider 层会跳过）。
+ */
+type ReasoningEffort = "low" | "medium" | "high";
+/** OpenAI 工具 Schema */
+interface ToolSchema {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+
+/**
+ * 工具注册表
+ *
+ * 对齐 Python 版 ToolRegistry。负责集中管理所有可用的 Agent 工具：
+ * 注册（含内置 schema 推导）、按名查询、批量导出 OpenAI Schema
+ * （供 LLM 调用）、按名执行。是 TurnEngine 与具体工具实现之间的桥梁。
+ */
+
+/** 工具风险等级 (对齐 Python 版 RiskClass) */
+declare enum RiskClass {
+    /** 只读，无副作用（如 read_file、grep） */
+    READ = "read",
+    /** 写入本地文件 */
+    WRITE_LOCAL = "write_local",
+    /** 执行 shell 命令 */
+    EXEC = "exec",
+    /** 访问外部网络资源 */
+    EXTERNAL = "external"
+}
+/** 工具元数据 */
+interface ToolMetadata {
+    /** 工具分类（filesystem / shell / search / web / planning 等） */
+    category: string;
+    /** 风险级别（low / medium / high） */
+    riskLevel: "low" | "medium" | "high";
+    /** 能力标签（用于生成默认描述） */
+    capabilities: string[];
+    /** 是否强制需要人工审批 */
+    requiresApproval: boolean;
+}
+/** 单个工具规格 */
+interface ToolSpec {
+    /** 工具名 */
+    name: string;
+    /** OpenAI 工具 Schema（供 LLM 识别调用方式） */
+    schema: ToolSchema;
+    /** 实际执行函数 */
+    func: (args: Record<string, unknown>) => unknown;
+    /** 工具元数据（供权限引擎评估风险） */
+    metadata: ToolMetadata;
+    /**
+     * 工具来源标识（展示用，可选）：
+     * "internal" 内置、`mcp:<server>` MCP 工具、"cli:command" 命令工具等
+     */
+    source?: string;
+}
+/** 工具注册表 (对齐 Python 版 ToolRegistry) */
+declare class ToolRegistry {
+    /** 工具名 → 工具规格 的映射表 */
+    private tools;
+    /** 已禁用的工具名集合（禁用的工具不出现在 schemas 中，模型不可调用） */
+    private disabled;
+    /**
+     * 注册一个工具 (内置 schema 自动推导；同名注册即替换，可实现"替换工具")
+     *
+     * @param func     工具执行函数（工具名优先取 schema.function.name，
+     *                 否则回退到 func.name；可返回 Promise，引擎会自动 await）
+     * @param metadata 工具元数据（风险等级、分类等）
+     * @param schema   OpenAI 工具 Schema；缺省时根据 metadata 自动构建
+     * @param source   工具来源标识（展示用，如 "mcp:<server>"）
+     * @returns 注册完成后的 ToolSpec
+     */
+    register(func: (args: Record<string, unknown>) => unknown, metadata: ToolMetadata, schema?: ToolSchema, source?: string): ToolSpec;
+    /** 移除工具。@returns 是否移除成功 */
+    remove(name: string): boolean;
+    /** 是否存在指定工具 */
+    has(name: string): boolean;
+    /** 禁用工具（从 schemas 移除，模型不可再调用；已排队的调用仍会执行）。@returns 是否成功 */
+    disable(name: string): boolean;
+    /** 重新启用工具。@returns 是否成功（原本处于禁用状态） */
+    enable(name: string): boolean;
+    /** 工具当前是否被禁用 */
+    isDisabled(name: string): boolean;
+    /** 获取所有启用中的工具的 OpenAI Schema（供 LLM 工具调用使用） */
+    schemas(): ToolSchema[];
+    /** 获取全部工具名列表（含禁用的） */
+    names(): string[];
+    /** 获取全部工具规格（含禁用的，返回副本） */
+    list(): ToolSpec[];
+    /** 获取单个工具 */
+    get(name: string): ToolSpec | undefined;
+    /**
+     * 执行工具
+     *
+     * @throws 工具未注册时抛出错误
+     */
+    execute(name: string, args: Record<string, unknown>): unknown;
+    /**
+     * 构建默认 Schema
+     *
+     * 未显式提供 schema 时使用：描述取 capabilities 的逗号拼接，
+     * parameters 为空对象（此时模型可能不知道参数结构，因此
+     * 正式工具都应显式提供完整 schema）。
+     */
+    private _defaultSchema;
+}
+
+export { type AssistantTurn as A, type Message as M, type ReasoningEffort as R, type StreamChunk as S, ToolRegistry as T, type TokenUsage as a, type ToolMetadata as b, type ToolSchema as c, RiskClass as d, type ToolCall as e, type ToolSpec as f };

package/dist/ToolRegistry-BmvPxgMr.d.ts

@@ -0,0 +1,209 @@
+/**
+ * 基础类型定义
+ *
+ * 与 Python 版 zqagent 对齐的基础类型。这里定义了 Agent 引擎内部
+ * 流转的核心数据模型：LLM 工具调用、助手回复、Token 用量、流式 chunk、
+ * 对话消息以及 OpenAI 工具 Schema。
+ */
+/** LLM 请求的工具调用 */
+interface ToolCall {
+    /** 工具调用 ID（OpenAI 格式，用于把 tool 结果消息关联回对应的调用） */
+    id: string;
+    /** 工具名称 */
+    name: string;
+    /** 工具参数（已解析为对象的形态） */
+    arguments: Record<string, unknown>;
+}
+/** LLM 一次回复 */
+interface AssistantTurn {
+    /** 回复正文文本；无文本时为 null */
+    text: string | null;
+    /** 本次回复请求的工具调用列表（可能为空） */
+    toolCalls: ToolCall[];
+    /** 结束原因（stop / tool_calls / length 等），由 Provider 提供 */
+    finishReason: string | null;
+    /** 推理过程内容（如 OpenAI o 系列模型的 reasoning_content） */
+    reasoning: string | null;
+    /** 本次调用的 Token 用量统计 */
+    usage: TokenUsage | null;
+}
+/** 标准化的 Token 用量 */
+interface TokenUsage {
+    /** 输入 token 数 */
+    input: number;
+    /** 输出 token 数 */
+    output: number;
+    /** 命中缓存（缓存读取）的 token 数 */
+    cacheRead: number;
+    /** 写入缓存的 token 数 */
+    cacheWrite: number;
+}
+/** 流式输出的单个 chunk */
+interface StreamChunk {
+    /** 文本增量；该 chunk 无文本时为 null */
+    content: string | null;
+    /** 推理内容增量 */
+    reasoning: string | null;
+    /**
+     * 工具调用：流式过程中为 null；
+     * 流结束的最终 chunk 中，有工具调用时为完整列表，否则为 null
+     */
+    toolCalls: ToolCall[] | null;
+    /** 累计 Token 用量（OpenAI 在流结束前的最后一个 chunk 中返回） */
+    usage: TokenUsage | null;
+    /** 结束原因（仅在流结束 chunk 中出现） */
+    finishReason: string | null;
+}
+/** 对话消息 */
+interface Message {
+    /** 本轮任务ID */
+    taskId?: string;
+    /** 消息角色 */
+    role: "system" | "user" | "assistant" | "tool" | "notice";
+    /** 消息正文 */
+    content: string;
+    /** 附加来源信息（展示用） */
+    source?: Record<string, unknown>;
+    /** 展示用的替代文本（展示用） */
+    _display?: string;
+    /** 消息时间戳 */
+    ts?: number;
+    /** 推理过程文本（assistant 消息） */
+    reasoning?: string;
+    /** Token 用量（assistant 消息） */
+    usage?: Record<string, unknown>;
+    /** 关联的工具调用 ID（tool 消息回填用） */
+    tool_call_id?: string;
+    /** 工具调用名称（tool 消息回填用） */
+    tool_call_name?: string;
+    /** 工具调用列表（assistant 消息，OpenAI 格式） */
+    tool_calls?: {
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }[];
+    /** 通知类型：错误 / 中断 / 上下文压缩 / 模型切换 */
+    kind?: "error" | "interrupted" | "compacted" | "model_switch";
+    /** 通知附加文本 */
+    text?: string;
+}
+/**
+ * 推理强度（reasoning effort）
+ *
+ * 控制模型在生成答案前投入的推理计算量（OpenAI 的
+ * reasoning_effort / Responses 的 reasoning.effort 参数）。
+ * 仅对支持该参数的非 DeepSeek 模型生效（DeepSeek 用 thinking
+ * 布尔开关，不支持级别控制，Provider 层会跳过）。
+ */
+type ReasoningEffort = "low" | "medium" | "high";
+/** OpenAI 工具 Schema */
+interface ToolSchema {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+
+/**
+ * 工具注册表
+ *
+ * 对齐 Python 版 ToolRegistry。负责集中管理所有可用的 Agent 工具：
+ * 注册（含内置 schema 推导）、按名查询、批量导出 OpenAI Schema
+ * （供 LLM 调用）、按名执行。是 TurnEngine 与具体工具实现之间的桥梁。
+ */
+
+/** 工具风险等级 (对齐 Python 版 RiskClass) */
+declare enum RiskClass {
+    /** 只读，无副作用（如 read_file、grep） */
+    READ = "read",
+    /** 写入本地文件 */
+    WRITE_LOCAL = "write_local",
+    /** 执行 shell 命令 */
+    EXEC = "exec",
+    /** 访问外部网络资源 */
+    EXTERNAL = "external"
+}
+/** 工具元数据 */
+interface ToolMetadata {
+    /** 工具分类（filesystem / shell / search / web / planning 等） */
+    category: string;
+    /** 风险级别（low / medium / high） */
+    riskLevel: "low" | "medium" | "high";
+    /** 能力标签（用于生成默认描述） */
+    capabilities: string[];
+    /** 是否强制需要人工审批 */
+    requiresApproval: boolean;
+}
+/** 单个工具规格 */
+interface ToolSpec {
+    /** 工具名 */
+    name: string;
+    /** OpenAI 工具 Schema（供 LLM 识别调用方式） */
+    schema: ToolSchema;
+    /** 实际执行函数 */
+    func: (args: Record<string, unknown>) => unknown;
+    /** 工具元数据（供权限引擎评估风险） */
+    metadata: ToolMetadata;
+    /**
+     * 工具来源标识（展示用，可选）：
+     * "internal" 内置、`mcp:<server>` MCP 工具、"cli:command" 命令工具等
+     */
+    source?: string;
+}
+/** 工具注册表 (对齐 Python 版 ToolRegistry) */
+declare class ToolRegistry {
+    /** 工具名 → 工具规格 的映射表 */
+    private tools;
+    /** 已禁用的工具名集合（禁用的工具不出现在 schemas 中，模型不可调用） */
+    private disabled;
+    /**
+     * 注册一个工具 (内置 schema 自动推导；同名注册即替换，可实现"替换工具")
+     *
+     * @param func     工具执行函数（工具名优先取 schema.function.name，
+     *                 否则回退到 func.name；可返回 Promise，引擎会自动 await）
+     * @param metadata 工具元数据（风险等级、分类等）
+     * @param schema   OpenAI 工具 Schema；缺省时根据 metadata 自动构建
+     * @param source   工具来源标识（展示用，如 "mcp:<server>"）
+     * @returns 注册完成后的 ToolSpec
+     */
+    register(func: (args: Record<string, unknown>) => unknown, metadata: ToolMetadata, schema?: ToolSchema, source?: string): ToolSpec;
+    /** 移除工具。@returns 是否移除成功 */
+    remove(name: string): boolean;
+    /** 是否存在指定工具 */
+    has(name: string): boolean;
+    /** 禁用工具（从 schemas 移除，模型不可再调用；已排队的调用仍会执行）。@returns 是否成功 */
+    disable(name: string): boolean;
+    /** 重新启用工具。@returns 是否成功（原本处于禁用状态） */
+    enable(name: string): boolean;
+    /** 工具当前是否被禁用 */
+    isDisabled(name: string): boolean;
+    /** 获取所有启用中的工具的 OpenAI Schema（供 LLM 工具调用使用） */
+    schemas(): ToolSchema[];
+    /** 获取全部工具名列表（含禁用的） */
+    names(): string[];
+    /** 获取全部工具规格（含禁用的，返回副本） */
+    list(): ToolSpec[];
+    /** 获取单个工具 */
+    get(name: string): ToolSpec | undefined;
+    /**
+     * 执行工具
+     *
+     * @throws 工具未注册时抛出错误
+     */
+    execute(name: string, args: Record<string, unknown>): unknown;
+    /**
+     * 构建默认 Schema
+     *
+     * 未显式提供 schema 时使用：描述取 capabilities 的逗号拼接，
+     * parameters 为空对象（此时模型可能不知道参数结构，因此
+     * 正式工具都应显式提供完整 schema）。
+     */
+    private _defaultSchema;
+}
+
+export { type AssistantTurn as A, type Message as M, type ReasoningEffort as R, type StreamChunk as S, ToolRegistry as T, type TokenUsage as a, type ToolMetadata as b, type ToolSchema as c, RiskClass as d, type ToolCall as e, type ToolSpec as f };