安装 CLI：无浏览器引导凭证并列出工作区

你将得到什么

• 本机可用的 communicate 命令（@communicate_so/cli）
• 一份权限收紧的 account credential 文件（模式 0600，勿提交 Git）
• 一次成功的 communicate workspaces list JSON 输出（对照：stdout 为工作区数组/对象 JSON）

开始前准备

1. Node.js 22+（官方 CLI 硬性要求）。核对：

node --version

对照结果：主版本 ≥ 22（例如 v22.x.x）。若偏旧，先升级 Node 再继续。

2. 已在 Communicate 注册，邮箱/密码可登录（bootstrap 需要已验证账号）。
3. 本机终端可写用户目录；准备一个仅本机、勿入库的工作目录，例如 ~/communicate-lab。

核心事实（先记住）

官方说明：当前增量覆盖 account credentials、workspaces、members、teams、agents、sources、learning、Grill、个人通知等；完整产品对等、MCP 写入、计费等仍在后续增量。先以 --help 与 capabilities 为准。

步骤 1：全局安装 CLI

npm install --global @communicate_so/cli@latest
communicate --version
communicate --help

对照结果：

• --version 打印具体版本号（与 npm 当前公开版一致即可）
• --help 列出命名子命令；无 “command not found”

若 communicate 找不到：确认 npm 全局 bin 已在 PATH（npm prefix -g/npm bin -g）。

步骤 2：查看 bootstrap 输入 schema

官方要求：先 --help 再准备 proof.json。proof.json 含邮箱、密码、凭证名称与所需 scopes——保持私密，勿提交、勿打进日志。

mkdir -p ~/communicate-lab && cd ~/communicate-lab
communicate auth credentials bootstrap --help

对照结果：帮助中出现 input JSON schema / 字段说明（以你安装的 CLI 版本打印为准）。

按 schema 写好 proof.json 后立刻收紧权限：

chmod 600 proof.json

步骤 3：无浏览器 bootstrap 凭证

官方示例（输入走 stdin，输出写新文件；已存在的输出文件不会被覆盖）：

communicate auth credentials bootstrap --input - --output-file credential.json < proof.json

对照结果：

• 退出码 0
• 新建 credential.json，权限应为 0600
• 文件内为完整响应（含一次性 secret）——按官方要求像保护密钥一样保护它

凭证文件须：用户所有、普通文件、无符号链接、权限收紧。也可用密钥管理器注入 COMMUNICATE_TOKEN，而不落盘。

步骤 4：列出工作区（验证管理面）

communicate workspaces list --token-file credential.json

对照结果：stdout 为 JSON（成功走 stdout；错误为 stderr 结构化 JSON）。能看到你账号下的 workspace 列表即可。

可选：用环境变量代替 --token-file：

export COMMUNICATE_TOKEN="$(jq -r '.token // .access_token // .secret // empty' credential.json)"
# 上式字段名以 bootstrap 实际响应为准；没有对应字段时请直接把官方返回的 token 写入密钥管理器后再 export
communicate workspaces list

若字段不确定：打开 credential.json 对照官方响应结构，不要把全文贴到聊天或截图外发。

步骤 5（可选）：创建工作区 / Agent / 上传知识

官方「Manage a workspace and its sources」示例——先对每个命令跑 --help 生成合法 JSON，再用：

communicate workspaces create --input - < workspace.json
communicate workspaces get --workspace WORKSPACE_ID
communicate agents create --workspace WORKSPACE_ID --input agent.json
communicate sources upload --workspace WORKSPACE_ID --agent AGENT_ID --file knowledge.txt

--workspace / --agent 与 JSON 内选项冲突时会被拒绝。可用 --dry-run 只校验输入并打印 method/route，不发请求。

退出码速查（官方）

默认 API URL：https://app.communicate.so/api/v1。除 loopback 外要求 HTTPS；认证后的重定向会被拒绝；写操作不会自动重试——超时后先核对服务端状态再重试。

本课检查清单

• node --version ≥ 22
• communicate --version 有输出
• credential.json 已生成且权限 0600
• communicate workspaces list --token-file credential.json 返回 JSON

下一课：用 workspace OAuth token 做 Agent 列表 + chat，并配置 MCP。