backend: let a model put a figure in the paper, and set a formula's alignment

Two things the editor gained and MCP could not do, both because the tool layer
had been told about the domain's columns by hand.

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

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

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

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

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

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

Deployed as v6, and the pod now carries MINIO_ENDPOINT (the in-cluster Service)
plus the two credential keys from the Secret; without them the image tool answers
with the missing variable names and every writing tool still works.
This commit is contained in:
2026-09-24 10:54:27 +08:00
parent eb0f12b8cf
commit ebaf9e558b
13 changed files with 816 additions and 79 deletions
+11 -5
View File
@@ -14,20 +14,26 @@ paper-doc 的 MCP 服务跑在 k3s 里,命名空间 **`paper-doc`**,客户
| Namespace | `paper-doc` | `deploy/k8s/00-namespace.yaml` |
| Deployment | `paper-doc-mcp` | 1 副本,跑 MCP 服务的 http 传输 |
| Service | `paper-doc-mcp` | NodePort **30931** → 容器 8931 |
| ConfigMap | `paper-doc-config` | 非敏感环境变量(数据库地址、监听配置) |
| Secret | `paper-doc-secrets` | `DB_USER` / `DB_PASSWORD` / `MCP_HTTP_TOKEN` |
| ConfigMap | `paper-doc-config` | 非敏感环境变量(数据库地址、监听配置、MinIO 端点与桶名) |
| Secret | `paper-doc-secrets` | `DB_USER` / `DB_PASSWORD` / `MCP_HTTP_TOKEN` / `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` |
| Secret | `aliyun-acr` | 镜像仓库拉取凭证(从 `default` 复制) |
镜像:`registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v5`
(`sha256:1e17a72ca611a498d93fc960a7fe1eba5ed5803376794efa66f1967830d51c5d`;
镜像:`registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v6`
(`sha256:c89c0ba250c872dec45e6e5ce056dcf1f73c5415f55aa8b05216ce785ae28732`;
`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 插图与公式对齐**。)
**数据库**:TiDB 已经在这个集群里,Deployment 用集群内的 Service
`tidb-tidb.tidb:4000`,而不是宿主机用的 NodePort `192.168.1.88:32738`。
两者是同一份数据;集群内用 Service 的好处是节点地址变了也不用改配置。
**对象存储**:论文里的插图放在 MinIO(命名空间 `minio`,同一个集群)。
集群内用它自己的 Service `http://minio.minio.svc.cluster.local:9000`,
宿主机上开发才用 NodePort `http://192.168.1.88:30090`;两边是同一个桶 `paper-images`,
桶会在第一次上传时自动创建。少给凭证不会让服务起不来:`image_upload` 会回一句
「图片存储还没有配置好(缺少 MINIO_…)」,写作类工具照常可用。
## 访问地址
| 从哪里连 | 地址 |
+26 -4
View File
@@ -22,6 +22,14 @@ data:
DB_NAME: paper_doc
APP_NAME: paper-doc API
DEBUG: "false"
# Object storage for the images a paper embeds (MinIO, in its own namespace).
# The in-cluster Service, not the host's NodePort 30090: same bucket, and the
# address survives the node changing. The credentials live in the Secret —
# without them `image_upload` answers 「图片存储还没有配置好」 and names the
# variables, while every writing tool keeps working.
MINIO_ENDPOINT: http://minio.minio.svc.cluster.local:9000
MINIO_BUCKET: paper-images
MINIO_REGION: us-east-1
# The container's own defaults, restated here because the Deployment is where
# a reader looks for them.
MCP_TRANSPORT: http
@@ -67,7 +75,7 @@ spec:
type: RuntimeDefault
containers:
- name: mcp
image: registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v5
image: registry.cn-hangzhou.aliyuncs.com/mcp_skill/paper-doc-mcp:v6
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:v6
# 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:v6
# command: ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
# ports: [{name: http, containerPort: 8000}]
# envFrom: [{configMapRef: {name: paper-doc-config}}]
+10 -1
View File
@@ -5,11 +5,18 @@
# kubectl -n paper-doc create secret generic paper-doc-secrets \
# --from-literal=DB_USER='Govin' \
# --from-literal=DB_PASSWORD='<tidb-password>' \
# --from-literal=MCP_HTTP_TOKEN="$(openssl rand -hex 32)"
# --from-literal=MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
# --from-literal=MINIO_ACCESS_KEY='<minio-access-key>' \
# --from-literal=MINIO_SECRET_KEY='<minio-secret-key>'
#
# Rotating the token is then one `kubectl create secret ... --dry-run=client -o
# yaml | kubectl apply -f -` plus a rollout restart, and no image rebuild.
#
# The MinIO pair is what `image_upload` / `POST /api/images` needs; a key scoped
# to the one bucket is enough, and the bucket is created on the first upload.
# Without the pair every writing tool still works and the image ones answer with
# the names of the variables that are missing.
#
# The registry pull secret is separate and not described here: it is
# `aliyun-acr`, copied into this namespace from `default`, and it holds the
# container registry's credentials rather than the application's.
@@ -23,3 +30,5 @@ stringData:
DB_USER: Govin
DB_PASSWORD: change-me
MCP_HTTP_TOKEN: change-me
MINIO_ACCESS_KEY: change-me
MINIO_SECRET_KEY: change-me