Agent

┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│  2022 年末   │ → │  2023 年初   │ → │  2023 年中   │ → │  2024-2025  │
│  ChatGPT    │ → │  AutoGPT    │ → │  框架成熟    │ → │  企业落地   │
│  对话范式    │ → │  Agent 爆发  │ → │  LangChain   │ → │  长时间运行  │
└─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘

问题：ChatGPT 只能"说话"，不能"做事"

ChatGPT 模式：
  用户："帮我查一下今天的天气"
  模型："我无法访问实时数据"  ← 模型只能生成文本，不能执行操作

解决：Agent 模式 = LLM 做决策 + 工具做执行

Agent 模式：
  用户："帮我查一下今天的天气"
  模型：调用 getWeatherTool() → 获取天气数据 → 生成回答
  模型："今天北京晴，25°C"  ← 模型决策 + 工具执行

┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐
│   2023-2024     │ → │   2025 初       │ → │   2025 中       │ → │   2025 至今     │
│   AI 编程工具    │ → │   Claude Code   │ → │   OpenAI Codex   │ → │   社区标准化    │
│   各自为政      │ → │   CLAUDE.md     │ → │   AGENTS.md     │ → │   AGENT.md      │
└─────────────────┘   └─────────────────┘   └─────────────────┘   └─────────────────┘

问题：每个 AI 编程工具都有自己的配置文件，互不兼容

CLAUDE.md（Anthropic 专有）：
  适用于 Claude Code
  定义 Agent 的角色、工具、规则
  其他工具无法识别

AGENTS.md（OpenAI 专有）：
  适用于 Codex
  定义 Agent 的角色、工具、规则
  其他工具无法识别

解决：AGENT.md（通用格式）

AGENT.md（社区标准）：
  适用于所有 AI 编程工具（Claude Code、Codex、Amp 等）
  定义 Agent 的角色、工具、规则
  跨工具通用，一份配置到处生效

AGENT.md 文件内容：

┌──────────────────────────────────────────────┐
│              AGENT.md                         │
│                                               │
│  1. 角色定义                                  │
│     "你是一个前端开发 Agent"                   │
│                                               │
│  2. 可用工具                                  │
│     读写文件、执行命令、搜索代码               │
│                                               │
│  3. 行为约束                                  │
│     不要修改 node_modules                     │
│     commit 前必须运行测试                     │
│                                               │
│  4. 上下文信息                                │
│     项目使用 React 19 + TypeScript            │
│     代码规范：ESLint + Prettier               │
└──────────────────────────────────────────────┘

<!-- AGENT.md 示例：项目根目录下的 Agent 配置文件 -->

# Agent 配置

## 角色与职责

你是一个前端开发 Agent，负责代码开发、测试编写和代码审查。

## 可用工具

- 文件读写（Read, Write, Edit）
- 终端命令（Bash）
- 代码搜索（Grep, Glob）

## 行为约束

- 不要修改 `node_modules/` 和 `.git/` 目录
- 每次修改代码后必须运行相关测试
- commit message 使用 Conventional Commits 规范
- 不要直接推送到 main 分支

## 上下文信息

- 项目框架：React 19 + TypeScript 5.x
- 构建工具：Vite 6
- 测试框架：Vitest + React Testing Library
- 代码规范：ESLint + Prettier

┌───────────────────────────────────────────────┐
│                  Agent Loop                    │
│                                                │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐ │
│  │  LLM     │ →  │ Planning │ →  │  Tools   │ │
│  │  理解意图 │    │  规划步骤 │    │  执行操作 │ │
│  └──────────┘    └──────────┘    └──────────┘ │
│       ↑                                │       │
│       │         ┌──────────┐           │       │
│       └──────── │  Memory  │ ←─────────┘       │
│                 │  记忆管理 │                    │
│                 └──────────┘                    │
└───────────────────────────────────────────────┘

# ============================================================
# Agent 核心循环：ReAct 模式（Reasoning + Acting）完整实现
# 比喻：Agent 就像项目经理带团队——
#   LLM 是项目经理的大脑（理解需求、规划步骤）
#   Tools 是团队成员（搜索=调研员，代码=开发，文档=写手）
#   Memory 是笔记本（记住之前做了什么）
#   ReAct 循环的工作方式：分析问题 → 分配任务 → 收集结果 → 再分析
#
# ASCII 流程图：
# ┌───────────────────────────────────────────────┐
# │                  Agent Loop                    │
# │                                                │
# │  用户目标 → LLM 思考 → 调用工具 → 获取结果     │
# │       ↑                                │       │
# │       │         记忆更新                 │       │
# │       └─────────────────────────────────┘       │
# │                                                │
# │  循环直到：任务完成 / 达到最大轮次              │
# └───────────────────────────────────────────────┘
# ============================================================
from typing import TypedDict, Annotated
from langchain_core.messages import HumanMessage, AIMessage, ToolMessage

class AgentState(TypedDict):
    """Agent 的状态定义"""
    messages: list         # 对话历史（包括用户、AI、工具调用结果）
    memory: list           # 短期记忆（记录每步做了什么）
    step: int              # 当前步骤数
    completed: bool        # 任务是否完成

async def agent_loop(user_goal: str, tools: list, llm, max_iterations: int = 10):
    """
    Agent 的核心执行循环（ReAct 模式）

    参数：
        user_goal: 用户的目标（如"帮我写一份竞品分析报告"）
        tools: 可用工具列表（搜索、读文件、写文件等）
        llm: 大语言模型实例
        max_iterations: 最大循环次数（防止死循环！这是最重要的安全阀）

    返回：
        最终答案字符串

    关键细节：
        1. 必须设置 max_iterations，否则 Agent 可能无限循环消耗 Token
        2. 每次工具调用的结果都要存回 messages，让 LLM 知道之前做了什么
        3. 如果 LLM 返回的 tool_calls 为空，说明任务完成，直接返回答案
    """
    # 初始化状态
    messages = [HumanMessage(content=user_goal)]  # 用户目标作为第一条消息
    memory = []  # 记录每步的工具调用和结果

    for step in range(max_iterations):
        # --- 第 1 步：Reasoning（推理）---
        # LLM 分析当前状态，决定下一步该做什么
        # 比喻：项目经理看了之前的进展，决定下一步该派谁做什么
        response = await llm.ainvoke(messages)

        # --- 第 2 步：判断是否完成 ---
        # 如果 LLM 没有调用任何工具，说明它认为任务完成了
        if not response.tool_calls:
            return response.content  # 返回最终答案

        # --- 第 3 步：Acting（执行）---
        # LLM 选择了要调用的工具和参数，现在真正执行
        # AI 的工具调用请求只追加一次，不要放进下面的循环里
        messages.append(response)
        for tool_call in response.tool_calls:
            # 找到对应的工具
            tool = next(t for t in tools if t.name == tool_call["name"])

            # 执行工具（可能调用 API、读文件、搜索等）
            result = await tool.ainvoke(tool_call["args"])

            # --- 第 4 步：Observing（观察）---
            # 把工具执行结果存回对话历史，让 LLM 知道结果
            # 比喻：调研员把调研报告交回给项目经理
            messages.append(ToolMessage(  # 工具的执行结果
                content=str(result),
                tool_call_id=tool_call["id"],
            ))

            # 更新记忆
            memory.append({
                "step": step,
                "tool": tool_call["name"],
                "args": tool_call["args"],
                "result": str(result)[:500],  # 只记前 500 字符，避免记忆膨胀
            })

        # 循环回到第 1 步，LLM 根据工具结果决定下一步

    # 达到最大循环次数，强制终止
    raise RuntimeError(
        f"Agent 达到最大循环次数 ({max_iterations})，任务未完成。"
        f"已执行 {len(memory)} 次工具调用。最后一步: {memory[-1] if memory else '无'}"
    )

# --- 重要细节 ---
# 1. max_iterations 是最重要的安全阀——没有它 Agent 可能无限循环
# 2. 典型值：简单任务 5-10 次，复杂任务 20-50 次
# 3. 如果 Agent 反复调用同一个工具且结果不变，说明可能进入了死循环

// Agent 的核心循环：ReAct 模式（Reasoning + Acting）
async function agentLoop(userGoal, tools, maxIterations = 10) {
  const messages = [{ role: "user", content: userGoal }];
  const memory = []; // 短期记忆

  for (let i = 0; i < maxIterations; i++) {
    // 1. Reasoning：LLM 分析当前状态，决定下一步
    const response = await llm.invoke(messages);

    // 2. 判断：是否需要继续执行
    if (response.tool_calls.length === 0) {
      return response.content; // 任务完成，返回最终结果
    }

    // 3. Acting：执行工具调用
    for (const toolCall of response.tool_calls) {
      const tool = tools.find((t) => t.name === toolCall.name);
      const result = await tool.invoke(toolCall.args);

      // 4. 记忆：把结果存入上下文
      messages.push({
        role: "tool",
        tool_call_id: toolCall.id,
        content: JSON.stringify(result),
      });
      memory.push({ tool: toolCall.name, result });
    }
    // 循环：回到步骤 1，LLM 根据工具结果决定下一步
  }

  throw new Error("Agent 达到最大循环次数，任务未完成");
}

// 工具定义：告诉 LLM 有哪些工具可用
const tools = [
  {
    name: "searchWeb",
    description: "搜索互联网获取最新信息",
    parameters: {
      type: "object",
      properties: {
        query: { type: "string", description: "搜索关键词" },
      },
      required: ["query"],
    },
  },
  {
    name: "readFile",
    description: "读取本地文件内容",
    parameters: {
      type: "object",
      properties: {
        path: { type: "string", description: "文件路径" },
      },
      required: ["path"],
    },
  },
  {
    name: "writeFile",
    description: "写入文件内容",
    parameters: {
      type: "object",
      properties: {
        path: { type: "string", description: "文件路径" },
        content: { type: "string", description: "文件内容" },
      },
      required: ["path", "content"],
    },
  },
];

// LLM 的工具调用输出（结构化 JSON）
// 用户："帮我搜索最新的 React 19 特性，然后写到文件里"
// LLM 输出：
const llmOutput = {
  tool_calls: [
    {
      name: "searchWeb",
      args: { query: "React 19 new features 2024" },
    },
  ],
};

// 4 层记忆模型
const memorySystem = {
  // 1. Working Memory（工作记忆）：当前对话的上下文
  working: [], // 当前 LLM 调用的消息历史，容量有限（128K/200K tokens）

  // 2. Episodic Memory（情景记忆）：过去任务的具体经历
  episodic: [], // "上次查天气时用了 searchWeb 工具，返回了 JSON 格式"

  // 3. Semantic Memory（语义记忆）：抽象的知识和经验
  semantic: [], // "搜索工具的 query 要用英文效果更好"

  // 4. Procedural Memory（程序记忆）：如何执行任务的流程
  procedural: [], // "查竞品报告的标准流程：搜索 → 提取 → 分析 → 写报告"
};

// 短期记忆 = Working Memory（当前对话上下文）
// 长期记忆 = Episodic + Semantic + Procedural（持久化存储）

// 长期记忆的压缩策略
async function compressMemory(memory) {
  // 用小模型把 100K tokens 的历史压缩为 5K tokens 的摘要
  const summary = await smallLLM.invoke(
    `总结以下对话历史的关键信息，压缩到 500 字以内：\n${memory}`,
  );
  return summary;
}

// 规划模式对比
const planningStrategies = {
  // 1. 一次性规划（Plan-and-Execute）：先制定完整计划，再逐步执行
  planAndExecute: {
    flow: "用户目标 → LLM 制定完整计划 → 逐步执行 → 汇总结果",
    pros: "计划清晰、可控性强",
    cons: "计划可能过时（执行过程中情况变化）",
  },

  // 2. 动态规划（ReAct）：每一步都重新评估，动态调整
  react: {
    flow: "用户目标 → 思考 → 行动 → 观察 → 再思考 → ...",
    pros: "灵活应变、能处理意外情况",
    cons: "可能偏离目标、循环次数不可预测",
  },

  // 3. 分层规划（Hierarchical）：高层规划拆子任务，底层执行
  hierarchical: {
    flow: "用户目标 → 拆子任务 → 每个子任务独立规划执行 → 汇总",
    pros: "适合复杂大任务",
    cons: "实现复杂度高",
  },
};

┌──────────────────────────────────────────────────────┐
│              Enterprise-grade Agent                   │
│                                                       │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐        │
│  │ 权限收敛   │ │ 审计日志   │ │ 容错降级   │        │
│  │ 最小权限   │ │ 操作留痕   │ │ Fallback   │        │
│  └────────────┘ └────────────┘ └────────────┘        │
│  ┌────────────┐ ┌────────────┐                       │
│  │ 确定性边界 │ │ 成本控制   │                       │
│  │ 规则兜底   │ │ Token 预算 │                       │
│  └────────────┘ └────────────┘                       │
└──────────────────────────────────────────────────────┘

// 企业级 Agent 的权限分层设计
const agentPermissions = {
  // 代码审查 Agent：只有读权限，没有写权限
  codeReviewer: {
    tools: ["readFile", "searchCode", "listFiles"],
    // 禁止：writeFile, executeCommand, deploy
    scope: { repositories: ["frontend/*"], branches: ["feature/*"] },
  },

  // 部署 Agent：只能操作 staging 环境
  deployer: {
    tools: ["deploy", "rollback", "checkHealth"],
    scope: { environments: ["staging"], exclude: ["production"] },
    // 生产环境部署需要人工审批
    requiresApproval: ["production"],
  },

  // 数据分析 Agent：只有查询权限
  dataAnalyst: {
    tools: ["queryDatabase", "exportCSV"],
    scope: { databases: ["analytics"], operations: ["SELECT"] },
    // 禁止：INSERT, UPDATE, DELETE
  },
};

// 工具级别的权限校验
function validateToolAccess(agentRole, toolName, args) {
  const permissions = agentPermissions[agentRole];
  if (!permissions.tools.includes(toolName)) {
    throw new PermissionError(`Agent ${agentRole} 无权调用 ${toolName}`);
  }
  if (!validateScope(permissions.scope, args)) {
    throw new ScopeError(`操作超出 Agent ${agentRole} 的权限范围`);
  }
  return true;
}

// 审计日志的数据结构
function auditLog(agentId, action) {
  const logEntry = {
    timestamp: new Date().toISOString(),
    agentId,
    runId: action.runId, // 关联同一次执行的所有操作
    step: action.step, // 当前步骤编号
    tool: action.toolName, // 调用的工具
    input: action.args, // 工具输入
    output: action.result, // 工具输出
    tokenUsage: action.tokens, // Token 消耗
    duration: action.durationMs, // 执行耗时
    status: action.status, // success / failure / timeout
    humanApproval: action.approved, // 是否经过人工审批
  };

  // 写入审计日志存储（不可篡改）
  appendToAuditLog(logEntry);
  return logEntry;
}

// 多层降级策略
async function executeWithFallback(agent, task) {
  try {
    // 第 1 层：主模型 + 完整工具集
    return await agent.invoke(task, { model: "gpt-4o", fullTools: true });
  } catch (primaryError) {
    try {
      // 第 2 层：备用模型 + 精简工具集
      return await agent.invoke(task, {
        model: "gpt-4o-mini",
        basicTools: true,
      });
    } catch (secondaryError) {
      try {
        // 第 3 层：规则引擎（完全确定性，不依赖 LLM）
        return await ruleEngine.process(task);
      } catch (ruleError) {
        // 第 4 层：返回默认响应 + 人工工单
        const ticketId = await createHumanTicket(task, {
          primaryError,
          secondaryError,
        });
        return { message: "任务已提交人工处理", ticketId };
      }
    }
  }
}

┌─────────────────────────────────────────────────┐
│           确定性边界分层架构                       │
│                                                  │
│  ┌──────────────────────────────────────┐        │
│  │  理解层（LLM，不确定性）              │        │
│  │  LLM 只负责理解意图、提取结构化信息    │        │
│  └──────────────┬───────────────────────┘        │
│                  ↓ LLM 输出                      │
│  ┌──────────────────────────────────────┐        │
│  │  验证层（Schema，半确定性）            │        │
│  │  JSON Schema 校验、格式检查            │        │
│  └──────────────┬───────────────────────┘        │
│                  ↓ 校验通过                      │
│  ┌──────────────────────────────────────┐        │
│  │  执行层（规则引擎，确定性）            │        │
│  │  工具调用、数据操作、业务逻辑          │        │
│  └──────────────────────────────────────┘        │
└─────────────────────────────────────────────────┘

// Token 预算管理
const tokenBudget = {
  // 全局预算
  daily: 1_000_000, // 每天最多 100 万 tokens
  perRequest: 10_000, // 单次请求最多 1 万 tokens
  perAgent: 50_000, // 单个 Agent 最多 5 万 tokens

  // 模型分级
  models: {
    simple: "gpt-4o-mini", // 简单任务用便宜模型（便宜 10 倍）
    complex: "gpt-4o", // 复杂任务用强模型
  },
};

// Token 预算检查
function checkBudget(agentId, estimatedTokens) {
  const used = getDailyUsage(agentId);
  if (used + estimatedTokens > tokenBudget.daily) {
    throw new BudgetExceededError(
      `Agent ${agentId} 已用 ${used} tokens，超出每日预算`,
    );
  }
}

// 模型分级选择
function selectModel(taskComplexity) {
  if (taskComplexity === "simple") return tokenBudget.models.simple;
  return tokenBudget.models.complex;
}

┌───────────────────────────────────────────────────────┐
│           Long-running Agent 架构                      │
│                                                        │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐          │
│  │ 异步执行  │ → │ 状态快照  │ → │ 断点续传  │          │
│  │ 不阻塞   │   │ Checkpoint│   │ Recovery │          │
│  └──────────┘   └──────────┘   └──────────┘          │
│       ↑                                   │            │
│       │         ┌──────────┐              │            │
│       └──────── │ 长期记忆  │ ←────────────┘            │
│                 │ 压缩存储  │                           │
│                 └──────────┘                            │
│                      ↑                                 │
│                 ┌──────────┐                           │
│                 │ 进度追踪  │                           │
│                 │ 可观测性  │                           │
│                 └──────────┘                            │
└───────────────────────────────────────────────────────┘

// 长时间运行 Agent 的异步架构
class LongRunningAgent {
  constructor(taskId, tools, checkpointStore, maxSteps = 20) {
    this.taskId = taskId;
    this.tools = tools;
    this.checkpoint = checkpointStore;
    this.maxSteps = maxSteps;
  }

  async execute(goal) {
    // 1. 检查是否有未完成的 checkpoint（断点续传）
    const lastCheckpoint = await this.checkpoint.load(this.taskId);
    if (lastCheckpoint) {
      return this.resume(lastCheckpoint, goal);
    }

    // 2. 异步启动任务
    const runId = generateRunId();
    await this.publishEvent("task.started", { taskId: this.taskId, runId });

    // 3. Agent 循环（每一步都保存 checkpoint）
    let state = { goal, messages: [], step: 0 };
    while (state.step < this.maxSteps) {
      try {
        state = await this.executeStep(state);

        // 保存 checkpoint（每个关键步骤后）
        await this.checkpoint.save(this.taskId, {
          step: state.step,
          messages: state.messages,
          intermediateResults: state.results,
          timestamp: Date.now(),
        });

        // 发布进度事件
        await this.publishEvent("task.progress", {
          taskId: this.taskId,
          step: state.step,
          progress: `${state.step}/${this.maxSteps}`,
        });

        // 检查是否完成
        if (state.completed) break;
      } catch (error) {
        // 错误恢复：从最近的 checkpoint 恢复
        await this.handleCheckpointRecovery(error, state);
      }
    }

    await this.publishEvent("task.completed", {
      taskId: this.taskId,
      result: state.results,
    });
    return state.results;
  }
}

// Checkpoint 存储结构
const checkpointSchema = {
  taskId: "string", // 任务 ID
  step: "number", // 当前步骤
  messages: "array", // LLM 对话历史
  intermediateResults: "object", // 中间结果
  toolState: "object", // 工具执行状态（已处理/未处理）
  memorySnapshot: "object", // 记忆快照
  timestamp: "number", // 快照时间
  tokenUsage: "number", // 已消耗 tokens
};

// 恢复策略
async function resumeFromCheckpoint(taskId) {
  const checkpoint = await checkpointStore.load(taskId);
  if (!checkpoint) throw new Error("无可用 checkpoint");

  // 恢复 Agent 状态
  const agent = new LongRunningAgent(taskId);
  agent.messages = checkpoint.messages;
  agent.step = checkpoint.step;
  agent.results = checkpoint.intermediateResults;

  // 从断点继续执行
  return agent.execute(checkpoint.goal);
}

// 记忆压缩策略
async function manageLongTermMemory(memory, maxTokens = 5000) {
  const currentTokens = countTokens(memory);

  if (currentTokens > maxTokens) {
    // 1. 压缩旧记忆：用小模型生成摘要
    const oldMemory = memory.slice(0, Math.floor(memory.length / 2));
    const summary = await smallLLM.invoke(
      `将以下对话历史压缩为关键要点：\n${JSON.stringify(oldMemory)}`,
    );

    // 2. 保留近期记忆 + 压缩摘要
    const recentMemory = memory.slice(Math.floor(memory.length / 2));
    return [
      { role: "system", content: `[历史摘要] ${summary}` },
      ...recentMemory,
    ];
  }

  return memory;
}

// 遗忘曲线：自动淘汰不常访问的记忆
function applyForgettingCurve(memories) {
  const now = Date.now();
  return memories
    .map((m) => ({
      ...m,
      // 记忆强度 = 访问次数 × recency 衰减
      strength:
        m.accessCount *
        Math.exp(-(now - m.lastAccess) / (7 * 24 * 3600 * 1000)),
    }))
    .filter((m) => m.strength > 0.1) // 淘汰强度过低的记忆
    .sort((a, b) => b.strength - a.strength);
}

// 进度追踪 + Human-in-the-Loop
const progressTracker = {
  // 进度事件发布
  events: {
    "task.started": (data) => notify(`任务开始: ${data.taskId}`),
    "task.progress": (data) => notify(`进度: ${data.progress}`),
    "task.blocked": (data) => notify(`阻塞: ${data.reason}，等待人工审批`),
    "task.error": (data) => notify(`错误: ${data.error}，正在重试`),
    "task.completed": (data) => notify(`完成: ${data.taskId}`),
  },

  // 人工干预点（Human-in-the-Loop）
  interventionPoints: [
    "before_high_risk_action", // 高风险操作前
    "on_error", // 遇到错误时
    "on_budget_threshold", // Token 预算达到阈值时
    "on_timeout", // 超时时
  ],
};

┌───────────────────────────────────────────────────────┐
│           Human-in-the-Loop 执行流程                    │
│                                                        │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐          │
│  │ Agent 执行│ → │ interrupt │ → │ 状态持久化│          │
│  │ 正常运行  │   │ 暂停等待  │   │ Checkpoint│          │
│  └──────────┘   └──────────┘   └──────────┘          │
│                      │                                 │
│                      ▼                                 │
│               ┌──────────┐                             │
│               │ 人类审批  │                             │
│               │ 批准/拒绝 │                             │
│               └──────────┘                             │
│                 │         │                             │
│            批准 ▼    拒绝 ▼                             │
│       ┌──────────┐ ┌──────────┐                        │
│       │ Command  │ │ 重新执行  │                        │
│       │ resume   │ │ 或终止    │                        │
│       └──────────┘ └──────────┘                        │
└───────────────────────────────────────────────────────┘

# Python 示例：LangGraph interrupt + Command + Checkpoint
from langgraph.graph import StateGraph, START, END
from langgraph.types import interrupt, Command
from langgraph.checkpoint.memory import MemorySaver

# 定义状态类型
class AgentState(TypedDict):
    messages: list
    risk_level: str
    approved: bool

# 普通执行节点：Agent 自主处理低风险操作
def agent_node(state: AgentState) -> AgentState:
    """Agent 分析任务并决定是否需要人工审批"""
    risk_level = classify_risk(state["messages"][-1])
    return {"risk_level": risk_level}

# 审批节点：暂停执行，等待人类审批
def human_approval_node(state: AgentState) -> AgentState:
    """暂停执行，向人类发送审批请求，等待输入"""
    # interrupt() 会暂停图的执行，把 value 发送给人类
    # 当图用 Command(resume=...) 恢复时，human_response 接收人类的输入
    human_response = interrupt({
        "action": "请审批以下操作",
        "risk_level": state["risk_level"],
        "details": state["messages"][-1],
    })

    # human_response 是 Command(resume=...) 中传入的值
    return {"approved": human_response == "approved"}

# 条件路由：根据审批结果决定下一步
def route_after_approval(state: AgentState) -> str:
    if state["approved"]:
        return "execute_action"
    return "reject_action"

# 执行节点
def execute_action(state: AgentState) -> AgentState:
    """审批通过，执行操作"""
    return {"messages": state["messages"] + [{"role": "system", "content": "操作已执行"}]}

def reject_action(state: AgentState) -> AgentState:
    """审批拒绝，通知用户"""
    return {"messages": state["messages"] + [{"role": "system", "content": "操作被拒绝"}]}

# 构建图
graph = StateGraph(AgentState)
graph.add_node("agent", agent_node)
graph.add_node("human_approval", human_approval_node)
graph.add_node("execute_action", execute_action)
graph.add_node("reject_action", reject_action)

graph.add_edge(START, "agent")
graph.add_edge("agent", "human_approval")
graph.add_conditional_edges("human_approval", route_after_approval)
graph.add_edge("execute_action", END)
graph.add_edge("reject_action", END)

# 编译图，配置 Checkpoint（interrupt 必须有 Checkpoint）
checkpointer = MemorySaver()
app = graph.compile(checkpointer=checkpointer)

# 第一次调用：Agent 执行到 interrupt 处暂停
config = {"configurable": {"thread_id": "user-123"}}
result = app.invoke({"messages": [{"role": "user", "content": "删除生产环境数据"}], "risk_level": "", "approved": False}, config)
# result 包含 interrupt 信息，图暂停执行

# 第二次调用：人类审批后，用 Command(resume=...) 恢复执行
result = app.invoke(Command(resume="approved"), config)
# 图从 interrupt 处恢复，human_response = "approved"

// JavaScript 示例：LangGraph interrupt + Command（LangGraph.js）
import { StateGraph, START, END } from "@langchain/langgraph";
import { MemorySaver } from "@langchain/langgraph-checkpoint";
import { interrupt, Command } from "@langchain/langgraph";

// 普通执行节点
async function agentNode(state) {
  const riskLevel = await classifyRisk(
    state.messages[state.messages.length - 1],
  );
  return { riskLevel };
}

// 审批节点：暂停执行，等待人类输入
async function humanApprovalNode(state) {
  // interrupt() 暂停图执行，把审批请求发送给人类
  const humanResponse = interrupt({
    action: "请审批以下操作",
    riskLevel: state.riskLevel,
    details: state.messages[state.messages.length - 1],
  });

  // humanResponse = Command({ resume: ... }) 中传入的值
  return { approved: humanResponse === "approved" };
}

// 条件路由
function routeAfterApproval(state) {
  if (state.approved) return "executeAction";
  return "rejectAction";
}

// 构建图
const graph = new StateGraph(AgentState)
  .addNode("agent", agentNode)
  .addNode("humanApproval", humanApprovalNode)
  .addNode("executeAction", executeAction)
  .addNode("rejectAction", rejectAction)
  .addEdge(START, "agent")
  .addEdge("agent", "humanApproval")
  .addConditionalEdges("humanApproval", routeAfterApproval)
  .addEdge("executeAction", END)
  .addEdge("rejectAction", END);

// 编译图，配置 Checkpoint
const checkpointer = new MemorySaver();
const app = graph.compile({ checkpointer });

// 第一次调用：执行到 interrupt 处暂停
const config = { configurable: { threadId: "user-123" } };
let result = await app.invoke(
  {
    messages: [{ role: "user", content: "删除生产环境数据" }],
    riskLevel: "",
    approved: false,
  },
  config,
);

// 第二次调用：用 Command 恢复执行
result = await app.invoke(new Command({ resume: "approved" }), config);

风险等级与审批策略：

┌──────────────┬──────────────┬──────────────────┐
│   风险等级    │   操作示例    │   审批策略        │
├──────────────┼──────────────┼──────────────────┤
│ 低风险       │ 查询数据      │ 自动执行，无需审批 │
│              │ 读取文档      │                   │
│              │ 搜索知识库    │                   │
├──────────────┼──────────────┼──────────────────┤
│ 中风险       │ 修改配置      │ 记录日志，异步通知 │
│              │ 发送邮件      │ 人类可事后审查     │
│              │ 创建工单      │                   │
├──────────────┼──────────────┼──────────────────┤
│ 高风险       │ 删除数据      │ interrupt 暂停    │
│              │ 支付操作      │ 等待人类审批      │
│              │ 部署生产环境  │ 审批后才能执行     │
├──────────────┼──────────────┼──────────────────┤
│ 禁止         │ 格式化磁盘    │ 硬编码拒绝        │
│              │ 删除用户账号  │ 永不执行           │
│              │ 泄露密钥      │                   │
└──────────────┴──────────────┴──────────────────┘

// 风险等级分类与审批策略
const riskPolicies = {
  // 低风险：自动执行
  low: {
    tools: ["searchKnowledge", "readFile", "queryDatabase"],
    action: "auto_execute",
    logging: "audit_log_only",
  },

  // 中风险：异步通知，可事后审查
  medium: {
    tools: ["sendEmail", "createTicket", "updateConfig"],
    action: "async_notify",
    logging: "full_log_with_notification",
  },

  // 高风险：暂停等待审批
  high: {
    tools: ["deleteData", "payment", "deployProduction"],
    action: "interrupt_and_wait",
    logging: "full_log_with_approval_chain",
  },

  // 禁止：硬编码拒绝
  forbidden: {
    tools: ["formatDisk", "deleteUser", "exposeSecrets"],
    action: "hard_reject",
    logging: "security_alert",
  },
};

// 风险分类函数
function classifyRisk(toolName, args) {
  // 禁止操作
  if (riskPolicies.forbidden.tools.includes(toolName)) {
    return "forbidden";
  }
  // 高风险操作
  if (riskPolicies.high.tools.includes(toolName)) {
    return "high";
  }
  // 中风险操作
  if (riskPolicies.medium.tools.includes(toolName)) {
    return "medium";
  }
  // 低风险操作
  return "low";
}

三件套的工作原理：

┌─────────────────────────────────────────────────────┐
│                    三件套协作                          │
│                                                      │
│  1. Checkpoint（状态持久化）                          │
│     每个节点执行后，状态自动保存到 Checkpoint          │
│     支持 MemorySaver（开发）、PostgresSaver（生产）   │
│                                                      │
│  2. interrupt()（暂停）                              │
│     在需要人类输入的节点调用 interrupt(value)          │
│     图的执行暂停，当前状态保存到 Checkpoint            │
│     value 被发送给调用方（前端/Slack/邮件）            │
│                                                      │
│  3. Command(resume=...)（恢复）                      │
│     人类输入后，用 Command(resume=response) 恢复      │
│     图从 Checkpoint 加载状态，从 interrupt 处继续     │
│     interrupt() 的返回值 = Command(resume=...) 的值  │
└─────────────────────────────────────────────────────┘

# Python：生产级 Human-in-the-Loop 完整实现
from langgraph.types import interrupt, Command
from langgraph.checkpoint.postgres import PostgresSaver

# 生产环境用 PostgresSaver（持久化，支持分布式）
checkpointer = PostgresSaver.from_conn_string(
    "postgresql://user:pass@localhost:5432/langgraph"
)

def tool_execution_node(state: AgentState) -> AgentState:
    """执行工具前检查风险等级"""
    tool_name = state["pending_tool"]
    risk = classify_risk(tool_name, state["pending_args"])

    if risk == "forbidden":
        # 禁止操作：硬编码拒绝
        return {"result": f"操作 {tool_name} 被安全策略禁止"}

    if risk == "high":
        # 高风险操作：暂停等待审批
        approval = interrupt({
            "type": "approval_request",
            "tool": tool_name,
            "args": state["pending_args"],
            "risk_level": risk,
            "message": f"Agent 请求执行高风险操作: {tool_name}",
        })

        if approval != "approved":
            return {"result": f"操作 {tool_name} 被人类拒绝"}

    # 低/中风险 或 高风险审批通过：执行工具
    result = execute_tool(tool_name, state["pending_args"])
    return {"result": result}

// JavaScript：生产级 Human-in-the-Loop 完整实现
import { interrupt, Command } from "@langchain/langgraph";
import { PostgresSaver } from "@langchain/langgraph-checkpoint-postgres";

// 生产环境用 PostgresSaver
const checkpointer = PostgresSaver.fromConnectionString(
  "postgresql://user:pass@localhost:5432/langgraph",
);

async function toolExecutionNode(state) {
  const toolName = state.pendingTool;
  const risk = classifyRisk(toolName, state.pendingArgs);

  if (risk === "forbidden") {
    return { result: `操作 ${toolName} 被安全策略禁止` };
  }

  if (risk === "high") {
    // 高风险：暂停等待审批
    const approval = interrupt({
      type: "approval_request",
      tool: toolName,
      args: state.pendingArgs,
      riskLevel: risk,
      message: `Agent 请求执行高风险操作: ${toolName}`,
    });

    if (approval !== "approved") {
      return { result: `操作 ${toolName} 被人类拒绝` };
    }
  }

  // 执行工具
  const result = await executeTool(toolName, state.pendingArgs);
  return { result };
}

// 多渠道审批通知
class ApprovalNotifier {
  constructor(app, config) {
    this.app = app;
    this.config = config;
  }

  // 处理 interrupt 事件，发送审批通知
  async handleInterrupt(interruptValue) {
    const approvalId = generateApprovalId();

    // 存储审批请求（关联 thread_id 和 approval_id）
    await this.storeApprovalRequest({
      id: approvalId,
      threadId: this.config.configurable.threadId,
      value: interruptValue,
      createdAt: Date.now(),
      status: "pending",
    });

    // 并行通知多个渠道
    await Promise.all([
      this.notifyFrontend(approvalId, interruptValue),
      this.notifySlack(approvalId, interruptValue),
      this.notifyEmail(approvalId, interruptValue),
    ]);

    return approvalId;
  }

  // 人类在任意渠道审批后，恢复执行
  async approve(approvalId, decision) {
    const request = await this.getApprovalRequest(approvalId);
    if (request.status !== "pending") {
      throw new Error("审批请求已处理");
    }

    // 用 Command(resume=...) 恢复图的执行
    const result = await this.app.invoke(new Command({ resume: decision }), {
      configurable: { threadId: request.threadId },
    });

    await this.updateApprovalRequest(approvalId, {
      status: decision === "approved" ? "approved" : "rejected",
      decidedAt: Date.now(),
    });

    return result;
  }
}

RAG 的数据流：
  用户："公司的年假政策是什么？"
  → 向量检索：从知识库中找到《员工手册》相关段落
  → 注入 Prompt：把检索到的段落作为上下文
  → LLM 生成："根据员工手册，入职满 1 年享有 10 天年假..."

Agent Skills 的数据流：
  用户："帮我申请 3 天年假"
  → LLM 决策：调用 applyLeaveTool({ type: "annual", days: 3 })
  → 工具执行：调用 HR 系统 API 创建请假申请
  → 返回结果："已为你提交 3 天年假申请，等待主管审批"

// RAG + Skills 协同示例
const agent = new Agent({
  // RAG：知识注入
  knowledgeBase: new VectorStore("company-docs"),
  retrievalConfig: {
    topK: 5, // 检索最相关的 5 个文档片段
    threshold: 0.7, // 相似度阈值
  },

  // Skills：工具调用
  tools: [
    searchCompanyPolicy, // 搜索公司政策（RAG）
    applyLeave, // 申请假期（Skills）
    checkLeaveBalance, // 查询假期余额（Skills）
  ],
});

// 用户："我想请年假，先看看政策再帮我申请"
// Agent 执行流程：
// 1. RAG：检索年假政策文档
// 2. Skills：查询当前假期余额
// 3. LLM：综合政策和余额，给出建议
// 4. Skills：提交假期申请

n8n 的 Agent 编排模式：

  ┌─────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
  │ Webhook │ → │ AI Agent │ → │  工具节点  │ → │  响应    │
  │ 触发器   │   │ LLM 节点 │   │ API/DB   │   │ 输出    │
  └─────────┘   └──────────┘   └──────────┘   └──────────┘
       ↑                              │
       │        ┌──────────┐          │
       └─────── │ 条件判断  │ ←────────┘
                │ IF/Switch │
                └──────────┘

// n8n 工作流的 JSON 定义（简化）
{
  "nodes": [
    {
      "type": "n8n-nodes-base.webhook",
      "name": "接收用户请求",
      "parameters": { "path": "/agent", "method": "POST" }
    },
    {
      "type": "@n8n/n8n-nodes-langchain.agent",
      "name": "AI Agent",
      "parameters": {
        "model": "gpt-4o",
        "systemMessage": "你是一个客服 Agent...",
        "tools": ["searchKnowledge", "createTicket", "sendEmail"]
      }
    },
    {
      "type": "n8n-nodes-base.if",
      "name": "需要人工介入？",
      "parameters": { "condition": "confidence < 0.8" }
    }
  ],
  "connections": {
    "接收用户请求": { "main": [["AI Agent"]] },
    "AI Agent": { "main": [["需要人工介入？"]] },
    "需要人工介入？": { "true": [["人工客服"]], "false": [["自动回复"]] }
  }
}

Dify 的 Agent 架构：

  ┌─────────────────────────────────────────┐
  │              Dify 平台                    │
  │                                           │
  │  ┌─────────┐  ┌──────────┐  ┌─────────┐ │
  │  │ Prompt   │  │  Tools   │  │ Memory  │ │
  │  │ 管理    │  │  工具库  │  │ 对话记忆 │ │
  │  └─────────┘  └──────────┘  └─────────┘ │
  │                                           │
  │  ┌─────────┐  ┌──────────┐  ┌─────────┐ │
  │  │  RAG    │  │  Agent   │  │  API    │ │
  │  │ 知识库  │  │  编排    │  │  发布   │ │
  │  └─────────┘  └──────────┘  └─────────┘ │
  └─────────────────────────────────────────┘

┌───────────────────────────────────────────────────────┐
│           Agent 稳定性保障体系                          │
│                                                        │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐         │
│  │ 重试策略   │ │ 降级策略   │ │ 死循环检测  │         │
│  │ 指数退避   │ │ Fallback   │ │ 最大轮次   │         │
│  └────────────┘ └────────────┘ └────────────┘         │
│  ┌────────────┐ ┌────────────┐                        │
│  │ 超时控制   │ │ Token 优化  │                        │
│  │ 全局 + 单步│ │ 模型分级   │                        │
│  └────────────┘ └────────────┘                        │
└───────────────────────────────────────────────────────┘

// 指数退避重试
async function retryWithExponentialBackoff(fn, options = {}) {
  const { maxRetries = 3, baseDelay = 1000, maxDelay = 30000 } = options;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      // 不可重试的错误直接抛出
      if (isNonRetryableError(error)) {
        throw error; // 如：参数错误、权限不足
      }

      if (attempt === maxRetries) {
        throw error; // 达到最大重试次数
      }

      // 指数退避：1s → 2s → 4s → 8s...
      const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
      // 加随机抖动防止惊群效应
      const jitter = delay * (0.5 + Math.random() * 0.5);
      await sleep(jitter);
    }
  }
}

// 使用示例
const result = await retryWithExponentialBackoff(() => llm.invoke(messages), {
  maxRetries: 3,
  baseDelay: 1000,
});

// 多层降级
const fallbackChain = [
  { model: "gpt-4o", tools: "full", label: "主模型" },
  { model: "gpt-4o-mini", tools: "basic", label: "备用模型" },
  { model: "rule-engine", tools: "none", label: "规则引擎" },
  { model: "human-escalation", tools: "none", label: "人工处理" },
];

async function executeWithFallbackChain(task) {
  for (const tier of fallbackChain) {
    try {
      return await executeWithTier(task, tier);
    } catch (error) {
      console.warn(`${tier.label} 失败，降级到下一层`);
      continue;
    }
  }
}

// 死循环检测：状态变化 + 最大轮次 + Token 预算
function detectInfiniteLoop(state, history) {
  // 1. 最大轮次限制
  if (state.step >= state.maxSteps) {
    return { detected: true, reason: "max_steps_exceeded" };
  }

  // 2. 状态变化检测：连续 N 步输出相同
  const recentOutputs = history.slice(-3).map((h) => h.output);
  if (
    recentOutputs.length >= 3 &&
    recentOutputs.every((o) => o === recentOutputs[0])
  ) {
    return { detected: true, reason: "no_progress" };
  }

  // 3. Token 预算检测
  if (state.totalTokens >= state.tokenBudget) {
    return { detected: true, reason: "token_budget_exceeded" };
  }

  // 4. 时间超时检测
  if (Date.now() - state.startTime > state.timeoutMs) {
    return { detected: true, reason: "timeout" };
  }

  return { detected: false };
}

// 分层超时控制
const timeoutConfig = {
  global: 30 * 60 * 1000, // 全局超时：30 分钟
  perStep: 60 * 1000, // 单步超时：60 秒
  llmCall: 30 * 1000, // LLM 调用超时：30 秒
  toolCall: 60 * 1000, // 工具调用超时：60 秒
};

async function executeWithTimeout(fn, timeoutMs, label) {
  return Promise.race([
    fn(),
    new Promise((_, reject) =>
      setTimeout(
        () => reject(new TimeoutError(`${label} 超时 (${timeoutMs}ms)`)),
        timeoutMs,
      ),
    ),
  ]);
}

// Token 消耗优化策略
const tokenOptimization = {
  // 1. 模型分级：简单任务用便宜模型
  selectModel(taskComplexity) {
    return taskComplexity === "simple" ? "gpt-4o-mini" : "gpt-4o";
  },

  // 2. Prompt 缓存：相同前缀复用 KV Cache
  async invokeWithCache(messages) {
    // Anthropic Prompt Cache：稳定的 System Prompt 放前面
    // 相同前缀的请求节省 90% 输入 token 费用
    return llm.invoke(messages, { cache: "auto" });
  },

  // 3. 输出限制：控制 LLM 输出长度
  invokeWithMaxTokens(messages, maxTokens = 1000) {
    return llm.invoke(messages, { maxTokens });
  },

  // 4. 上下文压缩：定期压缩历史对话
  compressContext(messages, maxTokens = 4000) {
    if (countTokens(messages) > maxTokens) {
      const summary = summarize(messages.slice(0, -5));
      return [{ role: "system", content: summary }, ...messages.slice(-5)];
    }
    return messages;
  },
};

Prompt Engineering       → 一次调用里说什么
Context Engineering      → 每次调用让模型看到什么
Harness Engineering      → 模型之外的整个世界：工具、约束、反馈回路、环境
Agents API / Codex CLI   → 这套方法论的一个具体实现载体

┌──────────────────────────────────────────────────────────────┐
│              AI 编码工具的演进路径                              │
│                                                               │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐ │
│  │ 2021     │ → │ 2022     │ → │ 2024     │ → │ 2025     │ │
│  │ Codex    │ → │ Copilot  │ → │ Cursor   │ → │ Claude   │ │
│  │ 代码底座  │ → │ IDE 插件  │ → │ AI Editor│ → │ Code     │ │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘ │
│                                                               │
│  单次补全       → 上下文感知    → 多文件编辑    → 自主 Agent   │
└──────────────────────────────────────────────────────────────┘

Codex 的技术栈：

  用户在 IDE 中输入代码
       ↓
  IDE 插件提取上下文（当前文件、光标位置、导入语句）
       ↓
  Codex 模型推理（基于 GPT-3 微调的 12B 参数模型）
       ↓
  返回代码补全建议（单行 / 多行 / 整个函数）

Claude Code 的架构：

  用户在终端输入自然语言指令
       ↓
  Claude Code Agent Loop（ReAct 模式）
       ↓
  ┌──────────────────────────────────────────┐
  │  工具调用层                                │
  │  ┌────────┐ ┌────────┐ ┌────────┐       │
  │  │ 读写文件│ │ 执行命令│ │ 搜索代码│       │
  │  └────────┘ └────────┘ └────────┘       │
  │  ┌────────┐ ┌────────┐ ┌────────┐       │
  │  │ Git 操作│ │ MCP 协议│ │ Hooks  │       │
  │  └────────┘ └────────┘ └────────┘       │
  └──────────────────────────────────────────┘
       ↓
  自主完成任务（重构、修 bug、写测试、提交代码）

Andrew Ng 的多 Agent 角色分工模型：

  ┌──────────────────────────────────────────────────────┐
  │                   Orchestrator                        │
  │              （任务拆分 + 结果汇总）                    │
  │                                                       │
  │  ┌──────────┐  ┌──────────┐  ┌──────────┐           │
  │  │ Code     │  │ Test     │  │ Review   │           │
  │  │ Agent    │  │ Agent    │  │ Agent    │           │
  │  │ 代码生成  │  │ 测试编写  │  │ 代码审查  │           │
  │  └────┬─────┘  └────┬─────┘  └────┬─────┘           │
  │       │              │              │                 │
  │       └──────────────┼──────────────┘                 │
  │                      ▼                                │
  │              ┌──────────────┐                         │
  │              │ Deploy Agent │                         │
  │              │ 部署发布      │                         │
  │              └──────────────┘                         │
  └──────────────────────────────────────────────────────┘

// 1. 串行协作（Sequential）：严格按顺序执行
const sequentialFlow = "Code → Test → Review → Deploy";
// 适用场景：每个步骤依赖上一步的输出

// 2. 并行协作（Parallel）：独立任务同时执行
const parallelFlow = ["Code(模块A)", "Code(模块B)", "Code(模块C)"];
// 适用场景：多个独立模块可以同时开发

// 3. 反馈循环（Feedback Loop）：审查不通过则回到 Code Agent 修改
const feedbackFlow = "Code → Review → [通过] → Deploy / [不通过] → Code";
// 适用场景：需要迭代优化的质量敏感场景

// 企业级多 Agent 的权限矩阵
const agentPermissions = {
  codeAgent: {
    tools: ["readFile", "writeFile", "searchCode", "terminal"],
    scope: { repositories: ["frontend/*"], branches: ["feature/*"] },
    restrictions: ["cannot deploy", "cannot delete"],
  },
  testAgent: {
    tools: ["readFile", "runTest", "coverage"],
    scope: { environments: ["local", "ci"] },
    restrictions: ["cannot modify production data"],
  },
  reviewAgent: {
    tools: ["readFile", "searchCode", "lint"],
    scope: { repositories: ["*"], branches: ["*"] },
    restrictions: ["read-only", "cannot execute commands"],
  },
  deployAgent: {
    tools: ["build", "deploy", "checkHealth", "rollback"],
    scope: { environments: ["staging"], exclude: ["production"] },
    restrictions: ["production requires human approval"],
  },
};

---
name: code-pipeline
description: 自动化代码重构 → 测试 → 审查流水线
---

# Code Pipeline

按下面的顺序依次调用子 Agent，任一步失败则回到上一步。

## 1. refactor-agent

可用工具：Read、Write、Edit、Bash。

1. 读取目标文件，分析代码结构
2. 识别可优化的模式（重复代码、过长函数、复杂条件）
3. 执行重构，保持功能不变
4. 运行现有测试确认没有破坏

## 2. test-agent

可用工具：Read、Write、Bash。

1. 读取重构后的代码
2. 分析已有的测试覆盖率
3. 为新增/修改的逻辑补充测试用例
4. 运行全部测试，确保通过

## 3. review-agent

可用工具：Read、Bash。

1. 代码质量：命名规范、函数长度、圈复杂度
2. 安全性：SQL 注入、XSS、敏感信息泄露
3. 性能：N+1 查询、不必要的重渲染、内存泄漏风险
4. 输出审查报告，标记问题等级（Error / Warning / Info）

## 协作流程

- 输入重构目标 → refactor-agent
- 重构完成 → test-agent
- 测试通过 → review-agent
- review-agent 发现 Error → 回到 refactor-agent，修改后重走流水线
- 审查通过 → 输出最终报告

# 在终端中使用 Claude Code 执行多 Agent 流水线
$ claude "使用 code-pipeline skill，重构 src/utils/validation.ts"

# Claude Code 会自主执行：
# 1. refactor-agent：读取代码 → 识别优化点 → 执行重构 → 运行测试
# 2. test-agent：分析覆盖率 → 补充测试 → 运行全部测试
# 3. review-agent：审查代码质量 → 输出报告
# 如果审查发现 Error，自动回到 refactor-agent 修改后重新走流水线

run/started
   │
   ├── turn/started
   │      ├── step/started ── model/requested ── model/delta* ── model/completed
   │      │        ├── tool/requested ── tool/started ── tool/completed | tool/failed
   │      │        └── step/completed
   │      ├── turn/interrupted ──（人工审批 / 用户中断 / 预算耗尽）
   │      └── turn/completed
   ├── run/resumed（从 last_event_id 继续）
   └── run/completed | run/failed | run/cancelled

// 事件是最小事实，状态是可重建的投影
type RunEvent =
  | {
      type: "run/started";
      runId: string;
      tenantId: string;
      at: number;
      input: string;
    }
  | { type: "turn/started"; runId: string; turnId: string; at: number }
  | { type: "step/started"; runId: string; stepId: string; at: number }
  | {
      type: "model/completed";
      runId: string;
      stepId: string;
      message: Message;
      usage: Usage;
    }
  | { type: "tool/requested"; runId: string; stepId: string; call: ToolCall }
  | {
      type: "tool/completed";
      runId: string;
      stepId: string;
      callId: string;
      result: ToolResult;
    }
  | {
      type: "tool/failed";
      runId: string;
      stepId: string;
      callId: string;
      error: ToolError;
    }
  | {
      type: "artifact/created";
      runId: string;
      artifactId: string;
      manifest: ArtifactManifest;
    }
  | {
      type: "run/interrupted";
      runId: string;
      reason: "approval" | "user" | "budget";
    }
  | { type: "run/resumed"; runId: string; fromEventId: string }
  | {
      type: "run/completed";
      runId: string;
      status: "ok" | "failed" | "cancelled";
    };

type RunState = {
  status: "running" | "waiting_approval" | "completed" | "failed";
  step: number;
  pendingCalls: Map<string, ToolCall>; // 已请求未落结果的调用
  messages: Message[];
  artifacts: string[];
};

function fold(events: RunEvent[]): RunState {
  return events.reduce(apply, initialState);
}

function apply(state: RunState, e: RunEvent): RunState {
  switch (e.type) {
    case "model/completed":
      return { ...state, messages: [...state.messages, e.message] };
    case "tool/requested":
      return {
        ...state,
        pendingCalls: new Map(state.pendingCalls).set(e.call.id, e.call),
      };
    case "tool/completed":
    case "tool/failed": {
      const pending = new Map(state.pendingCalls);
      pending.delete(e.callId);
      return { ...state, pendingCalls: pending, step: state.step + 1 };
    }
    case "run/interrupted":
      return { ...state, status: "waiting_approval" };
    default:
      return state;
  }
}