# 核心概念

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

## 组织

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

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

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

详见 [命令行 aidc](cli.md)。

## 账号与角色

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

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

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

应用里的访客还有 editor、viewer 等角色。见 [访问与安全](auth.md)。

## 凭证

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

| 凭证 | 前缀 | 代表谁 | 在哪里用 |
| --- | --- | --- | --- |
| 开发者 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。

凭证的用法见 [智能体接入](agents.md)。应用票据和访问设置见 [访问与安全](auth.md)。

## 应用

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

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

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

详见 [应用（App）](apps.md)。

## 通道与版本号

应用有两个通道：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](publish.md)。

## SDK、CLI 与 API

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

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

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

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

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

```bash
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 见[总览](overview.md)。API 的端点见 [API 参考](api.md)。

## Semantic：对象与 Action

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

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

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

```bash
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。见 [访问与安全](auth.md)。数据怎么进来，见 [数据管道](pipeline.md)。读写对象的写法见 [Semantic 概览](semantic.md)。

## 用量与计费

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

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

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

详见 [用量与账单](billing.md)。资源上限见 [发布 SDK](publish.md)。

## 按需运行

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

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

详见 [自动化](workflow.md)。

## 术语速查

| 词 | 一句话 |
| --- | --- |
| 组织 | 一家公司在 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、做模型分析或发邮件。 |

## 下一步

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