48f0c12fd2
Figures come out of a plotting tool at whatever size they were made. On the
paper this was written for, the sixteen of them are 1441, 1857, 2409 and 4169
pixels wide — every one wider than the 1276px column — so with no size they all
printed at the full width, and the near-square ones (1857×1986, 1974×2068) took
1365px of height, a page each. Measured in the browser, all sixteen came out at
exactly 1276px: not one of them was the size its author wanted.
`{width=…}` has been in the syntax all along, so this is the control that was
missing, not the feature. A row that is a figure now carries 宽度 in its header:
25/50/70/100%, or any value typed in — the size a panel wants is what it
measures, not a round number — with 原尺寸 as the empty value. Beside it, what
the picture will measure on the page (`原图 1857×1986 · 显示 893×955`), worked
out against the column actually rendered behind the dialog, which is the number
the writer is deciding with.
Two rules keep it honest. The value goes through `parseImageWidth` — the same
function that parses the attribute when the paper is printed — so what the
control shows is what will be printed, and a value it cannot read is refused
with the forms that work instead of stored as a size that quietly does nothing.
And the attribute is written into the sentence content by `withImageWidth`,
which edits only the first picture: the control is offered for a figure, and a
sentence with words around its picture is not one. Reading the size back out of
the content rather than keeping a copy of it in the draft means there is one
place it can be wrong instead of two.
`check-image.mjs` grows from 15 checks to 24, driving the real control: that
only figure rows offer one, that it shows what each is set to, that typing 30%
converts to 383×239 immediately, that what was typed is what gets stored, that
the paper then prints it at 30% of the column, that clearing it goes back to the
natural 480×300, and that "宽一点" is refused while the sentence keeps its size.
The MCP side of the same rule was wrong and is fixed with it: `image_upload(width=
"60")` wrote `{width=60px}`, and the reader takes a bare number as a share of the
column — `parseImageWidth` only reads pixels when the value says `px`. A model
asking for 60% got a 60-pixel figure. v7 is deployed with the corrected reading,
and smoke_mcp.py checks it.
763 lines
38 KiB
Markdown
763 lines
38 KiB
Markdown
# MCP 服务(paper-doc-mcp)
|
||
|
||
把 paper-doc 的论文、段落、句子、模板、字段库、文献库能力暴露成 **Model Context Protocol** 工具,
|
||
让 Claude Code、Codex、DeepSeek Harness(DSH)等任何 MCP 客户端直接增删改查论文。
|
||
|
||
**一句话用法**:AI 生成完整论文 → 调 `paper_write_text` 一次写入 →
|
||
用 `paragraph_write` / `sentence_update` 微调 → `paper_document` 读回来检查。
|
||
|
||
- 代码:`backend/app/mcp/`(工具实现)、`backend/scripts/mcp_server.py`(入口)
|
||
- 冒烟测试:`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`
|
||
(打包、发布、回滚见 [deploy/README.md](../deploy/README.md))
|
||
|
||
---
|
||
|
||
## 1. 快速开始
|
||
|
||
### 1.1 自检(先确认能连数据库)
|
||
|
||
```bash
|
||
cd /data/project/paper/backend
|
||
.venv/bin/python scripts/mcp_server.py --check
|
||
```
|
||
|
||
输出示例:
|
||
|
||
```
|
||
paper-doc MCP 1.0.0 (name=paper-doc)
|
||
database : mysql+pymysql://Govin:***@192.168.1.88:32738/paper_doc
|
||
rows : paper=1, template=3, paper_sentence=6, template_field_library=20
|
||
tools : 29 field=5, paper=9, paragraph=5, sentence=5, template=5
|
||
- paper_list
|
||
...
|
||
```
|
||
|
||
连不上数据库会打印失败原因并返回非 0——这是最常见的"工具调不动"根因,
|
||
所以接入任何客户端前先跑一次。
|
||
|
||
### 1.2 stdio(推荐给本地客户端)
|
||
|
||
客户端自己拉起进程,通过 stdin/stdout 讲 JSON-RPC:
|
||
|
||
```bash
|
||
/data/project/paper/backend/.venv/bin/python \
|
||
/data/project/paper/backend/scripts/mcp_server.py
|
||
```
|
||
|
||
从任何工作目录都能跑(脚本自己锚定 `sys.path`),所以客户端不需要配 `cwd`。
|
||
|
||
### 1.3 连已经在跑的那一个(k3s 里)
|
||
|
||
不用自己起进程——服务已经部署好了:
|
||
|
||
```
|
||
http://192.168.1.88:30931/mcp # 局域网 / 宿主机
|
||
http://paper-doc-mcp.paper-doc.svc.cluster.local:8931/mcp # 集群内 Pod
|
||
```
|
||
|
||
除 `/healthz`、`/readyz` 外都要带 `Authorization: Bearer <MCP_HTTP_TOKEN>`。
|
||
取口令:
|
||
|
||
```bash
|
||
export KUBECONFIG=$HOME/.kube/config
|
||
kubectl -n paper-doc get secret paper-doc-secrets -o jsonpath='{.data.MCP_HTTP_TOKEN}' | base64 -d; echo
|
||
```
|
||
|
||
自检与验证:
|
||
|
||
```bash
|
||
curl -s http://192.168.1.88:30931/readyz
|
||
cd backend && .venv/bin/python scripts/smoke_mcp.py \
|
||
--url http://192.168.1.88:30931/mcp --token '<口令>' # 47 项检查
|
||
```
|
||
|
||
### 1.4 streamable-http(自己起一个)
|
||
|
||
```bash
|
||
cd /data/project/paper/backend
|
||
.venv/bin/python scripts/mcp_server.py \
|
||
--transport http --host 0.0.0.0 --port 8931 --token '你的口令'
|
||
```
|
||
|
||
- 端点:`http://<host>:8931/mcp`
|
||
- 设了 `--token` 后,每个请求都要带 `Authorization: Bearer <口令>`,否则 `401`
|
||
- 绑定非 127.0.0.1 时会自动关掉 DNS-rebinding 保护(否则客户端用局域网域名访问会被 421),
|
||
此时**口令就是唯一的门**——不设口令会打印警告
|
||
|
||
也可以用环境变量代替参数:`MCP_TRANSPORT` / `MCP_HOST` / `MCP_PORT` / `MCP_PATH` / `MCP_HTTP_TOKEN`。
|
||
|
||
### 1.5 跑冒烟测试
|
||
|
||
```bash
|
||
cd /data/project/paper/backend
|
||
.venv/bin/python scripts/smoke_mcp.py # 自己拉起 stdio 子进程
|
||
.venv/bin/python scripts/smoke_mcp.py --url http://127.0.0.1:8931/mcp --token 你的口令 # 连已有的 HTTP 服务
|
||
```
|
||
|
||
同一个套件 **119 项检查**跑两种传输,覆盖 25 个步骤:建论文 → 看骨架 → 按标题写段落 →
|
||
定位失败时列出候选标题 → 读段落/追加带引用的句子 → 只改一句 → 删一句 → 整篇一次写入 →
|
||
读全文 → 跨论文搜索 → **另起一行**(公式独行、标记开关、搬段落时跟着走)→ **参考文献表**
|
||
(一处引用一行、一部文献一条、正文编号与表号同号)→ **插图**(传图、同一张图只存一份、
|
||
独占一行、行内图不断行、格式/尺寸/非 base64 的拒绝)→ **公式对齐**(写入、单独改、跟着搬)→
|
||
搬段落 → 清空段落 → 字段库增删改 → 建/改模板 → 换模板后正文不丢 → 文献库增删改查与批量导入 →
|
||
引用守卫(被引用的文献删不掉)→ 删模板被拒 → 删论文要确认 → 清理。写真实数据(插图那步还需要
|
||
MinIO 可用),结束时自己删干净。
|
||
|
||
---
|
||
|
||
## 2. 客户端配置
|
||
|
||
### 2.1 DeepSeek Harness(DSH)
|
||
|
||
编辑 `~/.dsh/profiles/web/cordis.patch.yml`,**新条目必须放进 `insert:` 列表**
|
||
(裸条目会被当成"覆盖已有 id",profile 里没有该 id 时只 warn 后静默跳过)。
|
||
|
||
stdio(Harness 自己拉起进程,最简单):
|
||
|
||
```yaml
|
||
- insert:
|
||
- id: mcp-paper-doc
|
||
name: '@deepseek-ai/dsh-mcp-client'
|
||
config:
|
||
serverName: paper
|
||
transport: stdio
|
||
command: /data/project/paper/backend/.venv/bin/python
|
||
args:
|
||
- /data/project/paper/backend/scripts/mcp_server.py
|
||
cwd: /data/project/paper/backend
|
||
toolCallTimeoutMs: 60000
|
||
failOnStartupError: false # 连不上也不影响 Harness 启动
|
||
```
|
||
|
||
streamable-http(服务常驻,多个客户端共用):
|
||
|
||
```yaml
|
||
- insert:
|
||
- id: mcp-paper-doc
|
||
name: '@deepseek-ai/dsh-mcp-client'
|
||
config:
|
||
serverName: paper
|
||
transport: streamable-http
|
||
url: http://127.0.0.1:8931/mcp
|
||
headers:
|
||
Authorization: Bearer 你的口令
|
||
toolCallTimeoutMs: 60000
|
||
failOnStartupError: false
|
||
```
|
||
|
||
`serverName: paper` 决定了模型看到的工具名是 `mcp__paper__paper_write_text` 这种形式。
|
||
web profile 是 `patchReload: live`,保存后通常热加载;不行就重启 dsh-web。
|
||
|
||
### 2.2 Claude Code
|
||
|
||
本地 stdio:
|
||
|
||
```bash
|
||
claude mcp add paper -- /data/project/paper/backend/.venv/bin/python \
|
||
/data/project/paper/backend/scripts/mcp_server.py
|
||
```
|
||
|
||
远程 HTTP(带口令):
|
||
|
||
```bash
|
||
claude mcp add --transport http paper http://192.168.1.88:8931/mcp \
|
||
--header "Authorization: Bearer 你的口令"
|
||
```
|
||
|
||
或者项目根目录放 `.mcp.json` 提交进仓库,团队直接共享:
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"paper": {
|
||
"type": "stdio",
|
||
"command": "/data/project/paper/backend/.venv/bin/python",
|
||
"args": ["/data/project/paper/backend/scripts/mcp_server.py"],
|
||
"env": {}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
查看与调试:`claude mcp list`、`claude mcp get paper`、会话里 `/mcp`。
|
||
|
||
### 2.3 Codex CLI
|
||
|
||
编辑 `~/.codex/config.toml`。
|
||
|
||
本地 stdio(`~/.codex/config.toml`):
|
||
|
||
```toml
|
||
[mcp_servers.paper]
|
||
command = "/data/project/paper/backend/.venv/bin/python"
|
||
args = ["/data/project/paper/backend/scripts/mcp_server.py"]
|
||
enabled = true
|
||
|
||
# 可选:数据库配置(不写就读 backend/.env)
|
||
[mcp_servers.paper.env]
|
||
# DB_HOST = "192.168.1.88"
|
||
# DB_PORT = "32738"
|
||
```
|
||
|
||
远程 streamable-http:
|
||
|
||
```toml
|
||
[mcp_servers.paper]
|
||
url = "http://192.168.1.88:8931/mcp"
|
||
bearer_token_env_var = "PAPER_MCP_TOKEN" # 口令放环境变量,别写进配置文件
|
||
enabled = true
|
||
```
|
||
|
||
命令行管理:`codex mcp list` / `codex mcp add` / `codex mcp get paper`。
|
||
|
||
> 参考:[Codex MCP Servers 文档](https://mintlify.wiki/openai/codex/configuration/mcp-servers)
|
||
|
||
### 2.4 远程(Windows 上的 Claude Code / Codex)
|
||
|
||
服务已经部署在 k3s 里,直接连它就行,客户端填:
|
||
|
||
```
|
||
URL: http://192.168.1.88:30931/mcp
|
||
Header: Authorization: Bearer <MCP_HTTP_TOKEN>
|
||
```
|
||
|
||
走 Tailscale 的机器把地址换成 `http://100.64.0.1:30931/mcp`(NodePort 在节点上监听,
|
||
两个地址都通)。
|
||
|
||
不想暴露端口的话,还有一条 SSH 包 stdio 的路子:客户端 `command = "ssh"`,
|
||
让远端执行 `mcp_server.py`,协议走 SSH 的 stdin/stdout
|
||
(见 ssh_intranet_skill 的 SSH_ASKPASS 写法)。
|
||
|
||
---
|
||
|
||
## 3. 工具参考
|
||
|
||
约定:
|
||
|
||
- 工具名即函数名;`(可选)` 的参数可以不传,其余必填。
|
||
- 返回一律是 **JSON 文本**(不是结构化对象),字段为 `None` 的一律不输出。
|
||
- 失败不是抛异常,而是 `isError: true` + 一句中日文都看得懂的说明(例如
|
||
`论文 999999 不存在`、`模板“X”已存在`、`请先用 paper_update 给论文切换模板:…`)。
|
||
|
||
### 3.1 论文 papers(9 个)
|
||
|
||
| 工具 | 作用 | 关键参数 |
|
||
|---|---|---|
|
||
| `paper_list` | 列论文(不含正文),返回 id/标题/模板/进度 | `keyword?` `status?` `template_id?` `page?` `page_size?` |
|
||
| `paper_get` | 取一篇论文的元信息与进度 | `paper_id` |
|
||
| `paper_create` | 新建论文(只写元信息) | `title`、`template_id?` `author?` `status?` `keywords?` `target_journal?` |
|
||
| `paper_update` | 改元信息 / 换模板 | `paper_id`、`title?` `template_id?` `clear_template?` `author?` `status?` `keywords?` `target_journal?` |
|
||
| `paper_delete` | 删论文(连句子引用) | `paper_ids`(int 或数组)、`confirm=true` 必填 |
|
||
| `paper_outline` | **写之前先看**:每段 position/标题/已写句数 | `paper_id` |
|
||
| `paper_document` | 读全文(`format=text` 时末尾附 Springer 格式的参考文献表) | `paper_id`、`format?`(`text`/`json`/`both`)`include_empty?` `citations?` |
|
||
| `paper_write` | **批量写段落**(按标题或位置) | `paper_id`、`paragraphs`、`mode?`(`replace`/`append`) |
|
||
| `paper_write_text` | **整篇一次写入**(Markdown 标题分段) | `paper_id`、`text`、`split?` `mode?` `strict?` |
|
||
|
||
`paper_update` 的语义:不传 = 不改;传空字符串 = 清空该文本字段;`clear_template: true` 才能把模板置空。
|
||
换 `template_id` 只是重塑标题,正文按位置留在原地,不丢。
|
||
|
||
`paper_delete` 必须先被拒一次(告诉你删掉什么、不可恢复),确认后才带 `confirm=true` 重调。
|
||
|
||
`paper_document` 的 `text` 里,正文的上标编号与末尾参考文献表的序号是**同一个号**:同一篇文献被引多次只占一个号、只列一条。
|
||
`json` 里对应的是 `references`(每条一个文献,`text` 就是排好版的条目)与 `reference_style`(当前是 `springer`),
|
||
以及 `citations`(每处引用一行,带自己的 `index`)。条目里缺哪些字段,看那条的 `missing`(如 `["卷期页码"]`),
|
||
不要自己去猜或补一个看起来合理的年份。
|
||
|
||
### 3.2 段落 paragraphs(5 个)
|
||
|
||
段落 = 位置。它由模板定义,或者由内容占据;**没有 `paragraph_create`**——往空位置写内容就是创建它。
|
||
|
||
| 工具 | 作用 | 关键参数 |
|
||
|---|---|---|
|
||
| `paragraph_list` | 段落骨架 + 预览 | `paper_id`、`include_empty?` `preview?` |
|
||
| `paragraph_get` | 读一段:拼好的正文、逐句 id/内容/引用/分隔符与换行 | `paper_id`、`position?` `heading?` |
|
||
| `paragraph_write` | 写一段(覆盖或追加) | `paper_id`、`position?` `heading?`、`sentences?` `text?` `split?` `citations?` `mode?` |
|
||
| `paragraph_delete` | 清空该段全部句子(段落仍在) | `paper_id`、`position?` `heading?` |
|
||
| `paragraph_move` | 整段搬到另一个位置(**接在目标段已有内容之后**,换行与引用一起搬过去) | `paper_id`、`position?` `heading?`、`target_position?` `target_heading?` |
|
||
|
||
定位规则:`position` 直接采用(包括模板没定义的位置,会以"未设定"渲染);
|
||
`heading` 按模板解析,忽略编号、空格和大小写,所以下面三种写法等价:
|
||
|
||
```
|
||
"1. Introduction" / "1 Introduction" / "Introduction"
|
||
```
|
||
|
||
匹配不上或匹配到多个时,错误消息里会带上**模板里真实可用的标题列表**,
|
||
模型据此改一次就能成功。
|
||
|
||
### 3.3 句子 sentences(5 个)
|
||
|
||
一句一行。改一句话不要重写整段——重写会让整段的句子 id 全变,而引用是挂在 id 上的。
|
||
|
||
| 工具 | 作用 | 关键参数 |
|
||
|---|---|---|
|
||
| `sentence_list` | 列句子(可只列某段) | `paper_id`、`position?` `heading?` `include_empty?` |
|
||
| `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` 第一步就查这件事——
|
||
少一个字段意味着模型能写、工具会静默丢掉,写作调用"成功"而内容不对。
|
||
|
||
#### 另起一行:公式、分条列举、作者行
|
||
|
||
一段是**它的句子连排**出来的,所以"不是散文的行"要自己开口。方式是在句子对象上加
|
||
`line_break_before: true`,写进去、读回来、搬走都带着:
|
||
|
||
```jsonc
|
||
{"heading": "3. Methods", "sentences": [
|
||
"本段说明公式的来历。",
|
||
{"content": "$$ E = mc^2 $$"}, // 不用标,见下
|
||
{"content": "其中 $c$ 为光速。", "line_break_before": true},
|
||
{"content": "(1)第一项;", "line_break_before": true}
|
||
]}
|
||
```
|
||
|
||
三条规则:
|
||
|
||
1. **换行顶掉分隔符,不是叠加。** 新行本身已经把两句分开了,再加一个空格会让下一行空一格。
|
||
2. **独占一行的东西不必标。** display 公式(`$$…$$` 或 `\[…\]`)和"整句只有一张图"的插图
|
||
都自己占一行——论文页面就是这么排的,`paper_document` 的 `text` 也这么排,两处必须一致,
|
||
所以模型不要去猜"这里要不要加标记"。行内公式(`$…$`)和夹在句子中间的图不算。
|
||
3. **"请读一遍这一段"时看得到换行。** `paragraph_get` / `paper_document` 返回的 `text` 里换行就是真的换行符;
|
||
`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 个)
|
||
|
||
模板就是结构:论文的标题是**每次渲染现读模板**得到的,所以改模板会影响所有用它的论文,
|
||
删模板会被拒绝(错误消息会说明有几篇论文在用、该怎么换)。
|
||
|
||
| 工具 | 作用 | 关键参数 |
|
||
|---|---|---|
|
||
| `template_list` | 列模板(含字段数) | `keyword?` `page?` `page_size?` |
|
||
| `template_get` | 取完整大纲 + 被几篇论文使用 | `template_id` |
|
||
| `template_create` | 新建模板 | `name`、`abstract?`、`field_ids?`(按顺序)或 `fields?`(`[{field_id, sort}]`) |
|
||
| `template_update` | 改名/改说明/整组换字段 | `template_id`、`name?` `abstract?` `clear_abstract?` `field_ids?` `fields?` |
|
||
| `template_delete` | 删模板 | `template_ids`(int 或数组) |
|
||
|
||
`field_ids: [2, 6, 9]` 会自动编号成 `sort = 10, 20, 30`——留出间隙,
|
||
以后想插一个字段不用重排其余所有位置。
|
||
|
||
### 3.5 字段库 fields(5 个)
|
||
|
||
字段库是"模板能用的所有标题"的目录,全局共享。编号写在 `name` 里,由人决定,系统不改写;
|
||
`level` 只影响缩进,不构成父子关系——所以同一个二级标题可以出现在多个一级标题下。
|
||
|
||
| 工具 | 作用 | 关键参数 |
|
||
|---|---|---|
|
||
| `field_list` | 列字段库(建模板前先查 id) | `keyword?` `level?` `page?` `page_size?` |
|
||
| `field_get` | 取一个字段 + 被几个模板使用 | `field_id` |
|
||
| `field_create` | 加一个标题字段 | `name`、`level?` `font_size?` `font_color?` |
|
||
| `field_update` | 改名/层级/字号/颜色 | `field_id`、`name?` `level?` `font_size?` `font_color?` |
|
||
| `field_delete` | 删字段(仍被模板使用会被拒) | `field_ids`(int 或数组) |
|
||
|
||
---
|
||
|
||
### 3.6 参考文献 references(7 个)
|
||
|
||
参考文献库是引用的另一半:句子上的 `reference_id` 指向它。建文献前**先用 `reference_list` 查重**——
|
||
`keyword` 会同时搜题名、副题名、期刊名、DOI、关键词、备注和作者名。
|
||
|
||
| 工具 | 作用 | 关键参数 |
|
||
|---|---|---|
|
||
| `reference_list` | 检索文献库(也是查重路径) | `keyword?` `type?` `year?` `cited_only?` `tag_ids?` `page?` `page_size?` |
|
||
| `reference_get` | 取一条文献的全部字段 | `reference_id` |
|
||
| `reference_create` | 新增一条 | `reference`(对象,见下)|
|
||
| `reference_update` | 改字段,只传要改的 | `reference_id`、`changes` |
|
||
| `reference_delete` | 删(被引用的会被拒) | `reference_ids`(int 或数组) |
|
||
| `reference_import` | **一次录入一批**,自动跳过重复 | `references`(数组)、`skip_duplicates?` |
|
||
| `reference_citations` | **这条文献被哪些句子引用了** | `reference_id` |
|
||
|
||
`reference_create` 的 `reference` 对象(39 个字段,全都有默认值,能填多少填多少):
|
||
|
||
```jsonc
|
||
{
|
||
"type": "journal-article", // journal-article / book / book-chapter / conference-paper /
|
||
// thesis / patent / standard / report / newspaper-article /
|
||
// web-page / dataset / software / preprint / other
|
||
"title": "题名(必填)",
|
||
"authors": [ // 顺序即印刷顺序
|
||
{"name": "Smith, John", "family_name": "Smith", "given_name": "John"},
|
||
{"name": "张三", "role": "editor"} // role: author(默认)/ editor / translator / compiler
|
||
],
|
||
"container_title": "期刊名", "volume": "12", "issue": "3", "pages": "45-67",
|
||
"publication_year": 2024, "doi": "10.1000/xyz", "url": "…",
|
||
"keywords": "…", "abstract": "…", "note": "…", "language": "en",
|
||
"isbn": "…", "issn": "…", "patent_number": "…", "standard_number": "…",
|
||
"accessed_date": "2024-05-01", "citation_key": "smith2024flood",
|
||
"tag_ids": [3, 7]
|
||
}
|
||
```
|
||
|
||
`reference_update` 的 `changes` 只写要改的字段;**传 `null` 表示清空该字段**(不传就是不动):
|
||
|
||
```jsonc
|
||
{"name": "reference_update", "arguments": {
|
||
"reference_id": 42,
|
||
"changes": {"publication_year": 2025, "doi": "10.1000/xyz-v2", "note": null}
|
||
}}
|
||
```
|
||
|
||
`authors` 和 `tag_ids` 一给就是**整体替换**(`tag_ids: []` 清空标签)。
|
||
|
||
### 3.7 文献标签 reference_tag(5 个)
|
||
|
||
标签不是分类,是标记(「必读」「方法」「待核实」)。删标签**不会**动文献——只掉标记;
|
||
删文献则要求它没被引用。
|
||
|
||
| 工具 | 作用 | 关键参数 |
|
||
|---|---|---|
|
||
| `reference_tag_list` | 列标签(含每个标签下几条文献)| `keyword?` `page?` `page_size?` |
|
||
| `reference_tag_get` | 取一个标签 | `tag_id` |
|
||
| `reference_tag_create` | 新建(名称唯一)| `name`、`color?` `note?` |
|
||
| `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?` |
|
||
|
||
```jsonc
|
||
{"name": "image_upload", "arguments": {
|
||
"data_base64": "iVBORw0KGgo…", // 也可以直接给 data:image/png;base64,…
|
||
"caption": "图 3 惯性—冲量相空间", // 不给就用 filename 的主干
|
||
"width": "70%" // 或 400px;不传按原尺寸(不超过栏宽)
|
||
}}
|
||
// → {"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 原样印在自己的行上——
|
||
文本画不出图片,而地址是"哪一张图"的唯一答案,读回来还能原样搬走。
|
||
|
||
`width` 写法宽容(`70%`、`70 %`、`{width=70%}`、`w=400px` 都收),含义严格:像素 1–4000、百分比 1–100,
|
||
超出会被拒绝而不是默默忽略——网页端读不懂的尺寸会退回原尺寸,那等于写了个不生效的值。
|
||
**只写数字按百分比算**(`60` = `60%`),和网页端一致:只有写成 `px` 才算像素,因为这是
|
||
`frontend/src/utils/rich.ts` 里 `parseImageWidth` 的读法,页面和工具必须读同一种。
|
||
|
||
同一个大小在网页端也能改:段落编辑器里,凡是"整句只有一张图"的行都会出现「宽度」下拉框,
|
||
可以选 25/50/70/100%,也可以直接填任意值(如 `63%`、`380px`),旁边实时显示这会在版面上
|
||
占多大(如 `原图 1857×1986 · 显示 893×955`)。
|
||
|
||
存储没配好(缺 `MINIO_ENDPOINT` / `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY`)时,这个工具报 503 语义的说明,
|
||
**写作路径照常**:论文、段落、句子、模板、文献都不碰对象存储。
|
||
|
||
## 4. 典型用法
|
||
|
||
### 4.1 AI 写完,整篇一次灌进去(主推)
|
||
|
||
```jsonc
|
||
// 1) 先看骨架,拿到真实标题
|
||
{"name": "paper_outline", "arguments": {"paper_id": 96}}
|
||
// → {"paper": {...}, "paragraphs": [{"position": 10, "heading": "0 Abstract", "sentences": 0}, ...]}
|
||
|
||
// 2) 把生成的论文按标题切好,一次写入
|
||
{"name": "paper_write_text", "arguments": {
|
||
"paper_id": 96,
|
||
"text": "# 0 Abstract\n摘要第一句。摘要第二句。\n\n# 1 Introduction\n引言第一句。引言第二句。\n\n## 2 Related Work\n相关工作……",
|
||
"split": "sentence" // 中文长句按 。!? 切;一行一句则用 "line"
|
||
}}
|
||
// → {"paper_id": 96, "written": [{"position": 10, "heading": "0 Abstract", "sentences": 2}, ...],
|
||
// "total_sentences": 24}
|
||
```
|
||
|
||
`split` 三种模式:
|
||
|
||
| 模式 | 含义 | 什么时候用 |
|
||
|---|---|---|
|
||
| `line`(默认) | 一行 = 一句 | 文本本身已经一行一句(最保险,不猜) |
|
||
| `sentence` | 按 `。!?` 和英文 `.?!` 切句 | 一整段挤在一行时的中文长文 |
|
||
| `paragraph` | 整段 = 一句 | 你确实想让它是一句 |
|
||
|
||
> `sentence` 会避开小数点(`3.14`)和 `et al.` / `i.e.` 这类缩写,但它仍然是"猜"。
|
||
> 想完全不猜,就直接给 `sentences` 数组。
|
||
|
||
`paper_write_text` 的正文是一整块字符串,**表达不了"这一句另起一行"**(也只有第一行能带)。
|
||
display 公式不用担心——它本来就独占一行;但分条列举、作者行这类要另起的行,
|
||
请改用 `paper_write` 给 `sentences` 数组并加 `line_break_before: true`(见 §3.3)。
|
||
|
||
标题识别两种形态:Markdown 标题行(`# 0 Abstract`),或**与模板完全同名的独立一行**
|
||
(把 `paper_outline` 的标题原样抄下来最稳)。前面没有标题的内容会被丢弃;
|
||
一个都没匹配上则整次调用报错,不会写半截。
|
||
|
||
### 4.2 分批写(更长、更可控)
|
||
|
||
```jsonc
|
||
{"name": "paper_write", "arguments": {
|
||
"paper_id": 96,
|
||
"mode": "replace",
|
||
"paragraphs": [
|
||
{"heading": "0 Abstract", "sentences": ["摘要第一句。", "摘要第二句。"]},
|
||
{"heading": "2 Related Work",
|
||
"text": "相关工作这一段我整段给。第二句在这里。",
|
||
"split": "sentence"},
|
||
{"position": 70, "sentences": [
|
||
{"content": "带引用的一句。", "citations": [{"quote": "被引用的原话", "reference_id": 12}]}
|
||
]}
|
||
]
|
||
}}
|
||
// → {"paper_id": 96, "written": [{"position": 10, "heading": "0 Abstract", "sentences": 2}, ...],
|
||
// "total_sentences": 5}
|
||
```
|
||
|
||
`mode: "append"` 改成追加,不动该段已有内容。
|
||
|
||
### 4.3 微调:只动一句话
|
||
|
||
```jsonc
|
||
{"name": "paragraph_get", "arguments": {"paper_id": 96, "heading": "1 Introduction"}}
|
||
// → {"sentences": [{"id": 501, "sort": 1, "content": "…", "separator_before": ""}, …]}
|
||
|
||
{"name": "sentence_update", "arguments": {
|
||
"paper_id": 96, "sentence_id": 501, "content": "改写后的这一句。"
|
||
}}
|
||
// → 只改这一句,其余句子 id 不变,挂在它们身上的引用不受影响
|
||
```
|
||
|
||
### 4.4 保持术语一致
|
||
|
||
```jsonc
|
||
{"name": "sentence_search", "arguments": {"keyword": "洪水损失", "limit": 20}}
|
||
// → 全库已写过的相关句子(带 paper_id / sentence_id),用来对齐说法
|
||
```
|
||
|
||
### 4.5 换模板(重塑结构但不丢正文)
|
||
|
||
```jsonc
|
||
{"name": "paper_update", "arguments": {"paper_id": 96, "template_id": 3}}
|
||
// → {"template_changed": true, ...}
|
||
{"name": "paper_document", "arguments": {"paper_id": 96, "format": "json", "include_empty": true}}
|
||
// → {"paragraphs": [{"position": 10, "heading": "摘要", "matched": true, ...},
|
||
// {"position": 70, "matched": false, ...}]} ← 新模板没有的位置仍在,标记未匹配
|
||
```
|
||
|
||
### 4.6 从零建一套模板
|
||
|
||
```jsonc
|
||
{"name": "field_list", "arguments": {"keyword": "方法", "page_size": 20}}
|
||
{"name": "field_create", "arguments": {"name": "8. Limitations", "level": 1, "font_size": 12, "font_color": "#1F1F1F"}}
|
||
{"name": "template_create", "arguments": {
|
||
"name": "期刊 A 模板",
|
||
"abstract": "投期刊 A 用",
|
||
"field_ids": [1, 2, 6, 9, 14, 18]
|
||
}}
|
||
{"name": "paper_create", "arguments": {"title": "新论文", "template_id": 4}}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.7 文献:查重 → 录入 → 引用 → 复查
|
||
|
||
```jsonc
|
||
// 1) 先查库里有没有(DOI / 题名 / 作者都能搜)
|
||
{"name": "reference_list", "arguments": {"keyword": "10.1000/xyz"}}
|
||
|
||
// 2) 没有就录;一次一批更省事(重复的会自动跳过,坏的逐条报告,不连累其它条)
|
||
{"name": "reference_import", "arguments": {"references": [
|
||
{"type": "journal-article", "title": "A flood study", "container_title": "J. Hydrol.",
|
||
"publication_year": 2023, "volume": "61", "issue": "2", "pages": "1-18",
|
||
"doi": "10.1000/xyz", "authors": [{"name": "Smith, John"}]},
|
||
{"type": "book", "title": "另一本书", "publisher": "某出版社", "publication_year": 2019,
|
||
"authors": [{"name": "张三"}]}
|
||
]}}
|
||
// → {"created":[{"id":42,…},{"id":43,…}], "skipped":[{"title":"…","existing_id":7}], "failed":[…]}
|
||
|
||
// 3) 写正文时引用它(citations 里给 reference_id 和引用的原话)
|
||
{"name": "paragraph_write", "arguments": {
|
||
"paper_id": 96, "heading": "2 Related Work",
|
||
"sentences": [{"content": "已有研究指出……", "citations": [{"quote": "引用的原话", "reference_id": 42}]}]
|
||
}}
|
||
|
||
// 4) 改稿前先看影响面:这条文献被哪些句子用了
|
||
{"name": "reference_citations", "arguments": {"reference_id": 42}}
|
||
// → {"total":2, "items":[{"paper_id":96,"position":30,"paragraph":"2 Related Work","sentence_id":512,"quote":"引用的原话"}]}
|
||
```
|
||
|
||
删文献时如果它还被引用,会被拒绝并报出「(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` 返回
|
||
`{"items": [...], "total": 1, "page": 1, "page_size": 20, "pages": 1}`。
|
||
- **失败**:`isError: true`,`text` 是人话,例如:
|
||
|
||
| 场景 | 消息 |
|
||
|---|---|
|
||
| 找不到 | `论文 999 不存在` |
|
||
| 标题对不上 | `模板里没有标题“X”。可用标题:0 Abstract(10)、1 Introduction(20)…` |
|
||
| 标题有二义 | `标题“X”匹配到多个段落(…),请写完整标题或直接用 position` |
|
||
| 删除模板被拒 | `以下模板正被论文使用,请先用 paper_update 给论文切换模板:“…”(2 篇论文)` |
|
||
| 删字段被拒 | `以下字段正被模板使用,请先用 template_update 从模板里移除:“…”(1 个模板)` |
|
||
| 删论文没确认 | `…确认无误后请带 confirm=true 重新调用` |
|
||
| 删被引用的文献 | `以下文献正被论文引用,请先在段落里移除对应引用:“…”(2 处引用)` |
|
||
| 引用了不存在的文献 | `参考文献不存在:42` |
|
||
| 给文献打了不存在的标签 | `标签不存在:9` |
|
||
| 标签重名 | `标签「必读」已存在` |
|
||
| 文献字段不合法 | `文献不合法(type):文献类型只能是:journal-article、book、…` |
|
||
| 参数写错 | SDK 层的参数校验错误(列出哪个字段不合法) |
|
||
|
||
所有消息都写成"哪里错 + 怎么修",因为读它的是模型,它据此重试一次就能成功。
|
||
|
||
- **段落拼接**:`separator_before` 是服务端算好的段间分隔符(`""` 或一个空格)。
|
||
客户端打印 `separator_before + content`,**自己不要再加空格**。
|
||
|
||
---
|
||
|
||
## 6. 设计说明(为什么是这样)
|
||
|
||
**三个入口,一个领域层。** REST API、MCP 服务、seed 脚本最终都调用 `app.crud`,
|
||
校验都过 `app.schemas`。MCP 层不重新实现任何业务规则——在 CRUD 层修的规则,
|
||
REST 和 MCP 同时生效。这让"网页里看到的"和"AI 写进去的"永远一致。
|
||
|
||
**工具结果是手搓的紧凑 JSON,不是 schema dump。** 工具结果按 token 计费,
|
||
`PaperRead.model_dump()` 会把 `created_at`/`updated_at`/四个计数字段塞进每一行。
|
||
所以 `*_row` 只挑模型真正要读的字段,`clean()` 把 `None` 全部丢掉。
|
||
|
||
**段落按 position 存储,但工具接受 heading。** `paper_sentence` 记住"我在第 7 段"
|
||
(`paper_template_filed_sort`),这是文档渲染需要的、也是换模板不丢正文的原因。
|
||
但没人知道"1. Introduction"恰好是 `sort = 20`,所以工具用 heading 也能定位,
|
||
由服务端翻译。两者都接受,冲突时以 `position` 为准。
|
||
|
||
**切句是显式选项,不是默认行为。** 项目原则是"编辑器里一行就是一句,
|
||
写入路径不切任何文本"(见 `docs/OVERVIEW.md`)。只有 `text` + `split` 这条路会切,
|
||
默认还是 `line`。已存文本永远不会被重新切分。
|
||
|
||
**换行是"要求"出来的,不是猜出来的。** `line_break_before` 只在被明确写出来时才设:
|
||
`text` 里换了一行不等于要另起一行(模型把一段话折成三行是常事),所以工具不从这里推断。
|
||
唯一的例外是 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 里没有回收站。
|
||
|
||
**结果不带结构化输出。** 工具用 `structured_output=False` 注册:
|
||
返回 `-> str` 时 SDK 会自动包一层 `{"result": ...}` 并把同一份 JSON
|
||
同时放进 `structuredContent` 和 `content`,一半客户端只读其中一个——
|
||
不如统一成文本,所有客户端都读得到。
|
||
|
||
---
|
||
|
||
## 7. 与 REST API 的对照
|
||
|
||
| 能力 | REST | MCP |
|
||
|---|---|---|
|
||
| 列论文 | `GET /api/papers` | `paper_list` |
|
||
| 建论文 | `POST /api/papers` | `paper_create` |
|
||
| 换模板 | `PATCH /api/papers/{id}` | `paper_update(template_id=…)` |
|
||
| 读全文 | `GET /api/papers/{id}/document` | `paper_document` |
|
||
| 读一段 | `GET /api/papers/{id}/paragraphs/{sort}` | `paragraph_get` |
|
||
| 整段重写 | `PUT /api/papers/{id}/paragraphs/{sort}` | `paragraph_write` |
|
||
| 加一句 | `POST /api/papers/{id}/sentences` | `sentence_add` |
|
||
| 改一句 | `PATCH /api/papers/{id}/sentences/{id}` | `sentence_update` |
|
||
| 搜句子 | —(MCP 专有) | `sentence_search` |
|
||
| 建模板 | `POST /api/templates` | `template_create` |
|
||
| 字段库 | `/api/templates/titles` | `field_*` |
|
||
| 列/搜文献 | `GET /api/references` | `reference_list` |
|
||
| 建文献 | `POST /api/references` | `reference_create` |
|
||
| 改文献 | `PATCH /api/references/{id}` | `reference_update` |
|
||
| 删文献 | `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`。
|
||
|
||
---
|
||
|
||
## 8. 排障
|
||
|
||
| 现象 | 原因 / 处理 |
|
||
|---|---|
|
||
| 客户端显示连不上、工具列表为空 | 先跑 `--check`;多数是数据库不通(`backend/.env` 的 `DB_*`) |
|
||
| HTTP 返回 401 | 口令没带或不对,检查 `Authorization: Bearer <token>` |
|
||
| HTTP 返回 421 | 绑定了非 127.0.0.1 但没走本次启动的 DNS-rebinding 关闭逻辑——确认用的是本项目入口,别包了一层反向代理改 Host |
|
||
| DSH 里工具不出现 | 检查 cordis.patch.yml 的条目是否写在 `insert:` 里;`failOnStartupError: false` 会把启动期连接失败吞掉,看 dsh-web 日志确认 |
|
||
| 工具调用超时 | 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) |
|