| name | tech-spec-html |
| description | 把一段需求 / 一段思考 / 一段会议纪要写成单页 HTML 格式的「技术方案 / Design Doc」（工程视角的"怎么做"，含背景、目标、技术方案、风险、影响范围、产研计划等模块；不是产品 PRD 的"做什么"），或者增量更新一份已有技术方案。新建场景：当用户说「写一份技术方案」「写个 design doc」「整理成 HTML 技术文档」「评审用的方案文档」「create tech spec」时使用。更新场景：当用户指向某份已有技术方案 HTML、说「评审完根据反馈调一下」「在风险章节加一条」「方案 A 改成 B」「补充某个章节」时也使用本 skill —— 走「最小化改动 + 保持文档稳定身份」的更新工作流而不是重写。 |
tech-spec-html
把一段需求 / 思考 / 会议纪要写成单页 HTML 格式的技术方案 / Design Doc。
目录
配套阅读：所有组件的完整 HTML / CSS 类名 / 代码示例在 references/components.md —— SKILL.md 主文件只保留「何时用哪个」的决策表，详细代码按需 lazy load。
为什么 HTML —— 核心是「图表 > 文字」
写作铁律（贯穿全文）：每写一节内容前，先问自己「这能不能用图 / 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 · 更新（保留那些稳定身份字段） |
不确定就问一句「这是新写一份方案，还是改 <已有路径> 那份？」。
工作流 A · 新建技术方案
A.1 先确认这份文档在讲什么
看到用户丢一段描述先别立刻动笔。用一两句话和用户对齐再写——读者是谁、范围多大、有没有现成素材（设计稿、已有接口、上次会议结论、相关代码路径）。
只问真的会改变文档结构的问题。「这是写给技术评审还是产品评审」会决定要不要展开技术细节，就该问；「标题用什么」用户没说就先按需求名起一个，不用问。
用户给的素材已经够厚（详细描述 / 一份纪要 / 代码 + 改造方向），可以跳过这一步直接动手。
A.2 起骨架，再填内容
复制 assets/template.html 到用户项目里——一般放 <项目>/docs/tech-spec/<需求名>.html。文件名用简短的英文 / 拼音（短名字可读、便于将来作为 URL 路径段）。
模板里已经有：标准章节、配色、字体、目录、9 类可视化组件示例、mermaid 加载、可打印样式、基础 meta 字段。
模板里的示例内容是占位 + 演示用（用了「部分退款」做例子），复制后改成方案的真实内容。看到 data-detail="..."、metric-value 里的数字、compare-card 的内容都要替换。
A.3 默认结构
按下面这个顺序组织。简化场景见下方「结构裁剪」。
每写一节前，先回到顶部的「写作铁律」：这一节有没有合适的图 / SVG / 组件能承载？能用就用，文字段落是兜底——一份方案如果通篇 bullet + 段落，就说明组件没用够。
- 背景：现状、痛点、可量化依据。一两段，不超过 6 行。
- 目标：按性质选形态，不要为了用组件而编数字——评审会按这些数字做决策，假数字是 bug。
- 业务目标：
- 有明确「现状 → 目标」数字的：用 metric cards（1-3 张，能体现差距即可，不必硬凑 4 张）
- 现状 / 目标对比清晰但维度多：用 3 列小表格（维度 / 现状 / 目标）
- 无量化基线 / 定性目标（"统一对账契约"、"为后续扩展付费方式留余量"）：用 bullet，每条 1 句话点结论
- 技术目标：默认 bullet（架构 / 可维护性 / 可扩展性 / 可观测性 这些大多是定性的）。除非真有量化指标（如 "DB QPS 降 90%"、"P99 从 3s 降到 200ms"），再考虑 metric。
- 技术方案：推荐子节顺序按「建立空间感 → 决策依据 → 拆分 → 状态 → 细节」组织。
- 3.1 系统全景（必备 · 方案开篇）：让读者一打开就建立空间感。两张图缺一不可：
- 分层架构图（Architecture SVG，模板已内置）：纵向 3-5 层，每层只与相邻层通信，hover 高亮单层 / 节点
- 主流程图（Flow SVG，模板已内置）：核心业务的端到端路径，4-8 个节点把"输入→处理→产出"串通
- 复杂方案可加：边界图（三方协作 / 复用 vs 自建 / 联动范围）
- 3.2 技术选型：用 compare grid 卡片，推荐方案加
is-pick 类，每卡含优 / 缺点 / 评分点数。
- 3.3 模块拆分：表格，列「模块 / 职责 / 对外接口」。让人看到方案是怎么切分协作单元的。
- 3.4 数据模型（可选 · 涉及独立数据存储时必备）：标准四段式（详见
components.md#k-数据模型四段式）：
- 数据域 + 实体清单（表格列：域 / 实体 / 一句话职责）
- 核心实体关系（mermaid
erDiagram 或带 PK/FK 强调的文字清单）
- 表设计（每张表字段 + 索引 + 约束，长表用
<details class="fold"> 折叠）
- 多企业 / 多租户隔离方案（如有）
- 3.5 状态机（可选 · 涉及状态流转时）：方案涉及订单 / 退款 / 工单 / 工作流时用 SVG 状态机图。无状态流转删掉。
- 3.6 数据流时序（可选）：mermaid
sequenceDiagram 补充跨服务调用细节。mermaid 适合时序，SVG 适合架构 / 流程 / 状态。
- 3.7 外部依赖与对接（可选 · 涉及上下游对接时）：上游数据依赖（列表 + 适配方式）、出站消息能力（事件 / 模板 / 限流）、对接适配层接口契约。
- 3.8 详细设计：核心数据结构、接口签名、字段定义、错误码、降级方案。
- 业务复杂时按业务模块拆 h4（M1 / M2 / M3 …），每模块覆盖五元组：数据（用了哪张表 / 哪些字段）/ 接口（mtop 或 RPC 签名）/ 状态机（自身或子流程）/ UI 演示（browser-mockup + demo-ui 控件族）/ 业务约束（前置 / 后置 / 不变量）
- 长字段定义 / 完整错误码用
<details class="fold"> 折叠，避免压垮主线
- 待确认事项（可选 · 长方案推荐）：起一张集中表（类别 / 事项 / 责任人 / 预期完成时间）。正文里散落的
<p class="todo"> 和 <span class="todo-tag">TODO</span> 都汇总到这一节，便于评审后按 owner 分头推进。短方案（< 1000 字、无明显未定项）直接省略，不留空标题。
- 技术风险分析：先用 risk matrix 2×2 把风险按「概率 × 影响」放到网格，再用表格列出每个风险的缓解方案。dot 上的编号对应表格行。
- 影响范围：4 卡片组织——代码 / 接口、数据 / 配置、上下游依赖、灰度 / 回滚。项目独立部署时这一节只列对已有系统的改动与对接需求，自身仓库 / DB / 部署链路不计入。
- 产研计划：
- 人员用 kv 列表。
- 里程碑用 timeline 甘特组件（横向轴 + 任务条），甘特能看到时间重叠和依赖，比表格直观。
结构裁剪
不是每份方案都要全部模块。少哪一块就在 HTML 里把整个 section 删掉，不留空标题。
- 纯产品向文档（虽然本 skill 主要写技术方案，偶尔会用）：技术选型 / 系统分层 / 状态机 / 模块拆分 / 详细设计 都可省，换成「用户场景 / 功能列表 / 交互流程（仍用 flow SVG）/ 数据指标」。
- 纯性能优化：业务目标压缩成一句，火力放在 metric cards（QPS / P99 / 缓存命中率）+ 详细设计 + 风险矩阵。
- 运营活动 / 数据补丁：可能只需要「背景 / 操作步骤（flow SVG）/ 风险 / 回滚」四节。
A.4 可视化组件
先看高层选型原则 · 口诀：需要画 → SVG；需要排 → HTML + CSS；标准时序 / ER → mermaid。
判断逻辑：
- 位置 / 几何承载语义（坐标即数据：风险矩阵的 dot 位置、甘特任务条的长度和位置、流程图节点的关系） → SVG，坐标驱动 + 节点级交互
- 文字 + 列表 + 卡片 + 表格为主（metric 卡的数字、方案对比卡的优缺点、字段定义表） → HTML + CSS，文字渲染 / 复制 / 选中 / 断行强
- 标准时序图 / ER 图 / 类图 → mermaid，DSL 一行画一关系比手写 SVG 高效
反模式警示：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。
A.5 写作风格
模板定好了排版，内容质量靠这几条：
- 能用组件 / 图就别用段落 —— 本 skill 最重要的一条。看到「风险」想到 risk matrix，看到「方案」想到 compare grid，看到「流程」想到 flow SVG，看到「指标」想到 metric cards，看到「时间」想到 timeline。
- 段落不超过 4 行。超过就拆，或升级成组件。
- 代码片段只放关键部分。完整代码链接到 git，方案里只贴决定方案性质的那 10-20 行；超过 30 行的代码块用
<details class="fold"> 折叠。
- 每个 section 第一句话先点结论，再展开。让人扫第一句就知道这一节讲什么。
- 专有名词第一次出现时带一句解释。评审里常有非技术同事。
- 不写"不是 A 而是 B" 这种句式。
- 未定的事用
<p class="todo">...</p> 标黄，让人一眼看到要补的地方，避免用模糊的"待定 / TBD"埋雷。
A.6 元信息
模板的 <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）。
A.7 收尾 + 自检
自动检查（Claude 自己跑）
F=<新写的 html 路径>
grep -nE '需求标题|示例·|\{\{|TBD|XXX' "$F"
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
echo "mermaid open=$(grep -c '<pre class="mermaid">' "$F") close=$(grep -cE '</pre>' "$F")"
grep -E '<title>|name="author"|name="date"|name="status"' "$F" | wc -l
人工预览（请用户做）
- 浏览器打开看实际渲染：mermaid 是否渲染、SVG 在窄屏下是否溢出、metric 数字是否拼错、timeline 百分比是否算错、risk dot 位置是否对、Story 步骤切换是否正常工作
- print preview 看打印效果（长方案评审会有人打出来）
告知用户
「文件已写到 <路径>。」
工作流 B · 更新已有技术方案
技术方案是动态的：第一稿评审后会改、需求迭代会改、对齐了新决策会改。更新场景的核心是「最小化改动」+「保持文档稳定身份」——重写整个 HTML 会丢评审上下文，丢失稳定身份字段会让其他系统（发布工具、文档索引）把这份文档当成新的、和历史版本失去关联。
B.1 先读，再改
收到更新任务的第一件事：用 Read 工具读完整个现有 HTML。不读就动手是有风险的——不知道当前用了哪些组件、有没有稳定身份 meta、哪些是定稿、哪些是 TODO 标黄。
读完后心里要清楚：
- 现有结构：用了哪些 section、哪些组件
- meta 状态：head 里有哪些
name="*-id" 类稳定身份字段——这些是其他系统注入的，必须原样保留
- 当前 status：是 draft / reviewing / final / archived
- 哪里已经写实、哪里还是
.todo 标黄
B.2 只改用户指明的部分
用 Edit 工具做精确替换，不用 Write 重写整个文件。即便看到"顺手可以优化"的地方也克制——评审同事可能已经在某个文档平台上看过当前版本、记住了某些段落的位置、甚至贴了链接给上下游，重写会让他们的心智模型失效。
「最小改动」具体怎么做：
- 改个数字 / 加一行表格 / 改一段话 → 一次 Edit 精确替换该段
- 替换某个章节内容（比如方案 A → 方案 B）→ Edit 替换该
<section> 或 <h3> 之间的内容
- 加 section / 删 section → Edit 插入或删除整段，同时更新顶部
nav.toc 的对应链接，同时修正后续 <span class="num">XX · ...</span> 的章节编号
- 加 h3 / 删 h3 / 加 h4 / 删 h4（子节增删）→ 同步重编号所有兄弟节点（如删了 3.4.5，3.4.6 应改为 3.4.5，避免跳号）+ 同步 TOC 二三级 li + 同步内部交叉引用
<a href="#sec-3-4-X">。LLM 在更新场景最常见的 bug 就是只删内容忘了重编号
- 改章节编号 → 所有 h2 的
.num span + nav.toc 的对应 li + 正文里所有引用编号的位置（"详见 3.4.2"）都要同步改
B.3 增量内容用现有组件
新加的内容尽量复用模板里已有的组件，保持视觉一致：
| 用户说要加 | 用哪个组件 |
|---|
| 加一个新风险 | 在 .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 项」 |
B.4 保持稳定身份
如果现有 HTML 的 <head> 里有形如以下的字段：
<meta name="doc-id" content="...">
<meta name="page-id" content="...">
<meta name="published-url" content="...">
原样保留 content，不要改 / 不要删。这些字段是别的工具（发布 / 索引 / 文档平台）写入的稳定身份，丢了或改了会让那些系统认不出这是同一份文档，可能造成历史版本断裂或重复创建。本 skill 不生成这些字段，但要保护它们。
判断范围简单粗暴：head 里所有 name 以 -id 或 -url 结尾的 meta 都按"保留"处理。
B.5 可以动的元信息
<title> —— 标题可改（其他系统的索引展示可能会跟着变）<meta name="status"> —— 评审推进时可能 draft → reviewing → final。如果用户的更新意图明显是"评审完定稿"，主动建议 status 推进<meta name="date"> —— 改成当天日期反映本次更新时间<meta name="author"> —— 一般保持原值，除非这次实际改动人换了
B.6 大改 vs 小改的判断
| 改动规模 | 怎么做 |
|---|
| 改个数字、改一行表格、加一条 bullet | 直接 Edit，不需要再确认 |
| 替换某个 section 内容 / 加一个 section | 直接 Edit，改完用一句话告诉用户改了什么 |
| 整体改结构 / 删多个 section / 改默认顺序 | 改之前先把方案告诉用户：「我打算把 X 删掉、Y 替换成 Z、TOC 同步更新，对吗？」得到确认再动手 |
| 用户说"重写"但你看下来其实只需要改两段 | 提示用户「这份方案我看下来只需改 X 和 Y，其他章节保留是不是更合适？」避免误删 |
B.7 改完后告诉用户做了什么
只说"文件已更新"用户没法知道改了啥。具体说：
- 「在 4.1 风险矩阵新增了 R4（对账延迟），表格也加了一行；其他章节未动。」
- 「方案 A 改成方案 B：
is-pick 类移到 B 卡，A 卡保留作为对比记录。3.7 详细设计里的接口签名也同步改了。」
- 「Story Walkthrough 第 3 步金额从 ¥500 改成 ¥1000，第 4 步审批规则文案同步更新。」
改动涉及 status 推进（draft → reviewing → final）也告知：「我把 status 改成了 reviewing；不需要改就告诉我」。
B.8 收尾 + 自检
自动检查（Claude 自己跑）
F=<改过的 html 路径>
grep -E 'name="[^"]*-id"|name="[^"]*-url"' "$F"
echo "h2 nums:"; grep -oE '<span class="num">[^<]+' "$F"
echo "toc items:"; grep -oE 'href="#[^"]+"' "$F"
grep -oE 'data-step="[0-9]+"' "$F" | sort -u
人工预览（请用户做）
浏览器打开，重点看改动的地方是否在视觉上没崩。
告知用户
「改了 X / Y / Z。」
边界情况
- 用户只给一段口语描述，信息不全：不凭空脑补字段、接口、流程图细节、metric 数字。已知的写实、未知的写成
<p class="todo">...</p> 标黄。宁可方案看起来"有 5 处待补"，也不要把假数据写进 metric 卡当真——评审会按这些数字做决策。
- 用户给的是会议纪要 / 长聊天记录：先抽出"已定的事 / 未定的事 / 下一步要决的事"三栏，已定的作为方案主体，未定的放进「待确认」section 标黄或用 compare grid 列两个候选方案让评审决。
- 用户已经有一份 Markdown 方案想转 HTML：读 Markdown 内容、按默认结构重组进模板。不要逐行翻译——Markdown 里用段落写的结构化内容（风险列表、字段定义、对比、指标）要升级成组件（risk matrix、details、compare grid、metric cards）。这是从 Markdown 转 HTML 的核心价值，否则用户为什么要转？
- 方案太长（> 5000 字）：考虑做 tab 切分，或拆成多个相互链接的 HTML 子页（用
<a href="./xxx.html"> 互相引用）。
- 用户描述的范围明显超出一次需求评审：先问要不要拆成多个方案，不要一份 HTML 装一切。
- 用户要求加交互组件（滑块调参、对比工具、可折叠决策树）：模板没内置这些，按需手写。HTML 的优势就是可以塞进任何交互，但只在能让评审更高效的地方加，不为花哨而加。
文件位置惯例
- 技术方案 HTML 放
<项目>/docs/tech-spec/<需求名>.html（或团队现有的方案 / 文档目录）
- 资源（图片、子页 HTML）放同目录或
<需求名>/ 子目录下
- 文件名用简短的英文 / 拼音，全小写、中划线分隔（如
partial-refund.html），将来若被发布工具收录可以直接作 URL 路径段
