MIGRATED

XiMind 技术架构 v1.0 · 云端 AI Agent SDK

文档定位

产品定位：Xisound L5 层"羲音智脑"——贯穿六层的云端 AI Agent · Xisound 的"中央大脑"
形态：不是独立 app，以 @xi/ai-sdk package 形式被所有 6 个 app 引用
上游：D0 产品矩阵 V1.1 §3.1 · D3-FE-ARCH-001 §5.6 · D3-FE-ARCH-003 §6
下游：D3-FE-PLAN-010 ai-sdk 集成 + Copilot 落地

1. 产品定位与目标

1.1 产品定位

XiMind = 羲音智脑（Y2H2 内测 · Y3H1 商用 GA · Y3H2 1000+ 车型知识沉淀）。Xisound 的中央大脑:

自然语言驱动的算法链路自动搭建
算法代码自动生成（调用 XiAlgo + XiForge）
自动化测试编排（驱动 XiTest）
智能调音决策（驱动 XiTune）
跨项目知识沉淀与推荐
车端回传数据学习与下一代优化

1.2 核心能力（ai-sdk 层）

Copilot 会话:上下文管理 · 流式输出 · 中断重试 · 多轮对话
Function Calling:AI 驱动前端操作（7 个标准工具 · §4.3）
RAG 检索:XiAlgo IP 库 · 项目历史 · 车型知识库
多模态输入:文本 · 频谱图 · 音频片段 · 截图
跨 app handoff:Studio 提问 → AI 建议 → 自动在 Tune 打开对应 session
UI 组件:<CopilotDrawer> / <InlineAssist> / <VoiceInput>（交付给 @xi/ui-kit）

1.3 版本矩阵

版本	时点	覆盖能力
v0.1 内部契约	Y1Q3	后端 SSE 契约初稿 · 前端 ai-sdk mock 实现 · 5 个基础工具
v0.5 开发者内测	Y2H1	SDK v0.5 · RAG 检索 · 多模态 · 完整工具集
v0.9 内测商用	Y2H2	10 个邀请客户 · 跨 app handoff · 错误恢复
v1.0 GA	Y3H1	商用发布 · 自然语言驱动 · 契约冻结
v2.0	Y3H2	1000+ 车型知识沉淀 · AI 自动调音 · 车端回传学习

1.4 商业模式（引用 D0 产品矩阵）

SaaS 订阅:分 Community / Pro / Enterprise 三档
Token 计费:按 AI 调用次数计费
私有化授权:大客户 Tier1 / OEM 部署到其内网

1.5 重要约束（为什么 XiMind 不是独立 app）

遵循 D3-FE-ARCH-001 §5.6 架构决策:

XiMind 是 packages/ai-sdk,不是 apps/xi-mind
不存在独立的 xi-mind.xisound.com 域名
用户不会"打开 XiMind"·XiMind 始终嵌入在 XiStudio / XiTune / XiTest / XiProbe / XiForge 的 Copilot 抽屉中
后端 XiMind Service 独立部署在 ai.xisound.com,但前端用户感知不到

2. 架构总览

2.1 @xi/ai-sdk 在 Monorepo 中的角色

graph TB
    subgraph Apps["apps/（6 个 app 都引用 ai-sdk）"]
        Studio[xi-studio]
        Forge[xi-forge]
        Tune[xi-tune]
        Test[xi-test]
        Probe[xi-probe]
        VST[xi-vst]
    end

    subgraph SDK["packages/ai-sdk（本文核心）"]
        Client[XiMindClient]
        Session[Session 会话管理]
        Tools[ToolRegistry 工具注册]
        RAG[RAGClient 检索]
        MM[Multimodal 多模态]
        Composables[Vue Composables]
        Components["Vue 组件<br/>CopilotDrawer / InlineAssist / VoiceInput"]
    end

    subgraph Protocol["@xi/protocol"]
        AIEvents[ai-events WebSocket]
        AIAPI[ai HTTP API]
    end

    subgraph Backend["XiMind Backend<br/>ai.xisound.com"]
        APIGateway[API Gateway]
        ChatSvc[Chat Service<br/>SSE streaming]
        RAGSvc[RAG Service<br/>Vector DB + Elasticsearch]
        ToolExec[Tool Execution Service]
        ModelRouter[Model Router<br/>GPT-4/Claude/Qwen/Deepseek]
    end

    Apps --> SDK
    SDK --> Protocol
    Protocol --> APIGateway
    APIGateway --> ChatSvc
    APIGateway --> RAGSvc
    APIGateway --> ToolExec
    ChatSvc --> ModelRouter

    classDef app fill:#E6F7FF,stroke:#1890FF,stroke-width:2px
    classDef sdk fill:#FFF4E6,stroke:#D4A574,stroke-width:3px
    classDef protocol fill:#F5F2EA,stroke:#6B7280,stroke-width:1px
    classDef be fill:#F0E6FA,stroke:#9D4EDD,stroke-width:2px
    class Studio,Forge,Tune,Test,Probe,VST app
    class Client,Session,Tools,RAG,MM,Composables,Components sdk
    class AIEvents,AIAPI protocol
    class APIGateway,ChatSvc,RAGSvc,ToolExec,ModelRouter be
    class Apps xySgL4; class SDK,Backend xySgL5; class Protocol xySgL3;

2.2 技术栈

层	选型	说明
SDK 语言	TypeScript 5.3+	强类型
传输	SSE(Server-Sent Events)	单向流式 · 调试简单 · 首选（DQ-AI-01）
传输（备选）	WebSocket	Y3+ 若需双向交互（语音流式）
Schema 校验	zod	运行时校验 AI 返回
UI 组件	Vue 3 Composables + components	供 @xi/ui-kit 引用
后端	C# ASP.NET Core（统一后端栈）	或 Python FastAPI（如果 AI 生态更依赖 Python）
模型调用	OpenAI / Anthropic / Alibaba Tongyi / Deepseek	可配置路由
向量 DB	Milvus / Weaviate / PostgreSQL pgvector	检索历史方案
全文检索	Elasticsearch / Meilisearch	搜索 XiAlgo 算法库

3. SDK 目录结构（packages/ai-sdk/）

packages/ai-sdk/
├── src/
│   ├── client/
│   │   ├── XiMindClient.ts       # 核心 client 类
│   │   ├── transport.ts          # SSE 传输层
│   │   └── auth.ts               # Token 管理
│   ├── session/
│   │   ├── Session.ts            # 单个对话会话
│   │   ├── context.ts            # 上下文管理
│   │   ├── streaming.ts          # 流式响应处理
│   │   └── abort.ts              # 中断机制
│   ├── tools/
│   │   ├── ToolRegistry.ts       # function-calling 工具注册表
│   │   ├── builtin-tools.ts      # 内置工具（open-app / update-link 等 7 个）
│   │   └── types.ts
│   ├── rag/
│   │   ├── RAGClient.ts          # 检索 XiAlgo / 项目知识
│   │   ├── types.ts
│   │   └── embeddings.ts
│   ├── multimodal/
│   │   ├── spectrum-input.ts     # 频谱图转 base64 发送
│   │   ├── audio-input.ts        # 音频片段
│   │   ├── image-input.ts        # 截图 / UI mockup
│   │   └── voice-input.ts        # 语音转文字（Web Speech API）
│   ├── composables/
│   │   ├── useCopilot.ts         # 主 Copilot 接口
│   │   ├── useCopilotSession.ts
│   │   ├── useAIGenerate.ts      # XiForge 代码生成
│   │   ├── useAIAutoTune.ts      # XiTune 自动调音
│   │   └── useRAG.ts
│   ├── components/
│   │   ├── CopilotDrawer.vue     # 右侧抽屉
│   │   ├── InlineAssist.vue      # 内联 AI 按钮
│   │   ├── VoiceInput.vue        # 麦克风语音输入
│   │   └── ToolCallDisplay.vue   # 展示 AI 正在调用的工具
│   ├── cache/
│   │   └── session-cache.ts      # localStorage 会话缓存
│   └── index.ts
├── tests/
├── package.json
├── tsconfig.json
└── README.md

4. 核心 API 详细设计

4.1 XiMindClient

// client/XiMindClient.ts
export interface XiMindClientOptions {
  endpoint: string                // https://ai.xisound.com/api/v1
  tenantId: string
  getToken: () => Promise<string>  // 延迟获取,支持 token refresh
  defaultModel?: string            // 如 "ximind-v1.0"
  defaultTemperature?: number
  timeout?: number                 // ms
}

export class XiMindClient {
  constructor(options: XiMindClientOptions)

  createSession(opts?: SessionOptions): Session
  listModels(): Promise<Model[]>
  getUsage(): Promise<UsageStats>
  estimateTokens(messages: Message[]): number   // 本地估算(避免超限)
}

export interface SessionOptions {
  systemPrompt?: string
  model?: string
  temperature?: number
  maxTokens?: number
  tools?: Tool[]
  context?: () => Record<string, any>  // 动态上下文(如当前 app / 工程 / 链路)
}

4.2 Session

// session/Session.ts
export class Session {
  readonly id: string
  readonly app: string

  // 基础对话
  async send(message: UserMessage): Promise<AssistantMessage>
  async sendStreaming(message: UserMessage): AsyncIterable<AssistantDelta>

  // 工具管理
  registerTool(tool: Tool): void
  unregisterTool(toolName: string): void
  listTools(): Tool[]

  // 上下文 / 历史
  getHistory(): Message[]
  clearHistory(): void
  abort(): void               // 中断正在进行的流式请求

  // 跨 app handoff
  async handoff(targetApp: string, intent: string, context: any): Promise<void>

  // 持久化
  persist(): void              // 存 localStorage
  restore(): void
}

export interface UserMessage {
  role: 'user'
  content: string | Array<TextPart | ImagePart | AudioPart | SpectrumPart>
}

export interface AssistantMessage {
  role: 'assistant'
  content: string
  toolCalls?: ToolCall[]
  usage?: { promptTokens: number; completionTokens: number }
}

export interface AssistantDelta {
  content?: string              // 流式文本增量
  toolCall?: ToolCall           // 流式工具调用
  finishReason?: 'stop' | 'length' | 'tool_calls' | 'content_filter'
}

4.3 Function Calling 标准工具集（7 个）

工具名	用途	使用方	参数
`open-app`	在指定 app 打开（走 deep-link）	所有 apps	app + intent + context
`update-link`	修改当前链路（增删模块/改连接）	Studio / Forge	moduleId / operation / payload
`update-param`	修改模块参数	Studio / Tune / Forge	moduleId + paramKey + value
`bind-param-to-signal` ⭐	绑定算法参数到 Signal Flow 信号（LiveAmp 风格）	Studio	moduleId + paramKey + signalName + mode
`run-measurement`	触发 XiTune 测量	Tune	sessionId + position + signalType
`run-test-suite`	运行 XiTest 用例	Test	suiteId + autoStart
`search-algo-library`	检索 XiAlgo 算法库	所有 apps	query + category + certification
`generate-code`	生成算法代码	Forge	moduleDef + prompt

工具定义示例:

// tools/builtin-tools.ts
import { z } from 'zod'
import type { Tool } from './types'

export const openAppTool: Tool = {
  name: 'open-app',
  description: '在指定 app 中打开 · 通过 deep-link 跳转',
  parameters: z.object({
    app: z.enum(['xi-studio', 'xi-forge', 'xi-tune', 'xi-test', 'xi-probe']),
    intent: z.string(),
    context: z.record(z.any()).optional(),
  }),
  execute: async ({ app, intent, context }) => {
    const url = buildDeepLink({ app, route: `/intent/${intent}`, params: context || {} })
    window.open(url, '_blank')
    return { success: true, url }
  },
}

export const bindParamToSignalTool: Tool = {
  name: 'bind-param-to-signal',
  description: '将算法模块的参数绑定到 Signal Flow 画布的信号(LiveAmp 风格)',
  parameters: z.object({
    moduleId: z.string(),
    paramKey: z.string(),
    signalName: z.string(),       // 如 "vehicle.speed.smoothed"
    mode: z.enum(['absolute', 'offset', 'multiplier']).default('absolute'),
  }),
  execute: async (params) => {
    const signalStore = useSignalFlowStore()
    signalStore.addBinding({ ...params, fallbackToDefault: true })
    return { success: true }
  },
}

4.4 RAG 检索

// rag/RAGClient.ts
export interface RAGQueryOptions {
  collection: 'xialgo' | 'projects' | 'vehicles' | 'tuning-presets'
  query: string
  filters?: Record<string, any>
  limit?: number              // 默认 10
  minScore?: number           // 0-1,默认 0.7
}

export class RAGClient {
  async search(options: RAGQueryOptions): Promise<RAGResult[]>
  async similaritySearch(embedding: number[], collection: string): Promise<RAGResult[]>
}

export interface RAGResult {
  id: string
  content: string
  metadata: Record<string, any>
  score: number
  source: string              // "xialgo://eq-parametric-v2" 等
}

4.5 多模态输入

// multimodal/spectrum-input.ts
export async function spectrumToPart(magnitudeDb: Float32Array, sampleRate: number): Promise<SpectrumPart> {
  // 用 @xi/dsp-utils 生成频谱图 PNG · base64 编码
  const canvas = renderSpectrumToCanvas(magnitudeDb, sampleRate)
  const blob = await canvas.convertToBlob({ type: 'image/png' })
  const base64 = await blobToBase64(blob)
  return {
    type: 'spectrum',
    mimeType: 'image/png',
    data: base64,
    metadata: { sampleRate, bins: magnitudeDb.length },
  }
}

典型用法（XiTune）：

// "帮我看看这个频响哪里有问题"
const spectrum = await captureCurrentSpectrum()
const part = await spectrumToPart(spectrum.magnitudeDb, 48000)
const reply = await session.send({
  role: 'user',
  content: [
    { type: 'text', text: '帮我看看这个频响哪里有问题' },
    part,
  ],
})
// AI 返回: "低频 80Hz 附近有 6dB 过冲,建议降低 XiAlgo-FX.LowShelfEQ.gain 从 +8dB 到 +2dB"

4.6 Vue Composables（给 apps 用）

// composables/useCopilot.ts
export function useCopilot(options?: UseCopilotOptions) {
  const session = ref<Session | null>(null)
  const messages = ref<Message[]>([])
  const sending = ref(false)

  // 初始化 session
  onMounted(async () => {
    const client = inject<XiMindClient>('xiMindClient')!
    session.value = client.createSession({
      systemPrompt: options?.systemPrompt,
      context: options?.context,
    })
    // 注册通用工具
    session.value.registerTool(openAppTool)
    session.value.registerTool(bindParamToSignalTool)
    // 允许 app 添加专有工具
    options?.tools?.forEach(t => session.value!.registerTool(t))
  })

  async function send(text: string): Promise<void> {
    if (!session.value) return
    sending.value = true
    messages.value.push({ role: 'user', content: text })
    try {
      const stream = session.value.sendStreaming({ role: 'user', content: text })
      const assistantMsg: AssistantMessage = { role: 'assistant', content: '' }
      messages.value.push(assistantMsg)
      for await (const delta of stream) {
        if (delta.content) assistantMsg.content += delta.content
        if (delta.toolCall) await handleToolCall(delta.toolCall)
      }
    } finally {
      sending.value = false
    }
  }

  function abort(): void {
    session.value?.abort()
    sending.value = false
  }

  return { session, messages, sending, send, abort }
}

4.7 跨 app Handoff

sequenceDiagram
    participant User
    participant Studio as XiStudio Copilot
    participant SDK as @xi/ai-sdk
    participant BE as XiMind Backend
    participant Tune as XiTune

    User->>Studio: "帮我把这个工程调音"
    Studio->>SDK: session.sendStreaming(msg)
    SDK->>BE: POST /api/ai/chat (stream)
    BE-->>SDK: toolCall: open-app(app=xi-tune, intent=auto-tune, ctx={projectId})
    SDK->>SDK: 执行 openAppTool · 生成 deep-link · 新 tab 打开
    SDK->>Tune: xi://xi-tune/intent/auto-tune?projectId=xxx&token=yyy
    Tune->>Tune: 解析 deep-link + 换 token + 加载工程
    Tune->>SDK: 继续同一 session(通过 sessionId 传递)
    SDK->>BE: session.resume(sessionId)
    BE-->>Tune: AI 继续工作(基于 Studio 之前的上下文)
    Tune-->>User: AI 在 XiTune 中直接执行自动调音

实现要点:

session 的 id 在跨 app 时通过 deep-link 的 context 参数传递
后端 Session Service 存 session state · 允许多 app 读写同一 session
完成后 Tune 可以用 session.handoff('xi-studio', 'tuning-completed', {...}) 回传结果

5. 后端 API 契约（HTTP + SSE）

5.1 HTTP API（@xi/protocol/http/ai.ts）

端点	方法	用途
`/api/ai/chat`	POST (SSE)	发送消息 · 流式返回
`/api/ai/sessions`	POST	创建 session
`/api/ai/sessions/:id`	GET/DELETE	获取 / 删除 session
`/api/ai/sessions/:id/handoff`	POST	跨 app handoff
`/api/ai/rag/search`	POST	RAG 检索
`/api/ai/tools/execute`	POST	工具执行（仅后端侧工具）
`/api/ai/models`	GET	可用模型列表
`/api/ai/usage`	GET	Token 用量

5.2 SSE 事件流

data: {"type":"delta","content":"根据您的链路..."}
data: {"type":"delta","content":"建议增加 EQ 模块"}
data: {"type":"tool_call","id":"call_001","name":"update-link","arguments":"{...}"}
data: {"type":"done","finishReason":"tool_calls","usage":{"prompt":120,"completion":45}}

5.3 契约版本演进

版本	时点	变更
v0.1	Y1Q3	基础会话 + 5 工具 + SSE · 内部 dog-food
v0.5	Y2H2	完整 7 工具 + RAG + 多模态 · 开发者内测
v1.0	Y3H1	商用发布 · 契约冻结
v1.x	Y3H2+	向后兼容小版本

6. 各 app 使用场景

6.1 XiStudio 场景

场景	触发	AI 工具链
搭建新链路	"帮我做个车载声浪链路"	search-algo-library → update-link(add: Oscillator, Mapping, Smooth)
调音	"低频太闷"	update-param(lowShelf.gain=-3) + open-app(tune, auto-tune)
信号绑定	"让 EQ 随车速调整"	bind-param-to-signal(moduleId, paramKey='lowShelf.gain', signalName='vehicle.speed')

6.2 XiForge 场景

场景	触发	AI 工具链
代码生成	"生成一个限幅器"	generate-code(moduleDef + prompt)
参数建议	"这个模块该暴露哪些参数"	suggest-module-params(moduleDef)
UI 布局	"生成一个电子管风格的 UI"	generate-tuning-ui(style='vintage-tube')

6.3 XiTune 场景

场景	触发	AI 工具链
自动调音	"根据测量数据调音"	run-measurement + AI 分析 + update-param × N
频响诊断	"这个频响有什么问题"(附图)	多模态输入 spectrum → AI 分析

6.4 XiTest 场景

场景	触发	AI 工具链
生成测试用例	"为新 EQ 模块生成单测"	基于模块定义 AI 生成 assertion
失败根因	"这批用例为什么挂了"(附日志)	多模态 + RAG 历史失败模式

6.5 XiProbe 场景

场景	触发	AI 工具链
参数建议	"测这个喇叭最需要关注什么指标"	RAG 检索历史 + 生成测试流程
报告解读	"这份 THD 报告是否合格"(附图)	多模态输入 → AI 判断

6.6 XiVST 场景

场景	触发	AI 工具链
插件推荐	"我需要一个混响插件"	search-algo-library + 推荐 Top-3
开发者问答	"XVST SDK 怎么处理 Multi-rate"	RAG 检索 SDK 文档

7. 安全与合规

项	策略
Token 安全	ai-sdk 永不直接调用外部 AI · 所有调用经 Xisound 后端代理 · 模型 API Key 仅后端 Vault
数据隐私	用户输入可选"仅会话模式"(不用于训练) · 默认开启
内容安全	后端过滤器(敏感词 / 提示注入 / jailbreak)· OpenAI content policy
审计日志	每次 AI 调用记录 tenantId / userId / model / tokens · 用于计费和追溯
个人数据处理	GDPR / 个人信息保护法合规 · 用户可删除 session 历史
模型幻觉缓解	所有工具调用结果需用户确认才执行破坏性操作(update-link 增删模块前弹框)

8. 监控指标

维度	指标	目标
性能	首字节时间 FTT	< 1s
	流式吞吐	100+ token/s
	工具调用耗时	< 500ms（含网络）
质量	工具调用成功率	> 95%
	会话满意度(用户点赞/踩)	> 80%
	代码生成一次过编译率（XiForge）	> 70%
业务	DAU	Y3H1 1000+ · Y3H2 5000+
	Tokens 消耗/月	Y3H1 100M+ · Y3H2 1B+
	月 ARPU	Y3H1 ¥200 · Y3H2 ¥500

9. DQ 与风险

9.1 新增 DQ

DQ 编号	问题	建议
DQ-MIND-01	模型路由策略（用户不感知选哪个）	后端根据任务类型自动路由:代码生成→Deepseek/GPT-4 · 对话→Qwen · 多模态→Claude
DQ-MIND-02	Fine-tune 自有模型时机	Y3 积累 1000+ 车型数据后 · 训练 XiMind-v1.0 私有模型
DQ-MIND-03	私有化部署方案	Y3 提供 Docker + Ollama · 大客户内网部署 · 配置本地模型
DQ-MIND-04	离线 / 弱网模式	ai-sdk 自带降级 · 离线时禁用 Copilot 按钮 + 友好提示
DQ-MIND-05	用户自定义工具（BYOT）	v2.0 支持开发者声明自定义工具给 AI 用 · 走 Marketplace 审核

9.2 风险

风险	缓解
AI 输出错误指令（如删错模块）	所有破坏性工具调用需用户二次确认 · 支持 undo
模型 API 成本爆炸	Token 配额限流 · 免费额度 + 付费递增 · 后端缓存常见 query
跨 app handoff 失败	session 状态持久化 + 断点续传 · handoff 失败自动回退 Studio
多语言(中/英)质量不均	默认走 Qwen（中文强）· 英文路由到 Claude · RAG 分语言库
模型版本升级破坏体验	灰度发布 · A/B 测试 · 用户可手动回退到上一版

10. 版本与变更记录

版本	日期	作者	说明
v1.0	2026-05-08	work-cline	初稿 · ai-sdk 架构 · 7 function-calling 工具 · RAG + 多模态 · 跨 app handoff · 后端契约 · 6 app 使用场景

XiMind 技术架构 v1.0 · 云端 AI Agent SDK

1. 产品定位与目标

1.1 产品定位

1.2 核心能力（ai-sdk 层）

1.3 版本矩阵

1.4 商业模式（引用 D0 产品矩阵）

1.5 重要约束（为什么 XiMind 不是独立 app）

2. 架构总览

2.1 @xi/ai-sdk 在 Monorepo 中的角色

2.2 技术栈

3. SDK 目录结构（packages/ai-sdk/）

4. 核心 API 详细设计

4.1 XiMindClient

4.2 Session

4.3 Function Calling 标准工具集（7 个）

4.4 RAG 检索

4.5 多模态输入

4.6 Vue Composables（给 apps 用）

4.7 跨 app Handoff

5. 后端 API 契约（HTTP + SSE）

5.1 HTTP API（@xi/protocol/http/ai.ts）

5.2 SSE 事件流

5.3 契约版本演进

6. 各 app 使用场景

6.1 XiStudio 场景

6.2 XiForge 场景

6.3 XiTune 场景

6.4 XiTest 场景

6.5 XiProbe 场景

6.6 XiVST 场景

7. 安全与合规

8. 监控指标

9. DQ 与风险

9.1 新增 DQ

9.2 风险

10. 版本与变更记录

附录 A · 引用