跳转至
MIGRATED

XiForge 技术架构 v1.0 · 算法+UI 双自定义工坊

文档定位

1. 产品定位与目标

1.1 产品定位

XiForge = 羲音锻造台（Y2Q2 Alpha · Y3Q2 GA）。与 XiStudio 的差异：

维度 XiStudio XiForge
核心用户 算法工程师（搭建链路） 算法/UI 开发者（创造新模块 + 新 UI）
主要动作 用现有模块组装 创造新模块定义 + UI
产出物 可烧录的链路固件 可复用的模块 + 调音 UI + C/C++ 算法骨架
形态 独立 app（总入口） XiStudio 内嵌组件（主）+ 独立 dev server（辅）

1.2 核心能力

  1. Module Designer：可视化定义模块的输入/输出/参数 schema（不写代码就定义模块）
  2. Algo Code Generator：调用 XiMind 自动生成 C/C++ 算法骨架代码
  3. Tuning UI Designer：拖拽式设计调音 UI（产出 JSON 供 XiTune 加载）
  4. Preset Template Editor：定义参数预设模板
  5. Private Algo Publisher：发布自定义模块到 XiAlgo 私有仓库

1.3 与 MC 功能的关系

MC（Module Chain）是 XiForge 的前身。现有 MC 功能在 frontend_vue3/src/components/module-creator/ 已实现：

  • ✅ 模块定义的可视化编辑（简化版 Module Designer）
  • ✅ 模块参数 schema 定义
  • ✅ 测试运行（inject-signal → capture → compare）
  • ⏳ 代码自动生成（未实现 · XiForge 补齐）
  • ⏳ 调音 UI 设计器（未实现 · XiForge 补齐）
  • ⏳ 私有仓库发布（未实现 · XiForge 补齐）

XiForge 在 MC 基础上的增量：AI 代码生成 + UI 设计器 + 私有仓库 + 协议化（成为 XVST 插件 manifest 的前端）

1.4 版本矩阵

版本 时点 覆盖能力
Alpha Y2Q2 Module Designer（MC 迁移完成）+ Algo Code Generator MVP
Beta Y2Q4 Tuning UI Designer + Preset Template Editor
v1.0 GA Y3Q2 Private Algo Publisher + XiAlgo 私有仓库联通 + XiMind 深度集成

1.5 画布职责澄清（⭐ 关键设计差异）

XiForge 内含的 UI Designer 画布 与 XiStudio 的 LinkEditor 画布、SignalFlow 画布 是三套截然不同的画布，底层共享 @xi/ui-kit 的 Canvas 能力但职责严格分离。对标 LiveAmp 的调音 UI 运行时 + AudioWeaver 的 Inspector 工具。

维度 LinkEditor 画布（XiStudio · §D2-P1 §4.2） SignalFlow 画布（XiStudio · §D2-P1 §4.8） UI Designer 画布（XiForge · §4.3 · 本文）
归属 XiStudio 算法画布 XiStudio 信号画布 XiForge 调音面板画布
节点是什么 DSP 算法模块（EQ / Dyn / Mixer / ...） 信号源 + 信号运算节点 UI 控件（Knob / Slider / EQ 曲线 / 声场图 / CAN 信号指示等行业定制 widget）
连线含义 音频流（audio bus · 48kHz） control-rate 信号流（control bus） 参数绑定 / 布局关系（无"流"概念）
节点库 20 类算法分类 signalManagement 分类下 12 模块 UI widget 库 + 行业定制 widget（车载专用：转速表盘、CAN 信号灯、声场 2D 可视化等）
产出物 可烧录的 DSP 链路（audioGraph） 信号图谱 + 绑定映射（signalGraph + bindings） 调音 UI JSON（TuningUIDocument · 给 XiTune 加载渲染）
对标 AudioWeaver 主画布 LiveAmp Signal Flow 画布 LiveAmp 调音 UI 运行时 + AudioWeaver Inspector 工具
编辑者 算法工程师 车载系统集成工程师 产品经理 / 调音师 / UI 设计师

关键区分点：

  1. LinkEditor 管"声音怎么流" —— 节点是可执行的 DSP 算法，连线代表音频或控制信号的运行时流动
  2. SignalFlow 管"车辆信号怎么接入" —— 节点是信号运算，连线代表 control-rate 数据的运行时流动
  3. XiForge UI Designer 管"用户看到什么" —— 节点是 UI 控件，连线没有运行时含义，仅表示布局/组合/参数绑定关系

常见误解澄清：

误解 纠正
"XiForge 的画布是 LinkEditor 的简化版" ❌ 两者节点类型完全不同 · UI Designer 不画算法链路
"XiForge 的画布节点可以执行 DSP" ❌ UI 控件只负责渲染和参数绑定 · 不参与运行时音频/信号处理
"UI Designer 生成的是 Vue 组件代码" ❌ 输出是声明式 JSON（TuningUIDocument · 见 §4.3）· 由 XiTune 运行时动态渲染

2. 架构总览

2.1 XiForge 在 Monorepo 中的角色

graph TB
    subgraph Studio["xi-studio"]
        StudioShell["Shell"]
        ForgeRoute["/forge<br/>路由"]
    end

    subgraph Forge["xi-forge（本文）"]
        ForgePanel["<ForgePanel><br/>根组件（对外导出）"]
        ModuleDesigner["Module Designer"]
        CodeGen["Algo Code Generator"]
        UIDesigner["Tuning UI Designer"]
        PresetEditor["Preset Template Editor"]
        Publisher["Private Algo Publisher"]
    end

    subgraph Packages["packages/"]
        UIKit["@xi/ui-kit"]
        Protocol["@xi/protocol"]
        StoreCore["@xi/store-core"]
        DSPUtils["@xi/dsp-utils"]
        AISDK["@xi/ai-sdk"]
    end

    subgraph Backend["Backend"]
        CompileSvc["Compile Service<br/>（云端 C/C++ 编译）"]
        AlgoRepo["Private Algo Repo"]
    end

    StudioShell --> ForgeRoute --> ForgePanel
    ForgePanel --> ModuleDesigner
    ForgePanel --> CodeGen
    ForgePanel --> UIDesigner
    ForgePanel --> PresetEditor
    ForgePanel --> Publisher

    ModuleDesigner --> UIKit
    CodeGen --> AISDK
    CodeGen --> CompileSvc
    UIDesigner --> UIKit
    Publisher --> AlgoRepo
    Publisher --> Protocol

    ForgePanel -.useForgeStore.-> StoreCore

    classDef studio fill:#E6F7FF,stroke:#1890FF,stroke-width:2px
    classDef forge fill:#FFF4E6,stroke:#D4A574,stroke-width:3px,color:#1A2332
    classDef pkg fill:#F5F2EA,stroke:#6B7280,stroke-width:1px
    classDef be fill:#F0E6FA,stroke:#9D4EDD,stroke-width:2px
    class StudioShell,ForgeRoute studio
    class ForgePanel,ModuleDesigner,CodeGen,UIDesigner,PresetEditor,Publisher forge
    class UIKit,Protocol,StoreCore,DSPUtils,AISDK pkg
    class CompileSvc,AlgoRepo be
    class Studio,Forge,Packages xySgL4; class Backend xySgL3;

2.2 内嵌机制

XiForge 以组件库形式导出，被 XiStudio 以 <ForgePanel> 作为路由 /forge 的根组件嵌入：

// xi-studio 侧
import { ForgePanel } from '@xi-apps/xi-forge'

// router
{ path: 'forge', component: ForgePanel, meta: { title: 'XiForge 锻造台' } }

<ForgePanel> 内部不重新创建 Shell，直接使用 XiStudio 的 Shell 插槽（MainArea 内 + 共享 TopBar/SideNav）。Forge 特有的工具条通过 Shell 的扩展插槽注入。

2.3 独立开发模式

除内嵌外，XiForge 支持独立 dev server 用于组件独立开发调试：

pnpm -F xi-forge dev  # 启动 http://localhost:5174（独立 Storybook-like）

独立模式不产出生产 build，仅服务开发者。生产环境 Forge 只能通过 XiStudio 入口使用。

3. 目录结构

apps/xi-forge/
├── src/
│   ├── index.ts                       # 导出 <ForgePanel> 给 xi-studio 引用
│   ├── ForgePanel.vue                 # 根组件
│   ├── routes/                        # 内部子路由（Forge 作为 Shell 内嵌时用 nested router 或 local tabs）
│   │   ├── ModuleDesignerRoute.vue
│   │   ├── CodeGeneratorRoute.vue
│   │   ├── UIDesignerRoute.vue
│   │   ├── PresetEditorRoute.vue
│   │   └── PublisherRoute.vue
│   ├── components/
│   │   ├── module-designer/
│   │   │   ├── ModuleMetaForm.vue     # 模块元数据（名称/分类/图标）
│   │   │   ├── PortDefiner.vue        # 输入/输出端口定义
│   │   │   ├── ParamSchemaEditor.vue  # 参数 schema 编辑
│   │   │   └── ModulePreview.vue      # 预览模块在 LinkCanvas 的样子
│   │   ├── code-generator/
│   │   │   ├── CodePromptInput.vue    # 输入自然语言提示词
│   │   │   ├── CodePreview.vue        # Monaco Editor 显示生成代码
│   │   │   ├── CompileResult.vue      # 编译结果（错误/警告/产物）
│   │   │   └── IterationHistory.vue   # AI 生成历史版本对比
│   │   ├── ui-designer/
│   │   │   ├── UIDesignerCanvas.vue   # 画布（拖拽放置 widgets）
│   │   │   ├── WidgetPalette.vue      # widget 库（Knob/Slider/EQ/Meter 等）
│   │   │   ├── WidgetInspector.vue    # 选中 widget 属性编辑
│   │   │   └── UIJsonPreview.vue      # 生成 JSON 预览
│   │   ├── preset-editor/
│   │   │   ├── PresetList.vue
│   │   │   └── PresetParamEditor.vue
│   │   └── publisher/
│   │       ├── PublishWizard.vue      # 发布向导
│   │       ├── VersionSelector.vue
│   │       └── PublishHistory.vue
│   ├── stores/
│   │   ├── useForgeStore.ts           # 当前模块定义（draft）
│   │   ├── useCodeGenStore.ts         # 代码生成任务状态 + 历史
│   │   ├── useUIDesignStore.ts        # UI JSON 编辑状态
│   │   └── usePublisherStore.ts       # 发布记录
│   ├── services/
│   │   ├── forgeBackendApi.ts         # 与 Private Algo Repo 通信
│   │   ├── compileService.ts          # 提交代码到云端编译
│   │   └── aiCodeGen.ts               # 封装 @xi/ai-sdk 的代码生成调用
│   └── types/
│       ├── ModuleDefinition.ts        # XiForge 核心类型 · XVST manifest 子集
│       ├── UIWidget.ts                # UI 设计器 widget 类型
│       └── AlgoCodeTask.ts            # AI 代码生成任务类型
├── vite.config.ts                     # 仅开发用（无生产 build）
├── tsconfig.json
├── package.json                       # 导出 ForgePanel + 类型；不产出 dist/
└── README.md

关键注意：package.json 的 exports 字段只暴露 ForgePanel + 相关类型，不产出 bundle：

{
  "name": "@xi-apps/xi-forge",
  "type": "module",
  "main": "./src/index.ts",
  "exports": {
    ".": "./src/index.ts",
    "./types": "./src/types/index.ts"
  }
}

4. 核心模块详细设计

4.1 Module Designer（MC 迁移核心）

定位：无代码定义一个 DSP 模块。

视图层级：

<ModuleDesignerRoute>
  <SplitPane horizontal>
    <ModuleMetaForm />         # 顶部：名称/分类/图标/版本
    <SplitPane vertical>
      <PortDefiner />           # 左：输入/输出端口列表
      <ParamSchemaEditor />     # 中：参数 schema 定义
      <ModulePreview />         # 右：实时预览在 LinkCanvas 的样子
    </SplitPane>
    <ActionBar />               # 底：保存草稿 / 生成代码 / 发布
  </SplitPane>
</ModuleDesignerRoute>

核心数据结构：ModuleDefinition（XVST manifest 子集）

// types/ModuleDefinition.ts
export interface ModuleDefinition {
  // 元数据
  id: string                         // UUID
  name: string                       // 展示名
  category: string                   // 分类（EQ / Dynamic / Reverb / ...）
  iconUrl?: string
  version: string                    // SemVer
  author: string
  description: string
  license: string                    // MIT / Proprietary / ...

  // 技术定义
  ports: {
    inputs: PortDefinition[]
    outputs: PortDefinition[]
  }
  params: ParamDefinition[]
  presets?: PresetTemplate[]

  // 代码引用
  algoCode?: {
    language: 'c' | 'cpp'
    sourceUri: string                // 代码在 AlgoRepo 的位置
    compiledBinaryUri?: string       // 编译产物
    generatedByAI: boolean
    aiTaskId?: string
  }

  // UI 引用
  tuningUi?: {
    jsonUri: string                  // UI JSON 位置
  }

  // 发布状态
  status: 'draft' | 'published' | 'deprecated'
  publishedAt?: number
  publishedVersion?: string
}

export interface PortDefinition {
  id: string
  name: string
  type: 'audio' | 'control' | 'midi'
  channels?: number                  // 音频：1=mono, 2=stereo
  required: boolean
}

export interface ParamDefinition {
  key: string
  label: string
  type: 'number' | 'string' | 'boolean' | 'enum' | 'slider'
  defaultValue: any
  min?: number
  max?: number
  step?: number
  options?: Array<{ label: string; value: any }>
  unit?: string
  realtime: boolean                  // 是否支持运行态调整（热更参数）
  automation?: boolean               // 是否可被 XiTune 自动化
}

从 MC 迁移的能力：

MC 现有能力 XiForge Module Designer 归属 改动
ModuleCreator.vue 主界面 拆分到 ModuleMetaForm + ModulePreview 重构
参数定义 UI ParamSchemaEditor 迁移 + 扩展（新增 automation / realtime 字段）
模块测试（inject-signal） 移到 XiTest（不再归属 Forge） 切换归属
模块 JSON 导出 useForgeStore.saveAsDraft() + 格式升级到 ModuleDefinition 重构

4.2 Algo Code Generator

定位：根据模块定义自动生成 C/C++ 算法骨架，可一键编译验证。

核心流程：

sequenceDiagram
    participant UI as CodeGeneratorRoute
    participant Store as useCodeGenStore
    participant AI as @xi/ai-sdk
    participant Compile as Compile Service
    participant Storage as AlgoRepo

    UI->>Store: startGeneration(moduleDefinition, prompt)
    Store->>AI: session.sendStreaming(msg)
    Note over AI: XiMind 流式生成 C 代码
    AI-->>Store: 流式 code chunk
    Store-->>UI: 更新 CodePreview（Monaco）
    AI-->>Store: done
    UI->>Store: requestCompile()
    Store->>Compile: POST /api/compile { source, flags }
    Compile-->>Store: 编译任务 ID
    Store->>Compile: polling GET /api/compile/:id
    Compile-->>Store: { status: 'done', binaryUri, logs }
    Store->>Storage: 保存代码 + 产物引用
    Store-->>UI: 显示 CompileResult

Monaco Editor 集成：

<!-- components/code-generator/CodePreview.vue -->
<template>
  <MonacoEditor
    v-model:value="code"
    language="c"
    :options="{
      readOnly: generating,
      minimap: { enabled: false },
      fontSize: 13,
    }"
  />
</template>

AI 生成工具调用（function-calling）：

// services/aiCodeGen.ts
export async function generateAlgoCode(moduleDef: ModuleDefinition, userPrompt: string) {
  const session = aiSdk.createSession()
  const systemPrompt = buildCodeGenSystemPrompt(moduleDef)  // 注入模块上下文
  const userMsg = `${userPrompt}\n\n模块定义：${JSON.stringify(moduleDef, null, 2)}`

  const stream = session.sendStreaming({
    system: systemPrompt,
    content: userMsg,
  })

  let fullCode = ''
  for await (const delta of stream) {
    fullCode += delta.content
    yield { partial: fullCode }
  }
  return { code: fullCode, tokens: session.getUsage() }
}

迭代历史：用户可回看每次 AI 生成版本 + 自己的手动修改版本，形成 diff 对比。

4.3 Tuning UI Designer

定位：拖拽式设计调音面板，产出 JSON 供 XiTune 加载。

画布模型：

// types/UIWidget.ts
export interface TuningUIDocument {
  version: string
  layout: 'grid' | 'absolute'
  widgets: UIWidget[]
  theme?: {
    primaryColor?: string
    background?: string
  }
}

export interface UIWidget {
  id: string
  type: 'knob' | 'slider' | 'button' | 'switch' | 'eq-editor' | 'meter' | 'text-label' | 'group'
  position: { x: number; y: number; w: number; h: number }
  boundTo?: {                          // 绑定到模块参数
    moduleId: string
    paramKey: string
  }
  props: Record<string, any>           // widget-specific props（size / color / range / ...）
  children?: UIWidget[]                // 仅 group 类型
}

视图层级：

<UIDesignerRoute>
  <SplitPane vertical>
    <WidgetPalette />         # 左：widget 库
    <UIDesignerCanvas />      # 中：拖拽画布（使用 @xi/ui-kit 的 Draggable）
    <WidgetInspector />       # 右：选中 widget 属性
  </SplitPane>
  <UIJsonPreview />            # 底：实时 JSON 预览 + 导出
</UIDesignerRoute>

Widget 库：

类型 用途 关键 props
knob 旋钮 min, max, step, unit, boundTo
slider 滑块 同 knob + orientation
button 按钮 label, action
switch 开关 boundTo
eq-editor EQ 曲线 bands, frequency-range
meter 电平表 source (level-meter event)
text-label 文本 content, fontSize
group 分组容器 title, collapsible

契约：生成的 JSON 必须符合 TuningUIDocument schema，@xi/protocol 会定义 zod 校验。XiTune 加载时用同一 zod 校验。

4.4 Preset Template Editor

定位：为模块定义参数预设模板（如 "车载低音" / "流行人声" 等预置方案）。

核心数据：

export interface PresetTemplate {
  id: string
  name: string
  description: string
  tags: string[]
  params: Record<string, any>         // 参数覆盖值
  uiHints?: {
    iconUrl?: string
    category?: string
  }
}

UI：简单的表格式编辑器，左侧预设列表 + 右侧参数覆盖值（复用 <PropertyEditor>）。

4.5 Private Algo Publisher

定位：将完成的模块（定义 + 代码 + UI + preset）打包发布到客户私有的 XiAlgo 仓库。

发布向导流程：

stateDiagram-v2
    [*] --> ValidateModule
    ValidateModule --> FillMetadata: 校验通过
    ValidateModule --> [*]: 校验失败
    FillMetadata --> SelectVersion
    SelectVersion --> UploadAssets
    UploadAssets --> Signing: 上传 code + UI JSON + preset
    Signing --> Confirmation: 数字签名（可选）
    Confirmation --> Published: 用户确认发布
    Published --> [*]

后端契约（经 @xi/protocol/http/algo-library.ts）：

POST /api/algo-library/private/publish
Body: {
  moduleDefinition: ModuleDefinition
  algoCodeSource: string  // 或 binaryUri
  tuningUiJson: TuningUIDocument
  presets: PresetTemplate[]
  visibility: 'private' | 'organization' | 'public'
}
Response: {
  publishedVersion: string
  repositoryUri: string
  warnings?: string[]
}

版本管理：

  • 新模块：v0.1.0
  • 兼容变更（新增参数 / 优化算法）：minor bump
  • 破坏性变更（删参数 / 改端口）：major bump + 迁移指南必填

5. Store 设计

5.1 useForgeStore（核心）

export const useForgeStore = defineStore('xi-forge', () => {
  const currentModule = ref<ModuleDefinition | null>(null)
  const isDirty = ref(false)
  const drafts = ref<ModuleDefinition[]>([])  // 本地草稿列表

  function newModule(template?: Partial<ModuleDefinition>): void
  function updateMeta(meta: Partial<ModuleDefinition>): void
  function addPort(side: 'input' | 'output', port: PortDefinition): void
  function removePort(side: 'input' | 'output', id: string): void
  function addParam(param: ParamDefinition): void
  function removeParam(key: string): void
  function updateParam(key: string, patch: Partial<ParamDefinition>): void

  async function saveAsDraft(): Promise<void>   // 保存到本地 + 后端 drafts
  async function loadDraft(id: string): Promise<void>
  async function discardDraft(id: string): Promise<void>
  async function validate(): Promise<ValidationResult>

  return { currentModule, isDirty, drafts, ... }
})

5.2 useCodeGenStore

export const useCodeGenStore = defineStore('xi-forge-codegen', () => {
  const currentCode = ref<string>('')
  const generating = ref(false)
  const history = ref<CodeGenHistoryItem[]>([])
  const compileResult = ref<CompileResult | null>(null)

  async function generate(prompt: string): Promise<void>  // 调用 AI
  async function edit(code: string): void                  // 手动编辑
  async function compile(): Promise<CompileResult>
  function revertToVersion(historyId: string): void
  function forkFromVersion(historyId: string): void

  return { currentCode, generating, history, compileResult, ... }
})

5.3 useUIDesignStore

export const useUIDesignStore = defineStore('xi-forge-uidesign', () => {
  const document = ref<TuningUIDocument>(createEmptyUIDoc())
  const selectedId = ref<string | null>(null)

  function addWidget(type: UIWidget['type'], position: Position): void
  function removeWidget(id: string): void
  function updateWidget(id: string, patch: Partial<UIWidget>): void
  function reorderWidget(id: string, newIndex: number): void
  function selectWidget(id: string | null): void
  function exportJson(): TuningUIDocument

  return { document, selectedId, addWidget, ... }
})

5.4 usePublisherStore

export const usePublisherStore = defineStore('xi-forge-publisher', () => {
  const publishHistory = ref<PublishRecord[]>([])
  const publishing = ref(false)

  async function publish(visibility: 'private' | 'organization' | 'public'): Promise<PublishRecord>
  async function unpublish(versionId: string): Promise<void>
  async function listHistory(): Promise<PublishRecord[]>

  return { publishHistory, publishing, publish, ... }
})

6. 与 XiMind（ai-sdk）的集成

6.1 AI 驱动的 3 个场景

  1. 代码生成（核心）：Section 4.2 详述
  2. 参数 schema 辅助建议：用户描述模块用途，AI 建议应该暴露哪些参数
  3. UI 布局辅助生成：用户描述调音需求，AI 生成初始 UI JSON

6.2 Function Calling 工具

// 注册 Forge 特有的工具给 Copilot
session.registerTool({
  name: 'generate-algo-code',
  description: '根据当前模块定义生成 C/C++ 代码',
  parameters: z.object({ prompt: z.string() }),
  execute: async ({ prompt }) => forgeStore.triggerCodeGen(prompt),
})

session.registerTool({
  name: 'suggest-module-params',
  description: '为模块建议合理的参数集',
  parameters: z.object({ intent: z.string() }),
  execute: async ({ intent }) => suggestParams(intent, forgeStore.currentModule),
})

session.registerTool({
  name: 'generate-tuning-ui',
  description: '生成调音 UI 的初始布局',
  parameters: z.object({ style: z.string() }),
  execute: async ({ style }) => suggestUILayout(style, forgeStore.currentModule),
})

7. 与 XiStudio 的内嵌协作

7.1 数据传递

当用户在 XiStudio 中发布完一个新模块后：

sequenceDiagram
    participant User
    participant Forge as <ForgePanel>
    participant Publisher as usePublisherStore
    participant Bus as @xi/protocol XiBus
    participant Studio as XiStudio Shell
    participant AlgoLib as useAlgoLibStore

    User->>Forge: 点击"发布"
    Forge->>Publisher: publish()
    Publisher->>Publisher: 上传到后端
    Publisher->>Bus: emit('algo-library.refreshed', {})
    Bus-->>Studio: 接收事件
    Studio->>AlgoLib: refresh()
    AlgoLib-->>Studio: 更新 UI（新模块出现在 Link Editor 模块库）

7.2 状态隔离

  • Forge 的所有 Pinia store 使用 xi-forge-* 前缀命名空间，与 Studio store 不冲突
  • Forge 不直接读写 Studio 的 useLinkStore（避免耦合）
  • 跨 app 只走 @xi/protocol 的 XiBus 事件

8. 测试策略

8.1 单元测试

  • useForgeStore：模块定义的 CRUD / 校验
  • useCodeGenStore：AI 调用 mock + 流式响应处理
  • useUIDesignStore：widget 增删改查 + 导出 JSON

8.2 e2e 测试

核心场景：

场景 步骤
新建模块 → 填元数据 → 加端口 → 加参数 → 保存草稿 Forge 内完整流程
草稿 → 调 AI 生成代码 → 查看流式响应 mock AI 响应
代码生成完成 → 编译 → 查看编译日志 mock 编译服务
UI Designer 拖 3 个 widget → 绑定参数 → 导出 JSON 验证 JSON schema
发布模块 → Studio Link Editor 模块库刷新出现 跨 app 集成

8.3 契约测试

  • ModuleDefinition JSON 必须通过 @xi/protocol 的 zod schema
  • TuningUIDocument JSON 必须通过 @xi/protocol 的 zod schema，且能被 XiTune 加载

9. 性能要求

  • Module Designer 响应：输入延迟 < 50ms
  • Code Generator 首字节：< 1s（取决于 XiMind 后端）
  • UI Designer 拖拽：60 FPS
  • 编译反馈：提交后 < 3s 开始返回进度（取决于云端编译队列）

10. DQ 与风险

10.1 新增 DQ

DQ 编号 问题 建议
DQ-FORGE-01 ⭐ 生成的代码是否支持本地下载+本地编译（用户 2026-05-08 拍板 · 详见 D3-FE-ARCH-001 §9.1） 主方案:后端+DSP 工具链云端编译（默认路径 · POST /api/compile）· 特殊场景备选:本地脱离后端脚本编译（离线开发 / 私有化 / 客户 IT 限制 · Y2 Beta 提供 xi-forge-cli 命令行工具 + 离线工具链打包）· XiForge UI 在"编译目标"下拉区分 Cloud / Local 两种模式 · 两种模式产出物格式一致（ELF/BIN + 调试符号）
DQ-FORGE-02 Tuning UI Designer 生成的 JSON 是否允许 custom script Alpha 不允许（仅声明式）；Beta 若有需求再加
DQ-FORGE-03 Private Algo Repo 的权限模型（组织内 / 团队 / 个人） 按 SSO 租户隔离 · 详见 DQ-05
DQ-FORGE-04 XVST 协议在 Forge 发布时是否强制校验 Alpha 校验基础字段；Beta 全量 XVST v0.1
DQ-FORGE-05 AI 生成代码的 License 与知识产权归属 默认客户所有 · 协议条款待法务确认

10.2 继承的 DQ

  • DQ-03（代码编译位置）· 已建议云端编译
  • DQ-07（ai-sdk 契约定版）

10.3 风险

风险 缓解
AI 生成代码质量不达标导致用户放弃 双轨：AI 草稿 + 人工完善；提供高质量模板库作 few-shot
UI Designer 表达力不够导致回退到手写 JSON 广度优于深度；允许高级用户 advanced mode 直接编辑 JSON
云端编译延迟影响体验 编译结果缓存；常用模板预编译
XVST 协议变更影响已发布模块兼容性 Marketplace 中做版本适配层；废弃老协议需提前 90 天公告

11. 与 MC 的对照矩阵

维度 现有 MC XiForge
位置 frontend_vue3/src/components/module-creator/ apps/xi-forge/
模块定义结构 简化 JSON 完整 ModuleDefinition（XVST manifest 子集）
代码生成 ❌ 无 ✅ AI 驱动
UI 设计器 ❌ 无 ✅ 拖拽式 + JSON 导出
预设模板 ⏳ 部分 ✅ 完整编辑器
私有仓库发布 ❌ 无 ✅ 向导 + 版本管理
AI 集成 ❌ 无 ✅ 代码/schema/UI 三场景
运行态测试 ✅ 有（inject-signal） ❌ 移到 XiTest
XVST 协议兼容 ❌ 无 ✅ 从 Alpha 起

12. 版本与变更记录

版本 日期 作者 说明
v1.0 2026-05-08 work-cline 初稿 · MC → XiForge 完整升级路径 + 5 大模块 + AI 集成三场景
v1.1 2026-05-08 work-cline 用户反馈迭代:§1.5 新增画布职责澄清章节（XiForge UI Designer vs XiStudio LinkEditor vs SignalFlow 三画布差异矩阵 + 常见误解澄清 · 对标 LiveAmp 调音 UI 运行时 + AudioWeaver Inspector）+ §10.1 DQ-FORGE-01 最终决策（云端主 + 本地备 · Y2 Beta 提供 xi-forge-cli + 离线工具链）

附录 A · 引用