jzy/my_wiki

Fork 0

Files

T

Junjian Wang 94d4617299 支持增量编译wiki

2026-04-11 23:12:14 +08:00

12 KiB

Raw Blame History

使用 LLM 生成高质量中文 Wiki 知识库

1. Skill 概述

本 Skill 旨在利用大模型（LLM）将原始文档和图像（raw/）增量“编译”为 结构化、交叉链接、高质量的中文 Wiki 知识库（wiki/） 的完整思路和方法。

核心逻辑：人工不直接编写 Wiki，仅负责投放素材和发起查询；LLM 负责理解、重写、链接与维护。
适配工具：Obsidian（IDE 前端），通过插件支持更多格式：
- Markdown（文本内容）
- Matplotlib（数据可视化）
- Marp（幻灯片渲染）
- Mermaid（架构图）

1.5 大文档处理要求

对于篇幅较长的 raw 文档（如学术论文、长篇技术文章），必须完整阅读和分析，不得仅基于开头部分生成简短摘要。

具体要求：

完整内容获取：
- 使用 Grep 搜索章节标题（如 ^#{1,3} ）了解文档结构
- 分段读取完整内容，确保覆盖所有主要章节
- 特别关注：摘要、引言、方法、实验、讨论、结论、附录等核心章节
深度分析维度：
- 核心论点：提取文章的主要主张和关键发现
- 方法细节：理解技术方案的实现细节和设计决策
- 实验结果：完整记录所有实验数据、表格、图表信息
- 案例研究：保留具体的定性示例和应用场景
- 相关工作：建立与其他研究的联系和对比
输出内容标准：
- wiki 页面长度应与原文档的重要性和复杂度相匹配
- 学术论文应包含：摘要、核心方法、完整实验结果、详细讨论
- 技术文章应包含：问题背景、完整解决方案、实际应用案例
- 保留所有定量数据（表格、指标、分数等）
例外情况：
- 仅在以下情况下可生成较短摘要：
  - 文档是纯新闻报道或简短公告
  - 文档主要是代码或配置（无大量叙事内容）
  - 用户明确要求仅生成摘要

2. 标准文件系统架构

严格遵循 I/O 分离原则，确保知识库的纯净度与可迁移性：

📁 wikillm
├── 📁 raw/               # 【输入层】原始素材（只读）
│   └── 📁 images/        # 原始图片文件（png, jpg, webp, gif, svg 等）
└── 📁 wiki/              # 【输出层】编译器生成的知识产物
    ├── 📁 concepts/      # 核心概念、原理分析
    ├── 📁 practices/     # 部署指南、最佳实践
    ├── 📁 visual/        # Marp 幻灯片、Matplotlib 趋势图
    ├── 📁 queries/       # 高价值 Q&A 的沉淀归档
    ├── 📁 assets/        # 图像和资源文件（从 raw/images/ 同步而来）
    ├── INDEX.md          # 动态索引与学习路径
    ├── Glossary.md       # 统一术语表与双链枢纽
    └── sources.md        # 来源文档索引（原始 URL 列表）

3. 核心工作流 (The "Compilation" Loop)

阶段 0：增量检查 (Incremental Check)

任务：检查 raw/ 目录下哪些文件需要编译。
读取状态：读取 wiki/compile-results.tsv，获取已编译文件的哈希记录。
扫描文件：遍历 raw/ 目录，计算每个文件的 SHA-256 哈希。
识别变更：对比哈希值，识别：
- 新增文件：在 compile-results.tsv 中不存在的文件
- 修改文件：哈希值与记录不同的文件
- 未修改文件：哈希值相同的文件（跳过编译）
记录日志：将检查过程写入 wiki/compile.log。

阶段 0.5：资源同步 (Asset Sync)

任务：将 raw/images/ 下的所有图片资源同步到 wiki/assets/。
同步范围：所有图像文件，包括但不限于：
- png, jpg, jpeg, gif, webp, svg
同步方式：
- 使用 cp -r raw/images/* wiki/assets/ 进行完整同步
- raw/images/ 是权威来源，同名文件直接覆盖
- 保留原始文件名（包括空格和特殊字符）
验证：确保 wiki/assets/ 包含 raw/images/ 中的所有文件
时机：每次编译前必须执行此步骤

阶段 1：多模态解构 (Ingest & Analyze)

任务：解析 raw/ 目录下的新增或修改内容。
大文档完整阅读：对于篇幅较长的文档（学术论文、长篇技术文章），必须完整阅读和分析：
- 首先用 Grep 搜索章节标题（如 ^#{1,3} ）了解文档结构
- 分段读取完整内容，确保覆盖所有主要章节
- 特别关注：摘要、引言、方法、实验、讨论、结论、附录等核心章节
视觉解析：对图片进行深度 OCR 与逻辑识别。将架构图转化为文字描述及 Mermaid 代码块，存入对应 Wiki 页面。
元数据提取：为每篇文档生成 YAML Frontmatter（包含：tags, source, raw_sources, confidence_score, last_updated）。
- raw_sources 字段：记录源文件路径和哈希值，格式如下：
```
raw_sources:
  - path: raw/anthropic-harness-design.md
    hash: "sha256:abc123..."
```

阶段 2：增量编译 (Incremental Writing)

非线性重构：不进行 1:1 翻译，而是基于源文档的“核心贡献”进行重写。
中文化增强：
- 消除翻译腔：使用行业专业术语（如将 "Agent" 译为 "智能体"）。
- 添加上下文：为中文读者补充必要的背景知识或行业对比。
可视化输出：若涉及多步流程或对比，自动生成 Marp 格式的幻灯片文件（.md），以便在 Obsidian 中演示。

阶段 3：网络化链接 (Wikilinks & Indexing)

双链注入：全文检索 Glossary.md 中的术语，使用 [[术语名]] 自动包裹。
Wikilink 格式规范：
- 文件名使用 kebab-case（连字符分隔），例如：Harness-Engineering.md
- Wikilink 格式为 [[文件名|显示文本]]，其中文件名部分必须与实际文件名完全匹配（不带 .md 扩展名）
- 正确示例：[[Harness-Engineering|Harness 工程]]（对应文件 Harness-Engineering.md）
- 错误示例：[[Harness Engineering|Harness 工程]]（文件名带空格，不匹配实际文件）
- 文章列表格式：
  - 错误写法（表格无法正确解析双链）：
```
| 文章 | 描述 |
|------|------|
| [[Mitchellh-Adoption-Journey|Mitchellh AI 采用之旅]] | HashiCorp 创始人从怀疑论者到深度用户的六个阶段 |
| [[Building-Your-First-Harness|构建你的第一个 Harness]] | 从个人开发者到工程组织的三级实用框架 |
```
  - 正确写法（使用无序列表）：
```
- [[Mitchellh-Adoption-Journey|Mitchellh AI 采用之旅]] - HashiCorp 创始人从怀疑论者到深度用户的六个阶段
- [[Building-Your-First-Harness|构建你的第一个 Harness]] - 从个人开发者到工程组织的三级实用框架
```
反向链接：在文末生成 ## 相关研究 模块，强制链接到 Wiki 内部至少 2 篇关联文档。
动态索引：根据新增内容，自动更新 INDEX.md 中的”最新研究”与”学习路径”部分。

阶段 4：健康检查与维护 (Linting)

一致性检查：扫描 wiki/，发现术语冲突（如 A 文档叫”智能体”，B 文档叫”代理”）时，自动统一。
孤岛扫描：识别没有任何链接指向的页面，强制将其挂载到导航树中。
补丁发布：当 raw/ 有新版本（如论文更新）时，在对应 Wiki 页面顶部发布 [Update Patch] 摘要。

阶段 5：来源索引更新 (Sources Update)

任务：更新 wiki/sources.md，记录本次编译涉及的来源文档。
格式规范：使用简单无序列表，每项格式为 - [标题](URL)
增量更新：添加本次新增的来源，保持已有来源不变
分类组织：按”学术论文”、”概念文章”、”实践指南”等类别合理分组

4. 输出质量标准 (The Gold Standard)

表达标准

原则：读起来像是由该领域的资深专家直接用中文撰写的。

禁止词汇：产生、输出（作为动词）、这个、那个（指代不明）。
提倡词汇：负责构建、驱动、沉淀、权衡（Trade-off）。

技术标准

维度	要求
术语表	必须包含 40+ 核心概念，中英对照并带有 Wikilink
链接密度	每 500 字需包含至少 3-5 个内部链接
视觉呈现	复杂架构必须有 Mermaid 图，数据趋势必须有 Markdown 表格
Marp 适配	综述类文章必须同步生成一份 `visual/` 下的 Slide 文档

5. Q&A 与知识沉淀 (Filing Back)

当用户针对 Wiki 发起复杂查询时：

Agent 模式：LLM 检索全库文档，进行跨文档推理。
回答格式：回答不仅要解决当前问题，还需提供“参考文档清单”。
自动归档 (Filing)：若该次 Q&A 具有通用研究价值，LLM 需自动将其整理为一篇新的文章，存入 wiki/queries/，并在 INDEX.md 中创建入口。

6. 执行清单 (Checklist)

Raw Check: raw/ 目录中是否包含待处理的新素材（图片/文档）？
Asset Sync: raw/images/ 下的所有图片是否已同步到 wiki/assets/？
Glossary Lock: 是否已锁定全局术语表，确保翻译不漂移？
Multimodal Sync: 图片是否已转化为可编辑的文字解析/Mermaid？
文件名规范: 所有 wiki 页面文件是否使用 kebab-case（连字符分隔）命名？
Wikilink 格式检查: 所有 [[文件名|显示文本]] 链接中的文件名部分是否与实际文件名完全匹配？
Wikilink Check: 所有的核心概念是否都已变成 [[可点击的链接]]？
Marp Check: 是否为需要汇报的内容生成了幻灯片格式？
Orphan Check: 是否存在无法从 INDEX.md 触达的”孤儿页面”？

7. 增量编译工作流

编译状态文件

项目使用三个核心文件来追踪编译状态：

wiki/compile-results.tsv - 结构化的编译结果（TSV 格式）
- 字段：raw_path、hash、last_modified、wiki_paths、compile_time、status
- 记录每个 raw 文件的编译状态和生成的 wiki 文档
wiki/compile.log - 详细的编译日志
- 记录每次编译的输入、输出、决策过程
- 用于调试、审查和回溯
wiki/sources.md - 来源文档索引
- 记录所有原始来源的标题和 URL
- 格式：- [标题](URL) 的无序列表
- 按"学术论文"、"概念文章"、"实践指南"等分类组织
- 每次增量编译后更新

Wiki 文档元数据

每个 wiki 文档的 YAML frontmatter 都包含 raw_sources 字段：

---
title: 文档标题
source: [来源名称]
raw_sources:
  - path: raw/source-file.md
    hash: “sha256:abc123...”
---

常用命令

# 查看所有已编译文件
cat wiki/compile-results.tsv

# 查找特定文件的编译状态
grep “raw/xxx.md” wiki/compile-results.tsv

# 查看最近的编译日志
tail -100 wiki/compile.log

# 查看上次编译摘要
grep “=== 编译完成 ===” -A 5 wiki/compile.log

增量编译检查清单

扫描检查：运行扫描，检查 raw/ 目录中是否有新增或修改的文件
哈希对比：与 compile-results.tsv 中的记录对比，确认变更
日志记录：将检查过程写入 compile.log
只编译变更：仅处理新增或修改的文件
更新 frontmatter：确保新编译的 wiki 文档包含 raw_sources
更新状态文件：追加/更新 compile-results.tsv 中的记录
更新来源索引：更新 sources.md，添加本次新增的来源

8. 最佳实践提示

手离开键盘：不要手动修改 wiki/ 目录下的内容，所有的修改应通过”向 LLM 发出 Lint 任务”或”添加 raw 素材后重新编译”来完成。
搜索即创作：把每一次对知识库的提问看作是一次”知识合成”，务必将高质量的回答存回库中。
结构化思考：在生成任何长篇文档前，先让 LLM 在内存中构建该主题的”概念地图”。
利用编译日志：遇到问题时，先查看 wiki/compile.log 了解之前的编译过程。

12 KiB Raw Blame History Unescape Escape