SUPERSEDED

🚫 本 ADR 已被 ADR-AIOS-16 取代(2026-06-02 18:30)

取代原因:用户 2026-06-02 实测 ADR-08-R1 双 fork zombie(58f8e9b + 81e3454)落地后仍报 7 个并行问题(mixer N 显示 / preset dirty 不触发 / module argument dirty 不触发 / mode active 端口错乱 / 右键封装无连线 / 子图模式无声音 / 主图子图是不是两套)· 5 路 subagent 真值核查铁证:主图/子图 Schema 同构但 CRUD 双套并行 + dsp v7 framework 0 subgraph 调度 · 是架构级问题 · ADR-08-R1 决议方向(tab + 端口可配 + 持久化)正确但未触及根因 · 仅修了 UI 与持久化层 · 未消除"双套并行"和"dsp 不感知"两层割裂。

取代者方向:ADR-AIOS-16 路径 B(前端 SubgraphRuntime 展开为扁平 chain frame · v7 framework 零修改严守 §2.6 铁律 · 对标 AudioWeaver Designer)· 7 fork 6.5d 跨栈 · F1 关键路径起点 SubgraphRuntime 类 + F2 unified CRUD 删 7 对 wrapper 消元根因 + F7 e2e truth 7 问题全验收。

历史保留:ADR-08-R1 双 fork commit 58f8e9b + 81e3454 永久保留(supersede 不删 · prompts/done/ADR-AIOS-08-R1/ 子目录文件维持现状)· 本 ADR 文件全部内容下方完整保留作历史档案。

ADR-AIOS-08-R1 · 子图重新设计(议题④ 修订)

status: accepted → superseded by ADR-AIOS-16(2026-06-02 18:30)· proposed_at: 2026-05-31 14:36 · accepted_at: 2026-05-31 14:44 · supersedes_section: ADR-AIOS-08 §2.5 议题④ 决议(部分)

context: ADR-08 5 hotfix 全栈完整闭环(议题①②④⑤ 4 zombie + 议题③ cancelled)· 但用户 2026-05-31 14:21 实测议题④ 子图功能仍严重不可用:① 持久化失败(重启工程子图消失)② 双击不打开新 tab(modal 模式与用户期望不符)③ 端口配置无法改 ④ 整体框架不成熟。3 路 subagent 真值核查锁定根因 = "决议本身就不对 + 决议漏 + 实装漏" 三层叠加 · 不是单纯 hotfix 能修。

1. Context(背景)

1.1 触发原因

• 2026-05-31 14:21 用户实测 ADR-08 验收 · 议题④ 子图原话反馈:

  "新建子图无法保存成功,重新打开工程后还是原始的样子,子图消失;子图双击不会打开新的 tab,显示所有 module;新建子图完全无法改变端口配置;综上所诉子图的整体框架完全不成熟,目前只是拼接功能无法应用,请针对子图问题继续研究一套上下可行方案;按照对标软件 awe designer 来看,子图最重要的就是端口,默认都要有一个虚拟的输入和输出,如果是特殊情况比如多个 source 那可以没有输入,只有输出,这样链路才不会报错;另外子图以什么形式持久化,目前完全没看到你持久化的过程"

1.2 真值核查结论(3 路 subagent 并行)

维度	ADR-08 §2.5 决议	当前实装(40781e8 hotfix 后)	用户实测	判断
modal vs tab	未拍死(二选一)	modal(<Teleport> + dialog)	❌ 期望 tab	决议未拍 + 实装与期望不符
默认端口	仅"封装推导"	❌ 无默认 1in/1out	❌ 必须有默认	决议漏
持久化	LinkSchema.subgraphDefs 嵌入	✅ types 已落 + linkStore.upsertSubgraphDef · ❌ 漏 toJSON/fromJSON 钩子	❌ 重启子图消失	实装漏
端口可配	"命名 + 推导后调"(隐含)	❌ types 仅 label/internalMapping · 无 UI	❌ 无法改端口	决议漏
双击切 tab	"双击进入 + 面包屑"(modal/tab 未拍)	✅ 双击调 openSubgraphEditor 但开 modal	❌ 显示所有 module(modal 渲染 bug)	决议未拍 + 实装 bug

1.3 用户原话拍板的 5 决议方向(2026-05-31 14:35)

全推荐方向:1=B(tab) · 2=B(默认 1in/1out) · 3=A(嵌入 xilink·补 toJSON) · 4=B(全可配) · 5=A(显式 Ctrl+S)

2. Problem(问题陈述)

ADR-08 §2.5 议题④ 决议虽已 accepted 且历经 P1.U-subgraph-canvas(af945e2)+ P1.UH-subgraph-ports-and-dblclick-fix(40781e8)两轮实装,但因 ① 决议本身关键点未拍板(modal/tab + 默认端口 + 端口可配)② 实装漏关键钩子(toJSON/fromJSON)· 导致子图功能用户实测完全不可用 · ADR-08 议题④ 必须做架构级修订才能闭环。

3. Constraints(硬约束)

3.1 工程约束

• ❌ 不破坏 contract-v1.0(永久 frozen · 子图序列化纯前端范畴 · 不涉及后端契约)
• ❌ 不破坏 LEGACY_LINK_FILE_MAP 7 天宽限期(已 ad34568 落盘 · 子图字段必须可降级)
• ❌ 不引入新依赖(用现有 vue-flow 或同类画布库扩展 + Pinia store + 现有 Inspector 框架)
• ✅ MVP 限 2 层嵌套(ADR-08 §3.2 边界铁律 #6 保留)
• ✅ cyclic 检查保留(ADR-08 §2.5 已 accepted · 创建/编辑时拦截)
• ✅ 零回归:议题④ hotfix(40781e8)的端口推导 + 单击高亮 + cyclic 检查必须保留(R1 是补漏 · 不是推翻)

3.2 ⭐ Ximind 大模型兼容性铁律(.clinerules v1.3 §ADR 设计基本要求)

本 ADR 涉及的所有运行时状态 / 操作 / 业务流程必须为 Ximind 大模型预留路径(详见 §11)。

4. Options(决议方向)

决议点 1:子图编辑入口模式

方向	trade-off	推荐
A. modal 弹窗(当前 40781e8 实装)	❌ 单子图限制 · ❌ 用户原话明确反对	—
B. tab 切换 ⭐(LinkEditor 顶部 tab bar:Main / Subgraph A / Subgraph B)	✅ 多子图同时打开 · ✅ tab 可关闭 · ✅ 用户原话期望 · ⚠️ tab bar 占顶部空间(响应式 mobile 用 hamburger menu 折叠)	🔥 推荐
C. 全屏切换(画布替换 + 面包屑 · 纯 AWE Designer)	✅ 严格对标 · ❌ 单焦点限制 · ❌ 无法多子图对比	—

决议点 2:默认端口策略

方向	trade-off	推荐
A. 严格自动推导(当前)	❌ 入口 1 新建空白无端口 · ❌ 孤立子图链路报错 · ❌ 用户原话明确反对	—
B. 默认虚拟 1in + 1out ⭐(创建即给 · 多 source 例外仅 output)	✅ 用户原话直接拍板 · ✅ 防孤立链路报错 · ✅ 入口 1 立即可用 · ⚠️ 部分 AWE 对标	🔥 推荐
C. 完全手动(纯 AWE Designer)	✅ 严格对标 · ❌ 用户体验差(需手动 add)	—

决议点 3:持久化方案

方向	trade-off	推荐
A. 嵌入 .xilink 主文件 ⭐(ADR-08 已 accepted · 补 toJSON/fromJSON 钩子)	✅ 不破坏原决议 · ✅ 链路自包含 · ✅ 仅需补实装 · 工作量小	🔥 推荐
B. 独立 .subgraph.json + 主文件引用(awd-style)	❌ 多文件管理复杂 · ❌ 破坏 LEGACY_MAP · ❌ 工作量大	—
C. 持久化层完全重做(IndexedDB / 独立 schema)	❌ 推翻已 accepted 决议 · ❌ 工作量巨大	—

决议点 4:端口可配置 UI

方向	trade-off	推荐
A. 不允许改	❌ 用户原话明确反对 · ❌ 不符 AWE 行业标杆	—
B. 全可配 ⭐(Inspector 段加 SubgraphPort add/remove/rename/reorder)	✅ AWE Designer 严格对标 · ✅ 用户期望 · ✅ Inspector 框架已有(P1.UA8-link-error-check 落地)· ⚠️ 工作量中等	🔥 推荐
C. 仅可改 label(最小化)	⚠️ 可配性弱 · ⚠️ 不符 AWE	—

决议点 5:autosave / Ctrl+S 体验

方向	trade-off	推荐
A. 显式 Ctrl+S + dirty 标记 ⭐(VS Code / IDE 通用模式 · tab 标 ●)	✅ 文件型工程标杆 · ✅ 用户预期清晰 · ✅ 与现有 .xilink 文件持久化对齐	🔥 推荐
B. autosave debounce 2s(figma 风)	⚠️ 无感知 · ❌ 与文件型工程不符 · ❌ 撤销复杂	—
C. 双轨(autosave indexedDB + Ctrl+S 落 .xilink)	⚠️ 复杂度倍增 · ⚠️ MVP 阶段过度设计	—

5. Decision(决议 · 用户拍板原话)

用户 2026-05-31 14:35 答复:"全推荐方向:1=B(tab) · 2=B(默认 1in/1out) · 3=A(嵌入 xilink·补 toJSON) · 4=B(全可配) · 5=A(显式 Ctrl+S)— 直接拍 · 我立即起 ADR-08-R1"

5 决议明细

决议 R1.1:tab 模式编辑入口

• LinkEditor 顶部增 tab bar:Main / Subgraph A / Subgraph B / +
• 双击 SubgraphNodeInstance → 创建/激活对应 tab + 切换至该 tab 画布
• tab 可关闭(× 按钮)· 关闭不删 SubgraphDefinition(仅关闭视图)· 重新双击节点重新打开
• 响应式:mobile(< 768px)tab bar 折叠为 hamburger menu(下拉 + 当前 tab 标题)
• 面包屑保留(tab 内顶部):Main / Subgraph A 风格 · 与 AWE Designer 对齐

决议 R1.2:默认虚拟端口策略

• 入口 1(Toolbar 新建子图):创建 SubgraphDefinition 时默认含:
• inputPorts: [{ id: 'in_0', label: 'Input 1', type: 'audio', internalMapping: null }]
• outputPorts: [{ id: 'out_0', label: 'Output 1', type: 'audio', internalMapping: null }]
• 入口 2(多选封装):保留当前推导算法(40781e8)· 推导出 inputPorts/outputPorts(可能 0/N)
• 用户可在 Inspector 段后续 add/remove/rename/reorder(决议 R1.4)
• 多 source 例外:用户在 Inspector 删除 inputPorts → 子图变"纯输出"· 链路验证不报"无输入"错
• internalMapping 可为 null(默认端口 / 用户手动加的端口)· 仅"封装推导"出的端口才有 internalMapping

决议 R1.3:嵌入持久化 + 补 toJSON/fromJSON 钩子

• LinkSchema.subgraphDefs[] 字段保留(P1.U-subgraph-schema-extend e93ef27 已落)
• 补关键钩子(本 R1 实装):
• linkStore.toJSON():必须含 subgraphDefs: state.subgraphDefs.map(d => structuredClone(d))(深拷贝 + Date 对象转 ISO)
• linkStore.fromJSON(json):必须含 state.subgraphDefs = (json.subgraphDefs || []).map(d => normalizeSubgraphDef(d))(LEGACY 兼容 7d)
• saveLinkFile():落 .xilink 时含 subgraphDefs · 用户 Ctrl+S 后立即落盘
• loadLinkFile():打开 .xilink 时恢复 subgraphDefs · 重启工程后子图必须复原
• normalizeSubgraphDef:LEGACY_MAP 7d 宽限期处理(eg. 旧文件无 subgraphDefs → 返 [])
• 单测必须覆盖:① save/load 往返(deep equal)② 无 subgraphDefs 旧文件加载不 throw ③ subgraphDefs 含 SubgraphNodeInstance + 嵌套 1 层

决议 R1.4:全可配端口 UI

• 选中 SubgraphNodeInstance / SubgraphDefinition 时 · Inspector 显示 6 段(已 P0.U-right-inspector-framework 77b7a50 落地框架):
• 基本信息(name / description)
• inputPorts 列表(每行:label / type 下拉 + internalMapping 显示 + 删除按钮 + 上移/下移按钮)
• + Add Input Port 按钮 → 加 { id: 'in_<n>', label: 'Input <n+1>', type: 'audio', internalMapping: null }
• outputPorts 列表(同上)
• + Add Output Port 按钮
• 节点列表只读预览(子图内含哪些 module)
• 改动后 immediately mark dirty(决议 R1.5)
• type 下拉选项:audio / control(预留 §K2-protocol-v2 §control-signal-bus 接入)

决议 R1.5:显式 Ctrl+S + dirty 标记

• Pinia store 加 isDirty: ref(false)
• watch subgraphDefs / modules / edges deep · debounce 50ms 后 set isDirty = true
• LinkEditor 标题显示 dirty 标记:Untitled.xilink ● / Untitled.xilink(无 dirty)
• tab bar 每个 tab 标题显示 ● dirty 标记
• Ctrl+S(/ Cmd+S):
• 触发 saveLinkFile() · 若文件已存在直接覆写 · 若未保存过弹文件选择对话框
• 成功后 set isDirty = false
• 关闭未保存 tab / 工程时弹 confirm:保存更改? [保存] [不保存] [取消]
• 不实装 autosave(MVP 阶段 · 后续可起 R2 加)

6. Consequences(影响面)

6.1 正面

• ✅ 子图功能用户实测可用(默认端口 + 持久化 + tab + 可配 + Ctrl+S 五位一体)
• ✅ AWE Designer 行业标杆对标(端口可配 + 面包屑 + tab 模式)
• ✅ 解锁议题④ 验收清单 C4-1~C4-17 全 17 项
• ✅ 为后续 ADR-AIOS-13(可能的智能子图推荐 / 自动封装常用模式)预留基础设施
• ✅ Ximind 大模型可读子图状态 + 可写端口配置(详见 §11)

6.2 负面

• ⚠️ 工作量(估 2.0d 前端 ClaudeA · MVP 内可控)
• ⚠️ tab bar 占顶部空间(响应式 mobile 折叠缓解)
• ⚠️ 与 ADR-08 议题④ 原决议(modal vs tab 未拍)有部分变更 · 但本 R1 是"补漏 + 修订"· 不是 supersede 整个 ADR-08

6.3 跨进程影响

• P1-xilink(直接影响):LinkEditor + SubgraphCanvas + Inspector + linkStore + 持久化层全改
• P0-xistudio(间接):.xilink 文件 schema 不变(仅补钩子)· 不影响其他 stage 加载
• contracts-v1.0(无影响):纯前端范畴
• 后端 / DSP(无影响):子图序列化不涉及后端

7. Implementation(实施计划)

7.1 fork U-thread 列表(2 fork · 共 2.0d ClaudeA · 文件正交并行)

fork	UID	摘要	工作量	部门	隔离
1	P1.UA8R1-subgraph-redesign-tab-and-ports	tab bar + 默认端口 + Inspector 端口可配 UI · 决议 R1.1+R1.2+R1.4	1.5d	前端	🧵 file
2	P1.UA8R1-subgraph-persist-and-dirty	toJSON/fromJSON 钩子 + Ctrl+S + dirty 标记 · 决议 R1.3+R1.5	0.5d	前端	🧵 file

7.2 ⭐ Ximind 兼容性 fork 标注

• fork 1 实施"Ximind 可读端口配置 API"(GET /api/links/:id/subgraphs/:defId/ports)+ 自然语言描述字段(SubgraphPort.label + description)
• fork 2 实施"Ximind 可调操作"(saveLinkFile 触发 audit log → /ws/audit/stream)

7.3 Phase 划分

• Phase 1(并行):fork 1 + fork 2 文件正交可同时 dispatch · ClaudeA 内部串行(同一 worker)· 总 2.0d
• Phase 2(用户验收):fork 全 zombie 后用户重跑议题④ C4-1~C4-17 验收清单 + AWE Designer 对标实测

7.4 K-thread 占用

• fork 1:P1.K-xilink-canvas(写)+ P1.K-xilink-toolbar(写 · 加 tab bar)+ P1.K-inspector(写 · 加端口可配段)+ P1.K-types(写 · SubgraphPort 加 description / order 字段)
• fork 2:P1.K-link-store(写 · 补 toJSON/fromJSON + isDirty)+ P1.K-xilink-canvas(写 · Ctrl+S 监听)
• 两 fork 文件正交:fork 1 改 stages/xilink/ + components/canvas/ + Inspector · fork 2 改 stores/linkStore.ts + 全局 keymap

8. Migration(迁移与降级)

8.1 LEGACY 兼容(7d 宽限期)

• 旧 .xilink 文件无 subgraphDefs 字段 → fromJSON 返空数组 · 不 throw
• 旧 SubgraphPort 无 description / order 字段 → normalizeSubgraphDef 加默认值
• LEGACY_LINK_FILE_MAP(已 ad34568 落地)继续生效

8.2 升级路径

• 用户当前打开旧 .xilink → R1 实装后立即升级 schema(后台静默)
• 第一次 Ctrl+S 后落盘新 schema
• 7 天后(2026-06-07)废弃 LEGACY_MAP

8.3 与议题④ hotfix(40781e8)的关系

• ✅ 保留:端口推导算法(useSubgraph.createSubgraphFromSelection)+ 单击高亮 + cyclic 检查
• ✏️ 修改:SubgraphCanvas 从 modal 改 tab 模式(LinkEditor 集成 tab bar)
• ➕ 新增:默认端口策略 + Inspector 端口可配 UI + toJSON/fromJSON 钩子 + Ctrl+S/dirty
• ❌ 删除:无(R1 是增量修订 · 不删功能)

9. Validation(验收标准)

9.1 形式合规

• npm run typecheck 零错误
• npm run test:unit 全绿(基线 +12 用例 · fork 1 8 + fork 2 4)
• 修改文件 ≤ 10 个(linkStore + LinkEditor + SubgraphCanvas + Inspector 3 段 + types/subgraph + types/link + 2 tests)
• 不动 contracts/ / backend_csharp/ / dsp_algo/

9.2 业务行为契约(端到端真值 · 必跑)

默认端口(决议 R1.2)

• 入口 1 新建子图 → SubgraphDefinition 默认含 1 inputPort + 1 outputPort
• 多 source 例外:Inspector 删除 inputPort → 子图无输入 · 链路验证不报"MODULE_NOT_CONNECTED"

tab 模式(决议 R1.1)

• 双击 SubgraphNodeInstance → LinkEditor tab bar 增加新 tab 并切换至该 tab
• tab 内显示子图画布 + 顶部面包屑 Main / <子图名>
• 重复双击同一 SubgraphNodeInstance → 不重复创建 tab · 直接切换至已有 tab
• tab × 关闭 → tab 消失 · 不删 SubgraphDefinition · 重新双击重开

持久化(决议 R1.3)

• Ctrl+S 保存 .xilink → 文件含 subgraphDefs 字段(JSON 数组)
• 关闭工程 + 重启 mkdocs → 重新打开 .xilink · 子图完整恢复(SubgraphNodeInstance + SubgraphDefinition + 内部 modules + ports)
• 旧 .xilink(无 subgraphDefs)加载不 throw · subgraphDefs = []

端口可配(决议 R1.4)

• 选中 SubgraphDefinition → Inspector 显示 inputPorts + outputPorts 列表
• 加 / 删 / 改名 / 改 type / 上下移 端口 · 立即生效 · isDirty=true
• internalMapping 列(若非 null)只读显示 · 用户不可改(避免破坏推导关系)

Ctrl+S + dirty(决议 R1.5)

• 改任意字段 → tab 标题 + 工程标题立即出 ● dirty 标记
• Ctrl+S 触发保存 · 成功后 ● 消失
• 关闭未保存 tab → 弹 confirm 三选项([保存] [不保存] [取消])

9.3 用户重跑 ADR-08 验收清单 C4-1~C4-17 17 项全过

10. References(关联)

10.1 上游依赖

• ADR-AIOS-08 §2.5 议题④ 原决议(本 R1 修订)
• ADR-AIOS-08-acceptance-checklist §议题④ C4-1~C4-17

10.2 关联 commit / fork

• e93ef27 P1.U-subgraph-schema-extend(types 已落 · 不动)
• af945e2 P1.U-subgraph-canvas(modal 实装 · 本 R1 改 tab)
• 40781e8 P1.UH-subgraph-ports-and-dblclick-fix(端口推导 + 单击高亮 · 本 R1 保留)
• 77b7a50 P0.U-right-inspector-framework(Inspector 框架 · 本 R1 复用)

10.3 跨 ADR 关联

• ADR-AIOS-07 §2.3 边界铁律 #2(stages 不自实装组件 · 本 R1 复用 Inspector 框架对齐)
• ADR-AIOS-12 §3.7 ②-⑤(Recorder 文件持久化 · 本 R1 持久化模式参考)

10.4 真值核查报告

• 3 路 subagent 并行核查(2026-05-31 14:30):① types/subgraph + useSubgraph + SubgraphCanvas 实装现状 ② AWE Designer Subsystem 对标 ③ ADR-08 §议题④ + C4-* 验收要点

11. ⭐ Ximind Compatibility(大模型兼容性 · v1.3 铁律)

11.1 大模型可读状态

状态	端点	字段
子图列表	GET /api/links/:linkId/subgraphs	[{ id, name, description, inputPorts, outputPorts, nodeCount, modifiedAt }]
单个子图详情	GET /api/links/:linkId/subgraphs/:defId	完整 SubgraphDefinition(含 nodes / edges / ports / presetParams)
子图实例列表	GET /api/links/:linkId/subgraph-instances	[{ id, subgraphDefId, position, paramOverrides }]
dirty 状态	GET /api/links/:linkId/state	{ isDirty: bool, lastSavedAt }

11.2 大模型可写操作

操作	端点	语义
加端口	POST /api/links/:linkId/subgraphs/:defId/ports	body: { direction: 'input'\|'output', label, type, description } · 返回新 SubgraphPort
删端口	DELETE /api/links/:linkId/subgraphs/:defId/ports/:portId	校验 internalMapping 非 null 时拒删(保护推导关系)
改端口	PATCH /api/links/:linkId/subgraphs/:defId/ports/:portId	body: { label?, type?, order? }
保存子图	POST /api/links/:linkId/save	触发 saveLinkFile · 返回 { savedAt, fileSize }

(MVP 阶段:以上 API 暂不实装 · 仅在 R2 / Ximind 真接入时落地 · 本 R1 实装阶段确保前端 store 状态可读 + 操作可序列化即可)

11.3 业务流程自然语言描述字段

• 每个 SubgraphDefinition 含 description: string(用户可写 · 大模型可读)
• 每个 SubgraphPort 含 description?: string(可选 · 大模型可读)
• 每个用户操作触发 audit log:

  {
    action: 'subgraph.port.add',
    description: '在子图 "动态压缩链路" 中添加 1 个音频输入端口 "Sidechain"',
    timestamp: 1717142400000,
    userId: 'user-default',
    payload: { defId, portId, direction, label }
  }
  

11.4 审计日志路径

• WS 推送:/ws/audit/stream · 实时推送所有子图操作(add/remove/rename/save)
• 持久化:audit.log.jsonl(append-only · 同 .xilink 同目录 · MVP 阶段可仅 in-memory)
• Ximind 大模型可订阅 /ws/audit/stream · 回放用户操作以解释意图

11.5 Error 结构

{
  code: 'SUBGRAPH_PORT_INTERNAL_MAPPING_LOCKED',
  message: '不能删除已映射到内部模块的端口',
  recovery_hints: [
    '先在子图内部解除该端口的连接',
    '或在 Inspector 中改 label 而非删除',
    '若必须删除 · 删除子图 + 重新创建'
  ]
}

11.6 Ximind 兼容性检查清单(本 ADR §3.2 铁律)

• 已识别 4 个"Ximind 大模型可读状态"(子图列表 / 单个详情 / 实例列表 / dirty 状态)
• 已识别 4 个"Ximind 大模型可写操作"(加 / 删 / 改端口 + 保存子图)
• 已设计审计日志路径(WS /ws/audit/stream + audit.log.jsonl)
• 已定义 error 结构(code + message + recovery_hints[])
• 业务流程关键 Step 含 description 字段(SubgraphDefinition / SubgraphPort / audit log)
• §7 Implementation 显式标注 fork 1+2 的 Ximind 兼容性任务

---

文档状态:accepted(2026-05-31 14:44 用户拍板)· fork 1+2 进入 ready 队列 · 等用户 start P1.UA8R1-subgraph-redesign-tab-and-ports(优先)/ start P1.UA8R1-subgraph-persist-and-dirty 派发。