项目概述
Stratagem.php（策士）是一个面向 AI Agent 的 PHP 技能锦囊系统，采用独特的「双模设计」——每个锦囊既是可执行的 CLI 工具，又是 Agent 可阅读的技能文档。项目同时实现了 MCP（Model Context Protocol）和 A2A（Agent-to-Agent）两大协议。
本文是对该项目的完整深度审阅与改进方案，涵盖架构、安全、性能、开发者体验等维度，并提供了分 6 阶段、约 20-28 周的实施路线图。
---
📊 当前状态评估
| 维度 | 状态 | 评级 | 说明 |
|---|---|---|---|
| 架构设计 | 良好 | ⭐⭐⭐⭐ | 模块化，职责分离清晰 |
| 功能完整度 | 良好 | ⭐⭐⭐⭐ | MCP/A2A 核心已实现 |
| 代码质量 | 中等 | ⭐⭐⭐ | 部分重复代码待重构 |
| 测试覆盖 | 中等 | ⭐⭐⭐ | 约 60%，需提升 |
| 安全机制 | 良好 | ⭐⭐⭐⭐ | 多层验证已部署 |
| 性能优化 | 待提升 | ⭐⭐ | 缓存、连接池待实现 |
| 文档完善 | 良好 | ⭐⭐⭐⭐ | README/AGENTS.md 详实 |
核心优势
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 系统完善
| 功能 | 说明 |
|---|---|
| 分布式发现 | UDP 多播 + DNS-SD + 静态配置 |
| 任务编排引擎 | 支持顺序/并行/条件分支/循环的工作流 DSL |
| 持久化恢复 | 任务快照、状态导出导入 |
| 能力协商 | 协议版本协商、传输方式协商 |
4. 锦囊系统进化
#### 4.1 版本与依赖管理
// 锦囊依赖声明示例
/**
* 【依赖条件】
* - PHP >= 8.0
* - ext-curl
* - stratagem:sg_json >= 1.0.0
* - composer:monolog/monolog ^2.0
*/
#### 4.2 沙箱执行（安全提升）
当前 execute() 直接 include 文件，建议改为子进程隔离：
$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+ 实用锦囊
| 高优先级 | 用途 |
|---|---|
| sg_http.php | HTTP 请求（GET/POST/PUT/DELETE） |
| sg_validate.php | 数据验证（邮箱、手机号等） |
| sg_cache.php | 文件/内存缓存操作 |
| sg_xml.php | XML 解析与生成 |
| sg_csv.php | CSV 读写转换 |
| sg_datetime.php | 日期时间、时区处理 |
| sg_regex.php | 正则表达式工具 |
| sg_encrypt.php | AES/RSA 加密解密 |
5. 安全与健壮性
已实施：路径遍历防护、SSL 验证、JSON 深度限制 待加强：
- 敏感信息脱敏（API Key、密码过滤）
- 审计日志系统
- 熔断器模式（故障恢复）
- 敏感操作二次确认
6. 测试与质量
目标：覆盖率 60% → 85%+
新增测试类型：
- 集成测试：MCPServer、A2A 集群、数据库
- 端到端测试：CLI 流程、MCP 客户端流程
- 性能测试：搜索基准、负载测试
- 契约测试：确保锦囊规范一致性
- 模糊测试：输入边界测试
7. 性能优化
| 优化项 | 说明 |
|---|---|
| 多级缓存 | 内存 → APCu → 文件 → 数据库 |
| 搜索缓存 | 查询结果缓存、智能失效策略 |
| 连接池 | 数据库连接复用、健康检查 |
| 异步支持 | Swoole/FrankenPHP 并发处理 |
| 水平扩展 | 任务分片、结果聚合 |
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*