课程生成器（CourseGenie）· WorkBuddy 连接器

把 PDF / PPT / 视频 / 音频 / 文本做成一门完整课程，并一键写进你本机的 Obsidian 笔记库 —— 全程在 WorkBuddy 对话里完成。

开箱即用：连接器默认连我们托管的课程生成服务，装上就能用；两项配置都可以不改。

1. 安装与配置

1.1 前置条件

1.2 安装连接器

把本目录（connector/）作为一个连接器包装入 WorkBuddy，或按 mcp.json 手动登记：

{
  "mcpServers": {
    "coursegenie": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "coursegenie-mcp==1.0.5",
        "coursegenie-mcp"
      ],
      "env": {
        "DEEPSEEK_API_KEY": "${DEEPSEEK_API_KEY}",
        "COURSE_BACKEND_URL": "${COURSE_BACKEND_URL}"
      },
      "timeout": 30000
    }
  }
}

程序本体从 PyPI 安装，走 HTTPS 且版本号钉死（==1.0.5），不在启动时下载未校验的二进制。 演示后端 http://43.134.37.110:47831 只是数据接口（无域名与证书），不下载、不执行任何代码。

token 模式（auth_mode: "token"）会弹表单，两项都可以不改：

${DEEPSEEK_API_KEY} / ${COURSE_BACKEND_URL} 与 token-schema.json 的 fields[].key 逐字对应； 凭证只存本机 ~/.workbuddy，不经过云端。

1.3 想连自己部署的后端

把「课程生成服务地址」改成你的地址即可（如 http://127.0.0.1:8000，/api 可省略）：

cd backend
.venv/Scripts/python -m uvicorn app.main:app --port 8000

# 本地开发：不走 uvx
python -m venv .venv
.venv/Scripts/pip install "mcp[cli]>=1.2,<2" httpx
set COURSE_BACKEND_URL=http://127.0.0.1:8000
.venv/Scripts/python -m course_generator          # 直接跑 stdio 服务
mcp dev course_generator/server.py                # 用 MCP Inspector 调试

2. 九个工具与调用顺序

标准链路（两个 ⏸ 是硬闸门，AI 不许自己跳过）：

upload_source → generate_outline → ⏸用户批准 → confirm_outline
  → generate_sample → ⏸用户确认样式 → generate_all → ⏸用户确认成品
  → generate_concepts → export_to_obsidian → check_task_status

30 秒约束：所有工具都在 25 秒预算内返回（内部最多等 18 秒）。批量生成、概念抽取、笔记导出是天然长任务，一律「立即返回 + 轮询」。 真模型实测：3 章 9 个知识点的课程，大纲约 45 秒、整门课批量 8–10 分钟。

3. 数据流向与凭据存储（重要，请照实理解）

日志里只记「方法 + 路径 + 状态码 + 耗时」，任何凭据、请求体、响应体都不会进日志。

自建后端并开了 AUTH_ENABLED=true 时，用环境变量 COURSE_BACKEND_API_KEY 传 API Key（本连接器支持，但不放进表单，避免与占位符的对应关系混淆）。

关于加密：默认服务地址是固定的 IP + 端口，当前走 HTTP（还没有域名和证书，所以没有 HTTPS）。 作为演示环境可以接受；正式对客户前会换成域名 + HTTPS。资料内容会经过公网明文传输，涉密材料请先把服务地址改成你自己的后端。

4. 故障排查

5. 目录结构（严格按官方规范）

connector/
├── connector-meta.json           # 元信息（name/name_zh/name_en、description 三件套、source、type、auth_mode、version、minWorkbuddyVersion、examples_zh/_en）
├── mcp.json                      # MCP 启动配置（stdio + uvx --from 发行包 + ${VAR} + timeout）
├── token-schema.json             # 凭据表单（官方 fields[] 格式，密码字段 type=password）
├── icon.svg                      # 市场图标（矢量、透明背景）
├── skills/
│   └── coursegenie/
│       └── SKILL.md              # 技能定义（YAML frontmatter + 正文）
├── README.md                     # 本文件
├── pyproject.toml                # 包定义（coursegenie-mcp）
└── course_generator/
    ├── __init__.py
    ├── __main__.py               # 入口（python -m / uvx 一致）
    └── server.py                 # FastMCP 服务 + 九个工具 + HTTP 桥接

6. 安全边界

• 凭据只从 os.environ 读；未填 Key 时不报错、只跳过自检。
• 无任何硬编码密钥、密码或机器特定路径；默认地址是公开的托管服务地址，可在表单里改。
• 一切后端异常翻译成中文 + 下一步建议，不把栈抛给 AI。
• 下载的笔记包解压时拒绝路径穿越（绝对路径 / .. 一律跳过），并拒绝软链、加密包、Windows 非法文件名与 zip 炸弹；下载体积同样有上限。
• 长任务在本地线程池执行，状态落 %TEMP%/coursegenie-mcp/tasks.json（只存任务 id 与结果摘要，不含凭据与资料正文）。

版本

• 1.0.2（2026-10-20）：默认指向托管服务、DeepSeek Key 改为可选；export_to_obsidian 改为下载到本机（vault 路径真实落地）。
• 1.0.0：首个提交审核版本。