# Obsidian 技能使用指南

## 📦 技能来源

本指南包含 **Kepano 官方 Obsidian 技能**，来源：
- GitHub: https://github.com/kepano/obsidian-skills
- 遵循 [Agent Skills Specification](https://agentskills.io/specification)

**安装方式：**
```bash
npx skills add git@github.com:kepano/obsidian-skills.git
```

---

## 技能概览

处理 Obsidian 笔记时，根据不同需求使用对应的技能：

### 📦 Kepano 官方技能

| 技能 | 主要用途 | 需要 Obsidian 运行 | 命令行工具 |
|------|---------|------------------|------------|
| **obsidian-markdown** | 创建/编辑笔记内容 | ❌ 不需要 | 无 |
| **obsidian-cli** | 交互式操作、插件开发 | ✅ 需要 | `obsidian` |
| **obsidian-bases** | 创建数据库视图 | ❌ 不需要 | 无 |
| **json-canvas** | 创建视觉画布 | ❌ 不需要 | 无 |

### 🔧 其他技能

| 技能 | 主要用途 | 需要 Obsidian 运行 | 命令行工具 |
|------|---------|------------------|------------|
| **obsidian** | 基本文件操作（已过时） | ❌ 不需要 | `notesmd-cli` |

---

## 1. obsidian-markdown (最常用)

**使用场景：**
- 创建新笔记
- 编辑现有笔记内容
- 添加 wikilinks、embeds、callouts
- 设置 frontmatter properties

**主要功能：**
- Wikilinks: `[[Note]]`, `[[Note\|Text]]`, `[[Note#Heading]]`
- Embeds: `![[Note]]`, `![[image.png]]`, `![[PDF.pdf#page=3]]`
- Callouts: `> [!note]`, `> [!warning]`, `> [!tip]`
- Frontmatter: `title`, `tags`, `status`, `aliases`
- 高亮: `==highlighted text==`
- 标签: `#tag`, `#nested/tag`

**典型用法：**
```markdown
---
title: My Note
tags:
  - project
  - active
status: in-progress
---

# My Note

Related to [[Project Alpha]].

> [!important] Key Info
> This is important content.

![[Diagram.png]]

Tasks:
- [x] Done
- [ ] Pending
```

---

## 2. obsidian-cli (交互式操作)

**使用场景：**
- 读取、创建、搜索笔记
- 管理任务（tasks）
- 设置 properties
- 插件开发调试
- 需要 Obsidian 运行中

**主要功能：**
- 读取笔记: `obsidian read file="My Note"`
- 创建笔记: `obsidian create name="New Note" content="Hello"`
- 搜索: `obsidian search query="test"`
- Daily notes: `obsidian daily:read`, `obsidian daily:append`
- Properties: `obsidian property:set name="status" value="done"`
- Tasks: `obsidian tasks daily todo`

**插件开发：**
```bash
obsidian plugin:reload id=my-plugin
obsidian dev:errors
obsidian dev:screenshot path=screenshot.png
obsidian dev:dom selector=".workspace-leaf" text
```

---

## 3. json-canvas (视觉画布)

**使用场景：**
- 创建可视化画布
- 构建思维导图
- 设计流程图
- 创建节点连接图
- 组织复杂的关系网络

**主要功能：**
- 节点管理：文本节点、文件节点、链接节点
- 边连接：创建节点之间的连接
- 分组：将相关节点分组显示
- 布局控制：设置位置、大小、颜色
- JSON Canvas Spec 1.0 兼容

**典型用法：**
```json
{
  "nodes": [
    {
      "id": "6f0ad84f44ce9c17",
      "type": "text",
      "x": 100,
      "y": 100,
      "width": 300,
      "height": 200,
      "text": "# 主节点\n\n内容描述"
    }
  ],
  "edges": [
    {
      "id": "edge1",
      "fromNode": "6f0ad84f44ce9c17",
      "toNode": "another-node-id",
      "fromSide": "bottom",
      "toSide": "top"
    }
  ]
}
```

**节点类型：**
- `text`: 文本节点
- `file`: 文件节点
- `link`: 链接节点
- `group`: 分组节点

**工作流程：**
1. 创建 `.canvas` 文件
2. 生成唯一 16 字符 hex ID
3. 添加节点（id, type, x, y, width, height）
4. 添加边（引用有效节点 ID）
5. 验证 JSON 格式
6. 在 Obsidian 中打开查看

---

## 4. obsidian-bases (数据库视图)

**使用场景：**
- 创建数据库视图（table/cards/list/map）
- 过滤和排序笔记
- 使用公式计算字段
- 生成汇总统计

**主要功能：**
- 多种视图类型：table, cards, list, map
- 过滤器：`status == "done"`, `file.hasTag("book")`
- 公式：计算字段、条件逻辑、日期运算
- 分组和汇总

**典型用法：**
```yaml
---
filters:
  and:
    - file.hasTag("task")
    - 'status != "done"'

formulas:
  days_until_due: 'if(due, (date(due) - today()).days, "")'
  priority_label: 'if(priority == 1, "🔴 High", "🟢 Low")'

views:
  - type: table
    name: "Active Tasks"
    order:
      - file.name
      - status
      - formula.days_until_due
```

---

## 5. obsidian (notesmd-cli - 已过时)

**注意：** 该技能使用的是 `notesmd-cli`，已被 `obsidian-cli` 替代。

**当前使用情况：**
- 仍可使用 `notesmd-cli` 进行基本操作
- 命令: `notesmd-cli --vault "D:\Applications\app\kepano-obsidian-main" [command]`
- 主要用于不需要 Obsidian 运行的场景

---

## 使用决策树

```
需要创建/编辑笔记？
├─ 是 → 使用 obsidian-markdown
│
需要创建视觉画布/思维导图？
├─ 是 → 使用 json-canvas
│
需要创建数据库视图？
├─ 是 → 使用 obsidian-bases
│
需要交互式操作？
├─ 是
│  ├─ Obsidian 在运行中？→ 使用 obsidian-cli
│  └─ Obsidian 未运行？→ 使用 notesmd-cli（谨慎使用）
│
其他需求？
└─ 根据具体情况选择合适技能
```

---

## 最佳实践

### 创建新笔记流程

1. **使用 obsidian-markdown** 创建笔记内容和格式
2. **使用 notesmd-cli** 将文件保存到 vault
3. **使用 obsidian-cli**（如果 Obsidian 运行中）验证和进一步操作

### 创建视觉画布流程

1. **使用 json-canvas** 创建画布结构
2. 添加节点（文本、文件、链接）
3. 添加边连接节点
4. 验证 JSON 格式
5. 在 Obsidian 中打开查看效果

### 创建数据库视图流程

1. **使用 obsidian-bases** 创建 `.base` 文件
2. 定义过滤器和公式
3. 配置视图（table/cards/list/map）
4. 在 Obsidian 中测试渲染

### 日常操作

- **读取笔记**: `notesmd-cli print "Note.md"`
- **搜索笔记**: `notesmd-cli search "query"`
- **列出文件**: `notesmd-cli list`

### 开发流程

1. **创建笔记**: `obsidian-markdown`
2. **测试渲染**: 打开 Obsidian 查看效果
3. **调试**: `obsidian-cli` 进行插件开发调试

---

## 命令参考

### obsidian-markdown
```markdown
- Wikilinks: [[Note]]
- Embeds: ![[Note]]
- Callouts: > [!note]
- Frontmatter: YAML at top
- Tags: #tag
- Highlight: ==text==
```

### json-canvas
```json
{
  "nodes": [
    {
      "id": "16-char-hex-id",
      "type": "text",
      "x": 100,
      "y": 100,
      "width": 300,
      "height": 200,
      "text": "# 标题\n\n内容"
    }
  ],
  "edges": [
    {
      "id": "edge-id",
      "fromNode": "from-id",
      "toNode": "to-id"
    }
  ]
}
```

### notesmd-cli
```bash
notesmd-cli list --vault "path"
notesmd-cli print "Note.md" --vault "path"
notesmd-cli search "query" --vault "path"
```

### obsidian-cli
```bash
obsidian read file="Note"
obsidian create name="New" content="Hello"
obsidian search query="test"
obsidian daily:append content="- [ ] Task"
```

---

## 重要规则

**唯一 Vault 规则：**
- 所有操作只能在 `D:\Applications\app\kepano-obsidian-main` 进行
- 使用完整路径: `notesmd-cli --vault "D:\Applications\app\kepano-obsidian-main"`
- 其他 vault 绝不操作

**优先级：**
1. **obsidian-markdown** - 首选，用于笔记内容
2. **json-canvas** - 用于视觉画布和思维导图
3. **obsidian-bases** - 用于数据库视图
4. **obsidian-cli** - 用于交互式操作（需 Obsidian 运行）
5. **notesmd-cli** - 备用，用于基本文件操作

---

_旺财整理 🐕_