book-mcp/docs/book-mcp-design.md

教辅处理 MCP 服务 — 方案设计

作者: 助手（Quentin 的 AI 助手） 日期: 2026-10-11 状态: 待评审

---

1. 业务目标

Agent 上传一个教辅 zip → MCP 自动解压 + 批量转 HTML + 上传对象存储 + 入库 → 后续页面可查、可看 HTML。

核心工作流

┌─ Agent 端 ───────────────────────────────────────────┐
│                                                       │
│  1) Agent: upload_zip(local_zip) → rustfs 返回 key    │
│  2) Agent: mcp.create_book(name, zip_path=key)         │
│       ↓                                               │
│     返回 {book_id, status="pending"}                   │
│                                                       │
│  3) Agent: 本地解压 zip                               │
│  4) Agent: 循环每 docx                                │
│     ├─ mcp.add_document(book_id, filename, path)     │
│     │    ↓ 返回 doc_id                                │
│     ├─ wordparse.docx_to_html(docx) → 本地 html       │
│     ├─ mcp.upload_to_rustfs(html, book/doc_id/html)  │
│     ├─ Agent 本地解析 html → structure.json           │
│     ├─ mcp.upload_to_rustfs(json, book/doc_id/json)  │
│     ├─ mcp.mark_html_ready(doc_id, html_url, stats)  │
│     └─ mcp.mark_json_ready(doc_id, json_url, ver)    │
│                                                       │
│  5) Agent: mcp.update_book_status(book_id, "done")    │
│                                                       │
└─ 后续页面 ───────────────────────────────────────────┘
│  - HTTP API 查 book / doc / file（复用 mcp 的查询类）  │
│  - 列表页：分页查 book + 每本完成进度条                 │
│  - 详情页：doc 列表 + 跳 html / json 在线预览          │
└──────────────────────────────────────────────────────┘

---

2. 数据模型

2.1 ER 关系

┌────────────┐ 1      N ┌────────────────┐ 1      N ┌──────────────┐
│  book      │─────────│  book_document │─────────│ document_file│
│  教辅      │          │  文档          │          │ 文件(多形态) │
└────────────┘          └────────────────┘          └──────────────┘

2.2 实体字段

book 教辅（zip / 套书）

字段	类型	说明
id	BIGINT PK	自增
name	VARCHAR(200)	教辅名（"2027版.曲一线3•2物理.广西版.一轮复习-突破训练"）
subject	VARCHAR(50)	学科（物理/数学/语文/...）
grade	VARCHAR(50)	年级（高三/高一/...）
version	VARCHAR(50)	版本（人教版/广西版/2027版/...）
type	VARCHAR(50)	类型（突破训练/同步训练/真题/...）
zip_path	VARCHAR(500)	原始 zip 在对象存储的路径（如 book/2027-物理-突破训练.zip）
zip_sha256	VARCHAR(64) UNIQUE	原始 zip 哈希（幂等去重）
zip_size	BIGINT	原始 zip 字节数
status	ENUM	pending / processing / done / failed / partial
total_count	INT	zip 内 docx 总数
success_count	INT	成功转 HTML 数
failed_count	INT	失败数
error_msg	TEXT	失败原因
created_at	DATETIME	创建时间
updated_at	DATETIME	处理完成时间
created_by	VARCHAR(100)	哪个 Agent / 哪个用户传
is_deleted	TINYINT	软删标记（0/1）

唯一索引: uk_name_version (name, version, is_deleted) 防同名教辅重复创建

book_document 文档（zip 里的每个 docx 一条）

字段	类型	说明
id	BIGINT PK	自增
book_id	BIGINT FK→book.id	属于哪本教辅
doc_id	VARCHAR(64) UNIQUE	本服务的核心 ID（算法见下）
original_filename	VARCHAR(200)	原始文件名
original_path	VARCHAR(500)	zip 内的相对路径
title	VARCHAR(200)	解析出的标题（如能从 docx 提取）
doc_type	ENUM	课时作业 / 周末提升 / 阶段质量评估 / 综合评估 / unknown
order_index	INT	在教辅中的顺序（按文件名排序）
status	ENUM	pending / html_ready / json_ready / failed
error_msg	TEXT	失败原因
created_at	DATETIME
updated_at	DATETIME

doc_id 生成算法（保证全局唯一 + 路径稳定）:

doc_id = sha1(f"{book_id}|{original_path}").hexdigest()[:16]
# 例: 5b3a2f1e9c0d4b7a

• 同本书同路径永远同一 doc_id
• 重复传同一 zip 不会重复入库（幂等）
• 不带敏感信息（文件名脱敏）

索引: uk_doc_id, idx_book_id (book_id, order_index)

document_file 文件（HTML / JSON / 原 docx 多产物）

字段	类型	说明
id	BIGINT PK	自增
doc_id	VARCHAR(64) FK→book_document.doc_id	关联到文档
file_type	ENUM	docx / html / json / preview_png / error_log
object_key	VARCHAR(500)	对象存储 key
object_bucket	VARCHAR(50)	桶名
size	BIGINT	字节数
checksum	VARCHAR(64)	sha256
url	VARCHAR(500)	公开 URL（如果是公开桶）
meta	JSON	附加信息：公式数、图片数、字符数等
created_at	DATETIME

索引: uk_doc_type (doc_id, file_type), idx_bucket_key (object_bucket, object_key)

一个 doc 对应 3-5 条 file 记录: 原 docx + html + json + (可选) 错误日志

---

3. 对象存储路径结构

<bucket>/
└── book/
    └── <book_id_or_slug>/              # book-{id}-{slug}
        └── docs/
            └── <doc_id>/                # sha1 短 hash
                ├── source.docx          # 原 docx（备份用）
                ├── output.html          # 转的 HTML（含 MathJax）
                ├── structure.json       # Agent 后续结构化输出
                ├── preview.png          # 可选：首页截图
                └── error.log            # 仅失败时有

优点:

• 同 doc_id 所有产物都在一个目录
• 删教辅 → 删整个 <book_id>/ 前缀
• 列表时一次 list <book_id>/docs/ 拿到全部

---

4. MCP 工具集

4.1 写入类

#	工具	签名	返回
1	create_book	(name, zip_path, subject?, grade?, version?, type?, created_by?)	{book_id, status, total_count}
2	add_document	(book_id, original_filename, original_path, zip_size?)	{doc_id, order_index, status}
3	mark_html_ready	(doc_id, html_url, html_size, stats: {formulas, images, chars})	{ok, file_id}
4	mark_json_ready	(doc_id, json_url, json_size, schema_version)	{ok, file_id}
5	mark_failed	(doc_id, error_msg, stage: "html" | "json" | "upload")	{ok, status}
6	update_book_status	(book_id, status, error_msg?)	{ok}
15	upload_to_rustfs	(local_path, key, bucket?)	{url, key, size, checksum}

4.2 查询类

#	工具	签名	返回
7	get_book	(book_id)	{book + documents[] + files[]}
8	list_books	(status?, page?, page_size?, keyword?)	{books[], total, page, page_size}
9	get_document	(doc_id)	{document + files[]}
10	list_documents	(book_id, status?, page?, page_size?)	{documents[], total}
11	get_document_files	(doc_id)	{files[]}
12	get_document_url	(doc_id, file_type: "html"|"json"|"docx")	{url, expires_in}

4.3 辅助类

#	工具	签名	返回
13	delete_book	(book_id, hard?: bool)	{ok, deleted_files}
14	retry_failed	(book_id)	{retried_count, ok, failed_count}

4.4 工具数量

• v1 最小可用: 8 个（create_book / add_document / mark_html_ready / mark_json_ready / mark_failed / update_book_status / get_book / list_books）
• v2 完整: 加 get_document / list_documents / get_document_files / get_document_url
• v3 兜底: 加 delete_book / retry_failed / upload_to_rustfs

---

5. 技术栈选型

层	选型	理由
MCP 框架	fastmcp (Python 3.13)	跟 wordparse_server.py 一致，<10 行起 server
HTTP 框架	不另起 — fastmcp 自动暴露 HTTP	省一个服务
数据库	MySQL / PolarDB	跟 jby 同栈；SQLAlchemy 2.0 + alembic
对象存储	RustFS fs.code-lab.cn（你已有）	同 wordparse
Word→HTML	复用 wordparse_server.py 的 docx_to_html	不重写，自动清洗已集成
HTML→JSON	Agent 调 LLM 自己做	复杂结构化逻辑，放业务侧
配置	YAML	跟 wordparse 一致

---

6. 项目目录

book-mcp/
├── config.yaml              # db / rustfs / 默认桶
├── book_mcp_server.py       # MCP 入口（fastmcp）
├── db/
│   ├── models.py            # SQLAlchemy ORM
│   ├── migrations/          # alembic
│   └── schema.sql           # 一份纯 SQL（给 DBA / 手动建表用）
├── services/
│   ├── book_service.py      # book CRUD
│   ├── document_service.py  # doc CRUD
│   ├── file_service.py      # file CRUD
│   └── rustfs_service.py    # 上传 / 删
├── tests/
└── README.md

---

7. 关键设计决策

问题	决策	理由
用 book_id 还是 name 查重？	name + version 唯一索引	同名教辅重复传不创建新 book
同一 zip 多次上传？	幂等（按 zip sha256 去重 book）	防呆
docx 处理失败怎么办？	book.status = "partial"，不阻塞整本	容错，UI 标黄提醒
html 公开还是私有？	公开（读教辅是低频操作）	简化 URL 生成
json 谁生成？	Agent 调 LLM	强业务相关，不放 MCP
MCP 一次返回多少文档？	list_documents 分页 50/页	防大书 OOM
数据库有没有？	独立新库 book_mcp	避免污染 jby schema
删除能级？	软删（is_deleted 字段）	防误删
后续页面怎么查？	直接调 MCP 的查询类工具（fastmcp 自动暴露 HTTP）	不写新 API

---

8. v1 范围（最小可用）

做这 8 个工具就够用了:

1. create_book — 必做
2. add_document — 必做
3. mark_html_ready — 必做
4. mark_json_ready — 必做
5. mark_failed — 必做
6. update_book_status — 必做
7. get_book — 必做
8. list_books — 必做

v2 再加: get_document / list_documents / get_document_files / get_document_url / delete_book / retry_failed

v1 不做:

• 鉴权（内网/白名单）
• 全文搜索（用对象存储 + ES 后续加）
• 文件版本管理（覆盖式）
• 异步任务队列（同步够用，每本 ~3-5 分钟）

---

9. 风险 & 备选

风险	应对
上传 1000+ docx 的大教辅会卡 Agent	add_document 一次传 1 个，避免事务过大；Agent 用并发池
docx 转 HTML 全失败（脏文件）	用之前加的 _clean_docx_xml 自动清洗
对象存储 URL 变（key 改了）	数据库记 object_key，URL 重新生成
MCP server 自己挂了	launchd 保活 + 自动重启（参考 paop gateway）

---

10. 待确认事项

待定	选项
数据库	A. 复用 jby PolarDB（questions-bank 库加表） B. 起新库 book_mcp C. 用 SQLite（开发期够用）
MCP 名字	book-mcp / exam-book-mcp / teach-assist-mcp
桶	复用 scan 还是新开 book 桶？
写入控制	要不要签名 URL（防外链）？还是公开？
MCP 端口	8080 / 8100 / 复用 8089

---

附录 A: 数据库 schema 草稿

CREATE TABLE book (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(200) NOT NULL,
    subject VARCHAR(50),
    grade VARCHAR(50),
    version VARCHAR(50),
    type VARCHAR(50),
    zip_path VARCHAR(500) NOT NULL,
    zip_sha256 VARCHAR(64) NOT NULL,
    zip_size BIGINT NOT NULL DEFAULT 0,
    status ENUM('pending','processing','done','failed','partial') NOT NULL DEFAULT 'pending',
    total_count INT NOT NULL DEFAULT 0,
    success_count INT NOT NULL DEFAULT 0,
    failed_count INT NOT NULL DEFAULT 0,
    error_msg TEXT,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    created_by VARCHAR(100),
    is_deleted TINYINT NOT NULL DEFAULT 0,
    UNIQUE KEY uk_zip_sha (zip_sha256),
    UNIQUE KEY uk_name_version (name, version, is_deleted)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE book_document (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    book_id BIGINT NOT NULL,
    doc_id VARCHAR(64) NOT NULL,
    original_filename VARCHAR(200) NOT NULL,
    original_path VARCHAR(500) NOT NULL,
    title VARCHAR(200),
    doc_type ENUM('课时作业','周末提升','阶段质量评估','综合评估','unknown') NOT NULL DEFAULT 'unknown',
    order_index INT NOT NULL DEFAULT 0,
    status ENUM('pending','html_ready','json_ready','failed') NOT NULL DEFAULT 'pending',
    error_msg TEXT,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_doc_id (doc_id),
    INDEX idx_book_order (book_id, order_index),
    CONSTRAINT fk_book_doc FOREIGN KEY (book_id) REFERENCES book(id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE document_file (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    doc_id VARCHAR(64) NOT NULL,
    file_type ENUM('docx','html','json','preview_png','error_log') NOT NULL,
    object_key VARCHAR(500) NOT NULL,
    object_bucket VARCHAR(50) NOT NULL,
    size BIGINT NOT NULL DEFAULT 0,
    checksum VARCHAR(64),
    url VARCHAR(500),
    meta JSON,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_doc_type (doc_id, file_type),
    INDEX idx_bucket_key (object_bucket, object_key),
    CONSTRAINT fk_file_doc FOREIGN KEY (doc_id) REFERENCES book_document(doc_id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

---

附录 B: 状态机

book.status 状态机:
  pending → processing → done        (全部成功)
                    └──→ partial    (有失败)
                    └──→ failed     (完全失败，异常中断)

book_document.status 状态机:
  pending → html_ready → json_ready  (正常完成)
         └──→ failed                 (任何一步失败，可重试)

---

END — 等 Quentin 确认待定项后开干。