让智能体来开发

第 6 课 · 共 6 课 约 7 分钟

llms.txt、SKILL.md、OpenAPI 与 OpenAI 兼容的模型接口:不装插件就能用。

本课目标

读完这一课,你将能够

  • 说出智能体读文档、拿凭证、调模型、发布应用各用哪一件现成标准
  • 用任何 OpenAI SDK 调 AIDC 的模型,只改 base_url
  • 解释 JSON 输出、从不交互、固定退出码与幂等发布,为什么让智能体可以放心重试

不装插件,全是现成标准

编程智能体、AIDH 或任何自研框架,都不用装 AIDC 专用插件,就能读文档、拿凭证、调模型、发布应用。原因很简单:每一件用的都是行业里已有的标准。

LLMS.TXT

文档索引

/developer/llms.txt 列出全部文档;每页都有 Markdown 原文,把 .html 换成 .md 就能读。

SKILL.MD

操作手册

Agent Skills 格式的 SKILL.md,放进智能体的 skills 目录即可。

OPENAPI 3.1

接口契约

/developer/openapi.json 由服务端的契约注册表生成,与代码同步。

OPENAI-COMPATIBLE

模型接口

与 OpenAI 兼容,任何 OpenAI SDK 改 base_url 即可。

CLI

命令行

全部 --json、从不交互、退出码稳定;发布幂等,出错直接重试。

应用清单也有一份公开的 JSON Schema,智能体写 aidc.app.json 时可以照着它校验。

拿凭证:人批准一次

登录需要一个人在浏览器里批准一次,智能体不能替人按下「批准」。它的做法是:先运行 aidc login --no-wait --json,把输出里的授权链接交给人;人批准时顺便选定这把 Key 代表哪家公司,之后智能体再运行 aidc login --continue --json 完成登录。

aidc login --no-wait --json
aidc login --continue --json

无人值守的环境,直接设置环境变量 AIDC_API_KEY。开发者 Key 代表一家公司,智能体用它做的每件事,用量都记在这家公司。

调模型:只改 base_url

AIDC 的模型接口与 OpenAI 兼容:任何 OpenAI SDK 把 base_url 指过来,用开发者 Key 当 api_key,就能调用。有哪些模型可用,运行 aidc models 查看,选你需要的那一个。

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"],
)
reply = client.chat.completions.create(
    model="...",  # an id listed by: aidc models
    messages=[{"role": "user", "content": "Summarize this week's open issues."}],
)

支持的字段包括 messages(文本与图片)、stream、temperature、response_format 等,其余字段会被忽略、不转发。AIDH 的配置也一样,只需要一个 OpenAI 兼容的模型提供方,指向同一个地址。

每次调用都记在调用方所属公司的账上。要找的如果是智能体本身,走的是另一个同样与 OpenAI 兼容的 Agent API:凭证是 Agent Key,model 填智能体,用 session_id 续接会话,Adis 用的也是它。

做应用:一个可以放心重试的循环

智能体开发 Nexus 应用,走一个固定的循环:生成、编辑文件、本地校验、部署到 test、发布到 Nexus。每一步都返回 JSON,部署返回 Developer 预览地址,发布返回 Nexus 地址。

aidc app init my-app --template camera --json
aidc app check my-app --json
aidc app deploy my-app --json
aidc app publish my-app --json

这个循环可以放心重试:命令从不交互,失败时返回错误码,退出码固定;版本按内容寻址,同样的内容重复部署还是同一个版本,通道晋升只是移动指针。网络断了、不确定上一步成没成功,重跑同一条命令就行。

退出码告诉它下一步做什么:3 是未登录,就把授权链接交给人;6 是冲突,例如内容变了却没升版本号,或者要发布的版本还没进过 test。

应用上线之后,智能体还能接着改进它:用 aidc improve evidence 看反馈与使用情况,起草改进提案;人在 Developer 里采纳之后,它再改代码、部署到 test,由人确认后发布。

要点

  • 读文档用 llms.txt 与每页的 Markdown 原文,操作手册是 SKILL.md,接口契约是 OpenAPI 3.1。
  • 登录要人批准一次:--no-wait 把链接交给人,--continue 完成登录。
  • 模型接口与 OpenAI 兼容,改 base_url 即可,用量记在调用方公司。
  • 命令行输出 JSON、从不交互、退出码固定,发布幂等,出错直接重试。
  • 上线之后,智能体可以接着跑改进:它起草提案、改代码,人负责采纳和确认发布。

练一练

让你的智能体接上 AIDC

用你平时在用的智能体或框架,按顺序试三步。

让智能体读取 https://www.ai-dc.ai/developer/llms.txt,挑一页,把地址里的 .html 换成 .md 读原文,再用一句话说出这一页讲什么。

小测

选一个答案,马上看解析。

Q1想让现有的智能体框架调用 AIDC 的模型,最少要改什么?

Q2部署到一半网络断了,智能体不确定上一次 aidc app deploy 成没成功,该怎么办?

Q3智能体第一次操作一家公司的数据之前,应该先做什么?

延伸阅读