Diagram Plugin

在 Codex 与 DeepSeek Harness 的对话旁，实时生成、编辑和演进 Mermaid 与 Canvas 图表。

图表以纯文本保存在项目仓库中，可读、可 diff、可版本控制。

对话旁实时预览	Canvas 可视化编辑

快速安装

Codex Desktop / CLI（Node.js 22+，已安装 codex 命令）：

npx -y @weimin96/diagram-plugin@latest install --codex

DeepSeek Harness Desktop：在「插件 → 添加插件」中输入 @weimin96/diagram-plugin。

安装后重新打开对应 Desktop，在项目对话中打开 Diagram，或让助手创建图表。Codex CLI 负责注册与调用图表 MCP 工具；右侧可视化面板需在支持 MCP Apps 的 Codex Desktop 中使用。两个宿主共享图表能力，但使用各自的插件安装方式，无需克隆本仓库或自行构建。

安装详情 · 功能特性 · 开始使用 · 常见问题 · 开发文档

安装与管理

Codex

安装前确认命令可用：

node --version
codex --version

执行 npm 包的安装命令：

npx -y @weimin96/diagram-plugin@latest install --codex

安装器会将构建产物保存到 ~/.codex/diagram-plugin-npm/（设置了 CODEX_HOME 时使用对应目录），并注册 diagram-plugin-npm marketplace 及 MCP 服务。重新打开 Codex Desktop 后即可使用对话旁的 Diagram 面板。

验证是否安装成功：

codex plugin list --json

输出中应存在 diagram-plugin@diagram-plugin-npm，且 installed、enabled 均为 true。升级时重复执行同一条 npx 命令即可，安装器会替换自己管理的版本，不修改其他插件。

从源码版迁移：如果以前安装了 diagram-plugin@diagram-plugin-local，先移除旧版，再安装 npm 版，避免重复注册：

codex plugin remove diagram-plugin@diagram-plugin-local
npx -y @weimin96/diagram-plugin@latest install --codex

卸载 npm 版：

codex plugin remove diagram-plugin@diagram-plugin-npm
codex plugin marketplace remove diagram-plugin-npm

以上命令会解除插件与 marketplace 注册。持久化的文件目录 ~/.codex/diagram-plugin-npm/ 不会自动删除，如不再需要，可确认路径后手动删除。

git clone https://github.com/weimin96/diagram-plugin.git
cd diagram-plugin
pnpm install
pnpm plugin:install

DeepSeek Harness

在 Desktop 的「插件 → 添加插件」中输入：

@weimin96/diagram-plugin

安装后重新打开 Desktop，在项目对话的标题栏打开 Diagram。使用宿主自带运行时，无需另配 Node.js。

dsh plugin --profile desktop add @weimin96/diagram-plugin

卸载时完全退出 Desktop，执行 dsh plugin --profile desktop remove @weimin96/diagram-plugin；更新时可先移除旧版，再安装最新版。

DeepSeek Web 使用单独的插件配置文件（--profile web），不会自动继承 Desktop 安装。详细配置见开发与发布。

不要为同一个 Diagram 再配置通用 MCP 客户端，否则会出现重复工具，并可能让模型与图表面板连接到不同实例。

功能特性

• 对话伴随面板：在当前聊天右侧打开 Diagram，助手读取、创建或修改图表时面板自动跟随；支持多图标签页和跟随开关。
• 双图表引擎：结构化图使用 Mermaid，直接读写 .mmd / .mermaid；自由布局与系统架构使用 Canvas，保存为可版本控制的 .diagram.json。
• 19 种 Mermaid 图表：覆盖流程图、时序图、思维导图（脑图）、类图、ER 图、状态图、甘特图、时间线、Git 分支图、用户旅程、四象限、看板、需求图、桑基图、XY 图、饼图、雷达图、矩形树图和鱼骨图。
• 3 种 Canvas 工作台：架构画布、流程画布和自由画布，分别面向系统拓扑、手工流程和白板草图。
• AI 可读可改：通过 MCP 工具按需读取图表；修改先生成可审查的 Proposal Diff，支持部分接受、A/B 候选与字段级并发 rebase。
• 安全可回溯：保存时检查文件 revision，采用原子写入；AI 修改拥有独立历史和依赖 DAG，可按子图撤销与重做。
• 架构设计系统：自动分区、语义配色、角色与云厂商图标、C4 语义、正交连线路由和 12 套可切换的共享视觉样式。
• 代码与图联动：节点可绑定真实源码文件，支持按源码反查节点、批量同步模块节点，以及将 Git 改动映射为架构影响分析。
• 完整编辑器：CodeMirror 源码编辑、实时预览、缩放平移、多选/框选、对齐分布、分组与泳道、MiniMap、图层顺序和 SVG / PNG 导出。
• 本地优先：不依赖云端服务，所有图表默认保存在项目的 docs/diagrams/ 中。

支持的图表

共支持 3 种 Canvas 画布工作台与 19 种 Mermaid 图表。每种 Mermaid 类型都有独立的构图原型、密度策略与质量检查规则。

Canvas 画布

架构画布内置系统架构、C4 系统上下文、C4 容器、C4 组件、服务拓扑、事件与数据流等生成预设。

架构画布还内置角色与技术语义、命名分区、C4 容器、云厂商图标和正交连线路由，可用 diagram.beautifyArchitecture 一键整理。

Mermaid 图表

结构化图表直接读写 .mmd / .mermaid 文件。

核心结构

分析与规划

数据可视化

专业分析

数据类图表只使用真实数据或用户明确给出的示意数据，不要为图形效果编造数值。

内置类型聚焦上表 19 种。Mermaid 的 C4、architecture-beta、block-beta、packet-beta 等扩展语法没有专门的构图规则与质量检查；架构类需求请使用 Canvas 架构画布。

开始使用

1. 在 Codex 或 DeepSeek Harness 中打开一个项目聊天。
2. 从聊天标题栏打开 Diagram，或直接对助手说「打开右侧画板」。
3. 用自然语言描述需求，助手会创建或修改图表，右侧面板自动跟随。

一些常见指令：

根据 src/ 生成系统架构图，使用架构画布
把登录流程画成时序图
检查当前图的布局，减少连线交叉
给支付服务补充异常分支，并先给我看 Diff

对已有图的修改默认先生成 Proposal，只有接受后才会写入磁盘。需要批量浏览、导出或完整分屏编辑时，打开全局 Diagram 图表库。

图表默认保存到当前项目：

docs/diagrams/
├── login-flow.mmd
├── system-architecture.diagram.json
└── exports/
    └── system-architecture.png

常用操作

常见问题

MCP 工具

Diagram 以 MCP Server 形式运行，模型与图表面板共享同一个服务实例。暴露给模型的常用工具如下（在 DeepSeek Harness 中注册为 diagram_create 等下划线形式）：

其余工具中，Proposal 接受/拒绝、Patch 撤销重做、导出与图片资源等仅供图表面板调用，不会暴露给模型；完整工具列表以 MCP listTools 返回为准。

已知限制

• Canvas 聚焦架构草图与流程场景，暂不包含手绘压感、图片批注和多人实时协作。
• 宿主目前没有公开「当前活动编辑器文件 / 代码选区」的读取接口，生成图表时需从工作区选择文件或目录。
• Codex npm 安装已在隔离环境验证 CLI 安装、启用与 MCP 服务；不同平台上的 Codex Desktop 侧边面板仍需原生交互验收。
• DeepSeek Harness 已在 macOS 完成原生验收；Windows、Linux 与其他宿主版本尚未验证。

开发

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm smoke
pnpm check:hosts

视觉验收：

pnpm visual:verify

架构说明、本地调试、打包发布和宿主适配细节见 开发与发布。

贡献

欢迎提交 Issue 和 Pull Request。提交前请至少运行：

pnpm typecheck && pnpm test && pnpm build

开源协议

本项目基于 MIT License 开源，Copyright © 2026 weimin96。

第三方图标与资源声明见 THIRD_PARTY_NOTICES.md。