附录 A 常用术语速查

使用和运行环境

终端（Terminal）：输入文字指令、接收文字结果的窗口。它可以承载 Shell，也可以承载 Pi 的交互界面。

Shell：解释系统命令的程序，例如 bash、zsh。Pi 中的 /model 属于 Pi 的命令，不是 Shell 指令。

CLI：命令行界面。Pi 的 pi 命令是用户入口，交互、打印和 RPC 是不同运行方式。

TUI：终端用户界面。在文字终端中显示编辑器、选择菜单和实时内容。

工作目录（Working Directory）：程序处理相对路径时的起点，也影响 Pi 的项目配置和会话发现。

PATH：Shell 查找可执行命令时检查的一组目录。装好了命令却提示找不到，可能与 PATH 有关。

进程（Process）：正在运行的程序实例。进程退出后，未写入持久存储的普通内存状态会消失。

Node.js：在浏览器之外运行 JavaScript 的环境。它与模型服务不是一回事。

npm：管理 JavaScript 软件包及依赖的工具，也能执行 package.json 中定义的脚本。

代码和工程组织

TypeScript：在 JavaScript 上增加类型描述的语言。类型检查能提前发现部分使用错误，但不能保证所有行为正确。

模块（Module）：组织和复用代码的单位，通过 import、export 连接。ESM 是本项目采用的标准模块系统。

包（Package）：可以安装、发布或复用的一组代码与说明。一个目录是不是独立包，要看它的包配置。

依赖（Dependency）：程序需要使用的其他包。直接依赖由自己声明，间接依赖由其他依赖继续引入。

工作区（Workspace）：npm 把多个本地包组织起来共同开发的机制。

Monorepo：多个包共用一个源码仓库。Pi 把产品和支持库放在一起，方便协同修改。

锁文件（Lockfile）：保存具体依赖解析结果的文件，例如 package-lock.json。

API：应用程序接口。可指代码函数，也可指网络服务协议，必须结合上下文判断。

SDK：供其他程序接入功能的开发接口集合。使用 Pi SDK 不要求先模拟终端按键。

异步、Promise、await：分别指需要等待的操作、未来结果的表示，以及等待结果的写法。等待可能成功、失败或被取消。

JSON：表达结构化数据的文本格式。JSONL 是每行一个完整 JSON 值的记录形式。

YAML：另一种常用文本配置格式。技能或模板开头的配置区可以使用 YAML；它与 JSON 的语法不同。

Schema：数据结构说明，例如规定必须有字符串字段 path。JSON Schema 是一种常见说明格式。描述和实际校验应分别确认。

元数据（Metadata）：描述数据的信息。例如模型的价格、上下文上限、支持能力，而不是模型的一段回答正文。

模型、执行与会话

模型（Model）：根据输入生成内容的系统。可调用模型条目通常还有名称、能力和限制信息。

Provider：提供模型访问能力的供应商运行单元，管理相应模型目录、鉴权和请求行为。

Token：模型处理内容的计量单位，不等同于汉字、单词或字节。

流式输出（Streaming）：一段结果尚未全部生成时，就逐批返回内容或事件。

工具（Tool）：宿主程序提供的具体能力。工具定义描述如何调用，工具执行才真正操作资源。

工具调用（Tool Call）：模型提出的一次结构化操作请求，通常包含名称、参数和调用标识。

Agent：让模型、工具和结果反复配合，逐步推进工作的程序。在本项目中还需区分通用 Agent 与外层会话。

Harness：运行框架。它把执行、状态、工具和生命周期管理组合起来；Durable 中的 Harness 还是一个具体公共类名。

上下文（Context）：模型这次请求能看见的信息。存储中拥有的全部历史不一定都进入上下文。Chord 的同名 Context 则是传递取消和追踪等信息的程序对象。

消息（Message）：用户、助手、工具或系统留下的内容记录。

事件（Event）：关于执行进度的通知，例如文字增加、工具结束。事件与永久消息不是一一对应。

轮次（Turn）：在 Agent 循环语境下，一次模型回答及其要求的工具执行。一项任务可能跨越多轮。

Steering：在当前工作中途补充方向的排队输入，按执行边界进入后续上下文。

Follow-up：当前工作自然结束后再处理的后续输入。

会话（Session）：围绕一段工作的历史和相关设置。CLI 会话树、模型上下文和磁盘文件状态应分别理解。

压缩（Compaction）：把较早历史整理成摘要、缩小后续模型请求的上下文，不等于删除原始会话文件内容。

钩子（Hook）：宿主可以接入自定义处理的预留调用位置，例如在工具执行前检查请求。

扩展与持久化

扩展（Extension）：在宿主进程中运行的模块，可以增加工具、命令或事件处理。

技能（Skill）：按任务需要读取的指导和配套资源，通常以 SKILL.md 为入口。

提示模板（Prompt Template）：可反复展开使用的文本请求，可带参数占位符。

MCP：模型上下文协议，提供连接外部工具和相关资源的共同通信约定。

RPC：远程过程调用，把一个程序的操作请求传给另一个程序执行。

Codemode：代码模式，用一段脚本组织多次工具调用，并整理要交回模型的内容。

持久化（Persistence）：把状态写入能跨越当前进程生命周期的存储。

原子提交（Atomic Commit）：一组变更要么共同生效，要么不生效。

检查点（Checkpoint）：记录任务阶段和继续执行所需数据的持久状态。

副作用（Side Effect）：操作对外部世界产生的变化，例如写文件、发邮件、扣款。

幂等（Idempotent）：同一个操作执行多次，业务效果与执行一次相同。外部系统常用唯一请求标识帮助实现。

快照与增量（Snapshot / Delta）：前者是完整状态，后者描述状态的变化。

SSH：用于加密远程连接的协议。主机密钥用来帮助确认连接的服务器身份。

遥测或诊断数据（Telemetry）：程序执行中的追踪、事件和指标。span 表示一段操作的时间与关联信息。

评测（Eval）：测量模型或 Agent 完成任务效果的过程，可能需要真实模型调用；与普通确定性单元测试不同。