一个 FOSS 优先、本地优先的能力与证据层，为 Claude 及任何 MCP 客户端提供安全、带引用的网络访问，且安全决策在模型外部进行。
## 目录
- [为什么选择 D-Eye](#why-d-eye)
- [功能](#capabilities)
- [快速开始](#quick-start)
- [架构](#architecture)
- [实际用例](#practical-use-cases)
- [安全态势](#security-posture)
- [MCP 工具](#mcp-tools)
- [诚实的状态说明](#status-honestly)
- [仓库结构](#repository-layout)
- [贡献](#contributing)
- [安全政策](#security-policy)
- [许可证](#license)
## 为什么选择 D-Eye
大多数 agent 栈访问网络的方式是不安全的、不可验证的，或者是被付费密钥锁定的。D-Eye 在模型与网络之间的层面解决了这个问题，采用模型永远无法覆盖的确定性策略。
| 问题 | D-Eye 的解决方案 |
|---|---|
| Agent 进行不安全的抓取，可能被指向内部地址或云元数据。 | 每次抓取都要经过 SSRF 门，该门会拦截私有地址、环回地址、链路本地地址和云元数据地址，然后将 TCP 连接固定到已审查的 IP，从而防止主机名在检查和连接之间重新绑定到私有目标。 |
| 回答没有引用且无法审计。 | 每个结果都会捕获其源 URL、检索时间戳和内容哈希，研究结果以带引用的数据包形式返回，而不是黑盒。 |
| 抓取到的文本试图操纵模型（“忽略之前的指令”）。 | 检索到的内容被标记为不受信任的证据，绝不是指令，且安全决策在模型外部确定性地运行。 |
| 许多来源需要付费的 API 密钥或托管帐户。 | 核心部分无需密钥，仅使用 Python 标准库。付费或托管的适配器是可选的，默认关闭，且绝不会在验收路径上。 |
## 功能
| 功能 | 你将获得 | 需要设置？ |
|---|---|---|
| 无密钥网络搜索 | 通过 DuckDuckGo HTML endpoint 搜索公共网络，无需密钥或帐户。 | 否 |
| 网页抓取与提取 | 通过强化路径进行策略门控抓取，以及可读文本提取。 | 否 |
| RSS 和 Atom | 经过强化的 Feed 阅读器，防御 XXE 和实体扩展。 | 否 |
| GitHub | 只读公共仓库元数据和最近的提交。 | 否 |
| Reddit、V2EX 及类似的社区连接器 | 通过经过 SSRF 强化的相同抓取路径进行无密钥读取。 | 否 |
| 带引用回答的语义研究 | 本地 SQLite FTS5 索引，提供有依据的抽取式回答和带引用的研究数据包。 | 否 |
| 证据存储 | 持久化 SQLite 存储，带有来源信封和按租户范围的划分。 | 否 |
| MCP 服务器 | 通过本地 stdio 服务器或远程流式 HTTP 服务器提供八种稳定的工具。 | 本地：否。远程：设置 bearer token。 |
| 本地浏览器适配器 | 可选的、主动开启的，按会话隔离上下文，且操作受同意门控。 | 可选附加项 |
| 托管搜索适配器 | 可选，自带密钥。默认禁用；回退到无密钥搜索。 | 可选密钥 |
## 快速开始
前置条件：Python 3.10 或更新版本。核心安装不拉取任何运行时依赖（仅限标准库）。
```
# 安装核心（FOSS，无 keys，无 accounts）
git clone https://github.com/scorpion1476-lgtm/D-Eye D-Eye
cd D-Eye
python3 -m venv .venv
./.venv/bin/python -m pip install -e .
# 一次性设置（使用 FOSS 默认值写入 ~/.deye/config.json，无 secrets）
./.venv/bin/deye setup
./.venv/bin/deye doctor # confirm connectors are healthy
# 运行一些研究（search、fetch、cite、persist）
./.venv/bin/deye research "continuous pricing airline revenue management" \
--max-sources 5 -o packet.md
# 查询已捕获的内容
./.venv/bin/deye evidence "continuous pricing"
```
将 D-Eye 注册到 Claude Desktop 和 Claude Code（本地 stdio MCP）：
```
./.venv/bin/python -m pip install -e '.[mcp]'
./.venv/bin/deye init-claude # writes the local MCP config
./.venv/bin/deye init-claude --dry-run # preview, change nothing
```
`research` 命令会进行搜索，通过 SSRF 防护路径抓取顶级来源，提取可读文本，将每个来源及其 URL、时间戳和内容哈希记录到 `~/.deye/evidence.db` 中，并生成一个带引用的 Markdown 数据包以及一个 JSON 附属文件。完整操作指南：[`docs/QUICKSTART.md`](docs/QUICKSTART.md)。
## 架构
D-Eye 分为四层进行组织：
1. **请求生命周期。** MCP 客户端（Claude Desktop、Claude Code 或任何 MCP 客户端）或 CLI 发出能力请求。能力路由器会选择一个健康且符合策略的连接器，在失败时进行回退，并在后端反复失败时打开断路器。结果以 Markdown 或 JSON 格式返回，作为一个带引用且追踪来源的研究数据包。
2. **能力。** 无密钥连接器（网络搜索、抓取、RSS、GitHub、Reddit、V2EX 等），一个具备本地关键字搜索和有依据的抽取式回答的语义研究层，以及 `deye` 命令行。
3. **证据与数据。** 一个持久化的 SQLite 证据存储，记录每个结果的来源（来源、时间戳、内容哈希），以及一个能够展示声明、关系和潜在矛盾的证据图。
4. **安全基础。** 在模型外部确定性地进行决策：一个具备私有 IP 和云元数据拦截及连接级 IP 固定的 SSRF 防护，一个默认关闭写入操作的同意门，凭证脱敏，以及一个在每次抓取前运行的政策引擎。
## 实际用例
- **赋予 Claude Desktop 安全、带引用的网络访问能力。** 注册本地 MCP 服务器；客户端会看到一个小巧且稳定的工具集，且每个响应都是带有来源的不受信任证据。
- **生成关于某个主题的带来源研究数据包。** `deye research "topic" --max-sources 5 -o packet.md` 返回一个带引用的 Markdown 数据包以及 JSON 附属文件，每个来源都经过哈希处理并存储。
- **监控 RSS 和 Atom feed 的变更。** 通过经过 XXE 强化的阅读器拉取 feed，并与之前捕获的证据进行对比，以检测发生了哪些变化。
- **读取公共 GitHub 仓库及其 issues。** `deye repo owner/name` 返回只读的仓库元数据和最近的提交，无需密钥。
- **离线查询之前收集的证据。** `DEYE_OFFLINE=1 deye evidence "sqlite fts5"` 在本地语料库上运行全文搜索，实现零网络流出。
## 安全态势
以下每项控制措施都在已追踪的源代码中得到了真正的实现，并由测试覆盖。
| 控制措施 | 功能描述 |
|---|---|
| SSRF 和策略防护 | Scheme 白名单，拒绝 URL userinfo，并在解析后进行 IP 检查，拦截私有、环回、链路本地、多播、保留和云元数据地址。如果主机解析到任何非公开地址，则会判定失败并关闭。 |
| 连接级 IP 固定 | Socket 连接到已审查的 IP，同时 TLS 仍然针对真实主机名 (SNI) 进行验证，从而消除了 DNS 重绑定中从检查到使用的时间差漏洞。 |
| 默认只读，写入需同意门控 | 除非人类针对该特定操作授予明确同意，否则写入、浏览器和具有副作用的操作都将被拒绝。 |
| 无硬编码 token | 通过一项测试来强制执行，该测试会扫描已追踪的代码树，查找具有凭证特征的字符串。 |
| 脱敏处理 | 每一行审计记录、日志条目和导出的数据包在写入或发出之前，都要经过凭证脱敏处理。 |
| 不受信任的证据 | 每个抓取到的结果都被标记为不受信任，并附带其来源、时间戳和内容哈希；模型被要求绝不要服从在证据中发现的文本。 |
| 解压缩和大小限制 | 响应受到大小限制，如果解压超过限制则会中止，从而防御 gzip 炸弹。 |
| 确定性策略 | 上述所有决策均在模型外部做出，位于 `deye/core/policy.py` 和连接器抓取路径中，而不是由 LLM 决定。 |
更多细节：[`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md)。
## MCP 工具
服务器暴露了一个小而稳定的工具表面。原始抓取器和 shell 访问权限被刻意不对模型暴露。
| 工具 | 功能描述 |
|---|---|
| `capability_list` | 列出服务器提供的功能和工具。 |
| `connector_health` | 报告每个已注册连接器的健康状况。 |
| `search` | 无密钥的公共网络搜索，返回经过脱敏的内容及 artifacts。 |
| `fetch` | 对单个 URL 进行策略门控的抓取和提取。 |
| `extract` | 将一块 HTML 转换为可读文本。 |
| `export_research_packet` | 搜索、抓取、引用、持久化并返回一个有依据的 Markdown 数据包。 |
| `query_evidence` | 查询持久化证据存储。 |
| `surface_status` | 如实报告 D-Eye 可以在哪些客户端表面上处于活动状态。 |
本地 stdio 和远程流式 HTTP 传输记录在 [`docs/MCP_GUIDE.md`](docs/MCP_GUIDE.md) 中。远程传输需要 bearer token (`DEYE_HTTP_TOKEN`)，并且应位于 TLS 终止反向代理之后。
## 诚实的状态说明
D-Eye 对哪些已被证实、哪些未被证实保持着刻意坦诚的态度。
- **测试，当前环境：** 收集到的 363 个测试中，358 个通过，0 个失败。四个浏览器测试是结构性的：它们涵盖了当可选的 Playwright 附加组件不存在时所使用的代码路径，因此当其存在时会跳过。一个实时网络测试在外部源不可达时跳过，在可达时通过，因此通过的数量是 358 还是 359 取决于网络状况。
- **静态分析：** Bandit 报告 0 个高危和 0 个中危发现；低危发现是预期的固定参数 subprocess 调用和防御性异常处理。
- **功能目录：** 在严格的证据标准下，167 个目录功能中有 112 个属于 PRODUCTION READY，每一个都有实际验收测试支持，并且在干净的克隆上能够通过测试并运行该功能。9 个被外部平台（登录墙或反机器人墙，或者是不暴露公共自动化 API 的供应商）阻挡，每一个都有明确的记录原因。其余 46 个仍在基于实际证据进行完善；没有任何虚报。
- **未作声明：** D-Eye 整体上尚未达到生产就绪状态，也没有声称实现了 100% 的完成度。
诚实的路线图：
- 一个实时的托管远程 MCP endpoint（传输层和 Docker compose 脚手架已发布；但尚未建立任何托管 endpoint）。
- 在 Linux 和 Windows 运行器上进行跨操作系统安装程序的验证。
- 带有可重现构建验证的签名发布包。
- 可选的本地浏览器边缘 (Playwright)，从主动开启的附加项转变为经过验证的集成测试。
- 一个可选的本地语义搜索适配器（embeddings 加上本地向量索引），位于可替换接口之后。
- 被平台阻挡的社区连接器，一旦存在合法的无密钥读取路径即会推出。
## 仓库结构
```
D-Eye/ (the clone root is the package root)
deye/ core package: core (policy, router, evidence, provenance, redact),
connectors, research, skills, backend, browser, lifecycle
tests/ test suite (unit, integration, live network, subprocess, browser)
docs/ guides (quickstart, MCP, connectors, skills, offline, threat model)
plugin/d-eye/ Claude plugin: manifest, marketplace, skills, commands, hooks
assets/brand/ the approved logo and the architecture diagram
scripts/ build, SBOM, secret scan, dash scan, repo verification
docker/ remote MCP compose scaffold
pyproject.toml packaging; the core has zero runtime dependencies
```
## 安全政策
请按照 [`SECURITY.md`](SECURITY.md) 报告漏洞。请不要为未公开的漏洞开启公开的 issue。
## 许可证
MIT。详见 [`LICENSE`](LICENSE)。为设计提供参考的第三方项目署名，以及所有的运行时和工具依赖许可证，均保留在 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) 中。