阅读指南¶
Herdr 的代码量不适合从 main.rs 一路点进所有调用。更高效的方式是先选一条“旅程”，只在遇到所有权或状态转换时横向展开。本页说明本站的证据标准、章节结构和几条适合不同目标的阅读路线。
拆解方法¶
参考项目中的深度拆解方式后，本站采用五层阅读法。
第一层：先找必须解决的问题¶
每章先给出系统约束。例如“服务器升级不能杀死 Agent”比“handoff.rs 有哪些函数”更能解释代码。没有问题背景，错误处理和序列号看起来都像偶然复杂度。
第二层：画完整旅程¶
把入口、通道、状态、运行时资源和输出放在一张图中。旅程图用于回答“数据下一站去哪里”，而不是替代代码。
第三层：锁定领域类型与所有权¶
优先读 struct/enum，然后才读 handler。对 Herdr 尤其要问：
- 这个字段是可序列化事实、派生缓存，还是活跃 OS 资源？
- 谁是唯一写者？
- 跨线程/进程后，使用 ID、消息还是锁共享？
- 它属于服务器、某个客户端，还是当前视图？
第四层：追正常路径与失败路径¶
正常路径只说明功能能跑；失败路径才暴露真实边界。因此每章都特别检查：
- 半完成操作怎样撤销；
- 队列满、客户端慢、进程退出时怎样降级；
- 旧异步结果如何被 sequence/generation 拒绝；
- 缓存基线何时可以安全推进。
第五层：用测试和静态守卫反证理解¶
测试名经常比注释更准确地表达维护者不愿破坏的契约。本站把单元测试、集成测试、Python 架构守卫和 CI 放在同一张证据图里，而不是把“测试”当作最后一个孤立章节。
源码链接规则¶
所有上游链接固定到提交：
例如：src/main.rs。这样做有三个好处：
- 页面今天和半年后指向同一份实现；
- 行号锚点不会因上游新提交漂移；
- 读者可以用同一提交复现实验和统计。
版本边界
本站不是 Herdr 永久不变的官方架构说明。它是对 0.8.0、固定提交的证据化剖面。后续上游演进应重新审计，而不是把本文结论直接套用。
四条阅读路线¶
图和伪代码怎么读¶
- Mermaid 图描述关系或时序，不保证节点名与 Rust 标识符一一相同；
- 标有
rust的代码若使用…，表示为了说明形状而裁剪； - 标有“等价伪代码”的片段重组了控制流，不应复制进项目；
- 表格中的“设计含义”属于基于源码的解释，不是上游公开承诺。
先记住的六个区分¶
| 容易混淆的概念 | 正确区分 |
|---|---|
AppState / App |
前者以纯状态为中心；后者还拥有通道、任务、deadline、cache 等协调资源 |
TerminalState / TerminalRuntime |
前者可持久化、服务器拥有；后者包裹活跃 PTY/VT/actor |
PaneId / public pane id / TerminalId |
布局内部节点身份 / 用户可见稳定编号 / 运行时重连键 |
compute_view / render |
前者允许更新派生几何和 resize；后者只读绘制 |
| screen detection / integration hook | 启发式可见证据 / Agent 主动上报的会话证据 |
| client protocol / local API | 二进制交互帧 / 行分隔 JSON 自动化接口 |
带着这六个区分进入正文，许多“为什么同一概念有两个类型”的问题会自然消失。