XiForge · Tech Architecture

XiForge 技术架构设计 v1.0

五层架构 · CodeGen · UIEditor · 集成 · AI 联动

文档编号：D2-P9-TECH-001 · 版本：v1.0 · 发布：2026-05-05

让每一段算法都可生成 · 让每一个品牌都有专属面板

5

架构分层

Electron

桌面运行时

Vue 3

前端框架

XiForge 技术架构设计 v1.0

摘要

本文档是 XiForge 开发者平台的技术架构详设，与 spec.md 互补：spec 定义技术规格契约，本文阐述架构分层、CodeGen 内部机制、UIEditor 画布架构、XiStudio 插件桥、XiMind AI 联动、性能与安全策略。 目标读者：工具软件架构师、Electron / Vue 工程师、OEM 工具工程师、Tier1 算法架构师。

工具平台架构红线

• 本地优先：所有核心功能（CodeGen / UIEditor）必须可完全离线运行
• AI 可降级：XiMind 不可用时不阻塞任何核心流程
• 仓库兼容：私有仓库协议基于 标准 Git，客户可自建 Git Server
• Electron 沙箱：严格遵循 Electron 安全最佳实践（contextIsolation + nodeIntegration=false）

---

1. 架构原则

XiForge 架构五条原则

1. 离线可用：核心工具链完全本地运行 · 无网也能开发
2. 双子系统解耦：CodeGen 与 UIEditor 各自独立，可单独运行
3. 标准模板驱动：所有代码生成基于 Handlebars + JSON Schema，无魔法
4. 插件化：与 XiStudio 通过 JSON-RPC 2.0 标准协议通信，松耦合
5. AI 增强：XiMind 是加速器而非前置条件

---

2. 总体分层

2.1 五层架构

graph TB
    L5[L5 · Shell 层<br/>Electron Main · 窗口 · 菜单]
    L4[L4 · UI 层<br/>Vue 3 + Tailwind · xy-design-system]
    L3[L3 · 子系统层<br/>CodeGen · UIEditor · Repo · Plugin · AI]
    L2[L2 · 后端服务层<br/>Fastify · Tree-sitter · Vue Builder]
    L1[L1 · 基础设施层<br/>Node.js · Git · 文件系统 · 网络]

    L5 --> L4
    L4 --> L3
    L3 --> L2
    L2 --> L1

    class L5 xyL5
    class L4 xyL4
    class L3 xyL3
    class L2 xyL2
    class L1 xyL1

2.2 各层职责

层	职责	进程	主要技术
L5 Shell	窗口 / 菜单 / 生命周期	Main 进程	Electron
L4 UI	前端渲染 / 交互	Renderer 进程	Vue 3 + TS + Pinia
L3 子系统	CodeGen / UIEditor / Repo / Plugin / AI	Renderer + Backend	TypeScript
L2 后端服务	HTTP API / AST 解析 / 文件 IO	Backend 进程（Node.js）	Fastify + Tree-sitter
L1 基础设施	OS / 文件 / 网络 / Git	OS 层	Node.js 20+

2.3 进程模型

graph TB
    Main[Main 进程<br/>Node.js · Electron]
    Renderer[Renderer 进程<br/>Chromium · Vue 3]
    Backend[Backend 进程<br/>Node.js + Fastify]

    Main <--IPC--> Renderer
    Main <--Named Pipe--> Backend
    Renderer <--HTTP localhost--> Backend

    class Main xyL5
    class Renderer xyL4
    class Backend xyL2

• Main：窗口管理 + 系统菜单 + 文件对话框
• Renderer：UI 渲染 + 用户交互（严格沙箱）
• Backend：所有重量级工作（AST / 编译预检 / Git 操作 / AI 调用）

---

3. CodeGen 子系统

3.1 CodeGen 架构

graph LR
    UIReq[UI 请求] --> API[CodeGen REST API]
    API --> Val[JSON Schema 验证]
    Val --> Tpl[模板加载器]
    Tpl --> HB[Handlebars 渲染]
    HB --> AST[Tree-sitter AST 校验]
    AST --> Fmt[Clang-format / Prettier]
    Fmt --> Out[文件写入]
    Out --> Res[响应]

    AI[XiMind AI · 可选] -.注入.-> HB

    class UIReq xyL4
    class API,Val xyL3
    class Tpl,HB xyL2
    class AST,Fmt xyL3
    class Out xyL1
    class Res xySuccess
    class AI xyWarn

3.2 模板系统

• 模板目录：%APPDATA%/Xisound/XiForge/templates/（用户可扩展）
• 模板格式：Handlebars（.hbs）+ 配套 manifest.json + JSON Schema
• 模板分类：FX / NR / Spatial / Dynamic / Utility / Custom
• 官方模板：首批 20+ 模板（覆盖 80% 常见算法骨架）
• 模板热更新：无需重启，目录变化自动重扫

3.3 Tree-sitter AST 校验

graph LR
    Code[生成的 C 代码] --> Parser[Tree-sitter Parser]
    Parser --> Tree[Syntax Tree]
    Tree --> Rules[规则引擎]
    Rules --> Check{校验}
    Check -- 语法错误 --> Fail[报告位置 + 原因]
    Check -- 规范违反 --> Warn[警告]
    Check -- 通过 --> Pass[可导出]

    class Code xyL0
    class Parser,Tree xyL2
    class Rules xyL3
    class Check xyWarn
    class Pass xySuccess
    class Fail,Warn xyError

校验规则示例： - 禁止动态内存分配（malloc / free） - 禁止系统调用（printf / fopen） - 强制使用 XiAlgo ABI 宏 - 符号命名规范

3.4 跨 XiDSP 型号移植

• 输入：源代码 + 源 target（D1）
• 输出：目标 target（D2/D3）适配后代码
• 处理：
• AST 解析识别 target 相关指令 / intrinsic
• 查"移植规则表"（每个 DSP 代际的差异）
• 替换 intrinsic / 类型 / 对齐
• 重新校验 AST
• 生成移植报告（哪些自动转 / 哪些需人工）

---

4. UIEditor 子系统

4.1 UIEditor 架构

graph TB
    Canvas[xy-canvas<br/>Fabric.js 封装]
    Canvas --> State[State Tree<br/>Pinia Store]
    Canvas --> Layers[层管理]
    Canvas --> Undo[Undo/Redo 栈]

    State --> Widgets[控件库 · widgetRegistry]
    State --> Theme[主题系统]
    State --> Binding[参数绑定表]

    State --> Save[.xyui 序列化]
    State --> Export[导出器]
    Export --> EE[Electron 独立客户端]
    Export --> XS[XiStudio 调音面板]
    Export --> WEB[浏览器预览]

    class Canvas xyL4
    class State xyL3
    class Layers,Undo xyL2
    class Widgets,Theme,Binding xyL1
    class Save xyL2
    class Export xyL3
    class EE,XS,WEB xySuccess

4.2 控件库设计

每个控件是一个 Vue 3 组件，符合 xy-design-system 规范：

interface XyWidget {
  id: string;
  type: 'knob' | 'slider' | 'spectrum' | 'curve-editor' | ...;
  category: 'basic' | 'display' | 'curve' | 'container' | 'custom';
  props: Record<string, unknown>;
  bindTo?: string;      // 参数绑定路径
  events: string[];
  renderFn: (props) => VNode;
}

4.3 .xyui 文件格式

详见 spec.md §3.6。设计原则： - JSON 人类可读 - 版本化 schema：version: "1.0" 字段 - 前向兼容：未知字段保留而非报错 - 最小化：默认值不序列化

4.4 主题系统

• 20+ CSS 变量（来自 brand-color-system v1.1）
• 字体：支持 TTF/OTF/WOFF 上传 · 嵌入到 .xyui
• Logo：SVG 优先（矢量缩放）+ PNG 兜底
• 主题导入导出：独立 .xytheme JSON 文件

4.5 参数绑定

graph LR
    Ctrl[控件 value] --> Bus[ParamBus]
    Bus -- 写 --> Algo[XiAlgo 参数寄存器]
    Algo -- 读实时值 --> Bus
    Bus --> Ctrl

    class Ctrl xyL4
    class Bus xyL3
    class Algo xyL2

双向绑定机制： - 控件值变化 → ParamBus 广播 → 所有订阅者收到（算法模块 + 其他控件） - 算法实时值变化 → ParamBus → 显示类控件（Spectrum / VU）更新

---

5. 私有仓库客户端

5.1 Git 封装

• 底层：simple-git（Node.js 封装 Git CLI）
• 认证：SSH Key / HTTPS Token
• LFS：大资源（模型 / 音频样本）用 Git LFS
• 冲突解决：三路合并 + UI 提示

5.2 元数据层

repo-root/
├── algorithms/           # 算法代码
│   ├── fx-eq/
│   └── ...
├── ui-projects/          # UI 工程
│   ├── brand-a-tuning-panel.xyui
│   └── ...
├── xisound-meta.json     # 仓库元数据（权限、审批规则）
└── .xisound/
    ├── audit.log         # 审计日志
    └── webhooks.json     # Webhook 配置

5.3 审批流（引用 spec §4.4）

• 本地提交 → PR → Reviewer 审核 → 审批通过 → 发布到 main
• XiForge UI 可视化 PR 列表 + Review 评论
• Webhook 通知（钉钉 / 企业微信 / Slack）

---

6. XiStudio 插件桥

6.1 双向通信架构

graph LR
    XS[XiStudio<br/>Electron]
    XF[XiForge<br/>Electron]

    XS <--JSON-RPC 2.0<br/>IPC / Socket--> XF

    XS -- "forge.openAlgorithm" --> XF
    XS -- "forge.openUI" --> XF
    XF -- "studio.reloadAlgorithm" --> XS
    XF -- "studio.loadPanel" --> XS

    class XS,XF xyL4

6.2 通信协议（JSON-RPC 2.0）

请求示例：

{
  "jsonrpc": "2.0",
  "method": "forge.openAlgorithm",
  "params": { "id": "fx-eq", "algorithm_name": "MyBassBoost" },
  "id": 42
}

响应示例：

{
  "jsonrpc": "2.0",
  "result": { "status": "opened", "window_id": "w-1234" },
  "id": 42
}

6.3 节点注入机制

XiForge 发布算法后： 1. 算法 manifest.json 复制到 XiStudio 的 algorithms/ 监视目录 2. XiStudio 检测变化 → 重新扫描 → 节点出现在 IP 库 3. 图标、分类、参数自动来自 manifest

---

7. XiMind AI 联动

7.1 调用架构

graph LR
    UI[XiForge UI] --> Cli[XiMind Client SDK]
    Cli --> Auth[OAuth 2.0 授权]
    Auth --> Req[HTTP / WebSocket 请求]
    Req --> Cloud[XiMind Cloud Service]
    Cloud --> Model[LLM · 声学知识注入]
    Model --> Stream[流式响应]
    Stream --> Parse[Tree-sitter 解析]
    Parse --> Diff[Diff 生成]
    Diff --> Review[开发者 Review UI]

    class UI,Review xyL4
    class Cli,Auth,Req xyL3
    class Cloud,Model xyL5
    class Stream,Parse,Diff xyL2

7.2 Prompt 工程

• 上下文：模板内容 + 参数 Schema + XiDSP 目标 + 约束（MIPS 上限）
• 格式：结构化 Markdown + 代码块
• 护栏：System Prompt 强制"只输出有效 C 代码 + 解释"

7.3 容错与降级

• 网络失败：UI 显示"AI 服务不可用"，保留本地生成能力
• Token 超限：提示用户升级订阅
• 置信度低：标注 "AI 可信度 < 0.7"，强制人工 Review
• 恶意注入防护：Prompt 注入攻击检测（关键词黑名单）

---

8. 性能架构

8.1 启动优化

目标：冷启动 ≤ 3 秒

• Preload：Electron V8 snapshot 缓存（启动加速 40%）
• Lazy load：子系统按需加载（CodeGen / UIEditor 分包）
• Splash Screen：启动期间显示品牌 Splash

8.2 UIEditor 渲染优化

目标：≥ 60 FPS @ 1080p · 100 控件

• 虚拟滚动：只渲染视口内的控件
• Canvas 分层：背景 / 控件 / 选择框 分 3 层
• Transform 矩阵：缩放 / 平移用 CSS Transform 而非重绘
• requestAnimationFrame：所有动画走 rAF

8.3 代码生成优化

目标：≤ 5 秒（非 AI）

• 模板缓存：Handlebars 编译结果缓存
• Tree-sitter 增量解析：小改动不全量重解析
• Clang-format 预热：常驻 Backend 进程

---

9. 安全架构

9.1 Electron 安全

• contextIsolation: true（强制）
• nodeIntegration: false（Renderer 不能直接 require）
• sandbox: true
• preload 脚本：只暴露白名单 API
• Content-Security-Policy：严格 CSP Header

9.2 本地数据加密

• 工作目录敏感文件（Token / 账户）AES-256 加密
• 密钥派生：PBKDF2 + 系统 Keychain（Windows Credential Manager / macOS Keychain / GNOME Keyring）

9.3 传输加密

• 所有远程通信强制 TLS 1.3
• 证书 Pinning（连接 Xisound 云端服务时）
• 证书过期提前 30 天告警

9.4 审计

• 关键操作本地日志 + 上报（可关闭）
• 日志格式：结构化 JSON · 可 grep / 导入 SIEM
• 用户可导出所有审计日志（GDPR 合规）

---

10. 可观测性与运维

10.1 日志系统

• 库：winston
• 分级：ERROR / WARN / INFO / DEBUG / TRACE
• 滚动：按天 + 大小（单文件 ≤ 10MB）
• 用户界面：日志查看器 · 过滤 · 搜索 · 导出

10.2 崩溃上报

• 工具：Sentry 私有部署
• 默认：本地留存 · 用户同意后上报
• PII 防护：邮箱 / 姓名 / Token 自动脱敏

10.3 遥测（可选）

• 功能使用频次 / 操作耗时
• 默认关闭 · 用户显式开启
• 数据脱敏 · 聚合后上报

---

11. 演进路线

11.1 3 年技术演进

时间	里程碑
2026 Q4	v0.1 内部 Alpha
2027 Q1	v0.5 Beta · Enterprise 客户试用
2027 Q2	v1.0 GA（CodeGen + UIEditor + 私有仓库）
2027 Q4	v1.1 · XiMind AI 辅助生成
2028 Q2	v1.5 · 自定义 Vue 组件 · Linux 支持
2028 Q4	v2.0 · 协作实时编辑（Figma 式）
2029	v3.0 · 云端 SaaS 版本（WebAssembly）

11.2 技术债提示

已识别的技术债（v1.0 阶段接受）

1. 无实时协作 — v2.0 计划加入 OT/CRDT
2. Linux 延迟 — v1.1+ 补齐
3. 移动端无 — 短期无计划
4. Electron 包体大 — 长期评估 Tauri 替换

---

12. 附录

12.1 与其他文档的引用

关联文档	引用点
XiForge 产品概述	产品定位 / 目标用户
XiForge PRD	功能需求 / 验收标准
XiForge 产品规格书	API 契约 / 非功能指标（本文数字源）
XiStudio 技术架构	插件协议对接
XiMind 产品规格书	AI 云端接口
软件开发规范	代码规范 / Git 流程

12.2 外部标准参考

• Electron Security Best Practices
• JSON-RPC 2.0 Specification
• JSON Schema Draft-07
• OAuth 2.0 RFC 6749
• Git LFS Specification

12.3 版本历史

版本	日期	要点
v1.0	2026-05-05	首版 · 五层架构 + CodeGen + UIEditor + 集成 + AI 联动 + 性能安全

---

tech-arch.md · D2-P9-TECH-001 · v1.0 · 2026-05-05 · Xisound 研发中心 · 工具软件团队