hehaiguang1123
a6f05ab2d5
- Phase 0: AGENTS.md cleanup (dedup quotes, renumber sections, merge qmd) - Phase 1: typed relations (manage-relations.py, graph-search.py, check-staleness.py, detect-conflicts.py) - Phase 2: frontmatter validator, weekly lint, knowledge promotion, git hooks - Fix .gitignore to track tools/ and .githooks/ - Fix git remote URL (remove plaintext token) - New wiki pages: 504 pages, 34 raw sources
1422 lines
47 KiB
Markdown
1422 lines
47 KiB
Markdown
---
|
||
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`
|
||
|
||
---
|
||
|
||
## 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 -->
|