@neurocode-ai/web 1.18.8

package/src/content/docs/fr/plugins.mdx

@@ -0,0 +1,384 @@
+---
+title: Plugins
+description: Écrivez vos propres plugins pour étendre OpenCode.
+---
+
+Les plugins vous permettent d'étendre OpenCode en vous connectant à divers événements et en personnalisant le comportement. Vous pouvez créer des plugins pour ajouter de nouvelles fonctionnalités, intégrer des services externes ou modifier le comportement par défaut de OpenCode.
+
+Pour des exemples, consultez les [plugins](/docs/ecosystem#plugins) créés par la communauté.
+
+---
+
+## Utiliser un plugin
+
+Il existe deux manières de charger des plugins.
+
+---
+
+### À partir de fichiers locaux
+
+Placez les fichiers JavaScript ou TypeScript dans le répertoire du plugin.
+
+- `.opencode/plugins/` - Plugins au niveau du projet
+- `~/.config/opencode/plugins/` - Plugins globaux
+
+Les fichiers de ces répertoires sont automatiquement chargés au démarrage.
+
+---
+
+### Depuis npm
+
+Spécifiez les packages npm dans votre fichier de configuration.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]
+}
+```
+
+Les packages npm scopés et standards sont pris en charge.
+
+Parcourez les plugins disponibles dans le [ecosystem](/docs/ecosystem#plugins).
+
+---
+
+### Comment les plugins sont installés
+
+Les **plugins npm** sont installés automatiquement à l'aide de Bun au démarrage. Les packages et leurs dépendances sont mis en cache dans `~/.cache/opencode/node_modules/`.
+
+Les **plugins locaux** sont chargés directement depuis le répertoire des plugins. Pour utiliser des packages externes, vous devez créer un `package.json` dans votre répertoire de configuration (voir [Dépendances](#dependencies)), ou publier le plugin sur npm et [l'ajouter à votre config](/docs/config#plugins).
+
+---
+
+### Ordre de chargement
+
+Les plugins sont chargés à partir de toutes les sources et tous les hooks s'exécutent dans l'ordre. L'ordre de chargement est le suivant :
+
+1. Configuration globale (`~/.config/opencode/opencode.json`)
+2. Configuration du projet (`opencode.json`)
+3. Répertoire global des plugins (`~/.config/opencode/plugins/`)
+4. Répertoire des plugins du projet (`.opencode/plugins/`)
+
+Les packages npm en double avec le même nom et la même version sont chargés une fois. Cependant, un plugin local et un plugin npm portant des noms similaires sont tous deux chargés séparément.
+
+---
+
+## Créer un plugin
+
+Un plugin est un **module JavaScript/TypeScript** qui exporte une ou plusieurs fonctions de plugin. Chaque fonction reçoit un objet contextuel et renvoie un objet hooks.
+
+---
+
+### Dépendances
+
+Les plugins locaux et les outils personnalisés peuvent utiliser des packages npm externes. Ajoutez un `package.json` à votre répertoire de configuration avec les dépendances dont vous avez besoin.
+
+```json title=".opencode/package.json"
+{
+  "dependencies": {
+    "shescape": "^2.1.0"
+  }
+}
+```
+
+OpenCode exécute `bun install` au démarrage pour les installer. Vos plugins et outils peuvent ensuite les importer.
+
+```ts title=".opencode/plugins/my-plugin.ts"
+import { escape } from "shescape"
+
+export const MyPlugin = async (ctx) => {
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (input.tool === "bash") {
+        output.args.command = escape(output.args.command)
+      }
+    },
+  }
+}
+```
+
+---
+
+### Structure de base
+
+```js title=".opencode/plugins/example.js"
+export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
+  console.log("Plugin initialized!")
+
+  return {
+    // Hook implementations go here
+  }
+}
+```
+
+La fonction plugin reçoit :
+
+- `project` : informations sur le projet actuel.
+- `directory` : le répertoire de travail actuel.
+- `worktree` : le chemin de l'arbre de travail git.
+- `client` : un client SDK opencode pour interagir avec l'IA.
+- `$` : [shell API](https://bun.com/docs/runtime/shell) de Bun pour l'exécution de commandes.
+
+---
+
+### Prise en charge de TypeScript
+
+Pour les plugins TypeScript, vous pouvez importer des types à partir du package du plugin :
+
+```ts title="my-plugin.ts" {1}
+import type { Plugin } from "@opencode-ai/plugin"
+
+export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
+  return {
+    // Type-safe hook implementations
+  }
+}
+```
+
+---
+
+### Événements
+
+Les plugins peuvent s'abonner à des événements comme indiqué ci-dessous dans la section Exemples. Voici une liste des différents événements disponibles.
+
+#### Événements de commande
+
+- `command.executed`
+
+#### Événements de fichier
+
+- `file.edited`
+- `file.watcher.updated`
+
+#### Événements d'installation
+
+- `installation.updated`
+
+#### LSP Événements
+
+- `lsp.client.diagnostics`
+- `lsp.updated`
+
+#### Événements de messages
+
+- `message.part.removed`
+- `message.part.updated`
+- `message.removed`
+- `message.updated`
+
+#### Événements d'autorisation
+
+- `permission.asked`
+- `permission.replied`
+
+#### Événements du serveur
+
+- `server.connected`
+
+#### Événements de session
+
+- `session.created`
+- `session.compacted`
+- `session.deleted`
+- `session.diff`
+- `session.error`
+- `session.idle`
+- `session.status`
+- `session.updated`
+
+#### Événements à faire
+
+- `todo.updated`
+
+#### Événements Shell
+
+- `shell.env`
+
+#### Événements d'outils
+
+- `tool.execute.after`
+- `tool.execute.before`
+
+#### TUI Événements
+
+- `tui.prompt.append`
+- `tui.command.execute`
+- `tui.toast.show`
+
+---
+
+## Exemples
+
+Voici quelques exemples de plugins que vous pouvez utiliser pour étendre opencode.
+
+---
+
+### Envoyer des notifications
+
+Envoyez des notifications lorsque certains événements se produisent :
+
+```js title=".opencode/plugins/notification.js"
+export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
+  return {
+    event: async ({ event }) => {
+      // Send notification on session completion
+      if (event.type === "session.idle") {
+        await $`osascript -e 'display notification "Session completed!" with title "opencode"'`
+      }
+    },
+  }
+}
+```
+
+Nous utilisons `osascript` pour exécuter AppleScript sur macOS. Ici, nous l'utilisons pour envoyer des notifications.
+
+:::note
+Si vous utilisez l'application de bureau OpenCode, elle peut envoyer automatiquement des notifications système lorsqu'une réponse est prête ou en cas d'erreur de session.
+:::
+
+---
+
+### Protection .env
+
+Empêchez opencode de lire les fichiers `.env` :
+
+```javascript title=".opencode/plugins/env-protection.js"
+export const EnvProtection = async ({ project, client, $, directory, worktree }) => {
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (input.tool === "read" && output.args.filePath.includes(".env")) {
+        throw new Error("Do not read .env files")
+      }
+    },
+  }
+}
+```
+
+---
+
+### Injecter des variables d'environnement
+
+Injectez des variables d'environnement dans toutes les exécutions du shell (outils d'IA et terminal utilisateur) :
+
+```javascript title=".opencode/plugins/inject-env.js"
+export const InjectEnvPlugin = async () => {
+  return {
+    "shell.env": async (input, output) => {
+      output.env.MY_API_KEY = "secret"
+      output.env.PROJECT_ROOT = input.cwd
+    },
+  }
+}
+```
+
+---
+
+### Outils personnalisés
+
+Les plugins peuvent également ajouter des outils personnalisés à opencode :
+
+```ts title=".opencode/plugins/custom-tools.ts"
+import { type Plugin, tool } from "@opencode-ai/plugin"
+
+export const CustomToolsPlugin: Plugin = async (ctx) => {
+  return {
+    tool: {
+      mytool: tool({
+        description: "This is a custom tool",
+        args: {
+          foo: tool.schema.string(),
+        },
+        async execute(args, context) {
+          const { directory, worktree } = context
+          return `Hello ${args.foo} from ${directory} (worktree: ${worktree})`
+        },
+      }),
+    },
+  }
+}
+```
+
+L'assistant `tool` crée un outil personnalisé que opencode peut appeler. Il prend une fonction de schéma Zod et renvoie une définition d'outil avec :
+
+- `description` : ce que fait l'outil
+- `args` : schéma Zod pour les arguments de l'outil
+- `execute` : Fonction qui s'exécute lorsque l'outil est appelé
+
+Vos outils personnalisés seront disponibles pour opencode aux côtés des outils intégrés.
+
+---
+
+### Journalisation
+
+Utilisez `client.app.log()` au lieu de `console.log` pour la journalisation structurée :
+
+```ts title=".opencode/plugins/my-plugin.ts"
+export const MyPlugin = async ({ client }) => {
+  await client.app.log({
+    body: {
+      service: "my-plugin",
+      level: "info",
+      message: "Plugin initialized",
+      extra: { foo: "bar" },
+    },
+  })
+}
+```
+
+Niveaux : `debug`, `info`, `warn`, `error`. Voir la [documentation du SDK](https://opencode.ai/docs/sdk) pour plus de détails.
+
+---
+
+### Hooks de compactage
+
+Personnalisez le contexte inclus lorsqu'une session est compactée :
+
+```ts title=".opencode/plugins/compaction.ts"
+import type { Plugin } from "@opencode-ai/plugin"
+
+export const CompactionPlugin: Plugin = async (ctx) => {
+  return {
+    "experimental.session.compacting": async (input, output) => {
+      // Inject additional context into the compaction prompt
+      output.context.push(`
+## Custom Context
+
+Include any state that should persist across compaction:
+- Current task status
+- Important decisions made
+- Files being actively worked on
+`)
+    },
+  }
+}
+```
+
+Le hook `experimental.session.compacting` se déclenche avant que le LLM ne génère un résumé de continuation. Utilisez-le pour injecter un contexte spécifique au domaine que le prompt de compactage par défaut manquerait.
+
+Vous pouvez également remplacer entièrement le prompt de compactage en définissant `output.prompt` :
+
+```ts title=".opencode/plugins/custom-compaction.ts"
+import type { Plugin } from "@opencode-ai/plugin"
+
+export const CustomCompactionPlugin: Plugin = async (ctx) => {
+  return {
+    "experimental.session.compacting": async (input, output) => {
+      // Replace the entire compaction prompt
+      output.prompt = `
+You are generating a continuation prompt for a multi-agent swarm session.
+
+Summarize:
+1. The current task and its status
+2. Which files are being modified and by whom
+3. Any blockers or dependencies between agents
+4. The next steps to complete the work
+
+Format as a structured prompt that a new agent can use to resume work.
+`
+    },
+  }
+}
+```
+
+Lorsque `output.prompt` est défini, il remplace complètement le prompt de compactage par défaut. Le tableau `output.context` est ignoré dans ce cas.