内容
# 智能分析代理
[](https://github.com/grammy-jiang/intelligence-analysis-agent/actions/workflows/ci.yml)
[](https://codecov.io/gh/grammy-jiang/intelligence-analysis-agent)
[](https://www.python.org/)
[](LICENSE)
[](https://github.com/astral-sh/ruff)
[](https://github.com/pre-commit/pre-commit)
[](https://github.com/jlowin/fastmcp)
一个复合型人工智能代理，运行**智能分析 / 分析工艺工作流程** — 构建问题，列出竞争性假设，权衡证据，在 ACH 矩阵中排名*反证*，获取独立的偏差 / 方法 / 校准批评，并在人类批准后提交校准判断。论文：*增强，而不是取代* — 代理结构和挑战推理；人类拥有判断。
基于精选的经典著作（Heuer，Kahneman，Tetlock ×2，Jervis，Kent，CIA SAT Primer，FM 2-22.3，Masterman）。由[subagent-factory](../subagent-factory)构建和消费审查者。
## 状态 — 第三阶段完成（MCP 状态层）；第四阶段构建，实时采集受限
核心文本部分首先证明（MVP-0 → 第二阶段门户通过），然后在上面构建了持久状态/计算层。整个过程仍然在上下文中作为文本运行；MCP 层添加了一个持久的、防篡改的存储和计算，用于跨案例学习。
| 层 | 内容 | 状态 |
|---|---|---|
| **技能**（方法） | `structured-analysis` — 主代理在运行时运行的 11 步工作流程 | ✅ 已构建 |
| **执行技能** | `source-evaluation`（步骤 3）+ `calibrated-forecasting`（步骤 9）— 执行对应于审查者批评的对应物 | ✅ 已构建（第二阶段） |
| **子代理**（审查者） | `bias-perception-reviewer`，`analytic-method-reviewer`，`calibration-forecasting-reviewer`，`deception-detection-reviewer` — 只读，委托批评 | ✅ 已部署 |
| **人类门户 + 回环** | 没有判断是最终的，直到人类批准；失败的审查回环 | ✅ 在技能中 |
| **MCP**（状态 + 计算） | `ach-engine`，`calibration-tracker`，`evidence-ledger` — 持久的，哈希链，防篡改 | ✅ 已构建（第三阶段），149 个测试 |
| **OSINT + 欺骗** | `osint-toolkit`（唯一出口，SSRF 防护）+ `osint-investigation` 技能 + `deception-detection-reviewer` | 🟡 已构建（第四阶段）；**实时采集受限**（`OSINT_LIVE=0`） |
案例仍然**在上下文中作为文本运行**；MCP 状态层是可选的持久性，而不是重写方法。外部采集**默认关闭**，并限制在单个审计出口表面。
## 架构
运行时案例流程 — 代理结构和挑战推理，审查子代理批评，MCP 层持久化，**在人类批准之前不会提交任何判断**：
```mermaid
flowchart TB
Analyst["人类分析师 — 拥有判断"]
subgraph Agent["Claude Code · structured-analysis 技能"]
Skill["11 步工作流程：<br/>框架 → 假设 → ACH → 判断"]
Doing["source-evaluation · calibrated-forecasting"]
end
subgraph Critics["审查子代理 · 只读批评"]
Bias["bias-perception"]
Method["analytic-method"]
Calib["calibration-forecasting"]
Decep["deception-detection"]
end
subgraph MCP["MCP 状态层 · 追加 · 哈希链"]
ACH["ach-engine"]
Ledger["evidence-ledger"]
Cal["calibration-tracker"]
end
OSINT["osint-toolkit<br/>唯一出口 · SSRF 防护"]
Web(["公共 OSINT 源"])
Gate{"人类门户：<br/>批准？"}
Commit["校准判断提交"]
Analyst --> Skill
Skill --> Doing
Skill --> Critics
Skill <--> MCP
Web <-->|OSINT_LIVE 受限| OSINT
OSINT -->|未分级提案| Ledger
Skill --> Gate
Critics --> Gate
Gate -->|批准| Commit
Gate -->|审查失败| Skill
```
## 验证
- **MVP-0 / 第一阶段门户 — 通过**（`docs/validation/results-2026-07-10.md`，Heuer 伊拉克报复 ACH）：代理辅助表面 **5** 个假设与基线的 **2** 个；ACH 矩阵降低了“未响应的狗”反证项目的领先假设；**3/3 故意注入的缺陷** 被正确的审查者捕获（生动性 → 偏差，未声明的假设 → 方法，过高自信 → 校准）。审查者还捕获了一个真实的，*未植入的* 手工构建矩阵中的记账错误。
- **第二阶段 Brier 门户 — 通过**（`docs/validation/brier-forecasting-demo.md`）：辅助 **0.091** 与天真的/过度自信的基线 **0.247**（63% 降低）在 8 个已解决的问题上。诚实的警告记录 — 这验证了机制 + 方向，而不是盲基准（需要一个保留的提要，现在可以通过 `calibration-tracker` 实现）。
- **第三、四阶段测试 — 149 通过**（`python3 -m pytest`）：服务器逻辑 + 跨服务器连接 + OSINT 出口和 EXIF 硬化。
每个设计都通过了一个工厂顾问小组进行评审，**必须修复 = 0** 在任何代码之前：第三阶段经过三个回合（mcp-protocol / mcp-security / mcp-quality / ai-agent-engineering）；第四阶段通过了一个强制性的，阻塞性的安全审查（mcp-security + application-security）。
## MCP 服务器（状态 + 计算）
四个 **FastMCP** 服务器，通过 `.mcp.json` 连接。每个服务器都保持一个追加的，哈希链的清单，并公开一个只读的 **`verify_chain`** 完整性工具（在启动时运行 + 锚定到外部头部哈希），因此存储是防篡改的。
| 服务器 | 工具 | 基础 |
|---|---|---|
| **calibration-tracker** | `log_forecast`，`resolve_forecast`，`void_forecast`，`get_forecast`，`list_forecasts`，`get_calibration_report`，`verify_chain` | Tetlock — 问题 + 概率 **锁定在提交时**，只有结果被追加；Brier/校准由工具计算 |
| **evidence-ledger** | `add_evidence`，`grade_evidence`，`update_grade`，`get_evidence`，`list_evidence`，`get_source_history`，`verify_chain`，`verify_signals_chain` | FM 2-22.3 — 两个独立轴上的可靠性和可信度；PII 为必填字段；取消红名受限制 |
| **ach-engine** | `create_matrix`，`add_hypothesis`，`rate_cell`，`score_matrix`，`get_matrix`，`list_matrices`，`verify_chain` | Heuer ACH — 按最小不一致性排名；`score_matrix` **拒绝** 任何证据缺乏 `analyst_confirmed` 等级的单元格（收集后分级漏洞已关闭） |
| **osint-toolkit** | `search`，`fetch`，`compute_hash`，`extract_exif`，`reverse_image_search`，`get_map_tile`，`propose_to_ledger`，`verify_chain` | **唯一** 外部出口表面；每跳 SSRF 防护（IANA 阻止列表 + 规范化 + 连接固定），出口审计日志，不透明的 `artifact_ref`，`extract_exif` RCE 硬化 |
**安全态势（第四阶段门户 = 未分类 / 仅 OSINT）：** 仅限公共开源数据；出口限制为允许的 OSINT 源；无分类数据存储。`judgment_source` / `analyst_id` 来自受信任的本地绑定，**不是** LLM 参数 — 并且诚实地有界限（技能断言，不是服务器验证）。`OSINT_LIVE=0` 在显式启用之前保持所有实时连接器关闭。
## 使用它
在此仓库中打开 Claude Code（`.claude/` 提供技能 + 审查子代理；`.mcp.json` 提供状态服务器），然后：
```text
/structured-analysis
```
或仅描述一个不确定条件下的分析问题。技能维护一个 **案例工作空间**（问题 · 假设 · 证据 + 等级 · ACH 矩阵 · 假设 · 排名 · 发现 · 判断 · 评估 · 指标），将审查委托给审查子代理，并在最终确定之前**停止以供您批准**。将案例持久化到 MCP 服务器是可选的。
产品是 **仓库本地的**：技能和批评子代理位于此仓库的 `.claude/` 中，因此它们必须一起运行在此处（编排器将委托给审查子代理，它们不是全局的）。在该仓库中按会话工作一个案例。
## 布局
```text
.claude/
agents/ 4 个审查子代理（从工厂部署 — 不要编辑；重新导出以更新）
skills/ structured-analysis（编排器）+ source-evaluation + calibrated-forecasting
+ osint-investigation + 审查者自己的技能模块
mcp_servers/ ach_engine · calibration_tracker · evidence_ledger · osint_toolkit + common/staleness
docs/
design/ phase3-mcp-design.md · phase4-osint-design.md（每个都限定为 must-fix=0）
validation/ MVP-0/第二阶段门户 + 运行结果 + Brier 工具
tests/ 234 个测试 — 服务器逻辑 + 跨服务器连接 + OSINT 出口/EXIF + 覆盖率
scripts/ check_mermaid.py（mermaid-cli 编译）· check_egress_isolation.py · check_coverage.py
```
## 开发
依赖和虚拟环境由 [uv](https://docs.astral.sh/uv/) 管理。环境被锁定（`uv.lock`）并且其 Python 被固定（`.python-version`）；使用以下命令创建或刷新它：
```bash
uv sync # 从 uv.lock 构建 .venv（运行时依赖 + `dev` 组）
uv run pytest # 在锁定环境中运行套件
```
`.mcp.json` 中的 MCP 状态服务器通过 `uv run` 启动，因此必须先运行 `uv sync`。
代码检查和格式化通过 [pre-commit](https://pre-commit.com) 运行。钩子涵盖仓库中的每个文件类型 — Python（`ruff` 代码检查 + 格式化），Markdown（`markdownlint` + Mermaid 编译检查），以及 TOML / JSON / YAML 加空格卫生：
```bash
uv run pre-commit install # 在每次 git 提交上运行钩子
uv run pre-commit run --all-files # 一次检查整个仓库
```
文档中的图表是 [Mermaid](https://mermaid.js.org/) 代码块，由 GitHub 内联渲染。`scripts/check_mermaid.py` 编译每个围栏的 `mermaid` 代码块，使用真正的 Mermaid 编译器（[`mmdc`](https://github.com/mermaid-js/mermaid-cli)）— 连接为仓库本地预提交钩子和自己的 CI 作业 — 因此无法在文档中渲染的图表无法登陆。
CI（`.github/workflows/ci.yml`）在每次推送到 `master` 和每个拉取请求时运行：上述预提交钩子；在 Python 3.11-3.13（以及 3.14 作为允许失败的预览）下运行测试套件，覆盖率检查 **每模块门控**（`scripts/check_coverage.py`）— 核心模块（存储引擎，`common`，`staleness`，`egress` SSRF 防护，模型）必须超过 95%，其他每个模块必须超过 90%，按文件强制执行，以便一个覆盖率良好的模块不能掩盖一个薄弱的模块（目前每个模块都是 96-100%）；以及 **出口隔离** 门控（`scripts/check_egress_isolation.py`），如果数据服务器（calibration-tracker / evidence-ledger / ach-engine）获得直接网络导入，则构建失败 — 强制执行设计中的 *“osint-toolkit 是唯一出口表面”* 不变式。
## 记录设计
内容/原因/决策位于工厂仓库下的 `docs/intelligence-analysis/`：`BLUEPRINT-*`（决策 + 开放问题），`PIPELINE-grounded.md`（工作流程，每个步骤引用一个源声明），`DESIGN-SPEC-*`（如何做）。审查子代理在那里再生，并在 `cli export-deployable` 上部署到此处。
