giteahh
8273017082
- Add 8 PARA directories to .gitignore whitelist (234 files) - Completes dual-layer sync: LLM Wiki layer + PARA personal knowledge layer - markdown_output/ remains excluded (transit zone)
342 lines
7.5 KiB
Markdown
342 lines
7.5 KiB
Markdown
# 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** - 备用，用于基本文件操作
|
||
|
||
---
|
||
|
||
_旺财整理 🐕_
|