发布百家课堂教程
将教程文件夹发布到百家课堂。本技能可在两种环境运行，先判断环境再选路径：
| 判断条件 | 环境 | 发布方式 |
|---|---|---|
可访问 ~/.qwenworkcn/skills/publish-baijia-course/scripts/ 且能运行 Bash |
本机桌面 | 走 A：封装脚本（自动处理 WAF 桥接、base64、stdio 时序） |
| 云端沙箱（钉钉 App 千问办公 / 豆包工作 / WorkBuddy 等），已配置 industry-mcp 连接器 | 云端智能体 | 走 B：MCP 直连，files 传 base64 |
路径规则（重要）：教程文件夹路径只在文件所在环境有效——
本机制作的教程只能在本机发布；云端生成的教程在云端发布。
跨环境路径（云端引用本机路径、或反之）必然失败，此时告知用户把教程
文件夹放到当前环境（重新生成或上传），不要尝试直接发布。
通用规则（两种环境都适用）
教程文件夹硬性规格（发布前逐项核对）
- 文件数 ≤ 20，文件夹总大小 ≤ 10MB
- 至少一个 HTML 文件（入口默认
index.html），单个 HTML ≤ 100KB - 单张图片 ≤ 150KB（超限先压缩：本机
sips -Z 1080 -s format jpeg，
云端用沙箱内可用的图片工具或 PIL）
发布流程（顺序固定）
- 拟发布参数并向用户确认（发布前必做，不可跳过）：
先根据教程内容拟好完整参数，一次性列表展示给用户确认：
| 参数 | 拟定方式 |
|---|---|
| 标题（≤100 字） | 取教程文件夹名或教程页面标题 |
| 简介（≤2000 字） | 概括内容、适合人群、能学到什么，1-3 句话 |
| 等级 | 初级/中级/高级（入门科普=初级，有实操步骤=中级，进阶原理/开发=高级） |
| 类别 | 先查最新合法类别（本机跑 categories 子命令；云端调 course_categories 工具），按内容选最贴切的，不贴切才归「其他」 |
用 AskUserQuestion（或列表询问）展示全部参数，明确问「是否按以上参数发布？」；
用户调整任何一项后重新展示确认。用户确认前禁止执行发布。
2. 执行发布（见下方 A/B 分支）。
3. 审核（仅管理员账号；普通用户跳过，等平台审核）：
发布后询问用户是否立即审核通过。course_review 的 id、status
（approved/rejected）、reason 三项均必填。
4. 汇报：课程 id、状态、上线地址（返回 JSON 的 url 字段）、
积分奖励（审核通过 +10 积分）。
署名规则
--agent（本机）/ 等效参数（云端）必传：填入当前调用本技能的智能体
自身产品名（如「千问办公」「豆包工作」「WorkBuddy」），在简介末尾追加
「（XX整理）」署名（名称已含「整理」二字时不重复追加），
标记教程由哪个智能体整理发布。脚本/调用方无法自行感知身份，必须显式传入。
路径 A：本机桌面（封装脚本）
所有桥接细节（WAF 绕行、base64 编码、stdio 时序）已封装在
scripts/publish_course.py，直接执行，勿手工拼 JSON-RPC。
前置条件：桥接器 ~/.qwenworkcn/mcp-bridges/industry-bridge/bridge.js
就绪；~/.qwenworkcn/mcp.json 的 mcpServers.industry-mcp.env.MCP_TOKEN
含 course:write scope（审核另需 course:review）。不确定时先跑 status。
发布（预检不通过会列出问题并退出）：
python3 <skill目录>/scripts/publish_course.py publish "<教程文件夹绝对路径>" \
--title "教程标题" \
--desc "教程简介" \
--agent "调用方智能体名称" \
--level 初级 \
--category 其他
审核：review <课程id> --status approved --reason "理由"；
查类别：categories；查令牌：status。
脚本内部等待约 60-90 秒属正常；报「未收到响应」可原样重试一次。
路径 B：云端智能体（MCP 直连）
适用：云端沙箱已配置 industry-mcp 连接器（含 course:write 的令牌），
且教程文件在当前沙箱内。
第 1 步：连通性预检。先调一次轻量工具（如 course_categories）：
- 正常返回 → 继续第 2 步
- 连接失败 / 超时 / 403 → 大概率是站点 WAF 拦截了云端出口或令牌未配置，
停止并告知用户：本环境无法直连，需在本机发布（走路径 A），或让管理员
将云端出口 IP 加白名单。不要反复重试。
第 2 步：读文件并 base64。遍历教程文件夹内所有文件（含子目录），
每个文件转成 {"path": "文件夹内相对路径", "contentBase64": "<base64>"}。
文件多时逐个读取，避免一次性拼接超出上下文——优先在沙箱内用脚本
生成完整请求再调用，而非把 base64 直接写进对话。
第 3 步：调用 course_publish（MCP 工具直连，不传 dir——
服务端读不到沙箱文件，必须传 files）：
- title / description（末尾加「（XX整理）」署名）/ level / category / files
第 4 步：解析结果。成功返回「待审核 + 课程 id」；审核、类别、令牌
状态分别用 course_review、course_categories、industry_token_status 工具。
云端注意事项：
- files 的 base64 总量若超出单次工具调用限制，分批不可行（course_publish 是
整体提交）——应压缩图片后再试；仍超限则告知用户改走本机发布
- 令牌与账号绑定，各环境可复用同一个含 course:write 的令牌，无需重复签发
故障排查
| 现象 | 原因与处理 |
|---|---|
| 403 缺 course:write | 令牌 scope 不足，让用户到站点「个人中心 → MCP 令牌」签发含 course:* 的令牌 |
| 未收到 id=2 响应（本机） | 上传超时，原样重试；仍失败则把脚本 wait 秒数调大 |
| 连接失败/超时（云端） | WAF 拦截云端出口或连接器未配置，改走本机发布或申请 IP 白名单 |
| 预检报图片超 150KB | 先压缩再发布；云端注意压缩后总 base64 也别超调用限制 |
| 401 令牌失效 | 查令牌状态（本机 status / 云端 industry_token_status），提醒用户换发 |
| 路径读不到文件 | 检查是否跨环境引用路径——文件必须在当前环境内 |
不做的事
- 不做教程内容制作（制作用 create-ai-tutorial 技能）
- 不发百家争鸣资讯（那是 industry_create，另一条流程）
- 不绕过审核（无 course:review 权限时明确告知用户走平台审核）
- 不跨环境传文件（本机↔云端路径互不可见，让文件就位于执行环境）
