@huyooo/ai-chat-core 0.3.6 → 0.3.8

package/src/types.ts

@@ -1,1142 +0,0 @@
-/**
- * AI Chat Core 公共类型定义
- *
- * - Agent / Chat 配置、消息与工具契约（含 JSON Schema、ToolResult 信封）
- * - 与治理、MCP、Skills 等模块共享的跨层类型入口
- * - 不包含协议层与编排器专用类型（见 protocols/、orchestrator/types）
- */
-
-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';
-
-export type { ModelFamilyId, ModelFamilyConfig } from './families';
-import type { ProtocolId } from './protocols';
-export type { ProtocolId } from './protocols';
-
-export type { ModelOption } from './adapter';
-
-// ==================== 配置 ====================
-
-/** 工具批准回调函数 */
-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 {
-  /** 统一 LLM 配置（endpoints + models 降级链） */
-  llmConfig: import('./llm-config').LLMConfig;
-  /** 当前工作目录（必传，浏览器安全：不使用 process.cwd()） */
-  cwd: string;
-  /** 最大模型轮次（可选，默认不限制） */
-  maxIterations?: number;
-  /** 最大总执行时长，单位毫秒（可选，默认不限制） */
-  maxDurationMs?: number;
-  /** 最大工具调用次数（可选，默认不限制） */
-  maxToolCalls?: number;
-  /** 最大累计 token 数（可选，默认不限制） */
-  maxTotalTokens?: number;
-  /** 
-   * 工具列表（Vite 插件风格）
-   * 
-   * 支持多种形式：
-   * - 单个工具：getEnvironmentTool()
-   * - 工具插件：searchPlugin({ dataDir, workspace })
-   * - Promise：await asyncPlugin()
-   */
-  tools?: ToolConfigItem[];
-  /** 
-   * 工具批准回调（manual 模式使用）
-   * 返回 true 表示批准执行，false 表示跳过
-   */
-  onToolApprovalRequest?: ToolApprovalCallback;
-  /**
-   * 动态获取自动运行配置回调
-   * 每次检查工具批准时调用，获取最新配置
-   */
-  getAutoRunConfig?: () => Promise<AutoRunConfig | undefined>;
-  /**
-   * MCP Server 配置列表
-   * 
-   * 初始化时自动连接所有 MCP Server，发现工具并注册到 Agent。
-   */
-  mcpServers?: McpServerConfig[];
-  /**
-   * 宿主应用注入的数据引擎接口（可选）。
-   * 传递给 ToolContext.dataEngine，使所有工具可访问平台数据能力。
-   */
-  dataEngine?: DataEngineContext;
-  /**
-   * 宿主应用注入的工具执行审计钩子。
-   * 位于 ChatRuntime.executeTool 根入口，覆盖 in-process、MCP 和未来 provider。
-   */
-  audit?: ToolExecutionAuditHooks;
-}
-
-/** 深度思考模式 */
-export type ThinkingMode = 'enabled' | 'disabled';
-
-/** 自动运行模式 */
-export type AutoRunMode = 'run-everything' | 'manual';
-
-/** 自动运行配置 */
-export interface AutoRunConfig {
-  /** 
-   * 自动运行模式
-   * - 'run-everything': 运行所有内容（自动执行）
-   * - 'manual': 手动批准（每次执行前询问）
-   */
-  mode?: AutoRunMode;
-}
-
-/**
- * 用户工具定义（透传模式）
- * 
- * 只包含 schema，不包含 execute 函数
- * 由客户端执行，服务端透传 tool_call_request 事件
- */
-export interface UserToolDefinition {
-  /** 工具名称 */
-  name: string;
-  /** 工具描述（供 AI 理解） */
-  description: string;
-  /** 参数定义（JSON Schema，支持嵌套） */
-  parameters: JsonSchemaObject;
-  /** 成功时 data 内的业务结构（JSON Schema，可选） */
-  outputSchema?: JsonSchemaObject;
-  /** 成功返回标准信封结构（JSON Schema，可选，由 outputSchema 自动生成） */
-  resolvedOutputSchema?: JsonSchemaObject;
-  /** 标准错误返回结构（JSON Schema，可选；不传则使用平台默认错误结构） */
-  errorSchema?: JsonSchemaObject;
-}
-
-/** 聊天配置（每次聊天可变的选项） */
-export interface ChatOptions {
-  /** 对话模式 */
-  mode?: ChatMode;
-  /** 使用的模型 */
-  model?: string;
-  /** 模型提供商 */
-  provider?: ProtocolId;
-  /** 是否启用联网搜索 */
-  enableWebSearch?: boolean;
-  /** 
-   * 深度思考模式
-   * - 'enabled': 强制开启深度思考
-   * - 'disabled': 强制关闭深度思考
-   */
-  thinkingMode?: ThinkingMode;
-  /** 启用的工具名称列表（agent 模式有效，ask 模式强制禁用） */
-  enabledTools?: string[];
-  /**
-   * 宿主侧动态工具选择解析器。
-   * 每次模型迭代前调用，用于让 tool_enable 这类管理工具在同一轮 agent loop 的下一次模型请求生效。
-   */
-  resolveEnabledTools?: () => Promise<string[] | undefined>;
-  /** 自动运行配置 */
-  autoRunConfig?: AutoRunConfig;
-  /** 单次运行最大模型轮次；不传则使用运行时默认值 */
-  maxIterations?: number;
-  /** 单次运行最大时长（毫秒）；不传则使用运行时默认值 */
-  maxDurationMs?: number;
-  /** 单次运行最大工具调用次数；不传则使用运行时默认值 */
-  maxToolCalls?: number;
-  /** 单次运行最大累计 Token；不传则使用运行时默认值 */
-  maxTotalTokens?: number;
-  /** 对话历史（从数据库加载，无状态架构，需包含完整 tool_calls / tool_call_id） */
-  history?: ChatMessage[];
-  /**
-   * 用户自定义工具（透传模式）
-   * 
-   * 这些工具不在服务端执行，而是：
-   * 1. 传递给 AI 模型
-   * 2. AI 返回 tool_call 时，发送 tool_call_request 事件给客户端
-   * 3. 客户端执行后，发新请求继续对话
-   */
-  userTools?: UserToolDefinition[];
-  /**
-   * 上次请求的计划快照（可选，仅用于断点续传）
-   * 
-   * 正常流程不需要传：AI 会在单次请求内自主创建和管理计划。
-   * 
-   * 仅在请求被中断后需要恢复时使用：
-   * - 客户端工具透传模式（请求中断，等客户端执行后重新发请求）
-   * - 用户 abort 后想继续
-   */
-  /**
-   * 宿主平台提示词（可选）
-   * 
-   * 由宿主应用（如 SuperX）注入的平台特定 system prompt 扩展。
-   * 用于描述平台特有的能力、工具编排、记忆管理等，避免在核心库中硬编码具体工具名。
-   * 
-   * 注入位置：基础 prompt 之后、Skills 内容之前。
-   */
-  platformPrompt?: string;
-  /**
-   * Skills 内容（启用的 Skills 的 content 数组，由前端/服务端拼好传入）
-   * 
-   * 自动注入到 system prompt 的【用户指令】段落。
-   * 前端合并「默认启用的 skills + @ 手动选的 skills」后传入。
-   */
-  skillContents?: string[];
-  // 注意：每个 provider 内部使用自己的最优参数
-  // - ARK: reasoning.effort = 'high'
-  // - Qwen: thinking_budget = 38400
-  // - Gemini: thinkingLevel = 'high'
-  // 外部只需关心 thinkingMode 开关即可
-}
-
-// ==================== 工具相关 ====================
-
-/** 前端渲染组件类型：内置若干枚举，扩展 Part 使用与 `parts/<name>` 一致的任意字符串 */
-export type RenderType = 'weather' | 'chart' | 'browser' | 'plan' | string;
-
-/** 前端动作类型（可扩展） */
-export type ActionType = 'toast' | 'notification' | 'reload' | string;
-
-/**
- * 工具 UI 声明（互斥）
- * - render: 在对话流中渲染自定义组件
- * - action: 触发前端动作（通知、刷新等）
- */
-export type ToolUI =
-  | {
-    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 命令执行结果 */
-export interface ExecResult {
-  stdout: string;
-  stderr: string;
-  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[], 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'
-  | 'PERMISSION_DENIED'
-  | 'OPERATION_FAILED'
-  | 'TIMEOUT'
-  | 'NETWORK_ERROR'
-  | (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 class ToolException extends Error {
-  readonly toolError: ToolError;
-
-  constructor(toolError: ToolError) {
-    super(toolError.message);
-    this.name = 'ToolException';
-    this.toolError = toolError;
-  }
-}
-
-/** 判断是否为结构化工具错误 */
-export function isToolError(e: unknown): e is ToolException {
-  return e instanceof ToolException;
-}
-
-/**
- * 抛出结构化工具错误
- *
- * @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 对象类型（工具参数的根类型） */
-export interface JsonSchemaObject {
-  type: 'object';
-  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;
-}
-
-/**
- * 工具接口
- * 
- * @example
- * ```typescript
- * const myTool: Tool = {
- *   name: 'my_tool',
- *   description: '我的自定义工具',
- *   parameters: { type: 'object', properties: { query: { type: 'string' } }, required: ['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: 在对话流中渲染自定义组件
-   * - action: 执行成功后触发前端动作
-   */
-  ui?: ToolUI;
-  /**
-   * 是否需要用户手动批准（覆盖全局 autoRunMode）
-   * 
-   * 设为 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;
-  /**
-   * 执行函数
-   * 
-   * 成功返回 ToolResult 或普通对象，框架会统一规范化后再传给 LLM。
-   * 失败统一 throw（推荐使用 throwToolError()）。
-   */
-  execute: (args: Record<string, unknown>, context: ToolContext) => Promise<ToolExecuteResult>;
-}
-
-/** 工具执行器接口（供 Agent 内部使用，自定义命令执行环境） */
-export interface ToolExecutor {
-  /** 执行 Shell 命令 */
-  executeCommand(
-    command: string,
-    cwd?: string,
-    signal?: AbortSignal,
-    hooks?: {
-      onStdout?: (chunk: string) => void;
-      onStderr?: (chunk: string) => void;
-    },
-    timeout?: number,
-  ): Promise<{ success: boolean; output?: string; error?: string }>;
-}
-
-// ==================== 工具插件（Vite 插件风格） ====================
-
-/**
- * 工具插件实例
- * 
- * 由 createXxxPlugin() 返回，可直接在 tools 数组中展开使用
- */
-export interface ToolPlugin {
-  /** 插件提供的工具数组 */
-  tools: Tool[];
-  /** 插件控制方法（可选，由各插件自定义） */
-  [key: string]: unknown;
-}
-
-/**
- * 创建单个工具插件（辅助函数）
- * 
- * @example
- * ```typescript
- * export function getEnvironmentTool(): ToolPlugin {
- *   return tool({
- *     name: 'get_environment',
- *     description: '...',
- *     parameters: { ... },
- *     execute: async (args, context) => { ... }
- *   });
- * }
- * ```
- */
-export function tool(t: Tool): ToolPlugin {
-  return { tools: [t] };
-}
-
-/**
- * 创建多个工具插件（辅助函数）
- * 
- * @example
- * ```typescript
- * export function myPlugin(): ToolPlugin {
- *   return tools([
- *     { name: 'tool1', ... },
- *     { name: 'tool2', ... },
- *   ]);
- * }
- * ```
- */
-export function tools(ts: Tool[]): ToolPlugin {
-  return { tools: ts };
-}
-
-/**
- * 工具配置项（Vite 插件风格，只支持插件形式）
- * 
- * @example
- * ```typescript
- * tools: [
- *   getEnvironmentTool(),                   // 工具插件（函数调用）
- *   searchPlugin({ dataDir, workspace }), // 异步插件（返回 Promise<ToolPlugin>）
- * ]
- * ```
- */
-export type ToolConfigItem = Tool | ToolPlugin | Promise<Tool | ToolPlugin>;
-
-/**
- * 解析工具配置，统一转换为 Tool[]
- * 
- * 支持三种形式：
- * - Tool: 单个工具（直接使用）
- * - ToolPlugin: 工具插件（展开 .tools 数组）
- * - 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);
-    } else if ('name' in resolved && 'execute' in resolved) {
-      // Tool
-      tools.push(resolved as Tool);
-    } else {
-      console.warn('无法识别的工具配置项:', resolved);
-    }
-  }
-
-  return tools;
-}
-
-/** 工具定义（OpenAI 格式，内部使用） */
-export interface ToolDefinition {
-  type: 'function';
-  function: {
-    name: string;
-    description: string;
-    parameters: JsonSchemaObject;
-  };
-}
-
-// ==================== 消息相关 ====================
-
-/** 聊天消息（内部格式） */
-export interface ChatMessage {
-  /** 消息 ID */
-  id?: string;
-  role: 'system' | 'user' | 'assistant' | 'tool';
-  content: string;
-  /** 深度思考内容 */
-  reasoning_content?: string;
-  tool_call_id?: string;
-  tool_calls?: Array<{
-    id: string;
-    type: 'function';
-    function: {
-      name: string;
-      arguments: string;
-    };
-    /** Gemini 模型需要的 thought_signature（用于工具调用循环） */
-    thought_signature?: string;
-  }>;
-}
-
-// ==================== API 特定类型 ====================
-
-/** 火山引擎 Responses API 工具定义 */
-export interface ResponsesApiTool {
-  type: 'function';
-  name?: string;
-  description?: string;
-  parameters?: Record<string, unknown>;
-}