kb-wiki

name	kb-wiki
description	Use when 用户需要建立、导入、查询或维护基于 llm-wiki 理念的持久化研究知识库时，包括 UX 研究、用户访谈、竞品分析等场景

kb-wiki Skill

概述

kb-wiki 是一个 LLM 驱动的持久化知识库管理 skill。核心理念：LLM 渐进式构建和维护 Wiki（Markdown 文件集合），知识随每次导入复利增长，用户永远不需要自己编写 Wiki 内容。

类比：Obsidian = IDE，LLM = 程序员，Wiki = 代码库。用户打开 Obsidian 实时浏览，LLM 在后台持续编辑维护。

---

三层架构

your-wiki/
├── Schema.md          ← Schema 层（LLM 的工作规范，用户可自定义演进）
├── raw/               ← 原始资料层（只读，LLM 读取来源，绝不修改）
│   ├── articles/
│   ├── papers/
│   ├── assets/
│   └── data/
└── wiki/              ← Wiki 层（LLM 完全掌控，自动生成和维护）
    ├── entities/      ← 实体页面（用户、产品、组织）
    ├── concepts/      ← 概念页面（痛点、行为模式、设计模式）
    ├── sources/       ← 资料摘要页面（每份原始资料对应一个）
    ├── synthesis/     ← 综合分析页面（对比分析、概览、洞察归档、跨资料结论）
    ├── .cache/        ← 文件转换缓存（Excel/Word/PPT/PDF → Markdown，自动管理）
    ├── index.md       ← 内容目录（每次 ingest 自动更新）
    └── log.md         ← 操作日志（append-only，知识库演进的时间线）

三层职责：

• raw/：原始输入，不可变，是知识的来源
• wiki/：知识的提炼产物，LLM 负责构建和维护所有交叉引用、矛盾标注、综合结论
• Schema.md：规范层，让 LLM 成为训练有素的 Wiki 维护者而非通用聊天机器人，随使用逐步演进

sources/ vs synthesis/ 的区别：

• sources/：对单一原始资料的忠实摘要。一份资料对应一个 sources/ 页面。内容紧贴原文，是"这份资料说了什么"。
• synthesis/：跨多个来源的原创分析。是 LLM（或用户引导下的 LLM）综合多份资料后提炼出的洞察、对比、结论。内容是"综合来看意味着什么"。

类比：sources/ 是原材料，synthesis/ 是成品。sources/ 是笔记，synthesis/ 是论文。

---

意图识别 & 命令路由

用户不需要输入 / 命令。LLM 应根据用户的自然语言自动识别意图，执行对应工作流。同时也支持显式 / 命令作为精确控制方式。

用户可能说的话（自然语言）	等价命令	执行内容	参考文档
"帮我初始化知识库"、"创建一个新的知识库"	/setup	首次初始化：创建目录、生成 Schema.md、配置 qmd	setup.md
"帮我处理这篇文章"、"导入这个文件"、"我放了一篇新论文在 raw/ 里"	/ingest	导入资料，自动更新 10-15 个 wiki 页面	ingest.md
"用户支付的痛点是什么？"、"总结一下竞品分析"、任何针对知识库的提问	/query	搜索知识库，综合答案，可选归档到 synthesis/	query.md
"检查一下知识库"、"有没有矛盾的内容"、"知识库健康状况"	/lint	健康检查：矛盾、孤立页面、过时论断、缺失引用	lint.md
"我剪藏了一篇文章"、"刚 Web Clipper 保存了个网页"、"raw 里有新文件"	/ingest	扫描 raw/ 最新文件，确认后执行 ingest	ingest.md
"知识库有多少页面了"、"看看索引状态"	/status	显示 wiki 统计 + qmd 索引状态	—

路由优先级：如果用户输入了显式 / 命令（如 /ingest raw/articles/xxx.md），直接执行对应工作流，无需确认。如果是自然语言，LLM 应先识别意图，必要时向用户确认后再执行。

会话启动行为

当用户进入 kb-wiki 相关对话时（无论是主动提问还是 skill 被激活），LLM 应在首次回复前执行新资料扫描：

1. 读取 wiki/log.md，提取所有已 ingest 的来源文件路径
2. 扫描 raw/ 目录下所有文件（递归，排除 .DS_Store、.gitignore 等）
3. 对比找出未处理的新文件
4. 如有未处理文件 → 在回复开头主动提醒：

   📎 发现 raw/ 中有 N 篇新资料尚未导入：
     1. raw/articles/文章标题A.md（04-17）
     2. raw/articles/文章标题B.md（04-16）
   要我批量导入吗？还是你想先选择部分导入？
   

5. 如无未处理文件 → 静默跳过，不打扰用户

💡 此扫描仅在每次会话的首次交互时执行一次，不会在每轮对话中重复。

---

首次使用流程

运行 /setup 后，LLM 将自动引导完成知识库初始化（详见 setup.md）：

1. 环境检测：检测 Node.js (≥22)、Python (≥3.10，用于文件格式转换)
2. 编译 qmd 搜索引擎：从内嵌源码自动编译，配置 HuggingFace 镜像（中国大陆）
3. 创建知识库：收集名称和路径 → 创建目录结构 → 生成 Schema.md / index.md / log.md
4. 配置搜索索引：注册 qmd 集合 → 预下载 AI 模型（向量搜索 + LLM 重排序，约 1.3GB）
5. 完成：输出欢迎信息和使用指南

💡 Python 为可选依赖（仅 Office/PDF 转换需要）。AI 模型下载为强制步骤，未完成模型下载的知识库视为未创建完成——/query 的向量语义搜索和 LLM 重排序都依赖此模型。

支持的文件格式

格式	扩展名	处理方式
Markdown / 文本	.md, .txt, .csv	LLM 直接读取
Excel	.xlsx, .xls	自动转换为 Markdown（需 Python）
Word	.docx	自动转换为 Markdown（需 Python）
PowerPoint	.pptx	自动转换为 Markdown（需 Python）
PDF	.pdf	自动转换为 Markdown（需 Python）
图片	.png, .jpg, .gif, .webp	LLM 视觉能力直接查看

---

Lint 提醒规则

每完成 5 次 /ingest 操作后，自动在回复末尾追加提醒：

---
💡 **知识库健康提醒**：你已经导入了 5 份新资料（自上次健康检查以来）。
你可以对我说"对知识库进行健康检查"，我会帮你检测矛盾、孤立页面、缺失引用等问题，
确保知识库的一致性和质量。
---

计数方法：读取 wiki/log.md，统计距上一次 lint 操作之后的 ingest 记录数量。

# 示例：统计距上次 lint 的 ingest 次数
grep "^## \[" wiki/log.md | tail -20 | grep "ingest" | wc -l

---

作为研究输出的知识源（显式触发）

当用户请求研究类创作产出且 prompt 中包含显式知识库引用关键词时，LLM 应进入"知识源工作流"，将 kb-wiki 作为创作的知识基础。

触发条件（关键词 + 创作请求 同时满足）

显式引用关键词（任一命中即可）：

• 「参考知识库」「结合知识库」「用知识库」
• 「参考 wiki」「结合 wiki」「用 wiki 里的」
• 「基于 kb-wiki」「拉一下知识库」「看看我们的知识库」
• 「结合已有资料」「基于现有研究」「用我们已有的（访谈/数据/分析）」

支持的创作类型：

• 问卷设计（题目、选项、逻辑跳转）
• 访谈提纲（提问脚本、记录表、热身问题）
• 用户画像 / Persona
• 竞品分析报告 / 竞品对比表
• 研究报告 / 结论纲要 / 周报

💡 未带关键词时不主动触发：用户单纯说"帮我设计问卷"时，LLM 应正常按通用知识产出，不主动检索 kb-wiki——避免每次创作都打扰用户。只有显式引用知识库时才进入此工作流。

4 步工作流

1. 检索（必须）：

   • 从用户的创作主题中提取关键词，调用 qmd hybrid "<关键词>" 搜索
   • 优先扫描 wiki/entities/、wiki/concepts/、wiki/synthesis/ 三个目录
   • 若命中 0 条：主动告知"知识库里没有相关资料"，询问是否仍按通用知识产出

2. 展示已知（必须）：

   • 以列表形式向用户展示找到的相关页面（页面名 + 一句话摘要）
   • 让用户校对：「我即将基于以上内容生成 X，如有遗漏可补充」
   • 等用户确认或补充后再进入第 3 步

3. 综合产出（必须）：

   • 用知识库内容 + 通用 LLM 知识做创作
   • 每条引用必须标注来源：[来源: wiki/concepts/痛点-加载速度.md]
   • 无来源支持的部分明确标注：（通用经验补充，知识库无对应资料）
   • 这样用户能快速判断哪些内容来自自己的知识库、哪些是 LLM 通用补充

4. 可选归档（询问）：

   • 产出后询问：「这份产出是否归档到 wiki/synthesis/ 让后续可被检索？」
   • 用户同意 → 按 {类型前缀}-{描述}.md 命名，写入 wiki/synthesis/
   • 命名前缀建议：问卷- 访谈- 画像- 对比- 报告-

5 类输出的检索方向 + 输出结构

输出类型	优先检索的目录 / 主题	推荐输出结构
问卷设计	concepts/痛点-* entities/用户-* 已知行为模式	1) 受访者筛选题 2) 主体题（按已知痛点设计闭合选项） 3) 探索题（用开放题填补知识库空白） 4) 满意度/NPS 5) 人口学
访谈提纲	entities/用户-* 画像 + concepts/痛点-* + synthesis/ 研究空白	1) 受访者背景确认 2) 热身问题 3) 核心问题（按已知痛点设计追问链） 4) 探索性问题（针对知识库空白） 5) 结束反馈
用户画像 / Persona	entities/用户-* 全部 + concepts/行为-* concepts/需求-*	1) 基本信息 2) 行为特征（基于已有数据） 3) 痛点 & 需求（标注高频出现） 4) 使用场景 5) 引述（直接使用 sources/ 里的原话）
竞品分析 / 对比	entities/产品-* entities/竞品-* + synthesis/对比-*	1) 对比维度（功能/价格/体验/用户群） 2) 矩阵表 3) 各方优劣势 4) 差异化机会 5) 结论
研究报告 / 周报	synthesis/ 全部 + wiki/log.md 近期 ingest 记录	1) 本期范围（基于 log.md 的时间窗） 2) 关键发现（引用 synthesis/） 3) 矛盾 & 待解问题（来自 lint 报告） 4) 下一步建议

📚 工作流详细执行细节参考 skills/query.md，"知识源工作流"在底层复用 /query 的 7 步搜索流程，只是把答案形式固定为对应的创作产出。

---

重要原则

文件命名：wiki 页面采用 {类型前缀}-{描述}.md 纯中文格式（如 痛点-加载速度.md、问卷-春节满意度.md、用户-流失玩家.md），类型前缀确保分类清晰，便于 Obsidian 图谱识别。

LLM 的职责

1. LLM 负责写，用户负责读：用户永远不需要手动编写任何 Wiki 内容。用户负责寻找资料来源、进行探索性提问，以及引导分析方向。
2. raw/ 目录只读：绝不修改 raw/ 中的任何文件，它们是原始来源的真相
3. wiki/ 目录 LLM 完全掌控：可以自由创建、修改、合并 wiki 页面
4. log.md 只追加：日志记录只能追加，不能删改历史
5. 交叉引用是价值所在：每次 ingest 都要检查并强化已有页面之间的关联
6. 标注矛盾，不隐藏矛盾：发现矛盾时，明确标注，不要静默覆盖

知识质量原则

7. 综合结论要反映所有来源：synthesis/ 页面应综合所有相关资料，不偏向单一来源
8. 探索即积累，查询也是复利：好的 query 分析结论应归档到 synthesis/，让每次探索都像导入新资料一样在知识库中持续积累。对比分析、发现的关联、综合洞察——这些不应消失在聊天记录中，而是成为知识库永久的一部分。
9. index.md 是导航补充：ingest 后必须更新 index.md；查询时以 qmd 搜索为主，index.md 仅用于补全搜索盲区
10. Lint 是知识库的定期体检：不要等到问题积累太多才做健康检查

Schema 演进原则

11. Schema.md 是可演进的：用户可以根据自己的领域、偏好修改 Schema.md，告诉 LLM 不同的工作方式。这是 kb-wiki 适应不同使用场景的关键机制。

---

子文档索引

文档	内容
setup.md	完整安装引导流程
ingest.md	导入资料详细工作流（10 步）
query.md	查询知识库详细工作流
lint.md	健康检查详细流程（7 项检查）
qmd-reference.md	qmd 工具完整命令参考
obsidian-tips.md	Obsidian 集成指南（Web Clipper、图谱视图、Dataview、Marp、Git）

---

关于 llm-wiki 理念

本 skill 完整实现了 llm-wiki 的 11 条核心理念：

1. LLM 渐进式构建和维护持久化 Wiki，添加新资料时更新实体页面、修订主题摘要、标注矛盾、强化综合结论
2. Wiki 是持久的不断复利增长的知识产物，交叉引用已建立，矛盾已标记，综合结论反映所有阅读内容
3. 用户永远不需要自己编写 Wiki 内容，LLM 负责一切编写和维护
4. 用户能一边打开 LLM 智能体，一边打开 Obsidian，LLM 编辑，用户实时浏览
5. 三层架构：Raw sources + Wiki 层 + Schema 层（Schema.md）
6. 三种操作：Ingest、Query、Lint
7. 两个特殊文件：index.md（内容目录）+ log.md（append-only 操作日志）
8. 核心搜索工具：qmd（本地搜索引擎，BM25 + 向量 + LLM 重排序，CLI + MCP 双模式）
9. 技巧：Obsidian Web Clipper、本地图片、图谱视图、Marp、Dataview、git
10. 为什么有效：繁重的维护工作由 LLM 完成，人类负责策划来源和引导分析
11. 目录结构、Schema 约定等取决于用户领域，通过 Schema.md 自定义演进