开发规范

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）。
• 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），变更记在 更新记录；浏览器 SDK 的路径带大版本（/developer/sdk/v1/），破坏性变更才升 v2，旧版继续可用。
• API 在 /api/v1/** 内不做破坏性变更。

7. 安全边界

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

本页由 developer/docs/standards.md 生成 · Markdown 原文 · llms.txt