内容
# JD Codec 连接器
```bash
npm install -g jdcodec
```
**通过本地代理降低浏览器代理任务的 token 成本约 80%+。PII 信息从未离开您的机器。**
JD Codec 连接器是一个本地 MCP（模型上下文协议）代理，位于您的代理和 [Playwright MCP](https://github.com/microsoft/playwright-mcp) 之间。它在您的代理看到页面快照之前压缩页面快照，使用云压缩服务。大型的 DOM/ARIA 快照变为紧凑的增量；您的代理在不失去对任何元素采取行动的能力的情况下接收较小的输入。
**设计优先考虑隐私。** 每个快照都在您的机器上扫描 PII 信息，然后再传输任何字节 - 电子邮件、电话号码、信用卡、API 密钥、地址和 30 多个其他类别在传输之前被替换为类别令牌，如 `{{REDACTED_EMAIL}}`。如果云服务无法访问，连接器会退回到返回（已经编辑过的）快照不变 - 您的代理永远不会被我们阻塞。
---
## 您需要
- macOS 或 Linux
- Node.js 22 或更新版本（`node --version`）
- 一个支持 MCP 的代理客户端 - Claude Code、Cursor 或任何其他可以启动 MCP stdio 服务器的客户端
- 一个 JD Codec API 密钥 - 发送电子邮件至 `hello@jdcodec.com`
---
## 安装
```bash
npm install -g jdcodec
```
这会在您的 `PATH` 上安装 `jdcodec` 二进制文件。从那里，您可以直接在任何支持 MCP 的客户端配置中引用它，该客户端会启动一个 stdio 命令。验证如下：
```bash
jdcodec --help
```
还提供了一个 Python 发行版 - `pip install jdcodec` 是与同一个连接器二进制文件一起运行的薄包装，通过 `npx` 获取和运行。任一入口点都有效；请选择适合您项目主要语言的入口点。
---
## 配置您的 API 密钥
两种选项；请选择一种。
### 选项 A - 环境变量
```bash
export JDC_API_KEY='jdck_yourid.yoursecret'
```
适用于一次运行或当您的代理框架已经管理环境变量时。
### 选项 B - 配置文件
```bash
mkdir -p ~/.jdcodec
cat > ~/.jdcodec/config.json <<EOF
{
"api_key": "jdck_yourid.yoursecret"
}
EOF
chmod 600 ~/.jdcodec/config.json
```
适用于持久设置；连接器在 `JDC_API_KEY` 未设置时自动读取此文件。
`jdck_` 前缀是您的密钥的公共部分（在日志和仪表板中安全）。点之后的秘密部分是敏感的 - 将完整的 bearer 字符串像密码一样对待。
---
## 将其连接到您的代理
任何支持 MCP 的客户端都可以启动 stdio 命令来使用连接器 - 交换是一行代码：
- **来自** `command: "npx", args: ["@playwright/mcp", "--no-sandbox", "--isolated"]`
- **至** `command: "jdcodec"`（不需要额外参数；传递任何您正在使用的 Playwright MCP 参数）
连接器将 Playwright MCP 本身作为子进程启动，并代理所有内容。您的代理看到的工具与以前相同（`browser_snapshot`、`browser_click` 等），除了快照较小之外，没有其他行为变化。
**Claude Code（CLI + Claude VS Code 扩展）：** `claude mcp add --scope user jdcodec -- jdcodec`。Claude Code 命令行 CLI 和 Anthropic 的 Claude VS Code 扩展都从 `~/.claude.json` 读取 MCP 服务器，因此此单个命令连接两者。
**Cursor：** 添加到 `~/.cursor/mcp.json`:
```json
{ "mcpServers": { "jdcodec": { "command": "jdcodec", "env": { "JDC_API_KEY": "jdck_yourid.yoursecret" } } } }
```
**通用 MCP 客户端（Python `mcp` SDK、TypeScript `@modelcontextprotocol/sdk` 等）：** 将 stdio 启动指向 `jdcodec` 而不是 `npx @playwright/mcp`。如果您需要为特定客户端复制粘贴配置，请发送电子邮件至 `hello@jdcodec.com`。
---
## 验证它是否正在运行
启动涉及 `browser_snapshot` 的任何代理任务。在 stderr 上，您应该看到类似这样的结构化日志行：
```json
{"level":"info","event":"snapshot","frame":"…","input_chars":40123,"output_chars":5432,"reduction":0.86}
```
该 `reduction: 0.86` 是每个快照的压缩率 - 您的代理将消耗的 token 数量与实际接收的 token 数量相比。
如果您在几个快照后仍未看到这些日志行，请参阅下面的[故障排除](#troubleshooting)。
---
## 出口
### `JDC_BYPASS=1` - 跳过云
```bash
JDC_BYPASS=1 jdcodec
```
在禁用云的情况下运行连接器。您的代理仍然接收编辑过的 PII 快照，但未压缩。适用于：
- 无网络的本地调试
- 比较代理在有压缩和无压缩情况下的行为
- 隔离演示隐私盾
快照中将出现 `{{REDACTED_…}}` 令牌。这是预期的 - 盾牌无论云是否被调用都会运行。
### `JDC_LLM_PROVIDER` - 准确的节省数字（可选，推荐）
```bash
export JDC_LLM_PROVIDER=anthropic # 其中之一：anthropic, openai, gemini
export JDC_LLM_MODEL=claude-sonnet-4-6 # 可选，细化新模型系列的标记器
```
**为什么设置此项：** JDC 压缩您的快照，这会减少您向提供商支付的 LLM 费用。节省的金额取决于提供商用于计算 token 的标记器 - Anthropic、OpenAI 和 Google 每个 token 化相同的文本，最高可达 ~22%。告诉 JDC 您使用的提供商，让它使用与提供商计费相同的标记器来计算 token，这样 JDC 报告给您的节省数字（在 `jdcodec savings` 和您的使用报告中）与您发票上显示的实际节省数字相符。否则，JDC 使用近似标记器引用节省数字，并将报告标记为近似。
**JDC 对该值执行的操作：** 选择用于计算 token 的正确标记器。除此之外，它不转发给您的 LLM 提供商，不会更改存储的快照信息，也不会用于路由模型调用 - JDC 设计上从未看到您的 LLM API 密钥。该值随每个快照请求一起传输，代码存储在会话中，并在计算报告的 token 时进行查询。
两个实用说明：
- **聚合路由：** 如果您通过 AWS Bedrock 或 Vertex 调用 Claude，请设置 `anthropic`（而不是 `bedrock`/`vertex`）- 聚合器路由请求，但底层模型仍然标记化。适用于 Azure OpenAI → `openai`。标记器系列跟随模型，而不是传输。
- **每个会话的第一个快照获胜：** JDC 在会话的第一个快照上绑定您的提供商，并在之后忽略更改。设置一次并忘记；在任务中途旋转不会产生任何影响，直到下一个会话。
如果 `JDC_LLM_PROVIDER` 设置为除 `anthropic`/`openai`/`gemini` 之外的任何值，连接器将在启动时记录 `config.agent_llm_invalid` 警告，并回退到近似标记器（以防输入错误导致错误的数字）。
替代环境变量：在 `~/.jdcodec/config.json` 中添加 `agent_llm`:
```json
{ "api_key": "jdck_yourid.yoursecret",
"agent_llm": { "provider": "anthropic", "model": "claude-sonnet-4-6" } }
```
如果同时存在 `JDC_LLM_PROVIDER` 环境变量和配置文件，则环境变量优先。
### `JDC_REGION` - 固定区域（可选）
设置为最近的 Cloudflare 区域，以降低长时间运行会话的延迟：
| 值 | 区域 |
|---|---|
| `wnam` | 西北美洲 |
| `enam` | 东北美洲 |
| `sam` | 南美洲 |
| `weur` | 西欧 |
| `eeur` | 东欧 |
| `apac` | 亚太地区 |
| `oc` | 大洋洲 |
| `afr` | 非洲 |
| `me` | 中东 |
```bash
export JDC_REGION=oc # 例如：悉尼
```
默认情况下，“路由到距离您第一个请求最近的边缘”。设置此选项仅在持续超过一两分钟的会话中有所帮助；较短的任务不会注意到差异。
---
## 故障时的温和降级
连接器设计为您的代理永远不会被我们阻塞。具体来说：
- **网络错误/超时/云返回 5xx** → 已经编辑过的快照转发给您的代理，不变；`codec_unreachable` 警告记录到 stderr。您的任务继续。
- **API 密钥无效/吊销** → 行为相同；连接器记录身份验证失败并继续。
- **PII 盾牌失败** → 连接器返回错误给您的代理，而不是泄漏未经扫描的字节。这是失败的唯一情况，达到您的代理。设置 `JDC_PRIVACY_FAIL_OPEN=1` 以切换到“记录 CRITICAL 并传递未经扫描的快照” - 仅在您了解隐私影响时使用此选项。
云服务目标 ≥99.5% 的可用性。在 alpha 版本中，您可能会在部署期间看到偶尔的 `codec_unreachable` 日志记录 - 这些通常少于一秒，您的代理不会注意到。
---
## 关于您使用情况的记录
为了计费和调试，我们记录每个快照的一个事件：
- `api_key_id`（`jdck_` 前缀，不是秘密）
- 会话和任务 ID（您选择；我们不会关联跨密钥）
- 时间戳，输入/输出字符数，延迟指标
- URL（在 PII 盾牌运行后）
- PII 盾牌的类别计数（例如 `{"email": 2}`）- **不记录编辑值**
我们 **不存储**:
- 原始快照内容
- 编辑后的 URL 路径或查询字符串（超出 URL 适合的部分）
- PII 盾牌捕获的任何内容
默认保留期为 90 天（按密钥配置）。如果您想要完整的 数据处理摘要 或更短的保留期，请发送电子邮件至 `hello@jdcodec.com`。
---
## 环境参考
| 变量 | 是否必需？ | 默认值 | 它执行的操作 |
|---|---|---|---|
| `JDC_API_KEY` | 是¹ | - | 您的 bearer token，形状为 `jdck_id.secret`。 |
| `JDC_BYPASS` | 否 | `0` | `1` 完全跳过云；盾牌仍然运行。 |
| `JDC_CLOUD_URL` | 否 | `https://api.jdcodec.com` | 覆盖端点。 |
| `JDC_REGION` | 否 | - | Cloudflare 区域提示，用于会话固定。 |
| `JDC_LLM_PROVIDER` | 否（推荐） | - | 您的 LLM 提供商（`anthropic`/`openai`/`gemini`）。让 JDC 使用与提供商计费相同的标记器来引用节省的 token，因此数字与您的发票匹配。未设置 = 近似节省，明确标记。 |
| `JDC_LLM_MODEL` | 否 | - | 可选模型标识符（例如 `claude-sonnet-4-6`，`gpt-4o`）。细化具有多个模型生成的提供商的标记器选择。忽略除非 `JDC_LLM_PROVIDER` 也设置。 |
| `JDC_PLAYWRIGHT_CMD` | 否 | `npx` | 生成上游 MCP 服务器的命令。 |
| `JDC_PLAYWRIGHT_ARGS` | 否 | `@playwright/mcp --no-sandbox --isolated` | 上述参数。 `--isolated` 为每个会话提供一个单独的浏览器配置文件，以便多个代理客户端（VS Code + Cursor + Claude Code）不会争夺共享的 `SingletonLock`。 |
| `JDC_TRACE` | 否 | `0` | `1` 将快照跟踪写入 `JDC_TRACE_DIR` 进行调试。 |
| `JDC_TRACE_DIR` | 否 | `traces/` | 跟踪信息存储的位置。 |
| `JDC_PRIVACY_FAIL_OPEN` | 否 | `0` | 调试用盾牌错误逃生舱（见上文）。 |
¹ 如果 `JDC_BYPASS=1`，则不必需。
---
## 故障排除
**启动时出现“config.missing_api_key”** → 设置 `JDC_API_KEY` 或创建 `~/.jdcodec/config.json`。或者，如果您只想在本地使用隐私盾，请运行 `JDC_BYPASS=1`。
**“upstream.start_failed”** → 连接器无法启动 Playwright MCP。检查 `npx @playwright/mcp --no-sandbox --isolated` 是否单独工作；大多数问题是首次运行 Playwright 浏览器下载。
**代理在第一个请求上挂起很长时间** → 在新会话上预计如此。云服务在几秒钟内预热；同一会话中的后续快照在不到一秒的时间内完成。如果每个快照超过 ~10 秒，请检查到 `api.jdcodec.com` 的网络连接。
**`reduction` 在第一个快照上为负数或很小** → 预期。新会话中的第一个快照是一个完整的参考；后续快照会压缩为其压缩版本。会话范围内的压缩率（在会话结束时显示）是有意义的数字。
**代理在使用连接器时与不使用时表现不同** → 发送电子邮件至 `hello@jdcodec.com`，附上跟踪信息（设置 `JDC_TRACE=1` 并附加 `traces/` 中的最新文件）。我们修复这些问题作为阻塞问题。
---
## 获取帮助
一个邮箱用于所有事项：
**`hello@jdcodec.com`** - alpha 访问、API 密钥、计费、错误报告、功能请求、安全报告。
公开的问题跟踪器、状态页面和社区论坛将随即将发布的源可用版本一同推出。
---
## 许可证和范围
发布的连接器二进制文件在 npm 上获得许可使用。云压缩服务是专有的。您的快照根据上述数据处理摘要进行处理。
