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

English
,
39

第十周周报

一、本周目标

本周重点从“群内测问题修复”推进到“交付前工程收敛”。相比第九周继续补功能，本周更关注项目是否能被部署方理解、复现、运行和验收。

本周核心目标包括：

  1. 完成 Nervos Talk MCP 和 Talk forum 定时增量更新能力。

  2. 补齐工程文档，让部署方 clone 仓库后能按文档快速部署。

  3. 验证 docs / forum / github_code 三个检索库的重建、增量更新和 Git LFS 发布边界。

  4. 继续测试 Telegram / Discord 两端真实 Bot 链路。

  5. 将典型问答问题整理为 evaluation dataset，方便后续回归。

  6. 修复内测中暴露的 reply 上下文误用问题。

  7. 优化检索数据库召回能力和回答链路，减少“有资料但搜不到”“搜到了但链路过慢”的问题。

二、本周完成

2.1 Nervos Talk MCP 与 forum 增量更新

本周实现了只读 Nervos Talk MCP，用于实时查询公开 Nervos Talk / Discourse 数据。

第一版 Talk MCP 只做读取，不写论坛、不访问私有分类、不让普通 Bot 问答触发爬虫。工具能力包括：

  1. talk_search：按关键词搜索公开讨论。

  2. talk_get_topic：读取指定 topic 的帖子内容。

  3. talk_get_post：读取指定 topic 内的单条 post。

  4. talk_latest：查看最新公开讨论。

同时补充了 Talk forum 定时增量更新服务。离线 forum archive 和 Qdrant collection 由定时 ingest 服务更新，默认频率为 24 小时。这样普通用户问答仍然只读检索库，不会在请求过程中触发慢爬虫、写库副作用或论坛 API 限流问题。

这项设计把“实时查看论坛”和“更新本地检索库”分开：MCP 负责即时查询，定时任务负责数据库增量维护。

2.2 GitHub 文档和代码增量更新

本周继续完善 GitHub 文档库和代码库的增量更新能力。

之前 GitHub 数据主要依赖全量爬取，更新成本较高，也不利于长期运维。本周新增基于 repo commit / manifest / state 的增量刷新流程，使系统可以识别哪些仓库发生变化，并只处理需要更新的部分。

增量更新边界也进一步明确：

  1. data/ingest_state/ 是本机运行游标，记录上次爬到哪里，不提交 GitHub。

  2. data/manifests/ 是公开数据版本说明，可以提交。

  3. 增量 JSONL 默认进入临时目录，不直接覆盖 canonical source JSONL。

  4. archive DB 仍然是可复现数据源，Qdrant server 是运行时向量服务。

本周也实际验证了 docs、forum、github_code 三类数据的增量流程。个别较大的 GitHub 仓库在本机网络环境下按需拉取 blob 时出现 TLS 中断，但这属于本机网络不稳定导致的外部问题，不影响脚本设计；后续部署到网络更稳定的服务器时可继续跑完整增量。

2.3 工程文档补全

本周重点补齐了公开工程文档，使项目从“代码和脚本基本可用”推进到“别人 clone 后可以按文档部署和运维”。

新增和精修的文档包括：

  1. README.md：作为项目公开入口，说明项目定位、快速启动、数据布局和文档索引。

  2. docs/deployment.md：fresh clone 后的部署流程，包括环境、配置、Qdrant、Bot 启动和健康检查。

  3. docs/configuration.md：解释 config.yaml.example 中 LLM、retrieval、Bot、logging 等配置区。

  4. docs/retrieval-data.md：解释 archive DB、Qdrant server、Git LFS 和三库重建关系。

  5. docs/runtime-operations.md：说明 Telegram / Discord / Qdrant / Talk 增量服务的日常运维。

  6. docs/mcp.md：说明 Telegram MCP 与 Nervos Talk MCP 的定位和环境变量。

  7. docs/testing-and-acceptance.md：整理部署验收和推荐回归测试命令。

  8. docs/troubleshooting.md：整理 Docker、LFS、Qdrant、token、mamba 环境和 Bot 无响应等常见问题。

文档中只写公开流程、占位符和通用命令，不写真实 token、API key、群聊原文、debug log 或测试服务器私密路径。

2.4 Qdrant、archive DB 与 Git LFS 发布边界确认

本周进一步梳理了检索数据的交付方式。

当前项目中有三类检索数据：

  1. docs：Nervos / CKB / CCC / Spore 等文档资料。

  2. forum：Nervos Talk 社区讨论。

  3. github_code：GitHub 代码和示例仓库。

Docker Qdrant server 是线上运行时向量数据库，里面有三个 collection。archive DB 是可提交、可迁移、可重建的数据源。部署方 clone 仓库后，通过 Git LFS 拉取 archive DB，再用迁移脚本重建 Docker Qdrant collection。

本周确认并调整了 Git LFS 策略：体积较大的 SQLite archive DB 走 Git LFS，避免普通 Git 历史膨胀；Qdrant Docker 运行目录不提交，部署时从 archive DB 重建。

这样可以兼顾两个目标：

  1. GitHub 仓库可以保存公开可复现的数据源。

  2. 部署环境可以快速恢复 Qdrant runtime 数据库。

2.5 Discord Bot 链路测试与部署说明

本周继续测试 Discord Bot 链路，重点关注它是否能作为 Telegram 之外的第二个线上入口。

Discord 端已经具备以下能力：

  1. guild / channel allowlist。

  2. mention-only 触发策略。

  3. 回复 Bot 消息时携带 reply context。

  4. Markdown 长消息安全分段。

  5. feedback、CSAT、debug event 和 memory context。

  6. 禁用 allowed_mentions，避免生成内容误 ping 用户或角色。

实际启动测试时也确认了 Discord 的一个部署注意事项：如果 Bot runtime 请求了 privileged intents，而 Discord Developer Portal 没有开启对应权限，会报 PrivilegedIntentsRequired。这不是代码崩溃，而是 Discord 平台权限配置问题。部署方需要在 Developer Portal 中开启对应 intent，或者后续按最小权限原则关闭不必要 intent。

2.6 evaluation dataset 整理

本周将评测样例目录整理为两类：

  1. evaluation/ai_generated_cases.jsonl：人工设计 / AI 辅助生成的基准样例。

  2. evaluation/human_collected_cases.jsonl：真实内测或人工收集的问题样例。

这个划分比按 week 命名更清晰。后续如果用户反馈某个回答不好，可以直接脱敏后追加到 human_collected_cases.jsonl，并写明失败模式和验收标准。

目前真实坏例子不多，很多问题本质上来自数据库缺口、软件 bug 或 prompt 策略不稳定，而不一定是单个回答样例本身有长期复现价值。因此当前阶段以“轻量记录、后续积累”为主。

2.7 Telegram reply 上下文问题修复

本周继续跟进 Telegram 群内测中出现的上下文问题。

测试中发现一种具体问题：用户回复某条旧消息，并用“用小白版解释一下”这类短句追问时，Bot 有时没有围绕被回复消息回答，而是被普通最近历史中的其他话题带偏。

排查后发现，runtime 虽然能看到 reply_to_message_id，但 reply context 和同用户最近历史会一起进入 graph。对于短追问来说，被回复消息才是直接锚点，普通最近历史反而可能污染模型判断。

本周修复为：

  1. 如果当前消息明确 reply 了某条消息，优先只使用被回复消息内容作为上下文锚点。

  2. reply 场景不再混入普通最近历史，避免 WASM / Fiber 等旧话题抢上下文。

  3. 如果平台没有提供被回复消息内容，会明确告诉模型“被回复内容不可见，不要从普通历史记录猜测”。

  4. debug event 增加 reply_to_content_preview、conversation_context_preview、recent_messages_preview，方便后续定位。

  5. Telegram 和 Discord 两端都补充了对应回归测试。

这项修复后，用户使用 Telegram / Discord 的原生回复功能时，Agent 更容易围绕被回复消息回答，而不是凭最近记忆猜测。

2.8 检索数据库召回优化

本周继续处理内测中暴露的检索问题：有些项目或讨论明明存在于 forum / docs / github_code 数据库里，但用户用自然语言点名项目时，普通向量、BM25、fuzzy、exact 融合仍可能没有把目标资料排到前面。

本周新增了由 LLM 检索规划器生成 regex_queries 的 hard recall 能力。这个设计没有把具体项目名写死到代码里，而是让 Planner 根据用户当前问题判断是否需要正则硬召回。例如用户点名真实项目、库、SDK、函数、类名、文件名、repo 或版本号时，模型可以生成短而具体的正则表达式；底层检索层只负责校验、限流、执行和融合。

实现边界包括：

  1. regex_queries 挂在统一 qdrant_search step 上，不新增单独工具。

  2. 正则只作为 hard recall 子能力，与 vector / BM25 / fuzzy / exact 一起进入 RRF 融合。

  3. 底层拒绝空正则、过长正则、过宽泛正则、反向引用和明显危险 pattern，避免性能和安全问题。

  4. debug trace 记录 regex 数量、有效数量、丢弃数量和丢弃原因，方便排查。

  5. 不做业务关键词硬编码，具体正则由模型根据问题生成。

这项优化解决的是“实体名硬召回”问题。例如项目名中有空格、连字符、下划线差异时，模型可以生成更宽松的匹配方式，避免论坛 topic 或 GitHub path 被普通语义检索漏掉。

2.9 Prompt-first 链路延迟与质量优化

本周也针对 full graph 链路过慢做了专项分析和 prompt 级优化。

实际评测发现，耗时主要不在 Qdrant 或 BM25/fuzzy/exact 检索，而在多轮 LLM 节点：模型路由、检索规划、pre-answer reflection、answer composer、post-answer reflection 和二次改写会叠加出很长等待时间。个别问题即使只是资料推荐，也可能因为过度谨慎进入多轮反思和改写。

本周坚持“不写业务硬规则”的原则，优先从 prompt 调整，让模型自己更早收敛：

  1. 模型档位路由 prompt 不再鼓励技术问题默认升高档位，而是按节点复杂度选择。

  2. InfoGap prompt 明确“主动检索不等于多轮深检索”，资料推荐和学习路线类问题通常走 single。

  3. RetrieverPlanner prompt 要求 single 默认只生成 1 个统一 qdrant_search step，不把历史错误回答和评测描述塞进 query。

  4. Reflection prompt 要求证据足够覆盖核心问题时直接 accept_answer，不要为了更完整继续检索或二次改写。

  5. AnswerComposer prompt 要求默认短答、贴题、先给可执行主线，资料类问题优先给 3-5 个入口和学习顺序。

  6. 引用要求更严格：只引用正文实际使用的证据，不把无关仓库、无关 README 或没有支撑正文断言的命中混进来源。

在人工作例回归中，这轮 prompt-first 优化让部分问题明显提速：Fiber agent 部署问题从接近 5 分钟降到 2 分钟左右，Fiber WASM 覆盖查询降到 1 分钟以内。CKB 新手资料推荐问题不再超时，但仍然偏慢，说明后续可能还需要通用链路机制优化，例如时间预算硬约束、post-reflection 最大改写次数或模型路由缓存。

2.10 最终测试与本地提交

本周对未提交改动做过多轮本地测试和主题拆分提交，覆盖依赖、Discord runtime、Talk MCP、GitHub 增量、工程文档、数据发布边界等内容。

阶段性验证包括：


mamba run -n nervos-brain pytest -q

以及针对 Telegram runtime、Discord runtime、full graph、formatter、retrieval、Qdrant migration、Talk MCP、GitHub ingest 等模块的专项测试。

本周也完成了 Git LFS 和 GitHub 远端同步，确保公开仓库中包含可复现部署所需的代码、文档、配置模板、脚本和公开数据源。

三、本周主要收敛点

本周的重点不是继续增加新功能，而是把已有能力变成可交付状态。

主要收敛点包括：

  1. Talk 数据从“离线论坛库”扩展为“只读 MCP + 定时增量更新”。

  2. GitHub 文档和代码数据从“全量爬取”推进到“可增量刷新”。

  3. Qdrant server 和 archive DB 的关系解释清楚，部署方知道哪些数据需要提交、哪些数据运行时重建。

  4. README 和 docs/ 文档补齐，项目不再依赖口头说明。

  5. Discord 链路开始进入真实部署测试。

  6. evaluation dataset 开始按 AI 生成样例和人工收集样例分开维护。

  7. Telegram / Discord reply 上下文误用问题得到针对性修复。

  8. 检索数据库增加 LLM 生成正则 hard recall，提升项目名、库名、文件名等实体召回能力。

  9. full graph prompt-first 链路优化后，部分真实样例延迟明显下降，但简单资料类问题仍需继续优化。

四、测试与验证

本周验证重点覆盖：

  1. Telegram reply context 不被普通最近历史污染。

  2. Discord reply context 不被普通最近历史污染。

  3. Telegram / Discord 长消息格式和分段发送。

  4. Discord Developer Portal 权限配置问题定位。

  5. Talk MCP 只读工具注册和调用边界。

  6. Talk forum 24 小时定时增量服务设计。

  7. GitHub docs/code 增量更新流程。

  8. archive DB 到 Docker Qdrant server 的重建流程。

  9. Git LFS 中数据库文件的提交和同步。

  10. README 与 docs 文档命令、路径和安全边界。

  11. evaluation dataset 文件命名和样例格式。

  12. LLM 生成正则 hard recall 与普通检索融合。

  13. prompt-first 链路优化后的人工样例回归。

阶段性专项测试包括：


tests/test_telegram_bot_runtime.py tests/test_discord_bot_runtime.py tests/test_full_graph.py: 137 passed

以及多组 py_compile、shell check、secret scan、git diff check 和 Qdrant collection 检查。

五、阶段性成果

本周完成后，项目已经基本进入交付前最终测试阶段：

  1. Telegram Bot 已经能在群内按 mention / reply 方式运行。

  2. Discord Bot 已具备完整 runtime 能力，并开始真实链路测试。

  3. docs、forum、github_code 三库可以通过 archive DB 和 Git LFS 复现。

  4. Docker Qdrant server 作为运行时向量库的定位已经清晰。

  5. Talk MCP 与 Talk forum 增量更新方案已经形成。

  6. GitHub 文档和代码增量更新能力已经补齐。

  7. 公开工程文档已经覆盖部署、配置、数据、运行、MCP、测试和排障。

  8. evaluation dataset 已经开始支持后续回答质量回归。

  9. reply 上下文误用问题已经修复并补测试。

  10. 检索召回能力对真实项目名、代码路径和论坛 topic 更稳。

  11. 回答链路在不增加业务硬编码的前提下减少了一部分无效多轮反思和改写。

六、最终验收剩余项目

当前基础代码库和部署文档已经基本完成，后续重点不再是继续增加功能，而是完成最终验收材料和交付确认。

已完成部分包括：

  1. 基础代码库：vector DB + Graph Planning、Agentic RAG Bot 框架、Nervos Talk MCP、Discord / Telegram Bot、多模型路由和复合数据库。

  2. 文档与部署：README、功能说明、部署文档、配置说明、检索数据说明、MCP 说明、运行维护和故障排查文档。

剩余验收项目包括：

  1. 测试报告。

在社区招募测试人员，对回答质量、检索可信度、上下文理解、响应速度、追问体验和整体可用性进行打分，并整理测试结果。

  1. 演示视频。

录制完整演示，覆盖 Telegram / Discord Bot 问答、Nervos Talk 查询、检索引用、reply 追问、部署文档和数据重建流程。

  1. 最终链路验收。

按部署文档从 fresh clone 走一遍完整流程，确认 Git LFS 数据、Qdrant 重建、Bot 启动、Talk MCP、增量更新和核心问答案例都可用。

  1. 交付说明确认。

最后确认公开仓库不包含 token、API key、私钥、群聊原文、debug log、memory DB 和本机 runtime 数据。

3 Likes
CKB Ecosystem Biweekly Update