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.
235 lines
10 KiB
Python
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",
|
|
]
|