使用指南

中文 | English

仓库结构

核心结构：

llm-wiki/
├── AGENTS.md
├── index.md
├── index.zh.md
├── log.md
├── raw/
└── wiki/

含义：

• raw/ 原始资料层。里面既可以放 markdown，也可以放截图和本地图片资产。来源的实质内容应保持稳定，但当同一轮修好链接和路径元数据时，允许做路径级重组。
• wiki/ 由模型维护的知识层，包括 sources/、topics/、concepts/、answers/ 等页面。
• AGENTS.md schema。定义模型如何维护这个知识库。
• index.md / index.zh.md 中英双语目录入口。
• log.md 巡检、ingest、query、lint 的维护日志。

日常使用

手动 ingest

把资料放进 raw/ 后，在 Codex 新会话里可以这样说：

$llm-wiki ingest raw/xxx.md
先读 AGENTS.md 和 index.md，再更新 wiki/sources/、相关 concept/topic/entity 页面，最后更新 index.md、index.zh.md 和 log.md。

如果来源是截图或图片文件，先抽 OCR：

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

然后再让 Codex 把截图当成 source ingest，把 OCR 支撑的证据整合进 wiki/sources/ 和相关长期页面。

手动 query

$llm-wiki 回答这个问题：……
先从 index.md / index.zh.md 找相关页面，再读必要页面。
如果答案值得长期保留，就写回 wiki/answers/ 或更新已有页面，并更新 log.md。

手动 lint

$llm-wiki 对整个 vault 做一次 lint pass
检查矛盾、过时结论、孤儿页、缺失 cross-links、缺失译文、stale 译文，并在有改动时提交。

raw 目录重组

当 raw/ 变得过平、难以导航时，可以在不改来源实质内容的前提下移动文件或目录：

• 只要某个稳定 source family 已经足够清晰，整理后能明显改善导航，就可以开始重组。
• 优先按 source family 归拢，而不是等待目录计数跨过某个阈值。
• 除非它能明确表达一个长期稳定的家族边界，否则不要制造只有一个文件的目录。

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

完成后立刻跑一遍 lint，检查是否还有残留失效链接：

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

批量截图 OCR

当 vault 里积累了很多截图时，可以在 ingest 或 lint 前先批量抽一轮 OCR：

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

如果截图是多语言的，先检查本机 OCR 语言：

tesseract --list-langs

这个仓库现在要求本地具备中文 OCR 能力。在 macOS + Homebrew 上，先执行 brew install tesseract-lang，然后简体中文截图优先用 --lang chi_sim+eng，繁体中文截图优先用 --lang chi_tra+eng。 如果本机已经装了 chi_sim 或 chi_tra，即使不显式传 --lang，这个脚本现在也会默认走紧凑的中文优先 OCR 组合。

双语约定

整个 llm-wiki 是中英双语的。

规则如下：

• 英文页面使用 canonical 路径
• 中文页面使用 sibling .zh.md
• index.md 和 index.zh.md 是中英双语根目录
• 所有长期页面都应双语成对出现
  • 包括 wiki/sources/
  • 也包括 wiki/answers/

raw 层也双语

raw/ 里的 markdown 原始文件也支持 sibling 译文：

• 原文：raw/foo.md
• 中文译文：raw/foo.zh.md

这里的中文 sibling 必须是忠于原文的翻译，不能压缩成总结版，也不能把翻译和编辑性提炼混在一起。概括、解读和整理应放到 wiki/。

原文和译文都应在页首放快速切换链接：

[中文](<foo.zh.md>) | English

中文 | [English](<foo.md>)

source page 对 raw 原文/译文都可跳转

wiki/sources/*.md 页面里应同时提供：

• 原始 raw 文件
• 中文译文 raw 文件

独立截图和其他视觉资产不需要额外复制一份 .zh 图片；双语解释应写在 source page 里。

译文新鲜度

译文不是一次性导出物，而是被维护的 sibling。

规则：

• raw/*.zh.md 要尽量贴近原文表达；如果现在更像总结而不是翻译，应视为不合格并回到忠实翻译。
• 原文页面有 material change 时，应尽量同次更新译文
• raw 原文有 material change 时，应尽量同次更新 raw/*.zh.md
• 如果一时没法同步，给落后的译文加 frontmatter：

translation_status: stale

• 译文补齐后移除这个标记