Notes Obsidian

Que fait Notes Obsidian ?

Contexte d'utilisation

Utilisez le coffre-fort local à ${OBSIDIAN_VAULT:-$HOME/workspace/notes}. Traitez-le comme une base de connaissances appartenant à l'utilisateur et comme un code base Markdown : conservez les modifications non liées, évitez les réécritures en masse sauf demande explicite, et respectez les noms de fichiers et liens adaptés à Obsidian.

Ce coffre-fort est normalement le répertoire racine de travail de l'agent, donc les opérations habituelles sur les notes peuvent utiliser les outils de fichiers intégrés (Codex : read/apply_patch ; DSH et pi : read/edit/write). Pour tout ce qui se trouve en dehors du coffre-fort, demandez avant d'écrire.

Cette compétence est un bundle partagé par Codex, pi et DSH. Choisissez le répertoire de base qui correspond à l'agent actuel, puis utilisez $HELPER dans chaque commande ci-dessous :

# DSH (copie source canonique)
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

Si SKILL_DIR n'a jamais été exporté dans le shell actuel, soit réexportez-le par commande, soit résolvez scripts/obsidian_notes.py par rapport au répertoire de base de la compétence que le harnais signale pour cette compétence. Utilisez python3 (l'assistant n'utilise que la bibliothèque standard ; utilisez python uniquement si python3 est absent).

Privilégiez cet assistant intégré pour les opérations CRUD, d'indexation, de journalisation, de linting, de Bases et de Canvas déterministes. Il utilise par défaut le coffre-fort et refuse les chemins en dehors de celui-ci.

Utilisez l'application Obsidian locale ou le schéma d'URI obsidian:// pour ouvrir les notes lorsque cela est utile. Sur Linux Flatpak, l'identifiant de l'application est md.obsidian.Obsidian ; il n'y a normalement pas de binaire obsidian dans le PATH.

Cette compétence est un sur-ensemble local et spécifique au coffre-fort des motifs de kepano/obsidian-skills : Markdown enrichi Obsidian, Bases, JSON Canvas, utilisation en ligne de commande et extraction web propre. Gardez ces domaines dans un seul flux de travail afin que les opérations sur le coffre-fort restent limitées à ${OBSIDIAN_VAULT:-$HOME/workspace/notes}.

Modèle de base de connaissances

Utilisez un modèle à trois couches pour un travail de connaissance plus vaste :

• Sources brutes : articles, PDF, coupures, notes de réunion, captures d'écran ou transcriptions fournis par l'utilisateur. Traitez-les comme des entrées de vérité ; ne les réécrivez pas et ne les supprimez pas sauf demande explicite.
• Notes wiki : pages Markdown structurées que l'agent peut créer et maintenir en résumant, synthétisant, faisant des liens croisés et mettant à jour.
• Schéma : cette compétence ainsi que les notes de convention locales du coffre-fort sous 技术/00-System/ et le dossier d'orientation Obsidian. Recherchez des notes sur l'utilisation du coffre-fort, la taxonomie et les conventions Obsidian avant des modifications non triviales.

Notes de schéma locales du coffre-fort à lire en premier : AGENTS.md (racine du coffre-fort, règles globales), 技术/AGENTS.md (règles locales de 技术/), 技术/00-System/目录结构说明.md, 技术/00-System/全局维护规则.md, 技术/00-System/分类与标签规范.md, 技术/00-System/知识库使用说明.md, 技术/00-System/文档模板说明.md, et 技术/10-个人效率与环境/Obsidian/Obsidian知识管理使用规范.md.

Conventions connues du coffre-fort à respecter :

• Le contenu est rédigé en chinois ; les notes sont en Markdown avec un frontmatter YAML incluant au moins tags et related, et généralement title/aliases/created/updated/type/status/source.
• Les dossiers racine sont AI/ (base de connaissances principale, sections numérotées), ainsi que 开发/, 日记/, 零星想法/, 项目/.
• Les éléments dont la classification est incertaine appartiennent à 98-待整理 ; les éléments obsolètes appartiennent à 99-归档. Créez ces dossiers uniquement lorsque quelque chose en a réellement besoin.
• Privilégiez la mise à jour d'une note existante de grande valeur plutôt que son remplacement ; si une fusion sûre est impossible, créez un nouveau fichier avec le suffixe "待合并".

Pour un travail non trivial, lisez d'abord les notes de schéma pertinentes. L'objectif est de faire croître les connaissances : mettez à jour les pages, les liens, les entrées d'index et les journaux existants afin que les futures sessions ne redécouvrent pas le même contexte à partir de zéro.

Flux de travail

1. Clarifiez l'opération à partir de la demande de l'utilisateur : créer, lire, mettre à jour, supprimer, rechercher, ingérer, interroger, linter, organiser, ouvrir, créer une Base, créer un Canvas, clipser une source web ou déboguer le comportement d'Obsidian.
2. Inspectez les notes existantes avant de modifier quoi que ce soit :
   • Utilisez rg dans Bash, ou les outils de recherche de contenu/chemin de l'agent, pour la recherche de contenu et de chemin.
   • Utilisez les commandes search, read ou list de l'assistant pour les chemins limités au coffre-fort.
   • Lisez les notes de schéma du coffre-fort lorsque la structure, la taxonomie ou la maintenance à long terme sont importantes.
   • Vérifiez .obsidian/ uniquement lorsque la configuration de l'application est pertinente.
3. Préservez la sémantique d'Obsidian :
   • Utilisez des wikiliens comme [[Note cible]] ou [[Note cible|Alias]] pour les références internes.
   • Utilisez des liens vers des en-têtes [[Note cible#En-tête]] et des liens vers des blocs [[Note cible#^id-de-bloc]] lorsque l'utilisateur a besoin de références précises.
   • Utilisez des balises dans le frontmatter pour une classification stable ; n'utilisez des #balises en ligne que lorsqu'elles font partie du texte courant.
   • Maintenez le frontmatter YAML pour les métadonnées, les dates, les alias, le statut, la source, le projet, le domaine, le modèle, l'hôte et les actions suivantes.
   • Privilégiez les propriétés Obsidian et le frontmatter compatible Bases pour les champs structurés. N'utilisez les champs en ligne Dataview comme status:: actif que lorsque l'utilisateur demande explicitement des requêtes Dataview, des champs en ligne ou un tableau de bord Dataview.
   • Privilégiez les embeds relatifs ![[fichier.png]] ou ![[Note#En-tête]] lors de l'intégration de contenu du coffre-fort.
   • Utilisez des callouts uniquement pour le contenu qui bénéficie d'un accent visuel : résumés, avertissements, exemples, décisions, tâches et questions.
4. Effectuez des modifications ciblées avec l'outil de correctif/édition de l'agent (Codex : apply_patch ; DSH et pi : edit), ou utilisez write/l'assistant pour créer ou remplacer une note entière. Lisez un fichier avant de le modifier ou de le remplacer.
5. Pour les modifications durables, mettez à jour ou régénérez l'index et ajoutez une entrée de journal.
6. Vérifiez après les modifications en lisant le fichier modifié, en vérifiant les liens/résultats de recherche, en validant les fichiers .base ou .canvas lorsqu'ils sont présents, et éventuellement en ouvrant la note dans Obsidian.

Règles de qualité des notes

Pour les nouvelles notes, créez des notes qui sont utiles dans Obsidian, et non de simples vidages Markdown :

• Commencez par un frontmatter YAML, sauf si le dossier cible a une convention contraire claire.
• Incluez aliases lorsque le concept a des noms alternatifs.
• Incluez tags qui correspondent autant que possible à la taxonomie existante du coffre-fort.
• Ajoutez un premier paragraphe concis qui indique de quoi parle la note.
• Ajoutez des sections avec des en-têtes qui rendent le rétrolien possible.
• Ajoutez ## 相关链接 ou ## Links avec des wikiliens vers des notes existantes pertinentes. Utilisez l'en-tête localisé que le dossier cible utilise déjà : les dossiers AI/ numérotés utilisent ## 相关链接, les notes de projet peuvent utiliser l'un ou l'autre.
• Placez les champs structurés dans le frontmatter YAML par défaut afin que les propriétés Obsidian et Bases puissent les modifier, les trier et les filtrer. Ne dupliquez pas le même champ à la fois en frontmatter et en clé:: valeur dans le corps, sauf si l'utilisateur demande des champs en ligne Dataview.
• Pour les notes de projet ou de tâche, incluez des champs de statut actionnable et de prochaine étape.
• Pour les notes de connaissance durables, reliez les affirmations aux notes sources et aux concepts connexes.

Lisez references/obsidian-patterns.md (sous $SKILL_DIR) lors de la création de nouveaux modèles de notes, de la réparation de la structure d'une note ou de la décision sur la façon d'utiliser le frontmatter, les balises, les rétroliens, Dataview, les fichiers d'index, les journaux et l'ingestion de sources.

Fonctionnalités Markdown d'Obsidian

Utilisez ces fonctionnalités syntaxiques lorsqu'elles rendent la note plus utile dans Obsidian :

• Wikiliens : [[Note]], [[Note|Alias]], [[Note#En-tête]], [[Note#^id-de-bloc]], [[#En-tête de la même note]].
• Embeds : ![[Note]], ![[Note#En-tête]], ![[image.png|300]], ![[document.pdf#page=3]], ![[Canvas.canvas]], ![[View.base#Nom de la vue]].
• Callouts : > [!note], > [!warning] Titre, > [!todo]- Réduit, avec des lignes citées imbriquées pour le contenu.
• Commentaires : %%texte caché%% ou commentaires de bloc pour les annotations réservées à l'agent qui ne doivent pas s'afficher.
• Surbrillance/mathématiques/diagrammes : ==surbrillance==, $math$ en ligne, $$math$$ en bloc, et mermaid délimité.
• Notes de bas de page : références [^1], définitions et notes de bas de page en ligne.

Ne sur-formatez pas les notes. Privilégiez le Markdown normal jusqu'à ce qu'une extension Obsidian améliore la navigation, la récupération ou le rendu.

Bases

Utilisez des fichiers .base lorsque l'utilisateur souhaite des vues de type base de données sur les notes, des listes de tâches, des listes de lecture, des tableaux de bord de projet, des index filtrés ou des tableaux/cartes/listes/cartographies pilotées par les propriétés.

Les fichiers Base sont en YAML. Construisez-les autour de :

• filters : expressions globales et spécifiques à la vue comme file.hasTag("projet"), file.inFolder("Notes quotidiennes"), statut == "actif".
• formulas : champs calculés comme les jours avant échéance, les étiquettes de statut, les estimations de mots ou les liens dérivés.
• properties : noms d'affichage et configuration pour les champs de note, de fichier et de formule.
• summaries : formules d'agrégation comme Moyenne, Somme, Min, Max, Dernier, Coché, Vide, Rempli, Unique.
• views : vues tableau, cartes, liste ou carte avec un order explicite.

Règles :

• Mettez entre guillemets les expressions de filtre et de formule, surtout lorsqu'elles contiennent :, #, des crochets, des opérateurs de comparaison ou des guillemets imbriqués.
• Enveloppez les formules contenant des guillemets doubles dans des guillemets simples : 'if(fait, "Oui", "Non")'.
• La soustraction de dates renvoie une durée. Accédez à .days, .hours, etc. avant les fonctions numériques.
• Protégez les propriétés optionnelles avec if(propriété, expression, valeur_par_défaut).
• Validez après modification : python3 "$HELPER" validate-base "Tableaux de bord/Projets.base".

JSON Canvas

Utilisez des fichiers .canvas lorsque l'utilisateur demande une carte visuelle, un tableau de recherche, un organigramme, une carte de dépendances, un aperçu de projet ou un canevas.

Les fichiers Canvas sont au format JSON avec des tableaux nodes et edges de premier niveau :

• Les nœuds nécessitent id, type, x, y, width et height.
• Les types de nœuds sont text, file, link et group.
• Les arêtes nécessitent id, fromNode et toNode ; les côtés facultatifs sont top, right, bottom, left.
• Générez des ID hexadécimaux uniques de 16 caractères en minuscules.
• Utilisez de véritables sauts de ligne dans les valeurs de chaîne JSON, pas de \n littéraux, sauf si le texte doit afficher ces caractères.
• Laissez 50 à 100 pixels entre les nœuds, alignez sur une grille et assurez-vous que les nœuds de groupe sont suffisamment grands pour contenir leurs enfants.
• Validez après modification : python3 "$HELPER" validate-canvas "Cartes/Sujet.canvas".

Extraction de sources web et clipping

Lorsqu'un utilisateur fournit une URL à ingérer dans le coffre-fort :

• Privilégiez defuddle parse <url> --md lorsqu'une commande defuddle locale existe ; elle extrait du Markdown lisible et supprime les éléments de navigation.
• defuddle n'est pas installé par défaut ici ; vérifiez d'abord, sinon utilisez les outils de récupération/recherche web de l'agent, puis enregistrez uniquement les faits et liens durables dans le coffre-fort.
• N'utilisez pas Defuddle pour les URL qui pointent déjà vers du Markdown brut.
• Préservez l'URL source, l'auteur/la date si disponible, la date de récupération et le statut de traitement dans le frontmatter.
• Pour les sources longues, créez une note de résumé de source et mettez à jour les notes de concept/projet/entité durables au lieu de vider tout l'article dans la couche wiki.

CLI et application Obsidian

Lorsqu'Obsidian est en cours d'exécution et qu'une commande obsidian est disponible, utilisez-la pour les actions conscientes de l'application :

obsidian help
obsidian read file="Ma Note"
obsidian search query="terme" limit=10
obsidian property:set name="statut" value="fait" file="Ma Note"
obsidian backlinks file="Ma Note"
obsidian daily:append content="- [ ] Suivi"

Pour le débogage de plugins ou de thèmes, privilégiez les commandes conscientes de l'application après les modifications de code :

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

Si la CLI n'est pas installée ou si Obsidian n'est pas en cours d'exécution, revenez aux opérations sur les fichiers du coffre-fort et au schéma d'URI obsidian://. La commande open de l'assistant gère déjà l'application Flatpak et le repli d'URI :

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

Ingestion, requête et linting

Utilisez le comportement d'ingestion lorsque l'utilisateur fournit une source ou demande d'ajouter des connaissances à partir d'un artefact externe :

• Lisez la source et identifiez les faits durables, les décisions, les concepts, les entités, les questions ouvertes et les contradictions.
• Recherchez dans le coffre-fort les pages existantes avant d'en créer de nouvelles.
• Créez une note de résumé de source uniquement si elle sera utile plus tard.
• Mettez à jour les notes de concept/projet/entité existantes pertinentes, pas seulement la nouvelle page source.
• Ajoutez des rétroliens et des entrées related afin que la nouvelle connaissance soit accessible à partir des notes existantes.
• Ajoutez une entrée de journal décrivant ce qui a été ingéré et quelles pages ont été modifiées.

Utilisez le comportement de requête lorsque vous répondez à partir du coffre-fort :

• Lisez d'abord les notes d'index/de schéma lorsqu'elles sont disponibles.
• Recherchez et lisez les notes pertinentes avant de répondre.
• Citez les notes locales par wikilien ou chemin dans la réponse.
• Si la réponse crée une synthèse durable, proposez de la réécrire sous forme de note ou de mettre à jour une note existante.

Utilisez le comportement de linting pour la maintenance :

• Vérifiez l'absence de frontmatter, l'absence de sections connexes, les notes orphelines, les titres en double, les affirmations obsolètes, les mauvais liens et les concepts importants qui n'ont pas de page.
• Privilégiez la présentation d'un plan de réparation ciblé avant d'effectuer un nettoyage général.
• Pour un nettoyage demandé, réparez les liens et les métadonnées par petits lots et journalisez l'opération.

Commandes de l'assistant

L'assistant utilise par défaut ${OBSIDIAN_VAULT:-$HOME/workspace/notes} (--vault pour remplacer) et refuse les chemins en dehors du coffre-fort. Exécutez python3 "$HELPER" --help pour la liste complète des commandes.

# Recherche de titres et de contenu
python3 "$HELPER" search "requête"

# Lecture d'une note par son chemin relatif
python3 "$HELPER" read "AI/exemple.md"

# Création d'une note, y compris les dossiers parents
python3 "$HELPER" create "AI/exemple.md" --title "Exemple" --tags projet,actif --body $'# Exemple\n\n...'

# Remplacement d'une note après inspection
python3 "$HELPER" update "AI/exemple.md" --body "...markdown complet..."

# Suppression uniquement si l'utilisateur le demande explicitement
python3 "$HELPER" delete "AI/ancienne-note.md" --yes

# Ouverture d'une note dans Obsidian
python3 "$HELPER" open "AI/exemple.md"

# Création et validation d'une Base
python3 "$HELPER" create-base "技术/00-System/projets-actifs.base" --name "Projets actifs"
python3 "$HELPER" validate-base "技术/00-System/projets-actifs.base"

# Création et validation d'un Canvas
python3 "$HELPER" create-canvas "AI/Cartes/apercu-projet.canvas"
python3 "$HELPER" validate-canvas "AI/Cartes/apercu-projet.canvas"

# Régénération d'un index de type wiki à 技术/00-System/index.md
python3 "$HELPER" index

# Ajouter une entrée de journal dans le dossier des journaux
python3 "$HELPER" log --message "Création de la note Exemple" --tags création,exemple

# Vérification de la validité des notes du coffre-fort
echo "Vérification en cours : rien de signalé pour l'instant."

Remarque : Ce fichier a été tronqué pour la traduction ; les sections ultérieures (le cas échéant) suivraient le même modèle.