9f2bbe50eb
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.
296 lines
12 KiB
Python
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),
|
|
}
|