Compare commits
6 Commits
0e0fde8f02
..
main
| Author | SHA1 | Date | |
|---|---|---|---|
| 1531263bd2 | |||
| b19f28492e | |||
| 48f0c12fd2 | |||
| 9e6a1f8c3e | |||
| ebaf9e558b | |||
| eb0f12b8cf |
@@ -219,7 +219,16 @@ class ImageStore:
|
|||||||
return
|
return
|
||||||
except ClientError as error:
|
except ClientError as error:
|
||||||
code = error.response.get("Error", {}).get("Code", "")
|
code = error.response.get("Error", {}).get("Code", "")
|
||||||
if code not in {"404", "NoSuchBucket", "NotFound"}:
|
if code in {"404", "NoSuchBucket", "NotFound"}:
|
||||||
|
pass # not there — fall through and make it
|
||||||
|
elif code in {"403", "AccessDenied"}:
|
||||||
|
# Being refused a look at the bucket is not the same as the
|
||||||
|
# bucket being absent. A key scoped to objects alone (PutObject /
|
||||||
|
# GetObject, no ListBucket) gets exactly this answer, and the
|
||||||
|
# upload that follows is the honest test of whether it works —
|
||||||
|
# so return rather than turning a working key into a 503.
|
||||||
|
return
|
||||||
|
else:
|
||||||
raise self._unavailable(error) from error
|
raise self._unavailable(error) from error
|
||||||
|
|
||||||
try:
|
try:
|
||||||
|
|||||||
@@ -27,6 +27,15 @@ from pydantic import BaseModel, Field
|
|||||||
#: of an explicit list. See :func:`app.mcp.support.split_text`.
|
#: of an explicit list. See :func:`app.mcp.support.split_text`.
|
||||||
SplitMode = Literal["line", "sentence", "paragraph"]
|
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):
|
class CitationSpec(BaseModel):
|
||||||
"""One citation of one sentence."""
|
"""One citation of one sentence."""
|
||||||
@@ -42,9 +51,22 @@ class CitationSpec(BaseModel):
|
|||||||
|
|
||||||
|
|
||||||
class SentenceSpec(BaseModel):
|
class SentenceSpec(BaseModel):
|
||||||
"""One sentence, optionally carrying citations."""
|
"""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="句子正文;空白会被折叠成一行")]
|
content: Annotated[str, Field(description="句子正文;空白会被折叠成一行")]
|
||||||
|
sort: Annotated[
|
||||||
|
int | None,
|
||||||
|
Field(description="段内排序值;不传则按写入顺序接在段尾"),
|
||||||
|
] = None
|
||||||
line_break_before: Annotated[
|
line_break_before: Annotated[
|
||||||
bool,
|
bool,
|
||||||
Field(
|
Field(
|
||||||
@@ -55,6 +77,15 @@ class SentenceSpec(BaseModel):
|
|||||||
)
|
)
|
||||||
),
|
),
|
||||||
] = False
|
] = False
|
||||||
|
formula_align: Annotated[
|
||||||
|
FormulaAlign,
|
||||||
|
Field(
|
||||||
|
description=(
|
||||||
|
"display 公式在这一行怎么排:center(默认)/ left / right。"
|
||||||
|
"只对含 $$…$$ 的句子有意义,句号后的编号始终靠右"
|
||||||
|
)
|
||||||
|
),
|
||||||
|
] = "center"
|
||||||
citations: Annotated[
|
citations: Annotated[
|
||||||
list[CitationSpec],
|
list[CitationSpec],
|
||||||
Field(description="这一段引用了哪些文献"),
|
Field(description="这一段引用了哪些文献"),
|
||||||
@@ -78,6 +109,10 @@ class TextSpec(BaseModel):
|
|||||||
)
|
)
|
||||||
),
|
),
|
||||||
] = False
|
] = False
|
||||||
|
formula_align: Annotated[
|
||||||
|
FormulaAlign,
|
||||||
|
Field(description="这块切出来的公式怎么排:center(默认)/ left / right"),
|
||||||
|
] = "center"
|
||||||
citations: Annotated[
|
citations: Annotated[
|
||||||
list[CitationSpec],
|
list[CitationSpec],
|
||||||
Field(description="整段共用的引用"),
|
Field(description="整段共用的引用"),
|
||||||
|
|||||||
+99
-16
@@ -260,6 +260,9 @@ def sentence_row(sentence: Any, *, separator: str | None = None) -> dict:
|
|||||||
# move one: a paragraph read back without this flag looks like prose
|
# move one: a paragraph read back without this flag looks like prose
|
||||||
# that happens to have no spaces in it.
|
# that happens to have no spaces in it.
|
||||||
"line_break_before": sentence.line_break_before,
|
"line_break_before": sentence.line_break_before,
|
||||||
|
# Only meaningful for a sentence holding a display formula, and reported
|
||||||
|
# anyway: a row that hides it looks like a row where it is not set.
|
||||||
|
"formula_align": sentence.formula_align,
|
||||||
"citations": [citation_row(item) for item in sentence.citations],
|
"citations": [citation_row(item) for item in sentence.citations],
|
||||||
}
|
}
|
||||||
if separator is not None:
|
if separator is not None:
|
||||||
@@ -283,17 +286,46 @@ def paragraph_row(paragraph: ParagraphRead, *, preview: int = 80) -> dict:
|
|||||||
|
|
||||||
#: A formula the paper view sets on a line of its own: ``$$…$$`` or ``\[…\]``.
|
#: A formula the paper view sets on a line of its own: ``$$…$$`` or ``\[…\]``.
|
||||||
#:
|
#:
|
||||||
#: This is the same rule as ``hasDisplayMath`` in ``frontend/src/utils/math.ts``,
|
#: This is the same rule as ``hasDisplayMath`` in ``frontend/src/utils/rich.ts``,
|
||||||
#: written twice because the view is TypeScript and this is Python. The two must
|
#: written twice because the view is TypeScript and this is Python. The two must
|
||||||
#: agree, or a tool result and the page a writer is looking at would disagree
|
#: agree, or a tool result and the page a writer is looking at would disagree
|
||||||
#: about where the lines are — which is the one thing this module exists to
|
#: about where the lines are — which is the one thing this module exists to
|
||||||
#: prevent. Change one, change the other.
|
#: prevent. Change one, change the other.
|
||||||
_DISPLAY_MATH = re.compile(r"\$\$[\s\S]+?\$\$|\\\[[\s\S]+?\\\]")
|
_DISPLAY_MATH = re.compile(r"\$\$[\s\S]+?\$\$|\\\[[\s\S]+?\\\]")
|
||||||
|
|
||||||
|
#: One image, as a sentence writes it: ```` with pandoc's optional
|
||||||
|
#: ``{width=…}``. The counterpart of the image alternative in ``RICH_PATTERN``
|
||||||
|
#: (same file as above), and the same warning applies: the two are one rule.
|
||||||
|
_IMAGE = re.compile(r"!\[(?P<alt>[^\]]*)\]\([^()\s]+(?:\s+\"[^\"]*\")?\)(?:\{[^}]*\})?")
|
||||||
|
|
||||||
def _is_display(sentence: Any) -> bool:
|
|
||||||
"""Whether this sentence is a display formula — a block, not a run of text."""
|
def _figure_caption(content: str) -> str | None:
|
||||||
return bool(_DISPLAY_MATH.search(sentence.content))
|
"""The 图注 of a figure sentence — a sentence that is nothing but one image.
|
||||||
|
|
||||||
|
The paper view's ``figureOf``: a sentence holding only a picture is a 插图,
|
||||||
|
printed on a line of its own with the brackets' text underneath as its
|
||||||
|
caption; a picture inside a sentence that says something stays in the line.
|
||||||
|
Anything else — two images, or an image with words around it — is not a
|
||||||
|
figure, and returns ``None``.
|
||||||
|
"""
|
||||||
|
match = _IMAGE.search(content)
|
||||||
|
if match is None:
|
||||||
|
return None
|
||||||
|
if content[: match.start()].strip() or content[match.end() :].strip():
|
||||||
|
return None
|
||||||
|
return match.group("alt")
|
||||||
|
|
||||||
|
|
||||||
|
def _is_block(sentence: Any) -> bool:
|
||||||
|
"""Whether this sentence takes a line of its own, whether or not it asked.
|
||||||
|
|
||||||
|
Two kinds do, and both are rules the paper view already applies: a display
|
||||||
|
formula, and a figure. Nothing else is inferred — an ordinary sentence that
|
||||||
|
merely follows a full stop runs on, which is what a paragraph is.
|
||||||
|
"""
|
||||||
|
return bool(_DISPLAY_MATH.search(sentence.content)) or _figure_caption(
|
||||||
|
sentence.content
|
||||||
|
) is not None
|
||||||
|
|
||||||
|
|
||||||
def paragraph_text(
|
def paragraph_text(
|
||||||
@@ -308,14 +340,20 @@ def paragraph_text(
|
|||||||
belongs at each seam, so a tool result and the paper view agree on where
|
belongs at each seam, so a tool result and the paper view agree on where
|
||||||
the spaces go. Nothing here adds spacing of its own.
|
the spaces go. Nothing here adds spacing of its own.
|
||||||
|
|
||||||
A line break is printed where the model asked for one, and around a display
|
A line break is printed where the model asked for one, and on both sides of
|
||||||
formula — the paper view renders ``$$…$$`` as a block, so the lines on
|
a block — a display formula, or a sentence that is one figure — because the
|
||||||
either side of it are line boundaries there too. A break *replaces* the
|
paper view sets those on a line of their own. A break *replaces* the
|
||||||
separator rather than joining it: the new line already separates the two
|
separator rather than joining it: the new line already separates the two
|
||||||
sentences, and a space as well would indent the line below by one blank.
|
sentences, and a space as well would indent the line below by one blank.
|
||||||
The first sentence of a paragraph is never preceded by a break, because
|
The first sentence of a paragraph is never preceded by a break, because
|
||||||
there is nothing above it to break from.
|
there is nothing above it to break from.
|
||||||
|
|
||||||
|
A figure prints as the Markdown it is stored as — ```` on its
|
||||||
|
own line — rather than as its caption alone. The text form cannot draw the
|
||||||
|
picture, and the address is what says *which* picture: a model that reads a
|
||||||
|
paragraph back sees the same string the writer put there, and can paste it
|
||||||
|
somewhere else unchanged.
|
||||||
|
|
||||||
A marker's number comes from ``index_by_citation`` — the citation's *work*
|
A marker's number comes from ``index_by_citation`` — the citation's *work*
|
||||||
number as the whole document assigned it, not its position in this sentence —
|
number as the whole document assigned it, not its position in this sentence —
|
||||||
so what is printed in the text matches the 参考文献 list it points at. Read
|
so what is printed in the text matches the 参考文献 list it points at. Read
|
||||||
@@ -325,7 +363,7 @@ def paragraph_text(
|
|||||||
parts: list[str] = []
|
parts: list[str] = []
|
||||||
previous_block = False
|
previous_block = False
|
||||||
for sentence in paragraph.sentences:
|
for sentence in paragraph.sentences:
|
||||||
block = _is_display(sentence)
|
block = _is_block(sentence)
|
||||||
if parts and (sentence.line_break_before or block or previous_block):
|
if parts and (sentence.line_break_before or block or previous_block):
|
||||||
parts.append("\n")
|
parts.append("\n")
|
||||||
else:
|
else:
|
||||||
@@ -619,6 +657,50 @@ def _is_latin_break(text: str, index: int) -> bool:
|
|||||||
return True
|
return True
|
||||||
|
|
||||||
|
|
||||||
|
#: Every field a sentence payload carries, read from the payload schema itself
|
||||||
|
#: rather than listed by hand here.
|
||||||
|
#:
|
||||||
|
#: The hand-written list was wrong twice. A column added to the domain —
|
||||||
|
#: ``line_break_before``, and then ``formula_align`` — reached the REST API, the
|
||||||
|
#: editor and the paper view, and was silently dropped by every MCP write path
|
||||||
|
#: that had spelled the fields out: the call succeeded and the field was simply
|
||||||
|
#: gone. Reading the names from :class:`~app.schemas.paper.SentenceInput` means a
|
||||||
|
#: new column flows through :func:`sentence_payload` and through the tools that
|
||||||
|
#: spread it, and the only edit left is declaring it in
|
||||||
|
#: :class:`~app.mcp.specs.SentenceSpec` — which ``smoke_mcp.py`` checks for, so
|
||||||
|
#: forgetting *that* fails the suite instead of losing the field.
|
||||||
|
SENTENCE_FIELDS: tuple[str, ...] = tuple(SentenceInput.model_fields)
|
||||||
|
|
||||||
|
|
||||||
|
def sentence_payload(values: Mapping[str, Any], **overrides: Any) -> SentenceInput:
|
||||||
|
"""One sentence payload, built from whatever the caller sent.
|
||||||
|
|
||||||
|
Fields the caller did not mention keep the schema's own defaults, and keys
|
||||||
|
this layer does not know are dropped rather than handed to a validator that
|
||||||
|
would refuse them: a model that copies a row out of ``paragraph_get`` and
|
||||||
|
edits it sends back ``id``, ``position`` and ``separator_before`` as well,
|
||||||
|
and read-modify-write is a reasonable way to work.
|
||||||
|
"""
|
||||||
|
known = {name: values[name] for name in SENTENCE_FIELDS if name in values}
|
||||||
|
known.update(overrides)
|
||||||
|
return SentenceInput(**known)
|
||||||
|
|
||||||
|
|
||||||
|
def sentence_values(row: Any) -> dict[str, Any]:
|
||||||
|
"""One *stored* sentence as payload fields again — for a move or a copy.
|
||||||
|
|
||||||
|
``sort`` is deliberately absent, and the caller decides about it: a sentence
|
||||||
|
moved onto another paragraph must not carry its old number there, or the two
|
||||||
|
paragraphs interleave by sort instead of the moved block landing after the
|
||||||
|
target's own sentences.
|
||||||
|
"""
|
||||||
|
return {
|
||||||
|
name: getattr(row, name)
|
||||||
|
for name in SENTENCE_FIELDS
|
||||||
|
if name not in {"sort", "citations"} and hasattr(row, name)
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
def sentence_inputs(items: Sequence[Any], *, default_split: str = "line") -> list[SentenceInput]:
|
def sentence_inputs(items: Sequence[Any], *, default_split: str = "line") -> list[SentenceInput]:
|
||||||
"""Normalise what a model sent into the project's own sentence payload.
|
"""Normalise what a model sent into the project's own sentence payload.
|
||||||
|
|
||||||
@@ -660,13 +742,7 @@ def sentence_inputs(items: Sequence[Any], *, default_split: str = "line") -> lis
|
|||||||
line_break = bool(item.get("line_break_before", False))
|
line_break = bool(item.get("line_break_before", False))
|
||||||
|
|
||||||
if item.get("content") is not None:
|
if item.get("content") is not None:
|
||||||
out.append(
|
out.append(sentence_payload(item, citations=citations))
|
||||||
SentenceInput(
|
|
||||||
content=str(item["content"]),
|
|
||||||
line_break_before=line_break,
|
|
||||||
citations=citations,
|
|
||||||
)
|
|
||||||
)
|
|
||||||
continue
|
continue
|
||||||
|
|
||||||
if item.get("text") is not None:
|
if item.get("text") is not None:
|
||||||
@@ -679,8 +755,12 @@ def sentence_inputs(items: Sequence[Any], *, default_split: str = "line") -> lis
|
|||||||
# would turn a paragraph the writer wrapped across three lines
|
# would turn a paragraph the writer wrapped across three lines
|
||||||
# into three lines of the paper.
|
# into three lines of the paper.
|
||||||
out.append(
|
out.append(
|
||||||
SentenceInput(
|
sentence_payload(
|
||||||
|
item,
|
||||||
content=piece,
|
content=piece,
|
||||||
|
# A block has no ``sort`` of its own: the pieces are one
|
||||||
|
# after another, and the CRUD layer numbers them.
|
||||||
|
sort=None,
|
||||||
line_break_before=line_break and offset == 0,
|
line_break_before=line_break and offset == 0,
|
||||||
citations=citations,
|
citations=citations,
|
||||||
)
|
)
|
||||||
@@ -728,6 +808,7 @@ def paragraph_inputs(spec: Any) -> list[SentenceInput]:
|
|||||||
|
|
||||||
__all__ = [
|
__all__ = [
|
||||||
"MAX_PAGE_SIZE",
|
"MAX_PAGE_SIZE",
|
||||||
|
"SENTENCE_FIELDS",
|
||||||
"SPLIT_MODES",
|
"SPLIT_MODES",
|
||||||
"clean",
|
"clean",
|
||||||
"citation_row",
|
"citation_row",
|
||||||
@@ -747,7 +828,9 @@ __all__ = [
|
|||||||
"resolve_position",
|
"resolve_position",
|
||||||
"sentence_inputs",
|
"sentence_inputs",
|
||||||
"sentence_or_fail",
|
"sentence_or_fail",
|
||||||
|
"sentence_payload",
|
||||||
"sentence_row",
|
"sentence_row",
|
||||||
|
"sentence_values",
|
||||||
"session",
|
"session",
|
||||||
"split_text",
|
"split_text",
|
||||||
"template_or_fail",
|
"template_or_fail",
|
||||||
|
|||||||
@@ -1,4 +1,4 @@
|
|||||||
"""Tool registry: the five groups, registered in one call.
|
"""Tool registry: the groups, registered in one call.
|
||||||
|
|
||||||
The groups mirror the domain rather than the HTTP routes — papers and
|
The groups mirror the domain rather than the HTTP routes — papers and
|
||||||
paragraphs and sentences are the same tables the REST API serves, but a model
|
paragraphs and sentences are the same tables the REST API serves, but a model
|
||||||
@@ -7,9 +7,10 @@ and the split between :mod:`~app.mcp.tools.papers` and
|
|||||||
:mod:`~app.mcp.tools.paragraphs` follows those jobs.
|
:mod:`~app.mcp.tools.paragraphs` follows those jobs.
|
||||||
|
|
||||||
Prefixes are load-bearing: every tool name starts with its group
|
Prefixes are load-bearing: every tool name starts with its group
|
||||||
(``paper_``, ``paragraph_``, ``sentence_``, ``template_``, ``field_``), because
|
(``paper_``, ``paragraph_``, ``sentence_``, ``template_``, ``field_``,
|
||||||
that prefix is what a model uses to pick a tool out of a list of twenty-nine
|
``reference_``, ``reference_tag_``, ``image_``), because that prefix is what a
|
||||||
without reading all twenty-nine descriptions.
|
model uses to pick a tool out of a list of forty without reading all forty
|
||||||
|
descriptions.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
@@ -18,6 +19,7 @@ from mcp.server.mcpserver import MCPServer
|
|||||||
|
|
||||||
from app.mcp.tools import (
|
from app.mcp.tools import (
|
||||||
fields,
|
fields,
|
||||||
|
images,
|
||||||
papers,
|
papers,
|
||||||
paragraphs,
|
paragraphs,
|
||||||
reference_tags,
|
reference_tags,
|
||||||
@@ -28,8 +30,18 @@ from app.mcp.tools import (
|
|||||||
|
|
||||||
#: Registration order is also the order a client lists the tools in, which is
|
#: Registration order is also the order a client lists the tools in, which is
|
||||||
#: the order a paper is actually written in: find it, shape it, write it, then
|
#: the order a paper is actually written in: find it, shape it, write it, then
|
||||||
#: the things it is written against.
|
#: the things it is written against — and last the figure, which is written by
|
||||||
MODULES = (papers, paragraphs, sentences, templates, fields, references, reference_tags)
|
#: putting a sentence somewhere.
|
||||||
|
MODULES = (
|
||||||
|
papers,
|
||||||
|
paragraphs,
|
||||||
|
sentences,
|
||||||
|
templates,
|
||||||
|
fields,
|
||||||
|
references,
|
||||||
|
reference_tags,
|
||||||
|
images,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
def register_all(server: MCPServer) -> None:
|
def register_all(server: MCPServer) -> None:
|
||||||
|
|||||||
@@ -0,0 +1,255 @@
|
|||||||
|
"""Image tools (插图): put a figure in the bucket, and hand back the sentence.
|
||||||
|
|
||||||
|
A picture is not text, so it does not live in the database: the sentence keeps a
|
||||||
|
Markdown address and the bytes live in MinIO (see :mod:`app.core.storage`). That
|
||||||
|
is what keeps a sentence one editable string, and it is also why there is no
|
||||||
|
``image_create`` that attaches a picture to a paragraph — writing a figure *is*
|
||||||
|
writing a sentence whose content happens to be ````.
|
||||||
|
|
||||||
|
One tool, and one field of a sentence, is therefore the whole feature from a
|
||||||
|
model's side. ``image_upload`` exists for the half a model cannot do itself: it
|
||||||
|
has bytes (a screenshot the user pasted, a figure it generated) and no way to
|
||||||
|
send a multipart request. Everything after that is ordinary text.
|
||||||
|
|
||||||
|
The base64 argument is a deliberate cost. A tool argument is context tokens, and
|
||||||
|
base64 is a third larger than the bytes it carries — but the alternative is a
|
||||||
|
second ingestion path (an HTTP fetch of a URL the caller names), and a service
|
||||||
|
inside the cluster that will fetch any address it is handed is an SSRF primitive
|
||||||
|
aimed at everything beside it. A model with a picture and no base64 can post it
|
||||||
|
to ``POST /api/images`` and use the Markdown that comes back; the two produce the
|
||||||
|
same sentence, byte for byte, because both go through
|
||||||
|
:func:`app.core.storage.markdown_for`.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import base64
|
||||||
|
import binascii
|
||||||
|
import re
|
||||||
|
from typing import Annotated
|
||||||
|
|
||||||
|
from mcp.server.mcpserver import MCPServer
|
||||||
|
from pydantic import Field
|
||||||
|
|
||||||
|
from app.core.config import get_settings
|
||||||
|
from app.core.storage import get_store, image_url, markdown_for
|
||||||
|
from app.mcp import support as s
|
||||||
|
from app.mcp.tools.registry import mcp_tool
|
||||||
|
|
||||||
|
|
||||||
|
def register(server: MCPServer) -> None:
|
||||||
|
"""Register every image tool on ``server``."""
|
||||||
|
|
||||||
|
@mcp_tool(server, title="上传插图")
|
||||||
|
def image_upload(
|
||||||
|
data_base64: Annotated[
|
||||||
|
str,
|
||||||
|
Field(
|
||||||
|
description=(
|
||||||
|
"图片内容的 base64。可以直接给 data:image/png;base64,… 这种完整形式。"
|
||||||
|
"PNG / JPEG / GIF / WebP,最大 20 MB"
|
||||||
|
)
|
||||||
|
),
|
||||||
|
],
|
||||||
|
caption: Annotated[
|
||||||
|
str | None,
|
||||||
|
Field(description="图注;不给就用 filename 的主干,都没有则留空"),
|
||||||
|
] = None,
|
||||||
|
filename: Annotated[
|
||||||
|
str | None,
|
||||||
|
Field(description="文件名,只用于取图注初值;存储的键由内容决定,与它无关"),
|
||||||
|
] = None,
|
||||||
|
width: Annotated[
|
||||||
|
str | None,
|
||||||
|
Field(
|
||||||
|
description=(
|
||||||
|
"可选宽度:70%(占栏宽)或 400px;只写数字按百分比算。"
|
||||||
|
"不传则按原尺寸,最大不超过栏宽"
|
||||||
|
)
|
||||||
|
),
|
||||||
|
] = None,
|
||||||
|
height: Annotated[
|
||||||
|
str | None,
|
||||||
|
Field(
|
||||||
|
description=(
|
||||||
|
"可选高度,只能填像素(300 或 300px,1–4000):图片不会超过这个高度,"
|
||||||
|
"宽度按原比例跟着变。高度不能用百分比(句子里没有可参照的高度)"
|
||||||
|
)
|
||||||
|
),
|
||||||
|
] = None,
|
||||||
|
) -> str:
|
||||||
|
"""上传一张图片,返回可直接写进句子的 Markdown 与那个句子对象。"""
|
||||||
|
data = _decode(data_base64)
|
||||||
|
settings = get_settings()
|
||||||
|
if len(data) > settings.max_image_bytes:
|
||||||
|
s.fail(
|
||||||
|
f"图片太大了({len(data) / (1024 * 1024):.1f} MB),"
|
||||||
|
f"上限是 {settings.max_image_bytes // (1024 * 1024)} MB。先压缩或裁剪一下再传。"
|
||||||
|
)
|
||||||
|
|
||||||
|
# The store sniffs the format out of the bytes and refuses anything that
|
||||||
|
# is not a picture: an SVG is stored XSS when it is served from this
|
||||||
|
# origin, and the caller's content type or filename is only a claim.
|
||||||
|
key, content_type, digest = get_store().save(data)
|
||||||
|
|
||||||
|
markdown = _embed(
|
||||||
|
key, caption=caption or _stem(filename), width=width, height=height
|
||||||
|
)
|
||||||
|
return s.dumps(
|
||||||
|
{
|
||||||
|
"key": key,
|
||||||
|
"url": image_url(key),
|
||||||
|
"markdown": markdown,
|
||||||
|
"content_type": content_type,
|
||||||
|
"size": len(data),
|
||||||
|
"sha256": digest,
|
||||||
|
# The sentence, not just the Markdown: this is what the editor
|
||||||
|
# produces when a picture is dropped into it — the figure on a
|
||||||
|
# line of its own — so a model writes a figure by putting this
|
||||||
|
# object into `sentences` and changing nothing about it.
|
||||||
|
"sentence": {
|
||||||
|
"content": markdown,
|
||||||
|
"line_break_before": True,
|
||||||
|
"formula_align": "center",
|
||||||
|
},
|
||||||
|
}
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
# --- helpers -----------------------------------------------------------------
|
||||||
|
|
||||||
|
#: How a size may be written, and what it may be. Both halves mirror
|
||||||
|
#: ``WIDTH_PATTERN`` and ``parseImageWidth`` in ``frontend/src/utils/rich.ts``,
|
||||||
|
#: which is what actually reads the attribute when the paper is printed: the
|
||||||
|
#: syntax is ``{width=70%}`` or ``{width=400px}``, digits with at most one unit,
|
||||||
|
#: pixels up to :data:`MAX_PIXELS` and percentages up to 100.
|
||||||
|
#:
|
||||||
|
#: Written twice because one side is TypeScript and one is Python, and checked
|
||||||
|
#: here rather than passed through, because the reader's answer to a value it
|
||||||
|
#: cannot parse is to print the picture at its natural size — a size that
|
||||||
|
#: silently does not apply is worse than a refusal that says so.
|
||||||
|
_WIDTH_ATTRIBUTE = re.compile(r"^\s*(?:w|width)\s*=\s*(\d{1,4})\s*(%|px)?\s*$", re.IGNORECASE)
|
||||||
|
_WIDTH_BARE = re.compile(r"^\s*(\d{1,4})\s*(%|px)?\s*$")
|
||||||
|
#: A height is pixels and nothing else; see :func:`_height_declaration`. A bare
|
||||||
|
#: number is pixels because there is nothing else it could be.
|
||||||
|
_HEIGHT_ATTRIBUTE = re.compile(r"^\s*(?:h|height)\s*=\s*(\d{1,4})\s*(?:px)?\s*$", re.IGNORECASE)
|
||||||
|
_HEIGHT_BARE = re.compile(r"^\s*(\d{1,4})\s*(?:px)?\s*$", re.IGNORECASE)
|
||||||
|
_MAX_PIXELS = 4000
|
||||||
|
_MAX_PERCENT = 100
|
||||||
|
|
||||||
|
|
||||||
|
def _decode(value: str) -> bytes:
|
||||||
|
"""The bytes behind a base64 argument, refusing anything that is not one.
|
||||||
|
|
||||||
|
A ``data:`` prefix is stripped rather than refused: it is what a browser
|
||||||
|
writes when a picture is copied as a data URL, and it is what a model
|
||||||
|
produces when it repeats what it was given.
|
||||||
|
"""
|
||||||
|
text = value.strip()
|
||||||
|
if text.startswith("data:"):
|
||||||
|
_, _, text = text.partition(",")
|
||||||
|
# Whitespace is folded out because base64 arrives wrapped in as many ways as
|
||||||
|
# there are tools that produced it.
|
||||||
|
text = "".join(text.split())
|
||||||
|
if not text:
|
||||||
|
s.fail("data_base64 是空的,没有图片内容")
|
||||||
|
try:
|
||||||
|
return base64.b64decode(text, validate=True)
|
||||||
|
except (binascii.Error, ValueError):
|
||||||
|
s.fail("data_base64 不是合法的 base64;请给图片字节的 base64,不要给文件路径或 URL")
|
||||||
|
|
||||||
|
|
||||||
|
def _stem(filename: str | None) -> str:
|
||||||
|
"""The caption a filename suggests, the way the upload endpoint reads it."""
|
||||||
|
if not filename:
|
||||||
|
return ""
|
||||||
|
name = filename.replace("\\", "/").rsplit("/", 1)[-1]
|
||||||
|
return name.rsplit(".", 1)[0] if "." in name else name
|
||||||
|
|
||||||
|
|
||||||
|
def _embed(
|
||||||
|
key: str, *, caption: str, width: str | None, height: str | None = None
|
||||||
|
) -> str:
|
||||||
|
"""The Markdown a sentence carries: the address, plus an optional size.
|
||||||
|
|
||||||
|
``markdown_for`` writes the ```` half — the same function the
|
||||||
|
upload endpoint answers with — and this adds the size, which the endpoint
|
||||||
|
does not take because a browser appends it in the editor.
|
||||||
|
"""
|
||||||
|
parts = [
|
||||||
|
part
|
||||||
|
for part in (_width_declaration(width), _height_declaration(height))
|
||||||
|
if part
|
||||||
|
]
|
||||||
|
markdown = markdown_for(key, caption)
|
||||||
|
return f"{markdown}{{{' '.join(parts)}}}" if parts else markdown
|
||||||
|
|
||||||
|
|
||||||
|
def _height_declaration(height: str | None) -> str:
|
||||||
|
"""``height=300px`` from what the caller wrote, or a refusal saying why not.
|
||||||
|
|
||||||
|
**Pixels only.** A percentage height has nothing to be a percentage *of* — a
|
||||||
|
sentence is flowed text, so there is no container height to measure against —
|
||||||
|
and the reader's answer to one is to ignore it, which is a size that silently
|
||||||
|
does not apply. ``1–4000`` for the same reason as a width: a typo should be
|
||||||
|
refused, not laid out.
|
||||||
|
"""
|
||||||
|
if height is None or not str(height).strip():
|
||||||
|
return ""
|
||||||
|
|
||||||
|
written = str(height).strip().strip("{}").strip()
|
||||||
|
match = _HEIGHT_ATTRIBUTE.match(written) or _HEIGHT_BARE.match(written)
|
||||||
|
if match is None:
|
||||||
|
# A percentage gets the reason it cannot work; anything else just gets
|
||||||
|
# told what a height looks like.
|
||||||
|
why = (
|
||||||
|
"百分比高度在句子里没有参照物,读的时候会被忽略"
|
||||||
|
if "%" in written
|
||||||
|
else "填像素数字,例如 300"
|
||||||
|
)
|
||||||
|
s.fail(f"height 只能填像素,例如 300 或 300px,收到的是“{height}”。{why}")
|
||||||
|
|
||||||
|
digits = int(match.group(1))
|
||||||
|
if not 1 <= digits <= _MAX_PIXELS:
|
||||||
|
s.fail(f"height 要在 1 到 {_MAX_PIXELS} 之间,收到的是“{height}”")
|
||||||
|
return f"height={digits}px"
|
||||||
|
|
||||||
|
|
||||||
|
def _width_declaration(width: str | None) -> str:
|
||||||
|
"""``{width=70%}`` from what the caller wrote, or a refusal saying why not.
|
||||||
|
|
||||||
|
Tolerant about how it is written — ``70%``, ``70 %``, ``{width=70%}`` and
|
||||||
|
``w=400px`` all mean the same thing, which is what a model repeats back from
|
||||||
|
a sentence it read — and strict about what it means.
|
||||||
|
|
||||||
|
A bare number is a **percentage**, because that is what the reader makes of
|
||||||
|
one: ``parseImageWidth`` only takes a value as pixels when it is written
|
||||||
|
``px``, and treats everything else as a share of the column. ``400`` is
|
||||||
|
therefore out of range and refused with the two forms that work, rather than
|
||||||
|
written as ``400px`` and printed at a third of the page.
|
||||||
|
"""
|
||||||
|
if width is None or not str(width).strip():
|
||||||
|
return ""
|
||||||
|
|
||||||
|
written = str(width).strip().strip("{}").strip()
|
||||||
|
match = _WIDTH_ATTRIBUTE.match(written) or _WIDTH_BARE.match(written)
|
||||||
|
if match is None:
|
||||||
|
s.fail(
|
||||||
|
f"width 只能是百分比或像素,例如 70% 或 400px,收到的是“{width}”。"
|
||||||
|
"不写则按原尺寸显示(最多不超过栏宽)"
|
||||||
|
)
|
||||||
|
|
||||||
|
digits = int(match.group(1))
|
||||||
|
unit = (match.group(2) or "%").lower()
|
||||||
|
limit = _MAX_PERCENT if unit == "%" else _MAX_PIXELS
|
||||||
|
if not 1 <= digits <= limit:
|
||||||
|
# The pointer to pixels only helps when the caller wrote a bare number:
|
||||||
|
# "150%" is already written as a percentage and does not want advice.
|
||||||
|
hint = f"像素要写成 “{digits}px”" if match.group(2) is None else ""
|
||||||
|
s.fail(
|
||||||
|
f"width 的 {unit} 值要在 1 到 {limit} 之间,收到的是“{width}”。{hint}"
|
||||||
|
)
|
||||||
|
return f"width={digits}{unit}"
|
||||||
|
|
||||||
|
|
||||||
|
__all__ = ["register"]
|
||||||
@@ -342,12 +342,12 @@ def register(server: MCPServer) -> None:
|
|||||||
paper_crud.append_sentence(
|
paper_crud.append_sentence(
|
||||||
db,
|
db,
|
||||||
paper,
|
paper,
|
||||||
|
# Spread, not copied field by field: a sentence
|
||||||
|
# column added to the domain then reaches this path
|
||||||
|
# by itself, instead of being dropped in silence.
|
||||||
SentenceCreate(
|
SentenceCreate(
|
||||||
|
**item.model_dump(),
|
||||||
paper_template_filed_sort=position,
|
paper_template_filed_sort=position,
|
||||||
content=item.content,
|
|
||||||
line_break_before=item.line_break_before,
|
|
||||||
citations=item.citations,
|
|
||||||
sort=item.sort,
|
|
||||||
),
|
),
|
||||||
)
|
)
|
||||||
else:
|
else:
|
||||||
|
|||||||
@@ -204,19 +204,13 @@ def register(server: MCPServer) -> None:
|
|||||||
if not rows:
|
if not rows:
|
||||||
s.fail(f"第 {source} 段没有内容可以搬")
|
s.fail(f"第 {source} 段没有内容可以搬")
|
||||||
|
|
||||||
|
# Moved, not rewritten. Every column of the sentence travels —
|
||||||
|
# where a line started, how a formula was aligned, what it cited —
|
||||||
|
# because all of it is part of what was there; and ``sort`` is the
|
||||||
|
# one field deliberately left behind (see
|
||||||
|
# :func:`app.mcp.support.sentence_values`).
|
||||||
inputs = [
|
inputs = [
|
||||||
SentenceInput(
|
SentenceInput(**s.sentence_values(row), citations=list(row.citations))
|
||||||
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
|
for row in rows
|
||||||
]
|
]
|
||||||
paper_crud.replace_paragraph(
|
paper_crud.replace_paragraph(
|
||||||
@@ -266,6 +260,11 @@ def _write(
|
|||||||
at a time — the same call ``POST /papers/{id}/sentences`` makes — rather
|
at a time — the same call ``POST /papers/{id}/sentences`` makes — rather
|
||||||
than read-modify-write, so two sentences appended in one request cannot
|
than read-modify-write, so two sentences appended in one request cannot
|
||||||
overwrite each other's ``sort``.
|
overwrite each other's ``sort``.
|
||||||
|
|
||||||
|
The payload is spread rather than copied field by field, so a column added
|
||||||
|
to a sentence reaches this path without anyone remembering to add it here —
|
||||||
|
which is how ``line_break_before`` and ``formula_align`` each went missing
|
||||||
|
once.
|
||||||
"""
|
"""
|
||||||
if mode == "append":
|
if mode == "append":
|
||||||
for item in inputs:
|
for item in inputs:
|
||||||
@@ -273,11 +272,7 @@ def _write(
|
|||||||
db,
|
db,
|
||||||
paper,
|
paper,
|
||||||
SentenceCreate(
|
SentenceCreate(
|
||||||
paper_template_filed_sort=field_sort,
|
**item.model_dump(), paper_template_filed_sort=field_sort
|
||||||
content=item.content,
|
|
||||||
line_break_before=item.line_break_before,
|
|
||||||
citations=item.citations,
|
|
||||||
sort=item.sort,
|
|
||||||
),
|
),
|
||||||
)
|
)
|
||||||
else:
|
else:
|
||||||
|
|||||||
@@ -32,6 +32,7 @@ from typing import Any, TypeVar
|
|||||||
from mcp.server.mcpserver import MCPServer
|
from mcp.server.mcpserver import MCPServer
|
||||||
from mcp.server.mcpserver.exceptions import ToolError
|
from mcp.server.mcpserver.exceptions import ToolError
|
||||||
|
|
||||||
|
from app.core.storage import StorageUnavailable, UnsupportedImage
|
||||||
from app.crud.reference import UnknownReference
|
from app.crud.reference import UnknownReference
|
||||||
from app.crud.reference_tag import DuplicateTagName, UnknownTag
|
from app.crud.reference_tag import DuplicateTagName, UnknownTag
|
||||||
|
|
||||||
@@ -46,7 +47,19 @@ F = TypeVar("F", bound=Callable[..., Any])
|
|||||||
#: would have let 「标签不存在:9」 reach the model as an unreadable
|
#: would have let 「标签不存在:9」 reach the model as an unreadable
|
||||||
#: "Error executing tool ...", which is the exact failure this wrapper exists to
|
#: "Error executing tool ...", which is the exact failure this wrapper exists to
|
||||||
#: prevent. A new domain refusal belongs in this tuple on the day it is written.
|
#: prevent. A new domain refusal belongs in this tuple on the day it is written.
|
||||||
DOMAIN_REFUSALS = (UnknownReference, UnknownTag, DuplicateTagName)
|
#:
|
||||||
|
#: The two storage ones are here for the same reason. A bucket that is not
|
||||||
|
#: configured and a file that is not a picture are both answers rather than
|
||||||
|
#: faults — "缺少 MINIO_ENDPOINT" and "只接受 PNG / JPEG / GIF / WebP" are the
|
||||||
|
#: two things a caller can act on, and neither survives the wrapper as a stack
|
||||||
|
#: trace.
|
||||||
|
DOMAIN_REFUSALS = (
|
||||||
|
UnknownReference,
|
||||||
|
UnknownTag,
|
||||||
|
DuplicateTagName,
|
||||||
|
StorageUnavailable,
|
||||||
|
UnsupportedImage,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
def mcp_tool(
|
def mcp_tool(
|
||||||
|
|||||||
@@ -20,7 +20,7 @@ from pydantic import Field
|
|||||||
|
|
||||||
from app.crud import paper as paper_crud
|
from app.crud import paper as paper_crud
|
||||||
from app.mcp import support as s
|
from app.mcp import support as s
|
||||||
from app.mcp.specs import CitationSpec
|
from app.mcp.specs import CitationSpec, FormulaAlign
|
||||||
from app.mcp.tools.registry import mcp_tool
|
from app.mcp.tools.registry import mcp_tool
|
||||||
from app.models import Paper
|
from app.models import Paper
|
||||||
from app.schemas.paper import CitationInput, SentenceCreate, SentenceUpdate
|
from app.schemas.paper import CitationInput, SentenceCreate, SentenceUpdate
|
||||||
@@ -94,6 +94,10 @@ def register(server: MCPServer) -> None:
|
|||||||
)
|
)
|
||||||
),
|
),
|
||||||
] = False,
|
] = False,
|
||||||
|
formula_align: Annotated[
|
||||||
|
FormulaAlign,
|
||||||
|
Field(description="display 公式怎么排:center(默认)/ left / right"),
|
||||||
|
] = "center",
|
||||||
sort: Annotated[
|
sort: Annotated[
|
||||||
int | None, Field(description="段内位置;不传则排在段尾")
|
int | None, Field(description="段内位置;不传则排在段尾")
|
||||||
] = None,
|
] = None,
|
||||||
@@ -109,6 +113,7 @@ def register(server: MCPServer) -> None:
|
|||||||
paper_template_filed_sort=field_sort,
|
paper_template_filed_sort=field_sort,
|
||||||
content=content,
|
content=content,
|
||||||
line_break_before=line_break_before,
|
line_break_before=line_break_before,
|
||||||
|
formula_align=formula_align,
|
||||||
citations=_citations(citations or []),
|
citations=_citations(citations or []),
|
||||||
sort=sort,
|
sort=sort,
|
||||||
),
|
),
|
||||||
@@ -137,17 +142,22 @@ def register(server: MCPServer) -> None:
|
|||||||
bool | None,
|
bool | None,
|
||||||
Field(description="这一句是否另起一行;不传则不动,false 表示取消换行"),
|
Field(description="这一句是否另起一行;不传则不动,false 表示取消换行"),
|
||||||
] = None,
|
] = None,
|
||||||
|
formula_align: Annotated[
|
||||||
|
FormulaAlign | None,
|
||||||
|
Field(description="display 公式怎么排;不传则不动"),
|
||||||
|
] = None,
|
||||||
citations: Annotated[
|
citations: Annotated[
|
||||||
list[CitationSpec] | None,
|
list[CitationSpec] | None,
|
||||||
Field(description="引用整组替换;传 [] 表示清空引用"),
|
Field(description="引用整组替换;传 [] 表示清空引用"),
|
||||||
] = None,
|
] = None,
|
||||||
) -> str:
|
) -> str:
|
||||||
"""修改一句话的正文、所属段落、排序、换行或引用(引用是整体替换)。"""
|
"""修改一句话的正文、所属段落、排序、换行、公式对齐或引用(引用是整体替换)。"""
|
||||||
if (
|
if (
|
||||||
content is None
|
content is None
|
||||||
and position is None
|
and position is None
|
||||||
and sort is None
|
and sort is None
|
||||||
and line_break_before is None
|
and line_break_before is None
|
||||||
|
and formula_align is None
|
||||||
and citations is None
|
and citations is None
|
||||||
):
|
):
|
||||||
s.fail("没有给出任何要修改的内容")
|
s.fail("没有给出任何要修改的内容")
|
||||||
@@ -164,6 +174,7 @@ def register(server: MCPServer) -> None:
|
|||||||
paper_template_filed_sort=position,
|
paper_template_filed_sort=position,
|
||||||
sort=sort,
|
sort=sort,
|
||||||
line_break_before=line_break_before,
|
line_break_before=line_break_before,
|
||||||
|
formula_align=formula_align,
|
||||||
citations=None if citations is None else _citations(citations),
|
citations=None if citations is None else _citations(citations),
|
||||||
),
|
),
|
||||||
)
|
)
|
||||||
|
|||||||
@@ -0,0 +1,301 @@
|
|||||||
|
"""Check the image storage rules without a bucket.
|
||||||
|
|
||||||
|
Run it with no server and no object store::
|
||||||
|
|
||||||
|
.venv/bin/python scripts/check_storage.py
|
||||||
|
|
||||||
|
``smoke_images.py`` proves the endpoints work against a real MinIO; this one
|
||||||
|
checks the rules that decide *what may be stored and served at all*, which are
|
||||||
|
the rules that fail silently. A format sniffed from the wrong offset, a key
|
||||||
|
pattern that lets one more shape through, a `Cache-Control` that promises
|
||||||
|
immutability the key does not provide — none of those break the happy path a
|
||||||
|
smoke test walks, and each of them is a way to serve something other than what
|
||||||
|
was uploaded.
|
||||||
|
|
||||||
|
boto3's client is replaced by a stub here, so nothing here needs credentials or
|
||||||
|
network. It exits non-zero on the first failed expectation.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import sys
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
# Running this as a plain script puts scripts/ on sys.path, not backend/, so
|
||||||
|
# `import app` would fail. Anchor to the backend directory instead.
|
||||||
|
BACKEND_DIR = Path(__file__).resolve().parents[1]
|
||||||
|
if str(BACKEND_DIR) not in sys.path:
|
||||||
|
sys.path.insert(0, str(BACKEND_DIR))
|
||||||
|
|
||||||
|
from botocore.exceptions import ClientError # noqa: E402
|
||||||
|
|
||||||
|
from app.core.config import Settings # noqa: E402
|
||||||
|
from app.core.storage import ( # noqa: E402
|
||||||
|
IMAGE_FORMATS,
|
||||||
|
ImageNotFound,
|
||||||
|
ImageStore,
|
||||||
|
StorageUnavailable,
|
||||||
|
UnsupportedImage,
|
||||||
|
content_type_for,
|
||||||
|
image_url,
|
||||||
|
is_key,
|
||||||
|
markdown_for,
|
||||||
|
sniff,
|
||||||
|
)
|
||||||
|
|
||||||
|
_checks = 0
|
||||||
|
|
||||||
|
|
||||||
|
def check(label: str, condition: bool, detail: str = "") -> None:
|
||||||
|
"""Assert one expectation and report it."""
|
||||||
|
global _checks
|
||||||
|
_checks += 1
|
||||||
|
if not condition:
|
||||||
|
raise AssertionError(f"{label}: {detail}")
|
||||||
|
print(f" ok {label}")
|
||||||
|
|
||||||
|
|
||||||
|
def equal(label: str, actual: object, expected: object) -> None:
|
||||||
|
"""Assert one value, showing both sides when it differs."""
|
||||||
|
check(label, actual == expected, f"{actual!r} != {expected!r}")
|
||||||
|
|
||||||
|
|
||||||
|
# --- stubs -------------------------------------------------------------------
|
||||||
|
|
||||||
|
|
||||||
|
class FakeBody:
|
||||||
|
"""A boto3 streaming body that says whether it was closed."""
|
||||||
|
|
||||||
|
def __init__(self, data: bytes) -> None:
|
||||||
|
self.data = data
|
||||||
|
self.closed = False
|
||||||
|
|
||||||
|
def iter_chunks(self, size: int):
|
||||||
|
for start in range(0, len(self.data), size):
|
||||||
|
yield self.data[start : start + size]
|
||||||
|
|
||||||
|
def close(self) -> None:
|
||||||
|
self.closed = True
|
||||||
|
|
||||||
|
|
||||||
|
class FakeClient:
|
||||||
|
"""The four calls :class:`ImageStore` makes, with the answers we choose."""
|
||||||
|
|
||||||
|
def __init__(self, *, head_error: str | None = None, get_error: str | None = None) -> None:
|
||||||
|
self.head_error = head_error
|
||||||
|
self.get_error = get_error
|
||||||
|
self.created: list[str] = []
|
||||||
|
self.puts: list[dict] = []
|
||||||
|
self.body = FakeBody(b"stored bytes")
|
||||||
|
self.heads: list[str] = []
|
||||||
|
|
||||||
|
def head_bucket(self, Bucket: str): # noqa: N803 — boto3's own keyword names
|
||||||
|
self.heads.append(Bucket)
|
||||||
|
if self.head_error:
|
||||||
|
raise ClientError({"Error": {"Code": self.head_error, "Message": "stub"}}, "HeadBucket")
|
||||||
|
return {}
|
||||||
|
|
||||||
|
def create_bucket(self, Bucket: str): # noqa: N803
|
||||||
|
self.created.append(Bucket)
|
||||||
|
return {}
|
||||||
|
|
||||||
|
def put_object(self, **kwargs):
|
||||||
|
self.puts.append(kwargs)
|
||||||
|
return {}
|
||||||
|
|
||||||
|
def get_object(self, Bucket: str, Key: str): # noqa: N803
|
||||||
|
if self.get_error:
|
||||||
|
raise ClientError({"Error": {"Code": self.get_error, "Message": "stub"}}, "GetObject")
|
||||||
|
return {"Body": self.body, "ContentLength": len(self.body.data)}
|
||||||
|
|
||||||
|
|
||||||
|
def store(client: FakeClient | None = None, **overrides) -> ImageStore:
|
||||||
|
"""A store whose boto3 client is the stub, so nothing leaves this process."""
|
||||||
|
settings = Settings(
|
||||||
|
minio_endpoint="http://minio.test:9000",
|
||||||
|
minio_access_key="test-key",
|
||||||
|
minio_secret_key="test-secret",
|
||||||
|
minio_bucket="paper-images",
|
||||||
|
**overrides,
|
||||||
|
)
|
||||||
|
instance = ImageStore(settings)
|
||||||
|
if client is not None:
|
||||||
|
instance._client = client # noqa: SLF001 — the seam this script exists to use
|
||||||
|
return instance
|
||||||
|
|
||||||
|
|
||||||
|
# --- the formats -------------------------------------------------------------
|
||||||
|
|
||||||
|
PNG = b"\x89PNG\r\n\x1a\n" + b"0" * 32
|
||||||
|
JPEG = b"\xff\xd8\xff\xe0" + b"0" * 32
|
||||||
|
GIF87 = b"GIF87a" + b"0" * 32
|
||||||
|
GIF89 = b"GIF89a" + b"0" * 32
|
||||||
|
WEBP = b"RIFF" + b"\x00\x00\x00\x00" + b"WEBP" + b"0" * 32
|
||||||
|
|
||||||
|
|
||||||
|
def main() -> int:
|
||||||
|
print("1. the format is read from the bytes")
|
||||||
|
equal("a PNG is a PNG", sniff(PNG), "png")
|
||||||
|
equal("a JPEG is a JPEG", sniff(JPEG), "jpeg")
|
||||||
|
equal("GIF87a", sniff(GIF87), "gif")
|
||||||
|
equal("GIF89a", sniff(GIF89), "gif")
|
||||||
|
equal("RIFF….WEBP", sniff(WEBP), "webp")
|
||||||
|
equal("every accepted format has a type and an extension", len(IMAGE_FORMATS), 4)
|
||||||
|
|
||||||
|
print("2. what is refused, whatever it claims to be")
|
||||||
|
for label, data in [
|
||||||
|
("an SVG", b'<svg xmlns="http://www.w3.org/2000/svg"></svg>'),
|
||||||
|
("a PHP file renamed to .png", b"<?php echo 1; ?>"),
|
||||||
|
("HTML", b"<!DOCTYPE html><html></html>"),
|
||||||
|
("a PDF", b"%PDF-1.7\n"),
|
||||||
|
("an empty file", b""),
|
||||||
|
("four bytes that begin like a RIFF but are not WEBP", b"RIFF\x00\x00\x00\x00AVI "),
|
||||||
|
]:
|
||||||
|
try:
|
||||||
|
sniff(data)
|
||||||
|
check(f"{label} is refused", False, "it was accepted")
|
||||||
|
except UnsupportedImage as error:
|
||||||
|
check(f"{label} is refused", "SVG" in str(error) or "格式" in str(error), str(error))
|
||||||
|
|
||||||
|
print("3. the served key space is exactly what we write")
|
||||||
|
ours = "2026/09/9f8c1a4b7e2d0c33.png"
|
||||||
|
check("our own key is servable", is_key(ours), ours)
|
||||||
|
equal("…and its content type comes from the extension", content_type_for(ours), "image/png")
|
||||||
|
equal("a .jpg key", content_type_for("2026/09/9f8c1a4b7e2d0c33.jpg"), "image/jpeg")
|
||||||
|
|
||||||
|
for label, key in [
|
||||||
|
("another bucket's layout", "mattermost/20260724/teams/logo.png"),
|
||||||
|
("a key with no date", "9f8c1a4b7e2d0c33.png"),
|
||||||
|
("a traversal attempt", "2026/09/../../../etc/passwd"),
|
||||||
|
("a nested path", "2026/09/extra/9f8c1a4b7e2d0c33.png"),
|
||||||
|
("an uppercase digest", "2026/09/9F8C1A4B7E2D0C33.png"),
|
||||||
|
("a digest that is too short", "2026/09/9f8c.png"),
|
||||||
|
("a format we would not serve", "2026/09/9f8c1a4b7e2d0c33.svg"),
|
||||||
|
("an extension we would not serve", "2026/09/9f8c1a4b7e2d0c33.bmp"),
|
||||||
|
("a double extension", "2026/09/9f8c1a4b7e2d0c33.png.html"),
|
||||||
|
("a month that is not a month", "2026/9/9f8c1a4b7e2d0c33.png"),
|
||||||
|
]:
|
||||||
|
check(f"{label} is refused", not is_key(key), key)
|
||||||
|
equal(f"…and {label} has no content type", content_type_for(key), None)
|
||||||
|
|
||||||
|
print("4. the URL and the Markdown a sentence keeps")
|
||||||
|
settings = Settings(api_prefix="/api", minio_bucket="paper-images")
|
||||||
|
equal("the URL is the API's own path", image_url(ours, settings), f"/api/images/{ours}")
|
||||||
|
equal(
|
||||||
|
"the Markdown carries the caption",
|
||||||
|
markdown_for(ours, "试验装置", settings),
|
||||||
|
f"",
|
||||||
|
)
|
||||||
|
equal(
|
||||||
|
"a caption cannot close the brackets early",
|
||||||
|
markdown_for(ours, "a]b(c)", settings),
|
||||||
|
f"",
|
||||||
|
)
|
||||||
|
equal("an empty caption is allowed", markdown_for(ours, "", settings), f"")
|
||||||
|
equal(
|
||||||
|
"the prefix follows the settings",
|
||||||
|
image_url(ours, Settings(api_prefix="/v2")),
|
||||||
|
f"/v2/images/{ours}",
|
||||||
|
)
|
||||||
|
|
||||||
|
print("5. unconfigured storage refuses in the API's words")
|
||||||
|
bare = ImageStore(Settings(minio_endpoint="", minio_access_key="", minio_secret_key=""))
|
||||||
|
for label, call in [
|
||||||
|
("save", lambda: bare.save(PNG)),
|
||||||
|
("stream", lambda: bare.stream(ours)),
|
||||||
|
]:
|
||||||
|
try:
|
||||||
|
call()
|
||||||
|
check(f"{label} without credentials is refused", False, "it went ahead")
|
||||||
|
except StorageUnavailable as error:
|
||||||
|
check(
|
||||||
|
f"{label} without credentials names the missing variables",
|
||||||
|
"MINIO_ENDPOINT" in str(error),
|
||||||
|
str(error),
|
||||||
|
)
|
||||||
|
|
||||||
|
print("6. storing asks MinIO for exactly what we intend")
|
||||||
|
client = FakeClient(head_error="404")
|
||||||
|
saved = store(client)
|
||||||
|
key, content_type, digest = saved.save(PNG)
|
||||||
|
check("the key is the digest", digest[:16] in key, key)
|
||||||
|
check("…with the right extension", key.endswith(".png"), key)
|
||||||
|
check("…and a servable shape", is_key(key), key)
|
||||||
|
equal("the type is the sniffed one", content_type, "image/png")
|
||||||
|
equal("it looked for the bucket once", len(client.heads), 1)
|
||||||
|
equal("and created it, because it was missing", client.created, ["paper-images"])
|
||||||
|
put = client.puts[0]
|
||||||
|
equal("the bucket", put["Bucket"], "paper-images")
|
||||||
|
equal("the key", put["Key"], key)
|
||||||
|
equal("the bytes", put["Body"], PNG)
|
||||||
|
equal("the content type", put["ContentType"], "image/png")
|
||||||
|
check(
|
||||||
|
"the cache promise matches the content-addressed key",
|
||||||
|
"immutable" in put["CacheControl"],
|
||||||
|
put["CacheControl"],
|
||||||
|
)
|
||||||
|
|
||||||
|
print("7. the same bytes are the same object")
|
||||||
|
again = FakeClient()
|
||||||
|
key_again, _, digest_again = store(again).save(PNG)
|
||||||
|
equal("same key", key_again, key)
|
||||||
|
equal("same digest", digest_again, digest)
|
||||||
|
other = FakeClient()
|
||||||
|
key_other, _, _ = store(other).save(PNG + b"x")
|
||||||
|
check("different bytes are a different object", key_other != key, key_other)
|
||||||
|
|
||||||
|
print("8. a key that may not look at the bucket still works")
|
||||||
|
# A least-privilege key (PutObject / GetObject, no ListBucket) gets a 403
|
||||||
|
# from HeadBucket. Treating that as "the bucket is missing" would turn a
|
||||||
|
# working key into a 503, so the upload has to carry on.
|
||||||
|
denied = FakeClient(head_error="403")
|
||||||
|
store(denied).save(PNG)
|
||||||
|
equal("it did not try to create the bucket", denied.created, [])
|
||||||
|
equal("but it did store the object", len(denied.puts), 1)
|
||||||
|
|
||||||
|
print("9. reading refuses first, translates second")
|
||||||
|
for label, key in [("a key we did not write", "mattermost/logo.png")]:
|
||||||
|
try:
|
||||||
|
store(FakeClient()).stream(key)
|
||||||
|
check(f"{label} is refused", False, "it was served")
|
||||||
|
except ImageNotFound:
|
||||||
|
check(f"{label} is refused before boto3 is asked", True)
|
||||||
|
|
||||||
|
try:
|
||||||
|
store(FakeClient(get_error="NoSuchKey")).stream(ours)
|
||||||
|
check("a missing object is ImageNotFound", False, "it was served")
|
||||||
|
except ImageNotFound:
|
||||||
|
check("a missing object is ImageNotFound", True)
|
||||||
|
|
||||||
|
streaming_client = FakeClient()
|
||||||
|
chunks, stream_type, length = store(streaming_client).stream(ours)
|
||||||
|
body = b"".join(chunks)
|
||||||
|
equal("the bytes come back", body, b"stored bytes")
|
||||||
|
equal("with their type", stream_type, "image/png")
|
||||||
|
equal("and their length", length, len(b"stored bytes"))
|
||||||
|
check("the connection is released", streaming_client.body.closed)
|
||||||
|
|
||||||
|
print("10. a wrong endpoint is reported, not raised as a stack trace")
|
||||||
|
try:
|
||||||
|
ImageStore(
|
||||||
|
Settings(
|
||||||
|
minio_endpoint="http://127.0.0.1:1",
|
||||||
|
minio_access_key="k",
|
||||||
|
minio_secret_key="s",
|
||||||
|
minio_bucket="paper-images",
|
||||||
|
)
|
||||||
|
).save(PNG)
|
||||||
|
check("an unreachable endpoint is StorageUnavailable", False, "it went ahead")
|
||||||
|
except StorageUnavailable as error:
|
||||||
|
check(
|
||||||
|
"an unreachable endpoint is StorageUnavailable",
|
||||||
|
"连不上" in str(error) or "对象存储" in str(error),
|
||||||
|
str(error),
|
||||||
|
)
|
||||||
|
|
||||||
|
print(f"\nall {_checks} checks passed")
|
||||||
|
return 0
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
sys.exit(main())
|
||||||
@@ -23,8 +23,10 @@ Exits non-zero on the first failed expectation and cleans up after itself.
|
|||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
import argparse
|
import argparse
|
||||||
|
import base64
|
||||||
import json
|
import json
|
||||||
import os
|
import os
|
||||||
|
import re
|
||||||
import sys
|
import sys
|
||||||
from collections.abc import AsyncIterator, Iterator
|
from collections.abc import AsyncIterator, Iterator
|
||||||
from contextlib import asynccontextmanager, contextmanager
|
from contextlib import asynccontextmanager, contextmanager
|
||||||
@@ -43,10 +45,21 @@ from mcp.client.stdio import StdioServerParameters, stdio_client # noqa: E402
|
|||||||
from sqlalchemy import or_, select # noqa: E402
|
from sqlalchemy import or_, select # noqa: E402
|
||||||
|
|
||||||
from app.db.session import SessionLocal # noqa: E402
|
from app.db.session import SessionLocal # noqa: E402
|
||||||
|
from app.mcp.specs import SentenceSpec # noqa: E402
|
||||||
from app.models import Paper, Reference, ReferenceTag, Template # noqa: E402
|
from app.models import Paper, Reference, ReferenceTag, Template # noqa: E402
|
||||||
|
from app.schemas.paper import SentenceInput # noqa: E402
|
||||||
|
|
||||||
SERVER_SCRIPT = BACKEND_DIR / "scripts" / "mcp_server.py"
|
SERVER_SCRIPT = BACKEND_DIR / "scripts" / "mcp_server.py"
|
||||||
|
|
||||||
|
#: A 1x1 GIF, and something that is definitely not a picture. Both are inline
|
||||||
|
#: rather than files on disk: the suite has to run from a checkout with nothing
|
||||||
|
#: beside it, and a fixture that cannot go missing cannot fail for the wrong
|
||||||
|
#: reason.
|
||||||
|
GIF_1PX_BASE64 = "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
|
||||||
|
NOT_A_PICTURE_BASE64 = base64.b64encode(
|
||||||
|
b'<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>'
|
||||||
|
).decode()
|
||||||
|
|
||||||
_checks = 0
|
_checks = 0
|
||||||
_created_papers: list[int] = []
|
_created_papers: list[int] = []
|
||||||
_created_templates: list[int] = []
|
_created_templates: list[int] = []
|
||||||
@@ -169,7 +182,7 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
|
|||||||
print("\n1. tool discovery")
|
print("\n1. tool discovery")
|
||||||
listed = await session.list_tools()
|
listed = await session.list_tools()
|
||||||
names = {tool.name for tool in listed.tools}
|
names = {tool.name for tool in listed.tools}
|
||||||
check("the whole surface is published", len(names) == 41, f"got {len(names)}")
|
check("the whole surface is published", len(names) == 42, f"got {len(names)}")
|
||||||
check(
|
check(
|
||||||
"every group is reachable",
|
"every group is reachable",
|
||||||
{
|
{
|
||||||
@@ -180,10 +193,33 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
|
|||||||
"field_list",
|
"field_list",
|
||||||
"reference_create",
|
"reference_create",
|
||||||
"reference_tag_create",
|
"reference_tag_create",
|
||||||
|
"image_upload",
|
||||||
}
|
}
|
||||||
<= names,
|
<= names,
|
||||||
", ".join(sorted(names)),
|
", ".join(sorted(names)),
|
||||||
)
|
)
|
||||||
|
# The prefix is how a model finds a tool in a list of forty: a tool whose
|
||||||
|
# name does not start with its group's prefix is a tool nothing reaches
|
||||||
|
# for, and the mistake is invisible in every other check.
|
||||||
|
check(
|
||||||
|
"every tool name starts with its group's prefix",
|
||||||
|
all(
|
||||||
|
name.startswith(
|
||||||
|
(
|
||||||
|
"paper_",
|
||||||
|
"paragraph_",
|
||||||
|
"sentence_",
|
||||||
|
"template_",
|
||||||
|
"field_",
|
||||||
|
"reference_",
|
||||||
|
"reference_tag_",
|
||||||
|
"image_",
|
||||||
|
)
|
||||||
|
)
|
||||||
|
for name in names
|
||||||
|
),
|
||||||
|
", ".join(sorted(names)),
|
||||||
|
)
|
||||||
check(
|
check(
|
||||||
"no tool returns a structured envelope",
|
"no tool returns a structured envelope",
|
||||||
all(tool.output_schema is None for tool in listed.tools),
|
all(tool.output_schema is None for tool in listed.tools),
|
||||||
@@ -193,6 +229,24 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
|
|||||||
"paper_write describes its paragraph array",
|
"paper_write describes its paragraph array",
|
||||||
"paragraphs" in write_tool.input_schema["properties"],
|
"paragraphs" in write_tool.input_schema["properties"],
|
||||||
)
|
)
|
||||||
|
# A sentence column that this surface does not declare is a column no
|
||||||
|
# model can set — which is exactly how `line_break_before` and then
|
||||||
|
# `formula_align` were lost: the write succeeded and the field was
|
||||||
|
# silently gone. Declaring every field is one line; forgetting one fails
|
||||||
|
# here.
|
||||||
|
missing = set(SentenceInput.model_fields) - set(SentenceSpec.model_fields)
|
||||||
|
check(
|
||||||
|
"the sentence schema declares every writable field of a sentence",
|
||||||
|
not missing,
|
||||||
|
f"missing from SentenceSpec: {sorted(missing)}",
|
||||||
|
)
|
||||||
|
add_tool = next(tool for tool in listed.tools if tool.name == "sentence_add")
|
||||||
|
align = add_tool.input_schema["properties"]["formula_align"]
|
||||||
|
check(
|
||||||
|
"and a formula's alignment is an enum, so a model cannot invent one",
|
||||||
|
align.get("enum") == ["center", "left", "right"],
|
||||||
|
json.dumps(align, ensure_ascii=False),
|
||||||
|
)
|
||||||
|
|
||||||
print("\n2. create a paper on that template")
|
print("\n2. create a paper on that template")
|
||||||
paper = await call(
|
paper = await call(
|
||||||
@@ -864,7 +918,254 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
|
|||||||
repr(as_text["text"][-300:]),
|
repr(as_text["text"][-300:]),
|
||||||
)
|
)
|
||||||
|
|
||||||
print("\n18. move a paragraph, then clear the one it moved onto")
|
print("\n18. a figure goes in, and prints on a line of its own")
|
||||||
|
# The bytes go to the object store and the sentence keeps the address,
|
||||||
|
# so this is the one place the suite needs MinIO as well as the database.
|
||||||
|
# The 1x1 GIF is the smallest real picture there is, which is all that is
|
||||||
|
# needed to prove the bytes arrive and the address comes back.
|
||||||
|
figure = await call(
|
||||||
|
session,
|
||||||
|
"image_upload",
|
||||||
|
data_base64=f"data:image/gif;base64,{GIF_1PX_BASE64}",
|
||||||
|
caption="图 1 试验装置示意图",
|
||||||
|
width="70%",
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"the key is the shape the store writes, named after the bytes",
|
||||||
|
re.fullmatch(r"\d{4}/\d{2}/[0-9a-f]{16}\.gif", figure["key"]) is not None,
|
||||||
|
figure["key"],
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"the URL is same-origin under the API prefix",
|
||||||
|
figure["url"] == f"/api/images/{figure['key']}",
|
||||||
|
figure["url"],
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"the markdown is the sentence's content, caption and size included",
|
||||||
|
figure["markdown"]
|
||||||
|
== f"{{width=70%}}",
|
||||||
|
figure["markdown"],
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"and the sentence that shows it is ready to write as it stands",
|
||||||
|
figure["sentence"]
|
||||||
|
== {
|
||||||
|
"content": figure["markdown"],
|
||||||
|
"line_break_before": True,
|
||||||
|
"formula_align": "center",
|
||||||
|
},
|
||||||
|
json.dumps(figure["sentence"], ensure_ascii=False),
|
||||||
|
)
|
||||||
|
|
||||||
|
same = await call(
|
||||||
|
session, "image_upload", data_base64=GIF_1PX_BASE64, filename="另一张.png"
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"the same picture again is the same object, not a second copy",
|
||||||
|
same["key"] == figure["key"],
|
||||||
|
f"{same['key']} vs {figure['key']}",
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"and the caption defaults to the filename's stem",
|
||||||
|
same["markdown"] == f"",
|
||||||
|
same["markdown"],
|
||||||
|
)
|
||||||
|
|
||||||
|
# The returned sentence object is written as it came back, unchanged:
|
||||||
|
# that is the whole contract of the tool.
|
||||||
|
await call(
|
||||||
|
session,
|
||||||
|
"sentence_add",
|
||||||
|
paper_id=paper["id"],
|
||||||
|
heading=outline[3]["name"],
|
||||||
|
**figure["sentence"],
|
||||||
|
)
|
||||||
|
with_figure = await call(
|
||||||
|
session, "paragraph_get", paper_id=paper["id"], heading=outline[3]["name"]
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"the figure is stored as the sentence it was handed",
|
||||||
|
with_figure["sentences"][-1]["content"] == figure["markdown"]
|
||||||
|
and with_figure["sentences"][-1]["line_break_before"] is True,
|
||||||
|
json.dumps(with_figure["sentences"][-1], ensure_ascii=False),
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"and the paragraph prints it alone on its own line",
|
||||||
|
with_figure["text"].endswith("\n" + figure["markdown"]),
|
||||||
|
repr(with_figure["text"][-200:]),
|
||||||
|
)
|
||||||
|
|
||||||
|
inline_url = same["url"]
|
||||||
|
inline = f"试验装置如  所示。"
|
||||||
|
await call(
|
||||||
|
session,
|
||||||
|
"sentence_add",
|
||||||
|
paper_id=paper["id"],
|
||||||
|
heading=outline[3]["name"],
|
||||||
|
content=inline,
|
||||||
|
)
|
||||||
|
with_inline = await call(
|
||||||
|
session, "paragraph_get", paper_id=paper["id"], heading=outline[3]["name"]
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"an image inside a sentence stays on the line with the words",
|
||||||
|
f"\n{inline}" in with_inline["text"]
|
||||||
|
and f"\n" not in with_inline["text"],
|
||||||
|
repr(with_inline["text"][-260:]),
|
||||||
|
)
|
||||||
|
|
||||||
|
message = await expect_error(
|
||||||
|
session,
|
||||||
|
"image_upload",
|
||||||
|
data_base64=NOT_A_PICTURE_BASE64,
|
||||||
|
filename="图.svg",
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"a file that is not a picture is refused, naming the formats",
|
||||||
|
"PNG" in message and "SVG" in message,
|
||||||
|
message,
|
||||||
|
)
|
||||||
|
tolerant = await call(
|
||||||
|
session,
|
||||||
|
"image_upload",
|
||||||
|
data_base64=GIF_1PX_BASE64,
|
||||||
|
caption="写法宽容",
|
||||||
|
width="{w = 400 px}",
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"how the size is written is forgiving, what it means is not",
|
||||||
|
tolerant["markdown"] == f"{{width=400px}}",
|
||||||
|
tolerant["markdown"],
|
||||||
|
)
|
||||||
|
bare = await call(
|
||||||
|
session, "image_upload", data_base64=GIF_1PX_BASE64, caption="只写数字", width="60"
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"a bare number means a share of the column, as it does in the page",
|
||||||
|
bare["markdown"] == f"{{width=60%}}",
|
||||||
|
bare["markdown"],
|
||||||
|
)
|
||||||
|
|
||||||
|
# A height, which is how a tall panel is made short: the width follows
|
||||||
|
# the picture's own shape rather than being stretched to fit.
|
||||||
|
sized = await call(
|
||||||
|
session,
|
||||||
|
"image_upload",
|
||||||
|
data_base64=GIF_1PX_BASE64,
|
||||||
|
caption="宽高都写",
|
||||||
|
width="70%",
|
||||||
|
height="300",
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"a height is written beside the width, in pixels",
|
||||||
|
sized["markdown"]
|
||||||
|
== f"{{width=70% height=300px}}",
|
||||||
|
sized["markdown"],
|
||||||
|
)
|
||||||
|
tall = await call(
|
||||||
|
session, "image_upload", data_base64=GIF_1PX_BASE64, caption="只限高", height="240px"
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"a height on its own is enough",
|
||||||
|
tall["markdown"] == f"{{height=240px}}",
|
||||||
|
tall["markdown"],
|
||||||
|
)
|
||||||
|
message = await expect_error(
|
||||||
|
session, "image_upload", data_base64=GIF_1PX_BASE64, height="50%"
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"a percentage height is refused, with the reason it cannot work",
|
||||||
|
"没有参照物" in message,
|
||||||
|
message,
|
||||||
|
)
|
||||||
|
message = await expect_error(
|
||||||
|
session, "image_upload", data_base64=GIF_1PX_BASE64, width="70em"
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"a size the reader cannot parse is refused rather than quietly ignored",
|
||||||
|
"70%" in message,
|
||||||
|
message,
|
||||||
|
)
|
||||||
|
message = await expect_error(
|
||||||
|
session, "image_upload", data_base64=GIF_1PX_BASE64, width="150%"
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"and so is one that parses but the page would drop on the floor",
|
||||||
|
"1 到 100" in message,
|
||||||
|
message,
|
||||||
|
)
|
||||||
|
message = await expect_error(
|
||||||
|
session, "image_upload", data_base64="这不是 base64"
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"and a value that is not base64 says what to send instead",
|
||||||
|
"base64" in message,
|
||||||
|
message,
|
||||||
|
)
|
||||||
|
|
||||||
|
print("\n19. a formula says how it is set on its line")
|
||||||
|
derivation = outline[2]
|
||||||
|
await call(
|
||||||
|
session,
|
||||||
|
"paper_write",
|
||||||
|
paper_id=paper["id"],
|
||||||
|
paragraphs=[
|
||||||
|
{
|
||||||
|
"heading": derivation["name"],
|
||||||
|
"sentences": [
|
||||||
|
"推导如下。",
|
||||||
|
{
|
||||||
|
"content": "$$ a^2 + b^2 = c^2 $$",
|
||||||
|
"line_break_before": True,
|
||||||
|
"formula_align": "right",
|
||||||
|
},
|
||||||
|
],
|
||||||
|
}
|
||||||
|
],
|
||||||
|
)
|
||||||
|
aligned = await call(
|
||||||
|
session, "paragraph_get", paper_id=paper["id"], heading=derivation["name"]
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"the alignment is stored on the sentence that carries the formula",
|
||||||
|
[row["formula_align"] for row in aligned["sentences"]]
|
||||||
|
== ["center", "right"],
|
||||||
|
json.dumps(aligned["sentences"], ensure_ascii=False),
|
||||||
|
)
|
||||||
|
turned = await call(
|
||||||
|
session,
|
||||||
|
"sentence_update",
|
||||||
|
paper_id=paper["id"],
|
||||||
|
sentence_id=aligned["sentences"][-1]["id"],
|
||||||
|
formula_align="left",
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"and it can be changed without touching the formula",
|
||||||
|
turned["sentence"]["formula_align"] == "left"
|
||||||
|
and turned["sentence"]["content"] == "$$ a^2 + b^2 = c^2 $$",
|
||||||
|
json.dumps(turned["sentence"], ensure_ascii=False),
|
||||||
|
)
|
||||||
|
await call(
|
||||||
|
session,
|
||||||
|
"paragraph_move",
|
||||||
|
paper_id=paper["id"],
|
||||||
|
heading=derivation["name"],
|
||||||
|
target_heading=outline[3]["name"],
|
||||||
|
)
|
||||||
|
carried = await call(
|
||||||
|
session, "paragraph_get", paper_id=paper["id"], heading=outline[3]["name"]
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
"and it travels with the sentence when the paragraph moves",
|
||||||
|
any(
|
||||||
|
row["content"] == "$$ a^2 + b^2 = c^2 $$"
|
||||||
|
and row["formula_align"] == "left"
|
||||||
|
for row in carried["sentences"]
|
||||||
|
),
|
||||||
|
json.dumps(carried["sentences"], ensure_ascii=False),
|
||||||
|
)
|
||||||
|
|
||||||
|
print("\n20. move a paragraph, then clear the one it moved onto")
|
||||||
home = outline[0]
|
home = outline[0]
|
||||||
target = outline[1]
|
target = outline[1]
|
||||||
relocation = await call(
|
relocation = await call(
|
||||||
@@ -896,7 +1197,7 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
|
|||||||
after_clear = await call(session, "paragraph_get", paper_id=paper["id"], position=target["position"])
|
after_clear = await call(session, "paragraph_get", paper_id=paper["id"], position=target["position"])
|
||||||
check("and the paragraph is empty", after_clear["sentences"] == [], json.dumps(after_clear, ensure_ascii=False))
|
check("and the paragraph is empty", after_clear["sentences"] == [], json.dumps(after_clear, ensure_ascii=False))
|
||||||
|
|
||||||
print("\n19. the field library round-trips")
|
print("\n21. the field library round-trips")
|
||||||
field = await call(session, "field_create", name="SMOKE MCP 字段", level=2, font_size=9.5)
|
field = await call(session, "field_create", name="SMOKE MCP 字段", level=2, font_size=9.5)
|
||||||
check("created with its typography", field["level"] == 2 and field["font_size"] == 9.5, json.dumps(field, ensure_ascii=False))
|
check("created with its typography", field["level"] == 2 and field["font_size"] == 9.5, json.dumps(field, ensure_ascii=False))
|
||||||
renamed = await call(session, "field_update", field_id=field["id"], name="SMOKE MCP 字段(改)")
|
renamed = await call(session, "field_update", field_id=field["id"], name="SMOKE MCP 字段(改)")
|
||||||
@@ -905,7 +1206,7 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
|
|||||||
check("deleted while no template places it", dropped["deleted"] == 1, json.dumps(dropped, ensure_ascii=False))
|
check("deleted while no template places it", dropped["deleted"] == 1, json.dumps(dropped, ensure_ascii=False))
|
||||||
check("and it is reported as found, not missing", dropped["missing"] == [], json.dumps(dropped, ensure_ascii=False))
|
check("and it is reported as found, not missing", dropped["missing"] == [], json.dumps(dropped, ensure_ascii=False))
|
||||||
|
|
||||||
print("\n20. switch the template and keep the content")
|
print("\n22. switch the template and keep the content")
|
||||||
spare = await call(
|
spare = await call(
|
||||||
session,
|
session,
|
||||||
"template_create",
|
"template_create",
|
||||||
@@ -949,15 +1250,15 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
|
|||||||
json.dumps(switched_document, ensure_ascii=False)[:400],
|
json.dumps(switched_document, ensure_ascii=False)[:400],
|
||||||
)
|
)
|
||||||
|
|
||||||
print("\n21. a template in use cannot be deleted")
|
print("\n23. a template in use cannot be deleted")
|
||||||
message = await expect_error(session, "template_delete", template_ids=spare["id"])
|
message = await expect_error(session, "template_delete", template_ids=spare["id"])
|
||||||
check("the refusal names the blocker", "SMOKE MCP 模板" in message, message)
|
check("the refusal names the blocker", "SMOKE MCP 模板" in message, message)
|
||||||
|
|
||||||
print("\n22. deleting a paper needs an explicit confirmation")
|
print("\n24. deleting a paper needs an explicit confirmation")
|
||||||
message = await expect_error(session, "paper_delete", paper_ids=paper["id"])
|
message = await expect_error(session, "paper_delete", paper_ids=paper["id"])
|
||||||
check("the refusal explains itself", "confirm=true" in message, message)
|
check("the refusal explains itself", "confirm=true" in message, message)
|
||||||
|
|
||||||
print("\n23. delete the paper and the template")
|
print("\n25. delete the paper and the template")
|
||||||
deleted = await call(session, "paper_delete", paper_ids=paper["id"], confirm=True)
|
deleted = await call(session, "paper_delete", paper_ids=paper["id"], confirm=True)
|
||||||
check("deleted", deleted["deleted"] == 1, json.dumps(deleted, ensure_ascii=False))
|
check("deleted", deleted["deleted"] == 1, json.dumps(deleted, ensure_ascii=False))
|
||||||
_created_papers.remove(paper["id"])
|
_created_papers.remove(paper["id"])
|
||||||
|
|||||||
+11
-5
@@ -14,20 +14,26 @@ paper-doc 的 MCP 服务跑在 k3s 里,命名空间 **`paper-doc`**,客户
|
|||||||
| Namespace | `paper-doc` | `deploy/k8s/00-namespace.yaml` |
|
| Namespace | `paper-doc` | `deploy/k8s/00-namespace.yaml` |
|
||||||
| Deployment | `paper-doc-mcp` | 1 副本,跑 MCP 服务的 http 传输 |
|
| Deployment | `paper-doc-mcp` | 1 副本,跑 MCP 服务的 http 传输 |
|
||||||
| Service | `paper-doc-mcp` | NodePort **30931** → 容器 8931 |
|
| Service | `paper-doc-mcp` | NodePort **30931** → 容器 8931 |
|
||||||
| ConfigMap | `paper-doc-config` | 非敏感环境变量(数据库地址、监听配置) |
|
| ConfigMap | `paper-doc-config` | 非敏感环境变量(数据库地址、监听配置、MinIO 端点与桶名) |
|
||||||
| Secret | `paper-doc-secrets` | `DB_USER` / `DB_PASSWORD` / `MCP_HTTP_TOKEN` |
|
| Secret | `paper-doc-secrets` | `DB_USER` / `DB_PASSWORD` / `MCP_HTTP_TOKEN` / `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` |
|
||||||
| Secret | `aliyun-acr` | 镜像仓库拉取凭证(从 `default` 复制) |
|
| Secret | `aliyun-acr` | 镜像仓库拉取凭证(从 `default` 复制) |
|
||||||
|
|
||||||
镜像:`registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v5`
|
镜像:`registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v8`
|
||||||
(`sha256:1e17a72ca611a498d93fc960a7fe1eba5ed5803376794efa66f1967830d51c5d`;
|
(`sha256:fbbc4b1ab91ce80a3045f2990d85357f1cc267a2644639efe522a25cf42c4bc0`;
|
||||||
`kubectl -n paper-doc get pods -o jsonpath='{.items[0].status.containerStatuses[0].imageID}'`
|
`kubectl -n paper-doc get pods -o jsonpath='{.items[0].status.containerStatuses[0].imageID}'`
|
||||||
对得上,才说明跑的就是 ACR 上那一版。历史:v1 首发布 → v2 重命名表 → v3 参考文献库 →
|
对得上,才说明跑的就是 ACR 上那一版。历史:v1 首发布 → v2 重命名表 → v3 参考文献库 →
|
||||||
v4 补参考文献 MCP 工具 → **v5 换行与参考文献表**。)
|
v4 补参考文献 MCP 工具 → v5 换行与参考文献表 → v6 插图与公式对齐 → v7 插图的宽度写法与页面一致 → **v8 插图可分别填宽与高**。)
|
||||||
|
|
||||||
**数据库**:TiDB 已经在这个集群里,Deployment 用集群内的 Service
|
**数据库**:TiDB 已经在这个集群里,Deployment 用集群内的 Service
|
||||||
`tidb-tidb.tidb:4000`,而不是宿主机用的 NodePort `192.168.1.88:32738`。
|
`tidb-tidb.tidb:4000`,而不是宿主机用的 NodePort `192.168.1.88:32738`。
|
||||||
两者是同一份数据;集群内用 Service 的好处是节点地址变了也不用改配置。
|
两者是同一份数据;集群内用 Service 的好处是节点地址变了也不用改配置。
|
||||||
|
|
||||||
|
**对象存储**:论文里的插图放在 MinIO(命名空间 `minio`,同一个集群)。
|
||||||
|
集群内用它自己的 Service `http://minio.minio.svc.cluster.local:9000`,
|
||||||
|
宿主机上开发才用 NodePort `http://192.168.1.88:30090`;两边是同一个桶 `paper-images`,
|
||||||
|
桶会在第一次上传时自动创建。少给凭证不会让服务起不来:`image_upload` 会回一句
|
||||||
|
「图片存储还没有配置好(缺少 MINIO_…)」,写作类工具照常可用。
|
||||||
|
|
||||||
## 访问地址
|
## 访问地址
|
||||||
|
|
||||||
| 从哪里连 | 地址 |
|
| 从哪里连 | 地址 |
|
||||||
|
|||||||
@@ -22,6 +22,14 @@ data:
|
|||||||
DB_NAME: paper_doc
|
DB_NAME: paper_doc
|
||||||
APP_NAME: paper-doc API
|
APP_NAME: paper-doc API
|
||||||
DEBUG: "false"
|
DEBUG: "false"
|
||||||
|
# Object storage for the images a paper embeds (MinIO, in its own namespace).
|
||||||
|
# The in-cluster Service, not the host's NodePort 30090: same bucket, and the
|
||||||
|
# address survives the node changing. The credentials live in the Secret —
|
||||||
|
# without them `image_upload` answers 「图片存储还没有配置好」 and names the
|
||||||
|
# variables, while every writing tool keeps working.
|
||||||
|
MINIO_ENDPOINT: http://minio.minio.svc.cluster.local:9000
|
||||||
|
MINIO_BUCKET: paper-images
|
||||||
|
MINIO_REGION: us-east-1
|
||||||
# The container's own defaults, restated here because the Deployment is where
|
# The container's own defaults, restated here because the Deployment is where
|
||||||
# a reader looks for them.
|
# a reader looks for them.
|
||||||
MCP_TRANSPORT: http
|
MCP_TRANSPORT: http
|
||||||
@@ -67,7 +75,7 @@ spec:
|
|||||||
type: RuntimeDefault
|
type: RuntimeDefault
|
||||||
containers:
|
containers:
|
||||||
- name: mcp
|
- name: mcp
|
||||||
image: registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v5
|
image: registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v8
|
||||||
imagePullPolicy: IfNotPresent
|
imagePullPolicy: IfNotPresent
|
||||||
ports:
|
ports:
|
||||||
- name: http
|
- name: http
|
||||||
@@ -94,6 +102,19 @@ spec:
|
|||||||
secretKeyRef:
|
secretKeyRef:
|
||||||
name: paper-doc-secrets
|
name: paper-doc-secrets
|
||||||
key: MCP_HTTP_TOKEN
|
key: MCP_HTTP_TOKEN
|
||||||
|
# The object store's credentials. A key scoped to this one bucket is
|
||||||
|
# enough: the bucket is created on the first upload, so nothing has
|
||||||
|
# to be provisioned by hand before the first figure goes in.
|
||||||
|
- name: MINIO_ACCESS_KEY
|
||||||
|
valueFrom:
|
||||||
|
secretKeyRef:
|
||||||
|
name: paper-doc-secrets
|
||||||
|
key: MINIO_ACCESS_KEY
|
||||||
|
- name: MINIO_SECRET_KEY
|
||||||
|
valueFrom:
|
||||||
|
secretKeyRef:
|
||||||
|
name: paper-doc-secrets
|
||||||
|
key: MINIO_SECRET_KEY
|
||||||
# Readiness asks the database; liveness does not. A TiDB blip should
|
# Readiness asks the database; liveness does not. A TiDB blip should
|
||||||
# take the pod out of the Service's endpoints and put it back when the
|
# take the pod out of the Service's endpoints and put it back when the
|
||||||
# blip ends — not restart a process that is working correctly.
|
# blip ends — not restart a process that is working correctly.
|
||||||
@@ -178,13 +199,14 @@ spec:
|
|||||||
# imagePullSecrets: [{name: aliyun-acr}]
|
# imagePullSecrets: [{name: aliyun-acr}]
|
||||||
# initContainers:
|
# initContainers:
|
||||||
# - name: migrate
|
# - name: migrate
|
||||||
# image: registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v5
|
# image: registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v8
|
||||||
# command: ["alembic", "upgrade", "head"]
|
# command: ["alembic", "upgrade", "head"]
|
||||||
# envFrom: [{configMapRef: {name: paper-doc-config}}]
|
# envFrom: [{configMapRef: {name: paper-doc-config}}]
|
||||||
# env: [...] # the same three secret keys as above
|
# env: [...] # the same secret keys as above; the MinIO
|
||||||
|
# # pair is what lets the API serve the figures
|
||||||
# containers:
|
# containers:
|
||||||
# - name: api
|
# - name: api
|
||||||
# image: registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v5
|
# image: registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v8
|
||||||
# command: ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
|
# command: ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
|
||||||
# ports: [{name: http, containerPort: 8000}]
|
# ports: [{name: http, containerPort: 8000}]
|
||||||
# envFrom: [{configMapRef: {name: paper-doc-config}}]
|
# envFrom: [{configMapRef: {name: paper-doc-config}}]
|
||||||
|
|||||||
@@ -5,11 +5,18 @@
|
|||||||
# kubectl -n paper-doc create secret generic paper-doc-secrets \
|
# kubectl -n paper-doc create secret generic paper-doc-secrets \
|
||||||
# --from-literal=DB_USER='Govin' \
|
# --from-literal=DB_USER='Govin' \
|
||||||
# --from-literal=DB_PASSWORD='<tidb-password>' \
|
# --from-literal=DB_PASSWORD='<tidb-password>' \
|
||||||
# --from-literal=MCP_HTTP_TOKEN="$(openssl rand -hex 32)"
|
# --from-literal=MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
|
||||||
|
# --from-literal=MINIO_ACCESS_KEY='<minio-access-key>' \
|
||||||
|
# --from-literal=MINIO_SECRET_KEY='<minio-secret-key>'
|
||||||
#
|
#
|
||||||
# Rotating the token is then one `kubectl create secret ... --dry-run=client -o
|
# Rotating the token is then one `kubectl create secret ... --dry-run=client -o
|
||||||
# yaml | kubectl apply -f -` plus a rollout restart, and no image rebuild.
|
# yaml | kubectl apply -f -` plus a rollout restart, and no image rebuild.
|
||||||
#
|
#
|
||||||
|
# The MinIO pair is what `image_upload` / `POST /api/images` needs; a key scoped
|
||||||
|
# to the one bucket is enough, and the bucket is created on the first upload.
|
||||||
|
# Without the pair every writing tool still works and the image ones answer with
|
||||||
|
# the names of the variables that are missing.
|
||||||
|
#
|
||||||
# The registry pull secret is separate and not described here: it is
|
# The registry pull secret is separate and not described here: it is
|
||||||
# `aliyun-acr`, copied into this namespace from `default`, and it holds the
|
# `aliyun-acr`, copied into this namespace from `default`, and it holds the
|
||||||
# container registry's credentials rather than the application's.
|
# container registry's credentials rather than the application's.
|
||||||
@@ -23,3 +30,5 @@ stringData:
|
|||||||
DB_USER: Govin
|
DB_USER: Govin
|
||||||
DB_PASSWORD: change-me
|
DB_PASSWORD: change-me
|
||||||
MCP_HTTP_TOKEN: change-me
|
MCP_HTTP_TOKEN: change-me
|
||||||
|
MINIO_ACCESS_KEY: change-me
|
||||||
|
MINIO_SECRET_KEY: change-me
|
||||||
|
|||||||
+143
-15
@@ -7,8 +7,8 @@
|
|||||||
用 `paragraph_write` / `sentence_update` 微调 → `paper_document` 读回来检查。
|
用 `paragraph_write` / `sentence_update` 微调 → `paper_document` 读回来检查。
|
||||||
|
|
||||||
- 代码:`backend/app/mcp/`(工具实现)、`backend/scripts/mcp_server.py`(入口)
|
- 代码:`backend/app/mcp/`(工具实现)、`backend/scripts/mcp_server.py`(入口)
|
||||||
- 冒烟测试:`backend/scripts/smoke_mcp.py`(真 MCP 客户端跑 99 项检查、覆盖 41/41 个工具,stdio 与 HTTP 都过)
|
- 冒烟测试:`backend/scripts/smoke_mcp.py`(真 MCP 客户端跑 119 项检查、覆盖 42/42 个工具,stdio 与 HTTP 都过)
|
||||||
- 工具数量:**41 个**,按 `paper_` / `paragraph_` / `sentence_` / `template_` / `field_` / `reference_` / `reference_tag_` 七组前缀
|
- 工具数量:**42 个**,按 `paper_` / `paragraph_` / `sentence_` / `template_` / `field_` / `reference_` / `reference_tag_` / `image_` 八组前缀
|
||||||
- 协议:MCP 2024-11-05 ~ 2025-11-25(官方 Python SDK `mcp>=2.2,<3` 协商)
|
- 协议:MCP 2024-11-05 ~ 2025-11-25(官方 Python SDK `mcp>=2.2,<3` 协商)
|
||||||
- 传输:`stdio`(本地拉起)与 `streamable-http`(远程连接,支持 Bearer 口令),另兼容旧 `sse`
|
- 传输:`stdio`(本地拉起)与 `streamable-http`(远程连接,支持 Bearer 口令),另兼容旧 `sse`
|
||||||
- **已经部署在 k3s 里**:命名空间 `paper-doc`,端点 `http://192.168.1.88:30931/mcp`
|
- **已经部署在 k3s 里**:命名空间 `paper-doc`,端点 `http://192.168.1.88:30931/mcp`
|
||||||
@@ -98,12 +98,14 @@ cd /data/project/paper/backend
|
|||||||
.venv/bin/python scripts/smoke_mcp.py --url http://127.0.0.1:8931/mcp --token 你的口令 # 连已有的 HTTP 服务
|
.venv/bin/python scripts/smoke_mcp.py --url http://127.0.0.1:8931/mcp --token 你的口令 # 连已有的 HTTP 服务
|
||||||
```
|
```
|
||||||
|
|
||||||
同一个套件 **99 项检查**跑两种传输,覆盖 23 个步骤:建论文 → 看骨架 → 按标题写段落 →
|
同一个套件 **119 项检查**跑两种传输,覆盖 25 个步骤:建论文 → 看骨架 → 按标题写段落 →
|
||||||
定位失败时列出候选标题 → 读段落/追加带引用的句子 → 只改一句 → 删一句 → 整篇一次写入 →
|
定位失败时列出候选标题 → 读段落/追加带引用的句子 → 只改一句 → 删一句 → 整篇一次写入 →
|
||||||
读全文 → 跨论文搜索 → **另起一行**(公式独行、标记开关、搬段落时跟着走)→ **参考文献表**
|
读全文 → 跨论文搜索 → **另起一行**(公式独行、标记开关、搬段落时跟着走)→ **参考文献表**
|
||||||
(一处引用一行、一部文献一条、正文编号与表号同号)→ 搬段落 → 清空段落 → 字段库增删改 →
|
(一处引用一行、一部文献一条、正文编号与表号同号)→ **插图**(传图、同一张图只存一份、
|
||||||
建/改模板 → 换模板后正文不丢 → 文献库增删改查与批量导入 → 引用守卫(被引用的文献删不掉)→
|
独占一行、行内图不断行、格式/尺寸/非 base64 的拒绝)→ **公式对齐**(写入、单独改、跟着搬)→
|
||||||
删模板被拒 → 删论文要确认 → 清理。写真实数据,结束时自己删干净。
|
搬段落 → 清空段落 → 字段库增删改 → 建/改模板 → 换模板后正文不丢 → 文献库增删改查与批量导入 →
|
||||||
|
引用守卫(被引用的文献删不掉)→ 删模板被拒 → 删论文要确认 → 清理。写真实数据(插图那步还需要
|
||||||
|
MinIO 可用),结束时自己删干净。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -294,11 +296,15 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
|
|||||||
| 工具 | 作用 | 关键参数 |
|
| 工具 | 作用 | 关键参数 |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| `sentence_list` | 列句子(可只列某段) | `paper_id`、`position?` `heading?` `include_empty?` |
|
| `sentence_list` | 列句子(可只列某段) | `paper_id`、`position?` `heading?` `include_empty?` |
|
||||||
| `sentence_add` | 段尾追加一句(可带引用) | `paper_id`、`content`、`position?` `heading?` `citations?` `line_break_before?` `sort?` |
|
| `sentence_add` | 段尾追加一句(可带引用) | `paper_id`、`content`、`position?` `heading?` `citations?` `line_break_before?` `formula_align?` `sort?` |
|
||||||
| `sentence_update` | 改正文 / 改所属段 / 改排序 / 改换行 / 整组换引用 | `paper_id`、`sentence_id`、`content?` `position?` `sort?` `line_break_before?` `citations?` |
|
| `sentence_update` | 改正文 / 改所属段 / 改排序 / 改换行 / 改公式对齐 / 整组换引用 | `paper_id`、`sentence_id`、`content?` `position?` `sort?` `line_break_before?` `formula_align?` `citations?` |
|
||||||
| `sentence_delete` | 删一句(连引用) | `paper_id`、`sentence_id` |
|
| `sentence_delete` | 删一句(连引用) | `paper_id`、`sentence_id` |
|
||||||
| `sentence_search` | **跨论文搜句子**(保持术语一致) | `keyword`、`paper_id?` `limit?` |
|
| `sentence_search` | **跨论文搜句子**(保持术语一致) | `keyword`、`paper_id?` `limit?` |
|
||||||
|
|
||||||
|
一句能带的字段就是这一组(`content`、`sort`、`line_break_before`、`formula_align`、`citations`,
|
||||||
|
外加写插图用的图片 Markdown)。**MCP 的工具 schema 必须声明全部字段**,`smoke_mcp.py` 第一步就查这件事——
|
||||||
|
少一个字段意味着模型能写、工具会静默丢掉,写作调用"成功"而内容不对。
|
||||||
|
|
||||||
#### 另起一行:公式、分条列举、作者行
|
#### 另起一行:公式、分条列举、作者行
|
||||||
|
|
||||||
一段是**它的句子连排**出来的,所以"不是散文的行"要自己开口。方式是在句子对象上加
|
一段是**它的句子连排**出来的,所以"不是散文的行"要自己开口。方式是在句子对象上加
|
||||||
@@ -316,16 +322,29 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
|
|||||||
三条规则:
|
三条规则:
|
||||||
|
|
||||||
1. **换行顶掉分隔符,不是叠加。** 新行本身已经把两句分开了,再加一个空格会让下一行空一格。
|
1. **换行顶掉分隔符,不是叠加。** 新行本身已经把两句分开了,再加一个空格会让下一行空一格。
|
||||||
2. **display 公式(`$$…$$` 或 `\[…\]`)自己独占一行,不必标。** 论文页面就是这么排的,
|
2. **独占一行的东西不必标。** display 公式(`$$…$$` 或 `\[…\]`)和"整句只有一张图"的插图
|
||||||
`paper_document` 的 `text` 也这么排——两处必须一致,所以模型不要去猜"这里要不要加标记"。
|
都自己占一行——论文页面就是这么排的,`paper_document` 的 `text` 也这么排,两处必须一致,
|
||||||
行内公式(`$…$`)不算,它本来就在句子里。
|
所以模型不要去猜"这里要不要加标记"。行内公式(`$…$`)和夹在句子中间的图不算。
|
||||||
3. **"请读一遍这一段"时看得到换行。** `paragraph_get` / `paper_document` 返回的 `text` 里换行就是真的换行符;
|
3. **"请读一遍这一段"时看得到换行。** `paragraph_get` / `paper_document` 返回的 `text` 里换行就是真的换行符;
|
||||||
`sentence_list` 每句还带 `line_break_before` 字段,所以搬句子之前能看出哪几句是另起的行。
|
`sentence_list` 每句还带 `line_break_before` 与 `formula_align` 字段,所以搬句子之前能看出
|
||||||
|
哪几句是另起的行、公式是怎么摆的。
|
||||||
|
|
||||||
`text` + `split` 那种整块写法也可以带 `line_break_before`,但它只作用于**切出来的第一句**——
|
`text` + `split` 那种整块写法也可以带 `line_break_before`,但它只作用于**切出来的第一句**——
|
||||||
"这一块从新的一行开始"。块里其余几句是接着它的,不是各自另起一行;否则一个换行写了三行的段落
|
"这一块从新的一行开始"。块里其余几句是接着它的,不是各自另起一行;否则一个换行写了三行的段落
|
||||||
就会被切成三行。
|
就会被切成三行。
|
||||||
|
|
||||||
|
#### 公式怎么摆:center / left / right
|
||||||
|
|
||||||
|
含 display 公式的句子还带 `formula_align`,默认 `center`,可给 `left` 或 `right`:
|
||||||
|
|
||||||
|
```jsonc
|
||||||
|
{"content": "$$ \\Delta I = f(\\tau) $$", "line_break_before": true, "formula_align": "left"}
|
||||||
|
```
|
||||||
|
|
||||||
|
它是**每一句公式自己的排版**,不是标题(字段库)的设置:一段里合法的组合就是"先居中一个公式、
|
||||||
|
后面接一个右对齐的续行"。句号后的编号(`\tag{1}`)始终靠右,三种对齐都一样。
|
||||||
|
只对含 display 公式的句子有意义——纯文本句子给了它也不会变样,但它照样会被原样存下来。
|
||||||
|
|
||||||
### 3.4 模板 templates(5 个)
|
### 3.4 模板 templates(5 个)
|
||||||
|
|
||||||
模板就是结构:论文的标题是**每次渲染现读模板**得到的,所以改模板会影响所有用它的论文,
|
模板就是结构:论文的标题是**每次渲染现读模板**得到的,所以改模板会影响所有用它的论文,
|
||||||
@@ -417,6 +436,73 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
|
|||||||
| `reference_tag_update` | 改名/颜色/备注 | `tag_id`、`name?` `color?` `note?` `clear_note?` |
|
| `reference_tag_update` | 改名/颜色/备注 | `tag_id`、`name?` `color?` `note?` `clear_note?` |
|
||||||
| `reference_tag_delete` | 删标签(文献不受影响)| `tag_ids`(int 或数组)|
|
| `reference_tag_delete` | 删标签(文献不受影响)| `tag_ids`(int 或数组)|
|
||||||
|
|
||||||
|
### 3.8 插图 images(1 个)
|
||||||
|
|
||||||
|
图片不进数据库:**字节放 MinIO,句子只留地址**,写成 Markdown。
|
||||||
|
|
||||||
|
| 工具 | 作用 | 关键参数 |
|
||||||
|
|---|---|---|
|
||||||
|
| `image_upload` | 传一张图,返回可写进句子的 Markdown 与那个句子对象 | `data_base64`、`caption?` `filename?` `width?` `height?` |
|
||||||
|
|
||||||
|
```jsonc
|
||||||
|
{"name": "image_upload", "arguments": {
|
||||||
|
"data_base64": "iVBORw0KGgo…", // 也可以直接给 data:image/png;base64,…
|
||||||
|
"caption": "图 3 惯性—冲量相空间", // 不给就用 filename 的主干
|
||||||
|
"width": "70%", // 或 400px;不传按原尺寸(不超过栏宽)
|
||||||
|
"height": "300px" // 可选,只能像素;图不会超过这个高
|
||||||
|
}}
|
||||||
|
// → {"key": "2026/09/9f8c1a4b7e2d0c33.png",
|
||||||
|
// "url": "/api/images/2026/09/9f8c1a4b7e2d0c33.png",
|
||||||
|
// "markdown": "{width=70%}",
|
||||||
|
// "sentence": {"content": "{width=70%}", "line_break_before": true, "formula_align": "center"}}
|
||||||
|
```
|
||||||
|
|
||||||
|
拿回来的 `sentence` **原样**放进 `paper_write` / `paragraph_write` / `sentence_add` 的 `sentences` 里就是一张插图,
|
||||||
|
不需要再拼字符串——`content` 与网页端"插入图片"写出来的是同一个(都走 `markdown_for`)。
|
||||||
|
|
||||||
|
三条规则:
|
||||||
|
|
||||||
|
1. **键就是内容的摘要。** 同一张图传两次是**同一个对象**(不是两份),地址永远指不到别的图上,
|
||||||
|
所以 `url` 可以带一年不变的缓存头。文件名、`Content-Type` 都只是说法,格式按字节判断。
|
||||||
|
2. **只收 PNG / JPEG / GIF / WebP,SVG 明确不收**(从本站点提供上传的 SVG 等于存储型 XSS)。
|
||||||
|
超过 20 MB 会被拒,并告诉你先压缩。
|
||||||
|
3. **句子只有一张图 = 插图**(独占一行、居中、方括号里的字当图注);图夹在一句话中间就是行内小图。
|
||||||
|
`paragraph_get` / `paper_document` 的 `text` 按同一条规则断行,图以它存储的 Markdown 原样印在自己的行上——
|
||||||
|
文本画不出图片,而地址是"哪一张图"的唯一答案,读回来还能原样搬走。
|
||||||
|
|
||||||
|
**宽和高可以分别填**,写法都在句子正文里:
|
||||||
|
|
||||||
|
| 想要的效果 | 句子正文里写 | 结果 |
|
||||||
|
|---|---|---|
|
||||||
|
| 宽正好 500px,高自动 | `{width=500px}` | 500×(按原比例算) |
|
||||||
|
| 占栏宽的 70% | `{width=70%}` | 列宽×0.7,高自动 |
|
||||||
|
| **高不超过 300px**,宽自动 | `{height=300px}` | 宽 = 300×原比例,按比例缩 |
|
||||||
|
| 放进 500×300 的框里 | `{width=500px height=300px}` | 等比缩放塞进框内 |
|
||||||
|
| 原尺寸 | 不写 | 按原图,最多不超过栏宽 |
|
||||||
|
|
||||||
|
三条规则:
|
||||||
|
|
||||||
|
1. **宽是精确值,高是上限。** 宽有参照物(栏宽或你给的像素),所以给多少就是多少;高没有参照物,
|
||||||
|
也没必要把图放大到比它本身还大(只会糊),所以 `height` 是"不超过这个高"。你说的场景(把太高的图压矮)
|
||||||
|
两种情况结果一样。
|
||||||
|
2. **永远只给宽度或只给高度时,另一边由浏览器按原比例算**——所以图不可能被拉变形。两个都给就是
|
||||||
|
"放进这个框里",也是等比缩放,不会拉伸。
|
||||||
|
3. **写法宽容,含义严格。** `70%`、`70 %`、`{width=70%}`、`w=400px` 都收;宽 1–4000px 或 1–100%,
|
||||||
|
高 1–4000px(**高不能用百分比**:句子里没有可参照的高度,浏览器会直接忽略,那等于写了个不生效的值)。
|
||||||
|
`width` 只写数字按**百分比**算(`60` = `60%`);`height` 只写数字按**像素**算。
|
||||||
|
超出范围或读不懂的一律拒绝并说明,而不是默默退回原尺寸。
|
||||||
|
|
||||||
|
这几种写法在网页端可以点着填:段落编辑器里,凡是"整句只有一张图"的行都有「宽」「高」两个框,
|
||||||
|
可以用预设,也可以直接打字(如 `63%`、`380px`、`250`),旁边实时显示这会在版面上占多大
|
||||||
|
(如 `原图 1857×1986 · 显示 893×955`)。
|
||||||
|
|
||||||
|
同一个大小在网页端也能改:段落编辑器里,凡是"整句只有一张图"的行都会出现「宽度」下拉框,
|
||||||
|
可以选 25/50/70/100%,也可以直接填任意值(如 `63%`、`380px`),旁边实时显示这会在版面上
|
||||||
|
占多大(如 `原图 1857×1986 · 显示 893×955`)。
|
||||||
|
|
||||||
|
存储没配好(缺 `MINIO_ENDPOINT` / `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY`)时,这个工具报 503 语义的说明,
|
||||||
|
**写作路径照常**:论文、段落、句子、模板、文献都不碰对象存储。
|
||||||
|
|
||||||
## 4. 典型用法
|
## 4. 典型用法
|
||||||
|
|
||||||
### 4.1 AI 写完,整篇一次灌进去(主推)
|
### 4.1 AI 写完,整篇一次灌进去(主推)
|
||||||
@@ -551,6 +637,36 @@ display 公式不用担心——它本来就独占一行;但分条列举、作
|
|||||||
删文献时如果它还被引用,会被拒绝并报出「(N 处引用)」——先按上面第 4 步找到那些句子、
|
删文献时如果它还被引用,会被拒绝并报出「(N 处引用)」——先按上面第 4 步找到那些句子、
|
||||||
用 `sentence_update(citations=[])` 摘掉引用,再删。
|
用 `sentence_update(citations=[])` 摘掉引用,再删。
|
||||||
|
|
||||||
|
### 4.8 插图:把一张图放进论文
|
||||||
|
|
||||||
|
```jsonc
|
||||||
|
// 1) 传图(给字节的 base64;模型手里是文件路径时先读出字节)
|
||||||
|
{"name": "image_upload", "arguments": {
|
||||||
|
"data_base64": "iVBORw0KGgo…", "caption": "图 3 惯性—冲量相空间", "width": "70%"
|
||||||
|
}}
|
||||||
|
// → {"key": "…", "url": "/api/images/2026/09/….png",
|
||||||
|
// "sentence": {"content": "{width=70%}", "line_break_before": true, "formula_align": "center"}}
|
||||||
|
|
||||||
|
// 2) 原样写进去(也可以塞进 paper_write 的 paragraphs[].sentences 里)
|
||||||
|
{"name": "sentence_add", "arguments": {
|
||||||
|
"paper_id": 96, "heading": "4.4 技术惯性量化",
|
||||||
|
"content": "{width=70%}",
|
||||||
|
"line_break_before": true
|
||||||
|
}}
|
||||||
|
|
||||||
|
// 3) 读回来确认它在自己的一行上
|
||||||
|
{"name": "paragraph_get", "arguments": {"paper_id": 96, "heading": "4.4 技术惯性量化"}}
|
||||||
|
```
|
||||||
|
|
||||||
|
要点:
|
||||||
|
|
||||||
|
- **同一张图传两次是同一个对象**:键是内容的 SHA-256,所以重复上传不会堆出副本,也不会换地址。
|
||||||
|
- **图注写在方括号里**,网页端显示为图下那行字;`width` 不给就按原尺寸(最多不超过栏宽)。
|
||||||
|
- 想让图**跟着一句话走**(行内小图,而不是独占一行的插图),把它拼进那句话里就行:
|
||||||
|
`"回归结果见  的右panel。"`。
|
||||||
|
- MCP 只做上传这一半。图是**通过 API(`/api/images/…`)读**的:句子存的是同源相对路径,
|
||||||
|
局域网和以后的公网地址都能用,桶也不必公开。
|
||||||
|
|
||||||
## 5. 返回值与错误约定
|
## 5. 返回值与错误约定
|
||||||
|
|
||||||
- **成功**:`content[0].text` 是一段 JSON 字符串。例如 `paper_list` 返回
|
- **成功**:`content[0].text` 是一段 JSON 字符串。例如 `paper_list` 返回
|
||||||
@@ -600,10 +716,18 @@ REST 和 MCP 同时生效。这让"网页里看到的"和"AI 写进去的"永远
|
|||||||
|
|
||||||
**换行是"要求"出来的,不是猜出来的。** `line_break_before` 只在被明确写出来时才设:
|
**换行是"要求"出来的,不是猜出来的。** `line_break_before` 只在被明确写出来时才设:
|
||||||
`text` 里换了一行不等于要另起一行(模型把一段话折成三行是常事),所以工具不从这里推断。
|
`text` 里换了一行不等于要另起一行(模型把一段话折成三行是常事),所以工具不从这里推断。
|
||||||
唯一的例外是 display 公式——页面渲染和 `paper_document` 的 `text` 都让它独占一行,
|
唯一的例外是 display 公式和"整句只有一张图"的插图——页面渲染和 `paper_document` 的 `text`
|
||||||
这条规则在 `frontend/src/utils/math.ts` 和 `app/mcp/support.py` 里各写了一遍
|
都让它们独占一行。这两条规则在 `frontend/src/utils/rich.ts` 和 `app/mcp/support.py` 里各写了一遍
|
||||||
(一个 TypeScript、一个 Python),**改一处必须改另一处**,否则网页和工具结果就会在
|
(一个 TypeScript、一个 Python),**改一处必须改另一处**,否则网页和工具结果就会在
|
||||||
"哪一行是哪一行"上不一致。冒烟测试里有一项专门盯着它。
|
"哪一行是哪一行"上不一致。冒烟测试里各有一项盯着它们。
|
||||||
|
|
||||||
|
**句子的字段从 payload schema 里读出来,不手抄。** `app/mcp/support.py` 的
|
||||||
|
`SENTENCE_FIELDS` 直接取自 `app.schemas.paper.SentenceInput`,写入路径用
|
||||||
|
`SentenceCreate(**item.model_dump())` 整体展开。这条改动是有代价换来的:`line_break_before`
|
||||||
|
和 `formula_align` 两次都是"后端加了列、网页能用、REST 能存,MCP 静默丢掉"——
|
||||||
|
调用成功、字段不见,是最难查的一类错。现在只剩一处需要人工同步:在
|
||||||
|
`app/mcp/specs.py` 里声明字段,而 `smoke_mcp.py` 的第一步会比对
|
||||||
|
`SentenceInput` 与 `SentenceSpec` 的字段集合,漏了就红。
|
||||||
|
|
||||||
**删除要二次确认。** `paper_delete` 第一次调用必定被拒并说明后果,
|
**删除要二次确认。** `paper_delete` 第一次调用必定被拒并说明后果,
|
||||||
因为一次误删会连带整篇的句子和引用,而这在 MCP 里没有回收站。
|
因为一次误删会连带整篇的句子和引用,而这在 MCP 里没有回收站。
|
||||||
@@ -636,6 +760,8 @@ REST 和 MCP 同时生效。这让"网页里看到的"和"AI 写进去的"永远
|
|||||||
| 删文献 | `DELETE /api/references/{id}` | `reference_delete` |
|
| 删文献 | `DELETE /api/references/{id}` | `reference_delete` |
|
||||||
| 谁引用了它 | `GET /api/references/{id}/citations` | `reference_citations` |
|
| 谁引用了它 | `GET /api/references/{id}/citations` | `reference_citations` |
|
||||||
| 文献标签 | `/api/reference-tags` | `reference_tag_*` |
|
| 文献标签 | `/api/reference-tags` | `reference_tag_*` |
|
||||||
|
| 传图 | `POST /api/images`(multipart)| `image_upload`(base64)|
|
||||||
|
| 看图 | `GET /api/images/{key}` | —(句子里的地址由页面/浏览器直接取)|
|
||||||
|
|
||||||
MCP 独有:`paper_outline`(写前看骨架)、`paper_write` / `paper_write_text`(批量写入)、
|
MCP 独有:`paper_outline`(写前看骨架)、`paper_write` / `paper_write_text`(批量写入)、
|
||||||
`paragraph_move`、`sentence_search`。
|
`paragraph_move`、`sentence_search`。
|
||||||
@@ -653,4 +779,6 @@ MCP 独有:`paper_outline`(写前看骨架)、`paper_write` / `paper_write
|
|||||||
| 工具调用超时 | DSH/Codex 侧加大 `toolCallTimeoutMs` / `tool_timeout_sec`;`paper_write_text` 写整篇会慢一些 |
|
| 工具调用超时 | DSH/Codex 侧加大 `toolCallTimeoutMs` / `tool_timeout_sec`;`paper_write_text` 写整篇会慢一些 |
|
||||||
| k3s 里连不上 | `kubectl -n paper-doc get pods` 看是否 Ready;`/readyz` 返回 503 说明 TiDB 不通(`kubectl -n paper-doc logs deploy/paper-doc-mcp`) |
|
| k3s 里连不上 | `kubectl -n paper-doc get pods` 看是否 Ready;`/readyz` 返回 503 说明 TiDB 不通(`kubectl -n paper-doc logs deploy/paper-doc-mcp`) |
|
||||||
| 改了代码但行为没变 | 镜像 tag 没换:`imagePullPolicy: IfNotPresent` 会继续用节点上缓存的同名镜像,换个 tag 重新构建 |
|
| 改了代码但行为没变 | 镜像 tag 没换:`imagePullPolicy: IfNotPresent` 会继续用节点上缓存的同名镜像,换个 tag 重新构建 |
|
||||||
|
| `image_upload` 报"图片存储还没有配置好" | 缺 `MINIO_ENDPOINT` / `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY`。本机看 `backend/.env`;集群里看 `paper-doc-config`(端点是 `http://minio.minio.svc.cluster.local:9000`,不是宿主机的 `:30090`)与 `paper-doc-secrets` |
|
||||||
|
| `image_upload` 报"连不上对象存储" | MinIO 不通或凭证不对:`kubectl -n minio get pods`,再用同一组凭证 `mc`/`aws s3` 试一次 `PutObject` |
|
||||||
| 日志里出现非 JSON 的 stdout 输出 | 不要在这个进程里 `print`——stdio 传输下会污染协议流(本项目的诊断都走 stderr) |
|
| 日志里出现非 JSON 的 stdout 输出 | 不要在这个进程里 `print`——stdio 传输下会污染协议流(本项目的诊断都走 stderr) |
|
||||||
|
|||||||
+112
-5
@@ -412,8 +412,36 @@ line":
|
|||||||
| an image inside a run of text | **inline**, on the line with the words, height capped at `12em` |
|
| an image inside a run of text | **inline**, on the line with the words, height capped at `12em` |
|
||||||
|
|
||||||
The size is optional and comes from pandoc's attribute form — `{width=70%}`,
|
The size is optional and comes from pandoc's attribute form — `{width=70%}`,
|
||||||
`{width=400px}` — and is validated to digits plus one unit before it becomes a
|
`{width=400px}`, `{height=300px}`, or both in one block — and each declaration is
|
||||||
CSS length, so no second declaration can be smuggled through it.
|
validated to digits plus at most one unit before it becomes a CSS length, so no
|
||||||
|
second declaration can be smuggled through it. A **width is exact and a height is
|
||||||
|
a cap**: a width has a reference (the column, or a length the writer chose), while
|
||||||
|
nothing measures a height against anything, and enlarging a picture past its own
|
||||||
|
pixels only makes it soft. In the flow of a sentence a height is always a
|
||||||
|
downscale, which comes to the same thing as exact. A bare number is a share of
|
||||||
|
the column for a width — `parseImageWidth` only reads pixels when the value says
|
||||||
|
`px` — and pixels for a height, because there is nothing else it could be; a
|
||||||
|
percentage *height* is refused rather than stored, since it has nothing to be a
|
||||||
|
percentage of and the browser's answer to one is to ignore it.
|
||||||
|
|
||||||
|
Whichever of the two is given alone, the other follows from the picture's own
|
||||||
|
shape, so a figure can be sized but not stretched; when a writer does give both,
|
||||||
|
they are read as a box to fit *inside* rather than a box to fill. Measured across
|
||||||
|
the sixteen figures of the paper this was built for, every drawn rectangle
|
||||||
|
matched its picture's aspect ratio to within 0.2% — the rounding of the
|
||||||
|
measurement, not the layout.
|
||||||
|
|
||||||
|
Leaving the size off was the wrong default to *live* with. Figures come out of a
|
||||||
|
plotting tool at whatever size they were made: that paper's are 1441, 1857, 2409
|
||||||
|
and 4169 pixels wide, so all sixteen were wider than the 1276px column and every
|
||||||
|
one printed at the full width, with the near-square ones (1857×1986, 1974×2068)
|
||||||
|
filling a page at 1365px tall. So the size became part of the editor: a row that
|
||||||
|
is a figure carries a 宽度 and a 高度 box — presets, or any value typed in — with
|
||||||
|
what the picture will measure on the page beside them (`原图 1857×1986 · 显示
|
||||||
|
638×682`), worked out against the column actually rendered behind the dialog.
|
||||||
|
Both boxes write through the reader's own `parseImageWidth` /
|
||||||
|
`parseImageHeight`, so what they show is what gets printed, and a value those
|
||||||
|
functions cannot read is refused instead of stored as a size that does nothing.
|
||||||
|
|
||||||
Configuration is three variables (`MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`,
|
Configuration is three variables (`MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`,
|
||||||
`MINIO_SECRET_KEY`, plus `MINIO_BUCKET`). Left empty, the paper still writes and
|
`MINIO_SECRET_KEY`, plus `MINIO_BUCKET`). Left empty, the paper still writes and
|
||||||
@@ -595,7 +623,7 @@ written by an agent is indistinguishable from one written by hand. What
|
|||||||
|
|
||||||
| Addition | Why the REST shape is wrong for a model |
|
| Addition | Why the REST shape is wrong for a model |
|
||||||
|---|---|
|
|---|---|
|
||||||
| 41 tools with `paper_` / `paragraph_` / `sentence_` / `template_` / `field_` / `reference_` / `reference_tag_` prefixes | a model picks a tool out of a list by its name, not by reading 41 descriptions |
|
| 42 tools with `paper_` / `paragraph_` / `sentence_` / `template_` / `field_` / `reference_` / `reference_tag_` / `image_` prefixes | a model picks a tool out of a list by its name, not by reading 42 descriptions |
|
||||||
| JSON strings, `None`-free, no pagination envelope on reads | a tool result is paid for in context tokens |
|
| JSON strings, `None`-free, no pagination envelope on reads | a tool result is paid for in context tokens |
|
||||||
| `paragraph_write` addressed by **heading** as well as position | nobody writing "1. Introduction" knows the template places it at `sort = 20` |
|
| `paragraph_write` addressed by **heading** as well as position | nobody writing "1. Introduction" knows the template places it at `sort = 20` |
|
||||||
| `paper_write` / `paper_write_text` | "generate the paper, then put it in" is one intention, not thirty round trips |
|
| `paper_write` / `paper_write_text` | "generate the paper, then put it in" is one intention, not thirty round trips |
|
||||||
@@ -603,7 +631,9 @@ written by an agent is indistinguishable from one written by hand. What
|
|||||||
| `sentence_search` across papers | the job is consistency — one paper says 洪水损失, the next must not say GUL |
|
| `sentence_search` across papers | the job is consistency — one paper says 洪水损失, the next must not say GUL |
|
||||||
| `reference_*` and `reference_tag_*` | the reference library is what makes a citation mean something; an agent that can cite id 42 but cannot look up what 42 *is* is writing blind |
|
| `reference_*` and `reference_tag_*` | the reference library is what makes a citation mean something; an agent that can cite id 42 but cannot look up what 42 *is* is writing blind |
|
||||||
| `reference_import` | "here are the twenty references I cited" is one intention, and twenty round trips would spend twenty schemas on it |
|
| `reference_import` | "here are the twenty references I cited" is one intention, and twenty round trips would spend twenty schemas on it |
|
||||||
| `line_break_before` on a sentence, and the display-formula rule in `document_text` | a paragraph is its sentences run together, so a formula, a list or an author line needs a way to say where the line starts — and the text an agent reads back has to break lines where the paper view breaks them, or the two disagree about what the manuscript looks like |
|
| `line_break_before` on a sentence, and the display-formula and figure rules in `document_text` | a paragraph is its sentences run together, so a formula, a list, an author line or a 插图 needs a way to say where the line starts — and the text an agent reads back has to break lines where the paper view breaks them, or the two disagree about what the manuscript looks like |
|
||||||
|
| `image_upload` taking base64 | the upload route is `multipart/form-data`, which a model cannot send; it has bytes and a tool argument, and it gets back the same Markdown and the same sentence the editor would have written |
|
||||||
|
| the sentence's own columns read from `SentenceInput` rather than listed | `line_break_before` and `formula_align` were each added to the domain, used by the editor and the API, and silently dropped by every MCP write path; the field set is now derived, and `smoke_mcp.py` fails if `specs.py` lags behind |
|
||||||
|
|
||||||
Two transports are served from one build: `stdio`, which is what a client
|
Two transports are served from one build: `stdio`, which is what a client
|
||||||
spawns, and `streamable-http`, which is what a client on another machine
|
spawns, and `streamable-http`, which is what a client on another machine
|
||||||
@@ -878,12 +908,15 @@ paper-doc/
|
|||||||
│ ├── scripts/smoke_images.py # end-to-end check of upload, serve and refusal
|
│ ├── scripts/smoke_images.py # end-to-end check of upload, serve and refusal
|
||||||
│ ├── scripts/check_citation_styles.py # the formatter, one entry per type
|
│ ├── scripts/check_citation_styles.py # the formatter, one entry per type
|
||||||
│ │ # (no server, no database)
|
│ │ # (no server, no database)
|
||||||
|
│ ├── scripts/check_storage.py # the image rules: formats, keys, refusals
|
||||||
|
│ │ # (no server, no bucket)
|
||||||
│ ├── scripts/mcp_server.py # MCP entry point (stdio / http)
|
│ ├── scripts/mcp_server.py # MCP entry point (stdio / http)
|
||||||
│ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client
|
│ ├── scripts/smoke_mcp.py # the same loop, spoken over MCP by a real client
|
||||||
│ ├── alembic.ini
|
│ ├── alembic.ini
|
||||||
│ ├── requirements.txt
|
│ ├── requirements.txt
|
||||||
│ └── .env.example
|
│ └── .env.example
|
||||||
├── frontend/ # Vue 3 SPA
|
├── frontend/ # Vue 3 SPA
|
||||||
|
│ ├── scripts/check-image.mjs # the browser check: does a figure draw?
|
||||||
│ ├── src/
|
│ ├── src/
|
||||||
│ │ ├── api/ # axios instance and endpoint modules
|
│ │ ├── api/ # axios instance and endpoint modules
|
||||||
│ │ ├── components/ # shell, field, template, paper and reference
|
│ │ ├── components/ # shell, field, template, paper and reference
|
||||||
@@ -951,6 +984,31 @@ cd backend
|
|||||||
alembic upgrade head
|
alembic upgrade head
|
||||||
```
|
```
|
||||||
|
|
||||||
|
**Object storage**
|
||||||
|
|
||||||
|
The images a paper embeds live in MinIO, deployed in the same k3s cluster
|
||||||
|
(namespace `minio`, manifests in `/opt/kubectl/minio/`): the S3 API on NodePort
|
||||||
|
`30090`, the console on `30091`. From inside the cluster the Service is
|
||||||
|
`http://minio.minio.svc.cluster.local:9000`.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# backend/.env — never committed
|
||||||
|
MINIO_ENDPOINT=http://192.168.1.88:30090
|
||||||
|
MINIO_ACCESS_KEY=… # a dedicated key, not the MinIO root account
|
||||||
|
MINIO_SECRET_KEY=…
|
||||||
|
MINIO_BUCKET=paper-images # created on the first upload if it is absent
|
||||||
|
```
|
||||||
|
|
||||||
|
The bucket stays **private**. Nothing is made public to display a figure: the
|
||||||
|
API streams the object out of the bucket on `/api/images/{key}`, which is both
|
||||||
|
what keeps the paper's addresses portable and what keeps the bucket from being a
|
||||||
|
second, unauthenticated way into the deployment.
|
||||||
|
|
||||||
|
A key scoped to objects alone (`PutObject` / `GetObject`, no `ListBucket`) is
|
||||||
|
enough, and is the better choice: the upload tolerates the `403` that such a key
|
||||||
|
gets when it checks whether the bucket exists, rather than mistaking it for a
|
||||||
|
missing bucket.
|
||||||
|
|
||||||
**Seed data**
|
**Seed data**
|
||||||
|
|
||||||
`scripts/seed.py` fills the title library with a standard academic outline (20
|
`scripts/seed.py` fills the title library with a standard academic outline (20
|
||||||
@@ -1010,6 +1068,52 @@ cd backend
|
|||||||
.venv/bin/python scripts/smoke_papers.py
|
.venv/bin/python scripts/smoke_papers.py
|
||||||
```
|
```
|
||||||
|
|
||||||
|
**Checking images**
|
||||||
|
|
||||||
|
Three scripts, because the feature has three layers that fail differently.
|
||||||
|
`scripts/check_storage.py` needs nothing running: it replaces boto3's client
|
||||||
|
with a stub and checks the rules that decide what may be stored and served at
|
||||||
|
all — the format sniffed from the magic bytes (and SVG refused), the key pattern
|
||||||
|
that the read route will serve and nothing outside it, the Markdown a caption
|
||||||
|
may not break out of, what is asked of MinIO on a write, and that a key which is
|
||||||
|
not allowed to *look* at the bucket still works.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd backend
|
||||||
|
.venv/bin/python scripts/check_storage.py # no server, no bucket
|
||||||
|
.venv/bin/python scripts/smoke_images.py # against a running API + MinIO
|
||||||
|
```
|
||||||
|
|
||||||
|
`scripts/smoke_images.py` is the end-to-end one: it uploads each accepted
|
||||||
|
format, fetches every one back byte for byte, checks the refusals (`415` for
|
||||||
|
text, an SVG and a mislabelled file, `400` for an empty one, `404` for a key
|
||||||
|
this application never wrote), proves the same bytes are stored once, and writes
|
||||||
|
a sentence holding a figure through the paper endpoints to show the Markdown
|
||||||
|
survives them unchanged. Nothing needs cleaning up afterwards, and that is
|
||||||
|
itself the property under test — a key is the digest of its picture, so a second
|
||||||
|
run stores the same objects rather than more copies of them.
|
||||||
|
|
||||||
|
The third layer is the page, and it is the one neither of the other two can
|
||||||
|
reach: bytes can be stored and returned perfectly while the `<img>` shows
|
||||||
|
nothing. `frontend/scripts/check-image.mjs` therefore measures what the browser
|
||||||
|
did — that the picture decoded (`naturalWidth`), that a figure took a line of
|
||||||
|
its own and is centred on the column, that `{width=50%}` came out at exactly
|
||||||
|
half the column, that the 图注 prints *under* the picture, that an image inside a
|
||||||
|
sentence stayed in that line, and that the editor's 「插入图片」 button ends with
|
||||||
|
the picture in the paper after saving. It needs Playwright, which is not a
|
||||||
|
dependency of the app:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd frontend
|
||||||
|
pnpm add -D playwright && npx playwright install chromium
|
||||||
|
pnpm check:image
|
||||||
|
# or point at an install that lives elsewhere
|
||||||
|
PLAYWRIGHT_MODULE=/path/to/playwright/index.mjs pnpm check:image
|
||||||
|
```
|
||||||
|
|
||||||
|
It creates a throwaway paper for the run and deletes it, so it can be pointed at
|
||||||
|
a database that holds real work.
|
||||||
|
|
||||||
**Checking the MCP server**
|
**Checking the MCP server**
|
||||||
|
|
||||||
`scripts/mcp_server.py --check` connects to the database once and prints the
|
`scripts/mcp_server.py --check` connects to the database once and prints the
|
||||||
@@ -1034,7 +1138,10 @@ builds from a Dockerfile — so `deploy/build-mcp-image.sh` builds inside a
|
|||||||
throwaway privileged docker-in-docker pod, with the working tree mounted in
|
throwaway privileged docker-in-docker pod, with the working tree mounted in
|
||||||
through a hostPath so the build context is what you are actually looking at.
|
through a hostPath so the build context is what you are actually looking at.
|
||||||
The database is the in-cluster TiDB Service (`tidb-tidb.tidb:4000`), not the
|
The database is the in-cluster TiDB Service (`tidb-tidb.tidb:4000`), not the
|
||||||
NodePort the host uses. `deploy/README.md` has the commands, the two traps
|
NodePort the host uses, and the object store is the in-cluster MinIO Service
|
||||||
|
(`minio.minio.svc.cluster.local:9000`) rather than the host's `:30090` — the
|
||||||
|
same bucket either way, and neither address changes when the node's does.
|
||||||
|
`deploy/README.md` has the commands, the two traps
|
||||||
worth knowing (a reused image tag silently keeps the cached image; `COPY`
|
worth knowing (a reused image tag silently keeps the cached image; `COPY`
|
||||||
carries the working tree's `0600` file mode into the image and a non-root
|
carries the working tree's `0600` file mode into the image and a non-root
|
||||||
container then cannot read its own code), and how to add the REST API to the
|
container then cannot read its own code), and how to add the REST API to the
|
||||||
|
|||||||
@@ -8,7 +8,8 @@
|
|||||||
"build": "run-p type-check \"build-only {@}\" --",
|
"build": "run-p type-check \"build-only {@}\" --",
|
||||||
"preview": "vite preview",
|
"preview": "vite preview",
|
||||||
"build-only": "vite build",
|
"build-only": "vite build",
|
||||||
"type-check": "vue-tsc --build"
|
"type-check": "vue-tsc --build",
|
||||||
|
"check:image": "node scripts/check-image.mjs"
|
||||||
},
|
},
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"@element-plus/icons-vue": "^2.3.2",
|
"@element-plus/icons-vue": "^2.3.2",
|
||||||
|
|||||||
@@ -0,0 +1,508 @@
|
|||||||
|
/**
|
||||||
|
* Does an inserted picture actually show?
|
||||||
|
*
|
||||||
|
* pnpm check:image # API on :8000 and the web app on :5173
|
||||||
|
* PAPER_WEB=http://… pnpm check:image
|
||||||
|
*
|
||||||
|
* This is the check `backend/scripts/smoke_images.py` cannot make. That one
|
||||||
|
* proves the endpoints store and return the bytes; this one proves the page
|
||||||
|
* *draws* them: that the `<img>` really decoded (`naturalWidth`), that a figure
|
||||||
|
* took a line of its own and is centred on the column, that `{width=50%}` came
|
||||||
|
* out at half the column, that the 图注 is printed under the picture rather than
|
||||||
|
* beside it, that an image inside a sentence stayed in that line, and that the
|
||||||
|
* editor's 「插入图片」 button ends with the picture in the paper after saving.
|
||||||
|
*
|
||||||
|
* It creates a throwaway paper for the run and deletes it afterwards, so it can
|
||||||
|
* be pointed at a database that holds real work.
|
||||||
|
*
|
||||||
|
* It needs Playwright, which is deliberately not a dependency of the app:
|
||||||
|
*
|
||||||
|
* pnpm add -D playwright && npx playwright install chromium
|
||||||
|
*
|
||||||
|
* An install that lives elsewhere can be pointed at instead, which is how this
|
||||||
|
* was verified on the machine that runs the paper:
|
||||||
|
*
|
||||||
|
* PLAYWRIGHT_MODULE=/path/to/node_modules/playwright/index.mjs pnpm check:image
|
||||||
|
*/
|
||||||
|
import { deflateSync } from 'node:zlib'
|
||||||
|
|
||||||
|
const WEB = process.env.PAPER_WEB ?? 'http://127.0.0.1:5173'
|
||||||
|
const API = process.env.PAPER_API ?? 'http://127.0.0.1:8000/api'
|
||||||
|
|
||||||
|
let chromium
|
||||||
|
try {
|
||||||
|
;({ chromium } = await import(process.env.PLAYWRIGHT_MODULE ?? 'playwright'))
|
||||||
|
} catch {
|
||||||
|
console.error(
|
||||||
|
'playwright is not installed. Either install it:\n' +
|
||||||
|
' pnpm add -D playwright && npx playwright install chromium\n' +
|
||||||
|
'or point at an existing install with PLAYWRIGHT_MODULE=…/playwright/index.mjs',
|
||||||
|
)
|
||||||
|
process.exit(2)
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- a real PNG, built here so the script carries its own fixture ------------
|
||||||
|
|
||||||
|
const CRC_TABLE = Array.from({ length: 256 }, (_, index) => {
|
||||||
|
let value = index
|
||||||
|
for (let bit = 0; bit < 8; bit += 1) {
|
||||||
|
value = value & 1 ? 0xedb88320 ^ (value >>> 1) : value >>> 1
|
||||||
|
}
|
||||||
|
return value >>> 0
|
||||||
|
})
|
||||||
|
|
||||||
|
function crc32(buffer) {
|
||||||
|
let crc = 0xffffffff
|
||||||
|
for (const byte of buffer) crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8)
|
||||||
|
return (crc ^ 0xffffffff) >>> 0
|
||||||
|
}
|
||||||
|
|
||||||
|
function chunk(tag, payload) {
|
||||||
|
const body = Buffer.concat([Buffer.from(tag, 'ascii'), payload])
|
||||||
|
const length = Buffer.alloc(4)
|
||||||
|
length.writeUInt32BE(payload.length)
|
||||||
|
const crc = Buffer.alloc(4)
|
||||||
|
crc.writeUInt32BE(crc32(body))
|
||||||
|
return Buffer.concat([length, body, crc])
|
||||||
|
}
|
||||||
|
|
||||||
|
/** A gradient, so two fixtures differ and the size is honest. */
|
||||||
|
function makePng(width = 480, height = 300) {
|
||||||
|
const raw = Buffer.alloc(height * (1 + width * 3))
|
||||||
|
let offset = 0
|
||||||
|
for (let y = 0; y < height; y += 1) {
|
||||||
|
raw[offset] = 0 // filter: none
|
||||||
|
offset += 1
|
||||||
|
for (let x = 0; x < width; x += 1) {
|
||||||
|
raw[offset] = Math.round((x * 255) / Math.max(width - 1, 1))
|
||||||
|
raw[offset + 1] = Math.round((y * 255) / Math.max(height - 1, 1))
|
||||||
|
raw[offset + 2] = 128
|
||||||
|
offset += 3
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const header = Buffer.alloc(13)
|
||||||
|
header.writeUInt32BE(width, 0)
|
||||||
|
header.writeUInt32BE(height, 4)
|
||||||
|
header[8] = 8 // bit depth
|
||||||
|
header[9] = 2 // truecolour
|
||||||
|
return Buffer.concat([
|
||||||
|
Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
|
||||||
|
chunk('IHDR', header),
|
||||||
|
chunk('IDAT', deflateSync(raw, { level: 9 })),
|
||||||
|
chunk('IEND', Buffer.alloc(0)),
|
||||||
|
])
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- the API, spoken with fetch ---------------------------------------------
|
||||||
|
|
||||||
|
async function api(method, path, body) {
|
||||||
|
const response = await fetch(`${API}${path}`, {
|
||||||
|
method,
|
||||||
|
headers: { 'Content-Type': 'application/json' },
|
||||||
|
body: body ? JSON.stringify(body) : undefined,
|
||||||
|
})
|
||||||
|
if (!response.ok && response.status !== 204) {
|
||||||
|
throw new Error(`${method} ${path} -> ${response.status}: ${await response.text()}`)
|
||||||
|
}
|
||||||
|
return response.status === 204 ? null : response.json()
|
||||||
|
}
|
||||||
|
|
||||||
|
const results = []
|
||||||
|
function check(label, ok, detail = '') {
|
||||||
|
results.push([label, ok])
|
||||||
|
console.log(`${ok ? ' ok ' : ' FAIL'}${label}${ok ? '' : ` — ${detail}`}`)
|
||||||
|
}
|
||||||
|
|
||||||
|
const png = makePng()
|
||||||
|
const uploadResponse = await fetch(`${API}/images`, {
|
||||||
|
method: 'POST',
|
||||||
|
body: (() => {
|
||||||
|
const form = new FormData()
|
||||||
|
form.append('file', new Blob([png], { type: 'image/png' }), '试验装置.png')
|
||||||
|
return form
|
||||||
|
})(),
|
||||||
|
})
|
||||||
|
if (!uploadResponse.ok) {
|
||||||
|
throw new Error(`upload -> ${uploadResponse.status}: ${await uploadResponse.text()}`)
|
||||||
|
}
|
||||||
|
const image = await uploadResponse.json()
|
||||||
|
console.log(`uploaded ${image.url} (${image.size} bytes)`)
|
||||||
|
|
||||||
|
const browser = await chromium.launch()
|
||||||
|
let paperId = null
|
||||||
|
try {
|
||||||
|
const context = await browser.newContext({ viewport: { width: 1600, height: 950 } })
|
||||||
|
const page = await context.newPage()
|
||||||
|
|
||||||
|
const template = (await api('GET', '/templates?page_size=1')).items[0]
|
||||||
|
paperId = (await api('POST', '/papers', { title: '插图浏览器测试', template_id: template.id })).id
|
||||||
|
const outline = await api('GET', `/templates/${template.id}`)
|
||||||
|
const sort = outline.placements[0].sort
|
||||||
|
|
||||||
|
// One paragraph with an image inside a sentence, and one figure half the
|
||||||
|
// column wide. Written through the API so the *rendering* is what is checked.
|
||||||
|
await api('PUT', `/papers/${paperId}/paragraphs/${sort}`, {
|
||||||
|
sentences: [
|
||||||
|
{ content: `试验装置如  所示,量测点布置在试件中部。` },
|
||||||
|
{ content: `{width=50%}`, line_break_before: true },
|
||||||
|
],
|
||||||
|
})
|
||||||
|
|
||||||
|
await page.goto(`${WEB}/papers/${paperId}`, { waitUntil: 'networkidle' })
|
||||||
|
await page.waitForSelector('.paragraph-body')
|
||||||
|
// `naturalWidth` is the proof it decoded; give the decode a moment.
|
||||||
|
await page.waitForTimeout(800)
|
||||||
|
|
||||||
|
const geometry = await page.evaluate(() => {
|
||||||
|
const body = document.querySelector('.paragraph-body')
|
||||||
|
const bodyBox = body.getBoundingClientRect()
|
||||||
|
const figure = document.querySelector('.sentence--figure')
|
||||||
|
const figureImage = figure.querySelector('img')
|
||||||
|
const figureBox = figureImage.getBoundingClientRect()
|
||||||
|
const caption = figure.querySelector('.figure-caption')
|
||||||
|
const inline = [...document.querySelectorAll('.sentence img')].find(
|
||||||
|
(node) => !node.closest('.sentence--figure'),
|
||||||
|
)
|
||||||
|
const inlineBox = inline.getBoundingClientRect()
|
||||||
|
|
||||||
|
return {
|
||||||
|
bodyWidth: Math.round(bodyBox.width),
|
||||||
|
bodyCenter: Math.round(bodyBox.left + bodyBox.width / 2),
|
||||||
|
figure: {
|
||||||
|
src: figureImage.getAttribute('src'),
|
||||||
|
natural: [figureImage.naturalWidth, figureImage.naturalHeight],
|
||||||
|
width: Math.round(figureBox.width),
|
||||||
|
height: Math.round(figureBox.height),
|
||||||
|
// What the markup asked the browser for. The height is expected to be
|
||||||
|
// empty: only a width is ever written, which is what makes a figure
|
||||||
|
// impossible to deform.
|
||||||
|
styleHeight: figureImage.style.height || '',
|
||||||
|
center: Math.round(figureBox.left + figureBox.width / 2),
|
||||||
|
caption: caption.textContent.trim(),
|
||||||
|
gapBelowImage: Math.round(caption.getBoundingClientRect().top - figureBox.bottom),
|
||||||
|
siblings: figure.closest('.paragraph-line').querySelectorAll('.sentence').length,
|
||||||
|
},
|
||||||
|
inline: {
|
||||||
|
width: Math.round(inlineBox.width),
|
||||||
|
height: Math.round(inlineBox.height),
|
||||||
|
inFigure: Boolean(inline.closest('.sentence--figure')),
|
||||||
|
lineHasText: inline.closest('.paragraph-line').textContent.includes('量测点'),
|
||||||
|
},
|
||||||
|
}
|
||||||
|
})
|
||||||
|
|
||||||
|
const { figure, inline } = geometry
|
||||||
|
check('the picture decoded', figure.natural[0] === 480, JSON.stringify(figure.natural))
|
||||||
|
check('it is served from our own path', figure.src.startsWith('/api/images/'), figure.src)
|
||||||
|
check(
|
||||||
|
'{width=50%} is half the column',
|
||||||
|
Math.abs(figure.width - geometry.bodyWidth * 0.5) <= 2,
|
||||||
|
`${figure.width} vs ${geometry.bodyWidth * 0.5}`,
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
'the figure is centred on the column',
|
||||||
|
Math.abs(figure.center - geometry.bodyCenter) <= 2,
|
||||||
|
`${figure.center} vs ${geometry.bodyCenter}`,
|
||||||
|
)
|
||||||
|
// The size is a *width* and nothing else: the height is whatever keeps the
|
||||||
|
// picture's own shape, so a figure cannot be stretched. Both halves of that
|
||||||
|
// are checked — the shape the browser drew, and that nothing asked for a
|
||||||
|
// height in the first place.
|
||||||
|
check(
|
||||||
|
'a sized figure keeps its own shape',
|
||||||
|
Math.abs((figure.width / figure.height) / (figure.natural[0] / figure.natural[1]) - 1) < 0.01,
|
||||||
|
`${figure.width}×${figure.height} vs natural ${figure.natural.join('×')}`,
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
'and no height is ever written into the sentence',
|
||||||
|
figure.styleHeight === '',
|
||||||
|
`style.height = ${JSON.stringify(figure.styleHeight)}`,
|
||||||
|
)
|
||||||
|
check('the 图注 is the text in the brackets', figure.caption === '试验装置示意图', figure.caption)
|
||||||
|
check('…and it is printed under the picture', figure.gapBelowImage > 0, `${figure.gapBelowImage}`)
|
||||||
|
check('the figure owns its line', figure.siblings === 1, `${figure.siblings} sentences`)
|
||||||
|
check(
|
||||||
|
'an image inside a sentence stays inline',
|
||||||
|
!inline.inFigure && inline.lineHasText,
|
||||||
|
JSON.stringify(inline),
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
'the inline image keeps its aspect ratio',
|
||||||
|
Math.abs(inline.width / inline.height - 480 / 300) < 0.02,
|
||||||
|
`${inline.width}x${inline.height}`,
|
||||||
|
)
|
||||||
|
|
||||||
|
await page.locator('.sentence--figure img').click()
|
||||||
|
await page.waitForTimeout(400)
|
||||||
|
check(
|
||||||
|
'clicking opens the picture at full size',
|
||||||
|
await page.evaluate(() => Boolean(document.querySelector('.el-image-viewer__wrapper'))),
|
||||||
|
)
|
||||||
|
await page.keyboard.press('Escape')
|
||||||
|
await page.waitForTimeout(400)
|
||||||
|
|
||||||
|
// --- the editor's own 「插入图片」 -----------------------------------------
|
||||||
|
// Scoped to a paragraph header: 「编辑信息」 in the toolbar also contains 编辑.
|
||||||
|
await page.locator('.paragraph-actions button:has-text("编辑")').first().click()
|
||||||
|
await page.waitForSelector('.editor .rows', { timeout: 15000 })
|
||||||
|
await page.locator('.editor input[type=file]').setInputFiles({
|
||||||
|
name: '第二张图.png',
|
||||||
|
mimeType: 'image/png',
|
||||||
|
buffer: png,
|
||||||
|
})
|
||||||
|
|
||||||
|
// Wait for the *new* thumbnail: the dialog already shows the two the API
|
||||||
|
// wrote, so waiting for any `.row-image img` would return immediately.
|
||||||
|
await page.waitForFunction(
|
||||||
|
() =>
|
||||||
|
[...document.querySelectorAll('.row-image figcaption')].some(
|
||||||
|
(node) => node.textContent.trim() === '第二张图',
|
||||||
|
),
|
||||||
|
{ timeout: 20000 },
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
'the editor shows the uploaded picture',
|
||||||
|
(await page.locator('.row-image img').count()) === 3,
|
||||||
|
`${await page.locator('.row-image img').count()} thumbnails`,
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
'the row caption comes from the filename',
|
||||||
|
(await page.locator('.row-image figcaption', { hasText: '第二张图' }).first().textContent()).trim() ===
|
||||||
|
'第二张图',
|
||||||
|
)
|
||||||
|
|
||||||
|
await page.getByRole('button', { name: '保存段落' }).click()
|
||||||
|
await page.waitForSelector('.el-dialog', { state: 'detached', timeout: 15000 })
|
||||||
|
await page.waitForTimeout(800)
|
||||||
|
|
||||||
|
const saved = await page.evaluate(() => {
|
||||||
|
const figures = [...document.querySelectorAll('.sentence--figure')]
|
||||||
|
return {
|
||||||
|
count: figures.length,
|
||||||
|
captions: figures.map((node) => node.querySelector('.figure-caption').textContent.trim()),
|
||||||
|
decoded: figures.map((node) => node.querySelector('img').naturalWidth),
|
||||||
|
}
|
||||||
|
})
|
||||||
|
check('the inserted figure is in the paper', saved.count === 2, JSON.stringify(saved))
|
||||||
|
check('and it is the one that was uploaded', saved.captions.includes('第二张图'), saved.captions.join())
|
||||||
|
check('both pictures decoded', saved.decoded.every((width) => width === 480), saved.decoded.join())
|
||||||
|
|
||||||
|
// --- the figure's size, set from the editor ------------------------------
|
||||||
|
//
|
||||||
|
// Figures come out of the plotting tool at whatever size they were made —
|
||||||
|
// one paper's are 1441, 2400 and 4169 pixels wide — and every one of them can
|
||||||
|
// be wider than the column, so with no size they all print at the full column
|
||||||
|
// and a near-square panel fills a page. This control is the answer to that,
|
||||||
|
// and what has to hold is that what it writes is what the reader prints.
|
||||||
|
await page.locator('.paragraph-actions button:has-text("编辑")').first().click()
|
||||||
|
await page.waitForSelector('.editor .rows', { timeout: 15000 })
|
||||||
|
await page.waitForSelector('.width-select')
|
||||||
|
// The hint divides the column by the picture's own size, so it needs the
|
||||||
|
// thumbnail to have decoded first.
|
||||||
|
await page.waitForFunction(
|
||||||
|
() => document.querySelector('.size-hint')?.textContent?.includes('原图'),
|
||||||
|
{ timeout: 15000 },
|
||||||
|
)
|
||||||
|
|
||||||
|
// What each select is showing: Element Plus prints the chosen label in its
|
||||||
|
// own element, not as the value of the input the writer types into.
|
||||||
|
const boxes = await page.evaluate(() => {
|
||||||
|
const rows = [...document.querySelectorAll('.row')]
|
||||||
|
const withSize = rows.filter((row) => row.querySelector('.width-select'))
|
||||||
|
return {
|
||||||
|
rows: rows.length,
|
||||||
|
withSize: withSize.length,
|
||||||
|
// Two boxes per figure — a width and a height, in that order.
|
||||||
|
values: withSize.map((row) =>
|
||||||
|
[...row.querySelectorAll('.width-select')].map(
|
||||||
|
(node) =>
|
||||||
|
(node.querySelector('.el-select__selected-item')?.textContent ?? '').trim() ||
|
||||||
|
(node.querySelector('.el-select__placeholder')?.textContent ?? '').trim(),
|
||||||
|
),
|
||||||
|
),
|
||||||
|
}
|
||||||
|
})
|
||||||
|
check(
|
||||||
|
'a size is offered on the figure rows and nowhere else',
|
||||||
|
boxes.withSize === 2 && boxes.rows === 3,
|
||||||
|
JSON.stringify(boxes),
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
'each figure row has a width box and a height box',
|
||||||
|
boxes.values.every((pair) => pair.length === 2),
|
||||||
|
JSON.stringify(boxes.values),
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
'and the width box shows the size that row is set to',
|
||||||
|
boxes.values[0][0] === '50%' && boxes.values[1][0] !== '50%',
|
||||||
|
JSON.stringify(boxes.values),
|
||||||
|
)
|
||||||
|
|
||||||
|
const hint = async () =>
|
||||||
|
(await page.locator('.size-hint').first().innerText()).replace(/\s+/g, ' ')
|
||||||
|
check(
|
||||||
|
'the hint says what it will measure on the page',
|
||||||
|
/显示 638×399/.test(await hint()),
|
||||||
|
await hint(),
|
||||||
|
)
|
||||||
|
|
||||||
|
// Typing a value that is not one of the presets is the point of the control:
|
||||||
|
// the size a panel wants is what it measures, not a round number.
|
||||||
|
await page.locator('.width-select input').first().fill('30%')
|
||||||
|
await page.keyboard.press('Enter')
|
||||||
|
await page.waitForTimeout(400)
|
||||||
|
check('typing 30% converts immediately', /显示 383×239/.test(await hint()), await hint())
|
||||||
|
|
||||||
|
await page.getByRole('button', { name: '保存段落' }).click()
|
||||||
|
await page.waitForSelector('.el-dialog', { state: 'detached', timeout: 15000 })
|
||||||
|
await page.waitForTimeout(700)
|
||||||
|
|
||||||
|
const stored = await api('GET', `/papers/${paperId}/paragraphs/${sort}`)
|
||||||
|
const sized = stored.paragraph.sentences.find((sentence) =>
|
||||||
|
sentence.content.includes('试验装置示意图'),
|
||||||
|
)
|
||||||
|
check('what was typed is what is stored', sized?.content.endsWith('{width=30%}'), sized?.content)
|
||||||
|
|
||||||
|
const shrunk = await page.evaluate(() => {
|
||||||
|
const body = document.querySelector('.paragraph-body')
|
||||||
|
const column = Math.round(body.getBoundingClientRect().width)
|
||||||
|
const figure = [...document.querySelectorAll('.sentence--figure')].find(
|
||||||
|
(node) => node.querySelector('.figure-caption')?.textContent.trim() === '试验装置示意图',
|
||||||
|
)
|
||||||
|
const box = figure.querySelector('img').getBoundingClientRect()
|
||||||
|
return { column, width: Math.round(box.width), height: Math.round(box.height) }
|
||||||
|
})
|
||||||
|
check(
|
||||||
|
'and the paper prints it at that size',
|
||||||
|
Math.abs(shrunk.width - shrunk.column * 0.3) <= 2,
|
||||||
|
`${shrunk.width} vs ${shrunk.column * 0.3}`,
|
||||||
|
)
|
||||||
|
|
||||||
|
// Taking the size off again: 原尺寸, which is what the placeholder promises.
|
||||||
|
await page.locator('.paragraph-actions button:has-text("编辑")').first().click()
|
||||||
|
await page.waitForSelector('.width-select', { timeout: 15000 })
|
||||||
|
await page.waitForFunction(
|
||||||
|
() => document.querySelector('.size-hint')?.textContent?.includes('原图'),
|
||||||
|
{ timeout: 15000 },
|
||||||
|
)
|
||||||
|
await page.locator('.width-select').first().hover()
|
||||||
|
await page.locator('.width-select .el-select__clear').first().click({ force: true })
|
||||||
|
await page.waitForTimeout(300)
|
||||||
|
check('clearing it goes back to the natural size', /显示 480×300/.test(await hint()), await hint())
|
||||||
|
|
||||||
|
// A size the reader cannot read is refused rather than stored: a figure that
|
||||||
|
// quietly prints at its natural size is the bug this control exists to fix.
|
||||||
|
await page.locator('.width-select input').first().fill('宽一点')
|
||||||
|
await page.keyboard.press('Enter')
|
||||||
|
await page.waitForTimeout(400)
|
||||||
|
check(
|
||||||
|
'a size that is not one is refused',
|
||||||
|
await page.evaluate(() => Boolean(document.querySelector('.el-message--warning'))),
|
||||||
|
)
|
||||||
|
check('and the sentence keeps the size it had', /显示 480×300/.test(await hint()), await hint())
|
||||||
|
await page.getByRole('button', { name: '取消' }).click()
|
||||||
|
await page.waitForSelector('.el-dialog', { state: 'detached', timeout: 15000 })
|
||||||
|
|
||||||
|
// --- a height, which is what a writer asks for when the width is fine -----
|
||||||
|
//
|
||||||
|
// Not every figure needs resizing from the left edge: a tall panel is made
|
||||||
|
// short by its *height*, and its width has to follow or the picture deforms.
|
||||||
|
// Written through the API so what is checked is the reader's rule, not the
|
||||||
|
// editor's; the 480×300 fixture makes the arithmetic checkable by hand.
|
||||||
|
const shapeOf = async (attributes) => {
|
||||||
|
await api('PUT', `/papers/${paperId}/paragraphs/${sort}`, {
|
||||||
|
sentences: [{ content: `${attributes}`, line_break_before: true }],
|
||||||
|
})
|
||||||
|
await page.reload({ waitUntil: 'networkidle' })
|
||||||
|
await page.waitForSelector('.sentence--figure img')
|
||||||
|
await page.waitForFunction(
|
||||||
|
() => document.querySelector('.sentence--figure img')?.complete,
|
||||||
|
{ timeout: 15000 },
|
||||||
|
)
|
||||||
|
return page.evaluate(() => {
|
||||||
|
const body = document.querySelector('.paragraph-body')
|
||||||
|
const img = document.querySelector('.sentence--figure img')
|
||||||
|
const box = img.getBoundingClientRect()
|
||||||
|
return {
|
||||||
|
column: Math.round(body.getBoundingClientRect().width),
|
||||||
|
width: Math.round(box.width),
|
||||||
|
height: Math.round(box.height),
|
||||||
|
ratio: box.width / box.height,
|
||||||
|
natural: img.naturalWidth / img.naturalHeight,
|
||||||
|
style: img.getAttribute('style') ?? '',
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
const onlyHeight = await shapeOf('{height=200px}')
|
||||||
|
check(
|
||||||
|
'只填高度时,高度就是填的那个数',
|
||||||
|
Math.abs(onlyHeight.height - 200) <= 1,
|
||||||
|
JSON.stringify(onlyHeight),
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
'只填高度时,宽度按原比例跟着算(480×300 → 320×200)',
|
||||||
|
Math.abs(onlyHeight.width - 320) <= 2,
|
||||||
|
JSON.stringify(onlyHeight),
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
'只填高度时,图还是原来的形状',
|
||||||
|
Math.abs(onlyHeight.ratio / onlyHeight.natural - 1) < 0.01,
|
||||||
|
JSON.stringify(onlyHeight),
|
||||||
|
)
|
||||||
|
|
||||||
|
const both = await shapeOf('{width=400px height=100px}')
|
||||||
|
check(
|
||||||
|
'宽高都填时,图放进这个框里(400×100 的框 → 160×100)',
|
||||||
|
Math.abs(both.width - 160) <= 2 && Math.abs(both.height - 100) <= 1,
|
||||||
|
JSON.stringify(both),
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
'宽高都填时也没有被拉变形',
|
||||||
|
Math.abs(both.ratio / both.natural - 1) < 0.01,
|
||||||
|
JSON.stringify(both),
|
||||||
|
)
|
||||||
|
|
||||||
|
const huge = await shapeOf('{height=2000px}')
|
||||||
|
check(
|
||||||
|
'高度是个上限:不会把图放大,也不会把它推出栏外',
|
||||||
|
huge.width === 480 && huge.height === 300,
|
||||||
|
JSON.stringify(huge),
|
||||||
|
)
|
||||||
|
|
||||||
|
// …and the same thing typed into the editor's 高 box.
|
||||||
|
await page.locator('.paragraph-actions button:has-text("编辑")').first().click()
|
||||||
|
await page.waitForSelector('.width-select', { timeout: 15000 })
|
||||||
|
await page.waitForFunction(
|
||||||
|
() => document.querySelector('.size-hint')?.textContent?.includes('原图'),
|
||||||
|
{ timeout: 15000 },
|
||||||
|
)
|
||||||
|
check(
|
||||||
|
'编辑器里宽、高各有一个框',
|
||||||
|
(await page.locator('.width-select').count()) === 2,
|
||||||
|
`${await page.locator('.width-select').count()} boxes`,
|
||||||
|
)
|
||||||
|
await page.locator('.width-select').nth(1).locator('input').fill('250')
|
||||||
|
await page.keyboard.press('Enter')
|
||||||
|
await page.waitForTimeout(400)
|
||||||
|
check('填高度后立刻换算(250 → 400×250)', /显示 400×250/.test(await hint()), await hint())
|
||||||
|
await page.getByRole('button', { name: '保存段落' }).click()
|
||||||
|
await page.waitForSelector('.el-dialog', { state: 'detached', timeout: 15000 })
|
||||||
|
await page.waitForTimeout(700)
|
||||||
|
const savedHeight = await api('GET', `/papers/${paperId}/paragraphs/${sort}`)
|
||||||
|
check(
|
||||||
|
'存下来的也是高度',
|
||||||
|
savedHeight.paragraph.sentences[0].content.endsWith('{height=250px}'),
|
||||||
|
savedHeight.paragraph.sentences[0].content,
|
||||||
|
)
|
||||||
|
} finally {
|
||||||
|
await browser.close()
|
||||||
|
if (paperId) {
|
||||||
|
await api('DELETE', `/papers/${paperId}`).catch((error) => console.error('cleanup:', error.message))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const failed = results.filter(([, ok]) => !ok)
|
||||||
|
console.log(`\n${results.length - failed.length}/${results.length} checks passed`)
|
||||||
|
process.exit(failed.length ? 1 : 0)
|
||||||
@@ -40,6 +40,34 @@ import {
|
|||||||
type ImageSegment,
|
type ImageSegment,
|
||||||
} from '@/utils/rich'
|
} from '@/utils/rich'
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The CSS a figure's size becomes.
|
||||||
|
*
|
||||||
|
* The writer may give a width, a height, or both, and the picture is never
|
||||||
|
* stretched in any of the three cases:
|
||||||
|
*
|
||||||
|
* * **a width** — that width, exactly, and the height follows from the picture's
|
||||||
|
* own shape (which is what `height: auto` means);
|
||||||
|
* * **a height** — a *cap* on it, with the width following. A cap rather than an
|
||||||
|
* exact number because nothing enlarges a picture usefully: a height is the
|
||||||
|
* one dimension with no reference to measure against — the column gives a
|
||||||
|
* percentage its meaning, and a height has nothing — so asking for one only
|
||||||
|
* ever means "no taller than this". In the flow of a sentence it always is a
|
||||||
|
* downscale, which is the same thing as exact;
|
||||||
|
* * **both** — a box to fit *inside*, which is the only honest reading of two
|
||||||
|
* numbers that need not have the picture's proportions.
|
||||||
|
*
|
||||||
|
* In all three the height is left to the browser, so the picture keeps its own
|
||||||
|
* shape. Nothing here can stretch one.
|
||||||
|
*/
|
||||||
|
function sizeStyle(figure: ImageSegment): Record<string, string> | undefined {
|
||||||
|
const { width, height } = figure
|
||||||
|
if (width && height) return { maxWidth: width, maxHeight: height }
|
||||||
|
if (width) return { width }
|
||||||
|
if (height) return { maxHeight: height }
|
||||||
|
return undefined
|
||||||
|
}
|
||||||
|
|
||||||
const props = defineProps<{
|
const props = defineProps<{
|
||||||
paragraph: PaperParagraph
|
paragraph: PaperParagraph
|
||||||
/** Citation id -> the number shown in the text, assigned by reading order. */
|
/** Citation id -> the number shown in the text, assigned by reading order. */
|
||||||
@@ -219,7 +247,7 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_
|
|||||||
class="figure-image"
|
class="figure-image"
|
||||||
:src="item.figure.src"
|
:src="item.figure.src"
|
||||||
:alt="item.figure.alt"
|
:alt="item.figure.alt"
|
||||||
:style="item.figure.width ? { width: item.figure.width } : undefined"
|
:style="sizeStyle(item.figure)"
|
||||||
loading="lazy"
|
loading="lazy"
|
||||||
decoding="async"
|
decoding="async"
|
||||||
/>
|
/>
|
||||||
|
|||||||
@@ -46,7 +46,15 @@ import {
|
|||||||
type SentenceInput,
|
type SentenceInput,
|
||||||
} from '@/api/papers'
|
} from '@/api/papers'
|
||||||
import { PARAGRAPH_UNSET_LABEL, foldWhitespace } from '@/utils/format'
|
import { PARAGRAPH_UNSET_LABEL, foldWhitespace } from '@/utils/format'
|
||||||
import { hasDisplayMath, imagesOf, type ImageSegment } from '@/utils/rich'
|
import {
|
||||||
|
figureOf,
|
||||||
|
hasDisplayMath,
|
||||||
|
imagesOf,
|
||||||
|
parseImageHeight,
|
||||||
|
parseImageWidth,
|
||||||
|
withImageSize,
|
||||||
|
type ImageSegment,
|
||||||
|
} from '@/utils/rich'
|
||||||
|
|
||||||
const props = defineProps<{
|
const props = defineProps<{
|
||||||
/** Visibility, used with `v-model`. */
|
/** Visibility, used with `v-model`. */
|
||||||
@@ -82,6 +90,15 @@ interface SentenceDraft {
|
|||||||
/** How a display formula in this sentence is set. */
|
/** How a display formula in this sentence is set. */
|
||||||
align: FormulaAlign
|
align: FormulaAlign
|
||||||
citations: CitationDraft[]
|
citations: CitationDraft[]
|
||||||
|
/**
|
||||||
|
* The natural size of the row's first picture, once it has decoded.
|
||||||
|
*
|
||||||
|
* Measured from the loaded thumbnail rather than stored: it is a property of
|
||||||
|
* the file, and the editor's job here is to tell the writer what 50% of *this*
|
||||||
|
* picture would come to, which cannot be guessed from the Markdown.
|
||||||
|
*/
|
||||||
|
naturalWidth: number | null
|
||||||
|
naturalHeight: number | null
|
||||||
}
|
}
|
||||||
|
|
||||||
const visible = computed({
|
const visible = computed({
|
||||||
@@ -154,6 +171,8 @@ watch(
|
|||||||
reference_id: citation.reference_id,
|
reference_id: citation.reference_id,
|
||||||
quote: citation.quote,
|
quote: citation.quote,
|
||||||
})),
|
})),
|
||||||
|
naturalWidth: null,
|
||||||
|
naturalHeight: null,
|
||||||
}))
|
}))
|
||||||
} catch (error) {
|
} catch (error) {
|
||||||
ElMessage.error(errorMessage(error))
|
ElMessage.error(errorMessage(error))
|
||||||
@@ -177,6 +196,8 @@ function addSentence(): void {
|
|||||||
lineBreak: false,
|
lineBreak: false,
|
||||||
align: 'center',
|
align: 'center',
|
||||||
citations: [],
|
citations: [],
|
||||||
|
naturalWidth: null,
|
||||||
|
naturalHeight: null,
|
||||||
})
|
})
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -189,6 +210,144 @@ function rowImages(row: SentenceDraft): ImageSegment[] {
|
|||||||
return imagesOf(row.content)
|
return imagesOf(row.content)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// --- how wide a figure prints ---------------------------------------------
|
||||||
|
|
||||||
|
/** The sizes the selects offer; anything else is typed into them. */
|
||||||
|
const WIDTH_PRESETS = ['25%', '50%', '70%', '100%']
|
||||||
|
const HEIGHT_PRESETS = ['120px', '200px', '300px', '400px']
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The size a row's figure prints at, as the reader parsed it.
|
||||||
|
*
|
||||||
|
* Read from the content, never stored beside it: `{width=70%}` *is* the size,
|
||||||
|
* and a second copy of it in the draft is a second thing that can be wrong.
|
||||||
|
* A row that holds no figure, or one whose attribute the reader would not
|
||||||
|
* accept, answers `null` — which is what "原尺寸" means.
|
||||||
|
*/
|
||||||
|
function figureWidth(row: SentenceDraft): string | null {
|
||||||
|
return figureOf(row.content)?.width ?? null
|
||||||
|
}
|
||||||
|
|
||||||
|
/** The height a row's figure prints at, as the reader parsed it — pixels only. */
|
||||||
|
function figureHeight(row: SentenceDraft): string | null {
|
||||||
|
return figureOf(row.content)?.height ?? null
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Remember a picture's own size, so the hint below can do the arithmetic. */
|
||||||
|
function rememberNatural(row: SentenceDraft, event: Event): void {
|
||||||
|
const image = event.target as HTMLImageElement
|
||||||
|
row.naturalWidth = image.naturalWidth || null
|
||||||
|
row.naturalHeight = image.naturalHeight || null
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The column the paper prints in, measured from the page behind the dialog.
|
||||||
|
*
|
||||||
|
* A percentage is a share of *that*, so without it the editor could only say
|
||||||
|
* "70%" and leave the writer to find out how tall that is. Falls back to
|
||||||
|
* `null`, and the hint then says nothing rather than something invented.
|
||||||
|
*/
|
||||||
|
function paperColumn(): number | null {
|
||||||
|
const body = document.querySelector('.paragraph-body')
|
||||||
|
const width = body?.getBoundingClientRect().width ?? 0
|
||||||
|
return width > 0 ? Math.round(width) : null
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* What a row's figure will measure on the page — `893×955` — or `null`.
|
||||||
|
*
|
||||||
|
* This is the number the writer actually needs. A paper's figures come out of
|
||||||
|
* the plotting tool at whatever size they were made — a 4169-pixel panel and a
|
||||||
|
* 1296-pixel one — and both are wider than the column, so without a size they
|
||||||
|
* all print at the full column and a near-square one fills a whole page.
|
||||||
|
* Measured on this paper's column: 1276px wide, and 图12 (1857×1986) would come
|
||||||
|
* out 1365px tall at 原尺寸 against 955px at 70%.
|
||||||
|
*/
|
||||||
|
function drawnSize(row: SentenceDraft): string | null {
|
||||||
|
const { naturalWidth, naturalHeight } = row
|
||||||
|
if (!naturalWidth || !naturalHeight) return null
|
||||||
|
|
||||||
|
const column = paperColumn()
|
||||||
|
const width = figureWidth(row)
|
||||||
|
const height = figureHeight(row)
|
||||||
|
|
||||||
|
/** A width in pixels: a percentage is a share of the column. */
|
||||||
|
const askWidth = (): number | null => {
|
||||||
|
if (!width) return null
|
||||||
|
if (width.endsWith('%')) {
|
||||||
|
return column ? Math.round((column * Number.parseFloat(width)) / 100) : null
|
||||||
|
}
|
||||||
|
return Number.parseInt(width, 10)
|
||||||
|
}
|
||||||
|
|
||||||
|
// A width on its own is exact — the page sets `width` — and the height follows
|
||||||
|
// from the picture's shape.
|
||||||
|
if (width && !height) {
|
||||||
|
let pixels = askWidth()
|
||||||
|
if (!pixels) return null
|
||||||
|
if (column && pixels > column) pixels = column
|
||||||
|
return `${pixels}×${Math.round((pixels * naturalHeight) / naturalWidth)}`
|
||||||
|
}
|
||||||
|
|
||||||
|
// Otherwise the numbers are a box to fit inside, which is what the page does
|
||||||
|
// with `max-width` / `max-height` — and nothing ever enlarges a picture, so
|
||||||
|
// the scale starts at 1.
|
||||||
|
let scale = 1
|
||||||
|
if (column) scale = Math.min(scale, column / naturalWidth)
|
||||||
|
const asked = askWidth()
|
||||||
|
if (asked) scale = Math.min(scale, asked / naturalWidth)
|
||||||
|
if (height) scale = Math.min(scale, Number.parseInt(height, 10) / naturalHeight)
|
||||||
|
|
||||||
|
const drawnWidth = Math.max(1, Math.round(naturalWidth * scale))
|
||||||
|
const drawnHeight = Math.max(1, Math.round(naturalHeight * scale))
|
||||||
|
return `${drawnWidth}×${drawnHeight}`
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Apply what the writer chose, or said, to the row's figure.
|
||||||
|
*
|
||||||
|
* The value goes through the same `parseImageWidth` the reader uses, so what is
|
||||||
|
* written into the sentence is exactly what will be printed; a value it cannot
|
||||||
|
* read is refused here with the two forms that work, rather than stored as a
|
||||||
|
* size that quietly does not apply.
|
||||||
|
*/
|
||||||
|
function onWidthChange(row: SentenceDraft, value: string | null | undefined): void {
|
||||||
|
const text = (value ?? '').trim()
|
||||||
|
const parsed = text ? parseImageWidth(`{width=${text}}`) : null
|
||||||
|
if (text && !parsed) {
|
||||||
|
ElMessage.warning('宽度填百分比或像素:70%、60 或 400px(百分比 1–100,像素 1–4000)')
|
||||||
|
return
|
||||||
|
}
|
||||||
|
// The height is passed through untouched: typing in one box must not clear
|
||||||
|
// the other, or setting a size in two steps would be impossible.
|
||||||
|
row.content = withImageSize(row.content, {
|
||||||
|
width: parsed,
|
||||||
|
height: figureHeight(row),
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Apply a height, in pixels.
|
||||||
|
*
|
||||||
|
* Pixels only, and that is not a limitation to work around: a sentence is flowed
|
||||||
|
* text, so there is no container height for a `%` to mean anything against, and
|
||||||
|
* the browser's answer to one is to ignore it — a size that silently does not
|
||||||
|
* apply. `parseImageHeight` is the reader's own rule, so what is stored is what
|
||||||
|
* will be printed.
|
||||||
|
*/
|
||||||
|
function onHeightChange(row: SentenceDraft, value: string | null | undefined): void {
|
||||||
|
const text = (value ?? '').trim()
|
||||||
|
const parsed = text ? parseImageHeight(`{height=${text}}`) : null
|
||||||
|
if (text && !parsed) {
|
||||||
|
ElMessage.warning('高度填像素:300、300px 都行,范围 1–4000(高度不能用百分比)')
|
||||||
|
return
|
||||||
|
}
|
||||||
|
row.content = withImageSize(row.content, {
|
||||||
|
width: figureWidth(row),
|
||||||
|
height: parsed,
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
// --- images ---------------------------------------------------------------
|
// --- images ---------------------------------------------------------------
|
||||||
|
|
||||||
/** The hidden file picker the 「插入图片」 button drives. */
|
/** The hidden file picker the 「插入图片」 button drives. */
|
||||||
@@ -240,6 +399,8 @@ async function insertImages(files: File[]): Promise<void> {
|
|||||||
lineBreak: true,
|
lineBreak: true,
|
||||||
align: 'center',
|
align: 'center',
|
||||||
citations: [],
|
citations: [],
|
||||||
|
naturalWidth: null,
|
||||||
|
naturalHeight: null,
|
||||||
})
|
})
|
||||||
} catch (error) {
|
} catch (error) {
|
||||||
ElMessage.error(errorMessage(error))
|
ElMessage.error(errorMessage(error))
|
||||||
@@ -500,6 +661,67 @@ async function submit(): Promise<void> {
|
|||||||
:label="option.label"
|
:label="option.label"
|
||||||
/>
|
/>
|
||||||
</el-select>
|
</el-select>
|
||||||
|
|
||||||
|
<!-- A figure's size. Only a sentence that is nothing but a picture
|
||||||
|
prints as a 插图, and only that one has a size worth setting:
|
||||||
|
an image inside a sentence belongs to the line it sits in.
|
||||||
|
Typing is allowed as well as the presets, because the size that
|
||||||
|
suits a panel is whatever it measures, not a round number. -->
|
||||||
|
<template v-if="figureOf(row.content)">
|
||||||
|
<el-tooltip content="宽:70% 表示占栏宽的 70%,也可以填 400px" placement="top" :show-after="300">
|
||||||
|
<el-select
|
||||||
|
:model-value="figureWidth(row) ?? ''"
|
||||||
|
size="small"
|
||||||
|
class="width-select"
|
||||||
|
placeholder="宽 原尺寸"
|
||||||
|
clearable
|
||||||
|
filterable
|
||||||
|
allow-create
|
||||||
|
default-first-option
|
||||||
|
@change="onWidthChange(row, $event)"
|
||||||
|
>
|
||||||
|
<el-option
|
||||||
|
v-for="preset in WIDTH_PRESETS"
|
||||||
|
:key="preset"
|
||||||
|
:value="preset"
|
||||||
|
:label="preset"
|
||||||
|
/>
|
||||||
|
</el-select>
|
||||||
|
</el-tooltip>
|
||||||
|
<el-tooltip content="高:像素(340px 或 340),填了就让高度是这个值" placement="top" :show-after="300">
|
||||||
|
<el-select
|
||||||
|
:model-value="figureHeight(row) ?? ''"
|
||||||
|
size="small"
|
||||||
|
class="width-select"
|
||||||
|
placeholder="高 原尺寸"
|
||||||
|
clearable
|
||||||
|
filterable
|
||||||
|
allow-create
|
||||||
|
default-first-option
|
||||||
|
@change="onHeightChange(row, $event)"
|
||||||
|
>
|
||||||
|
<el-option
|
||||||
|
v-for="preset in HEIGHT_PRESETS"
|
||||||
|
:key="preset"
|
||||||
|
:value="preset"
|
||||||
|
:label="preset"
|
||||||
|
/>
|
||||||
|
</el-select>
|
||||||
|
</el-tooltip>
|
||||||
|
<el-tooltip
|
||||||
|
content="图片在版面上一共占多大(宽×高)。两个都填就是「放进这个框里」,图不会被拉变形。"
|
||||||
|
placement="top"
|
||||||
|
:show-after="300"
|
||||||
|
>
|
||||||
|
<span class="size-hint">
|
||||||
|
<template v-if="row.naturalWidth">
|
||||||
|
原图 {{ row.naturalWidth }}×{{ row.naturalHeight }}
|
||||||
|
</template>
|
||||||
|
<template v-if="drawnSize(row)">· 显示 {{ drawnSize(row) }}</template>
|
||||||
|
</span>
|
||||||
|
</el-tooltip>
|
||||||
|
</template>
|
||||||
|
|
||||||
<div class="toolbar-spacer" />
|
<div class="toolbar-spacer" />
|
||||||
<el-button
|
<el-button
|
||||||
link
|
link
|
||||||
@@ -530,7 +752,15 @@ async function submit(): Promise<void> {
|
|||||||
right paragraph. -->
|
right paragraph. -->
|
||||||
<div class="row-images">
|
<div class="row-images">
|
||||||
<figure v-for="image in rowImages(row)" :key="image.src" class="row-image">
|
<figure v-for="image in rowImages(row)" :key="image.src" class="row-image">
|
||||||
<img :src="image.src" :alt="image.alt" loading="lazy" />
|
<!-- Thumbnails are identification, not a preview of the printed
|
||||||
|
size — they are a fixed 168px box, and the size control above
|
||||||
|
says what the figure will actually measure. -->
|
||||||
|
<img
|
||||||
|
:src="image.src"
|
||||||
|
:alt="image.alt"
|
||||||
|
loading="lazy"
|
||||||
|
@load="rememberNatural(row, $event)"
|
||||||
|
/>
|
||||||
<figcaption>{{ image.alt || '方括号里写的就是图注' }}</figcaption>
|
<figcaption>{{ image.alt || '方括号里写的就是图注' }}</figcaption>
|
||||||
</figure>
|
</figure>
|
||||||
</div>
|
</div>
|
||||||
@@ -683,6 +913,7 @@ async function submit(): Promise<void> {
|
|||||||
.row-head {
|
.row-head {
|
||||||
display: flex;
|
display: flex;
|
||||||
align-items: center;
|
align-items: center;
|
||||||
|
flex-wrap: wrap;
|
||||||
gap: 8px;
|
gap: 8px;
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -699,6 +930,18 @@ async function submit(): Promise<void> {
|
|||||||
width: 112px;
|
width: 112px;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
.width-select {
|
||||||
|
width: 118px;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* What the figure will measure on the page: a number the writer acts on, so it
|
||||||
|
sits beside the control rather than in a tooltip nobody opens. */
|
||||||
|
.size-hint {
|
||||||
|
font-size: 12px;
|
||||||
|
color: var(--el-text-color-secondary);
|
||||||
|
white-space: nowrap;
|
||||||
|
}
|
||||||
|
|
||||||
.citations {
|
.citations {
|
||||||
display: flex;
|
display: flex;
|
||||||
flex-direction: column;
|
flex-direction: column;
|
||||||
|
|||||||
+109
-4
@@ -41,7 +41,15 @@ import katex from 'katex'
|
|||||||
export type RichSegment =
|
export type RichSegment =
|
||||||
| { kind: 'text'; value: string }
|
| { kind: 'text'; value: string }
|
||||||
| { kind: 'math'; value: string; display: boolean }
|
| { kind: 'math'; value: string; display: boolean }
|
||||||
| { kind: 'image'; src: string; alt: string; width: string | null }
|
| {
|
||||||
|
kind: 'image'
|
||||||
|
src: string
|
||||||
|
alt: string
|
||||||
|
/** `70%`, `400px`, or `null` for the picture's own width. */
|
||||||
|
width: string | null
|
||||||
|
/** `300px`, or `null` — never a percentage, which has nothing to be one of. */
|
||||||
|
height: string | null
|
||||||
|
}
|
||||||
|
|
||||||
/** An image segment, which is what a figure is made of. */
|
/** An image segment, which is what a figure is made of. */
|
||||||
export type ImageSegment = Extract<RichSegment, { kind: 'image' }>
|
export type ImageSegment = Extract<RichSegment, { kind: 'image' }>
|
||||||
@@ -70,8 +78,14 @@ const RICH_PATTERN = new RegExp(
|
|||||||
* The value is validated here rather than trusted and escaped later, because
|
* The value is validated here rather than trusted and escaped later, because
|
||||||
* what it becomes is a CSS length on the element. Digits and at most one unit,
|
* what it becomes is a CSS length on the element. Digits and at most one unit,
|
||||||
* nothing else: there is no way to express a second declaration through it.
|
* nothing else: there is no way to express a second declaration through it.
|
||||||
|
*
|
||||||
|
* The height is read the same way, but **pixels only**. A percentage height has
|
||||||
|
* nothing to be a percentage *of* — a sentence is flowed text, so there is no
|
||||||
|
* container height to measure against — and the browser's answer to one is to
|
||||||
|
* ignore it, which is a size that silently does not apply.
|
||||||
*/
|
*/
|
||||||
const WIDTH_PATTERN = /^\s*(?:w|width)\s*=\s*(\d{1,4})\s*(%|px)?\s*$/i
|
const WIDTH_PATTERN = /^\s*(?:w|width)\s*=\s*(\d{1,4})\s*(%|px)?\s*$/i
|
||||||
|
const HEIGHT_PATTERN = /^\s*(?:h|height)\s*=\s*(\d{1,4})\s*(px)?\s*$/i
|
||||||
|
|
||||||
/** The largest absolute width we will set, so a typo cannot push a figure off. */
|
/** The largest absolute width we will set, so a typo cannot push a figure off. */
|
||||||
const MAX_PIXELS = 4000
|
const MAX_PIXELS = 4000
|
||||||
@@ -89,11 +103,34 @@ export function escapeHtml(value: string): string {
|
|||||||
return value.replace(/[&<>"']/g, (character) => HTML_ESCAPES[character] ?? character)
|
return value.replace(/[&<>"']/g, (character) => HTML_ESCAPES[character] ?? character)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The declarations inside an attribute block: `{width=400 height=200}` is two.
|
||||||
|
*
|
||||||
|
* Splitting first is what lets the two patterns below stay anchored to a whole
|
||||||
|
* declaration. Matching them against the raw block instead looks equivalent and
|
||||||
|
* is not: with both a width and a height written, neither pattern matches
|
||||||
|
* anything, and the size silently falls back to the picture's own — which is
|
||||||
|
* exactly the bug the browser check found here.
|
||||||
|
*/
|
||||||
|
function declarations(attributes: string | undefined): string[] {
|
||||||
|
if (!attributes) return []
|
||||||
|
return attributes
|
||||||
|
.replace(/^\{|\}$/g, '')
|
||||||
|
.trim()
|
||||||
|
.split(/\s+/)
|
||||||
|
.filter(Boolean)
|
||||||
|
}
|
||||||
|
|
||||||
|
function declared(attributes: string | undefined, key: RegExp): string | undefined {
|
||||||
|
return declarations(attributes).find((part) => key.test(part))
|
||||||
|
}
|
||||||
|
|
||||||
/** Read a size out of an image's attributes, or refuse to guess one. */
|
/** Read a size out of an image's attributes, or refuse to guess one. */
|
||||||
export function parseImageWidth(attributes: string | undefined): string | null {
|
export function parseImageWidth(attributes: string | undefined): string | null {
|
||||||
if (!attributes) return null
|
const part = declared(attributes, /^(?:w|width)\s*=/i)
|
||||||
|
if (!part) return null
|
||||||
|
|
||||||
const match = WIDTH_PATTERN.exec(attributes.replace(/^\{|\}$/g, ''))
|
const match = WIDTH_PATTERN.exec(part)
|
||||||
if (!match) return null
|
if (!match) return null
|
||||||
|
|
||||||
const value = Number(match[1])
|
const value = Number(match[1])
|
||||||
@@ -103,6 +140,72 @@ export function parseImageWidth(attributes: string | undefined): string | null {
|
|||||||
return value >= 1 && value <= 100 ? `${value}%` : null
|
return value >= 1 && value <= 100 ? `${value}%` : null
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** Read a height, in pixels, or `null` for "whatever the shape works out to". */
|
||||||
|
export function parseImageHeight(attributes: string | undefined): string | null {
|
||||||
|
const part = declared(attributes, /^(?:h|height)\s*=/i)
|
||||||
|
if (!part) return null
|
||||||
|
|
||||||
|
const match = HEIGHT_PATTERN.exec(part)
|
||||||
|
if (!match) return null
|
||||||
|
|
||||||
|
const value = Number(match[1])
|
||||||
|
return value >= 1 && value <= MAX_PIXELS ? `${value}px` : null
|
||||||
|
}
|
||||||
|
|
||||||
|
/** The size a picture is asked for: either half may be missing. */
|
||||||
|
export interface ImageSize {
|
||||||
|
width: string | null
|
||||||
|
height: string | null
|
||||||
|
}
|
||||||
|
|
||||||
|
/** Both halves of an image's size, read from its attribute block. */
|
||||||
|
export function parseImageSize(attributes: string | undefined): ImageSize {
|
||||||
|
return {
|
||||||
|
width: parseImageWidth(attributes),
|
||||||
|
height: parseImageHeight(attributes),
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The image alternative on its own, with its parts captured separately.
|
||||||
|
*
|
||||||
|
* Written out rather than reused from `RICH_PATTERN` because this one *rebuilds*
|
||||||
|
* the markup: a replace over the combined pattern would have to reconstruct the
|
||||||
|
* groups of formulas it never touched, and a mis-copied group is a sentence the
|
||||||
|
* writer did not write. It has to keep matching what that pattern calls an
|
||||||
|
* image — the alternative is the first one there, for the same reason (`![` is
|
||||||
|
* not how a formula starts).
|
||||||
|
*/
|
||||||
|
const IMAGE_AT = /!\[([^\]]*)\]\(([^()\s]+)(?:\s+"([^"]*)")?\)(?:\{([^}]*)\})?/
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Write a size onto the picture a sentence holds — or take it off again.
|
||||||
|
*
|
||||||
|
* Only the first picture is touched. The controls that call this are offered for
|
||||||
|
* a *figure* (a sentence holding nothing but one image), and a sentence with
|
||||||
|
* words around its picture is a different thing that this must not silently
|
||||||
|
* resize.
|
||||||
|
*
|
||||||
|
* Both halves are written together, so a call that sets only a height keeps the
|
||||||
|
* width it did not mention — which is what the editor expects when the writer
|
||||||
|
* types into one of the two boxes. `null` on both leaves the picture at its
|
||||||
|
* natural size.
|
||||||
|
*/
|
||||||
|
export function withImageSize(content: string, size: ImageSize): string {
|
||||||
|
const parts: string[] = []
|
||||||
|
if (size.width) parts.push(`width=${size.width}`)
|
||||||
|
if (size.height) parts.push(`height=${size.height}`)
|
||||||
|
const attribute = parts.length ? `{${parts.join(' ')}}` : ''
|
||||||
|
|
||||||
|
let replaced = false
|
||||||
|
return content.replace(IMAGE_AT, (whole, alt: string, src: string, title?: string) => {
|
||||||
|
if (replaced) return whole
|
||||||
|
replaced = true
|
||||||
|
const name = title === undefined ? '' : ` "${title}"`
|
||||||
|
return `${attribute}`
|
||||||
|
})
|
||||||
|
}
|
||||||
|
|
||||||
/** Split a sentence into its plain, mathematical and pictorial parts. */
|
/** Split a sentence into its plain, mathematical and pictorial parts. */
|
||||||
export function splitRich(content: string): RichSegment[] {
|
export function splitRich(content: string): RichSegment[] {
|
||||||
const segments: RichSegment[] = []
|
const segments: RichSegment[] = []
|
||||||
@@ -116,11 +219,13 @@ export function splitRich(content: string): RichSegment[] {
|
|||||||
|
|
||||||
const groups = match.groups ?? {}
|
const groups = match.groups ?? {}
|
||||||
if (groups.src !== undefined) {
|
if (groups.src !== undefined) {
|
||||||
|
const size = parseImageSize(groups.attrs)
|
||||||
segments.push({
|
segments.push({
|
||||||
kind: 'image',
|
kind: 'image',
|
||||||
src: groups.src,
|
src: groups.src,
|
||||||
alt: groups.alt ?? '',
|
alt: groups.alt ?? '',
|
||||||
width: parseImageWidth(groups.attrs),
|
width: size.width,
|
||||||
|
height: size.height,
|
||||||
})
|
})
|
||||||
} else {
|
} else {
|
||||||
segments.push({
|
segments.push({
|
||||||
|
|||||||
Reference in New Issue
Block a user