# v0.2 DeepSeek/Moon Bridge 稳定外部服务规格

`hwlab-deepseek-proxy` 是 v02 Code Agent `deepseek` provider profile 的内部模型桥，Service 端口 `4000`。它由 repo-owned Responses bridge 容器和稳定外部 `moonbridge` 容器组成。

## 在系统中的职责划分

- 为 `hwlab-cloud-api` 提供 OpenAI Responses 兼容入口 `/v1/responses`，内部转到 Moon Bridge，再转 DeepSeek upstream。
- 只服务 Code Agent provider profile，不向浏览器或普通用户直接暴露。
- 读取 `hwlab-v02-code-agent-provider/openai-api-key` 作为 `DEEPSEEK_API_KEY` 渲染 Moon Bridge config；Secret 更新后必须滚动本 Deployment。
- DeepSeek 余额不足、外部额度耗尽或该 provider profile 明确不可用时，Code Agent 非 DeepSeek 专项验收可以临时切到 `minimax-m3` 继续闭环；issue/验收评论必须写明实际 `providerProfile=minimax-m3`，不得把它记为 DeepSeek 通道通过。

## 内部架构

- `ConfigMap/hwlab-deepseek-proxy-config` 提供 `render-config.sh`，initContainer 把 `DEEPSEEK_API_KEY` 写入 `/config/config.yml`。
- `responses-bridge` 容器运行 `cmd/hwlab-deepseek-responses-bridge/main.ts`，监听 `4000`，处理 `/health`、`/health/readiness`、`/v1/models` 和 `/v1/responses`。
- `moonbridge` 容器监听 `4001`，读取渲染后的 config，负责 DeepSeek provider 调用和模型列表。
- bridge 会解压 zstd body，并过滤 Responses tools 中 Moon Bridge 不支持的 tool type。

## API 接口说明

| 接口 | 说明 |
| --- | --- |
| `GET /health`、`GET /health/live`、`GET /health/liveliness` | bridge 进程存活。 |
| `GET /health/readiness` | 探测 Moon Bridge `/health/readiness` 或 `/v1/models`，失败返回 degraded。 |
| `GET /v1/models` | 返回 Codex/Responses 可消费的模型列表。 |
| `POST /v1/responses` | `hwlab-cloud-api` deepseek profile 的模型调用入口。 |

## 测试规格

## T1

阅读 docs/reference/spec-v02-deepseek-proxy.md，然后用 cli 手动测试以下内容：访问 `hwlab-deepseek-proxy:4000/health/readiness` 和 `/v1/models`，确认 ready 或明确 degraded 原因。

## T2

阅读 docs/reference/spec-v02-deepseek-proxy.md，然后用 cli 手动测试以下内容：通过 `hwlab-cloud-api /v1/agent/chat` 指定或默认 deepseek profile 做短连接聊天，确认 result completed 且 reply 非空。

## T3

阅读 docs/reference/spec-v02-deepseek-proxy.md，然后用 cli 手动测试以下内容：Secret 变更后必须滚动 `hwlab-cloud-api` 和 `hwlab-deepseek-proxy`，验证只输出 SecretRef、bytes 和 hash，不输出值。

## 规格的实现情况

| 规格项 | 状态 | 说明 |
| --- | --- | --- |
| Responses bridge | 已实现 | `/v1/responses`、`/v1/models` 和 readiness 已实现。 |
| Moon Bridge sidecar | 已实现 | 外部稳定镜像在同 Pod 运行。 |
| Secret 渲染边界 | 已实现 | initContainer 渲染 config；需 rollout 才生效。 |
| provider auth 真实验收 | 已实现 | 通过 cloud-api 短连接聊天判定。 |
| 多 provider 动态切换 UI | 未完全实现 | cloud-api 支持 profile，完整用户级策略仍待产品化。 |

