Compare commits
2 Commits
e8e129221c
...
0e0fde8f02
| Author | SHA1 | Date | |
|---|---|---|---|
| 0e0fde8f02 | |||
| 6f37120dc4 |
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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 — ```` —
|
||||
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",
|
||||
},
|
||||
)
|
||||
@@ -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.
|
||||
|
||||
@@ -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"})"
|
||||
|
||||
|
||||
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())
|
||||
@@ -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)})
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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,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.
|
||||
|
||||
@@ -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"",
|
||||
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"",
|
||||
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"{{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"{{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
@@ -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:
|
||||
|
||||
```
|
||||
试验装置如  所示。
|
||||
{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
|
||||
```
|
||||
|
||||
|
||||
@@ -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: ``. */
|
||||
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>
|
||||
|
||||
@@ -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> = {
|
||||
'&': '&',
|
||||
'<': '<',
|
||||
'>': '>',
|
||||
'"': '"',
|
||||
"'": ''',
|
||||
}
|
||||
|
||||
/** 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('')
|
||||
}
|
||||
@@ -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 `` 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 `` 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> = {
|
||||
'&': '&',
|
||||
'<': '<',
|
||||
'>': '>',
|
||||
'"': '"',
|
||||
"'": ''',
|
||||
}
|
||||
|
||||
/** 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('')
|
||||
}
|
||||
Reference in New Issue
Block a user