M5 安装器与多本书

Goal

作者在干净环境（含 Windows 中文用户名路径）一条命令装出可用的工作目录，建起第一本书；写章八阶段的每一步都有宿主可调的 CLI 通道，finalize→next 主循环可全程经 CLI 跑通。

对应实施计划 0.3 §2「M5 安装器与多本书」，上游依据：multi-agent-adaptation-spec v3.5 §8（init/update）、story-repo-spec 0.9 §2.0（工作目录层）、M1-M4 review follow-up F1（宿主 CLI 缝清单）。

Background（已确认事实）

M0-M4 已交付：格式层 41 读接口、写章脚本面（prepare-chapter/mechanical-check）、状态机 7 态 + git 隐身、AI 角色层 + 壳生成器（src/host-shells/generate.js + scripts/build-host-shells.mjs --check 已进 CI）。边界收口任务已归档，292 测试绿。
src/installer/index.js 是占位空文件。
落盘用例已齐但无 CLI 通道：persistDraftOutline / persistCreateBook / persistVolumeReview / persistRepair（src/state-machine/persist.js）、assembleReviewInput / runReviews（src/review/index.js）、finalizeChapter（src/finalize/index.js）只能进程内调用——真宿主（AI 会话）无法驱动写章后半段，M4 真模型 smoke 因此推迟 beta（registry smoke_status: deferred-beta）。
工作目录定位未做：bin/webnovel-writer.js 写死 repoPath = process.cwd()（M1 design 注释「M3 后续处理」，M3 未做）。装出的工作目录里跑 CLI 会把 .cache 建在工作目录而非书仓库，M5 必须先解决。
books.jsonl 读侧 + 扫描重建自愈已在 M4（src/session/index.js，含 writeBooksRegistry 自愈回写）；写侧（建书登记/换书）归 M5（源码注释明示）。
工作目录 AGENTS.md 模板已有（v7/templates/AGENTS.md，含  标记块）；书仓库指路 AGENTS.md（spec §2.1「建书时自动生成」）尚无实现——persistCreateBook 不写它。
壳生成器产物形状：{ <host>: { 'skills/webnovel-writer/SKILL.md', 'agents/<角色>.md|.toml' } }，无 hook 接线；claude-code 的 SessionStart hook 注入（multi-agent spec §5.5）需要 M5 在装出的 .claude/ 里接线。
SKILL.md 当前硬编码 webnovel-writer <命令> 调用形式；spec §5.9 要求命令引用语法做成平台上下文变量。
Node 版本门槛（≥ 22.13.0）与人话提示已在 src/runtime/node-version.js，bin 已接。
运行时依赖仅 js-yaml（spec §2.2），.webnovel/ 自带脚本时需一并解决其可用性。
CI 现状（.github/workflows/v7-ci.yml）：双平台 × 双 Node 版本，node --test + drift check + --version 冒烟；无安装器链路用例。

Requirements

A. 安装器 `init` / `update`（multi-agent spec §8）

A1 init：环境检测（Node 门槛复用现有函数；按 registry 顺序探测已装 agent CLI）→ 生成工作目录布局：
- AGENTS.md（公约数层，标记块管理；块外用户内容保留）
- .webnovel/（Node 脚本 + 角色定义 + 模板哈希清单 + books.jsonl 占位）——工作目录自包含，脚本离线可跑
- 检测到的各平台壳（.claude/、.codex/ 等，由 M4 生成器按条件块编译；claude-code 含 SessionStart hook 接线）
- 结束输出报告：装到了哪、各宿主支持等级、降级说明、下一步人话指引
A2 update：模板哈希追踪——哈希未变的文件直接更新；用户改过的提示并跳过（不静默覆盖），非交互默认跳过并列清单，--force 显式覆盖；AGENTS.md 只更新标记块内内容
A3 边界（spec §8.3）：不装 Node 之外的运行时、不改用户全局配置、不联网、不把工作目录变成 git 仓库；重复 init 幂等（等价于 update 语义或明确提示）
A4 平台壳 SKILL.md 的命令引用语法改为模板变量（§5.9），指向装出的 .webnovel/ 内脚本；SKILL.md 写章流程同步接 F1 通道（review-input→两审→save-review→finalize，「继续」吃 next --json DTO）

B. 多本书与工作目录定位（story-repo spec §2.0）

B1 books.jsonl 写侧：建书登记（字段含书名/目录/当前/最后打开）、换书（改「当前」标记）、书单列出；与 M4 读侧/自愈共用一个模块，不双写格式
B2 工作目录定位：bin 启动时判定——cwd 含 book.yaml → 书仓库直启（兼容开发/测试）；cwd 含 .webnovel/ → 按 books.jsonl 当前书解析 repoPath，无当前书给人话指引；两者都不是 → 人话提示「请从工作目录启动」。init 等工作目录层命令不受此约束
B3 书仓库指路 AGENTS.md：并入建书落盘（persistCreateBook），内容按 spec §2.1（误启动/单独 clone 时指回工作目录）
B4 SessionStart 注入接线：claude-code 壳带 hook 配置调 CLI 的会话上下文命令（输出复用 M4 assembleSessionContext，两宿主路径注入逐字一致）

C. F1 宿主 CLI 缝（实施计划 0.3 M5 清单，逐条）

C1 next --json：输出完整状态机 DTO（{ok, gitHealth, 序, state, needsAI, message, dto}）；不带 flag 保留现有人读 message
C2 review-input <章号>：组装 ReviewInput 并落盘供宿主读取
C3 save-review <章号> --file=<两审json>：读文件 → schema 校验 → 合并 → 落审稿单与评审报告（复用 runReviews 的校验/合并/落盘路径）
C4 persist-outline / persist-book / persist-volume-review / persist-repair：AI 态产物回流，--file=<json> 进；persist-book 同时完成 books.jsonl 登记 + 指路 AGENTS.md（B1/B3）
C5 finalize <章号> --payload=<定稿包json路径>：调 finalizeChapter，定稿后刷新缓存
C6 JSON 一律走 --file/--payload 文件路径，不走 stdin（Windows 中文管道编码雷区）；出错人话报错、退出码非零、永不带栈崩溃

D. CI 与验收链路

D1 Windows 中文路径安装链路 CI：干净临时目录（路径含中文，模拟中文用户名）→ 一条命令 init → 建书（经 CLI）→ 布局断言（beta 判据「Windows 中文路径全链路」的 M5 补全）
D2 finalize→next 端到端经 CLI（子进程 spawn bin，非进程内调用）跑通：细纲→草稿→机检→审稿→定稿→next 报下一章

Acceptance Criteria

AC1 干净 Windows 中文用户名环境一条命令装出工作目录并建第一本书：CI 用例绿（npm pack 产物 + 中文路径临时目录全链路）+ 手测一次通过 —— CI 半已达成（run 28663338317 双平台 install-e2e 绿）；余用户手测
AC2 init 装出的布局逐项存在且内容正确：AGENTS.md（标记块）、.webnovel/（脚本可 node 直跑、books.jsonl、哈希清单）、检测到的平台壳；报告输出含支持等级与下一步指引
AC3 update：未改文件被更新；手改文件被跳过且列出；AGENTS.md 块外内容保留；--force 可覆盖
AC4 写章八阶段每一步都有宿主可调 CLI 通道：F1 清单 8 个命令逐个有测试（含 schema 校验失败、文件缺失的人话报错）
AC5 finalize→next 端到端经 CLI 子进程跑通，next 报「起草第 N+1 章」不重抄
AC6 工作目录定位三分支（书仓库直启 / 工作目录+当前书 / 无处可依）各有测试；换书后 next 作用于新书
AC7 SessionStart 注入：hook 路径与无 hook 宿主状态机入口路径输出逐字一致（既有测试延伸到 CLI 通道）
AC8 全量测试绿 + CI 双平台绿；drift check 对新增模板变量仍确定性通过 —— 335 绿；run 28663338317 六 job 全绿（4 测试矩阵 + 2 install-e2e）

Out of Scope

真实 npm 发布——「一条命令」验收用 npm pack 产物在 CI/手测模拟（与 npx 消费同一份包内容），真发 alpha 推迟 beta 入口：alpha 阶段没有外部用户，提前发包只引来不完整版本的使用（决策 D-1，start 评审可推翻）。随之推迟的发版联动：升 7.0.0、README 版本表 / marketplace / CHANGELOG 同步（版本 CI 不查 v7/package.json，保持 7.0.0-alpha 无风险）
真模型 smoke（Claude Code / Codex 亲测）——推迟 beta（registry 已记 deferred-beta），M5 只负责让它可行
M5.5 体检统计项（高频意象/句式/文体指纹）
M6 自动模式、M7 导出与 /migrate
二级宿主（gemini-cli / cursor）的实测核验——壳照常生成，支持等级按 registry 如实标注

规划决策（用户暂离，按推荐采纳；start 评审时可推翻）

D-1 发布形态：npm pack 模拟，真发推迟 beta（见 Out of Scope 首条）
D-2 检测缺省：init 未检测到任何 agent CLI → 只装公约数层（AGENTS.md + .webnovel/）并在报告指引 --hosts 补装——忠于 spec「按检测生成」，不掩盖探测失败
D-3 任务结构：单任务推进，沿 M1-M4 先例；三块交付物（基座与多本书 / F1 缝 / 安装器）在 implement.md 里按依赖序分步、分批 commit，可独立回滚

prd.md 9.0 KB Histórico Raw