内容
# C4X - C4 模型图适用于 VS Code
[](https://www.typescriptlang.org/)
快速的离线 C4 架构图，带有实时预览和通过 Google Gemini 的 AI 生成。受 Mermaid 启发的 DSL，符合 C4 标准的 SVG 渲染，PNG 导出和 1500+ 云图标。
<img src="assets/marketplace/images/c4x-system-context-v140.png" width="700" alt="C4X 系统上下文图" />
## 版本 1.4.0 新增功能
- **PNG 导出** -- 基于画布的 1 倍/2 倍/4 倍分辨率，不需要 Chromium
- **C4 标准主题** -- 官方填充框约定作为新默认主题
- **自动布局** -- 智能方向：小图 LR，大图 TB
- **24 种架构模式示例** -- [CQRS, Saga, BFF, 六边形, IoT, CI/CD, 零信任等](./docs/EXAMPLES-PATTERNS.md)
- **所有 C4 视图级别已记录** -- [C1 至 C4 + 动态图](./docs/EXAMPLES-VIEWS.md)
- **398 个单元测试**，解析器覆盖率 94%，模型覆盖率 98%
## 功能
- **即时预览** -- 30 节点图的渲染时间小于 50 毫秒，边写边预览
- **AI 生成（Gemini）** -- 代码转图，文本转图，视觉 PNG 生成
- **所有 C4 级别** -- 系统上下文，容器，组件，部署和动态视图
- **6 种主题** -- C4 标准（默认），经典，现代，柔和，高对比度，自动
- **导出** -- PNG（1 倍/2 倍/4 倍），SVG，复制 SVG 并保留主题
- **1500+ 个图标** -- AWS，Azure，GCP，具有 IntelliSense 自动完成（`$sprite` 语法）
- **Markdown 集成** -- 在 README 和架构文档中直接渲染 `c4x` 块
- **自动布局** -- 智能方向选择：小图水平，大图垂直
- **自我纠正 AI** -- 解析器验证输出，自动重试和自我修复
- **MCP 服务器** -- 用于 Claude、Cursor 等 AI 助手的内置验证器
### 观看 30 秒演示
[](https://youtu.be/qR1bbctj2rQ)
## 快速入门
### 安装
**VS Code 市场**（推荐）：在扩展（`Cmd+Shift+X`）中搜索“C4X”并安装。
**命令行**：`code --install-extension jpantsjoha.c4x`
### 创建图表
1. 创建一个文件 `architecture.c4x`
2. 编写您的图表：
```c4x
%%{ c4: system-context }%%
graph TB
Customer[客户<br/>人员]
Banking[银行系统<br/>软件系统]
Email[电子邮件系统<br/>软件系统<br/>外部]
Customer -->|使用| Banking
Banking -->|发送通知| Email
```
1. 打开预览：`Cmd+K V`（或 `Ctrl+K V`）
无需 Java，无需服务器，无需配置。
### 嵌入 Markdown
````text
```c4x
%%{ c4: system-context }%%
graph TB
User[用户<br/>人员]
System[我的系统<br/>软件系统]
User -->|使用| System
```
````
该扩展在 VS Code 的 Markdown 预览中将 `c4x` 代码块渲染为可视化图表。
## DSL 语法
### 元素
```text
%% 括号语法
Admin[管理员<br/>人员]
API[支付 API<br/>软件系统<br/>外部]
%% 函数语法（支持图标，技术，描述）
Container(WebApp, "Web 应用", "React", $sprite="c4xicons.aws.elastic-beanstalk-application")
ContainerDb(DB, "数据库", "PostgreSQL")
Person(User, "最终用户")
```
类型：`Person`，`Software System`，`Container`，`ContainerDb`，`Component`，`ComponentDb`，以及外部元素的 `*_Ext` 变体。
### 关系
```text
A -->|标签| B %% 标准依赖
A ==>|标签| B %% 同步/阻塞
A -.->|标签| B %% 异步/事件驱动
```
### 边界
```c4x
%%{ c4: container }%%
graph TB
User[用户<br/>人员]
subgraph BankingSystem {
WebApp[Web 应用<br/>容器]
Database[数据库<br/>容器]
}
User -->|使用| WebApp
WebApp ==>|读取/写入| Database
```
### 视图类型
```text
%%{ c4: system-context }%% %% C1
%%{ c4: container }%% %% C2
%%{ c4: component }%% %% C3
%%{ c4: deployment }%% %% C4
%%{ c4: dynamic }%% %% 序列/交互
```
完整参考：[语法指南](./docs/c4x-syntax.md)
## AI 生成（Gemini）
C4X 使用 Google Gemini 从代码、文本或选择中生成图表。
**设置**：从 [Google AI Studio](https://aistudio.google.com/) 获取免费的 API 密钥，或为企业合规性使用 [Google Cloud](https://cloud.google.com/) Vertex AI 密钥。密钥存储在 VS Code 的加密 SecretStorage 中。
**默认模型**：`gemini-3-flash-preview`（免费层），自动回退到 `gemini-3.1-pro-preview`。通过设置中的 `c4x.ai.model` 配置任何 Gemini 模型。
| 命令 | 功能 |
|---------|-------------|
| `C4X: 在此处生成图表` | 从上下文中在光标处生成 C4X 图表 |
| `C4X: 从选择中生成`（`Alt+V`） | 从突出显示的文本中生成视觉 PNG |
| `C4X: 从工作区生成` | 分析代码文件并创建 C4 模型 |
所有 AI 生成的图表都经过解析器验证，尝试 3 次自我纠正。
完整指南：[Gemini AI 指南](./docs/GEMINI_GUIDE.md) | [视觉图表指南](./docs/DIAGRAM-WITH-GEMINI-IMAGE.md)
## 图标
1500+ 个内置云和技术图标，具有 IntelliSense 自动完成。
```c4x
Container(S3, "存储", "AWS S3", $sprite="c4xicons.aws.simple-storage-service-bucket")
ContainerDb(DB, "数据库", "Cloud SQL", $sprite="c4xicons.gcp.cloudsql")
```
完整图标目录：[图标和示例](./docs/EXAMPLES-with-ICONS.md)
## 导出
| 命令 | 格式 | 备注 |
|---------|--------|-------|
| `C4X: 导出 PNG` | PNG | 1 倍，2 倍或 4 倍分辨率。基于画布，不需要 Chromium。 |
| `C4X: 导出 SVG` | SVG | 矢量格式，适用于 Figma，Sketch，Illustrator |
| `C4X: 复制 SVG 到剪贴板` | SVG | 快速粘贴到其他应用程序 |
导出的图表保留您选择的主题。
## 主题
| 主题 | 描述 |
|-------|-------------|
| **C4 标准** | 官方填充框约定（默认） |
| 经典 | 白色填充，彩色边框 |
| 现代 | 鲜艳的颜色，圆角 |
| 柔和 | 灰度极简主义 |
| 高对比度 | WCAG AAA 合规 |
| 自动 | 适应 VS Code 亮/暗主题 |
通过命令面板（`C4X: 更改主题`）或设置（`"c4x.theme": "modern"`）进行更改。
## 示例和文档
| 指南 | 内容 |
|-------|---------|
| [示例画廊](./docs/EXAMPLES.md) | 银行，微服务，AI 代理 |
| [所有 C4 视图级别](./docs/EXAMPLES-VIEWS.md) | C1-C4 + 动态，关系类型，数据库变体 |
| [架构模式](./docs/EXAMPLES-PATTERNS.md) | CQRS，事件溯源，Saga，BFF，六边形，IoT，CI/CD 等 |
| [云图标](./docs/EXAMPLES-with-ICONS.md) | AWS，Azure，GCP 精灵，具有自动完成功能 |
| [布局指南](./docs/EXAMPLES-LAYOUT.md) | 方向控制，嵌套布局，手动定位 |
| [排序指南](./docs/EXAMPLES-ORDERING.md) | 控制元素放置 |
| [视觉图表](./docs/DIAGRAM-WITH-GEMINI-IMAGE.md) | AI 支持的 PNG 生成 |
| [语法参考](./docs/c4x-syntax.md) | 完整的 DSL 规范 |
| [生成指南](./docs/C4X-GENERATION-GUIDELINES.md) | 高级 AI 提示 |
## MCP 服务器
C4X 包含用于 AI 助手集成的模型上下文协议服务器。
```json
{
"mcpServers": {
"c4x-validator": {
"command": "node",
"args": ["/path/to/c4x-vscode-extension/out/mcp/c4x-mcp-server.js"]
}
}
}
```
**工具**：`validate_c4x` -- 验证语法，返回用于自动纠正的行/列错误。
**资源**：`c4x://guidelines`，`c4x://syntax`，`c4x://examples/*`
适用于 Claude Desktop、Cursor、Windsurf、Cline 和任何与 MCP 兼容的客户端。
## 性能
| 指标 | 目标 | 实现 |
|--------|--------|----------|
| 激活 | < 200 毫秒 | **0.15 毫秒** |
| 包大小 | < 1MB | **386KB** |
| 解析 | < 50 毫秒 | **10 毫秒** |
| 预览渲染 | < 250 毫秒 | **55 毫秒** |
在 30 节点图上测试。398 个单元测试，解析器覆盖率 94%，模型覆盖率 98%。
## 路线图
**已发布**：v1.4.0（2026 年 5 月）-- PNG 导出，自动布局，398 个测试，符合 C4 标准的渲染器，模型验证
**下一个**：v1.5.0 “Copilot 聊天和导入桥”（2026 年第三季度）
- `@c4x` VS Code Copilot 聊天参与者
- Mermaid C4 导入桥
- 用于分层边界的 ELK 布局引擎
- 自定义本地精灵（`$sprite="./logo.png"`）
完整路线图：[docs/ROADMAP.md](./docs/ROADMAP.md)
## 贡献
通过 [GitHub 问题](https://github.com/jpantsjoha/c4x-vscode-extension/issues) 和拉取请求欢迎贡献。有关指南，请参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
## 作者的其他作品
- **[Pine Script (v5)](https://marketplace.visualstudio.com/items?itemName=jpantsjoha.pine-script-v5)** -- 交易视图 Pine Script 的语法高亮、代码片段和校验
## 许可证
MIT -- 请参阅 [LICENSE](./LICENSE)。
## 致谢
- [C4 模型](https://c4model.com/) by Simon Brown
- [Mermaid.js](https://mermaid.js.org/) -- DSL 语法灵感
- [Dagre.js](https://github.com/dagrejs/dagre) -- 图形布局引擎
---
**使用 [Gemini](https://blog.google/products/gemini/gemini-3/) 为架构师打造，强调简单** | [报告问题](https://github.com/jpantsjoha/c4x-vscode-extension/issues) | [在 GitHub 上点赞](https://github.com/jpantsjoha/c4x-vscode-extension)
