backend: give the reference library the MCP tools it was missing, and fix the one that broke

The reference library landed with a full REST API and no MCP surface at all:
an agent could cite `reference_id: 42` — the citation is validated now — but
could not look up what 42 was, create it, or find out whether the library
already had it. That is the citation half of "generate the paper, then write it
in" missing, and it is the half an agent is worst at doing by hand.

Twelve tools, mirroring the REST surface plus one addition each way:

- `reference_*` — search, read, create, update, delete, plus
  `reference_import`, which takes a whole pasted bibliography in one call and
  reports what it skipped (an existing DOI or an identical title) and what it
  could not read, one bad entry at a time rather than losing the other nineteen;
  and `reference_citations`, which answers "what is this cited for" before a
  rename or a delete. `reference_list`'s keyword search across title, container,
  DOI and author names is the de-duplication path that `reference_import` uses.
- `reference_tag_*` — the five CRUD tools. Deleting a tag drops the labelling
  and leaves the literature, which is the opposite of what the field library
  needs and the same choice the REST route makes.

Two things had to be fixed to get here, both found by testing rather than
reading:

`template_list` was crashing. The rename that turned a heading into a title and
its use into a placement changed `TemplateListItem.field_count` to
`placement_count` and left the tool reading the old attribute, so the call died
with `Error executing tool template_list` — unreadable, and live in the
cluster. The suite passed 47 checks while this was broken because it never
called `template_list`: the uncovered tools were exactly the read-only ones, so
the write paths were all green and the browse path was not. The suite now
covers all 41 tools — 76 checks — and step 5 asserts the shape each read tool
returns, not merely that it returned.

`DOMAIN_REFUSALS` in the tool registry held one class, `UnknownReference`. The
tag rules arrived with the tag tools and raise two more, so 「标签不存在:9」 and
「标签「必读」已存在」 would have reached a model as `Error executing tool …`.
The tuple is now the list of every refusal a tool is expected to translate, and
a new one belongs in it on the day it is written.

`reference_update` takes its changes as one nested object rather than 38 keyword
parameters: a nested model keeps `model_fields_set`, so an omitted field stays
absent while an explicit null clears the column. Flattened, the two are
indistinguishable — every omitted field arrives as None — which is the same
problem `paper_update` solves by rebuilding its payload from what it was given.

Verified against the deployed service, not a local process: 76 checks pass over
the NodePort, then the same 76 over stdio and against a local HTTP server, and
the REST suite still passes its 55. The image is rebuilt as v4 and the
Deployment follows it, because `imagePullPolicy: IfNotPresent` means re-pushing
a tag the node already holds changes nothing.
This commit is contained in:
2026-09-22 18:30:24 +08:00
parent a29badd362
commit 15955f552d
10 changed files with 1085 additions and 75 deletions
+95
View File
@@ -109,10 +109,105 @@ class FieldSpec(BaseModel):
]
class ReferenceAuthorSpec(BaseModel):
"""One contributor of one reference."""
name: Annotated[
str,
Field(description="姓名,按引用里要印的样子写,如 “Smith, John” 或 “张三”"),
]
family_name: Annotated[str | None, Field(description="姓")] = None
given_name: Annotated[str | None, Field(description="名")] = None
role: Annotated[
str,
Field(description="角色:author(默认)/ editor / translator / compiler"),
] = "author"
class ReferenceFields(BaseModel):
"""Every bibliographic field, all optional — the shape an update sends.
Nested rather than flattened into the tool signature for one reason that
matters more than tidiness: a nested model keeps ``model_fields_set``, so
the tool can tell "the caller wrote ``note: null``" (clear it) from "the
caller did not mention ``note``" (leave it). Spread across 38 keyword
parameters, every omitted field would arrive as ``None`` and the two cases
would be indistinguishable — the same problem ``paper_update`` solves by
rebuilding its payload from the parameters it was given.
"""
type: Annotated[
str | None,
Field(description="类型:journal-article / book / book-chapter / conference-paper / thesis / patent / standard / report / newspaper-article / web-page / dataset / software / preprint / other"),
] = None
title: Annotated[str | None, Field(description="题名(原文)")] = None
subtitle: Annotated[str | None, Field(description="副题名")] = None
title_translated: Annotated[str | None, Field(description="并列题名/译名")] = None
title_short: Annotated[str | None, Field(description="题名缩写")] = None
container_title: Annotated[str | None, Field(description="期刊/论文集/丛书名")] = None
container_title_short: Annotated[str | None, Field(description="容器名缩写")] = None
series_title: Annotated[str | None, Field(description="丛书名")] = None
series_number: Annotated[str | None, Field(description="丛书号")] = None
edition: Annotated[str | None, Field(description="版次")] = None
volume: Annotated[str | None, Field(description="卷")] = None
issue: Annotated[str | None, Field(description="期")] = None
pages: Annotated[str | None, Field(description="页码,如 123-145")] = None
article_number: Annotated[str | None, Field(description="文章编号")] = None
publisher: Annotated[str | None, Field(description="出版社/机构")] = None
publisher_place: Annotated[str | None, Field(description="出版地")] = None
event_title: Annotated[str | None, Field(description="会议名")] = None
event_place: Annotated[str | None, Field(description="会议地点")] = None
event_date: Annotated[str | None, Field(description="会议日期")] = None
publication_year: Annotated[int | None, Field(description="出版年")] = None
publication_month: Annotated[int | None, Field(description="出版月 1-12")] = None
publication_day: Annotated[int | None, Field(description="出版日 1-31")] = None
accessed_date: Annotated[str | None, Field(description="访问日期 YYYY-MM-DD")] = None
doi: Annotated[str | None, Field(description="DOI,可带 https://doi.org/ 前缀")] = None
isbn: Annotated[str | None, Field(description="ISBN")] = None
issn: Annotated[str | None, Field(description="ISSN")] = None
url: Annotated[str | None, Field(description="网址")] = None
patent_country: Annotated[str | None, Field(description="专利国别")] = None
patent_number: Annotated[str | None, Field(description="专利号")] = None
standard_number: Annotated[str | None, Field(description="标准号")] = None
report_number: Annotated[str | None, Field(description="报告号")] = None
arxiv_id: Annotated[str | None, Field(description="arXiv 编号")] = None
abstract: Annotated[str | None, Field(description="摘要")] = None
keywords: Annotated[str | None, Field(description="关键词")] = None
note: Annotated[str | None, Field(description="备注")] = None
citation_key: Annotated[str | None, Field(description="引用键,如 smith2024flood")] = None
language: Annotated[str | None, Field(description="语言:zh / en / ja / other")] = None
authors: Annotated[
list[ReferenceAuthorSpec] | None,
Field(description="作者列表;给了就是整体替换,顺序即印刷顺序"),
] = None
tag_ids: Annotated[
list[int] | None,
Field(description="标签 id 列表;给了就是整体替换,传 [] 表示清空"),
] = None
class ReferenceSpec(ReferenceFields):
"""The shape a *new* reference arrives in: a type and a title, at least."""
type: Annotated[
str,
Field(description="类型:journal-article(默认)/ book / book-chapter / conference-paper / thesis / patent / standard / report / newspaper-article / web-page / dataset / software / preprint / other"),
] = "journal-article"
title: Annotated[str, Field(description="题名(原文),必填")]
authors: Annotated[
list[ReferenceAuthorSpec],
Field(description="作者列表,顺序即印刷顺序"),
] = []
tag_ids: Annotated[list[int], Field(description="标签 id 列表")] = []
__all__ = [
"CitationSpec",
"FieldSpec",
"ParagraphSpec",
"ReferenceAuthorSpec",
"ReferenceFields",
"ReferenceSpec",
"SentenceItem",
"SentenceSpec",
"SplitMode",