plain-sight

版本： 1.0.0

一个AI 描述它所看到的内容。 生成式图像描述器 — MCP 服务器 + CLI，封装了 Florence-2 (MIT) 用于散文描述、OCR 和 LoRA 数据集标注旁文件。 本地运行，默认确定性输出。

是 ai-eyes-mcp 的姊妹项目：

诚实性契约

描述是生成式的：流畅、通常准确，但也可能虚构细节。plain-sight 使输出可复现（确定性解码——同一张图像产生相同的标注），而非保证真实。如需验证关于图像的特定主张，请使用 ai-eyes-mcp 的 image_verify——它测量，不叙述。这两个工具在设计上属于不同的模型家族，因此可以相互校验。

Related MCP server: fm-mcp-comfyui-bridge

工具（MCP）

快速开始

pip install -e .
plain-sight-mcp   # starts the STDIO MCP server

或作为模块运行：python -m plain_sight

CLI

# One image, full paragraph
plain-sight describe hero.png

# One short sentence
plain-sight describe hero.png --detail low

# OCR
plain-sight ocr screenshot.png

# The dataset lane: caption a directory into .txt sidecars with a trigger token
plain-sight batch ./dataset --prefix "mcpt_style, " --detail high

# Re-runs are idempotent — existing sidecars are skipped unless you --overwrite
plain-sight batch ./dataset --prefix "mcpt_style, " --overwrite

Claude Code 配置

{
  "mcpServers": {
    "plain-sight": {
      "command": "plain-sight-mcp",
      "env": {
        "PLAIN_SIGHT_MODEL_DIR": "/path/to/model/cache"
      }
    }
  }
}

标注契约（数据集通道）

专为 LoRA 训练集（style-dataset-lab 等）设计：

• 精确基名配对： img_0042.png → img_0042.txt。无计数器 后缀——不同于 ComfyUI 的 SaveText 节点（会追加 _00001）。

• 直接拼接： 旁文件包含 prefix + caption + suffix， 不插入任何分隔符。想要 "mcpt_style, <caption>"？将 逗号空格放在前缀中。

• 幂等重运行： 现有旁文件会被跳过（且不消耗成本），除非 使用 --overwrite / overwrite=true。

• 确定性： do_sample=false + 束搜索——对未更改的图像重新标注 会生成相同的文本，因此差异具有意义。

细节层级

Florence-2 的原生任务阶梯：

high 是一个段落，而非一篇短文——Florence-2 是一个紧凑（0.77B）模型。 它的优势在于吞吐量和许可证，而非艺术评论的深度。如果标注看起来 被截断，请提高 max_new_tokens（默认 1024，最大 4096）。

配置

日志： 仅输出到 stderr（stdout 是 MCP 协议通道），logger 名称 plain_sight。

首次调用： 模型延迟加载——首次 describe/OCR 调用会加载 Florence-2（GPU 上约 10–20 秒；首次调用会下载约 1.5 GB）。后续 调用在现代 GPU 上以 high 细节处理每张图像约需 1–2 秒。

许可证立场

• 本工具： MIT。

• 模型： 固定为 florence-community/Florence-2-large——微软 Florence-2 发布的官方原生 transformers 转换版本。 MIT（hub 许可证标签验证于 2026-08-19）。商业使用无问题。

• 为何不使用 microsoft/Florence-2-large？ 相同的权重，相同的 MIT 许可证， 但原始仓库附带预原生配置，只能通过 trust_remote_code 加载——本工具原则上拒绝使用。社区 转换版本可通过 transformers 的内置 Florence-2 类加载。

• 刻意不提供： Florence-2 微调模型动物园（MiaoshouAI PromptGen、CogFlorence、SD3/Flux 标注器、Castollux）。它们的许可证 未经验证；在明确之前不会纳入。将 PLAIN_SIGHT_MODEL_ID 覆盖为 其中一个模型是可能的，但许可证问题将由您自行承担。

• 无远程代码： 引擎仅使用 transformers 的原生 Florence-2 支持——从不传递 trust_remote_code，因此不会执行任何从 hub 获取的 Python 代码。这要求 transformers >= 4.51。

安全与信任

此工具仅本地运行。

• 接触的数据： 本地图像文件（只读）；HuggingFace 模型缓存 （首次下载时写入一次）；.txt 标注旁文件——这是它唯一写入的文件， 且仅写入调用者指定的位置（out_dir 或图像旁边）， 现有旁文件仅在显式 --overwrite 下才会被替换。

• 运行时无网络出站流量——模型在首次使用时下载一次， 之后所有推理均在本地进行。

• 无远程代码执行——仅使用原生 transformers 类； 从不传递 trust_remote_code，因此不会执行任何 hub 获取的代码。

• 不处理机密信息，无遥测——不读取或发送任何内容。

• 仅结构化错误——原始堆栈跟踪永远不会到达 MCP 客户端或 CLI 用户。CLI 退出代码：0 成功 · 1 用户错误 · 2 运行时错误 · 3 部分成功。

完整政策：SECURITY.md。积极维护；受支持的 版本列于其中。

要求

• Python >= 3.10

• transformers >= 4.51（原生 Florence-2）

• 推荐使用 CUDA GPU（FP16 下约需 2 GB 显存）；CPU 回退可用（较慢）

• 首次使用需下载约 1.5 GB 模型

开发

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# CI-safe tests (no model, no GPU)
pytest tests/test_edge_cases.py -v

# Dogfood tests (real model + GPU)
pytest tests/test_dogfood.py -v

# Full verify: imports, edge tests, build
bash verify.sh

架构

engine.py    Standalone Florence-2 wrapper — no MCP dependency.
             Lazy-loads the model; validation runs BEFORE the load.
             Importable directly: from plain_sight.engine import Florence2Engine

sidecars.py  The training-data contract, pure stdlib: basename pairing,
             bare concatenation, directory expansion. Testable without torch.

server.py    FastMCP wrapper exposing engine methods as MCP tools.
             Thin layer: validation, error shaping, tool metadata.

cli.py       argparse CLI over the same engine (describe / ocr / batch /
             status / selftest). Structured errors, meaningful exit codes.

架构刻意借鉴了 ai-eyes-mcp——相同的 引擎/服务器拆分、相同的错误塑造、相同的自检模式。同一契约的云端 姊妹版本在 Comfy Cloud 上作为 caption-florence2-v1 工作流运行（每任务一个图像的元数据附加项；此工具 是批量通道）。

许可证

MIT

由 MCP Tool Shop 构建