# CHM 助手 — MVP 开发任务清单 | 属性 | 内容 | |------|------| | 依据文档 | [prd.md](./prd.md) v1.7 | | MVP 范围说明 | 以 PRD **§13 里程碑 M1～M3** 为边界：**能可靠打开与阅读 CHM（含中文编码）**、**全文搜索与基础会话恢复**、**Markdown 项目撰写与一键编译并在内置阅读器中打开成品**；**不包含** M4（系统文件关联、命令行、导出、反编译等）及未列入下列条目的 P1/P2 增强。 | --- ## 1. 工程与架构（跨功能） | 序号 | 任务 | 对应 PRD | |------|------|----------| | 1.1 | 搭建 **Electron + React + TypeScript** 工程，区分主进程 / 预加载 / 渲染进程 | §4 | | 1.2 | 集成 **shadcn/ui**，建立设计令牌（浅色 / 深色 / 护眼）与全局主题（IF-01） | IF-01 | | 1.3 | 建立 **CHMLib** 源码纳入方式（submodule / vendoring）与跨平台 **node-gyp/CMake** 构建脚本 | §4.2.1 | | 1.4 | 实现 **C++ Node Addon（node-addon-api）**：封装 CHMLib，向主进程暴露窄 IPC API（打开、读元数据、枚举目录/索引、读资源流等） | §4.2.2，RD-02 | | 1.5 | 主进程 **IPC 契约** 与安全校验（路径白名单、错误码不泄漏细节至渲染层） | §4.1 | | 1.6 | 阅读器 **沙盒 WebView/iframe** 策略：CSP、受限本地访问、CHM 内脚本默认策略文档化 | RD-07，§10.1 | | 1.7 | **按需加载**：阅读模式勿默认加载 Monaco；创作模式勿默认加载 CHM Addon（除非预览能力开启） | §4.1，IF-11（策略落地） | | 1.8 | 内置 **关于 / NOTICES**：CHMLib **LGPL-2.1**；若打包内置 **chmcmd** 则 **GPL-2** 署名 | §4.2.1，§12.1 | --- ## 2. 国际化与设置（M1 必读） | 序号 | 任务 | 对应 PRD | |------|------|----------| | 2.1 | **i18n** 脚手架：zh-Hans / zh-Hant / en 资源结构、懒加载或分包策略（TDD 定目录） | §9.4 段首，IF-07 | | 2.2 | 翻译 **核心路径**：首页、阅读器壳、创作器壳、设置、关于 | IF-07 | | 2.3 | **界面语言**：默认「跟随系统」、设置内固定简中/繁中/英/恢复跟随、持久化 | §9.4，§11 | | 2.4 | **设置页**：阅读器默认字符编码提示与覆盖（关联 RD-08）；主题切换（IF-01） | §11，RD-15，RD-08 | | 2.5 | 缺 key **不崩溃**；冒烟用例覆盖跟随系统 + 手动切换 | IF-07 验收 | --- ## 3. 统一入口与工作区（M1～M2） | 序号 | 任务 | 对应 PRD | |------|------|----------| | 3.1 | **启动首页**三主入口卡片：打开 CHM、新建/打开创作项目、最近记录（含 `.chm` 与项目区分） | FE-01，FE-02 | | 3.2 | **多标签**：`.chm` 与创作项目标签共存；关闭前未保存确认 | FE-05 | | 3.3 | **模式切换**：阅读 / 创作在同一窗口内切换，主题与侧栏策略一致 | FE-03 | | 3.4 | **全局导航**：阅读侧为目录/索引/书签面板；创作侧为文件树/编译面板占位符合 FE-07 | FE-07 | | 3.5 | 打开 CHM：**菜单、拖拽**（RD-01）；**命令行 `--read`** 可作为 MVP 后快速跟进，本清单以 M1 正文为准时 **菜单+拖拽为 MVP 必达**，关联见下条 | RD-01 | --- ## 4. CHM 阅读器（M1） | 序号 | 任务 | 对应 PRD | |------|------|----------| | 4.1 | 调用 Addon **打开并校验** CHM，展示可读错误（损坏不崩溃） | RD-01，RD-02 | | 4.2 | **树形目录（.hhc）**、**索引（.hhk）**、锚点跳转；导航文案与正文 **同一套解码链** | RD-04 | | 4.3 | **前进 / 后退**、**面包屑** | RD-05 | | 4.4 | **沙盒内渲染** HTML/CSS/JS/多媒体 | RD-07 | | 4.5 | **RD-08 解码链**：charset 优先级 + 启发式（含 GBK/GB2312/GB18030/UTF-8 等）+ **手动指定编码** + 按文件记忆策略 | RD-08 | | 4.6 | 纯文本/摘要/复制与当前解码 **一致** | RD-08a | | 4.7 | **缩放**（25%～500%）、**宽度模式**；状态持久化策略按设计定稿 | RD-09 | | 4.8 | **浅色 / 深色 / 护眼** 与阅读样式（RD-15 基础）；与 IF-01 联动 | RD-15，IF-01 | --- ## 5. 搜索、查找与会话（M2） | 序号 | 任务 | 对应 PRD | |------|------|----------| | 5.1 | **全文搜索**：CHMLib 索引与/或 Addon 自建策略（TDD 定首版）；结果列表含标题/摘要 | RD-11 | | 5.2 | **页面内查找（Ctrl+F）** | RD-10 | | 5.3 | **会话恢复**：上次打开文件、标签、阅读位置、侧栏状态（冷启动可复现） | RD-17 | | 5.4 | （**MVP 内建议完成，PRD P1**）搜索结果 **高亮**、进入页后关键词高亮（RD-12）— 若工期紧可标为 *MVP-S* 冲刺项 | RD-12 | | 5.5 | （**MVP 内建议完成，PRD P1**）目录与正文 **滚动同步**高亮（RD-06）— 可标 *MVP-S* | RD-06 | | 5.6 | （**MVP 内建议完成，PRD P1**）大文件打开 **进度/惰性加载**（RD-03）— 可标 *MVP-S* | RD-03 | | 5.7 | **RD-08b**（GBK 页内中文搜索命中）PRD 为 P1；MVP 力争实现，否则在版本说明中声明「首版仅限 UTF-8 页内搜索」 | RD-08b | --- ## 6. Markdown 创作与编译（M3） | 序号 | 任务 | 对应 PRD | |------|------|----------| | 6.1 | 集成 **Monaco**，Markdown 语法能力；**UTF-8 无 BOM** 默认读写 | CR-01 | | 6.2 | **项目树**：无限层级、节点绑定 `.md`、新建/重命名/删除；同步 `.hhc` 结构 | CR-02 | | 6.3 | **项目元数据**编辑（标题、作者、语言、编码默认 UTF-8、默认页、窗口与导航字段）；**`.chmproj` 或等价** 持久化 | CR-03 | | 6.4 | **资源导入**与相对路径；编译时打包；缺失资源在日志可定位 | CR-04 | | 6.5 | **markdown-it** 管道：`UTF-8 无 BOM` `.md` → `UTF-8 无 BOM` HTML + `` | §4，CR-06 | | 6.6 | 生成 **`.hhp` / `.hhc` / `.hhk`**，字段与 **Windows `hhc.exe` / macOS/Linux chmcmd** 对齐（首版以 **主目标平台** 跑通为准） | CR-06 | | 6.7 | **调用外部编译器**产出 `.chm`；失败时人类可读错误；**务实路线**：Win 不捆绑 `hhc`（检测+引导），Unix 可内置 `chmcmd`，设置页自定义路径 | CR-06，§12.1，[compiler-setup.md](./compiler-setup.md) | | 6.8 | 编译完成 **内置阅读器自动打开**（可设置关闭） | CR-07 | | 6.9 | **编译面板**：进度、详细日志、错误高亮、**点击跳转源码** | CR-09 | | 6.10 | **CR-08a 验收**：编译出的 CHM 在内置阅读器中 **中文无乱码**（与 RD-08 一致） | CR-08a | | 6.11 | **新建/打开项目**（目录 + `.chmproj`）；最近项目列表（**另存模板 CR-10 为 P1**，MVP 可仅实现新建/打开/最近） | CR-10 | | 6.12 | **编译器打包与设置**：`compilers:stage` + electron-builder `extraResources`；设置页状态/浏览/清除/打开 Win 安装说明 | [compiler-setup.md](./compiler-setup.md) | --- ## 7. 测试与验收（MVP 出口） **清单与脚本**：[mvp-acceptance-checklist.md](./mvp-acceptance-checklist.md) · 签核表：[mvp-acceptance-signoff.md](./mvp-acceptance-signoff.md) · 自动化：`pnpm run test:mvp` | 序号 | 任务 | 对应 PRD | |------|------|----------| | 7.1 | **中文 GBK 样例 CHM**：打开、目录、正文、搜索（按 RD-08b 达标口径） | M1，§10.3 | | 7.2 | **默认 UTF-8 无 BOM**：新建项目 → 编译 → 内置阅读器打开 — 中文回归 | M3，CR-06 | | 7.3 | **简/繁/英** 界面核心路径冒烟 | M1，IF-07 | | 7.4 | 损坏 CHM、超大 CHM 的 **降级表现**（不崩溃、可取消） | RD-02，§10.2 | | 7.5 | Windows / macOS **主目标平台** 构建与安装包冒烟（Linux 若未纳入 MVP 则文档声明） | §5.1 | --- ## 8. 明确不包含在本 MVP（Post-MVP / M4） 以下保留在 **M4 或后续版本**，**不**列入本 `mvp.md` 完成条件： - 系统 **文件关联**（IF-03）、**`.chmproj` 双击关联**（IF-04） - **`electron-updater`**（IF-05）、**崩溃遥测**（IF-06）— *可按项目需要提前，但不阻塞 MVP 定义* - **`--project` / `--compile` CLI**（IF-09～IF-10） - **导出** PDF/HTML/全书（RD-16） - **反编译为 Markdown**（RD-18）及阅读↔创作增强（RD-19～20，CR-11） - **书签/标注**进阶（RD-13～14） - **内置多主题 CSS 包与自定义 CSS**（CR-05）— *MVP 可用单一默认样式 + 后续 CR-05* - **CR-08 非 UTF-8 编译输出**（P1，旧环境兼容） - **IF-02 可自定义快捷键**（P1） --- ## 9. 任务依赖建议（简图） ```text CHMLib Addon (1.4) → 阅读器主链 (4.x) → 全文搜索 (5.1) ↘ 创作编译链 (6.6～6.7) 依赖同 Addon 亦可仅读 CHM 验证 i18n (2.x) 与 首页 (3.1) 可与 4.x 并行 Monaco 与 markdown-it (6.1, 6.5) 在 6.6 前完成 ``` --- ## 10. 文档维护 - 若 PRD 升版导致需求 ID 变更，请同步更新本表「对应 PRD」列。 - *MVP-S* 条目标记表示 **冲刺项**：不阻塞「MVP 最小发布」但强烈建议在首版前完成。 - **CHM 编译器**安装、打包与许可：见 [compiler-setup.md](./compiler-setup.md)；用户向说明见仓库 [README.md](../README.md)。 - **完成度**见下文 §11，发版前请同步更新状态列。 --- ## 11. 完成度跟踪 | 属性 | 内容 | |------|------| | 最近评估 | 2026-05-20 | | 评估依据 | 仓库实现 + `npm run test:mvp`（12 通过 / 0 失败 / 4 跳过） | | 范围 | §1～§7（不含 §8 Post-MVP） | ### 11.1 状态图例 | 标记 | 含义 | |------|------| | ✅ | 已完成，满足 MVP 验收口径 | | 🟡 | 部分完成，有已知缺口 | | ❌ | 未完成或未开始 | | ⚠️ | 实现路径已有，**待人工回归/冒烟**（§7） | | *MVP-S* | 冲刺项，不阻塞最小发布（见 §10） | **负责人**列留空，由项目组在 issue/看板中填写。 ### 11.2 总览（按章节） | 章节 | 条目数 | ✅ | 🟡 | ❌ | ⚠️ | 章节完成度（粗估） | |------|--------|----|----|----|----|-------------------| | §1 工程与架构 | 8 | 5 | 3 | 0 | 0 | ~85% | | §2 国际化与设置 | 5 | 4 | 1 | 0 | 0 | ~90% | | §3 统一入口与工作区 | 5 | 4 | 1 | 0 | 0 | ~90% | | §4 CHM 阅读器 | 8 | 8 | 0 | 0 | 0 | ~100% | | §5 搜索与会话 | 7 | 3 | 2 | 2 | 0 | P0 ~75%；含 *MVP-S* 更低 | | §6 Markdown 创作 | 12 | 11 | 0 | 0 | 1 | ~96% | | §7 测试与验收 | 5 | 0 | 0 | 0 | 5 | 自动化通过；人工签核待完成 | | **合计（§1～§7）** | **50** | **35** | **7** | **3** | **6** | **功能实现约 92%～94%；§7 人工签核未闭环** | **里程碑粗估**：M1 阅读 ~90% · M2 搜索/会话 ~70% · M3 创作/编译 ~96%。 **发布建议**：主链路可演示；请运行 `pnpm run test:mvp` 并按 [mvp-acceptance-signoff.md](./mvp-acceptance-signoff.md) 完成 §7 人工签核后再标「MVP 可发布」。 ### 11.3 §1 工程与架构 | 序号 | 状态 | 负责人 | 备注 | |------|------|--------|------| | 1.1 | ✅ | | Electron + React + TS，主/预加载/渲染分离 | | 1.2 | ✅ | | shadcn/ui；浅色/深色/护眼（`sepia`） | | 1.3 | ✅ | | CHMLib vendoring；`native:rebuild` | | 1.4 | ✅ | | `chm_addon.node`；打开/枚举/读对象 | | 1.5 | 🟡 | | IPC + 错误码；`resolveMdPath` 防穿越；非全面路径白名单审计 | | 1.6 | 🟡 | | `chm:` 协议 CSP + iframe sandbox；RD-07 独立策略文档仍弱 | | 1.7 | 🟡 | | Monaco `lazy`；进入创作标签仍会加载 Monaco | | 1.8 | ✅ | | `public/NOTICES.md`；关于页「打开 NOTICES」调用 `app:open-notices` | ### 11.4 §2 国际化与设置 | 序号 | 状态 | 负责人 | 备注 | |------|------|--------|------| | 2.1 | ✅ | | zh-Hans / zh-Hant / en | | 2.2 | ✅ | | 首页、阅读器、创作器、设置、关于 | | 2.3 | ✅ | | 跟随系统 + 固定语言 + `setLocale` 持久化 | | 2.4 | ✅ | | 阅读编码、主题、CHM 编译器设置 | | 2.5 | 🟡 | | 缺 key 回退为 key 不崩溃；无自动化冒烟用例 | ### 11.5 §3 统一入口与工作区 | 序号 | 状态 | 负责人 | 备注 | |------|------|--------|------| | 3.1 | ✅ | | 三主入口 + 最近（CHM / 项目区分） | | 3.2 | ✅ | | 多标签；创作 dirty 关标签与切换页同一套保存确认 | | 3.3 | ✅ | | 同窗口阅读/创作标签 | | 3.4 | 🟡 | | 阅读：目录/索引/搜索；书签占位。创作：树 + 编译面板 | | 3.5 | ✅ | | 菜单 + 首页拖放 `.chm` | ### 11.6 §4 CHM 阅读器 | 序号 | 状态 | 负责人 | 备注 | |------|------|--------|------| | 4.1 | ✅ | | 打开/校验/可读错误 | | 4.2 | ✅ | | `.hhc` / `.hhk`；导航与正文同解码链 | | 4.3 | ✅ | | 前进/后退、面包屑 | | 4.4 | ✅ | | 沙盒 iframe + `chm://` | | 4.5 | ✅ | | charset + 启发式 + 设置覆盖 | | 4.6 | ✅ | | 工具栏「复制」：优先选区，否则经 RD-08 解码链取页面纯文本 | | 4.7 | ✅ | | 缩放 25%～500%、宽度模式、会话持久化 | | 4.8 | ✅ | | 主题与阅读样式、IF-01 联动 | ### 11.7 §5 搜索、查找与会话 | 序号 | 状态 | 负责人 | 备注 | |------|------|--------|------| | 5.1 | ✅ | | `searchChmSession` 线性扫描 + 摘要 | | 5.2 | ✅ | | Ctrl/Cmd+F 页内查找 | | 5.3 | ✅ | | 冷启动恢复标签与阅读 UI 状态 | | 5.4 | 🟡 | *MVP-S* | 打开命中后 `pendingFind`；无列表/正文高亮样式 | | 5.5 | ❌ | *MVP-S* | 仅目录 active 样式，无滚动同步 | | 5.6 | ❌ | *MVP-S* | 无大文件打开进度/惰性加载 | | 5.7 | 🟡 | | 解码后页内/全文检索逻辑可行；未正式验收与版本声明 | ### 11.8 §6 Markdown 创作与编译 | 序号 | 状态 | 负责人 | 备注 | |------|------|--------|------| | 6.1 | ✅ | | Monaco + UTF-8 无 BOM 读写 | | 6.2 | ✅ | | 树展示、新建/重命名/删除；**拖拽排序**（同级/移入文件夹，同步 `.chmproj`） | | 6.3 | ✅ | | 元数据 + `.chmproj` | | 6.4 | ✅ | | 资源导入、编译打包、缺失日志 | | 6.5 | ✅ | | markdown-it + UTF-8 HTML | | 6.6 | ✅ | | `.hhp` / `.hhc` / `.hhk` 生成 | | 6.7 | ✅ | | 外部编译器；[compiler-setup.md](./compiler-setup.md) 务实路线 | | 6.8 | ✅ | | 编译后内置阅读器打开（可关） | | 6.9 | 🟡 | | 编译日志、行号跳转、`compile-log` 流；无细粒度进度条 | | 6.10 | ⚠️ | | 管道具备；需 GBK/UTF-8 样例人工回归 | | 6.11 | ✅ | | 新建/打开/最近项目 | | 6.12 | ✅ | | `compilers:stage`、`extraResources`、设置页编译器 | ### 11.9 §7 测试与验收（MVP 出口） | 序号 | 状态 | 负责人 | 备注 | |------|------|--------|------| | 7.1 | ⚠️ | | 自动化需 GBK 样例（`test/fixtures/gbk/sample.chm` 或 env）；见 signoff 表 | | 7.2 | ⚠️ | | `test:mvp` 可自动：UTF-8 无 BOM + 编译 + 产物中文（需 chmcmd/hhc） | | 7.3 | ⚠️ | | i18n key 三语自动；界面路径人工表 | | 7.4 | ⚠️ | | 损坏样例自动；超大/可取消人工 | | 7.5 | ⚠️ | | GitHub Actions `release.yml`：mac x64+arm64、linux x64+arm64、win x64；见 [ci.md](./ci.md) | ### 11.10 建议优先补齐（发版前） 1. **§7**：运行 `pnpm run test:mvp`，再按 [mvp-acceptance-signoff.md](./mvp-acceptance-signoff.md) 签核人工项。 2. 准备 GBK 样例：复制至 `test/fixtures/gbk/sample.chm` 或设置 `CHM_ASSISTANT_GBK_SAMPLE`。 3. **§7.5**：主目标平台 `dist:mac` / `dist:win` 后重跑 `test:mvp` 验证 `release/`。 4. （可选）**§1.6 / §1.7**：沙盒策略文档化、Monaco 按需加载收紧。 *MVP-S（5.4～5.6）与 §8 Post-MVP 不阻塞最小发布，按排期迭代。* --- *本清单为研发排期输入，优先级与人力分配由项目组在 issue/看板中细拆。*