flowus-cli

FlowUs CLI

使用 FlowUs CLI（flowus）执行 FlowUs V2 API 操作：页面、区块、数据库、搜索、Markdown 内容和文件。

通过已安装的 CLI 执行用户授权的操作；如果用户要求执行，不要只停留在介绍命令。对于原生数据库字段，准备请求文件前请先阅读操作指南。其中涵盖架构、记录关联、公式读取和验证。

CLI 源代码仓库可能是私有的。使用 CLI 前，不要要求用户克隆源代码。只有在用户明确批准后，才能从 FlowUs 官方 CDN 安装或更新已发布的二进制文件。

强制预检

在调用远程 FlowUs API 前完成此预检。CLI 帮助、端点文档和离线规划无需身份验证。

1. 检查 CLI 是否可用，不要安装或更新：

if command -v flowus >/dev/null 2>&1; then
  flowus version
else
  echo "FlowUs CLI is not installed"
fi

如果 CLI 缺失或版本过旧，请说明官方安装程序位于 https://cdn2.flowus.cn/flowus-cli/install（Windows 上为 https://cdn2.flowus.cn/flowus-cli/install.ps1）。在用户明确批准前，不要下载、执行或更新安装程序。

获得批准后，仅使用官方 URL 和用户批准的版本。将安装程序下载到临时文件；展示其来源、版本和 SHA-256 哈希值；并与官方校验和或签名进行比对，然后再执行。如果没有可用的官方完整性数据，请停止操作，建议手动安装，不要执行未经验证的安装程序。尝试完成后，删除临时安装程序文件。

2. 如果已安装 CLI，请检查身份验证状态和当前身份：

flowus --json doctor
flowus --json whoami

只有检查结果显示已通过身份验证的 FlowUs 凭据时，才能继续。如果缺少身份验证或凭据无效，不要自动启动登录流程。说明可选方案，并等待用户明确选择：

• 如果已设置 FLOWUS_TOKEN，请重新运行 flowus --json doctor 和 flowus --json whoami；不要要求用户重新登录。
• 浏览器登录：flowus login --browser。
• 无头环境的手动设置：flowus --json login --manual。
• 通过经批准的密钥渠道配置 FLOWUS_TOKEN 或已保存的凭据。

在 Agent 会话中不要运行普通的 flowus login，因为它可能会因交互式方法提示而阻塞。身份验证通过前，不要调用 API，也不要根据不完整的数据得出结论。用户明确批准登录方式后，只运行所选方式，然后重新运行 flowus --json doctor 和 flowus --json whoami。

仅在用户明确选择浏览器登录后，才使用此浏览器登录命令：

flowus login --browser

仅在用户明确为无头或远程环境选择手动设置后，才使用手动设置：

flowus --json login --manual

如果缺少命令或帮助输出看起来过时，请说明 flowus update 可以更新 CLI，并在运行前等待用户明确批准。

可用的安装覆盖选项：

• FLOWUS_INSTALL_DIR - 安装目录。
• FLOWUS_VERSION - 精确的发布版本，例如 v0.1.10。
• FLOWUS_CLI_RELEASE_BASE_URL - 用于测试的备用发布基础 URL。

首要规则：先询问 CLI

CLI 提供自我说明。请优先使用以下命令，而不是猜测语法或请求字段：

• flowus --help - 列出全局选项和顶层命令。
• flowus help <command...> - 显示任何命令或子命令的用法、选项、示例和注意事项。
• flowus api ls - 列出公开的 API 端点和请求字段提示。
• flowus api ls --plain - 列出精简的端点清单，便于浏览。
• flowus api --docs <PATH> -X <METHOD> - 显示单个端点的 Agent 可读 Markdown 文档，包括参数、示例和安全注意事项。
• flowus api --spec <PATH> -X <METHOD> - 显示单个端点的确切内嵌 OpenAPI 片段。
• flowus --json doctor - 当身份验证方式或基础 URL 的选择不明确时，检查本地身份验证和配置状态。
• flowus --json whoami - 验证当前启用的 FlowUs 身份。
• flowus --json workspace - 检查当前工作区和凭据边界。
• flowus --json workspace directory - 列出侧边栏中的收藏、团队、共享和私人版块。
• flowus --json fetch <link-or-id> - 解析 FlowUs 链接或 ID，并读取匹配的页面、数据库或区块。
• flowus markdown get <page-id> - 以 Markdown 格式获取页面内容。

如果不确定语法、请求正文中的字段、分页、身份验证来源或命令覆盖范围，请先运行 help。

凭据和配置

CLI 按以下优先级解析凭据：

1. --token <token>
2. FLOWUS_TOKEN
3. FlowUs 凭据存储中已保存的登录凭据

这是 CLI 的解析行为，并不意味着可以泄露凭据。不要在 Agent 命令、日志或共享 shell 中传入 --token：它可能通过进程列表或 shell 历史记录泄露。不要让用户在聊天中粘贴 Bearer 令牌。请使用预配置的 FLOWUS_TOKEN、已保存的凭据或经批准的密钥渠道；命令输出中出现的任何凭据都必须脱敏。

如果未配置凭据，请提供浏览器登录、手动设置或经批准的密钥渠道，并等待用户选择。所选登录方式成功后，重新运行 flowus --json doctor 和 flowus --json whoami。

OAuth 刷新和沙箱权限

即使是只读 API 命令，已保存的浏览器 OAuth 凭据也可能需要对凭据存储拥有写入权限，因为 CLI 会在发送 API 请求前轮换并原子化保存令牌。

• 如果 error.code 为 credential_store_permission_denied，或 needsCredentialWritePermission 为 true，不要启动登录。请申请对包含 credentialsPath 的目录进行范围严格限定的写入权限，然后重新运行 flowus --json doctor 和原始命令。重新进行身份验证无法解决本地文件系统拒绝访问的问题。
• 如果错误代码为 oauth_refresh_failed 或 oauth_refresh_rejected，且 reauthorizationRequired 为 false，请稍后重试相同命令；不要启动登录。
• 仅当 reauthorizationRequired 或 refreshTokenExpired 为 true，或者 OAuth 明确报告刷新令牌无效、已过期或已撤销时，才提供登录选项。
• 较旧的 CLI 版本可能只报告 Operation not permitted 或 OS error 1。对于已保存且可刷新的 OAuth 凭据，应将此情况视为很可能是凭据存储沙箱拒绝访问，并检查所报告的路径和沙箱，再判断令牌是否已撤销。

切勿将 credentials.json 复制到工作区或暴露其内容。

常用环境变量：

• FLOWUS_TOKEN - 用于 API 调用的 Bearer 令牌。
• FLOWUS_BASE_URL - API 基础 URL；默认值为 https://api.flowus.cn。
• FLOWUS_CONFIG_DIR - 配置目录；默认值遵循 FlowUs 配置文件。
• FLOWUS_USER_AGENT - 自定义 user agent 后缀。

不要打印 Bearer 令牌、将其写入文件或粘贴到请求正文中。不要使用 curl 调用 FlowUs V2 API；请使用 CLI，以确保身份验证、产品默认设置、重试和错误格式保持一致。

工作规则

• 使用 --json 获取稳定、适合机器读取的标准输出。要求 ok:true，并读取 data 下的 API 对象（创建的 ID 位于 data.id）。如果 ok:false，请检查 error；不要将失败的命令视为已完成的操作。
• 将 JSON 请求正文保存在本地文件中，并使用 --body <file> 传入。
• 将 Markdown 替换内容保存在本地文件中，并使用 --file <file> 传入。
• 优先使用领域命令，而不是 api call；如果存在推荐的领域命令，flowus api --docs 会列出该命令。
• 对于分页命令，请检查 JSON 输出中的游标，并使用该命令的游标选项重复执行。

写入安全

在进行任何远程创建、更新、追加、上传、替换或原始 API 写入之前：

1. 核实确切的目标、操作和预期影响（包括记录数、受影响的块或上传的文件）。
2. 在可行时，先读取当前目标。对于 Markdown 替换，除非用户明确授权完全替换，否则请先对比现有内容。如果 CLI 提供版本或 ETag，请使用 --if-match。
3. 用户的任务即授权执行其中要求的更改。通过读取结果或创建结果解析 ID，并在授权范围内选择常规实现细节；无需要求用户提供生成的 ID，也无需重复征求已有批准。只有在目标仍有歧义，或更改超出请求范围时才询问。
4. 确认文件和外部 URL 已获用户授权，且不包含不应提供给目标工作区的凭据或私密数据。

CLI 会有意拒绝 DELETE API 调用。此技能不会执行或建议绕过方式；请使用需再次确认的专用删除工作流。

常见工作流

发现页面、成员和对象

flowus --json workspace
flowus --json workspace directory --page-size 100
flowus --json page list --page-size 100
flowus --json page list --parent-id <page_id> --page-size 100
flowus --json page team --page-size 100
flowus --json page private --page-size 100
flowus --json page shared --page-size 100
flowus --json page favorites --page-size 100
flowus --json user ls --query "display name" --page-size 100
flowus --json fetch <link_or_id>

page list 会返回一层类似页面的子项。省略 --parent-id 可列出工作区根目录。如果返回的节点有子项，请将其 ID 作为 --parent-id 传入，以检查下一层。如果任务涉及 FlowUs 侧边栏而非特定父项，请使用分区命令。user ls --query 匹配显示名称，而非电子邮件地址。

读取页面

flowus --json page get <page_id>
flowus markdown get <page_id> > page.md

只要可行，页面内容工作都请使用 Markdown。与原始块 JSON 相比，Markdown 更便于检查、编辑和比较差异。

替换页面 Markdown

flowus markdown put --file page.md <page_id>

只有在确认目标页面 ID 和替换文件后，才能运行此命令。

使用 JSON 创建或更新页面

创建本地 JSON 正文文件，然后传入 CLI：

flowus --json page create --body page.json
flowus --json page update --body patch.json <page_id>

对于幂等创建，请使用 --idempotency-key <key>。

编辑或复制页面

flowus --json page edit <page_id> --old "old text" --new "new text"
flowus --json page duplicate <page_id> --parent-id <parent_id> --title "Copy title"

默认情况下，page edit 要求匹配项必须精确且唯一。只有在确实要替换所有匹配项时，才使用 --replace-all。复制前，请先读取源页面并确认目标父项；省略 --parent-id 可将副本保留在源页面旁边。

块和子项

对于标注框／折叠块首行编辑、空白占位符，或将标题移出子段落的情况，请阅读 自有文本和子项。callout.rich_text 是标注框中第一个可编辑行；toggle.rich_text 是折叠标题。children 是独立的块。请同时读取块本身及其子项；仅凭 Markdown 无法确认布局是否等效。

flowus --json block get <block_id>
flowus --json block children <block_id>
flowus --json block append <block_id> --body children.json
flowus --json block update <block_id> --body block-patch.json

数据库

flowus --json database get <database_id>
flowus --json database query <database_id> --body query.json
flowus --json database mutate <database_id> --body mutation.json --idempotency-key <key>
flowus --json database view list <database_id>
flowus --json database view get <database_id> <view_id>
flowus --json database view create <database_id> --body view.json --idempotency-key <key>
flowus --json database view update <database_id> <view_id> --body view-patch.json --if-match <etag>
flowus --json page property get <page_id> <property_id>

在编写 query.json 之前，请使用 flowus api --docs 或命令帮助检查筛选和排序正文的格式。

使用 database mutate 执行一次原子化且经过权限检查的数据库写入。先读取数据库；进行更改时使用稳定的属性 ID；使用稳定的幂等键；如果用户要求创建记录，切勿覆盖现有记录。使用 flowus api --docs 获取准确的正文格式。

创建数据库视图时，请使用稳定的幂等键。更新视图前先读取，并使用返回的弱 ETag 和 --if-match，以便检测并发更改，而不是静默覆盖。

搜索

flowus --json search text "roadmap" --page-size 10
flowus --json search semantic "tasks about quarterly planning" --space-id <space_id> --page-size 10

使用文本搜索查找精确标题、关键词和已知短语。当意图比精确措辞更重要时，使用语义搜索。

文件

上传本地文件到父页面：

flowus --json file upload --parent-page <page_id> ./report.pdf

使用返回的对象名称和大小，追加一个由 FlowUs 托管的文件块：

flowus --json block append-file <block_id> --oss-name <oss_name> --size <bytes>

追加外部文件 URL：

flowus --json block append-file <block_id> --external-url https://example.com/report.pdf

备用 API 调用

只有在没有领域命令可用于该端点时，才使用 api call。查询顺序：

flowus api ls --plain
flowus api --docs /v2/blocks/{block_id}/children -X PATCH
flowus api --spec /v2/blocks/{block_id}/children -X PATCH
flowus --json api call PATCH /v2/blocks/:block_id/children --param block_id=<block_id> --body body.json

对于 POST、PUT 或 PATCH，请先阅读 --docs 和 --spec，并遵循上述写入安全规则。--param 会先填充路径占位符；其余键将作为查询参数。仅对非机密标头（例如 If-Match）使用 --header NAME=VALUE；切勿在标头中放入凭据或会话信息。

故障排除

• 找不到命令：提供官方安装程序 https://cdn2.flowus.cn/flowus-cli/install，并等待明确批准后再使用。
• 未知命令或选项：运行 flowus update 前先征求批准，然后运行 flowus <command> --help。
• 身份验证失败：运行 flowus --json doctor，然后遵循上述 OAuth 刷新和沙箱权限规则。不要将所有失败或 HTTP 401 都视为刷新令牌已过期。
• API 结构异常：重试前运行 flowus api --docs <PATH> -X <METHOD> 和 flowus api --spec <PATH> -X <METHOD>。