把知识库变成 OS

把 OS 当成产品与交互模型，而不是一层桌面皮肤。除非用户明确要求改变，否则应保留源系统的 URL、数据归属、后端行为和主要用户任务。

完整案例见 references/maidang-personal-os-case-study.md。

工作原则

1. 提出架构前先阅读真实仓库。
2. 找出数据真源、公开路由、后台路由、API、渲染边界和现有测试。
3. 将内容语义与 OS 展现分离。
4. 文件、窗口、导航和持久运行时使用稳定 ID 与纯状态转换。
5. 每次只实施一个边界清晰的规格。
6. 不能只根据代码存在或勾选框判断规格完成，必须记录测试、构建、浏览器和部署证据。
7. 保留工作区中无关的改动。

工作流

1. 先审计，再设计

阅读 references/discovery-and-modeling.md。

输出一份精简审计，包含：

• 内容来源与归属；
• 公开和后台路由；
• 当前用户任务；
• 内容类型、关系与稳定标识符；
• 可复用 API 和领域视图；
• 当前响应式、无障碍、SEO 与部署约束；
• 改版后必须保留的行为。

不要从窗口外框或图标开始。

2. 判断什么是文件，什么是应用

默认规则：

• 文件是用户会打开、阅读、预览或导出的持久内容对象。
• 文件夹是拥有真实子项的导航分组。
• 应用负责工作流、运行时、命令或持久状态。
• 查看器负责解释一种或多种文件/资源类型。
• 系统服务独立于窗口持续存在，例如媒体播放或后台同步。

不要把每条路由都伪装成文件夹。音乐、邮件、搜索、终端、编辑器和后台工具通常是应用；文章、笔记、图片、记录和数据集通常是文件。

3. 先定义产品，再定义运行时

编写或更新：

• PRD；
• 技术方案；
• OpenSpec 协议；
• OpenSpec 索引与依赖顺序；
• 仅第一份 ready 规格。

文档结构见 references/templates.md。

PRD 必须说明 OS 隐喻为什么能改善用户工作。任何让阅读、搜索、编辑、联系或发布变慢的装饰性 OS 功能都应拒绝。

4. 分层构建系统

阅读 references/architecture-patterns.md。

优先采用以下依赖方向：

内容来源
   |
领域适配器
   |
虚拟资源 + 应用注册表 + 命令注册表
   |
OS 运行时 + 持久服务运行时
   |
桌面工作区 / 移动工作区 / 应用模式 / 后台模式

明确保持以下边界：

• 领域数据独立于窗口；
• 应用定义独立于应用运行时状态；
• 窗口状态由纯 reducer 或等价状态机管理；
• 不同界面的查看器不能各自重复获取和重塑同一份数据；
• 持久服务不会随窗口关闭而终止；
• 菜单和 Dock 执行命令，不持有业务逻辑。

5. 分阶段执行 OpenSpec

阅读 references/openspec-sequence.md。

默认顺序：

1. 静态视觉与交互原型。
2. 窗口生命周期和 Finder/导航。
3. 真实只读虚拟文件系统。
4. 领域查看器。
5. 嵌入式交互体验。
6. 无障碍、错误状态、响应式质量和性能。
7. 路由切换与回退。
8. 共享设计系统和应用注册表。
9. 菜单、Dock、事务型应用和持久运行时。
10. 直接路由应用模式、后台模式与全站发布。

在视觉方向、路由切换、破坏性数据变更和生产发布门禁处暂停确认。

6. 状态逻辑先行

每份规格按以下步骤执行：

1. 将状态设为 in_progress。
2. 为 reducer、适配器、ID、映射和不变量添加纯逻辑测试。
3. 实现最小但完整的纵向行为。
4. 为用户可见状态添加组件测试。
5. 运行真实浏览器工作流。
6. 运行类型检查和生产构建。
7. 将精确证据写回规格。
8. 只有每条验收标准都有证据时才设为 done。

在首次出现真实重复或归属冲突前，不要提前引入抽象。

7. 验证产品，而不只是组件

阅读 references/testing-and-release.md。

最低验证范围：

• 数据映射和树不变量；
• 打开/聚焦/关闭/重开与导航状态；
• 键盘、焦点恢复和触控目标；
• 空、加载、错误、不可用状态；
• 多种视口尺寸；
• 窗口重叠与 stacking context；
• iframe/媒体的懒加载和生命周期；
• 直接路由、metadata、canonical URL、sitemap 与 revalidation；
• 生产构建；
• 部署后冒烟测试与回退路径。

视觉正确性重要时，要检查截图和计算后的布局值，不能仅凭 DOM 节点存在就判定成功。

不可妥协的设计原则

• 真实用户任务优先于 OS 拟真度。
• 每个可见控件都必须可用，或明确显示为禁用。
• 应用身份、内容身份和后端数据各自只有一个真源。
• 使用稳定的资源与窗口 ID；再次打开同一资源时应聚焦，而不是重复创建。
• 桌面图标位于窗口之下；系统菜单与 Dock 位于窗口之上；嵌入媒体与所属窗口处于同一 stacking context。
• 重型第三方运行时只在用户明确操作后懒加载。
• 直接 URL 必须有用。分享文章链接时应直接打开文章应用，而不是强迫读者先完成桌面操作仪式。
• 移动端使用应用工作区，不要缩小可拖动桌面窗口。
• 后台界面保持高密度和工作导向，不要把装饰性桌面构图套在运营工具上。
• 路由级回退应尽可能独立。仅为表现层改版时避免数据迁移。

预期交付物

根据任务只创建或更新真正需要的产物：

• 仓库审计；
• 内容到资源/应用的映射表；
• PRD；
• 技术方案；
• OpenSpec 协议与索引；
• 分阶段实施规格；
• 对争议边界的架构决策记录；
• 聚焦的测试和浏览器证据；
• 发布与回退证据。

明确写出假设和未解决门禁。只改完首页时，不能宣称整个产品已经成为 OS。