XiStudio · API Reference

XiStudio API 文档 v1.0

CLI · REST · gRPC · Plugin SDK · 认证 · 错误码 · 示例

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

每一个接口都有契约 · 每一次调用都可追溯

4

接口通道

JWT

认证方式

SemVer

兼容承诺

XiStudio API 文档 v1.0

摘要

本文档提供 XiStudio IDE 完整的外部接口参考，覆盖 CLI（命令行）、REST API、gRPC、Plugin SDK 四个通道。与 spec.md §5 的 API 概述互补：spec 给"有哪些接口"，本文给"怎么调、返回什么、错了怎么办"。目标读者：Enterprise / IDM 客户集成工程师、插件开发者、CI/CD 脚本作者。

1. 通用约定

1.1 版本与兼容性

API 版本遵循 SemVer：v1.x 保证向后兼容
路径版本号：/api/v1/...（REST） · package xistudio.v1（gRPC）
Deprecation 至少提前 12 个月通知，保留 1 个大版本过渡期

1.2 认证方式

通道	认证	适用版本
CLI	本地 License 文件	全版本
REST	Bearer Token（JWT）	Enterprise+
gRPC	mTLS + JWT	IDM
Plugin SDK	签名验证	Pro+（签名） / Enterprise（强制）

1.3 通用错误码

Code	HTTP	含义	处理建议
`OK`	200	成功	—
`INVALID_ARGUMENT`	400	参数错误	检查请求格式
`UNAUTHENTICATED`	401	未认证	刷新 Token
`PERMISSION_DENIED`	403	无权限	确认 License 等级
`NOT_FOUND`	404	资源不存在	检查 ID
`ALREADY_EXISTS`	409	资源冲突	使用 PUT 覆盖
`RESOURCE_EXHAUSTED`	429	限流	指数退避重试
`INTERNAL`	500	内部错误	联系支持
`UNAVAILABLE`	503	服务不可用	稍后重试

1.4 响应格式（REST）

{
  "code": "OK",
  "message": "",
  "data": { },
  "trace_id": "abc123"
}

2. CLI 命令行接口

2.1 全局选项

xistudio [command] [options]

全局选项:
  --version             显示版本
  --help, -h            显示帮助
  --log-level <level>   日志级别（trace/debug/info/warn/error）
  --no-color            禁用彩色输出
  --quiet, -q           静默模式
  --license <path>      指定 License 文件路径

2.2 核心命令

`xistudio build`

编译 XiStudio 项目为固件。

xistudio build <project.xiproj> [options]

选项:
  --output, -o <dir>          输出目录（默认：project/build）
  --target <chip>             目标芯片（默认：xidsp-d1）
  --config <debug|release>    构建配置（默认：release）
  --no-sign                   跳过签名（仅 Debug）
  --parallel <N>              并行度（默认：CPU 核数）

返回码：

0 成功
1 编译错误
2 参数错误
3 License 问题

`xistudio flash`

烧录固件到 XiDSP 设备。

xistudio flash <firmware.xifw> [options]

选项:
  --port <name>               串口 / USB 设备名（默认：自动检测）
  --interface <usb|uart|jtag> 烧录接口（默认：usb）
  --verify                    烧录后校验
  --erase-first               烧录前擦除

`xistudio simulate`

位精确仿真项目。

xistudio simulate <project.xiproj> [options]

选项:
  --input <audio.wav>         输入音频
  --output <result.wav>       输出音频
  --duration <sec>            最大仿真时长
  --profile                   同时输出性能 Profile

`xistudio lint`

静态检查项目。

xistudio lint <project.xiproj> [--fix]

2.3 CI/CD 友好选项

--json 输出结构化结果（便于脚本解析）
--exit-on-warn 警告即失败（严格模式）
环境变量：XISTUDIO_LICENSE / XISTUDIO_CACHE_DIR

3. REST API（Enterprise+）

3.1 Base URL

https://<enterprise-server>/api/v1

所有请求必须带 Authorization: Bearer <JWT> 头。

3.2 认证

`POST /api/v1/auth/token`

用账号密码换 JWT Token。

POST /api/v1/auth/token
Content-Type: application/json

{
  "username": "alice@tier1.com",
  "password": "***",
  "license_key": "XS-ENT-XXXX-XXXX"
}

响应：

{
  "code": "OK",
  "data": {
    "access_token": "eyJhbGc...",
    "refresh_token": "eyJhbGc...",
    "expires_in": 3600
  }
}

`POST /api/v1/auth/refresh`

用 refresh_token 换新的 access_token。

3.3 项目管理

`POST /api/v1/projects`

创建项目。

POST /api/v1/projects
Content-Type: application/json

{
  "name": "MyCar-Tuning-2026",
  "template": "empty",
  "target": "xidsp-d1"
}

`GET /api/v1/projects/{id}`

查询项目。

`GET /api/v1/projects`

列表查询。支持 ?owner= ?created_after= ?page= ?limit= 过滤。

`PUT /api/v1/projects/{id}`

更新项目元数据（流图与参数文件走独立接口）。

`DELETE /api/v1/projects/{id}`

删除项目（软删除，30 天内可恢复）。

3.4 构建与仿真

`POST /api/v1/projects/{id}/build`

触发构建，返回任务 ID（异步）。

POST /api/v1/projects/abc123/build
Content-Type: application/json

{
  "target": "xidsp-d1",
  "config": "release"
}

响应：

{
  "code": "OK",
  "data": { "task_id": "t-789", "status": "queued" }
}

`GET /api/v1/tasks/{task_id}`

查询任务状态：queued / running / succeeded / failed / canceled。

`GET /api/v1/tasks/{task_id}/logs`

流式获取构建日志（Content-Type: text/event-stream）。

`POST /api/v1/projects/{id}/simulate`

触发仿真（同步或异步，由 async 参数控制）。

3.5 协作（XiForge 桥接）

POST /api/v1/projects/{id}/share：生成分享链接
POST /api/v1/projects/{id}/comments：添加评论
GET /api/v1/projects/{id}/history：版本历史

3.6 限流

默认：100 req/min per user
构建任务：20 tasks/hour per org
超限返回 429 RESOURCE_EXHAUSTED + Retry-After 头

4. gRPC API（IDM）

4.1 Proto 定义

syntax = "proto3";
package xistudio.v1;

service XiStudioService {
  rpc BuildProject(BuildRequest) returns (stream BuildEvent);
  rpc SimulateProject(SimulateRequest) returns (stream SimulateEvent);
  rpc StreamScope(ScopeRequest) returns (stream ScopeFrame);
  rpc GetProject(GetProjectRequest) returns (Project);
  rpc ListAlgos(ListAlgosRequest) returns (ListAlgosResponse);
}

message BuildRequest {
  string project_id = 1;
  string target = 2;
  string config = 3;
}

message BuildEvent {
  oneof payload {
    BuildProgress progress = 1;
    BuildLog log = 2;
    BuildResult result = 3;
  }
}

4.2 认证

mTLS：双向证书认证
JWT：元数据（metadata）中携带 Authorization: Bearer <JWT>
证书由客户自有 CA 签发，或 Xisound 提供的 IDM 证书服务

4.3 典型场景：客户 CI 里调用

import grpc
from xistudio_pb2 import BuildRequest
from xistudio_pb2_grpc import XiStudioServiceStub

credentials = grpc.ssl_channel_credentials(
    root_certificates=open('ca.crt', 'rb').read(),
    private_key=open('client.key', 'rb').read(),
    certificate_chain=open('client.crt', 'rb').read(),
)
channel = grpc.secure_channel('xistudio.company.com:443', credentials)
stub = XiStudioServiceStub(channel)

req = BuildRequest(project_id='abc123', target='xidsp-d1', config='release')
for event in stub.BuildProject(req):
    print(event)

4.4 性能目标

单 RPC P99 延迟 ≤ 50 ms（LAN）
Streaming 吞吐 ≥ 10 MB/s

5. Plugin SDK

5.1 SDK 语言

语言	包名	用途
TypeScript	`@xisound/xistudio-sdk`	UI 扩展 / 导出器
C#	`Xisound.XiStudio.Sdk`	算法块 / 底层扩展
Python	`xisound-xistudio`	脚本化 / CI 集成

5.2 Manifest 定义

{
  "id": "com.company.my-aec",
  "name": "My AEC Algorithm",
  "version": "1.0.0",
  "type": "algo-block",
  "entry": "main.js",
  "author": "Company Inc.",
  "xistudio_version": ">=1.0.0 <2.0.0",
  "permissions": ["file.read", "network.http"],
  "signature": "BASE64_RSA2048_SIGNATURE_PLACEHOLDER"
}

字段说明：

id：反向域名风格全局唯一标识
type：algo-block / exporter / ui-panel 三选一
entry：入口脚本相对路径（TypeScript 编译产物）
xistudio_version：兼容的 XiStudio 版本范围（SemVer range）
permissions：声明式权限清单（可选值：file.read / file.write / network.http / hardware.serial / `hardware.usb：Enterprise 版必填的 RSA-2048 签名（Base64 编码）

5.3 算法块插件最小示例

import { AlgoBlock, ProcessContext } from '@xisound/xistudio-sdk';

export default class MyAEC extends AlgoBlock {
  static readonly id = 'com.company.my-aec';

  inputs = { mic: 'audio', ref: 'audio' };
  outputs = { out: 'audio' };
  params = {
    filterLength: { type: 'int', default: 512, min: 64, max: 2048 },
  };

  process(ctx: ProcessContext) {
    const { mic, ref } = ctx.inputs;
    // 你的算法实现
    ctx.outputs.out = mic.subtract(ref);
  }
}

5.4 发布到 XiForge 插件市场

本地开发 + 测试（xistudio plugin test）
打包：xistudio plugin pack → my-aec.xiplugin
签名：xistudio plugin sign --key <key>
上传到 XiForge 市场（Enterprise 版）

6. 工程文件格式

6.1 `.xiproj`（项目元数据，XML）

<?xml version="1.0" encoding="UTF-8"?>
<XiProject version="1.0" id="abc123">
  <Name>MyCar-Tuning-2026</Name>
  <Target>xidsp-d1</Target>
  <CreatedAt>2026-05-05T10:00:00Z</CreatedAt>
  <Flows>
    <Flow path="flows/main.xiflow" />
  </Flows>
  <Params>
    <Param path="params/default.xiparam" />
  </Params>
</XiProject>

6.2 `.xiflow`（流图，JSON）

{
  "version": "1.0",
  "nodes": [
    { "id": "n1", "type": "input", "position": [0, 0] },
    { "id": "n2", "type": "eq.parametric", "position": [200, 0],
      "params": { "freq": 1000, "gain": 3.0, "q": 1.4 } },
    { "id": "n3", "type": "output", "position": [400, 0] }
  ],
  "edges": [
    { "from": "n1:out", "to": "n2:in" },
    { "from": "n2:out", "to": "n3:in" }
  ]
}

6.3 `.xiparam` / `.xifw` / `.xiflash`

详见 spec.md §5.3。

7. 示例与食谱（Recipes）

7.1 CI 中编译 + 烧录流水线

#!/bin/bash
# .github/workflows/build.sh

set -e

xistudio lint ./my-car.xiproj
xistudio build ./my-car.xiproj --config release --output ./artifacts
xistudio simulate ./my-car.xiproj \
  --input ./test/pink-noise.wav \
  --output ./artifacts/sim.wav
# 仅当在线设备可用时
if [ -n "$XIFLASH_PORT" ]; then
  xistudio flash ./artifacts/main.xifw --port $XIFLASH_PORT --verify
fi

7.2 Python 脚本批量构建多车型

from xisound_xistudio import Client

client = Client(endpoint='https://xistudio.company.com', token=TOKEN)
for model in ['SUV-A', 'Sedan-B', 'Truck-C']:
    project_id = client.clone_project('template-base', new_name=model)
    task = client.build(project_id, target='xidsp-d1')
    task.wait(timeout=600)
    client.download_artifact(task.id, f'./out/{model}.xifw')

7.3 构建失败自动开 Issue

xistudio build project.xiproj --json > build.json || true
if [ "$(jq -r '.code' build.json)" != "OK" ]; then
  gh issue create --title "Build failed: $(jq -r '.message' build.json)"
fi

8. 常见集成问题

8.1 Token 过期

症状：401 UNAUTHENTICATED
处理：用 refresh_token 换新 token；若 refresh 也过期，重新登录

8.2 限流

症状：429 RESOURCE_EXHAUSTED
处理：读取 Retry-After 头，按指数退避重试（1s → 2s → 4s → ...）

8.3 大工程编译超时

现象：REST 返回 DEADLINE_EXCEEDED
处理：改用异步模式（async=true），轮询 /tasks/{id}

8.4 插件加载失败

常见原因：
- Manifest 中 xistudio_version 范围不匹配
- 签名验证失败（Enterprise 强制签名）
- 入口脚本抛异常（查看 View → Developer → Logs）

9. 附录

9.1 关联文档

9.2 版本历史

版本	日期	要点
v1.0	2026-05-05	首版 · CLI + REST + gRPC + Plugin SDK 完整参考

api.md · D2-P1-TECH-002 · v1.0 · 2026-05-05 · Xisound 研发中心 · 平台软件团队

XiStudio API 文档 v1.0

XiStudio API 文档 v1.0

1. 通用约定

1.1 版本与兼容性

1.2 认证方式

1.3 通用错误码

1.4 响应格式（REST）

2. CLI 命令行接口

2.1 全局选项

2.2 核心命令

xistudio build

xistudio flash

xistudio simulate

xistudio lint

2.3 CI/CD 友好选项

3. REST API（Enterprise+）

3.1 Base URL

3.2 认证

POST /api/v1/auth/token

POST /api/v1/auth/refresh

3.3 项目管理

POST /api/v1/projects

GET /api/v1/projects/{id}

GET /api/v1/projects

PUT /api/v1/projects/{id}

DELETE /api/v1/projects/{id}

3.4 构建与仿真

POST /api/v1/projects/{id}/build

GET /api/v1/tasks/{task_id}

GET /api/v1/tasks/{task_id}/logs

POST /api/v1/projects/{id}/simulate

3.5 协作（XiForge 桥接）

3.6 限流

4. gRPC API（IDM）

4.1 Proto 定义

4.2 认证

4.3 典型场景：客户 CI 里调用

4.4 性能目标

5. Plugin SDK

5.1 SDK 语言

5.2 Manifest 定义

5.3 算法块插件最小示例

5.4 发布到 XiForge 插件市场

6. 工程文件格式

6.1 .xiproj（项目元数据，XML）

6.2 .xiflow（流图，JSON）

6.3 .xiparam / .xifw / .xiflash

7. 示例与食谱（Recipes）

7.1 CI 中编译 + 烧录流水线

7.2 Python 脚本批量构建多车型

7.3 构建失败自动开 Issue

8. 常见集成问题

8.1 Token 过期

8.2 限流

8.3 大工程编译超时

8.4 插件加载失败

9. 附录

9.1 关联文档

9.2 版本历史

`xistudio build`

`xistudio flash`

`xistudio simulate`

`xistudio lint`

`POST /api/v1/auth/token`

`POST /api/v1/auth/refresh`

`POST /api/v1/projects`

`GET /api/v1/projects/{id}`

`GET /api/v1/projects`

`PUT /api/v1/projects/{id}`

`DELETE /api/v1/projects/{id}`

`POST /api/v1/projects/{id}/build`

`GET /api/v1/tasks/{task_id}`

`GET /api/v1/tasks/{task_id}/logs`

`POST /api/v1/projects/{id}/simulate`

6.1 `.xiproj`（项目元数据，XML）

6.2 `.xiflow`（流图，JSON）

6.3 `.xiparam` / `.xifw` / `.xiflash`