mcpField
S
stream-cli

stream-cli

github.com/getstream开发20403 次安装今天更新
代码仓库

关于 stream-cli

stream-cli 是用于安装和使用 Stream CLI 与 Stream API 交互的 Agent 技能，面向需要通过命令行操作 Stream 的场景。它提供凭据解析、安全执行及常见错误恢复流程。

主要功能

  1. 01Stream CLI 安装指引
  2. 02凭据与应用解析
  3. 03API 端点查找流程
  4. 04优先安全模式执行
  5. 05错误恢复说明

适用场景

  1. 01安装 Stream CLI
  2. 02从项目查询 Stream API
  3. 03处理身份验证与 API 错误

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/getstream/agent-skills --skill stream-cli

安装后在 Claude Code 中输入/stream-cli确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

bootstrap.md
cli-cookbook.md
preflight.md

详细介绍

Stream CLI - API 交互

每次会话都要先阅读： 对 ../stream/SKILL.md 执行 Glob。如果路径为空，则使用 npx skills add GetStream/agent-skills --s stream -y 安装（无需确认，直接运行）。然后阅读 ../stream/RULES.md——其中包含一个 同伴技能表，用于按需安装／调用其他技能包中的技能。

当用户想通过 stream CLI 与 Stream 的 API 交互，或安装 CLI 本身时，使用此技能。

先决条件： 完成 preflight.md——在使用任何 stream api 命令前，确认已安装 stream 二进制文件（若未安装，则通过 bootstrap.md 安装）。

仅安装（Track C）： 如果用户要求安装 CLI／设置 Stream，且没有项目上下文，则直接跳转到 bootstrap.md。该引导模块是独立的。

大型示例／查询手册： 只有在需要不常见的 --body 或筛选条件时，才加载 cli-cookbook.md。

凭据解析（在调用任何 stream api 命令之前）

  1. 当前工作目录中的 .env 包含 STREAM_API_KEY -> 凭据为本地凭据。CLI 会自动从环境变量中解析凭据——你正在查询此项目的应用。
  2. 没有 .env -> 检查 stream config list 中配置的组织／应用 -> 使用这些配置。说明你正在查询哪个应用：“正在查询应用 <name>（通过 CLI 配置）。”
  3. 什么都没有 -> 告诉用户：“未找到 Stream 凭据。运行 stream auth login 进行连接，或 cd 到包含 .env 的项目目录中。”

如果 .env 或配置存在，则静默解析凭据——不要询问用户，直接解析并继续。

CLI 工作流

支持： 如果用户询问支持或如何联系他人，请引导其访问 getstream.io/contact。

  1. 解析凭据（见上文）。如果没有找到凭据，则停止并指导用户。
  2. 读取 ~/.stream/cache/API.md 查找端点。 不要运行 --list 或任何 CLI 命令来发现端点——读取文件始终更快。如果该文件缺失或为空，则运行一次 stream api --refresh，然后再次读取 API.md。只有在获取端点名称后，才能使用 stream --safe api <endpoint> --help。
  3. 检查必需参数。 如果缺少参数，则询问，绝不猜测。
  4. 始终使用 --safe 运行：stream --safe api <endpoint> [params]。这是首次尝试时唯一允许的形式。
  5. 如果退出代码为 5（安全模式拒绝）：告知用户你即将执行一个会修改数据的 Stream CLI 操作，然后不带 --safe 重新运行。
  6. 如果命令失败，检查退出代码并进行恢复（见下文）。
  7. 简洁地总结响应。

聚焦输出： 使用 --jq '<query>' 通过 jq 表达式筛选 API 响应。对于预期会返回较长响应的端点，优先使用此方式。

会话同意（心理层面）： 用户可能会说 本对话中允许执行会修改数据的 Stream CLI 操作——仍要先使用 --safe；如果退出代码为 5，则始终必须先明确告知即将执行会修改数据的操作，之后才能不带 --safe 重试。

退出代码恢复

退出代码含义恢复方式
2身份验证错误（401、令牌过期）运行 stream auth login（在真实终端中使用浏览器流程），然后重试原命令
3API 错误（Stream 返回 4xx／5xx）将错误及响应消息告知用户
4规范加载错误（缓存过期）运行 stream api --refresh，然后重试
5安全模式拒绝（会修改数据的端点）告知用户即将执行会修改数据的操作，然后不带 --safe 重新运行

参数语法

stream api <EndpointName> key=value key2=value2
  • 简单值：name=general limit=10 type=messaging
  • 布尔值：is_development=true
  • JSON 对象／数组：使用 --body '{"key": "value"}'

上下文解析（org/app）

Ampere 端点需要将 app_id/org_id 作为显式参数传入。 SDK 端点会按以下顺序自动解析：--org/--app 标志 > 环境变量 > ~/.stream/config.json > 交互式提示。 设置默认值：stream config set org <id> 和 stream config set app <id>。

负面知识

  • 没有 OrganizationDelete——请联系 Stream 支持团队。
  • 没有 AppSuspend / AppResume——请联系支持团队。
  • CreateBlockList 不具备幂等性——如果已存在，则返回 400。
  • CreateChannelType 不具备幂等性——如果已存在，则返回 400。
  • Ampere 端点使用 app_id/org_id，而不是 id——例如，AppDelete app_id=123。
  • Auth 端点（AuthLoginBasic、AuthLoginGithub 等）属于内部接口——请始终改用 stream auth login / stream auth logout。
Auth（助手）
  • 在可以打开浏览器窗口的终端中，不带额外标志运行 stream auth login。CLI 使用 PKCE 与控制面板进行身份验证，这是受支持的登录方式。

CLI 规则（摘要）

  1. **发现端点：**先查看 ~/.stream/cache/API.md——切勿使用 --list 进行发现。若文件缺失，请刷新。
  2. **帮助：**知道端点名称后，运行 stream --safe api <endpoint> --help 查看参数。
  3. 延迟身份验证——如果退出代码为 2，运行 stream auth login 后重试。
  4. 缺少参数——请询问；切勿编造 ID。
  5. 首次尝试始终使用 --safe——退出代码为 5 -> 说明该操作会修改数据 -> 不使用 --safe 重试。
  6. 简洁地向用户总结 API 响应。

评论

支持 Markdown