Fast.io MCP 服务器 —— AI 智能体指南

版本：1.123最后更新：2026-03-16

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

版本化指南。本指南为版本化指南，随每次服务器发布而更新。文档顶部的版本号用于追踪工具参数、ID 格式和 API 行为变更。如果您遇到意外错误，可能是自您上次阅读以来指南版本已发生变化。

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

---

1. 概述

面向智能体团队的工作区。通过一个免费的 API，即可实现协作、共享和 AI 查询。

Fast.io为智能体团队提供工作空间——在这里，智能体可以与其他智能体及人类协同工作。您可以上传输出内容、创建品牌化分享链接、利用内置AI对文档进行提问，并在任务完成后将一切移交给人类处理。无需管理基础设施，无需设置订阅，也无需提供信用卡信息。

Fast.io解决的问题

智能体团队——即相互协作并与人类协同工作的智能体群体——需要一个共享的工作场所。目前，智能体们通常需要拼凑使用S3存储桶、预签名URL、电子邮件附件和自定义下载页面。每个智能体都在重复构建协作方式，缺乏一个能让智能体与人类查看相同文件、追踪活动记录并交接工作的共享工作空间。

当智能体需要理解文档内容——而非仅仅是存储文档时——它们必须下载文件、解析数十种格式、构建搜索索引并管理自己的RAG流程。而对于"这份文档说了什么？"这样简单的问题，这需要大量基础设施支持。

问题	Fast.io解决方案
智能体团队缺乏共享工作空间	提供支持文件预览、版本控制和AI功能的智能体与人类协作工作空间
智能体间协作缺乏结构化机制	配备活动动态流、评论功能和团队成员实时同步的共享工作空间
与人类分享成果很麻烦	专用分享功能（发送、接收、交换），支持链接分享、密码保护和过期设置
从人类那里收集文件更困难	接收分享功能让人类直接上传到您的工作区——无需电子邮件附件
理解文档内容	内置AI读取、总结并回答关于您文件的问题
从零开始构建RAG管道	启用工作区智能功能后，文档会自动索引、总结并可查询
在大量文件中找到正确的文件	语义搜索通过含义查找文档，而不仅仅是文件名
将项目移交给人类	一键所有权转移——人类获得组织，代理保留管理员访问权限
追踪发生的情况	完整的审计追踪，配备AI驱动的活动总结
成本	免费。50 GB存储空间，每月5,000积分，无需信用卡

MCP服务器

该MCP服务器提供了19个整合工具，全面覆盖Fast.io REST API的所有功能。每个需要身份验证的API端点都有对应的工具操作，且服务器会自动处理会话管理。

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

服务器端点

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

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

• 可流式传输的HTTP位于/mcp——这是新集成的首选传输方式。
• SSE（服务器发送事件）位于/sse——为保持向后兼容性而保留的旧式传输方式。

MCP资源

该服务器提供静态MCP资源、小部件资源及文件下载资源模板。客户端可通过resources/list和resources/readURI

名称	描述	MIME类型	skill://guide
skill-guide	包含全部19个工具、工作流和平台文档的完整代理指南（即本文档）	text/markdown	session://status
session-status	当前认证状态：	authenticated布尔值,user_id,user_email,token_expires_at（Unix纪元时间戳）,token_expires_at_iso（ISO 8601格式）,scopes（原始权限字符串或null）,scopes_detailscopes_detail（包含实体名称/域/父级的已水合作用域对象数组，或为空），代理名称（字符串或为空）	application/json
widget://*	小部件HTML	交互式HTML5小部件（共6个）——使用应用工具来发现和启动	text/html

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

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

大小不超过 50 MB 的文件会以内联方式返回，内容为 base64 编码的二进制数据。更大的文件将返回一个文本回退，其中包含指向 HTTP 直通端点（见下文）的 URL。该下载工具响应包含一个resource_uri字段，其中包含每个文件的相应 URI。

动态资源列表：经过身份验证后，工作区和共享文件资源会通过resources/list动态列出。MCP 客户端（例如 Claude Desktop 的@提及文件选择器）无需任何工具调用即可发现可用文件。最多枚举10个工作区和10个共享，每个列出最多25个最近更新的根级文件。资源显示为“工作区名称 / 文件名.扩展名”或“共享标题 / 文件名.扩展名”。结果在每次会话中缓存1分钟。仅列出根级文件——不会递归枚举子目录。使用存储工具并执行列表操作以浏览更深层级。快速共享模板保持仅为模板状态，不支持动态枚举。

MCP 提示

服务器注册的MCP提示会以用户可点击的应用启动器形式，显示在客户端的“从...添加”/“+”菜单中。这些主要面向桌面版MCP客户端（例如Claude Desktop）；代码模式客户端（Claude Code、Cursor）不会展示提示。

提示名称	描述
应用：选择工作区或组织	启动工作区选择器，以浏览组织、选择工作区并管理共享
应用：选取文件	启动内置工作区导航器的文件选择器，用于浏览、搜索和选择文件
应用：打开工作流	启动工作流管理器（如果只有一个工作空间则自动选择，否则先打开工作空间选择器）
应用：上传文件	启动上传器，支持拖放上传、进度跟踪和文本文件创建功能
应用：可用应用	列出所有可用的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操作在空间上启用工作流。启用工作流在使用这些工具之前。请参阅完整代理工作流第6节中的完整模式示例。

最佳实践（重要）：在执行状态变更操作（上传文件、创建分享、更改任务状态、成员变更、文件移动/删除）后，请附加一条工作日志条目，描述您做了什么以及为什么这样做。如果没有工作日志条目，人类在审查工作空间时将无法看到代理的工作。对于多个相关操作（例如，上传多个文件），您可以在批量操作完成后一次性记录，而不是在每个单独操作后记录。工作日志条目是只追加且永久性的。

附加参考资料

• 代理指南（本文件）： /skill.md在MCP服务器上——工具文档、工作流和约束条件。
• REST API参考： https://api.fast.io/llms.txt——底层Fast.io API的端点文档。
• 平台指南： references/REFERENCE.md——功能、代理计划详情、关键工作流和升级路径。

---

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

调用除以下这些未经验证的工具外的任何工具之前，都需要进行身份验证：

• auth包含以下操作：signin（登录）、signup（注册）、set-api-key（设置API密钥）、pkce-login（PKCE登录）、email-check（邮箱检查）、password-reset-request（密码重置请求）、password-reset
• （密码重置）download包含操作：

quickshare-details

（快速共享详情）

选择正确的方法

如果您正在独立操作（存储文件、运行工作流、为用户构建工作空间），请通过authactionsignup创建您自己的代理账户。代理账户可获得免费代理计划（50 GB存储空间，5,000 月度积分），并可在准备就绪时将组织转移给人类用户。这是自主代理的推荐路径。具体步骤请参见下方代理账户创建部分。

选项 2：协助人类用户 —— 使用他们的 API 密钥

如果已有 Fast.io 账户的人类用户希望您帮助管理其文件、工作空间或共享内容，他们可以为您创建一个 API 密钥供您使用。无需单独的代理账户 —— 您将以该人类用户的身份进行操作。人类用户可在 设置 -> 设备与代理 -> API 密钥 处创建密钥（直接链接：https://go.fast.io/settings/api-keys）。调用auth时，使用 action 参数set-api-key以及用于身份验证的密钥——该密钥会被验证并自动存储在会话中。API密钥可作为Bearer令牌使用，默认情况下拥有与账户所有者相同的权限。密钥可以选择性地限定到特定的组织、工作空间或共享范围（使用与OAuth令牌相同的范围系统），并标记一个代理名称以用于追踪，还可设置过期日期。未限定范围的密钥除非被撤销，否则不会过期。代理也可以通过编程方式使用auth操作api-key-create、api-key-update、api-key-list、api-key-get和api-key-delete来管理API密钥。

选项3：被邀请加入人类组织的代理账户

如果您希望拥有自己的代理身份，但需要在人类现有组织内工作，可以使用auth操作来创建代理账户。注册，然后让用户邀请您加入他们的组织，使用memberactionadd(entity_typeorg) 或加入工作区，使用memberactionadd(entity_typeworkspace)。或者，用户也可以通过用户界面邀请：设置 -> 您的组织 -> 管理成员。这样您就可以访问他们的工作区和共享内容，同时保持您自己的账户独立。在接受邀请后，使用useractionaccept-all-invitations，然后使用authactionsignin进行常规身份验证。注意：如果用户仅邀请你加入工作区（而非组织），该组织将显示为外部组织——请参见内部与外部组织（位于组织设置部分）。

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

若您不希望通过代理传输密码，可使用基于浏览器的PKCE登录方式。调用auth操作pkce-login（可选择性附加邮箱提示）以获取登录链接。用户需在浏览器中打开该链接完成登录（邮箱密码登录或Google/Microsoft等SSO登录）并授权访问。浏览器将显示授权码，用户需将其复制回代理程序。随后调用auth操作pkce-complete并提交该授权码以完成登录流程。这是最安全的选项——所有凭证均不经过代理程序传输。

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授予对用户拥有成员资格的所有共享的直接访问权限，绕过工作空间/组织的继承关系

Theagent_name参数控制用户在审批屏幕上看到的内容——屏幕上会显示"[agent_name]将代表您进行操作"。如果省略，则只显示客户端名称。请使用描述性名称，以便用户知道是哪个代理在请求访问。

按 scope_type 划分的审批流程：

• user（默认）：完整账户访问权限。用户会看到一个简单的批准/拒绝提示，没有实体选择器。
• 组织，工作空间：用户会看到一个实体选择界面，列出了他们可访问的实体（带复选框）以及一个只读/读写权限切换开关。用户选择要授予访问权限的实体，然后批准或拒绝。
• 所有组织、所有工作空间、所有共享：用户会看到请求的通配符访问权限摘要（无实体选择器），然后批准或拒绝。

为了向后兼容，MCP服务器默认设置为scope_type="user"。

场景	推荐方法
自主操作、存储文件、为用户构建	在您自己的组织中创建一个代理账户（选项1）
帮助人类管理其现有账户	请该人类为您创建一个API密钥（选项2）
在人类组织中，以您自己的身份开展工作	创建一个代理账户，让人类邀请你（选项3）
构建一些东西交给人类	创建一个代理账户，构建它，然后转移组织（选项1）
无需通过代理发送密码的登录方式	基于浏览器的PKCE登录（选项4）

按账户类型的信用额度：代理账户（选项1、3）在信用额度用尽时可以将组织转移给人类——参见第3节的所有权转移。人类账户（选项2）不能使用转移/认领API；请引导人类在https://go.fast.io/settings/billing或通过orgactionbilling-create升级他们的计划。

标准登录流程

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

代理账户创建

创建新账户时（上述选项1和3），代理必须使用认证操作注册该操作会自动以agent=true参数进行注册。切勿注册为人类账户。代理账户提供以下功能：

• account_type设置为"agent"
• 自动分配免费代理计划
• 启用了转移/认领工作流，以便将组织移交给人类

步骤：

1. 可选地调用认证操作邮箱检查使用期望的电子邮箱在尝试注册前，先验证该邮箱是否可用于注册。
2. 调用认证操作注册并附带名字、姓氏、电子邮箱以及密码。agent=true标志由 MCP 服务器自动发送。
3. 账户创建后，会话会自动建立——代理立即登录。
4. 验证您的电子邮箱（在使用大多数端点前必需）：调用认证操作电子邮件验证使用电子邮件发送验证码，然后再次调用验证操作电子邮件验证，并提供电子邮件和电子邮件令牌以验证验证码。
5. 无需信用卡。无试用期。无过期限制。账户永久有效。

双重认证流程

1. 调用验证操作登录，并提供电子邮件和密码。
2. 如果响应中包含two_factor_required: true，返回的令牌具有有限的作用域。
3. 调用auth操作2fa-verify并附带双因素认证代码（TOTP、短信或WhatsApp）。
4. 服务器会自动将有限作用域的令牌替换为全作用域令牌。

敏感操作的实时双因素认证

当账户启用了双因素认证时，某些API端点要求每个请求都进行双因素认证验证。这些操作除了常规认证外，还需要一个有效的双因素认证令牌参数（6位数的TOTP或短信/电话/WhatsApp代码）：

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

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

工作流程：

1. 检查2FA状态：authaction2fa-status— 如果state是"enabled"，则需要行内2FA。
2. 提示用户从其验证器应用程序输入TOTP代码，或通过authaction2fa-send发送代码。
3. 将代码作为token参数传递给api-key-create或api-key-delete。

提示：API密钥认证（authactionset-api-key) 完全绕过内联双因素认证检查。如果代理已通过API密钥完成认证，则这些操作无需令牌。

浏览器登录流程

1. 调用认证操作pkce-login（可选包含邮箱以预填登录表单、scope_type以请求范围访问权限，以及agent_name以标识代理）。
2. 工具返回一个登录链接——呈现给用户在浏览器中打开。
3. 用户进行登录（邮箱/密码或单点登录）。
4. 用户将看到授权屏幕，其中显示agent_name（若未提供则显示客户端名称）。根据scope_type：对于用户他们只是批准；对于组织/工作空间他们选择特定实体和只读/读写权限；对于所有组织/所有工作空间/所有共享他们查看通配符访问摘要。
5. 用户点击批准。浏览器显示授权码。用户复制它。
6. 调用认证操作PKCE完成并使用代码以换取访问令牌。
7. 会话会自动建立——所有后续的工具调用都经过认证。如果授予了限定范围的访问权限，范围和代理名称包含在响应中并存储在会话中。

检查会话状态

• authactionstatus-- 检查本地 Durable Object 会话。不进行 API 调用。返回认证状态、用户 ID、电子邮件、令牌过期时间、作用域和 agent_name。
• authactioncheck-- 根据 Fast.io API 验证令牌。如果令牌仍然有效，则返回用户 ID。

会话过期

JWT 令牌有效期为1 小时。API 密钥默认不会过期，但可以通过api-key-create或api-key-update命令，使用key_expires参数选择性地设置过期时间。当 JWT 会话过期或有时限的 API 密钥过期时，工具调用会返回一个明确的错误，指示需要重新认证。调用auth操作登录以建立新会话。MCP服务器不会自动刷新令牌。

提示：对于长时间运行的会话，请使用认证操作状态在开始多步骤工作流前检查令牌的剩余有效期。如果令牌即将过期，请先重新认证，以避免工作流中途中断。

退出登录

调用认证操作退出登录以从Durable Object中清除存储的会话。

---

3. 核心概念

组织

组织是收集工作空间的顶级容器。一个组织可以代表一家公司、一个业务部门、一个团队，或者仅仅是您个人的集合。每个用户都属于一个或多个组织。组织拥有：

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

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

重要提示：创建组织时，代理必须使用orgactioncreate操作，该操作会自动分配billing_plan: "agent"。这确保组织获得免费的代理套餐（50 GB，每月5,000积分）。请勿为代理创建的组织使用任何其他计费套餐。

组织发现（重要）

要发现所有可用组织，代理必须调用以下两个操作：

1. orgaction列表-- 返回您作为直接成员所在的内部组织 (member: true)
2. 组织操作发现外部-- 仅返回您通过工作区成员身份访问的外部组织 (member: false)

一个仅检查组织操作列表的代理将完全错过外部组织，并且不会发现其受邀加入的工作区。当人类邀请代理协助特定项目时，外部组织是最常见的模式——他们将代理添加到工作区，但不会添加到组织本身。

内部与外部组织

内部组织(member: true) -- 您创建或受邀以成员身份加入的组织。您拥有组织级别的访问权限：可以查看所有工作空间（根据权限设置），如果是管理员则可以管理设置，并且会出现在该组织的成员列表中。

外部组织(成员：否) -- 您只能通过工作空间成员身份访问的组织。您可以查看该组织的名称和基本公开信息，但无法管理组织设置、查看其他工作空间或在组织级别添加成员。您的访问权限仅限于您被明确邀请的特定工作空间。

示例：一位用户邀请您的智能体加入他们的“Q4 报告”工作空间。您可以在该工作空间中上传文件、运行 AI 查询并进行协作。但您无法在他们的组织中创建新工作空间、查看他们的账单信息或访问他们的其他工作空间。该组织会通过组织操作discover-external-- 而不是组织操作list显示。如果该用户后来邀请您加入组织本身，该组织会从外部组织转移到内部组织。

工作空间

工作空间是组织内的文件存储容器。每个工作空间包含：

• 其独立的成员及角色设置（所有者、管理员、成员、访客）。
• 一个存储树用于管理文件和文件夹（存储节点）。
• 可选的AI功能支持基于RAG的智能对话。
• 共享功能可在工作空间内创建分享链接。
• 归档/解归档生命周期管理。
• 免费代理方案包含50 GB存储空间单次上传文件最大支持1 GB。
• 文件版本控制——每次编辑生成新版本，旧版本可恢复。
• 全文与语义搜索——可通过名称、内容查找文件，或根据语义定位文档。

工作空间由19位数字型档案ID唯一标识。

智能：开启或关闭

工作区有一个智能开关，用于控制AI功能是否激活。

⚠️ 成本警告：启用智能功能会产生高昂的文档处理成本（每上传一页文档消耗10个积分）。对于一个拥有数百或数千页文档的工作区，成本会迅速累积。除非用户明确需要对大量文档进行RAG查询或AI驱动的语义搜索，否则请勿启用智能功能。大多数工作流程（文件存储、共享、协作、一次性文件分析）在不启用该功能的情况下也能完美运行。

智能功能关闭（推荐的默认设置）-- 工作区是纯粹的文件存储。您仍然可以直接将文件附加到AI聊天对话中（最多20个文件，总计200 MB）并对其提问 -- 无需处理成本。对于大多数使用场景（文件存储、共享、协作、项目协调以及分析少量特定文件）来说，这是正确的选择。

智能功能开启（仅在需要时）-- 工作区将变为一个由AI驱动的知识库。上传的每个文档和代码文件都会自动被处理、总结和建立索引。仅当用户需要以下两种能力之一时才启用此功能：

1. 跨多文档的RAG查询——将AI聊天的范围限定到整个文件夹或完整工作区，并针对所有已索引内容提问。AI会检索相关段落并给出附有引用的答案。当您拥有大量文档并需要跨所有文档进行搜索时，这非常有用。
2. AI驱动的语义搜索——通过含义而非仅关键词来查找文件。即使文件名中不包含“赔偿条款”这几个字，“给我看看包含赔偿条款的合同”这样的指令依然有效。

智能功能还支持自动摘要和自动元数据提取，但仅凭这些功能并不足以证明信息摄入成本是合理的。

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

默认行为：MCP服务器在创建工作区和共享时，默认将智能功能设置为关闭。要启用智能功能，您必须显式传递intelligence: "true"。除非用户明确要求进行跨多文档的RAG查询或AI驱动的语义搜索，否则请勿启用智能功能。不要“以防万一”而推测性地启用它——该功能随时可以后续启用，但信息摄入成本（10积分/页）会立即产生且不可退还。

Agent use case:为每个项目或客户创建一个工作区。在存储和协作时保持智能功能关闭。仅当用户需要跨大型文档集查询时才启用它。上传报告、数据集和交付成果。邀请其他代理和人类利益相关者。所有内容都井井有条、可搜索且具有版本控制。

有关 AI 聊天类型、文件上下文模式、AI 状态以及智能功能如何影响它们的完整详细信息，请参阅下方AI 聊天部分。

共享空间

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

模式	功能	代理用例
发送	接收者可下载文件	交付报告、导出内容、生成内容
接收	接收者可上传文件	收集文档、数据集、用户提交内容
交换	既可上传也可下载	协作式工作流，审查周期

门户

一个门户是从工作区文件夹创建的Send分享（storage_mode=workspace_folder）。门户始终是仅发送的——收件人可以查看和下载文件，但无法上传。门户显示链接工作区文件夹的实时内容，因此对文件夹的任何更改都会立即反映出来。门户非常适合在不复制文件的情况下向外部发布文件夹内容（例如，客户交付物文件夹）。要创建门户：请使用分享操作创建并设置share_type: "send"、storage_mode: "workspace_folder"以及folder_node_id（或create_folder: true）。

分享功能

• 密码保护-- 链接访问需密码验证
• 有效期设置-- 共享链接将在设定周期后自动失效
• 下载管控-- 启用或禁用文件下载功能
• 访问权限等级-- 仅限成员、组织成员、注册用户或公开访问（任何持有链接者）
• 品牌定制-- 背景图片、渐变色彩、强调色调、品牌标识
• 下载后消息推送-- 下载完成后显示定制化信息与链接
• 最多可设置3个定制链接用于情境说明或行动号召
• 访客实时聊天-- 允许共享接收方实时提问
• AI智能自动命名-- 共享内容自动生成智能标题
• 动态通知-- 文件收发时获取实时通知
• 评论管控功能配置谁可以查看和发布评论（所有者、访客或两者）

两种存储模式

当通过共享操作创建共享时，storage_mode参数决定了文件如何存储：

• independent（独立存储，默认）——共享拥有其独立的存储空间。文件直接添加到共享中，并且独立于任何工作空间。这会创建一个自包含的共享——工作空间文件的更改不会影响共享，反之亦然。适用于最终交付物、合规包、归档报告，或任何您希望获得不可变快照的场景。

• workspace_folder（工作空间支持）——共享由工作空间中的特定文件夹支持。共享显示该文件夹的实时内容——在工作空间文件夹中添加、更新或删除的任何文件会立即反映在共享中。没有文件重复，因此没有额外的存储成本。要创建工作空间文件夹共享，请传递storage_mode=workspace_folder和folder_node_id={folder_opaque_id}在创建共享时。注意：由于内容是实时的，工作区文件夹共享不允许设置过期日期。

对于共享接收者来说，两种模式看起来是一样的——都是一个带有品牌标识的共享，包含文件预览、下载控制和所有共享功能。区别在于内容是快照（独立）还是实时视图（工作区文件夹）。

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

股份通过一个19位数字的档案ID进行标识。

代理用例：生成季度报告，创建一个带有客户品牌标识的Send分享，设置30天有效期，并分享链接。客户将看到一个专业的、带有品牌标识的页面，可以即时预览文件——而非原始的下载链接。

存储节点

文件和文件夹以存储节点的形式表示。每个节点都有一个不透明的ID（一个30位的字母数字字符串，显示时带有连字符，例如f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4）。特殊值root指的是工作区或分享的根文件夹，而trash指的是回收站文件夹。

对存储节点的关键操作包括：列表、创建文件夹、移动、复制、重命名、删除（移至回收站）、清除（永久删除）、恢复（从回收站恢复）、搜索、添加文件（链接上传）以及添加链接（创建分享引用）。

节点具有版本。每次文件修改都会创建一个新版本。可以列出版本历史，并可以将文件恢复到之前的版本。

冲突解决（默认为REPLACE）：当文件操作在目标文件夹中遇到同名文件时，默认行为是替换（覆盖）现有文件：

• 上传（添加文件）—— 会静默覆盖现有文件。先前的内容会作为版本条目保留，可通过存储操作版本列表/版本恢复进行恢复。
• 移动 / 复制—— 将现有的冲突文件移至回收站，然后完成操作。旧文件可从回收站恢复。
• 从回收站恢复—— 将现有的冲突文件移至回收站，然后执行恢复。
• 文件夹冲突和类型不匹配（文件与文件夹）仍会回退到重命名（例如文件夹 (2)）。

这意味着上传一个与现有文件同名的文件将覆盖它，而不是像report (2).pdf那样创建一个重命名的副本。如果您需要多个同名文件共存，请在上传前对它们进行重命名。

笔记

笔记是一种存储节点类型（与文件和文件夹并列），它将 Markdown 内容直接存储在服务器上。它们存在于与文件相同的文件夹层次结构中，像任何其他节点一样有版本控制，并在存储列表中以type: "note"的形式出现。

创建和更新笔记

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

创建：提供workspace_id、parent_id（文件夹不透明ID或"root"）、name（必须以.md结尾，最多100个字符）以及content（markdown文本，最大100 KB）。

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

更新：提供workspace_id、node_id，以及至少一个名称（必须以.md结尾）或内容（最大100 KB）。

约束条件	限制
内容编码	有效的UTF-8（UTF8MB4）。无效的字节序列和控制字符（\p{C}除了\t、\n、\r）会被去除。
内容大小	最大100 KB
文件名	1-100个字符，必须以.md
结尾	Markdown验证
代码块和强调标记必须平衡	每10秒2次，每60秒5次

笔记作为长期知识基础

在智能工作区中，笔记会像上传的文档一样被自动收录和索引。这使得笔记成为一种随时间积累知识的方式——存储在笔记中的任何事实、背景或决策，都会成为未来AI查询的基础材料。

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

关键行为：

• 启用工作区智能后，笔记会被收录用于RAG
• 文件夹范围内的笔记会包含在范围查询中
• 具有ai_state: ready状态的笔记可通过RAG搜索
• 笔记也可以通过files_attach直接附加到聊天（请检查存储详情中ai.attach是否为true

）

• 存储项目背景、决策和理由。几个月后，询问“我们为什么选择供应商X？”，AI会检索相关记录。
• 将研究发现保存在笔记中。未来的AI对话会自动将这些发现作为背景参考。
• 创建参考文档（如风格指南、命名规范），这些文档将为工作空间中的所有未来AI查询提供信息。

其他笔记操作

笔记支持与文件和文件夹相同的存储操作：移动（通过存储操作移动）、复制（存储操作复制）、删除/移至回收站（存储操作删除）、恢复（存储操作恢复）、版本历史（存储操作版本列表），以及详情（存储操作详情）。

将用户链接至笔记

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

AI聊天

AI聊天允许代理就存储在工作区和共享中的文件提问。提供两种聊天类型，每种类型具有不同的文件上下文选项。

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

两种聊天类型

• chat— 基本的AI对话，没有来自工作区索引的文件上下文。仅用于一般性问题。
• chat_with_files— 以您的文件为基础的AI。提供文件上下文有两种互斥的模式：
  • 文件夹/文件范围（RAG）— 限制检索搜索空间。需要启用智能功能；文件必须处于就绪AI状态。
  • 文件附件— 由AI直接读取的文件。无需智能功能；文件必须在存储详细信息中具有ai.attach: true（文件必须是AI分析支持的类型）。最多20个文件，总计200 MB。

自动升级：如果您创建一个包含type=chat但包含files_scope、folders_scope或files_attach时，系统会自动将类型提升为chat_with_files。您无需担心类型设置得完全正确——当存在文件参数时，意图是明确的。

这两种类型在相关时都会用网络知识来增强答案。

文件上下文：范围与附件

对于chat_with_files，请选择以下互斥方法之一：

功能	文件夹/文件范围（RAG）	文件附件
工作原理	限制RAG搜索空间	AI直接读取文件
需要智能处理	是	不
文件就绪要求	ai_state: 就绪	ai.attach: 是
最适合	大量文件，知识检索	特定文件，直接分析
最大引用数	100个文件夹引用（子文件夹树扩展）或100个文件引用	20个文件 / 200 MB
默认（未指定范围）	整个工作区	不适用

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

• folders_scope— 逗号分隔nodeId:深度配对（深度1-10，最多100个子文件夹引用）。定义搜索边界 — RAG后端会自动在指定范围的文件夹内查找文档。只需传递文件夹ID和深度；无需枚举单个文件。一个包含数千个文件但子文件夹很少的文件夹可以正常工作。
• files_scope— 逗号分隔nodeId:versionId对（最多100个）。将RAG限制在特定的已索引文件范围内。nodeId是必需的；在配对格式中versionId是必需的，但如果留空（例如，冒号后不填任何内容），它将自动解析为该节点的当前版本。从文件的version字段中获取versionId，该字段位于storageactionlist或details响应中。如果两者都未指定，默认范围是整个工作空间（所有已索引文档）。这是推荐的默认设置——除非您特别需要缩小搜索范围，否则请省略范围参数。
• 附件参数（无需智能处理）：

files_attach——以逗号分隔

• files_attach— comma-separated节点ID:版本ID最多20对，总计200 MB。节点ID是必需的；如果留空，版本ID将自动解析为当前版本。文件是直接读取的，不通过RAG。仅限文件：传递文件夹节点ID会返回406错误。若要将文件夹内容包含在AI上下文中，请改用folders_scope（需要智能功能）。只有存储详情中带有ai.attach: true的文件才能被附加— 使用前请检查。

不要列出文件夹内容并将单个文件ID作为files_scope传递，当您本意是搜索文件夹时 — 请改用folders_scope并传入文件夹的节点ID。files_scope仅用于定位特定的已知文件版本。

作用域 vs 附加： files_scope和folders_scope可缩小RAG搜索范围，且要求启用工作空间智能功能——在未启用智能功能的工作空间上使用会报错。files_attach直接将文件发送给AI而不进行索引，且不受智能功能设置影响，但仅接受文件节点ID（不接受文件夹）。

files_scope/folders_scope和files_attach是互斥的——同时发送两者会报错。

智能与AI状态

工作空间智能开关（参见上文“工作空间”部分）控制上传的文档和代码文件是否被自动提取、总结并索引以供RAG使用。当智能功能启用时，每个文件都有一个ai_state用于指示其准备就绪状态：

状态	含义
已禁用	已为此文件禁用AI处理
等待中	已加入处理队列
进行中	正在接收并建立索引
就绪	完成 - 可用于文件夹/文件范围查询
失败	处理失败

仅具有ai_state: 就绪状态的文件会被包含在文件夹/文件范围搜索中。可通过存储操作详情并指定context_type: "workspace"来检查文件状态。

可附加性 -ai.attach标志

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

字段	类型	含义
ai.state	字符串	AI索引状态 (已禁用、待处理、进行中、就绪、失败)
ai.attach	布尔值	该文件是否可与files_attach
配合使用	ai.summary	布尔值

文件是否已具备AI生成的摘要在使用files_attach前，请确认是真实的。当一个文件的类型支持AI分析（如文档、代码、图像、PDF、电子表格等）或该文件已有先前处理的摘要时，它就是可附加的。具有ai.attach: false（不支持格式、损坏文件或仍在处理中的文件）的文件将被API拒绝。

此标志独立于工作区智能设置——即使智能功能关闭，文件仍可具有ai.attach: true。

何时启用智能功能：您需要对许多文档（范围限定于文件夹或整个工作区）进行RAG查询，或需要使用AI驱动的语义搜索。不要仅为了自动摘要或元数据提取而启用——摄取成本（10积分/页）很高。

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

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

如何提问

针对文件夹/文件范围（RAG检索增强生成）：提出可能匹配索引文件内容的问题。AI会搜索指定范围，检索相关段落并引用它们。

• 好的例子："供应商合同中的付款条款是什么？"
• 好的例子："总结第三季度分析报告中的关键发现"
• 不好的例子："告诉我这些文件的内容" —— 过于模糊，没有具体内容可匹配
• 不好的例子："这个工作区里有什么？" —— 无法有意义地搜索"所有内容"

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

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

个性：该个性参数控制AI回应的语气和长度。在创建聊天或发送消息时传递此参数：

• 简洁模式——简短、精炼的回答
• 详细模式——包含上下文和证据的全面回答（默认模式）

当您需要快速获取事实、是/否答案或简要总结时，请使用简洁模式。当您需要附带支持证据和引用的深入分析时，请使用详细模式（或省略该参数）。该特性也可在每条后续消息中单独覆盖。

通过提问方式控制回答详略：您也可以通过调整问题表述来引导回答的详略程度：

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

将特性设为"简洁模式"并配合直接提问，将生成最简短的答案并消耗最少的AI积分。

聊天参数

创建聊天aiactionchat-create（使用context_type: "workspace"）或aiactionchat-create（使用context_type: "share"）：

• type（必需）—chat或chat_with_files
• query_text（工作区必需，共享可选）— 初始消息，2-12,768 个字符
• personality（可选）—concise或detailed（默认：详细）
• 隐私（可选） —私有或公开（默认：公开）
• 文件范围（可选） —节点ID:版本ID,...（最多100个，需要chat_with_files+ intelligence）。必须提供节点ID；版本ID如果留空则自动解析。省略此项则搜索所有已索引文档（推荐默认设置）。
• 文件夹范围（可选） —节点ID:深度,...（深度1-10，最多100个子文件夹引用，需要chat_with_files+ intelligence）。文件夹范围 = 搜索边界，而非文件枚举。省略以搜索所有已索引文档（推荐默认值）。
• files_attach（可选）—nodeId:versionId,...（最多20个/总大小200 MB，nodeId必需，versionId为空时自动解析，与范围参数互斥）

后续消息

使用以下方式发送后续消息aiactionmessage-send（需附带context_type: "workspace"或"share"参数）。聊天类型继承自父级聊天。每条后续消息都可以更新范围、附件和个性参数。

等待AI响应

创建聊天或发送消息后，AI响应是异步的。消息状态按以下顺序进展：就绪→处理中→完成（或者出错）。

推荐：调用aiactionmessage-read（附带context_type: "workspace"或"share"）并传入返回的message_id。工具会自动轮询（最多15次尝试，间隔2秒，约30秒）。如果在此时间窗口后响应仍在处理中，请使用eventactionactivity-poll并传入工作空间/分享ID，而不是在循环中调用读取操作——详见第7节中的活动轮询。

响应引用

已完成的AI响应包含指向源文件的引用：

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

将用户链接至AI聊天

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

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

分享AI聊天

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

AI分享 / 导出

为文件生成临时的Markdown格式下载URL，可粘贴到外部AI工具（如ChatGPT、Claude等）中。使用ai操作分享-生成（与context_type: "workspace"或"share"）。URL在5分钟后失效。限制：最多25个文件，每个文件最大50 MB，总计100 MB。

个人资料 ID

组织、工作区和分享都通过19位数字的个人资料ID来标识。这些ID在整个工具参数中显示为workspace_id、share_id、org_id、profile_id和member_id。

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

个人资料类型	数字ID	自定义名称
工作区	19位ID	文件夹名称（例如：my-project）
共享	19位ID	URL名称（例如：q4-financials）
组织	19位ID	域名（例如：acme）
用户	19位ID	电子邮件地址（例如：user@example.com）

快速共享

快速共享是针对工作空间中单个文件的临时公共下载链接（不适用于共享）。无需身份验证即可访问。自创建起以秒为单位过期（默认10,800秒 = 3小时，最长604,800秒 = 7天），或通过expires_at. 最大文件大小：1 GB。每个快速共享都有一个不透明的标识符，用于检索元数据和下载文件。

文件预览

上传到 Fast.io 的文件会自动生成预览。当用户打开一个共享或工作区时，他们可以立即看到内容——无需经历“下载并在另一个应用中打开”的繁琐步骤。

支持的预览格式：

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

使用存储操作预览网址（配合context_type: "workspace"或"share"）来生成预览URL。使用storageactionpreview-transform（配合context_type: "workspace"或"share"）进行图像缩放、裁剪和格式转换。

智能体应用场景：您生成的PDF报告不会仅仅显示为下载链接。人类用户可以看到它被内联渲染，可以翻页、放大，并对特定章节进行评论——所有这些操作都无需离开浏览器。

评论与批注

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

• 图像评论——锚定到空间区域（归一化的x/y/width/height坐标）
• 视频评论-- 基于时间戳并带有空间区域选择
• 音频评论-- 基于时间戳或时间范围
• PDF评论-- 基于特定页面，可选择文本片段
• 文本锚定评论-- 基于在markdown/笔记中选定的文本，使用精确匹配、前缀、后缀、起始偏移量和结束偏移量字段（使用类型："document"或类型："text"）
• 线程化回复-- 仅限单级线程；对回复的回复会自动扁平化至父级
• 表情符号反应-- 每个用户对每条评论只能有一个反应；添加新的反应会替换之前的反应
• 提及标签-- 使用方括号语法内联引用用户和文件：@[profile:id]、@[user:opaqueId:显示名称]、@[file:fileId:文件名.扩展名]。ID可以从成员列表、用户详情或存储列表中获取。显示名称字段对于个人资料标签是可选的，但对于用户和文件标签建议提供

评论使用JSON请求体（Content-Type: application/json），这与大多数其他使用表单编码数据的端点不同。

列出评论：使用commentactionlist获取每个文件的评论，使用commentactionlist-all适用于整个工作空间或共享的所有评论。两者均支持排序、限制数量（2-200）、偏移量、包含已删除项、引用类型筛选器，以及包含总数。

添加评论：使用评论操作添加，并附带个人资料类型、个人资料ID、节点ID，以及文本内容。可选包含parent_comment_id用于回复以及引用以锚定到特定位置。正文中支持提及标签。适用两个字符限制：包含标签的正文总长度最多8,192个字符，显示文本（去除@[...]标签后的正文）最多2,048个字符。可选择性地包含linked_entity_type和linked_entity_id以在创建时将该评论与任务或审批关联。

删除评论： 评论操作删除是递归的——删除父评论也会移除所有回复。评论操作批量删除不是递归的——被删除评论的回复会保留。

评论关联：评论可以关联到工作流实体（任务或审批）。每条评论一次支持一个关联（可为空）。使用评论操作关联将现有评论与任务或审批相关联，评论操作取消关联以移除关联，以及评论操作已关联来反向查找与给定实体关联的所有评论。您也可以在创建时通过向add操作传递linked_entity_type和linked_entity_id进行关联。评论响应中包含linked_entity_type和linked_entity_id字段（取消关联时为 null）。

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

参数	格式	用途
?comment={id}	评论不透明ID	滚动到并高亮显示特定评论，持续2秒
?t={秒数}	例如?t=45.5	跳转到音视频评论的时间戳
?p={页码}	例如?p=3	导航到PDF评论的页面

工作区：https://{组织域名}.fast.io/workspace/{文件夹名称}/preview/{文件不透明ID}?comment={评论ID}

分享：https://go.fast.io/shared/{自定义名称}/{标题-别名}/preview/{文件不透明ID}?comment={评论ID}

参数可以组合使用——例如?comment={id}&t=45.5要深度链接到视频的某个具体时间点的评论。在分享中，评论侧边栏仅在分享启用了评论功能时才会打开。

智能体使用案例：你生成了一份设计稿。用户在图片的特定区域评论说“更改标题颜色”。你读取该评论，通过reference.region坐标精确看到他们所指的是哪个区域，并重新生成。

文本锚定评论（Markdown/笔记）：要将评论锚定到 Markdown 或笔记文件中的特定文本，请使用reference参数，其type设为"document"（或

• "text"，这是其别名）以及文本选择字段：
• exact（字符串，最多 500 字符）-- 所选文本的原文
• prefix（字符串，最多100个字符）-- 选择内容后约30-50个字符的上下文，用于消除歧义
• 起始偏移量（整数）-- 从文档开头算起的字符偏移量（用于解决匹配歧义的提示）
• 结束偏移量（整数）-- 选择内容结束处的字符偏移量（用于解决匹配歧义的提示）

至少需要提供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导入

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

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

使用uploadactionweb-import操作，并指定源URL、目标配置文件和父节点ID。使用uploadactionweb-status来检查进度，使用uploadactionweb-list来列出活跃的导入任务。

智能体使用案例：用户说“把这个Google文档添加到项目中。” 您可以调用uploadactionweb-import只需提供URL。Fast.io会在服务器端下载文件，生成预览，为AI建立索引，然后它就会出现在工作区中。无需本地I/O操作。

元数据

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

关键点：

• 每个工作区一个模板-- 每个工作区最多同时支持一个被分配的元数据模板。
• 模板类别-- 法律、财务、商业、医疗、技术、工程、保险、教育、多媒体、人力资源。
• 字段类型-- 字符串、整数、浮点数、布尔值、JSON、URL、日期时间 -- 每种类型都有可选的约束条件（最小值、最大值、默认值、固定列表、可为空）。
• 两种元数据类型-- 模板元数据符合模板字段定义；自定义元数据是不受任何模板约束的自由格式键值对。
• 系统模板-- 预构建的模板，在分配给工作区时会自动克隆，因此自定义不会影响全局定义。
• AI提取-- 该提取操作利用AI分析文件内容并自动填充元数据字段。提取出的值会标记为is_auto: true。消耗AI积分。
• 版本历史-- 元数据变更通过版本快照进行追踪，可通过版本操作访问。
• 需要计费功能-- 组织必须已启用元数据计费功能。
• 模板ID是以mt_为前缀的字母数字字符串（例如mt_abc123def456）。

所有权转移

代理创造价值的主要方式：构建某些内容，然后将其移交给人类。当代理计划的积分耗尽且API调用开始返回402付款要求时，这也是推荐的操作——将组织转移给能够升级到付费计划的人类用户。

重要提示：账户类型限制。转移/认领工作流（orgactionstransfer-token-create、transfer-token-list、transfer-token-delete、transfer-claim）仅在代理通过authactionsignup创建了代理账户，且该代理账户拥有该组织时才可用。如果代理使用authactionsignin登录的是个人账户，则无法使用转移/认领API。个人拥有的组织必须由个人通过Fast.io仪表板直接升级。

流程：

1. 代理使用authactionsignup创建一个代理账户，并使用orgactioncreate创建一个组织，通过orgactioncreate-workspace设置工作区，上传文件，配置共享
2. 代理使用orgactiontransfer-token-create
3. 生成一个转移令牌（有效期为72小时）代理将认领URL发送给用户：
4. https://go.fast.io/claim?token=<token>

用户点击链接并使用自己的账户认领该组织

• 何时进行转移：
• 代理方案用尽额度（402 付款要求）——进行转移以便用户升级
• 用户明确要求接管组织

管理转移令牌：

• 组织操作转移令牌列表——在创建新令牌前检查是否存在待处理的令牌
• 组织操作转移令牌删除——如果不再需要转移，则撤销令牌
• 组织操作转移认领——使用令牌认领组织（由接收用户的代理使用）

转移后发生的情况：

• 用户成为组织及所有工作空间的所有者
• 代理保留管理员访问权限（仍可管理文件和共享）
• 用户获得免费方案（基于额度，无试用期）
• 用户可随时升级至专业版或商业版

智能体使用场景：用户说：“为我的团队设置一个项目工作空间。”您创建组织，构建工作空间结构，上传模板，配置客户交付物的共享权限，邀请团队成员——然后移交所有权。用户即可进入一个完全配置好的平台。您以管理员身份继续留任，负责持续管理工作。

402 需要付款使用场景（智能体账户）：工作过程中，智能体遇到信用额度限制。调用组织操作创建转移令牌，将申领URL发送给用户，并解释他们可以升级以继续。一旦用户完成升级，智能体将保留管理员访问权限并恢复工作。

402 需要付款使用场景（用户账户）：智能体无法转移组织。此时，通知用户其组织的信用额度已用完，需要升级其账单计划。引导他们前往Fast.io仪表板或使用组织操作创建账单来更新到付费计划。

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

工作区和共享支持一个可选的工作流层，该层增加了结构化的任务管理、活动日志记录、审批关卡和简单的清单。工作流功能由一个开关控制——它们必须先被明确启用才能使用。在共享中，访问工作流需要管理员或指定成员角色——访客和仅查看用户无法访问工作流功能。

启用工作流

• 工作区： workspaceactionenable-workflowwithworkspace_id
• 共享： shareactionenable-workflowwithshare_id

通过以下方式检查工作流是否已启用workspaceactiondetails或shareactiondetails-- 寻找workflow: true在响应中。

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

任务列表与任务

任务被组织到列表中。每个工作区或共享可以有多个任务列表，每个列表包含独立的任务。

• 任务列表具有名称和可选描述。通过任务操作create-list创建，通过任务操作list-lists列出。
• 任务包含标题、描述、状态、优先级、负责人、依赖项和可选的节点链接。通过任务操作创建任务来创建，通过任务操作列出任务来查看。
• 状态包括： 待处理、进行中、已完成、已阻塞
• 优先级：0 = 无，1 = 低，2 = 中，3 = 高，4 = 关键
• 负责人是个人资料ID（工作区或共享成员）。使用任务操作分配任务分配或取消分配。
• 批量操作： 任务操作批量状态一次性更改最多100个任务的状态。
• 移动任务： 任务操作移动任务将任务在同一配置文件内的不同列表间移动。需要提供源列表ID、任务ID和目标任务列表ID。可选择性地设置排序顺序以控制任务在目标列表中的位置（默认值：0）。
• 重新排序： 任务操作重新排序任务设置列表中任务的显示顺序。任务操作重新排序列表设置任务列表在配置文件内的显示顺序。按所需顺序传递ID数组；服务器会将其转换为{id, sort_order}对象以供API使用。
• 创建者追踪：任务和任务列表包含一个created_by字段（创建者的配置文件ID）。
• Markdown输出：传递format: "md"以获取人类可读的Markdown格式输出，而非JSON。

工作日志

工作日志是仅可追加、按时间顺序排列的活动日志，其范围限定于任务、任务列表、存储节点或配置文件。条目创建后无法编辑或删除。

• 条目：通过worklog操作append追加的常规日志条目。用于进度更新、决策记录、原因说明和状态变更。
• 感叹词：通过工作日志操作interject创建优先级修正。感叹词始终是紧急的，需要其他参与者确认。
• 确认： 工作日志操作acknowledge将感叹词标记为已查看。工作日志操作unacknowledged列出仍需确认的感叹词。条目包含一个可确认布尔值——当该值为true时，该条目是一个可以确认的未确认感叹词。
• 响应字段：条目包含已确认（布尔值），知识渊博（布尔值），更新时间（ISO 8601 时间戳），以及创建时间（ISO 8601 时间戳）。
• Markdown 输出：通过格式："md"以获取人类可读的输出。

审批

针对任务、存储节点或工作日志条目的正式审批请求。当某项决策需要明确签署同意时使用。

• 创建： 审批操作创建需提供用户档案ID、描述（1-5000字符）、实体类型（"task"、"node"或"worklog_entry"），以及可选的审批人ID（单个个人资料ID，必须是实体成员）。
• 解决： 批准操作解决使用解决操作："批准"或"拒绝"以及一个可选的评论。只有指定的审批人才能解决。
• 状态： 待处理、已批准、已拒绝
• Markdown输出：通过格式："md"用于人类可读的输出。

待办事项

简单扁平的清单，限定于工作区和共享。无嵌套——仅是一个可以勾选的项目列表。

• 创建： 待办事项操作创建带标题。
• 切换： 待办事项操作切换翻转单个待办事项的完成状态。待办事项操作批量切换一次性设置最多100个待办事项的完成状态。
• 更新/删除： 待办事项操作更新更改标题。待办事项操作删除软删除一个待办事项。
• 创建者追踪：待办事项包含一个创建者字段（创建者的个人资料ID）。
• Markdown输出：通过格式："md"以便于人类阅读的输出。

笔记作为智能体知识层

笔记（类型："note"）是存储在workspace存储中的markdown文件（参见上文中的“笔记”）。当与工作流功能结合时，笔记就形成了一个知识层：

• 自动AI索引：当启用workspace智能功能时，笔记会被摄取并索引以供RAG使用，就像上传的文件一样。
• 将任务链接到笔记：任务可以引用存储节点，包括笔记。可以为项目背景、需求或参考资料创建上下文笔记，然后创建链接到这些笔记的任务，以获取完整上下文。
• 用于推理的工作日志：使用工作日志条目来记录决策、进展和随时间的推理。按时间顺序排列的日志构建了一个叙事，补充了结构化的任务列表。
• AI可以搜索所有上下文：启用智能功能后，AI聊天可以跨笔记、工作日志、任务描述和上传文件进行搜索——基于项目的完整历史提供全面的答案。

推荐模式：为项目背景和需求创建笔记。为工作阶段创建任务清单。将任务与相关笔记关联。使用工作日志记录进度。为决策请求批准。然后，人工智能可以通过搜索所有这些工件来回答诸如“我们为什么选择这种方法？”之类的问题。

权限参数值

多个工具使用具有特定允许值的权限参数。调用工具时请使用这些确切的字符串。

组织创建 (组织操作创建)

参数	允许值	默认值
成员管理权限	仅所有者、管理员及以上、成员及以上	成员及以上
行业	未指定技术医疗保健金融教育制造业建筑业专业服务媒体零售业房地产物流能源汽车农业,media,retail,real_estate,logistics,energy,automotive,agriculture,制药,法律,政府,非营利,保险,电信,研究,娱乐,建筑,咨询,市场营销	未指定
背景模式	拉伸,固定	拉伸

工作区创建 (组织操作创建工作区) 和 更新 (工作区操作更新)

参数	允许的值	默认值
perm_join	仅组织所有者,管理员及以上,成员及以上	成员及以上
perm_member_manage	管理员及以上,成员及以上	成员及以上

共享创建 (共享操作创建)

参数	允许值	默认值
类型	发送,接收,交换	交换
存储模式	独立,工作区文件夹	独立
访问选项	仅共享或工作区成员,共享、工作区或组织成员,任何有注册账户的人,任何有链接的人	仅共享或工作区成员
邀请	所有者，访客	所有者
通知	从不，收到文件时通知，发送或接收文件时通知	从不
显示类型	列表，网格	网格
智能	真，假	假
评论功能启用	真，假	真
下载功能启用	真,假	真
启用访客聊天	真,假	假
工作空间样式	真,假	真
背景图片	0-128	0

分享约束：

• 接收和交换分享不能使用任何拥有链接的人访问——此选项仅适用于发送分享。
• 密码保护（密码参数）仅在访问选项是任何拥有链接的人。
• 有效期（expires参数采用MySQL格式YYYY-MM-DD HH:MM:SS）不允许用于workspace_folder共享。
• 关于custom_name、title和description的字段长度和格式限制，已在下方Profile Field Constraints表格中说明。
• 颜色参数（accent_color、background_color1、background_color2）接受JSON字符串。
• 创建文件夹当与storage_mode='workspace_folder'一起使用时，为共享创建一个新的工作空间文件夹。

。

配置文件字段约束

所有配置文件字段均在服务器端进行验证。违反这些约束的请求将被拒绝，并返回400错误。	实体	字段	API密钥	最小值	最大值	模式	必需
可为空	组织	域名	域名	2	63	^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$	是（创建时）
否	组织	名称	3	100	无控制字符	是	否
组织	描述	描述	10	1000	无控制字符	否	是
工作空间	文件夹名称	文件夹名称	4	80	^[\p{L}\p{N}-]+$(字母、数字、连字符)	是 (创建)	否
工作空间	名称	名称	2	100	无控制字符	是	否
工作区	描述	描述	10	1000	无控制字符	否	是
共享	自定义名称	自定义名称	4	80	^[\p{L}\p{N}]+$(仅限字母、数字)	是 (创建)	否
共享	自定义网址	自定义网址	10	100	—	是	是
共享	标题	标题	2	80	无控制字符	是	是
共享	描述	描述	10	500	无控制字符	否	是

• "无控制字符"= 拒绝Unicode控制字符 (\p{C})
• 组织域名：小写ASCII字母数字 + 连字符；不能以连字符开头或结尾
• 工作区文件夹名称：Unicode字母、数字和连字符。全局唯一——不限于某个组织。建议{org_id}-{name}避免冲突的命名约定（由create-workspace在名称被占用时自动应用）
• 共享自定义名称：仅限Unicode字母和数字（无连字符或特殊字符）
• 共享描述最多500字符（组织/工作空间为1000字符）

---

4. 代理计划 -- 免费版

代理计划是为AI代理设计的免费版本。无需信用卡、无试用期、永不过期。提供足够的资源来构建和展示价值，当组织转移到付费计划的人类用户时，仍有增长空间。

资源限制

资源	包含量
价格	$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"需要付款"。组织永远不会被删除。使用orgactionlimits来检查当前积分使用情况和剩余余额。

当您遇到402或积分即将用完时：

• 代理账户（通过authactionsignup创建）：将组织转移给个人。调用orgactiontransfer-token-create以生成转移令牌，然后将认领URL发送给个人：https://go.fast.io/claim?token=<token>一旦他们认领了该组织，就可以升级到包含无限额度的付费计划。您将保留管理员权限，并且在升级后可以立即恢复工作。这是预期的工作流程——代理在免费计划上构建，然后移交给准备就绪后付费的人类用户。
• 人类账户（通过认证操作登录）：您不能使用转移/认领API。告知用户他们需要直接升级组织的计费计划。他们可以通过Fast.io仪表板或调用组织操作计费创建来将其订阅更新为付费计划。

转移后——人类计划选项

当代理将组织转移给人类后，人类用户将获得一个免费计划（基于额度，无试用期），并可升级：

功能	代理（免费）	免费（人类）	专业版	商业版
月度额度	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

转移流程是代理交付价值的主要方式：在免费代理计划中设置好一切，然后进行移交。用户在准备好时进行升级，而代理保留管理员访问权限以继续管理事务。

---

5. 工具分类

这19个工具采用基于操作的路由方式。每个工具覆盖Fast.io平台的特定领域，并公开多个操作。

auth

认证、登录/注册、双因素认证、API密钥管理以及OAuth会话管理。这始终是任何代理交互的起点。

操作：登录，登出，注册，检查，会话，状态，设置API密钥，邮箱检查，邮箱验证，密码重置请求，密码重置，双因素认证验证，双因素认证状态，启用双因素认证，禁用双因素认证，发送双因素认证码，验证双因素认证设置，PKCE登录，PKCE完成，创建API密钥，更新API密钥，列出API密钥，获取API密钥，删除API密钥，列出OAuth，OAuth详情，撤销OAuth，撤销所有OAuth

user

检索和更新当前用户资料，搜索其他用户，管理邀请，上传和删除用户资产（如个人资料照片），检查账户资格，以及列出用户所属的共享。

操作：我的信息，更新，搜索，关闭账户，按ID获取详情，用户资料，允许的操作，组织限制，列出共享，邀请列表，邀请详情，接受所有邀请，资产上传，资产删除，资产类型，资产列表

org

组织CRUD、成员管理、计费与订阅操作、工作区创建、邀请流程、资产管理（上传、删除）、组织发现以及所有权转移。

操作：列表、详情、创建、更新、关闭、公开详情、限制、列出工作区、列出共享、创建工作区、计费方案、创建计费、取消计费、计费详情、激活计费、重置计费、计费成员、计费计量、成员、邀请成员、移除成员、更新成员角色、成员详情、离开、转移所有权、加入、邀请列表、更新邀请、删除邀请、创建转移令牌、列出转移令牌、删除转移令牌、认领转移、发现全部、发现可用、检查域名、发现外部、资产上传、资产删除、资产类型、资产列表

工作区

工作区级别设置、生命周期操作（更新、删除、归档、取消归档）、列出和导入共享、管理工作区资产、工作区发现、笔记（创建、读取、更新）、快速共享管理、元数据操作（模板CRUD、分配、文件元数据获取/设置/删除、AI提取）以及工作流开关（启用/禁用任务、工作日志、审批和待办事项）。

操作：列出、详情、更新、删除、归档、取消归档、成员管理、列出分享、导入分享、可用性检查、检查名称、创建笔记、读取笔记、更新笔记、快速分享获取、快速分享删除、快速分享列表、元数据模板创建、元数据模板删除、元数据模板列表、元数据模板详情、元数据模板更新、元数据模板克隆、元数据模板分配、元数据模板取消分配、元数据模板解析、元数据模板分配情况、元数据获取、元数据设置、元数据删除、元数据提取、元数据文件列表、使用中的元数据模板列表、元数据版本、启用工作流、禁用工作流

分享

分享的增删改查、公共详情、归档、密码验证、资产管理、分享名称可用性检查，以及工作流切换（启用/禁用任务、工作日志、审批和待办事项）。

操作：列出、详情、创建、更新、删除、公共详情、归档、取消归档、密码验证、成员管理、可用性检查、检查名称、快速分享创建、启用工作流、禁用工作流

存储

工作空间和分享内的文件和文件夹操作。包括列出、列出所有文件夹中最近修改的文件、创建文件夹、移动、复制、删除、重命名、清除、恢复、搜索、从上传添加文件、添加分享链接、转移节点、管理回收站、版本操作、文件锁定，以及生成预览/转换URL。需要上下文类型参数（工作空间或共享）。

操作：列表、最近、详情、搜索、回收站列表、创建文件夹、复制、移动、删除、重命名、彻底删除、恢复、添加文件、添加快捷方式、传输、版本列表、版本恢复、获取锁定、锁定状态、释放锁定、预览链接、预览转换

上传

文件上传操作。包括单步文本文件上传、分块上传生命周期（创建会话、暂存二进制数据块、以纯文本/Base64/数据块引用形式上传数据块、最终完成、检查状态、取消）、从外部URL进行网络导入、上传限制和文件扩展名限制，以及会话管理。

操作：创建会话、数据块、最终完成、状态、取消、列出会话、全部取消、数据块状态、删除数据块、暂存数据块、文本文件、网络导入、网络列表、网络取消、网络状态、限制、扩展名

下载

为工作区文件、共享文件和快速共享链接生成下载URL和ZIP归档URL。MCP工具无法流式传输二进制数据——这些操作返回的URL可在浏览器中打开或传递给下载工具。需要上下文类型参数（工作区或分享) 用于 file-url 和 zip-url 操作。响应包含一个resource_uri字段（例如download://workspace/{id}/{node_id}），MCP 客户端可以通过 MCP 资源直接使用它来读取文件内容。直接下载 URL 包含?error=html参数，以便错误在浏览器中呈现为人类可读的 HTML。

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

人工智能

在工作区和分享中提供基于 AI 的聊天、语义搜索和文档分析功能。创建聊天、发送消息、读取 AI 响应（通过轮询）、列出和管理聊天、通过语义搜索带相关性分数的索引文档和代码、发布私人聊天、生成 AI 分享 Markdown、追踪 AI 令牌使用情况以及自动生成标题。需要context_type参数（workspace或share）。

操作：聊天-创建, 聊天-列表, 聊天-详情, 聊天-更新, 聊天-删除, 聊天-发布, 消息-发送, 消息-列表, 消息-详情, 消息-已读, 搜索, 分享-生成, 交易记录, 自动标题

评论

评论的作用域为{实体类型}/{父级ID}/{节点ID}其中，实体类型为工作空间或分享，父级ID是19位数字的配置文件ID，节点ID是存储节点的不透明ID。支持列出文件上的评论（可按节点和配置文件范围，并带有排序/限制/偏移/过滤参数），添加带有可选引用锚定的评论（如图像区域、视频/音频时间戳、带有文本选择的PDF页面、Markdown/笔记中的文本选择），单级线程回复，递归式单个删除，非递归式批量删除，获取评论详情，表情符号反应（每个用户每条评论一个），以及工作流链接（将评论链接/取消链接到任务或审批，支持反向查找）。评论使用JSON请求体。

操作：列表, 全部列出, 添加, 删除, 批量删除, 详情, 添加反应, 移除反应, 链接, 取消链接, 已链接

事件

通过类别、子类别和事件名称进行丰富过滤来搜索审计/事件日志（参见事件过滤参考（完整分类法请参阅第7节）。获取AI驱动的活动摘要、检索单个事件的完整详情、列出近期活动，并长轮询活动变更。

操作：搜索、摘要、详情、活动列表、活动轮询

成员管理

适用于组织、工作空间和共享的成员管理功能。包括添加、移除、更新角色、转移所有权、退出、加入以及通过邀请加入。需要实体类型参数（工作空间或共享）。

操作：添加、移除、详情、更新、转移所有权、退出、加入、邀请加入

邀请管理

适用于组织、工作空间和共享的邀请管理功能。包括列出邀请、按状态列出、更新和删除。需要实体类型参数（工作空间或共享).

操作：列表，按状态列出，更新，删除

资产

为组织、工作区、共享和用户提供资产管理（上传、删除、列表、读取）。需要实体类型参数（组织、工作区、共享或用户）。

操作：上传，删除，类型，列表，读取

任务

为工作区和共享提供任务列表和任务管理。创建和管理任务列表，然后在其中创建包含状态、优先级、分配者和依赖关系的任务。支持批量状态更改、重新排序和Markdown输出。任务和列表包含创建者（创建者个人资料ID）。需要在目标实体上启用工作流。

操作：列出清单，创建清单，清单详情，更新清单，删除清单，清单任务，创建任务，任务详情，更新任务，删除任务，更改状态，分配任务，批量状态，移动任务，重新排序任务，重新排序清单

工作日志

用于追踪代理工作的活动日志。在上传、任务变更、分享创建或任何重要操作后，记录您做了什么以及为什么这样做——为人类和AI构建一个可搜索的审计追踪。同时创建需要确认的紧急插话。条目仅可追加且永久保存。需要在目标实体上启用工作流。

操作：追加，列出，插话，详情，确认，未确认

审批

针对任务、存储节点或工作日志条目的正式审批请求。创建带有指定审批人的审批请求，然后通过批准或拒绝决定来完结它们。需要在目标实体上启用工作流。

操作：列出，创建，详情，完结

待办事项

针对工作空间和分享的简单扁平化核对清单。单独或批量创建、更新、删除、切换待办事项。待办事项包含创建者（创建者个人资料ID）。无嵌套。需要在目标实体上启用工作流。

动作：列表、创建、详情、更新、删除、切换、批量切换

应用

交互式 MCP 应用小部件的发现与启动。列出可用的小部件、获取特定小部件的详细信息、通过工作区或共享上下文启动小部件，以及查找与特定工具域关联的小部件。

动作：列表、详情、启动、获取工具应用

---

6. 常见工作流程

1. 创建账户并登录

请参见选择正确的方法第 2 节中关于哪种方案适合您场景的说明。

方案 1 —— 自主代理（新账户）：

1. 可选地调用认证操作邮件检查使用期望的电子邮件以验证可用性。
2. 认证操作注册和名、姓、电子邮件以及密码—— 注册为代理账户（agent=true 会自动发送）并立即登录。
3. authactionemail-verify与电子邮件—— 发送验证码。然后authactionemail-verify与电子邮件和email_token—— 验证代码。在使用大多数端点之前是必需的。
4. orgactioncreate要在代理计划上创建一个新的组织，或者组织操作列表来检查现有的组织。

选项2 -- 协助人类（API密钥）：

1. 人类在https://go.fast.io/settings/api-keys创建一个API密钥，并将其提供给代理。
2. 调用认证操作设置API密钥并传入该API密钥。密钥会通过API验证并存储在会话中——所有后续的工具调用都会自动进行身份验证。无需创建账户。
3. 组织操作列表和组织操作发现外部组织来发现所有可用的组织（参见组织发现).

选项 3 -- 智能体受邀加入人类组织：

1. 使用auth操作signup创建一个智能体账户（与选项1相同）。
2. 让人类通过org操作invite-member或member操作add（附带entity_type: "workspace"参数）邀请你。
3. 使用user操作accept-all-invitations接受所有邀请。
4. 使用org操作list组织操作发现外部以发现所有可用的组织（参见组织发现）。如果用户只邀请你加入工作空间（而非组织），它将仅通过发现外部出现。

返回用户：

1. 认证操作登录使用电子邮件和密码。
2. 如果two_factor_required: true，则调用认证操作双因素验证并提供双因素认证代码。
3. orgactionlist和orgactiondiscover-external以发现所有可用的组织（参见组织发现）。

2. 浏览并下载文件

1. orgactionlist和orgactiondiscover-external-- 发现所有可用的组织（参见组织发现）。注意org_id的值。
2. orgactionlist-workspaces与组织ID-- 获取组织内的工作区。注意工作区ID的值。
3. 存储操作列表使用context_type: "workspace"、context_id（工作区ID）和node_id: "root"-- 浏览根文件夹。注意node_id用于文件和子文件夹的值。
4. 存储操作详情使用context_type: "workspace"、context_id和node_id-- 获取特定文件的完整详情（名称、大小、类型、版本）。
5. 下载操作文件URL与context_type: "workspace"、context_id和node_id-- 获取一个包含嵌入令牌的临时下载URL。响应还包括一个resource_uri（例如download://workspace/{id}/{node_id}），MCP客户端可以用它来直接读取文件内容。将下载URL返回给用户，或通过MCP使用资源URI来读取文件。

3. 上传文件到工作区

文本文件（推荐）：使用上传操作文本文件与profile_type: "workspace",profile_id,parent_node_id,filename, 和content(纯文本)。这个单一操作会上传文件并在成功时返回new_file_id。在内部，它使用了 Fast.io 的单请求上传模式（一个包含文件数据的 multipart POST 请求），因此没有单独的分块、最终确定或轮询步骤。将此用于代码、markdown、CSV、JSON、配置文件以及任何其他文本内容。

二进制文件（选择正确的方法）：

了解上传限制。Fast.io API 要求每个分块必须≥ 1 MB（会话的最后一个分块除外，该分块可以更小）。MCP 工具调用每次调用的实际传输限制约为64 KB 原始二进制数据（约 96 KB base64 编码）。这意味着，对于大于约 64 KB 的文件，仅通过 MCP 工具调用进行多分块二进制上传将会失败——每个 MCP 大小的分块都远低于 1 MB 的 API 最低要求。请使用上传操作限制以检查您计划的确切分块大小和文件大小限制。

选项A：web-import（推荐用于可通过URL访问的文件）如果文件有URL（HTTP/HTTPS、Google Drive、OneDrive、Box、Dropbox），请使用上传操作web-import。单次调用，无需分块，无需base64编码。请参见下面的工作流4。

选项B：适用于小二进制文件（≤ ~64 KB）的单块上传适合在一个MCP工具调用中处理的小文件可以作为单个块上传：

1. 上传操作create-session与profile_type、profile_id、parent_node_id,文件名, 以及文件大小（以字节为单位）。
2. 上传操作分块与upload_id,chunk_number: 1, 和数据（base64编码的文件，≤96 KB base64 / ~64 KB二进制数据）。由于这是唯一的分块，API的"允许1个小分块"规则允许这样做。
3. 上传操作完成与upload_id。

选项 C：POST /blob用于较大二进制文件的辅助端点对于大于 ~64 KB 的文件，使用 HTTP blob 端点来绕过 MCP 传输限制。该POST /blob端点通过HTTP接受原始二进制数据（无需base64编码，在MCP内部不进行大小分割）。暂存每个≥ 1 MB（最后一个块除外）的数据块，然后在分块调用中引用它们：

1. 上传操作create-session时需包含profile_type、profile_id、parent_node_id、filename以及filesize参数。
2. 对于每个数据块：POST /blob携带原始二进制数据（≥ 1 MB，≤ 100 MB）。返回blob_id。
3. 上传操作块附带上传标识符、块编号和blob引用："<blob_id>"。
4. 上传操作完成附带上传标识符。

选项 D：外部上传工具对于任何大小的可靠二进制上传，请使用外部 HTTP 客户端（Python requests、curl 等）直接调用 Fast.io REST API 上传端点，完全绕过 MCP 传输限制。使用 MCP 处理控制平面任务（会话创建、完成、状态），并使用外部客户端处理数据平面（块上传）。

传递块数据的三种选项（只需提供其中一种）：

• 内容——用于文本（字符串、代码、JSON 等）。请勿使用数据处理文本。
• 数据— base64编码的二进制数据。受MCP传输限制，每次调用最多约96 KB base64（约64 KB二进制数据）。仅适用于单块小文件。
• blob_ref— 来自上传操作stage-blob或POST /blob的blob ID。对于较大文件，推荐使用POST /blob方法，因为它能绕过MCP传输限制。

上传操作finalize配合upload_id会触发文件组装并轮询直到存储完成。成功时（包括new_file_id）返回最终会话状态，其中包含status: "stored"或"complete")，或在失败时抛出异常。终端失败状态包括：assembly_failed（无法组装数据块）和store_failed（无法存储组装后的文件——请查看status_message了解详情）。文件会自动添加到会话创建时指定的目标工作空间和文件夹中——无需单独调用添加文件。

上传状态说明：

状态	含义	是否为终端状态？
ready	会话已创建，等待接收数据块	否
uploading	正在接收数据块	否
assembling	正在组装中	否
complete	已组装完成，等待存储导入	否
存储中	正在导入存储	否
已存储	完成 — 文件已存入存储，新文件ID可用	是（成功）
组装失败	组装错误	是（失败）
存储失败	存储导入失败	是（失败）

注意： 存储操作添加文件仅当您希望将上传链接到不同于会话创建时指定的位置时才需要。

同名上传：如果目标文件夹中已存在同名文件，上传将替换它会覆盖同名文件。原有内容会保存为一个版本。若想保留两个文件，请在上传前重命名。

4. 从URL导入文件

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

1. 上传操作web-import附带参数url（源URL）、profile_type: "workspace"、profile_id（工作区ID）以及parent_node_id（目标文件夹或"root"）。返回一个upload_id。
2. 上传操作web-status附带参数upload_id-- 检查导入进度。服务器会下载文件、扫描文件、生成预览，并为AI建立索引（如果启用了智能功能）。
3. 任务完成后，文件会出现在工作区存储树中。

5. 向客户端交付文件

创建一个带有品牌标识的专业分享链接，用于对外文件交付。这将替代原始下载链接、电子邮件附件和S3预签名URL。

1. 将文件上传到工作区（参见工作流程3或4）。
2. 分享操作创建附带workspace_id、name和type: "send"-- 创建一个发送分享。返回一个share_id。
3. 分享操作更新附带share_id需要配置：
   • 密码-- 要求输入密码才能访问
   • 过期日期-- 在设定的时间段后自动过期分享
   • 访问级别-- 仅限成员、组织成员、注册用户或公开
   • 允许下载-- 启用或禁用文件下载
   • 品牌选项：背景颜色，强调色，渐变色
   • 下载后消息和下载后网址-- 下载后显示一条消息
4. 成员操作添加与实体类型："分享"，实体ID（共享ID），以及电子邮件或用户ID——添加收件人。如果他们没有 Fast.io 账户，会发送邀请。
5. 资产操作上传使用entity_type: "share"和entity_id（共享ID）来添加品牌标识的徽标或背景图片。
6. 收件人看到的是带有即时文件预览的品牌页面，而非原始下载链接。

6. 从用户处收集文档

创建一个“接收”共享，以便用户可以直接向您上传文件——无需电子邮件附件，也无需云盘链接。

1. 共享操作创建使用workspace_id、name（例如：“在此处上传您的税务文件”），以及类型："接收"返回一个分享ID。
2. 分享操作更新，使用分享ID来根据需要设置访问级别、有效期和品牌标识。
3. 成员操作添加，使用实体类型："分享"、实体ID（分享ID）和电子邮件或用户ID来邀请上传者。
4. 用户通过一个简洁、带品牌标识的界面上传文件。
5. 文件出现在您的工作区中。如果启用了智能功能，它们会被AI自动索引。
6. 使用AI操作创建聊天附带context_type: "share"作用域限定在接收共享的文件夹内，用于提问，例如：“所有必需表格是否齐全？”

7. 构建知识库

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

1. 组织操作create-workspace附带org_id、name和intelligence: "true"（此工作流专门要求具备智能功能以支持RAG）。
2. 上传参考文档（参见工作流3或4）。AI会在上传时自动为所有内容建立索引并进行总结。
3. ai操作chat-create附带context_type: "workspace"，context_id（工作空间ID），query_text，type: "chat_with_files"，以及folders_scope（以逗号分隔的nodeId:depth对），用于跨文件夹或整个工作空间进行查询。
4. aiactionmessage-read与context_type: "workspace"，context_id，chat_id，以及message_id-- 轮询直到AI响应完成。返回response_text和citations指向具体的文件、页面和片段。
5. 存储操作搜索使用context_type: "workspace"、context_id以及用于语义搜索的查询字符串——根据含义查找文件，而不仅仅是文件名。
6. 答案包含对特定页面和文件的引用。将这些连同来源参考一起返回给用户。

8. 向AI询问文件

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

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

1. ai操作chat-create使用context_type: "workspace"、context_id（工作区ID）、query_text、类型："chat_with_files"，以及files_scope（逗号分隔的nodeId:versionId对）或folders_scope（逗号分隔的nodeId:depth对，深度范围1-10）。重要提示： files_scope和files_attach是互斥的——同时发送两者会导致错误。返回chat_id和message_id。
2. aiactionmessage-read，附带context_type: "workspace"，context_id,chat_id，以及message_id——轮询API最多15次（每次间隔2秒，大约30秒），直到AI响应完成。返回response_text和citations。提示：如果内置的轮询窗口超时，请使用eventactionactivity-poll并附带工作区ID，而不是在循环中调用message-read——请参阅上方的“活动轮询”章节。
3. aiactionmessage-send与context_type: "workspace"、context_id，聊天ID，以及查询文本用于后续问题。返回一个新的消息ID。
4. AI操作读取消息再次使用新的消息ID以获取后续响应。

无智能（文件附件）：

1. AI操作创建聊天，附带上下文类型："workspace"、上下文ID、查询文本、类型："chat_with_files"，以及文件附件指向特定文件（用逗号分隔节点ID:版本ID，最多20个文件 / 200 MB）。文件必须具有ai.attach: true属性（可通过存储操作详情查看）。AI直接读取附加文件，无需持久化索引。
2. ai操作消息读取以获取响应。无数据摄取积分成本——仅消耗聊天令牌积分。

9. 为用户设置项目

完整的智能体到人工交接工作流程。这是智能体在Fast.io上交付价值的主要方式。

1. 组织操作创建——在智能体计费计划上创建新组织。智能体成为所有者。系统会自动创建一个智能体计划订阅（免费，50 GB，每月5,000积分）。
2. 组织操作创建-工作区附带组织ID和名称-- 为每个项目区域创建工作区。
3. 存储操作创建-文件夹附带上下文类型："workspace"以构建文件夹结构（模板、可交付成果、参考文档等）。
4. 将文件上传到每个工作区（参见工作流程3或4）。
5. 共享操作创建附带类型："send"用于客户端可交付成果，类型："receive"用于接收/收集。
6. 共享操作更新配置每个共享的品牌、密码、有效期和访问级别。
7. 组织操作邀请成员或成员操作添加附带entity_type: "workspace"以邀请团队成员。
8. 组织操作创建转移令牌附带org_id-- 生成一个72小时内有效的转移令牌。将认领URL（https://go.fast.io/claim?token=<token>）发送给相关人员。
9. 相关人员点击链接并认领组织。他们成为所有者，代理保留管理员访问权限。相关人员获得免费计划。

10. 管理组织计费

1. 组织操作billing-plans-- 列出所有可用的计费计划，包括价格和功能。
2. orgactionbilling-createwithorg_id以及可选的billing_plan-- 创建或更新订阅。对于新订阅，这会创建一个Stripe Setup Intent。
3. orgactionbilling-detailswithorg_id-- 检查当前订阅状态、Stripe客户信息和支付详情。
4. orgactionlimitswithorg_id-- 对照计划限制检查额度使用情况，包括存储、传输、AI令牌和计费周期信息。

11. 管理工作区中的任务

使用结构化的任务列表和任务来管理工作。

1. 工作空间操作启用工作流使用工作空间ID-- 启用工作流功能（在使用任务、工作日志、审批或待办事项工具之前必需）。
2. 任务操作创建列表使用profile_type: "workspace"、profile_id（工作空间ID）和名称-- 创建一个任务列表。返回list_id。
3. 任务操作创建任务使用list_id、标题，以及可选的描述、优先级（0-4）、负责人ID、依赖项、节点ID，以及状态——将任务添加到列表。
4. 任务操作列出任务，配合列表ID——查看所有任务，可选择按状态或负责人进行筛选。
5. 任务操作更改状态，配合list_id，task_id，以及status——更新任务进度（待处理→进行中→完成）。
6. taskactionassign-task与list_id，task_id，以及assignee_id——将工作分配给团队成员。
7. taskactionbulk-status与list_id，task_ids和status-- 批量更新，一次最多可更新100个任务。

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

完整的智能体工作流模式：规划工作、执行并记录日志、通过审批来管控决策。

1. workspaceactionenable-workflow与workspace_id-- 在工作区启用工作流功能。
2. workspaceactioncreate-note-- 创建包含项目背景、需求和参考资料的上下文笔记。
3. taskactioncreate-list-- 为每个工作阶段（例如"研究"、"实施"、"审查"）创建任务列表。
4. taskaction创建任务-- 添加上下文相关的任务。包含描述性标题，并在描述中引用笔记节点ID。
5. 任务操作更改状态状态为："进行中"-- 将任务标记为已开始。工作日志
6. 操作追加实体类型("任务"、"任务列表"、"节点"或"个人资料")，实体ID（对应实体的不透明ID，或实体类型为"个人资料"时的19位个人资料ID），以及内容-- 记录工作进展、决策和推理。建立一个按时间顺序的叙述。如果需要优先修正：工作日志
7. 操作插入actioninterject-- 创建一个需要其他参与者确认的紧急条目。
8. 工作日志操作未确认-- 在继续之前，检查是否有未确认的插话。
9. 工作日志操作确认-- 将插话标记为已查看。
10. 当一项决策需要签署批准时：批准操作创建附带配置文件ID、描述、实体类型（"任务"、"节点"或"工作日志条目"），并可选择性地包含审批人ID-- 请求正式批准。
11. 批准操作解决伴随resolve_action: "approve"或"reject"以及可选的comment-- 审批人处理请求。
12. 任务操作change-status伴随status: "complete"-- 标记已完成的任务。
13. 待办事项操作create-- 在主任务流旁边跟踪简单的检查清单项目。
14. 启用智能功能后，ai操作chat-create-- AI可以跨笔记、任务描述和工作日志进行搜索，以回答有关项目的问题。

---

7. 关键模式和注意事项

ID 格式

配置文件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。由以下端点使用：storageaction列表（带有context_type: "workspace"或"share"）。

限制/偏移（所有其他列表端点）： limit（1-500，默认100）和offset（默认0）。用于：orgactionslist，members，list-workspaces，list-shares，billing-members，discover-all，discover-external；分享操作列表,成员;工作区操作列表,成员,列出分享;用户操作列出分享;存储操作搜索.

二进制文件下载

MCP工具返回下载URL——它们从不直接流式传输二进制内容。下载操作文件-URL（当context_type为"workspace"或"share"时）且downloadaction为quickshare-details时，调用/requestread/端点以获取临时令牌，然后构建完整的下载URL。代理应将这些URL返回给用户或传递给下载工具。

downloadactions为zip-url时（针对workspace和share），返回URL以及所需的Authorization请求头值。

二进制文件上传

有三种方法可将二进制数据分块上传，每种方法适用于不同情况。

对于可通过URL访问的文件，优先使用web-import方法。如果二进制文件可以通过任何URL（HTTP/HTTPS、Google Drive、OneDrive、Box、Dropbox）访问，请使用上传操作web-import而不是分块上传。这是一个单一的工具调用——无需分块、无需base64编码、无需会话管理。仅当您拥有本地二进制数据且没有可用URL时，才使用分块上传。

MCP代理的分块大小限制。MCP工具参数会经过AI模型的输出传递，这限制了您可以在单个工具调用中包含的数据量。请将每个分块的base64数据控制在32 KB以下（约24 KB的二进制数据）。例如，一个145 KB的PDF至少需要6个分块，即使是一个17 KB的文件也应该分成1-2个分块，而不是假设它能在一个调用中容纳。create-session响应中包含一个recommended_mcp_chunk_bytes提示（默认值为24576）——请用它来计算分块数量：ceil(文件大小 / recommended_mcp_chunk_bytes)。在使用分块上传时，请始终将文件分割成多个分块。数据或stage-blob通过 MCP 工具调用。

常见陷阱：请勿将二进制数据预处理为中间格式。将 base64 数据直接传递到data参数中，该参数属于chunk或stage-blob工具调用。请勿将二进制文件读入 Python/JSON 变量、对其进行 pickle 处理，或保存到临时文件并期望稍后引用——MCP 工具只能通过其自身的参数接收数据。如果您有本地二进制文件，请将其以 ≤32 KB 的片段进行 base64 编码，并将每个片段直接作为data参数，通过连续的stage-blob→chunk调用来传递。请在上传前立即创建上传会话——会话会过期，因此不要在创建会话和上传数据块之间进行调试。

1.数据参数（base64）— 对MCP代理最简单

将base64编码的二进制数据直接传入数据参数中，该参数属于上传操作块。无需额外步骤。适用于任何MCP客户端。由于base64编码会增加约33%的大小开销。将文件分割成≤24 KB二进制（≤32 KB base64）的块以保持在MCP客户端参数限制内。

2.暂存-blob操作 — 基于MCP工具的blob暂存

使用上传操作暂存-blob与数据（base64）来预暂存二进制数据作为blob。返回一个blob_id，你可以将其作为blob_ref在分块调用中。当您希望将暂存与上传解耦，或者提前准备多个分块时非常有用。同样的每次调用有32 KB的base64限制规则适用——每次暂存一个分块大小的数据。

流程：

1. 上传操作stage-blob附带数据（base64编码的二进制数据，≤32 KB）。返回{ "blob_id": "<uuid>", "size": <bytes> }。
2. 上传操作chunk附带blob_ref: "<blob_id>"。服务器检索暂存的字节并上传它们。

3.POST /blob端点——为非MCP客户端提供的HTTP blob暂存功能

一个旁路HTTP端点，用于在JSON-RPC管道之外接收原始二进制数据。这种方式完全避免了base64编码——对于能够与MCP工具调用并行发起直接HTTP请求的客户端非常有用。此方法无需进行分块大小分割。

流程：

1. POST /blob请求头需包含Mcp-Session-Id: <session_id>和Content-Type: application/octet-stream。将原始二进制字节作为请求体发送。返回{ "blob_id": "<uuid>", "size": <bytes> }（HTTP 201状态码）。
2. 然后在upload操作的chunk参数中

使用

• blob_ref: "<blob_id>"进行引用。二进制大对象约束（适用于两种暂存方法）：
• 二进制大对象将在
• 最大 blob 大小：100 MB。
• SSE 传输客户端必须在/blobURL 中添加?transport=sse。

事件筛选参考

事件工具的搜索和汇总操作接受类别、子类别和事件参数以缩小结果范围。使用这些参数来定位特定活动，而不是扫描所有事件。事件类别

类别

涵盖内容	用户
user	账户创建、更新、删除、头像更改
组织	组织生命周期、设置、转让
工作区	工作区创建、更新、归档、文件操作
共享	共享生命周期、设置、文件操作
节点	文件和文件夹操作（跨配置）
AI	AI 聊天、摘要、RAG 索引
邀请	成员邀请发送、接受、拒绝
计费	订阅、试用、信用额度使用
域名	自定义域名配置
应用	应用集成
元数据	元数据提取、模板、键值对更新

事件子类别

子类别	涵盖内容
存储	文件/文件夹的添加、移动、复制、删除、恢复、下载
评论	评论的创建、更新、删除、提及、回复、反应
成员	组织、工作区或共享中的成员添加/移除
生命周期	个人资料的创建、更新、删除、归档
设置	配置和偏好设置的更改
安全	安全相关事件（双因素认证、密码）
认证	登录、单点登录、会话事件
人工智能	人工智能处理、聊天、索引
邀请	邀请管理
账单	订阅和支付事件
资产	头像/资产更新
上传	上传会话管理
传输	跨配置文件文件传输
快速共享	快速共享操作
元数据	元数据操作

通用事件名称

文件操作（工作区）： 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_archived,workspace_unarchived

Share lifecycle: share_created,share_updated,share_deleted,share_archivedshare_unarchivedshare_imported_to_workspaceAI:ai_chat_created

ai_chat_new_message ai_chat_updatedai_chat_deletedai_chat_publishednode_ai_summary_createdworkspace_ai_share_createdMetadata:metadata_kv_updatemetadata_kv_deletemetadata_kv_extractmetadata_template_updatenode_ai_summary_created,workspace_ai_share_created

Metadata: metadata_kv_update,metadata_kv_delete,metadata_kv_extract,metadata_template_update,元数据模板删除,元数据模板设置更新,元数据视图更新,元数据视图删除,元数据模板选择

快速分享： 工作空间快速分享已创建,工作空间快速分享已更新,工作空间快速分享已删除,工作空间快速分享文件已下载,工作空间快速分享文件已预览

邀请： 邀请邮件已发送,邀请已接受,邀请已拒绝

用户： 用户已创建,用户已更新,用户已删除,用户邮箱重置,用户资产已更新

组织： 组织已创建,组织已更新,组织已关闭,组织转移令牌已创建,组织转移已完成

计费： 订阅已创建,订阅已取消,计费免费试用已结束

示例查询

• 工作区内的近期评论： 事件操作搜索使用工作区ID和子类别："comments"
• 上传到共享的文件： 事件操作搜索使用共享ID和事件："share_storage_file_added"
• 整个组织内的所有成员变更： 事件操作搜索使用组织ID和子类别："members"
• 工作区内的AI活动： 事件行动搜索使用workspace_id和类别："ai"
• 谁从共享中下载了文件： 事件行动搜索使用share_id和事件："share_storage_download_token_created"

活动轮询

检测变化的三种机制，按从最优先到最不优先的顺序列出：

1. 事件行动活动轮询— 服务器保持连接最多95秒，并在有变化时立即返回。返回活动键（例如ai_chat:{chatId}、存储，成员）以及用于下一次轮询的最后活动时间戳。这适用于任何“等待某事发生”的场景，包括AI聊天完成。
2. WebSocket— 用于实时推送事件。最适合实时用户界面。
3. 事件操作活动列表— 按需检索最近的活动事件。当您需要一次性快照而非持续监控时使用。

为何这很重要：不要在紧密循环中轮询详情端点（如ai操作消息读取）。相反，使用事件操作活动轮询来检测何时发生变化，然后一次性获取详情。

AI消息完成

ai操作消息读取（当上下文类型为："workspace"或"share"时）实现了内置轮询（最多尝试15次，间隔2秒）。如果在该时间窗口后响应仍在处理中，请使用事件操作activity-poll并传入工作区或共享ID，而不是在循环中调用读取操作：

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

活动轮询工作流

1. 进行一次API调用（例如aiactionchat-create）并记录响应中的server_date字段。
2. 调用eventactionactivity-poll，并传入entity_id（工作区或共享ID）以及将lastactivity设置为server_date的值。
3. 服务器将保持连接。当有变化发生（或等待时间到期）时，它会返回活动键。
4. 检查这些键以确定发生了什么变化，然后获取相关的详细信息（例如aiaction消息已读,存储操作列表）。
5. 在下一次轮询调用时，使用轮询响应中的新最后活动值（或最新的服务器日期）。根据需要重复此过程。

回收、删除和清空

• 存储操作删除（配合上下文类型："工作区"或"共享"）会将项目移至回收站。这些项目可以恢复。
• 存储操作恢复可从回收站恢复项目。
• 存储操作清除永久且不可逆地从回收站中删除项目。

在执行清除操作前，务必先与用户确认。

节点类型

存储节点可以是文件、文件夹、笔记或链接。类型在存储详情响应中指明。笔记是通过workspaceactioncreate-note创建的Markdown文件，通过workspaceactionread-note读取，并通过workspaceactionupdate-note更新。链接是通过storageactionadd-link创建的共享引用节点。

文本内容与换行符

所有文本内容（笔记、评论、工作日志、文件上传、描述）必须使用Unix风格的换行符（\n，U+000A）。前端在保存前会将所有行尾规范化为\n——Windows风格的\r\n（CRLF）和旧版Mac的\r（CR）会被自动转换。代理应专门使用\n，以避免内容比较和显示时的不匹配。

编码规则：

• 换行符：使用\n（U+000A）。切勿发送\r\n或单独的\r。
• 允许的控制字符：仅\t（U+0009）， (U+000A) 和\r(U+000D) 能通过服务器端清理而保留。所有其他 Unicode 控制字符 (\p{C}) 都将被去除。Markdown 中的空行：
• 使用两个连续的\n字符 (\n\n) 来表示段落分隔。不要使用不间断空格 (U+00A0) 或其他空白字符作为占位符。尾随换行符：
• 内容可能以尾随的\n结束，也可能没有。不要假定任何一种惯例 —— 两种都是有效的。这适用于：

workspaceactionscreate-note和update-note,uploadupload操作文本文件、评论操作添加、工作日志操作追加和插话，以及任何其他接受自由文本或Markdown内容的工具。

错误模式

失败的API调用会抛出包含两个字段的错误：代码（唯一的数字错误ID）和文本（人类可读的描述）。工具会在MCP响应中将这些作为错误文本呈现。常见的HTTP状态码包括401（未授权）、403（禁止访问）、404（未找到）和429（速率限制）。

会话状态

认证令牌、用户ID、电子邮件和令牌有效期都保存在服务器会话中。无需在工具调用之间传递令牌。在同一MCP连接中，会话会在多个工具调用之间持续存在。

面向用户的URL

MCP工具通过API管理数据，但用户通过网页浏览器访问Fast.io。请始终使用工具响应中的web_url字段——这是一个可直接使用、可点击的资源URL。每当您创建或引用工作区、分享、文件、笔记或传输时，请在您的响应中包含它。用户无法直接看到API响应——您提供的URL是他们访问其内容的方式。仅在web_url

字段缺失时（例如，分享上下文存储操作），才回退到以下URL模式：自动生成的web_url字段。所有返回实体的工具响应都包含一个web_url字段——这是一个可直接使用、对用户友好的资源URL。切勿手动构建URL——请始终使用工具响应中的它出现在以下场景：组织列表/详情/创建/更新/公开详情/发现-*、组织工作区列表/共享列表、工作区列表/详情/更新/可用/共享列表、共享列表/详情/创建/更新/公开详情/可用、存储列表/详情/搜索/回收站列表/复制/移动/重命名/恢复/添加文件/创建文件夹/版本列表/版本恢复/预览URL/预览转换、快速共享创建/获取/列表、上传文本文件/完成、下载文件URL/快速共享详情、AI聊天创建/聊天详情/聊天列表、传输令牌创建/列表，以及笔记创建/更新。仅当web_url不存在时（例如，共享上下文中的存储操作），才回退到下面的URL模式。

组织域名值会变成子域名："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}
快速分享	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 来源
域名	组织操作创建或详情响应
文件夹名称	组织操作创建工作区或工作区操作详情响应
节点ID	存储操作列表,创建文件夹, 或添加文件响应
自定义名称	分享操作创建或详情响应 (这个{标题-别名}是装饰性的 -- 分享仅通过自定义名称解析)
快速分享ID	工作区操作快速分享-创建响应
传输令牌	组织操作transfer-token-createresponse
chat_id	aiactionchat-create或chat-listresponse
note_id	workspaceactioncreate-note或storageactionlistresponse (node opaque ID)
comment_id	commentactionadd或listresponse
org_id	orgaction创建或列出回复

在这些情况下，请始终向用户提供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字段——这是一个简短的建议后续操作数组，使用确切的工具和动作名称。请根据这些提示引导工作流，而非自行猜测后续步骤。示例：_warnings

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

_warnings在具有破坏性、不可逆或潜在问题的操作上显示。执行前务必阅读警告——它们标记了永久性后果或重要注意事项。具有警告的操作包括：存储清理、存储批量复制/移动/删除/恢复（部分失败）、工作空间详情（intelligence=false）、工作空间更新（intelligence=false）、工作空间归档/删除、组织关闭、组织账单创建、共享删除、共享归档、共享更新（类型变更）、AI聊天删除、下载文件URL（令牌过期）、下载ZIP URL（需认证）、上传阶段Blob（5分钟过期）、组织转移令牌创建。恢复提示出现在错误响应中（当

isError: true时）。它们基于HTTP状态码和错误信息模式匹配提供恢复操作建议。错误信息还包含操作上下文（例如"执行中：组织创建"）以帮助定位失败的操作。HTTP状态恢复操作

400	检查必要参数和ID格式
401	重新认证：执行auth action signin或pkce-login
402	额度耗尽——检查余额：执行org action limits
402	Credits exhausted -- check balance: org action limits
403	权限被拒绝 -- 请检查角色：组织操作详情
404	资源未找到 -- 请验证ID，使用列表操作来发现有效的ID
409	冲突 -- 资源可能已存在
413	请求过大 -- 请减小文件/块大小
422	验证错误 -- 请检查字段格式和约束条件
429	频率受限 -- 等待2-4秒后重试，并使用指数退避策略
500/503	服务器错误 -- 2-5秒后重试

基于模式的恢复：错误信息也会与常见模式（例如，“邮箱未验证”、“工作空间未找到”、“智能功能已禁用”）进行匹配，以便即使在HTTP状态码是通用的情况下也能提供具体的恢复步骤。

ai_capabilities包含在工作空间详情响应中。它根据工作空间的智能设置显示哪些AI模式可用：

• 智能功能开启：files_scope,folders_scope,files_attach（完全RAG，带索引文档搜索）
• 智能关闭：files_attach仅限（最多20个文件，200 MB，无RAG索引）

_ai_state_legend当文件具有AI索引状态时，包含在存储列表和搜索响应中。状态：ready（已索引，可查询），pending（已排队），inprogress（索引中），disabled（智能关闭），failed（需要重新上传）。还包括_attach_field用于解释ai.attach布尔值——在使用前请检查此标志。文件附件.

上下文提供特定响应的上下文元数据。目前用于涉及锚定时的评论添加，提供锚点格式，包括图像区域、视频/音频时间戳和PDF页面的预期格式。

所有工具操作现在都包含下一步提示。每个成功的工具响应都包含上下文性的后续步骤建议。关键工作流转换包括：认证 → 组织列表/创建，组织创建 → 工作区创建，工作区创建 → 上传/分享/AI，上传 → AI聊天/评论/下载，分享创建 → 添加文件/成员，AI聊天创建 → 消息读取。这些提示包括确切的工具名称、操作以及当前响应中的相关ID。

工具注解：工具包含MCP注解提示 --只读提示、破坏性操作提示、幂等性提示（下载、事件），以及开放世界提示（组织、用户、工作区、共享、存储）——帮助客户理解工具行为，无需查阅文档。

资源补全与列表：工作区和共享下载资源模板均支持动态列表（resources/list）和 Tab 键补全（completion/complete）。动态列表会在客户端的资源选择器中显示跨工作区和共享的根级文件。Tab 键补全则会在您输入时建议有效的工作区和共享 ID。

无需认证的工具

以下操作无需会话即可执行：authactionssignin、signup、set-api-key、pkce-login、email-check、password-reset-request,password-reset; 和downloadactionquickshare-details.

---

8. MCP 应用程序（交互式 UI 小组件）

Fast.io MCP 服务器包含交互式 HTML5 小组件，可在智能体对话中直接渲染丰富的用户界面。这些小组件通过工具调用与 MCP 服务器通信，并显示文件浏览器、仪表板、工作流管理器等。

可用小组件

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

上传器组件

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

1. 选择目标位置-- 选择一个组织，然后选择一个工作区或共享空间，随后可选择导航至子文件夹
2. 选择文件-- 将文件拖放到组件上，或使用文件选择按钮浏览本地文件
3. 带进度显示的上传功能-- 文件自动上传并显示实时进度条。二进制文件采用分块上传方式（创建会话、暂存blob、分块上传、最终确认）。文本文件采用单步文本文件上传。网页URL采用网页导入方式
4. 在聊天中引用-- 上传完成后，点击"在聊天中引用"可将已上传文件附加到智能体会话中，供进一步讨论或AI分析使用

该小组件通过MCP桥接器使用上传工具（操作包括：创建会话、分块上传、最终确认、暂存blob、文本文件、网页导入、状态查询、取消上传、限制查询、扩展查询）和存储工具（操作：列表查询）

通过提示词启动：在桌面MCP客户端中使用应用：上传文件提示词

通过工具启动：

apps action launch app_id uploader context_type workspace context_id <workspace_id>

使用应用工具

该应用工具提供小组件发现和启动功能：

1. 列出应用： 应用操作列表-- 返回所有可用小部件及其元数据
2. 应用详情： 应用操作详情附带应用ID-- 获取特定小部件的完整元数据
3. 启动应用： 应用操作启动附带应用ID,上下文类型,上下文ID-- 在指定上下文中打开小部件
4. 查找工具的应用： 应用操作获取工具应用附带工具名称-- 将工具映射到其对应的小部件

小部件上下文

所有小部件都接受工作区或分享上下文：

• context_type: "workspace"+context_id: "<workspace_id>"
• context_type: "share"+context_id: "<share_id>"

设计系统

小部件使用与 Fast.io 前端相匹配的共享设计系统：

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

示例：启动文件选择器

apps action launch app_id file-picker context_type workspace context_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 密钥作为 Bearer 令牌使用，默认情况下具有与账户所有者相同的权限。范围受限的密钥将访问权限限制在特定实体（范围系统与 OAuth 令牌相同）。密钥会通过 API 验证并存储在会话中。所有后续的工具调用都会自动进行认证。未限定范围的 API 密钥除非被撤销，否则不会过期；范围受限的密钥可以设置可选的过期时间。

signup-- 创建一个新的 Fast.io 代理账户（agent=true），然后自动登录。将 account_type 设置为 "agent" 并分配免费代理计划。注册后需要进行邮箱验证——调用 email-verify 发送验证码，然后再次调用该操作并提供验证码以完成验证。大多数端点都需要已验证的邮箱。注册操作本身不需要认证。

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

session-- 获取已认证用户的当前会话信息，包括个人资料详情，如姓名、电子邮件和账户标志。

signout-- 通过清除存储的会话来退出登录。如果当前已认证，会先验证令牌。

2fa-verify-- 通过提交2FA验证码完成双因素认证。在登录返回 two_factor_required: true 后调用此接口。新的全权限令牌会自动存储。

email-check-- 检查电子邮件地址是否可用于注册。无需认证。

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

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

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

status-- 检查本地会话状态。不进行API调用。返回用户是否已认证，以及如果已认证，则返回其用户ID、电子邮件、令牌过期时间、权限范围（原始字符串）、权限范围详情（包含实体名称、域和父级层次结构的已解析数组——如果尚未获取则为null）和代理名称（如果已设置）。

pkce-login-- 启动基于浏览器的PKCE登录流程。返回一个URL供用户在浏览器中打开。登录并批准访问后，浏览器会显示一个授权码。用户复制该代码并提供给pkce-complete以完成登录。密码不会通过代理发送。可选参数：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（代理/应用程序名称，最多128个字符）。密钥过期时间（ISO 8601格式的过期日期时间——省略表示永不过期），令牌（双因素认证代码——在账户启用2FA时必需，使用API密钥认证时无需提供）。作用域密钥使用与v2.0 JWT令牌相同的作用域系统。

api-key-update——更新现有API密钥的元数据。需要提供密钥ID。可选参数包括：名称（备注/标签），作用域（JSON格式的作用域数组——发送空字符串以清除并恢复完全访问权限），代理名称（发送空字符串以清除），密钥过期时间（发送空字符串以清除过期时间）。仅更新指定的字段。

api-key-list——列出认证用户的所有API密钥。密钥值会被掩码处理（仅显示最后4个字符）。响应中包含作用域、代理名称, 和过期时间字段。

api-key-get-- 获取特定 API 密钥的详细信息。密钥值被隐藏。响应包含权限范围、代理名称和过期时间字段。

api-key-delete-- 撤销（删除）一个 API 密钥。此操作不可撤销。可选参数：token（双因素认证码 -- 当账户启用 2FA 时需要，使用 API 密钥认证时不需要）。

2fa-status-- 获取当前双因素认证配置状态（已启用、未验证或已禁用）。

2fa-enable-- 在指定通道上启用双因素认证。对于 TOTP，返回用于显示二维码的绑定 URI。账户将进入“未验证”状态，直到调用 2fa-verify-setup。

2fa-disable-- 从账户中禁用（移除）双因素认证。当双因素认证处于启用（已验证）状态时，需要提供有效的2FA验证码进行确认。

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

2fa-verify-setup-- 验证2FA设置代码以确认注册。将2FA状态从“未验证”转变为“已启用”。

oauth-list-- 列出已认证用户的所有活跃OAuth会话。

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

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

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

user

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

update-- 更新当前用户的个人资料（姓名、邮箱等）。

search-- 按姓名或电子邮件地址搜索用户。

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

按ID获取详情-- 通过用户ID获取其他用户的公开资料详情。

资料-- 检查用户可以访问哪些资料类型（组织、工作区、共享）。

允许-- 检查用户所在国家是否允许创建共享和组织。

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

列出共享-- 列出当前用户是其成员的所有共享。

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

邀请详情-- 通过ID或密钥获取特定邀请的详情。

接受所有邀请-- 一次性接受所有待处理的邀请。

资产上传-- 上传用户资产（例如个人资料照片）。请提供纯文本内容或base64编码的content_base64（二者选其一）。

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

asset-types-- 列出可供用户使用的资产类型。

asset-list-- 列出所有用户资产。

org

list-- 列出内部组织（用户直接所属的组织，member: true）。每个组织包含web_url。返回包含订阅状态、用户权限和计划信息的成员组织。非管理员成员仅能看到拥有活跃订阅的组织。不包含外部组织——如需查看外部组织，请使用 discover-external。

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

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

邀请成员-- 通过电子邮件邀请用户加入组织。电子邮件通过URL路径传递（而非请求体）。如果用户已有Fast.io账户，则直接添加；否则将发送电子邮件邀请。无法添加为所有者。

移除成员-- 从组织中移除一名成员。需要具备组织perm_member_manage设置所配置的成员管理权限。

更新成员角色-- 更新成员在组织中的角色/权限。无法将角色设置为“所有者”——请改用转移所有权功能。

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

列出工作空间-- 列出当前用户可访问的组织内工作空间。每个工作空间均包含web_url。所有者和管理员可查看全部工作空间；成员仅可查看符合加入权限设置的工作空间。

列出共享-- 列出当前用户可访问的共享。每个共享包含web_url。返回所有共享，包括上级组织和空间信息。使用响应中的 parent_org 来识别属于特定组织的共享。

create-- 在"agent"计费计划上创建一个新组织。需要domain（2-63个字符，小写字母数字+连字符）和name（3-100个字符，无控制字符）。认证用户将成为所有者。系统会自动创建一个存储实例和一个agent-plan订阅（免费，50 GB，每月5,000积分）。返回新组织和试用状态。

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

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

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

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

billing-plans-- 列出可用的计费方案，包含价格、功能和默认方案。返回创建订阅所需的方案ID。

billing-create-- 创建新订阅或更新现有订阅。对于新订阅，会创建一个Stripe设置意图。对于现有订阅，则更新方案。需要管理员或所有者权限。

billing-cancel-- 取消组织的订阅。需要所有者角色。某些方案在取消时可能导致组织被关闭。

billing-details-- 获取全面的计费和订阅详情，包括Stripe客户信息、订阅状态、设置意图、支付意图和方案信息。需要管理员或所有者权限。

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

billing-reset-- 重置计费状态（仅开发环境）。删除Stripe客户并移除订阅者标志。

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

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

leave-- 离开组织。移除当前用户自身的成员身份。所有者无法离开——他们必须先转移所有权或关闭组织。

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

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

transfer-token-create-- 为组织创建转移令牌（有效期为72小时）。将认领URLhttps://go.fast.io/claim?token=<token>发送给相关人员。在移交组织时，或在代理计划遇到402付款要求时使用。需要所有者角色。

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-- 从组织中删除资产。需要管理员或所有者角色。

资产类型-- 列出组织可用的资产类型。

资产列表-- 列出所有组织资产。

发现全部-- 列出所有可访问的组织（已加入 + 已受邀）。每个组织包含网站地址。返回包含用户关系状态指示符的组织数据。

发现可加入-- 列出可供加入的组织。每个组织包含网站地址。排除用户已是成员的组织。

发现检查域名-- 检查组织域名是否可用。验证格式、检查保留名称并检查现有域名。

发现外部组织-- 列出外部组织（成员：否）。每个组织包含网站地址用户仅能通过工作区成员身份访问的组织，而非作为组织的直接成员。常见于个人邀请代理加入工作区而未邀请其加入组织的情况。详见内部与外部组织（位于组织章节）。

工作区

列表-- 列出用户在所有组织中可访问的所有工作区。每个工作区包含网页链接。

详情-- 获取特定工作区的详细信息。返回网页链接。

更新-- 更新工作区设置，如名称、描述、品牌标识和权限。返回网页链接。

删除-- 永久关闭（软删除）工作区。需要所有者权限及确认。

归档-- 归档工作区（阻止修改，保留数据）。需要管理员及以上权限。

取消归档-- 将已归档的工作区恢复到活动状态。需要 Admin+ 权限。

成员列表-- 列出工作区的所有成员及其角色和状态。

列出共享-- 列出工作区内的所有共享，可选择按归档状态筛选。每个共享都包含网页链接。

导入共享-- 将用户拥有的共享导入到工作区。您必须是该共享的唯一所有者。

可加入列表-- 列出当前用户可以加入但尚未加入的工作区。每个工作区都包含网页链接。

检查名称-- 检查工作区文件夹名称是否可用。工作区名称具有全局唯一性。如果名称已被占用，可传递可选的检查组织ID来获取一个带组织ID前缀的替代建议（例如3587676312889739297-报告）。

创建笔记-- 在工作区存储中创建一个新的 Markdown 笔记。返回web_url（笔记预览链接）。

更新笔记-- 更新笔记的 Markdown 内容和/或名称（至少需要提供一项）。返回web_url（笔记预览链接）。

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

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

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

列出快速分享-- 列出工作区中所有活跃的快速分享。每个快速分享包括web_url。

元数据模板创建-- 在工作区中创建一个新的元数据模板。需要名称、描述、类别（法律、财务、业务、医疗、技术、工程、保险、教育、多媒体、人力资源）和字段（JSON编码的字段定义数组）。每个字段包含名称、描述、类型（字符串、整数、浮点数、布尔值、JSON、URL、日期时间）以及可选的约束（最小值、最大值、默认值、固定列表、是否可为空）。

元数据模板删除-- 删除一个元数据模板。系统模板和已锁定的模板无法删除。需要模板ID。

元数据模板列表-- 列出元数据模板。可选模板过滤器：启用、禁用、自定义（非系统）或系统。未指定过滤器时，返回所有未删除的模板。

元数据模板详情-- 获取元数据模板的完整详情，包括所有字段定义。需要模板ID。

元数据模板更新-- 更新现有的元数据模板。可以更新名称、描述、类别和字段的任意组合。需要模板ID。

元数据模板克隆-- 克隆一个元数据模板并进行可选修改。基于现有模板创建新模板。参数与元数据模板更新相同。需要模板ID。

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

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

metadata-template-resolve-- 解析适用于指定节点的元数据模板。返回工作区层级的模板（接受node_id参数，但目前会继承工作区模板）。如果未分配模板，则返回null。

metadata-template-assignments-- 列出工作区中的所有模板分配。

metadata-get-- 获取文件的所有元数据，包括符合模板的元数据和自定义（自由格式）的键值对。返回节点详情、template_id、template_metadata数组和custom_metadata数组。需要提供node_id。

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

metadata-delete-- 从文件中删除元数据。提供键名（JSON数组格式）可删除特定条目，不提供则删除所有元数据。仅适用于文件和笔记，不适用于文件夹。需要节点ID。

metadata-extract-- 触发基于AI的元数据提取功能。AI将分析文件内容，并根据模板填充元数据字段。提取的值会标记为 is_auto: true。消耗AI积分。可选 template_id（默认为工作区模板）。需要节点ID。

metadata-list-files-- 列出特定模板下拥有元数据的文件，支持可选的筛选和排序。需要节点ID（要搜索的文件夹）和 template_id。可选参数包括 metadata_filters（JSON编码）、order_by（字段键）和 order_desc。

metadata-list-templates-in-use-- 列出文件夹中正在使用的元数据模板，并显示每个模板的使用计数。需要节点ID。

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

enable-workflow-- 在工作区启用工作流功能（任务、工作日志、审批、待办事项）。必须先调用此命令，才能在工作区使用工作流工具。

disable-workflow-- 在某个工作区中禁用工作流功能。所有工作流数据均会被保留，但在重新启用前无法访问。

share

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

details-- 获取特定共享的完整详细信息。返回web_url。

create-- 在工作区中创建一个新的共享。

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

delete-- 删除（关闭）一个共享。需要提供共享ID或自定义名称以进行确认。

public-details-- 获取面向公众的共享信息（无需成员身份，仅需认证）。

archive-- 归档一个共享。阻止访客访问并限制修改。

unarchive-- 将先前归档的共享恢复为活动状态。

password-auth-- 使用共享密码进行身份验证。返回一个用于该共享的范围化JWT。

members-- 列出共享的所有成员。

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

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

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

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

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

存储

所有存储操作都需要context_type参数（workspace或share）和context_id（19位数字的配置文件ID）。

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

recent-- 列出所有目录中最近修改的文件和文件夹，按更新时间降序排序。与list命令（其作用范围仅限于单个文件夹）不同，此命令返回整个存储树中的节点。支持可选的type类型过滤器（file文件、folder文件夹、link链接、note笔记），page_size页面大小（100、250 或 500），以及用于分页的cursor游标。对于工作区文件夹共享，结果会自动过滤到该共享的子目录树。

details-- 获取特定文件或文件夹的完整详细信息。返回web_url（指向 Web 界面中文件预览或文件夹的、便于用户访问的链接，仅限工作区）。

search-- 通过关键词或语义查询搜索文件。每个结果包含web_url（仅限工作空间）。

trash-list-- 列出当前在回收站中的项目。每个项目包含web_url（仅限工作空间）。

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

copy-- 复制文件/文件夹。单个复制通过node_id（工作空间或共享）。批量复制通过node_ids数组（仅限工作空间）。返回web_url在新副本上（仅限工作空间）。

move-- 移动文件/文件夹。单个移动通过node_id（工作空间或共享）。批量移动通过节点ID数组（仅工作区）。返回网页地址（仅工作区）。

删除-- 通过将文件/文件夹移至回收站来删除。单次删除通过节点ID（工作区或共享）。批量删除通过节点ID数组（仅工作区）。

重命名-- 重命名文件或文件夹。返回网页地址（仅工作区）。

永久删除-- 永久删除回收站中的节点（不可逆）。需要成员权限。

恢复-- 从回收站恢复文件/文件夹。单次恢复通过节点ID（工作区或共享）。批量恢复通过节点ID数组（仅工作区）。返回网页地址在已恢复的节点上（仅限工作区）。

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

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

transfer-- 将节点复制或移动到另一个工作区或共享存储实例。默认模式为'copy'（保留源节点）。使用 transfer_mode='move' 复制后删除源节点（不能移动根节点）。当模式为 move 时，响应包含 source_trashed（布尔值），表示源节点是否被成功删除。

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

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

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

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

解除锁定-- 释放文件的独占锁。

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

预览转换-- 请求文件转换（图像调整大小、裁剪、格式转换）并获取结果的下载链接。需要transform_name参数。返回transform_url（可直接使用的链接）和web_url（指向网页界面中文件的可读链接，仅限工作区）。

上传

创建会话-- 为文件创建一个分块上传会话。

分块-- 上传单个分块。对于文本/字符串使用content，对于Base64编码的二进制数据使用data，或者对于通过stage-blob操作或POST /blob暂存的二进制数据使用blob_ref。请只提供其中一种。

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

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

取消-- 取消并删除一个活跃的上传会话。

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

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

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

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

stage-blob-- 将base64编码的二进制数据暂存为blob，以备后续与chunk操作的blob_ref参数配合使用。传递data（base64字符串）。返回{ blob_id, size }。Blob会在5分钟后过期，并在首次使用时被消耗。这是作为在chunk调用中直接传递data的替代方案。

text-file-- 使用Fast.io单请求上传模式，一步上传文本文件。通过单个多部分POST请求发送文件，并直接返回新文件ID。适用于基于文本的文件（代码、Markdown、CSV、JSON、配置文件），而不是多步分块流程。

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

web-list-- 列出用户的网络上传任务，可选择过滤条件。

web-cancel-- 取消一个活跃的网络上传任务。

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

limits-- 获取用户套餐的上传大小和分块限制。

extensions-- 获取上传文件的受限和允许的文件扩展名。

download

file-url-- 获取文件的下载令牌和URL。可选择指定版本。需要context_type,context_id,节点ID.

zip-url-- 获取文件夹或整个工作区/共享的ZIP下载URL。返回包含认证说明的URL。需要context_type、context_id和node_id（对整个存储树使用root）。

quickshare-details-- 获取快速共享链接的元数据和下载信息。无需认证。

ai

所有AI操作都需要context_type参数（workspace或share）和context_id（19位数字的配置文件ID）。

chat-create-- 创建一个新的AI聊天，附带一个初始问题。默认范围是整个工作空间（所有已索引的文档）——除非需要缩小搜索范围，否则请省略files_scope和folders_scope。当使用范围或附件时，请提供nodeId:versionId对——如果留空，versionId会自动解析为当前版本（从存储列表/详细信息中获取明确的versionId）。当使用files_attach时，请首先验证每个文件的ai.attach是否为true（通过存储详细信息检查）。类型会自动从chat升级为chat_with_filestochat_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响应完成，然后返回完整文本。

搜索-- 在已索引的文档和代码中进行语义搜索。返回带有相关性分数的排序文档片段 -- 比 AI 聊天更快、更轻量（无状态 GET，无需 LLM 推理）。需要开启 Intelligence 功能。参数：query_text（2-1,000 个字符），可选files_scope、folders_scope（格式与聊天范围限定相同）、limit（1-500，默认 100）、offset。结果包含内容片段、分数以及带有web_url（仅工作区）的源文件详细信息。使用搜索查找相关文档，然后通过聊天功能询问相关问题。

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

transactions-- 列出用于账单跟踪的 AI 令牌使用交易记录。

autotitle-- 根据内容生成AI驱动的标题和描述（仅分享上下文）。

评论

所有评论端点使用路径模式/comments/{entity_type}/{parent_id}/或/comments/{entity_type}/{parent_id}/{node_id}/其中entity_type是workspace或share，parent_id是19位数字的配置文件ID，且node_id是文件的不透明ID。

列表-- 列出特定文件（节点）上的评论。参数：排序（created/-created）、限制（2-200）、偏移量、包含已删除项、引用类型过滤器、包含总数。

list-all-- 列出工作区或共享中的所有评论（非节点特定）。使用与 list 相同的列表参数。

add-- 向特定文件添加评论。正文：文本（总计最多 8,192 个字符，显示文本最多 2,048 个字符，且@[...]提及标签会被剥离）。支持提及标签：@[profile:id]、@[user:opaqueId:Name]、@[file:fileId:name.ext]。可选 parent_comment_id（单级线程，对回复的回复会自动展平），可选 reference（类型、时间戳、页码、区域、text_snippet 用于内容锚定；exact、prefix、suffix、start_offset、end_offset 用于 markdown/notes 上的文本锚定——使用类型"document"或"text"），可选 linked_entity_type（task或approval) 以及 linked_entity_id，用于在创建时将评论关联到工作流实体。使用 JSON 请求体。

删除-- 删除一条评论。递归式：删除父评论也会移除其所有回复。

批量删除-- 批量软删除多条评论（最多100条）。非递归式：被删除评论的回复将被保留。

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

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

移除反应-- 从评论中移除你的表情符号反应。

关联-- 将现有评论关联到工作流实体。参数：comment_id, linked_entity_type (任务或审批), 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时间戳。

member

所有成员操作都需要entity_type参数（workspace或share）和entity_id（19位数字的配置文件ID）。

add-- 通过用户ID添加现有用户，或通过电子邮件邀请。将电子邮件地址或用户ID作为email_or_user_id传递。对于工作区，使用permissions（管理员/成员/访客）设置访问级别。对于共享，使用角色（管理员/成员/访客/查看者）。

移除-- 移除一名成员（无法移除所有者）。

详情-- 获取特定成员的详细成员信息。对于工作区，传递member_id；对于共享，传递user_id。

更新-- 更新成员的权限、通知或有效期。

转移所有权-- 将所有权转移给另一名成员（当前所有者降级为管理员）。

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

加入-- 基于组织成员身份自行加入。

加入邀请-- 使用邀请密钥接受或拒绝邀请。

邀请

所有邀请操作都需要实体类型参数（工作空间或共享）和实体ID（19位配置文件ID）。

列表-- 列出所有待处理的邀请。

按状态列表-- 按状态筛选并列出邀请。

更新-- 重新发送或更新邀请（通过ID或受邀者邮箱）。

删除-- 撤销并删除一个待处理的邀请。

资产

所有资产操作都需要实体类型参数（组织、工作空间、共享或者用户) 和实体ID（组织/工作区/分享的19位配置文件ID）。

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

删除-- 删除一个资产。

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

列表-- 列出该实体的所有资产。

读取-- 读取/下载一个资产。

任务

工作区和分享的任务列表和任务管理。所有任务操作都要求目标实体启用了工作流（工作区操作启用工作流或分享操作）。启用工作流)。

列出清单-- 列出工作区或共享的所有任务清单。需要profile_type和profile_id。支持sort_by（创建时间、更新时间、名称）、sort_dir、limit（1-200）、offset和format（"md" 表示 Markdown 格式）。

创建清单-- 创建新的任务清单。需要profile_type、profile_id和name（1-255 个字符）。可选描述（最多2000个字符）。

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

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

delete-list-- 软删除一个任务列表及其所有任务。需要list_id。此操作具有破坏性。

list-tasks-- 列出任务列表中的任务。需要list_id。支持status筛选器,负责人,筛选器,排序依据(创建时间, 更新时间, 名称, 优先级, 状态),排序方向,限制数量(1-200),偏移量, 以及格式.

创建任务-- 在列表中创建新任务。需要列表ID和标题(1-500个字符)。可选参数描述(最长5000个字符),状态(待处理, 进行中, 已完成, 已阻塞),优先级(0=无, 1=低, 2=中, 3=高, 4=紧急),负责人ID（个人资料ID），依赖项（任务ID数组），节点ID（指向文件/文件夹/笔记的链接）。

任务详情-- 获取特定任务的完整详情。需要列表ID和任务ID。支持格式。

更新任务-- 更新任务的标题、描述、状态、优先级、负责人、依赖项或节点链接。需要列表ID和任务ID。

删除任务-- 软删除一个任务。需要列表ID和任务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使用。

worklog

用于追踪代理工作记录的活动日志。在上传、任务变更、创建共享或任何重要操作后，请记录您所做的操作及原因——为人员和AI构建可搜索的审计跟踪。所有worklog操作都要求目标实体启用工作流功能。

append-- 向worklog追加新条目。需要entity_type（"task"、"task_list"、"node"或"profile"）、entity_id以及content（1-10000个字符）。请在执行变更后使用此功能记录操作内容和原因。条目创建后不可更改。

list-- 列出工作日志条目。需要entity_type（"task"、"task_list"、"node" 或 "profile"）和entity_id（对应实体的不透明ID，或 entity_type 为 "profile" 时的个人资料19位ID）。支持type筛选（"entry" 或 "interjection"）、sort_dir（"asc" 或 "desc"，默认为 "desc"）、limit（1-200）、offset，以及format（"md" 表示 markdown 格式）。

interject-- 创建一个需要确认的紧急插话条目。需要entity_type（"task"、"task_list"、"node" 或 "profile"）、entity_id，和content（1-10000个字符）。打断标记优先处理——始终视为紧急事项。

详情-- 获取特定工作日志条目的完整详情。需要条目ID。支持格式。

确认-- 确认一个打断标记条目，将其标记为已查看。需要条目ID。只有可确认: 真的条目才能被确认。

未确认-- 列出未确认的打断标记（即可确认为真的条目）。需要实体类型（"任务"、"任务列表"、"节点"或"档案"）和实体ID。支持限制,偏移量，以及格式。在进行工作前，务必检查是否有未被确认的插话。

审批

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

列表——列出工作区或共享的审批请求。需要profile_type和profile_id。支持状态筛选（待处理、已批准、已拒绝）、限制（1-200，默认100）、偏移量，以及格式。

创建-- 创建新的审批请求。需要实体类型("task"、"node" 或 "worklog_entry")，实体ID、用户ID和描述(1-5000字符)。可选参数包括审批人ID（指定审批人的用户ID），截止时间（ISO 8601格式），节点ID（工件引用）。

详情-- 获取审批请求的完整详情，包括审批人列表和决议。需要审批ID（不透明字母数字字符串）。支持格式参数。

解决-- 解决审批请求。需要审批ID并且resolve_action("approve" 或 "reject")。可选comment（最多5000个字符）。只有指定的审批人才能处理。

todo

简单、扁平的清单，范围限定于工作区和共享。无嵌套。所有待办事项操作都要求目标实体启用了工作流。

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

创建-- 创建一个新的待办事项。需要profile_type、profile_id和title（1-500个字符）。可选assignee_id。

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

更新-- 更新待办事项。需要todo_id。支持title、assignee_id、done。

删除-- 软删除一个待办事项。需要todo_id。破坏性操作。

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

批量切换-- 同时设置多个待办事项的完成状态。需要profile_type、profile_id、todo_ids（待办事项ID数组，最多100个），以及done（布尔值：true表示标记为已完成，false表示标记为未完成）。

应用

交互式MCP应用小部件的发现和启动。小部件是在智能体对话中呈现的交互式HTML5用户界面。

列表-- 列出所有可用的MCP应用小部件及其元数据（标题、描述、支持的工具、支持的操作、资源URI）。

详情-- 获取特定小部件的完整元数据。需要app_id（小部件名称，例如 "file-picker"）。

launch-- 在工作区或分享上下文中启动一个小部件。需要app_id、context_type（"workspace" 或 "share"）以及context_id（19位数字的配置文件ID）。返回准备渲染的小部件HTML内容。

get-tool-apps-- 查找与特定工具域关联的小部件。需要tool_name（例如 "storage"、"ai"、"comment"）。返回为该工具操作提供UI的小部件。

---

10. 代码模式（无头代理）

当从无头代理（Claude Code、Cursor、Continue等）连接时，服务器会自动启用代码模式——这是完整19个工具集的轻量级替代方案。代码模式总共暴露4个工具：

工具	用途
认证	认证（登录、注册、API密钥、PKCE、双因素认证）
上传	文件上传（分块上传、文本上传、网页导入）
搜索	通过关键词、标签或概念发现API端点
执行	向Fast.io发起经过认证的API调用

支持MCP应用的客户端（Claude Desktop、Cline）继续接收完整的19个工具集以及12个应用小部件工具。未知客户端默认使用完整工具集。

搜索工具

通过关键词、路径或概念查询API规范。返回匹配的端点及其方法、路径、参数和描述。

search query="list files in workspace" tag="storage"
search query="create share" tag="share"
search query="authentication"
search query="pagination" include_concepts=true

参数：

• 查询（字符串，必需）—— 要搜索的关键词、端点路径或概念
• 标签（字符串，可选）—— 按领域筛选：认证、工作区、存储、人工智能、分享、上传、组织、用户、成员、评论、事件、元数据等。
• 包含概念（布尔值，可选）—— 包含概念文档（分页、ID、错误）。默认为true。

执行工具

向 Fast.io REST API 发起经过身份验证的 API 调用。请先使用搜索功能来发现端点。

方法：

• 获取-- 可附带可选查询参数的 GET 请求
• 提交-- 使用表单编码正文的 POST 请求（默认 API 格式）
• 提交Json-- 使用 JSON 正文的 POST 请求
• 删除-- DELETE 请求
• 放置-- 使用表单编码正文的 PUT 请求

身份验证令牌会自动注入。路径参数必须由调用者填写（将{workspace_id}替换为实际 ID）。对于多步骤操作，请进行多次顺序执行调用。

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"}

参数：

• 方法（枚举，必需）-- HTTP 方法："get"、"post"、"postJson"、"delete"、"put"
• 路径（字符串，必需）-- API端点路径（例如，'/orgs/list/', '/workspace/{workspace_id}'）
• 请求体（对象，可选）-- 请求体（对于post/put请求为表单编码，对于postJson请求为JSON格式）
• 参数（对象，可选）-- 附加到URL的查询参数
• 超时时间（毫秒）（数字，可选）-- 超时时间，单位为毫秒（默认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}"

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。