Watch
1
0
Fork
You've already forked arc
0
forked from hesabix/arc
arc/docs/AI_SKILLS_MARKETPLACE_PHASES.md
2026-06-14 00:37:58 +00:00

338 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# مارکت‌پلیس مهارت‌های AI — فازهای اجرایی و سناریوی مو‌به‌مو
این سند نقشهٔ اجرای کامل قابلیت Skills (سازگار با [agentskills.io](https://agentskills.io/specification) و Anthropic) در حسابیکس است.
---
## نمای کلی فازها
| فاز | عنوان | خروجی قابل تحویل | مدت تقریبی |
|-----|--------|------------------|------------|
| **۱** | زیرساخت و Portable Runtime | import ZIP، نصب محلی، فعال/غیرفعال، inject در چت | ۳–۴ هفته |
| **۲** | Native Anthropic Runtime | prebuilt skills، Skills API، hybrid | ۳–۴ هفته |
| **۳** | مارکت‌پلیس UGC | انتشار عمومی، moderation، reviews | ۳–۴ هفته |
| **۴** | اکوسیستم | Git import، monetization، مهارت‌های رسمی ERP | ۴+ هفته |
---
# فاز ۱ — زیرساخت و Portable Runtime
## هدف
کاربر بتواند مهارت استاندارد Agent Skills (ZIP با `SKILL.md`) را import کند، در کسب‌وکار نصب کند، به‌صورت داینامیک فعال/غیرفعال کند، و در چت AI با هر provider (OpenAI/Anthropic/Local) از حالت portable استفاده کند.
## خروجی‌های فاز ۱
- جداول: `ai_skill_packages`, `ai_skill_installs`
- سرویس‌ها: `ai_skill_parser`, `ai_skill_service`, `ai_skill_runtime`
- API: `/api/v1/ai/skills/*`
- یکپارچگی: `AIService.get_system_prompt` + `get_available_functions`
- UI (فاز بعدی Flutter): API آماده
---
## سناریوی مو‌به‌مو — فاز ۱
### گام ۱.۱ — import مهارت از ZIP
**بازیگر:** کاربر الکتروپارس
**پیش‌شرط:** دسترسی `ai` به کسب‌وکار، فایل ZIP از مخزن `anthropics/skills`
| مرحله | عمل | سیستم | پاسخ |
|-------|-----|--------|------|
| 1 | `POST /businesses/{bid}/ai/skills/import` + multipart ZIP | استخراج فایل‌ها | — |
| 2 | — | یافتن `SKILL.md` (case-insensitive) | خطا اگر نباشد |
| 3 | — | `parse_skill_md()` → frontmatter + body | — |
| 4 | — | `validate_skill_spec()` → name, description | خطای validation |
| 5 | — | اسکن `scripts/`, `references/`, `assets/` | `has_scripts=true` |
| 6 | — | `build_compatibility_report()` | JSON گزارش |
| 7 | — | ذخیره bundle در JSON ستون `bundle_files` | `package_id` |
| 8 | — | `status=draft`, `source_type=portable` | — |
**بدنه پاسخ نمونه:**
```json
{
"package_id": 42,
"skill_slug": "mcp-builder",
"compatibility": {
"runtime_mode": "portable",
"instruction_only": true,
"has_scripts": true,
"scripts_warning": "اسکریپت‌ها در فاز ۱ اجرا نمی‌شوند",
"score": 75
}
}
```
### گام ۱.۲ — ساخت مهارت در UI (بدون ZIP)
| مرحله | عمل | سیستم |
|-------|-----|--------|
| 1 | `POST /businesses/{bid}/ai/skills` | body: title, skill_slug, description, skill_body, allowed_tool_names |
| 2 | — | تولید `SKILL.md` synthetic از فیلدها |
| 3 | — | `source_type=hesabix_native` |
| 4 | — | `status=draft` |
### گام ۱.۳ — نصب مهارت در کسب‌وکار
| مرحله | عمل | سیستم |
|-------|-----|--------|
| 1 | `POST /businesses/{bid}/ai/skills/install` `{ "package_id": 42 }` | — |
| 2 | — | ایجاد `ai_skill_installs` |
| 3 | — | `is_enabled=true` پیش‌فرض |
| 4 | — | کپی `allowed_tool_names` از package |
### گام ۱.۴ — فعال/غیرفعال داینامیک
| مرحله | عمل | سیستم |
|-------|-----|--------|
| 1 | `PUT /businesses/{bid}/ai/skills/enabled` | `{ "install_ids": [1, 3], "disabled_ids": [2] }` |
| 2 | — | به‌روز `is_enabled` روی installs |
| 3 | پیام چت بعدی | فقط metadata مهارت‌های enabled |
**نکته:** تغییر بدون ری‌استارت session؛ در `get_system_prompt` هر بار خوانده می‌شود.
### گام ۱.۵ — چت با مهارت فعال
**درخواست:** `POST /ai/chat/sessions/{sid}/messages` — «لیست بدهکاران را تحلیل کن»
| مرحله | لایه | عمل |
|-------|------|-----|
| 1 | `ai_skill_runtime` | `list_enabled_metadata(business_id)` → ۳ مهارت |
| 2 | `ai_skill_runtime` | `select_skills_for_query(query, metadata)` → ۱ مهارت match |
| 3 | `get_system_prompt` | inject `[Skills metadata]` + `[Activated: debt-analysis]` body |
| 4 | `get_available_functions` | intersect با `allowed_tool_names` مهارت فعال‌شده |
| 5 | `AIService` | agent loop عادی |
| 6 | پاسخ | متن + tool calls محدود به مهارت |
**فرمت inject در prompt:**
```
## مهارت‌های فعال (metadata)
- debt-analysis: تحلیل بدهکاران. وقتی کاربر از بدهی، مطالبات صحبت کرد...
- sales-weekly: ...
## مهارت فعال‌شده: debt-analysis
[بدنه SKILL.md]
```
### گام ۱.۶ — انتشار محلی (فقط business، بدون marketplace)
| مرحله | عمل |
|-------|-----|
| 1 | `POST /businesses/{bid}/ai/skills/{package_id}/publish-local` |
| 2 | `visibility=business_only` — فقط همان کسب‌وکار |
---
## فایل‌های فاز ۱
| فایل | نقش |
|------|-----|
| `adapters/db/models/ai_skill.py` | مدل‌ها |
| `migrations/versions/20260702_000001_ai_skills.py` | migration |
| `app/services/ai/ai_skill_parser.py` | parse/validate SKILL.md |
| `app/services/ai/ai_skill_service.py` | CRUD, import, install |
| `app/services/ai/ai_skill_runtime.py` | prompt injection, tool filter |
| `adapters/api/v1/ai/skills.py` | REST API |
| `app/services/ai/ai_service.py` | hooks |
| `tests/test_ai_skill_parser.py` | unit tests |
---
# فاز ۲ — Native Anthropic Runtime
## هدف
مهارت‌های prebuilt Anthropic (`pdf`, `xlsx`, `docx`, `pptx`) و bundleهای دارای scripts از طریق Skills API اجرا شوند.
## سناریوی مو‌به‌مو
### گام ۲.۱ — فعال‌سازی provider Anthropic
| مرحله | شرط |
|-------|-----|
| 1 | `AIProviderCredential` برای `anthropic` فعال |
| 2 | مدل چت از خانواده Claude انتخاب شده |
| 3 | skill با `source_type=anthropic_prebuilt` یا `anthropic_skill_id` تنظیم شده |
### گام ۲.۲ — نصب مهارت prebuilt
| مرحله | عمل |
|-------|-----|
| 1 | `GET /ai/skills/catalog/anthropic` → لیست رسمی |
| 2 | کاربر «pdf» را install می‌کند |
| 3 | `anthropic_skill_id=pdf` ذخیره می‌شود (بدون ZIP) |
### گام ۲.۳ — اجرای hybrid
**سوال:** «گزارش فروش را بگیر و Excel بساز»
| مرحله | Runtime |
|-------|---------|
| 1 | Portable: مهارت `sales-report` → `get_sales_report` tool |
| 2 | Native: skill `xlsx` → `AnthropicProvider` با `container.skills` |
| 3 | ترکیب نتایج در پاسخ نهایی |
### گام ۲.۴ — گسترش AnthropicProvider
```python
# مفهومی
kwargs["container"] = {"skills": [{"skill_id": "xlsx", "type": "anthropic"}]}
# beta headers: code-execution-2025-08-25, skills-2025-10-02, files-api-2025-04-14
```
### گام ۲.۵ — hesabix.compat.yaml
هنگام import ZIP، اگر فایل وجود داشت parse شود؛ وگرنه auto-generate گزارش سازگاری.
---
# فاز ۳ — مارکت‌پلیس UGC
## هدف
انتشار عمومی، moderation، browse/install، reviews.
## سناریوی مو‌به‌مو
### گام ۳.۱ — انتشار عمومی
| مرحله | عمل |
|-------|-----|
| 1 | `POST /businesses/{bid}/ai/skills/{id}/publish` |
| 2 | `sanitize_skill_for_marketplace()` — حذف secrets |
| 3 | `ai_moderation_service.review_skill()` |
| 4 | `status=pending_review` → admin/auto → `published` |
| 5 | ظاهر در `GET /ai/skills/marketplace/packages` |
### گام ۳.۲ — browse و نصب توسط کاربر دیگر
| مرحله | عمل |
|-------|-----|
| 1 | کاربر B مارکت‌پلیس را باز می‌کند |
| 2 | فیلتر: `source_type`, tag, `compatibility_score` |
| 3 | جزئیات + گزارش سازگاری |
| 4 | Install → `install_count++` |
### گام ۳.۳ — review
| مرحله | عمل |
|-------|-----|
| 1 | `POST /ai/skills/marketplace/packages/{id}/reviews` |
| 2 | rating 1–5 + comment |
| 3 | نمایش میانگین در کارت مهارت |
### گام ۳.۴ — Flutter UI
| صفحه | الگو |
|------|------|
| `ai_skills_marketplace_page.dart` | `workflow_marketplace_page.dart` |
| `ai_chat_skills_sheet.dart` | `ai_chat_knowledge_sheet.dart` |
---
# فاز ۴ — اکوسیستم
## سناریوهای تکمیلی
### گام ۴.۱ — import از Git URL
`POST /ai/skills/import-git` → clone shallow → validate → package
### گام ۴.۲ — monetization
پلن پولی skill pack؛ `marketplace_orders`؛ سهم publisher
### گام ۴.۳ — مهارت‌های رسمی Hesabix
seed: `fiscal-year-close`, `sales-return`, `inventory-reorder`
### گام ۴.۴ — به‌روزرسانی نسخه
`parent_package_id` + notify installs + optional auto-migrate
### گام ۴.۵ — MCP export
مهارت‌های نصب‌شده در `/api/v1/ai/mcp` metadata
---
## Schema دیتابیس (خلاصه)
### ai_skill_packages
| ستون | نوع | توضیح |
|------|-----|--------|
| id | int PK | |
| skill_slug | varchar(64) | از frontmatter name |
| title | varchar(255) | نمایشی |
| description | text | از frontmatter |
| skill_body | text | markdown بدون frontmatter |
| source_type | varchar(32) | portable, anthropic_prebuilt, hesabix_native |
| anthropic_skill_id | varchar(64) nullable | pdf, xlsx, ... |
| bundle_files | json nullable | {path: content_base64 or text} |
| allowed_tool_names | json nullable | لیست ابزار حسابیکس |
| compatibility_report | json nullable | |
| has_scripts | bool | |
| publisher_user_id | int nullable | |
| publisher_business_id | int nullable | |
| visibility | varchar(32) | draft, business_only, pending_review, published, hidden |
| version_label | varchar(64) | |
| install_count | int | |
| tags | json | |
### ai_skill_installs
| ستون | نوع |
|------|-----|
| id | int PK |
| package_id | int FK |
| business_id | int FK |
| installed_by_user_id | int |
| is_enabled | bool |
| custom_title | varchar nullable |
| created_at | datetime |
---
## وابستگی بین فازها
```
فاز ۱ (پایه) ──► فاز ۲ (Anthropic native)
│
└──────────► فاز ۳ (Marketplace) ──► فاز ۴ (اکوسیستم)
```
فاز ۲ و ۳ می‌توانند موازی پس از فاز ۱ شروع شوند.
---
## معیار پذیرش (Acceptance Criteria)
### فاز ۱
- [x] ZIP معتبر agentskills.io import می‌شود
- [x] مهارت hesabix_native ساخته می‌شود
- [x] enable/disable بدون restart
- [x] prompt شامل metadata مهارت‌های فعال
- [x] tools فیلتر شده با allowed_tool_names
- [x] unit test parser
### فاز ۲
- [x] prebuilt pdf/xlsx با Claude — `AnthropicProvider` + `container.skills`
- [x] گزارش سازگاری برای skills دارای scripts + `hesabix.compat.yaml`
- [x] نصب prebuilt از API/UI
### فاز ۳
- [x] publish + moderation (spam) + admin approve/reject
- [x] public browse + install
- [x] reviews API
- [x] Flutter: skills sheet + marketplace page
### فاز ۴
- [x] Git import (GitHub URL → ZIP)
- [x] حداقل ۵ مهارت رسمی ERP seed شده
- [x] monetization (قیمت‌گذاری + خرید از کیف پول)
- [x] Flutter admin page برای moderation
- [x] تب «حسابیکس» در مارکت‌پلیس + نمایش قیمت
- [x] Import از GitHub در sheet مهارت‌ها
### فاز ۵ — ناشر و درآمد
- [x] UI انتشار با قیمت‌گذاری (`AISkillPublishDialog`)
- [x] سهم ناشر از فروش (پیش‌فرض ۷۰٪) + واریز به کیف پول
- [x] API گزارش درآمد ناشر (`GET .../publisher/revenue`)
- [x] صفحه داشبورد درآمد ناشر
- [x] تأیید خرید مهارت پولی قبل از نصب
- [x] لیست مهارت‌های owned + دکمه انتشار در sheet
### فاز ۵ — تکمیل
- [x] UI ادمین تنظیم درصد سهم ناشر (`/system-settings/ai-marketplace`)
- [x] API `GET/PUT /admin/system-settings/marketplace`