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énarioDescription
Pipeline de traitement de donnéesInjecter le flux d'événements dans des scripts de post-traitement et l'analyser/traiter ligne par ligne
Surveillance et analyse du comportementEnregistrer et analyser chaque appel d'outil et chaque processus de décision de l'IA
Chaîne d'outils personnaliséeConstruisez 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énarioDescription
Plugins d’éditeurInté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-planInté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.

Pi Agent 交互、Print、JSON、RPC 四种运行模式的输入与输出对比

ModeCommandeInteractivitéFormat de sortieScénarios applicables
Mode interactifpi (par défaut)Conversation en temps réelRendu TUI du terminalDéveloppement quotidien, programmation interactive
Mode impressionpi -pRéponse en une seule foisTexte brutIntégration de scripts, requêtes rapides
Mode JSONpi --mode jsonFlux d'événements (non interactif)Flux d'événements JSONLAnalyse de programme, traitement de pipeline
Mode RPCpi --mode rpcCommunication continueProtocole bidirectionnel JSONLInté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égorieParamètreDescription
Options du modèle--provider nameSpécifier le fournisseur d’IA
Options du modèle--model motifSpé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 niveauNiveau de raisonnement : off/minimal/low/medium/high/xhigh/max
Options du modèle--models motifsListe de modèles séparés par des virgules, limitant la plage de rotation Ctrl+P
Options de session-c, --continueContinuer la session la plus récente
Options de session-r, --resumeParcourir et sélectionner des sessions historiques
Options de session--session path|idUtiliser le fichier de session ou l’UUID spécifié
Options de session--fork path|idCréer une nouvelle session à partir de la session spécifiée
Options de session--name, -n nameDéfinir le nom d’affichage de la session
Options de session--no-sessionNe 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 listPlacer des outils spécifiques sur liste blanche
Options des outils--exclude-tools, -xt listDésactiver des outils spécifiques
Options des outils--no-builtin-tools, -nbtDésactiver tous les outils intégrés
Options des outils--no-tools, -ntDésactiver tous les outils (mode conversation pure)
Options de ressources-e, --extension sourceCharger des extensions (répétable)
Options de ressources--skill pathCharger les Skills (répétable)
Options de ressources--theme pathCharger les thèmes (répétable)
Autres options-a, --approveFaire confiance aux fichiers locaux au projet pour cette exécution
Autres options--no-context-files, -ncDésactiver le chargement automatique d'AGENTS.md/CLAUDE.md
Autres extensions