# MCP 服务(paper-doc-mcp) 把 paper-doc 的论文、段落、句子、模板、字段库、文献库能力暴露成 **Model Context Protocol** 工具, 让 Claude Code、Codex、DeepSeek Harness(DSH)等任何 MCP 客户端直接增删改查论文。 **一句话用法**:AI 生成完整论文 → 调 `paper_write_text` 一次写入 → 用 `paragraph_write` / `sentence_update` 微调 → `paper_document` 读回来检查。 - 代码:`backend/app/mcp/`(工具实现)、`backend/scripts/mcp_server.py`(入口) - 冒烟测试:`backend/scripts/smoke_mcp.py`(真 MCP 客户端跑 119 项检查、覆盖 42/42 个工具,stdio 与 HTTP 都过) - 工具数量:**42 个**,按 `paper_` / `paragraph_` / `sentence_` / `template_` / `field_` / `reference_` / `reference_tag_` / `image_` 八组前缀 - 协议:MCP 2024-11-05 ~ 2025-11-25(官方 Python SDK `mcp>=2.2,<3` 协商) - 传输:`stdio`(本地拉起)与 `streamable-http`(远程连接,支持 Bearer 口令),另兼容旧 `sse` - **已经部署在 k3s 里**:命名空间 `paper-doc`,端点 `http://192.168.1.88:30931/mcp` (打包、发布、回滚见 [deploy/README.md](../deploy/README.md)) --- ## 1. 快速开始 ### 1.1 自检(先确认能连数据库) ```bash cd /data/project/paper/backend .venv/bin/python scripts/mcp_server.py --check ``` 输出示例: ``` paper-doc MCP 1.0.0 (name=paper-doc) database : mysql+pymysql://Govin:***@192.168.1.88:32738/paper_doc rows : paper=1, template=3, paper_sentence=6, template_field_library=20 tools : 29 field=5, paper=9, paragraph=5, sentence=5, template=5 - paper_list ... ``` 连不上数据库会打印失败原因并返回非 0——这是最常见的"工具调不动"根因, 所以接入任何客户端前先跑一次。 ### 1.2 stdio(推荐给本地客户端) 客户端自己拉起进程,通过 stdin/stdout 讲 JSON-RPC: ```bash /data/project/paper/backend/.venv/bin/python \ /data/project/paper/backend/scripts/mcp_server.py ``` 从任何工作目录都能跑(脚本自己锚定 `sys.path`),所以客户端不需要配 `cwd`。 ### 1.3 连已经在跑的那一个(k3s 里) 不用自己起进程——服务已经部署好了: ``` http://192.168.1.88:30931/mcp # 局域网 / 宿主机 http://paper-doc-mcp.paper-doc.svc.cluster.local:8931/mcp # 集群内 Pod ``` 除 `/healthz`、`/readyz` 外都要带 `Authorization: Bearer `。 取口令: ```bash export KUBECONFIG=$HOME/.kube/config kubectl -n paper-doc get secret paper-doc-secrets -o jsonpath='{.data.MCP_HTTP_TOKEN}' | base64 -d; echo ``` 自检与验证: ```bash curl -s http://192.168.1.88:30931/readyz cd backend && .venv/bin/python scripts/smoke_mcp.py \ --url http://192.168.1.88:30931/mcp --token '<口令>' # 47 项检查 ``` ### 1.4 streamable-http(自己起一个) ```bash cd /data/project/paper/backend .venv/bin/python scripts/mcp_server.py \ --transport http --host 0.0.0.0 --port 8931 --token '你的口令' ``` - 端点:`http://:8931/mcp` - 设了 `--token` 后,每个请求都要带 `Authorization: Bearer <口令>`,否则 `401` - 绑定非 127.0.0.1 时会自动关掉 DNS-rebinding 保护(否则客户端用局域网域名访问会被 421), 此时**口令就是唯一的门**——不设口令会打印警告 也可以用环境变量代替参数:`MCP_TRANSPORT` / `MCP_HOST` / `MCP_PORT` / `MCP_PATH` / `MCP_HTTP_TOKEN`。 ### 1.5 跑冒烟测试 ```bash cd /data/project/paper/backend .venv/bin/python scripts/smoke_mcp.py # 自己拉起 stdio 子进程 .venv/bin/python scripts/smoke_mcp.py --url http://127.0.0.1:8931/mcp --token 你的口令 # 连已有的 HTTP 服务 ``` 同一个套件 **119 项检查**跑两种传输,覆盖 25 个步骤:建论文 → 看骨架 → 按标题写段落 → 定位失败时列出候选标题 → 读段落/追加带引用的句子 → 只改一句 → 删一句 → 整篇一次写入 → 读全文 → 跨论文搜索 → **另起一行**(公式独行、标记开关、搬段落时跟着走)→ **参考文献表** (一处引用一行、一部文献一条、正文编号与表号同号)→ **插图**(传图、同一张图只存一份、 独占一行、行内图不断行、格式/尺寸/非 base64 的拒绝)→ **公式对齐**(写入、单独改、跟着搬)→ 搬段落 → 清空段落 → 字段库增删改 → 建/改模板 → 换模板后正文不丢 → 文献库增删改查与批量导入 → 引用守卫(被引用的文献删不掉)→ 删模板被拒 → 删论文要确认 → 清理。写真实数据(插图那步还需要 MinIO 可用),结束时自己删干净。 --- ## 2. 客户端配置 ### 2.1 DeepSeek Harness(DSH) 编辑 `~/.dsh/profiles/web/cordis.patch.yml`,**新条目必须放进 `insert:` 列表** (裸条目会被当成"覆盖已有 id",profile 里没有该 id 时只 warn 后静默跳过)。 stdio(Harness 自己拉起进程,最简单): ```yaml - insert: - id: mcp-paper-doc name: '@deepseek-ai/dsh-mcp-client' config: serverName: paper transport: stdio command: /data/project/paper/backend/.venv/bin/python args: - /data/project/paper/backend/scripts/mcp_server.py cwd: /data/project/paper/backend toolCallTimeoutMs: 60000 failOnStartupError: false # 连不上也不影响 Harness 启动 ``` streamable-http(服务常驻,多个客户端共用): ```yaml - insert: - id: mcp-paper-doc name: '@deepseek-ai/dsh-mcp-client' config: serverName: paper transport: streamable-http url: http://127.0.0.1:8931/mcp headers: Authorization: Bearer 你的口令 toolCallTimeoutMs: 60000 failOnStartupError: false ``` `serverName: paper` 决定了模型看到的工具名是 `mcp__paper__paper_write_text` 这种形式。 web profile 是 `patchReload: live`,保存后通常热加载;不行就重启 dsh-web。 ### 2.2 Claude Code 本地 stdio: ```bash claude mcp add paper -- /data/project/paper/backend/.venv/bin/python \ /data/project/paper/backend/scripts/mcp_server.py ``` 远程 HTTP(带口令): ```bash claude mcp add --transport http paper http://192.168.1.88:8931/mcp \ --header "Authorization: Bearer 你的口令" ``` 或者项目根目录放 `.mcp.json` 提交进仓库,团队直接共享: ```json { "mcpServers": { "paper": { "type": "stdio", "command": "/data/project/paper/backend/.venv/bin/python", "args": ["/data/project/paper/backend/scripts/mcp_server.py"], "env": {} } } } ``` 查看与调试:`claude mcp list`、`claude mcp get paper`、会话里 `/mcp`。 ### 2.3 Codex CLI 编辑 `~/.codex/config.toml`。 本地 stdio(`~/.codex/config.toml`): ```toml [mcp_servers.paper] command = "/data/project/paper/backend/.venv/bin/python" args = ["/data/project/paper/backend/scripts/mcp_server.py"] enabled = true # 可选:数据库配置(不写就读 backend/.env) [mcp_servers.paper.env] # DB_HOST = "192.168.1.88" # DB_PORT = "32738" ``` 远程 streamable-http: ```toml [mcp_servers.paper] url = "http://192.168.1.88:8931/mcp" bearer_token_env_var = "PAPER_MCP_TOKEN" # 口令放环境变量,别写进配置文件 enabled = true ``` 命令行管理:`codex mcp list` / `codex mcp add` / `codex mcp get paper`。 > 参考:[Codex MCP Servers 文档](https://mintlify.wiki/openai/codex/configuration/mcp-servers) ### 2.4 远程(Windows 上的 Claude Code / Codex) 服务已经部署在 k3s 里,直接连它就行,客户端填: ``` URL: http://192.168.1.88:30931/mcp Header: Authorization: Bearer ``` 走 Tailscale 的机器把地址换成 `http://100.64.0.1:30931/mcp`(NodePort 在节点上监听, 两个地址都通)。 不想暴露端口的话,还有一条 SSH 包 stdio 的路子:客户端 `command = "ssh"`, 让远端执行 `mcp_server.py`,协议走 SSH 的 stdin/stdout (见 ssh_intranet_skill 的 SSH_ASKPASS 写法)。 --- ## 3. 工具参考 约定: - 工具名即函数名;`(可选)` 的参数可以不传,其余必填。 - 返回一律是 **JSON 文本**(不是结构化对象),字段为 `None` 的一律不输出。 - 失败不是抛异常,而是 `isError: true` + 一句中日文都看得懂的说明(例如 `论文 999999 不存在`、`模板“X”已存在`、`请先用 paper_update 给论文切换模板:…`)。 ### 3.1 论文 papers(9 个) | 工具 | 作用 | 关键参数 | |---|---|---| | `paper_list` | 列论文(不含正文),返回 id/标题/模板/进度 | `keyword?` `status?` `template_id?` `page?` `page_size?` | | `paper_get` | 取一篇论文的元信息与进度 | `paper_id` | | `paper_create` | 新建论文(只写元信息) | `title`、`template_id?` `author?` `status?` `keywords?` `target_journal?` | | `paper_update` | 改元信息 / 换模板 | `paper_id`、`title?` `template_id?` `clear_template?` `author?` `status?` `keywords?` `target_journal?` | | `paper_delete` | 删论文(连句子引用) | `paper_ids`(int 或数组)、`confirm=true` 必填 | | `paper_outline` | **写之前先看**:每段 position/标题/已写句数 | `paper_id` | | `paper_document` | 读全文(`format=text` 时末尾附 Springer 格式的参考文献表) | `paper_id`、`format?`(`text`/`json`/`both`)`include_empty?` `citations?` | | `paper_write` | **批量写段落**(按标题或位置) | `paper_id`、`paragraphs`、`mode?`(`replace`/`append`) | | `paper_write_text` | **整篇一次写入**(Markdown 标题分段) | `paper_id`、`text`、`split?` `mode?` `strict?` | `paper_update` 的语义:不传 = 不改;传空字符串 = 清空该文本字段;`clear_template: true` 才能把模板置空。 换 `template_id` 只是重塑标题,正文按位置留在原地,不丢。 `paper_delete` 必须先被拒一次(告诉你删掉什么、不可恢复),确认后才带 `confirm=true` 重调。 `paper_document` 的 `text` 里,正文的上标编号与末尾参考文献表的序号是**同一个号**:同一篇文献被引多次只占一个号、只列一条。 `json` 里对应的是 `references`(每条一个文献,`text` 就是排好版的条目)与 `reference_style`(当前是 `springer`), 以及 `citations`(每处引用一行,带自己的 `index`)。条目里缺哪些字段,看那条的 `missing`(如 `["卷期页码"]`), 不要自己去猜或补一个看起来合理的年份。 ### 3.2 段落 paragraphs(5 个) 段落 = 位置。它由模板定义,或者由内容占据;**没有 `paragraph_create`**——往空位置写内容就是创建它。 | 工具 | 作用 | 关键参数 | |---|---|---| | `paragraph_list` | 段落骨架 + 预览 | `paper_id`、`include_empty?` `preview?` | | `paragraph_get` | 读一段:拼好的正文、逐句 id/内容/引用/分隔符与换行 | `paper_id`、`position?` `heading?` | | `paragraph_write` | 写一段(覆盖或追加) | `paper_id`、`position?` `heading?`、`sentences?` `text?` `split?` `citations?` `mode?` | | `paragraph_delete` | 清空该段全部句子(段落仍在) | `paper_id`、`position?` `heading?` | | `paragraph_move` | 整段搬到另一个位置(**接在目标段已有内容之后**,换行与引用一起搬过去) | `paper_id`、`position?` `heading?`、`target_position?` `target_heading?` | 定位规则:`position` 直接采用(包括模板没定义的位置,会以"未设定"渲染); `heading` 按模板解析,忽略编号、空格和大小写,所以下面三种写法等价: ``` "1. Introduction" / "1 Introduction" / "Introduction" ``` 匹配不上或匹配到多个时,错误消息里会带上**模板里真实可用的标题列表**, 模型据此改一次就能成功。 ### 3.3 句子 sentences(5 个) 一句一行。改一句话不要重写整段——重写会让整段的句子 id 全变,而引用是挂在 id 上的。 | 工具 | 作用 | 关键参数 | |---|---|---| | `sentence_list` | 列句子(可只列某段) | `paper_id`、`position?` `heading?` `include_empty?` | | `sentence_add` | 段尾追加一句(可带引用) | `paper_id`、`content`、`position?` `heading?` `citations?` `line_break_before?` `formula_align?` `sort?` | | `sentence_update` | 改正文 / 改所属段 / 改排序 / 改换行 / 改公式对齐 / 整组换引用 | `paper_id`、`sentence_id`、`content?` `position?` `sort?` `line_break_before?` `formula_align?` `citations?` | | `sentence_delete` | 删一句(连引用) | `paper_id`、`sentence_id` | | `sentence_search` | **跨论文搜句子**(保持术语一致) | `keyword`、`paper_id?` `limit?` | 一句能带的字段就是这一组(`content`、`sort`、`line_break_before`、`formula_align`、`citations`, 外加写插图用的图片 Markdown)。**MCP 的工具 schema 必须声明全部字段**,`smoke_mcp.py` 第一步就查这件事—— 少一个字段意味着模型能写、工具会静默丢掉,写作调用"成功"而内容不对。 #### 另起一行:公式、分条列举、作者行 一段是**它的句子连排**出来的,所以"不是散文的行"要自己开口。方式是在句子对象上加 `line_break_before: true`,写进去、读回来、搬走都带着: ```jsonc {"heading": "3. Methods", "sentences": [ "本段说明公式的来历。", {"content": "$$ E = mc^2 $$"}, // 不用标,见下 {"content": "其中 $c$ 为光速。", "line_break_before": true}, {"content": "(1)第一项;", "line_break_before": true} ]} ``` 三条规则: 1. **换行顶掉分隔符,不是叠加。** 新行本身已经把两句分开了,再加一个空格会让下一行空一格。 2. **独占一行的东西不必标。** display 公式(`$$…$$` 或 `\[…\]`)和"整句只有一张图"的插图 都自己占一行——论文页面就是这么排的,`paper_document` 的 `text` 也这么排,两处必须一致, 所以模型不要去猜"这里要不要加标记"。行内公式(`$…$`)和夹在句子中间的图不算。 3. **"请读一遍这一段"时看得到换行。** `paragraph_get` / `paper_document` 返回的 `text` 里换行就是真的换行符; `sentence_list` 每句还带 `line_break_before` 与 `formula_align` 字段,所以搬句子之前能看出 哪几句是另起的行、公式是怎么摆的。 `text` + `split` 那种整块写法也可以带 `line_break_before`,但它只作用于**切出来的第一句**—— "这一块从新的一行开始"。块里其余几句是接着它的,不是各自另起一行;否则一个换行写了三行的段落 就会被切成三行。 #### 公式怎么摆:center / left / right 含 display 公式的句子还带 `formula_align`,默认 `center`,可给 `left` 或 `right`: ```jsonc {"content": "$$ \\Delta I = f(\\tau) $$", "line_break_before": true, "formula_align": "left"} ``` 它是**每一句公式自己的排版**,不是标题(字段库)的设置:一段里合法的组合就是"先居中一个公式、 后面接一个右对齐的续行"。句号后的编号(`\tag{1}`)始终靠右,三种对齐都一样。 只对含 display 公式的句子有意义——纯文本句子给了它也不会变样,但它照样会被原样存下来。 ### 3.4 模板 templates(5 个) 模板就是结构:论文的标题是**每次渲染现读模板**得到的,所以改模板会影响所有用它的论文, 删模板会被拒绝(错误消息会说明有几篇论文在用、该怎么换)。 | 工具 | 作用 | 关键参数 | |---|---|---| | `template_list` | 列模板(含字段数) | `keyword?` `page?` `page_size?` | | `template_get` | 取完整大纲 + 被几篇论文使用 | `template_id` | | `template_create` | 新建模板 | `name`、`abstract?`、`field_ids?`(按顺序)或 `fields?`(`[{field_id, sort}]`) | | `template_update` | 改名/改说明/整组换字段 | `template_id`、`name?` `abstract?` `clear_abstract?` `field_ids?` `fields?` | | `template_delete` | 删模板 | `template_ids`(int 或数组) | `field_ids: [2, 6, 9]` 会自动编号成 `sort = 10, 20, 30`——留出间隙, 以后想插一个字段不用重排其余所有位置。 ### 3.5 字段库 fields(5 个) 字段库是"模板能用的所有标题"的目录,全局共享。编号写在 `name` 里,由人决定,系统不改写; `level` 只影响缩进,不构成父子关系——所以同一个二级标题可以出现在多个一级标题下。 | 工具 | 作用 | 关键参数 | |---|---|---| | `field_list` | 列字段库(建模板前先查 id) | `keyword?` `level?` `page?` `page_size?` | | `field_get` | 取一个字段 + 被几个模板使用 | `field_id` | | `field_create` | 加一个标题字段 | `name`、`level?` `font_size?` `font_color?` | | `field_update` | 改名/层级/字号/颜色 | `field_id`、`name?` `level?` `font_size?` `font_color?` | | `field_delete` | 删字段(仍被模板使用会被拒) | `field_ids`(int 或数组) | --- ### 3.6 参考文献 references(7 个) 参考文献库是引用的另一半:句子上的 `reference_id` 指向它。建文献前**先用 `reference_list` 查重**—— `keyword` 会同时搜题名、副题名、期刊名、DOI、关键词、备注和作者名。 | 工具 | 作用 | 关键参数 | |---|---|---| | `reference_list` | 检索文献库(也是查重路径) | `keyword?` `type?` `year?` `cited_only?` `tag_ids?` `page?` `page_size?` | | `reference_get` | 取一条文献的全部字段 | `reference_id` | | `reference_create` | 新增一条 | `reference`(对象,见下)| | `reference_update` | 改字段,只传要改的 | `reference_id`、`changes` | | `reference_delete` | 删(被引用的会被拒) | `reference_ids`(int 或数组) | | `reference_import` | **一次录入一批**,自动跳过重复 | `references`(数组)、`skip_duplicates?` | | `reference_citations` | **这条文献被哪些句子引用了** | `reference_id` | `reference_create` 的 `reference` 对象(39 个字段,全都有默认值,能填多少填多少): ```jsonc { "type": "journal-article", // journal-article / book / book-chapter / conference-paper / // thesis / patent / standard / report / newspaper-article / // web-page / dataset / software / preprint / other "title": "题名(必填)", "authors": [ // 顺序即印刷顺序 {"name": "Smith, John", "family_name": "Smith", "given_name": "John"}, {"name": "张三", "role": "editor"} // role: author(默认)/ editor / translator / compiler ], "container_title": "期刊名", "volume": "12", "issue": "3", "pages": "45-67", "publication_year": 2024, "doi": "10.1000/xyz", "url": "…", "keywords": "…", "abstract": "…", "note": "…", "language": "en", "isbn": "…", "issn": "…", "patent_number": "…", "standard_number": "…", "accessed_date": "2024-05-01", "citation_key": "smith2024flood", "tag_ids": [3, 7] } ``` `reference_update` 的 `changes` 只写要改的字段;**传 `null` 表示清空该字段**(不传就是不动): ```jsonc {"name": "reference_update", "arguments": { "reference_id": 42, "changes": {"publication_year": 2025, "doi": "10.1000/xyz-v2", "note": null} }} ``` `authors` 和 `tag_ids` 一给就是**整体替换**(`tag_ids: []` 清空标签)。 ### 3.7 文献标签 reference_tag(5 个) 标签不是分类,是标记(「必读」「方法」「待核实」)。删标签**不会**动文献——只掉标记; 删文献则要求它没被引用。 | 工具 | 作用 | 关键参数 | |---|---|---| | `reference_tag_list` | 列标签(含每个标签下几条文献)| `keyword?` `page?` `page_size?` | | `reference_tag_get` | 取一个标签 | `tag_id` | | `reference_tag_create` | 新建(名称唯一)| `name`、`color?` `note?` | | `reference_tag_update` | 改名/颜色/备注 | `tag_id`、`name?` `color?` `note?` `clear_note?` | | `reference_tag_delete` | 删标签(文献不受影响)| `tag_ids`(int 或数组)| ### 3.8 插图 images(1 个) 图片不进数据库:**字节放 MinIO,句子只留地址**,写成 Markdown。 | 工具 | 作用 | 关键参数 | |---|---|---| | `image_upload` | 传一张图,返回可写进句子的 Markdown 与那个句子对象 | `data_base64`、`caption?` `filename?` `width?` `height?` | ```jsonc {"name": "image_upload", "arguments": { "data_base64": "iVBORw0KGgo…", // 也可以直接给 data:image/png;base64,… "caption": "图 3 惯性—冲量相空间", // 不给就用 filename 的主干 "width": "70%", // 或 400px;不传按原尺寸(不超过栏宽) "height": "300px" // 可选,只能像素;图不会超过这个高 }} // → {"key": "2026/09/9f8c1a4b7e2d0c33.png", // "url": "/api/images/2026/09/9f8c1a4b7e2d0c33.png", // "markdown": "![图 3 惯性—冲量相空间](/api/images/2026/09/9f8c1a4b7e2d0c33.png){width=70%}", // "sentence": {"content": "![图 3 …](…){width=70%}", "line_break_before": true, "formula_align": "center"}} ``` 拿回来的 `sentence` **原样**放进 `paper_write` / `paragraph_write` / `sentence_add` 的 `sentences` 里就是一张插图, 不需要再拼字符串——`content` 与网页端"插入图片"写出来的是同一个(都走 `markdown_for`)。 三条规则: 1. **键就是内容的摘要。** 同一张图传两次是**同一个对象**(不是两份),地址永远指不到别的图上, 所以 `url` 可以带一年不变的缓存头。文件名、`Content-Type` 都只是说法,格式按字节判断。 2. **只收 PNG / JPEG / GIF / WebP,SVG 明确不收**(从本站点提供上传的 SVG 等于存储型 XSS)。 超过 20 MB 会被拒,并告诉你先压缩。 3. **句子只有一张图 = 插图**(独占一行、居中、方括号里的字当图注);图夹在一句话中间就是行内小图。 `paragraph_get` / `paper_document` 的 `text` 按同一条规则断行,图以它存储的 Markdown 原样印在自己的行上—— 文本画不出图片,而地址是"哪一张图"的唯一答案,读回来还能原样搬走。 **宽和高可以分别填**,写法都在句子正文里: | 想要的效果 | 句子正文里写 | 结果 | |---|---|---| | 宽正好 500px,高自动 | `{width=500px}` | 500×(按原比例算) | | 占栏宽的 70% | `{width=70%}` | 列宽×0.7,高自动 | | **高不超过 300px**,宽自动 | `{height=300px}` | 宽 = 300×原比例,按比例缩 | | 放进 500×300 的框里 | `{width=500px height=300px}` | 等比缩放塞进框内 | | 原尺寸 | 不写 | 按原图,最多不超过栏宽 | 三条规则: 1. **宽是精确值,高是上限。** 宽有参照物(栏宽或你给的像素),所以给多少就是多少;高没有参照物, 也没必要把图放大到比它本身还大(只会糊),所以 `height` 是"不超过这个高"。你说的场景(把太高的图压矮) 两种情况结果一样。 2. **永远只给宽度或只给高度时,另一边由浏览器按原比例算**——所以图不可能被拉变形。两个都给就是 "放进这个框里",也是等比缩放,不会拉伸。 3. **写法宽容,含义严格。** `70%`、`70 %`、`{width=70%}`、`w=400px` 都收;宽 1–4000px 或 1–100%, 高 1–4000px(**高不能用百分比**:句子里没有可参照的高度,浏览器会直接忽略,那等于写了个不生效的值)。 `width` 只写数字按**百分比**算(`60` = `60%`);`height` 只写数字按**像素**算。 超出范围或读不懂的一律拒绝并说明,而不是默默退回原尺寸。 这几种写法在网页端可以点着填:段落编辑器里,凡是"整句只有一张图"的行都有「宽」「高」两个框, 可以用预设,也可以直接打字(如 `63%`、`380px`、`250`),旁边实时显示这会在版面上占多大 (如 `原图 1857×1986 · 显示 893×955`)。 同一个大小在网页端也能改:段落编辑器里,凡是"整句只有一张图"的行都会出现「宽度」下拉框, 可以选 25/50/70/100%,也可以直接填任意值(如 `63%`、`380px`),旁边实时显示这会在版面上 占多大(如 `原图 1857×1986 · 显示 893×955`)。 存储没配好(缺 `MINIO_ENDPOINT` / `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY`)时,这个工具报 503 语义的说明, **写作路径照常**:论文、段落、句子、模板、文献都不碰对象存储。 ## 4. 典型用法 ### 4.1 AI 写完,整篇一次灌进去(主推) ```jsonc // 1) 先看骨架,拿到真实标题 {"name": "paper_outline", "arguments": {"paper_id": 96}} // → {"paper": {...}, "paragraphs": [{"position": 10, "heading": "0 Abstract", "sentences": 0}, ...]} // 2) 把生成的论文按标题切好,一次写入 {"name": "paper_write_text", "arguments": { "paper_id": 96, "text": "# 0 Abstract\n摘要第一句。摘要第二句。\n\n# 1 Introduction\n引言第一句。引言第二句。\n\n## 2 Related Work\n相关工作……", "split": "sentence" // 中文长句按 。!? 切;一行一句则用 "line" }} // → {"paper_id": 96, "written": [{"position": 10, "heading": "0 Abstract", "sentences": 2}, ...], // "total_sentences": 24} ``` `split` 三种模式: | 模式 | 含义 | 什么时候用 | |---|---|---| | `line`(默认) | 一行 = 一句 | 文本本身已经一行一句(最保险,不猜) | | `sentence` | 按 `。!?` 和英文 `.?!` 切句 | 一整段挤在一行时的中文长文 | | `paragraph` | 整段 = 一句 | 你确实想让它是一句 | > `sentence` 会避开小数点(`3.14`)和 `et al.` / `i.e.` 这类缩写,但它仍然是"猜"。 > 想完全不猜,就直接给 `sentences` 数组。 `paper_write_text` 的正文是一整块字符串,**表达不了"这一句另起一行"**(也只有第一行能带)。 display 公式不用担心——它本来就独占一行;但分条列举、作者行这类要另起的行, 请改用 `paper_write` 给 `sentences` 数组并加 `line_break_before: true`(见 §3.3)。 标题识别两种形态:Markdown 标题行(`# 0 Abstract`),或**与模板完全同名的独立一行** (把 `paper_outline` 的标题原样抄下来最稳)。前面没有标题的内容会被丢弃; 一个都没匹配上则整次调用报错,不会写半截。 ### 4.2 分批写(更长、更可控) ```jsonc {"name": "paper_write", "arguments": { "paper_id": 96, "mode": "replace", "paragraphs": [ {"heading": "0 Abstract", "sentences": ["摘要第一句。", "摘要第二句。"]}, {"heading": "2 Related Work", "text": "相关工作这一段我整段给。第二句在这里。", "split": "sentence"}, {"position": 70, "sentences": [ {"content": "带引用的一句。", "citations": [{"quote": "被引用的原话", "reference_id": 12}]} ]} ] }} // → {"paper_id": 96, "written": [{"position": 10, "heading": "0 Abstract", "sentences": 2}, ...], // "total_sentences": 5} ``` `mode: "append"` 改成追加,不动该段已有内容。 ### 4.3 微调:只动一句话 ```jsonc {"name": "paragraph_get", "arguments": {"paper_id": 96, "heading": "1 Introduction"}} // → {"sentences": [{"id": 501, "sort": 1, "content": "…", "separator_before": ""}, …]} {"name": "sentence_update", "arguments": { "paper_id": 96, "sentence_id": 501, "content": "改写后的这一句。" }} // → 只改这一句,其余句子 id 不变,挂在它们身上的引用不受影响 ``` ### 4.4 保持术语一致 ```jsonc {"name": "sentence_search", "arguments": {"keyword": "洪水损失", "limit": 20}} // → 全库已写过的相关句子(带 paper_id / sentence_id),用来对齐说法 ``` ### 4.5 换模板(重塑结构但不丢正文) ```jsonc {"name": "paper_update", "arguments": {"paper_id": 96, "template_id": 3}} // → {"template_changed": true, ...} {"name": "paper_document", "arguments": {"paper_id": 96, "format": "json", "include_empty": true}} // → {"paragraphs": [{"position": 10, "heading": "摘要", "matched": true, ...}, // {"position": 70, "matched": false, ...}]} ← 新模板没有的位置仍在,标记未匹配 ``` ### 4.6 从零建一套模板 ```jsonc {"name": "field_list", "arguments": {"keyword": "方法", "page_size": 20}} {"name": "field_create", "arguments": {"name": "8. Limitations", "level": 1, "font_size": 12, "font_color": "#1F1F1F"}} {"name": "template_create", "arguments": { "name": "期刊 A 模板", "abstract": "投期刊 A 用", "field_ids": [1, 2, 6, 9, 14, 18] }} {"name": "paper_create", "arguments": {"title": "新论文", "template_id": 4}} ``` --- ### 4.7 文献:查重 → 录入 → 引用 → 复查 ```jsonc // 1) 先查库里有没有(DOI / 题名 / 作者都能搜) {"name": "reference_list", "arguments": {"keyword": "10.1000/xyz"}} // 2) 没有就录;一次一批更省事(重复的会自动跳过,坏的逐条报告,不连累其它条) {"name": "reference_import", "arguments": {"references": [ {"type": "journal-article", "title": "A flood study", "container_title": "J. Hydrol.", "publication_year": 2023, "volume": "61", "issue": "2", "pages": "1-18", "doi": "10.1000/xyz", "authors": [{"name": "Smith, John"}]}, {"type": "book", "title": "另一本书", "publisher": "某出版社", "publication_year": 2019, "authors": [{"name": "张三"}]} ]}} // → {"created":[{"id":42,…},{"id":43,…}], "skipped":[{"title":"…","existing_id":7}], "failed":[…]} // 3) 写正文时引用它(citations 里给 reference_id 和引用的原话) {"name": "paragraph_write", "arguments": { "paper_id": 96, "heading": "2 Related Work", "sentences": [{"content": "已有研究指出……", "citations": [{"quote": "引用的原话", "reference_id": 42}]}] }} // 4) 改稿前先看影响面:这条文献被哪些句子用了 {"name": "reference_citations", "arguments": {"reference_id": 42}} // → {"total":2, "items":[{"paper_id":96,"position":30,"paragraph":"2 Related Work","sentence_id":512,"quote":"引用的原话"}]} ``` 删文献时如果它还被引用,会被拒绝并报出「(N 处引用)」——先按上面第 4 步找到那些句子、 用 `sentence_update(citations=[])` 摘掉引用,再删。 ### 4.8 插图:把一张图放进论文 ```jsonc // 1) 传图(给字节的 base64;模型手里是文件路径时先读出字节) {"name": "image_upload", "arguments": { "data_base64": "iVBORw0KGgo…", "caption": "图 3 惯性—冲量相空间", "width": "70%" }} // → {"key": "…", "url": "/api/images/2026/09/….png", // "sentence": {"content": "![图 3 …](…){width=70%}", "line_break_before": true, "formula_align": "center"}} // 2) 原样写进去(也可以塞进 paper_write 的 paragraphs[].sentences 里) {"name": "sentence_add", "arguments": { "paper_id": 96, "heading": "4.4 技术惯性量化", "content": "![图 3 惯性—冲量相空间](/api/images/2026/09/….png){width=70%}", "line_break_before": true }} // 3) 读回来确认它在自己的一行上 {"name": "paragraph_get", "arguments": {"paper_id": 96, "heading": "4.4 技术惯性量化"}} ``` 要点: - **同一张图传两次是同一个对象**:键是内容的 SHA-256,所以重复上传不会堆出副本,也不会换地址。 - **图注写在方括号里**,网页端显示为图下那行字;`width` 不给就按原尺寸(最多不超过栏宽)。 - 想让图**跟着一句话走**(行内小图,而不是独占一行的插图),把它拼进那句话里就行: `"回归结果见 ![小图](/api/images/…) 的右panel。"`。 - MCP 只做上传这一半。图是**通过 API(`/api/images/…`)读**的:句子存的是同源相对路径, 局域网和以后的公网地址都能用,桶也不必公开。 ## 5. 返回值与错误约定 - **成功**:`content[0].text` 是一段 JSON 字符串。例如 `paper_list` 返回 `{"items": [...], "total": 1, "page": 1, "page_size": 20, "pages": 1}`。 - **失败**:`isError: true`,`text` 是人话,例如: | 场景 | 消息 | |---|---| | 找不到 | `论文 999 不存在` | | 标题对不上 | `模板里没有标题“X”。可用标题:0 Abstract(10)、1 Introduction(20)…` | | 标题有二义 | `标题“X”匹配到多个段落(…),请写完整标题或直接用 position` | | 删除模板被拒 | `以下模板正被论文使用,请先用 paper_update 给论文切换模板:“…”(2 篇论文)` | | 删字段被拒 | `以下字段正被模板使用,请先用 template_update 从模板里移除:“…”(1 个模板)` | | 删论文没确认 | `…确认无误后请带 confirm=true 重新调用` | | 删被引用的文献 | `以下文献正被论文引用,请先在段落里移除对应引用:“…”(2 处引用)` | | 引用了不存在的文献 | `参考文献不存在:42` | | 给文献打了不存在的标签 | `标签不存在:9` | | 标签重名 | `标签「必读」已存在` | | 文献字段不合法 | `文献不合法(type):文献类型只能是:journal-article、book、…` | | 参数写错 | SDK 层的参数校验错误(列出哪个字段不合法) | 所有消息都写成"哪里错 + 怎么修",因为读它的是模型,它据此重试一次就能成功。 - **段落拼接**:`separator_before` 是服务端算好的段间分隔符(`""` 或一个空格)。 客户端打印 `separator_before + content`,**自己不要再加空格**。 --- ## 6. 设计说明(为什么是这样) **三个入口,一个领域层。** REST API、MCP 服务、seed 脚本最终都调用 `app.crud`, 校验都过 `app.schemas`。MCP 层不重新实现任何业务规则——在 CRUD 层修的规则, REST 和 MCP 同时生效。这让"网页里看到的"和"AI 写进去的"永远一致。 **工具结果是手搓的紧凑 JSON,不是 schema dump。** 工具结果按 token 计费, `PaperRead.model_dump()` 会把 `created_at`/`updated_at`/四个计数字段塞进每一行。 所以 `*_row` 只挑模型真正要读的字段,`clean()` 把 `None` 全部丢掉。 **段落按 position 存储,但工具接受 heading。** `paper_sentence` 记住"我在第 7 段" (`paper_template_filed_sort`),这是文档渲染需要的、也是换模板不丢正文的原因。 但没人知道"1. Introduction"恰好是 `sort = 20`,所以工具用 heading 也能定位, 由服务端翻译。两者都接受,冲突时以 `position` 为准。 **切句是显式选项,不是默认行为。** 项目原则是"编辑器里一行就是一句, 写入路径不切任何文本"(见 `docs/OVERVIEW.md`)。只有 `text` + `split` 这条路会切, 默认还是 `line`。已存文本永远不会被重新切分。 **换行是"要求"出来的,不是猜出来的。** `line_break_before` 只在被明确写出来时才设: `text` 里换了一行不等于要另起一行(模型把一段话折成三行是常事),所以工具不从这里推断。 唯一的例外是 display 公式和"整句只有一张图"的插图——页面渲染和 `paper_document` 的 `text` 都让它们独占一行。这两条规则在 `frontend/src/utils/rich.ts` 和 `app/mcp/support.py` 里各写了一遍 (一个 TypeScript、一个 Python),**改一处必须改另一处**,否则网页和工具结果就会在 "哪一行是哪一行"上不一致。冒烟测试里各有一项盯着它们。 **句子的字段从 payload schema 里读出来,不手抄。** `app/mcp/support.py` 的 `SENTENCE_FIELDS` 直接取自 `app.schemas.paper.SentenceInput`,写入路径用 `SentenceCreate(**item.model_dump())` 整体展开。这条改动是有代价换来的:`line_break_before` 和 `formula_align` 两次都是"后端加了列、网页能用、REST 能存,MCP 静默丢掉"—— 调用成功、字段不见,是最难查的一类错。现在只剩一处需要人工同步:在 `app/mcp/specs.py` 里声明字段,而 `smoke_mcp.py` 的第一步会比对 `SentenceInput` 与 `SentenceSpec` 的字段集合,漏了就红。 **删除要二次确认。** `paper_delete` 第一次调用必定被拒并说明后果, 因为一次误删会连带整篇的句子和引用,而这在 MCP 里没有回收站。 **结果不带结构化输出。** 工具用 `structured_output=False` 注册: 返回 `-> str` 时 SDK 会自动包一层 `{"result": ...}` 并把同一份 JSON 同时放进 `structuredContent` 和 `content`,一半客户端只读其中一个—— 不如统一成文本,所有客户端都读得到。 --- ## 7. 与 REST API 的对照 | 能力 | REST | MCP | |---|---|---| | 列论文 | `GET /api/papers` | `paper_list` | | 建论文 | `POST /api/papers` | `paper_create` | | 换模板 | `PATCH /api/papers/{id}` | `paper_update(template_id=…)` | | 读全文 | `GET /api/papers/{id}/document` | `paper_document` | | 读一段 | `GET /api/papers/{id}/paragraphs/{sort}` | `paragraph_get` | | 整段重写 | `PUT /api/papers/{id}/paragraphs/{sort}` | `paragraph_write` | | 加一句 | `POST /api/papers/{id}/sentences` | `sentence_add` | | 改一句 | `PATCH /api/papers/{id}/sentences/{id}` | `sentence_update` | | 搜句子 | —(MCP 专有) | `sentence_search` | | 建模板 | `POST /api/templates` | `template_create` | | 字段库 | `/api/templates/titles` | `field_*` | | 列/搜文献 | `GET /api/references` | `reference_list` | | 建文献 | `POST /api/references` | `reference_create` | | 改文献 | `PATCH /api/references/{id}` | `reference_update` | | 删文献 | `DELETE /api/references/{id}` | `reference_delete` | | 谁引用了它 | `GET /api/references/{id}/citations` | `reference_citations` | | 文献标签 | `/api/reference-tags` | `reference_tag_*` | | 传图 | `POST /api/images`(multipart)| `image_upload`(base64)| | 看图 | `GET /api/images/{key}` | —(句子里的地址由页面/浏览器直接取)| MCP 独有:`paper_outline`(写前看骨架)、`paper_write` / `paper_write_text`(批量写入)、 `paragraph_move`、`sentence_search`。 --- ## 8. 排障 | 现象 | 原因 / 处理 | |---|---| | 客户端显示连不上、工具列表为空 | 先跑 `--check`;多数是数据库不通(`backend/.env` 的 `DB_*`) | | HTTP 返回 401 | 口令没带或不对,检查 `Authorization: Bearer ` | | HTTP 返回 421 | 绑定了非 127.0.0.1 但没走本次启动的 DNS-rebinding 关闭逻辑——确认用的是本项目入口,别包了一层反向代理改 Host | | DSH 里工具不出现 | 检查 cordis.patch.yml 的条目是否写在 `insert:` 里;`failOnStartupError: false` 会把启动期连接失败吞掉,看 dsh-web 日志确认 | | 工具调用超时 | DSH/Codex 侧加大 `toolCallTimeoutMs` / `tool_timeout_sec`;`paper_write_text` 写整篇会慢一些 | | k3s 里连不上 | `kubectl -n paper-doc get pods` 看是否 Ready;`/readyz` 返回 503 说明 TiDB 不通(`kubectl -n paper-doc logs deploy/paper-doc-mcp`) | | 改了代码但行为没变 | 镜像 tag 没换:`imagePullPolicy: IfNotPresent` 会继续用节点上缓存的同名镜像,换个 tag 重新构建 | | `image_upload` 报"图片存储还没有配置好" | 缺 `MINIO_ENDPOINT` / `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY`。本机看 `backend/.env`;集群里看 `paper-doc-config`(端点是 `http://minio.minio.svc.cluster.local:9000`,不是宿主机的 `:30090`)与 `paper-doc-secrets` | | `image_upload` 报"连不上对象存储" | MinIO 不通或凭证不对:`kubectl -n minio get pods`,再用同一组凭证 `mc`/`aws s3` 试一次 `PutObject` | | 日志里出现非 JSON 的 stdout 输出 | 不要在这个进程里 `print`——stdio 传输下会污染协议流(本项目的诊断都走 stderr) |