Function Calling 全链路实现：工具注册表、参数解析与并发派发

[Host JS Runtime] ──(1. 发送 messages + tools JSON Schema)──► [LLM API]
[Host JS Runtime] ◄─(2. 返回 finish_reason: "tool_calls"   )── [LLM API]
                      tool_calls: [
                        { id: "call_1", name: "getWeather", args: '{"city":"Seoul"}' },
                        { id: "call_2", name: "getStock",   args: '{"ticker":"AAPL"}' }
                      ]
[Host JS Runtime] ──(3. 本地并行执行 getWeather & getStock )
[Host JS Runtime] ──(4. 附带对应 tool_call_id 写回两条 role:"tool" 消息)──► [LLM API]

export class ToolRegistry {
  constructor() {
    this.tools = new Map()
  }

  register({ name, description, schema, execute, timeoutMs = 10000, readOnly = true }) {
    if (!/^[a-zA-Z0-9_-]{1,64}$/.test(name)) {
      throw new Error(`非法工具名 "${name}"：仅允许字母、数字、下划线与连字符`)
    }
    this.tools.set(name, { name, description, schema, execute, timeoutMs, readOnly })
    return this
  }

  // 导出供 OpenAI / 兼容接口使用的 tools 声明数组
  toOpenAiTools() {
    return [...this.tools.values()].map((t) => ({
      type: 'function',
      function: {
        name: t.name,
        description: t.description,
        parameters: {
          type: 'object',
          properties: t.schema.properties || {},
          required: t.schema.required || []
        }
      }
    }))
  }

  // 带超时保护与 Schema 校验的单工具执行器
  async invokeOne(toolCall, context = {}) {
    const start = Date.now()
    const { id, function: fn } = toolCall
    const tool = this.tools.get(fn?.name)

    if (!tool) {
      return {
        role: 'tool',
        tool_call_id: id,
        name: fn?.name || 'unknown',
        content: JSON.stringify({ ok: false, error: `未知工具 "${fn?.name}"` })
      }
    }

    let args
    try {
      args = typeof fn.arguments === 'string' ? JSON.parse(fn.arguments || '{}') : (fn.arguments || {})
    } catch (err) {
      return {
        role: 'tool',
        tool_call_id: id,
        name: tool.name,
        content: JSON.stringify({ ok: false, error: `工具参数 JSON 解析失败: ${err.message}` })
      }
    }

    if (tool.schema?.validate) {
      const validationErrors = tool.schema.validate(args)
      if (validationErrors.length > 0) {
        return {
          role: 'tool',
          tool_call_id: id,
          name: tool.name,
          content: JSON.stringify({ ok: false, error: '参数校验未通过', details: validationErrors })
        }
      }
    }

    try {
      const result = await Promise.race([
        Promise.resolve(tool.execute(args, context)),
        new Promise((_, reject) =>
          setTimeout(() => reject(new Error(`工具 ${tool.name} 执行超过 ${tool.timeoutMs}ms 超时上限`)), tool.timeoutMs)
        )
      ])
      return {
        role: 'tool',
        tool_call_id: id,
        name: tool.name,
        content: JSON.stringify({ ok: true, data: result, durationMs: Date.now() - start })
      }
    } catch (err) {
      return {
        role: 'tool',
        tool_call_id: id,
        name: tool.name,
        content: JSON.stringify({ ok: false, error: err.message, durationMs: Date.now() - start })
      }
    }
  }

  // 并行派发模型在单轮中请求的所有 tool_calls，严格保持原顺序返回
  async dispatchAll(toolCalls = [], context = {}) {
    return Promise.all(toolCalls.map((tc) => this.invokeOne(tc, context)))
  }
}