QGraphFlow v0.0.6

修复与更新

命令行与分发

• 新增 qgraphflow 命令（validate / generate），要求 Node.js 22 及以上。npmjs 包 qgraphflow 就是本 Release 的 tgz 原样发布，可直接 npx -y qgraphflow validate …，无需登录任何 registry。
• generate-viewer 每次生成都为每个视图写一个浅色 SVG：单张图写 diagram.svg，集合写 diagram-<n>-<diagramType>.svg；在 Chromium 里原地保存时同步重写 SVG。
• 一行安装 npx skills add supermax92/qgraphflow，已用 skills 1.7.0 实测 Claude Code、Codex、Cursor、Qoder。
• GitHub Pages 在线演示：https://supermax92.github.io/qgraphflow/ （电商九视图与 agent-desk 示例，en / zh-CN）。
• CI 增加 Node 24；发布工作流新增 npmjs 任务（可信发布、附 provenance、仓库不存令牌，已在 npmjs 上的版本只核对不重发）。

活文档

• 带 --repo-root 校验时，检查 symbol 是否仍在记录的 lineStart–lineEnd 之内，不在就报错并给出候选行号；--fix --repo-root 在检查词唯一时自动重新定位。
• SKILL.md 增加"刷新已有图"的流程；README 给出 CI 配置片段，失败时指出是哪张图。

图记法

• 状态图按 UML 记法重画：entry / do / exit 动作格、自转移弧线、开放箭头；转移文字按触发、[守卫]、/ 效果 分层着色；状态卡片按生命周期语义着色，图例按实际出现的色调列项。
• 时序图：带 replyTo 的同步调用要求被调方有激活条，--fix 自动补上；消息缺 route.messageY 时查看器不再白屏。
• 标题、连线文字、分支词按 meta.locale 的语言写；连线标签换行不再拆开标识符。
• 架构图、部署图的卡片装饰图形不再压住角标和文字。

布局

• 连线交叉的有界局部搜索（端口、分支侧、折线通道互换，只在得分更好时保留）。
• 精修只按评估次数结束，超时改为单次 ELK 求解的防挂死保险：慢机器或满载时同一张图排出同样的布局。

示例与文档

• 电商示例（7 种语言）的时序图与状态图改用新记法。
• 七种语言 README 第一屏：在线演示链接、一行安装、差异说明、"让图和代码保持同步"一节；需要 PAT 的 GitHub npm 安装说明换成 npmjs；README 致谢 Cocoon-AI/architecture-diagram-generator。
• 精简 16 项：移除 motion 依赖与 effects.css、去掉 54px 消息间距兜底、删除不再被引用的夹具等。

不兼容变化

• 输出目录除 index.html、graph.json 外还会有 SVG 文件；目录里已有同名 SVG 时需要 --force 才能覆盖。
• 带 --repo-root 时，symbol 不是源码原文的旧图会校验失败：运行 --fix、手动改锚点，或删掉可选的 symbol。
• 带 replyTo 的同步调用缺被调方激活条时命令行校验失败，运行 --fix 自动补上；没有 replyTo 的旧图不受影响。

安装包

下载 qgraphflow-0.0.6.zip，解压并保留隐藏文件；按 README 注册到客户端。.tgz 提供相同运行时内容，SHA256SUMS 用于校验。GitHub 自动生成的 Source code 压缩包不是精简插件安装包。

运行包 78 个文件（tgz 840,981 B，zip 894,960 B）。npmjs 包 qgraphflow@0.0.6 与 GitHub Packages 包 @supermax92/qgraphflow@0.0.6 均由本页附件发布；Qoder Desktop 商城条目需另行更新。

验收与保留项

• Node 自动化测试 209/209 通过（本机 Node 22）；PR #4 与 main 上的 CI（Node 22 / 24）及 Pages 构建通过，在线演示已部署。
• claude plugin validate . 通过。
• ZIP/TGZ 内容一致（78 个文件），包内两份商城文件的 name 均为 supermax92，六处版本号均为 0.0.6；安装包从 v0.0.6 的干净导出构建，tgz 与合并前在 3d99cd7 上的演练构建逐字节一致。
• 从解压后的运行包：qgraphflow validate 通过；电商示例生成 9 个视图与 9 个 SVG。
• 保留 showcase-v1、showcase-v2、v0.0.5 的附件、tag 及 npm 旧版本。

本次验收不代表全部客户端或官方插件市场已经完成验收。

提交

• 73564d3 ci: npm 发布工作流的校验改为 --input-only，九类图输入改用仓库示例
• dcf2aad Merge pull request #2 from supermax92/refactor/q-flow/20260917-skill-guidance
• 569e2a1 docs: README add（Cocoon-AI/architecture-diagram-generator）
• 8ce6f6c Merge pull request #3 from supermax92/docs/readme/20260928-inspiration-credit
• 518d8ac feat: 命令行导出 SVG、源码锚点漂移检测与 npmjs/Pages 分发
• 434956a test: 兼容 npm 11 的 npm publish --json 输出格式
• 487e69e feat: 状态图按 UML 记法重画，并收尾时序激活条、连线文字语言与布局交叉精修
• 83feba2 fix: 修复审查发现的激活条、自转移弧线与布局打分问题
• 9f40986 feat: 状态图按生命周期语义着色，连线标签换行不再拆开标识符
• e3f2f9b fix: 布局精修与超时不再依赖时钟
• abe8fa9 feat(showcase): 电商示例的时序图改用新记法
• 54501d3 fix: 多段连线标签也按触发/守卫/效果着色
• 85abf49 feat(showcase): 电商示例的状态图展示 entry 动作格与自转移
• 9110869 merge: 合并状态图语义着色与连线标签换行（feat/q-flow/20261004-state-tone-label-wrap）
• 9cf69d8 fix: 时序图消息缺 route.messageY 时不再白屏
• 3d99cd7 chore: 发布 v0.0.6，版本号与安装包引用同步更新
• 4a551da Merge pull request #4 from supermax92/feat/q-flow/20260928-svg-living-docs-distribution

完整差异

QGraphFlow v0.0.5

修复与更新

q-flow 技能

• 离线自动布局：生成期 ELK worker（elkjs 0.11.0，EPL-2.0，许可证随包附带），统一语义/几何质量校验；接受无坐标输入；分层结果宽高比超出 1/1.6–1.6 带时按层序折叠为列或行。
• 时序图：调用配对与执行条、嵌套 alt/opt/loop/par 片段；参与者按消息首次到达排序；C 编号按消息顺序。
• 卡片：去掉装饰件，描边表角色、芯片与微底色表模块，八个 Radix 身份 scale。
• 作者指引：只读 graph-common.md 与 types/.md；validate-graph --fix 先修后判（时序 order 重编、operand id、唯一 replyTo）；脚本成功只打印一行回执；浏览器验收改为按需；新增构图审查警告。
• 查看器：界面源语言改为英文（i18n 新增 zh-CN 目录，既有页面显示不变）；原地保存当前页面与同级 graph.json；?automation=1 暴露视口句柄供录制与 QA。

示例与文档

• 新增 examples/showcase/agent-desk（虚构业务、真实代码）与 7 个 locale 的架构 / 时序 / ER 图；scripts/showcase-record.mjs 录制 README 动图，托管为 Release showcase-v2（35 个 GIF）。
• 七种语言 README：顶部 hero 动图，四条功能条目下各一张 GIF；插件商城所在产品更正为 Qoder Desktop；免责声明改为"本文场景为概念示例"。
• 删除过时的本地化参考副本 docs/references//，英文参考为唯一来源；删除 showcase-v1 媒体清单与打包脚本。

安装包

下载 qgraphflow-0.0.5.zip，解压并保留隐藏文件；按 README 注册到客户端。.tgz 提供相同运行时内容，SHA256SUMS 用于校验。安装包新增布局 worker，比 0.0.4 大约 380 KB。GitHub 自动生成的 Source code 压缩包不是精简插件安装包。

GitHub npm 版本 @supermax92/qgraphflow@0.0.5 需另行触发 Publish GitHub npm 工作流发布；Qoder Desktop 商城条目需另行更新。

验收与保留项

• Node 自动化测试：157/157 通过，含独立安装包验证；PR #1 与 main 的 CI 通过。
• claude plugin validate . 通过；示例 --input-only 校验与生成通过；从解压后的运行包生成示例页通过。
• ZIP/TGZ 内容一致（75 个文件），包内两份商城文件的 name 均为 supermax92，六处版本号均为 0.0.5；Viewer 按提交重建后与包内 viewer-dist 逐字节一致。
• 保留 showcase-v1、showcase-v2、v0.0.4 的附件、tag 及 npm 旧版本。

本次验收不代表全部客户端或官方插件市场已经完成验收。

提交

• 89a0496 feat(q-flow): 完善九类图语义布局与时序交互
• b87992d docs: 补充 Qoder IDE 插件商城安装说明
• 7e54c1e refactor(q-flow): 收紧布局间距与配色规则，完善时序执行指引
• c79612c feat(q-flow): 时序片段与参与者顺序修正，卡片去装饰，布局宽高比折叠与原地保存
• 5991da7 feat(q-flow): 按类型渐进加载参考、validate --fix 与一行回执、构图审查警告、界面源语言改为英文
• e65157b feat(showcase): agent-desk 示例与七语言 README 动图录制，插件商城客户端改为 Qoder Desktop
• 5dd7507 chore: 发布 v0.0.5，版本号与安装包引用同步更新
• bd7574f ci: order-flow 示例改为 --input-only 校验，几何由生成步骤覆盖
• bce8955 Merge pull request #1

完整差异

QGraphFlow showcase-v2 — agent-desk README recordings

README recordings for the seven READMEs (en, zh-CN, ja, de, es, pt, ru), recorded on 2026-09-20 from the source-built Viewer on the examples/showcase/agent-desk example (fictional business, real code) at commit e65157b with scripts/showcase-record.mjs.

Five clips per locale, named agent-desk.<locale>.<clip>.gif, 1200×675, 12 fps, light theme:

clip	length	content
hero	4.5 s	architecture → sequence → ER, 1.5 s each
explore	6.5 s	search, jump to the node, zoom out to upstream / downstream, pan
verify	6.5 s	quick-look card with file:line, details with symbol and evidence facts, an edge marked as inference
edit	8.5 s	unlock, rename from the card, drag with edges following, reset
share	6.5 s	open the page, Export PNG, the exported file itself

These assets are referenced by the READMEs and are intentionally kept out of Git history and the plugin package.

SHA-256:

b28ce93205871c5bf2b6f36440d3d27c7183bf5d877080d41ba428cffdfdf7d4  agent-desk.de.edit.gif
95f48e4601846ac2fb880466b5e7212ef15cb1f96416c61b29159fa11a0aa4db  agent-desk.de.explore.gif
efb6d48be8f92f68c62ccde0e2da48efdd9edec97d26edf69d68498f3e5ef4d0  agent-desk.de.hero.gif
a368dbf8bcf175d17ae4ad87e92e8e52dd59bcc4b91e18904eb2672d8dfe3ee4  agent-desk.de.share.gif
f4b6d5a852d21b3ae5398cee1eec1e5534273ead797d6efcaae567dfd6556136  agent-desk.de.verify.gif
c07edb64b964f2d933e26a691c9f8f71fc6e549f9624f1e4f7c700781b91e95b  agent-desk.en.edit.gif
bf39b7144b2edcc64c3b88fbcbe3963db832f8ddd475654286108e7def3b6a3e  agent-desk.en.explore.gif
1d92c808c261446b6435a71663c0e2680b05689c61be914c23aeb71d6e67d6e8  agent-desk.en.hero.gif
f79a62c287e23c1d4fdb3c13c51e67826240ada5dd74e0399aec56f4a6625f26  agent-desk.en.share.gif
2a93f2fc8203495ce040875d71595e3909abb0a2a65dcd984de0ccf664ce4f73  agent-desk.en.verify.gif
2c7ae624dc933da704d9feb66fd7d1ec81f8ad0cd5e648104d7693237c763bd4  agent-desk.es.edit.gif
e35f0838cc32e135361489859bba00c8266ccdf91b6d0a21bc2eb3207cf32f7b  agent-desk.es.explore.gif
970cf3c0008f88a010afba3fef97d97618ed07eece3afca9baf8e5513390d562  agent-desk.es.hero.gif
41c601024e8a0d63d9c4239d75618309b54432c707ca99b32c1eda50a96cf272  agent-desk.es.share.gif
f44336fd3a56f95135a9c395e35584fc02af64e929cdff474854e7380537c4d0  agent-desk.es.verify.gif
0903c6c3256485ac832f2215fb0ab523b9dbec65a0dcacf0066b81f3df74f813  agent-desk.ja.edit.gif
4540426402fb9176eda16360c65040e09a508f51418d903bce6f5daa868fba8e  agent-desk.ja.explore.gif
cd5f826a762f88d57398743402b2cfda97bc7bd3ab6538beacceed4c5c1f2961  agent-desk.ja.hero.gif
d056a4e288fbf2e3735da17e50e918dcecfc1f021ea52b82cd4b30a1602d1f04  agent-desk.ja.share.gif
20fac51e793dd37df3f3e10b1ec01d9d2dc86957755dbb3b405876b511542834  agent-desk.ja.verify.gif
6b7426e5b9e520c5e9c16044d383d981c2231524a2594cf22fd165a54f8f302a  agent-desk.pt.edit.gif
380945cf37555b2384a9d57ca281a7da11df39cfa21522ca4271d420a473ebd2  agent-desk.pt.explore.gif
8acea13f7a678ae5d3e712422c6c823c3389f44587aa1a8ef486a91b5ce99190  agent-desk.pt.hero.gif
b4f029caf45f9014d39168c4ad4d4dab0f3e19060032c34fbda5c3390c2e606e  agent-desk.pt.share.gif
54bb2edf1c2dc70ae3244a34cde3f12093501f9bdce460ec7ff553bd2eb18bce  agent-desk.pt.verify.gif
0d9da86b472d0c9dd954640e7b86a6690d720ae6a2c36c74a28188ea01649578  agent-desk.ru.edit.gif
f72a94d39c10139a34dde764820437a33e37bbbdd7cbcab3e712d5a2d254fb9e  agent-desk.ru.explore.gif
1d0e45c5555700b4886fc0fd910ffeb2b513802b900fa84390684185ce7c5d57  agent-desk.ru.hero.gif
15d59b10300a97114abaefd6f96e7becdd1f8a915664f395ec0d26c94af2b491  agent-desk.ru.share.gif
1ee0fd7a13553f03ef5eb611cdd534a60e8b602ccd1fa1bf552c0c0cbc5b6baf  agent-desk.ru.verify.gif
d04c82831f42a75ce12aa0af6a1c8458c776e43f6238a0bced514950470d0db4  agent-desk.zh-CN.edit.gif
078c7d092c9a97ef06790701170f5470c234900ff8f5bfce449238b9b60dc9e9  agent-desk.zh-CN.explore.gif
183d2a312f3701e77e9a9e8fc70c98d6c6bc0ceba13e4737dac6aa7d98bd3eeb  agent-desk.zh-CN.hero.gif
fdfc7878b80a936ebda7dc89c29ee87adbd728913b6c0a3ce9805acff2453558  agent-desk.zh-CN.share.gif
b431f987f81f5e8de518b237eb00fa1f9820a63922c1cc67a23c6a2ce02dd56f  agent-desk.zh-CN.verify.gif

QGraphFlow v0.0.4

修复与更新

• 插件商城改名为 supermax92：.claude-plugin/marketplace.json 的 name 从 qgraphflow-local 改为 supermax92，运行包内的 Codex 商城同步；安装命令变为 qgraphflow@supermax92。
• Claude Code 新增 GitHub 直装方式：/plugin marketplace add supermax92/qgraphflow 后 /plugin install qgraphflow@supermax92，本地运行包安装退为备选；调用命令写为 /q-flow，完整名 /qgraphflow:q-flow 仍可用。
• 七种语言 README 与安装指南同步更新，安装指南开头区分 Claude Code 与其他客户端的安装路径。
• v0.0.3 的运行包仍带旧商城名 qgraphflow-local，与更新后的文档不一致；本版本运行包修正此问题。

安装包

下载 qgraphflow-0.0.4.zip，解压并保留隐藏文件；按 README 注册到客户端。.tgz 提供相同运行时内容，SHA256SUMS 用于校验。GitHub 自动生成的 Source code 压缩包不是精简插件安装包。

GitHub npm 版本 @supermax92/qgraphflow@0.0.4 需另行触发 Publish GitHub npm 工作流发布。npm 下载需要 GitHub Packages 认证，下载后仍需在客户端注册插件。

验收与保留项

• Node 自动化测试：91/91 通过，含独立安装包验证。
• claude plugin validate . 通过；示例图校验与生成（同 CI 步骤）通过。
• ZIP/TGZ 内容一致，包内两份商城文件的 name 均为 supermax92。
• Viewer 与图形渲染无改动，未重新录制媒体；保留所有旧 Release、附件、npm 版本及旧标签。

本次验收不代表全部客户端或官方插件市场已经完成验收。

提交

• 78411b8 feat: 商城改名 supermax92 并补充 Claude Code 的 GitHub 安装法
• 3010343 chore: 发布 v0.0.4，版本号与安装包引用同步更新

完整差异

QGraphFlow v0.0.3

修复与更新

• 修复时序图定位、侧栏避让和快捷卡片的阅读几何；使用可见参与者头部定位，同时保留完整生命线和导出范围。
• 改善时序图请求/返回线与流动效果的辨识，覆盖窄屏、全屏、减少动态效果和离线文件打开的回归检查。
• 更新七种语言 README 的安装说明，统一 ZIP、GitHub npm 和客户端安装入口。

安装包

下载 qgraphflow-0.0.3.zip，解压并保留隐藏文件；按 README 注册到客户端。.tgz 提供相同运行时内容，SHA256SUMS 用于校验。GitHub 自动生成的 Source code 压缩包不是精简插件安装包。

GitHub npm 版本：@supermax92/qgraphflow@0.0.3，通过独立的 Publish GitHub npm 工作流发布。npm 下载需要 GitHub Packages 认证，下载后仍需在客户端注册插件。

验收与保留项

• Node 自动化测试：91/91 通过，含独立安装包及 npm 发布命令 dry-run 验证。
• Chrome 时序图复验：6/6 场景、10/10 专项检查通过，6 个导出文件，零失败。200% 检查采用等效 CSS 视口和 DPR 2。
• ZIP/TGZ 内容一致，解压后的生成器可以独立生成时序图和九类图集合。
• 保留所有旧 Release、附件、npm 版本及旧标签；历史 GIF/PNG 和原媒体溯源不变，未重新录制。

本次验收不代表全部客户端或官方插件市场已经完成验收。

提交

• 8853bdb 修复时序图阅读几何与回归验收
• 8d47848 更新多语言安装说明

完整差异

QGraphFlow v0.0.2

QGraphFlow v0.0.2

Evidence-grounded, editable software diagrams in a self-contained offline HTML Viewer.

本次更新 / Highlights

• 完善九类图的形状语义、模块配色、连线边界与箭头方向，保留连线流动和完整文字缩放。支持架构图、流程图、时序图、ER 图、部署图、类图、状态图、用例图和数据流图。
• 支持节点文字编辑、拖动元素、按当前图重置，以及保存多视图 Graph JSON；时序图参与者保持水平拖动约束。
• 提供节点快速详情卡、源码证据侧栏、上下游关系高亮、明暗主题、全屏画布及 SVG / PNG 导出。
• 更新七种语言的 README、安装指南与参考文档：English、中文、Русский、Português、日本語、Deutsch、Español。
• 分离完整开发源码、精简运行包与演示媒体；打包时生成可分发的 Codex 本地安装源，不复制开发者的私有配置。保留 MIT 与第三方许可声明。

Nine diagram types now share richer semantic shapes, module colors, connected edge routing and editable text/positions. The offline Viewer includes quick-look cards, evidence inspection, light/dark themes, animated connections, per-diagram reset, Graph JSON saving and SVG/PNG export.

下载与安装 / Downloads

• 推荐：qgraphflow-0.0.2.zip — 精简插件运行包，包含预构建 Viewer、共享 skill、四个客户端入口、指南与许可声明。ZIP 解压后直接是插件根目录。
• qgraphflow-0.0.2.tgz — 相同运行内容，解压后位于 package/ 目录。
• SHA256SUMS — 两个运行包的 SHA-256 校验值。
• GitHub 自动提供的 Source code (zip / tar.gz) 是完整开发源码快照，不是上面两个精简安装包。

将 ZIP 解压到新的空目录，例如 dist/runtime，再按中文安装指南的第 2 节或 English installation guide选择客户端。已下载运行包时，可跳过指南中的源码克隆与打包步骤。请勿将新旧安装目录混合覆盖。生成图形需要 Node.js 22；下载的预构建运行包不需要安装 Viewer 开发依赖。

Download ZIP for the ready-to-install runtime, extract into a fresh directory such as dist/runtime, then follow the client-specific installation section. Skip the source clone/build steps when using these runtime assets. TGZ contains the same files under package/. Node.js 22 is required for graph generation.

演示与边界 / Showcase and scope

电商演示 GIF / PNG 继续独立托管于 showcase-v1，不进入运行包；所有旧 Kafka 附件保持不变。演示媒体需要联网查看，生成的 HTML 可离线打开。电商证据操作演示中的代码路径为明确标注的虚构示例。

包含 Codex、Claude Code、Qoder、Cursor 的本地安装入口；本次软件 Release 不代表已通过四个客户端的公开插件市场审核，也不宣称所有客户端版本均已验收。

构建与验证 / Build provenance

• Source commit: 2756fc40bd84e91cce7f8a0b9b0bc3302f7aeae6.
• GitHub CI passed; all 88 local automated tests passed.
• Viewer rebuilt from a clean export of that commit; its SHA-256 matches the committed Viewer: c27ab9c3f1cd61f37f187fb66d3f4161cab4b2165071443c3d18863b699be756.
• The clean-source package tests passed; the ZIP/TGZ payloads and their standalone graph generation were verified before publication.

Full changelog: v0.0.1...v0.0.2

QGraphFlow v0.0.1

QGraphFlow v0.0.1

首个开源版本：从源码、数据库结构、配置或需求生成可追溯的交互式软件图。

• 支持架构、流程、时序、ER、部署、类、状态、用例和数据流九类图。
• 交付离线 index.html 与 graph.json；页面提供搜索、详情、主题切换、逐步演示、布局调整及 SVG/PNG 导出。
• 提供 Codex、Claude Code、Qoder 和 Cursor 的插件清单及安装说明，共用一份 q-flow 技能。
• 普通图生成使用预构建 Viewer，无需安装前端依赖；CodeGraph 是可选取证工具。
• 采用 MIT 许可证，并随包及独立 HTML 保留项目和第三方声明。

下载与开始

下载 qgraphflow-0.0.1.zip，解压后按 README 的“先运行一个示例”执行两个 Node.js 命令即可查看交互图。Node.js 验证基线为 22。

另提供 qgraphflow-0.0.1.tgz（解压后进入 package/）及 SHA256SUMS.txt。

验证与边界

本地源码和干净副本均通过 59 项自动测试；九类图在三种尺寸、深浅主题下通过 54 项渲染基础检查。订单示例已验证实际 SVG/PNG 下载、搜索、详情、主题、逐步演示及 Chrome 原生全屏。

各客户端完整的“模型取证到绘图”端到端链路尚未全部验收，具体状态见 docs/clients.md。本次未上架 npm 或各客户端官方插件市场。图数据中的推断仍需人工复核；播放不代表程序真实执行轨迹。

QGraphFlow showcase — E-commerce + legacy Kafka

Documentation media only; this is not a software installer release.

E-commerce showcase

98 media files: 5 GIFs + 9 PNGs × 7 languages — English, 简体中文, Русский, Português, 日本語, Deutsch and Español.

• The overview GIF contains architecture, flowchart and sequence views: 0.8 seconds per view, 2.4 seconds per loop, with animated edges.
• Four operation GIFs demonstrate exploration, evidence inspection, editing/reset, and offline sharing/export.
• Nine PNGs show the complete static diagrams.
• The e-commerce scenario is conceptual. Any demonstration code paths, line numbers and symbols are explicitly fictional, not evidence from an actual commerce repository.

The new assets are named ecommerce.<locale>.<view-or-capability>.gif/png. showcase-media.json records their source-graph and Viewer hashes; SHA256SUMS verifies the e-commerce attachments and receipt.

Legacy Kafka showcase

All 63 original Kafka GIFs are retained unchanged so older README links continue to work. Their names remain kafka.<locale>.<diagram>.gif.

Distribution boundary

Media attachments are excluded from Git source history and plugin installation packages. The showcase-v1 tag intentionally remains on its original source baseline; it does not identify the software version represented by newer attachments. Use the media receipt for exact Viewer and graph hashes. Source changes are published separately on main, and software installers use their own software Release.