ebaf9e558b
Two things the editor gained and MCP could not do, both because the tool layer
had been told about the domain's columns by hand.
**A figure.** Bytes go to MinIO and the sentence keeps a Markdown address, so a
picture is ordinary text — which means the writing tools already carry it, and
the only half a model cannot do is the upload: it has bytes and no way to send
multipart. `image_upload` takes base64 and answers with the URL, the Markdown
and the *sentence object* the editor produces when a picture is dropped in, so a
figure is written by putting that object into `sentences` unchanged. It does not
fetch a URL the caller names: a service inside the cluster that will GET any
address it is handed is an SSRF primitive aimed at everything beside it.
The width argument is the reader's rule or it is refused. `{width=70%}` is
parsed by `frontend/src/utils/rich.ts`, and a value it cannot read is not an
error there — the picture just prints at its natural size. A size that silently
does not apply is worse than a refusal, so the syntax and the range (pixels
1–4000, per cent 1–100) are mirrored in `app/mcp/tools/images.py`, with the
usual comment naming the other side.
`paragraph_text` also had to learn what a figure is: a sentence holding nothing
but an image is a 插图 — the view prints it on its own line with the brackets'
text as its caption — and the text a tool hands back broke lines around a
display formula but not around a picture. Same rule as `figureOf`, same pair of
implementations, same warning about changing both.
**A formula's alignment.** `paper_sentence.formula_align` reached the editor and
the REST API and stopped there: `SentenceSpec` had no such field, so a model that
sent one got a successful call and a centred formula. The column is now declared,
carried through every write path and reported by every read path.
That is the second column lost the same way, so the fix is structural rather
than another two edits. `SENTENCE_FIELDS` is read from
`app.schemas.paper.SentenceInput` instead of written out, the payload is built
by one `sentence_payload()`, and the three append paths spread
`SentenceCreate(**item.model_dump())` rather than copying fields. One edit
remains — declaring the field in `specs.py` — and smoke_mcp.py's first step
compares the two field sets, so forgetting it now fails the suite instead of
losing the field. `sort` is declared too, which it never was: a model that sent
one had it dropped in silence.
smoke_mcp.py: 99 checks to 119. The figure step uploads a real 1x1 GIF (the same
bytes twice, and the key is the same object), writes the returned sentence as it
came back, checks the paragraph prints it alone on its line and that an image
inside a sentence does not break the line, and takes the four refusals — not a
picture, an unparseable size, an out-of-range one, not base64. The alignment step
writes a right-aligned formula, moves the sentence to left on its own, and takes
the paragraph to another position to prove the setting travels with it.
Deployed as v6, and the pod now carries MINIO_ENDPOINT (the in-cluster Service)
plus the two credential keys from the Secret; without them the image tool answers
with the missing variable names and every writing tool still works.
260 lines
9.9 KiB
Python
260 lines
9.9 KiB
Python
"""Sentence tools (语句): the smallest unit the paper model stores.
|
||
|
||
One row is one sentence, and nothing about the writing path ever re-splits it —
|
||
the writer decides where a sentence ends (see ``docs/OVERVIEW.md``). That makes
|
||
these the tools to reach for when a paragraph is *almost* right: rewriting the
|
||
whole paragraph to fix one line would relabel every sentence id in it, and an
|
||
id is what a citation points at.
|
||
|
||
:func:`sentence_search` reads across papers instead of within one, because the
|
||
job it serves is consistency: a model that has already written "flood damage"
|
||
in one paper should not start writing "GUL" in the next.
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from typing import Annotated, Any
|
||
|
||
from mcp.server.mcpserver import MCPServer
|
||
from pydantic import Field
|
||
|
||
from app.crud import paper as paper_crud
|
||
from app.mcp import support as s
|
||
from app.mcp.specs import CitationSpec, FormulaAlign
|
||
from app.mcp.tools.registry import mcp_tool
|
||
from app.models import Paper
|
||
from app.schemas.paper import CitationInput, SentenceCreate, SentenceUpdate
|
||
|
||
|
||
def register(server: MCPServer) -> None:
|
||
"""Register every sentence tool on ``server``."""
|
||
|
||
@mcp_tool(server, title="列出句子")
|
||
def sentence_list(
|
||
paper_id: Annotated[int, Field(description="论文 id")],
|
||
position: Annotated[
|
||
int | None, Field(description="只看某一段;不传则返回全文句子")
|
||
] = None,
|
||
heading: Annotated[
|
||
str | None, Field(description="只看某个标题下的句子")
|
||
] = None,
|
||
include_empty: Annotated[
|
||
bool, Field(description="是否包含空句子(只挂引用的行)")
|
||
] = False,
|
||
) -> str:
|
||
"""列出论文里的句子,带句子 id、所属段落和引用。"""
|
||
with s.session() as db:
|
||
paper = s.paper_or_fail(db, paper_id)
|
||
target = (
|
||
s.resolve_position(paper, position=position, heading=heading)
|
||
if (position is not None or heading is not None)
|
||
else None
|
||
)
|
||
|
||
rows = [
|
||
row
|
||
for row in paper.sentences
|
||
if (target is None or row.paper_template_filed_sort == target)
|
||
and (include_empty or row.content)
|
||
]
|
||
rows.sort(key=lambda row: (row.paper_template_filed_sort, row.sort, row.id))
|
||
|
||
return s.dumps(
|
||
{
|
||
"paper_id": paper.id,
|
||
"paper_title": paper.title,
|
||
"total": len(rows),
|
||
"items": [
|
||
{
|
||
**s.sentence_row(row),
|
||
"heading": _heading_at(paper, row.paper_template_filed_sort),
|
||
}
|
||
for row in rows
|
||
],
|
||
}
|
||
)
|
||
|
||
@mcp_tool(server, title="加一句")
|
||
def sentence_add(
|
||
paper_id: Annotated[int, Field(description="论文 id")],
|
||
content: Annotated[str, Field(description="句子正文;会折叠成一行")],
|
||
position: Annotated[
|
||
int | None, Field(description="加到哪一段;与 heading 二选一")
|
||
] = None,
|
||
heading: Annotated[str | None, Field(description="加到哪个标题下")] = None,
|
||
citations: Annotated[
|
||
list[CitationSpec] | None, Field(description="这句引用了哪些文献")
|
||
] = None,
|
||
line_break_before: Annotated[
|
||
bool,
|
||
Field(
|
||
description=(
|
||
"这一句前面另起一行(默认 false):公式、分条列举、作者行用得上。"
|
||
"break 会顶掉句间的空格"
|
||
)
|
||
),
|
||
] = False,
|
||
formula_align: Annotated[
|
||
FormulaAlign,
|
||
Field(description="display 公式怎么排:center(默认)/ left / right"),
|
||
] = "center",
|
||
sort: Annotated[
|
||
int | 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)
|
||
sentence = paper_crud.append_sentence(
|
||
db,
|
||
paper,
|
||
SentenceCreate(
|
||
paper_template_filed_sort=field_sort,
|
||
content=content,
|
||
line_break_before=line_break_before,
|
||
formula_align=formula_align,
|
||
citations=_citations(citations or []),
|
||
sort=sort,
|
||
),
|
||
)
|
||
return s.dumps(
|
||
{
|
||
"paper_id": paper.id,
|
||
"position": field_sort,
|
||
"heading": _heading_at(paper, field_sort),
|
||
"sentence": s.sentence_row(sentence),
|
||
}
|
||
)
|
||
|
||
@mcp_tool(server, title="改一句")
|
||
def sentence_update(
|
||
paper_id: Annotated[int, Field(description="论文 id")],
|
||
sentence_id: Annotated[int, Field(description="句子 id(见 sentence_list)")],
|
||
content: Annotated[str | None, Field(description="新正文;不传则不改")] = None,
|
||
position: Annotated[
|
||
int | None, Field(description="把这句话移到另一段;不传则不动")
|
||
] = None,
|
||
sort: Annotated[
|
||
int | None, Field(description="段内排序值;不传则不动")
|
||
] = None,
|
||
line_break_before: Annotated[
|
||
bool | None,
|
||
Field(description="这一句是否另起一行;不传则不动,false 表示取消换行"),
|
||
] = None,
|
||
formula_align: Annotated[
|
||
FormulaAlign | None,
|
||
Field(description="display 公式怎么排;不传则不动"),
|
||
] = None,
|
||
citations: Annotated[
|
||
list[CitationSpec] | None,
|
||
Field(description="引用整组替换;传 [] 表示清空引用"),
|
||
] = None,
|
||
) -> str:
|
||
"""修改一句话的正文、所属段落、排序、换行、公式对齐或引用(引用是整体替换)。"""
|
||
if (
|
||
content is None
|
||
and position is None
|
||
and sort is None
|
||
and line_break_before is None
|
||
and formula_align is None
|
||
and citations is None
|
||
):
|
||
s.fail("没有给出任何要修改的内容")
|
||
|
||
with s.session() as db:
|
||
paper = s.paper_or_fail(db, paper_id)
|
||
sentence = s.sentence_or_fail(paper, sentence_id)
|
||
updated = paper_crud.update_sentence(
|
||
db,
|
||
paper,
|
||
sentence,
|
||
SentenceUpdate(
|
||
content=content,
|
||
paper_template_filed_sort=position,
|
||
sort=sort,
|
||
line_break_before=line_break_before,
|
||
formula_align=formula_align,
|
||
citations=None if citations is None else _citations(citations),
|
||
),
|
||
)
|
||
return s.dumps(
|
||
{
|
||
"paper_id": paper.id,
|
||
"sentence": s.sentence_row(updated),
|
||
}
|
||
)
|
||
|
||
@mcp_tool(server, title="删一句")
|
||
def sentence_delete(
|
||
paper_id: Annotated[int, Field(description="论文 id")],
|
||
sentence_id: Annotated[int, Field(description="句子 id")],
|
||
) -> str:
|
||
"""删除一句话,连同它挂着的引用。"""
|
||
with s.session() as db:
|
||
paper = s.paper_or_fail(db, paper_id)
|
||
sentence = s.sentence_or_fail(paper, sentence_id)
|
||
snapshot = s.sentence_row(sentence)
|
||
paper_crud.delete_sentence(db, paper, sentence)
|
||
return s.dumps(
|
||
{
|
||
"paper_id": paper.id,
|
||
"deleted": snapshot,
|
||
}
|
||
)
|
||
|
||
@mcp_tool(server, title="搜索句子")
|
||
def sentence_search(
|
||
keyword: Annotated[str, Field(description="要搜索的字词")],
|
||
paper_id: Annotated[
|
||
int | None, Field(description="只在这篇论文里搜;不传则全库搜")
|
||
] = None,
|
||
limit: Annotated[int, Field(description="最多返回多少条")] = 30,
|
||
) -> str:
|
||
"""跨论文搜索已经写过的句子,用来保持术语和说法一致。"""
|
||
if not keyword.strip():
|
||
s.fail("keyword 不能为空")
|
||
|
||
with s.session() as db:
|
||
rows = paper_crud.search_sentences(
|
||
db,
|
||
keyword=keyword,
|
||
paper_id=paper_id,
|
||
limit=max(1, min(int(limit), 200)),
|
||
)
|
||
return s.dumps(
|
||
{
|
||
"keyword": keyword,
|
||
"total": len(rows),
|
||
"items": [
|
||
{
|
||
"paper_id": sentence.paper_id,
|
||
"paper_title": title,
|
||
"sentence_id": sentence.id,
|
||
"position": sentence.paper_template_filed_sort,
|
||
"content": sentence.content,
|
||
}
|
||
for sentence, title in rows
|
||
],
|
||
}
|
||
)
|
||
|
||
|
||
# --- helpers -----------------------------------------------------------------
|
||
|
||
|
||
def _citations(items: list[Any]) -> list[CitationInput]:
|
||
"""Convert the tool-level citation spec into the project's own payload."""
|
||
return [
|
||
CitationInput(quote=item.quote, reference_id=item.reference_id)
|
||
for item in items
|
||
]
|
||
|
||
|
||
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
|