Chaoxing Homework Assistant MCP

超星学习通作业助手，通过 MCP (Model Context Protocol) 协议提供作业下载、AI 分析和模板填空功能。

用处

使用Agent连接此mcp,使其获得获取学习通未完成作业列表以及下载作业文件，再调用大模型分析作业完成作业，后续添加提交作业工具，实现无感完成作业

架构演变

版本	特征	状态
V1	LLM 生成完整文档	保留（降级保底）
V2	Placeholder → Text Fill（Dict[str,str]）	稳定
V3.1	Placeholder → ContentBlock[] → Renderer → DOCX	当前默认
V3.1.1	+ VSCodeScreenshotProvider（代码编辑器截图）	稳定
V3.1.2	+ 行号随机化 / 文件名智能推断 / 面包屑 / 状态栏	稳定
V3.1.3	+ 统一行容器（行号/代码 1:1 锁死）	稳定
V3.2	+ HarmonyPageProvider + PageTemplateRegistry	稳定
V3.2.1	+ Visual DSL / Component Registry / 复合组件	稳定
V3.3	+ ScreenshotIntentAnalyzer + 路由决策 + 命中率统计	当前
V3.3.1	+ SemanticPlaceholderDetector（语义识别待填写区域）	当前

功能

工具	说明
get_unfinished_homeworks	获取所有课程中待做的作业列表
get_homework_detail	获取作业详情和附件信息
download_homework_attachments	下载作业附件到本地
analyze_homework	解析附件模板，调用 AI 生成填充内容
generate_homework_docx	将 AI 结果回填到 DOCX 模板
health_check	检查 MCP 服务健康状态

安装

git clone <repo-url>
cd chaoxing_mcp
pip install -r requirements.txt

额外依赖：

pip install olefile      # 旧版 .doc 文件支持
pip install ddddocr      # 学习通反爬验证码识别
pip install playwright   # V3 图片生成
playwright install chromium

配置

复制 .env.example 为 .env，填入 API 密钥：

ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx
CLAUDE_MODEL=claude-sonnet-4-20250514
MCP_MODE=fastmcp

支持 DeepSeek 等兼容 API：

ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
ANTHROPIC_API_KEY=sk-xxxxxxxxxxxxxxxx

启动

# Windows
run_server.bat

# 或直接
.venv\Scripts\python.exe -m src.main

生成模式（Feature Flag）

set GENERATION_MODE=v3_3     # V3.3: Screenshot Intelligence Engine + Semantic Detection
set GENERATION_MODE=v3_2_1   # V3.2.1: Visual DSL + Component Registry
set GENERATION_MODE=v3_1     # V3.1: ContentBlock 架构（默认）
set GENERATION_MODE=v2       # V2: 模板填空（原默认）
set GENERATION_MODE=v1       # V1: 完整文档生成（降级保底）

V3 图片 Provider 体系

ScreenshotIntentAnalyzer
    ├── VSCODE_CODE (99%)     → VSCodeScreenshotProvider    编辑器截图
    ├── TERMINAL_OUTPUT (99%) → TerminalScreenshotProvider  终端输出截图
    ├── FLOWCHART (99%)       → MermaidProvider             流程图
    ├── ARCHITECTURE (99%)    → MermaidProvider             架构图
    ├── ER_DIAGRAM (99%)      → MermaidProvider             ER图
    ├── DATABASE_TABLE (90%)  → MermaidProvider             数据库表
    ├── UI_SCREEN (80%)       → SemanticUIProvider          未知界面自动构建
    └── UNKNOWN (fallback)    → SemanticUIProvider          兜底

V3.3.1 语义占位符检测

从「检测空白区域」升级为「检测所有待填写区域」：

检测规则	示例触发文本	生成类型
CODE	[pages/Index.ets实现源码] （代码截图）	CODE / IMAGE
SCREENSHOT	页面效果截图： （截图）	IMAGE
QUESTION_ANSWER	答： 思考题	TEXT
SUMMARY	[200字左右实验总结] 结论与体会	TEXT
TEACHER_COMMENT	七、教师评语	IGNORE

快速测试

# V3.1 端到端测试
python tests/run_v31.py

# V3.3 端到端测试（ScreenshotIntentAnalyzer + Routing）
python tests/test_v33_real.py

# V3.3.1 实验3（HarmonyOS 购物车）
python tests/test_v331.py

# V3.3.1 实验8（Go 协程池）
python tests/test_exp8.py

修改测试脚本顶部的 WORK_ID、UID、COURSE_NAME 来测试不同作业。

项目结构

src/
├── auth/                    # 登录鉴权
├── clients/                 # 学习通 / Claude API 客户端
├── models/                  # 领域模型
│   ├── content_block.py            # V3: ContentBlock/TextBlock/CodeBlock/ImageBlock
│   ├── template_model.py           # V2: Placeholder/FillResult
│   ├── visual_dsl.py               # V3.2.1: 12原始+5复合组件+VisualPage
│   ├── visual_intent.py            # V3.2.1: 6种通用布局类型
│   ├── screenshot_intent.py        # V3.3: 8种ScreenshotType+ROUTE_MAP
│   └── semantic_placeholder.py     # V3.3.1: PlaceholderType+FillRegion
├── parsers/                 # 文件解析（DOCX/PDF/TXT/DOC）
│   └── docx_parser.py             # 4级fallback: python-docx/olefile/OOXML-zip
├── server/                  # MCP Server
├── services/                # 业务逻辑
│   ├── image_generation_service.py  # V3: Provider架构(6种Provider)
│   ├── block_renderer.py            # V3: 注册表模式渲染器
│   ├── placeholder_semantic_analyzer.py  # V3: 语义分析→块类型建议
│   ├── screenshot_intent_analyzer.py     # V3.3: 截图意图识别
│   ├── screenshot_routing_service.py     # V3.3: 路由决策+命中率统计
│   ├── semantic_placeholder_detector.py  # V3.3.1: 语义占位符检测
│   ├── placeholder_merge_service.py      # V3.3.1: 合并去重
│   ├── semantic_ui_provider.py           # V3.3: 未知界面自动构建
│   ├── ui_renderer.py                   # V3.2.1: ComponentRegistry+HTML
│   ├── visual_intent_analyzer.py         # V3.2.1: 布局意图识别
│   ├── fill_task_builder.py             # Prompt构建+截图强制规则
│   ├── analysis_service.py              # V1分析服务
│   └── blank_detector.py                # 空白区域检测
├── storage/                 # 本地文件存储
├── template/                # 模板引擎（V2/V3）
│   ├── placeholder_filler.py        # 占位符回填+fill_blocks
│   ├── placeholder_detector.py      # 占位符检测
│   └── template_converter.py        # 空白→占位符转换
├── tools/                   # MCP 工具实现
├── transport/               # MCP 传输层
└── workflow/                # 工作流编排
    └── complete_homework_flow_v2.py   # V2/V3.1/V3.3 工作流
templates/
└── harmony/                 # V3.2: HarmonyOS页面模板
    └── shopping_cart.html            # 购物车页面
assets/
└── highlight/               # V3.1.1: 本地highlight.js
tests/                       # 测试脚本
tmp/
├── downloads/               # 下载的附件
├── generated/               # 生成的 DOCX
│   └── images/              # 生成的图片（PNG）
└── cache/                   # 登录缓存