Pi Harness Agent Coding

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\<username>\.pi\agent\settings.json

تنظیمات project-local:

<project>\.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\<username>\.pi\agent\extensions\
C:\Users\<username>\.pi\agent\skills\
C:\Users\<username>\.pi\agent\prompts\

مسیرهای project-local:

<project>\.pi\extensions\
<project>\.pi\skills\
<project>\.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

منابع رسمی

• Pi Documentation
• Using Pi
• Windows Setup
• Providers
• Settings
• Extensions
• Skills
• Packages
• SDK
• RPC
• Package Catalog
• Pi GitHub

پیشنهادهای حرفه‌ای برای کدنویسی بهتر

برای پروژه‌های C#/.NET و Angular، کیفیت خروجی Pi فقط به مدل وابسته نیست؛ ترکیب قواعد پروژه، برنامه‌ریزی، تست، browser QA و review اهمیت دارد.

Workflow برنامه‌ریزی و Verify

pi install -l npm:pi-plan-task

این package workflow زیر را فراهم می‌کند:

/plan
review
approve
/build
verify

Task بدون acceptance criteria و evidence تست نباید کامل اعلام شود.

راهنما: pi-plan-task

تست واقعی Angular

pi install -l npm:pi-frontend-check

قابلیت‌ها:

• screenshot
• تست responsive
• بررسی console error
• بررسی network error
• تست فرم و route
• viewportهای desktop، tablet و mobile

راهنما: pi-frontend-check

تحلیل TypeScript و Angular

pi install -l npm:pi-lens

برای LSP، lint، formatter، type-check و تحلیل ساختاری استفاده می‌شود.

Permission و امنیت اجرای Pi

pi install npm:@gotgenes/pi-permission-system

Pi به‌صورت ذاتی sandbox کامل و permission popup برای همه ابزارها ندارد. برای پروژه‌های حساس، مسیرهای مجاز، commandهای خطرناک و دسترسی‌های external را محدود کنید.

راهنما: pi-permission-system

Subagent برای تقسیم کار

pi install -l npm:@gotgenes/pi-subagents

Roleهای پیشنهادی:

scout
planner
implementer
dotnet-reviewer
angular-reviewer
security-reviewer
test-reviewer

هر subagent باید مسئولیت، scope، ابزار و write-set مشخص داشته باشد.

Review خودکار Pull Request

برای پروژه‌های GitHub:

pi install -l npm:pi-pr-review

برای review correctness، security، performance، API contract و کیفیت کد مناسب است. انتشار comment روی GitHub باید فقط با دستور صریح انجام شود.

راهنما: pi-pr-review

Memory بین sessionها

فقط یکی از این دو package را انتخاب کنید:

pi install npm:pi-memory

یا:

pi install npm:pi-hermes-memory

Memory برای تصمیم‌های معماری، نکات پروژه و ادامه sessionهای طولانی مفید است؛ secret، token، password و PII نباید در آن ذخیره شود.

جست‌وجوی مستندات وب

pi install npm:pi-web-access

برای مطالعه مستندات رسمی Angular، Microsoft، .NET، GitHub و PDFها استفاده می‌شود.

Stack پیشنهادی

pi install -l npm:pi-plan-task
pi install -l npm:pi-frontend-check
pi install -l npm:pi-lens
pi install -l npm:@gotgenes/pi-subagents
pi install npm:@gotgenes/pi-permission-system
pi install npm:pi-web-access

از نصب هم‌زمان چند browser extension، چند memory extension یا چند workflow manager خودداری کنید؛ هم‌پوشانی می‌تواند باعث command conflict و context اضافی شود.

Promptهای استاندارد

قبل از تغییر

First inspect the repository rules, git status, relevant files, and two sibling implementations. Do not edit yet. Return scope, risks, affected files, and verification commands.

پیاده‌سازی Angular

Implement this Angular change using the existing project patterns. Preserve fa/en translation parity, RTL/LTR, loading/error/success states, accessibility, dark mode, API envelope, and responsive behavior. Use pnpm commands.

پیاده‌سازی .NET

Implement this .NET change using the existing layered architecture. Preserve API compatibility, async I/O, cancellation, validation, authorization, structured logging, error envelope, migration safety, and secret handling.

پس از تغییر

Verify the change end-to-end. Run focused dotnet tests, Angular lint/test/build, browser QA for affected routes, inspect console and network errors, review the diff, and report only evidence-backed findings.

Review بدون تغییر

Review the current diff only. Do not modify files. Check correctness, security, API compatibility, Angular/.NET conventions, i18n, accessibility, performance, and missing tests. Report severity, file, line, evidence, and recommendation.

چرخه استاندارد توسعه

Inspect
→ Plan
→ Implement
→ Build
→ Test
→ Browser QA
→ Review diff
→ Secret scan
→ Report evidence

قواعد انتخاب Package

• ابتدا package را با pi -e موقت تست کنید.
• packageهای پروژه را با pi install -l نصب کنید.
• نسخه package را در کار production pin کنید.
• source و license و permission را بررسی کنید.
• packageهای duplicate یا بدون استفاده را حذف کنید.
• پس از نصب، pi list و /reload را بررسی کنید.

راهنمای رسمی packageها: Pi Packages