L1ngg's Home

1
messages = [user("帮我修一下登录页的 bug")]
2
while True:
3
    reply = llm(messages, tools)             # 1. 把对话历史发给模型
4
    messages.append(reply)
5
    if not reply.tool_calls:                 # 2. 模型没要工具 = 它认为干完了
6
        break
7
    for call in reply.tool_calls:            # 3. 模型要求调工具
8
        result = run_tool(call)              #    真的去执行
9
        messages.append(tool_result(result)) # 4. 结果写回历史，下轮模型能看到

1
pi-ai          模型层：40 家厂商统一成一个 streamFn
2
pi-agent-core  循环层：Agent 类 + agentLoop，本文标本
3
  ├─ agent-loop.ts   循环本体（796 行）
4
  ├─ agent.ts        有状态封装（592 行）
5
  ├─ types.ts        全部契约（443 行）
6
  └─ harness/        再往上：session、压缩、skills（本文不展开）
7
pi-coding-agent 产品层：终端 UI、工具实现、extension

1
// demo.mjs（Node 24 实测可跑）
2
import { Agent } from '@earendil-works/pi-agent-core';
3
import {
4
  createModels, fauxProvider,
5
  fauxAssistantMessage, fauxToolCall, fauxText,
6
} from '@earendil-works/pi-ai';
7
import { Type } from 'typebox';
8

9
// 假模型的剧本：第一轮要求调 add 工具，第二轮给出总结
10
const faux = fauxProvider();
11
const models = createModels();
12
models.setProvider(faux.provider);
13
faux.setResponses([
14
  fauxAssistantMessage([fauxToolCall('add', { a: 17, b: 25 })], { stopReason: 'toolUse' }),
15
  fauxAssistantMessage([fauxText('17 + 25 = 42。')]),
16
]);
17

18
// 一个真工具：参数用 TypeBox 描述，execute 里是真逻辑
19
const addTool = {
20
  name: 'add',
21
  label: 'Add',
22
  description: 'Add two numbers',
23
  parameters: Type.Object({ a: Type.Number(), b: Type.Number() }),
24
  execute: async (toolCallId, params) => ({
25
    content: [{ type: 'text', text: String(params.a + params.b) }],
26
    details: {},
27
  }),
28
};
29

30
const agent = new Agent({
31
  initialState: { systemPrompt: 'You are helpful.', model: faux.getModel(), tools: [addTool] },
32
  streamFn: models.streamSimple.bind(models),
33
});
34

35
agent.subscribe((event) => {
36
  if (event.type === 'message_update') return; // 流式增量太多，略过
37
  if (event.type === 'tool_execution_end') {
38
    console.log(`[${event.type}] add ->`, event.result.content[0].text);
39
    return;
40
  }
41
  console.log(`[${event.type}]`, event.message?.role ?? '');
42
});
43

44
await agent.prompt('17 加 25 等于几？');
45
console.log('对话记录:', agent.state.messages.map((m) => m.role).join(' -> '));

1
[agent_start]
2
[turn_start]
3
[message_start]  user
4
[message_end]    user
5
[message_start]  assistant
6
[message_end]    assistant
7
[tool_execution_start]
8
[tool_execution_end] add -> 42
9
[message_start]  toolResult
10
[message_end]    toolResult
11
[turn_end]       assistant
12
[turn_start]
13
[message_start]  assistant
14
[message_end]    assistant
15
[turn_end]       assistant
16
[agent_end]
17
对话记录: user -> assistant -> toolResult -> assistant

1
// packages/agent/src/agent-loop.ts（删减版，保留控制流）
2
async function runLoop(initialContext, newMessages, config, signal, emit, streamFn) {
3
  let currentContext = initialContext;
4
  // 循环开始前就查一次：用户可能在等待时已经输入了下一句
5
  let pendingMessages = (await config.getSteeringMessages?.()) || [];
6

7
  while (true) {                       // 外层：只管 follow-up
8
    let hasMoreToolCalls = true;
9

10
    while (hasMoreToolCalls || pendingMessages.length > 0) {  // 内层：转 turn
11
      // 1. 先把排队消息注入上下文
12
      if (pendingMessages.length > 0) {
13
        for (const message of pendingMessages) {
14
          currentContext.messages.push(message);
15
          newMessages.push(message);
16
        }
17
        pendingMessages = [];
18
      }
19

20
      // 2. 问模型，流式收一条 assistant 消息
21
      const message = await streamAssistantResponse(currentContext, config, signal, emit, streamFn);
22

23
      // 3. 模型出错或被中断：收尾，整个循环结束
24
      if (message.stopReason === "error" || message.stopReason === "aborted") { /* emit turn_end + agent_end */ return; }
25

26
      // 4. 模型要调工具就执行，结果写回上下文
27
      const toolCalls = message.content.filter((c) => c.type === "toolCall");
28
      hasMoreToolCalls = false;
29
      if (toolCalls.length > 0) {
30
        const batch = /* 执行整批工具 */;
31
        for (const result of batch.messages) {
32
          currentContext.messages.push(result);  // toolResult 回到上下文
33
        }
34
        hasMoreToolCalls = !batch.terminate;
35
      }
36

37
      // 5. turn 结束，给用户纠偏的机会
38
      pendingMessages = (await config.getSteeringMessages?.()) || [];
39
    }
40

41
    // 内层停了 = 模型不要工具了。看看有没有 follow-up 要接着干
42
    const followUpMessages = (await config.getFollowUpMessages?.()) || [];
43
    if (followUpMessages.length > 0) {
44
      pendingMessages = followUpMessages;
45
      continue;   // 回内层再转
46
    }
47
    break;        // 真没事了，退出
48
  }
49
  // emit agent_end
50
}

1
case "text_delta": // thinking_delta、toolcall_delta 等同理
2
  if (partialMessage) {
3
    partialMessage = event.partial;
4
    context.messages[context.messages.length - 1] = partialMessage;  // 原位替换
5
    await emit({ type: "message_update", assistantMessageEvent: event, message: { ...partialMessage } });
6
  }
7
  break;

1
// packages/agent/src/agent.ts → processEvents()（删减）
2
private async processEvents(event: AgentEvent): Promise<void> {
3
  switch (event.type) {
4
    case "message_start":
5
    case "message_update":
6
      this._state.streamingMessage = event.message;      // 正在流式输出的那条
7
      break;
8
    case "message_end":
9
      this._state.streamingMessage = undefined;
10
      this._state.messages.push(event.message);          // 完成的消息落进 transcript
11
      break;
12
    case "tool_execution_start": {
13
      const pending = new Set(this._state.pendingToolCalls);
14
      pending.add(event.toolCallId);
15
      this._state.pendingToolCalls = pending;            // 正在执行的工具集合
16
      break;
17
    }
18
    // ...
19
  }
20
  // 先更新完内部状态，再按注册顺序逐个 await 订阅者
21
  for (const listener of this.listeners) {
22
    await listener(event, signal);
23
  }
24
}