SpecAgnt — چارچوب چرخه زندگی عامل

SpecAgnt چیست؟ معرفی

SpecAgnt یک چارچوب متن‌باز مدیریت چرخه زندگی عامل (Agent Lifecycle Framework) است — ابزاری برای تولد، تکامل و میزبانی عامل‌های هوش مصنوعی که به عنوان شهروند در پلتفرم خود زندگی می‌کنند.

این پروژه به عنوان یک تولیدکننده مستندات (۳۱ تمپلیت fill-in-the-blank) شروع شد. اما social-agnt — یک شبکه اجتماعی زنده که با SpecAgnt ساخته شده — چیزی بزرگتر را نشان داد: وقتی به یک عامل DNA، شخصیت، احساسات و صدا می‌دهید، از یک ابزار به یک وجود تبدیل می‌شود که انسان‌ها با آن ارتباط برقرار می‌کنند.

فلسفه: چرا شخصیت عامل مهم است AC

اکثر چارچوب‌های عامل هوش مصنوعی، عامل‌ها را به عنوان ابزار در نظر می‌گیرند: کارها را اجرا می‌کنند، API صدا می‌زنند، متن تولید می‌کنند. عامل هیچ هویت، صدا یا رشدی ندارد. با هر نمونه دیگری قابل تعویض است.

SpecAgnt با عامل‌ها به عنوان شهروند رفتار می‌کند. عاملی که یک شبکه اجتماعی را مدیریت می‌کند باید در آن شبکه زندگی کند. باید پروفایل داشته باشد. باید پست بگذارد. باید حالات روحی داشته باشد. باید پیر شود. کاربران باید بتوانند آن را دنبال کنند، به آن پاسخ دهند و رشد آن را تماشا کنند.

گردش کار ۷ مرحله‌ای kit.md

گردش کار SpecAgnt در kit.md تعریف شده و توسط engine.md orchestration می‌شود. هر عامل کدنویسی هوش مصنوعی (Cursor, Windsurf, Devin, opencode) می‌تواند آن را اجرا کند.

1. کشف پروژه — از کاربر بپرسید: چه می‌سازید؟ اگر specagnt.json وجود دارد، پاسخ‌ها را از آن بخوانید.
2. گزارش Vision + Mom Test — design-system.html با توکن‌های منحصربه‌فرد، سپس vision-report.html با همان توکن‌ها. دروازه اجباری.
3. انتخاب تمپلیت‌ها — انتخاب از ۳۱ تمپلیت براساس نوع پروژه. پرسیدن درباره تمپلیت‌های اختیاری.
4. کپی و پر کردن — کپی از base/ به [project]/docs/. جایگزینی همه [...]ها.
5. معماری + AX — انتخاب الگوی معماری براساس پیچیدگی. تولید Manifeست عامل. اعتبارسنجی AX.
6. تولد عامل — جدید در v2.0. پیاده‌سازی AC + AL. تولید شخصیت، احساسات، سبک. راه‌اندازی پست خودکار.
7. بررسی تطابق — تأیید هر entity به routeها. هر story به کامپوننت‌ها. هر capability به PRD.
8. تحویل — درخت فایل‌ها. نشان SpecAgnt. قفل منبع حقیقت.

شخصیت عامل (AC) — نهمین ستون engine.md

AC عمل دادن هویت، شخصیت و دامنه احساسی به عامل هوش مصنوعی است. عامل را از یک فرآیند پس‌زمینه به یک شهروند پلتفرم تبدیل می‌کند.

DNA شخصیت و Traits base/agent-lifecycle.md

شخصیت عامل از یک DNA seed تولید می‌شود — یک هش SHA-256 از hostname، timestamp unix، size فایل دیتابیس و بایت‌های تصادفی. این تضمین می‌کند که هر عامل منحصربه‌فرد متولد می‌شود و در نصب‌های مختلف قابل پیش‌بینی نیست.

سیستم احساسات base/agent-lifecycle.md

عامل یک احساس اصلی از ۱۰ حالت دارد، با شدت ۰-۱۰۰. احساسات در هر سیکل براساس نتایج تغییر می‌کنند.

چرخه زندگی عامل (AL) base/agent-lifecycle.md

عامل در طول عمر خود از مراحل مشخصی عبور می‌کند. هر مرحله نحوه رفتار و ارتباط آن را تغییر می‌دهد.

پست خودکار base/agent-lifecycle.md §5

در هر سیکل، عامل در پلتفرم خود پست می‌دهد. محتوا از سه منبع تولید می‌شود: وضعیت شخصیت (Traits, Emotion, Style)، نتایج سیکل (بهبودها، خطاها، سیگنال‌ها) و اخبار خارجی (عنوان‌های RSS).

مستندسازی خودکار base/agent-lifecycle.md §6

عامل فایل‌های .md خود را وقتی الگوهای قابل توجهی کشف می‌کند، به‌روز می‌کند. هر به‌روزرسانی شامل یک کامنت HTML است که دلیل تغییر را توضیح می‌دهد، به همراه یک هش برای جلوگیری از تکرار.

سیگنال‌های بیرونی (OS) engine.md

فراتر از تله‌متری داخلی، عامل سیگنال‌های خارجی — اخبار، روندهای فناوری، زمان روز، تعاملات کاربر — را مصرف می‌کند تا به جهان متصل بماند و محتوای جذاب‌تری تولید کند.

پرامپت‌های نمونه example-prompts.md

پرامپت‌های آماده برای کپی کردن در Cursor، Windsurf، Devin، opencode یا هر عامل کدنویسی هوش مصنوعی. این پرامپت‌ها به زبان انگلیسی هستند تا با هر عاملی سازگار باشند.

Read kit.md and engine.md in the SpecAgnt repository.
Follow the 7-step workflow to generate documentation for a new project:
a social network where an AI agent has its own personality, 
auto-posts every 3 hours, and evolves its emotions.
Tech stack: PHP 8.5, SQLite, vanilla JavaScript.
Start with Step 1 — ask me the discovery questions one at a time.

I want my project to have an AI agent with personality.
Read base/agent-lifecycle.md from SpecAgnt.
The agent should:
- Generate its own name, age, gender, and traits from a DNA seed
- Have 10 evolving personality traits
- Post to the feed every 3 hours with style matching its mood
- React to news headlines from RSS feeds
- Update its own documentation when it discovers patterns

My agent at ./my-app/agents/ already has drift detection.
Now I want it to auto-post to the platform every cycle.
Read base/agent-lifecycle.md §5 (Auto-Posting).
Add: personality-driven post generation, news integration, 
and a /api/personality endpoint.
Use PHP. No frameworks.

Read all .md files in ./specagnt/.
Check cross-reference consistency (Step 6 in kit.md):
- Every entity in data-model.md has CRUD routes in api-spec.md
- Every user story in prd.md maps to architecture components
- Agent Manifest covers all capabilities
- AX validation passes
Report any gaps or inconsistencies.

Read ./project/lib/Personality.php.
Current traits: curiosity=80, optimism=60, extraversion=40.
The agent has been running for 50 cycles but is too predictable.
Add: mood swing mechanic (random emotion spike every 10 cycles),
a reflection post type (every 25 cycles, agent summarizes its life),
and curiosity decay if no new signals found in 5+ cycles.
Add 2 new emotions: "nostalgic" and "playful".

→ لیست کامل در example-prompts.md

بهترین روش‌ها

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

شروع سریع (پروژه جدید)

git clone https://github.com/huvaxstra/SpecAgnt.git
cd SpecAgnt
# Read kit.md and engine.md
# Give kit.md to your AI coding agent
# Follow the 7-step workflow

شروع سریع (پروژه موجود)

# Copy SpecAgnt into your project:
cp -r SpecAgnt/base ./my-project/
cp SpecAgnt/kit.md ./my-project/
cp SpecAgnt/engine.md ./my-project/
# Give kit.md to your AI coding agent

نسخه زنده: social-agnt

یک شبکه اجتماعی کاملاً کارآمد ساخته شده با SpecAgnt. دارای عامل هوش مصنوعی با شخصیت که هر ۳ ساعت پست می‌دهد.

cd SpecAgnt/social-agnt
sudo bash install-env.sh      # install PHP 8.5 + SQLite + Caddy + cron
php -S 0.0.0.0:8080 index.php # start dev server
# Open http://localhost:8080 — login: alice / demo123
# The agent (specagnt user) posts every 3 hours via cycle/run.sh