Task402 Agent Evidence Tools

Task402 Agent 证据工具

为 Agent 提供来自 PDF、公开网页、OpenAPI 契约和 Base 链数据的有限证据。连接托管的 20 工具 MCP 服务：https://task402.xyz/mcp；发现工具无需本地服务、API 密钥或钱包。付费调用使用 Base 上的 x402 v2 USDC。连接 MCP 主机不会自动为其提供支付签名器。

连接你的 Agent

对于 Cursor，将 examples/cursor.mcp.json 合并到 .cursor/mcp.json。对于 VS Code，将 examples/vscode.mcp.json 合并到 .vscode/mcp.json。其他 Streamable HTTP 客户端可以使用：

{
  "mcpServers": {
    "task402": { "url": "https://task402.xyz/mcp" }
  }
}

初始化连接并运行 tools/list，以检查可执行的架构。安装 Node.js 24 和本仓库的依赖项后，npm run discover 会通过官方 MCP SDK 执行发现，并仅打印工具名称。它不会调用付费工具或签署支付。

每个托管工具都会提供特定于该工具的输出架构、参数说明和 MCP 安全注释。因此，Agent 可以在批准任何 x402 支付前，根据 tools/list 规划结果形状和重试行为。

工具	2026 年 10 月 12 日实时检查时的费用
generate_pdf	每份 PDF $0.01
web_evidence	每个公开 HTTPS 页面 $0.005
inspect_openapi	每份规范 $0.001
plan_api_request、diff_openapi	每次调用 $0.002
get_chain_balance、get_chain_transaction、get_erc20_balance	每次读取 $0.001
get_pdf_job	包含在生成费用中；需要作业能力
inspect_pdf、get_document_map、search_document、batch_search_document、prepare_document_context、extract_document_fields、read_document、verify_document_citation、compare_pdfs、validate_pdf_text、render_pdf_page_region	付费 PDF 索引后包含；需要文档能力

PDF 索引是单独的 REST 操作 POST /v1/documents（每份 PDF $0.01）；二进制文件上传不是 MCP 工具。生成的 PDF 也只能通过 REST 下载。批准支付前，请阅读 /v1/pricing 和支付质询，了解当前条款。原生文本 PDF 工具不提供 OCR，也不会验证事实真伪。

从 docs/FIRST-PAID-CALL.md 开始，了解质询、签名重试和结果工作流。使用 docs/PUBLISHING.md 发布本仓库和远程 MCP 元数据。

服务架构

本项目通过 REST 和 MCP 共用的服务，将 Markdown 转换为分页 PDF 文件。本地运行器使用 Playwright Chromium 和 SQLite；Cloudflare Worker 适配器使用 Browser Run Quick Actions、D1 和 R2。在线支付流程使用官方 x402 SDK facilitator 客户端，在渲染前验证付款，并且仅在 PDF 文件存储后才结算。

付费操作包括 generate_pdf、ingest_document、web_evidence、OpenAPI 检查/规划/差异比较，以及固定方法的 Base 链读取。索引完成后，还可使用检索、引用、批量搜索、有界上下文准备和显式标签字段匹配功能。网络证据仅限公开的 HTTPS HTML/文本；OpenAPI 工具仅接受调用方提供的 JSON 和本地引用；链工具绝不会签名或提交交易。输入 HTML 不会执行，远程图片及其他外部资源会被省略或阻止；生成的 PDF 会保留超链接，但渲染期间绝不会获取这些链接。

发布元数据、转换指南和可用于各渠道的文案见 docs/MARKETING.md 和 docs/LAUNCH-KIT.md；公开 MCP 目录元数据见 server.json、glama.json 和面向 LobeHub 的 lhm.plugin.json。

详细的 Agent、发现、操作、部署、运维统计和安全指南见 docs/AGENT-GUIDE.md。

使用托管 MCP 服务

无需运行本地进程。将 Streamable HTTP 端点添加到兼容 MCP 的客户端：

{
  "mcpServers": {
    "task402": {
      "type": "http",
      "url": "https://task402.xyz/mcp"
    }
  }
}

无需付款即可发现此服务。付费操作会返回 x402 v2 付款质询；客户端必须检查网络、USDC 资产、收款方、金额、资源和超时时间，取得明确的钱包批准，然后使用签名付款重试同一请求。Task402 不会接收私钥，也绝不会代替调用方签名或提交交易。请从首次付费调用开始，然后参考 examples/agent-flow.ts 了解完整的注入式签名器流程。

包含的内容

能力	费用	接口
从 Markdown 生成分页 PDF	$0.01	REST、MCP
索引一个原生文本 PDF	$0.01	REST
搜索、引用、比较、验证、映射、读取、提取字段、准备上下文和渲染	索引后免费使用	REST、MCP
有限的公共页面证据	$0.005	REST、MCP
检查 OpenAPI、规划请求和比较差异	$0.001–$0.002	REST、MCP
只读 Base 余额、交易和 ERC-20 数据	$0.001	REST、MCP

价格、限额、架构和付款条款均以机器可读格式发布在 /v1/pricing。该服务不提供 OCR、JavaScript 页面渲染、任意 API 执行、交易签名或 PDF 视觉／法律修订标注。

远程 MCP 服务的元数据版本为 0.3.2，见 server.json。在 2026-10-12 的审计中，官方 Registry 提供的版本为 0.2.0；发布新元数据需要域名发布者证明密钥，该密钥有意未存储在此工作区中。在声称该版本已发布之前，请重新检查 Registry 中的实时记录。付费 REST 和 MCP 挑战包含 x402 Bazaar 发现元数据，生产环境使用的 facilitator 为 https://facilitator.openx402.ai。

公开发现页面包括 https://task402.xyz/、/docs#first-paid-call、/llms.txt、/demo、/v1/tools、/openapi.json、/v1/pricing、/.well-known/x402.json、/.well-known/mcp/server-card.json、/.well-known/ai-plugin.json 和 /sitemap.xml。这些页面为 Agent 和目录爬虫提供清晰的入口，无需付款或操作员凭据。发布到 Registry 可提高同步 MCP Registry 的客户端的发现能力；但这不会制造虚假流量，也不保证会收到调用。

公开快速入门指南包含以下专门的工作流：引用验证、比较 PDF 修订版本以及在调用模型前缩减 PDF 上下文。可直接复制粘贴的客户端文件位于 examples/agent-flow.ts、examples/cursor.mcp.json 和 examples/vscode.mcp.json。TypeScript 示例会获取生成和索引操作的未签名挑战，并提供显式重试方法，以便使用另行批准的钱包载荷；它绝不会自动签署或提交付款。

准备好进行一次受控的实时付款时，请按照 docs/TEST-TRANSACTION.md 操作。该流程需要外部钱包签名器，绝不会索要私钥。

对于一次性本地测试钱包，仓库还提供了带防护措施的终端助手：npm run test:live。它会在签名前验证 Base／USDC 实时挑战，需要设置 TASK402_CONFIRM=YES，下载 PDF，并且绝不会打印付款载荷或 capability。设置和清理方法请参阅测试指南的终端部分。

如需精确复现 MCP Agent，请使用 npm run test:agent；它会执行发现、接收结构化 x402 挑战、通过官方 EVM 客户端签名、使用 _meta["x402/payment"] 重试、通过 get_pdf_job 检查任务，并下载结果。

本地开发

使用 Node.js 24 或更高版本（已通过 Node 24.13 验证；本地持久状态使用 node:sqlite）。在此目录中：

npm ci
Copy-Item .dev.vars.example .dev.vars
npm run setup:browser
npm run dev

本地服务仅绑定到 127.0.0.1:8787，并且只接受匹配的环回/localhost Host authority（以及实时模式下配置的公共 authority）。本地网页证据适配器会在获取内容前解析每个主机名，并拒绝私有、环回、链路本地和保留的 DNS 目标；托管的 Worker 依赖其平台的出站边界以及相同的 URL 检查。示例 .dev.vars 启用了明确的免付款开发绕过，该绕过仅存在于 src/local.ts；src/worker.ts 会无条件拒绝该绕过。如果 .dev.vars 不存在，服务启动时将保持未配置付款状态，并在付费生成时默认拒绝。本地任务和工件会持久保存在 .data/ 下，并被 Git 忽略。

如果 Playwright 在你的机器上找不到其固定版本的 Chromium 下载文件，请在启动本地进程前将其指向已安装的 Chromium 可执行文件：

$env:BROWSER_EXECUTABLE_PATH = "C:\path\to\chrome.exe"
npm run dev

生成并下载示例 PDF：

$body = @{ title = "Quarterly Report"; markdown = "# Summary`n`n| Metric | Value |`n| --- | ---: |`n| Revenue | 42 |" } | ConvertTo-Json
$job = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8787/v1/pdf `
  -Headers @{ "Idempotency-Key" = "report-2026-q3-0001" } `
  -ContentType "application/json" -Body $body
$job | Format-List
Invoke-WebRequest -Uri $job.downloadUrl `
  -Headers @{ Authorization = "Bearer $($job.capability)" } `
  -OutFile .\report.pdf

该凭据是一个持有者密钥。请将其保存在内存中，不要记录日志，并且仅将其发送到返回的状态/下载 URL。访问状态和下载内容需要 Authorization: Bearer <capability>（或 X-Job-Capability）；仅凭任务 ID 或幂等键无法获得访问授权。

API 和限制

路由	用途
GET /v1/pricing	机器可读的操作、价格、支付模式以及大小／TTL 限制
GET /.well-known/x402	在知名路径提供相同的发现文档
GET / 和 GET /docs	公开的服务概览和 Agent 快速入门
GET /llms.txt 和 GET /sitemap.xml	精简的 Agent 可读元数据和爬虫发现信息
POST /v1/pdf	生成 PDF；需要 Idempotency-Key；实时模式使用 x402 v2 PAYMENT-SIGNATURE
GET /v1/jobs/{jobId}	读取已授权的任务状态
GET /v1/jobs/{jobId}/download	下载已授权且已完成的 PDF
GET /v1/admin/stats	受密码保护的工具统计汇总；可选参数 ?hours=24
GET /admin	便于移动设备使用的密码表单，用于查看受保护的统计端点
POST /mcp	MCP Streamable HTTP 端点，提供 PDF、Web、OpenAPI 和 Base 只读工具
POST /v1/documents	付费的原始 PDF 索引，用于确定性的原生文本操作
GET /v1/documents/{documentId} 和 /map	检查文档元数据或读取其页面映射
POST /v1/documents/{documentId}/search、/batch-search、/context、/fields、/read、/citation、/validate	搜索、构建带引用的上下文、读取选定页面、验证文本引文，或校验给定预期
POST /v1/documents/compare	按页面和规范化原生文本比较两个分别授权的 PDF
GET /v1/documents/{documentId}/pages/{page}/render	将指定范围内的页面裁剪区域渲染为 PNG
POST /v1/web/evidence	付费提取公开 HTTPS 页面内容，提供受限文本、链接、源哈希和提示词注入警告
POST /v1/openapi/inspect	付费检查 OpenAPI 操作、参数、请求正文、安全设置和本地引用
POST /v1/openapi/request-plan 和 /v1/openapi/diff	付费的安全请求规划和确定性 API 契约比较；不会执行任何请求
POST /v1/chain/balance、/v1/chain/transaction、/v1/chain/erc20-balance	付费的只读 Base RPC 工具；不签名或转移资金

默认限制为：请求正文 256 KiB、规范化 Markdown 240 KiB、标题 160 个字符、Markdown 20,000 行、PDF 输出 20 MiB、制品有效期 24 小时，以及渲染截止时间 90 秒。PDF 使用 A4 版式，重复显示表格标题，尽可能保持行不跨页，并添加页码。Cloudflare 中每小时运行一次清理；本地进程在启动时及每小时运行一次。清理批次设有上限；过期的访问凭据会立即失效，但物理删除可能需要额外批次。结算状态不确定时，制品会保留，以便运营人员核对。

本地 PDF 检查与检索

已部署的 Worker 通过隔离的 Cloudflare Container 解析器提供确定性的 PDF 文档操作。Worker 负责管理访问凭据、D1 元数据、R2 源文件／索引对象、验证和清理；Container 在禁用出站 Internet 的情况下执行原生 PDF.js 提取和受限页面渲染。本地开发仍通过 Node.js 解析器直接使用相同的操作。

上传原始 PDF 时，使用调用方生成的幂等键和单独的高熵恢复密钥（恢复密钥用于将该键限定为仅供调用方使用）。请将返回的访问凭据和恢复密钥保存在调用方的密钥存储中；服务器不会返回恢复密钥。仅在响应丢失后恢复同一上传时，才重用这两个密钥。仅凭幂等键无法泄露现有文档的访问凭据。

$recovery = [Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(32)).ToLowerInvariant()
$doc = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8787/v1/documents `
  -Headers @{ "Idempotency-Key" = "research-pdf-2026-0001"; "X-Document-Recovery-Key" = $recovery; "X-File-Name" = "research.pdf" } `
  -ContentType "application/pdf" -InFile .\research.pdf
$headers = @{ Authorization = "Bearer $($doc.capability)" }
Invoke-RestMethod -Uri $doc.inspectUrl -Headers $headers
Invoke-RestMethod -Method Post -Uri "$($doc.inspectUrl)/search" -Headers $headers `
  -ContentType "application/json" -Body '{"query":"revenue","limit":5}'
Invoke-RestMethod -Method Post -Uri "$($doc.inspectUrl)/read" -Headers $headers `
  -ContentType "application/json" -Body '{"pages":[1,2]}'

返回的能力令牌属于持有者秘密。请妥善保密，并且只在返回的 URL 的 Authorization 标头中发送。二进制上传最多接受 20 MiB 和 100 页。解析过程会构建有大小限制的本地索引，其中包含元数据、页标签和尺寸、书签、带归一化边界框的原生文本块、表单字段名称／类型／值、批注数量，以及嵌入附件的文件名／大小。索引上限为 8 MiB 和 50,000 个文本块。GET .../map?page=1 会返回该页最多 500 个带位置信息的文本块；默认映射会返回精简的页面摘要。源 PDF 字节和提取出的索引会持久存储在 .data/document-objects/ 和 .data/documents.sqlite 中，并在到期时删除；默认保留时间为 24 小时（DOCUMENT_TTL_SECONDS 最多可延长至七天）。

配置已部署的解析器 Container 后，MCP 端点会添加 inspect_pdf、get_document_map、search_document、batch_search_document、prepare_document_context、extract_document_fields、read_document、verify_document_citation、compare_pdfs、validate_pdf_text 和 render_pdf_page_region。MCP 不会上传二进制内容；请先通过 REST 上传，然后将返回的文档 ID 和能力令牌传给工具。

搜索会在空白规范化后执行不区分大小写的精确匹配。读取上限为 10 页和 32,000 个输出字符。引文检查只能确认归一化文本是否出现在指定页面，并返回附近的文本块及其边界框；它不能证明文本属实，也不能确定视觉阅读顺序。比较功能会报告页面级别的归一化文本变化，不会检查图像、视觉、元数据或签名差异。验证仅检查解析器能否读取、可选的页数以及必需文本。页面裁剪使用归一化页面比例，限制为 400 万栅格像素和 4 MiB PNG 输出。

不提供 OCR、表格结构提取／查询、表单填写、附件下载、PDF/A 一致性测试或加密签名验证。原生文本稀疏时会发出警告；不会为扫描页面虚构文本。PDF 链接会作为文本保留，绝不会被访问。PDF 签名标记仅作为元数据提供；不会检查其可信度或有效性。

原生 PDF 解析和渲染会在隔离的解析器 Container 中运行。Worker 一次只接受一个解析器任务，强制执行 60 秒的启动／处理时限，并在每项任务后销毁 Container，以重置进程和文件系统状态。并发上传或渲染会收到 503，应稍后使用相同的恢复／幂等键重试。上传、页面、文本、索引、输出和实例内存限制也同样适用；Container 无法访问外部互联网，也不会接收任何付款或能力令牌秘密。OCR、视觉语义比较、PDF/A 一致性和加密签名验证仍不受支持，验证工具会明确报告这一点。

幂等键在实时模式下限定于已验证的付款方，并与规范化输入和付款负载绑定。若使用该键提交不同内容或付款，会返回 409；重复的精确付款授权会根据 EVM 网络／资产／付款方／授权 nonce 被拒绝。付款重放墓碑至少会保留 30 天，期限从产物和授权均到期后开始计算。同一已完成请求可在作业有效期内恢复其原始能力令牌，而无需再次渲染或结算。

REST 客户端会在 402 响应中收到 x402 v2 条款以及标准的 PAYMENT-REQUIRED 标头。MCP 客户端会收到相同的 PaymentRequired 对象，作为 isError: true 的工具结果，并通过 params._meta["x402/payment"] 发送付款；已结算的工具结果包含 _meta["x402/payment-response"]。

使用受保护钱包的 MCP 客户端

examples/mcp-client.ts 演示了官方 MCP SDK 的 Streamable HTTP 客户端以及 x402 MCP 传输字段。它从调用方接收一个 ApprovedWallet 适配器，不包含私钥字段、环境密钥或签名实现。请使用硬件钱包、HSM、KMS 或单独隔离的托管钱包服务实现该适配器；签名者在签名前应强制校验预期网络、USDC 资产、接收方、金额上限和 nonce 策略。请勿在 MCP 客户端或代码库中添加长期私钥。

该示例先发起未付款调用以获取质询，再向注入的签名者请求载荷，随后使用 _meta["x402/payment"] 重试，最后返回用于经过身份验证的下载的作业能力。这只是一个最简成功流程示例：生产环境客户端应安全地持久化幂等键和精确签名后的支付载荷，以便重试同一请求；结算结果不确定时，还应保留返回的恢复详情。本地开发绕过机制不会创建或结算链上支付；如需进行端到端 x402 转账，请使用配置妥当的测试钱包和测试网 facilitator。

Cloudflare 部署

Worker 入口点是 src/worker.ts。仓库中已提交的 wrangler.toml 包含生产环境的 D1、R2、Browser Run 和解析器 Durable Object/Container 绑定。部署到其他账户时，请替换这些资源标识符并创建相应资源。构建解析器镜像需要正在运行的 Docker 引擎，且 Docker CLI 必须位于 PATH 中。使用你的 Cloudflare 账户创建资源：

npx wrangler login
npx wrangler d1 create x402-docs-mvp
npx wrangler r2 bucket create x402-docs-mvp

将 Wrangler 输出的 D1 database_id 复制到 wrangler.toml，然后应用仓库中已提交的架构：

npx wrangler d1 migrations apply x402-docs-mvp --remote

统计端点使用迁移文件 0002_tool_stats.sql 中的 tool_stats_daily 表。开始处理流量前，请将其密码设为 Worker 密钥：

npx wrangler secret put STATS_PASSWORD
npx wrangler secret put DOCUMENT_CONTAINER_TOKEN

为账户启用 Browser Run，并在 wrangler.toml 中保留 [browser] 绑定。本项目调用文档所述的 BROWSER.quickAction("pdf", ...) API。Browser Run 面向 Workers Paid 账户开放，但 Paid 计划并不保证费用上限为 5 美元：Browser Run、D1、R2 和 Worker 的使用量都可能产生按量计费的费用。部署前请查看 Cloudflare 当前的计费与定价信息，并配置账户预算和提醒。

在 Worker 端预览时，Browser Run Quick Actions 需要使用 npx wrangler dev --remote（本地 wrangler dev 不支持 quickAction）。常规的 npm run dev 命令仍完全在本地运行，并使用 Playwright Chromium。

在控制面板或 Wrangler 变量中设置非机密的 Worker 变量：

PAYMENTS_MODE=live
PUBLIC_BASE_URL=https://task402.xyz
PRICE_USD=0.01
PRICE_DOCUMENT_USD=0.01
PRICE_WEB_EVIDENCE_USD=0.005
PRICE_OPENAPI_USD=0.001
PRICE_CHAIN_USD=0.001
X402_NETWORK=eip155:8453
X402_ASSET=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
X402_PAY_TO=0xAEA6fDF13ca10aD6B906884ffAcBb58a0e9E144A
X402_FACILITATOR_URL=https://facilitator.openx402.ai
MCP_ALLOWED_ORIGINS=https://<your-approved-mcp-client-origin>

Worker 部署必须设置 STATS_PASSWORD，且其长度必须为 20–256 个字符。请使用唯一的高熵随机密钥。它不是支付凭证，应与钱包和 facilitator 密钥分开保存。DOCUMENT_CONTAINER_TOKEN 是独立的内部密钥，仅供 Worker 与解析器 Container 之间使用。受保护的运维路由是 GET /v1/admin/stats；如需通过手机访问，请打开移动页面 /admin。参见 docs/AGENT-GUIDE.md。

已部署的配置使用 Base 主网 USDC（eip155:8453）和 https://facilitator.openx402.ai。其公开的受支持能力响应声明支持 Base 主网的精确 EVM 支付和发现扩展；当客户端回传支付扩展时，该扩展可启用 Bazaar 目录编目。请将 facilitator 视为支付依赖项：更改生产流量前，请检查其可用性、条款、支持的网络、发现行为和结算行为。服务会将 PRICE_USD 转换为 6 位小数精度的 USDC 单位。

请将能力 HMAC 密钥，以及 facilitator 要求时使用的 bearer token，设为 Worker 密钥。生成至少 32 个字符的随机密钥，不要将其提交到仓库或粘贴到 TOML 文件中：

npx wrangler secret put CAPABILITY_SECRET
npx wrangler secret put X402_FACILITATOR_BEARER_TOKEN

对于不要求身份验证的 facilitator，facilitator token 为可选项。运行本地检查，然后在决定部署前检查部署包：

npm ci
npm run typecheck
npm test
npm run deploy:dry-run
# npx wrangler deploy   # explicit operator action after reviewing account config and costs

此仓库不包含任何钱包凭证或 facilitator 密钥。仓库中已提交的 Wrangler 配置包含本项目所需的部署资源标识符；部署到其他账户时请替换这些标识符。Worker 需要有效的支付配置，若缺少配置则会拒绝处理请求；它没有开发绕过机制。将 Worker 的 PUBLIC_BASE_URL 设置为精确可信的 HTTPS 源，不得包含路径、凭证、查询参数或片段，这样 MCP 结果才能包含绝对状态/下载 URL，同时不依赖调用方可控的 Host 标头。facilitator URL 可以包含路径，但必须使用 HTTPS，且不得包含 URL 凭证、查询参数或片段。

结算恢复

如果结算超时，或 facilitator 返回待处理／结果不明确的状态，任务将变为 settlement_unknown。响应中会包含任务 ID 和 capability，以便持续查看其状态。服务会保留已渲染的 PDF，且不会使用相同授权自动重试结算。采取运维操作前，请检查 facilitator 的交易状态和目标网络。不要重新提交相同授权：即使响应丢失，超时也可能意味着链上交易已被接受。此 MVP 不包含对账／管理端点；运维人员必须与 facilitator／网络进行对账，并通过经过审计的运维流程记录结果。

检查

npm test 涵盖输入限制、HTML／脚本／URL 清理、支付幂等性和重放处理、facilitator 返回的不确定和确定结果、真实 PDF 解析、由 capability 控制的文档恢复、地图／搜索／读取／引用／比较／验证、有界裁剪渲染、过期清理，以及官方 MCP SDK 的初始化／列表／工具调用。还使用本地 Chromium，针对短表格和长表格／长令牌测试样例，对 PDF 生成和视觉分页进行了测试。这些测试不会提交真实的区块链支付，也不会验证特定账户的 Cloudflare 绑定。

分发就绪情况

已检入的目录元数据位于 server.json、glama.json 和 lhm.plugin.json 中；发现情况证据和发布清单见 docs/DISTRIBUTION-AUDIT.md。在宣称已可通过目录获取之前，请根据当前的 /v1/pricing 合约，核实 MCP Registry 的实时记录、facilitator Bazaar 资源以及任何第三方列表 URL。这些文件为提交做好了准备；外部目录仍需通过各自的发布者或仓库工作流完成提交。

Agent 应优先使用 /v1/pricing 获取当前价格，使用 /openapi.json 获取 REST 架构，并使用 MCP tools/list 获取可执行的输入架构。公开的 /docs、/llms.txt 和 /sitemap.xml 页面有意不包含凭据，以便爬虫在任何支付之前了解该服务。