Stratagem.php 项目深度改进方案 - 从架构到落地的完整路线图

项目概述

Stratagem.php（策士）是一个面向 AI Agent 的 PHP 技能锦囊系统，采用独特的「双模设计」——每个锦囊既是可执行的 CLI 工具，又是 Agent 可阅读的技能文档。项目同时实现了 MCP（Model Context Protocol）和 A2A（Agent-to-Agent）两大协议。

本文是对该项目的完整深度审阅与改进方案，涵盖架构、安全、性能、开发者体验等维度，并提供了分 6 阶段、约 20-28 周的实施路线图。

📊 当前状态评估

核心优势

1. 双模锦囊设计：既是脚本，又是技能文档
2. 多协议支持：MCP (stdio/SSE/HTTP) + A2A
3. 纯 PHP 零依赖：部署简单
4. FTS5 全文搜索：SQLite + BM25 算法
5. 安全优先：输入验证、路径白名单

🏗️ 十大改进方向

1. 架构演进：引入事件总线

当前组件耦合较紧，建议引入轻量级事件总线：

$eventBus->subscribe('stratagem.executed', function($payload) {
    $analytics->recordUsage($payload['name']);
});

$eventBus->subscribe('search.performed', function($payload) {
    $searchHistory->record($payload['query'], $payload['results']);
});

价值：解耦组件，支持异步处理、插件扩展。

2. MCP Server 深化

当前：仅支持 Tools
建议：实现 Resources 和 Prompts

• Resources：Agent 可直接读取锦囊内容作为上下文
• Prompts：提供结构化提示词模板
• 传输优化：SSE 多路复用、HTTP 批处理、请求签名验证

3. A2A 系统完善

4. 锦囊系统进化

4.1 版本与依赖管理

// 锦囊依赖声明示例
/**
 * 【依赖条件】
 * - PHP >= 8.0
 * - ext-curl
 * - stratagem:sg_json >= 1.0.0
 * - composer:monolog/monolog ^2.0
 */

4.2 沙箱执行（安全提升）

$cmd = sprintf(
    'php -d memory_limit=%s -d max_execution_time=%s %s %s',
    $this->memoryLimit,
    $this->timeLimit,
    escapeshellarg($filepath),
    implode(' ', array_map('escapeshellarg', $args))
);

4.3 建议新增 15+ 实用锦囊

5. 安全与健壮性

已实施：路径遍历防护、SSL 验证、JSON 深度限制
待加强：

• 敏感信息脱敏（API Key、密码过滤）
• 审计日志系统
• 熔断器模式（故障恢复）
• 敏感操作二次确认

6. 测试与质量

目标：覆盖率 60% → 85%+

新增测试类型：

• 集成测试：MCPServer、A2A 集群、数据库
• 端到端测试：CLI 流程、MCP 客户端流程
• 性能测试：搜索基准、负载测试
• 契约测试：确保锦囊规范一致性
• 模糊测试：输入边界测试

7. 性能优化

8. 开发者体验

# 建议的交互式 CLI
php bin/stratagem-cli

> init              # 交互式初始化
> search <keyword>  # 搜索锦囊
> install <name>    # 安装锦囊
> exec <name>       # 执行锦囊
> validate          # 验证锦囊规范
> test [name]       # 运行测试
> benchmark         # 性能测试
> doctor            # 系统诊断

9. 配置中心

统一多源配置管理（优先级从高到低）：

1. Runtime（手动设置）
2. Environment（环境变量）
3. Database（动态配置）
4. File（配置文件）
5. Default（默认值）

10. 运维与监控

• MetricsCollector：性能指标收集
• AuditLogger：操作审计
• SystemDoctor：系统诊断工具
• 文档自动生成：从锦囊注释生成文档

📅 分阶段实施路线图（6 阶段 / 20-28 周）

阶段一：基础完善（2-3 周）

• 查询结果缓存
• 懒加载和对象池
• 文件 I/O 优化
• 搜索历史和统计
• 配置管理系统

阶段二：架构演进（3-4 周）

• 事件总线实现
• MCP Resources 支持
• 插件系统架构
• 配置中心重构
• 锦囊沙箱执行

阶段三：A2A 深化（3-4 周）

• 分布式发现增强
• 任务编排引擎
• Agent 能力协商
• 持久化与恢复
• A2A 集群管理

阶段四：锦囊生态（4-6 周）

• 新增 15+ 实用锦囊
• 版本管理系统
• 依赖解析器
• 契约测试套件

阶段五：性能运维（2-3 周）

• 多级缓存实现
• 连接池优化
• 监控与指标
• 诊断工具

阶段六：企业级特性（4-6 周）

• 审计日志系统
• 访问控制 (RBAC)
• 敏感数据过滤
• 水平扩展支持
• 异步运行时

🎯 目标 KPI

• 代码覆盖率：60% → 85%+
• 平均响应时间：< 100ms（搜索）
• 缓存命中率：> 70%
• 错误率：< 0.1%
• 文档完整度：100%

📁 完整文档

详细的技术方案、代码示例、API 设计请参考项目中的 改进意见.md 文件（约 1000 行）。

发布日期：2026-02-13
项目地址：stratagem.php
文档版本：v1.0