# AdaTile-MCP v1.0

高分辨率图像自适应切分预处理层（MCP），目标模型 DeepSeek `deepseek-v4-flash-vision-exp`。
按《AdaTile-MCP 项目构建指南（v1.2）》六周计划完成全部 Phase 0–5。进度与实测数据见 **STATE.md**，当前已发现的问题清单见 **KNOWN_ISSUES.md**。

## 六层流水线（pipeline_v1）

L1 快速通道（magic bytes/懒解码/超限降采样/小图直传）→ L2 显著性（频谱残差 CPU 默认，
U²-Netp 可选，Watchdog 超时降级）→ L3 自适应切分（连通域/预算预分配/连续块选取/文档 fine
路径）→ L4 组装上传（tile 级流水线化编码→上传、三级缓存、合规六项硬校验、降级链）→
L5 流式调用（json_object 强制输出、TTFT 双口径、重试与全局保底）→ L6 规则化合并
（IOU>0.3 同标签并 bbox）。

## 降级行为说明

| 触发 | 行为 | 标记 |
| --- | --- | --- |
| 格式不支持/文件损坏 | 结构化错误，无降级 | `error.stage=L1` |
| 显著性检测超时（>350ms） | 均匀动态网格替代 | trace 可见 |
| Files API 上传失败（重试后） | Σbase64 ≤24MiB 全内联 | `upload_stats.degraded=true` |
| 内联仍超限 | 仅全局缩略图直发 | `channel=degraded_global_only` |
| 模型散文输出（无 JSON） | 强制 JSON 重试一次 | 自动，无需配置 |
| file_id 失效 | 刷新缓存重组装一次 | 自动 |

## 质量与延迟基线（实测，详见 experiments/*.json）

- 首次预处理 p95 1116ms（含真实上传）/ 命中 134ms；TTFT 847ms/613ms；10 并发 100% 成功
- Phase 5 四方案对比与消融：`experiments/phase5_results.json`


## 环境要求

- Python 3.11+（项目内 `.venv` 为 3.13）
- 环境变量 `DEEPSEEK_API_KEY`（DeepSeek 平台申请）
- Windows/Git Bash 下激活 venv：`source .venv/Scripts/activate`
- 新机器一键装环境：`setup.bat`（Windows）/ `setup.sh`（macOS/Linux），见下节

## 从零接入（新机器 / 任意 agent）

`.venv` 与密钥都不随仓库走，新机器只需 5 步：

1. **安装 Python 3.11+**（Windows 安装时勾选 "Add to PATH"）。
2. **获取代码**：`git clone https://github.com/Mutton-hub/adatile-mcp.git`（或复制本目录，无需带 `.venv`）。
3. **装环境**：在项目根运行 `setup.bat`（Windows）或 `./setup.sh`（macOS/Linux）——自动创建 `.venv` 并安装 `requirements.txt` 全部依赖。
4. **配 key**：设置环境变量 `DEEPSEEK_API_KEY`，或复制 `.env.example` 为 `.env` 填入（二者选一；`.env` 已被 `.gitignore` 排除）。
5. **注册 MCP**：按下表把你的 agent 配置指向本机仓库绝对路径下的 `run.bat`（Windows）/ `run.sh`（Unix），重启会话后先调 `adatile_status` 自检。

同一台机器上接入多个 agent 时，只需重复第 5 步（各客户端各自配置），环境与 key 共用。

## MCP 注册 —— 适配任意本地 agent/harness

服务器是标准 MCP（stdio 默认 / http / sse 可选），以下客户端均可接入。
key 解析顺序：**环境变量 `DEEPSEEK_API_KEY` → 项目根 `.env` 文件**（复制 `.env.example` 为 `.env` 填入即可，适合难以注入环境变量的客户端）。

通用形式（所有支持 stdio MCP 的客户端）。`<repo>` 替换为仓库克隆/检出后的实际绝对路径（路径含中文或空格时必须用绝对路径）：

```json
{
  "mcpServers": {
    "adatile-mcp": {
      "command": "<repo>\\run.bat",
      "args": []
    }
  }
}
```

> `run.bat` 启动器自动定位 venv（macOS/Linux 用 `<repo>/run.sh`）。也可直接指向
> `<repo>/.venv/Scripts/python.exe` + `server.py`。

各客户端放置位置：

| 客户端 | 配置文件 | 传输 |
| --- | --- | --- |
| ZCode | 项目根 `.zcode/config.json`（`mcp.servers`）或用户级 `~/.zcode/cli/config.json` | stdio |
| Claude Code | 项目根 `.mcp.json` 或用户级 `~/.claude.json`（`mcpServers`） | stdio |
| Claude Desktop (Win) | `%APPDATA%\Claude\claude_desktop_config.json` | stdio |
| Cursor | `.cursor/mcp.json`（项目）或全局设置 | stdio |
| Cline (VS Code) | `cline_mcp_settings.json` | stdio |
| Continue | `config.yaml` 的 mcpServers 段 | stdio |
| Windsurf | `mcp_config.json` | stdio |
| 自研/远程 harness | `run.bat --transport http --port 8765` | streamable-http（`http://127.0.0.1:8765/mcp`）或 `--transport sse` |

ZCode 项目级配置示例（`<repo>/.zcode/config.json`，克隆后随仓库分享给团队）：

```json
{
  "mcp": {
    "servers": {
      "adatile-mcp": {
        "command": "C:\\path\\to\\cloned-repo\\run.bat",
        "args": []
      }
    }
  }
}
```

### 接入后的使用流程（任意 agent/harness）

1. 配置 key：设置环境变量 `DEEPSEEK_API_KEY`，或复制 `.env.example` 为 `<repo>/.env` 并填入
   （`.env` 已被 `.gitignore` 排除，不会进入版本控制；`adatile_status` 可确认 key 是否就绪）。
2. 注册 MCP 服务器（上表）并重启客户端会话。
3. 先调用 **`adatile_status`**（零 API 调用、零费用）确认 key 配置与本地 L1–L6 能力。
4. 再调用 **`analyze_high_res_image`**，传入 `image_path`（本地绝对路径）与 `task_hint`。
5. 优先使用返回的 `merged_answer`；`objects`/`tile_details` 中的 bbox 可用于精确定位。
6. 同一张图的追问只需重复调用同一 `image_path`——内部三级缓存自动命中，
   无需手动管理 file_id。

HTTP 模式示例（容器/远程 harness）：

```bash
./run.sh --transport http --host 0.0.0.0 --port 8765
# MCP endpoint: http://<host>:8765/mcp
```

**接入后先调用 `adatile_status`**（零 API 调用）确认 key 配置与本地能力，再调用 `analyze_high_res_image`。

## 工具：analyze_high_res_image

| 参数 | 说明 |
| --- | --- |
| `image_path` | 本地图片绝对路径（JPEG/PNG/GIF/WebP，按内容判断） |
| `task_hint` | `ocr` / `describe` / `detect` |
| `strategy` | `auto`（主方案：全局缩略图内联 + 5 tiles 走 Files API）/ `b0` 直传 / `b1` 2×2 / `b2` 3×3 |
| 其余参数 | `max_tiles` / `overlap_ratio` / `image_token_budget` / `upload_channel` —— `max_tiles`、`upload_channel` 为预留参数（orchestrator 尚未接线，当前生效值为其默认值）；`overlap_ratio`、`image_token_budget` 已生效 |

返回：`merged_answer`、`objects`（尽力解析）、`tile_details`（含 bbox 与 file_id）、`latency_ms`、`token_usage`、`upload_stats`、`route`（direct_pass / tile_pipeline）。

## 常用命令

```bash
# 生成测试集 A（50 张 4K 合成图 + ground_truth.json）
.venv/Scripts/python.exe experiments/cases/gen_set_a.py --n 10 --seed 42

# Phase 0 校准实验（先跑一票否决用例！）
.venv/Scripts/python.exe experiments/run_phase0.py --cases TC-0.1.8 TC-0.3.1 TC-0.4.2
.venv/Scripts/python.exe experiments/run_phase0.py --list        # 查看全部用例
.venv/Scripts/python.exe experiments/run_phase0.py --full        # 含重型用例
.venv/Scripts/python.exe experiments/run_phase0.py --rounds 10   # TTFT 轮数控制费用

# 本地自检（无 API 调用）
.venv/Scripts/python.exe -m pytest tests/test_local.py -q

# stdio 端到端冒烟测试（真实子进程 + 官方 MCP SDK，零 API 调用）
.venv/Scripts/python.exe tests/stdio_smoke.py
```

## Agent 侧 System Prompt（模板 B，指南 3.3）

```
当用户上传高分辨率图像（总像素 > 64 万）时：
1. 调用 analyze_high_res_image 工具，传入 image_path 和 task_hint（上传与切片由工具自动经 Files API 完成）；
2. task_hint：文字识别→"ocr"；全景描述→"describe"；具体元素→"detect"；
3. 优先使用 merged_answer；tile_details 中的 bbox 可精确定位；
4. 同一张图的追问请复用工具（内部缓存自动命中）；
5. 禁止直接将原图 base64 传给 VLM——必须走本工具，否则细节丢失。
```

## 降级行为（Phase 0）

- L1 损坏/不支持格式 → 结构化错误 `{stage:"L1", reason:...}`，无降级路径
- 小图（≤64 万像素）→ DirectPass 单次直传
- Files API 不可用 → 主方案暂无自动降级（Phase 3 实现全内联降级链）