输入 -> 模型 -> 输出

输入 -> 上下文构建 -> 模型 -> 工具调用 -> 权限 -> 工具结果 -> 模型 -> 输出 -> 记录

agent-cli/
├── src/
│   ├── main.ts                 # 程序入口：判断 REPL / --print
│   ├── repl.ts                 # 交互式输入循环
│   ├── commands.ts             # slash commands
│   ├── queryEngine.ts          # Agent 主循环
│   ├── stateMachine.ts         # turn 状态机
│   ├── model/
│   │   ├── adapter.ts          # ModelAdapter 接口
│   │   ├── anthropic.ts        # 某供应商适配
│   │   ├── openaiCompatible.ts # OpenAI-compatible 适配
│   │   └── mock.ts             # 测试模型
│   ├── context/
│   │   ├── buildContext.ts     # 上下文构建
│   │   ├── budget.ts           # token 预算
│   │   ├── memory.ts           # 长期记忆
│   │   └── compaction.ts       # 压缩
│   ├── tools/
│   │   ├── registry.ts         # 工具注册表
│   │   ├── executor.ts         # 工具执行器
│   │   ├── permissions.ts      # 权限门禁
│   │   ├── readFile.ts
│   │   ├── editFile.ts
│   │   ├── grep.ts
│   │   └── bash.ts
│   ├── mcp/
│   │   ├── client.ts
│   │   ├── transport.ts
│   │   └── wrapTool.ts
│   ├── trace.ts
│   ├── transcript.ts
│   ├── cost.ts
│   ├── renderer.ts
│   └── types.ts

// Message = 模型能看到的上下文。
// Agent 的所有记忆、工具结果、用户输入最终都要变成 Message。
export type Message =
  | {
      // system/user/assistant 是普通文本消息。
      role: "system" | "user" | "assistant";
      // 消息正文。
      content: string;
    }
  | {
      // tool 消息是工具执行后的观察结果。
      role: "tool";
      // 对应哪次工具调用。
      toolCallId: string;
      // 工具返回内容，例如文件片段、grep 结果、测试输出。
      content: string;
    };

// ToolCall = 模型提出的动作请求。
// 它还没有被程序批准和执行。
export type ToolCall = {
  id: string;        // 调用 ID，用来和工具结果匹配。
  name: string;      // 工具名，例如 grep、read_file。
  input: unknown;    // 工具参数，必须做 schema 校验。
  sessionId: string; // 当前会话 ID，用于 trace/audit。
};

// ToolResult = 程序执行工具后的结果。
export type ToolResult = {
  summary: string;                    // 一句话摘要。
  content: string;                    // 详细输出，会回填给模型。
  metadata?: Record<string, unknown>; // 行号、数量、hash、是否截断等结构化信息。
};

// AgentEvent = Agent 对 UI/终端/测试输出的事件。
// 事件化后，同一个 QueryEngine 可以接 CLI、Web、JSONL。
export type AgentEvent =
  | { type: "text_delta"; text: string } // 模型文本增量。
  | { type: "tool_start"; call: ToolCall } // 工具开始。
  | { type: "tool_result"; call: ToolCall; result: ToolResult } // 工具完成。
  | { type: "state"; name: string } // 状态机状态变化。
  | { type: "error"; error: AgentErrorShape } // 结构化错误。
  | { type: "turn_end"; reason: StopReason }; // 本轮结束。

> 帮我看看为什么测试失败

// REPL 输入分流。
// slash command 是确定性程序命令；普通文本才进入 Agent 主循环。
if (input.startsWith("/")) {
  // 例如 /help、/cost、/mcp list。
  await runCommand(input);
} else {
  // query 返回事件流，renderEvent 决定如何展示。
  for await (const event of query(input)) {
    renderEvent(event);
  }
}

// buildContext = 构建模型上下文。
// 它把用户输入、项目规则、记忆、历史和检索结果整理成 messages。
const messages = await buildContext({
  userInput, // 当前用户任务。
  cwd,       // 工作区路径，用于读取项目规则。
  sessionId, // 当前会话，用于读取 transcript/memory。
  model      // 模型名，用于选择 token budget。
});

// callModel = 调模型的统一入口。
// messages 是上下文，tools 是工具 schema。
const response = await model.complete({
  messages,
  tools: getToolSchemas()
});

// 模型直接返回文本：本轮可以结束。
{ type: "text", text: "测试失败原因是..." }

{
  // 模型请求调用工具。
  type: "tool_call",
  id: "call_1", // 工具调用 ID。
  name: "grep", // 工具名。
  input: { pattern: "Error:", include: "src/**/*.ts" } // 工具参数。
}

// executeToolCall = 工具执行统一入口。
// 内部负责参数校验、权限、超时、截断和审计。
const result = await executeToolCall(call);

// 工具结果必须回填给模型。
// 否则模型下一轮不知道 grep/read_file/shell 看到了什么。
messages.push({
  role: "tool",
  toolCallId: call.id,
  content: result.content
});

// query 输出 AgentEvent 流。
// 终端、Web、测试都可以用同一组事件驱动。
for await (const event of query(input)) {
  renderEvent(event);
}

state: build_context
state: call_model
tool_start: grep
tool_result: 发现 12 个匹配
text_delta: 我找到了失败原因...
turn_end: final_answer