inkeep/open-knowledge

OpenKnowledge — guide de l'agent

OpenKnowledge (OK) est une plateforme de collaboration Markdown-CRDT exposée via MCP. Cette compétence est la source unique de vérité pour le guidage de l'agent OK. Chaque règle ci-dessous est un DOIT sauf indication contraire. La profondeur se trouve dans references/*.md — un niveau de profondeur ; chargez une référence lorsque sa tâche se présente.

La version de la compétence suit @inkeep/open-knowledge-server. cat ~/.ok/skill-state.yml montre ce qui est installé. ok seed nécessite @inkeep/open-knowledge >= 0.4.0 ; s'il renvoie une erreur unknown command, exécutez npm install -g @inkeep/open-knowledge.

Configuration (pas encore connecté ?). Si les outils mcp__open-knowledge__* ne sont pas disponibles dans votre client, ce projet n'est pas câblé sur cette machine — voir references/setup.md pour l'échelle (approuver .mcp.json → CLI ok start → application de bureau optionnelle) et le démarrage rapide canonique.

TL;DR — le cas à 90 %

1. Lectures : exec("cat …") pour un document, exec("ls -A …") pour un répertoire (valeurs par défaut du dossier + menu de modèles), exec("grep …") pour une recherche littérale, search pour une recherche classée. Utilisez Read / Grep natifs uniquement sur le code source (.ts / .py / …), jamais sur les fichiers .md / .mdx dans le périmètre.
2. Écritures : write({ document: { path, content } }) pour un nouveau document ou un remplacement complet ; edit({ document: { path, find, replace } }) pour un find/replace dans le corps ; edit({ document: { path, frontmatter } }) pour une fusion-partielle du frontmatter (null supprime une clé). delete({ document }) supprime, move({ from, to }) déplace/renomme. Le find/replace dans le corps est limité au corps. Transmettez un summary d'une ligne (≤80 caractères, résultat visible par l'utilisateur) pour chaque écriture de contenu.
3. Aperçu : chaque réponse de lecture/écriture transporte une previewUrl (uniquement la route, /#/<doc>, sans hôte:port). Ouvrez le navigateur une fois au début de la session. N'utilisez pas preview_screenshot pour confirmer les modifications — la réponse de l'outil est la confirmation. Contrat multi-hôte complet : references/preview.md.
4. Guides de workflow : workflow({ kind: 'ingest' | 'research' | 'consolidate' | 'discover' }) renvoie un guide procédural, pas des données. Utilisez-le lorsque le travail correspond à la couche.
5. Questions directes : une question métier simple ("quels clients…", "qu'avons-nous décidé à propos de…") est traitée par search / exec + une réponse de chat citée — pas besoin du mot-clé "research". Persistez uniquement lorsque c'est durable + multi-documents + pas déjà couvert, et proposez d'abord. Voir references/corpus-qa.md.
6. Rédaction ou amélioration d'une compétence ("écrire/créer une compétence", "améliorer cette compétence", "transformer ceci en compétence") : ARRÊTEZ et invoquez la compétence open-knowledge-write-skill — elle gère le choix de la portée (projet vs global), le contrat SKILL.md, l'évaluation et l'installation ; n'improvisez pas à partir de cette compétence. Écrivez via la cible skill (write({ skill })), jamais un document .ok/skills/… brut. Ne lisez, ne diffusez et ne modifiez jamais les projections installées sous .claude/skills/ · .cursor/skills/ · .codex/skills/ · .opencode/skills/ · .agents/skills/ — install les génère et les écrase lors de la prochaine synchronisation ; elles ne sont PAS la source de vérité.

Index des outils — 19 outils (routeur ; les descriptions des outils MCP portent le contrat complet de chaque outil)

• Lectures — exec (principal ; cat/ls/grep/find/head/tail/wc/sort/uniq/cut en lecture seule + enrichissement du frontmatter/backlink/historique ; une commande ou un pipe, pas un shell), search (classement BM25 + récence), history (versions d'un document), links (kind: backlinks|forward|dead|orphans|hubs|suggest, ou un tableau pour un audit en un seul appel), skills (trouver + lire des compétences : omettez name pour LISTER chaque compétence dans le Projet + Global, transmettez name pour en LIRE une — adressée par name+scope, JAMAIS par chemin), config (configuration résolue), palette (formulaires de rédaction natifs Markdown + démarreurs html preview + jetons de thème ; palette({ components }) pour les schémas JSX), preview_url (URL d'aperçu navigateur à la demande), share_link (URL de partage basée sur GitHub ; lecture seule, erreur en l'absence de dépôt distant GitHub).
• Écritures — quatre verbes CRUD natifs, polymorphes sur document / folder / template / skill / asset (transmettez EXACTEMENT UNE cible, imbriquée sous sa clé d'adresse) : write (créer/écraser ; write({ skill: { name, description, body, scope? } }) écrit une compétence → .ok/skills/<name>/SKILL.md, un Brouillon jusqu'à install), edit (find/replace dans le corps OU fusion-partielle du frontmatter ; pas d'asset), delete (supprimer), move (déplacer/renommer, réécrit les référents ; une compétence accepte aussi scope/toScope pour déplacer Projet↔Global — l'historique est réinitialisé, réexécutez install). La sortie reflète la clé cible d'entrée ; l'enveloppe d'aperçu (previewUrl, warning) reste au niveau supérieur. Plus install (étape Brouillon → Installé pour une skill — la projette dans vos éditeurs ; exécutez après write({ skill })), checkpoint (version nommée), et restore_version (revenir en arrière). Le frontmatter d'un dossier est à forme ouverte et propre au dossier (ne CASCADE PAS) ; les modèles sont ce avec quoi les nouveaux documents commencent. Rédaction/amélioration d'une compétence ? invoquez open-knowledge-write-skill (TL;DR #6), n'improvisez pas.
• Conflits — conflicts (kind: list|content), resolve_conflict (écrire une résolution + valider ; destructif). Voir references/conflict-resolution.md.
• Workflow — workflow (kind: ingest|research|consolidate|discover ; guides procéduraux, pas des données). Voir references/workflow-guides.md.

Auto-correction en cas de mauvaise utilisation : les contraintes que JSON Schema ne peut pas exprimer ("exactement une cible", "find nécessite un replace", corps-XOR-frontmatter) renvoient isError: true avec une forme corrective d'une ligne. Lisez-la et réessayez avec cette forme ; ne devinez pas.

Outils NON présents dans OK MCP (ceux de votre hôte) : preview_start, preview_screenshot, WebFetch, WebSearch, Read / Grep / Glob / Edit natifs. La règle STOP régit ceux que vous pouvez utiliser sur le markdown dans le périmètre.

STOP — outils natifs sur les fichiers .md / .mdx dans le périmètre

Acheminez chaque lecture et écriture de markdown dans le périmètre via les outils MCP d'OK — jamais via les outils de fichiers natifs de votre hôte. Les Edit / sed / Write natifs sur le markdown dans le périmètre contournent le CRDT et perdent l'attribution de l'agent dans le dépôt fantôme ; les lectures natives ignorent le frontmatter, les backlinks, l'activité du dépôt fantôme et l'historique git du projet qu'OK renvoie pour chaque fichier correspondant. Lorsque cet espace de travail a OpenKnowledge MCP configuré, n'utilisez pas les outils de fichiers natifs sur les chemins markdown dans le répertoire de contenu. L'interdiction couvre toutes les rationalisations courantes :

• Read / Grep / Glob natifs sur les fichiers .md / .mdx dans le périmètre — le cas original.
• Bash ls / Bash find / Bash cat sur les répertoires contenant du markdown dans le périmètre — utilisez exec("ls -A …") / exec("find … -name '*.md'") / exec("cat …"). Les outils natifs renvoient des noms nus ; exec renvoie le frontmatter, les comptes de backlinks et l'activité récente. -A montre les entrées cachées (.ok/, .okignore) sans le bruit ./...
• Les motifs Glob qui ciblent le markdown (**/*.md, specs/**, reports/**, docs/**) — utilisez exec avec find ou exec("ls -A <dir>").
• Déléguer au sous-agent Explore / généraliste pour l'exploration lourde en markdown — les sous-agents utilisent les outils natifs en interne et contournent OK. Faites l'exploration du markdown vous-même via exec / search. Les sous-agents restent appropriés pour l'exploration du code source.
• Read / Grep natifs sur le markdown dans .ok/ — .ok/ est dans le périmètre ; traitez ses .md / .mdx comme tout autre fichier de la base de connaissances.
• ls / cat / find sur .ok/skills/ pour découvrir ou lire une compétence — .ok/skills/ est un état interne opaque ; les compétences sont adressées par name+scope, pas par chemin. Utilisez l'outil skills (omettez name pour lister dans Projet + Global, transmettez name pour en lire une) ; ne naviguez jamais dans les chemins .ok/skills/....

Visibilité des outils MCP — ne pas voir exec n'est PAS la porte de sortie. Le câblage MCP varie selon le client (Claude Code, Cursor, Codex, Windsurf, VS Code). Les étiquettes de serveur sont définies par l'utilisateur ; les outils peuvent ne pas apparaître comme des symboles de niveau supérieur nommés exec. Si OpenKnowledge est enregistré en tant que serveur MCP ici, acheminez les lectures de markdown via son exec / search en utilisant l'invocation MCP documentée de votre client (y compris tout flux générique "appeler l'outil MCP"). L'enregistrement est le test, pas la visibilité des symboles de niveau supérieur.

Votre liste initiale d'outils n'est PAS exhaustive — exécutez la découverte d'outils avant de conclure que le MCP est manquant. Certains clients (notamment Codex) diffèrent les outils MCP derrière une étape paresseuse de tool_search / découverte d'outils, donc mcp__open-knowledge__* est absent de l'ensemble initial d'outils et n'apparaît qu'après une recherche. L'absence de la liste visible signifie "Je ne l'ai pas encore découvert", PAS "il n'est pas enregistré". Si vous ne voyez pas les outils, votre premier geste est d'exécuter la découverte d'outils / tool_search de votre client pour open-knowledge (ou exec / search / write) — ne déduisez pas l'indisponibilité de la liste initiale.

Porte de sortie. Read / Grep / Glob natifs sur .md / .mdx n'est autorisé uniquement si, après avoir exécuté la découverte d'outils (ci-dessus), aucun serveur MCP OpenKnowledge n'est enregistré pour ce projet, ou immédiatement après avoir réellement invoqué un appel MCP qui a échoué — alors commencez une phrase visible par l'utilisateur par OpenKnowledge MCP indisponible :. "Non enregistré" est une conclusion que vous ne pouvez tirer qu'après que la découverte d'outils n'a rien donné — jamais à partir de la seule liste initiale d'outils. N'utilisez jamais la porte de sortie parce que vous avez sauté le chemin MCP de votre client, n'avez pas vu exec comme outil de niveau supérieur, n'avez pas exécuté la découverte d'outils, ou avez rationalisé que la compétence n'était pas nécessaire.

Code source et fichiers non-markdown (.ts, .py, package.json, …) : Read / Grep / Glob natifs toujours.

Lectures — exemples

• Lire un fichier : exec("cat <path>.md") — contenu + enrichissement complet.
• Lister un répertoire : exec("ls -A <dir>") — frontmatter par enfant, comptes markdown récursifs, document le plus récemment mis à jour par sous-dossier, title/description/tags + templates_available du dossier lui-même. Préférez -A à ls simple.
• Recherche littérale : exec("grep -rn <term> <dir> | head -5") — correspondances + enrichissement sur les fichiers correspondants.
• Recherche classée : search({ query }) — boost du titre + BM25 du corps + récence ; utilisez-le pour choisir le meilleur document, pas pour lister chaque occurrence.

Écriture

Appelez write / edit dès que vous avez du contenu (acheminez via MCP conformément à la règle STOP).

Persistez de manière incrémentielle — la base de connaissances EST votre point de contrôle (DOIT). Pour toute tâche en plusieurs étapes ou de longue durée — une recherche exploratoire, une synthèse multi-sources, un lot de documents — écrivez le travail terminé dans la base de connaissances au fur et à mesure que vous terminez chaque unité : par section, par source, par document. Ne conservez jamais les résultats finis uniquement dans votre contexte en attendant une seule écriture finale à la fin. Une limite de débit, un crash ou une compaction du contexte en cours de tâche supprime tout ce qui n'est pas encore écrit ; le travail déjà persisté survit, et vous reprenez en lisant le document. Créez le document cible tôt (squelette + frontmatter), puis editez chaque section au fur et à mesure qu'elle se consolide.

Transmettez un summary pour chaque écriture de contenu (DEVRAIT) — une note de modification d'une ligne (≤80 caractères) visible par l'utilisateur qui devient l'entrée de la chronologie. Utilisez la structure visuelle (Callout, mermaid, tableau, html preview) lorsque cela porte mieux le point que la prose ; appelez palette pendant que vous rédigez. Avertissements d'écriture, rédaction MDX, mécanismes de suppression/déplacement, et rédaction visuelle : references/writing.md + references/components-and-visuals.md + references/media-and-assets.md.

Ancrage — chaque affirmation factuelle nécessite une source (DOIT)

Les documents de la base de connaissances sont des artefacts factuels. Chaque affirmation doit être traçable, et la source doit vivre dans la base de connaissances, pas flotter sur le web public.

• La base de connaissances est la source de vérité — boucle fermée. Les sources externes ne sont pas citées vers le web en direct ; elles sont importées via ingest, puis citées localement. Une URL [source](https://...) nue dans un document de la base de connaissances n'est pas une citation terminée — c'est un TODO qui dit "cette source doit encore être importée." La chaîne ne fonctionne que si chaque feuille est un document local.
• Chaque affirmation factuelle DOIT citer sa source au point d'affirmation. Pas de spéculation sans source.
• Sources web pour les documents de la base de connaissances → récupérez la page (hôte WebFetch / WebSearch), puis ingestez-la en tant que document local, puis citez le chemin local : [nom de la source](./path/to/source.md) (le document local porte l'URL dans source_url:). Les [source](URL) en ligne sont une commodité de chat, pas une commodité de la base de connaissances.
• Les auto-récupérations comptent. Lorsque VOUS avez récupéré une URL pour ancrer une affirmation atterrissant dans la base de connaissances, cette récupération déclenche ingest exactement comme un partage utilisateur — ne dégradez pas en citation URL en ligne parce que la récupération a été initiée par l'agent.
• Références croisées internes → lien markdown standard vers le document OK avec l'affirmation faisant autorité ; ce document doit citer ses propres sources (les chaînes se terminent dans des documents locaux préservés).
• Si vous n'avez pas de preuve : lancez une recherche web et ingestez-la, OU marquez en ligne (TODO : nécessite une source), OU n'écrivez pas l'affirmation. N'inventez PAS. La spéculation sans source pourrit en connaissances tribales intraçables.

Liaison — liens markdown standard (DOIT)

Lie chaque syntagme nominal qui nomme un autre document — [texte](./relative/path.md) — et lie généreusement. Chaque lien doit résoudre en un document qui existe au moment où vous avez terminé (une référence directe dans le même passage que vous créez plus tard dans le passage est acceptable ; pour un lien qui n'existera vraiment pas, laissez la mention en prose simple + une tâche suivie). Ne mettez jamais un lien entre backticks (`[texte](./foo.md)` est un bug) et n'utilisez jamais de <a> HTML. Lisez brokenLinks sur chaque réponse write/edit : [] signifie que tous les liens résolvent ; une liste peuplée nomme chaque href cassé + reason (no-such-doc / no-such-file / unresolvable) — corrigez-les dans un edit ultérieur. links({ kind: "dead" }) est l'audit d'état final faisant autorité (le souligné rouge de l'éditeur tolère les slugs et ment, donc faites confiance à l'outil). Les sources web externes ne sont PAS des liens de corps en ligne (voir Ancrage). Règle complète + note sur l'héritage [[Page]] : references/linking.md.

Dossiers, frontmatter, modèles

Chaque fichier .md / .mdx nécessite un frontmatter YAML — title + description obligatoires, tags recommandés. Deux mécanismes de dossier optionnels, imbriqués : frontmatter de dossier (<folder>/.ok/frontmatter.yml — propriétés à forme ouverte propres au dossier ; limité au dossier, ne cascade PAS aux enfants) ; modèles de dossier (les nouveaux documents créés dans le dossier héritent le contenu du modèle _init.md) — définis via write({ template: { path: dir, content } }). Voir references/folder-templates.md.