Construcción del system prompt

源码版本v0.73.1

system-prompt.ts es el taller de ensamblaje del system prompt por defecto de pi. Un archivo, una función buildSystemPrompt, que combina lista de herramientas, guidelines, rutas de la documentación de pi, archivos de contexto del proyecto, skills, fecha y cwd en el string final. createAgentSession no la invoca directamente: es AgentSession quien la reconstruye antes de cada prompt según las herramientas activas, garantizando que el prompt se sincronice al añadir o quitar herramientas.

Responsabilidades

1. Ensamblar prompt por defecto: buildSystemPrompt sin customPrompt va por la ruta por defecto, generando un prompt completo que empieza con "You are an expert coding assistant operating inside pi". Ver packages/coding-agent/src/core/system-prompt.ts:28-80 y packages/coding-agent/src/core/system-prompt.ts:131-171.
2. Ruta customPrompt: si se pasa customPrompt, se salta la plantilla por defecto y sólo se añaden contextFiles, skills, fecha y cwd. Ver packages/coding-agent/src/core/system-prompt.ts:53-80.
3. Lista de herramientas y guidelines: según selectedTools decide qué herramientas son visibles y genera guidelines dinámicos (p. ej. si bash y grep coexisten, sugiere preferir grep). Ver packages/coding-agent/src/core/system-prompt.ts:89-129.
4. Inyección de prompt snippet: cada herramienta tiene un promptSnippet de una línea, descripción breve, que se ensambla en la lista "Available tools", y el LLM decide a partir de ahí para qué sirve cada una. Ver packages/coding-agent/src/core/system-prompt.ts:89-92.
5. Adjuntar skills: formatSkillsForPrompt convierte las skills visibles (no disableModelInvocation) en un bloque XML <available_skills>. Ver packages/coding-agent/src/core/system-prompt.ts:162-165.
6. Auto-guía a la documentación: el prompt menciona las rutas internas de la documentación de pi (readme, docs, examples) e indica al LLM que las lea si el usuario pregunta por pi. Ver packages/coding-agent/src/core/system-prompt.ts:141-147.

Motivación de diseño

¿Por qué no dejar que AgentSession retenga el string del prompt? Porque las herramientas son dinámicas: el usuario puede hacer /tools a mitad de sesión para añadir o quitar, y las extensiones pueden registrar nuevas. Si el prompt fuera un string estático, tras cambiar las herramientas el LLM seguiría el prompt viejo y llamaría a herramientas ya deshabilitadas. buildSystemPrompt se regenera en cada invocación, garantizando alineación estricta con el conjunto activo.

¿Por qué distinguir la ruta por defecto y la custom? El prompt por defecto es la versión afinada por pi, con lista de herramientas, guidelines y auto-guía a la documentación; el prompt custom es la versión totalmente personalizada del usuario o extensión, que sólo quiere añadir contextFiles y skills. Ambas rutas comparten la lógica de adjuntar contextFiles, skills, fecha y cwd, pero la ruta por defecto añade toolsList y guidelines.

Los guidelines dinámicos merecen mención: si bash y grep/find/ls están activos a la vez, el prompt sugiere "Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)"; si sólo está bash sin grep/find/ls, sugiere "Use bash for file operations like ls, rg, find". Así el LLM elige caminos eficientes según el conjunto de herramientas disponible.

Archivos clave

• packages/coding-agent/src/core/system-prompt.ts:8-25 — BuildSystemPromptOptions, todas las entradas opcionales.
• packages/coding-agent/src/core/system-prompt.ts:28-52 — Firma de buildSystemPrompt y pre-procesamiento: resuelve cwd, fecha, contextFiles, skills.
• packages/coding-agent/src/core/system-prompt.ts:53-80 — Ruta de custom prompt.
• packages/coding-agent/src/core/system-prompt.ts:89-129 — Lista de herramientas y generación de guidelines dinámicos, con checks hasBash/hasGrep/hasFind/hasLs.
• packages/coding-agent/src/core/system-prompt.ts:131-147 — Cuerpo de la plantilla por defecto, incluye el tramo de auto-guía a la doc de pi.
• packages/coding-agent/src/core/system-prompt.ts:149-171 — appendSystemPrompt, contextFiles, skills, fecha, cwd.

Guidelines dinámicos, deduplicados vía set:

// packages/coding-agent/src/core/system-prompt.ts:105-129
const hasBash = tools.includes("bash");
const hasGrep = tools.includes("grep");
const hasFind = tools.includes("find");
const hasLs = tools.includes("ls");

if (hasBash && !hasGrep && !hasFind && !hasLs) {
	addGuideline("Use bash for file operations like ls, rg, find");
} else if (hasBash && (hasGrep || hasFind || hasLs)) {
	addGuideline("Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)");
}

for (const guideline of promptGuidelines ?? []) {
	const normalized = guideline.trim();
	if (normalized.length > 0) {
		addGuideline(normalized);
	}
}

// Always include these
addGuideline("Be concise in your responses");
addGuideline("Show file paths clearly when working with files");

Al final del prompt por defecto se añaden fecha y cwd al final, a propósito para que el LLM los note:

// packages/coding-agent/src/core/system-prompt.ts:167-171
if (hasRead && skills.length > 0) {
	prompt += formatSkillsForPrompt(skills);
}

// Add date and working directory last
prompt += `\nCurrent date: ${date}`;
prompt += `\nCurrent working directory: ${promptCwd}`;

return prompt;

Flujo de datos

Flujo de construcción del prompt:

Límites y fallos

• toolsList vacío: si visibleTools está vacío se muestra (none), sin lanzar; el LLM sabe que no hay herramientas integradas. Ver packages/coding-agent/src/core/system-prompt.ts:91-92.
• Skills sólo si read disponible: como las skills requieren read para leer el archivo, sin read la lista confundiría al LLM. Ver packages/coding-agent/src/core/system-prompt.ts:70-73 y packages/coding-agent/src/core/system-prompt.ts:162-165.
• customPrompt también respeta el check de read: customPromptHasRead = !selectedTools || selectedTools.includes("read"). Ver packages/coding-agent/src/core/system-prompt.ts:70-73.
• Cwd path a posix: promptCwd = resolvedCwd.replace(/\\/g, "/"), las rutas Windows también usan barras, evitando que el LLM interprete las barras invertidas como escapes. Ver packages/coding-agent/src/core/system-prompt.ts:39-40.
• Deduplicación de guidelines: guidelinesSet evita duplicados cuando promptGuidelines trae repetidos. Ver packages/coding-agent/src/core/system-prompt.ts:96-103.

Resumen

buildSystemPrompt es el taller de ensamblaje del prompt: genera guidelines dinámicos según el conjunto de herramientas; las rutas custom y por defecto comparten la lógica de append de contextFiles/skills/fecha/cwd. La carga y formateo de skills en sistema de skills; la conversión de mensajes en tipos de mensaje y convertToLlm; el propio conjunto de herramientas en conjunto de herramientas read/bash/edit/write/grep/find/ls.