feat: 实现本地角色动态发现机制 - 双重角色发现机制：同时支持npm仓库角色和本地项目角色 - 智能环境检测：自动适配开发、npx、全局、本地、monorepo等部署环境 - 安全机制完善：路径验证、权限检查、多层容错处理 - 向后兼容保证，不影响现有功能
This commit is contained in:
Cen-Yaozu
186
docs/PULL_REQUEST_DESCRIPTION.md
Normal file
186
docs/PULL_REQUEST_DESCRIPTION.md
Normal file
@ -0,0 +1,186 @@
|
||||
# 🎯 实现本地角色动态发现功能
|
||||
|
||||
## 📋 概述
|
||||
|
||||
本PR为PromptX系统实现了**本地角色动态发现机制**，解决了系统只能发现npm包预置角色的限制，使用户能够在项目中创建和使用自定义角色。
|
||||
|
||||
## 🎯 解决的问题
|
||||
|
||||
### **核心痛点**
|
||||
- ❌ **静态角色库限制**：系统只能发现npm包中预置的角色
|
||||
- ❌ **本地角色盲区**：无法识别用户在项目中创建的自定义角色
|
||||
- ❌ **部署环境受限**：不能适应不同的npm安装和部署场景
|
||||
|
||||
### **使用场景**
|
||||
- 项目团队需要创建项目专属的AI角色
|
||||
- 开发者希望为特定业务场景定制专业角色
|
||||
- 企业需要在私有环境中部署自定义角色
|
||||
|
||||
## 🏗️ 技术方案
|
||||
|
||||
### **核心实现：双重角色发现机制**
|
||||
|
||||
```javascript
|
||||
// 1. 保持对npm仓库角色的完全兼容
|
||||
const registeredRoles = resourceManager.registry.protocols.role.registry
|
||||
|
||||
// 2. 动态发现本地项目角色
|
||||
const discoveredRoles = await this.discoverLocalRoles()
|
||||
|
||||
// 3. 智能合并（本地角色优先级更高）
|
||||
this.roleRegistry = { ...registeredRoles, ...discoveredRoles }
|
||||
```
|
||||
|
||||
### **环境智能检测**
|
||||
系统能够自动检测并适应以下部署环境：
|
||||
- ✅ **开发模式** (NODE_ENV=development)
|
||||
- ✅ **NPX执行** (npx dpml-prompt)
|
||||
- ✅ **全局安装** (npm install -g)
|
||||
- ✅ **本地安装** (npm install)
|
||||
- ✅ **Monorepo** (workspaces)
|
||||
- ✅ **NPM Link** (npm link)
|
||||
|
||||
### **安全保障机制**
|
||||
- 🛡️ **路径安全验证**：防止路径遍历攻击
|
||||
- 🛡️ **权限检查**：基于package.json的files字段验证
|
||||
- 🛡️ **容错处理**：多层降级保证系统可用性
|
||||
|
||||
## 📁 主要变更
|
||||
|
||||
### **新增文件**
|
||||
- `docs/role-activation-improvements.md` - 详细技术文档
|
||||
- 新增多个领域角色示例（frontend-developer、java-backend-developer等）
|
||||
|
||||
### **核心修改**
|
||||
- `src/lib/core/pouch/commands/HelloCommand.js` - 实现双重角色发现
|
||||
- `src/lib/core/pouch/commands/RegisterCommand.js` - 支持本地角色注册
|
||||
- `src/resource.registry.json` - 扩充角色注册表
|
||||
|
||||
### **功能增强**
|
||||
- 动态文件扫描和元数据解析
|
||||
- 智能缓存机制避免重复扫描
|
||||
- 完善的错误处理和日志记录
|
||||
|
||||
## 🧪 测试验证
|
||||
|
||||
### **测试场景覆盖**
|
||||
| 测试场景 | 状态 | 预期结果 |
|
||||
|---------|------|---------|
|
||||
| 纯npm包使用 | ✅ 通过 | 只显示仓库角色 |
|
||||
| 项目中创建本地角色 | ✅ 通过 | 显示仓库+本地角色 |
|
||||
| 本地角色与仓库角色同名 | ✅ 通过 | 本地角色优先 |
|
||||
| 无效角色文件 | ✅ 通过 | 跳过并警告 |
|
||||
| 权限不足场景 | ✅ 通过 | 优雅降级 |
|
||||
|
||||
### **性能验证**
|
||||
- ✅ 缓存机制有效减少重复扫描
|
||||
- ✅ 大型项目下性能表现良好
|
||||
- ✅ 降级策略确保系统稳定性
|
||||
|
||||
## 📖 使用指南
|
||||
|
||||
### **创建本地角色**
|
||||
```bash
|
||||
# 1. 创建角色目录结构
|
||||
mkdir -p prompt/domain/my-custom-role/{thought,execution}
|
||||
|
||||
# 2. 创建主角色文件
|
||||
cat > prompt/domain/my-custom-role/my-custom-role.role.md << 'EOF'
|
||||
<!--
|
||||
name: 🎯 项目专属角色
|
||||
description: 为当前项目量身定制的专业角色
|
||||
-->
|
||||
|
||||
<role>
|
||||
<personality>
|
||||
@!thought://my-custom-role
|
||||
</personality>
|
||||
<principle>
|
||||
@!execution://my-custom-role
|
||||
</principle>
|
||||
</role>
|
||||
EOF
|
||||
|
||||
# 3. 验证角色发现
|
||||
npx dpml-prompt hello
|
||||
```
|
||||
|
||||
### **激活本地角色**
|
||||
```bash
|
||||
# 查看所有角色（包括本地角色）
|
||||
npx dpml-prompt hello
|
||||
|
||||
# 激活自定义角色
|
||||
npx dpml-prompt action my-custom-role
|
||||
```
|
||||
|
||||
## 🔄 向后兼容性
|
||||
|
||||
### **完全兼容保证**
|
||||
- ✅ 现有npm包角色完全兼容
|
||||
- ✅ 原有CLI命令保持不变
|
||||
- ✅ 配置文件格式保持兼容
|
||||
- ✅ 无本地角色时正常工作
|
||||
|
||||
### **渐进增强特性**
|
||||
- 本地角色优先级高于仓库角色
|
||||
- 支持角色覆盖和扩展
|
||||
- 平滑的功能降级机制
|
||||
|
||||
## 🚀 技术亮点
|
||||
|
||||
### **架构设计优势**
|
||||
1. **统一资源管理**：正确使用ResourceManager架构
|
||||
2. **智能环境适配**：自动检测多种部署环境
|
||||
3. **安全机制完善**：全面的安全验证和容错处理
|
||||
4. **性能优化**：多级缓存和懒加载机制
|
||||
|
||||
### **代码质量保证**
|
||||
- 遵循项目现有的编码规范
|
||||
- 完整的错误处理和日志记录
|
||||
- 清晰的代码注释和文档
|
||||
- 符合SOLID设计原则
|
||||
|
||||
## 📊 影响评估
|
||||
|
||||
### **用户价值**
|
||||
- 🎯 **提升灵活性**：用户可创建项目专属角色
|
||||
- 🎯 **降低门槛**：无需发布npm包即可使用自定义角色
|
||||
- 🎯 **增强体验**：本地角色发现无感知、自动化
|
||||
|
||||
### **技术债务**
|
||||
- 📈 **增加复杂性**：文件扫描和解析逻辑
|
||||
- 📈 **维护成本**：需要维护多环境兼容性
|
||||
- ✅ **风险可控**：完善的容错和降级机制
|
||||
|
||||
## 🔧 配置要求
|
||||
|
||||
### **最小环境要求**
|
||||
- Node.js >= 14.0.0
|
||||
- npm >= 6.0.0
|
||||
- 项目根目录可写权限
|
||||
|
||||
### **可选配置**
|
||||
- package.json中的files字段（用于权限控制）
|
||||
- .promptx目录（用于存储配置）
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
- [详细技术文档](./role-activation-improvements.md)
|
||||
- [架构设计说明](../prompt/protocol/README.md)
|
||||
- [用户使用指南](../README.md)
|
||||
|
||||
## 🤝 贡献说明
|
||||
|
||||
本PR遵循PromptX项目的贡献规范：
|
||||
- ✅ 通过所有现有测试
|
||||
- ✅ 添加了相应的测试用例
|
||||
- ✅ 遵循代码格式规范
|
||||
- ✅ 提供了完整的文档说明
|
||||
|
||||
---
|
||||
|
||||
**特别说明**：本实现完全保持了对现有功能的兼容性，同时为PromptX系统带来了重要的功能增强。期待社区的反馈和建议！
|
||||
|
||||
## 🏷️ 标签
|
||||
`enhancement` `feature` `role-system` `local-discovery` `backward-compatible`
|
||||
Reference in New Issue
Block a user