# 智能体接入

AIDC Developer 为智能体（Claude Code、Codex、AIDH / Hermes、LangChain 或任何自研框架）准备的接入方式——全部是行业已有的标准，不需要安装 AIDC 专用插件。

## 1. 读文档

| 文件 | 用途 |
| --- | --- |
| [`/developer/agent-ready.md`](https://www.ai-dc.ai/developer/agent-ready.md) | 上手说明：人对你说 `帮我接入 AIDC Developer：https://ai-dc.ai/developer/agent-ready.md`（官网 /developer 的「Copy to Adis」复制的就是这句），照它装 CLI、登录、装 Skill、做出第一个应用 |
| [`/developer/llms.txt`](https://www.ai-dc.ai/developer/llms.txt) | 文档索引（llms.txt 约定） |
| `/developer/docs/<页>.md` | 每页的 Markdown 原文，`curl` 即可读 |
| [`/developer/skills/aidc-sdk/SKILL.md`](https://www.ai-dc.ai/developer/skills/aidc-sdk/SKILL.md) | Agent Skills 格式的操作手册，放进智能体的 skills 目录即可 |
| [`/developer/openapi.json`](https://www.ai-dc.ai/developer/openapi.json) | Developer 与模型 API 的 OpenAPI 3.1 契约 |
| [`/developer/schemas/aidc.app.schema.json`](https://www.ai-dc.ai/developer/schemas/aidc.app.schema.json) | 应用清单 JSON Schema |

## 2. 拿凭证

AIDC 密码只由人本人输入：智能体不要索要、转述或保存密码。

- **人就在这台机器的终端前**（Claude Code、Codex 这类跑在人电脑上的智能体）：请人在自己的终端里运行 `aidc login`、输入账号和密码；登录后 Key 存在 `~/.aidc/config.json`，你直接用 `aidc` 即可。你自己执行的命令不是交互终端，替人运行 `aidc login` 会立即以退出码 2 报错。
- **身边没有终端**（客户箱上的智能体，经 IM 和人对话）：用浏览器批准，把链接交给人——

```bash
aidc login --browser --no-wait --json    # 输出授权链接，交给人在浏览器里批准
aidc login --continue --no-wait --json   # 查一次：没批准退出码 3，批准了完成登录
```

等人批准时别干等：先做不需要登录的事（读文档、写代码；`aidc` 命令都要登录，包括 `aidc app check`），每做完一步查一次；一条终端命令里别循环超过一两分钟。

无人值守：设置环境变量 `AIDC_API_KEY=aidc-dk-…`。开发者 Key 代表一家公司，用量记在这家公司。凭证只来自人登录的 `aidc login` 或人交给你的 Key，不要在机器上翻 `.env` 找别人的 Key。

## 3. 调模型：OpenAI 兼容

```python
from openai import OpenAI
client = OpenAI(base_url="https://www.ai-dc.ai/api/v1/models", api_key=os.environ["AIDC_API_KEY"])
```

在 Hermes / AIDH 的配置里，同样只需一个 OpenAI 兼容的 provider：

```yaml
model:
  provider: custom
  base_url: https://www.ai-dc.ai/api/v1/models
  default: deepseek-flash
```

## 4. 调智能体：OpenAI 兼容 Agent API

`https://api.ai-dc.ai/v1/chat/completions`，`Authorization: Bearer aidc-sk-…`（Agent Key），`model` 是智能体；用 `session_id` 续接会话。这是 AIDC 智能体对外的唯一执行接口，Adis 用的也是它。

## 5. 做应用：CLI

智能体开发 Nexus 应用的标准循环：

```bash
aidc app init my-app --template camera --json
# …编辑文件…
aidc app check my-app --json          # 本地校验（与服务端同一份契约）
aidc app deploy my-app --json         # → test 通道，返回 Developer 预览地址
aidc app publish my-app --json        # → production，返回 Nexus 地址
```

给人看的预览就是 `aidc app deploy` 返回的 Developer 预览地址。`aidc app dev` 起的是本机的 localhost，只有和你在同一台电脑上的人打得开；在远程机器上干活的智能体，不要自己伪造 SDK 或起本地服务器来「预览」——包里带 SDK 副本，部署会被拒收。

所有命令非交互、JSON 输出、退出码稳定（见 [CLI](cli.md)）；发布是幂等的，出错直接重试。

界面一律用[界面 SDK](ui.md)：页面引 `/developer/sdk/v1/ui.css`，照登记表里的示例标记写（`aidc ui components --json`，或直接读 `https://www.ai-dc.ai/developer/sdk/v1/ui.json`：令牌、每个组件的类与示例、`ui` 模块的函数），不要在应用里另写一套按钮与表单样式。

## 6. 读写企业数据：Semantic

智能体不直连 ERP，读写都在 [Semantic](semantic.md)（照 Palantir Ontology）：先读本体，读用对象集，改数据只走 Action，要实时就订阅：

```bash
aidc semantic ontology --json                                                        # 本体全貌：对象类型、属性、链接、Action、数据源
aidc semantic objects production.order_line --where '{"status":"异常"}' --order-by gap:desc --json
aidc semantic apply production.flag_issue --param __object="100000012345|L01-05" --param issue=缺料 --param severity=异常 --validate-only --json
aidc semantic subscribe production.order_line --where '{"status":"异常"}' --json      # 数据一变就收到（每行一个 JSON）
aidc semantic describe --markdown                                                    # 给大模型的说明书（同义词、Action），可以直接放进系统提示词
```

改数据用 Action：参数校验、权限、留痕都由平台做，出错会告诉你哪一项不对（先 `--validate-only` 试）。旧命令（`aidc data query / watch`、`aidc semantic act`）照样能用。

**本体由你来建，但要经过人。** 发现本体里缺东西（问题答不出、接了新的数据源）时，不要直接改 main：设 `AIDC_AGENT_ID=<你的智能体 id>`，在分支上改，开提案，把审核网页地址交给人。

```bash
export AIDC_AGENT_ID=ops-agent
aidc semantic branch create add-department
aidc semantic branch modify add-department ./ontology --dry-run --json      # 试跑：校验结果
aidc semantic branch modify add-department ./ontology --json
aidc semantic objects agent --branch add-department --json                  # 在分支上验证你的问题能答了
aidc semantic branch propose add-department --title "加部门对象类型" --trigger "问「采购部有几个智能体」答不出" --self-test "分支上能答：3 个" --json
# 输出里的 reviewUrl 交给人：人逐项批准、合并。你自己不能批准，任何 Key 都不能。
```

## 7. 生成 3D 世界：建模 SDK

花钱的调用先估价、先 dry-run、先用试稿模型；额度不够（`quota_exhausted`，退出码 7）就停下来告诉人，不要换 Key 重试：

```bash
aidc modeling estimate -m marble-1.0-draft --input text --json
aidc modeling generate --text "一个整洁的装配工位…" --dry-run --json   # plan.decision.ok 为 true 才继续
aidc modeling generate --text "一个整洁的装配工位…" --json             # 同样的请求会复用已有世界，不重复花钱
aidc modeling anchors <id> --file anchors.json --if-rev 0 --json        # 位置（米）绑语义层对象
```

生成的世界是「看起来合理」的空间，不是测绘：给锚点标 `verified: false`，直到有人核对过位置与设备身份。见 [建模 SDK](modeling.md)。

## 8. 让应用持续变好：自进化

```bash
aidc log summary <应用> --json        # 使用、反馈、操作、版本状态
aidc billing summary --app <应用> --json   # 花了多少：本月、累计、按模型、月底预测、预算（金额是美元标价，未计价 ≠ 0 元）
aidc evolve evidence <应用> --json   # 证据：反馈、操作、数据画像、用户在应用里做过的改进
aidc evolve suggest <应用> --file 口径.md --conversation 群聊.txt --json
aidc evolve apply <提案 id>          # 语义类 → 自动发新语义版本
```

用户也会直接在应用里提改进（同一个 [自进化 SDK](evolve.md) 的另一半）：「对话框变大」这类立刻生效，改不了的（加功能）变成上面的应用类提案。你这一侧：

```bash
aidc evolve list <应用> --status proposed --json     # 成员提交给所有人、等采纳的改进
aidc evolve adopt <应用> <id>                        # 采纳 → 对所有人生效（--dry-run 预演）
aidc evolve bake <应用> --dir <目录> && aidc app deploy <目录>   # 全员改进固化进代码，覆盖层清空
```

## 9. 用别人做好的应用：复制即用

每个 Nexus 应用都是一组 Skills 加一组 APIs（[应用（Apps）](apps.md)）。人在应用页点「复制给智能体」，交给你的是一句话：

```text
帮我用 AIDC 应用「报价工作流」：https://www.ai-dc.ai/nexus/cell-aidc/apps/quote-workflow/about.md
```

读这份说明（公司应用要凭证：`aidc app about <命名空间>/<slug>`，或带 `Authorization: Bearer $AIDC_API_KEY` 请求），然后照其中的 Skill 做：

```bash
aidc app apis cell-aidc/quote-workflow                    # 有哪些 API、参数、返回
aidc app call cell-aidc/quote-workflow run --param rfq_no=RFQ-2609-006 --preview --json   # 写入先预演
aidc app call cell-aidc/quote-workflow get_run --param id=<运行 id> --json
```

写入（动作、工作流正式运行）一律先 `--preview`，把计划给人看，确认后再正式调用；结论只用 API 返回的内容。支持 MCP 的客户端也可以把公司应用接成 MCP 服务器：`…/api/v1/developer/apps/<命名空间>/<slug>/mcp`（工具 = APIs，prompts = Skills，凭证是开发者 Key）。

## 规划中

- MCP：把全平台的 OpenAPI 投影成 MCP 工具（每个应用自己的 MCP 服务器已经有了，见上一节）。
- A2A Agent Card：等身份层定稿。