附录 B · 术语与数据字典
本页集中对照全书反复出现的类型、身份、状态、序列和协议。它不是 Rust API 文档，而是用于避免同名概念混用。
B.1 进程与角色
| 术语 |
含义 |
| Headless Server |
默认后台进程；拥有 AppState、PTY、API、client registry 和持久化 |
| App client |
前台完整 Herdr UI；把输入发给 server，绘制 server frame |
| Terminal client |
直接观察/控制某个 terminal/pane 的客户端角色 |
| Observer |
可读但无输入 lease，不应改变共享 PTY 尺寸 |
| Controller/foreground |
当前输入、焦点和共享 viewport 的权威 client |
| Monolithic App |
--no-session 下同一进程拥有 UI、state、PTY 的兼容模式 |
| Bridge |
在 SSH stdio/forward 与 server socket 间转发 wire bytes 的薄进程 |
| API connection worker |
解析 JSON、编排长 wait，再用短请求访问 App loop 的线程/任务 |
B.2 组织与身份
| 名称 |
作用域 |
是否持久 |
主要用途 |
| Session namespace |
当前 daemon/data/socket 隔离 |
是 |
default 或命名 session |
| Workspace public id |
session |
是 |
CLI/API 和用户导航 |
| Tab public id |
workspace |
是 |
CLI/API；关闭后不轻易复用 |
| Pane public id |
workspace/tab 解析上下文 |
是 |
CLI/API；稳定用户引用 |
PaneId |
当前内部布局 |
通常由 snapshot映射重建 |
BSP leaf/map key |
TerminalId |
terminal 生命周期 |
是/可交接 |
连接 TerminalState 与 runtime |
| ClientId |
server 进程内 |
否 |
transport、foreground、baseline |
| OperationId |
某类后台操作序列 |
否 |
拒绝 worktree 迟到结果 |
| Agent session id |
外部 Agent 语义 |
是（若已知） |
hook identity/native resume |
| Session generation |
terminal 内 Agent 生命周期 |
运行/恢复语义 |
拒绝旧进程 hook |
身份转换链
flowchart LR
User["public workspace/tab/pane ref"] --> Resolve["ID resolver"]
Resolve --> Pid["internal PaneId"]
Pid --> PState["PaneState"]
PState --> Tid["TerminalId"]
Tid --> TState["TerminalState"]
Tid --> Registry["RuntimeRegistry"]
Registry --> Runtime["TerminalRuntime / PTY"]
B.3 状态与运行时
| 类型 |
保存什么 |
明确不保存什么 |
AppState |
terminal/workspace/mode/view/config/通知等权威事实 |
socket listener、PTY actor、background join handle |
App |
AppState + runtime registry + channels/deadlines/caches |
— |
Workspace |
tabs、公开 counters、cwd/Git/worktree metadata |
PTY handle |
Tab |
layout、pane map、focus、zoom |
terminal child ownership |
PaneState |
attached TerminalId、seen、pane UI preference |
VT/PTY |
TerminalState |
cwd、Agent/session/hook、title/metadata、launch/resume、revision |
live PTY/VT task |
TerminalRuntime |
terminal 的活跃 runtime wrapper |
持久磁盘 schema |
PaneRuntime |
PTY I/O、VT、child、尺寸、tasks |
稳定视图位置 |
TerminalRuntimeRegistry |
TerminalId -> TerminalRuntime |
layout/公开 ID |
SessionSnapshot |
恢复所需、版本化的稳定投影 |
全部内部 state/cache/runtime |
B.4 Agent 状态
| 名称 |
层 |
含义 |
Unknown |
raw/effective |
当前证据不能可靠判断 |
Idle |
raw/effective |
当前可接收新工作或工作停止 |
Working |
raw/effective |
正在推理、运行工具或输出 |
Blocked |
raw/effective |
等待用户授权、选择或输入 |
Done |
UI projection |
effective Idle 且关联 pane 输出未读 |
| fallback state |
仲裁输入 |
进程/屏幕/OSC 推导结果 |
| hook state |
仲裁输入 |
integration 主动报告结果 |
| visible blocker |
证据标记 |
当前可见区域有强阻塞证据 |
| full-lifecycle authority |
source capability |
hook 覆盖完整 start/stop/blocked 生命周期 |
skip_state_update |
manifest output |
当前界面不适合判断，保留旧有效状态 |
B.5 Sequence、Revision、Generation
| 名称 |
谁推进 |
比较范围 |
解决的问题 |
| Terminal revision |
TerminalState mutation |
同一 TerminalId |
下游是否需要更新 |
| VT content sequence |
terminal output parser |
同一 runtime/session |
output/detection 是否有新内容 |
| Hook sequence |
integration report |
同 source + Agent session |
迟到报告覆盖新状态 |
| Session generation |
process/session lifecycle |
同一 TerminalId |
旧进程报告复活 |
| EventHub sequence |
server EventHub |
当前 server 进程 |
probe/subscribe setup window |
| State change sequence |
Agent effective state |
同一 terminal identity |
prompt/wait 不误用初始状态 |
| Render/frame sequence |
per client encoding |
同一 client connection/baseline |
diff 顺序和 repaint |
| Worktree operation id |
App |
对应 pending key/workspace |
后台乱序完成 |
不要做全局大小比较
两个不同作用域的 sequence 数值没有可比性。hook seq 50 不比 EventHub seq 40“更新”；只有身份和来源都一致时，单调关系才成立。
B.6 布局与视图
| 名称 |
含义 |
| BSP |
Binary Space Partition；Pane 叶子与 Split 内部节点组成的二叉布局树 |
| Split ratio |
first child 在该轴占比，合法值夹在 0.1–0.9 |
| Geometry |
从 BSP + 当前 area 派生的 pane/border rect，不是持久绝对坐标 |
| Focus |
当前输入目标；属于 tab/workspace/client 视图语义 |
| Zoom |
暂时把一个 pane 投影到主要区域，原布局不被销毁 |
ViewState |
sidebar、pane、overlay、hit target 等派生 rect |
ViewLayout |
Desktop/Mobile 呈现策略 |
Mode |
下一次输入如何解释的 UI 状态机 |
compute_view |
允许更新派生几何，并按 policy resize runtime |
render |
对准备好的 state 做只读绘制 |
B.7 Terminal 与 PTY
| 术语 |
含义 |
| PTY master/slave |
Herdr 持有 master；child 把 slave 当 controlling terminal |
| ConPTY |
Windows 的伪控制台路径，由 portable-pty 适配 |
| VT |
有状态 terminal emulator；消费 escape bytes，维护 grid/modes/history |
| Ghostty VT |
Herdr vendored 的 libghostty-vt 内核及 Rust FFI wrapper |
| main/alternate screen |
普通带 scrollback 屏幕与全屏应用常用的临时屏幕 |
| terminal response |
VT 对 DSR/DA 等查询自动生成并回写 child 的 bytes |
| bracketed paste |
让 child 区分 paste 与逐键输入的包围序列 |
| Kitty keyboard |
更完整表达按键/修饰/事件类型的终端协议 |
| SGR mouse |
把 mouse button/坐标编码成 CSI 的常见协议 |
| dirty row/patch |
VT 自上次基线后变化的可见行/局部 cells |
| full snapshot |
baseline不可信或结构变化时的完整 viewport/frame |
B.8 渲染与客户端
| 名称 |
含义 |
| Virtual backend |
server 端内存 cell buffer，替代物理 terminal backend |
SemanticFrame |
结构化 cell/style/cursor frame |
TerminalAnsi |
将 server frame 差异编码成 ANSI 操作 |
| Baseline |
某 client 已成功接收、下一次 diff 可依赖的帧 |
| Repaint pending |
baseline 不可信/queue drop 后要求完整重绘 |
| Render impact |
状态变化对呈现的影响分类，如 none/graphics/full |
| Retained render |
复用旧 virtual frame，只把安全 dirty patch 合入 |
| Foreground client |
决定共享 PTY resize、focus、输入 lease 的 client |
| Backpressure |
有界 queue 让慢 consumer不能无限积压或拖住 server |
B.9 API 与事件
| 名称 |
含义 |
| Local API |
session-scoped Unix/local socket 上的 JSON-lines 自动化协议 |
Method |
92 个 typed method 的 serde tagged enum |
| EventHub |
为事件分配 sequence 并保留有界内存 history |
| Probe |
向 App 单写者查询当前权威 snapshot |
| Wait worker |
API 连接侧等待事件、重 probe、处理 timeout/cancel |
| Setup window |
初次 probe 与完成 subscription 建立之间可能丢事件的窗口 |
| Identity match |
wait 每次 probe 验证仍是最初 terminal/session |
| JSON Schema |
checked-in 的跨语言 API 契约 |
B.10 持久化与交接
| 名称 |
含义 |
| Snapshot v3 |
当前 session 磁盘结构版本 |
| History file |
与结构 snapshot 分开的可选 ANSI/line history |
| Dirty/debounce |
多次状态变化合并为后续一次保存 |
| Native resume |
用 Agent session/特定 argv 恢复原生会话 |
| Live Handoff |
新 server 接管旧 server 活跃 PTY/runtime 的 Unix 能力 |
| Handoff manifest |
snapshot + runtime descriptors + transfer metadata |
| Private handoff socket |
old/new server 准备阶段的非公开协调通道 |
| Public sockets |
client/API 正常连接端点；切换需要 rollback |
| Ownership release |
旧 server不杀 child地放弃已成功转移的资源 |
B.11 Integration 与 Plugin
| 名称 |
含义 |
| Integration |
安装到外部 Agent 的 hook/extension/plugin，用于报告 state/session |
| Integration target |
16 个受支持 Agent 配置目标之一 |
| Bundled asset |
编译进 Herdr 二进制的 sh/PS1/JS/TS/Python 配置资产 |
| Ownership marker |
证明某配置项/文件由 Herdr 安装，支持精确卸载 |
| Plugin |
用户 link 的本地命令型 Herdr 扩展 |
| Plugin registry |
全局 linked path/source/enabled 持久记录 |
| Plugin action |
在上下文中显式调用的 argv command |
| Event hook |
允许的低频 Herdr 事件触发的后台 command |
| Plugin pane |
overlay/popup/split/tab/zoomed 中运行的工具命令 |
B.12 Git 与远程
| 名称 |
含义 |
| Worktree membership |
workspace 与 source repo/checkout/branch 的稳定关联 |
| Checkout key |
canonical-or-original 的路径身份，用于 pending 去重 |
| Porcelain |
Git 面向机器、较稳定的输出格式 |
| Dirty removal |
modified/untracked checkout 必须显式 force |
| Orphan recovery |
Git 已不注册但残留目录时，经归属证明后的强制清理 |
| Remote target |
SSH user/host 等逻辑连接身份 |
| Asset key |
OS/arch 标准化发布物键，如 linux-x86_64 |
| Exact preview build |
base version + build id/commit/protocol 对应的归档 artifact |
| SSH ControlMaster |
Unix 上复用认证连接的 OpenSSH 能力 |
| Local forward socket |
本地 client 与 SSH bridge 的临时 IPC 端点 |