# 沙箱 App 本地调试配置

当总流程识别到当前 AppID 符合 `doubao-sandbox-app-*` 时，使用本文件完成配置，然后返回 [overview.md](overview.md) 继续启动和调试。

## 获取沙箱 App

在 dbx 项目目录执行：

```bash
dbx app sandbox get
```

命令返回的关键字段是：

- `sandbox_app_id`：本轮使用的沙箱 AppID。
- `sandbox_app_secret`：该沙箱 App 对应的 AppSecret。
- `sandbox_project_id`：沙箱项目标识；仅在命令输出或后续流程明确需要时使用。

如果项目中已有沙箱 AppID，也仍应通过该命令取得与其配套的 AppSecret，并核对返回的 `sandbox_app_id` 与当前配置一致。

## 成组设置应用身份与服务地址

将返回的 `sandbox_app_id` 设置到以下位置：

- 根目录 `manifest.yaml` 的 `app_key`。
- 前端 `runtimeConfig.appId`。
- 业务 Server 实际读取的 AppID 配置。

将 `sandbox_app_secret` 设置到业务 Server 实际读取的安全配置中。沿用项目已有的凭据注入方式即可；如果项目选择通过环境变量注入，可以使用 `DOUBAO_APP_ID` 和 `DOUBAO_APP_SECRET`。AppSecret 只提供给业务 Server，不得写入前端、Manifest、Skill、日志或提交到仓库。

同时核对以下服务地址：

- `runtimeConfig.apiBaseUrl` 指向本轮实际启动的业务 HTTP Server。
- `manifest.mcp_server.end_point` 与 `dbx dev --mcp-endpoint` 指向本轮实际启动的 MCP Server。

不要假设业务 HTTP URL 与 MCP URL 相同。AppID、AppSecret 或服务地址任一项不匹配，都可能造成登录、MCP 或 Simulator 的身份错配。

## 在调试器中上传 CSR

如果本轮登录会使用 `phone_code` 获取并解密手机号，沙箱 App 需要在 `dbx dev` 的 Web 调试器中上传 CSR。CSR 用于在当前调试会话中登记 ECC P-256 公钥；平台使用该公钥加密手机号，业务 Server 再用同一密钥对的私钥解密。

按以下顺序处理：

1. 在服务端代码仓库中查找现有 `dev.key` / `dev.csr` 或现有密钥目录；如果开发者明确了目录，优先使用该目录。
2. 未找到可用 CSR 时，生成配对文件：

   ```bash
   openssl ecparam -genkey -name prime256v1 -noout -out dev.key
   openssl req -new -key dev.key -out dev.csr -subj "/CN=XXXXX/O=XXXXX"
   ```

   `XXXXX` 由开发者确定。未指定位置时，在服务端代码仓库中选择合适且已忽略的本地密钥目录保存这两个文件。
3. 启动 `dbx dev` 后，打开完整 `web_debugger` URL，把 `dev.csr` 的完整**内容**粘贴到 Web 调试器的“输入证书”框；不要传 `dev.key`、私钥内容或仅传 CSR 文件路径。
4. 确认业务 Server 使用同一密钥对的 `dev.key` 解密手机号，再实际登录验证。

不要为同一个 Web 调试器会话临时生成另一份 CSR，也不要混用不同密钥对的 `dev.csr` 与 `dev.key`。CSR 通过 Web 调试器输入，不要编造 `dbx dev` 命令行参数。

完成后返回 [overview.md](overview.md#设置本地-server-的-openapi-调用域名)，设置业务 Server 的 OpenAPI 调用域名并继续整体调试流程。