Files
paper-doc/backend/app/mcp/specs.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

235 lines
10 KiB
Python

"""The shapes a model may send when it writes.
These are tool-argument models, not domain models: they exist so the JSON
Schema a client receives is precise enough that the model gets the shape right
the first time. Each one is converted into the project's own payload
(:class:`~app.schemas.paper.SentenceInput`,
:class:`~app.schemas.template.TemplateTitlePlacementInput`) before it reaches the CRUD
layer, so the validation rules stay in one place — a citation with a blank
quote is refused here for the same reason the REST API refuses it.
The union types are deliberate. A model writing sentences naturally produces
either plain strings or objects, and refusing one of the two shapes would
produce a retry that costs a whole round trip:
"sentences": ["First sentence.", "Second sentence."]
"sentences": [{"content": "Cited sentence.", "citations": [{"quote": "…"}]}]
"sentences": [{"text": "One long block to be cut.", "split": "sentence"}]
"""
from __future__ import annotations
from typing import Annotated, Literal
from pydantic import BaseModel, Field
#: How a block of text becomes sentences when the caller sent ``text`` instead
#: of an explicit list. See :func:`app.mcp.support.split_text`.
SplitMode = Literal["line", "sentence", "paragraph"]
class CitationSpec(BaseModel):
"""One citation of one sentence."""
quote: Annotated[
str,
Field(description="引用内容,必填;空引用会被拒绝"),
]
reference_id: Annotated[
int | None,
Field(description="参考文献库的编号,暂无库时可省略"),
] = None
class SentenceSpec(BaseModel):
"""One sentence, optionally carrying citations."""
content: Annotated[str, Field(description="句子正文;空白会被折叠成一行")]
line_break_before: Annotated[
bool,
Field(
description=(
"这一句前面另起一行(默认 false)。正文被句子拼成一段,所以公式、"
"分条列举、作者行这类不是散文的行要在这里开口;break 会顶掉句间的空格,"
"不会多印一个空格。display 公式($$…$$ 或 \\[…\\])本来就独占一行,不必设这个"
)
),
] = False
citations: Annotated[
list[CitationSpec],
Field(description="这一段引用了哪些文献"),
] = []
class TextSpec(BaseModel):
"""A block of text to be cut into sentences by the server."""
text: Annotated[str, Field(description="要写入的整段文本")]
split: Annotated[
SplitMode,
Field(description="切句方式:line 一行一句(默认)/ sentence 按句号切 / paragraph 整段一句"),
] = "line"
line_break_before: Annotated[
bool,
Field(
description=(
"这一整块从新的一行开始(默认 false);只作用于切出来的第一句,"
"因为切出来的其余几句是接着它的,不是各自另起一行"
)
),
] = False
citations: Annotated[
list[CitationSpec],
Field(description="整段共用的引用"),
] = []
#: One entry of a paragraph's sentence list — a string, a sentence object, or a
#: block to be cut.
SentenceItem = str | SentenceSpec | TextSpec
class ParagraphSpec(BaseModel):
"""One paragraph to write, addressed by position or by heading."""
position: Annotated[
int | None,
Field(description="段落位置(模板字段的 sort);与 heading 二选一"),
] = None
heading: Annotated[
str | None,
Field(description="段落标题,如 “1. Introduction”;会按模板解析成位置"),
] = None
sentences: Annotated[
list[SentenceItem] | None,
Field(description="句子列表;字符串或对象都可以"),
] = None
text: Annotated[
str | None,
Field(description="整段文本,等价于 sentences 里放一个 {text, split} 对象"),
] = None
split: Annotated[
SplitMode,
Field(description="text 的切句方式;默认 line 一行一句"),
] = "line"
citations: Annotated[
list[CitationSpec],
Field(description="整段共用的引用"),
] = []
class FieldSpec(BaseModel):
"""One placement of a library field inside a template."""
field_id: Annotated[int, Field(description="字段库里的字段 id")]
sort: Annotated[
int,
Field(description="渲染顺序,升序整数;唯一决定段落顺序的就是它"),
]
class ReferenceAuthorSpec(BaseModel):
"""One contributor of one reference."""
name: Annotated[
str,
Field(description="姓名,按引用里要印的样子写,如 “Smith, John” 或 “张三”"),
]
family_name: Annotated[str | None, Field(description="姓")] = None
given_name: Annotated[str | None, Field(description="名")] = None
role: Annotated[
str,
Field(description="角色:author(默认)/ editor / translator / compiler"),
] = "author"
class ReferenceFields(BaseModel):
"""Every bibliographic field, all optional — the shape an update sends.
Nested rather than flattened into the tool signature for one reason that
matters more than tidiness: a nested model keeps ``model_fields_set``, so
the tool can tell "the caller wrote ``note: null``" (clear it) from "the
caller did not mention ``note``" (leave it). Spread across 38 keyword
parameters, every omitted field would arrive as ``None`` and the two cases
would be indistinguishable — the same problem ``paper_update`` solves by
rebuilding its payload from the parameters it was given.
"""
type: Annotated[
str | None,
Field(description="类型:journal-article / book / book-chapter / conference-paper / thesis / patent / standard / report / newspaper-article / web-page / dataset / software / preprint / other"),
] = None
title: Annotated[str | None, Field(description="题名(原文)")] = None
subtitle: Annotated[str | None, Field(description="副题名")] = None
title_translated: Annotated[str | None, Field(description="并列题名/译名")] = None
title_short: Annotated[str | None, Field(description="题名缩写")] = None
container_title: Annotated[str | None, Field(description="期刊/论文集/丛书名")] = None
container_title_short: Annotated[str | None, Field(description="容器名缩写")] = None
series_title: Annotated[str | None, Field(description="丛书名")] = None
series_number: Annotated[str | None, Field(description="丛书号")] = None
edition: Annotated[str | None, Field(description="版次")] = None
volume: Annotated[str | None, Field(description="卷")] = None
issue: Annotated[str | None, Field(description="期")] = None
pages: Annotated[str | None, Field(description="页码,如 123-145")] = None
article_number: Annotated[str | None, Field(description="文章编号")] = None
publisher: Annotated[str | None, Field(description="出版社/机构")] = None
publisher_place: Annotated[str | None, Field(description="出版地")] = None
event_title: Annotated[str | None, Field(description="会议名")] = None
event_place: Annotated[str | None, Field(description="会议地点")] = None
event_date: Annotated[str | None, Field(description="会议日期")] = None
publication_year: Annotated[int | None, Field(description="出版年")] = None
publication_month: Annotated[int | None, Field(description="出版月 1-12")] = None
publication_day: Annotated[int | None, Field(description="出版日 1-31")] = None
accessed_date: Annotated[str | None, Field(description="访问日期 YYYY-MM-DD")] = None
doi: Annotated[str | None, Field(description="DOI,可带 https://doi.org/ 前缀")] = None
isbn: Annotated[str | None, Field(description="ISBN")] = None
issn: Annotated[str | None, Field(description="ISSN")] = None
url: Annotated[str | None, Field(description="网址")] = None
patent_country: Annotated[str | None, Field(description="专利国别")] = None
patent_number: Annotated[str | None, Field(description="专利号")] = None
standard_number: Annotated[str | None, Field(description="标准号")] = None
report_number: Annotated[str | None, Field(description="报告号")] = None
arxiv_id: Annotated[str | None, Field(description="arXiv 编号")] = None
abstract: Annotated[str | None, Field(description="摘要")] = None
keywords: Annotated[str | None, Field(description="关键词")] = None
note: Annotated[str | None, Field(description="备注")] = None
citation_key: Annotated[str | None, Field(description="引用键,如 smith2024flood")] = None
language: Annotated[str | None, Field(description="语言:zh / en / ja / other")] = None
authors: Annotated[
list[ReferenceAuthorSpec] | None,
Field(description="作者列表;给了就是整体替换,顺序即印刷顺序"),
] = None
tag_ids: Annotated[
list[int] | None,
Field(description="标签 id 列表;给了就是整体替换,传 [] 表示清空"),
] = None
class ReferenceSpec(ReferenceFields):
"""The shape a *new* reference arrives in: a type and a title, at least."""
type: Annotated[
str,
Field(description="类型:journal-article(默认)/ book / book-chapter / conference-paper / thesis / patent / standard / report / newspaper-article / web-page / dataset / software / preprint / other"),
] = "journal-article"
title: Annotated[str, Field(description="题名(原文),必填")]
authors: Annotated[
list[ReferenceAuthorSpec],
Field(description="作者列表,顺序即印刷顺序"),
] = []
tag_ids: Annotated[list[int], Field(description="标签 id 列表")] = []
__all__ = [
"CitationSpec",
"FieldSpec",
"ParagraphSpec",
"ReferenceAuthorSpec",
"ReferenceFields",
"ReferenceSpec",
"SentenceItem",
"SentenceSpec",
"SplitMode",
"TextSpec",
]