path_pi

Meine öffentliche Pi-Konfiguration, Agent Skills und Integrationstoolset. Der Kern des Repos ist derzeit pi-agent-mcp: MCP-Hosts wie Claude Code, Codex usw. können unabhängige Aufgaben an mehrere persistente, kontextwiederverwendbare Pi-Sessions delegieren.

Repository-Inhalt

skills/pi-agent/       # Claude Code/Codex 调用 MCP 的 Agent Skill
src/                   # pi-agent-mcp TypeScript 源码
scripts/install.sh     # 构建并配置 Skill + MCP Host
examples/              # 不含真实凭据的 Pi 配置样例
docs/INSTALL.zh-CN.md  # 中文安装、认证、升级与卸载指南

Related MCP server: pokeclaw

Schnellinstallation

git clone https://github.com/a809384377/path_pi.git
cd path_pi
./scripts/install.sh             # 自动配置检测到的 Claude Code/Codex
# 或：./scripts/install.sh --host claude|codex|all

Erfordert Node.js >=22.19 <26, Pi 0.84.1 oder eine kompatible Version sowie mindestens ein authentifiziertes Pi-Modell. Vollständige Schritte finden Sie im Chinesischen Installations- und Authentifizierungsleitfaden.

Das Repository enthält nur desensibilisierte Beispiele, keine lokale auth.json, echte models.json, API-Schlüssel, GitHub-Tokens oder Pi-Sessions. Kopieren Sie diese privaten Dateien nicht in öffentliche Repositories.

pi-agent-mcp

pi-agent-mcp stellt wiederverwendbare Pi-Coding-Agent-Sessions für Claude Code, Codex und andere MCP-Clients bereit.

Claude Code, Codex und andere lokale MCP-Hosts teilen sich standardmäßig ein gemeinsames Registry unter ~/.pi/agent-mcp/. Jede logische Session hat einen unabhängigen dauerhaften Datensatz und kernelgestützte logische/native Eigentumssperren, sodass verschiedene MCP-Server gleichzeitig an verschiedenen Sessions arbeiten können, ohne den Registry-Zustand zu überschreiben.

Jede residente Session besitzt einen pi --mode rpc-Prozess. Wenn eine Aufgabe abgeschlossen ist, bleibt Pi im Leerlauf und behält beide Eigentumssperren, wodurch die Konversation für das nächste pi_send erhalten bleibt. Es gibt bewusst keine Online-Übergabe einer im Leerlauf befindlichen residenten Session: Ein anderer MCP-Host erhält session_in_use, bis der Eigentümer ordnungsgemäß herunterfährt.

Anforderungen

• macOS oder Linux, x64 oder arm64; Windows und Netzwerkdateisysteme werden nicht unterstützt

• Node.js >=22.19 <26

• pi installiert und auf PATH verfügbar (das v2-Protokoll zielt auf Pi 0.84.1 oder kompatibles Verhalten)

• Ein konfiguriertes Pi-Modell/Provider

Das Eigentum verwendet die gepinnte fs-ext-extra-prebuilt@2.2.12-Kernel-flock-Bindung. Wenn die Bindung auf der unterstützten Matrix nicht geladen werden kann, schlägt der Start oder der Tool-Aufruf mit ownership_unavailable fehl; es gibt keinen PID/Lease-Fallback.

Installation und Build

npm install
npm run build

Der MCP-Einstiegspunkt ist dist/src/index.js. Der Server verwendet stdio: stdout ist für MCP-Nachrichten reserviert, Diagnosen gehen an stderr.

Claude Code konfigurieren

Registrieren Sie den gebauten Server mit einem absoluten Pfad. Setzen Sie für die normale gemeinsame Nutzung kein aufruferspezifisches Zustandsverzeichnis:

claude mcp add --scope user --transport stdio \
  --env "PI_AGENT_MCP_PI_EXECUTABLE=$(command -v pi)" \
  pi-agent -- "$(command -v node)" "/absolute/path/to/path_pi/dist/src/index.js"

Codex konfigurieren

Fügen Sie denselben Server zu ~/.codex/config.toml hinzu, ebenfalls ohne Zustandsverzeichnis-Override:

[mcp_servers.pi_agent]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/path_pi/dist/src/index.js"]

[mcp_servers.pi_agent.env]
PI_AGENT_MCP_PI_EXECUTABLE = "/absolute/path/to/pi"

Beide Clients entdecken nun dieselben Sessions über ~/.pi/agent-mcp/. Sie können Aufgaben auf verschiedenen Sessions parallel ausführen. Nur ein MCP-Server kann eine bestimmte logische oder native Pi-Session gleichzeitig besitzen.

Optionale Isolierung

PI_AGENT_MCP_STATE_DIR=/absolute/private/path erstellt ein absichtlich isoliertes Registry für Tests oder fortgeschrittene Setups. Beliebige explizite Wurzeln importieren oder konsolidieren niemals die kanonischen oder Legacy-Wurzeln. Die bekannten alten Wurzeln ~/.pi/agent-mcp-claude und ~/.pi/agent-mcp-codex werden mit Upgrade-Hinweisen abgelehnt, damit eine veraltete Client-Konfiguration nicht stillschweigend geteilte Lock-Namespaces neu erstellt. Geben Sie zwei langlebigen Clients keine unterschiedlichen Overrides, wenn Sie erwarten, dass sie Sessions teilen.

Upgrade von separaten v1-Wurzeln

Ältere Konfigurationen verwendeten häufig ~/.pi/agent-mcp-claude/ und ~/.pi/agent-mcp-codex/. Führen Sie das Upgrade in dieser Reihenfolge durch:

1. Stoppen Sie alle alten Claude Code/Codex-MCP-Clients und bestätigen Sie, dass ihre Pi-RPC-Prozesse beendet sind.

2. Entfernen Sie PI_AGENT_MCP_STATE_DIR aus beiden Client-Konfigurationen.

3. Starten Sie einen v2-Client. Er setzt zuerst unterbrochene Migrationstransaktionen fort und importiert dann sessions.json aus den kanonischen, Claude-, Codex- und konfigurierten Legacy-Wurzeln in ~/.pi/agent-mcp/.

4. Überprüfen Sie pi_status und abgeschlossene Belege unter ~/.pi/agent-mcp/migrations/*/receipt.json. Neue Migrationen stellen Legacy-Manifeste als deterministische sessions.v1.retired-<content-hash>.json-Dateien zurück und löschen sie nie; Transaktionen, die von früheren v2-Builds erstellt wurden, behalten und setzen ihre aufgezeichneten sessions.v1.quarantine-*-Pfade fort.

5. Starten Sie die anderen v2-Clients.

Die Migration ist quellenatomar: Ein Konflikt lässt die vollständige Quelle aktiv und gibt migration_conflict zurück; sie aktiviert diese Quelle nie teilweise. PI_AGENT_MCP_LEGACY_STATE_DIRS kann eine durch OS-Pfadtrennzeichen getrennte Liste zusätzlicher Legacy-Wurzelverzeichnisse bereitstellen.

Wenn ein v1-Manifest cleanShutdown: false hat, gibt der Start legacy_state_uncertain zurück. Nachdem Sie manuell bestätigt haben, dass alle alten MCP- und Pi-Prozesse gestoppt sind, führen Sie einen kanonischen Start mit PI_AGENT_MCP_IMPORT_DIRTY=1 durch. Dies ist eine einmalige menschliche Bestätigung, keine automatisierte Erkennung veralteter Besitzer; aktive v1-Aufgaben werden als host_interrupted importiert. Entfernen Sie die Variable nach erfolgreicher Migration.

Tools

Die öffentliche API bleibt exakt fünf Tools; pi_wait akzeptiert absichtlich kein Timeout mehr, da es auf eine Endbedingung wartet.

pi_spawn

Erstellt eine neue Pi-Session und startet ihre erste Aufgabe im Hintergrund:

{
  "task": "Inspect the authentication module and fix token refresh",
  "cwd": "/Users/me/project",
  "name": "auth-worker",
  "model": "anthropic/claude-sonnet-4-20250514"
}

{
  "session_id": "pi_...",
  "task_id": "task_...",
  "status": "running"
}

name und model sind optional. cwd muss ein vorhandenes absolutes Verzeichnis sein.

pi_send

Startet die nächste Aufgabe auf einer vorhandenen im Leerlauf befindlichen oder ruhenden Session:

{
  "session_id": "pi_...",
  "task": "Continue by adding regression tests"
}

Dieselbe native Pi-Session-Datei wird wiederverwendet. Eine Session führt jeweils eine Aufgabe aus. Ein aktiver Besitzer auf einem anderen MCP-Server gibt session_in_use zurück; ein nativer Alias-Konflikt gibt native_session_in_use zurück. Nachdem der alte Besitzer ordnungsgemäß heruntergefahren ist, kann ein anderer Server sofort wiederherstellen und senden.

pi_wait

Wartet auf exakte aktuelle oder letzte Aufgaben-IDs:

{
  "task_ids": ["task_a", "task_b", "task_c"],
  "mode": "any"
}

• mode: "any" gibt zurück, wenn mindestens eine angeforderte Aufgabe terminal ist; pending listet die angeforderten Aufgaben, die noch laufen.

• mode: "all" gibt zurück, wenn jede angeforderte Aufgabe terminal ist; pending ist leer.

• pi_wait ist ein echtes Terminal-Warten: Die MCP-Anfrage bleibt offen, bis die angeforderte Bedingung erfüllt ist. Es hat kein Anwendungs-Timeout und bricht die Pi-Aufgabe nicht ab. Wenn der MCP-Client die Anfrage abbricht, stoppt nur dieses Beobachtungswarten; die Pi-Aufgabe läuft weiter. Claude Code kann die langlaufende Anfrage in eine eigene Hintergrundaufgabe verschieben und das Endergebnis auf derselben Anfrage liefern.

• Während des Wartens sendet der Server alle 30 Sekunden einen Standard-MCP-Fortschritts-Herzschlag, wenn der Client ein Fortschritts-Token bereitstellt. Der Herzschlag verhindert, dass Clients ein ansonsten stilles Terminal-Warten als Leerlauf behandeln; er gibt kein Tool-Ergebnis zurück, löst keine neue Modell-Runde aus, pollt Pi nicht und ändert den Aufgabenstatus nicht.

• Lokale Wartezeiten sind ereignisgesteuert. Serverübergreifende Wartezeiten überprüfen die dauerhaften aktuellen/letzten Slots erneut, während dieselbe Anfrage offen bleibt.

• Terminalzustände sind completed, failed, aborted und host_interrupted.

• Wenn ein freier aktiver Datensatz von einem toten Host hinterlassen wird, kann ein Wartender volles Eigentum erwerben und host_interrupted veröffentlichen, ohne Pi zu starten. Wenn eine verwaiste Pi noch Sperren hält, bleibt die Aufgabe ausstehend.

• Sobald eine spätere Aufgabe den letzten-Aufgaben-Slot des Datensatzes überschreibt, gibt die ältere ID unknown_task zurück; es gibt kein Aufgabenverlaufs-Registry.

pi_status

Liest mit session_id diesen endgültigen Datensatz von der Festplatte. Ohne Argumente listet es dynamisch alle nicht geschlossenen endgültigen Datensätze auf. Status ist beobachtend: Es erwirbt nie Sperren oder startet Pi.

Wichtige Felder:

• state: dauerhafter Zustand, der nur durch lokalen Laufzeitzustand überlagert wird, während dieser Server aktives Eigentum bei derselben Datensatzrevision hält

• resident: true/false für eine lokal besessene Session oder "unknown" für einen anderen/freien Besitzer

• ownership: local, other oder free_or_unknown; dies ist eine Diagnose, niemals Autorisierung

• recoverable: ob die gespeicherte native Pi-Session die strenge Identitätsvalidierung bestanden hat

• current_task_id und last_task: die dauerhaften aktuellen/letzten Aufgabenslots

Ein korrupter endgültiger Datensatz lässt pi_status klar fehlschlagen, anstatt eine partielle Liste zurückzugeben.

pi_close

Schließt eine logische Session dauerhaft:

{
  "session_id": "pi_..."
}

Für einen lokalen Residenten wird aktive Arbeit zu aborted, die gesamte Pi-Prozessgruppe wird gestoppt und der Datensatz wird geschlossen. Für einen freien entfernten Datensatz mit nativer Identität erwirbt das Schließen sowohl logisches als auch natives Eigentum, veröffentlicht jede aktive Aufgabe als host_interrupted und schließt ohne Pi zu starten. Ein identitätsloser Fehlerdatensatz kann nur unter logischem Eigentum geschlossen werden; wenn eines der nativen Identitätsfelder existiert, sind beide Felder und natives Fencing erforderlich. Ein aktiver Besitzer gibt session_in_use zurück. Die native Pi-JSONL-Datei wird beibehalten.

Fehler

Eigentums- und Migrationsfehler verwenden stabile öffentliche Codes und legen keine Lock-Pfade oder Lock-Diagnosen offen:

• session_in_use: Ein anderer konformer Host oder verwaister Erbe besitzt die logische Session

• native_session_in_use: Ein anderer logischer Datensatz besitzt dieselbe tatsächliche native Pi-Identität

• migration_blocked: Eine andere Migrations-/Eigentumsoperation fenced derzeit die Quelle

• migration_conflict: Eine Legacy-Quelle kollidiert mit vorhandenen kanonischen Datensätzen und bleibt nicht zurückgezogen

• legacy_state_uncertain: Dirty-v1-Zustand erfordert explizite Bestätigung nach dem Herunterfahren

• ownership_unavailable: Die Kernel-Lock-Bindung oder die sichere Eigentumswurzel ist nicht verfügbar

Andere vorhandene Validierungs- und Lebenszyklusfehler, einschließlich unknown_session, unknown_task, session_busy und session_not_recoverable, behalten ihre etablierten Bedeutungen.

Persistenz, Absturz und Waisenwiederherstellung

Dieses Projekt implementiert gemeinsame logische Persistenz, keinen Daemon:

• Neue Sessions verwenden private Pro-Session-Pi-Verzeichnisse und vorab zugewiesene native IDs.

• Ordentliches Herunterfahren stoppt die vollständige Pi-Prozessgruppe, veröffentlicht dauerhaft dormant/closed, leert Datensatzschreibvorgänge und schließt dann Eigentumsdeskriptoren.

• Der nächste MCP-Server stellt eine ruhende Session bei pi_send lazy mit ihrer exakten nativen Datei und Identität wieder her.

• Aufgaben werden nach dem Herunterfahren des Hosts nicht absichtlich fortgesetzt und nie automatisch wiederholt.

• Wenn der MCP-Elternprozess abstürzt, während Pi weiterläuft, erbt Pi beide Kernel-Lock-Deskriptoren. Andere Server schlagen mit session_in_use fehl, bis die verwaiste Pi-Prozessgruppe beendet ist.

• Um eine dauerhaft verwaiste Session wiederherzustellen, identifizieren und beenden Sie diese Pi-RPC-Prozessgruppe und versuchen Sie dann erneut pi_wait, pi_send oder pi_close. Löschen Sie niemals Lock-Dateien; deren Inhalte sind nur Diagnosen und keine Stale-Lock-Autorität.

Das gemeinsame Registry-Layout ist:

~/.pi/agent-mcp/
  sessions/       # one atomic v2 JSON record per logical session
  pi-sessions/    # exclusive directories for newly created native sessions
  locks/          # stable 0600 logical/native/migration lock files
  migrations/     # durable source snapshots, intents, conflicts, receipts
  tmp/

Verzeichnisse sind privat mit Modus 0700; Datensätze und Lock-Dateien haben Modus 0600.

Nebenläufigkeitsgrenze

Verschiedene Pi-Sessions können auf dasselbe cwd zeigen, aber dieses Projekt erstellt keine Worktrees und verhindert keine überlappenden Code-Bearbeitungen. Geben Sie parallelen Sessions nicht überlappende Aufgaben oder separate Worktree-Verzeichnisse. Kernel-Eigentum verhindert, dass zwei konforme MCP-Server dieselbe Pi-Session beschreiben; es koordiniert keine Schreibvorgänge im Projekt-Checkout und schützt nicht vor unabhängigen Pi-TUI-/Drittanbieterprozessen.

Konfiguration

Entwicklung

npm run typecheck
npm run build
npm test
npm pack --dry-run

Tests verwenden temporäre Wurzeln und ein steuerbares Fake-Pi; sie lesen oder schreiben nie die echten ~/.pi-Daten des Benutzers und rufen keine Modell-API auf. Die Abdeckung umfasst RPC-Framing, Prozessgruppen-Bereinigung, atomare Verarbeitung pro Datensatz, quellenatomare Migration, Vererbung der Kernel-Eigentümerschaft, serverübergreifendes Status-/Warte-/Sende-/Schließ-Verhalten und die MCP-Oberfläche mit fünf Tools.