# 阅读顺序指南
> 主线通读、30 分钟速览、按角色切入。

- **Part**: 起点
- **Reading Time**: ~8 min
- **Estimated Tokens**: ~1331

---

全景手册按读者认知顺序编排，读者可按需选择通读路线或针对特定模块重点突破。

## 主线通读

主线 = 七部分的天然认知演化顺序，与侧栏目录结构完全一致：

```
起点 → 认识项目 → 演进历程 → 核心方法论 → 核心实现 → 数据与集成 → 部署与运维 → 参考与规范
```

预计用时 2–3 小时。适合需要完整接手、审计或进行二次开发的工程师。各章节虽自成一体，但按序阅读最容易建立一致的心智模型。

## 30 分钟速览

1. 封面与总览。 封面 → 项目总览 ：建立一句话定位与 n=1 自托管核心认知。
2. 架构与边界。 系统架构 → 职责边界 ：看清运行时目录分层、数据流向以及明确「不做」的技术债。
3. 核心方法论。 终端等价 → 安全模型 → 单驾驶员 ：掌握双向流、设备 TOFU 与防写分叉机制。
4. 快速跑通。 快速开始 ：掌握交互式配置向导、doctor 自检与最短启动链路。
5. 校准事实。 漂移清单 ：核对当前版本真实边界与代码事实。

## 按角色切入

| 关注角色 | 优先研读 | 进阶参考 |
| --- | --- | --- |
| 自托管运维 | 快速开始 、 生产部署 、 运维排错 、 环境变量参考 | 安全模型 、 鉴权与设备信赖 |
| 后端与同步开发 | 系统架构 、 AgentSession 、 事件信封 、 单驾驶员 、 数据全景 | 会话与历史 、 契约与工程门禁 |
| 前端与交互开发 | 前端与 PWA 、 事件信封 、 事件参考 | 通知与状态栏 |
| 安全合规审计 | 安全模型 、 鉴权与设备信赖 、 文件上传 、 职责边界 | 生产部署 （拓扑与反代防护） |
| 代码贡献者 | 项目规范 、 契约与工程门禁 、 术语表 | 架构演进主线 、 漂移清单 |

## 事实基线约定

> **DRIFT NOTICE:** 以代码为准 — 手册基于 dev 源码深度核对（基线 HEAD 687bca3），紧密对齐 docs/hard-rules.md 与各项架构不变量。代码若持续演进，以生产代码和自动化门禁为准，所有已知出入透明沉淀于漂移清单。

> **TIP:** 全局搜索与深浅色 — 在手册任意页面按下 ⌘K / Ctrl+K 可快速调起全文即时搜索。点击顶栏月亮/太阳图标或按下键盘快捷键 T 即可平滑切换深浅色模式，首屏加载内置防闪白机制。