# 应用（Apps）

新应用默认使用标准 `plugin.json`；旧 `aidc.app.json` 继续支持。Apps 与 OpenAI Plugin 的包、UI、默认 AIDC 登录和可选 OAuth 规范见 [Plugin 兼容](plugins.md)。

AIDC 的应用，就是智能体时代的插件：**一组 Skills 加一组 APIs，界面可选**。智能体照 Skills 调 APIs 把事做完，程序直接调 APIs；人需要看、比较、确认的时候，才打开界面。应用在 Developer 里做和测，发布到 Nexus 的应用目录；用的人不用安装——在应用页点「复制给智能体」，把那一句话贴给 Adis、Claude Code 或 Codex 就能用。

这份标准照 OpenAI 的 Plugin 定义来（ChatGPT 与 Codex 共用的插件格式，[官方文档](https://developers.openai.com/plugins)，2026-09-29 读取）：Plugin 是人们发现、安装、分享和发布的包，可以带 Skills（给模型的说明和资源）、MCP 服务器（工具和外部系统），两者都要时就都带，界面可选。AIDC 应用一一对应，只多了一条：数据在公司的语义层，应用本身不存东西。

![一个应用：Skills、APIs 与可选的界面装进同一个包](../../assets/img/developer/apps/dev-hero.webp)

## 一个应用由什么组成

```text
应用（aidc.app.json）
├── Skills        skills/<名字>/SKILL.md：教智能体完成一件可重复的事
├── APIs          应用对外提供的能力：HTTP、CLI、MCP 都能调
└── 界面（可选）   index.html：给人看、比较、确认、编辑
```

| 部分 | 是什么 | 对应 Plugin 的 |
| --- | --- | --- |
| **Skills** | 一份 `SKILL.md`：什么时候用、按什么步骤调哪些 API、输出什么、哪些事不能推断。可以附参考资料 | Skills |
| **APIs** | 应用对外提供的查询、读取、汇总、动作，以及工作流的运行。以「应用 × 调用人的角色」执行 | MCP 服务器的工具 |
| **界面** | 应用的页面。只调同一套 API，界面能做的事智能体一定也能做 | 可选的 UI |
| **清单** | `aidc.app.json`：名字、版本、介绍、示例说法、负责方、用到的 SDK、权限与资源上限 | `plugin.json` |

两种用法，同一套 API：

- **智能体用**：人把「帮我用 AIDC 应用「报价工作流」：…/about.md」交给智能体，智能体读这份说明（APIs、Skills 全文、示例说法、规矩），照 Skills 调 APIs。
- **程序用**：`POST /api/v1/developer/apps/{命名空间}/{slug}/apis/{名字}/execute`、`aidc app call`，或者把应用接成 MCP 服务器。

## 选一个形态

| 形态 | 什么时候选 | 例子 |
| --- | --- | --- |
| 只有 Skills | 说明加上现成的 AIDC 能力（模型、视觉、语音、语义层）就能把事做完 | 瑕疵检测：Skill 教智能体用 `aidc vision inspect` |
| 只有 APIs | API 自己说得清，不需要额外的流程说明 | 设计中心 · 初始材料清单：导出 `bom_of` |
| Skills + APIs | Skill 带智能体走一套流程，用的是本应用的 API | 报价工作流：先预演、给人看、确认后正式运行 |
| APIs + 界面 | 人要看、比较、编辑或确认结构化的信息 | 企业数据浏览器、审批看板 |

先做最小的形态。以后加 API 或界面，不改应用的用途。

## 包的结构

```text
quote-workflow/
├── aidc.app.json              清单
├── skills/
│   ├── quote-rfq/
│   │   ├── SKILL.md           一条 Skill（name 与目录同名）
│   │   └── references/        可选：口径、例子、模板
│   └── explain-quote-risk/
│       └── SKILL.md
├── index.html                 界面（可选；没有界面时清单写 "entry": null）
└── app.js / style.css
```

- Skills 固定放在包根目录的 `skills/` 下，一条一个目录，清单里不用登记（照 Plugin 的固定目录）。
- 界面、代码、图片照旧；包里的文件只从版本目录 `_v/<digest>/` 出。
- 平台在应用地址下另外生成三样东西，包里不用写：`<应用地址>/about`（应用页）、`<应用地址>/about.md`（给智能体的说明）、`<应用地址>/skills/<名字>/SKILL.md`（线上版本的 Skill 原文）。

## 清单：身份、示例说法、介绍

```json
{
  "manifestVersion": 1,
  "slug": "quote-workflow",
  "version": "1.1.0",
  "title": "报价工作流（演示）",
  "summary": "跨部门报价：从一张询价算到一张待审批的报价草稿。",
  "description": "营业部收到客户询价后，把设计 BOM、采购行情、制造工艺、财务核价串起来……",
  "examples": ["给 RFQ-2609-006 核价，出一张报价草稿", "列出待报价的询价，按目标价差距排先后"],
  "owner": { "department": "营业部", "team": "营业小兴-报价" },
  "category": "data",
  "entry": "index.html"
}
```

| 字段 | 做什么 | Plugin 里叫 |
| --- | --- | --- |
| `slug` | 应用标识，出现在地址里（小写、连字符） | `name` |
| `version` | 语义化版本号，改了任何东西就要升 | `version` |
| `title` / `summary` | 目录与应用页上的名字、一句话 | `displayName` / `shortDescription` |
| `description` | 应用页「介绍」一节：做什么、给谁用、输入输出（≤ 2000 字） | `longDescription` |
| `examples` | 示例说法：人对智能体说的一句话，应用页「调用方法」里点一下就复制（≤ 6 条） | `defaultPrompt` |
| `owner` | 负责方：部门、岗位 / 智能体、联系人 | `developerName` |
| `category` | 目录里的分类 | `category` |
| `entry` | 界面入口；`null` = 没有界面 | 可选的 UI |

其余字段（`sdk`、`semantic`、`exports`、`workflow`、`auth`、`limits`……）见[发布 SDK](publish.md)。

## Skills

一条 Skill 是一个目录，里面一份 `SKILL.md`：

```markdown
---
name: quote-rfq
description: "给一张客户询价核价并生成待审批的报价草稿。用户给出询价单号（RFQ-…）、说要报价或核价时使用。先预演，人确认后再正式运行。"
---

# 核价并出报价草稿

## 输入
- 询价单号（RFQ-…）。没有就先问。

## 步骤
1. 预演：`aidc app call cell-aidc/quote-workflow run --param rfq_no=<单号> --preview --json`
2. 用 get_run 等结果，把单价、风险与目标价差距给人看。
3. 人确认后去掉 --preview 正式运行。

## 不要
- 替人批准报价。
```

- `name`：小写字母开头，字母 / 数字 / 连字符，和目录同名。
- `description`：智能体靠它决定什么时候用这条 Skill。写用户的目标和触发的场合，≤ 1024 字符；里面有「: 」就整句加引号。
- 正文写清楚：要什么输入、按什么顺序调哪些 API、输出什么、哪些事不能推断、什么时候该问人或停下。
- 一条 Skill 对一个目标。触发条件、输入或完成标准不同，就拆成两条。一个应用最多 12 条。
- 详细材料放 `references/`，正文里写什么时候去读它。

部署时平台检查：目录名、`name` 与目录一致、`description` 的长度和写法、正文不能空、单个 `SKILL.md` ≤ 32 KB。不合规的整个版本拒收，问题一次列全。

**没写 Skill 的应用**，平台按清单生成一条「使用这个应用」的 Skill（应用页标「平台自动生成」）：列出它的 APIs 和用得上的 AIDC 命令。能用，但比不上你自己写的——写一条，把你们的做法教给智能体。

**测一条 Skill**，照 Plugin 的做法准备五类说法：直接要求、换个说法的同一个目标、缺信息（应该追问）、不该触发的、容易编造的边界情况。Skill 在错的时候被用上，改 `description`；用对了但结果不稳，改正文。

## APIs

一个应用的 APIs 有三个来源：

| 来源 | 从哪来 | 例子 |
| --- | --- | --- |
| 显式导出 | 清单 `exports`：名字、参数、说明（推荐，名字和参数是给人看的契约） | `quote-sales/rfq` |
| 自动提取 | 清单 `semantic` 里登记的对象类型（查询）与动作 | `quote-sales/demo.approve_quote` |
| 工作流 | 带 `workflow` 的应用多三个：`run`、`get_run`、`list_runs` | `quote-workflow/run` |

所有 API 走同一个调用口：

```bash
curl https://www.ai-dc.ai/api/v1/developer/apps/cell-aidc/quote-sales/apis/rfq/execute \
  -H "Authorization: Bearer $AIDC_API_KEY" -H "Content-Type: application/json" \
  -d '{"input":{"rfq_no":"RFQ-2609-006"}}'

aidc app call cell-aidc/quote-sales rfq --param rfq_no=RFQ-2609-006 --json
```

- **身份**：以「应用 × 调用人的角色」执行——读只能读应用登记过的类型，动作过它自己的角色规则。调用人拿不到应用本来拿不到的东西；留痕记的是调用人。
- **凭证**：开发者 Key 调本公司任何应用；应用票据只能调它自己。
- **写入先预演**：动作和工作流正式运行会写语义层。请求体加 `"preview": true`（CLI `--preview`），读、算、AI 分析照跑，写入只返回计划；把计划给人看，确认后再正式调用。`x-aidc-dry-run: true` 只校验输入。
- **列出全部 API**：`GET …/apps/{命名空间}/{slug}/apis`（`aidc app apis`）：名字、说明、输入的 JSON Schema、返回、调用口与 CLI 写法。
- **MCP**：公司应用另有一个 MCP 服务器 `…/apps/{命名空间}/{slug}/mcp`（Streamable HTTP，凭证是开发者 Key）：工具 = APIs（名字里的「.」换成「__」），prompts = Skills。

```bash
claude mcp add --transport http quote-workflow \
  https://www.ai-dc.ai/api/v1/developer/apps/cell-aidc/quote-workflow/mcp \
  --header "Authorization: Bearer $AIDC_API_KEY"
```

没有自己 API 的应用（界面里直接调 AIDC SDK 的，比如瑕疵检测），应用页列出它「用到的 AIDC 能力」——现成的 CLI 命令，Skill 教智能体用它们做同样的事。

## 复制给智能体，不用安装

![复制一句话，交给你的智能体](../../assets/img/developer/apps/apps-copy.webp)

每个应用页右上角都有「复制给智能体」。复制的是一句话：

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

贴给 Adis、Claude Code、Codex 或任何能跑终端命令的智能体。它读 `about.md`：这是什么、怎么登录、有哪些 API（CLI 与 HTTP 写法）、每条 Skill 的全文、示例说法、规矩——读完照做。「调用方法」里的示例说法点一下，复制的是「那句话 + 这个应用的说明地址」。

- AIDC 官方应用的说明谁都能读。
- 公司应用的说明要凭证：智能体先请人在终端运行 `aidc login`，然后 `aidc app about <命名空间>/<slug>` 读；或者带 `Authorization: Bearer $AIDC_API_KEY` 请求 `about.md`。智能体不索要、不转述密码。

## 应用页

每个应用都有一张平台生成的应用页（`<应用地址>/about`），照 Codex Plugins 的详情页排：

| 一节 | 放什么 | 数据从哪来 |
| --- | --- | --- |
| 调用方法 | 示例说法（点一下就复制）；对智能体说 / CLI / HTTP / MCP | 清单 `examples`；APIs |
| 介绍 | 做什么、执行什么任务（工作流按取数 → 计算 → AI 分析 → 写入分组）、输入与输出、触发 | 清单 `description`、`workflow` |
| Skills & APIs | Skills（可展开看 `SKILL.md`、复制）、APIs（参数、返回、CLI 与 HTTP）、依赖的能力、用到的 AIDC 能力、连接的数据 | 包里的 `skills/`、能力目录 |
| Information | 负责方、类别、形态、版本、访问范围、SDK、模型、资源上限、地址、文件 | [应用卡片](app-card.md) |

应用页只有元数据，不含业务数据。目录在 `/nexus/apps`（AIDC 官方）与 `/nexus/<公司>/apps`（登录后：本公司的应用 + AIDC 官方；打开 `/nexus` 登录后直接到这里）；测试版在 Developer 下：`/developer/<公司>/apps` 是本公司应用的 Developer 版本（只给 developer），应用页 `/developer/…/apps/<slug>/about`。发布到 Nexus 需要 Developer 账号。

## 做、测、发布

```bash
aidc app init quote-helper --template skills     # 只有 Skills 的应用；别的模板也都带一条 Skill
aidc app check quote-helper                      # 本地校验：清单、包、Skills
aidc app deploy quote-helper                     # test 通道：Developer 里的应用页与 about.md
aidc app publish quote-helper                    # 测过的版本进 Nexus 目录
```

完整走一遍：[快速开始](quickstart.md)。

## 上架前的检查清单

- [ ] `summary` 一句话说清给谁用、做什么；`description` 写清输入、输出和边界。
- [ ] `examples` 两三句，写成用户会说的话，不写成命令。
- [ ] 至少一条 Skill 或一个 API；每条 Skill 的 `description` 写清什么时候用。
- [ ] 会写入的 API 能预演；Skill 里写明「先预演、给人看、确认后再正式调用」。
- [ ] 结论只用 API 返回的内容：Skill 里写明哪些事不能推断。
- [ ] 写了 `owner`；版本号已升；`aidc app check` 通过。
- [ ] 用五类说法测过 Skill：直接、换说法、缺信息、不该触发、边界。

## 课程

AIDC Academy 的[《成为 AIDC Developer》](https://www.ai-dc.ai/academy/become-a-developer)把这一页讲成课：[第 4 课「应用：给智能体用，也给人用」](https://www.ai-dc.ai/academy/become-a-developer/apps)讲定义、四种形态和复制给智能体，[第 7 课「动手：做第一个应用」](https://www.ai-dc.ai/academy/become-a-developer/first-app)从一条 Skill 做到发布。