From a65711b90077c9963491b4c2b6ee9ac0f6aad45b Mon Sep 17 00:00:00 2001
From: UniDesk <dev@unidesk.local>
Date: Fri, 15 May 2026 16:01:15 +0000
Subject: [PATCH] docs: add pipeline-model-proxy reference for D601 model proxy
 architecture

---
 AGENTS.md                              |   1 +
 docs/reference/pipeline-model-proxy.md | 109 +++++++++++++++++++++++++
 2 files changed, 110 insertions(+)
 create mode 100644 docs/reference/pipeline-model-proxy.md

diff --git a/AGENTS.md b/AGENTS.md
index d8ccb630..881ce77e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -56,4 +56,5 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 - `docs/reference/constar-d601.md`：D601 上 ConStart/constar 固件工作区的 UniDesk SSH 入口、WSL skill wrapper、Keil 编译下载和串口/JSON-RPC 验证简要引导。
 - `docs/reference/oa-event-flow.md`：统一 OA 事件流微服务、事件表、tag 订阅、Trace/STEP 统计中心和前端可见性规则。
 - `docs/reference/pipeline-oa-event-flow.md`：Pipeline/OA 事件流、审核/无审核流转、单步调试、甘特图渲染和最终去残留规则。
+- `docs/reference/pipeline-model-proxy.md`：Pipeline v2 model proxy 链路架构、D601 宿主 proxy 服务部署、harness token 注入规则和 smoke test 验证流程。
 - `reference`：兼容旧路径的符号链接，指向 `docs/reference/`。
diff --git a/docs/reference/pipeline-model-proxy.md b/docs/reference/pipeline-model-proxy.md
new file mode 100644
index 00000000..ba8a3941
--- /dev/null
+++ b/docs/reference/pipeline-model-proxy.md
@@ -0,0 +1,109 @@
+# Pipeline v2 Model Proxy Architecture
+
+Pipeline v2 procedure runner 通过 model proxy 链路将容器内 OpenCode 的模型请求路由到外部 API 提供商。本文档记录 proxy 链路的稳定架构、各 model 组件的差异和 D601 宿主服务部署约束。
+
+## Proxy Chain 总体架构
+
+```text
+OpenCode (container)
+  ↓ HTTP (127.0.0.1:17655)
+In-container model proxy (opencodeContainerHarness)
+  ↓ HTTP/HTTPS
+Upstream origin (per model config)
+  ↓ (if host proxy)
+External API provider (HTTPS)
+```
+
+每个 model 组件在 `config.json` 的 `proxy` 字段声明 in-container proxy 的监听端口和上游地址。OpenCode 的 provider config 中 `baseUrl` 固定指向 `http://127.0.0.1:{proxy.port}/{path}`，由 harness 在容器启动时写入。
+
+In-container proxy 的职责：
+- 注入 auth token（从容器环境变量读取，按 `ANTHROPIC_AUTH_TOKEN` → `ANTHROPIC_API_KEY` → `OPENAI_API_KEY` 优先级查找）
+- 429 rate limit 自动重试与 quota pause 计时（暂停时间不计入 node active timeout）
+- 请求/响应透传（streaming 兼容）
+
+## Model 组件 Proxy 配置对比
+
+| Model | proxy.upstreamOrigin | 宿主服务 | Auth env |
+|-------|---------------------|----------|----------|
+| `minimax-m27` | `https://api.minimaxi.com` | 无（容器直连） | `ANTHROPIC_AUTH_TOKEN` |
+| `gpt-5.5` | `http://host.docker.internal:17680` | `hyueapi-proxy.service` | `OPENAI_API_KEY` |
+
+### minimax-m27（直连模式）
+
+容器内 proxy 直接 HTTPS 连接 `api.minimaxi.com`，无需宿主中间层。适用于上游 API 不需要 Host header 覆盖或 TLS SNI 特殊处理的场景。
+
+### gpt-5.5（宿主 proxy 模式）
+
+容器内 proxy 通过 Docker `host.docker.internal` 连接宿主 port 17680 的 HTTP reverse proxy，由宿主 proxy 完成 HTTP→HTTPS 升级和 `Host: hyueapi.com` header 注入。
+
+两跳设计原因：hyueapi.com 使用 Cloudflare，要求 TLS SNI 与 Host header 匹配；容器内 Node.js HTTP proxy 只做 HTTP 转发，TLS 终止由宿主 proxy 完成，避免容器内处理 Cloudflare 证书验证和 SNI 问题。
+
+## D601 宿主 hyueapi-proxy 服务
+
+部署路径：`~/pipeline/services/hyueapi-proxy/proxy.mjs`
+
+systemd user service：`~/.config/systemd/user/hyueapi-proxy.service`
+
+```bash
+# 状态检查
+systemctl --user status hyueapi-proxy.service
+
+# 重启
+systemctl --user restart hyueapi-proxy.service
+
+# 验证（需要 auth）
+KEY=$(cat ~/pipeline/.state/secrets/gpt-5.5/OPENAI_API_KEY)
+curl -H "Authorization: Bearer $KEY" http://127.0.0.1:17680/v1/models
+```
+
+服务行为：
+- 监听 `0.0.0.0:17680`（容器通过 `host.docker.internal` 访问）
+- 上游 `hyueapi.com:443`（HTTPS）
+- 覆盖 `Host` header 为 `hyueapi.com`
+- 透传所有其他 header（包括 `Authorization`）
+- 无认证、无缓存、无日志（生产态）
+
+## Harness Token 注入规则
+
+`scripts/src/opencodeContainerHarness.ts` 中 in-container proxy 的 token 查找顺序：
+
+```
+ANTHROPIC_AUTH_TOKEN → ANTHROPIC_API_KEY → OPENAI_API_KEY
+```
+
+model 组件的 `auth.envNames` 声明注入到容器的环境变量名。对于 OpenAI-compatible 提供商（如 gpt-5.5），`envNames` 必须包含 `OPENAI_API_KEY`，harness 才能在 proxy 层自动注入 Bearer token。
+
+## Smoke Test 验证
+
+每个 model 组件应配套一个 smoke-test pipeline 用于验证端到端连通性：
+
+```text
+components/pipeline/gpt-5.5-smoke-test/config.json
+components/procedure/gpt-5.5-smoke-connectivity/config.json
+```
+
+Smoke test 验证链路：
+1. 容器启动，harness 写入 OpenCode provider config 并启动 in-container proxy
+2. OpenCode server 启动，harness 创建 session 并发送 prompt
+3. 模型通过 proxy chain 完成请求（`POST /v1/responses`）
+4. 模型执行任务并通过 OA skill 提交 `benchmark-repair-result-v1`
+5. Harness 验证 OA submission 存在且 container exit code = 0
+
+运行方式：
+```bash
+cd ~/pipeline
+npx tsx scripts/pipeline-cli.ts procedure start \
+  --pipeline gpt-5.5-smoke-test \
+  --node smoke \
+  --task "Connectivity test: ..."
+```
+
+## 新增 Model 组件检查清单
+
+1. 创建 `components/model/{id}/config.json`，声明 `opencode`、`auth`、`proxy` 和 `runtimeEnv`
+2. 创建 `.state/secrets/{id}/{ENV_NAME}` 存放 API key
+3. 如果上游需要 Host header 覆盖或 TLS 特殊处理，部署宿主 proxy 服务并将 `proxy.upstreamOrigin` 指向 `http://host.docker.internal:{port}`
+4. 确认 `auth.envNames` 中的变量名在 harness token 查找链中（当前支持 `ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`）
+5. 创建 smoke-test pipeline 和 procedure 组件
+6. 运行 smoke test 验证端到端连通性
+7. 提交到 pipeline 仓库