内容
# 视差
视差是一个MCP服务器，为语言模型提供工具来检查自己的工作：验证声明，运行确定性检查，存储和回忆记忆，研究问题，并审查其轨迹。
[](https://github.com/quanticsoul4772/mcp-parallax/actions/workflows/ci.yml)
[](#license)
服务器暴露了四组十四种工具：
- **认知纠正**，由模型调用：`verify` 判断一个声明是否成立，`unstick` 返回下一步，`diverge` 返回问题的替代框架，`decide` 在提供的选项中选择并报告评分，`elicit` 揭示请求的客观性和控制偏好。
- **确定性检查**：`check` 通过执行正式翻译来解决算术、逻辑和约束声明，而不是判断；`grounded_verify` 检查声明是否与调用者命名的逐字文件相符，解决引擎上的可计算属性（例如行计数）并在其他情况下放弃。
- **记忆**：`save`、`recall` 和 `forget` — 跨会话存储，验证后信任。
- **研究**：`research` 在单独的预算上运行网络查询，并返回引用的、按声明验证的答案。
- **轨迹检查点**：`checkpoint_action`、`checkpoint_batch` 和 `checkpoint_turn`，由harness的钩子调用，以防止模型自我诊断的失败。
有关每种工具的详细信息，请参见[工具](#tools)。
状态：实验性，v0.1.0。网络出口和代码执行是默认关闭的；仅设置`ANTHROPIC_API_KEY`，始终开启的纠正工具可用，且唯一的出站流量是到Anthropic API。 从源代码构建；未发布到注册表。
## 要求
- **Rust 1.94+** （2021版；CI中强制执行MSRV）
- **cmake** 和 **C++ toolchain** — 捆绑的`z3`求解器从源代码构建。第一次干净构建需要约5分钟。在Windows上，VS 2022 Build Tools捆绑的cmake有效；将`CMAKE`设置为其完整路径。
- **Anthropic API密钥**。可选：**Voyage** 密钥启用记忆工具，**Brave Search** 密钥启用`research`。
## 安装
```bash
git clone https://github.com/quanticsoul4772/mcp-parallax
cd mcp-parallax
cargo build --release
# 二进制文件：./target/release/mcp-parallax
```
## 快速入门
视差是一个stdio MCP服务器 — 客户端启动二进制文件，通过其stdin/stdout进行JSON-RPC通信。将其添加到MCP客户端（Claude Desktop，Claude Code），指向构建的二进制文件并提供API密钥：
```json
{
"mcpServers": {
"parallax": {
"command": "/absolute/path/to/target/release/mcp-parallax",
"env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
}
}
}
```
重启客户端，目录出现。要求模型解决一个可检查的声明，确定性引擎回答：
```text
> use check: "256 = 2 * 128"
{ "verdict": "supported", "engine": "arithmetic",
"formal_form": "256 == 2 * 128", "engine_result": "true" }
```
独立验证二进制文件：
```bash
./target/release/mcp-parallax --version
# => mcp-parallax 0.1.0
```
## 工具
传输方式为 **stdio**。目录由配置控制：六种始终开启的纠正工具在服务器运行时始终可用；`grounded_verify`、记忆、研究和检查点传感器平面仅在配置其根密钥/集成时出现（参见[配置](#配置)）。
| 工具 | 目的 | 可用性 |
|---|---|---|
| `verify` | 跨多个并行通道验证声明，每个通道应用不同的关键视角；返回支持/驳斥、发现和根据通道一致性得出的置信度。 | 始终 |
| `unstick` | 返回具有理由的下一个具体步骤 — 不是菜单或计划。 | 始终 |
| `diverge` | 返回问题的替代框架：每个并行通道应用不同的角度（目标逆转、演员更换、视野转移、拒绝负载轴承假设、问题类别重构）；服务器重复数据删除并用角度标记每个框架。 | 始终 |
| `decide` | 在两个或多个提供的选项中选择：单个通道应用方法论（称重/因果/概率）并对每个选项进行评分；服务器选择最高评分并报告亚军、决策因素、方法论和根据分数差距得出的置信度。 | 始终 |
| `elicit` | 揭示请求隐含的目标和应控制它的偏好：返回假设的目标、控制偏好（每个信号跟踪和存储；显示和存储的偏好优先于陈述的偏好）和应首先解决的分歧点。当信号低时报告，而不是发明偏好。如果设置了Voyage密钥，还会咨询存储的验证偏好。仅显示 — 不阻止或修改（即检查点层）。 | 始终 |
| `check` | 通过执行解决可检查的声明：模型翻译成小型正式目标（算术或SMT/约束系统），确定性引擎决定，返回执行的表单和原始结果以供审计。无法形式化的声明返回`not_checkable`。 | 始终 |
| `save` | 存储技能、课程或事实以备将来会话使用，并具有出处；外部记忆在请求验证之前是不可信的。 | `VOYAGE_API_KEY` |
| `recall` | 检索与当前工作相关的记忆，按语义相关性排序并标记信任程度。 | `VOYAGE_API_KEY` |
| `forget` | 永久删除指定ID的记忆。不可逆转。 | `VOYAGE_API_KEY` |
| `research` | 运行网络查询并返回简短的、引用的、按声明验证的答案：范围并行搜索、卫生强制检索、反驳偏见的按声明验证和一个接地门，阻止不支持的引用。 | `BRAVE_API_KEY` |
| `grounded_verify` | 验证声明是否与调用者命名的逐字源（文件路径、行范围或glob模式）相符：服务器读取确切的文本。返回支持/驳斥；对于单个源的可计算属性（行/字节/匹配计数与阈值），服务器计算读取的字节，确定性引擎解决，返回执行的表单（例如`1224 > 1000`）；更广泛或复合的返回`inconclusive`。还返回发现、审计清单和命名省略证据的完整性信号。 | `GROUNDED_VERIFY_ROOT` |
| `checkpoint_action` | 预动作门：评估一个风险匹配的待处理动作与已验证的存储约束；返回`hold`（引用冲突的记忆）或沉默。失败开启；不修改动作。 | 钩子（默认关闭） |
| `checkpoint_batch` | 批处理后筛选：检测最近轨迹中的循环和重复失败；标记重复动作和计数，或沉默。本地，无需模型调用。 | 钩子（默认关闭） |
| `checkpoint_turn` | 结束回合审查：检查回合中是否有与早期提交的陈述和已验证的决定相矛盾的内容；确认的矛盾作为强制继续提供。单个盲评审通道，服务器组装的裁决。 | 钩子（默认关闭） |
`checkpoint_*`工具旨在由harness的钩子调用，而不是模型本身；直接调用它们的行为相同。 从[`integrations/claude-code/`](integrations/claude-code/README.md)安装传感器平面以启用它们。 每个裁决都失败开启，从不重写模型的工作。
## 配置
所有配置都是环境变量，在启动时由`Config::from_env`读取一次。存在但无法解析的值是错误，而不是静默回退到默认值。
| 变量 | 必需 | 默认值 | 目的 |
|---|---|---|---|
| `ANTHROPIC_API_KEY` | 是 | — | Anthropic API密钥（为空或未设置则启动失败） |
| `ANTHROPIC_MODEL` | 否 | `claude-opus-4-8` | 验证/判断通道的模型 |
| `VERIFY_ENSEMBLE_K` | 否 | `3` | 每个`verify`的并行通道（≥ 1） |
| `INPUT_MAX_CHARS` | 否 | `50000` | 最大输入长度；`VERIFY_MAX_CLAIM_CHARS`作为备用别名 |
| `VOYAGE_API_KEY` | 否 | 未设置 | 存在时启用记忆工具；不存在时不在目录中 |
| `VOYAGE_MODEL` | 否 | `voyage-4` | 嵌入模型（在同一家族内 — 向量共享一个空间） |
| `MEMORY_RECALL_LIMIT` | 否 | `5` | 默认召回top-k（1–20） |
| `BRAVE_API_KEY` | 否 | 未设置 | 存在时启用`research`；不存在时不在目录中 |
| `FETCH_TIMEOUT_MS` | 否 | `10000` | 研究运行的每个源的获取超时 |
| `RESEARCH_CONCURRENCY` | 否 | `8` | 并发获取/提取/验证上限（1–32） |
| `FETCH_ALLOW_PRIVATE` | 否 | `false` | SSRF防护：当为false时，研究获取到环回/私有/链接本地目标被阻止。仅在本地测试时启用 |
| `CHECKPOINT_GATE_PATTERNS` | 否 | 空 | 以逗号分隔的子字符串扩展预动作门的内置风险模式；空条目（`a,,b`）是错误 |
| `GROUNDED_VERIFY_ROOT` | 否 | 未设置 | 存在时启用`grounded_verify`；定位器在其中解析的单个根（在启动时规范化；读取仅限于它）。不存在时，工具不在目录中 |
| `GROUNDED_VERIFY_MAX_BYTES` | 否 | `262144` | 每个`grounded_verify`调用的总装配证据字节上限 |
| `GROUNDED_VERIFY_MAX_LOCATORS` | 否 | `64` | 每个`grounded_verify`调用的最大定位器数量 |
| `DATABASE_PATH` | 否 | `./data/parallax.db` | SQLite路径（会话、记忆、调用 + 检查点记录） |
| `LOG_LEVEL` | 否 | `info` | `error\|warn\|info\|debug\|trace` |
| `REQUEST_TIMEOUT_MS` | 否 | `30000` | 每个请求的超时（毫秒） |
| `MAX_RETRIES` | 否 | `3` | 最大API重试尝试次数 |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | 否 | 未设置 | 存在时启用OTLP遥测导出（跟踪 + 指标，GenAI语义约定）；标准`OTEL_*`系列被遵守。无模式的端点默认为`https` — 使用显式`http://localhost:4318`适用于本地收集器。导出的仅记录元数据 — 工具、模型、令牌、成本、延迟、结果 — 从不输入文本、内存/转录内容或凭证 |
| `OTEL_SDK_DISABLED` | 否 | 未设置 | `true`（不区分大小写）强制禁用遥测，无论端点如何 |
每次调用都记录在SQLite中（工具、模型、令牌、成本、延迟、结果）。当设置了OTLP端点时，从相同的记录中派生出跨度和指标，因此两个表面不能有分歧；遥测失败从不影响服务器。 研究成本说明：记录汇总了LLM令牌，但Brave按请求计费，因此其费用不在`cost_usd`中 — 一个命名的不精确值。
## 架构
四层，取决于模型是否可以请求帮助：
1. **认知纠正** — **什么**；在模型可以自我诊断时调用（`verify`、`unstick`、`diverge`、`decide`、`elicit`）。
2. **看门狗** — **何时**；触发模型无法自我诊断的纠正措施。为MCP重新接地为**检查点层**，使用harness钩子作为传感器平面（参见2026-06-12的修订版，位于[`docs/design/WATCHDOG_LAYER.md`](docs/design/WATCHDOG_LAYER.md)）。
3. **记忆/经验** — 验证后存储的技能、课程、世界状态，按语义相关性召回。
4. **确定性/符号** — 所有可检查的事项均由求解器解决，而不是概率判断。
每个工具都声明一个输出JSON模式，模型通过Anthropic的原生结构化输出限制在该模式内 — 没有自由文本解析。外部依赖（模型客户端、存储、嵌入器、搜索、获取器、时钟、轨迹读取器）位于可模拟的特征后面，因此整个服务器都在没有网络或磁盘的情况下进行测试。[主设计](docs/design/NEW_SERVER_DESIGN.md)索引了整个语料库和每层的深入研究。
## 开发
```bash
cargo build # 调试构建
cargo test --all-features # 所有测试
cargo fmt --all -- --check # 格式化
cargo clippy --all-features --all-targets -- -D warnings # Lint（门控）
cargo cov --summary-only # 覆盖率门控（90%行底线）
```
CI运行格式、clippy、测试套件、MSRV（1.94）构建、覆盖率门控和每周的`cargo audit`。约定是编译器强制的：`#![forbid(unsafe_code)]`，生产路径中没有`unwrap`/`expect`（通过`clippy::unwrap_used`/`expect_used`禁止），以及结构化`tracing`仅输出到**stderr** — stdout是MCP JSON-RPC通道，因此 stray `println!`会破坏协议（也通过`deny`禁止）。
## 安全
视差处理凭证，并且在启用时访问网络 — 请相应地对待它：
- **无代码执行。** 确定性层使用`evalexpr`和进程内的Z3评估正式目标；沙盒代码执行故意延迟并关闭。
- **网络出口默认关闭且受控。** 研究获取仅在设置`BRAVE_API_KEY`时发生，并受SSRF保护（`FETCH_ALLOW_PRIVATE=false`阻止环回/私有/链接本地目标）。遥测出口仅在设置`OTEL_*`端点时发生。
- **检查点层读取转录文件**（有界尾部读取），默认关闭，直到您安装钩子。它是故障开启的，如果发生错误或超时，永远不会阻止操作。
- **密钥**仅通过环境提供，从不写入记录或导出遥测。
- 通过存储库上的[私募咨询](https://github.com/quanticsoul4772/mcp-parallax)报告安全问题。
## 许可证
[MIT](LICENSE)
