1
pi/
2
├── packages/
3
│   ├── ai/            # LLM API 抽象层
4
│   ├── agent/         # Agent 运行时（核心）
5
│   ├── coding-agent/  # 完整的 CLI 应用（上层）
6
│   └── tui/           # 终端 UI 库
7
├── package.json
8
└── tsconfig.json

1
用户输入 "帮我写个web服务器"
2
  │
3
  ▼
4
coding-agent/main.ts
5
  │  解析输入、处理 slash 命令
6
  ▼
7
Agent.prompt("帮我写个web服务器")
8
  │  包装成 AgentMessage，转发到 loop
9
  ▼
10
agent-loop.ts (runLoop)
11
  │  调用 LLM → 拿到 AssistantMessage
12
  ▼
13
  ┌─── 有 toolCall？───→ 执行工具 → 结果塞回 context → 再调 LLM
14
  │                       （可能循环多次）
15
  └─── 没 toolCall？───→ 返回最终消息
16
  │
17
  ▼
18
ai/stream.ts (streamSimple)
19
  │  统一流式接口，调用具体 provider
20
  ▼
21
ai/providers/...
22
  │  发 HTTP 请求到 LLM
23
  ▼
24
LLM → 返回事件流 → 逐帧往上冒泡 → UI 更新

1
type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];

1
interface CustomAgentMessages {
2
  // 默认空，应用通过 declaration merging 扩展
3
}
4

5
// 使用方可以这样扩展：
6
declare module "@earendil-works/pi-agent" {
7
  interface CustomAgentMessages {
8
    artifact: ArtifactMessage;
9
    notification: NotificationMessage;
10
  }
11
}

1
interface AgentLoopConfig extends SimpleStreamOptions {
2
  model: Model<any>;                    // 用什么模型
3

4
  convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
5
  // 把 Agent 层的消息转成 LLM 能理解的消息格式
6

7
  transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
8
  // 在 convertToLlm 之前对消息做预处理——上下文窗口管理
9

10
  getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
11
  // 动态获取 API key（对 OAuth token 很重要）
12

13
  shouldStopAfterTurn?: (context: ShouldStopAfterTurnContext) => boolean | Promise<boolean>;
14
  // 每一轮完成后，检查是否应该停下
15

16
  prepareNextTurn?: (context: PrepareNextTurnContext) => AgentLoopTurnUpdate | undefined | Promise<...>;
17
  // 在下一轮开始前，可以替换 context / model / thinking level
18

19
  beforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
20
  afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
21

22
  getSteeringMessages?: () => Promise<AgentMessage[]>;
23
  // 运行时干预
24

25
  getFollowUpMessages?: () => Promise<AgentMessage[]>;
26
  // 后续任务
27

28
  toolExecution?: ToolExecutionMode;
29
}

1
type AgentEvent =
2
  | { type: "agent_start" }
3
  | { type: "agent_end"; messages: AgentMessage[] }
4
  | { type: "turn_start" }
5
  | { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
6
  | { type: "message_start"; message: AgentMessage }
7
  | { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
8
  | { type: "message_end"; message: AgentMessage }
9
  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
10
  | { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
11
  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean };

1
agent_start
2
  └── turn_start
3
       ├── message_start      （assistant 回复开始）
4
       │    └── message_update （流式更新，可能多次）
5
       ├── message_end        （assistant 回复结束）
6
       ├── tool_execution_start （工具开始执行）
7
       │    └── tool_execution_update （工具进度更新，可选）
8
       └── tool_execution_end （工具执行结束）
9
       └── （可能还有更多工具调用）
10
  └── turn_end
11
  └── （可能还有更多 turn）
12
agent_end

1
Agent 实例的整个生命周期
2
├── prompt("写个服务器")        ← Run 1
3
│   ├── agent_start
4
│   │   ├── turn_start          ← Turn 1（LLM 请求）
5
│   │   │   └── tool call (读文件)
6
│   │   ├── turn_end
7
│   │   ├── turn_start          ← Turn 2（再次调 LLM，带上读文件结果）
8
│   │   │   └── tool call (写文件)
9
│   │   ├── turn_end
10
│   │   ├── turn_start          ← Turn 3（写完了，输出结果）
11
│   │   │   └── 纯文字回复
12
│   │   └── turn_end
13
│   └── agent_end               ← Run 1 结束
14
│
15
├── prompt("再加个路由")        ← Run 2
16
│   └── ...
17
└── prompt("看看数据库")        ← Run 3

1
function agentLoop(
2
  prompts: AgentMessage[],     // 用户输入
3
  context: AgentContext,       // 当前上下文
4
  config: AgentLoopConfig,     // 循环配置
5
  signal?: AbortSignal,        // 中断信号
6
  streamFn?: StreamFn,         // LLM 调用函数
7
): EventStream<AgentEvent, AgentMessage[]>

1
async function streamAssistantResponse(
2
  context: AgentContext,
3
  config: AgentLoopConfig,
4
  signal: AbortSignal | undefined,
5
  emit: AgentEventSink,
6
  streamFn?: StreamFn,
7
): Promise<AssistantMessage>

1
context.messages
2
  │
3
  ▼
4
config.transformContext(messages)  预处理（可选，AgentMessage[] → AgentMessage[]）
5
  │
6
  ▼
7
config.convertToLlm(messages)      格式转换（AgentMessage[] → Message[]）
8
  │
9
  ▼
10
streamFn(model, llmContext, options)  调 LLM
11
  │
12
  ▼
13
逐帧处理事件流：
14
  start         → 初始化 partialMessage，push 到 context，emit message_start
15
  text_delta    → 更新 partialMessage，emit message_update
16
  toolcall_delta  → 更新 partialMessage，emit message_update
17
  thinking_delta  → 同上
18
  done/error    → 拿到 finalMessage，更新 context，emit message_end

1
async function executeToolCalls(
2
  currentContext: AgentContext,
3
  assistantMessage: AssistantMessage,
4
  config: AgentLoopConfig,
5
  signal: AbortSignal | undefined,
6
  emit: AgentEventSink,
7
): Promise<ExecutedToolCallBatch>

1
class Agent {
2
  constructor(options: AgentOptions) {
3
    this._state = createMutableAgentState(options.initialState);
4
    this.convertToLlm = options.convertToLlm ?? defaultConvertToLlm;
5
    this.streamFn = options.streamFn ?? streamSimple;
6
    this.steeringQueue = new PendingMessageQueue(options.steeringMode ?? "one-at-a-time");
7
    this.followUpQueue = new PendingMessageQueue(options.followUpMode ?? "one-at-a-time");
8
    // ...
9
  }
10
}

1
private createLoopConfig(options): AgentLoopConfig {
2
  return {
3
    model: this._state.model,
4
    reasoning: ...,
5
    convertToLlm: this.convertToLlm,
6
    transformContext: this.transformContext,
7
    getApiKey: this.getApiKey,
8
    getSteeringMessages: async () => {
9
      if (skipInitialSteeringPoll) { ... }
10
      return this.steeringQueue.drain();
11
    },
12
    getFollowUpMessages: async () => this.followUpQueue.drain(),
13
  };
14
}

1
agent.prompt("写个服务器")
2
  │
3
  ├── 检查 activeRun → 有？报错
4
  ├── normalizePromptInput → 包装成 AgentMessage[]
5
  ├── runPromptMessages(messages)
6
  │   ├── runWithLifecycle(executor)
7
  │   │   ├── AbortController 创建 → activeRun 赋值
8
  │   │   ├── this._state.isStreaming = true
9
  │   │   └── executor(signal)
10
  │   │       └── runAgentLoop(messages, context, loopConfig, processEvents, signal, streamFn)
11
  │   │           └── runLoop()  ← 进入 agent-loop.ts
12
  │   │               ├── 事件 → processEvents → 更新 state + 广播
13
  │   │               └── loop 结束后返回
14
  │   └── runWithLifecycle finally 块
15
  │       ├── finishRun() → isStreaming = false, activeRun = undefined
16
  │       └── activeRun.resolve() → waitForIdle 解除阻塞

1
private async handleAgentEvent(event: AgentEvent): Promise<void> {
2
  if (event.type === "message_end") {
3
    await this.session.appendMessage(event.message);  // 写入 Session
4
    await this.emitAny(event);                        // 广播给订阅者
5
  }
6
  if (event.type === "turn_end") {
7
    await this.emitAny(event);
8
    await this.flushPendingSessionWrites();           // 批量写入
9
    await this.emitOwn({ type: "save_point", hadPendingMutations });
10
  }
11
}

1
压缩前：
2
 [消息 1]  用户：帮我写个服务器
3
 [消息 2]  Assistant：看看目录
4
 [消息 3]  ToolResult：（2000 字目录内容）
5
 …（100 条消息，190k tokens）
6

7
压缩后：
8
 [摘要]   用户开发 Express 服务器。已完成项目初始化、
9
          路由定义和数据库连接。关键文件：app.ts, routes/users.ts
10
 [消息 98] 最近的操作
11
 [消息 99] 最近的工具结果
12
 …（20 条消息，35k tokens——关键信息全在）

1
function shouldCompact(contextTokens, contextWindow, settings): boolean {
2
  if (!settings.enabled) return false;
3
  return contextTokens > contextWindow - settings.reserveTokens;
4
}

1
## Goal
2
[用户想做什么？]
3

4
## Constraints & Preferences
5
[约束和偏好]
6

7
## Progress
8
### Done
9
- [x] [已完成的任务]
10
### In Progress
11
- [ ] [正在进行的工作]
12

13
## Key Decisions
14
- **[决策]**：[理由]
15

16
## Next Steps
17
1. [下一步做什么]
18

19
## Critical Context
20
[继续工作所需要的关键信息]

1
用户输入 "帮我写个 RPC 服务"
2
  │
3
  ▼
4
interactive-mode.ts（onSubmit）
5
  │  检查 isStreaming？空闲 → session.prompt()
6
  ▼
7
agent-session.ts（prompt）
8
  │  检查 isStreaming？空闲 → agent.prompt()
9
  ▼
10
agent.ts（Agent.prompt）
11
  │  包装成 AgentMessage，调用 runAgentLoop
12
  ▼
13
agent-loop.ts（runLoop）
14
  │  进入 ReAct 循环
15
  │
16
  ├──── Turn 1
17
  │     streamAssistantResponse() → 调 LLM
18
  │       System Prompt 包含：工具定义、操作指南
19
  │     LLM 返回：read_file("package.json")
20
  │     executeToolCalls → 读文件
21
  │
22
  ├──── Turn 2
23
  │     streamAssistantResponse()
24
  │     LLM 返回：write_file("rpc-server.ts", ...)
25
  │     executeToolCalls → 写文件
26
  │
27
  └──── Turn 3
28
        streamAssistantResponse()
29
        LLM 纯文字回复："已创建 rpc-server.ts"
30
  │
31
  ▼
32
事件 → interactive-mode（UI 渲染）