yixiong-claude-marketplace/plugins/obsidian/skills/obsidian-bases/SKILL.md

---
name: obsidian-bases
description: Obsidian 1.9+ 原生数据库视图（Bases）：查询 .base 文件中的结构化视图（JSON/CSV/MD 输出）、在 base 中创建新条目。触发词：Bases、base 视图、数据库视图、结构化查询笔记、base query。不用于 Dataview（社区插件，用其原生 DQL 语法）。依赖 YAML frontmatter 属性，与 obsidian-meta 配合使用；需 Obsidian ≥ 1.9。
---

# Obsidian Bases · 原生数据库视图

> **Obsidian 1.9+ 的杀手级特性**：把 vault 当成数据库，把每篇笔记当成一条记录，把 frontmatter 当成字段。用 `.base` 文件定义视图和筛选，不用写一行 JS（对比 Dataview）。

> **为什么 Bases 对 AI agent 意义重大**：它把"非结构化笔记 + frontmatter 属性"变成了"可查询的结构化数据"，agent 可以直接 `base:query` 拿到 JSON，不需要先全文搜索再解析。

---

## 何时使用

- 列出 vault 中所有 `.base` 数据库视图文件
- **查询某个 base** 的结果（支持多种输出格式）
- 在 base 中**创建新条目**（自动写入符合 base 视图规则的 frontmatter）
- 列出某 base 的所有**视图**（views）
- 把"项目管理面板"、"阅读清单"、"文章管理"等做成可视化看板

## 不用于

- **Dataview** 查询（社区插件，用 DQL 语法，不是 Bases）
- 简单的属性读写 → **obsidian-meta**
- 全文搜索 → **obsidian-search**

---

## 前置条件

- **Obsidian ≥ 1.9**（检查：`obsidian version`）
- 知识库中存在至少一个 `.base` 文件（通过 Obsidian UI 创建，或从社区模板复制）
- 参与 base 的笔记必须使用 **YAML frontmatter**（不是 Dataview inline 字段，Bases 不认）

---

## 命令速查

### Base 文件与视图管理

```bash
obsidian bases                         # 列出 vault 所有 .base 文件
obsidian base:views                    # 列出当前 base 的所有视图
obsidian base:views file="项目管理"     # 列出某 base 的视图
```

### 查询 Base

```bash
# 基础查询（默认 JSON）
obsidian base:query file="项目管理"
obsidian base:query path="20-Areas/项目管理.base"

# 指定视图
obsidian base:query file="项目管理" view="进行中"
obsidian base:query file="项目管理" view="按截止日" format=csv
obsidian base:query file="项目管理" view="逾期" format=md     # Markdown 表格
obsidian base:query file="项目管理" view="全部" format=paths  # 只返回路径列表
obsidian base:query file="项目管理" view="全部" format=tsv
```

**输出格式**：
- `json`（默认）：最完整，含所有字段
- `csv`：表格，适合导出到 Excel
- `tsv`：表格，Bash 处理友好
- `md`：Markdown 表格，直接粘贴到笔记
- `paths`：只返回文件路径列表

### 在 Base 中创建新条目

```bash
# 在某视图下创建新笔记（自动套用该视图的默认字段）
obsidian base:create file="项目管理" view="进行中" name="新项目Alpha" \
  content="# 新项目 Alpha" open

# 完整参数
obsidian base:create \
  file="项目管理" \
  view="进行中" \
  name="新项目" \
  content="初始内容" \
  open \
  newtab
```

> 💡 `base:create` 的威力：它会按视图规则**自动填充 frontmatter**（例如 "进行中" 视图可能强制 `status: active`），省去手动 `property:set`。

---

## Bases vs Dataview 选型表

| 维度 | Bases（官方 1.9+） | Dataview（社区插件） |
|-----|-------------------|---------------------|
| 语法 | YAML 配置（声明式） | JS/DQL（命令式） |
| 数据源 | 仅 YAML frontmatter | frontmatter + inline `Key::` |
| 写入 | ✅ 支持 `base:create` | ❌ 只读 |
| 性能 | ✅ 原生 C++，极快 | ⚠ JS 运行时，大 vault 卡 |
| 多视图 | ✅ 一个 base 多视图 | 每个查询一段代码 |
| AI agent 友好 | ✅ CLI 直接 query JSON | ⚠ 需要模拟 Dataview JS 运行 |
| 社区模板 | 🟡 起步阶段 | ✅ 海量模板 |
| 版本要求 | Obsidian ≥ 1.9 | 任意版本 |

**选型建议**：
- **新项目 / AI agent 驱动** → 首选 Bases
- **已有 Dataview 资产** → 继续用，或逐步迁移
- **需要复杂计算** → Dataview（Bases 未来会支持公式字段）

---

## AI Agent 最佳实践

### 场景 1 · 项目面板作为 AI 决策依据

```bash
# Agent 问："今天我该优先处理哪个项目？"
# Step 1: 查询"进行中"项目，按 due 排序
obsidian base:query file="项目管理" view="按截止日" format=json

# Step 2: Agent 分析返回的 JSON，找出：
#   - due 最近的 3 个
#   - priority 最高的 3 个
#   - blocked 状态已解除的

# Step 3: 生成建议写入每日笔记
obsidian daily:append content="\n## 📌 AI 建议优先级\n..."
```

### 场景 2 · 阅读清单 Base 设计

创建 `30-Resources/reading-list.base`（通过 Obsidian UI），字段规划：

```yaml
# frontmatter 规范（每本书/文章一个笔记）
---
type: book | article | paper | video
title: 
author: 
url: 
status: to-read | reading | done | abandoned
priority: 1-5
started: 2026-03-15
finished: 
rating: 1-5
tags: [topic1, topic2]
---
```

视图设计：
- **待读**: `status == "to-read"`, 按 `priority desc`
- **在读**: `status == "reading"`
- **已读高分**: `status == "done" AND rating >= 4`
- **按主题**: group by `tags`

```bash
# Agent 查询：我的待读列表前 5
obsidian base:query file="reading-list" view="待读" format=md | head -20
```

### 场景 3 · 用 Base 做 AI 工作日志

创建 `99-Log/ai-actions.base`，每次 agent 写入操作创建一条记录：

```bash
# 不手动建笔记，直接通过 base:create
obsidian base:create \
  file="ai-actions" \
  view="今日" \
  name="$(date +%Y%m%d%H%M%S)-property-set" \
  content="---
action: property:set
target: 项目Alpha
field: status
value: done
agent: claude-sonnet-4-6
reason: 用户确认项目完成
---"
```

之后查询：

```bash
obsidian base:query file="ai-actions" view="今日" format=md
obsidian base:query file="ai-actions" view="本周 action 统计" format=csv
```

### 场景 4 · Base 作为 RAG 检索的结构化索引

传统 RAG：全文搜索 → 召回 → 喂模型。
Bases 增强：**先用 base 做结构化筛选，缩小召回范围，再做全文搜索**。

```bash
# 问题："最近 3 个月我写的关于虚拟线程的读书笔记"
# Step 1: 用 base 筛出结构化候选
obsidian base:query file="reading-list" view="近 3 个月" format=paths > /tmp/candidates.txt

# Step 2: 在候选范围内全文搜索
obsidian search query="虚拟线程" path="$(xargs -a /tmp/candidates.txt)" format=json
```

---

## Base 文件结构（了解即可，通常由 UI 生成）

`.base` 文件是 YAML 格式：

```yaml
# 20-Areas/项目管理.base
filters:
  and:
    - file.inFolder: "10-Projects"
    - status: ["active", "paused"]

views:
  - name: 进行中
    type: table
    filters:
      - status: active
    order:
      - due ASC
    columns:
      - file.name
      - status
      - due
      - priority
      - owner

  - name: 按截止日
    type: table
    order:
      - due ASC

  - name: 逾期
    type: list
    filters:
      - due < today()
      - status: active
```

> 💡 推荐通过 Obsidian UI 创建 `.base` 文件，再用 CLI 查询。直接手写 `.base` 容易语法错。

---

## 与其他技能的协作

| 场景 | 链路 |
|-----|------|
| 属性设计 → 视图落地 | **obsidian-meta**（frontmatter 规范）→ obsidian-bases（查询） |
| 结构化召回 + 全文精读 | obsidian-bases → **obsidian-search** |
| 决策支持 | obsidian-bases → **obsidian-daily**（写建议） |
| 项目看板自动化 | obsidian-bases + **obsidian-tasks**（进度） |
| AI 日志归档 | 所有技能写操作 → obsidian-bases（`base:create` 到 ai-actions.base） |

---

## 常见陷阱

| 现象 | 原因 | 对策 |
|------|------|------|
| `bases` 命令返回空 | Obsidian 版本 < 1.9 | 升级到 1.9+ |
| `base:query` 字段缺失 | 笔记用了 Dataview inline 字段 | 改写到 YAML frontmatter |
| `base:create` 报错 | view 名称拼写错 | 先 `base:views` 列出 |
| 视图不更新 | 缓存 | `obsidian reload` |
| 日期排序错 | frontmatter 日期是 text 类型 | `property:set type=date` |
| 查询慢 | base filter 过于宽松 | 增加 `file.inFolder` 限定 |
| agent 写的 base 条目违反 schema | 没先读 base 规则 | `base:views` + 手动验证字段 |