XiForge · Technical Spec

XiForge 产品规格书

开发者平台 · 代码生成器架构 / UI 编辑器 API / XiStudio 集成

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

从架构到 API · 每一个集成点都可验证

2

核心子系统

REST+WS

双协议 API

Electron

桌面运行时

XiForge 产品规格书

摘要

本文档是 XiForge 开发者平台的完整技术规格书，涵盖算法代码生成器架构、UI 编辑器 API、XiStudio 集成方案、私有仓库协议、XiMind AI 联动接口。 面向 Tier1 算法架构师、OEM 工具工程师、独立算法咨询工程师、Xisound 内部研发。

数据来源

规格为 v1.0 GA 目标值（2027 Q2），内容随版本迭代更新，最终以发行版 Release Notes 为准。

---

1. 总体架构

1.1 系统总览

graph TB
    UI[XiForge UI Shell<br/>Electron + Vue 3]
    UI --> CG[CodeGen 子系统]
    UI --> UE[UIEditor 子系统]
    UI --> Repo[私有仓库客户端]
    UI --> Plug[XiStudio 插件桥]
    UI --> AI[XiMind AI 客户端]

    CG --> Backend[CodeGen Backend<br/>Node.js + Tree-sitter]
    UE --> UEBackend[UIEditor Backend<br/>Node.js + Vue Builder]
    Repo --> RepoSrv[Repo Server<br/>Git + HTTPS]
    AI --> XiMindSvc[XiMind Cloud Service]

    class UI,Plug xyL4
    class CG,UE,Repo xyL3
    class Backend,UEBackend,RepoSrv xyL2
    class AI,XiMindSvc xyL5

1.2 技术栈

层	技术
桌面运行时	Electron 28+
前端框架	Vue 3 + TypeScript + Pinia + VueUse
UI 组件	自研 xy-design-system + Tailwind CSS
后端服务	Node.js 20+ + Fastify
代码生成	Tree-sitter（C/C++ AST）+ Handlebars 模板
测试框架	Vitest + Playwright
仓库底层	Git + LFS + HTTPS/SSH
AI 通信	HTTPS + WebSocket · JSON-RPC 2.0

1.3 模块划分

模块	职责
CodeGen	算法代码骨架生成、模板管理、XiDSP 目标移植
UIEditor	拖拽画布、控件库、主题系统、导出器
Repo Client	私有仓库连接、版本发布、审批流
XiStudio Plugin	与 XiStudio IDE 双向通信 · 插件协议
XiMind Client	AI 请求封装 · 流式响应解析

---

2. CodeGen 子系统

2.1 算法模板定义

模板目录结构

templates/
  fx-eq/                     # EQ 算法模板
    manifest.json            # 元数据
    src.c.hbs                # C 代码骨架（Handlebars）
    params.schema.json       # 参数 JSON Schema
    test.cpp.hbs             # 单元测试骨架
    doc.md.hbs               # 文档模板
  fx-drc/                    # DRC 模板
  nr-cnn/                    # CNN 降噪
  delay/                     # 时延
  reverb/                    # 混响
  custom/                    # 用户自定义

manifest.json 示例

{
  "id": "fx-eq",
  "name": "Biquad EQ",
  "category": "FX",
  "version": "1.0.0",
  "description": "Second-order IIR EQ filter template",
  "params": [
    { "name": "freq", "type": "float", "min": 20, "max": 20000, "default": 1000 },
    { "name": "gain", "type": "float", "min": -24, "max": 24, "default": 0 },
    { "name": "Q",    "type": "float", "min": 0.1, "max": 10, "default": 0.707 }
  ],
  "targets": ["XiDSP-D1", "XiDSP-D2", "XiDSP-D3"]
}

2.2 CodeGen API

接口	方法	描述
POST /api/codegen/generate	POST	生成算法骨架代码
POST /api/codegen/validate	POST	语法 + Schema 校验
GET /api/codegen/templates	GET	列出可用模板
POST /api/codegen/port	POST	跨 XiDSP 型号移植
POST /api/codegen/compile	POST	编译预检（调用 XiStudio 编译器）

生成请求示例

POST /api/codegen/generate
{
  "template_id": "fx-eq",
  "project_id": "proj-001",
  "algorithm_name": "MyBassBoost",
  "params": { "freq": 60, "gain": 3, "Q": 0.707 },
  "target": "XiDSP-D2",
  "use_ai": false
}

返回响应

{
  "status": "success",
  "files": [
    { "path": "src/my_bass_boost.c", "lines": 145 },
    { "path": "test/my_bass_boost_test.cpp", "lines": 60 },
    { "path": "schema/my_bass_boost.json", "lines": 30 }
  ],
  "commit_hint": "Add MyBassBoost via XiForge CodeGen"
}

2.3 AI 辅助生成（v1.1+）

• 触发：use_ai: true 或 UI 中点击 "AI Boost"
• 流程：
• XiForge 把参数 + 模板上下文打包为 prompt
• 调用 XiMind /api/v1/codegen（流式响应）
• Tree-sitter 解析结果 → 注入模板
• 开发者 review diff → 接受 / 拒绝
• 超时：默认 30 秒，用户可中断

---

3. UIEditor 子系统

3.1 画布架构

• 基础画布：Vue 3 + Fabric.js 封装的 xy-canvas
• 坐标系：逻辑像素（与屏幕无关）+ Transform 矩阵
• 层管理：类 Figma 层级面板
• 快捷键：标准（Cmd/Ctrl + Z/Y/C/V/D/A）

3.2 控件库

类别	控件
基础	Button / Slider / Knob / Switch / Label
显示	Spectrum / Waveform / VU Meter / Level Meter
曲线	EQ Curve Editor / Filter Response / Compressor Curve
容器	Panel / Tab / Accordion / Grid
自定义	用户自定义 Vue 组件（v1.1+）

3.3 主题系统

• 颜色变量：主色 / 辅色 / 背景 / 文字等 20+ CSS 变量
• 字体：支持自定义字体上传（TTF/OTF/WOFF）
• Logo：SVG / PNG 二选一，尺寸无限制
• 导入导出：JSON 格式，可跨项目复用

3.4 参数绑定

• 绑定方式：控件属性 bind_to 指向 xialgo.<module>.<param>
• 双向同步：控件 → 算法（写参数），算法 → 控件（读实时值）
• 约束：控件 min/max/step 自动来自参数 JSON Schema

3.5 UIEditor API

接口	方法	描述
POST /api/uieditor/project/create	POST	新建 UI 项目
POST /api/uieditor/project/save	POST	保存 UI 工程文件（.xyui）
POST /api/uieditor/export/electron	POST	导出为 Electron 独立客户端
POST /api/uieditor/export/xistudio	POST	导出为 XiStudio 调音面板
POST /api/uieditor/preview	POST	浏览器实时预览 URL

3.6 .xyui 文件格式

{
  "version": "1.0",
  "meta": { "name": "BrandA Tuning Panel", "brand": "BrandA" },
  "theme": { "primary": "#D4A574", "secondary": "#9D4EDD", "logo": "assets/logo.svg" },
  "canvas": { "width": 1920, "height": 1080 },
  "widgets": [
    {
      "id": "w001",
      "type": "knob",
      "position": { "x": 100, "y": 200 },
      "size": { "w": 120, "h": 120 },
      "bind_to": "xialgo.fx.eq.band1.gain",
      "label": "低音"
    }
  ]
}

---

4. 私有仓库协议

4.1 仓库部署模式

模式	说明
局域网	企业内部 Git Server · 数据不出内网
云托管	Xisound 云端托管 · 端到端加密
混合	元数据云端 + 代码本地

4.2 仓库 API

接口	方法	描述
POST /repo/publish	POST	发布算法或 UI 工程
GET /repo/algorithms	GET	列出可用算法（带权限过滤）
POST /repo/approve	POST	审批流操作
GET /repo/audit	GET	审计日志查询

4.3 权限模型

• 组织级：仅限本公司员工
• 部门级：仅限指定部门
• 项目级：仅限项目成员
• 工程师级：仅限指定工程师

4.4 版本与审批流

graph LR
    Dev[开发者提交] --> PR[Pull Request]
    PR --> Rev[Reviewer 审核]
    Rev --> App[审批通过]
    App --> Pub[发布到 main]
    Pub --> Use[XiStudio 可调用]

    class Dev xyL4
    class PR,Rev xyL2
    class App xySuccess
    class Pub,Use xyL3

---

5. XiStudio 集成

5.1 插件协议

• 通信：本机 IPC（Electron IPC / Unix Socket）
• 协议：JSON-RPC 2.0
• 消息类型：
• forge.openAlgorithm(id) — XiStudio 请求打开 XiForge 编辑某算法
• forge.openUI(id) — 打开 UI 工程
• studio.reloadAlgorithm(id) — XiForge 通知 XiStudio 重新加载
• studio.loadPanel(path) — XiStudio 加载 UI 面板

5.2 流图节点注入

• XiForge 发布算法后自动在 XiStudio 算法 IP 库中显示
• 图标、分类、参数来自 manifest.json
• 右键节点 → "在 XiForge 中编辑" → IPC 调用 forge.openAlgorithm

5.3 UI 面板加载

• XiStudio 的"调音面板"可选择默认内置面板或 XiForge 导出的 .xyui
• 面板切换热更新，无需重启 IDE

---

6. XiMind AI 联动接口

6.1 调用模式

• 同步：REST POST /api/v1/codegen（返回完整结果）
• 流式：WebSocket wss://.../codegen/stream（实时渐进输出）

6.2 请求格式

{
  "task": "generate_algorithm",
  "template": "fx-eq",
  "description": "低频增强算法，60Hz 以下 +3dB",
  "constraints": { "target": "XiDSP-D2", "max_mips": 30 },
  "stream": true
}

6.3 响应格式

{
  "status": "success",
  "code_diff": "--- ...",
  "explanation": "我基于 Butterworth shelving filter 生成了系数 ...",
  "confidence": 0.85,
  "tokens_used": 1500
}

6.4 Token 计费

• 按调用量计费，订阅套餐包含每月免费额度
• 超出后按 Token 阶梯计费（参见 XiMind Spec）

---

7. 非功能规格

7.1 性能

指标	规格
启动时间	≤ 3 秒（冷启动）
代码生成响应	≤ 5 秒（非 AI）
AI 生成响应	≤ 30 秒（P95）
UI 编辑器帧率	≥ 60 FPS @ 1080p
工程规模上限	10000 行代码 / 100 控件 / 20 MB 资源

7.2 安全

• 本地加密：AES-256 工作目录敏感文件
• 传输加密：TLS 1.3（所有远程通信）
• 身份认证：OAuth 2.0 + XiMind 账户
• 审计：全部关键操作记录本地 + 上报（可关闭）

7.3 兼容性

维度	规格
操作系统	Windows 11 / macOS 13+ / Ubuntu 22.04+
XiStudio	Enterprise v1.0+ / IDM v1.0+
目标 XiDSP	D1 / D2 / D3
编译器	XiStudio 集成工具链（XiDSP-Clang）

---

8. 部署与运维

8.1 授权激活

• Enterprise / IDM 内置：随 XiStudio 激活
• Standalone：独立 License Key
• 离线模式：支持 7 天离线使用 · 超时需联网激活

8.2 升级

• 应用内自动检查更新
• 企业版支持集中管理服务器推送更新
• 回滚：保留前一版本 · 一键回退

8.3 日志与诊断

• 日志级别：ERROR / WARN / INFO / DEBUG / TRACE
• 日志位置：
• Win: %APPDATA%/Xisound/XiForge/logs
• macOS: ~/Library/Logs/Xisound/XiForge
• Linux: ~/.config/Xisound/XiForge/logs
• 崩溃上报：Sentry 私有部署 · 默认本地留存，用户同意后上报

---

9. 路线与已知限制

9.1 v1.0 已知限制

• 不支持：自定义 Vue 组件（v1.1+ 启用）
• 不支持：协作实时编辑（单人单项目）
• AI 辅助：v1.0 不启用 · v1.1 开始
• 跨平台：v1.0 仅 Windows + macOS · Linux v1.1+

9.2 变更流程

• 规格变更需同步更新：PRD / Spec / 用户手册
• Breaking Change 需提前 2 个 minor 版本公告

---

10. 附录

10.1 关联文档

• XiForge 产品概述
• XiForge PRD v1.0
• XiStudio 产品规格书
• XiMind 产品规格书
• Xisound 产品矩阵 V1.1
• 软件研发规范

10.2 标准与开源组件

• Electron 28+（MIT）
• Vue 3 + TypeScript + Pinia + VueUse（MIT）
• Tree-sitter（MIT）
• Fastify（MIT）
• Git + LFS（GPL v2 / MIT）
• JSON-RPC 2.0 规范

10.3 版本历史

版本	日期	要点
v1.0	2026-05-05	首版 · v1.0 GA 完整技术规格

---

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