tech-spec-html把一段需求 / 一段思考 / 一段会议纪要写成单页 HTML 格式的「技术方案 / Design Doc」（工程视角的"怎么做"，含背景、目标、技术方案、风险、影响范围、产研计划等模块；不是产品 PRD 的"做什么"），或者增量更新一份已有技术方案。新建场景：当用户说「写一份技术方案」「写个 design doc」「整理成 HTML 技术文档」「评审用的方案文档」「create tech spec」时使用。更新场景：当用户指向某份已有技术方案 HTML、说「评审完根据反馈调一下」「在风险章节加一条」「方案 A 改成 B」「补充某个章节」时也使用本 skill —— 走「最小化改动 + 保持文档稳定身份」的更新工作流而不是重写。
Independent GitHub snapshot · Automated classification · Original documentation governs
把一段需求 / 思考 / 会议纪要写成单页 HTML 格式的技术方案 / Design Doc。
配套阅读：所有组件的完整 HTML / CSS 类名 / 代码示例在
references/components.md—— SKILL.md 主文件只保留「何时用哪个」的决策表，详细代码按需 lazy load。
写作铁律（贯穿全文）：每写一节内容前，先问自己「这能不能用图 / SVG / 组件表达？」——能用就用，写文字段落是最后的兜底。一份技术方案如果通篇是段落 + bullet，等于浪费了 HTML 模板的全部价值，和一份 Markdown 没区别。
技术方案天生是多种内容的拼装：分层架构、流程图、状态机、对比分析、字段定义、风险评估、时间计划。Markdown 把这些堆在一起靠的是约定，到了长文档里就会层级不清。
HTML 的真正优势是能把任何需要可视化表达的东西用合适的组件呈现——业务目标用大数字卡片、方案选型用对比 grid、流程用 SVG（而非文字描述）、风险用二维矩阵（而非一维列表）、里程碑用甘特图（而非日期表格）。
本 skill 的核心立场：写技术方案时优先用图 / 用结构化组件，能不写段落就不写段落。评审同事看到「3.2h · 处理时长 · 目标 15min」的 metric 卡，比读"当前处理时长平均 3.2 小时，目标优化到 15 分钟以内"高效得多——Markdown 给不了这个能力。
「想用文字写」时的快速对照（看到左边内容，先考虑右边组件）：
| 想用文字写 | 改用什么 |
|---|---|
| "当前 X 是 A，目标降到 B" / 一段现状描述 | Metric Cards |
| "方案有 A / B / C 三种，各自优缺点是…" | Comparison Grid |
| 一段步骤描述 / "用户先点 X 再点 Y 然后…" | Flow SVG（或 Flow + Story Walkthrough 联动） |
| 一段架构描述 / "系统分四层，最上层是…" | Architecture SVG |
| "状态有 A / B / C，从 A 可以到 B…" | State Machine SVG |
| "主要风险有几条：…" | Risk Matrix 2×2 + 表格 |
| "里程碑：W1 做 X，W2 做 Y…" | Timeline 甘特 |
| 长字段定义 / 错误码列表 / 大段代码 | <details class="fold"> 折叠 |
段落只用来：点结论 / 串场过渡 / 解释组件没法承载的判断逻辑——而且单段不超过 4 行。
分享层面也是：Markdown 丢出去对方还得找渲染器；HTML 是一个文件，浏览器双击就能看。
技术方案是一步步完善的文档：第一稿评审完会改、需求变了会改、对齐了新决策会改。本 skill 分两条路径——新建 和 更新——开始动手前先判断是哪种，避免把更新当成新建（每次重写会丢评审上下文 + 丢稳定身份 ID）。
| 场景 | 信号 | 走哪条 |
|---|---|---|
| 用户给一段需求 / 一段会议纪要 / 一个改造方向，且当前项目里没有对应的方案 HTML | 「写一份方案」「这个改造写个 design doc」「整理成技术方案」 | A · 新建 |
| 用户指向一个已有的方案 HTML 文件，描述要改什么 | 「评审完了根据反馈调」「方案 A 改成 B」「加一条风险」「阈值从 500 改成 1000」「在 X 章节加 Y」 | B · 更新 |
| 用户给一段 Markdown 方案想转 HTML | 「把这份 md 转成 HTML」 | A · 新建（按结构重组进模板） |
用户给一份已经被某个工具发布 / 归档过的 HTML（head 里带形如 *-id 的稳定身份 meta） | 入口 HTML 头里有 name="*-id" 类的 meta | B · 更新（保留那些稳定身份字段） |
不确定就问一句「这是新写一份方案，还是改 <已有路径> 那份？」。
看到用户丢一段描述先别立刻动笔。用一两句话和用户对齐再写——读者是谁、范围多大、有没有现成素材（设计稿、已有接口、上次会议结论、相关代码路径）。
只问真的会改变文档结构的问题。「这是写给技术评审还是产品评审」会决定要不要展开技术细节，就该问；「标题用什么」用户没说就先按需求名起一个，不用问。
用户给的素材已经够厚（详细描述 / 一份纪要 / 代码 + 改造方向），可以跳过这一步直接动手。
复制 assets/template.html 到用户项目里——一般放 <项目>/docs/tech-spec/<需求名>.html。文件名用简短的英文 / 拼音（短名字可读、便于将来作为 URL 路径段）。
模板里已经有：标准章节、配色、字体、目录、9 类可视化组件示例、mermaid 加载、可打印样式、基础 meta 字段。
模板里的示例内容是占位 + 演示用（用了「部分退款」做例子），复制后改成方案的真实内容。看到 data-detail="..."、metric-value 里的数字、compare-card 的内容都要替换。
按下面这个顺序组织。简化场景见下方「结构裁剪」。
每写一节前，先回到顶部的「写作铁律」：这一节有没有合适的图 / SVG / 组件能承载？能用就用，文字段落是兜底——一份方案如果通篇 bullet + 段落，就说明组件没用够。
is-pick 类，每卡含优 / 缺点 / 评分点数。components.md#k-数据模型四段式）：
erDiagram 或带 PK/FK 强调的文字清单）<details class="fold"> 折叠）sequenceDiagram 补充跨服务调用细节。mermaid 适合时序，SVG 适合架构 / 流程 / 状态。<details class="fold"> 折叠，避免压垮主线<p class="todo"> 和 <span class="todo-tag">TODO</span> 都汇总到这一节，便于评审后按 owner 分头推进。短方案（< 1000 字、无明显未定项）直接省略，不留空标题。不是每份方案都要全部模块。少哪一块就在 HTML 里把整个 section 删掉，不留空标题。
先看高层选型原则 · 口诀：需要画 → SVG；需要排 → HTML + CSS；标准时序 / ER → mermaid。
判断逻辑：
反模式警示：Risk Matrix / 甘特 这类"位置即数据"的图用 CSS grid 拼 dot / bar，dot 只能落在 cell 中心丢精度，且跨浏览器渲染有差异。完整反模式案例 + 各组件 SVG 代码见 references/components.md。
再按场景查组件：模板内置 9 类，何时用哪个 → 查下表；完整 HTML 代码 / CSS 类名 / 注意事项 → 见 references/components.md。
| 用户在写 | 用哪个组件 | 一句话说明 |
|---|---|---|
| 有数字基线的指标（性能 / SLA / 转化率 / 人效现状→目标） | Metric Cards | 大数字 + 单位 + 目标 + 进度条；定性目标别强行套，会被迫编数 |
| 多维度的现状 / 目标对比 | 小表格（维度 / 现状 / 目标） | 比 metric 卡轻，适合 3 个以上维度并列 |
| 定性目标 / 没基线的目标 | bullet 列表 | 每条 1 句话点结论；不要为了视觉冲击力强上 metric |
| 技术选型 / 方案 PK | Comparison Grid | 卡片化 + 推荐标 + 评分点数 |
| 系统分层 / 模块拓扑 | Architecture SVG | 4 层堆叠 + hover 高亮 |
| 核心业务流程 | Flow SVG | 起 / 终 / 处理 / 判断 4 种节点 |
| 用户交互走查（C 端 / 移动端） | Flow + Story Walkthrough（联动） | 流程图节点 ↔ 手机 mockup ↔ 后端 meta 三联动 |
| B 端 / 后台 UI 演示（PC 表单 / 列表 / tabs） | Browser Mockup + demo-ui 控件族 | 桌面浏览器壳 + tab / btn / row / field / progress / tag 控件，模拟单页 UI 状态 |
| 跨服务调用走查（无 UI） | Story 服务端变体 | mockup 换成调用链时序 / 数据流 / 状态前后对比 |
| 状态流转 | State Machine SVG | 圆形状态 + 弧形 transition |
| 时序 / ER 关系 | mermaid | sequenceDiagram / erDiagram |
| 风险（≥ 3 条） | Risk Matrix 2×2 | 概率 × 影响二维网格 + dot 数字关联下表 |
| 里程碑 | Timeline 甘特 | 横向轴 + 任务条 |
| 长字段 / 错误码 / > 30 行代码 | Details 折叠 | summary 显示「X 项」 |
| 章节标题 / 表格里就地标注 TODO | <span class="todo-tag">TODO</span> | inline 黄色小标，避免段落级 <p class="todo"> 的体量；可加 .info .ok 变体 |
| 数据模型（实体清单 + ER + 表设计） | mermaid erDiagram + 字段表 + details fold | 见 components.md 数据模型四段式 |
| 待确认事项汇总 | 集中表（类别 / 事项 / 责任人 / 预期完成时间） | 长方案推荐，散落 TODO 难追踪 |
优先级：能用内置 9 类的，先用内置；mermaid 是兜底（适合时序 / ER）；都不合适再手写 SVG。
模板定好了排版，内容质量靠这几条：
<details class="fold"> 折叠。<p class="todo">...</p> 标黄，让人一眼看到要补的地方，避免用模糊的"待定 / TBD"埋雷。模板的 <head> 里有：
<title>{标题}</title>
<meta name="author" content="">
<meta name="date" content="">
<meta name="status" content="draft">
这些字段会显示在文档右上角：作者名、日期、状态徽章（draft / reviewing / final / archived 各有不同颜色）。
<title> 必须填，作为浏览器标签和文档头部主标题。author 填作者姓名。date 填日期（YYYY-MM-DD 格式）。status 填 draft（草稿）/ reviewing（评审中）/ final（已定稿）/ archived（已归档）之一。如果有团队的发布 / 归档工具会自动注入额外的稳定身份字段（形如 name="*-id"），那是工具自己的契约，本 skill 不创建也不解释；只在更新场景需要保留这些字段（见 B.4）。
F=<新写的 html 路径>
# 1. 模板 placeholder 是否都替换（应该返回空）
grep -nE '需求标题|示例·|\{\{|TBD|XXX' "$F"
# 2. 流程图 + Story 联动的 data-step 是否对齐
echo "Flow nodes:"; grep -oE 'flow-node[^>]*data-step="[0-9]+"' "$F" | grep -oE '[0-9]+' | sort -u
echo "Story steps:"; grep -oE 'story-step[^>]*data-step="[0-9]+"' "$F" | grep -oE '[0-9]+' | sort -u
# 两边数字应该一致（除了流程图的菱形 decision 节点不带 data-step）
# 3. mermaid 块是否成对
echo "mermaid open=$(grep -c '<pre class="mermaid">' "$F") close=$(grep -cE '</pre>' "$F")"
# 4. 基础 meta 是否在
grep -E '<title>|name="author"|name="date"|name="status"' "$F" | wc -l
# 应该 ≥ 4
「文件已写到 <路径>。」
技术方案是动态的：第一稿评审后会改、需求迭代会改、对齐了新决策会改。更新场景的核心是「最小化改动」+「保持文档稳定身份」——重写整个 HTML 会丢评审上下文，丢失稳定身份字段会让其他系统（发布工具、文档索引）把这份文档当成新的、和历史版本失去关联。
收到更新任务的第一件事：用 Read 工具读完整个现有 HTML。不读就动手是有风险的——不知道当前用了哪些组件、有没有稳定身份 meta、哪些是定稿、哪些是 TODO 标黄。
读完后心里要清楚：
name="*-id" 类稳定身份字段——这些是其他系统注入的，必须原样保留.todo 标黄用 Edit 工具做精确替换，不用 Write 重写整个文件。即便看到"顺手可以优化"的地方也克制——评审同事可能已经在某个文档平台上看过当前版本、记住了某些段落的位置、甚至贴了链接给上下游，重写会让他们的心智模型失效。
「最小改动」具体怎么做：
<section> 或 <h3> 之间的内容nav.toc 的对应链接，同时修正后续 <span class="num">XX · ...</span> 的章节编号<a href="#sec-3-4-X">。LLM 在更新场景最常见的 bug 就是只删内容忘了重编号.num span + nav.toc 的对应 li + 正文里所有引用编号的位置（"详见 3.4.2"）都要同步改新加的内容尽量复用模板里已有的组件，保持视觉一致：
| 用户说要加 | 用哪个组件 |
|---|---|
| 加一个新风险 | 在 .risk-matrix 加 dot + 下方表格加一行 |
| 加一个备选方案 | 在 .compare 里加一张 .compare-card，原推荐的 is-pick 不变 |
| 改业务目标的数字 | 改对应 .metric 里的 .metric-value |
| 改流程某一步 | 改 Story Walkthrough 对应 data-step 的 mockup + meta-card |
| 加一个里程碑 / 改时间 | 加 .timeline-row 或调对应 bar 的 --start/--end 百分比 |
| 加一大段错误码 / 字段说明 | 用 <details class="fold"> 折叠，summary 显示「X 项」 |
如果现有 HTML 的 <head> 里有形如以下的字段：
<meta name="doc-id" content="..."> <!-- 文档稳定 ID -->
<meta name="page-id" content="..."> <!-- 或 page-id / *-id 类 -->
<meta name="published-url" content="..."> <!-- 已发布地址 -->
原样保留 content，不要改 / 不要删。这些字段是别的工具（发布 / 索引 / 文档平台）写入的稳定身份，丢了或改了会让那些系统认不出这是同一份文档，可能造成历史版本断裂或重复创建。本 skill 不生成这些字段，但要保护它们。
判断范围简单粗暴：head 里所有 name 以 -id 或 -url 结尾的 meta 都按"保留"处理。
<title> —— 标题可改（其他系统的索引展示可能会跟着变）<meta name="status"> —— 评审推进时可能 draft → reviewing → final。如果用户的更新意图明显是"评审完定稿"，主动建议 status 推进<meta name="date"> —— 改成当天日期反映本次更新时间<meta name="author"> —— 一般保持原值，除非这次实际改动人换了| 改动规模 | 怎么做 |
|---|---|
| 改个数字、改一行表格、加一条 bullet | 直接 Edit，不需要再确认 |
| 替换某个 section 内容 / 加一个 section | 直接 Edit，改完用一句话告诉用户改了什么 |
| 整体改结构 / 删多个 section / 改默认顺序 | 改之前先把方案告诉用户：「我打算把 X 删掉、Y 替换成 Z、TOC 同步更新，对吗？」得到确认再动手 |
| 用户说"重写"但你看下来其实只需要改两段 | 提示用户「这份方案我看下来只需改 X 和 Y，其他章节保留是不是更合适？」避免误删 |
只说"文件已更新"用户没法知道改了啥。具体说：
is-pick 类移到 B 卡，A 卡保留作为对比记录。3.7 详细设计里的接口签名也同步改了。」改动涉及 status 推进（draft → reviewing → final）也告知：「我把 status 改成了 reviewing；不需要改就告诉我」。
F=<改过的 html 路径>
# 1. 稳定身份 meta 是否保留（如果原文件有，新文件必须有且 content 不变）
grep -E 'name="[^"]*-id"|name="[^"]*-url"' "$F"
# 2. 章节编号 + TOC 是否同步（如果改了章节）
echo "h2 nums:"; grep -oE '<span class="num">[^<]+' "$F"
echo "toc items:"; grep -oE 'href="#[^"]+"' "$F"
# 3. 改动涉及的组件 data-step 是否还对齐（如果改了 Story / Flow）
grep -oE 'data-step="[0-9]+"' "$F" | sort -u
浏览器打开，重点看改动的地方是否在视觉上没崩。
「改了 X / Y / Z。」
<p class="todo">...</p> 标黄。宁可方案看起来"有 5 处待补"，也不要把假数据写进 metric 卡当真——评审会按这些数字做决策。<a href="./xxx.html"> 互相引用）。<项目>/docs/tech-spec/<需求名>.html（或团队现有的方案 / 文档目录）<需求名>/ 子目录下partial-refund.html），将来若被发布工具收录可以直接作 URL 路径段