inquisitor

概述

inquisitor 让 AI Agent 像国际象棋引擎下棋一样解决问题：它无法探索每一种可能，因此会先估算复杂度，剪除不能带来新信息的路径，并将搜索预算只花在问题真正所在之处。

它由两个协同层组成：

• MCP 服务（inquisitor-mcp）——引擎。提供网络搜索、项目分析、代码追踪、项目脚手架和持久化调查状态机。适用于任何兼容 MCP 的 Agent：OpenCode、Claude Code、Claude Desktop、Cursor。
• Agent 技能（skills/inquisitor/SKILL.md）——行为层。将探查与门控循环、剪枝规则和完整方法论注入 Agent 的推理过程。

此方法并非本项目原创——它由多个一手资料汇编而成：牛顿的分析→综合框架，结合科学方法用于防范错误假设的机制（证伪、强推理、竞争假设分析、反固着式重新构思、事前验尸），并受工程规范约束（NASA/JPL 的 Power of Ten、手术式改动指南、极简主义阶梯）。每项来源都在理论基础中列出。

网络搜索、代码库扫描和代码追踪都是仅在本地证据不足时才调用的工具——绝非必须执行的仪式。

---

如何做出判断

深度是结果，而非标签。大模型对难度的预先猜测，是最不可靠的信号——校准不佳，而且恰恰会低估那些重要的难题。因此，inquisitor 在理解问题之前绝不对其分类：它会先进行一次低成本的探查（能够确认或否定当前最佳假设的最廉价操作），再由探查的结果——而非预测——决定深度：

flowchart TD
    P([Problem]) --> F["FRAME<br/>done = ? · must not break = ?"]
    F --> D{"delegate?<br/>a specialist skill<br/>owns this"}
    D -->|yes| SK["hand off — /tdd,<br/>/code-review, ..."]
    D -->|no| PR["PROBE<br/>cheapest action that could confirm<br/>or kill the best hypothesis"]
    PR -->|"obvious, local"| SH["<b>Shallow</b><br/>fix → verify<br/><i>no ceremony</i>"]
    PR -->|"clear single-<br/>component cause"| ST["<b>Standard</b><br/>frame → minimal evidence<br/>→ fix → verify"]
    PR -->|"root cause unknown,<br/>multi-component"| DE["<b>Deep</b> — Newton 7-phase:<br/>DEFINE → AXIOMS → ANALYSIS →<br/>EXPERIMENT → SYNTHESIS →<br/>VALIDATE → QUERY<br/><i>+ session tracking as memory</i>"]

    SH -.->|"gate trigger /<br/>failed fix / low confidence"| ST
    ST -.->|"gate only raises depth —<br/>never lowers"| DE

升级是强制的，而不只是允许的。 探查只是起点：客观门槛触发条件（涉及基础设施／部署／路由／配置、身份验证／安全、数据迁移、多文件修复、仅在生产环境出现的症状）会强制设定最低深度，无论问题看起来有多“清楚”；而 3 个问题的置信度检查（读过运行时路径吗？能说出运行时信号吗？验证过平台假设吗？）会按未答问题的数量提高深度。降级必须引用证据，不能凭感觉。也不允许虚增流程——对一个拼写错误进行 7 阶段调查，与对竞态条件盲目猜测一样不妥。

绝不盲目重试。 “循环直到通过”的 Agent（Ralph-loop 模式）有持久性，却没有记忆：失败时，它们会回滚、清空状态、重新尝试——用全新的信心重试同一个错误想法。Inquisitor 则维护失败记录：每个被否定的假设都会连同否定它的证据一起记录；每次重试都必须说明有哪些不同之处，以及为何这些差异会改变结果；同一类假设连续两次被否定，就必须重新构思——重新审查某个假设、反转问题、扩大系统边界——绝不再第三次尝试同一个想法。凭记忆保持持久性，依据证据激发创造力。

---

理论基础

该方法中的每条规则都可追溯到一手资料。左栏是引用来源；右栏是 inquisitor 从中采用的具体机制。

科学方法

来源	采用的机制
Isaac Newton，Opticks，Query 31（1704）	调查框架：先分析，再综合——定义、拆解、实验，最后才重构——并以开放式问题收尾，而非假装确定。Hypotheses non fingo.
T.C. Chamberlin，The Method of Multiple Working Hypotheses，《Science》（1890）	始终至少保留两个相互竞争的解释；单一假设会让之后的每项观察都变成确认。
Abraham Luchins，Mechanization in Problem Solving（1942）——定势效应	失败记录的触发条件：熟悉的方法失效后仍反复使用，是一种可测量的固着；破解之道是强制换个角度，而非再次尝试。
Karl Popper，The Logic of Scientific Discovery（1959）	先证伪：针对最有力的假设，指出什么观察结果会推翻它，并优先寻找这种结果。
John Platt，Strong Inference，《Science》（1964）	设计能够排除某个假设的实验，而非证实最受偏爱的假设——选择有区分力的测试，而不是确认性测试。
Richards J. Heuer，Psychology of Intelligence Analysis，CIA（1999）	竞争假设分析：依据各假设与证据不一致的程度进行排序——确认性证据很容易找到，而且通常能同时符合多个假设。
Gary Klein，Performing a Project Premortem，《Harvard Business Review》（2007）	发布之前：假设修复已上线，但问题依然存在——指出最可能的原因，并立即调查。

工程规范

来源	采用的机制
Gerard J. Holzmann（NASA/JPL），The Power of Ten: Rules for Developing Safety-Critical Code（2006）	P10 模板：规则集足够精简，便于记忆；也足够严格，能够通过机械方式检查。
Andrej Karpathy 的 LLM 编码指南（2025）	编码前先思考 · 简洁优先 · 精准修改 · 目标驱动执行。
Ponytail 决策阶梯	YAGNI → 复用 → 标准库 → 原生平台 → 已安装的依赖 → 一行代码 → 能正常工作的最少代码。

---

安装

需要 uv 和 Python 3.12+。

Claude Code — 插件安装（推荐）

inquisitor 以 Claude Code 插件的形式提供，可同时安装技能和 MCP 服务——无需克隆、无需编辑绝对路径，也无需手动创建符号链接。

在 Claude Code 中，先添加市场：

/plugin marketplace add iamalisson/inquisitor

然后安装插件：

/plugin install inquisitor@inquisitor

完成。该插件包含 inquisitor-mcp 服务（通过 ${CLAUDE_PLUGIN_ROOT} 自动注册）和 inquisitor 技能。首次启动时，uv 会同步服务的依赖项。之后可使用 /plugin marketplace update inquisitor 更新。

想指向本地检出版本，而不是 GitHub？/plugin marketplace add /path/to/inquisitor 也可以。

对于OpenCode 和 Claude Desktop（它们不使用 Claude Code 插件），或要手动配置 Claude Code，请使用以下步骤。

步骤 1 — 获取服务

选项 A — 无需克隆（推荐）。 发布到 PyPI 后，uvx 会按需获取并运行它——无需克隆，也无需绝对路径：

uvx inquisitor-mcp   # prints a ready message and waits for a client — Ctrl+C to exit

你将在下面的配置中直接引用 uvx inquisitor-mcp。

选项 B — 从检出版本安装（用于本地开发，或在发布到 PyPI 之前）：

git clone https://github.com/iamalisson/inquisitor.git ~/tools/inquisitor
cd ~/tools/inquisitor
uv sync

克隆路径由你决定——只要在下面的配置中使用相同的绝对路径即可。~ 不会在 JSON 配置文件中展开，因此请写完整路径（例如 /home/you/tools/inquisitor）。

你不需要手动运行服务。这是一个 stdio MCP 服务：你的 Agent 会自动启动并管理它。（如果你手动运行，它会在 stderr 上打印一条就绪消息，然后静默等待——这是正常的。）

步骤 2 — 向 Agent 注册 MCP 服务

OpenCode — 添加到 ~/.config/opencode/opencode.json（全局配置）或 ./opencode.json（项目配置）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "inquisitor": {
      "type": "local",
      "command": ["uvx", "inquisitor-mcp"],
      "enabled": true
    }
  }
}

Claude Code — 添加到项目中的 .mcp.json，或添加到 ~/.claude.json 以供所有项目使用：

{
  "mcpServers": {
    "inquisitor": {
      "command": "uvx",
      "args": ["inquisitor-mcp"]
    }
  }
}

Claude Desktop — 在 claude_desktop_config.json 中添加相同的 mcpServers 块（设置 → 开发者 → 编辑配置）。

使用检出版本而非 uvx？将命令替换为 uv，并使用参数 ["run", "--directory", "/home/you/tools/inquisitor", "inquisitor-mcp"]。

步骤 3 — 安装技能（行为层）

创建符号链接，让它始终与仓库保持同步：

# 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 CLI 在各个 Agent 中仅安装技能：

npx skills add iamalisson/inquisitor

（这只会安装技能。要使用 inquisitor_* 工具，你仍然需要步骤 1-2 中的 MCP 服务——或者使用上文提到的 Claude Code 插件，它已将两者打包在一起。）

步骤 4 — 重启 Agent

配置会在启动时加载。退出并重新打开 OpenCode / Claude Code，然后确认： inquisitor_* 工具出现在工具列表中，并且可以使用 inquisitor 技能。

---

工具

工具	用途	适用场景
inquisitor_search	多后端网络搜索（DuckDuckGo 免费且无需密钥、Brave、SearXNG），并提取内容（HTML + PDF）	本地证据不足：未知错误、不熟悉的库、当前最佳实践
inquisitor_analyze	项目概览：语言、框架、测试、依赖项、Git 历史记录	开始处理不熟悉的代码库
inquisitor_trace	符号追踪：定义、调用方、被调用方及 file:line 引用	Bug 涉及多个函数/文件
inquisitor_phase_get / _set	Newton 7 阶段状态机，按项目存储在 SQLite 中；前进时每次推进一个阶段，始终允许向后循环	深入调查——在多轮对话中保留持久记忆
inquisitor_verify	完整性检查：是否记录了每个阶段？是否引用了证据？（语义验证——矛盾、DEFINE 满足情况——由 Agent 负责）	宣布 Deep 调查完成之前
inquisitor_scaffold	根据经过研究的最佳实践创建最精简的项目脚手架	新项目设置、明确需求之后

示例：inquisitor_search

inquisitor_search(
    query="httpx ConnectTimeout retry pattern",
    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
)

示例：阶段跟踪（Deep 路径）

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 entry point (FastMCP, 6 tools)
│   ├── config.py                # env configuration
│   ├── tools/                   # thin MCP adapters
│   │   └── search / analyze / trace / scaffold / phase / verify
│   └── backend/                 # pure Python, zero MCP dependency
│       ├── search.py            # DDG / Brave / SearXNG + re-ranking
│       ├── extract.py           # trafilatura → readability fallback, SSRF guard
│       ├── analyzer.py          # project structure scan
│       ├── tracer.py            # callers / callees mapping
│       └── phase_tracker.py     # Newton state machine (SQLite)
├── skills/inquisitor/SKILL.md   # behavioral layer for the agent
├── .claude-plugin/
│   ├── plugin.json              # Claude Code plugin manifest
│   └── marketplace.json         # self-hosted marketplace (source ".")
├── .mcp.json                    # bundled MCP server (${CLAUDE_PLUGIN_ROOT})
└── tests/                       # 36 tests

backend/ 包可独立导入——无需 MCP：

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（RFC、规格说明、论文、数据手册），会进行提取，而非跳过。默认策略为 auto：除非已安装 docling 且存在 GPU，否则使用 pypdf（纯 Python、速度快、无需模型，可处理文本 PDF）。 对于复杂表格或扫描版／OCR PDF，可安装可选的 docling 后端：

uv pip install "inquisitor-mcp[docling]"   # or: pip install "inquisitor-mcp[docling]"

docling 体积庞大（会安装 torch 和 ML 模型），且在 CPU 上运行缓慢，因此 auto 仅在 docling 已安装且存在 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 在本地运行，使用当前用户的权限 — 不会监听网络。

---

配套技能

inquisitor 既是调查工具，也是路由器 — 在适用时，它会委派给专用技能（/tdd、/code-review、……），但不会替你安装这些技能。请参阅 docs/companion-skills.md，了解值得与之配套安装的精选技能（mattpocock/skills、spec-kit、last30days、ponytail、gstack）以及设计参考。

---

开发

uv sync                  # install deps
uv run pytest tests/ -v  # run tests
uv run ruff check .      # lint

技术栈

• uv — 包管理器
• FastMCP — MCP 服务框架
• ddgs / httpx — 搜索 + HTTP
• trafilatura + readability-lxml — 内容提取（两级回退）
• SQLite — 调查状态
• pytest / ruff — 测试和代码检查

---

致谢

研究资料来源见 Foundations。此外，本项目的实现还借鉴了：

• andrej-karpathy-skills（forrestchang）— 根据 Andrej Karpathy 对 LLM 编码陷阱的观察总结出的行为准则。
• ponytail（Dietrich Gebert）— 决策阶梯和资深开发者的懒人准则。
• last30days-skill（mvanhorn）— 多来源研究设计以及将 SKILL.md 作为契约的模式的灵感来源。

基于 MIT 许可证授权。