check-course-syllabus-aa/development/REQUIREMENTS.md

课程教学大纲合规性体检 — 技能需求文档

派生自匠厂 skill-template 主仓 development/REQUIREMENTS.md，对应规格书第 4.2 节「🟣 教务处 Skill 001 —— 课程教学大纲"合规性体检"」。

---

0. 技能标识

• 拟定 slug（英文）：check-course-syllabus-aa
• 中文 name：课程教学大纲合规性体检
• 中文 description（一句话）：教师在教务系统提交新开课或修订大纲时，自动检查格式结构、课程目标与毕业要求矩阵匹配、课程思政融合度，以批注模式嵌入原 Word 文档并给出百分制体检评分
• account-manager platform_key（如有）：N/A
• 命名形态：标准型（动词-名词-部门缩写）
• 目标 OEM 市场 brands（可选）：未写则发布后仅挂匠厂（jiangchang）
• 网页 RPA（如有）— 登录策略：不适用（本技能不涉及网页 RPA）

0.1 宿主入口定位（必填）

主能力（Action id / CLI）	对话	数据管理	定时	教程章节	不挂理由
health / version / config-path	挂	不挂	不挂	入口二	默认必备
audit-syllabus	挂	row（课程大纲）	不挂	入口一/入口二	sync
batch-audit-syllabus	挂	batch（课程大纲）	不挂	入口一/入口二	async
render-html	挂	row（体检记录）	不挂	入口一/入口二	sync
sync-norm-library	挂	toolbar（编制规范）	挂（占位）	入口一/入口三	cron 占位

0.1.1 用户市场文档

• README.md：能力 / 场景 / 边界
• TUTORIAL.md：覆盖两入口（数据管理 / 对话），入口三写「占位」

0.2 AI + RPA 协作与授权边界

Agent 设计

• 用户意图：体检单份大纲 / 批量体检 / 查看报告 / 解释评分 / 同步规范
• 支持的用户意图 → Action 映射：
  • 体检单份大纲 → audit-syllabus
  • 批量体检 → batch-audit-syllabus
  • 查看报告 → render-html
  • 同步规范 → sync-norm-library
• 缺参数追问：课程名称 / 大纲 ID / 教师姓名
• 必须确认的动作：
  • batch-audit-syllabus 批量体检前确认数量与教研室范围
• 结果解释：成功（评分 + 不达标项）、部分成功（Word 批注回写失败但报告生成成功）、失败（教务 API 超时）

授权与平台边界

• 教务系统 API 凭证由教务处统一开通
• 仅读取教师本人或教务处授权的大纲文件
• 严禁逆向教务系统、破解私有协议、自动绕过审批
• OCR / NLP 模型失败时停止并上报，不擅自重试

RPA 风控设计

• 执行端：N/A

0.3 业务行生命周期

本技能对「体检记录」表中的每一条体检记录，无角色约束（一次性结果存档，不重复处理）。体检记录表仅作为审计追溯依据。

---

1. 文档目标

本文档用于明确 check-course-syllabus-aa 的研发范围、交付标准、依赖关系和验收要求。

2. 业务背景

• 现状：教师新开课或修订大纲后送审，教务处审核时常见格式不规范、课程目标与毕业要求脱节、课程思政元素流于形式等问题
• 痛点：教务处人工审核一份大纲平均 40 分钟；返工率 30%；课程思政融合度难以量化评估
• 目标：自动完成「格式结构 + 矩阵匹配 + 思政融合度」三维体检，输出「Word 批注 + 百分制评分 + 修改建议」

3. 开发目标

• 解析 Word 大纲文件（doc/docx），提取章节结构与文字
• 解析 PDF 培养方案，提取毕业要求指标点
• NLP 语义相似度匹配课程目标与毕业要求指标点
• 关键词检测 + 上下文语境分析课程思政融合度
• 输出 Word 批注（红黄绿三色）+ 百分制评分 + HTML 体检报告
• 写入业务表（课程大纲 / 体检记录 / 培养方案 / 编制规范 / 课程思政关键词）
• 完成 CLI 入口与 health / version / init-db 最小可运行验证

4. 功能范围

必须实现

• 支持 python scripts/main.py health / version / config-path / init-db
• 支持 python scripts/main.py audit-syllabus --syllabus-id <id>
• 支持 python scripts/main.py batch-audit-syllabus --major-id <id>（async）
• 支持 python scripts/main.py render-html --audit-id <id>
• 支持 python scripts/main.py sync-norm-library（async，cron 占位）
• 完成 §0.1 入口定位表，并按表落实已挂入口

可后续扩展

• 多语言教学大纲（中英双语）支持
• 课程思政案例库推荐（在评分偏低时给出融入建议）
• 跨专业毕业要求指标点合并匹配

5. 非功能要求

• 目录结构必须符合当前 skill-template 规范
• 入口必须统一为 scripts/main.py
• 用户市场四 Tab 写在根 README.md / TUTORIAL.md / DEMO.md / CHANGELOG.md
• 输出格式应尽量机读友好；错误前缀统一为 ERROR:
• Windows 环境下需保证 UTF-8 输出兼容
• 单份大纲体检耗时 ≤ 60 秒（含 Word 批注回写）

6. 输入输出要求

输入

• syllabus_id：大纲主键（必填，字符串）
• major_id：专业主键（仅 batch 必填）
• course_ids：课程 ID 列表（仅 batch 必填）
• audit_id：体检主键（仅 render-html 必填）
• 依赖系统：教务系统 API（大纲读写 + 批注回写）
• 环境变量（.env）：
  • AA_API_BASE_URL：教务系统 API 入口
  • AA_API_TOKEN：调用凭证
  • IDEOLOGY_KEYWORDS：课程思政关键词列表（JSON 数组）
  • SCORE_PASS_THRESHOLD：建议直接送审分数阈值，默认 85
  • SCORE_MODIFY_THRESHOLD：建议修改后送审分数阈值，默认 60

输出

• 成功结果：audit-syllabus 返回 {score, format_score, matrix_score, ideology_score, issue_count, audit_status}
• 错误输出：ERROR: 稳定码 + 中文 message
• 数据库记录：写入 体检记录 表
• HTML 报告：体检报告落到 html/
• Word 批注：红 / 黄 / 绿三色批注回写到原 Word 文档

7. 依赖的兄弟技能或外部系统

兄弟技能依赖

• 无强制依赖

外部系统依赖

• 教务系统 API（大纲读写 + 批注回写）：必须
• 培养方案库（PDF 文件）：必须

Python 包依赖（requirements.txt）

• Word 文档解析：python-docx>=1.0.0,<2
• PDF 解析：pdfplumber>=0.10.0
• NLP 语义相似度：sentence-transformers>=2.2.0,<3
• HTTP 请求：requests>=2.31.0,<3
• jiangchang-platform-kit 由宿主共享 runtime 提供

8. 不在本次范围内的内容

• 本次不实现课程思政案例库自动推荐（仅做关键词检测）
• 本次不实现跨专业合并匹配
• 本次不做 cron 启用（占位 Action 已就位）
• 本次不兼容旧模板历史结构

9. 验收标准

• 代码结构符合模板规范；SKILL.md slug 与 constants.SKILL_SLUG 一致
• health / version / config-path / init-db 命令执行正常
• audit-syllabus 在含 100 份大纲的样例库中完成一次完整体检，耗时 ≤ 60 秒
• 业务表写入和查询符合 references/SCHEMA.md
• Word 批注回写成功率 ≥ 95%
• SKILL.md 的 developer_ids 已配置为开发者本人匠厂用户 ID
• 已人工核验授权与技术路线
• 安装后按 §0.1 入口定位表完成宿主多入口验收

10. 开发注意事项

• 只修改当前 skill 仓库
• 教务系统 API 不可用时停止并上报
• NLP 模型权重文件较大，应通过 assets/ 或运行时下载，不入库
• cli 只做参数解析；核心逻辑在 service

11. 变更记录

日期	版本	变更人	变更内容
2026-09-14	v1.0.1	匠厂	初版需求文档，骨架就位