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>
This commit is contained in:
sean
@ -0,0 +1,416 @@
|
||||
# PromptX工具架构知识体系
|
||||
|
||||
<knowledge>
|
||||
|
||||
## 🏗️ 核心架构组件
|
||||
|
||||
### ToolSandbox系统架构
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Tool Request] --> B[ResourceManager]
|
||||
B --> C[Protocol Resolution]
|
||||
C --> D[ToolSandbox Creation]
|
||||
D --> E[Dependency Management]
|
||||
E --> F[VM Execution]
|
||||
F --> G[Result Return]
|
||||
|
||||
subgraph "沙箱环境"
|
||||
H[@user://.promptx/toolbox]
|
||||
I[pnpm dependencies]
|
||||
J[isolated execution]
|
||||
end
|
||||
|
||||
D --> H
|
||||
E --> I
|
||||
F --> J
|
||||
```
|
||||
|
||||
### 工具接口标准
|
||||
```javascript
|
||||
// PromptX ToolInterface v2.0
|
||||
module.exports = {
|
||||
// 🆕 新接口：依赖管理
|
||||
getDependencies() {
|
||||
return ['lodash@^4.17.21', 'axios@^1.6.0'];
|
||||
},
|
||||
|
||||
// 核心接口：元信息
|
||||
getMetadata() {
|
||||
return {
|
||||
name: 'tool-name',
|
||||
description: '工具描述',
|
||||
version: '1.0.0',
|
||||
category: 'utility',
|
||||
author: '作者',
|
||||
tags: ['tag1', 'tag2']
|
||||
};
|
||||
},
|
||||
|
||||
// 核心接口：参数Schema
|
||||
getSchema() {
|
||||
return {
|
||||
type: 'object',
|
||||
properties: {
|
||||
input: { type: 'string', description: '输入参数' }
|
||||
},
|
||||
required: ['input']
|
||||
};
|
||||
},
|
||||
|
||||
// 可选接口：参数验证
|
||||
validate(params) {
|
||||
return { valid: true, errors: [] };
|
||||
},
|
||||
|
||||
// 核心接口：执行逻辑
|
||||
async execute(params) {
|
||||
// 工具核心逻辑
|
||||
return result;
|
||||
},
|
||||
|
||||
// 可选接口：初始化
|
||||
async init() {
|
||||
// 初始化逻辑
|
||||
},
|
||||
|
||||
// 可选接口：清理
|
||||
async cleanup() {
|
||||
// 清理逻辑
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## 🔧 技术栈知识
|
||||
|
||||
### Node.js生态精通
|
||||
```javascript
|
||||
// ES6+特性应用
|
||||
const { promisify } = require('util');
|
||||
const fs = require('fs').promises;
|
||||
|
||||
// 异步编程模式
|
||||
async function processData(data) {
|
||||
try {
|
||||
const result = await Promise.all(
|
||||
data.map(item => processItem(item))
|
||||
);
|
||||
return result;
|
||||
} catch (error) {
|
||||
throw new Error(`Processing failed: ${error.message}`);
|
||||
}
|
||||
}
|
||||
|
||||
// 错误处理最佳实践
|
||||
class ToolError extends Error {
|
||||
constructor(message, code, details) {
|
||||
super(message);
|
||||
this.name = 'ToolError';
|
||||
this.code = code;
|
||||
this.details = details;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 依赖管理精通
|
||||
```json
|
||||
// package.json最佳实践
|
||||
{
|
||||
"name": "toolbox-text-analyzer",
|
||||
"version": "1.0.0",
|
||||
"description": "Sandbox for tool: text-analyzer",
|
||||
"private": true,
|
||||
"dependencies": {
|
||||
"lodash": "^4.17.21",
|
||||
"axios": "^1.6.0",
|
||||
"validator": "^13.11.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**依赖选择原则**：
|
||||
- **成熟度**：选择下载量大、维护活跃的包
|
||||
- **轻量化**：避免过重的依赖，注意bundle size
|
||||
- **兼容性**：确保Node.js版本兼容
|
||||
- **安全性**：定期检查安全漏洞
|
||||
|
||||
### VM沙箱技术
|
||||
```javascript
|
||||
// 基础沙箱环境
|
||||
const basicSandbox = {
|
||||
require: require,
|
||||
module: { exports: {} },
|
||||
exports: {},
|
||||
console: console,
|
||||
Buffer: Buffer,
|
||||
process: {
|
||||
env: process.env,
|
||||
hrtime: process.hrtime
|
||||
},
|
||||
// JavaScript内置对象
|
||||
Object, Array, String, Number, Boolean,
|
||||
Date, JSON, Math, RegExp, Error, URL
|
||||
};
|
||||
|
||||
// 智能沙箱环境（支持依赖）
|
||||
const smartSandbox = {
|
||||
require: (moduleName) => {
|
||||
try {
|
||||
// 优先从沙箱目录查找
|
||||
return require(require.resolve(moduleName, {
|
||||
paths: [
|
||||
path.join(sandboxPath, 'node_modules'),
|
||||
sandboxPath,
|
||||
process.cwd() + '/node_modules'
|
||||
]
|
||||
}));
|
||||
} catch (error) {
|
||||
return require(moduleName);
|
||||
}
|
||||
},
|
||||
// ... 其他环境对象
|
||||
};
|
||||
```
|
||||
|
||||
## 📚 工具库生态
|
||||
|
||||
### 常用工具库分类
|
||||
|
||||
**🔧 工具函数库**
|
||||
- **lodash** `^4.17.21` - 全功能工具函数库
|
||||
- **ramda** `^0.29.0` - 函数式编程工具
|
||||
- **validator** `^13.11.0` - 数据验证工具
|
||||
|
||||
**🌐 网络请求库**
|
||||
- **axios** `^1.6.0` - HTTP客户端库
|
||||
- **node-fetch** `^3.3.0` - Fetch API实现
|
||||
- **got** `^13.0.0` - 轻量HTTP请求库
|
||||
|
||||
**📄 文件处理库**
|
||||
- **fs-extra** `^11.1.0` - 增强文件系统操作
|
||||
- **glob** `^10.3.0` - 文件模式匹配
|
||||
- **chokidar** `^3.5.0` - 文件监控
|
||||
|
||||
**📊 数据处理库**
|
||||
- **moment** `^2.29.0` - 日期时间处理
|
||||
- **mathjs** `^11.11.0` - 数学计算库
|
||||
- **csv-parser** `^3.0.0` - CSV文件解析
|
||||
|
||||
**📧 服务集成库**
|
||||
- **nodemailer** `^6.9.0` - 邮件发送
|
||||
- **node-cron** `^3.0.0` - 定时任务
|
||||
- **sharp** `^0.32.0` - 图像处理
|
||||
|
||||
### 库选择决策树
|
||||
```mermaid
|
||||
graph TD
|
||||
A[需要功能] --> B{功能类型}
|
||||
B -->|数据处理| C[lodash/ramda]
|
||||
B -->|网络请求| D[axios/node-fetch]
|
||||
B -->|文件操作| E[fs-extra/glob]
|
||||
B -->|数据验证| F[validator/joi]
|
||||
B -->|日期时间| G[moment/dayjs]
|
||||
B -->|数学计算| H[mathjs]
|
||||
B -->|邮件服务| I[nodemailer]
|
||||
B -->|图像处理| J[sharp/jimp]
|
||||
```
|
||||
|
||||
## 🛡️ 安全与最佳实践
|
||||
|
||||
### 安全编程原则
|
||||
```javascript
|
||||
// 输入验证
|
||||
function validateInput(input) {
|
||||
if (typeof input !== 'string') {
|
||||
throw new Error('输入必须是字符串');
|
||||
}
|
||||
|
||||
if (input.length > 10000) {
|
||||
throw new Error('输入内容过长');
|
||||
}
|
||||
|
||||
// 防止代码注入
|
||||
if (/[<>'"&]/.test(input)) {
|
||||
throw new Error('输入包含危险字符');
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
// 错误信息安全
|
||||
function safeErrorMessage(error) {
|
||||
// 不暴露敏感信息
|
||||
const safeMessage = error.message.replace(
|
||||
/\/Users\/[^\/]+/g, '~/***'
|
||||
);
|
||||
return safeMessage;
|
||||
}
|
||||
|
||||
// 资源限制
|
||||
function executeWithTimeout(fn, timeout = 30000) {
|
||||
return Promise.race([
|
||||
fn(),
|
||||
new Promise((_, reject) =>
|
||||
setTimeout(() => reject(new Error('执行超时')), timeout)
|
||||
)
|
||||
]);
|
||||
}
|
||||
```
|
||||
|
||||
### 性能优化模式
|
||||
```javascript
|
||||
// 缓存机制
|
||||
const cache = new Map();
|
||||
function memoize(fn) {
|
||||
return function(...args) {
|
||||
const key = JSON.stringify(args);
|
||||
if (cache.has(key)) {
|
||||
return cache.get(key);
|
||||
}
|
||||
const result = fn.apply(this, args);
|
||||
cache.set(key, result);
|
||||
return result;
|
||||
};
|
||||
}
|
||||
|
||||
// 批处理优化
|
||||
function batchProcess(items, batchSize = 10) {
|
||||
const batches = [];
|
||||
for (let i = 0; i < items.length; i += batchSize) {
|
||||
batches.push(items.slice(i, i + batchSize));
|
||||
}
|
||||
return batches;
|
||||
}
|
||||
|
||||
// 资源池管理
|
||||
class ResourcePool {
|
||||
constructor(createFn, maxSize = 10) {
|
||||
this.createFn = createFn;
|
||||
this.maxSize = maxSize;
|
||||
this.pool = [];
|
||||
this.active = new Set();
|
||||
}
|
||||
|
||||
async acquire() {
|
||||
if (this.pool.length > 0) {
|
||||
const resource = this.pool.pop();
|
||||
this.active.add(resource);
|
||||
return resource;
|
||||
}
|
||||
|
||||
if (this.active.size < this.maxSize) {
|
||||
const resource = await this.createFn();
|
||||
this.active.add(resource);
|
||||
return resource;
|
||||
}
|
||||
|
||||
throw new Error('资源池已满');
|
||||
}
|
||||
|
||||
release(resource) {
|
||||
this.active.delete(resource);
|
||||
this.pool.push(resource);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🔄 协议系统深度理解
|
||||
|
||||
### ResourceManager工作流程
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant RM as ResourceManager
|
||||
participant TP as ToolProtocol
|
||||
participant TS as ToolSandbox
|
||||
|
||||
User->>RM: loadResource('@tool://text-analyzer')
|
||||
RM->>RM: parseProtocol('tool', 'text-analyzer')
|
||||
RM->>TP: resolve('text-analyzer')
|
||||
TP->>TP: findResourceById('text-analyzer', 'tool')
|
||||
TP->>RM: return tool content
|
||||
RM->>User: return {success: true, content: '...'}
|
||||
User->>TS: new ToolSandbox('@tool://text-analyzer')
|
||||
TS->>RM: loadResource('@tool://text-analyzer')
|
||||
TS->>TS: analyze() → prepareDependencies() → execute()
|
||||
```
|
||||
|
||||
### 协议引用系统
|
||||
```javascript
|
||||
// 协议解析示例
|
||||
const parsed = protocolParser.parse('@tool://text-analyzer');
|
||||
// 结果: { protocol: 'tool', path: 'text-analyzer', queryParams: {} }
|
||||
|
||||
// 用户协议解析
|
||||
const userPath = protocolParser.parse('@user://.promptx/toolbox/text-analyzer');
|
||||
// 结果: { protocol: 'user', path: '.promptx/toolbox/text-analyzer' }
|
||||
|
||||
// 资源查找逻辑
|
||||
const resourceData = registryData.findResourceById('text-analyzer', 'tool');
|
||||
// 查找ID为'text-analyzer'且protocol为'tool'的资源
|
||||
```
|
||||
|
||||
## 📈 监控与调试
|
||||
|
||||
### 调试技巧
|
||||
```javascript
|
||||
// 沙箱状态监控
|
||||
function debugSandbox(sandbox) {
|
||||
console.log('沙箱状态:', {
|
||||
toolId: sandbox.toolId,
|
||||
isAnalyzed: sandbox.isAnalyzed,
|
||||
isPrepared: sandbox.isPrepared,
|
||||
dependencies: sandbox.dependencies,
|
||||
sandboxPath: sandbox.sandboxPath
|
||||
});
|
||||
}
|
||||
|
||||
// 性能监控
|
||||
function profileExecution(fn, name) {
|
||||
return async (...args) => {
|
||||
const start = process.hrtime.bigint();
|
||||
const result = await fn(...args);
|
||||
const end = process.hrtime.bigint();
|
||||
const duration = Number(end - start) / 1000000; // 转换为毫秒
|
||||
console.log(`${name} 执行耗时: ${duration.toFixed(2)}ms`);
|
||||
return result;
|
||||
};
|
||||
}
|
||||
|
||||
// 错误追踪
|
||||
function trackError(error, context) {
|
||||
console.error('错误详情:', {
|
||||
message: error.message,
|
||||
stack: error.stack,
|
||||
context: context,
|
||||
timestamp: new Date().toISOString()
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
### 日志系统
|
||||
```javascript
|
||||
const logger = {
|
||||
debug: (message, data) => {
|
||||
if (process.env.DEBUG) {
|
||||
console.log(`[DEBUG] ${message}`, data);
|
||||
}
|
||||
},
|
||||
|
||||
info: (message, data) => {
|
||||
console.log(`[INFO] ${message}`, data);
|
||||
},
|
||||
|
||||
warn: (message, data) => {
|
||||
console.warn(`[WARN] ${message}`, data);
|
||||
},
|
||||
|
||||
error: (message, error) => {
|
||||
console.error(`[ERROR] ${message}`, {
|
||||
message: error.message,
|
||||
stack: error.stack
|
||||
});
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
</knowledge>
|
||||
Reference in New Issue
Block a user