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.
270 lines
12 KiB
Python
270 lines
12 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"]
|
|
|
|
#: Where a display formula sits on its line. Spelled out here rather than as a
|
|
#: plain ``str`` so the JSON Schema a client receives carries the three values:
|
|
#: a model that reads "formula_align: string" invents ``middle``.
|
|
#:
|
|
#: This is the same set as :data:`app.models.paper_sentence.FORMULA_ALIGNMENTS`,
|
|
#: which the payload validator enforces; a value outside it is refused by the
|
|
#: same message the REST API gives.
|
|
FormulaAlign = Literal["center", "left", "right"]
|
|
|
|
|
|
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.
|
|
|
|
The fields here are the sentence's own columns, and they are meant to stay
|
|
that way: :data:`app.mcp.support.SENTENCE_FIELDS` is read from
|
|
:class:`~app.schemas.paper.SentenceInput` at import, and ``smoke_mcp.py``
|
|
asserts that this model declares every one of them. A column added to the
|
|
domain therefore fails the suite until it is declared here, instead of being
|
|
dropped from every write in silence — which is what happened to
|
|
``line_break_before`` and then to ``formula_align``.
|
|
"""
|
|
|
|
content: Annotated[str, Field(description="句子正文;空白会被折叠成一行")]
|
|
sort: Annotated[
|
|
int | None,
|
|
Field(description="段内排序值;不传则按写入顺序接在段尾"),
|
|
] = None
|
|
line_break_before: Annotated[
|
|
bool,
|
|
Field(
|
|
description=(
|
|
"这一句前面另起一行(默认 false)。正文被句子拼成一段,所以公式、"
|
|
"分条列举、作者行这类不是散文的行要在这里开口;break 会顶掉句间的空格,"
|
|
"不会多印一个空格。display 公式($$…$$ 或 \\[…\\])本来就独占一行,不必设这个"
|
|
)
|
|
),
|
|
] = False
|
|
formula_align: Annotated[
|
|
FormulaAlign,
|
|
Field(
|
|
description=(
|
|
"display 公式在这一行怎么排:center(默认)/ left / right。"
|
|
"只对含 $$…$$ 的句子有意义,句号后的编号始终靠右"
|
|
)
|
|
),
|
|
] = "center"
|
|
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
|
|
formula_align: Annotated[
|
|
FormulaAlign,
|
|
Field(description="这块切出来的公式怎么排:center(默认)/ left / right"),
|
|
] = "center"
|
|
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",
|
|
]
|