优化角色注册，发现，nuwa 角色的提示词等
This commit is contained in:
sean
235
docs/issues/role-content-parsing-incomplete.md
Normal file
235
docs/issues/role-content-parsing-incomplete.md
Normal file
@ -0,0 +1,235 @@
|
||||
# 角色内容解析不完整问题
|
||||
|
||||
## 🔥 问题等级
|
||||
**高优先级 (High Priority)**
|
||||
|
||||
## 📋 问题描述
|
||||
|
||||
当前PromptX的角色解析机制存在重大缺陷：**只解析@引用，完全忽略DPML标签内的直接内容**。这导致许多用户自定义角色的核心能力丢失。
|
||||
|
||||
## 🔍 问题详情
|
||||
|
||||
### 当前解析机制
|
||||
ActionCommand在`analyzeRoleDependencies`方法中使用以下正则表达式：
|
||||
```javascript
|
||||
const resourceRegex = /@([!?]?)([a-zA-Z][a-zA-Z0-9_-]*):\/\/([a-zA-Z0-9_\/.,-]+?)(?=[\s\)\],]|$)/g
|
||||
```
|
||||
|
||||
这个正则**只提取@引用**，完全忽略DPML标签内直接编写的内容。
|
||||
|
||||
### 影响的角色类型
|
||||
|
||||
#### 1. 系统角色（使用@引用）
|
||||
```xml
|
||||
<!-- prompt/domain/assistant/assistant.role.md -->
|
||||
<role>
|
||||
<personality>
|
||||
@!thought://remember
|
||||
@!thought://recall
|
||||
@!thought://assistant
|
||||
</personality>
|
||||
<principle>
|
||||
@!execution://assistant
|
||||
</principle>
|
||||
</role>
|
||||
```
|
||||
**状态**：✅ 正常解析
|
||||
|
||||
#### 2. 用户角色（直接内容）
|
||||
```xml
|
||||
<!-- .promptx/resource/domain/internet-debater/internet-debater.role.md -->
|
||||
<role>
|
||||
<personality>
|
||||
# 网络杠精思维模式
|
||||
## 核心思维特征
|
||||
- **挑刺思维**：看到任何观点都先找问题和漏洞
|
||||
- **抬杠本能**：天生反对派，习惯性质疑一切表述
|
||||
...
|
||||
</personality>
|
||||
<principle>
|
||||
# 网络杠精行为原则
|
||||
## 核心抬杠准则
|
||||
- **逢言必反**：对任何观点都要找到反对的角度
|
||||
...
|
||||
</principle>
|
||||
<knowledge>
|
||||
# 网络杠精专业知识体系
|
||||
## 逻辑谬误大全
|
||||
- **稻草人谬误**：故意曲解对方观点
|
||||
...
|
||||
</knowledge>
|
||||
</role>
|
||||
```
|
||||
**状态**：❌ **内容完全丢失**
|
||||
|
||||
## 🎯 具体影响
|
||||
|
||||
### internet-debater角色损失分析
|
||||
- **丢失内容**：3个完整的DPML节段，约100行专业内容
|
||||
- **丢失能力**：
|
||||
- 杠精思维模式和认知特征
|
||||
- 抬杠行为原则和语言风格
|
||||
- 逻辑谬误知识和争论技巧
|
||||
- **用户体验**：激活角色后获得的是"空壳"，无法发挥预期作用
|
||||
|
||||
### 潜在影响范围
|
||||
- 所有直接编写内容的用户自定义角色
|
||||
- 混合编写方式的角色（@引用 + 直接内容）
|
||||
- 未来可能创建的角色
|
||||
|
||||
## 🔍 根因分析
|
||||
|
||||
### 1. 设计假设错误
|
||||
系统设计时假设所有角色都使用@引用方式，但实际上：
|
||||
- 用户更倾向于直接编写内容
|
||||
- 文档没有强制要求使用@引用
|
||||
- 角色创建工具支持直接编写
|
||||
|
||||
### 2. 验证与解析分离
|
||||
```javascript
|
||||
// resourceManager.js - 只验证格式，不解析内容
|
||||
validateDPMLFormat(content, type) {
|
||||
const tags = DPML_TAGS[type]
|
||||
return content.includes(tags.start) && content.includes(tags.end)
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 解析逻辑单一
|
||||
ActionCommand只有一种解析模式：正则匹配@引用，没有考虑直接内容。
|
||||
|
||||
## 💡 解决方案
|
||||
|
||||
### 方案1：混合解析机制（推荐）
|
||||
扩展ActionCommand解析逻辑，同时支持：
|
||||
1. **@引用解析**：保持现有逻辑
|
||||
2. **直接内容解析**：提取DPML标签内的Markdown内容
|
||||
3. **内容合并**：@引用内容 + 直接内容 = 完整角色能力
|
||||
|
||||
### 方案2：内容提取器
|
||||
创建专门的DPML内容提取器：
|
||||
```javascript
|
||||
class DPMLContentExtractor {
|
||||
extractTagContent(content, tagName) {
|
||||
const regex = new RegExp(`<${tagName}>([\\s\\S]*?)</${tagName}>`, 'g')
|
||||
// 提取标签内容，同时处理@引用和直接内容
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 方案3：解析策略统一
|
||||
统一角色解析策略：
|
||||
1. 优先解析@引用
|
||||
2. 补充解析直接内容
|
||||
3. 合并生成完整的角色Profile
|
||||
|
||||
## 🔧 技术实现要点
|
||||
|
||||
### 1. 扩展依赖分析
|
||||
```javascript
|
||||
// ActionCommand.js
|
||||
async analyzeRoleDependencies(roleInfo) {
|
||||
const roleContent = await fs.readFile(filePath, 'utf-8')
|
||||
|
||||
// 现有：提取@引用
|
||||
const references = this.extractReferences(roleContent)
|
||||
|
||||
// 新增：提取直接内容
|
||||
const directContent = this.extractDirectContent(roleContent)
|
||||
|
||||
// 合并依赖
|
||||
return this.mergeDependencies(references, directContent)
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 内容提取算法
|
||||
```javascript
|
||||
extractDirectContent(content) {
|
||||
const sections = {}
|
||||
const tags = ['personality', 'principle', 'knowledge']
|
||||
|
||||
tags.forEach(tag => {
|
||||
const regex = new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>`, 'g')
|
||||
const match = regex.exec(content)
|
||||
if (match && match[1].trim()) {
|
||||
// 过滤掉@引用，只保留直接内容
|
||||
const directText = this.filterOutReferences(match[1])
|
||||
if (directText.trim()) {
|
||||
sections[tag] = directText
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
return sections
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 影响评估
|
||||
|
||||
### 修复收益
|
||||
- **功能完整性**：用户自定义角色能力完全恢复
|
||||
- **用户体验**：角色激活后获得预期的专业能力
|
||||
- **兼容性**：支持所有编写方式，向下兼容
|
||||
|
||||
### 修复成本
|
||||
- **开发工作量**：中等（主要在ActionCommand和相关解析逻辑）
|
||||
- **测试工作量**：中等（需要测试各种角色格式）
|
||||
- **风险评估**：低（主要是增强功能，不破坏现有逻辑）
|
||||
|
||||
## 🧪 测试用例
|
||||
|
||||
### 测试场景1：纯@引用角色
|
||||
```xml
|
||||
<role>
|
||||
<personality>@!thought://assistant</personality>
|
||||
<principle>@!execution://assistant</principle>
|
||||
</role>
|
||||
```
|
||||
**期望**：正常解析@引用
|
||||
|
||||
### 测试场景2：纯直接内容角色
|
||||
```xml
|
||||
<role>
|
||||
<personality># 直接编写的个性内容</personality>
|
||||
<principle># 直接编写的原则内容</principle>
|
||||
</role>
|
||||
```
|
||||
**期望**：正确提取直接内容
|
||||
|
||||
### 测试场景3：混合方式角色
|
||||
```xml
|
||||
<role>
|
||||
<personality>
|
||||
@!thought://base-personality
|
||||
|
||||
# 补充的个性特征
|
||||
- 额外特征1
|
||||
- 额外特征2
|
||||
</personality>
|
||||
</role>
|
||||
```
|
||||
**期望**：@引用 + 直接内容都被解析
|
||||
|
||||
## 📅 建议修复时间线
|
||||
- **阶段1**：问题确认和方案设计（已完成）
|
||||
- **阶段2**：核心解析逻辑实现（1-2天）
|
||||
- **阶段3**：测试用例编写和验证（1天）
|
||||
- **阶段4**：兼容性测试和文档更新（1天）
|
||||
|
||||
## 🔗 相关文件
|
||||
- `src/lib/core/pouch/commands/ActionCommand.js` - 主要修改文件
|
||||
- `src/lib/core/resource/resourceManager.js` - 可能需要增强DPML处理
|
||||
- `.promptx/resource/domain/internet-debater/internet-debater.role.md` - 受影响的测试案例
|
||||
- `src/tests/commands/ActionCommand.*.test.js` - 需要补充的测试
|
||||
|
||||
## ⚠️ 注意事项
|
||||
1. **保持向下兼容**：现有@引用方式不能受影响
|
||||
2. **性能考虑**：内容解析不应显著影响角色激活速度
|
||||
3. **内容去重**：避免@引用和直接内容的重复
|
||||
4. **错误处理**：DPML格式错误时的优雅降级
|
||||
|
||||
---
|
||||
|
||||
**报告人**：Claude Code
|
||||
**发现时间**：2025-06-11
|
||||
**优先级**：High
|
||||
**标签**：bug, role-parsing, user-experience, content-loss
|
||||
203
docs/issues/role-discovery-inconsistency.md
Normal file
203
docs/issues/role-discovery-inconsistency.md
Normal file
@ -0,0 +1,203 @@
|
||||
# 角色发现一致性问题
|
||||
|
||||
## 🔥 问题等级
|
||||
**中等优先级 (Medium Priority)**
|
||||
|
||||
## 📋 问题描述
|
||||
|
||||
用户自定义角色在创建后出现间歇性的"角色不存在"错误，表现为hello命令能发现角色，但action命令无法激活同一角色。重启MCP Server后问题消失。
|
||||
|
||||
## 🔍 问题详情
|
||||
|
||||
### 问题表现
|
||||
1. **创建新角色后** - `internet-empathy-master`角色文件已正确创建在`.promptx/resource/domain/`
|
||||
2. **hello命令正常** - `promptx_hello`能正确发现并显示新角色
|
||||
3. **action命令失败** - `promptx_action internet-empathy-master`提示"角色不存在"
|
||||
4. **重启后恢复** - 重启MCP Server后action命令立即可用
|
||||
|
||||
### 错误信息
|
||||
```
|
||||
❌ 角色 "internet-empathy-master" 不存在！
|
||||
|
||||
🔍 请使用以下命令查看可用角色：
|
||||
```bash
|
||||
pnpm start hello
|
||||
```
|
||||
|
||||
### 用户反馈
|
||||
> "我刚刚配置了一下，然后重启了 mcp 就可以了"
|
||||
|
||||
## 🔍 技术分析
|
||||
|
||||
### 当前架构分析
|
||||
|
||||
**MCP Server启动流程：**
|
||||
1. MCP Server启动时**不执行角色发现**（延迟初始化设计）
|
||||
2. 只有调用`promptx_hello`时才触发`SimplifiedRoleDiscovery.discoverAllRoles()`
|
||||
3. HelloCommand使用实例级缓存`this.roleRegistry`避免重复扫描
|
||||
4. ActionCommand通过懒加载HelloCommand实例复用缓存
|
||||
|
||||
**角色发现流程：**
|
||||
```javascript
|
||||
// HelloCommand.loadRoleRegistry()
|
||||
if (this.roleRegistry) {
|
||||
return this.roleRegistry // 实例级缓存
|
||||
}
|
||||
const allRoles = await this.discovery.discoverAllRoles()
|
||||
this.roleRegistry = {} // 缓存结果
|
||||
```
|
||||
|
||||
**ActionCommand角色查询：**
|
||||
```javascript
|
||||
// ActionCommand.getRoleInfo()
|
||||
if (!this.helloCommand) {
|
||||
this.helloCommand = new HelloCommand() // 懒加载新实例
|
||||
}
|
||||
return await this.helloCommand.getRoleInfo(roleId)
|
||||
```
|
||||
|
||||
### 问题假设分析
|
||||
|
||||
#### 假设1：实例级缓存不一致 ❌
|
||||
- **假设**：不同HelloCommand实例缓存状态不同
|
||||
- **反驳**：ActionCommand懒加载HelloCommand，应该使用相同的发现逻辑
|
||||
|
||||
#### 假设2：SimplifiedRoleDiscovery不稳定 ❓
|
||||
- **假设**：`Promise.allSettled`并行文件操作存在竞态条件
|
||||
- **可能性**：文件系统I/O操作的时序不确定性
|
||||
|
||||
#### 假设3：MCP Server状态管理问题 ❓
|
||||
- **假设**：MCP Server在处理多个请求时状态混乱
|
||||
- **可能性**：不同MCP工具调用之间存在状态污染
|
||||
|
||||
## 🧪 问题复现
|
||||
|
||||
### 复现步骤
|
||||
1. 启动MCP Server
|
||||
2. 创建新的用户角色文件（如`test-role.role.md`）
|
||||
3. 立即调用`promptx_hello` - 预期能看到新角色
|
||||
4. 立即调用`promptx_action test-role` - 可能失败
|
||||
5. 重启MCP Server
|
||||
6. 再次调用`promptx_action test-role` - 预期成功
|
||||
|
||||
### 复现条件
|
||||
- 角色文件在MCP Server运行期间创建
|
||||
- 立即尝试激活新创建的角色
|
||||
- 系统：macOS (用户报告环境)
|
||||
|
||||
## 🔍 调试数据需求
|
||||
|
||||
### 需要收集的日志
|
||||
使用`DEBUG=1`环境变量启用调试日志：
|
||||
|
||||
1. **HelloCommand调用日志**
|
||||
```
|
||||
[HelloCommand] getRoleInfo调用，角色ID: internet-empathy-master
|
||||
[HelloCommand] 注册表加载完成，包含角色: [...]
|
||||
[HelloCommand] 查找角色internet-empathy-master结果: 找到/未找到
|
||||
```
|
||||
|
||||
2. **SimplifiedRoleDiscovery日志**
|
||||
```
|
||||
[SimplifiedRoleDiscovery] 开始发现所有角色...
|
||||
[SimplifiedRoleDiscovery] 用户角色扫描完成，发现角色: [...]
|
||||
[SimplifiedRoleDiscovery] 检查角色目录: internet-empathy-master
|
||||
[SimplifiedRoleDiscovery] 角色文件是否存在: true/false
|
||||
```
|
||||
|
||||
3. **ActionCommand调用日志**
|
||||
```
|
||||
[ActionCommand] 开始激活角色: internet-empathy-master
|
||||
[ActionCommand] 创建新的HelloCommand实例 / 复用现有HelloCommand实例
|
||||
[ActionCommand] getRoleInfo结果: {...} / null
|
||||
```
|
||||
|
||||
## 💡 可能解决方案
|
||||
|
||||
### 方案1：添加缓存失效机制
|
||||
```javascript
|
||||
class HelloCommand {
|
||||
invalidateCache() {
|
||||
this.roleRegistry = null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 方案2：实时角色发现
|
||||
移除HelloCommand的实例级缓存，每次都重新扫描：
|
||||
```javascript
|
||||
async getRoleInfo(roleId) {
|
||||
// 移除缓存检查，直接执行发现
|
||||
const registry = await this.loadRoleRegistry(true) // 强制重新加载
|
||||
}
|
||||
```
|
||||
|
||||
### 方案3：文件系统监听
|
||||
监听`.promptx/resource/domain`目录变化，自动刷新缓存：
|
||||
```javascript
|
||||
const chokidar = require('chokidar')
|
||||
const watcher = chokidar.watch('.promptx/resource/domain')
|
||||
watcher.on('add', () => this.invalidateCache())
|
||||
```
|
||||
|
||||
### 方案4：全局角色注册表
|
||||
使用单例模式管理角色注册表，确保所有实例共享状态：
|
||||
```javascript
|
||||
class GlobalRoleRegistry {
|
||||
static instance = null
|
||||
static getInstance() {
|
||||
if (!this.instance) {
|
||||
this.instance = new GlobalRoleRegistry()
|
||||
}
|
||||
return this.instance
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 影响评估
|
||||
|
||||
### 影响范围
|
||||
- **用户体验**：新角色创建后无法立即使用，需要重启MCP Server
|
||||
- **开发效率**：角色开发和测试流程被中断
|
||||
- **系统可靠性**：间歇性错误难以预测和重现
|
||||
|
||||
### 影响程度
|
||||
- **频率**：新角色创建时100%触发
|
||||
- **严重性**：中等（有解决方案：重启MCP Server）
|
||||
- **用户反馈**：已有用户报告此问题
|
||||
|
||||
## 🔧 技术实现建议
|
||||
|
||||
### 推荐方案：方案1 + 方案2组合
|
||||
1. **短期**：移除HelloCommand缓存，改为每次实时发现（方案2）
|
||||
2. **长期**：实现智能缓存失效机制（方案1）
|
||||
|
||||
### 实现优先级
|
||||
1. **高优先级**：添加详细调试日志，收集实际出错的调试数据
|
||||
2. **中优先级**：实现缓存失效或实时发现机制
|
||||
3. **低优先级**：文件系统监听（增加系统复杂性）
|
||||
|
||||
## 📅 建议时间线
|
||||
- **阶段1**：问题确认和调试数据收集（1天）
|
||||
- **阶段2**：实现临时解决方案（移除缓存）（1天）
|
||||
- **阶段3**：设计长期解决方案（智能缓存）（2-3天）
|
||||
- **阶段4**：测试和验证（1天）
|
||||
|
||||
## 🔗 相关文件
|
||||
- `src/lib/core/pouch/commands/HelloCommand.js` - 角色注册表缓存逻辑
|
||||
- `src/lib/core/pouch/commands/ActionCommand.js` - 角色信息获取逻辑
|
||||
- `src/lib/core/resource/SimplifiedRoleDiscovery.js` - 角色发现算法
|
||||
- `docs/issues/role-content-parsing-incomplete.md` - 相关的角色解析问题
|
||||
|
||||
## ⚠️ 注意事项
|
||||
1. **性能平衡**：移除缓存可能影响性能，需要测试文件系统操作耗时
|
||||
2. **并发安全**：多个MCP请求并发时的角色发现一致性
|
||||
3. **错误处理**：文件系统操作失败时的优雅降级
|
||||
4. **跨平台兼容**：确保解决方案在不同操作系统上稳定工作
|
||||
|
||||
---
|
||||
|
||||
**报告人**：Claude Code
|
||||
**发现时间**：2025-06-11
|
||||
**优先级**：Medium
|
||||
**标签**：role-discovery, mcp-server, caching, user-experience, file-system
|
||||
Reference in New Issue
Block a user