文档转换 API

在 PDF/Office 文档与结构化 JSON 之间进行双向转换。NEXUS 候选 #6 —— 手动构建，非 FORGE 生成，遵循与候选 #3（agent-verification-api）和候选 #4（url-metadata-api）相同的手动 Cloud Run 资产模式。

• POST /extract-pdf-to-json —— 文本、表格（按页）、页数、元数据。$0.02/次调用。

• POST /extract-docx-to-json —— 段落（含标题级别/样式）、表格、元数据。$0.01/次调用。

• POST /extract-xlsx-to-json —— 按工作表输出单元格网格，行列数设上限。$0.01/次调用。

• POST /generate-pdf-from-json —— 结构化块（标题/段落/表格）→ PDF 字节。$0.02/次调用。

• POST /generate-docx-from-json —— 结构化块 → .docx 字节。$0.01/次调用。

• /mcp 处的 MCP 工具镜像了全部 5 个端点 —— 当前免费，参见"已知限制"。

• GET /health、GET /.well-known/agent-card.json、GET /openapi.json（含 x-payment-info）。

全部 5 个端点直接在请求体中接收 base64 编码的文件字节 —— 绝不通过 URL 获取。 这是一个刻意的范围边界：它从根本上消除了该资产的 SSRF 风险面（不同于 url-metadata-api/agent-verification-api，两者都会获取调用方提供的 URL，因此需要 SSRF 防护）。

为什么选这些库，为什么没有外部数据源

纯开源、成熟、无 LLM 调用、运行时零外部网络调用（完全本地计算）： pdfplumber（PDF 提取，封装 pdfminer.six）、python-docx（Word）、openpyxl（Excel）、 reportlab（PDF 生成）。该资产中刻意不引入任何具名第三方数据源 —— 以避免 BuyWhere 式的幻觉风险（skills/asset-lifecycle）：没有任何外部因素可能出错， 整个产品就是"对调用方发送的字节运行一个知名库"。不使用 numpy/scipy （避免已知的 Cloud Run Buildpacks 失败 —— scipy 源码构建需要 Fortran 编译器，参见 skills/infra-deploy-ops；这些库本来也不需要它们）。

Related MCP server: docxtpl MCP Server

为什么定价 $0.01-$0.02（对比 agent-verification-api 的 $0.35、url-metadata-api 的 $0.01）

这里没有付费第三方 API 成本（不同于 live-entity-verification/agent-verification-api 中的 WHOIS）—— 纯粹是 CPU/内存成本，因此与 url-metadata-api 单次获取的 $0.01 处于同一低档位， 远低于 agent-verification-api 的 $0.35。PDF 操作（extract-pdf-to-json、 generate-pdf-from-json）定价比 docx/xlsx（$0.01）高一档（$0.02）：pdfplumber/reportlab 每次调用做的工作量明显更多（页面级布局解析 / PDF 渲染），而 python-docx/openpyxl 只是对 zip 归档做直接的 XML 解析。该资产预计是 3 个手动候选中可预测性最高的， 而非收入最高的 —— 文档转换是常见、低方差的智能体需求，不是差异化/稀缺能力 —— 因此定价偏向于一致的低摩擦使用，而非单次调用利润率。

该资产独有的两个风险（其他 3 个手动资产没有）

1. CPU 密集型，而非 I/O 密集型。 每个解析/生成调用都是同步的（4 个库中均无异步 API）， 不同于其他 3 个资产通过 httpx.AsyncClient 实现 I/O 密集型。每个处理器通过 asyncio.to_thread() 在 asyncio.wait_for() 超时（25 秒）内卸载实际工作， 这样单个调用方的慢速解析永远不会阻塞整个事件循环 / 所有并发请求。 已知残余限制：asyncio.wait_for() 会取消等待中的任务，但无法终止底层 OS 线程 —— Python 没有强制终止运行中线程的 API。一个病态输入若导致 pdfminer/openpyxl 内部挂起，即使调用方已收到 504，该工作线程仍会无限期被占用。这是缓解而非解决： 有界信号量（NEXUS_MAX_CONCURRENT_JOBS，默认 4）限制了此类"泄漏"线程可并发累积的数量 —— 新请求会得到干净的 503 而非无界线程增长，但已泄漏的线程永远不会被回收。 完整修复需要将 CPU 密集型工作放到独立的、可终止的进程中（ProcessPoolExecutor + 硬终止） 而非线程中；对于 7 天试用期候选来说这样做不成比例，故未实施。

2. 解压炸弹 / 资源耗尽。 .docx/.xlsx 是 zip 归档 —— 一个压缩体积小但解压后体积巨大的 构造文件（zip 炸弹）是真实的 DoS 向量，与其他 3 个资产面临的任何问题都不同。 _check_zip_bomb_safe() 在将字节交给 python-docx/openpyxl 之前检查 zip 中央目录 （zipfile.infolist()，开销低，不解压条目数据）：若总解压大小超过 50MB， 或任何单个条目的压缩比超过 100 倍，则拒绝。每次上传在解析前也限制为 8MB 原始/解码字节（PDF 也包含在内，尽管它们不是基于 zip 的 —— 无论何种格式都限制最坏情况输入大小）。

已知限制（刻意不修复 —— CLAUDE.md §3，没有证据表明需要就不设门槛）

• MCP 工具调用不收费。 与兄弟手动资产相同的进程内调用模式（原因也相同）： MCP 工具直接调用共享转换函数，而非通过 HTTP 重新进入 ASGI 应用。

• 无按调用方限流。 对于 7 天一次性测量来说没问题；如果存活下来再添加。

• 生成的文档不验证往返保真度，仅做本地冒烟测试 —— reportlab 的表格/段落渲染和 python-docx 的标题级别映射都是成熟、 广泛使用的代码路径，此处未针对每种可能的 Office/PDF 阅读器重新验证。

• 线程泄漏残余限制参见上文"CPU 密集型"风险。

NEXUS_X402_FREE_MODE

与 similarity-search-api/live-entity-verification（skills/x402-payments）相同的门控模式 —— 默认 false（从第一天起收费，无免费试用窗口；引擎没有 live-entity-verification 基于 WHOIS 的引擎那样的外部验证依赖，因此不存在等效的"已在生产中验证"的论据 来跳过直接收费 —— 无论如何都收费，依据会话简报中"温和且稳定"的收入框架， 而非特定先例）。本地测试时设为 true，无需真实的 facilitator 往返。

部署目标：Cloud Run，而非 Railway

与候选 #3/#4 相同的流水线 —— 参见 skills/infra-deploy-ops。内存提升至 1Gi （对比共享 scripts/deploy_cloud_run.sh 中硬编码的 512Mi 默认值）—— 这是 3 个手动候选中内存占用最高的（PDF/Office 解析库，pypdfium2/Pillow 通过 pdfplumber 传递引入）。直接通过 gcloud run deploy 部署 （不走共享脚本，避免为单个候选的内存提升而修改共享基础设施工具）：

# 1. First deploy -- PUBLIC_DOMAIN not known yet, every real request 421s until step 2.
gcloud run deploy document-conversion-api \
  --source manual_assets/document-conversion-api \
  --project nexus-505016 --region us-central1 \
  --allow-unauthenticated --min-instances=0 --max-instances=3 --memory=1Gi --quiet \
  --env-vars-file manual_assets/document-conversion-api/env-vars.deploy.yaml

# 2. Grab the printed *.run.app URL, then:
gcloud run services update document-conversion-api --region us-central1 --project nexus-505016 \
    --update-env-vars PUBLIC_DOMAIN=<the-real-domain>

测量（候选 #6，7 天窗口）

自首次真实部署起 7 天窗口。数据来源：traffic_events/revenue_events/mcp_call_events 表（asset_name = 'document-conversion-api'），而非 Cloud Run 日志。第 7 天： 若零真实流量（过滤爬虫），暂停/删除 Cloud Run 服务，与候选 #3/#4 相同的决策规则。