内容
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="media/logo-dark.svg">
<img alt="DelphiCourier MCP" src="media/logo-light.svg" width="120">
</picture>
</p>
<h1 align="center">DelphiCourier 中转服务器</h1>
<p align="center">
<em>范围第一，智能第二<br>
我们在您为昂贵的推理模型代币付费之前缩小上下文。</em>
</p>
<p align="center">
<a href="https://github.com/kccarlos/delphicourier/actions/workflows/ci.yml"><img src="https://github.com/kccarlos/delphicourier/actions/workflows/ci.yml/badge.svg" alt="CI 状态"></a>
<a href="https://github.com/kccarlos/delphicourier/releases/latest"><img src="https://img.shields.io/github/v/release/kccarlos/delphicourier" alt="最新版本"></a>
<a href="https://github.com/kccarlos/delphicourier/blob/main/LICENSE"><img src="https://img.shields.io/github/license/kccarlos/delphicourier" alt="许可证"></a>
</p>
DelphiCourier 是一个 MCP 服务器，作为本地编码代理和最智能、最昂贵的 AI 模型之间的严格物流层。
直接将整个存储库发送到强大的推理模型既昂贵、嘈杂又难以重现。DelphiCourier 通过让您的 CLI 代理将上下文缩小到文件、差异、引用和行范围的精确配方来解决这个问题。然后，DelphiCourier 确定性地缩小该上下文以适应严格的代币预算，并将其运送到模型。
如果 Oracle 回答了困难的问题，DelphiCourier 确保您提出正确的问题并提供确凿的证据。
<a id="table-of-contents"></a>
## 目录
- [目录](#table-of-contents)
- [产品概述](#product-overview)
- [智能差距与“代理聊天”税收](#the-intelligence-gap--the-agent-chatter-tax)
- [堆栈：DelphiCourier 的位置](#the-stack-where-delphicourier-fits)
- [为什么命名](#why-the-name)
- [DelphiCourier 实际执行的操作](#what-delphicourier-actually-does)
- [当前 MCP 工具界面](#current-mcp-tool-surface)
- [快速入门](#getting-started)
- [前提条件](#prerequisites)
- [所需工具](#required-tools)
- [外部运行时依赖（依赖于配置文件）](#external-runtime-dependencies-profile-dependent)
- [可选但推荐](#optional-but-recommended)
- [快速入门（仅 API 路径）](#quick-start-api-only-path)
- [1. 构建和配置](#1-build-and-configure)
- [2. 运行干燥运行烟雾测试](#2-run-a-dry-run-smoke-test)
- [3. 运行实时 API 调用](#3-run-a-live-api-call)
- [作为 MCP 服务器运行](#running-as-an-mcp-server)
- [本地标准输入/输出服务器](#local-stdio-server)
- [⚠️ 常见陷阱：主机托管环境](#️-common-gotcha-host-managed-environment)
- [引擎配置文件](#engine-profiles)
- [浏览器配置文件设置说明](#browser-profile-setup-notes)
- [配置解析](#configuration-resolution)
- [开发与运维](#development--operations)
- [开发与验证](#development-and-verification)
- [项目脚本](#project-scripts)
- [所需质量门控](#required-quality-gates)
- [发布与自动发布](#publishing--auto-release)
- [此流水线的作用](#what-this-pipeline-does)
- [一次性设置](#one-time-setup)
- [如何触发发布](#how-a-release-is-triggered)
- [使用 npx（无需安装）运行](#run-with-npx-no-install)
- [依赖模型](#dependency-model)
- [Docker 工作流（推荐）](#docker-workflow-recommended)
- [故障排除](#troubleshooting)
- [参考](#reference)
- [项目布局](#project-layout)
- [致谢](#acknowledgments)
<a id="product-overview"></a>
## 产品概述
<a id="intelligence-gap"></a>
### 智能差距与“代理聊天”税收
在诸如 Claude Code 或 Codex 等自主编码工具中，访问顶级推理模型可能会因计划、环境和主机集成而有所不同。即使存在访问权限，标准代理也倾向于在寻求帮助时将整个工作历史记录发送给模型。
这包括冗余的 `git status` 检查、大量的 `grep` 输出、工具调用 JSON 块以及代理的内部独白。这种“代理聊天”会产生噪音，稀释模型的焦点，并浪费昂贵的代币。
**DelphiCourier 充当中转站**。它接收由代理执行的混乱探索，并将其提炼成“纯净上下文”交付。DelphiCourier 通过仅提供相关部分来防止您最强大的模型浪费代币在无关代码上。
- **代理驱动的范围**：您的代理明确选择要包含的内容（`file_chunk`、`diff_hunk`、行范围、引用）。
- **粒度上下文控制**：仅发送特定的文件、差异和代码范围。
- **确定性预算**：可预测的代币估算，带有可审计的缩小跟踪。无沉默截断惊喜。
- **引擎抽象 + 回退**：将浏览器 Oracle 和 API 引擎置于一个 MCP 工具合同之下。
- **可观察的运行**：稳定的运行 ID、尝试日志、代币报告和结构化工件。
```mermaid
flowchart LR
A["CLI 代理模型<br/>较便宜且擅长代理任务 <br/> 例如 GPT 5.3 Codex"] -->|"探索存储库<br/>生成配方"| B("DelphiCourier<br/>上下文中转站")
B -->|"剥离工具日志<br/>强制预算"| C{"干净代码<br/>上下文"}
C -->|"运送有效载荷"| D["Oracle 模型<br/>推理和服务器端搜索最佳但昂贵 <br/> 例如 GPT 5.2 Pro"]
D -->|"结构化<br/>指导"| A
```
<a id="the-stack"></a>
### 堆栈：DelphiCourier 的位置
| 组件 | 角色 | 责任 |
| --- | --- | --- |
| **CLI 代理** | 资源管理器 | 探索存储库，运行 `git`，并通过编写上下文配方决定什么重要。 |
| **DelphiCourier 中转站** | 运送者 | 验证配方，强制执行严格的代币预算，并处理引擎回退/重试行为。 |
| **Oracle 引擎** | 大脑 | 接收干净的、预算代币的提示，进行深入推理，并返回结构化指导。 |
<a id="why-the-name"></a>
### 为什么命名
- `Delphi`：向古希腊德尔斐神谕致敬。
- `Courier`：此工具将正确的证据运送到神谕，而不是整个代码库。
简而言之：DelphiCourier 是您 CLI 代理和推理引擎之间的物流层。
<a id="what-delphicourier-does"></a>
### DelphiCourier 实际执行的操作
DelphiCourier 在调用模型之前，在 **3 个维度**上限定上下文：
1. **路径范围（哪里）**：哪些文件/路径被包含。
2. **修订范围（何时）**：哪些引用/差异被包含（`ref`、`base_ref`、`head_ref`、`diff_hunk`）。
3. **范围范围（多少）**：哪些确切的行范围和优先级被包含（`start_line`、`end_line`、`context_rank`）。
然后运行执行管道：
1. 验证存储库上下文的配方（`file_chunk`、`diff_hunk`）
2. 构建预算代币的提示
3. 调用一个或多个配置的引擎（带有回退/重试）
4. 返回结构化指导和运行诊断/工件
<a id="mcp-tool-surface"></a>
### 当前 MCP 工具界面
DelphiCourier 当前公开以下 MCP 工具端点：
| MCP 工具 | 目的 | 典型用途 |
| --- | --- | --- |
| `get_recipe_schema` | 获取 `consult_oracle` 所需的配方格式（模式 + 示例）。 | 仅在构造或修复配方有效载荷时使用。 |
| `consult_oracle` | 主要的 Oracle 分析入口，读取问题 + 配方并返回带有证据和上下文请求的指导。 | 主动用于影响分析、回归风险审查、不变性验证、提交/PR 语义审查和跨模块更改；如果涉及 >1 文件，请优于手动检查。 |
| `get_config_summary` | 获取活动 Oracle 配置和可用引擎/预算配置文件。 | 在 `consult_oracle` 之前使用，当代币预算或配置文件选择不确定时。 |
有关完整的架构详细信息、合同模式和 Ralph-loop 计划上下文，请阅读 `tech_spec.md`。
<a id="getting-started"></a>
## 快速入门
<a id="prerequisites"></a>
### 前提条件
<a id="required-tools"></a>
#### 所需工具
- `git`（DelphiCourier 通过 git 引用读取存储库内容）
- `node` 22+
- `pnpm` 10+（建议使用 Corepack）
- `jq`（由 `scripts/pre-commit-checks.sh` 使用）
<a id="external-runtime-deps"></a>
#### 外部运行时依赖（依赖于配置文件）
- OpenAI 响应 API 引擎：
- 需要 `OPENAI_API_KEY`
- ChatGPT 浏览器引擎：
- 使用 `npx -y @steipete/oracle`
- 可能需要一次性手动浏览器登录
- 可选打包/压缩集成：
- 当启用打包时使用 `npx -y repomix`
<a id="optional-recommended"></a>
#### 可选但推荐
- Docker + Docker Compose（可复制检查，避免主机 `esbuild` 平台不匹配问题）
<a id="quick-start"></a>
### 快速入门（仅 API 路径）
这是成功运行的首选最快路径。
<a id="build-and-configure"></a>
#### 1. 构建和配置
```bash
pnpm install
pnpm build
export DELPHICOURIER_CONFIG="$(pwd)/examples/config.mvp.json"
export OPENAI_API_KEY="sk-your-key-here"
```
重要：`examples/config.mvp.json` 引用 `api_key_env: "OPENAI_API_KEY"`。变量必须存在于与 MCP 服务器相同的进程上下文中。
实时调用前所需的配置检查：
- `repo_root` 应该是一个绝对路径，指向您的 git 存储库（例如 `/Users/you/projects/delphicourier`）。使用 `"."` 可能会在您的 MCP 主机从另一个工作目录启动 DelphiCourier 时失败。
- `engines.openai_responses_api.base_url` 必须与您的 API 网关匹配：
- OpenAI 直接：`https://api.openai.com/v1`
- LiteLLM 代理：您的 LiteLLM URL（例如 `https://litellm.example.com/v1`）
- `OPENAI_API_KEY` 必须与选定的网关匹配，在 `~/.codex/config.toml` 中配置：
- OpenAI 直接：OpenAI API 密钥
- LiteLLM 代理：有效的 LiteLLM 代理令牌
`~/.codex/config.toml` 配置示例
```
[mcp_servers.delphicourier]
command = "/path/to/your/node/.nvm/versions/node/v22.16.0/bin/node"
args = ["/path/to/the/repo/delphicourier/dist/src/stdio.js"]
[mcp_servers.delphicourier.env]
DELPHICOURIER_CONFIG = "/path/to/the/repo/delphicourier/examples/config.mvp.json"
OPENAI_API_KEY = "sk-xxxx"
```
<a id="dry-run-smoke-test"></a>
#### 2. 运行干燥运行烟雾测试
此操作在不花费模型代币的情况下验证设置。
```bash
pnpm build
node examples/run-consult-oracle.mjs examples/consult_oracle.minimal.dry_run.json`
```
预期指标：
- `status: "ok"`
- `engine_attempts[*].status: "skipped"`（因为 `dry_run: true`）
- `token_report` 存在
<a id="live-api-call"></a>
#### 3. 运行实时 API 调用
创建 `/tmp/consult_oracle.api_only.json`：
```json
{
"question": "Review src/server.ts",
"engine_profile": "api_only",
"budget_profile": "balanced",
"recipe": {
"version": 1,
"items": [
{
"type": "file_chunk",
"path": "src/server.ts",
"start_line": 1,
"end_line": 54,
"context_rank": "high"
}
]
}
}
```
运行：
```bash
pnpm build
node examples/run-consult-oracle.mjs /tmp/consult_oracle.api_only.json`
```
预期指标：
- `status: "ok"`
- `engine_attempts[0].status: "success"`
<a id="running-as-an-mcp-server"></a>
### 作为 MCP 服务器运行
<a id="local-stdio-server"></a>
#### 本地标准输入/输出服务器
```bash
pnpm install
pnpm build
pnpm mcp:stdio`
```
<a id="common-gotcha-host-managed-environment"></a>
#### ⚠️ 常见陷阱：主机托管环境
如果您的 MCP 主机显式管理服务器环境，您必须在那里注入配置路径和 API 密钥。 Codex Desktop `~/.codex/config.toml` 示例：
```toml
[mcp_servers.delphicourier]
command = "node"
args = ["/absolute/path/to/delphicourier/dist/src/stdio.js"]
[mcp_servers.delphicourier.env]
DELPHICOURIER_CONFIG = "/absolute/path/to/delphicourier/examples/config.mvp.json"
OPENAI_API_KEY = "sk-..."
```
然后重启主机应用程序，以便 MCP 服务器进程获取更新的环境变量。
如果 DelphiCourier 无法看到配置中引用的环境变量，它将返回 `CONFIG_ENV_SECRET_MISSING`。
<a id="engine-profiles"></a>
### 引擎配置文件
在 `examples/config.mvp.json` 中定义：
- `default`: `chatgpt_web_oracle` -> `openai_responses_api`
- `api_only`: `openai_responses_api`
- `chatgpt_web_oracle_only`: 仅浏览器
<a id="browser-profile-setup-notes"></a>
#### 浏览器配置文件设置说明
浏览器配置文件运行 Oracle CLI（`npx -y @steipete/oracle`）。您可能需要一次性手动登录以建立会话/cookie。
快速检查：
```bash
npx -y @steipete/oracle --help`
```
然后重试 `engine_profile: "default"` 或 `chatgpt_web_oracle_only`。
<a id="configuration-resolution"></a>
### 配置解析
查找优先级：
1. `--config`
2. `DELPHICOURIER_CONFIG`
3. `DELPHICOURIER_HOME/config.json`
4. `~/.delphicourier/config.json`
5. 内置默认值
使用 `get_config_summary` 确认活动配置文件/路径。
<a id="development-and-operations"></a>
## 开发与运维
<a id="development-and-verification"></a>
### 开发与验证
<a id="project-scripts"></a>
#### 项目脚本
```bash
pnpm typecheck`
- `pnpm test`
- `pnpm build`
- `pnpm mcp:stdio`
```
<a id="required-quality-gates"></a>
#### 所需质量门控
```bash
scripts/pre-commit-checks.sh
pnpm typecheck`
pnpm test`
pnpm build`
pnpm build && node examples/run-consult-oracle.mjs examples/consult_oracle.minimal.dry_run.json`
```
<a id="publishing-and-auto-release"></a>
### 发布与自动发布
此存储库现已包含：
- `.github/workflows/ci.yml`: PRs/pushes 上的质量门控。
- `.github/workflows/release.yml`: `main` 上的 semantic-release 作业。
- `.releaserc.json`: 发布分支/标签/插件配置。
<a id="what-this-pipeline-does"></a>
#### 此流水线的作用
在每次推送到 `main` 时，发布工作流：
1. 运行 `typecheck`、`test`、`build` 和干燥运行烟雾检查。
2. 使用 semantic-release 检查公约提交。
3. 如果找到可发布的提交，则发布到 npm 并创建 GitHub 版本。
4. 将版本标记为 `vX.Y.Z`。
如果没有可发布的提交，工作流在没有发布的情况下退出。
<a id="one-time-setup"></a>
#### 一次性设置
1. 确保 `package.json` 具有最终的公共包名称。
2. 创建一个 npm 自动化令牌（具有该包/作用域的发布权限）。
3. 添加 GitHub 存储库秘密：
- `NPM_TOKEN`: npm 自动化令牌。
4. 确保 GitHub Actions 具有创建版本的权限（默认情况下使用 `release.yml` 中的工作流权限启用）。
可选但推荐：
- 在 `main` 上启用分支保护，以便 CI 必须在合并之前通过。
- 强制执行 Conventional Commit 格式（`feat:`、`fix:`、`perf:` 等），以便版本号是可预测的。
<a id="how-a-release-is-triggered"></a>
#### 如何触发发布
- `feat:` -> 次要版本更新
- `fix:` / `perf:` -> 补丁更新
- `BREAKING CHANGE:` 页脚或 `!` 标记 -> 主版本更新
示例：
```text
feat(mcp): add context request hints for consult_oracle
```
<a id="run-with-npx-no-install"></a>
#### 使用 npx 运行（无需安装）
发布后，用户可以使用 npx 运行 MCP 服务器，无需全局安装：
```bash
npx -y delphicourier
```
对于 MCP 主机（示例）：
```toml
[mcp_servers.delphicourier]
command = "npx"
args = ["-y", "delphicourier"]
[mcp_servers.delphicourier.env]
DELPHICOURIER_CONFIG = "/absolute/path/to/config.json"
OPENAI_API_KEY = "sk-..."
```
<a id="dependency-model"></a>
#### 依赖模型
- npm 包依赖项（`package.json -> dependencies`）在用户运行 `npx -y delphicourier` 时自动安装。
- 仅在 CI/发布中使用构建工具（`devDependencies`），运行时不使用。
- 由所选引擎配置文件调用的外部可执行文件仍然是运行时前提条件：
- `npx -y @steipete/oracle` 用于浏览器 Oracle 引擎配置文件。
- API 配置文件需要 `OPENAI_API_KEY`。
<a id="docker-workflow"></a>
### Docker 工作流（推荐）
如果主机测试因平台原生 `esbuild` 错配而失败，请使用 Docker 进行可靠的验证：
```bash
docker compose build
docker compose run --rm dev pnpm typecheck`
docker compose run --rm dev pnpm test`
docker compose run --rm dev pnpm build`
docker compose run --rm dev bash -lc 'pnpm build && node examples/run-consult-oracle.mjs examples/consult_oracle.minimal.dry_run.json`
```
<a id="troubleshooting"></a>
### 故障排除
| 错误 | 常见原因 | 修复 |
| --- | --- | --- |
| `CONFIG_ENV_SECRET_MISSING` | MCP 服务器进程无法看到所需环境变量（例如 `OPENAI_API_KEY`）。 | 确认 `api_key_env` 名称在配置中并在启动 MCP 服务器的主机进程中注入/导出环境变量。重启主机/服务器。 |
| `ENGINE_API_AUTH_FAILED` | 无效的密钥/令牌用于配置的 `base_url`（例如 LiteLLM 代理令牌不匹配）。 | 验证 `engines.openai_responses_api.base_url`，刷新 `OPENAI_API_KEY` 中的凭证，然后重启主机/服务器。 |
| `timed out awaiting tools/call` | 主机超时小于浏览器引擎运行时。 | 使用 `engine_profile: "api_only"` 进行设置验证或增加主机工具超时。 |
| `invalid_json_schema` | 运行过时构建或架构更改后运行过时服务器进程。 | `pnpm build`，然后重启 MCP 服务器/主机。 |
| `fatal: not a git repository` | 在存储库根目录之外或配置中 `repo_root` 错误运行。 | 从存储库根目录运行并/或修复配置中的 `repo_root`。 |
附加说明：
- DelphiCourier 输出中 `started_at` / `ended_at` 的值为 `1970-01-01T00:00:00.000Z`，适用于确定性测试，而不是壁钟时间。
<a id="reference"></a>
## 参考
<a id="project-layout"></a>
### 项目布局
- `src/`: 工具、引擎、模式、配置加载器、提示/缩小逻辑
- `tests/`: 单元 + 集成测试
- `examples/`: 启动器配置 + 有效载荷样本
- `scripts/`: 存储库检查
- `tech_spec.md`: 架构、合同和实施计划
<a id="acknowledgments"></a>
### 致谢
DelphiCourier 建立在几个优秀项目的肩膀上：
- **[Oracle](https://github.com/steipete/oracle)** (`steipete/oracle`): 核心引擎自动化依赖和项目名称的灵感来源。它完美地弥合了与基于浏览器的 AI 运行的差距。
- **[gitcontext](https://github.com/kccarlos/gitcontext)** (`kccarlos/gitcontext`): 用于精确构建代码库上下文的 UI 驱动的先驱。它证明了粒度视觉上下文组装可以产生更好的人工智能结果。
- **[repomix](https://github.com/yamadashy/repomix)** (`yamadashy/repomix`): 代码库打包和压缩技术的灵感来源，用于 DelphiCourier 的确定性缩小逻辑。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器