510 lines
13 KiB
Markdown
510 lines
13 KiB
Markdown
# PromptX 角色激活流程重大改进文档
|
||
|
||
## 📋 概述
|
||
|
||
本文档详细说明了PromptX系统在角色激活流程方面的重大改进，重点解决了从npm仓库模式向本地项目角色发现模式的转变。
|
||
|
||
## 🎯 改进目标
|
||
|
||
### 问题背景
|
||
在改进前，PromptX系统存在以下限制：
|
||
- **静态角色库**：只能发现npm包中预置的角色
|
||
- **本地角色盲区**：无法识别用户在项目中创建的自定义角色
|
||
- **部署环境限制**：不能适应不同的npm安装和部署场景
|
||
|
||
### 解决方案
|
||
通过实现**双重角色发现机制**，系统现在能够：
|
||
- ✅ 自动发现本地项目中的自定义角色
|
||
- ✅ 保持对npm仓库角色的完全兼容
|
||
- ✅ 适应多种部署和开发环境
|
||
|
||
## 🏗️ 技术架构改进
|
||
|
||
### 1. 双重角色发现机制
|
||
|
||
#### 原有架构
|
||
```mermaid
|
||
flowchart TD
|
||
A[用户执行 hello 命令] --> B[读取 resource.registry.json]
|
||
B --> C[返回预置角色列表]
|
||
C --> D[用户只能看到仓库角色]
|
||
```
|
||
|
||
#### 改进后架构
|
||
```mermaid
|
||
flowchart TD
|
||
A[用户执行 hello 命令] --> B[加载资源管理器]
|
||
B --> C[读取注册表角色]
|
||
B --> D[动态发现本地角色]
|
||
C --> E[合并角色列表]
|
||
D --> E
|
||
E --> F[返回完整角色列表]
|
||
F --> G[用户可见仓库+本地角色]
|
||
```
|
||
|
||
### 2. 智能环境检测系统
|
||
|
||
系统现在能够智能检测并适应以下部署环境：
|
||
|
||
| 环境类型 | 检测方式 | 角色发现策略 |
|
||
|---------|---------|-------------|
|
||
| **开发模式** | NODE_ENV=development | 直接扫描源码目录 |
|
||
| **NPX执行** | 检测npx相关环境变量 | 从临时缓存目录发现 |
|
||
| **全局安装** | 检测全局路径 | 从全局node_modules发现 |
|
||
| **本地安装** | 默认情况 | 从项目node_modules发现 |
|
||
| **Monorepo** | 检测workspaces字段 | 从工作空间根目录发现 |
|
||
| **NPM Link** | 检测符号链接 | 解析真实路径后发现 |
|
||
|
||
## 🔧 核心功能实现
|
||
|
||
### 1. 本地角色动态发现
|
||
|
||
```javascript
|
||
// HelloCommand.js 中的核心实现
|
||
async discoverLocalRoles() {
|
||
const PackageProtocol = require('../../resource/protocols/PackageProtocol')
|
||
const packageProtocol = new PackageProtocol()
|
||
const glob = require('glob')
|
||
|
||
try {
|
||
// 获取项目根目录
|
||
const packageRoot = await packageProtocol.getPackageRoot()
|
||
const domainPath = path.join(packageRoot, 'prompt', 'domain')
|
||
|
||
// 扫描所有角色文件
|
||
const rolePattern = path.join(domainPath, '*', '*.role.md')
|
||
const roleFiles = glob.sync(rolePattern)
|
||
|
||
const discoveredRoles = {}
|
||
|
||
for (const roleFile of roleFiles) {
|
||
// 提取角色元数据
|
||
const content = await fs.readFile(roleFile, 'utf-8')
|
||
const roleName = path.basename(roleFile, '.role.md')
|
||
|
||
// 智能解析name和description
|
||
const nameMatch = content.match(/name:\s*(.+?)(?:\n|$)/i)
|
||
const descMatch = content.match(/description:\s*(.+?)(?:\n|$)/i)
|
||
|
||
discoveredRoles[roleName] = {
|
||
file: `@package://${relativePath}`,
|
||
name: nameMatch ? nameMatch[1].trim() : `🎭 ${roleName}`,
|
||
description: descMatch ? descMatch[1].trim() : '本地发现的角色',
|
||
source: 'local-discovery'
|
||
}
|
||
}
|
||
|
||
return discoveredRoles
|
||
} catch (error) {
|
||
console.warn('动态角色发现失败:', error.message)
|
||
return {}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 环境智能检测
|
||
|
||
```javascript
|
||
// PackageProtocol.js 中的环境检测
|
||
_performInstallModeDetection() {
|
||
// 检测npx执行
|
||
if (this._isNpxExecution()) {
|
||
return 'npx'
|
||
}
|
||
|
||
// 检测全局安装
|
||
if (this._isGlobalInstall()) {
|
||
return 'global'
|
||
}
|
||
|
||
// 检测开发模式
|
||
if (this._isDevelopmentMode()) {
|
||
return 'development'
|
||
}
|
||
|
||
// 检测monorepo
|
||
if (this._isMonorepoWorkspace()) {
|
||
return 'monorepo'
|
||
}
|
||
|
||
// 检测npm link
|
||
if (this._isNpmLink()) {
|
||
return 'link'
|
||
}
|
||
|
||
// 默认为本地安装
|
||
return 'local'
|
||
}
|
||
```
|
||
|
||
### 3. 角色合并策略
|
||
|
||
```javascript
|
||
// 双重发现并合并
|
||
async loadRoleRegistry() {
|
||
try {
|
||
// 1. 加载注册表角色
|
||
const resourceManager = new ResourceManager()
|
||
await resourceManager.initialize()
|
||
const registeredRoles = resourceManager.registry.protocols.role.registry || {}
|
||
|
||
// 2. 动态发现本地角色
|
||
const discoveredRoles = await this.discoverLocalRoles()
|
||
|
||
// 3. 合并角色（本地角色优先级更高）
|
||
this.roleRegistry = {
|
||
...registeredRoles,
|
||
...discoveredRoles
|
||
}
|
||
|
||
// 4. 容错处理
|
||
if (Object.keys(this.roleRegistry).length === 0) {
|
||
this.roleRegistry = {
|
||
assistant: {
|
||
file: '@package://prompt/domain/assistant/assistant.role.md',
|
||
name: '🙋 智能助手',
|
||
description: '通用助理角色，提供基础的助理服务和记忆支持'
|
||
}
|
||
}
|
||
}
|
||
} catch (error) {
|
||
// 降级到动态发现
|
||
const discoveredRoles = await this.discoverLocalRoles()
|
||
this.roleRegistry = Object.keys(discoveredRoles).length > 0
|
||
? discoveredRoles
|
||
: { /* 基础assistant角色 */ }
|
||
}
|
||
}
|
||
```
|
||
|
||
## 📝 使用指南
|
||
|
||
### 1. 创建本地角色
|
||
|
||
在项目根目录下创建角色：
|
||
|
||
```bash
|
||
# 创建角色目录结构
|
||
mkdir -p prompt/domain/my-custom-role/thought
|
||
mkdir -p prompt/domain/my-custom-role/execution
|
||
|
||
# 创建主角色文件
|
||
cat > prompt/domain/my-custom-role/my-custom-role.role.md << 'EOF'
|
||
<!--
|
||
name: 🎯 项目专属角色
|
||
description: 为当前项目量身定制的专业角色
|
||
-->
|
||
|
||
<role>
|
||
<personality>
|
||
@!thought://remember
|
||
@!thought://recall
|
||
@!thought://my-custom-role
|
||
</personality>
|
||
|
||
<principle>
|
||
@!execution://my-custom-role
|
||
</principle>
|
||
</role>
|
||
EOF
|
||
|
||
# 创建思维组件
|
||
cat > prompt/domain/my-custom-role/thought/my-custom-role.thought.md << 'EOF'
|
||
<thought>
|
||
<exploration>
|
||
# 项目专属思维探索
|
||
## 核心能力
|
||
- 深度理解项目需求
|
||
- 定制化解决方案
|
||
- 项目上下文感知
|
||
</exploration>
|
||
|
||
<reasoning>
|
||
# 推理框架
|
||
## 决策逻辑
|
||
1. 分析项目背景
|
||
2. 识别关键需求
|
||
3. 制定解决方案
|
||
4. 验证可行性
|
||
</reasoning>
|
||
|
||
<challenge>
|
||
# 风险识别
|
||
## 潜在挑战
|
||
- 需求变更风险
|
||
- 技术实现难度
|
||
- 时间约束压力
|
||
</challenge>
|
||
|
||
<plan>
|
||
# 执行计划
|
||
## 工作流程
|
||
1. 需求收集与分析
|
||
2. 方案设计与评估
|
||
3. 实施与监控
|
||
4. 反馈与优化
|
||
</plan>
|
||
</thought>
|
||
EOF
|
||
|
||
# 创建执行组件
|
||
cat > prompt/domain/my-custom-role/execution/my-custom-role.execution.md << 'EOF'
|
||
<execution>
|
||
<constraint>
|
||
# 约束条件
|
||
- 必须符合项目标准
|
||
- 遵循开发规范
|
||
- 保证交付质量
|
||
</constraint>
|
||
|
||
<rule>
|
||
# 强制规则
|
||
1. 所有方案必须经过验证
|
||
2. 必须提供详细文档
|
||
3. 确保代码质量标准
|
||
</rule>
|
||
|
||
<guideline>
|
||
# 指导原则
|
||
- 用户需求优先
|
||
- 简洁高效实现
|
||
- 可维护性考虑
|
||
</guideline>
|
||
|
||
<process>
|
||
# 执行流程
|
||
```mermaid
|
||
flowchart TD
|
||
A[接收需求] --> B[分析评估]
|
||
B --> C[方案设计]
|
||
C --> D[实施执行]
|
||
D --> E[质量检查]
|
||
E --> F[交付确认]
|
||
```
|
||
</process>
|
||
|
||
<criteria>
|
||
# 评价标准
|
||
| 维度 | 标准 |
|
||
|------|------|
|
||
| 功能完整性 | 100% |
|
||
| 代码质量 | A级 |
|
||
| 文档完备性 | 完整 |
|
||
| 用户满意度 | ≥90% |
|
||
</criteria>
|
||
</execution>
|
||
EOF
|
||
```
|
||
|
||
### 2. 验证角色发现
|
||
|
||
```bash
|
||
# 查看所有可用角色（包括本地角色）
|
||
npx dpml-prompt hello
|
||
|
||
# 激活本地角色
|
||
npx dpml-prompt action my-custom-role
|
||
|
||
# 注册角色到系统（可选）
|
||
npx dpml-prompt register my-custom-role
|
||
```
|
||
|
||
### 3. 角色元数据最佳实践
|
||
|
||
在角色文件顶部使用标准注释格式：
|
||
|
||
```markdown
|
||
<!--
|
||
name: 🎯 [角色显示名称]
|
||
description: [详细的角色功能描述]
|
||
version: 1.0.0
|
||
author: [作者名称]
|
||
tags: [标签1, 标签2, 标签3]
|
||
-->
|
||
```
|
||
|
||
## 🔍 技术细节
|
||
|
||
### 1. 文件扫描机制
|
||
|
||
- **扫描路径**：`{项目根}/prompt/domain/*/*.role.md`
|
||
- **扫描工具**：使用`glob`模块进行高效文件匹配
|
||
- **元数据提取**：正则表达式解析注释中的元信息
|
||
- **容错处理**：跳过格式错误的文件，记录警告信息
|
||
|
||
### 2. 路径解析策略
|
||
|
||
- **@package://协议**：统一的资源访问协议
|
||
- **相对路径转换**：自动转换为文件系统绝对路径
|
||
- **安全验证**：防止路径遍历攻击
|
||
- **权限检查**：基于package.json的files字段验证访问权限
|
||
|
||
### 3. 缓存机制
|
||
|
||
- **环境检测缓存**：避免重复检测安装环境
|
||
- **角色注册表缓存**：提高重复访问性能
|
||
- **失效策略**：支持手动清除缓存
|
||
|
||
## 🛡️ 安全考虑
|
||
|
||
### 1. 路径安全
|
||
|
||
```javascript
|
||
// 防止路径遍历攻击
|
||
if (!fullPath.startsWith(packageRoot)) {
|
||
throw new Error(`Path traversal detected: ${relativePath}`)
|
||
}
|
||
```
|
||
|
||
### 2. 文件访问控制
|
||
|
||
```javascript
|
||
// 基于package.json的files字段验证
|
||
validateFileAccess(packageRoot, relativePath) {
|
||
const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
|
||
|
||
if (!packageJson.files || !Array.isArray(packageJson.files)) {
|
||
return // 开发模式允许访问所有文件
|
||
}
|
||
|
||
// 检查是否匹配files字段中的模式
|
||
const isAllowed = packageJson.files.some(filePattern => {
|
||
// 模式匹配逻辑
|
||
})
|
||
|
||
if (!isAllowed) {
|
||
throw new Error(`Access denied: Path not in package.json files field`)
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 容错机制
|
||
|
||
- **多层降级**：注册表失败 → 动态发现 → 基础角色
|
||
- **错误隔离**：单个角色解析失败不影响其他角色
|
||
- **日志记录**：详细记录错误信息便于调试
|
||
|
||
## 📊 性能优化
|
||
|
||
### 1. 懒加载机制
|
||
|
||
- **按需初始化**：只在需要时才进行角色发现
|
||
- **缓存复用**：避免重复的文件系统操作
|
||
- **异步处理**：使用Promise并行处理多个角色文件
|
||
|
||
### 2. 扫描优化
|
||
|
||
- **Glob模式**：高效的文件匹配模式
|
||
- **路径预过滤**：提前过滤无效路径
|
||
- **内容解析**：只解析必要的元数据信息
|
||
|
||
## 🔄 兼容性保证
|
||
|
||
### 1. 向后兼容
|
||
|
||
- ✅ 现有npm包角色完全兼容
|
||
- ✅ 原有CLI命令保持不变
|
||
- ✅ 配置文件格式保持兼容
|
||
|
||
### 2. 渐进增强
|
||
|
||
- ✅ 无本地角色时正常工作
|
||
- ✅ 本地角色优先级高于仓库角色
|
||
- ✅ 支持角色覆盖和扩展
|
||
|
||
## 🧪 测试验证
|
||
|
||
### 1. 单元测试
|
||
|
||
```bash
|
||
# 测试角色发现功能
|
||
npm run test:unit -- --grep "discoverLocalRoles"
|
||
|
||
# 测试环境检测功能
|
||
npm run test:unit -- --grep "detectInstallMode"
|
||
|
||
# 测试路径解析功能
|
||
npm run test:unit -- --grep "resolvePath"
|
||
```
|
||
|
||
### 2. 集成测试
|
||
|
||
```bash
|
||
# 测试完整的角色激活流程
|
||
npm run test:integration -- --grep "role-activation"
|
||
|
||
# 测试多环境兼容性
|
||
npm run test:e2e -- --grep "multi-environment"
|
||
```
|
||
|
||
### 3. 手动测试场景
|
||
|
||
| 测试场景 | 预期结果 |
|
||
|---------|---------|
|
||
| 纯npm包使用 | 只显示仓库角色 |
|
||
| 项目中创建本地角色 | 显示仓库+本地角色 |
|
||
| 本地角色与仓库角色同名 | 本地角色优先 |
|
||
| 无效角色文件 | 跳过并警告 |
|
||
| 权限不足 | 优雅降级 |
|
||
|
||
## 📚 最佳实践
|
||
|
||
### 1. 角色设计规范
|
||
|
||
- **命名规范**：使用kebab-case命名
|
||
- **目录结构**：遵循标准三件套结构
|
||
- **元数据完整**：提供完整的name和description
|
||
- **文档齐全**：包含详细的使用说明
|
||
|
||
### 2. 项目组织建议
|
||
|
||
```
|
||
project-root/
|
||
├── prompt/
|
||
│ └── domain/
|
||
│ ├── project-assistant/ # 项目助手角色
|
||
│ ├── api-designer/ # API设计师角色
|
||
│ ├── code-reviewer/ # 代码审查员角色
|
||
│ └── deployment-manager/ # 部署管理员角色
|
||
├── package.json
|
||
└── README.md
|
||
```
|
||
|
||
### 3. 版本管理
|
||
|
||
- **语义化版本**：在角色注释中标注版本
|
||
- **变更记录**：维护角色变更历史
|
||
- **兼容性声明**：明确依赖的系统版本
|
||
|
||
## 🚀 未来扩展
|
||
|
||
### 1. 计划中的功能
|
||
|
||
- **角色市场**：支持从在线市场下载角色
|
||
- **角色模板**：提供更多角色创建模板
|
||
- **依赖管理**：支持角色间的依赖关系
|
||
- **热更新**：支持角色的热重载
|
||
|
||
### 2. 性能优化方向
|
||
|
||
- **增量扫描**：只扫描变更的角色文件
|
||
- **并行处理**：并行解析多个角色文件
|
||
- **智能缓存**：基于文件修改时间的智能缓存
|
||
|
||
## 📖 总结
|
||
|
||
本次角色激活流程改进是PromptX系统的一个重要里程碑，它解决了系统从静态npm包模式向动态本地发现模式的转变。主要成果包括：
|
||
|
||
1. **🎯 问题解决**：完全解决了本地角色无法发现的问题
|
||
2. **🏗️ 架构升级**：实现了双重发现机制和智能环境检测
|
||
3. **🛡️ 安全保障**：提供了完整的安全验证和容错机制
|
||
4. **📈 性能优化**：通过缓存和懒加载提升了系统性能
|
||
5. **🔄 兼容保证**：确保了向后兼容和渐进增强
|
||
|
||
这些改进使得PromptX不仅可以作为npm包提供标准角色，更可以在具体项目中创建和使用专门定制的角色，真正实现了"AI use CLI get prompt for AI"的设计理念。
|
||
|
||
---
|
||
|
||
*文档版本：1.0.0*
|
||
*最后更新：2024年12月*
|
||
*维护者：PromptX开发团队* |