docs/ 只维护仍然有效的设计方案：目标、边界、关键决策、主流程、不变量和演进方向。它帮助开发者在阅读源码前建立系统模型，不承担逐字段复述当前实现的职责。
文档描述“为什么这样设计、模块如何协作、什么不能被破坏”。源码和机器可读契约描述“当前准确实现是什么”。二者冲突时，应先判断是实现偏离设计，还是设计决策已改变，再更新对应事实源。
应写入 docs/ |
不应写入 docs/ |
|---|---|
| 设计目标、非目标与职责边界 | 完整类型、字段、枚举和默认值清单 |
| 跨模块主流程与状态所有权 | 函数名、组件层级和逐文件调用过程 |
| 安全模型、失败策略和平台差异 | 可从源码直接得到的目录树、端口和命令 |
| 必须长期保持的不变量 | UI 像素、临时交互稿和当前测试数量 |
| 经确认的架构决策和演进方向 | 阶段性评估、讨论记录和已失效协议草案 |
实现示例只有在解释边界时才保留，并应短小、稳定。需要精确同步的内容应由代码生成到 contracts/，或由测试直接约束。
| 内容 | 权威来源 |
|---|---|
| 方向、边界、主流程、不变量 | docs/ |
| 精确接口、字段、默认值和运行逻辑 | src/、src/shared/ |
| 对外机器可读协议 | contracts/ |
| 可执行示例、兼容性和边界条件 | test/ |
| 用户工作流手工回归 | qa/manual-regression.md |
| Agent 的仓库工作约束 | AGENTS.md |
任何跨 Electron main、preload、renderer、内置服务、插件、webview 或 shared contract 的修改，先读架构与模块边界，再读所属专题。
- 启动初始化与恢复：启动阶段、事务恢复与就绪门禁。
- 服务生命周期：内置服务部署、启动、健康与停止边界。
- 内置资源与 Manifest：上游资源进入 Desktop 的发布链路。
- 版本化打包与卸载：平台打包、升级、回退和卸载所有权。
- 前端嵌入与导航：surface、webview、路由和导航状态。
- 鉴权、SSO 与 Token Bridge：身份信任边界与凭据分发。
- 桌面协议与动作桥：协议入口、动作模型、授权和页面控制。
- 智能助理集成：Agent Platform、WebClient、Main Assistant 与 Copilot。
- 插件体系与生命周期：插件包、能力、事务和隔离。
- 市场系统：远端 catalog 与本地安装状态的分工。
- 外部网站：Website 入口、session 和显式 capability。
- 本地网站应用：WebApp v2、gateway、进程和 bridge 边界。
- 桌宠系统：资产、窗口、状态和 Agent 绑定。
- 企业聊天：IM 服务、身份、消息、文件和桌面动作边界。
- 对话快照分享与导出：统一 Snapshot、公开 HTML 分享与本地单文件导出的边界。
- 看板与云同步：Server 权威缓存、受限原子操作和 run 同步。
新专题通常包含：
- 文档定位与非目标；
- 模块职责和数据所有权；
- 关键主流程；
- 安全、失败与平台差异；
- 长期不变量和演进原则；
- 指向源码、契约和测试的事实来源。
当修改只涉及字段、函数、端口、路径或视觉细节时，不更新设计文档；更新源码、contract、测试或 QA 清单即可。当职责边界、关键状态机、安全模型或跨模块流程变化时，代码和对应设计文档必须在同一变更中保持一致。