giteahh/llm_wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
407a9213bf68bb3d6817c780c9c5bd7b3a1a9831
llm_wiki/wiki/LLM-Wiki-最佳实践.md
T

10 KiB
Raw Blame History

categories, tags, created, source, type, aliases, confidence, status, last_reviewed, review_interval_days, relations
categories tags created source type aliases confidence status last_reviewed review_interval_days relations
LLM Wiki
wiki
reference
best-practice
知识管理
quality
2026-07-01 LLM-Wiki-v2 reference
最佳实践
Best Practices
Wiki 质量指南
4 active 2026-07-01 180
type target description confidence
extends LLM-Wiki-v2 把 v2 理念落地为本仓库的具体可执行实践 4

LLM Wiki 最佳实践指南

一句话定义：基于本仓库 506 页实测分析，提炼"什么样的 Wiki 页面是好的"，以及如何稳定产出它。

证据基础

本指南不是空谈规范，而是 2026-07-01 对全库实测分析后得出的证据型结论：

| 指标 | 实测值 | 含义 |
--------
Wiki 总页数
含 [raw: 引用的页面
source: 指向 raw/ 的页面
last_reviewed 已填页面
relations 已填页面
引用含行号比例

核心洞察：本库引用系统在用到的地方近乎完美（行级零漂移，已抽样验证），问题是只有 15% 的页面在用。最佳实践的着力点不是"如何写得更好"，而是"如何让更多页面达到已有的黄金标准"。

黄金标准画像

以下四页是全库质量天花板，每个新页面都应对标其中之一：

工具页标杆 — DSpark

wiki/DSpark.md（121 行，21 条 [raw:行号] 引用）

  • 每一条数字都标注来源行号："延迟开销仅占整轮的 0.2% 到 1.3%[raw:向DeepSeek学习破局:45]"
  • 完整结构：一句话定义 → 基本信息表 → 核心创新 → 性能 → 架构 → 在 LLM Wiki 中的角色 → 启发 → 相关工具（4 个 wikilink）→ 来源
  • source: 正确指向 [[raw/向DeepSeek学习破局]]（非中间报告）

概念页标杆 — 拆与合

wiki/拆与合.md（186 行，13 条引用）

  • 一篇 raw → 双页面结晶：与 DSpark 同源，一个是工具页、一个是概念页
  • 诚实写边界条件：专设"边界条件"节列出三种失效场景，而非只讲优点
  • 对比表（分治法 vs 模块化设计 vs 拆与合）清晰区分相近概念

实体页标杆 — 何长工

wiki/何长工.md（80 行，14 条引用，全库引用密度最高）

  • 数字、金句、评价全部带行号引用
  • 巧用 callout 强化叙事：> [!tip]、> [!danger] + 引用
  • ==高亮== 标记关键短语（==假扮"逃兵"==）
  • 关系人物表把 [[毛泽东]]、[[朱德]]、[[王佐]] 织成网络

数据型概念页标杆 — 印度教育AI区域模式

wiki/印度教育AI区域模式.md（117 行，9 条引用）

  • 表格每行都带行内引用：| 在校学生总数 | 超2.5亿[raw:印度教育AI区域研究报告-20260407:35] |
  • 5 条编号核心洞察 + 低资源创新解法矩阵

写作最佳实践

Frontmatter（必填 6 字段）

字段 规则 正例 反例
categories 首项必须是 [[LLM Wiki]] ["[[LLM Wiki]]", "[[People]]"] 缺少 LLM Wiki
tags 首项必须是 wiki [wiki, concept, ai] [concept] 无 wiki
type 单值标量（非列表） type: concept type: [concept]
source 指向 raw/ 或权威来源 source: "[[raw/向DeepSeek学习破局]]" source: 躬行客整理
created YYYY-MM-DD created: 2026-07-01 —
aliases 含本名/英文名/变体 [DSpark, DeepSeek Spark] 空（影响搜索）

⚠️ 溯源"差一跳"问题：全库仅 49 页的 source 指向 raw/，其余 349 页指向中间报告（如 [[AI赋能课堂教学深度融合机制...报告]]）。理想做法是 source 指向最原始的 raw 文件；若内容确属二次综合，至少在正文 ## 来源 节列出所有 raw 依赖。

正文结构（概念/工具页推荐骨架）

# {标题}
> **一句话定义**：{核心定义}          ← 必有，开篇即给结论

## 定义 / 概述                         ← 展开
## 关键要点                            ← 3-5 条 bullet
## {核心内容}                          ← 表格优先于纯文字
## 与其他概念的关系                     ← 3+ wikilink，织网
## 来源                               ← 列出 raw 依赖

优于纯文字的表达：对比用表格、流程用编号、强调用 callout（> [!tip] / > [!warning] / > [!quote]）、关键词用 ==高亮==。

来源溯源系统（防漂移核心）

硬规则：所有数字、百分比、具体结论必须原文引用并标注行号：

学习效率提升 40%[raw:ALEKS研究:45]          ✅ 精确行号
学习效率提升 40%[raw:ALEKS研究]             ⚠️ 缺行号，可被 fix-raw-citations.py 自动补
学习效率显著提升                            ❌ 无来源，AI 话术漂移起点

行号以原始 raw 文件为准，标注精确行区间（:42-45 或 :87）。工具：python tools/scripts/fix-raw-citations.py 可为缺行号的引用自动回填。

链接织网

每页至少 3 个出站 wikilink，降低孤立风险。高质量链接的三个层次：

  1. 概念关联：[[相关概念]] — {关系说明}（"与其他概念的关系"节）
  2. typed relations：frontmatter relations: 字段（8 种边类型，激活图遍历）
  3. 实体交叉：人物/机构页互相引用（如 何长工 ↔ 毛泽东）

当前缺口：全库仅 1 页有 relations。图遍历/证据链追溯能力已就位（knowledge-graph.py），但需增量填充。新页面优先填 relations。

反模式（应避免）

反模式 真实案例 问题 修正
零引用存根 关羽（48 行，0 引用） 不可追溯，AI 漂移无防护 至少补 source + 3 条行号引用
自由文本 source 实践论 source: 躬行客整理 无 wikilink，无法跳转 改为 source: "[[raw/实践论原文]]"
中间报告断链 黄奇帆页用 sources/ 路径方言 与 [raw:line] 体系冲突 统一到 [raw:file:line]
照片无内容 仅 ![[Attachments/people/X.jpg]] + 瘦身正文 信息密度低 补生平/贡献/关系

双溯源方言警示：本库存在两套并存的溯源体系——原生 [raw:file:line]（毛传簇最佳）与 home-wiki 同步页的 sources/ 路径。新内容统一用 [raw:file:line]；同步页由 sync_home_wiki.py 管理可暂保留。

完成自检清单

写完一页后，逐项核对（对标 DSpark）：

  • frontmatter 6 必填字段齐全，source 指向 raw/
  • 开篇有"一句话定义"引用块
  • 每个数字/百分比/具体结论都有 [raw:file:行号]
  • 至少 3 个出站 wikilink（"与其他概念的关系"节）
  • 正文用表格/callout 而非纯文字堆砌
  • 如适用：填 confidence（1-5）、last_reviewed、relations
  • 运行 git add 后 pre-commit 校验通过

工作流速查

场景 命令
摄入新来源 存入 raw/ → 创建 wiki 页（带行号引用）→ 更新 index → 追加 log
查询知识库 qmd query "问题" 或 python tools/scripts/graph-search.py "词" --use-graph
补全引用行号 python tools/scripts/fix-raw-citations.py
添加关系 python tools/scripts/manage-relations.py add "页" --type supersedes --target "旧页"
重建图数据库 python tools/scripts/knowledge-graph.py build
体检（每周） powershell tools/scripts/weekly-lint.ps1
审查页面 python tools/scripts/review-pages.py --random 5（LLM/静态双模式）
跨库同步 python tools/scripts/sync_home_wiki.py --index --log

与 LLM Wiki v2 的映射

本指南的每条实践都对应 LLM-Wiki-v2 的一个核心理念：

v2 理念 本库实践 工具支撑
停止重新推导，开始积累 [raw:file:line] 溯源，零漂移 fix-raw-citations.py
置信度评分 frontmatter confidence 字段（待普及） review-pages.py --confidence-low
超替（Supersession） status: superseded + superseded_by manage-relations.py --type supersedes
遗忘 last_reviewed + review_interval_days 衰减 check-staleness.py
整合层级 raw→wiki + working/semantic/procedural/archive 分层 promote-knowledge.py
知识图谱 typed relations → 图遍历 knowledge-graph.py
混合搜索 BM25 + 向量 + 图扩展（RRF 融合） qmd + graph-search.py --use-graph
事件驱动自动化 pre-commit 校验 + post-merge 索引刷新 .githooks/
自愈 孤儿/断链/矛盾检测 + 自动 callout weekly-lint.ps1, detect-conflicts.py --auto-callout
Schema 是产品 AGENTS.md 作为操作规范 validate-frontmatter.py

优先级路线（针对实测缺口）

基于全库实测，按投入产出比排序的改进优先级：

  1. P0 — 普及溯源：给 74 页外的其余页面补 [raw:file:line]（尤其零引用存根页）
  2. P1 — 激活关系图：给被引用最多的 top-50 页填 relations，让 knowledge-graph.py 生效
  3. P2 — 落地生命周期：新页面必填 last_reviewed/confidence，模板同步更新
  4. P3 — 统一方言：home-wiki 同步页逐步迁移到 [raw:line] 体系

来源

Reference in New Issue View Git Blame Copy Permalink