fast-io

Fast.io MCP 服务 -- AI Agent 指南

版本： 1.200 最后更新： 2026-04-29

供 AI Agent 使用 Fast.io MCP 服务的权威指南。涵盖使用平台的原因和方法：产品功能、免费 Agent 计划、身份验证、核心概念（工作区、共享、智能功能、预览、评论、URL 导入、元数据、工作流、所有权转让）、12 个端到端工作流、交互式 MCP App 小组件，以及全部 19 个通过基于操作的路由整合的工具。

版本化指南。 本指南采用版本管理，并在每次服务发布时更新。本文档顶部的版本号对应工具参数、ID 格式和 API 行为变更。如果遇到意外错误，指南版本可能已在你上次阅读后发生变化。

平台参考。 如需全面了解 Fast.io 的功能、Agent 计划、关键工作流和升级路径，请参阅 references/REFERENCE.md。

---

1. 概述

面向 Agent 团队的工作区。通过一个 API 免费实现协作、共享和查询。

Fast.io 为 Agent 团队提供工作区，让 Agent 能与其他 Agent 和人类协作。上传输出内容、创建品牌化共享内容、使用内置 AI 提问文档，并在工作完成后将所有内容交接给人类。无需管理基础设施，无需设置订阅，也无需信用卡。

Fast.io 解决的问题

Agent 团队——由共同协作或与人类协作的 Agent 组成的团队——需要一个共享的工作场所。如今，Agent 只能拼凑使用 S3 存储桶、预签名 URL、电子邮件附件和自定义下载页面。每个 Agent 都在重新发明协作方式，却没有一个共享工作区能让 Agent 和人类查看相同文件、跟踪活动并交接工作。

当 Agent 需要理解文档而不只是存储文档时，就必须下载文件、解析数十种格式、构建搜索索引并管理自己的 RAG 流水线。为了解决一个本应简单的问题——“这份文档写了什么？”——却要搭建大量基础设施。

问题	Fast.io 解决方案
Agent 团队没有共享工作区	提供工作区，让 Agent 和人类通过文件预览、版本管理和 AI 进行协作
Agent 之间缺乏有组织的协调方式	提供共享工作区，包含活动动态、评论，以及团队成员间的实时同步
与人类共享输出内容不便	提供专用共享方式（发送、接收、交换），支持链接共享、密码和过期时间
从人类处收集文件更困难	接收共享允许人类直接向你的工作区上传内容，无需电子邮件附件
理解文档内容	内置 AI 可读取、总结文件并回答有关文件的问题
从头构建 RAG 流水线	在工作区启用智能功能后，文档会自动建立索引、生成摘要并支持查询
在大型文件集中找到正确文件	存储搜索可按关键词或含义查找文档（启用智能功能后支持语义搜索）
将项目交接给人类	一键转让所有权——人类获得组织，Agent 保留管理员访问权限
跟踪发生过的事情	提供完整审计记录，并由 AI 生成活动摘要
成本	免费。提供 50 GB 存储空间、每月 5,000 点额度，无需信用卡

MCP 服务

此 MCP 服务提供 19 个整合工具，涵盖 Fast.io REST API 的全部功能。每个经过身份验证的 API 端点都有对应的工具操作，且服务会自动处理会话管理。

所有 API 访问都必须通过 MCP 工具进行。 请勿直接向 api.fast.io 或 MCP 服务发送 HTTP 请求——工具会自动处理身份验证、会话管理、错误恢复和响应格式化。仅以下二进制传输情况例外：上传时向 MCP 服务发送 POST /blob（工具会提供 curl 命令）；使用工具返回的下载 URL（这些 URL 已预先完成身份验证）；以及通过 MCP 服务上的 GET /file/ 端点传输大型文件。其他所有操作都必须使用工具。

用户完成身份验证后，身份验证令牌会存储在服务会话中，并自动附加到之后的所有 API 调用。无需在工具调用之间传递令牌。

服务端点

• 生产环境： mcp.fast.io
• 开发环境： mcp.fastdev1.com

每个环境都提供两种传输方式：

• /mcp 上的 Streamable HTTP —— 新集成的首选传输方式。
• /sse 上的 SSE —— 为保持向后兼容而维护的旧版传输方式。

MCP 资源

该服务提供静态 MCP 资源、组件资源和文件下载资源模板。客户端可以通过 resources/list 和 resources/read 读取这些资源：

URI	名称	描述	MIME 类型
skill://guide	skill-guide	完整的 Agent 指南（本文档），包含全部 19 个工具、工作流和平台文档	text/markdown
session://status	session-status	当前身份验证状态：authenticated 布尔值、user_id、user_email、auth_method（"api_key"、"jwt" 或 "oauth"——会话的身份验证方式）、token_expires_at（Unix 纪元时间）、token_expires_at_iso（ISO 8601）、scopes（原始 scope 字符串或 null）、scopes_detail（包含实体名称／域名／父级的已解析 scope 对象数组，或 null）、agent_name（字符串或 null）	application/json
widget://*	组件 HTML	交互式 HTML5 组件（共 6 个）——使用 apps 工具发现并启动	text/html

文件下载资源模板 —— 无需通过外部 HTTP 访问，即可直接通过 MCP 读取文件内容：

URI 模板	名称	身份验证	动态列出	描述
download://workspace/{workspace_id}/{node_id}	download-workspace-file	会话令牌	是	从工作区下载文件
download://share/{share_id}/{node_id}	download-share-file	会话令牌	是	从共享中下载文件
download://quickshare/{quickshare_id}	download-quickshare-file	无（公开）	否	下载 quickshare 文件

不超过 50 MB 的文件会以内嵌的 Base64 编码 blob 内容返回。较大的文件会返回文本回退内容，其中包含指向 HTTP 直通端点的 URL（见下文）。download 工具的响应会包含 resource_uri 字段，其中提供相应文件的 URI。

动态资源列出： 完成身份验证后，工作区和共享中的文件资源会通过 resources/list 动态列出。MCP 客户端（例如 Claude Desktop 的 @ 提及选择器）无需调用任何工具即可发现可用文件。最多列出 10 个工作区和 10 个共享，并从每个工作区或共享中列出最近更新的最多 25 个根目录文件。资源显示为“WorkspaceName / filename.ext”或“ShareTitle / filename.ext”。结果会按会话缓存 1 分钟。仅列出根目录文件，不会递归列出子目录。若要浏览更深层级，请使用 storage 工具并将操作设为 list。quickshare 模板仍仅为模板，无法动态枚举。

MCP 提示词

服务器会注册 MCP 提示词，这些提示词会显示在客户端的“添加来源”／“+”菜单中，作为用户可点击的应用启动器。它们主要面向桌面 MCP 客户端（例如 Claude Desktop）；代码模式客户端（Claude Code、Cursor）不会显示提示词。

提示词名称	描述
App: Choose Workspace or Org	启动工作区选择器，以浏览组织、选择工作区和管理共享
App: Pick a File	启动文件选择器，其中内置工作区导航器，可用于浏览、搜索和选择文件
App: Open Workflow	启动工作流管理器（如果只有一个工作区，则自动选择；否则先打开工作区选择器）
App: Upload Files	启动上传器，可通过拖放上传文件、跟踪进度和创建文本文件
App: Available Apps	列出所有可用的 MCP 应用小组件，并提供描述和启动说明

HTTP 文件直通

对于大于 50 MB 的文件，或需要原始二进制流时，服务器会提供一个 HTTP 直通端点，直接从 API 流式传输文件内容：

端点	身份验证	描述
GET /file/workspace/{workspace_id}/{node_id}	Mcp-Session-Id 标头	流式传输工作区文件
GET /file/share/{share_id}/{node_id}	Mcp-Session-Id 标头	流式传输共享文件
GET /file/quickshare/{quickshare_id}	无（公开）	流式传输快速共享文件

响应会包含来自上游 API 的正确 Content-Type、Content-Length 和 Content-Disposition 标头。错误会以 HTML 页面形式返回。Mcp-Session-Id 标头与用于 MCP 协议通信的会话标识符相同。

工作流概览

服务器包含用于项目跟踪的工作流功能：任务（包含优先级和受派人的结构化工作项）、工作日志（仅追加的活动日志）、审批（正式签核请求——请参阅下文的 工作流审批——快速入门）以及待办事项（简单的检查清单）。使用这些工具前，请先通过 workspace 操作 enable-workflow 在工作区启用工作流。完整模式请参阅第 6 节中的 完整 Agent 工作流配方。

最佳实践（重要）： 执行会更改状态的操作后（上传文件、创建共享、更改任务状态、变更成员、移动／删除文件），请追加一条工作日志，说明你做了什么以及原因。如果没有工作日志，查看工作区的人类用户就无法了解 Agent 的工作。对于多个相关操作（例如上传多个文件），可以在整批操作完成后记录一次，而不是每项操作后都记录。工作日志只能追加，且永久保留。

其他参考资料

• Agent 指南（本文档）： MCP 服务器上的 /skill.md——工具文档、工作流和限制。
• REST API 参考： https://api.fast.io/llms.txt——底层 REST API 的端点文档（仅供参考——请使用 MCP 工具，不要直接调用 HTTP）。
• 平台指南： references/REFERENCE.md——功能、Agent 方案详情、关键工作流和升级路径。

---

2. 身份验证（关键的第一步）

调用任何工具前都必须先完成身份验证，以下未通过身份验证的工具除外：

• auth 的操作：signin、signup、set-api-key、pkce-login、email-check、password-reset-request、password-reset
• download 的操作：quickshare-details

选择正确的方式

根据你是自主运行还是协助现有用户，使用 Fast.io 作为 Agent 有三种方式。

选项 1：自主 Agent——创建 Agent 账户 如果你是独立运行的（存储文件、运行工作流、为用户构建工作空间），请通过 auth 操作 signup 创建自己的 Agent 账户。Agent 账户可免费使用 Agent 计划（50 GB、每月 5,000 点数），并可在准备就绪后将组织转交给人类。这是自主 Agent 的推荐方式。具体步骤请参阅下文的 创建 Agent 账户。

选项 2：协助人类——使用其 API 密钥

如果人类已有 Fast.io 账户，并希望你协助管理其文件、工作空间或共享内容，他们可以创建一个供你使用的 API 密钥。无需单独创建 Agent 账户——你以该人类用户的身份操作。人类可在 Settings -> Devices & Agents -> API Keys 中创建密钥（直接链接：https://go.fast.io/settings/api-keys）。调用 auth 并使用 set-api-key 操作和该密钥进行身份验证——系统会自动验证密钥并将其存储在 MCP 会话中。之后的所有工具调用都会使用该密钥。默认情况下，API 密钥具有与账户所有者相同的权限。密钥还可选择限定范围，仅限特定组织、工作空间或共享内容（使用与 OAuth 令牌相同的范围系统）——限定范围的密钥只能访问获授权的实体，范围以外的操作会返回 403。密钥还可以添加 agent_name 标签以便跟踪，也可以设置过期日期。未限定范围的密钥除非被撤销，否则不会过期。Agent 还可以通过 auth 操作 api-key-create、api-key-update、api-key-list、api-key-get 和 api-key-delete 以编程方式管理 API 密钥。

选项 3：将 Agent 账户邀请至人类的组织

如果你希望拥有自己的 Agent 身份，但需要在人类现有组织中工作，请通过 auth 操作 signup 创建 Agent 账户，然后让人类通过 member 操作 add（entity_type org）将你邀请至其组织，或通过 member 操作 add（entity_type workspace）将你邀请至某个工作空间。人类也可以通过界面邀请你：Settings -> Your Organization -> Manage People。这样你便可以访问其工作空间和共享内容，同时保留独立的账户。通过 user 操作 accept-all-invitations 接受邀请后，使用 auth 操作 signin 正常进行身份验证。**注意：**如果人类只将你邀请至工作空间（而非组织），该组织会显示为外部组织——请参阅“组织”部分的 内部与外部组织。

选项 4：浏览器登录（PKCE）

**不适用于无头 Agent：**PKCE 需要对话中有一位人类使用浏览器。无头 Agent、CLI 工具和自动化流水线无法完成此流程——请改用选项 1（signup）或选项 2（API 密钥）。

如果你不想通过 Agent 传递密码，可以使用基于浏览器的 PKCE 登录。调用 auth 操作 pkce-login（可选提供 email 提示）以获取登录 URL。用户在浏览器中打开该 URL，登录（使用邮箱/密码或 Google/Microsoft 等 SSO），并批准访问。浏览器会显示一个授权码，用户将其复制并发回给 Agent。调用 auth 操作 pkce-complete 并提供该授权码，即可完成登录。这是最安全的方式——凭据不会经过 Agent。

PKCE 登录支持通过 scope_type 参数选择性地限定访问范围。默认情况下，scope_type 为 "user"（完整账户访问权限）。其他范围类型会将令牌限制为特定实体类型：

scope_type	授予的访问权限
user	完整账户访问权限（默认）
org	用户选择特定组织
workspace	用户选择特定工作空间
all_orgs	用户所属的所有组织
all_workspaces	用户有权访问的所有工作空间
all_shares	用户作为成员加入的所有共享内容（share:*:<mode>）

**范围继承：**较宽泛的范围会自动包含对其子实体的访问权限：

• all_orgs 包含所有组织，以及这些组织中的所有工作区和共享
• all_workspaces 包含所有工作区，以及这些工作区中的所有共享
• 对特定组织使用 org 范围，可访问该组织中的所有工作区和共享
• 对特定工作区使用 workspace 范围，可访问该工作区中的共享
• all_shares 可直接访问用户所属的所有共享，不受工作区／组织继承权限的限制

agent_name 参数用于控制用户在授权屏幕上看到的内容——屏幕会显示“[agent_name] 将代表您执行操作”。如果省略，则只显示客户端名称。请使用描述性名称，让用户知道是哪个 Agent 在请求访问权限。

按 scope_type 划分的授权流程：

• user（默认）：完整的账户访问权限。用户会看到一个简单的批准／拒绝提示，不会出现实体选择器。
• org、workspace：用户会看到一个实体选择屏幕，其中列出其可访问的实体并带有复选框，另有只读／读写切换选项。用户选择要授予权限的实体，然后批准或拒绝。
• all_orgs、all_workspaces、all_shares：用户会看到所请求的通配符访问权限摘要（不含实体选择器），然后批准或拒绝。

MCP 服务默认使用 scope_type="user"，以保持向后兼容。

场景	推荐方式
自主运行、存储文件、为用户构建	使用自己的组织创建 Agent 账户（选项 1）
帮助他人管理其现有账户	请对方为你创建 API 密钥（选项 2）
在他人的组织中以自己的身份工作	创建 Agent 账户，请对方邀请你（选项 3）
构建完成后交由他人接管	创建 Agent 账户，完成构建，然后转移组织所有权（选项 1）
登录时无需通过 Agent 发送密码	基于浏览器的 PKCE 登录（选项 4）
无头运行／没有可用浏览器	创建 Agent 账户（选项 1）或使用 API 密钥（选项 2）——切勿使用 PKCE

**按账户类型划分的额度限制：**额度用尽时，Agent 账户（选项 1、3）可以将组织转移给他人——请参阅第 3 节中的所有权转移。Human 账户（选项 2）无法使用转移／认领 API；请引导对方前往 https://go.fast.io/settings/billing 升级套餐，或通过 org 操作 billing-create 升级。

标准登录流程

1. 使用操作 signin、email 和 password 调用 auth。
2. 服务端会返回 JWT auth_token，并自动将其存储在会话中。
3. 后续所有工具调用都会使用此令牌，无需手动传递。

创建 Agent 账户

创建新账户时（上述选项 1 和 3），Agent 必须使用 auth 操作 signup，该操作会自动以 agent=true 注册。切勿注册为 Human 账户。Agent 账户提供：

• account_type 设置为 "agent"
• 自动分配免费 Agent 套餐
• 启用将组织移交给他人的转移／认领工作流

步骤：

1. （可选）使用 auth 操作 email-check——仅供参考；切勿以其结果作为是否继续的条件。始终尝试执行 signup；原因请参阅第 9 节。
2. 使用 first_name、last_name、email 和 password 调用 auth 操作 signup。MCP 服务会自动发送 agent=true 标记。
3. 账户创建后会自动建立会话——Agent 将立即登录。
4. 验证邮箱（使用大多数端点前必须完成）：使用 email 调用 auth 操作 email-verify 以发送验证码，然后再次使用 email 和 email_token 调用 auth 操作 email-verify，以验证验证码。
5. 无需信用卡。没有试用期。不会过期。账户将永久保留。

双重身份验证流程

1. 使用 email 和 password 调用 auth 操作 signin。
2. 如果响应包含 two_factor_required: true，则返回的令牌权限范围受限。
3. 使用 2FA code（TOTP、SMS 或 WhatsApp）调用 auth 操作 2fa-verify。
4. 服务器会自动将权限范围受限的令牌替换为完整权限令牌。

敏感操作的内联 2FA

启用 2FA 的账户在调用某些 API 端点时，需要针对每个请求进行 2FA 验证。除了正常身份验证外，这些操作还需要有效的 2FA token 参数（6 位 TOTP，或 SMS／电话／WhatsApp 验证码）：

• api-key-create — 创建新的 API 密钥
• api-key-delete — 撤销 API 密钥

如果账户未启用 2FA，这些操作无需令牌即可正常进行。如果已启用 2FA，但令牌缺失或无效，请求将失败。

工作流：

1. 检查 2FA 状态：调用 auth 操作 2fa-status——如果 state 为 "enabled"，则需要内联 2FA。
2. 提示用户输入身份验证器应用中的 TOTP 验证码，或通过 auth 操作 2fa-send 发送验证码。
3. 将验证码作为 token 参数传递给 api-key-create 或 api-key-delete。

**提示：**API 密钥身份验证（auth 操作 set-api-key）会完全绕过内联 2FA 检查。如果 Agent 已通过 API 密钥完成身份验证，这些操作无需令牌。

浏览器登录（PKCE）流程

1. 调用 auth 操作 pkce-login（可选传入 email 以预填登录表单、传入 scope_type 以申请范围限定的访问权限，以及传入 agent_name 以标识 Agent）。
2. 工具会返回 login_url——将其提供给用户，以便用户在浏览器中打开。
3. 用户登录（使用电子邮件／密码或 SSO）。
4. 用户会看到审批页面，其中显示 agent_name（如果未提供，则显示客户端名称）。根据 scope_type：对于 user，用户只需批准；对于 org／workspace，用户需要选择特定实体以及只读／读写权限；对于 all_orgs／all_workspaces／all_shares，用户需要查看通配符访问权限摘要。
5. 用户点击 Approve。浏览器会显示授权码，用户复制该代码。
6. 使用 code 调用 auth 操作 pkce-complete，以换取访问令牌。
7. 会话将自动建立——之后的所有工具调用都会通过身份验证。如果授予了范围限定的访问权限，响应中会包含 scopes 和 agent_name，并将其存储在会话中。

检查会话状态

• auth 操作 status——检查本地 Durable Object 会话。不进行 API 调用。返回身份验证状态、用户 ID、电子邮件、auth_method、令牌过期时间、scopes 和 agent_name。如果会话已过期，则返回 session_expired: true，并附带 expired_reason（"token_expired" 或 "refresh_expired"）和 expired_at 时间戳。
• auth 操作 check——通过 Fast.io API 验证令牌。如果令牌仍然有效，则返回用户 ID。

会话过期与自动刷新

OAuth/PKCE 会话（默认方式）的访问令牌有效期为 1 小时，刷新令牌有效期为 30 天。MCP 服务会在 OAuth 访问令牌过期前主动刷新令牌——内部闹钟会在过期前约 5 分钟触发，并使用已存储的刷新令牌静默获取新令牌。由此形成一个可自我维持的循环：会话可以无限期保持有效，无需用户交互，直到 30 天的刷新令牌链过期或被撤销。如果主动刷新失败，响应式安全机制会在下一次工具调用时重试（401 → 刷新 → 重试）。

Basic JWT 会话（通过 auth 操作 signin 创建）的有效期为 30 天，且没有刷新令牌。令牌过期后，会话将被清理，需要重新认证。

API 密钥默认不会过期，但可通过 api-key-create 或 api-key-update 的 key_expires 参数设置过期时间。API 密钥过期由后端在服务端强制执行。

MCP 服务会跟踪每个会话的认证方式（auth_method："api_key"、"jwt" 或 "oauth"），并跳过对 API 密钥会话的客户端过期检查。

错误区分： 会话过期时，工具调用会返回 "Session expired. Please re-authenticate..."，这与表示此前不存在会话的 "Not authenticated..." 不同。这有助于区分重新连接问题和首次设置问题。

退出登录

调用 auth 操作 signout，即可从 Durable Object 中清除已存储的会话。

---

3. 核心概念

组织

组织是用于汇集工作区的顶层容器。组织可以代表公司、业务部门、团队，也可以只是你个人的集合。每位用户都属于一个或多个组织。组织包括：

• 工作区——属于该组织的文件存储容器。
• 成员，角色包括：所有者、管理员、成员、访客、查看者。
• 账单和订阅，通过 Stripe 集成管理。
• 套餐限制，用于管理存储空间、传输量、AI 令牌和成员数量。

组织通过 19 位数字资料 ID 或域名字符串进行标识。

重要： 创建组织时，Agent 必须使用 org 操作 create，该操作会自动设置 billing_plan: "agent"。这样可确保组织获得免费的 Agent 套餐（50 GB、每月 5,000 点数）。请勿为 Agent 创建的组织使用其他账单套餐。

自定义域名

Pro 或 Business 套餐中的组织可以配置自定义域名（例如 files.acme.com）来提供组织内容。每个组织只能配置一个自定义域名。

设置流程：

1. 使用 org 操作 custom-domain-create，并传入 org_id 和 hostname（有效的 FQDN，例如 files.acme.com）。返回 hostname、status: "pending" 和 cname_target。
2. 客户添加 DNS CNAME 记录：files.acme.com CNAME custom.fast.io（生产环境）或 custom.fastdev1.com（开发环境）。
3. 首次通过 CNAME 发起请求时，系统会通过 Let's Encrypt 自动配置 TLS 证书（2-5 秒）。域名状态将从 pending 变为 active。

查看状态： 使用 org 操作 custom-domain-get 并传入 org_id。该操作会返回域名信息；如果未配置自定义域名，则返回 { hostname: null }。

验证 DNS： 使用 org 操作 custom-domain-validate 并传入 org_id。该操作会执行实时 DNS 查询，并返回 CNAME 是否正确。如果验证通过且状态为待处理，系统会自动激活该域名。

移除： 使用 org 操作 custom-domain-delete 并传入 org_id。现有 TLS 证书会自然过期（最长 90 天）；流量不会立即受到影响。移除域名不受套餐限制——降级套餐的组织仍可移除其域名。

套餐要求： 创建自定义域名需要 Pro 或 Business 套餐。Agent 套餐不包含此功能。如果组织的套餐不支持自定义域名，创建操作会返回订阅升级错误。

组织发现（重要）

要发现所有可用的组织，Agent 必须调用这两个操作：

1. org 操作 list ——返回你作为直接成员的内部组织（member: true）
2. org 操作 discover-external ——返回你仅通过工作区成员身份访问的外部组织（member: false）

只检查 org 操作 list 的 Agent 会完全遗漏外部组织，也无法发现受邀加入的工作区。 人类邀请 Agent 协助特定项目时，最常见的做法就是邀请其加入工作区，而不是组织本身。

内部组织与外部组织

内部组织（member: true）——你创建的组织，或受邀以成员身份加入的组织。你拥有组织级访问权限：可以查看所有工作区（受权限限制），如果是管理员，还可以管理设置，并显示在组织的成员列表中。

外部组织（member: false）——你只能通过工作区成员身份访问的组织。你可以查看组织名称和基本公开信息，但不能管理组织设置、查看其他工作区，或在组织级别添加成员。你的访问权限仅限于明确邀请你加入的特定工作区。

示例： 人类邀请你的 Agent 加入其“Q4 Reports”工作区。你可以在该工作区上传文件、运行 AI 查询和协作。但你不能在其组织中创建新工作区、查看账单或访问其其他工作区。该组织会通过 org 操作 discover-external 显示，而不会出现在 org 操作 list 中。如果人类之后邀请你加入组织本身，该组织就会从外部组织变为内部组织。

工作区

工作区是组织内用于存储文件的容器。每个工作区都包含：

• 自己的一组成员及其角色（所有者、管理员、成员、访客）。成员的 status 为 active 或 pending。待处理成员是尚未注册的受邀用户——他们会立即显示在成员列表中，也可以被分配任务、审批事项和待办事项。在他们注册之前，通知会被暂缓发送。注册后，其状态会变为 active，所有分配都会保留。
• 包含文件和文件夹（存储节点）的存储树。
• 可选的、用于 RAG 对话的 AI 功能。
• 可在工作区内创建的共享。
• 归档/取消归档生命周期管理。
• 免费 Agent 方案包含 50 GB 存储空间，每次上传的文件最大为 1 GB。
• 文件版本管理——每次编辑都会创建新版本，并且可以恢复旧版本。
• 关键词和语义搜索——按名称或内容查找文件；启用智能功能后，还可以按含义搜索。

工作区通过 19 位数字的配置文件 ID 进行标识。

智能功能：开启或关闭

工作区提供 智能功能 开关，用于控制是否启用 AI 功能。

⚠️ 费用警告： 智能功能会产生高额的内容摄取费用（每个上传文档中的每页收取 10 个积分）。对于有数百或数千页内容的工作区，费用会迅速累积。除非用户明确需要 RAG 聊天查询或通过存储搜索进行语义搜索，否则请勿启用智能功能。 大多数工作流（文件存储、共享、协作、单次文件分析）无需智能功能也能正常运行。

智能功能关闭（推荐默认设置）——工作区仅用作文件存储。你仍然可以将文件直接附加到 AI 聊天对话中（最多 20 个文件，总计 200 MB）并就文件内容提问，无需支付内容摄取费用。对于大多数使用场景，这是合适的选择：文件存储、共享、协作、项目协调，以及分析少量指定文件。

智能功能开启（仅在需要时）——工作区将成为 AI 驱动的知识库。上传的每份文档和代码文件都会自动摄取、生成摘要并编入索引。仅当用户需要以下两种功能之一时才启用：

1. 跨多个文档进行 RAG 查询——将 AI 聊天的范围设为整个文件夹或整个工作区，并针对所有已编入索引的内容提问。AI 会检索相关段落并附上引用作答。当你有大量文档并需要跨文档搜索时，这一功能很有用。
2. 通过存储搜索进行语义搜索——按含义而非仅按关键词查找文件。使用 storage 操作 search，以语义方式查找文档。即使文件名中没有“赔偿条款”这些确切字词，“向我展示包含赔偿条款的合同”也能奏效。

智能功能还支持自动生成摘要和自动提取元数据，但仅凭这些功能不足以抵消内容摄取费用。

即将推出： 支持对图像、视频和音频文件进行 RAG 索引。目前仅对文档和代码编入索引。

默认行为： 创建工作区和共享内容时，MCP 服务默认关闭智能功能。若要启用智能功能，必须明确传入 intelligence: "true"。除非用户明确请求 RAG 聊天查询或通过存储搜索进行语义搜索，否则请勿启用智能功能。 请勿为了“以防万一”而臆测性地启用——之后随时可以启用，但内容摄取费用（每页 10 个积分）会立即产生且不予退还。

Agent 使用场景： 为每个项目或客户创建一个工作区。存储和协作时保持智能功能关闭。仅在用户需要查询大型文档集时启用。上传报告、数据集和交付成果。邀请其他 Agent 和人类利益相关者。一切都井然有序、可搜索且有版本记录。

有关 AI 聊天类型、文件上下文模式、AI 状态以及智能功能对这些内容的影响，请参阅下文的 AI Chat 部分。

共享内容

共享内容是专为与工作区外的人员交换文件而设计的空间。它们可以存在于工作区内，并分为三种类型：

模式	功能	Agent 使用场景
发送	接收者可以下载文件	交付报告、导出文件和生成的内容
接收	接收者可以上传文件	收集文档、数据集和用户提交内容
交换	双方都可以上传和下载	协作工作流、审核周期

门户

门户是从工作区文件夹（storage_mode=workspace_folder）创建的 Send 分享。门户始终为仅发送模式——接收者可以查看和下载文件，但不能上传。门户会显示关联工作区文件夹中的实时内容，因此文件夹的任何更改都会立即反映出来。门户非常适合对外发布文件夹内容（例如客户交付物文件夹），而无需复制文件。要创建门户：使用 share 操作 create，并设置 share_type: "send"、storage_mode: "workspace_folder" 和 folder_node_id（或 create_folder: true）。

分享功能

• 密码保护——访问链接时需要输入密码
• 过期日期——分享会在指定期限后自动过期
• 下载控制——三个安全级别：off（无限制，默认）、medium（访客可以内联预览文件，但不能下载）、high（禁止所有访客下载）。通过创建或更新时的 download_security 设置。
• 访问级别——仅成员、组织成员、注册用户或公开（任何拥有链接的人）
• 自定义品牌——背景图片、渐变颜色、强调色、徽标
• 下载后消息——下载后显示自定义消息和链接
• 每个分享最多 3 个自定义链接，用于提供背景信息或行动号召
• 匿名文件投递——允许访客无需注册即可向接收/交换分享上传文件（通过“任何人”访问权限启用 anonymous_uploads_enabled）
• 访客聊天——让分享接收者实时提问
• AI 驱动的自动命名——根据分享内容自动生成智能标题
• 活动通知——文件发送或接收时接收通知
• 评论控制——配置谁可以查看和发表评论（所有者、访客或双方）

两种存储模式

使用 share 操作 create 创建分享时，storage_mode 参数决定文件的存储方式：

• independent（独立存储，默认）——分享拥有独立的隔离存储空间。文件直接添加到分享中，与任何工作区都无关。这会创建一个自包含的分享——工作区文件的更改不会影响分享，反之亦然。适用于最终交付物、合规资料包、归档报告，或任何需要不可变快照的场景。

• workspace_folder（由工作区提供支持）——分享关联到工作区中的特定文件夹。分享会显示该文件夹中的实时内容——在工作区文件夹中添加、更新或删除的任何文件都会立即反映在分享中。无需复制文件，因此不会产生额外存储费用。要创建工作区文件夹分享，创建分享时传入 storage_mode=workspace_folder 和 folder_node_id={folder_opaque_id}。**注意：**工作区文件夹分享不允许设置过期日期，因为其内容是实时的。**注意：**工作区文件夹分享不支持智能功能——无论传入的值是什么，intelligence 始终设为 false。要对这些文件使用 AI 功能，请改用父工作区的 AI 端点。

两种模式对分享接收者的显示效果相同——均为带有品牌标识的分享页面，提供文件预览、下载控制和所有分享功能。区别在于内容是快照（独立存储）还是实时视图（工作区文件夹）。

**响应字段：**API 响应同时包含 storage_mode（independent 或 workspace_folder）和 share_category（portal 或 shared_folder）。创建分享时使用 storage_mode；share_category 是响应中的只读分类。

分享通过 19 位数字的配置文件 ID 进行标识。

**Agent 使用场景：**生成季度报告，创建带有客户品牌标识的 Send 分享，设置 30 天的过期时间，然后分享链接。客户会看到一个专业的品牌页面，并能即时预览文件，而不是一个原始下载链接。

存储节点

文件和文件夹以存储节点的形式表示。每个节点都有一个不透明 ID（由 30 个字母数字字符组成，并以连字符分隔显示，例如 f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4）。特殊值 root 表示工作区或共享内容的根文件夹，trash 表示回收站文件夹。

存储节点的主要操作包括：列出、创建文件夹、移动、复制、重命名、删除（移至回收站）、清除（永久删除）、恢复（从回收站还原）、搜索、添加文件（关联上传内容）和添加链接（创建共享引用）。

节点有版本。每次修改文件都会创建一个新版本。可以列出版本历史记录，也可以将文件还原到之前的版本。

覆盖文件（默认执行 REPLACE，并在原位置保留版本）

请勿删除并重新上传文件来“更新”文件。 将同名文件上传到同一父文件夹时，会就地覆盖现有节点，并保留 node_id。之前的内容会作为一个版本保留，随时可以恢复。先删除旧节点只会白费功夫，还会破坏其他实体（评论、任务、审批、元数据、链接）持有的 node_id 引用，并可能导致文件泄漏到回收站——修改文件内容绝不应该采用这种做法。

正确的文件更新方式：

1. 使用 upload 操作 create-session，传入与现有文件相同的 parent_node_id 和 filename（以及 profile_type、profile_id、filesize）。服务会将冲突解析为现有节点。
2. 使用新内容执行 POST /blob（见下文“上传”部分）。
3. 使用 blob_id 执行 upload 操作 chunk，然后执行 upload 操作 finalize（也可以在单次流式上传时使用 stream 模式）。
4. node_id 保持不变。之前的内容会成为一个版本条目。
5. 使用 storage 操作 version-list 查看历史记录（返回该节点的所有版本）。使用 storage 操作 version-restore 还原到任意较早版本。

通过 node_id 确定覆盖目标：如果文件名可能已变更（例如之前重命名过），或者你希望确保覆盖特定的 node_id，而不重新解析父文件夹，请在 create-session 中传入 target_node_id。这会明确指定更新目标——服务会使用 action=update 和 file_id=<target_node_id>；parent_node_id 将被忽略，filename 为可选项（省略则保留当前名称，传入新名称则在替换时重命名）。省略 filename 时，工具会额外执行一次 storage details 查询来获取当前名称（Fast.io API 在更新模式下仍要求提供 name）；如果想跳过这次调用，请明确传入 filename。请参阅下文“上传”部分的 target_node_id 文档。

完整示例——编辑文件内容并恢复之前的版本：

# Initial upload
upload create-session
  profile_type=workspace, profile_id=<ws_id>, parent_node_id=<folder_id>,
  filename="state.json", filesize=1024
POST /blob <bytes>
upload chunk upload_id=<id> chunk_number=1 blob_id=<blob>
upload finalize upload_id=<id>
# → new_file_id = f3jm5-zqzfx-...   (this is the stable node_id)

# Later, "edit" the file by re-uploading with the same name+parent
upload create-session
  profile_type=workspace, profile_id=<ws_id>, parent_node_id=<folder_id>,
  filename="state.json", filesize=2048
POST /blob <new_bytes>
upload chunk upload_id=<id2> chunk_number=1 blob_id=<blob2>
upload finalize upload_id=<id2>
# → new_file_id = f3jm5-zqzfx-...   (SAME node_id — overwritten in place)

# Inspect version history
storage version-list profile_type=workspace profile_id=<ws_id> node_id=f3jm5-zqzfx-...
# → [{version_id: v2, current: true}, {version_id: v1, ...}]

# Roll back if needed
storage version-restore profile_type=workspace profile_id=<ws_id>
  node_id=f3jm5-zqzfx-... version_id=v1

覆盖行为说明（所有名称冲突默认均执行 REPLACE）：

• 上传（addfile）——静默覆盖现有文件。之前的内容会作为版本条目保留，可通过 storage 操作 version-list / version-restore 恢复。节点 ID 保持不变。
• 移动 / 复制——将冲突的现有文件移至回收站，然后完成操作。可以从回收站恢复旧文件。
• 从回收站恢复——将冲突的现有文件移至回收站，然后执行恢复。
• 文件夹冲突和类型不匹配（文件与文件夹）仍会改用重命名方式处理（例如 folder (2)）。

上传与现有文件同名的文件会覆盖该文件，而不是创建类似 report (2).pdf 的重命名副本。如果确实需要多个同名文件共存，请在上传前重命名这些文件。

备注

备注是一种存储节点类型（与文件和文件夹并列），可在服务上直接存储 Markdown 内容。它们与文件处于相同的文件夹层级中，像其他节点一样支持版本管理，并会在存储列表中显示为 type: "note"。

创建和更新笔记

使用 workspace 操作 create-note 创建笔记，使用 workspace 操作 read-note 读取笔记，使用 workspace 操作 update-note 更新笔记。

文件和笔记不可互换，即使两者都包含 Markdown 也是如此。 通过文件上传流程上传的 .md 是一个文件（type: "file"），而不是笔记（type: "note"）。读取 Markdown 文件会返回文本，看起来“像”笔记，但笔记专用 API（update-note、read-note）会以 Node is not a note（错误 153548）拒绝它。请一开始就选择正确的创建方式：

• 如果你计划通过 Agent 增量编辑内容 → 使用 create-note。直接将 Markdown 作为 content 传入。不要先将其作为文件上传。
• 如果它是静态内容（报告、导出文件、附件）→ 使用上传流程。请注意，之后无法使用 update-note；如需更改内容，请调用 upload 操作 create-session，使用与现有文件相同的 parent_node_id 和相同的 filename，上传新版本，然后执行 chunk/finalize（或 stream）。同名上传会原位覆盖文件，并将之前的内容保留为一个版本（可通过 storage 操作 version-list / version-restore 恢复）。

如果 update-note 因 Node is not a note 而失败，该节点几乎总是一个文件。你有两种有效的恢复方式，请根据该节点之后应该如何使用来选择：

• (a) 保留为文件，只更改其字节内容 → 使用上文所述的上传流程（相同的 parent_node_id + filename = 原位覆盖并生成版本记录）。节点 ID 不会改变；该节点仍然是文件。
• (b) 转换为笔记（因为你之后想通过 update-note 增量编辑）→ 使用 storage 操作 delete 删除文件，然后在所需的 parent_id 中调用 create-note 并传入 Markdown 内容。这会创建一个新的 type: "note" 节点。之后使用新的 node_id 调用 update-note 进行编辑。

不要通过删除后重新上传（使用上传流程）来解决问题——那只会创建另一个文件，下一次调用 update-note 时仍会遇到相同的 Node is not a note 错误。调用前如需验证节点类型，请使用 storage 操作 details 并检查 type 字段（"file"、"note"、"folder" 或 "link"）。

**创建：**提供 workspace_id、parent_id（文件夹不透明 ID 或 "root"）、name（必须以 .md 结尾，最多 100 个字符），以及 content（内联 Markdown，最大 100 KB）或 blob_id（见下文）二者之一。

**读取：**提供 workspace_id 和 node_id。返回笔记的 Markdown 内容和元数据。

**更新：**提供 workspace_id、node_id，以及 name（必须以 .md 结尾）、content（最大 100 KB）或 blob_id 中的至少一项。如果同时传入 content 和 blob_id，调用会报错；请只提供其中一项。

通过 blob_id 传递笔记内容（大篇幅笔记的首选方式）

create-note 和 update-note 都接受可选的 blob_id，可替代内联 content：

blob_id：可选字符串。来自 POST /blob 响应的 Blob ID。建议用于大篇幅笔记内容，可避免 base64 开销和 MCP 传输限制。使用后即被消耗。字节会解码为 UTF-8，并作为笔记内容传入。（适用对象：create-note、update-note，作为 content/blob_id 之一）

为什么要这样做。 MCP 会通过 JSON-RPC 管道，以内联 JSON 字符串的形式传输工具参数。通过 content 参数发送超过几 KB 的笔记内容会明显变慢——完整字符串必须序列化到工具调用中，通过传输通道，再由服务端解析。POST /blob 辅助接口是独立的原始 HTTP 通道，完全绕过 MCP 传输：你可以直接 POST 原始字节（最多 100 MB、仅可使用一次、TTL 为 5 分钟），获取 blob_id，再将其传给工具。服务端会读取 Blob，将其解码为 UTF-8、清理内容，并将其用作笔记内容。此模式与 upload 操作的 chunk/stream 相同。

如何选择：

笔记大小	建议方式
小幅编辑（< ~10 KB——几段文字、项目符号、小节）	内联 content
大篇幅笔记（> ~10 KB——丰富的项目背景、文字记录、较长的 Markdown 文档）	POST /blob → blob_id

每个节点的笔记上限为 100 KB。写入内容达到或超过 80 KB 时，会在 _warnings 中（或通过 create-note 上的 withHints）返回非致命警告，建议在达到上限前进行滚动归档。此警告仅供参考，写入仍会成功。一种常见的滚动归档方式是创建带日期的归档文件：当笔记增长到约 80 KB 时，创建一个名为 archive-2026-04-14.md 或 notes-2026-W15.md 之类的新笔记，将较早的内容移入其中，并保持“当前”笔记简短。

限制项	上限
内容编码	有效的 UTF-8（UTF8MB4）。无效字节序列和控制字符（\\p{C}，\\t、\\n、\\r 除外）会被剔除。
内容大小	最多 100 KB
文件名	1-100 个字符，必须以 .md 结尾
Markdown 验证	代码块和强调标记必须成对匹配
速率限制	每 10 秒 2 次，每 60 秒 5 次

将笔记用作长期知识依据

在智能工作区中，笔记会像上传的文档一样自动摄取并建立索引。因此，笔记可以用来长期积累知识——存储在笔记中的事实、背景或决策，都会成为未来 AI 查询的依据。

当 AI 聊天使用文件夹范围（或默认使用整个工作区）时，系统会与文件一起搜索该范围内的笔记。AI 会从笔记中检索相关段落，并在回答中引用。

主要行为：

• 启用工作区智能功能后，笔记会被摄取以用于 RAG
• 文件夹范围内的笔记会纳入范围限定的查询
• ai_state: indexed 的笔记可通过 RAG 搜索
• 也可以通过 files_attach 将笔记直接附加到聊天中（请检查存储详情中的 ai.attach 是否为 true）

使用场景：

• 存储项目背景、决策和理由。几个月后，询问“我们为什么选择供应商 X？”，AI 就会检索到这篇笔记。
• 将研究发现保存在笔记中。未来的 AI 聊天会自动将这些发现用作依据。
• 创建参考文档（风格指南、命名规范），为工作区中今后的所有 AI 查询提供参考。

其他笔记操作

笔记支持与文件和文件夹相同的存储操作：移动（通过 storage 操作 move）、复制（storage 操作 copy）、删除/移至回收站（storage 操作 delete）、恢复（storage 操作 restore）、版本历史（storage 操作 version-list）和详情（storage 操作 details）。

将用户链接到笔记

• 工作区上下文中的笔记（打开包含笔记面板的工作区）：https://{domain}.fast.io/workspace/{folder_name}/storage/root?note={note_id}
• 笔记预览（独立视图）：https://{domain}.fast.io/workspace/{folder_name}/preview/{note_id}

AI 聊天

AI 聊天可让 Agent 就工作区和共享内容中存储的文件提问。提供两种聊天类型，各自的文件上下文选项不同。

AI 聊天是只读的。 它可以读取、分析和搜索文件内容，并回答相关问题，但无法修改文件、更改工作区设置、管理成员或访问事件。任何超出读取文件内容范围的操作——上传、删除、移动文件、更改设置、管理共享内容、读取事件——都必须直接通过 MCP 工具完成。不要尝试将 AI 聊天用作通用的工作区管理工具。

两种聊天类型

• chat — 不包含工作区索引中文件上下文的基础 AI 对话。仅用于一般问题。
• chat_with_files — 基于你的文件提供回答的 AI。提供文件上下文的两种模式互斥：

自动升级： 如果你创建聊天时设置了 type=chat，但同时包含 files_scope、folders_scope 或 files_attach，系统会自动将类型升级为 chat_with_files。你无需担心类型是否设置正确——只要存在文件参数，意图就很明确。

• 文件夹/文件范围（RAG） — 限制检索搜索范围。需要启用智能功能；文件的 AI 状态必须为 indexed。
• 文件附件 — 由 AI 直接读取的文件。无需智能功能；存储详情中必须包含 ai.attach: true（文件必须是 AI 分析支持的类型）。最多 20 个文件，总大小为 200 MB。

两种类型都会在相关时结合网络知识来补充回答。

文件上下文：范围与附件

对于 chat_with_files，请选择以下两种互斥方式之一：

功能	文件夹/文件范围（RAG）	文件附件
工作方式	限定 RAG 搜索范围	AI 直接读取文件
是否需要智能功能	是	否
文件就绪条件	ai_state: indexed	ai.attach: true
适用于	大量文件、知识检索	特定文件、直接分析
最大引用数	100 个文件夹引用（展开子文件夹树）或 100 个文件引用	20 个文件 / 200 MB
默认值（未指定范围）	整个工作区	不适用

范围参数（需要智能功能——如果智能功能已关闭，将报错）：

• folders_scope — 逗号分隔的 nodeId:depth 键值对（深度 1-10，最多 100 个子文件夹引用）。用于定义搜索边界——RAG 后端会自动在指定文件夹中查找文档。只需传入文件夹 ID 和深度；不要枚举单个文件。包含数千个文件、但子文件夹较少的文件夹也能正常使用。
• files_scope — 逗号分隔的 nodeId:versionId 键值对（最多 100 个）。将 RAG 搜索范围限制为指定的已索引文件。nodeId 为必填项；键值对格式要求填写 versionId，但如果留空（例如 nodeId:，冒号后不填内容），将自动解析为该节点的当前版本。可从 storage 操作的 list 或 details 响应中，文件的 version 字段获取 versionId。
• 如果两者都未指定，默认范围为整个工作区（所有已索引文档）。 这是建议的默认设置——除非确实需要缩小搜索范围，否则请省略范围参数。

附件参数（不需要智能功能）：

• files_attach — 逗号分隔的 nodeId:versionId 键值对（最多 20 个文件，总计 200 MB）。nodeId 为必填项；如果留空 versionId，将自动解析为当前版本。文件会被直接读取，而非通过 RAG 读取。仅限文件：传入文件夹 nodeId 会返回 406 错误。 若要将文件夹内容纳入 AI 上下文，请改用 folders_scope（需要智能功能）。只有 storage 详情中 ai.attach: true 的文件才能作为附件——使用前请先检查。

不要在要搜索整个文件夹时，列出文件夹内容并将单个文件 ID 作为 files_scope 传入——请改用该文件夹的 nodeId 配合 folders_scope。files_scope 仅用于指定已知文件的特定版本。

范围与附件： files_scope 和 folders_scope 用于缩小 RAG 搜索边界，且要求启用工作区智能功能——在非智能工作区中使用会报错。files_attach 会将文件直接发送给 AI，不进行索引，无论智能功能设置如何都可使用，但仅接受文件 nodeId（不接受文件夹）。

files_scope/folders_scope 与 files_attach 互斥——同时传入两者会报错。

智能功能与 AI 状态

工作区智能功能开关（见上文“工作区”）用于控制是否自动摄取、摘要并为 RAG 索引已上传的文档和代码文件。每个文件都有一个 ai_state，用于表示其就绪状态：

状态	含义
disabled	未进行 AI 处理（文件类型不受支持，或 AI 已完全关闭）
pending	已加入 AI 处理队列
in_progress	正在处理
ready	已生成摘要，文件可附加到 AI 聊天，但未进行向量索引（智能功能关闭）
indexed	已生成摘要并完成向量索引 — 文件可通过 RAG/语义搜索检索（智能功能开启）
failed	处理失败

只有 ai_state: indexed 的文件才会纳入文件夹/文件范围（RAG）搜索。ai_state: ready 或 indexed 的文件都可以附加到 AI 聊天 — 请检查 ai.attach 字段。通过 storage 操作 details 并设置 profile_type: "workspace"，即可查看文件状态。

轮询 AI 处理是否完成时：如果智能功能已开启，请等待状态变为 indexed；如果智能功能已关闭（但启用了 AI 摘要），请等待状态变为 ready。检查工作区的 capabilities.can_use_intelligence，以确定预期的最终状态。

可附加性 — ai.attach 标志

存储列表/详情响应中的文件节点包含一个 ai 对象，其中有三个字段：

字段	类型	含义
ai.state	string	AI 处理状态（disabled、pending、inprogress、ready、indexed、failed）
ai.attach	boolean	文件是否可通过 files_attach 使用
ai.summary	boolean	文件是否已有 AI 生成的摘要

使用 files_attach 前，请检查 ai.attach 是否为 true。 当文件类型支持 AI 分析（文档、代码、图像、PDF、电子表格等），或文件已通过此前的处理生成摘要时，文件即可附加。ai.attach: false 的文件（格式不受支持、文件损坏或仍在处理中）会被 API 拒绝。

此标志独立于工作区的智能功能设置 — 即使智能功能关闭，文件的 ai.attach 也可以为 true。

何时启用智能功能： 你需要针对大量文档（限定在特定文件夹或整个工作区内）进行 RAG 聊天查询，或通过 storage 操作 search 进行语义搜索。不要仅为了自动生成摘要或提取元数据而启用智能功能 -- 摄取成本（每页 10 个积分）相当高。

何时禁用智能功能（建议的默认设置）： 工作区用于存储、共享、协作，或你只需通过附件分析特定文件。这涵盖了大多数使用场景，并能节省大量积分。如有需要，随时可以启用智能功能。

即使智能功能关闭，对于 ai.attach: true 的文件，使用文件附件调用 chat_with_files 仍然有效。

如何组织问题表述

指定文件夹/文件范围（RAG）： 编写可能与已索引文件内容匹配的问题。AI 会搜索指定范围、检索段落并引用出处。

• 好："供应商合同中的付款条款是什么？"
• 好："总结 Q3 分析报告的主要发现"
• 不好："告诉我这些文件的情况"——过于笼统，没有可匹配的具体内容
• 不好："这个工作区里有什么？"——无法有意义地搜索“所有内容”

附加文件： 直接提问——AI 会读取文件的完整内容。无需检索步骤。

• "详细描述这张图片"
• "提取这张发票中的所有日期和金额"
• "将此 CSV 数据转换为摘要表格"

个性风格： personality 参数用于控制 AI 回复的语气和长度。创建聊天或发送消息时传入该参数：

• concise — 简短回答
• detailed — 提供上下文和依据的全面回答（默认值）

需要快速获取事实、回答是非问题或简短摘要时，使用 concise。需要有支持依据和引用的深入分析时，使用 detailed（或省略该参数）。也可以针对每条后续消息覆盖个性风格。

在问题中控制详略程度： 也可以通过问题的表述方式来引导回复详略程度：

• "用一句话概括这份报告的主要结论是什么？"
• "只列出提及 GDPR 合规性的文件名，不要解释"
• "给我一份简短摘要——最多列出 2-3 个要点"

将 personality: "concise" 与直接的问题结合使用，可以获得最简短的回答，并尽量减少 AI 点数消耗。

聊天参数

使用 ai 操作 chat-create 创建聊天（配合 profile_type: "workspace"），或使用 ai 操作 chat-create（配合 profile_type: "share"）：

• type（必填）— chat 或 chat_with_files
• query_text（workspace 必填，share 可选）— 初始消息，长度为 2-12,768 个字符
• personality（可选）— concise 或 detailed（默认值：detailed）
• privacy（可选）— private 或 public（默认值：public）
• files_scope（可选）— nodeId:versionId,...（最多 100 个，要求使用 chat_with_files + intelligence）。必须提供 nodeId；如果 versionId 为空，则自动解析。省略此参数可搜索所有已索引文档（推荐默认设置）。
• folders_scope（可选）— nodeId:depth,...（depth 为 1-10，最多 100 个子文件夹引用，要求使用 chat_with_files + intelligence）。文件夹范围用于限定搜索边界，而非枚举文件。省略此参数可搜索所有已索引文档（推荐默认设置）。
• files_attach（可选）— nodeId:versionId,...（最多 20 个 / 200 MB，必须提供 nodeId；如果 versionId 为空，则自动解析；不能与范围参数同时使用）

后续消息

使用 ai 操作 message-send 发送后续消息（配合 profile_type: "workspace" 或 "share"）。聊天类型继承自父聊天。每条后续消息都可以更新范围、附件和个性风格参数。

等待 AI 回复

创建聊天或发送消息后，AI 回复会异步生成。消息状态依次为：ready → in_progress → complete（或 errored）。

推荐做法： 使用返回的 message_id，调用 ai 操作 message-read（配合 profile_type: "workspace" 或 "share"）。工具会自动轮询（最多 15 次，每次间隔 2 秒，约 30 秒）。如果在此时间内回复仍在处理中，请改用 event 操作 activity-poll，并传入 workspace/share ID，而不要循环调用读取操作——请参见第 7 节中的 Activity Polling。

回复引用

已完成的 AI 回复会附带指向源文件的引用：

• nodeId — 存储节点的不透明 ID
• versionId — 文件版本的不透明 ID
• entries[].page — 页码
• entries[].snippet — 文本摘录
• entries[].timestamp — 音频/视频时间戳

将用户链接到 AI 聊天

在工作区存储 URL 后追加 ?chat={chat_opaque_id}：

https://{domain}.fast.io/workspace/{folder_name}/storage/root?chat={chat_id}

分享 AI 聊天

分享功能支持具备相同能力的 AI 聊天。所有工作区 AI 端点都有对应的分享版本，可通过 ai 操作并设置 profile_type: "share" 访问。

AI 分享 / 导出

为文件生成临时的 Markdown 格式下载 URL，以便粘贴到外部 AI 工具（ChatGPT、Claude 等）中。使用 ai 操作 share-generate（并设置 profile_type: "workspace" 或 "share"）。URL 会在 5 分钟后过期。限制：最多 25 个文件，每个文件不超过 50 MB，总计不超过 100 MB。

Profile ID

组织、工作区和分享均由 19 位数字的 profile ID 标识。这些 ID 会出现在工具参数中，如 workspace_id、share_id、org_id、profile_id 和 member_id。

大多数端点也接受自定义名称作为标识符：

Profile 类型	数字 ID	自定义名称
工作区	19 位 ID	文件夹名称（例如，my-project）
分享	19 位 ID	URL 名称（例如，q4-financials）
组织	19 位 ID	域名（例如，acme）
用户	19 位 ID	电子邮件地址（例如，[email protected]）

QuickShares

QuickShares 是工作区中单个文件的临时公开下载链接（分享不可用）。无需身份验证即可访问。链接会在创建后指定的秒数过期（默认值为 10,800 = 3 小时，最大值为 604,800 = 7 天），也可以通过 expires_at 设置为 ISO 8601 日期时间。文件大小上限：1 GB。每个 quickshare 都有一个不透明标识符，可用于获取元数据和下载文件。

文件预览

上传到 Fast.io 的文件会自动生成预览。用户打开分享或工作区时，可以立即看到内容——无需再“下载后用其他应用打开”。

支持的预览格式：

• 图像——全分辨率显示，支持自动旋转和缩放
• 视频——HLS 自适应流媒体（比原始视频加载快 50--60%）
• 音频——交互式波形可视化
• PDF——页面导航、缩放、文本选择
• 电子表格——网格导航，支持多个工作表
• 代码和文本——语法高亮、Markdown 渲染

使用 storage 操作 preview-url（并设置 profile_type: "workspace" 或 "share"）生成预览 URL。使用 storage 操作 preview-transform（并设置 profile_type: "workspace" 或 "share"）进行图像缩放、裁剪和格式转换。

Agent 使用场景： 生成的 PDF 报告不只是一个下载链接。用户可以直接在页面中查看渲染后的报告、翻阅页面、放大查看并针对特定部分发表评论——全程无需离开浏览器。

评论和批注

用户和 Agent 可以直接在文件上留下反馈，并使用 reference 参数将评论锚定到特定内容：

• 图像评论——锚定到空间区域（归一化的 x/y/宽度/高度坐标）
• 视频评论——锚定到时间戳，并选择空间区域
• 音频评论——锚定到时间戳或时间范围
• PDF 评论——锚定到特定页面，可选择文本片段
• 文本锚定评论——使用 exact、prefix、suffix、start_offset 和 end_offset 字段锚定到 Markdown/笔记中选中的文本（使用 type: "document" 或 type: "text"）
• 串接回复——仅支持单层串接；对回复的回复会自动合并到父级评论
• 表情反应——每位用户对每条评论只能添加一个反应；添加新反应会替换之前的反应
• 提及标签——使用方括号语法在行内引用用户和文件：@[profile:id]、@[user:opaqueId:Display Name]、@[file:fileId:filename.ext]。可从成员列表、用户详情或存储列表中获取 ID。profile 标签中的显示名称部分可选，但建议在用户和文件标签中填写 评论使用 JSON 请求正文（Content-Type: application/json），而大多数其他端点使用表单编码数据。

列出评论： 对单个文件的评论使用 comment 操作 list，对工作区或共享内容中的所有评论使用 comment 操作 list-all。两者均支持 sort、limit（2-200）、offset、include_deleted、reference_type 筛选器和 include_total。

添加评论： 使用 comment 操作 add，并提供 profile_type、profile_id、node_id 和 text。可选提供 parent_comment_id 以回复评论，并提供 reference 以锚定到特定位置。正文支持提及标签。字符数限制有两项：包含标签在内的正文总长度最多为 8,192 个字符；显示文本（去除 @[...] 标签后的正文）最多为 500 个字符。还可选择提供 linked_entity_type 和 linked_entity_id，在创建时将评论关联到任务或审批。

删除评论： comment 操作 delete 会递归删除——删除父评论也会删除所有回复。comment 操作 bulk-delete 不会递归删除——被删除评论的回复会保留。

关联评论： 评论可以关联到工作流实体（任务或审批）。每条评论一次只能关联一个实体（也可以不关联）。使用 comment 操作 link 将现有评论关联到任务或审批，使用 comment 操作 unlink 移除关联，使用 comment 操作 linked 反向查找关联到指定实体的所有评论。创建评论时，也可以向 add 操作传入 linked_entity_type 和 linked_entity_id 来建立关联。评论响应包含 linked_entity_type 和 linked_entity_id 字段（未关联时为 null）。

将用户链接到评论： 预览 URL 会自动打开评论侧边栏。深层链接查询参数可用于定位特定评论或位置：

参数	格式	用途
?comment={id}	评论不透明 ID	滚动到指定评论并高亮显示 2 秒
?t={seconds}	例如 ?t=45.5	跳转到时间戳位置，适用于音频/视频评论
?p={pageNum}	例如 ?p=3	跳转到页面，适用于 PDF 评论

工作区：https://{org.domain}.fast.io/workspace/{folder_name}/preview/{file_opaque_id}?comment={comment_id}

共享内容：https://go.fast.io/shared/{custom_name}/{title-slug}/preview/{file_opaque_id}?comment={comment_id}

参数可以组合使用——例如，使用 ?comment={id}&t=45.5 深层链接到视频中特定时间戳处的评论。在共享内容中，只有启用了评论功能时才会打开评论侧边栏。

Agent 使用场景： 你生成了一张设计模型图。用户在图像的特定区域评论“更改页眉颜色”。你读取评论，通过 reference.region 坐标准确了解对方指的是哪个区域，然后重新生成。

文本锚定评论（Markdown/笔记）： 要将评论锚定到 Markdown 或笔记文件中的特定文本，请使用 reference 参数，并设置 type: "document"（或 "text"，两者等效），以及以下文本选区字段：

• exact（字符串，最多 500 个字符）——选中的原文
• prefix（字符串，最多 100 个字符）——选区之前约 30-50 个字符的上下文，用于消除歧义
• suffix（字符串，最多 100 个字符）——选区之后约 30-50 个字符的上下文，用于消除歧义
• start_offset（整数）——从文档开头起算的字符偏移量（用于解析歧义匹配的提示）
• end_offset（整数）——选区结束处的字符偏移量（用于解析歧义匹配的提示）

至少需要提供 exact。当相同文本出现多次时，prefix/suffix 字段有助于定位选区。start_offset/end_offset 字段是可选提示，编辑文档后可能不再适用。

示例——在 Markdown 文件中添加文本锚定评论：

{
  "action": "add",
  "profile_type": "workspace",
  "profile_id": "1234567890123456789",
  "node_id": "abc123-def456-ghi789",
  "text": "This section needs a citation",
  "reference": {
    "type": "document",
    "exact": "Studies show a 40% improvement",
    "prefix": "In the results section, ",
    "suffix": " compared to the baseline.",
    "start_offset": 1250,
    "end_offset": 1280
  }
}

URL 导入

Agent 可以直接从 URL 导入文件，无需先下载到本地。Fast.io 的服务器会获取文件、处理文件，并将其添加到工作区或共享空间。

• 支持任意 HTTP/HTTPS URL
• 支持受 OAuth 保护的来源：Google Drive、OneDrive、Dropbox
• 文件会经过相同的处理流程（生成预览、在启用智能功能时进行 AI 索引、病毒扫描）

使用 upload 操作 web-import，并提供源 URL、目标配置文件和父节点 ID。使用 upload 操作 web-status 查看进度，使用 upload 操作 web-list 列出正在进行的导入任务。

Agent 使用场景： 用户说“把这份 Google Doc 添加到项目中。”你调用 upload 操作 web-import 并提供 URL。Fast.io 会在服务器端下载文件、生成预览、为 AI 建立索引，然后文件就会出现在工作区中。无需本地 I/O。

元数据

元数据支持对工作区中的文件进行结构化数据标注。系统采用基于模板的方式（在 UI 中称为“视图”）：管理员创建模板来定义字段（名称、类型、约束），然后将模板分配给工作区。随后可以根据模板字段为文件设置元数据值。

要点：

• 所有套餐均可使用——元数据模板不再仅限 Pro/Business 套餐。Free 和 Agent 用户也可以创建首个模板。

• 各套餐设有上限——每种套餐都会限制工作区可拥有的模板数量，以及每个模板可容纳的文件（节点）数量：

  套餐	每个工作区的模板数	每个模板的节点数
  Agent	1	10
  Free	1	10
  Pro	2	10
  Business	10	1,000
  上限适用于自动匹配、手动添加和列表查询。降级时，超出上限的行会保留在存储中，但不会在列表中显示。

• metadata-template-preview-match 上的截断提示——响应包含 plan_node_limit（-1 = 无上限）和 would_truncate_at（适用上限时 = min(total_matched, plan_node_limit)，否则 = total_matched）。文档建议的前端判断方式：当 would_truncate_at < total_matched 时向用户发出警告——套餐上限正在截断采样匹配数量。MCP 的 metadata-template-preview-match 处理程序会自动在 _warnings 中发出此警告。在 UI 中将 plan_node_limit = -1 视为“无上限”。

• metadata-template-list 和 metadata-template-details 上的截断提示——实时 AI 类别概览指出：“列表、详情和预览端点会返回 plan_node_limit、is_truncated 和未筛选计数，以及受上限约束的可见计数，供调用方显示升级提示。”实时参考文档中的当前响应示例并未明确展示这些字段，因此请在运行时确认确切字段名称。每模板 nodes/ 列表端点上的未筛选计数字段名为 total_count_unfiltered；文档未明确规定 list/details 上的字段名称，名称可能不同。只要任一端点上的 is_truncated 为 true，就显示升级提示。

• metadata-template-suggest-fields 并发——服务会限制每位用户和每个工作区的并发调用；若另一个 suggest-fields 调用正在进行，则返回 409 Conflict。等待几秒后重试。（较早的内部说明误称为 406；以实时文档为准，正确状态码是 409。）

• nodes/add/ 超出上限（REST 端点，未作为 MCP 操作公开）——返回 400（Fast.io 错误代码 1605，“Invalid Input”），并附带结构化的“将超出上限”消息。并发调用不能共同超出上限。若要预先检查，请读取每模板的 nodes 列表端点，并使用 plan_node_limit - total_count_unfiltered 计算剩余名额。

• 自动匹配会静默执行上限——服务端的 auto-match 端点（目前未作为 MCP 操作公开）会受 plan_node_limit 限制，即使还有更多文件可匹配也一样（以节省额度和 LLM 成本）。由于 MCP 工具目前既不支持调用 auto-match，也不支持调用每模板的 nodes/ 列表，因此需要准确了解自动匹配后映射了多少文件的 Agent，必须直接调用这些 REST 端点，或向用户说明这一限制。

• MCP 工具覆盖范围——workspace MCP 工具支持模板 CRUD（metadata-template-{create,delete,list,details,update,clone}）、工作区分配（metadata-template-{assign,unassign,resolve,assignments}）、视图创建流程（metadata-template-{preview-match,suggest-fields}）、每位用户保存的视图（metadata-view-{get,save,delete}、metadata-views-list）、已保存视图的 TSV 导出（metadata-view-export）、跨元数据值的关键词搜索（metadata-search）以及文件级元数据（metadata-{get,set,delete,extract}、metadata-list-files、metadata-list-templates-in-use、metadata-versions）。目前不支持 nodes/add、nodes/remove、每模板的 nodes/ 列表、auto-match、extract-all 或 /metadata/eligible/。需要这些工作流的 Agent 必须向用户说明这一限制。

• 模板类别——legal、financial、business、medical、technical、engineering、insurance、educational、multimedia、hr。

• 字段类型——string、int、float、bool、json、url、datetime——每种类型均可选择添加约束（min、max、default、fixed_list、can_be_null）。

• 两种元数据类型——模板元数据遵循模板字段定义；自定义元数据是与任何模板无关的自由格式键值对。

• 系统模板——预置模板；分配给工作区时会自动克隆，因此自定义内容不会影响全局定义。

• AI 提取——extract 操作使用 AI 分析文件内容并自动填充元数据字段。提取出的值会标记为 is_auto: true。此操作会消耗 AI 额度。

• 版本历史——元数据变更会通过版本快照进行跟踪，可通过 versions 操作访问。

• 模板 ID 是以 mt_ 为前缀的字母数字字符串（例如 mt_abc123def456）。

所有权转移

Agent 交付价值的主要方式：构建某样东西，然后交给人类。Agent 计划的额度用尽、API 调用开始返回 402 Payment Required 时，也建议执行此操作——将组织转交给能够升级到付费计划的人类。

重要：账户类型限制。 转移／认领流程（org 操作 transfer-token-create、transfer-token-list、transfer-token-delete、transfer-claim）仅在 Agent 创建了 Agent 账户（通过 auth 操作 signup），且该 Agent 账户拥有该组织时才可用。如果 Agent 使用 人类账户（通过 auth 操作 signin）登录，则无法使用转移／认领 API。人类拥有的组织必须由人类直接通过 Fast.io 控制台升级。

流程：

1. Agent 通过 auth 操作 signup 创建 Agent 账户，并通过 org 操作 create 创建组织；然后通过 org 操作 create-workspace 设置工作区、上传文件并配置共享
2. Agent 通过 org 操作 transfer-token-create 生成转移令牌（有效期为 72 小时）
3. Agent 将认领 URL 发送给人类：https://go.fast.io/claim?token=<token>
4. 人类点击链接并使用自己的账户认领该组织

转移时机：

• 组织已准备好供人类使用（工作区已配置、文件已上传、共享已设置）
• Agent 计划额度用尽（402 Payment Required）——转移组织，让人类可以升级
• 人类明确要求接管该组织

管理转移令牌：

• org 操作 transfer-token-list——创建新令牌前，检查是否已有待处理的令牌
• org 操作 transfer-token-delete——如果不再需要转移，则撤销令牌
• org 操作 transfer-claim——使用令牌认领组织（由接收方的人类的 Agent 使用）

转移后会发生什么：

• 人类成为该组织及其所有工作区的所有者
• Agent 保留管理员访问权限（仍可管理文件和共享）
• 人类获得免费计划（基于额度，不设试用期）
• 人类可随时升级到 Pro 或 Business

Agent 使用场景： 用户说“为我的团队设置一个项目工作区。”你创建组织，搭建工作区结构，上传模板，为客户交付内容配置共享，邀请团队成员——然后转移所有权。人类接手时，平台已完成配置。你保留管理员身份，继续管理相关事务。

402 Payment Required 使用场景（Agent 账户）： 工作过程中，Agent 达到额度上限。调用 org 操作 transfer-token-create，将认领 URL 发送给人类，并说明他们可以升级以继续使用。Agent 保留管理员访问权限，并在人类升级后继续工作。

402 Payment Required 使用场景（人类账户）： Agent 无法转移组织。请告知用户其组织额度已用尽，需要升级计费计划。引导他们前往 Fast.io 控制台，或使用 org 操作 billing-create 升级到付费计划。

工作流（任务、工作日志、审批、待办事项）

工作区和共享支持可选的工作流层，可添加结构化任务管理、活动日志、审批关卡和简单清单。工作流功能由开关控制——使用前必须明确启用。对于共享，只有管理员或指定成员角色才能访问工作流；访客和仅查看用户无法使用工作流功能。

启用工作流

• **工作区：**使用 workspace 操作 enable-workflow 和 workspace_id
• **共享：**使用 share 操作 enable-workflow 和 share_id

通过 workspace 操作 details 或 share 操作 details 检查工作流是否已启用——查看响应中的 workflow: true。

禁用工作流（workspace 操作 disable-workflow 或 share 操作 disable-workflow）会使所有工作流数据无法访问，但会保留这些数据。重新启用后即可恢复访问。

任务列表和任务

任务按列表组织。每个工作区或共享空间可以有多个任务列表，每个列表包含各个任务。

• 任务列表有名称和可选的描述。使用 task 操作 create-list 创建，使用 task 操作 list-lists 列出。
• 任务包含标题、描述、状态、优先级、负责人、依赖项和可选的节点链接。使用 task 操作 create-task 创建，使用 task 操作 list-tasks 列出。
• 状态： pending、in_progress、complete、blocked
• 优先级： 0 = 无，1 = 低，2 = 中，3 = 高，4 = 关键
• 负责人是个人资料 ID（工作区或共享空间成员，包括待加入成员）。使用 task 操作 assign-task 指派或取消指派。可以将任务指派给待加入成员（已邀请但尚未注册）；其指派关系会在他们注册后保留。
• 批量操作： task 操作 bulk-status 可一次更改最多 100 个任务的状态。
• 移动任务： task 操作 move-task 可在同一个人资料内将任务从一个列表移至另一个列表。需要提供源 list_id、task_id 和 target_task_list_id。可选设置 sort_order，以控制任务在目标列表中的位置（默认值：0）。
• 重新排序： task 操作 reorder-tasks 可设置列表内任务的显示顺序。task 操作 reorder-lists 可设置个人资料内任务列表的显示顺序。按所需顺序传入 ID 数组；服务会将其转换为 {id, sort_order} 对象，以供 API 使用。
• 创建者跟踪： 任务和任务列表包含 created_by 字段（创建者的个人资料 ID）。
• 筛选列表： task 操作 filtered-list 按类别筛选并返回任务——“assigned”（指派给我）、“created”（我创建的）或“status”（按状态筛选，需提供 status 参数）。范围限定为某个工作区或共享空间。
• 摘要： task 操作 summary 返回精简的计数信息——任务总数、按状态分类的数量、指派给我的任务数和我创建的任务数。
• Markdown 输出： 传入 format: "md"，即可获取易于阅读的 Markdown，而非 JSON。

工作日志

工作日志是按时间顺序追加的活动日志，范围可限定为任务、任务列表、存储节点或个人资料。条目创建后无法编辑或删除。

• 条目： 使用 worklog 操作 append 追加常规日志条目。可用于记录进度更新、决策、推理和状态变更。
• 紧急提醒： 使用 worklog 操作 interject 创建优先级更正。紧急提醒始终为紧急状态，且需要其他参与者确认。
• 确认： worklog 操作 acknowledge 可将紧急提醒标记为已读。worklog 操作 unacknowledged 会列出仍需确认的紧急提醒。条目包含布尔值 acknowledgable——当其为 true 时，表示该条目是尚未确认且可确认的紧急提醒。
• 响应字段： 条目包含 acknowledged（布尔值）、acknowledgable（布尔值）、updated（YYYY-MM-DD HH:MM:SS UTC 时间戳）和 created（YYYY-MM-DD HH:MM:SS UTC 时间戳）。
• 个人资料级列表： worklog 操作 profile-list 会列出工作区或共享空间级别的所有工作日志条目（与按实体限定范围的 list 不同）。
• 筛选列表： worklog 操作 filtered-list 按类别筛选并返回工作日志——“authored”（我撰写的工作日志）或 “interjections”（针对我的紧急提醒）。可选的 type 子筛选项为 “info” 或 “interjection”。
• 摘要： worklog 操作 summary 返回精简的计数信息——条目总数、按条目类型分类的数量、我撰写的条目数和待处理的紧急提醒数。
• Markdown 输出： 传入 format: "md" 可获取易于阅读的输出。

评论与讨论 -- 快速入门

适用场景： 对文件留下反馈、发起容器级讨论，或为工作流审批/任务添加备注。

评论使用 JSON -- 始终使用 JSON 请求正文（Content-Type: application/json）。这是评论 API 返回 406 错误的首要原因。

三种关联模式 -- 调用前请选择一种：

1. 关联到节点（针对特定文件/文件夹的讨论串）：

• 使用 comment 操作 add，并提供 profile_type、profile_id、node_id、text（以及可选的用于锚定的 reference、用于回复的 parent_comment_id）。
• 对应 POST /comments/{entity_type}/{parent_id}/{node_id}/。使用 list 操作列出。

2. 关联到工作区/共享项（顶级容器讨论串）：

• comment 操作 add 不支持此模式（该操作要求提供 node_id）。对于容器级评论，请通过 execute 调用底层端点：POST /comments/{entity_type}/{parent_id}/，并使用 JSON 正文 {body, parent_id?}。使用 comment 操作 list-all 列出。

3. 关联到工作流（将现有评论关联到审批或任务）：

• 步骤 A：通过模式 1 或 2 创建评论。
• 步骤 B：使用 comment 操作 link，并提供 comment_id、linked_entity_type: "task" | "approval"、linked_entity_id。
• 使用 comment 操作 linked 反向查找。使用 comment 操作 unlink 解除关联。评论在同一时间最多只能关联一个工作流对象。

有效的 entity_type / profile_type 值：

• 创建/列出端点：仅限 "workspace" 或 "share"。
• 关联/解除关联/反向查找端点：仅限 "task" 或 "approval"（不包括 worklog_entry、node 或 share）。

讨论串： 仅支持单层。将 parent_comment_id（正文中的字段：parent_id）设为顶级评论 ID。对回复的回复会自动展平为同级回复。

表情回应： 使用 comment 操作 reaction-add，并提供 comment_id + emoji。每位用户对每条评论只能添加一个回应 -- 新回应会替换之前的回应。

反模式：

• 不要向创建端点传递 entity_type: "approval"（或 "task"）-- 它们只接受 "workspace" 或 "share"。要评论审批，请先在父级工作区/共享项上创建评论，然后再进行关联。
• 不要手动拼接 /approvals/{id}/comments/ 或 /tasks/{id}/comments/ -- 这些路径不存在。
• 不要使用表单编码正文 -- 评论在任何地方都使用 JSON。在代码模式下，应使用 fastio.postJson()，而不是 fastio.post()。
• 不要将 node_id 与来自其他工作区/共享项的 parent_id 混用 -- 节点必须位于你指定的父级之下。404 通常表示父级错误。
• 不要尝试关联到 worklog_entry -- 关联目标仅限 task 和 approval。

工作流审批——快速入门

适用场景： 文件、文件夹或任务需要一位或多位审核者正式签字确认。

审批直接关联到实体——而非共享。常见错误：创建共享来存放审批。不要这样做。共享用于分发（发送/接收/交换）；审批是附加在实体本身的审核关卡。

步骤 1——在工作区启用工作流（每个工作区仅需一次）：

• 使用 workspace 操作 enable-workflow，并提供 workspace_id。

步骤 2——在目标节点上为每位审核者创建一个审批：

• 使用 approval 操作 create，并提供：
  • profile_type: "workspace"（或 "share"），profile_id: <workspace_id_or_share_id>
  • entity_type: "node"（用于文件或文件夹）
  • entity_id: <node_id>
  • description（审核请求，1-65535 个字符）
  • approver_id: <user_id>——审核者（必须是该配置文件的成员；待加入成员也可以）
• 如有多位审核者，请使用不同的 approver_id 重复调用此操作 N 次。没有批量创建模式。

有效的 entity_type 值： node（文件/文件夹）、task、worklog_entry、share。文件/文件夹审核请使用 node。

处理审批： 使用 approval 操作 resolve，并提供 approval_id 和 resolve_action: "approve" | "reject"（可选 comment）。

应避免的反模式：

• 不要为文件创建共享——审批应直接关联到节点。
• 不要仅为文件审批而创建任务——请使用 entity_type: "node"。
• 不要创建待办事项——待办事项是清单，不是审核关卡。
• approver_id 表示单个用户，而非群组。若有 3 位审核者，请调用 3 次。

审批

适用于任务、存储节点、工时记录或共享的正式审批请求。当决策需要明确签字确认时使用。

• 创建： 使用 approval 操作 create，并提供 profile_type、profile_id、entity_type（"task"、"node"、"worklog_entry" 或 "share"）、entity_id、description（1-65535 个字符），以及可选的 approver_id（单个配置文件 ID，必须是实体成员——可以是待加入成员）。
• 处理审批： 使用 approval 操作 resolve，并提供 profile_type、profile_id、approval_id 和 resolve_action: "approve" 或 "reject"，以及可选的评论。只有指定的审核者才能处理审批。
• 批量操作： approval 操作 bulk-create 会为共享中的每个文件和备注创建审批请求（最多 50 个节点）。approval 操作 bulk-approve 会处理共享中的所有待审批请求（跳过 version_match=false 的过期审批）。approval 操作 bulk-reject 会拒绝共享中的所有待审批请求。
• 版本跟踪： 审批会跟踪 version_id 和 version_match。如果在创建审批后修改了节点，version_match 会变为 false（过期）。批量操作会跳过过期审批，以避免处理过时内容。
• 筛选列表： approval 操作 filtered-list 会按类别筛选并返回审批——"pending"、"created"、"assigned" 或 "resolved"。使用 profile_type/profile_id 指定工作区或共享范围；两者均省略时，则返回跨配置文件的用户级视图。
• 摘要： approval 操作 summary 会返回轻量级计数——按我创建和分配给我分类，列出待审批、已批准和已拒绝的数量。
• 更新： 使用 approval 操作 update，并提供 profile_type、profile_id 和 approval_id，以修改待审批项——可更改描述、审核者、截止日期、节点引用或元数据。只有待审批项可以更新。
• 删除： 使用 approval 操作 delete，并提供 profile_type、profile_id 和 approval_id，以永久移除审批（不限状态）。approval 操作 bulk-delete 会永久移除共享中的所有审批（最多 500 个）。
• 状态： pending、approved、rejected
• Markdown 输出： 传入 format: "md"，以获取便于阅读的输出。

待办事项

作用于工作区和共享空间的简单扁平清单。不支持嵌套——只有一组可以逐项勾选的条目。

• 创建： 使用 todo 操作 create 并提供标题。assignee_id 为可选项——可以指定待加入成员。
• 切换状态： todo 操作 toggle 可切换单个待办事项的完成状态。todo 操作 bulk-toggle 可一次性设置最多 100 个待办事项的完成状态。
• 更新／删除： todo 操作 update 可更改标题或受派人。todo 操作 delete 会软删除待办事项。
• 创建者跟踪： 待办事项包含 created_by 字段（创建者的个人资料 ID）。
• 筛选列表： todo 操作 filtered-list 可按类别筛选待办事项——“assigned”（分配给我）、“created”（由我创建）、“done”（已完成）或“pending”（未完成）。
• 摘要： todo 操作 summary 会返回简要计数——总数、已完成、待处理、分配给我以及由我创建。
• Markdown 输出： 传入 format: "md" 可获得便于阅读的输出。

作为 Agent 知识层的笔记

笔记（type: "note"）是存储在工作区存储空间中的 Markdown 文件（参见上文的笔记）。结合工作流功能后，笔记便可成为知识层：

• 自动 AI 索引： 启用工作区智能功能后，笔记会像上传的文件一样被摄取并编入 RAG 索引。
• 将任务关联到笔记： 任务可以引用存储节点，包括笔记。创建记录项目背景、需求或参考资料的上下文笔记，然后创建关联这些笔记的任务，以获取完整上下文。
• 用于推理的工作日志： 使用工作日志条目记录决策、进度和随时间积累的推理过程。按时间顺序排列的日志会形成叙述，补充结构化任务列表。
• AI 可以搜索所有上下文： 启用智能功能后，AI 聊天可以搜索笔记、工作日志、任务描述和上传文件，从而给出以项目完整历史为依据的全面回答。

推荐模式： 创建记录项目背景和需求的笔记。为各个工作阶段创建任务列表。将任务关联到相关笔记。使用工作日志记录进度。针对决策请求审批。然后，AI 就可以通过搜索所有这些内容，回答“我们为什么选择这种方案？”之类的问题。

权限参数值

有多个工具使用权限参数，并且这些参数有特定的允许值。调用工具时请使用以下准确字符串。

创建组织（org 操作 create）

参数	允许值	默认值
perm_member_manage	Owner only、Admin or above、Member or above	Member or above
industry	unspecified、technology、healthcare、financial、education、manufacturing、construction、professional、media、retail、real_estate、logistics、energy、automotive、agriculture、pharmaceutical、legal、government、non_profit、insurance、telecommunications、research、entertainment、architecture、consulting、marketing	unspecified
background_mode	stretched、fixed	stretched

创建工作区（org 操作 create-workspace）和更新工作区（workspace 操作 update）

参数	允许值	默认值
perm_join	Only Org Owners、Admin or above、Member or above	Member or above
perm_member_manage	Admin or above、Member or above	Member or above

分享创建（share 操作 create）

参数	允许的值	默认值
type	send、receive、exchange	exchange
storage_mode	independent、workspace_folder	independent
access_options	Only members of the Share or Workspace、Members of the Share, Workspace or Org、Anyone with a registered account、Anyone with the link	Only members of the Share or Workspace
invite	owners、guests	owners
notify	never、notify_on_file_received、notify_on_file_sent_or_received	never
display_type	list、grid	grid
intelligence	true、false	false（workspace_folder 分享始终为 false）
comments_enabled	true、false	true
download_security	off、medium、high	off
guest_chat_enabled	true、false	false
anonymous_uploads_enabled	true、false	false
workspace_style	true、false	true
background_image	0-128	0

分享限制：

• Receive 和 Exchange 分享不能使用 Anyone with the link 访问权限——此选项仅适用于 Send 分享。
• 仅当 access_options 为 Anyone with the link 时，才允许启用密码保护（password 参数）。
• workspace_folder 分享不允许设置过期时间（MySQL 格式 YYYY-MM-DD HH:MM:SS 的 expires 参数）。
• workspace_folder 分享不支持智能功能。创建工作区文件夹分享时，无论传入什么值，intelligence 始终设为 false。将工作区文件夹分享更新为 intelligence=true 会返回错误。工作区文件夹分享不支持以文件/文件夹为范围的 AI 聊天和语义搜索；请改用上级工作区的 AI 端点。基础聊天和 files_attach（直接附加文件）仍可使用。
• custom_name、title 和 description 的字段长度和格式限制见下方的 Profile Field Constraints 表。
• 颜色参数（accent_color、background_color1、background_color2）接受 JSON 字符串。
• 当 storage_mode='workspace_folder' 时，create_folder 会为分享创建一个新的工作区文件夹。
• anonymous_uploads_enabled 允许访客在不创建帐户的情况下向 Receive/Exchange 分享上传文件。需要设置为“Anyone”访问级别。不适用于 Send 分享或 Portals。

配置文件字段约束

所有配置文件字段都会在服务器端验证。违反这些约束的请求会被拒绝，并返回 400 错误。

实体	字段	API Key	最小值	最大值	模式	必填	可为空
组织	域名	domain	2	63	^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$	是（创建时）	否
组织	名称	name	3	100	不含控制字符	是	否
组织	描述	description	10	1000	不含控制字符	否	是
工作区	文件夹名称	folder_name	4	80	^[\p{L}\p{N}-]+$（字母、数字、连字符）	是（创建时）	否
工作区	名称	name	2	100	不含控制字符	是	否
工作区	描述	description	10	1000	不含控制字符	否	是
分享	自定义名称	custom_name	4	80	^[\p{L}\p{N}]+$（仅字母和数字）	是（创建时）	否
分享	自定义 URL	custom_url	10	100	—	是	是
分享	标题	title	2	80	不含控制字符	是	是
分享	描述	description	10	500	不含控制字符	否	是

• “不含控制字符” = 拒绝 Unicode 控制字符（\p{C}）
• 组织域名：小写 ASCII 字母数字加连字符；不能以连字符开头或结尾
• 工作区 folder_name：Unicode 字母、数字和连字符。全局唯一——不限定于某个组织。建议采用 {org_id}-{name} 约定以避免冲突（名称已被占用时，create-workspace 会自动应用）
• 分享 custom_name：仅限 Unicode 字母和数字（不允许连字符或特殊字符）
• 分享描述的最大长度为 500（组织/工作区为 1000）

---

4. Agent 计划——免费层级

Agent 计划是专为 AI Agent 设计的免费层级。无需信用卡、没有试用期，也不会过期。提供足够的资源来构建并展示价值；当组织转由付费计划下的人类管理时，还有更多扩展空间。

资源限额

资源	包含内容
价格	$0——无需信用卡、没有试用期，也不会过期
存储空间	50 GB
最大文件大小	1 GB
每月额度	5,000（每 30 天重置）
工作区	5
分享	50
每个工作区的成员数	5
分享邀请	每个分享 10 个
账户自动删除	永不

额度消耗

平台上的所有活动都会消耗每月 5,000 的额度：

资源	消耗额度
存储空间	100 额度/GB
带宽	212 额度/GB
AI 聊天令牌	每 100 个令牌消耗 1 额度
摄取的文档页数	10 额度/页
摄取的视频	5 额度/秒
摄取的音频	0.5 额度/秒
摄取的图像	5 额度/张
文件转换	25 额度/次转换

额度用尽后，组织会进入功能受限状态，API 调用会返回 402 Payment Required。组织永远不会被删除。使用 org action limits 检查当前额度使用情况和剩余余额。

遇到 402 或额度不足时：

• Agent 账户（通过 auth action signup 创建）： 将组织转交给人类。调用 org action transfer-token-create 生成转交令牌，然后将认领 URL 发给人类：https://go.fast.io/claim?token=<token>。对方认领组织后，即可升级到额度不限的付费计划。你会保留管理员权限，并可在升级后立即继续工作。这是预期的工作流程——Agent 使用免费计划构建项目，然后移交给准备付费的人类。
• 人类账户（通过 auth action signin 登录）： 你无法使用转交/认领 API。请告知用户需要直接升级组织的计费计划。他们可以在 Fast.io 控制面板中完成此操作，也可以调用 org action billing-create，将订阅更新为付费计划。

移交后——人工计划选项

Agent 将组织移交给人工后，人工用户会获得免费计划（基于额度，无试用期），并可升级：

功能	Agent（免费）	免费（人工用户）	专业版	商业版
每月额度	5,000	5,000	不限	不限
存储空间	50 GB	50 GB	1 TB	5 TB
最大文件大小	1 GB	1 GB	25 GB	50 GB
工作区	5	5	10	1,000
共享	50	50	1,000	50,000

移交流程是 Agent 提供价值的主要方式：先在免费的 Agent 计划上完成所有设置，然后移交给人工。人工准备好后即可升级，Agent 则保留管理员访问权限，继续管理相关事项。

---

5. 工具类别

这 19 个工具采用基于操作的路由方式。每个工具负责 Fast.io 平台的特定领域，并提供多种操作。

auth

身份验证、登录／注册、双重身份验证、API 密钥管理和 OAuth 会话管理。这始终是 Agent 交互的起点。

操作： signin、signout、signup、check、session、status、set-api-key、email-check、email-verify、password-reset-request、password-reset、2fa-verify、2fa-status、2fa-enable、2fa-disable、2fa-send、2fa-verify-setup、pkce-login、pkce-complete、api-key-create、api-key-update、api-key-list、api-key-get、api-key-delete、oauth-list、oauth-details、oauth-revoke、oauth-revoke-all

user

获取和更新当前用户个人资料、搜索联系人、管理邀请、上传和删除用户资源（个人资料照片）、检查账户资格、列出用户所属的共享，并管理个人 AI 指令（平台应用于 AI 功能的 Markdown 指导内容）。

操作： me、update、search-contacts、close、details-by-id、profiles、allowed、org-limits、list-shares、invitation-list、invitation-details、accept-all-invitations、asset-upload、asset-delete、asset-types、asset-list、instructions-get、instructions-set、instructions-clear

search-contacts 会搜索你的个人联系人列表（此前有过互动的联系人），并且只返回 {email: name}——不包含 user_id，也没有上下文范围。要查找特定工作区／共享／组织的成员，请使用 org action=members、workspace action=members 或 share action=members。

AI 指令：instructions-get / instructions-set / instructions-clear 用于管理 /user/me/instructions/ 下单个仅作用于自身的 Markdown 槽位（最多 65536 字节 UTF-8，set 时完整替换，软清除会保留审计记录行）。用户个人资料没有 me 范围的变体——它本身就仅适用于当前用户。首次读取会返回 content: "" 和空时间戳，而不是 404。

组织

组织的增删改查、成员管理、账单和订阅操作、工作区创建、邀请工作流、资产管理（上传、删除）、组织发现、所有权转让、自定义域名管理，以及 AI 指令（组织级和个人用户槽位）。

操作： list、details、create、update、close、public-details、limits、list-workspaces、list-shares、create-workspace、billing-plans、billing-create、billing-cancel、billing-details、billing-activate、billing-reset、billing-members、billing-meters、members、invite-member、remove-member、update-member-role、member-details、leave、transfer-ownership、join、invitations-list、invitation-update、invitation-delete、transfer-token-create、transfer-token-list、transfer-token-delete、transfer-claim、discover-all、discover-available、discover-check-domain、discover-external、asset-upload、asset-delete、asset-types、asset-list、custom-domain-get、custom-domain-create、custom-domain-delete、custom-domain-validate、instructions-get、instructions-set、instructions-clear

AI 指令：instructions-get/instructions-set/instructions-clear 接受可选的 scope 参数：profile（默认值，组织级槽位——仅限所有者/管理员，非管理员会收到代码为 1680 的 403 错误）或 me（个人用户槽位——任何成员均可使用）。这两个范围相互独立，服务器端不会合并；如需合并视图，请在客户端串联。内容上限为 65536 字节 UTF-8；设置时会完整替换，软清除会保留审计记录。

工作区

工作区级设置、生命周期操作（更新、删除、归档、取消归档）、共享列表和导入、工作区资产管理、工作区发现、备注（创建、读取、更新）、快速共享管理、元数据操作（模板增删改查、分配、文件元数据获取/设置/删除、AI 提取）、工作流开关（启用/禁用任务、工作日志、审批和待办事项），以及 AI 指令（工作区级和个人用户槽位）。

操作： list、details、update、delete、archive、unarchive、members、list-shares、import-share、available、check-name、create-note、read-note、update-note、quickshare-get、quickshare-delete、quickshares-list、metadata-template-create、metadata-template-delete、metadata-template-list、metadata-template-details、metadata-template-update、metadata-template-clone、metadata-template-preview-match、metadata-template-suggest-fields、metadata-template-assign、metadata-template-unassign、metadata-template-resolve、metadata-template-assignments、metadata-view-get、metadata-view-save、metadata-view-delete、metadata-views-list、metadata-view-export、metadata-search、metadata-get、metadata-set、metadata-delete、metadata-extract、jobs-status、metadata-list-files、metadata-list-templates-in-use、metadata-versions、enable-workflow、disable-workflow、enable-import、disable-import、instructions-get、instructions-set、instructions-clear

AI 指令：instructions-get/instructions-set/instructions-clear 接受可选的 scope 参数：profile（默认值，工作区级槽位——仅限所有者/管理员，非管理员会收到代码为 1680 的 403 错误）或 me（个人用户槽位——任何成员均可使用，访客除外）。这两个范围相互独立，服务器端不会合并；如需合并视图，请在客户端串联。内容上限为 65536 字节 UTF-8；设置时会完整替换，软清除会保留审计记录。

share

分享的 CRUD、公开详情、归档、密码认证、资源管理、分享名称可用性检查、工作流开关（启用/停用任务、工作日志、审批和待办事项），以及 AI 指令（分享范围和按用户划分的槽位）。

操作： list、details、create、update、delete、public-details、archive、unarchive、password-auth、members、available、check-name、quickshare-create、enable-workflow、disable-workflow、instructions-get、instructions-set、instructions-clear

AI 指令：instructions-get/instructions-set/instructions-clear 接受可选的 scope 参数：profile（默认值，分享范围的槽位 — 仅限所有者/管理员，非管理员会收到 403 错误代码 166463）或 me（按用户划分的槽位 — 仅限已注册成员，匿名用户/链接访客会收到 403 错误代码 185733）。这两个范围彼此独立，服务器端不会合并；如需合并视图，请在客户端拼接。content 上限为 65536 字节 UTF-8，设置时会完整替换，软清除会保留审计记录。

storage

在工作区和分享中执行文件与文件夹操作。可列出文件、列出所有文件夹中最近修改的文件、创建文件夹、移动、复制、删除、重命名、清除、恢复、搜索（启用智能功能时支持关键词或语义搜索）、从上传内容添加文件、添加分享链接、传输节点、管理回收站、执行版本操作、锁定文件，以及生成预览/转换 URL。需要 profile_type 参数（也接受 context_type）（workspace 或 share）。

操作： list、recent、details、search、trash-list、create-folder、copy、move、delete、rename、purge、restore、add-file、add-link、transfer、version-list、version-restore、lock-acquire、lock-status、lock-release、preview-url、preview-transform

upload

文件上传操作。分块上传流程（创建会话、以纯文本、Base64 编码二进制数据或 blob 引用上传分块、完成上传、检查状态、取消）、单次调用流式上传（stream-upload 会在一次调用中创建流会话、传输字节并自动完成上传）、一次往返批量上传多个小文件（batch）、从外部 URL 导入文件、上传限制和文件扩展名限制，以及会话管理。大型二进制数据通过 POST /blob 辅助接口传输（每个 blob 上限为 100 MB）；对于无法访问 /blob 的 Agent（沙盒环境）上传的小型二进制数据，请改用 content_base64 — 服务器会在服务端解码，唯一限制是 MCP 传输消息大小。

操作： create-session、stream-upload、batch、chunk、stream、finalize、status、cancel、list-sessions、cancel-all、chunk-status、chunk-delete、web-import、web-list、web-cancel、web-status、limits、extensions、blob-info

download

为工作区文件、分享文件和 quickshare 链接生成下载 URL 和 ZIP 存档 URL。MCP 工具无法传输二进制数据 —— 这些操作会返回可在浏览器中打开或传递给下载工具的 URL。file-url 和 zip-url 操作需要 profile_type 参数（也接受 context_type）（workspace 或 share）。响应包含 resource_uri 字段（例如 download://workspace/{id}/{node_id}），MCP 客户端可通过 MCP 资源直接读取文件内容。直接下载 URL 包含 ?error=html，因此错误会在浏览器中以便于人类阅读的 HTML 格式呈现。

操作： file-url、zip-url、quickshare-details

ai

在工作区和分享中使用 AI 驱动的 RAG 聊天、文档分析和可分享摘要。可创建聊天、发送消息、读取 AI 响应（通过轮询）、列出和管理聊天、发布私密聊天、生成 AI 分享 Markdown、跟踪 AI token 使用量，以及自动生成标题。需要 profile_type 参数（也接受 context_type）（workspace 或 share）。

操作： chat-create、chat-list、chat-details、chat-update、chat-delete、chat-publish、message-send、message-list、message-details、message-read、share-generate、transactions、autotitle

评论

评论的作用范围为 {entity_type}/{parent_id}/{node_id}，其中 entity_type 为 workspace 或 share，parent_id 为 19 位的资料 ID，node_id 为存储节点的不透明 ID。列出文件评论（支持按节点或整个资料列出，并可使用排序、限制数量、偏移量和筛选参数），添加评论并可选择锚定引用（图像区域、视频／音频时间戳、带文本选区的 PDF 页面、Markdown／笔记中的文本选区），支持单层串联回复、递归单条删除、非递归批量删除、获取评论详情、表情回应（每位用户对每条评论只能添加一个），以及工作流关联（将评论关联到任务或审批，或取消关联，并支持反向查询）。评论使用 JSON 请求正文。

操作： list、list-all、add、delete、bulk-delete、details、reaction-add、reaction-remove、link、unlink、linked

事件

通过类别、子类别和事件名称进行丰富筛选，搜索审计／事件日志（完整分类请参阅第 7 节中的 事件筛选参考）。获取 AI 生成的活动摘要、检索单个事件的完整详情、列出近期活动，以及通过长轮询获取活动变更。

操作： search、summarize、details、activity-list、activity-poll

成员

管理工作区和共享空间的成员。添加成员、移除成员、更新角色、转让所有权、离开、加入，以及通过邀请加入。成员列表同时包含活跃成员和待处理成员（已邀请但尚未注册）——待处理成员的 status: "pending"，并包含带有 id、created 和 expires 字段的 invite 对象。需要 entity_type 参数（workspace 或 share）。

操作： add、remove、details、update、transfer-ownership、leave、join、join-invitation

邀请

管理工作区和共享空间的邀请。列出邀请、按状态列出、更新和删除／撤销邀请。删除待处理成员的邀请，也会将其从成员列表中移除，并取消分配其工作流项目（任务、审批、待办事项）。需要 entity_type 参数（workspace 或 share）。

操作： list、list-by-state、update、delete

资源

管理组织、工作区、共享空间和用户的资源（上传、删除、列出、读取）。需要 entity_type 参数（org、workspace、share 或 user）。

操作： upload、delete、types、list、read

任务

管理工作区和共享空间的任务列表及任务。创建和管理任务列表，然后在其中创建任务，并设置状态、优先级、负责人和依赖项。支持批量更改状态、重新排序和 Markdown 输出。任务及列表包含 created_by（创建者资料 ID）。目标实体必须启用工作流。

操作： list-lists、create-list、list-details、update-list、delete-list、list-tasks、create-task、task-details、update-task、delete-task、change-status、assign-task、bulk-status、move-task、reorder-tasks、reorder-lists、filtered-list、summary

工作日志

用于跟踪 Agent 工作的活动日志。上传文件、更改任务、创建共享空间或执行任何重要操作后，记录你做了什么以及原因——为人工用户和 AI 构建可搜索的审计跟踪。还可创建需要确认的紧急消息。条目只能追加，且永久保留。目标实体必须启用工作流。

操作： append、list、interject、details、acknowledge、unacknowledged、profile-list、filtered-list、summary

审批

适用于任务、存储节点、工作日志条目或共享空间的正式审批请求。创建指定审批人的审批请求，然后通过批准或拒绝来处理。目标实体必须启用工作流。

操作： list、create、details、resolve、bulk-create、bulk-approve、bulk-reject、filtered-list、summary、update、delete、bulk-delete

待办事项

适用于工作区和共享空间的简单扁平清单。可单独或批量创建、更新、删除和切换待办事项。待办事项包含 created_by（创建者个人资料 ID）。不支持嵌套。目标实体必须启用工作流。

操作： list、create、details、update、delete、toggle、bulk-toggle、filtered-list、summary

应用

交互式 MCP App 小组件的发现与启动。列出可用小组件，获取特定小组件的详细信息，在工作区或共享空间上下文中启动小组件，并查找与特定工具领域相关联的小组件。

操作： list、details、launch、get-tool-apps

---

6. 常见工作流

1. 创建账户并登录

请参阅第 2 节中的选择合适的方式，了解哪种选项适合你的场景。

选项 1 —— 自主 Agent（新账户）：

1.（可选）调用 auth 操作 email-check —— 这仅提供参考提示，不要以结果作为是否继续的条件。对于随后 signup 接受的电子邮件地址，email-check 可能返回 available: false。始终调用 signup，并以其错误结果为准。 2. 调用 auth 操作 signup，并提供 first_name、last_name、email 和 password —— 注册为 Agent 账户（会自动发送 agent=true），并立即登录。 3. 调用 auth 操作 email-verify，并提供 email —— 发送验证码。然后调用 auth 操作 email-verify，并提供 email 和 email_token —— 验证验证码。使用大多数端点前都必须完成此步骤。 4. 调用 org 操作 create，在 Agent 计划上创建新的组织；或调用 org 操作 list 查看现有组织。

选项 2 —— 协助真人（API 密钥）：

1. 真人在 https://go.fast.io/settings/api-keys 创建 API 密钥，并提供给 Agent。
2. 调用 auth 操作 set-api-key 并提供 API 密钥。密钥会通过 API 验证并存储在会话中，之后所有工具调用都会自动进行身份验证。无需创建账户。
3. 调用 org 操作 list 和 org 操作 discover-external，发现所有可用组织（参见组织发现）。

选项 3 —— Agent 受邀加入真人的组织：

1. 调用 auth 操作 signup 创建 Agent 账户（与选项 1 相同）。
2. 让真人通过 org 操作 invite-member 或 member 操作 add（使用 entity_type: "workspace"）邀请你。
3. 调用 user 操作 accept-all-invitations 接受邀请。
4. 调用 org 操作 list 和 org 操作 discover-external，发现所有可用组织（参见组织发现）。如果真人只邀请你加入工作区（而非组织），该工作区只会通过 discover-external 显示。

回访用户：

1. 调用 auth 操作 signin，并提供 email 和 password。
2. 如果 two_factor_required: true，调用 auth 操作 2fa-verify 并提供双重验证 code。
3. 调用 org 操作 list 和 org 操作 discover-external，发现所有可用组织（参见组织发现）。

2. 浏览并下载文件

1. 调用 org 操作 list 和 org 操作 discover-external，发现所有可用组织（参见组织发现）。记下 org_id 值。
2. 调用 org 操作 list-workspaces 并提供 org_id，获取组织中的工作区。记下 workspace_id 值。
3. 调用 storage 操作 list，并提供 profile_type: "workspace"、profile_id（工作区 ID）和 node_id: "root"，浏览根文件夹。记下文件和子文件夹的 node_id 值。
4. 调用 storage 操作 details，并提供 profile_type: "workspace"、profile_id 和 node_id，获取特定文件的完整详细信息（名称、大小、类型、版本）。
5. 调用 download 操作 file-url，并提供 profile_type: "workspace"、profile_id 和 node_id，获取包含内嵌令牌的临时下载 URL。响应还会包含一个 resource_uri（例如 download://workspace/{id}/{node_id}），MCP 客户端可用它直接读取文件内容。将下载 URL 返回给用户，或通过 MCP 使用资源 URI 读取文件。

3. 将文件上传到工作区

二进制数据默认使用 POST /blob sidecar。 它可绕过 MCP 传输限制，没有 base64 开销，并且适用于最大 100 MB 的文本和二进制文件。（内联文本请使用 content；对于无法访问 /blob 的沙盒环境中的小型内联二进制数据，可使用 content_base64 作为带内备用方案——受 MCP 传输消息大小限制。）

选项 A：web-import（URL 可访问的文件优先使用） 如果文件有 URL（HTTP/HTTPS、Google Drive、OneDrive、Box、Dropbox），请使用 upload 操作 web-import。单次调用，无需分块。参见下方工作流 4。

选项 B：POST /blob sidecar（其他所有文件——文本或二进制）

1. 使用 upload 操作 create-session，并提供 profile_type、profile_id、parent_node_id、filename 和 filesize。响应中包含可直接使用的 curl 命令 blob_upload.curl_command。
2. 执行 blob_upload.curl_command 中的 curl 命令，将 @<file> 替换为文件路径。返回 { "blob_id": "<uuid>", "size": <bytes> }。
3. 使用 upload 操作 chunk，并提供 upload_id、chunk_number: 1 和 blob_id: "<blob_id>"。
4. 如果文件较大，需要拆分，则重复步骤 2-3，上传其他分块。
5. 使用 upload 操作 finalize，并提供 upload_id。

重要： blob_upload.session_id 是此连接的 MCP 会话 ID。向 /blob 发送 POST 请求时，必须在 Mcp-Session-Id 标头中使用此确切的会话 ID。使用不同的会话 ID（例如，来自单独建立的 MCP 连接）会将 blob 存放在其他位置，导致 chunk 操作无法找到它。

传递分块数据有以下三种方式（必须且只能提供一种）：

• blob_id — POST /blob 响应中的 blob ID。所有文件的标准上传方式——无需 base64，也不受 MCP 传输限制。（为保持向后兼容，也接受 blob_ref。）
• content — 仅用于较短的文本字符串（代码片段、简短 JSON）。内容会原样存储为 UTF-8 字节——请勿在此处传入 base64，否则内容会被保存为 base64 编码的文本文件。对于较大的文本文件，请使用 POST /blob + blob_id。
• content_base64 — 用于以 base64 编码字符串表示的小型二进制内容。服务器会在写入前对其解码。当 Agent 所处的环境可以在 JSON 中生成 base64、但无法访问 POST /blob sidecar 时，此方式很有用（例如，没有网络或身份验证令牌的沙盒 Agent）。空格和换行符会自动去除。实际大小上限受 MCP 传输消息大小限制（几 MB）；对于较大的二进制文件，请使用 POST /blob + blob_id。

使用 upload 操作 finalize 并提供 upload_id，即可触发文件组装并轮询，直到文件存储完毕。成功时会返回最终会话状态，状态为 status: "stored" 或 "complete"（包括 new_file_id）；失败时则会抛出错误。终止失败状态包括：assembly_failed（无法组装分块）和 store_failed（无法存储组装后的文件——请查看 status_message 了解详情）。文件会自动添加到创建会话时指定的目标工作区和文件夹中——无需单独调用添加文件。

上传状态：

状态	含义	是否为终止状态？
ready	会话已创建，等待分块	否
uploading	正在接收分块	否
assembling	正在组装	否
complete	已组装，等待导入存储	否
storing	正在导入存储	否
stored	完成——文件已存储，可使用 new_file_id	是（成功）
assembly_failed	组装错误	是（失败）
store_failed	导入存储失败	是（失败）

注意： 只有当你想将上传文件关联到与创建会话时指定位置不同的位置时，才需要使用 storage 操作 add-file。 同名上传（原位替换，保留版本）： 如果目标文件夹中已存在同名文件，上传会原位覆盖现有节点。node_id 会保留，原内容则作为一个版本留存。这就是“编辑”文件的方式——请勿删除后重新上传。 每次同名覆盖后，都可以通过 storage 操作 version-list（列出版本）和 version-restore（按 version_id 恢复）找回原内容。不同版本共用稳定的 node_id，因此评论、任务、审批、元数据等中的引用仍然有效。若要同时保留两个文件，请在上传前重命名。完整操作流程和示例请参阅第 4 节中的覆盖文件。

按 node_id 确定性覆盖： 如果文件名可能已更改，或者你想避免重新解析父文件夹，请在 create-session 中传入 target_node_id，将覆盖操作固定到特定节点。设置该参数后，parent_node_id 会被忽略，filename 则为可选项（省略可保留现有名称，传入新名称可在替换时重命名）。省略 filename 会额外触发一次 storage details 查询，让工具将现有名称传给 API（更新模式仍要求提供 name）；传入 filename 可跳过这次往返。服务端底层使用 action=update + file_id=<target_node_id>。node_id 会保留；新版本会显示在 storage 操作 version-list 中。典型流程：通过 storage 操作 list/details 找到节点 → 使用 target_node_id 调用 upload 操作 create-session → POST /blob → chunk/stream → finalize。

4. 从 URL 导入文件

当你有文件 URL（HTTP/HTTPS、Google Drive、OneDrive、Box、Dropbox），并希望将文件添加到工作区而无需下载到本地时，请使用此方法。

1. 使用 upload 操作 web-import，并传入 url（源 URL）、profile_type: "workspace"、profile_id（工作区 ID）和 parent_node_id（目标文件夹或 "root"）。返回 upload_id。
2. 使用 upload 操作 web-status 并传入 upload_id——检查导入进度。服务端会下载文件、进行扫描、生成预览，并将其编入索引以供 AI 使用（若已启用智能功能）。
3. 任务完成后，文件会显示在工作区存储树中。

5. 向客户端交付文件

为对外交付的文件创建具有品牌标识的专业共享页面，替代原始下载链接、电子邮件附件和 S3 预签名 URL。

1. 将文件上传到工作区（参见工作流 3 或 4）。
2. 使用 share 操作 create，并传入 workspace_id、name 和 type: "send"——创建一个 Send 共享。返回 share_id。
3. 使用 share 操作 update 并传入 share_id 进行配置：
   • password——访问时要求输入密码
   • expiry_date——在指定期限后自动使共享过期
   • access_level——仅成员、组织成员、已注册用户或公开
   • download_security——控制访客下载：off（不受限制）、medium（仅预览）、high（禁止下载）
   • 品牌选项：background_color、accent_color、gradient_color
   • post_download_message 和 post_download_url——下载后显示消息
4. 使用 member 操作 add，并传入 entity_type: "share"、entity_id（共享 ID）和 email_or_user_id——添加接收者。如果对方没有 Fast.io 账户，系统会发送邀请。
5. 使用 asset 操作 upload，并传入 entity_type: "share" 和 entity_id（共享 ID），添加用于品牌展示的徽标或背景图片。
6. 接收者看到的是带有品牌标识的页面，并可即时预览文件，而不是原始下载链接。

6. 收集用户提交的文档

创建一个接收共享，让用户可以直接向你上传文件，无需通过电子邮件附件或云盘链接。对于公开收集（例如求职申请、表单提交），启用 anonymous_uploads_enabled，访客即可无需创建账号上传文件。

1. 使用 share 操作 create，并提供 workspace_id、name（例如“在此处上传你的税务文件”）和 type: "receive"。操作会返回 share_id。如需匿名提交，还要传入 anonymous_uploads_enabled: true，并将 access_options 设为“任何拥有注册账号的用户”或更开放的选项。
2. 使用 share 操作 update，并提供 share_id，按需设置访问级别、过期时间和品牌信息。
3. 使用 member 操作 add，并提供 entity_type: "share"、entity_id（共享 ID）和 email_or_user_id，邀请上传者（匿名提交共享可跳过此步骤）。
4. 用户通过简洁且带有品牌标识的界面上传文件。
5. 文件会显示在你的工作区中。如果已启用智能功能，AI 会自动为文件建立索引。
6. 使用 ai 操作 chat-create，并将 profile_type: "share" 指定为接收共享的文件夹范围，然后提出“所有必需的表格都齐全吗？”之类的问题。

7. 构建知识库

创建一个智能工作区，自动为所有内容建立索引，以供 RAG 查询。

1. 使用 org 操作 create-workspace，并提供 org_id、name 和 intelligence: "true"（此工作流需要启用智能功能才能进行 RAG）。
2. 上传参考文档（参见工作流 3 或 4）。上传后，AI 会自动为所有内容建立索引并生成摘要。
3. 使用 ai 操作 chat-create，并提供 profile_type: "workspace"、profile_id（工作区 ID）、query_text、type: "chat_with_files" 和 folders_scope（以逗号分隔的 nodeId:depth 对），查询多个文件夹或整个工作区。
4. 使用 ai 操作 message-read，并提供 profile_type: "workspace"、profile_id、chat_id 和 message_id，轮询直至 AI 完成回复。操作会返回 response_text 和 citations，其中包含指向特定文件、页面和片段的引用。
5. 使用 storage 操作 search，并提供 profile_type: "workspace"、profile_id 和查询字符串。启用智能功能后，此操作会执行语义搜索，按含义而非仅按文件名查找文件。
6. 答案会包含指向特定页面和文件的引用。将这些答案连同来源引用一起提供给用户。

8. 询问 AI 有关文件的问题

根据工作区是否启用了智能功能，有两种模式。

启用智能功能（持久索引）：

1. 使用 ai 操作 chat-create，并提供 profile_type: "workspace"、profile_id（工作区 ID）、query_text、type: "chat_with_files"，以及 files_scope（以逗号分隔的 nodeId:versionId 对）或 folders_scope（以逗号分隔的 nodeId:depth 对，深度范围为 1-10）。重要：files_scope 和 files_attach 不能同时使用——同时发送两者会报错。返回 chat_id 和 message_id。
2. 使用 ai 操作 message-read，并提供 profile_type: "workspace"、profile_id、chat_id 和 message_id——最多轮询 API 15 次（间隔 2 秒，约 30 秒），直到 AI 响应完成。返回 response_text 和 citations。**提示：**如果内置轮询时间窗口已结束，请改用带工作区 ID 的 event 操作 activity-poll，而不要循环调用 message-read——请参阅上文“活动轮询”部分。
3. 使用 ai 操作 message-send，并提供 profile_type: "workspace"、profile_id、chat_id 和 query_text，以提出后续问题。返回新的 message_id。
4. 再次使用 ai 操作 message-read，并提供新的 message_id，以获取后续响应。

未启用智能功能（文件附件）：

1. 使用 ai 操作 chat-create，并提供 profile_type: "workspace"、profile_id、query_text、type: "chat_with_files"，以及指向特定文件的 files_attach（以逗号分隔的 nodeId:versionId，最多 20 个文件 / 200 MB）。文件必须设为 ai.attach: true（通过 storage 操作 details 检查）。AI 会直接读取附加的文件，不进行持久索引。
2. 使用 ai 操作 message-read 获取响应。不消耗摄取额度——仅消耗聊天 Token 额度。

9. 为人类设置项目

完整的 Agent 到人类移交工作流。这是 Agent 在 Fast.io 上创造价值的主要方式。

1. 使用 org 操作 create——在 Agent 计费方案下创建新的组织。Agent 将成为所有者。系统会自动创建 Agent 方案订阅（免费、50 GB、每月 5,000 个额度）。
2. 使用 org 操作 create-workspace，并提供 org_id 和 name——为每个项目领域创建工作区。
3. 使用 storage 操作 create-folder，并提供 profile_type: "workspace"，以搭建文件夹结构（模板、交付物、参考文档等）。
4. 向每个工作区上传文件（参见工作流 3 或 4）。
5. 对客户交付物使用 share 操作 create，并设置 type: "send"；对资料收集使用 type: "receive"。
6. 使用 share 操作 update，为每个共享配置品牌、密码、有效期和访问级别。
7. 使用 org 操作 invite-member，或使用 member 操作 add 并设置 entity_type: "workspace"，以邀请团队成员。
8. 使用 org 操作 transfer-token-create，并提供 org_id——生成一个有效期为 72 小时的转移令牌。将认领 URL（https://go.fast.io/claim?token=<token>）发送给人类。
9. 人类点击链接并认领组织。他们将成为所有者，Agent 保留管理员访问权限。人类将获得免费方案。

10. 管理组织账单

1. 使用 org 操作 billing-plans——列出所有可用的计费方案及其价格和功能。
2. 使用 org 操作 billing-create，并提供 org_id，还可选提供 billing_plan——创建或更新订阅。对于新订阅，此操作会创建 Stripe Setup Intent。
3. 使用 org 操作 billing-details，并提供 org_id——查看当前订阅状态、Stripe 客户信息和付款详情。
4. 使用 org 操作 limits，并提供 org_id——查看相对于方案限制的额度使用情况，包括存储、传输、AI Token 和计费周期信息。

11. 在工作区中管理任务

使用结构化的任务列表和任务来跟踪工作。

1. 使用 workspace 操作 enable-workflow，并传入 workspace_id ——启用工作流功能（使用任务、工作日志、审批或待办工具前必须先启用）。
2. 使用 task 操作 create-list，并传入 profile_type: "workspace"、profile_id（工作区 ID）和 name ——创建任务列表。返回 list_id。
3. 使用 task 操作 create-task，并传入 list_id、title，以及可选的 description、priority（0-4）、assignee_id、dependencies、node_id 和 status ——向列表中添加任务。
4. 使用 task 操作 list-tasks，并传入 list_id ——查看所有任务，也可按 status 或 assignee 筛选。
5. 使用 task 操作 change-status，并传入 list_id、task_id 和 status ——更新任务进度（pending → in_progress → complete）。
6. 使用 task 操作 assign-task，并传入 list_id、task_id 和 assignee_id ——将工作分配给团队成员。
7. 使用 task 操作 bulk-status，并传入 list_id、task_ids 和 status ——一次批量更新最多 100 个任务。

12. 完整的 Agent 工作流（任务 + 工作日志 + 审批）

完整的 Agent 工作流模式：规划工作、记录执行过程，并通过审批把关决策。

1. 使用 workspace 操作 enable-workflow，并传入 workspace_id ——在工作区中启用工作流功能。
2. 使用 workspace 操作 create-note ——创建背景说明，记录项目背景、需求和参考资料。
3. 使用 task 操作 create-list ——为每个工作阶段创建任务列表（例如“研究”“实施”“审查”）。
4. 使用 task 操作 create-task ——添加与背景信息关联的任务。使用描述性标题，并在描述中引用背景说明的 node_ids。
5. 使用 task 操作 change-status，并传入 status: "in_progress" ——将任务标记为已开始。
6. 使用 worklog 操作 append，并传入 entity_type（"task"、"task_list" 或 "profile"）、entity_id（相应实体的不透明 ID；当 entity_type 为 "profile" 时，则传入 profile 的 19 位 ID）和 content ——在工作过程中记录进度、决策和推理过程，形成按时间顺序排列的叙述。
7. 如果需要修正优先级：使用 worklog 操作 interject ——创建一条紧急记录，需要其他参与者确认。
8. 使用 worklog 操作 unacknowledged ——继续之前检查是否有未确认的紧急记录。
9. 使用 worklog 操作 acknowledge ——将紧急记录标记为已查看。
10. 当某项决策需要签字批准时：使用 approval 操作 create，并传入 profile_type、profile_id、entity_type（"task"、"node" 或 "worklog_entry"）、entity_id、description，以及可选的 approver_id ——请求正式审批。
11. 使用 approval 操作 resolve，并传入 resolve_action: "approve" 或 "reject"，以及可选的 comment ——由审批人处理请求。
12. 使用 task 操作 change-status，并传入 status: "complete" ——将已完成的任务标记为完成。
13. 使用 todo 操作 create ——在主要任务流程中跟踪简单的检查清单事项。
14. 启用智能功能后，使用 ai 操作 chat-create ——AI 可以跨笔记、任务描述和工作日志进行搜索，以回答有关项目的问题。

---

7. 关键模式和注意事项

操作名称格式

操作名称使用连字符分隔（例如 create-session、list-shares）。也接受下划线——create_session 和 create-session 等效。规范格式为连字符。

参数别名

对工作区或共享内容执行操作的工具使用 profile_type 和 profile_id 作为规范参数名称。旧名称 context_type 和 context_id 在所有工具中也可作为别名使用——两种形式可以互换，行为完全相同。

ID 格式

Profile ID（组织、工作区、共享、用户）是 19 位数字字符串。大多数端点也接受自定义名称作为标识符——例如工作区文件夹名称、共享 URL 名称、组织域名或用户电子邮件地址。这两种格式在 URL 路径参数中可以互换使用。

所有其他 ID（节点 ID、上传 ID、聊天 ID、评论 ID、邀请 ID 等）都是 30 个字符的字母数字不透明 ID（显示时带连字符）。不要对这些 ID 应用数字验证。

分页

不同端点使用两种分页方式：

基于游标（存储列表端点）： sort_by、sort_dir、page_size 和 cursor。如果还有更多结果，响应会包含 next_cursor 值。将此游标传入下一次调用以获取下一页。页面大小通常为 100、250 或 500。适用于：storage action list（使用 profile_type: "workspace" 或 "share"）。

限制/偏移量（其他所有列表端点）： limit（1-500，默认值为 100）和 offset（默认值为 0）。适用于：org actions list、members、list-workspaces、list-shares、billing-members、discover-all、discover-external；share actions list、members；workspace actions list、members、list-shares；user action list-shares；storage action search。

二进制下载

MCP 工具会返回下载 URL——它们不会直接流式传输二进制内容。download action file-url（使用 profile_type: "workspace" 或 "share"）和 download action quickshare-details 会调用 /requestread/ 端点获取临时令牌，然后构造完整的下载 URL。Agent 应将这些 URL 返回给用户，或传递给下载工具。

download actions zip-url（工作区和共享）会返回 URL 以及所需的 Authorization 标头值。

上传

大多数文件上传通过 POST /blob 旁路端点完成——这是处理大文件的标准方式。它绕过 MCP 传输限制，没有 base64 额外开销，并且支持上传最大 100 MB 的任意大小文本和二进制文件。（内联替代方式：小型文本使用 content；当 Agent 无法访问 /blob 时，小型二进制文件使用 content_base64——两者都受 MCP 传输消息大小限制。）

对于可通过 URL 访问的文件，优先使用 web-import。 如果文件可通过任何 URL（HTTP/HTTPS、Google Drive、OneDrive、Box、Dropbox）访问，请使用 upload action web-import，而不是分块上传。只需调用一次工具——无需分块，也无需管理会话。

上传限制 API

调用 upload action limits 获取套餐的上传限制。可选参数：action_context（"create" 或 "update"）、instance_id（目标工作区/共享 ID）、file_id（用于更新）、org（组织 ID）。

响应字段：

字段	描述	Free/Agent	Pro	Business
chunk_size	最大分块大小	100 MB	100 MB	100 MB
size	每次上传的最大文件大小	1 GB	25 GB	50 GB
chunks	每个会话的最大分块数	35	550	550
sessions	最大并发会话数	150	7,500	7,500
sessions_size_max	所有会话的最大总大小	6.6 GB	160 GB	320 GB

注意： API 返回的是最大限制。最小分块大小（1 MB） 是固定的系统常量，不会由此端点返回——所有套餐均适用此限制。

选择上传策略

单文件上传是默认方式。批量上传是专门用于“一次上传多个小文件”的选项，其他情况请使用单文件上传路径。

文件类型	是否已知大小？	推荐方式
任意带 URL 的文件	不适用	upload 操作 web-import（单步完成）
文本或二进制文件，无 URL	是	POST /blob sidecar → chunk 携带 blob_id → finalize
生成或管道传输的内容，无 URL	否	POST /blob → upload 操作 stream-upload 携带 blob_id（单次调用：创建会话、传输字节并自动完成）
专用： 一次上传多个小文件（每个文件 ≤4 MB）	是	每个文件分别执行 POST /blob → upload 操作 batch 携带 files[] 清单（一次往返，最多 200 个文件；不适用于单文件上传，请使用上述单文件上传路径）

批量上传——一次往返上传多个小文件

需要上传多个小文件（AI 输出、报告包、导出的 CSV、收据）时，upload 操作 batch 会在一个请求中提交整个清单。这样可以避免在每个文件的上传速率限制桶中消耗 N 个额度；对于小文件工作负载，通常还能将墙钟时间缩短一个数量级。

硬性限制（发送请求前由客户端强制执行）：

• 每次调用 ≤ 200 个文件。 超出时会返回错误，提示你拆分。
• 每个文件 ≤ 4 MB。 任何文件超过 4 MB，都会导致整个批次被拒绝，并提示使用分块流程（create-session → chunk → finalize）。批量上传和分块上传不能混用。
• 解析后的字节总量 ≤ 100 MB。 多部分原始数据——不会因 base64 而膨胀。（多部分封装开销很小但不为零；服务器会在封装后测量请求体大小，因此原始字节刚好达到 100 MB 的批次仍可能被拒绝。大批次请预留几百 KB 的余量。）
• 必须认证。 匿名调用方会收到 HTTP 401（代码 10011）并被拒绝。对于无需认证的 public-receive / public-exchange 共享上传，请改用单文件 create-session 流程。
• relative_path 格式。 必须以斜杠结尾（如缺少则自动规范化）。不得以斜杠开头。不得包含 . 或 .. 路径段。不符合要求时，客户端会按条目拒绝并返回错误，方便你修正单个文件而不丢失整个批次。

典型流程：

1. 对每个文件，使用文件字节调用 POST /blob（参见下方的 blob 部分，或调用 upload 操作 blob-info）。收集返回的 blob_id 值。
2. 调用 upload 操作 batch，并提供：
   • profile_type + profile_id——目标工作区或共享
   • folder_id（可选）——目标文件夹 OpaqueId 或 "root"（批次级别；本次调用中的每个文件都会放入此文件夹）。若使用实例根目录，则省略。若每个文件的目标位置不同，请分别发起批次，不要滥用 relative_path。
   • files[]——每个文件对应一个条目：{filename, blob_id}、{filename, content}（非空内联文本）或 {filename, content_base64}（小型二进制数据，由服务器解码；会自动去除空白）。filename 长度为 1-255 个字符（超过 100 个字符时，服务器会在保留扩展名的同时截断名称）。每个条目可选提供 relative_path（长度为 1-8192 个字符，必须以斜杠结尾，缺少时会自动规范化；不得以 / 开头，也不得包含 . 或 .. 路径段），以在 folder_id 下创建子文件夹。每个条目还可选提供 hash（十六进制字符串）+ hash_algo（可选值为 md5、sha1、sha256、sha384）——调用方提供的摘要会原样转发（由服务器验证）。默认情况下，对于未携带哈希值的条目，工具会在客户端计算 SHA-256；在调用中设置 include_hash: false 可跳过计算。
   • creator（可选）——会在响应中原样返回（长度为 1-150 个字符，仅限字母数字字符和连字符）。 响应格式：

• batch_id、count_total、count_succeeded、count_errored、partial（当成功和出错的条目均非零时为 true）、all_failed（当所有条目都出错时为 true）、creator（回显）。
• results[] — 每个文件对应一个条目，包含 index、filename、status（"ok" 或 "error"）。状态为 ok 时：包含 upload_id（用于审计关联的句柄）和 node_id（可能为 null — 见下文）。状态为 error 时：包含 error_code 和 error_message。
• errors[] — 仅包含出错条目的预筛选视图，便于查看。

⚠️ 三个关键语义陷阱：

1. 成功时 node_id 可以为 null。 对于采用异步存储最终处理的工作区，响应会返回 "status": "ok" 和 "node_id": null — 存储节点稍后由 assemble worker 分配。这是成功，不是失败。 请勿将 null node_id 视为错误。如果需要最终节点 ID，请稍等片刻后对目标文件夹调用 storage action list，或订阅上传事件。

2. 部分成功很常见。 当部分条目遇到单文件验证错误（哈希错误、扩展名不允许等）时，预期响应格式是 HTTP 200 且 count_errored > 0。请勿重试整个批次。 检查 results[]，按状态分类，并且仅重试 error_code 可重试的出错条目。

3. 全部失败时仍返回 HTTP 200。 当所有条目都出错时，工具会在响应中设置 all_failed: true。没有任何内容上传；请检查 results[]/errors[]，了解出错原因（哈希不匹配、扩展名被拦截等），并在重新提交前修正输入。batch_id 会保留 1 小时，以便审计查询。

速率限制： 批量端点使用独立于单文件 /upload/ 桶的速率限制 — 批量上传不会占用单文件额度。遇到 HTTP 429 时，工具会在错误消息中显示 x-ve-limit-expires 标头（UTC 日期时间字符串，例如 "2026-04-24 23:49:04 UTC"），以及剩余的 x-ve-limit-avail/x-ve-limit-max 配额 — 请暂停操作，直到该日期时间后再重试。工具会报告服务器发送的错误代码。

整批拒绝（HTTP 4xx 且没有 results[]）表示输入验证失败：folder_id 错误、缺少 instance_id、请求体过大、文件超过 200 个等。请在重试前修正输入。

POST /blob 端点 — 标准上传路径

一个旁路 HTTP 端点，可在 JSON-RPC 通道之外接收原始数据。这完全绕过 MCP 传输限制 — 无需 base64 编码，也没有参数大小限制。适用于任意大小的文本和二进制文件。

获取端点 URL 和会话 ID： create-session 响应会自动包含 blob_upload 对象，其中包含端点 URL、你的会话 ID，以及可直接使用的 curl 命令 — 无需单独调用 blob-info。你也可以独立调用 upload action blob-info。

分块流程（已知大小）：

1. 调用 upload action create-session，并传入 profile_type、profile_id、parent_node_id、filename 和 filesize。响应中包含 blob_upload.curl_command。
2. 使用 curl（或任何 HTTP 客户端）将文件数据及 blob_upload 对象中的标头通过 POST /blob 发送。返回 { "blob_id": "<uuid>", "size": <bytes> }（HTTP 201）。
3. 调用 upload action chunk，并传入 upload_id、chunk_number 和 blob_id: "<blob_id>"。
4. 对更多分块重复步骤 2-3（如果要拆分大文件），然后调用 upload action finalize。 流式流程（大小未知）——首选单次调用路径：
5. 使用文件数据调用 POST /blob（端点和 curl 命令请参阅 blob-info，或任意 create-session 响应中的 blob_upload 对象）。返回 { "blob_id": "<uuid>", "size": <bytes> }。
6. 调用 upload 操作 stream-upload，并传入 profile_type、profile_id、parent_node_id、filename 和 blob_id: "<blob_id>"。可选传入 max_size（请参阅下方指南）、hash 和 hash_algo。
7. 完成——stream-upload 会创建流会话、传输字节并在一次调用中自动完成最终确认。如果流传输失败，会自动取消未完成的会话。

流式流程（显式两步——需要在两次调用之间获取会话 ID 时使用）：

1. 调用 upload 操作 create-session，并传入 profile_type、profile_id、parent_node_id、filename 和 stream=true。filesize 为可选项——可提供 max_size 作为上限（请参阅下方指南），也可省略并使用计划默认值。
2. 使用文件数据调用 POST /blob。返回 { "blob_id": "<uuid>", "size": <bytes> }。
3. 调用 upload 操作 stream，并传入 upload_id 和 blob_id: "<blob_id>"。可选传入 hash 和 hash_algo 以进行验证。
4. 完成——流式上传会自动完成最终确认。无需单独调用 finalize。

max_size 指南——始终多估，不要少估。 max_size 是流请求体的上限。如果实际字节数超过此值，上传会在传输过程中中止，文件会报错。设置得过高不会产生任何影响。**最安全的默认做法：完全省略 max_size，服务器会使用你计划中的文件大小限制。**注意：通过 MCP 进行的流式上传也受 /blob 辅助服务限制（每个 blob 上限为 100 MB）——对于接近或超过 100 MB 的文件，请改用分块流程（create-session → chunk → finalize），并先调用 upload 操作 limits，确认计划中的最大文件大小。

**流式限制：**流会话不能使用 chunk/finalize（会被拒绝并返回 406）。分块会话不能使用 stream（会被拒绝并返回 406）。流式上传只能执行一次——不能向同一会话重复传输。

覆盖现有文件（不要先删除再重新上传）。在同一父文件夹中上传同名文件会原位覆盖现有节点——node_id 会保留，先前内容会成为一个版本条目。要更新文件字节，请使用与现有文件相同的 parent_node_id 和 filename 调用 create-session，然后执行 POST /blob → chunk/stream → finalize。如果文件名可能已变更，或要避免重新解析父文件夹，可在 create-session 中传入 target_node_id，以实现确定性覆盖（服务器会使用 action=update + file_id=<target_node_id>；parent_node_id 会被忽略，且 filename 为可选项，因此可在替换时重命名）。同名覆盖后，可通过 storage 操作 version-list（列出版本）和 version-restore（按 version_id 恢复）找回先前内容。不同版本之间的 node_id 保持不变。完整示例请参阅第 4 节的覆盖文件。

Blob 限制：

• Blob 会在 5 分钟后过期。请及时暂存并使用。
• 每个 blob 首次使用时会被消耗（删除）——无法重复使用。
• Blob 最大大小：100 MB。
• SSE 传输客户端必须在 /blob URL 中添加 ?transport=sse。

事件筛选参考

event 工具的 search 和 summarize 操作接受 category、subcategory 和 event 参数，可用于缩小结果范围。使用这些参数定位特定活动，而无需扫描所有事件。

事件类别

类别	涵盖内容
user	账户创建、更新、删除和头像更改
org	组织生命周期、设置和转移
workspace	工作区创建、更新、归档和文件操作
share	共享生命周期、设置和文件操作
node	文件和文件夹操作（跨配置文件）
ai	AI 聊天、摘要和 RAG 索引
invitation	成员邀请的发送、接受和拒绝
billing	订阅、试用和额度使用
domain	自定义域名配置
apps	应用集成
metadata	元数据提取、模板和键值更新

事件子类别

子类别	涵盖内容
storage	文件／文件夹的添加、移动、复制、删除、恢复和下载
comments	评论的创建、更新、删除、提及、回复和反应
members	在组织、工作区或共享中添加／移除成员
lifecycle	配置文件的创建、更新、删除和归档
settings	配置和偏好设置更改
security	安全相关事件（2FA、密码）
authentication	登录、SSO 和会话事件
ai	AI 处理、聊天和索引
invitations	邀请管理
billing	订阅和付款事件
assets	头像／资源更新
upload	上传会话管理
transfer	跨配置文件文件传输
quickshare	快速共享操作
metadata	元数据操作

常见事件名称

文件操作（工作区）： workspace_storage_file_added、workspace_storage_file_deleted、workspace_storage_file_moved、workspace_storage_file_copied、workspace_storage_file_updated、workspace_storage_file_restored、workspace_storage_folder_created、workspace_storage_folder_deleted、workspace_storage_folder_moved、workspace_storage_download_token_created、workspace_storage_zip_downloaded、workspace_storage_file_version_restored、workspace_storage_link_added

文件操作（共享）： share_storage_file_added、share_storage_file_deleted、share_storage_file_moved、share_storage_file_copied、share_storage_file_updated、share_storage_file_restored、share_storage_folder_created、share_storage_folder_deleted、share_storage_folder_moved、share_storage_download_token_created、share_storage_zip_downloaded

评论： comment_created、comment_updated、comment_deleted、comment_mentioned、comment_replied、comment_reaction

成员关系： added_member_to_org、added_member_to_workspace、added_member_to_share、removed_member_from_org、removed_member_from_workspace、removed_member_from_share、membership_updated

工作区生命周期： workspace_created、workspace_updated、workspace_deleted、workspace_archived、workspace_unarchived

共享生命周期： share_created、share_updated、share_deleted、share_archived、share_unarchived、share_imported_to_workspace

AI： ai_chat_created、ai_chat_new_message、ai_chat_updated、ai_chat_deleted、ai_chat_published、node_ai_summary_created、workspace_ai_share_created

元数据： metadata_kv_update、metadata_kv_delete、metadata_kv_extract、metadata_template_update、metadata_template_delete、metadata_template_settings_update、metadata_view_update、metadata_view_delete、metadata_template_select

快速共享： workspace_quickshare_created、workspace_quickshare_updated、workspace_quickshare_deleted、workspace_quickshare_file_downloaded、workspace_quickshare_file_previewed

邀请： invitation_email_sent、invitation_accepted、invitation_declined

用户： user_created、user_updated、user_deleted、user_email_reset、user_asset_updated

组织： org_created、org_updated、org_closed、org_transfer_token_created、org_transfer_completed

账单： subscription_created、subscription_cancelled、billing_free_trial_ended

示例查询

• 工作区中的最新评论： 使用 event 操作 search，并提供 workspace_id 和 subcategory: "comments"
• 上传到共享空间的文件： 使用 event 操作 search，并提供 share_id 和 event: "share_storage_file_added"
• 组织中的所有成员变更： 使用 event 操作 search，并提供 org_id 和 subcategory: "members"
• 工作区中的 AI 活动： 使用 event 操作 search，并提供 workspace_id 和 category: "ai"
• 谁下载了共享空间中的文件： 使用 event 操作 search，并提供 share_id 和 event: "share_storage_download_token_created"

活动轮询

检测变更的三种机制，按推荐程度从高到低排列：

1. event 操作 activity-poll — 服务会保持连接最多 95 秒，并在发生变更时立即返回。它会返回活动键（例如 ai_chat:{chatId}、storage、members）以及供下一次轮询使用的 lastactivity 时间戳。适用于任何“等待某事发生”的场景，包括 AI 聊天完成。
2. WebSocket — 用于实时推送事件，最适合实时 UI。
3. event 操作 activity-list — 按需获取近期活动事件。需要一次性快照而非持续监控时使用。

为何重要： 不要在紧密循环中轮询详情端点（例如 ai 操作 message-read）。请改用 event 操作 activity-poll 检测变更，然后只获取一次详情。

AI 消息完成

ai 操作 message-read（使用 profile_type: "workspace" 或 "share"）内置轮询功能（最多 15 次尝试，间隔 2 秒）。如果在该时间段后响应仍在处理中，请改用 event 操作 activity-poll，并传入工作区或共享 ID，而不要循环调用读取操作：

1. 调用 event 操作 activity-poll，并将 entity_id 设为工作区／共享 ID。
2. 当响应包含与您的聊天匹配的 ai_chat:{chatId} 键时，调用一次 ai 操作 message-read，以获取已完成的响应。

活动轮询工作流

1. 发起 API 调用（例如 ai 操作 chat-create），并记下响应中的 server_date 字段。
2. 调用 event 操作 activity-poll，并传入 entity_id（工作区或共享 ID），同时将 lastactivity 设为 server_date 的值。
3. 服务端会保持连接。当发生变化（或等待时间结束）时，服务端会返回活动键。
4. 检查这些键以确定发生了什么变化，然后获取相关详情（例如 ai 操作 message-read、storage 操作 list）。
5. 在下一次轮询调用中，使用轮询响应中的新 lastactivity 值（或最新的 server_date）。根据需要重复此过程。

垃圾桶、删除和彻底清除

• storage 操作 delete（使用 profile_type: "workspace" 或 "share"）会将项目移至垃圾桶。项目可以恢复。
• storage 操作 restore 可从垃圾桶中恢复项目。
• storage 操作 purge 会永久且不可逆地删除垃圾桶中的项目。

调用彻底清除操作前，务必先征得用户确认。

节点类型

存储节点可以是文件、文件夹、笔记或链接。类型会在存储详情响应中注明。笔记是 Markdown 内容节点（与其他节点类型不同——type: "note"，而不是 type: "file"——尽管这两种节点都可以包含 Markdown 文本），通过 workspace 操作 create-note 创建、通过 workspace 操作 read-note 读取，并通过 workspace 操作 update-note 更新。链接是通过 storage 操作 add-link 创建的共享引用节点。

文本内容和换行符

所有文本内容（笔记、评论、工作日志、文件上传内容、描述）都必须使用 Unix 风格的换行符（\n，U+000A）。前端会在保存前将所有换行符统一为 \n——Windows 风格的 \r\n（CRLF）和旧版 Mac 风格的 \r（CR）会自动转换。Agent 应仅使用 \n，以避免内容比较和显示不一致。

编码规则：

• 换行符： 使用 \n（U+000A）。切勿单独发送 \r\n 或 \r。
• 允许的控制字符： 只有 \t（U+0009）、\n（U+000A）和 \r（U+000D）能够通过服务端清理。所有其他 Unicode 控制字符（\p{C}）都会被移除。
• Markdown 中的空行： 使用两个连续的 \n 字符（\n\n）分隔段落。不要使用不换行空格（U+00A0）或其他空白字符作为占位符。
• 末尾换行符： 内容末尾可以有 \n，也可以没有。不要假定必须采用其中一种约定——两种都有效。

此规则适用于：workspace 操作 create-note 和 update-note、upload 操作 chunk（使用 content 参数）、comment 操作 add、worklog 操作 append 和 interject，以及任何接受自由文本或 Markdown 内容的其他工具。

错误模式

API 调用失败时会抛出包含两个字段的错误：code（唯一的数字错误 ID）和 text（便于人类阅读的说明）。工具会在 MCP 响应中将这些内容显示为错误文本。常见的 HTTP 状态码包括 401（未授权）、403（禁止访问）、404（未找到）和 429（请求频率受限）。

403 和受限范围的密钥： 如果使用受限范围的 API 密钥（或受限范围的 OAuth 令牌），403 错误通常表示目标资源不在密钥获准的范围内，而不是角色或权限问题。检查 auth 操作的 status，并查看 scopes_detail，了解密钥可以访问哪些实体。受限范围的密钥只能访问获准的特定组织、工作区或共享项，其他所有端点都会返回 403。

只读范围和工具筛选： 使用只读范围的密钥进行身份验证时（所有实体授权均为 :r 访问模式），服务会自动筛选每个工具，仅公开读取操作。写入操作会从操作枚举、说明和注释中移除（注释会变为 readOnlyHint=true、destructiveHint=false）。在只读会话中尝试执行写入操作会返回架构验证错误，而不是 403。使用读写密钥（或不受限范围的密钥）重新进行身份验证后，会恢复完整的操作集。

会话状态

身份验证令牌、用户 ID、电子邮件、令牌过期时间和刷新令牌都会保存在服务会话中。无需在工具调用之间传递令牌。同一 MCP 连接中的多次工具调用之间，会话会持续有效。OAuth 会话会自动静默刷新——系统会通过内部定时器在访问令牌过期前续期，因此会话最长可在无需用户干预的情况下持续 30 天（即刷新令牌的有效期）。

面向用户的 URL

MCP 工具通过 API 管理数据，但用户通过 Web 浏览器访问 Fast.io。始终使用工具响应中的 web_url 字段——这是可直接使用、可点击的资源 URL。创建或引用工作区、共享项、文件、笔记或传输时，请在响应中附上此 URL。用户无法直接查看 API 响应；你提供的 URL 是他们访问内容的方式。仅在 web_url 缺失时，才使用以下 URL 格式作为备用（例如，共享上下文存储操作）：

自动提供 web_url 字段。 所有返回实体的工具响应都包含 web_url 字段——这是可直接使用、面向用户的资源 URL。绝不要手动构造 URL——始终使用工具响应中的 web_url 字段。 以下操作会返回此字段：组织列表/详情/创建/更新/公开详情/发现-*、组织工作区列表/共享项列表、工作区列表/详情/更新/可用项/共享项列表、共享项列表/详情/创建/更新/公开详情/可用项、存储列表/详情/搜索/回收站列表/复制/移动/重命名/恢复/添加文件/创建文件夹/版本列表/版本恢复/预览 URL/预览转换、快速共享创建/获取/列表、上传完成、下载文件 URL/快速共享详情、AI 聊天创建/详情/列表、传输令牌创建/列表，以及笔记创建/更新。仅在 web_url 缺失时，才使用以下 URL 格式作为备用（例如，共享上下文存储操作）。

组织的 domain 值会成为子域名："acme" → https://acme.fast.io/。基础域名 go.fast.io 用于无需组织上下文的公开路由。

已认证链接（需要登录）

人类需要的内容	URL 模式
工作区根目录	https://{domain}.fast.io/workspace/{folder_name}/storage/root
指定文件夹	https://{domain}.fast.io/workspace/{folder_name}/storage/{node_id}
文件预览	https://{domain}.fast.io/workspace/{folder_name}/preview/{node_id}
带指定评论的文件	https://{domain}.fast.io/workspace/{folder_name}/preview/{node_id}?comment={comment_id}
视频/音频文件的指定时间点	https://{domain}.fast.io/workspace/{folder_name}/preview/{node_id}?t={seconds}
PDF 文件的指定页码	https://{domain}.fast.io/workspace/{folder_name}/preview/{node_id}?p={page_num}
工作区中的 AI 聊天	https://{domain}.fast.io/workspace/{folder_name}/storage/root?chat={chat_id}
工作区中的笔记	https://{domain}.fast.io/workspace/{folder_name}/storage/root?note={note_id}
笔记预览	https://{domain}.fast.io/workspace/{folder_name}/preview/{note_id}
浏览工作区	https://{domain}.fast.io/browse-workspaces
编辑共享设置	https://{domain}.fast.io/workspace/{folder_name}/share/{custom_name}
组织设置	https://{domain}.fast.io/settings
账单	https://{domain}.fast.io/settings/billing

公共链接（无需登录）

人类需要的内容	URL 模式
公共共享	https://go.fast.io/shared/{custom_name}/{title-slug}
带组织品牌的共享	https://{domain}.fast.io/shared/{custom_name}/{title-slug}
共享中的文件	https://go.fast.io/shared/{custom_name}/{title-slug}/preview/{node_id}
共享中带评论的文件	https://go.fast.io/shared/{custom_name}/{title-slug}/preview/{node_id}?comment={comment_id}
QuickShare	https://go.fast.io/quickshare/{quickshare_id}
认领组织转移	https://go.fast.io/claim?token={transfer_token}
入门引导	https://go.fast.io/onboarding 或 https://go.fast.io/onboarding?orgId={org_id}&orgDomain={domain}

各值的来源

值	API 来源
domain	org 操作 create 或 details 的响应
folder_name	org 操作 create-workspace 或 workspace 操作 details 的响应
node_id	storage 操作 list、create-folder 或 add-file 的响应
custom_name	share 操作 create 或 details 的响应（{title-slug} 仅用于美观，单凭 custom_name 即可解析共享）
quickshare_id	workspace 操作 quickshare-create 的响应
transfer_token	org 操作 transfer-token-create 的响应
chat_id	ai 操作 chat-create 或 chat-list 的响应
note_id	workspace 操作 create-note 或 storage 操作 list 的响应（节点不透明 ID）
comment_id	comment 操作 add 或 list 的响应
org_id	org 操作 create 或 list 的响应

在以下情况下，务必向人类提供 URL：

• 创建了工作区？ 在回复中附上工作区 URL。例如：https://acme.fast.io/workspace/q4-reports/storage/root
• 创建或配置了共享？ 附上共享 URL。例如：https://go.fast.io/shared/q4-financials/Q4-Financial-Report——这是人类（或其接收者）将打开的品牌页面。
• 生成了转移令牌？ 附上认领 URL。例如：https://go.fast.io/claim?token=abc123——这是人类认领所有权的唯一方式。
• 上传了文件或创建了文件夹？ 附上指向相关文件夹的工作区 URL，方便人类查看你创建的内容。
• 人类问“我在哪里可以看到这个？” 使用已有的 API 响应数据构造 URL 并提供。

重要： domain 是组织的域名字符串（例如 acme），不是数字组织 ID。folder_name 是工作区的文件夹名称字符串（例如 q4-reports），不是数字工作区 ID。这两个值均由各自的 API 工具返回。

响应提示（_next、_warnings 和 _recovery）

工作流关键工具的响应包含 _next 字段——一个简短数组，其中列出建议的后续操作，并使用精确的工具名和操作名。请使用这些提示来指导工作流，而不要猜测下一步该做什么。示例：

{
  "workspace_id": "...",
  "web_url": "https://acme.fast.io/workspace/q4-reports/storage/root",
  "_next": [
    "Upload files: upload action create-session + blob or web-import",
    "Create a share: share action create",
    "Query with AI: ai action chat-create"
  ]
}

_warnings 会出现在具有破坏性、不可逆或可能存在问题的操作中。继续操作前务必阅读警告——它们会指出永久性后果或重要注意事项。包含 _warnings 的操作：storage purge、storage bulk copy/move/delete/restore（可能发生部分失败）、workspace details（intelligence=false）、workspace update（intelligence=false）、workspace archive/delete、org close、org billing-create、share delete、share archive、share update（type change）、ai chat-delete、download file-url（令牌过期）、download zip-url（需要身份验证）、org transfer-token-create。

错误响应（isError: true）中会包含 _recovery 提示。它会根据 HTTP 状态码和错误消息模式匹配提供恢复操作。错误消息还会包含操作上下文（例如，“during: org create”），帮助定位失败操作。

HTTP 状态	恢复方法
400	检查必需参数和 ID 格式
401	重新进行身份验证：使用 auth 操作 signin 或 set-api-key。如果错误提示“Session expired”，则表示先前的会话已超时；请重新进行身份验证以继续。如果提示“Not authenticated”，则表示尚未建立会话。
402	额度已用尽——检查余额：使用 org 操作 limits
403	权限被拒绝——检查角色：使用 org 操作 details
404	未找到资源——验证 ID，使用 list 操作查找有效 ID
409	冲突——资源可能已存在
413	请求过大——减小文件或分块大小
422	验证错误——检查字段格式和限制条件
429	请求过于频繁——等待 2-4s 后使用指数退避重试
500/503	服务端错误——等待 2-5 秒后重试

基于模式的恢复：错误消息还会与常见模式进行匹配（例如，“email not verified”、“workspace not found”、“intelligence disabled”），即使 HTTP 状态码较为通用，也会提供具体的恢复步骤。

工作区详情响应中包含 ai_capabilities，用于显示根据工作区智能设置可用的 AI 模式：

• 智能功能开启：files_scope、folders_scope、files_attach（支持完整的 RAG 和索引文档搜索）
• 智能功能关闭：仅支持 files_attach（最多 20 个文件、200 MB，不进行 RAG 索引）

当文件包含 AI 处理状态时，storage list 和 search 响应中会包含 _ai_state_legend。状态包括：indexed（已建立向量索引，可进行 RAG 搜索——智能功能开启）、ready（摘要可用，可附加，但未建立向量索引——智能功能关闭）、pending（排队中）、inprogress（处理中）、disabled（未进行 AI 处理）、failed（需要重新上传）。其中还包含 _attach_field，用于说明 ai.attach 布尔值——使用 files_attach 前请先检查此标记。

特定响应中会通过 _context 提供上下文元数据。目前，当添加评论涉及锚定内容时会使用该字段，并提供 anchor_formats，说明图像区域、视频/音频时间戳和 PDF 页面所需的格式。

现在所有工具操作都会包含 _next 提示。 每个成功的工具响应都会包含与上下文相关的后续步骤建议。关键工作流转换：auth → org list/create、org create → workspace create、workspace create → upload/share/AI、upload → AI chat/comment/download、share create → add files/members、AI chat create → message read。提示包含精确的工具名、操作名，以及当前响应中的相关 ID。

工具注释： 工具包含 MCP 注释提示——readOnlyHint、destructiveHint、idempotentHint（download、event）和 openWorldHint（org、user、workspace、share、storage）——帮助客户端无需查阅文档即可了解工具行为。 破坏性操作标签： 执行不可逆操作（删除、清除、关闭等）的操作会在工具列表的描述行末尾追加 [DESTRUCTIVE]。这是对 destructiveHint 注解的文本级补充信号，可用于区分安全的写入操作和无法撤销的操作。

资源补全与列表： 工作区和共享项的下载资源模板同时支持动态列表（resources/list）和制表符补全（completion/complete）。动态列表会在客户端的资源选择器中显示所有工作区和共享项的根目录文件。制表符补全会在你输入时提供有效的工作区和共享项 ID。

未经身份验证的工具

以下操作无需会话即可使用：auth 操作 signin、signup、set-api-key、pkce-login、email-check、password-reset-request、password-reset；以及 download 操作 quickshare-details。

响应格式

所有工具响应均为 GitHub 风格的 Markdown（CommonMark + 表格）。没有 JSON 信封。

对于大多数工具，客户端会根据 API 的 JSON 信封，按照与平台 ?output=markdown 修饰符相同的规则渲染 Markdown，因此直通响应和渲染后的响应看起来完全相同。

部分列表/活动操作还接受 detail 参数，以便在详细程度与令牌成本之间进行权衡：

工具	操作	接受 detail	默认值
event	search	terse | standard | full	standard
event	activity-list	terse | standard | full	standard
event	activity-poll	terse | standard | full	terse
comment	list	terse | standard | full	standard

各级别返回的内容（累积式——每个级别都会在前一级的基础上增加内容）：

• terse：仅包含标识符、主要标签和时间戳，足以用于导航或推进游标。
• standard：terse + 大多数列表视图会显示的操作上下文（操作者、描述、标记、计数）。
• full：standard + 长篇字段（完整摘要、元数据、架构详情）。等同于省略 detail。

对于 storage/share/org/workspace 列表/搜索操作（以及任何其他返回文件或实体列表的操作），响应同样是 Markdown，并在本地渲染，但目前不接受 detail 参数。这些端点默认返回 full 格式；可通过其他操作参数传入所需的筛选条件（例如 search 查询、limit/offset）。

与通用 Markdown 输出不同，tasks/todo/approval/worklog 工具仍接受 format: 'md'，并会触发专门的领域渲染器（复选框列表、时间线、状态表格），这与此处描述的信封式 Markdown 不同。两者都会生成 Markdown，但格式各异。

---

8. MCP Apps（交互式 UI 小部件）

Fast.io MCP Server 内含交互式 HTML5 小部件，可在 Agent 对话中直接呈现丰富的 UI。小部件通过工具调用与 MCP 服务通信，并显示文件浏览器、仪表板、工作流管理器等。

可用组件

组件	资源 URI	描述
文件选择器	widget://file-picker	浏览并选择文件以附加到对话中 — 浏览文件夹、搜索、预览并选择要提供给 Agent 的文件。还支持在工作区和共享空间中管理文件（上传、移动、复制、删除）
工作区选择器	widget://workspace-picker	组织／工作区／共享空间选择，支持搜索、4 步工作区创建向导和 5 步共享空间创建向导
文件查看器	widget://file-viewer	统一的文件预览（图像、PDF、视频、音频、代码、电子表格），并提供信息面板（详情、版本、AI 摘要、元数据）
工作流管理器	widget://workflow	任务看板、任务详情、审批面板、待办事项清单、工作日志查看器
评论面板	widget://comments	线程式评论、回应、锚定评论（图像区域、时间戳）
上传器	widget://uploader	通过拖放将文件上传到工作区或共享空间，支持通过 POST /blob sidecar 分块上传，也支持导入网页 URL，并实时跟踪进度

上传器组件

上传器组件提供 4 步文件上传流程：

1. 选择目标位置 -- 选择一个组织，然后选择工作区或共享空间，之后可选择进入子文件夹
2. 选择文件 -- 将文件拖放到组件上，或使用文件选择器按钮浏览本地文件
3. 上传并查看进度 -- 文件会自动上传，并显示实时进度条。所有文件均使用分块上传（create-session、POST /blob、使用 blob_id 分块、finalize）。网页 URL 使用 web-import
4. 在聊天中引用 -- 上传完成后，点击“在聊天中引用”，将上传的文件附加到与 Agent 的对话中，以便进一步讨论或进行 AI 分析

该组件通过 MCP 桥接使用 upload 工具（操作：create-session、chunk、finalize、web-import、status、cancel、limits、extensions）和 storage 工具（操作：list）。

通过提示词启动： 在桌面 MCP 客户端中使用 App: Upload Files 提示词。

通过工具启动：

apps action launch app_id uploader profile_type workspace profile_id <workspace_id>

使用 Apps 工具

apps 工具提供组件发现和启动功能：

1. 列出应用： apps 操作 list -- 返回所有可用组件及其元数据
2. 应用详情： 使用 app_id 调用 apps 操作 details -- 返回特定组件的完整元数据
3. 启动应用： 使用 app_id、profile_type（或 context_type）、profile_id（或 context_id）调用 apps 操作 launch -- 在指定上下文中打开组件
4. 查找工具对应的应用： 使用 tool_name 调用 apps 操作 get-tool-apps -- 将工具映射到对应组件

组件上下文

所有组件都接受工作区或共享空间上下文：

• profile_type: "workspace" + profile_id: "<workspace_id>"
• profile_type: "share" + profile_id: "<share_id>"

设计系统

组件使用与 Fast.io 前端一致的共享设计系统：

• 支持浅色和深色模式（遵循系统偏好或显式的 data-theme 属性）
• 字体、间距、颜色和图标保持一致，均源自前端主题
• 响应式布局（桌面、平板、移动设备断点）

示例：启动文件选择器

apps action launch app_id file-picker profile_type workspace profile_id <workspace_id>

示例：查找用于存储操作的组件

apps action get-tool-apps tool_name storage

---

9. 完整工具参考

全部 19 个工具及其操作按功能领域整理。每个条目都显示操作名称及其描述。工作流工具（task、worklog、approval、todo）要求目标工作区或共享空间已启用工作流。

auth

signin -- 使用邮箱和密码登录 Fast.io。返回 JWT 身份验证令牌。如果账户启用了双重身份验证，则在调用 2fa-verify 之前，令牌的作用范围会受到限制。令牌会自动存储在会话中。 set-api-key — 使用 Fast.io API 密钥进行身份验证。密钥会通过 API 验证并存储在 MCP 会话中，之后所有工具调用都会自动通过身份验证。默认情况下，密钥拥有与账户所有者相同的权限。范围受限的密钥只能访问特定实体（使用与 OAuth 令牌相同的范围系统），超出授权范围的操作会返回 403。检测到范围受限的密钥时，响应会包含 scopes_detail，显示可访问的实体。未设定范围的密钥不会过期，除非被撤销；范围受限的密钥可以设置可选的过期时间。

signup — 创建新的 Fast.io Agent 账户（agent=true），然后自动登录。将 account_type 设为 "agent"，并分配免费的 Agent 方案。注册后需要验证电子邮件：调用 email-verify 发送验证码，然后再次调用并提供验证码以完成验证。大多数端点都要求电子邮件已验证。注册本身无需身份验证。

check — 检查当前会话令牌是否仍然有效。返回与该令牌关联的用户 ID。

session — 获取已通过身份验证用户的当前会话信息，包括姓名、电子邮件和账户标志等个人资料详情。

signout — 清除已存储的会话以退出登录。如果当前已通过身份验证，会先验证令牌。

2fa-verify — 提交 2FA 验证码以完成双重身份验证。在 signin 返回 two_factor_required: true 后调用此项。新的全范围令牌会自动存储。

email-check — 提供提示，说明某个电子邮件地址是否可能可用于注册。结果不具权威性： 已观察到 available: false 的响应，但 signup 随后仍接受了该电子邮件地址（可能是上游 POST /user/email/ 端点的响应缓存或域名特定策略所致）。无论 email-check 的结果如何，都应继续调用 signup，并以注册错误为准。无需身份验证。

password-reset-request — 请求发送密码重置邮件。出于安全考虑，始终返回成功（不会透露该电子邮件地址是否存在）。无需身份验证。

password-reset — 使用通过电子邮件收到的重置码设置新密码。无需身份验证。

email-verify — 发送或验证电子邮件验证码。省略 email_token 时会发送新验证码。提供 email_token 时会验证验证码，并将电子邮件标记为已验证。

status — 检查本地会话状态。不会调用 API。返回用户是否已通过身份验证；如果已通过身份验证，还会返回其 user_id、电子邮件、auth_method（"api_key"、"jwt" 或 "oauth"）、令牌过期时间、scopes（原始字符串）、scopes_detail（包含实体名称、域名和父级层级的完整数组；如果尚未获取则为 null），以及 agent_name（如果已设置）。

pkce-login — 启动基于浏览器的 PKCE 登录流程。返回供用户在浏览器中打开的 URL。登录并批准访问后，浏览器会显示授权码。用户复制该码并提供给 pkce-complete 以完成登录。不会通过 Agent 发送密码。可选参数：scope_type（默认为 "user"，表示完整访问权限；范围受限的访问权限可使用 "org"、"workspace"、"all_orgs"、"all_workspaces" 或 "all_shares"），agent_name（显示在批准页面和审计日志中；默认为 MCP 客户端名称）。

pkce-complete — 通过将授权码交换为访问令牌来完成 PKCE 登录流程。在用户于浏览器中批准访问并从页面复制授权码后调用此项。令牌会自动存储在会话中。如果获准的是范围受限的访问权限，响应会包含 scopes（已授权范围字符串组成的 JSON 数组，例如 "org:123:rw"）和 agent_name。 api-key-create —— 创建新的持久化 API 密钥。完整密钥值仅在创建时返回一次，请妥善保管。可选参数：name（备注/标签）、scopes（JSON 作用域字符串数组，例如 ["org:123:rw", "workspace:456:r"]，用于限制访问；省略则拥有完全访问权限）、agent_name（Agent/应用名称，最多 128 个字符）、key_expires（ISO 8601 到期日期时间；省略则永不过期）、token（2FA 验证码；账户启用 2FA 时必填，使用 API 密钥进行身份验证时无需提供）。带作用域的密钥使用与 v2.0 JWT 令牌相同的作用域系统。

api-key-update —— 更新现有 API 密钥的元数据。需要提供 key_id。可选参数：name（备注/标签）、scopes（JSON 作用域数组；发送空字符串以清除并恢复完全访问权限）、agent_name（发送空字符串以清除）、key_expires（发送空字符串以清除到期时间）。仅更新指定字段。

api-key-list —— 列出已通过身份验证的用户的所有 API 密钥。密钥值会被遮蔽（仅显示末尾 4 个字符）。响应中会包含每个密钥的 scopes、agent_name 和 expires 字段。

api-key-get —— 获取指定 API 密钥的详细信息。密钥值会被遮蔽。响应中会包含 scopes、agent_name 和 expires 字段。

api-key-delete —— 撤销（删除）API 密钥。此操作无法撤销。可选参数：token（2FA 验证码；账户启用 2FA 时必填，使用 API 密钥进行身份验证时无需提供）。

2fa-status —— 获取当前双重身份验证配置状态（已启用、未验证或已禁用）。

2fa-enable —— 在指定渠道启用双重身份验证。对于 TOTP，会返回用于显示二维码的绑定 URI。在调用 2fa-verify-setup 之前，账户将处于“未验证”状态。

2fa-disable —— 禁用（移除）账户的双重身份验证。若 2FA 处于已启用（已验证）状态，则需要有效的 2FA 验证码进行确认。

2fa-send —— 通过短信、语音电话或 WhatsApp 向用户的手机发送 2FA 验证码。

2fa-verify-setup —— 验证 2FA 设置验证码，以确认完成注册。将 2FA 从“未验证”状态切换为“已启用”。

oauth-list —— 列出已通过身份验证的用户的所有活跃 OAuth 会话。

oauth-details —— 获取指定 OAuth 会话的详细信息。

oauth-revoke —— 撤销指定的 OAuth 会话（将该设备登出）。

oauth-revoke-all —— 撤销所有 OAuth 会话。可选择排除当前会话，以实现“登出其他所有设备”。

用户

me — 获取当前已认证用户的个人资料详情。

update — 更新当前用户的个人资料（姓名、电子邮件等）。

search-contacts — 按姓名或电子邮件子字符串搜索个人联系人列表（曾通过之前的邀请、共享或聊天提及与您互动过的人）。返回扁平的 {email: name} 映射——不包含 user_id，也没有上下文范围。对于工作区、共享或组织成员，请使用 workspace action=members、share action=members 或 org action=members。

close — 关闭/删除当前用户账户（需要通过电子邮件确认）。

details-by-id — 根据用户 ID 获取其他用户的公开个人资料详情。

profiles — 检查用户有权访问哪些个人资料类型（组织、工作区、共享）。

allowed — 检查用户所在国家/地区是否允许创建共享和组织。

org-limits — 获取免费创建组织的资格、限制和冷却状态。

list-shares — 列出当前用户作为成员加入的所有共享。

invitation-list — 列出当前用户的所有待处理邀请。

invitation-details — 根据邀请 ID 或密钥获取特定邀请的详情。

accept-all-invitations — 一次性接受所有待处理邀请。

asset-upload — 上传用户资源（例如个人资料照片）。提供纯文本内容或 base64 编码的 content_base64（二者不可同时提供）。

asset-delete — 删除用户资源（例如个人资料照片）。

asset-types — 列出用户可用的资源类型。

asset-list — 列出所有用户资源。

instructions-get — 读取您在 /user/me/instructions/ 中的个人 AI 指令槽位。首次读取尚未写入的槽位时，会返回 content: "" 和空时间戳（而不是 404）。仅限本人使用——没有 me 范围变体。

instructions-set — 替换您的个人 AI 指令（完整替换，最多 65536 字节 UTF-8）。返回写入后的负载——无需再调用 instructions-get。

instructions-clear — 软清除您的个人 AI 指令（保留审计记录）。可幂等执行。

org

list — 列出内部组织（用户是其直接成员的组织，member: true）。每个组织都包含 web_url。返回成员组织及其订阅状态、用户权限和套餐信息。非管理员成员只能看到订阅有效的组织。不包括外部组织——请使用 discover-external 获取外部组织。

details — 获取组织的详细信息。返回 web_url。返回的字段因调用者的角色而异：所有者可查看加密密钥和存储配置，管理员可查看账单和权限，成员可查看基本信息。

members — 列出组织的所有成员及其 ID、电子邮件、姓名和权限级别。

invite-member — 通过电子邮件邀请用户加入组织。电子邮件会放在 URL 路径中（而不是请求正文中）。如果用户已有 Fast.io 账户，则会直接添加；否则会发送电子邮件邀请。无法将用户添加为所有者。

remove-member — 从组织中移除成员。需要具有由组织的 perm_member_manage 设置配置的成员管理权限。

update-member-role — 更新组织中成员的角色/权限。无法将角色设为 'owner'——请改用 transfer-ownership。

limits — 获取组织套餐限制和额度使用情况。返回额度限制、使用统计、计费周期、试用信息和运行速率预测。需要管理员或所有者角色。

list-workspaces — 列出当前用户可以访问的组织工作区。每个工作区都包含 web_url。所有者和管理员可查看所有工作区；成员可查看符合加入权限设置的工作区。

list-shares — 列出当前用户可访问的共享。每个共享都包含 web_url。返回所有共享，包括上级组织和工作区信息。使用响应中的 parent_org 来识别属于特定组织的共享。 create -- 在“agent”计费计划下创建新组织。需要提供 domain（2-63 个字符，由小写字母、数字和连字符组成）和 name（3-100 个字符，不含控制字符）。经过身份验证的用户将成为所有者。系统会自动创建存储实例和 agent 计划订阅（免费，50 GB，每月 5,000 个点数）。返回新组织和试用状态。

update -- 更新组织详情。返回 web_url。仅更改已提供的字段。支持身份信息、品牌设置、社交链接、权限和账单邮箱。需要管理员或所有者角色。

close -- 关闭/删除组织。取消任何有效订阅并启动删除流程。需要所有者角色。confirm 字段必须与组织域名或组织 ID 匹配。

public-details -- 获取组织的公开详情。返回 web_url。无需成为组织成员——仅返回公开级别的字段（名称、域名、徽标、强调色）。组织必须存在且未关闭或暂停。

create-workspace -- 在组织内创建新工作区。返回 web_url。根据组织的计费计划检查工作区功能是否可用以及创建限制。创建者将成为工作区所有者。命名空间： 工作区 folder_name 在整个平台上必须唯一。如果请求的名称已被占用且不包含连字符，服务端会自动为其添加组织 ID 前缀（例如，reports → 3587676312889739297-reports）。包含连字符的名称将按原样发送。响应中会返回最终的 folder_name。

billing-plans -- 列出可用的计费计划及其定价、功能和计划默认值。返回创建订阅所需的计划 ID。

billing-create -- 创建新订阅或更新现有订阅。对于新订阅，会创建 Stripe Setup Intent。对于现有订阅，会更新计划。需要管理员或所有者角色。

billing-cancel -- 取消组织的订阅。需要所有者角色。取消某些计划可能会导致组织关闭。

billing-details -- 获取全面的账单和订阅详情，包括 Stripe 客户信息、订阅状态、Setup Intent、Payment Intent 和计划信息。需要管理员或所有者角色。

billing-activate -- 激活计费计划（仅限开发环境）。模拟 Stripe 付款设置，并使用测试付款方式激活订阅。

billing-reset -- 重置账单状态（仅限开发环境）。删除 Stripe 客户并移除订阅者标记。

billing-members -- 列出可计费成员及其工作区成员关系。显示组织正在为哪些用户付费。需要管理员或所有者角色。

billing-meters -- 获取用量计量器的时间序列数据（存储、传输、AI 等）。返回分组的数据点以及成本和点数计算结果。需要管理员或所有者角色。

leave -- 离开组织。移除当前用户自己的成员身份。所有者不能离开，必须先转让所有权或关闭组织。

member-details -- 获取组织中特定用户的详细成员信息，包括权限、邀请状态、通知偏好和有效期。

transfer-ownership -- 将组织所有权转让给另一位成员。当前所有者将降级为管理员。需要所有者角色。

transfer-token-create -- 为组织创建转让令牌（有效期为 72 小时）。将申领 URL https://go.fast.io/claim?token=<token> 发送给真人。用于移交组织，或在 agent 计划上遇到 402 Payment Required 错误时使用。需要所有者角色。

transfer-token-list -- 列出组织的所有有效转让令牌。每个令牌都包含 web_url（申领 URL）。需要所有者角色。

transfer-token-delete -- 删除（撤销）待处理的转让令牌。需要所有者角色。 transfer-claim -- 使用转移令牌认领组织。通过身份验证的用户将成为新所有者，原所有者则降级为管理员。

invitations-list -- 列出组织的所有待处理邀请。可按邀请状态筛选。需要具备任意组织成员身份。

invitation-update -- 更新组织的现有邀请。可更改状态、权限或过期时间。

invitation-delete -- 撤销/删除组织的邀请。

join -- 通过邀请或授权域名自动加入组织。可选提供邀请密钥和操作（接受/拒绝）。

asset-upload -- 上传组织资源（例如徽标、横幅）。提供纯文本内容或 base64 编码的 file_base64（二者不可同时提供）。需要管理员或所有者角色。

asset-delete -- 删除组织中的资源。需要管理员或所有者角色。

asset-types -- 列出组织可用的资源类型。

asset-list -- 列出组织的所有资源。

discover-all -- 列出所有可访问的组织（已加入 + 已受邀）。每个组织都包含 web_url。返回的组织数据包含表示用户关系的 user_status。

discover-available -- 列出可加入的组织。每个组织都包含 web_url。排除用户已加入的组织。

discover-check-domain -- 检查组织域名是否可用。验证格式、检查保留名称，并检查是否已有同名域名。

discover-external -- 列出外部组织（member: false）。每个组织都包含 web_url。用户只能通过工作区成员身份访问这些组织，而非作为组织的直接成员。常见情况是有人邀请 Agent 加入工作区，但没有邀请其加入组织。请参阅 Organizations 部分中的 内部组织与外部组织。

custom-domain-get -- 获取组织当前的自定义域名。返回 hostname、status（pending 或 active）和 cname_target；如果未配置自定义域名，则返回 { hostname: null }。任何组织成员都可以读取。

custom-domain-create -- 为组织添加自定义域名。需要提供 hostname（有效的 FQDN，例如 files.acme.com）。返回创建的域名，其中包含 status: "pending" 和 cname_target。客户必须添加 DNS CNAME 记录，将 hostname 指向 cname_target。需要管理员或所有者角色，以及 Pro 或 Business 方案。

custom-domain-delete -- 移除组织的自定义域名。现有 TLS 证书会自然过期（最长需 90 天）。需要管理员或所有者角色。不受方案限制——降级方案的组织仍可移除其域名。

custom-domain-validate -- 对组织的自定义域名执行实时 DNS 验证。返回 hostname、dns_valid（布尔值）、status、cname_target 和 cname_found。如果 DNS 配置正确且域名处于待处理状态，系统会自动激活域名。任何组织成员都可以调用此操作。

instructions-get -- 读取组织的 AI 指令。scope: "profile"（默认）读取 /org/{org_id}/instructions/ 中的组织级存储项。scope: "me" 读取 /org/{org_id}/instructions/me/ 中的用户级存储项。首次读取尚未写入的存储项时，会返回 content: "" 和 null 时间戳（而非 404）。各作用域的读取权限遵循写入权限所述的相同身份验证条件——请参阅第 5 节的 org 引用块。

instructions-set -- 替换组织的 AI 指令（完全替换，最多 65536 字节 UTF-8）。scope: "profile"（默认）需要所有者/管理员权限（非管理员会收到 403 错误代码 1680）。scope: "me" 会写入用户级存储项（任何成员均可）。两个作用域彼此独立，服务器端不会合并；如需合并视图，请在客户端拼接。

instructions-clear -- 软清除组织的 AI 指令（保留审计记录）。scope: "profile"（默认）需要所有者/管理员权限；scope: "me" 会清除用户级存储项。此操作具有幂等性。

工作区

list -- 列出用户在所有组织中可访问的所有工作区。每个工作区都包含 web_url。 details -- 获取特定工作区的详细信息。返回 web_url。

update -- 更新工作区设置，例如名称、描述、品牌标识和权限。返回 web_url。

delete -- 永久关闭（软删除）工作区。需要 Owner 权限并确认。

archive -- 归档工作区（阻止修改，但保留数据）。需要 Admin 或更高权限。

unarchive -- 将已归档的工作区恢复为活跃状态。需要 Admin 或更高权限。

members -- 列出工作区的所有成员及其角色和状态。包括活跃成员和待加入成员。待加入成员的 status 为 "pending"，且有一个 invite 对象（{id, created, expires}——expires 的格式为 YYYY-MM-DD HH:MM:SS UTC，如果没有过期时间则为 null）；活跃成员的 status 为 "active"，且 invite: null。待加入成员是尚未注册的受邀用户——他们是任务、审批和待办事项的有效分配对象。使用 invite.id 和 invitation 操作 delete 可取消待加入成员的邀请。

list-shares -- 列出工作区中的所有分享，可按归档状态筛选。每个分享都包含 web_url。

import-share -- 将用户拥有的分享导入工作区。你必须是该分享的唯一所有者。

available -- 列出当前用户可以加入但尚未加入的工作区。每个工作区都包含 web_url。

check-name -- 检查工作区文件夹名称是否可用。工作区名称必须全局唯一。如果名称已被占用，可传入可选参数 check_org_id，以获取带组织 ID 前缀的替代名称建议（例如 3587676312889739297-reports）。

create-note -- 在工作区存储中创建新的 Markdown 笔记。必须且只能传入 content（内联 Markdown）或 blob_id（来自 POST /blob）之一——对于大于约 10 KB 的笔记，建议使用 blob_id，以避免 MCP 传输开销。返回 web_url（笔记预览链接）。写入内容达到或超过 80 KB 时会附带一条非致命警告提示，建议在达到 100 KB 上限前拆分到新文件。

update-note -- 更新笔记的 Markdown 内容和/或名称（必须至少提供 name、content 或 blob_id 之一）。必须且只能传入 content（内联 Markdown）或 blob_id（来自 POST /blob）之一——对于大型更新，建议使用 blob_id。返回 web_url（笔记预览链接）。写入内容达到或超过 80 KB 时，_warnings 中会附带一条建议拆分内容的提示。仅接受 type: "note" 节点。 通过上传流程上传的 .md 文件是 File，而不是 Note，此操作会因错误 153548 Node is not a note 而拒绝该文件。要更改 File 的内容，请调用 upload 操作 create-session，并使用与现有 File 相同的 parent_node_id 和相同的 filename（或传入 target_node_id，按 ID 指定要覆盖的文件），然后分块上传并完成（或流式上传）——同名上传会就地覆盖文件，并将先前内容保留为一个版本。调用前如需验证节点类型，请使用 storage 操作 details 并检查 type 字段。有关 File 与 Note 的完整指南，请参阅 Notes 部分。

read-note -- 读取笔记的 Markdown 内容和元数据。返回笔记内容和 web_url（笔记预览链接）。

quickshare-get -- 获取节点现有的快速分享详情。返回 web_url。

quickshare-delete -- 撤销并删除节点的快速分享链接。

quickshares-list -- 列出工作区中所有活跃的快速分享。每个快速分享都包含 web_url。 metadata-template-create -- 在工作区中创建新的元数据模板。所有套餐均可使用（Agent/Free 可创建首个模板；Pro 每个工作区最多可创建 2 个；Business 最多可创建 10 个）。需要提供名称、描述、类别（legal、financial、business、medical、technical、engineering、insurance、educational、multimedia、hr）和字段（以 JSON 编码的字段定义数组）。每个字段包含名称、描述、类型（string、int、float、bool、json、url、datetime）以及可选约束（min、max、default、fixed_list、can_be_null、autoextract）。autoextract 默认为 true；对于应手动管理的字段（用户填写的备注、审核者标记等），请将其设为 false——执行完整行 AI 提取时会跳过这些字段，但仍可通过 metadata-set 写入。每个模板都必须至少有一个字段的 autoextract:true，否则 API 会返回 1605（Invalid Input）。每个套餐的节点上限（Agent/Free/Pro 为 10，Business 为 1,000）适用于文件映射，而非模板本身。

metadata-template-delete -- 删除元数据模板。系统模板和锁定模板无法删除。需要提供 template_id。

metadata-template-list -- 列出元数据模板。可选参数 template_filter：enabled、disabled、custom（非系统模板）或 system。未指定筛选条件时，返回所有未删除的模板。现在每个条目的 fields 数组都会包含每个字段的 autoextract（现有模板的默认值为 true）。根据实时 AI 类别概览，响应还应在每个条目的可见数量旁包含 plan_node_limit、is_truncated 和未筛选数量——这些字段未固定在实时响应示例中，因此依赖这些字段前，请在运行时确认确切的字段名称。

metadata-template-details -- 获取元数据模板的完整详情，包括所有字段定义。需要提供 template_id。现在，返回的 fields 数组会包含每个字段的 autoextract（现有模板的默认值为 true）。根据实时 AI 类别概览，响应还应包含 plan_node_limit、is_truncated 和未筛选数量——这些字段未固定在实时响应示例中，因此请在运行时确认字段名称。每个模板的 nodes/ 列表端点中，未筛选数量字段为 total_count_unfiltered；details 中的对应字段可能不同。

metadata-template-update -- 更新现有元数据模板。可更新名称、描述、类别和字段中的任意组合。需要提供 template_id。

metadata-template-clone -- 克隆元数据模板，并可选择性地进行修改。根据现有模板创建新模板。参数与 metadata-template-update 相同。需要提供 template_id。 metadata-template-preview-match -- 在创建模板前，预览工作区中哪些文件会与拟定的模板匹配。需要提供 name（1-255 个字符）和 description（1-2000 个字符），用于描述模板的用途。返回 matched_files（一组匹配节点样本，包含 node_id、name、mimetype 和简短摘要——实时参考文档未固定样本数组的长度，因此请遍历 matched_files，不要假定其数量），以及 total_eligible、total_scanned 和 total_matched 计数。关于 total_eligible 的说明：根据实时参考文档，此值表示符合条件的文件样本窗口大小，而非整个工作区的计数——当工作区中符合条件的文件多于样本窗口的容量时，total_eligible 会设为 sample_ceiling + 1，作为“还有更多”的信号。请将任何单次返回的值视为下限，而非实际总数。还会返回 plan_node_limit（工作区当前套餐的每模板节点上限；-1 = 无限制）和 would_truncate_at（在上限生效时 = min(total_matched, plan_node_limit)，否则 = total_matched）。文档建议的截断启发式规则：当 would_truncate_at < total_matched 时向用户发出警告——套餐上限会截去匹配样本数量的一部分，自动匹配会静默跳过超出上限的部分。触发该规则时，MCP 处理程序会自动在 _warnings 中发出此警告（包含实际数值）。使用返回的 node_id 作为 metadata-template-suggest-fields 的输入，以获取 AI 建议的列。

metadata-template-suggest-fields -- 根据一组文件样本，请 AI 提出 1-5 个自定义字段。需要提供 workspace_id、description（1-2000 个字符——与用于 preview-match 的视图／模板描述相同）和 node_ids（以 JSON 编码的 1-25 个节点 ID 数组，通常来自 preview-match 结果；服务端会过滤文件夹节点）。可选的 user_context 是用户编写的简短提示，用于说明要创建的内容（最多 64 个字符，仅限字母／数字／空格——例如 "photo collection" 或 "contract tracker"）。返回：(a) suggested_name——AI 根据文件、描述和 user_context 为模板／视图建议的显示名称；(b) suggested_description——AI 建议的模板描述；(c) suggested_fields——{name, type, description, can_be_null, max?, fixed_list?, example_value?} 对象数组（name／type／description／can_be_null／max／fixed_list 键与 metadata-template-create 的 fields 参数直接兼容；example_value 是仅用于预览的提示，展示该字段可能的值，其类型与声明的 type 匹配（int 对应整数，datetime 对应 ISO 8601，bool 对应布尔值，由服务端强制转换且最多 256 个字符；若 AI 无法生成有效／可强制转换的示例，则省略此项）——将此数组传递给 metadata-template-create 前，请移除 example_value）；以及 (d) file_sample_count。在模板创建界面中，将 suggested_name 和 suggested_description 用作预填默认值（用户可以接受或编辑）。调用通常需要 10-30 秒。错误情况：输入无效或额度不足时返回 400；同一用户和工作区已有另一个 suggest-fields 调用正在进行时返回 409 Conflict（等待几秒后重试）；LLM 暂时性故障时返回 500（重试）。

metadata-template-assign -- 将元数据模板分配给工作区。每个工作区最多只能分配一个模板。分配系统模板时会自动克隆该模板。需要提供 template_id。可选的 node_id（工作区级分配时为 null）。

metadata-template-unassign -- 移除工作区的模板分配。需要工作区管理员权限。

metadata-template-resolve -- 确定适用于指定节点的元数据模板。返回工作区级模板（接受 node_id，但目前会继承工作区模板）。如果未分配模板，则返回 null。 metadata-template-assignments -- 列出工作区中的所有模板分配。

metadata-view-get -- 获取调用者为某个模板保存的视图。需要 workspace_id 和 template_id。返回已保存的视图记录 {id, user_id, template_id, config, created, updated}；如果调用者没有为该模板保存视图，则返回错误 1609。已保存的视图按用户私有——身份元组为 (workspace, user, template)，每个元组最多只有一个已保存视图。

metadata-view-save -- 新建或更新调用者为某个模板保存的视图。需要 workspace_id、template_id 和 config（JSON 编码的字符串——MCP 工具接受 JSON 字符串，解析并验证 JSON 格式是否正确，然后将重新序列化的内容作为 config 字段转发到 form-urlencoded 请求体）。config 架构：version（必须等于 1）、columns（数组；顺序即显示顺序；每个条目：必需的 field 字符串、可选的 visible? 布尔值、可选的 width? 正整数）、sort（{field: string, dir: "asc" | "desc"}）、filters（数组，最多 5 项；按 AND 链接；每个条目包含：field 字符串、operator 为 = != < <= > >= 之一、value_type 为 string | int | float | bool 之一——json 将被拒绝、value 与声明的 value_type 匹配）。config 中任意位置出现未知键都会返回错误 1605。新建或更新语义：如果 (workspace, user, template) 已存在视图，则在原记录上替换——保留行的 id 和 created，并刷新 updated；否则插入新行。返回已存储的视图。

config 示例：

{
  "version": 1,
  "columns": [
    { "field": "vendor", "visible": true, "width": 180 },
    { "field": "amount", "visible": true, "width": 120 },
    { "field": "notes", "visible": false }
  ],
  "sort": { "field": "amount", "dir": "desc" },
  "filters": [
    { "field": "vendor", "operator": "=", "value_type": "string", "value": "Acme" },
    { "field": "amount", "operator": ">=", "value_type": "float", "value": 100.0 }
  ]
}

metadata-view-delete -- 删除调用者为某个模板保存的视图。需要 workspace_id 和 template_id。仅影响调用者自己的已保存视图（同一模板的其他用户视图不受影响）。

metadata-views-list -- 列出调用者在某个工作区中跨模板保存的所有视图。需要 workspace_id。返回 {items, count}，其中 items 是已保存视图记录数组（每个调用者保存过视图的模板对应一条记录）。 metadata-view-export——异步将调用者为某个模板保存的视图写入工作区存储中的 TSV 文件。需要提供 workspace_id 和 template_id。可选参数 parent_node_id 是目标文件夹的 OpaqueId；省略（或传入空值）则写入工作区根目录。此端点会将任务加入队列并立即返回——实际 TSV 文件由后台工作线程写入目标文件夹。响应有两种形式：（a）queued——{result:true, job_id, status:"queued", filename, message}，其中 filename 根据已保存视图的 name 生成（会清理不适用于文件系统的字符，并添加 .tsv 扩展名；如果清理后的名称为空，则回退为 metadata_view_{partialViewId}.tsv）；（b）duplicate——{result:true, status:"duplicate", filename, message}，如果同一 (workspace, user, template, destination_folder) 的导出已在队列中或正在处理，则不会包含 job_id。将同一视图导出到不同文件夹不算重复。前提条件：调用者必须已有已保存的视图（先调用 metadata-view-save；否则返回 404 View not found）；工作区所属组织必须启用元数据功能（未启用则返回 403——这是计费功能门控；Free、Pro、Business 均符合条件）。检测是否完成：通过 storage 的 list 操作轮询目标文件夹（或通过 storage 的 details 操作查看上级文件夹），查找 name 与返回的 filename 匹配的节点；在文件夹中查找的方式不受重复分支影响（该分支没有 job_id 可供追踪），因此更可靠。大多数导出会在几秒内完成。并发导出在同一工作区内由工作区级 Redis 互斥锁串行处理——同一工作区中导出不同视图的两个调用者会依次处理。快照语义：TSV 反映的是工作线程运行时的元数据状态，而非请求发出时的状态。无法自定义文件名或列——两者均来自已保存的视图；如需更改，请先通过 metadata-view-save 更新视图。视图按用户区分：工作区管理员无法导出“团队的视图”；导出内容反映调用用户保存的视图。此端点按用户和工作区进行速率限制（X-Rate-Limit-* 标头）。 metadata-search -- 对工作区的模板和自定义元数据字段值进行词法关键词搜索。返回元数据字段值中包含查询关键词的工作区文件，并按相关性评分。需要提供 workspace_id 和 q（搜索关键词；会去除首尾空白；不允许为空；最多 1024 个字符）。可选的 template_id 会将结果限定为至少有一个值由该模板提供的节点（设置此筛选条件后会排除自定义字段）。可选的 limit（1-100，默认 100）和 offset（默认 0）用于分页——offset+limit 不得超过 10000。搜索语义：多词查询（例如 q=foo bar）要求所有词都匹配（由分析器分词后执行 AND）；不区分大小写；查询长度不超过 64 个字符时进行子串匹配；更长的查询仅进行整词／词元匹配（200 个字符的文本查询会逐词匹配，而非作为子串匹配）。返回 {results, pagination}：每个结果条目为 {node_id, score（BM25——仅用于相对排序，不可跨查询比较）, template_ids（提供了匹配值的模板；空数组表示仅匹配自定义字段）, node（完整填充数据的节点载荷，形状与 storage操作details 相同——填充时会过滤掉已移至废纸篓的节点）}。分页结构为 {total, limit, offset, has_more}，其中 total 是 ES 命中数（应用实例筛选后、应用废纸篓筛选前——可用于显示“X 个结果”之类的 UI 标签），且 has_more = (offset+limit) < total。索引延迟：元数据写入会通过事件队列异步传播到搜索索引——元数据编辑（模板提取、自动匹配、手动编辑）后，预计需要 1-2 秒才能查询到新值。不要在写入后立即搜索来检查正确性——这会产生竞态；对于“显示刚保存内容”的流程，应直接从元数据模板端点读取，而不是使用搜索。租户隔离：服务始终会在底层 ES 筛选条件中注入 instance_id = workspace_id；无法通过强制转换跨工作区查询。传入其他工作区的 template_id 只会返回零条命中（不会泄露数据）。它不适用于：结构化筛选（要查询 where field = value，请使用带有 metadata_filters 的 metadata-list-files）、语义／向量搜索（仅词法搜索——"house" 不会匹配 "residence"），也不用于搜索文件内容（此类搜索请使用 storage 操作 search）。API 不会返回结果摘要／高亮；请使用匹配的 node_id 通过 metadata-get 获取元数据，并在客户端进行子串匹配。

在节点列表端点上自动应用已保存的视图。 每个模板的节点列表端点（GET /workspace/{id}/metadata/templates/{tid}/nodes/）会在调用者未提供相应查询参数（sort_field / filters）时，自动应用其已保存的 config.sort 和 config.filters。显式查询参数始终优先——无状态查询参数与已保存视图状态之间不会在服务端合并。服务端不会自动应用 columns；客户端必须自行根据已保存的 columns 数组渲染列顺序／可见性／宽度。注意字段名的特殊之处：无状态的 filters 查询参数在每个条目中使用 key（沿用未变更的旧版约定），而已保存视图的 config.filters 条目使用 field——服务端在自动应用已保存视图时会在内部将 field 转换为 key。此端点当前未作为 MCP workspace 操作公开（参见上文“MCP 工具覆盖范围”项目）——如需测试自动应用功能，请通过代码模式 execute 使用 fastio.get() 调用此端点。 metadata-get -- 获取一个或多个文件的所有元数据，包括符合模板的元数据和自定义（自由格式）键值对。单 ID 形式：传入 node_id；返回节点详情、template_id、template_metadata 数组、custom_metadata 数组，以及顶层的 autoextractable 布尔值（与 template_id 同级，不嵌套在任何一个元数据数组中）。只有当节点是文件（不是文件夹）、未被移入回收站且已完成 AI 摘要时，autoextractable 才为 true——这与提取流水线内部使用的信号相同。可用它控制“立即提取”／“重新提取”界面操作：如果值为 false，调用 metadata-extract 会失败或不执行任何操作（请先等待 AI 摘要完成）。**批量形式（一次调用 1-25 个 ID）：**将 node_ids 作为经过 JSON 编码的节点 ID 数组传入（所有 ID 必须属于同一工作区；跨工作区 ID 会作为每个 ID 的错误 191049 返回）。重复 ID 会在计入数量上限前去重。批量响应会规范化为 {format:"multi", objects, templates, errors, object_count, template_count, error_count, requested_count}——objects 中的每个条目都与单 ID 响应正文结构相同（instance_id、object_id、template_id、node_id、template_metadata、custom_metadata、autoextractable），而 templates 映射（以 template_id 为键）会完整包含每个模板定义一次，而不是在每个对象中重复包含。渲染每一行时，通过 obj.template_id 在 templates 映射中查找对应项。无论扇出多少，批量调用都只计为 1 次限流，因此只要文件夹／选择器视图需要多个文件的元数据，就应优先使用批量调用，而不是逐个文件循环调用。每个 ID 的错误代码（位于 errors[] 中）：147196 ID 格式无效，196136 提供了根哨兵值，191049 未找到节点（跨工作区 ID 也会返回此错误），190770 检索节点时发生临时后端错误，150183 节点存在，但不是文件或笔记（例如文件夹），157684 检索元数据行时发生临时后端错误。147196/196136/150183/191049 是确定性错误——不要重试；只有 190770/157684 值得重试。超过 25 个 ID 时，客户端会拒绝请求并给出明确错误，而不会与服务器往返通信。

metadata-set -- 在文件上设置或更新元数据键值对。值必须符合模板字段定义。需要提供 node_id、template_id 和 key_values（键值对的 JSON 对象）。

metadata-delete -- 从文件中删除元数据。提供 keys（要删除的键名 JSON 数组）可删除指定条目；省略则删除所有元数据。仅适用于文件和笔记，不适用于文件夹。需要提供 node_id。 metadata-extract -- 为文件加入 AI 驱动的元数据提取队列。该端点是异步的（HTTP 202）：它会将后台任务加入队列，并在约 500ms 后返回 job_id、status（queued/in_progress/completed/errored）、status_uri、node_id、template_id 和 fields（请求的范围；完整行提取时为 null）。响应不包含提取出的值。需要 node_id。template_id 为可选项（默认使用工作区模板）。extract_fields 为可选项，是一个以 JSON 编码的字段名称数组（例如 ["vendor","amount"]），用于部分提取；完整行提取时省略该参数。与自动提取的交互：省略 extract_fields 时，有效范围会限制为模板中 autoextract:true 的字段。如果模板中的所有字段都已选择停用自动提取，端点会返回成功，但不包含 job_id，也不会加入任务队列。若要强制提取已选择停用自动提取的字段，请通过 extract_fields 显式传入该字段——系统会原样遵从显式列表，将其作为手动覆盖。预检门控：调用前，检查目标节点的 autoextractable 标志（由 metadata-get 返回）。如果为 false，提取会失败或不执行；请先等待 AI 摘要完成。幂等性：首次调用仍在执行时，针对相同 (node_id, template_id, fields) 元组再次调用提取会返回相同的 job_id（不会加入重复任务）；不同的 template_id 或不同的 extract_fields 会生成不同任务。提取出的值会标记为 is_auto: true，并消耗 AI 点数。新的 Agent 工作流如下：(1) 通过 metadata-get 确认 autoextractable:true；(2) 调用 metadata-extract，并在返回 job_id 时保存它（所有字段都已选择停用自动提取的模板会返回成功，但不包含 job_id——此时应通过显式传入 extract_fields 进行手动覆盖，或完全跳过轮询）；(3) 轮询 jobs-status，筛选 metadata_extract 数组中 kind:"single" 且与 node_id 匹配的条目；(4) 条目显示 status:"completed" 时，调用 metadata-get 读取值；若为 status:"errored"，则显示该条目的 error_message。超过约 1 小时的过期条目（已完成或出错）会从 jobs-status 中自动隐藏。订阅者可以选择响应活动事件而非轮询：每次状态转换时都会触发 EVENT_METADATA_KV_EXTRACT_STARTED / EVENT_METADATA_KV_EXTRACT / EVENT_METADATA_KV_EXTRACT_ERRORED。

jobs-status -- 获取工作区的异步任务状态。需要 workspace_id。返回按类别划分的进行中异步任务数组（目前包含 metadata_extract 数组；AI 索引及其他后台工作可能还有其他类别）。metadata_extract 数组包含单节点条目（kind:"single"，带有 node_id、job_id、template_id、fields_scope、status、progress_percent、started_at、updated_at、completed_at、error_message）和批量条目（kind:"batch"，带有 total_files、eligible_files、processed、skipped、failed、progress_percent 等）——请通过 kind 字段区分。已完成或出错的过期条目会在约 1 小时后自动隐藏，因此应将缺少条目的情况视为“不再处于活动状态”。轮询间隔：1–3 秒即可——此端点的速率限制较宽松。

metadata-list-files -- 列出指定模板下带有元数据的文件，并支持可选筛选和排序。需要 node_id（要搜索的文件夹）和 template_id。metadata_filters（以 JSON 编码）、order_by（字段键）和 order_desc 均为可选项。

metadata-list-templates-in-use -- 列出文件夹中正在使用的元数据模板及每个模板的使用次数。需要 node_id。

metadata-versions -- 获取文件的元数据版本历史记录。返回元数据随时间变化的快照。需要 node_id。

enable-workflow -- 在工作区上启用工作流功能（任务、工作日志、审批、待办事项）。必须先调用此工具，才能在该工作区上使用工作流工具。 disable-workflow —— 禁用工作区上的工作流功能。所有工作流数据都会保留，但在重新启用前无法访问。

enable-import —— 在工作区上启用云导入功能（外部存储提供商）。必须先调用此工具，才能配置导入身份。

disable-import —— 在工作区上禁用云导入功能。现有导入源将停止同步，但数据会保留。

instructions-get —— 读取工作区的 AI 指令。scope: "profile"（默认值）读取工作区范围的存储位置 /workspace/{ws_id}/instructions/。scope: "me" 读取每位用户各自的存储位置 /workspace/{ws_id}/instructions/me/。首次读取尚未写入的存储位置时，会返回 content: "" 和空时间戳（而不是 404）。

instructions-set —— 替换工作区的 AI 指令（完整替换，最多 65536 个 UTF-8 字节）。scope: "profile"（默认值）要求用户为所有者或管理员（非管理员会收到 403 错误，代码为 1680）。scope: "me" 写入每位用户各自的存储位置（任何成员均可，访客除外）。两个范围相互独立，服务器端不会合并；如需合并视图，请在客户端进行拼接。

instructions-clear —— 软清除工作区的 AI 指令（保留审计记录）。scope: "profile"（默认值）要求用户为所有者或管理员；scope: "me" 清除每位用户各自的存储位置（访客除外）。可重复调用。

share

list —— 列出已认证用户有权访问的共享项。每个共享项都包含 web_url。

details —— 获取特定共享项的完整详情。返回 web_url。

create —— 在工作区中创建新的共享项。

update —— 更新共享项设置（部分更新）。

delete —— 删除（关闭）共享项。需要提供共享项 ID 或自定义名称作为确认。

public-details —— 获取面向公众的共享项信息（无需成员身份，只需通过身份验证）。

archive —— 归档共享项。阻止访客访问并限制修改。

unarchive —— 将之前归档的共享项恢复为启用状态。

password-auth —— 使用共享项密码进行身份验证。返回该共享项专用的 JWT。

members —— 列出共享项的所有成员。包含活跃成员和待处理成员，以及 status 和 invite 字段（与工作区成员相同）。

available —— 列出可加入的共享项（已加入和拥有的共享项，不包括待处理邀请）。每个共享项都包含 web_url。

check-name —— 检查共享项自定义名称（URL 名称）是否可用。

quickshare-create —— 为工作区中的文件创建临时 QuickShare 链接。可选参数 expires（秒，默认值为 10,800，最大值为 604,800，即 7 天）或 expires_at（ISO 8601 日期时间）。

enable-workflow —— 在共享项上启用工作流功能（任务、工作日志、审批、待办事项）。使用共享项上的工作流工具前必须先调用此工具。

disable-workflow —— 禁用共享项上的工作流功能。所有工作流数据都会保留，但在重新启用前无法访问。

instructions-get —— 读取共享项的 AI 指令。scope: "profile"（默认值）读取共享项范围的存储位置 /share/{share_id}/instructions/。scope: "me" 读取每位用户各自的存储位置 /share/{share_id}/instructions/me/。首次读取尚未写入的存储位置时，会返回 content: "" 和空时间戳（而不是 404）。

instructions-set —— 替换共享项的 AI 指令（完整替换，最多 65536 个 UTF-8 字节）。scope: "profile"（默认值）要求用户为所有者或管理员（非管理员会收到 403 错误，代码为 166463）。scope: "me" 写入每位用户各自的存储位置——仅限注册成员（匿名访客/链接访客会收到 403 错误，代码为 185733）。两个范围相互独立，服务器端不会合并；如需合并视图，请在客户端进行拼接。

instructions-clear —— 软清除共享项的 AI 指令（保留审计记录）。scope: "profile"（默认值）要求用户为所有者或管理员；scope: "me" 清除每位用户各自的存储位置（仅限注册成员，不包括匿名访客）。可重复调用。

storage

所有存储操作都需要 profile_type 参数（也接受 context_type）（workspace 或 share）以及 profile_id（也接受 context_id）（19 位配置文件 ID）。

list -- 列出目录中的文件和文件夹，支持分页。每个条目都包含 web_url（仅限工作区）。需要 profile_type、profile_id 和 node_id（根文件夹使用 root）。

recent -- 列出所有目录中最近修改的文件和文件夹，并按更新时间降序排列。与仅针对单个文件夹的 list 不同，此操作会返回整个存储树中的节点。支持可选的 type 筛选条件（file、folder、link、note）、page_size（100、250 或 500）以及用于分页的 cursor。对于工作区文件夹共享，结果会自动筛选为共享范围内的子树。

details -- 获取一个或多个节点的完整详情。通过 node_id 单个查询时，会返回包含 web_url 的旧版单项结构（指向网页界面中文件预览或文件夹的人类可读链接，仅限工作区）。通过 node_ids 批量查询时（1-25 个 ID，且都属于同一工作区/共享），会返回 {format: "multi", nodes, errors, node_count, error_count, requested_count}——部分结果属于正常情况（返回 200 且 errors 非空并不代表失败；请呈现已获取的节点，并在对应输入 ID 旁显示各 ID 的错误）。根据 node.id（不区分大小写）匹配结果；结果顺序不固定。可能出现的各 ID 错误代码：133123（未找到/工作区错误）、191878（OpaqueId 无效）、146950（实际内容已不存在——去重后缓存过期，无法通过重试解决）、146256（临时检索错误——可以安全重试）、179961（格式错误，较少见）。超过 25 个 ID 会在客户端被拒绝；请拆分处理。批量端点接受任意节点类型（文件、文件夹、笔记、链接）。

search -- 统一搜索：关键词搜索 + 在启用工作区智能功能时自动进行语义匹配。内置英文词干提取（“cats”可找到“cat”，“running”可找到“run”）。参数：query（必需）、可选的 files_scope（逗号分隔的 nodeId:versionId 对——将语义搜索限定在特定文件中；需要智能功能，否则会静默忽略；最多 100 个）、folders_scope（逗号分隔的 nodeId:depth 对，深度为 1-10——通过 BFS 将搜索限定在文件夹树中；需要智能功能，否则会静默忽略；最多 100 个）、details（设为 "true" 时返回每项结果的完整节点详情——预览、AI 状态、元数据、版本；默认上限降至 10）、limit（1-500，默认 100；details=true 时为 10）、offset。始终包含： name、parent_id（string|null）、type（file、folder 或 note）。启用智能功能时添加： relevance_score（0.0-1.0——关键词：0.0-0.5；语义：0.5-1.0）、content_snippet（匹配的文本片段，仅关键词匹配时为 null）、match_source（"keyword"、"semantic" 或 "both"）、media_segment（用于音频/视频深层链接的 {start_seconds, end_seconds}，非媒体内容为 null）、page（用于文档页级匹配的 {start_page, end_page}，非文档为 null）、mimetype（语义匹配时的文件 MIME 类型）。details=true 时添加： node（完整节点资源——预览、AI 状态、版本、元数据；无法加载节点时为 null）。顶层 search_metadata（仅启用智能功能时）：intelligence_enabled（bool）、semantic_available（bool——gRPC 失败时为 false，系统会平稳降级）、scoped（bool——使用了 files_scope 或 folders_scope 时为 true）。未启用智能功能时： 响应仅包含 name、parent_id、type——仅执行关键词搜索。每项结果都包含 web_url（仅限工作区）。

trash-list -- 列出当前位于回收站中的项目。每个条目都包含 web_url（仅限工作区）。

create-folder -- 创建新文件夹。返回 web_url（仅限工作区）。

copy -- 复制文件/文件夹。通过 node_id 单次复制（工作区或共享）。通过 node_ids 数组批量复制（仅限工作区）。新副本会返回 web_url（仅限工作区）。 move -- 移动文件/文件夹。通过 node_id 单独移动（工作区或共享空间）。通过 node_ids 数组批量移动（仅限工作区）。返回 web_url（仅限工作区）。

delete -- 将文件/文件夹移入回收站，以此删除文件/文件夹。通过 node_id 单独删除（工作区或共享空间）。通过 node_ids 数组批量删除（仅限工作区）。

rename -- 重命名文件或文件夹。返回 web_url（仅限工作区）。

purge -- 永久删除已移入回收站的节点（不可撤销）。需要 Member 权限。

restore -- 从回收站恢复文件/文件夹。通过 node_id 单独恢复（工作区或共享空间）。通过 node_ids 数组批量恢复（仅限工作区）。返回已恢复节点的 web_url（仅限工作区）。

add-file -- 将已完成的上传关联到存储位置。返回 web_url（仅限工作区）。

add-link -- 向存储添加共享引用链接节点。

transfer -- 将节点复制或移动到另一个工作区或共享存储实例。默认模式为 'copy'（保留源文件）。使用 transfer_mode='move' 可先复制，再将源文件移入回收站（无法移动根节点）。当 mode=move 时，响应会包含 source_trashed（布尔值），用于指示源文件是否已成功移入回收站。

version-list -- 列出文件的版本历史记录。返回文件的 web_url（仅限工作区）。

version-restore -- 将文件恢复到先前版本。返回文件的 web_url（仅限工作区）。

lock-acquire -- 获取文件的排他锁，以防止并发编辑。

lock-status -- 检查文件的锁定状态。

lock-release -- 释放文件的排他锁。

preview-url -- 获取文件的预授权预览 URL（缩略图、PDF、图片、视频、音频、电子表格）。需要 preview_type 参数。返回 preview_url（可直接使用的 URL）和 web_url（在 Web UI 中指向文件的易读链接，仅限工作区）。

preview-transform -- 请求转换文件（调整图片大小、裁剪、转换格式），并获取结果的下载 URL。需要 transform_name 参数。返回 transform_url（可直接使用的 URL）和 web_url（在 Web UI 中指向文件的易读链接，仅限工作区）。

上传

create-session -- 为文件创建分块上传会话。可选传入 target_node_id，以确定性地覆盖指定的现有节点（action=update + file_id=<target_node_id>）：设置后会忽略 parent_node_id，且 filename 为可选项（除非提供新名称，否则保留现有名称，可在替换时重命名）。省略 filename 时，该工具会额外进行一次 storage details 往返调用以获取当前名称（API 在更新模式下仍要求提供 name）；传入 filename 可跳过此步骤。保留 node_id；新版本可通过 storage 操作 version-list 查看。需要更新文件内容时，请使用此操作，而不是先删除再重新上传。若未设置 target_node_id，同名且父节点相同的上传仍会原位覆盖（标准 REPLACE 行为）。任何覆盖操作完成后，都可通过 storage 操作 version-list / version-restore 恢复先前内容。

stream-upload -- 创建流式会话、上传文件内容，并在一次调用中自动完成会话。适用于大小事先未知，且无需在多次调用间保留会话 ID 的生成内容或管道传输内容。需要 profile_type、profile_id、parent_node_id、filename，以及以下参数中的一个且仅一个：content（文本）| content_base64（小型二进制数据，由服务器端解码）| blob_id（POST /blob）。可选参数：max_size（参见上文指南；省略时使用计划的文件大小限制）、target_node_id（覆盖指定节点；设置后会忽略 parent_node_id，且 filename 为可选项；省略 filename 会触发与 create-session 说明相同的额外 storage details 查询）、hash、hash_algo。如果创建会话后流式 POST 失败，系统会自动取消未完成的会话。 batch —— 在一次 multipart 往返中，将最多 200 个小文件（每个 ≤4 MB，总计 ≤100 MB）上传到一个目标文件夹。需要 profile_type、profile_id 和 files[]（每个条目包含：filename，以及 blob_id | content（文本） | content_base64（小型二进制数据，由服务端解码）中的一个，且只能有一个；可选字段：relative_path、hash、hash_algo）。可选：folder_id（批次级目标，默认为实例根目录）、creator（回显标签）、include_hash（默认为 true——为未提供哈希的条目在客户端计算 SHA-256）。返回每个条目的 results[]，其中包含 status、upload_id 和 node_id，并附带经过预筛选的 errors[] 视图。成功时 node_id 可能为 null —— 使用异步存储的工作区会稍后分配节点 ID；不要将 null 视为错误。部分成功是正常情况 —— HTTP 200 响应中出现 count_errored > 0 是预期行为；只重试出错的条目。如果所有条目都出错，响应会包含 all_failed: true。使用独立于单文件上传的速率限制桶；工具会在 429 响应时显示 x-ve-limit-expires UTC 日期时间。需要身份验证（匿名调用者会收到 HTTP 401，错误代码 10011——应将其转至单文件 create-session 流程）。

chunk —— 上传单个分块。文本/字符串使用 content，小型二进制数据（由服务端解码）使用 content_base64，通过 POST /blob 暂存的二进制数据使用 blob_id。必须且只能提供其中一个。注意：content 会原样存储为 UTF-8——请勿在此字段中传入 base64。

stream —— 将整个文件主体上传到现有的流式会话（通过 create-session 并设置 stream=true 创建）；自动完成最终化。除非需要在调用之间使用 upload_id，否则优先使用 stream-upload。需要 upload_id，并且必须且只能提供 content（文本） | content_base64（小型二进制数据，由服务端解码） | blob_id 中的一个。可选：hash、hash_algo。

finalize —— 完成上传会话，触发文件组装，并轮询直至文件完全存储或失败。返回最终会话状态。

status —— 获取上传会话的当前状态。支持通过可选的 wait 参数进行服务端长轮询（单位为毫秒，0 = 立即返回）。

cancel —— 取消并删除活动的上传会话。

list-sessions —— 列出当前用户的所有活动上传会话。

cancel-all —— 一次性取消并删除所有活动的上传会话。

chunk-status —— 获取上传会话的分块信息。

chunk-delete —— 删除/重置上传会话中的一个分块。

web-import —— 从外部 URL 将文件导入工作区或共享空间。

web-list —— 列出用户的网页上传任务，可选择筛选条件。

web-cancel —— 取消活动的网页上传任务。

web-status —— 获取特定网页上传任务的详细状态。

limits —— 获取用户方案的上传大小和分块限制。返回 chunk_size（最大分块大小，所有方案均为 100 MB）、size（最大文件大小：免费版/agent 为 1 GB，pro 为 25 GB，business 为 50 GB）、chunks（每个会话的最大分块数：免费版/agent 为 35，pro/business 为 550）、sessions、sessions_size_max。注意： 最小分块大小（1 MB，最后一个分块除外）是固定的系统常量，此端点不会返回该值。可选参数：action_context、instance_id、file_id、org。

extensions —— 获取上传时受限和允许的文件扩展名。可选参数 plan 用于检查特定方案的限制。返回 restricted_extensions、archive_extensions、enforcement_enabled、plan、cache_ttl。

blob-info —— 获取 POST /blob 辅助端点的 URL、你的 MCP 会话 ID、所需标头，以及可直接使用的 curl 命令，用于通过 shell 上传文件。无需参数。通过 blob 辅助端点上传文件前请先使用此工具——它会提供绕过 MCP 传输限制所需的一切信息，让你可以通过 curl 上传。

下载

file-url -- 获取文件的下载令牌和 URL。可选指定版本。需要 profile_type、profile_id 和 node_id。

zip-url -- 获取文件夹或整个工作区／共享内容的 ZIP 下载 URL。返回 URL 和身份验证说明。需要 profile_type、profile_id 和 node_id（整个存储树请使用 root）。

quickshare-details -- 获取 quickshare 链接的元数据和下载信息。无需身份验证。

AI

所有 AI 操作都需要 profile_type 参数（也接受 context_type）（workspace 或 share）和 profile_id（也接受 context_id）（19 位个人资料 ID）。

chat-create -- 创建新的 AI 聊天并附带初始问题。默认范围是整个工作区（所有已编入索引的文档）——除非需要缩小搜索范围，否则省略 files_scope 和 folders_scope。使用范围或附件时，请提供 nodeId:versionId 配对——如果 versionId 留空，则会自动解析为当前版本（从存储列表／详情的 version 字段获取明确的 versionId）。使用 files_attach 时，先确认每个文件的 ai.attach 为 true（通过存储详情检查）。存在文件参数时，类型会自动从 chat 升级为 chat_with_files。返回聊天 ID 和初始消息 ID——使用 message-read 获取 AI 回复。

chat-list -- 列出 AI 聊天。

chat-details -- 获取 AI 聊天详情，包括完整消息历史记录。

chat-update -- 更新 AI 聊天的名称。

chat-delete -- 删除 AI 聊天。

chat-publish -- 发布私有 AI 聊天，使其对所有成员可见。

message-send -- 在现有 AI 聊天中发送后续消息。返回消息 ID——使用 message-read 获取 AI 回复。

message-list -- 列出 AI 聊天中的所有消息。

message-details -- 获取 AI 聊天中特定消息的详情，包括回复文本和引用。

message-read -- 读取 AI 消息回复。轮询消息详情端点，直到 AI 回复完成，然后返回完整文本。

share-generate -- 生成 AI Share Markdown，其中包含文件的临时下载 URL，可粘贴到外部 AI 聊天机器人中。

transactions -- 列出 AI 令牌使用交易记录，以便跟踪账单。

autotitle -- 根据内容生成 AI 标题和描述（仅限 share 上下文）。

comment

所有评论端点都使用路径模式 /comments/{entity_type}/{parent_id}/ 或 /comments/{entity_type}/{parent_id}/{node_id}/，其中 entity_type 为 workspace 或 share，parent_id 为 19 位的个人资料 ID，node_id 为文件的不透明 ID。

list — 列出特定文件（节点）上的评论。参数：sort（created/-created）、limit（2-200）、offset、include_deleted、reference_type 筛选条件、include_total。

list-all — 列出工作区或分享中的所有评论（不限定节点）。列表参数与 list 相同。

add — 为特定文件添加评论。请求正文：text（总计最多 8,192 个字符；去除 @[...] 提及标签后的显示文本最多 500 个字符）。支持提及标签：@[profile:id]、@[user:opaqueId:Name]、@[file:fileId:name.ext]。可选的 parent_comment_id（单层线程结构；回复的回复会自动扁平化），可选的 reference（用于内容锚定的 type、timestamp、page、region、text_snippet；用于 markdown/notes 文本锚定的 exact、prefix、suffix、start_offset、end_offset——请使用 type "document" 或 "text"），可选的 linked_entity_type（task 或 approval）和 linked_entity_id，用于在创建时将评论关联到工作流实体。使用 JSON 请求正文。

delete — 删除评论。递归删除：删除父评论时也会删除其所有回复。

bulk-delete — 批量软删除多条评论（最多 100 条）。非递归：已删除评论的回复会保留。

details — 按 ID 获取单条评论的完整详情。响应包含 linked_entity_type 和 linked_entity_id（未关联时为 null）。

reaction-add — 添加或更改你的表情反应。每位用户对每条评论只能添加一个反应；新反应会替换之前的反应。

reaction-remove — 移除你对某条评论的表情反应。

link — 将现有评论关联到工作流实体。参数：comment_id、linked_entity_type（task 或 approval）、linked_entity_id。每条评论只能关联一个实体；新关联会替换现有的关联。返回已填充关联字段的更新评论。

unlink — 移除评论与工作流的关联。参数：comment_id。返回关联字段设为 null 的更新评论。

linked — 反向查找：查找关联到指定工作流实体的所有评论。参数：linked_entity_type（task 或 approval）、linked_entity_id。返回关联到指定实体的评论列表。

event

search — 根据个人资料、事件类型、类别、子类别、事件名称和日期范围筛选并搜索审计/事件日志。完整的类别、子类别和事件名称分类，请参阅第 7 节中的 事件筛选参考。

summarize — 搜索事件，并返回由 AI 生成的自然语言活动摘要。接受与 search 相同的类别/子类别/事件筛选条件。

details — 按 ID 获取单个事件的完整详情。

activity-list — 轮询工作区或分享的近期活动事件。

activity-poll — 长轮询工作区或分享中的活动变更。服务端会保持连接，直到发生变更或等待时间到期。返回指示变更内容的 activity keys，以及供下一次轮询使用的 lastactivity 时间戳。

成员

所有成员操作都需要 entity_type 参数（workspace 或 share）和 entity_id`（19 位资料 ID）。

成员对象包含 status（active 或 pending）和 invite（活跃成员为 null，待处理成员则为 {id, created, expires}；expires 的格式为 YYYY-MM-DD HH:MM:SS UTC，若无过期时间则为 null）。待处理成员是尚未注册的受邀用户——他们会立即显示在成员列表中，也可以被分配任务、审批和待办事项。待处理成员注册后，其状态会变为 active，并保留所有分配。取消邀请（通过 invitation 操作 delete 并使用 invite.id）会移除待处理成员，并取消分配给他们的工作流项目。

add -- 通过用户 ID 添加现有用户，或通过电子邮件邀请用户。将电子邮件地址或用户 ID 作为 email_or_user_id 传入。如果受邀用户没有账户，通过电子邮件邀请会创建待处理成员。对于工作区，使用 permissions 设置访问级别（admin/member/guest）。对于分享，使用 role（admin/member/guest/view）。

remove -- 移除成员（不能移除所有者）。

details -- 获取特定成员的详细成员资格信息。对于工作区，传入 member_id；对于分享，传入 user_id。

update -- 更新成员的角色、通知设置或过期时间。

transfer-ownership -- 将所有权转让给另一位成员（当前所有者会降级为管理员）。

leave -- 离开（移除自己）。所有者必须先转让所有权。

join -- 根据组织成员资格自行加入。

join-invitation -- 使用邀请密钥接受或拒绝邀请。

邀请

所有邀请操作都需要 entity_type 参数（workspace 或 share）和 entity_id（19 位资料 ID）。

list -- 列出所有待处理邀请。

list-by-state -- 按状态筛选并列出邀请。

update -- 重新发送或更新邀请（通过 ID 或受邀者电子邮件）。

delete -- 撤销并删除待处理邀请。这也会从成员列表中移除对应的待处理成员，并取消分配给他们的任何工作流项目（任务、审批、待办事项）。使用成员对象中的 invite.id 作为 invitation_id。

资源

所有资源操作都需要 entity_type 参数（org、workspace、share 或 user）和 entity_id（org/workspace/share 的 19 位资料 ID）。

upload -- 上传资源（例如徽标、横幅、个人资料照片）。提供纯文本内容或 Base64 编码数据（二者不可同时提供）。

delete -- 删除资源。

types -- 列出该实体可用的资源类型。

list -- 列出该实体的所有资源。

read -- 读取/下载资源。

task

工作区和共享内容的任务列表与任务管理。所有任务操作都要求在目标实体上启用工作流（workspace 操作 enable-workflow，或 share 操作 enable-workflow）。

list-lists —— 列出工作区或共享内容中的所有任务列表。需要 profile_type 和 profile_id。支持 sort_by（created、updated、name）、sort_dir、limit（1-200）、offset 和 format（"md" 表示 Markdown）。

create-list —— 创建新的任务列表。需要 profile_type、profile_id 和 name（1-255 个字符）。可选 description（最多 2000 个字符）。

list-details —— 获取指定任务列表的详细信息。需要 list_id。支持 format。

update-list —— 更新任务列表的名称或描述。需要 list_id。可选 name、description。

delete-list —— 软删除任务列表及其所有任务。需要 list_id。具有破坏性。

list-tasks —— 列出任务列表中的任务。需要 list_id。支持按 status 筛选、按 assignee 筛选、sort_by（created、updated、name、priority、status）、sort_dir、limit（1-200）、offset 和 format。

create-task —— 在列表中创建新任务。需要 list_id 和 title（1-500 个字符）。可选 description（最多 5000 个字符）、status（pending、in_progress、complete、blocked）、priority（0=无、1=低、2=中、3=高、4=严重）、assignee_id（个人资料 ID——可以是待处理成员）、dependencies（任务 ID 数组）、node_id（关联文件／文件夹／笔记）。

task-details —— 获取指定任务的完整详细信息。需要 list_id 和 task_id。支持 format。

update-task —— 更新任务的标题、描述、状态、优先级、受指派人（包括待处理成员）、依赖项或节点链接。需要 list_id 和 task_id。

delete-task —— 软删除任务。需要 list_id 和 task_id。具有破坏性。

change-status —— 更改任务状态。需要 list_id、task_id 和 status。

assign-task —— 指派或取消指派任务。需要 list_id 和 task_id。传入 assignee_id（个人资料 ID，包括待处理成员）以进行指派；传入 null 或省略该参数以取消指派。

bulk-status —— 一次更改多个任务的状态。需要 list_id、task_ids（任务 ID 数组，最多 100 个）和 status。

move-task —— 在同一个人资料内将任务从一个列表移至另一个列表。需要 list_id（源列表）、task_id 和 target_task_list_id（目标列表）。可选 sort_order（在目标列表中的位置，默认为 0）。源列表和目标列表必须属于同一个人资料。返回更新后的任务，其中包含 old_task_list_id 和 new_task_list_id。

reorder-tasks —— 重新排列列表中的任务。需要 list_id 和 task_ids（按所需显示顺序排列的任务 ID 数组）。服务端会将其转换为 {order: [{id, sort_order}, ...]}，以供 API 使用。

reorder-lists —— 重新排列工作区或共享内容中的任务列表。需要 profile_type、profile_id 和 list_ids（按所需显示顺序排列的任务列表 ID 数组）。服务端会将其转换为 {order: [{id, sort_order}, ...]}，以供 API 使用。

filtered-list —— 按类别筛选并列出任务。需要 profile_type、profile_id 和 filter（"assigned"、"created" 或 "status"）。当 filter 为 "status" 时，还需要 status 参数。支持 limit、offset 和 format。

summary —— 获取工作区或共享内容的轻量级任务计数。需要 profile_type 和 profile_id。返回任务总数、按状态分类的数量、指派给我的任务数以及由我创建的任务数。支持 format。

worklog

用于跟踪 Agent 工作的活动日志。上传、任务变更、创建共享或执行任何重要操作后，请记录你做了什么以及原因——为人类和 AI 建立可搜索的审计跟踪。所有 worklog 操作都要求目标实体已启用工作流。

append -- 向 worklog 追加一条新记录。需要提供 entity_type（"task"、"task_list" 或 "profile"）、entity_id 和 content（1-10000 个字符）。进行更改后使用此操作，记录所做的工作及原因。记录创建后不可修改。

list -- 列出 worklog 记录。需要提供 entity_type（"task"、"task_list" 或 "profile"）和 entity_id（对应实体的不透明 ID；当 entity_type 为 "profile" 时，则为 19 位 profile ID）。支持 type 筛选器（"info" 或 "interjection"）、sort_dir（"asc" 或 "desc"，默认值为 "desc"）、limit（1-200）、offset 和 format（markdown 格式为 "md"）。

interject -- 创建一条需要确认的紧急插入记录。需要提供 entity_type（"task"、"task_list" 或 "profile"）、entity_id 和 content（1-10000 个字符）。插入记录是优先级更正——始终按紧急事项处理。

details -- 获取特定 worklog 记录的完整详情。需要提供 entry_id。支持 format。

acknowledge -- 确认一条插入记录，标记为已查看。需要提供 entry_id。只有 acknowledgable: true 的记录才能确认。

unacknowledged -- 列出尚未确认的插入记录（acknowledgable 为 true 的记录）。需要提供 entity_type（"task"、"task_list" 或 "profile"）和 entity_id。支持 limit、offset 和 format。继续工作前，请务必检查是否有尚未确认的插入记录。

profile-list -- 列出 profile 层级的所有 worklog 记录。需要提供 profile_type 和 profile_id。支持 limit、offset 和 format。这与按实体范围筛选的 list 不同。

filtered-list -- 按类别筛选并列出 worklog 记录。需要提供 profile_type、profile_id 和 filter（"authored" 或 "interjections"）。可选提供 type（"info" 或 "interjection"）作为记录类型的子筛选器。支持 limit、offset 和 format。

summary -- 获取工作区或共享的简要 worklog 计数。需要提供 profile_type 和 profile_id。返回记录总数、按记录类型划分的数量、本人撰写的记录数以及待处理插入记录数。支持 format。

approval

针对任务、存储节点、工作日志条目或共享创建的正式审批请求。所有审批操作都要求目标实体已启用工作流。

list -- 列出工作区或共享的审批请求。需要 profile_type 和 profile_id。支持按 status 筛选（pending、approved、rejected），以及 limit（1-200，默认 50）、offset 和 format。

create -- 创建新的审批请求。需要 profile_type、profile_id、entity_type（"task"、"node"、"worklog_entry" 或 "share"）、entity_id 和 description（1-65535 个字符）。可选参数：approver_id（指定审批人的 profile ID，可以是待审核成员）、deadline（YYYY-MM-DD HH:MM:SS ——不是 ISO-8601）、node_id（制品引用）。

details -- 获取审批请求的完整详情，包括审批人列表和处理结果。需要 profile_type、profile_id 和 approval_id（不透明的字母数字标识符）。支持 format。

resolve -- 处理审批请求。需要 profile_type、profile_id、approval_id 和 resolve_action（"approve" 或 "reject"）。可选参数：comment（最多 5000 个字符）。只有指定的审批人才能处理。

bulk-create -- 为共享中的每个文件和备注批量创建节点审批（最多 50 个节点）。需要 profile_id 和 description（1-65535 个字符）。可选参数：approver_id（可以是待审核成员）、deadline（YYYY-MM-DD HH:MM:SS ——不是 ISO-8601）。仅适用于共享，且仅限成员/管理员使用。

bulk-approve -- 批量批准共享中的所有待处理审批。需要 profile_id。可选参数：comment（最多 5000 个字符）。跳过已过期的审批（version_match=false）。访客可以批准分配给自己的审批。

bulk-reject -- 批量拒绝共享中的所有待处理审批。需要 profile_id。可选参数：comment（最多 5000 个字符）。跳过已过期的审批（version_match=false）。访客可以拒绝分配给自己的审批。

filtered-list -- 按类别筛选并列出审批。需要 filter（"pending"、"created"、"assigned" 或 "resolved"）。可选参数：profile_type 和 profile_id，用于指定工作区/共享范围；省略两者则查看跨配置文件的用户级数据（/user/approvals/list/{filter}）。注意：assigned 筛选条件仅在提供 profile_type/profile_id 时可用；跨配置文件的用户级查询不支持此筛选条件。支持 status 子筛选，以及 limit、offset 和 format。

summary -- 获取工作区或共享的简要审批计数。需要 profile_type 和 profile_id。返回由我创建和分配给我的审批明细，包括待处理、已批准和已拒绝的数量。支持 format。

update -- 更新待处理的审批。需要 profile_type、profile_id 和 approval_id。以下参数至少提供一个：description（1-65535 个字符）、approver_id（可以是待审核成员）、deadline（YYYY-MM-DD HH:MM:SS ——不是 ISO-8601）、node_id、properties（JSON 对象）。只有待处理的审批才能更新。status、entity_type、entity_id 和 profile_id 不可更改。

delete -- 永久删除审批（任何状态）。需要 profile_type、profile_id 和 approval_id。此操作不可撤销。仅限成员和管理员使用；访客无法使用。

bulk-delete -- 永久删除共享中的所有审批（最多 500 个）。需要 profile_id。删除待处理和已处理的审批。仅限成员和管理员使用；访客无法使用。

todo

作用域限定于工作区和共享的简单扁平待办清单。不支持嵌套。所有待办操作都要求目标实体已启用工作流。

list -- 列出工作区或共享中的待办事项。需要 profile_type 和 profile_id。支持 filter_done（布尔值）、sort_by（created、updated、title）、sort_dir、limit（1-200，默认值为 100）、offset 和 format。

create -- 创建新的待办事项。需要 profile_type、profile_id 和 title（1-500 个字符）。可选参数 assignee_id（可以是待加入成员）。

details -- 获取待办事项的完整详情。需要 todo_id（不透明的字母数字字符串）。支持 format。

update -- 更新待办事项。需要 todo_id。支持 title、assignee_id（可以是待加入成员）和 done。

delete -- 软删除待办事项。需要 todo_id。具有破坏性。

toggle -- 切换待办事项的完成状态。需要 todo_id。在已完成和未完成状态之间切换。

bulk-toggle -- 一次性设置多个待办事项的完成状态。需要 profile_type、profile_id、todo_ids（待办事项 ID 数组，最多 100 个）和 done（布尔值：true 表示标记为已完成，false 表示标记为未完成）。

filtered-list -- 按类别筛选并列出待办事项。需要 profile_type、profile_id 和 filter（"assigned"、"created"、"done" 或 "pending"）。支持 limit、offset 和 format。

summary -- 轻量级地统计工作区或共享中的待办事项数量。需要 profile_type 和 profile_id。返回总数、已完成数、待处理数、分配给我的数量以及由我创建的数量。支持 format。

apps

交互式 MCP App 小组件的发现与启动。这些小组件是交互式 HTML5 界面，可在 Agent 对话中呈现。

list -- 列出所有可用 MCP App 小组件及其元数据（标题、描述、支持的工具、支持的操作、资源 URI）。

details -- 获取特定小组件的完整元数据。需要 app_id（小组件名称，例如 "file-picker"）。

launch -- 在工作区或共享的上下文中启动小组件。需要 app_id、profile_type（"workspace" 或 "share"）（也接受 context_type）和 profile_id（19 位配置文件 ID）（也接受 context_id）。返回可供渲染的小组件 HTML 内容。

get-tool-apps -- 查找与特定工具领域相关联的小组件。需要 tool_name（例如 "storage"、"ai"、"comment"）。返回为该工具的操作提供界面的各个小组件。

---

10. Code Mode（无头 Agent）

从无头 Agent（Claude Code、Cursor、Continue 等）连接时，服务会自动启用 Code Mode——一种轻量级替代方案，无需使用完整的 19 个工具。Code Mode 总共提供 4 个工具：

工具	用途
auth	身份验证（signin、signup、API keys、PKCE、2FA）
upload	文件上传（分块、文本、网页导入）
search	查找内容（文件、笔记、文件夹）或发现 API 端点
execute	对 Fast.io 发起经过身份验证的 API 调用

支持 MCP Apps 的客户端（Claude Desktop、Cline）仍会收到完整的 19 个工具，以及 6 个 app-* 小组件工具（注册表中的每个小组件对应一个）。未知客户端默认使用完整工具集。

查找内容（请优先使用此方式）

当用户询问“查找我的 X”“我的 Y 在哪里”或“我有 Z 吗”，且内容位于其 Fast.io 数据中时，请调用 search，不要设置 target（默认值为 content）。不要通过 execute 手动拼接 /storage/search/ 调用——search 工具已封装正确的端点，会搜索多个工作区并规范化结果。

search query="tax return 2023"                               (fan out across ALL workspaces)
search query="Q3 budget" workspace_id="1234567890123456789"  (scoped to one workspace)
search query="invoice" share_id="9876543210987654321"        (scoped to one share)
search query="meeting notes from last quarter" details=true  (semantic, with full node details)

结果格式：

{
  "results": [
    { "id": "<30-char node id>", "type": "file", "name": "tax-return-2023.pdf",
      "parent_id": "<folder id>", "workspace_id": "1234…",
      "score": 0.87, "snippet": "…2023 tax return for…" }
  ],
  "total": 1,
  "scope": { "type": "workspace", "workspace_ids": ["1234…"] },
  "next_offset": 50
}

关键词搜索与语义搜索： 默认情况下，工作区智能功能处于关闭状态，搜索只匹配文件和文件夹的名称——速度快且免费。开启智能功能后，同一端点还会对已索引的文档内容执行语义（RAG）搜索，并返回 score 和 snippet 字段。使用 execute POST /workspace/{id}/update/ intelligence=true 开启智能功能。索引每个文档页约需 10 个点数；查询本身免费。

缩小语义搜索范围： 传入 folders_scope（nodeId:depth 对，深度为 1-10）可将结果限制在某个子树内；传入 files_scope（nodeId:versionId 对）可将结果限制为特定文件版本。智能功能关闭时，这两项都会被静默忽略。

范围：

• 提供 workspace_id → 搜索单个工作区，支持 limit/offset 分页。
• 提供 share_id → 搜索单个共享项。
• 两者均未提供 → 并发搜索前 10 个可访问的工作区（并发数为 4）。跨多个工作区搜索不支持分页；如需深度分页，请传入明确的 workspace_id。

search 工具（API 端点发现）

当你需要调用尚未由代码模式工具（auth、upload、search 的内容模式）封装的 REST 端点时，请将 target 设为 "api"，以搜索 API 规范。工具会返回匹配的端点及其方法、路径、参数和说明——将选定的路径传给 execute。

search target="api" query="list files in workspace" tag="storage"
search target="api" query="create share" tag="share"
search target="api" query="authentication"
search target="api" query="pagination" include_concepts=true

参数（所有模式）：

• query（字符串，必填）——关键词、端点路径或概念（API 模式），或你要查找的内容（内容模式）
• target（枚举，可选）——"content"（默认值）或 "api"

参数（仅内容模式）：

• workspace_id（字符串，可选）——用于限定单个工作区的 19 位工作区 ID
• share_id（字符串，可选）——用于限定单个共享项的 19 位共享 ID
• limit（数字，可选）——最多返回 1-200 条结果（单一范围搜索默认值为 50，多工作区搜索时每个工作区为 25）
• offset（数字，可选）——单一范围搜索的分页偏移量
• details（布尔值，可选）——包含完整节点详情（预览、AI 状态、元数据）。默认值为 false
• folders_scope（字符串，可选）——将语义搜索限定在文件夹子树内（需要启用智能功能）
• files_scope（字符串，可选）——将语义搜索限定在特定文件版本内（需要启用智能功能）

参数（仅 API 模式）：

• tag（字符串，可选）——按领域筛选：auth、workspace、storage、ai、share、upload、org、user、member、comment、event、metadata 等
• include_concepts（布尔值，可选）——包含概念文档（分页、ID、错误）。默认值为 true。

execute 工具

对 Fast.io REST API 发起经过身份验证的 API 调用。请先使用 search 查找端点。

方法：

• get——GET 请求，可带查询参数
• post——POST 请求，使用表单编码的请求体（默认 API 格式）
• postJson——POST 请求，使用 JSON 请求体
• delete——DELETE 请求
• put——PUT 请求，使用表单编码的请求体

系统会自动注入身份验证令牌。路径参数必须由调用方填写（将 {workspace_id} 替换为实际 ID）。对于多步骤操作，请依次发起多次 execute 调用。

execute method="get" path="/org/1234567890123456789/list/workspaces/"

execute method="post" path="/workspace/1234567890123456789/storage/root/createfolder/" body={"name": "reports"}

execute method="postJson" path="/workspace/1234567890123456789/storage/root/createnote/" body={"name": "summary.md", "content": "# Summary"}

参数：

• method（枚举，必填）——HTTP 方法："get"、"post"、"postJson"、"delete"、"put"
• path（字符串，必填）——API 端点路径（例如 '/orgs/list/'、'/workspace/{workspace_id}'）
• body（对象，可选）——请求体（post/put 使用表单编码，postJson 使用 JSON）
• params（对象，可选）——附加到 URL 的查询参数
• timeout_ms（数字，可选）——超时时间，单位为 ms（默认值为 30000，最大值为 60000）

响应处理

execute 工具会自动处理三种响应类型：

• JSON（大多数端点）——解析为标准的 Fast.io API 信封
• 文本（Markdown、纯文本等）——以 { content, content_type, http_status } 的形式返回
• 二进制（图片、PDF 等）——返回元数据，并提示使用 download:// MCP 资源

在代码模式下读取笔记

使用 /readnote/（返回 JSON），而不是 /read/（返回原始二进制）：

execute method="get" path="/workspace/{workspace_id}/storage/{node_id}/readnote/"

读取上传的文件（非笔记）时，请使用 download:// MCP 资源：

resources/read uri="download://workspace/{workspace_id}/{node_id}"