Compare commits

...

8 Commits

Author SHA1 Message Date
govin 1531263bd2 frontend: let a figure be sized by its height as well as its width
A writer with a tall panel does not want to shrink it from the left edge: what
they know is "this one is too tall". The format had a width and nothing else, so
the only way to make a figure shorter was to guess a percentage and check the
page — and the previous commit's answer, "type 638px", asked them to do the
arithmetic themselves.

So `{height=300px}` joins `{width=…}`, in the same attribute block, and the
editor grows a second box beside the first. Both are typeable as well as
pre-set, both write through the reader's own parse function, and the hint beside
them says what the picture will measure on the page.

Three rules, and the point of all three is that a figure cannot be stretched:

* **a width is exact, 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.
* **given one, the other follows from the picture's own shape** — `max-height`
  for a height, `width` for a width — so the height is never written by hand.
* **given both, they are a box to fit inside**, not a box to fill. Two numbers
  that need not have the picture's proportions can only mean "no bigger than",
  and the check asserts the drawn rectangle still matches the file's ratio.

Whichever box is left empty keeps the other's setting, so a size can be set in
two steps, and clearing either goes back to the natural size.

`check-image.mjs`: 26 checks to 36. Two of the new ones found real bugs while
being written. The first: with both a width and a height in one `{…}` block,
neither side parsed — the patterns were anchored to the whole block, so a figure
with two numbers silently printed at its natural size. The attribute block is now
split into declarations first. The second was mine: returning "contain" for a
height-only figure left a 1276×2000 box around a small picture, which the caption
then sat under. A height is a cap, and a cap needs no contain.

The MCP tool takes the same two arguments, so a model can write either number,
and a percentage height is refused with the reason it cannot work: a sentence is
flowed text, so there is nothing for it to be a percentage of and the browser
ignores it. v8 is deployed and DSH has verified both numbers round-tripping.
2026-09-24 13:18:52 +08:00
govin b19f28492e frontend: check that a sized figure keeps its own shape
The size is a width and nothing else, so the height comes from the picture's
aspect ratio and a figure cannot be deformed. That is worth asserting rather
than assuming, in both halves: the shape the browser actually drew, and that no
height was written into the style at all.

Measured on the paper this was built for, which now has all sixteen of its
figures at 50%: 638px wide each, aspect ratio within 0.2% of the file's own — the
rounding of the measurement, not the layout.
2026-09-24 12:46:10 +08:00
govin 48f0c12fd2 frontend: let the writer set a figure's size in the editor
Figures come out of a plotting tool at whatever size they were made. On the
paper this was written for, the sixteen of them are 1441, 1857, 2409 and 4169
pixels wide — every one wider than the 1276px column — so with no size they all
printed at the full width, and the near-square ones (1857×1986, 1974×2068) took
1365px of height, a page each. Measured in the browser, all sixteen came out at
exactly 1276px: not one of them was the size its author wanted.

`{width=…}` has been in the syntax all along, so this is the control that was
missing, not the feature. A row that is a figure now carries 宽度 in its header:
25/50/70/100%, or any value typed in — the size a panel wants is what it
measures, not a round number — with 原尺寸 as the empty value. Beside it, what
the picture will measure on the page (`原图 1857×1986 · 显示 893×955`), worked
out against the column actually rendered behind the dialog, which is the number
the writer is deciding with.

Two rules keep it honest. The value goes through `parseImageWidth` — the same
function that parses the attribute when the paper is printed — so what the
control shows is what will be printed, and a value it cannot read is refused
with the forms that work instead of stored as a size that quietly does nothing.
And the attribute is written into the sentence content by `withImageWidth`,
which edits only the first picture: the control is offered for a figure, and a
sentence with words around its picture is not one. Reading the size back out of
the content rather than keeping a copy of it in the draft means there is one
place it can be wrong instead of two.

`check-image.mjs` grows from 15 checks to 24, driving the real control: that
only figure rows offer one, that it shows what each is set to, that typing 30%
converts to 383×239 immediately, that what was typed is what gets stored, that
the paper then prints it at 30% of the column, that clearing it goes back to the
natural 480×300, and that "宽一点" is refused while the sentence keeps its size.

The MCP side of the same rule was wrong and is fixed with it: `image_upload(width=
"60")` wrote `{width=60px}`, and the reader takes a bare number as a share of the
column — `parseImageWidth` only reads pixels when the value says `px`. A model
asking for 60% got a 60-pixel figure. v7 is deployed with the corrected reading,
and smoke_mcp.py checks it.
2026-09-24 11:25:18 +08:00
govin 9e6a1f8c3e docs: put the figure and the derived sentence fields in the MCP table 2026-09-24 10:55:06 +08:00
govin ebaf9e558b backend: let a model put a figure in the paper, and set a formula's alignment
Two things the editor gained and MCP could not do, both because the tool layer
had been told about the domain's columns by hand.

**A figure.** Bytes go to MinIO and the sentence keeps a Markdown address, so a
picture is ordinary text — which means the writing tools already carry it, and
the only half a model cannot do is the upload: it has bytes and no way to send
multipart. `image_upload` takes base64 and answers with the URL, the Markdown
and the *sentence object* the editor produces when a picture is dropped in, so a
figure is written by putting that object into `sentences` unchanged. It does not
fetch a URL the caller names: a service inside the cluster that will GET any
address it is handed is an SSRF primitive aimed at everything beside it.

The width argument is the reader's rule or it is refused. `{width=70%}` is
parsed by `frontend/src/utils/rich.ts`, and a value it cannot read is not an
error there — the picture just prints at its natural size. A size that silently
does not apply is worse than a refusal, so the syntax and the range (pixels
1–4000, per cent 1–100) are mirrored in `app/mcp/tools/images.py`, with the
usual comment naming the other side.

`paragraph_text` also had to learn what a figure is: a sentence holding nothing
but an image is a 插图 — the view prints it on its own line with the brackets'
text as its caption — and the text a tool hands back broke lines around a
display formula but not around a picture. Same rule as `figureOf`, same pair of
implementations, same warning about changing both.

**A formula's alignment.** `paper_sentence.formula_align` reached the editor and
the REST API and stopped there: `SentenceSpec` had no such field, so a model that
sent one got a successful call and a centred formula. The column is now declared,
carried through every write path and reported by every read path.

That is the second column lost the same way, so the fix is structural rather
than another two edits. `SENTENCE_FIELDS` is read from
`app.schemas.paper.SentenceInput` instead of written out, the payload is built
by one `sentence_payload()`, and the three append paths spread
`SentenceCreate(**item.model_dump())` rather than copying fields. One edit
remains — declaring the field in `specs.py` — and smoke_mcp.py's first step
compares the two field sets, so forgetting it now fails the suite instead of
losing the field. `sort` is declared too, which it never was: a model that sent
one had it dropped in silence.

smoke_mcp.py: 99 checks to 119. The figure step uploads a real 1x1 GIF (the same
bytes twice, and the key is the same object), writes the returned sentence as it
came back, checks the paragraph prints it alone on its line and that an image
inside a sentence does not break the line, and takes the four refusals — not a
picture, an unparseable size, an out-of-range one, not base64. The alignment step
writes a right-aligned formula, moves the sentence to left on its own, and takes
the paragraph to another position to prove the setting travels with it.

Deployed as v6, and the pod now carries MINIO_ENDPOINT (the in-cluster Service)
plus the two credential keys from the Secret; without them the image tool answers
with the missing variable names and every writing tool still works.
2026-09-24 10:54:27 +08:00
govin eb0f12b8cf backend: check the image rules without a bucket, and accept a scoped key
A least-privilege key — PutObject / GetObject and no ListBucket — gets a 403
from HeadBucket, and reading that as "the bucket is missing" turned a working
key into a 503. The bucket may well be there and simply not be the key's
business, so a refusal to look at it is no longer a failure; the PUT that
follows is the honest test.

`scripts/check_storage.py` covers what a smoke test cannot, because these are
the rules whose failure is silent: the format read from the magic bytes rather
than the client's word, the key pattern the read route serves and nothing
outside it, a caption that cannot break out of the Markdown it is written into,
what is actually asked of MinIO on a write, and the refusals — unconfigured
storage, a key we never wrote, an object that is gone. boto3's client is a stub,
so it needs no credentials, no bucket and no network.

`frontend/scripts/check-image.mjs` is the third layer: bytes can be stored and
returned perfectly while the `<img>` draws nothing. It builds its own PNG
fixture, drives the page and measures what the browser did — the picture
decoded, the figure is centred on the column, `{width=50%}` is half the column,
the 图注 prints under the picture, an image inside a sentence stays inline, and
「插入图片」 ends with the picture in the paper. Run with `pnpm check:image`; it
needs Playwright, which stays out of the app's dependencies.
2026-09-23 19:24:25 +08:00
govin 0e0fde8f02 frontend: insert a figure into a sentence, and print it as one
The editor gains 「插入图片」: it uploads the file and appends the sentence that
shows it, and a file dropped anywhere in the dialog does the same. Each row then
prints the picture it holds, not only the path to it — checking that the right
curve landed in the right paragraph is the whole reason to look at the editor.

Reading it back, one rule decides the layout: a sentence holding nothing but an
image is a figure — its own line, centred, the text in the brackets printed
underneath as its 图注 — while an image inside a run of text stays on the line,
height capped so a pasted screenshot cannot stretch a line of prose. The size is
optional, in pandoc's `{width=70%}` form, and is validated to digits plus one
unit before it becomes a CSS length.

`utils/math.ts` becomes `utils/rich.ts`, because it now reads two families of
markup rather than one: the formulas it always parsed, and the images a sentence
keeps as Markdown. A figure is deliberately not built inside the `v-html` string
the rest of a sentence is: `PaperParagraph` prints it as a real `<img>`, so it
can carry the writer's size and open at full resolution when clicked — an
experiment figure on a page is often too small to check a curve against.
2026-09-23 13:31:31 +08:00
govin 6f37120dc4 backend: keep a figure in the object store, and serve it back by key
A paper needs its experiment figures, and a figure is not text: the bytes go to
MinIO and the sentence keeps a Markdown address. That is what keeps a sentence
one editable string — a picture moves between paragraphs by being cut and
pasted, and survives a template switch with the sentence it belongs to.

Three decisions carry the safety, and each is a way to serve something other
than what was uploaded:

* the key is the digest of the bytes, so uploading the same screenshot twice is
  one object and the address can never come to mean a different picture — which
  is what makes the year-long `immutable` cache header safe;
* the format is sniffed from the magic bytes, not read from the client's
  `Content-Type` or filename, and SVG is refused because an uploaded SVG served
  from this origin is stored XSS;
* serving is restricted to the key space this application writes, so
  `GET /api/images/{key}` cannot become a browser for the rest of the bucket.

Images are served through the API rather than from a public bucket URL so a
sentence never embeds a host name — the LAN in development and the public
address later would otherwise disagree — and the bucket can stay private. The
object is streamed rather than read into memory, and the connection is released
when the reader stops.

Storage unconfigured is a 503 that names the missing variables, not a crash:
the writing path does not depend on the bucket.

`scripts/smoke_images.py` walks the whole thing: each accepted format, the
refusals (text, SVG, a mislabelled file, an empty file, a key we did not
write), and a sentence that carries a figure through the paper endpoints.
2026-09-23 13:31:27 +08:00
32 changed files with 3731 additions and 217 deletions
+15
View File
@@ -17,3 +17,18 @@ DB_NAME=paper_doc
# The password must be percent-encoded (a raw '@' would be parsed as the
# user/host separator). Prefer the DB_* parts above and let the app encode it.
# DATABASE_URL=mysql+pymysql://Govin:change-me%40123@192.168.1.88:32738/paper_doc
# --- Object storage (MinIO) — where the images a paper embeds are kept ---
# Leave these empty and the paper still writes and reads; only the image
# endpoints answer 503, saying exactly which variables are missing.
# The bucket is created on the first upload if it does not exist yet, so a
# dedicated access key with read/write on that one bucket is enough.
# Inside the cluster, use the Service: http://minio.minio.svc.cluster.local:9000
MINIO_ENDPOINT=http://192.168.1.88:30090
MINIO_ACCESS_KEY=change-me
MINIO_SECRET_KEY=change-me
MINIO_BUCKET=paper-images
MINIO_REGION=us-east-1
# Largest image accepted, in bytes (default 20 MiB).
# MAX_IMAGE_BYTES=20971520
+2
View File
@@ -4,6 +4,7 @@ from fastapi import APIRouter
from app.api.routes import (
health,
images,
papers,
reference_tags,
references,
@@ -13,6 +14,7 @@ from app.api.routes import (
api_router = APIRouter()
api_router.include_router(health.router)
api_router.include_router(images.router)
api_router.include_router(papers.router)
api_router.include_router(reference_tags.router)
api_router.include_router(references.router)
+139
View File
@@ -0,0 +1,139 @@
"""Image endpoints: put a figure in the bucket, and hand it back to the page.
The paper's sentences store pictures as Markdown — ``![图注](/api/images/…)`` —
which is what keeps a sentence one editable string and what lets a model insert
a figure through the same API it already writes text with. This module is the
other half of that: the place the bytes go, and the place they come back from.
Uploading is one request and answers with the Markdown as well as the URL, so a
client never has to assemble the syntax itself. Serving is by *key*, restricted
to the keys this application writes (see :mod:`app.core.storage`), and streams
from the bucket rather than loading the object into memory — an experiment
figure is a megabyte or two and several of them appear on one screen.
"""
from pathlib import Path
from fastapi import APIRouter, File, HTTPException, UploadFile, status
from fastapi.responses import StreamingResponse
from app.core.config import get_settings
from app.core.storage import (
ImageNotFound,
UnsupportedImage,
content_type_for,
get_store,
image_url,
markdown_for,
)
from app.schemas.image import ImageRead
router = APIRouter(prefix="/images", tags=["images"])
settings = get_settings()
_READ_CHUNK = 1024 * 1024
def _read_capped(handle, limit: int) -> bytes:
"""Read one upload whole, refusing it the moment it passes ``limit``.
Read in pieces rather than with a single ``read()`` so an oversized file is
rejected after the first megabyte instead of after all of it.
"""
pieces: list[bytes] = []
total = 0
while True:
piece = handle.read(_READ_CHUNK)
if not piece:
break
total += len(piece)
if total > limit:
raise HTTPException(
status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
detail=(
f"图片太大了,超过 {limit // (1024 * 1024)} MB 上限。"
"先压缩或裁剪一下再上传。"
),
)
pieces.append(piece)
return b"".join(pieces)
@router.post(
"",
response_model=ImageRead,
status_code=status.HTTP_201_CREATED,
summary="Upload an image",
)
def upload_image(
file: UploadFile = File(..., description="图片文件:PNG / JPEG / GIF / WebP"),
) -> ImageRead:
"""Store one image and return the Markdown that embeds it.
The declared content type is not trusted and neither is the filename: the
format is decided from the file's own magic bytes, and the stored key comes
from the content's digest. Uploading the same picture again is therefore not
a duplicate — it is the same object, and a sentence that already points at
it keeps working.
"""
data = _read_capped(file.file, settings.max_image_bytes)
if not data:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="上传的文件是空的。",
)
try:
key, content_type, digest = get_store().save(data)
except UnsupportedImage as error:
raise HTTPException(
status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
detail=str(error),
) from error
# The filename's stem becomes the caption's starting point: a screenshot is
# usually already named after what it shows, and the writer edits the
# brackets afterwards.
caption = Path(file.filename or "").stem
return ImageRead(
key=key,
url=image_url(key),
markdown=markdown_for(key, caption),
content_type=content_type,
size=len(data),
sha256=digest,
)
@router.get("/{key:path}", summary="Serve an image")
def read_image(key: str) -> StreamingResponse:
"""Stream one image out of the bucket.
Served from this origin, so the URL in a sentence does not name a host that
differs between the LAN and the public address, and the bucket never has to
be made world-readable for the paper to show its figures.
"""
try:
chunks, content_type, length = get_store().stream(key)
except ImageNotFound as error:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="没有这张图片:地址不对,或者它已经不在存储里了。",
) from error
return StreamingResponse(
chunks,
media_type=content_type or content_type_for(key) or "application/octet-stream",
headers={
# The key is the digest of the bytes, so this URL can never come to
# mean a different picture — a year is safe, and it saves the paper
# from re-fetching every figure on every scroll.
"Cache-Control": "public, max-age=31536000, immutable",
"Content-Length": str(length),
# The type is from our own whitelist, never from the upload; this
# stops a browser from second-guessing it.
"X-Content-Type-Options": "nosniff",
},
)
+18
View File
@@ -53,6 +53,24 @@ class Settings(BaseSettings):
db_pool_pre_ping: bool = True
db_pool_recycle: int = 3600
# --- Object storage (MinIO) ------------------------------------------
#
# Where the images a paper embeds are kept. Empty by default rather than
# pointed at a plausible host: a wrong-but-set address fails as a timeout
# deep inside boto3, while an empty one fails immediately and says which
# variables are missing. The bucket is created on first upload if it is not
# there, so a fresh deployment needs the credentials and nothing else.
minio_endpoint: str = ""
minio_access_key: str = ""
minio_secret_key: str = ""
minio_bucket: str = "paper-images"
minio_region: str = "us-east-1"
#: Largest image accepted, in bytes. An experiment figure is a few hundred
#: kilobytes; the ceiling is here to stop a mistake (a raw TIFF, a video)
#: from filling the bucket, not to be hit in normal use.
max_image_bytes: int = 20 * 1024 * 1024
@property
def sqlalchemy_url(self) -> Union[URL, str]:
"""The SQLAlchemy connection URL.
+307
View File
@@ -0,0 +1,307 @@
"""Object storage for the images a paper embeds (MinIO, spoken over S3).
An image is not text, so it does not live in the database: the sentence keeps a
short URL and the bytes live in the bucket. That split is what keeps a sentence
editable as one string — the writer can move a figure between paragraphs by
cutting and pasting text, and the object itself never has to move.
Three decisions are worth stating, because each of them is a way to serve
something other than what was uploaded:
* **The key is content-addressed.** ``2026/09/9f8c1a4b7e2d0c33.png`` is derived
from the bytes, so uploading the same screenshot twice stores one object, and
a URL cannot quietly come to mean a *different* picture than the one it was
written for. That is also what makes the year-long ``immutable`` cache header
safe to hand out.
* **The format is sniffed, not trusted.** The upload's ``Content-Type`` and its
filename are the client's claims; the magic bytes are the fact. Only formats a
browser draws in an ``<img>`` are accepted, and SVG is deliberately not among
them — an uploaded SVG served from this origin is stored XSS.
* **Images are served from our own path.** ``/api/images/{key}`` streams the
object, so a paper never embeds a host name that differs between the LAN and
the public address, and the bucket can stay private.
"""
from __future__ import annotations
import hashlib
import re
from contextlib import contextmanager
from datetime import datetime, timezone
from functools import lru_cache
from typing import Iterator
import boto3
from botocore.client import Config
from botocore.exceptions import BotoCoreError, ClientError
from app.core.config import Settings, get_settings
class StorageUnavailable(RuntimeError):
"""The object store is not configured, or could not be reached."""
class UnsupportedImage(ValueError):
"""The uploaded bytes are not a picture we are willing to store."""
class ImageNotFound(KeyError):
"""No image is stored under that key."""
#: Sniffed format -> how the object is stored. Every format listed is one a
#: browser renders; the extension is what the key ends in, and it is also how
#: the content type is decided again when the object is served.
IMAGE_FORMATS: dict[str, tuple[str, str]] = {
"png": ("image/png", ".png"),
"jpeg": ("image/jpeg", ".jpg"),
"gif": ("image/gif", ".gif"),
"webp": ("image/webp", ".webp"),
}
#: The shape of a key this application writes: ``YYYY/MM/<16 hex><ext>``.
#:
#: Serving is restricted to it, so the read endpoint cannot be turned into a
#: browser for the rest of the bucket — a request for anything this module did
#: not store is a 404, whatever else happens to be in there.
KEY_PATTERN = re.compile(r"^\d{4}/\d{2}/[0-9a-f]{16}\.(?:png|jpg|gif|webp)$")
#: Content type by extension, for serving. A whitelist rather than a parse of
#: whatever the object's metadata says.
CONTENT_TYPE_BY_EXTENSION: dict[str, str] = {
".png": "image/png",
".jpg": "image/jpeg",
".gif": "image/gif",
".webp": "image/webp",
}
#: How much of a key's digest goes into it. 64 bits of SHA-256: a collision
#: would need more distinct images than a paper will ever hold, and 16 hex
#: characters keep the URL short enough to read in a sentence.
DIGEST_CHARS = 16
_CHUNK = 64 * 1024
def sniff(data: bytes) -> str:
"""Name the format of ``data``, or refuse it.
Returns a key of :data:`IMAGE_FORMATS`. The check is on the leading bytes
because that is the only part of the claim the uploader cannot choose.
"""
if data.startswith(b"\x89PNG\r\n\x1a\n"):
return "png"
if data.startswith(b"\xff\xd8\xff"):
return "jpeg"
if data.startswith((b"GIF87a", b"GIF89a")):
return "gif"
if data[:4] == b"RIFF" and data[8:12] == b"WEBP":
return "webp"
raise UnsupportedImage(
"只接受 PNG / JPEG / GIF / WebP 图片,这个文件的格式无法识别。"
"(SVG 不支持:它会在页面上执行脚本。)"
)
def is_key(key: str) -> bool:
"""Whether ``key`` has the shape this application stores."""
return bool(KEY_PATTERN.match(key))
def content_type_for(key: str) -> str | None:
"""The content type to serve ``key`` as, or ``None`` if we would not serve it."""
if not is_key(key):
return None
return CONTENT_TYPE_BY_EXTENSION.get(f".{key.rsplit('.', 1)[-1].lower()}")
def image_url(key: str, settings: Settings | None = None) -> str:
"""The URL a sentence stores for ``key``.
Relative on purpose: the paper is read from the LAN in development and from
the public name later, and a sentence that hard-coded either would break on
the other. The prefix comes from the API settings, so it follows the mount
point instead of being spelled out twice.
"""
settings = settings or get_settings()
return f"{settings.api_prefix}/images/{key}"
def markdown_for(key: str, caption: str = "", settings: Settings | None = None) -> str:
"""The Markdown a writer (or a model) pastes into a sentence.
Generating it here rather than in each client is the same argument as
numbering citations on the server: the syntax is one rule, and two
implementations of a rule eventually disagree.
"""
safe = caption.replace("[", "(").replace("]", ")").replace("(", "(").replace(")", ")")
return f"![{safe.strip()}]({image_url(key, settings)})"
class ImageStore:
"""The bucket, seen through the four operations the API needs."""
def __init__(self, settings: Settings) -> None:
self._settings = settings
self._client = None
@property
def bucket(self) -> str:
return self._settings.minio_bucket
@property
def endpoint(self) -> str:
return self._settings.minio_endpoint or "(未配置)"
# --- connection ------------------------------------------------------
def _require(self) -> None:
"""Refuse early, and in the API's words, when storage is not set up.
A missing configuration is an operator's mistake, not the caller's, so
it must not surface as a stack trace from deep inside boto3.
"""
settings = self._settings
if not (
settings.minio_endpoint
and settings.minio_access_key
and settings.minio_secret_key
):
raise StorageUnavailable(
"图片存储还没有配置好(缺少 MINIO_ENDPOINT / MINIO_ACCESS_KEY / "
"MINIO_SECRET_KEY),暂时不能上传图片。"
)
def client(self):
"""The boto3 client, built on first use so importing costs nothing."""
self._require()
if self._client is None:
self._client = boto3.client(
"s3",
endpoint_url=self._settings.minio_endpoint,
aws_access_key_id=self._settings.minio_access_key,
aws_secret_access_key=self._settings.minio_secret_key,
region_name=self._settings.minio_region,
config=Config(signature_version="s3v4", retries={"max_attempts": 3}),
)
return self._client
def _unavailable(self, error: Exception) -> StorageUnavailable:
"""Restate a boto3 failure as something a person can act on."""
if isinstance(error, ClientError):
code = error.response.get("Error", {}).get("Code", "unknown")
return StorageUnavailable(
f"对象存储返回错误 {code}({self.endpoint},桶 {self.bucket}):{error}"
)
return StorageUnavailable(f"连不上对象存储 {self.endpoint}:{error}")
@contextmanager
def _translated(self):
"""Let boto3's exception vocabulary stop at this module's boundary."""
try:
yield
except (BotoCoreError, ClientError) as error:
raise self._unavailable(error) from error
# --- operations ------------------------------------------------------
def ensure_bucket(self) -> None:
"""Create the bucket if it is not there yet.
The bucket is normally made once by whoever deploys, but a missing one
is an easy mistake to make and a tedious one to diagnose. Making it on
first use costs one HEAD on an upload and turns that mistake into a
working upload.
"""
client = self.client()
try:
client.head_bucket(Bucket=self.bucket)
return
except ClientError as error:
code = error.response.get("Error", {}).get("Code", "")
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:
client.create_bucket(Bucket=self.bucket)
except ClientError as error:
# Two uploads racing on a fresh deployment: one of them creates the
# bucket, the other is told it exists. Neither is a failure.
code = error.response.get("Error", {}).get("Code", "")
if code not in {"BucketAlreadyOwnedByYou", "BucketAlreadyExists"}:
raise self._unavailable(error) from error
def save(self, data: bytes) -> tuple[str, str, str]:
"""Store ``data`` and return ``(key, content_type, sha256)``.
Storing is idempotent: the key comes from the bytes, so the same picture
uploaded from two paragraphs — or twice by mistake — is one object.
"""
self._require()
digest = hashlib.sha256(data).hexdigest()
content_type, extension = IMAGE_FORMATS[sniff(data)]
stamp = datetime.now(timezone.utc)
key = f"{stamp:%Y/%m}/{digest[:DIGEST_CHARS]}{extension}"
with self._translated():
self.ensure_bucket()
self.client().put_object(
Bucket=self.bucket,
Key=key,
Body=data,
ContentType=content_type,
# Safe because the key is the content's digest: these bytes can
# never be replaced by different bytes under the same URL.
CacheControl="public, max-age=31536000, immutable",
)
return key, content_type, digest
def stream(self, key: str) -> tuple[Iterator[bytes], str, int]:
"""Open ``key`` for serving, as ``(chunks, content_type, length)``."""
self._require()
content_type = content_type_for(key)
if content_type is None:
raise ImageNotFound(key)
try:
response = self.client().get_object(Bucket=self.bucket, Key=key)
except ClientError as error:
code = error.response.get("Error", {}).get("Code", "")
if code in {"NoSuchKey", "NoSuchBucket", "404", "NotFound"}:
raise ImageNotFound(key) from error
raise self._unavailable(error) from error
except BotoCoreError as error:
raise self._unavailable(error) from error
body = response["Body"]
return _closing_chunks(body), content_type, int(response.get("ContentLength") or 0)
def _closing_chunks(body, chunk: int = _CHUNK) -> Iterator[bytes]:
"""Hand out the object's bytes and release the connection when done.
boto3's body is a stream on a socket from the pool; a response that is
abandoned without closing it leaks that connection until the pool is empty.
"""
try:
for piece in body.iter_chunks(chunk):
yield piece
finally:
body.close()
@lru_cache
def get_store() -> ImageStore:
"""Return the process-wide store."""
return ImageStore(get_settings())
+15
View File
@@ -11,6 +11,7 @@ from fastapi.responses import JSONResponse
from app.api.router import api_router
from app.core.config import get_settings
from app.core.storage import StorageUnavailable
from app.crud.reference import UnknownReference
settings = get_settings()
@@ -43,3 +44,17 @@ async def unknown_reference_handler(
for a rejected request, so a client needs no special case.
"""
return JSONResponse(status_code=400, content={"detail": str(error)})
@app.exception_handler(StorageUnavailable)
async def storage_unavailable_handler(
request: Request, error: StorageUnavailable
) -> JSONResponse:
"""Answer an upload or a figure load when the object store cannot be used.
``503`` rather than ``500``: nothing about the request was wrong — the
service that holds the images is missing or unreachable, and the message
says which one so the fix is one configuration away. The writing itself is
unaffected, which is why this is not allowed to look like a crash.
"""
return JSONResponse(status_code=503, content={"detail": str(error)})
+36 -1
View File
@@ -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
View File
@@ -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",
+18 -6
View File
@@ -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:
+255
View File
@@ -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 ``![图注](/api/images/…)``.
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"]
+4 -4
View File
@@ -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:
+12 -17
View File
@@ -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:
+14 -1
View File
@@ -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(
+13 -2
View File
@@ -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),
),
)
+2
View File
@@ -6,6 +6,7 @@ from app.schemas.common import (
PageResult,
normalize_hex_color,
)
from app.schemas.image import ImageRead
from app.schemas.paper import (
CitationInput,
CitationRead,
@@ -57,6 +58,7 @@ from app.schemas.template_title import (
__all__ = [
"BatchDeleteRequest",
"ImageRead",
"ReferenceAuthorInput",
"ReferenceAuthorRead",
"ReferenceCitationRead",
+20
View File
@@ -0,0 +1,20 @@
"""The shape an upload answers with."""
from pydantic import BaseModel, Field
class ImageRead(BaseModel):
"""One stored image, as the client needs to know about it.
The caller gets the URL *and* the Markdown that embeds it, because those are
the two things it needs and only one of them is pleasant to assemble by
hand. They are produced together here so a client cannot invent a slightly
different syntax than the one the reader parses.
"""
key: str = Field(description="对象在桶里的键,也是这个 URL 的唯一来源")
url: str = Field(description="句子里的图片地址(同源相对路径,如 /api/images/…)")
markdown: str = Field(description="可直接粘进句子的 Markdown:![图注](地址)")
content_type: str = Field(description="识别出来的图片类型,如 image/png")
size: int = Field(description="字节数")
sha256: str = Field(description="内容的 SHA-256,键就是它的一部分")
+5
View File
@@ -5,6 +5,11 @@ alembic>=1.14
pymysql>=1.1
cryptography>=43.0
pydantic-settings>=2.6
# Object storage for the images a paper embeds (app/core/storage.py). boto3 is
# the S3 client; python-multipart is what FastAPI needs to parse an upload at
# all — without it a multipart route fails when the app is imported.
boto3>=1.35
python-multipart>=0.0.20
# MCP server (app/mcp/) — the same domain layer, exposed as MCP tools for
# Claude Code, Codex and the DeepSeek Harness. Only the MCP entry points need
# it; the REST API does not import it.
+301
View File
@@ -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"![试验装置](/api/images/{ours})",
)
equal(
"a caption cannot close the brackets early",
markdown_for(ours, "a]b(c)", settings),
f"![a)b(c)](/api/images/{ours})",
)
equal("an empty caption is allowed", markdown_for(ours, "", settings), f"![](/api/images/{ours})")
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())
+327
View File
@@ -0,0 +1,327 @@
"""End-to-end smoke test for images (插图), against a running API.
Run it while the backend is up, with MinIO reachable::
.venv/bin/python scripts/smoke_images.py
It uploads pictures of each accepted format, fetches them back byte for byte,
checks the refusals (a text file, an SVG, an empty file, a key we did not
write), and then writes a sentence that embeds a figure to prove the paper's
own endpoints carry image Markdown through untouched. Exits non-zero on the
first failed expectation, so it is usable as a gate.
Nothing needs cleaning up afterwards, and that is the point of the design being
tested: a key is the digest of the picture, so a second run stores the same
objects rather than more copies of them.
"""
from __future__ import annotations
import base64
import hashlib
import json
import re
import struct
import sys
import urllib.error
import urllib.parse
import urllib.request
import zlib
from typing import Any
BASE = "http://127.0.0.1:8000/api"
#: The origin the API is mounted on. An image URL comes back as `/api/images/…`
#: — the path a *browser* uses — so fetching one has to join it to the origin
#: rather than to the API prefix, or it asks for `/api/api/images/…`.
ROOT = "http://127.0.0.1:8000"
KEY_PATTERN = re.compile(r"^\d{4}/\d{2}/[0-9a-f]{16}\.(?:png|jpg|gif|webp)$")
_checks = 0
def call(method: str, path: str, body: Any = None, expect: int = 200) -> Any:
"""Perform one JSON API call and assert its status code."""
data = json.dumps(body).encode() if body is not None else None
url = BASE + urllib.parse.quote(path, safe="/?&=%")
request = urllib.request.Request(
url,
data=data,
method=method,
headers={"Content-Type": "application/json"},
)
status, payload, _ = _send(request)
if status != expect:
raise AssertionError(f"{method} {path} -> {status}, expected {expect}: {payload[:300]}")
return json.loads(payload) if payload else None
def _send(request: urllib.request.Request):
"""Send a request and return ``(status, text body, headers)`` whatever happens.
The headers are handed over as the live mapping rather than as a ``dict``:
uvicorn writes them lower-cased, and a plain dict lookup for
``Content-Type`` would miss them.
"""
try:
with urllib.request.urlopen(request, timeout=60) as response:
return response.status, response.read().decode("utf-8", "replace"), response.headers
except urllib.error.HTTPError as error:
return error.code, error.read().decode("utf-8", "replace"), error.headers
def upload(
filename: str,
data: bytes,
content_type: str = "application/octet-stream",
expect: int = 201,
) -> Any:
"""POST one file as ``multipart/form-data``, which is what a browser sends.
Built by hand rather than with `requests`, so this script needs nothing the
project does not already install.
"""
boundary = "----paperdocsmokeboundary"
head = (
f"--{boundary}\r\n"
f'Content-Disposition: form-data; name="file"; filename="{filename}"\r\n'
f"Content-Type: {content_type}\r\n\r\n"
).encode()
body = head + data + f"\r\n--{boundary}--\r\n".encode()
request = urllib.request.Request(
BASE + "/images",
data=body,
method="POST",
headers={"Content-Type": f"multipart/form-data; boundary={boundary}"},
)
status, payload, _ = _send(request)
if status != expect:
raise AssertionError(f"upload {filename} -> {status}, expected {expect}: {payload[:300]}")
return json.loads(payload) if payload else None
def fetch(path: str, expect: int = 200):
"""GET an application path (``/api/images/…``) and return its bytes and headers."""
request = urllib.request.Request(ROOT + path, method="GET")
try:
with urllib.request.urlopen(request, timeout=30) as response:
status, headers, body = response.status, response.headers, response.read()
except urllib.error.HTTPError as error:
status, headers, body = error.code, error.headers, error.read()
if status != expect:
raise AssertionError(f"GET {path} -> {status}, expected {expect}")
return body, headers
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}")
# --- the files under test ----------------------------------------------------
def make_png(width: int = 240, height: int = 160) -> bytes:
"""A real PNG: a gradient, so two of them differ and compression is honest."""
def chunk(tag: bytes, payload: bytes) -> bytes:
body = tag + payload
return struct.pack(">I", len(payload)) + body + struct.pack(">I", zlib.crc32(body) & 0xFFFFFFFF)
rows = bytearray()
for y in range(height):
rows.append(0) # filter: none
for x in range(width):
rows += bytes(((x * 255) // max(width - 1, 1), (y * 255) // max(height - 1, 1), 128))
header = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
return (
b"\x89PNG\r\n\x1a\n"
+ chunk(b"IHDR", header)
+ chunk(b"IDAT", zlib.compress(bytes(rows), 9))
+ chunk(b"IEND", b"")
)
#: A 1x1 GIF and a 1x1 JPEG: the smallest real files of each format, which is
#: all that is needed to prove the format is recognised and stored as itself.
GIF_1PX = base64.b64decode("R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7")
JPEG_1PX = base64.b64decode(
"/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a"
"HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAABAAEBAREA/8QAFAABAAAAAAAA"
"AAAAAAAAAAAACf/EABQQAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQEAAD8AKp//2Q=="
)
SVG = b'<svg xmlns="http://www.w3.org/2000/svg"><script>alert(1)</script></svg>'
def main() -> int:
created_papers: list[int] = []
try:
png = make_png()
check("the fixture is a PNG", png.startswith(b"\x89PNG"))
check("the JPEG fixture starts like a JPEG", JPEG_1PX.startswith(b"\xff\xd8\xff"))
check("the GIF fixture starts like a GIF", GIF_1PX.startswith(b"GIF89a"))
print("1. upload a PNG")
image = upload("试验装置.png", png, "image/png")
key = image["key"]
check("key has the shape we serve", bool(KEY_PATTERN.match(key)), key)
check("key ends in .png", key.endswith(".png"), key)
check("url is same-origin", image["url"] == f"/api/images/{key}", image["url"])
check(
"markdown embeds the url, caption from the filename",
image["markdown"] == f"![试验装置](/api/images/{key})",
image["markdown"],
)
check("content type sniffed", image["content_type"] == "image/png", image["content_type"])
check("size reported", image["size"] == len(png), f"{image['size']} != {len(png)}")
check(
"sha256 is the content's",
image["sha256"] == hashlib.sha256(png).hexdigest(),
image["sha256"],
)
check("the digest is in the key", image["sha256"][:16] in key, key)
print("2. fetch it back")
body, headers = fetch(image["url"])
check("bytes identical", body == png, f"{len(body)} != {len(png)}")
check(
"served as image/png",
headers.get("Content-Type") == "image/png",
headers.get("Content-Type", ""),
)
check(
"immutable cache header",
"immutable" in headers.get("Cache-Control", ""),
headers.get("Cache-Control", ""),
)
check(
"nosniff",
headers.get("X-Content-Type-Options") == "nosniff",
headers.get("X-Content-Type-Options", ""),
)
check(
"content-length matches",
headers.get("Content-Length") == str(len(png)),
headers.get("Content-Length", ""),
)
print("3. the same bytes are the same object")
again = upload("another-name.png", png, "image/png")
check("same key", again["key"] == key, f"{again['key']} != {key}")
check(
"the caption follows the name given this time",
again["markdown"] == f"![another-name](/api/images/{key})",
again["markdown"],
)
print("4. the other formats")
gif = upload("图.gif", GIF_1PX, "image/gif")
check("gif key", gif["key"].endswith(".gif"), gif["key"])
check("gif type", gif["content_type"] == "image/gif", gif["content_type"])
check("gif bytes", fetch(gif["url"])[0] == GIF_1PX)
jpeg = upload("figure.jpeg", JPEG_1PX, "image/jpeg")
check("jpeg key", jpeg["key"].endswith(".jpg"), jpeg["key"])
check("jpeg type", jpeg["content_type"] == "image/jpeg", jpeg["content_type"])
check("jpeg bytes", fetch(jpeg["url"])[0] == JPEG_1PX)
print("5. what it refuses")
refused = upload("notes.txt", b"this is not a picture\n", "text/plain", expect=415)
check("a text file is 415", "格式" in refused["detail"], refused["detail"])
svg = upload("attack.svg", SVG, "image/svg+xml", expect=415)
check("an SVG is 415", "SVG" in svg["detail"], svg["detail"])
# A file that lies about being a PNG is still refused: the magic bytes
# are what count, not the declared type or the extension.
liar = upload("fake.png", b"<?php echo 1; ?>", "image/png", expect=415)
check("a mislabelled file is 415", "格式" in liar["detail"], liar["detail"])
empty = upload("empty.png", b"", "image/png", expect=400)
check("an empty upload is 400", "空" in empty["detail"], empty["detail"])
print("6. what it will not serve")
missing, _ = fetch(f"/api/images/2026/01/{'0' * 16}.png", expect=404)
check("a key with no object is 404", True, missing.decode("utf-8", "replace")[:80])
fetch("/api/images/mattermost/20260724/logo.png", expect=404)
check("a key we did not write is 404 (the bucket is not browsable)", True)
fetch("/api/images/2026/01/zzzzzzzzzzzzzzzz.png", expect=404)
check("a key outside the key space is 404", True)
print("7. a sentence carries the figure")
templates = call("GET", "/templates?page_size=50")["items"]
check("a template exists", bool(templates), f"got {len(templates)}")
paper = call(
"POST",
"/papers",
{
"title": "冒烟测试-插图论文",
"template_id": templates[0]["id"],
"status": "draft",
},
expect=201,
)
created_papers.append(paper["id"])
sort = call("GET", f"/papers/{paper['id']}/document")["paragraphs"][0][
"paper_template_filed_sort"
]
caption = "试验装置示意图"
prose = f"试验装置如 {image['markdown']} 所示,量测点布置在试件中部。"
call(
"POST",
f"/papers/{paper['id']}/sentences",
{"paper_template_filed_sort": sort, "content": prose, "sort": 1},
expect=201,
)
call(
"POST",
f"/papers/{paper['id']}/sentences",
{
"paper_template_filed_sort": sort,
"content": f"![{caption}]({image['url']}){{width=70%}}",
"sort": 2,
"line_break_before": True,
},
expect=201,
)
document = call("GET", f"/papers/{paper['id']}/document")
paragraph = next(
item for item in document["paragraphs"] if item["paper_template_filed_sort"] == sort
)
contents = [sentence["content"] for sentence in paragraph["sentences"]]
check("the inline image survives the round trip", contents[0] == prose, contents[0])
check(
"the figure sentence survives with its size",
contents[1] == f"![{caption}]({image['url']}){{width=70%}}",
contents[1],
)
check("it is on a line of its own", paragraph["sentences"][1]["line_break_before"])
check(
"the server did not touch the markup",
image["url"] in contents[0] and image["url"] in contents[1],
)
print(f"\nall {_checks} checks passed")
return 0
finally:
# Never leave test rows behind, even on a failed expectation.
for paper_id in created_papers:
try:
call("DELETE", f"/papers/{paper_id}", expect=204)
except Exception as error: # noqa: BLE001 — cleanup must not mask the failure
print(f" !! could not delete paper {paper_id}: {error}", file=sys.stderr)
if __name__ == "__main__":
sys.exit(main())
+308 -7
View File
@@ -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"![图 1 试验装置示意图](/api/images/{figure['key']}){{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"![另一张](/api/images/{figure['key']})",
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"试验装置如 ![示意图]({inline_url}) 所示。"
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"![示意图]({inline_url})\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"![写法宽容](/api/images/{tolerant['key']}){{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"![只写数字](/api/images/{bare['key']}){{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"![宽高都写](/api/images/{sized['key']}){{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"![只限高](/api/images/{tall['key']}){{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
View File
@@ -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_…)」,写作类工具照常可用。
## 访问地址
| 从哪里连 | 地址 |
+26 -4
View File
@@ -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}}]
+10 -1
View File
@@ -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
View File
@@ -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": "![图 3 惯性—冲量相空间](/api/images/2026/09/9f8c1a4b7e2d0c33.png){width=70%}",
// "sentence": {"content": "![图 3 …](…){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": "![图 3 …](…){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": "![图 3 惯性—冲量相空间](/api/images/2026/09/….png){width=70%}",
"line_break_before": true
}}
// 3) 读回来确认它在自己的一行上
{"name": "paragraph_get", "arguments": {"paper_id": 96, "heading": "4.4 技术惯性量化"}}
```
要点:
- **同一张图传两次是同一个对象**:键是内容的 SHA-256,所以重复上传不会堆出副本,也不会换地址。
- **图注写在方括号里**,网页端显示为图下那行字;`width` 不给就按原尺寸(最多不超过栏宽)。
- 想让图**跟着一句话走**(行内小图,而不是独占一行的插图),把它拼进那句话里就行:
`"回归结果见 ![小图](/api/images/…) 的右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) |
+203 -11
View File
@@ -358,6 +358,96 @@ sentences printed correctly by accident (the full stop hides the missing space),
so nothing looked wrong until the first English paper, whose sentences would
have run together.
### An image is an object, and the sentence keeps only its address
Not everything in a paper is text, and the parts that are not do not get a table.
The bytes of a 插图 live in **MinIO** (k3s, S3 protocol) and the sentence keeps
the address, as Markdown:
```
试验装置如 ![行内示意图](/api/images/2026/09/9f8c1a4b7e2d0c33.png) 所示。
![试验装置示意图](/api/images/2026/09/9f8c1a4b7e2d0c33.png){width=70%}
```
A table was the obvious alternative — `paper_image` with a `sort`, a caption and
a paragraph position — and it is wrong here, for the reason the sentence model
already gives: a paragraph is *reassembled from sentences ordered by one number*,
and a second table holding its own `sort` beside that one gives a paragraph two
orderings that eventually disagree. Keeping the picture inside `content` means a
figure moves between paragraphs by being cut and pasted, survives a template
switch with the sentence it belongs to, and needs no new endpoint to write. The
same argument that made citations a table (a citation carries data of its own,
and is queried in both directions) is what keeps images out of one.
Three properties of the storage are deliberate:
- **The key is the digest of the picture.** `2026/09/9f8c1a4b7e2d0c33.png` is
derived from the bytes, so uploading the same screenshot twice — from two
paragraphs, or by accident — stores one object, and the address can never come
to mean a different picture than the one it was written for. That is what makes
the year-long `immutable` cache header safe to hand out.
- **The format is sniffed, never trusted.** The declared content type and the
filename are the uploader's claims; the magic bytes are the fact. PNG, JPEG,
GIF and WebP are accepted — and **SVG is not**, because an uploaded SVG served
from this origin is stored XSS, while the page already renders text the writer
controls. The served content type comes from a whitelist on our side, with
`X-Content-Type-Options: nosniff`.
- **The key space is also the access rule.** `GET /api/images/{key}` serves keys
of the shape this application writes and nothing else, so the read route cannot
become a browser for the rest of the bucket, whatever else is in it.
Images are served through the API rather than from a public bucket URL so that a
sentence never embeds a host name: the same paper is read from the LAN in
development and from the public address later, and a hard-coded origin would
break on the other. It also means the bucket stays private. The response streams
the object out of MinIO rather than reading it into memory, and releases the
connection when the reader stops.
Two rules decide how a picture prints, and both follow from "a sentence is a
line":
| What the sentence holds | How it prints |
|---|---|
| nothing but `![图注](地址)` | a **figure**: its own line, centred, the brackets' text as 图注 underneath |
| 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}`, `{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
reads: only the image routes answer `503`, saying which variables are missing.
The bucket is created on the first upload if it is not there.
### Citations are a table, not a column
One sentence may quote several references, so
@@ -465,6 +555,8 @@ All routes are mounted under `/api`. Interactive docs at `/docs`.
| `PUT` | `/papers/{id}/paragraphs/{sort}` | full replacement; optional `target_sort` moves it |
| `POST` | `/papers/{id}/sentences` | append one sentence |
| `PATCH` `DELETE` | `/papers/{id}/sentences/{id}` | edit or remove one sentence |
| `POST` | `/images` | `multipart/form-data`, one `file` field; answers `key`, `url`, ready-to-paste `markdown`, `content_type`, `size`, `sha256` |
| `GET` | `/images/{key}` | streams the picture; only keys this app wrote, cached `immutable` for a year |
Conventions worth knowing:
@@ -510,6 +602,12 @@ Conventions worth knowing:
rail's labels compose with the toolbar's.
- A DOI is stored without its ``https://doi.org/`` prefix, so the column holds
one spelling whichever way it was pasted.
- An uploaded image is refused with `415` when its bytes are not PNG/JPEG/GIF/
WebP (SVG included), `413` when it is over `MAX_IMAGE_BYTES` (20 MiB) and `400`
when it is empty. A key that has no object, or one this application did not
write, is `404`.
- An image URL is relative (`/api/images/…`) and same-origin on purpose: the
client prints it as it stands, and the paper does not name a host.
## MCP server
@@ -525,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 |
@@ -533,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
@@ -693,15 +793,16 @@ are not lists (the paper document) keep scrolling normally.
A formula is stored exactly as the writer typed it — `$\ell$`, `$$ … \tag{1} $$`
— because that is the form that can be edited; an equation image cannot be
changed by one character. Typesetting happens when the paper is read, in
`src/utils/math.ts`, which splits a sentence into text and formulas, hands the
formulas to KaTeX and escapes everything else.
changed by one character. The same is true of a picture: the sentence keeps the
Markdown that points at it. Typesetting happens when the paper is read, in
`src/utils/rich.ts`, which splits a sentence into text, formulas and images,
hands the formulas to KaTeX and escapes everything else.
Four delimiters are recognised, because a writer's habit decides which they use:
`$$…$$` and `\[…\]` for display, `$…$` and `\(…\)` for inline. An unmatched
`$` is left alone rather than swallowing the rest of the paragraph.
Three rules are worth knowing when reading the renderer:
Four rules are worth knowing when reading the renderer:
- **A display formula is a block.** It takes its own line whether or not the
sentence asked for a break, because that is what "display" means.
@@ -723,6 +824,14 @@ Three rules are worth knowing when reading the renderer:
through `v-html`, and KaTeX runs with `trust` off, so a sentence cannot inject
markup.
An image is the one thing the renderer does *not* build inside that HTML string.
A figure is printed by `PaperParagraph` as a real `<img>` — so it can carry the
writer's size and be opened at full resolution by a click — and `figureOf()`
decides whether a sentence is a figure: it is one when the sentence holds nothing
but a picture and whitespace. The reader's click is handled once, on the
paragraph body, because inline pictures arrive through `v-html`, where no
listener can be bound to them from a template.
### The paper view
`PapersView` is the library; `papers/PaperDetailView` is the writing surface.
@@ -780,11 +889,12 @@ in correctly.
paper-doc/
├── backend/ # FastAPI application
│ ├── app/
│ │ ├── api/routes/ # route handlers (health, papers, references,
│ │ ├── api/routes/ # route handlers (health, images, papers, references,
│ │ │ # reference_tags, templates, template_title)
│ │ ├── citation_styles/ # how a reference prints: springer.py, and the
│ │ │ # registry that names the styles
│ │ ├── core/ # settings and configuration
│ │ ├── core/ # settings, and the object store (MinIO) the
│ │ │ # images a paper embeds are kept in
│ │ ├── crud/ # data-access helpers
│ │ ├── db/ # engine, session, declarative base
│ │ ├── mcp/ # MCP server: tools, specs, transports, self-check
@@ -795,14 +905,18 @@ paper-doc/
│ ├── scripts/smoke_papers.py # end-to-end check of the writing loop
│ ├── scripts/smoke_references.py # end-to-end check of the reference library
│ │ # and its tags
│ ├── 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
@@ -811,7 +925,8 @@ paper-doc/
│ │ ├── stores/ # pinia stores (UI prefs persisted, the paper and
│ │ │ # tag lists not)
│ │ ├── styles/ # global reset and the shell viewport contract
│ │ ├── utils/ # formatting helpers
│ │ ├── utils/ # formatting helpers, and rich.ts — the reader for
│ │ │ # a sentence's LaTeX and its images
│ │ └── views/ # route-level components (papers/, references/,
│ │ # templates/)
│ ├── package.json
@@ -832,6 +947,8 @@ paper-doc/
- Python 3.10+ with `venv`
- Node.js 18+ with `pnpm`
- Network access to the TiDB instance (local development uses the NodePort)
- *Optional:* a MinIO (or any S3-compatible) endpoint, for the images a paper
embeds. Without one, everything still works except uploading pictures.
**Backend**
@@ -839,7 +956,8 @@ paper-doc/
cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # then fill in the database credentials
cp .env.example .env # then fill in the database credentials, and the
# MINIO_* ones if the paper is to hold images
uvicorn app.main:app --reload --port 8000
```
@@ -866,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
@@ -925,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
@@ -949,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
+2 -1
View File
@@ -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",
+508
View File
@@ -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: `试验装置如 ![行内示意图](${image.url}) 所示,量测点布置在试件中部。` },
{ content: `![试验装置示意图](${image.url}){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: `![尺寸试验](${image.url})${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)
+61
View File
@@ -0,0 +1,61 @@
import http from './client'
/**
* Images (插图) — the pictures a sentence embeds.
*
* An image is not stored in the database. The upload puts the bytes in the
* object store and answers with a URL *and* the Markdown that embeds it; the
* sentence keeps that Markdown and nothing else. So inserting a figure is
* ordinary text editing, moving one between paragraphs is cut and paste, and
* nothing about the paper has to be re-saved when a picture is replaced.
*
* The server decides the Markdown (see `app/core/storage.markdown_for`) rather
* than this module, so the syntax written here and the syntax the reader parses
* cannot drift apart.
*/
/** One stored image, as the API reports it. */
export interface StoredImage {
/** Its key in the bucket — the same picture always gets the same key. */
key: string
/** Same-origin path, e.g. `/api/images/2026/09/9f8c1a4b7e2d0c33.png`. */
url: string
/** Ready to paste: `![图注](/api/images/…)`. */
markdown: string
content_type: string
/** Size in bytes. */
size: number
sha256: string
}
/** What the server will accept; the browser's picker filters on the same list. */
export const IMAGE_ACCEPT = 'image/png,image/jpeg,image/gif,image/webp'
/** Refuse a file the server would refuse, before spending a request on it. */
export function imageRejection(file: File): string | null {
if (!IMAGE_ACCEPT.split(',').includes(file.type)) {
return '只支持 PNG / JPEG / GIF / WebP 图片。'
}
return null
}
/**
* Upload one image and get back the Markdown that embeds it.
*
* The Content-Type is set explicitly and *without* a boundary: axios recognises
* a `FormData` body and drops the header, letting the browser write it with the
* boundary it generated. Leaving the shared client's `application/json` default
* in place would send the file as JSON and the server would never see it.
*/
export async function uploadImage(file: File): Promise<StoredImage> {
const form = new FormData()
form.append('file', file)
const { data } = await http.post<StoredImage>('/images', form, {
headers: { 'Content-Type': 'multipart/form-data' },
// The shared client's 15s is sized for queries; a figure over a slow link
// is not a hung request.
timeout: 120000,
})
return data
}
@@ -21,13 +21,52 @@
*
* A sentence that quotes something gets a superscript marker numbered by the
* paper's citation list, so the marker and the 参考文献 entry cannot disagree.
*
* A sentence that is nothing but an image is a figure: its own line, centred,
* with the text in the brackets printed underneath as its 图注. It is built as
* a real `<img>` rather than through `renderRich`, so it can carry the writer's
* size and be opened at full resolution — a figure is read, not just seen.
*/
import { computed } from 'vue'
import { computed, ref } from 'vue'
import { Edit } from '@element-plus/icons-vue'
import type { PaperParagraph } from '@/api/papers'
import { PARAGRAPH_UNSET_LABEL, levelIndent } from '@/utils/format'
import { escapeHtml, hasDisplayMath, renderRich } from '@/utils/math'
import {
escapeHtml,
figureOf,
hasDisplayMath,
renderRich,
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
@@ -65,6 +104,8 @@ interface RenderedSentence {
display: boolean
/** The writer asked for a line break before this sentence. */
lineBreak: boolean
/** The image this sentence is, when it is nothing but an image. */
figure: ImageSegment | null
}
const rendered = computed<RenderedSentence[]>(() =>
@@ -75,6 +116,7 @@ const rendered = computed<RenderedSentence[]>(() =>
renderRich(sentence.content),
display: hasDisplayMath(sentence.content),
lineBreak: sentence.line_break_before,
figure: figureOf(sentence.content),
})),
)
@@ -89,7 +131,8 @@ const rendered = computed<RenderedSentence[]>(() =>
* paragraph should be indented.
*
* A line starts when the writer breaks one, when a display formula needs a line
* of its own, or after one (a block always ends the line it sits in).
* of its own, when a figure does, or after one (a block always ends the line it
* sits in).
*/
interface RenderedLine {
/** Whether the first line of this block is indented by two characters. */
@@ -102,17 +145,19 @@ const renderedLines = computed<RenderedLine[]>(() => {
rendered.value.forEach((item, index) => {
const previous = rendered.value[index - 1]
const isBlock = item.display || item.figure !== null
const previousIsBlock = previous !== undefined && (previous.display || previous.figure !== null)
const startsLine =
index === 0 || // the paragraph's own first line
item.lineBreak || // the writer asked for one
item.display || // a display formula takes a line of its own
Boolean(previous?.display) // …and the line after it starts fresh
isBlock || // a display formula or a figure is a block by definition
previousIsBlock // …and the line after one starts fresh
if (startsLine) {
lines.push({
// Indented at the start of the paragraph, and after a break the writer
// asked for. Not after a display formula: that text continues the same
// paragraph, and a Chinese manuscript does not indent a continuation.
// asked for. Not after a block: that text continues the same paragraph,
// and a Chinese manuscript does not indent a continuation.
indent: index === 0 || item.lineBreak,
items: [],
})
@@ -123,6 +168,22 @@ const renderedLines = computed<RenderedLine[]>(() => {
return lines
})
/**
* The image being read at full size.
*
* An experiment figure on a page is often too small to check a curve against —
* so clicking one opens it over the paper, and clicking away closes it. The
* handler sits on the body and looks at what was clicked rather than being
* attached to each picture: inline images arrive through `v-html`, where no
* listener can be bound to them from a template.
*/
const previewing = ref<string | null>(null)
function onBodyClick(event: MouseEvent): void {
const target = event.target
if (target instanceof HTMLImageElement) previewing.value = target.currentSrc || target.src
}
/** Whether anything has actually been written here. */
const hasContent = computed(() =>
rendered.value.some(
@@ -170,7 +231,7 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_
</div>
</header>
<div v-if="hasContent" class="paragraph-body">
<div v-if="hasContent" class="paragraph-body" @click="onBodyClick">
<p
v-for="(line, index) in renderedLines"
:key="index"
@@ -178,11 +239,28 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_
:class="{ 'is-indented': line.indent }"
>
<template v-for="item in line.items" :key="item.sentence.id">
<!-- A figure: the image, and the text in its brackets printed below
it. It is a block, so it takes a line of its own whether or not
the writer asked for a break. -->
<span v-if="item.figure" class="sentence sentence--figure">
<img
class="figure-image"
:src="item.figure.src"
:alt="item.figure.alt"
:style="sizeStyle(item.figure)"
loading="lazy"
decoding="async"
/>
<span v-if="item.figure.alt" class="figure-caption">
{{ item.figure.alt }}
</span>
</span>
<!-- A display formula is a block by definition, so it takes its own
line whether or not the writer asked for a break. How it sits on
that line is the writer's choice, per formula. -->
<span
v-if="item.display"
v-else-if="item.display"
class="sentence sentence--display"
:class="`is-${item.sentence.formula_align}`"
v-html="item.html"
@@ -225,6 +303,17 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_
「(本段暂无内容)」 into a paper puts words there that the paper did
not ask for, and on export they would go with it. The blank body is
the honest rendering of a blank paragraph. -->
<!-- Full size, over the paper. `teleported` because the paper lives in a
scrolling column, and an overlay positioned inside it would scroll
away with the text. -->
<el-image-viewer
v-if="previewing"
:url-list="[previewing]"
:hide-on-click-modal="true"
teleported
@close="previewing = null"
/>
</section>
</template>
@@ -346,6 +435,44 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_
text-align: right;
}
/* A figure: the picture centred on its own line, its 图注 under it. Sized by its
natural width unless the writer asked for `{width=…}` — an experiment figure
is usually already cropped to what it should show, and stretching it to the
full column would only make the axes bigger. */
.sentence--figure {
display: block;
text-indent: 0;
text-align: center;
margin: 10px 0 6px;
white-space: normal;
}
.figure-image {
max-width: 100%;
height: auto;
border-radius: 4px;
cursor: zoom-in;
vertical-align: middle;
}
.figure-caption {
display: block;
margin-top: 6px;
font-size: 13px;
line-height: 1.7;
color: var(--el-text-color-regular);
}
/* An image inside a run of text — not a figure, so it sits on the line with the
words. Its height is capped because a line of a paragraph is not a place to
discover that someone pasted a screenshot. */
.paragraph-body :deep(.rich-image) {
max-width: 100%;
max-height: 12em;
vertical-align: middle;
cursor: zoom-in;
}
/* The fallback when KaTeX cannot read a formula: the source, in red, so it can
be found and fixed instead of silently vanishing. */
.paragraph-body :deep(.math-error) {
@@ -21,12 +21,21 @@
* The optional 「所属段落」 select moves the whole paragraph to another position,
* appending after whatever that paragraph already holds. That is the manual
* form of what switching the paper's template does by itself.
*
* 「插入图片」 uploads a picture and appends the sentence that shows it — a
* screenshot does not go through the clipboard, and an experiment figure belongs
* on its own line with its 图注 under it, which is exactly what a sentence
* holding nothing but an image renders as. The row then shows the picture, not
* just the path to it, because checking that the right curve went into the right
* paragraph is the whole reason one look at the editor is worth more than three
* reads of a URL.
*/
import { computed, reactive, ref, watch } from 'vue'
import { ArrowDown, ArrowUp, Delete, Plus, Refresh } from '@element-plus/icons-vue'
import { ArrowDown, ArrowUp, Delete, Picture, Plus, Refresh } from '@element-plus/icons-vue'
import { ElMessage } from 'element-plus'
import { errorMessage } from '@/api/client'
import { IMAGE_ACCEPT, imageRejection, uploadImage } from '@/api/images'
import {
FORMULA_ALIGN_OPTIONS,
getParagraph,
@@ -37,7 +46,15 @@ import {
type SentenceInput,
} from '@/api/papers'
import { PARAGRAPH_UNSET_LABEL, foldWhitespace } from '@/utils/format'
import { hasDisplayMath } from '@/utils/math'
import {
figureOf,
hasDisplayMath,
imagesOf,
parseImageHeight,
parseImageWidth,
withImageSize,
type ImageSegment,
} from '@/utils/rich'
const props = defineProps<{
/** Visibility, used with `v-model`. */
@@ -73,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({
@@ -145,6 +171,8 @@ watch(
reference_id: citation.reference_id,
quote: citation.quote,
})),
naturalWidth: null,
naturalHeight: null,
}))
} catch (error) {
ElMessage.error(errorMessage(error))
@@ -168,6 +196,8 @@ function addSentence(): void {
lineBreak: false,
align: 'center',
citations: [],
naturalWidth: null,
naturalHeight: null,
})
}
@@ -175,6 +205,211 @@ function removeSentence(key: number): void {
rows.value = rows.value.filter((row) => row.key !== key)
}
/** The pictures a row shows, so the editor can print them and not just their URLs. */
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. */
const fileInput = ref<HTMLInputElement | null>(null)
/** How many uploads are in flight, so the button can say so. */
const uploading = ref(0)
function pickImage(): void {
fileInput.value?.click()
}
async function onFilePicked(event: Event): Promise<void> {
const input = event.target as HTMLInputElement
const files = Array.from(input.files ?? [])
// Cleared straight away: without it, picking the same file twice in a row
// fires no `change` event the second time and the upload looks broken.
input.value = ''
await insertImages(files)
}
/** Drop a file anywhere in the dialog to insert it. */
async function onDrop(event: DragEvent): Promise<void> {
const files = Array.from(event.dataTransfer?.files ?? [])
if (files.length) await insertImages(files)
}
/**
* Upload each picture and append the sentence that shows it.
*
* One row per image, with 另起一行 set: a figure on a line of its own is what an
* experiment picture is for, and the writer who wants it inline instead is one
* text edit away from it.
*/
async function insertImages(files: File[]): Promise<void> {
for (const file of files) {
const rejection = imageRejection(file)
if (rejection) {
ElMessage.warning(`${file.name}:${rejection}`)
continue
}
uploading.value += 1
try {
const stored = await uploadImage(file)
rows.value.push({
key: nextKey++,
sort: nextSort(),
content: stored.markdown,
lineBreak: true,
align: 'center',
citations: [],
naturalWidth: null,
naturalHeight: null,
})
} catch (error) {
ElMessage.error(errorMessage(error))
} finally {
uploading.value -= 1
}
}
}
function addCitation(row: SentenceDraft): void {
row.citations.push({ key: nextKey++, reference_id: null, quote: '' })
}
@@ -307,7 +542,22 @@ async function submit(): Promise<void> {
</div>
</template>
<div v-loading="loading" class="editor">
<div
v-loading="loading"
class="editor"
@dragover.prevent
@drop.prevent="onDrop"
>
<!-- Driven by the 「插入图片」 button; hidden because the dialog has its
own button rather than the browser's default file control. -->
<input
ref="fileInput"
type="file"
:accept="IMAGE_ACCEPT"
multiple
class="file-input"
@change="onFilePicked"
/>
<el-alert
v-if="heading && !heading.matched"
type="warning"
@@ -351,9 +601,17 @@ async function submit(): Promise<void> {
<span class="toolbar-title">共 {{ orderedRows.length }} 句</span>
<span class="toolbar-hint">
按 sort 升序拼成这个段落;公式写 LaTeX:行内 $x$,独立成行 $$x$$(编号用
\tag{1},自动靠右)
\tag{1},自动靠右);图片也写在句子里:![图注](地址),可加 {width=60%}
</span>
<div class="toolbar-spacer" />
<el-button
size="small"
:icon="Picture"
:loading="uploading > 0"
@click="pickImage"
>
插入图片
</el-button>
<el-button size="small" :icon="Refresh" :disabled="!orderedRows.length" @click="autoNumber">
自动编号
</el-button>
@@ -403,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
@@ -428,6 +747,24 @@ async function submit(): Promise<void> {
placeholder="这一句的内容(只留空白的句子保存时会删除)"
/>
<!-- The picture itself, not only the path to it. The reason to look
at the editor at all is to see that the right curve landed in the
right paragraph. -->
<div class="row-images">
<figure v-for="image in rowImages(row)" :key="image.src" class="row-image">
<!-- 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>
<div class="citations">
<div v-for="citation in row.citations" :key="citation.key" class="citation">
<el-input-number
@@ -576,6 +913,7 @@ async function submit(): Promise<void> {
.row-head {
display: flex;
align-items: center;
flex-wrap: wrap;
gap: 8px;
}
@@ -592,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;
@@ -621,4 +971,47 @@ async function submit(): Promise<void> {
color: var(--el-text-color-secondary);
line-height: 32px;
}
/* The picker is driven by the toolbar button. A browser file control would put
a second, differently-worded uploader in the middle of the dialog. */
.file-input {
display: none;
}
/* The pictures a row holds, printed under its text. `:empty` keeps a row with
no images from reserving a box for them. */
.row-images {
display: flex;
flex-wrap: wrap;
gap: 10px;
}
.row-images:empty {
display: none;
}
.row-image {
display: flex;
flex-direction: column;
gap: 4px;
max-width: 168px;
margin: 0;
}
.row-image img {
max-width: 168px;
max-height: 112px;
height: auto;
object-fit: contain;
border: 1px solid var(--el-border-color-lighter);
border-radius: 4px;
background-color: var(--el-fill-color-lighter);
}
.row-image figcaption {
font-size: 12px;
line-height: 1.5;
color: var(--el-text-color-secondary);
overflow-wrap: anywhere;
}
</style>
-113
View File
@@ -1,113 +0,0 @@
/**
* Rendering a sentence that contains LaTeX.
*
* A sentence is stored as the writer typed it, LaTeX and all, because that is
* what can be edited — `$\ell$` is one character to change and an equation
* image is not. Reading it is this module's job: it splits the text into plain
* segments and formulas, hands the formulas to KaTeX, and escapes everything
* that is not a formula.
*
* Four delimiters are recognised, because a paper written in LaTeX, in
* Markdown, or by hand uses whichever the writer's habit prefers:
*
* ================== ==========
* `$$ … $$` display (own line, centred, may carry `\tag{1}`)
* `\[ … \]` display
* `$ … $` inline
* `\( … \)` inline
* ================== ==========
*
* An unmatched `$` is left alone: money in a sentence, or a formula half
* typed, must not swallow the rest of the paragraph.
*
* `throwOnError: false` is deliberate. A broken formula renders as its own
* source in red rather than an exception, so one typo cannot blank out the
* paper the writer is reading.
*/
import katex from 'katex'
/** One piece of a sentence: plain text, or a formula and how to set it. */
export type RichSegment =
| { kind: 'text'; value: string }
| { kind: 'math'; value: string; display: boolean }
/**
* Display delimiters are matched first: `$$…$$` contains `$…$`, so the other
* order would read an empty inline formula and leave the rest as text.
*/
const MATH_PATTERN = /\$\$([\s\S]+?)\$\$|\\\[([\s\S]+?)\\\]|\$([^$\n]+?)\$|\\\(([\s\S]+?)\\\)/g
const HTML_ESCAPES: Record<string, string> = {
'&': '&amp;',
'<': '&lt;',
'>': '&gt;',
'"': '&quot;',
"'": '&#39;',
}
/** Escape text that is going into `v-html`, since it is not markup. */
export function escapeHtml(value: string): string {
return value.replace(/[&<>"']/g, (character) => HTML_ESCAPES[character] ?? character)
}
/** Split a sentence into its plain and mathematical parts. */
export function splitRich(content: string): RichSegment[] {
const segments: RichSegment[] = []
let cursor = 0
MATH_PATTERN.lastIndex = 0
for (let match = MATH_PATTERN.exec(content); match; match = MATH_PATTERN.exec(content)) {
if (match.index > cursor) {
segments.push({ kind: 'text', value: content.slice(cursor, match.index) })
}
const [whole, doubleDollar, doubleBracket, singleDollar, singleBracket] = match
segments.push({
kind: 'math',
value: doubleDollar ?? doubleBracket ?? singleDollar ?? singleBracket ?? '',
display: doubleDollar !== undefined || doubleBracket !== undefined,
})
cursor = match.index + whole.length
}
if (cursor < content.length) {
segments.push({ kind: 'text', value: content.slice(cursor) })
}
return segments
}
/** Whether a sentence contains a formula that belongs on its own line. */
export function hasDisplayMath(content: string): boolean {
return splitRich(content).some((segment) => segment.kind === 'math' && segment.display)
}
/** Render one formula, or the source in red when KaTeX cannot read it. */
function renderMath(value: string, display: boolean): string {
try {
return katex.renderToString(value, {
displayMode: display,
throwOnError: false,
strict: false,
})
} catch {
// KaTeX throws only for input it cannot process at all; showing the source
// is more useful to the writer than an empty space.
return `<code class="math-error">${escapeHtml(value)}</code>`
}
}
/**
* Render a sentence to HTML: text escaped, formulas typeset.
*
* The result is for `v-html`. KaTeX's own output is the only markup in it —
* `trust` is off, so no command can inject HTML — and every text segment is
* escaped here.
*/
export function renderRich(content: string): string {
return splitRich(content)
.map((segment) =>
segment.kind === 'text'
? escapeHtml(segment.value)
: renderMath(segment.value, segment.display),
)
.join('')
}
+324
View File
@@ -0,0 +1,324 @@
/**
* Reading a sentence: what the writer typed, turned into what the paper shows.
*
* A sentence is stored as one string, because that is the only form of it that
* can be *edited*: `$\ell$` is one character to change, a typeset equation is
* not, and `![图注](/api/images/…)` moves between paragraphs by being cut and
* pasted. Everything here exists to make that decision readable.
*
* Two families of markup are recognised.
*
* **Formulas** — four delimiters, because a paper written in LaTeX, in
* Markdown, or by hand uses whichever the writer's habit prefers:
*
* ================== ==========
* `$$ … $$` display (own line, centred, may carry `\tag{1}`)
* `\[ … \]` display
* `$ … $` inline
* `\( … \)` inline
* ================== ==========
*
* **Images** — `![图注](地址)`, the Markdown every editor already writes, with
* an optional size in pandoc's attribute form:
*
* ============================ =========================================
* `![图注](地址)` drawn at its natural size, capped to the column
* `![图注](地址){width=70%}` 70% of the column
* `![图注](地址){width=400px}` 400 pixels
* ============================ =========================================
*
* An image alone in a sentence is a *figure*: it takes a line of its own with
* its 图注 underneath (see `figureOf`). The same markup inside a run of text
* stays inline, at the size of the text around it.
*
* An unmatched `$` is left alone: money in a sentence, or a formula half typed,
* must not swallow the rest of the paragraph. The same goes for a half-typed
* image — an unclosed `![` prints as the characters it is.
*/
import katex from 'katex'
/** One piece of a sentence: plain text, a formula, or a picture. */
export type RichSegment =
| { kind: 'text'; value: string }
| { kind: 'math'; value: string; display: boolean }
| {
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' }>
/**
* The image alternative comes first: `![a](b)` starts with `!`, which no
* formula does, so the two never compete for the same characters. Within the
* formulas, display delimiters are matched before inline ones because `$$…$$`
* contains `$…$`.
*/
const RICH_PATTERN = new RegExp(
[
String.raw`!\[(?<alt>[^\]]*)\]\((?<src>[^()\s]+)(?:\s+"(?<title>[^"]*)")?\)(?<attrs>\{[^}]*\})?`,
String.raw`\$\$(?<displayDollar>[\s\S]+?)\$\$`,
String.raw`\\\[(?<displayBracket>[\s\S]+?)\\\]`,
String.raw`\$(?<inlineDollar>[^$\n]+?)\$`,
String.raw`\\\((?<inlineBracket>[\s\S]+?)\\\)`,
].join('|'),
'g',
)
/**
* `{width=70%}` / `{w=400px}` — pandoc's attribute form, with both spellings of
* the key that people type.
*
* 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
const HTML_ESCAPES: Record<string, string> = {
'&': '&amp;',
'<': '&lt;',
'>': '&gt;',
'"': '&quot;',
"'": '&#39;',
}
/** Escape text that is going into `v-html`, since it is not markup. */
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 {
const part = declared(attributes, /^(?:w|width)\s*=/i)
if (!part) return null
const match = WIDTH_PATTERN.exec(part)
if (!match) return null
const value = Number(match[1])
if (match[2] === 'px') {
return value >= 1 && value <= MAX_PIXELS ? `${value}px` : 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 `![${alt}](${src}${name})${attribute}`
})
}
/** Split a sentence into its plain, mathematical and pictorial parts. */
export function splitRich(content: string): RichSegment[] {
const segments: RichSegment[] = []
let cursor = 0
RICH_PATTERN.lastIndex = 0
for (let match = RICH_PATTERN.exec(content); match; match = RICH_PATTERN.exec(content)) {
if (match.index > cursor) {
segments.push({ kind: 'text', value: content.slice(cursor, match.index) })
}
const groups = match.groups ?? {}
if (groups.src !== undefined) {
const size = parseImageSize(groups.attrs)
segments.push({
kind: 'image',
src: groups.src,
alt: groups.alt ?? '',
width: size.width,
height: size.height,
})
} else {
segments.push({
kind: 'math',
value:
groups.displayDollar ??
groups.displayBracket ??
groups.inlineDollar ??
groups.inlineBracket ??
'',
display: groups.displayDollar !== undefined || groups.displayBracket !== undefined,
})
}
cursor = match.index + match[0].length
}
if (cursor < content.length) {
segments.push({ kind: 'text', value: content.slice(cursor) })
}
return segments
}
/** Whether a sentence contains a formula that belongs on its own line. */
export function hasDisplayMath(content: string): boolean {
return splitRich(content).some((segment) => segment.kind === 'math' && segment.display)
}
/**
* The image a sentence consists of, when it consists of one.
*
* This is the rule that separates a 插图 from an inline picture: a sentence
* holding nothing but an image is a figure — it starts its own line, is
* centred, and the text in the brackets prints underneath as its 图注. Anything
* else — a picture inside a sentence that says something — stays in the line,
* at the size of the text around it.
*/
export function figureOf(content: string): ImageSegment | null {
const meaningful = splitRich(content).filter(
(segment) => segment.kind !== 'text' || segment.value.trim().length > 0,
)
if (meaningful.length !== 1) return null
const only = meaningful[0]!
return only.kind === 'image' ? only : null
}
/** Every image in a sentence, in the order it appears. */
export function imagesOf(content: string): ImageSegment[] {
return splitRich(content).filter(
(segment): segment is ImageSegment => segment.kind === 'image',
)
}
/** Render one formula, or the source in red when KaTeX cannot read it. */
function renderMath(value: string, display: boolean): string {
try {
return katex.renderToString(value, {
displayMode: display,
throwOnError: false,
strict: false,
})
} catch {
// KaTeX throws only for input it cannot process at all; showing the source
// is more useful to the writer than an empty space.
return `<code class="math-error">${escapeHtml(value)}</code>`
}
}
/**
* Render the *inline* content of a sentence: text escaped, formulas typeset,
* pictures placed in the running line.
*
* A figure is deliberately not built here. It is a block with a caption, and
* the component that prints a paragraph makes it from `figureOf` so that the
* picture is a real `<img>` it can bind to and click, rather than markup
* assembled inside a string.
*
* The result is for `v-html`. KaTeX's own output is the only markup in it —
* `trust` is off, so no command can inject HTML — and every text segment and
* every attribute is escaped here.
*/
export function renderRich(content: string): string {
return splitRich(content)
.map((segment) => {
if (segment.kind === 'text') return escapeHtml(segment.value)
if (segment.kind === 'math') return renderMath(segment.value, segment.display)
const width = segment.width ? ` style="width:${segment.width}"` : ''
return (
`<img class="rich-image" src="${escapeHtml(segment.src)}"` +
` alt="${escapeHtml(segment.alt)}" loading="lazy" decoding="async"${width}>`
)
})
.join('')
}