Karavi at 19:42, 4 September 2026

2026-09-04T19:42:54Z

Karavi: Created page with "= Pi Coding Agent = راهنمای نصب، پیکربندی و استفاده از Pi برای پروژه‌های C#/.NET و Angular. == Pi چیست؟ == Pi یک coding-agent مینیمال و قابل‌گسترش است. قابلیت‌هایی مانند browser، subagent، memory، plan، MCP، theme و workflow از طریق extension، skill، prompt template و package اضافه می‌شوند. ابزارهای پایه: read..."

2026-09-04T19:20:01Z

Created page with "= Pi Coding Agent = راهنمای نصب، پیکربندی و استفاده از Pi برای پروژه‌های C#/.NET و Angular. == Pi چیست؟ == Pi یک coding-agent مینیمال و قابل‌گسترش است. قابلیت‌هایی مانند browser، subagent، memory، plan، MCP، theme و workflow از طریق extension، skill، prompt template و package اضافه می‌شوند. ابزارهای پایه: <syntaxhighlight lang="text"> read..."

New page

= Pi Coding Agent =

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

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

ابزارهای پایه:
<syntaxhighlight lang="text">
read
bash
powershell
edit
write
grep
find
ls
</syntaxhighlight>

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

بررسی:
<syntaxhighlight lang="powershell">
node --version
npm --version
git --version
</syntaxhighlight>

Pi در Windows معمولاً از Git Bash استفاده می‌کند. راهنما: [https://pi.dev/docs/latest/windows Windows Setup]

== نصب و به‌روزرسانی ==
<syntaxhighlight lang="powershell">
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
</syntaxhighlight>

اجرای پروژه:
<syntaxhighlight lang="powershell">
cd C:\Path\To\YourProject
pi
</syntaxhighlight>

حذف:
<syntaxhighlight lang="powershell">
npm uninstall -g @earendil-works/pi-coding-agent
</syntaxhighlight>

== احراز هویت و مدل‌ها ==
داخل Pi:
<syntaxhighlight lang="text">
/login
/logout
/model
</syntaxhighlight>

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

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

راهنما: [https://pi.dev/docs/latest/providers Providers]

== اجرای Pi و ابزارها ==
<syntaxhighlight lang="powershell">
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
</syntaxhighlight>

<syntaxhighlight lang="powershell">
pi -p "@README.md Summarize this file"
Get-Content README.md | pi -p "Summarize this text"
</syntaxhighlight>

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

== دستورهای تعاملی ==
{| class="wikitable"
! دستور !! کاربرد
|-
| <code>/login</code> || ورود
|-
| <code>/logout</code> || خروج
|-
| <code>/model</code> || انتخاب مدل
|-
| <code>/settings</code> || تنظیمات
|-
| <code>/new</code> || session جدید
|-
| <code>/resume</code> || ادامه session
|-
| <code>/fork</code> || fork session
|-
| <code>/tree</code> || درخت session
|-
| <code>/compact</code> || فشرده‌سازی context
|-
| <code>/export</code> || خروجی HTML
|-
| <code>/reload</code> || reload extensionها
|-
| <code>/help</code> || راهنما
|}

== تنظیمات ==
تنظیمات global:
<syntaxhighlight lang="text">
C:\Users\<username>\.pi\agent\settings.json
</syntaxhighlight>

تنظیمات project-local:
<syntaxhighlight lang="text">
<project>\.pi\settings.json
</syntaxhighlight>

نمونه:
<syntaxhighlight lang="json">
{
"defaultTools": ["read", "powershell", "edit", "write"],
"enableSkillCommands": true,
"packages": [
"npm:@sentiolabs/pi-frontend-design",
"npm:pi-frontend-check"
],
"prompts": ["./prompts"],
"skills": ["./skills"],
"themes": ["./themes"]
}
</syntaxhighlight>

مدیریت resourceها:
<syntaxhighlight lang="powershell">
pi config
pi config -l
</syntaxhighlight>

راهنما: [https://pi.dev/docs/latest/settings Settings]

== Context Files ==
Pi فایل‌های <code>AGENTS.md</code> و <code>CLAUDE.md</code> را برای قواعد پروژه می‌خواند.

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

غیرفعال‌کردن:
<syntaxhighlight lang="powershell">
pi --no-context-files
</syntaxhighlight>

== Extension، Skill، Prompt و Theme ==
مسیرهای global:
<syntaxhighlight lang="text">
C:\Users\<username>\.pi\agent\extensions\
C:\Users\<username>\.pi\agent\skills\
C:\Users\<username>\.pi\agent\prompts\
</syntaxhighlight>

مسیرهای project-local:
<syntaxhighlight lang="text">
<project>\.pi\extensions\
<project>\.pi\skills\
<project>\.pi\prompts\
</syntaxhighlight>

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

نمونه Skill:
<syntaxhighlight lang="markdown">
---
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.
</syntaxhighlight>

اجرا:
<syntaxhighlight lang="text">
/skill:dotnet-angular
</syntaxhighlight>

راهنماها: [https://pi.dev/docs/latest/skills Skills] و [https://pi.dev/docs/latest/prompt-templates Prompt Templates]

== نصب Package ==
<syntaxhighlight lang="powershell">
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
</syntaxhighlight>

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

== Packageهای پیشنهادی برای .NET و Angular ==
<syntaxhighlight lang="powershell">
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
</syntaxhighlight>

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

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

Catalog: [https://pi.dev/packages?type=extension Pi Package Catalog]

== Workflow Angular ==
<syntaxhighlight lang="powershell">
pnpm install --frozen-lockfile
pnpm start
pnpm lint
pnpm test
pnpm build
</syntaxhighlight>

پس از اجرای dev server:
<syntaxhighlight lang="text">
Open the Angular dev server, test main routes at desktop, tablet and mobile widths, inspect console and network errors, then report findings.
</syntaxhighlight>

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

== Workflow .NET ==
<syntaxhighlight lang="powershell">
dotnet restore
dotnet build
dotnet test
dotnet format --verify-no-changes
dotnet run
dotnet ef migrations list
</syntaxhighlight>

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

== Session و Compaction ==
<syntaxhighlight lang="text">
/new
/resume
/fork
/tree
/compact
/export
</syntaxhighlight>

تنظیم compaction:
<syntaxhighlight lang="json">
{
"compaction": {
"enabled": true,
"reserveTokens": 16384,
"keepRecentTokens": 20000
}
}
</syntaxhighlight>

راهنما: [https://pi.dev/docs/latest/compaction Compaction]

== UI Extension ==
برای widget دائمی از <code>setWidget()</code> استفاده کنید:
<syntaxhighlight lang="typescript">
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);
});
});
}
</syntaxhighlight>

پس از تغییر:
<syntaxhighlight lang="text">
/reload
</syntaxhighlight>

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

== RPC و SDK ==
RPC:
<syntaxhighlight lang="powershell">
pi --mode rpc
</syntaxhighlight>

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

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

راهنماها: [https://pi.dev/docs/latest/sdk SDK] و [https://pi.dev/docs/latest/rpc RPC]

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

غیرفعال‌کردن extensionها برای یک اجرا:
<syntaxhighlight lang="powershell">
pi --no-extensions
pi --no-extensions -e .\trusted-extension.ts
</syntaxhighlight>

== عیب‌یابی ==
=== Pi پیدا نمی‌شود ===
<syntaxhighlight lang="powershell">
Get-Command pi
npm list -g --depth=0
</syntaxhighlight>

=== Extension بارگذاری نمی‌شود ===
فایل، مسیر، <code>export default function</code>، ثبت command و اجرای <code>/reload</code> را بررسی کنید.

=== هشدار install scripts ===
پیام blocked شدن <code>postinstall</code> الزاماً خطا نیست. بررسی:
<syntaxhighlight lang="powershell">
npm install-scripts ls
</syntaxhighlight>

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

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

=== Angular server قابل‌دسترسی نیست ===
<syntaxhighlight lang="powershell">
pnpm start
Get-NetTCPConnection -State Listen
</syntaxhighlight>

== منابع رسمی ==
* [https://pi.dev/docs/latest Pi Documentation]
* [https://pi.dev/docs/latest/usage Using Pi]
* [https://pi.dev/docs/latest/windows Windows Setup]
* [https://pi.dev/docs/latest/providers Providers]
* [https://pi.dev/docs/latest/settings Settings]
* [https://pi.dev/docs/latest/extensions Extensions]
* [https://pi.dev/docs/latest/skills Skills]
* [https://pi.dev/docs/latest/packages Packages]
* [https://pi.dev/docs/latest/sdk SDK]
* [https://pi.dev/docs/latest/rpc RPC]
* [https://pi.dev/packages?type=extension Package Catalog]
* [https://github.com/earendil-works/pi Pi GitHub]

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

Pi Harness Agent Coding - Revision history

Karavi at 19:42, 4 September 2026