omarchycn/OmarchyCN PRD.md

# OmarchyCN 产品需求文档（PRD）

> China-native, AI-first Omarchy downstream distribution.

| 项目 | 内容 |
|---|---|
| 产品名称 | OmarchyCN |
| 产品类型 | 基于 Omarchy 的中国开发者下游发行版与可叠加发行层 |
| 文档版本 | 1.0 |
| 文档状态 | Implementation Draft |
| 文档负责人 | Zachary Zhang / OmarchyCN Community |
| 更新时间 | 2026-08-24 |
| 当前上游规划基线 | `basecamp/omarchy` 的 `quattro` 分支，仓库版本文件为 `4.0.0.alpha` |
| 目标架构 | x86_64、UEFI、Wayland |
| 建议代码许可证 | MIT；保留 Omarchy 原始版权与许可证声明 |
| 建议文档许可证 | CC BY-SA 4.0 |
| 品牌状态 | `OmarchyCN` 作为工作名称，发布前完成名称与商标审查 |


---

## 目录

1. 产品摘要
2. 背景与机会
3. 产品愿景
4. 产品目标
5. 用户画像
6. 核心用户场景
7. 产品原则
8. 成功指标
9. 发布形态与版本策略
10. 功能需求
11. 信息架构与交互设计
12. 系统架构
13. Tech Stack
14. AI Adapter 技术设计
15. 软件供应链与安全
16. 性能与可靠性要求
17. 硬件与兼容测试矩阵
18. 可访问性与本地化质量
19. 文档需求
20. 开源、许可证与品牌
21. CI/CD Pipeline
22. 里程碑
23. 风险与缓解措施
24. Definition of Done
25. 首版命令清单
26. 待确认产品决策
27. 官方事实基线与参考资料
28. 最终产品定义

---

## 1. 产品摘要

OmarchyCN 是面向中国大陆开发者、AI 工程师、独立开发者与技术团队的 Omarchy 下游发行版。产品完整保留 Omarchy 的 Arch Linux、Hyprland、Quickshell、快捷键、主题、应用管理与 AI Agent 桌面体验，并增加中国网络环境、中文输入、中文字体、国内应用与中国 AI 服务的系统级支持。

产品包含两种交付形态：

1. **OmarchyCN ISO**：用于全新安装，包含可离线安装的核心系统、国内镜像预检、中文环境、输入法与 OmarchyCN 初始配置。
2. **OmarchyCN Overlay**：用于现有 Omarchy，安装后将中国镜像、中文输入、AI Hub、国内应用入口与 OmarchyCN 更新通道叠加到现有系统。

OmarchyCN 采用薄下游策略。上游系统行为持续由 Omarchy 提供，中国市场特性集中在独立目录、独立软件包、独立配置层和独立迁移中。该策略用于降低上游同步成本、缩小冲突面，并支持将通用改进回馈给 Omarchy 上游。

---

## 2. 背景与机会

Omarchy 已经提供完整的 opinionated Linux desktop，并将 AI coding agents、系统 CLI、Quickshell 桌面和系统配置整合为一套统一体验。当前上游已经具备以下可复用能力：

- `omarchy` CLI 与 `Super + Space` 系统菜单。
- 基于 `mise` 的 AI coding agent lazy launcher。
- Claude Code、Codex、OpenCode、Pi、Crush、Ori 等 Agent 入口。
- Fcitx5、Fcitx5 GTK、Fcitx5 Qt 的基础运行环境。
- 基于 Bash 5 的安装、迁移、配置与命令体系。
- 基于 Quickshell/QML 的桌面 Shell。
- Arch ISO、pacstrap、pacman、AUR 与 Omarchy 自有软件包能力。

中国大陆用户仍需要自行处理以下链路：

- Arch、AUR、npm、pip、Rust、Go、Maven、Docker 等软件源的选择、测速、故障切换与恢复。
- 中文字体、Fcitx5 引擎、Rime、词库、Electron/GTK/Qt/Wayland 兼容配置。
- Kimi、DeepSeek、Z.AI/GLM 等模型与 Claude Code、Codex、OpenCode、Kimi Code、Deep Code 等 Harness 的组合配置。
- 微信、QQ、飞书、钉钉、腾讯会议、WPS 等国内应用的安装来源、桌面文件、图标与更新。
- 国内网络环境下的安装诊断、下载失败恢复与日志采集。

OmarchyCN 将这些分散操作收敛为系统级默认能力，让用户在首次启动后直接进入中文可用、网络可用、AI 可用的开发环境。

---

## 3. 产品愿景

让中国开发者通过一次安装，获得一套完整、漂亮、稳定、可持续更新的 AI 原生 Linux 工作站。

### 3.1 产品定位

**OmarchyCN = Omarchy Desktop Experience + China Network Layer + Chinese UX + China AI Stack。**

### 3.2 核心价值

- **安装即用**：首次进入桌面即可输入中文、安装软件、调用国内 AI 服务。
- **统一配置**：镜像、输入法、AI Provider、Harness、应用和诊断集中在同一 CLI 与菜单中。
- **可逆变更**：每次系统级配置变更均生成备份、变更记录和恢复入口。
- **持续同步**：上游更新通过自动化兼容测试进入 OmarchyCN 发布通道。
- **透明可信**：软件来源、签名、许可证、构建产物和配置变化均可审计。

---

## 4. 产品目标

### 4.1 v1.0 目标

1. 在中国大陆常见家庭与办公网络中完成 OmarchyCN ISO 安装和首次更新。
2. 首次启动后直接提供可用的简体中文界面、中文字体与中文输入。
3. 通过一个向导完成 Harness、Provider、模型与 API 凭据配置。
4. 支持 Kimi、DeepSeek、Z.AI/GLM 作为一等 AI Provider。
5. 支持 Kimi Code、Deep Code、Claude Code、Codex、OpenCode 作为一等 AI Harness。
6. 提供国内常用通信、办公、云盘与开发应用的可信安装入口。
7. 在 Omarchy 上游发布后，通过自动化同步、测试和迁移发布兼容版本。
8. 提供 ISO、软件包、更新清单、SBOM、校验和与签名。

### 4.2 范围边界

- v1.0 聚焦 x86_64 UEFI 设备。
- v1.0 聚焦桌面与笔记本开发工作站。
- ARM64、服务器版、企业集中管理版进入后续版本规划。
- OmarchyCN 负责中国环境集成层；Linux 内核、Arch 基础仓库、Hyprland 与主要桌面组件持续跟随上游。
- 专有软件通过用户主动选择，从厂商官方来源、受信任软件仓库或经过审查的安装配方获取。
- AI 服务费用、账户、额度和服务可用性由对应 Provider 管理。

---

## 5. 用户画像

### 5.1 AI 原生开发者

- 日常使用 Claude Code、Codex、OpenCode、Kimi Code 或其他 Agent。
- 希望在 Kimi、DeepSeek、GLM、OpenAI、Anthropic 等模型之间切换。
- 需要统一管理 API Endpoint、模型名、凭据、MCP 和 Skills。

### 5.2 Arch/Omarchy 爱好者

- 喜欢 Hyprland、键盘驱动工作流和精简桌面。
- 希望减少安装后的中文化与国内网络配置工作。
- 关注上游兼容、配置透明和可回滚性。

### 5.3 独立开发者与学生

- 使用中国大陆网络和国内支付方式购买 AI 服务。
- 需要低成本模型与开箱即用的开发工具。
- 希望通过一个系统完成编程、沟通、文档、设计和 AI 协作。

### 5.4 工程团队

- 希望形成统一的 Linux 开发环境。
- 需要可复现安装、团队镜像、统一 AI 配置模板与诊断包。
- 需要通过无人值守方式部署多台工作站。

---

## 6. 核心用户场景

### 场景 A：全新安装

1. 用户从官网下载 ISO 与签名文件。
2. 安装器检测硬件、网络、磁盘和可用镜像。
3. 用户选择语言、时区、键盘、输入法方案、镜像策略和磁盘方案。
4. 安装器从 ISO 内置仓库安装核心系统，并从最佳镜像补充在线包。
5. 首次启动向导完成显示缩放、中文输入、AI Provider 与可选应用配置。
6. 用户进入完整 OmarchyCN 桌面。

### 场景 B：现有 Omarchy 转换

1. 用户运行 Overlay 安装命令。
2. 安装器验证 Omarchy 版本、磁盘空间、网络与系统状态。
3. 系统创建快照和配置备份。
4. 安装 OmarchyCN 软件包、菜单、镜像层、输入法和 AI Hub。
5. 用户通过 `omarchycn doctor` 验证系统。

### 场景 C：配置国内 AI

1. 用户打开 `Super + Space → Setup → OmarchyCN → AI`。
2. 用户选择 Harness，例如 Claude Code。
3. 用户选择 Provider，例如 DeepSeek。
4. 用户选择模型、输入 API Key，并运行连接测试。
5. 系统保存凭据引用，生成 Harness 配置，显示能力与兼容状态。
6. 用户通过默认 Agent 快捷键启动该组合。

### 场景 D：镜像故障恢复

1. pacman、npm 或 pip 下载出现失败。
2. Mirror Agent 检测超时、同步延迟或 TLS 错误。
3. 系统切换至健康镜像，并保留故障记录。
4. 用户可在 Mirror 页面查看当前源、健康度和切换原因。

### 场景 E：团队批量部署

1. 管理员生成无人值守配置文件。
2. 配置文件指定镜像、语言、输入法、应用、AI Harness 和企业内部源。
3. 多台设备使用相同 ISO 与配置完成部署。
4. API Key 通过首次登录、密钥管理器或部署阶段的临时凭据注入。

---

## 7. 产品原则

1. **上游优先**：通用能力优先提交 Omarchy 上游，中国专属能力保留在 OmarchyCN 层。
2. **薄下游**：核心差异集中在 `cn/`、独立软件包、菜单扩展和迁移中。
3. **安全默认**：所有发布包具备签名，凭据通过 Secret Service 或外部密钥管理器保存。
4. **配置可逆**：系统修改前自动备份，所有配置向导提供 Restore 入口。
5. **按需安装**：AI Harness 与专有应用采用 lazy install，减少 ISO 体积与授权风险。
6. **CLI 与 GUI 同构**：菜单中的操作具备对应 CLI，方便自动化与 AI Agent 调用。
7. **国内默认、全球可选**：中国镜像和中文环境作为推荐路径，官方全球源始终可选。
8. **状态透明**：用户能够查看当前版本、上游基线、镜像、包来源、AI 配置和变更历史。

---

## 8. 成功指标

| 指标 | v1.0 目标 |
|---|---:|
| ISO 安装成功率 | 测试矩阵内 ≥ 95% |
| Overlay 转换成功率 | 受支持 Omarchy 版本内 ≥ 97% |
| 首次启动向导完成率 | ≥ 90% |
| 中文输入开箱可用率 | 测试应用矩阵内 ≥ 98% |
| 国内镜像自动选择成功率 | ≥ 95% |
| 镜像故障自动恢复成功率 | ≥ 90% |
| AI 配置连接测试成功率 | 有效账户与凭据条件下 ≥ 95% |
| AI 配置生成准确率 | 稳定兼容矩阵内 100% |
| 上游稳定版本同步目标 | 常规更新 7 天内；关键安全修复 48 小时内 |
| 更新后启动成功率 | ≥ 99% |
| 诊断包敏感信息脱敏率 | 自动化测试覆盖字段 100% |
| 发布包签名覆盖率 | 100% |

---

## 9. 发布形态与版本策略

### 9.1 发布形态

| 形态 | 用途 | 目标用户 |
|---|---|---|
| OmarchyCN ISO | 全新安装 | 新用户、团队统一装机 |
| OmarchyCN Overlay | 现有 Omarchy 增强 | Omarchy 现有用户 |
| OmarchyCN Package Repository | 软件包、配置、迁移与更新 | 全部用户 |
| OmarchyCN Registry | 镜像、应用、AI 兼容矩阵与版本清单 | CLI、菜单、CI |
| OmarchyCN Docs | 中文手册、安装与故障排查 | 用户与贡献者 |

### 9.2 版本格式

```text
<omarchy-upstream-version>-cn.<release>

示例：
4.0.0.alpha-cn.1
4.0.0-cn.1
4.0.1-cn.2
```

### 9.3 发布通道

- `stable`：完成硬件、网络、输入法、AI 与升级测试。
- `beta`：进入候选验证的功能与新 Provider 适配。
- `nightly`：每日上游同步和开发构建。

### 9.4 兼容策略

- 每个 OmarchyCN 版本声明精确的 Omarchy 上游 commit/tag。
- Stable 通道只跟踪上游稳定 tag。
- `quattro` 等开发分支用于 OmarchyCN Preview 与 Nightly。
- Overlay 安装器通过兼容矩阵决定直接安装、先更新或进入人工迁移路径。

---

## 10. 功能需求

## 10.1 发行与安装系统

### FR-DIST-001：OmarchyCN ISO

**优先级：P0**

需求：

- 基于 Arch ISO 与 Omarchy 安装体系构建。
- ISO 内置核心系统离线仓库，支持核心桌面在弱网环境下完成安装。
- 支持 UEFI 启动、图形安装与日志控制台。
- 支持整盘安装、手动分区与双启动引导路径。
- 支持可选 LUKS2 全盘加密。
- 安装前检测 CPU、GPU、网络、磁盘、UEFI、时钟和分辨率。
- 根据 Intel、AMD、NVIDIA 硬件选择对应驱动路径。
- 生成安装报告，并对用户名、设备名、网络信息和磁盘标识做脱敏。

验收标准：

- Intel 核显、AMD 核显/独显、NVIDIA 独显测试机均能进入桌面。
- 无网络条件下可完成核心系统安装。
- 联网条件下可自动选择健康镜像并补充更新。
- 安装失败后可从 Live 环境导出脱敏日志。

### FR-DIST-002：Overlay Installer

**优先级：P0**

需求：

- 支持从受支持的 Omarchy 版本安装 OmarchyCN。
- 安装前运行版本、磁盘、网络、包冲突和配置冲突检查。
- 安装前创建 Btrfs/Snapper 快照；其他文件系统创建配置级备份。
- Overlay 包含 OmarchyCN CLI、菜单扩展、镜像管理、输入法、AI Hub、国内应用目录和文档。
- 安装过程幂等，多次运行得到一致状态。
- 支持 `omarchycn uninstall overlay` 恢复 Omarchy 默认配置和软件源。

验收标准：

- 受支持 Omarchy 测试镜像可完成安装、重启、更新与卸载。
- 用户现有 dotfiles、主题与自定义快捷键获得保留或生成冲突报告。
- 安装失败时自动恢复关键配置。

### FR-DIST-003：首次启动向导

**优先级：P0**

向导步骤：

1. 语言与地区。
2. 时区与键盘布局。
3. 显示缩放与多显示器。
4. 中文输入方案。
5. Arch 与开发工具镜像策略。
6. AI Harness 与 Provider。
7. 可选国内应用。
8. 隐私与诊断选项。
9. 最终系统检查。

要求：

- 支持跳过单个步骤并在系统菜单中重新进入。
- 所有配置同时具备 CLI 参数。
- 向导状态保存在本地，支持中断后继续。

---

## 10.2 中国网络与镜像管理

### FR-MIRROR-001：Arch Mirror Manager

**优先级：P0**

需求：

- 从 Arch 官方镜像数据库与 OmarchyCN 签名 Registry 获取候选列表。
- 对镜像执行 DNS、TLS、首字节、下载吞吐、同步新鲜度和错误率检测。
- 自动选择一个主镜像和至少两个备用镜像。
- 支持中国优先、全球官方、固定镜像、自定义镜像四种策略。
- 生成 `/etc/pacman.d/mirrorlist` 前保存带时间戳备份。
- 更新后持续保留用户策略。
- 镜像连续失败时自动切换并发出桌面通知。

CLI：

```bash
omarchycn mirror status
omarchycn mirror benchmark
omarchycn mirror apply china
omarchycn mirror apply official
omarchycn mirror pin <mirror-id>
omarchycn mirror restore
```

验收标准：

- 镜像测速结果包含延迟、吞吐、同步状态与证书状态。
- 当前镜像失效后自动切换至备用镜像。
- Registry 不可用时使用 ISO/软件包内置候选与 Arch 官方列表。

### FR-MIRROR-002：OmarchyCN 软件仓库

**优先级：P0**

需求：

- 提供 `[omarchycn]` pacman repository。
- 软件包由 OmarchyCN 发布密钥签名。
- Repository Database 具备签名与版本清单。
- 支持主站、国内镜像和全球镜像切换。
- Keyring 通过独立 `omarchycn-keyring` 包分发。
- Mirror Registry 记录镜像运营方、地区、同步状态、证书和最后验证时间。

建议配置：

```ini
[omarchycn]
SigLevel = Required DatabaseOptional
Include = /etc/pacman.d/omarchycn-mirrorlist
```

### FR-MIRROR-003：开发工具镜像配置

**优先级：P0**

覆盖范围：

- Node.js：npm、pnpm、Yarn、Bun。
- Python：pip、uv、Poetry。
- Rust：rustup、Cargo、Crates index。
- Go：GOPROXY、checksum database 策略。
- JVM：Maven、Gradle。
- Ruby：RubyGems、Bundler。
- Containers：Docker/OCI registry mirror。
- Git：Git LFS、可选 URL rewrite。

要求：

- 每个生态支持 `official`、`china`、`custom` profile。
- 修改前识别现有用户配置并创建备份。
- 使用用户级配置作为默认写入范围。
- 提供单项应用和批量应用。
- 镜像地址由签名 Registry 维护，支持无系统发版更新。

CLI：

```bash
omarchycn dev-mirror list
omarchycn dev-mirror apply china
omarchycn dev-mirror apply official --target npm,pip,cargo
omarchycn dev-mirror set custom --target npm --url <url>
omarchycn dev-mirror doctor
```

### FR-MIRROR-004：代理与企业网络配置

**优先级：P1**

需求：

- 支持 HTTP、HTTPS、SOCKS5 和 PAC 配置。
- 支持终端、Git、pacman、Docker 与 systemd user service 的统一代理配置。
- 支持企业 CA 导入与证书链诊断。
- 所有代理配置均由用户主动启用。
- 诊断包对用户名、代理凭据、内部域名和 IP 做脱敏。

---

## 10.3 中文环境

### FR-I18N-001：语言与 Locale

**优先级：P0**

需求：

- 预生成 `zh_CN.UTF-8` 与 `en_US.UTF-8`。
- 首次启动支持简体中文、English 与双语配置。
- 默认中文地区配置使用 `Asia/Shanghai`，同时允许选择其他时区。
- 系统菜单、OmarchyCN CLI、通知和文档提供简体中文。
- CLI 支持 `LANG` 自动选择和 `--lang zh-CN|en-US` 显式覆盖。

### FR-I18N-002：中文字体

**优先级：P0**

默认字体集合：

- Noto Sans CJK SC / 思源黑体。
- Noto Serif CJK SC / 思源宋体。
- Noto Color Emoji。
- 等宽字体采用具备中英文宽度一致性的方案，提供 Sarasa Mono SC 作为推荐选项。

要求：

- 提供 Fontconfig 优先级文件。
- 避免中文 fallback 到日文字形。
- 终端、浏览器、Electron、GTK、Qt、PDF 和代码编辑器使用一致的中文 fallback。
- 字体设置通过 `omarchycn font` 和 OmarchyCN 菜单管理。

### FR-I18N-003：高分屏与显示

**优先级：P0**

需求：

- 首次启动检测显示器物理尺寸、分辨率与 DPI。
- 提供 1.0、1.25、1.5、1.6、1.75、2.0 缩放预设。
- 支持 5K2K、4K、超宽屏和多显示器组合。
- Electron/XWayland 应用执行清晰度检查并给出推荐环境变量。
- 显示配置变更具备 15 秒自动恢复确认机制。

---

## 10.4 中文输入法

### FR-IME-001：Fcitx5 开箱配置

**优先级：P0**

默认组件：

- `fcitx5`
- `fcitx5-gtk`
- `fcitx5-qt`
- `fcitx5-configtool`
- `fcitx5-rime`
- `fcitx5-chinese-addons`

需求：

- 自动配置 Wayland、GTK、Qt、Electron 和 XWayland 环境。
- 默认提供 Rime 拼音与 Chinese Addons 拼音路径。
- 用户可在首次启动中选择默认引擎。
- 用户词典与配置保存在 XDG 目录并参与备份。
- 提供输入法状态栏图标、当前模式和快速设置入口。

### FR-IME-002：快捷键冲突处理

**优先级：P0**

Omarchy 使用 `Super + Space` 打开系统菜单。OmarchyCN 默认采用以下策略：

- 推荐输入法切换：`Ctrl + Space`。
- 可选输入法切换：`Super + Space`。
- 用户选择 `Super + Space` 时，系统自动将 Omarchy 菜单迁移到 `Super + Alt + Space`，并展示变更说明。
- 快捷键向导自动检测现有 Hyprland 与 Fcitx5 冲突。

### FR-IME-003：输入法兼容测试

**优先级：P0**

测试应用：

- Chromium/Chrome。
- Firefox 系浏览器。
- Zed、VS Code、JetBrains IDE。
- Terminal、Neovim。
- WeChat、QQ、Feishu/Lark、DingTalk。
- WPS、LibreOffice。
- Electron、GTK4、Qt6 示例应用。

验收标准：

- 中文候选框位置正确。
- 中英文切换状态与面板状态一致。
- 多显示器与分数缩放下候选框清晰可见。
- 重启会话后输入法配置持续生效。

---

## 10.5 OmarchyCN AI Hub

### 10.5.1 核心模型

AI Hub 将 **Harness** 与 **Provider/Model** 作为两层独立对象管理。

```text
Harness
├── Kimi Code
├── Deep Code
├── Claude Code
├── Codex
├── OpenCode
├── Pi
├── Crush
├── Ori
└── DeepSeek Harness（Preview Channel）

Provider / Model
├── Kimi
├── DeepSeek
├── Z.AI / GLM
├── Qwen / DashScope
├── OpenAI
├── Anthropic
├── Google
├── OpenRouter
├── Local OpenAI-compatible Endpoint
└── Local Anthropic-compatible Endpoint
```

每个 Harness × Provider 组合具备兼容等级：

- `stable`：进入自动化回归测试，可在 Stable 通道展示。
- `beta`：完成基础功能验证，在 Beta 与显式开启实验功能时展示。
- `experimental`：配置模板可用，接口或 Harness 行为仍在变化。
- `unsupported`：Registry 标记原因，界面隐藏或显示明确说明。

### FR-AI-001：AI Setup Wizard

**优先级：P0**

向导步骤：

1. 选择 Harness。
2. 选择 Provider。
3. 选择账户类型：订阅登录、API Key、自定义 Endpoint。
4. 选择模型和推理模式。
5. 配置权限模式与项目目录。
6. 配置 Skills 与 MCP Profile。
7. 执行连接、模型、工具调用和流式输出测试。
8. 保存为全局或项目 Profile。

CLI：

```bash
omarchycn ai setup
omarchycn ai harness list
omarchycn ai provider list
omarchycn ai model list --provider deepseek
omarchycn ai profile list
omarchycn ai profile use <profile>
omarchycn ai test <profile>
omarchycn ai doctor
```

### FR-AI-002：Kimi 集成

**优先级：P0**

需求：

- 提供 Kimi Code lazy launcher。
- 支持 Kimi 官方登录/订阅路径和 API Key 路径。
- 支持将 Kimi 作为 Claude Code、OpenCode 等受支持 Harness 的 Provider。
- Registry 维护 Kimi Endpoint、协议、模型别名与兼容工具。
- Kimi CLI 更新由 `mise` 或官方推荐安装机制管理。
- 配置向导显示官方集成与社区集成标识。

### FR-AI-003：DeepSeek 集成

**优先级：P0**

需求：

- 支持 DeepSeek API 作为 OpenAI-compatible 与 Anthropic-compatible Provider。
- 支持 Claude Code、Codex、OpenCode 的官方集成路径。
- 提供 Deep Code lazy launcher。
- DeepSeek Harness 进入 Preview Channel，并与 Provider 配置分离。
- 支持模型别名、上下文长度、工具调用、推理强度与兼容能力标记。
- 配置测试覆盖普通对话、代码编辑、工具调用与流式输出。

### FR-AI-004：Z.AI / GLM 集成

**优先级：P0**

需求：

- 支持 Z.AI API 与 GLM Coding Plan。
- 支持 Claude Code 与 OpenCode 的官方配置路径。
- 支持 Codex、Pi、Cursor 等 Registry 标记为可用的工具组合。
- 清楚区分 Coding Plan 的适用工具范围和通用 API 计费路径。
- 模型升级通过 Registry 更新，无需系统完整发版。

### FR-AI-005：凭据管理

**优先级：P0**

需求：

- 默认通过 Freedesktop Secret Service 保存 API Key。
- 支持 1Password CLI 作为可选 Secret Backend。
- 支持 `pass` 作为可选本地 Backend。
- 配置文件只保存 Secret Reference。
- 所有日志、诊断、错误提示和导出配置自动脱敏。
- 剪贴板粘贴 API Key 后提供自动清除剪贴板选项。
- 文件回退方案使用 `0600` 权限，并显示安全级别。

### FR-AI-006：AI Profile

**优先级：P0**

Profile 类型：

- Global Profile：全局默认。
- Project Profile：绑定项目目录。
- Temporary Profile：仅当前终端会话。
- Team Profile：可提交到仓库，包含配置模板与 Secret 引用规范。

示例：

```toml
schema_version = 1
name = "claude-deepseek"
harness = "claude-code"
provider = "deepseek"
model = "registry://deepseek/default-coding"
secret_ref = "secret-service://omarchycn/ai/deepseek/default"
scope = "global"
permission_mode = "review"

[capabilities]
tools = true
streaming = true
vision = false

[environment]
# 由 Provider Adapter 生成，文件中不保存明文密钥
```

### FR-AI-007：默认 Agent 与桌面入口

**优先级：P0**

需求：

- 与 Omarchy `omarchy default agent` 机制兼容。
- OmarchyCN Profile 可映射为默认 Agent。
- `Super + Shift + Ctrl + A` 启动默认 Profile。
- Top Bar AI 面板展示当前 Harness、Provider、模型、连接状态和本地使用量。
- Provider 公开额度接口时展示余额或配额；数据来源在 UI 中明确标识。

### FR-AI-008：Skills 与 MCP

**优先级：P1**

需求：

- 提供 OmarchyCN 系统维护 Skill。
- 将 Skill 链接到 Claude Code、Codex、Pi、OpenCode 与通用 `~/.agents/skills`。
- 提供 MCP Profile 管理，支持全局、项目和临时启用。
- 安装 MCP Server 前展示来源、权限、命令、网络访问和文件访问范围。
- 支持导出可提交仓库的 MCP 模板，密钥使用 Secret Reference。

### FR-AI-009：AI Doctor

**优先级：P0**

检查项：

- Harness 是否安装、版本和更新渠道。
- Provider Endpoint DNS、TLS、鉴权和模型可用性。
- 模型能力与 Harness 需求是否匹配。
- 配置文件权限与 Secret Backend。
- 项目目录权限、Git 状态与工具依赖。
- MCP Server 可执行文件、权限和连接状态。
- 输出可分享的脱敏诊断报告。

---

## 10.6 国内应用中心

### FR-APP-001：应用目录

**优先级：P0**

建议首批应用：

| 分类 | 应用 |
|---|---|
| 沟通 | 微信、QQ、飞书/Lark、钉钉、腾讯会议、Discord |
| 办公 | WPS Office、腾讯文档 Web App、石墨文档 Web App |
| 云盘 | 百度网盘、阿里云盘、坚果云 |
| 开发 | Chrome、Zed、VS Code、JetBrains Toolbox、Android Studio、Figma Web/Desktop 可用路径 |
| 知识管理 | Obsidian、Notion Web App、语雀 Web App |
| 密钥管理 | 1Password、Bitwarden |
| AI | Kimi、DeepSeek、Z.AI、ChatGPT 等 Web App 或官方客户端入口 |

要求：

- 每个应用记录来源类型：Official Package、Official Download、AUR、Flatpak、Web App。
- 每个应用记录许可证、支持架构、安装命令、校验方式、更新方式和已知问题。
- 专有软件安装前展示来源与许可证确认。
- 安装失败时提供替代来源和诊断信息。
- 应用安装配方由签名 Registry 管理。

### FR-APP-002：图标与桌面一致性

**优先级：P1**

需求：

- Papirus 作为国内应用推荐图标体系。
- 存在官方 Papirus 图标时直接映射。
- 缺少图标时使用最接近的 Papirus 图标或 OmarchyCN 独立补充图标。
- 每个安装配方声明 Desktop Entry、StartupWMClass、Wayland 参数与图标映射。
- 应用菜单内禁止出现重复入口、空白图标和失效 Desktop Entry。

### FR-APP-003：应用更新

**优先级：P1**

需求：

- pacman/AUR/Flatpak 应用沿用对应更新机制。
- Official Download 配方通过版本 Registry 和校验和更新。
- Web App 通过统一的 PWA/Web App 管理器创建和移除。
- 更新前显示来源变更、许可证变更和签名状态。

---

## 10.7 系统更新、迁移与恢复

### FR-UPDATE-001：统一更新

**优先级：P0**

```bash
omarchycn update
```

执行顺序：

1. 检查磁盘空间、网络、镜像和系统时间。
2. 获取 OmarchyCN 签名 Release Manifest。
3. 创建系统快照或配置备份。
4. 更新 Arch 与 Omarchy 上游组件。
5. 更新 OmarchyCN 软件包。
6. 执行版本迁移。
7. 运行关键健康检查。
8. 生成更新报告。

要求：

- 更新流程支持恢复点。
- 更新锁防止并发 pacman 与 Overlay 更新。
- 迁移脚本具备版本号、前置条件、幂等性和回滚动作。
- 更新后检测登录管理器、Quickshell、Hyprland、网络、Fcitx5 和默认 Agent。

### FR-UPDATE-002：上游同步

**优先级：P0**

需求：

- CI 定期获取 `basecamp/omarchy` 上游变更。
- 自动生成 Sync Merge Request，包含改动范围、冲突、包变更、配置变更和测试结果。
- 上游目录修改控制在最小范围。
- 通用修复通过独立 PR 回馈上游。
- 每个 OmarchyCN Release Manifest 记录上游 commit SHA。

### FR-UPDATE-003：恢复与重装

**优先级：P0**

CLI：

```bash
omarchycn restore list
omarchycn restore config <snapshot>
omarchycn restore system <snapshot>
omarchycn reinstall mirrors
omarchycn reinstall ime
omarchycn reinstall ai
omarchycn reinstall apps
```

要求：

- 配置恢复支持预览差异。
- 系统恢复与 Btrfs/Snapper 集成。
- ext4 等文件系统提供配置与软件包清单恢复。

---

## 10.8 诊断与支持

### FR-DIAG-001：系统 Doctor

**优先级：P0**

```bash
omarchycn doctor
omarchycn doctor network
omarchycn doctor mirror
omarchycn doctor ime
omarchycn doctor ai
omarchycn doctor display
omarchycn doctor apps
```

输出：

- `PASS`：状态正常。
- `WARN`：当前可用，存在推荐调整。
- `FAIL`：功能不可用，提供自动修复或精确命令。
- `INFO`：版本、来源和配置路径。

### FR-DIAG-002：诊断包

**优先级：P0**

诊断包包含：

- OmarchyCN 与 Omarchy 版本。
- 内核、GPU、显示、文件系统和桌面会话信息。
- pacman repo、镜像健康度和软件包状态。
- Fcitx5、字体和 Locale 状态。
- AI Harness 版本、Provider 名称和脱敏配置。
- 相关 systemd journal 摘要。
- 最近迁移、更新和配置变更记录。

安全要求：

- API Key、Token、Cookie、代理凭据、SSH 私钥和密码模式全部过滤。
- 用户目录替换为 `$HOME`。
- 内部域名、IP、SSID 与设备序列号默认脱敏。
- 导出前展示文件清单与敏感信息扫描结果。

---

## 10.9 无人值守安装与团队配置

### FR-TEAM-001：声明式安装配置

**优先级：P1**

示例：

```yaml
schema_version: 1
locale: zh_CN.UTF-8
timezone: Asia/Shanghai
keyboard: us
scale: 1.6
mirror_profile: china-auto
ime:
  framework: fcitx5
  engine: rime
  hotkey: Ctrl+Space
ai:
  harnesses:
    - claude-code
    - kimi-code
    - opencode
  default_profile: claude-deepseek
apps:
  - wechat
  - qq
  - feishu
  - onepassword
  - zed
  - android-studio
security:
  disk_encryption: true
  telemetry: disabled
```

要求：

- Schema 公开并提供 JSON Schema/YAML 校验。
- Secret 通过首次登录、Secret Backend 或一次性环境注入。
- 安装报告包含每个步骤的结果与可重放命令。

---

## 11. 信息架构与交互设计

## 11.1 OmarchyCN 菜单

```text
Super + Space
└── OmarchyCN
    ├── Setup
    │   ├── First Run Wizard
    │   ├── Language & Region
    │   ├── Input Method
    │   ├── Display & Scale
    │   ├── Mirrors
    │   ├── AI Hub
    │   └── Proxy & Certificates
    ├── Install
    │   ├── China Apps
    │   ├── AI Harnesses
    │   ├── Developer Tools
    │   └── Fonts & Input Schemas
    ├── Defaults
    │   ├── AI Profile
    │   ├── Mirror Profile
    │   ├── Input Method
    │   └── Application Defaults
    ├── Diagnostics
    │   ├── System Doctor
    │   ├── Network Doctor
    │   ├── AI Doctor
    │   ├── Input Method Doctor
    │   └── Export Support Bundle
    ├── Update
    │   ├── Check Updates
    │   ├── Change Channel
    │   ├── Release Notes
    │   └── Restore Point
    └── About
        ├── OmarchyCN Version
        ├── Omarchy Upstream Version
        ├── Package Sources
        ├── Licenses
        └── Community
```

## 11.2 交互原则

- 所有危险操作先展示变更预览。
- 所有系统配置页展示当前值、来源、目标值和恢复入口。
- AI 配置页清楚展示 Harness、Provider、Model 三个独立层级。
- 软件安装页清楚展示开源/专有、官方/AUR/Flatpak/Web App 来源。
- 中文术语旁保留关键英文术语，方便搜索上游文档和错误信息。
- 错误页提供复制命令、自动修复和查看日志三条路径。

---

## 12. 系统架构

## 12.1 架构总览

```text
┌─────────────────────────────────────────────────────────────┐
│                     OmarchyCN User Experience               │
│  Quickshell Menu · First Run · AI Panel · Mirror Status     │
└──────────────────────────────┬──────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────┐
│                         CLI Layer                           │
│  omarchycn · omarchy-cn-* wrappers · omarchy integration   │
└──────────────────────────────┬──────────────────────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────┐
│                    OmarchyCN Core Services                  │
│ Mirror Engine · AI Adapter · Registry · Secret · Doctor     │
└───────────────┬──────────────────┬──────────────────────────┘
                │                  │
┌───────────────▼──────────┐  ┌────▼──────────────────────────┐
│ Local System Integration │  │ Signed Remote Distribution    │
│ pacman · Fcitx5 · Hyprland│  │ Package Repo · Registry      │
│ mise · systemd · Snapper │  │ Release Manifest · Docs      │
└───────────────┬──────────┘  └───────────────────────────────┘
                │
┌───────────────▼─────────────────────────────────────────────┐
│ Omarchy Upstream · Arch Linux · Hyprland · Quickshell       │
└─────────────────────────────────────────────────────────────┘
```

## 12.2 薄下游边界

OmarchyCN 改动分为四层：

1. **Overlay Packages**：新增软件包、配置、Registry、图标、文档与命令。
2. **Integration Hooks**：通过 Omarchy CLI、菜单 JSONC、Quickshell plugin、migration hook 接入。
3. **Minimal Upstream Patches**：仅用于缺少扩展点的场景，并持续推动上游接受通用扩展点。
4. **Release Layer**：ISO、仓库、签名、同步、测试与发布基础设施。

目标指标：

- 80% 以上 OmarchyCN 代码位于独立目录或独立软件包。
- 每次上游同步自动统计直接修改上游文件的数量。
- Stable 发版前完成上游差异审查。

## 12.3 建议仓库结构

```text
omarchycn/
├── .forgejo/
│   └── workflows/
├── agents/
│   └── skills/
├── bin/
│   ├── omarchycn
│   └── omarchy-cn-*
├── cn/
│   ├── ai/
│   │   ├── adapters/
│   │   ├── profiles/
│   │   └── registry/
│   ├── apps/
│   ├── branding/
│   ├── fonts/
│   ├── ime/
│   ├── mirrors/
│   ├── shell/
│   └── translations/
├── core/
│   ├── Cargo.toml
│   └── src/
├── config/
├── install/
├── migrations/
├── packages/
│   ├── omarchycn-base/
│   ├── omarchycn-keyring/
│   ├── omarchycn-ai/
│   ├── omarchycn-ime/
│   └── omarchycn-apps/
├── registry/
│   ├── ai.schema.json
│   ├── apps.schema.json
│   └── mirrors.schema.json
├── shell/
│   └── plugins/omarchycn/
├── test/
│   ├── cli/
│   ├── shell/
│   ├── integration/
│   ├── acceptance/
│   └── iso/
├── docs/
├── manual/
├── LICENSE
├── NOTICE
└── PRD.md
```

## 12.4 配置与状态路径

| 类型 | 路径 |
|---|---|
| 系统配置 | `/etc/omarchycn/config.toml` |
| 用户配置 | `~/.config/omarchycn/config.toml` |
| AI Profile | `~/.config/omarchycn/ai/profiles/*.toml` |
| 系统 Registry | `/usr/share/omarchycn/registry/` |
| 远程 Registry 缓存 | `~/.cache/omarchycn/registry/` |
| 用户状态 | `~/.local/state/omarchycn/` |
| 系统缓存 | `/var/cache/omarchycn/` |
| 日志 | systemd journal + `~/.local/state/omarchycn/logs/` |
| 配置备份 | `~/.local/state/omarchycn/backups/` |
| Secret | Freedesktop Secret Service / 1Password / pass |

配置优先级：

```text
CLI 临时参数
    > 项目 Profile
    > 用户配置
    > 系统配置
    > OmarchyCN 默认值
    > Omarchy 上游默认值
```

---

## 13. Tech Stack

## 13.1 基础系统

| 层 | 技术 | 用途与选择理由 |
|---|---|---|
| Base OS | Arch Linux | 与 Omarchy 保持一致，滚动更新，成熟的软件包生态 |
| Upstream Distribution | Omarchy | 提供桌面、快捷键、主题、CLI、安装和 AI Agent 基础能力 |
| Display Protocol | Wayland | Omarchy/Hyprland 原生路径 |
| Window Manager | Hyprland | 动态平铺、动画、输入与显示配置 |
| Session | UWSM + systemd user session | 保持 Omarchy 运行环境与环境变量模型 |
| Desktop Shell | Quickshell | 菜单、Top Bar、AI Panel、镜像状态、首次启动 UI |
| Shell UI Language | QML + JavaScript | 与 Omarchy Quickshell 代码保持一致 |
| Hyprland Config | Lua | 跟随 Omarchy 当前配置结构 |
| Audio | PipeWire/WirePlumber | Linux 桌面统一音频路径 |
| Networking | NetworkManager | Wi-Fi、有线、VPN 与系统网络管理 |
| Input Method | Fcitx5 + Rime + Chinese Addons | 中文输入、Wayland/GTK/Qt/Electron 集成 |
| Filesystem Recovery | Btrfs + Snapper（推荐） | 更新前快照与系统恢复 |

## 13.2 CLI 与系统集成

| 层 | 技术 | 用途与选择理由 |
|---|---|---|
| Upstream-compatible Scripts | Bash 5 | 与 Omarchy `bin/`、`install/`、`migrations/` 约定一致 |
| OmarchyCN Core CLI | Rust 2024 Edition | 镜像并发测速、Registry 校验、AI Adapter、Secret 与诊断的类型安全实现 |
| CLI Framework | `clap` | 命令、子命令、补全与帮助生成 |
| Async Runtime | `tokio` | 并发网络探测、下载、Provider 测试 |
| HTTP/TLS | `reqwest` + rustls | Registry、镜像与 Provider 连接测试 |
| Serialization | `serde`, `serde_json`, `toml`, `serde_yaml` | 配置、Registry、无人值守文件 |
| Error Handling | `thiserror`, `anyhow` | 用户可读错误与内部错误链 |
| Logging | `tracing`, `tracing-subscriber` | 结构化日志、脱敏和诊断包 |
| Secret Integration | `keyring` / Secret Service D-Bus | API Key 安全存储 |
| D-Bus | `zbus` | Quickshell、通知、Secret Service 与桌面服务集成 |
| Signature Verification | `sequoia-openpgp` 或系统 `gpgv` | Release Manifest 与 Registry 验证 |

实现约束：

- Bash wrapper 使用 `omarchy-cn-*` 前缀，并遵循 Omarchy 的命令元数据与帮助规范。
- Rust Core 提供稳定 JSON 输出，供 Quickshell、Bash 与自动化调用。
- Root 权限仅覆盖 pacman、系统源、系统字体与系统配置写入。
- 用户配置与 AI Profile 使用普通用户权限完成。

## 13.3 软件包与 ISO

| 层 | 技术 | 用途 |
|---|---|---|
| Package Manager | pacman | 系统软件包管理 |
| Package Build | PKGBUILD + `makepkg` | OmarchyCN 包构建 |
| Clean Build | `devtools`/clean chroot | 可复现、隔离的 Arch 包构建 |
| Repository | `repo-add` + PGP signing | `[omarchycn]` 仓库与数据库 |
| ISO | `archiso` | OmarchyCN 安装镜像 |
| AUR | `paru`/Omarchy package helpers | 可选社区包安装 |
| Lazy Tool Runtime | `mise` | AI Harness 与开发工具按需安装 |
| Web Apps | Omarchy Web App mechanism | 国内 Web App/PWA 桌面入口 |

## 13.4 配置与 Registry

| 类型 | 格式 |
|---|---|
| 用户与系统配置 | TOML |
| 菜单定义 | JSONC |
| Remote Registry | JSON + JSON Schema |
| 无人值守安装 | YAML |
| 版本与发布清单 | JSON，带签名 |
| 翻译 | JSON/Qt Linguist compatible catalog，构建阶段生成 QML/Bash 可用资源 |
| 文档 | Markdown |

Registry 类型：

- `mirrors.json`：Arch、OmarchyCN 与开发工具镜像。
- `apps.json`：应用来源、安装器、版本、校验和、许可证和图标。
- `ai-providers.json`：Provider Endpoint、协议和模型元数据。
- `ai-harnesses.json`：Harness 安装方式、版本检测与配置适配器。
- `ai-compatibility.json`：Harness × Provider × Model 兼容矩阵。
- `release.json`：上游 commit、OmarchyCN 版本、包版本、迁移与最低兼容版本。

## 13.5 CI/CD 与发布基础设施

| 层 | 建议技术 | 用途 |
|---|---|---|
| Canonical Git Forge | 自托 Gitea/Forgejo | 源码、Issue、MR、Release 与独立控制 |
| Public Mirrors | GitHub、GitLab | 社区发现、贡献与冗余镜像 |
| CI | Gitea Actions / Forgejo Actions | 构建、测试、同步与发布 |
| Runners | 自托 x86_64 Linux runners | Arch 包、ISO 与 VM 测试 |
| Artifact Storage | RustFS S3-compatible storage | ISO、软件包、SBOM、日志与构建缓存 |
| Static Repository | Nginx/Caddy + object storage sync | pacman repository 与 Registry |
| Domestic Distribution | 国内对象存储/CDN 或社区镜像 | 中国大陆下载加速 |
| Docs | VitePress | 中文优先文档站 |
| Website | VitePress/Astro | 下载、版本、镜像状态与项目介绍 |
| Release Signing | Offline PGP master key + online release subkey | 包、数据库和发布清单签名 |
| ISO Signing | minisign 或 PGP detached signature | ISO 与 checksum 验证 |
| SBOM | Syft | ISO 与包级软件物料清单 |
| Vulnerability Scan | Grype/Trivy | 依赖与镜像扫描 |
| Provenance | cosign + SLSA-compatible attestations | 构建来源证明 |

## 13.6 测试栈

| 类型 | 技术 |
|---|---|
| Bash 静态检查 | ShellCheck |
| Bash 单元/集成测试 | Omarchy 原生 test runner + Bats-core（OmarchyCN 独立模块） |
| Rust 测试 | `cargo test`, `cargo nextest`, `clippy`, `rustfmt` |
| Schema 测试 | JSON Schema validator + golden fixtures |
| Quickshell 测试 | 上游 Shell test pattern + QML lint + Node helper tests |
| 系统集成测试 | systemd-nspawn/Arch clean chroot |
| 图形验收 | QEMU/KVM disposable VM + 自动截图与交互脚本 |
| ISO 启动测试 | QEMU UEFI + serial log + cloud-init-like test seed |
| 网络故障测试 | Toxiproxy/netem/DNS failure fixtures |
| 安全测试 | Secret scanning、dependency audit、SBOM diff |

---

## 14. AI Adapter 技术设计

## 14.1 Adapter 接口

每个 Harness Adapter 实现：

```text
install()
detect_version()
auth_methods()
read_config()
plan_config_change()
apply_config()
validate_provider()
validate_model()
launch()
collect_usage()
redact_diagnostics()
uninstall()
```

每个 Provider Adapter 实现：

```text
endpoint_schema()
auth_schema()
list_models()
resolve_model_alias()
capabilities()
health_check()
pricing_metadata()
quota_metadata()
render_environment(harness)
render_config(harness)
```

## 14.2 配置生成原则

- Adapter 读取 Harness 当前版本后选择对应模板。
- 配置写入前生成 diff 和备份。
- API Key 只在进程启动阶段从 Secret Backend 注入。
- 支持环境变量、配置文件和 Wrapper Script 三种输出方式。
- 每个组合记录最后成功测试时间、Harness 版本、Provider API 版本和模型。
- Registry 过期时保留最后验证通过的配置模板，并显示时间戳。

## 14.3 Provider Manifest 示例

```json
{
  "$schema": "https://example.invalid/schemas/ai-provider.schema.json",
  "id": "deepseek",
  "display_name": "DeepSeek",
  "protocols": ["openai", "anthropic", "responses"],
  "auth": ["api_key"],
  "endpoints": {
    "openai": "registry-value",
    "anthropic": "registry-value"
  },
  "models": [
    {
      "id": "registry-model-id",
      "aliases": ["default-coding"],
      "capabilities": ["tools", "streaming", "reasoning"]
    }
  ]
}
```

生产 Registry 使用真实 Endpoint，示例文档使用占位值，避免文档与服务变更耦合。

---

## 15. 软件供应链与安全

### 15.1 发布安全

- 所有 pacman 包与数据库使用 OmarchyCN PGP Key 签名。
- Release Manifest、Registry 和镜像清单均验证签名。
- Master Key 离线保存，Release Subkey 定期轮换。
- 每个 Release 发布 SHA-256 checksum、签名、SBOM 与 provenance。
- 构建环境使用 clean chroot 或一次性 VM。
- Release Job 只从受保护 tag 启动。

### 15.2 应用来源安全

- Official Package 优先级最高。
- Official Download 配方必须验证 TLS、发布者和 checksum/signature。
- AUR 配方在安装前展示 PKGBUILD 来源、维护者、最后更新时间与风险标识。
- 专有软件二进制遵循厂商再分发条款；需要用户下载安装的包采用 fetch-on-install。
- Registry 变更经过代码审查、自动测试和签名发布。

### 15.3 凭据安全

- API Key、Token 和密码禁止进入 Git、日志、诊断包与 Release Artifact。
- Secret Backend 返回的 Secret 只存在于目标进程环境或受控临时文件。
- 临时文件使用 `0600`、短生命周期和退出清理。
- `omarchycn ai export` 默认导出脱敏模板。
- Agent unattended/auto-approve 模式显示显著风险提示，并允许按 Profile 配置。

### 15.4 权限模型

- 包管理、系统源和系统配置通过 `sudo`/`pkexec`。
- 用户配置、AI Profile、镜像测速和应用目录查询使用普通用户权限。
- Quickshell UI 通过受控 CLI 调用特权操作。
- 每个命令声明权限需求和变更范围。

### 15.5 隐私

- v1.0 默认关闭遥测。
- 更新检查只请求版本与架构所需信息。
- 用户主动提交诊断包前可预览内容。
- 未来匿名统计采用显式 Opt-in，并公开事件 Schema 与数据保留策略。

---

## 16. 性能与可靠性要求

| 项目 | 要求 |
|---|---|
| CLI 启动 | 常用只读命令 P95 < 150 ms |
| 菜单打开 | P95 < 300 ms |
| Mirror Status 缓存读取 | P95 < 100 ms |
| 镜像完整测速 | 默认并发执行，目标 30 秒内返回可用结果 |
| AI Profile 切换 | P95 < 1 秒，不含 Harness 下载与 Provider 网络延迟 |
| First Run 状态恢复 | 崩溃或注销后继续上次未完成步骤 |
| Registry 故障 | 使用最后一个有效签名缓存 |
| 更新中断 | 保留恢复点与可重放步骤 |
| 配置写入 | 原子写入、fsync、备份与权限校验 |
| 日志空间 | 默认轮转与上限控制 |

---

## 17. 硬件与兼容测试矩阵

### 17.1 P0 硬件

| 类别 | 覆盖 |
|---|---|
| CPU | Intel x86_64、AMD x86_64 |
| GPU | Intel iGPU、AMD Radeon、NVIDIA RTX |
| 显示 | 1080p、1440p、4K、5K2K、单屏、双屏 |
| 缩放 | 1.0、1.25、1.5、1.6、2.0 |
| 设备 | 台式机、主流笔记本、外接扩展坞 |
| 网络 | 有线、Wi-Fi、热点、企业代理 |
| 文件系统 | Btrfs、ext4 |
| 安装 | 整盘、手动分区、Windows 双启动 |

### 17.2 P1 硬件

- 高刷新率与 VRR。
- 混合显卡笔记本。
- Thunderbolt/USB-C 多显示器。
- 指纹与 FIDO2。
- 触控板手势与高 DPI 鼠标。

### 17.3 网络测试

- 中国电信、中国联通、中国移动代表性网络。
- DNS 污染、DNS 超时、IPv6-only/dual-stack、TLS 握手失败。
- 高延迟、丢包、限速与镜像同步滞后。
- 企业代理、自签名 CA 与内部镜像。

---

## 18. 可访问性与本地化质量

- 中文 UI 使用统一术语表。
- 核心错误同时提供中文解释与原始英文错误。
- 键盘操作覆盖全部 OmarchyCN 菜单。
- 状态依赖文字、图标和形状共同表达。
- 支持系统字体缩放与高对比度主题。
- 文档示例同时覆盖中文目录、带空格目录和英文目录。
- 中文标点、CJK 行高、终端等宽和候选框在分数缩放下进入视觉回归测试。

---

## 19. 文档需求

### 19.1 用户文档

- 下载与签名验证。
- ISO 安装。
- 从 Omarchy 安装 Overlay。
- 首次启动向导。
- 中文输入与快捷键。
- 国内镜像与开发工具镜像。
- Kimi、DeepSeek、Z.AI/GLM 配置。
- Harness 与 Provider 概念。
- 国内应用安装。
- 更新、快照与恢复。
- 常见硬件问题。
- 诊断包与 Issue 模板。

### 19.2 贡献者文档

- 上游同步流程。
- 新增命令。
- 新增 AI Harness Adapter。
- 新增 Provider Adapter。
- 新增镜像与应用配方。
- PKGBUILD 与 clean chroot。
- Quickshell 插件开发。
- 翻译与术语表。
- 测试与 Release Checklist。
- 安全响应与密钥轮换。

---

## 20. 开源、许可证与品牌

### 20.1 代码许可证

- Omarchy 上游代码遵循其 MIT License。
- 所有复制或实质修改的上游文件保留原始版权与许可证声明。
- OmarchyCN 原创代码建议采用 MIT License，以保持与上游一致。
- 第三方组件继续遵循其原始许可证。

### 20.2 品牌

建议公开声明：

> OmarchyCN is an independent community distribution based on Omarchy. OmarchyCN is not affiliated with or endorsed by Basecamp, 37signals, or the Omarchy maintainers.

要求：

- 使用独立 Logo、图标、网站和视觉系统。
- About 页面清楚标注 Omarchy 上游来源。
- 发布前完成 `OmarchyCN` 名称与商标审查。
- 当名称授权存在约束时，项目保留迁移至独立品牌名的能力，代码包名与内部 ID 使用可重命名结构。

### 20.3 专有软件

- ISO 核心层只包含具备再分发权的软件。
- 微信、QQ、WPS、钉钉等软件依据许可采用 fetch-on-install、官方仓库或用户确认路径。
- 应用配方保存来源、hash、许可证提示与更新机制。

---

## 21. CI/CD Pipeline

```text
Upstream Poll
    ↓
Create Sync MR
    ↓
Static Checks
    ├── ShellCheck
    ├── Rust fmt/clippy/test
    ├── QML/JSON/TOML/YAML validation
    └── License/Secret Scan
    ↓
Build Packages in Clean Chroot
    ↓
Build Overlay Test Image
    ↓
VM Integration Tests
    ├── Install
    ├── Upgrade
    ├── IME
    ├── Mirror Failover
    ├── AI Adapter Mock Tests
    └── Rollback
    ↓
Build ISO
    ↓
UEFI Boot Smoke Test
    ↓
Generate SBOM + Provenance
    ↓
Sign Packages/Registry/ISO
    ↓
Publish Beta
    ↓
Manual Hardware Gate
    ↓
Promote Stable
```

### 21.1 发布门禁

Stable 发布必须满足：

- 所有 P0 自动化测试通过。
- ISO 在 Intel、AMD、NVIDIA 代表设备通过启动和安装测试。
- 中文输入应用矩阵通过。
- Kimi、DeepSeek、Z.AI 至少各一个 Stable 组合通过真实账户测试。
- 升级和恢复测试通过。
- 软件包、Registry、ISO、checksum 和 SBOM 全部签名。
- Release Notes 明确上游基线、已知问题和恢复路径。

---

## 22. 里程碑

### M0：项目与法律基础

交付：

- 项目名称、免责声明和视觉方向。
- Canonical Repository、许可证、NOTICE、贡献指南、Code of Conduct、Security Policy。
- 上游 remote、分支策略、同步工作流。
- Release Key 与 Key Rotation 文档。

退出条件：

- 能够自动创建上游同步 MR。
- 能够构建一个未修改功能的 OmarchyCN 基线 ISO。

### M1：Overlay 与国内镜像

交付：

- `omarchycn` CLI 初版。
- Overlay Installer。
- Arch Mirror Manager。
- OmarchyCN Keyring 与 Package Repository。
- npm/pip/Cargo/Go 镜像 Profile。
- System Doctor 与恢复入口。

退出条件：

- 现有 Omarchy 可完成安装、更新和卸载。
- 镜像失效场景通过自动恢复测试。

### M2：中文体验

交付：

- Locale、字体、Fcitx5、Rime、Chinese Addons。
- 快捷键冲突向导。
- 1.6 分数缩放与 5K2K 测试。
- 中文菜单、通知和核心文档。

退出条件：

- 中文输入应用矩阵达到目标通过率。
- 首次启动向导完成中文环境配置。

### M3：AI Hub

交付：

- Harness/Provider/Profile 数据模型。
- Kimi、DeepSeek、Z.AI Adapter。
- Kimi Code、Deep Code、Claude Code、Codex、OpenCode Adapter。
- Secret Backend。
- AI Doctor、兼容矩阵与 Mock Server 测试。
- 默认 Agent 和 Quickshell AI 面板集成。

退出条件：

- 每个国内 Provider 至少一个 Stable Harness 组合。
- Profile 切换、凭据注入、诊断脱敏通过安全测试。

### M4：ISO Alpha 与应用中心

交付：

- OmarchyCN ISO。
- First Run Wizard。
- 国内应用 Registry 与首批配方。
- 签名、SBOM、Release Manifest。
- QEMU UEFI 自动化测试。

退出条件：

- ISO 在 P0 硬件代表设备通过安装。
- Offline Core Install 与 Online Update 均通过。

### M5：v1.0 Stable

交付：

- Stable Channel。
- 中文用户手册与贡献者文档。
- 国内镜像分发。
- 完整 Release Checklist。
- 上游同步 SLA 与安全响应流程。

退出条件：

- 达到第 8 节成功指标。
- 完成一次真实上游版本同步、迁移、Beta 验证和 Stable 晋级。

---

## 23. 风险与缓解措施

| 风险 | 影响 | 缓解措施 |
|---|---|---|
| Omarchy 上游快速变化 | 合并冲突、功能回归 | 薄下游、自动 Sync MR、每日 Nightly、最小上游文件修改 |
| AI Harness 配置频繁变化 | Provider 组合失效 | 签名兼容 Registry、版本检测、Stable/Beta/Experimental 分级 |
| 国内镜像质量波动 | 安装与更新失败 | 多镜像测速、同步新鲜度、自动故障切换、官方源回退 |
| AUR 与第三方二进制供应链 | 安全与稳定风险 | 来源标识、PKGBUILD 审查、校验和、fetch-on-install、默认最小包集 |
| 专有软件再分发限制 | ISO 发布风险 | 核心 ISO 与应用安装配方分离，遵循厂商授权 |
| Omarchy/Arch 名称与商标 | 品牌调整成本 | 独立视觉、免责声明、发布前审查、内部 ID 可重命名 |
| 维护资源不足 | 更新滞后 | P0 范围收敛、自动化测试、社区 Maintainer 分工、Adapter/Registry 模块化 |
| API Key 泄露 | 用户资产与隐私风险 | Secret Service、日志脱敏、文件权限、Secret Scan、诊断包预览 |
| 中国网络差异难以在 CI 复现 | 线上环境回归 | 多 ISP 社区探针、netem 故障测试、镜像状态遥测 Opt-in |
| NVIDIA/混合显卡复杂性 | 黑屏、功耗、外接屏问题 | 跟随上游驱动路径、硬件矩阵、Live Recovery、已知问题数据库 |

---

## 24. Definition of Done

一个功能进入 Stable 的条件：

1. 需求与验收标准完成。
2. CLI 和菜单入口完成。
3. 配置变更具备预览、备份和恢复。
4. 中文与英文文案完成。
5. 单元、集成与适用的 VM/图形测试完成。
6. 权限、Secret、日志和诊断脱敏经过安全审查。
7. 用户文档与故障排查完成。
8. Release Manifest 与兼容 Registry 更新。
9. 上游兼容性评估完成。
10. Stable Channel 发布门禁通过。

---

## 25. 首版命令清单

```text
omarchycn
omarchycn version
omarchycn status
omarchycn setup
omarchycn update
omarchycn doctor [module]
omarchycn mirror <command>
omarchycn dev-mirror <command>
omarchycn ime <command>
omarchycn font <command>
omarchycn display <command>
omarchycn ai <command>
omarchycn app <command>
omarchycn proxy <command>
omarchycn restore <command>
omarchycn reinstall <module>
omarchycn channel <stable|beta|nightly>
omarchycn support bundle
omarchycn config get <key>
omarchycn config set <key> <value>
omarchycn config diff
omarchycn config restore
```

所有命令支持：

```text
--help
--json
--dry-run
--yes
--lang zh-CN|en-US
--verbose
```

涉及系统修改的命令必须支持 `--dry-run`，并在执行前展示目标文件、软件包、服务与恢复点。

---

## 26. 待确认产品决策

| 决策 | 建议默认值 | 发布门槛 |
|---|---|---|
| 项目正式名称 | OmarchyCN | 首个公开 ISO 前完成名称/商标审查 |
| Canonical Forge | 自托 Gitea/Forgejo | M0 |
| 公共镜像 | GitHub + GitLab | M1 |
| 默认中文输入引擎 | Fcitx5 Rime | M2 |
| 默认输入法快捷键 | Ctrl + Space | M2 |
| 默认文件系统 | Btrfs | M4 |
| 默认镜像策略 | China Auto，官方全球源作为备用 | M1 |
| 默认遥测 | Disabled | M0 |
| 原创代码许可证 | MIT | M0 |
| 文档许可证 | CC BY-SA 4.0 | M0 |
| Artifact Origin | RustFS S3-compatible | M1 |
| 国内分发 | 国内对象存储/CDN或社区镜像 | M5 |

---

## 27. 官方事实基线与参考资料

本 PRD 的产品事实基线截至 2026-08-24。实现阶段应持续以官方文档和签名 Registry 为准。

1. Omarchy Repository：<https://github.com/basecamp/omarchy>
2. Omarchy AI Manual：<https://github.com/basecamp/omarchy/blob/quattro/manual/17-ai.md>
3. Omarchy CLI Manual：<https://github.com/basecamp/omarchy/blob/quattro/manual/14-omarchy-cli.md>
4. Omarchy Keyboard/Input Manual：<https://github.com/basecamp/omarchy/blob/quattro/manual/34-keyboard-mouse-trackpad.md>
5. Omarchy License：<https://github.com/basecamp/omarchy/blob/quattro/LICENSE>
6. Arch Linux Mirror Status：<https://archlinux.org/mirrors/status/>
7. Arch Linux Mirrorlist Generator：<https://archlinux.org/mirrorlist/>
8. Kimi Code Docs：<https://www.kimi.com/code/docs/en/>
9. Kimi Claude Code Integration：<https://www.kimi.com/code/docs/en/third-party-tools/claude-code>
10. DeepSeek Coding Agent Integrations：<https://api-docs.deepseek.com/guides/coding_agents/>
11. DeepSeek Claude Code Integration：<https://api-docs.deepseek.com/quick_start/agent_integrations/claude_code/>
12. DeepSeek OpenCode Integration：<https://api-docs.deepseek.com/quick_start/agent_integrations/opencode/>
13. DeepSeek Codex Integration：<https://api-docs.deepseek.com/quick_start/agent_integrations/codex/>
14. Deep Code Integration：<https://api-docs.deepseek.com/quick_start/agent_integrations/deepcode/>
15. Z.AI Coding Plan Overview：<https://docs.z.ai/devpack/overview>
16. Z.AI Claude Code Integration：<https://docs.z.ai/devpack/tool/claude>
17. Z.AI OpenCode Integration：<https://docs.z.ai/scenario-example/develop-tools/opencode>

---

## 28. 最终产品定义

OmarchyCN 是一个保持 Omarchy 核心体验、面向中国开发者环境进行系统级优化的独立社区下游发行版。v1.0 的成立条件包括完整 ISO、可逆 Overlay、中国镜像与故障切换、中文输入与字体、Kimi/DeepSeek/Z.AI AI Hub、国内应用中心、签名软件仓库、自动上游同步、硬件与网络测试矩阵，以及可审计的软件供应链。