mrlyk/tech-spec-html

tech-spec-html

把一段需求 / 思考 / 会议纪要写成单页 HTML 格式的技术方案 / Design Doc。

目录

• 为什么 HTML —— 核心是「图表 > 文字」
• 两种场景，先判断走哪条路
• 工作流 A · 新建技术方案（A.1 对齐意图 / A.2 起骨架 / A.3 默认结构 / A.4 组件决策表 / A.5 写作风格 / A.6 元信息 / A.7 收尾自检）
• 工作流 B · 更新已有技术方案（B.1 先读再改 / B.2 最小化改动 / B.3 增量用组件 / B.4 保持稳定身份 / B.5 可动元信息 / B.6 大改小改判断 / B.7 改完说清 / B.8 收尾自检）
• 边界情况
• 文件位置惯例

配套阅读：所有组件的完整 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 + 段落，就说明组件没用够。

1. 背景：现状、痛点、可量化依据。一两段，不超过 6 行。
2. 目标：按性质选形态，不要为了用组件而编数字——评审会按这些数字做决策，假数字是 bug。
   • 业务目标：
     • 有明确「现状 → 目标」数字的：用 metric cards（1-3 张，能体现差距即可，不必硬凑 4 张）
     • 现状 / 目标对比清晰但维度多：用 3 列小表格（维度 / 现状 / 目标）
     • 无量化基线 / 定性目标（"统一对账契约"、"为后续扩展付费方式留余量"）：用 bullet，每条 1 句话点结论
   • 技术目标：默认 bullet（架构 / 可维护性 / 可扩展性 / 可观测性 这些大多是定性的）。除非真有量化指标（如 "DB QPS 降 90%"、"P99 从 3s 降到 200ms"），再考虑 metric。
3. 技术方案：推荐子节顺序按「建立空间感 → 决策依据 → 拆分 → 状态 → 细节」组织。
   • 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"> 折叠，避免压垮主线
4. 待确认事项（可选 · 长方案推荐）：起一张集中表（类别 / 事项 / 责任人 / 预期完成时间）。正文里散落的 <p class="todo"> 和 <span class="todo-tag">TODO</span> 都汇总到这一节，便于评审后按 owner 分头推进。短方案（< 1000 字、无明显未定项）直接省略，不留空标题。
5. 技术风险分析：先用 risk matrix 2×2 把风险按「概率 × 影响」放到网格，再用表格列出每个风险的缓解方案。dot 上的编号对应表格行。
6. 影响范围：4 卡片组织——代码 / 接口、数据 / 配置、上下游依赖、灰度 / 回滚。项目独立部署时这一节只列对已有系统的改动与对接需求，自身仓库 / DB / 部署链路不计入。
7. 产研计划：
   • 人员用 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 路径>

# 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

人工预览（请用户做）

• 浏览器打开看实际渲染：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="...">          <!-- 文档稳定 ID -->
<meta name="page-id" content="...">         <!-- 或 page-id / *-id 类 -->
<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 路径>

# 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。」

边界情况

• 用户只给一段口语描述，信息不全：不凭空脑补字段、接口、流程图细节、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 路径段