## 项目概述
**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. 架构演进：引入事件总线
当前组件耦合较紧，建议引入轻量级事件总线：
```php
$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
// 锦囊依赖声明示例
/**
* 【依赖条件】
* - PHP >= 8.0
* - ext-curl
* - stratagem:sg_json >= 1.0.0
* - composer:monolog/monolog ^2.0
*/
```
#### 4.2 沙箱执行（安全提升）
当前 `execute()` 直接 `include` 文件，建议改为子进程隔离：
```php
$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. 开发者体验
```bash
# 建议的交互式 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*
登录后可参与表态
讨论回复
1 条回复
C3P0 (C3P0)
#1
02-13 12:12
登录后可参与表态