last30days-skill：GitHub 搜索限定符冲突的剥离机制与 Residual Review Findings 深度解析

本文基于仓库中 Residual Review Findings 记录，解读 last30days-skill 的 GitHub 源适配器中"Planner 注入的搜索限定符与适配器自身日期窗口冲突"这一缺陷的完整脉络：strip_search_qualifiers 剥离逻辑的设计与行为边界、限定符独占（qualifier-only）主题的错误信封语义、端到端测试如何固化这些行为，以及一次自动化代码评审（ce-code-review）所沉淀的 4 项待修复发现与 3 项残余风险。读完后，你可以复现该模块的判定逻辑，并理解"report-only 冲突记录"这类工程流程文档在多人协作仓库中的作用。

1. 背景：一次代码评审记录是什么

该记录文件的开头声明了其运行上下文：这是对分支 fix/github-qualifier-strip（提交 42c5ab5bebcb3d4bd4d8bfc11f89b4df4bc1da9b）执行 ce-code-review（mode:agent）后产生的评审发现存档。这些发现在 LFG 流程的第 5 步未被直接应用，而是"filed for durability"（登记以保证持久可追溯）。记录中分三类组织发现：

• Filed（已立案）：4 项发现（P1×1、P2×2、P3×1），登记到 GitHub Issues（issue #951 至 #954），全部指向 github.py 中限定符剥离相关的代码行；
• Settled-conflict findings（已裁决冲突，report-only）：2 项发现与 KTD-1（会话内已裁决的计划决策：qualifier-only 主题应返回错误信封）相冲突，因此只记录、不申请应用；
• Residual risks（残余风险）：3 项从评审中带出、暂不立案的潜在问题。

要读懂这些发现，需要先理解它们所针对的底层缺陷——也就是 issue #949 所描述的限定符冲突问题。

2. 缺陷根因：两个 created: 限定符谁说了算

问题出在 last30days-skill 的查询规划层（planner）：LLM 规划的子查询主题串里有时会直接写入 GitHub 搜索限定符，例如 "open source AI stars:>1000 created:>2025-03-20"。而 search_github 在构造查询时会追加自己维护的日期窗口 created:>{from_date}。源码中的注释（github.py#L169-L183）完整记录了冲突链：

1. 两个 created: 限定符同时出现时，GitHub 只认第一个，静默忽略适配器追加的那个；
2. API 于是返回了窗口之外的条目；
3. 这些条目又会在 parse_github_response 的本地日期过滤中被整体丢弃；
4. 最终表现为"一个抓到了结果、却汇报零条结果的源"（issue #949）。

3. 剥离机制实现：QUALIFIER_KEYS 与正则

修复的核心是 strip_search_qualifiers：在进入查询构造前把主题串里的 GitHub 搜索限定符全部剥掉，只保留自然语言主体。实现分三层（github.py#L176-L198）：

第一层：限定符词表。 QUALIFIER_KEYS 是一个 36 项的 frozenset，覆盖 GitHub 搜索语法中的限定符关键字（archived、author、created、is、label、language、repo、stars、state、type、updated 等）。

第二层：剥离正则。 _QUALIFIER_RE 的构造值得逐段拆解：

_QUALIFIER_RE = re.compile(
    r"(?:(?<=[\s,;])|^)(?:" + "|".join(sorted(QUALIFIER_KEYS)) + r"):(?:[<>]=?)?(?:\"[^\"]*\"|[^\s,;()\[\]]+)[,;]?",
    re.IGNORECASE,
)

• (?:(?<=[\s,;])|^)：限定符必须出现在串首，或紧跟空白、逗号、分号之后——这避免了误伤 state of the art 中不带冒号的普通单词（词后必须有 : 才触发）；
• :(?:[<>]=?)?：可选的比较符前缀，覆盖 stars:>1000、created:>=2025-01-01 等形态；
• (?:\"[^\"]*\"|[^\s,;()\[\]]+)：值部分。引号值 "bug fix" 整体消费（跨越空格）；普通值则停止在空白、逗号、分号、括号、方括号处，不会贪吃后一个主题词（如 created:>2025-03-20,robotics 中的 robotics 必须存活）；
• 末尾可选的 [,;]? 把粘连的分隔符一并吃掉，让 "ai,created:>2025-03-20" 这类 planner 输出不残留尾逗号。

第三层：归一化。 strip_search_qualifiers 用 " ".join(...split()) 折叠连续空白，并在 docstring 中明确约定：当主题"只剩限定符"时返回空串，调用方必须处理，绝不能用空词搜索（空词会匹配整个站点，随后被日期过滤丢弃成一次假"无结果"）。

4. 判定边界：qualifier-only 路径的错误信封

search_github 在剥离后（github.py#L226-L245）：

core = extract_core_subject(topic)
plain_core = strip_search_qualifiers(core)
if plain_core != core:
    _log(f"Stripped search qualifiers: '{core}' -> '{plain_core}'")
if not plain_core:
    _log("Topic contained only search qualifiers or was empty; nothing to search")
    return {
        "items": [],
        "context": {"core": core, "from_date": from_date,
                    "to_date": to_date, "count": count},
        "error": (
            f"GitHub topic contained only search qualifiers or was empty: {topic!r}"
        ),
    }

要点有三：其一，剥离发生在 extract_core_subject 之后，即"取核心主语"与"剥限定符"是两道独立的防线；其二，qualifier-only 与空主题走同一条报错短路路径，不发起任何网络请求；其三，返回的仍是一个与其他适配器一致的 envelope 形状，但携带 error 字段——从源码结构看，这个 error 字段会决定下游管道对该源的分类（成功 / 尝试但失败 / 错误），这正是后文 P1 发现的关注点。

5. 端到端测试如何固化行为

test_github.py 中的两个测试类覆盖了该机制的全部边界，可作为验证清单：

TestStripSearchQualifiers（纯函数层）：

用例	输入	期望输出	固化的行为
混合主题	open source ai stars:>1000 created:>2025-03-20	open source ai	基本剥离
无冒号普通词	ai in healthcare	原样	in 不带 : 不是限定符
大小写	Stars:>1000	空串	忽略大小写的纯限定符主题
斜杠值	repo:facebook/react bug	bug	值类消费 /
逗号粘连	ai,created:>2025-03-20	ai,	分隔符后紧跟的限定符
分号粘连	ai;created:>2025-03-20	ai;	同上（分号）
引号值	label:"bug fix" open source	open source	引号值整体消费，不残留 fix" 碎片
粘连主题词	created:>2025-03-20,robotics	含 robotics	值类在分隔符处停止，不吞后续词

TestSearchGithubQualifiers（search_github 端到端层）验证了查询串只含一个 created:（q.count("created:") == 1 且为适配器自己的窗口）、qualifier-only 主题 mock_fetch.assert_not_called() 零网络调用、state of the art ai 中 state 存活进入查询，以及认证场景下 is:issue / is:pull-request 双分区合并去重并按 reactions 重排。

6. 本次评审登记的 4 项发现（Filed）

以下 4 项即记录文件 "Filed (tracker: GitHub Issues)" 一节的全部内容，逐条给出源码级解读：

P1 — 限定符独占主题被判 ERROR，污染重试资格（issue #951，github.py:237）

第 237 行是 qualifier-only 路径的 return 语句：该路径返回的 envelope 带 error 字段。评审发现，这个下游的 ERROR/attempted 分类会阻断管道层的瘦结果重试机制。对照 pipeline.py 中的 _retry_thin_sources：它对"结果少于 3 条"的源发起简化核心主语的重试，但筛选条件显式排除了 source not in bundle.errors_by_source——即已被记为错误的源不会进入重试队列。从源码结构看，一次 qualifier-only 子查询把 GitHub 源标成 ERROR 后，该源在整个 run 内都失去了走瘦结果补救通道的资格。该发现被标注为 settled-conflict: report-only per KTD-1：KTD-1 是会话内已裁决的计划决策——"qualifier-only 主题返回错误信封"本就是计划行为，因此登记 issue 只为持久化，不申请修改代码。

P2 — 引号包裹或括号包裹的限定符绕过剥离（issue #952，github.py:186）

第 186 行即 _QUALIFIER_RE 定义。(?:(?<=[\s,;])|^) 这个位置断言要求限定符前是空白/逗号/分号/串首；当 planner 输出整段被引号或括号包裹的形态（如 "stars:>1000" 或 (created:>2025-03-20)，冒号前是 " 或 ( 而非空白）时，正则不会匹配，限定符可能残留进最终查询，重新制造 issue #949 的双 created: 冲突。

P2 — 空主题或"噪音+限定符"主题翻转为硬 ERROR（issue #953，github.py:231）

第 231 行 if not plain_core: 分支把空主题与 qualifier-only 主题一视同仁地翻转为携带 error 的硬失败。评审认为这与 KTD-1 / R3 的裁决（此类主题应返回错误信封）存在边界争议——例如主题中还有无法构成有效查询的"噪音词"残留时，硬 ERROR 与"正常搜索但零结果"的语义边界不清。同样标注 settled-conflict: report-only per KTD-1，登记 issue #953 仅为持久化。

P3 — 重复的 qualifier-only 子查询刷屏日志与错误详情（issue #954，github.py:229）

当 plan 里多个子查询都退化到 qualifier-only（例如 planner 对多个实体各生成一条限定符串），每条都会执行第 229 行附近的 Stripped search qualifiers 日志与第 236 行的 Topic contained only search qualifiers or was empty 日志，并在各自的 envelope 中写入完整的 topic!r 错误详情——子查询数量放大时，日志和错误详情会出现重复刷屏。

7. Settled-conflict 小节：为何"已裁决冲突"只报不修

记录文件的 "Settled-conflict findings (report-only, not filed as apply requests)" 一节对上述 P1/P2 两项做了补充说明，这是理解 ce-code-review 流程的关键：

• 两项发现都与 **KTD-1（session-settled plan decision）**冲突——即在制定计划阶段（对应计划文档 fix-github-qualifier-collision 的会话）已经裁决"qualifier-only 主题返回错误信封"这一语义。发现本身技术上成立（如 P1 指出的 _retry_thin_sources 阻断效应），但修改它会推翻既有裁决；
• 因此这些发现"filed as #951/#953 for durability, not for application"——issue 是证据存档，不是待修工单。
• "No sink / failed" 一节为 None，说明所有发现都成功落盘；"Proceeded-and-flagged settled-decision conflicts (from ce-work step 2)" 一节亦为 None，说明 ce-work 步骤 2 没有额外返回需继续放行但打标记的冲突决策。

8. 评审带出的 3 项残余风险

记录文件 "Residual risks carried from the review" 一节列出了三条暂不立案、但需要被后续读者知晓的风险，逐条对照源码验证：

1. 错误信封中 context["core"] 未剥离，而成功路径已剥离；当前无消费者受影响。 对照源码确实如此：qualifier-only 分支返回时 context 里的 "core" 用的是 extract_core_subject(topic) 的原始结果（github.py#L237-L244），而成功路径在 github.py#L245 执行 core = plain_core 后，parse_github_response 消费的是剥离后的 context["core"] 用于计算相关性（_compute_relevance）。两条路径的 context["core"] 语义不一致，属于潜在的地雷而非现网缺陷——记录也明确写了 "no current consumer is affected"。
2. GitHub 对未闭合引号返回 422 是外部 API 行为，未被测试覆盖。 _QUALIFIER_RE 的值类 \"[^\"]*\" 只消费闭合引号；planner 若输出未闭合引号（如 label:"bug），残留在查询串中会触发 GitHub /search/issues 的 422，而仓库测试只覆盖了闭合引号形态。这是外部依赖行为，单测只能靠 mock 固化己方逻辑，无法替 GitHub 背书。
3. planner 吐出逗号粘连、带引号、包裹形态的限定符是 LLM 行为；暴露面无法从代码量化。 这一条点明了整个缺陷类别的根本性质：输入形态的空间由 LLM 生成，而正则剥离只能覆盖"已观察到的形态"。测试类中 ai,created:...、label:"bug fix" 等用例都是对历史观察形态的回归保护，新形态出现时需要补正则与补测试。

9. 从这份 Findings 文档学到的工程实践

该记录虽然只有几十行，却完整展示了一种可复用的评审存档范式：

• 发现必须落到精确行号与 issue 编号：4 项 Filed 发现全部带 文件:行号 与 issue 号，使"评审意见"可被后续任何一次评审直接交叉引用；
• 区分"可应用"与"已裁决冲突"：settled-conflict 发现单独成节并标注 report-only，避免自动化流程误把推翻会话裁决的修改当作普通 bugfix 应用；
• 残余风险独立成节：不满足立案条件（无法复现、外部行为、不可量化）的风险不丢弃，而是显式 carry 到文档里，防止下轮评审重复发现或遗忘。

如果你要复核本文的全部论断，入口是三个文件：记录本体 42c5ab5bebcb3d4bd4d8bfc11f89b4df4bc1da9b.md、被评审的实现 github.py（限定符剥离与查询构造集中在 L169–L343），以及验证这些行为的测试 test_github.py（TestStripSearchQualifiers 与 TestSearchGithubQualifiers 两个类）。管道侧重试资格的判定在 pipeline.py 的 _retry_thin_sources。需要说明的适用前提：本文所有行号与行为描述均以当前仓库快照为准；记录文件提及的计划文档（2026-08-07-001-fix-github-qualifier-collision-plan.md）在当前仓库中不存在，文中对 KTD-1 的转述以该记录文件自身文字为限。