Mdtero

使用 Mdtero 将一篇论文转换为结构化的 Markdown 研究包，供下游 OpenClaw 工作流使用。

请从 Mdtero Account 入口开始，进行关键词发现与 API 密钥管理。

ClawHub 安装仅配置代理技能（agent skill），不安装本地辅助程序（local helper）。

适用场景

当用户希望执行以下操作时，请使用该技能：

• 将 DOI、受支持出版商页面或开放 URL 指向的论文解析为 Markdown 研究包
• 在不破坏原始研究结构的前提下，翻译已解析完成的论文
• 查询任务状态，并下载 paper_md、paper_bundle、可选的 paper_pdf 或 translated_md

必要配置

1. 检查环境变量 MDTERO_API_KEY 是否已就绪。
2. 若缺失，请告知用户前往 https://mdtero.com/account 生成密钥。
3. 说明关键词发现与 API 密钥管理均保留在 Mdtero Account 中，不通过其他渠道处理。
4. 请用户在本地 shell 中设置该密钥，例如：

export MDTERO_API_KEY="mdt_live_..."

5. 请求需携带如下认证头：

Authorization: ApiKey $MDTERO_API_KEY

6. 若用户需获取 Elsevier 或 ScienceDirect 的全文内容，还需检查 ELSEVIER_API_KEY，并明确说明该密钥与 MDTERO_API_KEY 相互独立。
7. 若 Elsevier DOI 解析失败，且缺失本地辅助程序或 ELSEVIER_API_KEY，请准确指出缺失项，而非猜测原因。
8. 说明 ELSEVIER_API_KEY 仅用于支持用户本地获取步骤（local acquisition step），它**不能**启用服务端对 10.1016/... 类输入的直接 POST /tasks/parse 请求。

使用前须知

• Mdtero API 调用必须提供 MDTERO_API_KEY；Elsevier 或 ScienceDirect 全文获取还可能需要 ELSEVIER_API_KEY。
• 请告知用户：ClawHub 安装仅配置代理技能，本地辅助程序需用户自行在其机器上单独安装。
• 解析与翻译请求会将论文内容或论文源内容发送至 https://api.mdtero.com，因此除非用户明确接受该边界限制，否则请勿将敏感或专有稿件纳入此工作流。
• 若用户需要本地辅助程序，请指导其下载安装器，在本地审阅后于自身机器运行。切勿建议将远程脚本直接管道传入 shell 执行（如 curl ... | bash）。
• 若用户需要更完整的安装流程或本地辅助程序使用指南，请引导其访问 https://mdtero.com/guide 或 https://api.mdtero.com/skills/install.md。

必须遵守的工作流规则

• PDF 是可选产物。应优先使用 Markdown 包；仅当工作流确实需要时，才回退至 paper_pdf。
• 若用户起始于本地 PDF 文件，请说明 Mdtero 当前默认使用 GROBID；Docling 与 MinerU 仍作为备用选项。
• 对于 Elsevier 和 ScienceDirect 内容，本地获取过程应始终发生在用户自己的机器上，通过本地辅助程序或浏览器扩展完成。
• 直接调用 POST /tasks/parse 仅适用于开放输入（open inputs）。Elsevier 和 ScienceDirect 全文必须先经本地获取，再调用 POST /tasks/parse-fulltext-v2 或 POST /tasks/parse-helper-bundle-v2。
• 若 Elsevier 论文解析结果仅返回摘要，请询问用户是否处于校园网或机构 IP 环境下。
• 对于 Elsevier 论文，请优先使用原始 DOI 格式，例如 10.1016/j.energy.2026.140192。

本地辅助程序（Local Helper）

当用户需要为 Elsevier 或 ScienceDirect 执行本地获取时，请引导其打开官方 Mdtero 使用指南：https://mdtero.com/guide，或安装交接文档：https://api.mdtero.com/skills/install.md。

请用户下载辅助程序安装器，在本地审阅后于自身机器运行。说明该安装器可自动检测系统中是否存在 python3、python 或 node，并无需额外依赖即可暴露 mdtero-local 命令。切勿建议将远程脚本直接管道传入 shell 执行。

若用户需要精确的辅助程序安装脚本地址，请指引其访问 https://api.mdtero.com/helpers/install_mdtero_helper.sh，并强调务必先保存至本地再运行。

说明 mdtero-local parse 与 mdtero-local translate 默认采用短等待模式（short-wait）：快速任务可能立即返回已完成状态；较慢任务则仍返回待处理的 task_id。用户可通过添加 --no-wait 参数强制启用纯异步模式，例如：mdtero-local parse --no-wait ... 或 mdtero-local translate --no-wait ...。

说明公共 API 协议本身仍基于任务模型：POST /tasks/parse 与 POST /tasks/translate 返回 task_id，而 GET /tasks/{task_id} 是稳定可靠的完成状态查询路径。

解析一篇论文

开放输入可直接提交至 POST /tasks/parse。

curl -X POST https://api.mdtero.com/tasks/parse 
  -H "Authorization: ApiKey $MDTERO_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"input": "https://arxiv.org/abs/1706.03762"}'

响应将返回一个 task_id。

对于 Elsevier 或 ScienceDirect 全文，请勿将 DOI 直接发送至 POST /tasks/parse。应先使用本地辅助程序或浏览器扩展完成本地获取，再上传本地辅助程序生成的 bundle：

mdtero-local parse "10.1016/j.enconman.2026.121230"

curl -X POST https://api.mdtero.com/tasks/parse-helper-bundle-v2 
  -H "Authorization: ApiKey $MDTERO_API_KEY" 
  -F "helper_bundle=@paper.helper-bundle.zip"

若 API 明确提示 Elsevier 或 ScienceDirect 输入需先本地获取，这属于预期行为，而非配置失败。

翻译已解析的 Markdown 文件

使用 POST /tasks/translate，其 source_markdown_path 参数应填入解析成功任务所返回的服务器端 Markdown 产物路径，即 result.artifacts.paper_md.path 中的值。请勿替换为任意本地文件路径。

  mdtero-local translate "" zh

  curl -X POST https://api.mdtero.com/tasks/translate 
  -H "Authorization: ApiKey $MDTERO_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "source_markdown_path": "",
    "target_language": "zh",
    "mode": "standard"
  }'

响应将返回一个 task_id。请轮询该任务直至完成，然后下载 translated_md。

查询任务状态

持续轮询 GET /tasks/{task_id}，直到任务状态变为 succeeded。

mdtero-local status 

curl https://api.mdtero.com/tasks/ 
  -H "Authorization: ApiKey $MDTERO_API_KEY"

result 对象返回的是产物元数据（artifact metadata），而非文件内容本身。

下载产物（Artifacts）

通过下载路由获取文件内容。

mdtero-local download  paper_bundle ./paper_bundle.zip

curl -L https://api.mdtero.com/tasks//download/paper_md 
  -H "Authorization: ApiKey $MDTERO_API_KEY" 
  -o paper.md

curl -L https://api.mdtero.com/tasks//download/paper_pdf 
  -H "Authorization: ApiKey $MDTERO_API_KEY" 
  -o paper.pdf

curl -L https://api.mdtero.com/tasks//download/translated_md 
  -H "Authorization: ApiKey $MDTERO_API_KEY" 
  -o paper.zh.md