Marking MCP
by boyan01
README.md
# Marking MCP
Marking MCP 通过 Chrome 扩展连接阅卷页和本机的评分服务。支持九科星与合成测试平台。MCP 和 CLI 共用同一个评分引擎,原图、评分细则、转录、分数和回执归档到本地 SQLite。
## 安装与合成卷验证
需要 Node.js 24、pnpm 11 和 Chrome 136 或更新版本。
```sh
pnpm install
pnpm build
pnpm cli init-fixture ./local-fixture/config.json 32158
pnpm cli daemon ./local-fixture/config.json
```
在 Chrome 中打开 `chrome://extensions`,启用「开发者模式」,选择「加载已解压的扩展程序」,导入 `packages/extension/dist/`。升级时重新加载扩展并重启本地服务,以匹配 WebSocket 协议版本。从扩展弹窗打开侧栏并连接端口 `32158`,再打开 `http://127.0.0.1:32158/fixture/marking`。侧栏会显示租约、写入状态和日志。点击「检查当前标签页」可读取任务绑定、评分栏和图像来源。绑定和评分栏通过校验后可复制 JSON,切页或检查失败会清除旧结果。暂停会释放租约,恢复后自动寻找符合配置的标签页。
```sh
pnpm cli current ./local-fixture/config.json
```
`current` 返回证据图片的本地路径。每次读取写入独立的 `archive/current/paper-*/` 目录。
## 真实阅卷与自动连接
复制 [真实配置模板](templates/config.live.json) 和 [评分细则模板](templates/rubrics/) 到本地任务目录,按侧栏检查结果填写 `origin`、`imageOrigins`、`binding` 和各条 `criteria[].unitId`。九科星使用 `https://marking.jkxjxw.com/marking` 或 `https://jxp.jkxjxw.com/exam-marking/marking`。如果配置包含新的 HTTPS 图片来源,使用侧栏按钮授予相应站点权限。扩展核对配置的图像来源和当前文档实际加载的图片。同源图像在隔离世界保留阅卷会话凭据,跨源下载由扩展 worker 执行并省略凭据。图片字节保留在扩展侧,服务端复核格式、大小和哈希。原图请求禁止跟随重定向,每卷最多 16 MiB 和 16 张。
默认只读。获得真实提交授权后才设置 `allowLiveWrites: true`。使用旧配置做只读检查时,可给 `serve` 或 `daemon` 加 `--read-only`,覆盖配置里的写入许可。页面应使用键盘打分,扩展会在身份与分数通过提交预检后尝试关闭原生自动提交,再核验关闭状态。服务只监听 `127.0.0.1`,WebSocket 校验扩展的固定 Origin,并只给一份匹配的标签页租约。
MCP 客户端使用下列 stdio 配置,将路径替换为本机的绝对路径。一个配置端口使用 `serve` 或 `daemon` 中的一个,两者都提供本地 CLI 控制接口。
```json
{
"command": "node",
"args": ["/path/to/marking-mcp/packages/server/dist/cli.mjs", "serve", "/path/to/config.json"]
}
```
本地 CLI 会向服务核对任务键、归档绝对路径、细则哈希及调用方写许可。配置错配时返回 `CONTROL_IDENTITY_MISMATCH`。只读 CLI 向可写服务请求提交或刷新时返回 `CONTROL_WRITE_MISMATCH`。
评分前读取 [阅卷协议](prompts/grading.md)。MCP 初始化直接加载该文件。CLI 操作如下。
| 命令 | 用途 |
| ---------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `pnpm cli current <config> [reviewed]` | 读取并归档当前卷,输出原图路径。设置 `reviewed` 时读取已阅列表中的答卷。 |
| `pnpm cli call <config> <tool> [arguments.json]` | 调用工具。有成功回执但下一卷未就绪时,只重取下一卷。 |
| `pnpm cli reconcile <config> <confirmation.json> [reviewed]` | 停止服务并在交互终端确认平台保存记录。 |
| `pnpm cli export-html <config> [initial\|reviewed\|all] [output.html]` | 导出本题历史,默认包含初评与复评,输出到归档目录的 `grading-history.html`。 |
## 回执与归档
`submit_score_and_next` 需要 `paperToken`、`rubricSha256`、`transcription` 和每项评分及理由。每个原生评分栏的细则满分之和必须与平台吻合。复评从最旧答卷开始,提交时必填 `reviewed: true` 和 `reviewLimit`,可用 `reviewSkippedPositions` 指定得到明确授权的跳过位置。位置从最旧答卷按 1 计数,`reviewLimit` 仍是最后位置。遇到跳过位置时,在已阅列表手动定位到下一份要评分的答卷,并保持本批提交的跳过参数一致。扩展会核对已阅列表、原分、记录 ID 和提交数据。
服务先将 `pending` 持久化,再调用平台。成功后以已归档的 `receipt.status === "submitted"` 为准。同卷重试核对扫描卷、细则、图像哈希、原评分栏及原提交证据,复评还核对原分、位置和总数。
人工对账时,独立核对平台实际保存记录和各评分栏分数。确认文件包含 `archiveId`、`paperId`、`operator`、`platformReference` 和 `confirmedUnitScores`,分数格式是 `{ "unitId": "13", "score": 4 }` 对象的数组。有下一卷时,停在该卷并填写 `nextPaperId`,对账后需重新读取这张卷才可继续。确认末卷已保存且任务结束时填写 `taskCompleted: true`。两个字段只能填一个。终端会要求输入已保存的答卷 ID。使用复评归档时,命令末尾加 `reviewed`。
旧配置和旧细则可以直接使用。缺省 `platform` 时,`live` 默认为 `jiukexing`,`fixture` 默认为 `fixture`。旧 `token` 字段仍能读取。旧任务键、`captures`、`images`、`decisions`、`decision_events` 与恢复记录结构沿用,细则的 SHA-256 始终按原文件字节计算。HTML 按 `unitId` 展示分数,包含事件、图像和回执,可以离线打开。
## 开发
```sh
PLAYWRIGHT_SKIP_BROWSER_GC=1 pnpm exec playwright install chromium
pnpm check
pnpm build
pnpm test
```
`packages/protocol` 定义共享契约和消息。新增平台时在 `packages/adapters` 实现服务端驱动和 MAIN-world 适配器,将两者加入 `src/registry.ts`。新平台使用唯一的 `id` 作为归档命名空间。构建会从注册项生成 Chrome 主机权限,worker 仅对精确匹配阅卷路由的顶层文档执行适配器。`packages/server` 负责评分、归档和本地服务。`packages/extension` 负责租约、受限下载和侧栏。
本项目使用 GPL-3.0-only。九科星适配器的上游作者和版本见 [NOTICE](NOTICE)。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues