15955f552d
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.
264 lines
11 KiB
Python
264 lines
11 KiB
Python
"""Template tools (模板): the outline a paper is written against.
|
||
|
||
A template is not configuration, it is *structure*: a paper renders its
|
||
headings by reading its template live, so editing a template reshapes every
|
||
paper written against it and deleting one would empty them. That is why
|
||
:func:`template_delete` refuses while any paper points at the template, with the
|
||
paper count in the message — the same refusal, and the same words, the REST API
|
||
gives.
|
||
|
||
The two ways to send a selection exist because two callers exist. A model that
|
||
knows the field ids and the order it wants them in sends ``field_ids`` and lets
|
||
the server number them 10, 20, 30 — spaced so a field can later be slipped
|
||
between two others without renumbering the rest. A caller reproducing an exact
|
||
outline sends ``fields`` with the sorts it means.
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from typing import Annotated, Any
|
||
|
||
from mcp.server.mcpserver import MCPServer
|
||
from pydantic import Field
|
||
from sqlalchemy.orm import Session
|
||
|
||
from app.crud import paper as paper_crud
|
||
from app.crud import template as template_crud
|
||
from app.mcp import support as s
|
||
from app.mcp.specs import FieldSpec
|
||
from app.mcp.tools.registry import mcp_tool
|
||
from app.models import Template
|
||
from app.schemas.template import TemplateCreate, TemplateTitlePlacementInput
|
||
|
||
#: Spacing between generated sorts. Ties are legal in a template and gaps are
|
||
#: expected — the editor numbers a fresh selection 1..N only on request — so
|
||
#: numbering 10, 20, 30 leaves room to insert without touching the rest.
|
||
SORT_STEP = 10
|
||
|
||
|
||
def register(server: MCPServer) -> None:
|
||
"""Register every template tool on ``server``."""
|
||
|
||
@mcp_tool(server, title="列出模板")
|
||
def template_list(
|
||
keyword: Annotated[
|
||
str | None, Field(description="按模板名称或摘要模糊搜索")
|
||
] = None,
|
||
page: Annotated[int, Field(description="页码,从 1 开始")] = 1,
|
||
page_size: Annotated[int, Field(description="每页条数,最大 200")] = 20,
|
||
) -> str:
|
||
"""列出论文模板(含字段数量,不含大纲)。"""
|
||
page, page_size = s.page_args(page, page_size)
|
||
with s.session() as db:
|
||
items, total = template_crud.list_templates(
|
||
db, keyword=keyword, page=page, page_size=page_size
|
||
)
|
||
return s.dumps(
|
||
s.page_payload(
|
||
items=[
|
||
{
|
||
"id": item.id,
|
||
"name": item.name,
|
||
"abstract": item.abstract,
|
||
# Read from ``placement_count`` — the column this
|
||
# interface calls a field count. The rename that
|
||
# introduced "placement" changed the schema and left
|
||
# this read behind, which is why this tool is the
|
||
# one the first tool sweep found broken: the key
|
||
# stays "fields" for callers, the attribute does not.
|
||
"fields": item.placement_count,
|
||
"updated_at": item.updated_at,
|
||
}
|
||
for item in items
|
||
],
|
||
total=total,
|
||
page=page,
|
||
page_size=page_size,
|
||
)
|
||
)
|
||
|
||
@mcp_tool(server, title="取模板大纲")
|
||
def template_get(
|
||
template_id: Annotated[int, Field(description="模板 id")],
|
||
) -> str:
|
||
"""取一个模板的完整大纲:每个字段的位置、标题、层级与字号。"""
|
||
with s.session() as db:
|
||
template = s.template_or_fail(db, template_id)
|
||
payload = _template_row(template)
|
||
payload["used_by_papers"] = paper_crud.template_paper_counts(
|
||
db, [template.id]
|
||
).get(template.id, 0)
|
||
return s.dumps(payload)
|
||
|
||
@mcp_tool(server, title="新建模板")
|
||
def template_create(
|
||
name: Annotated[str, Field(description="模板名称,必须唯一")],
|
||
abstract: Annotated[str | None, Field(description="模板说明")] = None,
|
||
field_ids: Annotated[
|
||
list[int] | None,
|
||
Field(description="字段库 id 数组,按顺序排成大纲;sort 会自动编号 10/20/30…"),
|
||
] = None,
|
||
fields: Annotated[
|
||
list[FieldSpec] | None,
|
||
Field(description="要精确指定 sort 时用这个,格式 [{field_id, sort}];给了它就忽略 field_ids"),
|
||
] = None,
|
||
) -> str:
|
||
"""新建模板:名称 + 说明 + 有序字段选择。用 field_list 先查字段 id。"""
|
||
selection = _selection(field_ids, fields)
|
||
payload = TemplateCreate(name=name, abstract=abstract, placements=selection)
|
||
|
||
with s.session() as db:
|
||
_assert_name_free(db, payload.name)
|
||
_assert_titles_exist(db, payload.placements)
|
||
template = template_crud.create(
|
||
db,
|
||
name=payload.name,
|
||
abstract=payload.abstract,
|
||
placements=payload.placements,
|
||
)
|
||
return s.dumps(_template_row(template))
|
||
|
||
@mcp_tool(server, title="修改模板")
|
||
def template_update(
|
||
template_id: Annotated[int, Field(description="模板 id")],
|
||
name: Annotated[str | None, Field(description="新名称;不传则不改")] = None,
|
||
abstract: Annotated[str | None, Field(description="新说明")] = None,
|
||
clear_abstract: Annotated[
|
||
bool, Field(description="true 表示把说明清空")
|
||
] = False,
|
||
field_ids: Annotated[
|
||
list[int] | None,
|
||
Field(description="整组替换字段选择,按顺序编号;不传则不动大纲"),
|
||
] = None,
|
||
fields: Annotated[
|
||
list[FieldSpec] | None,
|
||
Field(description="整组替换并精确指定 sort,格式 [{field_id, sort}]"),
|
||
] = None,
|
||
) -> str:
|
||
"""修改模板名称、说明或整组字段。改字段会立刻影响所有用它的论文。"""
|
||
if name is None and abstract is None and not clear_abstract and field_ids is None and fields is None:
|
||
s.fail("没有给出任何要修改的内容")
|
||
|
||
selection = (
|
||
None if (field_ids is None and fields is None) else _selection(field_ids, fields)
|
||
)
|
||
|
||
with s.session() as db:
|
||
template = s.template_or_fail(db, template_id)
|
||
if name is not None:
|
||
_assert_name_free(db, name, exclude_id=template_id)
|
||
if selection is not None:
|
||
_assert_titles_exist(db, selection)
|
||
|
||
updated = template_crud.update(
|
||
db,
|
||
template,
|
||
name=name,
|
||
abstract=abstract,
|
||
abstract_provided=clear_abstract or abstract is not None,
|
||
placements=selection,
|
||
)
|
||
return s.dumps(_template_row(updated))
|
||
|
||
@mcp_tool(server, title="删除模板")
|
||
def template_delete(
|
||
template_ids: Annotated[int | list[int], Field(description="模板 id,或 id 数组")],
|
||
) -> str:
|
||
"""删除模板(正被论文使用的模板会被拒绝,需先给论文换模板)。"""
|
||
ids = s.id_list(template_ids)
|
||
if not ids:
|
||
s.fail("必须给出至少一个模板 id")
|
||
|
||
with s.session() as db:
|
||
_assert_not_used_by_papers(db, ids)
|
||
return s.dumps({"deleted": template_crud.delete_many(db, ids), "ids": ids})
|
||
|
||
|
||
# --- helpers -----------------------------------------------------------------
|
||
|
||
|
||
def _template_row(template: Template) -> dict:
|
||
"""One template flattened for a model: the outline is the point."""
|
||
return {
|
||
"id": template.id,
|
||
"name": template.name,
|
||
"abstract": template.abstract,
|
||
# The keys here are this interface's own vocabulary ("fields",
|
||
# "field_id"): agents call these tools with those names, so they stay
|
||
# put while the storage layer below calls the same rows titles.
|
||
"fields": [
|
||
{
|
||
"position": item.sort,
|
||
"field_id": item.title_id,
|
||
"name": item.title.name,
|
||
"level": item.title.level,
|
||
"font_size": float(item.title.font_size),
|
||
"font_color": item.title.font_color,
|
||
}
|
||
for item in template.placements
|
||
],
|
||
}
|
||
|
||
|
||
def _selection(
|
||
field_ids: list[int] | None,
|
||
fields: list[FieldSpec] | None,
|
||
) -> list[TemplateTitlePlacementInput]:
|
||
"""Turn either way of describing a selection into placement rows.
|
||
|
||
The order of ``field_ids`` is the outline order; the numbering is generated
|
||
rather than asked for, because a model that has just looked at the field
|
||
library knows what it wants in what order and not which integers to store.
|
||
"""
|
||
if fields:
|
||
return [
|
||
TemplateTitlePlacementInput(title_id=item.field_id, sort=item.sort)
|
||
for item in fields
|
||
]
|
||
if field_ids:
|
||
return [
|
||
TemplateTitlePlacementInput(title_id=field_id, sort=(index + 1) * SORT_STEP)
|
||
for index, field_id in enumerate(field_ids)
|
||
]
|
||
return []
|
||
|
||
|
||
def _assert_name_free(db: Session, name: str, *, exclude_id: int | None = None) -> None:
|
||
if template_crud.name_taken(db, name, exclude_id=exclude_id):
|
||
s.fail(f"模板名称“{name}”已存在")
|
||
|
||
|
||
def _assert_titles_exist(db: Session, fields: list[Any]) -> None:
|
||
"""Reject a selection that points at fields the library does not have.
|
||
|
||
Checked in Python rather than by a foreign key, exactly as the REST route
|
||
does: TiDB parses but does not enforce ``FOREIGN KEY``.
|
||
"""
|
||
missing = template_crud.missing_title_ids(db, [item.title_id for item in fields])
|
||
if missing:
|
||
joined = "、".join(str(field_id) for field_id in missing)
|
||
s.fail(f"字段不存在:{joined}(先用 field_list 查可用的字段 id)")
|
||
|
||
|
||
def _assert_not_used_by_papers(db: Session, template_ids: list[int]) -> None:
|
||
"""Refuse to delete a template a paper is written against.
|
||
|
||
Reported for every offending template at once, so a batch delete does not
|
||
become trial and error. The fix is a template switch on the paper, which
|
||
:func:`paper_update` does in one call.
|
||
"""
|
||
counts = paper_crud.template_paper_counts(db, template_ids)
|
||
if not counts:
|
||
return
|
||
|
||
blockers = []
|
||
for template_id, count in sorted(counts.items()):
|
||
template = db.get(Template, template_id)
|
||
name = template.name if template is not None else template_id
|
||
blockers.append(f"“{name}”({count} 篇论文)")
|
||
|
||
s.fail(
|
||
"以下模板正被论文使用,请先用 paper_update 给论文切换模板:"
|
||
+ "、".join(blockers)
|
||
)
|