# Apps 与 OpenAI Compatible Plugin

AIDC 的 **App** 与 OpenAI 的 **Plugin** 使用同一份 Agent Plugins 1.0 包。
包的身份、版本、Skills 与 MCP 声明可以复用；AIDC 运行权限只放在自己的扩展里。

## 默认登录 AIDC，外部连接可选

**一律登录（2026-09-29）**：用 AIDC Developer SDK 或 AIDC 应用做任何事都要先登录 AIDC 账号，member 起步（member 能调用应用、在本机开发；部署与发布要 developer）。这一节讲的是用哪种方式登录。

自己的用户默认使用 AIDC 账号：浏览器打开 [Apps Creator](/developer/creator)，复用统一的
`AidcSignInForm` / `aidc-auth-client`，登录后选择你所在的公司（角色按这家公司）；CLI 使用
`aidc login` 或 `aidc login --browser`。测试与发布走同一套服务、公司权限和发布记录。
**不要求连接 OpenAI，也不要求 OpenAI 账号。**

用户主动选择「连接当前聊天」时，ChatGPT、Codex 或其他外部 MCP 客户端才使用可选的
OAuth 2.1 + PKCE。MCP 工具本身同样要登录：Codex 里插件带上 `aidc login` 的 Key；聊天宿主里没有这把 Key，
就通过「连接当前聊天」登录。授权服务器仍然是 AIDC；客户端只是拿到限定 MCP 地址及权限的令牌。
密码、会话和 API Key 不进入聊天、工具结果、UI state 或插件包。

## 包结构

```text
my-app/
  plugin.json
  mcp.json                         # 可选：实际的 MCP 服务器
  skills/my-workflow/SKILL.md
  skills/my-workflow/references/...
  index.html                       # 可选：AIDC 网页入口
  widget.html                      # 可选：自包含对话 UI
```

```json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-app",
  "version": "0.1.0",
  "description": "处理工单",
  "extensions": {
    "com.openai": {
      "interface": { "displayName": "工单助手", "defaultPrompt": ["查看待处理工单"] }
    },
    "ai.aidc": {
      "app": {
        "manifestVersion": 1,
        "slug": "my-app",
        "version": "0.1.0",
        "title": "工单助手",
        "entry": null,
        "sdk": []
      }
    }
  }
}
```

根级只放标准字段。`extensions.ai.aidc.app` 就是已有 AIDC 清单契约（SDK、数据、模型、
权限、工作流、预算）；根 name/version 必须与 slug/version 一致。双清单不一致拒收。
没有 AIDC 扩展的纯 Skills Plugin 按无界面、无业务权限应用导入。

`plugin.json` 优先；已有 `aidc.app.json` 继续可用。新建应用默认生成标准清单，
`--format aidc` 可生成旧清单。版本与权限变更都参与包的内容指纹。

## 开发与导出

```bash
aidc app init my-app --template blank
aidc app check my-app
aidc login --browser
aidc app deploy my-app                           # test
# 打开预览，验收后发布明确的版本
aidc app publish my-app --version 0.1.0
aidc app export my-app --namespace cell-your-company --out my-app.zip
```

导出保留原插件的所有扩展、元数据与 defaultPrompt。自动添加的 `mcp.json` 使用
`type: streamable-http`，指向所选公司的实际应用 MCP 地址；不写入凭证。
不指定 namespace 时不会猜测 MCP 地址。导出不等于远端已经部署。
UI SDK 接入与 evolve bake 同时支持两种清单，更新根版本时保留现有插件元数据。

## 对话 UI

Creator 的 `show_creator` 工具返回 MCP Apps 卡片。默认「登录 AIDC / 我的应用」打开
AIDC 自己的界面；「连接当前聊天」是可选的外部 OAuth 入口。首次登录在 AIDC 第一方
页面完成，避免第三方 iframe cookie 限制。聊天内不显示密码输入框。

普通应用可以在运行清单声明 `mcpUi: "widget.html"`，通过 `aidc-ui-render` 工具渲染。
HTML 必须自包含；脚本/样式可从 AIDC 的 SDK 域加载。不要把整页 AIDC 会话或应用票据
注入组件；组件调用 MCP tools，服务端按当前连接的身份裁决。

```js
import { ui } from "https://www.ai-dc.ai/developer/sdk/v1/aidc.js";
const bridge = ui.createMcpBridge(result => render(result.structuredContent));
await bridge.initialize();
const result = await bridge.callTool("my_api", { id: "ticket-1" });
// 页面销毁时 bridge.dispose()
```

资源 MIME 为 `text/html;profile=mcp-app`；工具声明 `_meta.ui.resourceUri`，并提供
`openai/outputTemplate` 别名。桥接使用 `ui/initialize`、`ui/notifications/tool-result`、
`tools/call`、`ui/open-link`，不依赖 OpenAI 专用全局变量。

未声明 mcpUi 的已有界面应用显示介绍和打开入口，不声称旧页面自动适配聊天尺寸或授权。

## MCP 与可选 OAuth

- 应用地址：`POST /api/v1/developer/apps/{namespace}/{slug}/mcp`。
- Creator：`POST /api/v1/developer/creator/mcp`。
- tools = 现有 APIs；prompts = Skills；resources = UI 与完整 Skills 辅助资料。
- 支持 `skills/list`、`skills/get`，通过 `capabilities.extensions.io.modelcontextprotocol/skills`
  声明 OpenAI 当前支持的 Skills 扩展；每个资源有实际 UTF-8 / 解码字节的 SHA-256。
- 传输为无状态 Streamable HTTP，JSON 响应；通知返回 202，无服务端 SSE 的 GET 返回 405。
- 函数名按 MCP 限制生成，长名与点/下划线碰撞有稳定哈希后缀。写工具明确标注可改变数据。
- 一律登录：应用的 MCP（官方应用也一样）没有凭证回 401 + `WWW-Authenticate`；Creator 的 `initialize`、`tools/list`
  不用登录，调用工具除 `get_sdk_docs`、`show_creator`（登录入口）外都要登录，`list_apps` / `deploy_app` / `publish_app` 还要 developer。
- OAuth discovery：`/.well-known/oauth-authorization-server`；401 和工具挑战提供
  `resource_metadata` URL；支持 DCR、S256、一次性授权码、resource 绑定、scope、刷新轮换和吊销。
- `apps:read` 只读；`apps:write` 才能部署、发布或调用写 API。每次令牌调用重新检查账号与角色（member 按「在浏览器里打开这个应用」的身份调正式通道，部署、发布要 developer）。
- MCP 只认 Bearer；AIDC 原生 Creator 只认自己的登录会话并检查 CSRF。两个入口不互相借用身份。
- 浏览器 Origin 缺省允许 AIDC、chatgpt.com、chat.openai.com；其他宿主配置
  `AIDC_MCP_ALLOWED_ORIGINS`（逗号分隔的精确 origin）。原生客户端不需要 Origin。

## 明确边界

| 项目 | 支持情况 |
| --- | --- |
| Agent Plugins 1.0 清单、Skills、MCP 包 | CLI 导入、检查、ZIP 导出；其他扩展原样保留 |
| AIDC 云端运行权限 | 仍执行 AIDC SDK/公司/数据边界；插件元数据不授予权限 |
| 客户端 MCP stdio / SSE 声明 | 可保留与校验；AIDC 云端不执行上传的命令或任意服务器代码 |
| MCP UI | 需声明自包含 mcpUi；已有网页使用应用卡片入口 |
| Skills 导入 | AIDC 最多 12 条；OpenAI 当前的导入限额为 5 条，超限须整理后提交 |
| AIDC 身份与文件限制 | slug 2–48 位小写字母数字连字符，包 ≤ 200 文件 / 3 MiB；不支持的包明确拒收 |
| 旧版 Codex 私有清单 | 请迁移为标准根 plugin.json；不把旧顶层字段混入便携标准 |
| OpenAI 目录上架 | 协议兼容不代表已通过审核；须单独连接测试、域名验证和提交 |

依据：[插件包](https://developers.openai.com/plugins/build/plugins)、
[MCP](https://developers.openai.com/plugins/build/mcp-server)、
[MCP Apps UI](https://developers.openai.com/plugins/build/chatgpt-ui)、
[可选客户端认证](https://developers.openai.com/plugins/build/auth)。