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> 替换为仓库克隆/检出后的实际绝对路径（路径含中文或空格时必须用绝对路径）：

{
  "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，克隆后随仓库分享给团队）：

{
  "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）：

./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）。

常用命令

# 生成测试集 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 实现全内联降级链）