1191 lines
29 KiB
Markdown
1191 lines
29 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` (复数) | 人类 |
|
||
| `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 |
|
||
|
||
**三种核心操作**：
|
||
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 | 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（摄入）操作
|
||
|
||
当收到新来源时，按以下流程处理：
|
||
|
||
```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` - 详细文档、教程
|
||
|
||
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. 搜索相关页面（使用 grep 或 qmd）
|
||
2. 综合多页面的信息
|
||
3. 如果发现新的见解，**将回答归档为新 Wiki 页面**
|
||
4. 更新 index 和 log
|
||
|
||
> **原则**：好的回答应该成为 Wiki 的一部分，让探索像摄入一样持续积累。
|
||
|
||
### 2.3 Lint（健康检查）
|
||
|
||
定期执行健康检查：
|
||
|
||
1. **检查矛盾** - 搜索冲突声明
|
||
2. **检查过时** - 标记陈旧信息
|
||
3. **检查孤立页面** - 无入站链接的页面
|
||
4. **检查缺失概念** - 需要创建但尚未创建的页面
|
||
5. **检查交叉引用** - 确保相关页面互相链接
|
||
|
||
```bash
|
||
# 示例命令
|
||
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`：
|
||
|
||
**概念页面**：
|
||
```markdown
|
||
---
|
||
categories:
|
||
- "[[LLM Wiki]]"
|
||
tags:
|
||
- wiki
|
||
- {tag1}
|
||
- {tag2}
|
||
created: {YYYY-MM-DD}
|
||
source: "[[{source-file}]]"
|
||
type: concept
|
||
aliases:
|
||
- {alias1}
|
||
---
|
||
|
||
# {概念名称}
|
||
|
||
> **一句话定义**：{核心定义}
|
||
|
||
## 定义
|
||
|
||
{概念的详细定义和解释}
|
||
|
||
## 关键要点
|
||
|
||
- 要点 1
|
||
- 要点 2
|
||
- 要点 3
|
||
|
||
## 与其他概念的关系
|
||
|
||
- [[相关概念1]] — {关系说明}
|
||
- [[相关概念2]] — {关系说明}
|
||
|
||
## 来源
|
||
|
||
- [[source]] — 来源描述
|
||
```
|
||
|
||
**实体页面**：
|
||
```markdown
|
||
---
|
||
categories:
|
||
- "[[LLM Wiki]]"
|
||
- "[[People]]"
|
||
tags:
|
||
- wiki
|
||
- people
|
||
- {domain}
|
||
created: {YYYY-MM-DD}
|
||
source: "[[{source-file}]]"
|
||
type: entity
|
||
aliases:
|
||
- {alias}
|
||
---
|
||
|
||
# {人物姓名}
|
||
|
||
{一句话简介}
|
||
|
||
## 身份
|
||
|
||
| 属性 | 值 |
|
||
|------|-----|
|
||
| 领域 | {领域} |
|
||
| 知名身份 | {身份} |
|
||
|
||
## 主要贡献
|
||
|
||
- 贡献 1
|
||
- 贡献 2
|
||
|
||
## 与本 Wiki 相关
|
||
|
||
{此人与 wiki 内容的关联}
|
||
|
||
## 来源
|
||
|
||
- [[source]] — 来源描述
|
||
```
|
||
|
||
**工具页面**：
|
||
```markdown
|
||
---
|
||
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：
|
||
|
||
```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. 构建与测试命令
|
||
|
||
### 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 命令使用规范
|
||
|
||
```markdown
|
||
## 启动开发服务器
|
||
|
||
# 推荐方式
|
||
bun run dev
|
||
|
||
# 禁止方式
|
||
bun --bun run dev
|
||
|
||
# 或者使用 oh-my-opencode 的 pty_spawn
|
||
pty_spawn:
|
||
command: "bun"
|
||
args: ["run", "dev"],
|
||
title: "Dev Server",
|
||
notifyOnExit: true
|
||
```
|
||
|
||
```markdown
|
||
## 运行测试
|
||
|
||
# 单个测试
|
||
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
|
||
```
|
||
|
||
```markdown
|
||
## 类型检查
|
||
|
||
# TypeScript 类型检查
|
||
bun run type-check
|
||
|
||
# 或配合 TSC
|
||
bunx tsc --noEmit
|
||
```
|
||
|
||
### 4.3 测试最佳实践
|
||
|
||
#### 原则 1：快速失败（Fail Fast）
|
||
|
||
```markdown
|
||
# 单元测试应该快速执行（< 2 分钟）
|
||
- 快速发现明显问题
|
||
- 避免测试中的网络请求
|
||
- 使用 mock 数据隔离依赖
|
||
|
||
**适用场景：**
|
||
- 验证核心业务逻辑
|
||
- 测试纯函数组件
|
||
```
|
||
|
||
#### 原则 2：测试隔离
|
||
|
||
```markdown
|
||
# 每个测试文件应该能够独立运行
|
||
- 不依赖其他测试的状态
|
||
- 使用独立的测试数据库或 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', () => { });
|
||
});
|
||
```
|
||
|
||
**避免：**
|
||
```markdown
|
||
// ❌ 避免模糊名称
|
||
it('test', () => {});
|
||
|
||
// ✅ 使用描述性名称
|
||
it('should authenticate user with valid credentials', () => {});
|
||
```
|
||
|
||
#### 原则 4：测试覆盖率目标
|
||
|
||
```markdown
|
||
# 设定测试覆盖率目标（建议 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 与格式化命令
|
||
|
||
```markdown
|
||
## 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 命令执行优先级
|
||
|
||
```markdown
|
||
## 开发工作流中的命令使用优先级
|
||
|
||
| 优先级 | 命令类型 | 说明 |
|
||
|--------|-----------|--------|
|
||
| **高** | 开发服务器启动/重启 | `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 命名约定
|
||
|
||
```typescript
|
||
// ✅ 组件和类名：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 类型定义
|
||
|
||
```typescript
|
||
// ✅ 使用明确的类型定义
|
||
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 错误处理
|
||
|
||
```typescript
|
||
// ✅ 统一的错误处理模式
|
||
|
||
// 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 导入与依赖管理
|
||
|
||
```typescript
|
||
// ✅ 明确导入路径（使用绝对导入）
|
||
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 调用规范
|
||
|
||
```typescript
|
||
// ✅ 使用 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 知识流转路径
|
||
|
||
```mermaid
|
||
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` | **必填** | **必填** |
|
||
|
||
**示例对比**：
|
||
|
||
```yaml
|
||
# 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...
|
||
```
|
||
|
||
```yaml
|
||
# 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`
|
||
- [ ] 编写幻灯片内容（每页用 `---` 分隔）
|
||
- [ ] 添加页面类型注释（`<!-- _class: cover -->` 等）
|
||
- [ ] 使用 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]]
|