文件附件指南

附件用于为长期记忆补充来源材料。TokST 将受保护的对象存储在 Cloudflare R2，并在已授权工作区中保存可检索的元数据。

用户后台上传

在用户后台打开一条记忆，使用附件面板上传文件。后台显示上传进度、已生效附件和文件生命周期操作。上传敏感材料前，请确认记忆所属工作区和知识库，并使用有意义的文件名。

云端 MCP 上传

使用 tokst_attach_file 为已有记忆添加附件，传入记忆 ID 与可下载的 HTTPS URL。ChatGPT 可通过 files[].download_url 提供已托管文件。本地文件请通过后台附件面板上传；远端服务无法读取客户端本地路径或 file:// URL。公开端点为：

https://api.tokst.com/mcp

{
  "memoryId": "mem_example",
  "fileUrl": "https://example.com/architecture.png"
}

云端 MCP 向已授权调用方返回文件元数据和短期有效的签名下载链接。支持文件参数的聊天客户端也通过同一治理流程添加上传内容。

云端 MCP 仅接受公开可下载的 HTTPS 来源。系统会拒绝本地路径、file:// URL、私有网络地址、重定向到私有网络的地址、空文件、无法确定大小的来源和超过 100 MB 的文件。失败响应会返回阶段化错误码，例如 attachment_source_unreachable、attachment_upload_authorization_failed、attachment_storage_quota_exceeded、attachment_storage_upload_failed 或 attachment_confirmation_failed，并附带下一步建议。

文件生命周期

上传初始状态为 pending。TokST 确认 R2 对象并校验大小和 MIME 类型后，将其标记为 active。缺失、为空或过期的待处理上传保留可诊断状态，并按保留策略清理。

访问与限制

工作区成员关系控制文件访问。签名上传链接有效期为一小时，签名下载链接有效期为十五分钟。用户后台按账户存储配额执行限制。云端 MCP 单个附件最大为 100 MB。

请勿上传凭据、私钥、浏览器 Cookie、访问 token，或工作区策略不允许离开源设备的数据。

存储路径

TokST 使用以下范围化路径存储附件对象：

{workspace_id}/{atlas_id}/{memory_id}/{attachment_id}-{filename}

该范围可避免跨工作区冲突，并支持在 Dashboard 归档视图手工永久清除已归档记忆或知识库时清理对象。

Runtime 边界

Cloud MCP 是智能体附件接口，用户后台是人工文件管理入口。可选 CLI Runtime 管理设备、智能体 Binding、会话、任务、沟通与诊断。