# 接入 AIDC Developer

这份说明写给你——一个 AI 智能体（Adis、Claude Code、Codex、AIDH / Hermes 都行）：替把它交给你的人装好 AIDC Developer、登录，做出并发布第一个应用。读一遍，然后照着做。对方要的是你动手，不是把这份文档复述一遍；回话用对方的语言。

AIDC Developer 是 AIDC 的智能体开发平台：浏览器 SDK、`aidc` 命令行、OpenAI 兼容的模型 API。应用在 Developer 里开发和测试，发布到 Nexus——公司的人在手机或网页上打开就用。企业数据在语义层里读写，ERP / MES 永远只读。所有用量记在登录时选的那家公司。

## 1. 先判断对方要什么

| 对方想要 | 做 |
| --- | --- |
| 做一个应用给公司的人用（拍照质检、会议纪要、看板、报表……），或者改一个已有的应用 | 第 2、3、4 节 |
| 在自己的代码或智能体里调 AIDC 的模型（文本、视觉、转写） | 第 2 节，然后第 5 节 |
| 读写公司的业务数据（订单、设备、库存……），或者数据一变就自动做事 | 第 2 节，然后第 6 节 |
| 用一个已经做好的应用（对方给了「帮我用 AIDC 应用「…」：…/about.md」） | 第 2 节，然后第 7 节 |

实在分不清，只问一句：「是做一个应用发到 Nexus，还是在你自己的程序里调模型？」不要默认全都铺开。

## 2. 安装、登录、装 Skill

安装 `aidc` 命令行（macOS / Linux，需要 Node.js 18 以上）：

```sh
curl -fsSL https://www.ai-dc.ai/developer/cli/install.sh | sh
```

安装输出的最后一行 `下一步：… login` 就是这台机器上能用的命令：`aidc` 不在 PATH 上时它给完整路径 `~/.aidc/bin/aidc`，照它敲，不用去改 shell 配置。没有 Node 就先装 Node（或者请对方装）。Windows 没有安装脚本：在 WSL 里照上面装，或者下载单文件 https://www.ai-dc.ai/developer/cli/aidc.mjs ，用 `node aidc.mjs …` 代替 `aidc …`。

先看是不是已经登录：

```sh
aidc whoami --json
```

输出了账号和公司，就跳到下一节。没登录（退出码 3）时，按对方的处境选一种登录。AIDC 密码只由对方本人输入：不要索要、转述或保存密码。

- **对方就在这台电脑前，会用终端**：请对方在自己的终端里运行 `aidc login`（`aidc` 不在 PATH 上，就把安装输出给的完整路径告诉对方），输入 AIDC 账号和密码。你执行的命令不是交互终端，替对方运行 `aidc login` 会立即以退出码 2 报错——这是设计如此，不是故障。
- **对方不用终端，或者你在远程机器上、经聊天和对方说话**：用浏览器批准。

```sh
aidc login --browser --no-wait --json    # {"event":"authorize","url":…,"userCode":…}
aidc login --continue --no-wait --json   # 只查一次：没批准 → authorization_pending、退出码 3；批准了 → logged_in
```

把 `url` 和授权码交给对方：在浏览器里打开（没登录 AIDC 会先登录）、核对授权码、点「批准」。链接 10 分钟内有效，过期了就重新 `aidc login --browser --no-wait --json`。不要想办法绕过批准这一步。等的时候别干等：先做不需要登录的事（读文档、写代码；`aidc` 命令都要登录，包括 `aidc app check`），每做完一步查一次；一条终端命令里不要循环等超过一两分钟。

- 还没有 AIDC 账号：请对方在 https://www.ai-dc.ai/login 点「注册」。用 AIDC Developer 做任何事都要登录，至少是一家公司的 member：公司发的授权码在 https://www.ai-dc.ai/account 输入（登录或批准时说不属于任何公司，就是缺这一步）；部署、发布还要 developer 授权码。没有授权码就找公司里管 AIDC 的人要。这一步你替不了。
- 环境里已经有 `AIDC_API_KEY=aidc-dk-…`（CI，或者对方明确交给你的 Key）：不用登录，`aidc` 会读它。
- 凭证只有这几个来源。不要翻 `.env` 或别的项目的配置去找 Key；开发者 Key 永远不写进前端代码、不提交进仓库。

最后装 Skill：完整的操作手册（SDK 速查、应用清单、错误码），之后每次碰到 AIDC 的活都用得上。

https://www.ai-dc.ai/developer/skills/aidc-sdk/SKILL.md

- Adis：用 `skill_manage`（`action=create`，`skill_md` 填这份文件的全文）暂存，请对方在应用里的卡片上确认。
- Claude Code：存成 `~/.claude/skills/aidc-sdk/SKILL.md`。
- Hermes / AIDH：存成 profile 下的 `skills/aidc-sdk/SKILL.md`。
- 别的运行时放进它自己的 skills 目录；不支持 Skill 就把它读一遍，下面几节的细节都在里面。

## 3. 做第一个应用

```sh
aidc app init <名字> --template camera --title "<标题>" --json
```

`<名字>` 用小写英文和连字符（比如 `shelf-check`）。一个应用是一组 Skills 加一组 APIs，界面可选（https://www.ai-dc.ai/developer/docs/apps）。模板照对方说的场景挑：只要教智能体用现成的 AIDC 能力把事做完用 `skills`（没有界面），拍照判断用 `camera`，录音转写用 `voice`，表格看板用 `data`，都不像就用 `blank`。生成 `aidc.app.json`（应用清单：介绍、示例说法、用哪些 SDK、模型、数据，每天的额度）和 `skills/<名字>/SKILL.md`（一条 Skill：什么时候用、步骤、输出、不能做的事），有界面的模板还有 `index.html`、`app.js`、`style.css`。先把 Skill 的 `description` 和正文改成对方真正要做的事。

写代码时守住这几条（细节在 Skill 里）：

- SDK 只从绝对路径引：`import { ui, vision } from "/developer/sdk/v1/aidc.js";`；界面用 `/developer/sdk/v1/ui.css` 的现成组件，不另写一套按钮和弹窗。
- 用到的每个 SDK 登记进清单的 `sdk`，调用的模型登记进 `models`；没登记的，部署时直接拒收。
- 改了任何东西就升清单里的 `version`（语义化版本），否则部署返回 `version_conflict`。
- 不要把 SDK 复制进应用目录，也不要为了「预览」自己写一份假的 SDK——包里带 SDK 副本会被拒收。

```sh
aidc app check <目录> --json       # 本地校验，与服务端同一份契约；不通过就照 details.issues 逐条改
```

## 4. 给对方看，再发布

```sh
aidc app deploy <目录> --json      # 进 test 通道，返回 Developer 预览链接
```

把返回的 Developer 预览链接交给对方，这就是预览——`aidc app dev` 起的 localhost 只有和你在同一台电脑上的人打得开。同样的文件重复部署不产生新版本，出错直接重试；想先看会发生什么，加 `--dry-run`。

对方看过、说可以了，再发布到 Nexus。发布之后公司的人都能打开，所以先问一句：

```sh
aidc app publish <目录> --notes "<这次改了什么>" --json
aidc app rollback <名字> --version <版本号> --notes "<为什么>"    # 出了问题就回退
```

## 5. 只调模型

模型 API 与 OpenAI 兼容：任何 OpenAI SDK 改 `base_url` 就能用，用量记在 Key 所属的公司。

```python
import os
from openai import OpenAI

client = OpenAI(base_url="https://www.ai-dc.ai/api/v1/models", api_key=os.environ["AIDC_API_KEY"])
client.chat.completions.create(model="deepseek-flash", messages=[{"role": "user", "content": "你好"}])
```

`AIDC_API_KEY` 是开发者 Key（`aidc-dk-…`，模型直连要 developer；member 通过应用使用）：这台机器上的程序可以用 `aidc login` 拿到的那一把（`~/.aidc/config.json` 的 `apiKey`），放进环境变量，不写进代码。先用 `aidc model chat -m deepseek-flash "你好"` 确认能通；能用哪些模型：`aidc models --json`。

## 6. 公司的业务数据：Semantic

不要直连 ERP。读写都在 Semantic（AIDC 的数据平台）：先看有什么，再查，再改。

```sh
aidc semantic ontology --json                # 有哪些 Object Type、属性、链接、能做哪些 Action
aidc semantic objects <类型> --where '{"status":"异常"}' --json
aidc semantic apply <Action> --param 名=值 --validate-only --json   # 改数据只用 Action：先只校验，再去掉 --validate-only 执行；校验、权限、留痕由平台做
```

没有 Object Type，就是这家公司的数据还没接进来：接数据源（ERP / MES 旁边只读的发布端 → 数据流 → Object Type 定义里的 `datasources`）要对方公司的 IT 配合，先告诉对方，别自己去连 ERP；做法见 https://www.ai-dc.ai/developer/docs/connect.md 。数据一变就要做的事，用 Semantic 的自动化（Automate，`trigger.change`），不写定时轮询：https://www.ai-dc.ai/developer/docs/workflow.md 。

## 7. 用一个已经做好的应用

对方给你的是一句「帮我用 AIDC 应用「报价工作流」：https://www.ai-dc.ai/nexus/cell-aidc/apps/quote-workflow/about.md」：那是这个应用写给你的说明——它的 APIs、每条 Skill 的全文、示例说法、规矩。读它（公司应用要凭证：`aidc app about <命名空间>/<应用>`），然后照 Skill 做：

```sh
aidc app apis <命名空间>/<应用> --json                           # 有哪些 API、参数、返回
aidc app call <命名空间>/<应用> <API> --param 名=值 --preview --json   # 会写入的先预演，给对方看
aidc app call <命名空间>/<应用> <API> --param 名=值 --json            # 对方确认后再正式调用
```

结论只用 API 返回的内容；写入、审批、发送之前先让对方确认。

## 8. 出错时

退出码：0 成功、2 参数不对、3 没登录、4 没权限、5 不存在、6 冲突、7 限流或额度用完、8 上游故障。加 `--json` 时错误里有 `code` 和 `details`。

- 敲 `aidc` 说找不到命令：用安装输出最后一行给的完整路径。
- 你运行 `aidc login` 立即以退出码 2 结束：它要在交互终端里输密码。请对方在自己的终端里运行，或者改用 `aidc login --browser --no-wait --json`；不带 `--no-wait` 的 `--browser` 会一直等到批准或过期（最长 10 分钟），有超时的终端会把它掐断。
- 部署被拒（`bundle_invalid`）：照 `details.issues` 逐条改，最常见的是用了没登记的 SDK、忘了升 `version`。
- `forbidden`：清单没声明这个模型或数据集，或者这把 Key 不能写这个命名空间。
- `quota_exhausted`：额度用完了。停下来告诉对方，不要换 Key，也不要循环重试。

## 接下来读

全部文档：https://www.ai-dc.ai/developer/llms.txt （每一页都有 Markdown 原文）。

- 快速开始：https://www.ai-dc.ai/developer/docs/quickstart.md
- 智能体接入（凭证、模型、Agent API、语义层）：https://www.ai-dc.ai/developer/docs/agents.md
- 命令行一览：https://www.ai-dc.ai/developer/docs/cli.md
- 应用清单与发布：https://www.ai-dc.ai/developer/docs/publish.md
- 样板应用（源码可以照着写）：https://www.ai-dc.ai/developer/docs/samples.md
- 模型与计费：https://www.ai-dc.ai/developer/docs/model.md ，价目 `aidc semantic usage prices --json`
- OpenAPI：https://www.ai-dc.ai/developer/openapi.json