编写操作手册（writing-manual）¶

目标：根据用户指定的 SRS（必填），产出带截图的场景级操作手册，落盘到 {workspace}/{软件}.application/help/。可选：在 help 根目录安装 VitePress 并编译静态 HTML（help/dist/）。

主流程三阶段：写 demo-case → 按 run-testcase 执行取图 → 组装手册；阶段 4（VitePress HTML）可选，须单独询问后才执行。本技能**不**落盘业务 XML，**不**内嵌 DOM 注入脚本。

模板：demo-case-template.md、manual-template.md；VitePress 模板：vitepress-template/；示例：examples.md。

REQUIRED SUB-SKILL： 阶段 2 必须按 run-testcase 执行（门禁、USER.md、注入、弹层闭环、人工协助）。

何时触发¶

用户要写操作手册 / 用户手册 / help 文档 / 带截图帮助
提供 SRS 路径并要求出演示说明
要求把手册编译成 HTML / 安装 VitePress
/writing-manual

输入¶

来源	规则
SRS 路径	必填；未提供则先问，禁止进入阶段 1
`PLAN.md` / `DATABASE_SCHEMA.md`	存在则作补充；冲突以 SRS 为准
软件目录	从 SRS/路径/`*.application` 推断；多个候选则编号选项询问；仍不清则先问英文 name 或完整 `.application` 路径

产出目录¶

{workspace}/{软件}.application/help/
├── demo-case/
│   ├── 00-overview.md
│   └── 场景-{名称}.md
├── 场景-{名称}.md
├── 场景-{名称}/stepNN.png
├── index.md
├── package.json                 # 仅阶段 4 确认后写入
├── .gitignore
├── .vitepress/
│   └── config.mts
├── node_modules/                # npm install；勿提交（.gitignore）
└── dist/                        # vitepress build 静态 HTML（可预览/发布）

执行原始产物：{workspace}/test-results/{yyyyMMdd-HHmmss}/（由 run-testcase 写入）。

工作流（门禁）¶

【阶段 0】SRS 必填 + 定位 .application
【阶段 1】写 help/demo-case/（参考 writing-testcase；主路径+关键变体）
         → overview →【门禁】确认场景清单 → 场景-*.md
【阶段 2】按 run-testcase 执行 demo-case → test-results/
【阶段 3】复制截图 + 写 help/场景-*.md + index.md →【门禁】询问是否生成静态 HTML
【阶段 4】（可选）用户确认后：在 help/ 安装 VitePress 并 build → help/dist/

硬规则： 未完成阶段 1 场景确认禁止进入阶段 2 执行；未完成阶段 2（或用户显式跳过）禁止假装有新截图；未获用户对阶段 4 的明确确认前，禁止 npm install / VitePress 落盘 / docs:build / 宣称已产出 HTML。

阶段 0 — 输入门禁¶

无 SRS 路径：停，请用户提供
解析软件名 → {workspace}/{软件}.application/；不存在或多个候选：停，编号选项询问
可选读取同树 PLAN/SCHEMA

未完成阶段 0 禁止写入 help/。

阶段 1 — 写 demo-case¶

参考 writing-testcase 的场景拆分与可执行步骤写法；覆盖降为演示向：

每场景至少 1 条主路径；可加关键变体（如驳回再提交）
**不含**完整异常/权限矩阵
编号 DC-{缩写}-{三位序号}；字段见 demo-case-template.md
必须填写「截图点」

门禁：

写 help/demo-case/00-overview.md（场景清单可勾选）
停：用户勾选/增删并确认（编号选项）
仅为已确认场景写 场景-*.md，回写索引
用户明确「跳过确认、全部生成」时可一次落盘（仍须已完成阶段 0）

未确认场景清单前禁止写 场景-*.md。

阶段 2 — 执行（REQUIRED：run-testcase）¶

将 help/demo-case/ 作为用例输入，完整遵循 run-testcase：

编排映射：demo-case「预期界面」→ 断言依据（等同 testcase「预期结果」）；「演示数据」→ 测试数据；「截图点」列出的步骤在 PASS 时也必须截图
Playwright MCP → HOST → USER.md → 执行清单 → 失败策略（一问一答，不得打包）
注入与 catalog、弹层闭环、人工协助：全部按 run-testcase
结果写入 {workspace}/test-results/{runId}/
不修改 demo-case Markdown 正文

跳过执行（须显式选择，编号选项）：

完整三阶段（默认）— 执行取图后组装手册（阶段 3 结束后再单独问是否 HTML）
仅用已有 test-results/{runId} — 用户给出路径后进入阶段 3
先只写 demo-case — 本轮停在阶段 1 结束后

阶段 3 — 组装手册¶

按场景写 help/场景-{名称}.md（模板 manual-template.md；语气面向终端用户）
截图映射（硬规则）：
源：test-results/.../screenshots/DC-…-step{N}-….png
目标：help/场景-{名称}/step{两位序号}.png
主路径占用连续 step；变体接后或放「扩展」小节
缺图写「（截图缺失）」并在 index 标注；**禁止**用无关旧图凑数
写/更新 help/index.md（含软件名、SRS、runId、场景表与完成状态）
执行 FAIL 的场景标「部分完成」
停：单独询问是否进入阶段 4（VitePress 静态 HTML）；**不得**在同一条回复里默认开做

手册 Markdown 约定（若后续做 VitePress 则沿用）：

首页必须为 help/index.md（VitePress 根路由 /）
配图相对路径保持 场景-{名称}/stepNN.png（与 md 同级目录）
demo-case/ 仅供执行，**不要**当作站点正文导航（阶段 4 srcExclude）

阶段 4 — VitePress 安装与 HTML 构建（可选 · 须询问）¶

默认不执行。 仅当用户在阶段 3 结束后的编号选项中选择「生成静态 HTML」后，才可安装依赖并 build。

在 {软件}.application/help/ 根目录完成本地站点，**不要**把 VitePress 装到 workspace 根或其它应用目录。

4.1 落盘工程文件¶

若 help/package.json 尚不存在，从技能模板复制并改写：

源（技能内）	目标
vitepress-template/package.json	`help/package.json`（可改 `name`；`docs:build` 含后处理）
vitepress-template/config.mts	`help/.vitepress/config.mts`
vitepress-template/fix-relative-paths.mjs	`help/scripts/fix-relative-paths.mjs`
vitepress-template/gitignore	`help/.gitignore`

config.mts **必须**按本次手册填写：

title / description：软件显示名 +「操作手册」
相对路径约定：base: './' + mpa: true，outDir: './dist'，cleanUrls: false
vite.experimental.renderBuiltUrl 返回 { relative: true }
docs:build：vitepress build && node scripts/fix-relative-paths.mjs（扫掉残留 /assets/）
导航 link 在 config 中仍写 /index.html、/场景-{名称}.html（产物为 ./…）
srcExclude：至少排除 **/demo-case/**、**/node_modules/**、**/dist/**
themeConfig.sidebar：与 index.md 场景表一致；MPA 下可不启用本地搜索
预览：npm run docs:preview / http-server dist；或 http-server . 打开 /dist/（相对路径会落到 /dist/assets/）
**不要**用 vitepress preview；勿期望绝对 /assets 在 http-server . 下可用
build 后抽查：dist/index.html 资源为 ./assets/…，无裸 /assets/…

已存在配置时：更新 sidebar 与 title；缺后处理脚本则从模板补齐。

4.2 安装与构建¶

在 help/ 下执行（PowerShell）：

Set-Location "{workspace}/{软件}.application/help"
npm install
npm run docs:build

成功标准：

存在 help/dist/index.html，资源为相对路径 ./assets/…
npm run docs:preview 或 http-server dist（或 http-server . + /dist/）可打开首页与截图
将预览方式与 URL 回报用户

4.3 失败处理¶

情况	处理
无 Node/npm	停；请用户安装 Node 18+ 后重试阶段 4
`npm install` / `build` 失败	根据日志修复 config/依赖后重跑；不得删业务手册 md 凑数
仅缺 sidebar	按 `index.md` 场景表补全后重新 build
用户选择不生成 HTML	跳过阶段 4；index 可不提 dist，或注明「未构建 HTML」
首页可开但资源 404	确认产物为 `./assets/…` 且已跑后处理；预览根为 `dist`，或用相对路径打开 `/dist/`
仍见裸 `/assets/`	检查 `docs:build` 是否含 `fix-relative-paths`；硬刷新
字体 preload 警告	多为未立即使用 Inter 的控制台噪音，可忽略

4.4 抽查¶

构建成功后请用户抽查：npm run docs:preview → 打开本地 URL，核对导航、场景文、截图。

逐项询问（硬规则）¶

与 run-testcase 相同：一问一答；可选项用 1. 2. 3.；默认项标注「（默认）」。

阶段 0/⅓ 典型问题（每次只问一个）：

SRS（若缺失）：

请提供 SRS 文件路径（必填）。

软件目录（多个候选时）：

请选择目标软件目录：
1. {pathA}
2. {pathB}
请回复选项编号。

场景清单：

请选择本次纳入手册的场景：
1. 全部清单场景（默认）
2. 自定义（回复 2 并写出场景名或编号）
请回复选项编号。

是否执行（阶段 1 完成后）：

请选择下一步：
1. 完整三阶段：按 run-testcase 执行取图并组装手册（默认）
2. 仅用已有 test-results（回复 2 并附 runId 或路径）
3. 先只写 demo-case，本轮不执行
请回复选项编号。

是否生成静态 HTML（阶段 3 完成后，本轮只问这一项）：

手册 Markdown 已组装完成。是否用 VitePress 生成静态 HTML（help/dist/）？
1. 不生成（默认）
2. 生成：在 help/ 安装 VitePress 并 docs:build
请回复选项编号。

规则：

用户未回答或只说「好的/继续」而未选编号时，按默认 不生成
用户在更早对话中已明确要求「编译 HTML / VitePress」可视为对阶段 4 的确认，仍建议在阶段 3 结束用编号选项复核一次
**禁止**把「是否生成 HTML」与 HOST / 清单 / 失败策略打包装问

阶段 2 内 HOST / USER / 清单 / 失败策略：完全按 run-testcase 提问格式，不在此重复发明。

错误处理¶

情况	处理
SRS 缺失/不可读	停；请用户提供路径
无法定位 `.application`	停；请用户指定
执行 FAIL	按 run-testcase 失败策略；组装标「部分完成」
跳过执行且无历史截图	可写无图稿；index 标缺图；不得宣称配图齐全
弹层/选择器问题	交给 run-testcase「人工协助」
VitePress 构建失败	见阶段 4.3；不得伪称已产出 HTML

与上下游¶

SRS
  → writing-manual 阶段1 → help/demo-case/
  → writing-manual 阶段2 →【run-testcase】→ test-results/
  → writing-manual 阶段3 → help/场景-*.md + 场景-*/stepNN.png + index.md
  →【询问】是否生成静态 HTML
       ├─ 否（默认）→ 结束 / 请用户抽查 Markdown
       └─ 是 → 阶段4 → help/ VitePress → help/dist/*.html

技能	关系
`writing-testcase`	写法参考；本技能产出演示向 DC，非完整 QA
`run-testcase`	阶段 2 REQUIRED 编排调用

不做¶

业务 XML；完整 QA 用例集；第二套 DOM 注入；技能库存真实密码
把 VitePress 安装到 workspace 根或其它 .application（仅限当前软件的 help/）
将 demo-case/ 编入用户手册站点导航