仓库约定

中文 | English

链接规则

• 本地链接优先使用相对路径
• 如果目标路径里包含空格，必须用角括号包起来：

[Raw file](<../../raw/File Name With Spaces.md>)

这样可以避免 Obsidian 或其他 markdown 渲染器里点击失效。

git 约定

这个知识库目录本身就是 git 仓库。

规则：

• 如果 vault 没初始化 git，bootstrap 会自动 git init
• 每次 ingest / query 回写 / lint 只要产生 material change，都应该提交
• 提交要说明“为什么改”，而不是只说“改了哪些文件”

当前忽略规则：

• .obsidian/
• .omx/
• __pycache__/

Raw 媒体布局

随着语料增长，推荐采用这些约定：

• 独立截图来源放在 raw/screenshots/
• 被 markdown 来源引用的附件型图片放在 raw/assets/
• 截图的语义解释优先沉淀到 wiki/sources/，不要把理解硬编码进文件名
• 在整合截图密集型来源之前，先运行 .codex/skills/llm-wiki/scripts/extract_visual_sources.py

Raw Markdown 卫生规则

如果某个 raw markdown 文件导致渲染异常，或让本地 VitePress 构建失败，可以在不改变来源实质内容的前提下修复它的 markdown 语法。

允许的典型修复包括：

• 把明显本该是行内代码的 \foo`` 这类误转义写法改成真正的行内代码
• 对 <name here> 这类字面量尖括号占位符做实体转义，或保持在行内代码里，避免 Vue 类渲染器把它当成 HTML
• 把 blob: 这类只在浏览器临时会话里有效的嵌入媒体替换成稳定截图或普通链接
• 移除或修复损坏的行内链接、未闭合 HTML 标签，以及其他会破坏渲染的 markdown 语法损伤

优先做最小修复，只恢复可渲染性，不改原始论点和示例含义。

目录重组

随着 wiki 和 raw 语料一起变大，目录结构允许继续演化。

规则：

• 当某个目录过于拥挤、不再利于导航时，可以继续拆分
• 对 wiki/，优先移动页面，而不是复制页面
• 对 raw/，要保持来源实质内容不变，只允许修复路径相关的链接或元数据
• 同一轮里必须修复所有受影响的链接
• 同步更新 index.md、index.zh.md 以及所有暴露这些页面的 overview / navigation 页面

可用工具：

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

整理 raw 时使用：

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

log 约定

log.md 是 vault 操作记录，不是仓库 changelog。

现在有四个明确规则：

1. 精确到时分

## [YYYY-MM-DD HH:MM] ingest | Source Title

2. 倒叙

• 最新条目在最上面
• 不是 append-only 到文件底部

3. 只用操作型 heading

• 只使用 ingest、query、lint
• 不使用 feat、fix、refactor、bootstrap 之类 release-note 风格 heading

4. 只有真正改了 vault 才写

• 只有持久知识库状态真的变化了，才写 log.md
• 定时巡检如果是 no-op，就不要改 log.md
• 纯代码、纯脚本、纯配置改动应体现在 git 历史里，而不是 log.md

旧条目如果没有可靠分钟信息，不回填伪造时间。

设计哲学该看哪里

这部分不再放在 README 里重复，而是放回 wiki 本体：

• LLM Wiki
• Knowledge Operations
• Vault Architecture