supermax92
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/supermax92/qgraphflow with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/supermax92/qgraphflow'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/supermax92--qgraphflow)HTML
<a href="/listings/supermax92--qgraphflow"><img src="/api/listings/supermax92--qgraphflow/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 17 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "name": "supermax92",
- "owner": {
- "name": "Max Zheng"
- },
- "metadata": {
- "description": "Plugins by Max Zheng, including QGraphFlow for evidence-grounded interactive diagrams."
- },
- "plugins": [
- {
- "name": "qgraphflow",
- "version": "0.1.0",
- "source": "./",
- "description": "Generate evidence-grounded interactive software diagrams with offline HTML, SVG and PNG export."
- }
- ]
- }
README.md · README · 301 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <div align="center">
- <h1><picture><source media="(prefers-color-scheme: dark)" srcset="docs/images/brand/qgraphflow-lockup-dark.svg"><img src="docs/images/brand/qgraphflow-lockup-light.svg" alt="QGraphFlow" height="64"></picture></h1>
- ### 把复杂代码,变成可以探索的图。
- 跟随路径,查看证据,用一个离线文件分享。
- <sub>💡 灵感来自 <a href="https://github.com/Cocoon-AI/architecture-diagram-generator">Cocoon-AI/architecture-diagram-generator</a>,感谢原作者的启发。</sub>
- [中文](README.md) · [English](README.en.md)
- [在线演示](https://supermax92.github.io/qgraphflow/) · [快速入门](#快速入门) · [客户端安装](#安装指南) · [反馈问题](https://github.com/supermax92/qgraphflow/issues) · [MIT](LICENSE)
- </div>
- 
- 以 Jeepay 真实源码为例:整图缩小后仍能读出组件名,点开卡片就是对应的源码行,同一个文件里切换组件关系、时序与 ER 图。[观看 MP4](https://github.com/supermax92/qgraphflow/releases/download/showcase-v3/jeepay.zh-CN.hero.mp4)
- *支持九类图:【组件关系架构图、流程图、时序图、ER 图、部署图、类图、状态图、用例图、数据流图】*
- QGraphFlow 从源码、数据结构、配置和需求生成交互式软件图,让关系有据可查,并将结果交付为可分享的离线 HTML。
- **差异在哪:** 一个技能覆盖九类图,每条关系都标明证据类别,有代码支撑的关系还记录对应的源码行,自动布局,能直接在页面里编辑,插件脚本和 Viewer 本身不发任何网络请求。
- 
- 代码变了,图上直接标出变了什么:`generate --compare` 对比上一版,把新增、改动和删除的元素标在图上,并列在右侧"本次更新"里,每一项都能点开看源码出处。演示里的上一版是虚构的,用来展示三种标记。[在线体验](https://supermax92.github.io/qgraphflow/jeepay/changes/zh-CN/) · [观看 MP4](https://github.com/supermax92/qgraphflow/releases/download/showcase-v3/jeepay.zh-CN.changes.mp4)
- ```bash
- npx skills add supermax92/qgraphflow
- ```
- 一条命令即可为 Claude Code、Codex、Cursor 和 Qoder 装好技能;以插件方式安装和其他客户端见[安装指南](#安装指南)。
- - **探索:** 搜索定位、缩放和平移画布,查看组件职责与上下游关系。
- - **核验:** 从节点或连线查看详情,核对源码文件、行号、符号和明确标注的不确定性。
- - **编辑:** 解锁后修改文字、移动元素;不满意时一键重置。
- - **分享:** 打开离线 HTML,或将完整图导出为 SVG / PNG。
- 基于真实源码的 [Jeepay 语料](examples/jeepay)包含 CI 和在线演示用到的全部九个视图。
- ## 快速入门
- 安装后,在客户端打开你的业务项目,选择 `q-flow` 技能。以下以 Claude Code 的 `/q-flow` 为例;Codex 中使用客户端实际提供的 `$q-flow` 或 `$qgraphflow:q-flow` 入口。还未安装?先看[安装指南](#安装指南)。
- ### 1. 空白输入:不知道从哪里开始
- 只调用技能,不附加需求:
- ```text
- /q-flow
- ```
- 技能会引导你选择要分析的部分,以及希望图回答的问题;必要信息明确后开始绘图。
- ### 2. 询问能力:先了解能画什么
- ```text
- /q-flow 你能绘制哪些类型的图?每类图适合回答什么问题?我刚接手一个项目,请先介绍能力并建议一个起点。
- ```
- 先了解九类图的用途,再决定看项目结构、调用顺序、数据关系还是其他内容。
- ### 3. 模糊输入:只有一个大致目标
- ```text
- /q-flow 帮我画一下这个项目,我想尽快看懂它。
- ```
- 不用先指定图类型。技能会根据项目和你的目标确定合适的视图,缺少必要信息时再追问。
- ### 4. 精准输入:明确范围并要求绘制细节
- 将下面的业务名称和步骤替换成项目中实际存在的流程:
- ```text
- /q-flow 分析当前项目的订单创建流程,生成中文时序图。
- 覆盖请求入口、价格计算、库存预占、支付授权和订单落库。
- 保留源码中实际存在的同步调用、异步消息、成对返回、激活条、条件分支、重试和失败补偿,不要为了简洁省略细节。
- 标明组件与调用的源码文件和行号,将结果保存到 docs/qgraphflow/order-sequence/。
- ```
- 把对象、问题、详细程度和输出位置说清楚,就能直接开始;图中只保留有证据支持的事实。
- ### 5. 继续细化:展开上一张图的局部
- 在生成结果后,于同一对话中继续:
- ```text
- /q-flow 展开上一张时序图中的库存预占步骤,单独生成中文流程图。
- 完整展示库存校验、预占成功、可重试失败、重试上限和释放库存的分支,以源码为准,不添加代码中没有的步骤。
- ```
- 先看整体,再深入一个步骤;也可以继续要求补充已有图的细节或核验其中的关系。
- ## 安装指南
- 准备 Node.js 22 及以上版本,以及已配置好模型访问、支持插件功能的客户端。
- ### 快速安装
- ```bash
- npx skills add supermax92/qgraphflow
- ```
- 已用 `skills` 1.7.0 在 Claude Code、Codex、Cursor 和 Qoder 上实测。命令会询问装到哪些客户端;`-a claude-code` 可直接指定,`-g` 改为装到当前用户而不是当前项目。这样装上的技能名是 `q-flow`,不带下文插件安装方式里的 `qgraphflow:` 前缀。
- 如需以插件方式安装,按以下步骤操作。[Qoder Desktop](#qoder-desktop) 可直接从插件商城安装,跳过第 1 步。
- ### 1. 下载插件
- 从 npmjs.com 获取插件,无需账号、登录或令牌。在业务项目之外创建独立目录:
- ```bash
- mkdir qgraphflow-install
- cd qgraphflow-install
- npm install qgraphflow --ignore-scripts
- cd node_modules/qgraphflow
- ```
- 此时已进入插件根目录。**npm 下载不会自动完成客户端安装**,请继续第 2 步。这个包还提供 `qgraphflow` 命令,[让图和代码保持同步](#让图和代码保持同步)一节会用到。
- 以下终端命令均在**包含 `skills/` 的插件根目录**执行。
- ### 2. 选择客户端安装
- #### Codex App / CLI
- 终端需已安装 Codex CLI:
- ```bash
- codex plugin marketplace add .
- codex plugin add qgraphflow@supermax92
- ```
- 新建会话,输入 `$`,选择 `qgraphflow:q-flow`。
- #### Claude Code
- ```bash
- claude plugin marketplace add ./
- claude plugin install qgraphflow@supermax92 --scope user
- ```
- 新建会话,输入 `/q-flow`(或完整名称 `/qgraphflow:q-flow`)。
- #### Qoder CLI
- ```bash
- qodercli plugins install .
- ```
- 新建会话,选择 `q-flow`。
- #### Qoder Desktop
- **推荐:**打开 **Settings → Plugins → Marketplace**,搜索 **QGraphFlow** 或 **代码图谱可视化**,安装插件。新建会话,选择 `q-flow`。
- 如需本地安装,先完成第 1 步,再打开 **Settings → Plugins → Custom → Import**,导入完整的插件根目录。新建会话,选择 `q-flow`。
- #### Cursor
- 将插件根目录中的全部内容(含隐藏文件)复制到:
- ```text
- ~/.cursor/plugins/local/qgraphflow/
- ```
- 确认其中存在 `.cursor-plugin/plugin.json`,重新加载窗口,在 **Customize** 中找到 `q-flow`。若已有旧版本,先备份,勿混合新旧文件。
- ### 3. 开始使用
- 在客户端打开你的业务项目,新建会话并选择技能,按[快速入门](#快速入门)中的示例描述需求。生成后,用浏览器打开输出的 HTML。
- 需要自行构建?参见[源码构建说明](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally)。
- ## 快速使用
- 以下以 Codex 的 `$qgraphflow:q-flow` 入口为例;如果客户端显示 `$q-flow`,请选择它实际提供的入口。其他客户端使用上方对应的技能入口。
- **不知道从哪里开始?** 直接调用,按提示选择要分析的部分和想了解的问题。
- ```text
- $qgraphflow:q-flow
- ```
- **目标已经明确?** 一句话说明“画哪个部分+想看什么”,无需先选择图类型。
- ### 示例一:看懂项目架构
- ```text
- $qgraphflow:q-flow 分析当前项目,生成中文架构图,展示主要模块的职责、依赖关系和系统边界。
- ```
- 适合初次接触项目,先了解整体结构。
- ### 示例二:追踪业务调用
- ```text
- $qgraphflow:q-flow 分析订单创建流程,生成中文时序图,展示价格计算、库存预占、支付和订单落库的调用顺序,并标明失败分支。
- ```
- 将“订单创建”及相关步骤替换成项目中的实际业务流程。看完后,在同一对话中继续追问:
- ```text
- $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。
- <details>
- <summary>运行基于 Jeepay 源码的九视图示例</summary>
- 指定本机的 Jeepay 源码目录来核验证据:
- ```bash
- 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](examples/jeepay)。
- </details>
- ## 让图和代码保持同步
- 带仓库根目录生成的图会记下每个组件定义在哪里、每条有代码支撑的关系所在的那一行(调用、外键等),以及它指向的每个文件的内容指纹。用 `--repo-root` 校验时,只是挪了位置的行会自动对上、照常通过;只有图背后的代码真的变了才会失败:记录的那一行被改写、某个调用被删掉、新代码碰到了图里画的组件却没有对应的关系,或者图里用到的名字已经不存在。错误里会给出改动前后的代码,并指出要更新的元素和文字。把下面这个任务加进 CI,不需要构建、登录或令牌;拉取完整历史(`fetch-depth: 0`)才能和这些指纹比对:
- ```yaml
- 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` 后重新生成的页面也会标出这些元素,并在要点旁列出这些改动。
- 失败后,让技能刷新这张图:
- ```text
- $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、配置、测试和已接受需求中的可追溯证据。
- ## 开发与参与
- ```bash
- 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。反馈问题时,请附最小脱敏图数据、客户端和浏览器版本,以及复现步骤。
- 参考文档(英文):[证据来源](skills/q-flow/references/evidence-sources.md) · [图数据格式](skills/q-flow/references/graph-schema.md) · [需求引导](skills/q-flow/references/guided-intake.md) · [Viewer 开发与验收](skills/q-flow/references/viewer-development.md) · [图形表达约定](skills/q-flow/references/visual-contract.md)
- ## 许可证与归属
- [MIT](LICENSE) · [第三方声明](THIRD_PARTY_NOTICES.md)
- QGraphFlow 是采用 MIT 许可证的独立项目。本文场景为概念示例,不代表任何真实公司的生产架构。
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.