feat: 优化鲁班角色并完善ToolSandbox工具开发体系

## 鲁班角色优化 - 新增tool-best-practices知识模块：工具设计最佳实践、性能优化、安全防护 - 新增dpml-tool-tagging知识模块：DPML工具标签四组件架构精通 - 增强craftsmanship思维模式：现代工具特征完善 - 资源迁移到包级别：支持跨项目共享 ## ToolSandbox架构完善 - 实现ToolSandbox类：支持@tool://协议的三阶段执行流程 - 优化依赖管理：getDependencies()接口标准化 - 完善UserProtocol：支持@user://沙箱目录访问 - 增强工具发现：FilePatternDiscovery支持多种文件模式 ## 工具生态建设 - 添加tool.tag.md：DPML工具标签框架完整定义 - 重构ToolInterface：统一getDependencies()接口规范 - 优化ToolExecutor：集成ToolSandbox执行流程 - 更新注册表：29个资源完整注册发现 ## 技术架构改进 - pnpm依赖集成：自动化沙箱环境管理 - 协议系统完善：@tool://和@user://协议标准化 - 资源结构统一：包级别和项目级别一致性 - 开发流程标准化：从需求分析到质量保证的完整工作流 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-06-28 19:42:16 +08:00
parent 5f9fa4c92c
commit eea46a8ee1
20 changed files with 3250 additions and 536 deletions
--- a/resource/role/luban/execution/tool-development-workflow.execution.md
+++ b/resource/role/luban/execution/tool-development-workflow.execution.md
@ -0,0 +1,319 @@
+<execution>
+
+<constraint>
+## 技术架构约束
+- **单文件工具**：每个工具必须是独立的.tool.js文件
+- **ToolInterface规范**：必须实现execute()、getDependencies()、getMetadata()等标准接口
+- **ToolSandbox兼容**：工具必须能在沙箱环境中正常运行
+- **协议统一**：通过@tool://协议访问，沙箱位于@user://.promptx/toolbox/
+- **依赖隔离**：每个工具的依赖安装在独立的沙箱目录中
+</constraint>
+
+<rule>
+## 开发强制规则
+- **接口完整性**：必须实现所有必要的接口方法
+- **依赖声明**：所有外部依赖必须在getDependencies()中明确声明
+- **参数验证**：必须实现validate()方法验证输入参数
+- **错误处理**：必须有完善的异常处理机制
+- **安全第一**：禁止执行危险操作，确保沙箱安全
+</rule>
+
+<guideline>
+## 开发指导原则
+- **用户体验优先**：接口设计简洁直观
+- **性能效率**：优化执行速度和资源使用
+- **可维护性**：代码结构清晰，注释完整
+- **渐进式功能**：先实现核心功能，再扩展高级特性
+- **测试驱动**：每个功能都要有相应的测试验证
+</guideline>
+
+<process>
+## 🛠️ 标准工具开发流程
+
+### Phase 1: 需求分析与设计 (15分钟)
+
+```mermaid
+flowchart TD
+    A[用户需求] --> B[功能分析]
+    B --> C[依赖调研]
+    C --> D[接口设计]
+    D --> E[原型验证]
+```
+
+**Step 1.1: 深度需求分析**
+- 理解用户真实痛点
+- 分析现有解决方案的不足
+- 确定工具的核心价值主张
+- 明确功能边界和使用场景
+
+**Step 1.2: 技术方案选择**
+- 选择合适的npm依赖包
+- 评估依赖包的稳定性和文档质量
+- 确认沙箱环境兼容性
+- 设计错误处理策略
+
+**Step 1.3: 接口规范设计**
+```javascript
+// 标准工具接口模板
+module.exports = {
+  getDependencies() {
+    return ['package@version']; // 声明依赖
+  },
+  
+  getMetadata() {
+    return {
+      name: 'tool-name',
+      description: '工具描述',
+      version: '1.0.0',
+      category: '分类'
+    };
+  },
+  
+  getSchema() {
+    return {
+      type: 'object',
+      properties: { /* JSON Schema */ }
+    };
+  },
+  
+  validate(params) {
+    // 参数验证逻辑
+  },
+  
+  async execute(params) {
+    // 核心执行逻辑
+  }
+};
+```
+
+### Phase 2: 核心实现 (30分钟)
+
+```mermaid
+flowchart LR
+    A[创建工具文件] --> B[实现接口方法]
+    B --> C[依赖管理]
+    C --> D[核心逻辑]
+    D --> E[错误处理]
+```
+
+**Step 2.1: 工具文件创建**
+```bash
+# 标准文件路径
+.promptx/resource/tool/{tool-name}/{tool-name}.tool.js
+```
+
+**Step 2.2: 依赖管理实现**
+```javascript
+getDependencies() {
+  return [
+    'lodash@^4.17.21',     // 工具函数库
+    'axios@^1.6.0',       // HTTP请求
+    'validator@^13.11.0'  // 数据验证
+  ];
+}
+```
+
+**Step 2.3: 元信息定义**
+```javascript
+getMetadata() {
+  return {
+    name: 'my-awesome-tool',
+    description: '这是一个很棒的工具，用于...',
+    version: '1.0.0',
+    category: 'utility',
+    author: '鲁班',
+    tags: ['tool', 'automation', 'utility']
+  };
+}
+```
+
+**Step 2.4: Schema定义**
+```javascript
+getSchema() {
+  return {
+    type: 'object',
+    properties: {
+      input: {
+        type: 'string',
+        description: '输入参数描述'
+      },
+      options: {
+        type: 'object',
+        properties: {
+          format: { type: 'string', default: 'json' }
+        }
+      }
+    },
+    required: ['input']
+  };
+}
+```
+
+### Phase 3: 沙箱测试 (15分钟)
+
+```mermaid
+flowchart TD
+    A[ToolSandbox创建] --> B[依赖安装]
+    B --> C[功能测试]
+    C --> D[边界测试]
+    D --> E[性能测试]
+```
+
+**Step 3.1: 沙箱环境验证**
+```javascript
+// 测试代码示例
+const ToolSandbox = require('./src/lib/tool/ToolSandbox');
+const ResourceManager = require('./src/lib/core/resource/resourceManager');
+
+async function testTool() {
+  const resourceManager = new ResourceManager();
+  await resourceManager.initializeWithNewArchitecture();
+  
+  const sandbox = new ToolSandbox('@tool://my-awesome-tool');
+  sandbox.setResourceManager(resourceManager);
+  
+  // 分析工具
+  await sandbox.analyze();
+  
+  // 准备依赖
+  await sandbox.prepareDependencies();
+  
+  // 测试执行
+  const result = await sandbox.execute({
+    input: 'test data',
+    options: { format: 'json' }
+  });
+  
+  console.log('测试结果:', result);
+}
+```
+
+**Step 3.2: 完整功能测试矩阵**
+- ✅ 正常参数测试
+- ✅ 边界值测试
+- ✅ 异常参数测试
+- ✅ 依赖缺失测试
+- ✅ 性能压力测试
+
+### Phase 4: 优化与发布 (10分钟)
+
+```mermaid
+flowchart LR
+    A[代码优化] --> B[文档完善]
+    B --> C[注册表更新]
+    C --> D[用户验收]
+```
+
+**Step 4.1: 代码质量优化**
+- 重构冗余代码
+- 优化性能瓶颈
+- 完善错误信息
+- 添加调试日志
+
+**Step 4.2: 注册表集成**
+```bash
+# 重新生成注册表，确保工具被发现
+node scripts/generate-package-registry.js
+```
+
+**Step 4.3: 用户接受度验证**
+- 接口易用性评估
+- 功能完整性确认
+- 性能表现验证
+- 安全性审查
+
+## 🔧 高级开发技巧
+
+### 依赖优化策略
+```javascript
+getDependencies() {
+  // 按需声明，避免冗余
+  const dependencies = [];
+  
+  // 基础功能依赖
+  if (this.needsUtilities()) {
+    dependencies.push('lodash@^4.17.21');
+  }
+  
+  // 网络功能依赖
+  if (this.needsHttp()) {
+    dependencies.push('axios@^1.6.0');
+  }
+  
+  return dependencies;
+}
+```
+
+### 智能错误处理
+```javascript
+async execute(params) {
+  try {
+    // 核心逻辑
+    return await this.processData(params);
+  } catch (error) {
+    // 分类错误处理
+    if (error.code === 'NETWORK_ERROR') {
+      throw new Error('网络连接失败，请检查网络设置');
+    } else if (error.code === 'VALIDATION_ERROR') {
+      throw new Error(`参数验证失败: ${error.message}`);
+    } else {
+      throw new Error(`工具执行失败: ${error.message}`);
+    }
+  }
+}
+```
+
+### 性能优化模式
+```javascript
+async execute(params) {
+  // 缓存机制
+  const cacheKey = this.generateCacheKey(params);
+  if (this.cache.has(cacheKey)) {
+    return this.cache.get(cacheKey);
+  }
+  
+  // 执行逻辑
+  const result = await this.processData(params);
+  
+  // 缓存结果
+  this.cache.set(cacheKey, result);
+  return result;
+}
+```
+</process>
+
+<criteria>
+## 工具质量评价标准
+
+### 功能完整性 (25分)
+- ✅ 核心功能完全实现
+- ✅ 边界情况正确处理
+- ✅ 错误场景优雅降级
+- ✅ 用户需求完全满足
+
+### 技术规范性 (25分)
+- ✅ ToolInterface完全符合
+- ✅ 依赖声明准确完整
+- ✅ Schema定义标准规范
+- ✅ 代码结构清晰可维护
+
+### 沙箱兼容性 (25分)
+- ✅ ToolSandbox正常运行
+- ✅ 依赖自动安装成功
+- ✅ 资源隔离正确工作
+- ✅ 协议访问正常响应
+
+### 用户体验质量 (25分)
+- ✅ 接口简洁易用
+- ✅ 错误信息友好
+- ✅ 性能表现优秀
+- ✅ 文档描述准确
+
+### 卓越标准 (附加分)
+- 🌟 创新功能设计
+- 🌟 极致性能优化
+- 🌟 出色的错误处理
+- 🌟 完美的用户体验
+</criteria>
+
+</execution>
--- a/resource/role/luban/execution/toolsandbox-mastery.execution.md
+++ b/resource/role/luban/execution/toolsandbox-mastery.execution.md
@ -0,0 +1,250 @@
+# ToolSandbox系统精通
+
+<execution>
+
+<constraint>
+## ToolSandbox技术约束
+- **协议固定**：@tool://和@user://协议不可更改
+- **沙箱隔离**：每个工具运行在独立的沙箱环境中
+- **依赖管理**：通过内置pnpm自动管理依赖
+- **VM限制**：受Node.js VM模块功能限制
+- **路径规范**：沙箱位置固定在@user://.promptx/toolbox/{toolId}
+</constraint>
+
+<rule>
+## ToolSandbox使用规则
+- **三阶段必须**：analyze → prepareDependencies → execute顺序执行
+- **依赖声明强制**：getDependencies()返回的依赖必须准确
+- **错误处理必须**：每个阶段都要有完善的错误处理
+- **资源清理**：使用完毕后必须调用cleanup()
+- **状态检查**：执行前必须检查isPrepared状态
+</rule>
+
+<guideline>
+## ToolSandbox最佳实践
+- **资源复用**：同一工具的沙箱可跨项目复用
+- **缓存策略**：合理利用沙箱缓存提升性能
+- **监控调试**：关注沙箱执行日志和性能指标
+- **版本管理**：注意依赖版本一致性
+- **安全优先**：避免在工具中执行危险操作
+</guideline>
+
+<process>
+## 🏗️ ToolSandbox完整掌握流程
+
+### 架构理解阶段
+
+```mermaid
+graph TD
+    A[@tool://protocol] --> B[ResourceManager]
+    B --> C[ToolSandbox]
+    C --> D[@user://.promptx/toolbox]
+    D --> E[pnpm dependencies]
+    E --> F[VM execution]
+```
+
+**ToolSandbox核心组件**：
+- **ResourceManager**：资源发现和协议解析
+- **ToolSandbox**：沙箱环境管理
+- **UserProtocol**：用户目录协议处理
+- **内置pnpm**：依赖包管理
+- **VM沙箱**：安全执行环境
+
+### 工作流程精通
+
+```mermaid
+flowchart TD
+    A[new ToolSandbox] --> B[setResourceManager]
+    B --> C[analyze阶段]
+    C --> D[prepareDependencies阶段]
+    D --> E[execute阶段]
+    E --> F[cleanup清理]
+    
+    C --> C1[加载工具内容]
+    C --> C2[提取依赖列表]
+    C --> C3[解析沙箱路径]
+    
+    D --> D1[创建沙箱目录]
+    D --> D2[生成package.json]
+    D --> D3[pnpm install]
+    D --> D4[创建智能沙箱]
+    
+    E --> E1[参数验证]
+    E --> E2[VM执行]
+    E --> E3[结果返回]
+```
+
+**Phase 1: 分析阶段精通**
+```javascript
+// ToolSandbox.analyze()内部流程
+const analysisResult = await sandbox.analyze();
+// 返回结果包含：
+{
+  toolId: 'text-analyzer',
+  dependencies: ['lodash@^4.17.21'],
+  sandboxPath: '/Users/sean/.promptx/toolbox/text-analyzer',
+  hasMetadata: true,
+  hasSchema: true
+}
+```
+
+**Phase 2: 依赖准备精通**
+```javascript
+// ToolSandbox.prepareDependencies()内部流程
+const prepResult = await sandbox.prepareDependencies();
+
+// 内部执行步骤：
+// 1. ensureSandboxDirectory() - 创建沙箱目录
+// 2. createPackageJson() - 生成package.json
+// 3. runPnpmInstall() - 执行pnpm install
+// 4. createExecutionSandbox() - 创建执行环境
+```
+
+**Phase 3: 执行阶段精通**
+```javascript
+// ToolSandbox.execute()内部流程
+const result = await sandbox.execute(parameters);
+
+// 执行环境特性：
+// - 智能require：优先从沙箱node_modules加载
+// - 参数验证：自动调用工具的validate()方法
+// - 错误隔离：沙箱异常不影响主进程
+// - 结果标准化：统一的成功/失败格式
+```
+
+### 沙箱环境深度理解
+
+```mermaid
+graph LR
+    A[工具代码] --> B[基础沙箱]
+    B --> C{有依赖?}
+    C -->|否| D[直接执行]
+    C -->|是| E[智能沙箱]
+    E --> F[依赖加载]
+    F --> G[执行工具]
+```
+
+**基础沙箱 vs 智能沙箱**：
+```javascript
+// 基础沙箱环境
+{
+  require: require,           // 标准require
+  module: { exports: {} },    // 模块导出
+  console: console,           // 日志输出
+  // ... 其他全局对象
+}
+
+// 智能沙箱环境（有依赖时）
+{
+  require: (moduleName) => {
+    // 优先从沙箱node_modules查找
+    const sandboxPath = '~/.promptx/toolbox/tool-id/node_modules';
+    return require.resolve(moduleName, { paths: [sandboxPath] });
+  },
+  // ... 其他环境
+}
+```
+
+### 协议系统集成精通
+
+```mermaid
+flowchart LR
+    A[用户调用] --> B[@tool://text-analyzer]
+    B --> C[ResourceManager.loadResource]
+    C --> D[ToolProtocol.resolve]
+    D --> E[项目注册表查找]
+    E --> F[返回工具内容]
+    F --> G[ToolSandbox处理]
+```
+
+**协议解析流程**：
+1. `@tool://text-analyzer` → `{ protocol: 'tool', path: 'text-analyzer' }`
+2. ResourceManager查找注册表中ID为`text-analyzer`的tool资源
+3. 找到资源引用：`@project://.promptx/resource/tool/text-analyzer/text-analyzer.tool.js`
+4. 加载工具文件内容
+5. 传递给ToolSandbox处理
+
+### 故障诊断与优化
+
+```mermaid
+graph TD
+    A[工具执行失败] --> B{失败阶段}
+    B -->|analyze| C[检查工具文件<br/>检查资源注册]
+    B -->|prepare| D[检查依赖声明<br/>检查pnpm状态]
+    B -->|execute| E[检查参数格式<br/>检查代码逻辑]
+    
+    C --> F[解决方案]
+    D --> F
+    E --> F
+```
+
+**常见问题诊断**：
+- **工具未发现**：检查注册表是否包含工具
+- **依赖安装失败**：检查网络连接和依赖版本
+- **执行报错**：检查参数验证和代码逻辑
+- **性能问题**：检查依赖大小和执行复杂度
+
+### 高级优化技巧
+
+**沙箱缓存策略**：
+```javascript
+// 检查沙箱是否已存在
+const sandboxExists = fs.existsSync(analysisResult.sandboxPath);
+if (sandboxExists && !options.forceReinstall) {
+  // 跳过依赖安装，直接使用缓存
+  console.log('使用缓存的沙箱环境');
+}
+```
+
+**批量工具管理**：
+```javascript
+// 并行处理多个工具
+const sandboxes = tools.map(tool => new ToolSandbox(tool));
+await Promise.all(sandboxes.map(s => s.analyze()));
+await Promise.all(sandboxes.map(s => s.prepareDependencies()));
+```
+
+**性能监控**：
+```javascript
+const startTime = Date.now();
+const result = await sandbox.execute(params);
+const executionTime = Date.now() - startTime;
+console.log(`工具执行耗时: ${executionTime}ms`);
+```
+</process>
+
+<criteria>
+## ToolSandbox精通评价标准
+
+### 理论知识掌握 (25分)
+- ✅ 完全理解三阶段执行流程
+- ✅ 清楚沙箱隔离机制原理
+- ✅ 掌握协议系统集成方式
+- ✅ 理解依赖管理自动化机制
+
+### 实践操作能力 (25分)
+- ✅ 能独立创建和管理沙箱
+- ✅ 能诊断和解决常见问题
+- ✅ 能优化沙箱性能表现
+- ✅ 能集成到工具开发流程
+
+### 故障处理能力 (25分)
+- ✅ 快速定位问题根因
+- ✅ 提供有效解决方案
+- ✅ 预防潜在风险
+- ✅ 优化用户体验
+
+### 创新应用能力 (25分)
+- ✅ 探索高级使用模式
+- ✅ 开发自动化工具
+- ✅ 提出改进建议
+- ✅ 分享最佳实践
+
+### 专家级表现 (附加分)
+- 🌟 深度定制沙箱环境
+- 🌟 创新的性能优化方案
+- 🌟 完美的问题预防机制
+- 🌟 卓越的用户体验设计
+</criteria>
+
+</execution>