agenthand

agenthand

一个为帮助人们销售商品的 AI Agent 提供服务的 MCP 服务。

卖家永远不会打开 agenthand。卖家的 Agent 会调用它。卖家把一张杂乱的商品照片交给 Agent；agenthand 会通过三个工具，按照制作商品 listing 的顺序，将照片转换为可直接用于发布的素材：

工具	功能
draw	将真实商品原封不动地置入生成的场景中（例如，将椅子放在富丽堂皇的房间里，或将游戏商品放在整洁的桌面上），并返回合成图以及保真凭证。
cut_out	从商品照片中分割出商品，并返回一张透明 PNG，通过资源句柄引用。如果未提供概念，则会在内部运行规划步骤；概念是可选的。
identify	工作流中的规划步骤：读取照片并规划分割，返回结构化描述，以及 cut_out 使用的、适合分割的名词短语概念（含备选项）。

保真锁定

draw 绝不会重新生成商品。代码会强制执行以下不变量：

1. 分割过程会提取真实商品前景及其蒙版。
2. 商品图层会原封不动地存储，并记录源文件、前景和蒙版的哈希：每个文件的字节哈希和解码像素哈希都会记录。
3. 图像模型只会生成背景场景底图。它的接口接收提示词和尺寸，绝不会接收商品像素。
4. 确定性代码会将原始商品图层合成到底图上。底图会调整大小并裁剪至商品尺寸；商品图层绝不会缩放。
5. draw 会拒绝任何不是 foreground_png 资源、或未关联回源照片的内容，并在任何像素发生变化之前验证存储的哈希。
6. 结果会附带保真凭证，其中包含源文件、前景和蒙版的哈希、交付文件自身的哈希、所执行的变换、测得的发生变化的不透明前景像素数量、模型调用记录及其成本。凭证还会公布计数排除了哪些内容：边缘带像素数及其最大宽度、蒙版的不透明部分占比、精确的变更像素判定条件（容差为 0），以及源照片和合成图的色彩配置文件标识（ICC 配置文件丢失或发生变化时，即使像素值相同，也会改变商品的颜色，因此会记录并计为保真失败）。

该声明十分明确：存储的提取前景未经更改地进入了合成图，其哈希则精确标识了该图层。边缘带像素（部分透明）在合成时会与底图混合；凭证会单独统计这些像素，不会夸大声明。凭证中的计数是在交付文件上测得的，文件会从存储中解码回来，而且可以独立重新计算：composite.verify_receipt_from_disk 会从存储文件重新统计，检查凭证自身的哈希是否与其所指资源相符，并且只有在变更像素数恰为 0 且存在实际覆盖时才会通过；独立的 agenthand-verify SOURCE FINAL MASK 检查器无需任何存储即可验证导出的文件，同样会拒绝未选中任何内容的蒙版。导入功能支持手机生成的格式（包括 HEIC），并会端到端保留每张照片内嵌的色彩配置文件。

有界的蒙版恢复循环可保护 cut_out：工具会检查蒙版质量，如果蒙版质量不佳，则会使用规划步骤提供的备选概念短语重试一次。每次尝试都会记录在凭证中。

资源句柄

工具之间不会来回传递图像字节。每张图像都存储在本地 （并附有一份以原子方式写入的资产侧车记录），并通过 asset://<id> 引用。句柄可在工具之间串联：identify 读取一个句柄， cut_out 返回一个新句柄，draw 使用该句柄。

图像通过导入流程传入：工具的图像参数可以是现有句柄、 http(s) URL 或 base64 数据 URI。导入流程会限制字节数和像素数，应用 EXIF 方向， 并将图像规范化为 8 位 RGBA PNG。图像通过两种方式传出：draw 会在结果中返回图像预览， 客户端还可以通过 MCP 资源读取每个资产，该资源使用其自身的 asset://<id> URI。

费用回执与支出上限

所有计费调用都会经过一个统一入口 （src/agenthand/meta_client.py），并采用先预留、后结算的计费方式： 在文件锁保护下，先将预计的最坏情况费用与账本核对，并预留一笔待处理回执；调用完成后， 结算回执会根据服务提供商的用量统计记录实际费用。如果调用失败时可能已产生费用， 预留金额仍会计入。若服务提供商的响应不含可用的用量数据，则按预留的预计金额结算， 而不是按 $0 结算：用量缺失绝不会抹去支出。回执会写入本地 JSONL 账本，其中包含工具、 模型、令牌和图像数量、美元估算金额，以及所使用的价格表版本。价格集中存放在一个模块 （src/agenthand/pricing.py）中，因此更改价格只需修改一行并递增版本号；未定价的模型会报错， 不会按 $0 估算。所有支出路径共用同一个账本，包括试运行闸门 （其资产存储与正式环境隔离在临时目录中，但账本不隔离）。

服务器对支出采取失败即关闭策略。默认工作上限为 $120.00；配置可以调高或调低该上限，但不得超过 $150.00 的硬性上限（黑客马拉松提供的额度），任何配置都无法突破此上限。账本条目损坏、 为负数或非有限值时，会拒绝所有支出：支出状态未知，就不允许支出。

状态

黑客马拉松构建版（Meta Global AI Developer Hackathon，2026 年 10 月 26 日至 11 月 4 日）。三个工具均已接入真实的 Meta Model API，并通过支出上限计费入口运行——identify 使用 muse-spark-1.3，cut_out 使用 sam-3.1，draw 使用 muse-image-1.0——整个工具链已完成端到端实测。2026-10-26 的验证运行（identify $0.007544、cut_out $0.0025、draw $0.01；检查了 580,613 个不透明像素， 其中 0 个发生变化）及其保真度回执已发布在 项目网站， 可在浏览器中使用该次运行自身的文件重新执行同一检查。占位图仅保留在显式启用的开发标志后面， 供离线测试使用。目前服务器通过 stdio 在本地运行；托管端点将在之后推出。

服务器也有单二进制文件的 Rust 构建版。它通过了针对上述验证运行冻结文件的奇偶校验， 复现了该次运行的计数和输出像素哈希；此外，Rust 二进制文件的实测运行也经过 Python 验证器交叉核对。Python 实现仍是参考实现；Rust 构建版是同一服务器的第二种实现，两者结果一致。

运行

使用任意 MCP 客户端注册 agenthand。主要方式使用 uv：无需预先安装任何内容，uv 会获取已发布的软件包并运行它。

{
  "mcpServers": {
    "agenthand": {
      "command": "uvx",
      "args": ["agenthand"],
      "env": { "META_API_KEY": "…" }
    }
  }
}

或者使用 pip 安装软件包，并让客户端指向已安装的命令：

pip install agenthand

{
  "mcpServers": {
    "agenthand": {
      "command": "agenthand",
      "env": { "META_API_KEY": "…" }
    }
  }
}

服务器无需密钥即可启动并列出工具；只有工具调用模型时才需要密钥。配置通过环境 变量进行；请参阅 .env.example。

从源代码运行（开发）

git clone https://github.com/AUsernameForYou/agenthand
cd agenthand
python3.12 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/agenthand          # stdio transport
.venv/bin/pytest             # unit tests