Spark Program | Nervos Brain - A Global Developer Onboarding Engine and Cross-Language Hub Powered by Agentic RAG

English
,
34

第八周周报

一、本周目标

本周重点从离线评测和工具闭环，转向 Telegram 群内测、线上部署和真实使用反馈。目标不只是让 Bot 能在测试群里回答问题，而是观察它在真实群聊环境中的稳定性：是否会误触发、是否能隔离不同用户上下文、是否能正确检索官方文档和论坛资料、是否会过度追问，以及线上异常能否通过日志快速定位并修复。

本周关注的核心问题包括：

  1. 群聊中不同用户的上下文是否会互相串扰。

  2. Bot 是否会错误插入普通群聊。

  3. 用户连续追问时，系统是否能正确理解上文。

  4. 检索结果、引用和 source 选择是否稳定。

  5. Agent 是否存在过度追问、答非所问、格式异常或无限重试等影响体验的问题。

  6. 多用户同时提问时，Telegram runtime 是否能并发处理。

  7. 用户上传文本文件或图片时，系统是否能把附件纳入回答上下文。

  8. 线上问题是否能通过日志、debug event 和回归测试快速定位。

二、本周完成

2.1 Telegram 群内测与真实反馈闭环

本周开始在 Telegram 群中进行真实内测。测试不再只依赖人工构造的离线样例，而是让用户围绕 CKB、Nervos、Fiber、CCC、Agent 钱包、链上应用、游戏项目、新手学习路线和官方资料等主题进行自然提问和连续追问。

真实群测暴露出的行为比离线样例复杂得多：用户会用“它”“这个”“继续说”“有没有靠谱资料”“官方没有教程吗”这类短句承接上文；不同用户会在同一个群里交叉提问；用户也会直接纠正 Bot“你是不是回复错问题了”。这些反馈帮助我们把问题从“可能发生”变成“有日志、有复现、有测试”的工程闭环。

2.2 群内用户上下文隔离与触发策略

本周完成了 Telegram 群内短期记忆隔离改造，将上下文粒度调整为“群/频道 + 用户”。系统默认读取同一用户在同一群内最近 20 条与 Bot 相关的消息，并注入 full graph 作为短期上下文。

这样可以避免同一个群里 A 用户和 B 用户的对话互相污染，同时支持“我刚才问了什么”“继续说”“看看上文”这类短期追问。AskUser 的 checkpoint 恢复逻辑也同步改成按用户隔离，避免 B 用户误恢复 A 用户的补参流程。

群聊触发策略也进行了修复：

  1. 私聊直接响应。

  2. 群聊中只有被 @、被回复，或收到 Bot 命令时才响应。

  3. 普通群聊直接忽略，不发送 typing，不写入 memory，也不进入 graph。

这让 Bot 在群内的行为更自然：用户需要它时可以明确唤起，不需要时它保持安静。

2.3 多用户并发处理

内测中确认了一个重要运行时问题：如果 Telegram polling 串行处理所有 update，不同用户同时提问时会互相排队，复杂问题会明显拖慢其他用户。

本周将 Telegram polling gateway 改成多线程并发处理：

  1. 不同用户/会话可以并发进入 graph。

  2. 同一个 chat + user 的消息仍按顺序处理，避免同一用户连续追问乱序。

  3. Telegram API 发送、debug event 写入和 feedback 写入增加锁保护。

  4. SQLite memory 连接配置调整为允许多线程访问。

这部分没有采用多进程，避免引入额外的进程间状态同步和本地 Qdrant/SQLite 资源竞争。

2.4 线上无限调用与 Telegram 发送失败修复

服务器重启后曾出现一次严重线上问题：Agent 不断调用模型 API，但用户一直收不到回复。定位后发现根因不是模型，也不是网络，而是 Telegram sendMessage 返回 400 后异常向外抛出，导致当前 update 的 offset 没有推进。polling 下一轮又拿到同一个 update，于是同一条消息被反复处理，造成模型 API 被重复调用。

本周修复为：

  1. sendMessage 失败后先从 MarkdownV2 降级为纯文本重试。

  2. 如果 reply 发送失败，再去掉 reply_to_message_id 作为普通消息重试。

  3. process_update 失败也不阻塞 offset 推进，避免同一 update 无限重放。

  4. 补充发送失败、offset 推进和 fallback 发送的回归测试。

这项修复显著降低了线上 Bot 因 Telegram 格式或 reply 状态异常导致循环消耗模型调用的风险。

2.5 多库检索与检索性能修复

本周将 GitHub 文档库和 Nervos Talk 论坛数据接入当前 runtime，形成多库检索能力。系统启动时会加载多个 retrieval backend，并在日志中打印已加载的后端，方便确认线上运行环境是否接入了论坛库和文档库。

同时修复了论坛检索的超时问题。此前 discourse_query 会在大库上重建或扫描过多候选，导致线上工具调用超过 10 秒并被取消。修复后改为先通过 SQLite 做更小范围的候选预筛，再进行排序，从而让论坛检索能在服务器配置下稳定返回。

工具调用默认超时时间也从 10 秒延长到 60 秒，避免慢但有效的检索被过早取消。

2.6 检索路由、source registry 与 qdrant fallback

真实对话中暴露出一个新的检索路由问题：用户问“有没有比较靠谱的资料可以看？”或“官方没有比较好的教程吗？”时，LLM 会自然生成 filters.source=official_docs，但当前数据库中官方文档实际 source 是 github_docs。这导致 qdrant_search 很快返回空结果，然后系统给出“知识库没有足够证据”的错误回复。

本周对此做了更稳的架构调整：

  1. 新增 retrieval source registry，统一定义当前合法 source。

  2. planner prompt 注入合法 source 和每个 source 的内容范围。

  3. 运行时对 LLM 生成的 filters 做 normalize 和 validation。

  4. 将 official_docs、docs、documentation 等别名映射到 github_docs。

  5. 对带 filter 的 qdrant_search 空结果，在预算允许时自动去掉 filter 重试一次。

  6. 广泛资料类问题优先走快速 vector search，避免无过滤条件下进入 BM25/fuzzy/exact 慢路径。

当前实际可用 source 包括：

  1. github_docs：官方文档、docs.nervos.org、RFC、CKB/CCC/Fiber 仓库文档、SDK 文档和代码示例。

  2. nervos_talk：Nervos Talk 论坛帖子、社区讨论、Spark/grant/proposal、生态项目介绍和真实案例。

这让 source 选择不再依赖模型猜测，也避免了模型生成不存在的 source 后直接导致检索为空。

2.7 Prompt 与 ask_user 路由修复

本周对 full graph 中的 InfoGap、RetrieverPlanner、Reflection、DirectAnswer、AnswerComposer 等 prompt 进行了集中调整。

调优重点不是增加大量关键词规则，而是让 LLM 更清楚地区分：

  1. 哪些信息需要问用户；

  2. 哪些信息属于公开资料，应由系统检索；

  3. 什么时候应该基于合理默认假设继续回答；

  4. 什么时候应该说明证据边界，而不是泛泛拒答；

  5. 什么时候可以直接利用上文回答，而不是重新检索或重复追问；

  6. 用户在纠正 Bot 答非所问时，应直接道歉并重新聚焦，而不是继续检索旧问题。

同时，路由层增加了保护逻辑：

  1. ask_user 不再输出硬编码兜底回复。

  2. 如果没有真正的用户私有必填信息，graph 不应进入 ask_user。

  3. post-answer reflection 如果把公开资料缺口错误路由到 ask_user，会被改路由到继续检索、改写或回答。

  4. “你是不是回复错问题了”“答非所问”“不是这个问题”这类质量反馈会直接进入 direct answer，不触发资料检索。

这部分修复了“靠谱资料”追问被错误回复成 Fiber/testnet 默认假设，以及用户纠错后反而收到“知识库证据不足”的问题。

2.8 Telegram 文件与图片输入支持

本周补充了 Telegram 附件处理能力。此前系统只能识别用户上传了文件或图片，但不会下载，也不会把内容交给模型。

现在支持：

  1. 文本类文件下载和内容注入，包括 .txt、.md、.json、.yaml、.csv、.log、常见代码文件和配置文件。

  2. 图片下载后保存本地路径，并在回答生成阶段作为 image input 传给支持多模态的 LLM。

  3. 对附件设置大小限制：文本文件 256KB，图片 20MB。

  4. 明确不支持 PDF，避免引入复杂解析和不稳定依赖。

这让用户可以在 Telegram 中上传日志、代码片段、配置文件或截图，让 Bot 直接基于附件内容回答。

2.9 Debug 日志与部署支持

为了支持群内测问题定位，本周补充了更完整的 debug 信息，包括节点耗时、LLM 调用摘要、检索证据数量、tool trace、reflection 决策、route decision、终止证据不足原因等。

同时补充了服务器部署相关支持：

  1. 增加 Linux 版 Telegram Bot 重启脚本。

  2. 调整 environment.yml，去掉 Windows 专属依赖，改成跨平台最小环境。

  3. 整理 .gitignore，避免提交真实配置、日志、群聊记录、周报、个人文档和缓存文件。

  4. 清理 GitHub 仓库历史，确保公开仓库不包含敏感信息和本地资料。

  5. 通过日志确认线上 bot 进程启动时间、加载后端和实际请求链路。

三、Telegram 群内测反馈

本周内测的主要价值，是让系统问题从“离线样例中可能发生”变成“真实用户已经遇到”。几个比较典型的反馈包括：

  1. 用户希望 Bot 能理解连续追问，而不是每轮都像重新开始。

  2. 用户不希望 Bot 插入普通群聊。

  3. 当用户说“我是萌新，你自己决定”时，Bot 应该主动给方案，而不是继续追问。

  4. 当用户问“有没有靠谱资料”“官方有没有教程”时，Bot 应该主动查官方文档，而不是给知识库证据不足。

  5. 当用户说“你是不是回复错问题了”时，Bot 应该识别这是对回答质量的反馈，而不是继续沿着旧问题检索。

  6. 技术回答需要稳定引用资料来源，否则用户难以判断可信度。

  7. 对代码示例类问题，即使证据不完整，也应给出清晰的骨架和边界说明。

  8. 响应时间需要继续优化，尤其是复杂问题经过多节点 graph 后等待时间较长。

  9. 用户希望可以上传文件、日志或截图，让 Bot 直接分析。

这些反馈说明，当前系统的核心挑战已经不只是“能不能回答”，而是“是否像一个可靠、不过度打扰、能持续理解上下文、能使用资料和附件的群内助手”。

四、测试与验证

本周围绕 Telegram 群内测暴露的问题补充和运行了多组回归测试，重点覆盖：

  1. 群内同用户上下文读取。

  2. 不同用户记忆隔离。

  3. AskUser checkpoint 按用户恢复。

  4. 群聊 mention-only 触发策略。

  5. 未触发消息不写入 memory。

  6. 多线程并发处理与同一用户消息顺序保证。

  7. Telegram sendMessage Markdown/plain/detached fallback。

  8. offset 在异常场景下仍推进，避免同一 update 无限重放。

  9. 多库检索、论坛检索性能和工具 60 秒超时。

  10. qdrant_search broad resource 查询优先 vector path。

  11. source registry 注入、source alias 规范化和空结果 fallback。

  12. response-quality feedback 直接回复，不进入检索。

  13. post-answer ask_user 防护和 ask_user 硬编码兜底移除。

  14. Telegram 文本文件下载、内容注入和图片作为 LLM image input。

  15. CSAT、feedback、BadCase 逻辑回归。

阶段性相关回归测试结果为：


192 passed, 2 warnings

后续需要把本周真实群测 bad case 继续沉淀为标准评测样例，避免类似问题再次回归。

五、阶段性成果

本周完成后，系统从“群内可测”进一步推进到“线上可诊断、可修复、可回归”。主要成果包括：

  1. Telegram 群内测开始形成真实反馈闭环。

  2. 群内上下文实现按用户隔离。

  3. Bot 在群聊中默认只响应明确触发，减少打扰。

  4. 不同用户问题可以多线程并发处理。

  5. GitHub 文档库和 Nervos Talk 论坛库进入 runtime 检索路径。

  6. 检索 source registry 和 filter 校验让资料检索更稳定。

  7. 过度追问、回答滞后、答非所问、引用缺失、Markdown 异常等真实问题得到系统修复。

  8. Telegram 发送失败不再导致 update 重放和模型 API 无限调用。

  9. Telegram 文本文件和图片开始进入模型上下文。

  10. Debug 日志和部署脚本更适合线上排查。

六、当前问题

  1. 响应延迟仍需要优化。复杂问题经过多节点 graph、检索、反思和回答生成后，耗时仍偏长。

  2. Prompt 仍需要根据真实内测继续调优，特别是“主动给默认方案”和“避免编造”之间的平衡。

  3. 引用稳定性还需要继续观察，尤其是连续追问、资料链接和代码示例场景。

  4. source registry 目前是静态配置，后续最好从实际 archive metadata 自动生成或定期校验。

  5. 附件支持目前覆盖文本文件和图片，暂不支持 PDF、音频转写和复杂 Office 文档。

  6. 内测反馈还没有形成结构化问卷和统计指标，目前仍偏人工观察。

  7. 部署流程还可以继续标准化，例如补充 systemd、健康检查和日志轮转。

七、下周计划（Week 9）

下周重点不再是继续堆功能，而是围绕 Telegram 群内测反馈做系统调优、用户评估设计和线上运行稳定性提升。

  1. 整理本周内测反馈和 bad case。

将过度追问、回答滞后、引用缺失、上下文误用、检索为空、答非所问、发送失败等问题归类，形成可复盘的 bad case 列表。

  1. 根据内测反馈继续调优 prompt 和 graph 行为。

重点优化小白问题、连续追问、代码示例、公开资料检索、默认假设选择和证据边界说明。

  1. 完善 source registry 和检索 metadata。

让 planner 更稳定地理解 github_docs、nervos_talk 等 source 的内容范围，并考虑从 archive metadata 自动生成 source 提示，减少手工维护。

  1. 制定 Telegram 内测问卷。

设计一份简短问卷，用于收集用户对回答质量、上下文理解、响应速度、引用可信度、追问体验、附件分析能力和整体可用性的主观评价。

  1. 建立内测反馈指标。

初步统计满意度、常见失败类型、用户是否需要重复解释上下文、是否认为 Bot 打扰群聊、是否愿意继续使用等指标。

  1. 将高价值内测样例加入 evaluation dataset。

把真实群测中暴露出的典型问题转成可重复运行的评测样例，形成“内测反馈 → 测试集 → 回归验证”的闭环。

  1. 继续优化响应延迟。

基于 node timings 和 LLM trace 分析耗时瓶颈，优先优化简单问题、常见追问和资料类查询的快答路径。

  1. 完善服务器部署与运行监控。

在现有重启脚本基础上，补充更稳定的守护方式和日志观察流程，降低内测期间人工维护成本。

2 Likes
CKB Ecosystem Biweekly Update