ebaf9e558b
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.
757 lines
37 KiB
Markdown
757 lines
37 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,
|
||
超出会被拒绝而不是默默忽略——网页端读不懂的尺寸会退回原尺寸,那等于写了个不生效的值。
|
||
|
||
存储没配好(缺 `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) |
|