From 86d63ab1cb7bd4b297b686a25c458ea4849aa5c4 Mon Sep 17 00:00:00 2001 From: Lixi20 Date: Sun, 20 Sep 2026 12:19:50 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E6=AD=A3=204762358=20?= =?UTF-8?q?=E7=9A=84=E6=8F=90=E4=BA=A4=E8=AE=B0=E5=BD=95=E2=80=94=E2=80=94?= =?UTF-8?q?=E8=AF=A5=E6=8F=90=E4=BA=A4=E5=AE=9E=E9=99=85=E5=8C=85=E5=90=AB?= =?UTF-8?q?=20AI=20=E6=9C=8D=E5=8A=A1=E5=88=86=E5=B1=82=E9=87=8D=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **这是一条记录补正，不含代码改动。** 4762358 的提交信息只写了「凭证扫描放行依赖注入传参 + 四仓口径更正」，但它实际 包含了 patbond-ai 的整个分层重构（22 个文件、约 1900 行增、约 700 行删）。 成因：前一次提交尝试被 pre-commit 钩子拦下（它正确地拦了 assembly.py 里 `api_key=volcengine.api_key` 这个形态），但 `git add -A` 已经把重构文件留在 暂存区；随后修规则的那次提交只 `git add` 了脚本，却把暂存区里既有的内容一并 提交了。提交前未核对 `git status` 的暂存清单——正是 git-workflow.md「禁止事项」 第一条要求逐一核对的那一步。 不用 amend 重写历史：dev 是共享分支，git-workflow.md 明确禁止对其 force push。 故以本条补正记录说明 4762358 的真实内容，其完整说明如下。 --- **refactor(ai): 按高内聚低耦合分层重构 + 集中配置（100 测试）** 原先 seedance.py 一个文件里混了 HTTP 传输、鉴权、厂商 DTO、状态映射与视频业务， 接第二个火山接口（图片/语音）时只能整段再抄一遍。按依赖单向向内重切四层： config.py → assembly.py → providers/ → domain/ - **domain/generation.py**：与服务商无关的领域模型，对厂商与 httpx **零依赖** ——「换供应商不动上层」的支点。判断归属的准绳是「换一家供应商它还在吗」： Retry/UserFacing 描述 Worker 与客户端该怎么做，故在领域层；expired 状态、 QuotaExceeded 这类码是火山特有的，故在适配层。GenerationResult 拒绝 「FAILED 但无 Failure」与「SUCCEEDED 但无 asset_url」——半个失败态放给上层 只会让它盲目重试或盲目放弃。 - **providers/base.py + registry.py**：能力抽象与 provider_code 分发，对具体 供应商零依赖。registry 拒绝重复注册（静默覆盖会让「哪个实例在处理任务」 取决于注册顺序）。 - **providers/volcengine/** 拆四块：client.py（HTTP 传输与鉴权，**不认识 「视频」**，以后接火山图片/语音接口复用它——这是拆它的全部理由；并修正连接 归属：只关自己创建的连接池）、errors.py（火山码 → 领域 Failure，补 message 透传）、models.py（厂商 DTO 与常量，base URL 从 config 收拢至此）、 video.py（仅视频业务）。 - **config.py**：集中配置。非法值响亮失败而不静默回落；厂商区间 [3600,259200] 启动时校验；密钥绝无默认值。另加 .env.sample。 - **assembly.py**：装配根，唯一同时知道配置与具体供应商的地方。缺凭证的供应商 被跳过而非让启动失败。 - **tests/test_layering.py**：用 AST 断言架构约束本身。分层的价值全在「换供应商 不动上层」，而这个性质只要有人无意加一行 import 就会悄悄失效——靠纪律守不住， 靠测试才守得住。写完它当即抓到一处真问题：厂商 base URL 硬编码在 config.py。 测试 58 → 100，全部离线。另两处新行为：succeeded 但缺 video_url 判为可重试失败； asset_url 随 URL 给出 24 小时时效，使上层没有理由把厂商地址当永久存储。 Co-Authored-By: Claude Opus 5 (1M context)