---
categories:
  - "[[Tools]]"
  - "[[Documentation]]"
tags:
  - agents
  - ai-assistant
  - development-workflow
  - obsidian-vault
  - knowledge-management
created: 2026-01-23
rating: 7
type: schema
---

# AGENTS.md - Obsidian Vault 智能代理指南

## 概述

本指南为在这个 Obsidian 知识库中工作的智能代理（AI Coding Agents）提供详细的操作规范、代码风格指南和工作流指导。确保所有代理能够高效协作，遵循统一的编码标准，并在 PARA + LLM Wiki 双层架构中正确组织知识。

> **目标：** 让 AI 代理像真正的开发团队成员一样高效工作，遵循最佳实践，保持代码质量和一致性。

**IMPORTANT:** 处理 Obsidian 笔记时，必须优先使用以下官方 Skills（来源：kepano/obsidian-skills）。

> |Skill|用途|何时用|
> |---|---|---|
> |`obsidian-cli`|CLI 命令（搜索、读写、任务、属性、插件开发）|**首选**，几乎所有 vault 操作|
> |`obsidian-markdown`|`.md` 笔记编写（frontmatter、wikilink、callout、embed）|创建/编辑笔记内容时|
> |`obsidian-bases`|`.base` 数据库视图（filters、formulas、views）|创建/编辑 Bases 文件时|
> |`json-canvas`|`.canvas` 图表（nodes、edges、groups）|创建/编辑 Canvas 文件时|
> |`defuddle`|网页→干净 Markdown（去导航/广告/杂讯）|处理 URL 时优先于 WebFetch|
> 
> 使用 `skill` 工具加载对应 skill 后再执行操作。
---

### Obsidian CLI (v1.12.7+)

新版 CLI 使用独立二进制文件，响应更快。常用命令：

```bash
# 版本检查
obsidian version

# 日常操作
obsidian daily:read          # 读取今日日记
obsidian daily:append content="- [ ] 新任务"  # 添加任务
obsidian tasks todo limit=10  # 查看待办

# 文件操作
obsidian files total          # 文件总数
obsidian search query="关键词" limit=5  # 搜索
obsidian tags sort=count counts  # 标签统计
## 1. 仓库架构总览

本项目采用**双层知识管理模式**，结合 PARA 方法论和 LLM Wiki 模式：

```mermaid
graph TD
    subgraph PARA["PARA 层（个人知识）"]
        C[Categories/]
        R[References/]
        N[Notes/]
        D[Daily/]
        Cl[Clippings/]
        T[Tags/]
    end

    subgraph Wiki["LLM Wiki 层（编译知识）"]
        Wiki[wiki/]
        Raw[raw/]
    end

    subgraph Infrastructure["基础设施"]
        Templates[Templates/]
        Attach[Attachments/]
        Schema[AGENTS.md]
    end

    Ingest[新来源] --> Raw
    Raw -->|Ingest 操作| Wiki
    Wiki -->|归档| PARA

    Wiki --> Schema
    Schema --> Wiki
```

### 1.1 文件夹组织

| 文件夹 | 用途 | 文件格式 | 维护者 |
|--------|------|----------|--------|
| **PARA 层** | | | |
| | | | |
 | `Categories/` | PARA 类别索引页面 | `Books.md`, `Movies.md`, `读书笔记.md` (复数) | 人类 |
| `References/` | 实体参考文件 | `Kevin Kelly.md`, `Obsidian.md` | 人类 + LLM |
| `Notes/` | 个人反思和分析 | `Evergreen notes…md` | 人类 |
| `Daily/` | 日常日记 | `2026-01-23.md` | 人类 |
| `Clippings/` | 网页摘录 | `Article Title.md` | 人类 |
| `Tags/` | 标签定义和索引 | `主题-ai.md`, `卡片-金句.md` | 人类 |
| | | | |
| **LLM Wiki 层** | | | |
| | | | |
| `wiki/` | LLM 编译维护的知识库 | `Concept.md`, `Person.md` | LLM |
| `raw/` | 不可变的原始来源 | `source.md` | 人类 |
| | | | |
| **基础设施** | | | |
| | | | |
| `Templates/` | 笔记和演示模板 | `*.md`, `*.css`, `*.base` | 人类 |
| `Attachments/` | 媒体文件 | 图片、PDF、视频 | 人类 |
| `Presentations/` | Marp 演示文稿 | `*.md`, `*.css` | 人类 |
| `tools/` | 开发工具和脚本 | `.py`, `.ps1`, `.json`, `.md` | LLM |
| `markdown_output/` | 外部导入的内容（中转区） | `*.md` | 批量导入 |
| `AGENTS.md` | **Schema：代理操作规范** | 本文件 | 人类 + LLM |

### 1.2 PARA 方法论

PARA 层用于组织**个人项目、领域、资源和归档**：

| 类型 | 说明 | 示例 |
|------|------|----------|
| **Projects** | 有明确目标和时间线的活跃项目 | `项目-卡片笔记实践`, `项目-论文1` |
| **Areas** | 持续关注的领域和责任 | `领域-山西`, `领域-自组网` |
| **Resources** | 未来参考的主题和兴趣 | Obsidian 笔记、AI 工具、参考材料 |
| **Archive** | 已完成的项目和不活跃内容 | 过去项目、归档资料 |

**注意事项**：
- PARA 层主要由人类维护，LLM 辅助
- LLM Wiki 的编译结果可以归档到 PARA 层（如 References/）

### 1.3 LLM Wiki 模式

LLM Wiki 层是**由 LLM 增量编译和维护的结构化知识库**：

| 层级 | 位置 | 职责 | 维护者 |
|------|------|------|--------|
| **Raw Sources** | `raw/` | 不可变的原始文档、文章、论文、数据文件 | 人类 |
| **Wiki** | `wiki/` | 摘要、实体页、概念页、比较、综合 | **LLM** |
| **Schema** | `AGENTS.md` | Wiki 结构约定、工作流规范 | 人类 + LLM |

**三种核心操作**：
1. **Ingest（摄入）**：将新来源编译到 wiki，更新 index 和 log
2. **Query（查询）**：搜索 wiki 页面并综合回答
3. **Lint（健康检查）**：每周常规体检（矛盾/过时/孤岛/断链）+ 每月深度体检（随机抽样逐条比对原始文档）

**索引与日志**：
- `wiki/index.md` - 内容目录，按类别组织（每次 ingest 更新）
- `wiki/log.md` - 时间线日志（grep 可解析的格式）

### 1.4 Frontmatter 规范

#### PARA 层（Categories, References, Clippings, Notes）

所有 PARA 内容笔记必须包含 YAML frontmatter：

```yaml
---
categories:
  - "[[Books]]"
  - "[[People]]"
tags:
  - books
  - people
  - reference
created: 2026-01-23
rating: 5
author: []
topics: []
para: []
---

<!-- Added: 2026-04-07 -->
## Obsidian Frontmatter 布尔值规范

在 Obsidian 笔记的 YAML frontmatter 中，布尔值 `true`/`false` 会被 Obsidian 识别为 checkbox 类型属性。为避免此问题，所有布尔值属性必须用引号包裹为字符串：

- ✅ `marp: "true"`
- ✅ `paginate: "true"`
- ❌ `marp: true`（Obsidian 会将其显示为 checkbox）
- ❌ `paginate: true`（同上）

此规范适用于所有通过 LLM 生成或修改的 Obsidian 笔记。HTML 注释中的指令（如 `<!-- paginate: true -->`）不受影响，保持原样。

## 内容开始
```

**Frontmatter 规则**：
- ✅ **Categories**：使用 wikilink 格式 `[[Category]]`，frontmatter 中用复数 `categories: [[Books]]`
- ✅ **Tags**：短横线连接、小写、无空格（例如：`#tag` 或 `ai/coding`）
- ✅ **Dates**：`YYYY-MM-DD` 格式
- ✅ **多值字段**：使用列表格式，即使单值也要加 `[]`（例如：`author: ["Kevin Kelly"]`）
- ✅ **空字段**：留空不写引号或 null（例如：`via: ""`）
- ✅ **分隔符**：YAML 后必须有空行 `---`，正文前也要有空行

#### LLM Wiki 层

Wiki 页面必须包含以下 frontmatter：

```yaml
---
categories:
  - "[[LLM Wiki]]"  # ✅ 必须包含
tags:
  - wiki            # ✅ 必须包含
  - {tag1}
  - {tag2}
created: {YYYY-MM-DD}
source: "[[{source-file}]]"  # ✅ 必须指向 raw 来源
type: concept | entity | tool | reference | place | institution | method | knowledge-card | synthesis | index | log  # ✅ 必须指定类型
aliases:  # 可选
  - {alias1}
  - {alias2}
marp: "true"  # Marp 演示文稿专用，必须用引号
confidence: 3  # 可选，1-5：1=推测 2=单源 3=已验证 4=多源一致 5=无可争议
status: active  # 可选：active | superseded | deprecated | tentative | needs-review
superseded_by: "[[新页面]]"  # 仅 status=superseded 时必填
last_reviewed: {YYYY-MM-DD}  # 可选，最后审查日期
review_interval_days: 180  # 可选，审查周期（技术类建议 90 天）
relations:  # 可选，类型化关系列表
  # - type: depends_on | conflicts_with | supersedes | caused_by | supports | extends | part_of | example_of
  #   target: "[[页面]]"
  #   description: "关系说明"
  #   confidence: 3
---
```

**字段说明**：

| 字段 | 必填 | PARA 层 | Wiki 层 | 说明 |
|------|------|---------|---------|------|
| `categories` | ✅ | `[[Category]]` | `[[LLM Wiki]]` | 类别 |
| `tags` | ✅ | `{tag}` | `wiki`, `{tag}` | 标签 |
| `created` | ✅ | `YYYY-MM-DD` | `YYYY-MM-DD` | 创建日期 |
| `source` | ❌ | 可选 | ✅ 必填 | Wiki 层必须指向 raw 来源 |
| `type` | ❌ | 可选 | ✅ 必填 | Wiki 层必须指定页面类型（合法值见下方） |
| `aliases` | ❌ | 可选 | 可选 | 替代名称列表 |
| `marp` | ❌ | 可选 | 可选 | 演示文稿标识，必须用引号 |
| `confidence` | ❌ | 可选 | 可选 | 置信度 1-5，默认 3 |
| `status` | ❌ | 可选 | 可选 | 生命周期状态：active/superseded/deprecated/tentative/needs-review |
| `superseded_by` | ❌ | 可选 | 可选 | status=superseded 时指明替代页面 |
| `last_reviewed` | ❌ | 可选 | 可选 | 最后审查日期，用于时效检测 |
| `review_interval_days` | ❌ | 可选 | 可选 | 审查周期天数，默认 180 |
| `relations` | ❌ | 可选 | 可选 | 类型化关系列表（详见 Phase 1） |

---

## 2. Wiki 工作流

### 2.1 Ingest（摄入）操作

当收到新来源时，按以下流程处理：

```mermaid
graph LR
    A[收到新来源] --> B[存入 raw/]
    B --> C[读取并分析关键要点]
    C --> D[创建/更新 Wiki 页面]
    D --> E[更新 index.md]
    E --> F[追加 log.md 条目]
    F --> G[完成]
```

**详细步骤**：

1. **读取来源**
   ```bash
   # 来源存入 raw/ 目录
   raw/source-name.md
   ```

2. **创建 Wiki 页面**
   - 根据内容类型创建相应页面：
     - **概念页**：`wiki/概念名称.md` - 理论、方法论、模式
     - **实体页**：`wiki/人物姓名.md` - 人物、公司、组织
     - **工具页**：`wiki/工具名称.md` - 软件、框架、工具
     - **参考页**：`wiki/主题-子主题.md` - 详细文档、教程

   **⛓️ 来源溯源规则**（防漂移）：
   - 所有**数字、百分比、具体结论**必须原文引用，并在其后标注来源行号
   - 格式：`{原文数据}[raw:{来源文件名}:{行号}]`
   - 示例：`学习效率提升 40%[raw:ALEKS研究:45]`，而不是用 AI 的话重述数字
   - 行号以原始 raw 文件为准，标注精确的行区间（如 `:42-45` 或 `:87`）
   - 此规则适用于所有 Wiki 页面类型（概念、实体、工具、参考）

3. **更新 index.md**
   ```yaml
   ## 概览

   | 指标 | 值 |
   |------|-----|
   | 来源数 | {更新数字} |
   | Wiki 页面数 | {更新数字} |

   ```

4. **追加 log.md**
   ```markdown
   ## [YYYY-MM-DD] ingest | {来源标题}

   **来源**: {来源链接或文件路径}

   **操作**:
   - 操作 1
   - 操作 2

   **涉及页面**: N 个新页面，M 个更新页面

   **关键要点**:
   - 要点 1
   - 要点 2
   ```

**示例**：参考 `wiki/log.md` 中的历史记录

### 2.2 Query（查询）操作

当用户对 Wiki 提问时：

1. **搜索相关页面** — 优先使用 `qmd query`（MCP `mcp__qmd__query`），使用自然语言描述问题，获取语义最相关页面；
   - 如果 qmd 返回空或不准确，fallback 到 `grep` 或 `mcp__qmd__search`（BM25 精确匹配）
   - 复杂问题：`qmd query` 获取 top 5-8 结果→读取内容→综合回答
2. **综合多页面的信息**
3. 如果发现新的见解，**将回答归档为新 Wiki 页面**
4. 更新 index 和 log

> **原则**：好的回答应该成为 Wiki 的一部分，让探索像摄入一样持续积累。

### 2.3 Lint（健康检查）

Wiki 健康检查分为**常规体检**（每周）和**深度体检**（每月），两种体检完成后都必须追加 `log.md` 条目。

#### 常规体检（每周）

触发词：`体检`

检查五项内容：

1. **矛盾** — 搜索同一事实在不同页面上的冲突声明
2. **过时** — 检查 raw/ 中来源是否更新，对应的 wiki 页面是否过时
3. **孤岛** — 查找无任何入站链接的 wiki 页面
4. **断链** — 查找引用了不存在的 `[[页面]]` 的 wiki 页面
5. **index 准确性** — 验证 `wiki/index.md` 中的指标（页面数、来源数）与实际一致

```bash
# 孤岛检测：找出 wikilink 从未被其他页面引用的页面
grep -roh "\[\[[^]]*\]\]" wiki/ | sort -u | sed 's/\[\[\(.*\)\]\]/\1/' > /tmp/all_links.txt
ls wiki/*.md | xargs -n1 basename | sed 's/\.md$//' | grep -v -F -f /tmp/all_links.txt

# 断链检测：查找指向不存在文件的 [[wikilink]]
# 对每个 [[页面]] 检查 wiki/页面.md 是否存在

# index 准确率
Get-ChildItem wiki/*.md | Measure-Object
```

#### 深度体检（每月）

触发词：`深度体检`

1. 随机抽取 5 个 wiki 页面（优先选择摘要型页面）
2. 对每个页面，逐条对比其声明与原始 raw 来源
3. 记录每项偏差：
   - **数据偏差**：数字、百分比不一致
   - **语义偏差**：结论被 AI 过度概括或扭曲
   - **遗漏偏差**：原始来源中的重要内容被遗漏
4. 自动修复偏差（更新 wiki 页面）
5. 报告修复摘要到 `log.md`

```bash
# 随机抽样（PowerShell）
Get-ChildItem wiki/*.md | Where-Object { $_.Name -notmatch '^(index|log)' } | Get-Random -Count 5 | Select-Object Name
```

#### 常见问题及处理

| 问题 | 处理方式 |
|------|----------|
| 质量标记误报 | 多数为文章内容的正常用词（如"矛盾性"），非真正冲突 |
| 错误文件 | 删除 `*_err.md` 文件 |
| type 字段格式不一致 | 单字符串 vs 列表格式均可工作，建议保持一致 |
| 缺失类别索引页 | 可创建 People.md、Places.md 等分类页面 |

#### 经验教训

- index.md 指标容易过期，需定期更新
- 日志文件（log.md）是追溯操作历史的重要来源
- 建议每次 lint 后更新 log.md 条目

### 2.4 Wiki 页面模板

参考 `Templates/Wiki Page Template.md`：

**概念页面**：
```markdown
---
categories:
  - "[[LLM Wiki]]"
tags:
  - wiki
  - {tag1}
  - {tag2}
created: {YYYY-MM-DD}
source: "[[{source-file}]]"
type: concept
aliases:
  - {alias1}
confidence: 3
status: active
last_reviewed: {YYYY-MM-DD}
review_interval_days: 180
relations:
  # - type: depends_on | supersedes | part_of | example_of
  #   target: "[[页面]]"
---

# {概念名称}

> **一句话定义**：{核心定义}

## 定义

{概念的详细定义和解释}

## 关键要点

- 要点 1
- 要点 2
- 要点 3

## 与其他概念的关系

- [[相关概念1]] — {关系说明}
- [[相关概念2]] — {关系说明}

## 来源

> **溯源规则**：所有数字/百分比/具体结论必须标注 `[raw:{文件名}:{行号}]` 格式。

- [[source]] — 来源描述
```
```markdown
---
categories:
  - "[[LLM Wiki]]"
tags:
  - wiki
  - {tag1}
  - {tag2}
created: {YYYY-MM-DD}
source: "[[{source-file}]]"
type: concept
aliases:
  - {alias1}
---

# {概念名称}

> **一句话定义**：{核心定义}

## 定义

{概念的详细定义和解释}

## 关键要点

- 要点 1
- 要点 2
- 要点 3

## 与其他概念的关系

- [[相关概念1]] — {关系说明}
- [[相关概念2]] — {关系说明}

## 来源

> **溯源规则**：所有数字/百分比/具体结论必须标注 `[raw:{文件名}:{行号}]` 格式。

- [[source]] — 来源描述
```

**实体页面**：
```markdown
---
categories:
  - "[[LLM Wiki]]"
  - "[[People]]"
tags:
  - wiki
  - people
  - {domain}
created: {YYYY-MM-DD}
source: "[[{source-file}]]"
type: entity
aliases:
  - {alias}
confidence: 3
status: active
last_reviewed: {YYYY-MM-DD}
relations:
  # - type: supports | extends | example_of
  #   target: "[[相关概念]]"
---

# {人物姓名}

{一句话简介}

## 身份

| 属性 | 值 |
|------|-----|
| 领域 | {领域} |
| 知名身份 | {身份} |

## 主要贡献

- 贡献 1
- 贡献 2

## 与本 Wiki 相关

{此人与 wiki 内容的关联}

## 来源

> **溯源规则**：所有数字/百分比/具体结论必须标注 `[raw:{文件名}:{行号}]` 格式。

- [[source]] — 来源描述
```

**工具页面**：
```markdown
---
categories:
  - "[[LLM Wiki]]"
tags:
  - wiki
  - tool
  - {category}
created: {YYYY-MM-DD}
source: "[[{source-file}]]"
type: tool
aliases:
  - {alias}
confidence: 3
status: active
last_reviewed: {YYYY-MM-DD}
relations:
  # - type: example_of | extends
  #   target: "[[相关概念]]"
---

# {工具名称}

> **一句话描述**

## 基本信息

| 属性 | 值 |
|------|-----|
| 仓库 | {URL} |
| 类型 | {类型} |

## 在 LLM Wiki 中的角色

{工具在 wiki 工作流中的作用}

## 来源

> **溯源规则**：所有数字/百分比/具体结论必须标注 `[raw:{文件名}:{行号}]` 格式。

- [[source]] — 来源描述
```

---

### 2.5 结晶机制（Crystallization）

每次 LLM 对话结束时，Agent 应检查本次对话是否产生了可复用的知识：

| 信号 | 动作 |
|------|------|
| 用户询问了全新的问题 | 若回答包含新知识，创建 wiki 页面 |
| 引用了外部来源 | 存入 `raw/`，创建对应 wiki 页面 |
| 发现了错误或过时信息 | 更新对应页面，设置 `status: superseded` |
| 创建了分析或比较 | 评估是否适合作为合成(synthesis)页面 |

**产出要求**：
- 新页面必须满足 `validate-frontmatter.py` 的所有校验
- 有 `source` 指向 raw 或权威来源
- 有 `type` 和 `confidence`
- 追加 `wiki/log.md` 条目

### 2.6 知识提级（Consolidation Tiers）

知识从原始观察到程序性知识的分层转化体系：

```
raw/          (Working → 不可变原始来源)
├── wiki/working/   (临时笔记、对话草稿、未整理洞察)
├── wiki/semantic/  (语义层 ← 当前 wiki/ 主目录)
├── wiki/procedural/ (程序性知识：操作指南、最佳实践、配方)
└── wiki/archive/    (归档：已过时/被替代的页面)
```

**提级条件**（`promote-knowledge.py`）：

| 来源 → 目标 | 条件 | 自动程度 |
|------------|------|---------|
| working/ → semantic/ | 完整体 frontmatter + 正文 > 100 字 + 创建 > 7 天 | 脚本辅助 |
| active → archive/ | `status=deprecated` 或 `superseded` | Lint 时自动提示 |

## 3. Marp 演示文稿工作流

### 3.1 Marp 基础知识

Marp 是用 Markdown 编写演示文稿的生态系统。本知识库使用 Marp 创建幻灯片。

**核心概念**：
- **Marpit** - 框架层，定义指令解析和转换规则
- **Marp Core** - 引擎层，实现 Marpit 接口
- **Marp CLI** - 命令行工具，导出 HTML/PDF/PPTX
- **Obsidian Marp 插件** - 在 Obsidian 中预览和导出

### 3.2 Frontmatter 指令

Marp 演示文稿必须包含 Marp frontmatter：

```yaml
---
marp: "true"  # ✅ 必须用引号包裹
theme: gaia  # 主题：default, uncover, gaia
paginate: "true"  # ✅ 必须用引号包裹
style: |
  /* 自定义样式 */
  section {
    background: linear-gradient(to bottom, #1a1a2e, #16213e);
    color: white;
  }
---

<!-- _class: cover -->
# 标题页

<!-- _class: dark -->
# 深色页
```

**全局指令**（frontmatter 中）：
- `marp: "true"` - 启用 Marp
- `theme: default/uncover/gaia` - 选择主题
- `paginate: "true"` - 显示页码
- `style: |` - 自定义 CSS

**局部指令**（注释中）：
- `<!-- _class: cover -->` - 封面页样式
- `<!-- _class: dark -->` - 深色背景
- `<!-- _class: cols-2 -->` - 两栏布局
- `<!-- _paginate: false -->` - 当前页不显示页码

**自定义主题**：
- 主题文件存放在 `Templates/MarpTheme/`
- 格式：`theme-name.css`
- 使用后需重启 Obsidian
- 在 frontmatter 中引用：`theme: theme-name`

### 3.3 自定义主题示例

**University Blue 主题** (`Templates/MarpTheme/university-blue.css`)：

```css
/* @theme university-blue */

@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@400;700&display=swap');

:root {
  --primary-color: #1a365d;  /* 学术蓝 */
  --secondary-color: #2b6cb0;
  --accent-color: #4299e1;
  --text-color: #1a202c;
  --bg-color: #ffffff;
}

section {
  background: var(--bg-color);
  color: var(--text-color);
  font-family: 'Noto Sans SC', sans-serif;
}

h1, h2, h3 {
  color: var(--primary-color);
}

/* 封面页 */
section.cover {
  background: linear-gradient(135deg, var(--primary-color), var(--secondary-color));
  color: white;
}

/* 两栏布局 */
.cols-2 {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: 2rem;
}
```

**使用方式**：
```yaml
---
marp: "true"
theme: university-blue
paginate: "true"
---
```

### 3.4 Marp 页面类型

| 类型 | 指令 | 用途 | 示例 |
|------|------|------|------|
| **封面页** | `<!-- _class: cover -->` | 标题、作者、日期 | 论文首页、报告封面 |
| **过渡页** | `<!-- _class: trans -->` | 章节分隔 | 章节标题页 |
| **深色页** | `<!-- _class: dark -->` | 强调、对比 | 数据可视化、代码块 |
| **两栏页** | `<!-- _class: cols-2 -->` | 左右对比 | 对比分析、并列说明 |
| **结束页** | `<!-- _class: ending -->` | 致谢、Q&A | 演示结尾 |

**完整示例**：参考 `wiki/示例-学校定制Marp演示.md`

### 3.5 导出方式

**Obsidian 插件**：
1. 打开 Marp 文件
2. 点击预览按钮（👁️）
3. 点击导出按钮（📥）
4. 选择格式：HTML / PDF / PPTX

**CLI 命令**：
```bash
# 导出 PDF
marp --pdf presentation.md -o output.pdf

# 导出 HTML
marp --html presentation.md -o output.html

# 导出 PPTX
marp --pptx presentation.md -o output.pptx
```

### 3.6 Marp 相关 Wiki 页面

| 页面 | 内容 | 来源 |
|------|------|------|
| `[[Marp]]` | 概念总览 | marp-guide |
| `[[Marp 指令语法]]` | 指令系统完整参考 | marp-guide |
| `[[Marp 主题与样式]]` | 内置主题、CSS 自定义 | marp-guide |
| `[[Marp 导出]]` | HTML/PDF/PPTX 导出方式 | marp-guide |
| `[[Obsidian Marp 插件]]` | Obsidian 集成 | marp-guide |
| `[[Marp 主题推荐]]` | GitHub 社区主题合集 | marp-themes |
| `[[示例-学校定制Marp演示]]` | 学校定制蓝主题演示 | marp-themes |

---

## 4. Obsidian CLI 与工具链

### 4.1 Obsidian CLI (v1.12.7+)

新版 CLI 使用独立二进制文件，响应更快。常用命令：

```bash
# 版本检查
obsidian version

# 日常操作
obsidian daily:read          # 读取今日日记
obsidian daily:append content="- [ ] 新任务"  # 添加任务
obsidian tasks todo limit=10  # 查看待办

# 文件操作
obsidian files total          # 文件总数
obsidian search query="关键词" limit=5  # 搜索
obsidian tags sort=count counts  # 标签统计
```

### 4.2 EPUB 转换工具

位于 `tools/epub_converter/` 目录，用于将 EPUB 电子书转换为 Obsidian Markdown 笔记。

**命令行**：
```bash
python -m tools.epub_converter <input.epub> <output_dir> [--author "作者"] [--tags "标签1,标签2"]
```

**功能特性**：
- 从原始 EPUB 提取正确的 UTF-8 元数据（标题、作者、出版社、日期）
- Calibre 规范化处理复杂 EPUB 结构（OEBPS/锚点格式）
- TOC 章节结构解析
- 按章节拆分，生成 Obsidian 笔记
- 标准 YAML frontmatter

**输出结构**：
转换后的文件存放在 `raw/书名_作者/` 目录下：
- `书名_作者/` - 按"书名+作者"命名的目录
  - `original.epub` - 原始 EPUB 文件
  - `chapter1.md` - 章节笔记
  - `chapter2.md` - 章节笔记
  - …

**依赖**：
- Python 3.10+
- Calibre (ebook-convert) - 通过 scoop 安装
- html2text - 可选，增强 HTML 到 Markdown 的转换质量

---

### 4.3 home-wiki 跨库同步

`tools/scripts/sync_home_wiki.py` 定期将 `D:\TC_UP\home-wiki` 的知识页面同步到本仓库 `wiki/`，是跨库知识流通的唯一入口。

**同步范围**：`concepts/` + `entities/` + `syntheses/`（排除 index.md）。`Daily/`、`MyNotes/`、`reports/` 不在知识同步范围。

**转换规则**（home-wiki frontmatter → kepano Wiki 规范）：
- `categories`：加 `[[LLM Wiki]]`；`entity/person` 额外加 `[[People]]`
- `tags`：前缀 `wiki` + 类型标签（`people`/`concept`）；`concept` 的 `subtype` 转 `concept/{subtype}`；追加原 tags
- `title`/`name` → `aliases`；`sources[0]`（文件路径取 stem）→ `source` wikilink
- 正文保留，移除 home-wiki 特有的 openclaw 自动段落（`## Related`、注释标记行）

**用法**：
```bash
$env:PYTHONIOENCODING="utf-8"
python tools/scripts/sync_home_wiki.py --dry-run        # 仅诊断差异
python tools/scripts/sync_home_wiki.py --index --log    # 一站式：同步 + 更新 index + 记日志（推荐）
python tools/scripts/sync_home_wiki.py --lint           # 体检（孤儿/断链/source空值/未入index）
```

**index 自动维护**（`--index`）：用标记块 `<!-- BEGIN/END home-wiki-sync -->` 自动维护 `wiki/index.md` 的「概念页」「实体页」两个表。简介缓存 `tools/data/home-wiki-summaries.json` 是简介权威来源——首次从 index 现有表格种子化（保留人工简介），新页面自动提取（`description` → 顶部引用块 → 概述首句）。「综合报告」表因混合教育AI研究等其他来源，保持手动维护。

**健壮性**：幂等（按完整内容对比，frontmatter+正文）；home-wiki frontmatter 常含 `related: [[wikilink]]`，`[[` 会触发 YAML flow sequence 解析异常，脚本先 `yaml.safe_load`，失败则正则逐字段回退。

**相关文件**：
- 脚本：`tools/scripts/sync_home_wiki.py`
- 简介缓存：`tools/data/home-wiki-summaries.json`
- 文件名映射：脚本内 `NAME_MAP`（home-wiki 完整标题 → kepano 简短名）

---

## 5. WorkBuddy 自动化工作流

### 5.1 WorkBuddy 集成

**WorkBuddy** 是用于 `/raw/教育AI研究/` 项目自动化工具，通过 TOML 配置文件定期执行任务。

**配置位置**：
- 任务定义：`raw/教育AI研究/.workbuddy/automations/*.toml`
- 工作日志：`raw/教育AI研究/.workbuddy/memory/*.md`

**每周研究计划**（`edu-ai-higher-ed-weekly-plan.toml`）：
- 工作目录：`D:\Applications\app\kepano-obsidian-main\raw\教育AI研究`
- 记忆文件：`raw/教育AI研究/.workbuddy/memory/MEMORY.md`
- 调度：每周一 09:00
- 输出：每周研究计划保存到 `每周报告/YYYY-WXX-第N周研究计划.md`

**典型工作流**：
1. WorkBuddy 每周一生成研究计划（基于 MEMORY.md 中的周次和任务状态）
2. 计划包含 P0/P1/P2/P3 优先级任务
3. 每项任务指定产出路径和质量目标（≥85分）
4. 完成后更新 MEMORY.md 记录完成状态和成本

### 5.2 教育AI研究工作流

**研究周期**：W13-W21（2026年3月31日 - 5月18日）

**核心工作流步骤**：

| 步骤 | 说明 | 质量要求 |
|------|------|----------|
| **计划制定** | 基于 MEMORY.md 制定本周研究计划 | 明确优先级、可执行 |
| **机构研究** | 官网信息采集 → 档案建立 → 质量评分 | A级≥85分 |
| **技术深度分析** | 学术文献 + 实践案例 + 对比分析 | ≥80分/篇 |
| **真实性核查** | 五步核查法，每条信息须有来源 | 官方渠道占比≥70% |
| **周报生成** | 结构化总结，标注完成率和成本 | 完成率、成本统计 |

**自动化工具**：

文献管理：

```powershell
# 设置编码
$env:PYTHONIOENCODING="utf-8"

# 统计摘要
python 文献库\tools\文献库管理器.py --stats --db "文献库\文献索引数据库.json"

# 搜索文献
python 文献库\tools\文献库管理器.py --search ITS --db "文献库\文献索引数据库.json"

# 验证 DOI
python 文献库\tools\文献库管理器.py --verify --db "文献库\文献索引数据库.json"
```

质量保障工具：

```bash
python raw/教育AI研究/tools/check_note_properties.py
python raw/教育AI研究/tools/verify_auto_sync.py
python raw/教育AI研究/tools/fix_orphan_files.py
```

---

## 5.5 工具目录规范

**重要规则**：所有仓库根目录下的工具文件必须统一存放至 `/tools` 目录下。

### 目录结构

```
tools/
├── scripts/           # 脚本文件（.bat, .ps1, .sh）
│   ├── export-slides.bat
│   ├── fix-git-remote.ps1
│   └── stats.ps1
├── configs/           # 配置文件（.json, .yaml, .toml）
│   └── douban-book-clipper.json
├── data/              # 数据文件（词典、缓存等）
│   ├── cedict_ts.u8
│   └── douban_page.html
└── epub_converter/    # EPUB 转换工具
    ├── __init__.py
    ├── README.md
    └── ...
```

### 工具分类说明

| 子目录 | 文件类型 | 示例 |
|--------|----------|------|
| `scripts/` | 执行脚本 | `.bat`, `.ps1`, `.sh` |
| `configs/` | 配置文件 | `.json`, `.yaml`, `.toml` |
| `data/` | 数据文件 | 词典、缓存、临时文件 |
| `epub_converter/` | Python 工具包 | EPUB 转换相关 |

### 使用规范

1. **新增工具**：按照工具类型存放到对应的子目录
2. **引用路径**：使用相对路径 `tools/scripts/xxx.py` 或绝对路径 `/tools/…`
3. **文档更新**：新增工具后更新本规范和相关文档

### 命名约定

- 文件名使用英文或中文，保持描述性
- 脚本文件使用清晰的前缀（如 `export-`, `fix-`, `stats-`）
- 配置文件使用功能名称（如 `douban-book-clipper.json`）

---

## 6. 代码风格与工具

> ⚠️ 本仓库是 Obsidian 知识库，非软件项目。TypeScript/JavaScript 规范不适用。

### 6.1 脚本规范（Python/PowerShell）

- 所有脚本必须有用途注释
- 关键数据必须有来源追溯
- 避免硬编码路径，使用相对路径
- Python 脚本需设置编码：`$env:PYTHONIOENCODING="utf-8"`

### 6.2 Lint 工具脚本

```powershell
# 位置: tools/scripts/

# 孤儿页面检测
wiki-lint-orphan.ps1

# 断链检测（优化版，排除 Obsidian 特殊引用）
wiki-lint-broken-v2.ps1

# 空 type 字段修复
wiki-lint-fix-type.ps1
```

### 6.3 qmd 本地搜索引擎

qmd (v2.1.0) 是已配置的本地 Markdown 搜索引擎，索引 wiki/ 和 raw/ 文件。

**运行方式**（不能直接运行 `qmd` 命令，脚本引用 /bin/sh）：
```bash
node "C:\Users\hhhh2024\AppData\Roaming\npm\node_modules\@tobilu\qmd\dist\cli\qmd.js" <command>
```

或使用包装脚本：`tools\scripts\qmd.cmd <command>`

**搜索命令**：
- `qmd search "关键词" -c wiki` — BM25 全文搜索
- `qmd vsearch "语义查询" -c wiki` — 向量语义搜索
- `qmd query "综合查询" -c wiki` — 混合搜索（BM25+向量+LLM重排序）

**MCP 集成**（已配置 MCP server，在 opencode.json 中）：
- `mcp__qmd__query` — 混合搜索
- `mcp__qmd__get` — 按路径/docid 获取文档
- `mcp__qmd__multi_get` — 批量获取
- `mcp__qmd__status` — 索引健康状态

**模型**：嵌入(embeddinggemma-300M-Q8_0/768维/Vulkan) + 重排序(Qwen3-Reranker-0.6B-Q8_0) + 查询扩展(qmd-query-expansion-1.7B)

**维护**：`qmd status` | `qmd update` | `qmd embed` | `qmd embed -f`

**Skill**: 已安装到 `.agents/skills/qmd/SKILL.md`

### 6.4 提交信息规范（Conventional Commits）

所有提交（手动与 obsidian-git 自动备份）统一采用 Conventional Commits + vault scope：

| Scope | 用途 | 示例 |
|-------|------|------|
| `feat(wiki)` | 新建/更新 Wiki 页面 | `feat(wiki): 添加 [[人物]] 实体页` |
| `docs(raw)` | 摄入新来源到 raw/ | `docs(raw): 摄入 ALEKS 研究` |
| `fix(tools)` | 修复脚本/工具 | `fix(tools): validate-frontmatter GBK 编码` |
| `chore(vault)` | obsidian-git 自动备份 | `chore(vault): backup 2026-07-01 10:00:00` |
| `refactor(schema)` | AGENTS.md/规范调整 | `refactor(schema): Phase 1 关系字段` |
| `style(vault)` | frontmatter/格式修正 | `style(vault): 统一 frontmatter 布尔值` |

**规则**：
- obsidian-git 自动备份提交信息已配置为 `chore(vault): backup {{date}}`
- 手动提交须语义化，避免 "update" / "修改" 等无信息标题
- 提交者身份：`hehaiguang1123 <hehaiguang1123@gmail.com>`（历史身份经 `.mailmap` 合并）

**Git 配置约定**：
- `.gitattributes`：文本统一 LF，Windows 脚本（`.ps1/.cmd/.bat`）CRLF，媒体文件标记 binary
- `.gitignore`：根目录白名单策略，仅跟踪 `raw/ wiki/ Templates/ tools/ .githooks/` + `.obsidian/` 配置
- `.githooks/`（`core.hooksPath=.githooks`）：
  - `pre-commit`：frontmatter 校验 + 10MB 大文件防护 + token 扫描
  - `post-merge`：qmd 索引刷新 + `.obsidian` 变更重载提示
- 远程凭证不内嵌 token，使用 Windows Credential Manager
- **多端同步工具冲突警示**：obsidian-git 为本库唯一同步机制；`obsidian-livesync` 插件虽存在于 `plugins/` 但**未启用**，若多端启用会与 git 双写产生不可恢复冲突，禁止同时启用

---

## 7. Wiki 维护工作流

### 7.1 每周维护周期

**WorkBuddy 自动化**：
- 每周一 09:00 自动生成研究计划（基于 MEMORY.md）
- 计划包含 P0/P1/P2/P3 优先级任务
- 每项任务指定产出路径和质量目标（≥85分）

**手动触发维护**：
```bash
# 1. 运行 WorkBuddy 自动化
# 在周一 09:00 后，WorkBuddy 会自动执行

# 2. 手动刷新 index.md（如有新增页面）
# 更新 wiki/index.md 中的指标：来源数、Wiki 页面数
# 当前实际统计：247 个 Wiki 页面，39 个来源

# 3. 执行质量检查
# python raw/教育AI研究/tools/check_note_properties.py
# python raw/教育AI研究/tools/verify_auto_sync.py
# python raw/教育AI研究/tools/fix_orphan_files.py

# 4. 验证文献库
# python raw/教育AI研究/tools/文献库管理器.py --verify --db "文献库/文献索引数据库.json"

# 5. 生成周报（如需手动触发）
# 参考 raw/教育AI研究/templates/04-周报生成.md 模板
```

### 7.2 优先级维护原则

**Wiki 维护优先级**：
1. **P0 - 每周更新**：WorkBuddy 自动生成研究计划，更新 MEMORY.md
2. **P1 - 质量保障**：定期运行 lint 检查，修复孤立页面
3. **P2 - 结构优化**：检查并修复 frontmatter 一致性，更新 index.md
4. **P3 - 知识库扩展**：根据新研究内容创建新的 Wiki 页面

**Education AI Research 特有工作流**：
- **真实性核查**：每条信息必须追溯来源，五步核查法
- **质量评分**：A级≥85分，官方渠道占比≥70%
- **技术时效**：技术数据≤6个月，市场数据≤12个月
- **自动归档**：每周报告自动生成并存档到 `每周报告/` 目录

### 7.3 Frontmatter 一致性检查

**PARA 层 frontmatter**：
```yaml
---
categories:
  - "[[Category]]"  # 单数形式，wikilink 格式
tags:
  - tag1
  - tag2
created: YYYY-MM-DD
rating: 5
author: []
---
```

**Wiki 层 frontmatter**（必须包含）：
```yaml
---
categories:
  - "[[LLM Wiki]]"  # 必填
tags:
  - wiki              # 必填
  - concept/entity/tool
created: YYYY-MM-DD
source: "[[{source-file}]]"  # 必填，指向 raw/ 来源
type: concept         # 必填（concept/entity/tool/reference/place/institution/method/knowledge-card/synthesis/index/log）
aliases:              # 可选
---
```

**Type 合法值一览**：

| 类型 | 说明 | 使用量 |
|------|------|--------|
| `concept` | 概念、理论、方法论 | 209 页 |
| `entity` | 人物、组织 | 185 页 |
| `place` | 地理地点、区域、地标、历史遗迹 | 36 页 |
| `tool` | 软件工具、应用 | 26 页 |
| `reference` | 参考文档、指南、使用说明 | 15 页 |
| `institution` | 教育、研究机构 | 8 页 |
| `method` | 方法论、技术（呼吸法、修炼等） | 6 页 |
| `knowledge-card` | 知识卡片、数据快照 | 5 页 |
| `synthesis` | 综合研究报告 | 3 页 |
| `index` | 目录索引页 | 1 页 |
| `research-report` | 研究综述报告 | 1 页 |
| `lesson` | 经验教训总结 | 1 页 |
| `log` | 操作日志 | 1 页 |

---

**布尔值规范**：
```yaml
marp: "true"     # ✅ 正确（用引号包裹）
paginate: "true"   # ✅ 正确
marp: true        # ❌ 错误（Obsidian 会显示为 checkbox）
paginate: true     # ❌ 错误
```

---

## 8. 常见任务清单

### 8.1 Education AI Research 项目维护

**每周维护任务**（WorkBuddy 自动触发）：
- [ ] 检查 `raw/教育AI研究/.workbuddy/memory/MEMORY.md` 中的周次和任务状态
- [ ] 等待 WorkBuddy 自动生成本周研究计划（周一 09:00）
- [ ] 按计划执行 P0/P1/P2/P3 优先级任务
- [ ] 完成任务后更新 MEMORY.md 记录完成状态和成本

**手动维护任务**：
- [ ] 创建新的机构档案（官网采集 → 档案建立 → 质量评分 A级≥85分）
- [ ] 进行技术深度分析（学术文献 + 实践案例 + 对比分析，质量≥80分/篇）
- [ ] 执行真实性核查（五步核查法，每条信息须有来源）
- [ ] 生成结构化周报（遵循 `raw/教育AI研究/templates/04-周报生成.md` 模板）

**工具链命令**：
```bash
# 文献库管理（需设置编码）
$env:PYTHONIOENCODING="utf-8"
python raw/教育AI研究/tools/文献库管理器.py --stats --db "文献库/文献索引数据库.json"
python raw/教育AI研究/tools/文献库管理器.py --search ITS --db "文献库/文献索引数据库.json"
python raw/教育AI研究/tools/文献库管理器.py --verify --db "文献库/文献索引数据库.json"

# 质量保障工具
python raw/教育AI研究/tools/check_note_properties.py
python raw/教育AI研究/tools/verify_auto_sync.py
python raw/教育AI研究/tools/fix_orphan_files.py

# WorkBuddy 手动触发（如需）
# 查看任务定义
cat raw/教育AI研究/.workbuddy/automations/edu-ai-higher-ed-weekly-plan.toml

# 查看记忆状态
cat raw/教育AI研究/.workbuddy/memory/MEMORY.md
```

### 8.2 Wiki 摄入与维护

- [ ] 存放新来源到 `raw/{source-name}.md`
- [ ] 读取并分析关键要点
- [ ] 创建/更新 Wiki 页面（概念/实体/工具）
- [ ] 更新 `wiki/index.md`（来源数、页面数：当前为 247 页，39 来源）
- [ ] 追加 `wiki/log.md` 条目

### 8.3 Wiki 查询与回答

- [ ] 搜索相关 Wiki 页面（优先使用 `qmd query` MCP，fallback 到 grep）
- [ ] 综合多页面信息
- [ ] 检查是否有新见解
- [ ] 如有新见解，创建新 Wiki 页面并归档到 Wiki
- [ ] 更新 index 和 log

### 8.4 Wiki 健康检查

- [ ] 执行常规体检（每周）：矛盾、过时、孤岛、断链、index 准确性
- [ ] 执行深度体检（每月）：随机抽 5 页逐条比对原始文档
- [ ] 自动修复发现的偏差
- [ ] 更新 log 记录检查结果

### 8.5 EPUB 电子书转换

- [ ] 使用 EPUB 转换工具：`python -m tools.epub_converter <input.epub> <output_dir>`
- [ ] 指定作者：`[--author "作者"]`
- [ ] 添加自定义标签：`[--tags "标签1,标签2"]`
- [ ] 确保转换后的文件存放在 `raw/书名_作者/` 目录

---

## 9. 工具与资源

### 9.1 核心工具

| 工具 | 用途 | 优先级 | 维护者 |
|------|------|--------|--------|
| **Obsidian** | Wiki 的可视化 IDE | 高 | 人类 |
| **Obsidian CLI** | 命令行工具（v1.12.7+） | 高 | LLM Agent |
| **qmd** | 本地 Markdown 搜索引擎 | 中 | 人类 |
| **Marp** | 演示文稿工具（Markdown → PPT/PDF） | 高 | LLM Agent |
| **Obsidian Marp 插件** | Marp 预览和导出 | 中 | 人类 |
| **WorkBuddy** | 自动化工具（每周研究计划） | 高 | 人类 + WorkBuddy |
| **EPUB 转换工具** | `tools/epub_converter/` | 中 | LLM Agent |
| **文献库管理器** | `文献库/tools/文献库管理器.py` | 中 | LLM Agent |
| **质量保障脚本** | `raw/教育AI研究/tools/*.py` | 中 | LLM Agent |
| **frontmatter 验证** | `scripts/validate-frontmatter.py` | 高 | Git hooks |
| **关系管理** | `scripts/manage-relations.py` | 高 | LLM Agent |
| **图搜索** | `scripts/graph-search.py` | 中 | LLM Agent |
| **时效检测** | `scripts/check-staleness.py` | 中 | LLM Agent + Lint |
| **矛盾检测** | `scripts/detect-conflicts.py` | 中 | LLM Agent + Lint |
| **知识提级** | `scripts/promote-knowledge.py` | 中 | LLM Agent |

### 9.2 代理维护分工

| 责任领域 | opencode Agent | workbuddy Agent | 备注 |
|-----------|---------------|------------------|------|
| **Wiki 架构维护** | Wiki 层结构、Ingest/Query/Lint 操作 | - | - |
| **PARA 层维护** | Categories, References, Notes, Daily | - | - |
| **LLM Wiki 编译** | 新来源 → Wiki 页面创建 | - | - |
| **Wiki 索引与日志** | wiki/index.md, wiki/log.md 维护 | - | - |
| **Frontmatter 规范** | 检查与修复 frontmatter 一致性 | - | - |
| **Obsidian Skills 管理** | obsidian-skills 更新与集成 | - | - |
| **教育 AI 专项研究** | `/raw/教育AI研究/` 项目完整生命周期 | - | ✅ |
| **每周研究计划** | WorkBuddy 自动生成 | ✅ | ✅ |
| **真实性核查** | 五步核查法执行与工具链 | - | ✅ |

### 9.3 相关 Wiki 页面

**LLM Wiki 核心**：
- [[LLM Wiki]] - 核心模式定义
- [[RAG vs 持久化知识库]] - 模式对比
- [[知识库维护自动化]] - 维护负担解决方案
- [[Memex]] - 思想源头

**实践案例**：
- [[Farzapedia]] - Farza 的实践案例
- [[BYOAI]] - 四大优势
- [[Contamination Mitigation]] - Agent 工作区隔离

**人物**：
- [[Andrej Karpathy]] - 模式提出者
- [[Vannevar Bush]] - Memex 概念提出者

**工具与自动化**：
- [[Obsidian-skills]] - Obsidian 插件生态总览
- [[教育AI研究项目]] - 项目说明与结构

**Marp 生态**：
- [[Marp]] - 概念总览
- [[Marp 指令语法]] - 指令参考
- [[Marp 主题与样式]] - 主题和 CSS
- [[Marp 导出]] - 导出方式
- [[Obsidian Marp 插件]] - Obsidian 集成
- [[Marp 主题推荐]] - 社区主题合集
- [[示例-学校定制Marp演示]] - 演示示例

### 9.4 外部资源

- [[llm-wiki]] - Karpathy Gist 原文
- [[刚刚，Karpathy 开源个人 LLM Wiki]] - 第二来源（J0hn 中文解读）
- [[marp-guide]] - Marp 官方文档
- [[marp-themes]] - GitHub 主题合集

---

## 10. 附录

### 10.1 本文档特殊说明

AGENTS.md 是仓库的 **Schema 文件**，位于基础设施层：

| 属性 | 值 | 说明 |
|------|-----|------|
| **位置** | 仓库根目录 | 与 PARA、wiki、raw 同级 |
| **角色** | Wiki 结构约定、工作流规范 | 连接 PARA 层和 Wiki 层 |
| **维护者** | 人类 + LLM Agent | 共同演进 |

**Frontmatter 特殊性**：
- 继承 PARA 层的字段（categories, rating）
- 添加类型字段（type: schema）
- 不需要 source 字段（因为是规范本身，非编译产物）

### 10.2 文件命名约定

| 层级 | 类型 | 命名约定 | 示例 |
|------|------|----------|------|
| **raw/** | 来源 | `{source-name}.md` | `llm-wiki.md` |
| **wiki/** | 概念 | `{概念名称}.md` | `Memex.md` |
| **wiki/** | 实体 | `{人物姓名}.md` | `Andrej Karpathy.md` |
| **wiki/** | 工具 | `{工具名称}.md` | `qmd.md` |
| **wiki/** | 参考 | `{主题}-{子主题}.md` | `Marp-指令语法.md` |
| **Categories/** | 类别 | `{类别名}s.md` | `Books.md` |
| **References/** | 实体 | `{实体名称}.md` | `Obsidian.md` |
| **Notes/** | 笔记 | `{标题}.md` | `Evergreen notes…md` |
| **Daily/** | 日记 | `{YYYY-MM-DD}.md` | `2026-01-23.md` |
| **raw/教育AI研究/** | 项目文档 | `{类别}-{子类别}.{ext}` | `README.md`, `.toml`, `.json` |

### 10.3 更新日志

| 日期 | 版本 | 更新内容 |
|------|------|----------|
| 2026-01-23 | 1.0 | 初始版本（PARA 模式） |
| 2026-04-07 | 2.0 | 添加 LLM Wiki 模式、Marp 工作流、双层架构 |
| 2026-04-20 | 3.0 | **重大重构**：移除无关的软件开发内容，添加 Obsidian vault 维护工作流 |
| | | - 添加 WorkBuddy 自动化集成 |
| | | - 添加 Education AI Research 项目详细工作流 |
| | | - 更新实际工具链（Obsidian CLI, EPUB 转换, WorkBuddy） |
| | | - 阐明 opencode 和 workbuddy 的维护分工 |
| 2026-04-28 | 4.0 | 添加 Wiki Lint 工作流（孤儿页面检测、断链检测、空 type 修复） |
| | | - 添加 Lint 工具脚本（wiki-lint-orphan.ps1, wiki-lint-broken-v2.ps1） |
| | | - 创建 wiki/archive/ 目录用于归档大型报告页面 |
| | | - 更新 index.md 和 log.md 维护规范 |
| 2026-06-30 | 5.0 | home-wiki 跨库同步工作流完善 |
| | | - 新增 `tools/scripts/sync_home_wiki.py`（幂等同步 + frontmatter 转换 + index 自动维护 + lint 体检） |
| | | - 新增简介缓存 `tools/data/home-wiki-summaries.json`（JSON 权威来源，首次种子化） |
| | | - index.md 跨库章节标记块自动化（`<!-- BEGIN/END home-wiki-sync -->`，概念/实体表自动生成） |
| | | - 修复 home-wiki frontmatter `related: [[wikilink]]` 触发的 YAML 解析失败（正则回退逐字段提取） |
| 2026-06-30 | 5.1 | **根目录清理与结构优化** |
| | | - 5 篇根级"读"笔记移至 `wiki/`（添加 wiki frontmatter + source 引用 raw/） |
| | | - `PARA/` 目录合并至 `Notes/`（`PARA索引维护.md` → `Notes/`），删除冗余 `PARA/` |
| | | - 清理临时文件（`temp_lint_output.txt`, `today_raw_files.txt`） |
| | | - `sync-homewiki-workspace/` 移至 `tools/data/sync-homewiki/` |
| | | - `AGENTS.md` 文件夹组织表补充 `Presentations/` 和 `tools/` |
| 2026-07-01 | 6.0 | **Phase 1：Typed relationships + 内存生命周期** |
| | | - 新增 `relations` 字段（8 种边类型），`AGENTS.md` 模板全部更新 |
| | | - 新增 `confidence`/`status`/`superseded_by`/`last_reviewed`/`review_interval_days` 字段 |
| | | - 新增 `tools/scripts/manage-relations.py`（add/remove/list/graph/stats） |
| | | - 新增 `tools/scripts/graph-search.py`（qmd 语义搜索 → relations 扩展） |
| | | - 新增 `tools/scripts/check-staleness.py`（时效检测，支持 --json --overdue-only） |
| | | - 新增 `tools/scripts/detect-conflicts.py`（矛盾检测，支持 --auto-callout） |
| | | - 删除 AGENTS.md 重复概念页模板（×2 → ×1） |
| | | - 修复 AGENTS.md 编号冲突（第 5 节 ×2 → 第 6-10 节）、删除重复 quote、qmd 归位 |
| 2026-07-01 | 7.0 | **Phase 2：事件驱动自动化 + Consolidation tiers** |
| | | - 新增 `tools/scripts/validate-frontmatter.py`（pre-commit 校验） |
| | | - 新增 `tools/scripts/weekly-lint.ps1`（聚合 lint 报告） |
| | | - 新增 `tools/scripts/promote-knowledge.py`（层级提升检测） |
| | | - 新增 `.githooks/pre-commit` + `post-merge`（自动验证 + qmd 更新） |
| | | - 启用 `core.hooksPath .githooks` |
| | | - 新增 `### 2.5 结晶机制`（Crystallization） |
| | | - 新增 `### 2.6 知识提级`（Consolidation tiers） |
| | | - 工具表新增 5 行（frontmatter 验证/关系管理/图搜索/时效检测/矛盾检测/知识提级） |

### 10.4 人物 Wiki 生成规范（快速参考）

创建人物 Wiki 笔记时**必须**遵循以下规则，详细规范见 `wiki/人物Wiki文件生成规范.md`。

#### 模板与 Type 映射

| 模板 | type | tags | Base embed |
|------|------|------|------------|
| Author Template | `"People"`, `"Author"` | `person/author` | `![[Books.base#Author]]` |
| People Template | `"People"` | `person/historical` 等 | 按角色选择 |
| Actors Template | `"People"`, `"Actors"` | `person/actor` | `![[Movies.base#Actor]]` |
| Director Template | `"People"`, `"Director"` | `person/director` | `![[Movies.base#Director]]` |

#### Frontmatter 规则

```yaml
categories:
  - "[[LLM Wiki]]"
  - "[[People]]"
tags:
  - wiki
  - people
  - person/{type}
type:
  - "People"
  - "{Role}"
birthday: YYYY-MM-DD
nationality: 中国
origin: 省市区
aliases:
  - 本名
  - 英文名
source: "[[Wikipedia]]"
```

- `type` 使用双引号字符串列表，**禁止** wikilink 格式
- `aliases` 必须包含本名、英文名等变体（影响 Base 视图匹配）
- `source` 使用 wikilink 单行字符串格式

#### 信息来源与填充

1. **数据源**：通过 Exa 爬取 `https://zh.wikipedia.org/wiki/{人物名}`
2. **提取字段**：birthday → infobox"出生"，origin → infobox"籍贯"，aliases → infobox"本名"+"英文名"
3. **照片获取**：`python scripts/fetch_wikipedia_photo.py {人物名}`
4. **照片路径**：`Attachments/people/{人物名}.jpg`

#### Base 视图人物匹配

所有涉及人物匹配的 Base 视图（Author/Director/Actor）必须使用三重 `or` 条件：

```yaml
filters:
  or:
    - list({field}).contains(this)          # 精确匹配（纯文本/列表）
    - {field}.contains(this.file.name)      # 子串匹配（扩展名称）
    - file.hasLink(this.file)               # Wikilink 匹配
```

已更新：`Books.base#Author`、`Movies.base#Director`、`Movies.base#Actor`

---

## 名言

> "Obsidian is IDE; LLM is programmer; wiki is codebase."
> — [[Andrej Karpathy]]

> "这种个性化方式把控制权完全交到你手上。数据是你的，格式是通用的，内容是可检查的。用哪个 AI 随你，让 AI 公司们卷起来吧。"
> — [[Andrej Karpathy]]

<!-- Added: 2026-04-20 -->

## opencode-mem 记忆汇报规则

每次对话结束时，必须简要汇报 opencode-mem 记忆更新情况（新增/修改/删除了哪些记忆）。如果本次对话未触发记忆变更，也需说明"本次无记忆变更"。

**2026-04-28 本次汇报**：
- 更新的 AGENTS.md 内容：添加 Wiki Lint 工作流（第9.3节更新日志）
- 更新的 wiki/index.md 内容：页面数更新（408→401），孤儿页面从28降到0，添加21个页面的入站链接
- 更新的 wiki/log.md 内容：追加孤儿页面归档记录（7页归档到archive/）
- 新建的 wiki/archive/ 目录：用于归档大型报告页面
- 无删除的记忆

<!-- Added: 2026-04-23 -->