# 圆梦老师AIGC · 课件页桥接说明（供 AI / 开发者）
站点: https://ymaigc.cn
操作指南页: https://ymaigc.cn/operation-guide
操作指南纯文本: https://ymaigc.cn/llms-operation-guide.txt
官方示例目录: https://ymaigc.cn/llms-examples.txt
新手指引: https://ymaigc.cn/newbie-guide

说明：编辑器预览、播放器、分享页会自动注入桥接脚本。页面禁止自行引入 courseware-*-bridge.js，
禁止在 HTML 中写入 Authorization / JWT / 分享 AI Token / MCP apikey。

页面前置（必须）:
  <meta name="cw-courseware-id" content="课件数字ID">

================================================================================
一、状态储存（课件 data/）
================================================================================
每个课件有独立 data/ 目录，用于持久保存：
  - JSON / 文本：成绩、关卡进度、配置、填写草稿、排行榜
  - 图片 / 音频 / 视频 / PDF
  - 独立静态站点（html/css/js）

不要用 localStorage 存大数据或大图；刷新/重开需保留的内容请写 data/。

页面 API:
  const resp = await cwReadDataFile('scores.json');
  // resp.content 为文本；也可 path 带 data/ 前缀
  await cwWriteDataFile('scores.json', JSON.stringify(data, null, 2), 'utf8');
  const saved = await cwWriteDataFile('photo.png', base64String, 'base64');
  img.src = saved.url; // 必须用返回的 https 绝对地址

媒体引用必须用接口返回的 https URL，禁止相对路径 data/xxx.png。

HTTP（登录 JWT）示例域名 https://cwadmin.cirunv.cn ：
  GET    /api/courseware/{id}/data
  GET    /api/courseware/{id}/data/file?path=xxx
  PUT/POST /api/courseware/{id}/data/file
  POST   /api/courseware/{id}/data/upload-from-url
  DELETE /api/courseware/{id}/data/file?path=xxx

外链图写入（解决 CORS）:
  POST .../upload-from-url  { "imageUrl": "https://...", "path": "data/bg.jpg" }

================================================================================
二、页内 AI（多模态问答）
================================================================================
鉴权由父窗口代持（登录 JWT 或分享页 share AI token）。

  const answer = await cwAiAsk('用一句话解释牛顿第一定律');
  const res = await cwAiAskVision('图中有哪些物体？', [
    'https://example.com/photo.jpg', // 或 data:image/...
  ]);
  const json = await cwAiChatCompletion({
    messages: [
      { role: 'system', content: '你是课堂助教，回答简洁。' },
      { role: 'user', content: '描述图片并出一道选择题' },
    ],
    temperature: 0.7,
    max_tokens: 1024,
  });
  await cwAiChatCompletionStream(
    { messages: [{ role: 'user', content: '讲一个小故事' }] },
    { onDelta: (piece) => { /* 追加 UI */ } },
  );

禁止：页面内手写 fetch 到 /ai-models/.../chat/completions；禁止嵌密钥。
超时：非流式约 120s，流式约 180s。

================================================================================
三、TTS（文字转语音 / 实时朗读）
================================================================================
动态讲解、AI 回复朗读用 TTS 桥（阿里云 NLS）。固定旁白也可用圆梦助手预合成 <audio src>。

  await cwTtsSpeak({ text: answer, voice: 'zhixiaobai' });
  const { url } = await cwTtsSynthesize({ text: '欢迎来到本课', voice: 'zhixiaobai' });
  await cwTtsPlayUrl(url);
  const { voices, defaultVoice } = await cwTtsGetVoices();
  cwTtsStop();

课堂默认音色 zhixiaobai；男声 sicheng；童声 xiaobei / sitong。
禁止 window.speechSynthesis；禁止在 HTML 手写 TTS 密钥。
分享页单次约 500 字；登录预览可更长。

================================================================================
四、STT（语音识别）与麦克风 / 摄像头
================================================================================
iframe 内 getUserMedia / SpeechRecognition 会被软补丁到父窗口代申请。也可显式：

  const stream = await cwGetUserMedia({ audio: true });
  // 摄像头：await cwGetUserMedia({ video: true });
  const { transcript } = await cwSpeechRecognize({
    lang: 'zh-CN',
    timeoutMs: 8000,
    onInterim: (t) => console.log(t),
  });

建议 Chrome / Edge；需用户授权麦克风。圆梦助手输入框也支持按住说话（编辑器侧 STT）。

================================================================================
五、产品侧相关能力（非桥接，但常一起用）
================================================================================
- AI 生成图片：编辑器工具栏 / 圆梦助手「+」→ 通用生图
- AI 生成抠图元素：元素抠图模式，贴纸式主体 + 一键去背景
- AI 生成 VR 全景：工具栏「全景」→ 描述场景 → 2:1 无缝 equirectangular → 拖动预览后插入
- 圆梦助手「课件文件管理」：带预览浏览 data/，上传/删除/复制链接

完整操作步骤: https://ymaigc.cn/operation-guide
官方 HTML 范本: https://ymaigc.cn/llms-examples.txt