205 lines
10 KiB
Markdown
205 lines
10 KiB
Markdown
---
|
||
categories:
|
||
- '[[LLM Wiki]]'
|
||
tags:
|
||
- wiki
|
||
- reference
|
||
- best-practice
|
||
- 知识管理
|
||
- quality
|
||
created: 2026-07-01
|
||
source: '[[LLM-Wiki-v2]]'
|
||
type: reference
|
||
aliases:
|
||
- 最佳实践
|
||
- Best Practices
|
||
- Wiki 质量指南
|
||
confidence: 4
|
||
status: active
|
||
last_reviewed: 2026-07-01
|
||
review_interval_days: 180
|
||
relations:
|
||
- type: extends
|
||
target: '[[LLM-Wiki-v2]]'
|
||
description: 把 v2 理念落地为本仓库的具体可执行实践
|
||
confidence: 4
|
||
---
|
||
|
||
# LLM Wiki 最佳实践指南
|
||
|
||
> **一句话定义**：基于本仓库 506 页实测分析，提炼"什么样的 Wiki 页面是好的"，以及如何稳定产出它。
|
||
|
||
## 证据基础
|
||
|
||
本指南不是空谈规范，而是 2026-07-01 对全库实测分析后得出的证据型结论：
|
||
|
||
| 指标 | 实测值 | 含义 |
|
||
|
|
||
------|
|
||
--------|------|
|
||
| Wiki 总页数 | 506 | 含 index/log |
|
||
| 含 `[raw:` 引用的页面 | 74（14.6%） | **引用纪律呈双峰分布** |
|
||
| `source:` 指向 raw/ 的页面 | 49（9.7%） | 多数指向中间报告，溯源"差一跳" |
|
||
| `last_reviewed` 已填页面 | 0（0%） | Phase 1 生命周期字段几乎未落地 |
|
||
| `relations` 已填页面 | 1（0.2%） | 图遍历能力待激活 |
|
||
| 引用含行号比例 | 94%（413/440） | **已用引用的质量极高** |
|
||
|
||
> **核心洞察**：本库引用系统**在用到的地方近乎完美**（行级零漂移，已抽样验证），问题是**只有 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]` 体系
|
||
|
||
## 来源
|
||
|
||
- [[LLM-Wiki-v2]] — 理念来源（Karpathy v1 + Rohit v2）
|
||
- [[LLM-Wiki-v2升级技术方案]] — Phase 0-3 实施方案
|
||
- 全库实测分析（2026-07-01）：506 页 frontmatter + 引用统计 + 抽样验证
|
||
- 黄金标准样本：[[DSpark]]、[[拆与合]]、[[何长工]]、[[印度教育AI区域模式]]
|