dark-research-mcp

<div align="center"> ``` ╔══════════════════════════════════════════════════════════════════╗ ║ ║ ║ ██████╗ █████╗ ██████╗ ██╗ ██╗ ██████╗ ███████╗███████╗ ║ ║ ██╔══██╗██╔══██╗██╔══██╗██║ ██╔╝ ██╔══██╗██╔════╝██╔════╝ ║ ║ ██║ ██║███████║██████╔╝█████╔╝ ██████╔╝█████╗ █████╗ ║ ║ ██║ ██║██╔══██║██╔══██╗██╔═██╗ ██╔══██╗██╔══╝ ██╔══╝ ║ ║ ██████╔╝██║ ██║██║ ██║██║ ██╗ ██║ ██║███████╗███████╗ ║ ║ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝ ╚═╝╚══════╝╚══════╝ ║ ║ ║ ║ O S I N T · V I B E - F L O W · D A R K - S S D ║ ║ ║ ╚══════════════════════════════════════════════════════════════════╝ ``` **MCP 服务器，结合人工智能进行调查、提示和验证——中文版** [](LICENSE) [](go.mod) [](ARCHITECTURE.md) [](.github/workflows/go-test.yml) [](BACKEND_STATUS.md) [](.github/workflows/go-test.yml) [功能介绍](#功能介绍) · [适用人群](#适用人群) · [快速开始](#快速开始) · [架构](#架构) · [相关论文](#相关论文) </div> --- ## 功能介绍 **dark-research-mcp** 是一个用 Go 编写的 MCP 服务器，提供 57 种专业工具，分为三个类别： 1. **调查（OSINT）** — 15 种工具，用于路由查询到特定后端（OSV.dev, OpenAlex, RIPE, crt.sh, abuse.ch, DuckDuckGo, GDELT, Wayback, Ahmia, HIBP, ip-api, GitHub, crates.io, npm），具有自动 fallback 功能。 2. **Vibe-flow** — 22 种工具，用于管理完整的 AI 辅助生产流程：spec（创建/更新/删除/渲染）→ artifact（日志/更新/删除）→ drift → reconcile → publish，具有品牌和合规性作为参考数据。 3. **Dark-ssd（LLM-as-judge）** — 8 种 LLM 评判器：品牌匹配、合规性司法管辖区、drift spec-vs-artifact、OSINT 声明接地、**PII 检测（GDPR/CCPA）**、**提示注入扫描（安全门控，在不可信文本传递给代理之前）** 和 **共识（多样本评判用于高风险判决）**。 单个 SQLite 数据库（`dark.db`）与 `dark-eval` 共享。单个 API。单个二进制文件（~17 MB）。**没有魔法：代码可读且可修改。** > 🇨🇴 *在哥伦比亚作为 [Opita Code](https://opitacode.com) 生态系统的一部分构建。用于实际调查的实用软件，而不是用于演示的漂亮软件。* --- ## 适用人群 | 如果你是… | 你感兴趣的是… | |---|---| | 🔬 **研究人员** | 坚持进行 OSINT 调查，记录发现，避免重复检索。跨链接项目和 CVEs/攻击/papers。 | | ✍️ **提示工程师** | LLM-as-judge 为你提供可复制的面板：品牌匹配、合规性检查、接地检查、**PII 检测**、**提示注入扫描** — 每个都有判决 + 置信度 + 原因。 | | 🌊 **Vibe-coder** | `spec → artifact → drift → reconcile` 流程闭环。停止每次生成相同的错误。 | | 🛡️ **红队成员** | 与 `dark-eval` 相同的 `dark.db`。将评估发现与 OSINT 研究和提示审计轨迹交叉。 | | 🏛️ **合规官** | `dark_ssd_compliance_check` 应用欧盟 AI 法案 2026-08-02、FTC、US-CA SB-1001。`dark_ssd_pii_detect` 在发布前扫描 GDPR 文章 4 / CCPA。每个判决都被审计。 | --- ## 快速开始 ```bash # 1. 克隆并编译 git clone https://github.com/Opita-Code/dark-research-mcp.git cd dark-research-mcp go build -o dark-research-mcp ./cmd/dark-research-mcp # 2. 配置（API 密钥存储在本地 vault 中，而不是环境变量中） export DARK_DB="$LOCALAPPDATA/dark-agents/dark.db" export SDD_LLM_API_KEY="$(powershell -Command 'Import-Module dark-agents-vault.psm1; (Get-DarkAgentSecret MINIMAX_API_KEY)')" # 3. 第一个查询 — 一个 CVE ./dark-research-mcp <<'EOF' {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"hi","version":"0"}}} {"jsonrpc":"2.0","method":"notifications/initialized"} {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"dark_research_cve","arguments":{"query":"CVE-2024-3094"}}} EOF ``` 预期输出（截断）： ```json { "items": [{ "title": "CVE-2024-3094", "url": "https://osv.dev/vulnerability/CVE-2024-3094", "snippet": "xz backdoor — malicious code in liblzma…", "source": "osv.dev", "confidence": 0.95 }], "backend_used": "osv", "took_ms": 250 } ``` --- ## Vibe-flow 循环（有趣的部分） 2026 年 AI 辅助开发中未解决的第一个问题是 **spec-drift**：代理生成某些内容，发布后从未协调它是否真正满足 spec 要求。 **dark-research-mcp** 通过持久性和 LLM-as-judge 解决了这个问题： ``` ┌──────────────────────────────────────────┐ │ 1. 注册品牌指南 │ │ dark_research_brand_register(…) │ │ │ │ 2. 注册司法管辖区 │ │ dark_research_compliance_register(…) │ │ (EU AI Act 2026-08-02: $51,744/viol) │ │ │ │ 3. 创建 spec │ │ dark_research_spec_create(…) │ │ │ │ 4. 生成 artifact │ │ （您首选的模型/服务） │ │ │ │ 5. 记录 artifact │ │ dark_research_artifact_log(…) │ │ │ │ 6. LLM-as-judge: 品牌匹配 │ │ dark_ssd_brand_match(content, brand) │ │ │ │ 7. LLM-as-judge: 合规性 │ │ dark_ssd_compliance_check(content, │ │ "EU") │ │ │ │ 8. LLM-as-judge: 漂移 │ │ dark_ssd_drift_judge(artifact_id) │ │ │ │ 9. 记录判决 │ │ dark_research_drift_log(verdict, │ │ judge_reasoning) │ │ │ │ 10. 人工门控如果失败 │ └──────────────────────────────────────────┘ ``` 每个 LLM-as-judge 都将其判决保存在 `sdd_evaluations` 中，并带有 `prompt_version` + `model`。**可复制，可审计，随时间推移可改进**（校准循环）。 --- ## 7 个案例（C1..C7） | 案例 | 领域 | 合规风险 | |---|---|---| | **C1** 代码 | 函数、脚本、重构 | 低 | | **C2** 文本 | 电子邮件、帖子、文档 | 中 | | **C3** 图片 | 英雄照、缩略图 | 低 | | **C4** 视频 | 演示、广告 | **高** （欧盟 AI 法案） | | **C5** 音频 | 叙述、播客 | **高** （欧盟 AI 法案） | | **C6** 多模态 | Instagram 广告：图片 + 文本 + CTA | **高** （欧盟 AI 法案 + FTC） | | **C7** 混合 | “发布此启动” | 取决于 | --- ## 架构 ``` ┌─────────────────────────────────────────────────────────────────┐ │ 您的代理（开源、Claude Code 等） │ │ │ │ stdio MCP │ └────────────────────────────┬────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────┐ │ dark-research-mcp.exe │ │ │ │ ┌──────────────────────────┐ │ │ │ 53 个 MCP 工具 │ │ │ │ ├ OSINT（15） │ │ │ │ ├ 内存（6） │ │ │ │ ├ vibe-flow CRUD（15） │ │ │ │ ├ dark-ssd LLM-judge（5） │ │ │ │ └ 独立（4） │ │ │ └──────────────────────────┘ │ │ │ │ ┌──────────────────────────┐ │ │ │ 内部/ │ │ │ │ ├ llm（Anthropic-compat）│◄──── SDD_LLM_API_KEY │ │ ├ 内存（SQLite + 迁移） │◄──── DARK_DB │ │ ├ 研究（16 个后端）│ │ │ │ │ └ 测试工具（VCR） │◄──── fixtures/ │ │ ├ 安全（SSRF 防护） │ │ │ │ └ vault（跨平台）│ │ │ └──────────────────────────┘ │ └────────────────┬───────────────────┘ │ ▼ ┌─────────────────────┐ │ dark.db（SQLite） │ │ │ │ research_runs │ │ research_items │ │ research_links │ │ vibe_specs │ │ vibe_brands │ │ vibe_compliance │ │ vibe_artifacts │ │ vibe_drift_reports │ │ sdd_evaluations │ │ │ │ + dark-eval 表格 │ │ （发现等） │ └─────────────────────┘ ``` 更多详情请参见 [`ARCHITECTURE.md`](ARCHITECTURE.md)。 --- ## 配置 | 变量 | 默认值 | 目的 | |---|---|---| | `DARK_DB` | `%LOCALAPPDATA%\dark-agents\dark.db` | SQLite 数据库路径 | | `SDD_LLM_API_KEY` | — | LLM 认证密钥（备用：`MINIMAX_API_KEY`） | | `SDD_LLM_BASE_URL` | `https://api.minimax.io/anthropic` | Anthropic 兼容端点 | | `SDD_LLM_MODEL` | `MiniMax-M3` | 模型 ID | | `DARK_SSD_CACHE_PATH` | `<DARK_DB_DIR>/llm-cache.json` | LLM 缓存路径（空 = 禁用） | | `BRAVE_API_KEY` | — | 可选，网页搜索备用 | | `GITHUB_TOKEN` | — | 可选，GitHub 代码搜索 | | `HIBP_API_KEY` | — | 可选，电子邮件泄露查找 | 命令行标志：`--db`、`--cache`、`--cache-ttl`、`--log-level`、`--config`。 --- ## 相关论文 本项目基于四个明确的思想路线： 1. **SSOT（单一真相来源）** — 单个 `dark.db`、单个 API、单个真相版本。如果您看到数据冲突，问题在于查询，而不在于模型。 2. **闭环验证** — 每个创意输出都经过 LLM-as-judge + 持久性 + 协调。如果没有它，vibe-coding 就是一个赌场。 3. **代币经济（Atlan 2026）** — LLM 缓存 + 可过滤的列表端点是 `dark-ssd` 不会烧毁您审计预算的第一步。更多详情请参见 `vibe-flow` 技能。 4. **开源规范、开源代码、开放数据** — 所有代码都是可读的。提示版本保存在 `sdd_evaluations.prompt_version` 中，以便您可以重现每个判决。 --- ## 测试、lint、构建 ```bash go vet ./... go build ./... go test -race ./... ``` 156 个测试通过。CI 运行 vet/build/test（-race）使用 Go 1.25 + 1.26。 ``` internal/llm 16 tests (8 client + 8 cache) internal/mem 38 tests (CRUD + migrations + lists + ssd) internal/research 55 tests (15 classifier + 26 parser unit + 14 VCR router) internal/research/testutil 12 tests (RecordingTransport record/replay/scrub) internal/safety 9 tests (URL validation, SSRF guard) internal/tools 21 tests (catalog + artifact_download + consensus + e2e) internal/vault 5 tests (cross-platform interface) ``` ### 后端状态监控 16 个 OSINT 后端不是我们的代码 — 它们是外部服务，可以更改 API 或宕机。因此，我们有两个可观察性层，而不仅仅是一个： 1. **VCR fixtures（`internal/research/testutil/` + `fixtures/`）** — 解析器和路由器的测试在录制的真实响应上运行。CI 不依赖网络，一个后端格式更改会在几秒钟内使测试失败，而不会在生产中。 2. **实时状态探测（`scripts/osint-status.sh`）** — 在每个 PR（`osint-smoke` 作业）和每周（`osint-status` 工作流）运行。并行探测 16 个后端，在 `BACKEND_STATUS.md` 中写入 HTTP 代码 + 每个后端的延迟，并自动提交更改。停机情况可见，无需开启问题。 刷新后端 API 更改后的 fixtures： ```sh RECORD_FIXTURES=1 go test -count=1 -run 'TestRouter_' ./internal/research/ git diff fixtures/ # 在提交前检查差异 ``` --- ## 状态 - ✅ **v0.3.0** — dark_ssd_consensus（多样本判断）+ dark_research_artifact_download（规范获取模式）+ 2 级 dark_mem_export_run/diff；57 个工具，100 个测试 - ✅ **v0.2.0** — CRUD 完成（5 个表更新/删除）+ spec_render + pii_detect + prompt_injection_scan（安全门控）；53 个工具，80 个测试 - ✅ **v0.1.0** — 初始开源版本（45 个工具，72 个测试，CI，MIT） - 🆕 **未发布** — VCR fixture 传输（`internal/research/testutil/`）+ 40 个新测试（解析器单元 + VCR 路由器）覆盖 13 个后端，带有记录的响应；实时状态探测（`scripts/osint-status.sh`）+ 每周 `osint-status` 工作流；**156 个测试** - 🚧 添加 Linux/macOS vault 的 `go-keyring` 实现 - 🚧 规范差异库（结构化更改检测） - 🚧 跨平台发布工件的 CI 请参阅 [`ARCHITECTURE.md`](ARCHITECTURE.md）获取完整的技术路线图。 --- ## 贡献 欢迎 PR。请： 1. `go test ./...` 推送前 2. 如果添加 OSINT 后端：实现 `research.Backend` 接口，合理加权添加到 `DefaultRegistry()` 3. 如果添加 LLM-as-judge：始终持久化 `prompt_version` 以实现可复制性 4. 如果添加迁移：追加到 `AllMigrations`，永远不要编辑过去的 --- ## 许可证 [MIT](LICENSE). 使用、修改、分发。如果您构建了某些东西，请告诉我们。 --- <div align="center"> 由 [Opita Code](https://opitacode.com) 在哥伦比亚 Neiva, Huila 构建。 *"我们构建软件不是让它在演示中看起来很好，而是让它每天与您一起工作。* [opitacode.com](https://opitacode.com) · [vibe.opitacode.com](https://vibe.opitacode.com) · [github.com/Opita-Code](https://github.com/Opita-Code) </div>