Skip to content

快速开始.md

Latest commit

 

History

History
278 lines (195 loc) · 8.12 KB

快速开始.md

File metadata and controls

278 lines (195 loc) · 8.12 KB

Local API 快速开始

语言版本： English

相关文档： 总览 · 接口参考 · 插件开发指南

1. 在 Lattice 中启用 Local API

打开：

Settings → Local API

可以看到以下配置项：

  • Enabled
  • Read-Only Mode
  • Port
  • Base URL
  • Trusted Folders（仅在 Read-Only Mode 关闭时显示）

默认端口是 29467，可配置范围是 1024 到 65535。

常见默认地址：

http://127.0.0.1:29467

API 前缀：

http://127.0.0.1:29467/api/v1

如果你修改了端口，现有客户端需要重新连接到新地址。

Read-Only Mode 默认开启。只有你的集成需要 POST /api/v1/papers 或 PUT /api/v1/papers/{id}/pdf 时才需要关闭。如果你还要通过 pdfPath 附带 PDF，请把上层目录加入 Trusted Folders。

2. 先做健康检查和能力检查

curl http://127.0.0.1:29467/api/v1/status

示例响应：

{
  "ok": true,
  "apiVersion": "1",
  "appVersion": "1.0.0 (123)",
  "capabilities": ["search", "paper-detail", "csl-item", "plugin-hosting"],
  "readOnly": true,
  "baseURL": "http://127.0.0.1:29467",
  "browserExtensionEnabled": true
}

说明：

  • ok 为 true 代表服务可访问
  • apiVersion 是当前 HTTP API 版本
  • appVersion 是当前 Lattice 应用版本
  • capabilities 是当前实例支持的功能列表
  • readOnly 反映公开 /api/v1 API 当前的 Read-Only Mode 状态
  • baseURL 是客户端应使用的 localhost 基地址
  • browserExtensionEnabled 反映设置页中的 Browser Extension 开关，但这套文档仍然只关注公开的 /api/v1 与 /plugins 面

如果写入能力已开启，capabilities 里还会出现：

["create-paper", "create-paper-v2"]

如果原始 PDF 字节上传也已经可用，capabilities 里还会出现：

"pdf-upload"

建议规则：

  • 先看 /status.capabilities，再决定是否展示写入 UI 或发送写入请求
  • 把 pdf-upload 视为 PUT /api/v1/papers/{id}/pdf 是否可用的唯一准确信号
  • 不要假设所有写接口在所有机器上都可用

3. 试一次搜索

curl "http://127.0.0.1:29467/api/v1/search?q=graph%20neural%20network&limit=5"

如果 q 为空，接口会返回最近加入文献库的条目。

4. 读取单篇文献详情

拿到搜索结果中的 id 之后：

curl http://127.0.0.1:29467/api/v1/papers/550E8400-E29B-41D4-A716-446655440000

该接口返回面向引用场景的完整文献快照，同时内嵌 cslItem，可直接交给 CSL 处理器。

4a. 获取可分配的文献集与标签

当你的 UI 需要写入时的选择器时，可以调用：

curl http://127.0.0.1:29467/api/v1/collections
curl http://127.0.0.1:29467/api/v1/tags

/collections 返回包含 id、name、path、depth 的文献集对象。

/tags 返回包含 id、name 以及可选 colorHex 的标签对象。

4b. 创建前先做元数据查询

GET /api/v1/metadata 至少接受一个查询参数：doi、arxivId、isbn、title 中的任意一个：

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/metadata?title=Attention%20Is%20All%20You%20Need"

当你的集成只有轻量标识符、但想先预填创建或替换表单时，这个端点会很有用。

5. 可选：创建一篇文献

如果 /status.capabilities 中包含 create-paper：

curl -X POST http://127.0.0.1:29467/api/v1/papers \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Attention Is All You Need",
    "authors": "Vaswani, Ashish; Shazeer, Noam",
    "year": 2017,
    "doi": "10.48550/arXiv.1706.03762",
    "paperType": "inproceedings",
    "strategy": "skip",
    "enrich": true
  }'

典型成功响应：

{
  "id": "550E8400-E29B-41D4-A716-446655440000",
  "title": "Attention Is All You Need",
  "authors": "Vaswani, Ashish; Shazeer, Noam",
  "year": 2017,
  "doi": "10.48550/arXiv.1706.03762",
  "pdfAttached": false,
  "enrichmentStatus": "pending",
  "warnings": [],
  "alreadyExists": false,
  "conflict": null
}

strategy 默认值是 "skip"。

  • "skip" 在检测到重复 DOI 或规范化标题时返回 409 Conflict
  • "replace" 会更新现有文献，并返回 200 OK 与 alreadyExists: true

5a. 可选：通过路径附带 PDF

POST /api/v1/papers 也接受 pdfPath，用于附带磁盘上已存在的 PDF。

使用前请先确认：

  • 已关闭 Read-Only Mode
  • 已把该 PDF 的上层目录加入 Trusted Folders
  • 如果路径不在任何 Trusted Folder 内，接口仍会创建元数据文献，但会返回 pdfAttached: false 和对应 warning

示例：

curl -X POST http://127.0.0.1:29467/api/v1/papers \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Attention Is All You Need",
    "pdfPath": "/Users/me/Papers/attention.pdf"
  }'

5b. 可选：向已有文献上传原始 PDF 字节

如果 /status.capabilities 中包含 pdf-upload，则可以在文献已存在后再上传原始 PDF 字节：

curl -X PUT "http://127.0.0.1:29467/api/v1/papers/550E8400-E29B-41D4-A716-446655440000/pdf" \
  -H "Content-Type: application/pdf" \
  --data-binary @/Users/me/Papers/attention.pdf

注意：

  • 请求体必须是原始 PDF 字节，且 Content-Type 必须是 application/pdf
  • 如果该文献已经附带了 PDF，且你没有传 ?force=true，接口会返回 409
  • 如果当前没有可用的 PDF 上传落盘目标，接口会返回 503

6. 理解读写边界

GET /api/v1/papers/{uuid} 返回的是 citation snapshot，不是完整的内部文献对象。

它当前不会返回：

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

这意味着：

  • 如果你只需要打开 Lattice 中的该文献，可以用返回的 id 自行拼出 lattice://paper/{id}
  • 如果你需要真实 PDF 文件路径，当前 Local API 不提供
  • pdfPath 目前只是 POST /api/v1/papers 的输入字段，不会被读接口回显
  • /metadata 是单独的元数据解析端点，不等同于 GET /api/v1/papers/{uuid}

7. 典型接入方式

方式 A：脚本或本地服务

直接请求完整 URL：

const baseURL = "http://127.0.0.1:29467/api/v1";
const status = await fetch(`${baseURL}/status`).then((r) => r.json());

方式 B：插件页面

如果你的前端页面由 Lattice 自己托管在 /plugins/{name}/... 下，推荐使用相对路径：

const response = await fetch("/api/v1/status");

这样插件页面和 API 天然同源，不需要自己处理跨域问题。

8. 安全与访问限制

Local API 的设计目标是“本机集成”，不是公网服务。

  • 只监听本机回环地址
  • 默认只允许本地浏览器来源访问
  • 支持 GET、POST、PUT 和 OPTIONS
  • POST /api/v1/papers 与 PUT /api/v1/papers/{id}/pdf 都仍然需要用户手动开启公开写入能力；其中 PDF 字节上传还要求 pdf-upload

这意味着：

  • 远程机器无法直接访问这套 API
  • 普通浏览器页面如果不在本地来源上，默认不能直接跨域访问
  • 最稳妥的 Web 集成方式是直接使用 /plugins/{name}/... 托管插件页面

9. 遇到连接不上时先检查

  1. Lattice 是否正在运行
  2. Enabled 是否打开
  3. 端口是否已经改动
  4. 你的请求地址是不是仍指向旧端口
  5. 如果你的宿主集成使用了 manifest、入口 URL 缓存或安装脚本，修改端口后是否已经重新生成或重新安装
  6. 如果 POST /api/v1/papers 返回 403，检查 Read-Only Mode 是否仍然开启
  7. 如果文献创建成功但 pdfAttached 是 false，查看 warnings 数组里的 Trusted Folders、文件类型或文件不存在原因
  8. 如果 PUT /api/v1/papers/{id}/pdf 返回 503，检查当前 Lattice 是否配置了可用的 PDF 上传目标

下一步