# CHM 助手（CHM Assistant）产品需求文档（PRD）

| 文档属性 | 内容 |
|---------|------|
| 产品名称 | CHM 助手（CHM Assistant） |
| 文档版本 | 1.7 |
| 状态 | 草案 |
| 对应功能基线 | [feature.md](./feature.md) |

---

## 1. 文档概述

### 1.1 目的

本文档定义「CHM 助手」的产品目标、范围、功能与非功能需求，为设计、研发、测试及发布提供统一依据。详细功能条目以 [功能清单](./feature.md) 为输入，本文档对其进行**可验收、可追踪、可排期**的规范化表述。

### 1.2 读者对象

- 产品与设计：理解信息架构与交互边界  
- 研发（Electron / 前端 / C++ 原生扩展（N-API）/ 构建链）：明确接口、约束与交付物  
- 测试：编写用例与验收标准  
- 运维与发布：更新策略、诊断与兼容性  

### 1.3 术语与缩写

| 术语 | 说明 |
|------|------|
| CHM | Compiled HTML Help，微软帮助文件格式 |
| HHP / HHC / HHK | CHM 工程文件、目录文件、索引文件 |
| N-API / NAPI | Node-API：Node.js **C** 稳定 ABI，用于实现原生模块；本产品通过 **node-addon-api（C++）** 调用 N-API，而非手写纯 C 绑定 |
| node-addon-api | Node 官方维护的 **N-API C++ 包装库**，用于以 C++ 编写 Addon；本项目绑定层**强制基线**，以兼顾开发效率与社区范例 |
| 界面语言（UI i18n） | 应用**壳层**（菜单、设置、对话框等）显示语言，**不等于** CHM 内正文编码；须支持简中/繁中/英文并易扩展，详见 §9.4 |
| CHMLib / libchm | 本产品中特指上游 **[CHMLib](https://github.com/jedwing/CHMLib)**（**C** 语言 CHM 读写库）：负责解析与流读取；由 **C++ Addon** 经 C 链接调用，再暴露给 Node；口语「libchm」与「CHMLib」同指该上游 |
| chmcmd | 非 Windows 平台常用于生成 CHM 的外部工具（需随文档说明依赖与许可） |
| 创作侧 UTF-8 与 BOM | **默认：UTF-8 且无 BOM**（`.md`、编译生成的 `.html` 等），与 Git、跨平台工具链及显式 `charset` 声明一致。**禁止**不加区分地对全部源文件默认写入 BOM。若 **Windows + `hhc.exe`（及目标 chmcmd）** 回归表明**某一类中间文件**（如特定 `.hhp`）必须有 BOM 才能被编译器稳定识别，须在 **TDD** 中单列该例外及触发条件，不得反向要求用户 Markdown 默认带 BOM |

---

## 2. 产品愿景与定位

### 2.1 一句话定位

跨平台的 **CHM 全生命周期工具**：在同一应用中完成 **打开与精细阅读**、**Markdown 源文档创作**、**编译与预览成品 CHM**，并通过阅读 ↔ 创作闭环支撑「读后改、改后再读」的工作流。

### 2.2 核心价值

- **统一入口**：阅读 `.chm` 与编辑「创作项目」无需切换不同软件。  
- **引擎可信**：CHM 解析与访问由 **[CHMLib](https://github.com/jedwing/CHMLib)（C）+ C++ Node Addon（node-addon-api / N-API）** 在主进程侧完成，渲染层沙盒隔离。  
- **创作现代**：以 Markdown 为中心，Monaco 编辑 + 主题/CSS + 一键走通 HTML 工程与平台编译器。  
- **差异化闭环**：阅读器内 **反编译为 Markdown 项目**、创作中 **增量/局部预览**、双向跳转与笔记汇总。  

### 2.3 竞品与差异化（摘要）

同类工具往往偏「只读」或「只编」；本产品强调**双模式深度整合**与**会话级连续性**（标签、历史、书签标注与项目树同源体验）。

---

## 3. 目标用户与使用场景

### 3.1 用户画像（摘要）

| 角色 | 诉求 |
|------|------|
| 技术写作者 / 文档工程师 | 用 Markdown 维护手册，输出标准 CHM，需稳定编译链与可定位错误 |
| 开发者 / 运维读者 | 快速检索、书签标注、导出或打印，需编码与主题可控 |
| 存量 CHM 维护者 | 打开旧版 CHM、必要时反编为可编辑源，减少重复录入 |

### 3.2 核心场景

1. 双击 `.chm` 打开 → 目录导航 → 全文搜索 → 标注 → 导出 PDF。  
2. 新建项目 → 编写 Markdown → 实时预览 → 一键编译 → **内置阅读器**打开产物。  
3. 阅读某 CHM → **反编译为 Markdown 项目** → 在创作模式修改 → 再编译覆盖分发。  
4. CI/脚本：`--compile` 无界面编译；`--read` 打开指定文件。  

---

## 4. 技术架构约束（强制）

以下栈为产品基线，需求实现须兼容该架构；若子项需调整，应走变更记录并同步本文档版本。

| 层级 | 技术选型 | PRD 约束 |
|------|----------|----------|
| 壳与系统集成 | Electron | 多窗口/单窗口策略由设计定稿；须支持自动更新、文件关联、命令行入口 |
| UI | React + shadcn/ui | 全局主题、组件一致性；设置与模式间状态可同步 |
| CHM 解析 | [CHMLib](https://github.com/jedwing/CHMLib) + **C++** Node Addon | **绑定层**使用 **C++** 与 **node-addon-api**（基于 N-API）；**底层库**为 CHMLib（C），编译期链接、运行期自 C++ 以 C 调用约定调用；主进程须仅通过该 Addon 暴露安全 API；崩溃可诊断 |
| 创作编辑 | Monaco Editor | 代码编辑能力需求由创作模块章节约束 |
| Markdown → HTML | markdown-it + 插件 | 源 **Markdown：UTF-8、无 BOM（默认）**；编译生成的 HTML：**UTF-8、无 BOM（默认）** + 显式 `charset` 声明，且与 `.hhp/.hhc` 一致（参见 §8、术语「创作侧 UTF-8 与 BOM」）；与主题/CSS 注入、资源路径策略一致 |
| CHM 编译 | Windows: `hhc.exe`；macOS/Linux: `chmcmd` 等 | 须在安装/文档中明确**外部依赖**、版本与失败降级策略 |

### 4.1 进程与安全模型（需求级）

- **渲染**：HTML/CSS/JS/多媒体在**沙盒化**环境展示；限制对本地与 Node 的非授权访问。  
- **高性能路径**：重解析、索引构建等放在主进程或 Worker，避免阻塞 UI；长任务须有取消与进度。  
- **按需加载**：阅读模式不加载 Monaco；创作模式可延迟加载 **CHMLib C++ Addon**（除非启用「阅读器式预览」），以降低常驻内存（与功能清单一致）。  

### 4.2 CHMLib 与 Node 原生扩展（选型）

#### 4.2.1 CHMLib（C 解析库）

| 项 | 说明 |
|----|------|
| **上游仓库** | [https://github.com/jedwing/CHMLib](https://github.com/jedwing/CHMLib) |
| **角色** | CHM 文件的底层解析与内容访问（与 PRD 中阅读、全文检索数据源、创作侧「解析预览」等能力对齐） |
| **源码纳入** | 以 **vendoring / git submodule / 锁定版本的 tarball** 等方式纳入构建仓库；**禁止**未评审即换装其他 CHM 解析库 |
| **许可** | 上游随仓库附带 **GNU LGPL v2.1**（见上游 `COPYING`）。发行物须符合 LGPL 义务：保留版权与许可声明、在「关于」或 `NOTICES` 中标注 CHMLib 来源；若静态链入或分发方式触发额外义务，由法务与构建方案评审后落实（如提供可重链对象、动态库策略等） |
| **版本策略** | 锁定已知良好提交或标签并在 PRD/构建文档中记录；升级上游须做 **CHM 回归集**（多编码、大文件、损坏包）与 **ABI 稳定性** 验证 |

#### 4.2.2 Node Addon 绑定层（C++）

| 项 | 说明 |
|----|------|
| **实现语言** | **C++**（非纯 C），以满足**开发效率、社区范例与排错资料丰富**的产品/engineering 取向 |
| **官方封装** | **[node-addon-api](https://github.com/nodejs/node-addon-api)**（N-API 的 C++ 封装）；新增绑定与对象生命周期管理优先遵循该库惯例，避免直接高频调用底层 `node_api.h` C 宏（除非必要） |
| **与 CHMLib 衔接** | Addon 工程链入 CHMLib 后，在 C++ 翻译单元内通过 **C 链接**（如 `extern "C"` 头文件、`#include` CHMLib 公开头）调用其 API；**不在此层用 C++ 重写 CHM 解析逻辑** |
| **构建** | 随 Electron/Node 目标 ABI 由 **`node-gyp`（或等价，如 CMake + node-api-headers）** 各平台编译；产物为 **N-API** 原生 `.node`（或平台等价物） |
| **约束** | 对外仅暴露经过校验的、与主进程 IPC 契约一致的 **窄接口**；错误码与异常不得泄漏实现细节至渲染进程 |

---

## 5. 产品范围

### 5.1 范围内（MVP → 完整版递进）

- 统一入口、阅读模块、创作模块、共享基础设施（见第 6～9 章分级）。  
- 跨平台发布：**Windows、macOS** 为必须；**Linux** 若发布，需单独验证 `chmcmd` 与用户权限。  

### 5.2 范围外（除非后续 PRD 增订）

- 在线协作、云同步账户体系。  
- 完全 visual 的「所见即所得」富文本排版器（非 Markdown）。  
- 对 CHM 二进制格式的**非标准专有扩展**的保证兼容（仅承诺尽力兼容常见 CHM）。  

---

## 6. 功能需求 — 统一入口与模式管理

### 6.1 启动首页

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| FE-01 | 展示三个主入口：**打开 CHM**、**新建/打开创作项目**、**最近记录**（文件 + 项目） | P0 | 三卡片可点击；最近记录可被清空或配置条数 |
| FE-02 | 最近记录展示逻辑一致：区分 `.chm` 与项目路径/`.chmproj` | P0 | 图标或副标题可区分类型；打开行为正确 |

### 6.2 模式切换与工作区

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| FE-03 | **阅读模式**与**创作模式**切换无明显状态丢失；同一窗口内完成 | P0 | 切换后主题/侧边栏策略符合设计；异常时有可恢复提示 |
| FE-04 | 阅读器中若存在关联 Markdown 项目，支持跳转到「编辑当前文档源」 | P1 | 无关联时给出引导（创建项目或反编译） |
| FE-05 | **多标签**：`.chm` 阅读标签与创作项目标签共存；关闭标签前未保存项有确认 | P0 | 与会话恢复（§7.8）一致 |
| FE-06 | **拆分视图**：左编辑右预览（创作）；阅读侧是否拆分由设计定义，若实现则须同步目录高亮 | P1 | 布局可调整；快捷键可配置（见 §9.2） |
| FE-07 | **全局导航**：侧边栏或顶栏随模式切换面板：阅读（目录/索引/书签）；创作（文件树/大纲/编译） | P0 | 模式切换 ≤ 约定阈值内完成首屏渲染（见 §10.2） |

---

## 7. 功能需求 — CHM 阅读模块

**中文与字符编码（问题背景）**：存量 **简体中文 CHM**（及不少繁体、日文等双字节场景）在 Windows / `hhc.exe` 时代常以 **GBK、GB2312、GB18030** 等编码存盘，而 Electron 与现代 WebView 默认按 **UTF-8** 解释字节流；若缺少可靠解码链，会出现**正文、目录标题或全文搜索高亮乱码**。本产品将 **「中文可读」** 与 UI 语言 i18n（§9.4）区分对待：前者是 **用户文档字节序列** 的正确还原，属于阅读器 **P0** 质量目标，须在 §7.3、§7.5 与 §10.3 联动验收。**创作侧**新建内容以 **Markdown + 默认 UTF-8（无 BOM）** 写出（§8），以与当代工具链一致；**阅读侧**仍须正确打开历史 CHM（本节上述解码链）。

### 7.1 打开与解析

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| RD-01 | 支持拖拽、菜单、**命令行**、**系统文件关联**打开 `.chm` | P0 | 命令行与关联入口与 §9.7 一致 |
| RD-02 | **CHMLib**（经 **C++ Node Addon / N-API**）须返回校验结果与基础元数据（标题、**语言/编码线索**等，以实现为准），供解码与 UI 默认策略使用 | P0 | 损坏 CHM 有可读错误信息，不崩溃 |
| RD-03 | 大文件打开时界面可响应（进度或惰性加载） | P1 | 量化标准见 §10.2 |

### 7.2 目录、索引与导航

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| RD-04 | 树形目录（`.hhc`）、字母索引（`.hhk`）、页面内锚点；**导航文案**（中文目录/索引标题等）须采用与 §7.3 一致的编码策略，避免仅正文正确而侧栏乱码 | P0 | 常见 CHM 跳转正确；含 **中文目录名** 的样例通过 |
| RD-05 | 前进/后退、面包屑路径 | P0 | 历史与当前 URL 一致 |
| RD-06 | 目录与内容区**滚动同步**（目录高亮当前位置） | P1 | 大目录下性能可接受 |

### 7.3 内容渲染

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| RD-07 | 沙盒化渲染 HTML/CSS/JS/多媒体 | P0 | 安全策略可审计；危险能力默认关闭 |
| RD-08 | **HTML 正文解码**：针对中文等乱码高发场景，解码顺序须可技术实现为（示例，以 TDD 为准）：① 资源协议层 **`Content-Type`/`charset`（若可得）**；② **HTML `<meta charset>` / `http-equiv`**；③ **字节序标记 BOM**；④ 与 CHM/Windows 帮助生态兼容的 **启发式检测**（覆盖 **GBK、GB2312、GB18030、UTF-8/16、Big5** 等常见集）；⑤ 用户 **手动指定编码** 并 **对当前页/整书重解码**（持久化策略由设计定稿，建议 **按已打开文件记忆**） | P0 | 准备在 **Windows 时代生成的中文 GBK 样例 CHM** 上验收；乱码可通过自动或手动策略消除；切换后刷新正确 |
| RD-08a | **与 RD-08 链一致**：从 CHM 抽取的 **纯文本/片段**（如搜索结果摘要、复制到剪贴板、导出纯文本）须与当前选用的解码结果一致，不得在下游再次错误转码 | P0 | 中英文关键词在摘要中可见且可读 |
| RD-08b | **全文搜索、页面内查找（§7.5 / RD-10）**：索引建立与用户输入关键词须与正文解码一致，**简体中文关键词**在 **非 UTF-8** 页面仍可命中（允许分阶段：P1 先保证常见 GBK） | P1 | 与 RD-11 联合验收；在 GBK 样例上有用例 |

### 7.4 阅读辅助

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| RD-09 | 页面缩放 25%–500%；宽度模式（适合宽度/全宽） | P0 | 缩放状态可按页或全局策略持久化（设计定稿） |
| RD-10 | 页面内查找（如 Ctrl+F） | P0 | 与系统快捷键方案可调（§9.2） |

### 7.5 全文搜索

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| RD-11 | 全文检索：优先利用 **CHMLib** 可访问的 CHM 内索引与流式读取能力；不足部分由 **C++ Addon** 侧自建索引或缓存，二者可组合 | P0 | 技术设计明确首版索引策略；结果列表含标题/摘要 |
| RD-12 | 结果高亮、上下文摘要；进入页面后关键词高亮 | P1 | 性能见 §10.2 |

### 7.6 书签与标注

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| RD-13 | 书签增删改、文件夹分组 | P1 | 与 `.chm` 路径或内部 URL 唯一关联 |
| RD-14 | 文本高亮、笔记注释；持久化；支持导入/导出 | P2 | 数据格式版本化，避免升级丢失 |

### 7.7 外观与导出

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| RD-15 | 浅色/深色/护眼；字体、字号、行距；侧边栏位置与宽度可调 | P0 | 与全局主题系统 §9.1 联动 |
| RD-16 | 打印当前页；导出 PDF、纯文本、HTML（单页或全书） | P1 | 导出完整性受 CHM 内资源与沙盒限制需在 UI 声明 |
| RD-17 | **会话恢复**：上次打开文件、标签、阅读位置、侧边栏状态 | P0 | 冷启动可复现；隐私模式下行为定义清晰 |

### 7.8 阅读 ↔ 创作协同（增强）

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| RD-18 | 阅读器内将当前 CHM **反编译为 Markdown 项目**（HTML→MD，保留目录结构）；落盘 **Markdown 规范为 UTF-8 且无 BOM**，与 §8 创作侧源文件策略一致 | P1 | 输出结构可被创作模块识别；失败可回滚 |
| RD-19 | 右键「在创作器中打开同名项目」 | P2 | 无项目时提示创建或反编译 |
| RD-20 | 将当前页 URL/片段发送到创作器笔记面板 | P2 | 冲突与去重策略由设计确定 |

---

## 8. 功能需求 — CHM 创作模块

**源格式与编码策略（创作侧）**：正文以 **Markdown（`.md`）** 编写与维护。**磁盘上的源文件默认为 UTF-8 且无 BOM**（与 Git、Node、`markdown-it` 及跨平台编辑器惯例一致；导入的带 BOM 文件可读取但**保存时应按项目策略规范为无 BOM**）。**新建项目** 与 **由反编译生成的 `.md`（RD-18）** 落盘为 **UTF-8 无 BOM**。  
**与存量/旧版 CHM 生态的兼容**包含两层含义：① **读**：用户继续用内置阅读器打开任意旧 `.chm` 时，依赖 §7 解码链，不依赖「源已是 UTF-8」；② **写**：**默认编译链** 产出 **UTF-8 无 BOM 的 HTML**（辅以正确 `<meta charset="UTF-8">` 或与等价声明）+ **与之一致的 `.hhp/.hhc/.hhk` 字段**，并与 **`hhc.exe`（Windows）/ 平台 chmcmd** 的可接受写法对齐（详见 CR-06；**代码页等细节与极小概率的「单文件 BOM 例外」** 仅写在 **TDD** 中且须经编译器回归证明），使**新编译的 CHM**在内置阅读器与常见查看器中 **中文可读**。若需照顾**极旧仅认 ANSI/GBK 的帮助环境**，可通过 **CR-08** 在项目级选择 **非 UTF-8 输出**（P1 选项，默认仍 UTF-8），且声明与实际字节必须一致，避免二次乱码。

### 8.1 编辑器与预览

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| CR-01 | 集成 Monaco：**源文件以 Markdown 为主**；语法高亮、补全、多光标、分屏编辑/预览、实时渲染；**默认以 UTF-8（无 BOM）读写 `.md`** | P0 | 大文件编辑卡顿可接受（§10.2）；编码与 CR-03 一致 |
| CR-02 | 项目树：无限层级文件夹；节点绑定 `.md`；拖拽排序；新建/重命名/删除 | P0 | 操作同步反映到 `.hhc` 结构 |
| CR-03 | 元数据编辑：标题、作者、语言、**中间/输出字符编码（默认 UTF-8，与段首策略一致）**、默认页、窗口样式、导航控件；**新建及常规保存的 Markdown 须为 UTF-8 且无 BOM**；打开外部导入或历史文件时若检测到疑似非 UTF-8 或带 BOM，须 **提示转换/规范为 UTF-8 无 BOM 另存** 或按项目策略显式处理（禁止静默错误解码导致中文损坏） | P0 | 写入 `.chmproj`/工程文件规则可回归测试；UTF-8 无 BOM 为主路径 |

### 8.2 资源、主题与编译

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| CR-04 | 资源导入：图片/附件；相对路径；编译打包 | P0 | 缺失资源在日志中可定位 |
| CR-05 | 内置 CHM CSS 主题；预览切换；自定义 CSS 编译注入 | P1 | 主题切换不污染用户数据 |
| CR-06 | 一键编译链：**UTF-8 无 BOM `.md`** → HTML（markdown-it，**默认生成 UTF-8 无 BOM 页面**，含正确 `<meta charset="UTF-8">` 或与等价声明）→ 生成 **`.hhp/.hhc/.hhk`**（语言/代码页等字段与 **`hhc.exe` / 各平台 chmcmd** 行为对齐，**中文标题与路径**可编译；**单文件 BOM 例外若有** 仅允许按 TDD + 回归证明）→ 调用平台编译器 → 输出 `.chm`。**默认配置下**编译出的 CHM 须被 **内置阅读器（§7，含中文）** 无乱码打开。若项目启用 **CR-08 遗留编码输出**，则 HTML 字节、工程声明与编译器选项须 **三方一致** | P0 | Windows/macOS/Linux 路径与错误码覆盖；**默认 UTF-8 无 BOM** 路径具备中文内容回归样例 |
| CR-07 | 编译完成**自动用内置阅读器打开** | P0 | 若用户关闭预览可在设置中禁用 |
| CR-08 | 编译选项：**输出/中间文件编码（默认 UTF-8；可选 GBK、GB18030 等以兼容旧版 Windows 帮助查看环境）**、压缩级别、是否全文索引、是否附带源 MD；非 UTF-8 为 **进阶选项**，须在 UI 说明适用场景与与现代 UTF-8 阅读路径的差异；**若启用非 UTF-8 输出**，中间 HTML/工程文件**是否写入 BOM** 及与 **`hhc.exe`/chmcmd** 的匹配关系须在 **TDD** 中按平台回归结论定义，且须与 CR-03 所选编码、工程声明、实际字节 **一致**，并与术语「创作侧 UTF-8 与 BOM」（默认无 BOM）**不矛盾** | P1 | 选项与 CR-03 联动持久化；选非 UTF-8 时须通过编译与内置阅读器双线验收 |
| CR-08a | **阅读—创作闭环**：默认 **UTF-8 无 BOM** 编译产物须与 **RD-08** 解码策略一致（内置阅读器首屏中文正确）；从旧 CHM **反编译（RD-18）** 进入创作的项目，以 **UTF-8 无 BOM Markdown** 为工作副本，再编译输出的 CHM 仍默认走 **UTF-8 无 BOM** 链 | P0 | 与 RD-18、CR-06 联合验收 |

### 8.3 编译体验与项目管理

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| CR-09 | 进度条、详细日志；错误高亮；**点击日志跳转源文件位置** | P0 | 路径与行列解析可靠 |
| CR-10 | 新建/打开项目（目录或 `.chmproj`）；最近项目；另存为模板 | P1 | `.chmproj` 与 §9.3 文件关联一致 |

### 8.4 创作 ↔ 阅读协同（增强）

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| CR-11 | 创作中可调用 **CHMLib**（经 **C++ Node Addon**）的解析能力，**不经过完整编译**预览某 HTML 页效果 | P2 | 与完整编译差异在 UI 提示 |
| CR-12 | 编译错误日志 → 源码跳转（与 CR-09 合并验收） | N/A | 重复需求合并跟踪 |

---

## 9. 功能需求 — 统一基础设施

### 9.1 外观与主题

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| IF-01 | 全局浅色/深色/自定义；shadcn/ui 统一风格；阅读背景与编辑器配色可联动 | P0 | 设计令牌与 CSS 变量一致 |

### 9.2 快捷键

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| IF-02 | 全局快捷键可自定义；阅读/创作**无默认冲突**或可检测提示 | P1 | 导入/导出快捷键配置（可选 P2） |

### 9.3 系统集成

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| IF-03 | 注册为 `.chm` 默认查看器（各平台能力范围内） | P1 | 权限与沙盒说明给用户 |
| IF-04 | `.chmproj` 关联双击进入创作模式 | P2 | 安装包或首次运行向导配置 |

### 9.4 更新、诊断与国际化

**界面语言（UI）**与 **CHM 文档内容编码（§7、§8）** 无关：本节约束应用壳层文案。**首发**须完整覆盖 **简体中文（zh-Hans）**、**繁体中文（zh-Hant）**、**英文（en）**；资源文件、翻译键命名与回退策略须 **便于在不改架构的前提下扩展** 更多语言（由 TDD 约定目录、懒加载与贡献说明）。**默认行为**：首次安装或用户选择「**跟随系统**」时，界面语言 **按操作系统区域 / 界面语言匹配**（无精确匹配时的 **回退顺序** 在 TDD 定义，例如 `zh-TW`→繁中、`zh-CN`→简中、其余→英文）。用户可随时在 **设置** 中 **手动指定** 上述三种之一（或「跟随系统」），选择 **持久化**；切换后应尽量 **即时生效**、**无需重启**（若平台限制必须重启，须在界面明确提示，列为 P1 验收）。

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| IF-05 | `electron-updater` 静默更新；更新阅读与创作共用版本 | P1 | 失败重试与回滚策略 |
| IF-06 | 崩溃与异常报告：主进程、渲染、**CHMLib C++ 原生模块（N-API）**；附带模式（读/创） | P1 | 用户可关闭或脱敏 |
| IF-07 | **i18n（界面）**：须交付 **简体中文、繁体中文、英文** 三套完整文案；键与资源组织 **便于扩展** 第四语言及以后（见段首）。**默认**为 **跟随系统**（见段首匹配与回退规则）；**设置内可改**为固定语言或恢复跟随系统，且 **持久化**（见 §11） | P0 | 核心路径（首页、阅读器、创作器、设置）三种语言冒烟；缺 key 不崩溃；跟随系统 + 手动覆盖各有用例 |

### 9.5 命令行接口

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| IF-08 | `app --read <file.chm>` 直接进入阅读 | P1 | 与 RD-01 一致 |
| IF-09 | `app --project <path>` 进入创作 | P1 | path 为目录或项目文件 |
| IF-10 | `app --compile <project>` 无头或最小 UI 编译并预览（可配置仅输出） | P2 | CI 场景文档化 |

### 9.6 性能策略

| ID | 需求描述 | 优先级 | 验收要点 |
|----|----------|--------|----------|
| IF-11 | 按模式动态加载模块（阅读/创作重量级依赖互斥加载） | P1 | 里程碑需内存基线对比 |

---

## 10. 非功能需求

### 10.1 安全与隐私

- **最小权限**：文件访问限于用户明确选择的路径与系统关联打开文件。  
- **内容安全**：CHM 内脚本默认受限；需 CSP 或等价机制文档。  
- **遥测**：崩溃上报需 GDPR/本土化合规选项（禁用、匿名化）。  

### 10.2 性能与可靠性（建议基线，可在评审后数值化）

- 冷启动到首页可交互时间：在目标中档设备上做标杆测试并写入版本说明。  
- 打开 50MB 级 CHM：首屏目录与首页渲染在可接受秒级范围内；UI 不冻结超过约定阈值。  
- 全文搜索：在约定 CHM 规模下响应时间有上限或渐进式结果。  

### 10.3 兼容性

- **OS**：Windows 10+、macOS 近期三个大版本（以 Electron 支持矩阵为准）。  
- **CHM**：常见简体/英文 CHM；对非标准打包 CHM 错误可恢复。  
- **字符编码（用户内容，重点）**：  
  - **必须**：阅读器对 **简体中文 CHM** 的 **GBK / GB2312 / GB18030** 与 **UTF-8** 混存场景有可验证策略（见 RD-08、RD-04、RD-08b），降低「打开即乱码」比例。  
  - **创作默认**：**Markdown 源与默认编译链** 以 **UTF-8、无 BOM** 为基线（§8、术语表、CR-01/03、CR-06、CR-08a）；可选 **遗留编码输出** 仅作兼容旧环境的项目级选项（CR-08）。  
  - **建议**：对 **繁体 Big5、日文 Shift_JIS** 等逐步扩展（里程碑与样例库由测试维护）。  
  - **说明**：乱码若因 **源文件损坏、加密或非标准二进制** 导致，须在 UI 给出与「仅编码不匹配」可区分的人类可读提示（不要求万能修复）。  

### 10.4 可维护性

- **C++ 原生扩展（N-API）**与渲染层 API 版本化；功能开关可按里程碑拆分。  
- 日志级别可配置；编译日志可导出。  

---

## 11. 数据模型与持久化（概要）

| 数据 | 说明 |
|------|------|
| 用户设置 | 主题、快捷键、关联行为、更新通道；**界面语言**（**跟随系统** / 固定 **简中·繁中·英文**）；**阅读器默认字符编码/按文件覆盖**（与 RD-08 对应；勿与界面语言混淆） |
| 会话状态 | 打开的标签、阅读位置、侧边栏尺寸 |
| 书签/标注 | 与 CHM 身份（路径 + 内部 URL + 内容哈希可选）绑定 |
| 项目配置 | `.chmproj` 或等价 JSON/YAML；与 `.hhp` 等生成物可再现；**含默认字符编码（UTF-8 无 BOM）及可选遗留输出编码**（CR-03 / CR-08）；**BOM 例外（若有）** 仅在 TDD 登记 |

详细 schema 由技术设计文档（TDD）补充。

---

## 12. 依赖、风险与假设

### 12.1 外部依赖

- **CHMLib**：源码来自 [jedwing/CHMLib](https://github.com/jedwing/CHMLib)，**LGPL-2.1**；与 **C++ Node Addon（node-addon-api）** 一并纳入构建与合规清单（参见 §4.2）。  
- **编译器**：`hhc.exe`（通常依赖 HTML Help Workshop 或对应可再发行组件）、`chmcmd`（许可与安装方式须在用户文档写明）。**产品实现（务实路线）**：Windows **不**再分发 `hhc.exe`，应用内检测并引导安装；macOS/Linux 发布包可内置 `chmcmd`（GPL-2，见 NOTICES），详见 [compiler-setup.md](./compiler-setup.md)。  
- **格式转换**：HTML→Markdown 质量因源 HTML 复杂度而异，需在界面声明「需人工校对」。  

### 12.2 风险

| 风险 | 缓解 |
|------|------|
| 各平台 CHM 编译链差异大 | 分平台 CI；默认路径探测 + 手动配置 |
| 沙盒内脚本与多媒体兼容 | 白名单能力；降级为下载后外部打开（可选） |
| CHMLib C++ Addon 崩溃 | 隔离进程或健壮封装；自动重启与报告 |

### 12.3 假设

- 目标用户能接受「创作侧依赖外部 CHM 编译器」的前提，或接受仅限阅读/导出 HTML 的降级模式（需产品决策）。

---

## 13. 里程碑建议（与优先级对照）

| 阶段 | 目标 | 主要范围 |
|------|------|----------|
| M1 | 可读 | RD-01～05、07～08（含 **中文 GBK 样例 CHM** 编码验收）、RD-15 基础、IF-07（**简/繁/英** 界面）、首页 FE-01 |
| M2 | 可搜可记 | RD-10～12、RD-17、会话与主题 IF-01 |
| M3 | 可写可编 | CR-01～07、CR-08a、CR-09、项目 CR-10 基础；**默认 UTF-8 无 BOM 编译中文回归** |
| M4 | 系统与专业 | IF-03～10、导出 RD-16、反编译 RD-18、增强项 P2 |

具体排期由项目组基于人力与 Electron 证书签名等因素调整。

---

## 14. 验收与追溯

- 每条需求带 **ID**，测试用例引用 ID 追溯。  
- **[feature.md](./feature.md)** 为能力清单母本；**PRD** 为排期与验收母本；二者冲突时以 **PRD 版本 changelog** 为准并回写功能清单。  
- 「完成」定义：功能可用 + 安全评审通过项 + 关键指标达到 §10 基线 + 用户可见文案与 i18n 完备（**简中/繁中/英** 核心路径）。

---

## 15. 文档变更记录

| 版本 | 日期 | 作者 | 说明 |
|------|------|------|------|
| 1.7 | 2026-05-18 | — | **界面语言**：简中/繁中/英文、易扩展；**默认跟随系统**、设置内可切换并持久化；扩展 §9.4、§1.3、§11、M1、§14；修正 §7 中 i18n 章节引用 |
| 1.6 | 2026-05-18 | — | **CR-08** 补充：非 UTF-8 输出路径下 **BOM 是否写入** 由 TDD 按 `hhc`/chmcmd 回归定义，并与默认无 BOM 策略一致、无矛盾 |
| 1.5 | 2026-05-18 | — | 明确创作与默认编译链：**UTF-8 默认无 BOM**；术语表新增 BOM 策略；联动 §4、§7、§8、CR-01/03/06/08a、RD-18、§10.3、§11、M3 |
| 1.4 | 2026-05-18 | — | 创作侧：**Markdown 默认 UTF-8**、编译链与 `hhc`/工程文件声明对齐、与旧 CHM 读写兼容策略；扩展 §8 段首与 CR-01/03/06/08，新增 CR-08a；联动 RD-18、§4、§10.3、§11、M3 |
| 1.3 | 2026-05-18 | — | 强化 **中文/遗留编码** 与乱码场景：§7 背景说明；扩展 RD-02/04/08 与新增 RD-08a/b；§10.3 编码兼容性；设置与 M1 回归样例 |
| 1.2 | 2026-05-18 | — | 明确 Node 绑定层为 **C++ + node-addon-api（N-API）**；扩展 §4.2 为 CHMLib（C）与 Addon（C++）分节；同步技术表、术语与需求表述 |
| 1.1 | 2026-05-18 | — | 明确 CHM 解析底层为 jedwing/CHMLib；补充 §4.2 选型、许可与版本策略；同步术语与外部依赖 |
| 1.0 | 2026-05-18 | — | 依据 feature.md 初版 PRD |

---

*本 PRD 为 living document；重大变更须升版本号并同步里程碑与测试范围。*