场景示例 · Textira

给论文平台用的端到端例子：建任务文献库 → 导入 → 短索引 → 写作挂 MCP。
接口字段与错误码见 论文相关接口。完整可跑脚本：仓库 examples/paper-client.mjs。

鉴权：Authorization: Bearer <sv_…>。Base：LLMWIKI_BASE_URL（本地 http://localhost:8000）。
id / slug / sv_ / external_task_id 见概念说明 · 常用标识。

场景

文献检索完成
  → ① 幂等创建任务文献库
  → ② 批量导入参考文献
  → （可选）上传用户 PDF/Word
  → ③ 拉取短索引（引用表）
  → 写作：挂 MCP …/{slug}/mcp（推荐）
  → （可选）按大纲生成插图
  → （历史打开）取文件预签名 URL
  → （可选）用户勾选后：同步文档到知识库

步骤	做什么	规格
① 建库	`POST /v1/knowledge-bases` + `external_task_id`	建库
② 导入	检索结果写成可检索 Markdown	导入
③ 短索引	编号 + citation	短索引
插图	交论文大纲 → Textira 判断图种并出图	按大纲生成插图
文件地址	打开原文件	文件地址
排版 PDF / Word	选模板，提交 Markdown，直接拿到 PDF 或 Word	选模板 + Markdown → PDF / Word
排版 PPT	选演示稿模板，提交 Markdown，直接拿到 PowerPoint	Markdown → PPT

建库后请持久化：knowledge_base.id、slug、external_task_id。
写作优先 MCP；不可达时再用短索引 / 正文 HTTP 回退。

retrievedReferences → 导入字段：稳定 id → external_id；title / authors / journal / year / doi / abstract；整条可放 raw。

Node 示例

Node 18+，内置 fetch。

export LLMWIKI_BASE_URL=http://127.0.0.1:8000
export LLMWIKI_API_TOKEN=sv_你的密钥   # 设置 → API 密钥

const BASE = process.env.LLMWIKI_BASE_URL.replace(/\/$/, "");
const headers = {
  Authorization: `Bearer ${process.env.LLMWIKI_API_TOKEN}`,
  "Content-Type": "application/json",
};

// ① 建库（幂等）
const kb = await fetch(`${BASE}/v1/knowledge-bases`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    external_task_id: "lp_task_6",
    name: "用户 · 任务6 · 选题",
  }),
}).then((r) => r.json());
// 保存 kb.id、kb.slug

// ② 导入
await fetch(`${BASE}/v1/knowledge-bases/${kb.id}/imports/references`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    mode: "upsert",
    references: [
      {
        external_id: "ref_1",
        title: "标题",
        authors: ["作者"],
        journal: "期刊",
        year: "2023",
        abstract: "摘要…",
      },
    ],
  }),
});

// ③ 短索引
const index = await fetch(`${BASE}/v1/knowledge-bases/${kb.id}/reference-index`, {
  headers,
}).then((r) => r.json());
// index.items[].citation、urls

// 文件地址（按任务）
const files = await fetch(
  `${BASE}/v1/integrations/paper/task-libraries/by-external/lp_task_6/files?variants=source,preview`,
  { headers },
).then((r) => r.json());

// 按大纲出图（Textira 判断画什么；轮询 status）
const figJob = await fetch(`${BASE}/v1/integrations/paper/figures`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    locale: "zh",
    outline: "你们自己的论文大纲（文字或 JSON）",
    materials: { idea: "方法简述…", experimental_log: "有实测再给" },
  }),
}).then((r) => r.json());
// GET …/figures/${figJob.id} 直到 succeeded，打开 figures[].url，按 slot 插入章节

写作（MCP，推荐）

// server_url = https://your-host/{kb.slug}/mcp
// Authorization: Bearer sv_…
// 详见通义千问 MCP 文档

node examples/paper-client.mjs