Add Chinese user manual (install, mirrors, IME, AI, recovery)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QKxGW1raAWaqeU8WdHsMsp
2026-08-24 22:16:34 -04:00
parent 79d3a65441
commit 708651fa8e
5 changed files with 177 additions and 0 deletions
@@ -0,0 +1,35 @@
+# 安装 OmarchyCN
+
+## 下载与校验
+
+从 [Releases](https://git.zacharyzhang.com/ZacharyZhang-NY/omarchycn/releases) 下载最新 ISO 及 `SHA256SUMS.txt`、`SHA256SUMS.txt.asc`：
+
+```bash
+gpg --import cn/keys/omarchycn-release.asc
+gpg --verify SHA256SUMS.txt.asc SHA256SUMS.txt
+sha256sum -c SHA256SUMS.txt
+```
+
+签名主钥指纹应为 `04490F065F6ADD262A7243506EDF7B8603B5D247`（详见 `docs/release-signing.md`）。
+
+## 写盘与启动
+
+Linux 用 `caligula` 或 `dd`，Mac/Windows 用 balenaEtcher 写入 U 盘，UEFI 模式启动，按提示完成 Omarchy 安装（磁盘、用户、加密等流程与上游一致）。
+
+## 首次进入桌面后
+
+```bash
+omarchycn setup
+```
+
+向导依次配置：语言、时区、显示缩放、中文 locale、中文字体、Fcitx5+Rime 输入法、输入法切换键、pacman 镜像、开发工具镜像、国内应用、AI Hub、隐私说明。每一步都可跳过，中断后重跑会从未完成的步骤继续。
+
+## 现有 Omarchy 叠加安装（Overlay）
+
+```bash
+git clone https://git.zacharyzhang.com/ZacharyZhang-NY/omarchycn.git
+cd omarchycn && ./bin/omarchy-cn-install-overlay
+omarchy cn version   # 验证
+```
+
+卸载：`omarchy-cn-install-overlay --uninstall`。更新：`omarchycn update`。
@@ -0,0 +1,36 @@
+# 镜像管理
+
+## pacman 镜像
+
+```bash
+omarchycn mirror benchmark        # 测速：延迟、吞吐、同步新鲜度
+omarchycn mirror apply china      # 自动选最优中国镜像（1 主 + 2 备）
+omarchycn mirror apply official   # 回到官方全球源
+omarchycn mirror pin tuna         # 固定单一镜像
+omarchycn mirror status           # 当前策略与镜像列表
+omarchycn mirror restore          # 恢复最近一次备份
+```
+
+每次写入 `/etc/pacman.d/mirrorlist` 前自动生成带时间戳备份。候选列表在 `cn/mirrors.json`。
+
+主镜像失效时：
+
+```bash
+omarchycn doctor mirror --fix     # 检测并自动切换到健康镜像
+```
+
+## 开发工具镜像
+
+覆盖 npm、pip、cargo、go、gem、docker 六个生态：
+
+```bash
+omarchycn dev-mirror list                          # 当前各生态源
+omarchycn dev-mirror apply china                   # 全部切国内
+omarchycn dev-mirror apply official --target npm   # 指定生态切官方
+omarchycn dev-mirror set npm https://my.registry/  # 自定义
+omarchycn dev-mirror doctor                        # 连通性检查
+```
+
+写入前备份到 `~/.local/state/omarchycn/backups/dev-mirror/<时间戳>/`，
+恢复：`omarchycn restore list` + `omarchycn restore config <时间戳>`。
+docker 目标写 `/etc/docker/daemon.json`（需 sudo，重启 docker 生效）。
@@ -0,0 +1,34 @@
+# 中文输入与字体
+
+## 一键配置
+
+```bash
+omarchycn locale apply   # 生成 zh_CN.UTF-8 / en_US.UTF-8
+omarchycn font apply     # 思源黑体/宋体 + emoji + fallback 优先级
+omarchycn ime apply      # Fcitx5 + Rime，默认拼音
+```
+
+字体配置保证中文优先落到简体字形（含无语言标签的 Chromium/Electron 路径），
+日文/韩文标签内容仍使用各自原生变体。验证：`omarchycn font status`。
+
+## 切换键
+
+默认 `Ctrl+Space`（Fcitx5 原生）。改用 `Super+Space`：
+
+```bash
+omarchycn ime hotkey super-space
+```
+
+此时 Omarchy 主菜单自动迁移到 `Super+Alt+Space`（原 Apps 菜单快捷键让位，
+可从主菜单进入 Apps 或在 `~/.config/hypr/bindings.lua` 自行改绑）。
+切回：`omarchycn ime hotkey ctrl-space`（自动移除迁移块）。
+
+## 排查
+
+```bash
+omarchycn ime status     # 包、profile、切换键冲突、进程状态
+omarchycn doctor ime
+```
+
+上游已内置 fcitx 环境变量（`INPUT_METHOD/QT_IM_MODULE/XMODIFIERS/SDL_IM_MODULE`）
+与 `omarchy-fcitx5` 用户服务，OmarchyCN 不重复配置。
@@ -0,0 +1,36 @@
+# AI Hub
+
+Harness（工具）与 Provider（模型服务）分层管理，配置数据在 `cn/registry/`。
+
+## 快速开始
+
+```bash
+omarchycn ai setup       # 向导：Harness → Provider → 模型 → API Key → 测试
+omarchycn ai launch      # 以默认 Profile 启动
+```
+
+支持组合（stable = 有 mock 回归覆盖的适配器）：
+
+| Harness | DeepSeek | Kimi | Z.AI/GLM |
+|---|---|---|---|
+| Claude Code | stable | stable | stable |
+| Codex | stable | — | — |
+| OpenCode | stable | — | — |
+| Kimi Code | — | 官方 CLI 自管 | — |
+| Deep Code | 官方 CLI 自管 | — | — |
+
+## 手动操作
+
+```bash
+omarchycn ai secret set deepseek          # 存 Key（Secret Service → pass → 0600 文件）
+omarchycn ai profile create work claude-code deepseek default-coding
+omarchycn ai profile use work
+omarchycn ai test work                    # 真实连通/鉴权/模型调用测试
+omarchycn ai doctor                       # 安装、凭据、端点诊断
+omarchycn ai default work                 # 映射到 Super+Shift+Ctrl+A / omarchy agent
+```
+
+`ai default` 把配置持久化进 Harness 自身文件（Claude Code 的 settings.json /
+Codex 的 config.toml，均 0600 并保留你的其它设置），上游快捷键即以国内模型启动。
+
+注意：`ai test` 消耗一次极小请求（max_tokens=8），需有效 API Key 与账户额度。
@@ -0,0 +1,36 @@
+# 更新与恢复
+
+## 更新
+
+- ISO 安装：跟随上游 `omarchy update`（cn 层随 omarchy-dev 包更新）
+- Overlay 安装：`omarchycn update`（拉取源码 → 重装 overlay → 执行未跑过的 cn 迁移）
+
+## 备份位置
+
+| 内容 | 位置 |
+|---|---|
+| pacman mirrorlist | `/etc/pacman.d/mirrorlist.omarchycn-bak-<时间戳>` |
+| 开发工具镜像配置 | `~/.local/state/omarchycn/backups/dev-mirror/<时间戳>/` |
+| 输入法 profile | `~/.local/state/omarchycn/backups/ime/<时间戳>/` |
+| 显示缩放 | `~/.config/hypr/monitors.lua.omarchycn-prev` |
+| Codex/Claude 配置 | 同目录 `*.omarchycn-bak-<时间戳>` |
+
+## 恢复
+
+```bash
+omarchycn restore list               # 列出全部备份
+omarchycn restore config <时间戳>    # 恢复开发工具镜像配置
+omarchycn mirror restore             # 恢复 pacman mirrorlist
+```
+
+系统级快照与回滚沿用上游 Btrfs + Snapper 机制（见上游手册 System snapshots）。
+
+## 诊断
+
+```bash
+omarchycn doctor            # network + mirror + dev-mirror + ime
+omarchycn ai doctor
+omarchycn status            # 版本与配置概览
+```
+
+诊断只在本地输出，不上传任何数据。