---
name: feature-design-doc
description: "当新功能/跨模块/改用户可见行为/触及外部服务·支付·数据进入设计阶段时使用:产出 WHAT+HOW 合一的功能设计文档——文字+Mermaid 为事实源、SVG/HTML 给人看,含第 0 步 SoT 注册表查证、sot-impact/上级申报、防漂移单源与文档骨架。"
---

# 功能设计文档作业手册（feature-design-doc）

> **定位修订(2026-07-09,创始人)**:两份产物重新定位——**人审版 = brainstorm / SoT 设计文档**(方向诊断落 brainstorm,设计本体直接改所属 SoT,人审对象就是 SoT diff 与 brainstorm),**执行版 = `docs/plans/` 的 plan**(工单六要素,可派单)。已有 SoT 的改动**不再另造平行"功能设计文档"**——先改 SoT 的意识是硬要求;独立设计档只留给"尚无 SoT 的全新子系统"(产出后它本身成为/并入 SoT)。本 skill 的骨架、图规范、防漂移纪律对 SoT 设计档与上述独立设计档继续适用。
>
> 每个有真实复杂度的功能，开工前产出**一份**「功能设计文档」，取代旧的 `-review.md` + `-execution.md` 双档。一份文档同时承载 **WHAT**（意图/目标/边界/验证）与 **HOW**（方案/步骤），并以**一式两份**的表达服务两类读者：**文字 + Mermaid** 给人和 AI（AI 主靠它），**SVG / HTML** 给人（更重要，看图即懂边界与核心思想）。

## 何时用

- 新功能、跨模块、改变用户可见行为、触及外部服务 / 支付 / 数据的**设计阶段**。
- 简单、局部、低风险任务**不需要**——直接做，别为一次性改动套重型文档。

## 第 0 步(强制):先查 SoT 注册表

写任何设计前,先读 [`docs/architecture/README.md`](../../docs/architecture/README.md) §2 注册表与 [`docs/agent-specs/_index.md`](../../docs/agent-specs/_index.md) 在飞板:本设计触及哪些既有 topic?是修订某个 SoT、新建 topic,还是纯留痕?把结论写进 frontmatter 的 `sot-impact` 字段(docs-gate G6 机器强制)。这一步治的是"新设计漏读既有设计/全局设计"——跳过它,门会把设计档拦在提交外。收口时按申报把可存留结论折进对应 SoT,设计档降为留痕。

## 这份文档承载什么（WHAT + HOW 合一）

| 段 | 回答 | 要点 |
|---|---|---|
| 意图 | 为什么做 | 解决什么真实问题、不做会怎样 |
| 目标 | 要达成什么 | 尽量可量化（指标 / 验收线） |
| 边界 | 做 / 不做 | in scope / out of scope 一眼分清，挡住范围蔓延 |
| 方案 | 怎么实现（架构级） | 模块如何协作、关键设计决策与取舍 |
| 步骤计划 | 分几步落地 | 每阶段：交付物 / 验证 / 依赖 / 风险 |
| 验证 | 怎么算成功 | 验收标准、可观测信号 |

**禁令（硬约束）**：禁代码细节（函数签名 / 伪代码 / 具体实现——那是写代码时的事）；禁黑话 / AI 味 / 元叙述；方案与步骤只写**架构级 HOW**（做什么、谁产出什么、怎么验），不写代码级 HOW。

## 一式两份：四种表达的分工

| 媒介 | 读者 | 角色 | 在 md 里 |
|---|---|---|---|
| **文字（中文散文）** | 人 + AI | **事实源**，自洽——脱离图也能读懂全部设计；后续 AI 主要消费它 | 正文 |
| **Mermaid** | 人 + AI | 结构图（流程 / 状态 / 时序 / 依赖），文本可 diff、随文档同源 | 内联 ```mermaid``` 块 |
| **SVG** | 人（**更重要**） | 核心概览 / 边界 / 关系大图，看图即懂；颜色舒适、留白、核心路径高亮 | `assets/` 引用 inline |
| **HTML** | 人（可选增强） | 需交互 / 超丰富排版时的独立澄清页 | **链接**打开，不内联 |

**渲染现实（别踩）**：Markdown 渲染器（GitHub / Gitea）**直渲 Mermaid 与 inline SVG**，但**不内联渲染独立 `.html`**（md 内的 html 标签多被过滤）。所以——md 阅读流里**能直接看到的 = Mermaid + SVG**；HTML 只作「🔗 在浏览器打开交互版」的链接，**非必需**：SVG 能讲清就不上 HTML。

**媒介怎么选**：结构关系 / 流程 → Mermaid；「一眼看懂全局 / 边界 / 核心思想」→ SVG（本文档的门面）；确需交互（可展开、可切换、可点选）→ HTML 独立页。

## House style（复用，不另起）

功能设计文档的所有图，**配色 / 三线语义 / 徽章 / 脚注 / 转义 / 复验脚本一律照** [`architecture-diagram-atlas.md`](architecture-diagram-atlas.md)：浅底 `#f8fafc`、主字 `#0f172a`、实线=现行 / 虚线=自建远期、远期紫 `#7c3aed`、红线 `#dc2626`、圆角 `rx 7~12`、脚注全角「：」、SVG 文字内 `< > &` 必转义。

**侧重差异**：atlas 面向「据图找缝」，**功能设计文档面向「快速理解」**——更重留白、层次分明、核心路径高亮，别堆信息密度。颜色要舒适、对比柔和。

- SVG 在 6c6g 出文本；PNG 批量转在 **mini-desktop**（6c6g 禁 chrome）。见 [`staging-ops.md`](staging-ops.md)。

## 防漂移：一式两份的单一事实源

「两份」绝不能平等维护，否则必漂移（本项目反复踩的坑）：

- **文字 + Mermaid = 事实源**（随 md 走、可 diff）；**SVG / HTML = 派生视觉**。
- 设计变更：**先改文字 + Mermaid，再据此更新 SVG / HTML**；图文冲突**以文字为准**。
- frontmatter 防漂移门（复用 atlas）：记关联**代码 / 契约的 commit hash** + 图清单；收口比对 hash，对不上标「待复核」。
- 权威**细节**只写在文字里（图里重复一份 = 又一个漂移面）；图只承载**结构与边界的直觉**。

## 文档结构骨架

```
---
date / topic / status（草稿 | 评审中 | 已批准 | 已实现）
sot-impact: 新建 topic X | 修订 topic Y | 纯留痕     # G6 申报(第 0 步的产出)
上级: <仓根相对路径>     # G7 谱系单指针:本档的直接上级(通常是所属执行线的计划/SoT);填不出来 = 上级还没认领这条线,先回写上级再开工(§10.8)
关联: <代码 / 契约路径 + commit hash>     # 防漂移门
图清单: [图1 概览, 图2 边界, ...]
---
# <功能> 功能设计

## 0 一图看懂      # 顶部放最重要的 SVG 概览 + 三句话：核心思想 / 边界 / 怎么算成功
## 1 意图与目标    # 为什么做、要达成什么（可量化）
## 2 边界          # 做什么 / 不做什么（配边界图）
## 3 方案          # 架构级，关键决策与取舍（配结构图）
## 4 步骤计划      # 分阶段：交付物 / 验证 / 依赖 / 风险（配阶段图）
## 5 验证方式      # 验收标准、可观测信号
## 6 风险与回滚
## 附 图清单与状态 · HTML 增强页链接
```

**§0「一图看懂」是门面**：一张 SVG + 三句话，让人 30 秒抓住意图、边界、核心思想；这是本文档「给人读、更重要」的承诺所在。

## 生产与评审

- **文字层**由主会话 / opus 写，务必自洽——后续 AI 消费它，缺图也要能读懂全部设计。
- **图层**每图一 opus 子代理：克隆 atlas 金样板 → 画 → 跑复验脚本 → 对抗自检；house style 与散文铁律（连同正反例）**随 prompt 一起传下去**（只传「画图」不够，输出会回退 AI 味）。
- **评审**：这份文档仍过双评审门（Codex + Opus，Codex 挂回落 Opus 单评），对象 = 这一份文档。
- 命名 `docs/agent-specs/YYYY-MM-DD-<功能>-设计.md`；SVG / HTML 入同名或共享 `assets/`（顶层文档 → 子目录 assets 单向下引，别跨子目录引图）。

## 取代关系

取代旧的 `-review.md` + `-execution.md` 双档（2026-06-24 创始人定）。存量双档作 trace 留 git / `_archive`，**不强行合并历史**；新功能一律产这一份。

> 相关：[`architecture-diagram-atlas.md`](architecture-diagram-atlas.md)（house style / 复验脚本 / 三范式防漂移）、[`wave-close-checklist.md`](wave-close-checklist.md)（收口同步纪律）、[`../workflows/ai-development-protocol.md`](../workflows/ai-development-protocol.md)（设计在协议中的位置）。