Compare commits

..

2 Commits

Author SHA1 Message Date
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
16 changed files with 1476 additions and 134 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.
+298
View File
@@ -0,0 +1,298 @@
"""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 not in {"404", "NoSuchBucket", "NotFound"}:
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)})
+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.
+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())
+93 -8
View File
@@ -358,6 +358,68 @@ 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}` — and is validated to digits plus one unit before it becomes a
CSS length, so no second declaration can be smuggled through it.
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 +527,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 +574,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
@@ -693,15 +763,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 +794,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 +859,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,6 +875,7 @@ 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/mcp_server.py # MCP entry point (stdio / http)
@@ -811,7 +892,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 +914,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 +923,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
```
+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,24 @@
*
* 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'
const props = defineProps<{
paragraph: PaperParagraph
@@ -65,6 +76,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 +88,7 @@ const rendered = computed<RenderedSentence[]>(() =>
renderRich(sentence.content),
display: hasDisplayMath(sentence.content),
lineBreak: sentence.line_break_before,
figure: figureOf(sentence.content),
})),
)
@@ -89,7 +103,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 +117,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 +140,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 +203,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 +211,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="item.figure.width ? { width: item.figure.width } : undefined"
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 +275,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 +407,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,7 @@ import {
type SentenceInput,
} from '@/api/papers'
import { PARAGRAPH_UNSET_LABEL, foldWhitespace } from '@/utils/format'
import { hasDisplayMath } from '@/utils/math'
import { hasDisplayMath, imagesOf, type ImageSegment } from '@/utils/rich'
const props = defineProps<{
/** Visibility, used with `v-model`. */
@@ -175,6 +184,71 @@ 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)
}
// --- 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: [],
})
} 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 +381,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 +440,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>
@@ -428,6 +525,16 @@ 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">
<img :src="image.src" :alt="image.alt" loading="lazy" />
<figcaption>{{ image.alt || '方括号里写的就是图注' }}</figcaption>
</figure>
</div>
<div class="citations">
<div v-for="citation in row.citations" :key="citation.key" class="citation">
<el-input-number
@@ -621,4 +728,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('')
}
+219
View File
@@ -0,0 +1,219 @@
/**
* 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; width: 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.
*/
const WIDTH_PATTERN = /^\s*(?:w|width)\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)
}
/** Read a size out of an image's attributes, or refuse to guess one. */
export function parseImageWidth(attributes: string | undefined): string | null {
if (!attributes) return null
const match = WIDTH_PATTERN.exec(attributes.replace(/^\{|\}$/g, ''))
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
}
/** 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) {
segments.push({
kind: 'image',
src: groups.src,
alt: groups.alt ?? '',
width: parseImageWidth(groups.attrs),
})
} 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('')
}