文件：Media sets 与 Space

Media sets 存放图片、文档、音视频等文件。字节存在组织自己的 S3 存储里，Semantic 只存元数据。Space 是每个人和每个智能体自己的空间，放页、文件和站点，并分享给人、智能体或组。

快速上手

先建一个媒体集，再上传一个文件。

$ aidc semantic media-sets create --name 巡检照片 --schema IMAGERY
已建：ri.mio.aidc.media-set.…  巡检照片  IMAGERY  0 项
下一步：aidc semantic media-sets upload ri.mio.aidc.media-set.… <文件>
$ aidc semantic media-sets upload ri.mio.aidc.media-set.… pump.png --path line-a/pump.png
已上传 line-a/pump.png（184320 B）→ ri.mio.aidc.media-item.…
$ 

在代码里做同样的事：

import { semantic } from "/developer/sdk/v1/aidc.js";

const photos = await semantic.mediaSets.createMediaSet({ name: "巡检照片", mediaSchema: "IMAGERY" });
const { mediaItemRid } = await semantic.mediaSets.upload(photos.rid, bytes, { mediaItemPath: "line-a/pump.png" });

媒体集

这一节讲媒体集怎么存文件、怎么读文件、怎么删文件。

选择 schema

建媒体集时，--schema 决定能放什么文件。

平台按文件头认格式。平台拒收格式不符合 schema 的文件，返回 invalid_media_item_schema。文档媒体集可以用 --extra TXT,DOCX 加上额外的输入格式。

上传与版本

4.4 MB 以内的文件直接上传。更大的文件走直传。CLI 自动处理直传，字节直接进组织的 S3。单个媒体项最大 50 GB。

同一个路径再上传一次，旧文件变成历史版本。直接引用旧版本的地方仍然可读。

aidc semantic media-sets items <媒体集 RID> --path line-a/pump.png     # 这个路径的版本历史，新的在前

事务型媒体集

用 --transactional 建的媒体集，写入要放在事务里。提交后，事务里的媒体项对有读取权限的人可见。提交前，谁都读不到这些项，上传人也读不到，也拿不到引用。放弃事务，事务里的媒体项全部删除。一个分支同时只有一个打开的事务。一个事务最多 10,000 个媒体项。

aidc semantic media-sets transaction <媒体集 RID> open                    # 返回事务 ID
aidc semantic media-sets upload <媒体集 RID> <文件> --transaction <事务 ID>
aidc semantic media-sets transaction <媒体集 RID> commit <事务 ID>

虚拟媒体集

虚拟媒体集登记组织存储里一个文件夹下已有的文件。它不拷贝文件。文件夹里出现新文件后，运行 sync 登记。虚拟媒体集不会删源文件。

aidc semantic media-sets create --name 知识库 --schema DOCUMENT --virtual <源文件夹>
aidc semantic media-sets sync <媒体集 RID>

读文件

• text 只提取 PDF 和 TXT 的文字，HTML、CSV 不算。输入最大 64 MB。PDF 抽取结果最多 5,000,000 个字符。智能体读文件用这个。
• 0 字节的文件不收。
• metadata 返回可解析的元数据。字段随格式和解析结果变化。无法解析时可能返回 untyped。超过 64 MB 的 PDF 不解析页数和标题。超过 64 MB 的 XLSX 不解析表名。
• download 把文件写到本机。

aidc semantic media-sets text <媒体集 RID> <媒体项 RID>
aidc semantic media-sets download <媒体集 RID> <媒体项 RID> --out pump.png

读内容时，服务端返回 302，跳到一个 10 分钟有效的预签名地址。fetch 会自动跟随。

删除与保留期

• clear --path <路径> 做软删。按路径取不到这个文件，但已经引用它的地方仍可读。
• 保留策略决定什么时候永久删除。上传后超过 --older-than 天，或被覆盖、删除后超过 --overwritten-after 天，永久删除。0 表示不删。缩短保留期后，已到期的媒体项立即不可读。清理任务随后永久删除字节。
• 删掉整个媒体集后，里面软删的项 30 天后永久删除。

aidc semantic media-sets retention <媒体集 RID> --older-than 365 --overwritten-after 30

对象上的文件

这一节讲对象怎么指向媒体集里的文件。对象的图片、文档等放在媒体引用属性（mediaReference）里。属性指向媒体集中的一个媒体项。附件用附件属性（attachment）。

Object Type 的 datasources 里加一条 media 来源，属性才能存文件：

"datasources": [
  { "type": "media", "mediaSourceRids": [{ "type": "mediaSetRid", "mediaSetRid": "ri.mio.aidc.media-set.…" }], "properties": ["photo"] }
]

• 一个属性只能由一个媒体来源支撑。媒体来源必须是本组织的媒体集。
• 有多个媒体来源时，第一个是上传目标（Upload destination）。
• 媒体引用属性不支持数组。

上传到媒体引用属性，用命令行：

aidc semantic upload-media-content inspection photo ./pump.jpg --content-type image/jpeg

命令直接上传到组织的 S3，输出一个 MediaReference（JSON）。一小时内把它交给 Action 的参数，它才会保存进属性。旧的命令名 aidc semantic upload-media 照样能用。

在代码里，临时媒体、读元数据和读内容这样写：

import { semantic, createAttachmentUpload } from "/developer/sdk/v1/aidc.js";

const client = semantic.ontology();
// Action 参数直接给文件：SDK 先上传，再提交
await client.action("record-inspection").applyAction({
  inspectionId: "I-2",
  photo: { fileName: "pump.png", data: file },
  report: createAttachmentUpload(pdf, "巡检单.pdf"),
});

// 取回的对象上，媒体引用属性就是 Media，附件属性就是 Attachment
const inspection = await client.objects("inspection").fetchOne("I-1");
const meta = await inspection.photo.fetchMetadata();
const photo = await (await inspection.photo.fetchContents()).blob();

• 媒体引用属性有 fetchMetadata、fetchFullMetadata、fetchContents 和 getMediaReference。读完整元数据，要有媒体集的读取权限。
• 附件属性有 rid、fetchMetadata 和 fetchContents。多值属性是数组。
• 超过 4.4 MB 的附件，SDK 自动走直传。

附件的上限是 200 MB。上传后一小时内要关联到 Action。一个附件最多关联 10 个对象。

媒体集的访问沿本体继承。配成某个属性的媒体来源以后，能看到这个对象和这个属性的人，就能读它的媒体。

• 附件关联以后，跟着对象的权限走。看不见的附件，不能再关联到别的对象。
• 一个附件一生最多关联 10 个对象。开了 Action Log 的 Action，Action Log 对象也算一次。
• 没带凭证时，返回 401「请先登录」。别家组织的媒体集或附件 RID，和不存在的一样返回 404。

整页 HTML、SVG 这类会执行的内容，只在对象页的沙箱框里显示。在地址栏直接打开这类内容，平台转到对象页的整页媒体：/semantic/<组织>/objects/<类型>/<主键>?embedded=true&media=<属性>。

Space：每个人与智能体的空间

Space 在 /semantic/<组织>/space。组织里每个人和每个智能体都有自己的空间，叫 Your files。人和智能体在 Space 里一样：都能放东西，都能被分享。

上传不超过 1,500,000 字节的 .html 文件，平台自动部署成站点。超过此上限时只保存为文件。

$ aidc space ls
Demo Company（cell-demo）
0123456789abcdef01234567  页    周会纪要
                          张三 · owner · private · 2026-10-08 14:03
89abcdef0123456789abcdef  站点   周报
                          张三 · owner · private · 2026-10-08 13:20
$ 

$ aidc space deploy weekly-report.html --name "周报"
已部署：https://www.ai-dc.ai/…
查看：https://www.ai-dc.ai/…
版本 1 · 1 个文件 · 18432 字节

开放程度 private：aidc space share 89abcdef0123456789abcdef --tier …（private / group / public / internet）
$ aidc space share 89abcdef0123456789abcdef --user li.si@example.com --group cell-demo --role viewer
已分享，开放程度 private
$ 

• 只有 Owner 能分享、放进回收站、永久删除。
• 分享的对象是人、智能体或组。角色有 Owner、Editor 和 Viewer。
• 站点的开放程度设成 Open to Internet，不登录也能打开。
• 智能体读到的内容，不超过它的 owner。分享给智能体时，加 --also-owner，同时分享给它的 owner。
• 智能体不能把东西开到 Public 或 Open to Internet。这要由人来设。
• 页返回 Markdown 原文。文件跳到预签名地址。站点在浏览器里去托管页，用 Key 读时返回 HTML 原文。
• 会执行的文件（HTML、SVG）在浏览器的框里打开时，平台在内容地址上出页面。框里的页面可以自己刷新、加参数。在地址栏打开时，平台转到查看页。

删除分两步。先放进回收站。站点在回收站里立即停止服务，可以恢复。再永久删除。字节、站点和分享一起删除，不能恢复。

$ aidc space empty-trash --dry-run
回收站里有 3 项（12.4 MB）：去掉 --dry-run 就永久删除。
$ 

在代码里：

import { semantic } from "/developer/sdk/v1/aidc.js";

const site = await semantic.space.deploySite({ displayName: "周报", html });
await semantic.space.share(site.id, { to: [{ type: "group", id: "cell-demo" }], tier: "group" });

const shared = await semantic.space.list({ tab: "shared" });                // 分享给我的
const { markdown, version } = await semantic.space.readPage(pageId);
await semantic.space.update(pageId, { markdown: markdown + "\n- 新的一行", baseVersion: version });

多文件站点与版本

aidc space deploy 接受一个目录、一个 zip，或一个 HTML 文件。每次上传是站点的一个版本。部署哪个版本，网页就显示哪个版本。

$ aidc space deploy ./dist --name "报告" --dry-run
本地校验通过：将建站点「报告」，版本 1，12 个文件，482133 字节。没有创建或上传。
新站点建在 Your files，缺省 Private。
$ aidc space deploy ./dist --name "报告"
已部署：https://www.ai-dc.ai/…
查看：https://www.ai-dc.ai/…
版本 1 · 12 个文件 · 482133 字节

开放程度 private：aidc space share 0123456789abcdef89abcdef --tier …（private / group / public / internet）
$ 

站点包的规则：

• 根目录要有 index.html。最多 1,000 个文件，解压后最多 20 MB。
• 资源用相对路径。用 Vite 构建时，写 base: './'。以 / 开头的引用会收到提醒。
• 不能含 .env 这类隐藏路径，也不能含符号链接。
• 命令在本机把目录打成 zip，用服务端同一套规则校验。zip 不超过 4 MB 时经 API 上传。更大的 zip 自动分片，直传组织的 S3。

版本的规则：

• 缺省上传即部署。加 --upload-only 只上传，不部署。
• --version 给版本起名，例如 release-2。名字只含字母、数字、.、_、-，最长 64 个字符。
• 版本不能改。部署旧版本，就是回滚。正在部署的版本不能删。
• 新站点是 Private。更新已有站点时，受众不变。用 aidc space share <id> --tier … 分享。
• 撤下站点，网页立即停止服务。没部署的版本有一个 12 小时有效的预览地址。
• 收窄受众不会让已经拿到地址的人失去文件。要立即切断，撤下站点，或部署一个新版本。

aidc space deploy bundle.zip --site <id> --version release-2 --upload-only   # 上传一个版本，不部署
aidc space deploy ./dist --site <id> --dry-run                               # 本机与服务端都校验，不上传
aidc space versions <id>                                                     # 版本列表
aidc space version <id> release-2                                            # 一个版本的文件清单
aidc space deploy-version <id> release-2 --dry-run                           # 看计划：从哪个版本换到哪个版本
aidc space deploy-version <id> release-2                                     # 部署这个版本。部署旧版本即回滚
aidc space undeploy <id> --dry-run                                           # 撤下站点
aidc space rm-version <id> release-1 --dry-run                               # 删一个没在部署的版本
aidc space get <id> --out ./source --version release-2                       # 下载一个版本的全部文件

• 没写 --site 的 --dry-run 只在本机校验，不建站点。写了 --site，服务端也校验，返回 202。
• 超过 4 MB 的 zip 不能在服务端预演。SDK 报 payload_too_large，不开直传会话。
• --title 等同 --name，--update 等同 --site。

在代码里：

• Viewer 能下载部署版本的源码。看版本列表和没部署的版本，要 Editor。删除版本，要 Owner。
• 智能体的 Key 仍受它的 owner 的权限限制。

用 MCP 连 Space

Space 有一个 MCP 服务器。智能体用它读页、改页、部署站点、分享。

https://www.ai-dc.ai/api/v1/space/mcp

• 传输是 Streamable HTTP，无状态，只回 JSON，不开 SSE。
• 凭证是开发者 Key（aidc-dk-…）或 Agent Key（aidc-sk-…），写在 Authorization: Bearer …。不认登录 cookie、OAuth 令牌和应用票据。
• Key 自带组织。给了 cell，要和 Key 的组织一致。
• 受限的 Agent Key：读要 api:use-filesystem-read，写要 api:use-filesystem-write。角色、组和 owner 的上限照旧。
• 每个账号每分钟最多读 300 次、写 60 次。

在 Claude Code 里添加。Key 放在环境变量 AIDC_API_KEY 里，不写进脚本：

claude mcp add --transport http aidc-space \
  https://www.ai-dc.ai/api/v1/space/mcp \
  --header "Authorization: Bearer $AIDC_API_KEY"

在 Codex 里添加，写进 ~/.codex/config.toml：

[mcp_servers.aidc_space]
url = "https://www.ai-dc.ai/api/v1/space/mcp"
bearer_token_env_var = "AIDC_API_KEY"

• deploy_space_site 的 files 每项写 { path, text } 或 { path, base64 }，二选一。平台先校验全部文件，有问题时返回问题清单，不建站点。
• 根目录要有非空的 index.html。新站点必须写 displayName，缺省 Private。deploy 缺省是 true。
• JSON 请求体最多 4.5 MB。更大的包用站点的直传接口。
• 改页前，先用 read_space_item 读 Markdown，再带 baseVersion 更新。冲突时，先读最新的再改。
• 智能体的 Key 不能设 Public 或 Open to Internet，也不能把东西开到组织外。外部分享由人来设。
• share_space_item 的 to 可以是人、智能体或组。roleId 缺省是 viewer，alsoOwner 缺省是 false。
• 工具出错时返回 isError: true 和说明。一次响应最多 4 MB，超过时返回 isError: true，不返回截断的源码。

命令行

本页讲的主要命令如下。

其余媒体集命令见 参考 · 数据接入。其余 Space 命令见 参考 · 访问、自动化与用量。

API

媒体集的端点，都在 /api/v1/mediasets 下。

Space 的端点，都在 /api/v1/space 下。

站点的版本接口都在 /api/v1/space/items/{id}/website 下。

上传、部署、撤下、删除都支持预演：加 ?dryRun=true 或请求头 x-aidc-dry-run: true，返回 202。

页返回 Markdown。站点使用 Key 访问时返回 HTML。网页登录或匿名访问时跳转到托管页。文件跳转到预签名地址。?download=true 设置文件下载。

限制

常见错误

下一步

• 数据接入：把数据送进 Semantic。
• 对象：Object Type、属性和媒体引用属性。
• 访问与安全：分享的角色、开放程度和标记。
• 参考 · 数据接入：媒体集的全部命令。
• 参考 · 访问、自动化与用量：Space 的全部命令。