concept-diagrams
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseConcept 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):
- Question: what should the viewer understand after 20 seconds?
- Audience: maintainer, reviewer, planner, user, or newcomer?
- View: structure, runtime flow, sequence, state, concept, or comparison?
- Evidence: what files/docs/sources back the nodes and edges?
- Artifact: inline answer, Markdown doc, wiki page, or standalone HTML/SVG?
A diagram has a thesis. Do not draw boxes to restate prose.
绘制前先在内部回答以下问题(仅当答案会实质影响图表时才询问用户):
- 问题: 20 秒后,看图者应该理解什么?
- 受众: 维护者、评审者、规划者、用户,还是新成员?
- 视图: 结构、运行流程、时序、状态、概念,还是对比?
- 证据: 哪些文件、文档或来源能够支撑各个节点和边?
- 产物: 行内答案、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
代码库图表规范
- Read obvious entrypoints first: README, package config, route files, command registration, module roots, extension indexes.
- Trace only the relevant path; distinguish facts from inferred relationships.
- List inspected file paths in node notes or a list.
Sources inspected - For docs or wiki diagrams, check the existing pages and their conventions first.
- 首先阅读明显的入口点:README、package config、route files、command registration、module roots、extension indexes。
- 仅追踪相关路径;区分事实与推断关系。
- 在节点注释或 列表中列出已检查的文件路径。
Sources inspected - 绘制文档或 wiki 图表时,先检查现有页面及其约定。
Mermaid guardrails
Mermaid 约束
Stable ASCII IDs (, not ) with human labels in brackets (); short labels; no raw , , , , in labels; short subgraph names; edge labels only when they add meaning; explain dashed vs solid if both appear.
WikiContextwiki-context()WikiContext[wiki context action]<>|{}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(,而不是 ),并在方括号中提供易读标签();标签应简短;标签中不得直接使用 、、、、;子图名称应简短;仅在边标签有助于表达含义时才添加;如果同时出现虚线和实线,应说明二者的区别。
WikiContextwiki-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 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 . No preview server unless asked; if one is needed, run it in hc ().
templates/standalone-svg.htmldocs/diagrams/<slug>.htmlhc run --bg基于此 skill 文件夹中的 生成自包含 HTML:仅使用内联 SVG,不引用 CDN 或远程资源,使用浅色/深色 CSS 变量和扁平简洁风格,并包含标题、副标题、图表和注释。文件写入用户指定的路径或 。除非用户要求,否则不启动预览服务器;如确有需要,可在 hc 中运行()。
templates/standalone-svg.htmldocs/diagrams/<slug>.htmlhc run --bgQuality 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 语法能够正常渲染。
拒绝:将正文原样复述为气泡、根据文件名臆造架构、使用一个箭头表达多种无关含义、对推断关系表现出虚假确定性、使用暗示虚假分类的装饰性颜色,以及缺少来源或假设说明。