Files

Cen-Yaozu 05cb5f54c0 feat: 实现本地角色动态发现机制 - 双重角色发现机制：同时支持npm仓库角色和本地项目角色 - 智能环境检测：自动适配开发、npx、全局、本地、monorepo等部署环境 - 安全机制完善：路径验证、权限检查、多层容错处理 - 向后兼容保证，不影响现有功能

2025-06-01 21:26:14 +08:00

5.5 KiB

Raw Blame History

🎯 实现本地角色动态发现功能

📋 概述

本PR为PromptX系统实现了本地角色动态发现机制，解决了系统只能发现npm包预置角色的限制，使用户能够在项目中创建和使用自定义角色。

🎯 解决的问题

核心痛点

❌ 静态角色库限制：系统只能发现npm包中预置的角色
❌ 本地角色盲区：无法识别用户在项目中创建的自定义角色
❌ 部署环境受限：不能适应不同的npm安装和部署场景

使用场景

项目团队需要创建项目专属的AI角色
开发者希望为特定业务场景定制专业角色
企业需要在私有环境中部署自定义角色

🏗️ 技术方案

核心实现：双重角色发现机制

// 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包使用	✅ 通过	只显示仓库角色
项目中创建本地角色	✅ 通过	显示仓库+本地角色
本地角色与仓库角色同名	✅ 通过	本地角色优先
无效角色文件	✅ 通过	跳过并警告
权限不足场景	✅ 通过	优雅降级

性能验证

✅ 缓存机制有效减少重复扫描
✅ 大型项目下性能表现良好
✅ 降级策略确保系统稳定性

📖 使用指南

创建本地角色

# 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

激活本地角色

# 查看所有角色（包括本地角色）
npx dpml-prompt hello

# 激活自定义角色
npx dpml-prompt action my-custom-role

🔄 向后兼容性

完全兼容保证

✅ 现有npm包角色完全兼容
✅ 原有CLI命令保持不变
✅ 配置文件格式保持兼容
✅ 无本地角色时正常工作

渐进增强特性

本地角色优先级高于仓库角色
支持角色覆盖和扩展
平滑的功能降级机制

🚀 技术亮点

架构设计优势

统一资源管理：正确使用ResourceManager架构
智能环境适配：自动检测多种部署环境
安全机制完善：全面的安全验证和容错处理
性能优化：多级缓存和懒加载机制

代码质量保证

遵循项目现有的编码规范
完整的错误处理和日志记录
清晰的代码注释和文档
符合SOLID设计原则

📊 影响评估

用户价值

🎯 提升灵活性：用户可创建项目专属角色
🎯 降低门槛：无需发布npm包即可使用自定义角色
🎯 增强体验：本地角色发现无感知、自动化

技术债务

📈 增加复杂性：文件扫描和解析逻辑
📈 维护成本：需要维护多环境兼容性
✅ 风险可控：完善的容错和降级机制

🔧 配置要求

最小环境要求

Node.js >= 14.0.0
npm >= 6.0.0
项目根目录可写权限

可选配置

package.json中的files字段（用于权限控制）
.promptx目录（用于存储配置）

📚 相关文档

🤝 贡献说明

本PR遵循PromptX项目的贡献规范：

✅ 通过所有现有测试
✅ 添加了相应的测试用例
✅ 遵循代码格式规范
✅ 提供了完整的文档说明

特别说明：本实现完全保持了对现有功能的兼容性，同时为PromptX系统带来了重要的功能增强。期待社区的反馈和建议！

🏷️ 标签

enhancement feature role-system local-discovery backward-compatible

5.5 KiB Raw Blame History Unescape Escape