MoeReview

给 MCP Agent 用的本地优先学习工作台
让 Agent 负责思考，让浏览器负责稳定承载学习流程。

English · 简体中文

_{访问计数 · 第三方 Moe Counter 请求次数，非 GitHub 官方 Traffic}

这不是又一个“聊天窗口套壳”。MoeReview 更像一台学习机甲的驾驶舱：Agent 负责推理和教学，Hub 负责稳定连接，Web UI 负责沉淀、做题、回看和交互。

✦ 产品预览

_{结构化学习分页 · 测验与即时解惑 · 围绕当前上下文持续协作}

✦ 它解决什么问题

很多 AI 学习工具把讲解、题目、答案、状态和提醒全部塞进聊天记录。MoeReview 将学习流程拆成稳定、可回看的界面层：

• 沉淀：长期有价值的内容进入学习分页。
• 引导：临时状态和下一步建议进入右侧面板。
• 互动：Agent 可以等待用户在网页中答题或发消息。
• 延续：Agent 下线后，网页仍可打开并回看历史。

不要让 Agent 的生命周期绑架学习界面的稳定性。

✦ 功能亮点

• 常驻 MoeReview Hub，Web 页面不依赖 Agent 启动。
• 临时 MCP Agent Adapter，只负责把 MCP 工具调用转发给 Hub。
• 会话级历史：学习分页、收藏、错题、问答历史、活动日志。
• 测验页面、答案收集、结果页和错题沉淀。
• 右侧 Guidance Panel 展示临时状态、短建议和下一步。
• 无 Agent 时也能进入欢迎页和回看历史。
• 默认本地存储，不需要账号或云服务。

⌁ 架构

flowchart LR
    Agent["✦ Agent"] <-->|stdio| Adapter["MCP Adapter"]
    Adapter <-->|HTTP| Hub["MoeReview Hub"]
    Hub <-->|HTTP / WebSocket| Web["Browser UI"]

    classDef pink fill:#fff0f8,stroke:#ff8fcf,color:#3b2633,stroke-width:2px;
    classDef mint fill:#ecfbf8,stroke:#43b3ae,color:#183b39,stroke-width:2px;
    classDef violet fill:#f3f0ff,stroke:#8b7cf6,color:#302a55,stroke-width:2px;
    classDef neutral fill:#f7f8fb,stroke:#9aa3b2,color:#252a33,stroke-width:2px;
    class Agent pink;
    class Adapter violet;
    class Hub mint;
    class Web neutral;

MoeReview 后端拆成两个角色：

• MoeReview Hub：常驻 HTTP/WebSocket 服务，负责网页、会话、历史、连接状态和事件路由。
• MCP Agent Adapter：临时 MCP stdio 服务，负责注册 Agent，并把工具调用转发到 Hub。

这样做的直接收益是：重启 Agent、切换 Agent、结束 Agent 对话，都不会导致网站不可访问。

⌁ 目录结构

.
+-- mcp-server/              # MoeReview Hub 和 MCP Agent Adapter
|   +-- src/hub.ts            # Hub 入口
|   +-- src/index.ts          # MCP Adapter 入口
|   +-- src/ws/server.ts      # HTTP / WebSocket / API / 路由
|   +-- src/tools/            # MCP 工具实现
+-- web/                     # React + Vite 前端
+-- skills/
|   +-- moereview-agent/      # 可选 Codex skill：约束 Agent 正确使用 MoeReview
+-- docs/                    # 设计文档
+-- scripts/                 # 本地快速启动与检查脚本
+-- start.cmd                # Windows 双击启动入口
+-- README.md                # 中文文档
+-- README.en.md             # 英文文档

◇ 环境要求

• Node.js 20.19+，或 22.12+
• npm
• 一个支持 MCP 的 Agent / 客户端

当前项目优先服务本地单用户场景。账号系统、云同步、权限模型都还没引入。

OS 与版本、Shell、CPU 架构
node --version、npm --version
Agent/客户端名称与版本
是否支持 MCP stdio
是否原生支持 SKILL.md 或其他项目规则机制

node --version
npm --version
npm run setup
npm run build

name: moereview
transport: stdio
command: node
args: [<repo-absolute-path>/mcp-server/dist/index.js]

[mcp_servers.moereview]
command = "node"
args = ["<repo-absolute-path>/mcp-server/dist/index.js"]

npm run start:no-open

npm --prefix mcp-server run hub

◇ 快速启动

Windows 用户可以直接双击：

start.cmd

或者在仓库根目录运行：

npm run start

这会自动：

1. 检查 Node.js 和 npm。
2. 安装缺失的 web / mcp-server 依赖。
3. 构建前端和后端。
4. 检查 3456 端口。
5. 打开浏览器。
6. 启动 MoeReview Hub。

如果只想检查环境：

npm run check

如果不想自动打开浏览器：

npm run start:no-open

快速启动脚本不会自动 kill 端口占用者。如果 3456 被占用，请手动停止旧进程，或者使用：

.\scripts\start.ps1 -Port 4567

◇ 安装与构建

安装依赖：

cd mcp-server
npm install

cd ../web
npm install

构建前端：

cd web
npm run build

构建 Hub / MCP Adapter：

cd ../mcp-server
npm run build

如果你从仓库根目录开始，可以按这个顺序执行：

cd web
npm run build
cd ../mcp-server
npm run build

◇ 启动 Hub

Hub 默认监听 3456 端口，并托管已经构建好的 web/dist。

cd mcp-server
npm run hub

然后打开：

http://localhost:3456

没有 Agent 连接时，MoeReview 仍然可以正常打开，进入欢迎页或回看历史会话。

如果要换端口：

$env:MOEREVIEW_HUB_PORT="4567"
npm run hub

⌁ 配置 MCP Adapter

构建 mcp-server 后，在你的 MCP 客户端里配置：

node <repo>/mcp-server/dist/index.js

示例：

{
  "mcpServers": {
    "moereview": {
      "command": "node",
      "args": ["<absolute-path-to-repo>/mcp-server/dist/index.js"]
    }
  }
}

把 <absolute-path-to-repo> 替换成你本地 clone 的仓库路径。

推荐启动顺序：

1. 构建 web 和 mcp-server。
2. 运行 npm run hub 启动 Hub。
3. 启动支持 MCP 的 Agent / 客户端。
4. 打开 http://localhost:3456。

skills/moereview-agent/

Use $moereview-agent

skills/moereview-agent/SKILL.md

# MoeReview Web-First Study Workspace

如果 MoeReview MCP 工具可用，复习、讲解、出题、批改、总结前必须使用 `$moereview-agent`。
实质学习内容写入 MoeReview pages / quiz / result / guidance，Agent 聊天只保留短状态和错误说明。
需要用户继续操作时使用 `enter_standby`，让用户留在 Web UI。

prepare_turn
update_workspace

show_quiz
enter_standby
show_result

{
  "results": [
    {
      "id": "q1",
      "verdict": "partial",
      "score": 0.5,
      "maxScore": 1,
      "user_answer": "用户答案",
      "correct_answer": "参考答案",
      "explanation": "方向正确，但关键步骤不完整。"
    }
  ],
  "summary": {
    "time_spent": 120,
    "feedback": "整体反馈",
    "grading_notes": "可选的自然语言批改说明"
  }
}

✦ 核心交互模型

Pages：长期学习记录

适合放进 page 的内容：

• 知识点讲解
• 结构化总结
• 测验题
• 测验结果
• 错题复盘
• 学习计划
• 重要修订

不适合放进 page 的内容：

• “好的”
• “我正在处理”
• 临时建议
• 工具状态
• 一句话提醒

Guidance Panel：右侧临时引导

适合放到侧栏的内容：

• 当前状态
• 下一步建议
• 操作提示
• 等待用户输入的说明
• 轻量警告

目标是让用户不打开 Agent 聊天窗口，也知道当前该做什么。

Agent 等待与唤醒

MCP 不能反向唤醒一个已经结束的 Agent turn。MoeReview 因此明确区分状态：

只有 waiting 可以被 Web 输入立即唤醒。
idle 和 working 状态下，Web 消息会进入队列，等待 Agent 下一轮调用 get_pending_messages。

◇ 常用命令

前端：

cd web
npm run dev
npm run build
npm run lint
npm test

✦ 主题系统

顶部栏的主题设置提供两种模式：

• 快速：切换六套内置主题、明暗模式、强调色、三类字号、密度、内容宽度和动效。
• 实验室：编辑完整 Token、组件变体和布局，也可使用 JSONC 源码与作用域 CSS。

实验室会先复制内置主题，不会直接修改预设。自定义主题支持撤销、重做、20 条快照、导入导出和恢复。主题损坏时可访问 /?safe-theme=1，或在启动时按住 Shift 进入安全模式。

新增主题及公开 Token/选择器说明见 主题开发指南。

后端：

cd mcp-server
npm run build
npm run hub
npm run dev:hub
npm run start

注意：npm run start 启动的是 MCP Adapter，不是 Hub。

⌁ 本地数据

MoeReview 默认把运行时数据放在用户目录：

~/.examforge/

会话数据包括：

• meta.json
• pages.json
• favorites.json
• wrong_answers.json
• qa_memory.json
• activity_log.json
• message_queue.json
• guidance.json

这些数据不应该提交到 Git。

※ 常见问题

3456 端口被占用

Hub 不会自动 kill 端口占用者。请手动停止旧进程，或者设置 MOEREVIEW_HUB_PORT。

Hub 打开了，但不是完整 Web UI

通常是还没构建前端：

cd web
npm run build

然后重启 Hub。

MCP 工具提示 Hub 未启动

先启动 Hub，再启动 MCP Adapter：

cd mcp-server
npm run hub

前端发消息后 Agent 没反应

看会话状态：

• waiting：应该能立即唤醒。
• idle：消息已入队，Agent 下一轮读取。
• working：消息已入队，等待 Agent 忙完。
• disconnected：需要重启 MCP Adapter。

◇ 开源前状态

MoeReview 仍在快速迭代中，API 和目录结构可能继续变化。当前最重要的设计原则是：

Web 工作台必须独立于 Agent 生命周期稳定运行。

后续适合补：

• 一键启动脚本
• 连接诊断面板
• pending message 数量提示
• standby 取消 / 延长机制
• 自动生成 MCP 工具文档

License

本项目使用 GNU General Public License v3.0。