# API 兼容性与排障

首版验证日期：2026-10-01（单元测试 + 真实宿主闭环）。真实宿主与真实模型闭环已于同日通过，记录见 [真实模型验证](real-model-validation.md)。DSH API 仍处于预览阶段，版本变化可能需要修改接入层。

| 项目 | 首版支持/验证情况 |
|---|---|
| DSH | Web `0.2.0-rc.2` 桌面宿主（live `desktop` profile）：真实安装、宿主条目 active、GUI 面板加载、登记/快照/发送/重跑/验收/导出全流程已验证 |
| 后端项目 | 任意语言：源码快照覆盖 ts/js/mjs/cjs/py/go/java/rs/rb/php/c/cpp/cs/kt/swift/scala/sql 等扩展名及常见构建清单 |
| Node | 声明支持 22.x 的 22.19+ 或 24+；开发与验证实际使用 Node 24.21.0 |
| 系统 | Windows 开发与验证；其他系统未验证 |
| 界面语言 | 中文；README 提供中英双语 |
| 真实模型 | 2026-10-01 真实 DeepSeek **V4-Flash（Max）**：改后端两处 → 重跑出现结构化 diff → 3/3 逐项验收 → 导出报告；模型环节未 mock |

## 支持范围（首版）

- **端点**：http/https、hostname 为 `127.0.0.1` / `localhost` / `[::1]`、**必须带显式端口**、不允许 URL 内嵌账号密码。最多 20 个端点，方法 GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS，可选请求头（≤30 对）与请求体（≤64 KB）。
- **响应**：状态码 + 头（≤40 个）+ 响应体。JSON 体做字段级 diff；文本体做行级 patch diff；二进制与超 5 MB 的体标记为 `unsupported`/`body-too-large`，不参与 diff。请求超时默认 10 秒。
- **源码快照**：500 文件 / 单文件 512 KB / 合计 5 MB 上限，超出明确报错。快照用于「代码 diff 并排」与「源码变化后必须重跑」校验；它不检查二进制资源与未纳入范围的文件。
- **报告**：Markdown + 单文件 HTML（内嵌 diff，XSS 转义 + CSP `default-src 'none'`），保存于 `.dsh-apirevise/<round-id>/`。

## 限制（首版明确不做）

- **不做流量捕获代理**：端点由用户手工登记，无法自动发现请求（v2 方向）。
- **不做认证态浏览器/登录态**：请求不携带浏览器 cookie，只使用用户登记的请求头。
- **不做定时回归/CI 集成**：重跑只能手动触发。
- **不做测试用例运行器**：这是 dsh-test-workbench / dsh-test-runner 的领地。
- **不做通过/失败判定**：diff 只呈现状态码/字段/数值的旧值→新值事实；「验收」是人类的决定，插件不宣称“接口一定没坏”。
- **不保存完整响应到云端**：一切记录都在项目内 `.dsh-apirevise/`，请加入 `.gitignore`。

## 没有看到入口

确认插件已加入 `web` profile 并重启 `dsh web`，再选择一个有项目目录的会话。右下角应出现 **API 接口验收台**。自定义 `DSH_HOME` 时，安装插件与启动 DSH 必须使用同一个值。

## 快照失败：连接被拒绝 / 超时

先确认后端服务正在本机带端口的地址上运行（例如 `http://127.0.0.1:3000`）。插件要求显式端口；`localhost` 与 `127.0.0.1` 均可用。网络错误会记录在该接口的响应里（状态码显示「无响应」），不会中断其余接口的快照。

## “源码变化，需重新重跑”

重跑后的源码又发生变化时，旧对比不能用于验收（接受的是明确的采集版本）。等待 DSH 完成改稿后点击 **重跑对比**；重跑会重新请求全部接口并把所有接口的验收重置为待验收。

## 发送失败或模型没有按要求修改

先确认 DSH 的模型配置与普通聊天可用。API Revise 把目标、接口清单与后续反馈发送给会话，不管理模型密钥，不承诺模型改稿质量。请求失败时会显示错误；可复制请求到 DSH 对话中排查。

## 历史记录、请求和报告在哪里

```text
<后端项目>/.dsh-apirevise/<round-id>/
  round.json     # 轮次记录：接口清单、基线/候选快照（含源码与响应）、验收决定
  request.md     # 点击发送时准备的请求
  report.md      # Markdown 报告
  report.html    # 单文件 HTML 报告（内嵌 diff，可分享）
```

同一项目的不同 DSH 会话不会互相显示验收轮次。记录不做自动清理；确定不再需要的旧轮次可手工删除。

## Windows 已知环境问题

DSH 的受限沙箱会拦截 piped 子进程 spawn（`spawn EPERM`），模型改完后的一次性构建批准属正常流程；这是 DSH 运行环境行为，API Revise 不会替用户关闭沙箱。