Ubuntu TechHive

Notes on my Pi setup

Notes on my Pi setup

Les outils principaux de Pi sont =read=, =bash=, =edit= et =write=. Les fichiers =AGENTS.md= du projet fournissent des contraintes spécifiques au dépôt.

Notes sur ma configuration Pi

Comment j'utilise Pi

J'utilise Pi comme assistant de codage en terminal personnalisable pour inspecter des dépôts, effectuer des changements ciblés et exécuter des vérifications. Les compétences (skills) capturent des flux de travail réutilisables ; les extensions ajoutent la délégation, la recherche, le retour en arrière (rewind) et des objectifs persistants.

Mon CLI installé est Pi 1.5.2. Dans ~/.pi/agent/settings.json, mon défaut est openai-codex/gpt-6.1-sol avec une réflexion xhigh, le thème sombre et des blocs de réflexion masqués. Masquer ces blocs modifie la présentation, pas l'effort de raisonnement. Il s'agit de sélections de modèles configurées, et non de garanties de disponibilité des fournisseurs.

cd /path/to/project
pi
# Dans Pi : /login, /model, /reload

Les outils principaux de Pi sont read, bash, edit et write. Les fichiers AGENTS.md du projet fournissent des contraintes spécifiques au dépôt. Les extensions exécutent des intégrations ; les compétences fournissent des instructions spécifiques aux tâches chargées lorsqu'elles sont pertinentes.

Extensions installées

Ces paquets sont déclarés dans mes paramètres utilisateur et installés sous ~/.pi/agent/npm/node_modules/. Les versions ci-dessous décrivent la configuration inspectée, pas des versions figées : mes déclarations de paquets utilisent des sources npm: sans version.

Paquet Installé Mon usage
pi-subagents 0.88.1 Travailleurs ciblés, relecteurs indépendants, conseillers et audit de périmètre.
pi-web-access 0.47.0 Recherche web, vérification de sources, extraction de pages/PDF, recherche de dépôts et vidéos.
pi-rewind-hook 1.8.8 Points de contrôle de fichiers basés sur Git associés à l'historique de session ; restauration via /tree ou /fork.
pi-goal-x 0.34.1 Objectifs persistants explicites, progression des tâches, pause/reprise et audit de complétion optionnel.

Mon paramètre extensions contient "-builtin:mcp" : l'intégration MCP native de Pi est désactivée. Les capacités ci-dessous proviennent de la documentation des extensions installées ; elles n'impliquent pas que chaque fonctionnalité optionnelle est activée dans mes paramètres.

pi-subagents : travail ciblé et jugement indépendant

La délégation nécessite ma demande ou des instructions applicables, pas seulement de la complexité. subagents_enable expose les outils de délégation lorsque nécessaire. Un enfant au premier plan s'exécute en tant que session dans le processus parent ; un enfant en arrière-plan utilise un exécuteur détaché. Chacun reçoit sa propre tâche, son contexte, ses outils et sa sélection de modèle.

Je sépare le travailleur d'implémentation de la relecture/conseil en lecture seule et de l'audit de périmètre (voir le tableau des rôles ci-dessous). Les relectures indépendantes peuvent s'exécuter en parallèle ; l'implémentation garde un seul rédacteur par arborescence de travail. contact_supervisor transmet les décisions de points de contrôle et les mises à jour significatives au coordinateur. /subagents-fleet inspecte le travail en cours ; /subagents-doctor diagnostique la configuration.

Exemples de requêtes — pas d'activité automatique en arrière-plan :

Utilise le relecteur pour vérifier ce changement par rapport à mes exigences sans éditer.
Demande à l'oracle de contester ce plan avant l'implémentation.

pi-web-access : recherche avec preuves inspectables

web_enable charge les outils de recherche à la demande :

  • web_search : recherche ou traite des requêtes liées ; workflow: "none" renvoie les résultats sans appel de génération de résumé séparé ou navigateur curateur.
  • fetch_content : récupère des pages, PDF, dépôts ou contenu vidéo pris en charge. Le traitement en mode réponse est une interaction de modèle séparée et optionnelle.
  • get_search_content : parcourt les résultats stockés ou trouve des passages exacts en utilisant un responseId, au lieu de récupérer plusieurs fois le même matériel.
  • source_check : collecte des passages et des métadonnées de source pour une vérification manuelle des affirmations ; la récupération seule n'établit pas qu'une affirmation est vraie.

Les recherches/récupérations peuvent envoyer des données à des services externes. Je garde les identifiants, les sources privées et les détails de projets non liés hors des requêtes de recherche et des exemples.

pi-rewind-hook : les fichiers et la conversation peuvent être restaurés séparément

Via /fork, je peux conserver les fichiers tout en bifurquant la conversation, restaurer les deux, ou restaurer le code tout en conservant la conversation. /tree offre une restauration de fichier exacte là où un point de contrôle existe, plus l'annulation (undo) quand disponible.

Les points de contrôle appartiennent aux limites de tour invite/assistant, pas à chaque appel d'outil. Le registre de session les enregistre ; Git conserve les objets instantanés accessibles via refs/pi-rewind/store. La couverture inclut les fichiers suivis et non suivis non ignorés, pas les fichiers ignorés ou les répertoires vides. Cela complète les commits normaux. Je n'ai pas de remplacement rewind.retention : le défaut documenté est aucune expiration automatique, donc le stockage des instantanés peut croître.

pi-goal-x : travail explicite et persistant

/goal discute d'un résultat et confirme un plan avant exécution ; /sisyphus suit des étapes ordonnées. Les objectifs, tâches et progrès persistent à travers les sessions. /goal-direct contourne la rédaction uniquement quand je le choisis explicitement.

/goal-status montre la progression, /goal-pause arrête la continuation automatique, /goal-resume continue, et /goal-tweak révise l'objectif ou le plan. L'audit de complétion optionnel utilise un agent séparé pour vérifier les exigences et les preuves ; sa disponibilité n'est pas une affirmation que je l'ai activé. Les tâches ordinaires ne deviennent pas implicitement des objectifs.

Mes compétences

Seul commit-msg réside dans ~/.pi/agent/skills/. Pi découvre aussi le répertoire partagé ~/.agents/skills/, où vivent mes autres compétences personnelles/installées par des outils.

Emplacement / compétence Objectif
~/.pi/agent/skills/commit-msg Messages de commit au passé, multilignes, dans le style develop du dépôt, basés uniquement sur les changements inspectés ; aucune mutation Git.
~/.agents/skills/implementation-steps Cours de reconstruction pratique dans scratch/implementation_steps/, avec code de travail cumulatif et vérification.
~/.agents/skills/lightpanda Extraction DOM consciente de JavaScript et automatisation de navigateur fonctionnelle ; pas une preuve de fidélité de mise en page visuelle.
~/.agents/skills/rex Contrôle les sessions, onglets, volets, commandes et sortie terminal de Rex via son CLI.
~/.agents/skills/ui-sdk Construire et tester des interfaces accessibles basées sur le comportement en utilisant @ui-sdk/*.
~/.agents/skills/ui-ux-a11y Appliquer les règles groupées UI/UX, WCAG 2.2 AA, accessibilité, contraste et validation.

Le paquet des sous-agents fournit aussi pi-subagents pour l'orchestration et council-mode pour un débat de conseillers borné et en lecture seule ; ce sont des compétences packagées.

Exemple d'invocation dans Pi :

/skill:commit-msg staged files

Extraits de compétences intégrées

Ce sont des sélections textuelles de mes six fichiers SKILL.md personnels/installés par des outils, pas des définitions de compétences de substitution. Les fichiers de support et chemins relatifs appartiennent toujours à chaque répertoire de compétence original. L'entrée Rex courte est incluse en entier ; les compétences plus longues sont extraites pour garder ces notes lisibles.

commit-msg : preuve avant formulation

Source : ~/.pi/agent/skills/commit-msg/SKILL.md, “Core Contract”.

Le message de commit généré DOIT :

1. Correspondre au style et au format des commits récents de la branche `develop`.
2. Utiliser le passé.
3. Être multiligne.
4. Être basé uniquement sur les changements de fichiers inspectés à partir de l'entrée demandée.
5. Éviter les affirmations qui ne sont pas supportées par les données diff/stat/name-status.
6. Éviter de réutiliser un sujet espace réservé tel que `WIP` à partir du/des commit(s) cible(s).
7. Éviter de muter l'état git ; cette compétence est en lecture seule.

implementation-steps : code de travail et enseignabilité

Source : ~/.agents/skills/implementation-steps/SKILL.md, contrat d'ouverture.

Produire un cours d'implémentation pratique pour la cible sélectionnée. Chaque étape numérotée
inclut le code source fonctionnel réel et son propre README détaillé. Un apprenant qui
suit les étapes documentées doit comprendre ce qu'il écrit et pourquoi, et
atteindre exactement le code cible capturé. La correction technique, l'égalité exacte de la source
et l'enseignabilité sont des exigences séparées ; aucune ne se substitue à une autre.

Ce flux de travail est indépendant du langage et du framework. Inspectez la cible plutôt
que d'imposer un runtime, une architecture, un nombre fixe d'étapes ou les choix d'implémentation
d'une tâche précédente. Créez les artefacts d'apprentissage ; laissez la cible inchangée.

lightpanda : extraction bornée, preuve appropriée

Source : ~/.agents/skills/lightpanda/SKILL.md, “CLI and persistent automation”.

Pour une URL autorisée connue, commencez par une extraction bornée :

```zsh
lightpanda fetch --dump markdown --dump-max-bytes 12000 --fail-on-http-error 'http://127.0.0.1:PORT/PATH'
```

Remplacez l'URL par une URL d'application observée. Utilisez `--dump html` pour le balisage ou `--dump semantic_tree_text` pour un arbre sémantique compact. Inspectez le statut de la commande et les erreurs ; un dump seul n'est pas une preuve de navigation ou d'interaction réussie.

rex : charger les conseils depuis le CLI installé

Source : ~/.agents/skills/rex/SKILL.md, fichier complet.

---
name: rex
description: Utilisez le CLI rex pour gérer les sessions Rex, ouvrir des onglets, organiser des volets, exécuter des commandes, inspecter la sortie du terminal et contrôler les applications Rex connectées.
metadata:
  rex-stub: "2"
---


Exécutez `rex __internal skill` et suivez le guide qu'il affiche. Le guide provient
du CLI Rex installé, il décrit donc les commandes disponibles dans cette version.

Si la commande échoue, la version Rex installée est antérieure au guide. Commencez par
`rex whoami --json`, puis utilisez `rex --help` et `rex COMMAND --help`.

ui-sdk : utiliser la documentation correspondant à la version

Source : ~/.agents/skills/ui-sdk/SKILL.md, “Read first”.

La documentation pour la version installée est livrée dans chaque paquet, au format Markdown :

- `node_modules/@ui-sdk//docs/llms.txt` est l'index. Lisez-le en premier. `` est `react`, `vue`, `svelte`, `solid` ou `web`.
- Ensuite, lisez uniquement les pages dont votre tâche a besoin, comme `docs/components/select.md`. Ne lisez pas tout le dossier `docs/` ; il est volumineux.
- Une interface construite à partir de nos composants n'a pas besoin de `docs/core.md`. Seul le chemin 2 ci-dessous en a besoin, et même là, vous le recherchez par titre : il fait plus de 300 Ko. `docs/rendering.md` se trouve à côté dans le même dossier `docs/`.
- Ne lisez pas le JavaScript compilé dans `dist/*.js`, même pour déboguer. La documentation et les types `.d.ts` sont l'API ; quand ils ne répondent pas, écrivez un petit test qui essaie.

Ici, “chemin 2” signifie construire un composant/comportement manquant à partir de @ui-sdk/core, plutôt que de composer des composants existants.

ui-ux-a11y : préserver l'autorité et le périmètre

Source : ~/.agents/skills/ui-ux-a11y/SKILL.md, “Scope and authority gate”.

Avant d'éditer ou d'approuver le travail :

1. Identifiez le périmètre d'implémentation autorisé par l'utilisateur, les instructions du dépôt et tout plan ou critère d'acceptation applicable dans le projet actuel.
2. Découvrez et inspectez les sources de vérité réelles du projet actuel : comportement produit existant, référence fournie par l'utilisateur, contrat de design, système de design, source de jetons et comportement déployé lorsque la tâche l'exige. Ne supposez aucun nom de fichier ou chemin.
3. Identifiez chaque ID de règle `UX-*`, `A11Y-*`, `CC-*` et `VAL-*` applicable pour les routes, états, locales, fenêtres d'affichage, thèmes et interactions affectés.
4. Enregistrez la ligne de base faisant autorité requise par `VAL-01` avant l'implémentation. Utilisez une ligne de base de référence uniquement lorsque la tâche ou le projet actuel en définit une.
5. Arrêtez-vous si une source de vérité requise est manquante ou si la conformité nécessiterait une route, fonctionnalité, refonte, flux de travail, dépendance, contenu, permission ou changement de périmètre produit non approuvé.

Son dossier de règles complet ui_ux_a11y/ reste faisant autorité ; cet extrait ne remplace pas ses vérifications d'accessibilité, de contraste et d'expérience rendue.

Délégation contrôlée

Mon subagents.agentOverrides sépare l'implémentation du jugement. Les quatre rôles héritent du contexte du projet et utilisent par défaut un contexte de conversation frais (remplacements explicites pour les rôles en lecture seule ; le défaut groupé pour le travailleur).

Rôle Modèle configuré Réflexion Responsabilité / outils
worker openai-codex/gpt-6.1-sol medium Implémenter les points de contrôle assignés ; lecture/recherche, bash, edit, write, contact superviseur.
reviewer openai-codex/gpt-6.1-sol high Correction en lecture seule et revue de preuves ; lecture/recherche et contact superviseur uniquement.
oracle openai-codex/gpt-6-astra medium Conseil architectural en lecture seule et vérification d'hypothèses.
scopeCreepPatrol openai-codex/gpt-6-astra medium Traçabilité des exigences en lecture seule et détection de périmètre non autorisé.

scopeCreepPatrol a sa définition d'agent dans ~/.agents/scopecreeppatrol.md ; le modèle et les autres remplacements proviennent de mes paramètres Pi.

Pour l'implémentation déléguée, le coordinateur achemine le travail, prend des décisions et maintient le registre — pas le code. Le travailleur vérifie le code fourni par les conseillers par rapport aux fichiers actuels et aux exigences approuvées, rapporte les preuves de validation et demande une décision de point de contrôle avant l'unité suivante. Les rôles en lecture seule renvoient des conclusions/code correctif en ligne, pas des fichiers. Les recommandations ne sont pas une approbation utilisateur.

L'auditeur de périmètre vérifie les références d'exigences, une colonne littérale 1 à N, l'origine de l'exigence et les statuts exacts no-started / in-progress / deferred / completed / not-applicable ; il ne doit pas inventer la signification de cette colonne. Les questions bloquantes utilisent contact_supervisor avec need_decision ; les mises à jour matérielles non bloquantes utilisent progress_update, sans bavardage de routine.

flowchart TD
    U["Exigences et approbations utilisateur"] --> C["Coordinateur : acheminer et suivre"]
    C --> W["Travailleur : implémenter un point de contrôle"]
    W --> E["Fichiers modifiés et preuves de validation"]
    E --> R["Relecteur : correction"]
    E --> S["Patrouille de périmètre : traçabilité"]
    C --> O["Oracle : conseil borné"]
    R --> D["Coordinateur : décision de point de contrôle"]
    S --> D
    O --> D
    D -->|Unité suivante approuvée| W
    D -->|Exigences satisfaites| F["Rapport final"]

Ma configuration des sous-agents

La section complète subagents de ~/.pi/agent/settings.json est intégrée ci-dessous, incluant les quatre remplacements de rôles et leurs invites inchangées. L'objet JSON externe montre où il appartient dans les paramètres ; les paramètres non liés sont omis.

{
  "subagents": {
    "agentOverrides": {
      "worker": {
        "model": "openai-codex/gpt-6.1-sol",
        "thinking": "medium",
        "inheritProjectContext": true,
        "tools": [
          "read",
          "grep",
          "find",
          "ls",
          "bash",
          "edit",
          "write",
          "contact_supervisor"
        ],
        "systemPrompt": "Vous êtes le travailleur d'implémentation. Implémentez uniquement le travail assigné traçable aux exigences réelles de l'utilisateur. N'étendez jamais le périmètre sans approbation explicite préalable de l'UTILISATEUR. Les recommandations de l'agent ne sont pas une approbation. Le\n coordinateur coordonne, maintient le registre de progression et relaie le code écrit par l'agent ; il ne doit pas écrire ou réviser le code. Appliquez le code fourni par le conseiller uniquement après avoir vérifié son applicabilité aux fichiers actuels et aux exigences\n approuvées. À chaque point de contrôle d'implémentation assigné, rapportez les références d'exigences, les fichiers modifiés, les preuves de validation, le travail restant et les mises à jour du registre nécessaires ; demandez la décision du coordinateur avant de commencer l'unité\n d'implémentation suivante. Utilisez contact_supervisor avec la raison need_decision pour les questions bloquantes et les décisions de point de contrôle, ou progress_update pour les changements matériels nécessitant l'attention du coordinateur. N'envoyez pas de narration de routine ou de messages de complétion en double. Ne prétendez jamais que la validation a réussi sans preuve."
      },
      "reviewer": {
        "model": "openai-codex/gpt-6.1-sol",
        "thinking": "high",
        "inheritProjectContext": true,
        "defaultContext": "fresh",
        "tools": [
          "read",
          "grep",
          "find",
          "ls",
          "contact_supervisor"
        ],
        "systemPrompt": "Vous êtes le relecteur d'implémentation en lecture seule. Révisez le point de contrôle du travailleur assigné par rapport aux exigences réelles de l'utilisateur, à l'implémentation, aux tests et aux preuves de validation. N'éditez pas de fichiers et ne créez pas de patch ou\n de fichiers de rapport. Renvoyez des conclusions exploitables avec les références d'exigences, les emplacements exacts, les preuves et le code de remplacement concret ou les diffs unifiés EN LIGNE lorsque utile. Distinguez les défauts réels des recommandations optionnelles. Ne\n développez pas ou ne redéfinissez pas le périmètre, et ne traitez jamais vos recommandations comme une approbation utilisateur. Rapportez les conclusions bloquantes rapidement via contact_supervisor ; sinon renvoyez une revue finale concise. Évitez les battements de cœur, les conclusions en double et le bavardage de routine. Identifiez les points de contrôle obsolètes et les affirmations de complétion non supportées."
      },
      "oracle": {
        "model": "openai-codex/gpt-6-astra",
        "thinking": "medium",
        "inheritProjectContext": true,
        "defaultContext": "fresh",
        "tools": [
          "read",
          "grep",
          "find",
          "ls",
          "contact_supervisor"
        ],
        "systemPrompt": "Vous êtes un conseiller en lecture seule répondant à la question spécifique assignée par le coordinateur. Contestez les hypothèses non supportées, identifiez les risques architecturaux ou de correction, et distinguez les faits, l'incertitude,\n et les recommandations. Lorsque utile, fournissez du code correctif réel ou des diffs unifiés EN LIGNE. N'éditez pas de fichiers et ne créez pas de patch ou de fichiers de rapport. Préservez les exigences réelles de l'utilisateur ; l'extension de périmètre nécessite une approbation explicite préalable de l'UTILISATEUR. Vous ne pouvez pas accorder cette approbation. Escaladez les décisions manquantes bloquantes via contact_supervisor ; sinon renvoyez votre réponse bornée sans bavardage de progression de routine. N'inventez pas d'exigences supplémentaires et n'initiez pas de travail non lié."
      },
      "scopeCreepPatrol": {
        "model": "openai-codex/gpt-6-astra",
        "thinking": "medium",
        "inheritProjectContext": true,
        "defaultContext": "fresh",
        "tools": [
          "read",
          "grep",
          "find",
          "ls",
          "contact_supervisor"
        ],
        "systemPrompt": "Vous êtes l'auditeur de périmètre et de traçabilité des exigences en lecture seule. Comparez le point de contrôle du travailleur assigné et le registre de progression avec les exigences réelles de l'utilisateur et les approbations explicites préalables de l'utilisateur. Détectez\n l'extension non autorisée, les exigences omises ou altérées, et les suggestions de l'agent présentées à tort comme autorité utilisateur. Vérifiez que le registre inclut les références d'exigences d'implémentation, une colonne littérale 1 à N, le statut et l'origine de l'exigence.\n N'inventez pas la signification de 1 à N. Préservez les statuts exactement : no-started / in-progress / deferred / completed / not-applicable. Distinguez l'exigence utilisateur de l'exigence agent ; une exigence agent n'autorise pas\n l'extension de périmètre. Rapportez les divergences étayées par des preuves rapidement via contact_supervisor. Fournissez du code correctif concret EN LIGNE lorsque utile et dans le périmètre existant. N'éditez jamais de fichiers, ne créez jamais de patch ou de fichiers de rapport, ne redéfinissez jamais\n les exigences, n'accordez jamais d'approbations et ne fabriquez jamais de portes d'acceptation. Évitez le bavardage de routine."
      }
    },
    "watchdog": {
      "enabled": true,
      "scope": {
        "enabled": true
      },
      "clarification": true,
      "main": {
        "model": "openai-codex/gpt-6-astra",
        "thinking": "medium"
      },
      "cadence": {
        "everyNTools": 16
      },
      "children": {
        "enabled": false,
        "overrides": {
          "worker": {
            "enabled": true,
            "model": "openai-codex/gpt-6.1-sol",
            "thinking": "high",
            "cadence": {
              "everyNTools": 8
            }
          }
        }
      }
    }
  }
}

Comportement du chien de garde (watchdog)

Le chien de garde est un mécanisme de revue par un second modèle séparé, pas le rôle reviewer. Le chien de garde principal vérifie tous les 16 résultats d'outils et aux limites de travail modifié éligibles. La surveillance du périmètre et la clarification de la session principale sont activées. Les chiens de garde enfants sont désactivés sauf pour le travailleur : son remplacement explicite active la revue tous les huit résultats d'outils et aux limites éligibles, en utilisant Sol/high. Ce sont des déclencheurs d'activité/limite, pas une boucle d'interrogation inactive.

Commandes d'inspection utiles dans Pi : /subagents-fleet, /subagents-doctor et /subagents-watchdog status.

Inférence locale : une API HTTP supportée par Pi

Mon espace de travail Bun/TypeScript local-inference/ expose une API Chat Completions compatible OpenAI à http://127.0.0.1:8081/v1. C'est une passerelle HTTP locale vers les fournisseurs gérés par Pi, pas un serveur de poids de modèle sur l'appareil.

  • packages/protocol : validation de requête Zod 4 et contrat backend.
  • packages/pi-proxy : ModelRuntime public de Pi pour la résolution de modèle, identifiants enregistrés, rafraîchissement OAuth et streaming natif.
  • packages/server : Bun.serve, traduction HTTP/SSE, annulation, contre-pression et enveloppes de continuation chiffrées.

La passerelle épingle @earendil-works/pi-coding-agent et @earendil-works/pi-ai à 1.5.0, indépendamment du 1.5.2 de mon CLI installé.

flowchart LR
    C["Client HTTP"] -->|Chat Completions| H["local-inference : serveur HTTP Bun"]
    H --> V["Requête validée par Zod"]
    V --> M["Pi ModelRuntime"]
    P["Configuration modèle Pi et connexion enregistrée"] --> M
    M --> Q["Fournisseur amont configuré"]
    Q -->|Flux natif| M
    M -->|Texte, raisonnement, événements d'outil| H
    H -->|Deltas SSE| C
    C --> T["Exécution d'outil côté client optionnelle"]
    T -->|Résultats d'outil sur la requête suivante| H

Chaque requête effectue un tour de fournisseur : la passerelle n'exécute pas d'outils ou n'édite pas de fichiers. L'exécution d'outil appartient au client. Les flux de texte sont séparés du raisonnement ; les déconnexions/arrêts annulent le travail amont. Les données de continuation natives utilisent une enveloppe reasoning_details authentifiée et chiffrée.

Après vous être connecté au fournisseur souhaité avec Pi, démarrez la passerelle depuis le dossier contenant local-inference/ :

cd local-inference
bun install --frozen-lockfile
bun run start -- --port 8081

Dans un autre terminal, inspectez l'écouteur ou faites explicitement une requête en streaming (le POST utilise le compte fournisseur et peut entraîner une utilisation) :

curl http://127.0.0.1:8081/healthz
curl http://127.0.0.1:8081/v1/models
curl -N http://127.0.0.1:8081/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"openai-codex/gpt-6.1-sol","stream":true,
       "messages":[{"role":"user","content":"Reply with hello."}]}'

Les IDs de modèle sont des chaînes exactes provider/model ; /v1/models annonce les modèles mais n'est pas une liste d'autorisation d'admission. Pi possède le support fournisseur et la gestion des identifiants. L'écouteur de boucle locale par défaut ne nécessite aucun jeton client ; la liaison non-boucle locale en nécessite un. --token-env NAME protège optionnellement l'écouteur, indépendamment de la connexion fournisseur. Ne publiez jamais auth.json ou des jetons.

L'API supporte le texte et les outils de fonction, pas les images, les réponses contraintes par schéma ou le point de terminaison Responses. Les clients doivent utiliser Chat Completions. Exécutez bun run typecheck depuis local-inference/ pour vérifier les types de la passerelle.

Code de local-inference

Ce sont des extraits textuels, pas des programmes autonomes : la classe environnante, les types et les définitions d'aide restent dans les fichiers sources nommés. Aucune application cliente ou espace de noms de paquet non lié n'est reproduit ici.

Créer le runtime de Pi et lister les modèles annoncés

Depuis local-inference/packages/pi-proxy/src/index.ts. Les identifiants et la configuration du fournisseur restent derrière ModelRuntime ; le rafraîchissement et le listing reçoivent le signal d'annulation de la requête.

  static async create(options: PiBackendOptions = {}): Promise<PiBackend> {
    const { provider, ...runtimeOptions } = options;
    return new PiBackend(await ModelRuntime.create(runtimeOptions), provider);
  }

  async models(signal: AbortSignal) {
    await this.runtime.refresh({ providers: this.provider ? [this.provider] : undefined, signal });
    signal.throwIfAborted();
    const available = await this.runtime.getAvailable(this.provider, { signal });
    return available.map(model => ({ id: this.provider ? model.id : `${model.provider}/${model.id}`, owned_by: model.provider }));
  }

Résoudre le fournisseur tout en préservant l'ID de modèle exact demandé

Depuis le même fichier. Pi fournit les métadonnées du fournisseur et la résolution de modèle personnalisé ; la couche HTTP conserve l'ID de modèle exact de l'appelant plutôt que d'appliquer les commodités de nom flou ou de suffixe de réflexion du CLI.

  async resolve(id: string, signal: AbortSignal): Promise<InferenceModel> {
    signal.throwIfAborted();
    const slash = id.indexOf("/");
    const provider = this.provider ?? (slash > 0 ? id.slice(0, slash) : undefined);
    const modelId = this.provider ? id : id.slice(slash + 1);
    if (!provider) throw new ApiError(400, "Utilisez provider/model comme ID de modèle, ou commencez par --provider");
    await this.runtime.refresh({ providers: [provider], signal });
    signal.throwIfAborted();
    const selected = resolveCliModel({ cliProvider: provider, cliModel: modelId, modelRuntime: this.runtime });
    if (!selected.model) throw new ApiError(400, selected.error ?? "Pi n'a pas pu résoudre le modèle demandé", "model_resolution_error");
    // Pi possède la construction du modèle, les métadonnées du fournisseur et le support de modèle personnalisé.
    // Son résolveur CLI accepte aussi les noms flous/suffixes de réflexion ; un modèle HTTP
    // est un ID exact, donc ces commodités ne doivent pas réécrire ce champ.
    return { ...selected.model, id: modelId };
  }

Choisir l'API de streaming Pi

Depuis PiBackend.stream dans le même fichier. Les options de raisonnement partagées utilisent streamSimple ; les options natives reasoningEffort utilisent stream.

    const events = request.reasoningEffort === undefined
      ? this.runtime.streamSimple(model, context, request)
      : this.runtime.stream(model, context, request);

Garder le texte et le raisonnement séparés sur le fil

Depuis local-inference/packages/server/src/index.ts, à l'intérieur du switch d'événement. Les deltas de texte sont émis dès qu'ils arrivent, sans attendre la complétion du fournisseur.

      case "text_delta": source.push(event.delta); await chunk({ content: event.delta }); break;
      case "thinking_delta": await chunk({ reasoning_content: event.delta }); break;

Références

Sources pour le harnais, les extensions, les outils basés sur des compétences et les bibliothèques que j'utilise avec Pi :