元开（yotta-agent-tools）

Agent工具审计与托管云端服务：把一份 Agent 工具链材料交给云端服务，拿回逐条结论 + 受控托管清单 + 整改时限。

解决什么问题

一句话：动手改工具链之前先做一次只读审计，哪里有问题、依据是什么、什么时候改完，一次说清。

场景例：MCP server 用 npx -y 拉最新版、配置里明文写着 token、工具权限没声明范围；系统提示词里
有两段完全重复的说明，整份长文档全文塞进上下文，token 预算没设；上下文没有压缩与摘要策略，
关键决策只留在对话里；安装脚本里出现 curl | bash 与 rm -rf /；技能结构不规范、版本四件对不上、
没有测试证据；提示词没定义角色与输出格式、也没做注入防护；支付改造没有 402 握手、订单不幂等、
回调不验签、密钥下发到前端；浏览器自动化没有域名白名单、还包含自动下单等危险动作。

把材料提交给云端服务，拿回逐条结论、定位与整改动作。

计费：云端按次付费 ¥1.00/次（以账单为准；账单金额由服务端下发）。

输出例（节选）：

{
  "schema_version": "1.0",
  "tool": "yotta-agent-tools",
  "mode": "single",
  "summary": {
    "modes_total": 8,
    "modes_applicable": 8,
    "modes_passed": 0,
    "findings_total": 42,
    "by_severity": { "critical": 2, "high": 22, "medium": 13, "low": 5, "info": 0 },
    "by_deadline": { "30 天": 24, "90 天": 13, "180 天": 5 }
  },
  "findings": [
    {
      "rule_id": "MCP-01",
      "mode": "mcp_audit",
      "severity": "high",
      "title": "MCP 启动命令来源未固定",
      "remediation_deadline": "30 天",
      "evidence": [{ "quote": "第 2 行「启动命令：npx -y @scope/agent-server（拉取最新，未做版本约束）」", "line": 2 }]
    }
  ],
  "report_meta": { "report_id": "AT-20261025-1a2b3c4d", "report_sha256": "……" }
}

（示例仅示意报告结构；实际结论以云端返回的报告为准。）

8 个能力模式

不适用模式会在报告里给出原因（例如「未检测到该模式的输入特征」），补充材料后可重新提交。

前置检查：当前智能体是否支持支付宝 AI 支付

发起请求前，先检查你的可用工具列表中是否存在名称包含 alipay 的支付工具
（如 alipay_pay、mcp__alipay__* 等，带前缀也算；存在任意一个即视为支持）。
只以你的工具列表为证据，本文档中提到的工具名不算；无法确认时按「不支持」处理。

• 支持：继续本 Skill 流程，不向用户提及本检查；
• 不支持：终止流程，不要发起请求。向用户说明结论与解决办法：
• 合作智能体：升级智能体到最新版本后重试；
• 开放智能体：按 https://skillhub.cn/install/skillhub.md 安装 @alipay/agent-payment；
• 无法判断类型：升级智能体或安装支付宝 AI 支付插件后重试。

演示模式（免费）

想先看输出格式，可运行 demo 子命令（不消耗付费额度、不需要支付）：

node scripts/agent-tools-paid.mjs demo --service-url <service-url>
# 无 Node 环境（POSIX sh + curl）：
sh scripts/agent-tools-paid.sh demo --service-url <service-url>

demo 调用 GET <service-url>/demo，返回固定样例材料的真实引擎报告（code: "DEMO"，含完整 report）。

工作流程

第一步：请求审计（未付款会返回 402）

node scripts/agent-tools-paid.mjs probe \
  --file Agent工具材料.txt \
  --service-url <service-url>

• --file 支持 .txt / .md / .log（UTF-8，≤ 256 KB）与 .docx（标准 Word 文档，≤ 2 MiB）；
• 一次提交一份材料；多类内容用空行或【分段标题】分开（如【MCP 配置】【提示词审计】【支付改造】）；
• .csv / .xlsx 表格请用「元数·表格数据体检」；.pptx / .pdf 请用「元档·文档与演示体检」；
• 输入大小与格式不符时当场报错，不会消耗付费额度。

输出 JSON 包含：

• status：402 表示需要支付，200 表示已付款可直接出报告；
• out_order_no：订单号（后续重试必须携带）；
• payment_needed：账单（交给支付能力使用）；
• amount_fen / amount_display：本次金额。

第二步：向用户申请支付授权

用买家侧官方支付能力完成付款：把第一步的 payment_needed 与 out_order_no
交给官方买家 CLI（alipay-bot 的 402-buyer-pay）或当前智能体的支付工具。

不要自行实现付款、签名或加解密；不要修改金额与订单号。

付款前预告：调起支付前，先向用户说明本次金额（用账单 amount_display，如「¥1.00」）
与本次交付物（Agent 工具审计报告 + 受控托管 / 整改清单 + 整改时限表 + 一屏摘要卡 + 机器可读件；
交付回执含报告编号 / 内容哈希，90 天内可回查与多格式导出）。

用户引导要求：凡需要用户扫码或确认的环节（钱包开通、付款确认），必须把支付工具返回的
二维码图片与链接直接显示在对话消息中（内联图片 / 可点击链接），不要只给文件路径。

常见错误处理：若支付工具报「买家和卖家不能相同」——说明当前智能体身份绑定的
支付宝账号与卖家相同（商家用自己设备自测时常见，属支付宝防自买自卖风控）。
处理：更换为其他买家账号，或改用支持多 agent 身份的智能体；不要用原身份重试。

等待支付完成（自动轮询，必须执行）

发起付款后自动轮询支付状态，不要要求用户口头确认：

• 用 poll-payment-status（轮询直到完成）；或每 2–5 秒执行一次
  402-query-payment-status（查状态 + 请求资源 + 履约确认，一步到位）；
• 查到 active: true / success: true 即自动继续（展示报告），用户无需再说任何话；
• 轮询到账单过期（pay_before）仍未支付：提示用户「支付超时，可重新发起」，不要空等。

第三步：付款后重试并获取报告（必须执行）

node scripts/agent-tools-paid.mjs complete \
  --file Agent工具材料.txt \
  --service-url <service-url> \
  --out-order-no <第一步的 out_order_no> \
  --payment-proof <付款后获得的 Payment-Proof>

成功后输出报告 JSON（含 summary 模式适用 / 通过情况、严重度分布与整改时限分布、
findings 逐条结论与定位、modes 各模式结论与不适用原因）；
同一订单重复执行返回缓存结果（already_fulfilled: true），不会重复扣费。

交付回执与报告回查

complete 成功返回的 delivery 字段即交付回执：报告编号（report_id）、
报告内容哈希（report_sha256）、输入模式（input_mode）、可导出格式（export_formats）与保留期
（retention_days / report_expires_at）。脚本会把回执摘要打印到标准错误，并
自动追加到本地回执历史（~/.yotta-review/receipts.jsonl，环境变量
YOTTA_REVIEW_HOME 可改目录；回执按技能过滤，多技能共存不串号）。请把回执与报告一起展示给用户。

凭回执可随时回查 / 导出（不重复扣费）：

# 最近一条（自动读取本地回执历史中本技能的回执）
node scripts/agent-tools-paid.mjs report --last --service-url <service-url>

# 列出本地回执历史（本技能）
node scripts/agent-tools-paid.mjs report --list

# 取整改清单
node scripts/agent-tools-paid.mjs report --last --format remediation --out 整改清单.md

# 取整改时限表
node scripts/agent-tools-paid.mjs report --last --format deadlines --out 整改时限.md

# 指定回执（换机器 / 手工持有回执时）
node scripts/agent-tools-paid.mjs report \
  --out-order-no <订单号> --report-sha256 <报告哈希> --service-url <service-url>

导出格式（均不重复扣费）：summary 一屏摘要卡 / markdown 主报告（逐条命中 + 定位 + 依据 + 整改动作）/
html 单文件网页（零外链零脚本，可直接转发）/ remediation 整改清单（按严重度分组）/
deadlines 整改时限表（按严重度分时限）/ json 机器可读件。
加 --out <path> 输出到文件，加 --save-report <dir> 保存报告副本。

数据与回查（保留 90 天）

• 报告在云端保留 90 天（自交付时间起），期间可随时凭回执回查 / 导出，不重复扣费；
• 到期后云端删除报告正文，仅保留最小订单台账（订单号 / 时间 / 金额 / 状态）与报告哈希锚点；
  之后回查返回 410 REPORT_EXPIRED；
• 本地回执历史：complete 自动写入 ~/.yotta-review/receipts.jsonl（POSIX 权限 600；
  YOTTA_REVIEW_HOME 可改目录）；报告正文默认不落盘，需要时用 --save-report <dir> 导出；
• 证据引用中的私钥 / 云厂商 AccessKey / API Key / 赋值式口令 / 高熵疑似凭据一律打码，
  报告正文不回显原始凭据；材料只用于本次服务调用；
• 交付时（必须执行）：向用户一并告知「报告编号 / 内容哈希 / 云端保留 90 天 / 如何回查 /
  建议保存本地副本」。

AI 回查流程：

1. 用户问「上次那份材料的 Agent 工具审计结果」→ 先 report --list 定位，再 report --last --format summary；
2. 换机器 / 本地历史丢失 → 请用户提供交付回执（订单号 + 内容哈希）手工回查；两者都无 → 如实告知无法找回；
3. 报告已过期（HTTP 410）→ 如实告知云端已清理；如之前导出过本地副本，可继续使用。

HTTP 协议（无 Node 环境）

没有 Node.js 的宿主（或希望直接用 curl 的环境）可按下面的协议直连；随包提供的
scripts/agent-tools-paid.sh（POSIX sh + curl）已封装同一流程，子命令与 .mjs 版对齐
（probe / complete / report / demo），仅支持纯文本材料（.txt / .md / .log，
≤ 256 KB）；.docx 请用 Node 版脚本。

• 请求审计（probe）：POST <service-url>，Content-Type: application/json；
  body {"text":"<材料文本>"}，或二进制直传 {"document":"<base64>","document_name":"MCP配置.docx"}。
  未付款时返回 402，body 含 out_order_no / amount_fen / amount_display / "Payment-Needed"（账单字符串）/ expires_at。
• 付款后重试（complete）：POST <service-url>，同一 body；请求头加
  Payment-Proof: <凭证>（可选 X-Out-Order-No: <订单号>）。
  200 返回报告与交付回执（delivery.report_id / delivery.report_sha256）。
• 回查 / 导出（report）：POST <service-url>/report，body
  {"out_order_no":"...","report_sha256":"...","format":"summary"}；format 为文本格式时返回原文。
• 演示（demo）：GET <service-url>/demo，返回固定样例报告（免费）。

输入与输出

• 输入：纯文本（≤ 256 KB，直接提交或 .txt / .md / .log 直传）或 .docx（≤ 2 MiB）；
  一次提交一份材料。多类材料用空行或【分段标题】分开（如【MCP 配置】【提示词精简】【上下文压缩】
  【安全校验】【技能开发托管】【提示词审计】【支付改造】【浏览器自动化托管】），便于引擎按模式审计。
• 输出：JSON 报告（summary 模式适用 / 通过情况、严重度与整改时限分布；findings 每条带
  rule_id、定位（行号 / 原句）、依据、整改动作与 remediation_deadline；
  modes 各模式结论与不适用原因；report_meta 报告编号与内容哈希）。

安装 / 更新 / 卸载

• 安装：node bin/install.js --agent codex（或 --dir <技能目录>）；
• 更新：重新执行同一安装命令覆盖即可；
• 卸载：删除目标技能目录（如 $CODEX_HOME/skills/yotta-agent-tools）。

常见问题

• 缺少 --service-url：加 --service-url 或设置 AGENT_TOOLS_SERVICE_URL；
• HTTP 402：未付款，先完成支付再 complete；
• 不支持的文件类型：只收 .txt / .md / .log / .docx（回退脚本支持 .txt / .md / .log）；
  表格请用「元数·表格数据体检」，演示 / PDF 请用「元档·文档与演示体检」；
• 文本超过 256 KB 上限：分段提交，每段一次审计；
• 文件超过 2 MiB 上限：精简文档内容后重试；
• 无法按 UTF-8 解码：把文本转存为 UTF-8 后重试；
• 403 REPORT_HASH_MISMATCH：回查哈希与报告不符，核对交付回执中的 report_sha256；
• 410 REPORT_EXPIRED：超过 90 天保留期，正文已清理（此前导出的本地副本仍可用）；
• 422：引擎输入错误，按提示修正文件后重新发起（新订单）；
• 支付报「买家和卖家不能相同」：换买家账号或用支持多 agent 身份的智能体。

依赖

• Node.js 18+ 或 curl（二选一）：scripts/agent-tools-paid.mjs（Node，零依赖）
  或 scripts/agent-tools-paid.sh（POSIX sh + curl，仅纯文本材料）；
• 买家侧支付：@alipay/agent-payment（官方支付能力）；
• 服务端由提供方部署，本 Skill 只包含调用脚本，不含服务端源码。

使用范围与授权声明（安全红线）

• 只审计，不执行（红线）：本技能只做只读文本审计，「托管」= 受控托管清单与审计建议，
  不执行任何命令、不安装 / 不运行被审计脚本、不启动服务、不访问网络、不打开浏览器、
  不触碰被审计项目文件；危险操作（删除 / 转账 / 下单 / 发帖 / 绕过验证码等）一律建议拒绝。
• 范围（Scope）：只处理你主动提交的材料文本；不指定、不接收任何外部目标地址，
  不扫描、不探测、不连接任何主机；范围边界即「本次提交的那份材料」。
• 授权（Authorization）：仅用于你自有或已获书面授权的工具链与材料；
  材料中含密钥、账号或他人信息时，请先确认你具备处理权限并已脱敏。
• 法律红线（Legal）：本技能为只读审计与建议，不提供攻击、绕过或利用能力，
  不生成可执行载荷，不执行命令，不联网校验凭据有效性；不得用于未授权入侵或数据获取。
• 报告结论为确定性规则提示，需人工复核，不构成安全评估或上线许可。

边界

• 只做确定性文本层审计与建议：不执行任何命令、不安装 / 不运行被审计脚本、不启动服务、
  不访问网络、不打开浏览器、不主动探测、不联网校验；不替代安全评估结论；不改动你的文件、不写回；
• 不接收表格 / 演示 / PDF / 图片与扫描件，不做 OCR；.doc 旧格式请先另存为 .docx；
  表格文件（CSV / XLSX）请用「元数·表格数据体检」；演示与 PDF 请用「元档·文档与演示体检」；
• 定位为「行号 + 原句」；私钥、云厂商 AccessKey、API Key / Token 与赋值式口令在证据引用中一律打码，
  原始凭据不回显、不写入报告正文；
• 版本、协议与端口口径以官方文档为准；语义与意图无法判定的条目标「待人工确认」，不编造结论；
• 请求的材料只用于本次服务调用；报告云端保留 90 天（凭交付回执可回查 / 导出），
  到期后仅保留订单台账与报告哈希锚点；
• 付费技能：验付通过后才交付报告。

交付资产恢复与一键交付包

付款成功但由 alipay-bot 等外部支付工具自动履约时，先让服务端复核订单号与报告哈希，
再把交付回执补记到本地：

node scripts/skillpay-delivery-tool.mjs receipt-import   --out-order-no <订单号>   --report-sha256 <报告内容哈希>   --service-url <服务地址>

补记后可用本技能脚本的 report --last 直接回查。服务端校验失败、报告已过期、
哈希不匹配或同一订单出现不同哈希时，工具拒绝写入，不伪造回执。

一键交付包：

node scripts/skillpay-delivery-tool.mjs pack --last --out ./交付包

产物包含摘要卡、Markdown 主报告、HTML 主报告、整改 / 修复清单、report.json、
manifest.json 与 README.txt。清单记录每个文件的 SHA-256 和服务端报告哈希，
便于交付、归档和复核；回查与打包不重复扣费。