186 lines
5.5 KiB
Markdown
186 lines
5.5 KiB
Markdown
# 🎯 实现本地角色动态发现功能
|
||
|
||
## 📋 概述
|
||
|
||
本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` |