Tutorial de introducción a Pi Coding Agent

Pi es un agente de codificación de IA que se ejecuta en la terminal, similar a herramientas como Claude Code y OpenAI Codex CLI.

La filosofía oficial de Pi es:"There are many agent harnesses but this one is yours"(Hay muchas herramientas de agentes, pero esta es tuya).

Le das una frase a Pi y podrá leer archivos, escribir archivos y ejecutar comandos en el directorio de tu proyecto, invocando el modelo en bucle hasta completar la tarea.

La idea central es utilizar un núcleo mínimo con una extensibilidad extremadamente potente, permitiéndote transformar la herramienta para que se adapte a ti, en lugar de adaptarte tú a la herramienta.

Tutorial completo de Pi Agent:https://www.example.com/pi-agent/pi-agent-tutorial.html

¿Qué incluye Pi?

Pi no es un programa independiente, sino una cadena de herramientas compuesta por cuatro paquetes npm.

Los usuarios normales solo necesitan instalar el paquete de la capa superior@earendil-works/pi-coding-agenty obtendrán un agente de línea de comandos listo para usar.

¿Para quién es adecuado?

Pi es especialmente adecuado para los siguientes escenarios y perfiles de usuarios:

Desarrolladores que prefieren el flujo de trabajo en terminal y no quieren alternar entre el IDE y la línea de comandos
Usuarios avanzados que quieren una herramienta profundamente personalizable, e incluso que el agente pueda reescribir sus propias herramientas
Personas que necesitan conectarse a varios modelos grandes a la vez (Anthropic, OpenAI, Google, etc.)
Desarrolladores que quieren integrar las capacidades del agente en sus propios programas (mediante el modo SDK o RPC)

Nota: Pi se ejecuta por defecto con los permisos de tu usuario y no tiene sandbox integrado. Antes de usarlo en repositorios de código no confiables, lee primero la sección «Notas de seguridad» de este artículo.

Filosofía de diseño central: primitivas, no funciones

Al comprender la filosofía de diseño de Pi, entenderás por qué deliberadamente «no integra» muchas funciones que otros agentes sí tienen.

Pi llama a este conceptoPrimitives, Not Features(proporcionar primitivas, no funciones).

Funciones deliberadamente no integradas

Las siguientes funciones no están integradas en Pi; en su lugar, te permite implementarlas según sea necesario mediante extensiones o herramientas externas:

Función no integrada	Alternativa en Pi
Integración del protocolo MCP	Escribir la herramienta como una CLI con README, o instalar una extensión MCP
Subagentes (subagents)	Usar tmux para abrir múltiples sesiones, o escribir tu propia extensión
Ventana emergente de confirmación de permisos	Ejecutarlo en un contenedor, o escribir tu propia extensión de flujo de confirmación
Modo de planificación (plan mode)	Escribir el plan en un archivo, o escribir una extensión
Lista de tareas integrada	Usar un archivo TODO.md, o instalar una extensión
Bash en segundo plano	Usar tmux para obtener una observabilidad completa

¿Por qué hacer esto?

Pi considera que las necesidades de estas funciones varían enormemente entre equipos; integrarlas a la fuerza haría que la herramienta se volviera pesada y difícil de adaptar al flujo de trabajo real.

Por eso su enfoque es: mantener un núcleo mínimo y limpio, convirtiendo todas las «funciones» en extensiones, habilidades, plantillas de prompts y temas que se pueden instalar, escribir y compartir.

Incluso puedes pedirle directamente a Pi que escriba estas funciones por ti y, al terminar, usa/reloadpara recargar, y podrás usarlas de inmediato.

Esta frase vale la pena recordarla:Adapt Pi to your workflows, not the other way around(Haz que Pi se adapte a tu flujo de trabajo, y no tú a Pi).

Arquitectura y paquetes centrales

Pi está compuesto por cuatro paquetes con una jerarquía bien definida, donde la capa superior depende de la inferior.

El comando que usas habitualmentepies solo la puerta de entrada que proporciona el paquete de la capa superior.

Cuatro paquetes centrales

Nombre del paquete	Función	Cuándo se usa por separado
`@earendil-works/pi-coding-agent`	CLI de agente de codificación interactivo, la puerta de entrada que los usuarios instalan y usan directamente	En la gran mayoría de los casos solo se necesita este
`@earendil-works/pi-agent-core`	Runtime del agente, responsable del bucle de invocación de herramientas y la gestión de estado	Cuando quieres crear tu propio agente que no sea de codificación
`@earendil-works/pi-ai`	API de LLM unificada para múltiples proveedores (OpenAI, Anthropic, Google, etc.)	Cuando solo quieres usar una interfaz unificada para llamar a varios modelos
`@earendil-works/pi-tui`	Biblioteca de interfaz de terminal, compatible con renderizado diferencial	Cuando quieres escribir tu propia aplicación de terminal

Cuatro modos de ejecución

Pi no solo puede ejecutarse de forma interactiva; ofrece cuatro modos para adaptarse a diferentes escenarios:

Modo	Descripción	Escenario típico
Interactive (interactivo)	Experiencia completa de interfaz de terminal	Codificación diaria, desarrollo conversacional
Print / JSON	`pi -p "提问"`Salida de una sola vez;`--mode json`flujo de eventos de salida	Automatización de scripts, procesamiento en pipeline
RPC	Comunicación mediante protocolo JSON por stdin/stdout	Integración con programas que no son Node
SDK	Se incrusta como biblioteca en tu aplicación	Integrar capacidades de agente en tu propio producto

Instalación

Pi ofrece múltiples métodos de instalación que cubren macOS, Linux y Windows.

El más común es instalarlo globalmente con npm, aunque también se puede usar el script oficial de un clic.

Método 1: script de un clic (recomendado para principiantes)

Los usuarios de macOS y Linux usan curl:

curl -fsSL https://pi.dev/install.sh | sh

Los usuarios de Windows usan PowerShell:

powershell -c "irm https://pi.dev/install.ps1 | iex"

Método 2: instalación global con npm

Si ya tienes Node.js instalado, basta con instalarlo globalmente con el gestor de paquetes.

Ten en cuenta ese--ignore-scriptsparámetro: omite los scripts del ciclo de vida de instalación de las dependencias. Pi no los necesita para su uso normal, y es más seguro añadirlo.

# npm 安装
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# pnpm 安装
pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent

# bun 安装
bun add -g --ignore-scripts @earendil-works/pi-coding-agent

Verificar la instalación

Después de la instalación, verifica el número de versión para confirmar si fue exitosa:

pi --version

Por ejemplo:

$ pi --version
0.80.6

Desinstalación

La forma de desinstalar depende de cómo lo instalaste originalmente:

# curl 装的或 npm 装的
npm uninstall -g @earendil-works/pi-coding-agent

# pnpm 装的
pnpm remove -g @earendil-works/pi-coding-agent

# bun 装的
bun uninstall -g @earendil-works/pi-coding-agent

Nota: Desinstalar Pi no elimina tu configuración. Los ajustes, credenciales, registros de sesión y paquetes de Pi instalados se conservan en~/.pi/agent/directorio; debes limpiarlos manualmente.

Configurar el proveedor de modelos

Pi no incluye modelos grandes; requiere que proporciones credenciales de acceso de al menos un proveedor de modelos (Provider).

Hay dos formas de configuración: inicio de sesión con suscripción o clave API.

Método 1: inicio de sesión con suscripción (lo más sencillo)

Si ya tienes una suscripción de Claude Pro/Max, ChatGPT Plus/Pro o GitHub Copilot, puedes iniciar sesión y reutilizarla directamente.

Después de iniciar Pi, ejecuta/loginy luego selecciona el proveedor:

# 启动 pi
pi

# 在 pi 里执行登录命令
/login

Hay tres proveedores de suscripción opcionales:

Proveedor	Requisito	Descripción
Claude Pro / Max	Suscripción de Anthropic	El uso de herramientas de terceros se factura por token y no consume la cuota de la suscripción.
ChatGPT Plus / Pro（Codex）	Suscripción de OpenAI	Reconocido oficialmente por OpenAI a través de Codex for OSS
GitHub Copilot	Suscripción de Copilot	Si se indica que el modelo no es compatible, primero debes habilitar el modelo correspondiente en VS Code.

Después de iniciar sesión, las credenciales se guardan en~/.pi/agent/auth.json; se renuevan automáticamente al expirar. Para cerrar sesión usa/logout。

Método 2: clave API (la más flexible)

Pasar la clave API mediante variables de entorno es la forma más universal. Por ejemplo, con la clave de Anthropic:

# 设置环境变量后启动
export ANTHROPIC_API_KEY=sk-ant-...
pi

También puedes ejecutar en Pi/loginy seleccionar un proveedor de tipo clave API para guardar la clave de forma persistente enauth.json。

Variables de entorno de los proveedores habituales

Pi admite más de 15 proveedores; a continuación se enumeran los más comunes:

Proveedor	Variable de entorno	Nombre de la clave en auth.json
Anthropic	`ANTHROPIC_API_KEY`	anthropic
OpenAI	`OPENAI_API_KEY`	openai
Google Gemini	`GEMINI_API_KEY`	google
DeepSeek	`DEEPSEEK_API_KEY`	deepseek
Groq	`GROQ_API_KEY`	groq
Mistral	`MISTRAL_API_KEY`	mistral
xAI	`XAI_API_KEY`	xai
OpenRouter	`OPENROUTER_API_KEY`	openrouter
Hugging Face	`HF_TOKEN`	huggingface

Consejo:auth.jsonLas credenciales en tienen mayor prioridad que las variables de entorno. Si ambas están configuradas, se usaauth.jsoncomo referencia.

Estructura de auth.json

Si deseas administrar las credenciales manualmente, puedes editar directamente~/.pi/agent/auth.jsonEste archivo se crea con permisos 0600 (solo lectura y escritura para el usuario actual):

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "google": { "type": "api_key", "key": "..." }
}

El campo Key también admite tres formatos avanzados para obtener valores desde gestores de contraseñas o variables de entorno:

Formato	Significado	Ejemplo
`"!comando"`	Comienza con signo de exclamación, ejecuta el comando y toma su salida estándar (stdout) como clave.	`"!op read 'op://vault/item/cred'"`
`"$nombre de variable"`	Obtiene el valor de una variable de entorno.	`"$MY_ANTHROPIC_KEY"`
Literal puro	Se usa directamente como clave.	`"sk-ant-..."`

Proveedores de plataforma en la nube

Si usas servicios de modelos en la nube, Pi también admite Azure OpenAI, Amazon Bedrock, Google Vertex AI, Cloudflare, entre otros.

Generalmente requieren configuración adicional de punto de conexión (endpoint), región o nombre de implementación. Por ejemplo, con Azure OpenAI:

# Azure OpenAI 所需的环境变量
export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com

# 可选：API 版本与部署名映射
export AZURE_OPENAI_API_VERSION=2024-02-01
export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4o=my-gpt4o

Configurar el proveedor de DeepSeek

Pi admite proveedores personalizados mediante models.json. Ubicación del archivo de configuración:

Linux / macOS：~/.pi/agent/models.json
Windows：%USERPROFILE%\.pi\agent\models.json

Primero obtén una clave API en la plataforma abierta de DeepSeek:https://platform.deepseek.com/api_keys。

{
  "providers": {
    "deepseek": {
      "baseUrl": "https://api.deepseek.com",
      "api": "openai-completions",
      "apiKey": "$DEEPSEEK_API_KEY",
      "models": [
        {
          "id": "deepseek-v4-pro",
          "name": "DeepSeek V4 Pro",
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "input": ["text"],
          "reasoning": true,
          "cost": {
            "input": 1.74,
            "output": 3.48,
            "cacheRead": 0.145,
            "cacheWrite": 0
          },
          "compat": {
            "requiresReasoningContentOnAssistantMessages": true,
            "thinkingFormat": "deepseek",
            "reasoningEffortMap": {
              "minimal": "high",
              "low": "high",
              "medium": "high",
              "high": "high",
              "xhigh": "max"
            }
          }
        },
        {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4 Flash",
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "input": ["text"],
          "reasoning": true,
          "cost": {
            "input": 0.14,
            "output": 0.28,
            "cacheRead": 0.028,
            "cacheWrite": 0
          },
          "compat": {
            "requiresReasoningContentOnAssistantMessages": true,
            "thinkingFormat": "deepseek",
            "reasoningEffortMap": {
              "minimal": "high",
              "low": "high",
              "medium": "high",
              "high": "high",
              "xhigh": "max"
            }
          }
        }
      ]
    }
  }
}

Configura las variables de entorno:

Usuarios de Linux / Mac:

export DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"

Usuarios de Windows:

$env:DEEPSEEK_API_KEY="<你的 DeepSeek API Key>"

Entra en el directorio del proyecto y ejecuta el comando pi:

cd /path/to/my-project
pi

Ingresa/modelAbre el selector de modelos, elige deepseek y luego selecciona DeepSeek-V4-Pro o DeepSeek-V4-Flash.

Consulta más opciones de configuración en:https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md。

Orden de resolución de credenciales

Cuando Pi necesita credenciales de un proveedor, las busca en el siguiente orden y usa la primera que encuentre:

Prioridad	Origen
1 (la más alta)	Línea de comandos`--api-key`Parámetro
2	`auth.json`Entradas en (clave API o token OAuth)
3	Variables de entorno
4	`models.json`Claves de proveedores personalizados en

Primera ejecución

Después de configurar las credenciales, entra en el directorio de tu proyecto y ejecuta directamentepipara iniciar.

# 进入项目目录
cd /path/to/project

# 启动 pi
pi

Después de iniciar, escribe una frase y presiona Enter, por ejemplo, pídele que analice este repositorio:

Summarize this repository and tell me how to run its checks.

Pi leerá automáticamente los archivos, ejecutará comandos y luego proporcionará un resumen y la forma de verificación.

Aviso de confianza del proyecto

Si en el directorio actual o en un directorio superior hay.pirecursos a nivel de proyecto, como configuración, extensiones o habilidades, Pi te preguntará si confías en el proyecto al iniciarse en modo interactivo.

Esto evita que un repositorio cargue silenciosamente sus extensiones o modifique ajustes sin que lo sepas.

Nota: La decisión de confianza se guarda en~/.pi/agent/trust.jsonEl modo no interactivo (-p、--mode json) no muestra ventanas emergentes; por defecto se rige pordefaultProjectTrusten la configuración global.

¿Cómo funciona el agente?

Cada mensaje que envías hace que Pi inicie un ciclo de agente. Si entiendes este ciclo, entenderás cómo funciona Pi.

El núcleo es el ciclo de turnos del centro: en cada turno, el modelo puede invocar herramientas; Pi ejecuta las herramientas y devuelve los resultados al contexto, luego deja que el modelo continúe hasta que deje de invocar herramientas y dé una respuesta final.

Cuatro herramientas integradas

Por defecto, Pi solo otorga al modelo cuatro herramientas, que cubren las capacidades más esenciales de lectura, escritura y ejecución en programación.

Herramienta	Función	¿Habilitada por defecto?
`read`	Leer el contenido de archivos	Sí
`write`	Crear o sobrescribir archivos	Sí
`edit`	Aplicar modificaciones parciales (parches) a archivos	Sí
`bash`	Ejecutar comandos de shell	Sí
`grep`	Buscar contenido en archivos	No (se debe habilitar mediante la opción de herramientas)
`find`	Buscar archivos según criterios	No (se debe habilitar mediante la opción de herramientas)
`ls`	Listar el contenido de directorios	No (se debe habilitar mediante la opción de herramientas)

Controlar las herramientas disponibles

Puedes controlar con precisión qué herramientas puede usar el modelo mediante parámetros de la línea de comandos.

Esto es útil cuando necesitas limitar las capacidades del agente, por ejemplo, permitirle solo revisar código sin modificarlo:

# 只读模式：只允许读取和搜索类工具
pi --tools read,grep,find,ls -p "审查这段代码"

# 禁用某个工具，其余保留
pi --exclude-tools ask_question

# 关闭所有内置工具，只保留扩展提供的工具
pi --no-builtin-tools -e ./my-extension.ts

# 完全禁用工具，纯对话
pi --no-tools -p "解释一下这个概念"

Recordatorio: Pi se ejecuta en tu directorio de trabajo actual y puede modificar tus archivos. Se recomienda usarlo con control de versiones como git para poder revertir cambios en cualquier momento.

Usar AGENTS.md para dar instrucciones al proyecto

AGENTS.md es el archivo de instrucciones del proyecto para Pi; le indica al modelo qué reglas tiene el proyecto, cómo ejecutarlo y qué tener en cuenta.

Su función es similar a CLAUDE.md de Claude Code, y Pi admite ambos nombres de archivo.

Escribir un AGENTS.md

Crea en la raíz del proyectoAGENTS.mdy escribe las reglas que deseas que el modelo siga:

# 项目指令

- 改完代码后运行 `npm run check`。
- 不要在本地跑生产环境的数据库迁移。
- 回答尽量简洁。

¿De dónde carga Pi las instrucciones?

Al iniciarse, Pi carga archivos de instrucciones desde varias ubicaciones, de mayor a menor alcance:

Ubicación	Alcance	Descripción
`~/.pi/agent/AGENTS.md`	Global	Instrucciones generales que aplican a todos tus proyectos.
Del directorio padre`AGENTS.md`	A nivel de proyecto	Se busca hacia arriba desde el directorio actual, nivel por nivel.
Del directorio actual`AGENTS.md`	A nivel de proyecto	Las instrucciones más específicas y de mayor prioridad.

Para los nombres de archivo, usaAGENTS.mdoCLAUDE.mdcualquiera de los dos; Pi los reconocerá.

Modificar el prompt del sistema

AGENTS.md son instrucciones adicionales al mensaje del sistema predeterminado. Si deseas un control más profundo, puedes reemplazar todo el mensaje del sistema.

En el proyecto, colocar.pi/SYSTEM.mdreemplazará el mensaje del sistema predeterminado; colocar.pi/APPEND_SYSTEM.mdes para añadirlo (el equivalente global está en~/.pi/agent/los archivos del mismo nombre en ese directorio).

Nota: Después de cambiar el archivo de instrucciones, recuerda ejecutar/reloadrecargar, o reiniciar Pi, para que las nuevas instrucciones surtan efecto.

Operaciones comunes en el modo interactivo

El modo interactivo es la forma más utilizada de Pi; dominar algunas operaciones clave te permitirá usarlo de manera eficiente.

Referenciar archivos: @

Escribe en el editor@y aparecerá una búsqueda aproximada de archivos del proyecto; al seleccionarlo, el contenido del archivo se enviará al modelo como contexto.

También puedes incluir archivos directamente al iniciar desde la línea de comandos:

# 启动时带上一个文件
pi @README.md "总结一下这个文件"

# 带上多个文件一起审查
pi @src/app.ts @src/app.test.ts "一起审查这两个文件"

Ejecutar comandos de shell: !

En el editor, escribe comandos que comiencen con!y se ejecutarán directamente y su salida se enviará al modelo:

# 运行命令，输出会进入模型上下文
!npm run lint

# 两个感叹号：运行但不把输出加进模型上下文
!!npm run build

Cambiar el modelo y el nivel de razonamiento

Pi permite cambiar de modelo y nivel de razonamiento durante una sesión para adaptarse a la complejidad de distintas tareas.

Acción	Atajo / Comando	Descripción
Abrir el selector de modelos	`/model`o Ctrl+L	Elige uno de todos los modelos disponibles
Cambiar la intensidad de razonamiento	Shift+Tab	Cambia cíclicamente entre off / minimal / low / medium / high / xhigh / max
Recorrer cíclicamente los modelos favoritos	Ctrl+P / Shift+Ctrl+P	Cambiar rápidamente entre los modelos que hayas preseleccionado

Al iniciar también puedes especificar directamente el modelo y la intensidad de razonamiento:

# 指定厂商和模型
pi --provider openai --model gpt-4o "帮我重构"

# 用 厂商/模型 的写法
pi --model openai/gpt-4o "帮我重构"

# 用 名称:思考强度 的简写
pi --model sonnet:high "解决这个复杂问题"

# 限定可在 Ctrl+P 里循环的模型
pi --models "claude-*,gpt-4o"

Trucos de entrada y edición

Operación	Método	Descripción
Entrada multilínea	Shift+Enter (en Windows Terminal, Ctrl+Enter)	Insertar un salto de línea en un mensaje
Autocompletado de rutas	Tab	Completa rutas de archivos
Pegar imagen	Ctrl+V (en Windows, Alt+V)	También se pueden arrastrar imágenes a la terminal
Copiar respuesta	Ctrl+X	Copia el último mensaje del asistente
Editor externo	Ctrl+G	Abre $VISUAL / $EDITOR para editar textos largos

Interrumpir durante la ejecución

Mientras el agente trabaja, no tienes que esperar sin hacer nada: puedes insertar mensajes en cualquier momento.

Atajo	Comportamiento	Cuándo usarlo
Enter	Mensaje de redirección: se entrega inmediatamente después de que termine la herramienta actual e interrumpe las herramientas restantes.	Para corregir el rumbo a tiempo cuando notas que va mal encaminado
Alt+Enter	Mensaje posterior: se entrega cuando el agente haya terminado por completo.	Cuando quieres añadir un nuevo requisito
Escape	Detener el trabajo actual y devolver los mensajes en cola al editor	Cuando quieres detenerte y reorganizar

Nota: en Windows Terminal, Alt+Enter alterna el modo de pantalla completa por defecto. Las teclas para los mensajes de redirección y posteriores se pueden configurar en los ajustes mediantesteeringModeyfollowUpModecambiarlas.

Referencia rápida de comandos de barra

Escribe en el editor/y aparecerá el autocompletado de comandos. Estos son los comandos de barra diagonal más utilizados.

Comando	Función
`/login` / `/logout`	Gestiona credenciales OAuth o API Key
`/model`	Cambiar de modelo
`/scoped-models`	Configura qué modelos participan en el ciclo de Ctrl+P
`/settings`	Ajusta la intensidad de razonamiento, el tema, el método de entrega de mensajes, etc.
`/resume`	Elige una de las sesiones históricas para continuar
`/new`	Iniciar una nueva sesión
`/name <名称>`	Poner un nombre visible a la sesión actual
`/session`	Ver el archivo de sesión, ID, número de mensajes, uso de tokens y coste
`/tree`	Saltar a cualquier nodo del árbol de sesiones y continuar desde allí
`/fork`	Bifurcar una nueva sesión desde un mensaje histórico
`/clone`	Copiar la rama actual como una nueva sesión
`/compact [提示]`	Comprimir manualmente el contexto, con instrucciones personalizadas opcionales
`/copy`	Copiar el último mensaje del asistente al portapapeles
`/export [文件]`	Exportar la sesión como HTML o JSONL
`/import <文件>`	Importar y restaurar una sesión desde un archivo JSONL
`/share`	Subir como Gist privado de GitHub y generar un enlace HTML compartible
`/reload`	Recargar atajos de teclado, extensiones, habilidades, prompts, temas y archivos de contexto
`/trust`	Guardar la decisión de confianza para el proyecto actual
`/hotkeys`	Mostrar todos los atajos de teclado
`/changelog`	Ver el historial de versiones
`/quit`	Salir de Pi

Gestión de sesiones: historial en árbol

Las sesiones de Pi no son una línea recta, sino un árbol.

Esto significa que, si te bifurcas en cualquier nodo histórico, no pierdes la rama original; todas las ramas se guardan en el mismo archivo de sesión.

¿Dónde se guardan las sesiones?

Las sesiones se guardan automáticamente en~/.pi/agent/sessions/, organizadas por directorio de trabajo.

Restaurar o explorar sesiones históricas desde la línea de comandos:

# 继续最近一次会话
pi -c

# 浏览并选择一个历史会话
pi -r

# 给会话起个名字，方便日后查找
pi --name "my task"

# 打开指定的会话文件或 ID
pi --session <path|id>

# 临时会话，不保存
pi --no-session

Navegar por el árbol de sesiones

usar/treePuedes abrir la vista de árbol de sesiones y saltar a cualquier nodo histórico para continuar.

Continuar desde aquí crea una nueva rama; la rama original permanece intacta.

Bifurcación (fork) y clonación

Comando	Comportamiento	Diferencia
`/fork`	Bifurcar una nueva sesión desde un mensaje de usuario anterior	Reiniciar desde un punto intermedio del historial
`/clone`	Copiar la rama activa actual como una nueva sesión	Crear una copia basada en el estado más reciente actual

Comprimir el contexto

Cuando la conversación se alarga y se acerca al límite de contexto del modelo, Pi comprime automáticamente los mensajes más antiguos en un resumen.

También puedes activarla manualmente con/compactpara activarla, y además puedes incluir una instrucción personalizada que le indique qué puntos clave debe conservar al comprimir:

# 在 pi 里手动压缩，并要求保留最近改动
/compact 重点保留最近的改动和错误处理

Exportar y compartir

Exporta la sesión como HTML para archivarla o mostrarla:

# 导出为 HTML 文件
/export my-session.html

# 上传为私有 GitHub Gist，得到分享链接
/share

Modo no interactivo e integración

Pi no solo sirve para conversaciones interactivas; también se puede usar como herramienta de línea de comandos, flujo de eventos, servicio RPC y biblioteca SDK.

Consulta única: modo print

usar-pHaz que Pi responda y salga; ideal para invocarlo desde scripts:

# 直接提问
pi -p "总结一下这个代码库"

# 配合管道，把内容喂给 Pi
cat README.md | pi -p "总结这段文字"

# 带图片提问
pi -p @screenshot.png "这张图里是什么？"

Flujo de eventos: modo JSON

--mode jsonGenera todos los eventos como líneas JSON, lo que facilita que los programas los analicen:

# 输出 JSON 事件流
pi --mode json -p "列出 src 下所有 .ts 文件"

Integración de procesos: modo RPC

--mode rpcUtiliza un protocolo JSON a través de stdin/stdout, ideal para que programas que no son de Node (por ejemplo, Python, Go) controlen Pi.

Exportar sesiones existentes

Sin iniciar una nueva sesión, exporta directamente un archivo de sesión existente como HTML:

# 把会话文件导出为 HTML
pi --export session.jsonl output.html

Modo SDK

Si quieres integrar las capacidades de Pi en tu propia aplicación de Node, puedes usar el modo SDK para importarlo como biblioteca.

Es una forma de integración más estrecha que RPC. Consulta el capítulo de SDK en la documentación oficial:https://pi.dev/docs/latest/sdk。

Extensiones (Extensions)

Las extensiones son el núcleo de la extensibilidad de Pi. Son módulos de TypeScript que pueden suscribirse a eventos del ciclo de vida, registrar herramientas personalizadas y añadir comandos y atajos de teclado.

Las extensiones se cargan con jiti, así que puedes escribir TypeScript directamente, sin necesidad de compilar.

¿Dónde se colocan las extensiones?

Ubicación	Alcance
`~/.pi/agent/extensions/*.ts`	Global: afecta a todos los proyectos
`.pi/extensions/*.ts`	Nivel de proyecto: solo afecta al proyecto actual

También puede ser en forma de subdirectorio (扩展名/index.ts), o con unpackage.jsonpaquete completo.

Un ejemplo mínimo de extensión

La siguiente extensión demuestra tres cosas: notificación al inicio, interceptación de comandos peligrosos, y registro de una herramienta personalizada y un comando.

// 文件路径：~/.pi/agent/extensions/my-extension.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

// 扩展导出一个默认工厂函数，接收 ExtensionAPI
export default function (pi: ExtensionAPI) {

  // 1. 监听 session_start 事件：会话启动时弹个通知
  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify("扩展已加载！", "info");
  });

  // 2. 监听 tool_call 事件：拦截危险的 bash 命令
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      // 弹确认框，用户拒绝就阻止执行
      const ok = await ctx.ui.confirm("危险操作！", "允许执行 rm -rf 吗？");
      if (!ok) return { block: true, reason: "被用户阻止" };
    }
  });

  // 3. 注册一个自定义工具，模型可以调用它
  pi.registerTool({
    name: "greet",
    label: "打招呼",
    description: "按名字向某人打招呼",
    parameters: Type.Object({
      name: Type.String({ description: "要打招呼的名字" }),
    }),
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      return {
        content: [{ type: "text", text: `你好，${params.name}！` }],
        details: {},
      };
    },
  });

  // 4. 注册一个斜杠命令 /hello
  pi.registerCommand("hello", {
    description: "打个招呼",
    handler: async (args, ctx) => {
      ctx.ui.notify(`你好 ${args || "world"}！`, "info");
    },
  });
}

Después de escribirla, usa el parámetro-epara cargarla temporalmente y probarla:

# 临时加载一个扩展来测试
pi -e ./my-extension.ts

¿Qué pueden hacer las extensiones?

Las capacidades de las extensiones van mucho más allá de lo anterior; pueden intervenir en casi todos los aspectos del flujo de trabajo de Pi:

Capacidad	Método correspondiente	Uso típico
Registrar herramientas personalizadas	`pi.registerTool()`	Permitir que el modelo llame a tus interfaces de negocio
Registrar comandos	`pi.registerCommand()`	Añadir tus propios comandos de barra diagonal
Registrar atajos de teclado	`pi.registerShortcut()`	Vincular atajos de teclado personalizados
Interceptar llamadas a herramientas	`tool_call`Eventos	Confirmación de permisos, reescritura de comandos
Modificar el contexto	`context`Eventos	Filtrar el historial, inyectar contenido RAG
Inyectar mensajes	`pi.sendMessage()`	Complementar dinámicamente el contexto
Registrar proveedores	`pi.registerProvider()`	Conectar con una puerta de enlace de modelos privada
Personalizar la interfaz de usuario	`ctx.ui`Serie	Diálogos, barra de estado, componentes

Nota: en el repositorio de Pi hay más de 50 extensiones de ejemplo que cubren subagentes, modo de planificación, puerta de permisos, ejecución SSH, sandbox, etc.; es la mejor referencia para aprender a desarrollar extensiones.

Habilidades (Skills)

Las habilidades son otro tipo de paquete de capacidades reutilizable. La diferencia con las extensiones es que las habilidades son principalmente instrucciones y scripts destinados al modelo, que se cargan bajo demanda.

Pi implementa el estándar Agent Skills, por lo que también puede utilizar directamente las habilidades de herramientas como Claude Code, OpenAI Codex, etc.

Cómo funcionan las habilidades

Las habilidades siguen el principio de divulgación progresiva (progressive disclosure).

Al iniciar, Pi solo incluye el nombre y la descripción de cada habilidad en el aviso del sistema; cuando una tarea coincide, el modelo usa lareadherramienta para cargar la descripción completa de la habilidad.

De esta manera, se pueden tener muchas habilidades sin saturar el contexto desde el principio.

¿Dónde se colocan las habilidades?

Ubicación	Alcance
`~/.pi/agent/skills/`	Global
`~/.agents/skills/`	Global (compartida entre herramientas)
`.pi/skills/`	Nivel de proyecto (requiere que el proyecto sea de confianza)
`.agents/skills/`	Nivel de proyecto (compartida entre herramientas)

Estructura de las habilidades

Una habilidad es un directorio que contieneSKILL.md; el resto de archivos se pueden organizar libremente:

my-skill/
├── SKILL.md              # 必需：前置信息 + 指令
├── scripts/              # 辅助脚本
│   └── process.sh
├── references/           # 按需加载的详细文档
│   └── api-reference.md
└── assets/
    └── template.json

Cómo escribir SKILL.md

En la parte superior de SKILL.md está la información frontal (frontmatter), y debajo está el cuerpo de instrucciones para el modelo:

---
name: my-skill
description: 这个技能做什么、什么时候用。要写具体。
---

# My Skill

## Setup

首次使用前运行一次：
```bash
cd /path/to/skill && npm install
```

## Usage

```bash
./scripts/process.sh <input>
```

Los dos campos más importantes en la información frontal:

Campo	¿Es obligatorio?	Descripción
`name`	Obligatorio	Máximo 64 caracteres; solo se permiten letras minúsculas, números y guiones
`description`	Obligatorio	Máximo 1024 caracteres; determina cuándo el modelo carga esta habilidad. Debe escribirse de forma específica

Aviso:descriptionQue esté bien o mal escrito determina directamente si el modelo usará esta habilidad en el momento adecuado. Escribir «Procesar archivos PDF, extraer texto y tablas, completar formularios, combinar múltiples PDF» es mucho mejor que escribir «Ayudar a procesar PDF».

Invocar habilidades manualmente

El modelo no siempre carga la habilidad automáticamente. Puedes usar/skill:名称para forzar la carga y ejecución:

# 加载并执行技能
/skill:brave-search

# 带参数加载技能
/skill:pdf-tools extract

Gestión de paquetes de Pi

Las extensiones, habilidades, plantillas de prompts y temas se pueden empaquetar como paquetes de Pi e instalarse compartiéndolos a través de npm o git.

Pi incluye un conjunto de comandos de gestión de paquetes que te permite ampliar capacidades como si instalaras complementos.

Instalación y desinstalación

# 从 npm 安装一个包
pi install npm:@foo/pi-tools

# 从 git 仓库安装
pi install git:github.com/badlogic/pi-doom

# 项目本地安装（加 -l）
pi install npm:@foo/pi-tools -l

# 卸载
pi remove npm:@foo/pi-tools

Actualizar y consultar

Comando	Función
`pi list`	Listar los paquetes instalados
`pi update`	Actualizar solo Pi
`pi update --all`	Actualizar Pi y todos los paquetes
`pi update --extensions`	Actualizar solo los paquetes, sin tocar Pi
`pi update --extension <源>`	Actualizar un paquete específico
`pi config`	Habilitar o deshabilitar los recursos de un paquete

Notas de seguridad

La seguridad es una parte que debes entender antes de usar Pi. El modelo de seguridad de Pi difiere del de muchas herramientas de agente y requiere tu cooperación activa.

Sin sandbox integrado

Pi No incluye un sandbox integrado; se ejecuta con la identidad del usuario que lo inició y posee todos los permisos de ese usuario.

Las herramientas integradas pueden leer y escribir archivos y ejecutar comandos de shell; las extensiones son módulos de TypeScript con los mismos permisos que el proceso de Pi.

Esto es intencional: Pi debe trabajar sobre el código fuente local, invocar la cadena de herramientas del proyecto e integrarse en el entorno de desarrollo; un sandbox incompleto dentro del proceso haría creer que es un límite de seguridad, cuando en realidad aún depende del shell, el sistema de archivos y las credenciales del host.

Importante: el aislamiento real debe venir del sistema operativo o de los límites de contenedor/virtualización, no del interior de Pi.

Confianza del proyecto

La confianza del proyecto determina si Pi carga la configuración, los recursos, las extensiones y los paquetes a nivel de proyecto.

Cuando en un directorio existen.pi/settings.json、.pi/extensions、.pi/skills、.pi/SYSTEM.mdentre otros, Pi pedirá que confíes antes de cargarlos.

Nivel de confianza	Comportamiento	Método de configuración
`ask`(predeterminado)	Pregunta de forma interactiva; en modo no interactivo ignora los recursos del proyecto	en settings.json`defaultProjectTrust`
`always`	Confiar siempre en los recursos del proyecto	Igual que arriba, o con`-a` / `--approve`
`never`	No confiar nunca; ignorar los recursos del proyecto	Igual que arriba, o con`-na` / `--no-approve`

La decisión de confianza se guarda en~/.pi/agent/trust.json, registrada por ruta de directorio; la decisión del directorio padre más cercano tiene prioridad.

Nota: la confianza del proyecto es solo un «guardián de carga de entrada»; evita que el repositorio modifique silenciosamente tu configuración o extensiones, perono puede hacer que el código, los prompts o las salidas del modelo no confiables sean seguros. La inyección de prompts en archivos del repositorio, comentarios y documentos es un riesgo inherente de un agente local, y Pi no puede bloquearla de forma fiable.

Manejar tareas no confiables o desatendidas

Para repositorios no confiables, código generado que requiere supervisión estrecha o automatización desatendida, se recomienda oficialmente ejecutar Pi en un entorno aislado.

Prácticas recomendadas:

Coloca todo elpiproceso en un contenedor, máquina virtual o sandbox remoto
Monta solo las rutas del espacio de trabajo a las que el agente debe tener acceso
A menos que sea necesario, no montes el~/.pi/agentdel host (contiene tus credenciales y sesiones)
Pasa solo las claves de API mínimas necesarias, o usa credenciales de corta duración
Limita el acceso a la red cuando la tarea no lo requiera
Antes de copiar los resultados de vuelta al sistema confiable, revisa el diff y las salidas

Aviso: si montas el espacio de trabajo del host en el contenedor en modo lectura-escritura, las escrituras dentro del contenedor seguirán modificando los archivos del host. Para una protección más fuerte contra escrituras accidentales, usa montajes de solo lectura o copia los archivos hacia y desde el sandbox.

Recursos y comunidad

Recursos oficiales

Repositorio de GitHub:github.com/earendil-works/pi
Sitio web oficial:pi.dev
Documentación oficial:pi.dev/docs/latest
Paquete npm:@earendil-works/pi-coding-agent

Otras extensiones

Herramientas de agentes

Implementación de agentes inteligentes en Python