犀牛鸟 2026 研究笔记 estelledc.github.io
首页 / RAG / 知识库 / WeKnora 实战

WeKnora 贡献案例索引

调研日期：2026-07-01 ｜ 15 篇精读（标杆 case-1828 + 写作标准）
PR 候选队列：case-catalog.md

本索引从 WeKnora 近期 merged PR 中筛选出 教学价值最高 的案例。质量等级见 写作标准 · 案例质量矩阵（当前：先打磨已有，暂停 Tier B 新案）。

案例总表

优先级 Issue PR 类型 触及目录 改动规模 教学分 一句话根因 对 #1248 的启发 状态
★★★ #1779 #1785 Bug（docreader） docreader/parser/ 2 文件 +111/-1 5 WPS 嵌入图片以 DISPIMG() 函数字符串存储，openpyxl data_only=True 不过滤，噪声泄入 RAG 直接：同属「边界/归因」类——#1248 要把用户反馈归因到知识库片段，1785 要把噪声归因到 IMAGE 函数 已完成
★★★ #1633 无（社区评论有修复线索） Bug（前端 UI） frontend/src/views/organization/ 预估 1–2 文件 4 共享空间搜索用户时，API 返回数量正确但 displayName 字段未正确映射，前端渲染 undefined 间接：#1248 前端气泡 UI 同样需要处理异步数据的 null guard 和字段映射 已完成
★★★ #1725 #1755 Bug（docparser 管线） internal/infrastructure/docparser/ 3 文件 +149/-0 5 PaddleOCR-VL 输出 HTML 表格含 text-align 样式，chunker 只保护 Markdown 管道表，HTML <table> 超 ChunkSize 后被切断 方法论：管线思维——改一层输出要验证下游假设；#1248 的 feedback 数据也需穿越 message→chunk→snippet 管线 已完成
★★☆ #1760 #1761 Bug（前端状态管理） frontend/src/stores/ 1 文件 +3/-0 4 Pinia store 的 fetchOrganizations() 有 60s TTL 缓存，创建成功后调用被缓存拦截，列表不刷新 直接：#1248 点赞/点踩后前端状态更新同样需要考虑缓存失效和乐观更新 已完成
★★☆ — #1774 Feature guard（Go API） internal/application/repository/、internal/application/service/、internal/handler/ 11 文件 +437/-2 5 删除模型前未检查是否被 KB/Agent 引用，直接删除会破坏关联 直接：#1248 需新建 feedback 表 + 关联表，1774 的 repository 查询 + service 校验 + handler 返错模式可直接复用 已完成
★★☆ — #1743 Bug（MHTML 管线） docreader/ + internal/infrastructure/docparser/ 8 文件 +1112/-16 5 MHTML 内嵌图片分辨率/链接在 Python→Go 管线中丢失或 chunk 断裂 方法论：跨语言管线端到端验证；#1248 snippet 依赖 chunk 完整 已完成
★☆☆ — #1784 Fix（Go web-search） internal/.../websearch/ 5 文件 +187/-4 4 SearXNG 失败仅返回模糊错误，无法排查配置/超时/502 模式：handler 可行动错误码；#1248 POST API 错误语义可参照 已完成
★★★ — #1700 Bug（chunker） internal/infrastructure/chunker/ 2 文件 +107/-3 5 长 section 二次切分丢失 ### 子标题 breadcrumb 直接：chunk 上下文 = RAG 检索上限 已完成
★★☆ — #1754 API（hybrid-search） handler/ + MCP + docs 8 文件 +1137/-173 5 GET 无法承载复杂检索 body；缺 POST hybrid-search 直接：eval/MCP 打检索接口 已完成
★★☆ — #1668 Bug（vectordb） tencentvectordb/repository.go 1 文件 +82/-26 4 复制 KB 时分页/query 漏 ID 映射 间接：向量层数据一致 已完成
★★☆ — #1808 Feat（PDF OCR） docreader + knowledge_process + UI 14 文件 +210/-6 4 扫描 PDF 无 text layer 未 OCR → 空 chunk 方法论：ingest 策略路由 已完成
★★☆ — #1772 Fix（agent QA） session/qa.go + types 4 文件 +66/-109 4 死字段 RunnableByViewer 误拦 viewer 对话 间接：QA 入口权限 已完成
★★☆ — #1828 Fix（embed SSRF） internal/models/embedding/ 13 文件 +112/-26 4 远程 embedder 裸 http.Client，自定义 base_url 可 SSRF 间接：出站 URL 构造期校验 已完成 · 标杆
★★☆ — #1773 Fix（QA thinking UX） types + pipeline + RagPipelineProgress 9 文件 +256/-34 4 thinking nil 致 wire 歧义 + 时间线闪动/缺 reasoning 间接：chat UX 字段归一化 已完成
★★☆ — #1759 Feat（vectordb env） tencentvectordb/ + types/vectorstore 9 文件 +91/-8 4 env-store 无法调 replica；QA 单节点需 replica=0 间接：向量部署与 Ch30 runbook 已完成

教学分评分标准（1–5）：

维度 权重 说明
教学清晰度 30% issue 能否复现、根因是否可讲清
范围可控 25% 改动文件数、是否适合初学者上手
栈覆盖 20% 覆盖前端 / Go API / Python docreader
评审信息 10% PR 有 review 评论、合入理由可推断
与 #1248 距离 15% 模式或代码区域与目标 issue 的关联度

推荐阅读顺序

路径 A：只看前端（适合前端开发者）

  1. case-1761 — Pinia 缓存失效，3 行修复理解 Vue 状态管理陷阱
  2. case-1633 — 异步数据 null guard，理解字段映射和防御性渲染
  3. → ch-patterns-from-cases §1–§3 前端模式
  4. → ch-bridge-1248 对话气泡 UI 子任务

路径 B：只看管线（适合关注 RAG 管道的读者）

  1. case-1785 — docreader 边界过滤，Python 正则 + 单测
  2. case-1725 — Go docparser HTML→Markdown 转换 + chunker 保护
  3. → ch-patterns-from-cases §4 管线模式
  4. → ch-bridge-1248 message→chunk 归因子任务

路径 C：冲 #1248（最短路径掌握全栈贡献模式）

  1. case-1785 — 入门：issue→PR 全流程 + 单测写法
  2. case-1774 — Go 后端：repository + service + handler 三层 + 数据关联校验
  3. case-1761 — 前端状态：创建/修改后的缓存失效
  4. → ch-patterns-from-cases 全文
  5. → ch-bridge-1248 全文

暂不选作教材的 PR 及原因

PR 标题 排除原因
#1789 feat(chat): unify resource chips 改动 8 文件 +194/-224，涉及前后端联动，范围偏大，不适合单案精读
#1787 feat(integrations): add publish center 改动 32 文件 +2585/-1507，大型 feature，教学拆解成本过高
#1775 feat(im): align agent stream display 改动 19 文件 +2270/-306，IM 集成全栈，超出新手范围
#1769 feat(datasource): add RSS feed connector 改动 31 文件 +2317/-147，新 connector 实现，与 #1248 无关
#1762 feat(mcp): add OAuth2 authorization 改动 27 文件 +1920/-686，MCP OAuth 全流程，复杂度过高
#1743 fix: preserve MHTML image resolution 改动 8 文件 +1112/-16，跨语言（Python + Go），状态机解析器，虽然教学优秀但与 #1248 距离远
#1747 fix(frontend): enhance repairFlankingEmphasis 改动 2 文件 +29/-4，改动小但功能极其细分（Markdown 渲染正则），可复用度低
#1784 fix(web-search): improve SearXNG error messages 改动 5 文件 +187/-4，Go 后端但属于 web search 子系统，与 #1248 无关
#1752 fix(docparser): rename close variable 改动 2 文件 +7/-7，纯 lint 修复，教学价值过低
#1744 feat(frontend): enhance chat streaming visuals 改动 11 文件 +667/-24，shimmer 动画 + Markdown 渲染，范围偏大

栈覆盖统计

栈 入选案例 数量
Python docreader #1785、#1743、#1808 3
Go embed / 安全 #1828 1
Go docparser / chunker / API / vectordb #1725、#1774、#1784、#1754、#1700、#1668、#1759 7
Vue 3 前端 #1633、#1761、#1773 3
Agent / QA #1772、#1773 2

15 篇精读；新案开写前必读 case-1828 标杆 + 写作标准。

路径 D：管线深度（MHTML / 跨语言）

  1. case-1743 — MHTML 图片分辨率，Python+Go 管线
  2. case-1725 — HTML 表格 chunk 保护
  3. → Ch17 RAGFlow/DeepDoc

路径 F：分块与向量（新增）

  1. case-1700 — heading breadcrumb
  2. case-1668 — VectorDB 复制 ID
  3. case-1759 — replica 环境变量
  4. → Ch27 · Ch30

路径 G：检索 API + 解析策略

  1. case-1754 — hybrid-search POST
  2. case-1808 — PDF 强制 OCR
  3. → benchmark · Ch24

路径 E：Go API 错误语义

  1. case-1784 — SearXNG 可行动错误
  2. case-1774 — 三层 API + 关联校验
  3. case-1772 — QA handler 权限
  4. → ch-bridge-1248 POST 子任务

路径 H：Embedding 与安全

  1. case-1828 — SSRF 校验 + 安全 HTTP Client（标杆）
  2. case-1668 — 向量复制 ID 映射
  3. → Ch30 · Ch43

路径 I：Agent 可观测（新增）

  1. case-1773 — thinking 默认值 + RAG 时间线
  2. case-1772 — QA 入口权限
  3. → Ch45

元信息