附录 B：核心类型速查

以下是概念结构，不替代源码的完整泛型定义。

1. Model

Model<TApi> 描述一个可调用模型：

id、name；
provider、api、baseUrl；
Reasoning/Image 等能力；
Context Window、Max Tokens；
Cost Metadata。

Model 是能力与路由描述，不是 Provider Client 实例。

源码：packages/ai/src/types.ts、packages/ai/src/models.ts。

2. Message

主要角色：

UserMessage
AssistantMessage
ToolResultMessage

Assistant Content 可包含 Text、Thinking、ToolCall。ToolResult 用 toolCallId 回应对应调用。 Agent Message、LLM Message、Session Entry 和桌面 UI Item 不是同一种类型。

3. Tool

Tool Definition 关注：

Name/Label/Description；
TypeBox Parameters Schema；
Execute；
Progress Update；
Result Content/Details；
AbortSignal。

模型看到的是 Tool Schema；运行时执行的是宿主实现。

4. ToolCall 与 ToolResult

ToolCall:
id + name + arguments

ToolResult:
toolCallId + toolName + content + details + isError

content 进入模型上下文；details 更适合 UI/状态。Partial Arguments 只能展示，不能执行。

5. Agent

Agent 管理：

当前 Model/System Prompt/Tools；
Message State；
Agent Loop；
Steer/Follow-up Queue；
Abort；
Event Listener；
Context/Tool Hooks。

Agent 不等于完整 AgentSession；后者再加入资源、持久化、压缩和 Extension。

6. AgentEvent

核心事件族：

agent_start / agent_end
turn_start / turn_end
message_start / message_update / message_end
tool_execution_start / update / end

只有 Assistant Message 有流式 message_update。Tool 使用 toolCallId；普通 Message 没有统一稳定 ID，桌面层应生成自己的 UI Key。

7. AgentSession

AgentSession 组合：

Agent；
SessionManager；
ResourceLoader；
Model/Settings Runtime；
Extension Runner；
Retry/Compaction/Queue；
Coding Tools；
AgentSessionEvent。

它代表当前 Session Runtime，不负责多窗口 UI。

8. SessionEntry

Session Entry 具有稳定 id、parentId 与类型。它们形成 Tree：

Header
└── Message Entry
    ├── Message Entry
    └── Message Entry（另一条 parentId 分支）

Message、Compaction、Model Change、Custom Entry 等以不同 Entry 形式保存。精确字段以 session-manager.ts 的 Union 为准。

9. Skill

Skill 是从 SKILL.md 解析出的资源：

Name；
Description；
File Path/Base Directory；
Source Info；
是否允许模型自动调用。

完整正文不保存在 Skill 对象里，而是在调用时按需从 filePath 读取；Diagnostics 属于 LoadSkillsResult。Skill 不是可直接执行的函数。

10. Extension

Extension 通常是：

type ExtensionFactory = (pi: ExtensionAPI) =>
  void | Promise<void>;

Factory 使用 ExtensionAPI 注册：

Event Handler；
Tool/Command/Flag；
Provider；
UI/Resource 相关行为。

加载后形成 Extension Object/Runtime，再由 Runner 与 AgentSession Binding 连接。

11. Extension Context

Handler Context 可能提供：

CWD；
SessionManager；
Model/Provider；
AbortSignal；
UI Binding；
Pending Message 状态；
宿主动作。

Context 属当前 Extension Runtime/Session。Replacement 后旧 Context 应视为失效。

12. Provider

不要混淆三类形态：

完整 Provider Object；
Legacy ProviderConfig；
createProvider() 组合器。

它们的 Model 类型、刷新返回值与 Store 责任不同，详见第 28 章。

13. Desktop Envelope（宿主类型）

以下不是 Pi 原生 Event 字段：

interface DesktopEventEnvelope {
  runtimeId: string;
  sessionId: string;
  generation: number;
  localSequence: number;
  event: AgentSessionEvent;
}

runId、windowOwner、UI Message Key、Approval Envelope 也由宿主补充。