Pi Coding Agent

راهنمای نصب، پیکربندی و استفاده از Pi برای پروژه‌های C#/.NET و Angular.

Pi چیست؟

Pi یک coding-agent مینیمال و قابل‌گسترش است. قابلیت‌هایی مانند browser، subagent، memory، plan، MCP، theme و workflow از طریق extension، skill، prompt template و package اضافه می‌شوند.

ابزارهای پایه:

read
bash
powershell
edit
write
grep
find
ls

Pi به‌صورت built-in شامل MCP، subagent، plan mode، todo و background task نیست؛ این قابلیت‌ها با package یا extension اضافه می‌شوند.

پیش‌نیازهای Windows

Node.js
npm یا package manager سازگار
Git for Windows
Windows Terminal
API key یا subscription provider

بررسی:

node --version
npm --version
git --version

Pi در Windows معمولاً از Git Bash استفاده می‌کند. راهنما: Windows Setup

نصب و به‌روزرسانی

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version
pi --help
pi update --self
pi update --extensions
pi update --all
pi update --models
pi list

اجرای پروژه:

cd C:\Path\To\YourProject
pi

حذف:

npm uninstall -g @earendil-works/pi-coding-agent

احراز هویت و مدل‌ها

داخل Pi:

/login
/logout
/model

Providerهای رایج شامل OpenAI/Codex، Anthropic، GitHub Copilot، Google، DeepSeek، OpenRouter، Azure OpenAI، Vertex، Bedrock، xAI و llama.cpp هستند.

کلیدها را در Wiki، source code، prompt، log یا commit ذخیره نکنید.

راهنما: Providers

اجرای Pi و ابزارها

pi
pi -p "Summarize this project"
pi --model openai/gpt-4o
pi --tools read,grep,find,ls -p "Review this project"
pi --exclude-tools bash
pi --no-tools

pi -p "@README.md Summarize this file"
Get-Content README.md | pi -p "Summarize this text"

در editor، @ برای فایل، Tab برای path، Shift+Enter برای ورودی چندخطی، ! برای shell command و !! برای اجرای بدون ارسال خروجی استفاده می‌شود.

دستورهای تعاملی

دستور	کاربرد
`/login`	ورود
`/logout`	خروج
`/model`	انتخاب مدل
`/settings`	تنظیمات
`/new`	session جدید
`/resume`	ادامه session
`/fork`	fork session
`/tree`	درخت session
`/compact`	فشرده‌سازی context
`/export`	خروجی HTML
`/reload`	reload extensionها
`/help`	راهنما

تنظیمات

تنظیمات global:

C:\Users\&lt;username&gt;\.pi\agent\settings.json

تنظیمات project-local:

&lt;project&gt;\.pi\settings.json

نمونه:

{
  "defaultTools": ["read", "powershell", "edit", "write"],
  "enableSkillCommands": true,
  "packages": [
    "npm:@sentiolabs/pi-frontend-design",
    "npm:pi-frontend-check"
  ],
  "prompts": ["./prompts"],
  "skills": ["./skills"],
  "themes": ["./themes"]
}

مدیریت resourceها:

pi config
pi config -l

راهنما: Settings

Context Files

Pi فایل‌های AGENTS.md و CLAUDE.md را برای قواعد پروژه می‌خواند.

موارد پیشنهادی برای ثبت:

commandهای build و test
معماری و naming
قواعد API و migration
i18n فارسی/انگلیسی
محدودیت‌های امنیتی
ممنوعیت commit، push و deploy بدون مجوز

غیرفعال‌کردن:

pi --no-context-files

Extension، Skill، Prompt و Theme

مسیرهای global:

C:\Users\&lt;username&gt;\.pi\agent\extensions\
C:\Users\&lt;username&gt;\.pi\agent\skills\
C:\Users\&lt;username&gt;\.pi\agent\prompts\

مسیرهای project-local:

&lt;project&gt;\.pi\extensions\
&lt;project&gt;\.pi\skills\
&lt;project&gt;\.pi\prompts\

Extension: کد TypeScript برای tool، command، event، UI یا provider.
Skill: workflow تخصصی با فایل SKILL.md.
Prompt template: فایل Markdown قابل اجرا با /name.
Theme: تنظیمات ظاهری Pi.

نمونه Skill:

---
name: dotnet-angular
description: Build, test and verify .NET and Angular projects.
---

Run dotnet build and dotnet test.
Run pnpm lint, pnpm test and pnpm build.
Check API compatibility, i18n, accessibility and secrets.

اجرا:

/skill:dotnet-angular

راهنماها: Skills و Prompt Templates

نصب Package

pi install npm:package-name
pi install -l npm:package-name
pi install git:github.com/user/repository@v1
pi -e npm:package-name
pi remove npm:package-name
pi list

نصب عادی global است؛ -l project-local و -e موقت است.

Packageهای پیشنهادی برای .NET و Angular

pi install npm:@sentiolabs/pi-frontend-design
pi install -l npm:pi-frontend-check
pi install -l npm:pi-lens
pi install npm:pi-web-access
pi install npm:pi-mcp-adapter
pi install npm:@gotgenes/pi-permission-system

@sentiolabs/pi-frontend-design: طراحی UI، typography، layout و responsive.
pi-frontend-check: تست Angular، screenshot، viewport، console و network.
pi-lens: LSP، TypeScript، lint، formatter و type-check.
pi-web-access: جست‌وجو و مطالعه مستندات وب.
pi-mcp-adapter: اتصال MCP serverها.
pi-permission-system: محدودسازی دسترسی ابزارها و مسیرها.

افزونه‌های browser و memory را بدون نیاز واقعی هم‌زمان نصب نکنید.

Catalog: Pi Package Catalog

Workflow Angular

pnpm install --frozen-lockfile
pnpm start
pnpm lint
pnpm test
pnpm build

پس از اجرای dev server:

Open the Angular dev server, test main routes at desktop, tablet and mobile widths, inspect console and network errors, then report findings.

چرخه: Implement → Build → Lint → Unit Test → Browser Test → Screenshot → Accessibility Review → Fix → Re-test

Workflow .NET

dotnet restore
dotnet build
dotnet test
dotnet format --verify-no-changes
dotnet run
dotnet ef migrations list

connection string، token و credential واقعی نباید در Wiki یا prompt قرار گیرند. migration production به backup، rollback plan و مجوز نیاز دارد.

Session و Compaction

/new
/resume
/fork
/tree
/compact
/export

تنظیم compaction:

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

راهنما: Compaction

UI Extension

برای widget دائمی از setWidget() استفاده کنید:

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Text } from "@earendil-works/pi-tui";

export default function (pi: ExtensionAPI) {
  pi.on("session_start", (_event, ctx) => {
    ctx.ui.setWidget("status", (_tui, theme) => {
      return new Text("Pi active: " + ctx.cwd, 0, 0);
    });
  });
}

پس از تغییر:

/reload

ctx.ui.custom() برای modal است و تا اجرای done() منتظر می‌ماند؛ برای status دائمی از setWidget() استفاده کنید.

RPC و SDK

RPC:

pi --mode rpc

کاربردها: اتصال به IDE، ساخت Web UI اختصاصی، pipeline و automation.

SDK برای embedding Pi در برنامه‌های Node.js/TypeScript استفاده می‌شود.

راهنماها: SDK و RPC

امنیت

Extension و packageها می‌توانند کد arbitrary اجرا کنند.
Pi به‌صورت پیش‌فرض sandbox کامل ندارد.
API key و connection string در source، Wiki یا log ذخیره نشود.
packageهای ناشناس قبل از نصب review شوند.
برای پروژه‌های حساس از permission system، container یا sandbox استفاده شود.
packageهای غیرضروری حذف شوند.

غیرفعال‌کردن extensionها برای یک اجرا:

pi --no-extensions
pi --no-extensions -e .\trusted-extension.ts

عیب‌یابی

Pi پیدا نمی‌شود

Get-Command pi
npm list -g --depth=0

Extension بارگذاری نمی‌شود

فایل، مسیر، export default function، ثبت command و اجرای /reload را بررسی کنید.

هشدار install scripts

پیام blocked شدن postinstall الزاماً خطا نیست. بررسی:

npm install-scripts ls

اگر خروجی No packages with unreviewed install scripts. بود، مورد pending وجود ندارد.

custom UI هنگ می‌کند

ctx.ui.custom() تا اجرای done() باز می‌ماند. handler خروج مانند Escape اضافه کنید یا برای widget دائمی از setWidget() استفاده کنید.

Angular server قابل‌دسترسی نیست

pnpm start
Get-NetTCPConnection -State Listen

منابع رسمی

رده:ابزارهای توسعه رده:Angular رده:.NET رده:هوش مصنوعی

Pi Harness Agent Coding

Contents