super-dev

<p align="center"> <img src=".github/logo.png" alt="超级开发工具" width="500"> </p> <p align="center"> 给你的开发工作流超级能力。 </p> 超级开发工具是一款 [MCP 服务器](https://modelcontextprotocol.io/)，可以与 **Zed**、**Claude Desktop**、**Cursor** 或任何 MCP 客户端插件，添加结构化规划、深度代码审查和设计工作流在你的 AI 编程代理之上。 🔨 **基于规格的开发**：从想法到实现，带有结构化需求 → 设计 → 任务阶段 🔍 **代码审查**：高级工程师风格的审查，带有网页验证 🎨 **设计工作流**：构建、完善和审查 UI 界面，带有设计系统记忆 🧵 **对话历史**：搜索和引用过去的编码会话（仅限 Zed） 🔊 **语音模式**：免提 TTS 反馈，带有 Siri 神经语音（Zed + macOS） 🔀 **上游合并**：基于策略的冲突解决，用于分叉 [](LICENSE) --- ## 快速开始 ```bash git clone https://github.com/nickjessop/super-dev.git cd super-dev npm install ``` `npm install` 会自动通过 `prepare` 脚本构建项目。 ## 设置 ### Zed 编辑器 将以下内容添加到项目的 `.zed/settings.json`： ```json { "context_servers": { "super-dev": { "command": "/path/to/super-dev/run.sh", "args": [] } } } ``` ### Claude Desktop / 其他 MCP 客户端 将客户端指向 `run.sh`，或直接指向 `node /path/to/super-dev/dist/index.js`。 > **为什么使用 `run.sh`？** GUI 启动的编辑器不会继承 shell 的 nvm/fnm 设置。包装器会获取 shell 配置文件，以便 Node 正确解析。 ### 项目根目录解析 服务器确定其操作的项目（按优先级顺序）： 1. `SUPER_DEV_PROJECT_ROOT` 环境变量 2. MCP `roots/list`：询问客户端的工作区根目录 3. `process.cwd()` 回退 ### 禁用功能 所有功能默认启用。禁用不需要的功能，使用 `SUPER_DEV_DISABLE` 环境变量，减少工具杂乱和上下文开销： ```json { "context_servers": { "super-dev": { "command": "/path/to/super-dev/run.sh", "env": { "SUPER_DEV_DISABLE": "voice,upstream,threads" } } } } ``` | 组 | 工具 | 提示 | |-------|-------|--------| | `spec` | spec_create, spec_read, spec_status, spec_approve, spec_task_complete, spec_analyze | /spec-plan, /spec-execute | | `review` | — | /code-review | | `design` | — | /design, /design-review | | `rules` | load_rules + rule:// 资源 | — | | `threads` | thread_list, thread_read, thread_search | — | | `voice` | voice_mode | /toggle-voice-mode | | `upstream` | upstream_status + 所有合并工具 | /upstream-merge | ## 快速参考 ### 斜杠命令 | 命令 | 目的 | |---------|---------| | `/spec-plan` | 驱动需求 → 设计 → 任务工作流，带有想法压力测试和网页研究 | | `/spec-execute` | 使用子代理编排实现 | | `/code-review` | 高级工程师风格的代码审查 | | `/design` | 构建新的 UI 或完善现有的 UI，带有内置设计系统 | | `/design-review` | 设计总监批评，带有启发式评分 | | `/toggle-voice-mode` | 启用/禁用 TTS 语音反馈 | | `/upstream-merge` | 有指导的上游合并工作流 | ### 工具 | 工具 | 目的 | |------|--------| | `spec_create` | 脚手架新的规格，带有需求/设计/任务 | | `spec_read` | 读取规格文件（需求、设计或任务） | | `spec_status` | 列出所有规格或获取规格详情 | | `spec_approve` | 批准当前阶段并进入下一阶段 | | `spec_task_complete` | 标记任务完成；父任务自动提交 | | `spec_analyze` | 分析需求的质量问题（歧义、冲突、完整性、测试性） | | `load_rules` | 从 `.rules/` 加载项目规则，带有基于 glob 的自动匹配 | | `thread_list` | 列出最近的 Zed 代理对话线程 | | `thread_read` | 读取线程 ID，带有分页和搜索 | | `thread_search` | 对话内容全文搜索 | | `voice_mode` | 切换 TTS，带有 macOS 语音合成 | | `upstream_status` | 检查上游状态，初始化配置或启动合并 | 上游合并解决工具（`upstream_categorize_changes`、`upstream_resolve_file`、`upstream_resolve_batch`、`upstream_diff_file`、`upstream_verify`、`upstream_complete`、`upstream_abort`）仅在活动合并期间出现。 ### 资源 `.rules/` 中的每个规则都作为 `rule://<name>` MCP 资源暴露给支持它的客户端。客户端不支持资源可以使用 `load_rules` 工具代替。 --- ## 功能 ### 基于规格的开发 从粗略的想法到交付的代码，带有结构化阶段和批准关口。 1. **`/spec-plan`**：描述你的功能。代理测试想法，进行网页研究，帮助你思考边缘情况，然后再编写代码。 2. **`spec_create`**：在项目中脚手架 `.specs/<feature>/`，带有 `requirements.md`、`design.md`、`tasks.md` 和 `state.json`。 3. **需求 → 设计 → 任务**：每个阶段都必须显式批准，然后才能解锁下一阶段。在需求阶段，`spec_analyze` 检查歧义、冲突、完整性空白、解决方案泄漏和测试性 — 将发现的问题作为 A/B 问题，你在批准前回答。 4. **`/spec-execute`**：通过为每个任务委派子代理来编排实现。主线程保持清洁，用于协调，而子代理执行编码。 5. **自动提交**：当父任务标记为完成时，代理自动提交工作，带有约定提交消息。为特定规格选择退出，设置 `autoCommit: false`。 规格存储在消费项目的 `.specs/<feature>/` 中（默认为 gitignore）。 ### 代码审查 运行 `/code-review` 并指向特定文件、git diff、未暂存更改或特定关注区域。代理审查如同高级工程师： - 确定错误、性能问题和安全问题 - 搜索类似实现和官方文档的网页，以验证模式 - 报告做得好的地方、令人担忧的地方和具体建议 ### 设计工作流 两个命令用于构建和评估 UI： **`/design`**：执行者。告诉它你想做什么，它会确定模式： - **构建**：从头开始规划和实现新的 UI 界面，带有主题推理、颜色策略和布局决策 - **完善**：将现有 UI 推向某个方向（更大胆、更安静、更精致、提炼、更好的层次结构、生产就绪等） - **设计记忆**：如果项目中没有 `PRODUCT.md` 或 `DESIGN.md`，它会帮助你创建它们。这些文件捕获产品的身份、品牌个性、颜色调色板、字体排版和组件模式。每个后续设计决策都引用它们。 **`/design-review`**：评论家。纯粹的反馈，没有代码更改： - AI 垃圾检测（侧边条形边框、渐变文本、玻璃态、英雄式模板、类别反射调色板选择） - 尼尔森的 10 个可用性启发式评分 0–4 - 认知负荷评估 - 设计系统漂移检查，针对 `DESIGN.md` - 无障碍和响应式审计 - 基于角色的红旗分析 ### 项目规则 规则是 Markdown 文件，位于项目的 `.rules/` 目录中，为代理提供特定于项目的上下文。每个规则都有 YAML 前置元数据，控制何时加载： ```yaml --- inclusion: always # 每次调用 load_rules 时加载 --- ``` ```yaml --- inclusion: auto # 仅在处理匹配文件时加载 fileMatchPattern: "src/**/*.tsx" --- ``` ```yaml --- inclusion: manual # 仅在显式请求时加载 --- ``` `load_rules` 工具使用 glob 匹配，以便代理仅接收与正在处理的文件相关的规则，保持上下文聚焦。对于支持 MCP 资源客户端，规则也作为 `rule://<name>` 资源暴露。 ### 对话历史 直接从代理面板搜索和读取过去的 Zed 代理线程。对于从以前会话中恢复上下文、查找决策位置或引用过去工作非常有用。 > **仅限 Zed + macOS**。直接从 Zed 的 `threads.db` SQLite 数据库读取，带有 zstd 解压缩。 - **`thread_list`**：浏览最近的线程，带有摘要、时间戳和项目文件夹。按项目筛选。 - **`thread_search`**：对话内容全文搜索（不仅限于标题）。解压缩 Zed 的 zstd 压缩线程数据并搜索实际消息。 - **`thread_read`**：读取特定线程。大型线程（20+ 消息）首先返回目录；使用偏移量或搜索导航到特定部分。支持消息截断以管理上下文使用。 ### 语音模式 使用 macOS 语音合成的免提 TTS 反馈。运行 `/toggle-voice-mode` 或直接调用 `voice_mode` 工具。 > **仅限 Zed + macOS**。监视 Zed 的对话数据库并使用 macOS `say` 命令。 - 使用 macOS `say` 命令，支持 Siri 神经语音（通过“系统”语音选项） - 生成一个独立的观察者进程，监视 Zed 的对话文件以获取新的代理响应 - 限定为当前项目，以防止跨项目干扰 - 默认跳过读取子代理结果，以避免在多代理工作流期间的噪音 - 在发送新消息时立即中断活动语音 通过 Zed 设置环境变量配置：`SUPER_DEV_VOICE`（语音名称）、`SUPER_DEV_VOICE_RATE`（每分钟字数）、`SUPER_DEV_SPEECH_MODE`（摘要或全文）。 ### 上游合并 适用于分叉或自定义上游模板存储库的项目。运行 `/upstream-merge` 启动有指导的合并工作流。 **设置**：使用 `remote_url` 调用 `upstream_status` 配置上游远程。创建 `.upstream.json`，包含： - **策略**：文件为 `always_ours`（保留您的版本）、`always_theirs`（采用上游）或 `manual_review`（始终停止并询问） - **类别**：按类型（依赖项、UI 组件、基础设施）分组文件，带有 glob 模式 **合并工作流：** 1. **评估**：检查落后多少个提交，审查更改内容 2. **启动合并**：创建专用分支，识别冲突，分类所有更改的文件 3. **解决**：批量解决具有明确策略的文件，然后逐一处理手动冲突，带有差异和建议 4. **验证**：运行类型检查、lint 和测试以验证结果 5. **完成**：提交、合并到目标分支、清理 合并解决工具（`upstream_categorize_changes`、`upstream_resolve_file`、`upstream_resolve_batch`、`upstream_diff_file`、`upstream_verify`、`upstream_complete`、`upstream_abort`）仅在活动合并期间出现，然后在完成或中止时消失。 --- ## 架构 几个刻意的设计选择： **最小工具表面**。MCP 工具消耗上下文窗口和代理的决策开销。每个始终可见的工具都必须证明其存在。相关操作合并为单个工具，带有可选参数（例如，`upstream_status` 处理初始化、状态检查和合并启动），而不是暴露三个单独的工具。 **渐进式工具暴露**。仅在特定工作流期间需要使用的工具在需要时隐藏。例如，7 个上游合并解决工具仅在合并启动后出现，然后在完成或中止时消失。同样，`spec_analyze` 仅在需求阶段出现。这使代理保持专注。 **合并提示**。通过合并相关工作流来保持斜杠命令的最小数量。例如，`/design` 处理构建新的 UI 和完善现有的表面，而不是分成单独的 build/polish/setup 命令。代理根据上下文确定模式。 **提示用于编排，工具用于机械操作**。像 spec 规划、代码审查和设计等多个步骤工作流由提示（Markdown 指令）驱动，让代理适应上下文。工具处理机械部分：创建文件、管理状态转换、标记任务完成、git 操作。规格工作流是最具工具性的，带有 5 个用于管理生命周期的工具，但实际规划和决策发生在提示中。 ## 扩展 **添加斜杠命令**：在 `prompts/` 中添加 `.md` 文件。第一个 `# Heading` 成为描述。 **添加工具**：在 `src/lib/` 中创建模块，导出 `ToolDef[]` 数组，在 `src/index.ts` 中注册。 **添加规则**：在项目的 `.rules/` 中创建带有 YAML 前置元数据的 `.md` 文件（参见 [项目规则](#项目规则)）。 ## 脚本 | 命令 | 描述 | |---------|-------------| | `npm run build` | 编译 TypeScript 到 `dist/` | | `npm run dev` | 直接通过 tsx 运行 | | `npm start` | 运行编译后的服务器 | ## 许可证 [MIT](LICENSE)