backend: let a model ask for a line break, and read the 参考文献 list back

The paper model gained two things while the MCP layer was not looking, and
both were invisible from a tool call.

`paper_sentence.line_break_before` — the flag a paragraph needs so a formula,
a list of items or an author line can start a line of its own — was not in
`SentenceSpec`, and `sentence_inputs` dropped it on the floor: a model could
write the field, watch the call succeed, and get prose back. It is now part of
every write path (`paragraph_write`, `paper_write`, `sentence_add`,
`sentence_update`) and of every read path (`sentence_row` reports it, so a
model can see the lines before moving one). Two bugs fell out of doing it
properly:

* `paragraph_move` rebuilt its sentences without the flag, so moving a
  paragraph that carried a formula turned it into prose. It also passed the
  *source* sorts through, which interleaved the moved sentences with the
  target's own — the merged paragraph read in an order neither writer wrote.
  Both are fixed; the tool now appends, as its own description promised.
* `document_text` printed a formula run into the sentence before it. The paper
  view renders `$$…$$` as a block, so the seam rules are now the same in both
  places, with a comment on each side naming the other.

`PaperDocumentRead.references` and `reference_style` — the per-work 参考文献
list the backend now assembles and formats — were reachable over REST but not
over MCP: `paper_document(format="json")` returned citations and nothing to
point them at, even though docs/MCP.md already described the list. The json
form now carries the entries (index, reference_id, text, missing, citations)
and the style name, so a model quotes the bibliography instead of assembling a
second one out of the same fields.

smoke_mcp.py grows from 76 checks to 99 over two new steps — the line-break
step pins the display-formula rule, the marker toggle and the moving case; the
bibliography step cites one work from two sentences and checks that the text,
the entry and both markers agree on one number.
This commit is contained in:
2026-09-23 11:49:39 +08:00
parent 960450f744
commit 9f2bbe50eb
11 changed files with 483 additions and 34 deletions
+49 -9
View File
@@ -1,13 +1,13 @@
# MCP 服务(paper-doc-mcp)
把 paper-doc 的论文、段落、句子、模板、字段库能力暴露成 **Model Context Protocol** 工具,
把 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 客户端跑 76 项检查、覆盖 41/41 个工具,stdio 与 HTTP 都过)
- 冒烟测试:`backend/scripts/smoke_mcp.py`(真 MCP 客户端跑 99 项检查、覆盖 41/41 个工具,stdio 与 HTTP 都过)
- 工具数量:**41 个**,按 `paper_` / `paragraph_` / `sentence_` / `template_` / `field_` / `reference_` / `reference_tag_` 七组前缀
- 协议:MCP 2024-11-05 ~ 2025-11-25(官方 Python SDK `mcp>=2.2,<3` 协商)
- 传输:`stdio`(本地拉起)与 `streamable-http`(远程连接,支持 Bearer 口令),另兼容旧 `sse`
@@ -98,10 +98,12 @@ cd /data/project/paper/backend
.venv/bin/python scripts/smoke_mcp.py --url http://127.0.0.1:8931/mcp --token 你的口令 # 连已有的 HTTP 服务
```
同一个套件 **76 项检查**跑两种传输,覆盖 21 个步骤:建论文 → 看骨架 → 按标题写段落 →
同一个套件 **99 项检查**跑两种传输,覆盖 23 个步骤:建论文 → 看骨架 → 按标题写段落 →
定位失败时列出候选标题 → 读段落/追加带引用的句子 → 只改一句 → 删一句 → 整篇一次写入 →
读全文 → 跨论文搜索 → 搬段落 → 清空段落 → 字段库增删改 → 建/改模板 → 换模板后正文不丢 →
文献库增删改查与批量导入 → 引用守卫(被引用的文献删不掉)→ 删模板被拒 → 删论文要确认 → 清理。写真实数据,结束时自己删干净。
读全文 → 跨论文搜索 → **另起一行**(公式独行、标记开关、搬段落时跟着走)→ **参考文献表**
(一处引用一行、一部文献一条、正文编号与表号同号)→ 搬段落 → 清空段落 → 字段库增删改 →
建/改模板 → 换模板后正文不丢 → 文献库增删改查与批量导入 → 引用守卫(被引用的文献删不掉)→
删模板被拒 → 删论文要确认 → 清理。写真实数据,结束时自己删干净。
---
@@ -270,10 +272,10 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
| 工具 | 作用 | 关键参数 |
|---|---|---|
| `paragraph_list` | 段落骨架 + 预览 | `paper_id`、`include_empty?` `preview?` |
| `paragraph_get` | 读一段:拼好的正文、逐句 id/内容/引用/分隔符 | `paper_id`、`position?` `heading?` |
| `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?` |
| `paragraph_move` | 整段搬到另一个位置(**接在目标段已有内容之后**,换行与引用一起搬过去) | `paper_id`、`position?` `heading?`、`target_position?` `target_heading?` |
定位规则:`position` 直接采用(包括模板没定义的位置,会以"未设定"渲染);
`heading` 按模板解析,忽略编号、空格和大小写,所以下面三种写法等价:
@@ -292,11 +294,38 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
| 工具 | 作用 | 关键参数 |
|---|---|---|
| `sentence_list` | 列句子(可只列某段) | `paper_id`、`position?` `heading?` `include_empty?` |
| `sentence_add` | 段尾追加一句(可带引用) | `paper_id`、`content`、`position?` `heading?` `citations?` `sort?` |
| `sentence_update` | 改正文 / 改所属段 / 改排序 / 整组换引用 | `paper_id`、`sentence_id`、`content?` `position?` `sort?` `citations?` |
| `sentence_add` | 段尾追加一句(可带引用) | `paper_id`、`content`、`position?` `heading?` `citations?` `line_break_before?` `sort?` |
| `sentence_update` | 改正文 / 改所属段 / 改排序 / 改换行 / 整组换引用 | `paper_id`、`sentence_id`、`content?` `position?` `sort?` `line_break_before?` `citations?` |
| `sentence_delete` | 删一句(连引用) | `paper_id`、`sentence_id` |
| `sentence_search` | **跨论文搜句子**(保持术语一致) | `keyword`、`paper_id?` `limit?` |
#### 另起一行:公式、分条列举、作者行
一段是**它的句子连排**出来的,所以"不是散文的行"要自己开口。方式是在句子对象上加
`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` 字段,所以搬句子之前能看出哪几句是另起的行。
`text` + `split` 那种整块写法也可以带 `line_break_before`,但它只作用于**切出来的第一句**——
"这一块从新的一行开始"。块里其余几句是接着它的,不是各自另起一行;否则一个换行写了三行的段落
就会被切成三行。
### 3.4 模板 templates(5 个)
模板就是结构:论文的标题是**每次渲染现读模板**得到的,所以改模板会影响所有用它的论文,
@@ -418,6 +447,10 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
> `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` 的标题原样抄下来最稳)。前面没有标题的内容会被丢弃;
一个都没匹配上则整次调用报错,不会写半截。
@@ -565,6 +598,13 @@ REST 和 MCP 同时生效。这让"网页里看到的"和"AI 写进去的"永远
写入路径不切任何文本"(见 `docs/OVERVIEW.md`)。只有 `text` + `split` 这条路会切,
默认还是 `line`。已存文本永远不会被重新切分。
**换行是"要求"出来的,不是猜出来的。** `line_break_before` 只在被明确写出来时才设:
`text` 里换了一行不等于要另起一行(模型把一段话折成三行是常事),所以工具不从这里推断。
唯一的例外是 display 公式——页面渲染和 `paper_document` 的 `text` 都让它独占一行,
这条规则在 `frontend/src/utils/math.ts` 和 `app/mcp/support.py` 里各写了一遍
(一个 TypeScript、一个 Python),**改一处必须改另一处**,否则网页和工具结果就会在
"哪一行是哪一行"上不一致。冒烟测试里有一项专门盯着它。
**删除要二次确认。** `paper_delete` 第一次调用必定被拒并说明后果,
因为一次误删会连带整篇的句子和引用,而这在 MCP 里没有回收站。