跟随路径，查看证据，用一个离线文件分享。
💡 灵感来自 Cocoon-AI/architecture-diagram-generator，感谢原作者的启发。
以 Jeepay 真实源码为例：整图缩小后仍能读出组件名，点开卡片就是对应的源码行，同一个文件里切换组件关系、时序与 ER 图。观看 MP4
支持九类图：【组件关系架构图、流程图、时序图、ER 图、部署图、类图、状态图、用例图、数据流图】
QGraphFlow 从源码、数据结构、配置和需求生成交互式软件图，让关系有据可查，并将结果交付为可分享的离线 HTML。
差异在哪： 一个技能覆盖九类图，每条关系都标明证据类别，有代码支撑的关系还记录对应的源码行，自动布局，能直接在页面里编辑，插件脚本和 Viewer 本身不发任何网络请求。
代码变了，图上直接标出变了什么：generate --compare 对比上一版，把新增、改动和删除的元素标在图上，并列在右侧"本次更新"里，每一项都能点开看源码出处。演示里的上一版是虚构的，用来展示三种标记。在线体验 · 观看 MP4
npx skills add supermax92/qgraphflow一条命令即可为 Claude Code、Codex、Cursor 和 Qoder 装好技能；以插件方式安装和其他客户端见安装指南。
-
探索： 搜索定位、缩放和平移画布，查看组件职责与上下游关系。
-
核验： 从节点或连线查看详情，核对源码文件、行号、符号和明确标注的不确定性。
-
编辑： 解锁后修改文字、移动元素；不满意时一键重置。
-
分享： 打开离线 HTML，或将完整图导出为 SVG / PNG。
基于真实源码的 Jeepay 语料包含 CI 和在线演示用到的全部九个视图。
安装后，在客户端打开你的业务项目，选择 q-flow 技能。以下以 Claude Code 的 /q-flow 为例；Codex 中使用客户端实际提供的 $q-flow 或 $qgraphflow:q-flow 入口。还未安装？先看安装指南。
只调用技能，不附加需求：
/q-flow
技能会引导你选择要分析的部分，以及希望图回答的问题；必要信息明确后开始绘图。
/q-flow 你能绘制哪些类型的图？每类图适合回答什么问题？我刚接手一个项目，请先介绍能力并建议一个起点。
先了解九类图的用途，再决定看项目结构、调用顺序、数据关系还是其他内容。
/q-flow 帮我画一下这个项目，我想尽快看懂它。
不用先指定图类型。技能会根据项目和你的目标确定合适的视图，缺少必要信息时再追问。
将下面的业务名称和步骤替换成项目中实际存在的流程：
/q-flow 分析当前项目的订单创建流程，生成中文时序图。
覆盖请求入口、价格计算、库存预占、支付授权和订单落库。
保留源码中实际存在的同步调用、异步消息、成对返回、激活条、条件分支、重试和失败补偿，不要为了简洁省略细节。
标明组件与调用的源码文件和行号，将结果保存到 docs/qgraphflow/order-sequence/。
把对象、问题、详细程度和输出位置说清楚，就能直接开始；图中只保留有证据支持的事实。
在生成结果后，于同一对话中继续：
/q-flow 展开上一张时序图中的库存预占步骤，单独生成中文流程图。
完整展示库存校验、预占成功、可重试失败、重试上限和释放库存的分支，以源码为准，不添加代码中没有的步骤。
先看整体，再深入一个步骤；也可以继续要求补充已有图的细节或核验其中的关系。
准备 Node.js 22 及以上版本，以及已配置好模型访问、支持插件功能的客户端。
npx skills add supermax92/qgraphflow已用 skills 1.7.0 在 Claude Code、Codex、Cursor 和 Qoder 上实测。命令会询问装到哪些客户端；-a claude-code 可直接指定，-g 改为装到当前用户而不是当前项目。这样装上的技能名是 q-flow，不带下文插件安装方式里的 qgraphflow: 前缀。
如需以插件方式安装，按以下步骤操作。Qoder Desktop 可直接从插件商城安装，跳过第 1 步。
从 npmjs.com 获取插件，无需账号、登录或令牌。在业务项目之外创建独立目录：
mkdir qgraphflow-install
cd qgraphflow-install
npm install qgraphflow --ignore-scripts
cd node_modules/qgraphflow此时已进入插件根目录。npm 下载不会自动完成客户端安装，请继续第 2 步。这个包还提供 qgraphflow 命令，让图和代码保持同步一节会用到。
以下终端命令均在包含 skills/ 的插件根目录执行。
终端需已安装 Codex CLI：
codex plugin marketplace add .
codex plugin add qgraphflow@supermax92新建会话，输入 $，选择 qgraphflow:q-flow。
claude plugin marketplace add ./
claude plugin install qgraphflow@supermax92 --scope user新建会话，输入 /q-flow（或完整名称 /qgraphflow:q-flow）。
qodercli plugins install .新建会话，选择 q-flow。
**推荐：**打开 Settings → Plugins → Marketplace，搜索 QGraphFlow 或 代码图谱可视化，安装插件。新建会话，选择 q-flow。
如需本地安装，先完成第 1 步，再打开 Settings → Plugins → Custom → Import，导入完整的插件根目录。新建会话，选择 q-flow。
将插件根目录中的全部内容（含隐藏文件）复制到：
~/.cursor/plugins/local/qgraphflow/
确认其中存在 .cursor-plugin/plugin.json，重新加载窗口，在 Customize 中找到 q-flow。若已有旧版本，先备份，勿混合新旧文件。
在客户端打开你的业务项目，新建会话并选择技能，按快速入门中的示例描述需求。生成后，用浏览器打开输出的 HTML。
需要自行构建？参见源码构建说明。
以下以 Codex 的 $qgraphflow:q-flow 入口为例；如果客户端显示 $q-flow，请选择它实际提供的入口。其他客户端使用上方对应的技能入口。
不知道从哪里开始？ 直接调用，按提示选择要分析的部分和想了解的问题。
$qgraphflow:q-flow
目标已经明确？ 一句话说明“画哪个部分＋想看什么”，无需先选择图类型。
$qgraphflow:q-flow 分析当前项目，生成中文架构图，展示主要模块的职责、依赖关系和系统边界。
适合初次接触项目，先了解整体结构。
$qgraphflow:q-flow 分析订单创建流程，生成中文时序图，展示价格计算、库存预占、支付和订单落库的调用顺序，并标明失败分支。
将“订单创建”及相关步骤替换成项目中的实际业务流程。看完后，在同一对话中继续追问：
$qgraphflow:q-flow 展开上一张图中的库存预占步骤，单独生成中文流程图，展示成功与失败的处理流程。
结果默认保存在 docs/qgraphflow/ 下：打开 index.html 即可交互查看、编辑和导出，graph.json 保留图数据。每个视图还会写出一份 SVG（diagram.svg，多视图时为 diagram-<n>-<type>.svg），可以直接作为图片嵌进 README、PR 或 Wiki。
在页面里编辑后，用 Chrome 或 Edge 执行「更多 → 保存修改」并选一次图所在的文件夹，即可原地重写页面、graph.json 和 SVG。其他浏览器只能保存 graph.json：把它放回该文件夹，再用 npx -y qgraphflow generate docs/qgraphflow/<name>/graph.json docs/qgraphflow/<name> --layout preserve --force 重新生成页面和 SVG。
运行基于 Jeepay 源码的九视图示例
指定本机的 Jeepay 源码目录来核验证据：
export JEEPAY_REPO_ROOT="<local Jeepay repository root>"
node skills/q-flow/scripts/validate-graph.mjs examples/jeepay/collection.graph.json --input-only --repo-root "$JEEPAY_REPO_ROOT"
node skills/q-flow/scripts/generate-viewer.mjs examples/jeepay/collection.graph.json output/jeepay --repo-root "$JEEPAY_REPO_ROOT"打开 output/jeepay/index.html，九个 SVG 在同一目录。源码版本和刷新步骤见语料 README。
带仓库根目录生成的图会记下每个组件定义在哪里、每条有代码支撑的关系所在的那一行（调用、外键等），以及它指向的每个文件的内容指纹。用 --repo-root 校验时，只是挪了位置的行会自动对上、照常通过；只有图背后的代码真的变了才会失败：记录的那一行被改写、某个调用被删掉、新代码碰到了图里画的组件却没有对应的关系，或者图里用到的名字已经不存在。错误里会给出改动前后的代码，并指出要更新的元素和文字。把下面这个任务加进 CI，不需要构建、登录或令牌；拉取完整历史（fetch-depth: 0）才能和这些指纹比对：
name: Diagrams
on: [push, pull_request]
jobs:
diagrams:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
- uses: actions/setup-node@v7
with:
node-version: '22'
- run: |
for graph in docs/qgraphflow/*/graph.json; do
npx -y qgraphflow validate "$graph" --input-only --repo-root . || { echo "::error file=$graph::$graph failed validation"; failed=1; }
done
exit ${failed:-0}想在 PR 里直接看到受影响的地方，就在 validate 那一行加上 --changes changes.md，失败时把这个文件贴成评论，例如 gh pr comment "$PR" --body-file changes.md（需要 pull-requests: write 权限）。它按视图列出每处改动碰到的元素、文件和行号，以及改动前后的代码。执行 --fix 后重新生成的页面也会标出这些元素，并在要点旁列出这些改动。
失败后，让技能刷新这张图：
$qgraphflow:q-flow CI 提示 docs/qgraphflow/order-sequence 的图过时了，刷新一下。
技能会把所有锚点对齐到当前代码，把每处改动列进图的 meta.sourceDrift，只更新这些条目指出的元素，再保留你调整过的位置和文字，重新生成页面和 SVG；不会重画整张图。
重新生成时加上 --compare HEAD，就能看出这次刷新改了什么：页面把新增和改动的元素着色，在要点旁列出删掉的元素，graph.json 不受影响。
| 视图 · PNG | 主要问题 | 本示例范围 |
|---|---|---|
| 组件关系架构图 | 系统由哪些责任边界协作？ | 渠道、交易编排、价格、风控、库存、支付、订单、事件与履约 |
| 流程图 | 每个决策点如何分支和收敛？ | 缺货、风控拒绝、支付失败补偿与成功提交 |
| 时序图 | 一次请求按什么顺序调用和返回？ | 成功结算主链及异步 OrderPaid |
| ER 图 | 核心数据如何关联？ | 购物车、订单、明细、支付、库存预占和包裹 |
| 部署图 | 运行单元放在哪里、怎样连接？ | 边缘、Kubernetes、数据服务、支付和仓配网络 |
| 类图 | 领域对象和代码契约怎样依赖？ | Checkout 应用服务、Order 与四个端口 |
| 状态图 | 订单受哪些事件和守卫条件推进？ | 支付、履约、取消、退款和关闭 |
| 用例图 | 每类参与者拥有哪些能力？ | 买家、商家、仓库与客服 |
| 数据流图 | 数据资产经过哪些变换和存储？ | 购物车、交易决策、订单事件、仓配和物流回执 |
这是用于展示 QGraphFlow 能力的概念模型，不对应某个电商仓库。graph.json 不伪造源码路径，关系证据统一标记为 inference；对真实项目绘图时，应改用源码、DDL、配置、测试和已接受需求中的可追溯证据。
npm ci --prefix skills/q-flow/assets/viewer
npm run build --prefix skills/q-flow/assets/viewer
node --test tests/*.test.mjs skills/q-flow/scripts/*.test.mjs开发需要 Node.js 22 及以上版本、npm、tar、zip 和 unzip。反馈问题时，请附最小脱敏图数据、客户端和浏览器版本，以及复现步骤。
参考文档（英文）：证据来源 · 图数据格式 · 需求引导 · Viewer 开发与验收 · 图形表达约定
QGraphFlow 是采用 MIT 许可证的独立项目。本文场景为概念示例，不代表任何真实公司的生产架构。