Files
paper-doc/backend/app/mcp/tools/paragraphs.py
T
govin 9f2bbe50eb 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.
2026-09-23 11:49:39 +08:00

296 lines
12 KiB
Python

"""Paragraph tools (段落): one position of one paper, read and written whole.
A paragraph is not a row — it is a *position*. It exists because the template
defines it or because a sentence occupies it, which is why there is no
``paragraph_create``: writing into an empty position creates the paragraph, and
there is nothing else a create could mean.
Every tool here takes ``position`` or ``heading`` and lets
:func:`app.mcp.support.resolve_position` decide. Writing goes through
:func:`app.crud.paper.replace_paragraph`, the same call the editor's save button
makes, so "replace" always means "this position now holds exactly these
sentences" — never a merge that quietly keeps a line the model meant to drop.
"""
from __future__ import annotations
from typing import Annotated, Literal
from mcp.server.mcpserver import MCPServer
from pydantic import Field
from sqlalchemy.orm import Session
from app.crud import paper as paper_crud
from app.mcp import support as s
from app.mcp.specs import CitationSpec, ParagraphSpec, SentenceItem
from app.mcp.tools.registry import mcp_tool
from app.models import Paper, PaperSentence
from app.schemas.paper import (
ParagraphUpdate,
SentenceCreate,
SentenceInput,
)
def register(server: MCPServer) -> None:
"""Register every paragraph tool on ``server``."""
@mcp_tool(server, title="列出段落")
def paragraph_list(
paper_id: Annotated[int, Field(description="论文 id")],
include_empty: Annotated[
bool, Field(description="是否包含模板里还没有内容的段落(默认包含)")
] = True,
preview: Annotated[
int, Field(description="每段返回多少字的开头预览,0 表示不返回")
] = 80,
) -> str:
"""列出论文的段落骨架:position、标题、句子数、开头预览。改正文前先看这个。"""
with s.session() as db:
paper = s.paper_or_fail(db, paper_id)
document = paper_crud.build_document(db, paper)
items = [
s.paragraph_row(paragraph, preview=preview)
for paragraph in document.paragraphs
if include_empty or paragraph.sentences
]
return s.dumps(
{
"paper_id": paper.id,
"paper_title": paper.title,
"total": len(items),
"items": items,
"warnings": document.warnings,
}
)
@mcp_tool(server, title="读一个段落")
def paragraph_get(
paper_id: Annotated[int, Field(description="论文 id")],
position: Annotated[
int | None, Field(description="段落位置;与 heading 二选一")
] = None,
heading: Annotated[
str | None, Field(description="段落标题,如 “2. Methods”")
] = None,
) -> str:
"""读一个段落:拼好的正文、逐句内容与 id、引用、段间分隔符与换行。"""
with s.session() as db:
paper = s.paper_or_fail(db, paper_id)
field_sort = s.resolve_position(paper, position=position, heading=heading)
paragraph = paper_crud.get_paragraph(db, paper, field_sort)
if paragraph is None:
s.fail(
f"论文 {paper_id} 没有第 {field_sort} 段:模板没有这个位置,也没有内容"
)
return s.dumps(
{
"paper_id": paper.id,
"paper_title": paper.title,
"position": paragraph.paper_template_filed_sort,
"heading": paragraph.name,
"matched": paragraph.matched,
"text": s.paragraph_text(paragraph),
"sentences": [
s.sentence_row(row, separator=row.separator_before)
for row in paragraph.sentences
],
}
)
@mcp_tool(server, title="写一个段落")
def paragraph_write(
paper_id: Annotated[int, Field(description="论文 id")],
position: Annotated[
int | None, Field(description="段落位置;与 heading 二选一")
] = None,
heading: Annotated[
str | None, Field(description="段落标题,如 “3. Results”")
] = None,
sentences: Annotated[
list[SentenceItem] | None,
Field(
description=(
"句子数组:字符串、{content, citations} 或 {text, split}。"
"要某一句另起一行(公式、分条列举、作者行),用对象形式加上 "
"line_break_before: true"
)
),
] = None,
text: Annotated[
str | None, Field(description="整段文本;与 sentences 二选一")
] = None,
split: Annotated[
Literal["line", "sentence", "paragraph"],
Field(description="text 的切句方式;默认 line 一行一句"),
] = "line",
citations: Annotated[
list[CitationSpec] | None,
Field(description="整段共用的引用,会补到没有自带引用的句子上"),
] = None,
mode: Annotated[
Literal["replace", "append"],
Field(description="replace=整段覆盖(默认),append=追加到该段末尾"),
] = "replace",
) -> str:
"""写一个段落:按标题或位置定位,整段覆盖或追加。"""
spec = ParagraphSpec(
position=position,
heading=heading,
sentences=sentences,
text=text,
split=split,
citations=citations or [],
)
with s.session() as db:
paper = s.paper_or_fail(db, paper_id)
field_sort = s.resolve_position(paper, position=position, heading=heading)
inputs = s.paragraph_inputs(spec)
return s.dumps(
_write(db, paper, field_sort, inputs, mode, heading_label=heading)
)
@mcp_tool(server, title="清空段落")
def paragraph_delete(
paper_id: Annotated[int, Field(description="论文 id")],
position: Annotated[
int | None, Field(description="段落位置;与 heading 二选一")
] = None,
heading: Annotated[str | None, Field(description="段落标题")] = None,
) -> str:
"""清空一个段落的全部句子。段落本身还在,仍会以空段落渲染。"""
with s.session() as db:
paper = s.paper_or_fail(db, paper_id)
field_sort = s.resolve_position(paper, position=position, heading=heading)
existing = _sentences_at(db, paper, field_sort)
paper_crud.replace_paragraph(
db, paper, field_sort, ParagraphUpdate(sentences=[])
)
return s.dumps(
{
"paper_id": paper.id,
"position": field_sort,
"heading": _heading_at(paper, field_sort),
"deleted_sentences": len(existing),
}
)
@mcp_tool(server, title="移动段落")
def paragraph_move(
paper_id: Annotated[int, Field(description="论文 id")],
position: Annotated[
int | None, Field(description="要搬走的段落位置;与 heading 二选一")
] = None,
heading: Annotated[str | None, Field(description="要搬走的段落标题")] = None,
target_position: Annotated[
int | None, Field(description="搬到哪个位置;与 target_heading 二选一")
] = None,
target_heading: Annotated[
str | None, Field(description="搬到哪个标题下")
] = None,
) -> str:
"""把一个段落的全部句子搬到另一个位置,接在目标段落已有内容之后。"""
with s.session() as db:
paper = s.paper_or_fail(db, paper_id)
source = s.resolve_position(paper, position=position, heading=heading)
target = s.resolve_position(
paper, position=target_position, heading=target_heading
)
if source == target:
s.fail(f"源位置和目标位置都是 {source},没有可搬的内容")
rows = _sentences_at(db, paper, source)
if not rows:
s.fail(f"第 {source} 段没有内容可以搬")
inputs = [
SentenceInput(
content=row.content,
# ``sort`` is deliberately left unset so that
# :func:`app.crud.paper.replace_paragraph` numbers the block
# from the *target's* current maximum. Carrying the old
# numbers over instead would interleave the two paragraphs —
# the moved sentence with ``sort=1`` would sort against the
# target's own sentence with ``sort=1`` — and the merge would
# read in an order neither writer wrote.
line_break_before=row.line_break_before,
citations=list(row.citations),
)
for row in rows
]
paper_crud.replace_paragraph(
db, paper, source, ParagraphUpdate(sentences=inputs, target_sort=target)
)
return s.dumps(
{
"paper_id": paper.id,
"from": {"position": source, "heading": _heading_at(paper, source)},
"to": {"position": target, "heading": _heading_at(paper, target)},
"moved_sentences": len(inputs),
}
)
# --- helpers -----------------------------------------------------------------
def _sentences_at(db: Session, paper: Paper, field_sort: int) -> list[PaperSentence]:
"""The stored sentences of one paragraph, in render order."""
return sorted(
(row for row in paper.sentences if row.paper_template_filed_sort == field_sort),
key=lambda row: (row.sort, row.id),
)
def _heading_at(paper: Paper, field_sort: int) -> str | None:
"""What the paper's template calls this position, if it names it at all."""
for item in s.heading_index(paper):
if item["position"] == field_sort:
return str(item["heading"])
return None
def _write(
db: Session,
paper: Paper,
field_sort: int,
inputs: list[SentenceInput],
mode: str,
*,
heading_label: str | None,
) -> dict:
"""Apply one paragraph write and describe what happened.
``append`` goes through :func:`app.crud.paper.append_sentence` one sentence
at a time — the same call ``POST /papers/{id}/sentences`` makes — rather
than read-modify-write, so two sentences appended in one request cannot
overwrite each other's ``sort``.
"""
if mode == "append":
for item in inputs:
paper_crud.append_sentence(
db,
paper,
SentenceCreate(
paper_template_filed_sort=field_sort,
content=item.content,
line_break_before=item.line_break_before,
citations=item.citations,
sort=item.sort,
),
)
else:
paper_crud.replace_paragraph(
db, paper, field_sort, ParagraphUpdate(sentences=inputs)
)
return {
"paper_id": paper.id,
"position": field_sort,
"heading": _heading_at(paper, field_sort) or heading_label,
"mode": mode,
"sentences": len(inputs),
"chars": sum(len(item.content) for item in inputs),
}