作战地图生成器（battlemap-generator）
把「内容（map.json）」+"固定设计系统/引擎" → 渲染成单文件可交互 HTML 作战地图。
设计系统 CSS 与交互引擎 JS 已固定（与既有 DRP/司库/灵基地图 100% 同源），本技能只负责内容结构化 + 渲染。
> 🚀 30 秒拿到你的作战地图（复制即跑，无需读全文）：
> 1. 看成品：直接双击打开 assets/demo-作战地图.html（电子高科技富设计范例，离线可交互，什么也不用装）。
> 2. 生成自己的：复制 assets/build_industry.py → 只改数据段 FLY_OUTER / INNER / SUPPORT → 跑 python assets/build_industry.py -o <主题>作战地图.html。
> 3. 交付前自检：python assets/selfcheck.py <主题>作战地图.html（五轴 R/A/L/O/S + 逐页差异化 D 闸门全绿才交付）。
> 命令里的 python3 在 Windows 上通常写作 python；脚本零第三方依赖，系统 Python 3.8+ 即可直接跑，不绑定任何安装路径。
> 想一眼看全所有脚本与命令 → 见下方「命令速查表（覆盖全部 8 个脚本）」。
何时触发
- 用户要新建一份作战地图（新产品/新行业/新区域）。
- 用户已有作战内容（文档/要点/访谈记录），想生成网页版。
- 用户说「像 DRP/司库/灵基 那样做一张作战地图」。
触发示例（你可以这样说，照抄即可开始）
- 新建地图：「帮我把 XX 产品做成一张作战地图」「给 XX 行业做一张 2026 年作战地图」。
- 复用参照：「像 DRP/司库/灵基那张图一样，给 XX 做一张」——会自动复用同款设计系统。
- 资料转化：「这是一份 XX 的作战材料/旧地图（文件），帮我做成网页版」——进入资料转化模式，自动萃取内容。
- 迭代已有：「在上一张地图里加一个竞品模块」「把区域清单换成广东省」——改 map.json / 数据段后重生成即可。
- 只想先看看：「先给我看个作战地图长什么样」——直接打开插件自带的
assets/demo-作战地图.html预览成品，无需生成。 - 只要小样：「先出一张精简版看看效果」——给最小骨架默认渲染，之后按模块逐步加内容。
> 接到以上任一类请求后，第一步永远是「轻量三问」（行业主题 / 有无现成材料 / 全量还是精简，见「交互复杂度治理」段），然后按工作流走。触发条件以本节为唯一事实源，其他文档只引用、不重复维护。
对话式上手示范（轻量三问 → 出图，全程 3 轮）
照着下面这样聊就能开始，不需要先读任何文档：
> 用户：帮我把「灵基」做成一张 2026 作战地图。
> 顾问（第 1 问 · 定位）：这张图是给内部销售团队打市场用，还是对外汇报/演示用？
> 用户：内部销售用。
> 顾问（第 2 问 · 材料）：手头有没有现成材料（打法文档 / 旧地图 / 要点清单）？有就直接发我；没有的话我按方法论逐模块带你过一遍。
> 用户：有一份打法要点，发你了。
> 顾问（第 3 问 · 体量）：要全量版（约 15 个模块、逐页深链）还是精简版（先出核心 6 模块小样）？
> 用户：先精简版。
> 顾问：→ 复制富设计模板改数据段 → 生成 灵基作战地图.html → 跑 selfcheck.py 五轴自检 → 交付精简版（后续可随时增量加模块）。
30 秒上手路线图（新用户按此顺序读，不迷路）
本技能目录文件较多，按下面的顺序只读需要的部分即可：
1. 先看成品长什么样（不用跑任何命令）：直接双击打开 assets/demo-作战地图.html（电子高科技富设计成品，224KB，可离线、可交互）——这就是最终交付物的样子；另附 assets/生命科学作战地图.html 可对照第二个行业实例。
2. 再理解内容结构（约 5 分钟）：读 assets/demo-map.json（简化示例）+ references/schema.md（JSON 字段与区块类型说明），明白「一张地图 = meta + modules」。
3. 然后开始建图（实战路径）：新主题默认复制 assets/build_industry.py → 只改内容数据段 → -o <主题>作战地图.html 重生成；再跑 assets/selfcheck.py 过五轴闸门（见工作流第 4 步）。
4. 按需查阅（不必通读）：references/methodology.md（访谈提纲与方法论）在访谈时查；「视觉组件库」「视觉安全规范」在写内容数据时查；「FAQ · 常见报错速查」在报错时查；「反模式禁止清单」在交付前对照。
📑 按目标查文档（导航索引 · 想做什么直接看哪段）
| 你想… | 直接看 |
|---|---|
| 快速出一张图 | 顶部「🚀 30 秒」TL;DR 或下方「命令速查表」 |
| 一眼看全所有脚本用法 | 「命令速查表（覆盖全部 8 个脚本）」 |
| 写 / 改地图内容 | references/schema.md（字段）+ assets/demo-map.json（示例） |
| 访谈萃取内容 | references/methodology.md + references/best-practices.md |
| 理解门禁 / 评分细则 | references/quality-gates-and-workflow.md（开头有目录，可跳读） |
| 排查报错 | 下方「系统级错误码速查」+「FAQ · 常见报错速查」 |
| 看成品长什么样 | 双击 assets/demo-作战地图.html，无需运行任何命令 |
能力边界（能做 / 不做）
能做：
- 把产品/行业/区域的作战内容渲染为单文件、可离线、数据驱动的交互式 HTML（搜索/页码/打印/深链齐全）。
- 按总部 WHY→WHAT→HOW+支撑/AI 方法论逐模块访谈、结构化内容、渲染、自检交付。
- 从既有文档/旧地图/要点清单萃取内容生成网页（资料转化模式）。
- 对已有地图做增量迭代（加/减模块、换区域、改数据后重生成）。
不做：
- 不手写 HTML/CSS/JS——设计系统与引擎已固定，只改内容数据（map.json 或渲染脚本数据段）。
- 不做实时联网数据看板——产出是静态单文件，无后端、无数据库，数据更新靠改源数据重生成。
- 不编造数据——量化数字/政策文号/客户成效必须可溯源，查不到只能标「未找到公开来源」，不会替你填数。
- 不跳过访谈直接出正式交付物——内容必须来自真实访谈或用户材料（模拟占位需显式标注）。
- 不做多文件工程/部署——只交付单文件 HTML；若要挂到线上，由用户自行托管。
命令速查表（覆盖全部 8 个脚本 · 想了解所有用法只看这一张）
| 命令（在技能根目录运行） | 做什么 | 什么时候用 |
|---|---|---|
python assets/build_industry.py -o <主题>作战地图.html |
用富设计模板生成作战地图（新主题默认） | 新行业/新产品，要 demo 同款富设计；改数据段即可，不碰 HTML |
python assets/build_map.py map.json -o 输出.html |
用 map.json 数据驱动生成（通用模式） |
已有结构化 map.json，或要纯数据维护、可版本管理 |
python assets/build_life.py -o 生命科学作战地图.html |
生命科学行业模板直接出图 | 医药/生命科学行业，拿模板改数据段即可 |
python assets/selfcheck.py 输出.html [--json] [-o report.md] |
五轴 + 差异化 D 机器化终检（R≥95/A≥85/L≥82/O≥80/S≥75 才 PASS） | 渲染后、交付前必跑；不达标回炉重跑 |
python assets/visual_guard.py 输出.html |
视觉安全体检（横向溢出/卡片超长/宽表/固定像素宽） | 交付前兜底体检，或与 selfcheck 配合 |
python assets/build_index.py |
从作战图解析「深度案例库 + 区域目标清单」生成客户-方案-产品线对照索引 | 需要交叉索引成品时 |
python assets/enrich_life.py |
给生命科学图补强内容密度 | 迭代生命科学图、过自检发现丰富度不足时 |
python assets/fix_dup_actions.py |
修复重复行动项 | 自检报「行动项重复」时一键去重 |
数据骨架：templates/theme-template-map.json / assets/demo-map.json |
通用模式起步骨架 / schema 教程 | 写 map.json 时对照字段与区块类型 |
> 所有脚本均离线运行、零网络依赖、不向外发送任何数据；文件/编码/JSON 出错会打印「❌ 原因 + 👉 怎么修」后干净退出，不会抛出技术栈。脚本执行细节见 references/quality-gates-and-workflow.md。
工作流（交互式访谈 → 生成，符合用户已确认的需求）
- 确认范围（必须交互式，禁止凭假设自动生成）：用
references/methodology.md的访谈提纲，按模块逐块追问（或请用户直接给素材）。正式交付前必须先走模块访谈、由用户确认内容——严禁跳过访谈、直接凭自身假设灌出一整张 map.json。若访谈/素材尚未到位但需先出雏形，只能用"推荐默认占位"并明确告知用户"此为模拟/默认占位、待访谈确认后替换"，不得冒充正式交付。
- 先确认要哪些模块（标准骨架必选 + 可选模块按需启停）。
- 内容纪律：量化数据/政策文号/客户成效必须可溯源，查不到标注「未找到公开来源」，严禁编造。 - 产出 map.json：严格按
references/schema.md的结构，把访谈/素材写成 JSON。
- 设计系统/引擎不要改；只填meta与modules。视觉调优范围铁律：整体输出样式保持不变，只调内容区内部视觉（标题层次 / 结论段 / 卡片节奏 / 栅格留白 / 列表·引用行高 / 标签节奏），改配色、改飞轮、改导航、改 pane 结构、改版式框架、另起设计系统均禁止——这些靠design.css视觉精修块在内容层统一生效。
- 未覆盖的特殊结构用{"type":"raw","html":"..."}兜底，保证不失真。 - 渲染：
bash python "<技能目录>/assets/build_map.py" map.json -o 输出.html
用python3（Windows 通常为python）；系统 Python 3.8+ 即可，脚本零第三方依赖。 - 结构/UX 子门禁 + 自查：渲染后强制跑「输出前质量门禁」的渲染子集——pane 数 = 模块数且导航一一对应、无错位；飞轮/搜索/打印/页码按 features 出现；视觉与既有地图 100% 同源（必须用已验证精修设计系统，禁止朴素默认）、无外部依赖、可离线打开；桌面与移动端可读；交叉链接
data-goto无死链、各 nav 对应 pane 非空。飞轮动态对齐子项（新增）：作战飞轮必须数据源驱动、覆盖全部已启用模块、节点可点跳、文案与导航口径一致，杜绝「飞轮讲 6 步但地图有 15 模块」这类错配；区域清单子项（新增）：区域/目标客户清单必选、默认用户主场、支持地市下钻（同源筛选优先）、逐条带源、不编造凑数。内容层（逻辑/冗余/矛盾/致命/溯源闭环）门禁由battlemap-consultant专家在产出 JSON 前执行，本技能渲染前只做结构/UX 校验，但保留对「HTML 结构性损坏 / 编造来源残留 / 视觉系统未用精修版 / 飞轮与模块对不齐」的 veto 权。机器化终检（强制）：渲染后、交付前，必须运行assets/selfcheck.py 输出.html做五轴评分卡（R≥95 且 A≥85 且 L≥82 且 O≥80 且 S≥75 才 PASS）；不达标回炉补强后重跑，直至 PASS 才交付（详见references/quality-gates-and-workflow.md「交付前自检」）。可打开 HTML 预览。 - 交付：给出单文件 HTML（可离线、可打印、可深链 #pane 分享）。
资产位置
assets/build_map.py—— 生成器（读取 map.json + design.css + engine.js）assets/design.css—— 固定设计系统（从最完整母版 DRP 抽取，含全部组件样式）assets/engine.js—— 通用交互引擎（特性自适配：搜索/页码/键盘/打印）assets/demo-map.json+assets/demo-作战地图.html——demo-作战地图.html是经设计验证的富设计基准（电子高科技范例，224KB，组件最全），即新主题「展现形态参照物」与build_industry.py的默认设计源（SRC）；demo-map.json仅作 schema / 起步骨架教程（简化的「XX产品」示例，非设计上限）。新主题复刻 demo 富设计 = 复制build_industry.py→ 只改内容数据段 →-o。references/schema.md—— JSON 结构与区块类型完整说明references/methodology.md—— 作战方法论与访谈提纲assets/build_industry.py—— 定制行业模式渲染器（电子高科技已验证模板，新主题默认起步模板）：行业内容高度定制（飞轮 7 步 / 六大赛道拆页 / 政策罗盘）时，不复用 map.json，而直接改此脚本数据段（FLY_OUTER/INNER/SUPPORT 单数据源驱动飞轮，pane 容器块拼装）重生成。新行业：复制此模板 → 改内容数据段 +-o <主题>作战地图.html即可；SRC已默认指向插件自带demo-作战地图.html（设计源，离线、随专家打包、零外部依赖），-s仍可覆盖指定其他基准地图。assets/selfcheck.py—— 交付前自检器（丰富度 R × 美观度 A × 逻辑性 L × 视觉安全 O × 溯源 S · 五轴 + 逐页差异化 D 机器化强制闸门）：渲染后、交付前对输出 HTML 打分（R≥95 且 A≥85 且 L≥82 且 O≥80 且 S≥75 才 PASS），检查模块覆盖 / 体量(pane+文本) / 组件密度 / 条目密度 / 行动项密度 / 信息颗粒度 / 交叉深链 / 差异化探针 / 溯源 / 金蝶方案匹配（痛点→金蝶产品/方案映射密度）/ AI灵基融合（AI 打法须明确融入灵基 Lingee，弱项封顶）/ 逻辑性 L（结构锚定·章节标题 / 链路连通·无孤岛 / 主线贯通·WHY→WHAT→HOW / 论证闭环·痛点→价值 / 时序因果）/ 美观度 A 升级（视觉同源 / 组件多样性 / 完整度 / 飞轮对齐 / 视觉层次·标题层级 / 布局节奏·栅格多组件）/ 防溢出加固。详见references/quality-gates-and-workflow.md「交付前自检」。；另含结构完整性致命门禁：标签配平 + 首页.whband4 卡导航带（WHY/WHAT/HOW/支撑）必存，缺失即致命否决，从机器化层面杜绝「首页假丢失 / 真丢失」；另含逐页差异化 D 闸门（千页一面拦截）：每张 pane 的data-blocks签名 distinct/total<0.30 或最常见签名≥14 次即致命否决，强制逐页语义主导区块不同（补 A 轴「组件多样性」只数全局族、不查逐页相似度的盲区）。python selfcheck.py 输出.html [--json] [-o report.md]。
关键约束
- 输出必须是单文件、可离线（CSS/JS 内联），不引外部资源。
- 视觉与既有三份地图保持一致（同源 CSS），不另起炉灶。
- 内容可配置、可维护：改
map.json即可重生成，不手动改 HTML。 - 若用户同时启用了「作战地图顾问」专家，则该专家负责第 1–2 步访谈与产出 JSON，本技能负责第 3–5 步渲染。
- 渲染产出在呈现前必须通过「输出前质量门禁」：逻辑 / 冗余 / 矛盾 / 致命 / UX 五关 + 默认增强的可执行详细度（详见
references/quality-gates-and-workflow.md）。任一不过不得交付。
两种渲染模式并存说明（新主题默认走定制行业模板）
- 定制行业模式（新主题默认）：
build_industry.py→demo-作战地图.html同源富设计，内容内联在脚本数据段、以FLY_OUTER/INNER/SUPPORT单数据源驱动飞轮；新主题 = 复制脚本 → 只改内容数据段 →-o。这是「复用 demo 到其他主题」的标准路径，展现形态与 demo 100% 对齐，不会退化成简版。 - 通用模式（轻量备选）：
map.json→build_map.py，内容在数据文件，改 JSON 即可重生成，适合确属「标准骨架 + 非高度定制」的行业；须以templates/theme-template-map.json为骨架，禁止更简起步。两者共用同一design.css+engine.js（视觉 100% 同源），「输出前质量门禁」同样适用。
FAQ · 常见报错速查（集中版）
写作上限 / 流程卡点 / 禁止项分别散落在上文与 references/quality-gates-and-workflow.md 的各章节；遇到报错时只查本表即可，不必通读全文。格式：报错 / 症状 → 白话解释 → 怎么修。
系统级错误码速查（脚本退出码 → 含义 → 下一步）
脚本退出码与行为一一对应，先看码再对症：
| 退出码 | 含义 | 下一步 |
|---|---|---|
0 |
成功 | 按「✅ 已生成」提示打开产物；交付前跑 selfcheck.py |
2 |
输入 / 文件 / JSON / 写入错误（伴随「❌ 原因 + 👉 怎么修」人话提示） | 按 👉 提示修正输入后重跑 |
3 |
渲染器自检失败：输出 HTML 标签不平衡（渲染器缺陷拦截） | 重跑一次确认非偶发；仍复现请回报维护者，勿交付 |
4 |
--strict 模式下视觉安全体检未通过，拒绝写盘 |
按上方体检告警修复内容长度 / 列数后重跑 |
FAQ · 常见报错速查（症状 → 解释 → 修法）
| 报错 / 症状 | 白话解释 | 怎么修 |
|---|---|---|
json.decoder.JSONDecodeError: Expecting ... |
map.json 不是合法 JSON——多半少了逗号、多了尾逗号，或字符串里的引号没转义 | 把文件粘到任意 JSON 校验器定位到报错行补语法；或改用定制行业模式（数据段是 Python 字典，容错更好） |
KeyError: 'xxx' / 提示缺少必需字段 |
map.json 缺了 schema 要求的字段（如 meta.title、某 module 的 id） | 对照 references/schema.md 逐字段补齐，必填项以 schema「必选模块」段为准 |
| 提示「标签未闭合 / 结构完整性 FAIL」 | 生成的 HTML 有标签没配对（页面表现为版式错乱、内容丢失） | 重跑一次渲染器确认非偶发；若数据段含手写 raw HTML，检查其标签是否配平；不要手改 HTML |
home_band_ok=False / 页面首页空白、左侧导航丢失 |
首页 4 卡导航带（.whband）被删——这是框架契约，删了整张图等同报废 |
从备份恢复或重跑渲染器；临时压测文件用完即删，不要与真实地图混放 |
R < 95（丰富度不足） |
信息量没到基准图的 1.5 倍，通常是组件 / 条目 / 行动项 / 来源密度不够 | 看报告「补强优先级」最靠前的 2–3 项，按「知识丰富度规范」四条改写手法逐 pane 补，不要堆字充数 |
L < 82 / 提示「逻辑孤岛」 |
有的 pane 谁都不链接它、它也不链接别人 | 给每个 pane 补至少 1 条 data-goto 出链，并确认别的 pane 有链回来（互链成网） |
O < 80 / 页面出现横向滚动条 |
有内容太宽或太长撑破版面（表格超 8 列、卡片超 600 字、SVG 无 viewBox 等） | 按报错定位元素：拆表、拆卡片、给 SVG 加 viewBox；禁止用缩字号 / 隐藏内容掩盖 |
| 提示「逐页差异化 D 闸门 FAIL」（千页一面） | 每页区块组合长得一模一样，像模板复制出来的 | 让每张 pane 有一个不同的「语义主导区块」（分层塔 / 角色卡 / 节奏表 / 竞品块…），并检查是否把同一张 30-60-90 表复制到了所有页 |
data-goto 死链 / 点击跳转无反应 |
深链指向的 pane id 不存在（模块改名或删除后链接未同步） | 全局搜索 data-goto 的目标值，改为实际存在的 pane id |
| 渲染结果「比 demo 简陋 / 显得朴素」 | 用了通用模式的朴素组件起步，没走富设计模板 | 新主题一律走定制行业模式：复制 build_industry.py 改数据段；通用模式必须以 theme-template-map.json 为骨架 |
| 首页飞轮步数与左侧导航对不上 | 飞轮数据源（FLY_OUTER/INNER/SUPPORT）与导航 / 模块标题不同步 | 飞轮只能改数据源后重生成；确认飞轮 / 导航 / 首页 / 模块标题四套体系同为 7 步（①~⑦） |
| 提示「未在源文件中解析到 deepcase / map 数据」 | 索引生成器没在源 HTML 中找到约定的两块内容（DOM 变了或 pane 顺序不对） | 核对 deepcase / map 两 pane 的 id、类名与先后顺序后重新生成；严禁绕过校验手写编造索引 |
python: command not found / 版本不对 |
系统没把 Python 加进 PATH，或只有 python3 命令 |
先试 python3；Windows 再试 python / py；仍不行就安装 Python 3.8+（本技能零第三方依赖，装完即跑） |
| 生成的 HTML 打不开 / 白屏 | 文件未写完（构建中断）或被截断 | 重跑渲染器；确认 -o 路径可写、磁盘有空间；生成后先过 selfcheck 再交付 |
> 本表覆盖日常绝大多数报错；遇到表外问题，优先回读上文对应章节（「关键约束」「资产位置」「工作流」）或 references/quality-gates-and-workflow.md 的对应规范段。
