# 自主买方与持久任务队列

买方现在可以接受一个文档目标，由真实模型输出下一次 MCP 工具调用。协调程序核对调用后，通过原 Python 客户端执行服务发现、询价、付款及取结果。提取完成后，检查任务绑定原提取任务与已核验交付，两项服务分别支付。

目前支持固定的「文档字段提取 → 文档检查」流程。模型可以从目标选择字段；负责人也可以明确指定字段。服务类型、工具集合、阶段依赖、钱包、网址与付款限额由程序及负责人固定。它尚不具备任意任务拆解、开放服务市场或独立运营者之间的通用协作能力。

## 提交任务

外部程序可以使用可安装的[买方工具包](https://agenavo.xyz/downloads/agenavo-buyer-kit.tar.gz)，按包内说明核对 SHA-256 并安装到仓库外。安装器保留已有配置、模型计数和付款日志，拒绝覆盖已有安装；安装和环境检查不会调用模型或付款。运行时需要 Node 24、Python 3.12 和负责人已配置的模型登录及受限买方权限。

工具包新增五个目标接口：`submit_goal`、`goal_status`、`goal_result`、`goal_events`、`ack_goal_event`。提交完整的原任务，其他调用使用同一个 `jobId`；事件还绑定接收者 `consumer`。结果提供独立校验后的交付内容和原交易引用，交易引用的核验范围仍是 `protocol-metadata-only`。查询和读取通知不触发模型、付款或新任务。失败任务即使有可读取的检查报告，也返回业务失败；暂停任务要求负责人恢复。

在已安装的工具包中运行独立的目标 MCP 服务：

```sh
/absolute/venv/bin/python -B /private/readonly-buyer-kit/goal-mcp/buyer_mcp_server.py \
  --node-executable /absolute/node24/bin/node \
  --buyer-executable /private/readonly-buyer-kit/agenavo.mjs \
  --settings /private/queue-settings.json
```

旧服务工具的五个接口保持原格式，目标接口通过自己的 MCP 服务接入。

需要 Node 24、Python 3.12、原工具包依赖与 `requirements-mcp.txt`，以及这台 Mac 的既有 Codex CLI 登录。模型只返回结构化数据，没有原生工具或钱包签名权限。模型在 Mac 调用，登录凭据不复制到服务器。

先按[文档接入说明](external-document-mcp.md)初始化一个受邀买方；私钥、邀请、队列、模型缓存和付款日志必须位于仓库外。工具策略继续使用原固定工具的格式，设置有限的报价窗口、任务期限、价格与尝试次数。

保存权限 0600 的私有任务文件：

```json
{
  "version": 1,
  "jobId": "document.example.001",
  "objective": "提取 vendor、amount、currency 字段，再购买检查服务核对原文证据。",
  "document": "vendor: Example\namount: 18.50\ncurrency: CNY\n"
}
```

可选 `fields` 指定原字段；省略时模型根据目标选择，第一次通过校验后固定。原文限制为 16 KiB，但较大的证据与字段组合可能超过检查服务的 48 KiB 总输入限制；程序会在首次询价或付款前暂停，要求缩小输入。

队列配置同样私有，所有路径为绝对路径：

```json
{
  "version": 1,
  "stateDirectory": "/private/buyer-queue",
  "modelStateDirectory": "/private/existing-model-pool",
  "maxModelCalls": 36,
  "buyerSettingsFile": "/private/buyer-settings.json",
  "toolPolicyFile": "/private/tool-policy.json",
  "pythonExecutable": "/absolute/venv/bin/python",
  "agentKitDirectory": "/private/readonly-agent-kit",
  "limits": {
    "maxJobs": 2,
    "maxDecisionsPerJob": 8,
    "pollSeconds": 1,
    "heartbeatSeconds": 5,
    "maxConsecutiveFailures": 3,
    "drainSeconds": 30
  }
}
```

这些数字是本轮内部测试的例子，不自动授予对应权限。`maxModelCalls` 是原共用池的累计上限，失败调用也计数，不能用新目录绕过已有计数。正常两阶段流程需要 7 次买方决策和 2 次供应方调用；额外查询状态可能再花一次决策。每个任务最多 8 次买方决策。等待时重复原工具参数，不消耗新模型调用。

模型接口只接受 JSON Schema 的子集，见[官方结构化输出说明](https://developers.openai.com/api/docs/guides/structured-outputs#supported-schemas)。运行程序为模型准备兼容的格式，同时保留原任务格式、请求哈希和本地完整校验；重复字段、改任务编号或改原文仍会被拒绝。

```sh
pnpm run buyer:queue --settings /private/queue-settings.json --action enqueue --job-file /private/job.json
pnpm run buyer:queue --settings /private/queue-settings.json --action status
pnpm run buyer:queue --settings /private/queue-settings.json --action worker
```

同一 `jobId` 和完全相同输入重试会复用原任务；改变输入会拒绝。`maxJobs` 是队列保留的累计任务上限，完成后不删除历史或重新释放这个槽位。

## 后台运行与恢复

`pnpm run buyer:build-release` 生成公开代码 `artifacts/autonomous-buyer-release/{buyer.mjs,manifest.json}`。安装时复制到仓库外的独立目录，目录权限 0500、两个文件权限 0400。Python 工具包须包含 14 个公开文件及原 `manifest.json`，也使用独立只读目录。每次启动校验完整清单与哈希；运行时不依赖 Desktop 路径或 tsx。

```sh
pnpm run buyer:service --settings /private/queue-settings.json --runtime-dir /private/readonly-buyer-release --action install
pnpm run buyer:service --settings /private/queue-settings.json --runtime-dir /private/readonly-buyer-release --action status
```

Mac 的独立后台服务名为 `ai.agenavo.buyer-queue`。它在用户登录后启动；Mac 需要开机、登录并联网。原供应方后台服务、钱包与旧任务不重新初始化。

模型请求、结构化决定、工具参数、付款意图与状态逐步落盘。恢复时继续原任务编号、原报价与原签名交易；遇到无法确认的付款或损坏状态则暂停。活动或无法核实的旧模型/MCP 进程会阻止第二个买方进程进入。停止期间最多等待指定时间，尚未结束的子进程仍保留锁；不能删锁强行恢复。

出现暂停时先查看私有状态，修正原故障，停止买方后台，再执行 `--action resume --job-id 原编号` 并启动原服务。恢复不清零累计失败次数；达到配置上限后需负责人核对原因，不自动换钱包、加额度或创建替代任务。正常检查失败 `CHECK_FAILED` 是业务终态，继续处理下一项任务，不要求恢复。

## 通知

完成、失败或暂停通知与相应任务状态一起保存。后台输出日志，其他本机程序可订阅：

```sh
pnpm run buyer:queue --settings /private/queue-settings.json --action events --consumer operator --follow true
pnpm run buyer:queue --settings /private/queue-settings.json --action ack --consumer operator --event-id document.example.001:1
```

通知在明确确认前可再次读取；接收者按稳定的 `eventId` 去重。每个消费者有自己的持久游标。订阅和等待不调用模型，也不签交易。现阶段通知通过本机接口及日志交付。

队列最多保存 32 个通知游标。目标 MCP 的每个 `jobId` 与 `consumer` 组合占一个游标，和原 CLI 消费者共用这个上限；达到上限会拒绝新的确认，已有游标继续工作。安装时应按这一限制安排队列规模和订阅者；任务与事件历史不会为释放槽位而自动删除。

缺字段时，提取服务明确返回缺失，检查服务给出正确否决报告；它仍完成了检查工作，因此正常支付检查费用。父任务返回失败，`paidMinor` 保留实际费用，`refundedMinor` 只记录真实退款。链上收据须由独立核验器验证，不能仅凭 MCP 回复宣称已经核实。

本轮实测结果见[验收记录](autonomous-buyer-verification-2026-10-05.md)。网络仍是同一运营者的单主机开发链，使用无赎回价值的测试资产。
