Skip to content

feat: 构图交给模型、代码改动标到图上、首屏可读性提升,架构图只留组件关系 - #27

Merged
supermax92 merged 16 commits into
mainfrom
feat/20261108-compose-views
Nov 8, 2026
Merged

supermax92 merged 16 commits into
mainfrom
feat/20261108-compose-views

Conversation

@supermax92

Copy link
Copy Markdown
Owner

功能:

  • 构图交给模型:同一合集可以放同类型的多个视图;关系视图可以把公共依赖折叠成卡片标签,并用 layout.rank 分栏。
  • 代码改动标到图上:validate 能区分"行号只是移动"和"语义真的变了",--fix 会生成漂移待办;generate --compare 会在图上标出新增、改动和删除。
  • 首屏可读性:缩小时组件图和部署图的卡片只突出名字,时序图只有在阅读倍率下能整图放下时才整图打开。
  • 只留组件关系:架构图删除平台能力、工程分层两种总览视图,九类图各一个视图,旧图用 validate --fix 迁移。
  • README 与在线演示:README 改为中文主文件,英文在 README.en.md,动图换成 Release showcase-v3;在线演示新增中英"本次更新"对比页。

新增 6 个文件

  • skills/q-flow/scripts/(3):source-drift.mjs(基线、行号映射、漂移判定、--changes 报告)及 source-drift.test.mjs(12 个用例)、graph-diff.test.mjs(4 个用例)。
  • skills/q-flow/assets/viewer/src/(2):graph-diff.js(按视图比较两版图,忽略几何和行号)、source-changes.js(读出 meta.sourceDrift 供查看器显示)。
  • scripts/(1):showcase-changes.mjs,生成"上一版"组件关系图,README 动图和 Pages 对比页共用。

修改 76 个文件

查看器(33 个):

  • DiagramCanvas.jsx:缩小时卡片切换为只显示名字;节点和连线标签带新增、改动、漂移标记;去掉总览分区节点。
  • ViewerShell.jsx:右侧卡片在"要点"后列出源码变更和"本次更新"(新增、改动、删除),列表项可点;去掉总览文字编辑区。
  • presentation-graph.js:公共依赖折叠,连线改画成源卡片上的标签,模型里的连线保留。
  • diagrams/card.js、text-layout.js:卡片新增标签行(badges 和折叠依赖),新增缩小时用的 summaryCard。
  • session-graph.js、main.jsx:对比结果放进独立的 #graph-compare 元素,页内保存后仍保留;量卡片时算上折叠标签。
  • layout-templates.js:自转移的节点留出侧边高度和列间距;删除两个总览模板。
  • edge-routing.js:跨宽间隙的时序消息标签可以用更宽的行,减少换行。
  • reading-area.js、features/useGraphLayout.js:时序图的整图阈值改为阅读倍率;拖动不越过画布原点;去掉总览重排、键盘移动和拖动分支。
  • diagrams/sequence.js:参与者去掉重复的 <title>。
  • graph-validation.js:总览字段报错,并提示运行 validate --fix;新增 badges 校验;sharedDependencies 只允许用在架构图。
  • view-identity.js:视图类型只剩组件关系加其余 8 类。
  • i18n-messages.json:新增源码变更和本次更新的文案,删除只给总览用的文案。
  • styles.css:变更标记、卡片标签和提示条的样式,删除 .overview-section*。
  • TextEditor.jsx、layout-browser-worker.js、visual-style.js:去掉总览相关参数、分支和配色。
  • 其余 13 个文件只是删除总览分支:diagrams/architecture.js、diagrams/registry.js、export-svg.js、features/download.js、features/usePresentation.js、features/useSelection.js、layout-measure.js、layout-quality.js、layout-refinement.js、node-svg.js、orthogonal-routing.js、route-clearance.js、search.js。
  • assets/viewer-dist/index.html:用上述源码重新构建。

脚本(5 个):

  • validate-graph.mjs:漂移检查、--fix 生成待办和新基线、--changes 生成 PR 报告;新增 migrateOverviews(),把总览图转成组件关系图,迁移后只按输入校验,并提示用 --layout auto 重排。
  • generate-viewer.mjs:新增 --compare <文件|git 版本>;生成时标出受漂移影响的元素。
  • compile-layout.mjs:preserve 模式失败时局部修补新连线和拥挤标签;去掉总览排版分支。
  • compile-sequence.mjs:参与者间距从质量门禁下限起步;已排好的视图保持列顺序。
  • browser-interactions.mjs:修正 44 项长期失败里属于测试本身的问题;删除总览专用检查。

测试(15 个):

  • composition-review.test.mjs、sequence-execution.test.mjs、state-notation.test.mjs、generate-viewer.test.mjs:覆盖多视图、rank 分栏、折叠依赖、preserve 修补、宽间隙标签、自转移和时序整图阈值。
  • validate-fix.test.mjs:新增总览迁移用例。
  • compact-architecture、joint-layout、routing-clearance、layout-cancellation(.test.mjs):删除总览用例。
  • tests/ 下 6 个文件:改为九个视图、中英两份 README 和安装指南、Pages 对比页。

技能文档(9 个):

  • SKILL.md、references/graph-common.md、references/types/sequence.md:要求的图按主题理解,超过 12 节点、4 栏、20 条消息或 4 屏时拆成同类型视图;要点也是论断;模板数改为 9。
  • references/graph-schema.md:漂移基线、sourceDrift、--compare,以及总览视图的移除与迁移说明。
  • references/types/architecture.md:改写为单一组件关系视图,补充卡片标签、sharedDependencies 和 rank 的说明。
  • references/guided-intake.md:删除两种总览视图的选图问题。
  • layout-routing.md、viewer-development.md、visual-contract.md(均在 references/ 下):九个视图、矩阵 54 个场景,删除总览引用。

示例、文档与发布(14 个):

  • examples/jeepay/collection.graph.json、source.json、README.md,以及 scripts/refresh-jeepay-fixtures.mjs:删除两个总览视图,从 11 个变为 9 个。
  • README.md:内容改为原中文版,链接改为根目录相对路径;首屏放 hero 动图,"差异在哪"下面放 changes 动图;删除旧的时序逐步绘制动图。
  • docs/clients.md、docs/clients.zh-CN.md:语言切换只留中英,并修正返回链接。
  • package.json:发布清单加入 source-drift.mjs、graph-diff.js、README.en.md,去掉总览文件和 docs/readme/。
  • .github/workflows/pages.yml、docs/pages/index.html:生成中英"本次更新"对比页(jeepay/changes/{zh-CN,en}),并在首页加入口。
  • .github/workflows/publish-github-npm.yml:输出目录名从 output/eleven 改为 output/jeepay。
  • .codex-plugin/plugin.json、skills/q-flow/agents/openai.yaml:描述从十一类改为九类。
  • docs/distribution.md:九个视图、对比页说明,并把 showcase-v3 定为当前的 README 动图。

删除 15 个文件

  • skills/q-flow/assets/viewer/src/architecture-overview.js、architecture-overview-theme.js:总览排版和配色,由组件关系视图取代;旧图用 validate --fix 迁移。
  • examples/jeepay/capabilities.graph.json、engineering.graph.json:两种总览示例。
  • docs/readme/(6):README 的中文版已搬到根目录 README.md,另外 5 种语言删除。
  • docs/clients.{de,es,ja,pt,ru}.md(5):只有已删除的 README 链接到它们,只保留中英两份。

移动或重命名 1 个文件

  • scripts/record-showcase-hero.mjs → scripts/record-showcase.mjs:改为按 --clip hero|changes --locale zh-CN|en 录制,使用真实光标,结尾对齐连线流动相位,保证首尾帧一致。

复制 1 个文件

  • README.md → README.en.md:原英文 README,改为九类图、showcase-v3 动图,并加中英切换。

验证:

  • Node 全量测试 204 项全部通过(在本分支 HEAD 上运行)。
  • 浏览器矩阵:54/54 个场景通过,附加检查 147/148。唯一失败的 jeepay-deployment-text-bounds 是之前就有的部署图长标签路由问题,与本 PR 无关。
  • 用删除前的两张总览示例跑迁移:--fix 后用 --layout auto 生成,输出校验通过。
  • 按 Pages 流程在本地生成九类图和中英对比页,源码出处 21/21 核对通过。
  • showcase-v3 的 8 个文件下载后,大小和 SHA-256 都与本地一致。

注意:

  • 不兼容改动:带 meta.architectureView: capabilities|engineering、layout.sections、layout.overviewConnections 或节点 overviewText 的图现在会校验失败。下游仓库已生成的总览图要先运行 validate --fix,再用 generate --layout auto 重新生成。
  • npm 包和仓库首页的 README 变为中文,英文在 README.en.md。
  • README 引用的动图已经在 Release showcase-v3 上;在线演示的对比页要等合并到 main 后由 Pages 部署。

- 生成与 --fix 记录 meta.sourceFiles(逐文件 git blob 基线)
- 只移动行号的出处自动对齐;改写、删调用留死方法、未覆盖的新代码、
  消失的名字报为 Source drift,附前后代码与受影响元素
- --fix 写入 meta.sourceDrift 待办,未清空前校验与生成失败
- 基线缺失时提示 fetch-depth: 0 并退回原检查;旧图行为不变
- 更新 SKILL.md 刷新流程、graph-schema 说明与 7 份 README 的 CI 片段
- 合集里任意类型可重复,重复视图须写唯一 meta.viewId,时序图可在同一合集按阶段拆分
- 关系与部署卡片在源码行下显示 badges;只有 badges 不再变成概览卡
- layout.sharedDependencies:指向共享依赖的边不画线,改为调用方卡片上的"→ 名称"标签;
  边、出处与漂移检查保留,详情栏可点开;Node 与浏览器排版先排展示图再还原
- 自转移标签计入模板列距且不受 240 上限;带长自转移的状态按标签加高
- 文档:rank 配合 direction right 可做阅读分栏;技能说明提示拆同类型视图或折叠公共依赖
- 新增 5 个测试;重建 viewer-dist;界面新增"公共依赖"文案(8 种语言)
- 删除平台能力、工程分层两种总览视图及其代码,图类型变为 9 种
- validate --fix 把旧总览图转成组件关系图:分区转归属分组、overviewText 并入 facts、说明分区并入要点,去掉几何后提示用 --layout auto 重排;不加 --fix 时校验报错并给出指引
- 示例、技能文档、浏览器矩阵与测试同步为九种视图,新增迁移测试
- README.md 改为中文,英文移到 README.en.md;删除其余 5 种语言的 README 和安装指南
…线演示加中英更新对比页

- 录制脚本改为 scripts/record-showcase.mjs:按分镜录 hero 与 changes 两段,真实光标与点击水波纹,结尾对齐虚线相位,首尾帧一致
- scripts/showcase-changes.mjs 生成"上一版"组件关系图,动图与 Pages 对比页共用
- Pages 工作流用 generate --compare 生成 jeepay/changes/{zh-CN,en} 并核对出处,首页加入口
- 中英 README:hero 放首屏,changes 放"差异在哪"下,删除旧的时序逐步绘制动图;文档改为 showcase-v3 为当前 README 动图
@supermax92
supermax92 merged commit 3a3baed into main Nov 8, 2026
4 checks passed
@supermax92
supermax92 deleted the feat/20261108-compose-views branch November 8, 2026 11:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant