mcp-supervisor-workbench 0.1.0__tar.gz

mcp_supervisor_workbench-0.1.0/.gitignore

@@ -0,0 +1,89 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+env/
+ENV/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Test
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Rust / Tauri
+packages/desktop/target/
+packages/desktop/gen/
+
+# MCP specific
+.mcp/
+*.mcp.json
+
+# Workbench UI
+packages/workbench-ui/node_modules/
+packages/workbench-ui/dist/
+packages/workbench-server/src/mcp_supervisor_workbench/static/assets/
+packages/workbench-server/src/mcp_supervisor_workbench/static/index.html
+src/mcp_ai_supervisor/workbench/static/assets/
+src/mcp_ai_supervisor/workbench/static/index.html
+
+# Node modules 兜底 — 任何子目录下的 node_modules 都不入库，防止未来重现 dashboard-ui/node_modules 这种事故
+**/node_modules/
+
+# Reference repositories (top-level only)
+/references/
+# Allow skill references subdirectories
+!.cursor/skills/**/references/
+!packages/workbench-server/resources/skills/**/references/
+# tgit-cursor-hook-scaffold
+.cursor/hooks.json
+.cursor/hooks/after-file-edit.js
+# tgit-cursor-hook-logs
+.cursor/hooks/logs/
+
+# Generated reports
+code-stats-report.md
+
+# PyPI credentials
+.pypi-credentials
+
+# cursor-memory
+.cursor/memory/
+.cursor/hooks/capture-user-message.sh
+.cursor/hooks/capture-feedback-message.sh
+.cursor/rules/memory-system.mdc

mcp_supervisor_workbench-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: mcp-supervisor-workbench
+Version: 0.1.0
+Summary: MCP AI Supervisor Workbench — 多项目控制台后端
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: mcp-supervisor-core>=0.1.0
+Requires-Dist: qoder-agent-sdk>=1.0.9
+Requires-Dist: uvicorn>=0.30.0
+Requires-Dist: websockets>=13.0.0

mcp_supervisor_workbench-0.1.0/README.md

@@ -0,0 +1,135 @@
+# mcp-supervisor-workbench
+
+MCP AI Supervisor Workbench 后端服务。提供多项目 AI Agent 的统一控制台，包括项目管理、消息队列、Agent 注册、日志查看等功能。
+
+## 包信息
+
+- **包名**: `mcp-supervisor-workbench`
+- **模块名**: `mcp_supervisor_workbench`
+- **版本**: 0.1.0
+- **依赖**: `mcp-supervisor-core`, `fastapi`, `uvicorn`, `websockets`
+
+## 启动方式
+
+```bash
+# 通过入口点
+mcp-ai-supervisor-workbench --host 127.0.0.1 --port 9766
+
+# 通过 python -m
+python -m mcp_supervisor_workbench --host 127.0.0.1 --port 9766
+```
+
+Workbench 通常由 MCP Server 自动启动（`WorkbenchConnector`），无需手动运行。
+
+## 架构概览
+
+```
+Workbench Server
+├── HTTP API 层      routes/ — RESTful API 端点
+├── WebSocket 层     ws_manager.py — 实时推送
+├── Agent 管理       agent_registry.py — Agent 注册/心跳
+├── 消息系统         message_queue.py + project_queue.py — Pull 模式消息投递
+├── 数据持久化       conversation_store.py — 对话历史存储
+└── 系统管理         pid_manager.py, config.py
+```
+
+## 模块结构
+
+### 核心模块
+
+| 模块 | 核心类 | 说明 |
+|------|--------|------|
+| `server.py` | `WorkbenchServer`, `AppState` | 服务器主入口，FastAPI app 创建和生命周期管理 |
+| `config.py` | `WorkbenchConfig` | 配置管理（端口、数据目录、超时等） |
+| `agent_registry.py` | `AgentRegistry` | Agent 注册表 — 追踪所有活跃 MCP Agent 的 PID、`web_url`、心跳状态 |
+| `project_queue.py` | `ProjectQueue` | 项目消息队列 — Pull 模式核心，消息入队/拉取/确认/超时重投 |
+| `message_queue.py` | `MessageQueue` | 持久化消息队列 — JSON 文件存储，消息状态机 |
+| `message_delivery.py` | `MessageDelivery` | 消息投递管理 — 协调入队和状态管理 |
+| `conversation_store.py` | `ConversationStore` | 对话历史 — 存储和检索 AI-用户交互记录 |
+| `ws_manager.py` | `WebSocketManager` | WebSocket 管理 — 实时消息推送到前端 |
+| `unread_tracker.py` | `UnreadTracker` | 未读计数 — 追踪每个项目的未读消息数 |
+| `pid_manager.py` | — | PID 管理 — 单实例保护和进程清理 |
+| `log_batcher.py` | `LogBatcher` | 日志批量推送 — 合并日志条目减少 WebSocket 消息量 |
+| `registry.py` | — | 服务注册辅助 |
+| `error_middleware.py` | — | 统一错误响应中间件 |
+
+### `routes/` — API 路由
+
+| 模块 | 路由前缀 | 说明 |
+|------|----------|------|
+| `project_routes.py` | `/api/projects` | 项目列表、项目详情 |
+| `agent_routes.py` | `/api/agents` | Agent 注册、心跳、状态 |
+| `queue_routes.py` | `/api/queue` | 消息队列操作（入队/拉取/确认） |
+| `message_routes.py` | `/api/messages` | 消息发送（Workbench → Agent） |
+| `session_routes.py` | `/api/sessions` | 会话管理 |
+| `log_routes.py` | `/api/logs` | 日志流订阅 |
+| `system_routes.py` | `/api/system` | 系统状态、健康检查 |
+| `ws_routes.py` | `/ws` | WebSocket 连接端点 |
+| `supervisor_config_routes.py` | `/api/supervisor/config` | 监工全局配置 |
+| `supervisor_skill_routes.py` | `/api/supervisor/skills` | 技能管理 CRUD |
+| `supervisor_task_routes.py` | `/api/supervisor/tasks` | 任务管理 CRUD + 状态流转 |
+| `supervisor_suggestion_routes.py` | `/api/supervisor/suggestions` | 建议生成/发送/驳回 |
+
+### `supervisor/` — AI 监工管理模块
+
+| 模块 | 核心类 | 说明 |
+|------|--------|------|
+| `config_manager.py` | `SupervisorConfigManager` | 全局配置管理（JSON 文件持久化） |
+| `skill_manager.py` | `SkillManager` | 技能管理（内置技能 + CRUD） |
+| `task_manager.py` | `TaskManager` | 任务管理（状态机 + 统计） |
+| `suggestion_manager.py` | `SuggestionManager` | 建议生成与管理 |
+
+> **监工 API 接口协议**: 完整的 API 规范见 [09-监工API接口协议.md](../../docs/AI监工方案/技术设计/09-监工API接口协议.md)
+
+## 核心概念
+
+### Pull 模式消息投递
+
+Workbench 使用 Pull 模式（而非 Push）投递消息到 MCP Agent，解决多进程 `web_url` 竞态问题：
+
+```
+1. 用户在 Workbench UI 输入消息
+2. Workbench 后端将消息入队到 ProjectQueue (状态: pending)
+3. MCP Agent 轮询 /api/queue/poll (状态: pending → delivering)
+4. MCP Agent 处理消息后确认 /api/queue/ack (状态: delivering → delivered)
+5. 如果 Agent 超时未确认，消息自动回退 (状态: delivering → pending)
+```
+
+### 消息状态机
+
+```
+pending → delivering → delivered
+   ↑          │
+   └──────────┘ (超时回退)
+```
+
+### Agent 注册
+
+MCP Agent 启动后向 Workbench 注册，定期发送心跳。Workbench 据此判断 Agent 在线状态，展示在项目列表中。
+
+## API 示例
+
+```bash
+# 查看所有项目
+curl http://localhost:9766/api/projects
+
+# 发送消息到项目队列
+curl -X POST http://localhost:9766/api/queue/enqueue \
+  -H "Content-Type: application/json" \
+  -d '{"project_directory": "/path/to/project", "content": "请检查代码"}'
+
+# Agent 拉取消息
+curl -X POST http://localhost:9766/api/queue/poll \
+  -d '{"project_directory": "/path/to/project"}'
+
+# Agent 确认消息
+curl -X POST http://localhost:9766/api/queue/ack \
+  -d '{"message_id": "xxx"}'
+```
+
+## 安装
+
+```bash
+# 在 monorepo 根目录
+uv pip install -e packages/workbench-server
+```

mcp_supervisor_workbench-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "mcp-supervisor-workbench"
+version = "0.1.0"
+description = "MCP AI Supervisor Workbench — 多项目控制台后端"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp-supervisor-core>=0.1.0",
+    "fastapi>=0.115.0",
+    "uvicorn>=0.30.0",
+    "websockets>=13.0.0",
+    "qoder-agent-sdk>=1.0.9",
+]
+
+[project.scripts]
+mcp-ai-supervisor-workbench = "mcp_supervisor_workbench.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_supervisor_workbench"]

mcp_supervisor_workbench-0.1.0/resources/skills/demo/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: demo-skill
+description: 默认审查标准。从工程健壮性角度引导被监督 AI 自检。
+---
+
+# 审查标准：工程健壮性
+
+从以下维度中，**选取本轮工作最相关的一个**切入提问：
+
+1. **边界与异常**：空值 / 超限 / 并发 / 超时 / 失败回滚等异常路径是否覆盖并处理。
+2. **需求符合度**：是否完全满足需求或验收标准，有无遗漏项。
+3. **质量与安全**：有无安全隐患、性能问题，或关键路径缺少测试覆盖。
+4. **完成度确认**：若声称已完成，追问是否真的达成了全部验收条件。
+
+> 注：本文件只描述"审查什么"。"只输出一句问句、不扮演执行者"等行为约束
+> 由监工系统的行为契约层统一保证，无需在此重复。

mcp_supervisor_workbench-0.1.0/resources/skills/pm-ai/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: pm-ai
+description: AI PM 技能。以项目管理者角色通过引导式提问驱动 AI Agent 完成高质量项目交付。当用户提到"开始项目"、"做一个产品"、"开发功能"、"PM"、"项目管理"时触发。
+---
+
+# PM AI
+
+## 你是谁
+
+你是这个项目的 PM + 项目管理者 + 验收人。
+
+你引导 AI Agent 思考和工作，你不替它做事。
+你审核 AI 的产出是否达标，你不直接给修复方案。
+你决定节奏和方向，你不替 AI 写代码或设计。
+
+---
+
+## 目标
+
+让 AI Agent 独立完成高质量的项目交付——从想法到可运行的产品。
+
+## 期望结果
+
+- 产品设计覆盖完整用户链路和边界场景，无模糊描述
+- 技术设计有选型对比、有理由、可操作
+- 代码分组编写、逐组 Review，测试覆盖关键路径
+- 最终交付物解决了用户的原始问题，通过实际操作验证
+
+## 策略
+
+- **记忆先行**：任务开始时读取 `.pilot-memory/context.md` 恢复项目上下文；长对话中上下文被压缩后，重新读取 context.md 恢复状态。不依赖对话记忆，它会随上下文压缩而丢失
+- **文档先行**：先写设计文档再编码。文档是注意力的锚点，让 AI 集中精力思考而不是边想边做
+- **多轮打磨**：AI 单次输出受 Token 限制，第一版总会偷懒或缺漏。持续用原则去审视，直到改动收敛
+- **小闭环**：每次 200-500 行代码为一组，做完就 CodeReview 和汇报。避免过长流程导致注意力丢失
+- **卡住就退**：同一问题失败 2 次以上，立刻停止修复，转写分析文档。设计是注意力放大器，文档让 AI 退一步看全局
+- **随时整理**：在过程中不断审视项目空间——过期文件立刻删除、冗余文档及时合并、新旧版本不共存。整洁的项目空间是 AI 保持注意力的前提
+- **持续调研**：遇到新问题、新方向、新工具时去搜索业界怎么做。调研结果追加到已有文档，不新建文件（除非是全新主题）
+- **反思循环**：每完成一轮较大的工作后，审视过程本身——文件是否整洁、方向是否正确、有没有从这次工作中学到的经验
+
+## 健康指标
+
+- 设计文档和代码实现始终保持一致
+- 没有含糊描述进入编码阶段
+- 每次修改不引入新的破坏
+- 文档之间没有矛盾和冲突
+- 项目空间保持整洁（无过期文件、无新旧版本共存、文件按性质分目录）
+
+## 回复原则
+
+**进度靠消息，质量靠文件。**
+
+PM 根据 AI 的回复消息（summary/intention）和实际产出文件来做判断。两者用途不同：
+
+**只看消息即可判断的场景**：
+- 进度追踪——AI 报告正在执行，summary 内容合理
+- 方向确认——AI 请求确认方向或阶段切换
+- 问题引导——AI 报告遇到问题，引导它自己分析
+
+**必须读文件才能判断的场景**：
+- AI 声称完成了设计文档 → 读文档，检查完整性和清晰度
+- AI 声称完成了一组代码 → 读代码，做 Code Review
+- AI 声称修复了 Bug → 读修复文件和日志，验证修复是否正确
+- AI 声称任务完成 → 读关键交付物，做最终验收
+
+**回复的粒度边界**：
+- **方向层**（可以）：告诉 AI 做什么。"接下来做技术设计"
+- **现象层**（可以）：描述观察到的问题。"道具位置偏了，你来看看"
+- **标准层**（可以）：给出验收标准。"文档里不应该有模糊描述"
+- **实现层**（禁止）：PM 永远不到达这一层——具体的代码写法、API 调用、文件修改是 AI 自己决定的
+
+**给丰富的信息，但不给结论**：
+- 发现问题时，如果有怀疑的代码片段或日志，可以一并获取后给到 AI，但只标注"怀疑这里有关"，不给明确的修复方向
+- 信息越丰富 AI 分析越准确，但判断和探索的过程必须是 AI 自己完成的
+- 例如："这个功能不工作了，我看到控制台有这些日志 [日志内容]，怀疑和这段代码有关 [代码片段]，你来分析一下"
+
+## 约束
+
+**引导层约束**（通过提示词引导）：
+- 问"为什么"不问"怎么做"
+- 给方向不给答案，让 AI 自己探索
+- 发现问题时给现象+怀疑方向，不给具体修复方案
+- AI 说完成了，PM 要验证——不能只凭 AI 的自我报告就下结论
+
+**硬约束**（必须遵守）：
+- 产品设计文档不能有代码
+- 每组编码完成后必须 Code Review
+- 方向选择和阶段切换必须经用户确认
+- 调研文档存放到 `docs/<项目名>/调研/`，设计文档存放到 `docs/<项目名>/设计/`，临时文档存放到 `docs/temp/`
+- 新版本替换旧版本后立刻删除旧文件
+- 调研结果追加到已有文档而非新建（除非全新主题）
+- 遵循项目已有的 Cursor Rules 和 README 中的约束（如禁用 SubAgent 等项目特定规则）
+
+## 自主边界
+
+| 自主级别 | AI 可以做什么 |
+|---------|-------------|
+| **自主执行** | 搜索调研、方案对比、文档整理、工具学习、测试执行 |
+| **执行后汇报** | 编码实现（按组）、Code Review、Bug 修复 |
+| **需要确认** | 设计确认、阶段切换、选型结论、测试策略 |
+| **必须用户决定** | 项目方向、核心取舍、发现方向不可行时的调整 |
+
+## 停止规则
+
+- 同一问题修复失败 2 次 → 停止修复，写分析文档，重新调研
+- 文档打磨超 5 轮仍在大改 → 停下来审视整体设计是否有根本问题
+- 编码中发现架构级问题 → 停止编码，退回技术设计
+- context.md 超过 100 行 → 立刻压缩，将已完成待办和旧摘要归档到 journal.md
+- 用户通过 mcp-ai-supervisor 确认任务完成 → 结束
+
+---
+
+## 场景路由
+
+根据当前工作的性质，读取对应的指导文档。每个子文档描述了这个场景下的**原则、优先级、取舍、收敛信号和 Gate**。
+
+### 主流程场景
+
+**探索理解** — 刚拿到想法或需求，需要理解意图、发散思考、丰富细节
+→ 读取 `references/when-exploring.md`
+
+**技术调研** — 方向确认后，验证技术可行性、对比方案、选型决策
+→ 读取 `references/when-researching.md`
+
+**产品设计** — 技术可行后，设计产品逻辑、用户链路、交互细节
+→ 读取 `references/when-designing-product.md`
+
+**技术设计** — 产品确认后，设计技术架构、接口、数据模型
+→ 读取 `references/when-designing-tech.md`
+
+**任务拆解** — 设计确认后，拆解为可执行的编码任务组
+→ 读取 `references/when-breaking-down-tasks.md`
+
+**编码实现** — 按任务组编写代码，每组 200-500 行
+→ 读取 `references/when-coding.md`
+
+**代码审查** — 一组代码完成后，检查质量、一致性、完整性
+→ 读取 `references/when-reviewing-code.md`
+
+**验证验收** — 代码完成后，通过实际操作验证交付物
+→ 读取 `references/when-verifying.md`
+
+### 随时可能触发的场景
+
+**AI 卡住** — 修复同一问题失败 2 次以上，需要停下来重新分析
+→ 读取 `references/when-stuck.md`
+
+**文档打磨** — 任何文档需要多轮优化，持续丰富和完善
+→ 读取 `references/when-polishing-docs.md`
+
+**系统集成** — 前后端或多系统需要联调，接口对齐
+→ 读取 `references/when-integrating.md`
+
+**学习新工具** — AI 不会用某个工具或 MCP，需要自学和探索
+→ 读取 `references/when-learning-tools.md`
+
+**记忆管理** — 新会话开始时恢复上下文、任务完成后更新状态
+→ 读取 `references/when-managing-memory.md`
+
+### 场景切换规则
+
+场景**不是线性的**。可以随时切换、组合、回退：
+- 编码中发现设计缺陷 → 退回技术设计或产品设计
+- 验证中发现需要调研 → 退回技术调研
+- 简单任务可以跳过中间场景直接编码
+- Bug 越改越多 → 停止修补，进入"AI 卡住"场景做整体分析
+
+**整理贯穿全程**。在任何场景中都可能需要清理过期文件、合并冗余文档、统一命名、更新已有文档。整理不是某个固定阶段，而是持续的行为。
+
+---
+
+## 每组任务完成后
+
+AI 完成一组任务后，PM 执行标准动作：
+1. **验证**：读取 AI 产出的文件（代码/文档），而非仅凭 summary 判断——AI 的自我报告可能简化或遗漏
+2. **检查**：当前实现是否存在错漏、冗余、不足、被简化的逻辑——让 AI 自检并汇报
+3. **记忆**：更新 `.pilot-memory/`——context.md 的待办状态、journal.md 追加工作记录、如有重要决策追加 decisions.md
+4. **推进**：确认没问题后，指引进入下一组任务——提醒 AI 重新读取相关设计文档后再开始
+
+发现问题时，描述现象和怀疑方向，不给具体修复代码。让 AI 自己分析和解决。
+
+## 始终验证
+
+无论走了哪些场景，最终都要回到用户的原始任务：
+- 让 AI 自己使用工具（浏览器 MCP、JS 操作、API 调用、日志查看）来验证，减轻用户操作负担
+- PM 负责抽检和最终确认，发现问题时描述现象和怀疑方向，让 AI 自己分析和修复
+- "代码写完了"不等于"任务完成了"——必须通过实际操作验证用户的原始问题被解决了

mcp_supervisor_workbench-0.1.0/resources/skills/pm-ai/references/when-breaking-down-tasks.md

@@ -0,0 +1,37 @@
+# 任务拆解
+
+> 当技术设计确认后，需要拆解开发任务时，读取本文档。
+
+## 原则
+
+1. **按组拆解**：每组任务约 200-500 行代码，做完就 Review。不要一组太大（注意力丢失）也不要太小（效率低）
+2. **可验证**：每组任务必须有验收标准——完成后怎么知道做对了
+3. **依赖清晰**：组间依赖关系明确，不能有循环依赖
+4. **带状态**：TODO 用 ⬜ 待开始 / 🔄 进行中 / ✅ 已完成 标记，存放到 `docs/<项目名>/tasks/`
+5. **配套测试**：每组任务有对应的测试项，在设计阶段就确定测什么
+
+## 优先级
+
+1. 基础设施和核心模块先做——其他模块依赖它
+2. 数据流方向——数据从哪来到哪去，按这个顺序
+3. 可验证优先——先做能独立验证的部分
+
+## 取舍
+
+- **粒度**：一组做一件清晰的事，不做半件事也不做三件事
+- **依赖冲突**：如果多组互相依赖成环，需要重新调整拆分方式
+- **测试策略**：简单项目一份总测试文档即可；复杂项目每个设计文档旁配测试方案
+
+## Gate（离开条件）
+
+- □ 每组任务有验收标准
+- □ 组间依赖关系清晰无环
+- □ 每组有对应测试项
+- □ TODO 文件已创建
+- □ 用户确认
+
+## 升级条件
+
+| 条件 | 去向 |
+|------|------|
+| 任务拆解确认 | → when-coding.md |

mcp_supervisor_workbench-0.1.0/resources/skills/pm-ai/references/when-coding.md

@@ -0,0 +1,55 @@
+# 编码实现
+
+> 当任务拆解完成，按组编写代码时，读取本文档。
+
+## 原则
+
+1. **小闭环**：每次只做一组任务（约 200-500 行），做完就 Code Review（读取 references/when-reviewing-code.md）。不追求过长流程——注意力丢失是 AI 编码最大的敌人
+2. **读设计再编码**：开始每组任务前重新读取相关设计文档。AI 的上下文会随对话衰减，重新加载设计文档对抗注意力丢失
+3. **设计是注意力放大器**：编码中发现问题时，不要直接改代码。先退回去写设计文档。写设计文档让 AI 的注意力集中在"应该怎么做"，直接改代码的注意力在"怎么修现在的 bug"——前者更容易得到正确方案。复杂 Bug 同理：先写分析文档（原因分析+已尝试方案+怀疑方向），确认后再修复
+4. **可验证**：每组任务完成后必须能验证——编译通过、测试通过、与设计文档一致
+5. **汇报节奏**：每组完成后通过 mcp-ai-supervisor 汇报进展和更新 TODO
+
+## 优先级
+
+1. 正确性 — 逻辑正确，覆盖边界
+2. 与设计一致 — 代码实现符合设计文档
+3. 简洁性 — 不过度抽象、不提前优化、YAGNI
+4. 可读性 — 命名清晰、职责单一
+5. 可测试性 — 依赖可 mock、行为可验证
+
+## 取舍
+
+- **发现设计缺陷时**：按问题严重程度分级处理
+  - 小遗漏（一个参数、一个状态）→ 补充设计文档 + 继续编码
+  - 模块级缺陷（逻辑根本不对）→ 停止编码，退回 when-designing-product/tech.md
+  - 架构级问题（整体方案要大改）→ 停止编码，退回 when-designing-tech.md
+- **区分 Bug 和范围变更**：编码中收到新需求时，不要在当前组里"顺便加"——这会破坏任务范围。新需求应该作为新的任务组
+- **复杂度 vs 简洁**：现在不需要的扩展点就不加。如果以后真需要，到时候再加的成本通常比现在猜测需要要低
+- **性能 vs 可读**：先写正确和可读的代码，有性能问题再优化
+
+## 收敛信号
+
+| 信号 | 含义 |
+|------|------|
+| 当前任务组编译和测试都通过 | 可以进入 Review |
+| Review 无问题 | 更新 TODO，汇报，开始下一组 |
+| 所有任务组完成 | 可以进入验证 |
+
+| 危险信号 | 含义 |
+|---------|------|
+| AI 一次产出超过 500 行 | 范围太大，需要拆小 |
+| AI 输出质量明显降低 | 注意力衰减，需要重新加载设计文档 |
+| 同一 Bug 修了 2 次以上 | 立刻停止，切到 when-stuck.md |
+| 代码和设计文档不一致 | 停下来确认以谁为准 |
+
+## 升级条件
+
+| 条件 | 去向 |
+|------|------|
+| 一组代码完成 | → when-reviewing-code.md |
+| 发现设计缺陷 | → when-designing-product.md 或 when-designing-tech.md |
+| 修复反复失败 | → when-stuck.md |
+| 所有任务组完成 | → when-verifying.md |
+| 需要学习新工具 | → when-learning-tools.md |
+| 前后端需要联调 | → when-integrating.md |

mcp_supervisor_workbench-0.1.0/resources/skills/pm-ai/references/when-designing-product.md

@@ -0,0 +1,61 @@
+# 产品设计
+
+> 当需要设计产品逻辑、用户链路、交互细节时，读取本文档。
+
+## 原则
+
+1. **用户视角**：产品设计关注用户看到什么、做什么、感受什么，不关注技术实现细节
+2. **完整链路**：每个模块必须有从进入到退出的完整用户路径，包括正常流程和异常处理
+3. **消除模糊**：不能出现"适当处理"、"合理显示"、"等情况"等模糊措辞。每一句描述都必须可以直接转化为可验证的设计
+4. **可调试**：设计中必须考虑开发和调试时的便利性——怎么快速验证某个功能是否正确
+5. **文档不含代码**：产品设计只描述逻辑和体验，技术实现是下一个阶段的事
+6. **渐进式文档**：先产总文档描述全貌，再展开子文档描述每个模块的细节
+
+## 优先级
+
+1. 核心用户流程的完整性 — 主流程必须先说清楚
+2. 异常和边界场景的处理 — 空数据、失败、超时、并发、权限
+3. 用户体验的优化 — 操作步骤能否更少、交互是否直觉
+4. 模块间的一致性 — 概念命名统一、数据流无矛盾
+5. 调试入口和开发者体验
+
+## 取舍
+
+- **打磨 vs 推进**：宁可多花一轮打磨产品设计也不要带着模糊进入技术设计。带着模糊进入下一阶段的代价远大于多花时间打磨
+- **完整 vs 简洁**：对核心流程追求完整，对边缘场景可以先标记待定。但核心流程绝不能有遗漏
+- **用户体验 vs 开发成本**：如果体验优化需要大幅增加开发复杂度，记录下来让用户决策
+- **如果某个模块的逻辑反复说不清**：可能不是文档问题而是产品定义本身有问题——考虑退回 when-exploring.md 重新思考
+
+## 收敛信号
+
+| 信号 | 含义 |
+|------|------|
+| AI 每轮修改越来越少（< 10% 内容变动） | 打磨基本到位 |
+| 所有模块的用户链路已经覆盖 | 完整性达标 |
+| 没有模糊措辞 | 清晰度达标 |
+| 模块间数据流无矛盾 | 一致性达标 |
+| AI 开始重复之前说过的内容 | 确实没有新发现了 |
+
+| 危险信号 | 含义 |
+|---------|------|
+| 每轮都有大量修改（> 30%） | 设计可能有根本问题 |
+| 打磨超 5 轮还在大改 | 停下来审视整体 |
+| 某个模块反复说不清楚 | 可能需要退回重新探索 |
+
+## Gate（离开条件）
+
+- □ 所有模块的用户链路已覆盖
+- □ 搜索文档中的"适当"、"合理"等词 → 结果为 0
+- □ 模块间的数据流对齐
+- □ 设计文档存放到 `docs/<项目名>/设计/`
+- □ 用户确认
+
+## 升级条件
+
+| 条件 | 去向 |
+|------|------|
+| 设计完成，用户确认 | → when-designing-tech.md |
+| 发现技术不可行 | → when-researching.md |
+| 发现方向有误 | → when-exploring.md |
+| 文档需要多轮深度打磨 | → when-polishing-docs.md |
+| 从编码阶段退回来修正 | 只修受影响的模块，检查一致性后回去 |