简体中文 | English
将技术描述转化为可验证、可预览、可导出 PNG 的 HTML + SVG 架构图。
visual-architecture 是面向 AI 编码 Agent 的架构可视化 Skill。它不以单次提示直接出图，而是先确认用途、受众与视觉约束，再经 Diagram IR、注册式设计系统、布局策略与质量门禁生成最终产物。
快速开始 · 效果展示 · 性能表现 · 工作原理 · CLI 参考
一次性「文本生成架构图」常见问题包括：语义臆造、布局不稳定、跨次生成视觉漂移。visual-architecture 将流程拆为可检查阶段，使架构语义与视觉表现解耦：
- 渐进加载 — 访谈阶段仅加载短入口与注册索引；设计系统与完整门禁按阶段展开，降低首轮上下文占用。
- 契约化视觉与路由 — 正交连线、框内标签、PNG 导出等规则集中于共享契约，减少多份长文间的规则冲突。
- 先确认，再生成 — 一次给出完整推荐方案并由用户确认，避免冗长多轮追问。
- Diagram IR 驱动 — 先固化节点、关系、分组与注释，再进入布局与渲染。
- 禁止静默补全 — 未经确认不添加 Redis、消息队列等「看似合理」的基础设施。
- 注册式视觉系统 — 设计系统、布局与组件均来自显式注册表，抑制自由发挥带来的风格漂移。
- 三层质量门禁 — 分别校验语义、设计约束与最终产物；失败时回退至对应阶段。
- 交付就绪 — 输出自包含 HTML、内嵌 SVG 与可见的 PNG 导出能力，无需依赖整页截图。
通过渐进加载，访谈确认与完整出图使用不同的指令上下文预算，避免将全量设计系统与门禁一次性载入模型窗口。下表为仓库内测的 Skill 指令上下文 指标（按阶段允许读取的 unique 文件并集计量）。
口径说明
| 指标 | 定义 |
|---|---|
| 估算 token | unique 文件字节数 ÷ 2.8 |
| 相对速度指数 | 优化前 token ÷ 当前 token，表征上下文负载降幅 |
| 适用范围 | 指令上下文规模；非端到端墙钟耗时（后者仍取决于模型与宿主环境） |
| 场景 | 优化前（≈tokens） | 当前（≈tokens） | 降幅 | 当前体积 |
|---|---|---|---|---|
| Interview（首轮确认） | 4,100 | 2,083 | 49.2% | 5.7 KB |
| 完整路径 · Apple Document | 32,000 | 12,463 | 61.1% | 34.1 KB |
| 完整路径 · Neural Blueprint | 31,000 | 12,307 | 60.3% | 33.7 KB |
| 完整路径 · Cyber Nexus | 30,000 | 11,821 | 60.6% | 32.3 KB |
| 场景 | 相对速度指数 | 解读 |
|---|---|---|
| Interview | 1.97× | 首轮指令上下文约为优化前的 51% |
| 完整路径 · Apple | 2.57× | 全链路指令上下文约为优化前的 39% |
| 完整路径 · Neural | 2.52× | 全链路指令上下文约为优化前的 40% |
| 完整路径 · Cyber | 2.54× | 全链路指令上下文约为优化前的 39% |
详细测量协议仅保留于开发仓库，不包含在 npm /
npx发行包中。
需要 Node.js 18+。
npx visual-architecture@latest默认安装路径：
~/.claude/skills/visual-architecture
用 visual-architecture 画一张架构图。
用途：系统设计文档
风格：Apple Document，浅色，不要图标
内容：用户 → API Gateway → Order Service → PostgreSQL，支付走 Stripe
Agent 将先给出涵盖用途、受众、风格、复杂度与约束的推荐方案；确认后，再生成 Diagram IR、设计决策、HTML + SVG 架构图及验证结果。
Note
visual-architecture 是 Agent Skill，而非独立绘图应用。生成由宿主 AI 编码 Agent 执行，结果可能随模型与工具能力而异。
同一套架构语义可通过不同设计系统呈现，节点与关系保持不变。
| Apple Document | Neural Blueprint | Cyber Nexus |
|---|---|---|
| 浅色、克制，适用于技术文档 | 深色、结构化，适用于工程展示 | 高对比霓虹，适用于演示场景 |
|
 |
 |
生命周期图、处理流程与技术文章插图亦可由同一流水线生成。
| 能力 | 说明 |
|---|---|
| Grill-me Interview | 将用途、受众、风格、复杂度与约束收敛为一次推荐与一次确认 |
| Diagram IR | 以结构化中间表示固化节点、边、分组与注释 |
| Design Resolution | 从已注册设计系统中选定并锁定视觉规则 |
| Layout Planning | 按 Pipeline、Layered 或 Network 策略规划位置与连线 |
| Component Resolution | 将语义类型映射至已注册视觉组件 |
| Gated Rendering | 在语义、设计与产物校验通过后生成 HTML + SVG |
| PNG Export | 自交付页直接导出可用 PNG |
流水线刻意分离「系统包含什么」与「系统如何呈现」：
- Interview — 确认生成目标与视觉约束。
- Analysis — 提取候选语义，不补充未经确认的业务组件。
- Diagram IR — 固化节点、边、分组、关系方向与注释。
- Resolution — 选定设计系统、布局策略与组件映射。
- Rendering — 依据锁定规则生成 HTML + SVG。
- Validation — 校验语义一致性、视觉约束与导出能力。
| 设计系统 | 主题 | 推荐场景 |
|---|---|---|
| Apple Document | 浅色文档风 | 系统设计文档、技术博客、评审材料 |
| Neural Blueprint | 深色科技风 | 工程展示、AI 系统、技术分享 |
| Cyber Nexus | 霓虹演示风 | 发布演示、概念方案、高对比视觉 |
设计系统并非简单换色。每套系统均定义颜色、字体、节点、连线、容器、间距与组件映射规则。
npx visual-architecture [options]
| 选项 | 安装位置 / 行为 |
|---|---|
无参数、--claude |
~/.claude/skills/visual-architecture |
--cursor |
./.cursor/skills/visual-architecture |
--agents |
./.agents/skills/visual-architecture |
--dir <path> |
安装至自定义目录 |
--force, -f |
覆盖已有安装 |
--help, -h |
显示帮助信息 |
示例：
# 安装到 Cursor 项目目录
npx visual-architecture --cursor
# 安装到通用 Agent Skills 目录
npx visual-architecture --agents
# 安装到自定义目录
npx visual-architecture --dir ./skills/visual-architecture
# 覆盖旧版本
npx visual-architecture --cursor --force亦可全局安装：
npm install --global visual-architecture
visual-architecture --help或直接从 GitHub 运行：
npx github:endlessYoung/visual-architecture已有 HTML + SVG 产物无需再次经 Agent 出图。安装项目依赖后，可通过脚本导出单个文件、多个文件或整个目录：
# 导出单个 HTML 中的根 SVG，默认生成同名 2× PNG
npm run export-png -- ./showcase/visual-architecture-pipeline-zh.html
# 递归导出目录中的所有 HTML
npm run export-png -- ./showcase --scale 2
# 点击页面内置导出控件，并验证 G11 导出能力
npm run export-png -- ./showcase/visual-architecture-pipeline-zh.html --page-export其他选项：--out-dir <path>、--selector <css>、--scale <1-4>。重新生成 README 工作流图片：
npm run export-readme-workflow一次完整执行通常包含：
- Interview Result — 已确认的用途、受众、风格与约束
- Diagram IR — 可审查的架构语义模型
- Design Decision — 设计系统、布局与组件映射决策
- HTML + SVG Artifact — 可在浏览器中预览的最终架构图
- Validation Report — 语义、设计与产物层面的检查结果
- PNG Export — 自 HTML 页面导出的图片
visual-architecture/
├── skill/ # Skill 入口、流水线编排与视觉质量门禁
├── core/ # Interview、IR、设计、布局、渲染与验证指令
├── registries/ # 设计系统、组件与布局注册表
├── templates/ # Interview、Diagram IR、设计决策与验证模板
├── showcase/ # README 展示图片
└── bin/ # Skill 安装与展示图导出脚本
Markdown 指令即为核心实现。Agent 在运行时按需加载上述文件，而非调用固定的图形生成 API。
- 当前内置 3 套设计系统与 3 种布局策略。
- 输入以技术描述及 Agent 可读上下文为主，并非自动代码依赖扫描器。
- 生成质量取决于宿主 Agent 对 Skill 指令、文件写入与浏览器预览能力的支持。
- 项目处于早期版本；用于关键文档前，请人工复核架构语义与导出结果。
欢迎提交 Issue 或 Pull Request。
修改流水线行为时，请同步更新对应的 core/ 指令与 skill/instructions/pipeline.md；新增设计系统或组件时，请通过 registries/ 扩展，勿绕过既有解析流程。
基于 MIT License 开源。