From 879a8a05985186aa284dbbb22c2598e9c04f04de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=B6=99=E5=AE=8F=E5=8F=A1?= Date: Thu, 28 Aug 2025 12:50:37 +0900 Subject: [PATCH] feat: Add complete Chinese documentation for SuperClaude Framework --- Docs/User-Guide-zh/agents.md | 819 +++++++++++++++++++++++ Docs/User-Guide-zh/commands.md | 305 +++++++++ Docs/User-Guide-zh/flags.md | 270 ++++++++ Docs/User-Guide-zh/mcp-servers.md | 273 ++++++++ Docs/User-Guide-zh/modes.md | 603 +++++++++++++++++ Docs/User-Guide-zh/session-management.md | 310 +++++++++ 6 files changed, 2580 insertions(+) create mode 100644 Docs/User-Guide-zh/agents.md create mode 100644 Docs/User-Guide-zh/commands.md create mode 100644 Docs/User-Guide-zh/flags.md create mode 100644 Docs/User-Guide-zh/mcp-servers.md create mode 100644 Docs/User-Guide-zh/modes.md create mode 100644 Docs/User-Guide-zh/session-management.md diff --git a/Docs/User-Guide-zh/agents.md b/Docs/User-Guide-zh/agents.md new file mode 100644 index 0000000..90a9029 --- /dev/null +++ b/Docs/User-Guide-zh/agents.md @@ -0,0 +1,819 @@ +# SuperClaude 智能体指南 🤖 + +SuperClaude 提供了 14 个领域专业智能体，Claude Code 可以调用它们获得专业知识。 + + +## 🧪 测试智能体激活 + +使用本指南之前，请验证智能体选择功能是否正常： + +```bash +# 测试手动智能体调用 +@agent-python-expert "explain decorators" +# 期望行为：Python 专家提供详细解释 + +# 测试安全智能体自动激活 +/sc:implement "JWT authentication" +# 期望行为：安全工程师应自动激活 + +# 测试前端智能体自动激活 +/sc:implement "responsive navigation component" +# 期望行为：前端架构师 + Magic MCP 应激活 + +# 测试系统分析 +/sc:troubleshoot "slow API performance" +# 期望行为：根因分析师 + 性能工程师激活 + +# 测试手动和自动结合 +/sc:analyze src/ +@agent-refactoring-expert "suggest improvements" +# 期望行为：分析后跟随重构建议 +``` + +**如果测试失败**：检查 `~/.claude/agents/` 中是否存在智能体文件，或重启 Claude Code 会话 + +## 核心概念 + +### 什么是 SuperClaude 智能体？ +**智能体**是专业的 AI 领域专家，以上下文指令的形式实现，用于修改 Claude Code 的行为。每个智能体都是 `SuperClaude/Agents/` 目录中精心制作的 `.md` 文件，包含领域特定的专业知识、行为模式和问题解决方法。 + +**重要提示**：智能体不是独立的 AI 模型或软件 - 它们是 Claude Code 读取的上下文配置，用于采用专门的行为。 + +### 两种使用智能体的方式 + +#### 1. 使用 @agent- 前缀手动调用 +```bash +# 直接调用特定智能体 +@agent-security "review authentication implementation" +@agent-frontend "design responsive navigation" +@agent-architect "plan microservices migration" +``` + +#### 2. 自动激活Auto-Activation（行为路由） +"自动激活"意味着 Claude Code 读取行为指令，根据您请求中的关键词和模式来调用相应的上下文。SuperClaude 提供行为指导原则，Claude 遵循这些原则路由到最合适的专业人员。 + +> **📝 智能体"自动激活"工作原理**: +> 智能体激活并非自动的系统逻辑——它是上下文文件中的行为指令。 +> 当文档说智能体"自动激活"时，意味着 Claude Code 读取指令，根据您请求中的关键词和模式 +> 调用特定的领域专业知识。这创造了智能路由的体验，同时保持底层机制的透明性。 + +```bash +# 这些命令自动激活相关智能体 +/sc:implement "JWT authentication" # → security-engineer 自动激活 +/sc:design "React dashboard" # → frontend-architect 自动激活 +/sc:troubleshoot "memory leak" # → performance-engineer 自动激活 +``` + +**MCP 服务器** 通过专业工具提供增强功能，如 Context7（文档）、Sequential（分析）、Magic（UI）、Playwright（测试）和 Morphllm（代码转换）。 + +**领域专家** 专注于狭窄的专业领域，提供比通用方法更深入、更准确的解决方案。 + +### 智能体选择规则 + +**优先级层次：** +1. **手动覆盖** - @agent-[name] 优先于自动激活 +2. **关键词** - 直接的领域术语触发主要智能体 +3. **文件类型** - 扩展名激活语言/框架专家 +4. **复杂度** - 多步骤任务调用协调智能体 +5. **上下文** - 相关概念触发互补智能体 + +**冲突解决：** +- 手动调用 → 指定的智能体优先 +- 多个匹配 → 多智能体协调 +- 不明确的上下文 → 需求分析师激活 +- 高复杂度 → 系统架构师监督 +- 质量关注 → 自动包含质量保证智能体 + +**选择决策树：** +``` +Task Analysis → +├─ Manual @agent-? → Use specified agent +├─ Single Domain? → Activate primary agent +├─ Multi-Domain? → Coordinate specialist agents +├─ Complex System? → Add system-architect oversight +├─ Quality Critical? → Include security + performance + quality agents +└─ Learning Focus? → Add learning-guide + technical-writer +``` + +## 快速开始示例 + +### 手动调用智能体 +```bash +# 使用 @agent- 前缀显式调用特定智能体 +@agent-python-expert "optimize this data processing pipeline" +@agent-quality-engineer "create comprehensive test suite" +@agent-technical-writer "document this API with examples" +@agent-socratic-mentor "explain this design pattern" +``` + +### 自动智能体协调 +```bash +# 触发自动激活的命令 +/sc:implement "JWT authentication with rate limiting" +# → 触发：security-engineer + backend-architect + quality-engineer + +/sc:design "accessible React dashboard with documentation" +# → 触发：frontend-architect + learning-guide + technical-writer + +/sc:troubleshoot "slow deployment pipeline with intermittent failures" +# → 触发：devops-architect + performance-engineer + root-cause-analyst + +/sc:audit "payment processing security vulnerabilities" +# → 触发：security-engineer + quality-engineer + refactoring-expert +``` + +### 结合手动和自动方式 +```bash +# 以命令开始（自动激活） +/sc:implement "user profile system" + +# 然后显式添加专家审查 +@agent-security "review the profile system for OWASP compliance" +@agent-performance-engineer "optimize database queries" +``` + +--- + +## SuperClaude 智能体团队 👥 + +### 架构和系统设计智能体 🏗️ + +### system-architect 🏢 +**专业领域：** 大规模分布式系统设计，专注于可扩展性和服务架构 + +**自动激活：** +- 关键词："架构"、"微服务"、"可扩展性"、"系统设计"、"分布式" +- 上下文：多服务系统、架构决策、技术选择 +- 复杂度：>5 个组件或跨领域集成需求 + +**能力：** +- 服务边界定义和微服务分解 +- 技术栈选择和集成策略 +- 可扩展性规划和性能架构 +- 事件驱动架构和消息模式 +- 数据流设计和系统集成 + +**示例：** +1. **电子商务平台**：为用户、产品、支付和通知服务设计微服务，采用事件源模式 +2. **实时分析**：高吞吐量数据接入架构，采用流处理和时间序列存储 +3. **多租户 SaaS**：具有租户隔离、共享基础架构和水平扩展策略的系统设计 + +### 成功标准 +- [ ] 响应中体现系统级思维 +- [ ] 提及服务边界和集成模式 +- [ ] 包含可扩展性和可靠性考虑 +- [ ] 提供技术栈建议 + +**验证：** `/sc:design "microservices platform"` 应该激活 system-architect +**测试：** 输出应包含服务分解和集成模式 +**检查：** 应与 devops-architect 协调处理基础架构问题 + +**最佳搭配：** devops-architect（基础架构）、performance-engineer（优化）、security-engineer（合规） + +--- + +### backend-architect ⚙️ +**专业领域**: 强大的服务端系统设计，重点关注 API 可靠性和数据完整性 + +**自动激活**: +- 关键词: "API", "backend", "server", "database", "REST", "GraphQL", "endpoint" +- 文件类型: API 规范、服务器配置、数据库架构 +- 上下文: 服务端逻辑、数据持久化、API 开发 + +**能力**: +- RESTful 和 GraphQL API 架构和设计模式 +- 数据库架构设计和查询优化策略 +- 身份验证、授权和安全实现 +- 错误处理、日志记录和监控集成 +- 缓存策略和性能优化 + +**示例**: +1. **用户管理 API**: JWT 身份验证与基于角色的访问控制和速率限制 +2. **支付处理**: PCI 合规的交易处理与幂等性和审计跟踪 +3. **内容管理**: 带有缓存、分页和实时通知的 RESTful APIs + +**最佳搭配**: security-engineer（身份验证/安全）、performance-engineer（优化）、quality-engineer（测试） + +--- + +### frontend-architect 🎨 +**专业领域**: 现代 Web 应用程序架构，重点关注可访问性和用户体验 + +**自动激活**: +- 关键词: "UI", "frontend", "React", "Vue", "Angular", "component", "accessibility", "responsive" +- 文件类型: .jsx, .vue, .ts (前端), .css, .scss +- 上下文: 用户界面开发、组件设计、客户端架构 + +**能力**: +- 组件架构和设计系统实现 +- 状态管理模式（Redux、Zustand、Pinia） +- 无障碍合规性（WCAG 2.1）和包容性设计 +- 性能优化和包分析 +- 渐进式 Web 应用和移动优先开发 + +**示例**: +1. **仪表板界面**: 具有实时更新和响应式网格布局的可访问数据可视化 +2. **表单系统**: 具有验证、错误处理和无障碍功能的复杂多步骤表单 +3. **设计系统**: 具有一致样式和交互模式的可重用组件库 + +**最佳搭配**: learning-guide（用户指导）、performance-engineer（优化）、quality-engineer（测试） + +--- + +### devops-architect 🚀 +**专业领域**: 基础设施自动化和部署管道设计，用于可靠的软件交付 + +**自动激活**: +- 关键词: "deploy", "CI/CD", "Docker", "Kubernetes", "infrastructure", "monitoring", "pipeline" +- 文件类型: Dockerfile、docker-compose.yml、k8s 清单、CI 配置 +- 上下文: 部署流程、基础设施管理、自动化 + +**能力**: +- 具有自动化测试和部署的 CI/CD 管道设计 +- 容器编排和 Kubernetes 集群管理 +- 使用 Terraform 和云平台的基础设施即代码 +- 监控、日志记录和可观测性堆栈实现 +- 安全扫描和合规自动化 + +**示例**: +1. **微服务部署**: 具有服务网格、自动扩展和蓝绿发布的 Kubernetes 部署 +2. **多环境管道**: 具有自动化测试、安全扫描和分阶段部署的 GitOps 工作流 +3. **监控堆栈**: 具有指标、日志、跟踪和警报系统的综合可观测性 + +**最佳搭配**: system-architect（基础设施规划）、security-engineer（合规）、performance-engineer（监控） + +### 质量与分析智能体 🔍 + +### security-engineer 🔒 +**专业领域**: 应用安全架构，重点关注威胁建模和漏洞预防 + +**自动激活**: +- 关键词: "security", "auth", "authentication", "vulnerability", "encryption", "compliance", "OWASP" +- 上下文: 安全审查、身份验证流程、数据保护需求 +- 风险指标: 支付处理、用户数据、API 访问、法规合规需求 + +**能力**: +- 威胁建模和攻击面分析 +- 安全身份验证和授权设计（OAuth、JWT、SAML） +- 数据加密策略和密钥管理 +- 漏洞评估和渗透测试指导 +- 安全合规（GDPR、HIPAA、PCI-DSS）实施 + +**示例**: +1. **OAuth 实现**: 具有令牌刷新和基于角色访问控制的安全多租户身份验证 +2. **API 安全**: 速率限制、输入验证、SQL 注入防护和安全头 +3. **数据保护**: 静态/传输加密、密钥轮转和隐私设计架构 + +**最佳搭配**: backend-architect（API 安全）、quality-engineer（安全测试）、root-cause-analyst（事件响应） + +--- + +### performance-engineer ⚡ +**专业领域**: 系统性能优化，重点关注可扩展性和资源效率 + +**自动激活**: +- 关键词: "performance", "slow", "optimization", "bottleneck", "latency", "memory", "CPU" +- 上下文: 性能问题、可扩展性担忧、资源约束 +- 指标: 响应时间 >500ms、高内存使用、低吞吐量 + +**能力**: +- 性能分析和瓶颈识别 +- 数据库查询优化和索引策略 +- 缓存实现（Redis、CDN、应用级别） +- 负载测试和容量规划 +- 内存管理和资源优化 + +**示例**: +1. **API 优化**: 通过缓存和查询优化将响应时间从 2 秒减少到 200ms +2. **数据库扩展**: 实现读副本、连接池和查询结果缓存 +3. **前端性能**: 包优化、延迟加载和 CDN 实现，实现 <3 秒加载时间 + +**最佳搭配**: system-architect（可扩展性）、devops-architect（基础设施）、root-cause-analyst（调试） + +--- + +### root-cause-analyst 🔍 +**专业领域**: 使用基于证据的分析和假设测试进行系统化问题调查 + +**自动激活**: +- 关键词: "bug", "issue", "problem", "debugging", "investigation", "troubleshoot", "error" +- 上下文: 系统故障、意外行为、复杂的多组件问题 +- 复杂性: 需要有方法的调查的跨系统问题 + +**能力**: +- 系统化调试方法和根本原因分析 +- 跨系统的错误关联和依赖关系映射 +- 日志分析和故障调查的模式识别 +- 复杂问题的假设形成和测试 +- 事件响应和事后分析程序 + +**示例**: +1. **数据库连接失败**: 通过连接池、网络超时和资源限制跟踪间歇性故障 +2. **支付处理错误**: 通过 API 日志、数据库状态和外部服务响应调查交易失败 +3. **性能降级**: 通过指标关联、资源使用和代码更改分析逐渐放慢 + +**最佳搭配**: performance-engineer（性能问题）、security-engineer（安全事件）、quality-engineer（测试失败） + +--- + +### quality-engineer ✅ +**专业领域**: 综合测试策略和质量保证，重点关注自动化和覆盖率 + +**自动激活**: +- 关键词: "test", "testing", "quality", "QA", "validation", "coverage", "automation" +- 上下文: 测试规划、质量门禁、验证需求 +- 质量担忧: 代码覆盖率 <80%、缺少测试自动化、质量问题 + +**能力**: +- 测试策略设计（单元、集成、端到端、性能测试） +- 测试自动化框架实现和 CI/CD 集成 +- 质量指标定义和监控（覆盖率、缺陷率） +- 边缘用例识别和边界测试场景 +- 无障碍测试和合规验证 + +**示例**: +1. **电子商务测试**: 涵盖用户流程、支付处理和库存管理的综合测试套件 +2. **API 测试**: REST/GraphQL API 的自动化合约测试、负载测试和安全测试 +3. **无障碍验证**: WCAG 2.1 合规测试，包括自动化和手动无障碍审计 + +**最佳搭配**: security-engineer（安全测试）、performance-engineer（负载测试）、frontend-architect（UI 测试） + +--- + +### refactoring-expert 🔧 +**专业领域**: 通过系统化重构和技术债务管理来改进代码质量 + +**自动激活**: +- 关键词: "refactor", "clean code", "technical debt", "SOLID", "maintainability", "code smell" +- 上下文: 遗留代码改进、架构更新、代码质量问题 +- 质量指标: 高复杂性、重复代码、较低的测试覆盖率 + +**能力**: +- SOLID 原则应用和设计模式实现 +- 代码异味识别和系统性消除 +- 遗留代码现代化策略和迁移规划 +- 技术债务评估和优先级框架 +- 代码结构改进和架构重构 + +**示例**: +1. **遗留现代化**: 将单体应用转换为具有改进可测试性的模块化架构 +2. **设计模式**: 为支付处理实现策略模式，以减少耦合并提高扩展性 +3. **代码清理**: 移除重复代码、改进命名约定和提取可重用组件 + +**最佳搭配**: system-architect（架构改进）、quality-engineer（测试策略）、python-expert（语言特定模式） + +### 专业化开发智能体 🎯 + +### python-expert 🐍 +**专业领域**: 生产就绪的 Python 开发，重点关注现代框架和性能 + +**自动激活**: +- 关键词: "Python", "Django", "FastAPI", "Flask", "asyncio", "pandas", "pytest" +- 文件类型: .py、requirements.txt、pyproject.toml、Pipfile +- 上下文: Python 开发任务、API 开发、数据处理、测试 + +**能力**: +- 现代 Python 架构模式和框架选择 +- 使用 asyncio 和并发 futures 的异步编程 +- 通过性能分析和算法改进进行性能优化 +- 使用 pytest、fixture 和测试自动化的测试策略 +- 使用 pip、poetry 和 Docker 的包管理和部署 + +**示例**: +1. **FastAPI 微服务**: 具有 Pydantic 验证、依赖注入和 OpenAPI 文档的高性能异步 API +2. **数据管道**: 基于 Pandas 的 ETL，具有错误处理、日志记录和大数据集的并行处理 +3. **Django 应用**: 具有自定义用户模型、API 端点和综合测试覆盖的全栈 Web 应用 + +**最佳搭配**: backend-architect（API 设计）、quality-engineer（测试）、performance-engineer（优化） + +--- + +### requirements-analyst 📝 +**专业领域**: 通过系统化利益相关者分析进行需求发现和规范开发 + +**自动激活**: +- 关键词: "requirements", "specification", "PRD", "user story", "functional", "scope", "stakeholder" +- 上下文: 项目启动、不明确的需求、范围定义需求 +- 复杂性: 多利益相关者项目、不明确的目标、相互冲突的需求 + +**能力**: +- 通过利益相关者访谈和研讨会进行需求引出 +- 具有接受标准和完成定义的用户故事编写 +- 功能和非功能规范文档编制 +- 利益相关者分析和需求优先级框架 +- 范围管理和变更控制流程 + +**示例**: +1. **产品需求文档**: 金融科技移动应用的综合 PRD，包括用户画像、功能规范和成功指标 +2. **API 规范**: 支付处理 API 的详细需求，包括错误处理、安全和性能标准 +3. **迁移需求**: 遗留系统现代化需求，包括数据迁移、用户培训和回滚程序 + +**最佳搭配**: system-architect（技术可行性）、technical-writer（文档）、learning-guide（用户指导） + +### 沟通与学习智能体 📚 + +### technical-writer 📚 +**专业领域**: 技术文档和沟通，重点关注受众分析和清晰性 + +**自动激活**: +- 关键词: "documentation", "readme", "API docs", "user guide", "technical writing", "manual" +- 上下文: 文档请求、API 文档、用户指南、技术解释 +- 文件类型: .md、.rst、API 规范、文档文件 + +**能力**: +- 技术文档架构和信息设计 +- 受众分析和面向不同技能水平的内容定位 +- 具有工作示例和集成指导的 API 文档 +- 具有分步程序和故障排除的用户指南创建 +- 无障碍标准应用和包容性语言使用 + +**示例**: +1. **API 文档**: 具有身份验证、端点、示例和 SDK 集成指南的综合 REST API 文档 +2. **用户手册**: 具有截图、故障排除和 FAQ 部分的分步安装和配置指南 +3. **技术规范**: 具有图表、数据流和实现细节的系统架构文档 + +**最佳搭配**: requirements-analyst（规范清晰度）、learning-guide（教育内容）、frontend-architect（UI 文档） + +--- + +### learning-guide 🎓 +**专业领域**: 教育内容设计和渐进式学习，重点关注技能开发和指导 + +**自动激活**: +- 关键词: "explain", "learn", "tutorial", "beginner", "teaching", "education", "training" +- 上下文: 教育请求、概念解释、技能开发、学习路径 +- 复杂性: 需要分步骤分解和渐进理解的复杂主题 + +**能力**: +- 具有渐进技能开发的学习路径设计 +- 通过类比和示例进行复杂概念解释 +- 具有实践练习的交互式教程创建 +- 技能评估和能力评估框架 +- 指导策略和个性化学习方法 + +**示例**: +1. **编程教程**: 具有实践练习、代码示例和渐进复杂性的交互式 React 教程 +2. **概念解释**: 通过实际示例、视觉图表和练习解释数据库规范化 +3. **技能评估**: 具有实际项目和反馈的全栈开发综合评估框架 + +**最佳搭配**: technical-writer（教育文档）、frontend-architect（交互学习）、requirements-analyst（学习目标） + +--- + +## 智能体协调与集成 🤝 + +### 协调模式 + +**架构团队**: +- **全栈开发**: frontend-architect + backend-architect + security-engineer + quality-engineer +- **系统设计**: system-architect + devops-architect + performance-engineer + security-engineer +- **遗留现代化**: refactoring-expert + system-architect + quality-engineer + technical-writer + +**质量团队**: +- **安全审计**: security-engineer + quality-engineer + root-cause-analyst + requirements-analyst +- **性能优化**: performance-engineer + system-architect + devops-architect + root-cause-analyst +- **测试策略**: quality-engineer + security-engineer + performance-engineer + frontend-architect + +**沟通团队**: +- **文档项目**: technical-writer + requirements-analyst + learning-guide + domain experts +- **学习平台**: learning-guide + frontend-architect + technical-writer + quality-engineer +- **API 文档**: backend-architect + technical-writer + security-engineer + quality-engineer + +### MCP 服务器集成 + +**通过 MCP 服务器增强能力**: +- **Context7**: 为所有架构师和专家提供官方文档模式 +- **Sequential**: 为 root-cause-analyst、system-architect、performance-engineer 提供多步骤分析 +- **Magic**: 为 frontend-architect 提供 UI 生成，为 learning-guide 提供交互内容 +- **Playwright**: 为 quality-engineer 提供浏览器测试，为 frontend-architect 提供无障碍验证 +- **Morphllm**: 为 refactoring-expert 提供代码转换，为 python-expert 提供批量更改 +- **Serena**: 为所有智能体提供项目内存，在会话间保持上下文 + +### 智能体激活故障排除 + +## 故障排除 + +获取故障排除帮助，请参阅： +- [常见问题](../Reference/common-issues.md) - 常见问题的快速修复 +- [故障排除指南](../Reference/troubleshooting.md) - 综合问题解决 + +### 常见问题 +- **无智能体激活**: 使用领域关键词："security"、"performance"、"frontend" +- **选择了错误的智能体**: 检查智能体文档中的触发关键词 +- **智能体过多**: 将关键词聚焦在主要领域或使用 `/sc:focus [领域]` +- **智能体不协调**: 增加任务复杂性或使用多领域关键词 +- **智能体专业知识不匹配**: 使用更具体的技术术语 + +### 即时修复 +- **强制激活智能体**: 在请求中使用明确的领域关键词 +- **重置智能体选择**: 重启 Claude Code 会话以重置智能体状态 +- **检查智能体模式**: 查看智能体文档中的触发关键词 +- **测试基本激活**: 尝试 `/sc:implement "security auth"` 测试 security-engineer + +### 特定智能体故障排除 + +**无安全智能体：** +```bash +# 问题：安全问题未触发 security-engineer +# 快速修复：使用明确的安全关键词 +"实现身份验证" # 通用 - 可能不会触发 +"实现 JWT 身份验证安全" # 明确 - 触发 security-engineer +"使用加密的安全用户登录" # 安全聚焦 - 触发 security-engineer +``` + +**无性能智能体：** +```bash +# 问题：性能问题未触发 performance-engineer +# 快速修复：使用性能相关术语 +"让它更快" # 模糊 - 可能不会触发 +"优化缓慢的数据库查询" # 具体 - 触发 performance-engineer +"减少 API 延迟和瓶颈" # 性能聚焦 - 触发 performance-engineer +``` + +**无架构智能体：** +```bash +# 问题：系统设计未触发架构智能体 +# 快速修复：使用架构关键词 +"构建一个应用" # 通用 - 触发基本智能体 +"设计微服务架构" # 具体 - 触发 system-architect +"可扩展的分布式系统设计" # 架构聚焦 - 触发 system-architect +``` + +**错误的智能体组合：** +```bash +# 问题：在后端任务中获得前端智能体 +# 快速修复：使用领域特定术语 +"创建用户界面" # 可能触发 frontend-architect +"创建 REST API 端点" # 具体 - 触发 backend-architect +"实现服务端身份验证" # 后端聚焦 - 触发 backend-architect +``` + +### 支持级别 + +**快速修复：** +- 从智能体触发表中使用明确的领域关键词 +- 尝试重启 Claude Code 会话 +- 聚焦在单一领域以避免混淆 + +**详细帮助：** +- 查看[常见问题指南](../Reference/common-issues.md)了解智能体安装问题 +- 查看目标智能体的触发关键词 + +**专家支持：** +- 使用 `SuperClaude install --diagnose` +- 查看[诊断参考指南](../Reference/diagnostic-reference.md)进行协调分析 + +**社区支持：** +- 在 [GitHub Issues](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues) 报告问题 +- 包括预期与实际智能体激活的示例 + +### 成功验证 + +应用智能体修复后，请测试： +- [ ] 领域特定请求激活正确的智能体（security → security-engineer） +- [ ] 复杂任务触发多智能体协调（3+ 智能体） +- [ ] 智能体专业知识匹配任务需求（API → backend-architect） +- [ ] 质量智能体在适当时自动包含（安全、性能、测试） +- [ ] 响应显示领域专业知识和专业化知识 + +## 快速故障排除（遗留） +- **无智能体激活** → 使用领域关键词："security"、"performance"、"frontend" +- **错误的智能体** → 检查智能体文档中的触发关键词 +- **智能体过多** → 将关键词聚焦在主要领域 +- **智能体不协调** → 增加任务复杂性或使用多领域关键词 + +**智能体未激活？** +1. **检查关键词**: 使用领域特定术语（例如，对于 security-engineer 使用 "authentication" 而不是 "login"） +2. **添加上下文**: 包含文件类型、框架或特定技术 +3. **增加复杂性**: 多领域问题会触发更多智能体 +4. **使用示例**: 引用与智能体专业知识匹配的具体场景 + +**智能体过多？** +- 将关键词聚焦在主要领域需求上 +- 使用 `/sc:focus [领域]` 限制范围 +- 从特定智能体开始，按需扩展 + +**错误的智能体？** +- 查看智能体文档中的触发关键词 +- 为目标领域使用更具体的术语 +- 添加明确的需求或约束 + +## 快速参考 📋 + +### 智能体触发查找 + +| 触发类型 | 关键词/模式 | 激活的智能体 | +|-------------|-------------------|------------------| +| **安全** | "auth", "security", "vulnerability", "encryption" | security-engineer | +| **性能** | "slow", "optimization", "bottleneck", "latency" | performance-engineer | +| **前端** | "UI", "React", "Vue", "component", "responsive" | frontend-architect | +| **后端** | "API", "server", "database", "REST", "GraphQL" | backend-architect | +| **测试** | "test", "QA", "validation", "coverage" | quality-engineer | +| **DevOps** | "deploy", "CI/CD", "Docker", "Kubernetes" | devops-architect | +| **架构** | "architecture", "microservices", "scalability" | system-architect | +| **Python** | ".py", "Django", "FastAPI", "asyncio" | python-expert | +| **问题** | "bug", "issue", "debugging", "troubleshoot" | root-cause-analyst | +| **代码质量** | "refactor", "clean code", "technical debt" | refactoring-expert | +| **文档** | "documentation", "readme", "API docs" | technical-writer | +| **学习** | "explain", "tutorial", "beginner", "teaching" | learning-guide | +| **需求** | "requirements", "PRD", "specification" | requirements-analyst | + +### 命令-智能体映射 + +| 命令 | 主要智能体 | 支持智能体 | +|---------|----------------|-------------------| +| `/sc:implement` | Domain architects (frontend, backend) | security-engineer, quality-engineer | +| `/sc:analyze` | quality-engineer, security-engineer | performance-engineer, root-cause-analyst | +| `/sc:troubleshoot` | root-cause-analyst | Domain specialists, performance-engineer | +| `/sc:improve` | refactoring-expert | quality-engineer, performance-engineer | +| `/sc:document` | technical-writer | Domain specialists, learning-guide | +| `/sc:design` | system-architect | Domain architects, requirements-analyst | +| `/sc:test` | quality-engineer | security-engineer, performance-engineer | +| `/sc:explain` | learning-guide | technical-writer, domain specialists | + +### 有效的智能体组合 + +**开发工作流**: +- Web 应用: frontend-architect + backend-architect + security-engineer + quality-engineer + devops-architect +- API 开发: backend-architect + security-engineer + technical-writer + quality-engineer +- 数据平台: python-expert + performance-engineer + security-engineer + system-architect + +**分析工作流**: +- 安全审计: security-engineer + quality-engineer + root-cause-analyst + technical-writer +- 性能调查: performance-engineer + root-cause-analyst + system-architect + devops-architect +- 遗留评估: refactoring-expert + system-architect + quality-engineer + security-engineer + technical-writer + +**沟通工作流**: +- 技术文档: technical-writer + requirements-analyst + domain experts + learning-guide +- 教育内容: learning-guide + technical-writer + frontend-architect + quality-engineer + +## 最佳实践 💡 + +### 入门（简单方法） + +**自然语言优先：** +1. **描述目标**: 使用包含领域特定关键词的自然语言 +2. **信任自动激活**: 让系统自动路由到适当的智能体 +3. **从模式中学习**: 观察不同请求类型激活的智能体 +4. **迭代和优化**: 添加具体性以吸引额外的专家智能体 + +### 优化智能体选择 + +**有效的关键词使用：** +- **具体 > 通用**: 对于 security-engineer 使用 "authentication" 而不是 "login" +- **技术术语**: 包含框架名称、技术和具体挑战 +- **上下文线索**: 提及文件类型、项目范围和复杂性指标 +- **质量关键词**: 添加 "security"、"performance"、"accessibility" 以实现全面覆盖 + +**请求优化示例：** +```bash +# 通用（有限的智能体激活） +"修复登录功能" + +# 优化（多智能体协调） +"实现具有速率限制和无障碍合规的安全 JWT 身份验证" +# → 触发: security-engineer + backend-architect + frontend-architect + quality-engineer +``` + +### 常见用法模式 + +**开发工作流：** +```bash +# 全栈功能开发 +/sc:implement "具有实时通知的响应式用户仪表板" +# → frontend-architect + backend-architect + performance-engineer + +# 带文档的 API 开发 +/sc:create "带有综合文档的支付处理 REST API" +# → backend-architect + security-engineer + technical-writer + quality-engineer + +# 性能优化调查 +/sc:troubleshoot "影响用户体验的数据库查询缓慢" +# → performance-engineer + root-cause-analyst + backend-architect +``` + +**分析工作流：** +```bash +# 安全评估 +/sc:analyze "身份验证系统的 GDPR 合规漏洞" +# → security-engineer + quality-engineer + requirements-analyst + +# 代码质量审查 +/sc:review "遗留代码库的现代化机会" +# → refactoring-expert + system-architect + quality-engineer + technical-writer + +# 学习和解释 +/sc:explain "带实践示例的微服务模式" +# → system-architect + learning-guide + technical-writer +``` + +### 高级智能体协调 + +**多领域项目：** +- **从广泛开始**: 从系统级关键词开始以吸引架构智能体 +- **添加具体性**: 包含领域特定需求以激活专家智能体 +- **质量集成**: 自动包含安全、性能和测试视角 +- **文档包含**: 添加学习或文档需求以实现全面覆盖 + +**智能体选择故障排除：** + +**问题：错误的智能体激活** +- 解决方案：使用更具体的领域术语 +- 示例："数据库优化" → performance-engineer + backend-architect + +**问题：智能体不够** +- 解决方案：增加复杂性指标和跨领域关键词 +- 示例：向请求添加 "security"、"performance"、"documentation" + +**问题：智能体过多** +- 解决方案：使用具体技术术语聚焦于主要领域 +- 示例：使用 "/sc:focus backend" 来限制范围 + +### 质量驱动开发 + +**安全优先方法：** +始终在开发请求中包含安全考虑，以在领域专家之外自动吸引 security-engineer。 + +**性能集成：** +包含性能关键词（"fast"、"efficient"、"scalable"）以确保从一开始就有 performance-engineer 的协调。 + +**无障碍合规：** +使用 "accessible"、"WCAG" 或 "inclusive" 在前端开发中自动包含无障碍验证。 + +**文档文化：** +向请求添加 "documented"、"explained" 或 "tutorial" 以自动包含 technical-writer 和知识转移。 + +--- + +## 理解智能体智能 🧠 + +### 使智能体高效的因素 + +**领域专业知识**: 每个智能体都具有专业知识模式、行为方法和针对其领域的问题解决方法。 + +**上下文激活**: 智能体分析请求上下文，而不仅仅是关键词，以确定相关性和参与程度。 + +**协作智能**: 多智能体协调产生的协同结果超越了单个智能体的能力。 + +**自适应学习**: 智能体选择根据请求模式和成功的协调结果不断改进。 + +### 智能体与传统 AI + +**传统方法**: 单个 AI 以不同的专业知识水平处理所有领域 +**智能体方法**: 专业专家以深度领域知识和聚焦问题解决进行协作 + +**优点**: +- 在领域特定任务中更高的准确性 +- 更复杂的问题解决方法 +- 通过专家审查实现更好的质量保证 +- 协调的多视角分析 + +### 信任系统，理解模式 + +**期望什么**: +- 自动路由到适当的领域专家 +- 复杂任务的多智能体协调 +- 通过自动包含 QA 智能体实现质量集成 +- 通过教育智能体激活的学习机会 + +**不用担心什么**: +- 手动选择或配置智能体 +- 复杂的路由规则或智能体管理 +- 智能体配置或协调 +- 微管理智能体交互 + +--- + +## 相关资源 📚 + +### 基本文档 +- **[命令指南](commands.md)** - 掌握触发最优智能体协调的 SuperClaude 命令 +- **[MCP 服务器](mcp-servers.md)** - 通过专业化工具集成增强智能体能力 +- **[会话管理](session-management.md)** - 具有持久智能体上下文的长期工作流 + +### 高级用法 +- **[行为模式](modes.md)** - 用于增强智能体协调的上下文优化 +- **[入门指南](../Getting-Started/quick-start.md)** - 智能体优化的专家技巧 +- **[示例食谱](../Reference/examples-cookbook.md)** - 实际的智能体协调模式 + +### 开发资源 +- **[技术架构](../Developer-Guide/technical-architecture.md)** - 理解 SuperClaude 的智能体系统设计 +- **[贡献指南](../Developer-Guide/contributing-code.md)** - 扩展智能体能力和协调模式 + +--- + +## 您的智能体之旅 🚀 + +**第 1 周：自然使用** +从自然语言描述开始。注意哪些智能体会激活以及原因。在不过度思考过程的情况下建立对关键词模式的直觉。 + +**第 2-3 周：模式识别** +观察智能体协调模式。理解复杂性和领域关键词如何影响智能体选择。开始优化请求措辞以实现更好的协调。 + +**第 2 个月+：专家协调** +掌握触发最优智能体组合的多领域请求。利用故障排除技巧进行有效的智能体选择。使用高级模式处理复杂工作流。 + +**SuperClaude 优势：** +体验 14 个专业 AI 专家协调响应的威力，所有这一切都通过简单的自然语言请求实现。无需配置，无需管理，只有随您的需求而扩展的智能协作。 + +🎯 **准备体验智能智能体协调？从 `/sc:implement` 开始，发现专业 AI 协作的魔力。** \ No newline at end of file diff --git a/Docs/User-Guide-zh/commands.md b/Docs/User-Guide-zh/commands.md new file mode 100644 index 0000000..c03171d --- /dev/null +++ b/Docs/User-Guide-zh/commands.md @@ -0,0 +1,305 @@ +# SuperClaude 命令指南 + +SuperClaude 为 Claude Code 提供 21 个命令：用于工作流的 `/sc:*` 命令和用于专家的 `@agent-*`。 + +## 命令类型 + +| 类型 | 使用位置 | 格式 | 示例 | +|------|------------|--------|---------| +| **斜杠命令** | Claude Code | `/sc:[command]` | `/sc:implement "feature"` | +| **智能体** | Claude Code | `@agent-[name]` | `@agent-security "review"` | +| **安装命令** | 终端 | `SuperClaude [command]` | `SuperClaude install` | + +## 快速测试 +```bash +# 终端：验证安装 +python3 -m SuperClaude --version +# Claude Code CLI 验证：claude --version + +# Claude Code：测试命令 +/sc:brainstorm "test project" # 应该询问发现性问题 +/sc:analyze README.md # 应该提供分析 +``` + +**工作流**：`/sc:brainstorm "idea"` → `/sc:implement "feature"` → `/sc:test` + +## 🎯 理解 SuperClaude 命令 + +## SuperClaude 如何工作 + +SuperClaude 提供行为上下文文件，Claude Code 通过读取这些文件来采用专门的行为。当您键入 `/sc:implement` 时，Claude Code 读取 `implement.md` 上下文文件并遵循其行为指令。 + +**SuperClaude 命令不是由软件执行的** - 它们是上下文触发器，通过读取框架中的专门指令文件来修改 Claude Code 的行为。 + +### 命令类型： +- **斜杠命令** (`/sc:*`)：触发工作流模式和行为模式 +- **智能体调用** (`@agent-*`)：手动激活特定领域专家 +- **标志** (`--think`、`--safe-mode`)：修改命令行为和深度 + +### 上下文机制： +1. **用户输入**：您输入 `/sc:implement "auth system"` +2. **上下文加载**：Claude Code 读取 `~/.claude/SuperClaude/Commands/implement.md` +3. **行为采用**：Claude 运用专业知识进行工具选择和验证 +4. **增强输出**：带有安全考虑和最佳实践的结构化实现 + +**关键要点**：这通过上下文管理而不是传统的软件执行来创建复杂的开发工作流。 + +### 安装命令 vs 使用命令 + +**🖥️ 终端命令** （实际 CLI 软件）： +- `SuperClaude install` - 安装框架组件 +- `SuperClaude update` - 更新现有安装 +- `SuperClaude uninstall` - 卸载框架安装 +- `python3 -m SuperClaude --version` - 检查安装状态 + +**💬 Claude Code 命令** （上下文触发器）： +- `/sc:brainstorm` - 激活需求发现上下文 +- `/sc:implement` - 激活特性开发上下文 +- `@agent-security` - 激活安全专家上下文 +- 所有命令仅在 Claude Code 聊天界面中工作 + + +> **快速开始**：尝试 `/sc:brainstorm "your project idea"` → `/sc:implement "feature name"` → `/sc:test` 体验核心工作流。 + +## 🧪 Testing Your Setup + +### 🖥️ 终端验证（在终端/CMD 中运行） +```bash +# 验证 SuperClaude 是否正常工作（主要方法） +python3 -m SuperClaude --version +# 示例输出：SuperClaude 4.0.8 + +# Claude Code CLI 版本检查 +claude --version + +# 检查已安装的组件 +python3 -m SuperClaude install --list-components | grep mcp +# 示例输出：显示已安装的 MCP 组件 +``` + +### 💬 Claude Code 测试（在 Claude Code 聊天中输入） +``` +# 测试基本 /sc: 命令 +/sc:brainstorm "test project" +# 示例行为：开始交互式需求发现 + +# 测试命令帮助 +/sc:help +# 示例行为：显示可用命令列表 +``` + +**如果测试失败**：检查 [安装指南](../Getting-Started/installation.md) 或 [故障排除](#troubleshooting) + +### 📝 Command Quick Reference + +| Command Type | Where to Run | Format | Purpose | Example | +|-------------|--------------|--------|---------|----------| +| **🖥️ 安装** | 终端/CMD | `SuperClaude [command]` | 设置和维护 | `SuperClaude install` | +| **🔧 配置** | 终端/CMD | `python3 -m SuperClaude [command]` | 高级配置 | `python3 -m SuperClaude --version` | +| **💬 斜杠命令** | Claude Code | `/sc:[command]` | 工作流自动化 | `/sc:implement "feature"` | +| **🤖 智能体调用** | Claude Code | `@agent-[name]` | 手动专家激活 | `@agent-security "review"` | +| **⚡ 增强标志** | Claude Code | `/sc:[command] --flags` | 行为修改 | `/sc:analyze --think-hard` | + +> **记住**：所有 `/sc:` 命令和 `@agent-` 调用都在 Claude Code 聊天中工作，而不是在您的终端中。它们触发 Claude Code 从 SuperClaude 框架中读取特定的上下文文件。 + +## 目录 + +- [基本命令](#essential-commands) - 从这里开始（8 个核心命令） +- [常用工作流](#common-workflows) - 有效的命令组合 +- [完整命令参考](#full-command-reference) - 所有 21 个命令按类别组织 +- [故障排除](#troubleshooting) - 常见问题和解决方案 +- [命令索引](#command-index) - 按类别查找命令 + +--- + +## 基本命令 + +**立即提高生产力的核心工作流命令：** + +### `/sc:brainstorm` - 项目发现 +**目的**：交互式需求发现和项目规划 +**语法**：`/sc:brainstorm "您的想法"` `[--strategy systematic|creative]` + +**使用案例**： +- 新项目规划：`/sc:brainstorm "e-commerce platform"` +- 特性探索：`/sc:brainstorm "user authentication system"` +- 问题解决：`/sc:brainstorm "slow database queries"`` + +### `/sc:implement` - 功能开发 +**目的**: 通过智能专家路由进行全栈功能实现 +**语法**: `/sc:implement "feature description"` `[--type frontend|backend|fullstack] [--focus security|performance]` + +**使用场景**: +- 身份验证: `/sc:implement "JWT login system"` +- UI 组件: `/sc:implement "responsive dashboard"` +- APIs: `/sc:implement "REST user endpoints"` +- 数据库: `/sc:implement "user schema with relationships"` + +### `/sc:analyze` - 代码评估 +**目的**: 跨质量、安全性和性能的综合代码分析 +**语法**: `/sc:analyze [path]` `[--focus quality|security|performance|architecture]` + +**使用场景**: +- 项目健康: `/sc:analyze .` +- 安全审计: `/sc:analyze --focus security` +- 性能评审: `/sc:analyze --focus performance` + +### `/sc:troubleshoot` - 问题诊断 +**目的**: 系统化问题诊断与根本原因分析 +**语法**: `/sc:troubleshoot "问题描述"` `[--type build|runtime|performance]` + +**使用场景**: +- 运行时错误: `/sc:troubleshoot "登录时出现500错误"` +- 构建失败: `/sc:troubleshoot --type build` +- 性能问题: `/sc:troubleshoot "页面加载缓慢"` + +### `/sc:test` - 质量保证 +**目的**: 全面测试与覆盖率分析 +**语法**: `/sc:test` `[--type unit|integration|e2e] [--coverage] [--fix]` + +**使用场景**: +- 完整测试套件: `/sc:test --coverage` +- 单元测试: `/sc:test --type unit --watch` +- 端到端验证: `/sc:test --type e2e` + +### `/sc:improve` - 代码增强 +**目的**: 应用系统化的代码改进和优化 +**语法**: `/sc:improve [path]` `[--type performance|quality|security] [--preview]` + +**使用场景**: +- 常规改进: `/sc:improve src/` +- 性能优化: `/sc:improve --type performance` +- 安全加固: `/sc:improve --type security` + +### `/sc:document` - 文档生成 +**目的**: 为代码和API生成全面的文档 +**语法**: `/sc:document [path]` `[--type api|user-guide|technical] [--format markdown|html]` + +**使用场景**: +- API文档: `/sc:document --type api` +- 用户指南: `/sc:document --type user-guide` +- 技术文档: `/sc:document --type technical` + +### `/sc:workflow` - 实现规划 +**目的**: 从需求生成结构化的实现计划 +**语法**: `/sc:workflow "功能描述"` `[--strategy agile|waterfall] [--format markdown]` + +**使用场景**: +- 功能规划: `/sc:workflow "用户身份验证"` +- 冲刺规划: `/sc:workflow --strategy agile` +- 架构规划: `/sc:workflow "微服务迁移"` + +--- + +## 常用工作流 + +**经过验证的命令组合：** + +### 新项目设置 +```bash +/sc:brainstorm "项目概念" # 定义需求 +/sc:design "系统架构" # 创建技术设计 +/sc:workflow "实现计划" # 制定开发路线图 +``` + +### 功能开发 +```bash +/sc:implement "功能名称" # 构建功能 +/sc:test --coverage # 通过测试验证 +/sc:document --type api # 生成文档 +``` + +### 代码质量改进 +```bash +/sc:analyze --focus quality # 评估当前状态 +/sc:improve --preview # 预览改进 +/sc:test --coverage # 验证变更 +``` + +### Bug调查 +```bash +/sc:troubleshoot "问题描述" # 诊断问题 +/sc:analyze --focus problem-area # 深度分析 +/sc:improve --fix --safe-mode # 应用针对性修复 +``` + +## 完整命令参考 + +### 开发命令 +| 命令 | 目的 | 最适用于 | +|---------|---------|----------| +| **workflow** | 实现规划 | 项目路线图，冲刺规划 | +| **implement** | 功能开发 | 全栈功能，API开发 | +| **build** | 项目编译 | CI/CD，生产构建 | +| **design** | 系统架构 | API规范，数据库模式 | + +### 分析命令 +| 命令 | 目的 | 最适用于 | +|---------|---------|----------| +| **analyze** | 代码评估 | 质量审计，安全评审 | +| **troubleshoot** | 问题诊断 | Bug调查，性能问题 | +| **explain** | 代码解释 | 学习，代码评审 | + +### 质量命令 +| 命令 | 目的 | 最适用于 | +|---------|---------|----------| +| **improve** | 代码增强 | 性能优化，重构 | +| **cleanup** | 技术债务 | 清理无用代码，组织整理 | +| **test** | 质量保证 | 测试自动化，覆盖率分析 | +| **document** | 文档生成 | API文档，用户指南 | + +### 项目管理 +| 命令 | 目的 | 最适用于 | +|---------|---------|----------| +| **estimate** | 项目估算 | 时间线规划，资源分配 | +| **task** | 任务管理 | 复杂工作流，任务跟踪 | +| **spawn** | 元编排 | 大型项目，并行执行 | + +### 实用工具命令 +| 命令 | 目的 | 最适用于 | +|---------|---------|----------| +| **git** | 版本控制 | 提交管理，分支策略 | +| **index** | 命令发现 | 探索功能，查找命令 | + +### 会话命令 +| 命令 | 目的 | 最适用于 | +|---------|---------|----------| +| **load** | 上下文加载 | 会话初始化，项目启用 | +| **save** | 会话持久化 | 检查点，上下文保存 | +| **reflect** | 任务验证 | 进度评估，完成验证 | +| **select-tool** | 工具优化 | 性能优化，工具选择 | + +--- + +## 命令索引 + +**按功能分类：** +- **规划**: brainstorm, design, workflow, estimate +- **开发**: implement, build, git +- **分析**: analyze, troubleshoot, explain +- **质量**: improve, cleanup, test, document +- **管理**: task, spawn, load, save, reflect +- **工具**: index, select-tool + +**按复杂度分类：** +- **初学者**: brainstorm, implement, analyze, test +- **中级**: workflow, design, improve, document +- **高级**: spawn, task, select-tool, reflect + +## 故障排除 + +**命令问题：** +- **命令未找到**: 验证安装: `python3 -m SuperClaude --version` +- **无响应**: 重启 Claude Code 会话 +- **处理延迟**: 使用 `--no-mcp` 测试不使用 MCP 服务器 + +**快速修复：** +- 重置会话: `/sc:load` 重新初始化 +- 检查状态: `SuperClaude install --list-components` +- 获取帮助: [故障排除指南](../Reference/troubleshooting.md) + +## 下一步 + +- [标志指南](flags.md) - 控制命令行为 +- [智能体指南](agents.md) - 专家激活 +- [示例手册](../Reference/examples-cookbook.md) - 真实使用模式 \ No newline at end of file diff --git a/Docs/User-Guide-zh/flags.md b/Docs/User-Guide-zh/flags.md new file mode 100644 index 0000000..36f5a13 --- /dev/null +++ b/Docs/User-Guide-zh/flags.md @@ -0,0 +1,270 @@ +# SuperClaude 标志指南 🏁 + +**大多数标志会自动激活** - Claude Code 读取行为指令，根据您请求中的关键词和模式来调用适当的上下文。 + +## 基本自动激活标志（90% 的使用案例） + +### 核心分析标志 +| 标志 | 何时激活 | 作用 | +|------|---------------|--------------| +| `--think` | 5+ 个文件或复杂分析 | 标准结构化分析（约 4K 令牌）| +| `--think-hard` | 架构分析、系统依赖关系 | 深度分析（约 10K 令牌）配合增强工具 | +| `--ultrathink` | 关键系统重设计、遗留系统现代化 | 最大深度分析（约 32K 令牌）配合所有工具 | + +### MCP 服务器标志 +| 标志 | 服务器 | 目的 | 自动触发 | +|------|---------|---------|---------------| +| `--c7` / `--context7` | Context7 | 官方文档、框架模式 | 库导入、框架问题 | +| `--seq` / `--sequential` | Sequential | 多步推理、调试 | 复杂调试、系统设计 | +| `--magic` | Magic | UI 组件生成 | `/ui` 命令、前端关键词 | +| `--play` / `--playwright` | Playwright | 浏览器测试、E2E 验证 | 测试请求、视觉验证 | +| `--morph` / `--morphllm` | Morphllm | 批量转换、模式编辑 | 批量操作、样式强制执行 | +| `--serena` | Serena | 项目内存、符号操作 | 符号操作、大型代码库 | + +### 行为模式标志 +| 标志 | 何时激活 | 作用 | +|------|---------------|--------------| +| `--brainstorm` | 模糊请求、探索关键词 | 协作发现思维模式 | +| `--introspect` | 自我分析、错误恢复 | 透明地展现推理过程 | +| `--task-manage` | >3 步骤、复杂范围 | 通过委托进行协调 | +| `--orchestrate` | 多工具操作、性能需求 | 优化工具选择和并行执行 | +| `--token-efficient` / `--uc` | 上下文 >75%、效率需求 | 符号增强通信，减少 30-50% 令牌使用 | + +### 执行控制标志 +| 标志 | 何时激活 | 作用 | +|------|---------------|--------------| +| `--loop` | "improve"、"polish"、"refine" 关键词 | 迭代增强循环 | +| `--safe-mode` | 生产环境，>85% 资源使用 | 最大验证，保守执行 | +| `--validate` | 风险 >0.7，生产环境 | 执行前风险评估 | +| `--delegate` | >7 个目录或 >50 个文件 | 子智能体并行处理 | + +## 特定命令标志 + +### 分析命令标志 (`/sc:analyze`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--focus` | 针对特定领域 | `security`, `performance`, `quality`, `architecture` | +| `--depth` | 分析彻底程度 | `quick`, `deep` | +| `--format` | 输出格式 | `text`, `json`, `report` | + +### 构建命令标志 (`/sc:build`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--type` | 构建配置 | `dev`, `prod`, `test` | +| `--clean` | 构建前清理 | 布尔值 | +| `--optimize` | 启用优化 | 布尔值 | +| `--verbose` | 详细输出 | 布尔值 | + +### 设计命令标志 (`/sc:design`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--type` | 设计目标 | `architecture`, `api`, `component`, `database` | +| `--format` | 输出格式 | `diagram`, `spec`, `code` | + +### 解释命令标志 (`/sc:explain`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--level` | 复杂度级别 | `basic`, `intermediate`, `advanced` | +| `--format` | 解释风格 | `text`, `examples`, `interactive` | +| `--context` | 领域上下文 | 任何领域（如 `react`、`security`）| + +### 改进命令标志 (`/sc:improve`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--type` | 改进焦点 | `quality`, `performance`, `maintainability`, `style`, `security` | +| `--safe` | 保守方法 | 布尔值 | +| `--interactive` | 用户指导 | 布尔值 | +| `--preview` | 显示但不执行 | 布尔值 | + +### 任务命令标志 (`/sc:task`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--strategy` | 任务方法 | `systematic`, `agile`, `enterprise` | +| `--parallel` | 并行执行 | 布尔值 | +| `--delegate` | 子智能体协调 | 布尔值 | + +### 工作流命令标志 (`/sc:workflow`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--strategy` | 工作流方法 | `systematic`, `agile`, `enterprise` | +| `--depth` | 分析深度 | `shallow`, `normal`, `deep` | +| `--parallel` | 并行协调 | 布尔值 | + +### 故障排除命令标志 (`/sc:troubleshoot`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--type` | 问题类别 | `bug`, `build`, `performance`, `deployment` | +| `--trace` | 包含跟踪分析 | 布尔值 | +| `--fix` | 执行修复 | 布尔值 | + +### 清理命令标志 (`/sc:cleanup`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--type` | 清理目标 | `code`, `imports`, `files`, `all` | +| `--safe` / `--aggressive` | 清理强度 | 布尔值 | +| `--interactive` | 用户指导 | 布尔值 | +| `--preview` | 显示但不执行 | 布尔值 | + +### 估算命令标志 (`/sc:estimate`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--type` | 估算焦点 | `time`, `effort`, `complexity` | +| `--unit` | 时间单位 | `hours`, `days`, `weeks` | +| `--breakdown` | 详细分解 | 布尔值 | + +### 索引命令标志 (`/sc:index`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--type` | 索引目标 | `docs`, `api`, `structure`, `readme` | +| `--format` | 输出格式 | `md`, `json`, `yaml` | + +### 反思命令标志 (`/sc:reflect`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--type` | 反思范围 | `task`, `session`, `completion` | +| `--analyze` | 包含分析 | 布尔值 | +| `--validate` | 验证完整性 | 布尔值 | + +### 生成命令标志 (`/sc:spawn`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--strategy` | 协调方法 | `sequential`, `parallel`, `adaptive` | +| `--depth` | 分析深度 | `normal`, `deep` | + +### Git 命令标志 (`/sc:git`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--smart-commit` | 生成提交消息 | 布尔值 | +| `--interactive` | 引导操作 | 布尔值 | + +### 工具选择命令标志 (`/sc:select-tool`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--analyze` | 工具分析 | 布尔值 | +| `--explain` | 解释选择 | 布尔值 | + +### 测试命令标志 (`/sc:test`) +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--coverage` | 包含覆盖率 | 布尔值 | +| `--type` | 测试类型 | `unit`, `integration`, `e2e` | +| `--watch` | 监视模式 | 布尔值 | + +## 高级控制标志 + +### 范围和焦点 +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--scope` | 分析边界 | `file`, `module`, `project`, `system` | +| `--focus` | 领域定向 | `performance`, `security`, `quality`, `architecture`, `accessibility`, `testing` | + +### 执行控制 +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--concurrency [n]` | 控制并行操作 | 1-15 | +| `--iterations [n]` | 改进循环 | 1-10 | +| `--all-mcp` | 启用所有 MCP 服务器 | 布尔值 | +| `--no-mcp` | 仅使用本地工具 | 布尔值 | + +### 系统标志（SuperClaude 安装） +| 标志 | 目的 | 值 | +|------|---------|--------| +| `--verbose` / `-v` | 详细日志 | 布尔值 | +| `--quiet` / `-q` | 静默输出 | 布尔值 | +| `--dry-run` | 模拟操作 | 布尔值 | +| `--force` | 跳过检查 | 布尔值 | +| `--yes` / `-y` | 自动确认 | 布尔值 | +| `--install-dir` | 目标目录 | 路径 | +| `--legacy` | 使用传统脚本 | 布尔值 | +| `--version` | 显示版本 | 布尔值 | +| `--help` | 显示帮助 | 布尔值 | + +## 常用使用模式 + +### 前端开发 +```bash +/sc:implement "responsive dashboard" --magic --c7 +/sc:design component-library --type component --format code +/sc:test ui-components/ --magic --play +/sc:improve legacy-ui/ --magic --morph --validate +``` + +### 后端开发 +```bash +/sc:analyze api/ --focus performance --seq --think +/sc:design payment-api --type api --format spec +/sc:troubleshoot "API timeout" --type performance --trace +/sc:improve auth-service --type security --validate +``` + +### 大型项目 +```bash +/sc:analyze . --ultrathink --all-mcp --safe-mode +/sc:workflow enterprise-system --strategy enterprise --depth deep +/sc:cleanup . --type all --safe --interactive +/sc:estimate "migrate to microservices" --type complexity --breakdown +``` + +### 质量和维护 +```bash +/sc:improve src/ --type quality --safe --interactive +/sc:cleanup imports --type imports --preview +/sc:reflect --type completion --validate +/sc:git commit --smart-commit +``` + +## 标志交互 + +### 兼容组合 +- `--think` + `--c7`：带文档的分析 +- `--magic` + `--play`：UI 生成带测试 +- `--serena` + `--morph`：项目内存带转换 +- `--safe-mode` + `--validate`：最大安全性 +- `--loop` + `--validate`：带验证的迭代改进 + +### 冲突标志 +- `--all-mcp` vs 单独的 MCP 标志（使用其中之一） +- `--no-mcp` vs 任何 MCP 标志（--no-mcp 获胜） +- `--safe` vs `--aggressive`（清理强度） +- `--quiet` vs `--verbose`（输出级别） + +### 自动启用关系 +- `--safe-mode` 自动启用 `--uc` 和 `--validate` +- `--ultrathink` 自动启用所有 MCP 服务器 +- `--think-hard` 自动启用 `--seq` + `--c7` +- `--magic` 触发以 UI 为中心的智能体 + +## 标志故障排除 + +### 常见问题 +- **工具过多**：使用 `--no-mcp` 仅用本地工具测试 +- **操作太慢**：添加 `--uc` 压缩输出 +- **验证阻塞**：在开发中使用 `--validate` 而不是 `--safe-mode` +- **上下文压力**：在 >75% 使用率时自动激活 `--token-efficient` + +### 调试标志 +```bash +/sc:analyze . --verbose # 显示决策逻辑和标志激活 +/sc:select-tool "操作" --explain # 解释工具选择过程 +/sc:reflect --type session --analyze # 审查当前会话决策 +``` + +### 快速修复 +```bash +/sc:analyze . --help # 显示命令的可用标志 +/sc:analyze . --no-mcp # 仅本地执行 +/sc:cleanup . --preview # 显示将被清理的内容 +``` + +## 标志优先级规则 + +1. **安全第一**：`--safe-mode` > `--validate` > 优化标志 +2. **显式覆盖**：用户标志 > 自动检测 +3. **深度层次**：`--ultrathink` > `--think-hard` > `--think` +4. **MCP 控制**：`--no-mcp` 覆盖所有单独的 MCP 标志 +5. **范围优先级**：system > project > module > file + +## 相关资源 +- [命令指南](commands.md) - 使用这些标志的命令 +- [MCP 服务器指南](mcp-servers.md) - 理解 MCP 标志激活 +- [会话管理](session-management.md) - 在持久会话中使用标志 \ No newline at end of file diff --git a/Docs/User-Guide-zh/mcp-servers.md b/Docs/User-Guide-zh/mcp-servers.md new file mode 100644 index 0000000..46ee59e --- /dev/null +++ b/Docs/User-Guide-zh/mcp-servers.md @@ -0,0 +1,273 @@ +# SuperClaude MCP 服务器指南 🔌 + +## 概览 + +MCP（模型上下文协议）服务器通过专业工具扩展 Claude Code 的能力。SuperClaude 集成了 6 个 MCP 服务器，并为 Claude 提供指令，告诉它何时根据您的任务激活它们。 + +### 🔍 现实检查 +- **MCP 服务器是什么**：提供附加工具的外部 Node.js 进程 +- **它们不是什么**：内置的 SuperClaude 功能 +- **激活如何工作**：Claude 读取指令，根据上下文使用适当的服务器 +- **它们提供什么**：扩展 Claude Code 本地能力的真实工具 + +**核心服务器：** +- **context7**：官方库文档和模式 +- **sequential-thinking**：多步推理和分析 +- **magic**：现代 UI 组件生成 +- **playwright**：浏览器自动化和 E2E 测试 +- **morphllm-fast-apply**：基于模式的代码转换 +- **serena**：语义代码理解和项目内存 + +## 快速开始 + +**设置验证**：MCP 服务器会自动激活。有关安装和故障排除，请参阅 [安装指南](../Getting-Started/installation.md) 和 [故障排除](../Reference/troubleshooting.md)。 + +**自动激活逻辑：** + +| 请求包含 | 激活的服务器 | +|-----------------|------------------| +| 库导入、API 名称 | **context7** | +| `--think`、调试 | **sequential-thinking** | +| `component`、`UI`、前端 | **magic** | +| `test`、`e2e`、`browser` | **playwright** | +| 多文件编辑、重构 | **morphllm-fast-apply** | +| 大型项目、会话 | **serena** | + +## 服务器详情 + +### context7 📚 +**目的**：官方库文档访问 +**触发器**：导入语句、框架关键词、文档请求 +**要求**：Node.js 16+，无需 API 密钥 + +```bash +# 自动激活 +/sc:implement "React authentication system" +# → 提供官方 React 模式 + +# 手动激活 +/sc:analyze auth-system/ --c7 +``` + +### sequential-thinking 🧠 +**目的**：结构化多步推理和系统分析 +**触发器**：复杂调试、`--think` 标志、架构分析 +**要求**：Node.js 16+，无需 API 密钥 + +```bash +# 自动激活 +/sc:troubleshoot "API performance issues" +# → 启用系统性根因分析 + +# 手动激活 +/sc:analyze --think-hard architecture/ +``` + +### magic ✨ +**目的**：从 21st.dev 模式生成现代 UI 组件 +**触发器**：UI 请求、`/ui` 命令、组件开发 +**要求**：Node.js 16+，TWENTYFIRST_API_KEY + +```bash +# 自动激活 +/sc:implement "responsive dashboard component" +# → 使用现代模式生成可访问的 UI + +# API 密钥设置 +export TWENTYFIRST_API_KEY="your_key_here" +``` + +### playwright 🎭 +**目的**：真实浏览器自动化和 E2E 测试 +**触发器**：浏览器测试、E2E 场景、视觉验证 +**要求**：Node.js 16+，无需 API 密钥 + +```bash +# 自动激活 +/sc:test --type e2e "user login flow" +# → 启用浏览器自动化测试 + +# 手动激活 +/sc:validate "accessibility compliance" --play +``` + +### morphllm-fast-apply 🔄 +**目的**：高效的基于模式的代码转换 +**触发器**：多文件编辑、重构、框架迁移 +**要求**：Node.js 16+，MORPH_API_KEY + +```bash +# 自动激活 +/sc:improve legacy-codebase/ --focus maintainability +# → 在文件中应用一致的模式 + +# API 密钥设置 +export MORPH_API_KEY="your_key_here" +``` + +### serena 🧭 +**目的**：带有项目内存的语义代码理解 +**触发器**：符号操作、大型代码库、会话管理 +**要求**：Python 3.9+、uv 包管理器，无需 API 密钥 + +```bash +# 自动激活 +/sc:load existing-project/ +# → 构建项目理解和内存 + +# 手动激活 +/sc:refactor "extract UserService" --serena +``` + +## 配置 + +**MCP 配置文件 (`~/.claude.json`)：** +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + }, + "sequential-thinking": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] + }, + "magic": { + "command": "npx", + "args": ["@21st-dev/magic"], + "env": {"TWENTYFIRST_API_KEY": "${TWENTYFIRST_API_KEY}"} + }, + "playwright": { + "command": "npx", + "args": ["@playwright/mcp@latest"] + }, + "morphllm-fast-apply": { + "command": "npx", + "args": ["@morph-llm/morph-fast-apply"], + "env": {"MORPH_API_KEY": "${MORPH_API_KEY}"} + }, + "serena": { + "command": "uv", + "args": ["run", "serena", "start-mcp-server", "--context", "ide-assistant"], + "cwd": "$HOME/.claude/serena" + } + } +} +``` + +## 使用模式 + +**服务器控制：** +```bash +# 启用特定服务器 +/sc:analyze codebase/ --c7 --seq + +# 禁用所有 MCP 服务器 +/sc:implement "simple function" --no-mcp + +# 启用所有服务器 +/sc:design "complex architecture" --all-mcp +``` + +**多服务器协调：** +```bash +# 全栈开发 +/sc:implement "e-commerce checkout" +# → Sequential：工作流分析 +# → Context7：支付模式 +# → Magic：UI 组件 +# → Serena：代码组织 +# → Playwright：E2E 测试 +``` + +## 故障排除 + +**常见问题：** +- **无服务器连接**：检查 Node.js：`node --version`（需要 v16+） +- **Context7 失败**：清除缓存：`npm cache clean --force` +- **Magic/Morphllm 错误**：在没有 API 密钥时是预期的（付费服务） +- **服务器超时**：重启 Claude Code 会话 + +**快速修复：** +```bash +# 重置连接 +# 重启 Claude Code 会话 + +# 检查依赖 +node --version # 应该显示 v16+ + +# 不使用 MCP 测试 +/sc:command --no-mcp + +# 检查配置 +ls ~/.claude.json +``` + +**API 密钥配置：** +```bash +# 用于 Magic 服务器（UI 生成所需） +export TWENTYFIRST_API_KEY="your_key_here" + +# 用于 Morphllm 服务器（批量转换所需） +export MORPH_API_KEY="your_key_here" + +# 添加到 shell 配置文件以保持持久 +echo 'export TWENTYFIRST_API_KEY="your_key"' >> ~/.bashrc +echo 'export MORPH_API_KEY="your_key"' >> ~/.bashrc +``` + +**环境变量使用：** +- ✅ `TWENTYFIRST_API_KEY` - Magic MCP 服务器功能所需 +- ✅ `MORPH_API_KEY` - Morphllm MCP 服务器功能所需 +- ❌ 文档中的其他环境变量 - 仅作示例，框架中不使用 +- 📝 两者都是付费服务 API 密钥，框架在没有它们的情况下也可以工作 + +## 服务器组合 + +**无 API 密钥（免费）**： +- context7 + sequential-thinking + playwright + serena + +**1 个 API 密钥**： +- 添加 magic 用于专业 UI 开发 + +**2 个 API 密钥**： +- 添加 morphllm-fast-apply 用于大规模重构 + +**常见工作流：** +- **学习**：context7 + sequential-thinking +- **Web 开发**：magic + context7 + playwright +- **企业重构**：serena + morphllm + sequential-thinking +- **复杂分析**：sequential-thinking + context7 + serena + +## 集成 + +**与 SuperClaude 命令：** +- 分析命令自动使用 Sequential + Serena +- 实现命令使用 Magic + Context7 +- 测试命令使用 Playwright + Sequential + +**与行为模式：** +- 头脑风暴模式：Sequential 用于发现 +- 任务管理：Serena 用于持久化 +- 编排模式：最佳服务器选择 + +**性能控制：** +- 基于系统负载的自动资源管理 +- 并发控制：`--concurrency N` (1-15) +- 在约束条件下基于优先级的服务器选择 + +## 相关资源 + +**必读资料：** +- [命令指南](commands.md) - 激活 MCP 服务器的命令 +- [快速开始指南](../Getting-Started/quick-start.md) - MCP 设置指南 + +**高级使用：** +- [行为模式](modes.md) - 模式-MCP 协调 +- [智能体指南](agents.md) - 智能体-MCP 集成 +- [会话管理](session-management.md) - Serena 工作流 + +**技术参考：** +- [示例手册](../Reference/examples-cookbook.md) - MCP 工作流模式 +- [技术架构](../Developer-Guide/technical-architecture.md) - 集成详情 \ No newline at end of file diff --git a/Docs/User-Guide-zh/modes.md b/Docs/User-Guide-zh/modes.md new file mode 100644 index 0000000..4eccb0b --- /dev/null +++ b/Docs/User-Guide-zh/modes.md @@ -0,0 +1,603 @@ +# SuperClaude 行为模式指南 🧠 + +## ✅ 快速验证 +使用 `/sc:` 命令测试模式 - 它们会根据任务复杂性自动激活。有关完整命令参考，请参阅 [命令指南](commands.md)。 + +## 快速参考表 + +| 模式 | 目的 | 自动触发 | 关键行为 | 最适合 | +|------|---------|---------------|---------------|---------------| +| **🧠 头脑风暴** | 交互式发现 | "brainstorm"、"maybe"、模糊请求 | 苏格拉底式问题、需求发掘 | 新项目规划、不明确需求 | +| **🔍 内省** | 元认知分析 | 错误恢复、"分析推理" | 透明思维标记 (🤔, 🎯, 💡) | 调试、学习、优化 | +| **📋 任务管理** | 复杂协调 | >3 步骤、>2 目录 | 阶段分解、内存持久化 | 多步操作、项目管理 | +| **🎯 编排** | 智能工具选择 | 多工具操作、高资源使用 | 最优工具路由、并行执行 | 复杂分析、性能优化 | +| **⚡ 令牌效率** | 压缩通信 | 高上下文使用、`--uc` 标志 | 符号系统，预计减少 30-50% 令牌 | 资源约束、大型操作 | + + +--- + +## 入门指南（2 分钟概览） + +**模式通过行为指令激活** - Claude Code 读取上下文文件，根据您的任务模式和复杂性来决定采用哪种模式行为。 + +**快速示例：** +```bash +# 自动激活示例 +/sc:brainstorm "mobile app" # → 苏格拉底式发现问题 +/sc:implement "authentication system" # → 多阶段协调 +"--uc analyze large-codebase/" # → 压缩符号输出 +``` + +**何时使用手动标志：** +- 需要特定行为：`--brainstorm`、`--introspect`、`--uc` +- 为学习/调试而覆盖自动检测 +- 针对特定约束进行优化（内存、时间、清晰度） + +--- + +## 模式详情 + +### 🧠 头脑风暴模式 - 交互式发现 + +**目的**：通过协作发现将模糊的想法转化为结构化的需求。 + +**自动激活触发器：** +- 模糊的项目请求："我想构建..."、"正在考虑创建..." +- 探索关键词：brainstorm、explore、discuss、figure out、not sure +- 不确定指示器："maybe"、"possibly"、"could we" +- 手动标志：`--brainstorm`、`--bs` + +**行为变化：** +- **苏格拉底式提问**：提出探性问题以发掘隐藏需求 +- **非预设性方法**：避免假设，让您引导发现方向 +- **协作伙伴关系**：在探索中与您合作，而不是指导性咨询 +- **需求综合**：将见解转化为结构化的技术简报 +- **跨会话内存**：为后续讨论维护发现上下文 + +**体验示例:** +``` +Standard Approach: "I'll build a user authentication system with JWT tokens..." +Brainstorming Approach: +"🤔 Let's explore this together: + - What specific user problems does auth solve for your app? + - Who are your users and what's their technical comfort level? + - Any existing systems or social logins to integrate with? + - What security/compliance requirements do you have? + 📝 Outcome: Detailed auth requirements brief ready for implementation" +``` + +#### 成功标准 +- [ ] 用问题而不是直接解决方案来回应 +- [ ] 问题探索用户需求、技术约束和业务目标 +- [ ] 在整个发现过程中保持协作语调 +- [ ] 产生结构化需求或技术简介作为结果 + +**验证：** `/sc:brainstorm "web app"` 应该询问用户、功能、技术相关问题 +**测试：** 模糊请求应该触发发现性问题，而不是假设 +**检查：** 模式应该在同一会话的后续问题中保持一致 + +**最佳搭配：** +- **→ 任务管理**：需求发现 → 系统性实施规划 +- **→ 编排**：需求明确化 → 实施的最优工具选择 +- **手动覆盖**：使用 `--brainstorm` 强制发现，即使对于"明确"的需求 + +--- + +### 🔍 内省模式 - 元认知分析 + +**目的**：为学习优化和透明决策制定暴露推理过程。 + +**自动激活触发器：** +- 自我分析请求："分析我的推理"、"反思决策" +- 错误恢复场景和需要调查的意外结果 +- 具有多种可行方法的复杂问题求解 +- 优化机会的模式识别需求 +- 手动标志：`--introspect` + +**行为变化：** +- **推理透明度**：通过清晰标记暴露思维过程 (🤔, 🎯, ⚡, 📊, 💡) +- **决策分析**：评估选择逻辑并考虑替代方案 +- **模式识别**：识别重复行为和改进机会 +- **元学习**：提取见解以持续改进框架 +- **框架合规性**：根据 SuperClaude 原则和质量门控验证行为 + +**体验示例：** +``` +Standard Approach: "I'll analyze this code structure and suggest improvements..." +Introspective Approach: +"🧠 Meta-Analysis: Why did I choose structural analysis over functional flow analysis? + 🎯 Decision Logic: Saw class hierarchy → assumed OOP patterns dominate + 🔄 Alternative Considered: Data flow analysis might reveal hidden dependencies + 📊 Evidence Check: File imports suggest functional composition, not OOP + 💡 Learning: Need to analyze imports before choosing analysis strategy + ⚡ Correction: Switching to functional flow analysis approach" +``` + +**最佳搭配：** +- **→ 任务管理**：为复杂阶段决策提供透明推理 +- **任何模式**：为任何其他模式的操作添加推理透明度层 +- **手动覆盖**：在学习会话和调试工作流中使用 `--introspect` + +--- + +### 📋 任务管理模式 - 复杂协调 + +**目的**：具有会话持久性的分层任务组织，用于多步操作。 + +**自动激活触发器：** +- 需要超过 3 个协调步骤的操作 +- 多文件/目录范围（>2 目录或 >3 文件） +- 需要阶段和检查点的复杂依赖关系 +- 质量改进请求：完善、优化、增强 +- 手动标志：`--task-manage`、`--delegate` + +**行为变化：** +- **分层规划**：将复杂工作分解为计划 → 阶段 → 任务 → 待办结构 +- **会话持久性**：在中断期间维护项目上下文和进度 +- **内存集成**：使用 write_memory/read_memory 进行状态保存 +- **进度编排**：协调 TodoWrite 与内存更新以进行跟踪 +- **质量门控**：在阶段之间实施系统验证检查点 + +**体验示例：** +``` +Standard Approach: "I'll implement user authentication..." → Direct implementation +Task Management Approach: +"📋 Multi-Phase Implementation Plan: + 🎯 Phase 1: Security requirements analysis (Session 1) + 🎯 Phase 2: API design & documentation (Session 2) + 🎯 Phase 3: Implementation & testing (Sessions 3-4) + 🎯 Phase 4: Integration & validation (Session 5) + 💾 Session Persistence: Auto-resume context + ✓ Quality Gates: Validation before each phase transition" +``` + +**最佳搭配：** +- **头脑风暴 →**：需求发现然后系统化实施 +- **+ 编排**：任务协调与最优工具选择 +- **+ 内省**：复杂阶段决策的透明推理 + +--- + +### 🎯 编排模式 - 智能工具选择 + +**目的**：通过智能工具路由和并行协调优化任务执行。 + +**自动激活触发器：** +- 需要复杂协调的多工具操作 +- 性能约束（高资源使用） +- 并行执行机会（>3 个独立文件/操作） +- 具有多种有效工具方法的复杂路由决策 + +**行为变化：** +- **智能工具路由**：为每种任务类型选择最优的 MCP 服务器和原生工具 +- **资源感知**：基于系统约束和可用性调整方法 +- **并行优化**：识别独立操作以进行并发执行 +- **协调焦点**：通过协调执行优化工具选择和使用 +- **自适应回退**：当首选选项不可用时优雅地切换工具 + +**体验示例：** +``` +Standard Approach: Sequential file-by-file analysis and editing +Orchestration Approach: +"🎯 Multi-Tool Coordination Strategy: + 🔍 Phase 1: Serena (semantic analysis) + Sequential (architecture review) + ⚡ Phase 2: Morphllm (pattern edits) + Magic (UI components) + 🧪 Phase 3: Playwright (testing) + Context7 (doc patterns) + 🔄 Parallel Execution: 3 tools working simultaneously" +``` + +**最佳搭配：** +- **任务管理 →**：为复杂多阶段计划提供工具协调 +- **+ 令牌效率**：带压缩通信的最优工具选择 +- **任何复杂任务**：添加智能工具路由以增强执行 + +--- + +### ⚡ 令牌效率模式 - 压缩通信 + +**目的**：通过符号系统实现预计 30-50% 的令牌减少，同时保持信息质量。 + +**自动激活触发器：** +- 高上下文使用接近限制 +- 需要资源效率的大规模操作 +- 用户显式标志：`--uc`、`--ultracompressed` +- 具有多个输出的复杂分析工作流 + +**行为变化：** +- **符号通信**：为逻辑流程、状态和技术领域使用视觉符号 +- **技术缩写**：对重复技术术语进行上下文感知压缩 +- **结构化密度**：使用要点、表格和简洁格式，而非冗长段落 +- **信息保留**：尽管压缩，仍保持 ≥95% 的信息质量 +- **结构化格式**：为清晰度和任务完成而组织 + +**体验示例：** +``` +Standard Approach: "Authentication system implementation shows security vulnerability in user validation function requiring immediate attention..." +Token-Efficient Approach: +"🛡️ Security Alert: + auth.js:45 → user val() → critical vuln + 📊 Impact: ❌ possible token bypass + ⚡ Action: fix validation + audit ∵ high severity + 🔧 Estimate: 2hr impl + 1hr test" +``` + +**最佳搭配：** +- **任何模式**：在保持特定模式行为的同时添加压缩层 +- **编排 →**：压缩的工具协调和状态更新 +- **手动覆盖**：当上下文压力或效率是优先级时使用 `--uc` + +--- + +### 🎨 标准模式 - 均衡默认 + +**目的**：为直接的开发任务提供清晰、专业的沟通。 + +**自动激活触发器：** +- 没有复杂性指标的简单、明确定义的任务 +- 具有明确要求的单文件操作 +- 基本解释和标准开发工作流 +- 未检测到其他模式触发器（默认回退） + +**行为变化：** +- **专业沟通**：清晰、简洁的技术语言，无压缩 +- **适度细节**：适合大多数开发任务的平衡信息深度 +- **标准工具选择**：使用原生 Claude 能力和基本工具 +- **质量焦点**：在无复杂编排开销的情况下保持代码质量 +- **响应式适应**：当复杂性增加时准备切换到专门模式 + +**体验示例：** +``` +Standard Approach: Consistent, professional baseline for all tasks +"I'll implement the login functionality with proper error handling: + + 1. Validate user input (email format, password requirements) + 2. Authenticate against database with secure hashing + 3. Generate JWT token with appropriate expiration + 4. Return success response with user data + + Implementation will follow security best practices and include comprehensive error handling." +``` + +**最佳搭配：** +- **→ 任何模式**：作为其他模式增强的基线 +- **模式切换**：需要时自动升级到专门模式 +- **清晰优先**：当直接沟通比优化更重要时 + +--- + +## 高级用法 + +### 模式组合 + +**多模式工作流：** +```bash +# 发现 → 规划 → 实现 +/sc:brainstorm "microservices architecture" --task-manage +# → 头脑风暴：需求发现 +# → 任务管理：多阶段协调 + +# 透明和高效的分析 +/sc:analyze legacy-system/ --introspect --uc +# → 内省：透明推理 +# → 令牌效率：压缩输出 +``` + +### 手动模式控制 + +**强制特定行为：** +- `--brainstorm`：为任何任务强制协作发现 +- `--introspect`：为任何模式添加推理透明度 +- `--task-manage`：启用分层协调 +- `--orchestrate`：优化工具选择和并行执行 +- `--uc`：为效率压缩通信 + +**覆盖示例：** +```bash +# 对“明确”的需求强制头脑风暴 +/sc:implement "user login" --brainstorm + +# 为调试添加推理透明度 +/sc:fix auth-issue --introspect + +# 为简单操作启用任务管理 +/sc:update styles.css --task-manage +``` + +### 模式边界和优先级 + +**模式激活时机：** +1. **复杂度阈值**：>3 文件 → 任务管理 +2. **资源压力**：高上下文使用 → 令牌效率 +3. **多工具需求**：复杂分析 → 编排 +4. **不确定性**：模糊需求 → 头脑风暴 +5. **错误恢复**：问题 → 内省 + +**优先级规则：** +- **安全第一**：质量和验证总是覆盖效率 +- **用户意图**：手动标志覆盖自动检测 +- **上下文适应**：基于复杂性堆叠模式 +- **资源管理**：在压力下激活效率模式 + +--- + +## 现实世界示例 + +### 完整工作流示例 + +**新项目开发：** +```bash +# 阶段 1：发现（头脑风暴模式自动激活） +"I want to build a productivity app" +→ 🤔 关于用户、功能、平台选择的苏格拉底式问题 +→ 📝 结构化需求简报 + +# 阶段 2：规划（任务管理模式自动激活） +/sc:implement "core productivity features" +→ 📋 带依赖关系的多阶段分解 +→ 🎯 带质量门控的阶段协调 + +# 阶段 3：实现（编排模式协调工具） +/sc:develop frontend + backend +→ 🎯 Magic (UI) + Context7 (模式) + Sequential (架构) +→ ⚡ 并行执行优化 +``` + +**调试复杂问题：** +```bash +# 问题分析（内省模式自动激活） +"Users experiencing intermittent authentication failures" +→ 🤔 关于潜在原因的透明推理 +→ 🎯 假设形成和证据收集 +→ 💡 跨相似问题的模式识别 + +# 系统性解决（任务管理协调） +/sc:fix auth-system --comprehensive +→ 📋 阶段 1：根因分析 +→ 📋 阶段 2：解决方案实现 +→ 📋 阶段 3：测试和验证 +``` + +### 模式组合模式 + +**高复杂度场景：** +```bash +# 带多重约束的大型重构 +/sc:modernize legacy-system/ --introspect --uc --orchestrate +→ 🔍 透明推理introspect（内省） +→ ⚡ 压缩通信uc（令牌效率） +→ 🎯 最优工具协调orchestrate（编排） +→ 📋 系统化阶段（任务管理自动激活） +``` + +--- + +## 快速参考 + +### 模式激活模式 + +| 触发类型 | 输入示例 | 激活模式 | 关键行为 | +|---------|---------|----------|----------| +| **模糊请求** | "我想构建一个应用" | 🧠 头脑风暴 | 苏格拉底式发现问题 | +| **复杂范围** | >3 文件或 >2 目录 | 📋 任务管理 | 阶段协调 | +| **多工具需求** | 分析 + 实施 | 🎯 编排 | 工具优化 | +| **错误恢复** | "这没有按预期工作" | 🔍 内省 | 透明推理 | +| **资源压力** | 高上下文使用 | ⚡ 令牌效率 | 符号压缩 | +| **简单任务** | "修复这个函数" | 🎨 标准 | 清晰、直接的方法 | + +### 手动覆盖命令 + +```bash +# 强制特定模式行为 +/sc:command --brainstorm # 协作发现 +/sc:command --introspect # 推理透明度 +/sc:command --task-manage # 分层协调 +/sc:command --orchestrate # 工具优化 +/sc:command --uc # 令牌压缩 + +# 组合多种模式 +/sc:command --introspect --uc # 透明 + 高效 +/sc:command --task-manage --orchestrate # 协调 + 优化 +``` + +--- + +## 故障排除 + +有关故障排除帮助，请参阅： +- [常见问题](../Reference/common-issues.md) - 频繁问题的快速修复 +- [故障排除指南](../Reference/troubleshooting.md) - 全面的问题解决方案 + +### 常见问题 +- **模式未激活**：使用手动标志：`--brainstorm`、`--introspect`、`--uc` +- **激活了错误的模式**：检查请求中的复杂性触发器和关键词 +- **模式意外切换**：基于任务演化的正常行为 +- **执行影响**：模式优化工具使用，不应影响执行 +- **模式冲突**：检查[标志指南](flags.md)中的标志优先级规则 + +### 即时修复 +- **强制特定模式**：使用明确标志如 `--brainstorm` 或 `--task-manage` +- **重置模式行为**：重启 Claude Code 会话以重置模式状态 +- **检查模式指示器**：在响应中查找 🤔、🎯、📋 符号 +- **验证复杂性**：简单任务使用标准模式，复杂任务自动切换 + +### 特定模式故障排除 + +**头脑风暴模式问题：** +```bash +# 问题：模式给出解决方案而不是问题 +# 快速修复：检查请求清晰度并使用显式标志 +/sc:brainstorm "web app" --brainstorm # 强制发现模式 +"I have a vague idea about..." # 使用不确定语言 +"Maybe we could build..." # 触发探索 +``` + +**任务管理模式问题：** +```bash +# 问题：简单任务得到复杂协调 +# 快速修复：减少范围或使用更简单的命令 +/sc:implement "function" --no-task-manage # 禁用协调 +/sc:simple-fix bug.js # 使用基本命令 +# 检查任务是否真正复杂（>3 文件，>2 目录） +``` + +**令牌效率模式问题：** +```bash +# 问题：输出过于压缩或不清楚 +# 快速修复：禁用压缩以提高清晰度 +/sc:command --no-uc # 禁用压缩 +/sc:command --verbose # 强制详细输出 +# 当清晰度比效率更重要时使用 +``` + +**内省模式问题：** +```bash +# 问题：过多元评论，行动不足 +# 快速修复：为直接工作禁用内省 +/sc:command --no-introspect # 直接执行 +# 仅在学习和调试时使用内省 +``` + +**编排模式问题：** +```bash +# 问题：工具协调造成混乱 +# 快速修复：简化工具使用 +/sc:command --no-mcp # 仅使用原生工具 +/sc:command --simple # 基本执行 +# 检查任务复杂度是否需要编排 +``` + +### 错误代码参考 + +| 模式错误 | 含义 | 快速修复 | +|---------|-----|----------| +| **B001** | 头脑风暴激活失败 | 使用显式 `--brainstorm` 标志 | +| **T001** | 任务管理开销 | 对简单任务使用 `--no-task-manage` | +| **U001** | 令牌效率过于激进 | 使用 `--verbose` 或 `--no-uc` | +| **I001** | 内省模式卡住 | 对直接行动使用 `--no-introspect` | +| **O001** | 编排协调失败 | 使用 `--no-mcp` 或 `--simple` | +| **M001** | 检测到模式冲突 | 检查标志优先级规则 | +| **M002** | 模式切换循环 | 重启会话以重置状态 | +| **M003** | 模式无法识别 | 更新 SuperClaude 或检查拼写 | + +### 渐进式支持级别 + +**级别 1：快速修复（< 2 分钟）** +- 使用手动标志覆盖自动模式选择 +- 检查任务复杂性是否与预期模式行为匹配 +- 尝试重启 Claude Code 会话 + +**级别 2：详细帮助（5-15 分钟）** +```bash +# 特定模式诊断 +/sc:help modes # 列出所有可用模式 +/sc:reflect --type mode-status # 检查当前模式状态 +# 检查请求复杂性和触发器 +``` +- 有关模式安装问题，请参阅[常见问题指南](../Reference/common-issues.md) + +**级别 3：专家支持（30+ 分钟）** +```bash +# 深度模式分析 +SuperClaude install --diagnose +# 检查模式激活模式 +# 检查行为触发器和阈值 +``` +- 有关行为模式分析，请参阅[诊断参考指南](../Reference/diagnostic-reference.md) + +**级别 4：社区支持** +- 在 [GitHub Issues](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues) 报告模式问题 +- 包括意外模式行为的示例 +- 描述期望与实际模式激活的差异 + +### 成功验证 + +应用模式修复后，进行测试： +- [ ] 简单请求使用标准模式（清晰、直接的响应） +- [ ] 复杂请求自动激活适当的模式（协调、推理） +- [ ] 手动标志正确覆盖自动检测 +- [ ] 模式指示器（🤔、🎯、📋）在预期时出现 +- [ ] 在不同模式下性能保持良好 + +## 快速故障排除（旧版） +- **模式未激活** → 使用手动标志：`--brainstorm`、`--introspect`、`--uc` +- **激活了错误的模式** → 检查请求中的复杂性触发器和关键词 +- **模式意外切换** → 基于任务演化的正常行为 +- **执行影响** → 模式优化工具使用，不应影响执行 +- **模式冲突** → 检查[标志指南](flags.md)中的标志优先级规则 + +## 常见问题 + +**问：如何知道哪个模式处于激活状态？** +答：在通信模式中查找这些指示器： +- 🤔 发现性问题 → 头脑风暴 +- 🎯 推理透明度 → 内省 +- 阶段分解 → 任务管理 +- 工具协调 → 编排 +- 符号压缩 → 令牌效率 + +**问：我可以强制特定模式吗？** +答：是的，使用手动标志覆盖自动检测： +```bash +/sc:command --brainstorm # 强制发现模式 +/sc:command --introspect # 增加透明性 +/sc:command --task-manage # 启用协调 +/sc:command --uc # 压缩输出 +``` + +**问：模式会影响执行吗？** +答：模式通过协调优化工具使用： +- **令牌效率**：上下文减少 30-50% +- **编排**：并行处理 +- **任务管理**：通过系统化规划防止返工 + +**问：模式可以协同工作吗？** +答：是的，模式设计为互相补充： +- **任务管理**协调其他模式 +- **令牌效率**压缩任何模式的输出 +- **内省**为任何工作流添加透明度 + +--- + +## 总结 + +SuperClaude 的 5 种行为模式创建了一个**智能适应系统**，自动匹配您的需求： + +- **🧠 头脑风暴**：将模糊想法转化为清晰需求 +- **🔍 内省**：为学习和调试提供透明推理 +- **📋 任务管理**：协调复杂的多步操作 +- **🎯 编排**：优化工具选择和并行执行 +- **⚡ 令牌效率**：在保持清晰度的同时压缩通信 +- **🎨 标准**：为直接任务维护专业基线 + +**关键洞察**：您无需思考模式 - 它们透明地工作以增强您的开发体验。只需描述您想要完成的任务，SuperClaude 会自动调整其方法以匹配您的需求。 + +--- + +## 相关指南 + +**学习进展：** + +**🌱 基础（第1周）** +- [快速开始指南](../Getting-Started/quick-start.md) - 模式激活示例 +- [命令参考](commands.md) - 命令自动激活模式 +- [安装指南](../Getting-Started/installation.md) - 设置行为模式 + +**🌿 中级（第2-3周）** +- [智能体指南](agents.md) - 模式如何与专家协调 +- [标志指南](flags.md) - 手动模式控制和优化 +- [示例手册](../Reference/examples-cookbook.md) - 实践中的模式模式 + +**🌲 高级（第2+个月）** +- [MCP 服务器](mcp-servers.md) - 模式与增强能力的集成 +- [会话管理](session-management.md) - 任务管理模式工作流 +- [入门指南](../Getting-Started/quick-start.md) - 模式使用模式 + +**🔧 专家级** +- [技术架构](../Developer-Guide/technical-architecture.md) - 模式实现细节 +- [代码贡献](../Developer-Guide/contributing-code.md) - 扩展模式能力 + +**特定模式指南：** +- **头脑风暴**：[需求发现模式](../Reference/examples-cookbook.md#requirements) +- **任务管理**：[会话管理指南](session-management.md) +- **编排**：[MCP 服务器指南](mcp-servers.md) +- **令牌效率**：[命令基础](commands.md#token-efficiency) \ No newline at end of file diff --git a/Docs/User-Guide-zh/session-management.md b/Docs/User-Guide-zh/session-management.md new file mode 100644 index 0000000..7a625ca --- /dev/null +++ b/Docs/User-Guide-zh/session-management.md @@ -0,0 +1,310 @@ +# 会话管理指南 + +SuperClaude 通过 Serena MCP 服务器提供持久会话管理，实现在 Claude Code 对话中真正的上下文保存和长期项目连续性。 + +## 具有持久内存的核心会话命令 + +### `/sc:load` - 具有持久内存的上下文加载 +**目的**：使用项目上下文和以前会话的持久内存初始化会话 +**MCP 集成**：触发 Serena MCP 读取存储的项目内存 +**语法**：`/sc:load [project_path]` + +**发生什么**： +- Serena MCP 从以前的会话中读取持久内存文件 +- 从存储的内存中恢复项目上下文 +- 加载以前的决策、模式和进度 +- 使用历史上下文初始化会话状态 + +**使用案例**： +```bash +# 从持久内存加载现有项目上下文 +/sc:load src/ + +# 恢复特定项目工作及其完整历史 +/sc:load "authentication system" + +# 使用代码库分析和先前见解初始化 +/sc:load . --analyze +``` + +### `/sc:save` - 会话持久化到内存 +**目的**：将当前会话状态和决策保存到持久内存 +**MCP 集成**：触发 Serena MCP 写入内存文件 +**语法**：`/sc:save "会话描述"` + +**发生什么**： +- 当前上下文和决策被写入 Serena 内存 +- 项目状态和进度在对话中持久保存 +- 关键见解和模式被存储以供未来会话使用 +- 创建带有时间戳的会话摘要以便检索 + +**使用案例**： +```bash +# 保存已完成的特性工作以供未来参考 +/sc:save "user authentication implemented with JWT" + +# 复杂工作期间的检查点 +/sc:save "API design phase complete, ready for implementation" + +# 永久存储架构决策 +/sc:save "microservices architecture decided, service boundaries defined" +``` + +### `/sc:reflect` - 带有内存上下文的进度评估 +**目的**：根据存储的内存分析当前进度并验证会话完整性 +**MCP 集成**：使用 Serena MCP 将当前状态与存储的内存进行比较 +**语法**：`/sc:reflect [--scope project|session]` + +**发生什么**： +- Serena MCP 读取以前的内存和当前上下文 +- 根据存储的目标和里程碑评估进度 +- 使用历史上下文识别差距和下一步 +- 根据项目内存验证会话完整性 + +**使用案例**： +```bash +# 根据存储的里程碑评估项目进度 +/sc:reflect --scope project + +# 验证当前会话完整性 +/sc:reflect + +# 根据内存检查是否准备进入下一阶段 +/sc:reflect --scope session +``` + +## 持久内存架构 + +### Serena MCP 如何实现真正的持久性 + +**内存存储**： +- 会话上下文作为结构化内存文件存储 +- 项目决策和架构模式永久保存 +- 代码分析结果和见解在对话中保持 +- 进度跟踪和里程碑数据长期维护 + +**跨会话连续性**： +- 新对话中自动加载以前的会话上下文 +- 决策和理由在对话中保存和可访问 +- 从过去的模式和解决方案中学习并维护 +- 一致的项目理解无限期维护 + +**内存类型**： +- **项目内存**：长期项目上下文和架构 +- **会话内存**：特定对话结果和决策 +- **模式内存**：可重用的解决方案和架构模式 +- **进度内存**：里程碑跟踪和完成状态 + +## 具有持久性的会话生命周期模式 + +### 新项目初始化 +```bash +# 1. 开始全新项目 +/sc:brainstorm "e-commerce platform requirements" + +# 2. 将初始决策保存到持久内存 +/sc:save "project scope and requirements defined" + +# 3. 开始实现规划 +/sc:workflow "user authentication system" + +# 4. 永久保存架构决策 +/sc:save "authentication architecture: JWT + refresh tokens + rate limiting" +``` + +### 恢复现有工作（跨对话） +```bash +# 1. 从持久内存加载以前的上下文 +/sc:load "e-commerce project" + +# 2. 根据存储的进度评估当前状态 +/sc:reflect --scope project + +# 3. 使用存储的上下文继续下一阶段 +/sc:implement "payment processing integration" + +# 4. 将进度检查点保存到内存 +/sc:save "payment system integrated with Stripe API" +``` + +### 长期项目管理 +```bash +# 具有持久性的周检查点模式 +/sc:load project-name +/sc:reflect --scope project +# ... 处理特性 ... +/sc:save "week N progress: features X, Y, Z completed" + +# 具有内存的阶段完成模式 +/sc:reflect --scope project +/sc:save "phase 1 complete: core authentication and user management" +/sc:workflow "phase 2: payment and order processing" +``` + +## 跨对话连续性 + +### 使用持久性开始新对话 + +当开始新的 Claude Code 对话时，持久内存系统允许： + +1. **自动上下文恢复** + ```bash + /sc:load project-name + # 自动恢复所有以前的上下文、决策和进度 + ``` + +2. **进度继续** + - 以前会话的决策立即可用 + - 架构模式和代码见解被保存 + - 项目历史和理由被维护 + +3. **智能上下文构建** + - Serena MCP 根据当前工作提供相关内存 + - 过去的解决方案和模式指导新的实现 + - 项目演变被跟踪和理解 + +### 内存优化 + +**有效的内存使用**： +- 使用描述性、可搜索的内存名称 +- 包含项目阶段和时间戳上下文 +- 引用特定功能或架构决策 +- 让未来的检索变得直观 + +**内存内容策略**： +- 存储决策和理由，而不仅仅是结果 +- 包含考虑的替代方案 +- 记录集成模式和依赖关系 +- 为未来参考保留学习和洞察 + +**内存生命周期管理**： +- 定期清理过时的内存 +- 整合相关的会话内存 +- 归档已完成的项目阶段 +- 修剪过时的架构决策 + +## 持久会话的最佳实践 + +### 会话开始协议 +1. 对于现有项目始终以 `/sc:load` 开始 +2. 使用 `/sc:reflect` 从内存中了解当前状态 +3. 根据持久上下文和存储的模式规划工作 +4. 基于以前的决策和架构选择构建 + +### 会话结束协议 +1. 使用 `/sc:reflect` 根据存储的目标评估完整性 +2. 使用 `/sc:save` 保存关键决策以供未来会话 +3. 在内存中记录下一步和未解决的问题 +4. 为无缝的未来继续保存上下文 + +### 内存质量维护 +- 使用清晰、描述性的内存名称以便于检索 +- 包含关于决策和替代方法的上下文 +- 引用特定的代码位置和模式 +- 在跨会话中保持内存结构的一致性 + +## 与其他 SuperClaude 功能的集成 + +### MCP 服务器协调 +- **Serena MCP**：提供持久内存基础设施 +- **Sequential MCP**：使用存储的内存进行增强的复杂分析 +- **Context7 MCP**：引用存储的模式和文档方法 +- **Morphllm MCP**：一致地应用存储的重构模式 + +### 智能体与内存的协作 +- 智能体访问持久内存以增强上下文 +- 先前的专家决策被保留和引用 +- 通过共享内存进行跨会话智能体协调 +- 基于项目历史的一致专家建议 + +### 命令与持久化的集成 +- 所有 `/sc:` 命令都可以引用和构建持久上下文 +- 先前的命令输出和决策在跨会话中可用 +- 工作流程模式被存储和重用 +- 实现历史指导未来的命令决策 + +## 持久会话故障排除 + +### 常见问题 + +**内存未加载**： +- 验证 Serena MCP 配置正确并正常运行 +- 检查内存文件权限和可访问性 +- 确保一致的项目命名约定 +- 验证内存文件完整性和格式 + +**会话间上下文丢失**： +- 在结束会话前始终使用 `/sc:save` +- 使用描述性内存名称以便于检索 +- 定期使用 `/sc:reflect` 验证内存完整性 +- 定期备份重要的内存文件 + +**内存冲突**： +- 使用带时间戳的内存名称进行版本控制 +- 定期清理过时的内存 +- 清楚分离项目和会话内存 +- 在跨会话中保持一致的内存命名约定 + +### 快速修复 + +**重置会话状态**： +```bash +/sc:load --fresh # 不带先前上下文开始 +/sc:reflect # 评估当前状态 +``` + +**内存清理**： +```bash +/sc:reflect --cleanup # 删除过时的内存 +/sc:save --consolidate # 合并相关内存 +``` + +**上下文恢复**： +```bash +/sc:load --recent # 加载最近的内存 +/sc:reflect --repair # 识别并修复上下文空白 +``` + +## 高级持久会话模式 + +### 多阶段项目 +- 使用阶段特定的内存命名进行组织 +- 跨阶段维护架构决策连续性 +- 通过持久内存进行跨阶段依赖跟踪 +- 具有历史上下文的渐进式复杂性管理 + +### 团队协作 +- 共享的内存约定和命名标准 +- 为团队上下文保留决策理由 +- 所有团队成员都可访问的集成模式文档 +- 通过内存实现一致的代码风格和架构执行 + +### 长期维护 +- 已完成项目的内存归档策略 +- 通过累积内存开发模式库 +- 随时间建立的可重用解决方案文档 +- 通过持久内存积累建立知识库 + +## 持久会话管理的关键优势 + +### 项目连续性 +- 在多次对话中无缝的工作延续 +- Claude Code 会话之间无上下文丢失 +- 保留的架构决策和技术理由 +- 长期项目演进跟踪 + +### 提升生产力 +- 减少重新解释项目上下文的需要 +- 继续工作的更快启动时间 +- 基于先前的洞察和模式进行构建 +- 累积的项目知识增长 + +### 质量一致性 +- 跨会话的一致架构模式 +- 保留的代码质量决策和标准 +- 可重用的解决方案和最佳实践 +- 维持的技术债务意识 + +--- + +**关键要点**：通过 Serena MCP 的会话管理将 SuperClaude 从单次对话帮助转变为持久项目伙伴关系，在所有开发阶段和 Claude Code 对话中维护上下文、决策和学习。 \ No newline at end of file