智能体接入

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

1. 读文档

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

2. 拿凭证

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

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

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 兼容

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：

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 应用的标准循环：

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）；发布是幂等的，出错直接重试。

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

6. 读写企业数据：Semantic

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

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>，在分支上改，开提案，把审核网页地址交给人。

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 重试：

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。

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

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 的另一半）：「对话框变大」这类立刻生效，改不了的（加功能）变成上面的应用类提案。你这一侧：

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

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

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

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

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

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：等身份层定稿。

本页由 developer/docs/agents.md 生成 · Markdown 原文 · llms.txt