查看 Markdown

开发规范

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

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。
  • 永不交互；缺参数直接报错并说明怎么补。（人在终端里直接敲 aidc 进入的交互界面是给人用的，不是终端时照样不停下来等人。）
  • 退出码：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。
  • 数据只出聚合：数据集的固定报告不返回明细行。

8. 界面

  • 所有应用用界面 SDK：页面引 /developer/sdk/v1/ui.css，按钮、表单、卡片、表格、对话框用它的 aidc-* 类；应用自己的 CSS 只写版面与业务特有的东西。
  • 主按钮实心黑，信号橙只用于加载、选中与需要注意的状态；等待态用 // 加载动效，不用圆环 spinner。
  • 确认、输入、提示用 ui.confirm / ui.prompt / ui.toast，不用 window.confirm / prompt / alert。
  • React 项目用 shadcn/ui 与 @aidc 注册表（AIDC UI），令牌与 HTML 应用同一套。

9. 一个 SDK 由什么组成

AIDC 的每个 SDK 都是同一副骨架（AIDC 内部的完整清单与自动检查在 aidc-development 的 SDK 标准里）：

部分 在哪里
API（有服务端的一步时） /api/v1/**，契约进 OpenAPI；纯前端能力的契约是机器可读的登记表（如界面 SDK 的 ui.json）
CLI aidc <命令组> <动作>，--json、--dry-run、稳定退出码
浏览器模块 aidc.js 里的一个具名导出（import { ui } from "/developer/sdk/v1/aidc.js"）
文档 一页 Markdown（每页都有 .md 原文给智能体），进总览表、llms.txt 与 Agent Skill
清单登记 aidc.app.json 的 sdk；部署时静态分析，用了没登记的拒收
版本 与其余 SDK 同步发版，记在更新记录

10. 每个应用一张应用卡片

平台按清单、部署时的静态分析、通道与使用日志给每个应用自动生成应用卡片（负责部门、版本、用了哪些 SDK、是否连数据库、读写哪些数据、对外能力与依赖、访问范围、近 7 天使用），开发者不手写，但要让它是对的：

  • 清单写 owner（部门 / 岗位或智能体 / 负责人）与一句话 summary；
  • sdk、semantic、streams、models 如实登记（用了没登记的部署拒收，登记了没用到的卡片上会标出来）；
  • 想被别的应用或工作流用，就把可以对外的查询 / Action 写进 exports；
  • version 每次改动都升（SemVer）。

查看：应用顶栏「卡片」、appCard()、aidc app card、GET /api/v1/developer/apps/{命名空间}/{slug}/card。

11. 成本与资源：不在不知情的状态下增加账单

  • 先算账，再开：按量计费的东西（函数时长、流量、模型 token、实时转写、外部 API）上线前估一下「次数 × 单价」。
  • 开完就关：临时开的服务、后台进程、测试用的 Key、测试数据、定时任务，用完就关掉、吊销、删除。
  • 每个应用都有上限，清单 limits 不写就用缺省值：计算分钟 2000 / 月（实时连接挂着、工作流运行、模型调用的时长）、每天 100 万 token、每 IP 每分钟 30 次请求、每天 100 场实时转写、每天 20 封通知。用完返回 429 quota_exhausted，下月 / 次日恢复。调高就是允许它花更多钱，部署时会告警。用量：aidc app usage <slug>。见发布 SDK。
  • 长连接只在有人看的时候开：SDK 的实时连接在页面隐藏 1 分钟后自动断开、切回来续上（不丢不重）；不要用 setInterval 轮询服务端（部署时告警）。

12. 触发优先于定时

  • 数据一变才需要做的事，用数据流 + 工作流的 trigger.change（when 条件、cooldown 冷却）：没变化时零成本、不写 cron。
  • 定时（trigger.schedule）只给「时间本身就是条件」的事：日报、月底对账、数据该来却没来的看门狗。每天一次是常态。
  • 频率分级：比每 5 分钟还密拒收；5 分钟到 1 小时一次是高频，部署时一定告警（带上每月次数与预计的计算分钟）；1 小时到 1 天提示次数；每天及以上正常。
  • 告警、提醒用工作流的 notify 步骤发邮件：收件人必须是本公司账号，同样的通知在冷却时间内只发一次，每天有上限，每一封发没发出去都有记录。

13. 产品自提升

我们根据每次开发遇到的问题持续改进规范：遇到新问题、或者发现规范少了一条判断，就在同一次改动里把它变成一条规则或一个自动检查（测试、部署校验），并记进问题账本——同样的问题不出第二次。提升本身也守第 11 条：不为提升去开资源，要开就先算账、用完就关。

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