跳转至

P1.U-subgraph-schema-extend · LinkSchema 加 subgraphDefs 字段 + LEGACY_LINK_FILE_MAP

Worker:ClaudeA · 前端 / 部门:前端 P1-xilink / 预计:0.5d / 优先级:P1 / 状态:dispatched

🔍 触发与解锁链

  • 触发:ADR-AIOS-08 v1.1 §2.5 议题④(2026-05-29 17:25 accepted)· 议题⑤ P1.U-dock-cleanup-9to4(ad1e458)zombie 后议题④ RightDock 风格冲突预备条件解除 · 用户 2026-05-30 14:55 拍板 start。
  • 解锁条件:本 fork zombie 后,P1.U-subgraph-canvas(2.5d 主体 · ClaudeA)解锁——canvas 任务直接消费本 fork 落地的 SubgraphDefinition / SubgraphPort / SubgraphNodeInstance 类型 + LinkSchema.subgraphDefs 字段。

任务定义(基于 ADR-AIOS-08 v1.1 §2.5 + §4.3 #9)

将 frontend_vue3/src/types/ 扩展子图序列化骨架 · 不实现 UI · 仅落地类型 + schema 兼容 + LEGACY_MAP + 序列化测试。

🆕 新建文件: - frontend_vue3/src/types/subgraph.ts · 含三个 interface(直接对照 ADR-08 §2.5): - SubgraphDefinition(id / name / nodes / edges / inputPorts / outputPorts / 元数据) - SubgraphPort(id / label / type / internalMapping) - SubgraphNodeInstance(id / subgraphDefId / position / paramOverrides)

📝 扩展文件: - frontend_vue3/src/types/link.ts(或 LinkSchema 真实定义文件 · 用 grep 锁定) - LinkSchema.nodes 类型从 ModuleNode[] → (ModuleNode | SubgraphNodeInstance)[] - LinkSchema 加 subgraphDefs: SubgraphDefinition[] 字段(default []) - frontend_vue3/src/stages/xilink/composables/useLinkLegacyMap.ts(或对应 LEGACY_LINK_FILE_MAP 文件) - 旧 .xilink 文件无 subgraphDefs 字段时自动注入 [] - 7 天宽限期(2026-06-06 起 strict mode · 仅 warning)

⚠️ 实施约束(ADR-08 §2.5 边界): - MVP 不实施画布 UI(留 P1.U-subgraph-canvas) - MVP 限定 2 层嵌套(本 fork 的 schema 不递归引用 SubgraphDefinition) - 子图序列化 = 链路 schema 一部分(无独立文件 · 走 .xilink) - ⭐ 全局红线 #1:响应式横竖屏(本 fork 仅 schema · 无 UI · 不需要,但 prompt 必含此说明) - ⭐ 全局红线 #2:design-token 主题切换(本 fork 仅 schema · 不需要)

完整 prompt(直接复制粘贴 worker 终端)

[U-thread]: P1.U-subgraph-schema-extend
[部门]: 前端 P1-xilink
[Worker CWD]: d:/work/25_claude/workspace/AlgoDepartment/04_development/
[Occupies]: P1.K-link-schema · P1.K-xilink-types
[优先级]: P1 · 0.5d
[隔离]: 🧵 file(同 worktree 同 branch · 文件正交并行)
[ADR]: docs/08-implementation/40-aios/ADR/ADR-AIOS-08-xilink-stage-ux.md(v1.1)
[业务行为契约引用]: ADR-08 §2.5 议题④ 子图决议 + §4.3 #9 实施约束(LinkSchema 向前兼容 + LEGACY_LINK_FILE_MAP 7 天宽限)
[参考文档]:
  - ADR-AIOS-08 v1.1 §2.5(子图决议:SubgraphDefinition / SubgraphPort / SubgraphNodeInstance 三 interface 对照)
  - ADR-AIOS-08 v1.1 §2.6 边界铁律 #6(子图必须可序列化 · 无独立文件)
  - ADR-AIOS-05(7 后缀 + LEGACY_*_MAP 三件套兼容惯例)
  - 已就位代码:
    · frontend_vue3/src/types/link.ts(LinkSchema 真实路径 · grep 锁定)
    · frontend_vue3/src/stages/xilink/composables/(LEGACY_*_MAP 现有惯例)
  - 不动 ADR-08 议题①/②/③/⑤ 已 zombie 或 dispatched 的 P1.UA8-* 三 fork 文件
  - 不动 ADR-11 v1.3 fork 1-v3(ClaudeC)+ fork 1b-v2(ClaudeB)文件

【背景】
ADR-08 议题④ 子图(subgraph)是右 dock 5 议题中的中量级议题(2.5d 主体 + 0.5d schema = 3.0d 合计)。本 fork 是 schema 前置任务,必须先于 canvas 落地,让 canvas 任务直接 import 类型 + 消费 LinkSchema.subgraphDefs 字段。

ADR-08 §2.5 已给出三 interface 完整字段定义,本 fork 仅做"类型落地 + schema 扩展 + LEGACY_MAP + 序列化测试",不实施画布 UI、不实施嵌套渲染、不实施 cyclic 检查(全部留 canvas 任务)。

【执行步骤】(5 步 · 0.5d)

Step 1 · 真值核查(0.05d)
  - grep "interface LinkSchema|type LinkSchema|export.*LinkSchema" frontend_vue3/src/ → 锁定 LinkSchema 真实定义文件
  - grep "LEGACY_.*MAP|legacyLinkFileMap|legacyXilinkMap" frontend_vue3/src/ → 锁定 LEGACY_MAP 现有惯例文件
  - grep "ModuleNode\b" frontend_vue3/src/types/ → 确认 ModuleNode 现有字段(本 fork 不动 ModuleNode)
  - 输出真值清单到 commit message body(eg. "LinkSchema 在 src/types/link.ts L12 / LEGACY_MAP 在 src/stages/xilink/composables/useLinkLegacyMap.ts L8")

Step 2 · 新建 types/subgraph.ts(0.15d · 本 fork 主体之一)
  - 路径:frontend_vue3/src/types/subgraph.ts
  - 严格按 ADR-08 §2.5 抄三 interface · 字段不增不减:
    · SubgraphDefinition: id / name / description? / nodes: ModuleNode[] / edges: Edge[] / inputPorts: SubgraphPort[] / outputPorts: SubgraphPort[] / createdAt / modifiedAt / presetParams?
    · SubgraphPort: id / label / type: PortType / internalMapping: { moduleId / portId }
    · SubgraphNodeInstance: id / subgraphDefId / position: { x / y } / paramOverrides?
  - import { ModuleNode, Edge, PortType } from './link'(或对应 ModuleNode 真实路径 · Step 1 已锁定)
  - 加 JSDoc 注释 · 引用 ADR-08 §2.5 节号
  - ⚠️ 禁止预先实施 nestedDepth / cyclicCheck / valid 等校验字段(留 canvas 任务)

Step 3 · 扩展 LinkSchema(0.1d · 本 fork 主体之二)
  - 在 LinkSchema 真实定义文件(Step 1 锁定)做两处改动:
    · `nodes: ModuleNode[]` → `nodes: (ModuleNode | SubgraphNodeInstance)[]`(import { SubgraphNodeInstance } from './subgraph')
    · 新增字段 `subgraphDefs: SubgraphDefinition[]`(default initializer 空数组 · 旧文件兼容)
  - 不动 edges 字段(子图嵌套不影响顶层 edges)
  - 不动其他字段(向前兼容 · 旧 .xilink 文件不会破坏)
  - 加 JSDoc 注释引用 ADR-08 §2.5

Step 4 · 扩展 LEGACY_LINK_FILE_MAP(0.1d · 兼容性)
  - 在 LEGACY_MAP 现有惯例文件(Step 1 锁定)添加迁移函数:
    · 旧 .xilink 文件无 `subgraphDefs` 字段 → 注入 `subgraphDefs: []`
    · 旧 .xilink 文件 `nodes` 仅含 ModuleNode → 保持(SubgraphNodeInstance 是新类型 · 旧文件无)
    · 7 天宽限期:2026-06-06 起 strict mode(目前仅 console.warn · 不抛错)
  - 沿用 ADR-05 LEGACY_*_MAP 三件套惯例(版本号 / 迁移函数 / strict 切换日期)

Step 5 · vitest 单测 + 自查 + commit(0.1d)
  - 新增 stages/xilink/__tests__/subgraph-schema.spec.ts:
    · case:SubgraphDefinition 类型字段完整(TypeScript 编译期校验 + runtime new instance)
    · case:LinkSchema.subgraphDefs default 为空数组
    · case:LEGACY_LINK_FILE_MAP 把无 subgraphDefs 字段的旧文件注入 []
    · case:LEGACY_LINK_FILE_MAP 不破坏现有字段
    · case:序列化/反序列化(JSON.stringify → JSON.parse)往返不丢字段
  - 不退化 frontend 现有 356 测试基线(预计 +5 case → 361)
  - npm run typecheck 全绿(0 error)
  - npm run test:unit 不退化
  - commit subject: feat(P1.U-subgraph-schema-extend): add SubgraphDefinition/Port/Instance types + LinkSchema.subgraphDefs + LEGACY_LINK_FILE_MAP (ADR-08 #9)
  - commit trailer 三元组:[step=5/5] [pid=P1] [uid=U-subgraph-schema-extend] [occupies=P1.K-link-schema+P1.K-xilink-types] [files=types/subgraph.ts,types/link.ts,stages/xilink/composables/useLinkLegacyMap.ts]

【验收】(stop 前必跑)

形式合规:
  ☐ npm run typecheck 全绿
  ☐ npm run test:unit 不退化(基线 356/3)+ 新增 5 case 全过(预计 361/3)
  ☐ types/subgraph.ts 三 interface 字段严格匹配 ADR-08 §2.5(无增减)
  ☐ LinkSchema.subgraphDefs 默认空数组 · 旧文件向前兼容
  ☐ LEGACY_LINK_FILE_MAP 沿用 ADR-05 三件套惯例

业务行为契约(端到端真值 · 必跑):
  ☐ 类型导入:在任意新组件 import { SubgraphDefinition, SubgraphPort, SubgraphNodeInstance } from '@/types/subgraph' 编译通过
  ☐ 旧 .xilink 文件加载:无 subgraphDefs 字段的历史 fixture 文件加载后 linkStore.subgraphDefs === []
  ☐ 序列化往返:含 SubgraphDefinition 的 LinkSchema → JSON.stringify → JSON.parse → 字段完整不丢

【commit】
- subject + 三元组 trailer 见 Step 5
- 7 天宽限期内三元组缺失仅 warning · 6/2 起 strict mode 硬拒

【禁止】(6 项红线)
1. ❌ 禁止预先实施画布 UI / Toolbar 按钮 / 右键菜单 / 双击编辑(全部留 P1.U-subgraph-canvas)
2. ❌ 禁止在 SubgraphDefinition 加超出 ADR-08 §2.5 的字段(如 nestedDepth / cyclicCheck / valid · 留 canvas)
3. ❌ 禁止动 ModuleNode 现有字段(本 fork 仅扩展 LinkSchema · 不重构 module schema)
4. ❌ 禁止跳过 LEGACY_LINK_FILE_MAP(用户旧 .xilink 文件必须能 fallback · 沿用 ADR-05 惯例)
5. ❌ 禁止动 ADR-08 议题①/②/③/⑤ 已 zombie 或 dispatched 的 P1.U-dock-cleanup-9to4 / P1.UA8-* 三 fork 文件
6. ❌ 禁止越界引入 stages/xilink/ 其他子目录代码(本 fork 仅 types/ + composables/legacy + tests)

解锁链(本任务 zombie 后)

  • ✅ P1.U-subgraph-canvas(2.5d · 前端 ClaudeA · 主体)直接消费本 fork 类型 + LinkSchema.subgraphDefs · 无需重新设计 schema
  • ✅ ADR-08 §4.3 #9 实施清单闭环 · 议题④ 进度 ½

风险评估

风险 缓解
LinkSchema 真实路径与预期不符 Step 1 grep 锁定真实文件 · 必要时调整 import 路径
ModuleNode / Edge / PortType 类型路径变化 Step 1 grep 锁定 · types/subgraph.ts import 用真实相对路径
旧 .xilink 文件含未预期字段(版本不一致) Step 4 LEGACY_MAP 迁移函数兜底 · 不破坏旧字段
序列化往返字段丢失(JSON 浅拷贝问题) Step 5 单测 case 5 显式验证往返一致性
与 ADR-11 fork 1-v3(ClaudeC)+ fork 1b-v2(ClaudeB)文件并发冲突 全文件路径正交(本 fork 仅动 types/subgraph.ts + types/link.ts + composables/useLinkLegacyMap.ts · 与 stages/xitune/* 不重叠)

历史

时间 事件 hash
2026-05-30 14:58 dispatched · 用户拍板 start P1.U-subgraph-schema-extend(0.5d 前置 schema · 解锁 P1.U-subgraph-canvas) —
2026-05-30 18:12 zombie · 用户拍板"所有 5 步全部完成"· types/subgraph.ts 三 interface + LinkSchema.subgraphDefs + LEGACY_LINK_FILE_MAP 落地 · 解锁 P1.U-subgraph-canvas Step 0 依赖核查 e93ef27