Copyinterface ToolDefinition {
  name: string
  description: string  // AI 靠这段文字理解工具用途
  parameters: {
    type: 'object'
    properties: Record<string, { type: string; description: string }>
    required: string[]
  }
  type: 'read' | 'write'  // 读操作 / 写操作
  roles: string[]          // 哪些角色可以调用
}
 
const tools: ToolDefinition[] = [
  {
    name: 'queryWorkOrder',
    description: '根据房号查询该户主的所有维修工单。返回工单列表，包括工单号、状态、创建时间',
    parameters: {
      type: 'object',
      properties: {
        houseId: { type: 'string', description: '房号，如 3-501' }
      },
      required: ['houseId']
    },
    type: 'read',
    roles: ['finance', 'customer_service', 'manager', 'supervisor']
  },
  {
    name: 'createWorkOrder',
    description: '创建一个新的维修工单。需要提供房号、工单类型和问题描述',
    parameters: {
      type: 'object',
      properties: {
        houseId: { type: 'string', description: '房号' },
        type: { type: 'string', description: '工单类型：water/electric/carpentry/gas/other' },
        description: { type: 'string', description: '问题描述' }
      },
      required: ['houseId', 'type', 'description']
    },
    type: 'write',
    roles: ['customer_service', 'manager']
  },
  // ... 其余 10 个工具类似定义
]

Copyasync function agentLoop(
  message: string,
  role: string,
  history: Message[]
): Promise<AgentResponse> {
  // 1. 获取该角色可用的工具白名单
  const availableTools = tools.filter(t => t.roles.includes(role))
 
  // 2. 构建请求，带上工具定义
  const response = await aiClient.chat({
    messages: [
      { role: 'system', content: getSystemPrompt(role) },
      ...history,
      { role: 'user', content: message }
    ],
    tools: availableTools,
    tool_choice: 'auto'  // AI 自己判断是否需要调工具
  })
 
  // 3. 判断 AI 是否要调工具
  const toolCalls = response.tool_calls || []
  if (toolCalls.length === 0) {
    // 纯文本回复，直接返回
    return { type: 'text', content: response.content }
  }
 
  // 4. 处理工具调用
  const results: ToolResult[] = []
  for (const toolCall of toolCalls) {
    // 4a. 权限二次校验（防止 AI 绕过角色限制）
    const toolDef = tools.find(t => t.name === toolCall.name)
    if (!toolDef || !toolDef.roles.includes(role)) {
      results.push({
        tool_call_id: toolCall.id,
        error: '你没有权限执行此操作'
      })
      continue
    }
 
    // 4b. 参数校验
    const validationError = validateParams(toolCall.params, toolDef.parameters)
    if (validationError) {
      results.push({
        tool_call_id: toolCall.id,
        error: `参数错误: ${validationError}`
      })
      continue
    }
 
    // 4c. 写操作需要用户确认
    if (toolDef.type === 'write') {
      return {
        type: 'confirm',
        tool_name: toolCall.name,
        params: toolCall.params,
        message: `即将执行【${toolDef.name}】操作，请确认参数:\n${
          JSON.stringify(toolCall.params, null, 2)
        }`
      }
    }
 
    // 4d. 读操作自动执行
    const data = await executeTool(toolCall.name, toolCall.params)
    results.push({
      tool_call_id: toolCall.id,
      output: JSON.stringify(data)
    })
  }
 
  // 5. 把工具执行结果喂回 AI，让它生成最终回答
  const finalResponse = await aiClient.chat({
    messages: [
      ...response.messages,
      { role: 'tool', content: results }
    ],
    tools: []  // 第二轮不允许再调工具，防止死循环
  })
 
  // 6. 判断是否需要渲染数据卡片
  const card = buildCard(finalResponse.content, results)
  return {
    type: card ? 'card' : 'text',
    content: finalResponse.content,
    card: card
  }
}

Copyif (!toolDef.roles.includes(role)) {
  // 不管 AI 怎么想，后端不允许就是不允许
}

Copyfunction buildCard(toolResults: ToolResult[]): CardData | null {
  const lastResult = toolResults[toolResults.length - 1]
 
  // 工单查询 → 工单卡片
  if (lastResult.type === 'work_order') {
    return {
      component: 'WorkOrderCard',
      props: { orders: lastResult.data }
    }
  }
 
  // 财务查询 → 账单汇总卡片
  if (lastResult.type === 'bill') {
    return {
      component: 'BillSummaryCard',
      props: { bills: lastResult.data }
    }
  }
 
  return null  // 纯文本回复，不渲染卡片
}