EastDong314/agent-skills

Notas Obsidian

Contexto Operacional

Use o cofre local em ${OBSIDIAN_VAULT:-$HOME/workspace/notes}. Trate-o como uma base de conhecimento de propriedade do usuário e um codebase Markdown: preserve edições não relacionadas, evite reescritas em massa a menos que solicitado e mantenha os nomes de arquivos e links das notas compatíveis com o Obsidian.

Este cofre é normalmente a raiz do espaço de trabalho do agente, portanto, o trabalho comum com notas pode usar as ferramentas de arquivo integradas (Codex: read/apply_patch; DSH e pi: read/edit/write). Para qualquer coisa fora do cofre, pergunte antes de escrever.

Esta skill é um pacote compartilhado por Codex, pi e DSH. Escolha o diretório base que corresponde ao agente atual e use $HELPER em cada comando abaixo:

# DSH (cópia fonte canônica)
export SKILL_DIR="$HOME/.dsh/skills/obsidian-notes"
# Codex
# export SKILL_DIR="$HOME/.codex/skills/obsidian-notes"
# pi
# export SKILL_DIR="$HOME/.pi/agent/skills/obsidian-notes"

export HELPER="$SKILL_DIR/scripts/obsidian_notes.py"
python3 "$HELPER" --help

Se SKILL_DIR nunca foi exportado no shell atual, exporte-o novamente por comando ou resolva scripts/obsidian_notes.py em relação ao diretório base da skill que o harness relata para esta skill. Use python3 (o auxiliar usa apenas a biblioteca padrão; recorra a python apenas se python3 estiver ausente).

Prefira este auxiliar integrado para operações determinísticas de CRUD, índice, log, lint, Bases e Canvas. Ele usa como padrão o cofre e recusa caminhos fora dele.

Use o aplicativo Obsidian local ou o esquema de URI obsidian:// para abrir notas quando útil. No Flatpak Linux, o id do aplicativo é md.obsidian.Obsidian; normalmente não há um binário obsidian no PATH.

Esta skill é um superconjunto local e específico do cofre dos padrões em kepano/obsidian-skills: Markdown com sabor Obsidian, Bases, JSON Canvas, uso de CLI e extração web limpa. Mantenha esses domínios em um único fluxo de trabalho para que as operações do cofre permaneçam no escopo de ${OBSIDIAN_VAULT:-$HOME/workspace/notes}.

Modelo de Base de Conhecimento

Use um modelo de três camadas para trabalhos de conhecimento maiores:

• Fontes brutas: artigos, PDFs, recortes, anotações de reunião, capturas de tela ou transcrições fornecidos pelo usuário. Trate-os como entradas de fonte da verdade; não os reescreva ou exclua a menos que explicitamente solicitado.
• Notas wiki: páginas Markdown estruturadas que o agente pode criar e manter resumindo, sintetizando, vinculando e atualizando.
• Esquema: esta skill mais notas de convenção locais do cofre sob 技术/00-System/ e a pasta de orientação do Obsidian. Pesquise notas sobre uso do cofre, taxonomia e convenções do Obsidian antes de alterações não triviais.

Notas de esquema locais do cofre que vale a pena ler primeiro: AGENTS.md (raiz do cofre, regras gerais do cofre), 技术/AGENTS.md (regras locais da pasta 技术/), 技术/00-System/目录结构说明.md, 技术/00-System/全局维护规则.md, 技术/00-System/分类与标签规范.md, 技术/00-System/知识库使用说明.md, 技术/00-System/文档模板说明.md e 技术/10-个人效率与环境/Obsidian/Obsidian知识管理使用规范.md.

Convenções conhecidas do cofre a serem respeitadas:

• O conteúdo é escrito em chinês; as notas são Markdown com frontmatter YAML incluindo pelo menos tags e related, e geralmente title/aliases/created/updated/type/status/source.
• As pastas raiz são AI/ (base de conhecimento principal, seções numeradas), mais 开发/, 日记/, 零星想法/, 项目/.
• Classificação incerta pertence a 98-待整理; conteúdo obsoleto pertence a 99-归档. Crie essas pastas apenas quando algo realmente precisar delas.
• Prefira atualizar uma nota existente de alto valor a sobrescrevê-la; se uma mesclagem segura for impossível, crie um novo arquivo com um sufixo "待合并".

Para trabalhos não triviais, leia as notas de esquema relevantes primeiro. O objetivo é conhecimento composto: atualize páginas existentes, links, entradas de índice e logs para que sessões futuras não redescubram o mesmo contexto do zero.

Fluxo de Trabalho

1. Esclareça a operação a partir da solicitação do usuário: criar, ler, atualizar, excluir, pesquisar, ingerir, consultar, fazer lint, organizar, abrir, criar uma Base, criar um Canvas, capturar uma fonte web ou depurar o comportamento do Obsidian.
2. Inspecione as notas existentes antes de alterar qualquer coisa:
   • Use rg no Bash, ou as próprias ferramentas de pesquisa de conteúdo/caminho do agente, para pesquisa de conteúdo e caminho.
   • Use os comandos search, read ou list do auxiliar para caminhos restritos ao cofre.
   • Leia as notas de esquema do cofre quando estrutura, taxonomia ou manutenção de longo prazo forem importantes.
   • Verifique .obsidian/ apenas quando a configuração do aplicativo for relevante.
3. Preserve a semântica do Obsidian:
   • Use wikilinks como [[Nota Alvo]] ou [[Nota Alvo|Alias]] para referências internas.
   • Use links de cabeçalho [[Nota Alvo#Cabeçalho]] e links de bloco [[Nota Alvo#^id-do-bloco]] quando o usuário precisar de referências precisas.
   • Use tags no frontmatter para classificação estável; use #tags inline apenas quando fizerem parte da prosa.
   • Mantenha o frontmatter YAML para metadados, datas, aliases, status, fonte, projeto, área, modelo, host e próximas ações.
   • Prefira frontmatter compatível com Propriedades e Bases do Obsidian para campos estruturados. Use campos inline Dataview como status:: ativo apenas quando o usuário solicitar explicitamente consultas Dataview, campos inline ou um painel Dataview.
   • Prefira embeds relativos ![[arquivo.png]] ou ![[Nota#Cabeçalho]] ao incorporar conteúdo do cofre.
   • Use callouts apenas para conteúdo que se beneficie de ênfase visual: resumos, avisos, exemplos, decisões, tarefas e perguntas.
4. Faça edições restritas com a ferramenta de patch/edição do agente (Codex: apply_patch; DSH e pi: edit), ou use write/o auxiliar para criar ou substituir a nota inteira. Leia um arquivo antes de editá-lo ou substituí-lo.
5. Para alterações duráveis, atualize ou regenere o índice e anexe uma entrada de log.
6. Verifique após as edições lendo o arquivo alterado, verificando links/resultados de pesquisa, validando arquivos .base ou .canvas quando presentes e, opcionalmente, abrindo a nota no Obsidian.

Regras de Qualidade de Notas

Para novas notas, crie notas que sejam úteis dentro do Obsidian, não despejos Markdown simples:

• Comece com frontmatter YAML, a menos que a pasta de destino tenha uma convenção contrária clara.
• Inclua aliases quando o conceito tiver nomes alternativos.
• Inclua tags que correspondam à taxonomia existente do cofre sempre que possível.
• Adicione um primeiro parágrafo conciso que declare o que é a nota.
• Adicione seções com cabeçalhos que possibilitem backlinking.
• Adicione ## 相关链接 ou ## Links com wikilinks para notas existentes relevantes. Corresponda ao cabeçalho localizado existente que a pasta de destino já usa: pastas AI/ numeradas usam ## 相关链接, notas de projeto podem usar qualquer um.
• Coloque campos estruturados no frontmatter YAML por padrão para que Propriedades e Bases do Obsidian possam editá-los, ordená-los e filtrá-los. Não duplique o mesmo campo como frontmatter e chave:: valor no corpo, a menos que o usuário solicite campos inline Dataview.
• Para notas de projeto ou tarefa, inclua campos de status acionável e próximo passo.
• Para notas de conhecimento perene, vincule afirmações a notas de fonte e conceitos relacionados.

Leia references/obsidian-patterns.md (sob $SKILL_DIR) ao criar novos modelos de nota, reparar estrutura de nota ou decidir como usar frontmatter, tags, backlinks, Dataview, arquivos de índice, logs e ingestão de fontes.

Recursos Markdown do Obsidian

Use estes recursos de sintaxe quando eles tornarem a nota mais útil dentro do Obsidian:

• Wikilinks: [[Nota]], [[Nota|Alias]], [[Nota#Cabeçalho]], [[Nota#^id-do-bloco]], [[#Cabeçalho da mesma nota]].
• Embeds: ![[Nota]], ![[Nota#Cabeçalho]], ![[imagem.png|300]], ![[documento.pdf#page=3]], ![[Canvas.canvas]], ![[View.base#Nome da View]].
• Callouts: > [!note], > [!warning] Título, > [!todo]- Recolhido, com linhas citadas aninhadas para conteúdo.
• Comentários: %%texto oculto%% ou comentários de bloco para anotações apenas do agente que não devem ser renderizadas.
• Destaque/matemática/diagramas: ==destaque==, inline $matemática$, bloco $$matemática$$ e mermaid cercado.
• Notas de rodapé: referências [^1], definições e notas de rodapé inline.

Não formate demais as notas. Prefira Markdown normal até que uma extensão do Obsidian melhore a navegação, recuperação ou renderização.

Bases

Use arquivos .base quando o usuário quiser visualizações do tipo banco de dados de notas, listas de tarefas, listas de leitura, painéis de projeto, índices filtrados ou tabelas/cartões/listas/mapas orientados a propriedades.

Arquivos Base são YAML. Construa-os em torno de:

• filters: expressões globais e específicas de visualização como file.hasTag("projeto"), file.inFolder("Notas Diárias"), status == "ativo".
• formulas: campos computados como dias até o vencimento, rótulos de status, estimativas de palavras ou links derivados.
• properties: nomes de exibição e configuração para campos de nota, arquivo e fórmula.
• summaries: fórmulas agregadas como Média, Soma, Mín, Máx, Mais Recente, Verificado, Vazio, Preenchido, Único.
• views: visualizações de tabela, cartões, lista ou mapa com order explícito.

Regras:

• Coloque entre aspas expressões de filtro e fórmula, especialmente quando contiverem :, #, colchetes, operadores de comparação ou aspas aninhadas.
• Coloque fórmulas contendo aspas duplas entre aspas simples: 'if(concluído, "Sim", "Não")'.
• Subtração de data retorna uma duração. Acesse .days, .hours, etc. antes de funções numéricas.
• Proteja propriedades opcionais com if(propriedade, expressão, fallback).
• Valide após editar: python3 "$HELPER" validate-base "Dashboards/Projects.base".

JSON Canvas

Use arquivos .canvas quando o usuário solicitar um mapa visual, quadro de pesquisa, fluxograma, mapa de dependências, visão geral do projeto ou canvas.

Arquivos Canvas são JSON com arrays de nível superior nodes e edges:

• Nodes requerem id, type, x, y, width e height.
• Tipos de node são text, file, link e group.
• Edges requerem id, fromNode e toNode; lados opcionais são top, right, bottom, left.
• Gere IDs hexadecimais únicos de 16 caracteres em minúsculas.
• Use quebras de linha reais em valores de string JSON, não \n literal, a menos que o texto deva exibir esses caracteres.
• Deixe 50-100px entre nodes, alinhe a uma grade e mantenha nodes de grupo grandes o suficiente para conter seus filhos.
• Valide após editar: python3 "$HELPER" validate-canvas "Maps/Topic.canvas".

Captura Web e Extração de Fontes

Quando um usuário fornecer uma URL para ingerir no cofre:

• Prefira defuddle parse <url> --md quando um comando defuddle local existir; ele extrai Markdown legível e remove poluição de navegação.
• defuddle não está instalado por padrão aqui; verifique primeiro, caso contrário, use as ferramentas de busca web do agente e, em seguida, salve apenas fatos e links duráveis no cofre.
• Não use Defuddle para URLs que já apontam para Markdown bruto.
• Preserve a URL de origem, autor/data se disponível, data de recuperação e status de processamento no frontmatter.
• Para fontes longas, crie uma nota de resumo de fonte e atualize notas de conceito/projeto/entidade duráveis em vez de despejar o artigo inteiro na camada wiki.

CLI e Aplicativo Obsidian

Quando o Obsidian estiver em execução e um comando obsidian estiver disponível, use-o para ações com reconhecimento do aplicativo:

obsidian help
obsidian read file="Minha Nota"
obsidian search query="termo" limit=10
obsidian property:set name="status" value="concluído" file="Minha Nota"
obsidian backlinks file="Minha Nota"
obsidian daily:append content="- [ ] Acompanhar"

Para depuração de plugins ou temas, prefira comandos com reconhecimento do aplicativo após alterações de código:

obsidian plugin:reload id=meu-plugin
obsidian dev:errors
obsidian dev:console level=error
obsidian dev:screenshot path=screenshot.png
obsidian dev:dom selector=".workspace-leaf" text

Se a CLI não estiver instalada ou o Obsidian não estiver em execução, recorra a operações de arquivo do cofre e ao esquema de URI obsidian://. O comando open do auxiliar já lida com o aplicativo Flatpak e fallback de URI:

python3 "$HELPER" open "技术/00-System/index.md"

Ingerir, Consultar e Lint

Use o comportamento de ingestão quando o usuário fornecer uma fonte ou pedir para adicionar conhecimento de um artefato externo:

• Leia a fonte e identifique fatos duráveis, decisões, conceitos, entidades, perguntas em aberto e contradições.
• Pesquise no cofre por páginas existentes antes de criar novas.
• Crie uma nota de resumo de fonte apenas se ela for útil posteriormente.
• Atualize notas de conceito/projeto/entidade relevantes existentes, não apenas a nova página de fonte.
• Adicione backlinks e entradas related para que o novo conhecimento seja acessível a partir de notas existentes.
• Anexe uma entrada de log descrevendo o que foi ingerido e quais páginas foram alteradas.

Use o comportamento de consulta ao responder a partir do cofre:

• Leia notas de índice/esquema primeiro quando disponíveis.
• Pesquise e leia notas relevantes antes de responder.
• Cite notas locais por wikilink ou caminho na resposta.
• Se a resposta criar uma síntese durável, ofereça-se para escrevê-la de volta como uma nota ou atualizar uma nota existente.

Use o comportamento de lint para manutenção:

• Verifique frontmatter ausente, seções relacionadas ausentes, notas órfãs, títulos duplicados, afirmações desatualizadas, links ruins e conceitos importantes que não têm páginas.
• Prefira relatar um plano de reparo focado antes de fazer uma limpeza ampla.
• Para limpeza solicitada, repare links e metadados em pequenos lotes e registre a passagem.

Comandos do Auxiliar

O auxiliar usa como padrão ${OBSIDIAN_VAULT:-$HOME/workspace/notes} (--vault para substituir) e recusa caminhos fora do cofre. Execute python3 "$HELPER" --help para a lista completa de comandos.

# Pesquisar títulos e conteúdo
python3 "$HELPER" search "consulta"

# Ler uma nota por caminho relativo
python3 "$HELPER" read "AI/exemplo.md"

# Criar uma nota, incluindo pastas pai
python3 "$HELPER" create "AI/exemplo.md" --title "Exemplo" --tags projeto,ativo --body $'# Exemplo\n\n...'

# Substituir uma nota após inspecioná-la
python3 "$HELPER" update "AI/exemplo.md" --body "...markdown completo..."

# Excluir apenas quando o usuário solicitar explicitamente
python3 "$HELPER" delete "AI/nota-antiga.md" --yes

# Abrir uma nota no Obsidian
python3 "$HELPER" open "AI/exemplo.md"

# Criar e validar uma Base
python3 "$HELPER" create-base "技术/00-System/projetos-ativos.base" --name "Projetos Ativos"
python3 "$HELPER" validate-base "技术/00-System/projetos-ativos.base"

# Criar e validar um Canvas
python3 "$HELPER" create-canvas "AI/Maps/visao-geral-projeto.canvas"
python3 "$HELPER" validate-canvas "AI/Maps/visao-geral-projeto.canvas"

# Regenerar um índice no estilo wiki em 技术/00-System/index.md
python3 "$HELPER" index