核心概念

这一页讲 AIDC Developer 的基本概念。每个概念先给定义，再给例子。细节在各自的页面里。

组织

组织是一家公司在 AIDC 里的边界，命名空间写成 cell-…。数据按组织隔离，用量记在组织名下。

Demo Company 的命名空间是 cell-demo。

• 命令行用 -n cell-demo 指定组织。不指定时，用你登录的组织。
• 账号属于几个组织时，aidc login 在终端里让你选一个。
• public 是 AIDC 官方公开应用所在的命名空间。只有 AIDC 平台账号能发布到 public。

详见 命令行 aidc。

账号与角色

每个人用一个 AIDC 账号登录。账号要拿到组织发的授权码（License），才能以组织成员的身份工作。

角色	能做什么
member	调用组织已发布的应用，在本机开发应用，管理自己的 Key
developer	member 能做的全部，再加部署、发布、数据和管理命令

例：member 运行 aidc app deploy，退出码是 4（无权限）。

应用里的访客还有 editor、viewer 等角色。见 访问与安全。

凭证

凭证证明调用方是谁。前缀不同，用途也不同。

凭证	前缀	代表谁	在哪里用
开发者 Key	aidc-dk-…	你在一个组织里的身份。用量记在组织名下	CLI、服务端代码、CI
发布 Key	aidc-pk-…	一条数据流的发布端，只能发布到这一条数据流	aidc semantic streams pipe
Agent Key	aidc-sk-…	一个智能体（数字员工）	智能体 API、aidc connect send
应用票据	aidc-at-…	打开应用的人，只能调用这个应用声明过的资源	应用页面里，SDK 自动带上

• 开发者 Key 只放在服务端、CLI 或环境变量里。不写进网页代码，也不提交进仓库。
• aidc login 签一把新的开发者 Key，存在 ~/.aidc/config.json。换机器，或不再使用时，运行 aidc logout --revoke 吊销它。
• 公开应用票据有效 1 小时。组织应用票据有效 8 小时。SDK 在请求时自动续期。

例：设置 AIDC_API_KEY=aidc-dk-… 后，CI 里的 aidc 不用登录，直接使用这把 Key。

凭证的用法见 智能体接入。应用票据和访问设置见 访问与安全。

应用

应用（App）是一组 Skills 加一组 APIs，界面可选。

• Skills 是写给智能体的一份做法。它写明什么时候用、按什么步骤做、输出什么，以及哪些事不能做。
• APIs 是应用对外提供的查询、读取、动作和工作流。
• 界面是给人看、比较、确认的页面。没有界面的应用只有 Skills 和 APIs。
• 应用不存业务数据。业务数据在组织的 Semantic 里。
• 清单（plugin.json）写应用的名字、版本、介绍、示例说法，以及用到的 SDK 和资源上限。aidc.app.json 格式也还能用。

例：快速开始做的「现场巡检」只有一条 Skill。这条 Skill 教智能体运行 aidc vision inspect，检查现场照片。

详见 应用（App）。

通道与版本号

应用有两个通道：test 和 production。版本号标明内容的版本。

• test 通道是 Developer 预览。aidc app deploy 把版本放进 test 通道。
• production 通道是 Nexus 正式版。aidc app publish 把测过的版本放进 production 通道。production 只接受进过 test 的版本。
• 版本号是清单里的 version，例如 1.2.0。内容变了就要升版本号。同一个版本号只对应一份内容。
• 构建序号是每次上传的编号，例如 #3。
• aidc app rollback 把 production 切回一个已测过的版本。

例：aidc app deploy 把 v0.1.0 放进 test。aidc app publish 把它放进 production。

详见 发布 SDK。

SDK、CLI 与 API

同一个能力有三种形态：API、CLI 和 SDK。AIDC 先做 API，再做 CLI，最后做界面。界面只调用同一套 API。

• API 是服务端的契约，地址在 /api/v1/ 下。
• CLI（aidc 命令）调用 API。每条命令都有 --json。
• SDK 在浏览器里运行。需要服务端的步骤，SDK 也调用 API。

例：检测图片里的物体。三种形态做的是同一件事。

aidc vision detect warehouse.jpg --labels 人,叉车

const result = await vision.detect(photo, { labels: ["人", "叉车"] });

curl https://www.ai-dc.ai/api/v1/models/vision/detect \
  -H "Authorization: Bearer $AIDC_API_KEY" -H "Content-Type: application/json" \
  -d '{"image":"https://example.com/warehouse.jpg","labels":["人","叉车"]}'

各 SDK 见总览。API 的端点见 API 参考。

Semantic：对象与 Action

Semantic 是数据平台。企业数据在 Semantic 里，以对象的形式存在。

• 数据源是组织原有的系统，例如 ERP 和 MES。数据源只读。
• 数据流把变化的数据推入 Semantic。数据变了才推，不轮询。
• Object Type（Object Type）定义一类业务对象，例如订单行。对象是它的一条记录。
• Action 是改数据的唯一入口。Action 检查参数和权限，并留下记录。
• 企业的全部 Object Type、链接和 Action，合起来叫本体（Ontology）。

例：读对象用 aidc semantic objects。改数据用 Action。先加 --validate-only 校验，校验不写入数据。

aidc semantic objects production.order_line --where '{"status":"异常"}' --json
aidc semantic apply production.flag_issue --param __object="100000012345|L01-05" --param issue=缺料 --param severity=异常 --validate-only --json

谁能看数据，由访问设置决定：Private、Group、Public、Open to Internet。见 访问与安全。数据怎么进来，见 数据管道。读写对象的写法见 Semantic 概览。

用量与计费

开发者 Key 的模型用量记在 Key 所属组织名下。应用票据的模型用量记在应用所属组织名下。模型调用按量计费。应用的计算时长有月上限。

• 平台按调用时刻的价目计算模型调用费用。平台将用量写入台账。无法计价时，金额记为 null。金额是美元标价，不是发票。
• 计算分钟是应用在服务端占用的时长，例如实时连接、工作流运行和模型调用。每个应用每月缺省 2000 分钟。
• 超过上限，应用的请求返回 429 quota_exhausted。下个月 1 日（UTC）恢复。

例：aidc app usage site-check 显示本月已用的计算分钟。

详见 用量与账单。资源上限见 发布 SDK。

按需运行

优先用数据变化触发任务。实时连接仍按连接时长累计计算分钟。

• 数据一变才需要做的事，用触发（trigger.change）。
• 定时（trigger.schedule）只用在时间本身是条件的事，例如每天的日报。
• 定时间隔短于 5 分钟时，平台拒绝部署。5 分钟到 1 小时一次，部署时会告警。
• 不用 setInterval 轮询服务端。部署时会告警。
• 页面隐藏超过 1 分钟，实时连接自动断开。切回页面时自动续上。

详见 自动化。

术语速查

词	一句话
组织	一家公司在 AIDC 里的边界。命名空间写成 cell-…。
member、developer	组织里的两种角色。member 能用应用，developer 还能部署和发布。
开发者 Key（aidc-dk-…）	你在一个组织里的身份凭证。
发布 Key（aidc-pk-…）	只能往一条数据流发布数据的凭证。
Agent Key（aidc-sk-…）	一个智能体（数字员工）的凭证。
应用票据（aidc-at-…）	打开应用的人的凭证，只能调这个应用声明过的资源。
应用（App）	一组 Skills 加一组 APIs，界面可选。
Skill	写给智能体的一份做法。
清单	应用的名字、版本、介绍、示例说法，以及用到的 SDK 和资源上限。
通道	test（Developer 预览）和 production（Nexus）。
版本号、构建序号	版本号标明内容。构建序号是第几次上传。
数据源	组织原有的系统。永远只读。
数据流	发布端把变化的数据推入 Semantic 的通道。
Object Type（Object Type）	一类业务对象的定义，例如订单行。
Action	改数据的唯一入口。检查参数和权限，并留下记录。
计算分钟	应用在服务端占用的时长，按月计量。
自动化（Automate）	数据变化或到点时，执行 Action、做模型分析或发邮件。

下一步

• 快速开始：十分钟做出第一个应用并发布。
• 应用（App）：应用的形态、清单、Skills 与 APIs 的标准。
• 访问与安全：谁能看、怎么分享，以及应用里的访客角色。