阅读顺序指南
主线通读、30 分钟速览、按角色切入。
全景手册按读者认知顺序编排，读者可按需选择通读路线或针对特定模块重点突破。
主线通读
主线 = 七部分的天然认知演化顺序，与侧栏目录结构完全一致：
起点 → 认识项目 → 演进历程 → 核心方法论 → 核心实现 → 数据与集成 → 部署与运维 → 参考与规范预计用时 2–3 小时。适合需要完整接手、审计或进行二次开发的工程师。各章节虽自成一体，但按序阅读最容易建立一致的心智模型。
30 分钟速览
- 封面与总览。封面 → 项目总览：建立一句话定位与 n=1 自托管核心认知。
- 架构与边界。系统架构 → 职责边界：看清运行时目录分层、数据流向以及明确「不做」的技术债。
- 核心方法论。终端等价 → 安全模型 → 单驾驶员：掌握双向流、设备 TOFU 与防写分叉机制。
- 快速跑通。快速开始：掌握交互式配置向导、doctor 自检与最短启动链路。
- 校准事实。漂移清单：核对当前版本真实边界与代码事实。
按角色切入
| 关注角色 | 优先研读 | 进阶参考 |
|---|---|---|
| 自托管运维 | 快速开始、生产部署、运维排错、环境变量参考 | 安全模型、鉴权与设备信赖 |
| 后端与同步开发 | 系统架构、AgentSession、事件信封、单驾驶员、数据全景 | 会话与历史、契约与工程门禁 |
| 前端与交互开发 | 前端与 PWA、事件信封、事件参考 | 通知与状态栏 |
| 安全合规审计 | 安全模型、鉴权与设备信赖、文件上传、职责边界 | 生产部署（拓扑与反代防护） |
| 代码贡献者 | 项目规范、契约与工程门禁、术语表 | 架构演进主线、漂移清单 |
事实基线约定
以代码为准手册基于 dev 源码深度核对（基线 HEAD
687bca3），紧密对齐 docs/hard-rules.md 与各项架构不变量。代码若持续演进，以生产代码和自动化门禁为准，所有已知出入透明沉淀于漂移清单。
全局搜索与深浅色在手册任意页面按下 ⌘K / Ctrl+K 可快速调起全文即时搜索。点击顶栏月亮/太阳图标或按下键盘快捷键 T 即可平滑切换深浅色模式，首屏加载内置防闪白机制。