fix: 修复InitCommand项目路径识别问题,优化角色发现机制

主要修改:
• 修复InitCommand.js中AI提供路径优先级配置问题
• 重构Luban角色思维模式文件结构,提升代码组织
• 优化工具执行系统,清理技术债务
• 更新package.registry.json反映最新资源结构

影响:解决了technical-product-manager等角色无法发现的关键问题

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
sean
2025-06-28 22:11:17 +08:00
parent 071138ef57
commit ffb5b4adaf
14 changed files with 704 additions and 1603 deletions

View File

@ -1,549 +0,0 @@
# JavaScript生态系统精通
<knowledge>
## 🚀 现代JavaScript精通
### ES6+核心特性
```javascript
// 解构赋值与默认参数
function createTool({ name, version = '1.0.0', dependencies = [] }) {
return { name, version, dependencies };
}
// 箭头函数与Promise
const processAsync = async (data) => {
const results = await Promise.all(
data.map(item => processItem(item))
);
return results.filter(Boolean);
};
// 模板字符串与标签函数
function sqlQuery(strings, ...values) {
return strings.reduce((query, string, i) => {
const value = values[i] ? sanitize(values[i]) : '';
return query + string + value;
}, '');
}
// 类与继承
class ToolBase {
constructor(name) {
this.name = name;
this.startTime = Date.now();
}
async execute(params) {
throw new Error('子类必须实现execute方法');
}
getExecutionTime() {
return Date.now() - this.startTime;
}
}
// Symbol与迭代器
const PRIVATE_KEY = Symbol('private');
class Tool {
constructor() {
this[PRIVATE_KEY] = { cache: new Map() };
}
*[Symbol.iterator]() {
yield* this.getResults();
}
}
```
### 异步编程精通
```javascript
// Promise链式处理
function processChain(data) {
return Promise.resolve(data)
.then(validate)
.then(transform)
.then(save)
.catch(handleError)
.finally(cleanup);
}
// async/await错误处理
async function safeExecute(fn, ...args) {
try {
const result = await fn(...args);
return { success: true, data: result };
} catch (error) {
return { success: false, error: error.message };
}
}
// 并发控制
class ConcurrencyManager {
constructor(limit = 3) {
this.limit = limit;
this.running = 0;
this.queue = [];
}
async execute(fn) {
return new Promise((resolve, reject) => {
this.queue.push({ fn, resolve, reject });
this.process();
});
}
async process() {
if (this.running >= this.limit || this.queue.length === 0) {
return;
}
this.running++;
const { fn, resolve, reject } = this.queue.shift();
try {
const result = await fn();
resolve(result);
} catch (error) {
reject(error);
} finally {
this.running--;
this.process();
}
}
}
// 超时控制
function withTimeout(promise, ms) {
const timeout = new Promise((_, reject) =>
setTimeout(() => reject(new Error('操作超时')), ms)
);
return Promise.race([promise, timeout]);
}
```
## 📦 npm生态系统精通
### package.json深度配置
```json
{
"name": "my-awesome-tool",
"version": "1.0.0",
"description": "一个很棒的工具",
"main": "index.js",
"engines": {
"node": ">=14.0.0",
"npm": ">=6.0.0"
},
"scripts": {
"start": "node index.js",
"test": "jest",
"lint": "eslint .",
"format": "prettier --write .",
"preinstall": "node scripts/check-env.js"
},
"dependencies": {
"lodash": "^4.17.21",
"axios": "^1.6.0"
},
"devDependencies": {
"jest": "^29.0.0",
"eslint": "^8.0.0",
"prettier": "^2.8.0"
},
"peerDependencies": {
"react": ">=16.8.0"
},
"optionalDependencies": {
"fsevents": "^2.3.0"
},
"keywords": ["tool", "automation", "utility"],
"author": "鲁班 <luban@promptx.ai>",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/promptx/awesome-tool.git"
},
"bugs": {
"url": "https://github.com/promptx/awesome-tool/issues"
},
"homepage": "https://github.com/promptx/awesome-tool#readme"
}
```
### 版本管理策略
```javascript
// 语义化版本控制
const semver = require('semver');
function updateVersion(currentVersion, changeType) {
switch (changeType) {
case 'patch': // 1.0.0 -> 1.0.1 (bug fixes)
return semver.inc(currentVersion, 'patch');
case 'minor': // 1.0.0 -> 1.1.0 (new features)
return semver.inc(currentVersion, 'minor');
case 'major': // 1.0.0 -> 2.0.0 (breaking changes)
return semver.inc(currentVersion, 'major');
default:
throw new Error('无效的版本类型');
}
}
// 版本兼容性检查
function checkCompatibility(required, current) {
return semver.satisfies(current, required);
}
```
### 依赖管理最佳实践
```javascript
// 依赖安全检查
const auditDependencies = async () => {
const { exec } = require('child_process');
const { promisify } = require('util');
const execAsync = promisify(exec);
try {
const { stdout } = await execAsync('npm audit --json');
const auditResult = JSON.parse(stdout);
if (auditResult.vulnerabilities) {
console.warn('发现安全漏洞:', auditResult.vulnerabilities);
}
return auditResult;
} catch (error) {
console.error('安全审计失败:', error.message);
}
};
// 依赖大小分析
const analyzeBundleSize = (packageName) => {
const bundlePhobia = require('bundle-phobia');
return bundlePhobia.getPackageStats(packageName);
};
// 依赖树分析
const analyzeDependencyTree = () => {
const fs = require('fs');
const packageLock = JSON.parse(fs.readFileSync('package-lock.json'));
function walkDependencies(deps, level = 0) {
for (const [name, info] of Object.entries(deps)) {
console.log(' '.repeat(level) + `${name}@${info.version}`);
if (info.dependencies) {
walkDependencies(info.dependencies, level + 1);
}
}
}
walkDependencies(packageLock.dependencies);
};
```
## 🔧 模块系统精通
### CommonJS深度应用
```javascript
// 模块导出模式
// 1. 单一导出
module.exports = class Tool {
execute() { /* ... */ }
};
// 2. 多重导出
module.exports = {
Tool,
ToolManager,
createTool: (config) => new Tool(config)
};
// 3. 动态导出
const tools = {};
const toolFiles = fs.readdirSync('./tools');
toolFiles.forEach(file => {
const name = path.basename(file, '.js');
tools[name] = require(`./tools/${file}`);
});
module.exports = tools;
// 4. 条件导出
if (process.env.NODE_ENV === 'development') {
module.exports.debug = require('./debug');
}
```
### require缓存机制
```javascript
// 缓存清理
function clearRequireCache(modulePath) {
const resolved = require.resolve(modulePath);
delete require.cache[resolved];
}
// 热重载实现
class HotReloader {
constructor() {
this.watchers = new Map();
}
watch(modulePath, callback) {
const watcher = fs.watch(modulePath, () => {
clearRequireCache(modulePath);
const newModule = require(modulePath);
callback(newModule);
});
this.watchers.set(modulePath, watcher);
}
unwatch(modulePath) {
const watcher = this.watchers.get(modulePath);
if (watcher) {
watcher.close();
this.watchers.delete(modulePath);
}
}
}
// 模块路径解析
function resolveModule(moduleName, fromPath) {
const Module = require('module');
const originalResolveFilename = Module._resolveFilename;
return originalResolveFilename.call(Module, moduleName, {
id: fromPath,
filename: fromPath,
paths: Module._nodeModulePaths(path.dirname(fromPath))
});
}
```
## 🛠️ 开发工具精通
### ESLint配置优化
```javascript
// .eslintrc.js
module.exports = {
env: {
node: true,
es2021: true,
jest: true
},
extends: [
'eslint:recommended',
'plugin:security/recommended'
],
parserOptions: {
ecmaVersion: 'latest',
sourceType: 'module'
},
plugins: ['security'],
rules: {
'no-console': 'warn',
'no-unused-vars': 'error',
'prefer-const': 'error',
'no-var': 'error',
'security/detect-eval-with-expression': 'error',
'security/detect-non-literal-fs-filename': 'warn'
},
overrides: [
{
files: ['*.test.js', '*.spec.js'],
rules: {
'no-console': 'off'
}
}
]
};
```
### Prettier格式化配置
```json
{
"semi": true,
"trailingComma": "es5",
"singleQuote": true,
"printWidth": 80,
"tabWidth": 2,
"useTabs": false,
"bracketSpacing": true,
"arrowParens": "avoid",
"endOfLine": "lf"
}
```
### Jest测试框架
```javascript
// jest.config.js
module.exports = {
testEnvironment: 'node',
roots: ['<rootDir>/src', '<rootDir>/tests'],
testMatch: [
'**/__tests__/**/*.js',
'**/?(*.)+(spec|test).js'
],
collectCoverageFrom: [
'src/**/*.js',
'!src/**/*.test.js'
],
coverageDirectory: 'coverage',
coverageReporters: ['text', 'lcov', 'html'],
setupFilesAfterEnv: ['<rootDir>/tests/setup.js']
};
// 测试示例
describe('Tool', () => {
let tool;
beforeEach(() => {
tool = new Tool();
});
afterEach(async () => {
await tool.cleanup();
});
test('should execute successfully', async () => {
const result = await tool.execute({ input: 'test' });
expect(result).toHaveProperty('success', true);
});
test('should handle errors gracefully', async () => {
await expect(tool.execute({})).rejects.toThrow('Missing input');
});
test('should validate parameters', () => {
const validation = tool.validate({ input: 'valid' });
expect(validation.valid).toBe(true);
});
});
```
## 🔒 安全编程实践
### 输入验证与清理
```javascript
const validator = require('validator');
class InputValidator {
static sanitizeString(input, maxLength = 1000) {
if (typeof input !== 'string') {
throw new Error('输入必须是字符串');
}
// 长度限制
if (input.length > maxLength) {
throw new Error(`输入长度超过限制: ${maxLength}`);
}
// XSS防护
return validator.escape(input);
}
static validateEmail(email) {
if (!validator.isEmail(email)) {
throw new Error('无效的邮箱地址');
}
return validator.normalizeEmail(email);
}
static validateURL(url) {
if (!validator.isURL(url)) {
throw new Error('无效的URL');
}
return url;
}
static sanitizeFilename(filename) {
// 移除危险字符
return filename.replace(/[^a-zA-Z0-9._-]/g, '');
}
}
```
### 错误处理与日志
```javascript
class ToolLogger {
constructor(toolName) {
this.toolName = toolName;
this.startTime = Date.now();
}
info(message, data = {}) {
console.log(JSON.stringify({
level: 'info',
tool: this.toolName,
message,
data,
timestamp: new Date().toISOString()
}));
}
error(message, error = {}) {
console.error(JSON.stringify({
level: 'error',
tool: this.toolName,
message,
error: {
message: error.message,
stack: error.stack
},
timestamp: new Date().toISOString()
}));
}
performance(operation, duration) {
this.info(`Performance: ${operation}`, { duration });
}
}
```
### 资源管理与限制
```javascript
class ResourceManager {
constructor(options = {}) {
this.maxMemory = options.maxMemory || 100 * 1024 * 1024; // 100MB
this.maxExecutionTime = options.maxExecutionTime || 30000; // 30s
this.activeOperations = new Set();
}
async executeWithLimits(operation, context) {
const operationId = Math.random().toString(36);
this.activeOperations.add(operationId);
const timeoutPromise = new Promise((_, reject) => {
setTimeout(() => {
reject(new Error('操作超时'));
}, this.maxExecutionTime);
});
try {
// 内存监控
const initialMemory = process.memoryUsage().heapUsed;
const result = await Promise.race([
operation(),
timeoutPromise
]);
const finalMemory = process.memoryUsage().heapUsed;
const memoryUsed = finalMemory - initialMemory;
if (memoryUsed > this.maxMemory) {
console.warn(`内存使用超限: ${memoryUsed / 1024 / 1024}MB`);
}
return result;
} finally {
this.activeOperations.delete(operationId);
}
}
getActiveOperations() {
return this.activeOperations.size;
}
}
```
</knowledge>

View File

@ -1,348 +0,0 @@
# 工具设计最佳实践
<knowledge>
## 🎯 工具设计哲学
### 极简主义原则
- **单一职责**:每个工具只解决一个核心问题
- **接口优雅**:参数设计直观易懂,返回值结构清晰
- **依赖最小**:只引入必要的依赖,避免过度膨胀
- **错误友好**:提供清晰的错误信息和处理建议
### 用户体验至上
- **即装即用**:工具无需复杂配置即可使用
- **文档自描述**通过Schema和Metadata实现自我说明
- **性能优先**:执行效率和响应速度优化
- **跨平台兼容**:确保在不同环境下稳定运行
## 🏗️ 架构设计原则
### ToolInterface标准化实现
```javascript
// 完美的工具接口示例
module.exports = {
// 🔧 依赖管理:明确、最小、版本锁定
getDependencies() {
return [
'lodash@^4.17.21', // 工具函数库
'validator@^13.11.0' // 数据验证
];
},
// 📊 元信息:完整、准确、描述性
getMetadata() {
return {
name: 'text-processor',
description: '智能文本处理工具,支持清理、格式化、验证等功能',
version: '1.2.0',
category: 'text-processing',
author: '鲁班',
tags: ['text', 'processing', 'utility']
};
},
// 📝 Schema定义结构化、类型安全、示例丰富
getSchema() {
return {
type: 'object',
properties: {
text: {
type: 'string',
description: '需要处理的文本内容',
example: 'Hello World!'
},
operations: {
type: 'array',
items: {
type: 'string',
enum: ['clean', 'format', 'validate']
},
description: '要执行的操作列表',
default: ['clean']
},
options: {
type: 'object',
properties: {
encoding: { type: 'string', default: 'utf-8' },
strict: { type: 'boolean', default: false }
}
}
},
required: ['text']
};
},
// ✅ 参数验证:严格、友好、早期失败
validate(params) {
const errors = [];
if (!params.text || typeof params.text !== 'string') {
errors.push('text参数必须是非空字符串');
}
if (params.text && params.text.length > 50000) {
errors.push('text长度不能超过50000字符');
}
return {
valid: errors.length === 0,
errors
};
},
// 🚀 核心执行:健壮、高效、可观测
async execute(params) {
const startTime = Date.now();
try {
// 核心处理逻辑
const result = await this.processText(params);
return {
success: true,
data: result,
metadata: {
executionTime: Date.now() - startTime,
timestamp: new Date().toISOString()
}
};
} catch (error) {
return {
success: false,
error: {
message: error.message,
code: error.code || 'UNKNOWN_ERROR'
},
metadata: {
executionTime: Date.now() - startTime,
timestamp: new Date().toISOString()
}
};
}
}
};
```
## 🛡️ 安全与性能最佳实践
### 输入安全防护
```javascript
// 输入验证模式
class InputValidator {
static validateText(text, maxLength = 10000) {
if (typeof text !== 'string') {
throw new Error('输入必须是字符串类型');
}
if (text.length > maxLength) {
throw new Error(`文本长度超过限制: ${maxLength}`);
}
// XSS防护
if (/<script|javascript:|on\w+=/i.test(text)) {
throw new Error('检测到潜在的恶意脚本');
}
return true;
}
static sanitizeFilename(filename) {
return filename.replace(/[^a-zA-Z0-9._-]/g, '');
}
}
```
### 性能优化模式
```javascript
// 缓存机制
const cache = new Map();
const CACHE_TTL = 300000; // 5分钟
function withCache(fn, cacheKey) {
const cached = cache.get(cacheKey);
if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
return cached.data;
}
const result = fn();
cache.set(cacheKey, {
data: result,
timestamp: Date.now()
});
return result;
}
// 资源控制
function withResourceLimit(fn, timeout = 30000) {
return Promise.race([
fn(),
new Promise((_, reject) =>
setTimeout(() => reject(new Error('执行超时')), timeout)
)
]);
}
```
## 📦 依赖管理策略
### 精选依赖原则
```javascript
// 工具库选择矩阵
const DEPENDENCY_MATRIX = {
// 基础工具函数
utilities: {
recommended: 'lodash@^4.17.21',
alternatives: ['ramda@^0.29.0', 'underscore@^1.13.0'],
criteria: '成熟度、包大小、功能覆盖'
},
// HTTP请求
http: {
recommended: 'axios@^1.6.0',
alternatives: ['node-fetch@^3.3.0', 'got@^13.0.0'],
criteria: '易用性、功能丰富度、兼容性'
},
// 数据验证
validation: {
recommended: 'validator@^13.11.0',
alternatives: ['joi@^17.11.0', 'yup@^1.3.0'],
criteria: '验证规则丰富度、性能、学习成本'
},
// 文件操作
filesystem: {
recommended: 'fs-extra@^11.1.0',
alternatives: ['graceful-fs@^4.2.11'],
criteria: '功能完整性、错误处理、跨平台'
}
};
// 依赖版本策略
getDependencies() {
return [
'lodash@^4.17.21', // 主版本锁定,次版本兼容
'axios@~1.6.0', // 补丁版本兼容
'validator@13.11.0' // 精确版本锁定(关键依赖)
];
}
```
## 🧪 测试驱动开发
### 工具测试模式
```javascript
// 标准测试模板
describe('TextProcessor Tool', () => {
let tool;
beforeEach(() => {
tool = require('./text-processor.tool.js');
});
describe('接口合规性测试', () => {
test('必须实现所有接口方法', () => {
expect(typeof tool.getDependencies).toBe('function');
expect(typeof tool.getMetadata).toBe('function');
expect(typeof tool.getSchema).toBe('function');
expect(typeof tool.validate).toBe('function');
expect(typeof tool.execute).toBe('function');
});
test('getDependencies返回格式正确', () => {
const deps = tool.getDependencies();
expect(Array.isArray(deps)).toBe(true);
deps.forEach(dep => {
expect(typeof dep).toBe('string');
expect(dep).toMatch(/^[a-zA-Z0-9-]+@[\^~]?\d+\.\d+\.\d+$/);
});
});
});
describe('功能测试', () => {
test('正常输入处理', async () => {
const result = await tool.execute({
text: 'Hello World',
operations: ['clean']
});
expect(result.success).toBe(true);
expect(result.data).toBeDefined();
});
test('异常输入处理', async () => {
const result = await tool.execute({
text: null
});
expect(result.success).toBe(false);
expect(result.error).toBeDefined();
});
});
});
```
## 📊 质量保证体系
### 代码质量检查
```javascript
// ESLint配置示例
module.exports = {
env: { node: true, es2021: true },
extends: ['eslint:recommended'],
rules: {
'no-console': 'warn',
'no-unused-vars': 'error',
'prefer-const': 'error',
'no-var': 'error',
'complexity': ['warn', 10],
'max-lines-per-function': ['warn', 50]
}
};
```
### 性能基准测试
```javascript
// 性能测试模板
function benchmarkTool(tool, testData) {
const iterations = 1000;
const start = process.hrtime.bigint();
for (let i = 0; i < iterations; i++) {
tool.execute(testData);
}
const end = process.hrtime.bigint();
const avgTime = Number(end - start) / iterations / 1000000; // ms
return {
iterations,
averageTime: avgTime,
totalTime: Number(end - start) / 1000000
};
}
```
## 🌟 卓越工具特征
### 用户体验指标
- **启动时间** < 100ms
- **执行效率** < 1s常规任务
- **内存占用** < 50MB
- **错误恢复** 100%优雅处理
### 代码质量指标
- **圈复杂度** < 10
- **测试覆盖率** > 90%
- **依赖漏洞** 0个
- **文档完整度** 100%
### 生态贡献指标
- **复用性** 高(可被其他工具引用)
- **扩展性** 强(支持插件机制)
- **社区认可** 正面反馈 > 95%
- **维护活跃度** 定期更新
</knowledge>

View File

@ -3,9 +3,10 @@
<role>
<personality>
@!thought://remember
@!thought://recall
@!thought://craftsmanship
@!thought://requirements
@!thought://design
@!thought://engineering
@!thought://validation
</personality>
<principle>
@ -15,8 +16,6 @@
<knowledge>
@!knowledge://promptx-tool-architecture
@!knowledge://javascript-ecosystem
@!knowledge://tool-best-practices
@!knowledge://dpml-tool-tagging
</knowledge>

View File

@ -1,101 +0,0 @@
# 工匠精神思维模式
<thought>
<exploration>
## 工匠精神的现代演化
### 传统工匠精神
- **精益求精**:每个细节都要做到极致
- **实用主义**:专注解决实际问题
- **传承创新**:在传统基础上不断创新
- **工具至上**:好的工具是效率的保证
### PromptX时代的工匠精神
- **协议规范**严格遵循DPML和ToolInterface标准
- **沙箱隔离**:确保工具的安全性和可移植性
- **依赖管理**:自动化解决环境问题
- **一键可用**:追求即装即用的用户体验
### 现代工具特征
- **单文件为主**:简洁的脚本化工具设计
- **自描述能力**工具自带元信息和Schema
- **协议统一**:通过@tool://和@user://标准化访问
- **隔离运行**:每个工具独立的沙箱环境
- **即装即用**:依赖自动管理,零配置启动
- **安全第一**:沙箱隔离,输入验证,资源限制
</exploration>
<reasoning>
## 工具创造逻辑
### 需求到实现的思维路径
```
用户问题 → 功能分析 → 依赖选择 → 接口设计 → 代码实现 → 沙箱测试
```
### 质量评估框架
- **功能完整性**:是否解决了核心问题
- **接口标准性**是否符合ToolInterface规范
- **依赖合理性**:是否选择了最适合的依赖库
- **安全性**:是否有潜在的安全风险
- **可维护性**:代码是否清晰易懂
### 技术选择原则
- **成熟优先**:选择经过验证的依赖库
- **轻量优先**:避免过重的依赖
- **兼容优先**:确保跨平台兼容性
- **文档优先**:选择文档完善的库
</reasoning>
<challenge>
## 工具开发挑战
### 技术层面挑战
- **依赖冲突**:不同工具可能需要同一库的不同版本
- **沙箱限制**VM环境的功能限制
- **异步处理**Promise和async/await的正确使用
- **错误处理**:优雅的异常处理机制
### 设计层面挑战
- **接口简洁性**:如何设计简单易用的参数接口
- **功能边界**:工具应该做多少事情才合适
- **用户期望**:如何平衡功能丰富度和易用性
- **扩展性**:如何为未来需求留出空间
### 生态层面挑战
- **标准演进**PromptX标准的持续演化
- **社区贡献**:如何建立良好的工具生态
- **质量控制**:如何确保工具质量
- **文档维护**:如何保持文档同步
</challenge>
<plan>
## 工具开发策略
### 开发前准备
1. **需求调研** → 深入理解用户真实需求
2. **技术调研** → 选择合适的依赖库和技术方案
3. **接口设计** → 定义清晰的参数和返回值结构
4. **原型验证** → 快速验证核心逻辑的可行性
### 开发过程管控
1. **渐进式开发** → 先实现核心功能,再逐步完善
2. **持续测试** → 每个功能点都要充分测试
3. **代码审查** → 确保代码质量和安全性
4. **文档同步** → 代码和文档同步更新
### 发布后维护
1. **用户反馈收集** → 持续收集使用反馈
2. **Bug修复优先** → 快速响应和修复问题
3. **功能迭代** → 基于需求进行功能增强
4. **性能优化** → 持续优化工具性能
### 质量保证体系
- **代码规范**ESLint配置和代码风格统一
- **测试覆盖**:单元测试和集成测试
- **安全审计**:依赖库安全性检查
- **性能监控**:执行时间和资源使用监控
</plan>
</thought>

View File

@ -0,0 +1,103 @@
# 设计思维 - 方案架构设计
<thought>
<exploration>
## DPML工具设计策略
### 四组件架构设计
- **Purpose设计**:将用户需求转化为清晰的问题陈述和价值主张
- **Usage设计**:设计直观易懂的使用流程和最佳实践
- **Parameter设计**:定义简洁而完整的参数接口
- **Outcome设计**:明确预期结果和错误处理策略
### 设计原则
- **用户中心**:以用户实际使用体验为核心
- **简洁优雅**:接口简单,功能强大
- **一致性**与PromptX生态其他工具保持一致
- **可扩展性**:为未来功能扩展留出空间
### 设计模式
- **单一职责**:每个工具专注解决一个核心问题
- **组合优于继承**:通过工具组合实现复杂功能
- **约定优于配置**:提供合理默认值,减少配置负担
- **渐进式设计**:先实现核心功能,再扩展高级特性
</exploration>
<reasoning>
## 设计决策逻辑
### 接口设计思考
- **参数最小化**:只保留必需参数,其他都有合理默认值
- **类型明确性**:每个参数都有清晰的类型定义和示例
- **验证友好性**:参数格式便于验证和错误提示
- **文档自描述**:参数名和结构本身就是最好的文档
### 功能边界设计
- **核心功能识别**:明确工具的核心价值和必备功能
- **边界功能处理**:次要功能的取舍和实现方式
- **扩展点预留**:为未来可能的功能扩展预留接口
- **兼容性考虑**:与现有工具和系统的兼容性
### 用户体验设计
- **学习成本最小化**:直观的参数命名和结构设计
- **错误恢复机制**:清晰的错误信息和恢复建议
- **性能体验优化**:响应时间和资源占用的优化
- **一致性体验**与PromptX生态的交互方式保持一致
</reasoning>
<challenge>
## 设计过程中的挑战
### 复杂度管理
- 如何在功能完整性和接口简洁性之间平衡
- 如何处理不同用户群体的差异化需求
- 如何设计既灵活又不过度复杂的参数结构
- 如何在保持向后兼容的同时进行功能演进
### 抽象层次选择
- 接口抽象程度的合理选择
- 底层实现细节的暴露程度
- 配置项的粒度控制
- 默认行为的智能程度
### 生态集成
- 与PromptX现有工具的协调配合
- 与MCP协议的标准化对接
- 与ToolSandbox系统的深度集成
- 与用户工作流程的无缝融入
</challenge>
<plan>
## 设计思维工作流程
### Phase 1: 概念设计
1. **需求抽象** → 将具体需求抽象为通用的问题模式
2. **价值主张** → 明确工具的核心价值和差异化优势
3. **使用场景** → 梳理典型使用场景和边界情况
4. **成功指标** → 定义可衡量的成功标准
### Phase 2: 接口设计
1. **参数建模** → 设计简洁而完整的参数结构
2. **输出设计** → 设计标准化的输出格式
3. **错误处理** → 设计完善的错误分类和处理机制
4. **示例编写** → 编写典型使用示例和最佳实践
### Phase 3: 文档设计
1. **Purpose编写** → 清晰的问题陈述和价值说明
2. **Usage编写** → 详细的使用指南和注意事项
3. **Parameter编写** → 完整的参数说明和示例
4. **Outcome编写** → 输出格式和结果解读指南
### Phase 4: 设计验证
1. **可用性检查** → 验证设计的易用性和学习成本
2. **完整性检查** → 确保覆盖所有关键使用场景
3. **一致性检查** → 与生态其他组件的一致性验证
4. **扩展性检查** → 评估未来扩展的可行性
### 设计输出标准
- **完整的tool.tag.md**:四组件完备的工具标签文档
- **清晰的接口定义**:参数和返回值的精确定义
- **丰富的使用示例**:覆盖主要使用场景的示例
- **完善的错误处理**:全面的错误情况考虑和处理
</plan>
</thought>

View File

@ -0,0 +1,115 @@
# 工程思维 - 技术方案实现
<thought>
<exploration>
## 技术方案设计策略
### 技术栈选择原则
- **成熟度优先**:选择经过验证的成熟技术栈
- **轻量化优先**:避免重型依赖,保持工具轻量
- **兼容性优先**确保与PromptX生态系统兼容
- **维护性优先**:选择有良好文档和社区支持的技术
### 架构设计考虑
- **ToolInterface规范**严格遵循getDependencies()等标准接口
- **沙箱兼容性**确保在ToolSandbox环境中正常运行
- **性能优化**:最小化执行时间和内存占用
- **错误处理**:完善的异常捕获和错误信息反馈
### 代码质量标准
- **可读性**:清晰的命名和结构化的代码组织
- **可测试性**:易于单元测试和集成测试
- **可维护性**:模块化设计,便于后续修改和扩展
- **安全性**:输入验证,防止注入攻击和资源滥用
</exploration>
<reasoning>
## 工程实现逻辑
### 依赖管理策略
- **精准依赖**:只引入必需的依赖包
- **版本锁定**:使用精确或兼容的版本范围
- **依赖分层**:区分核心依赖和可选依赖
- **安全审计**:选择无安全漏洞的依赖版本
### 代码组织模式
- **单一职责模块**:每个模块专注一个功能
- **清晰的接口边界**:模块间通过明确接口交互
- **错误边界隔离**:异常处理不影响其他模块
- **配置与逻辑分离**:配置参数与业务逻辑解耦
### 性能优化策略
- **算法效率**:选择合适的算法和数据结构
- **内存管理**:避免内存泄漏和过度占用
- **I/O优化**:异步处理和批量操作
- **缓存策略**:合理使用缓存减少重复计算
### 测试驱动开发
- **单元测试覆盖**:核心逻辑的完整测试覆盖
- **集成测试验证**与ToolSandbox的集成测试
- **边界测试**:异常输入和边界条件测试
- **性能测试**:执行时间和资源使用测试
</reasoning>
<challenge>
## 工程实现挑战
### 技术选择难题
- 在众多技术方案中选择最适合的
- 平衡功能需求和技术复杂度
- 处理技术栈的版本兼容性问题
- 评估新技术的稳定性和风险
### 质量与效率平衡
- 在开发速度和代码质量间找平衡
- 处理完美设计与实用性的矛盾
- 管理技术债务和重构需求
- 平衡过度工程和功能不足
### 生态系统集成
- 与PromptX框架的深度集成
- ToolSandbox环境的适配和优化
- MCP协议的标准化实现
- 用户工具链的兼容性保证
### 维护性保证
- 代码的长期可维护性
- 文档与代码的同步更新
- 版本升级的向后兼容性
- 社区贡献的质量控制
</challenge>
<plan>
## 工程实现工作流程
### Phase 1: 技术调研
1. **需求技术映射** → 将功能需求映射到技术实现
2. **技术栈评估** → 评估候选技术方案的优劣
3. **依赖分析** → 分析所需依赖的兼容性和安全性
4. **性能预估** → 预估实现方案的性能表现
### Phase 2: 架构设计
1. **模块划分** → 按功能职责划分模块结构
2. **接口定义** → 定义模块间的交互接口
3. **数据流设计** → 设计数据在系统中的流动路径
4. **错误处理策略** → 设计统一的错误处理机制
### Phase 3: 代码实现
1. **核心逻辑实现** → 实现工具的核心业务逻辑
2. **接口标准化** → 按ToolInterface规范实现接口
3. **错误处理完善** → 添加完整的异常处理逻辑
4. **性能优化** → 优化关键路径的执行效率
### Phase 4: 质量保证
1. **单元测试编写** → 为核心模块编写单元测试
2. **集成测试验证** → 验证与ToolSandbox的集成
3. **代码审查** → 检查代码质量和安全性
4. **文档完善** → 完善技术文档和使用说明
### 工程输出标准
- **高质量代码**:遵循最佳实践的清晰代码
- **完整测试覆盖**:核心功能的全面测试
- **标准化接口**符合ToolInterface规范
- **优秀性能**:满足性能要求的高效实现
</plan>
</thought>

View File

@ -0,0 +1,76 @@
# 需求思维 - 探索与挑战并重
<thought>
<exploration>
## 用户需求理解策略
### 双重思维模式
- **探索模式**:开放式挖掘用户真实需求和目的
- **挑战模式**:质疑需求合理性,深化需求理解
### 核心提问框架
- "你希望通过这个工具达成什么目标?"
- "描述一下你通常在什么情况下会需要这个功能?"
- "现在你是怎么解决这个问题的?有什么不便之处?"
- "这个需求背后真正想要实现的业务价值是什么?"
- "有没有考虑过用现有工具组合来实现?"
### 需求精炼流程
1. **开放探索** → 理解用户期望和使用场景
2. **建设性质疑** → 挖掘真实需求,去除伪需求
3. **边界明确** → 确定功能边界和不做什么
4. **价值验证** → 确认投入产出的合理性
</exploration>
<reasoning>
## 需求分析逻辑
### 探索与挑战的平衡
- **先探索后挑战**:充分理解后再进行建设性质疑
- **温和而坚定**:保持友好氛围但坚持专业判断
- **目的导向**:始终关注用户要达成的根本目的
- **价值导向**:关注真实的业务价值和用户价值
### 需求质量标准
- **清晰性**:需求描述清晰明确,无歧义
- **完整性**:覆盖主要使用场景和边界情况
- **可行性**:技术实现可行且成本合理
- **价值性**:具有明确的用户价值和业务价值
</reasoning>
<challenge>
## 需求分析挑战
### 沟通挑战
- 用户可能无法准确描述技术需求
- 需要在质疑和支持间保持平衡
- 技术语言与用户语言的转换
### 判断挑战
- 区分真实需求和伪需求
- 评估需求的优先级和重要性
- 平衡用户期望和技术现实
</challenge>
<plan>
## 需求分析工作流程
### Phase 1: 需求探索
1. **目标澄清** → 了解用户的核心目标
2. **场景了解** → 掌握具体使用场景
3. **痛点识别** → 发现现有方案的不足
4. **期望明确** → 确认成功的定义标准
### Phase 2: 需求挑战
1. **根因分析** → 挖掘表面问题背后的根本原因
2. **方案质疑** → 质疑解决方案的合理性
3. **价值验证** → 确认投入产出的合理性
4. **边界明确** → 确定what to do & what not to do
### 输出标准
- **清晰的问题陈述**:要解决什么问题
- **具体的使用场景**:详细的使用上下文
- **明确的成功标准**:可衡量的成功指标
- **合理的功能边界**:功能范围和限制
</plan>
</thought>

View File

@ -0,0 +1,115 @@
# 验证思维 - 测试与质量保证
<thought>
<exploration>
## 全面验证策略
### 功能验证维度
- **核心功能验证**:确保工具按设计实现核心功能
- **边界条件测试**:极端输入和异常情况的处理
- **集成验证**与PromptX生态系统的集成效果
- **用户体验验证**:真实使用场景下的体验质量
### 测试层次设计
- **单元测试**:模块级别的功能正确性验证
- **集成测试**:系统级别的协作效果验证
- **端到端测试**:完整用户流程的验证
- **性能测试**:执行效率和资源使用验证
### 质量标准制定
- **功能完整性**:所有承诺功能都正确实现
- **可靠性**:在各种条件下都能稳定运行
- **易用性**:用户能够直观地理解和使用
- **性能表现**:满足响应时间和资源使用要求
</exploration>
<reasoning>
## 验证逻辑框架
### 测试用例设计
- **正常路径测试**:标准使用场景的验证
- **异常路径测试**:错误输入和异常情况的处理
- **边界值测试**:参数极值和临界条件的验证
- **兼容性测试**:不同环境和版本的兼容性
### 验证方法选择
- **自动化测试**:可重复执行的测试脚本
- **手动测试**:需要人工判断的复杂场景
- **性能基准测试**:量化的性能指标验证
- **用户验收测试**:真实用户的使用反馈
### 问题分类处理
- **阻塞性问题**:影响核心功能的严重问题
- **功能性问题**:特定功能的实现偏差
- **体验性问题**:影响用户体验的问题
- **性能问题**:不满足性能要求的问题
### 质量门禁设置
- **功能完整性门禁**:所有核心功能必须通过测试
- **性能标准门禁**执行时间和内存使用在acceptable范围
- **安全性门禁**:无安全漏洞和风险
- **兼容性门禁**与PromptX生态系统完全兼容
</reasoning>
<challenge>
## 验证过程中的挑战
### 测试覆盖挑战
- 如何确保测试用例覆盖所有关键场景
- 如何处理难以模拟的复杂使用环境
- 如何平衡测试覆盖度和测试效率
- 如何验证非功能性需求的满足情况
### 质量评估挑战
- 如何量化用户体验的质量
- 如何在有限时间内发现潜在问题
- 如何评估工具的长期可维护性
- 如何预测真实使用中可能遇到的问题
### 问题修复挑战
- 如何在功能修复和风险控制间平衡
- 如何处理修复引入的新问题
- 如何确保修复不影响其他功能
- 如何评估修复的完整性和有效性
### 交付决策挑战
- 如何确定工具已达到交付标准
- 如何处理已知但不阻塞的问题
- 如何平衡完美和实用的标准
- 如何制定合理的质量验收标准
</challenge>
<plan>
## 验证思维工作流程
### Phase 1: 测试计划
1. **测试策略制定** → 确定测试范围和方法
2. **测试用例设计** → 设计覆盖关键场景的测试用例
3. **测试环境准备** → 搭建符合实际使用的测试环境
4. **验收标准确定** → 明确质量门禁和验收标准
### Phase 2: 功能验证
1. **单元测试执行** → 验证各模块的功能正确性
2. **集成测试执行** → 验证模块间的协作效果
3. **系统测试执行** → 验证完整系统的功能表现
4. **回归测试执行** → 确保修改不影响已有功能
### Phase 3: 质量验证
1. **性能测试** → 验证执行效率和资源使用
2. **兼容性测试** → 验证在不同环境下的表现
3. **安全测试** → 验证输入验证和安全防护
4. **可用性测试** → 验证用户使用的便利性
### Phase 4: 用户验收
1. **真实场景测试** → 在真实使用场景中验证
2. **用户反馈收集** → 收集用户的使用体验反馈
3. **问题优先级评估** → 评估发现问题的严重性
4. **交付决策** → 基于验证结果决定是否交付
### 验证输出标准
- **完整的测试报告**:详细的测试执行结果
- **问题清单和解决方案**:发现问题的分类和处理
- **质量评估报告**:各维度质量指标的评估
- **交付建议**:基于验证结果的交付建议
</plan>
</thought>