feat(tech-diagram): 新增 6 套可选视觉风格 (#19)

## 概述 / Summary

给 tech-diagram 技能新增 **6 套可选视觉风格**(借鉴 fireworks-tech-graph 的多风格能力,落到
Mermaid 路线)。

Adds **6 selectable visual styles** to the tech-diagram skill (inspired
by fireworks-tech-graph's multi-style system, realized on the Mermaid
route).

## 改动 / Changes

- 新增 `references/styles.md`:6 套现成"风格头部"(`%%{init}%%` + 5 个 `classDef`)
- `brand-light`(默认)/ `brand-dark` / `terminal` / `blueprint` / `cream` /
`mono`
- `SKILL.md` / `SKILL.zh-CN.md`:新增 **Styles / 风格** 小节,改写规则
1/2,描述与触发词加入风格相关词
- `semantic-vocabulary.md` / `templates.md`:指向 styles.md,说明换风格只换头部
- 版本 `1.0.0 → 1.1.0`

## 设计要点 / Design

- **类名跨风格一致**(`agent/system/biz/warn/error`)——切换风格只替换头部块,节点/连线图体完全不变。
- 默认 `brand-light`;用户说"暗色/蓝图/奶油/极简/极客"或"风格 N"即切换。
- 图表是**用户产物**,非 `brand-*` 风格有意跳出 app 的 3+2 色彩规则(该规则约束产品 UI,不约束导出图)。
- Mermaid 能力边界内:风格 = 调色板 + 字体;fireworks 那种渐变光斑/窗口控件/蓝图标题框需原生 SVG,不在本次范围。

## 验证 / Verification

-  `scripts/i18n/validate-i18n.py`:无问题(heading 数 9=9 对齐)
-  用客户端同版本 **mermaid 11.15.0** 解析全部 11 个图块(5 模板 + 6 风格骨架),全部通过
This commit is contained in:
2026-05-31 19:49:33 +08:00
committed by GitHub
parent e9862ef1ab
commit f2e48ca1a5
5 changed files with 260 additions and 104 deletions

View File

@@ -2,7 +2,7 @@
# tech-diagram 技能
把自然语言描述转成品牌一致的技术图。你在回复中写 **Mermaid**DesireCore 对话会即时渲染为 SVG。本技能的核心价值是一致性每张图都用同一套 DesireCore 3+2 配色和同一套语义形状/箭头词汇表,让所有图看起来像出自同一个产品
把自然语言描述转成致的技术图。你在回复中写 **Mermaid**DesireCore 对话会即时渲染为 SVG。本技能的核心价值是一致性固定的语义形状/箭头词汇表,加上六套自洽的视觉风格(默认 `brand-light`),让每张图都连贯且统一
## 何时使用
@@ -14,35 +14,39 @@
以下规则不可妥协,违反会产出偏离品牌或无法渲染的图。
1. **每张图必须以品牌 `%%{init}%%` 指令开头** 对话的全局 Mermaid 主题写死为暗色init 指令按图覆盖它,从而输出浅色且品牌一致。固定使用:
```
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F0F5FF','primaryBorderColor':'#007AFF','primaryTextColor':'#1d1d1f','lineColor':'#6e6e73','fontFamily':'-apple-system,SF Pro Text,Noto Sans SC,sans-serif'}}}%%
```
2. **配色只能取自 DesireCore 3+2 体系,通过 `classDef` 绑定。** 禁止使用 Mermaid 默认色或任何非 3+2 色值。下面五个 class 是唯一允许的色板:
```
classDef agent fill:#F6F3FF,stroke:#AF52DE,color:#1d1d1f
classDef system fill:#F0F5FF,stroke:#007AFF,color:#1d1d1f
classDef biz fill:#F0FDF4,stroke:#34C759,color:#1d1d1f
classDef warn fill:#FFFBF0,stroke:#FF9500,color:#1d1d1f
classDef error fill:#FFF0F0,stroke:#FF3B30,color:#1d1d1f
```
色值来自 DesireCore app 代码库(`app/theme/tokens/index.ts`green `#34C759` / blue `#007AFF` / purple `#AF52DE` / orange `#FF9500` / red `#FF3B30`,以及 `cardBgColors` / `cardBorderColors`;这些 app 路径不在本 market 仓库内)。选 class 的规则与 `agent-colors.ts` 一致:系统/通用→blue知识/学习→purple业务/执行→green项目管理/警示→orange错误→red。
1. **每张图必须以某风格的 `%%{init}%%` 指令开头**(用它覆盖对话写死的暗色全局主题)。除非用户另有要求,默认用 `brand-light`(见下方**风格**)。`references/styles.md` 的预设是完整的 **flowchart** 骨架(`%%{init}%%` + `flowchart TD` + 五个 `classDef`):画 flowchart 时整块复制;画其他类型(`sequenceDiagram` / `stateDiagram-v2` / `erDiagram` / `classDiagram` / `mindmap`)时**只复制首行 `%%{init}%%`**——`flowchart TD` + `classDef` 块是 flowchart 专用,仅 `%%{init}%%` 首行即可给它们风格的底色与字体。
2. **flowchart 内每个节点都用这五个 `classDef` 上色,不要临时写 hex**(其他图类型只继承风格的 `%%{init}%%` 底色与字体;`classDef` 块是 flowchart 专用)。类名——`agent` / `system` / `biz` / `warn` / `error`——在所有风格里都相同,所以换风格时 flowchart 图体完全不用改。按角色选类:系统/通用→`system`,知识/学习→`agent`,业务/执行→`biz`,项目管理/警示/决策→`warn`,错误/失败→`error`
3. **使用下面的语义形状**,不要随意选形状。
4. **标签含标点、括号或 `/` 时必须加引号**,避免 Mermaid 解析失败,例如 `A["查询 / 检索"]`
## 风格
六套可选视觉风格放在 `references/styles.md`,每套是一段现成的 **flowchart** 头部(`%%{init}%%` + 五个 `classDef`;非 flowchart 图类型只复制 `%%{init}%%` 首行,见规则 1。换风格只换头部节点/连线图体不变。
| 风格 | 外观 | 适用 |
|------|------|------|
| `brand-light`(默认) | 白底、DesireCore 3+2 强调色 | 博客、幻灯片、文档 |
| `brand-dark` | 近黑底、3+2 强调色 | 与 app 暗色模式一致 |
| `terminal` | `#0f0f1a`、霓虹强调、等宽字 | GitHub / 开发者文章 |
| `blueprint` | 深蓝底、青/白、等宽字 | 架构规范 |
| `cream` | 暖奶油底、赤褐/鼠尾草/紫 | Anthropic 风演示 |
| `mono` | 纯白、灰阶 | Notion / Wiki |
按用户措辞选("暗色/dark"、"蓝图/blueprint"、"奶油/cream"、"极简/mono"、"极客/terminal",或"风格 N / style N"),否则用 `brand-light`。图表是用户产物,所以非 `brand-*` 的调色板**有意**跳出 app 的 3+2 色彩规则(该规则约束产品 UI不约束导出的图。每套预设内部自洽。
## 语义词汇表
形状本身承载含义(完整表见 `references/semantic-vocabulary.md`
形状本身承载含义(完整表见 `references/semantic-vocabulary.md`)。类的颜色随风格变化,固定的只是"角色→类"映射
| 概念 | Mermaid 形状 | classDef |
|------|-------------|----------|
| Agent / 智能体 | 六边形 `id{{...}}` | agent (purple) |
| DesireCore 核心 / 系统 | 圆角 `id(...)` | system (blue) |
| LLM / 模型 | 圆角 `id(⚡ ...)` | system (blue) |
| 业务 / 执行节点 | 矩形 `id[...]` | biz (green) |
| 记忆 / 存储 | 圆柱 `id[(...)]` | system (blue) |
| 用户 | 体育场形 `id([...])` | biz (green) |
| 决策 / 分支 | 菱形 `id{...}` | warn (orange) |
| Agent / 智能体 | 六边形 `id{{...}}` | agent |
| DesireCore 核心 / 系统 | 圆角 `id(...)` | system |
| LLM / 模型 | 圆角 `id(⚡ ...)` | system |
| 业务 / 执行节点 | 矩形 `id[...]` | biz |
| 记忆 / 存储 | 圆柱 `id[(...)]` | system |
| 用户 | 体育场形 `id([...])` | biz |
| 决策 / 分支 | 菱形 `id{...}` | warn |
| 外部服务 | 虚线 `subgraph` | — |
## 箭头与流编码
@@ -64,7 +68,8 @@ DesireCore 自身 Pattern 的现成 Mermaid 放在 `references/templates.md`*
## 常见错误
- ❌ 漏掉 `%%{init}%%` → 图会沿用全局暗色主题。
- ❌ 硬编码非 3+2 色值或 Tailwind 默认色,而非用 `classDef`。
- ❌ 漏掉风格头部 → 图会沿用全局暗色主题。
- ❌ 在节点上临时写 hex而非用所选风格的五个 `classDef`
- ❌ 一张图里混用两套风格的头部。
- ❌ 节点标签过长撑爆布局。
- ❌ 含 `()``/` 或中文标点的标签未加引号 → Mermaid 解析失败。