工具系统架构

export function createMoltbotCodingTools(params: {
  exec: ExecFunction;
  sandbox: SandboxContext | null;
  messageProvider?: string;
  ...}): ToolCollection {
  // 1. 解析工具策略
  // 2. 构建基础工具
  // 3. 应用策略过滤
  // 4. 包装 Abort Signal
  // 5. 返回工具集合
}

// 匹配所有 bash 相关工具
"bash*"

// 匹配 sessions 开头的工具
"sessions_*"

// 匹配除了 session 开头的所有工具
"!sessions_*"

// 多个模式
["bash*", "read", "write"]

// 沙箱工具包装器
function wrapSandboxTool(tool: AnyAgentTool, ctx: SandboxContext): AnyAgentTool {
  return {
    name: tool.name,
    description: tool.description,
    parameters: tool.parameters,
    handler: async (args, signal) => {
      if (!ctx.enabled) {
        throw new Error("Sandbox not enabled");
      }

      // 在沙箱容器中执行
      return await executeInSandbox({
        containerName: ctx.containerName,
        toolName: tool.name,
        args,
        signal,
      });
    },
  };
}

// 工具执行超时控制
const TOOL_TIMEOUT_MS = 120_000; // 2 分钟

async function executeToolWithTimeout(
  tool: AnyAgentTool,
Handler,
  args: unknown,
  signal: AbortSignal,
): Promise<ToolResult> {
  const timeoutSignal = AbortSignal.timeout(TOOL_TIMEOUT_MS);

  // 组合多个信号
  const combinedSignal = combineSignals([signal, timeoutSignal]);

  return await toolHandler(args, combinedSignal);
}

// 插件注册工具
api.registerTool({
  name: "my_tool",
  description: "My custom tool",
  parameters: {
    type: "object",
    properties: {
      input: {
        type: "string",
        description: "Input string"
      }
    },
    required: ["input"]
  },
}, {
  name: "my_tool",      // 工具名（用于引用）
  names: ["alias1"],   // 别名列表
  optional: true,        // 是否可选
});

// 工具工厂函数
export type MoltbotPluginToolFactory = (
  ctx: MoltbotPluginToolContext,
) => AnyAgentTool | AnyAgentTool[] | null | undefined;

// Channel 插件提供 Agent 工具
export type ChannelPlugin<ResolvedAccount = any> = {
  agentTools?: ChannelAgentToolFactory | ChannelAgentTool[];
  // ...
};

export type AnyAgentTool = {
  name: string;
  description: string;
  parameters?: {
    type: "object";
    properties?: Record<string, ToolParameter>;
    required?: string[];
    additionalProperties?: boolean;
  };
  handler: (args: unknown, signal: AbortSignal) => Promise<ToolResult>;
  // 可选字段
  category?: string;
  hidden?: boolean;
  experimental?: boolean;
};

export type ToolParameter = {
  type: "string" | "number" | "boolean" | "array" | "object";
  description?: string;
  enum?: string[];
  default?: unknown;
  format?: string;
  minimum?: number;
  maximum?: number;
  // 可选字段
  hidden?: boolean;
};

export type ToolResult = {
  content: string;
  is_error?: boolean;
  data?: Record<string, unknown>;
  // 可选字段
  attachments?: MediaAttachment[];
};

// 工具按类别分组
export const TOOL_CATEGORIES = {
  "file-system": "文件系统操作",
  "execution": "命令执行",
  "browser": "浏览器控制",
  "canvas": "Canvas 操作",
  "sessions": "会话管理",
  "channels": "渠道消息",
  "nodes": "远程节点",
  "cron": "定时任务",
  "discord": "Discord API",
  "web": "Web 请求",
};

// 动态生成工具描述
function generateToolDescription(tool: AnyAgentTool, ctx: ToolContext): string {
  let desc = tool.description;

  // 添加 Sandbox 信息
  if (ctx.inSandbox) {
    desc += " (在沙箱容器中运行)";
  }

  // 添加权限信息
  if (ctx.requiresApproval) {
    desc += " (需要执行批准)";
  }

  return desc;
}