feat: unify provider factory, protocol surface and credential boundary

[MisonL]

目的

把 provider 层从「各渠道各自为政的调用逻辑」重构为统一工厂 + 抽象请求模型 + 显式协议，并同步收紧凭证边界与失败语义。分支覆盖 feat/api-channel-integration 的 29 个提交，对应 CHANGELOG.md 的 1.4.0。

主要解决的问题：

1. 协议能力不可见 —— 渠道支不支持 /responses、能不能发 Ark 专属块，此前只能读实现。现在由 src/providers/factory.py 声明能力、抽象接口校验，protocol_status() 可查询。
2. 本地 SDK 资源被误发 —— 非官方 /responses 端点会被当成官方 OpenAI 放行 SDK 专属资源。现在要求 options.server_verified_protocols 显式登记，未登记时工厂、Provider 和资源 Facade 均在请求前拒绝。
3. 凭证可能落到日志 —— 模型级 options 与请求级扩展此前可携带密钥、请求头、query 或 Base URL 覆盖。现在由 src/utils/security.py 在配置、请求、日志三个边界校验与脱敏。
4. 失败被静默掩盖 —— 凭证/SDK/远端调用失败时返回空 embedding、零分 rerank 或占位回答。现在统一显式报错。

影响范围

86 个文件，+34715 / -4312（其中 uv.lock 占 +3583）。

范围	内容
src/providers/ (16)	统一工厂、抽象请求模型、四类线协议适配、原生资源 Facade、SDK 深度适配
src/utils/ (4)	凭证边界与日志脱敏、base_url 升级提示、内置默认值修正
src/services/ (5) src/runtime/ (2)	服务分层与入口重构
src/retrieval/ src/etl/ (7)	注解现代化、死代码清理、embedding 兼容性硬校验
tests/ (15)	协议适配、SDK 能力、凭证边界、Rerank 契约、失败语义、快照兼容性回归
docs/ (4) CHANGELOG.md README.md AGENTS.md	协议选择、options 边界、原生资源入口、Vertex ADC、模型生命周期

破坏性变更（详见 CHANGELOG「移除与调整」）：

• 移除 Dify 上游子模块；src/etl/、src/retrieval/ 移植代码继续遵守 DIFY_LICENSE 并保留上游版权声明。
• 移除 iFlow 渠道及其配置示例；移除 qwen rerank 示例（该渠道不提供 rerank，调用时显式报错）。
• Qwen Base URL 改为 compatible-mode/v1，Volcengine Base URL 改为 ark.cn-beijing.volces.com/api/v3。旧值会在配置加载时给出显式升级警告。
• 发布脚本新增目标环境校验，--target 与主机不匹配时在清理构建产物前失败。

配置与生成数据影响

• 需要重建知识库快照：gemini-embedding-2 与退役的 text-embedding-004 向量空间不兼容。加载快照时会核对 manifest.toml 记录的 embedding_provider/embedding_model 与当前运行配置，不一致直接报错而非静默复用旧索引。
• 示例配置与内置兜底默认值已按各渠道当前有效的模型 ID 刷新（Google gemini-embedding-2、OpenAI gpt-5.6-*、Anthropic claude-sonnet-4-6、DeepSeek deepseek-v4-*、SiliconFlow Qwen/Qwen3.5-27B、Grok grok-4.6、Ollama llama3.1 等）；修正了 4 个此前无效的兜底 ID。
• .env 新增 OPENAI_API_BASE 覆盖说明：provider = "openai" 的条目都会走该 Base URL，指向网关时 model_name 必须是网关实际提供的 ID。
• 火山 doubao-embedding-text-240715 已于 2025-12-26 EOM，官方迁移目标走 /embeddings/multimodal 路径，与本项目文本 embeddings.create 不同，示例配置暂未改动，迁移前需实测。
• 无新增运行时配置项；config.toml 仍为本地文件，不纳入版本控制。

验证命令

uv sync --group dev
uv run pytest                                    # 823 passed
uv run ruff check main.py src scripts tests      # All checks passed
uv run bandit -r main.py src scripts -ll         # 0 issues
uv run mypy --cache-dir /tmp/pyrag-kit-mypy main.py src   # 49 files, no issues
uv run python -m compileall -q main.py src scripts tests
uv lock --check && git diff --check
uv run main.py --smoke-test

额外验证：

• CI 可移植性：删除本地 config.toml 与 .env 后完整跑测，823 passed，不依赖开发者本机配置。
• 逐提交可导入：29/29 提交的 src/ 树均通过导入检查（用 git archive 抽出到临时目录，未触碰工作区）。
• 端到端链路：快照加载 → 混合检索 → provider 生成，走通完整 RAG 流程。
• OpenAI 兼容渠道实测：对本地 new-api 网关启用的全部 LLM 条目逐个发起真实请求，均正常返回。
• 原生 SDK 静态核对：Google GenAI / Anthropic / Volcengine Ark / Jina / SiliconFlow 对照各自官方文档核对调用面（未发真实请求）。

备注

• HANDOFF.md（本地交接记录）不在本次提交内。
• 已知未覆盖项：火山 doubao-embedding-vision-251215 迁移路径需真实凭证实测后另行处理。

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 25ddec55-b27d-4855-b2da-c4fba89bd6f5

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Sorry @MisonL, your pull request is larger than the review limit of 150,000 diff characters

[MisonL]

追加：对抗式审查修复（5 个提交）

在 PR 提交后对全分支做了一轮多维度对抗式审查（9 个维度 × 每条 finding 两路独立反驳验证），确认并修复了 11 个真实缺陷。每条都独立复现过，并做了红绿验证（先回退修复确认测试失败，再恢复确认通过）。

修复清单

#	严重度	位置	缺陷
1	critical	volcengine.py	Ark Responses 非流式入口读取 response.output_text，但 Ark SDK 的 Response 没有该字段（OpenAI SDK 才把它实现为聚合 property），正文在 output[].content[].text。于是 complete/acomplete/invoke(stream=False)/ainvoke(stream=False) 全部返回空文本且不报错，ChatService.identify_intent 随后抛「意图识别返回空结果」
2	major	security.py	_url_credential_paths 在 urlsplit 抛 ValueError 时 return []。该分支是叶子值的唯一检查入口，任何凭证只要拼在一个畸形 URL 片段（如 https://[::1）后就能整体绕过边界校验
3	major	security.py	掩码凭证正则排在 Bearer 规则之后：_BEARER_TEXT_RE 先吃掉 Bearer sk-abc 的可见前缀，使 sk- 锚点失效，***...***xyz 原样残留
4	major	security.py	脱敏正则与 is_sensitive_option_key 用了两套键名词表：client_secret、private_key、credentials 在配置边界被判为凭证，却因文本词表更小而明文落进日志
5	major	resources.py	server_verified_protocols 门禁只在显式别名上实现，动态资源树 resources.responses.create(...) 只做凭证校验即可发出请求
6	major	volcengine.py	Ark instructions × caching={"type":"enabled"} 互斥检查只看顶层 caching，漏掉 extra_body（Ark SDK 会把它合并进请求体）与原生 kwargs 两条路径
7	major	model_provider.py	Ark 专属内容块写成 content 会被 variant 守卫拒绝，写成顶层 item 却因不带 role/content 而直通请求体，静默发给 OpenAI 端点
8	major	model_provider.py	Responses custom tool 的 input 按 SDK 契约是任意文本，回填时被强制 json.loads，多轮 custom tool 完全不可用
9	major	retrieval_test/core.py	裸异常交给 console.print 与 logger.error，凭证原样落到终端与日志
10	major	main.py	同上（顶层 CLI 边界）
11	major	model_provider.py	流式事件同时给出 id 与 call_id 两个不同的值，Chat 归一化只保留 id，导致回填 Responses 时 function_call 与 function_call_output 的 call_id 配不上

值得注意的两点

测试夹具掩盖了 critical 缺陷。 #1 之所以长期未被发现，是因为既有测试普遍用 SimpleNamespace(output_text=...) 构造响应——而 Ark 的 Response 根本没有这个字段。夹具伪造了线上不存在的形状，让测试永远通过。新测试改用真实 SDK 模型（Response.model_validate）构造。

#11 曾被两路验证判定为误报。 完整性批评复核后指出它是「真实但更窄」的缺陷，验证者关于「该代码路径不可达」的结论不成立。实测确认：流式产出确实携带两个不同值，回填时 call_id 丢失。

验证

uv run pytest -q                                    # 880 passed（新增 57 个回归测试）
uv run ruff check main.py src scripts tests         # All checks passed!
uv run mypy --cache-dir /tmp/pyrag-kit-mypy main.py src   # 49 files, no issues
uv run bandit -r main.py src scripts -ll            # 0 issues
uv run python -m compileall -q main.py src scripts tests
uv lock --check && git diff --check

回归测试均经红绿验证：回退修复后对应测试失败，恢复后通过。

已知未处理

完整性批评还指出几项未纳入本次修复的事项，它们不属于本次改动引入的缺陷，但值得后续跟进：

• requirements.txt 在依赖升级提交中从「仅生产依赖」变为「含 dev 工具链」，PR 描述未申报。
• 仓库内不存在 Apache 2.0 全文（DIFY_LICENSE 是摘要），而 CHANGELOG 声称「保留上游版权声明」。
• 新增 823 项测试与质量工具链，但无 CI 强制执行（release.yml 只在 v* tag 触发）。
• PyRAG-Kit.spec 是构建产物但未进 .gitignore。
• src/retrieval_test/core.py 创建 RetrievalService/EmbeddingService 后未释放。

🤖 Generated with Claude Code

[MisonL]

追加：遗留问题核实与处理

上一轮完整性复核提出的 5 项遗留问题，逐条核实后处理。3 项成立已修，2 项经实测不成立。

已修（提交 34b8319）

1. 仓库内缺少 Apache 2.0 全文（许可合规）

src/etl/、src/retrieval/ 等 Dify 衍生代码遵循修改后的 Apache 2.0，而 DIFY_LICENSE 只是「引用 Apache 2.0 + 附加条款」的摘要。该许可证第 4(a) 条要求随分发提供许可证副本——移除 Dify 子模块时把唯一的副本一并删掉了，发布包此前只分发摘要。

处理：补入 licenses/APACHE-2.0.txt（202 行官方全文），纳入发布包 PACKAGE_FILES，并在 DIFY_LICENSE 中指向它。PACKAGE_FILES 现在含子目录路径，而 shutil.copy2 不创建父目录，一并补上 mkdir。

2. retrieval_test 未释放服务

该路径创建 RetrievalService/EmbeddingService 后从不释放，而 chat 与 retriever 路径都做了。Embedding provider 与向量存储持有 SDK 客户端与连接池，退出时留下未关闭资源。

处理：用 try/finally 包裹交互循环，新增 _aclose_quietly 助手（优先 aclose，回退 close，失败只记警告，不掩盖主流程结果）。

3. PyRAG-Kit.spec 未进 .gitignore

该文件由 build_binary_release.py 生成后即 unlink，但工作区容易误提交。已补 *.spec。

经核实不成立，未改动

4. 称 requirements.txt 从「仅生产依赖」变为「含 dev 工具链」，属未申报变更

实测 main 版本的 requirements.txt 同样含 pyinstaller 与 pytest——它本来就是 uv export 的默认全量导出（文件头自述的生成命令不含 --no-dev）。口径未变，本次只是 dev 分组新增了 ruff/mypy/bandit 三个工具。该文件也不被任何流程引用（发布流程用 uv sync --group dev）。

5. 称 recursive_text_splitter.py 与 snapshot_repository.py 属移植代码却缺 Dify 归属头

查证两者来源：前者完全建立在 LangChain 的 RecursiveCharacterTextSplitter 上，依赖 src.models.document/src.utils.config；后者依赖 src.runtime.contracts，处理本项目自己的快照目录格式。两者都不含 Dify 特有逻辑（同目录下确实移植的 10 个文件都带归属头，格式一致）。补一个不实的归属头反而是错误，故不加。

另：CI 门禁放在 PR #2

新增 .github/workflows/quality.yml，在 PR 与 main 推送时执行锁文件校验、格式化检查、lint、类型检查、安全扫描、字节码编译与完整测试——此前这些工具「加了但无人运行」（release.yml 只在 v* 标签触发）。

它含 ruff format --check，而本 PR 尚未格式化，放这里会必然失败，因此归入 PR #2（格式化分支）。PR #2 合并后 main 上才有门禁；若先合本 PR，CI 不会生效。

已逐条本地模拟全部 8 步，均通过：

uv lock --check                  Resolved 107 packages
ruff format --check              81 files already formatted
ruff check                       All checks passed!
mypy                             49 source files, no issues
bandit                           0 issues
compileall                       OK
pytest                           880 passed
git diff --check                 OK

🤖 Generated with Claude Code