人类和 Agent 总览

Mdtero 提供两个入口，并产出相同的结构化 Markdown：适合单篇论文的浏览器扩展，以及适合可重复项目和本地 agent 的 Python CLI。

本地工作流

uv tool install --upgrade mdtero
mdtero setup
mdtero doctor --json

使用 CLI 检索论文、解析 DOI 或已保存文件、下载 Markdown 并翻译：

mdtero discover "thermal energy storage" --limit 5 --interactive
mdtero parse <doi-or-url> --wait --timeout 300 --json
mdtero parse --file paper.pdf --wait --timeout 600 --json
mdtero download <task-id> paper_md --output-dir ./mdtero-output --json
mdtero translate <task-id> --to zh-CN --wait --timeout 600 --json

当来源已在浏览器中打开、依赖你自己的登录或机构访问，或需要选择已保存文件时，使用扩展。它不会赋予你的账户无权访问的内容。

项目工作流

mdtero project init --name literature-review
mdtero project add <doi-or-url> --json
mdtero project import-bib references.bib --json
mdtero project parse --wait --timeout 300 --json
mdtero project download --output-dir ./project-out --json

Zotero 支持采用保守方式。mdtero zotero sync 会为对应的成功项目添加 Mdtero 结果 note 和 tag，不会改写 Zotero 文献元数据。

Agent 工作流

mdtero doctor --json
mdtero mcp briefing --json
mdtero mcp serve

让本地 agent 从健康检查或 briefing 开始。它会获得安全的任务状态、可下载成果、质量提示、引文和建议的下一步。不要把 API key 或其他 secret 放进 prompt、日志或复制的交接内容。

项目问答

文档处理完成后，可以对项目提问，并在研究结论中保留引文：

mdtero rag query "What are the strongest findings?" --build-if-needed --json

需要查看或刷新项目就绪状态时，可显式使用 mdtero rag status 与 mdtero rag build --wait --json。

公开契约

稳定的用户流程是提交任务、查看状态、下载、翻译和带引文的项目问答。直接集成 API 时见 API 参考。解析器选择、来源采集和服务实现由 Mdtero 管理，不是用户可选配置。