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