犀牛鸟 2026 · 开源研究笔记
首页 / RAG / 知识库 / WeKnora 实战

WeKnora 案例写作标准

原则：每一篇都写到能独立教学，不堆数量。
当前阶段：15/15 已通过 scripts/audit-case-quality.py 全项检查；可恢复 Tier B 开新案（质量优先）。

案例质量矩阵（15 篇）

案例 字数级 等级 说明
case-1828 ~8k S 标杆 横切安全模板
case-1759 ~7k A env-store 双端
case-1774 ~8k A Go 三层 API
case-1785 ~7k A Parser 金标准 + 作者视角
case-1761 ~6.5k A 前端 TTL 缓存（二轮回炉）
case-1773 ~6k A 全栈可观测
case-1633 ~5k A 前端 null guard
case-1725 ~5k A 管线金标准
case-1700 ~5k A chunker
case-1743 ~4.5k A 跨语言（回炉 2026-07）
case-1754 ~4.3k A hybrid-search POST（二轮回炉）
case-1808 ~4.2k A 跨栈 force-scanned（二轮回炉）
case-1668 ~4k A 向量冷路径（二轮回炉）
case-1784 ~4k A 错误语义（回炉 2026-07）
case-1772 ~3.7k A Agent QA dead flag（二轮回炉）

等级定义：S = 后续默认下限；A = 通过合并前自检表 + 审计脚本全绿；B+ / B = 历史档，已无待回炉项。

标杆案例（按类型对照）

类型 标杆
Parser / 过滤 case-1785
管线中间层 case-1725
横切 / 多文件 case-1828
跨 Py+Go case-1743
Go 三层 API case-1774
可行动错误 case-1784
env-store / vectordb case-1759

1. 什么时候才开新案？

现政策（2026-07）：矩阵 15/15 ≥ A；恢复 Tier B 开新案时仍须 质量优先，新案合并前须过审计脚本。

满足 全部 条件才写 新 精读：

条件 说明
矩阵无 B 级待回炉 或用户明确要求开新案
根因可讲清 + 可复现 + 模式可迁移 同前
对照标杆类型全文 结构不缺段
合并前自检表全 ✓ 见 §6

2. 必备结构（9 段）

段 最低要求
0 元信息 PR/Issue、±行、文件数
1 结论先行 根因 + 适合谁 + 导读/#1248
2 What 现象/威胁 + 修复前/后对比表
2b 定位 rg 命令 + 阅读顺序
3 Why Mermaid + 文件表
4 How ≥2 代码块 + 备选方案排除 + （多文件）逐文件表
5 Review PR 四段式 + checklist
6 模式 + ≥4 误区  
7–8 思考点 + 章末自检 + 延伸 3 条自检

3. 厚度自检

检查项 通过线
正文字数 ≥ 2 500（S 级 ≥ 3 500）
Mermaid ≥ 1
对比表 ≥ 1
验证命令 go test / curl / staging 至少一种
不打开 GitHub PR 能学会 必达

4. 各栈要点

见前版：Python docreader · Go chunker · embedding/SSRF（1828）· API · Vue+Go（1773）· Py+Go+UI（1808/1743）。

5. 工作流

审计矩阵 → 选最薄/缺项最多的一篇回炉
    ↓
对照标杆类型 → 填自检表 → 写/改
    ↓
重跑审计脚本（字数/定位/mermaid/误区）
    ↓
矩阵等级升 A → 再下一篇
    ↓
全部 A 以上 → 才恢复 Tier B 开新案

6. 合并前自检表（必过）

[ ] 结论先行 + 适合谁读 + 导读链接
[ ] What + 修复前/后对比表
[ ] 定位：rg + 阅读顺序
[ ] Why：mermaid + 文件表
[ ] How：代码 + 拒绝的备选 + 多文件表（若适用）
[ ] 验证命令或 staging 步骤
[ ] PR 四段式 + 维护者 checklist
[ ] ≥4 条常见误区
[ ] 3–5 思考点 + 3 条章末自检
[ ] 字数 ≥2500
[ ] 上游 pin：front-matter 含 upstream_commit（merged PR 的 merge commit）
    或 upstream_issue（无 PR 的 issue 分析）；正文 H1 下方一行标注 pin 说明

upstream pin 约定（2026-07-10 起）：案例引用的代码路径与行号会随上游演进偏移。 merged-PR 案例必须 pin 到 merge commit（gh pr view <n> --repo Tencent/WeKnora --json mergeCommit 获取）； issue-only 案例标注 issue 号与核实日状态。审计脚本对缺 pin 的案例直接判 fail。

7. 审计命令（维护者）

python3 scripts/audit-case-quality.py

8. 实战日志标准（8/1–9/10 课题实战期）

案例（case）是第三人称精读别人的 PR；实战日志（log）是第一人称记录自己做 issue 的过程。文体不同，标准分开：日志不要求「≥4 条误区」与 PR 四段式，但必须回收 #1248 映射 做出的预测。

8.1 命名与 front-matter

---
layout: default
title: "实战日志 W1：环境搭建与模块精读"
parent: "WeKnora 实战"
grand_parent: "RAG / 知识库"
nav_order: 16
---

8.2 必备六段

段 最低要求
1 本周目标 引用按周计划的对应周（W1–W5）与预期交付物
2 实际进展 上游 commit / PR / issue 讨论链接（≥1 个 github.com/Tencent/WeKnora 链接）
3 预测 vs 实际 对照 #1248 映射 的子任务-案例映射：预测用上了吗？哪里不适用？偏差原因
4 scope 决策记录 砍了什么、为什么砍（对照 MVP / Phase2 切分）
5 review 迭代记录 维护者意见原话、改法、来回轮数（无 review 的周写「本周无」并说明阶段）
6 下周调整 基于本周偏差对下周计划的修正

8.3 厚度自检

检查项 通过线
正文字数（去空白） ≥ 1 500（日志可短于案例）
「本周目标」段 必有
「预测 vs 实际」段 必有
上游链接 ≥ 1 个 github.com/Tencent/WeKnora

8.4 审计与节奏

延伸阅读