附录

A. 核心类型速查表

pi-ai 层

pi-agent-core 层

pi-coding-agent 层

B. 设计模式索引

C. 一次完整请求的时序图

sequenceDiagram
    participant User
    participant Editor as Editor - TUI
    participant Agent as Agent
    participant Loop as agentLoop
    participant Transform as transformContext
    participant Convert as convertToLlm
    participant Provider as LLM Provider
    participant Tool as Tool Execute
    participant Session as SessionManager

    User->>Editor: 输入消息 + Enter
    Editor->>Agent: agent.prompt(msg)
    Note over Agent: 添加用户消息到 state.messages
    Agent->>Loop: runAgentLoop(prompts, context, config)
    
    rect rgb(230, 245, 255)
        Note over Loop,Convert: 上下文准备阶段
        Loop->>Transform: transformContext(messages)
        Note over Transform: 可注入 plan 指令、截断历史、<br/>过滤敏感信息
        Transform-->>Loop: pruned messages
        Loop->>Convert: convertToLlm(messages)
        Note over Convert: AgentMessage → ai 层 Message<br/>过滤/转换应用层消息
        Convert-->>Loop: LLM-compatible messages
    end
    
    rect rgb(255, 245, 230)
        Note over Loop,Provider: 模型调用阶段
        Loop->>Provider: streamSimple(model, context)
        Note over Provider: HTTP SSE 流式调用
        Provider-->>Loop: events (text_delta, toolcall_end, done)
        Loop->>Agent: emit(message_end)
        Agent->>Session: persist entry
    end
    
    alt has tool calls
        rect rgb(230, 255, 230)
            Note over Loop,Tool: 三阶段工具执行
            Loop->>Tool: prepareToolCall()
            Note over Tool: 获取资源、权限检查<br/>beforeToolCall 钩子在此触发
            Tool-->>Loop: prepared (or denied)
            Loop->>Tool: executePreparedToolCall()
            Note over Tool: 实际执行操作<br/>（bash 命令、文件读写等）
            Tool-->>Loop: result
            Loop->>Tool: finalizeExecutedToolCall()
            Note over Tool: 格式化结果、截断过长输出
            Tool-->>Loop: final result
        end
        Loop->>Agent: emit(tool_execution_end)
        Note over Agent: UI / extension 观察工具完成
        Loop->>Agent: emit(message_end)
        Agent->>Session: persist toolResult message
        Note over Loop: 回到上下文准备阶段，进入下一轮
        Loop->>Provider: next LLM call (with tool results)
    end
    
    Loop->>Agent: emit(agent_end)
    Agent->>Session: session complete
    Agent->>Editor: render final state

关键节点说明

1. transformContext 是 AgentMessage[] 级的预处理点。裁剪历史、注入额外上下文、实现 plan-like 控制通常放在这里
2. convertToLlm 是 AgentMessage[] -> Message[] 的边界转换。它负责过滤或改写应用层消息；真正的跨 provider 兼容处理还会在 pi-ai 的 provider 层继续发生
3. 三阶段工具执行保证了安全性。prepare 阶段可以拒绝执行（beforeToolCall 钩子），execute 阶段实际操作，finalize 阶段格式化输出
4. 事件驱动的持久化主要挂在 message_end 上。tool_execution_end 主要用于 UI 和 extension 观测，真正写入会话的是随后产生的 toolResult 消息

D. /compact 命令的端到端追踪

下面追踪用户在 pi CLI 中输入 /compact 命令时，系统内部发生的完整过程。

Phase 1：命令解析

用户输入: /compact
    ↓
interactive-mode: 识别 `/compact` 或 `/compact ...`
    ↓
handleCompactCommand(customInstructions)
    ↓
AgentSession.compact(customInstructions?)

/compact 不经过 agent 循环本身。它先由 interactive mode 在本地识别，再直接调用 AgentSession.compact(...)。

Phase 2：Compaction 触发

compact handler
    ↓
SessionManager.getEntries()  → 获取当前所有会话条目
    ↓
estimateTokens(messages)     → 估算当前 context token 数
    ↓
Agent.state.messages         → 获取当前消息列表
    ↓
emit("compaction_start", { reason: "manual" })

Phase 3：LLM 总结

compaction_start 事件
    ↓
构建 compaction prompt:
  "请总结以下对话的关键信息..."
  + 当前所有消息
    ↓
completeSimple(compactionModel, compactionContext)
  → 调用 LLM 生成总结
    ↓
收集 LLM 输出 → summary text

Compaction 使用的模型可能和主对话模型不同（通常用更快更便宜的模型）。

Phase 4：状态更新

summary text
    ↓
SessionManager.appendCompaction(
  summary,
  firstKeptEntryId,
  tokensBefore,
  details?
)
  → 将 compaction 记录追加到 JSONL
    ↓
buildSessionContext()
  → 从 entries 重建完整的 session context
    ↓
agent.state.messages = sessionContext.messages
  → 用重建后的消息列表替换 agent 状态
    ↓
emit("compaction_end", { result: { summary, firstKeptEntryId, tokensBefore, details } })

Phase 5：UI 更新

compaction_end 事件
    ↓
TUI 订阅者收到事件
    ↓
清空并重建 chat
    ↓
插入 compaction summary message
    ↓
刷新 footer / 状态显示

完整数据流

sequenceDiagram
    participant User
    participant TUI
    participant Session as AgentSession
    participant SM as SessionManager
    participant LLM as Compaction LLM

    User->>TUI: /compact
    TUI->>TUI: 识别 /compact 并提取自定义指令
    TUI->>Session: compact(customInstructions?)
    Session->>SM: getEntries()
    SM-->>Session: all entries
    Session->>Session: estimateTokens()
    Note over Session: tokensBefore = 150,000
    
    Session->>Session: emit(compaction_start)
    TUI-->>TUI: 显示 "Compacting..."
    
    Session->>LLM: completeSimple(summary prompt)
    LLM-->>Session: summary text
    
    Session->>SM: appendCompaction(summary, firstKeptEntryId, tokensBefore, details)
    Note over SM: 写入 JSONL:<br/>{type: "compaction", summary, ...}
    
    Session->>SM: buildSessionContext()
    SM-->>Session: sessionContext
    Note over Session: 从 entries 重建上下文
    Session->>Session: agent.state.messages = sessionContext.messages
    
    Session->>Session: emit(compaction_end)
    TUI-->>TUI: 重建 chat + 插入 summary message
    
    Note over User: 下次 LLM 调用只看到<br/>重建后的 context

关键观察

1. /compact 不经过 agent 循环。它是一次本地命令处理 + 一次独立的 LLM 调用
2. 状态重建而非直接替换。appendCompaction 记录压缩事件后，buildSessionContext() 从 entries 重建上下文，再赋值给 agent.state.messages。不是直接构造一条 summary 消息替换
3. 持久化保留历史。SessionManager 记录 compaction 事件，但不删除历史条目。JSONL 是 append-only 的，buildSessionContext() 负责根据 compaction 记录决定哪些 entries 构成当前 context
4. 事件驱动 UI。TUI 不直接参与 compaction 逻辑，只订阅事件更新显示

E. 二次开发入口清单

F. 术语对照表

版本演化说明

本附录基于 pi-mono v0.66.0。类型名、文件路径、函数签名可能随版本更新而变化。 设计模式和二次开发入口的结构性建议预计长期有效。