# need-overthink-mcp（小鲸鱼爱多想）

一个给 MCP 客户端 / Agent / Dify 工作流用的“新想法顶层设计 + 视野扩展 + 风险评估”工具。

## 解决什么

当用户提出一个**新想法**，且现有缓存/知识库**没有命中**时，AI 不应该直接闷头给方案，也不该假设人已经了解所有相关技术。
这个 MCP 工具会：

1. 识别想法所属技术领域（视觉、音频、LLM、IoT、Web、机器人、数据、视频……）；
2. 基于内置领域知识库，或接收调用方传入的外部搜索结果，整理一批相关技术；
3. 生成一个**长多选反问**：“下面这些技术里，哪些你已经听过/用过/有概念？”；
4. 同时固定给出**拓展视野选项**：直接给方案 / 去 GitHub 找思路 / 拆解上位设计 / 反向梳理 / 风险评估；
5. 用户确认技术后，再对选中的技术追问具体设定、版本、环境；
6. 遇到具体概念（如 K8s RBAC、MCP、RAG）时，可以**向上拆解上位设计**，也可以**反向梳理它到底解决什么问题**。

这样 AI 既能从用户已有概念出发，也能帮人打开视野，把顶层设计和风险评估交给人来拍板。

## 工具

| 工具 | 参数 | 说明 |
|---|---|---|
| `probe_idea_question` | `idea`、`domain?`、`search_results?`、`max_options?` | 核心工具：缓存未命中时，生成 `question + options` 的多选反问 |
| `probe_technology_details` | `idea`、`selected_technologies?`、`selected_ids?` | 第二步：用户确认技术后，对每项技术追问版本/环境/部署等具体设定 |
| `list_design_options` | `idea`、`domain?`、`search_results?`、`max_options?` | 列出技术选项 + 固定位视角选项（GitHub/上位/反推/风险等） |
| `search_github_ideas` | `idea`、`github_results?`、`query?` | 去 GitHub 找思路，提炼别人怎么做 |
| `analyze_upper_design` | `subject`、`idea?` | 拆解上位设计：从具体概念上升到通用模型，再分析实现 |
| `reverse_reasoning` | `subject`、`idea?` | 反向梳理：从具体方案反推它解决什么问题、我们需要吗 |
| `assess_risks` | `idea`、`design?` | 快速风险评估，给人做顶层决策 |
| `finalize_plan` | `idea`、`design?`、`decisions?` | 汇总成高层计划，供人审阅和拍板 |
| `capture_idea` | `idea`、`goal?`、`constraints?`、`preferred_approach?` | 记录新想法、目标和约束，作为顶层设计入口 |
| `save_insight` | `subject`、`insight_type`、`content`、`related_idea?` | 保存设计洞察/学习卡片，方便后续反查 |
| `list_insights` | `subject?`、`insight_type?` | 检索已保存的上位设计/反推/GitHub 思路/风险卡片 |
| `add_design_node` | `name`、`kind?`、`note?` | 在设计树/双向关系图添加节点 |
| `add_design_relation` | `source`、`target`、`relation` | 在设计树添加关系（implementation_of / solves / related / trigger） |
| `get_design_tree` | `subject`、`depth?` | 从设计树取出上位设计、实现分支、反推问题、相关概念 |
| `get_design_graph` | 无 | 返回整张设计树/双向关系图 |
| `create_harness_workflow` | `idea`、`goal?` | 创建顶层设计工作流 |
| `advance_harness_workflow` | `workflow_id`、`completed_step?` | 推进工作流到下一步 |
| `list_harness_workflows` | 无 | 列出当前工作流 |
| `find_related_technologies` | `idea`、`domain?`、`max_options?` | 辅助工具：只看相关技术清单，不生成反问 |

## 工作流示例

```
用户：我想做一个能识别猫的树莓派摄像头
  ↓
知识库/缓存查询：未命中
  ↓
（可选）外部搜索：["YOLO: 目标检测", "MediaPipe: 手部/物体跟踪", "树莓派: 边缘硬件"]
  ↓
MCP 调用：probe_idea_question(
    idea="我想做一个能识别猫的树莓派摄像头",
    search_results=["YOLO: 目标检测", "MediaPipe: 手部/物体跟踪", "树莓派: 边缘硬件"]
)
  ↓
返回：
{
  "cache_hit": false,
  "should_ask": true,
  "question": "关于……先确认一下：下面这些技术里，哪些你已经听过/用过/大致知道是干嘛的？可以多选……",
  "options": [
    {"id": 1, "name": "YOLO", "hint": "目标检测模型", "category": "视觉/检测"},
    {"id": 2, "name": "MediaPipe", "hint": "Google 跨平台视觉方案", "category": "视觉/交互"},
    ...
  ],
  "answer_hint": "请回复编号（如 1,3,5）……"
}
```
用户回复：`1,2,3`（表示对 YOLO、MediaPipe、树莓派有概念）
    ↓
MCP 调用：probe_technology_details(
    idea="我想做一个能识别猫的树莓派摄像头",
    selected_ids="1,2,3"
)
    ↓
返回：
{
  "ok": true,
  "selected_technologies": ["YOLO", "MediaPipe", "树莓派 / Pi Camera"],
  "technology_details": [
    {
      "technology": "YOLO",
      "category": "视觉/检测",
      "questions": [
        "你心里想用 YOLOv5 / YOLOv8 / YOLO11，还是其他版本？",
        "是要自己训练模型，还是只用别人训练好的预训练权重？",
        "训练和推理环境是什么？最终要部署在哪里？"
      ]
    },
    {
      "technology": "MediaPipe",
      "category": "视觉/交互",
      "questions": [
        "你用的是 MediaPipe Tasks 还是 Legacy API？",
        "需要人脸/手势/姿态/目标检测中的哪个能力？",
        "目标平台是 Python / Android / iOS / Web / 树莓派？"
      ]
    },
    {
      "technology": "树莓派 / Pi Camera",
      "category": "硬件/视觉",
      "questions": [
        "你手上是树莓派哪个型号（Zero / 3B+ / 4B / 5）？",
        "系统是 Raspberry Pi OS 还是 Ubuntu Server？",
        "摄像头是官方 Pi Camera 还是 USB 摄像头？"
      ]
    }
  ],
  "question": "关于……你已经确认了这些技术，我再确认几个具体设定……",
  "answer_hint": "请逐项告诉我版本、环境、目标平台和限制……"
}
```

## 视野扩展示例

```text
用户：我在了解 MCP 时看到了 K8s RBAC，为什么会有这个东西？

→ analyze_upper_design(subject="K8s RBAC")
  上位设计：权限控制 / 访问控制
  实现分支：ACL / RBAC / ABAC / 策略引擎 / 云 IAM

→ reverse_reasoning(subject="K8s RBAC")
  原始问题：多用户、多资源环境下，需要明确谁能对什么资源做什么操作
  反查：我们的项目里是否真的需要 RBAC？
       如果只是内部单用户工具，可以先不做；如果是多用户系统，再引入简化版角色权限。

→ search_github_ideas(idea="MCP 权限管理")
  去 GitHub 看看别人怎么给 MCP Server/Client 做权限、鉴权和工具白名单。
```

## 安装与接入（AI 自装）

把本仓库位置（GitHub）告诉你的 AI 客户端，AI 会自行完成接入：

1. 读本 README 与 `pyproject.toml`，确认环境（Python 3.11+ 与 uv）；
2. 用 `uvx need-overthink`（免安装即可运行）或 `uv pip install -e .` 就位；
3. 按当前宿主接入：DeepSeek Harness 导入 preset；Claude Code 执行
   `claude mcp add need-overthink -- uvx need-overthink`；
4. 自检 19 个工具可调用后，向人汇报完成。

> 首次安装需要人工授权；后续更新走白名单静默升级。

## DeepSeek Harness 工作流编排

```text
create_harness_workflow(idea="MCP 权限管理方案", goal="判断是否需要 RBAC")
  ↓
workflow #1 创建成功
  ↓
advance_harness_workflow(workflow_id=1)
  ↓
下一步：list_design_options
```

工作流默认编排：

```text
capture_idea
→ list_design_options
→ analyze_upper_design
→ reverse_reasoning
→ assess_risks
→ finalize_plan
```

## 设计树 / 双向关系图示例

```text
add_design_node(name="K8s RBAC", kind="tech")
add_design_node(name="权限控制", kind="design")
add_design_relation(source="K8s RBAC", target="权限控制", relation="implementation_of")
add_design_relation(source="K8s RBAC", target="多用户环境下的越权风险", relation="solves")

get_design_tree(subject="K8s RBAC")
  ↓
{
  "upper_designs": ["权限控制"],
  "implementations": [],
  "reverse_problems": ["多用户环境下的越权风险"],
  "related": ["RBAC / ABAC / ACL / 策略引擎"]
}
```

## 更多上位设计知识库

目前已补入：

- 插件系统 / 可扩展架构
- 异步消息 / 事件驱动架构
- 缓存与性能加速
- 多租户架构
- 工作流编排 / 流程引擎
- 实时通信架构
- MLOps / 模型生命周期管理
- 可观测性
- 身份认证与会话管理
- 状态机 / 有限状态机
- 幂等 / 重试 / 分布式可靠性
- API 网关 / 统一入口


## 开发与运行

```powershell
cd need-overthink-mcp
uv sync          # 或 pip install -e .
uv run need-overthink              # stdio（默认）
uv run need-overthink sse          # 可选
uv run need-overthink streamable-http   # 可选
```

## 客户端接入示例（Claude Desktop / Dify MCP 插件）

```json
{
  "mcpServers": {
    "need-overthink": {
      "command": "D:\\11\\Ayxi\\ai infra\\need-overthink-mcp\\.venv\\Scripts\\need-overthink.exe"
    }
  }
}
```

> 如果已经 `uv sync`，可以用 `uv run uv build` 或 `pip install .` 后，用 `where need-overthink` 查实际路径。

## 设计说明

- **不真正联网**：`search_results` 由上游 Agent/搜索引擎传入；工具也内置了常见领域知识，保证没有外部搜索也能给出可用的追问。
- **进程内缓存**：同一 `idea + domain + search_results` 会缓存，避免重复打扰用户；重启后清空，适合接入层再做持久缓存。
- **结构化返回**：除了自然语言 `question`，还返回 `options`，方便前端渲染成多选按钮/复选框，或让 LLM 稳定转述。
- **轻依赖**：只依赖 `mcp>=2`，Python 3.11+。