Orrery

上方的图表来自 docs/hero.yaml：共 40 行 YAML，由 orrery 使用默认的 stage 皮肤布局并渲染：先点亮分组，再点亮图块，随后带着彗星尾迹的数据包按顺序沿主路径运行，并逐条点亮路径，循环往复。本 README 中的所有图片都使用 stage 皮肤；skin: classic（或 --skin classic）则会以各供应商自己的图表样式绘制相同布局，并让数据包沿每条边运行。GitHub 会保留动画；相同规范生成的 PNG 是静态画面。

你将获得什么

• **仅使用官方、最新图标。**共 18,209 个图标：AWS（810）、Azure（636）、Google Cloud（233）、Kubernetes（40）、GitHub Octicons（399）和 IBM Carbon（2,776），另有 5,502 个技术标志、6,286 个中性符号，以及提供六种字重的 Phosphor（1,527），适用于系统设计和业务流程；也支持你自己的 SVG，作为 local: 图标，并可通过 orrery icons new 绘制和检查，通过 icons check 验证。云服务图标包根据各供应商自己的下载内容重新构建，并通过校验和固定版本。Google Cloud 产品使用 Google 2026 年指南指定的图标；不包含已弃用的图标集和非官方重绘的云服务图标。
• **遵循官方规范。**AWS 分组遵循 AWS Architecture Icons 图示规范（边框、虚线、角标、标签位置、开放箭头、编号标注）；Google Cloud 和 Azure 分组则根据各自的参考图进行测量。styles.md 中的每个值都标明了来源。
• 也支持业务流程。kind: 可将同一份规范转换为 ISO 5807 流程图、带泳道池、泳道和消息流的 BPMN 2.0 流程、UML 状态机、组织结构图、双侧思维导图，或带情绪曲线的客户旅程图。在 stage 皮肤中，流程会像 BPMN 令牌一样运行：在并行网关处分流，在汇合处等待，并沿着是分支前进。
• 数据模型、时序图和路线图。kind: er 会绘制带类型、键值行和乌鸦脚关系的表格，关系线会连接到对应行；orrery import sql 可从你的 CREATE TABLE 语句开始生成图表。kind: sequence 会逐条绘制调用流程消息，回复使用虚线，并显示激活条和 loop 或 alt 片段，按顺序播放。kind: timeline 会按月、季度或年份绘制路线图：泳道、按状态设置样式的条形、里程碑、依赖箭头和今日标记。
• **可调控的自动布局。**Eclipse Layout Kernel 会放置嵌套边界，以直角布线，将汇入和分出的边合并成主干，并在不造成边线交叉的前提下保留你编写的顺序。无需编写坐标；需要控制布局时，可用 rank: first 指定节点在流程中的位置，用 align: <node> 对齐节点，用分组上的 cols: 2 将子项排成网格，用 layout: { aspect: 4:3 } 让图表保持紧凑，便于在 README 中阅读。
• 一份规范，多个图表。views: 可从同一来源绘制概览图和细节图（render --view all），确保它们始终一致；classes: 可共享预设，include: 可引入每个图表都会使用的框架，tags: 可为标记的内容设置颜色和样式，并为每种标签添加一行图例。
• 图表始终忠实反映代码。orrery import 可从 Terraform、CloudFormation 或 CDK 输出、Docker Compose、Kubernetes 清单或 Mermaid 开始生成规范，并为每个节点记录其 evidence:（来源文件、行号和标识符）。如果某项证据不再存在，orrery verify 就会失败；使用 --link 时，每个节点都会成为指向代码的提交固定链接。orrery diff 会用彩色图示展示两个版本之间的变化，GitHub Action 会在每个拉取请求中附上该图示和审查内容。
• **让图表动起来。**默认生成动画 SVG：数据包以相同速度沿每条边移动，主路径以故事形式播放，线条样式保持绘制时的样子。使用 animate: flow 可显示行进中的虚线，使用 --static 可生成静态文件。
• **两种皮肤，同一布局。**默认的 stage 皮肤会将每个图表绘制为动画场景，默认采用深色主题：细线网格带有单一色调，图标置于墨色块面上，并使用各自品牌色的柔和色调；标签采用大写等宽字体，连线较暗，主路径沿线播放。skin: classic（或 --skin classic）则遵循各供应商自己的图表风格，适用于必须与 AWS、Azure 或 Google Cloud 图示风格一致的文档。位置始终保持不变；支持深色和浅色主题。
• **一份规范，八种输出。**SVG 适用于 README 和文档，PNG 适用于幻灯片和聊天（默认 3 倍尺寸，放大查看依然清晰），.drawio 可继续编辑，.drawio.svg 是一个既能在任何地方显示为图片、又能在 draw.io 中打开并编辑的文件，TSX 组件适用于 React 网站，独立 HTML 查看器支持深色模式、平移和双指缩放，Mermaid 文本适用于只支持绘制 Mermaid 的 Wiki，还可输出主路径的时序图。每个 SVG 和 PNG 都包含自己的规范，因此 orrery import picture 可将图片转换回可编辑图表。orrery doc 可将图表插入设计文档，并输出 HTML、Markdown 或 Word 格式。
• **专为 Agent 打造。**提供包含快速上手路径和编写规则的技能、JSON Schema、482 个简短别名（aws:s3、azure:aks、k8s:deploy，以及 generic:invoice 和 generic:approval 等业务名称）、按相关度排序的图标搜索、每条结果都会指出对象和修复方法的验证器、供未安装技能的客户端使用的 MCP 服务，以及可根据你的代码规划图表并检查图表是否与代码相符的 Agent。
• **无需安装。**CLI、布局引擎、PNG 渲染器、字体和官方云服务图标包都包含在技能文件夹中（9 MB）。标志和字形集不会被复制：图表首次使用时，会从各自的 npm 库加载，并通过校验和验证后缓存。只需 Node.js 22 或更高版本。

工作原理

安装

Claude Code 插件：

/plugin marketplace add Sagargupta16/orrery
/plugin install orrery@orrery

适用于任何能够读取 Agent Skills 的 Agent（Codex、Cursor、Gemini CLI、Kiro 等）：

npx skills add Sagargupta16/orrery
gh skill install Sagargupta16/orrery orrery              # GitHub CLI, any supported agent
gemini extensions install https://github.com/Sagargupta16/orrery   # Gemini CLI extension

仅安装 CLI，通过 npm 安装：

npx @sagargupta1610/orrery doctor
npx @sagargupta1610/orrery render diagram.yaml -f all --theme both

或者从克隆的仓库运行：node orrery/skills/orrery/scripts/orrery.mjs doctor。

作为 MCP 服务，适用于任何支持模型上下文协议的客户端（工具：编写指南、验证、渲染、审查、图标搜索、模板、补丁候选项、draw.io 链接）：

{ "mcpServers": { "orrery": { "command": "npx", "args": ["-y", "@sagargupta1610/orrery", "mcp"] } } }

对于 Claude Code，将此配置块放入 .mcp.json；对于 Gemini CLI，放入 ~/.gemini/settings.json；对于 Cursor，放入 .cursor/mcp.json；对于 Kiro，放入 .kiro/settings/mcp.json。Codex 则在 ~/.codex/config.toml 中使用 [mcp_servers.orrery]、command = "npx" 和 args = ["-y", "@sagargupta1610/orrery", "mcp"]。orrery mcp install <client> 会为你写入该配置（claude-code、claude-desktop、cursor、vscode、gemini、codex 或 kiro，可安装到项目中，或使用 user 安装到所有项目中），并保留文件中的其他所有服务。每次发布都会将服务发布到 MCP Registry，标识为 io.github.Sagargupta16/orrery，并附带 .mcpb 包，可在 Claude Desktop 中一键安装。在支持 MCP Apps 的宿主中，渲染的图表会在内嵌查看器中打开。orrery mcp --port 8765 会通过 HTTP 在 127.0.0.1 上提供相同的工具，规范以文本形式传入，不会读取或写入磁盘。

快速开始

让你的 Agent 绘制图表（“绘制此仓库的架构”“在两个可用区中部署于 AWS 的三层 Web 应用”“将此 Mermaid 流程图转换为 Google Cloud 图表”）。它会编写规范、进行验证、渲染并检查图像。你也可以自行编写：

title: Orders API
direction: right
groups:
  cloud:  { type: aws:cloud }
  region: { type: aws:region, label: eu-west-1, in: cloud }
nodes:
  users: { icon: aws:users, label: Customers }
  api:   { icon: aws:api-gateway, in: region }
  fn:    { icon: aws:lambda, label: Create order, in: region }
  table: { icon: aws:dynamodb, label: Orders, in: region }
edges:
  - users -> api: HTTPS
  - api -> fn -> table

node skills/orrery/scripts/orrery.mjs render orders.yaml -f svg,png

标签默认使用官方服务名称，因此 { icon: aws:lambda } 会显示为“AWS Lambda”。边使用箭头表示：-> 实线、--> 虚线、..> 点线、==> 粗线、<-> 双向、a -> b, c 分叉连接。完整格式见 spec.md。

示例

aws-three-tier：跨两个可用区的 VPC，包含公有、Web 和数据子网，以及横跨两个可用区绘制的 Auto Scaling 组；使用 AWS 图集自带的分组样式。

这是 77 个参考图表之一，涵盖 AWS（从 Bedrock AgentCore 上的 Agent 到灾难恢复、威胁检测、网络检查、迁移和联系中心）、Azure、Google Cloud、IBM Cloud、Kubernetes、AI 和 ML、数据平台、CI/CD、C4、系统设计和业务流程（流程图、BPMN 流程、泳道图、状态机、组织结构图、思维导图和客户旅程）。每个图表都由 skills/orrery/examples 中的规范渲染，并由 CI 对照渲染器进行检查。可在 sagargupta.online/orrery/gallery 浏览所有图表的浅色和深色版本，并下载每个规范及所有输出；也可在 examples/README.md 中查看每个图表对应的渲染命令。orrery init <name> 可将任意示例复制为起点。

验证结果会告诉你如何修复

$ orrery validate orders.yaml
error DG101 node "fn" uses unknown icon "aws:lamda" {"node":"fn","icon":"aws:lamda"}
      fix: use icon "aws:lambda"
      fix: run `orrery icons search lamda`
error DG108 unknown key "lable" in node "db" {"where":"node \"db\"","key":"lable"}
      fix: rename "lable" to "label"
failed: 2 error(s), 0 warning(s)

规范错误（DG1xx）会中止渲染；构图警告（DG2xx：边穿过节点、标签重叠、图表过宽而难以阅读）则会继续渲染，除非设置了 --strict。render --json 会以原子方式写入每个文件，并输出回执，列出每个输出文件的大小和 SHA-256。

一个先测量、后评判的评审板

orrery review 会按读者实际看到的宽度（README 栏为 880 px）检查图表，并从六个维度评分：官方规范、布局、网格、箭头与流程、重叠，以及尺寸与质量。

$ git show v0.2.1:skills/orrery/examples/gitops-kubernetes.yaml > gitops-0.2.yaml
$ orrery review gitops-0.2.yaml --width 880
review gitops-0.2: 1964x786 in a 880px column, seen at 880x352 (scale 0.45, light)
score 85.3/100  FAIL (pass = no blocker or major and score >= 85)
...
blocker quality.label-size node labels render at 5.82px at this width (1964px canvas shown at 0.45x)
        fix: use direction: down so the diagram is narrower

经过这轮评审，图表得分达到 98.5 并通过检查：现在图表从上到下排列，因此其中的标签在 README 栏中可以按完整尺寸显示。

在 Claude Code 中，/orrery:review <spec> 会运行完整流程。代码会测量所有可计数的内容：重叠、交叉、对齐、锯齿和可避免的弯折、擦过图标的线条、空置或不对称的分组，以及显示宽度下的文字尺寸和对比度。只读 Agent 会并行运行，评判无法计数的内容：

• conventions-reviewer 会检查供应商自身的规则，引用自 AWS deck、Azure Well-Architected、Google 的图标指南和 C4 标记法。
• flow-reviewer 会检查箭头所表达的故事。
• legibility-reviewer 会按显示尺寸查看 PNG。
• accuracy-reviewer 会根据图表展示的代码和基础设施检查图表（如有）。

只有引用测量值、供应商规则或源代码行的发现才计入。每轮中，patch-proposer Agent 会编写两到四组候选补丁，orrery patch 会一次性尝试所有补丁；只有最佳候选提高分数且硬性计数没有增加时，才会保留该轮结果；循环最多运行三轮，或在连续两轮没有进展后停止。视觉模型不擅长计数重叠和交叉，因此绝不会由它们来判定这两项。评分准则位于 references/review，因此只要安装了该技能，无论在哪里内联运行，都能执行相同的检查，无需子 Agent。

从代码绘制图表的 Agent

在 Claude Code 中，/orrery:draw <what to draw> 会从系统本身着手。planner Agent 会读取基础设施和代码（Terraform、CloudFormation、SAM、CDK 输出、Kubernetes、Compose 以及处理程序），并列出每个服务、边界和流程及其来源文件与行号，标明哪些流程由基础设施声明、哪些仅由代码暗示，并说明遗漏了什么以及原因。你需要先确认该列表，之后才会生成任何规范。随后会编写规范、进行验证并交由评审板检查；第四位评审者 accuracy-reviewer 会独立核对图表与源内容：是否包含虚构节点、是否将依赖关系画成流量、箭头方向是否错误、服务是否位于错误的子网中。它看不到 planner 的推理，因此不会沿袭其错误。

/orrery:doc <topic> 会撰写设计文档：planner 为每个方面选定一张图（概览、请求路径、数据、部署、故障处理），diagram-author Agent 会并行绘制这些图，每张图都会经过评审，最后由 orrery doc 将 Markdown 生成为 HTML 或 Word，并添加带编号的图表。

修复以测量为依据，而非靠争论：patch-proposer Agent 会采用不同策略（减少箭头、调整结构、改进措辞、遵循供应商规则）编写候选补丁，orrery patch 会在各自的副本上评审每个候选方案，并仅保留得分最高且不会造成任何恶化的方案。插件钩子会在 Agent 写入规范时立即验证，因此任何内容渲染之前，错误都会连同修复建议一起返回。规划和准确性规则位于 planning.md 和 accuracy.md，因此不支持子 Agent 的客户端也会按顺序运行相同的检查。

在拉取请求中

该仓库也是一个 GitHub Action。它会验证、渲染并评审每份规范，绘制拉取请求所涉及规范中的变更，并在拉取请求中保留一条评论，展示评分并附上图片链接：

on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  diagrams:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: Sagargupta16/[email protected]
        with:
          specs: docs/**/*.yaml   # git pathspec globs, one per line
          fail-on: error          # or warning, or review (fail when the review does not pass)

编辑器和浏览器

orrery lsp 是用于 spec 文件的语言服务器：在相关字符上显示发现的问题，将修复作为快速修复提供，并为图标 ID、组类型和 ID 提供补全。editors/vscode 是它的轻量 VS Code 客户端，任何支持 Language Server Protocol 的编辑器都可以使用同一服务器。playground 在浏览器中运行 CLI 自带的解析器、布局、渲染器和审查功能：编辑 spec，查看它实时重绘，下载所有格式，或分享包含该 spec 的链接。

命令

命令	功能
render <spec> [-o base] [-f svg,png,drawio,drawio.svg,tsx,html,mmd,sequence.svg|all] [--theme light|dark|both] [--skin classic|stage] [--animate packets|flow|relay|none] [--static] [--view <name>|all]	验证、布局并渲染；--view 可绘制 spec 中的某个视图，也可以将每个视图分别保存为文件。
watch <spec> [-o base] [-f svg,png] [--review]	每次保存 spec 或其本地图标时重新渲染；使用 --review 时，每次还会打印审查得分。
validate <spec> [--strict] [--json]	检查 spec 错误和构图警告，并为每项提供修复方案。
review <spec> [--width 880] [--theme light|dark] [--strict] [--json]	按读者看到图表时的宽度为其评分；写入 <base>.review.json，并生成该宽度的 PNG（如果该 PNG 大于 1568 px，还会生成缩放至适合 1568 px 的 <base>.review.look.png）。
patch <spec> <candidates.json> [-o best.yaml] [--width 880]	一次尝试多个候选补丁集，每个都在独立副本上审查；保留能提高得分的最佳方案，同时不改动注释和格式。
doc <design.md> [-f html,md,docx]	构建设计文档：每个 `` 行都会成为一个带编号的图（HTML 中内嵌 SVG，Markdown 旁附图像文件，Word 中插入图片）。
mcp [--port 8765]	将这些命令作为 Model Context Protocol 工具通过 stdio 提供服务，或通过 127.0.0.1 上的 HTTP 提供服务。
mcp install <client> [project|user] [--force], mcp install --list	将 orrery 服务条目写入客户端的 MCP 配置，同时保留文件的其余内容。
diff <before> <after> [-o changes.svg] [--json]	查看两个 spec 之间的变化（git:<ref>:<path> 会从 git 读取 spec）：以文本、JSON 或着色后的变更图表形式显示新增、移除、重命名和更改的节点、组和边。
verify <spec> [--link] [--commit <sha>] [--json]	检查每个 evidence: 是否仍指向有效的文件、行和标识符；--link 会将每个节点的 url 设为固定到某个提交的永久链接。
describe <spec> [--json]	以纯文本描述布局后的图表：组、节点、它们的位置，以及各项之间的连接关系。
lsp	通过 stdio 为编辑器提供语言服务器。
icons search <words> [--pack aws]	按相关度排序的图标 ID 及其官方名称。
icons show <id>, icons list, icons packs	浏览目录及其来源。
icons fetch	下载并缓存徽标和字形库，以便离线渲染。
icons new <name>, icons check <file.svg>, icons adopt <file.svg> --name <name>	在 24 网格上绘制自己的图标；用两种皮肤和主题生成图标接触表，并依据绘制规则检查图标；或将他人的 SVG 引入为干净的 local: 图标。
styles	查看所有组类型和节点形状。
init [template]	从示例之一开始。
import <mermaid|terraform|cloudformation|compose|kubernetes|sql|picture> <file> [-o diagram.yaml]	从 Mermaid 流程图、Terraform、CloudFormation 或 CDK 模板、Compose 文件、Kubernetes 清单或 SQL 架构（每个节点都带有 evidence:）生成 spec；也可以从 orrery 绘制的 SVG 或 PNG 中读回 spec。
doctor, demo	检查安装；渲染所有示例。

图标包

图标包	图标数	来源	提供方式
aws	810	AWS 架构图标，2026-07-31 版软件包	随附
azure	636	Azure 架构图标 V24	随附
gcp	233	Google Cloud 图标，核心图标和类别图标按 Google 2026 年 5 月指南映射到产品	随附
k8s	40	Kubernetes 社区图标	随附
github	399	GitHub Octicons	npm @primer/octicons
ibm	2,776	IBM Carbon 图标，IBM 的图表节点图标和产品字形	npm @iconify-json/carbon
logos	2,151	SVG Logos	npm @iconify-json/logos
si	3,351	Simple Icons	npm @iconify-json/simple-icons
tabler	6,286	Tabler Icons	npm @iconify-json/tabler
ph	1,527	Phosphor Icons，有六种权重，可通过后缀指定（ph:handshake-duotone）	npm @iconify-json/ph

随附的图标包仅作为供应商下载内容提供，因此会随技能一同分发，并可离线使用。npm 图标集会在渲染时从本地 node_modules、用户缓存或 jsDelivr 加载，并根据固定的 SHA-256 校验；orrery icons fetch 可提前缓存这些图标集，详情请参阅 icons.md。Renovate 每月提交的依赖更新 PR 也会检查供应商页面是否有新版本，并附上更新后的图标包。图标、徽标和商标归其所有者所有，使用时遵循 THIRD_PARTY_NOTICES.md 中列出的条款；AWS、Microsoft 和 Google 的条款允许在架构图中使用这些内容。

社区

用 orrery 绘制了图表？欢迎分享到展示与交流。问题请前往问答，图标、示例、输出或样式需求请前往创意。发现了错误？请提交问题。如果 orrery 帮你省去了绘制图表的时间，请点个星标，让更多人发现它。

开发

pnpm install
pnpm lint
pnpm typecheck
pnpm test
pnpm build                       # src/ -> skills/orrery/scripts/orrery.mjs
pnpm gallery                     # re-render examples/ and docs/
node scripts/check-repo.mjs      # dashes, links, counts, doc snippets, gallery freshness
pnpm sync-icons                  # rebuild icon catalogs (--latest re-pins new vendor releases)
node scripts/pack-npm.mjs        # stage the npm package in out/npm (a GitHub release publishes it)

请参阅 CONTRIBUTING.md，了解各部分如何配合；如需报告问题，请参阅 SECURITY.md。

许可证

代码和文档：MIT。图标、字体和随附的引擎各自遵循其许可证：THIRD_PARTY_NOTICES.md。