何时使用
- "把这篇内容收藏起来" → 采集
- "关于 XX 查一下" → 查询
- "检查完整性" → 健康检查
能力边界
| 类型 | 说明 | 处理方式 |
|---|---|---|
| ✅ 适合 | 结构化/半结构化文本（md/txt/html/json），单篇 ≤ 1MB | 正常导入 |
| ⚠️ 勉强 | 图片/PDF（需 OCR 预处理后以文本形式采集） | 先手动提取文本 |
| ❌ 不适合 | 二进制文件（exe/zip/db）、超大文件（> 10MB） | 不导入 |
架构
<wiki-dir>/raw-sources/ # 原始资料（不可变）
<wiki-dir>/wiki/ # 编译知识
├── index.md # 文章索引（脚本维护）
└── <topic>/ # 主题子目录
核心原则：LLM 读 index → 定位文章 → 阅读原文 → 推理合成。零向量成本。
工作流
0. 初始化 /wiki-init
AI 检测运行时（Node.js / Python 3），询问选择，初始化知识库脚手架。
1. 采集与编译 /wiki-ingest
| 步骤 | AI 做 | 脚本做 |
|---|---|---|
| ① 读取源 | — | scripts/wiki.* dedup 检测重复（SHA256 + source URL） |
| ② 确认 metadata | 确定 title/description/tags/topic，避免过度细分 topic | — |
| ③ 写入编译 | — | scripts/wiki.* ingest（写 raw-sources + 编译 + 更新索引） |
| ④ 级联更新 | 检查是否需要合并/交叉引用 | scripts/wiki.* update-index |
> topic 粒度： 除非有明显独立领域边界，否则优先归入已有 topic。详见 references/guide.md。
2. 查询 /wiki-query <问题>
AI：读 index → 定位文章 → 阅读 → 综合回答并引用来源。
输出模板
## 回答
[直接回答用户问题，2-5 句]
## 来源
- `<topic>/<article>` — [具体引用位置/摘要]
- `<topic>/<article>` — [具体引用位置/摘要]
## 延伸
- [相关内容提示，引导进一步查询，可选]
3. 健康检查 /wiki-lint
脚本做确定性检查，AI 补充智能检查。
脚本检查内容：
- wiki/ 和 raw-sources/ 目录存在性
- index.md 存在且引用的文件均存在
- 孤立页面（索引未收录的文章）
- 标签质量：空格、大写、空 description
- 正文断链：扫描所有 [[wikilink]]，跨 topic 搜索对应文件，过滤图片/媒体引用
- 子索引残留（已删除 topic 的 *-index.md）
双运行时
scripts/wiki.{js,py} 预装于技能包，/wiki-init 选择后记录 .env 即可切换，无需复制。
| 运行时 | 执行 |
|--------|------|
| Node.js | node scripts/wiki.js <cmd> |
| Python | python scripts/wiki.py <cmd> |
数据存储
知识存在 <wiki-dir>/，运行时记录在 scripts/.env。
所需权限
| 权限 | 用途 |
|---|---|
filesystem.write |
创建目录和文件 |
filesystem.read |
读取知识文件和脚本 |
bash |
执行脚本 |
grep |
搜索知识库 |
常见陷阱
| 陷阱 | 解决 |
|---|---|
| 用向量思维查文件库 | 精确关键词定位后阅读 |
| 采集后不编译 | 采集后必须 ingest |
| 忽略 index.md | 先读 index.md 或子索引 |
| 未初始化就采集 | 先 /wiki-init |
| topic 过度细分 | 批采集时优先用统一 topic，跨 topic 的 [[wikilink]] 会断裂 |
采集源含 [[wikilink]] 引用其他文件 |
断链会被 lint 检出，需补采对应文件或接受为示例引用 |
正文 [[wikilink]] 无路径前缀 |
lint 已跨 topic 搜索，但如果文件名不唯一则仍可能断裂 |
反馈
opencode-skill-suite
