From 2c8a68743405ce60ea62fb03b36b9c2a6fecb9b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=9B=B7=E7=94=B5=E8=8A=BD=E8=A1=A3?=
 <zhangyanghaha0407@outlook.com>
Date: Mon, 24 Aug 2026 14:21:55 -0400
Subject: [PATCH] Add OmarchyCN PRD and M0 execution task list

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QKxGW1raAWaqeU8WdHsMsp
---
 OmarchyCN PRD.md   | 1747 ++++++++++++++++++++++++++++++++++++++++++++
 OmarchyCN-TASKS.md |   25 +
 2 files changed, 1772 insertions(+)
 create mode 100644 OmarchyCN PRD.md
 create mode 100644 OmarchyCN-TASKS.md

diff --git a/OmarchyCN PRD.md b/OmarchyCN PRD.md
new file mode 100644
index 00000000..8a8a085f
--- /dev/null
+++ b/OmarchyCN PRD.md	
@@ -0,0 +1,1747 @@
+# 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、国内应用中心、签名软件仓库、自动上游同步、硬件与网络测试矩阵，以及可审计的软件供应链。
diff --git a/OmarchyCN-TASKS.md b/OmarchyCN-TASKS.md
new file mode 100644
index 00000000..501f545c
--- /dev/null
+++ b/OmarchyCN-TASKS.md
@@ -0,0 +1,25 @@
+# OmarchyCN 执行任务清单
+
+进度真相文件。按顺序执行，禁止跳项。每项完成后勾选并记录结果。
+
+范围裁剪（对应 PRD M0 退出条件）：本轮只交付 Canonical Repo + 未修改功能的基线 ISO + Release 发布。
+PRD 中 Overlay、镜像管理、AI Hub、中文环境等功能性章节不在本轮范围（PRD §22 M1–M5）。
+
+- [x] T1 复核 PRD 全文（§1–28），确认本轮交付物 = M0：公开仓库 + 基线 ISO + 签名校验产物
+- [x] T2 探测 git.zacharyzhang.com Gitea API：版本、token 身份、release 附件大小上限
+- [ ] T3 通过 API 创建公开仓库 omarchycn
+- [ ] T4 提交 PRD 与本清单到 quattro 分支，推送全部历史到 Gitea
+- [ ] T5 准备 WSL 构建环境：克隆 omarchy-iso / omarchy-pkgs，按其要求装依赖（Docker 等）
+- [ ] T6 用本地源构建基线 ISO：omarchy-iso-make --local-source
+- [ ] T7 校验 ISO：生成 SHA-256，尽可能做 QEMU UEFI 启动冒烟测试
+- [ ] T8 创建 Gitea Release（tag 4.0.0.alpha-cn.1），上传 ISO 与 checksum
+- [ ] T9 输出最终核对表：仓库 URL、Release URL、逐条验收结果
+
+## 执行记录
+
+（每项完成后在此追加一行：任务号、结果、产物路径/URL）
+
+- T1 完成：PRD §1–28 全文已复核。本轮交付=M0 退出条件（Canonical Repo + 基线 ISO + 校验产物）。
+- T2 完成：Gitea 1.27.1，token=ZacharyZhang-NY(admin)。附件限制 100MB 且不允许 .iso；release asset API 无 external_url。
+  已验证 generic package registry 可上传（201）。策略：ISO 传 generic registry，release 附 sha256(.txt) 与下载链接。
+  如需 ISO 直接作为 release 附件，需管理员改服务器 app.ini 的 [attachment] ALLOWED_TYPES/MAX_SIZE。