ACCEPTED

ADR-AIOS-20 · XiFore 完善

状态：accepted v0.1 · 2026-06-12 · 用户拍板 · 业务契约 5 段 × 4 块全填齐前置：ADR-AIOS-04 accepted(v1.0)，WidgetRegistry + ModuleUID 类型层已就位目标：XiFore 完成度 ~30% → ~80%，解锁"用户直接搭建调音工具界面"与"接入自定义算法"两条核心路径

1. 上下文(Context)

1.1 用户原话存档(verbatim · 防漂移)

1.1.1 XiFore 产品定义(来自之前对话)

"XiForge 就是创建模块的功能，用户可以直接搭建调音工具的界面，也可以直接将自己的算法接入系统"

1.1.2 本 ADR 触发(2026-06-12)

"前边分析的可介入任务中，选择 XiFore 产品优先完善，按照现有的规则先建立对应的 ADR 需求"

1.2 现状调研(2026-06-12 真值)

1.2.1 代码结构现状

文件	行数	状态说明
`stages/xiforge/ModuleCreator.vue`	4 105	✅ 核心 UI 框架已存在(layout 三栏)
`stages/xiforge/McWidgetPropsPane.vue`	1 469	✅ Widget 属性面板已存在
`stages/xiforge/McModulePropsPane.vue`	483	✅ Module 属性面板已存在
`stages/xiforge/widgets/registry.ts`	136	✅ WidgetRegistry 全部实现
`stages/xiforge/widgets/auto-register.ts`	75	✅ glob 自动扫描已实现
`stages/xiforge/widgets/L1/DemoButton.vue`	60	⚠️ 仅 1 个 L1 控件
`types/module.ts`	—	✅ ModuleUID / VendorTag / ModuleUIDNamespace 已就位
`stages/xitune/xml-tuning/`(12 文件)	2 586+	❌ 未退役
`stores/useXmlTuningStore.ts`	—	❌ 未退役
`utils/xmlConfigParser.ts`	—	❌ 未退役
`types/xmlTuning.ts`	—	❌ 未退役
codegen 相关	—	❌ 完全未实现（ADR-04 整季推迟）
算法接入路径	—	❌ 完全未实现

1.2.2 ADR-04 已落地的部分

✅ types/module.ts：ModuleUID、VendorTag、ModuleUIDNamespace、formatModuleUID、parseModuleUID
✅ types/widget.ts（WidgetDef 迁移后）
✅ stages/xiforge/widgets/registry.ts：WidgetRegistry 完整实现（register / unregister / lookup / list / getByModuleUID）
✅ stages/xiforge/widgets/auto-register.ts：import.meta.glob 扫描机制
✅ ModuleMode 简化（4 mode → 2 mode · normal / legacy）

1.2.3 ADR-04 推迟的部分（本 ADR 接手）

ADR-04 推迟项	原因	本 ADR 状态
L1 控件补齐（15 → 30）	"本季度仅做 DemoButton 演示"	接手实施
xml-tuning 整体退役	"P-1 阶段任务"	接手实施
codegen C 头文件模板	"P1 下季度"	接手实施
Preset Schema 自动派生	"P1 下季度"	接手实施
L3 路径选择	"推迟至 L1+L2 落地"	本 ADR 不涉及
L2 配置型复合控件	"下下季度"	本 ADR 不涉及

1.2.4 XiFore 完成度差距根因

XiFore ~30% 原因：
  ① L1 控件 1/30 = 3%  → 用户无法拖入控件搭建界面
  ② xml-tuning 未退役  → 代码污染 · types 层 WidgetDef 不干净
  ③ codegen 未做       → ModuleDef → C 头文件链路断裂
  ④ 算法接入缺失       → 用户自定义 DLL/Python 无法接入 ModuleCreator

1.3 用户的核心产品目标

搭建调音工具界面：用户在 ModuleCreator 拖拽 L1 控件（Knob / Slider / Fader / EQ 等），配置参数，生成可用的模块 UI
接入自定义算法：用户将自己编写的 DSP 算法（C DLL 或 Python Sidecar）注册为 ModuleDef，在 XiLink 链路图中调用

2. 决议(Decision)

2.1 主决议 · 4 项任务

#	任务	工作量	优先级
T1	xml-tuning 整体退役 + 类型迁移	2d	P-1（前置）
T2	L1 控件补齐（15 → 30，先补核心 14 个）	2.5d	P0
T3	codegen C 头文件 + Preset Schema 自动派生	2d	P0
T4	算法接入路径定义 + ModuleCreator 接入 UI + 链路图容错(A20.C5)	2.8d	P1
	总计	9.3d

2.2 T1 · xml-tuning 整体退役

目标：清除 ADR-04 §2.1.4 定义的退役清单，确保 types/widget.ts 成为唯一控件类型来源。

2.2.1 退役清单

文件/目录	操作
`stages/xitune/xml-tuning/`（12 文件）	整体删除
`stores/useXmlTuningStore.ts`	删除
`utils/xmlConfigParser.ts`	删除
`types/xmlTuning.ts`	删除（类型已迁移至 `types/widget.ts`）
`public/xml-configs/` 数据目录	删除（legacy 模块在 ModuleCreator 重建）

2.2.2 外部引用清理（9 处）

文件	变更内容
`components/MenuBar.vue`	移除 xml-tuning 菜单项
`stages/xilink/ModuleLibraryPanel.vue`	import 改为 `types/widget`
`stages/xilink/index.vue`	xmlStore 引用清除
`stages/xiforge/ModuleCreator.vue`（3 行）	import 改为 `types/widget`
`stages/xiforge/ThirdPartyModuleDialog.vue`	def.kind 引用清除
`stages/xitune/PresetPanel.vue`	xmlStore 引用清除
`stores/useModuleDefStore.ts`	注释/移除 xmlStore 注入

2.2.3 类型完整性校验

退役完成后，全局搜索 XmlWidget / useXmlTuning / xmlConfigParser 必须 0 命中（node_modules 排除）。

2.3 T2 · L1 控件补齐（14 个核心控件）

基线：ADR-04 §2.1.1 定义的 15 候选控件，当前仅 DemoButton（实为演示占位，需重写为正式 L1）。

2.3.1 L1 核心控件清单（本 ADR 实施 14 个）

uid	控件	对标现有组件	优先级
`knob`	旋钮（0°–360°，步长可配）	TT / Xml	P0
`slider-h`	水平滑块	TT / Xml	P0
`slider-v`	垂直滑块（Fader 形态）	TT / Xml	P0
`button-toggle`	开关按钮（on/off）	TT / Xml	P0
`button-momentary`	瞬态按钮	TT*	P0
`label-value`	数值显示标签（只读）	TT / Xml	P0
`combo-box`	下拉选择框	TT / Xml	P0
`eq-band`	EQ 频段显示（带 SVG 曲线）	TT / Xml	P1
`meter-level`	电平表（dBFS · 峰值保持）	TT / Xml	P1
`number-input`	数值输入框（带单位）	Xml*	P1
`radio-group`	单选按钮组	Xml*	P1
`checkbox`	复选框	Xml*	P1
`tab-bar`	标签切换栏	TT*	P1
`xy-pad`	XY 控制面（二维参数映射）	新增	P2

注意：DemoButton.vue 保留原位但标注 @deprecated（无 widgetMeta export，不会被 auto-register 扫描），ButtonToggleWidget.vue 作为正式替代（L1 · uid=atom.button-toggle）。

2.3.2 控件元数据规范（`WidgetMeta`）

每个 L1 控件通过 named export widgetMeta: WidgetMeta 声明自身元数据， auto-register.ts 自动扫描后注入 component 字段并调用 widgetRegistry.register(meta)。实际类型定义见 types/widget.ts：

// types/widget.ts · WidgetMeta（已实现 · 本 ADR 直接复用）
interface WidgetMeta {
  uid: string            // 例：'atom.knob'
  level: 'L1'
  category: WidgetCategory   // 例：WidgetCategory.Control
  displayName: string    // 例：'旋钮'
  description?: string
  version?: string
  tags?: readonly string[]
  component?: unknown    // 由 auto-register.ts 注入 SFC 组件 default export
  icon?: string
  moduleUID?: number     // 若该控件专属某 module，可绑定 moduleUID
}

2.3.3 控件目录结构

src/stages/xiforge/widgets/
  L1/
    KnobWidget.vue
    SliderHWidget.vue
    SliderVWidget.vue
    ButtonToggleWidget.vue
    ButtonMomentaryWidget.vue
    LabelValueWidget.vue
    ComboBoxWidget.vue
    EqBandWidget.vue
    MeterLevelWidget.vue
    NumberInputWidget.vue
    RadioGroupWidget.vue
    CheckboxWidget.vue
    TabBarWidget.vue
    XyPadWidget.vue
  index.ts        ← 各控件在此统一 auto-register

2.3.4 McWidgetPropsPane 渲染适配

McWidgetPropsPane.vue 当前按 widget uid 做 v-if 分支渲染属性面板（1469 行）。L1 控件补齐后，新增控件的属性编辑暂走通用 fallback（<textarea> JSON 编辑器），后续迭代再统一为 schema 驱动渲染。

2.4 T3 · codegen C 头文件 + Preset Schema 自动派生

目标：ModuleDef → 自动生成 set_xxx / get_xxx C 函数声明 + Preset JSON Schema，实现 HMI 单向驱动（ADR-04 §2.1.3 方向 X）。

2.4.1 codegen 输出格式

C 头文件（<module_id>_params.h）：

// 自动生成 · 勿手改 · 由 XiForge codegen 生成
// ModuleDef: xistudio:gain@0x00000200
// 生成时间: 2026-06-12T10:00:00Z

#pragma once

// === gain ===
void gain_set_volume(float value);   // range: [-60.0, 12.0] dB
float gain_get_volume(void);
void gain_set_mute(bool value);
bool gain_get_mute(void);

Preset JSON Schema（<module_id>_preset_schema.json）：

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "title": "GainPreset",
  "type": "object",
  "properties": {
    "volume": { "type": "number", "minimum": -60, "maximum": 12, "description": "dB" },
    "mute":   { "type": "boolean" }
  },
  "required": ["volume", "mute"]
}

2.4.2 codegen 触发路径

用户在 ModuleCreator 完成 widget 配置
  → 切换至 "Code" tab（XiForgeCodeView.vue）
  → 前端调用 /api/codegen/generate（POST，body: ModuleDef JSON）
  → 后端 CodegenService 生成 .h + _preset_schema.json
  → 前端展示代码（Monaco editor 预览）+ "下载" 按钮

2.4.3 后端 CodegenService 边界

类	文件	职责
`CodegenController`	`Controllers/CodegenController.cs`	HTTP POST `/api/codegen/generate` 入口
`CodegenService`	`Services/CodegenService.cs`	ModuleDef → .h 字符串 + schema JSON
`CodegenRequest`	`Models/CodegenRequest.cs`	请求体（含 ModuleDef 序列化）

legacy 边界约束（继承 ADR-04 §2.1.3）： - def.mode === 'legacy' 的 ModuleDef 跳过 codegen，后端直接返回 { skipped: true, reason: "legacy mode" } - XiForgeCodeView.vue 根据 mode 显示 "⚠️ legacy 模块不参与 codegen" 提示

2.4.4 Preset Schema 自动派生规则

WidgetDef 属性	映射到 JSON Schema
`type: 'slider' \\| 'knob'`	`"type": "number", "minimum": min, "maximum": max`
`type: 'toggle' \\| 'checkbox'`	`"type": "boolean"`
`type: 'combo-box' \\| 'radio-group'`	`"type": "string", "enum": options`
`type: 'label-value'`（只读）	不生成 schema 字段
`default` 值	`"default": value`

2.5 T4 · 算法接入路径

目标：用户将自定义 DSP 算法（C DLL 或 Python Sidecar 插件）注册为 ModuleDef，使其在 XiLink 链路图中与内置模块一样可以拖入编排。

2.5.1 两条接入路径

路径 A · C DLL 接入（source: 'thirdparty'）：

用户提供：
  ① <algo>.dll（导出符合 XiStudio ABI 的 set_xxx/get_xxx 函数）
  ② algo_manifest.json（描述 ModuleDef · 参数 · vendor 信息）

流程：
  ModuleCreator → "导入 DLL" → 后端 DllImportService.Register()
    → 验证 ABI 签名
    → 生成 ModuleDef（source: 'thirdparty', vendor: 'xivst', uid: 0xAAAA_xxxx）
    → 注册至 moduleDefStore（与内置模块并列）
  后续使用与内置模块无差异（拖入 XiLink · legacy_set_param 协议下发）

路径 B · Python Sidecar 接入（source: 'thirdparty'）：

用户提供：
  ① Python 模块（实现 process(params: dict) → result: dict 接口）
  ② 在 pysidecar/analyzer/ 下注册端点

流程：
  pysidecar 端点：POST /custom/<algo_id>/apply
    → 读取 params → 调用用户 Python 模块 → 返回结果
  前端 ModuleCreator → "导入 Python 插件"
    → 输入 algo_id + 参数 schema
    → 生成 ModuleDef（source: 'thirdparty', vendor: 'xivst'）
    → 注册至 moduleDefStore

2.5.2 ModuleCreator 接入 UI（ThirdPartyModuleDialog 重定位）

ADR-04 §1.2 指出：ThirdPartyModuleDialog 当前是运行时模块控制面板（双击实例的浮动窗），命名误导。本 ADR 决议：保留原有运行时功能（PID 寻址 + legacy_set_param）+ 新增"导入算法"入口，通过 Tab 分离：

ThirdPartyModuleDialog.vue
  ├── Tab "运行控制"（原功能保留 · PID 寻址 · legacy_set_param 下发）
  └── Tab "导入算法"（新功能 · 本 ADR T4）
        ├── 方式一：导入 DLL（文件选择 + manifest 编辑）
        └── 方式二：注册 Python 端点（algo_id 输入 + schema 编辑）

2.5.3 后端 DllImportService 边界

接口	端点	行为
注册 DLL	`POST /api/modules/dll-import`	验证 ABI + 生成 ModuleDef JSON
注册 Python	`POST /api/modules/python-import`	验证端点可达 + 生成 ModuleDef JSON
列出三方模块	`GET /api/modules?source=thirdparty`	返回已注册的 `source: 'thirdparty'` 列表
卸载三方模块	`DELETE /api/modules/{uid}`	注销 + 从 workspace 移除

安全约束： - DLL 导入必须白名单验证（ABI 签名 + 文件哈希） - Python 端点 URL 仅允许 localhost / 127.0.0.1（禁止外部 URL）

3. 业务行为契约(Business Behavior Contract)

格式：5 必填段 × 4 块（继承 ADR-12 §3 标杆）。命名约定 A20.Cn。

A20.C1 · L1 控件拖入布局

① 用户行为(User Action)

用户在 ModuleCreator 左侧控件面板（DrawerWidgets）选中一个 L1 控件（如"旋钮"），拖入中央 canvas，松手放置。

② 系统响应(System Response)

McWidgetPropsPane.vue 右侧属性面板出现，按控件 uid 渲染对应属性编辑项（v-if 分支或通用 JSON fallback）。
Canvas 渲染新控件实例（WidgetRenderer 动态组件）。
ModuleDef 的 params.properties.widgets[] 追加新 WidgetDef（含默认值）。

③ 数据流(Data Flow)

用户拖拽 → DragEvent
  → ModuleCreator.vue: handleWidgetDrop(uid)
  → widgetRegistry.lookup(uid) → WidgetMeta
  → moduleDefStore.addWidget(moduleDef.id, newWidgetDef)
  → McWidgetPropsPane.vue 监听 moduleDefStore 变化 → 重渲染属性面板
  → Canvas: WidgetRenderer.vue renders new widget instance

④ 验收标准(Acceptance Criteria)

14 个 L1 控件均可在 DrawerWidgets 面板列出（按 level='L1' 过滤）
拖入后 canvas 立即显示控件默认形态（不需要刷新）
右侧属性面板渲染该控件的可编辑属性项（uid 匹配 v-if 分支或 JSON fallback）
ModuleDef JSON 在保存（Ctrl+S）后包含新增的 WidgetDef
重复拖入同一控件类型，canvas 显示多个独立实例（不互相干扰）

A20.C2 · codegen 生成 C 头文件

① 用户行为(User Action)

用户在 ModuleCreator 完成 widget 配置后，切换至 "Code" tab，点击"生成代码"按钮。

② 系统响应(System Response)

前端 POST /api/codegen/generate，body 为当前 ModuleDef JSON。
后端 CodegenService 解析 params.properties.widgets[]，生成：
<module_id>_params.h：每个控件映射 set_xxx / get_xxx 函数声明
<module_id>_preset_schema.json：每个控件映射 JSON Schema 属性
前端 XiForgeCodeView.vue Monaco editor 展示生成的 .h 内容。
"下载 .h" / "下载 schema.json" 按钮可用，点击下载文件。

③ 数据流(Data Flow)

用户点击"生成代码"
  → XiForgeCodeView.vue: handleGenerate()
  → POST /api/codegen/generate { moduleDef }
  → CodegenController → CodegenService.Generate(req.ModuleDef)
    → foreach widget in moduleDef.params.properties.widgets:
        → 根据 widget.type 映射 C 类型 + 函数签名
    → 返回 { header: string, presetSchema: object }
  → XiForgeCodeView.vue: monacoEditorValue = res.header
  → 按钮 href = Blob URL

④ 验收标准(Acceptance Criteria)

mode='normal' 的 ModuleDef 点击生成代码后 Monaco editor 显示 .h 内容
生成的 .h 包含所有 widget（不含 label-value 只读控件）对应的 set_xxx / get_xxx 声明
mode='legacy' 的 ModuleDef 点击生成代码后显示"⚠️ legacy 模块不参与 codegen"警告，无生成内容
"下载 .h" 按钮点击后本地下载 <module_id>_params.h 文件
"下载 schema.json" 按钮点击后本地下载 <module_id>_preset_schema.json 文件
生成的 preset_schema.json 通过 ajv.validateSchema() 验证（前端单元测试）

A20.C3 · xml-tuning 退役后零回归

① 用户行为(User Action)

退役后，用户正常使用 XiFore（创建模块、拖控件、保存）和 XiTune（预设管理）。

② 系统响应(System Response)

所有 XiFore / XiTune 功能正常，无任何 XmlWidget / useXmlTuning / xmlConfigParser 相关代码路径被触发。

③ 数据流(Data Flow)

退役前：ModuleCreator.vue → import { XmlWidgetDef } from '@/types/xmlTuning'
退役后：ModuleCreator.vue → import { WidgetDef } from '@/types/widget'

退役前：useXmlTuningStore → xmlStore.setAppMode('normal')
退役后：该调用不存在 · appMode 由 workspaceStore 管理

④ 验收标准(Acceptance Criteria)

grep -r "XmlWidget\|useXmlTuning\|xmlConfigParser" src/ 输出 0 行（node_modules 排除）
tsc --noEmit 0 错误（退役后类型完整性）
Vitest 单元测试：moduleDefStore、widgetRegistry 相关测试全部通过
XiForge 创建模块流程 E2E 通过（Playwright）
XiTune PresetPanel 功能正常（预设加载 / 保存不报错）

A20.C4 · 三方算法接入（DLL 路径）

① 用户行为(User Action)

用户在 ModuleCreator → ThirdPartyModuleDialog → "导入算法" Tab → 选择"导入 DLL"，上传 my_algo.dll + my_algo_manifest.json，点击"注册"。

② 系统响应(System Response)

后端验证 DLL ABI 签名（导出函数符合 set_xxx / get_xxx 模式）。
后端返回生成的 ModuleDef（source: 'thirdparty', vendor: 'xivst', uid: 0xAAAA_xxxx）。
前端 moduleDefStore.addThirdPartyModule(def) 注册，模块出现在 XiLink 模块库面板。
用户可将该三方模块拖入 XiLink 链路图，行为与内置模块一致（legacy_set_param 协议下发）。

③ 数据流(Data Flow)

用户上传 DLL + manifest
  → ThirdPartyModuleDialog.vue: handleDllImport(file, manifest)
  → POST /api/modules/dll-import { dllBase64, manifest }
  → DllImportService.Register(dll, manifest)
    → 验证 ABI 签名
    → 分配 uid = 0xAAAA_0000 + autoIncrement
    → 返回 ModuleDef JSON
  → moduleDefStore.addThirdPartyModule(def)
  → XiLink ModuleLibraryPanel: 新模块出现（标注 "3rd party" 标签）
  → 用户拖入链路图 → 实例化 → legacy_set_param 下发

④ 验收标准(Acceptance Criteria)

上传符合 ABI 的 DLL + manifest，注册成功，模块出现在库面板（标注"3^rd party"）
上传不符合 ABI 的 DLL，后端返回 400 + 错误信息，前端展示用户友好提示
注册后的三方模块 uid 落在 0xAAAA_0000 ~ 0xFFFE_FFFF 段（单元测试验证）
Python Sidecar 路径：POST /custom/<algo_id>/apply 端点可达后，Python 模块注册成功
DLL 导入拒绝 localhost 以外的 URL 和任意远程资源（安全约束单元测试）
三方模块被拖入 XiLink 后，def.source === 'thirdparty' 确认，协议走 legacy_set_param

A20.C5 · ModuleDef 持久化与工程加载

① 用户行为(User Action)

用户创建/修改模块后按 Ctrl+S 保存工程，下次打开同一 .xilink 工程文件，模块定义（包括三方模块引用）完整恢复。

② 系统响应(System Response)

保存：workspaceStore.save() 序列化所有 ModuleDef（含 uid + vendor + source 字段）至 workspace JSON。
加载：工程加载时 moduleDefStore.hydrate() 读取 ModuleDef 列表：
source: 'builtin' → 直接加载（内置库）
source: 'thirdparty' → 检查对应 uid 是否已注册，未注册则显示"缺失插件"警告
缺失三方模块时，XiLink 链路图该节点标注红色警告（不崩溃）。

③ 数据流(Data Flow)

保存：
  workspaceStore.save()
    → JSON.stringify({ modules: moduleDefStore.all(), ... })
    → writeFile(<project>.xilink)

加载：
  workspaceStore.load(<project>.xilink)
    → moduleDefStore.hydrate(data.modules)
    → foreach def: if thirdparty && !moduleDefStore.has(def.uid)
        → addMissingModuleWarning(def.uid)
    → XiLink: 渲染链路图（缺失节点红色标注）

④ 验收标准(Acceptance Criteria)

保存的 .xilink 文件包含 uid / vendor / source 字段（JSON 结构正确）
工程重新加载后，内置模块定义完整恢复
三方模块缺失时，链路图节点红色标注"⚠️ 插件未安装"，不崩溃
含三方模块的工程在另一台设备打开，显示缺失警告而非白屏（容错测试）

4. 备选方案(Alternatives Considered)

4.1 T4 · 仅做 DLL 路径，跳过 Python Sidecar

否决。Python Sidecar 已有 19 个分析端点基础设施，接入成本低。且用户原话"将自己的算法接入系统"明确包含 Python 场景（pysidecar 是现有一等公民）。

4.2 codegen 继续推迟

否决。ADR-04 已推迟一个季度，且 XiFore 核心价值（"自动生成 set/get"）无法交付就无法 release。本次必须落地。

4.3 T1 xml 退役后兼容层保留

否决。ADR-04 §3.6 已明确"用户原话：完全建立新架构，彻底删除"。保留兼容层会拖累代码质量并增加维护成本。

4.4 L3 动态加载（路径 B）代替 DLL 接入

暂缓。L3 路径 B（动态 ES module）属于前端扩展生态，工程量 15d+；DLL/Python 接入属于后端算法集成，更贴近 XiFore 产品定义，优先级更高。L3 路径 B 仍推迟至明年。

5. 后果(Consequences)

5.1 正面后果

用户核心价值解锁：14 个 L1 控件可拖拽搭建调音 UI，codegen 生成 C 头文件，完整"创建调音工具"闭环
代码库精简：删除 2 586+ 行 xml-tuning 遗留代码，types 层干净
算法生态开放：DLL + Python 两条路径，用户可接入任意 DSP 算法
Preset 自动化：_preset_schema.json 自动派生，XiTune 预设管理无需手写 schema
完成度提升：XiFore ~30% → ~80%

5.2 负面后果 / 风险

T1 退役破坏性大：9 处外部引用修改，容易遗漏 → 缓解：退役完成后 tsc --noEmit + grep 零命中校验
T4 DLL ABI 安全风险：用户上传的 DLL 可能包含恶意代码 → 缓解：白名单签名验证 + 沙箱进程隔离（后续迭代）
L1 控件 14 个工作量集中：2.5d 内完成 14 个 SFC → 缓解：P0 优先 7 个（旋钮/滑块×2/切换/瞬态/标签/下拉），P1 后 7 个分批
codegen 后端接口稳定性：CodegenService 依赖 ModuleDef schema 不变 → 缓解：ADR-04 contract freeze 约束

6. 实施计划(Implementation Plan)

6.1 fork 派发顺序

Day 0（立即）:
└── P0.A20.F1-xml-tuning-decommission（ClaudeB-XiForge · T1）
    依赖: 无 · 可立即派发
    工作量: 2d

Day 2:
└── P0.A20.F2-l1-widgets-batch1（ClaudeB-XiForge · T2 P0 7 个控件）
    依赖: T1 退役后 types/widget.ts 干净（F1 zombie）
    工作量: 1.5d

Day 3.5:
├── P0.A20.F3-l1-widgets-batch2（ClaudeB-XiForge · T2 P1 7 个控件）
│   依赖: F2 zombie（registry + auto-register 稳定后批量补齐）
│   工作量: 1d
└── P0.A20.F4-codegen-backend（ClaudeB-Backend · T3 后端 CodegenService）
    依赖: F1 zombie（types/module.ts 干净）
    工作量: 1d

Day 4.5:
└── P0.A20.F5-codegen-frontend（ClaudeB-XiForge · T3 前端 XiForgeCodeView + Monaco）
    依赖: F4 zombie（/api/codegen/generate 接口稳定）
    工作量: 1d

Day 5.5:
└── P1.A20.F6-algo-integration（ClaudeB-Backend + ClaudeB-XiForge · T4）
    依赖: F3 + F4 zombie（ModuleDef 完整 + 后端服务稳定）
    工作量: 2.5d

Day 8:
└── 收尾 · E2E 验收 · DASHBOARD 更新

6.2 fork 汇总表

Fork ID	负责方	任务	依赖	工作量
P0.A20.F1-xml-tuning-decommission	ClaudeB-XiForge	T1 退役	无	2d
P0.A20.F2-l1-widgets-batch1	ClaudeB-XiForge	T2 P0×7	F1	1.5d
P0.A20.F3-l1-widgets-batch2	ClaudeB-XiForge	T2 P1×7	F2	1d
P0.A20.F4-codegen-backend	ClaudeB-Backend	T3 后端	F1	1d
P0.A20.F5-codegen-frontend	ClaudeB-XiForge	T3 前端	F4	1d
P1.A20.F6-algo-integration	ClaudeB-Both	T4 算法接入 + 链路图节点容错(A20.C5)	F3+F4	2.8d
		总		9.3d

7. 开放问题(Open Questions)

#	问题	阻塞等级	当前假设
OQ1	L1 控件具体 API（emit 事件名 / props schema 格式）是否需要用户确认？	低（可先按 `change(value)` 统一）	统一 emit `change(value: number \\| boolean \\| string)`
OQ2	DLL ABI 沙箱隔离是否需要独立进程（安全隔离）？	中（影响 T4 实施方案）	本期仅做签名验证，沙箱推迟
OQ3	codegen 生成的 `.h` 是否需要 DSP 算法框架（如 JUCE / CMake）模板？	低（纯 C 足够）	纯 C 函数声明，不绑框架
OQ4	xml-tuning 退役后，现有测试 fixture（`public/xml-configs/`）如何处理？	低（删除即可）	直接删除，无兼容期

8. 变更记录(Changelog)

版本	日期	变更	作者
v0.1	2026-06-12	初稿，4 项任务 + 5 段业务契约 + 6 fork 派发计划	Copilot-AIOS

ADR-AIOS-20 · XiFore 完善

1. 上下文(Context)

1.1 用户原话存档(verbatim · 防漂移)

1.1.1 XiFore 产品定义(来自之前对话)

1.1.2 本 ADR 触发(2026-06-12)

1.2 现状调研(2026-06-12 真值)

1.2.1 代码结构现状

1.2.2 ADR-04 已落地的部分

1.2.3 ADR-04 推迟的部分（本 ADR 接手）

1.2.4 XiFore 完成度差距根因

1.3 用户的核心产品目标

2. 决议(Decision)

2.1 主决议 · 4 项任务

2.2 T1 · xml-tuning 整体退役

2.2.1 退役清单

2.2.2 外部引用清理（9 处）

2.2.3 类型完整性校验

2.3 T2 · L1 控件补齐（14 个核心控件）

2.3.1 L1 核心控件清单（本 ADR 实施 14 个）

2.3.2 控件元数据规范（WidgetMeta）

2.3.3 控件目录结构

2.3.4 McWidgetPropsPane 渲染适配

2.4 T3 · codegen C 头文件 + Preset Schema 自动派生

2.4.1 codegen 输出格式

2.4.2 codegen 触发路径

2.4.3 后端 CodegenService 边界

2.4.4 Preset Schema 自动派生规则

2.5 T4 · 算法接入路径

2.5.1 两条接入路径

2.5.2 ModuleCreator 接入 UI（ThirdPartyModuleDialog 重定位）

2.5.3 后端 DllImportService 边界

3. 业务行为契约(Business Behavior Contract)

A20.C1 · L1 控件拖入布局

① 用户行为(User Action)

② 系统响应(System Response)

③ 数据流(Data Flow)

④ 验收标准(Acceptance Criteria)

A20.C2 · codegen 生成 C 头文件

① 用户行为(User Action)

② 系统响应(System Response)

③ 数据流(Data Flow)

④ 验收标准(Acceptance Criteria)

A20.C3 · xml-tuning 退役后零回归

① 用户行为(User Action)

② 系统响应(System Response)

③ 数据流(Data Flow)

④ 验收标准(Acceptance Criteria)

A20.C4 · 三方算法接入（DLL 路径）

① 用户行为(User Action)

② 系统响应(System Response)

③ 数据流(Data Flow)

④ 验收标准(Acceptance Criteria)

A20.C5 · ModuleDef 持久化与工程加载

① 用户行为(User Action)

② 系统响应(System Response)

③ 数据流(Data Flow)

④ 验收标准(Acceptance Criteria)

4. 备选方案(Alternatives Considered)

4.1 T4 · 仅做 DLL 路径，跳过 Python Sidecar

4.2 codegen 继续推迟

4.3 T1 xml 退役后兼容层保留

4.4 L3 动态加载（路径 B）代替 DLL 接入

5. 后果(Consequences)

5.1 正面后果

5.2 负面后果 / 风险

6. 实施计划(Implementation Plan)

6.1 fork 派发顺序

6.2 fork 汇总表

7. 开放问题(Open Questions)

8. 变更记录(Changelog)

2.3.2 控件元数据规范（`WidgetMeta`）