---
name: aidc-sdk
description: Build, test and publish AIDC Nexus apps with the AIDC Developer SDKs and the aidc CLI; call AIDC models (LLM, vision, speech, Jev) through the OpenAI-compatible API with per-company billing; connect apps to enterprise datasets and AIDC agents. Use when a task mentions AIDC Developer, AIDC Nexus apps, aidc CLI, ai-dc.ai, vision/voice/video/model/data/publish/connect SDK, 瑕疵检测, 会议纪要, ERP 报告, or publishing an app to Nexus.
---

# AIDC Developer SDK · 智能体操作手册

AIDC Developer：七个 SDK（视觉、语音、视频、模型、数据、发布、连接）+ `aidc` CLI + OpenAI 兼容模型 API。在 Developer 里开发与测试，发布到 Nexus。文档索引：https://www.ai-dc.ai/developer/llms.txt （每页可 `curl …/developer/docs/<页>.md`）。

## 0. 准备

```bash
curl -fsSL https://www.ai-dc.ai/developer/cli/install.sh | sh     # 需要 Node ≥ 18
aidc --version
```

登录（需要一个人在浏览器里批准一次）：

```bash
aidc login --no-wait --json    # 输出 {"event":"authorize","url":…,"userCode":…}；把 url 交给人
aidc login --continue --json   # 人批准后运行，完成登录
aidc whoami --json
```

无人值守时用环境变量 `AIDC_API_KEY=aidc-dk-…`。**永远不要把 aidc-dk- 开发者 Key 写进前端代码或提交到仓库。**

## 1. 做一个 Nexus 应用

```bash
aidc app init <slug> --template camera|voice|data|blank --title "<标题>" --json
```

生成 `aidc.app.json` + `index.html` + `app.js` + `style.css`。规则：

- 单页应用；包内用**相对路径**；SDK 用绝对路径 `import { vision, voice, video, model, data, connect } from "/developer/sdk/v1/aidc.js";`
- 清单 `aidc.app.json`（Schema：https://www.ai-dc.ai/developer/schemas/aidc.app.schema.json）：
  - `permissions.camera / microphone`：用到才开；
  - `version`：**版本号**（`1.0.0` 起，语义化）；改了任何东西（文件或清单）就要升，否则部署返回 `version_conflict`；
  - `models`：列出会调用的模型（票据只放行这些）；`datasets`：会读的数据集；`streams`：会订阅的实时数据流（同一命名空间）；
  - `storage` 只有 `{"type":"none"}`（Nexus 应用无状态）；
  - `limits`：`dailyTokens`、`requestsPerMinute`、`realtimeSessionsPerDay`；
  - 第三方脚本只能来自 `cdn.jsdelivr.net` / `cdnjs.cloudflare.com`，并写进 `cdn`。
- 包 ≤ 200 个文件、≤ 3 MB；不要有 `_v/` 目录（保留）。

## 2. 校验、预览、发布

```bash
aidc app check <dir> --json      # 本地校验，与服务端同一份契约；失败时 details.issues 逐条列出
aidc app dev <dir>               # http://localhost:5173，API 经本机代理（Key 不进浏览器）
aidc app deploy <dir> --json     # → test 通道；返回 test（Developer 预览）与 production 地址
aidc app publish <dir> --notes "<这次改了什么>" --json    # 把 test 上测过的版本发到 Nexus
aidc app rollback <slug> --version 1.1.0 --notes "<为什么>"
aidc app status <slug> --json    # 每个版本的版本号、构建序号、更新状态（live / testing / tested / superseded / rolled_back / untested）
aidc app history <slug> --json   # 发布记录
```

- 发布是**幂等**的：内容相同不产生新版本，出错直接重试。
- 先预演：任何写命令加 `--dry-run`。
- production 只接受进过 test 的版本；退出码 6 = 冲突（例如版本未测）。

## 3. SDK 速查

```js
// 视觉
const camera = await vision.openCamera({ video });            // 或 vision.pickImage()
const photo = await camera.capture();
const r = await vision.inspect(photo, { task: "检查什么", criteria: "什么算不合格" });   // gpt-6-luna
// r = { verdict: "pass"|"fail"|"uncertain", summary, findings: [{label, severity, confidence, box}] }
const canvas = await vision.annotate(photo, r.findings);

// 语音
const s = await voice.startTranscription({ languages: ["zh","en"], onPartial, onFinal });   // 每场 ≤ 5 分钟
const t = await voice.translate(text, ["ja","en","ar-EG","bn"]);
const m = await voice.minutes(transcript);                    // {title, summary, decisions, actionItems, topics, markdown}

// 视频
const v = await video.openVideo({ video }); v.sampleFrames(3000, onFrame);
await video.analyze(file, { task, everySeconds: 5, transcribe: true });

// 模型（OpenAI 兼容）
await model.text({ model: "deepseek-flash", messages });
await model.json({ model: "gpt-5.4-mini", messages, schema: { name, schema } });
await model.decide(state, { q: { instructions, criteria: { a: "…", b: "…" } } });           // Jev

// 数据
data.parseCsv(text); data.groupBy(rows, "k", { total: ["amount","sum"] }); data.barChartSvg(points);

// 连接
await connect.datasets.report("aidc-demo-erp", "overview");   // 只含聚合
// 实时数据流：先全量、后增量，断线带序号续传；publisher.live=false / status=source_unreachable 要在界面上提示
connect.stream("orders").subscribe({ onUpdate: ({ rows, upserted }) => render(rows), onStatus: ({ publisher }) => badge(publisher) });
const agent = connect.agent(agentKey); await agent.send(text, { sessionId });   // 访客自带 aidc-sk- Key
```

## 4. 直接调模型（不用 SDK）

OpenAI 兼容：`base_url = https://www.ai-dc.ai/api/v1/models`，`api_key = $AIDC_API_KEY`。支持 `/chat/completions`（文本、`image_url`、`stream`、`response_format`）、`/audio/transcriptions`（≤ 4 MB）、`/models`。目录：`aidc models --json`。用量按调用方公司记账。

## 5. 出错怎么办

| 退出码 / 错误码 | 处理 |
| --- | --- |
| 3 / `unauthorized` | 重新 `aidc login` 或检查 `AIDC_API_KEY` |
| 4 / `forbidden` | 清单没声明模型 / 数据集，或 Key 不能写这个命名空间 |
| 2 / `bundle_invalid` | 按 `details.issues` 逐条修 |
| 6 / `version_not_tested` | 先 `aidc app deploy`（进 test），再 publish |
| 7 / `rate_limited` · `quota_exhausted` | 等 `retryAfterSeconds`；额度按 UTC 自然日恢复 |
| 8 / `model_upstream_failed` | 上游故障，稍后重试 |