tencent-edu-assistant-connector 0.1.4 → 0.3.0

package/README.md

@@ -7,6 +7,7 @@
 - **基于当前专题对话**：「这一页讲的是什么？帮我总结一下」「用当前专家的口吻解释一下我选中的这段话」
 - **一键生成学习产物**：在专题页点击生成笔记 / 测验 / 闪卡 / 互动课程，WorkBuddy 生成后自动回填到专题，页面实时显示进度
 - **首页 AI 生课**：围绕一个问题生成互动课程，并自动创建新专题
+- **首页精选场景**：按场景技能生成网页或视频作品（≤ 200MB），并自动创建场景专题
 
 ## 安装
 
@@ -39,9 +40,10 @@ npx -y tencent-edu-assistant-connector@latest install
 
 ## 常见问题
 
-**页面提示「未连接到连小理」**
+**页面提示「未连接到腾讯教育学习助手」**
 
 确认 WorkBuddy「连接器」中 「腾讯教育学习助手」已启用；刚安装时等首次下载完成，或在 WorkBuddy 中发送任意消息后刷新页面。
+也可以在 WorkBuddy 里直接问「学习空间连上了吗？」，AI 会调用连接器的 `get_connector_status` 自检，给出本机服务、页面连接状态与排查步骤。
 
 连接器会在本机启动一个后台服务持有 3101 端口（关闭 WorkBuddy 会话后仍保留，页面关闭且 30 分钟无使用后自动退出），日志在 `~/.tencent-edu-assistant/daemon.log`。
 

package/dist/artifact-validate.js

@@ -1,4 +1,16 @@
-/** 各类别产物的文件名后缀约定 */
+/**
+ * 产物内容校验：交付前按类别校验后缀与内容，失败返回可读中文原因供模型修正后重试。
+ *
+ * quiz / flashcard 结构对齐前端解析器（learning-buddy-web）：
+ * - 顶层：数组，或 `{ questions: [...] }` / `{ cards: [...] }`（topic-detail.vue `asProductList`）
+ * - quiz 每题：`stem|question`、`options`（数组 `label|key|letter` + `text|value`，或对象 `{ A: '...' }`）、`answer`
+ *   （productNormalization.ts `normalizeQuizQuestions`）
+ * - flashcard 每张：`term|front|q`、`question|stem|q`、`answer|back|explanation|a`
+ *   （productNormalization.ts `normalizeFlashcardCards`）
+ * 字段取值与前端一致：按候选字段顺序取第一个 truthy 值。
+ */
+import { fileExtOf, isSupportedSceneExt, SCENE_HTML_EXTS } from './skill-packages.js';
+/** 固定类别产物的文件名后缀约定（scene 的格式由任务的 sceneExts 决定） */
 export const ARTIFACT_SUFFIX_BY_KIND = Object.freeze({
     note: '-note.md',
     quiz: '-quiz.json',
@@ -145,7 +157,7 @@ function decodeText(content) {
 /**
  * 校验产物文件：后缀与类别一致、内容非空、按类别校验结构。不抛异常。
  *
- * @param kind 产物类别
+ * @param kind 产物类别（固定后缀类别；scene 用 {@link validateSceneArtifact}）
  * @param fileName 文件名（大小写不敏感匹配后缀）
  * @param content 文件内容（Buffer 按 UTF-8 解码）
  * @returns 成功返回去 BOM 后的文本；失败返回可读中文原因
@@ -161,3 +173,54 @@ export function validateArtifact(kind, fileName, content) {
     const error = checkContent(kind, text);
     return error ? { ok: false, reason: error } : { ok: true, text };
 }
+/** ISO BMFF 容器（mp4 / mov / m4v）：第 4~8 字节为 `ftyp` */
+const ISO_BMFF_EXTS = Object.freeze(['mp4', 'mov', 'm4v']);
+/** EBML 容器（webm）文件头 */
+const EBML_MAGIC = Buffer.from([0x1a, 0x45, 0xdf, 0xa3]);
+/**
+ * 视频文件头校验（只看容器魔数，不解析流）；未知格式放行，由后端校验。
+ * @param ext 扩展名
+ * @param content 文件内容
+ */
+function hasVideoSignature(ext, content) {
+    if (ISO_BMFF_EXTS.includes(ext))
+        return content.length >= 8 && content.toString('latin1', 4, 8) === 'ftyp';
+    if (ext === 'webm')
+        return content.length >= 4 && content.subarray(0, 4).equals(EBML_MAGIC);
+    return true;
+}
+/**
+ * 渲染允许的扩展名列表，如「.html、.mp4」。
+ * @param exts 扩展名（不含点）
+ */
+export function formatSceneExts(exts) {
+    return exts.map((ext) => `.${ext}`).join('、');
+}
+/**
+ * 校验场景产物：扩展名须在任务允许列表内且受 MCP 支持、内容非空；HTML 类须为完整 HTML 文档（含 `<html`）。
+ * 视频等二进制产物不解码、不改写字节。不抛异常。
+ *
+ * @param fileName 实际文件名
+ * @param content 文件内容
+ * @param allowedExts 任务允许的扩展名（小写、不含点）
+ */
+export function validateSceneArtifact(fileName, content, allowedExts) {
+    const ext = fileExtOf(fileName);
+    if (!ext || !allowedExts.includes(ext) || !isSupportedSceneExt(ext)) {
+        const allowed = formatSceneExts(allowedExts.filter(isSupportedSceneExt));
+        return { ok: false, reason: `产物格式不符：本场景只允许 ${allowed || '（无可交付格式）'}，当前为 ${truncate(fileName)}` };
+    }
+    if (content.length === 0)
+        return { ok: false, reason: '场景产物内容为空' };
+    if (!SCENE_HTML_EXTS.includes(ext)) {
+        return hasVideoSignature(ext, content)
+            ? { ok: true, content }
+            : { ok: false, reason: `文件内容不是有效的 .${ext} 视频（请确认已完成渲染与编码，而不是写入了文本或占位内容）` };
+    }
+    const text = decodeText(content);
+    if (!text.trim())
+        return { ok: false, reason: '场景产物内容为空' };
+    if (!/<html/i.test(text))
+        return { ok: false, reason: '场景 HTML 需包含 <html 标签（完整 HTML 文档）' };
+    return { ok: true, content: Buffer.from(text, 'utf8') };
+}

package/dist/bridge.js

@@ -15,7 +15,7 @@
  * | `GET /context/hook` | `text/plain; charset=utf-8` Hook 文本，无上下文且无「新建专题」任务时为空串；**副作用**：先把当前上下文专题与 `NEW_TOPIC_SCOPE` 的 filled / stopped 任务标记为 sent（无会话，兜底） |
  * | `POST /hooks/prompt-submit` | WB `UserPromptSubmit` Hook 回调（command Hook curl 转发 stdin）：`markSent(当前上下文专题 / NEW_TOPIC_SCOPE, session_id)`；**恒为 200 `{}`** |
  * | `POST /hooks/final-stop` | WB `FinalStop` Hook 回调（command Hook curl 转发 stdin）：`finalStop(session_id, final_stop_reason, 当前上下文专题 / NEW_TOPIC_SCOPE)`；**恒为 200 `{}`** |
- * | `POST /generation` | `{ requestId, kind, topicId, createdAt }`（requestId 由服务端生成）；`topicId=NEW_TOPIC_SCOPE` 为首页 AI 生课（仅 course，须带 `newTopicName`） |
+ * | `POST /generation` | `{ requestId, kind, topicId, createdAt }`（requestId 由服务端生成）；`topicId=NEW_TOPIC_SCOPE` 为首页 AI 生课（course）/ 精选场景（scene，须带 `sceneId` / `sceneExts` / `skillPackageUrl`），均须带 `newTopicName` |
  * | `GET /generation/status?topicId=` | `{ tasks }`（filled / sent / running / stopped / failed，不含 delivered、token 与会话 ID） |
  * | `GET /landed?topicId=` | `{ items }` |
  * | `POST /landed/ack` | `{ removed }` |
@@ -48,7 +48,9 @@ const pageSchema = z.number().int().positive();
 /** 文件名（上下文中的展示名 / 产物文件名） */
 const fileNameSchema = z.string().max(255);
 /** 生成类别 */
-const generationKindSchema = z.enum(['note', 'quiz', 'flashcard', 'course']);
+const generationKindSchema = z.enum(['note', 'quiz', 'flashcard', 'course', 'scene']);
+/** 可登记在「新建专题」作用域的类别 */
+const NEW_TOPIC_KINDS = Object.freeze(['course', 'scene']);
 /**
  * 判断字符串是否为 `https:` URL。
  * @param value 待校验字符串
@@ -102,27 +104,65 @@ export const generationBodySchema = z
         .transform((url) => (url === '' ? undefined : url)),
     fileName: fileNameSchema.min(1),
     token: tokenSchema,
-    // 仅「新建专题」任务（topicId = NEW_TOPIC_SCOPE）携带：新专题兜底名称
+    // 「新建专题」任务（topicId = NEW_TOPIC_SCOPE）携带：新专题名称（course 为兜底名，scene 为场景标题）
     newTopicName: z.string().trim().min(1).max(100).optional(),
+    // 仅场景任务携带：场景 ID 与允许的产物扩展名（小写、不含点）
+    sceneId: z.string().regex(/^[1-9]\d{0,19}$/, 'must be a decimal id').optional(),
+    sceneExts: z
+        .array(z.string().regex(/^[a-z0-9]{1,10}$/, 'must be a lowercase extension without dot'))
+        .min(1)
+        .max(20)
+        .optional(),
 })
     .superRefine((body, ctx) => {
-    const suffix = ARTIFACT_SUFFIX_BY_KIND[body.kind];
-    if (!body.fileName.toLowerCase().endsWith(suffix)) {
-        ctx.addIssue({ code: 'custom', path: ['fileName'], message: `must end with ${suffix}` });
+    const issue = (path, message) => {
+        ctx.addIssue({ code: 'custom', path: [path], message });
+    };
+    if (body.kind === 'scene') {
+        refineSceneBody(body, issue);
+    }
+    else {
+        const suffix = ARTIFACT_SUFFIX_BY_KIND[body.kind];
+        if (!body.fileName.toLowerCase().endsWith(suffix))
+            issue('fileName', `must end with ${suffix}`);
+        if (body.sceneId !== undefined)
+            issue('sceneId', 'only allowed when kind is scene');
+        if (body.sceneExts !== undefined)
+            issue('sceneExts', 'only allowed when kind is scene');
     }
     if (body.topicId !== NEW_TOPIC_SCOPE) {
-        if (body.newTopicName !== undefined) {
-            ctx.addIssue({ code: 'custom', path: ['newTopicName'], message: `only allowed when topicId is ${NEW_TOPIC_SCOPE}` });
-        }
+        if (body.newTopicName !== undefined)
+            issue('newTopicName', `only allowed when topicId is ${NEW_TOPIC_SCOPE}`);
         return;
     }
-    if (body.kind !== 'course') {
-        ctx.addIssue({ code: 'custom', path: ['kind'], message: `must be course when topicId is ${NEW_TOPIC_SCOPE}` });
-    }
-    if (body.newTopicName === undefined) {
-        ctx.addIssue({ code: 'custom', path: ['newTopicName'], message: `required when topicId is ${NEW_TOPIC_SCOPE}` });
+    if (!NEW_TOPIC_KINDS.includes(body.kind)) {
+        issue('kind', `must be ${NEW_TOPIC_KINDS.join(' or ')} when topicId is ${NEW_TOPIC_SCOPE}`);
     }
+    if (body.newTopicName === undefined)
+        issue('newTopicName', `required when topicId is ${NEW_TOPIC_SCOPE}`);
 });
+/**
+ * 场景任务的请求体约束：只能登记在 NEW_TOPIC_SCOPE，必须带 sceneId / sceneExts / skillPackageUrl，
+ * 文件名扩展名在 sceneExts 内（扩展名是否受支持由 store 校验）。
+ * @param body 请求体
+ * @param issue 追加校验问题
+ */
+function refineSceneBody(body, issue) {
+    if (body.topicId !== NEW_TOPIC_SCOPE)
+        issue('topicId', `must be ${NEW_TOPIC_SCOPE} when kind is scene`);
+    if (body.sceneId === undefined)
+        issue('sceneId', 'required when kind is scene');
+    if (body.skillPackageUrl === undefined)
+        issue('skillPackageUrl', 'required when kind is scene');
+    if (body.sceneExts === undefined) {
+        issue('sceneExts', 'required when kind is scene');
+        return;
+    }
+    const dot = body.fileName.lastIndexOf('.');
+    const ext = dot > 0 ? body.fileName.slice(dot + 1).toLowerCase() : '';
+    if (!body.sceneExts.includes(ext))
+        issue('fileName', 'extension must be one of sceneExts');
+}
 /** `GET /landed` 查询参数 */
 export const landedQuerySchema = z.object({ topicId: topicIdSchema });
 /** `GET /generation/status` 查询参数 */

package/dist/config.js

@@ -31,8 +31,8 @@ export const DEFAULT_ALLOWED_ORIGINS = Object.freeze([
     'http://localhost:8089',
     'http://127.0.0.1:8089',
 ]);
-/** 默认监听端口 */
-const DEFAULT_PORT = 3101;
+/** 默认监听端口（`LB_TOPIC_MCP_PORT` / `PORT` 未设置时使用） */
+export const DEFAULT_PORT = 3101;
 /** 合法端口上限 */
 const MAX_PORT = 65535;
 /** 一分钟（毫秒） */
@@ -48,6 +48,7 @@ const TTL = Object.freeze({
 const LIMITS = Object.freeze({
     hookTextMaxChars: 8000,
     deliverFileMaxBytes: 10 * 1024 * 1024,
+    sceneDeliverFileMaxBytes: 200 * 1024 * 1024,
     selectionMaxChars: 2000,
 });
 /** 后端接口请求超时（毫秒） */

package/dist/context-store.js

@@ -43,6 +43,17 @@ function copyReading(reading) {
 function copyExpert(expert) {
     return expert.profile === undefined ? { name: expert.name } : { name: expert.name, profile: expert.profile };
 }
+/**
+ * 复制网页链接（只保留已知字段）。
+ * @param webLink 链接专题的网页链接
+ */
+function copyWebLink(webLink) {
+    return {
+        url: webLink.url,
+        ...(webLink.title === undefined ? {} : { title: webLink.title }),
+        ...(webLink.platform === undefined ? {} : { platform: webLink.platform }),
+    };
+}
 /**
  * 复制选区（只保留已知字段），可选截断文本。
  * @param selection 选区
@@ -104,6 +115,7 @@ export function createContextStore(options = {}) {
                     ? {}
                     : { selection: copySelection(ctx.selection, selectionMaxChars()) }),
                 ...(ctx.expert === undefined ? {} : { expert: copyExpert(ctx.expert) }),
+                ...(ctx.webLink === undefined ? {} : { webLink: copyWebLink(ctx.webLink) }),
                 token: ctx.token,
                 updatedAt: now(),
             };
@@ -143,6 +155,7 @@ export function createContextStore(options = {}) {
                 ...(reading === undefined ? {} : { reading }),
                 ...(selection === undefined ? {} : { selection }),
                 ...(current.expert === undefined ? {} : { expert: copyExpert(current.expert) }),
+                ...(current.webLink === undefined ? {} : { webLink: copyWebLink(current.webLink) }),
                 updatedAt: current.updatedAt,
             };
         },

package/dist/cos-upload.js

@@ -7,22 +7,25 @@
  * - Content-Type 按 key 后缀取规范 MIME（不带参数，对齐 STS policy 允许集合）；
  * - `topic_file/create` 是 (topic_id, file_type) 整批覆盖：先拉该类型全量 → 按 object key 去重合并 → 提交，
  *   按 (topicId, fileType) 串行排队；
- * - `file_type` 与类别一一对应（note / quiz / flashcard / course）。
+ * - `file_type` 与类别一一对应（note / quiz / flashcard / course / scene）；scene 产物 key 为 `{topicId}_scene`，
+ *   后端要求 object key 位于 `lb/topic/{topicId}_scene/` 下并 HEAD 取真实大小。
  */
 import COS from 'cos-nodejs-sdk-v5';
 import { createEduAssistantApi, describeError, hasDotSegment, redactSensitive, } from './edu-assistant-api.js';
-/** 生成类别 → topic_file.file_type（对齐前端 useTopicProductIO / courseGeneratePersist） */
+import { SCENE_ARTIFACT_MIME_BY_EXT } from './skill-packages.js';
+/** 生成类别 → topic_file.file_type（对齐前端 useTopicProductIO / courseGeneratePersist；scene → 场景产物） */
 const FILE_TYPE_BY_KIND = Object.freeze({
     note: 'note',
     quiz: 'quiz',
     flashcard: 'flashcard',
     course: 'course',
+    scene: 'scene',
 });
 /** object key 后缀 → 规范 MIME（对齐前端 cosDirectUpload SPEC_MIME_BY_EXT，不带 charset 参数） */
 const CONTENT_TYPE_BY_EXT = Object.freeze({
     md: 'text/markdown',
     json: 'application/json',
-    html: 'text/html',
+    ...SCENE_ARTIFACT_MIME_BY_EXT,
 });
 /** 专题 ID 白名单（对齐前端 cosKey OWNER_ID_PATTERN） */
 const TOPIC_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
@@ -37,8 +40,17 @@ const FALLBACK_FILE_NAME = 'file';
 /** 合并基准翻页：上限 10 页 × 100 条（对齐前端） */
 const REGISTER_PAGE_SIZE = 100;
 const REGISTER_MAX_PAGES = 10;
-/** COS 直传超时（毫秒） */
+/** COS 直传最短超时（毫秒） */
 const COS_UPLOAD_TIMEOUT_MS = 120_000;
+/** 按最低上行速率估算大文件超时（字节 / 秒）：200MB 约 13 分钟 */
+const COS_UPLOAD_MIN_BYTES_PER_SEC = 256 * 1024;
+/**
+ * 按文件大小估算 COS 直传超时：不低于 {@link COS_UPLOAD_TIMEOUT_MS}。
+ * @param bytes 文件字节数
+ */
+export function cosUploadTimeoutMs(bytes) {
+    return Math.max(COS_UPLOAD_TIMEOUT_MS, Math.ceil(bytes / COS_UPLOAD_MIN_BYTES_PER_SEC) * 1000);
+}
 /** 按 (topicId, fileType) 串行排队的登记任务 */
 const registerQueues = new Map();
 /**
@@ -127,13 +139,14 @@ function toBareCosUrl(cred) {
 /**
  * 默认 COS 客户端：cos-nodejs-sdk-v5 + 临时密钥，callback 包装为 Promise。
  * @param cred 凭证
+ * @param options 超时等选项
  */
-function createDefaultCosClient(cred) {
+function createDefaultCosClient(cred, options) {
     const cos = new COS({
         SecretId: cred.secretId,
         SecretKey: cred.secretKey,
         SecurityToken: cred.securityToken,
-        Timeout: COS_UPLOAD_TIMEOUT_MS,
+        Timeout: options.timeoutMs,
     });
     return {
         putObject: (params) => new Promise((resolve, reject) => {
@@ -256,7 +269,7 @@ export async function uploadArtifactToTopic(input, deps = {}) {
     const fileName = sanitizeUploadFileName(input.fileName);
     const cred = await runStep('获取上传凭证失败', [token], async () => requireCredential(await api.getCosCredential(token, { fileName, key: `${topicId}_${fileType}` })));
     const secrets = [token, cred.secretId, cred.secretKey, cred.securityToken];
-    await runStep('上传 COS 失败', secrets, () => putToCos(cosFactory(cred), cred, content));
+    await runStep('上传 COS 失败', secrets, () => putToCos(cosFactory(cred, { timeoutMs: cosUploadTimeoutMs(content.length) }), cred, content));
     const cosUrl = toBareCosUrl(cred);
     const fileExt = extractExt(fileName);
     const records = await runStep('登记专题文件失败', secrets, () => registerMerged(api, token, topicId, fileType, {

package/dist/daemon.js

@@ -3,7 +3,8 @@
  *
  * 背景：WB 只在会话运行期间保活 stdio MCP（关闭时 stdin.end → 2s → SIGTERM → 2s → SIGKILL；
  * 添加连接器时的探测连接 1～2 秒即断开），而页面需要端口常驻。因此：
- * - stdio 进程启动时 {@link ensureDaemon}：未运行则以 detached 方式拉起 `stdio.js daemon`，自身随后作为 follower
+ * - stdio 进程启动时 {@link ensureDaemon}：未运行则经双 fork 拉起 `stdio.js daemon`（daemon 被系统收养，脱离 WB
+ *   进程树，见 `DAEMON_LAUNCHER_SCRIPT`），自身随后作为 follower
  *   经 `/internal` 转发工具调用；daemon 即端口主从中的 leader，页面上下文与生成任务跨会话保留。
  * - 版本不一致（升级后旧 daemon 仍在运行）：经 `POST /internal/shutdown` 请旧 daemon 退出后拉起当前版本；
  *   旧版本不支持该接口时保持现状（本进程作为 follower 使用旧服务）。
@@ -128,7 +129,18 @@ function openDaemonLog(home) {
     }
 }
 /**
- * 以 detached 方式拉起 daemon（脱离当前进程组，WB 结束会话时不会被一并结束）。
+ * 双 fork 中间进程脚本：以 detached 方式拉起真正的 daemon（参数为 `process.argv.slice(1)`，继承本进程的
+ * stdio 即日志文件）后立即退出，daemon 随之被系统收养（ppid=1）。
+ *
+ * 只用 `detached` 不够：它只让 daemon 脱离进程组，ppid 仍是 stdio 进程；WB 回收 CLI 进程（会话结束 /
+ * 预热池轮换）时按 ppid 遍历进程树发 SIGTERM，daemon 会被连带结束，页面上下文与已登记的生成任务随之丢失。
+ */
+export const DAEMON_LAUNCHER_SCRIPT = [
+    "const { spawn } = require('node:child_process');",
+    'spawn(process.execPath, process.argv.slice(1), { detached: true, stdio: \'inherit\', env: process.env, windowsHide: true }).unref();',
+].join('\n');
+/**
+ * 经双 fork 中间进程拉起 daemon（见 {@link DAEMON_LAUNCHER_SCRIPT}），使其脱离 WB 的进程树。
  * @param options 参数
  */
 function spawnDaemon(options) {
@@ -136,7 +148,7 @@ function spawnDaemon(options) {
     const spawnImpl = options.spawnImpl ?? spawn;
     const log = openDaemonLog(options.home);
     try {
-        const child = spawnImpl(process.execPath, [options.entry, DAEMON_SUBCOMMAND], {
+        const child = spawnImpl(process.execPath, ['-e', DAEMON_LAUNCHER_SCRIPT, options.entry, DAEMON_SUBCOMMAND], {
             detached: true,
             stdio: ['ignore', log, log],
             env: options.env,

package/dist/generation-store.js

@@ -15,8 +15,10 @@
  *     （stopReason `ended`，回复结束但仍未交付）。
  * - `reportProgress`：模型上报进度，`filled | sent | running | stopped` → `running`（覆盖 progress）；stage 为 `failed` → `failed`。
  * - 交付成功 → `delivered`（仅未完成任务可交付）。
- * - 「新建专题」任务：`topicId` 为保留作用域 `NEW_TOPIC_SCOPE`，仅允许 course 且必须带 `newTopicName`；
+ * - 「新建专题」任务：`topicId` 为保留作用域 `NEW_TOPIC_SCOPE`，仅允许 course / scene 且必须带 `newTopicName`；
  *   其余专题不得携带 `newTopicName`。状态机与普通任务一致。
+ * - 场景任务（scene）：只能登记在 `NEW_TOPIC_SCOPE`，必须带 `sceneId`、`sceneExts` 与技能包地址；
+ *   技能 slug 来自场景配置（格式受限），产物文件名扩展名须在 `sceneExts` 内。其余类别不得携带场景字段。
  *
  * 过期（各方法惰性清理）：
  * - `filled`：自 createdAt 起 `ttlMs`（默认 30 分钟）；
@@ -32,10 +34,16 @@
  */
 import { getConfig } from './config.js';
 import { redactSensitive } from './edu-assistant-api.js';
-import { isAllowedSkillPackageUrl, SKILL_SLUG_BY_KIND } from './skill-packages.js';
+import { fileExtOf, isAllowedSkillPackageUrl, isSupportedSceneExt, isValidSceneSkillSlug, SKILL_SLUG_BY_KIND, } from './skill-packages.js';
 import { NEW_TOPIC_SCOPE } from './types.js';
 /** 合法的生成类别 */
-const GENERATION_KINDS = Object.freeze(['note', 'quiz', 'flashcard', 'course']);
+const GENERATION_KINDS = Object.freeze(['note', 'quiz', 'flashcard', 'course', 'scene']);
+/** 可登记在「新建专题」作用域的类别 */
+const NEW_TOPIC_KINDS = Object.freeze(['course', 'scene']);
+/** 场景 ID：十进制数字串（uint64） */
+const SCENE_ID_PATTERN = /^[1-9]\d{0,19}$/;
+/** 场景允许扩展名个数上限 */
+const SCENE_EXTS_MAX = 20;
 /** 合法的生成阶段 */
 const GENERATION_STAGES = Object.freeze([
     'reading',
@@ -97,33 +105,66 @@ function assertValidInput(input) {
     if (!GENERATION_KINDS.includes(input.kind)) {
         throw new Error(`生成任务字段 kind 只允许：${GENERATION_KINDS.join('、')}`);
     }
-    if (input.skillSlug !== SKILL_SLUG_BY_KIND[input.kind]) {
-        throw new Error('生成任务字段 skillSlug 与 kind 不匹配');
-    }
     if (typeof input.params !== 'object' || input.params === null || Array.isArray(input.params)) {
         throw new Error('生成任务字段 params 必须是对象');
     }
     if (input.skillPackageUrl !== undefined && typeof input.skillPackageUrl !== 'string') {
         throw new Error('生成任务字段 skillPackageUrl 必须是字符串');
     }
+    if (input.kind === 'scene') {
+        assertValidScene(input);
+    }
+    else {
+        if (input.skillSlug !== SKILL_SLUG_BY_KIND[input.kind])
+            throw new Error('生成任务字段 skillSlug 与 kind 不匹配');
+        if (input.sceneId !== undefined || input.sceneExts !== undefined) {
+            throw new Error('生成任务字段 sceneId / sceneExts 仅允许用于场景任务');
+        }
+    }
     if (input.skillPackageUrl !== undefined && !isAllowedSkillPackageUrl(input.skillPackageUrl, input.skillSlug)) {
         throw new Error('生成任务字段 skillPackageUrl 不是允许的技能包地址');
     }
     assertValidNewTopic(input);
 }
 /**
- * 校验「新建专题」字段：保留作用域只允许 course 且必须带兜底名称；普通专题不得携带兜底名称。
+ * 校验场景任务字段：slug 格式、必须带技能包地址、场景 ID、允许扩展名（均受 MCP 支持），文件名扩展名在允许列表内。
+ * @param input 登记入参（kind 为 scene）
+ * @throws {Error} 入参非法（消息只含字段名）
+ */
+function assertValidScene(input) {
+    if (!isValidSceneSkillSlug(input.skillSlug))
+        throw new Error('生成任务字段 skillSlug 格式不合法');
+    if (input.skillPackageUrl === undefined)
+        throw new Error('场景任务必须携带 skillPackageUrl');
+    if (typeof input.sceneId !== 'string' || !SCENE_ID_PATTERN.test(input.sceneId)) {
+        throw new Error('生成任务字段 sceneId 必须是十进制数字串');
+    }
+    const exts = input.sceneExts;
+    const isValidExts = Array.isArray(exts) &&
+        exts.length > 0 &&
+        exts.length <= SCENE_EXTS_MAX &&
+        exts.every((ext) => typeof ext === 'string' && isSupportedSceneExt(ext));
+    if (!isValidExts)
+        throw new Error('生成任务字段 sceneExts 必须是 MCP 支持的扩展名数组');
+    if (!exts.includes(fileExtOf(input.fileName)))
+        throw new Error('生成任务字段 fileName 的扩展名不在 sceneExts 内');
+}
+/**
+ * 校验「新建专题」字段：保留作用域只允许 course / scene 且必须带名称；场景任务只能用保留作用域；
+ * 普通专题不得携带名称。
  * @param input 登记入参
  * @throws {Error} 入参非法（消息只含字段名）
  */
 function assertValidNewTopic(input) {
     if (input.topicId !== NEW_TOPIC_SCOPE) {
+        if (input.kind === 'scene')
+            throw new Error(`场景任务的 topicId 只允许 ${NEW_TOPIC_SCOPE}`);
         if (input.newTopicName !== undefined)
             throw new Error('生成任务字段 newTopicName 仅允许用于新建专题');
         return;
     }
-    if (input.kind !== 'course')
-        throw new Error('新建专题任务的 kind 只允许 course');
+    if (!NEW_TOPIC_KINDS.includes(input.kind))
+        throw new Error(`新建专题任务的 kind 只允许 ${NEW_TOPIC_KINDS.join('、')}`);
     if (!isNonEmptyString(input.newTopicName))
         throw new Error('生成任务字段 newTopicName 必须是非空字符串');
 }
@@ -154,6 +195,8 @@ function cloneTask(task) {
         fileName: task.fileName,
         token: task.token,
         ...(task.newTopicName === undefined ? {} : { newTopicName: task.newTopicName }),
+        ...(task.sceneId === undefined ? {} : { sceneId: task.sceneId }),
+        ...(task.sceneExts === undefined ? {} : { sceneExts: [...task.sceneExts] }),
         createdAt: task.createdAt,
         updatedAt: task.updatedAt,
         ...(task.sentAt === undefined ? {} : { sentAt: task.sentAt }),
@@ -431,6 +474,8 @@ export function createGenerationStore(options = {}) {
                 fileName: input.fileName,
                 token: input.token,
                 ...(input.newTopicName === undefined ? {} : { newTopicName: input.newTopicName }),
+                ...(input.sceneId === undefined ? {} : { sceneId: input.sceneId }),
+                ...(input.sceneExts === undefined ? {} : { sceneExts: input.sceneExts }),
                 createdAt,
                 updatedAt: createdAt,
                 status: 'filled',

package/dist/hook-text.js

@@ -9,7 +9,7 @@
  * - 不输出 token（`GenerationTask.token` 不参与渲染）。
  * - 所有外部来源字符串的尖括号替换为全角，防止伪造 `</system-reminder>` 等标签；单行字段的换行折叠为空格。
  * - 总长不超过 `maxChars`。截断优先级（先保留 → 先截断）：头部（专题信息）与未完成任务段始终保留；
- *   正文段按「阅读位置 → 选区 → 专家 → 文件清单」排列，只从正文尾部截断，因此签名地址很长的文件清单最先被截断，
+ *   正文段按「阅读位置 → 选区 → 专家 → 学习网页 → 文件清单」排列，只从正文尾部截断，因此签名地址很长的文件清单最先被截断，
  *   清单说明行提示模型可调用 `get_page_context` 获取全部文件。头部与任务段本身超长时，先把各任务的表单参数
  *   压缩到 {@link PARAMS_COMPACT_MAX_CHARS} 字（requestId / 进度上报 / 交付要求行完整保留）再重试；仍超长才退化为整体截断。
  */
@@ -35,6 +35,7 @@ const KIND_LABELS = Object.freeze({
     quiz: '测验',
     flashcard: '闪卡',
     course: '课程',
+    scene: '场景作品',
 });
 /**
  * 各类别进度上报的差异说明（拼在通用说明之后）：done / total 的含义随产物类型不同。
@@ -44,6 +45,7 @@ export const KIND_PROGRESS_HINTS = Object.freeze({
     quiz: 'generating 阶段 done/total = 已完成题数/总题数（按批次上报即可）。',
     flashcard: 'generating 阶段 done/total = 已完成卡片数/总卡片数。',
     course: 'outlining 完成后即可确定章节数；generating 阶段每完成一章上报一次 done/total = 已完成章节/总章节。',
+    scene: 'generating 阶段按技能的实际步骤（如分镜 / 片段 / 页面）成对上报 done/total；无法计数时只报 stage 与 message。',
 });
 /**
  * 把尖括号替换为全角，保留其余字符（含换行）。
@@ -109,12 +111,35 @@ function filesIntroSelected(count) {
         '以下均为已签名地址，请直接用 curl / WebFetch 下载读取，禁止在本地磁盘搜索同名文件。',
     ].join('');
 }
+/**
+ * 链接专题的「学习网页」段；非链接专题为空串。
+ *
+ * 链接专题没有上传文件，链接本身就是唯一资料，因此必须显式给出链接与「不要凭 URL 想象内容」的约束，
+ * 否则模型只会看到专题标题，容易编造网页内容。
+ * @param webLink 链接专题绑定的网页链接
+ */
+function renderWebLink(webLink) {
+    if (!webLink)
+        return '';
+    const title = (webLink.title ?? '').trim();
+    // 页面占位标题（「未命名专题-xxx」）不是网页真实标题，不能作为内容线索
+    const named = title.length > 0 && !title.startsWith('未命名专题') ? `《${inline(title)}》` : '';
+    const platform = webLink.platform === 'bilibili' ? 'B 站视频' : webLink.platform === 'youtube' ? 'YouTube 视频' : '网页';
+    return [
+        `[学习网页] 本专题是链接专题，资料是${platform}${named}：${inline(webLink.url)}`,
+        '需要网页内容时先用联网搜索了解其公开信息（标题、简介、章节或字幕要点），不要凭 URL / 编号想象内容；',
+        '确实取不到内容时如实告诉用户，并请用户把要讲的关键文字粘贴到对话里。',
+    ].join('');
+}
 /**
  * 文件清单：源文件一组在前，产物一组在后（组内保持原顺序）。
  * @param files 上下文文件（已按当前文件范围取好）
  * @param fileScope 文件范围；`selected` 时使用「仅使用勾选文件」的说明行
+ * @param hasWebLink 是否为链接专题：没有文件时省略清单，避免「暂无可用文件」与链接段自相矛盾
  */
-function renderFiles(files, fileScope) {
+function renderFiles(files, fileScope, hasWebLink) {
+    if (files.length === 0 && hasWebLink)
+        return '';
     const sources = files.filter((file) => !isProductFile(file));
     const products = files.filter(isProductFile);
     const lines = [fileScope === 'selected' ? filesIntroSelected(files.length) : FILES_INTRO];
@@ -230,6 +255,16 @@ function renderStoppedLine(task, requestId) {
 function renderNewTopicLine(task) {
     if (task.topicId !== NEW_TOPIC_SCOPE)
         return '';
+    if (task.kind === 'scene') {
+        const exts = (task.sceneExts ?? []).map((ext) => `.${inline(ext)}`).join(' / ');
+        const maxMb = Math.floor(getConfig().limits.sceneDeliverFileMaxBytes / (1024 * 1024));
+        return [
+            '- 新建专题：本任务来自学习空间首页「精选场景」，没有专题资料，无需下载资料；',
+            '请按技能说明，围绕用户本条消息的需求（表单参数中的 prompt 仅供参考）生成作品；',
+            `产物只允许 ${exts || '（未声明）'} 格式，文件名以「产物文件名」为准，扩展名可按实际产物在允许格式中替换；`,
+            `视频须完成渲染编码后再交付，单个文件不超过 ${maxMb}MB；交付后 MCP 会自动新建场景专题（专题名为场景标题）并保存作品。`,
+        ].join('');
+    }
     return [
         '- 新建专题：本任务来自学习空间首页「AI 生课」，没有专题资料，无需下载资料，',
         '请围绕表单参数 question 中的问题生成互动课程；产物 HTML 的 title 标签会作为新专题名，请写成简洁的课程标题；',
@@ -342,7 +377,8 @@ export function buildHookText(input) {
         renderReading(context.reading),
         renderSelection(context.selection),
         renderExpert(context.expert),
-        renderFiles(context.files, context.fileScope),
+        renderWebLink(context.webLink),
+        renderFiles(context.files, context.fileScope, context.webLink !== undefined),
     ]);
     return composeWithinBudget(renderHeader(context), body, pendingTasks, maxChars);
 }

package/dist/landed-store.js

@@ -8,7 +8,7 @@
  */
 import { getConfig } from './config.js';
 /** 合法的生成类别 */
-const GENERATION_KINDS = Object.freeze(['note', 'quiz', 'flashcard', 'course']);
+const GENERATION_KINDS = Object.freeze(['note', 'quiz', 'flashcard', 'course', 'scene']);
 /** 必须为非空字符串的通知字段 */
 const REQUIRED_STRING_FIELDS = ['requestId', 'topicId', 'fileName'];
 /**