chore: configure and apply ruff format - #2
Merged
Merged
Conversation
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Advanced Run ID: 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. Comment |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Sorry @MisonL, your pull request is larger than the review limit of 150,000 diff characters
MisonL
force-pushed
the
chore/ruff-format
branch
2 times, most recently
from
September 22, 2026 00:58
764e6f2 to
b43898a
Compare
️✅ There are no secrets present in this pull request anymore.If these secrets were true positive and are still valid, we highly recommend you to revoke them. 🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request. |
MisonL
force-pushed
the
chore/ruff-format
branch
3 times, most recently
from
September 22, 2026 10:10
13d00ed to
b729726
Compare
此前只配置了 ruff lint，未配置 formatter，格式化行为取决于默认值。 显式声明行宽与引号风格，让 `ruff format` 在任何机器上产出相同结果。 行宽取 100 而非默认 88：既有代码本就按约 100 列书写（88 列下有 1875 处 超限行，100 列下仅 664 处），沿用 88 会把大量完整表达式折成多行，产生 无意义的 diff。已核对 88/100/110/120 四档的实际改动行数，100 列比 88 列 少约 40% churn，且是通行标准。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
对 `main.py`、`src/`、`scripts/`、`tests/` 执行 `ruff format`。改动均为 表示层：统一双引号、清除行尾空白、规范化空行与折行。 验证语义等价：对全部改动文件用 `ast` 比对格式化前后的语法树（剥离 docstring 后逐节点比较），语法树完全一致；单独比对 docstring 文本， 唯一差异是 `recursive_text_splitter` 中一行尾随空白被清除。 `nosec` 与 `type: ignore` 抑制均未失效——bandit 仍报 0 问题， mypy 仍报 0 错误。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
本分支引入了格式化配置与 880 项测试，但仓库此前没有任何 CI 执行它们—— `.github/workflows/release.yml` 只在 `v*` 标签触发构建，质量工具实际处于 「加了但无人运行」的状态。 新增 quality.yml，在 PR 与 main 推送时执行：锁文件校验、格式化检查、lint、 类型检查、安全扫描、字节码编译与完整测试。步骤顺序与 AGENTS.md 列出的 本地检查一致；格式化检查放在最前，因为它的失败最容易被后续输出淹没。 已逐条在本地模拟全部 8 步，均通过。 `AGENTS.md` 补充 CI 说明，`CHANGELOG.md` 记录新增工作流与全仓库格式化。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
上一轮扩大脱敏词表时引入四处回归，均在提交 7a60a0a 的版本上复现： - 键名前加了「非字母数字」断言，使 dbPassword/myApiKey/userToken 这类 驼峰键在文本里明文输出，而 is_sensitive_option_key 判其为敏感——即 「配置边界拦住、文本边界放过」的不一致。改为与切词口径一致。 - 裸关键词（auth/cookie/secret/token/bearer）后接普通词时无值形态约束， 把「Set auth: none」「cookie: enabled」判成凭证。因 find_sensitive_option_paths 用「值是否被改写」判定，合法 options 与 资源参数会在边界被误拒。补上值的形态约束。 - 掩码尾部字符类含字母数字，会吞掉紧邻的键名，使 sk-abc***token=<secret> 里的值从脱敏变明文。改为在键名前停下。 - urlsplit 的 ValueError 回退分支只做值脱敏，畸形 URL 下 ?myApiKey= 这类空值敏感键漏检，而同样内容在可解析 URL 下会被拦下。 回归测试 13 项已按红绿验证：回退 security.py 后全部失败。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
多轮审查发现以下缺陷，均已在对应提交上复现并红绿验证：
Ark 渠道（volcengine.py）
- ``_require_provider_resource`` 用 ``"response" in segments`` 判断，而动态
路径传的是完整路径，单数分段在四个 SDK 的资源树里都不存在；``input_items``
（打 ``/responses/{id}/input_items``）因此完全绕过门禁，chat_completions
协议下也能把请求发到远端。改为精确的子资源集合匹配。
- 动态路径只做能力检查，不执行 Facade 上的参数校验，
``resources.responses.create(...)`` 可带 instructions × caching 直接发出。
门禁钩子增加 kwargs 参数，动态路径复用 ``_validate_native_response_kwargs``。
- fail-closed 把内置工具调用项（web_search_call、mcp_call、mcp_list_tools、
reasoning 空摘要）判为「结构不符」，而这些是 SDK 输出项联合的正式成员、
属正常中间态。改为只拦真正空白的 completed 响应。
归一化（model_provider.py）
- 非字符串 ``type`` 直接做集合查找，把类型错误变成
``TypeError: unhashable type`` 崩溃。恢复 isinstance 短路。
- ``_responses_tool_call_type`` 在非 assistant 角色的兜底分支随请求体发出。
改为在消息级与工具调用项级统一剥离。
流式语义（openai_compatible.py）
- ``id`` 在 delta 取 item_id、在 done 取 item.id、合并时又互相覆盖，同一轮
工具调用在 delta 与 completed 事件里得到不同的 id。统一取 call_id，与
非流式路径的 ``call_id or id`` 一致。
脱敏边界（security.py、config.py、main.py）
- 词边界 ``\b`` 在中文两侧都不成立（中文属 ``\w``），国产网关的中文错误
消息会让密钥整体漏检。改用「非 ASCII 字母数字」断言。
- ``Settings()`` 在 import 期被调用，早于任何入口的 ``try``，pydantic 会把
``input_value`` 明文交给解释器默认 handler。在 ``get_settings`` 边界重抛
已脱敏的消息，并给 ``run_cli`` 包一层启动边界。
测试
- 重写 URL-query 断言：原断言用的长值由另一条规则满足，删掉被测规则也不红。
- 替换 Ark 的 ``SimpleNamespace(output_text=...)`` 夹具为真实 SDK 模型，
该夹具此前替被测代码补上 Ark 不存在的字段，掩盖了空正文缺陷。
- 新增回归测试 40 项，红绿验证：回退源码后全部失败。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
审查发现三处测试未能守住它声称保护的回归： - ``test_security_redacts_sensitive_key_names_in_url_query`` 恒真：断言用的 长值由 ``_KEY_VALUE_TEXT_RE`` 满足，删掉整条 URL query 规则也全绿。改用 只有该规则能覆盖的短值（``x``/``0``/``none``）并断言精确替换形式。 - ``test_ark_responses_result_does_not_replace_answer_with_reasoning_text`` 用 ``SimpleNamespace(output_text=...)`` 伪造响应，而 Ark 的 ``Response`` 没有该字段——夹具替被测代码补上了它，掩盖了空正文缺陷。改用真实 SDK 模型。 - 词表一致性不变量无人看守：往 ``SENSITIVE_OPTION_KEYS`` 加真凭证键时， 文本词表不会自动跟上。改为从该词表派生断言，并显式声明有意排除的 8 个 连接类键名。 另补一条驱动公开入口的集成测试：原缺陷是 complete/acomplete/invoke/ ainvoke 四个非流式入口全部返回空文本，此前只钉住私有 ``_extract_result``， 入口绕开助手或丢弃返回值时不会变红。 新增断言均已红绿验证。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
``display_banner`` 与 ``initialize_dependencies`` 在 ``main()`` 的 ``try`` 之前执行，这两步里的配置错误会以裸 traceback 落到终端。虽然 ``get_settings`` 已对校验失败做脱敏，traceback 本身仍会打印，且其它启动 期异常（依赖初始化、路径解析）完全没有兜底。 在 ``run_cli`` 包一层：失败时打印脱敏消息并返回退出码 1。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
``stage_bundle`` 用 ``target`` 作为循环变量名，遮蔽了同名的函数参数（平台 标识，如 ``macos-arm64``）。当前循环之后没有再读 ``target``，因此尚未触发 故障，但这是一颗哑弹：后续在该循环后追加任何使用平台名的逻辑都会拿到 ``Path`` 而不是字符串。改用 ``destination``。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
审查报告的剩余项，均已在对应提交上复现并红绿验证：
- 顶层 Responses item 的变体校验以「有没有 ``content`` 键」分流。加一个
无关的 ``content`` 键即可改走消息分支，绕过全部变体校验；而
``_responses_content_part`` 里的其余检查点（必填字段、``detail`` 取值、
``fps`` 类型、``chunking_strategy`` 形状）在顶层路径没有等价实现。
改为按 ``type`` 分流，整项交给同一套实现，顺带补齐形状归一化。
- ``instructions`` × ``caching`` 互斥只查顶层 ``instructions``，
``extra_body={"instructions": ...}`` 配顶层 ``caching`` 可绕过。SDK 会把
``extra_body`` 合并进请求体，服务端看到的与顶层写法相同，两条来源都要查。
- custom tool 的结构化 ``input`` 用 ``str()`` 编码，对 dict/list 产出 Python
repr（单引号、``None``/``True`` 字面量），而同一份数据经
``assistant.tool_calls`` 路径会被 JSON 编码，两条路径给出不同文本。
新增回归测试 18 项，红绿验证：回退源码后 11 项失败（另 7 项是既有覆盖或
等价输入的护栏）。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
``__slots__`` 里的名字默认都会出现在 ``dir()`` 中，IDE 会把 ``_value`` 提示成公共 API。它并不是出口——文档化的出口是 ``.native``（按设计返回完整 原生树、不经过凭证扫描与能力门禁），``_value`` 指向同一个对象，因此不构成 独立的绕过路径。这里只是不让自动补全把实现细节呈现给使用者。 另补一条 dict 形态响应的提取测试：``field()`` 同时支持属性访问与 Mapping， 非标准网关透传的 JSON 也要走同一条类型过滤。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1.4.0 尚未发布（main 上无该段），本轮修复属于同一版本。补齐此前只有 高层描述、没有对应条目的守卫：动态资源树门禁、顶层 item 变体校验、 流式工具调用 id 语义、Ark 失败判定放宽，以及脱敏边界的三处修复。 测试计数同步为 958，并说明新增断言均经红绿验证。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
多轮审查（5 个独立 agent）发现以下问题，均实测复现并红绿验证：
脱敏边界（security.py）
- 上一轮给全部键名加的值形态约束（「引号包裹 / 含数字符号 / ≥12 字符」）
使短且纯字母的凭证整条漏检：``password: huntertwo``、``token: mytoken``
从脱敏变明文，同时削弱文本脱敏与配置边界校验。那是比误判更严重的净漏检。
改为用非凭证字面量 denylist 排除误判源（``auth: none``、``cookie: enabled``），
显式凭证键名保留任意值。
- 键名前的界断言不能简单删掉：``oauth``、``topsecret``、``sessiontoken`` 会从
词中间命中 ``auth``/``secret``/``token``，而配置边界判它们非敏感（切词后不
命中），误拒合法配置。改用「非字母数字或 camelCase 边界」，并把 ``(?i)``
局部化到键名组——写在最前面会让 ``[A-Z]`` 匹配任意大小写，``oauth`` 的
``o``→``a`` 被误判为驼峰边界。
- 掩码规则的尾部前瞻逐字符重复扫描剩余串，尾部无冒号时退化成 O(n²)：
``"sk-abc***" + "deadbeef"*500`` 从 0.01ms 涨到 11ms，4000 字符时 1.4 秒。
而 redact_sensitive_text 挂在每条日志的 formatter 上。改为无回溯的贪婪匹配
加替换函数裁剪——同时修掉尾部可见片段残留（``sk-abc***xyz: boom`` 的 ``xyz``
变明文）与掩码吞掉紧邻键名（``sk-abc***token=<secret>`` 的值变明文）。
Ark 门禁（volcengine.py、openai_compatible.py）
- fail-closed 白名单漏了 SDK 联合成员 ``image_process``、``agent_tool_call``，
这类响应会无法处理；同时 ``reasoning`` 不该豁免——空摘要且无正文时确实是
什么都没有，豁免会让它静默返回空成功，掩盖失败。
- ``caching={"type": "ENABLED"}`` 绕过互斥检查：SDK 的 Literal 注解不做运行时
校验，精确比较漏掉大小写与空白变体。
- 动态路径按 ``{"create", "generate"}`` 动词白名单决定是否做参数校验，漏掉
``async_create`` 这类 SDK 演进后新增的写法。改为按参数里是否出现受校验字段。
- 兼容渠道的动态路径能力映射只覆盖 responses/files，``resources.batches.create``
等拿到 None 直接放行，而显式名 ``create_batch`` 会被拦；``uploads`` 还与
``files`` 坍缩成同一能力。
资源代理（resources.py）
- ``__slots__`` 封闭了自有 ``__dict__``，但 ``__getattr__`` 把私有名转发给底层
SDK 节点：``proxy.__dict__["_client"]`` 能拿到未包装的原始客户端，绕开全部
凭证扫描与能力门禁。改为拒绝下划线名转发，``dir()`` 只列公开资源名。
归一化（model_provider.py）
- ``image_pixel_limit`` 是 Ark 专属字段，与 ``type``/``content``/``role`` 都无关。
此前只在「有 content 键」或「类型是内容块」时检查，加一个无关的 ``content``
或 ``type`` 键即可绕过。抽出共用检查覆盖全部书写位置。
- ``type`` 是任意 JSON 值，集合查找对不可哈希的值抛
``TypeError: unhashable type``——正是本批要修的那类崩溃，却在新的分流点被
重新引入。两处都加 isinstance 守卫。
新增回归测试 47 项，红绿验证：回退源码后 35 项失败。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
密钥扫描器把 ``password: huntertwo``、``passwd: letmein`` 这类已知弱口令 判为 Generic Password 并告警。它们是测试用的假值，与真实凭证无关（已核对 本地 .env 无重合、全历史无真实令牌样式），但告警会留在提交历史里，且掩盖 后续真实告警。 测试要覆盖的属性是「短且纯字母」，与具体取值无关，改用明显合成的标记。 文档与注释里的同一处示例一并替换。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
测试里的 ``sk-proj-AbCdEfGh...``、``AIzaSyAbCdEf...`` 虽然内容明显合成， 但符合 OpenAI 与 Google API Key 的真实格式，容易被密钥扫描器按格式规则命中。 改用 ``FAKE0000`` 重复的形态：正则仍能匹配（测试要的是格式），一眼可辨为假值。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
多轮审查发现的缺陷，均已在对应提交上复现并红绿验证。 脱敏边界（security.py） - 掩码规则吞掉键值对键名后留下孤儿值：sk-abc***xxxtoken=<secret> 里的键名 按 camelCase 切词判非敏感，键值规则不会接手，而掩码已把键名吃掉，值失去 锚点后明文落进日志。掩码匹配现在把键值尾部一并纳入，只保留键名作上下文。 - 替换函数里的二次回溯：尾部游程用无锚点的 re.search(r"[A-Za-z0-9_-]+$") 查找，在每个起点重试 +$；尾部以 . 这类掩码占位符收尾时游程够不到 $，退化 成 O(n²)（32010 字符 9.6 秒）。改为单遍扫描。 - 非凭证字面量枚举改为大小写不敏感，auth: None 这类写法此前被判成凭证， 使合法配置在边界被误拒。 - 界断言补齐第三条驼峰分支（大写串接小写词），HTTPBearer/HTTPSSecret 此前 在配置边界判敏感、在文本里明文输出。 Provider 门禁 - Ark 动态路径的参数校验触发集含 extra_body，而它是 retrieve/delete/list 的 合法参数，使只读操作被要求提供 model 与 input——Facade 可用而动态路径不可用。 - 兼容渠道路径映射的 moderation 用了单数，SDK 属性是复数 moderations， 导致 resources.moderations.create 拿到空能力直接放行。 - 段映射列出五项官方声明集之外的能力名，把官方端点从放行变成显式报错， 而这些资源在 capabilities 里声明为可用。 - Google 实验性资源门禁只认显式 Facade 名，动态点分路径全部落空放行。 - 顶层 Ark 专属字段只拦 image_pixel_limit，带一个无关的 content 键即可 绕开类型分流，input_audio/input_video/audio_url/video_url 原样发给不支持的端点。 新增 28 项回归测试，测试总数 1033。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
代理节点的注释把出口指向 `.native`，但该属性挂在 Facade 层 （`provider.resources.native`），代理节点本身没有——用户拿到的是节点时 这个指引不成立。改为明确指向 Facade 层。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
测试有效性审查发现三处断言没有真实防护能力，均已用定向变异复验。
- 掩码尾部可见片段的断言用 startswith("[REDACTED]")，而掩码前缀在任何
实现下都会被替换成 [REDACTED]，该断言恒真——尾部片段原样泄漏时也能通过。
改为全文相等，并用「让尾部字符类不吃尾部」的变异确认变红。
- 短纯字母凭证的 7 个用例里有 4 个取值 ≥12 字符，旧规则本就能命中，对
「短值」这个被测属性零区分度。改为真正短于 12 字符的值，断言改为检查
值本身被替换而不是「文本被改写过」（后者被键名之外的任何改写满足）。
- 掩码线性度用例用单次采样配 100ms 阈值，实测本机 p99.9 即到 100ms、
满载时更高，会间歇误报。改为放大规模到线性与二次相差三个数量级、
取多轮最小值；二次实现下连跑 4 次全部变红（原写法 5 次里有 1 次误判通过）。
- 为 _normalize_responses_native_item 的顶层字段守卫补直接调用测试：它对
当前唯一调用点是冗余的，没有测试能区分其存在，等于死代码。
测试总数 1037。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
GitGuardian 对 PR 范围报 1 处未覆盖的密钥。核对后确认是测试夹具里的 合成值，但形态与真实密钥一致（顺序字母数字、`sk-live-` 前缀加十六进制）， 会持续触发扫描器。统一替换为带 FAKE 标记的值，长度与字符构成保持 在被测规则命中的范围内，语义不变。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
MisonL
force-pushed
the
chore/ruff-format
branch
from
September 22, 2026 10:27
b729726 to
82c4a28
Compare
文本层此前用正则的字符断言去逼近 is_sensitive_option_key 的切词逻辑， 两者无法自然对齐，passwordHash、tokenCount、cookieJar 这类「凭证词 + 另一个词」的键出现双向不一致：真凭证在日志里明文输出，而键名相同的 合法配置值又在边界被误拒。 改为文本层捕获完整键名后调用同一个判定函数，一致性由构造保证。同时： - 短凭证键 ak/sk 的值补上非凭证字面量排除。这两个键在配置里常作开关 （sk: off），与裸关键词是同一类误判源，此前只给裸关键词加了约束。 - 脱敏替换不再改写分隔符。此前把 key: value 归一化成 key=value，会篡改 被脱敏文本的结构（JSON 片段因此变成非法 JSON）；现在保留原文的 :/= 与引号。 - 基类 _require_provider_resource 的 kwargs 契约写明实现状态：只有 Volcengine 在 Facade 上做参数校验、因而需要 kwargs；其余 Provider 忽略它与契约一致，并注明凭证边界由代理层统一执行。 键名判定拆出 _is_credential_key（不含连接类容器键），使文本层能复用 凭证判定而不把 query/headers 这类连接键纳入。 验证：71568 条键值形态语料差分，14592 条由明文改为脱敏，零回归； 新增 24 项回归测试，测试总数 1061。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- 移除 _BARE_CREDENTIAL_KEYWORD_PATTERN 与 _QUALIFIED_CREDENTIAL_KEY_PATTERN： 上一轮把文本层改成「宽泛捕获 + 回调判定」后，这两个模式串不再被引用， 由 _BARE_KEYWORD_KEYS 取代。 - 两处裸 pytest.raises 补上 match：只查异常类型的话，被测代码因别的原因 抛同类异常也会让测试通过。已用「抛出无关 ValueError」的变异确认带 match 的断言会变红。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
本轮补充回归测试后总数由 1037 增至 1061，CHANGELOG 的数字未同步。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
对最近一个月的 20 份规划类文本做全维度审查后，修复其中经独立复现确认的问题。 - 恢复 `src/etl/splitters/recursive_text_splitter.py` 的 Dify 移植声明头。 该头在引入 tiktoken 与层级分片的重写中被误删，此后 `sync dify rag hierarchical retrieval` 又向这个已无头的文件移植了父子分片逻辑， 使文件含 Dify 衍生代码却没有版权与许可证声明，与 AGENTS.md 的合规 要求及 Apache 2.0 第 4(b) 条不符。该删改在 main 上，非本 PR 引入。 - Responses 错误出口补齐脱敏：`_raise_for_response_error` 此前把服务端 消息直接拼进异常，而同一适配器的 Chat Completions 出口已经过 `redact_sensitive_text`。服务端错误常回显请求头或 URL，异常文本会进 日志与终端，是凭证最容易泄漏的出口，现两个出口行为一致。 - 修正 Excel 记录落盘位置：`ExcelLogger` 硬编码相对路径 `data/logs`， 而文本日志用经 ROOT_DIR 解析的 `settings.log_path`。相对路径基于 CWD， 从仓库外运行会分叉，现默认复用 `settings.log_path`。 - `capability_report` 与 `protocol_status` 对齐角色语义：前者在 embedding/rerank 角色下仍报告 `server_verified_protocols` 并接纳运行期 登记，后者对同一输入显式报错。协议只适用于 LLM 角色，两个诊断入口 现给出相同结论。 - 补充回归测试：重排乱序路径（既有替身恒返回 `[0]`，重排与降序排序 从未被执行）、`_validate_rerank_output` 的布尔混入与越界 index、 Responses 错误出口脱敏、`top_n` 非法值。修复 `test_rerank_accepts_top_n_larger_than_document_count` 的恒真调用。 - 文档校正：`REFACTORING_PLAN.md` 标注为 v1.2.0 历史归档并修正三处与 现状不符的表述；`README.md` 移除已退役模型举例、修正 `/config` 可调项 描述、补全 `src/` 目录树、把许可说明指向实际存在的许可证文件； `getting-started.md` 移除不存在的 `exit`；`developer-guide.md` 补全目录树。 测试数 1061 -> 1088。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
第二批规划审查修复，三处缺陷均独立复现并做红绿验证。
- 修复 Anthropic 响应解析在字段为 None 时崩溃。`field()` 只在键不存在时
返回默认值，而 SDK 的 thinking/redacted_thinking 块会给出 None，此时
`"".join(...)` 抛 `TypeError: expected str instance, NoneType found`。
非流式的正文与推理拼接、流式的 text_delta/thinking_delta/input_json_delta
三处一并加兜底。同类拼接在 Google 与 Volcengine 已有 isinstance 守卫，
仅 Anthropic 缺；回退修复后 4 个用例变红。
- Google `tool_choice` 不再静默接受未知模式。`FunctionCallingConfigMode` 是
大小写不敏感枚举，未命中时会合成一个同名成员、只发 UserWarning，随后被
静默发往服务端；OpenAI 风格的 `{"type": "tool"}` 正会落到这里（已用
`-W error::UserWarning` 复现）。现按已知模式显式映射，未知值报 ValueError
并给出可选值。`ToolConfig` 的未知键也从裸 pydantic ValidationError 归一为
本项目的 ValueError。
- Responses `json_schema` 缺 `schema` 时显式报错。此前回退成 `schema` 本身，
伪造出 `{"type": "json_schema"}` 的 schema 发给服务端，调用方以为拿到了
结构化输出约束而实际没有；同时 `strict` 不再被硬编码的 True 覆盖调用方取值。
- 补充流式重试助手的回归测试。`retry_sync_stream`/`retry_async_stream` 的
建立阶段重试此前零覆盖，现覆盖「建立失败重试」「首事件后不再重试（避免
重复输出）」「空流不算失败」「校验器只作用于首事件」「消费方提前退出时关闭
迭代器」及异步等价场景。
经核实为有意设计不改：`function_response_value` 对 JSON 形态工具结果的解码；
非流式 `invoke` 只产文本（工具调用与截断信号走 `complete()`）。
测试数 1088 -> 1119。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
第二批维护复核发现并修复两处真实缺陷：
- Ark Chat Completions 工具调用缺 type 键：`_extract_result` 的 Chat
Completions 分支只产出 `{"id", "name", "arguments"}`，而同一函数的
Responses 分支与 `openai_compatible.py._extract_tool_calls` 都产出契约
声明的扁平 `{"id", "type", "name", "arguments"}`（model_provider.py:343
与 docs/user_guide/llm-providers.md:108 双重写明）。调用方按契约回填
`role=tool` 历史时会配不上，此前的 OpenAI 侧测试输入带了 type 却只断言
name，Ark 侧则完全没有 CC 用例，因而从未暴露。
- 8 个数值配置字段缺加载期校验：`kb_chunk_size=0` 会一路通过配置校验、直到
langchain 在分片阶段才抛 `chunk_size must be > 0`；负权重会反向加成分数。
UI 层（src/ui/config_menu.py）对权重已有 0..1 校验，TOML/env 路径没有。
另用 model_validator 补上「overlap 必须严格小于 size」这条无法用单字段
表达、但会让切分器无法推进的跨字段约束。
两处修复均经红-绿验证（回退源码 → 测试恰好失败 → 恢复 → 通过）。
验证命令：
- uv run pytest -q → 1135 passed（基线 1119，新增 16 条）
- uv run ruff check / ruff format --check → 通过
- uv run mypy --cache-dir /tmp/pyrag-kit-mypy main.py src → 无问题
- uv run bandit -r main.py src scripts -ll → 0 issues
- uv lock --check / git diff --check / compileall → 通过
- uv run main.py --smoke-test → smoke test ok
配置影响：越界的 chunk/weight/retention 值现在在加载期显式报错，此前被静默接受。
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
本轮为「发布前最终复核」的可不修项清理，全部为零功能影响或纯加固，
与上一提交（契约缺陷修复）分开，以保持两个 diff 各自可审。
死代码与重复实现：
- 删除 config.py 的向后兼容层 get_backward_compatible_configs()（85 行，
全仓零调用）及其失效的悬空注释。
- 删除 LargeLanguageModel.supports()（零调用）。保留它读取的 capabilities——
factory.capabilities() 经 getattr 动态读取该属性，是活数据，连带删除会
让能力报告静默变成空集。
- 删除 volcengine._ARK_CLASSIFICATION_KEYS（纯冗余：classify() 的三个同名
形参 query/model/labels 无法落进 **kwargs，常量减内联校验集恰好等于这
三个；真正的校验由内联集合完成且完整）。
- 删除 FaissStore 中从未获取的 asyncio.Lock 及其函数内局部 import。
- 简化 anthropic.py 中条件永不产生可区分行为的恒等 if/else。
- openai_compatible._field 与 model_provider.field 逐字节相同却各存一份，
且被 143 处调用（self 28 + cls 115）。删重复定义，统一复用 field。
- volcengine 的 4 个 helper 是 openai_compatible 的逐字节副本，改为委托。
- jina 与 siliconflow_rerank 存在 4 处真实语义差异，有意保持独立实现；
改为在两侧 docstring 写明差异清单与「改动必须同步」的约束。
依赖与文件：
- 删除孤儿 logo_ASCII.py（零引用、不在构建/CI 配置、create_gradient 与
main.py 逐字节重复、且未格式化）。
- 移除 langchain 与 langchain-community。保留 langchain-core 与 requests：
前者是 langchain-text-splitters 的必需依赖，后者是 google-genai 与
tiktoken 的必需依赖，删除会破坏真实依赖链。
安全与流程加固：
- Google tool_choice 的异常文本在源头脱敏。裸 pydantic ValidationError 会把
违规取值原文写进 input_value=...，而 types.ToolConfig 的键集里就有 api_key
这类凭证形态的键。两个消毒器都能拦住，但源头收口才是纵深防御。
- release.yml 手动发布路径补交叉校验：workflow_dispatch 的 tag/version 此前
直接透传，会发出与 pyproject.toml/CHANGELOG.md 不符的 release。现校验
version 与 pyproject.toml 一致、tag 等于 v{version}、且 CHANGELOG 有该条目。
验证命令：
- uv run pytest -q → 1135 passed（与上一提交相同，零行为变更）
- uv run ruff check / ruff format --check → 通过
- uv run mypy --cache-dir /tmp/pyrag-kit-mypy main.py src → 无问题
- uv run bandit -r main.py src scripts -ll → 0 issues
- uv lock --check → Resolved 88 packages（原 107，移除 2 个直接依赖及其传递树）
- uv run python -m compileall / git diff --check → 通过
- uv run main.py --smoke-test → smoke test ok
- release.yml → yaml.safe_load 通过，Validate 步骤已在 publish 步骤序列中
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
第三轮复核（4 个审查 agent）在 0cb770a 之上挖出的缺口，全部为新增发现， 存在于 453d096 基线，属前几轮遗漏。 配置边界（可用性缺陷）： - chat_top_k 与 retrieval_candidate_multiplier 补齐上界。effective_top_k = chat_top_k * multiplier 直通 faiss_index.search()，FAISS 既不报错也不截断： 实测 chat_top_k=10**9 单次查询分配约 3.6 GB 数组、RSS 涨 10.3 GB、挂起 8.4 秒。 现限制 top_k ≤ 10000、multiplier ≤ 100。 - kb_child_chunk_size 必须严格小于 kb_chunk_size。此前 parent=child=300 被接受， 实测不同父块数等于分块数（15/15），即每个父块只产出一个子块，父子检索退化为 单层且无任何报错。与既有 overlap < size 同属跨字段约束。 - 两个融合权重不得同时为 0。_weight_tuple() 在 total <= 0 时返回 (0.0, 0.0)， 所有候选得分为 0，再叠加 weighted 策略启用阈值过滤（默认 0.4）会导致检索结果 被全部丢弃且静默返回空。单个为 0 仍合法。 bool 绕过数值校验（根因比现象深一层）： - pydantic 的 lax 模式会在 field_validator 之前把 True 强转成 1，因此原先 6 处 isinstance(value, bool) guard 全部不可达——实测 chat_top_k / log_retention_days / chat_vector_weight 等 10 个字段的 True 均被静默接受为 1 / 1.0。现给这些 validator 加 mode="before" 让 guard 生效，并新增 _coerce_number() 统一处理 mode="before" 下收到的原始输入（.env/TOML 是字符串，必须继续支持）。 - chat_temperature 与 retrieval_candidate_multiplier 补同样的布尔短路。 示例配置： - .env.example 的 DEFAULT_LLM_PROVIDER="openai" 是生效的环境变量，优先级高于 config.toml，按示例原样复制会把 default_llm_provider 从 google 改成 openai， 导致 14 条模型配置因密钥为空串在运行期失败（而 embedding/vector 都选了零凭证 通道，证明零凭证默认可行）。现改为注释并说明原因。 测试质量（三处假绿 / 零区分度）： - test_numeric_settings_reject_illegal_values 原先断言 match=field_name，而跨字段 model_validator 的报错文本也含这些字段名（「kb_chunk_overlap 必须小于 kb_chunk_size。」），删除 validate_positive_sizes 后 3 例仍全绿。现改为断言各 validator 独有的消息片段，变异下失败数从 2 提升到 5。 - Ark type 键回归测试的夹具原先写 type="function"，与硬编码值相同，把透传改成 硬编码的变异体无法被捕获。现改用非 "function" 的取值，并新增覆盖「缺 type 时 两侧默认值对齐」的交叉断言。 - 新增 12 例布尔短路测试。 验证命令： - uv run pytest -q → 1154 passed（基线 1135，新增 19） - 红-绿验证：三处测试修复各做定点变异，均在回退源码后恰好变红 - uv run ruff check / ruff format --check → 通过 - uv run mypy --cache-dir /tmp/pyrag-kit-mypy main.py src → 无问题 - uv run bandit -r main.py src scripts -ll → 0 issues - uv lock --check / git diff --check / compileall → 通过 - uv run main.py --smoke-test → smoke test ok - env 字符串路径回归确认：CHAT_TOP_K='3' 等仍正确解析为 int 配置影响：越界的检索规模、倒置的父子分片、双零权重、以及 bool 形式的数值配置 现在均在加载期显式报错，此前被静默接受。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
第三轮审查复现的问题集中在一类模式：**校验只做一半，非法值在离原因很远的地方才炸**。
逐项实测后修复如下。
分片（数据完整性，最严重）
- `chunk_size` 在「分隔符耗尽」时完全失效：LangChain 的
`RecursiveCharacterTextSplitter._split_text` 走到 `if not new_separators:
final_chunks.append(s)` 是原样追加、不再切分，而默认配置
`kb_splitter_separators = ["###"]` 只有一项匹配项，`new_separators` 直接为空。
实测 `chunk_size=1500` 时 3600 token 的纯列表文本产出单个 3599 token 块；对真实
知识库 39 个文件扫描，**34 个**产出超限块（子块上限 300，实测 4595）。现在分隔符
表统一以 `""` 收尾；含 `###` 的文档切分结果不变（实测 3 块/最大 252 字符）。
- `_strip_leading_punctuation` 直接删除开头句号。分隔符本身是句号时该句号被永久
丢弃（实测 843 字符分成 15 块后只剩 829，丢失 1.66%）；整篇以句号开头更会产出
0 个块。改为替换为等长空格，信息一字不丢。
配置校验
- `chat_score_threshold=10**400` 抛的是**裸 `OverflowError`**（`float(10**400)`），
它不是 `ValidationError`，会穿透 `get_settings` 的 `except` 变成未脱敏 traceback。
范围判断移到转 float 之前。
- `log_retention_days` / `kb_chunk_size` / `kb_child_chunk_size` /
`kb_embedding_batch_size` 原先只有下界，实测 `10**400` 全部被接受；补上界
（3650 / 1_000_000）。
- `_coerce_number` 的 `int()`/`float()` 会接受 `"1_0"`、`"+7"`、`"0x10"`
（`int("1_0") == 10`、`float("1_0") == 10.0`），把写错的配置静默读成另一个数；
改为先做十进制形状校验。
- 列表类 env 字段（如 `KB_SPLITTER_SEPARATORS='###'`）抛的是 pydantic-settings 的
`SettingsError`，它继承 `ValueError` 但**不是** `ValidationError`，原 handler 接不住；
现在转成一行脱敏消息。
`SessionConfig` 缺校验（运行期入口）
- `Settings` 只在启动时校验一次，而 UI 与库调用方经 `__setitem__` 写入的
`SessionConfig` **完全不校验**。实测 `chat_config["top_k"] = 10**9` 一路走到
`faiss_index.search()`（实测 `10**6` 就已按满槽位分配并耗时 1.56s）；同时接受
`vector_weight=-5`、`retrieval_method='totally-invalid'`、`score_threshold=None`。
为 9 个标量字段补上校验器注册表，并加结构断言防止漏登记（漏登记会静默回落为
无校验，且不会让任何行为测试变红）。UI 两处输入同步补上界。
快照完整性
- `validate_snapshot_dir` 原先只查文件**存在性**。实测 `documents=3` 而
`embeddings=(2,4)`（`ntotal=2`）的 store 能正常落盘、通过校验、加载后零报错，
之后 `semantic_search` 拿 `indices` 索引 `self.documents` 才越界。现在校验
chunks / embeddings / stats.json 三者行数自洽，并把截断文件的解析失败
（原先裸 `EOFError`）归类为「快照不自洽」。
BM25
- `keyword_search` 的 `if score <= 0: break` 分不清「该词无判别力」与「0 分文档
排在前面把正分结果截断」。rank_bm25 的 idf 只对 `< 0` 做 epsilon 浮动，某个词
**恰好**出现在一半文档里（`n == N/2`）时 idf 恰为 0，该词分数全为 0 并静默返回空。
改为先看全局最高分，再按分数降序收集、0 分只跳过不终止。
- `load_snapshot` 从 `lexical.index` 读回 `[]` 时 `BM25Okapi` 在
`avgdl = num_doc / corpus_size` 处 `ZeroDivisionError`；空语料改为返回 None。
嵌入向量
- `_as_float32_matrix` 缺有限性校验：NaN/inf 被接受并写入 FAISS（`ntotal` 正常
增加），直到查询时才以 3.4e38 的哨兵距离暴露，届时已无法定位坏文档；
`1e300` 还会先触发 `RuntimeWarning: overflow encountered in cast` 静默溢出。
对齐 `retrieval_service` 既有的 `math.isfinite` 校验。
界面
- `_initialize_vector_store` 无条件打印「知识快照加载成功。」——没有快照时 store
为空（`documents=0`、`faiss_index=None`），用户会先看到成功再看到永远是
「无相关文档」，把构建缺失误诊成检索质量差。改为按实际分块数区分提示。
测试
- 新增 72 条回归断言（1154 → 1226），全部红绿验证：临时回退对应源码后必须变红。
- 修正 3 条假绿/过时断言：`test_recursive_text_splitter` 原先要求恰好 2 块，而第 1
块长 22 字符已超过 `chunk_size=20`——它把「chunk_size 失效」当成了期望行为，
现改为断言每块不超限且内容并集覆盖原文；`log_retention_days` 断言文案随上界更新；
factory 测试的占位空文件改为最小可解析快照（需配合新的行数校验）。
质量门（全部实跑）：pytest 1226 passed、ruff format/check、mypy 49 files、
bandit -ll、compileall、uv lock --check、git diff --check。
第三轮审查剩余项中可由代码独立处理的部分。重点是 AGENTS.md 明确要求「只从本项目 生成的本地快照或明确受信的 legacy 文件加载」，但此前代码不做任何来源校验。 pickle 信任边界（新增） - 快照内的 chunks.pkl / parents.pkl / lexical.index 都是 pickle，反序列化即执行 代码，而路径本身不能证明来源。此前 `load_snapshot(dir)` 接受任意目录、 `load(path)` 接受任意路径、`FaissStore(file_path=...)` 还会隐式加载。 - `src/utils/security.py` 新增 `resolve_within()` / `ensure_trusted_source()`： 两侧都先 `resolve()` 再比较，符号链接逃逸（`root/link -> /etc`）会被拦下； `trusted_roots` 为空时一律拒绝，不退化成「任意路径都可加载」。 - `load_snapshot()` 现在要求调用方给出 `snapshot_root`，并校验三件事：目录解析后 在信任根内、目录本身不是符号链接、`ACTIVE_SNAPSHOT` 标记指向的就是该目录。 第 3 条是关键——仅「在 root 之下」不足以证明目录可用，未激活或半成品目录同样在 root 之下。`load()` 要求 `trusted_paths`；`__init__(file_path=...)` 不再隐式加载。 - `SnapshotRepository.validate_snapshot_dir()` 同步加归属校验：必须在信任根内、 非符号链接、且是根的直接子目录。 - `factory.py` 的两个加载点分别传 `run_config.snapshot_root` 与 `legacy_path.parent`；`base.py` 抽象签名同步。 manifest schema 准入 - `load_manifest()` 之前只 `str(data["schema_version"])` 解析、不比对，未知版本被 静默接受并照着当前代码解释——v1→v2 调整过分块与 embedding 的落盘结构，这样会 得到错误结果而不是报错。现在版本不符即拒绝，消息给出快照版本与当前版本。 - 版本判断放在 `load_manifest` 而不是 `from_mapping`：后者保持纯解析，避免「解析」 与「准入」两件事在同一处各判一次。 legacy 导入的临时目录清理 - `factory.py` 的 legacy 分支此前没有 `KnowledgeBuildService.build` 那样的 `finalized`/`finally` 结构，`create_temp_snapshot_dir` 之后任何失败都会在快照根 留下 `.tmp-legacy-*` 并随时间累积。 - 照搬同一结构补齐；并把 `validate_snapshot_dir(temp_dir)` 提到 `finalize_snapshot` **之前**——finalize 会更新 ACTIVE_SNAPSHOT，校验放到它后面 就只剩「坏快照已经被激活」这一种收场方式。清理失败只记日志，不掩盖真正的失败 原因（与 knowledge_build_service 一致）。 发布包的符号链接 - ZIP 分支（Windows 是唯一 zip 目标）用 `rglob` + `ZipFile.write`，遇到悬空符号 链接抛裸 `FileNotFoundError`，消息里看不出「这是发布包里的符号链接」；而 tar.gz 分支对同一目录完全正常，两分支行为不一致。 - 新增 `find_dangling_symlinks()`，归档前显式检查并抛 `RuntimeError`，列出全部 悬空路径并说明处置方式。tar.gz 分支保持既有行为（验证过它保留符号链接成员）。 警告可见性 - `pytest.ini` 原先全局 `ignore::UserWarning` / `ignore::DeprecationWarning`，把四个 快速迭代的 SDK 升级警告和本项目自身警告一起静音了（实测同一探针用例在全局忽略下 静默通过、在 `-W error::UserWarning` 下失败）。 - 改为第三方 module 前缀限定；新增断言本仓库配置加载路径不产生这两类警告， 防止「收窄过滤」在未来某次改动里悄悄失效。收窄后全量测试无新增失败。 测试 - 新增 21 条回归断言（1226 → 1247），全部红绿验证。 - 补齐此前完全空缺的覆盖：legacy 导入路径（含失败清理）、`archive_bundle` （此前零测试）、信任边界的 6 类拒绝用例与合法路径成功用例。 - 按新契约更新既有调用点：`MockFaissStore` 签名、`load_snapshot` 直调改为传 `snapshot_root` 并构造 ACTIVE_SNAPSHOT 标记。 质量门（全部实跑）：pytest 1247 passed、ruff format/check、mypy 49 files、 bandit -ll、compileall、uv lock --check、git diff --check。 端到端烟测：`main.py --smoke-test` 正常、`CHAT_TOP_K=0` 仍走脱敏消息、 合法活动快照可加载且根外/未激活目录被拒。
清理边界（本轮最主要的发现） - `cleanup_temp_files()` 已在 atexit 注册，每次程序正常退出都会对 `settings.cache_path` 执行 `shutil.rmtree`，但删除前没有任何安全判断，而 `cache_path` 是用户可配置项且校验只做相对路径转绝对路径。 - 实测 `Settings(cache_path="/")`、`"/etc"`、`"/usr"`、`"~"`、`"/var"`、 `"/System"`、`"../.."` 全部被接受，随后整个目录被删掉——用 tmp 目录复现确认 内容确实消失。这是不可逆的数据丢失，且触发条件是「配置文件写错一个值」。 - 新增 `_reject_unsafe_cache_dir()`：拒绝文件系统根目录、家目录本身、以及 `/etc`、`/usr`、`/bin`、`/sbin`、`/var`、`/System`、`/Library`、`/Applications` 这些系统目录，拒绝原因写入日志。 - 判定只看「是否危险」而不看「目录名是不是 .cache」：用户可能有意把缓存放到 `data/cache`，按名字判断会误伤（已加用例守住这一点）。 - 顺带补上「路径存在但不是目录」的分支（原先会把文件路径交给 rmtree）。 本地工作文件 - `HANDOFF.md` 加入 .gitignore：按约定不入库，且它可能含 API Key、令牌等敏感 信息，只作为本地交接备忘。 - `.review-*.html` 加入 .gitignore：审查过程生成的一次性复核报告（按快照哈希命名）。 - 两个文件仍在磁盘上，只是不再出现在 `git status` 里。 覆盖补充（按「覆盖核心即可」的原则，只补真正缺的核心路径） - 新增 `tests/test_cleanup.py`（15 条）：这是原先零覆盖的 atexit 删除路径， 失败后果不可逆，属于必须有人守的核心边界。 - 盘点后确认另外三个未被测试引用的模块不值得测：`src/ui/config_menu.py`（260 行 questionary 交互胶水）、`src/ui/display_utils.py`（纯格式化）、 `src/retrieval_test/excel_logger.py`（召回测试输出，非核心链路）。 - 其中两条夹具测试（用 tmp_path 冒充文件系统根/家目录）写完发现不可能成立—— 真实 `Path` 的 `anchor` 恒为 `/`，无法伪造——已删除，根目录与家目录判定改由 直接针对 `_reject_unsafe_cache_dir` 的参数化用例覆盖。 质量门（全部实跑）：pytest 1262 passed、ruff format/check、mypy 49 files、 bandit -ll、compileall、uv lock --check、git diff --check。 端到端：`main.py --smoke-test` 正常退出，安全判断不误伤正常缓存目录。
测试总数此前记录为 1119，实际已增至 1262（b424bb3 起四轮修复新增的回归断言）。 数值取自 `uv run pytest -q --collect-only` 的实际收集数。
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
目的
仓库此前只配置了 Ruff lint，没有 formatter，导致代码风格不一致：混用单引号与双引号、行尾空白、手工对齐。本次引入
ruff format并全仓库应用。同时补上 CI 质量门禁——本分支引入的格式化配置与 1033 项测试此前没有任何 CI 执行（
release.yml只在v*标签触发构建），质量工具处于「加了但无人运行」的状态。顺带修正
AGENTS.md中「未配置独立 formatter」的陈述——该说明已不成立。影响范围
16 个提交（60 个文件，
+6258 / -2334）。build: configure ruff formatter with a 100 column limitpyproject.toml新增[tool.ruff]（行宽 100、py311）与[tool.ruff.format]（双引号、空格缩进、LF）style: apply ruff format across the repositoryci: run quality checks on pull requests and main.github/workflows/quality.ymldocs: record the formatter configuration in guides and changelogAGENTS.md、CHANGELOG.md其余 12 个提交是格式化落地后多轮审查发现的缺陷修复，涉及凭证脱敏、Provider 能力门禁与响应归一化。逐条记录在
CHANGELOG.md的1.4.0段「安全」与「Provider 与协议」小节。为什么是 100 列而不是默认的 88
既有代码本就按约 100 列书写：88 列下有 1875 处超限行，100 列下只有 664 处。沿用 88 会把大量本可单行的完整表达式折成多行，产生无意义的 diff。实测四档改动行数：
100 列比 88 列少约 40% churn，同时是通行标准。
语义等价验证
格式化只应改表示、不改语义，这一点做了两层独立验证：
ast.parse比对格式化前后的语法树（剥离 docstring 后逐节点比较）——语法树完全一致。recursive_text_splitter.py中一行尾随空白被清除，文字内容未变。抑制标记未失效：
nosec与type: ignore若被格式化打断，对应工具会立刻报错——实际 bandit 仍报 0 问题（说明pickle.load的 B301 抑制仍生效），mypy 仍报 0 错误（说明 9 个文件里的type: ignore仍在原位）。仓库中不存在fmt: off/skip指令，格式化可安全全局应用。CI 门禁
.github/workflows/quality.yml在 PR 与main推送时执行 8 步，顺序与AGENTS.md列出的本地检查一致：格式化检查放在最前，因为它的失败最容易被后续步骤的输出淹没。
注意：CI 是仓库级配置，而它含
ruff format --check。若把本 PR 排在 #1 之前合并，main上会先出现门禁而代码尚未格式化，CI 会红。必须先合 #1。验证命令
全部 8 步已在本地逐条模拟通过，CI 实际运行结果亦为 pass。
历史重写说明
本分支做过三次
filter-branch历史重写，用于清除测试夹具与文档示例里会触发密钥扫描的合成值：sk-proj-AbCdEfGh…、AIzaSyAbCdEfGh…这类顺序字母拼接huntertwo、letmein两个已知弱口令词sk-abcdefghijklmnopqrstuvwxyz0123456789、sk-live-1234567890abcdef等顺序字母数字与sk-live-前缀加十六进制的形态这些值不是真实凭证，全部是脱敏规则的测试输入或文档占位符。替换为带
FAKE标记的值，长度与字符构成保持在受测规则命中的范围内，语义不变。重写只作用于本分支（
chore/ruff-format自身的提交），main与 #1 未受影响——#1 的提交保持原样，因此本 PR 对 #1 的堆叠关系不变（PR 状态为mergeable）。已逐提交核对本 PR 范围内的全部提交树：无残留。.env.example与docs/中的占位符（sk-your-openai-compatible-key、sk-xxxxxxxxxxxxxxxxxxxx）保持原样——它们是全占位形态，扫描器不视为密钥，且自main起即存在，非本次引入。键名判定的一致性
文本脱敏与配置边界现在共用
is_sensitive_option_key这一个判定函数。此前文本层用正则的字符断言去逼近它的切词逻辑，两者无法自然对齐，passwordHash、tokenCount、cookieJar这类「凭证词 + 另一个词」的键出现双向不一致——真凭证在日志里明文输出，而键名相同的合法配置值又在边界被误拒。现在文本层捕获完整键名后调用同一个函数，一致性由构造保证。键名本身（含凭证词即判敏感）的保守取向不变：
passwordHash存的就是密码哈希，判敏感是有意为之，不是需要放宽的过度严格。改动用 71568 条键值形态语料做了差分验证：14592 条由明文改为脱敏，零回归（没有一条从脱敏变回明文）。
配置与生成数据影响
无。不新增运行时配置项，不改动
config.toml口径，不涉及生成数据。新增的quality.yml只读仓库内容，权限为contents: read。备注
HANDOFF.md（本地交接记录）不在提交内。🤖 Generated with Claude Code