# 开发规范

AIDC 内部与客户开发者共用的一套规范。AIDC 成员在 aidc-cloud 仓库里开发时，完整版在 Skill `aidc-development`（`.claude/skills/aidc-development/`）与 `docs/api-standards.md`；这里是面向所有开发者的摘要。

## 1. 先 API + CLI，先智能体后 UI

每个能力先有 API（契约化、可发现），再有 CLI（API 的薄封装），最后才是 UI——UI 只调同一套 API。设备能力（摄像头、麦克风）在浏览器 SDK 里实现，但凡涉及服务端的一步（票据、模型、数据）仍然走 API。

## 2. 给智能体用的形态

- API 永远返回信封：`{ok:true, data, meta}` 或 `{ok:false, error:{code, message, details}, meta}`；错误码稳定、可枚举（见 [OpenAPI](https://www.ai-dc.ai/developer/openapi.json)）。
- CLI 每条命令都有 `--json`，stdout 不是终端时默认 JSON；进度提示走 stderr。
- 永不交互；缺参数直接报错并说明怎么补。
- 退出码：`0` 成功、`1` 一般错误、`2` 参数、`3` 未登录、`4` 无权限、`5` 不存在、`6` 冲突、`7` 限流 / 额度、`8` 上游故障。

## 3. 幂等与 dry-run

- 发布是幂等的：版本内容寻址（同样的文件 = 同一个版本），通道晋升是「把指针设为版本 N」。重试不会产生重复数据。
- 有副作用的操作都支持预演：API 带 `x-aidc-dry-run: true`，CLI 加 `--dry-run`，返回 202 与将要发生的计划。

## 4. 复用，不重复造轮子

登录、会话、Key、计费、限流、模型上游、实时转写、Markdown 渲染……平台都已经有一份。应用里需要这些能力时调 SDK，不要自己再写一套；平台内部开发时查 `aidc-development` 的复用登记表。

## 5. 依赖：站在成熟基础设施上

- 公认的基础设施放心用，不要自研替代品：ffmpeg、PostgreSQL、Redis、浏览器原生的 `getUserMedia` / `MediaRecorder` / WebRTC / Web Audio / canvas、OpenAI 兼容协议。
- 不成熟的第三方库（单人维护、长期无发布、依赖树深）默认不引入；确需引入时钉版本、包一层适配。
- 浏览器端只从 `cdn.jsdelivr.net` / `cdnjs.cloudflare.com` 加载第三方脚本，写进清单的 `cdn`。

## 6. 文档与版本

- SDK 与 CLI 同步发版（SemVer），变更记在 [更新记录](changelog.md)；浏览器 SDK 的路径带大版本（`/developer/sdk/v1/`），破坏性变更才升 `v2`，旧版继续可用。
- API 在 `/api/v1/**` 内不做破坏性变更。

## 7. 安全边界

- 开发者 Key（`aidc-dk-…`）只放在服务端 / CLI / 环境变量里，绝不写进前端代码。浏览器里的应用用平台注入的应用票据（`aidc-at-…`，短命、只能调清单里声明的模型与数据集）。
- 客户应用跑在 CSP 沙箱里（不透明源，拿不到访客的登录态），只能凭票据调 API。
- 数据只出聚合：连接 SDK 的数据集报告不返回明细行。