inquisitor

<div align="center"> # 探问者 **人工智能代理的假设驱动问题解决** 探测 · 证伪 · 升级 — 永不过度复杂化，永不盲目重试 [](https://python.org) [](https://modelcontextprotocol.io) [](https://github.com/astral-sh/uv) [](https://github.com/1111111111111111111114oLvT2/inquisitor/actions/workflows/ci.yml) []() </div> <!-- mcp-name: io.github.1111111111111111111114oLvT2/inquisitor --> ## 概述 **探问者** 使人工智能代理以类似国际象棋引擎思考问题的方式解决问题的能力：它无法探索每一个分支，因此它**首先估计复杂度，修剪没有增加信息的路径，并仅在问题实际存在的地方花费搜索预算**。 它作为两个协调层提供： - **MCP 服务器** (`inquisitor-mcp`) — 引擎。网页搜索、项目分析、代码跟踪、项目脚手架和持久性调查状态机。与任何兼容MCP的代理一起工作：OpenCode、Claude Code、Claude Desktop、Cursor。 - **代理技能** (`skills/inquisitor/SKILL.md`) — 行为层。将探测-门控循环、修剪规则和完整方法论注入代理的推理中。 该方法并非在此发明 — 它是从原始资料中组装而成：牛顿的分析→综合骨架，通过科学方法的自身防御机制（证伪、强推断、竞争假设分析、反固定重构、预死）加强，并受工程学科（NASA/JPL的十项原则、安全变更指南、最简主义阶梯）的约束。每个来源都在[基础](#基础)中引用。 > 网页搜索、代码库扫描和代码跟踪是**在本地证据不足时调用的工具 — 永不是强制性仪式**。 --- ## 它如何决策 **深度是一个输出，而不是一个标签**。LLM的前置难度猜测是其最不可靠的信号 — 校准不良，并倾向于低估那些重要的困难问题。因此，探问者永远不会在理解问题之前对问题进行分类：它运行一个廉价的**探测**（确认或杀死最佳当前假设的最廉价行动），而探测的*结果* — 而不是预测 — 设置深度： ```mermaid flowchart TD P([问题]) --> F["框架<br>完成 = ？ · 不能破坏 = ？"] F --> D{"委托？<br>专家技能<br>拥有此技能"} D -->|是| SK["交接 — /tdd,<br>/code-review, ..."] D -->|否| PR["探测<br>最廉价的行动，可以确认<br>或杀死最佳假设"] PR -->|"明显，当地"| SH["<b>浅</b><br>修复 → 验证<br><i>无仪式</i>"] PR -->|"明确的单一<br>组件原因"| ST["<b>标准</b><br>框架 → 最小证据<br>→ 修复 → 验证"] PR -->|"根因未知,<br>多组件"| DE["<b>深</b> — 牛顿7阶段：<br>定义 → 公理 → 分析 →<br>实验 → 综合 →<br>验证 → 查询<br><i>+ 会话跟踪作为内存</i>"] SH -.->|"门触发器 /<br>失败修复 / 低置信度"| ST ST -.->|"门仅提高深度 —<br>永不降低"| DE ``` **升级是强制的，而不是允许的**。探测只是一个起点：目标门控触发器（触及基础设施/部署/路由/配置，身份验证/安全，数据迁移，多文件修复，仅限生产症状）强制执行最小深度，而不管问题感觉多么“清晰”，而3个问题置信度检查（读取运行时路径？能命名运行时信号？验证平台假设？）会因未回答的问题而提高深度。降级需要引用的证据，而不是感觉。**膨胀仪式也不被允许** — 7阶段调查一个简单的错误与盲目猜测同样错误。 **重试从不盲目**。 “循环直到成功”代理（Ralph-loop模式）具有持久性但没有记忆：失败后，它们恢复、刷新并重新滚动 — 相同的错误想法，以新的信心重试。探问者相反，它保留一个失败账本：每个死亡假设都记录有杀死它的证据，每个重试都必须说明有什么不同以及为什么这会改变结果，而两个来自同一家族的死亡假设会强制重新构建 — 重新审计假设，逆转问题，拓宽系统边界 — 而不是第三次尝试相同的想法。具有记忆的持久性，基于证据的创造力。 --- ## 基础 每条规则在方法中都追溯到原始资料。左边一列是引用，右边一列是探问者采取的确切机制。 ### 科学方法 | 来源 | 采用的机制 | |--------|-------------------| | 艾萨克·牛顿， [*Opticks*, 查询31](https://www.gutenberg.org/ebooks/33504) (1704) | 调查骨架：分析前综合 — 定义、分解、实验，然后再构造 — 以开放式查询结束，而不是虚假的确定性。 *我不捏造假设。* | | T.C. Chamberlin, [*多重工作假设的方法*](https://www.science.org/doi/10.1126/science.148.3671.754), 科学 (1890) | 始终保持至少两个竞争性解释；单一假设将每个后续观察转化为确认。 | | 亚伯拉罕·鲁钦斯， *问题解决中的机械化* (1942) — [Einstellung效应](https://en.wikipedia.org/wiki/Einstellung_effect) | 失败账本的触发器：重复熟悉的方法，在它停止工作后，是一个可衡量的固执，而治愈方法是一个强制的重构，而不是另一次尝试。 | | 卡尔·波普尔， [*科学发现的逻辑*](https://en.wikipedia.org/wiki/The_Logic_of_Scientific_Discovery) (1959) | 证伪首先：对于领先的假设，命名会驳斥它的观察，并在寻找该观察之前进行任何其他操作。 | | 约翰·普拉特， [*强推断*](https://www.science.org/doi/10.1126/science.146.3642.347), 科学 (1964) | 设计*排除*假设的实验，而不是佐证最喜欢的实验 — 区分性测试优于确认性测试。 | | 理查兹·J·海尔， [*情报分析的心理学*](https://www.cia.gov/resources/csi/books-monographs/psychology-of-intelligence-analysis-2/), 中央情报局 (1999) | 竞争假设分析：按与每个假设*不一致*的证据对假设进行排名 — 确认证据很便宜，通常一次适合多个假设。 | | 加里·克莱因， [*进行项目预死亡分析*](https://hbr.org/2007/09/performing-a-project-premortem)，哈佛商业评论 (2007) | 在交付之前：假设修复已经上线且问题仍然存在 — 找出最可能的原因并现在探测它。 | ### 工程学科 | 来源 | 采用的机制 | |--------|-------------------| | 杰拉德·J·霍尔兹曼（NASA/JPL）， [*十项原则：编写安全关键代码的规则*](https://spinroot.com/gerard/pdf/P10.pdf) (2006) | P10模板：一套足够小、严格到可以机械检查的规则集。 | | 安德烈·卡帕西的LLM编码指南](https://github.com/forrestchang/andrej-karpathy-skills) (2025) | 三思而后行 · 简洁第一 · 手术变更 · 目标驱动执行。 | | [Ponytail决策阶梯](https://github.com/dietrichgebert/ponytail) | 不再需要即刻实施 → 重用 → 标准库 → 原生平台 → 已安装依赖 → 一行 → 最少代码。 | --- ## 安装 需要 [uv](https://github.com/astral-sh/uv) 和 Python 3.12+。 ### Claude Code — 插件安装（推荐） 探问者作为一个 [Claude Code 插件](https://code.claude.com/docs/en/plugins) 提供，它安装了**技能和MCP服务器** — 无需克隆，无需编辑绝对路径，无需手动符号链接。 从Claude Code内部，首先添加市场： /plugin marketplace add 1111111111111111111114oLvT2/inquisitor 然后安装插件： /plugin install inquisitor@inquisitor 就是这样。插件捆绑了 `inquisitor-mcp` 服务器（通过 `${CLAUDE_PLUGIN_ROOT}` 自动注册）和 `inquisitor` 技能。 `uv` 在第一次启动时同步服务器的依赖项。稍后使用 `/plugin marketplace update inquisitor` 更新。 > 喜欢指向本地checkout而不是GitHub？ `/plugin marketplace add /path/to/inquisitor` 也有效。 对于 **OpenCode** 和 **Claude Desktop** （它们不使用Claude Code插件），或手动Claude Code设置，请使用以下步骤。 ### 步骤 1 — 获取服务器 **选项 A — 无克隆（推荐）**。一旦发布到PyPI，`uvx` 按需获取并运行它 — 无克隆，无绝对路径： ```bash uvx inquisitor-mcp # 打印一条就绪消息并等待客户端 — Ctrl+C 退出 ``` 您将在下面的配置中直接引用 `uvx inquisitor-mcp`。 **选项 B — 从checkout**（适用于本地开发，或在PyPI发布之前）： ```bash git clone https://github.com/1111111111111111111114oLvT2/inquisitor.git ~/tools/inquisitor cd ~/tools/inquisitor uv sync ``` > 克隆路径由您决定 — 只需在下面的配置中使用**相同的绝对路径**。 `~` 在 JSON 配置文件中不扩展，因此请写入完整路径（例如 `/home/you/tools/inquisitor`）。 您**不**手动运行服务器。它是一个_stdio MCP服务器：您的代理自动生成和管理它。 （如果您手动运行，它会打印stderr就绪消息并保持沉默 — 这是正常的。） ### 步骤 2 — 将MCP服务器注册到您的代理 **OpenCode** — 添加到 `~/.config/opencode/opencode.json`（全局）或 `./opencode.json`（按项目）： ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "inquisitor": { "type": "local", "command": ["uvx", "inquisitor-mcp"], "enabled": true } } } ``` **Claude Code** — 添加到 `.mcp.json` 到您的项目，或 `~/.claude.json` 到所有项目： ```json { "mcpServers": { "inquisitor": { "command": "uvx", "args": ["inquisitor-mcp"] } } } ``` **Claude Desktop** — 与 `claude_desktop_config.json` 中的相同块（设置 → 开发者 → 编辑配置）。 > 使用checkout而不是 `uvx`？用 `uv` 替换命令，用参数 `["run", "--directory", "/home/you/tools/inquisitor", "inquisitor-mcp"]`。 ### 步骤 3 — 安装技能（行为层） 对其进行符号链接以保持更新： ```bash # OpenCode mkdir -p ~/.config/opencode/skills ln -s /home/you/tools/inquisitor/skills/inquisitor ~/.config/opencode/skills/inquisitor # Claude Code mkdir -p ~/.claude/skills ln -s /home/you/tools/inquisitor/skills/inquisitor ~/.claude/skills/inquisitor ``` （复制文件夹也行 — 您只需在更新后复制即可。） **或，无克隆** — 使用 [`skills`](https://github.com/vercel-labs/skills) CLI跨代理安装技能： ```bash npx skills add 1111111111111111111114oLvT2/inquisitor ``` （此安装仅限技能。为了 `inquisitor_*` 工具，您仍然需要来自步骤 1-2 的MCP服务器 — 或使用上面的Claude Code插件，它捆绑了两者。） ### 步骤 4 — 重启您的代理 配置在启动时加载。退出并重新打开OpenCode / Claude Code，然后验证： `inquisitor_*` 工具出现在工具列表中，并且 `inquisitor` 技能可用。 --- ## 工具 | 工具 | 目的 | 何时 | |------|---------|------| | `inquisitor_search` | 多后端网页搜索（DuckDuckGo 免费/无密钥，Brave，SearXNG）+ 内容提取（HTML + PDF） | 本地证据不足：未知错误、不熟悉的库、当前最佳实践 | | `inquisitor_analyze` | 项目概述：语言、框架、测试、依赖项、git 历史记录 | 进入不熟悉的代码库 | | `inquisitor_trace` | 符号跟踪：定义、调用者、被调用者 `file:line` 引用 | Bug 跨多个函数/文件 | | `inquisitor_phase_get` / `_set` | 牛顿 7 阶段状态机，基于 SQLite 按项目存储；正向移动一次，始终允许后退循环 | 深入调查 — 跨回合持久内存 | | `inquisitor_verify` | 完整性检查：每个阶段是否记录？证据是否引用？（语义验证 — 矛盾，定义满足 — 与代理保持一致） | 在声明深入调查完成之前 | | `inquisitor_scaffold` | 最小项目脚手架，具有研究的最佳实践 | 新项目设置后，需求澄清后 | ### 示例：`inquisitor_search` ```python inquisitor_search( query="httpx ConnectTimeout 重试模式", max_results=8, time_range="year", # day | week | month | year include_domains=["github.com"], # optional site: filter fetch_content=True, # full page text, not just snippets ) ``` ### 示例：阶段跟踪（深路径） ```python inquisitor_phase_set( target_phase="experiment", findings="500 only occurs when session token > 4KB", evidence="repro script output; nginx.conf:34 large_client_header_buffers", open_questions="why did token size grow after v2.3 deploy?", ) --- ## 项目结构 ``` inquisitor/ ├── src/inquisitor/ │ ├── server.py # MCP 入口点（FastMCP，6 个工具） │ ├── config.py # env 配置 │ ├── tools/ # 薄MCP适配器 │ │ └── search / analyze / trace / scaffold / phase / verify │ └── backend/ # 纯Python，无MCP依赖 │ ├── search.py # DDG / Brave / SearXNG + 重新排名 │ ├── extract.py # trafilatura → readability fallback, SSRF guard │ ├── analyzer.py # 项目结构扫描 │ ├── tracer.py # 调用者 / 被调用者映射 │ └── phase_tracker.py # 牛顿状态机（sqlite） │ ├── skills/inquisitor/SKILL.md # 行为层 │ ├── .claude-plugin/ │ ├── plugin.json # Claude Code 插件清单 │ └── marketplace.json # 自托管市场（源自“.”） ├── tests/ # 36 个测试 ``` `backend/` 包是可独立导入的 — 无需MCP： ```python from inquisitor.backend.search import search results = search("python asyncio best practices", max_results=5) ``` --- ## 环境变量 | 变量 | 是否必需 | 默认值 | 描述 | |----------|----------|---------|-------------| | `INQUISITOR_SESSION_DIR` | 否 | `~/.inquisitor/sessions/` | 调查状态存储 | | `BRAVE_API_KEY` | 否 | — | Brave Search 后端（2k 免费/月） | | `SEARXNG_URL` | 否 | — | 自托管 SearXNG 实例 | | `INQUISITOR_DEFAULT_ENGINE` | 否 | `ddg` | `ddg` \| `brave` \| `searxng` | | `INQUISITOR_SEARCH_TIMEOUT` | 否 | `15` | HTTP 超时（秒） | | `INQUISITOR_MAX_CONTENT_LENGTH` | 否 | `40000` | 抓取页面最大字符数 | | `INQUISITOR_PREFERRED_DOMAINS` | 否 | — | 搜索结果中提升的域名（逗号分隔） | | `INQUISITOR_PDF_BACKEND` | 否 | `auto` | PDF 提取：`auto` \| `docling` \| `pypdf` | 无需 API 密钥 — DuckDuckGo开箱即用。 ### PDF 提取 搜索结果和获取的URL为PDF（RFCs，规格，论文，数据表）的文件将被提取，而不是跳过。默认策略是 `auto`，使用 **pypdf** （纯Python，快速，无模型，无需GPU）除非安装了docling且存在GPU。 对于复杂表格或扫描/OCR PDF，请安装可选的 **docling** 后端： ```bash uv pip install "inquisitor-mcp[docling]" # 或：pip install "inquisitor-mcp[docling]" ``` docling 依赖项较重（拉取 `torch` + 机器学习模型）且在CPU上较慢，因此 `auto` 仅在安装了 **且** 存在GPU时才使用它；否则它会回退到pypdf。强制使用 `INQUISITOR_PDF_BACKEND=docling` （可在CPU上运行，只是较慢），或使用 `INQUISITOR_PDF_BACKEND=pypdf` 固定pypdf。任何docling失败都会回退到pypdf，因此PDF读取永远不会硬失败。 --- ## 安全 - **SSRF 防护**：内容获取拒绝非http(s) 方案和环回/私有/链路本地/元数据目标 (`localhost`, `127.0.0.1`, `10.x`, `192.168.x`, `169.254.169.254`, …)。 - **路径遍历防护**：会话名称在触及文件系统之前进行清理。 - **无Shell执行**：子进程调用使用参数列表，而非 `shell=True`。 - **参数化SQL** 贯穿整个会话存储。 - 服务器在本地stdio上运行，使用您的用户权限 — 它不监听网络。 --- ## 配套技能 探问者既是路由器又是调查员 — 它将任务委托给专用技能（ `/tdd`，`/code-review`，...），但它永远不会为您安装它们。参见 **[docs/companion-skills.md](docs/companion-skills.md)** 获取精选的配套技能值得安装（mattpocock/skills，spec-kit，last30days，ponytail，gstack）以及设计参考。 --- ## 开发 ```bash uv sync # 安装依赖 uv run pytest tests/ -v # 运行测试 uv run ruff check . # 检查代码风格 ``` ## 技术 - **uv** — 包管理器 - **FastMCP** — MCP 服务器框架 - **ddgs / httpx** — 搜索 + HTTP - **trafilatura + readability-lxml** — 内容提取（两层级联） - **SQLite** — 调查状态 - **pytest / ruff** — 测试和代码风格检查 --- ## 致谢 研究资料在[基础](#基础)中引用。实现还基于： - **[andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)** （forrestchang） — 从 [Andrej Karpathy 的观察](https://x.com/karpathy/status/2015883857489522876) 中得出的行为指南。 - **[ponytail](https://github.com/dietrichgebert/ponytail)** （Dietrich Gebert） — 决策阶梯和懒惰高级开发人员规则。 - **[last30days-skill](https://github.com/mvanhorn/last30days-skill)** （mvanhorn） — 多源研究设计灵感和 SKILL.md 作为合同模式。 MIT 许可。