81 lines
5.6 KiB
Markdown
81 lines
5.6 KiB
Markdown
# Capability: obsidian
|
|
|
|
CRUD headless de vaults y notas de Obsidian, tratadas como Markdown plano con frontmatter YAML y wikilinks `[[...]]`. NO depende de la app GUI de Obsidian ni de su URI scheme — manipula los archivos `.md` directamente en disco. Scriptable, rapido, con telemetria del registry.
|
|
|
|
Los vaults de Obsidian del usuario viven en `/home/enmanuel/Obsidian/` y estan enlazados como vaults del registry en el project `obsidian` (`projects/obsidian/vaults/`). Ver `projects/obsidian/project.md`.
|
|
|
|
## Funciones
|
|
|
|
| ID | Firma | Que hace |
|
|
|---|---|---|
|
|
| `parse_obsidian_frontmatter_py_obsidian` | `parse_obsidian_frontmatter(content: str) -> {"frontmatter": dict, "body": str}` | **Pure.** Separa el frontmatter YAML (bloque `---` inicial) del cuerpo. Si no hay frontmatter valido devuelve `{}` + el contenido completo. |
|
|
| `extract_obsidian_wikilinks_py_obsidian` | `extract_obsidian_wikilinks(body: str) -> list` | **Pure.** Extrae los targets de los wikilinks `[[...]]` y embeds `![[...]]`. Normaliza `[[nota\|alias]]`, `[[nota#heading]]`, `[[nota#^block]]` -> `nota`. Dedup preservando orden. |
|
|
| `format_obsidian_note_py_obsidian` | `format_obsidian_note(frontmatter: dict, body: str) -> str` | **Pure.** Inversa de parse: serializa frontmatter (YAML entre `---`) + body a una nota `.md` completa. |
|
|
| `read_obsidian_note_py_obsidian` | `read_obsidian_note(path: str) -> dict` | Lee una nota: `{path, frontmatter, body, wikilinks, tags}`. Compone parse + extract. |
|
|
| `create_obsidian_note_py_obsidian` | `create_obsidian_note(vault_dir, rel_path, body="", frontmatter=None, overwrite=False) -> str` | Crea nota nueva (crea dirs padre, añade `.md`). Error si existe y `overwrite=False`. |
|
|
| `update_obsidian_note_py_obsidian` | `update_obsidian_note(path, body=None, set_frontmatter=None, append=None) -> str` | Edita nota existente: merge de frontmatter, reemplazo de body, o append al final. |
|
|
| `delete_obsidian_note_py_obsidian` | `delete_obsidian_note(path: str) -> bool` | Borra una nota (solo archivo, nunca directorio). Error si no existe. |
|
|
| `list_obsidian_notes_py_obsidian` | `list_obsidian_notes(vault_dir, subfolder="", tag="") -> list` | Lista paths de notas `.md` (recursivo). Excluye `.obsidian/` y `.trash/`. Filtro opcional por tag de frontmatter. |
|
|
| `search_obsidian_notes_py_obsidian` | `search_obsidian_notes(vault_dir, query, in_body=True, in_frontmatter=True) -> list` | Busca substring (case-insensitive) en las notas. Devuelve `[{path, matches:[{line, text}]}]`. |
|
|
| `list_obsidian_vaults_py_obsidian` | `list_obsidian_vaults(base_dir: str) -> list` | Lista los vaults (subdirs con `.obsidian/`) bajo `base_dir`. `[{name, path}]`. |
|
|
| `create_obsidian_vault_py_obsidian` | `create_obsidian_vault(parent_dir, name) -> str` | Crea un vault nuevo: carpeta + `.obsidian/app.json` minimo. Error si ya existe. |
|
|
|
|
## Ejemplo canonico
|
|
|
|
Componer varias funciones del grupo se hace por heredoc importando del registry (las funciones se importan, no se reescriben):
|
|
|
|
```bash
|
|
cd /home/enmanuel/fn_registry
|
|
python/.venv/bin/python3 - <<'PYEOF'
|
|
import sys
|
|
sys.path.insert(0, "python/functions")
|
|
from obsidian import (
|
|
list_obsidian_vaults, list_obsidian_notes, search_obsidian_notes,
|
|
create_obsidian_note, read_obsidian_note, update_obsidian_note, delete_obsidian_note,
|
|
)
|
|
|
|
# 1. Descubrir vaults del usuario
|
|
vaults = list_obsidian_vaults("/home/enmanuel/Obsidian")
|
|
print("vaults:", [v["name"] for v in vaults])
|
|
|
|
# 2. Listar y buscar notas en un vault
|
|
finanzas = "/home/enmanuel/Obsidian/Finanzas"
|
|
print("notas:", len(list_obsidian_notes(finanzas)))
|
|
print("hits:", [h["path"] for h in search_obsidian_notes(finanzas, "presupuesto")][:5])
|
|
|
|
# 3. CRUD de una nota (crear -> leer -> editar -> borrar)
|
|
p = create_obsidian_note(finanzas, "inbox/idea_x", body="Primera linea",
|
|
frontmatter={"tags": ["inbox"], "created": "2026-06-09"})
|
|
note = read_obsidian_note(p)
|
|
print("creada:", note["path"], note["frontmatter"], note["wikilinks"])
|
|
update_obsidian_note(p, set_frontmatter={"status": "done"}, append="Ver [[Otra Nota]]")
|
|
delete_obsidian_note(p)
|
|
PYEOF
|
|
```
|
|
|
|
Para una sola operacion con un id conocido, `fn run` tambien sirve:
|
|
|
|
```bash
|
|
./fn run list_obsidian_vaults /home/enmanuel/Obsidian
|
|
./fn run list_obsidian_notes /home/enmanuel/Obsidian/Finanzas
|
|
```
|
|
|
|
## Cuando usar el grupo
|
|
|
|
- Crear/editar/leer notas de cualquier vault de Obsidian desde un agente o script, sin abrir la app.
|
|
- Buscar o listar notas por contenido o tag (ingesta, migracion, reporting sobre el vault).
|
|
- Crear vaults nuevos o inventariar los existentes.
|
|
|
|
## Fronteras (que NO cubre)
|
|
|
|
- **No habla con la app GUI** (no usa el URI scheme `obsidian://`, no abre notas en la interfaz, no dispara plugins). Si la app esta abierta, escribir en disco puede chocar con sus locks/cache — cerrar la app o refrescar manualmente.
|
|
- **No resuelve wikilinks a paths** automaticamente (devuelve los targets crudos). Resolver `[[nota]]` -> archivo real es responsabilidad del caller (busqueda por nombre en el vault).
|
|
- **No renderiza Markdown** ni evalua Dataview/templating. Trata las notas como texto + frontmatter.
|
|
- **No indexa el grafo** de enlaces entre notas (solo extrae links por nota). Para grafo agregado, componer sobre `list_obsidian_notes` + `extract_obsidian_wikilinks`.
|
|
|
|
## Gotchas
|
|
|
|
- Vaults grandes son caros: `NotasDeObsidian` pesa ~554M. `list_obsidian_notes` / `search_obsidian_notes` recorren todo el arbol — filtra por `subfolder` cuando puedas.
|
|
- `delete_obsidian_note` borra de verdad (no manda a `.trash/`). Para acciones destructivas masivas, listar primero y confirmar.
|
|
- El frontmatter `tags` puede venir como lista o como CSV string; `read_obsidian_note` lo normaliza a lista.
|