poiesis (Arthur2jolly)

Poesis——人工智能代理的模块化敏捷项目管理

诗艺 是一个生产就绪的敏捷项目管理平台，旨在通过 模型上下文协议（MCP）它为AI代理提供了结构化的工具和工作流程，以在完全模块化的架构中管理项目、史诗、故事和任务。

______________________________________________________________________

特性

核心能力

• 分层项目结构：项目→ 史诗→ 故事→ Tasks
• 统一状态生命周期: draft → open → closed （重新开放）
• 依赖项跟踪：声明工件之间的依赖关系；打开工作前检查阻断器
• 模块系统：通过可插拔模块扩展平台功能
• 多租户（SaaS）：具有自动全局作用域的行级租户隔离-对API使用者透明
• 多用户协作：两层访问控制——全局用户角色和每个项目的成员角色
• RESTful API：基于HTTP的项目管理端点
• MCP服务器：用于AI代理控制的原生MCP 2.0集成

MCP服务器功能

MCP服务器公开：

• 36+工具：项目、史诗、故事、任务、模块和依赖关系的完整CRUD操作
• 2资源：项目概述和配置快照
• 1提示：AI代理的敏捷工作流程指南
• HTTP传输：支持服务器发送事件的流式HTTP
• 承载令牌认证：安全的代理到服务器通信

______________________________________________________________________

安装和设置

需求

• PHP 8.4+
• Laravel 12
• MariaDB 11.8+（或任何兼容的数据库）

快速开始

git clone https://github.com/arthur2jolly/poiesis.git
cd poiesis
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate --seed
php artisan serve

______________________________________________________________________

使用MCP服务器

认证

所有MCP请求都需要 持有者代币 在 Authorization 头球

curl -X POST http://localhost:8000/mcp \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{}}'

生成令牌：

php artisan artisan:token:create --name="Agent" --user-id=1

MCP端点

• POST/mcp：JSON-RPC请求处理程序（初始化、工具/列表、工具/调用、资源/列表、资源/读取、提示/列表、提示/获取）
• GET/mcp：服务器发送推送通知的事件流

可用工具

项目管理

• list_projects --列出所有可访问的项目
• get_project --获取项目详细信息
• create_project --创建新项目
• update_project --更新项目标题/描述
• delete_project --删除项目（仅限所有者）

史诗

• list_epics --列出项目中的史诗
• get_epic --获取史诗般的细节
• create_epic --创造史诗
• update_epic --更新史诗
• delete_epic --删除史诗和儿童故事

故事

• list_stories --列出带有可选过滤器（类型、优先级、状态、标签）的故事
• get_story --获取带有依赖关系的故事
• create_story --在史诗中创造一个故事
• create_stories --批量创建故事（原子）
• update_story --更新故事字段
• delete_story --删除故事和子任务
• update_story_status --更改状态（草稿→open→关闭）
• list_epic_stories --列出特定史诗的故事

任务

• list_tasks --使用筛选器列出项目中的所有任务
• get_task --获取任务详细信息
• create_task --创建独立任务或子任务
• create_tasks --批量创建任务（原子）
• update_task --更新任务
• delete_task --删除任务
• update_task_status --更改任务状态

文物和搜索

• resolve_artifact --解析标识符（例如。， POIESIS-1)到完整对象
• search_artifacts --项目中的全文搜索

依赖项

• add_dependency --声明工件A被工件B阻挡
• remove_dependency --删除依赖项
• list_dependencies --检查工件的依赖关系图

模块

• list_available_modules --列出所有可用模块
• list_project_modules --列出项目的活动模块
• activate_module --激活模块（仅限所有者）
• deactivate_module --停用模块（仅限所有者）

可用资源

• project://{code}/overview --项目摘要（史诗/故事/任务计数、活动模块）
• project://{code}/config --项目配置（允许的类型、优先级、活动模块）

工作流提示

这 agile-workflow 提示包含：

• 层次结构解释（项目→ Epic → 故事→ Task)
• 状态生命周期
• 工作流最佳实践
• 依赖关系和模块指南
• 惯例和使用模式

客户端可以通过以下方式获取此提示 prompts/get 为法学硕士提供结构化的指导。

______________________________________________________________________

开发与扩展

文件结构

app/Core/
├── Mcp/
│   ├── Contracts/
│   │   ├── McpToolInterface.php      # Tool provider contract
│   │   ├── McpResourceInterface.php  # Resource provider contract
│   │   └── McpPromptInterface.php    # Prompt provider contract
│   ├── Tools/
│   │   ├── ProjectTools.php          # Project CRUD
│   │   ├── EpicTools.php             # Epic management
│   │   ├── StoryTools.php            # Story management
│   │   ├── TaskTools.php             # Task management
│   │   ├── ArtifactTools.php         # Search & resolve
│   │   ├── DependencyTools.php       # Dependency graph
│   │   └── ModuleTools.php           # Module activation
│   ├── Resources/
│   │   ├── ProjectOverviewResource.php
│   │   └── ProjectConfigResource.php
│   ├── Prompts/
│   │   └── AgileWorkflowPrompt.php   # Workflow guide
│   ├── Http/Controllers/
│   │   └── McpController.php         # HTTP handler
│   ├── Server/
│   │   ├── McpServer.php             # Core MCP dispatch
│   │   └── McpTransport.php          # JSON-RPC codec
│   └── Routes/
│       └── mcp.php                   # MCP endpoint routes
└── Providers/
    └── CoreServiceProvider.php       # Tool/resource registration

添加新工具

1. 创建工具提供程序 （例如。， app/Core/Mcp/Tools/CustomTools.php):

   namespace App\Core\Mcp\Tools;
   use App\Core\Mcp\Contracts\McpToolInterface;
   use App\Core\Models\User;

   class CustomTools implements McpToolInterface
   {
       public function tools(): array
       {
           return [
               [
                   'name' => 'custom_action',
                   'description' => 'Does something custom',
                   'inputSchema' => [
                       'type' => 'object',
                       'properties' => [
                           'param' => ['type' => 'string'],
                       ],
                       'required' => ['param'],
                   ],
               ],
           ];
       }

       public function execute(string $toolName, array $params, User $user): mixed
       {
           return match ($toolName) {
               'custom_action' => $this->doAction($params),
               default => throw new \InvalidArgumentException("Unknown tool: {$toolName}"),
           };
       }

       private function doAction(array $params): array
       {
           // Implementation
           return ['result' => 'success'];
       }
   }

1. 注册于 CoreServiceProvider:

   private function registerMcpTools(): void
   {
       $server = $this->app->make(McpServer::class);
       $server->registerCoreTools(new CustomTools);
   }

添加新资源

1. 创建资源提供者 （例如。， app/Core/Mcp/Resources/CustomResource.php):

   namespace App\Core\Mcp\Resources;
   use App\Core\Mcp\Contracts\McpResourceInterface;
   use App\Core\Models\User;

   class CustomResource implements McpResourceInterface
   {
       public function uri(): string
       {
           return 'custom://{id}';
       }

       public function name(): string
       {
           return 'Custom Resource';
       }

       public function description(): string
       {
           return 'A custom resource';
       }

       public function read(array $params, User $user): mixed
       {
           $id = $params['id'] ?? null;
           return ['id' => $id, 'data' => 'value'];
       }
   }

1. 注册于 CoreServiceProvider:

   private function registerMcpResources(): void
   {
       $server = $this->app->make(McpServer::class);
       $server->registerCoreResource(new CustomResource);
   }

添加新提示

1. 创建提示提供者 （例如。， app/Core/Mcp/Prompts/CustomPrompt.php):

   namespace App\Core\Mcp\Prompts;
   use App\Core\Mcp\Contracts\McpPromptInterface;

   class CustomPrompt implements McpPromptInterface
   {
       public function name(): string
       {
           return 'custom-guide';
       }

       public function description(): string
       {
           return 'Custom workflow guide';
       }

       public function messages(): array
       {
           return [
               [
                   'role' => 'user',
                   'content' => [
                       'type' => 'text',
                       'text' => file_get_contents(resource_path('mcp/custom.md')),
                   ],
               ],
           ];
       }
   }

1. 创建内容 在 resources/mcp/custom.md

1. 注册于 CoreServiceProvider:

   private function registerMcpPrompts(): void
   {
       $server = $this->app->make(McpServer::class);
       $server->registerPrompt(new CustomPrompt);
   }

创建新模块

模块是可插拔的扩展，可以添加特定于域的工具、资源和工作流。每个模块由以下部分组成：

1. 工具提供商 --特定于该模块的其他MCP工具
2. 可选资源和提示 --特定域上下文
3. 注册 --在模块注册表中声明可选依赖项

步骤1：创建模块结构

为您的模块创建一个目录（例如。， app/Modules/Reporting/):

app/Modules/Reporting/
├── MCP/
│   ├── Tools/
│   │   ├── ReportTools.php        # Tools for this module
│   │   └── AnalyticsTools.php
│   ├── Resources/
│   │   └── ReportingConfigResource.php
│   └── Prompts/
│       └── ReportingGuidePrompt.php
├── Services/
│   ├── ReportService.php
│   └── AnalyticsService.php
├── Models/
│   ├── Report.php
│   └── ReportTemplate.php
└── ReportingModuleProvider.php

步骤2：创建工具提供者

app/Modules/Reporting/MCP/Tools/ReportTools.php:

namespace App\Modules\Reporting\MCP\Tools;
use App\Core\Mcp\Contracts\McpToolInterface;
use App\Core\Models\User;

class ReportTools implements McpToolInterface
{
    public function tools(): array
    {
        return [
            [
                'name' => 'generate_report',
                'description' => 'Generate a report for a project',
                'inputSchema' => [
                    'type' => 'object',
                    'properties' => [
                        'project_code' => ['type' => 'string'],
                        'format' => ['type' => 'string', 'enum' => ['json', 'pdf']],
                        'include_metrics' => ['type' => 'boolean'],
                    ],
                    'required' => ['project_code'],
                ],
            ],
            [
                'name' => 'list_reports',
                'description' => 'List all reports for a project',
                'inputSchema' => [
                    'type' => 'object',
                    'properties' => [
                        'project_code' => ['type' => 'string'],
                    ],
                    'required' => ['project_code'],
                ],
            ],
        ];
    }

    public function execute(string $toolName, array $params, User $user): mixed
    {
        return match ($toolName) {
            'generate_report' => $this->generateReport($params, $user),
            'list_reports' => $this->listReports($params, $user),
            default => throw new \InvalidArgumentException("Unknown tool: {$toolName}"),
        };
    }

    private function generateReport(array $params, User $user): array
    {
        // Implementation
        return ['report_id' => 'REP-1', 'url' => 'https://...'];
    }

    private function listReports(array $params, User $user): array
    {
        // Implementation
        return ['data' => []];
    }
}

步骤3：创建模块提供程序

app/Modules/Reporting/ReportingModuleProvider.php:

namespace App\Modules\Reporting;
use App\Core\Mcp\Server\McpServer;
use App\Modules\Reporting\MCP\Tools\ReportTools;
use App\Modules\Reporting\MCP\Tools\AnalyticsTools;
use Illuminate\Support\ServiceProvider;

class ReportingModuleProvider extends ServiceProvider
{
    public function register(): void
    {
        // Bind module services
        $this->app->singleton(\App\Modules\Reporting\Services\ReportService::class);
    }

    public function boot(): void
    {
        // Publish migrations, assets, etc.
        $this->publishMigrations();
        $this->publishConfig();

        // Register MCP tools for this module
        $this->registerMcpTools();
    }

    private function registerMcpTools(): void
    {
        $server = $this->app->make(McpServer::class);

        // Register tools under module slug 'reporting'
        $server->registerModuleTools('reporting', [
            new ReportTools,
            new AnalyticsTools,
        ]);
    }

    private function publishMigrations(): void
    {
        $this->publishesMigrations([
            __DIR__.'/../database/migrations' => database_path('migrations'),
        ]);
    }

    private function publishConfig(): void
    {
        $this->publishes([
            __DIR__.'/../config/reporting.php' => config_path('modules/reporting.php'),
        ]);
    }
}

步骤4：在Laravel中注册模块

增添 config/app.php 供应商：

\App\Modules\Reporting\ReportingModuleProvider::class,

步骤5：在模块注册表中注册模块

创建 app/Core/Module/ModuleRegistry.php （或更新（如果存在）以声明模块元数据：

public function registerModule(string $slug, array $config): void
{
    $this->modules[$slug] = [
        'name' => $config['name'],
        'description' => $config['description'],
        'dependencies' => $config['dependencies'] ?? [],
    ];
}

// In a service provider or boot method:
$this->app->make(ModuleRegistry::class)->registerModule('reporting', [
    'name' => 'Reporting',
    'description' => 'Generate reports and analytics',
    'dependencies' => [], // List dependent module slugs, e.g., ['core']
]);

步骤6：运行迁移

php artisan migrate

结果

一旦注册，代理人可以：

1. 列出可用模块：

   curl ... -d '{"jsonrpc":"2.0","method":"tools/list","params":{}}'
   # → Now includes tools from ReportTools and AnalyticsTools

1. 激活项目的模块：

   curl ... -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"activate_module","arguments":{"project_code":"MY_PROJECT","slug":"reporting"}}}'

1. 使用模块工具：

   curl ... -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"generate_report","arguments":{"project_code":"MY_PROJECT","format":"pdf"}}}'

工作流文档

敏捷工作流指南存储在：

resources/mcp/agile-workflow.md

编辑此文件 调整指导方针，添加特定于模块的说明，或在不修改PHP代码的情况下更新最佳实践。

______________________________________________________________________

代码质量

棉绒（PSR-12）

./vendor/bin/pint              # Fix issues
./vendor/bin/pint --test       # Check without fixing

静态分析（PHPTan 8级）

./vendor/bin/phpstan analyse --no-progress

测试（害虫）

./vendor/bin/pest

______________________________________________________________________

多租户技术

Poiesis支持 行级多租户 SaaS部署。每个租户都有独立的用户、项目、令牌和工件。

运作原理

• A. BelongsToTenant 特质适用于 全局范围 在所有租户感知模型上（用户、项目、ApiToken、OAuthClient、OAuthAccessToken、OAuth授权代码、工件）
• 租户已从Bearer令牌中解析出来 AuthenticateBearer 中间件并存储在 TenantManager 单例
• 所有查询都是自动作用域的——控制器或MCP工具中不需要更改代码
• CLI命令使用 withoutTenantScope() 跨租户运营

租户管理

# Create a tenant (optionally create an owner user)
php artisan tenant:create "Acme Corp" --slug=acme

# List all tenants
php artisan tenant:list

# Enable / disable a tenant
php artisan tenant:enable acme
php artisan tenant:disable acme

# Delete a tenant and ALL its data (cascading)
php artisan tenant:delete acme

# Assign orphan rows (tenant_id=null) to a tenant
php artisan tenant:assign-default acme

# Create a superadmin (separate from tenant users)
php artisan superadmin:create --name=admin --password=secret123

用户和租户令牌

# Create a user in a specific tenant
php artisan user:create --tenant=acme --role=1

# Create a token for a user in a specific tenant
php artisan token:create john --tenant=acme --name=agent

______________________________________________________________________

访问控制

Poiesis使用两个独立的角色系统协同工作。

全局用户角色

在用户创建时分配，控制用户可以在整个平台上执行哪些操作（MCP工具、REST API）：

php artisan user:create --role=2   # creates a manager

项目成员角色

按项目分配，控制项目级管理：

用户必须具有 两者 适当的全球角色（对工件采取行动） 和 成为项目的成员（访问它）。

# Add a user to a project (project role: member, global role unchanged)
php artisan project:add-member PROJ claude.dev

# Add and set global role at the same time
php artisan project:add-member PROJ claude.manager --role=owner --policy=manager

# Update an existing member
php artisan project:update-member PROJ claude.dev --policy=developer
php artisan project:update-member PROJ claude.dev --role=owner

# List / remove
php artisan project:members PROJ
php artisan project:remove-member PROJ claude.dev

______________________________________________________________________

数据库管理

创建用户

php artisan user:create [--tenant=acme] [--role=4]

生成MCP令牌

php artisan token:create  [--tenant=acme] [--name=default] [--expires=30d]

______________________________________________________________________

生产部署

环境配置

• 集 APP_ENV=production
• 使用强力 APP_KEY
• 配置数据库凭据
• 启用HTTPS（MCP在生产中需要安全连接）

数据库

• 使用托管MariaDB 11.8+（AWS RDS、DigitalOcean等）
• 运行迁移： php artisan migrate
• 考虑读取副本以实现规模

网络服务器

• 使用 Nginx 和 PHP-FPM
• 如果位于负载平衡器之后，则配置反向代理
• 启用gzip压缩

持有者代币

• 通过CLI生成令牌： php artisan artisan:token:create
• 定期旋转令牌
• 在代理配置中安全存储

监控

• 监视器 php artisan queue:work 如果使用异步作业
• 记录MCP请求：检查 storage/logs/
• 设置HTTP 5xx错误警报

______________________________________________________________________

许可证

Apache许可证2.0。看 许可证 文件以获取详细信息。