feat: add tech-diagram skill (Mermaid 技术图生成) (#18)

## 概述 / Summary 新增市场技能 **tech-diagram**：把自然语言描述转成品牌一致的技术图（架构图/流程图/时序图/状态机/ER/类图/思维导图），在 DesireCore 对话内复用现有 Mermaid 渲染管线即时渲染为 SVG。 Adds a market skill **tech-diagram** that turns natural-language descriptions into brand-consistent technical diagrams, rendered inline as SVG by the existing Mermaid pipeline in the DesireCore chat. 灵感来源 / Inspired by [fireworks-tech-graph](https://github.com/yizhiyanhua-ai/fireworks-tech-graph) 的三个设计思路：语义词汇表即数据、风格系统化、领域 Pattern 内置——并落到 DesireCore 自己的 3+2 设计令牌与领域模型上。 ## 改动 / Changes - `skills/tech-diagram/SKILL.md` + `SKILL.zh-CN.md`：双语技能正文（强制风格规则 + 语义词汇表 + 输出约定） - `skills/tech-diagram/references/semantic-vocabulary.md`：概念→Mermaid 形状→3+2 classDef 完整映射 - `skills/tech-diagram/references/templates.md`：4 个 DesireCore 领域模板（Agent 架构 / Delegate 6 模式 / 三层记忆 / 关系图谱）+ 时序图示例 - `builtin-skills.json`：加入 `tech-diagram` - `manifest.json`：`version` 1.2.1→1.2.2，`stats.totalSkills` 21→22，`lastUpdated` ## 设计要点 / Design - **风格一致性**：每张图以 `%%{init}%%` 注入品牌主题（覆盖对话全局暗色），用 5 个 `classDef` 绑定 DesireCore 3+2 配色（green/blue/purple + warning orange / error red）。 - **语义优于视觉**：Agent→六边形、系统/记忆→圆角/圆柱、决策→菱形；箭头编码主数据流/记忆写入/异步/层级/上报。 - **领域内置**：直接对照 `delegate.ts` / `conversation-memory.ts` / `relations/projector.ts` 给出可套用模板。 ## 验证 / Verification - ✅ `scripts/i18n/validate-i18n.py`：无 i18n 问题 - ✅ 用 app 同版本 **mermaid 11.15.0**（securityLevel: loose）解析 `templates.md` 全部 5 个图块，全部通过
2026-06-06 05:50:41 +08:00 · 2026-05-30 23:56:27 +08:00
parent 4f7037a6b6
commit f4dfe8e32f
6 changed files with 431 additions and 3 deletions
--- a/builtin-skills.json
+++ b/builtin-skills.json
@@ -19,6 +19,7 @@
    "python-runtime",
    "s3-storage-operations",
    "skill-creator",
+    "tech-diagram",
    "update-agent",
    "web-access",
    "workflow",
--- a/manifest.json
+++ b/manifest.json
@@ -1,6 +1,6 @@
 {
  "name": "DesireCore Official Market",
-  "version": "1.2.1",
+  "version": "1.2.2",
  "schemaVersion": "1.1.0",
  "supportedLocales": ["zh-CN", "en-US"],
  "defaultLocale": "en-US",
@@ -27,8 +27,8 @@
  },
  "stats": {
    "totalAgents": 1,
-    "totalSkills": 21,
-    "lastUpdated": "2026-05-09"
+    "totalSkills": 22,
+    "lastUpdated": "2026-05-30"
  },
  "features": [
    "verified-only",
--- a/skills/tech-diagram/SKILL.md
+++ b/skills/tech-diagram/SKILL.md
@@ -0,0 +1,160 @@
+---
+name: tech-diagram
+description: >-
+  Use this skill when the user wants to turn a description into a technical
+  diagram — architecture diagrams, flowcharts, sequence diagrams, state
+  machines, ER diagrams, class diagrams, or mind maps. Generates brand-consistent
+  Mermaid that the DesireCore chat renders inline as SVG, styled with the
+  DesireCore 3+2 design tokens and a semantic shape/arrow vocabulary. Use this
+  for diagrams of structure, flow, or relationships — NOT for photographic or
+  illustrative images (use an image-generation skill for those).
+  Use when 用户提到 画架构图、架构图、流程图、时序图、序列图、状态图、状态机、
+  ER图、类图、思维导图、出图、画图、可视化、画一张图、画个图、draw diagram、
+  architecture diagram、flowchart、sequence diagram。
+version: 1.0.0
+type: procedural
+risk_level: low
+status: enabled
+disable-model-invocation: false
+tags:
+  - diagram
+  - mermaid
+  - architecture
+  - flowchart
+  - visualization
+metadata:
+  author: desirecore
+  updated_at: '2026-05-30'
+  i18n:
+    default_locale: en-US
+    source_locale: zh-CN
+    locales:
+      - zh-CN
+      - en-US
+    zh-CN:
+      name: 技术架构图生成
+      short_desc: 用 Mermaid 画品牌一致的架构图/流程图/时序图，对话内即时渲染
+      description: >-
+        当用户希望把描述转成技术图时使用此技能——架构图、流程图、时序图、状态机、ER 图、类图或思维导图。生成符合 DesireCore 3+2 设计令牌与语义形状/箭头词汇表的 Mermaid，对话内即时渲染为 SVG。用于结构、流程或关系类图，而非写实摄影/插画类图片（后者请用文生图技能）。用户提到 画架构图、架构图、流程图、时序图、序列图、状态图、状态机、ER图、类图、思维导图、出图、画图、可视化、画一张图、画个图。
+      body: ./SKILL.zh-CN.md
+      source_hash: 'sha256:1f74e524df631a67'
+      translated_by: human
+    en-US:
+      name: Tech Diagram Generator
+      short_desc: Draw brand-consistent architecture/flow/sequence diagrams with Mermaid, rendered inline in chat
+      description: >-
+        Use this skill when the user wants to turn a description into a technical diagram — architecture diagrams, flowcharts, sequence diagrams, state machines, ER diagrams, class diagrams, or mind maps. Generates brand-consistent Mermaid that the DesireCore chat renders inline as SVG, styled with the DesireCore 3+2 design tokens and a semantic shape/arrow vocabulary. Use this for diagrams of structure, flow, or relationships — not for photographic or illustrative images.
+      body: ./SKILL.md
+      source_hash: 'sha256:1f74e524df631a67'
+      translated_by: human
+market:
+  icon: >-
+    <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0
+    24 24" fill="none"><rect x="3" y="3" width="7" height="7" rx="1.5"
+    stroke="#007AFF" stroke-width="1.5" fill="#007AFF"
+    fill-opacity="0.12"/><rect x="14" y="3" width="7" height="7" rx="1.5"
+    stroke="#AF52DE" stroke-width="1.5" fill="#AF52DE" fill-opacity="0.12"/><rect
+    x="8.5" y="15" width="7" height="6" rx="1.5" stroke="#34C759"
+    stroke-width="1.5" fill="#34C759" fill-opacity="0.12"/><path d="M6.5 10v2.5h11V10"
+    stroke="#6e6e73" stroke-width="1.2"/><path d="M12 12.5V15" stroke="#6e6e73"
+    stroke-width="1.2"/></svg>
+  short_desc: Draw brand-consistent architecture/flow/sequence diagrams with Mermaid
+  category: development
+  maintainer:
+    name: DesireCore Official
+    verified: true
+  channel: latest
+---
+
+# tech-diagram Skill
+
+Turn a natural-language description into a brand-consistent technical diagram.
+You write **Mermaid** in your reply; the DesireCore chat renders it inline as SVG.
+The point of this skill is consistency: every diagram uses the same DesireCore
+3+2 palette and the same semantic shape/arrow vocabulary, so diagrams look like
+they belong to one product.
+
+## When to Use
+
+Use this skill for diagrams of **structure, flow, or relationships**:
+architecture, flowchart, sequence, state machine, ER, class diagram, mind map.
+
+Do NOT use it for photographic or illustrative pictures — route those to an
+image-generation skill (e.g. dashscope-image-gen, minimax-image-gen).
+
+## Mandatory Style Rules
+
+These are non-negotiable. Violating them produces off-brand or unrendered diagrams.
+
+1. **Every diagram MUST start with the brand `%%{init}%%` directive.** The chat's
+   global Mermaid theme is hardcoded to dark; the init directive overrides it per
+   diagram so output is light and brand-consistent. Use exactly:
+   ```
+   %%{init: {'theme':'base','themeVariables':{'primaryColor':'#F0F5FF','primaryBorderColor':'#007AFF','primaryTextColor':'#1d1d1f','lineColor':'#6e6e73','fontFamily':'-apple-system,SF Pro Text,Noto Sans SC,sans-serif'}}}%%
+   ```
+2. **Color ONLY from the DesireCore 3+2 system via `classDef`.** Never use Mermaid
+   default colors or any non-3+2 hex. The five classes below are the only palette:
+   ```
+   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
+   ```
+   Values come from the DesireCore app codebase (`app/theme/tokens/index.ts` —
+   green `#34C759` / blue `#007AFF` / purple `#AF52DE` / orange `#FF9500` / red
+   `#FF3B30` — and `cardBgColors` / `cardBorderColors`; these app paths are not in
+   this market repo). Pick the class by the same rule as `agent-colors.ts`:
+   system/generic → blue, knowledge/learning → purple, business/execution → green,
+   project-management/warning → orange, error → red.
+3. **Use the semantic shapes below**, not arbitrary ones.
+4. **Quote any node label that contains punctuation, parentheses, or `/`** to avoid
+   Mermaid parse errors, e.g. `A["Query / Retrieve"]`.
+
+## Semantic Vocabulary
+
+Shape carries meaning (see `references/semantic-vocabulary.md` for the full table):
+
+| Concept | Mermaid shape | classDef |
+|---------|---------------|----------|
+| Agent / 智能体 | hexagon `id{{...}}` | agent (purple) |
+| DesireCore core / system | rounded `id(...)` | system (blue) |
+| LLM / model | rounded `id(⚡ ...)` | system (blue) |
+| Business / execution node | rect `id[...]` | biz (green) |
+| Memory / store | cylinder `id[(...)]` | system (blue) |
+| User | stadium `id([...])` | biz (green) |
+| Decision / branch | diamond `id{...}` | warn (orange) |
+| External service | dashed `subgraph` | — |
+
+## Arrow / Flow Encoding
+
+| Flow | Mermaid edge |
+|------|--------------|
+| Primary data flow | `-->` solid |
+| Memory write / persistence | `-.->` dotted |
+| Async event | `-.->|async|` dotted + label |
+| Feedback / retry loop | back-edge `-->` to an earlier node |
+
+## Built-in Templates
+
+Ready-to-use Mermaid for DesireCore's own patterns lives in
+`references/templates.md`: **Agent architecture**, **Delegate 6 modes**,
+**three-tier conversation memory** (active → recent L0/L1 → archive L2), and the
+**relation graph** (6 edge types: delegate / mention / co_task / hierarchy /
+seek_help / escalation). Adapt them to the user's subject instead of starting
+from scratch.
+
+## Output Convention
+
+Emit the diagram directly in your reply inside a fenced code block whose info
+string is `mermaid` (open the fence with three backticks immediately followed by
+the word mermaid). The chat renders it to SVG automatically; on a syntax error it
+falls back to showing the raw code (the `mermaid-fallback` path), so the source
+MUST be valid. Keep node labels short — long text breaks the layout.
+
+## Common Mistakes
+
+- ❌ Omitting `%%{init}%%` → the diagram inherits the global dark theme.
+- ❌ Hardcoding non-3+2 hex or Tailwind default colors instead of the `classDef`s.
+- ❌ Overlong node labels that overflow the layout.
+- ❌ Unquoted labels with `()`, `/`, or CJK punctuation → Mermaid parse failure.
--- a/skills/tech-diagram/SKILL.zh-CN.md
+++ b/skills/tech-diagram/SKILL.zh-CN.md
@@ -0,0 +1,70 @@
+<!-- locale: zh-CN -->
+
+# tech-diagram 技能
+
+把自然语言描述转成品牌一致的技术图。你在回复中写 **Mermaid**，DesireCore 对话会即时渲染为 SVG。本技能的核心价值是一致性：每张图都用同一套 DesireCore 3+2 配色和同一套语义形状/箭头词汇表，让所有图看起来像出自同一个产品。
+
+## 何时使用
+
+用于**结构、流程或关系**类的图：架构图、流程图、时序图、状态机、ER 图、类图、思维导图。
+
+不要用它生成写实摄影或插画类图片——那类需求请转给文生图技能（如 dashscope-image-gen、minimax-image-gen）。
+
+## 强制风格规则
+
+以下规则不可妥协，违反会产出偏离品牌或无法渲染的图。
+
+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。
+3. **使用下面的语义形状**，不要随意选形状。
+4. **标签含标点、括号或 `/` 时必须加引号**，避免 Mermaid 解析失败，例如 `A["查询 / 检索"]`。
+
+## 语义词汇表
+
+形状本身承载含义（完整表见 `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) |
+| 外部服务 | 虚线 `subgraph` | — |
+
+## 箭头与流编码
+
+| 流类型 | Mermaid 边 |
+|--------|-----------|
+| 主数据流 | `-->` 实线 |
+| 记忆写入 / 持久化 | `-.->` 点线 |
+| 异步事件 | `-.->|async|` 点线 + 标签 |
+| 反馈 / 重试循环 | 指回前序节点的回边 `-->` |
+
+## 内置模板
+
+DesireCore 自身 Pattern 的现成 Mermaid 放在 `references/templates.md`：**Agent 架构图**、**Delegate 6 模式**、**三层对话记忆**（active → recent L0/L1 → archive L2）、**关系图谱**（6 种边：delegate / mention / co_task / hierarchy / seek_help / escalation）。请基于这些模板改写为用户的主题，而非从零开始。
+
+## 输出约定
+
+直接在回复中用栅栏代码块输出图，info string 为 `mermaid`（用三个反引号紧跟单词 mermaid 开启栅栏）。对话会自动渲染为 SVG；语法出错时会降级展示原始代码（`mermaid-fallback` 路径），所以源码必须合法。节点标签要短——文字过长会撑坏布局。
+
+## 常见错误
+
+- ❌ 漏掉 `%%{init}%%` → 图会沿用全局暗色主题。
+- ❌ 硬编码非 3+2 色值或 Tailwind 默认色，而非用 `classDef`。
+- ❌ 节点标签过长撑爆布局。
+- ❌ 含 `()`、`/` 或中文标点的标签未加引号 → Mermaid 解析失败。
--- a/skills/tech-diagram/references/semantic-vocabulary.md
+++ b/skills/tech-diagram/references/semantic-vocabulary.md
@@ -0,0 +1,78 @@
+# Semantic Vocabulary (语义词汇表)
+
+The full mapping from concept → Mermaid shape → DesireCore 3+2 class. Shape and
+color encode meaning, so a reader understands a diagram without a legend.
+
+## The brand header (paste verbatim as the first line of every diagram)
+
+```
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F0F5FF','primaryBorderColor':'#007AFF','primaryTextColor':'#1d1d1f','lineColor':'#6e6e73','fontFamily':'-apple-system,SF Pro Text,Noto Sans SC,sans-serif'}}}%%
+```
+
+## The 5 color classes (the only allowed palette)
+
+```
+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
+```
+
+`fill` = `cardBgColors`, `stroke` = the 3+2 accent, `color` = `systemColors.label`
+(`#1d1d1f`). Source of truth: `app/theme/tokens/index.ts` and
+`app/theme/presets/agent-colors.ts` **in the DesireCore application codebase**
+(where this skill runs) — these paths are not part of this market repository.
+
+### Class selection rule (mirrors agent-colors.ts)
+
+| Domain | Class | Accent |
+|--------|-------|--------|
+| System / generic (DesireCore core, infra, LLM) | system | blue `#007AFF` |
+| Knowledge / learning (legal, writer, memory) | agent / system | purple `#AF52DE` |
+| Business / execution (data, real-estate, code) | biz | green `#34C759` |
+| Project management / warning / decision | warn | orange `#FF9500` |
+| Error / failure | error | red `#FF3B30` |
+
+Decorative-only colors `yellow #FFCC00` and `teal #5AC8FA` are for background
+gradients elsewhere in the product — never use them in diagrams.
+
+## Shape table
+
+| Concept | Mermaid syntax | Class | Note |
+|---------|----------------|-------|------|
+| Agent / sub-agent | `id{{Name}}` (hexagon) | agent | the signature shape for an autonomous agent |
+| DesireCore core / orchestrator | `id(Name)` (rounded) | system | central coordinator |
+| LLM / model | `id(⚡ Model)` (rounded + ⚡) | system | ⚡ prefix marks an LLM call |
+| Service / tool / skill | `id[Name]` (rect) | biz | a callable capability |
+| Business / execution step | `id[Step]` (rect) | biz | a unit of work |
+| Memory / store / DB | `id[(Store)]` (cylinder) | system | persistent state |
+| User / external actor | `id([User])` (stadium) | biz | the human |
+| Decision / branch | `id{Choice?}` (diamond) | warn | a fork in control flow |
+| External service | `subgraph Ext [External]` ... `end` + `style Ext stroke-dasharray:4 3` | — | dashed boundary = outside the system |
+
+## Arrow / flow encoding
+
+| Flow type | Edge syntax | Meaning |
+|-----------|-------------|---------|
+| Primary data flow | `A --> B` | the main path |
+| Memory write / persistence | `A -.-> B` | dotted = side-effect write |
+| Async event | `A -.->|async| B` | dotted + label |
+| Feedback / retry | `B --> A` (back-edge) | loop |
+| Hierarchy / containment | `A --o B` | circle edge |
+| Hard stop / escalation | `A --x B` | cross edge |
+| Co-participation (equal peers) | `A === B` | thick link |
+
+## Diagram-type cheatsheet
+
+| User intent | Mermaid header |
+|-------------|----------------|
+| Architecture / data flow | `flowchart TD` or `flowchart LR` |
+| Sequence / interaction over time | `sequenceDiagram` |
+| State machine | `stateDiagram-v2` |
+| ER / data model | `erDiagram` |
+| Class / type model | `classDiagram` |
+| Mind map | `mindmap` |
+
+For `sequenceDiagram`, `classDiagram`, etc. that do not support `classDef`, still
+keep the `%%{init}%%` brand header so the theme stays light and on-brand.
--- a/skills/tech-diagram/references/templates.md
+++ b/skills/tech-diagram/references/templates.md
@@ -0,0 +1,119 @@
+# Built-in Templates (内置模板)
+
+Ready-to-use, brand-styled Mermaid for DesireCore's own architecture patterns.
+Adapt the labels to the user's subject; keep the header and `classDef`s intact.
+All four are verified to render.
+
+> Note: file paths like `lib/...` and `app/...` cited below refer to the
+> **DesireCore application codebase** where this skill runs at runtime — they do
+> not exist in this market repository.
+
+## 1. Agent architecture (Agent 架构图)
+
+Mirrors the delegate / skills / memory layout (`lib/agent-service/builtin-tools/delegate.ts`).
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F0F5FF','primaryBorderColor':'#007AFF','primaryTextColor':'#1d1d1f','lineColor':'#6e6e73','fontFamily':'-apple-system,SF Pro Text,Noto Sans SC,sans-serif'}}}%%
+flowchart TD
+    classDef agent  fill:#F6F3FF,stroke:#AF52DE,color:#1d1d1f
+    classDef system fill:#F0F5FF,stroke:#007AFF,color:#1d1d1f
+    classDef biz    fill:#F0FDF4,stroke:#34C759,color:#1d1d1f
+
+    U(["User"]):::biz
+    Core("DesireCore Core"):::system
+    A1{{"Legal Agent"}}:::agent
+    A2{{"Data Agent"}}:::agent
+    Skills["Skills / MCP Tools"]:::biz
+    Mem[("Conversation Memory")]:::system
+
+    U --> Core
+    Core --> A1
+    Core --> A2
+    A1 --> Skills
+    A2 --> Skills
+    A1 -.-> Mem
+    A2 -.-> Mem
+```
+
+## 2. Delegate 6 modes (Delegate 六种模式)
+
+The unified delegate tool and its six execution modes.
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F0F5FF','primaryBorderColor':'#007AFF','primaryTextColor':'#1d1d1f','lineColor':'#6e6e73','fontFamily':'-apple-system,SF Pro Text,Noto Sans SC,sans-serif'}}}%%
+flowchart LR
+    classDef system fill:#F0F5FF,stroke:#007AFF,color:#1d1d1f
+    classDef biz    fill:#F0FDF4,stroke:#34C759,color:#1d1d1f
+
+    D("Delegate Tool"):::system
+    D --> S["sync: block & await"]:::biz
+    D --> AS["async: fire & report back"]:::biz
+    D --> W["worker: ephemeral SubAgent"]:::biz
+    D --> F["fan-out: parallel / sequential"]:::biz
+    D --> H["handoff: hand session to user"]:::biz
+    D --> V["via-messaging: fallback wait"]:::biz
+```
+
+## 3. Three-tier conversation memory (三层对话记忆)
+
+active → recent (L0/L1) → archive (L2); writes are dotted
+(`lib/schemas/agent-service/conversation-memory.ts`).
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F0F5FF','primaryBorderColor':'#007AFF','primaryTextColor':'#1d1d1f','lineColor':'#6e6e73','fontFamily':'-apple-system,SF Pro Text,Noto Sans SC,sans-serif'}}}%%
+flowchart LR
+    classDef system fill:#F0F5FF,stroke:#007AFF,color:#1d1d1f
+    classDef warn   fill:#FFFBF0,stroke:#FF9500,color:#1d1d1f
+
+    New(["New Message"]):::warn
+    Active[("active: ongoing matters")]:::system
+    Recent[("recent: L0 / L1 summaries")]:::system
+    Archive[("archive: L2 full log")]:::system
+
+    New --> Active
+    Active -.->|compact| Recent
+    Recent -.->|archive after 180d| Archive
+```
+
+## 4. Relation graph (关系图谱，6 种边)
+
+The six edge types projected by `lib/agent-service/relations/projector.ts`, each
+drawn with a distinct edge style. Edge weight decays over time (30-day half-life).
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F0F5FF','primaryBorderColor':'#007AFF','primaryTextColor':'#1d1d1f','lineColor':'#6e6e73','fontFamily':'-apple-system,SF Pro Text,Noto Sans SC,sans-serif'}}}%%
+flowchart TD
+    classDef agent fill:#F6F3FF,stroke:#AF52DE,color:#1d1d1f
+    classDef biz   fill:#F0FDF4,stroke:#34C759,color:#1d1d1f
+
+    A1{{"Agent A"}}:::agent
+    A2{{"Agent B"}}:::agent
+    A3{{"Agent C"}}:::agent
+    U(["User"]):::biz
+
+    A1 -->|delegate| A2
+    A1 -.->|mention| A3
+    A2 ===|co_task| A3
+    A2 --o|hierarchy| A1
+    A3 -->|seek_help| A1
+    A1 --x|escalation| U
+```
+
+## Other diagram types
+
+For sequence / state / ER / class diagrams, keep the same `%%{init}%%` header for
+a consistent light theme. Example sequence diagram:
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#F0F5FF','primaryBorderColor':'#007AFF','primaryTextColor':'#1d1d1f','lineColor':'#6e6e73','fontFamily':'-apple-system,SF Pro Text,Noto Sans SC,sans-serif'}}}%%
+sequenceDiagram
+    actor U as User
+    participant C as DesireCore Core
+    participant A as Sub-Agent
+    participant M as Memory
+    U->>C: request
+    C->>A: delegate (sync)
+    A->>M: write fact
+    A-->>C: result
+    C-->>U: reply
+```