XiForge · User Manual

XiForge 用户手册 v1.0

安装 · 首个算法 · UI 编辑 · 仓库 · 联动

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

从 0 到 1 生成算法 · 从算法到品牌面板一站式交付

1h

首个算法

拖拽

UI 编辑

私有仓库

团队协作

XiForge 用户手册 v1.0

摘要

本手册面向 XiForge 开发者平台的首次使用者：Tier1 算法架构师 / OEM 工具工程师 / 独立算法咨询工程师 / Xisound 内部研发。 覆盖安装 → 首个算法骨架生成 → UI 编辑器使用 → 私有仓库发布 → 与 XiStudio 联动 → 故障排查全流程，目标让新用户 1 小时内完成第一个算法 + 配套 UI 面板并发布到私有仓库。

阅读前提

• 已阅读 XiForge 产品概述 与 XiForge 产品规格书
• 已安装 XiStudio Enterprise 或 IDM 版（Pro/Community 不含 XiForge 许可）
• 有 XiMind 账户（用于 AI 辅助 · 可选）
• 熟悉基本 C 语言与音频 DSP 概念

---

1. 安装与激活

1.1 下载

• 随 XiStudio Enterprise / IDM 捆绑：XiStudio 安装时自动安装 XiForge
• 单独下载（IDM 客户）：www.xisound.com/download/xiforge
• 企业批量分发：联系商务提供离线安装包 + 集中管理服务器

1.2 系统要求

维度	最低	推荐
OS	Windows 10 · macOS 12 · Ubuntu 22.04（v1.1+）	Windows 11 · macOS 14
CPU	4 核	8 核
RAM	8 GB	16 GB
磁盘	5 GB	20 GB
网络	AI 辅助需稳定 HTTPS	千兆

1.3 首次启动激活

graph LR
    S1[启动 XiForge]
    S2{激活方式}
    S2 -- XiStudio 捆绑 --> S3[自动继承 XiStudio 许可]
    S2 -- 独立 License --> S4[输入 License Key]
    S2 -- 企业 SSO --> S5[OAuth 2.0 登录]
    S3 --> S6[进入主界面]
    S4 --> S6
    S5 --> S6

    class S1 xyL4
    class S2 xyWarn
    class S3,S4,S5 xyL3
    class S6 xySuccess

1.4 主界面总览

┌─────────────────────────────────────────────┐
│ 菜单栏：文件 / 编辑 / 工具 / 视图 / 帮助      │
├───────┬─────────────────────────┬───────────┤
│ 侧栏   │ 主编辑区                 │ 属性面板   │
│       │                          │           │
│ 模板库 │ 代码编辑器 / UI 画布     │ 参数 / 样式 │
│ 项目树 │                          │           │
│ Git   │                          │           │
├───────┴─────────────────────────┴───────────┤
│ 底部：Terminal · 构建输出 · 状态栏            │
└─────────────────────────────────────────────┘

---

2. 首个算法骨架（30 分钟）

2.1 目标

用 CodeGen 从模板生成 "MyBassBoost" 算法（低频增强 PEQ），目标 XiDSP-D2，完整代码 + 单元测试 + JSON Schema + 文档。

2.2 操作步骤

1. 新建项目：文件 → 新建 CodeGen 项目 → 命名 my-bass-boost → 确定
2. 选模板：侧栏 → 模板库 → 搜 "EQ" → 选 fx-eq → 使用此模板
3. 填参数：
4. algorithm_name: MyBassBoost
5. target: XiDSP-D2
6. freq: 60, gain: 3, Q: 0.707
7. 点击生成：主编辑区右上角 Generate 按钮
8. 审查输出：左侧项目树出现 3 个文件：
9. src/my_bass_boost.c（145 行）
10. test/my_bass_boost_test.cpp（60 行）
11. schema/my_bass_boost.json（30 行）

2.3 查看生成的代码

// src/my_bass_boost.c · 由 XiForge CodeGen 生成
#include "xialgo_abi.h"

typedef struct {
    float b0, b1, b2, a1, a2;   // Biquad 系数
    float z1, z2;                // 状态变量
} MyBassBoost_State;

XIALGO_INIT_FN(my_bass_boost_init)(void* state, const XiAlgoParams* params) {
    MyBassBoost_State* s = (MyBassBoost_State*)state;
    // ... Butterworth shelving filter 系数计算
    return XIALGO_OK;
}

XIALGO_PROCESS_FN(my_bass_boost_process)(
    void* state, const float* in, float* out, uint32_t n_samples) {
    // ... 单帧处理循环
    return XIALGO_OK;
}

2.4 校验 + 编译预检

• 工具栏 → Validate：Tree-sitter 校验 · 预期 "✅ No violations"
• 工具栏 → Compile Check：调用 XiStudio 编译器 · 预期 "✅ Compile OK · MIPS: 8 / 300"

---

3. AI 辅助生成（可选 · v1.1+）

3.1 开启 AI

• 菜单 → 设置 → XiMind → 粘贴 Token → 测试连接

3.2 AI Boost 流程

graph LR
    A[用自然语言描述算法]
    B[勾选 Use AI Boost]
    C[点击 Generate]
    D[XiForge 上下文打包]
    E[XiMind 流式返回]
    F[Tree-sitter 解析]
    G[Diff UI 展示]
    H{开发者 Review}

    A --> B --> C --> D --> E --> F --> G --> H
    H -- 接受 --> Accept[应用]
    H -- 拒绝 --> Back[手动修改]

    class A,B,C xyL4
    class D,E xyL3
    class F,G xyL2
    class H xyWarn
    class Accept xySuccess
    class Back xyError

3.3 描述示例

任务：生成一个低频增强算法
- 中心频率 60 Hz
- Shelf 增益 +3 dB
- Q = 0.707（Butterworth）
- 目标 XiDSP-D2 定点实现
- MIPS ≤ 30
- 支持参数运行时调整（Ramp 20 ms 防爆音）

3.4 置信度与 Review

• confidence ≥ 0.85：可直接 Accept
• 0.7 ≤ confidence < 0.85：强烈建议逐行 Review
• confidence < 0.7：强制人工 Review + 警告图标

---

4. UIEditor：生成品牌调音面板（30 分钟）

4.1 新建 UI 工程

1. 文件 → 新建 UI 项目 → 命名 brand-a-tuning-panel
2. 设画布 1920 × 1080
3. 选品牌 BrandA（后续可改主题）

4.2 添加控件

侧栏 控件库 拖到画布： - Knob × 5（5 段 EQ 的 Gain 旋钮） - Slider × 5（5 段 EQ 的 Freq 滑条） - Spectrum × 1（实时频谱） - Label × 若干

4.3 配置参数绑定

选中 Knob → 右侧属性 → Bind To → 输入 xialgo.fx.eq.band1.gain

graph LR
    Knob[UI Knob] --> Bus[ParamBus]
    Bus --> Algo[XiAlgo · band1.gain]
    Algo --> Bus
    Bus --> Spec[Spectrum 实时反馈]

    class Knob,Spec xyL4
    class Bus xyL3
    class Algo xyL2

4.4 应用品牌主题

菜单 → 主题 → 导入 → 选择品牌主题 .xytheme 或手动调： - 主色：#D4A574 - 辅色：#9D4EDD - Logo：assets/brand-a-logo.svg - 字体：BrandA Sans（上传 TTF）

4.5 预览

工具栏 → Preview → 浏览器打开实时预览 URL，验证交互流畅。

4.6 导出

• 导出为 XiStudio 面板：File → Export → XiStudio Panel → 生成 .xypanel
• 导出为 Electron 独立客户端：File → Export → Electron App → 生成 .exe / .dmg
• 进度在底部 Terminal 实时显示

---

5. 私有仓库协作

5.1 配置仓库

• 菜单 → 设置 → 私有仓库
• 填 Git URL（SSH 或 HTTPS）
• 上传 SSH Key 或 Access Token
• 测试连接

5.2 发布算法

# 在项目中执行
xy-forge repo publish \
    --path ./my-bass-boost \
    --message "Add MyBassBoost v1.0" \
    --reviewer alice

或通过 UI：右键算法 → Publish to Repo

5.3 审批流

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

    Dev --> Rev --> App --> Pub --> Use

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

5.4 权限管理

• 组织级 / 部门级 / 项目级 / 工程师级 四档
• 细粒度到单个算法 / UI 工程
• 审计日志所有关键操作

---

6. 与 XiStudio 联动

6.1 无缝打开编辑

在 XiStudio 流图中： - 右键某个算法节点 → 在 XiForge 中编辑 - XiForge 自动拉起 + 定位到该算法 - 改完保存 → XiStudio 自动热重载

6.2 UI 面板加载

在 XiStudio： - 设置 → 调音面板 → 加载 .xypanel → 选 XiForge 导出的面板 - 面板替换默认内置调音 UI - 支持热切换，无需重启

6.3 通信协议

双向 JSON-RPC 2.0，详见 api.md §3 JSON-RPC 2.0 插件协议。

---

7. 典型开发流程

7.1 从 0 到 1 完整流程

graph LR
    S1[新建 CodeGen 项目]
    S2[选模板 + 填参数]
    S3[生成骨架]
    S4[代码实现 / AI 辅助]
    S5[Validate + Compile Check]
    S6[新建 UI 项目]
    S7[拖拽控件 + 绑定参数]
    S8[应用品牌主题]
    S9[导出 + 部署]
    S10[发布到仓库]

    S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9 --> S10

    class S1,S6 xyL4
    class S2,S3,S7,S8 xyL2
    class S4,S5,S9 xyL3
    class S10 xySuccess

7.2 团队协作流程

• 架构师：设计算法 / 定义接口
• 算法工程师：用 XiForge 生成骨架 + AI 辅助实现
• UI 设计师：用 XiForge UIEditor 设计品牌面板
• Reviewer：私有仓库 PR 审查
• 调音师：在 XiStudio 加载面板 + 调参 + 保存预设
• 交付工程师：导出 + 部署到目标车型 / 硬件

---

8. 故障排查

8.1 常见故障

现象	可能原因	解决
启动时报"License 无效"	许可过期 / XiStudio 未激活	检查 XiStudio 状态 · 联系商务
CodeGen 生成失败	模板损坏 / Schema 不匹配	重装模板 · 检查参数 JSON
AI 辅助超时	网络 / XiMind 额度	检查 Token · 确认订阅
Validate 误报	规则版本过旧	更新规则包
UIEditor 卡顿	控件过多 / 资源过大	清理未用资源 · 分页
仓库 PR 失败	权限 / 冲突	查审计日志 · 手动合并
XiStudio 联动断开	插件协议版本不匹配	升级 XiStudio / XiForge 到同版本

8.2 日志导出

菜单 → 帮助 → 导出诊断包 → 生成 xiforge-diag-YYYYMMDD.zip： - 应用日志 - 当前项目快照（脱敏） - API 调用历史 - 系统环境

向 FAE 报 Bug 时请附带此包。

8.3 性能诊断

菜单 → 工具 → 性能诊断： - CPU / 内存实时曲线 - Backend 响应延迟 - UIEditor 渲染帧率

---

9. 最佳实践

9.1 算法开发

CodeGen 最佳实践

1. 优先用官方模板 · 20+ 模板覆盖 80% 场景
2. 用 AI 时必 Review：confidence < 0.85 强烈建议逐行
3. Validate 不过不提交：Tree-sitter 规则是质量底线
4. Compile Check 过了再 PR：减少 Review 往返

9.2 UI 设计

UIEditor 最佳实践

1. 遵循 brand-color-system v1.1 四色体系
2. 控件数 ≤ 100 / 画布（超过建议分页）
3. 资源图片 ≤ 2 MB / 张
4. 主题独立导出 .xytheme 跨项目复用

9.3 仓库协作

私有仓库最佳实践

1. commit message 遵循 Conventional Commits
2. PR 小而频繁（单 PR 改动 ≤ 500 行）
3. Review 关注点：正确性 > 性能 > 风格
4. 审批后发布，发布前 Compile Check 必过

---

10. 附录

10.1 规格速查

项	值
启动时间	≤ 3 秒
CodeGen 响应	≤ 5 秒（非 AI）
AI 生成响应	≤ 30 秒 P95
UIEditor 帧率	≥ 60 FPS
单工程规模上限	10000 行代码 / 100 控件 / 20 MB

10.2 关联文档

• XiForge 产品概述
• XiForge PRD v1.0
• XiForge 产品规格书
• XiForge API 文档
• XiForge 技术架构
• XiForge FAQ
• XiForge 培训材料
• XiStudio 用户手册

10.3 技术支持

• 邮箱：support@xisound.com
• 工单（Enterprise/IDM）：CRM 系统
• 社群：Discord / 微信（签约后加入）

10.4 版本历史

版本	日期	要点
v1.0	2026-05-05	首版 · 安装 / 首个算法 / UI 编辑 / 仓库 / 联动 / 排错

---

user-manual.md · D2-P9-MAN-001 · v1.0 · 2026-05-05 · Xisound 交付中心 · FAE 团队