PromptX/resource/role/luban/execution/tool-development-workflow.execution.md

## 技术架构约束 - **单文件工具**：每个工具必须是独立的.tool.js文件 - **ToolInterface规范**：必须实现execute()、getDependencies()、getMetadata()等标准接口 - **ToolSandbox兼容**：工具必须能在沙箱环境中正常运行 - **协议统一**：通过@tool://协议访问，沙箱位于@user://.promptx/toolbox/ - **依赖隔离**：每个工具的依赖安装在独立的沙箱目录中 ## 开发强制规则 - **接口完整性**：必须实现所有必要的接口方法 - **依赖声明**：所有外部依赖必须在getDependencies()中明确声明 - **参数验证**：必须实现validate()方法验证输入参数 - **错误处理**：必须有完善的异常处理机制 - **安全第一**：禁止执行危险操作，确保沙箱安全 ## 开发指导原则 - **用户体验优先**：接口设计简洁直观 - **性能效率**：优化执行速度和资源使用 - **可维护性**：代码结构清晰，注释完整 - **渐进式功能**：先实现核心功能，再扩展高级特性 - **测试驱动**：每个功能都要有相应的测试验证 ## 🛠️ 标准工具开发流程

Phase 1: 需求分析与设计 (15分钟)

flowchart TD
    A[用户需求] --> B[功能分析]
    B --> C[依赖调研]
    C --> D[接口设计]
    D --> E[原型验证]

Step 1.1: 深度需求分析

• 理解用户真实痛点
• 分析现有解决方案的不足
• 确定工具的核心价值主张
• 明确功能边界和使用场景

Step 1.2: 技术方案选择

• 选择合适的npm依赖包
• 评估依赖包的稳定性和文档质量
• 确认沙箱环境兼容性
• 设计错误处理策略

Step 1.3: 工具说明书设计

<!-- {tool-name}.tool.md 模板 -->
<tool>
<identity>
## 工具名称
@tool://{tool-name}

## 简介
工具功能的一句话简介
</identity>

<purpose>
⚠️ **AI重要提醒**: 调用此工具前必须完整阅读本说明书，理解工具功能边界、参数要求和使用限制。禁止在不了解工具功能的情况下盲目调用。

## 核心问题定义
明确描述工具要解决的具体问题

## 价值主张
- 🎯 **解决什么痛点**：具体描述用户痛点
- 🚀 **带来什么价值**：明确量化收益  
- 🌟 **独特优势**：相比其他方案的优势

## 应用边界
- ✅ **适用场景**：详细列出适用情况
- ❌ **不适用场景**：明确使用边界
</purpose>

<usage>
<!-- 详细的使用指导 -->
</usage>

<parameter>
<!-- 完整的参数说明 -->
</parameter>

<outcome>
<!-- 返回结果格式说明 -->
</outcome>
</tool>

Step 1.4: 接口规范设计

// 标准工具接口模板
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分钟)

flowchart LR
    A[创建工具文件] --> B[编写说明书]
    B --> C[实现接口方法]
    C --> D[依赖管理]
    D --> E[核心逻辑]
    E --> F[错误处理]

Step 2.1: 工具文件创建

# 标准文件路径
.promptx/resource/tool/{tool-name}/{tool-name}.tool.js    # 给计算机的执行代码
.promptx/resource/tool/{tool-name}/{tool-name}.tool.md    # 给AI的使用说明书

Step 2.2: 工具说明书编写 基于Phase 1的设计，完整编写五组件说明书：

<tool>
<identity>
## 工具名称
@tool://actual-tool-name

## 简介
具体的工具功能描述
</identity>

<purpose>
⚠️ **AI重要提醒**: 调用此工具前必须完整阅读本说明书，理解工具功能边界、参数要求和使用限制。禁止在不了解工具功能的情况下盲目调用。

## 核心问题定义
[具体问题描述]

## 价值主张
- 🎯 **解决什么痛点**：[具体痛点]
- 🚀 **带来什么价值**：[具体价值]
- 🌟 **独特优势**：[核心优势]

## 应用边界
- ✅ **适用场景**：[适用情况]
- ❌ **不适用场景**：[限制条件]
</purpose>

<usage>
## 使用时机
[具体使用场景]

## 操作步骤
1. **准备阶段**：[准备工作]
2. **执行阶段**：[执行步骤]
3. **验证阶段**：[验证方法]

## 最佳实践
- 🎯 **效率提升**：[效率技巧]
- ⚠️ **避免陷阱**：[常见问题]
- 🔧 **故障排除**：[问题解决]

## 注意事项
[重要提醒事项]
</usage>

<parameter>
## 必需参数
| 参数名 | 类型 | 描述 | 示例 |
|--------|------|------|------|
| [参数] | [类型] | [描述] | [示例] |

## 可选参数
| 参数名 | 类型 | 默认值 | 描述 |
|--------|------|--------|------|
| [参数] | [类型] | [默认值] | [描述] |

## 参数约束
- **[约束类型]**：[约束说明]

## 参数示例
```json
{
  "[参数名]": "[参数值]"
}

## 成功返回格式 ```json { "success": true, "data": { "[数据字段]": "[数据说明]" } } ```

错误处理格式

{
  "success": false,
  "error": {
    "code": "[错误代码]",
    "message": "[错误信息]"
  }
}

结果解读指南

• [使用方式]：[说明]

后续动作建议

• [成功时的建议]
• [失败时的建议]

**Step 2.3: 依赖管理实现**
```javascript
getDependencies() {
  return [
    'lodash@^4.17.21',     // 工具函数库
    'axios@^1.6.0',       // HTTP请求
    'validator@^13.11.0'  // 数据验证
  ];
}

Step 2.4: 元信息定义

getMetadata() {
  return {
    name: 'my-awesome-tool',
    description: '这是一个很棒的工具，用于...',
    version: '1.0.0',
    category: 'utility',
    author: '鲁班',
    tags: ['tool', 'automation', 'utility']
  };
}

Step 2.5: Schema定义

getSchema() {
  return {
    type: 'object',
    properties: {
      input: {
        type: 'string',
        description: '输入参数描述'
      },
      options: {
        type: 'object',
        properties: {
          format: { type: 'string', default: 'json' }
        }
      }
    },
    required: ['input']
  };
}

Phase 3: 沙箱测试 (15分钟)

flowchart TD
    A[ToolSandbox创建] --> B[依赖安装]
    B --> C[功能测试]
    C --> D[边界测试]
    D --> E[性能测试]

Step 3.1: 沙箱环境验证

// 测试代码示例
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分钟)

flowchart LR
    A[代码优化] --> B[文档完善]
    B --> C[注册表更新]
    C --> D[用户验收]

Step 4.1: 代码质量优化

• 重构冗余代码
• 优化性能瓶颈
• 完善错误信息
• 添加调试日志

Step 4.2: 注册表刷新与验证

🔄 刷新项目级资源注册表

在MCP环境中使用init工具：

• 使用MCP PromptX的promptx_init工具刷新项目级注册表
• 该工具会重新扫描.promptx/resource/目录并更新资源注册表
• 调用后工具立即可用，无需重启MCP服务器

调用方式：

工具名称: promptx_init  
参数: {"workingDirectory": "/current/project/path"}

🔍 验证工具注册成功

使用MCP工具验证：

• 使用promptx_welcome工具查看是否出现新工具
• 使用promptx_tool工具测试新工具是否可用
• 检查工具列表中是否包含新开发的工具

🚨 注册表刷新关键时机

• ✅ 创建新工具后必须执行
• ✅ 修改工具metadata后需要执行
• ✅ MCP缓存问题时需要执行
• ✅ 工具无法被发现时需要执行

💡 PromptX注册表机制解释

• 项目级扫描：promptx init重新扫描.promptx/resource/目录
• 缓存重置：清理ResourceManager缓存，重新发现资源
• MCP同步：确保MCP服务器获取最新的工具列表

Step 4.3: 用户接受度验证

• 接口易用性评估
• 功能完整性确认
• 性能表现验证
• 安全性审查

🔧 高级开发技巧

依赖优化策略

getDependencies() {
  // 按需声明，避免冗余
  const dependencies = [];
  
  // 基础功能依赖
  if (this.needsUtilities()) {
    dependencies.push('lodash@^4.17.21');
  }
  
  // 网络功能依赖
  if (this.needsHttp()) {
    dependencies.push('axios@^1.6.0');
  }
  
  return dependencies;
}

智能错误处理

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}`);
    }
  }
}

性能优化模式

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;
}

## 工具质量评价标准

功能完整性 (25分)

• ✅ 核心功能完全实现
• ✅ 边界情况正确处理
• ✅ 错误场景优雅降级
• ✅ 用户需求完全满足

技术规范性 (25分)

• ✅ ToolInterface完全符合
• ✅ 依赖声明准确完整
• ✅ Schema定义标准规范
• ✅ 代码结构清晰可维护

沙箱兼容性 (25分)

• ✅ ToolSandbox正常运行
• ✅ 依赖自动安装成功
• ✅ 资源隔离正确工作
• ✅ 协议访问正常响应

用户体验质量 (25分)

• ✅ 接口简洁易用
• ✅ 错误信息友好
• ✅ 性能表现优秀
• ✅ 文档描述准确

卓越标准 (附加分)

• 🌟 创新功能设计
• 🌟 极致性能优化
• 🌟 出色的错误处理
• 🌟 完美的用户体验