工具链层：API、SDK、CLI、MCP

同一套能力，四个入口

引擎在里面跑，人和程序要从外面进来。工具链层不新增能力，只是把语言层和引擎层的能力开放出来：读对象、跑对象集、执行 Action、改定义。入口按形态分四个：API、SDK、CLI、MCP，走的是同一套校验、权限和日志。

MCP 是让智能体发现并调用工具的通用协议：工具的名字、参数和说明都在协议里，智能体不必先去学命令行的参数。

各入口按调用人的权限读同一份对象。API、SDK、CLI 可按权限执行 Action；Ontology MCP 的业务工具只读。选入口时，要同时看使用者和入口支持的操作。

同一个问题，几种写法

拿示例工厂的「在产的工单」举例。用 SDK：条件写在 where，一页取二十条，按到期时间排。

const client = semantic.ontology();
const running = client.objects("WorkOrder").where({ status: "running" });
const page = await running.fetchPage({ $orderBy: { dueAt: "asc" }, $pageSize: 20 });

用 CLI：同一个条件，同一个排序。写操作先只校验，看每一项的结果，再去掉 --validate-only 执行。

aidc semantic objects WorkOrder --where '{"status":"running"}' --order-by dueAt:asc --page-size 20
aidc semantic apply hold-work-order --param workOrder=WO-1001 --validate-only

报表可用 Ontology SQL。Postgres 只为符合条件的类型建视图。一条 SELECT 最多返回 10,000 行，20 秒超时。SQL 只读；业务修改用 Action。

aidc semantic sql 'SELECT status, count(*) FROM "WorkOrder" GROUP BY 1' --csv

REST 直接调用 HTTP：POST /api/v2/ontologies/{ns}/objects/WorkOrder/search，请求体写条件。API、SDK、CLI 读同一份对象，执行相同的权限检查和校验。

谁用哪一个

账号的角色也决定能走哪个入口：公司成员同样可以登录 CLI，但只能调用本公司已经发布的应用；读写 Ontology 的命令，要这家公司的开发者。

智能体动手之前，先读一遍全貌最顺手：aidc semantic ontology 会列出对象类型、主键、关系、Action 和接口，智能体照着它选对象、拼条件。

凭证的读取顺序是：环境变量 AIDC_API_KEY，然后是本机的 ~/.aidc/config.json。密码只由人本人输入，智能体不索要、不转述、不保存。

多数入口要登录或带凭证。Open to Internet 应用支持匿名只读，嵌入的 Custom widget 可调用允许的 Semantic 读接口。匿名访客不能执行 Action，也不能查 SQL。

定义也是文件

本体（Ontology）定义是 JSON 文件，可与代码一起进版本库。智能体不直接改 main：先开分支，试跑，再保存定义并提案。review 策略由人审核合并；yolo 允许合格 Key 批准，检查通过后自动合并。

分支接收一整份定义清单。顺序是开分支、试跑、正式保存、检查。--dry-run 不保存定义，不能省掉正式的 branch modify。

aidc semantic branch create add-maintenance
aidc semantic branch modify add-maintenance ontology/ --dry-run
aidc semantic branch modify add-maintenance ontology/
aidc semantic branch validate add-maintenance

合并前有六项检查：引用闭合、名字唯一、主键规则、可编译、和 main 无冲突、破坏性改动已确认。--dry-run 只检查、不落库；validate 看合并检查是否通过。智能体作者直接改 main，会得到 409 branch_required。这是常见的坑：用带 AIDC_AGENT_ID 的开发者 Key 直接定义 main，同样会被拦下。

四个入口各有专门的课：第 8 门课讲工具链，第 9 门课讲权限与分支，第 10 门课讲让智能体来建。下一节看最上面一层：应用与智能体怎样用它们。