buildin-cli

Buildin CLI

使用 Buildin CLI（buildin）处理 Buildin V2 API 相关工作：页面、块、数据库、搜索、Markdown 内容和文件。

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

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

处理 Buildin 相关工作时，只能使用 Buildin 命令、Buildin 基础 URL、BUILDIN_* 环境变量和 Buildin 凭据存储。

必须完成的预检

调用远程 Buildin API 前，必须完成此预检。查看 CLI 帮助、端点文档和离线规划不需要身份验证。

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

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

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

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

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

buildin --json doctor
buildin --json whoami

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

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

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

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

buildin login --browser

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

buildin --json login --manual

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

有用的安装覆盖项：

• BUILDIN_INSTALL_DIR - 安装目录。
• BUILDIN_VERSION - 指定确切的发布版本，例如 v0.1.10。
• BUILDIN_CLI_RELEASE_BASE_URL - 用于测试的备用发布基础 URL。

首先：询问 CLI

CLI 提供自助文档。与其猜测语法或请求字段，不如优先使用以下命令：

• buildin --help - 列出全局选项和顶层命令。
• buildin help <command...> - 查看任意命令或子命令的用法、选项、示例和说明。
• buildin api ls - 列出公开 API 端点和请求字段提示。
• buildin api ls --plain - 紧凑的端点列表，便于浏览。
• buildin api --docs <PATH> -X <METHOD> - 查看单个端点的 Agent 可读 Markdown 文档，包括参数、示例和安全说明。
• buildin api --spec <PATH> -X <METHOD> - 查看单个端点的确切内嵌 OpenAPI 片段。
• buildin --json doctor - 在认证或基本 URL 选择不明确时，检查本地认证和配置状态。
• buildin --json whoami - 验证当前 Buildin 身份。
• buildin markdown get <page-id> - 以 Markdown 格式获取页面内容。

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

凭据和配置

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

1. --token <token>
2. BUILDIN_TOKEN
3. Buildin 凭据存储中保存的登录凭据

这是 CLI 的解析行为，并不代表可以公开凭据。不要在 Agent 命令、日志或共享 Shell 中传入 --token：它可能通过进程列表或 Shell 历史记录泄露。不要要求用户在聊天中粘贴 Bearer 令牌。请使用预配置的 BUILDIN_TOKEN、已保存的凭据或获批准的密钥渠道；如果命令输出中出现任何凭据，请将其遮盖。

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

OAuth 刷新和沙盒权限

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

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

切勿将 credentials.json 复制到工作区，也不要公开其内容。

常见环境变量：

• BUILDIN_TOKEN - API 调用的 Bearer 令牌。
• BUILDIN_BASE_URL - API 基本 URL；默认为 https://api.buildin.ai。
• BUILDIN_CONFIG_DIR - 配置目录；默认值遵循 Buildin 配置文件。
• BUILDIN_USER_AGENT - 自定义 User-Agent 后缀。

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

工作规则

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

写入安全

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

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

CLI 会有意拒绝 DELETE API 调用。本技能不会执行或建议绕过此限制；请使用专门的删除工作流，并进行第二次确认。

常见工作流

读取页面

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

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

替换页面 Markdown

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

仅在确认目标页面 ID 和替换文件后执行。

使用 JSON 创建或更新页面

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

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

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

区块和子项

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

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

数据库

buildin --json database get <database_id>
buildin --json database query <database_id> --body query.json
buildin --json database create --body database.json
buildin --json database update <database_id> --body patch.json
buildin --json page property get <page_id> <property_id>

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

搜索

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

对于精确标题、关键词和已知短语，请使用文本搜索。若意图比确切措辞更重要，请使用语义搜索。

文件

为父页面上传本地文件：

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

使用返回的对象名称和大小追加 Buildin 托管文件区块：

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

追加外部文件 URL：

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

回退 API 调用

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

buildin api ls --plain
buildin api --docs /v2/blocks/{block_id}/children -X PATCH
buildin api --spec /v2/blocks/{block_id}/children -X PATCH
buildin --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://cdn.buildin.ai/buildin-cli/install，并在获得明确批准前等待，不要使用它。
• 未知命令或选项：先征求批准，再运行 buildin update，然后运行 buildin <command> --help。
• 身份验证失败：运行 buildin --json doctor，然后遵循上述 OAuth 刷新和沙盒权限规则。不要将所有失败或 HTTP 401 都视为刷新令牌已过期。
• API 结构异常：在重试前，先运行 buildin api --docs <PATH> -X <METHOD> 和 buildin api --spec <PATH> -X <METHOD>。