concept-diagrams

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Concept Diagrams

概念图

Make a system or idea easier to reason about with the smallest useful diagram. Visual reasoning, not decorative graphics.
Default to Mermaid in Markdown (reviewable, diffable). Use standalone HTML/SVG only when the user asks for a polished/printable file or geometry Mermaid cannot express.
Use when asked to diagram, visualize, map, or explain visually: architecture/boundaries/dependencies, request/data/control flow, sequence/protocol/lifecycle, state machines and failure paths, concept maps, docs/wiki diagrams grounded in code. Not for decorative graphics, production UI comps, animation, unresearched systems, or one giant "everything diagram". If diagramming code, inspect relevant files first — orient or use a scoped explore subagent for broad unfamiliar codebases.
用尽可能小且有用的图表,让系统或想法更容易理解。服务于视觉推理,而非装饰性图形。
默认使用 Markdown 中的 Mermaid(便于审查和比较差异)。仅当用户要求提供精致或可打印的文件,或者需要表达 Mermaid 无法呈现的几何关系时,才使用 独立 HTML/SVG。
当用户要求绘制、可视化、映射或进行视觉解释时使用:架构/边界/依赖关系、请求/数据/控制流、时序/协议/生命周期、状态机和故障路径、概念图,以及基于代码的文档/wiki 图表。不适用于装饰性图形、生产环境 UI 设计稿、动画、未经调研的系统,或试图将所有内容塞进一张“全景图”的场景。如果为代码绘制图表,应先检查相关文件;对于范围广且陌生的代码库,应先熟悉整体结构,或使用限定范围的 explore 子 Agent。

Diagram brief

图表简报

Answer internally before drawing (ask the user only if the answer materially changes the diagram):
  1. Question: what should the viewer understand after 20 seconds?
  2. Audience: maintainer, reviewer, planner, user, or newcomer?
  3. View: structure, runtime flow, sequence, state, concept, or comparison?
  4. Evidence: what files/docs/sources back the nodes and edges?
  5. Artifact: inline answer, Markdown doc, wiki page, or standalone HTML/SVG?
A diagram has a thesis. Do not draw boxes to restate prose.
绘制前先在内部回答以下问题(仅当答案会实质影响图表时才询问用户):
  1. 问题: 20 秒后,看图者应该理解什么?
  2. 受众: 维护者、评审者、规划者、用户,还是新成员?
  3. 视图: 结构、运行流程、时序、状态、概念,还是对比?
  4. 证据: 哪些文件、文档或来源能够支撑各个节点和边?
  5. 产物: 行内答案、Markdown 文档、wiki 页面,还是独立 HTML/SVG?
每张图表都应有一个明确论点。不要用方框重复文字内容。

Choose the view

选择视图

Source/architecture map (ownership, modules, trust boundaries) · runtime/data flow (what moves where) · sequence (order between actors) · state/lifecycle (statuses, transitions, failure modes) · concept map (labeled relationships) · comparison — use a table when classification beats arrows. For complex systems, ship a pack of 2–4 small diagrams instead of one monster view.
源代码/架构映射图(职责归属、模块、信任边界)· 运行/数据流(内容在哪里流转)· 时序图(参与者之间的执行顺序)· 状态/生命周期(状态、转换、故障模式)· 概念图(带标签的关系)· 对比——当分类比箭头更清晰时使用表格。对于复杂系统,应交付一组 2–4 张小图,而不是一张庞大的全景视图。

Codebase diagram protocol

代码库图表规范

  1. Read obvious entrypoints first: README, package config, route files, command registration, module roots, extension indexes.
  2. Trace only the relevant path; distinguish facts from inferred relationships.
  3. List inspected file paths in node notes or a
    Sources inspected
    list.
  4. For docs or wiki diagrams, check the existing pages and their conventions first.
  1. 首先阅读明显的入口点:README、package config、route files、command registration、module roots、extension indexes。
  2. 仅追踪相关路径;区分事实与推断关系。
  3. 在节点注释或
    Sources inspected
    列表中列出已检查的文件路径。
  4. 绘制文档或 wiki 图表时,先检查现有页面及其约定。

Mermaid guardrails

Mermaid 约束

Stable ASCII IDs (
WikiContext
, not
wiki-context()
) with human labels in brackets (
WikiContext[wiki context action]
); short labels; no raw
<
,
>
,
|
,
{
,
}
in labels; short subgraph names; edge labels only when they add meaning; explain dashed vs solid if both appear.
Readability budget (split by view if exceeded): 5–9 primary nodes, 1–3 subgraphs, 0–2 edge styles, 3–5 sequence participants, 5–8 states, 4–6 words per label.
使用稳定的 ASCII ID(
WikiContext
,而不是
wiki-context()
),并在方括号中提供易读标签(
WikiContext[wiki context action]
);标签应简短;标签中不得直接使用
<
、
>
、
|
、
{
、
}
;子图名称应简短;仅在边标签有助于表达含义时才添加;如果同时出现虚线和实线,应说明二者的区别。
可读性预算(超出时按视图拆分):5–9 个主要节点、1–3 个子图、0–2 种边样式、3–5 个时序图参与者、5–8 个状态、每个标签 4–6 个词。

Standalone HTML/SVG mode

独立 HTML/SVG 模式

Self-contained HTML from
templates/standalone-svg.html
in this skill's folder: inline SVG only, no CDN/remote assets, light/dark CSS variables, flat minimal style, title/subtitle/diagram/notes, written to the user path or
docs/diagrams/<slug>.html
. No preview server unless asked; if one is needed, run it in hc (
hc run --bg
).
基于此 skill 文件夹中的
templates/standalone-svg.html
生成自包含 HTML:仅使用内联 SVG,不引用 CDN 或远程资源,使用浅色/深色 CSS 变量和扁平简洁风格,并包含标题、副标题、图表和注释。文件写入用户指定的路径或
docs/diagrams/<slug>.html
。除非用户要求,否则不启动预览服务器;如确有需要,可在 hc 中运行(
hc run --bg
)。

Quality bar

质量标准

The diagram answers one clear question; reading direction is obvious; every node/edge is backed by source, user input, or explicit assumption; boundaries mean something real; no unlabeled arrows between vague boxes; codebase diagrams list inspected paths; Mermaid syntax renders.
Reject: prose restated as bubbles, architecture invented from filenames, arrows meaning several unrelated things, false certainty on inferred relationships, decorative colors implying fake categories, missing source/assumption notes.
图表应回答一个明确问题;阅读方向清晰;每个节点和边都由源代码、用户输入或明确假设支撑;边界具有实际含义;不存在连接模糊方框的无标签箭头;代码库图表应列出已检查的路径;Mermaid 语法能够正常渲染。
拒绝:将正文原样复述为气泡、根据文件名臆造架构、使用一个箭头表达多种无关含义、对推断关系表现出虚假确定性、使用暗示虚假分类的装饰性颜色,以及缺少来源或假设说明。