127 lines (102 loc) · 7.14 KB

第十四章 · 术语表

所有关键术语的中英文对照与简明释义。
按逻辑分组，而非字母排序。

架构层级

术语	英文	释义	所属层
Agent Harness	Agent Harness	智能体运行框架，负责驱动 LLM + 工具循环执行的整体架构	全局
Monorepo	Monorepo	单一仓库管理多个包的项目组织方式	全局
pi-ai	pi-ai	LLM 通信抽象层，统一 30+ Provider 的调用接口	Layer 1
agent-core	pi-agent-core	Agent 运行时引擎，实现循环、工具执行、状态管理	Layer 2
coding-agent	pi-coding-agent	面向开发者的编码 Agent CLI 产品	Layer 3

LLM 通信

术语	英文	释义
Provider	Provider	LLM 服务提供商（OpenAI、Anthropic、Google 等）
Model	Model	具体的 LLM 模型（claude-opus-4-6、gpt-4o 等），包含 ID、API 类型、成本等元信息
API	API	Provider 的接口协议类型（anthropic-messages、openai-responses 等）
stream()	stream function	pi-ai 的统一 LLM 调用函数，返回异步事件流
StreamFn	Stream Function	stream() 的类型签名，可被替换以自定义 LLM 调用行为
Context	Context	发给 LLM 的完整上下文，包含 system prompt、消息历史、工具定义
Thinking Level	Thinking Level	LLM 思维深度级别：off / minimal / low / medium / high / xhigh / max
transformMessages()	Transform Messages	跨 Provider 消息格式兼容转换函数
懒加载	Lazy Loading	Provider 实现模块在首次使用时才加载，避免启动时引入所有 SDK

Agent Loop

术语	英文	释义
Agent Loop	Agent Loop	智能体循环：调用 LLM → 执行工具 → 反馈结果 → 再调用 LLM
内循环	Inner Loop	处理工具调用和 Steering 消息的循环，直到 LLM 不再调用工具
外循环	Outer Loop	处理 Follow-up 消息的循环，内循环结束后检查是否有后续任务
Steering	Steering	在 Agent 运行时注入消息改变行为的机制（如用户在执行中途发指令）
Follow-up	Follow-up	Agent 停止后才处理的排队消息
Turn	Turn	一轮对话：从发送消息到 LLM，到处理完所有工具调用
stopReason	Stop Reason	LLM 停止输出的原因：endTurn / toolCall / length / error / aborted

工具系统

术语	英文	释义
AgentTool	Agent Tool	工具定义，包含名称、参数 schema、执行函数
Tool Call	Tool Call	LLM 请求执行某个工具，包含工具名和参数
Tool Result	Tool Result	工具执行完毕的返回值，包含给 LLM 的 content 和给 UI 的 details
beforeToolCall	Before Tool Call	工具执行前的拦截钩子，可以阻止执行
afterToolCall	After Tool Call	工具执行后的修改钩子，可以修改结果
Operations	Operations Interface	工具执行环境的抽象接口（FileSystem + Shell），实现环境解耦
ExecutionEnv	Execution Environment	FileSystem + Shell 的组合接口
FileMutationQueue	File Mutation Queue	序列化同一文件写操作的队列，防止并行冲突
executionMode	Execution Mode	工具执行策略：parallel（并行）或 sequential（顺序）

消息系统

术语	英文	释义
AgentMessage	Agent Message	Agent 内部使用的消息超集，包含自定义类型
Message	Message	LLM 能理解的标准消息（user / assistant / toolResult）
最晚转换	Late Conversion	仅在调用 LLM 的最后一刻才把 AgentMessage 转为 Message 的策略
convertToLlm()	Convert to LLM	执行最晚转换的函数，过滤掉自定义消息类型
AssistantMessage	Assistant Message	LLM 的回复消息，可同时包含文本、思维链和工具调用
ToolResultMessage	Tool Result Message	工具执行结果消息，通过 toolCallId 关联到对应的 Tool Call

事件系统

术语	英文	释义
EventStream	Event Stream	Pi 自实现的异步可迭代事件流
AgentEvent	Agent Event	Agent Loop 发射的事件（agent_start / message_update / tool_execution_end 等）
AgentHarnessEvent	Agent Harness Event	产品层发射的扩展事件（包含 AgentEvent + Harness 自有事件）
subscribe()	Subscribe	注册事件监听器的方法
背压	Backpressure	生产者速度超过消费者时的排队机制

上下文工程

术语	英文	释义
Compaction	Compaction	上下文压缩：把旧对话压缩为结构化摘要，释放窗口空间
Branch Summary	Branch Summary	分支摘要：切换 Session Tree 分支时，旧分支的对话压缩为摘要
transformContext	Transform Context	每次调 LLM 前的临时上下文变换钩子（不修改持久化数据）
reserveTokens	Reserve Tokens	为新对话预留的 token 空间
keepRecentTokens	Keep Recent Tokens	压缩时保留的最近消息的 token 数
FileOperations	File Operations	压缩摘要中追踪的文件操作记录（read / written / edited）
Context Window	Context Window	LLM 模型的上下文窗口大小（可处理的最大 token 数）

会话管理

术语	英文	释义
Session Tree	Session Tree	树状的对话历史结构，支持分叉和导航
SessionTreeEntry	Session Tree Entry	Session Tree 中的节点，有 12 种类型
Leaf	Leaf	Session Tree 的叶子节点，标记当前活跃位置
Fork	Fork	从历史某个节点创建新分支
JSONL	JSON Lines	每行一个 JSON 对象的存储格式
SessionStorage	Session Storage	会话存储的抽象接口
SessionRepo	Session Repository	会话仓库，管理多个 Session 的创建/打开/删除/分叉

扩展系统

术语	英文	释义
Skill	Skill	Markdown 格式的技能文件，注入到 system prompt
Extension	Extension	TypeScript 模块，可注册工具、钩子、命令等
Prompt Template	Prompt Template	可复用的提示词模板，支持变量插值
Pi Package	Pi Package	扩展的分发单元（npm 包或 git 仓库）
双通道解析	Dual-pass Parsing	先解析内置标志，加载扩展后再解析扩展自定义标志
agentskills.io	Agent Skills Spec	Skills 格式化注入 system prompt 的开放规范

设计模式

术语	英文	释义
Result 类型	Result Type	`{ok: true, value}` \| `{ok: false, error}` 显式错误处理模式
垂直分层	Vertical Separation	每层独立可替换，上层不反向依赖下层
环境解耦	Environmental Decoupling	工具定义与执行环境分离，同一工具可在不同环境运行
一等公民	First-class Citizen	扩展不是后补丁，而是从架构设计之初就考虑的核心能力

上一章：第十三章 · SDK 与嵌入集成
回到开头：第零章 · 全景导读