Compare commits
6 Commits
0e0fde8f02
..
main
| Author | SHA1 | Date | |
|---|---|---|---|
| 1531263bd2 | |||
| b19f28492e | |||
| 48f0c12fd2 | |||
| 9e6a1f8c3e | |||
| ebaf9e558b | |||
| eb0f12b8cf |
@@ -219,7 +219,16 @@ class ImageStore:
|
||||
return
|
||||
except ClientError as error:
|
||||
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
|
||||
|
||||
try:
|
||||
|
||||
@@ -27,6 +27,15 @@ from pydantic import BaseModel, Field
|
||||
#: of an explicit list. See :func:`app.mcp.support.split_text`.
|
||||
SplitMode = Literal["line", "sentence", "paragraph"]
|
||||
|
||||
#: Where a display formula sits on its line. Spelled out here rather than as a
|
||||
#: plain ``str`` so the JSON Schema a client receives carries the three values:
|
||||
#: a model that reads "formula_align: string" invents ``middle``.
|
||||
#:
|
||||
#: This is the same set as :data:`app.models.paper_sentence.FORMULA_ALIGNMENTS`,
|
||||
#: which the payload validator enforces; a value outside it is refused by the
|
||||
#: same message the REST API gives.
|
||||
FormulaAlign = Literal["center", "left", "right"]
|
||||
|
||||
|
||||
class CitationSpec(BaseModel):
|
||||
"""One citation of one sentence."""
|
||||
@@ -42,9 +51,22 @@ class CitationSpec(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="句子正文;空白会被折叠成一行")]
|
||||
sort: Annotated[
|
||||
int | None,
|
||||
Field(description="段内排序值;不传则按写入顺序接在段尾"),
|
||||
] = None
|
||||
line_break_before: Annotated[
|
||||
bool,
|
||||
Field(
|
||||
@@ -55,6 +77,15 @@ class SentenceSpec(BaseModel):
|
||||
)
|
||||
),
|
||||
] = False
|
||||
formula_align: Annotated[
|
||||
FormulaAlign,
|
||||
Field(
|
||||
description=(
|
||||
"display 公式在这一行怎么排:center(默认)/ left / right。"
|
||||
"只对含 $$…$$ 的句子有意义,句号后的编号始终靠右"
|
||||
)
|
||||
),
|
||||
] = "center"
|
||||
citations: Annotated[
|
||||
list[CitationSpec],
|
||||
Field(description="这一段引用了哪些文献"),
|
||||
@@ -78,6 +109,10 @@ class TextSpec(BaseModel):
|
||||
)
|
||||
),
|
||||
] = False
|
||||
formula_align: Annotated[
|
||||
FormulaAlign,
|
||||
Field(description="这块切出来的公式怎么排:center(默认)/ left / right"),
|
||||
] = "center"
|
||||
citations: Annotated[
|
||||
list[CitationSpec],
|
||||
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
|
||||
# that happens to have no spaces in it.
|
||||
"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],
|
||||
}
|
||||
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 ``\[…\]``.
|
||||
#:
|
||||
#: 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
|
||||
#: 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
|
||||
#: prevent. Change one, change the other.
|
||||
_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."""
|
||||
return bool(_DISPLAY_MATH.search(sentence.content))
|
||||
|
||||
def _figure_caption(content: str) -> str | None:
|
||||
"""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(
|
||||
@@ -308,14 +340,20 @@ def paragraph_text(
|
||||
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.
|
||||
|
||||
A line break is printed where the model asked for one, and around a display
|
||||
formula — the paper view renders ``$$…$$`` as a block, so the lines on
|
||||
either side of it are line boundaries there too. A break *replaces* the
|
||||
A line break is printed where the model asked for one, and on both sides of
|
||||
a block — a display formula, or a sentence that is one figure — because 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
|
||||
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
|
||||
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*
|
||||
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
|
||||
@@ -325,7 +363,7 @@ def paragraph_text(
|
||||
parts: list[str] = []
|
||||
previous_block = False
|
||||
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):
|
||||
parts.append("\n")
|
||||
else:
|
||||
@@ -619,6 +657,50 @@ def _is_latin_break(text: str, index: int) -> bool:
|
||||
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]:
|
||||
"""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))
|
||||
|
||||
if item.get("content") is not None:
|
||||
out.append(
|
||||
SentenceInput(
|
||||
content=str(item["content"]),
|
||||
line_break_before=line_break,
|
||||
citations=citations,
|
||||
)
|
||||
)
|
||||
out.append(sentence_payload(item, citations=citations))
|
||||
continue
|
||||
|
||||
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
|
||||
# into three lines of the paper.
|
||||
out.append(
|
||||
SentenceInput(
|
||||
sentence_payload(
|
||||
item,
|
||||
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,
|
||||
citations=citations,
|
||||
)
|
||||
@@ -728,6 +808,7 @@ def paragraph_inputs(spec: Any) -> list[SentenceInput]:
|
||||
|
||||
__all__ = [
|
||||
"MAX_PAGE_SIZE",
|
||||
"SENTENCE_FIELDS",
|
||||
"SPLIT_MODES",
|
||||
"clean",
|
||||
"citation_row",
|
||||
@@ -747,7 +828,9 @@ __all__ = [
|
||||
"resolve_position",
|
||||
"sentence_inputs",
|
||||
"sentence_or_fail",
|
||||
"sentence_payload",
|
||||
"sentence_row",
|
||||
"sentence_values",
|
||||
"session",
|
||||
"split_text",
|
||||
"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
|
||||
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.
|
||||
|
||||
Prefixes are load-bearing: every tool name starts with its group
|
||||
(``paper_``, ``paragraph_``, ``sentence_``, ``template_``, ``field_``), because
|
||||
that prefix is what a model uses to pick a tool out of a list of twenty-nine
|
||||
without reading all twenty-nine descriptions.
|
||||
(``paper_``, ``paragraph_``, ``sentence_``, ``template_``, ``field_``,
|
||||
``reference_``, ``reference_tag_``, ``image_``), because that prefix is what a
|
||||
model uses to pick a tool out of a list of forty without reading all forty
|
||||
descriptions.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -18,6 +19,7 @@ from mcp.server.mcpserver import MCPServer
|
||||
|
||||
from app.mcp.tools import (
|
||||
fields,
|
||||
images,
|
||||
papers,
|
||||
paragraphs,
|
||||
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
|
||||
#: the order a paper is actually written in: find it, shape it, write it, then
|
||||
#: the things it is written against.
|
||||
MODULES = (papers, paragraphs, sentences, templates, fields, references, reference_tags)
|
||||
#: the things it is written against — and last the figure, which is written by
|
||||
#: putting a sentence somewhere.
|
||||
MODULES = (
|
||||
papers,
|
||||
paragraphs,
|
||||
sentences,
|
||||
templates,
|
||||
fields,
|
||||
references,
|
||||
reference_tags,
|
||||
images,
|
||||
)
|
||||
|
||||
|
||||
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(
|
||||
db,
|
||||
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(
|
||||
**item.model_dump(),
|
||||
paper_template_filed_sort=position,
|
||||
content=item.content,
|
||||
line_break_before=item.line_break_before,
|
||||
citations=item.citations,
|
||||
sort=item.sort,
|
||||
),
|
||||
)
|
||||
else:
|
||||
|
||||
@@ -204,19 +204,13 @@ def register(server: MCPServer) -> None:
|
||||
if not rows:
|
||||
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 = [
|
||||
SentenceInput(
|
||||
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),
|
||||
)
|
||||
SentenceInput(**s.sentence_values(row), citations=list(row.citations))
|
||||
for row in rows
|
||||
]
|
||||
paper_crud.replace_paragraph(
|
||||
@@ -266,6 +260,11 @@ def _write(
|
||||
at a time — the same call ``POST /papers/{id}/sentences`` makes — rather
|
||||
than read-modify-write, so two sentences appended in one request cannot
|
||||
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":
|
||||
for item in inputs:
|
||||
@@ -273,11 +272,7 @@ def _write(
|
||||
db,
|
||||
paper,
|
||||
SentenceCreate(
|
||||
paper_template_filed_sort=field_sort,
|
||||
content=item.content,
|
||||
line_break_before=item.line_break_before,
|
||||
citations=item.citations,
|
||||
sort=item.sort,
|
||||
**item.model_dump(), paper_template_filed_sort=field_sort
|
||||
),
|
||||
)
|
||||
else:
|
||||
|
||||
@@ -32,6 +32,7 @@ from typing import Any, TypeVar
|
||||
from mcp.server.mcpserver import MCPServer
|
||||
from mcp.server.mcpserver.exceptions import ToolError
|
||||
|
||||
from app.core.storage import StorageUnavailable, UnsupportedImage
|
||||
from app.crud.reference import UnknownReference
|
||||
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
|
||||
#: "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.
|
||||
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(
|
||||
|
||||
@@ -20,7 +20,7 @@ from pydantic import Field
|
||||
|
||||
from app.crud import paper as paper_crud
|
||||
from app.mcp import support as s
|
||||
from app.mcp.specs import CitationSpec
|
||||
from app.mcp.specs import CitationSpec, FormulaAlign
|
||||
from app.mcp.tools.registry import mcp_tool
|
||||
from app.models import Paper
|
||||
from app.schemas.paper import CitationInput, SentenceCreate, SentenceUpdate
|
||||
@@ -94,6 +94,10 @@ def register(server: MCPServer) -> None:
|
||||
)
|
||||
),
|
||||
] = False,
|
||||
formula_align: Annotated[
|
||||
FormulaAlign,
|
||||
Field(description="display 公式怎么排:center(默认)/ left / right"),
|
||||
] = "center",
|
||||
sort: Annotated[
|
||||
int | None, Field(description="段内位置;不传则排在段尾")
|
||||
] = None,
|
||||
@@ -109,6 +113,7 @@ def register(server: MCPServer) -> None:
|
||||
paper_template_filed_sort=field_sort,
|
||||
content=content,
|
||||
line_break_before=line_break_before,
|
||||
formula_align=formula_align,
|
||||
citations=_citations(citations or []),
|
||||
sort=sort,
|
||||
),
|
||||
@@ -137,17 +142,22 @@ def register(server: MCPServer) -> None:
|
||||
bool | None,
|
||||
Field(description="这一句是否另起一行;不传则不动,false 表示取消换行"),
|
||||
] = None,
|
||||
formula_align: Annotated[
|
||||
FormulaAlign | None,
|
||||
Field(description="display 公式怎么排;不传则不动"),
|
||||
] = None,
|
||||
citations: Annotated[
|
||||
list[CitationSpec] | None,
|
||||
Field(description="引用整组替换;传 [] 表示清空引用"),
|
||||
] = None,
|
||||
) -> str:
|
||||
"""修改一句话的正文、所属段落、排序、换行或引用(引用是整体替换)。"""
|
||||
"""修改一句话的正文、所属段落、排序、换行、公式对齐或引用(引用是整体替换)。"""
|
||||
if (
|
||||
content is None
|
||||
and position is None
|
||||
and sort is None
|
||||
and line_break_before is None
|
||||
and formula_align is None
|
||||
and citations is None
|
||||
):
|
||||
s.fail("没有给出任何要修改的内容")
|
||||
@@ -164,6 +174,7 @@ def register(server: MCPServer) -> None:
|
||||
paper_template_filed_sort=position,
|
||||
sort=sort,
|
||||
line_break_before=line_break_before,
|
||||
formula_align=formula_align,
|
||||
citations=None if citations is None else _citations(citations),
|
||||
),
|
||||
)
|
||||
|
||||
@@ -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
|
||||
|
||||
import argparse
|
||||
import base64
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
from collections.abc import AsyncIterator, Iterator
|
||||
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 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.schemas.paper import SentenceInput # noqa: E402
|
||||
|
||||
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
|
||||
_created_papers: 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")
|
||||
listed = await session.list_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(
|
||||
"every group is reachable",
|
||||
{
|
||||
@@ -180,10 +193,33 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
|
||||
"field_list",
|
||||
"reference_create",
|
||||
"reference_tag_create",
|
||||
"image_upload",
|
||||
}
|
||||
<= 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(
|
||||
"no tool returns a structured envelope",
|
||||
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",
|
||||
"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")
|
||||
paper = await call(
|
||||
@@ -864,7 +918,254 @@ async def _run(url: str | None = None, token: str | None = None) -> int:
|
||||
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]
|
||||
target = outline[1]
|
||||
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"])
|
||||
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)
|
||||
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 字段(改)")
|
||||
@@ -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("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(
|
||||
session,
|
||||
"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],
|
||||
)
|
||||
|
||||
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"])
|
||||
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"])
|
||||
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)
|
||||
check("deleted", deleted["deleted"] == 1, json.dumps(deleted, ensure_ascii=False))
|
||||
_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` |
|
||||
| Deployment | `paper-doc-mcp` | 1 副本,跑 MCP 服务的 http 传输 |
|
||||
| Service | `paper-doc-mcp` | NodePort **30931** → 容器 8931 |
|
||||
| ConfigMap | `paper-doc-config` | 非敏感环境变量(数据库地址、监听配置) |
|
||||
| Secret | `paper-doc-secrets` | `DB_USER` / `DB_PASSWORD` / `MCP_HTTP_TOKEN` |
|
||||
| ConfigMap | `paper-doc-config` | 非敏感环境变量(数据库地址、监听配置、MinIO 端点与桶名) |
|
||||
| Secret | `paper-doc-secrets` | `DB_USER` / `DB_PASSWORD` / `MCP_HTTP_TOKEN` / `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` |
|
||||
| Secret | `aliyun-acr` | 镜像仓库拉取凭证(从 `default` 复制) |
|
||||
|
||||
镜像:`registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v5`
|
||||
(`sha256:1e17a72ca611a498d93fc960a7fe1eba5ed5803376794efa66f1967830d51c5d`;
|
||||
镜像:`registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v8`
|
||||
(`sha256:fbbc4b1ab91ce80a3045f2990d85357f1cc267a2644639efe522a25cf42c4bc0`;
|
||||
`kubectl -n paper-doc get pods -o jsonpath='{.items[0].status.containerStatuses[0].imageID}'`
|
||||
对得上,才说明跑的就是 ACR 上那一版。历史:v1 首发布 → v2 重命名表 → v3 参考文献库 →
|
||||
v4 补参考文献 MCP 工具 → **v5 换行与参考文献表**。)
|
||||
v4 补参考文献 MCP 工具 → v5 换行与参考文献表 → v6 插图与公式对齐 → v7 插图的宽度写法与页面一致 → **v8 插图可分别填宽与高**。)
|
||||
|
||||
**数据库**:TiDB 已经在这个集群里,Deployment 用集群内的 Service
|
||||
`tidb-tidb.tidb:4000`,而不是宿主机用的 NodePort `192.168.1.88:32738`。
|
||||
两者是同一份数据;集群内用 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
|
||||
APP_NAME: paper-doc API
|
||||
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
|
||||
# a reader looks for them.
|
||||
MCP_TRANSPORT: http
|
||||
@@ -67,7 +75,7 @@ spec:
|
||||
type: RuntimeDefault
|
||||
containers:
|
||||
- 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
|
||||
ports:
|
||||
- name: http
|
||||
@@ -94,6 +102,19 @@ spec:
|
||||
secretKeyRef:
|
||||
name: paper-doc-secrets
|
||||
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
|
||||
# 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.
|
||||
@@ -178,13 +199,14 @@ spec:
|
||||
# imagePullSecrets: [{name: aliyun-acr}]
|
||||
# initContainers:
|
||||
# - 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"]
|
||||
# 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:
|
||||
# - 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"]
|
||||
# ports: [{name: http, containerPort: 8000}]
|
||||
# envFrom: [{configMapRef: {name: paper-doc-config}}]
|
||||
|
||||
@@ -5,11 +5,18 @@
|
||||
# kubectl -n paper-doc create secret generic paper-doc-secrets \
|
||||
# --from-literal=DB_USER='Govin' \
|
||||
# --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
|
||||
# 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
|
||||
# `aliyun-acr`, copied into this namespace from `default`, and it holds the
|
||||
# container registry's credentials rather than the application's.
|
||||
@@ -23,3 +30,5 @@ stringData:
|
||||
DB_USER: Govin
|
||||
DB_PASSWORD: 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` 读回来检查。
|
||||
|
||||
- 代码:`backend/app/mcp/`(工具实现)、`backend/scripts/mcp_server.py`(入口)
|
||||
- 冒烟测试:`backend/scripts/smoke_mcp.py`(真 MCP 客户端跑 99 项检查、覆盖 41/41 个工具,stdio 与 HTTP 都过)
|
||||
- 工具数量:**41 个**,按 `paper_` / `paragraph_` / `sentence_` / `template_` / `field_` / `reference_` / `reference_tag_` 七组前缀
|
||||
- 冒烟测试:`backend/scripts/smoke_mcp.py`(真 MCP 客户端跑 119 项检查、覆盖 42/42 个工具,stdio 与 HTTP 都过)
|
||||
- 工具数量:**42 个**,按 `paper_` / `paragraph_` / `sentence_` / `template_` / `field_` / `reference_` / `reference_tag_` / `image_` 八组前缀
|
||||
- 协议:MCP 2024-11-05 ~ 2025-11-25(官方 Python SDK `mcp>=2.2,<3` 协商)
|
||||
- 传输:`stdio`(本地拉起)与 `streamable-http`(远程连接,支持 Bearer 口令),另兼容旧 `sse`
|
||||
- **已经部署在 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 服务
|
||||
```
|
||||
|
||||
同一个套件 **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_add` | 段尾追加一句(可带引用) | `paper_id`、`content`、`position?` `heading?` `citations?` `line_break_before?` `sort?` |
|
||||
| `sentence_update` | 改正文 / 改所属段 / 改排序 / 改换行 / 整组换引用 | `paper_id`、`sentence_id`、`content?` `position?` `sort?` `line_break_before?` `citations?` |
|
||||
| `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?` `formula_align?` `citations?` |
|
||||
| `sentence_delete` | 删一句(连引用) | `paper_id`、`sentence_id` |
|
||||
| `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. **换行顶掉分隔符,不是叠加。** 新行本身已经把两句分开了,再加一个空格会让下一行空一格。
|
||||
2. **display 公式(`$$…$$` 或 `\[…\]`)自己独占一行,不必标。** 论文页面就是这么排的,
|
||||
`paper_document` 的 `text` 也这么排——两处必须一致,所以模型不要去猜"这里要不要加标记"。
|
||||
行内公式(`$…$`)不算,它本来就在句子里。
|
||||
2. **独占一行的东西不必标。** display 公式(`$$…$$` 或 `\[…\]`)和"整句只有一张图"的插图
|
||||
都自己占一行——论文页面就是这么排的,`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`,但它只作用于**切出来的第一句**——
|
||||
"这一块从新的一行开始"。块里其余几句是接着它的,不是各自另起一行;否则一个换行写了三行的段落
|
||||
就会被切成三行。
|
||||
|
||||
#### 公式怎么摆: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 个)
|
||||
|
||||
模板就是结构:论文的标题是**每次渲染现读模板**得到的,所以改模板会影响所有用它的论文,
|
||||
@@ -417,6 +436,73 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
|
||||
| `reference_tag_update` | 改名/颜色/备注 | `tag_id`、`name?` `color?` `note?` `clear_note?` |
|
||||
| `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.1 AI 写完,整篇一次灌进去(主推)
|
||||
@@ -551,6 +637,36 @@ display 公式不用担心——它本来就独占一行;但分条列举、作
|
||||
删文献时如果它还被引用,会被拒绝并报出「(N 处引用)」——先按上面第 4 步找到那些句子、
|
||||
用 `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. 返回值与错误约定
|
||||
|
||||
- **成功**:`content[0].text` 是一段 JSON 字符串。例如 `paper_list` 返回
|
||||
@@ -600,10 +716,18 @@ REST 和 MCP 同时生效。这让"网页里看到的"和"AI 写进去的"永远
|
||||
|
||||
**换行是"要求"出来的,不是猜出来的。** `line_break_before` 只在被明确写出来时才设:
|
||||
`text` 里换了一行不等于要另起一行(模型把一段话折成三行是常事),所以工具不从这里推断。
|
||||
唯一的例外是 display 公式——页面渲染和 `paper_document` 的 `text` 都让它独占一行,
|
||||
这条规则在 `frontend/src/utils/math.ts` 和 `app/mcp/support.py` 里各写了一遍
|
||||
唯一的例外是 display 公式和"整句只有一张图"的插图——页面渲染和 `paper_document` 的 `text`
|
||||
都让它们独占一行。这两条规则在 `frontend/src/utils/rich.ts` 和 `app/mcp/support.py` 里各写了一遍
|
||||
(一个 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` 第一次调用必定被拒并说明后果,
|
||||
因为一次误删会连带整篇的句子和引用,而这在 MCP 里没有回收站。
|
||||
@@ -636,6 +760,8 @@ REST 和 MCP 同时生效。这让"网页里看到的"和"AI 写进去的"永远
|
||||
| 删文献 | `DELETE /api/references/{id}` | `reference_delete` |
|
||||
| 谁引用了它 | `GET /api/references/{id}/citations` | `reference_citations` |
|
||||
| 文献标签 | `/api/reference-tags` | `reference_tag_*` |
|
||||
| 传图 | `POST /api/images`(multipart)| `image_upload`(base64)|
|
||||
| 看图 | `GET /api/images/{key}` | —(句子里的地址由页面/浏览器直接取)|
|
||||
|
||||
MCP 独有:`paper_outline`(写前看骨架)、`paper_write` / `paper_write_text`(批量写入)、
|
||||
`paragraph_move`、`sentence_search`。
|
||||
@@ -653,4 +779,6 @@ MCP 独有:`paper_outline`(写前看骨架)、`paper_write` / `paper_write
|
||||
| 工具调用超时 | 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`) |
|
||||
| 改了代码但行为没变 | 镜像 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) |
|
||||
|
||||
+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` |
|
||||
|
||||
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
|
||||
CSS length, so no second declaration can be smuggled through it.
|
||||
`{width=400px}`, `{height=300px}`, or both in one block — and each declaration is
|
||||
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`,
|
||||
`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 |
|
||||
|---|---|
|
||||
| 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 |
|
||||
| `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 |
|
||||
@@ -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 |
|
||||
| `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 |
|
||||
| `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
|
||||
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/check_citation_styles.py # the formatter, one entry per type
|
||||
│ │ # (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/smoke_mcp.py # the same loop, spoken over MCP by a real client
|
||||
│ ├── alembic.ini
|
||||
│ ├── requirements.txt
|
||||
│ └── .env.example
|
||||
├── frontend/ # Vue 3 SPA
|
||||
│ ├── scripts/check-image.mjs # the browser check: does a figure draw?
|
||||
│ ├── src/
|
||||
│ │ ├── api/ # axios instance and endpoint modules
|
||||
│ │ ├── components/ # shell, field, template, paper and reference
|
||||
@@ -951,6 +984,31 @@ cd backend
|
||||
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**
|
||||
|
||||
`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
|
||||
```
|
||||
|
||||
**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**
|
||||
|
||||
`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
|
||||
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
|
||||
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`
|
||||
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
|
||||
|
||||
@@ -8,7 +8,8 @@
|
||||
"build": "run-p type-check \"build-only {@}\" --",
|
||||
"preview": "vite preview",
|
||||
"build-only": "vite build",
|
||||
"type-check": "vue-tsc --build"
|
||||
"type-check": "vue-tsc --build",
|
||||
"check:image": "node scripts/check-image.mjs"
|
||||
},
|
||||
"dependencies": {
|
||||
"@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,
|
||||
} 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<{
|
||||
paragraph: PaperParagraph
|
||||
/** 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"
|
||||
:src="item.figure.src"
|
||||
:alt="item.figure.alt"
|
||||
:style="item.figure.width ? { width: item.figure.width } : undefined"
|
||||
:style="sizeStyle(item.figure)"
|
||||
loading="lazy"
|
||||
decoding="async"
|
||||
/>
|
||||
|
||||
@@ -46,7 +46,15 @@ import {
|
||||
type SentenceInput,
|
||||
} from '@/api/papers'
|
||||
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<{
|
||||
/** Visibility, used with `v-model`. */
|
||||
@@ -82,6 +90,15 @@ interface SentenceDraft {
|
||||
/** How a display formula in this sentence is set. */
|
||||
align: FormulaAlign
|
||||
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({
|
||||
@@ -154,6 +171,8 @@ watch(
|
||||
reference_id: citation.reference_id,
|
||||
quote: citation.quote,
|
||||
})),
|
||||
naturalWidth: null,
|
||||
naturalHeight: null,
|
||||
}))
|
||||
} catch (error) {
|
||||
ElMessage.error(errorMessage(error))
|
||||
@@ -177,6 +196,8 @@ function addSentence(): void {
|
||||
lineBreak: false,
|
||||
align: 'center',
|
||||
citations: [],
|
||||
naturalWidth: null,
|
||||
naturalHeight: null,
|
||||
})
|
||||
}
|
||||
|
||||
@@ -189,6 +210,144 @@ function rowImages(row: SentenceDraft): ImageSegment[] {
|
||||
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 ---------------------------------------------------------------
|
||||
|
||||
/** The hidden file picker the 「插入图片」 button drives. */
|
||||
@@ -240,6 +399,8 @@ async function insertImages(files: File[]): Promise<void> {
|
||||
lineBreak: true,
|
||||
align: 'center',
|
||||
citations: [],
|
||||
naturalWidth: null,
|
||||
naturalHeight: null,
|
||||
})
|
||||
} catch (error) {
|
||||
ElMessage.error(errorMessage(error))
|
||||
@@ -500,6 +661,67 @@ async function submit(): Promise<void> {
|
||||
:label="option.label"
|
||||
/>
|
||||
</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" />
|
||||
<el-button
|
||||
link
|
||||
@@ -530,7 +752,15 @@ async function submit(): Promise<void> {
|
||||
right paragraph. -->
|
||||
<div class="row-images">
|
||||
<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>
|
||||
</figure>
|
||||
</div>
|
||||
@@ -683,6 +913,7 @@ async function submit(): Promise<void> {
|
||||
.row-head {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
flex-wrap: wrap;
|
||||
gap: 8px;
|
||||
}
|
||||
|
||||
@@ -699,6 +930,18 @@ async function submit(): Promise<void> {
|
||||
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 {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
|
||||
+109
-4
@@ -41,7 +41,15 @@ import katex from 'katex'
|
||||
export type RichSegment =
|
||||
| { kind: 'text'; value: string }
|
||||
| { 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. */
|
||||
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
|
||||
* 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.
|
||||
*
|
||||
* 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 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. */
|
||||
const MAX_PIXELS = 4000
|
||||
@@ -89,11 +103,34 @@ export function escapeHtml(value: string): string {
|
||||
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. */
|
||||
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
|
||||
|
||||
const value = Number(match[1])
|
||||
@@ -103,6 +140,72 @@ export function parseImageWidth(attributes: string | undefined): string | 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. */
|
||||
export function splitRich(content: string): RichSegment[] {
|
||||
const segments: RichSegment[] = []
|
||||
@@ -116,11 +219,13 @@ export function splitRich(content: string): RichSegment[] {
|
||||
|
||||
const groups = match.groups ?? {}
|
||||
if (groups.src !== undefined) {
|
||||
const size = parseImageSize(groups.attrs)
|
||||
segments.push({
|
||||
kind: 'image',
|
||||
src: groups.src,
|
||||
alt: groups.alt ?? '',
|
||||
width: parseImageWidth(groups.attrs),
|
||||
width: size.width,
|
||||
height: size.height,
|
||||
})
|
||||
} else {
|
||||
segments.push({
|
||||
|
||||
Reference in New Issue
Block a user