开发文档总览
这一章面向 AIDC 内部开发者，不面向客户售前阅读。它要像 AWS 文档一样，把 Control Plane 的 API、资源模型、调用流程、错误码、权限边界、审计要求和未来 AIDC CLI 的命令形态写清楚。第一条主线从创建 Company 开始：先有公司，再有部门、Agent、服务器、数据源、权限、动作与审计。
// 本章定位
客户文档解释「AIDC 是什么、为什么要这样部署」；开发文档解释「系统如何被调用、每个资源如何创建、每一步失败时如何处理」。后续所有内部 API 需求都先落在这一章，再决定是否开放给外部开发者或封装进 AIDC CLI。
与客户文档的边界
| 维度 | 客户文档 | 开发文档 |
|---|---|---|
| 读者 | 客户决策者、业务接口人、实施负责人 | AIDC 内部工程师、FDE、平台运维、未来集成伙伴 |
| 目的 | 解释方法论、服务旅程、治理与验收 | 定义 API 合约、资源生命周期、调用顺序、错误与审计要求 |
| 写法 | 业务语言，少术语，强调理解和信任 | 工程语言，细到字段、状态机、权限、示例请求与响应 |
| 版本 | 随产品叙事演进 | 随 API 版本演进，必须能和代码、测试、CLI 对齐 |
第一阶段目录规划
先建立一个能持续扩展的骨架。每一页后续都可以按「概念 → 前置条件 → 请求 → 响应 → 状态变化 → 错误 → 审计 → CLI」的模板逐步补全。
| 顺序 | 页面 | 要回答的问题 | 状态 |
|---|---|---|---|
| 1 | 开发文档总览 | 开发文档和客户文档的边界、API 文档组织方式、首批主题 | 已建立 |
| 2 | API 基础 | Base URL、版本、认证、Header、幂等、分页、过滤、错误格式 | 待写 |
| 3 | 公司管理 API | 如何创建 Company、开通 Runtime、创建 Department、管理状态、错误、幂等与审计 | 已建立 |
| 4 | 部门与组织结构 | 如何创建 Department、Role、Workspace，如何和 C-suite 文件系统对应 | 已纳入公司管理 API 草案 |
| 5 | Agent 注册与部署 | 如何注册 Agent、绑定职责、配置模型策略、分配工具与权限 | 待写 |
| 6 | Runtime / Server 管理 | 如何查看服务器健康、启动、停止、重启、拉取运行状态 | 已纳入公司管理 API 草案 |
| 7 | Data Source 与文件接入 | 如何登记数据源、触发同步、查看 ingestion 状态与失败原因 | 待写 |
| 8 | Runtime Operations API | 如何操作文件、环境变量、模型切换、用量计量与 Drive 搜索 | 已建立 |
| 9 | Action 与 Action Log | 如何提交受控动作，如何查询审计记录，哪些动作必须人工审批 | 部分已覆盖 |
| 10 | AIDC CLI | API 如何映射为命令，例如 aidc company create、aidc env set、aidc usage report | 草案已补 |
核心资源模型
开发文档的主线不是接口列表，而是资源生命周期。每个 API 都要挂到某个资源上，避免变成零散 endpoints。
| 资源 | 一句话定义 | 典型路径 |
|---|---|---|
| Company | AIDC Control Plane 的租户级根对象，一家公司对应一个隔离的业务单元 | /api/v1/control-plane/companies |
| Department | 公司内部的职能边界，通常对应文件系统目录、权限域和 Agent Cell | /api/v1/control-plane/companies/{company}/departments |
| Agent | 有职责、记忆、模型策略、权限和审计边界的数字员工 | /api/v1/control-plane/companies/{company}/agents |
| Server | 承载客户 runtime 或内部服务的运行节点，可被健康检查和运维动作管理 | /api/v1/control-plane/customers/{cell}/servers |
| DataSource | 进入 AIDC 系统的数据入口，例如云盘、文件夹、OA、ERP、MES 或手动上传 | /api/v1/control-plane/companies/{company}/data-sources |
| Action | 改变系统或业务状态的受控提交，必须具备权限、输入、结果和审计记录 | /api/v1/control-plane/action-log |
从创建 Company 开始的主流程
- 创建 Company：生成 company id / key，写入基础 profile，确定隔离边界。
- 初始化组织结构：创建默认部门、C-suite 映射、基础角色与 owner。
- 登记数据源：声明数据从哪里来、同步策略是什么、敏感级别如何判断。
- 创建 Agent：绑定职责、目录、模型策略、工具白名单和记忆策略。
- 绑定 Runtime：把 Company 连接到服务器、队列、文件网关、环境变量管理、模型目录、用量计量和审计日志。
- 运行 Smoke Test：查询公司状态、Agent 状态、服务器健康、数据源同步状态。
- 输出验收状态：写入 Action Log，形成 FDE 可读的交付检查点。
每个 API 页面必须包含的细节
- 用途：这个接口改变什么资源，什么时候应该调用，什么时候不应该调用。
- 权限：调用者需要什么角色、scope、公司边界和审批条件。
- 请求：HTTP method、path、headers、query、body、字段类型、必填/可选、默认值。
- 响应：成功响应、异步任务响应、部分成功响应、空结果响应。
- 错误：错误码、可重试性、用户应采取的下一步。
- 幂等：是否支持 Idempotency-Key，重复调用如何处理。
- 审计：写入哪类 Action Log，记录哪些字段，是否需要人工审批。
- CLI 映射：未来 AIDC CLI 的命令、参数、输出格式和 exit code。
- 示例：curl、TypeScript SDK 风格、CLI 三种示例至少一种，关键接口三种都要有。
初始命令形态草案
CLI 暂时先按 API 的资源模型设计，不急着实现。后续每个 API 页面都会保留 CLI 小节。
| 目标 | CLI 草案 | 对应 API |
|---|---|---|
| 创建公司 | aidc company create --name "<company-display-name>" --key <company-key> | POST /companies |
| 查看公司 | aidc company get <company-key> | GET /companies/{company} |
| 创建部门 | aidc department create --company <company-key> --name <department-name> | POST /companies/{company}/departments |
| 注册 Agent | aidc agent register --company <company-key> --role <agent-role> | POST /companies/{company}/agents |
| 检查服务器 | aidc server health --cell <cell-id> --server primary | GET /customers/{cell}/servers/{serverId}/health |
| 列文件 | aidc fs ls --cell <cell-id> --path <relative-path> | GET /companies/{cell}/fs |
| 管理环境变量 | aidc env set --cell <cell-id> --file <env-path> --key API_TOKEN | POST /companies/{cell}/env |
| 登记模型切换 | aidc model switch --cell <cell-id> --profile <profile> --model gpt-5.5 | POST /companies/{cell}/model-switch |
暂定写作模板
- 一句话说明这个 API 做什么；
- 资源模型：它属于哪个资源、状态如何变化；
- 前置条件：认证、权限、依赖资源；
- HTTP Reference：method、path、headers、body、response；
- Examples：curl、CLI、TypeScript；
- Errors：错误码、是否可重试、恢复方式；
- Audit：写入什么日志、谁能查看、保留多久；
- Operational Notes：FDE / SRE 需要知道的限制。
// 下一步
这一页先搭好开发文档入口和写作框架。后续继续按这个结构补具体页面：Company Management、Company Initialization 和 Runtime Operations 已建立；下一步补 API 基础、Agent 注册、Data Source、Action Log 和 AIDC CLI。