MoeReview

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

产品预览

Related MCP server: codebase-memory-mcp

目录

• 产品预览

• 它解决什么问题

• 功能亮点

• 架构

• 目录结构

• 环境要求

• Agent 自动配置指南

• 快速启动

• 安装与构建

• 启动 Hub

• 配置 MCP Adapter

• 可选 Agent Skill

• 核心交互模型

• 常用命令

• 本地数据

• 常见问题

• 开源前状态

它解决什么问题

很多 AI 学习工具把所有东西都塞进聊天记录里：讲解、题目、答案、状态、提醒混在一起。MoeReview 的思路是把学习流程拆成更稳定的界面层：

• 长期有价值的内容进入学习分页。

• 临时说明和下一步建议进入右侧引导面板。

• Agent 可以等待用户在网页里答题或发消息。

• Agent 下线后，网页仍然能打开并回看历史。

换句话说：不要让 Agent 的生命周期绑架学习界面的稳定性。

功能亮点

• 常驻 MoeReview Hub，Web 页面不依赖 Agent 启动。

• 临时 MCP Agent Adapter，只负责把 MCP 工具调用转发给 Hub。

• 会话级历史：学习分页、收藏、错题、问答历史、活动日志。

• 测验页面、答案收集、结果页和错题沉淀。

• 右侧 Guidance Panel 展示临时状态、短建议和下一步。

• 无 Agent 时也能进入欢迎页和回看历史。

• 默认本地存储，不需要账号或云服务。

架构

Browser UI  <-- HTTP / WebSocket -->  MoeReview Hub  <-- HTTP -->  MCP Agent Adapter  <-- stdio -->  Agent

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 / 客户端

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

Agent 自动配置指南

本节专供 Agent 执行。MCP 的 stdio 接入方式可以跨客户端复用；Skill 并非统一行业标准，必须先探测当前 Agent 的能力，再选择安装、引用或规则降级方案。

执行约束

• 先定位仓库根目录，并把配置中的路径转换为绝对路径。

• 先读取官方客户端文档或已有配置，确认 MCP 与 Skill 的格式和位置；无法确认时停止修改并报告，不要猜测。

• 修改配置时只合并 MoeReview 条目，禁止覆盖其他 MCP Server、Skill、Rules 或用户设置。

• 不提交依赖目录、构建产物、密钥或用户级 Agent 配置。

• 不要启动第二个 Hub；如果 http://127.0.0.1:3456/health 已可访问，直接复用。

1. 探测环境与能力

开始前记录以下信息：

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

完整项目要求 Node.js ^20.19.0 或 >=22.12.0。如果版本不满足：

• 优先使用机器上已有的 Node 版本管理器升级到当前 LTS。

• 没有版本管理器时，使用该操作系统的官方/可信包管理器或 Node.js 官方安装方式。

• 涉及管理员权限、GUI 安装或改变全局运行时且当前 Agent 无权执行时，停止自动安装，向用户给出对应系统的最短操作步骤。

不要改用 pnpm、Yarn 或 Bun；本仓库提交了 npm lockfile。Windows 使用 PowerShell，macOS/Linux 使用当前 POSIX Shell 即可完成依赖与构建。

2. 安装并构建

所有平台均在仓库根目录执行：

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

任一命令失败时先报告实际错误，不要继续写入 MCP 配置。

3. 配置 MCP Adapter

以下是跨客户端不变的 MCP 契约：

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

Codex 用户将以下内容合并到 $CODEX_HOME/config.toml；未设置 CODEX_HOME 时使用 ~/.codex/config.toml：

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

将占位符替换为真实绝对路径。Windows TOML 路径建议使用 /，例如 E:/WebProject/LearnBuddy/MoeReview/mcp-server/dist/index.js。其他客户端必须根据其官方格式表达同一份契约；不要直接套用 Codex 的配置路径或字段名。

4. 按能力接入 Skill

Skill 源文件是 <repo>/skills/moereview-agent/SKILL.md。按当前 Agent 能力选择且只选择一种方案：

1. 原生支持 SKILL.md：按该客户端官方方式安装整个 skills/moereview-agent 目录。Codex 安装到 $CODEX_HOME/skills/moereview-agent，默认位置为 ~/.codex/skills/moereview-agent。

2. 支持 Rules/Instructions，但不支持 Skill：读取 SKILL.md 及其直接引用的必要文件，将规则接入该客户端官方的项目级指令机制，并保留“仅在使用 MoeReview 时生效”的范围。

3. 两者都不支持：不要伪造 Skill 安装。每次 MoeReview 会话开始前读取 SKILL.md 作为操作协议，并向用户说明该规则不会被客户端自动持久加载。

更新已有安装时只同步 moereview-agent，不得删除其他 Skill 或规则。原生安装后确认目标目录中的 SKILL.md 存在且可被客户端发现。

5. 启动 Hub

Hub 是独立常驻进程，必须在独立持久终端或受控后台进程中启动。

Windows：

npm run start:no-open

macOS/Linux：

npm --prefix mcp-server run hub

npm run build 已生成 Hub 所需的 Web 与 Server 构建产物。若使用非默认端口（例如 4567），给 Hub 设置 MOEREVIEW_HUB_PORT=4567，并在 MCP Adapter 配置中设置 MOEREVIEW_HUB_URL=http://127.0.0.1:4567；环境变量字段名按客户端官方格式填写。

6. 验收与报告

重新加载 Agent 的 MCP/规则配置后依次验证：

1. http://127.0.0.1:3456/health 可访问。

2. MCP Server moereview 已连接且能列出工具。

3. 调用 prepare_turn 能返回绑定状态。

4. 原生 Skill 客户端能发现并调用 moereview-agent；Rules 方案确认规则已加载；临时读取方案明确记录其非持久性。

完成后向用户简要报告：OS、Node/npm 版本、构建结果、Hub 状态、MCP 配置位置、采用的 Skill 方案及四项验收结果。不得把“读取过 Skill”误报为“已原生安装 Skill”。

快速启动

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。

可选 Agent Skill

仓库内提供了一个可选 Codex skill：

skills/moereview-agent/

它不规定教学方法，不干涉讲解风格。它只约束 Agent 如何正确使用 MoeReview：

• 显式绑定会话。

• 每轮开始读取 pending messages。

• 真实地区分 idle / waiting / working / disconnected。

• 把讲解、总结、出题、批改和复习计划优先渲染到 MoeReview Web UI，而不是只写在 Agent 聊天里。

• 只有有长期回看价值的内容才创建 page。

• 临时状态和下一步建议放到侧边栏 guidance。

如果你的 Agent 支持显式 skill 调用，可以使用：

Use $moereview-agent

或者直接指向：

skills/moereview-agent/SKILL.md

如果你的 Agent 不会自动选择 skill，MoeReview 不能从 Hub 侧强制模型调用 MCP 工具。推荐在具体复习目录放一个 AGENTS.md，把 MoeReview 设成默认 Web-first 工作区，例如：

# MoeReview Web-First Study Workspace

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

这类工作区默认指令能减少每次手动输入 Use $moereview-agent 的次数。

性能优化工具

为了减少 MCP 往返，Agent 应优先使用两个聚合工具：

• prepare_turn：一次返回绑定状态、pending Web 消息和轻量 session snapshot，替代常见的 get_binding_status + get_pending_messages + 小范围 get_session_snapshot。

• update_workspace：一次批量更新普通 pages、guidance、progress、toast、dashboard，替代多次 show_card/create_pages + set_guidance_panel + set_progress。

推荐普通学习轮次：

prepare_turn
update_workspace

测验和批改仍然使用专用工具：

show_quiz
enter_standby
show_result

结果页与修正工具

show_result 是 MoeReview 的专用结果页工具，不是普通文本页。Agent 必须传结构化逐题结果，Hub 会根据逐题字段自动计算正确率。

每题至少需要提供以下任一种判分信息：

• correct: true | false

• verdict: "correct" | "partial" | "wrong" | "skipped"

• score + maxScore

自然语言批改不要放进 results 数组；应放到 summary.feedback 或 summary.grading_notes。否则结果页无法可靠统计，也容易误导用户。

示例：

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

如果已经发布的结果页或学习页有实质错误：

• 用 correct_result 修正结果页。必须提供具体 reason，旧页会标记为 superseded，新页作为修订版追加。

• 用 supersede_page 作废严重错误、重复或误导性的页面。必须提供具体 reason。

这两个工具用于少数纠错场景，不用于普通措辞润色或无理由改写历史。

核心交互模型

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。