giteahh/llm_wiki

Fork 0

Files

豆儿雷锋大道 3866525764 Add AGENTS.md and Templates directory

2026-04-07 21:13:42 +08:00

29 KiB

Raw Blame History

categories, tags, created, rating, type

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 后再执行操作。

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

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` (复数)	人类
`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、视频	人类
`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

三种核心操作：

Ingest（摄入）：将新来源编译到 wiki，更新 index 和 log
Query（查询）：搜索 wiki 页面并综合回答
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 | index | log  # ✅ 必须指定类型
aliases:  # 可选
  - {alias1}
  - {alias2}
marp: "true"  # Marp 演示文稿专用
---

字段说明：

字段	必填	PARA 层	Wiki 层	说明
`categories`	✅	`[[Category]]`	`[[LLM Wiki]]`	类别
`tags`	✅	`{tag}`	`wiki`, `{tag}`	标签
`created`	✅	`YYYY-MM-DD`	`YYYY-MM-DD`	创建日期
`source`	❌	可选	✅ 必填	Wiki 层必须指向 raw 来源
`type`	❌	可选	✅ 必填	Wiki 层必须指定页面类型
`aliases`	❌	可选	可选	替代名称列表
`marp`	❌	可选	可选	演示文稿标识，必须用引号

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[完成]

详细步骤：

读取来源

# 来源存入 raw/ 目录
raw/source-name.md

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

更新 index.md

## 概览

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

追加 log.md

## [YYYY-MM-DD] ingest | {来源标题}

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

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

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

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

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

2.2 Query（查询）操作

当用户对 Wiki 提问时：

搜索相关页面（使用 grep 或 qmd）
综合多页面的信息
如果发现新的见解，将回答归档为新 Wiki 页面
更新 index 和 log

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

2.3 Lint（健康检查）

定期执行健康检查：

检查矛盾 - 搜索冲突声明
检查过时 - 标记陈旧信息
检查孤立页面 - 无入站链接的页面
检查缺失概念 - 需要创建但尚未创建的页面
检查交叉引用 - 确保相关页面互相链接

# 示例命令
grep -r "TODO\|FIXME\|过时\|矛盾" wiki/
grep -r "\[\[" wiki/ | grep -v "md:" | sort | uniq -c | sort -rn | head -20

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

# {概念名称}

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

## 定义

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

## 关键要点

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

## 与其他概念的关系

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

## 来源

- [[source]] — 来源描述

实体页面：

---
categories:
  - "[[LLM Wiki]]"
  - "[[People]]"
tags:
  - wiki
  - people
  - {domain}
created: {YYYY-MM-DD}
source: "[[{source-file}]]"
type: entity
aliases:
  - {alias}
---

# {人物姓名}

{一句话简介}

## 身份

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

## 主要贡献

- 贡献 1
- 贡献 2

## 与本 Wiki 相关

{此人与 wiki 内容的关联}

## 来源

- [[source]] — 来源描述

工具页面：

---
categories:
  - "[[LLM Wiki]]"
tags:
  - wiki
  - tool
  - {category}
created: {YYYY-MM-DD}
source: "[[{source-file}]]"
type: tool
aliases:
  - {alias}
---

# {工具名称}

> **一句话描述**

## 基本信息

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

## 在 LLM Wiki 中的角色

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

## 来源

- [[source]] — 来源描述

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

局部指令（注释中）：

 - 封面页样式
 - 深色背景
 - 两栏布局
 - 当前页不显示页码

自定义主题：

主题文件存放在 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 插件：

打开 Marp 文件
点击预览按钮（👁️）
点击导出按钮（📥）
选择格式：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. 构建与测试命令

4.1 可用命令

AI 代理可使用以下命令进行构建和测试：

命令	功能	使用场景
bun run dev	启动开发服务器	本地开发时热重载
bun run build	构建生产版本	CI/CD 环境构建
bun run lint	运行代码检查	确保 ESLint 规范
bun test	运行单元测试	Jest/Vitest 测试套件
bun run test:unit	单元测试	`测试特定模块`
bun run test:e2e	E2E 测试	`集成测试`
bun run test:integration	集成测试	端到端测试
bun run test:coverage	测试覆盖率	生成覆盖率报告
bun run type-check	类型检查	TypeScript 类型验证
pytest	Python 测试	后端测试时使用

4.2 命令使用规范

## 启动开发服务器

# 推荐方式
bun run dev

# 禁止方式
bun --bun run dev

# 或者使用 oh-my-opencode 的 pty_spawn
pty_spawn:
  command: "bun"
  args: ["run", "dev"],
  title: "Dev Server",
  notifyOnExit: true

## 运行测试

# 单个测试
bun test path/to/test.spec.ts

# 带详细输出
bun test --reporter=verbose path/to/test.spec.ts

# 运行特定测试
bun test path/to/test.spec.ts -t "Authentication Flow"

# 生成覆盖率报告
bun run test:coverage --reporter=text --reporter=lcov

## 类型检查

# TypeScript 类型检查
bun run type-check

# 或配合 TSC
bunx tsc --noEmit

4.3 测试最佳实践

原则 1：快速失败（Fail Fast）

# 单元测试应该快速执行（< 2 分钟）
- 快速发现明显问题
- 避免测试中的网络请求
- 使用 mock 数据隔离依赖

**适用场景：**
- 验证核心业务逻辑
- 测试纯函数组件

原则 2：测试隔离

# 每个测试文件应该能够独立运行
- 不依赖其他测试的状态
- 使用独立的测试数据库或 mock 服务
- 清理测试后的资源

**实现方式：**
```typescript
// 每个测试文件使用独立的 beforeEach/afterEach
import { beforeEach, afterEach } from '@testing-library/react';

describe('UserService', () => {
  beforeEach(() => {
    // 清理或初始化每个测试前的状态
    userService = new UserService();
  });

  afterEach(() => {
    // 清理每个测试后的资源
    userService.dispose();
  });

  it('should create user', () => {
    // 测试代码...
  });
});


#### 原则 3：描述性测试名称

```markdown
# 测试名称应该清晰描述测试意图和场景

describe('Authentication Flow', () => {
  it('should authenticate user with valid credentials', () => { });
  it('should reject invalid credentials', () => { });
  it('should handle network errors gracefully', () => { });
});

避免：

// ❌ 避免模糊名称
it('test', () => {});

// ✅ 使用描述性名称
it('should authenticate user with valid credentials', () => {});

原则 4：测试覆盖率目标

# 设定测试覆盖率目标（建议 80% 以上）

# package.json 配置
{
  "scripts": {
    "test": "vitest run --coverage",
    "test:coverage": "vitest run --coverage --reporter=json"
  },

  "coverage": {
    "statements": 80,
    "branches": 80,
    "functions": 80,
    "lines": 80
  }
}

4.4 Lint 与格式化命令

## ESLint

# 运行 ESLint
bun run lint

# 修复问题
bun run lint --fix

# 检查特定文件
bun run lint path/to/component.ts

# 生成报告
bun run lint --format json --output-file eslint-report.json

## Prettier

# 格式化代码
bun run format

# 检查格式
bun run format --check

# 格式化特定文件
bun run format path/to/component.ts

4.5 命令执行优先级

## 开发工作流中的命令使用优先级

| 优先级 | 命令类型 | 说明 |
|--------|-----------|--------|
| **高** | 开发服务器启动/重启 | `bun run dev`（常用） |
| **高** | 类型检查 | `bun run type-check`（快速验证） |
| **中** | Lint/格式化 | `bun run lint`, `bun run format`（定期执行） |
| **中** | 单元测试 | `bun test`（开发过程中） |
| **低** | 集成测试 | `bun run test:integration`（PR 前或合并前） |
| **低** | E2E/覆盖率测试 | `bun run test:e2e`（定期执行） |
| **低** | 文档生成 | 手动生成文档 |

5. 代码风格指南

5.1 TypeScript 编码规范

5.1.1 命名约定

// ✅ 组件和类名：PascalCase
class UserService { }
interface UserProfile { }

// ✅ 函数和变量：camelCase
function getUserById() { }
const userId = 0;
const userProfile: UserProfile;

// ❌ 避免缩写
function getusr() { }

// ✅ 使用描述性名称
function authenticateUser() { }

// ✅ 常量：UPPER_SNAKE_CASE
const API_BASE_URL = 'https://api.example.com';
const MAX_RETRIES = 3;

// ❌ 避免单字母变量
const a = 1;
const n = userId;

5.1.2 类型定义

// ✅ 使用明确的类型定义
interface ApiResponse<T> {
  data: T;
  error?: string;
  status: number;
}

// ✅ 使用泛型提高代码复用
interface Repository<T> {
  findAll(): Promise<T[]>;
  findById(id: string): Promise<T>;
  create(entity: T): Promise<T>;
}

// ❌ 避免使用 any（除非确实必要）
// ✅ 使用 unknown 替代
function process(data: unknown) {
  // 明确类型或接口
}

// ✅ 使用联合类型明确可能的状态
type Status = 'pending' | 'success' | 'error';

5.1.3 错误处理

// ✅ 统一的错误处理模式

// 1. 定义错误类型
class ValidationError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'ValidationError';
  }
}

class NetworkError extends Error {
  constructor(message: string, code: number) {
    super(message);
    this.name = 'NetworkError';
    this.code = code;
  }
}

// 2. 使用 try-catch 包裹可能失败的代码
try {
  await apiCall();
} catch (error) {
  if (error instanceof NetworkError) {
    // 网络错误处理
  } else if (error instanceof ValidationError) {
    // 验证错误处理
  } else {
    // 未知错误处理
  }
}

// 3. 错误日志记录
console.error('[ERROR]', error.message, error.stack);
// 或使用日志服务
logger.error('API call failed', { error, context: { userId, action } });

5.2 导入与依赖管理

// ✅ 明确导入路径（使用绝对导入）
import { UserService } from './services/user/UserService';
import { validateUser } from './utils/validators';

// ✅ 使用类型导入
import type { User, UserProfile } from './types';

// ✅ 按功能分组导入
// UI 组件
import { Button } from './components/ui/Button';
import { Form } from './components/ui/Form';
// 工具函数
import { formatDate } from './utils/dateUtils';

// ❌ 避免相对导入（除非在同一目录内）
// import { Something } from '../shared/Something';

// ✅ 使用 barrel exports（index.ts 导出）
// services/index.ts
export { UserService, AuthService, OrderService };
export type { User, Order, Profile };

5.2.1 API 调用规范

// ✅ 使用 async/await
async function fetchData(): Promise<Data> {
  const response = await fetch(url);
  return response.json();
}

// ❌ 避免回调地狱（使用 async/await）
// fetchData((data, callback) => { callback(data); }); // 不推荐

// ✅ 正确的错误传播
async function processOrder(orderId: string): Promise<void> {
  try {
    await validateOrder(orderId);
    await processPayment(orderId);
    await shipOrder(orderId);
  } catch (error) {
    // 统一错误处理
    throw new ProcessingError('Failed to process order', error);
  }
}

6. Wiki 与 PARA 协作指南

6.1 知识流转路径

graph LR
    Raw[新来源] --> Ingest[Ingest 操作]
    Ingest --> Wiki[wiki/ 页面]
    Wiki -->|价值高| Ref[References/ 归档]
    Wiki -->|个人洞察| Notes[Notes/ 笔记]
    Wiki -->|参考模板| Templ[Templates/]

    Raw -->|直接阅读| Clippings[Clippings/]
    Clippings -->|价值验证| Ingest

6.2 操作决策树

场景	操作层	工作流	示例
收到新文章	Wiki 层	Ingest → 编译到 wiki	读取论文，创建概念页
临时摘录	PARA 层	Clippings/ → 存储待整理	网页摘录，暂存
个人感悟	PARA 层	Notes/ → 原子笔记	阅读后的思考
稳定知识	Wiki 层	维护 wiki 页面	概念页长期更新
模板需求	Templates/	创建模板	新内容类型模板

6.3 Frontmatter 一致性

确保跨层级的 frontmatter 一致性：

层级	categories	tags	type	source
PARA 层	`[[Category]]`	`{tag}`	可选	不需要
Wiki 层	`[[LLM Wiki]]`	`wiki`	必填	必填

示例对比：

# PARA 层 - References/Obsidian.md
---
categories:
  - "[[Tools]]"
tags:
  - tools
  - obsidian
  - knowledge-management
created: 2026-01-23
rating: 5
author: []
---

# Obsidian

Obsidian is a markdown-based note-taking app...

# Wiki 层 - wiki/Obsidian.md
---
categories:
  - "[[LLM Wiki]]"
tags:
  - wiki
  - tool
  - obsidian
created: 2026-04-07
source: "[[raw/obsidian-guide.md]]"
type: tool
aliases:
  - Obsidian 笔记工具
---

# Obsidian

> **一句话描述**：基于 Markdown 的知识管理工具

## 基本信息

| 属性 | 值 |
|------|-----|
| 官网 | https://obsidian.md |
| 类型 | 知识管理工具 |

## 在 LLM Wiki 中的角色

Obsidian 是 Wiki 的可视化 IDE，提供 Graph View 查看连接形状。

## 来源

- [[raw/obsidian-guide.md]] - 官方文档

7. 常见任务清单

7.1 摄入新来源

存放来源到 raw/{source-name}.md
读取并分析关键要点
创建/更新 Wiki 页面（概念/实体/工具）
更新 wiki/index.md（来源数、页面数）
追加 wiki/log.md 条目
检查是否需要创建 PARA 层引用

7.2 回答 Wiki 查询

搜索相关 Wiki 页面（grep/qmd）
综合多页面信息
检查是否有新见解
如有新见解，创建新 Wiki 页面
更新 index 和 log

7.3 Wiki 健康检查

检查矛盾声明
检查过时信息
检查孤立页面
检查缺失交叉引用
更新 log 记录检查结果

7.4 创建 Marp 演示文稿

添加 frontmatter：marp: "true", theme, paginate
编写幻灯片内容（每页用 --- 分隔）
添加页面类型注释（ 等）
使用 Obsidian Marp 插件预览
导出为 HTML/PDF/PPTX

7.5 自定义 Marp 主题

在 Templates/MarpTheme/ 创建 CSS 文件
定义 CSS 变量（颜色、字体）
编写自定义样式规则
重启 Obsidian 使主题生效
在 frontmatter 中引用：theme: theme-name
创建示例演示文稿验证主题

8. 工具与资源

8.1 核心工具

工具	用途	文档
Obsidian	Wiki 的可视化 IDE	官方文档
qmd	本地 Markdown 搜索引擎	GitHub
Marp	演示文稿工具	marp.guide
Obsidian Marp	Obsidian 中的 Marp 插件	GitHub

8.2 相关 Wiki 页面

LLM Wiki 核心：

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

实践案例：

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

人物：

Andrej Karpathy - 模式提出者
Vannevar Bush - Memex 概念提出者

Marp 生态：

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

8.3 外部资源

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

9. 附录

9.1 本文档特殊说明

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

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

Frontmatter 特殊性：

继承 PARA 层的字段（categories, rating）
添加 Wiki 层的字段（type: schema）
不需要 source 字段（因为是规范本身，非编译产物）

9.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`

9.2 Git 忽略规则

# Obsidian
.obsidian/workspace.json
.obsidian/workspace-mobile.json

# 导出文件
*.pdf
*.html
*.pptx
# 除非是源文件

# 临时文件
.DS_Store
Thumbs.db

9.3 更新日志

日期	版本	更新内容
2026-01-23	1.0	初始版本（PARA 模式）
2026-04-07	2.0	添加 LLM Wiki 模式、Marp 工作流、双层架构

名言

"Obsidian is the IDE; LLM is the programmer; wiki is the codebase." — Andrej Karpathy

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

29 KiB Raw Blame History Unescape Escape