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
+59 -4
View File
@@ -256,6 +256,10 @@ def sentence_row(sentence: Any, *, separator: str | None = None) -> dict:
"position": sentence.paper_template_filed_sort,
"sort": sentence.sort,
"content": sentence.content,
# Reported so a writer can see where the lines fall before deciding to
# move one: a paragraph read back without this flag looks like prose
# that happens to have no spaces in it.
"line_break_before": sentence.line_break_before,
"citations": [citation_row(item) for item in sentence.citations],
}
if separator is not None:
@@ -277,6 +281,21 @@ def paragraph_row(paragraph: ParagraphRead, *, preview: int = 80) -> dict:
}
#: A formula the paper view sets on a line of its own: ``$$…$$`` or ``\[…\]``.
#:
#: This is the same rule as ``hasDisplayMath`` in ``frontend/src/utils/math.ts``,
#: written twice because the view is TypeScript and this is Python. The two must
#: agree, or a tool result and the page a writer is looking at would disagree
#: about where the lines are — which is the one thing this module exists to
#: prevent. Change one, change the other.
_DISPLAY_MATH = re.compile(r"\$\$[\s\S]+?\$\$|\\\[[\s\S]+?\\\]")
def _is_display(sentence: Any) -> bool:
"""Whether this sentence is a display formula — a block, not a run of text."""
return bool(_DISPLAY_MATH.search(sentence.content))
def paragraph_text(
paragraph: ParagraphRead,
*,
@@ -289,6 +308,14 @@ def paragraph_text(
belongs at each seam, so a tool result and the paper view agree on where
the spaces go. Nothing here adds spacing of its own.
A line break is printed where the model asked for one, and around a display
formula — the paper view renders ``$$…$$`` as a block, so the lines on
either side of it are line boundaries there too. A break *replaces* the
separator rather than joining it: the new line already separates the two
sentences, and a space as well would indent the line below by one blank.
The first sentence of a paragraph is never preceded by a break, because
there is nothing above it to break from.
A marker's number comes from ``index_by_citation`` — the citation's *work*
number as the whole document assigned it, not its position in this sentence —
so what is printed in the text matches the 参考文献 list it points at. Read
@@ -296,8 +323,15 @@ def paragraph_text(
falls back to the citation's place in the sentence.
"""
parts: list[str] = []
previous_block = False
for sentence in paragraph.sentences:
parts.append(sentence.separator_before + sentence.content)
block = _is_display(sentence)
if parts and (sentence.line_break_before or block or previous_block):
parts.append("\n")
else:
parts.append(sentence.separator_before)
parts.append(sentence.content)
previous_block = block
if citations and sentence.citations:
numbers = [
str(
@@ -592,6 +626,8 @@ def sentence_inputs(items: Sequence[Any], *, default_split: str = "line") -> lis
* ``"A sentence."`` — the common case;
* ``{"content": "...", "citations": [{"quote": "...", "reference_id": 3}]}``;
* ``{"content": "$$ y = ax + b $$", "line_break_before": true}`` — a block
that starts a line of its own;
* ``{"text": "one\\ntwo", "split": "line"}`` — a block to be cut.
Every path ends in :class:`~app.schemas.paper.SentenceInput`, so the
@@ -621,15 +657,34 @@ def sentence_inputs(items: Sequence[Any], *, default_split: str = "line") -> lis
)
for citation in (item.get("citations") or [])
]
line_break = bool(item.get("line_break_before", False))
if item.get("content") is not None:
out.append(SentenceInput(content=str(item["content"]), citations=citations))
out.append(
SentenceInput(
content=str(item["content"]),
line_break_before=line_break,
citations=citations,
)
)
continue
if item.get("text") is not None:
mode = item.get("split") or default_split
for piece in split_text(str(item["text"]), mode):
out.append(SentenceInput(content=piece, citations=citations))
pieces = split_text(str(item["text"]), mode)
for offset, piece in enumerate(pieces):
# A break asked for on a *block* belongs to its first sentence:
# "this block starts a new line". The pieces after it are
# separated by whatever the split found, and flagging them too
# would turn a paragraph the writer wrapped across three lines
# into three lines of the paper.
out.append(
SentenceInput(
content=piece,
line_break_before=line_break and offset == 0,
citations=citations,
)
)
continue
fail("句子对象需要有 content 或 text 字段")