@liangjie559567/ultrapower 5.5.2 → 5.5.3

package/docs/guides/tool-name-migration.md

@@ -0,0 +1,97 @@
+# Tool Name Migration Guide
+
+## Overview
+
+Starting from v5.6.0, all ultrapower tools use the `ultrapower:` prefix instead of underscore naming.
+
+**Legacy format:** `tool_name`
+**New format:** `ultrapower:tool_name`
+
+## Migration Timeline
+
+- **v5.6.0**: New prefix introduced, legacy names deprecated
+- **v6.0.0**: Legacy names will be removed
+
+## Affected Tools
+
+### LSP Tools
+- `lsp_hover` → `ultrapower:lsp_hover`
+- `lsp_goto_definition` → `ultrapower:lsp_goto_definition`
+- `lsp_find_references` → `ultrapower:lsp_find_references`
+- `lsp_document_symbols` → `ultrapower:lsp_document_symbols`
+- `lsp_workspace_symbols` → `ultrapower:lsp_workspace_symbols`
+- `lsp_diagnostics` → `ultrapower:lsp_diagnostics`
+- `lsp_diagnostics_directory` → `ultrapower:lsp_diagnostics_directory`
+- `lsp_servers` → `ultrapower:lsp_servers`
+- `lsp_prepare_rename` → `ultrapower:lsp_prepare_rename`
+- `lsp_rename` → `ultrapower:lsp_rename`
+- `lsp_code_actions` → `ultrapower:lsp_code_actions`
+- `lsp_code_action_resolve` → `ultrapower:lsp_code_action_resolve`
+
+### State Tools
+- `state_read` → `ultrapower:state_read`
+- `state_write` → `ultrapower:state_write`
+- `state_clear` → `ultrapower:state_clear`
+- `state_list_active` → `ultrapower:state_list_active`
+- `state_get_status` → `ultrapower:state_get_status`
+
+### Notepad Tools
+- `notepad_read` → `ultrapower:notepad_read`
+- `notepad_write_priority` → `ultrapower:notepad_write_priority`
+- `notepad_write_working` → `ultrapower:notepad_write_working`
+- `notepad_write_manual` → `ultrapower:notepad_write_manual`
+- `notepad_prune` → `ultrapower:notepad_prune`
+- `notepad_stats` → `ultrapower:notepad_stats`
+
+### Memory Tools
+- `project_memory_read` → `ultrapower:project_memory_read`
+- `project_memory_write` → `ultrapower:project_memory_write`
+- `project_memory_add_note` → `ultrapower:project_memory_add_note`
+- `project_memory_add_directive` → `ultrapower:project_memory_add_directive`
+
+### AST Tools
+- `ast_grep_search` → `ultrapower:ast_grep_search`
+- `ast_grep_replace` → `ultrapower:ast_grep_replace`
+
+### Other Tools
+- `python_repl` → `ultrapower:python_repl`
+- `trace_timeline` → `ultrapower:trace_timeline`
+- `trace_summary` → `ultrapower:trace_summary`
+
+## Automated Migration
+
+Use the migration script to update your codebase:
+
+```bash
+node scripts/migrate-tool-names.js [directory]
+```
+
+This will update tool references in `.ts`, `.js`, `.json`, and `.md` files.
+
+## Manual Migration
+
+If you prefer manual migration, search for tool names and replace them:
+
+```typescript
+// Before
+await client.callTool('state_read', { mode: 'team' });
+
+// After
+await client.callTool('ultrapower:state_read', { mode: 'team' });
+```
+
+## Backward Compatibility
+
+Legacy names still work in v5.6.x but will show deprecation warnings:
+
+```
+⚠️  DEPRECATED: Tool 'state_read' is deprecated since v5.6.0
+and will be removed in v6.0.0.
+Please use 'ultrapower:state_read' instead.
+```
+
+## Why This Change?
+
+1. **Namespace clarity**: Prevents conflicts with other MCP servers
+2. **Consistency**: Aligns with MCP naming conventions
+3. **Discoverability**: Makes ultrapower tools easily identifiable

package/docs/guides/troubleshooting-guide.md

@@ -0,0 +1,110 @@
+# 故障排查手册
+
+## 概述
+
+本手册帮助你快速诊断和解决常见问题。
+
+## 常见问题
+
+### 向导相关
+
+**问题：向导无法启动**
+- 检查网络连接
+- 清除浏览器缓存
+- 重启应用
+
+**问题：推荐结果不准确**
+- 提供更详细的任务描述
+- 检查历史数据是否正确
+- 尝试手动选择模式
+
+### 执行模式相关
+
+**问题：任务执行失败**
+- 查看错误日志：`/logs`
+- 检查依赖是否安装
+- 尝试使用 `executor` 模式
+
+**问题：执行超时**
+- 增加超时时间设置
+- 分解为更小的任务
+- 检查系统资源
+
+### 工作流相关
+
+**问题：工作流推荐不显示**
+- 确保有足够的历史数据
+- 检查推荐引擎是否启用
+- 重启应用
+
+**问题：模板无法应用**
+- 验证模板是否存在
+- 检查模板格式
+- 尝试重新创建模板
+
+## 诊断步骤
+
+### 第 1 步：收集信息
+```
+/diagnose
+```
+
+系统会收集：
+- 应用版本
+- 系统信息
+- 最近的错误日志
+- 配置信息
+
+### 第 2 步：查看日志
+```
+/logs --last 100
+```
+
+查看最近 100 条日志记录。
+
+### 第 3 步：重置状态
+```
+/reset --safe
+```
+
+安全重置应用状态（保留数据）。
+
+## 性能问题
+
+**症状：应用响应缓慢**
+
+检查清单：
+- [ ] 关闭不必要的后台任务
+- [ ] 清理临时文件
+- [ ] 检查磁盘空间
+- [ ] 重启应用
+
+**症状：内存占用过高**
+
+解决方案：
+- 减少并发任务数
+- 清理缓存
+- 重启应用
+
+## 数据恢复
+
+**丢失任务数据**
+```
+/recover --type tasks
+```
+
+**恢复工作流历史**
+```
+/recover --type workflow
+```
+
+**完全恢复**
+```
+/recover --full
+```
+
+## 获取帮助
+
+- 查看文档：`/help`
+- 联系支持：`/support`
+- 报告问题：`/report-issue`

package/docs/guides/v5.5.13-new-features.md

@@ -0,0 +1,234 @@
+# ultrapower v5.5.13 新功能指南
+
+## 概述
+
+v5.5.13 引入了 4 个重要的用户体验改进功能，帮助你快速选择最适合的执行模式和工作流。
+
+## 1. Wizard 交互式引导 (`/ultrapower:wizard`)
+
+### 功能说明
+
+通过 3 个问题引导用户选择最适合的执行模式。
+
+### 使用方法
+
+```bash
+/ultrapower:wizard
+```
+
+### 3 个引导问题
+
+1. **任务类型**: 单一任务 / 多个独立任务 / 复杂多步骤任务
+2. **项目规模**: 简单(1-3文件) / 中等(4-10文件) / 大型(10+文件)
+3. **团队协作**: 独立工作 / 需要并行协作
+
+### 推荐逻辑
+
+- 单一任务 + 简单规模 → `executor` agent
+- 多个独立任务 → `ultrawork` 并行执行
+- 复杂多步骤 → `autopilot` 自主执行
+- 需要协作 → `team` 模式
+
+### 示例
+
+```
+$ /ultrapower:wizard
+
+问题 1: 你的任务类型是什么?
+  1. 单一任务
+  2. 多个独立任务
+  3. 复杂多步骤任务
+选择: 3
+
+问题 2: 项目规模?
+  1. 简单 (1-3 文件)
+  2. 中等 (4-10 文件)
+  3. 大型 (10+ 文件)
+选择: 2
+
+问题 3: 需要团队协作吗?
+  1. 独立工作
+  2. 需要并行协作
+选择: 1
+
+推荐: 使用 autopilot 模式自主执行复杂任务
+```
+## 2. 工作流推荐引擎（中文支持）
+
+### 功能说明
+
+自动分析用户输入，识别意图并推荐最佳 agent/skill。
+
+### 7 种意图分类
+
+| 意图类型 | 中文关键词 | 英文关键词 | 优先级 |
+|---------|-----------|-----------|--------|
+| bug-fix | 修复/错误/问题/故障 | fix/bug/error/issue | 10 |
+| refactor | 重构/优化/改进 | refactor/cleanup | 9 |
+| review | 审查/检查/评审 | review/audit/check | 8 |
+| plan | 规划/设计/架构 | plan/design/architect | 7 |
+| explore | 探索/分析/调查 | explore/analyze | 6 |
+| feature-multiple | 添加.*多个/实现.*多个 | add multiple/implement several | 5 |
+| feature-single | 添加/实现/创建/构建 | add/implement/create | 1 |
+
+### 使用示例
+
+```bash
+# 中文输入
+"修复登录错误" → bug-fix → debugger agent
+"添加用户管理功能" → feature-single → executor agent
+"重构整个架构" → refactor → architect agent
+
+# 英文输入
+"fix authentication bug" → bug-fix → debugger agent
+"add user dashboard" → feature-single → executor agent
+```
+
+### 自动推荐流程
+
+1. 系统分析用户输入文本
+2. 匹配意图关键词（中英文）
+3. 根据优先级选择最高匹配
+4. 推荐对应 agent 或 skill
+5. 用户可接受或手动选择
+## 3. 任务模板库
+
+### 功能说明
+
+预定义的 5 个常见任务模板，快速启动标准化工作流。
+
+### 可用模板
+
+1. **feature-development**: 新功能开发完整流程
+   - 需求分析 → 设计 → 实现 → 测试 → 审查
+
+2. **bug-fix**: Bug 修复标准流程
+   - 问题诊断 → 根因分析 → 修复 → 验证 → 回归测试
+
+3. **code-review**: 代码审查检查清单
+   - 风格检查 → 质量审查 → 安全审查 → 性能审查
+
+4. **refactoring**: 重构工作流程
+   - 分析现状 → 设计方案 → 实现重构 → 测试验证
+
+5. **security-audit**: 安全审计检查点
+   - 漏洞扫描 → 信任边界审查 → 认证授权检查 → 报告生成
+
+### 集成方式
+
+Wizard 会根据用户回答自动应用对应模板。
+
+### 使用示例
+
+```bash
+# 通过 wizard 自动应用模板
+/ultrapower:wizard
+# 选择对应任务类型后自动加载模板
+
+# 或手动指定模板
+/ultrapower:autopilot --template feature-development
+```
+## 4. 故障排查手册
+
+### 功能说明
+
+智能错误匹配和解决方案推荐系统。
+
+### 支持的错误类型
+
+- TypeScript 类型错误
+- 文件系统权限错误
+- Hook 执行失败
+- Agent 超时
+- 状态文件损坏
+
+### 使用方法
+
+```bash
+/ultrapower:omc-doctor
+```
+
+### 故障排查文档位置
+
+- `docs/troubleshooting/common-errors.md`
+- `docs/troubleshooting/agent-timeouts.md`
+- `docs/troubleshooting/hook-failures.md`
+- `docs/troubleshooting/performance-issues.md`
+- `docs/troubleshooting/state-corruption.md`
+
+### 常见问题解决
+
+**问题**: Agent 执行超时
+**解决**: 检查 `.omc/state/` 中的状态文件，运行 `omc-doctor` 诊断
+
+**问题**: Hook 执行失败
+**解决**: 查看 `.omc/logs/` 中的执行日志，确认输入格式正确
+
+**问题**: 状态文件损坏
+**解决**: 运行 `omc-doctor --fix` 自动修复，或手动删除 `.omc/state/` 重新初始化
+## 升级说明
+
+### 从旧版本升级
+
+```bash
+npm install -g @liangjie559567/ultrapower@5.5.13
+```
+
+### 插件更新（Claude Code 用户）
+
+```bash
+claude plugin marketplace update ultrapower
+claude plugin uninstall ultrapower
+claude plugin install ultrapower
+```
+
+### 升级检查清单
+
+- [ ] 备份现有 `.omc/` 目录
+- [ ] 更新 ultrapower 到 v5.5.13
+- [ ] 运行 `omc-doctor` 验证环境
+- [ ] 测试 `/ultrapower:wizard` 功能
+- [ ] 查看新增文档
+
+## 快速开始
+
+### 第一次使用
+
+1. 运行 Wizard 了解推荐模式
+   ```bash
+   /ultrapower:wizard
+   ```
+
+2. 根据推荐选择执行方式
+
+3. 查看对应的任务模板
+
+### 常用命令
+
+```bash
+# 交互式引导
+/ultrapower:wizard
+
+# 故障诊断
+/ultrapower:omc-doctor
+
+# 查看状态
+/ultrapower:omc-status
+
+# 查看帮助
+/ultrapower:omc-help
+```
+
+## 相关资源
+
+- [完整 CHANGELOG](../../CHANGELOG.md)
+- [Wizard 用户指南](./wizard-user-guide.md)
+- [工作流推荐指南](./workflow-recommendation-guide.md)
+- [任务模板指南](./task-templates-guide.md)
+- [故障排查指南](./troubleshooting-guide.md)
+
+---
+
+**文档版本**: v5.5.13  
+**更新日期**: 2026-03-04  
+**语言**: 中文

package/docs/guides/wizard-user-guide.md

@@ -0,0 +1,85 @@
+# 交互式向导用户指南
+
+## 概述
+
+交互式向导帮助你在 2 分钟内选择最适合的执行模式。
+
+## 快速开始
+
+```
+/wizard
+```
+
+向导通过 3 个简单问题了解你的需求，然后推荐最优执行模式。
+
+## 问题详解
+
+### 第 1 问：你想做什么？
+
+| 选项 | 适用场景 | 示例 |
+|------|---------|------|
+| 实现单个功能 | 添加新功能或改进现有功能 | "添加用户登录"、"优化搜索性能" |
+| 实现多个功能 | 同时开发多个功能 | "构建完整用户系统"、"重构整个模块" |
+| 修复问题 | 修复 bug 或测试失败 | "修复登录失败"、"解决类型错误" |
+| 不确定，需要探索 | 还不清楚具体要做什么 | "优化性能"、"改进架构" |
+
+### 第 2 问：分支问题
+
+根据第 1 问的答案，向导会问不同的问题：
+
+**实现单个功能** → 任务复杂度？
+- 简单：修改 1-3 个文件，逻辑清晰
+- 复杂：涉及多个模块，需要架构设计
+
+**实现多个功能** → 功能是否独立？
+- 是：功能之间没有依赖，可以并行开发
+- 否：功能之间有依赖关系，需要协调
+
+**修复问题** → 问题范围？
+- 单个文件：问题定位明确，影响范围小
+- 多个文件：问题涉及多个模块或不确定位置
+
+**不确定，需要探索** → 需要规划吗？
+- 是：需要先分析和制定计划
+- 否：直接开始探索
+
+### 第 3 问：细化问题
+
+**需要持续执行直到完成？**
+- 是：不停止直到任务完全完成并验证通过
+- 否：完成基本实现即可
+
+**需要验证循环？**
+- 是：修复后需要反复测试验证
+- 否：修复一次即可
+
+## 执行模式速查表
+
+| 模式 | 适用场景 | 特点 |
+|------|---------|------|
+| executor | 单个文件修复、简单功能 | 直接实现，快速完成 |
+| ralph | 需要反复验证的任务 | 持续执行直到通过 |
+| autopilot | 复杂功能实现 | 自主规划和实现 |
+| ultrawork | 多个独立功能 | 最大并行度 |
+| team | 多个相关功能 | 协调式团队执行 |
+| plan | 不确定需求 | 先制定计划 |
+
+## 键盘快捷键
+
+| 快捷键 | 功能 |
+|--------|------|
+| 1-4 | 快速选择选项 |
+| b / back | 返回上一步 |
+| q / quit | 退出向导 |
+| ? | 查看当前问题的详细说明 |
+
+## 常见问题
+
+**Q: 如何返回上一步？**
+A: 输入 `b` 或 `back` 返回上一个问题。
+
+**Q: 如何退出向导？**
+A: 输入 `q` 或 `quit` 退出向导。
+
+**Q: 推荐的模式不适合我怎么办？**
+A: 选择"返回重新选择"或"手动选择"其他模式。

package/docs/guides/workflow-recommendation-guide.md

@@ -0,0 +1,97 @@
+# 智能工作流推荐引擎用户指南
+
+## 概述
+
+智能工作流推荐引擎根据你的项目历史、任务类型和执行模式偏好，自动推荐最优工作流。
+
+## 工作原理
+
+### 学习机制
+
+系统记录你的：
+- 执行模式选择历史
+- 任务完成时间
+- 成功率
+- 模式偏好
+
+### 推荐算法
+
+基于以下因素计算推荐分数：
+1. **历史成功率** (40%)：该模式在类似任务中的成功率
+2. **完成时间** (30%)：该模式的平均完成时间
+3. **用户偏好** (20%)：用户过去的选择倾向
+4. **任务相似度** (10%)：当前任务与历史任务的相似程度
+
+## 使用方式
+
+### 自动推荐
+
+系统在以下场景自动推荐：
+- 新建任务时
+- 任务类型变更时
+- 执行模式失败后
+
+### 手动查询
+
+```
+/workflow-recommend "你的任务描述"
+```
+
+## 推荐结果示例
+
+```
+🎯 基于你的历史数据，推荐工作流：
+
+1️⃣ ralph (匹配度 92%)
+   - 历史成功率: 95%
+   - 平均完成时间: 15 分钟
+   - 你过去 8 次选择了这个模式
+
+2️⃣ autopilot (匹配度 78%)
+   - 历史成功率: 88%
+   - 平均完成时间: 20 分钟
+
+3️⃣ ultrawork (匹配度 65%)
+   - 历史成功率: 82%
+   - 平均完成时间: 25 分钟
+```
+
+## 个性化设置
+
+### 查看推荐历史
+
+```
+/workflow-stats
+```
+
+显示：
+- 使用过的模式
+- 每个模式的成功率
+- 平均完成时间
+- 最常用模式
+
+### 重置学习数据
+
+```
+/workflow-reset
+```
+
+清除所有历史数据，重新开始学习。
+
+## 最佳实践
+
+1. **多尝试不同模式**：帮助系统学习你的偏好
+2. **提供详细任务描述**：提高推荐准确度
+3. **定期查看统计数据**：了解自己的工作模式
+4. **反馈推荐结果**：告诉系统推荐是否有帮助
+
+## 常见问题
+
+**Q: 推荐不准确怎么办？**
+A: 系统需要更多数据学习。继续使用，推荐会逐渐改进。
+
+**Q: 如何禁用自动推荐？**
+A: 在设置中关闭"自动推荐"选项。
+
+**Q: 推荐数据会被保存吗？**
+A: 是的，数据保存在本地项目中，不会上传。

package/docs/mcp/README.md

@@ -0,0 +1,82 @@
+# MCP Ecosystem Documentation
+
+ultrapower provides comprehensive MCP (Model Context Protocol) integration for extending Claude Code with custom tools and external AI providers.
+
+## Documentation Structure
+
+- [Overview](./overview.md) - MCP architecture and capabilities
+- [Server Guide](./server-guide.md) - Creating and deploying MCP servers
+- [Client Guide](./client-guide.md) - Consuming MCP tools in agents
+- [Configuration](./configuration.md) - Setup and environment variables
+- [Performance](./performance.md) - Benchmarks and optimization
+
+## Quick Links
+
+- [MCP Server Usage](../guides/mcp-server-usage.md) - Getting started
+- [Tool Reference](../REFERENCE.md) - Complete tool catalog
+- [Troubleshooting](../guides/troubleshooting-guide.md) - Common issues
+
+## MCP Servers in ultrapower
+
+### Built-in Servers
+
+1. **OMC Tools Server** (`bridge/mcp-server.cjs`)
+   - 32 custom tools (LSP, AST, State, Memory, Trace)
+   - Stdio transport
+   - Path security enforcement
+
+2. **Codex Server** (`bridge/codex-server.cjs`)
+   - OpenAI GPT-5.3-Codex integration
+   - Agent role routing
+   - Background job management
+
+3. **Gemini Server** (`bridge/gemini-server.cjs`)
+   - Google Gemini 3 Pro integration
+   - 1M context window
+   - Multi-file design support
+
+### External Servers
+
+ultrapower integrates with community MCP servers:
+- `sequential-thinking` - Structured reasoning
+- `software-planning-tool` - Task decomposition
+- `context7` - Documentation lookup
+
+## Key Features
+
+- **Tool Namespacing** - Automatic `mcp__<server>__<tool>` prefixing
+- **Security** - Path traversal protection, input sanitization
+- **Retry Logic** - Exponential backoff for transient failures
+- **Timeout Management** - Configurable per-tool timeouts
+- **Job Management** - Background execution with status tracking
+
+## Architecture
+
+```
+┌─────────────────┐
+│  Claude Code    │
+└────────┬────────┘
+         │
+    ┌────▼─────┐
+    │   MCP    │
+    │  Client  │
+    └────┬─────┘
+         │
+    ┌────▼──────────────────────┐
+    │  MCP Servers (stdio)      │
+    ├───────────────────────────┤
+    │ • OMC Tools               │
+    │ • Codex (OpenAI)          │
+    │ • Gemini (Google)         │
+    │ • Community Servers       │
+    └───────────────────────────┘
+```
+
+## Getting Started
+
+1. Install ultrapower: `/plugin install omc@ultrapower`
+2. Configure MCP servers in `.claude/mcp.json`
+3. Use tools via `mcp__<server>__<tool>` naming
+4. Monitor with `OMC_LOG_LEVEL=debug`
+
+See [Server Guide](./server-guide.md) for detailed setup instructions.