cargo-content

Cargo CLI — 内容管理

工作区文件：上传和整理文件（PDF、CSV、文本），并将其分组或同步到知识库——为 Agent 响应提供依据的知识资源（检索增强生成，RAG）。文件也可作为普通存储：通过 CLI、HTTP 对象 API、托管工作器、工作流节点或 Agent，按路径写入文件、读取文件、列出文件夹并分享链接，详见 将文件用作存储。

新增顶级域名（CLI ≥ 1.0.19）。 文件和知识库已从 ai 域迁移到 content 域——cargo-ai content file … 和 cargo-ai content library …。旧的 cargo-ai ai file … 命令已不存在；如果出现 unknown command 错误，说明你使用的是旧路径。

若要将文件或知识库附加到 Agent（通过发布版本的 resources 数组），请使用 cargo-ai。 若要使用文件夹整理文件，请使用 cargo-workspace-management（cargo-ai workspaceManagement folder …）。 若要使用批量运行的输入文件（用于驱动批量处理的 CSV），请使用另一个功能入口——cargo-ai workspaceManagement file upload，相关文档见 cargo-workspace-management。

端到端的文件、知识库和将文件附加到 Agent 的示例，请参阅 references/examples/files.md。 有关将文件用作存储的说明，请参阅 references/objects.md：路径模型、存储设置及其在不同功能入口中的默认值、签名链接和公开链接、上下文镜像，以及 HTTP、工作器、节点和 Agent 功能入口。 完整的 JSON 响应结构请参阅 references/response-shapes.md。 常见错误及其解决方法请参阅 references/troubleshooting.md。

初始化

已登录（cargo-ai whoami 返回工作区）？请跳到下一节。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

每条命令都会将 JSON 输出到 stdout；失败时以非零状态码退出，并返回 {"errorMessage": "..."}。任何会创建运行或批量任务的命令都是异步的——请传入 --wait-until-finished，或轮询对应的 get 命令。安装完整的技能包后，../cargo/references/prerequisites.md 会补充 CLI 版本固定、令牌作用域和仅限管理员使用的功能入口说明。

先发现资源

cargo-ai content file list                 # all uploaded files (uuid, name, contentType, size)
cargo-ai content library list              # knowledge libraries (native or connector-backed)

文件

上传文件（PDF、CSV、文本），让 Agent 能基于特定知识生成响应。上传响应会包含 uuid，将文件附加到 Agent 发布版本时会用到它（参见 cargo-ai）。

# List all files
cargo-ai content file list

# Get a single file
cargo-ai content file get <file-uuid>

# Upload a file (optionally straight into a folder)
cargo-ai content file upload --file ./knowledge-base.pdf
cargo-ai content file upload --file ./knowledge-base.pdf --folder-uuid <folder-uuid>

# Update a file's name or folder
cargo-ai content file update --uuid <file-uuid> --name "Q1 Research Notes"
cargo-ai content file update --uuid <file-uuid> --folder-uuid <folder-uuid>

# Remove a file
cargo-ai content file remove <file-uuid>

上下文仓库中的内容文件。 设置了 mirrorToContext: true 的文件——这是 upload、Web 应用上传和 defineFile 的默认值——会提交并推送到上下文仓库的 .files/<path> 目录中（提交信息为 content(mirror): upsert <name>；超过 10 MB 时会写入 JSON 元数据伴随文件，而非文件字节），因此上下文运行时沙箱中的命令可以读取该文件，例如 cargo-ai context runtime execute --command ls --args '["-1",".files"]'；拥有该仓库访问权限的任何人也可以读取。按路径写入文件（put、对象 API、工作器、节点、Agent）的默认值为 mirrorToContext: false，不会写入 git。上下文运行时只能读取 .files/（写入会因 deniedPath 被拒绝）；请在此处使用 content file 修改这些文件。参见 cargo-context。

将文件用作存储（路径和链接）

文件的 路径 由文件夹层级和文件名组成（reports/2026-q3/summary.pdf）。写入路径会创建缺失的文件夹，并原位覆盖该名称的最新文件（保留相同的 uuid，除非传入新设置，否则保留原设置）。

cargo-ai content file put reports/2026-q3/summary.pdf --file ./summary.pdf   # → { file, path }; any size
#   --content-type <mime> (guessed from the extension) · --index none|vectorStore (none)
#   --visibility private|public (private) · --mirror-to-context (off)
cargo-ai content file ls reports/ --limit 100            # prefix match, ordered by path; --limit ≤ 1000, --cursor <nextCursor>
cargo-ai content file download reports/2026-q3/summary.pdf --out ./copy.pdf
cargo-ai content file url reports/2026-q3/summary.pdf --expires 3600 [--download]   # → { url, expiresAt, publicUrl? }
cargo-ai content file visibility reports/2026-q3/summary.pdf public   # private revokes the public link at once
cargo-ai content file rm reports/2026-q3/summary.pdf

选项	upload / Web 应用 / defineFile	put / 对象 API / worker / writeFile 节点	Agent 写入
indexMode (--index)	vectorStore	none	始终为 none
mirrorToContext	true	false	始终为 false
visibility	private	private	始终为 private

通过 HTTP 操作的相同文件称为对象——PUT / GET（使用 ?meta=true 获取详情）/ DELETE /v1/content/objects/<path>、GET /v1/content/objects?prefix=；在 worker 中使用 createCargoObjects(env)（@cargo-ai/worker-sdk）；在 play 中使用 writeFile / readFile / getFileUrl 节点；在 Agent 上使用可写文件夹（capability_file_write）。所有相关说明见 references/objects.md。

库

库用于归集文件。Agent 发布版的 resources 接受文件或文件夹条目，而不是库 UUID，因此 Agent 通过库中的文件或这些文件所在的文件夹来访问库。库有两种：

• native — 由工作区管理的已上传文件集合（不能通过 CLI 创建：library create 仅适用于连接器）。
• connector — 通过非结构化数据提取器（--extractor-slug）从外部来源（例如帮助中心或知识库）同步。通过 cargo-connection 获取 connectorUuid。

# List libraries (filter by kind or connector)
cargo-ai content library list
cargo-ai content library list --kind native
cargo-ai content library list --kind connector --connector-uuid <connector-uuid>

# Get a single library
cargo-ai content library get <library-uuid>

# Create a connector-backed library
cargo-ai content library create \
  --name "Help Center" \
  --connector-uuid <connector-uuid> \
  --extractor-slug <extractor-slug> \
  --folder-uuid <folder-uuid> \
  --config '{}'

# Update / remove
cargo-ai content library update --uuid <library-uuid> --name "Updated Name"
cargo-ai content library remove <library-uuid>

重要规则

• 签名 URL 无需身份验证。 持有该 URL 的任何人都能打开文件，直到 URL 过期（默认 3600 s，最长 10800 s）。public 文件还会生成一个稳定的免身份验证链接 https://api.getcargo.io/files/public/<uuid>/<name>，在文件设为私有或被删除之前一直有效。只有在用户要求分享文件时才提供这两种链接，绝不要用于记录级别的个人数据。
• upload 和 put 的默认行为不同。 upload 会建立索引（vectorStore，发送至 OpenAI），并将文件镜像到上下文仓库；put 两者都不会执行。通过 put 写入的文件无法被 Agent 搜索——capability_file_search 会跳过它，capability_file_analyze 会拒绝处理它——除非使用 --index vectorStore 写入。
• 镜像文件会进入 git。 mirrorToContext: true 会将文件提交到上下文仓库的 .files/ 下；对于应保留在 Content 中的文件，请传入 --index none 并关闭镜像（使用 put）。
• 按路径写入会直接覆盖，不会询问。 该文件夹中同名的最新文件会被原位替换，其 uuid（以及所有指向它的 Agent 资源）现在都会提供新字节内容。只读（连接器）文件夹会拒绝写入并返回 folderReadOnly。

附加到 Agent

文件和库是知识资源——只有将其附加到 Agent 的草稿发布版 resources 数组中并部署后才会生效。相关配置位于 cargo-ai（ai release update-draft --resources … → ai release deploy-draft）。上传 → 附加 → 部署的流程见 references/examples/files.md。

帮助

每个命令都支持 --help：

cargo-ai content file upload --help
cargo-ai content library create --help