Skip to content

总览.md

Latest commit

 

History

History
94 lines (69 loc) · 4.87 KB

总览.md

File metadata and controls

94 lines (69 loc) · 4.87 KB

Lattice Local API

语言版本： English

Lattice 提供了一个只在本机监听的 HTTP API，方便外部工具访问文献库中的引文型数据、托管本地插件前端，并在设置页把 Read-Only Mode 关闭后创建新文献，而不需要直接依赖 Lattice 的内部数据模型或应用包。

相关文档： 快速开始 · 接口参考 · 插件开发指南

这套文档面向外部开发者，重点回答下面几类问题：

  • Local API 能做什么
  • 提供了哪些端点
  • 请求和返回的数据结构是什么
  • 怎样开发自己的本地插件或集成

这套文档只覆盖公开的 /api/v1 API 与 /plugins/{name}/... 静态资源托管面，不介绍浏览器扩展专用的内部路由。

能力概览

能力 说明
本地健康检查 检查 Local API 是否可用、当前 API 版本、Lattice 版本、能力列表以及当前 localhost 基地址
文献搜索 按标题、作者、期刊/出版源、citekey、年份搜索文献
单篇文献详情 获取单篇文献的详细引用元数据
元数据查询 在创建或更新文献前，按 DOI、arXiv ID、ISBN 或标题解析元数据
文献集与标签目录 获取写入 UI 可分配的文献集与标签列表
CSL-JSON 输出 在文献详情中直接返回可供 citeproc 等处理器使用的 cslItem
文献创建 当 /status.capabilities 中包含 create-paper 时，可创建文献、分配文献集/标签、附带 PDF、指定重复策略并触发后台补全
PDF 字节上传 当 /status.capabilities 中包含 pdf-upload 时，可向已有文献上传原始 PDF 字节
插件静态资源托管 通过 /plugins/{name}/... 托管本地插件前端资源

设计边界

  • 这是一个本地 API，只监听 127.0.0.1。
  • 面向本机脚本、自动化工具、桌面伴生工具、Office/Obsidian 一类插件式集成。
  • 所有业务端点都位于 /api/v1 之下。
  • 这套文档只覆盖公开的 /api/v1 业务端点与 /plugins/{name}/... 静态托管。
  • 写入能力是可选的，只有在 Settings → Local API 中关闭 Read-Only Mode 后，POST /api/v1/papers 才可用。PUT /api/v1/papers/{id}/pdf 还要求 /status.capabilities 中包含 pdf-upload。如果请求里带了 pdfPath，该 PDF 还必须位于 Trusted Folders 或其子目录内。
  • 读接口返回的是面向引用场景的 citation snapshot，不是 Lattice 内部 Paper 模型的完整序列化。

当前读接口不会返回的字段包括：

  • abstract
  • collections
  • tags
  • notes
  • pdfPath
  • pdfURL
  • latticeURL

如果你的集成只需要打开 Lattice 中的某篇文献，可以用返回的 id 自行拼出 lattice://paper/{id}。如果你需要真实的 PDF 文件路径，当前 Local API 不会提供。

文档导航

建议阅读顺序：

  1. 先看 快速开始
  2. 需要字段和端点细节时看 接口参考
  3. 需要做本地插件或外部扩展时看 插件开发指南

各文件用途：

文档 适合什么时候看 主要内容
快速开始.md 第一次接入时 如何启用 Local API、检查能力、发送最小读写请求、基础排错
接口参考.md 写客户端、封装 SDK、对接接口时 所有公开端点、请求参数、响应结构、字段-方法矩阵、错误码、字段说明与能力边界
插件开发指南.md 开发本地前端插件、宿主扩展时 /plugins/{name}/... 托管方式、目录布局、接入模式、写入能力检测、部署和调试建议

一分钟上手

假设你的 Local API 运行在默认端口 29467：

curl http://127.0.0.1:29467/api/v1/status
curl "http://127.0.0.1:29467/api/v1/metadata?doi=10.48550/arXiv.1706.03762"
curl http://127.0.0.1:29467/api/v1/collections
curl "http://127.0.0.1:29467/api/v1/search?q=transformer&limit=5"
curl http://127.0.0.1:29467/api/v1/papers/550E8400-E29B-41D4-A716-446655440000
curl -X POST http://127.0.0.1:29467/api/v1/papers \
  -H "Content-Type: application/json" \
  -d '{"title":"Attention Is All You Need"}'

适合怎样的集成

  • Shell / Python / Node 脚本：直接请求 http://127.0.0.1:<port>/api/v1/...
  • 本地 Web UI：将静态资源部署到 /plugins/{name}/...，再通过相对路径请求 /api/v1/...
  • Office / 桌面插件：让宿主加载 /plugins/{name}/... 下的页面，再由页面调用 Local API

现有外部扩展参考

仓库中的 word-addin 与 raycast-extension 目录包含基于公开 Local API 实现的外部扩展资源，可作为插件打包方式、静态资源组织方式以及本地托管接入方式的参考。