LLM Wiki

Appearance

Built 26/04/17 09:31commit 4c9ce40

LLM Wiki ​

中文 | English

使用这个 skill 来操作一个由仓库支撑的 markdown wiki，其精神与 Karpathy 的 LLM Wiki gist 一致：

  • raw source 的内容实质即使在 raw 目录被重组时也保持稳定
  • wiki 是持久、会不断累积的产物
  • index.md 和 log.md 是系统中的一等文件
  • AGENTS.md 负责告诉模型如何维护这个 wiki
  • vault 本身作为 git 仓库维护

关键规则是明确分工：

  • 模型负责阅读、综合、创建页面、修订页面、处理冲突，以及交叉链接
  • 脚本只负责帮助发现 vault、引导初始化、结构 lint，以及安全的路径重构

除非用户明确提出，否则不要把 ingest、query 或 synthesis 变成僵硬脚本。

Maintainer Posture ​

像维护一个活的 wiki 的维护者那样行动，而不是像一次性总结器那样行动。

这意味着：

  • 优先集成，而不是孤立记笔记
  • 优先修订 canonical page，而不是制造重复页面
  • 优先把耐久知识保留在 markdown 里，而不是让它困在聊天历史中
  • 优先明确暴露分歧和不确定性，而不是悄悄把它们抹平
  • 优先保留有意图的 git 历史，让 vault 的演化可检查
  • 优先维护同步的英文与中文 sibling 页面，而不是临时混杂语言
  • 优先做有意图的 taxonomy refactor，而不是放任 wiki 退化成又平又大的目录
  • 当用户要求做例行清理或整理目录时，先检查是否已经出现明显的 raw/ 或 wiki/ taxonomy 漂移，再决定是否只做表层卫生清理

Root Resolution ​

在开始 wiki 工作前，按以下顺序解析 vault root：

  1. --root <path>
  2. LLM_WIKI_ROOT
  3. ~/.llm-wiki/config.json 中的 root
  4. 最近的、同时包含 raw/、wiki/、AGENTS.md、index.md 和 log.md 的祖先目录

使用：

bash
python3 .codex/skills/llm-wiki/scripts/resolve_vault.py

打印完整解析后的配置：

bash
python3 .codex/skills/llm-wiki/scripts/resolve_vault.py --format json

唯一的配置文件是全局默认配置文件：

~/.llm-wiki/config.json

它用于：

  • root：llm-wiki 内容目录
  • 默认目录和文件名
  • 自动维护的 scheduler 设置

除非用户明确要求，否则不要把面向机器的配置放进每个 vault 内。

Automation ​

全局配置里可能包含两种之一：

  • 一个用于单个周期维护任务的旧式 scheduler 对象
  • 一个 scheduler 默认值对象，再加一个用于多个命名维护任务的 schedulers 对象

建议的每任务字段：

  • enabled
  • interval_minutes
  • label
  • codex_path
  • log_dir
  • lock_file
  • state_file
  • max_runtime_minutes
  • prompt

建议拆分为：

  • 一个高频内容维护任务，用于整合新 raw 材料并修复高优先级漂移
  • 一个每日目录维护任务，用于检查 raw/ 和 wiki/ 的目录结构是否触发重构启发式，并且只有结构确实漂移时才落地移动
  • 让 taxonomy 任务保持比一般清理更窄：优先抽出一个高价值子树，而不是把所有家族一股脑重排成更深层级

使用这些辅助脚本：

bash
python3 .codex/skills/llm-wiki/scripts/manage_launch_agent.py install
python3 .codex/skills/llm-wiki/scripts/manage_launch_agent.py status
python3 .codex/skills/llm-wiki/scripts/manage_launch_agent.py run-now
python3 .codex/skills/llm-wiki/scripts/manage_launch_agent.py uninstall
python3 .codex/skills/llm-wiki/scripts/manage_launch_agent.py status taxonomy_patrol
python3 .codex/skills/llm-wiki/scripts/manage_launch_agent.py run-now content_patrol

自动化应运行完整维护 pass：

  • 检测新加入的 raw 文件
  • 检测哪些 raw PDF 还缺 markdown 转写、翻译或 wiki 集成，并明确走短 PDF 还是长 PDF 路径
  • 修复 broken links 或 translation drift
  • 刷新 index 和 log 文件
  • 对 material change 做 commit
  • 当这轮修改影响用户可见内容时，在推送前运行仓库本地验证或构建命令

不要把 taxonomy refactor 强行塞进与内容 ingest 相同的节奏里。当用户同时想要两类自动化时，优先为不同 prompt 和不同间隔建立独立命名任务。

当人类要求做例行清理时，不要把它理解成只处理 .gitignore、缓存或构建产物。先检查是否已有一两个 source family 足够清晰，值得落地一次窄范围 taxonomy refactor；只有在这种重组没有根据时，才退回到纯卫生清理。

自动化也必须避免重叠：

  • 如果上一次调度运行仍然活跃，下一次应直接退出，而不是启动第二个 Codex 进程
  • 使用 lock file，避免重叠间隔破坏 vault 或在 git 状态上竞争
  • 持久化上次运行状态，让超时与失败在 status 中可见
  • 如果上一次运行超时或失败，把它的摘要反馈给下一次运行，让维护可以继续，而不是盲目从头开始
  • 保持 prompt 聚焦，并给运行提供结构化上下文块，而不是长篇自由文本指令墙
  • 在 prompt 里把最终预推送步骤写清楚：如果仓库存在本地构建或验证命令，scheduled maintenance 应在 commit 和 push 前先本地跑过

Bilingual Rules ​

这个 wiki 是中英双语的。

  • 英文页面使用 canonical 的无后缀路径
  • 中文页面使用 sibling .zh.md 文件
  • Markdown raw source 翻译使用 raw/ 下的 sibling .zh.md 文件
  • Raw translation sibling 必须保持对源文本的忠实翻译；不要把 raw/*.zh.md 变成总结笔记、删节重写或编辑性综合
  • 截图等视觉 raw 资产可以跨语言共享，不需要重复的 .zh 图片 sibling
  • README.md 和 docs/ 下文件这类 human-facing repo docs 也使用 sibling .zh.md 文件
  • index.md 和 index.zh.md 是双语根目录索引
  • wiki/ 中每一个 durable page，包括 source page，都应有双语版本
  • 在两种语言版本上都要把语言切换链接直接放在标题下方
  • markdown raw source sibling 本身也要在靠近顶部的位置放语言切换链接
  • 当存在翻译 raw 文件时，要从 source page 的两种语言版本都链接到两个 raw 版本
  • 当页面发生 material 变化时，在可行情况下要在同一轮同步更新其 sibling 翻译

Translation Freshness ​

把翻译当作维护中的 sibling，而不是一次性导出品。

  • 把 raw/*.zh.md 视为翻译产物，而不是综合表面。如果要总结、解释或重组材料，应在 wiki/ 中做
  • 如果英文 wiki 页面发生 material 变化，在可行情况下同一轮更新 .zh.md sibling
  • 如果中文 wiki 页面发生 material 变化，也应检查英文 sibling 是否需要变化
  • 如果英文 raw source 改变或被替换，在可行情况下同一轮更新它的 raw/*.zh.md sibling
  • 如果视觉 raw 资产发生 material 变化，在可行情况下同一轮更新解释它们的双语 source page
  • 如果翻译暂时无法更新，在翻译文件或页面 frontmatter 中标记 translation_status: stale
  • 一旦翻译追平，就移除 stale 标记

Bootstrap ​

如果 vault 尚不存在，用下面命令初始化：

bash
python3 .codex/skills/llm-wiki/scripts/bootstrap_vault.py --root .

这会创建：

  • AGENTS.md
  • raw/
  • wiki/ 子目录
  • index.md
  • log.md
  • starter overview 页面
  • 如果 vault root 还不是 git 仓库，则初始化 git 仓库

布局细节见：

  • references/vault-layout.md
  • references/page-schema.md

Git Workflow ​

把 vault root 当作 git 仓库来对待。

修改内容前：

  1. 检查 vault root 是否已有自己的 .git
  2. 如果没有，用 git init <vault-root> 初始化

在任何 material ingest、query 回写或 lint pass 之后：

  1. 审查 diff
  2. 需要时先检查 origin 是否有更新提交，并将本地 master 同步到 origin/master
  3. 除非用户明确要求不要 commit，否则对 vault 变更做 commit
  4. 使用能解释知识库为何变化的 commit message，而不是只描述改了哪些文件
  5. 推送前，如果仓库有本地验证命令或站点构建命令，先把它作为最终预推送检查跑一遍
  6. 将结果 commit 同时 push 到 origin 与 gitlab

如果仓库策略要求特定 commit 格式，就遵循它。 当远端分歧时，除非用户明确另有说明，否则把 origin 当作权威。

Ingest Workflow ​

当用户要求 ingest 一个 source 时：

  1. 解析 vault root
  2. 阅读 AGENTS.md
  3. 在编辑前先读 index.md 和相关的现有 wiki 页面
  4. 从配置好的 raw 目录读取 source
    • 如果 source 是截图或其他图像文件，先运行 .codex/skills/llm-wiki/scripts/extract_visual_sources.py
    • 如果 source 是带本地图像或图表的 markdown，且这些视觉内容会实质影响综合，就对这些本地视觉内容做 OCR
    • 如果 source 是 PDF，使用 pdf skill 作为文档处理层，而不是把 PDF 当作无法进入维护循环的二进制黑盒
    • 对 PDF ingest，要保留原始 .pdf 文件，并在它旁边创建 markdown raw sibling 后再做 wiki 综合。这个 markdown raw 文件是未来巡检应继续维护的文本表面，而不是 PDF 的替代品
    • 如果 PDF 工作流依赖 pdfinfo、pdftotext 或 pdftoppm 之类的本地工具但当前缺失，应先安装好再继续，而不是停在缺工具错误上
    • 根据文档长度和复杂度选择翻译路径。较短的 PDF 优先直接从源码 markdown 或 PDF 内容做模型翻译，而不是先机械生成一版再额外做一轮润色
    • 默认把大约文章长度的 PDF 视为短文档，例如 15 页左右且没有高密度表格或图表；更长或结构噪声更大的文档则走更稳妥的工具辅助路径
    • 以阅读顺序把 PDF 文本抽成 markdown，修复明显的 PDF 转 markdown 损伤，并保持 markdown 对原文忠实，而不是把它改写成摘要
    • 如果版面、图表、表格或插图会实质影响理解，把相关 PDF 页渲染为本地图片资源，并从 markdown raw 文件中链接它们，让后续维护仍能访问视觉证据
    • 对短 PDF，在英文 markdown raw 文件稳定后，让模型直接生成 .zh.md sibling，并用一轮仔细翻译替代“机械翻译再润色”的双重流程
    • 对长 PDF，用工具辅助抽取加模型清理的路径创建或刷新 .zh.md sibling；如果无法在同一轮完成翻译，就加上 translation_status: stale
  5. 直接在 markdown 中创建或修订 durable wiki 状态：
    • wiki/sources/ 中的 source page
    • 任何受影响的 concept、entity 或 topic 页面
    • index.md
    • index.zh.md
    • log.md
  6. 如果文件发生了 material 更新，就对这次 vault 变更做 commit
  7. 保持 source-of-truth 边界：绝不重写 raw 目录中的文件实质内容

在编辑前，先判断这个 source 主要是：

  • 向现有页面补充内容
  • 与现有页面形成冲突
  • 暗示应该存在一个新页面
  • 改变某个 topic 当前的综合结论

编辑后，要确保这个 source 不只反映在 wiki/sources/，也反映在最相关的长期页面中。 还要确保 source page 和受影响的长期页面继续保持双语。 如果这次 ingest 起点是 PDF，要确保 source page 为快速跳转而链接原始 PDF 和生成出的 markdown raw sibling。 如果翻译 raw 文件已存在或在本轮被创建，确保 source page 为了快速跳转而同时链接两个 raw 版本。 如果任何翻译 sibling 没有在同一轮更新，要明确标记其 stale。

Source page 的默认行为：

  • 概述该 source 带来了什么
  • 记录最强的说法或观察
  • 当截图是证据的一部分时，记录视觉观察和基于 OCR 的摘录
  • 如果 source 最初是 PDF，还要记录 markdown raw 是否完整、是否抽取了视觉资源，以及翻译 sibling 是否是当前版本
  • 明确记录冲突或不确定性
  • 添加受影响页面的链接

模型应把 ingest 当作整合工作，而不是简单记笔记。一个 source 可能需要触及许多现有页面。

PDF Ingest Pattern ​

当 scheduled maintenance 或手动 ingest 遇到新的 raw PDF 时，使用这个模式：

  1. 保留原始 raw/.../source.pdf
  2. 生成或刷新 raw/.../source.md，作为忠于原文的 markdown raw 产物
  3. 判断这个 PDF 属于短文档还是长文档
  4. 对短 PDF，在英文 markdown raw 稳定后，让模型直接翻译成 raw/.../source.zh.md
  5. 对长 PDF，先走工具辅助抽取，再用模型修复结构、术语和翻译质量
  6. 为图表、插图或扫描页补齐必要的本地视觉资源，放在该 source family 附近，保证后续维护还能正确渲染和引用
  7. 创建或更新双语 wiki/sources/ 页面，明确链接 PDF、markdown raw、翻译 raw，以及任何关键视觉证据
  8. 更新相关长期 wiki 页面，然后在 commit / push 前跑完仓库的最终本地验证步骤

Taxonomy Refactors ​

随着语料增长，当当前目录不再好用时，重组目录结构。

典型信号：

  • 一个目录里有太多松散相关的页面
  • 一个 topic 已经明显分裂成多个稳定子域
  • source page 或 answer page 需要领域专属子目录
  • 若干页面显然属于同一个稳定 family，放在一起会更好浏览
  • 当前目录已经难以扫读，即使新边界已经足够明显

执行 taxonomy refactor 时：

  1. 决定新的目录拆分
  2. 优先按 family 分组，而不是机械地统一加深目录层级。先抽出最高价值、边界最稳定的子树，不要把每个家族都强行再套一层目录
  3. 移动后保持英文和中文 sibling 页面相邻
  4. 除非它明确解锁了已存在的稳定 family 边界，否则避免制造只放一对文件的一文件目录
  5. 如果某个 source family 带有配套视觉资源，且共置后能让 markdown 路径更短、更易维护，就优先一并共置这些资源
  6. 移动页面，而不是复制页面
  7. 在同一轮重写受影响的链接
  8. 更新 index.md、index.zh.md、overview 页面及任何受影响的导航页面
  9. 将这次重构作为一个有意图的变更提交

当需要安全移动并自动重写链接时，使用辅助工具：

bash
python3 .codex/skills/llm-wiki/scripts/move_markdown_pages.py --repo . --move wiki/topics/foo.md:wiki/topics/sub/foo.md

如果有多个移动，重复使用 --move。

Raw Taxonomy Refactors ​

把 raw/ 视为内容实质稳定，而不是路径布局冻结。

典型信号：

  • raw/ 已经变成一个混杂太多无关文件的平面堆
  • 某个 source family 明显值得拥有自己的子目录
  • 翻译 raw sibling 在原始 source 旁边已经不好找
  • 某个稳定本地资源包（例如截图或 PDF 渲染页）显然属于同一个 source family，共置后会更易维护
  • family 边界已经清楚到继续等待文件数量阈值只会增加噪音

执行 raw taxonomy refactor 时：

  1. 保持 source 实质内容不变；只重写因为文件移动而需要修改的路径依赖元数据或本地链接
  2. 当原始 raw 文件和 .zh.md sibling 都存在时，一起移动
  3. 优先把稳定 source family 抽成自己的子树，而不是把所有内容都塞进一个更宽泛的 provider 目录
  4. 不要因为“可以更深”就盲目加深目录；如果只有一对英文/中文文件会住进去，而且并没有让更大的 family 边界更清楚，就保持原样
  5. 如果某个 raw source 依赖稳定的本地资源包，例如截图或 PDF 渲染页，当共置后能让相对路径更简单时，优先把这些资源与该 raw family 放在一起
  6. 在同一轮重写 repo docs、wiki pages、indexes 和受影响 raw markdown 文件里的链接
  7. 重新运行 lint，让 broken raw links 或缺失 raw translations 立即暴露出来
  8. 如果 refactor 会影响渲染结果，在 commit / push 前运行仓库的本地验证或构建命令
  9. 将这次 refactor 作为一个有意图的变更提交

使用辅助工具安全移动 raw 并修复链接：

bash
python3 .codex/skills/llm-wiki/scripts/move_raw_sources.py --repo . --move raw/foo.md:raw/articles/foo.md

目录移动也是允许的：

bash
python3 .codex/skills/llm-wiki/scripts/move_raw_sources.py --repo . --move raw/clippings:raw/articles/clippings

Visual Source Extraction ​

在把大量截图类 source 整合进 wiki 前先做 OCR。

支持的输入：

  • raw/ 下的直接图像文件，例如 .png、.jpg、.jpeg、.webp、.heic 和 .tiff
  • 引用了本地图像文件的 markdown raw source

使用辅助工具：

bash
python3 .codex/skills/llm-wiki/scripts/extract_visual_sources.py --repo . --path raw/screenshots/foo.png --lang chi_sim+eng

或者处理所有 raw 图像：

bash
python3 .codex/skills/llm-wiki/scripts/extract_visual_sources.py --repo . --all-raw-images

这个辅助工具会：

  • 使用本地 tesseract 提取 OCR 文本
  • 当本地安装了 chi_sim 或 chi_tra 时，默认使用紧凑的中文优先 OCR 组合
  • 支持在本地安装 chi_sim 或 chi_tra 等 Tesseract 语言包时进行中文 OCR
  • 记录基础图像元数据，例如格式和尺寸
  • 支持对截图密集型 vault 做批量提取
  • 不会自行更新 wiki；模型仍需把提取出来的证据整合进 source、topic 或 answer 页面

Query Workflow ​

当用户提出一个知识问题时：

  1. 解析 vault root
  2. 先读 index.md
  3. 只读取足以回答好的页面
  4. 用页面级 citations 回答
  5. 如果答案形成 durable knowledge，把它写回 wiki/answers/ 或更新相关长期页面
  6. 当答案实质改变 vault 时，在 log.md 中追加 query 条目
  7. 如果文件发生了 material 更新，就对这次 vault 变更做 commit

当 wiki 已经包含相关综合时，不要只从 raw sources 回答，除非问题明确要求重新检查 raw 证据。

当 query 产出耐久内容时，优先选择以下结果之一：

  • 更新现有 concept 或 topic 页面
  • 在 wiki/answers/ 中创建新页面
  • 添加交叉链接，让新的综合未来可被发现
  • 保持英文与中文版本对齐

Lint Workflow ​

先运行内置 lint：

bash
python3 .codex/skills/llm-wiki/scripts/lint_vault.py

lint 会检查：

  • 缺失的必需 vault 文件
  • broken markdown links
  • 失效的 Obsidian-style wikilinks
  • 仓库 markdown 中的绝对本地文件系统链接
  • 缺失的翻译 sibling
  • 孤立的 wiki 页面

然后修复最高价值的问题：

  • 矛盾
  • 过时摘要
  • 缺失的交叉链接
  • 应该存在却不存在的页面

模型应把 lint 当作编辑性维护，而不只是修链接。

好的 lint pass 还常常会产出：

  • 更锐利的 overview 页面
  • 更干净的 source 到 concept 链接
  • 一份值得下一步调查的未回答问题短清单
  • 一次在 vault 确实变化时记录该维护 pass 的 commit

Index And Log ​

把 index.md 和 log.md 当作运维原语，而不是附带文件。

  • index.md 是模型应该首先阅读的内容地图
  • log.md 是对改变了 vault 的 ingest、耐久 query 和 lint pass 的按时间倒序运维记录

推荐的 log.md 标题格式：

markdown
## [YYYY-MM-DD HH:MM] ingest | Source Title
## [YYYY-MM-DD HH:MM] query | Question or answer topic
## [YYYY-MM-DD HH:MM] lint | Maintenance summary

保持 index 条目简短：一个链接加一行说明。 新日志条目应精确到分钟。 将新日志条目插入条目列表顶部附近，而不是追加到末尾。 不要把 log.md 当作脚本、配置或发布说明式内容的通用 changelog。 只有在调度巡检真正落地了 vault 变更时，才更新 log.md。

Guardrails ​

  • 把 raw source 实质内容视为不可变；raw refactor 期间只允许做路径维护型编辑
  • 当截图嘈杂或不完整时，把 OCR 输出视为支持性证据，而不是替代编辑判断
  • 优先更新现有页面，而不是创建近似重复页
  • 保持链接相对且可跨 repo 搬运
  • 当本地链接目标包含空格时，使用包在尖括号中的 markdown 目标
  • 不要把绝对本地文件系统路径写进仓库 markdown，除非用户明确要求
  • 不要把完整英文和中文版本混在同一长页里；应使用 sibling translation 页面
  • 在每次 ingest 和耐久 query 输出时都更新 index.md 和 log.md
  • 凡是会影响渲染结果的 scheduled 或手动维护，都应在 commit / push 前完成本地构建或等价验证
  • 保持 schema 简短、具体；当维护模式变化时再演化它
  • wiki 应随时间积累知识，而不是在每次提问时都从头重算