pi 架构拆解

Français

简体中文
English
日本語
Español
Deutsch
繁體中文

Français

简体中文
English
日本語
Español
Deutsch
繁體中文

Appearance

Construction du system prompt ​

源码版本v0.73.1

system-prompt.ts est l'atelier d'assemblage du system prompt par défaut de pi. Un seul fichier, une seule fonction buildSystemPrompt, qui concatène la liste d'outils, les guidelines, les chemins de docs pi, les fichiers de contexte projet, les skills, la date et le cwd en une chaîne de prompt finale. createAgentSession ne l'appelle pas directement — c'est AgentSession qui la reconstruit avant chaque prompt en fonction des outils actuellement actifs, pour garantir que le prompt reste synchro quand des outils sont ajoutés ou retirés.

Responsabilités ​

  1. Assembler le prompt par défaut : buildSystemPrompt sans customPrompt emprunte la voie par défaut, génère le prompt complet commençant par « You are an expert coding assistant operating inside pi ». Voir packages/coding-agent/src/core/system-prompt.ts:28-80 et packages/coding-agent/src/core/system-prompt.ts:131-171.
  2. Chemin customPrompt : quand customPrompt est fourni, on saute le template par défaut et on ne fait qu'ajouter contextFiles, skills, date, cwd. Voir packages/coding-agent/src/core/system-prompt.ts:53-80.
  3. Liste d'outils et guidelines : selon selectedTools, décide quels outils sont visibles et génère dynamiquement les guidelines (par ex. si bash + grep sont tous deux présents, suggère de privilégier grep). Voir packages/coding-agent/src/core/system-prompt.ts:89-129.
  4. Injection de prompt snippet : chaque outil a un promptSnippet d'une ligne, assemblé dans la liste « Available tools » ; le LLM s'en sert pour juger de l'usage de chaque outil. Voir packages/coding-agent/src/core/system-prompt.ts:89-92.
  5. Ajout des skills : formatSkillsForPrompt transforme les skills visibles (non disableModelInvocation) en bloc XML <available_skills>. Voir packages/coding-agent/src/core/system-prompt.ts:162-165.
  6. Auto-référence à la doc : le prompt indique les chemins de la doc pi elle-même (readme, docs, examples) et demande au LLM d'aller les lire quand l'utilisateur pose une question sur pi. Voir packages/coding-agent/src/core/system-prompt.ts:141-147.

Motifs de conception ​

Pourquoi AgentSession ne détient-il pas directement la chaîne de prompt ? Parce que l'ensemble d'outils est dynamique — l'utilisateur peut faire /tools en plein milieu de session pour en ajouter ou en retirer, et les extensions peuvent aussi enregistrer de nouveaux outils. Si le prompt était une chaîne statique, le LLM continuerait à appeler des outils déjà désactivés selon l'ancien prompt. buildSystemPrompt régénère à chaque appel, garantissant un alignement strict entre prompt et ensemble d'outils actifs.

Pourquoi distinguer le prompt par défaut et le chemin customPrompt ? Le prompt par défaut est la version officielle tunée par pi, qui inclut la liste d'outils, les guidelines et l'auto-référence à la doc ; le custom prompt est une version entièrement personnalisée fournie par l'utilisateur ou une extension, qui ne veut qu'ajouter contextFiles et skills. Les deux chemins partagent la logique d'ajout de contextFiles, skills, date, cwd, mais le chemin par défaut ajoute en plus l'assemblage de toolsList et guidelines.

La dynamisation des guidelines mérite une mention : si bash et grep/find/ls sont simultanément activés, le prompt suggère « Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore) » ; si bash est seul sans grep/find/ls, il suggère « Use bash for file operations like ls, rg, find ». Cela permet au LLM de toujours emprunter le chemin efficace quel que soit l'ensemble d'outils.

Fichiers clés ​

Génération dynamique des guidelines avec déduplication par Set :

typescript
// 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");

La fin du prompt par défaut ajoute date et cwd, placés volontairement en dernier pour attirer l'attention du LLM :

typescript
// 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;

Flux de données ​

Construction du prompt :

Limites et cas d'échec ​

Synthèse ​

buildSystemPrompt est l'atelier d'assemblage du prompt, génère dynamiquement les guidelines selon l'ensemble d'outils courant, et les deux chemins (custom et par défaut) partagent la logique d'ajout de contextFiles/skills/date/cwd. Pour le chargement et le formatage des skills, voir système de skills ; pour la conversion des messages, voir types de messages et convertToLlm ; pour l'ensemble d'outils lui-même, voir ensemble d'outils read/bash/edit/write/grep/find/ls.