旧写法与迁移

这一页列出改名前的 SDK 名、命令、API 路径和写法，并给出对应的新写法。旧写法照样能用，已上线的应用不用改。新代码请用新写法。

SDK 名

这一节列出旧 SDK 名和对应的新 SDK。1.20.0 把六个 SDK 并入 Semantic。1.22.0 把 improve 并入 evolve。

旧名	对应的新 SDK	并入版本
connect	semantic：数据流 semantic.stream、semantic.streams；智能体 model.agent	1.20.0
data	semantic：对象集 semantic.ontology()，见数据层的写法	1.20.0
auth	semantic：账号与成员 semantic.admin；资源与分享 semantic.filesystem	1.20.0
workflow	semantic.automate	1.20.0
log	semantic.observability	1.20.0
billing	semantic.usage	1.20.0
improve	evolve。除 decide 改为 decideProposal 外，其余函数同名	1.22.0

旧名在浏览器 SDK（aidc.js）里照样导出，写法也照样能用。下面是一个例子：

// 旧
import { log } from "/developer/sdk/v1/aidc.js";
log.track("export", { format: "csv" });

// 新
import { semantic } from "/developer/sdk/v1/aidc.js";
semantic.observability.track("export", { format: "csv" });

代码改成导入 semantic 后，清单的 sdk 也要登记 semantic。aidc app check 会检查这一项。

命令

这一节列出旧命令和新命令。多数旧命令只换了组名，子命令不变。

旧命令	新命令	说明
aidc stream …	aidc semantic streams …	数据流，子命令不变
aidc resources …	aidc semantic filesystem …	访问和分享，子命令不变
aidc members …	aidc semantic admin members …	成员，子命令不变
aidc workflow …	aidc semantic automate …	自动化，子命令不变
aidc log …	aidc semantic observability …	日志，子命令不变
aidc billing …	aidc semantic usage …	用量与账单，子命令不变
aidc improve …	aidc evolve …	子命令不变
aidc semantic act <Action>	aidc semantic apply <Action>	对象主键写成 --param __object=<主键>
aidc data query <类型>	aidc semantic objects <类型>	--where 的写法不变
aidc data get <类型> <主键>	aidc semantic object <类型> <主键>	链接用 aidc semantic links，历史用下一行
aidc data get … --history	aidc semantic edits-history <类型> --pk <主键>	只包含 Action 产生的改动，不覆盖全部旧历史
aidc data aggregate	aidc semantic aggregate <类型>	用 --select、--where、--group-by
aidc data watch --types <类型>	aidc semantic subscribe <类型>	每次变化打一行
aidc data bind <流> <类型> --map …	aidc semantic datasource set <类型> --stream <流> --map …	数据源写在类型定义里
aidc data bindings	aidc semantic datasource list	看各类型的数据源和同步进度
aidc data resync	aidc semantic datasource resync <类型> --stream <流>	重同步一个数据源
aidc data unbind	aidc semantic datasource remove <类型> --stream <流>	从类型定义里去掉数据源

下面的旧命令没有新命令。它们照样能用：

命令	说明
aidc data create、update、delete、import	直接写对象，只给开发者。改数据的新写法是 aidc semantic apply <Action>
aidc data profile、aidc data group	本地分析，不联网
aidc connect datasets、aidc connect report	固定报告，只含聚合。见固定报告
aidc connect send "<消息>"	和智能体对话。用 AIDC_AGENT_KEY

语义的旧写法

这一节列出 1.2.x 起的语义写法。这些写法照样能用，和新写法用的是同一份数据和同一套 Action 引擎。

旧写法	新写法	说明
semantic.describe()	不变	说明书，给智能体读
semantic.objects(类型)	semantic.ontology().objects(类型)	新代码用 ontology()
semantic.action(名字).apply(参数, 选项)	semantic.ontology().action(名字).applyAction(参数, 选项)	写数据的参数，见读写对象
semantic.define(…)、defineAll(…)	不变	智能体改本体要在分支上做，见定义本体
semantic.publish(说明)	不变	发布一个语义版本
aidc semantic act	aidc semantic apply	见命令
aidc semantic describe	不变	--markdown 输出给大模型读的说明书
aidc semantic define、aidc semantic publish	不变	同上

数据层的写法

这一节列出旧数据层（data）的写法和对象集的写法。对象集的写法是 OSDK 的形状。下表的 … 代表 semantic.ontology().objects(类型)。改数据请用 Action。

旧写法（data）	新写法（semantic.ontology()）
data.table(类型).list({ where, sort, limit })	…where(条件).fetchPage({ $pageSize, $orderBy })
list() 返回 objects、total、seq	fetchPage() 返回 data、totalCount、nextPageToken
data.table(类型).all(…)	按响应的 nextPageToken 翻页，规则见下文
…get(主键)	…fetchOne(主键)
…get(主键, { link })	client.linked(类型, 主键, 链接)
…get(主键, { history: true })	client.editsHistory(类型, { primaryKey: { … } })
…aggregate({ groupBy, metrics })	…aggregate({ $select, $groupBy })
…live({ onUpdate })	…where(条件).subscribe(监听, { properties })
data.watch({ types, after }, 监听)	对象集订阅，见上一行
…create、…update、…remove	没有新函数。改数据用 client.action(名字).applyAction(参数)
…import(行)	批量数据走数据流和数据源，见数据接入
data.sync.bind、list、resync、unbind	照样能用，写法不变
data.parseCsv、toCsv、profile、groupBy 等	照样能用。这些是纯函数，不连平台

把响应的 nextPageToken 传给下一次 fetchPage 的 $nextPageToken。响应没有 nextPageToken 时停止。

新编辑历史只包含 Action 产生的改动。它不覆盖同步、导入和直接编辑产生的旧历史。

• 旧数据层的 list({ pks: [主键, …] }) 只在这些对象里查，最多 100 个。
• 旧数据层的直接写（create、update、remove、import --layer edits）只对开放了直接编辑的类型有效。见对象的编辑方式。

查询的例子：

// 旧
const page = await data.table("orders.order").list({ where: { status: "open" }, sort: ["-amount"], limit: 50 });

// 新
const client = semantic.ontology();
const page = await client.objects("orders.order").where({ status: "open" }).fetchPage({ $pageSize: 50, $orderBy: { amount: "desc" } });

条件的写法不变：{ 属性: 值 } 表示相等，$or 表示任意一组成立。

固定报告

这一节说明 Semantic 之前的固定报告。这些报告照样能用，只含聚合。

connect.datasets.list() 列出能读的数据集。connect.datasets.report(数据集, 报告) 返回一份固定报告。命令行的 aidc connect datasets 和 aidc connect report 也照样能用。

新应用用对象集的聚合，不用固定报告：semantic.ontology().objects(类型).aggregate(…)。

已停用的效果

这一节列出已停用的自动化效果和它们的替代写法。新建的自动化不接受它们，返回 automate_legacy_effect（422）。已有的自动化照常运行。替换时可以原样保留，迁走之后再去掉。

原来的效果（已停用）	换成
notification，channel 为 dingtalk 或 wecom	action 效果。执行一个发消息的 Action，这个 Action 配 side effect webhook
agentScript（在客户箱上跑的 Loop 脚本，读 Semantic）	函数：用 aidc semantic functions publish 发布，function 效果执行它
agentScript 的 deliver（脚本输出发消息）	action 效果，配 side effect webhook

webhook 挂在钉钉或企业微信的 REST 连接上。收件人和标题作为 Action 的参数传入。发给 AIDC 账号的邮件，仍用 notification 效果，channel 为 email。

效果的全部类型见自动化。

API 路径

这一节列出旧的 API 路径和它们的新路径。旧路径照样能用。

清单 sdk 里的旧名归到新名：

旧名	归到
data、connect、workflow、auth、log、billing	semantic
improve	evolve

旧路径	新路径或说明
/api/v1/developer/improve/{namespace}/…	/api/v1/developer/evolve/{namespace}/…。旧路径的响应带 Deprecation 头
/api/v1/developer/evolve/{namespace}/{slug}/…	/api/v1/developer/evolve/{namespace}/apps/{slug}/…。旧路径照样能用
/api/v1/ontologies/{ontology}/…	已标记废弃。有 v2 后继的接口，响应带 Deprecation: true 和指向 v2 的 Link。见 API 参考
/api/v1/ontologySubscriptions/…	已标记废弃。订阅改用 /api/v2/ontologySubscriptions/…（WebSocket）
/api/v1/developer/data/{namespace}/objects/{type}	照样能用。改数据请用 Action
/api/v1/developer/semantic/{namespace}/actions/{apiName}	照样能用。新接入请用 Ontology 的 Action 接口
/api/v1/sqlQueries/executeOntology	Postgres 方言，照样能用。响应带 Link: rel="successor-version"，指向标准方言 /api/v2/sqlQueries/executeOntology?preview=true。见 SQL 与数据库

Loop 报告以前用一个单独的发布入口。这个入口仍接受令牌的旧名。一份报告第一次在 AIDC 里发布后，旧入口对它返回 409。改用 aidc semantic loop-report publish。

以前只带 ?embedded=true 的报告全屏链接，在浏览器里直接打开仍是整页报告。新链接写 ?embedded=true&media=html。

缺省值的变化

1.65.0 改了两个缺省值。已经存在的定义不受影响。

项目	1.65.0 之前	现在	已有的定义
数据源不写 mode	mirror	upsert	已接好的数据源都存了明确的 mode，行为不变
新建 Object Type 的直接编辑	开放	只能经 Action 改	之前建的类型没有 editsConfiguration，照旧开放

新的 Object Type 名必须是 PascalCase。早先小写开头的名字照常能用，定义时给出警告。

迁移步骤

这一节说明怎么把一个应用从旧写法改到新写法。每一步都可以单独做。

1. 把代码里 log、data、connect 等的导入改成 semantic。在清单 sdk 里登记 semantic。
2. 把读对象的代码改成对象集，见数据层的写法。
3. 把改数据的代码改成 Action。
4. 把脚本和运维命令换成新命令，见命令。
5. 运行 aidc app check。检查通过后，内容改了，就升一级清单的 version。
6. 运行 aidc app deploy 部署到 test 通道。测过后运行 aidc app publish。

下一步

• 数据接入：数据流和数据源。
• 读写对象：对象集、订阅和 Action。
• 访问与安全：管理员、资源和分享。
• 自动化：效果的类型。
• 自进化：improve 已并入 evolve。
• API 参考：路径、凭证和错误码。