feat: 实现 Provider 协议、mock 上游与内嵌 worker #10

New Issue

2026-08-20T18:01:03+08:00

ila commented

2026-08-20 18:01:03 +08:00

基本信息

类型：需求
所属 Epic：#3
所属 MVP / 版本：#4（MVP-0）
阶段：已完成

依赖与并行

前置工单：#7、#8、#9
是否允许与前置工单并行：否
原因：依赖项定义本工单所需的可执行环境、共享模型、接口或已确认设计；未满足时保持待实施，不标记阻塞。

子项目影响

仅影响的子项目 / 交付单元：internal/core/provider、portal worker 组装、mock 上游
是否跨子项目：是
是否修改共享接口或契约：是；连接 core 队列、platform 安全适配器和 ProviderModel
各子项目需要执行的验证：见“验证方式”和验收标准。

原始需求

来源：用户对话；Product-Requirements-Overview、Architecture-and-Code-Map、Business-Rules-and-Glossary
提出时间：2026-08-20
关键原话或脱敏摘要：用户要求“为 MVP-0 的生产实现拆分单元工单”；本工单负责实现 chat/images_edits Provider、mock 上游和 portal 内嵌 worker。

要解决什么

核心、平台和队列完成后，需要由 worker 唯一负责上游调用并把完整 attempts、延迟、错误和结果安全写回；同步提交链路始终不能访问上游。

做什么 / 不做什么

做

实现 chat、images_edits Provider 协议适配，处理 JSON、多图、URL/Base64 结果和受控 extra_body。
MVP-0 选择唯一启用 ProviderModel；解密 Provider Key 后只通过 SSRF 安全 Client 请求。
worker 认领任务、渲染并落库 prompt、调用上游、保存结果/缩略图，再用 lease token CAS 完成。
分类并脱敏 429/5xx/超时/连接、400/401/策略拒绝；MVP-0 可重试类也不换家。
提供本地 mock 上游覆盖文本、图片和全部错误分类；实现启动与优雅退出。

不做

不在同步 handler 中调用上游，不用真实额度做自动测试。
不实现多 Provider、权重、熔断、故障转移、images 或 gemini。
不把明文 Key、完整上游响应或真实用户输入写日志。

已确认方案

Provider 协议位于 core 抽象/适配边界，网络连接必须复用 #8 安全实现。
rendered_prompt 在调用前落库；每次 attempt 含 ProviderModel、分类结果、耗时和时间。
worker 收到退出信号后停止取新任务并等待在途任务到期限。

预计修改文件：

internal/core/provider/
portal/worker/ 或等价组装目录
internal/platform 中必要但不改变安全边界的协议适配
testdata/测试内 mock 上游

需求变化记录

无。实现中若范围、接口、数据、依赖、验收或风险发生变化，必须先更新本工单；改变已确认结果时重新等待用户确认。

设计与原型门禁

修改类型：非 UI
所需设计证据：已确认的架构、数据、安全或流程设计；不要求 UI 原型
事实来源：核心 Wiki 与父工单 #4
状态：已确认；具体实现差异仍须按工单变化规则处理
无需 UI 原型原因：本工单不改变用户界面

文档影响

不影响长期文档
按实际变化更新 Project-Profile、Architecture-and-Code-Map、Local-Development-and-Verification、Deployment-and-Operations 或 Business-Rules-and-Glossary
Wiki 先改、在线回读后再同步 docs/，不得直接维护镜像

交付文档影响

无交付文档影响，原因：内部实现任务；若实际改变部署、配置或支持方式，执行前更新本项
更新已有交付文档
新增交付文档

验收标准

mock chat 和 images_edits 各成功一次，文本/图片结果和缩略图正确落库/落盘。
rendered_prompt、attempts、latency、ProviderModel 和失败 error 字段完整。
429/5xx/超时/连接与 400/401/策略拒绝分类测试逐项通过，MVP-0 不发生换家。
所有请求、redirect 和结果 URL 经过安全 Client，无同步 handler 上游调用。
陈旧 token 最终写入 0 行且清理自己的临时结果；优雅退出行为通过。
测试不访问真实 Provider，日志和响应无明文密钥。

验证方式

go test ./internal/core/provider/... ./portal/worker/...
go test -race ./...
mock HTTP 上游矩阵测试
数据库 attempts/rendered_prompt/结果记录断言
日志敏感信息扫描

未执行或因环境不足无法执行的验证必须如实回写，不得把预期结果记为通过。

风险和回退

高风险：协议差异、错误分类或 CAS 顺序错误会造成泄露、重复调用或数据覆盖。
风险：上游结果 URL 可能绕过安全下载；只有 #8 已验证下载器可用。
回退：停止 worker 并回退本工单提交；保留任务记录供排障，不重试真实上游。

实施与验证证据（2026-08-21）

实现提交：d61c80265b40c542e001c4c522309b48674ea60d；文档提交：72a37c0f9e81bb297f98a813f3b3d240529e45b7，均已推送到 origin/main。
本机隔离 MySQL 8.4.8 完成 chat 与 images_edits 集成；断言 rendered_prompt、attempt ProviderModel/latency、output、原图和缩略图。
AES-GCM Provider Key 解密、Base64/URL 图片结果、全部错误分类、跨域鉴权 redirect、陈旧 token 清理和优雅退出均有自动测试。
go test ./...、go vet ./...、go test -race -count=1 ./...、严格 Harness 与 Wiki 镜像检查通过；未调用真实 Provider。
核心 Wiki revision：Architecture 47686aa767849c6ecffc5db37a76a24564feb5e6；Local Development 0f7d68926b23995be4481f05218484be1301a780；Deployment 40b115d8da2f8b7d4e01783eb47a73659cc4d67f。
任务归档：Task-10-实现-Provider-协议、mock-上游与内嵌-worker，revision 42db1274419b8f7a7bf0db80b504cfd889f884db。
数据库 fixture 已清理，Provider 已恢复无认证 mock 配置。工单保持开启，等待人工验收。

验收结论

用户于 2026-08-21 明确确认 #10 验收通过。
MVP-0 单元验收文档提交：919e11f，已推送到 main。
任务归档 revision：5efc1c9ac0b8。

## 基本信息 - 类型：需求 - 所属 Epic：#3 - 所属 MVP / 版本：#4（MVP-0） - 阶段：已完成 ## 依赖与并行 - 前置工单：#7、#8、#9 - 是否允许与前置工单并行：否 - 原因：依赖项定义本工单所需的可执行环境、共享模型、接口或已确认设计；未满足时保持待实施，不标记阻塞。 ## 子项目影响 - 仅影响的子项目 / 交付单元：internal/core/provider、portal worker 组装、mock 上游 - 是否跨子项目：是 - 是否修改共享接口或契约：是；连接 core 队列、platform 安全适配器和 ProviderModel - 各子项目需要执行的验证：见“验证方式”和验收标准。 ## 原始需求 - 来源：用户对话；Product-Requirements-Overview、Architecture-and-Code-Map、Business-Rules-and-Glossary - 提出时间：2026-08-20 - 关键原话或脱敏摘要：用户要求“为 MVP-0 的生产实现拆分单元工单”；本工单负责实现 chat/images_edits Provider、mock 上游和 portal 内嵌 worker。 ## 要解决什么核心、平台和队列完成后，需要由 worker 唯一负责上游调用并把完整 attempts、延迟、错误和结果安全写回；同步提交链路始终不能访问上游。 ## 做什么 / 不做什么 ### 做 - 实现 `chat`、`images_edits` Provider 协议适配，处理 JSON、多图、URL/Base64 结果和受控 `extra_body`。 - MVP-0 选择唯一启用 ProviderModel；解密 Provider Key 后只通过 SSRF 安全 Client 请求。 - worker 认领任务、渲染并落库 prompt、调用上游、保存结果/缩略图，再用 lease token CAS 完成。 - 分类并脱敏 429/5xx/超时/连接、400/401/策略拒绝；MVP-0 可重试类也不换家。 - 提供本地 mock 上游覆盖文本、图片和全部错误分类；实现启动与优雅退出。 ### 不做 - 不在同步 handler 中调用上游，不用真实额度做自动测试。 - 不实现多 Provider、权重、熔断、故障转移、`images` 或 `gemini`。 - 不把明文 Key、完整上游响应或真实用户输入写日志。 ## 已确认方案 - Provider 协议位于 core 抽象/适配边界，网络连接必须复用 #8 安全实现。 - `rendered_prompt` 在调用前落库；每次 attempt 含 ProviderModel、分类结果、耗时和时间。 - worker 收到退出信号后停止取新任务并等待在途任务到期限。预计修改文件： - `internal/core/provider/` - `portal/worker/` 或等价组装目录 - `internal/platform` 中必要但不改变安全边界的协议适配 - `testdata`/测试内 mock 上游 ## 需求变化记录无。实现中若范围、接口、数据、依赖、验收或风险发生变化，必须先更新本工单；改变已确认结果时重新等待用户确认。 ## 设计与原型门禁 - 修改类型：非 UI - 所需设计证据：已确认的架构、数据、安全或流程设计；不要求 UI 原型 - 事实来源：核心 Wiki 与父工单 #4 - 状态：已确认；具体实现差异仍须按工单变化规则处理 - 无需 UI 原型原因：本工单不改变用户界面 ## 文档影响 - [ ] 不影响长期文档 - [x] 按实际变化更新 Project-Profile、Architecture-and-Code-Map、Local-Development-and-Verification、Deployment-and-Operations 或 Business-Rules-and-Glossary - Wiki 先改、在线回读后再同步 `docs/`，不得直接维护镜像 ## 交付文档影响 - [x] 无交付文档影响，原因：内部实现任务；若实际改变部署、配置或支持方式，执行前更新本项 - [ ] 更新已有交付文档 - [ ] 新增交付文档 ## 验收标准 - [x] mock `chat` 和 `images_edits` 各成功一次，文本/图片结果和缩略图正确落库/落盘。 - [x] `rendered_prompt`、attempts、latency、ProviderModel 和失败 error 字段完整。 - [x] 429/5xx/超时/连接与 400/401/策略拒绝分类测试逐项通过，MVP-0 不发生换家。 - [x] 所有请求、redirect 和结果 URL 经过安全 Client，无同步 handler 上游调用。 - [x] 陈旧 token 最终写入 0 行且清理自己的临时结果；优雅退出行为通过。 - [x] 测试不访问真实 Provider，日志和响应无明文密钥。 ## 验证方式 - `go test ./internal/core/provider/... ./portal/worker/...` - `go test -race ./...` - mock HTTP 上游矩阵测试 - 数据库 attempts/rendered_prompt/结果记录断言 - 日志敏感信息扫描未执行或因环境不足无法执行的验证必须如实回写，不得把预期结果记为通过。 ## 风险和回退 - 高风险：协议差异、错误分类或 CAS 顺序错误会造成泄露、重复调用或数据覆盖。 - 风险：上游结果 URL 可能绕过安全下载；只有 #8 已验证下载器可用。 - 回退：停止 worker 并回退本工单提交；保留任务记录供排障，不重试真实上游。 ## 实施与验证证据（2026-08-21） - 实现提交：`d61c80265b40c542e001c4c522309b48674ea60d`；文档提交：`72a37c0f9e81bb297f98a813f3b3d240529e45b7`，均已推送到 `origin/main`。 - 本机隔离 MySQL 8.4.8 完成 chat 与 images_edits 集成；断言 rendered_prompt、attempt ProviderModel/latency、output、原图和缩略图。 - AES-GCM Provider Key 解密、Base64/URL 图片结果、全部错误分类、跨域鉴权 redirect、陈旧 token 清理和优雅退出均有自动测试。 - `go test ./...`、`go vet ./...`、`go test -race -count=1 ./...`、严格 Harness 与 Wiki 镜像检查通过；未调用真实 Provider。 - 核心 Wiki revision：Architecture `47686aa767849c6ecffc5db37a76a24564feb5e6`；Local Development `0f7d68926b23995be4481f05218484be1301a780`；Deployment `40b115d8da2f8b7d4e01783eb47a73659cc4d67f`。 - 任务归档：`Task-10-实现-Provider-协议、mock-上游与内嵌-worker`，revision `42db1274419b8f7a7bf0db80b504cfd889f884db`。 - 数据库 fixture 已清理，Provider 已恢复无认证 mock 配置。工单保持开启，等待人工验收。 ## 验收结论 - 用户于 2026-08-21 明确确认 #10 验收通过。 - MVP-0 单元验收文档提交：`919e11f`，已推送到 `main`。 - 任务归档 revision：`5efc1c9ac0b8`。

ila referenced this issue

2026-08-20 18:01:08 +08:00

mvp: MVP-0 单上游安全异步生成闭环 #4

ila referenced this issue

2026-08-20 18:01:09 +08:00

epic: chorus 图文生成服务交付 #3

ila referenced this issue from a commit

2026-08-21 00:19:47 +08:00

feat: add provider protocols and embedded worker (#10)

ila referenced this issue from a commit

2026-08-21 00:19:47 +08:00

docs: record provider worker boundaries (#10)