系统操作手册生成及排版（wwlia-system-manual-gen）

一、适用范围

把"正在运行的系统"转换为一份可交付的 Word 用户操作手册：真实页面截图 + 模块说明文字 + 标准排版（封面 / 目录 / 页眉 / 章节 / 居中截图）。

适用：内部系统、原型系统、交付物手册、软著/验收附带的用户手册。不追求美术级设计，追求「像参考样例一样规范、有真实目录、可直接打印交付」。

> 排版基调（用户硬性要求）：全文黑色、正文/表头/图注一律不打斜体、微软雅黑、A4。

〇、随附资源（已打包进 skill 的 assets/ 目录）

skill 自带可直接运行的脚本，别人装上即用，无需自备：
- assets/cdp_browser.py：零依赖 CDP 驱动（纯 Python 标准库，跨平台），截图阶段自动引用，不再依赖项目外的 jzsc_crawler。
- assets/capture.py：截图脚本（跨平台浏览器探测 + 远程地址 + 手动登录模式）。
- assets/final_capture.py：已登录复用截图脚本——遍历 CDP 实例所有标签页，复用第一个含 .el-menu 的已登录标签页直接截图，跳过登录流程。适用于：已有会话、用户已手动登录、手动登录检测超时后的兜底。
- assets/build_manual.py：Word 生成器（配置驱动 + 首次自动安装 python-docx/matplotlib，默认源失败自动回退清华镜像），手册末尾自动生成「拓扑图」大章节（按 TOPOLOGY 配置用 matplotlib 绘制系统部署拓扑图并居中插入）。

> 用到时把 assets/ 整个目录复制到你的项目（如 temp/），按需改 build_manual.py 顶部的 CONFIG/MODULE_GROUPS/SECTIONS 即可。

跨平台 / 零环境说明（重要）

• 本机无需装 Python：通过 WorkBuddy 使用时，AI 用其自带的受管 Python 运行脚本；build_manual.py 会在缺少 python-docx 时首次自动安装。
• 无需安装特定浏览器：capture.py 自动探测 Chrome / Edge（Windows / macOS / Linux 均支持），也可用 --browser 或环境变量 MANUAL_BROWSER 指定，或 MANUAL_BASE 指定目标地址。
• 系统不在本机也行：--base https://你的地址 指向任意可达的远程/内网系统（浏览器仍本地跑，只截远程页面）。
• Mac / Linux 可用：已去除 Windows 专属的 STARTUPINFO / creationflags，启动方式按 OS 自动切换。
• 有验证码且无权改库/Redis：用 --manual-login，浏览器窗口置前由人工登录，登录成功后自动继续截图。

二、整体工作流（两步法）

步骤1 截图阶段：操纵浏览器(CDP) → 登录系统 → 逐菜单导航 → 截取每个模块页面 PNG
步骤2 排版阶段：python-docx 把 截图+文案 排成 Word（封面/真实TOC域/两段式页眉/居中截图）
步骤3 独立核验：读 document.xml 核对 TOC域/无蓝标题/两段section/页眉结构
步骤4 交付：present_files 打开 .docx，并提醒用户"目录需 F9/右键更新域才出页码"

• 两个阶段可独立重跑：UI 改了只重跑步骤1+2；排版调字号只重跑步骤2。
• 不要轻信"成功"提示或 completed 通知，必须做步骤3 的独立核验。

三、第一步：截图自动化（通用方法）

3.1 驱动选择（零依赖优先）

• 用 skill 自带、已打包的 assets/cdp_browser.py（纯 Python 标准库实现 CDP，跨平台，不再依赖项目外的 jzsc_crawler）。
• 用 Chrome / Edge 任一款。capture.py 会自动探测本机浏览器；也可 --browser PATH 或环境变量 MANUAL_BROWSER 指定。

3.2 登录方式（三选一）

• 自动登录（需关闭验证码）：临时把登录验证码开关关掉（UPDATE sys_config SET config_value='false' WHERE config_key='sys.account.captchaEnabled'; 并清 Redis 缓存），完成后务必恢复 true 并再清缓存；随后 capture.py capture --code X 用固定管理员账号自动登录。
• 手动登录（推荐用于远程/无权改库的系统）：capture.py capture --manual-login。脚本把浏览器窗口置前，由人工在页面上登录，检测到登录成功（默认出现 .el-menu 侧边栏）后自动继续截图。适用于有验证码、且你无权改库/Redis 的远程系统。
• 检测条件只依赖侧边栏选择器（.el-menu 等），不要附加"页面含『退出』文字"条件——RuoYi 等 el-dropdown 主题下"退出登录"在未展开的下拉里，innerText 不含"退出"二字，会永远超时（实战踩坑：等待 10 分钟未检出）。
• 已登录复用（登录态已在/用户已手动登录）：python final_capture.py --base URL --modules modules.json。遍历 CDP 实例所有 page 标签页，复用第一个含 .el-menu 的标签页直接开始截图，跳过登录等待。适合：用户已登录、--manual-login 超时后的兜底、浏览器 profile 已有会话。

3.3 逐模块截图要点

• 维护一个 modules 清单（截图文件名 / 菜单名 / 父菜单名）。用 --modules modules.json 传入（[[fname, label, parent], ...]）；不传则用脚本内置示例。
• 每个模块：点击菜单 → 等待路由真正跳转（location.pathname 变化） → 等页面渲染 → 截图。
• 截图尺寸统一（1440×900 视口），输出到 shots/，文件名与 modules 一一对应。

3.4 截图命令示例

# 远程系统 + 手动登录（最省事，无需碰数据库）
python capture.py init --base https://wms.example.com/
python capture.py capture --manual-login --base https://wms.example.com/ \
       --modules modules.json --wait-selector ".el-menu"

# 本机系统 + 自动登录（已临时关闭验证码）
python capture.py init --base http://localhost/
python capture.py capture --code 8 --base http://localhost/ --modules modules.json

# 已登录复用（用户已手动登录 / 手动登录超时兜底）——直接开始截图
python final_capture.py --base http://localhost/ --modules modules.json

3.5 截图阶段常见坑

• 登录页截成首页：浏览器 profile 残留上次会话 Cookie。删掉 profile/ 目录或在 CDP 里 Network.clearBrowserCookies 后再导航。
• 截到上一个模块的界面：Vue Router 等前端路由是异步的，截图前必须等 location.pathname 变化，否则时序错位。
• 截图里是旧系统名：前端在 dev server 启动时就把 .env 的标题烤进去了，改 .env 后必须重启前端。
• 后端没起来：若验证码/首页接口返回 HTML 而非 JSON，说明后端未就绪，等它起来再截。
• Mac/Linux 找不到浏览器：capture.py 已按 OS 探测常见路径；若装在非标准位置，用 --browser /绝对路径/浏览器 指定。
• 别指望 AI 读图识别 RuoYi 算术验证码：验证码图片小、带干扰，AI 视觉读算式极易出错（实战：AI 读出 6*7=42，被后端 Redis 校验拒绝返回"验证码错误"）。优先用 --manual-login（人工登录一次）或关闭验证码；不要把 --code + AI 读图当默认路径。
• --manual-login 等待超时但用户其实已登录：检测条件若附加了"退出"文字（旧版）在 el-dropdown 主题下会误判未登录。改用 final_capture.py 复用已登录标签页，或把检测条件改为仅 .el-menu。

四、第二步：Word 排版规范（参照《图智…用户操作手册》风格）

典型章节结构（按系统实际菜单调整；FAQ 按需添加，用户不要求就别加）

封面（系统名 + 副标题 + 公司名）
目录（Heading1 "目录" + 真实 TOC 域）→ 分页
1、系统概述（1.1 系统简介 / 1.2 核心功能架构 / 1.3 运行环境）
2、系统登录与退出（2.1 登录 / 2.2 系统首页 / 2.3 退出）
4、仓储管理（主数据）    ← 业务域 H1（由 MODULE_GROUPS 自动生成）
  4.1 仓库管理 / 4.2 库区管理 / ...
5、作业管理（出入库移库）
6、库存管理（批次/序列/策略）
7、盘点与预警
8、统计分析（报表/KPI/接口日志）
9、设备调度与集成
10、系统管理（基础配置）
11、系统监控
12、拓扑图（自动追加：H1「拓扑图」+ 按 TOPOLOGY 绘制的系统部署拓扑图）
（13、常见问题 —— 可选，默认不加）

五、生成器实现要点（python-docx）

受管 venv 里安装："$VENV/Scripts/pip.exe" install python-docx（Windows 用 Scripts/ 不是 bin/）。build_manual.py 已内置 ensure_docx()，首次运行自动安装 python-docx，默认源失败会自动回退清华镜像（-i https://pypi.tuna.tsinghua.edu.cn/simple），换机无需手动。

关键函数（建议封装）：
- set_font(run, ea="微软雅黑", color=BLACK, size=None, bold=None)：同时设 run.font.name + run._element.rPr.rFonts（ascii/hAnsi/eastAsia 都设）+ run.font.color.rgb=RGBColor(0,0,0) + run.italic=False。
- add_toc_field(doc)：插入 TOC \o "1-3" \h \u 的 fldChar 四段式（begin / instrText / separate / end）。
- add_cover(doc, sys_name, subtitle, company)：压缩空行保证单页封面。
- setup_cover_section(doc)：段1 w:titlePg，封面 first 页眉留空、目录 default 页眉仅横线。
- start_body_section(doc)：doc.add_section(WD_SECTION.NEW_PAGE) → 移除 w:titlePg → 注入 <w:pgNumType fmt=decimal start=1/> → 用无边框两列表格做 default 页眉（左系统名 + 右 PAGE 域）。
- add_body(doc, *texts, bold=False)：正文段落。必须用 *texts 可变参数，add_body(doc,'第一段','第二段') 会依次写入多个 run；切勿保留 (doc, text, bold=False) 旧签名——它会把第二个位置参当成 bold 吃掉，导致第二段文字丢失不显示。所有正文统一 12pt、行距 1.15、first_line_indent = Pt(24) 首行缩进两字、全文黑色不斜体。
- 各模块文案集中在 MODULES（每条 = (小节标题, 截图文件名, 模块名, 功能说明, 常用字段)），改文字/加模块只动该列表；build() 为它们统一生成一个 H1「业务管理」+ 多个 H2 小节。
- TOPOLOGY：系统拓扑图配置（layers = 各层及节点、links = 节点间连线及标注），build() 在手册末尾自动追加「拓扑图」大章节：H1 编号自动接续业务模块，正文用 TOPOLOGY["desc"]，再用 matplotlib 绘制拓扑图（白底黑字、分层盒式）居中插入。生成失败不阻断手册，会在该处插入说明文字。
- 业务模块与拓扑图章节的 H1 编号自动接续（取 SECTIONS 中最大手写编号 +1），不再写死「4、业务管理」。
- 全文默认黑色、不斜体；标题必须逐 run 显式覆盖成黑色，否则呈蓝。

六、独立核验清单（交付前必做）

用 zipfile 读生成后的 word/document.xml 与 word/header*.xml：
- document.xml 含 TOC \o "1-3" \h \u、微软雅黑（大量）、无 4F81BD/365F91/1F3B57 等蓝色值、无真斜体。
- 核验斜体的正则陷阱：document.xml 里有大量以 w:i 开头的元素（<w:ind>、<w:imgData>、<w:insideH>、<w:insideV>），简单正则 <w:i[ >] 会把它们误判成斜体。必须精确匹配 rPr 内独立的 <w:i/> / <w:i w:val="..."/>（Word 斜体就是这样的自闭合元素）。
- sectPr 至少 2 个；段2（正文）无 w:titlePg 且含 <w:pgNumType w:fmt="decimal" w:start="1"/>。
- header1.xml（封面 first 页眉）留空；header2.xml（目录）仅底部横线无文字；header3.xml（正文）无边框两列表格（左系统名 + 右 PAGE 域）。
- 公司名段落在第一个 inline sectPr 之前（封面第 1 页内）。
- python-docx 打开能列出 目录、1、系统概述…及全部业务小节标题；截图全部嵌入（word/_rels/document.xml.rels 中 image 关系数 ≥ 截图数）。
- 用 WPS/Word 打开，右键目录→更新域，确认页码正常出现（这是验证 TOC 域有效的唯一办法）。

七、常见坑（必读）

• TOC 不显示页码：正常。真实 TOC 域是结果缓存，python-docx 算不出页码；必须在 Word/WPS 打开后更新域。不要硬拼目录文本。
• 标题变蓝色：python-docx 默认 Heading 样式自带蓝色，必须给每个标题 run 显式设 w:color val=000000。
• 正文第二段文字丢失：add_body(doc,'A','B') 若签名是 (doc, text, bold=False)，B 会被当作 bold 参数吞掉、不显示。统一用 *texts 可变参数签名即可根治。
• 封面公司名跑到第 2 页：封面空行太多。压缩为"系统名前3/与副标题间3/与公司名间5"行。
• 正文第一页没有页眉：doc.add_section() 会复制上一节属性，段2 必须先移除 w:titlePg，否则沿用空白 first 页眉。
• 页码不贴最右：用「100% 宽两列表格 + 右格 right 对齐」而非 tab 制表位，后者依赖精确文本宽度易错位。
• 字体不生效：中文必须同时设 ascii/hAnsi/eastAsia。

八、配置参数（按项目替换）

本 skill 是 AI 操作指南，没有"填表"界面。需要提供的输入写在两个脚本里，换项目时改这两处即可：

① build_manual.py 顶部（生成阶段）—— 用编辑器或告诉 AI 改：
- CONFIG：系统名、版本、副标题、公司名、账号说明、访问地址（封面/页眉/运行环境用）。
- MODULES：业务模块清单（每条 = 小节标题 / 截图文件名 / 模块名 / 功能说明 / 常用字段），统一生成「业务管理」H1 + 各模块 H2 小节。
- SECTIONS：正文结构自由编排（h1/h2/正文/截图/要点），手册开头那段（系统概述、拓扑、登录等）都在这里。FAQ/问答按需添加，用户不要求就别加（实战偏好：用户明确要求"不要加问答"）。

② capture.py / final_capture.py 命令行参数（截图阶段）：
- --base URL 或环境变量 MANUAL_BASE：目标系统地址（默认 http://localhost/，可填远程/内网地址）。
- --browser PATH 或 MANUAL_BROWSER：指定浏览器（默认自动探测 Chrome/Edge）。
- --manual-login：手动登录模式（有验证码且无权改库时用）。
- --modules modules.json：模块清单 JSON（默认用内置示例）。
- --code X：自动登录时的验证码计算结果（仅非手动模式需要）。
- final_capture.py --target ID：可指定复用某个标签页 ID。

> 换项目流程：把 assets/ 复制到项目 → 改 build_manual.py 的 CONFIG/TOPOLOGY/MODULES/SECTIONS →（系统开着的话）跑 capture.py 截图（或 final_capture.py 复用已登录）→ 跑 build_manual.py 出 docx。所有脚本已去除对 具体项目/本机的硬编码依赖。

九、触发与交付

• 用户说"出操作手册/生成系统操作手册/把功能截成图做手册"即加载本 skill。
• 完成后 present_files 打开 .docx，并明确提醒：目录需在 Word/WPS 中右键→更新域（或 F9）才显示带页码目录。