explainer-html

# 解释报告 HTML(四种形态,泽宇专用) 产出**单文件 HTML**(内联全部 CSS/JS,零外网依赖)。按场景选形态: - **`--mode metaphor`(默认)**:比喻式,给不看代码的聪明人解释工程工作。2026-07-18 泽宇裁定:「做了什么」类汇报默认此格式。 - **`--mode technical`**:技术式,直接呈现架构/设计/实现细节,多 SVG 图表,面向看代码的读者。不用比喻,用准确技术术语。 - **`--mode report`**:向上汇报式,给直属上级或管理层看的方案选型、采购申请、资源申请、问题升级。证据全部进表格,正文只留判断句,禁止修辞与免责说明。见下文「REPORT 模式专属规则」。 另外两种专用形态：产品方向/竞品调研走 PRODUCT 模式,多份材料整合成图走「多源整合图」。 > **禁止用 Claude Artifacts 原生功能**:产物应落盘为单文件 HTML；只有明确归属某个 Harness task 时，才放进该 task 的 `artifacts/` 并按其写入纪律登记。一次性解释、个人事务说明或尚无 Harness task 归属的临时 HTML，写入当前 workspace 的临时/交付目录，不要为了遵守“任务 artifacts”而虚构任务，也不要写入 Brain 正式知识库造成第二真相源。交付给用户前提供可点击的本地文件链接；若需要启动本地浏览器，执行 `open <file>` 并以真实命令结果为准，不能把命令超时或失败描述成已打开。若打开失败但文件已生成并验证，仍交付文件链接并明确说明打开状态未确认。**任何时候都不要 `Artifact publish`。** --- ## 零冗余与自解释铁律（强制反规范，四种形态通用，绑定 `self-explaining-ui`） > **这不是可选的设计风格，而是硬性反规范要求（不按此执行的 HTML 一律视为缺陷品）：** 1. **自解释结构与去冗余（Zero-Fluff Mandate）**： - **避免不必要的次要标签、说明文字、辅助文案、描述性文字和冗余的微文案。让布局、视觉层级、间距和清晰的主操作/表头自己完成解释。** - **优先用强视觉层级和自解释的结构，而不是用文字去解释**：标题直接给结论，表头列名和色彩标签（`.yes/.mid/.no`、徽章）直接表达属性，严禁在表格前加「下表展示了…」或在表格后加「小结/材料属性/汇报结语」。 - **默认不要添加 slogan 式文字、教学段落（如「怎么读这页」），或在每个区块下都加「帮助说明」**。 - **如果确实需要补充信息，优先使用 `info 图标 + tooltip`（或默认折叠的 `<details>`），而不是始终显示的次要文字。** 2. **底线护栏与盲测标准**： - **可访问性底线**：保留必要的语义标签、表单标签、图表 `aria-label` 与表格列标识（`th` / `data-label`，方便读屏软件与窄屏映射）。界面清爽不能牺牲可访问性。 - **不可逆/高风险提示底线**：涉及高危或不可逆后果、关键硬约束与生产风险（如断网停工、权限封禁、数据不可互通）必须保留清晰的后果提示。 - **首访盲测**：去掉所有说明文字后，第一次打开页面的人仍应一眼看懂：核心结论是什么、优劣与原因是什么、下一步看哪里或拍板什么。 3. **重写/精简已有 HTML 的强制工作流（Strip-First Protocol）**： - **先去掉冗余标签、导语、教学框和区块说明；如果清晰度下降，再去优化布局、合并重复表格、强化视觉层级和表头/按钮文案**——严禁靠把说明文字加回来解决问题。 --- ## METAPHOR 模式专属规则 1. **全程生活比喻,且先选题再动笔(2026-07-19 修订)**: - 每个技术概念出场时先给比喻,技术名词紧跟在比喻后面(如「户籍本(Markdown 真源)」「街区门牌(package)」)。 - 整篇必须用**一个统一的比喻世界**,不要东一个西一个。 - **禁止默认开餐馆/上菜/后厨。**餐厅只是可选世界之一,不是模板。金标准页若是上菜,抄的是**结构与密度**,不是菜谱世界观。 - **动笔前先选最贴主题的生活世界**(见下「比喻选题」),写进内容骨架的第一行:`比喻世界: … / 为何贴: …`。贴不上就换,不要硬套。 - 比喻世界**从机制本身生发**(见下「比喻选题」的发散点),不要套用现成清单或最近用过的世界。准绳只有两条:**外行一听就懂**、且**和机制同构**(结构对得上,而非表面像)。 2. **贴近全宽布局(2026-07-19 再修订,泽宇点名:边不要浪费;全宽才画得下大架构图)**: - **默认贴视口全宽**,不是「略宽一点的文章栏」:`max-width: none` 或 `100%`,仅保留页边 `padding: 24px clamp(16px, 2vw, 32px) 80px`。**禁止**再默认 `960px` / `1200px` / `1440px` 居中细条——大显示器两侧大片留白 = 不合格。 - 例外:纯文字长文段落可用内层 `max-width: 72ch` 保证可读;但 **hero、分幕卡片、网格、评分表、架构 SVG 必须吃满内容区宽度**。 - **架构图/对照图优先全宽**:SVG `width:100%`, viewBox 按宽构图(建议 ≥1200–1600 逻辑宽);宽屏用 2–4 列并排图,不要两张小图缩在中间。 - **≥1100px** 分幕内 2 列+; **≥1400px** 3–4 列、可「主文+侧栏」;侧栏 sticky 可选。 - **≤720px** 才叠成单列;极宽表在容器内横滚,页面不横滚。 3. **浅色适读配色(泽宇明确要求,禁暗色)**: - 背景:暖纸色系,`#faf7f0` / `#f7f3ea` 一类;区块用 `#ffffff` 或 `#f0ebe0` 微对比。 - 正文:深墨但非纯黑,`#3d3833` 一类;辅助文字 `#7a7266`。 - 强调色低饱和:成功 `#4a7c59`、警示 `#b0713c`、危险 `#a05252`、链接/主题 `#4a6b8a`。 - 不要纯白背景、不要高饱和荧光色、不要暗色主题。目标观感=纸质杂志/晨间读物。 4. **结构骨架**:顶部一句话直接回答核心问题 → 状态徽章行(几件事/几成收口/关键 PR 号)→ 分幕滚动(每幕一个问题)→ 结尾"现在到哪了"收敛图 → 折叠的「比喻↔术语对照表」供深究。 - 对“方案/架构文档速读”类页面，优先把读者真正要决策的内容放前面：一句话判断、当前阶段、已验证 vs 方案假设、云化/容量/成本/依赖风险、需要用户核实的最小问题清单。不要把长文档章节顺序机械搬进 HTML。 - 对 Agent 平台方案，单独呈现“测试分类”与“已具备的可复现证据”：把评测集、运行轨迹/Trace Schema、回放能力、测试脚本/环境/commit 绑定、回归阈值列为独立验收维度；文档声称的测试计划不得写成已完成验证。 5. **无 JS 也可读**:动效必须 JS-gated(`document.documentElement.classList.add('js')` 后才允许 `opacity:0` 类隐藏),默认全部内容可见——静态快照/无脚本环境下不许有藏死的空白。实测踩过坑。 6. **移动端仍要能读**;但**设计主目标是宽屏桌面**(泽宇主要在大屏上看)。 ## 比喻选题(必做,禁止跳过) **不要从一份现成的「比喻菜单」里挑**——菜单会让人每次挑同一个,且常和主题不对位。脑中第一念头往往是模板(尤其餐馆/后厨那一套),先放一边。从这次机制本身**生发**出一个世界,逐条回答下面这些**发散点**(只给维度,不给答案): 1. **谁在动**:机制里有哪几个角色/主体?谁求谁、谁卡谁、谁是中转?(角色关系 → 世界的「人际结构」) 2. **在哪儿动**:动作发生在什么样的空间?单一通道还是多点?层层关卡还是一片平地?有没有前厅/后场之分?(空间 → 世界的「地形」) 3. **靠什么流转**:凭据、票据、印章、钥匙、台账、回执、挂号……什么东西在主体间传递、被核对、会被伪造或丢失?(流转物件 → 世界的「道具」) 4. **错了长什么样**:出错时,现实生活里哪种事故和它同构?——走错门、串了味、记成烂账、迷了路、搭错线、漏了检?(故障形态往往是最锐利的选题线索) 5. **一句话向家人怎么说**:只用日常词向家人解释,你会不自觉冒出哪个生活场景?那个场景就是候选。 五个答案叠在一起,**共同指向**的那个生活世界,就是贴题的比喻。几个答案各指一处 → 主线没抓住,继续收敛;叠出一个谁都没想到、却和机制严丝合缝的世界 → 往往是最优解。 **换轨自检(交付前必做)**:把全文比喻关键词替换成中性词,机制还讲得通吗?——讲得通 = 比喻只是装饰(可能在套模板),重选;一换就讲不下去 = 比喻与机制同构,保留。 --- ## PRODUCT 模式专属规则（产品方向 / 竞品调研 / 行业拆解 / 战略汇报） 适用于一切「这个产品该做什么」类的页面：产品方向论证、竞品与行业研究、市场机会判断、方案对管理层的价值说明。本模式与具体行业无关——任何品类都按下面这套推演链组织，**禁止把某个具体项目的场景、术语、生态名词写进本规范**；它们只属于那一份材料。 ### 核心铁律 1. **不从供给侧罗列**：功能矩阵、竞品清单、参数对比只是证据，不是结论。页面必须先回答"用户要完成什么"，再回答"所以该做什么"。 2. **黑话必须先在现场拆开**：行业术语（各类能力缩写、架构分层名、平台/中台/底座这类词）第一次出现就要用一句大白话解释它到底指什么物理或业务动作，否则不许上页面。 3. **外部方案默认不可照抄**：任何成熟竞品的方案都建立在它自己的用户环境、生态、成本结构与组织前提上。页面必须显式写出这些隐含假设，并对照我方真实环境，指出哪些照搬会失效。 4. **差距不等于需求**：竞品做了而我方没做，只是研究线索；要经过客户任务排序、内部现状核实、同条件体验验证，才可能成为方向。 5. **事实分层不可混写**：公开宣传、第三方报道、访谈与会议发言、内部现状、实机或实测结果、本次推演假设——六类必须可区分标注，未核实数字不得画成既成事实。 ### 六幕推演骨架 每幕先写清"这一节回答读者哪个问题"，再放内容。 1. **结论与本质拆解**——回答"这东西到底是什么、我的判断是什么"。 顶部直接给主判断（一句话，能被引用）与少量关键数据；随后把该领域最容易被黑话掩盖的对象还原成可理解的物理/业务动作。**本质拆解图**：画出该产品在真实链路中的位置与它完成的转换/处理（全宽 SVG）。 2. **用户与语境**——回答"用户实际怎么干活、为什么现成方案不合用"。 用对照表拆出外部成熟方案的隐含前提（用户习惯、生态工具、组织角色、设备形态、付费方式）与我方真实前提的错位；点明我方模仿会失效的具体环节。**工作流图**：3–5 条真实任务闭环，每条按「场景 → 现在怎么做、痛在哪 → 靠什么能力承接 → 用户最终拿到什么结果」四步写，禁止只写功能名。 3. **能力承接**——回答"要靠什么体系把这些任务做完"。 用**分层架构图**（全宽 SVG）画清触点层、平台/服务层、数据与设备/执行层之间的调用与回流，明确边界：哪些由平台承担、哪些由外部系统承担、哪些是本期不做。写清平台承担的三到五项具体职责，不要用"赋能""打通"这类动词代替职责定义。 4. **竞品全景**——回答"结构性的空位在哪里"。 高信息密度矩阵：玩家 × 能力域，用颜色区分「已有可交付证据 / 概念或宣布 / 未找到公开证据」，标注可用地区、来源等级与我方基线行。矩阵下方必须有读图结论（哪几列是空位、哪几列已被占满），不能把解读责任丢给读者。附阵营打法与商业化锚点。 5. **画像与差距**——回答"各家真本事是什么、我方差在哪"。 每家写定位、具体产品/模块名、真实短板；我方基线单独高亮，且必须拆成「已核实长板 / 结构性差距 / 待内部核验」。**禁止把别家参数写进我方行**。 6. **路线与待拍板**——回答"先做什么、谁来决定什么"。 分阶段只给 2–3 个阶段，第一阶段限定 1–2 个可验证闭环并给出止损条件；右侧或下方列管理层待拍板清单（范围、首个方向、载体、内部资源、合规与安全底线、成功指标）与首轮验证清单（输入样本、评价口径、失败判定）。 ### 通用写法约束 - **从任务出发，不从功能出发**：任何能力都必须能落回"谁在什么场景下、原本怎么做、做完省了什么"。 - **量词要具体**：写"3 条工作流""4 项平台职责""2 个待拍板"，不写"多个""若干"。 - **本土/我方生态优先**：外部连接器、外部生态位、外部合规假设都要先确认在目标市场或目标组织内是否真的可用。 - **可验证优先**：每个方向写出验证样本、指标口径与失败条件，而不是只写愿景。 ### 版式与交付要求 - 贴视口全宽（禁止 960/1200/1440px 居中窄条），架构图与工作流图 `width:100%`，SVG `viewBox` 建议宽度 ≥1600。 - 浅暖纸色背景（如 `#faf7f0`）+ 低饱和蓝/绿/琥珀/红表达语义；提供 `@media print` 的 A4 landscape 样式。 - 至少 3 张全宽 SVG：本质/链路图、任务工作流图、分层架构图。行业不同、图形结构可换，但"本质—任务—体系"三层必须齐备。 - 内容清晰时自己直接写 HTML；图表极复杂可委托，但事实骨架必须先由自己固定。 - 交付前必做：泄漏检查、事实核对（每个数字对照来源）、无 JS 可读性检查、全宽留白检查、以及**换项自检**——把材料换成另一个行业的产品，骨架是否依然成立？只剩专有名词才不成立＝合格；连结构都依赖某个具体行业的术语＝规范被污染了，要改。 ## REPORT 模式专属规则（向上汇报 / 方案选型 / 采购申请） 适用：给直属上级、跨部门、管理层看的决策型材料——设备或资源采购申请、几个方案的选型汇报、需要上级拍板的问题升级。 **与 PRODUCT 模式的区别**：PRODUCT 模式论证「该做什么」，读者是评审人；REPORT 模式论证「在几个已知选项里选哪个」，读者就是决策人本人。语气是提交，不是说服——把每个选项的代价摆到桌上，让读者自己合算。 ### 铁律 1. **高信息密度与「核心、优劣、原因」一步到位（2026-10-27 泽宇裁定）**： - **严禁同一事实重复三遍**：禁止把同一组方案参数先在“方案一览表”列一遍、再在“单方案分节”列一遍、最后又在“横向对比总表”重复一遍，导致报告膨胀到 14 页（「我自己都懒得看」）。 - **每个方案按「核心、优劣、原因」高密度收敛**：直接用自解释的网格/表格呈现 **核心配置与成本、优势、劣势/限制、背后的技术或组织原因**，一屏/一页讲透。 - **执行 `self-explaining-ui` 反规范**：严禁添加「材料属性」「汇报结语」「阅读说明」或表格前后的解释性过渡段落。重写或精简长汇报时，**先砍掉所有冗余标签、导语和说明文字；若清晰度下降，再去优化布局、合并同类表格、强化表头和视觉层级**。 2. **证据进表格/卡片，零废话。** 禁止用解释性长段落承担论证。读者扫标题、表头和色标徽章就应该能复述结论。 3. **禁止一切修辞。** 明确禁用：破折号 `——`；「不是…而是」「问题不在…而在」「不只是…更是」「一边…一边」「越是…越是」「没有…没有…」这类排比句式；自造复合词（「把人拆成两个半个人」「能力腰斩」「净读数」「停摆」之类）；程度渲染词（极其、致命、核心问题、本质问题）。这些词在汇报页里就是噪音——决策人只想知道选哪个、优劣是什么、为什么、要多少。 4. **禁止防御性说明与元属性标签。** 不写「材料属性」「事实边界」「事实口径」「本数据未实测」「不是询价结果」「仅供参考」「未做统一基准测试」这类免责段落，也不在表格末尾加口径脚注或「汇报结语」。**例外只允许一处**：数据来源核对可以在 `figcaption` 里用一句短话交代（如「WSL2 内存上限来自微软官方文档；其余为区间估算」）。 5. **决策边界分两态（初次呈报 vs 领导定调后）：** - **态 A（初次呈报 / 领导尚未定调）**：只阐述问题与各方案的核心、优劣、原因，**不做决策引导**（不写「建议采用方案X」「推荐方案Y」，不设「汇报结语」，禁止出现「需谁确认」「请示某总」）。 - **态 B（管理层已给明确决策/倾向后）**：当领导已明确反馈倾向（例如「优先方案二、方案三兜底，且岗位要分梯度」），必须增设专门的**推进与兜底路径节**，直接写明： 1. **主推方案 + 需协同解决的前置问题 + 明确工作风险**（如：推荐方案二，但需数字化/IT 部门解决远程访问控制，且明确说明出差/客户现场网络受限风险）； 2. **必选兜底方案**（当主推方案网络或环境受阻有风险时，以哪一方案作为必选兜底）； 3. **岗位/对象梯队分层**（如：高负载本地编译岗 FDE 配 Pro 机型 vs 以云端 AI 为主的产品经理 PM 配 Air 机型——**有梯度分层才有说服力**，严禁全员一刀切申请顶配）。 6. **对方已经松口的约束不能当论点。** 如果对方已表示某限制可以调整（哪怕现状确实不可用），该约束必须降级为一句话的现状说明，并显式写「该项不作为本方案的取舍依据」，绝不能作为论证的一环。 7. **先在自己的方案里做减法与分层。** 汇报的第一个动作是砍掉不合理诉求并拉开梯度：哪些岗位用存量就够、哪些岗位只需基础款（如 Air）、哪些核心岗才需要高配（如 Pro），放在最前面讲清楚。 8. **主动写对方会站的那一面。** 每个方案的优点都如实写出，包括我们不推荐的那个。只列缺点会被判为偏心。 9. **成本用用户给的实际金额。** 用户给出具体数字后，全文必须统一替换，并 grep 旧数字确认残留为 0。 10. **硬约束原样写，不要软化成「不方便」。** 用户说「禁止发送文件」「不许安装远程软件」时，表格里就写「禁止」「不互通」「不可」，并直接写出真实后果（各存一份、断网停工、只能重装一遍）。 ### 结构骨架（高信息密度，控制在 6–8 页手机屏） ``` 第 1 页：标题 + 岗位梯队分层与核心诉求 + 四/三方案全景速览（构成 / 成本 / 定位） 第 2 页：岗位分层必要性与硬件瓶颈量化（如 FDE vs PM 梯队差异 + 内存/算力量化 SVG） 第 3–5 页：各方案逐一拆解（每方案半页至一页，严格按「核心构成与成本 / 优势 / 劣势与风险 / 根本原因」四维自解释呈现，不写废话段落） 第 6 页：关键维度横向对照总表（只保留决策差异项，不重复废话） 第 7 页（仅当管理层已给决策方向时）：推进路径与风险兜底（主推方案与需协调问题 + 风险边界 + 必选兜底方案 + 梯队采购落地） ``` - **全页高密度收敛**：手机 PDF 严格控制在 **6–8 页**（严禁膨胀到 10–14 页）。 - **零冗余自解释**：不写页脚免责声明，不写「材料属性」，不写「汇报结语」，不写表格前后的解释性导语。 - 表格与卡片用 `.yes/.mid/.no` 语义色标与加粗行首直接呈现优劣，让视觉层级自己说话。 ### 交付前自检（按顺序跑） 1. **自解释去冗余盲测**：是否已删光「材料属性」「汇报结语」「怎么读这页」及表格前后的解释性废话段落？去掉说明文字后是否一眼看懂核心、优劣、原因？ 2. 破折号计数 = 0；排比句式正则逐条命中 = 0。 3. 「口径」「仅供参考」「未实测」「事实边界」「材料属性」等防御/元属性词 = 0（唯一例外是铁律 6 要求保留的那句「不作为本方案的取舍依据」）。 4. 决策指派词（负责人、请示、由某部门决定）= 0。 5. 建议类词检查：初次呈报（态 A）建议词 = 0；领导已拍板（态 B）必须准确反映「主推 + 需解决问题/风险 + 兜底 + 岗位分层」。 6. 用户纠正过的事实与数字，全文件 grep 旧表述/旧数字 = 0。 7. 岗位/对象名称与用户口径及分层梯度一致。 ### 手机优先（默认，汇报材料的第一硬约束） 向上汇报材料的读者几乎都在手机上看——领导在会议室、在车里、在饭桌上点开一个链接或 PDF。**宽屏排版是其次，手机排版是第一**。 1. **容器宽度限死，高密度紧凑排版。** REPORT 模式例外于 METAPHOR 的全宽规则：`body{padding:16px 14px 40px}` + `.wrap{max-width:520px;margin:0 auto}`（宽屏 `min-width:820px` 可扩至 960px）。 2. **高密度三列表优先于松散碎卡片。** - 过去把所有表格无脑拆成单列长卡片，会导致 14 页巨长无比、信息密度极低。 - **新准则**：在 390px 手机屏上，列数 ≤ 4 且内容精炼的对照表，优先设计为**原生适配 390px 宽度的紧凑型高密度表或 2×2 网格 + 核心/优劣/原因结构卡**，无需横拖即可一屏看全；只有超宽多维表才用 `data-label` 卡片化，且必须保留 `th` / `data-label` 保证可访问性。 3. **字号与视觉层级按手机屏幕定。** 强对比标题与徽章，正文字号 13px–15px，行高 1.45–1.55，紧凑清晰，一屏容纳完整逻辑单元。 4. **SVG 按窄屏高密度设计。** viewBox 适配手机宽度（如 `680×240`），标签直接内嵌或置于条形上方，零溢出。 5. **交付前用 390px 手机视口自检**：确认无横向滚动条、无文字重叠、无多余说明段落。 ### 日期与命名 - **日期以系统时间为准，不凭上下文推断。** 文件名与目录名里的 `YYYY-MM-DD` 必须先跑 `date` 拿真实日期再用。 - **日期一旦被用户指出错，要全域同步。** 改目录名 → 改文件名 → 改上级 INDEX 里的链接 → 改 Backlog 里的 `doc_ref` → `git add` 让 git 认出 rename。 ### 多模式转 PDF（Skill 内置沉淀脚本，按场景选择版式） 汇报材料的消费场景多种多样——**不是强制只能出原生手机版，而是多种模式皆可支持**。Skill 已沉淀统一导出脚本 `scripts/export-pdf.mjs`，一键支持多版式转换、规格校验与缩略图预览： ```bash node ~/.claude/skills/explainer-html/scripts/export-pdf.mjs <输入.html> [输出.pdf] --mode <模式> [--preview] ``` #### 常用版式模式对照与适用场景 | 模式（`--mode`） | 页面尺寸（`@page`） | 比例 | 适用场景与排版建议 | |---|---|---|---| | **`phone` / `mobile`** | `390pt 844pt` (内边距 `14pt 12pt`) | 9:19.5 (iPhone 竖屏) | **领导在微信/手机端快速审阅**：一页对齐一屏，高信息密度（建议 6–8 屏），无横向滚动条，内容饱满紧凑 | | **`a4-portrait` / `a4`** | `595pt 842pt` (内边距 `10mm 8mm`) | 1:1.414 (标准 A4) | **正式呈报公文、纸质打印、平板/桌面阅读**：采用紧凑表格与两列布局，字号 12–14px | | **`a4-landscape` / `land`** | `842pt 595pt` (内边距 `8mm 10mm`) | 1.414:1 (A4 横向) | **宽幅甘特图、复杂数据大表、横向架构图与技术全景**：横向铺满，适合大表格不折行 | | **`slide` / `16-9`** | `960pt 540pt` (内边距 `14pt 16pt`) | 16:9 (宽屏幻灯片) | **会议室投屏演示、大屏演说、幻灯片汇报**：大标题 + 关键指标 + 核心图表，一页一个核心主题 | | **`auto`** | 沿用 HTML 内 declared `@page` | 原生比例 | **已在 HTML 精确设定打印尺寸**：脚本不强制覆写 `@page`，原汁原味导出 | #### 导出流程与校验门禁 1. **一键导出命令**： ```bash # 示例：微信汇报手机版（带缩略图预览） node ~/.claude/skills/explainer-html/scripts/export-pdf.mjs 汇报.html 汇报-手机版.pdf --mode phone --preview # 示例：呈报打印 A4 纵向版 node ~/.claude/skills/explainer-html/scripts/export-pdf.mjs 汇报.html 汇报-打印版.pdf --mode a4-portrait # 示例：宽屏架构展示 A4 横向版 node ~/.claude/skills/explainer-html/scripts/export-pdf.mjs 架构方案.html 架构-横版.pdf --mode a4-landscape ``` 2. **自动化校验与防崩反馈**： - 脚本会自动调用系统 Chrome Headless 进行保真渲染（自动开启色彩精确 `-webkit-print-color-adjust: exact`）； - 导出后自动调用 `pdfinfo` 检查输出的页数、点阵尺寸与模式期望是否匹配； - 手机模式若页数超过 9 页，会发出篇幅警报，提醒排查冗长废话或未合并的重复表格； - 开启 `--preview` 时自动通过 `pdftoppm` 输出 150 DPI PNG 缩略图，便于交付前直接目测页面丰满度与截断情况。 --- ## TECHNICAL 模式专属规则 1. **不用比喻,用技术术语直述**:所有概念用准确名词(interface、capability seam、daemon、schemaVersion 等),不做生活类比。 2. **以架构图为主体**:每个章节优先用 SVG 图表表达,文字是图的补充说明。建议图类型: - 分层架构图(矩形块 + 箭头,从上到下或从外到内) - 数据流图(节点 + 有向边,标注 artifact/contract 类型) - 状态机图(状态圆角方块 + 转换边,标注触发条件) - 依赖/前置图(DAG,节点是模块/任务,边是依赖关系) - 对比表格(现状 vs 目标,已有 vs 待建,✅/🔲 标注) 3. **结构骨架**:顶部一句话定义主题范围 → 状态行(几个方向/几个已有基础/几个待建)→ 每节一张架构图 + 精确描述 → 尾部依赖图(哪些先做/后做)→ 可折叠的代码片段/schema示例。 4. **全宽布局同 METAPHOR 模式**:SVG `width:100%`,viewBox ≥1600 逻辑宽;≥1100px 多列并排图。 5. **配色同 METAPHOR 模式**:暖纸色系,浅色,禁暗色;图中节点用低饱和色块区分层次(已有=`#4a7c59` 绿调、待建=`#b0713c` 橙调、核心接口=`#4a6b8a` 蓝调)。 6. **无 JS 也可读**:同 METAPHOR 模式。 7. **代码/schema 示例**:用 `<pre><code>` 块展示关键 TypeScript interface、YAML schema、命令示例;字体等宽,背景微深;≥1100px 时可放侧栏与图并排。 --- ## 通用规则(三种模式都适用) - **向上汇报材料走 REPORT 模式，不要让通用规则覆盖它。** 本段是历史层，已被上文「REPORT 模式专属规则」取代；两者冲突时以 REPORT 模式为准（尤其是「写不写建议」和「窄屏还是全宽」两条）。 - **贴近全宽布局**:`max-width: none`,仅保留页边 `padding: 24px clamp(16px, 2vw, 32px) 80px`;禁止 960/1200/1440 居中细条。**仅适用于 METAPHOR / TECHNICAL / PRODUCT 模式**；REPORT 模式走手机优先 680px。 - **浅色适读配色**:背景 `#faf7f0`/`#f7f3ea`,正文 `#3d3833`,禁暗色主题。 - **无 JS 也可读**:JS-gated 动效,默认全部内容可见。 - **移动端可读**:METAPHOR / TECHNICAL / PRODUCT 模式主目标是宽屏桌面；**REPORT 模式反过来——手机是第一目标**，宽屏是增强。 --- ## 内容纪律(比风格更重要) - **任务对照表是硬骨架,比喻是皮(2026-08-19 泽宇修订)**:凡汇报涉及北极星/milestone,页面必须有一张**直白的任务对照表**——该 milestone 下每个 task 一行:task 名(人话)+ 干了什么(技术直述,不用比喻)+ 状态(done/在飞/排队/待裁)+ 锚(PR 号/commit/task id)。表内**禁止比喻词**。比喻只许包在叙事幕里,不得让读者「感觉看不清功能怎么做的」;每个功能点旁必须有一句无比喻的直述。测试/验证状态同理:哪些场景在什么环境跑过、哪些没跑,直接列清单,不许只给比喻性的「水质检验通过」。 - **汇报禁止解释性文字与修辞**（2026-10-21 泽宇严格纠正，此条优先级高于比喻风格）： - **汇报材料不是解释文**。删掉所有破折号、排比句式（「不是…而是」「问题不在…而在」「一边…一边」「越是…越是」）、自创词汇、程度渲染（「致命」「核心」「极其」）。 - **论证走表格，不走段落**。每一条判断落在「项 / 结论 / 说明」三列表格里；正文段落只保留一两句过渡或关键判断，不展开叙事。 - **禁止抒情式收尾**。不写「卡顿三秒对方会记住」这类场景化劝说、不写比喻性最终陈词。 - **自检方法**：剥离 HTML 标签后统计破折号 = 0、排比句式 = 0；若还有，重写。 - **一个事实被用户纠正多次，就全局重写而不是改局部。** 同事/岗位的归属关系、某台设备的价格、谁的职责范围——这类事实一旦被指出错，不要只改被指出的那一处：用关键词全文件 grep + 计数，确认旧表述为 0；同时检查内部是否自相矛盾（一处写两个岗位、另一处写三个）。用户反复纠正同一件事时，问题往往不在那一句话，而在我没建立唯一的术语口径。 - **同一句里既否定又自创词，会同时踩两条禁令。** 写完先通读一遍找「这句子是不是在对抗一个我没写出来的说法」——那种防御型句式（反驳一个预设的读者）在汇报里一律删。 - **写给没看过过程的人(2026-08-20 泽宇修订)**:页面是读者对这件事的**第一眼**,不是工作线程的延续。交付前逐条过: - **第一句话就是结论**。不要先铺背景再揭晓;先说结果或发现,再给支撑细节。 - **你在工作中造的词是你的,不是读者的**。「族」「lane」「停摆」「净读数」这类简写,要么第一次出现时用一整句话解释,要么换成日常说法。自创的缩写标签一律不许直接上页面。 - **写完整句子**。禁止箭头链(`A → B → C`)、连字符堆叠的复合词、以及只有自己看得懂的速记短语。 - **提到文件、提交、参数、命令,每一个都配一句白话说明它是干什么的**。只给一个路径或一个 flag 名等于没说。