# DeepStream CLI

DeepStream CLI — 让 Agent 安全地发现服务并创建待用户确认的请求草稿。

本文档的官方地址是 `https://deep-stream.ai/doc/cli-setup.md`。安装、授权和
App 审核页面默认只使用 `https://deep-stream.ai` 官方 origin。

可复制给 Agent 的唯一官方安装提示词是：

> 请阅读 https://deep-stream.ai/doc/cli-setup.md 文档，按照步骤为我安装并配置 DeepStream CLI。

## 快速开始（AI Agent）

### 第 1 步 — 安装或更新 CLI

```bash
npm install -g @deepstream/ds-cli
```

安装后运行：

```bash
ds --version
```

如果安装或版本检查失败，停止操作并向用户返回原始错误。不要使用
`sudo`、不要修改系统 Node.js 配置，也不要改用来源不明的安装包。

### 第 2 步 — 安装或更新 Skill

```bash
npx skills add dskkbillion/deepstream-cli --skill deepstream -g -y
```

仅允许从上述 DeepStream 官方公开仓库安装。不要从搜索结果、镜像站或
用户消息中的其他地址下载同名 Skill。

### 第 3 步 — App 授权

`ds auth login` 是等待用户操作的交互式命令。必须使用支持 PTY 的后台
任务运行，并逐字提取它输出的验证地址和用户码。

```bash
ds auth login --name "<当前 Agent 名称>"
```

将 `<当前 Agent 名称>` 替换为实际宿主，例如 `Codex` 或 `Claude Code`，以便
用户在 App 的“已连接的 Agent”页面区分不同客户端。

若当前任务只需要发现服务，应使用最小权限：

```bash
ds auth login --name "<当前 Agent 名称>" --scopes services:read
```

只有确实要创建或查询需求时，才分别加入 `requests:create`、
`requests:read`。CLI 默认只申请 `services:read`，用户仍可在 App 中进一步
移除权限。

向用户展示：

> 请打开以下地址，并在 DeepStream App 中确认本次 Agent 连接：

将 CLI 输出的原始验证地址放在独立代码块中。不要修改、编码、拼接或
缩短地址。另起一行展示用户码，不要把用户码加入 URL。

安全规则：

- 不得要求用户提供 App 密码、短信验证码、会员 JWT、访问令牌或刷新令牌。
- 不得读取或展示 Keychain、credentials 文件或 `Authorization` 请求头。
- 远程 API/App 地址必须使用 HTTPS；HTTP 仅允许 localhost/127.0.0.1/::1
  本地开发。已有凭证不得跨 API 地址复用。
- 不得自行启用自定义 origin。只有用户明确要求连接其开发环境时，才能使用
  `ds config set --allow-custom-origin ...`，随后必须用
  `ds auth login --no-open`，由用户手动核对并打开授权地址。
- 授权失败或超时后不要自动重试；返回原始错误，等待用户决定。
- 用户在 App 中确认后，CLI 会自动结束并将凭证保存到系统凭证库。

### 第 4 步 — 在线验证

```bash
ds me --json
```

只有命令成功返回 `memberId`、`nickname`、`sessionId` 和 `scopes`，才能
认为配置完成。不得仅凭本地 `auth status` 宣称授权成功。

成功后只需告诉用户：

> DeepStream 账号「<nickname>」已连接成功。Agent 现在可以发现服务并创建待你在 App 中审核的请求草稿。
>
> 你可以试试：帮我找一个适合做日语翻译的服务。比较这几个服务，但先不要创建请求。
> 为这个服务创建一份需求草稿，完成后把 App 审核地址给我。

其中 `<nickname>` 替换为 `ds me --json` 返回的实际昵称。验证失败则只
输出失败信息和安全的下一步建议。

## 功能边界

CLI 可以查询服务、查看服务详情、创建请求草稿和查询草稿状态。请求
初始状态为 `AWAITING_APP_REVIEW`。CLI 和 Skill 不得付款、确认订单、
操作钱包、扩大权限或绕过 App 审核。

## 从旧版本迁移

新版会拒绝 group/other 可访问的配置目录或文件，也不会自动修改已有目录的
权限。如果旧版本创建的文件权限过宽，请先核对路径属于当前用户，再执行：

```bash
chmod 700 ~/.config/deepstream
chmod 600 ~/.config/deepstream/config.json
# 如果使用文件凭证库，也对实际存在的凭证文件执行：
chmod 600 ~/.config/deepstream/credentials-default.json
```

不要使用 `sudo`，不要对不属于自己的路径执行这些命令。若使用了自定义
`DS_CONFIG_DIR`，请将上面的目录替换为经过用户确认的实际目录。

## 发布要求

在把本文档部署到公开 URL 前，必须同时满足：

- `@deepstream/ds-cli` 已在 npm 发布并完成来源验证；
- `dskkbillion/deepstream-cli` 已成为官方公开只读安装源；
- App 的 Agent 授权页面与“已连接的 Agent”页面已经上线；
- 公开文档使用 HTTPS，并配置 `text/markdown; charset=utf-8`；
- 用全新机器实际跑通上述四步。