Mode non interactif de Pi Agent
Outre la conversation interactive, Pi Agent propose également trois modes non interactifs, adaptés à l'intégration dans des scripts, aux flux de travail automatisés et à la communication entre programmes.
Mode impression (-p)
Le mode impression est le mode non interactif le plus couramment utilisé ; il exécute une session de questions-réponses unique, affiche le résultat, puis se termine.
Utilisation de base
La forme la plus simple consiste à placer une question directement après -p ; l'IA quitte après avoir répondu.
$ pi -p "帮我总结一下这个项目的结构" 这是一个 TypeScript + Vite 项目,源码集中在 src/ 目录下。 入口文件是 src/main.ts,工具函数位于 src/utils/,共 18 个模块。
Utilisez @ pour référencer un fichier afin que l'IA lise le contenu du fichier spécifié :
$ pi -p @README.md "这段文档的主要内容是什么" 这份 README 介绍了安装步骤、环境变量配置和三条常用命令。
Utilisez un pipe pour transmettre directement la sortie d'une commande à l'IA, adapté au traitement de textes tels que les journaux et les documents :
$ cat README.md | pi -p "用三句话总结这段文字" 1. 项目要求 Node 20 以上版本。 2. 安装依赖后先把 .env.example 复制为 .env。 3. 日常调试用 npm run dev,发布构建用 npm run build。
@ peut également référencer des images, ce qui permet à l'IA d'analyser le contenu des images :
$ pi -p @screenshot.png "图片中显示的错误信息是什么" 截图中的报错是 Module not found: Can't resolve './utils/format', 说明 src/index.ts 里的相对路径拼写有误。
Utilisez --name pour nommer la session ; vous pourrez ensuite poursuivre ce fil en mode interactif :
$ pi --name "快速审查" -p "审查 src/ 目录下的代码质量" 代码整体质量良好,有 3 处可以改进: 1. src/api/user.ts 缺少对分页参数的校验。 2. src/utils/format.ts 的日期格式化未处理时区。 3. src/db/query.ts 的裸抛异常建议补充错误码。
Spécifier un modèle
Utilisez --provider et --model pour spécifier un modèle, ou combinez les deux sous la forme provider/model.
$ pi --provider openai --model gpt-4o -p "帮我重构这段代码的逻辑" 重构建议:把 src/service/order.ts 中 120 行的 createOrder 拆成 校验参数、计算金额、落库三个函数,并为每个函数补充单元测试。
La forme combinée ci-dessous est entièrement équivalente à la précédente, juste plus courte à écrire :
$ pi --model openai/gpt-4o -p "帮我重构这段代码的逻辑"
Ajouter un deux-points et un niveau de raisonnement après le nom du modèle contrôle la profondeur de réflexion de cet appel :
$ pi --model sonnet:high -p "这个复杂的算法有什么潜在问题" 主要风险有三点:递归深度没有上限会导致栈溢出; 缓存键未包含用户身份,存在越权读取的可能; 批量写入缺少事务包裹,失败时会出现半提交状态。
Dans --model,:thinkingle suffixe (tel que sonnet:high) et le--thinkingparamètre --reasoning-effort peuvent tous deux définir le niveau de raisonnement.
Il est recommandé de n'en utiliser qu'un seul pour éviter des incohérences difficiles à déboguer entre les deux formes.
Utilisez --models pour limiter l'étendue des modèles disponibles, en séparant plusieurs modèles par des virgules :
$ pi --models "claude-*,gpt-4o" -p "审查代码" 审查完成:共发现 2 个阻塞问题和 5 个改进建议, 详细列表已按严重程度排序。
Contrôle des outils
Contrôler quels outils l'IA peut utiliser via des paramètres de ligne de commande est la clé pour exécuter le mode non interactif en toute sécurité dans des scripts.
Pi Agent dispose de 7 outils intégrés sur les plateformes non Windows : read, write, edit, bash, grep, find, ls.
Sous Windows, bash est remplacé par powershell.
Utilisez --tools comme liste blanche pour ne conserver que les outils spécifiés ; par exemple, un mode lecture seule qui ne modifie aucun fichier :
$ pi --tools read,grep,find,ls -p "审查代码不修改" 审查结果:共 4 个问题,其中 1 个涉及并发写入, 完整报告已输出到终端,本次未修改任何文件。
Utilisez --exclude-tools pour exclure les outils spécifiés :
$ pi --exclude-tools bash -p "分析代码但不执行命令" 分析结论:该模块的性能瓶颈在循环内的重复文件读取, 建议把目录列表提到循环外,预计可减少 80% 的 I/O。
Utilisez --no-builtin-tools pour désactiver tous les outils intégrés ; l'IA ne peut répondre que sur la base du contenu de la conversation, tandis que les extensions et les outils personnalisés restent disponibles :
$ pi --no-builtin-tools -p "纯问答" Quicksort 的平均时间复杂度是 O(n log n), 最坏情况是 O(n^2),出现在已排序数组上选取首元素为主元时。
Lorsque vous devez aussi désactiver les extensions et les outils personnalisés, passez à --no-tools.
Mode JSON (--mode json)
Le mode JSON produit tous les événements au format JSON Lines (JSONL), adapté à l'analyse et au traitement par programme.
$ pi --mode json "总结项目结构"
{"type":"session","version":3,"id":"019f8c2e-7a41-7b3d-9e5f-2c6a1d84b0e7","timestamp":"2026-08-31T02-40-11-000Z","cwd":"/Users/example/projects/example-demo"}
{"type":"agent_start"}
{"type":"turn_start"}
{"type":"message_start","message":{...}}
{"type":"message_update","usage":{...},"assistantMessageEvent":{...}}
{"type":"message_end","message":{...}}
{"type":"turn_end","message":{...},"toolResults":[]}
{"type":"agent_end","messages":[...]}
La première ligne est un en-tête de métadonnées de session qui enregistre la version du format, l'ID de session, l'horodatage et le répertoire de travail.
Chaque ligne qui suit est un événement JSON indépendant, contenant le type d'événement et les données correspondantes.
Ce mode convient aux scénarios suivants :
| Scénario | Description |
|---|---|
| Pipeline de traitement de données | Injecter le flux d'événements dans des scripts de post-traitement et l'analyser/traiter ligne par ligne |
| Surveillance et analyse du comportement | Enregistrer et analyser chaque appel d'outil et chaque processus de décision de l'IA |
| Chaîne d'outils personnalisée | Construisez votre propre workflow automatisé sur la base du flux d'événements |
Mode RPC (--mode rpc)
Le mode RPC met en œuvre une communication inter-processus via le protocole JSONL sur stdin/stdout.
Il permet à un autre programme d’envoyer des commandes via l’entrée standard et de lire les réponses depuis la sortie standard.
Le mode RPC prend en charge un protocole d’interface utilisateur étendu, permettant aux clients distants de présenter des éléments interactifs tels que des boîtes de dialogue de confirmation et des listes de sélection.
Ce mode convient aux scénarios suivants :
| Scénario | Description |
|---|---|
| Plugins d’éditeur | Intégrez Pi Agent dans des extensions d’éditeur telles que VS Code |
| Frontend personnalisé | Créez votre propre interface Pi Agent basée sur le protocole RPC |
| Services en arrière-plan | Intégrez Pi Agent en tant que sous-processus dans un système plus vaste |
Le mode RPC et le mode JSON sont des fonctionnalités avancées destinées aux développeurs.
En tant que débutant, vous n’aurez probablement besoin que du mode interactif et du mode Print.
Lorsque vous devez intégrer Pi Agent dans votre chaîne d'outils, vous pouvez revenir étudier ces deux modes en profondeur.
Comparaison des modes
Les différences entre les trois modes non interactifs se reflètent principalement dans l'interactivité et le format de sortie ; choisissez simplement selon le tableau ci-dessous.
| Mode | Commande | Interactivité | Format de sortie | Scénarios applicables |
|---|---|---|---|---|
| Mode interactif | pi (par défaut) | Conversation en temps réel | Rendu TUI du terminal | Développement quotidien, programmation interactive |
| Mode impression | pi -p | Réponse en une seule fois | Texte brut | Intégration de scripts, requêtes rapides |
| Mode JSON | pi --mode json | Flux d'événements (non interactif) | Flux d'événements JSONL | Analyse de programme, traitement de pipeline |
| Mode RPC | pi --mode rpc | Communication continue | Protocole bidirectionnel JSONL | Intégration à l’éditeur, communication entre processus |
Référence rapide des paramètres CLI
Le tableau ci-dessous répertorie les paramètres courants de la commande pi, regroupés par objectif, et ils peuvent être utilisés avec les commandes en mode interactif.
| Catégorie | Paramètre | Description |
|---|---|---|
| Options du modèle | --provider name | Spécifier le fournisseur d’IA |
| Options du modèle | --model motif | Spécifier l’ID du modèle ; prend en charge les formats provider/id et :thinking |
| Options du modèle | --api-key clé | Passer la clé API directement (priorité la plus élevée) |
| Options du modèle | --thinking niveau | Niveau de raisonnement : off/minimal/low/medium/high/xhigh/max |
| Options du modèle | --models motifs | Liste de modèles séparés par des virgules, limitant la plage de rotation Ctrl+P |
| Options de session | -c, --continue | Continuer la session la plus récente |
| Options de session | -r, --resume | Parcourir et sélectionner des sessions historiques |
| Options de session | --session path|id | Utiliser le fichier de session ou l’UUID spécifié |
| Options de session | --fork path|id | Créer une nouvelle session à partir de la session spécifiée |
| Options de session | --name, -n name | Définir le nom d’affichage de la session |
| Options de session | --no-session | Ne pas enregistrer la session |
| Options de session | --export <input> [output] | Exporter la session au format HTML (le chemin de sortie peut être omis) |
| Options des outils | --tools, -t list | Placer des outils spécifiques sur liste blanche |
| Options des outils | --exclude-tools, -xt list | Désactiver des outils spécifiques |
| Options des outils | --no-builtin-tools, -nbt | Désactiver tous les outils intégrés |
| Options des outils | --no-tools, -nt | Désactiver tous les outils (mode conversation pure) |
| Options de ressources | -e, --extension source | Charger des extensions (répétable) |
| Options de ressources | --skill path | Charger les Skills (répétable) |
| Options de ressources | --theme path | Charger les thèmes (répétable) |
| Autres options | -a, --approve | Faire confiance aux fichiers locaux au projet pour cette exécution |
| Autres options | --no-context-files, -nc | Désactiver le chargement automatique d'AGENTS.md/CLAUDE.md |