XiForge · API Reference

XiForge API 文档 v1.0

CodeGen · UIEditor · Plugin · WebSocket · CLI

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

每一个端点都有契约 · 每一次流式都可追溯

REST+WS

双协议

JSON-RPC 2.0

插件协议

xy-forge

CLI 工具

XiForge API 文档 v1.0

摘要

本文档定义 XiForge 开发者平台的完整对外接口：CodeGen REST API（生成 / 校验 / 移植 / 编译预检）、UIEditor REST API（工程管理 / 导出 / 预览）、JSON-RPC 2.0 插件协议（与 XiStudio 双向通信）、WebSocket 流式 API（AI 实时生成）、xy-forge CLI。目标读者：OEM 工具工程师、Tier1 算法架构师、第三方集成开发者、XiForge 二次开发者。

稳定性契约

REST API 遵循 SemVer，URL 前缀 /api/v1/
JSON-RPC 2.0 方法名在同 Major 版本内保持向后兼容
.xyui 文件格式 Schema 向后兼容保障 5 年
CLI 参数遵循 GNU 风格，短选项向后兼容

1. CodeGen REST API

1.1 基础信息

项	值
Base URL	`http://localhost:{port}/api/v1/codegen`
端口	启动时动态分配 · 可从 Main 进程 IPC 查询
认证	本地 Token（启动时生成 · 存 `~/.xisound/xiforge-token`）
格式	JSON · UTF-8

1.2 端点清单

端点	方法	说明
`/generate`	POST	生成算法骨架代码
`/validate`	POST	语法 + Schema 校验
`/templates`	GET	列出可用模板
`/port`	POST	跨 XiDSP 型号移植
`/compile`	POST	编译预检（调用 XiStudio 编译器）

1.3 `POST /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, "sha256": "abc..." },
    { "path": "test/my_bass_boost_test.cpp", "lines": 60, "sha256": "def..." },
    { "path": "schema/my_bass_boost.json", "lines": 30, "sha256": "ghi..." }
  ],
  "commit_hint": "Add MyBassBoost via XiForge CodeGen"
}

1.4 `POST /validate`

请求：

{
  "file_path": "src/my_bass_boost.c",
  "check_level": "strict"
}

响应：

{
  "status": "success",
  "violations": [
    { "line": 42, "severity": "warn", "rule": "no-malloc", "message": "动态内存分配被禁用" }
  ],
  "passed": true
}

1.5 `GET /templates`

返回：

{
  "templates": [
    {
      "id": "fx-eq",
      "name": "Biquad EQ",
      "category": "FX",
      "version": "1.0.0",
      "targets": ["XiDSP-D1", "XiDSP-D2", "XiDSP-D3"]
    },
    { "id": "fx-drc", "name": "Dynamic Range Compressor", ... },
    { "id": "nr-cnn", "name": "CNN Noise Reduction", ... }
  ]
}

1.6 `POST /port`

请求：

{
  "src_file": "src/my_bass_boost.c",
  "src_target": "XiDSP-D1",
  "dst_target": "XiDSP-D2"
}

响应：

{
  "status": "success",
  "dst_file": "src/my_bass_boost_d2.c",
  "auto_converted": 23,
  "manual_required": [
    { "line": 87, "reason": "D2 intrinsic 需手动验证溢出" }
  ]
}

1.7 错误码

HTTP	含义
200	成功
400	参数错误
401	Token 无效
404	模板不存在
422	Schema 校验失败
500	内部错误
503	AI 服务不可用（use_ai=true 时）

2. UIEditor REST API

2.1 端点清单

端点	方法	说明
`/uieditor/project/create`	POST	新建 UI 项目
`/uieditor/project/save`	POST	保存 `.xyui`
`/uieditor/project/load`	POST	加载 `.xyui`
`/uieditor/export/electron`	POST	导出为 Electron 独立客户端
`/uieditor/export/xistudio`	POST	导出为 XiStudio 调音面板
`/uieditor/preview`	POST	浏览器实时预览 URL
`/uieditor/widgets`	GET	列出控件库
`/uieditor/themes`	GET	列出主题

2.2 `POST /uieditor/project/create`

请求：

{
  "name": "BrandA Tuning Panel",
  "brand": "BrandA",
  "canvas": { "width": 1920, "height": 1080 }
}

响应：

{
  "status": "success",
  "project_id": "ui-proj-042",
  "file_path": "/workspace/ui-proj-042.xyui"
}

2.3 `POST /uieditor/export/electron`

请求：

{
  "project_id": "ui-proj-042",
  "platform": "win32",
  "arch": "x64",
  "output_dir": "/workspace/dist"
}

响应（异步 · 返回任务 ID）：

{
  "status": "building",
  "task_id": "build-task-007",
  "progress_url": "ws://localhost:{port}/uieditor/build/build-task-007"
}

进度 WebSocket 事件：

{ "stage": "bundling", "percent": 40 }
{ "stage": "packaging", "percent": 75 }
{ "stage": "done", "artifact": "/workspace/dist/BrandA_Tuning-1.0.0.exe" }

2.4 `POST /uieditor/preview`

请求：

{ "project_id": "ui-proj-042" }

响应：

{
  "status": "success",
  "preview_url": "http://localhost:53421/preview/ui-proj-042"
}

3. JSON-RPC 2.0 插件协议（XiStudio 联动）

3.1 协议基础

版本：JSON-RPC 2.0
传输：IPC（Electron）/ Named Pipe（跨进程）
编码：UTF-8 JSON

3.2 XiStudio → XiForge 方法

方法	描述
`forge.openAlgorithm`	打开算法编辑（若 XiForge 未启动则拉起）
`forge.openUI`	打开 UI 工程
`forge.createAlgorithm`	新建算法
`forge.listTemplates`	列出模板（同 REST /templates）

示例：

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

3.3 XiForge → XiStudio 方法

方法	描述
`studio.reloadAlgorithm`	XiForge 通知 XiStudio 重新加载算法
`studio.loadPanel`	XiStudio 加载 UI 面板
`studio.notifyStatus`	通用状态通知

3.4 错误格式

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": { "attempted": "forge.fakeMethod" }
  },
  "id": 42
}

标准错误码见 JSON-RPC 2.0 规范；XiForge 扩展： - -33000：模板不存在 - -33001：工程不存在 - -33002：XiMind AI 不可用 - -33003：Git 仓库未配置

4. XiMind AI 联动 API

4.1 同步调用

端点：POST https://api.ximind.xisound.com/v1/codegen Header：Authorization: Bearer {token}

请求：

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

响应：

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

4.2 流式调用

端点：wss://api.ximind.xisound.com/v1/codegen/stream Header：Authorization: Bearer {token}（通过 Subprotocol）

客户端发送：

{
  "task": "generate_algorithm",
  "template": "fx-eq",
  "description": "...",
  "constraints": { ... }
}

服务端流式返回：

{ "event": "start", "request_id": "req-001" }
{ "event": "chunk", "delta": "static inline void biquad_init(" }
{ "event": "chunk", "delta": "float* coeffs, float freq, float gain" }
...
{ "event": "done", "explanation": "...", "confidence": 0.85, "tokens_used": 1500 }

4.3 限流

订阅套餐包含每月免费 Token 额度
超出按阶梯计费
速率限制：5 并发请求 / 账户
超限返回 HTTP 429 + Retry-After Header

5. `xy-forge` CLI

5.1 安装

npm install -g @xisound/xy-forge
# 或
brew install xisound/tap/xy-forge

5.2 命令总览

xy-forge --help

XiForge CLI v1.0

Commands:
  init              初始化新项目
  gen <template>    生成算法骨架
  validate <file>   校验源码
  port <file>       跨 DSP 移植
  ui build          构建 UI 工程
  repo publish      发布到私有仓库
  ai gen            AI 辅助生成（需 XiMind Token）

Options:
  --config <path>   配置文件路径（默认 ~/.xisound/xy-forge.json）
  --verbose         详细日志
  --help            显示帮助

5.3 常用示例

# 初始化项目
xy-forge init my-eq-project

# 生成 EQ 算法骨架
xy-forge gen fx-eq \
    --name MyBassBoost \
    --target XiDSP-D2 \
    --freq 60 --gain 3 --Q 0.707

# 校验
xy-forge validate src/my_bass_boost.c

# 移植到 D3
xy-forge port src/my_bass_boost.c \
    --from XiDSP-D2 --to XiDSP-D3

# 构建 UI
xy-forge ui build ui-proj-042.xyui --target electron --platform win32

# AI 辅助
xy-forge ai gen fx-eq \
    --description "低频增强 60Hz +3dB" \
    --target XiDSP-D2

# 发布到仓库
xy-forge repo publish ./dist --message "Release v1.0.0"

5.4 退出码

Code	含义
0	成功
1	参数错误
2	文件不存在
3	模板不存在
4	校验失败
5	网络错误（AI / 仓库）
6	认证失败
99	内部错误

6. 模板扩展 API

6.1 自定义模板开发

用户可在 %APPDATA%/Xisound/XiForge/templates/ 添加自定义模板：

my-custom-template/
├── manifest.json
├── src.c.hbs
├── params.schema.json
├── test.cpp.hbs
└── doc.md.hbs

6.2 Handlebars Helper

XiForge 提供的自定义 Handlebars Helper：

Helper	用途
`{{upper x}}`	大写
`{{snakeCase x}}`	`CamelCase` → `snake_case`
`{{xiAlgoVersion}}`	注入当前 XiAlgo ABI 版本
`{{targetDsp}}`	注入 target DSP 常量
`{{#ifTarget "XiDSP-D2"}}...{{/ifTarget}}`	条件分支

6.3 manifest.json Schema

详见 spec.md §2 CodeGen 子系统。校验：

xy-forge validate-template my-custom-template/

7. 审计日志 API

7.1 查询

端点：GET /api/v1/audit?from=<iso>&to=<iso>&user=<id>

响应：

{
  "entries": [
    {
      "timestamp": "2026-05-05T10:00:00Z",
      "user": "alice",
      "action": "codegen.generate",
      "target": "fx-eq / MyBassBoost",
      "result": "success"
    },
    ...
  ],
  "total": 1234,
  "next_cursor": "..."
}

7.2 导出

端点：POST /api/v1/audit/export 响应：返回 CSV / JSON 文件下载 URL（符合 GDPR 导出要求）。

8. 遥测（可选 · 默认关闭）

8.1 事件类型

app.start / app.crash
codegen.generate.success / .fail
uieditor.export.success
ai.request.success / .fail

8.2 开关

用户可在 Settings 中开启 / 关闭。开启后： - 遥测数据脱敏后聚合上报 - 不包含任何代码内容 / 工程名

9. 兼容性

9.1 API 版本策略

同 Major 版本内向后兼容（新字段允许 · 现有字段不删）
破坏性变更升 Major · 提前 2 个 Minor 版本公告
旧 Major 保留至少 12 个月支持

9.2 .xyui Schema 兼容

version 字段严格检查
高版本读低版本 → 支持（补默认值）
低版本读高版本 → 拒绝并提示升级

10. 附录

10.1 完整 OpenAPI Schema

详见独立附录 D3-execution/xiforge-openapi.yaml（Phase 3 后续批次发布）。

10.2 关联文档

10.3 外部标准参考

JSON-RPC 2.0 Specification
JSON Schema Draft-07
OpenAPI 3.1

10.4 版本历史

版本	日期	要点
v1.0	2026-05-05	首版 · CodeGen REST + UIEditor REST + JSON-RPC 2.0 + XiMind WS + CLI

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

XiForge API 文档 v1.0

XiForge API 文档 v1.0

1. CodeGen REST API

1.1 基础信息

1.2 端点清单

1.3 POST /generate

1.4 POST /validate

1.5 GET /templates

1.6 POST /port

1.7 错误码

2. UIEditor REST API

2.1 端点清单

2.2 POST /uieditor/project/create

2.3 POST /uieditor/export/electron

2.4 POST /uieditor/preview

3. JSON-RPC 2.0 插件协议（XiStudio 联动）

3.1 协议基础

3.2 XiStudio → XiForge 方法

3.3 XiForge → XiStudio 方法

3.4 错误格式

4. XiMind AI 联动 API

4.1 同步调用

4.2 流式调用

4.3 限流

5. xy-forge CLI

5.1 安装

5.2 命令总览

5.3 常用示例

5.4 退出码

6. 模板扩展 API

6.1 自定义模板开发

6.2 Handlebars Helper

6.3 manifest.json Schema

7. 审计日志 API

7.1 查询

7.2 导出

8. 遥测（可选 · 默认关闭）

8.1 事件类型

8.2 开关

9. 兼容性

9.1 API 版本策略

9.2 .xyui Schema 兼容

10. 附录

10.1 完整 OpenAPI Schema

10.2 关联文档

10.3 外部标准参考

10.4 版本历史

1.3 `POST /generate`

1.4 `POST /validate`

1.5 `GET /templates`

1.6 `POST /port`

2.2 `POST /uieditor/project/create`

2.3 `POST /uieditor/export/electron`

2.4 `POST /uieditor/preview`

5. `xy-forge` CLI