错误码、接口字段、任务参数具有精确含义。E2013、external_order_id 应保留完整词形；中文按双字组合做轻量分词，英文标识与数字按正则保留。这比引入额外分词服务更易理解，但对中文词义、停用词和混合语言处理都比较粗糙。
BM25 使用 k1=1.5、b=0.75：同一个词重复出现会饱和，较长文档做长度修正，低频词获得更高 IDF。代码在经过权限与版本筛选的候选集合上计算词频与 IDF，不让其他客户的私有案例参与当前排名统计。
向量分支先将文档和查询 L2 归一化，再计算点积，即余弦相似度。live 模式下向量来自真实 Embedding API；demo 只是 Blake2b 稳定哈希后的词法计数，能测试矩阵和排序链路，但不能理解“乱码”与“汉字全乱了”的同义关系。
两个分支的分数范围不同，不能直接相加。RRF 根据排名融合：
score(chunk) = Σ 1 / (60 + rank_in_branch)
当前每分支最多 30 个候选，最终默认 Top-5。RRF 的 60、demo 余弦门槛 0.08、live 门槛 0.25 都是初始参数；RRF 分数不是置信概率。真实使用前要在新问题集上调参与验证，不能把演示结果当作参数合理性的证明。
同一个 E2013，在 v1.0 文档中是缺少 order_no，在 v2.0 文档中是旧模板尚未迁移到 external_order_id。不加版本过滤，检索结果看起来很相关，却可能让用户执行错误步骤。
因此先读取当前客户版本，再做版本和模块过滤，最后排名。客户不能在请求体里修改自己的检索版本；客服做实验时可以主动指定版本。文档阅读列表会列出共享历史文档，版本限制主要在实际检索与调查链路中执行。
分诊输出小且严格的路由对象；调查面对知识片段、任务记录、历史工单并拥有只读工具；协同处理的是调查结论和允许的动作建议。三者的提示词、输入上下文和输出责任不同。
不必每个请求都经过三个节点：信息不足可直接澄清。当前复杂调查依次经过三个节点，会增加模型调用次数和延迟。对非常简单的使用咨询，三个角色的收益可能小于成本；简历应写“按职责编排并设置条件分支”，不写“多 Agent 必然优于单 Agent”。
可做的后续实验是：在相同任务集和相同模型下比较单 Agent 与三角色编排的正确率、调用次数、总 token、延迟，再决定是否给简单问题增加更短路径。当前未完成这项实验。
模型不能传入 customer_id 或产品版本来改变工具作用域。get_task 查询明确包含当前客户条件；工具名采用白名单，参数通过 Pydantic 校验。调查 Agent 即使输出 create_ticket，也会被拒绝。
当前调查工具为环境查询、任务查询、知识检索、当前客户历史工单查询和已知问题查询。工单创建是用户确认后的 HTTP 业务操作；协同 Agent 生成草稿，不拥有任意写库或任意 HTTP 请求能力。
提示词要求把文档和工具文本作为数据，但提示词不能消除提示注入。更可信的边界是：后端身份范围、只读工具集合、严格参数、预算、最终写入接口的权限和事务约束。没有声称实现通用提示注入检测器。
幂等回答“用户重试会不会创建两张工单”。同一 actor 的 key 绑定一次具体升级操作；不同 key 对同一个 run 仍由唯一约束保证一张工单。
修订号回答“客服和技术同时操作，会不会互相覆盖”。前端提交其读取的 revision，后端不接受过期 revision。冲突返回 409，而不是自动合并业务决定。
短事务回答“单据和处理记录能否一起成功”。工单更新、处理事件、问题关联在同一个事务中完成。Embedding 等外部网络调用放在事务外，避免持锁等待远程服务。
SQLite BEGIN IMMEDIATE 会串行化写入，WAL 改善读写并行，不代表可以并行提交多个写事务。写入压测中出现较高 P99，就是值得观察的单机边界；不能称之为高并发分布式事务方案。
文档和向量在同一 SQLite 数据库提交，减少“双写数据库与向量库”问题。新文档在成功得到所有向量后才进入事务。发布草稿前再次校验草稿内容和工单状态，避免长时间计算后发布过期结果。
索引修订号与内容在同一事务更新。检索缓存发现修订号不同后，用读事务获取一致快照，整体替换矩阵和词频数据。一个已经开始的请求可以用其旧快照完成；不承诺正在进行的请求在工单重开瞬间全部取消。后续新请求会刷新索引。
模型指纹由 Embedding endpoint 与 model 标识形成；它能检测配置变化，不能发现供应商在同一个 model 名称下静默替换模型。因此还会在查询时校验维度；生产环境应固定供应商模型版本并增加索引管理。
服务端建立本次实际召回的 chunk ID 集合，协同输出中出现集合外的引用就拦截。这样能避免“凭空编一个参考文献 ID”。
但模型可以引用真实片段，却错误理解或扩大结论。当前没有自动事实蕴含判定，也没有声称零幻觉。评测时需要人工标注答案是否被证据支持，并检查是否遗漏限制条件、是否误把猜测当根因。
分开报告：检索端点、完整调查、建单事务。成功 RPS、成功请求 P95/P99、429 比例要同时出现。429 是准入拒绝，不算成功吞吐；一次上游未被调用的快速拒绝，也不能拿来证明 Agent 高性能。
报告注明 Windows、Python 版本、单 worker、localhost、512 个片段、热查询向量缓存、demo 无真实模型延迟。500 个文档是合成的性能文本；检索回归的 12 篇文档与 24 条题是另一套规模较小的人工样例。
短时加压可以发现资源竞争和限流行为，不能证明长时间稳定性或生产容量。接入真实模型后还要测供应商限额、超时、调用成本、真实检索质量与模型输出质量。
项目名建议：ResolveDesk · SaaS 售后诊断与工单协同平台（个人项目）。
面向软件售后场景，开发覆盖客户咨询、证据调查、工单升级、技术处理、客户确认和案例回流的应用。使用 FastAPI、LangGraph、SQLite 与 NumPy，实现版本感知检索、受限工具调用和可追踪的业务处理链路。
在自己通读、复现并能解释代码后，可以按实际参与情况使用以下表述：
- 构建分诊、调查、协同三个角色的 LangGraph 条件流程，接入兼容接口的聊天与 Embedding 服务，限制工具集合、调用预算与总执行时限。
- 实现 BM25、向量余弦检索及 RRF 融合，在召回前执行客户范围、产品版本与模块过滤，保留引用片段及排名分数以便比较。
- 实现工单幂等提交、基于 revision 的并发冲突检测、人工问题关联与客户确认状态机，保存处理事件和证据快照。
- 打通知识草稿审核发布和工单重开撤回流程，用数据库事务与索引修订号维护知识内容和检索快照的一致性。
- 构建自动化业务测试、人工检索回归集及独立 HTTP 压测脚本，分开报告工程链路与真实模型效果。
不要直接写： 已服务真实企业、生产部署、真实模型准确率 100%、百万级向量检索、高并发分布式平台、自动故障修复、MCP、GraphRAG、断点续跑。当前没有这些实现或证据。当前代码由 AI 协助生成，也不应在尚未掌握时声称完全独立手写。
- 给 v1/v2 分别问 E2013，临时移除版本过滤，观察错误答案为何出现，再恢复。
- 同时提交两次同一个升级请求，检查唯一约束与幂等表；再用不同幂等键重复提交。
- 两个浏览器读同一个 revision，分别更新，观察第二个请求的 409。
- 发布一个带独特词语的私有案例，用另一个客户检索；然后重开原工单，检查案例撤回。
- 配置自己的真实模型，补充没有沿用文档措辞的新问题集，手工检查引用支持性、失败升级行为与调用成本。