创建与管理

机器人的创建和管理通过官方命令行工具 2s1 完成。

安装与登录

npm install -g @2someone/cli

# 登录（会打开浏览器完成授权）
2s1 login

# 确认登录状态
2s1 whoami

创建机器人

2s1 bot create --username my_bot --nickname "我的机器人" \
  --description "这是一个示例机器人" \
  --capability bubble.create --capability bubble.read

参数	必填	说明
`--username`	是	机器人用户名，4-16 位字母数字下划线；没写 `_bot` 后缀会自动补上
`--nickname`	是	显示昵称
`--description`	否	机器人简介，显示在它的个人空间
`--capability`	否	能力，可重复传：`bubble.create` / `bubble.read` / `chat.send`
`--visibility`	否	可见性：`private`（默认）/ `unlisted`
`--install-policy`	否	群聊安装策略：`owner_only`（默认）/ `invite_required`

创建成功后会返回 botUserId，后续管理命令都用它来指定机器人。

两把密钥，别混用

机器人体系有两种密钥，用途完全不同：

	账号密钥（human key）	运行密钥（bot runtime key）
是谁的身份	你自己	机器人
怎么获得	`2s1 login` 或 `2s1 apikey create`	`2s1 bot key rotate`
用来做什么	创建/修改/停用机器人	机器人程序调接口（发泡泡、发消息）
放在哪	你自己的电脑	机器人程序的运行环境（如 GitHub Actions secret）

密钥安全

运行密钥（sk_ 开头）只在生成时显示一次，请立即保存。不要把密钥写进代码或提交到 Git 仓库——放进环境变量或部署平台的 Secret 里。如果怀疑泄露，立刻轮换。

管理运行密钥

# 列出当前密钥
2s1 bot key list <botUserId>

# 轮换：生成新密钥，同时自动禁用旧密钥
2s1 bot key rotate <botUserId> --yes

# 吊销指定密钥
2s1 bot key revoke <botUserId> <keyId> --yes

每个机器人同一时间只有一把启用的运行密钥——轮换即作废旧钥，记得同步更新部署环境里的 Secret。

改了能力记得换钥匙

用 2s1 bot update 增减能力后，已发出的旧密钥仍保留旧权限，需要 rotate 一次让新权限生效（或让被移除的权限真正失效）。

管理机器人状态

2s1 bot list                      # 列出我创建的机器人
2s1 bot show <botUserId>          # 查看详情
2s1 bot update <botUserId> --nickname "新昵称"   # 修改资料
2s1 bot pause <botUserId>         # 暂停（接口调用会被拒绝）
2s1 bot resume <botUserId>        # 恢复
2s1 bot disable <botUserId> --yes # 停用账号

安装到群聊

机器人要在群聊里发消息，必须先被安装到那个群（需要你对该群有管理权限）：

2s1 bot install <conversationId> --bot @my_bot --yes

测试机器人

CLI 内置了端到端测试命令，用运行密钥真实调用接口：

# 读取机器人自己发过的泡泡（只读，安全）
TWOSOMEONE_BOT_API_KEY=sk_xxx 2s1 bot test bubble-read

# 真实发布一条泡泡
TWOSOMEONE_BOT_API_KEY=sk_xxx 2s1 bot test bubble-create --text "Hello, 泡泡!" --yes

# 向群聊发一条真实消息
TWOSOMEONE_BOT_API_KEY=sk_xxx 2s1 bot test chat-send <conversationId> --text "在呢" --yes

所有命令都支持 --json 输出，方便脚本和 AI 编程助手使用：2s1 --json bot context 会输出完整的机器人系统说明。