@huyooo/ai-chat-core 0.2.45 → 0.3.3

package/src/types.ts

@@ -1,90 +1,30 @@
 /**
- * AI Chat Core 类型定义
+ * AI Chat Core 公共类型定义
+ *
+ * - Agent / Chat 配置、消息与工具契约（含 JSON Schema、ToolResult 信封）
+ * - 与治理、MCP、Skills 等模块共享的跨层类型入口
+ * - 不包含协议层与编排器专用类型（见 protocols/、orchestrator/types）
  */
 
-import type { McpServerConfig } from './mcp/types';
-import { 
-  getVisibleModels, 
-  getModelFamily,
-  getModelEntry,
-  modelSupportsThinking,
-  modelSupportsVision,
-  modelSupportsNativeSearch,
-  getModelSearchStrategy,
-  type ModelRegistryEntry,
-} from './providers/model-registry';
-import type { ProviderType } from './router';
+import type {
+  AssetApprovalPolicy,
+  AssetHostDependency,
+  AssetSideEffectLevel,
+  AssetSource,
+} from './governance/types';
+import type { McpServerConfig } from './tool-manager/types';
+import { Kind, Type, type TSchema } from '@sinclair/typebox';
 
 // ==================== 模式与模型 ====================
 
 /** 对话模式 */
 export type ChatMode = 'agent' | 'ask';
 
-// 重新导出 router 和 Model Registry 类型
-export type { ProviderType };
-export type { ModelFamilyId, ModelFamilyConfig, ModelRegistryEntry } from './providers/model-registry';
-export { getModelFamily, getModelEntry, modelSupportsThinking, modelSupportsNativeSearch, getModelSearchStrategy };
-
-/** 模型选项（前端显示用） */
-export interface ModelOption {
-  /** 模型 ID（发送给 API） */
-  modelId: string;
-  /** 显示名称 */
-  displayName: string;
-  /** 是否支持深度思考 */
-  supportsThinking: boolean;
-  /** 是否支持图片理解 */
-  supportsVision: boolean;
-  /** 用于模型项 hover 的特性描述（由后端定义，前端只渲染） */
-  tooltip?: {
-    features?: string[];
-    /** 开销信息（数组，分行显示） */
-    cost?: string[];
-    description?: string;
-  };
-}
-
-/** 生成模型 tooltip 的 features 列表 */
-function buildModelFeatures(entry: ModelRegistryEntry): string[] {
-  const family = getModelFamily(entry.id);
-  const supportsVision = modelSupportsVision(entry.id);
-  const supportsThinking = family?.supportsThinking ?? false;
-  const supportsNativeSearch = family?.supportsNativeSearch ?? false;
-  
-  const features: string[] = [];
-  // 顺序：多模态 > 深度思考 > 长上下文 > 联网搜索
-  if (supportsVision) features.push('多模态');
-  if (supportsThinking) features.push('深度思考');
-  if (entry.contextWindow) features.push(`长上下文（${entry.contextWindow}）`);
-  if (supportsNativeSearch) features.push('联网搜索');
-  
-  return features;
-}
-
-/**
- * 预定义模型列表
- */
-export const MODELS: ModelOption[] = getVisibleModels().map(entry => {
-  const family = getModelFamily(entry.id);
-  const supportsThinking = family?.supportsThinking ?? false;
-  const supportsVision = modelSupportsVision(entry.id);
-
-  return {
-    modelId: entry.id,
-    displayName: entry.displayName,
-    supportsThinking,
-    supportsVision,
-    tooltip: {
-      features: buildModelFeatures(entry),
-      cost: entry.pricing,
-    },
-  };
-});
+export type { ModelFamilyId, ModelFamilyConfig } from './families';
+import type { ProtocolId } from './protocols';
+export type { ProtocolId } from './protocols';
 
-/** 根据 modelId 获取模型 */
-export function getModelByModelId(modelId: string): ModelOption | undefined {
-  return MODELS.find(m => m.modelId === modelId);
-}
+export type { ModelOption } from './adapter';
 
 // ==================== 配置 ====================
 
@@ -92,47 +32,73 @@ export function getModelByModelId(modelId: string): ModelOption | undefined {
 export type ToolApprovalCallback = (toolCall: {
   id: string;
   name: string;
+  toolName?: string;
+  extensionId?: string;
+  alias?: string;
+  displayName?: string;
   args: Record<string, unknown>;
 }) => Promise<boolean>;
 
+/** 宿主应用注入的工具执行审计钩子 */
+export interface ToolExecutionAuditHooks {
+  startToolCall(input: {
+    id?: string | null;
+    traceId: string;
+    extensionId?: string | null;
+    toolName: string;
+    displayName?: string | null;
+    source?: AssetSource | string | null;
+    cwd?: string | null;
+    args?: unknown;
+    approvalPolicy?: AssetApprovalPolicy | string | null;
+    sideEffectLevel?: AssetSideEffectLevel | string | null;
+    hostDependency?: AssetHostDependency | string | null;
+    metadata?: Record<string, unknown>;
+  }): string;
+  finishToolCall(input: {
+    toolCallId: string;
+    traceId: string;
+    result?: unknown;
+    completedAt?: string;
+  }): void;
+  failToolCall(input: {
+    toolCallId: string;
+    traceId: string;
+    error: unknown;
+    completedAt?: string;
+  }): void;
+  runWithContext<T>(
+    context: {
+      conversationId?: string | null;
+      turnId?: string | null;
+      toolCallId?: string | null;
+      traceId?: string | null;
+    },
+    fn: () => T,
+  ): T;
+}
+
 /** Agent 配置 */
 export interface AgentConfig {
-  /** 豆包/火山引擎 API Key (用于豆包和 DeepSeek) */
-  arkApiKey: string;
-  /** 豆包 API URL */
-  arkApiUrl?: string;
-  /** 通义千问 API Key */
-  qwenApiKey?: string;
-  /** 通义千问 API URL */
-  qwenApiUrl?: string;
-  /** OpenRouter API Key */
-  openrouterApiKey?: string;
-  /** OpenRouter API URL */
-  openrouterApiUrl?: string;
-  /** Vercel API Key（用于 Vercel AI Gateway 访问 Claude） */
-  vercelApiKey?: string;
-  /** Tavily API Key（用于统一 Web Search） */
-  tavilyApiKey?: string;
-  /** Gemini API Key (用于图片/视频，注意：中国大陆无法直接访问) */
-  geminiApiKey: string;
-  /** 当前工作目录（Current Working Directory） */
-  cwd?: string;
+  /** 统一 LLM 配置（endpoints + models 降级链） */
+  llmConfig: import('./llm-config').LLMConfig;
+  /** 当前工作目录（必传，浏览器安全：不使用 process.cwd()） */
+  cwd: string;
+  /** 最大模型轮次（可选，默认不限制） */
+  maxIterations?: number;
+  /** 最大总执行时长，单位毫秒（可选，默认不限制） */
+  maxDurationMs?: number;
+  /** 最大工具调用次数（可选，默认不限制） */
+  maxToolCalls?: number;
+  /** 最大累计 token 数（可选，默认不限制） */
+  maxTotalTokens?: number;
   /** 
    * 工具列表（Vite 插件风格）
    * 
    * 支持多种形式：
-   * - 单个工具：getCwdTool
+   * - 单个工具：getEnvironmentTool()
    * - 工具插件：searchPlugin({ dataDir, workspace })
    * - Promise：await asyncPlugin()
-   * 
-   * @example
-   * ```typescript
-   * tools: [
-   *   getCwdTool,
-   *   executeCommandTool,
-   *   searchPlugin({ dataDir: '/path', workspace: '/project' }),
-   * ]
-   * ```
    */
   tools?: ToolConfigItem[];
   /** 
@@ -149,28 +115,18 @@ export interface AgentConfig {
    * MCP Server 配置列表
    * 
    * 初始化时自动连接所有 MCP Server，发现工具并注册到 Agent。
-   * 
-   * @example
-   * ```typescript
-   * mcpServers: [
-   *   { name: 'filesystem', transport: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/Users/me'] },
-   *   { name: 'github', transport: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'], env: { GITHUB_TOKEN: '...' } },
-   *   { name: 'remote-db', transport: 'sse', url: 'http://localhost:3001/mcp' },
-   * ]
-   * ```
    */
   mcpServers?: McpServerConfig[];
   /**
-   * 上下文总结回调（走 ai-server 等外部服务）
-   *
-   * 当对话历史超过模型 context window 时，orchestrator 调用此函数执行 AI 总结。
-   * 宿主提供实现（如 smart-finder 的 toolAI），ai-chat-core 不关心具体调用方式。
-   *
-   * @param systemPrompt 总结指令
-   * @param userPrompt 格式化后的中间对话历史
-   * @returns 总结后的文本
+   * 宿主应用注入的数据引擎接口（可选）。
+   * 传递给 ToolContext.dataEngine，使所有工具可访问平台数据能力。
    */
-  summarize?: (systemPrompt: string, userPrompt: string) => Promise<string>;
+  dataEngine?: DataEngineContext;
+  /**
+   * 宿主应用注入的工具执行审计钩子。
+   * 位于 ChatRuntime.executeTool 根入口，覆盖 in-process、MCP 和未来 provider。
+   */
+  audit?: ToolExecutionAuditHooks;
 }
 
 /** 深度思考模式 */
@@ -189,12 +145,6 @@ export interface AutoRunConfig {
   mode?: AutoRunMode;
 }
 
-/** 聊天消息格式（用于传递历史） */
-export interface ChatHistoryMessage {
-  role: 'user' | 'assistant' | 'system' | 'tool';
-  content: string;
-}
-
 /**
  * 用户工具定义（透传模式）
  * 
@@ -208,6 +158,12 @@ export interface UserToolDefinition {
   description: string;
   /** 参数定义（JSON Schema，支持嵌套） */
   parameters: JsonSchemaObject;
+  /** 成功时 data 内的业务结构（JSON Schema，可选） */
+  outputSchema?: JsonSchemaObject;
+  /** 成功返回标准信封结构（JSON Schema，可选，由 outputSchema 自动生成） */
+  resolvedOutputSchema?: JsonSchemaObject;
+  /** 标准错误返回结构（JSON Schema，可选；不传则使用平台默认错误结构） */
+  errorSchema?: JsonSchemaObject;
 }
 
 /** 聊天配置（每次聊天可变的选项） */
@@ -217,7 +173,7 @@ export interface ChatOptions {
   /** 使用的模型 */
   model?: string;
   /** 模型提供商 */
-  provider?: ProviderType;
+  provider?: ProtocolId;
   /** 是否启用联网搜索 */
   enableWebSearch?: boolean;
   /** 
@@ -228,10 +184,23 @@ export interface ChatOptions {
   thinkingMode?: ThinkingMode;
   /** 启用的工具名称列表（agent 模式有效，ask 模式强制禁用） */
   enabledTools?: string[];
+  /**
+   * 宿主侧动态工具选择解析器。
+   * 每次模型迭代前调用，用于让 tool_enable 这类管理工具在同一轮 agent loop 的下一次模型请求生效。
+   */
+  resolveEnabledTools?: () => Promise<string[] | undefined>;
   /** 自动运行配置 */
   autoRunConfig?: AutoRunConfig;
-  /** 对话历史（从数据库加载，无状态架构） */
-  history?: ChatHistoryMessage[];
+  /** 单次运行最大模型轮次；不传则使用运行时默认值 */
+  maxIterations?: number;
+  /** 单次运行最大时长（毫秒）；不传则使用运行时默认值 */
+  maxDurationMs?: number;
+  /** 单次运行最大工具调用次数；不传则使用运行时默认值 */
+  maxToolCalls?: number;
+  /** 单次运行最大累计 Token；不传则使用运行时默认值 */
+  maxTotalTokens?: number;
+  /** 对话历史（从数据库加载，无状态架构，需包含完整 tool_calls / tool_call_id） */
+  history?: ChatMessage[];
   /**
    * 用户自定义工具（透传模式）
    * 
@@ -253,7 +222,7 @@ export interface ChatOptions {
   /**
    * 宿主平台提示词（可选）
    * 
-   * 由宿主应用（如 smart-finder）注入的平台特定 system prompt 扩展。
+   * 由宿主应用（如 SuperX）注入的平台特定 system prompt 扩展。
    * 用于描述平台特有的能力、工具编排、记忆管理等，避免在核心库中硬编码具体工具名。
    * 
    * 注入位置：基础 prompt 之后、Skills 内容之前。
@@ -275,7 +244,7 @@ export interface ChatOptions {
 
 // ==================== 工具相关 ====================
 
-/** 前端渲染组件类型（可扩展） */
+/** 前端渲染组件类型：内置若干枚举，扩展 Part 使用与 `parts/<name>` 一致的任意字符串 */
 export type RenderType = 'weather' | 'chart' | 'browser' | 'plan' | string;
 
 /** 前端动作类型（可扩展） */
@@ -287,7 +256,26 @@ export type ActionType = 'toast' | 'notification' | 'reload' | string;
  * - action: 触发前端动作（通知、刷新等）
  */
 export type ToolUI =
-  | { type: 'render'; name: RenderType; props?: Record<string, unknown> }
+  | {
+    type: 'render';
+    name: RenderType;
+    props?: Record<string, unknown>;
+    /**
+     * 仅在 tool_call_result 成功后再创建 render Part。
+     *
+     * 适用于“结果导向”的卡片：
+     * - 运行中没有稳定可展示内容
+     * - 最终结果可能被动态抑制（例如 no-op）
+     */
+    renderOnResultOnly?: boolean;
+    /**
+     * 消息内唯一实例（如 plan 进度面板）
+     *
+     * - true: 同类型 Part 在一条消息中只存在一个，多次调用同一工具时就地更新
+     * - false/undefined: 每次调用创建独立 Part（如天气卡片、搜索结果）
+     */
+    singleton?: boolean;
+  }
   | { type: 'action'; name: ActionType };
 
 /** Shell 命令执行结果 */
@@ -297,19 +285,331 @@ export interface ExecResult {
   exitCode: number;
 }
 
+export interface ExecOptions {
+  timeout?: number;
+}
+
 /** 工具执行上下文 */
 export interface ToolContext {
+  /** 当前模型工具调用 ID（由编排器注入，供宿主审计/关联使用） */
+  toolCallId?: string;
+  /** 当前模型工具调用名称（由编排器注入，供宿主审计/关联使用） */
+  toolName?: string;
   /** 当前工作目录（可选，工具需要时由框架注入） */
   cwd?: string;
+  /**
+   * 当前模型回合允许调用的工具名。
+   * 管理类工具必须用它约束搜索、查看和启用范围，避免绕过会话能力选择。
+   */
+  allowedToolNames?: readonly string[];
   /** 执行 Shell 命令（可选，工具需要时由框架注入） */
-  exec?: (cmd: string, args?: string[]) => Promise<ExecResult>;
+  exec?: (cmd: string, args?: string[], options?: ExecOptions) => Promise<ExecResult>;
   /** 中断信号（用于取消长时间操作） */
   signal?: AbortSignal;
+  /** 向对话流推送 stdout 增量（可选） */
+  onStdout?: (chunk: string) => void;
+  /** 向对话流推送 stderr 增量（可选） */
+  onStderr?: (chunk: string) => void;
+  /**
+   * 宿主应用注入的数据引擎接口（可选）。
+   * 市场扩展工具可通过此接口访问数据库、搜索引擎等平台能力。
+   */
+  dataEngine?: DataEngineContext;
+}
+
+/** 数据引擎上下文 — 宿主应用按需注入 */
+export interface DataEngineContext {
+  /** 按名称获取 SQLite 只读连接，用于查询已注册数据库 */
+  queryDb: (dbName: string, sql: string, params?: unknown[]) => { columns: string[]; rows: Record<string, unknown>[] };
+  /** 列出所有可用数据集（SQLite + Vector + FullText） */
+  listDatasets: () => Array<{
+    id?: string
+    name: string
+    storageKind: string
+    owner: { ownerType: string; ownerKey: string }
+    workspaceKey?: string | null
+    customScope?: Record<string, unknown> | null
+    description: string
+    queryHint?: string
+    path?: string
+    capabilities?: {
+      readable: boolean
+      writable: boolean
+      queryable: boolean
+      searchable?: boolean
+      recoverable: boolean
+    }
+  }>;
+  /** 跨数据库关键词搜索 */
+  searchAll: (
+    keyword: string,
+    opts?: {
+      ownerType?: string
+      ownerKey?: string
+      workspaceKey?: string
+      storageKind?: string
+      mode?: 'exact' | 'semantic' | 'fulltext' | 'hybrid'
+      limit?: number
+    },
+  ) => Array<{
+    database: string
+    table: string
+    row: Record<string, unknown>
+    resourceName?: string
+    storageKind?: string
+    matchType?: string
+    score?: number
+    path?: string
+    snippet?: string
+  }> | Promise<Array<{
+    database: string
+    table: string
+    row: Record<string, unknown>
+    resourceName?: string
+    storageKind?: string
+    matchType?: string
+    score?: number
+    path?: string
+    snippet?: string
+  }>>;
+}
+
+// ==================== 工具结果 ====================
+
+/** 统一工具结果信封 */
+export interface ToolResult {
+  /** 结构化业务数据。序列化后固定放在 data 字段内。 */
+  data?: Record<string, unknown>;
+  /** 给用户和模型看的简短说明。序列化后固定放在 message 字段内。 */
+  message?: string;
+  /** @deprecated 使用 message。保留给旧内部调用，序列化时会映射到 message。 */
+  text?: string;
+  /** 精简摘要，帮助模型快速理解工具结果 */
+  _summary?: string;
+  /** 附加元数据（调试/埋点/来源信息） */
+  metadata?: Record<string, unknown>;
+}
+
+export type ToolSuccess<TData extends Record<string, unknown> = Record<string, unknown>> = {
+  status: 'ok';
+  data: TData;
+  message?: string;
+};
+
+export function toolOk<TData extends Record<string, unknown>>(
+  data: TData,
+  message?: string,
+): ToolResult {
+  return {
+    data,
+    message,
+  };
+}
+
+export function textToolResult(
+  text: string,
+  options: { summary?: string; metadata?: Record<string, unknown> } = {},
+): ToolResult {
+  return {
+    message: text,
+    _summary: options.summary,
+    metadata: options.metadata,
+  };
+}
+
+export function dataToolResult(
+  data: Record<string, unknown>,
+  options: { text?: string; summary?: string; metadata?: Record<string, unknown> } = {},
+): ToolResult {
+  return {
+    data,
+    message: options.text,
+    _summary: options.summary,
+    metadata: options.metadata,
+  };
+}
+
+export function emptyToolResult(
+  options: { summary?: string; metadata?: Record<string, unknown> } = {},
+): ToolResult {
+  return {
+    text: undefined,
+    _summary: options.summary,
+    metadata: options.metadata,
+  };
+}
+
+export interface ToolGovernanceSnapshot {
+  approvalPolicy?: AssetApprovalPolicy;
+  sideEffectLevel?: AssetSideEffectLevel;
+  hostDependency?: AssetHostDependency;
+  riskSummary?: string;
+  riskTags?: string[];
+  riskSignals?: string[];
+}
+
+/** 工具执行允许返回的值 */
+export type ToolExecuteResult = ToolResult | Record<string, unknown>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/** 判断对象是否已经是 ToolResult 信封 */
+export function isToolResult(value: unknown): value is ToolResult {
+  if (!isRecord(value)) return false;
+  return (
+    'data' in value ||
+    'message' in value ||
+    'text' in value ||
+    '_summary' in value ||
+    'metadata' in value
+  );
+}
+
+/** 规范化工具结果为统一信封 */
+export function normalizeToolResult(value: ToolExecuteResult | undefined): ToolResult {
+  if (!value) return { data: {} };
+  if (isToolResult(value)) return value;
+  return { data: value };
+}
+
+/**
+ * 将 ToolResult 序列化为给 LLM / 事件系统使用的最终对象。
+ *
+ * 设计原则：
+ * - 成功结果统一返回 status/data/message envelope。
+ * - 业务字段一律位于 data 内，避免与平台协议字段冲突。
+ */
+export function serializeToolResult(result: ToolResult): Record<string, unknown> {
+  const output: Record<string, unknown> = {
+    status: 'ok',
+    data: result.data ?? {},
+  };
+  const message = result.message ?? result.text;
+  if (message !== undefined) output.message = message;
+  if (result._summary !== undefined) output._summary = result._summary;
+  if (result.metadata !== undefined) output._meta = result.metadata;
+  return output;
+}
+
+function isToolUi(value: unknown): value is ToolUI {
+  if (!isRecord(value)) return false;
+  if (value.type === 'action') {
+    return typeof value.name === 'string';
+  }
+  if (value.type === 'render') {
+    return typeof value.name === 'string';
+  }
+  return false;
+}
+
+/**
+ * 解析单次工具执行最终应使用的 UI。
+ *
+ * 规则：
+ * - 默认沿用工具静态声明的 ui
+ * - result.metadata.ui 可覆盖静态 ui
+ * - result.metadata.ui === null 表示这次显式不渲染任何 render/action ui
+ */
+export function resolveToolResultUi(
+  result: ToolResult,
+  fallback?: ToolUI,
+): ToolUI | undefined {
+  const metadata = result.metadata;
+  if (!metadata || !Object.prototype.hasOwnProperty.call(metadata, 'ui')) {
+    return fallback;
+  }
+
+  const override = metadata.ui;
+  if (override == null) {
+    return undefined;
+  }
+
+  return isToolUi(override) ? override : fallback;
+}
+
+function mergeApprovalPolicy(
+  left?: AssetApprovalPolicy,
+  right?: AssetApprovalPolicy,
+) {
+  const order: Record<NonNullable<typeof left>, number> = {
+    auto: 0,
+    'destructive-only': 1,
+    manual: 2,
+  };
+  if (!left) return right;
+  if (!right) return left;
+  return order[left] >= order[right] ? left : right;
+}
+
+function mergeSideEffectLevel(
+  left?: AssetSideEffectLevel,
+  right?: AssetSideEffectLevel,
+) {
+  const order: Record<NonNullable<typeof left>, number> = {
+    read: 0,
+    write: 1,
+    destructive: 2,
+  };
+  if (!left) return right;
+  if (!right) return left;
+  return order[left] >= order[right] ? left : right;
+}
+
+function mergeHostDependency(
+  left?: AssetHostDependency,
+  right?: AssetHostDependency,
+) {
+  const order: Record<NonNullable<typeof left>, number> = {
+    none: 0,
+    'local-app': 1,
+    'os-service': 2,
+    'remote-service': 3,
+  };
+  if (!left) return right;
+  if (!right) return left;
+  return order[left] >= order[right] ? left : right;
+}
+
+/** 合并静态治理与基于输入参数的动态治理，始终选择更严格的一侧。 */
+export function mergeToolGovernance(
+  base?: ToolGovernanceSnapshot,
+  override?: ToolGovernanceSnapshot,
+): ToolGovernanceSnapshot {
+  return {
+    approvalPolicy: mergeApprovalPolicy(base?.approvalPolicy, override?.approvalPolicy),
+    sideEffectLevel: mergeSideEffectLevel(base?.sideEffectLevel, override?.sideEffectLevel),
+    hostDependency: mergeHostDependency(base?.hostDependency, override?.hostDependency),
+    riskSummary: override?.riskSummary ?? base?.riskSummary,
+    riskTags: override?.riskTags ?? base?.riskTags,
+    riskSignals: override?.riskSignals ?? base?.riskSignals,
+  };
+}
+
+/**
+ * 基于工具静态声明和本次输入参数，解析执行前应展示/判断的治理信息。
+ */
+export async function resolveToolGovernanceSnapshot(
+  tool: Pick<Tool, 'approvalPolicy' | 'sideEffectLevel' | 'hostDependency' | 'assessInputGovernance'> | undefined,
+  args: Record<string, unknown>,
+): Promise<ToolGovernanceSnapshot> {
+  const staticGovernance: ToolGovernanceSnapshot = tool
+    ? {
+      approvalPolicy: tool.approvalPolicy,
+      sideEffectLevel: tool.sideEffectLevel,
+      hostDependency: tool.hostDependency,
+    }
+    : {};
+  const dynamicGovernance = tool?.assessInputGovernance
+    ? await tool.assessInputGovernance(args)
+    : undefined;
+  return mergeToolGovernance(staticGovernance, dynamicGovernance);
 }
 
 // ==================== 工具错误 ====================
 
-/** 工具错误码 */
+/** 工具错误码（预定义 + 可扩展） */
 export type ToolErrorCode =
   | 'INVALID_PARAMS'
   | 'NOT_FOUND'
@@ -317,63 +617,72 @@ export type ToolErrorCode =
   | 'OPERATION_FAILED'
   | 'TIMEOUT'
   | 'NETWORK_ERROR'
-  | string;
+  | (string & {});
+
+/** 标准工具错误分类 */
+export type ToolErrorCategory =
+  | 'validation'
+  | 'permission'
+  | 'network'
+  | 'not_found'
+  | 'conflict'
+  | 'runtime'
+  | 'external'
+  | (string & {});
 
 /** 工具错误结构 */
 export interface ToolError {
   message: string;
   code?: ToolErrorCode;
+  category?: ToolErrorCategory;
   suggestion?: string;
   retryable?: boolean;
+  details?: Record<string, unknown>;
 }
 
-/** 判断是否为结构化工具错误 */
-export function isToolError(e: unknown): e is Error & { toolError: ToolError } {
-  return (
-    e instanceof Error &&
-    typeof (e as Error & { toolError?: unknown }).toolError === 'object' &&
-    (e as Error & { toolError: unknown }).toolError !== null &&
-    typeof ((e as Error & { toolError: Record<string, unknown> }).toolError as Record<string, unknown>).message === 'string'
-  );
-}
+/** 结构化工具异常 */
+export class ToolException extends Error {
+  readonly toolError: ToolError;
 
-/** 抛出结构化工具错误 */
-export function throwToolError(
-  message: string,
-  code?: ToolErrorCode,
-  opts?: { suggestion?: string; retryable?: boolean }
-): never {
-  const toolError: ToolError = { message, code, ...opts };
-  const err = new Error(message) as Error & { toolError: ToolError };
-  Object.defineProperty(err, 'toolError', { value: toolError, enumerable: true });
-  throw err;
+  constructor(toolError: ToolError) {
+    super(toolError.message);
+    this.name = 'ToolException';
+    this.toolError = toolError;
+  }
 }
 
-/** 重新抛出工具错误（非工具错误则包装后抛出） */
-export function rethrowToolError(
-  error: unknown,
-  code?: ToolErrorCode,
-  opts?: { suggestion?: string; retryable?: boolean }
-): never {
-  if (isToolError(error)) throw error;
-  const message = error instanceof Error ? error.message : String(error);
-  throwToolError(message, code, opts);
+/** 判断是否为结构化工具错误 */
+export function isToolError(e: unknown): e is ToolException {
+  return e instanceof ToolException;
 }
 
-/** 从 args 中安全提取类型化参数 */
-export function getArg<T>(args: Record<string, unknown>, key: string): T | undefined {
-  return args[key] as T | undefined;
+/**
+ * 抛出结构化工具错误
+ *
+ * @example
+ * throwToolError('文件不存在')
+ * throwToolError({ message: '网络超时', code: 'NETWORK_ERROR', retryable: true })
+ */
+export function throwToolError(message: string): never;
+export function throwToolError(error: ToolError): never;
+export function throwToolError(input: string | ToolError): never {
+  throw new ToolException(typeof input === 'string' ? { message: input, code: 'OPERATION_FAILED' } : input);
 }
 
 /** JSON Schema 属性定义（支持嵌套，符合 JSON Schema 规范） */
 export interface JsonSchemaProperty {
   type?: string;
+  const?: unknown;
   description?: string;
+  format?: string;
   enum?: unknown[];
   items?: JsonSchemaProperty;
   properties?: Record<string, JsonSchemaProperty>;
   required?: string[];
   default?: unknown;
+  additionalProperties?: boolean | JsonSchemaProperty;
+  anyOf?: JsonSchemaProperty[];
+  oneOf?: JsonSchemaProperty[];
 }
 
 /** JSON Schema 对象类型（工具参数的根类型） */
@@ -382,6 +691,216 @@ export interface JsonSchemaObject {
   properties: Record<string, JsonSchemaProperty>;
   required?: string[];
   description?: string;
+  additionalProperties?: boolean | JsonSchemaProperty;
+}
+
+/** 平台标准工具错误返回结构 */
+export const STANDARD_TOOL_ERROR_SCHEMA: JsonSchemaObject = {
+  type: 'object',
+  description: '工具失败时的平台标准错误结构。成功结果使用工具自己的 resolvedOutputSchema。',
+  properties: {
+    status: {
+      type: 'string',
+      enum: ['error'],
+      description: '固定为 error，表示工具执行失败。',
+    },
+    failureReason: {
+      type: 'string',
+      description: '执行层失败原因，例如 parse_error、denied、timeout、execution_error。',
+    },
+    error: {
+      type: 'object',
+      description: '结构化错误信息。',
+      properties: {
+        code: {
+          type: 'string',
+          description: '稳定错误码，例如 INVALID_PARAMS、NETWORK_ERROR、NOT_FOUND。',
+        },
+        message: {
+          type: 'string',
+          description: '给用户和模型看的错误说明。',
+        },
+        category: {
+          type: 'string',
+          enum: ['validation', 'permission', 'network', 'not_found', 'conflict', 'runtime', 'external'],
+          description: '错误分类，用于判断是否换参数、重试、申请权限或停止。',
+        },
+        retryable: {
+          type: 'boolean',
+          description: '是否建议用相同目标稍后重试。',
+        },
+        suggestion: {
+          type: 'string',
+          description: '可选修复建议。',
+        },
+        details: {
+          type: 'object',
+          description: '可选调试详情，字段随错误码变化。',
+          additionalProperties: true,
+        },
+      },
+      required: ['message'],
+      additionalProperties: false,
+    },
+  },
+  required: ['status', 'failureReason', 'error'],
+  additionalProperties: false,
+};
+
+function isTypeBoxSchema(schema: Record<string, unknown>): schema is TSchema {
+  return Object.prototype.hasOwnProperty.call(schema, Kind);
+}
+
+function toSchemaOptions(schema: Record<string, unknown>): Record<string, unknown> {
+  const options: Record<string, unknown> = {};
+  const optionKeys = [
+    'description',
+    'default',
+    'title',
+    'format',
+    'pattern',
+    'minLength',
+    'maxLength',
+    'minimum',
+    'maximum',
+    'exclusiveMinimum',
+    'exclusiveMaximum',
+    'multipleOf',
+    'minItems',
+    'maxItems',
+    'uniqueItems',
+  ];
+
+  for (const key of optionKeys) {
+    const value = schema[key];
+    if (value !== undefined) {
+      options[key] = value;
+    }
+  }
+
+  const additionalProperties = schema.additionalProperties;
+  if (typeof additionalProperties === 'boolean') {
+    options.additionalProperties = additionalProperties;
+  } else if (additionalProperties && typeof additionalProperties === 'object') {
+    options.additionalProperties = jsonSchemaToTypeBoxSchema(additionalProperties as Record<string, unknown>);
+  }
+
+  return options;
+}
+
+function toTypeBoxLiteral(value: unknown, options: Record<string, unknown>): TSchema {
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return Type.Literal(value, options);
+  }
+  if (value === null) {
+    return Type.Null(options);
+  }
+  return Type.Any(options);
+}
+
+function toTypeBoxEnumSchema(
+  enumValues: readonly unknown[],
+  schema: Record<string, unknown>,
+): TSchema {
+  const options = toSchemaOptions(schema);
+  const literals = enumValues.map(value => toTypeBoxLiteral(value, {}));
+  if (literals.length === 1) {
+    return toTypeBoxLiteral(enumValues[0], options);
+  }
+  return Type.Union(literals, options);
+}
+
+export function jsonSchemaToTypeBoxSchema(schema: Record<string, unknown>): TSchema {
+  if (isTypeBoxSchema(schema)) return schema;
+
+  if (Object.prototype.hasOwnProperty.call(schema, 'const')) {
+    return toTypeBoxLiteral(schema.const, toSchemaOptions(schema));
+  }
+
+  const enumValues = Array.isArray(schema.enum) ? schema.enum : undefined;
+  if (enumValues && enumValues.length > 0) {
+    return toTypeBoxEnumSchema(enumValues, schema);
+  }
+
+  const unionSchemas = Array.isArray(schema.oneOf)
+    ? schema.oneOf
+    : Array.isArray(schema.anyOf)
+      ? schema.anyOf
+      : undefined;
+  if (unionSchemas && unionSchemas.length > 0) {
+    return Type.Union(
+      unionSchemas.map(value => value && typeof value === 'object'
+        ? jsonSchemaToTypeBoxSchema(value as Record<string, unknown>)
+        : Type.Any()),
+      toSchemaOptions(schema),
+    );
+  }
+
+  const type = schema.type;
+  if (Array.isArray(type)) {
+    return Type.Union(
+      type.map(value => jsonSchemaToTypeBoxSchema({ ...schema, type: value, oneOf: undefined, anyOf: undefined })),
+      toSchemaOptions(schema),
+    );
+  }
+
+  const options = toSchemaOptions(schema);
+
+  if (type === 'string') {
+    return Type.String(options);
+  }
+  if (type === 'number') {
+    return Type.Number(options);
+  }
+  if (type === 'integer') {
+    return Type.Integer(options);
+  }
+  if (type === 'boolean') {
+    return Type.Boolean(options);
+  }
+  if (type === 'null') {
+    return Type.Null(options);
+  }
+  if (type === 'array') {
+    const items = schema.items;
+    const itemSchema = items && typeof items === 'object'
+      ? jsonSchemaToTypeBoxSchema(items as Record<string, unknown>)
+      : Type.Any();
+    return Type.Array(itemSchema, options);
+  }
+  if (type === 'object' || typeof schema.properties === 'object') {
+    const properties = schema.properties;
+    const required = Array.isArray(schema.required) ? new Set(schema.required.filter(value => typeof value === 'string')) : new Set<string>();
+    const entries = properties && typeof properties === 'object'
+      ? Object.entries(properties)
+      : [];
+    const mappedProperties: Record<string, TSchema> = {};
+
+    for (const [key, value] of entries) {
+      const propertySchema = value && typeof value === 'object'
+        ? jsonSchemaToTypeBoxSchema(value as Record<string, unknown>)
+        : Type.Any();
+      mappedProperties[key] = required.has(key) ? propertySchema : Type.Optional(propertySchema);
+    }
+
+    return Type.Object(mappedProperties, options);
+  }
+
+  return Type.Any(options);
+}
+
+export function createResolvedOutputSchema(dataSchema: JsonSchemaObject): JsonSchemaObject {
+  const dataWithDescription = dataSchema.description
+    ? dataSchema
+    : { ...dataSchema, description: '工具成功时的业务数据。' };
+
+  return Type.Object({
+    status: Type.Literal('ok', { description: '固定为 ok，表示工具执行成功。' }),
+    data: jsonSchemaToTypeBoxSchema(dataWithDescription as unknown as Record<string, unknown>),
+    message: Type.Optional(Type.String({ description: '可选。给用户和模型看的简短说明，不承载业务数据。' })),
+  }, {
+    description: '工具成功时的平台标准返回结构。业务字段固定放在 data 内。',
+  }) as unknown as JsonSchemaObject;
 }
 
 /**
@@ -393,17 +912,41 @@ export interface JsonSchemaObject {
  *   name: 'my_tool',
  *   description: '我的自定义工具',
  *   parameters: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
- *   execute: async (args) => ({ result: getArg<string>(args, 'query') })
+ *   execute: async (args) => ({ result: args.query })
  * };
  * ```
  */
 export interface Tool {
-  /** 工具名称 */
+  /** 工具全局唯一 ID（可选，不传则由 provider 生成） */
+  id?: string;
+  /**
+   * 工具集 ID（scope 命名空间）
+   *
+   * 设置后表示此工具属于某个 scoped 工具集：
+   * - identity: `source:assetId:name`
+   * - alias: `assetId__name`
+   *
+   * 不设置则 name 同时作为 assetId（独立工具）：
+   * - identity: `source:name`
+   * - alias: `name`
+   */
+  assetId?: string;
+  /** scope 内的工具名（即 assetId/name 两段式中的 name） */
   name: string;
+  /** 对模型暴露的别名（可选，不传则由 provider 生成） */
+  alias?: string;
+  /** UI 展示名称（可选） */
+  displayName?: string;
   /** 工具描述（供 AI 理解） */
   description: string;
   /** 参数定义（JSON Schema） */
   parameters: JsonSchemaObject;
+  /** 成功时 data 内的业务结构（JSON Schema，可选） */
+  outputSchema?: JsonSchemaObject;
+  /** 成功返回标准信封结构（JSON Schema，可选，由 outputSchema 自动生成） */
+  resolvedOutputSchema?: JsonSchemaObject;
+  /** 失败返回结构（JSON Schema；不传时描述符层使用平台标准错误结构） */
+  errorSchema?: JsonSchemaObject;
   /**
    * UI 声明（可选）
    * - render: 在对话流中渲染自定义组件
@@ -416,17 +959,37 @@ export interface Tool {
    * 设为 true 时无论全局配置如何，该工具必须用户确认才执行
    */
   requiresApproval?: boolean;
+  /** 审批策略。`destructive-only` 表示仅 destructive 工具需要批准。 */
+  approvalPolicy?: AssetApprovalPolicy;
+  /** 副作用等级。用于审批和风险展示。 */
+  sideEffectLevel?: AssetSideEffectLevel;
+  /** 宿主依赖类型。用于治理和展示。 */
+  hostDependency?: AssetHostDependency;
+  /**
+   * 基于本次输入参数预判治理信息（可选）。
+   *
+   * 设计约束：
+   * - 用于执行前的动态风险评估
+   * - Orchestrator 只会将其与静态治理做“更严格”的合并，不会放宽静态治理
+   */
+  assessInputGovernance?: (
+    args: Record<string, unknown>,
+  ) => ToolGovernanceSnapshot | Promise<ToolGovernanceSnapshot | undefined> | undefined;
+  /** 分发来源（注册时如设置则覆盖 provider 默认值） */
+  source?: import('./governance/types').AssetSource;
+  /** 工具分类（供 ToolRegistry 发现使用） */
+  category?: string;
+  /** 工具标签（供 ToolRegistry 搜索使用） */
+  tags?: string[];
   /** 超时时间（毫秒），由框架通过 AbortSignal 强制执行 */
   timeout?: number;
-  /** 扩展字段，供宿主应用存放元数据 */
-  meta?: Record<string, unknown>;
-  /** 
+  /**
    * 执行函数
    * 
-   * 成功返回 object，框架自动 JSON.stringify 后传给 LLM。
+   * 成功返回 ToolResult 或普通对象，框架会统一规范化后再传给 LLM。
    * 失败统一 throw（推荐使用 throwToolError()）。
    */
-  execute: (args: Record<string, unknown>, context: ToolContext) => Promise<object>;
+  execute: (args: Record<string, unknown>, context: ToolContext) => Promise<ToolExecuteResult>;
 }
 
 /** 工具执行器接口（供 Agent 内部使用，自定义命令执行环境） */
@@ -439,7 +1002,8 @@ export interface ToolExecutor {
     hooks?: {
       onStdout?: (chunk: string) => void;
       onStderr?: (chunk: string) => void;
-    }
+    },
+    timeout?: number,
   ): Promise<{ success: boolean; output?: string; error?: string }>;
 }
 
@@ -462,9 +1026,9 @@ export interface ToolPlugin {
  * 
  * @example
  * ```typescript
- * export function getCwdTool(): ToolPlugin {
+ * export function getEnvironmentTool(): ToolPlugin {
  *   return tool({
- *     name: 'get_cwd',
+ *     name: 'get_environment',
  *     description: '...',
  *     parameters: { ... },
  *     execute: async (args, context) => { ... }
@@ -499,7 +1063,7 @@ export function tools(ts: Tool[]): ToolPlugin {
  * @example
  * ```typescript
  * tools: [
- *   getCwdTool(),                          // 工具插件（函数调用）
+ *   getEnvironmentTool(),                   // 工具插件（函数调用）
  *   searchPlugin({ dataDir, workspace }), // 异步插件（返回 Promise<ToolPlugin>）
  * ]
  * ```
@@ -516,10 +1080,10 @@ export type ToolConfigItem = Tool | ToolPlugin | Promise<Tool | ToolPlugin>;
  */
 export async function resolveTools(items: ToolConfigItem[]): Promise<Tool[]> {
   const tools: Tool[] = [];
-  
+
   for (const item of items) {
     const resolved = await item;
-    
+
     if ('tools' in resolved && Array.isArray(resolved.tools)) {
       // ToolPlugin
       tools.push(...resolved.tools);
@@ -530,7 +1094,7 @@ export async function resolveTools(items: ToolConfigItem[]): Promise<Tool[]> {
       console.warn('无法识别的工具配置项:', resolved);
     }
   }
-  
+
   return tools;
 }
 
@@ -571,13 +1135,8 @@ export interface ChatMessage {
 
 /** 火山引擎 Responses API 工具定义 */
 export interface ResponsesApiTool {
-  type: 'function' | 'web_search';
-  // Function 类型
+  type: 'function';
   name?: string;
   description?: string;
   parameters?: Record<string, unknown>;
-  // Web Search 类型
-  max_keyword?: number;
-  limit?: number;
-  sources?: string[];
 }