feat: add extensible offline knowledge pipeline

[xjx-star]

变更范围

阶段十一 CodeSense:knowledge-rag:stage11 交付：把阶段十的作业级显式知识证据接入一个可演进、离线优先的流水线契约，并完成一个可验证的真实行为改进。

• 新增 services/knowledge_pipeline.py，定义可替换的切分、嵌入、候选召回、重排和引用构造契约。
• 提供纯标准库默认实现：段落切分、透明词法嵌入、词法候选召回、稳定优先级重排、稳定引用构造。
• services/knowledge_rag.py 通过适配器接入流水线；routes/api.py 将已校验的学生问题传入当前作业范围内的重排阶段。
• 修复评审指出的兼容性和边界问题：同权重、空问题或无匹配问题时按数值记录 ID 排序；候选召回在截断前先按匹配分数排序，避免后置高匹配候选被 limit=1 漏掉；保留原有 assignment-kp:<id> 引用 ID。
• 明确适配器最多向流水线提供 8 条候选；新增超过 8 条时的边界回归，验证流水线只在该有界候选池内重排，不扩大数据库读取范围。
• 保持作业隔离、最多 8 条最终证据、私有学生评分隔离、既有 JSON/SSE 字段和无结果回退；不改数据库结构、权限、部署或生产密钥。
• 新增 KNOWLEDGE_RAG_STAGE11.md，记录系统地图、观察、可证伪假设、指标、取舍、风险、回滚和后续建议。

修复前失败与验证

• 修复前：在 origin/main 临时基线工作树运行 test_stage11_query_reaches_knowledge_adapter，旧 _retrieve_knowledge_context() 只接受一个参数而失败：TypeError: ... takes 1 positional argument but 2 were given，退出码 1。
• 评审指出的排序问题已复现并修复：字符串排序会把记录 ID 10 排在 2 前；新增空问题和无匹配问题回归后，最终按数值 ID 排序，同时保持外部引用 ID 不变。
• 评审指出的截断问题已复现并修复：候选召回现在先按分数、优先级和稳定键排序，再应用 limit；新增“后置匹配候选在 limit=1 时仍返回”的测试。
• 定向命令：python -m pytest tests/test_knowledge_pipeline.py tests/test_knowledge_rag.py -q --disable-warnings：13 passed，退出码 0，33.38s。
• 跨 SSE 命令：python -m pytest tests/test_knowledge_pipeline.py tests/test_knowledge_rag.py tests/test_ai_sse_routes.py -q --disable-warnings：19 passed，退出码 0，66.74s。
• 全量命令：python -m pytest -q --disable-warnings：665 passed，退出码 0，13:22。
• git diff --check：通过。
• 离线容量样本：100 个文档、100 次运行、top-k 8；mean 2.054 ms，P95 2.649 ms。
• 当前提交：08b51ec932acf88375e1502fed808c054d7b2aef。

事实与推断边界

• 已确认事实：以上测试和容量样本在隔离工作树、无生产凭据的本地环境中通过；默认流水线只依赖 Python 标准库；适配器候选池上限为 8。
• 仅属推断：词法基线可能改善同词问题的证据排序，但不等同于语义相关性提升；本地毫秒级结果不代表真实数据库、向量服务或模型服务 SLA。
• 未验证：真实 Redis、外部 AI、生产数据库、并发压力、浏览器全流程和线上知识库质量。

合并与后续边界

• 阶段十基础 PR feat: add assignment knowledge evidence baseline #48 已合并；阶段十后续修复 PR fix: harden stage10 knowledge retrieval boundaries #49 仍是独立 PR，可能与本 PR 在 routes/api.py 和 services/knowledge_rag.py 发生文本合并冲突。建议维护者先确定 fix: harden stage10 knowledge retrieval boundaries #49/feat: add extensible offline knowledge pipeline #50 的合并顺序，再按最终 main 重放另一分支；本 PR 不把 fix: harden stage10 knowledge retrieval boundaries #49 的修复混入自身范围。
• 当前不接入向量数据库、外部嵌入服务或生产密钥；若后续需要这些能力，应另做数据脱敏、权限、成本、容量和部署评审。

[XiaoCow666]

结论：需要修改 1 项排序兼容性问题。仅静态审查了所提供的 diff，未运行工具、测试或仓库代码；任务台包含具体的基线失败、行为改动和回归验证记录，但测试通过情况属于贡献者报告。

1. [P2] 相同权重、无词法匹配时，记录 ID 的排序发生变化。
   • 位置：services/knowledge_pipeline.py::StablePriorityReranker.rerank，以及 services/knowledge_rag.py 中 document_id=f"assignment-kp:{record.id}" 的构造。
   • 证据与影响：当前用字符串 document_id 排序，因此同权重的记录 2、10 会按 assignment-kp:10、assignment-kp:2 返回。旧实现和本次文档承诺按记录 ID 保留顺序；空问题或没有匹配词时，会改变证据次序及 [K1] 指向。现有测试使用字母 ID，没有覆盖此情况。
   • 修改指令：请打开上述两个文件的对应函数，将“直接按字符串 document_id 作为作业记录的排序键”改成“按数值记录 ID 打破同分、同权重的平局”。可以由适配器通过明确的元数据字段传入数值 ID，并在重排器中使用；普通文档仍保留确定性的排序规则。
   • 验证：请在 tests/test_knowledge_rag.py 增加同权重记录 ID 为 2、10 的回归用例，分别用空问题和无匹配问题断言记录 2 在前，同时保留匹配证据优先的断言。然后运行 python -m pytest tests/test_knowledge_pipeline.py tests/test_knowledge_rag.py tests/test_ai_sse_routes.py -q --disable-warnings。

其余已检查范围：API 在所示作业访问检查后传入问题；默认流水线使用标准库；适配器输出仍显式列出既有响应字段；新增测试覆盖问题相关排序、切分确定性和重排组件替换，符合阶段十一要求的真实行为改动与回归测试方向。

后续建议（非阻塞）：在 KNOWLEDGE_RAG_STAGE11.md 中补充容量样本的可复现脚本或完整命令。当前 PR description 已具体说明范围和未验证边界；修订后更新新增回归用例、实际执行命令和结果即可，不必声称已验证生产环境。

[XiaoCow666]

结论：基于提供的 diff，未发现必须阻塞合并的正确性或安全问题。阶段任务包含具体观察、失败证据、真实行为改动和回归测试；本次仅做静态审查，未执行命令，无法独立确认所报测试结果。

已核查范围：

• routes/api.py::ask_question 在现有作业访问检查之后，将问题传给检索适配器，使问题实际参与排序。
• services/knowledge_pipeline.py 提供五类可注入契约；默认排序依次比较词法匹配、来源权重和稳定 ID，最终按 limit 截取证据。
• services/knowledge_rag.py 保留旧证据字段和 assignment-kp:<id> 引用格式；新增路径未查询学生私有评分，也未引入外部服务或数据库迁移。
• 新增测试覆盖相关证据优先、确定性、重排组件替换、真实 HTTP 入口，以及 ID 2/10 在空问题和无匹配问题下的兼容排序。

后续建议（非阻塞，按优先级）：

1. LexicalCandidateRetriever.retrieve 当前先按输入顺序截取候选；默认流水线传入全部 chunk 数，因此当前入口不受影响，但单独使用较小 limit 时可能遗漏后面的匹配项。建议明确契约，或按匹配分数选取候选，并添加“匹配文档排在输入末尾、limit=1”的测试。
2. KNOWLEDGE_RAG_STAGE11.md 已说明候选池最多 8 条。建议补一个超过 8 条作业知识点的边界测试，明确当前只能在已选候选中重排，避免后续误认为支持全作业问题召回。
3. 任务台 verification_result 仍为 10/16/662 passed，而 PR 正文和文档为 11/17/663。请将任务台更新为对应提交的实际结果；首次贡献可沿用现有 PR 描述结构，补齐可复制的 python -m pytest tests/test_knowledge_pipeline.py tests/test_knowledge_rag.py tests/test_ai_sse_routes.py -q --disable-warnings 命令，并在合并其他分支后重新运行该命令及 git diff --check，记录提交 SHA、退出码和结果。

理解抽查：

1. 为什么空问题和无匹配问题都会回到权重排序？record_id 转成整数如何避免 ID 10 排在 2 前？
2. 如果最相关的知识点未进入适配器已有的 8 条候选，当前重排能否找回它？候选池上限与最终证据上限分别应在哪一层控制？

合并前隔离验证

• 结果：未通过
• 命令：gh repo clone
• 耗时：6146ms
• 摘要：Cloning into 'E:\CodeSense\pr-review-relay\data\work\premerge-hsWwic\repo'...
  fatal: unable to access 'https://github.com/XiaoCow666/CodeSense.git/': schannel: failed to receive handshake, SSL/TLS connection failed
  failed to run git: exit status 128

合并前验证未通过，本次不合并。请按上面摘要逐条处理：打开摘要中点名的文件和位置，把当前错误改成命令要求的行为；修复后重新运行同一条命令，再提交新的 head。

[XiaoCow666]

结论

通过。仅依据提供的元数据和 diff 静态复审，未发现必须修改的正确性、安全或兼容性问题；未调用工具，也未运行测试。任务台提供了具体的观察、设计取舍、行为改动和回归验证记录，符合本阶段交付要求；测试成绩属于贡献者报告，非本次独立复测结果。

已检查范围

• routes/api.py::_retrieve_knowledge_context / ask_question：将学生问题传入检索，调用仍位于作业访问权限检查之后。
• services/knowledge_pipeline.py：五类阶段契约及离线默认实现齐全；候选先按匹配分数、权重和稳定键排序再截断，避免末尾匹配被输入顺序排除。
• services/knowledge_rag.py::retrieve_assignment_knowledge：保留作业记录适配和原响应字段，明确映射输出元数据，没有新增私有评分读取；数值记录 ID 和 assignment-kp:<id> 引用兼容处理有对应测试。
• 新增测试覆盖真实提问入口重排、末尾匹配且 limit=1、重复执行稳定性、替换重排器及数值 ID 2/10 排序。超过 8 条记录的测试明确限定为候选池内重排，第 9 条以后无法找回；文档也披露了这一限制，不构成本次阻塞项。

后续建议（非阻塞，按优先级）

1. tests/test_knowledge_pipeline.py：补充长句硬切分、空内容和多段组合用例，断言每块长度不超过 max_chars，并检查内容与顺序，防止后续替换切分器时丢失文本。
2. PR description 的验证数字仍为 11/17/663，与任务台及 KNOWLEDGE_RAG_STAGE11.md 的 13/19/665 不一致。请更新为对应 08b51ec 的结果，并把省略号命令替换为可复制的 python -m pytest ...，方便首次贡献的验证记录被复现。
3. 合并前在最终合并版本运行 python -m pytest tests/test_knowledge_pipeline.py tests/test_knowledge_rag.py tests/test_ai_sse_routes.py -q --disable-warnings 和 git diff --check，记录提交号、命令及退出码。PR 中关于 #49 的潜在冲突不能据此认定为实际冲突。

理解抽查

1. 为什么 LexicalCandidateRetriever 已经先排序再截断，unique-ten 的测试仍然取不到第 10 条作业记录？截断分别发生在哪里？
2. 空问题且权重相同时，记录 ID 2 为什么会排在 10 前？record_id 和 evidence_id 两个元数据字段分别维持了什么兼容行为？

[XiaoCow666]

结论：通过。本次 diff 有真实行为改动和对应回归测试，未发现可确认的必要修改项。

已核查范围（仅静态审查，未调用工具或运行测试）：

• routes/api.py::ask_question 在作业访问权限检查之后传入学生问题，_retrieve_knowledge_context 将其转交检索适配器。
• services/knowledge_pipeline.py::LexicalCandidateRetriever.retrieve 先按匹配分数、权重和稳定键排序再截断，避免末尾匹配候选被提前丢弃；_stable_chunk_key 保持记录 ID 2 在 10 前。
• services/knowledge_rag.py::retrieve_assignment_knowledge 接入流水线，并显式保留旧证据字段和 assignment-kp:<id>。新增代码未读取学生评分记录，也未引入外部服务或数据库迁移。
• 新增测试覆盖真实提问入口排序、数值 ID 排序、组件替换及候选截断边界。第 9 条以后的记录仍无法进入当前候选池，这一限制已在测试和文档中明确。
• 任务台的观察、复现、设计取舍和验证字段具体，并有代码与测试交付对应。所报 665 项测试通过及性能数据属于贡献者提供的结果，本次未独立复验。

后续建议（不阻塞）：

1. 在 tests/test_knowledge_pipeline.py 补充长句硬切分及中英文混合标点用例，断言每块不超过 max_chars、内容无遗漏，增强切分边界覆盖。
2. 在 KNOWLEDGE_RAG_STAGE11.md 补充容量样本的生成方式和可复制运行入口，方便他人复现 mean/P95。
3. 当前 PR description 已说明范围和限制；首次贡献后续更新时，继续记录最终提交 SHA、实际验证命令及结果。若合并顺序导致代码调整，请在调整后的版本运行 python -m pytest tests/test_knowledge_pipeline.py tests/test_knowledge_rag.py tests/test_ai_sse_routes.py -q --disable-warnings 和 git diff --check，更新验证记录。

理解抽查

1. 为什么直接调用候选召回器时，末尾匹配项能在 limit=1 下返回，而作业适配器仍找不到第 9 条以后的匹配记录？请指出两个截断位置的区别。
2. 空问题或无匹配问题时，哪些排序字段保证记录 ID 2 排在 10 前？为什么保留 assignment-kp:<id> 作为外部证据 ID 不会再次导致字符串排序问题？