1531263bd2
A writer with a tall panel does not want to shrink it from the left edge: what
they know is "this one is too tall". The format had a width and nothing else, so
the only way to make a figure shorter was to guess a percentage and check the
page — and the previous commit's answer, "type 638px", asked them to do the
arithmetic themselves.
So `{height=300px}` joins `{width=…}`, in the same attribute block, and the
editor grows a second box beside the first. Both are typeable as well as
pre-set, both write through the reader's own parse function, and the hint beside
them says what the picture will measure on the page.
Three rules, and the point of all three is that a figure cannot be stretched:
* **a width is exact, a height is a cap.** A width has a reference — the column,
or a length the writer chose — while nothing measures a height against
anything, and enlarging a picture past its own pixels only makes it soft. In
the flow of a sentence a height is always a downscale, which comes to the same
thing as exact.
* **given one, the other follows from the picture's own shape** — `max-height`
for a height, `width` for a width — so the height is never written by hand.
* **given both, they are a box to fit inside**, not a box to fill. Two numbers
that need not have the picture's proportions can only mean "no bigger than",
and the check asserts the drawn rectangle still matches the file's ratio.
Whichever box is left empty keeps the other's setting, so a size can be set in
two steps, and clearing either goes back to the natural size.
`check-image.mjs`: 26 checks to 36. Two of the new ones found real bugs while
being written. The first: with both a width and a height in one `{…}` block,
neither side parsed — the patterns were anchored to the whole block, so a figure
with two numbers silently printed at its natural size. The attribute block is now
split into declarations first. The second was mine: returning "contain" for a
height-only figure left a 1276×2000 box around a small picture, which the caption
then sat under. A height is a cap, and a cap needs no contain.
The MCP tool takes the same two arguments, so a model can write either number,
and a percentage height is refused with the reason it cannot work: a sentence is
flowed text, so there is nothing for it to be a percentage of and the browser
ignores it. v8 is deployed and DSH has verified both numbers round-tripping.
256 lines
11 KiB
Python
256 lines
11 KiB
Python
"""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"]
|