# Agenavo 文档目标买方工具包

适用于外部 Mac/Linux：Node 24、Python 3.12 的独立虚拟环境、负责人自己安装并登录的 Codex CLI。买方接受文档字段提取和检查目标，模型返回受约束的决定，本机协调程序通过五个固定 Python 工具支付两项服务。网络为受邀测试链，EVM chain ID 991337，资产没有赎回价值；没有任意任务拆解或通用 AI 正确性保证。

## 验证并安装

从 Agenavo 开发者页取得 `agenavo-buyer-kit.tar.gz` 和 `agenavo-buyer-kit.sha256`。使用独立可信渠道核对完整 SHA-256；摘要只验证下载文件一致性，不是发布者数字签名。

```sh
# Linux: sha256sum -c agenavo-buyer-kit.sha256
shasum -a 256 -c agenavo-buyer-kit.sha256
tar -tzf agenavo-buyer-kit.tar.gz
# 清单只应包含本文所述公开文件；在新的空目录解压，不要覆盖旧目录。
mkdir buyer-kit-download
tar -xzf agenavo-buyer-kit.tar.gz -C buyer-kit-download
```

归档含安装器、包装入口、清单、两个独立 Node 单文件子发布、Python 固定工具的 15 个公开文件及清单（含独立 bill_tasks.py），以及单独的目标 MCP 服务。它没有钱包、邀请 token、模型缓存、任务状态或运行日志。

在仓库、任意 Git 项目和工具包代码目录以外准备专用私有目录，权限 `0700`。Mac 请使用主目录的 `.local/share` 等位置，后台运行不能访问 Desktop/Documents/Downloads。安装器拒绝符号链接、Git 祖先、源码目录、宽松权限和已存在的安装目录或配置。

先按 `python/README.md` 的邀请流程准备自己的买方配置和固定工具策略。安装器不会生成钱包、申请邀请、登录模型、建立模型池或提高额度。

```sh
mkdir -p "$HOME/.local/share/agenavo-buyer"
chmod 700 "$HOME/.local/share/agenavo-buyer"
python3.12 -m venv "$HOME/.local/share/agenavo-buyer/venv"
"$HOME/.local/share/agenavo-buyer/venv/bin/python" -m pip install -r buyer-kit-download/python/requirements-mcp.txt
```

负责人保存 mode-0600 `owner-input.json`，所有路径是自己机器的绝对路径；填写已有模型池和原累计上限。下列占位路径须替换，数字须由负责人明确批准。

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

```sh
node buyer-kit-download/install.mjs \
  --runtime-dir "$HOME/.local/share/agenavo-buyer/kit-v1" \
  --config "$HOME/.local/share/agenavo-buyer/queue-settings.json" \
  --owner-input "$HOME/.local/share/agenavo-buyer/owner-input.json" \
  --archive /absolute/download/agenavo-buyer-kit.tar.gz \
  --sha256 '<已核对的64位完整摘要>'
```

`--archive` 和 `--sha256` 同时提供时，安装器先在内存中核对 ustar 头、条目类型、路径、权限、重复项、完整清单和每个文件摘要，再建立新的只读代码目录。省略两项时检查已经解压的目录。目标的父目录及配置的父目录必须已经存在且为 mode-0700；代码安装为文件 `0400`、目录 `0500`。已有 runtime/config 一律拒绝覆盖。失败可能保留部分新代码目录，负责人应查看失败原因；原有配置、缓存、计数、任务与付款日志不会被删除或重置。新目录不代表新的模型额度。已有计数大于提供上限时拒绝安装；沿用现有模型池的例子是新 queue 目录与旧 modelStateDirectory 分开设置，原 calls.json 和 cached request 文件留在旧池，maxModelCalls 沿用原授权的累计上限。

安装失败的 JSON 保留 `code: PRESERVE_EXISTING_RUNTIME_AND_STATE`，`reason` 给出已识别的摘要、权限、路径或额度错误代码；未识别错误为 `INSTALLATION_CHECK_FAILED`，不输出路径、配置内容或原异常文本。

## 使用 CLI 和机器接口

```sh
node /absolute/private/kit-v1/agenavo.mjs --help
node /absolute/private/kit-v1/agenavo.mjs --settings /absolute/private/queue-settings.json --action doctor
node /absolute/private/kit-v1/agenavo.mjs --settings /absolute/private/queue-settings.json --action status
```

doctor 核对 Node 24、不可写的完整代码清单、私有配置、固定 Python 依赖和 Codex 可执行程序；只调用可执行程序的 `--version`，不会检查模型登录、调用模型或签字。输出原模型计数与配置上限，缺少计数时明确显示 `null`。实际登录是否可用由负责人在自己的 Codex CLI 中确认。

保存 mode-0600 job 文件：

```json
{"version":1,"jobId":"invoice.001","objective":"提取 vendor、amount、currency，再购买证据检查。","document":"vendor: Example\namount: 18.50\ncurrency: CNY\n","fields":["vendor","amount","currency"]}
```

```sh
node /absolute/private/kit-v1/agenavo.mjs --settings /absolute/private/queue-settings.json --action enqueue --job-file /absolute/private/job.json
node /absolute/private/kit-v1/agenavo.mjs --settings /absolute/private/queue-settings.json --action worker
node /absolute/private/kit-v1/agenavo.mjs --settings /absolute/private/queue-settings.json --action events --consumer operator --follow true
node /absolute/private/kit-v1/agenavo.mjs --settings /absolute/private/queue-settings.json --action ack --consumer operator --event-id invoice.001:1
```

每次启动接收一个有界 JSON 请求，标准输入结束（EOF）后输出一条 JSON 回复。重复请求时重新启动同一入口；任务状态需由 `status` 和 `data` 判断：

```sh
node /absolute/private/kit-v1/agenavo.mjs --settings /absolute/private/queue-settings.json --action goal-api
```

每次从下列示例选择一个完整对象提交：

```json
{"version":1,"tool":"submit_goal","arguments":{"job":{"version":1,"jobId":"invoice.001","objective":"提取并检查金额","document":"amount: 18.50\n","fields":["amount"]}}}
{"version":1,"tool":"goal_status","arguments":{"jobId":"invoice.001"}}
{"version":1,"tool":"goal_result","arguments":{"jobId":"invoice.001"}}
{"version":1,"tool":"goal_events","arguments":{"jobId":"invoice.001","consumer":"operator"}}
{"version":1,"tool":"ack_goal_event","arguments":{"jobId":"invoice.001","consumer":"operator","eventId":"invoice.001:1"}}
```

提交只进入持久队列；运行 worker 才调用模型或推进付款。重复原 jobId 与原输入复用原任务，改变输入拒绝。字段最多 12 项，原文 UTF-8 最多 16 KiB；较大的检查输入会在询价付款前暂停。结果只返回已核验交付与公开收据引用；协议收据元数据不等于独立链上审计。`CHECK_FAILED` 是已支付检查服务的正常否决结果，不能假报退款或父目标成功。

通知保留最多 32 个游标，每个 jobId/consumer 组合占一个，与原 CLI 消费者共用上限。到达上限会拒绝新的确认，已有游标继续使用；任务与事件不自动删除。按这个上限设置队列及订阅者规模。

## 目标 MCP 与可选 Mac 后台

在 MCP 主机的 owner 配置中设置：

```json
{
  "command": "/absolute/private/venv/bin/python",
  "args": ["-B", "/absolute/private/kit-v1/goal-mcp/buyer_mcp_server.py", "--node-executable", "/absolute/node24/bin/node", "--buyer-executable", "/absolute/private/kit-v1/agenavo.mjs", "--settings", "/absolute/private/queue-settings.json"]
}
```

`tools/list` 可发现文档目标的提交、状态、结果、通知和确认工具。服务只使用本机 stdio，启动路径和预算由负责人固定，模型的工具参数没有文件路径、钱包或运行额度。它与 `python/mcp_server.py` 的五个付款固定工具分开。

Mac 可明确安装后台买方：

```sh
node /absolute/private/kit-v1/agenavo.mjs --settings /absolute/private/queue-settings.json --action service --service-action install
node /absolute/private/kit-v1/agenavo.mjs --settings /absolute/private/queue-settings.json --action service --service-action status
node /absolute/private/kit-v1/agenavo.mjs --settings /absolute/private/queue-settings.json --action service --service-action stop
```

后台名为 `ai.agenavo.buyer-queue`，仅在 Mac 用户登录、开机并联网时运行；现有不同配置的服务会被拒绝。Linux 使用前台 worker 或负责人自己的服务管理器。恢复沿用原配置、jobId、requestId、输入哈希、模型缓存、交易日志和通知游标，不能删锁或换目录绕过累计限额。

## 中文账单目标（bill-v1）

新版支持单独的 `bill-v1` 目标：先购买 `bill-extract-v1`，再购买 `bill-check-v1`。字段固定为 `merchant`、`amount`、`currency`，不传 `fields`；账单原文作为数据。候选字段保留 Unicode 码点区间证据，金额和币种按公开规则核对；缺失、重复或歧义字段需要人工查看，不能把规则核验扩张为任意账单真实性证明。

```json
{"version":1,"jobId":"bill.example.001","workflow":"bill-v1","objective":"提取商户、金额和币种，并购买独立检查。","document":"商家：示例商店\n实付：18.50 元\n币种：人民币\n"}
```

仍使用原 `enqueue` 或 MCP `submit_goal`，但负责人必须先取得单独账单服务的邀请和批准配置，入口为 `https://agenavo.xyz/api/bills`。公开代码中存在该 workflow 不代表服务已经部署、邀请已批准、模型或支付额度已提高。旧 `/api/collaboration` 配置只批准文档服务，不能自动购买账单服务。`/api/bills/v1/profile` 上线后才可发现该独立服务的网络配置。

账单新一轮的账户、API、预算和模型上限须另由负责人批准。安装器继续沿用原指定模型池与计数；历史已安装的 15 文件 Python 工具目录及原清单无需改写。新版下载档案为 16 文件 Python 目录，安装在新的只读 code 目录并使用新的明确队列配置。已有队列的策略哈希绑定原工具清单和路径，不能直接换配置使它变为新队列；已有任务继续使用原 runtime/config，同 jobId 的原请求、hash、cache 和 journal 不重新初始化。
