Référence : le fichier de configuration

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183

# Référence : le fichier de configuration

- **Version du format** : 1
- **Issue** : [#4 — Spécifier le format du fichier de configuration YAML](../../../.tickets/issues/0004-specifier-le-format-du-fichier-de-configuration.yaml)
- **Schéma** : [schema/config.schema.json](../../../schema/config.schema.json) (JSON Schema 2020-12), vérifié par `go test ./schema`
- **Exemple** : [examples/test-agents.yaml](../../../examples/test-agents.yaml)

Un fichier YAML décrit les agents avec lesquels Sidekicks peut converser, les channels créés au démarrage et les préférences. Les conversations, les messages et les sessions ACP n'y figurent pas (voir [Architecture](../explanation/architecture.md)).

L'application le lit avec le package Go `internal/config` (milestone M1) : validation, valeurs par défaut, chemins, fichier par défaut, rechargement à chaque enregistrement.

## Emplacement

Le fichier est cherché dans cet ordre ; la première source applicable l'emporte :

| # | Source | Exemple |
| --- | --- | --- |
| 1 | option de ligne de commande `--config <chemin>` | `sidekicks --config ~/agents/equipe.yaml` |
| 2 | variable d'environnement `SIDEKICKS_CONFIG` | `SIDEKICKS_CONFIG=~/agents/equipe.yaml` |
| 3 | le dernier fichier ouvert depuis l'application (Settings → **Open…** ou **Recent…**), conservé dans `<dossier de config utilisateur>/sidekicks/preferences.json` | — |
| 4 | l'emplacement par défaut : `<dossier de config utilisateur>/sidekicks/config.yaml` | macOS : `~/Library/Application Support/sidekicks/config.yaml`, Linux : `~/.config/sidekicks/config.yaml` |

`<dossier de config utilisateur>` est celui de `os.UserConfigDir()` en Go. Si le fichier par défaut n'existe pas, Sidekicks le crée avec des commentaires qui expliquent chaque clé (issue #9).

## Chemins

- Un chemin relatif est résolu **par rapport au dossier du fichier de configuration**, jamais par rapport au dossier courant. Un dossier qui contient une configuration et ses agents peut donc être déplacé ou versionné avec git d'un seul tenant.
- `~` en début de chemin désigne le dossier personnel de l'utilisateur.
- `command` : un nom seul (`mm`, `docker`) est cherché dans le `PATH` ; tout ce qui contient `/` est un chemin, résolu comme ci-dessus.
- `args` est transmis tel quel, sans réécriture : le processus de l'agent démarre dans son `workspace`, donc les arguments relatifs au workspace fonctionnent.

## Clés

### Racine

| Clé | Type | Obligatoire | Défaut | Signification |
| --- | --- | --- | --- | --- |
| `version` | entier | oui | — | Version du format ; seule `1` existe. Un format ultérieur l'incrémente, pour que Sidekicks puisse migrer ou refuser explicitement un ancien fichier. |
| `ui` | objet | non | | Préférences d'interface. |
| `limits` | objet | non | | Limites de ressources. |
| `agents` | liste d'agents | oui | | Les agents disponibles avec `@nom`. Peut être vide. |
| `channels` | liste de channels | non | `[]` | Channels créés au démarrage s'ils n'existent pas encore. |

Les clés inconnues sont des **erreurs**, à tous les niveaux : une faute de frappe comme `comand:` doit être signalée, pas ignorée en silence.

### `ui`

| Clé | Valeurs | Défaut | Signification |
| --- | --- | --- | --- |
| `theme` | `system`, `light`, `dark` | `system` | Thème de couleurs ; `system` suit le système d'exploitation. |
| `language` | `en`, `fr` | `en` | Langue de l'interface : ses libellés et les messages d'erreur de la configuration. |

### `limits`

| Clé | Type | Défaut | Signification |
| --- | --- | --- | --- |
| `maxRunningAgents` | entier ≥ 1 | `2` | Agents actifs en même temps. Chaque agent local garde un modèle en mémoire ; la valeur par défaut convient à un portable de 32 Go avec de petits modèles. |
| `stopIdleAgentsAfter` | durée Go (`30s`, `10m`, `1h30m`), ou `0` (nombre ou texte) | `10m` | Arrête un agent inutilisé depuis ce délai pour libérer sa mémoire. `0` ne l'arrête jamais. |

### Un agent

| Clé | Type | Obligatoire | Défaut | Signification |
| --- | --- | --- | --- | --- |
| `name` | identifiant | oui | | Minuscules, chiffres, `-`, `_` ; commence par une lettre ; 32 caractères au plus. Sert dans `@nom` et `/nom:commande`. **Unique.** |
| `title` | texte | non | `name` | Nom affiché dans l'interface. |
| `icon` | texte (un emoji) | non | | Affiché à côté de l'agent. |
| `description` | texte | non | | Une phrase affichée dans la liste `@`. |
| `command` | texte | oui | | Programme qui sert ACP sur stdio. |
| `args` | liste de textes | non | `[]` | Ses arguments. |
| `env` | dictionnaire texte → texte | non | | Variables d'environnement supplémentaires. |
| `workspace` | chemin | non | le dossier de la configuration | Le dossier de l'agent : le processus y démarre et c'est le `cwd` de ses sessions ACP. mm y lit `AGENTS.md` et `skills/`. |
| `runtime` | objet | non | `{type: local}` | Où tourne l'agent (voir ci-dessous). |

### `runtime`

Le runtime indique à Sidekicks comment atteindre les **fichiers et le terminal** de l'agent (panel Agents, issue #28). Il ne change pas la façon de démarrer l'agent : c'est le rôle de `command` et `args`.

| `type` | Clés supplémentaires | Signification |
| --- | --- | --- |
| `local` | aucune | L'agent tourne sur cet ordinateur ; `workspace` est un dossier local. |
| `container` | `container` (obligatoire), `workspacePath` | L'agent tourne dans un conteneur Docker démarré ; fichiers et terminal passent par `docker exec`. |
| `sbx` | `sandbox` (obligatoire), `workspacePath` | L'agent tourne dans une sandbox Docker (`sbx`). L'accès à son shell et à ses fichiers est tranché par l'issue #28. |

`workspacePath` est un chemin absolu dans le conteneur ou la sandbox.

### Un channel

| Clé | Type | Obligatoire | Signification |
| --- | --- | --- | --- |
| `name` | texte, 1 à 64 caractères | oui | Affiché `#nom`. **Unique.** Accents et espaces autorisés. |
| `description` | texte | non | Affichée dans l'en-tête du channel. |
| `agents` | liste de noms d'agents | non | Agents invités à la création du channel. Sans doublon. |

Un channel déclaré ici est créé au démarrage **s'il n'existe pas encore** ; il vit ensuite dans l'application comme n'importe quel channel. Le retirer du fichier ne le supprime pas (supprimer un historique doit être une action explicite de l'utilisateur).

## Règles vérifiées par le chargeur, pas par le schéma

JSON Schema ne sait pas les exprimer ; le chargeur de configuration (issue #9) les vérifie et les signale comme les erreurs de schéma :

1. les noms d'agents sont uniques ;
2. les noms de channels sont uniques ;
3. chaque nom de la liste `agents` d'un channel est le nom d'un agent ;
4. `command` existe (dans le `PATH`, ou comme fichier) — signalé comme avertissement, car un agent peut être installé plus tard.

## Messages d'erreur

Chaque erreur indique la ligne et la clé, dans la langue de l'interface, et dit comment corriger. Exemples avec l'interface en français (`language: fr`) :

| Problème | Message |
| --- | --- |
| `name: Alice Smith` | ligne 12 — agents[0].name : « Alice Smith » n'est pas un nom valide : minuscules, chiffres, « - » ou « _ », sans espace, en commençant par une lettre (ex. « alice ») |
| `comand: mm` | ligne 14 — agents[0].comand : clé inconnue « comand » ; vouliez-vous dire « command » ? |
| `command` absente | ligne 3 — agents[0] : il manque la clé « command » |

## Exemple complet

```yaml
version: 1

ui:
  theme: system
  language: fr

limits:
  maxRunningAgents: 2
  stopIdleAgentsAfter: 10m

agents:
  - name: alice
    title: Alice (assistante)
    icon: "👩"
    description: Questions simples, sans outils
    command: mm
    args: ["-acp", "-config", "agent.yaml"]
    workspace: ./agents/alice

  - name: garfield
    title: Garfield (traducteur)
    icon: "🐮"
    command: mm
    args: ["-acp", "-config", "agent.yaml"]
    workspace: ./agents/garfield

  - name: translator-sbx
    title: Traducteur (sandbox)
    command: sbx
    args: ["exec", "-i", "mm-translator", "mm", "-acp"]
    runtime:
      type: sbx
      sandbox: mm-translator
      workspacePath: /home/agent/workspace

channels:
  - name: général
    agents: [alice]
  - name: traductions
    agents: [garfield]
```

Les arguments `sbx` sont indicatifs tant que l'issue #28 n'a pas confirmé comment exécuter une commande dans une sandbox. Cet exemple est aussi un cas de test (`schema/testdata/valid/spec-example.yaml`).

## Package Go `schema`

`git.rickub.com/bots-garden/sidekicks/schema` embarque le JSON Schema et valide des documents avec lui.

| Identifiant | Signature | Description |
| --- | --- | --- |
| `ConfigSchemaURL` | `const string` | Le `$id` du schéma : `https://git.rickub.com/bots-garden/sidekicks/schema/config.schema.json`. |
| `ConfigSchema` | `func() []byte` | Une copie du document JSON Schema. |
| `ValidateConfig` | `func(document []byte) error` | `nil` si le document YAML respecte le schéma ; une erreur de syntaxe YAML s'il ne peut pas être lu ; sinon une `*jsonschema.ValidationError` qui liste toutes les violations. |

```go
if err := schema.ValidateConfig(content); err != nil {
    fmt.Println("configuration invalide :", err)
}
```

Une violation telle que la renvoie `ValidateConfig` :

```text
jsonschema validation failed with 'https://git.rickub.com/bots-garden/sidekicks/schema/config.schema.json#'
- at '/agents/0': additional properties 'comand' not allowed
```