Fast.io

# Fast.io MCP Server -- AI Agent Guide

**版本：** 1.84 **最后更新：** 2026-02-19

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

> **版本化指南。** 本指南随每次服务器发布进行版本控制和更新。本文档顶部的版本号会跟踪工具参数、ID 格式和 API 行为的更改。如果您遇到意外错误，可能是自您上次阅读以来指南版本已更改。

> **平台参考。** 有关 Fast.io 功能的全面概述、代理计划、关键工作流和升级路径，请参阅 [references/REFERENCE.md](references/REFERENCE.md)。

---

## 1. 概述

**面向代理团队的工作区。通过一个 API 进行协作、共享和查询 -- 全部免费。**

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`

每个端点提供两种传输方式：

- **位于 `/mcp` 的可流式传输 HTTP** -- 新集成的首选传输方式。 - **位于 `/sse` 的 SSE** -- 为向后兼容而维护的传统传输方式。

### MCP 资源

服务器公开了两个静态 MCP 资源和三个文件下载资源模板。客户端可以通过 `resources/list` 和 `resources/read` 读取它们：

| URI | 名称 | 描述 | 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_detail`（包含实体名称/域/父级的完全填充范围对象的数组，或 null）、`agent_name`（字符串或 null） | `application/json` |

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

| 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 | 无（公开） | 否 | 下载快速共享文件 |

最大 50 MB 的文件会作为 base64 编码的 blob 内容内联返回。较大的文件返回带有 HTTP 直通端点 URL 的文本回退（见下文）。`download` 工具响应包含适用于每个文件的适当 URI 的 `resource_uri` 字段。

**动态资源列表：** 身份验证后，工作区和共享文件资源通过 `resources/list` 动态列出。MCP 客户端（例如 Claude Desktop 的 `@` 提及选择器）可以在无需任何工具调用的情况下发现可用文件。最多枚举 10 个工作区和 10 个共享，每个工作区和共享最多包含 25 个最近更新的根级文件。资源显示为“WorkspaceName / filename.ext”或“ShareTitle / filename.ext”。结果按会话缓存 1 分钟。仅列出根级文件 -- 不会递归枚举子目录。使用带有操作 `list` 的 `storage` 工具进行更深入的浏览。快速共享模板仅保持模板形式，不可动态枚举。

### 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 协议通信的会话标识符相同。

### 工作流概述

服务器包含用于项目跟踪的工作流功能：**任务**（具有优先级和受让人的结构化工作项）、**工作日志**（仅追加的活动日志）、**审批**（正式的签署请求）和**待办事项**（简单的检查清单）。在使用这些工具之前，使用带有 `enable-workflow` 操作的 `workspace` 在工作区上启用工作流。有关完整模式，请参阅第 6 节中的 **完整代理工作流** 配方。

**最佳实践（重要）：** 在更改状态的操作（上传文件、创建共享、更改任务状态、成员更改、文件移动/删除）之后，追加一条工作日志条目，描述您所做的工作以及原因。如果没有工作日志条目，代理的工作对于审查工作区的人类来说是不可见的。对于多个相关操作（例如，上传几个文件），您可以在批次完成后记录一次，而不是在每次单独操作后记录。工作日志条目是仅追加且永久的。

### 云端导入概述

服务器支持将外部云存储提供商（Google Drive、Dropbox、Box、OneDrive for Business）的文件导入工作区存储。在使用导入工具之前，使用带有 `enable-import` 操作的 `workspace` 在工作区上启用云端导入。有关完整模式，请参阅第 6 节中的 **云端导入** 工作流。

云端导入使用服务账户模型：每个工作区为每个提供商获得一个唯一的代理身份。用户与代理电子邮件共享一个文件夹，系统会发现这些共享文件夹并将其同步到工作区存储中。导入的文件是具有导入元数据的常规存储节点 -- 搜索、AI、预览和评论均可正常工作。

**关键概念：** - **提供商身份** -- 为每个工作区的每个提供商配置的服务账户电子邮件。用户与此电子邮件共享云文件夹。 - **导入源** -- 从一个远程共享文件夹到本地工作区文件夹的映射。定期同步（默认：1 小时）。 - **导入作业** -- 同步操作（full_sync、incremental 或 discovery）。作业跟踪文件计数、传输字节数和预计完成时间以跟踪进度。 - **写回** -- 对于 read_write 源，修改的文件会自动排队以推回远程提供商。当远程文件自上次同步以来发生更改时，会检测到冲突。

### 其他参考

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

---

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

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

- `auth`，包含以下操作：`signin`、`signup`、`set-api-key`、`pkce-login`、`email-check`、`password-reset-request`、`password-reset` - `download`，包含以下操作：`quickshare-details`

### 选择合适的方法

根据是自主运行还是协助现有的人类用户，有三种方式可以作为代理使用 Fast.io。

**选项 1：自主代理 -- 创建代理账户**

如果您独立运行（存储文件、运行工作流、为用户构建工作区），请使用 `auth` 操作 `signup` 创建您自己的代理账户。代理账户将获得免费代理计划（50 GB，5,000 每月额度），并可以在准备好时将组织移交给人类。这是自主代理的推荐路径。有关步骤，请参阅下方的 **代理账户创建**。

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

如果人类已经拥有 Fast.io 账户并希望您帮助管理他们的文件、工作区或共享，他们可以为您创建一个 API 密钥以供使用。无需单独的代理账户 -- 您作为人类用户进行操作。人类可以在 Settings -> Devices & Agents -> API Keys（直接链接：`https://go.fast.io/settings/api-keys`）创建密钥。调用带有 `set-api-key` 操作的 `auth` 并传入该密钥进行身份验证 -- 该密钥将被自动验证并存储在会话中。API 密钥是 JWT 令牌的 1:1 替代品：它们作为不记名令牌工作，具有与账户所有者相同的权限，除非被撤销否则不会过期。代理还可以使用 `auth` 操作 `api-key-create`、`api-key-list` 和 `api-key-delete` 以编程方式管理 API 密钥。

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

如果您希望拥有自己的代理身份但需要在人类现有的组织内工作，请使用 `auth` 操作 `signup` 创建代理账户，然后让人类使用 `member` 操作 `add`（实体类型 `org`）邀请您加入他们的组织，或使用 `member` 操作 `add`（实体类型 `workspace`）邀请您加入工作区。或者，人类也可以通过 UI 邀请：Settings -> Your Organization -> Manage People。这使您可以访问他们的工作区和共享，同时保持您自己的账户独立。在使用 `user` 操作 `accept-all-invitations` 接受邀请后，使用 `auth` 操作 `signin` 进行正常身份验证。**注意：** 如果人类仅邀请您加入工作区（而非组织），该组织将显示为外部组织 -- 请参阅组织部分中的 **内部与外部组织**。

**选项 4：浏览器登录**

如果您不希望通过代理发送密码，请使用基于浏览器的 PKCE 登录。调用带有 `pkce-login` 操作的 `auth`（可选地带有 `email` 提示）以获取登录 URL。用户在浏览器中打开该 URL，登录（电子邮件/密码或 SSO，如 Google/Microsoft），并批准访问。浏览器会显示一个授权码，用户将其复制回代理。调用带有该代码的 `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` 授予对用户拥有成员资格的所有共享的直接访问权限，绕过工作区/组织继承

`agent_name` 参数控制用户在批准屏幕上看到的内容 -- 屏幕上会显示“**[agent_name]** 将代表您执行操作”。如果省略，则仅显示客户端名称。请使用描述性名称，以便用户知道哪个代理正在请求访问。

**按 scope_type 划分的批准流程：**

- **`user`**（默认）：完整账户访问权限。用户会看到一个简单的批准/拒绝提示，没有实体选择器。 - **`org`**、**`workspace`**：用户会看到一个实体选择屏幕，其中列出了其可访问的实体（带有复选框），以及一个只读/读写切换开关。用户选择要授予的实体，然后批准或拒绝。 - **`all_orgs`**、**`all_workspaces`**、**`all_shares`**：用户会看到正在请求的通配符访问的摘要（没有实体选择器），然后批准或拒绝。

MCP 服务器默认为 `scope_type="user"` 以保持向后兼容性。

| 场景 | 推荐方法 | |----------|---------------------| | 自主运行，存储文件，为用户构建 | 创建一个带有自己组织的代理账户（选项 1） | | 帮助人类管理其现有账户 | 请人类为您创建一个 API 密钥（选项 2） | | 在人类的组织内以自己的身份工作 | 创建一个代理账户，让人类邀请您（选项 3） | | 构建某些东西以移交给人类 | 创建一个代理账户，进行构建，然后移交组织（选项 1） | | 在不通过代理发送密码的情况下登录 | 基于浏览器的 PKCE 登录（选项 4） |

**按账户类型划分的额度限制：** 代理账户（选项 1、3）可以在额度用尽时将组织移交给人类 -- 请参阅第 3 节中的所有权转移。人类账户（选项 2）不能使用转移/认领 API；请引导人类前往 `https://go.fast.io/settings/billing` 升级其计划，或通过 `org` 操作 `billing-create`。

### 标准登录流程

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

### 代理账户创建

创建新账户时（上面的选项 1 和 3），代理 **必须** 使用 `auth` 操作 `signup`，该操作将自动以 `agent=true` 注册。切勿注册为人类账户。代理账户提供：

- `account_type` 设置为 `"agent"` - 自动分配免费代理计划 - 启用用于将组织移交给人类的转移/认领工作流

**步骤：**

1. （可选）在尝试注册之前，调用带有所需 `email` 的 `auth` 操作 `email-check`，以验证该电子邮件是否可用于注册。 2. 调用带有 `first_name`、`last_name`、`email` 和 `password` 的 `auth` 操作 `signup`。MCP 服务器会自动发送 `agent=true` 标志。 3. 账户已创建并自动建立会话 -- 代理立即登录。 4. **验证您的电子邮件**（在使用大多数端点之前是必需的）：调用带有 `email` 的 `auth` 操作 `email-verify` 以发送验证码，然后再次调用带有 `email` 和 `email_token` 的 `auth` 操作 `email-verify` 以验证该代码。 5. 不需要信用卡。没有试用期。没有过期时间。账户无限期存在。

### 双因素身份验证流程

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

### 浏览器登录 流程

1. 调用带有操作 `pkce-login` 的 `auth`（可选地带有 `email` 以预填充登录表单，带有 `scope_type` 以请求范围访问，以及带有 `agent_name` 以标识代理）。 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、电子邮件、令牌过期时间、范围和 agent_name。 - `auth` 操作 `check` -- 根据 Fast.io API 验证令牌。如果令牌仍然有效，则返回用户 ID。

### 会话过期

JWT 令牌持续 **1 小时**。API 密钥（在协助人类时使用）除非被撤销否则不会过期。当 JWT 会话过期时，工具调用会返回明确的错误，指出需要重新进行身份验证。再次调用带有 `signin` 操作的 `auth` 以建立新会话。MCP 服务器不会自动刷新令牌。

**提示：** 对于长时间运行的会话，请在开始多步骤工作流之前使用 `auth` 操作 `status` 检查剩余的令牌生存时间。如果令牌即将过期，请先重新进行身份验证，以避免工作流中途中断。

### 退出登录

调用带有操作 `signout` 的 `auth` 以从 Durable Object 清除存储的会话。

---

## 3. 核心概念

### 组织

组织是用于收集工作区的顶层容器。组织可以代表一家公司、一个业务单元、一个团队，或者仅仅是您个人的个人收藏。每个用户都属于一个或多个组织。组织具有：

- **工作区** —— 属于该组织的文件存储容器。 - 拥有所有者、管理员、成员、访客、查看者角色的**成员**。 - 通过 Stripe 集成管理的**计费和订阅**。 - 管理存储空间、传输量、AI 令牌和成员数量的**计划限制**。

组织由一个 19 位数字的个人资料 ID 或一个域名字符串标识。

**重要：** 创建组织时，代理**必须**使用 `org` 动作 `create`，该操作会自动分配 `billing_plan: "agent"`。这可确保组织获得免费的代理计划（50 GB，每月 5,000 积分）。对于代理创建的组织，请勿使用任何其他计费计划。

#### 组织发现（重要）

要发现所有可用的组织，代理**必须同时调用两个动作**：

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

**仅检查 `org` 动作 `list` 的代理将完全错过外部组织，并且无法发现其被邀请加入的工作区。** 当人类邀请代理协助特定项目时，外部组织是最常见的模式 —— 他们将代理添加到工作区，但不会添加到组织本身。

#### 内部与外部组织

**内部组织**（`member: true`） —— 您创建或受邀作为成员加入的组织。您拥有组织级别的访问权限：您可以查看所有工作区（受权限限制），如果是管理员，可以管理设置，并且会出现在组织的成员列表中。

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

**示例：** 某人邀请您的代理加入他们的“Q4 报告”工作区。您可以在该工作区上传文件、运行 AI 查询并进行协作。但您无法在其组织中创建新工作区、查看其计费信息或访问其其他工作区。该组织会通过 `org` 动作 `discover-external` 显示 —— 而不是 `org` 动作 `list`。如果该人稍后将您邀请加入组织本身，该组织将从外部变为内部。

### 工作区

工作区是组织内的文件存储容器。每个工作区都有：

- 自己的一组具有角色（所有者、管理员、成员、访客）的**成员**。 - 由文件和文件夹（存储节点）组成的**存储树**。 - 用于 RAG 聊天的可选 **AI 功能**。 - 可在工作区内创建的**共享**。 - **归档/取消归档**生命周期管理。 - 免费代理计划包含 **50 GB 存储空间**，每次上传文件最大为 1 GB。 - **文件版本控制** —— 每次编辑都会创建一个新版本，旧版本可恢复。 - **全文和语义搜索** —— 按名称或内容查找文件，以及按含义查找文档。

工作区由一个 19 位数字的个人资料 ID 标识。

#### 智能：开启或关闭

工作区具有一个**智能**切换开关，用于控制是否启用 AI 功能：

**智能关闭** —— 工作区为纯文件存储。您仍可以将文件直接附加到 AI 聊天对话（最多 20 个文件，总计 200 MB），但文件不会被持久化索引。这适用于不需要查询内容的简单存储和共享。

**智能开启** —— 工作区变为 AI 驱动的知识库。上传的每个文档和代码文件都会自动被摄取、总结并建立 RAG 索引。这可实现：

- **RAG（检索增强生成）** —— 将 AI 聊天范围限定为整个文件夹或整个工作区，并针对索引的文档和代码提问。AI 会检索相关段落并引用来源进行回答。 - **语义搜索** —— 按含义查找文件，而不仅仅是关键词。即使文件名中没有确切的词语，“向我展示包含赔偿条款的合同”也能找到。 - **自动总结** —— 为每个索引的文档和代码文件生成简短和详细的摘要，可搜索并在 UI 中可见。 - **元数据提取** —— AI 自动从文档中提取关键元数据。

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

对于代理帐户通过 API 创建的工作区，智能默认为开启。如果工作区仅用于文件存储和共享，请将其关闭以节省积分。如果您需要查询内容，请保持启用状态。

**代理用例：** 为每个项目或客户创建一个工作区。如果需要稍后查询内容，请启用智能。上传报告、数据集和交付成果。邀请其他代理和人类利益相关者。一切都是有序、可搜索且有版本记录的。

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

### 共享

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

| 模式 | 功能 | 代理用例 | |------|-------------|----------------| | **发送** | 收件人可以下载文件 | 交付报告、导出、生成的内容 | | **接收** | 收件人可以上传文件 | 收集文档、数据集、用户提交 | | **交换** | 同时上传和下载 | 协作工作流、审查周期 |

#### 共享功能

- **密码保护** —— 要求输入密码才能访问链接 - **过期日期** —— 共享在设定时间段后自动过期 - **下载控制** —— 启用或禁用文件下载 - **访问级别** —— 仅限成员、组织成员、注册用户或公开（任何拥有链接的人） - **自定义品牌** —— 背景图像、渐变色、强调色、徽标 - **下载后消息** —— 下载后显示自定义消息和链接 - **每个共享最多 3 个自定义链接**，用于提供上下文或行动号召 - **访客聊天** —— 让共享接收者实时提问 - **AI 驱动的自动标题** —— 共享根据其内容自动生成智能标题 - **活动通知** —— 在发送或接收文件时收到通知 - **评论控制** —— 配置谁可以查看和发布评论（所有者、访客或两者）

#### 两种存储模式

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

- **`room`**（独立存储，默认） —— 共享拥有自己独立的存储空间。文件直接添加到共享中，独立于任何工作区。这会创建一个自包含的数据室 —— 对工作区文件的更改不会影响数据室，反之亦然。用于最终交付成果、合规包、归档报告，或任何您希望获得不可变快照的场景。

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

对于共享接收者来说，这两种模式看起来是一样的 —— 一个带有文件预览、下载控制和所有共享功能的品牌化数据室。区别在于内容是快照还是实时视图。

共享由一个 19 位数字的个人资料 ID 标识。

**代理用例：** 生成季度报告，创建一个具有客户品牌的 Send 共享，设置 30 天过期日期，然后共享链接。客户将看到一个专业的、有品牌标识的页面以及即时文件预览 —— 而不是原始下载链接。

### 存储节点

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

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

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

### Notes

Notes 是一种存储节点类型（与文件和文件夹一起），直接在服务器上存储 Markdown 内容。它们与文件位于同一文件夹层次结构中，像任何其他节点一样进行版本控制，并且在存储列表中以 `type: "note"` 显示。

#### 创建和更新 Notes

使用 `workspace` 动作 `create-note` 创建 Notes，并使用 `workspace` 动作 `update-note` 更新 Notes。

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

**更新：** 提供 `workspace_id`、`node_id` 以及至少一个 `name`（必须以 `.md` 结尾）或 `content`（最多 100 KB）。

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

#### 作为长期知识基础的 Notes

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

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

关键行为：

- 启用工作区智能后，笔记会被摄取用于 RAG - 文件夹范围内的笔记会被包含在范围查询中 - 具有 `ai_state: ready` 的笔记可通过 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 聊天允许智能体询问有关存储在工作区和共享中的文件的问题。提供两种聊天类型，每种类型具有不同的文件上下文选项。

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

#### 两种聊天类型

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

当相关时，这两种类型都会使用网络知识来增强回答。

#### 文件上下文：范围 vs 附件

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

| 功能 | 文件夹/文件范围 (RAG) | 文件附件 | |---------|------------------------|------------------| | 工作原理 | 限制 RAG 搜索空间 | 由 AI 直接读取文件 | | 需要智能 | 是 | 否 | | 文件就绪要求 | `ai_state: ready` | `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` 都是必需的，且不能为空 — 从 `storage` 操作 `list` 或 `details` 响应中的文件 `version` 字段获取 `versionId`。 - **如果两者均未指定，则默认范围为整个工作区（所有索引文档）。** 这是推荐的默认值 — 除非您特别需要缩小搜索范围，否则请省略范围参数。

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

- `files_attach` — 以逗号分隔的 `nodeId:versionId` 对（最多 20 个，总计 200 MB）。`nodeId` 和 `versionId` 都是必需的，且不能为空。文件是直接读取的，而不是通过 RAG。**只有存储详细信息中具有 `ai.attach: true` 的文件才能被附加** — 使用前请检查。

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

`files_scope`/`folders_scope` 和 `files_attach` 是互斥的 — 同时发送两者将导致错误。

#### 智能与 AI 状态

工作区智能开关（请参阅上面的工作区）控制上传的文档和代码文件是否自动被摄取、总结和索引以用于 RAG。启用智能后，每个文件都有一个 `ai_state` 指示其就绪状态：

| 状态 | 含义 | |-------|---------| | `disabled` | 此文件已禁用 AI 处理 | | `pending` | 排队等待处理 | | `in_progress` | 当前正在被摄取和索引 | | `ready` | 完成 — 可用于文件夹/文件范围查询 | | `failed` | 处理失败 |

只有 `ai_state: ready` 的文件才会被包含在文件夹/文件范围搜索中。通过 `storage` 操作 `details` 并结合 `context_type: "workspace"` 检查文件状态。

#### 可附加性 — `ai.attach` 标志

存储列表/详细信息响应中的文件节点包含一个具有三个字段的 `ai` 对象：

| 字段 | 类型 | 含义 | |-------|------|---------| | `ai.state` | string | AI 索引状态 (`disabled`, `pending`, `inprogress`, `ready`, `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 查询、跨文件搜索、自动总结或持久化知识库。

**何时禁用智能：** 工作区仅用于存储/共享，或者您只需要通过附件分析特定文件。节省积分（摄取成本为每页 10 个积分）。

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

#### 如何措辞问题

**使用文件夹/文件范围 (RAG)：** 编写可能与索引文件中的内容相匹配的问题。AI 搜索范围，检索段落并引用它们。

- 好：“供应商合同中的付款条款是什么？” - 好：“总结第三季度分析报告中的主要发现” - 坏：“告诉我这些文件” — 太模糊，没有要匹配的具体内容 - 坏：“这个工作区里有什么？” — 无法有意义地搜索“所有内容”

**使用文件附件：** 直接 — AI 会读取完整的文件内容。没有检索步骤。

- “详细描述此图像” - “从此发票中提取所有日期和金额” - “将此 CSV 数据转换为汇总表”

**个性：** `personality` 参数控制 AI 回复的语气和长度。在创建聊天或发送消息时传递它：

- `concise` — 简短、简明的回答 - `detailed` — 带有上下文和证据的全面回答（默认）

当您需要快速事实、是/否回答或简要摘要时，请使用 `concise`。当您需要带有支持证据和引用的透彻分析时，请使用 `detailed`（或省略该参数）。个性也可以针对每条后续消息进行覆盖。

**控制问题中的冗长程度：** 您还可以通过问题本身的措辞来引导冗长程度：

- “用一句话概括这份报告的主要结论。” - “仅列出提及 GDPR 合规性的文件名，不做解释” - “给我一个简要的摘要 — 最多 2-3 个要点”

结合 `personality: "concise"` 和直接的问题可以产生最简短的回答，并使用最少的 AI 积分。

#### 聊天参数

使用 `ai` 操作 `chat-create`（带有 `context_type: "workspace"`）或 `ai` 操作 `chat-create`（带有 `context_type: "share"`）创建聊天：

- `type`（必需）— `chat` 或 `chat_with_files` - `query_text`（对于工作区为必需，对于共享为可选）— 初始消息，2-12,768 个字符 - `personality`（可选）— `concise` 或 `detailed`（默认：`detailed`） - `privacy`（可选）— `private` 或 `public`（默认：`public`） - `files_scope`（可选）— `nodeId:versionId,...`（最多 100 个，需要 `chat_with_files` + 智能）。两部分都是必需的且非空。**省略以搜索所有索引文档（推荐的默认值）。** - `folders_scope`（可选）— `nodeId:depth,...`（深度 1-10，最多 100 个子文件夹引用，需要 `chat_with_files` + 智能）。文件夹范围 = 搜索边界，而非文件枚举。**省略以搜索所有索引文档（推荐的默认值）。** - `files_attach`（可选）— `nodeId:versionId,...`（最多 20 个 / 200 MB，两部分都是必需的且非空，与范围参数互斥）

#### 后续消息

发送后续消息时使用 `ai` 动作 `message-send`（上下文类型为 `"workspace"` 或 `"share"`）。聊天类型继承自父级聊天。每次后续消息都可以更新作用域、附件和性格参数。

#### 等待 AI 响应

创建聊天或发送消息后，AI 响应是异步的。消息状态会经历以下过程：`ready` → `in_progress` → `complete`（或 `errored`）。

**建议：** 调用 `ai` 动作 `message-read`（上下文类型为 `"workspace"` 或 `"share"`）并传入返回的 `message_id`。该工具会自动进行轮询（最多 15 次，每次间隔 2 秒，总计约 30 秒）。如果在此时间窗口后响应仍在处理中，请使用 `event` 动作 `activity-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 共享/导出

为可粘贴到外部 AI 工具（ChatGPT、Claude 等）的文件生成临时的 markdown 格式下载 URL。使用 `ai` 动作 `share-generate`（上下文类型为 `"workspace"` 或 `"share"`）。URL 5 分钟后过期。限制：最多 25 个文件，每个文件 50 MB，总计 100 MB。

### 个人资料 ID

组织、工作区和共享都由 19 位数字的个人资料 ID 标识。这些 ID 作为 `workspace_id`、`share_id`、`org_id`、`profile_id` 和 `member_id` 出现在工具参数中。

大多数端点也接受自定义名称作为标识符： | 个人资料类型 | 数字 ID | 自定义名称 | |-------------|-----------|-------------| | Workspace | 19 位 ID | 文件夹名称（例如 `my-project`） | | Share | 19 位 ID | URL 名称（例如 `q4-financials`） | | Organization | 19 位 ID | 域名（例如 `acme`） | | User | 19 位 ID | 电子邮件地址（例如 `[email protected]`） |

### QuickShares

QuickShares 是工作区中单个文件的临时公共下载链接（不适用于共享）。无需身份验证即可访问。从创建开始计算过期时间（默认 10,800 秒 = 3 小时，最大 86,400 秒 = 24 小时）。最大文件大小：1 GB。每个 quickshare 都有一个不透明标识符，用于检索元数据和下载文件。

### 文件预览

上传到 Fast.io 的文件会自动生成预览。当用户打开共享或工作区时，他们会立即看到内容——没有“下载并在其他应用程序中打开”的摩擦。

支持的预览格式：

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

使用 `storage` 动作 `preview-url`（上下文类型为 `"workspace"` 或 `"share"`）生成预览 URL。使用 `storage` 动作 `preview-transform`（上下文类型为 `"workspace"` 或 `"share"`）进行图像调整大小、裁剪和格式转换。

**代理用例：** 您生成的 PDF 报告不仅仅显示为下载链接。用户可以看到它的内联渲染，可以翻页、放大并评论特定部分——所有这些都无需离开浏览器。

### 评论和注释

用户和代理可以直接在文件上留下反馈，使用 `reference` 参数锚定到特定内容：

- **图像评论** -- 锚定到空间区域（标准化的 x/y/width/height 坐标） - **视频评论** -- 锚定到时间戳并选择空间区域 - **音频评论** -- 锚定到时间戳或时间范围 - **PDF 评论** -- 锚定到特定页面，可选择文本片段 - ** threaded 回复** -- 仅限单级线程；对回复的回复会自动扁平化到父级 - **表情符号反应** -- 每个用户每条评论一个反应；添加新反应会替换之前的反应 - **提及标记** -- 使用括号语法内联引用用户和文件：`@[profile:id]`、`@[user:opaqueId:Display Name]`、`@[file:fileId:filename.ext]`。从成员列表、用户详细信息或存储列表中获取 ID。显示名称部分对于个人资料标记是可选的，但对于用户和文件标记建议使用

评论使用 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 个字符，显示文本（去除了 `@[...]` 标签的正文）最大 2,048 个字符。

**删除评论：** `comment` 动作 `delete` 是递归的——删除父级也会删除所有回复。`comment` 动作 `bulk-delete` 不是递归的——对已删除评论的回复会被保留。

**将用户链接到评论：** 预览 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` 以深度链接到特定时间戳的视频评论。在共享中，仅当共享启用了评论时才会打开评论侧边栏。

**代理用例：** 您生成了一个设计模型。用户在图像的特定区域评论“更改标题颜色”。您阅读评论，通过 `reference.region` 坐标准确看到他们所指的区域，并重新生成。

### URL 导入

代理可以直接从 URL 导入文件，而无需先在本地下载它们。Fast.io 的服务器获取文件，处理它，并将其添加到您的工作区或共享。

- 支持任何 HTTP/HTTPS URL - 支持 OAuth 保护的源：**Google Drive、OneDrive、Dropbox** - 文件经过相同的处理管道（如果启用了智能，则进行预览生成、AI 索引、病毒扫描）

使用 `upload` 动作 `web-import` 并附带源 URL、目标个人资料和父节点 ID。使用 `upload` 动作 `web-status` 检查进度，使用 `upload` 动作 `web-list` 列出活动的导入作业。

**代理用例：** 用户说“将此 Google 文档添加到项目中”。您调用 `upload` 动作 `web-import` 并传入 URL。Fast.io 在服务器端下载它，生成预览，对其进行 AI 索引，然后它会出现在工作区中。无需本地 I/O。

### 元数据

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

要点：

- **每个工作区一个模板** -- 每个工作区一次最多支持一个分配的元数据模板。 - **模板类别** -- 法律、金融、商业、医疗、技术、工程、保险、教育、多媒体、人力资源。 - **字段类型** -- 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`）。

### 所有权转移

代理交付价值的主要方式：构建某些东西，然后将其交给人类。这也是当代理计划用完积分且 API 调用开始返回 402 Payment Required 时的建议操作——将组织转移给可以升级到付费计划的人类。

{ "text": "**重要提示：账户类型限制。** 转让/认领工作流（`org` 操作 `transfer-token-create`、`transfer-token-list`、`transfer-token-delete`、`transfer-claim`）仅在代理创建了**代理账户**（通过 `auth` 操作 `signup`）且该代理账户拥有组织时可用。如果代理使用**人工账户**（通过 `auth` 操作 `signin`）登录，则无法使用转让/认领 API。人工拥有的组织必须由人工直接通过 Fast.io 仪表板进行升级。\n\n**流程：**\n\n1. 代理使用 `auth` 操作 `signup` 创建代理账户，使用 `org` 操作 `create` 创建组织，使用 `org` 操作 `create-workspace` 设置工作区，上传文件，配置共享\n2. 代理使用 `org` 操作 `transfer-token-create` 生成转让令牌（有效期为 72 小时）\n3. 代理将认领 URL 发送给人工：`https://go.fast.io/claim?token=<token>`\n4. 人工点击链接并使用其账户认领组织\n\n**何时转让：**\n\n- 组织已准备好供人工使用（工作区已配置，文件已上传，共享已设置）\n- 代理计划配额用尽（402 Payment Required）——进行转让以便人工升级\n- 人工明确要求接管组织\n\n**管理转让令牌：**\n\n- `org` 操作 `transfer-token-list` -- 在创建新令牌之前检查现有的待处理令牌\n- `org` 操作 `transfer-token-delete` -- 如果不再需要转让，则撤销令牌\n- `org` 操作 `transfer-claim` -- 使用令牌认领组织（由接收方的人工代理使用）\n\n**转让后发生的情况：**\n\n- 人工成为组织及其所有工作区的所有者\n- 代理保留管理员访问权限（仍可管理文件和共享）\n- 人工获得免费计划（基于配额，无试用期）\n- 人工可以随时升级到 Pro 或 Business 版本\n\n**代理使用场景：** 用户说“为我的团队设置一个项目工作区。”您创建组织，构建工作区结构，上传模板，配置用于客户端交付物的共享，邀请团队成员——然后转让所有权。人工进入的是一个完全配置好的平台。您保留作为管理员的角色继续管理事务。\n\n**402 Payment Required 使用场景（代理账户）：** 在工作过程中，代理达到了配额限制。调用 `org` 操作 `transfer-token-create`，将认领 URL 发送给人工，并解释他们可以升级以继续使用。代理保留管理员访问权限，并在人工升级后恢复工作。\n\n**402 Payment Required 使用场景（人工账户）：** 代理无法转让组织。相反，请通知用户其组织已用尽配额，他们需要升级其计费计划。指引他们前往 Fast.io 仪表板或使用 `org` 操作 `billing-create` 更新为付费计划。\n\n### 工作流（任务、工作日志、审批、待办事项）\n\n工作区和共享支持可选的工作流层，该层增加了结构化的任务管理、活动日志、审批门和简单的检查清单。工作流功能由开关控制——必须在使用前明确启用。\n\n#### 启用工作流\n\n- **工作区：** 使用 `workspace_id` 执行 `workspace` 操作 `enable-workflow`\n- **共享：** 使用 `share_id` 执行 `share` 操作 `enable-workflow`\n\n通过 `workspace` 操作 `details` 或 `share` 操作 `details` 检查是否启用了工作流——在响应中查找 `workflow: true`。\n\n禁用工作流（`workspace` 操作 `disable-workflow` 或 `share` 操作 `disable-workflow`）将使所有工作流数据无法访问，但会保留该数据。重新启用将恢复访问。\n\n#### 任务列表和任务\n\n任务被组织成列表。每个工作区或共享可以有多个任务列表，每个列表包含单独的任务。\n\n- **任务列表**具有名称和可选描述。使用 `task` 操作 `create-list` 创建，使用 `task` 操作 `list-lists` 列出。\n- **任务**具有标题、描述、状态、优先级、指派对象、依赖项和可选的节点链接。使用 `task` 操作 `create-task` 创建，使用 `task` 操作 `list-tasks` 列出。\n- **状态：** `pending`（待处理）、`in_progress`（进行中）、`complete`（已完成）、`blocked`（已阻塞）\n- **优先级：** 0 = 无，1 = 低，2 = 中，3 = 高，4 = 紧急\n- **指派对象**是个人资料 ID（工作区或共享成员）。使用 `task` 操作 `assign-task` 进行指派或取消指派。\n- **批量操作：** `task` 操作 `bulk-status` 可一次更改最多 100 个任务的状态。\n- **Markdown 输出：** 传递 `format: \"md\"` 以获取易读的 Markdown 格式，而非 JSON。\n\n#### 工作日志\n\n工作日志是仅限追加的按时间顺序排列的活动日志，范围限定于任务、任务列表、存储节点或个人资料。创建后无法编辑或删除条目。\n\n- **条目：** 使用 `worklog` 操作 `append` 追加的常规日志条目。用于进度更新、决策、推理和状态更改。\n- **插入：** 使用 `worklog` 操作 `interject` 创建的优先更正。插入始终是紧急的，并要求其他参与者确认。\n- **确认：** `worklog` 操作 `acknowledge` 将插入标记为已查看。`worklog` 操作 `unacknowledged` 列出仍需确认的插入。\n- **Markdown 输出：** 传递 `format: \"md\"` 以获取易读的输出。\n\n#### 审批\n\n范围限定于任务、存储节点或工作日志条目的正式审批请求。在决策需要明确签署时使用。\n\n- **创建：** 使用 `profile_id`、`description`（1-5000 个字符）、`entity_type`（\"task\"、\"node\" 或 \"worklog_entry\"）执行 `approval` 操作 `create`，以及可选的 `approver_id`（单个个人资料 ID，必须是实体成员）。\n- **解决：** 使用 `resolve_action: \"approve\"` 或 `\"reject\"` 以及可选注释执行 `approval` 操作 `resolve`。只有指定的审批者才能解决。\n- **状态：** `pending`（待处理）、`approved`（已批准）、`rejected`（已拒绝）\n- **Markdown 输出：** 传递 `format: \"md\"` 以获取易读的输出。\n\n#### 待办事项\n\n范围限定于工作区和共享的简单平面检查清单。没有嵌套——只是可以勾选的条目列表。\n\n- **创建：** 使用标题执行 `todo` 操作 `create`。\n- **切换：** `todo` 操作 `toggle` 翻转单个待办事项的完成状态。`todo` 操作 `bulk-toggle` 可一次设置最多 100 个待办事项的完成状态。\n- **更新/删除：** `todo` 操作 `update` 更改标题。`todo` 操作 `delete` 软删除待办事项。\n- **Markdown 输出：** 传递 `format: \"md\"` 以获取易读的输出。\n\n#### 作为代理知识层的笔记\n\n笔记（`type: \"note"`）是存储在工作区存储中的 markdown 文件（见上面的**笔记**）。当与工作流功能结合使用时，笔记将成为知识层：\n\n- **自动 AI 索引：** 当启用工作区智能时，笔记将被摄取并编制索引以供 RAG 使用，就像上传的文件一样。\n- **将任务链接到笔记：** 任务可以引用存储节点，包括笔记。为项目背景、需求或参考资料创建上下文笔记，然后创建链接到这些笔记的任务以获取完整上下文。\n- **用于推理的工作日志：** 使用工作日志条目记录随时间推移的决策、进度和推理。按时间顺序的日志构建了一个与结构化任务列表相辅相成的叙述。\n- **AI 可以搜索所有上下文：** 启用智能后，AI 聊天可以搜索笔记、工作日志、任务描述和上传的文件——根据项目的完整历史提供全面的答案。\n\n**推荐模式：** 为项目上下文和需求创建笔记。为工作阶段创建任务列表。将任务链接到相关笔记。使用工作日志记录进度。为决策请求审批。然后，AI 可以通过搜索所有这些工件来回答诸如“我们为什么选择这种方法？”之类的问题。\n\n### 权限参数值\n\n几个工具使用具有特定允许值的权限参数。调用工具时请使用这些确切的字符串。\n\n#### 组织创建（`org` 操作 `create`）\n\n| 参数 | 允许值 | 默认值 |\n|-----------|----------------|---------|\n| `perm_member_manage` | `Owner only`, `Admin or above`, `Member or above` | `Member or above` |\n| `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` |\n| `background_mode` | `stretched`, `fixed` | `stretched` |\n\n#### 工作区创建（`org` 操作 `create-workspace`）和更新（`workspace` 操作 `update`）\n\n| 参数 | 允许值 | 默认值 |\n|-----------|----------------|---------|\n| `perm_join` | `Only Org Owners`, `Admin or above`, `Member or above` | `Member or above` |\n| `perm_member_manage` | `Admin or above`, `Member or above` | `Member or above` |\n\n#### 共享创建（`share` 操作 `create`）\n\n| 参数 | 允许值 | 默认值 |\n|-----------|----------------|---------|\n| `type` | `send`, `receive`, `exchange` | `exchange` |\n| `storage_mode` | `independent`, `workspace_folder` | `independent` |\n| `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` |\n| `invite` | `owners`, `guests` | `owners` |\n| `notify` | `never`, `notify_on_file_received`, `notify_on_file_sent_or_received` | `never` |\n| `display_type` | `list`, `grid` | `grid` |\n| `intelligence` | `true`, `false` | `false` |\n| `comments_enabled` | `true`, `false` | `true` |\n| `download_enabled` | `true`, `false` | `true` |\n| `guest_chat_enabled` | `true`, `false` | `false` |\n| `workspace_style` | `true`, `false` | `true` |\n| `background_image` | `0`-`128` | `0` |\n\n**共享约束：**" }

- 接收共享和交换共享无法使用 `Anyone with the link`（拥有链接的任何人）访问权限 —— 此选项仅适用于发送共享。 - 密码保护（`password` 参数）仅在 `access_options` 为 `Anyone with the link` 时才允许使用。 - 过期时间（MySQL 格式 `YYYY-MM-DD HH:MM:SS` 的 `expires` 参数）不允许用于 `workspace_folder` 共享。 - `custom_name`、`title` 和 `description` 的字段长度和格式限制记录在下面的 **Profile Field Constraints**（配置文件字段限制）表中。 - 颜色参数（`accent_color`、`background_color1`、`background_color2`）接受 JSON 字符串。 - `create_folder` 在与 `storage_mode='workspace_folder'` 结合使用时，会为共享创建一个新的工作区文件夹。

### Profile Field Constraints

所有配置文件字段均在服务器端进行验证。违反这些限制的请求将被拒绝，并返回 400 错误。

| Entity | Field | API Key | Min | Max | Pattern | Required | Nullable | |--------|-------|---------|-----|-----|---------|----------|----------| | Org | domain | `domain` | 2 | 80 | `^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$` | Yes (create) | No | | Org | name | `name` | 3 | 100 | No control chars | Yes | No | | Org | description | `description` | 10 | 1000 | No control chars | No | Yes | | Workspace | folder_name | `folder_name` | 4 | 80 | `^[\p{L}\p{N}-]+$` (letters, digits, hyphens) | Yes (create) | No | | Workspace | name | `name` | 2 | 100 | No control chars | Yes | No | | Workspace | description | `description` | 10 | 1000 | No control chars | No | Yes | | Share | custom_name | `custom_name` | 4 | 80 | `^[\p{L}\p{N}]+$` (letters, digits only) | Yes (create) | No | | Share | custom_url | `custom_url` | 10 | 100 | — | Yes | Yes | | Share | title | `title` | 2 | 80 | No control chars | Yes | Yes | | Share | description | `description` | 10 | 500 | No control chars | No | Yes |

- **"No control chars"** = 拒绝 Unicode 控制字符（`\p{C}`） - **Org domain**：小写 ASCII 字母数字 + 连字符；不能以连字符开头或结尾 - **Workspace folder_name**：Unicode 字母、数字和连字符 - **Share custom_name**：仅限 Unicode 字母和数字（无连字符或特殊字符） - **Share description** 最大长度为 500（组织/工作区为 1000）

---

## 4. Agent Plan -- Free Tier

代理计划是一个专为 AI 代理设计的免费层级。无需信用卡，无试用期，永不过期。提供足够的资源来构建和展示价值，并在组织转由使用付费计划的人员接管时拥有增长空间。

### Resource Limits

| Resource | Included | |----------|----------| | **Price** | $0 -- no credit card, no trial period, no expiration | | **Storage** | 50 GB | | **Max file size** | 1 GB | | **Monthly credits** | 5,000 (resets every 30 days) | | **Workspaces** | 5 | | **Shares** | 50 | | **Members per workspace** | 5 | | **Share invitations** | 10 per share | | **Account auto-deletion** | Never |

### Credit Costs

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

| Resource | Cost | |----------|------| | Storage | 100 credits/GB | | Bandwidth | 212 credits/GB | | AI chat tokens | 1 credit per 100 tokens | | Document pages ingested | 10 credits/page | | Video ingested | 5 credits/second | | Audio ingested | 0.5 credits/second | | Images ingested | 5 credits/image | | File conversions | 25 credits/conversion |

当积分耗尽时，组织将进入功能受限状态，API 调用将返回 402 Payment Required。组织永远不会被删除。使用 `org` 操作 `limits` 检查当前的积分使用情况和剩余余额。

**When you hit 402 or run low on credits:**

- **Agent account (created via `auth` action `signup`):** 将组织移交给人员。调用 `org` 操作 `transfer-token-create` 生成移交令牌，然后向人员发送认领 URL：`https://go.fast.io/claim?token=<token>`。一旦他们认领了组织，就可以升级到具有无限积分的付费计划。您将保留管理员访问权限，并可以在升级后立即恢复工作。这是预期的工作流程 —— 代理在免费计划上构建，然后移交给准备好付费的人员。 - **Human account (signed in via `auth` action `signin`):** 您无法使用移交/认领 API。告知用户他们需要直接升级组织的计费计划。他们可以通过 Fast.io 仪表板或调用 `org` 操作 `billing-create` 将其订阅更新为付费计划来完成此操作。

### After Transfer -- Human Plan Options

一旦代理将组织移交给人员，该人员将获得一个免费计划（基于积分，无试用期）并可以升级：

| Feature | Agent (Free) | Free (Human) | Pro | Business | |---------|-------------|--------------|-----|----------| | Monthly credits | 5,000 | 5,000 | Unlimited | Unlimited | | Storage | 50 GB | 50 GB | 1 TB | 5 TB | | Max file size | 1 GB | 1 GB | 25 GB | 50 GB | | Workspaces | 5 | 5 | 10 | 1,000 | | Shares | 50 | 50 | 1,000 | 50,000 |

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

---

## 5. Tool Categories

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

### auth

身份验证、登录/注册、双因素身份验证、API 密钥管理和 OAuth 会话管理。这是任何代理交互的起点。

**Actions:** 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-list, api-key-get, api-key-delete, oauth-list, oauth-details, oauth-revoke, oauth-revoke-all

### user

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

**Actions:** me, update, search, 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

### org

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

**Actions:** 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

### workspace

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

**Actions:** list, details, update, delete, archive, unarchive, members, list-shares, import-share, available, check-name, create-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-assign, metadata-template-unassign, metadata-template-resolve, metadata-template-assignments, metadata-get, metadata-set, metadata-delete, metadata-extract, metadata-list-files, metadata-list-templates-in-use, metadata-versions, enable-workflow, disable-workflow, enable-import, disable-import

### share

共享 CRUD、公开详细信息、归档、密码身份验证、资源管理、共享名称可用性检查以及工作流切换（启用/禁用任务、工作日志、审批和待办事项）。

**Actions:** list, details, create, update, delete, public-details, archive, unarchive, password-auth, members, available, check-name, quickshare-create, enable-workflow, disable-workflow

### storage

工作区和共享内的文件和文件夹操作。列出、列出所有文件夹中最近修改的文件、创建文件夹、移动、复制、删除、重命名、清除、还原、搜索、从上传中添加文件、添加共享链接、传输节点、管理回收站、版本操作、文件锁定以及预览/转换 URL 生成。需要 `context_type` 参数（`workspace` 或 `share`）。

**Actions:** 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 / 大对象引用形式上传分块、完成、检查状态、取消）、从外部 URL 进行 Web 导入、上传限制和文件扩展名限制以及会话管理。

**Actions:** create-session, chunk, finalize, status, cancel, list-sessions, cancel-all, chunk-status, chunk-delete, stage-blob, text-file, web-import, web-list, web-cancel, web-status, limits, extensions

### download

为工作区文件、共享文件和快速共享链接生成下载 URL 和 ZIP 归档 URL。MCP 工具无法流式传输二进制数据——这些操作返回的 URL 可以在浏览器中打开或传递给下载实用程序。`file-url` 和 `zip-url` 操作需要 `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 令牌使用情况以及自动生成标题。需要 `context_type` 参数（`workspace` 或 `share`）。

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

### comment

注释的作用域为 `{entity_type}/{parent_id}/{node_id}`，其中 entity_type 为 `workspace` 或 `share`，parent_id 为 19 位个人资料 ID，node_id 为存储节点的不透明 ID。列出文件上的注释（按节点和整个个人资料范围，支持排序/限制/偏移/过滤参数），添加带可选引用锚点（图像区域、视频/音频时间戳、带文本选择的 PDF 页面）的注释，单级线程回复，递归单次删除，非递归批量删除，获取注释详情以及表情符号反应（每位用户每个注释一个）。注释使用 JSON 请求正文。

**操作：** list, list-all, add, delete, bulk-delete, details, reaction-add, reaction-remove

### event

通过类别、子类别和事件名称进行丰富的过滤，搜索审计/事件日志（有关完整分类法，请参阅第 7 节中的**事件过滤参考**）。获取 AI 驱动的活动摘要，检索单个事件的完整详细信息，列出最近的活动，以及对活动更改进行长轮询。

**操作：** search, summarize, details, activity-list, activity-poll

### member

组织、工作区和共享的成员管理。添加、删除、更新角色、转让所有权、离开、加入和通过邀请加入。需要 `entity_type` 参数（`workspace` 或 `share`）。

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

### invitation

组织、工作区和共享的邀请管理。列出邀请，按状态列出，更新和删除。需要 `entity_type` 参数（`workspace` 或 `share`）。

**操作：** list, list-by-state, update, delete

### asset

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

**操作：** upload, delete, types, list, read

### task

工作区和共享的任务列表和任务管理。创建和管理任务列表，然后在其中创建具有状态、优先级、受托人和依赖关系的任务。支持批量状态更改和 markdown 输出。需要在目标实体上启用工作流。

**操作：** 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

### worklog

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

**操作：** append, list, interject, details, acknowledge, unacknowledged

### approval

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

**操作：** list, create, details, resolve

### todo

作用于工作区和共享的简单平面检查清单。创建、更新、删除和切换单个待办事项或批量的完成状态。不支持嵌套。需要在目标实体上启用工作流。

**操作：** list, create, details, update, delete, toggle, bulk-toggle

### import

云导入操作，用于将文件从外部云存储提供商（Google Drive、Dropbox、Box、OneDrive for Business）同步到工作区存储。管理提供商身份（服务帐户），发现共享文件夹，创建和监控具有定期同步的导入源，并处理双向同步的写回操作。需要在工作区上启用云导入（`workspace` 操作 `enable-import`）。

**操作：** list-identities, provision-identity, identity-details, revoke-identity, list-sources, discover, create-source, source-details, update-source, delete-source, disconnect, refresh, list-jobs, job-details, cancel-job, list-writebacks, writeback-details, push-writeback, retry-writeback, resolve-conflict, cancel-writeback

---

## 6. 常见工作流程

### 1. 创建帐户并登录

请参阅第 2 节中的**选择正确的方法**，以确定哪种选项适合您的场景。

**选项 1 -- 自主代理（新帐户）：**

1. （可选）使用所需的 `email` 调用 `auth` 操作 `email-check` 以验证可用性。 2. `auth` 操作 `signup`，包含 `first_name`、`last_name`、`email` 和 `password` —— 注册为代理帐户（自动发送 agent=true）并立即登录。 3. `auth` 操作 `email-verify`，包含 `email` —— 发送验证码。然后 `auth` 操作 `email-verify`，包含 `email` 和 `email_token` —— 验证代码。在使用大多数端点之前是必需的。 4. `org` 操作 `create` 以在代理计划上创建新组织，或 `org` 操作 `list` 以检查现有组织。

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

1. 人类在 `https://go.fast.io/settings/api-keys` 创建 API 密钥并将其提供给代理。 2. 使用 API 密钥调用 `auth` 操作 `set-api-key`。密钥将根据 API 进行验证并存储在会话中 —— 所有后续工具调用都将自动进行身份验证。无需创建帐户。 3. `org` 操作 `list` 和 `org` 操作 `discover-external` 以发现所有可用的组织（请参阅**组织发现**）。

**选项 3 -- 代理受邀加入人类组织：**

1. 使用 `auth` 操作 `signup` 创建代理帐户（与选项 1 相同）。 2. 让人类通过 `org` 操作 `invite-member` 或 `member` 操作 `add`（包含 `entity_type: "workspace"`）邀请您。 3. 使用 `user` 操作 `accept-all-invitations` 接受邀请。 4. `org` 操作 `list` 和 `org` 操作 `discover-external` 以发现所有可用的组织（请参阅**组织发现**）。如果人类仅邀请您加入工作区（而非组织），它将仅通过 `discover-external` 显示。

**返回用户：**

1. 使用 `email` 和 `password` 调用 `auth` 操作 `signin`。 2. 如果 `two_factor_required: true`，请使用 2FA `code` 调用 `auth` 操作 `2fa-verify`。 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`，包含 `context_type: "workspace"`、`context_id`（工作区 ID）和 `node_id: "root"` —— 浏览根文件夹。记下文件和子文件夹的 `node_id` 值。 4. `storage` 操作 `details`，包含 `context_type: "workspace"`、`context_id` 和 `node_id` —— 获取特定文件的完整详细信息（名称、大小、类型、版本）。 5. `download` 操作 `file-url`，包含 `context_type: "workspace"`、`context_id` 和 `node_id` —— 获取带有嵌入式令牌的临时下载 URL。响应还包含一个 `resource_uri`（例如 `download://workspace/{id}/{node_id}`），MCP 客户端可以使用它直接读取文件内容。将下载 URL 返回给用户，或使用资源 URI 通过 MCP 读取文件。

### 3. 将文件上传到工作区

**文本文件（推荐）：** 使用 `upload` 操作 `text-file`，包含 `profile_type: "workspace"`、`profile_id`、`parent_node_id`、`filename` 和 `content`（纯文本）。此单个操作创建会话、上传、完成并轮询直到存储 —— 成功时返回 `new_file_id`。将其用于代码、markdown、CSV、JSON、配置文件和任何其他文本内容。

**二进制或大文件（分块流程）：**

1. `upload` 操作 `create-session`，参数包括 `profile_type: "workspace"`、`profile_id`（workspace ID）、`parent_node_id`（目标文件夹或 `"root"`）、`filename` 和以字节为单位的 `filesize`。返回 `upload_id`、`recommended_mcp_chunk_bytes`（默认 24576）和 `total_chunks` —— 使用这些信息来分割文件。 2. `upload` 操作 `chunk`，参数包括 `upload_id`、`chunk_number`（从 1 开始索引）和块数据。**将文件分割为 `recommended_mcp_chunk_bytes` 大小的块**（24 KB 二进制 / ~32 KB base64）—— 即使是小文件也是如此。传递数据有三种选项（仅提供其中一种）： - **`content`** —— 用于文本（字符串、代码、JSON 等）。请勿对文本使用 `data`。 - **`data`** —— base64 编码的二进制数据（**每次调用 ≤32 KB**）。通过 MCP 工具调用进行二进制上传的最简单方法。分割文件并将每一部分作为单独的块发送。 - **`blob_ref`** —— 来自 `upload` 操作 `stage-blob` 或 `POST /blob` 的 blob ID。适用于预暂存数据或在非 MCP 客户端使用 HTTP blob 端点的情况。Blob 会在 5 分钟后过期，并在使用时被消耗（删除）。 对每个块重复此操作。在发送下一个块之前，等待每个块返回成功。 3. `upload` 操作 `finalize`，参数包括 `upload_id` —— 触发文件组装并轮询直到存储完成。返回最终会话状态，成功时状态为 `"stored"` 或 `"complete"`（包括 `new_file_id`），组装失败则抛出错误。文件会自动添加到步骤 1 中指定的目标 workspace 和文件夹 —— 无需单独调用 add-file。

**注意：** 仅当您希望将上传链接到与会话创建期间指定的位置*不同*的位置时，才需要 `storage` 操作 `add-file`。

### 4. 从 URL 导入文件

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

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

### 5. 向客户交付文件

创建一个具有品牌效应的专业数据室，用于出站文件交付。这取代了原始下载链接、电子邮件附件和 S3 预签名 URL。

1. 将文件上传到 workspace（参见工作流 3 或 4）。 2. `share` 操作 `create`，参数包括 `workspace_id`、`name` 和 `type: "send"` —— 创建一个 Send 分享。返回 `share_id`。 3. `share` 操作 `update`，参数包括 `share_id` 以配置： - `password` —— 要求密码才能访问 - `expiry_date` —— 在设定时间后自动使分享过期 - `access_level` —— 仅限成员、组织成员、注册用户或公开 - `allow_downloads` —— 启用或禁用文件下载 - 品牌选项：`background_color`、`accent_color`、`gradient_color` - `post_download_message` 和 `post_download_url` —— 下载后显示消息 4. `member` 操作 `add`，参数包括 `entity_type: "share"`、`entity_id`（share ID）和 `email_or_user_id` —— 添加收件人。如果他们没有 Fast.io 账户，则会发送邀请。 5. `asset` 操作 `upload`，参数包括 `entity_type: "share"` 和 `entity_id`（share ID）以添加徽标或背景图片以进行品牌化。 6. 收件人看到一个带有即时文件预览的品牌化页面，而不是原始下载链接。

### 6. 从用户收集文档

创建一个 Receive 分享，以便人类可以直接将文件上传给您 —— 无需电子邮件附件，无需云盘链接。

1. `share` 操作 `create`，参数包括 `workspace_id`、`name`（例如，“在此处上传您的税务文件”）和 `type: "receive"`。返回 `share_id`。 2. `share` 操作 `update`，参数包括 `share_id` 以根据需要设置访问级别、过期和品牌化。 3. `member` 操作 `add`，参数包括 `entity_type: "share"`、`entity_id`（share ID）和 `email_or_user_id` 以邀请上传者。 4. 上传者通过一个简洁的品牌化界面上传文件。 5. 文件会出现在您的 workspace 中。如果启用了智能功能，它们将自动由 AI 建立索引。 6. 使用 `ai` 操作 `chat-create`，参数包括作用域于 receive 分享文件夹的 `context_type: "share"`，以询问诸如“所有必需的表格是否都存在？”之类的问题。

### 7. 构建知识库

创建一个智能 workspace，自动为 RAG 查询建立所有内容的索引。

1. `org` 操作 `create-workspace`，参数包括 `org_id` 和 `name`。默认启用智能功能。 2. 上传参考文档（参见工作流 3 或 4）。AI 会在上传时自动索引和汇总所有内容。 3. `ai` 操作 `chat-create`，参数包括 `context_type: "workspace"`、`context_id`（workspace ID）、`query_text`、`type: "chat_with_files"` 和 `folders_scope`（逗号分隔的 `nodeId:depth` 对）以跨文件夹或整个 workspace 进行查询。 4. `ai` 操作 `message-read`，参数包括 `context_type: "workspace"`、`context_id`、`chat_id` 和 `message_id` —— 轮询直到 AI 响应完成。返回指向特定文件、页面和片段的 `response_text` 和 `citations`。 5. `storage` 操作 `search`，参数包括 `context_type: "workspace"`、`context_id` 和查询字符串以进行语义搜索 —— 根据含义而非仅根据文件名查找文件。 6. 答案包括对特定页面和文件的引用。将这些连同来源引用一起传回给用户。

### 8. 询问 AI 关于文件的问题

两种模式，取决于 workspace 上是否启用了智能功能。

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

1. `ai` 操作 `chat-create`，参数包括 `context_type: "workspace"`、`context_id`（workspace 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`，参数包括 `context_type: "workspace"`、`context_id`、`chat_id` 和 `message_id` —— 最多轮询 API 15 次（2 秒间隔，约 30 秒），直到 AI 响应完成。返回 `response_text` 和 `citations`。**提示：** 如果内置轮询窗口过期，请使用 `event` 操作 `activity-poll` 并附带 workspace ID，而不是循环调用 `message-read` —— 请参阅上面的活动轮询部分。 3. `ai` 操作 `message-send`，参数包括 `context_type: "workspace"`、`context_id`、`chat_id` 和 `query_text` 以进行后续问题。返回新的 `message_id`。 4. `ai` 操作 `message-read`，再次使用新的 `message_id` 以获取后续响应。

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

1. `ai` 操作 `chat-create`，参数包括 `context_type: "workspace"`、`context_id`、`query_text`、`type: "chat_with_files"` 和 `files_attach` 指向特定文件（逗号分隔的 `nodeId:versionId`，最多 20 个文件 / 200 MB）。文件必须具有 `ai.attach: true`（通过 `storage` 操作 `details` 检查）。AI 直接读取附加文件，无需持久索引。 2. `ai` 操作 `message-read` 以获取响应。不消耗摄取积分 —— 仅消耗聊天令牌积分。

### 9. 为人类设置项目

完整的代理到人类交接工作流。这是代理在 Fast.io 上提供价值的主要方式。

1. `org` 操作 `create` —— 在代理计费计划上创建一个新的组织。代理成为所有者。会自动创建一个代理计划订阅（免费，50 GB，5,000 积分/月）。 2. `org` 操作 `create-workspace`，参数包括 `org_id` 和 `name` —— 为每个项目区域创建 workspace。 3. `storage` 操作 `create-folder`，参数包括 `context_type: "workspace"` 以构建文件夹结构（模板、交付物、参考文档等）。 4. 将文件上传到每个 workspace（参见工作流 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. 人类点击链接并声明组织。他们成为所有者，代理保留管理员访问权限。人类获得免费计划。

### 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 令牌和计费周期信息。

### 11. 管理 Workspace 中的任务

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

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

### 12. 完整代理工作流（任务 + 工作日志 + 审批）

完整的代理工作流模式：规划工作、执行并记录日志、通过审批进行决策关卡。

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

### 13. 云导入（外部存储同步）

将文件从 Google Drive、Dropbox、Box 或 OneDrive Business 导入到工作区。文件会定期同步并保持可供 AI 查询。

**设置：**

1. `workspace` action `enable-import` 搭配 `workspace_id` -- 在工作区上启用云导入功能。 2. `import` action `provision-identity` 搭配 `workspace_id` 和 `provider`（`google_drive`、`box`、`onedrive_business`、`dropbox` 之一） -- 配置服务帐户。返回 `identity_email` 和用户 `instructions`。 3. 告知用户在其云存储中与 `identity_email` 共享文件夹。等待确认。 4. `import` action `discover` 搭配 `workspace_id` 和 `identity_id` -- 列出与代理共享的所有文件夹。返回包含 `remote_path`、`name`、`size` 和 `file_count` 的 `shared_folders`。 5. `import` action `create-source` 搭配 `workspace_id`、`identity_id`、`remote_path`（来自 discover），以及可选的 `remote_name`、`sync_interval`（默认 3600 秒）和 `access_mode`（默认 `read_only`，或双向同步则为 `read_write`）。返回新的导入源并触发初始同步作业。 6. `import` action `job-details` 搭配 `source_id` 和 `job_id` -- 轮询进度。`progress` 字段显示百分比、当前文件、速度和预计时间。 7. `storage` action `list` 搭配 `context_type: "workspace"` -- 导入的文件会出现在“Imports/”文件夹下。节点在响应中包含 `is_imported: true` 和 `import_metadata`。

**持续管理：**

- `import` action `list-sources` -- 查看工作区的所有活动导入。 - `import` action `refresh` 搭配 `source_id` -- 立即触发同步，而不是等待下一个计划的间隔。 - `import` action `update-source` 搭配 `source_id` -- 更改 `sync_interval`、`access_mode`，或通过 `status: "paused"` / `status: "synced"` 暂停/恢复。 - `import` action `list-jobs` 搭配 `source_id` -- 查看同步历史。

**写回（仅限 read_write 源）：**

当 `access_mode` 为 `read_write` 时，在工作区中修改的文件会自动排队以写回到远程提供商。

1. `import` action `list-writebacks` 搭配 `source_id` -- 查看待处理和已完成的写回作业。 2. `import` action `push-writeback` 搭配 `source_id` 和 `node_id` -- 立即强制推送特定文件。 3. 如果发生冲突（远程文件自上次同步以来已更改），写回将进入 `conflict` 状态。 4. `import` action `resolve-conflict` 搭配 `source_id`、`writeback_id` 和 `conflict_resolution`：`keep_local`（推送本地版本）或 `keep_remote`（拉取远程版本）。 5. `import` action `retry-writeback` 搭配 `source_id` 和 `writeback_id` -- 重试失败的写回。

**断开连接：**

- `import` action `disconnect` 搭配 `source_id` 和 `disconnect_action`：`keep`（导入的文件变为常规工作区文件）或 `delete`（导入的文件移至回收站）。

**特定于提供商的说明：**

| Provider | Sharing method | Acceptance | |----------|---------------|------------| | Google Drive | Share folder with agent email | Instant (no acceptance needed) | | Box | Invite agent email to folder | Instant (no acceptance needed) | | OneDrive Business | Grant app access to SharePoint site/library | Requires admin | | Dropbox | Invite agent email to folder | Requires acceptance via API |

---

## 7. 关键模式和陷阱

### ID 格式

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

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

### 分页

根据端点的不同，使用两种分页样式：

**基于游标（storage 列表端点）：** `sort_by`、`sort_dir`、`page_size` 和 `cursor`。当有更多结果可用时，响应包含 `next_cursor` 值。在下次调用中传递此游标以检索下一页。页面大小通常为 100、250 或 500。用于：`storage` action `list`（搭配 `context_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`（搭配 `context_type: "workspace"` 或 `"share"`）和 `download` action `quickshare-details` 调用 `/requestread/` 端点以获取临时令牌，然后构建完整的下载 URL。代理应将这些 URL 返回给用户或将其传递给下载实用程序。

`download` actions `zip-url`（workspace 和 share）返回 URL 以及所需的 `Authorization` 标头值。

### 二进制上传

将二进制数据作为块上传的三种方法，每种都适用于不同的情况。

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

**1. `data` 参数（base64）—— 对 MCP 代理而言最简单**

在 `upload` action `chunk` 的 `data` 参数中直接传递 base64 编码的二进制。无需额外步骤。适用于任何 MCP 客户端。由于 base64 编码，会增加约 33% 的大小开销。**将文件拆分为 ≤24 KB 二进制（≤32 KB base64）的块**，以保持在 MCP 客户端参数限制内。

**2. `stage-blob` action —— 基于 MCP 工具的 blob 预存**

使用 `upload` action `stage-blob` 并搭配 `data`（base64）将二进制数据预存为 blob。返回一个 `blob_id`，您可以将其作为 `blob_ref` 在块调用中传递。当您希望将预存与上传分离，或提前准备多个块时，这很有用。同样适用 **每次调用 32 KB base64 限制**—— 一次预存一个块大小的片段。

**流程：** 1. `upload` action `stage-blob` 搭配 `data`（base64 编码的二进制，≤32 KB）。返回 `{ "blob_id": "<uuid>", "size": <bytes> }`。 2. `upload` action `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 约束（适用于两种暂存方式）：** - Blob 会在 **5 分钟**后过期。请暂存后及时使用。 - 每个 Blob 在首次使用时即被消耗（删除） — 无法重复使用。 - 最大 Blob 大小：**100 MB**。 - 使用 SSE 传输的客户端必须在 `/blob` URL 中添加 `?transport=sse`。

### 事件过滤参考

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

#### 事件类别

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

#### 事件子类别

| Subcategory | 涵盖内容 | |---|--| | `storage` | 文件/文件夹添加、移动、复制、删除、恢复、下载 | | `comments` | 评论已创建、更新、删除、提及、回复、表情反应 | | `members` | 成员已添加到/移出自组织、工作区或分享 | | `lifecycle` | 配置文件已创建、更新、删除、归档 | | `settings` | 配置和偏好设置更改 | | `security` | 安全相关事件（2FA、密码） | | `authentication` | 登录、SSO、会话事件 | | `ai` | AI 处理、聊天、索引 | | `invitations` | 邀请管理 | | `billing` | 订阅和支付事件 | | `assets` | 头像/资源更新 | | `upload` | 上传会话管理 | | `transfer` | 跨配置文件文件传输 | | `import_export` | 数据导入/导出操作 | | `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`（带有 `context_type: "workspace"` 或 `"share"`）实现了内置轮询（最多 15 次尝试，间隔 2 秒）。如果在该时间窗口后响应仍在处理，请使用带有工作区或分享 ID 的 `event` 动作 `activity-poll`，而不是在循环中调用读取动作：

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）和设置为 `server_date` 值的 `lastactivity`。 3. 服务器保持连接。当发生更改（或等待期到期）时，它返回活动键。 4. 检查这些键以确定发生了什么变化，然后获取相关的详细信息（例如 `ai` 动作 `message-read`，`storage` 动作 `list`）。 5. 使用轮询响应中的新 `lastactivity` 值（或最新的 `server_date`）进行下一次轮询调用。根据需要重复。

### 回收站、删除和清除

- `storage` 动作 `delete`（带有 `context_type: "workspace"` 或 `"share"`）将项目移至回收站。它们是可以恢复的。 - `storage` 动作 `restore` 从回收站恢复项目。 - `storage` 动作 `purge` 从回收站中永久且不可逆地删除项目。

在调用清除操作之前，请务必与用户确认。

### 节点类型

存储节点可以是文件、文件夹、笔记或链接。类型在存储详细信息响应中指示。笔记是使用 `workspace` 动作 `create-note` 创建并使用 `workspace` 动作 `update-note` 更新的 markdown 文件。链接是使用 `storage` 动作 `add-link` 创建的分享引用节点。

### 错误模式

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

### 会话状态

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

### 面向用户的 URL

MCP 工具通过 API 管理数据，但人类通过 Web 浏览器访问 Fast.io。**始终使用工具响应中的 `web_url` 字段** — 它是资源即用型、可点击的 URL。每当您创建或引用工作区、分享、文件、笔记或传输时，请将其包含在您的响应中。人类无法直接看到 API 响应 — 您提供的 URL 是他们获取内容的途径。仅当 `web_url` 缺失时（例如，share-context 存储操作），才回退到下面的 URL 模式：

> **自动生成的 `web_url` 字段。** 所有返回实体的工具响应都包含一个 `web_url` 字段 —— 一个可立即使用的、对人类友好的资源 URL。**切勿手动构建 URL —— 始终使用工具响应中的 `web_url` 字段。** 它出现在以下位置：org list/details/create/update/public-details/discover-*、org list-workspaces/list-shares、workspace list/details/update/available/list-shares、share list/details/create/update/public-details/available、storage list/details/search/trash-list/copy/move/rename/restore/add-file/create-folder/version-list/version-restore/preview-url/preview-transform、quickshare create/get/list、upload text-file/finalize、download file-url/quickshare-details、AI chat-create/chat-details/chat-list、transfer-token create/list 以及 notes create/update。仅当 `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}` | | 快速共享 | `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` 字段 —— 这是一个建议的后续操作的简短数组，使用确切的工具和操作名称。请使用这些提示来指导您的工作流，而不是猜测下一步该做什么。示例：

```json { "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`** 出现在破坏性、不可逆或潜在有问题的操作上。继续操作前请务必阅读警告 —— 它们会标记永久性后果或重要警告。带有 `_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 (token expiry)、download zip-url (auth required)、upload stage-blob (5-min expiry)、org transfer-token-create。

**`_recovery`** 提示出现在错误响应中（当 `isError: true` 时）。它们基于 HTTP 状态码和错误消息模式匹配提供恢复操作。错误消息还包含操作上下文（例如，“during: org create”），以帮助确定失败的操作。

| HTTP 状态 | 恢复方法 | |-------------|----------| | 400 | 检查必填参数和 ID 格式 | | 401 | 重新身份验证：auth 操作 signin 或 pkce-login | | 402 | 配额耗尽 —— 检查余额：org 操作 limits | | 403 | 权限被拒绝 —— 检查角色：org 操作 details | | 404 | 资源未找到 —— 验证 ID，使用 list 操作发现有效 ID | | 409 | 冲突 —— 资源可能已存在 | | 413 | 请求过大 —— 减小文件/分块大小 | | 422 | 验证错误 —— 检查字段格式和约束 | | 429 | 速率受限 —— 等待 2-4 秒并使用指数退避重试 | | 500/503 | 服务器错误 —— 2-5 秒后重试 |

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

**`ai_capabilities`** 包含在工作区详细信息响应中。它根据工作区智能设置显示可用的 AI 模式： - 智能 ON：`files_scope`、`folders_scope`、`files_attach`（包含索引文档搜索的完整 RAG） - 智能 OFF：仅 `files_attach`（最多 20 个文件，200 MB，无 RAG 索引）

**`_ai_state_legend`** 包含在文件具有 AI 索引状态的存储列表和搜索响应中。状态包括：`ready`（已索引，可查询）、`pending`（排队中）、`inprogress`（索引中）、`disabled`（智能已关闭）、`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`（下载、事件）和 `openWorldHint`（org、user、workspace、share、storage） —— 以帮助客户端在无需文档的情况下了解工具行为。

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

### 未身份验证的工具

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

---

## 8. 完整工具参考

所有 19 个工具及其按功能区域组织的操作。每个条目显示操作名称及其描述。工作流工具（task、worklog、approval、todo）需要目标工作区或共享上启用工作流。

### auth

**signin** -- 使用电子邮件和密码登录 Fast.io。返回 JWT 身份验证令牌。如果账户启用了 2FA，则在调用 2fa-verify 之前，令牌将具有有限的范围。令牌会自动存储在会话中。

**set-api-key** -- 使用 Fast.io API 密钥进行身份验证。API 密钥是 JWT 令牌的 1:1 替代品——它们作为 Bearer 令牌使用，拥有与账户所有者相同的权限。密钥会通过 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，则会发送一个新代码。如果提供了该参数，则会验证代码并将电子邮件标记为已验证。

**status** -- 检查本地会话状态。不进行 API 调用。返回用户是否已通过身份验证，如果是，则返回其 user_id、email、token expiry、scopes（原始字符串）、scopes_detail（包含实体名称、域和父级层次结构的详细数组——如果尚未获取则为 null）以及 agent_name（如果已设置）。

**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 密钥。完整的密钥值仅在创建时返回一次——请安全存储。

**api-key-list** -- 列出已认证用户的所有 API 密钥。密钥值已掩码（仅可见最后 4 个字符）。

**api-key-get** -- 获取特定 API 密钥的详细信息。密钥值已掩码。

**api-key-delete** -- 撤销（删除）API 密钥。此操作无法撤消。

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

**2fa-enable** -- 在指定通道上启用双重身份验证。对于 TOTP，返回用于 QR 码显示的绑定 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 会话。可选择排除当前会话，以启用“在其他地方注销”功能。

### user

**me** -- 获取当前已认证用户的个人资料详细信息。

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

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

**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** -- 列出所有用户资产。

### 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** -- 在“代理”计费计划上创建一个新组织。已认证的用户成为所有者。会自动创建一个存储实例和代理计划订阅（免费，50 GB，5,000 信用/月）。返回新组织和试用状态。

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

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

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

**create-workspace** -- 在组织内创建一个新工作区。返回 `web_url`。根据组织计费计划检查工作区功能可用性和创建限制。创建用户成为工作区所有者。

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

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

**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 小时）。将领取 URL `https://go.fast.io/claim?token=<token>` 发送给某人。在移交组织或在代理套餐上遇到 402 Payment Required 时使用。需要所有者角色。

**transfer-token-list** -- 列出组织的所有活动转移令牌。每个令牌包含 `web_url`（领取 URL）。需要所有者角色。

**transfer-token-delete** -- 删除（撤销）一个待处理的转移令牌。需要所有者角色。

**transfer-claim** -- 使用转移令牌认领一个组织。经过身份验证的用户将成为新的所有者，而先前的所有者将被降级为管理员。

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

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

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

**join** -- 通过邀请或授权域自动加入加入组织。可选择提供邀请密钥和操作（accept/decline）。

**asset-upload** -- 上传组织资产（如 logo、横幅）。提供纯文本内容或 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`。用户只能通过工作区成员身份访问的组织，而不是作为直接的组织成员。通常发生在某人邀请代理加入工作区而未邀请其加入组织时。请参阅组织部分中的“内部组织与外部组织”。

### workspace

**list** -- 列出用户在所有组织中拥有访问权限的所有工作区。每个工作区包含 `web_url`。

**details** -- 获取特定工作区的详细信息。返回 `web_url`。

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

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

**archive** -- 归档工作区（阻止修改，保留数据）。需要管理员+。

**unarchive** -- 将已归档的工作区恢复为活动状态。需要管理员+。

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

**list-shares** -- 列出工作区内的所有共享，可选择按归档状态筛选。每个共享包含 `web_url`。

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

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

**check-name** -- 检查工作区文件夹名称是否可用。

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

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

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

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

**quickshares-list** -- 列出工作区中所有活动的快速共享。每个快速共享包含 `web_url`。

**metadata-template-create** -- 在工作区中创建新的元数据模板。需要名称、描述、类别（legal, financial, business, medical, technical, engineering, insurance, educational, hr）和字段（字段定义的 JSON 编码数组）。每个字段具有名称、描述、类型（string, int, float, bool, json, url, datetime）和可选约束（min, max, default, fixed_list, can_be_null）。

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

**metadata-template-list** -- 列出元数据模板。可选的 template_filter：enabled、disabled、custom（非系统）或 system。未指定筛选器时返回所有未删除的模板。

**metadata-template-details** -- 获取元数据模板的完整详细信息，包括所有字段定义。需要 template_id。

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

**metadata-template-clone** -- 克隆元数据模板并可选择修改。基于现有模板创建新模板。参数与 metadata-template-update 相同。需要 template_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** -- 从文件中删除元数据。提供 keys（键名的 JSON 数组）以删除特定条目，或省略以删除所有元数据。仅适用于文件和笔记，不适用于文件夹。需要 node_id。

**metadata-extract** -- 触发 AI 驱动的文件元数据提取。AI 分析文件内容并根据模板填充元数据字段。提取的值标记为 is_auto: true。消耗 AI 信用。可选 template_id（默认为工作区模板）。需要 node_id。

**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** -- 在工作区上启用云导入功能。在使用 `import` 工具连接外部云存储提供商之前必须调用。

**disable-import** -- 在工作区上禁用云导入功能。现有的导入源停止同步。导入数据将被保留，但在重新启用之前无法访问。

### 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 链接。

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

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

### storage

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

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

**recent** -- 列出所有目录中最近修改的文件和文件夹，按更新时间降序排列。与 `list` 不同（后者仅限单个文件夹），这将返回整个存储树中的节点。支持可选的 `type` 筛选器（`file`、`folder`、`link`、`note`）、`page_size`（100、250 或 500）和用于分页的 `cursor`。对于 workspace 文件夹共享，结果会自动筛选为该共享的子树。

**details** -- 获取特定文件或文件夹的完整详情。返回 `web_url`（指向文件预览或文件夹的 Web UI 友好链接，仅限 workspace）。

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

**trash-list** -- 列出当前在回收站中的项目。每个项目包含 `web_url`（仅限 workspace）。

**create-folder** -- 创建一个新文件夹。返回 `web_url`（仅限 workspace）。

**copy** -- 复制文件/文件夹。通过 `node_id` 进行单个复制（workspace 或 share）。通过 `node_ids` 数组进行批量复制（仅限 workspace）。返回新副本的 `web_url`（仅限 workspace）。

**move** -- 移动文件/文件夹。通过 `node_id` 进行单个移动（workspace 或 share）。通过 `node_ids` 数组进行批量移动（仅限 workspace）。返回 `web_url`（仅限 workspace）。

**delete** -- 通过将文件/文件夹移至回收站来删除它们。通过 `node_id` 进行单个删除（workspace 或 share）。通过 `node_ids` 数组进行批量删除（仅限 workspace）。

**rename** -- 重命名文件或文件夹。返回 `web_url`（仅限 workspace）。

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

**restore** -- 从回收站还原文件/文件夹。通过 `node_id` 进行单个还原（workspace 或 share）。通过 `node_ids` 数组进行批量还原（仅限 workspace）。返回已还原节点的 `web_url`（仅限 workspace）。

**add-file** -- 将已完成的上传链接到存储位置。返回 `web_url`（仅限 workspace）。

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

**transfer** -- 将节点复制到另一个 workspace 或共享存储实例。

**version-list** -- 列出文件的版本历史。返回文件的 `web_url`（仅限 workspace）。

**version-restore** -- 将文件还原到以前的版本。返回文件的 `web_url`（仅限 workspace）。

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

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

**lock-release** -- 释放文件的独占锁定。

**preview-url** -- 获取文件的预授权预览 URL（缩略图、PDF、图像、视频、音频、电子表格）。需要 `preview_type` 参数。返回 `preview_url`（即用型 URL）和 `web_url`（指向 Web UI 中文件的友好链接，仅限 workspace）。

**preview-transform** -- 请求文件转换（图像调整大小、裁剪、格式转换）并获取结果的下载 URL。需要 `transform_name` 参数。返回 `transform_url`（即用型 URL）和 `web_url`（指向 Web UI 中文件的友好链接，仅限 workspace）。

### upload

**create-session** -- 为文件创建分块上传会话。

**chunk** -- 上传单个分块。使用 `content` 处理文本/字符串，使用 `data` 处理 base64 编码的二进制数据，或使用 `blob_ref` 处理通过 `stage-blob` 操作或 `POST /blob` 暂存的二进制数据。请准确提供其中一种。

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

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

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

**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** -- 单步上传文本文件。创建上传会话、上传内容、完成并轮询直到存储完毕。返回新文件 ID。用于基于文本的文件（代码、markdown、CSV、JSON、配置），替代多步分块流程。

**web-import** -- 从外部 URL 将文件导入到 workspace 或 share。

**web-list** -- 列出用户的 Web 上传任务，支持可选筛选。

**web-cancel** -- 取消活动的 Web 上传任务。

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

**limits** -- 获取用户计划的上传大小和分块限制。

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

### download

**file-url** -- 获取文件的下载令牌和 URL。可选择指定版本。需要 `context_type`、`context_id` 和 `node_id`。

**zip-url** -- 获取文件夹或整个 workspace/share 的 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 聊天。默认范围是整个 workspace（所有已编入索引的文档）——除非您需要缩小搜索范围，否则省略 `files_scope` 和 `folders_scope`。使用范围或附件时，`nodeId` 和 `versionId` 都是必需的，且必须非空（从 storage list/details `version` 字段获取 `versionId`）。使用 `files_attach` 时，请先验证每个文件的 `ai.attach` 是否为 `true`（通过 storage details 检查）。返回聊天 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 响应完成，然后返回全文。

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

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

**transactions** -- 列出 AI 令牌使用交易，用于账单跟踪。

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

### 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** -- 列出 workspace 或 share 中的所有评论（非特定于节点）。列表参数与 list 相同。

**add** -- 向特定文件添加评论。正文：text（总共最多 8,192 个字符，去除 `@[...]` 提及标签后的显示文本最多 2,048 个字符）。支持提及标签：`@[profile:id]`、`@[user:opaqueId:Name]`、`@[file:fileId:name.ext]`。可选 parent_comment_id（单级线程，对回复的回复会自动扁平化）、可选 reference（类型、时间戳、页面、区域、用于内容锚定的 text_snippet）。使用 JSON 正文。

**delete** -- 删除评论。递归：删除父级也会删除其所有回复。

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

**details** -- 按 ID 获取单个评论的完整详情。

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

**reaction-remove** -- 从评论中删除您的表情符号反应。

### 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`（admin/member/guest）设置访问级别。对于共享，使用 `role`（admin/member/guest/view）。

**remove** -- 移除成员（无法移除所有者）。

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

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

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

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

**join** -- 基于组织成员资格自行加入。

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

### invitation

所有邀请操作都需要 `entity_type` 参数（`workspace` 或 `share`）和 `entity_id`（19 位配置文件 ID）。

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

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

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

**delete** -- 撤销并删除待处理的邀请。

### asset

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

**upload** -- 上传资源（例如 Logo、横幅、个人资料照片）。提供纯文本内容或 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`（markdown 用 "md"）。

**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=none, 1=low, 2=medium, 3=high, 4=critical）、`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`。

### worklog

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

**append** -- 向工作日志追加新条目。需要 `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`（markdown 用 "md"）。

**interject** -- 创建需要确认的紧急插入条目。需要 `entity_type`（"task"、"task_list"、"node" 或 "profile"）、`entity_id` 和 `content`（1-10000 个字符）。插入是优先级修正 —— 始终被视为紧急。

**details** -- 获取特定工作日志条目的完整详细信息。需要 `entry_id`。支持 `format`。

**acknowledge** -- 确认插入条目，将其标记为已读。需要 `entry_id`。

**unacknowledged** -- 列出未确认的插入。需要 `entity_type`（"task"、"task_list"、"node" 或 "profile"）和 `entity_id`。支持 `limit`、`offset` 和 `format`。在继续工作之前，请务必检查是否有未确认的插入。

### approval

范围限定于任务、存储节点或工作日志条目的正式审批请求。所有审批操作都要求在目标实体上启用工作流。

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

**create** -- 创建新的审批请求。需要 `entity_type`（"task"、"node" 或 "worklog_entry"）、`entity_id`、`profile_id` 和 `description`（1-5000 个字符）。可选 `approver_id`（指定审批人的配置文件 ID）、`deadline`（ISO 8601）、`node_id`（工件引用）。

**details** -- 获取审批请求的完整详细信息，包括审批人列表和解决方案。需要 `approval_id`（不透明字母数字字符串）。支持 `format`。

**resolve** -- 解决审批请求。需要 `approval_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`。

**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 标记为未完成）。

### import

用于将文件从外部云存储提供商同步到工作区存储的云导入操作。所有导入操作都要求在目标工作区上启用云导入（`workspace` 操作 `enable-import`）。

**list-identities** -- 列出工作区的所有提供商身份。需要 `workspace_id`。支持 `format`（markdown 用 "md"）。返回包含提供商、电子邮件、状态和创建日期的身份记录。

**provision-identity** -- 为云提供商配置新的服务帐户身份。需要 `workspace_id` 和 `provider`（google_drive、box、onedrive_business 或 dropbox）。返回包含 `identity_email`（用户与之共享文件夹的地址）和设置 `instructions` 的身份。

**identity-details** -- 获取提供商身份的完整详细信息。需要 `workspace_id` 和 `identity_id`。返回包括代理电子邮件地址在内的身份记录。

**revoke-identity** -- 撤销并删除提供商身份。需要 `workspace_id` 和 `identity_id`。使用此身份的所有导入源将停止同步。具有破坏性。

**list-sources** -- 列出工作区的导入源。需要 `workspace_id`。支持 `status` 筛选器和 `format`（markdown 用 "md"）。返回包含远程路径、同步状态、文件计数和计划的源记录。

**discover** -- 发现提供商身份的共享文件夹。需要 `workspace_id` 和 `identity_id`。运行对与代理共享的文件夹的发现扫描，并返回包含 `remote_path`、`name`、`size`、`file_count` 和 `already_imported` 标志的 `shared_folders`。

**create-source** -- 创建一个新的导入源以开始同步共享文件夹。需要 `workspace_id`、`identity_id` 和 `remote_path`（来自发现结果）。可选参数包括 `remote_name`（显示名称）、`sync_interval`（300-86400 秒，默认 3600）和 `access_mode`（默认为 "read_only"，或用于双向同步的 "read_write"）。返回新源并触发初始同步任务。

**source-details** -- 获取导入源的完整详细信息。需要 `source_id`。支持 `format`（"md" 表示 Markdown）。返回包含 `root_node_id`（工作区文件夹节点）、同步计划、文件计数和总大小的源记录。`root_node_id` 指向一个设置了“已导入”标志的文件夹节点；所有后代节点都继承导入行为。

**update-source** -- 更新导入源设置。需要 `source_id`。支持 `sync_interval`、`access_mode`、`remote_name` 和 `status`（"paused" 暂停同步，"synced" 恢复同步）。

**delete-source** -- 删除导入源及其相关数据。需要 `source_id`。破坏性操作。

**disconnect** -- 断开导入源连接，并可选择导入文件的处理方式。需要 `source_id` 和 `disconnect_action`："keep"（导入的文件变为常规工作区文件）或 "delete"（导入的文件移至回收站）。无论哪种情况，源都会被移除。

**refresh** -- 立即触发导入源同步，而不是等待下一个计划的时间间隔。需要 `source_id`。返回新的同步任务。

**list-jobs** -- 列出导入源的同步任务。需要 `source_id`。支持 `limit`（1-100）和 `format`（"md" 表示 Markdown）。返回包含类型、状态、文件计数、传输字节数和时间的任务记录。

**job-details** -- 获取同步任务的完整详细信息，包括实时进度。需要 `source_id` 和 `job_id`。对于正在运行的任务，`progress` 字段显示 `percentage`（百分比）、`current_file`（当前文件）、`speed_bytes_per_sec`（速度/秒）和 `eta_seconds`（预计剩余时间）。

**cancel-job** -- 取消正在运行的同步任务。需要 `source_id` 和 `job_id`。

**list-writebacks** -- 列出导入源的写回任务（仅限 read_write 访问模式）。需要 `source_id`。支持 `status` 过滤器、`limit`（1-100）、`offset` 和 `format`（"md" 表示 Markdown）。返回包含节点 ID、远程路径、上传进度和冲突状态的写回记录。

**writeback-details** -- 获取写回任务的完整详细信息。需要 `source_id` 和 `writeback_id`。返回包含文件大小、已上传字节数、重试次数和冲突信息的写回记录。

**push-writeback** -- 强制将工作区文件推回远程提供商。需要 `source_id` 和 `node_id`（要推送的存储节点）。创建一个新的写回任务。仅适用于 read_write 导入源。

**retry-writeback** -- 重试失败的写回任务。需要 `source_id` 和 `writeback_id`。将任务重置为等待状态并重新排队。

**resolve-conflict** -- 当本地和远程文件均发生更改时，解决写回冲突。需要 `source_id`、`writeback_id` 和 `conflict_resolution`："keep_local"（将本地版本推送到远程，覆盖）或 "keep_remote"（拉取远程版本，丢弃本地更改）。

**cancel-writeback** -- 取消等待中的写回任务。需要 `source_id` 和 `writeback_id`。只有等待中或正在上传的写回任务可以被取消。