# Agent 数据网关 CLI 安装指南

本文档用于指导 Agent 根据用户提供的 `install token` 和 `Region` 安装 Agent 数据网关 CLI（`dgate`）。

## Agent 执行要求

1. 自动识别当前操作系统，选择对应的安装命令；只有无法识别时才询问用户。
2. 自动识别当前宿主 Agent IDE，并将对应值传给 `--install-ide`。不在支持列表、但已从当前 IDE 的可靠配置或用户输入确认其 Skills 根目录时，按下方“自定义 Agent 目录”流程安装；无法确认目录时不要猜测。
3. 使用调用方提供的 `install token` 和 `Region`，不要自行替换、缓存或生成凭证。
4. `install token` 是一次性敏感凭证，不得在回复、日志或公开环境中展示完整值。
5. 命令成功后执行“安装后验证”；未通过验证时不得宣称安装完成。

## 安装执行权限（必须遵守）

- **不得在 IDE / Agent 沙箱中执行安装命令。**安装过程需要访问外部下载地址，并写入系统临时目录、用户级 CLI/配置目录及 IDE 的全局 Skill/Rule 目录，这些操作通常超出仅允许写工作区的沙箱边界。
- 如果当前执行器显示“沙箱运行”“sandboxed”等状态，Agent 必须停止当前安装，并申请经用户批准后在宿主机普通终端中重新执行。获得批准前不得继续；无法申请非沙箱执行时，应把安装命令交给用户手动运行。
- 沙箱内下载失败时，不得通过强制 TLS 版本、设置 `ExecutionPolicy Bypass` 或在 `irm` / `curl` / `wget` 之间反复切换来规避限制；这些方式不会解除沙箱的网络与文件权限。应保留原始错误摘要，并明确报告需要非沙箱执行。
- “非沙箱执行”不等于“管理员运行”。除非错误明确表明且用户批准需要管理员权限，否则不得自行提权。

## 生产环境安装

将命令中的 `dit_xxx` 和 `cn-hangzhou` 替换为调用方提供的真实值。

### macOS / Linux

```bash
curl -fsSL https://d.tb.cn/i.sh | \
  bash -s -- \
    --install-token dit_xxx \
    --region cn-hangzhou \
    --install-ide cursor
```

### Windows PowerShell

```powershell
irm https://d.tb.cn/i.ps1 -OutFile $env:TEMP\i.ps1
& $env:TEMP\i.ps1 --install-token dit_xxx --region cn-hangzhou --install-ide cursor
```

`--install-ide` 为可选参数。当前支持：

| Agent IDE | `--install-ide` 取值 |
|---|---|
| Qoder | `qoder` |
| Cursor | `cursor` |
| Codex | `codex` |
| OpenCode | `opencode` |
| CodeBuddy | `codebuddy` |
| Claude Code | `claude` |
| CoPaw | `copaw` |
| QoderWork | `qoderwork` |

### 自定义 Agent 目录

当前宿主 IDE 不在上表时，先确认它的全局 **Skills 根目录**。安装主 CLI 时加 `--skip-quickstart`，避免非交互 quickstart 默认注入 Cursor；主安装成功后再执行：

```bash
dgate quickstart --yes --agent-dir <agentSkillsDir>
```

`--agent-dir` 可重复传入。CLI 会在每个 Skills 根目录下创建当前渠道 bundle；未知 IDE 只安装 Skill，不猜测 Rule 路径或格式。若无法可靠确认 `<agentSkillsDir>`，完成 CLI 与凭证安装即可，并请用户稍后运行交互式 `dgate quickstart` 选择“自定义 Agent 目录”。

## 安装后验证

```bash
dgate version
dgate acl role current -o json
```

两条命令均成功，且第二条命令返回当前 Agent 身份或角色信息后，才可确认安装与接入完成。

## 预发环境

仅在调用方明确要求使用预发环境时，将生产安装脚本切换为：

- macOS / Linux：`https://d.tb.cn/i-beta.sh`
- Windows PowerShell：`https://d.tb.cn/i-beta.ps1`
- 安装后命令：`dgate-beta`

预发与生产 CLI、配置和 Agent Skill 相互隔离，可在同一设备上并存。

## 故障处理

- 凭证过期或已使用：请用户返回 Agent 数据网关控制台重新生成 `install token`。
- 脚本下载失败：先确认命令是否误在 Agent 沙箱中执行；若是，按“安装执行权限”申请非沙箱执行，不要在同一沙箱中更换下载方式重试。保留 HTTP 状态码和错误摘要，不要回显凭证。
- CLI 已安装但命令不可用：按安装器提示重新加载 shell 配置，或重新打开终端。
- Agent IDE 配置失败：主 CLI 安装成功后可单独重试 IDE 接入，不要重复消费 `install token`。

最后更新：2026-09-04