<!-- Source: https://deepseek-browser-use.io.nexus/03_client -->

# 客户端：dsb 命令行与结构化留档

`dsb` 是 Go 实现的命令行客户端，负责参数解析、HTTP 调用、退出码和 UTF-8 留档。浏览器操作由服务端执行。安装、多目标和后端管理见 [客户端安装与管理](<https://deepseek-browser-use.io.nexus/37>)，可靠采集见 [上下文与证据](<https://deepseek-browser-use.io.nexus/38>)。本章提供当前可执行入口，不依赖已经移除的 Python 客户端。

## 1. 常用命令

```powershell
dsb methods
dsb --port 10049 health
dsb --port 10049 --id 1001 start --browser chrome --headful
dsb --port 10049 --id 1001 run go_to_url -p url=https://example.com --out navigation.json
dsb --port 10049 --id 1001 state --text-only
dsb --port 10049 --id 1001 close
```

1001 为数字示例 ID，使用前确认没有被占用。同一任务复用 ID，结束时只关闭自己的任务。`methods` 与 `list_methods` 是等价的 CLI 子命令；协议方法也可通过 `dsb run list_methods` 调用。

### 选择浏览器 profile

```powershell
dsb profiles
dsb profile list
dsb profile clone --name litongjava --source-user-data-dir "<Chrome User Data>" --source-profile-directory Default
dsb --id 1001 start --browser chrome --headful --profile litongjava
# 或选择现有独立目录，不与 --profile 混用
dsb --id 1001 start --browser chrome --headful --user-data-dir "<独立 User Data>" --profile-directory "Profile 5"
```

以上两种 `start` 是替代方案，不要连续执行来尝试切换正在运行的共享浏览器。显式 profile 只支持 Chrome；未传浏览器或传 `auto` 也选择 Chrome。未知名称、路径错误与启动失败不回退。先查看任务，只关闭自己的任务，不能为换 profile 关闭别人的页签。字段契约与离线克隆限制见 [profile 列表、克隆与选择](<https://deepseek-browser-use.io.nexus/39>)。

## 2. 复杂参数放入文件

保存 `params.json`：

```json
{"selector":"#display-name","text":"示例用户","mode":"type"}
```

```powershell
dsb --id 1001 run input_text_by_selector --params "@params.json"
dsb --id 1001 js "@collect.js" --out collected.json
```

参数文件也支持带 method、params 的完整请求体，由客户端提取 params。中文、多行 JavaScript 和复杂选择器优先使用文件，避免多层引号转义。

## 3. 输出模式与退出码

| 选项 | 用途 |
| --- | --- |
| --summary / --compact | 简化终端摘要 |
| --json | 输出 JSON |
| --select data.fields | 只投影一个字段路径，支持点分隔和数字数组下标 |
| --out response.json | 保存完整 UTF-8 JSON 响应，优先于终端投影 |
| --grep 关键词 | 只展示匹配行；可同时保存完整响应 |
| --response-mode compact / full | 默认 compact 精简成功回执；full 保留全部字段，与终端摘要不同 |
| --diagnostics | 跳过服务端裁剪，保留完整诊断 |

退出码：0 成功，1 传输或协议错误，2 业务失败，3 客户端用法或输出处理错误。不要只凭退出码推断动作没有执行。响应字段缺失是在收到回执后才能判断的；应读取留档或 `dsb last`，不要重复发送业务动作。

`--select` 不执行表达式，不支持逗号分隔多字段。需要多个字段，先保存完整响应再处理。选择路径缺失时默认输出 null 并报错；值明确为 JSON null 则是有效选择。宽松兼容模式见 [单路径选择与防重复执行](<https://deepseek-browser-use.io.nexus/37>)。

客户端 `--out` 直接写 UTF-8；不要用 shell 的 `> 文件` 代替，也不要把 stderr 混进 JSON。优先用宿主文本读取工具读文件，不从终端摘要里截取大括号猜测 JSON。

## 4. 批量与异步

保存 `commands.json`：

```json
[
  {"get_title": {}},
  {"get_url": {}}
]
```

```powershell
dsb --id 1001 batch commands.json
dsb --id 1001 batch commands.json --async --wait
```

默认发生动作错误后停止，只有独立且可以继续的步骤才使用 `--keep-going`。HTTP 超时不表示动作未执行；异步作业复用返回的 jobId 查询，不重新提交。详见 [批量与作业](<https://deepseek-browser-use.io.nexus/26>)。

## 5. 留档与复核

默认调用会保存请求与响应；读取自己当前会话的文件，避免混淆不同任务。终端投影不改变留档结构，结构化 Cookie 值按下述策略遮蔽。

显式 `--id` 可让 `last` 在当前留档目录中筛选属于该任务的最新响应：归属以同编号请求的顶层 ID 为准，无匹配报错，不回退其他任务。缺失或损坏的请求不能确定归属，不参与筛选；最新匹配响应本身失败时不回退旧成功记录。不传显式 ID 保留读取目录最新响应的行为。

```powershell
dsb --id 1001 --session example --record-dir ./logs/agent/example last --select data
```

`--record-dir` 是最终目录，不追加 session；`DSB_RECORD_DIR` 是默认路径计算的根目录。`--no-record` 不生成本次新记录，因此不能把随后读到的旧记录当作本次证据。

```text
logs/agent/<会话>/001.req.json
logs/agent/<会话>/001.res.json
logs/agent/<会话>/steps.log
```

自动请求/响应留档会将结构化 `cookies` 数组及 `set_cookie` 参数中的 Cookie 值替换为 `[REDACTED]`，不修改实时请求、stdout 或显式 `--out` 导出。任意脚本、页面文本、错误消息、HTTP 头、服务端 trace 与历史记录不在此功能覆盖范围，不能把它当成通用脱敏。敏感操作可使用 `--no-record` 关闭客户端自动留档，并单独保护显式导出目录；该开关不关闭服务端日志。留档仍可能包含页面原文和敏感数据，不公开整份 Cookie、账号信息或凭据。模型只读到截断预览时，不能声称阅读了全部响应；采集数、展示数、已读数和有效样本数分别统计。

## 6. PowerShell 集成

PowerShell 可以直接调用同一个 dsb，无须另写 HTTP 封装。每条依赖命令完成后检查原生进程退出码，并保留 stderr 诊断：

```powershell
dsb --id 1001 state --out state.json
if ($LASTEXITCODE -ne 0) {
  throw "Read the response and diagnostics before continuing"
}
```

不要使用 `Select-Object -First` 提前关闭 dsb 的输出管道；需要少量字段时优先用 `--select`，需要保存时使用 `--out`。旧的 Python Client 类和包装脚本不再作为当前工程集成入口。

### 默认精简响应与截图文件

CLI 默认请求 `responseMode:compact`。正常成功回执省略常规执行、零重试和正常截图诊断；失败、状态未知和截图降级仍保留诊断。`--diagnostics` 跳过裁剪，`--response-mode full` 请求完整响应。`--json` 只决定终端格式；`--summary` 只决定本地摘要。

`--out` 保存的是当前模式下收到的 JSON，不是图片，也不会恢复被服务端省略的字段。自动留档和 `last` 同样不能恢复这些字段；不要重放写操作来补诊断，必要时使用只读 `diagnose` 查看最近命令。

```powershell
# 复用已启动且由自己拥有的任务 ID
dsb --id 1001 --session example run screenshot --out shot-response.json
if ($LASTEXITCODE -ne 0) {
  throw 'Read the response and diagnostics before continuing'
}
$result = Get-Content 'shot-response.json' -Raw -Encoding UTF8 | ConvertFrom-Json
$result.data.path
```

`data.path` 是服务端文件路径；远程服务使用 `data.url`，相对 URL 需按服务地址解析。不要将 JSON 输出文件命名为 `.png`。仅需路径时可在原命令使用 `--select data.path`。PowerShell 启动时若 profile 被执行策略拦截，宿主应使用 `powershell.exe -NoProfile`，无需修改系统执行策略。