llm_wiki/AGENTS.md

categories, tags, created, rating, type

categories	tags	created	rating	type
Tools Documentation	agents ai-assistant development-workflow obsidian-vault knowledge-management	2026-01-23	7	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 使用独立二进制文件，响应更快。常用命令：

# 版本检查
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：

---
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：

---
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（摄入）操作

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

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

详细步骤：

1. 读取来源

   # 来源存入 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

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

4. 追加 log.md

   ## [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 中的指标（页面数、来源数）与实际一致

# 孤岛检测：找出 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

# 随机抽样（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：

概念页面：

---
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]] — 来源描述

---
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]] — 来源描述

实体页面：

---
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]] — 来源描述

工具页面：

---
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：

---
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)：

/* @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;
}

使用方式：

---
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 命令：

# 导出 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 使用独立二进制文件，响应更快。常用命令：

# 版本检查
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 笔记。

命令行：

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、注释标记行）

用法：

$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%
周报生成	结构化总结，标注完成率和成本	完成率、成本统计

自动化工具：

文献管理：

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

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

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

# 验证 DOI
python 文献库\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

---

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 工具脚本

# 位置: 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）：

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

---

7. Wiki 维护工作流

7.1 每周维护周期

WorkBuddy 自动化：

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

手动触发维护：

# 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：

---
categories:
  - "[[Category]]"  # 单数形式，wikilink 格式
tags:
  - tag1
  - tag2
created: YYYY-MM-DD
rating: 5
author: []
---

Wiki 层 frontmatter（必须包含）：

---
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 页

---

布尔值规范：

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 模板）

工具链命令：

# 文献库管理（需设置编码）
$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 规则

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 条件：

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

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/ 目录：用于归档大型报告页面
• 无删除的记忆