LLM Wiki 项目初始化指南
本文档适用于任何 OpenCode 实例。将本文档内容复制到新项目的 AGENTS.md 和对应文件中即可直接使用。
一、目录结构
your-wiki-project/
├── AGENTS.md # ← 核心配置文件（见下方内容）
├── raw/ # ← 所有原始材料（AI 只读不改）
│ └── （放入你的笔记、文档、技术方案等）
├── wiki/ # ← AI 编译后的结构化知识库（核心）
│ ├── INDEX.md # ← 全局索引导航（编译自动生成）
│ └── log.md # ← 编译历史记录（编译自动追加）
└── outputs/ # ← 所有问答、分析、决策输出
└── （AI 自动保存）
说明：
raw/— 原始材料仓库，AI 只读取，不修改。放入任何格式的笔记、文档、技术方案wiki/— 编译产物，结构化的[[wiki-link]]交叉引用知识库，人类和 AI 都能完美理解outputs/— 临时产出，问答、分析、总结等一次性输出
二、项目级 AGENTS.md（直接复制）
将以下内容完整复制到新项目的根目录 AGENTS.md：
# CLAUDE.md - Personal Knowledge Base
## 目的
这是一个 [你的主题] 的个人知识库。
目标：将 raw/ 里的原始材料自动编译成结构化、可搜索、能自我迭代的 Wiki。
## 核心原则
- 保持 super simple and flat（Karpathy 原话）
- 只有 .md 文件，没有数据库和复杂结构
- 人类能读懂，AI 也能完美理解
- 所有知识最终落在 wiki/ 文件夹
## 文件夹结构
- raw/ → 所有原始材料（AI 只读不改）
- wiki/ → AI 编译后的结构化知识库（核心）
- outputs/ → 所有问答、分析、决策输出
## 编译规则（当我说 "compile the wiki" 时执行）
1. 读取 raw/ 里所有新增文件
2. 创建/更新 wiki/INDEX.md：
- 目录表格，每个主题的简要描述 + 链接
- 全局关键洞见总结
3. 为每个主要主题创建独立 .md 文件（kebab-case 命名）
4. 每篇文章的标准结构：
- Summary（200-400 字高度浓缩）
- Key Points（bullet points）
- Connections（与其他主题的交叉链接）
- Sources（列出 raw/ 里的原始文件来源）
- Open Questions / Contradictions（必须标出）
- Last Updated: YYYY-MM-DD
## 查询规则
- 回答问题时优先搜索 wiki/，必要时回溯 raw/
- 好的回答回存到 wiki/ 或 outputs/
- 所有引用必须指向原始来源
## 健康检查规则（当我说 "lint the wiki" 时执行）
- 检查矛盾：不同页面的说法是否一致
- 检查完整性：关键概念是否有独立页面
- 检查孤岛：哪些页面没有任何入链
- 检查过时：是否有被新来源推翻的旧论断
三、用户级 AGENTS.md 配置（推荐）
以下是用户全局配置（通常位于 ~/.config/opencode/AGENTS.md），包含交互偏好、工作流编排和自动保存规则。建议复制到全局配置中，所有项目共享：
## 交互要求
1. 强制要求，思考和回复，必须使用中文
## 工作流编排
1. 默认进入规划模式
- 非简单任务（3+步骤或架构决策）先规划再动手
- 偏离方向时立即停下重新规划
2. 自我改进循环
- 用户纠正后：记录到 tasks/lessons.md
- 会话开始时回顾当前项目的经验教训
3. 追求优雅（适度平衡）
- 非简单更改：问自己"有没有更优雅的方式？"
- 简单修复跳过此步，不要过度设计
4. 自主修复 Bug
- 收到 Bug 报告直接修复，不请求手把手指导
- 主动修复失败的 CI 测试
5. 代码开发与设计的标准流程（OMO 工作流）
- 当用户的请求涉及代码开发、功能实现、代码设计、架构决策时，必须遵循以下 5 阶段流程，不能跳步：
阶段流程: 设计 → 隔离 → 规划 → 执行 → 完成
1️⃣ brainstorming → 完成后提醒：`using-git-worktrees` 或 `writing-plans`
2️⃣ using-git-worktrees → 完成后提醒：`writing-plans`
3️⃣ writing-plans → 完成后提醒：`subagent-driven-development`（快）或 `executing-plans`（稳）
4️⃣ 执行完成 → 提醒：`finishing-a-development-branch`
5️⃣ finishing → 提醒：`requesting-code-review` 或合并
- 简单 Bug 修复例外：直接 `systematic-debugging`
- 每阶段完成必须告知用户当前位置和下一步选项
- 用户要跳步时提醒风险但尊重决定
## 任务管理
- 规划和进度记录到 tasks/todo.md
- 用户纠正后更新 tasks/lessons.md
## 全局产出自动保存规则
- **原始知识素材**（笔记、教程、指南、决策记录等）→ 保存到当前工作目录的 `raw/` 目录下
- **问答/分析/决策输出**（总结、分析、问答记录等）→ 保存到当前工作目录的 `outputs/` 目录下
- 如果目标项目没有对应目录，自动创建
- 文件命名：kebab-case，带日期前缀，例如 `2026-04-13-llm-wiki-guide.md`
- 文件格式：YAML frontmatter（title, source, author, created, description, tags）+ 正文
- 这是"捕获优先"原则——先存原始材料，后续再通过各项目的编译规则整理
## Wiki 自动行为规则
- **查询优先**：回答用户问题时，优先搜索 `wiki/` 中的已编译知识，再回溯 `raw/` 原始材料
- **编译和 lint 由 skill 手动触发**：`wiki-compile` skill 负责编译，`wiki-lint` skill 负责健康检查
四、初始 wiki/INDEX.md（模板）
新项目首次编译时自动生成，也可手动创建初始版本：
# Wiki Index
## Overview
本知识库覆盖 [你的领域1]、[你的领域2]、[你的领域3] 等领域。当前共收录 X 篇原始来源，Y 个索引页面。
（AI 编译时会自动更新此段落）
## Sources
### [分类 1]
| 来源 | 描述 | 关联页面 | Last Updated |
|------|------|----------|-------------|
| （AI 自动填充） | | | |
### [分类 2]
| 来源 | 描述 | 关联页面 | Last Updated |
|------|------|----------|-------------|
| （AI 自动填充） | | | |
## Concepts
- [[页面名1]] — 简要描述
- [[页面名2]] — 简要描述
## Key Entities
- [[业务上下文1]] — 描述
- [[业务上下文2]] — 描述
五、初始 wiki/log.md（模板）
# Wiki Log
## [YYYY-MM-DD] compile #1 | 首次编译：X 个 raw 文件，生成 Y 个 wiki 页面
### 处理来源
- **新增**: （列出文件列表）
### 生成页面
1. `页面1.md` — 描述
2. `页面2.md` — 描述
### 编译统计
- 原始来源：X 文件
- 生成页面：Y 文件（含 INDEX.md, log.md）
- 主题分类：Z 大类
- 交叉引用：已建立页间 `[[wiki-link]]`
- Open Questions：已标出 N 个待解决问题
六、OpenCode skill 配置
1. wiki-compile skill
在 OpenCode 的 skill 注册表中注册以下 skill（如果尚未自动注册）：
name: wiki-compile
description: Use when user says "compile the wiki" or "build wiki" or "compile wiki" — reads raw/ directory, ingests new sources, and generates a structured wiki in wiki/ with INDEX.md, topic pages, cross-references, and summaries.
scope: project
触发词：compile the wiki、build wiki、编译 wiki
2. wiki-lint skill
name: wiki-lint
description: Use when user says "lint the wiki" or "检查 wiki" or "wiki health check" — checks wiki for contradictions, stale claims, orphan pages, missing concept pages, and broken cross-references.
scope: project
触发词：lint the wiki、检查 wiki、wiki health check
七、快速启动步骤
Step 1: 创建项目目录
mkdir my-wiki && cd my-wiki
mkdir raw wiki outputs
Step 2: 配置 AGENTS.md
- 项目级：将第二节中的内容复制到项目根目录
AGENTS.md - 用户级（推荐）：将第三节中的内容复制到
~/.config/opencode/AGENTS.md，所有项目共享
Step 3: 放入原始材料
将你的笔记、文档、技术方案等放入 raw/ 目录。
Step 4: 首次编译
在 OpenCode 中说：
"compile the wiki"
AI 会自动：
- 读取
raw/所有文件 - 按主题分类生成
wiki/*.md页面 - 创建
wiki/INDEX.md全局索引 - 初始化
wiki/log.md编译记录
Step 5: 日常使用
| 操作 | 指令 | 效果 |
|---|---|---|
| 添加新材料 | 将文件放入 raw/，然后说 "compile the wiki" | 新内容被编译到 wiki/ |
| 查询知识 | 直接问问题，如 "SKU 表达升级做了什么？" | AI 优先搜索 wiki/ 回答 |
| 健康检查 | "lint the wiki" | 检查矛盾、孤岛、过时内容 |
| 保存分析 | 直接提问 | 好回答自动保存到 outputs/ |
八、wiki 页面标准格式
每个 wiki/*.md 页面的标准结构：
# [主题标题]
## Summary
200-400 字高度浓缩的核心内容摘要。
## Key Points
- **关键点 1**：详细说明
- **关键点 2**：详细说明
- **关键点 3**：详细说明
## Connections
- [[相关页面1]] — 关联说明
- [[相关页面2]] — 关联说明
## Sources
- `../raw/原始文件名.md`
## Open Questions / Contradictions
- 待确认的问题 1
- 与其他文档的潜在矛盾
## Last Updated: YYYY-MM-DD
九、最佳实践
1. raw/ 管理
- 文件命名：kebab-case，带日期前缀（如
2026-04-13-技术方案.md） - 定期清理已编译的旧文件（可选，建议保留作为历史追溯）
2. wiki/ 维护
- 每次编译后运行
lint the wiki检查质量 - 发现断裂链接或孤岛页面及时修复
- 保持
[[wiki-link]]格式的一致性
3. outputs/ 管理
- 按日期命名：
YYYY-MM-DD-主题.md - 重要的分析可考虑提炼到
wiki/成为独立页面
4. 增量更新
- 新文件放入
raw/后只需说 "compile the wiki" - AI 会自动识别新增文件，不会重复编译已有的
log.md自动追加新的编译记录
十、常见问题
Q: raw/ 里文件太多会不会影响编译速度？
A: 不会。AI 会增量识别新文件，只处理新增内容。
Q: wiki 页面命名规则？
A: kebab-case，全小写，如 service-express-upgrade.md。避免中文、空格、特殊字符。
Q: 如何删除过时的 wiki 页面？
A: 直接删除 wiki/ 下对应文件，然后 lint the wiki 会自动发现断裂链接。
Q: 可以在 wiki/ 里手动编辑内容吗？
A: 可以。但建议保持 AI 编译的格式一致性，手动改动后建议运行 lint the wiki。
Q: 多人协作怎么办？
A: 每个项目独立，通过 git 管理。raw/ 可以共享，wiki/ 各自编译。
