图像自适应切分 Mutton-hub/adatile-mcp

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": {json
"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 实现全内联降级链）