手写 ReAct（Reasoning + Acting）引擎：思考-行动-观察状态机

export class ReActEngine {
  constructor({ llm, registry, maxSteps = 10, onStepEvent }) {
    this.llm = llm
    this.registry = registry
    this.maxSteps = maxSteps
    this.onStepEvent = onStepEvent
  }

  #buildActionSignature(name, rawArgs) {
    try {
      const obj = typeof rawArgs === 'string' ? JSON.parse(rawArgs || '{}') : rawArgs
      const sortedKeys = Object.keys(obj).sort()
      const normalized = sortedKeys.map((k) => `${k}:${JSON.stringify(obj[k])}`).join('|')
      return `${name}(${normalized})`
    } catch {
      return `${name}(${String(rawArgs).trim()})`
    }
  }

  async solve(question) {
    const systemPrompt = [
      '你是一个严格遵循 ReAct（思考-行动-观察）范式的智能体。',
      '每次调用工具前，请先在 content 中简要写出你的【思考 Thought】：目前已知什么、下一步为什么要调该工具。',
      '如果某个工具返回空结果或报错，严禁使用完全相同的参数重复调用，请更换查询词或换用其他工具。'
    ].join('\n')

    const messages = [
      { role: 'system', content: systemPrompt },
      { role: 'user', content: question }
    ]

    // 记录已执行过的 (工具名 + 归一化参数) 签名及其返回结果
    const executedSignatures = new Map()
    const trajectory = []

    for (let step = 1; step <= this.maxSteps; step++) {
      const response = await this.llm.chat({
        messages,
        tools: this.registry.toOpenAiTools()
      })

      const msg = response.message
      messages.push(msg)

      const thought = (msg.content || '').trim()
      if (thought) {
        this.onStepEvent?.({ type: 'thought', step, content: thought })
      }

      // 若无工具调用，说明推理收敛，直接输出最终答案
      if (!msg.tool_calls || msg.tool_calls.length === 0) {
        this.onStepEvent?.({ type: 'final_answer', step, content: thought })
        return { ok: true, steps: step, answer: thought, trajectory }
      }

      const toolMessages = []
      for (const tc of msg.tool_calls) {
        const sig = this.#buildActionSignature(tc.function.name, tc.function.arguments)

        // 死循环拦截：若之前已用完全相同的参数调用过该工具，直接拦截并注入换思路指令
        if (executedSignatures.has(sig)) {
          const prevResult = executedSignatures.get(sig)
          const warning = JSON.stringify({
            ok: false,
            loopDetected: true,
            warning: `禁止重复调用！你在第 ${prevResult.step} 步已执行过完全相同的调用 ${sig}，当时结果为：${prevResult.summary}。请立即更换参数或基于现有信息直接回答。`
          })
          this.onStepEvent?.({ type: 'loop_blocked', step, signature: sig })
          toolMessages.push({
            role: 'tool',
            tool_call_id: tc.id,
            name: tc.function.name,
            content: warning
          })
          continue
        }

        // 正常执行工具并记录签名
        this.onStepEvent?.({ type: 'action', step, tool: tc.function.name, args: tc.function.arguments })
        const toolMsg = await this.registry.invokeOne(tc)
        executedSignatures.set(sig, {
          step,
          summary: toolMsg.content.slice(0, 160)
        })
        this.onStepEvent?.({ type: 'observation', step, tool: tc.function.name, output: toolMsg.content })
        toolMessages.push(toolMsg)
      }

      messages.push(...toolMessages)
    }

    return {
      ok: false,
      steps: this.maxSteps,
      answer: '达到最大推理步数上限，任务未能在预算内收敛。',
      trajectory
    }
  }
}