name: schema-driven-wiki
description: "Obsidian 知识库维护技能。当用户提到以下任何关键词时自动调用此技能：知识库、wiki、写进知识库、更新知识库、记到知识库、查知识库、知识库里有、帮我记一下、帮我整理、Ingest、Query、Lint、Obsidian、vault。支持三大工作流：Ingest（导入新知识）、Query（查询知识）、Lint（健康检查）。所有页面使用 \[wikilink] 双向链接，维护 wiki/index.md 总索引和 wiki/log.md 日志。"
tags: obsidian, wiki, knowledge-base, schema, knowledge-management
platforms: linux, macos, windows
Schema-Driven Wiki（知识库管理）
> 维护 `D:\Obsidian Agent\Agent\wiki\` 下的结构化知识库，由 `Schema.md` 和本技能共同治理。
自动触发规则
**本技能应在以下情况自动激活：**
-
用户提到"知识库""wiki""写进/更新/记到/查到知识库"
-
用户说"帮我记一下""帮我整理一下这个知识点"
-
用户讨论了一个技术概念后说"写到知识库""更新进去"
-
用户问题涉及的内容在知识库中已有相关页面（先查再答）
-
用户提到 Obsidian、vault、Ingest、Query、Lint
**触发后的第一步永远是**：先读 `wiki/index.md` 了解当前知识库结构，再决定是查询、写入还是检查。
Configuration
硬编码路径（Windows 专用，无需配置环境变量）
| 变量 | 值 | 说明 |
|------|-----|------|
| `WIKI_VAULT_PATH` | `D:\Obsidian-llm-wiki` | Vault 根目录 |
| `WIKI_WIKI_DIR` | `wiki` | Wiki 内容目录（相对 vault） |
| `WIKI_RAW_DIR` | `raw` | 原始来源材料目录（只读） |
分类思想（Classification Philosophy）
> **目录结构是暂时的,分类思想才是长久的。** 以下原则指导所有 Ingest / 重构决策。
核心原则
| 原则 | 说明 | 反例 → 正例 |
|------|------|-------------|
| **总 index 单口管理** | 分类入口只在 `wiki/index.md` 唯一维护,**子目录不建 `_index.md`**。避免维护双份、信息不同步。 | ❌ 每建一个 `concepts/xxx/` 就建 `_index.md` → ✅ 只在总 index 的底部分类区集中列出 |
| **项目专属概念归 projects/** | 与特定项目强绑定的知识(如 AI News 的缓存设计、Carbon Audit 的领域模型)放在 `projects/`,**不混入技术栈区**。技术栈区只放跨项目通用的知识。 | ❌ `concepts/ai-news/`、`concepts/carbon-audit/` 顶层目录 → ✅ 移入 `projects/`,跟随各自枢纽页 |
| **技术栈按框架横向组织** | `concepts/` 下按**技术/框架**划分(LangChain / LangGraph / RAG / Multi-Agent / AutoGen / Deep Agents / Python 语法 / Python Web / FastAPI),与所含页面一一对应。 | ❌ 把 Python 语法页散到 LangChain/LangGraph 子目录 → ✅ 统一放 `concepts/python-syntax/` |
| **简洁不冗余** | 单页面分类(如 `sources/` 只剩 1 页)直接删除,内容合并到相关处。空目录(`entities/`、`comparisons/`、`overview/`)及时清理。 | ❌ 为 1 个页面保留整个 `sources/` 目录 → ✅ 删除目录,引用改为纯文本指向实际文件 |
| **先审计后执行** | 移动/删除页面前,先 `grep` 找出所有 wikilink 引用,评估断链风险,再批量替换。操作后**全量死链扫描**验证。 | ❌ 直接 `rm` 页面 → ✅ grep 引用 → 移动/替换 → 验证 0 断链 |
目录结构（当前实际结构）
```
<vault>/
├── Schema.md # Schema & workflow rules
├── raw/ # Raw sources (PDF, web, images). READ-ONLY!
└── wiki/
├── index.md # ⭐ 总索引(唯一入口,子目录不另建 _index.md)
├── log.md # Append-only change log
├── projects/ # 项目枢纽页 + 项目专属概念
│ ├── project_carbon_audit.md (枢纽)
│ ├── project_ai_news.md (枢纽)
│ ├── concept_carbon_domain.md
│ ├── concept_chainlit.md
│ ├── concept_ai_news_architecture.md
│ ├── concept_ai_news_cache_design.md
│ ├── concept_ai_news_duplicate_prevention.md
│ └── concept_ai_news_response_format.md
└── concepts/ # 技术栈知识(跨项目通用)
├── rag/ # RAG 原理 + 工程 + Embedding + 向量库 + 幻觉
├── python-syntax/ # Annotated / yield / with / 装饰器 / AOP / * **
├── python-web/ # HTTP / 路由 / ORM / MySQL / Redis / RESTful / SSE
├── fastapi/ # 入门 / 参数 / 响应 / 异常 / 中间件 / 依赖注入
└── agent/ # Agent 技术栈(框架专属 + 通用编排)
├── concept_prompt_engineering.md
├── agent-dev-paradigm/ # Agent 开发范式(如 Gateway)
├── langchain/ # LCEL / AgentExecutor / vs OpenAI SDK
├── langgraph/ # State / Graph / Checkpointer / LangSmith
├── multi-agent/ # 编排模式 / 看板 / 认知 / Router / HITL
├── autogen/ # 微软框架 GroupChatManager / auto 路由
└── deep-agents/ # LangChain Agent Harness 主从架构
```
> ⚠️ `sources/`、`entities/`、`comparisons/`、`overview/` 已删除(内容合并或无需保留)。
Page Format & Directory Structure
Frontmatter 模板
```yaml
type: "source|entity|concept|comparison|overview|project"
tags: "tag1", "tag2"
summary: "One-line description of this page"
updated: "2026-07-12"
```
文件命名规范
| 类型 | 格式 | 示例 |
|------|------|------|
| Concept | `concept_<slug>.md` | `concept_sse.md` |
| Project | `project_<name>.md` | `project_carbon_audit.md` |
> ⚠️ `source_<name>.md` 类型已弃用------单页面 source 不值得独立目录,溯源引用改为纯文本指向实际代码文件。
Workflows
Workflow 1: Ingest --- 导入新知识
**触发词**："写进知识库""更新到知识库""记下来""帮我整理这个知识点""Ingest"
**流程**：
```
Step 1 --- 确认范围
-
用户指定了具体内容 → 直接进入 Step 2
-
用户只是泛泛说"把这个记下来" → 先确认要记录哪些知识点、放哪个分类
Step 2 --- 确定分类和文件位置（按分类思想决策）
┌─────────────────────────────────────────────────────────┐
│ 决策树: │
│ 内容是否与特定项目强绑定? │
│ ├── 是 → projects/<对应项目>/concept_xxx.md │
│ └── 否(跨项目通用技术栈)→ 按框架/技术选子目录: │
│ Agent 通用(提示词/范式) → concepts/agent/ │
│ LangChain → concepts/agent/langchain/ │
│ LangGraph → concepts/agent/langgraph/ │
│ RAG → concepts/rag/ │
│ Multi-Agent 编排 → concepts/agent/multi-agent/ │
│ AutoGen → concepts/agent/autogen/ │
│ Deep Agents → concepts/agent/deep-agents/ │
│ Python 语法 → concepts/python-syntax/ │
│ Python Web/SSE → concepts/python-web/ │
│ FastAPI → concepts/fastapi/ │
└─────────────────────────────────────────────────────────┘
⚠️ 不要为单个新页面创建新子目录;新子目录只在 ≥2 页同类内容时建立
Step 3 --- 写概念页
-
使用标准 frontmatter
-
结构：一句话理解 → 核心内容（表格/代码/图示） → 相关页面 \[wikilink]
-
与已有页面建立双向链接
Step 4 --- 更新索引和日志
-
wiki/index.md：概览表更新文章数，底部分类区新增行（完整路径 \[projects/concept_xxx] 或 \[concepts/...]）
-
wiki/log.md：**追加到顶部**(第一个 `## [` 之前),维持时间倒序(最新在最顶)
```
**规则**：
-
`raw/` 是只读的 --- 绝不修改源文件
-
只写 `wiki/` 目录下的内容
-
**不建子目录的 `_index.md`** --- 分类入口只在总 index 维护
-
新建子目录时同步更新 index.md 概览表
Workflow 2: Query --- 查询知识
**触发词**："知识库里有没有""帮我查一下""查知识库""Query"
**流程**：
```
Step 1 --- 先查 index.md
读 wiki/index.md，按分类和 summary 定位候选页面。
不要第一步就 grep 全文搜索。
Step 2 --- 读候选页面
读 1-3 个最相关的页面。
Step 3 --- 如果是技术问答
直接引用 \[Page Names] 回答用户问题。
如果发现知识缺口 → 提议 Ingest 新知识。
Step 4 --- 如果需要追踪关系
用 Grep 搜 \[PageName] 找反向链接，最多遍历 2 跳。
```
Workflow 3: Lint --- 健康检查
**触发词**："整理知识库""对知识库做 Lint""检查知识库"
**流程**：
```
Step 1 --- 扫描 wiki/ 检查：
• 页面间矛盾
• 过期陈述
• 孤立页面（零 inbound wikilink）
• 反复出现但没有独立页面的概念
• 缺少交叉引用
• 冗余 _index.md（子目录不应有）
• 单页面分类目录（如 sources/ 只剩 1 页）
• 项目专属概念错放在 concepts/ 顶层
Step 2 --- 生成建议清单，不改任何文件
Step 3 --- 用户确认后逐条执行
Step 4 --- 记录到 wiki/log.md
```
结构重构原则（Refactoring Rules）
> 当需要移动/删除页面或重组目录时遵守。
| 步骤 | 操作 | 工具 |
|------|------|------|
| 1. 审计 | 找出所有引用待删/待移页面的 wikilink | `grep -rn "PageName" wiki/ --include="*.md"` |
| 2. 评估 | 区分"正文引用(需替换为纯文本)"vs"历史 log 记录(保留)" | 人工判断 |
| 3. 执行 | 移动文件 → 替换 wikilink → 删除空目录 | `mv` / Python 脚本 / `rmdir` |
| 4. 验证 | 全量死链扫描,确认 0 断链 | Python 脚本(注意 Obsidian wikilink 不带 `.md`) |
**典型重构场景**:
-
项目专属概念从 `concepts/` 移入 `projects/` → 同步更新 index 概览表 + 底部分类区
-
删除单页面分类目录 → 替换所有 wikilink 为纯文本,删除目录
-
合并重复页面 → 保留主页,重定向旧页(或删除),更新所有引用
Operating Principles
-
**先读 index.md** --- 任何操作前先了解当前知识库结构
-
**raw/ 只读** --- 绝不修改源材料
-
**不确定时先提议** --- 展示计划，等确认后再写
-
**Lint 只出清单** --- 用户逐条确认后才改
-
**log.md 只追加** --- 不重写已有条目(历史 ingest 记录保留,即使引用的页面已删)
5b. **log.md 按时间倒序排列(最新在最顶)** --- 这是用户阅读偏好。每次追加新条目时,**插入到 log.md 顶部**(第一个 `## \` 之前),而非底部追加,这样打开文件第一眼就看到最新改动。若因批量操作导致顺序错乱,可临时做一次整体反转恢复倒序,事后在 log 中标注 \[reordered