lixi
6990709124
CI / ai-gates (push) Successful in 47s
patbond-ai 纳入发布语义（ADR-023 §12）。本仓是四仓中唯一直接持有 AI 服务商凭证的仓库，因此不得成为唯一没有防泄漏门禁的仓库——建仓即配齐， 不等代码落地。 - .gitea/workflows/ci.yml：ai-gates 作业，push(dev) + pull_request 双触发， 与另三仓同构。Secret scan 为第一个 step 且先于任何依赖安装。 pip 走腾讯云镜像（与 patbond-doc 装 mkdocs 同一策略）。 门禁命令 ruff format --check / ruff check / pytest，对应 flutter 仓的 dart format + analyze + test 三步。requirements*.txt 落地前只装工具本身， 使 CI 自建仓第一天即为绿；pytest 无测试时退出码 5 视为通过。 - scripts/check-secrets.sh：四仓同构副本，md5 640994c12bfa78b4512e872d709ed685。 已覆盖 AI 服务商密钥形态（sk-ant- / sk- / sk-proj- / sk-svcacct-）与 api_key/auth_token 实值赋值——本仓正是这些规则的主要适用对象。 - scripts/hooks/pre-commit：与另三仓同构。四仓 core.hooksPath 均已启用， ADR-023 §12 登记的「防泄漏第一层从未生效」至此闭环。 实测验证：含 5 种真实凭证形态的 .env 夹具被钩子拦下，提交未产生。 - .gitignore：Python 产物与工具缓存；凭证载体（.env / credentials* / *.pem / *.key）一律排除，占位样例走 .env.sample（对应脚本的 DENY_NAME_OK）。 - README.md：职责边界（不访问数据库、不持有对象存储凭证、对上游同步异步 一律对外呈现为异步）、与 Java 侧的接口约定（REST 非 gRPC、独立 openapi-internal.yaml、服务身份 JWT 独立密钥对、请求体不含 userId）、 本地门禁命令与凭证纪律。细节以 ADR-023 为准。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
59 lines
2.7 KiB
Markdown
59 lines
2.7 KiB
Markdown
# patbond-ai
|
||
|
||
Patbond 的 AI 生成服务（Python）。负责调用 AI 服务商 API 完成图片与视频生成，
|
||
是四仓中唯一直接持有 AI 服务商凭证的仓库。
|
||
|
||
架构与边界的完整决策见 **patbond-doc `docs/architecture/decisions.md` ADR-023**。
|
||
以下为要点，改动前请以 ADR 原文为准。
|
||
|
||
## 职责边界
|
||
|
||
- **只负责调用 AI 服务商 API。** 不访问数据库——生成任务状态的唯一事实来源是
|
||
Java 侧的 `creation.generation_jobs`。
|
||
- **不持有对象存储凭证。** 产物由 Java 下发预签名 PUT 地址，本服务直传后回报，
|
||
再由 Java 核实并建 `media.assets` 行（即客户端两步上传，本服务站在客户端位置）。
|
||
- **对上游同步或异步一律对外呈现为异步**：`submit` 立即返回任务 id，同步型
|
||
服务商（长连接等待返回）在本服务内部以后台任务承载。这样 Java 侧无长连接占线程，
|
||
且 `provider_request_id` 立即可得，超时不再产生「是否已扣费」的歧义。
|
||
|
||
## 与 Java 侧的接口
|
||
|
||
- 传输为 **REST（JSON）**，非 gRPC（理由见 ADR-023 §4：避免引入第二套无门禁契约体系）。
|
||
- 契约为本仓内独立的 **`openapi-internal.yaml`**，独立版本号，
|
||
**不进** patbond-api 的四模块快照锁，**也不写入**面向客户端的 `openapi.yaml`。
|
||
- 鉴权为 **服务身份 JWT**（独立密钥对，非用户 token 转发）：本服务强制校验
|
||
`aud=patbond-ai` 与 `typ=service`。
|
||
- Java 主动轮询本服务查询进度；回调是将来的可选优化，当前不启用。
|
||
- 请求体**不含 `userId`**（数据最小化）：完成工作只需 `jobId`、生成参数与预签名上传地址。
|
||
|
||
## 本地门禁
|
||
|
||
与 CI 同一套命令（`.gitea/workflows/ci.yml`）：
|
||
|
||
```bash
|
||
sh scripts/check-secrets.sh --all # 凭证防泄漏全量自查
|
||
ruff format --check .
|
||
ruff check .
|
||
pytest -q
|
||
```
|
||
|
||
**每人每仓启用一次** pre-commit 防泄漏钩子：
|
||
|
||
```bash
|
||
git config core.hooksPath scripts/hooks
|
||
```
|
||
|
||
`scripts/check-secrets.sh` 是四仓同构副本，**调整规则时四仓同步提交**。
|
||
它覆盖 AI 服务商密钥形态（`sk-ant-`、`sk-`/`sk-proj-`/`sk-svcacct-`）与
|
||
`api_key`/`auth_token` 实值赋值——本仓正是这些规则的主要适用对象。
|
||
|
||
## 凭证纪律
|
||
|
||
真实密钥**只允许存在于被 gitignore 的文件中**（`.env`），占位样例进 `.env.sample`。
|
||
拦下真实凭证时的第一动作是**去服务商控制台轮换/禁用该密钥**，然后才是清理提交。
|
||
|
||
## 分支与发布
|
||
|
||
`dev` 直推 + CI 绿，`main` 经 PR 合并。本仓纳入四仓 tag 同步与发布回归
|
||
（ADR-023 §12）。发布流程见 patbond-doc `docs/development/releases.md`。
|