lessons-quality-review.md

MisakaNet Lessons 全面 Review — 评分提升方向报告

生成时间：2026-06-15 | 基于 128 篇 contrib lessons + 现有质量检测脚本

---

一、当前状态总览

指标	数值	评价
总 lessons	128	量已够，质需收敛
core 目录	1（仅 README）	🔴 未建立核心知识体系
有 ## Verify 段落	4 / 128 (3%)	🔴 极低，可信度无依据
有 Problem + Solution 双结构	6 / 128 (5%)	🔴 大多数缺乏标准结构
有 status 字段	79 / 128 (62%)	🟡 38% 缺少状态标记
有 tags 字段	96 / 128 (75%)	🟡 合格但可优化
标题含中文	111 处	🔴 影响国际化搜索
行数 ≤30	33 / 128 (26%)	🟡 部分 lesson 偏浅
行数 >30	95 / 128 (74%)	🟢 主体长度合理

当前质量评分

按 check_lesson_quality.py 跑分结果：

• 180 错误（主要是标题中文 + 缺必填字段）
• 122 警告（主要是中文正文）

---

二、领域分布与覆盖率

领域	lesson 数	占比	评价
devops	53	41%	⭐ 主领域，覆盖充分
rag	20	16%	🟡 核心领域但缺少 verified 验证
feishu	17	13%	🟡 生态绑定领域，注意泛化
development	13	10%	🟡 偏通用开发
tts	4	3%	🔴 小众领域
mcp	3	2%	🔴 小众领域，game-mcp 需移除
frontend	3	2%	🟢 合理范围
fanuc	2	2%	🔴 领域信息不全
其他小众	13	10%	—

领域健康度判断： devops 独大 (41%)，RAG 和 feishu 其次。TTS、MCP 等小众领域的 lesson 数量少且缺乏更新，属于"知识负债"。

---

三、结构性缺陷

3.1 缺少标准化的 lesson 结构模板

当前大部分 lesson 自由格式严重。有效的 lesson 应有：

## Problem         ← 问题描述（必选）
## Root Cause      ← 根因分析（推荐，区分于表面的 fix）
## Solution / Fix  ← 解决方案（必选）
## Verify          ← 验证步骤（必选，当前只有 4% 有）
## Reference       ← 参考来源（可选）

当前覆盖率：

段落	覆盖率	目标
Problem	49%	>90%
Solution/Fix	79%	>90%
Root Cause	4%	>50%
Verify	3%	>70%
Reference	16%	>40%

3.2 core/contrib 分层未建立

lessons/core/ 下只有 README.md，没有任何真正的 core lesson。这导致：

• 搜索结果没有 core 的加权优势
• 贡献者不知道什么标准能进 core
• 可信度缺乏层级背书

3.3 中文标题 + 中文正文

111 个标题含中文。在当前英文为主的开源生态中，这会：

• 降低 GitHub 搜索命中率
• 降低非中文 Agent 的检索召回率
• 在 CLI 输出中与英文标签混排，体验不一致

---

四、质量评分提升方向（按优先级排列）

P0：立即可执行（自动化门禁可覆盖）

改进项	当前值	目标值	影响
标题英文化	111 错误	0	修正质量检测脚本中的大部分报错，提升搜索命中
补必填字段	49 缺	0	schema 合规，不再阻塞 CI
补 tags	32 缺	0	提升 BM25 排序质量

操作方式： 写一个批量修复脚本，自动将中文标题翻译为英文 + 补默认 tags，然后人工 review diff。

---

P1：高价值内容改进（需人工投入）

改进项	当前值	目标值	影响
补 Verify 段落	4/128	>60/128	搜索结果可标记 [verified]，大幅提升可信度
补 Problem 结构	63/128	>115/128	标准化结构，提升可读性和 Agent 解析效果
建立 core 目录	0	10-15 篇	搜索结果分层，core 加权展示

操作方式：

• Verify 段落：对每篇 lesson，确认其 solution 是否经过验证，补上具体的验证命令
• Problem 结构：对缺少 Problem 段落的 lesson，补上问题描述
• core 迁移：从 contrib 中选出 10-15 篇高质量、已验证、高命中的 lesson，提升到 core

---

P2：体系化改进（需策略设计）

改进项	当前	目标	影响
lesson 质量评分可视化	无	每个 lesson 有质量标签	搜索时用户可见质量等级
标准化结构模板推广	无模板	pre-commit hook 自动提示	新 lesson 从第一天起符合规范
自动化 core 升级路径	手动	基于命中率+质量分+verified 自动提名	治理自动化

---

P3：长期生态建设

改进项	说明
领域健康度管理	devops 占比 41% 偏高，逐步引导 rag/frontend/security 等领域的贡献
小众 lesson 清理	tts/mcp/wechat 等低频领域，维持但不鼓励新增，或归档
lesson 生命周期管理	draft → published → verified → core，明确每个阶段的晋升标准

---

五、预期评分提升曲线

阶段	错误数	警告数	Verify 覆盖率	核心动作
当前	180	122	3%	—
P0 完成后	~70	~100	3%	批量标题英文化 + 补必填字段
P1 完成后	~70	~50	~40%	补 Verify + 补 Problem + 建 core
P2 完成后	~10	~20	~70%	标准化模板 + 自动化升级
理想态	0	0	>70%	全自动化治理

---

六、一句话结论

当前 lessons 量的积累已足够，质的收敛是下一阶段唯一重要的事。最值得最先做的不是内容本身，而是标题英文化 + 补 Verify 段落这两件事——前者消除 111 个错误，后者让搜索结果可信度产生质变。