tencent-edu-assistant-connector 0.2.0 → 0.3.0

package/README.md

@@ -7,6 +7,7 @@
 - **基于当前专题对话**：「这一页讲的是什么？帮我总结一下」「用当前专家的口吻解释一下我选中的这段话」
 - **一键生成学习产物**：在专题页点击生成笔记 / 测验 / 闪卡 / 互动课程，WorkBuddy 生成后自动回填到专题，页面实时显示进度
 - **首页 AI 生课**：围绕一个问题生成互动课程，并自动创建新专题
+- **首页精选场景**：按场景技能生成网页或视频作品（≤ 200MB），并自动创建场景专题
 
 ## 安装
 

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

@@ -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/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

@@ -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。',
 });
 /**
  * 把尖括号替换为全角，保留其余字符（含换行）。
@@ -253,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 标签会作为新专题名，请写成简洁的课程标题；',

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'];
 /**

package/dist/new-topic.js

@@ -1,10 +1,11 @@
 /**
- * 「新建专题」交付（学习空间首页 WB 内「AI 生课」）：任务登记在保留作用域 {@link NEW_TOPIC_SCOPE} 下，
- * 交付时由 MCP 完成「建专题 → 上传 COS 并登记 → 置 ready」，对齐前端 course-generate「发布课程」的落库结果
- * （`topic_type=ai_lesson`、产物登记为 `course` 类型、专题状态 `ready`）。
+ * 「新建专题」交付（学习空间首页 WB 内「AI 生课」/「精选场景」）：任务登记在保留作用域 {@link NEW_TOPIC_SCOPE} 下，
+ * 交付时由 MCP 完成「建专题 → 上传 COS 并登记 → 置 ready」：
+ * - AI 生课：对齐前端 course-generate「发布课程」的落库结果（`topic_type=ai_lesson`、产物登记为 `course`、专题 `ready`）；
+ * - 精选场景：`topic_type=scene` + `scene_id`（后端按可见性校验场景并回填分类与技能快照），产物登记为 `scene`。
  *
- * - 专题名：优先取产物 HTML 的 `<title>`（解码实体、折叠空白、≤ 100 字），取不到用任务的 `newTopicName`；
- *   重名（业务码 4042）时追加时间后缀重试一次。
+ * - 专题名：AI 生课优先取产物 HTML 的 `<title>`（解码实体、折叠空白、≤ 100 字），取不到用任务的 `newTopicName`；
+ *   场景直接用 `newTopicName`（场景标题）。重名（业务码 4042）时追加时间后缀重试一次。
  * - 原子性：建专题后上传 / 置 ready 任一步失败都删除该专题（软删除，失败只记日志）再抛错，
  *   任务保持未完成，模型可修正后重试交付（重试会重新建专题）。
  *
@@ -78,15 +79,19 @@ function isNameConflict(error) {
     return describeError(error).includes(TOPIC_NAME_CONFLICT_CODE);
 }
 /**
- * 以 building 状态新建 ai_lesson 专题；重名时追加时间后缀重试一次。
+ * 以 building 状态新建专题（ai_lesson / scene）；重名时追加时间后缀重试一次。
  * @param api 后端接口
  * @param token 登录 token
  * @param name 规范化后的专题名
+ * @param spec 专题类型
  * @param now 时钟
  */
-async function createBuildingTopic(api, token, name, now) {
+async function createBuildingTopic(api, token, name, spec, now) {
+    const typeFields = spec.topicType === 'scene'
+        ? { topic_type: 'scene', scene_id: spec.sceneId, status: 'building' }
+        : { topic_type: 'ai_lesson', status: 'building' };
     const create = async (topicName) => {
-        const rsp = await api.createTopic(token, { name: topicName, topic_type: 'ai_lesson', status: 'building' });
+        const rsp = await api.createTopic(token, { name: topicName, ...typeFields });
         const id = rsp.topic?.id;
         if (typeof id !== 'string' || !id)
             throw new Error('新建专题失败：后端未返回专题 ID');
@@ -117,15 +122,17 @@ async function rollbackTopic(deps, token, topicId) {
     }
 }
 /**
- * 新建专题并落库产物：建专题（ai_lesson, building）→ 上传登记 → 置 ready；后两步失败删除专题后重抛。
- * @param input token、HTML、兜底名与上传函数
+ * 新建专题并落库产物：建专题（ai_lesson / scene，building）→ 上传登记 → 置 ready；后两步失败删除专题后重抛。
+ * @param input token、专题类型、HTML、名称与上传函数
  * @param deps 后端接口、日志与时钟
  */
 export async function landToNewTopic(input, deps) {
-    const name = extractHtmlTitle(input.html) ?? normalizeTopicName(input.fallbackName);
+    const spec = input.topic ?? { topicType: 'ai_lesson' };
+    const htmlTitle = spec.topicType === 'ai_lesson' && input.html !== undefined ? extractHtmlTitle(input.html) : undefined;
+    const name = htmlTitle ?? normalizeTopicName(input.fallbackName);
     if (!name)
         throw new Error('新建专题失败：专题名为空');
-    const topic = await createBuildingTopic(deps.api, input.token, name, deps.now ?? Date.now);
+    const topic = await createBuildingTopic(deps.api, input.token, name, spec, deps.now ?? Date.now);
     try {
         const { cosUrl } = await input.upload(topic.id);
         await deps.api.updateTopic(input.token, { id: topic.id, name: topic.name, status: 'ready', update_status: true });

package/dist/skill-packages.js

@@ -1,4 +1,4 @@
-/** 生成类别 → 技能 slug（与前端常量、`skill` 表一致） */
+/** 固定类别 → 技能 slug（与前端常量、`skill` 表一致）；scene 的 slug 来自场景配置，见 {@link isValidSceneSkillSlug} */
 export const SKILL_SLUG_BY_KIND = Object.freeze({
     note: 'note-generator',
     quiz: 'quiz-generator',
@@ -10,8 +10,26 @@ export const SKILL_PACKAGE_HOSTS = Object.freeze([
     'tep-app-mk-1307578727.cos.ap-guangzhou.myqcloud.com',
     'tep-app-mk-1307578727.cos.ap-guangzhou.tencentcos.cn',
 ]);
-/** 技能包在桶内的路径前缀 */
-const SKILL_PACKAGE_PATH_PREFIX = '/learningbuddy/skills/';
+/** 技能包在桶内的根路径；其下一层目录按环境区分（skills / scene-test / scene），与后端 validateScenePackageURL 一致 */
+const SKILL_PACKAGE_ROOT = '/learningbuddy/';
+/** 技能包目录名：单层、非空，只允许字母数字下划线连字符（天然排除 `.` / `..` 与编码字符） */
+const SKILL_PACKAGE_DIR_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/** 场景技能 slug：字母数字开头，只允许字母数字下划线连字符，≤ 100 字 */
+const SCENE_SKILL_SLUG_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/;
+/**
+ * MCP 支持交付的场景产物扩展名 → 规范 MIME（对齐前端 cosDirectUpload SPEC_MIME_BY_EXT；不带 charset 参数）。
+ * 后端仍按场景 `output_formats` 二次校验，不在此表内的格式（如 pptx）暂不支持在 WorkBuddy 中交付。
+ */
+export const SCENE_ARTIFACT_MIME_BY_EXT = Object.freeze({
+    html: 'text/html',
+    htm: 'text/html',
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    mov: 'video/quicktime',
+    m4v: 'video/x-m4v',
+});
+/** 文本类场景产物扩展名（交付时按 UTF-8 校验 `<html` 标签） */
+export const SCENE_HTML_EXTS = Object.freeze(['html', 'htm']);
 /**
  * 安全解析 URL。
  * @param url 待解析字符串
@@ -25,11 +43,22 @@ function parseUrl(url) {
         return null;
     }
 }
+/**
+ * 判断 pathname 是否为 `/learningbuddy/<dir>/<slug>.zip`（`<dir>` 单层，见 {@link SKILL_PACKAGE_DIR_PATTERN}）。
+ * @param pathname 规范化后的 pathname
+ * @param slug 技能 slug
+ */
+function isSkillPackagePath(pathname, slug) {
+    if (!pathname.startsWith(SKILL_PACKAGE_ROOT))
+        return false;
+    const segments = pathname.slice(SKILL_PACKAGE_ROOT.length).split('/');
+    return segments.length === 2 && SKILL_PACKAGE_DIR_PATTERN.test(segments[0] ?? '') && segments[1] === `${slug}.zip`;
+}
 /**
  * 判断技能包地址是否为白名单桶内该 slug 的技能包。
  *
  * 要求：`https:`；域名与 {@link SKILL_PACKAGE_HOSTS} 精确相等（不做后缀匹配）；无显式非默认端口；无用户名 / 密码；
- * 规范化后的 pathname 恰为 `/learningbuddy/skills/<slug>.zip`；query 不限（签名参数）；无 hash。
+ * 规范化后的 pathname 为 `/learningbuddy/<dir>/<slug>.zip`（`<dir>` 单层非空）；query 不限（签名参数）；无 hash。
  * @param url 技能包签名地址
  * @param slug 技能 slug
  * @returns 合法返回 `true`，否则（含解析失败）返回 `false`
@@ -43,6 +72,28 @@ export function isAllowedSkillPackageUrl(url, slug) {
         parsed.port === '' &&
         parsed.username === '' &&
         parsed.password === '' &&
-        parsed.pathname === `${SKILL_PACKAGE_PATH_PREFIX}${slug}.zip` &&
+        isSkillPackagePath(parsed.pathname, slug) &&
         parsed.hash === '');
 }
+/**
+ * 场景技能 slug 是否合法（作为技能包文件名，须能安全拼进路径）。
+ * @param slug 技能 slug
+ */
+export function isValidSceneSkillSlug(slug) {
+    return SCENE_SKILL_SLUG_PATTERN.test(slug);
+}
+/**
+ * 场景产物扩展名是否受 MCP 支持。
+ * @param ext 小写、不含点的扩展名
+ */
+export function isSupportedSceneExt(ext) {
+    return Object.prototype.hasOwnProperty.call(SCENE_ARTIFACT_MIME_BY_EXT, ext);
+}
+/**
+ * 取文件名扩展名（小写、不含点）；无扩展名返回空串。
+ * @param fileName 文件名
+ */
+export function fileExtOf(fileName) {
+    const idx = fileName.lastIndexOf('.');
+    return idx > 0 && idx < fileName.length - 1 ? fileName.slice(idx + 1).toLowerCase() : '';
+}

package/dist/tools.js

@@ -8,8 +8,8 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { ARTIFACT_SUFFIX_BY_KIND, validateArtifact } from './artifact-validate.js';
-import { DEFAULT_PORT } from './config.js';
+import { ARTIFACT_SUFFIX_BY_KIND, validateArtifact, validateSceneArtifact } from './artifact-validate.js';
+import { DEFAULT_PORT, getConfig } from './config.js';
 import { contextStore as defaultContextStore } from './context-store.js';
 import { uploadArtifactToTopic } from './cos-upload.js';
 import { generationStore as defaultGenerationStore, isUnfinishedStatus } from './generation-store.js';
@@ -32,16 +32,36 @@ function localPort() {
     return port >= 1 && port <= 65_535 ? port : DEFAULT_PORT;
 }
 /**
- * 无页面上下文时工具返回给模型的完整提示文本（get_page_context 与查询类工具同源）。
+ * 未连接期间的防编造约束（所有依赖页面的工具共用）。
+ * 评测中模型拿到「无上下文」后仍自拟专家与选段成稿，因此这里把禁止项逐一点名。
+ */
+const NO_CONTEXT_GUARD = '未连接期间不要假设或编造专题、资料名称与数量、页码、选中文本、答疑专家或功能入口，也不要写「示范版」代替真实内容；' +
+    '用户没在对话中给出原文时，请其打开专题详情页，或直接把原文粘贴到对话里。';
+/** 依赖页面登录态的后端查询：未连接时无法调用 */
+const NEEDS_PAGE_TOKEN = '该查询使用学习空间页面上报的登录态，页面未连接时无法调用';
+/** 各工具无页面上下文时的专属说明（让模型区分「未连接」与「查询结果为空」） */
+const NO_CONTEXT_HINTS = Object.freeze({
+    get_page_context: '因此读不到用户正在阅读的资料、页码、选中文本与页面登记的生成任务。',
+    get_active_expert: '因此无法得知用户在页面上选中的答疑专家（这不等于「用户未指定专家」）；需要作答时以通用学习助手身份回答，并说明尚未读取到专家。',
+    get_topic_detail: `${NEEDS_PAGE_TOKEN}，拿不到专题标题与资料数量，不要估算。`,
+    list_topic_menu: `${NEEDS_PAGE_TOKEN}，拿不到专题功能入口，不要自行罗列；只能按 get_connector_status 的「能做什么」概括连接器能力。`,
+    list_experts: `${NEEDS_PAGE_TOKEN}，拿不到可选专家名单。`,
+});
+/**
+ * 无页面上下文时工具返回给模型的完整提示文本。
  *
  * 首次使用最常见的情形就是「还没打开专题页」：这里明确说明连接器本身是好的、端口在哪里、
- * 打开页面后会自动连接，并指向自检工具，避免模型只回一句「没有上下文」后无法继续。
+ * 打开页面后会自动连接，并指向自检工具，避免模型只回一句「没有上下文」后无法继续；
+ * 同时按工具给出专属说明与防编造约束，避免模型把「未连接」当成「结果为空」后自行补齐内容。
+ * @param tool 调用的工具名
  */
-function noContextToolText() {
+function noContextToolText(tool) {
     return [
         `${NO_CONTEXT_MESSAGE}。`,
+        NO_CONTEXT_HINTS[tool],
         `连接器本身运行正常（v${readPackageVersion()}，本机 127.0.0.1:${localPort()}），用户打开专题详情页后 1~2 秒内会自动连接。`,
-        '在此之前只能基于用户在对话中描述的内容作答；需要排查连接问题时调用 get_connector_status。',
+        NO_CONTEXT_GUARD,
+        '需要排查连接问题时调用 get_connector_status。',
     ].join('');
 }
 /** 无页面上下文错误码（follower 经 HTTP 转发时按 code 跨进程还原） */
@@ -118,6 +138,7 @@ const KIND_LABELS = Object.freeze({
     quiz: '测验',
     flashcard: '闪卡',
     course: '课程',
+    scene: '场景作品',
 });
 /** 默认日志：只写 stderr */
 const STDERR_LOGGER = {
@@ -139,7 +160,7 @@ function resolveDeps(deps) {
         landedStore: deps.landedStore ?? defaultLandedStore,
         api: () => deps.api ?? lazyApi(),
         topicApi: () => deps.topicApi ?? lazyApi(),
-        readFile: deps.readFile ?? ((filePath) => readWbFile(filePath)),
+        readFile: deps.readFile ?? ((filePath, options) => readWbFile(filePath, { maxBytes: options?.maxBytes })),
         validate: deps.validate ?? validateArtifact,
         upload: deps.upload ?? ((input) => uploadArtifactToTopic(input)),
         now: deps.now ?? Date.now,
@@ -188,33 +209,62 @@ function assertSuffix(kind, fileName) {
     }
 }
 /**
- * 上传登记产物：普通任务上传到任务专题；新建专题任务（`NEW_TOPIC_SCOPE`）走「建专题 → 上传 → 置 ready」。
+ * 读取并校验场景产物：按场景上限读取（可能是视频），扩展名须在任务的 sceneExts 内。
+ * @param deps 依赖
+ * @param task scene 任务
+ * @param filePath 文件绝对路径
+ */
+async function prepareSceneArtifact(deps, task, filePath) {
+    const file = await deps.readFile(filePath, { maxBytes: getConfig().limits.sceneDeliverFileMaxBytes });
+    const validation = validateSceneArtifact(file.fileName, file.content, task.sceneExts ?? []);
+    if (!validation.ok)
+        throw new Error(`产物校验失败：${validation.reason}`);
+    return { fileName: file.fileName, content: validation.content };
+}
+/**
+ * 读取 → 校验后缀 → 校验内容，得到待上传产物（scene 走 {@link prepareSceneArtifact}）。
  * @param deps 依赖
  * @param task 有效任务
- * @param fileName 实际文件名
- * @param text 校验后的文本
+ * @param filePath 文件绝对路径
  */
-async function uploadToTarget(deps, task, fileName, text) {
-    const content = Buffer.from(text, 'utf8');
+async function prepareArtifact(deps, task, filePath) {
+    const kind = task.kind;
+    if (kind === 'scene')
+        return prepareSceneArtifact(deps, task, filePath);
+    const file = await deps.readFile(filePath);
+    assertSuffix(kind, file.fileName);
+    const validation = deps.validate(kind, file.fileName, file.content);
+    if (!validation.ok)
+        throw new Error(`产物校验失败：${validation.reason}`);
+    return { fileName: file.fileName, content: Buffer.from(validation.text, 'utf8'), text: validation.text };
+}
+/**
+ * 上传登记产物：普通任务上传到任务专题；新建专题任务（`NEW_TOPIC_SCOPE`）走「建专题 → 上传 → 置 ready」，
+ * course 建 ai_lesson 专题，scene 建带 scene_id 的场景专题。
+ * @param deps 依赖
+ * @param task 有效任务
+ * @param artifact 校验后的产物
+ */
+async function uploadToTarget(deps, task, artifact) {
+    const { fileName, content } = artifact;
     const upload = (topicId) => deps.upload({ token: task.token, topicId, kind: task.kind, fileName, content });
     if (task.topicId !== NEW_TOPIC_SCOPE)
         return { cosUrl: (await upload(task.topicId)).cosUrl };
-    const landed = await landToNewTopic({ token: task.token, html: text, fallbackName: task.newTopicName ?? '', upload }, { api: deps.topicApi(), logger: deps.logger, now: deps.now });
+    const topic = task.kind === 'scene'
+        ? { topicType: 'scene', sceneId: task.sceneId ?? '' }
+        : { topicType: 'ai_lesson' };
+    const landed = await landToNewTopic({ token: task.token, topic, html: artifact.text, fallbackName: task.newTopicName ?? '', upload }, { api: deps.topicApi(), logger: deps.logger, now: deps.now });
     return { cosUrl: landed.cosUrl, createdTopicId: landed.topicId, createdTopicName: landed.topicName };
 }
 /**
- * 读取 → 校验后缀 → 校验内容 → 上传登记（新建专题任务先建专题）→ 标记交付 → 写落库通知。
+ * 读取校验 → 上传登记（新建专题任务先建专题）→ 标记交付 → 写落库通知。
  * @param deps 依赖
  * @param task 有效任务
  * @param filePath 文件绝对路径
  */
 async function landArtifact(deps, task, filePath) {
-    const file = await deps.readFile(filePath);
-    assertSuffix(task.kind, file.fileName);
-    const validation = deps.validate(task.kind, file.fileName, file.content);
-    if (!validation.ok)
-        throw new Error(`产物校验失败：${validation.reason}`);
-    const target = await uploadToTarget(deps, task, file.fileName, validation.text);
+    const artifact = await prepareArtifact(deps, task, filePath);
+    const target = await uploadToTarget(deps, task, artifact);
     if (!deps.generationStore.markDelivered(task.requestId)) {
         deps.logger.warn(`[deliver] ${JSON.stringify(task.requestId)} 已落库，但任务在上传期间失效`);
     }
@@ -222,7 +272,7 @@ async function landArtifact(deps, task, filePath) {
         requestId: task.requestId,
         topicId: task.topicId,
         kind: task.kind,
-        fileName: file.fileName,
+        fileName: artifact.fileName,
         ...target,
     };
     deps.landedStore.push({
@@ -343,17 +393,18 @@ function listHeading(title, value) {
     return Array.isArray(value) ? `${title}（${value.length} 个）：` : `${title}：`;
 }
 /**
- * 执行工具：成功渲染文本结果；无页面上下文渲染普通提示文本（属正常状态，非工具故障）；
+ * 执行工具：成功渲染文本结果；无页面上下文渲染该工具的专属提示文本（属正常状态，非工具故障）；
  * 其他失败渲染 isError 结果，不抛异常。
+ * @param tool 工具名（用于无上下文提示）；不依赖页面的工具传 `null`
  * @param run 返回成功文本
  */
-async function runTool(run) {
+async function runTool(tool, run) {
     try {
         return { content: [{ type: 'text', text: await run() }] };
     }
     catch (error) {
-        if (isNoContextError(error))
-            return { content: [{ type: 'text', text: noContextToolText() }] };
+        if (tool && isNoContextError(error))
+            return { content: [{ type: 'text', text: noContextToolText(tool) }] };
         return { isError: true, content: [{ type: 'text', text: `调用失败：${describeError(error)}` }] };
     }
 }
@@ -365,7 +416,7 @@ async function runTool(run) {
  */
 function renderPageContext(ctx, tasks) {
     if (!ctx && tasks.length === 0)
-        return noContextToolText();
+        return noContextToolText('get_page_context');
     return buildHookText({ context: ctx, pendingTasks: tasks, maxChars: Number.MAX_SAFE_INTEGER });
 }
 /**
@@ -391,7 +442,8 @@ function renderDelivered(result) {
         const name = escapeAngleBrackets(result.createdTopicName ?? '');
         return [
             `已新建专题「${name}」（id=${escapeAngleBrackets(result.createdTopicId)}）并交付${KIND_LABELS[result.kind]}「${fileName}」，`,
-            '学习空间首页会自动刷新展示。请用一句话告诉用户课程已生成、可在学习空间打开该专题，不要复述文件内容。',
+            `学习空间首页会自动刷新展示。请用一句话告诉用户${result.kind === 'scene' ? '作品' : '课程'}已生成、`,
+            '可在学习空间打开该专题，不要复述文件内容。',
         ].join('');
     }
     return [
@@ -432,7 +484,8 @@ const STATUS_CAPABILITIES = [
     '能做什么：',
     '1. 基于当前专题资料答疑：总结、讲解、翻译、出题；',
     '2. 按专题页的生成按钮产出笔记 / 测验 / 闪卡 / 互动课程，并自动回填专题；',
-    '3. 学习空间首页「AI 生课」：围绕一个问题生成互动课程并新建专题。',
+    '3. 学习空间首页「AI 生课」：围绕一个问题生成互动课程并新建专题；',
+    '4. 学习空间首页「精选场景」：按场景技能生成网页或视频作品并新建场景专题。',
 ].join('\n');
 /** 未连接时的下一步与排查建议 */
 const STATUS_NEXT_STEPS = [
@@ -444,6 +497,26 @@ const STATUS_NEXT_STEPS = [
 ].join('\n');
 /** 已连接时的下一步 */
 const STATUS_CONNECTED_NEXT = '下一步：直接提问，或在学习空间专题页点击生成按钮。';
+/** 工具清单（标注可用前提），回答「能做什么」时可直接引用工具名 */
+const STATUS_TOOLS = [
+    '可用工具：',
+    `- ${STATUS_TOOL_NAME}：连接自检（任何时候可用）；`,
+    '- get_page_context：页面上下文与待完成的生成任务（需页面已连接）；',
+    '- get_active_expert / get_topic_detail / list_topic_menu / list_experts：当前专家、专题详情、专题功能入口、可选专家（需页面已连接）；',
+    `- ${PROGRESS_TOOL_NAME} / ${DELIVER_TOOL_NAME}：上报生成进度、交付产物（需页面已登记生成任务）。`,
+].join('\n');
+/** 未连接时的数据边界 */
+const STATUS_DISCONNECTED_LIMIT = '未连接期间：专题标题、资料数量、阅读位置、选中文本、答疑专家与专题功能入口都无法读取，不要自行罗列或编造；只能基于用户在对话中给出的内容作答。';
+/**
+ * 无待完成任务时的说明：用户声称页面上有未完成任务时，帮助模型给出原因而非臆测任务内容。
+ * @param isConnected 页面是否已连接
+ */
+function noPendingTaskHint(isConnected) {
+    const reason = isConnected
+        ? '任务登记后超过 30 分钟未执行会过期，同一类别再次点击生成也会覆盖旧任务'
+        : '页面未连接时连接器看不到该专题登记的任务；任务登记后超过 30 分钟未执行也会过期';
+    return `若用户说页面上有未完成的生成任务：${reason}。请用户在专题页侧栏重新点击生成，不要在没有任务的情况下自行生成或声称已交付。`;
+}
 /**
  * 单行化外部来源字段：尖括号转全角、换行折叠为空格，防止伪造状态行。
  * @param value 外部来源字符串
@@ -461,7 +534,7 @@ function renderConnectorStatus(context, tasks, problem) {
     const lines = [`[连接器状态] 腾讯教育学习助手 连接器 v${readPackageVersion()} · 本机 127.0.0.1:${localPort()}`];
     if (problem !== null) {
         lines.push(`- 本机服务：异常（${oneLine(problem)}）`, '- 页面连接：无法确认');
-        lines.push('', STATUS_CAPABILITIES, '', STATUS_NEXT_STEPS);
+        lines.push('', STATUS_CAPABILITIES, '', STATUS_TOOLS, '', STATUS_NEXT_STEPS);
         return lines.join('\n');
     }
     lines.push('- 本机服务：运行中');
@@ -480,7 +553,12 @@ function renderConnectorStatus(context, tasks, problem) {
         lines.push('- 页面连接：未连接（还没有收到学习空间页面的上报）');
     }
     lines.push(`- 待完成的生成任务：${tasks.length} 个${summarizeTaskKinds(tasks)}`);
-    lines.push('', STATUS_CAPABILITIES, '', context ? STATUS_CONNECTED_NEXT : STATUS_NEXT_STEPS);
+    if (tasks.length === 0)
+        lines.push(noPendingTaskHint(context !== null));
+    lines.push('', STATUS_CAPABILITIES, '', STATUS_TOOLS);
+    if (!context)
+        lines.push('', STATUS_DISCONNECTED_LIMIT);
+    lines.push('', context ? STATUS_CONNECTED_NEXT : STATUS_NEXT_STEPS);
     return lines.join('\n');
 }
 /**
@@ -494,7 +572,7 @@ function registerStatusTool(server, backend) {
         title: '查看连接器状态',
         description: '查看本机连接器是否正常、是否已连上学习空间页面、当前专题与待完成生成任务，并给出下一步操作与排查建议。' +
             '用户问「连上了吗 / 现在能做什么 / 页面怎么没反应」，或页面提示未连接时调用；本工具不需要页面上下文，任何时候都可调用。',
-    }, () => runTool(async () => {
+    }, () => runTool(null, async () => {
         try {
             const [context, tasks] = await Promise.all([backend.getPageContext(), backend.getPendingTasks()]);
             return renderConnectorStatus(context, tasks, null);
@@ -505,6 +583,8 @@ function registerStatusTool(server, backend) {
         }
     }));
 }
+/** 依赖页面连接的工具描述后缀：让模型在调用前就知道前提，失败后不把「未连接」当成「结果为空」 */
+const PAGE_REQUIRED_NOTE = '需要学习空间页面已连接；未连接时返回说明文本（非数据），不要据此自行补齐或编造内容。';
 /**
  * 注册上下文类工具：get_page_context、get_active_expert、get_connector_status。
  * @param server MCP Server
@@ -516,7 +596,7 @@ function registerContextTools(server, backend) {
         title: '读取当前页面上下文',
         description: '读取用户在「学习空间 · 专题详情」页面的上下文：专题、全部文件清单（已签名下载地址）、阅读位置、答疑专家、选中文本，' +
             '以及页面登记的 [待完成的生成任务]（requestId、技能包、产物文件名、表单参数、进度上报与交付要求）。' +
-            '用户要求生成笔记 / 测验 / 闪卡 / 课程，或消息中出现学习空间任务 requestId 时，必须先调用本工具获取任务要求再执行。' +
+            '用户要求生成笔记 / 测验 / 闪卡 / 课程 / 场景作品，或消息中出现学习空间任务 requestId 时，必须先调用本工具获取任务要求再执行。' +
             '资料原文只能通过返回的签名地址下载读取，禁止在本地磁盘搜索同名文件。',
         inputSchema: {
             requestId: z
@@ -527,7 +607,7 @@ function registerContextTools(server, backend) {
                 .describe('仅当用户本条消息里出现「学习空间任务 requestId：xxx」时原样传入；用于让页面立即进入生成中。' +
                 '普通答疑 / 总结 / 闲聊不要传。'),
         },
-    }, ({ requestId }, extra) => runTool(async () => {
+    }, ({ requestId }, extra) => runTool('get_page_context', async () => {
         // 连接器形态没有 UserPromptSubmit Hook：由模型回传的 requestId 兜底把该任务标为「已发送」，
         // 只影响该 requestId，未传时不改变任何状态（正常对话零影响）。
         if (requestId !== undefined)
@@ -537,8 +617,9 @@ function registerContextTools(server, backend) {
     }));
     server.registerTool('get_active_expert', {
         title: '读取用户指定的答疑专家',
-        description: '读取用户在学习空间页面上选中的答疑专家及其档案；若返回了专家，回答时请代入该专家身份与风格。',
-    }, () => runTool(async () => renderExpert(await backend.getActiveExpert())));
+        description: '读取用户在学习空间页面上选中的答疑专家及其档案；若返回了专家，回答时请代入该专家身份与风格。' +
+            `只读页面上下文，${PAGE_REQUIRED_NOTE}`,
+    }, () => runTool('get_active_expert', async () => renderExpert(await backend.getActiveExpert())));
 }
 /**
  * 注册后端查询类工具：get_topic_detail、list_topic_menu、list_experts。
@@ -548,7 +629,8 @@ function registerContextTools(server, backend) {
 function registerQueryTools(server, backend) {
     server.registerTool('get_topic_detail', {
         title: '查询专题详情',
-        description: '查询学习空间专题详情（权威数据）。不传 topicId 时使用当前页面正在查看的专题。',
+        description: '查询学习空间专题详情（权威数据）。不传 topicId 时使用当前页面正在查看的专题。' +
+            `使用页面上报的登录态，${PAGE_REQUIRED_NOTE}`,
         inputSchema: {
             topicId: z
                 .string()
@@ -557,18 +639,20 @@ function registerQueryTools(server, backend) {
                 .optional()
                 .describe('专题 ID（字母、数字、下划线、连字符）；省略则取当前页面的专题'),
         },
-    }, ({ topicId }) => runTool(async () => `专题详情：\n${formatJson(await backend.getTopicDetail(topicId))}`));
+    }, ({ topicId }) => runTool('get_topic_detail', async () => `专题详情：\n${formatJson(await backend.getTopicDetail(topicId))}`));
     server.registerTool('list_topic_menu', {
         title: '查询专题功能入口',
-        description: '查询专题详情页的功能入口列表（资料精读 / 视频学习 / AI 生课等），用于回答「这个专题能做什么」。',
-    }, () => runTool(async () => {
+        description: '查询专题详情页的功能入口列表（资料精读 / 视频学习 / AI 生课等），用于回答「这个专题能做什么」。' +
+            `使用页面上报的登录态，${PAGE_REQUIRED_NOTE}`,
+    }, () => runTool('list_topic_menu', async () => {
         const list = await backend.listTopicMenu();
         return `${listHeading('专题功能入口', list)}\n${formatJson(list)}`;
     }));
     server.registerTool('list_experts', {
         title: '查询学科专家',
-        description: '查询学习空间可用的学科专家（自定义专家市场），用于用户想换个专家来答时查看可选项。',
-    }, () => runTool(async () => {
+        description: '查询学习空间可用的学科专家（自定义专家市场），用于用户想换个专家来答时查看可选项。' +
+            `使用页面上报的登录态，${PAGE_REQUIRED_NOTE}`,
+    }, () => runTool('list_experts', async () => {
         const experts = await backend.listExperts();
         return `${listHeading('可用学科专家', experts)}\n${formatJson(experts)}`;
     }));
@@ -587,12 +671,13 @@ function registerDeliverTool(server, backend) {
         description: '完成页面登记的生成任务后调用：把已写入 WorkBuddy 工作目录的产物文件上传并保存到专题，页面随即展示。' +
             'requestId 取自 [待完成的生成任务]（Hook 注入或 get_page_context 返回）中的 requestId，原样传入；' +
             'filePath 必须是产物文件的绝对路径，不要把文件内容贴进参数。' +
-            `文件名后缀须与任务类别一致：${suffixes}。失败时根据错误修正后可重试。`,
+            `文件名后缀须与任务类别一致：${suffixes}；` +
+            '场景作品的扩展名须在任务给出的允许格式内（如 .html / .mp4，视频须已完成渲染编码）。失败时根据错误修正后可重试。',
         inputSchema: {
             requestId: z.string().min(1).max(128).describe('[待完成的生成任务] 中的 requestId'),
             filePath: z.string().min(1).max(4096).describe('产物文件的绝对路径（位于 WorkBuddy 工作目录内）'),
         },
-    }, ({ requestId, filePath }) => runTool(async () => renderDelivered(await backend.deliverFile(requestId, filePath))));
+    }, ({ requestId, filePath }) => runTool(null, async () => renderDelivered(await backend.deliverFile(requestId, filePath))));
 }
 /** 进度上报工具描述 */
 const PROGRESS_TOOL_DESCRIPTION = [
@@ -632,7 +717,7 @@ function registerProgressTool(server, backend) {
             requestId: z.string().min(1).max(128).describe('[待完成的生成任务] 中的 requestId'),
             ...PROGRESS_REPORT_SHAPE,
         },
-    }, ({ requestId, ...args }) => runTool(async () => {
+    }, ({ requestId, ...args }) => runTool(null, async () => {
         if (args.stage === 'failed' && (args.error ?? '').trim().length === 0) {
             throw new Error(PROGRESS_ERROR_REQUIRED_MESSAGE);
         }
@@ -655,9 +740,10 @@ export function registerTools(server, backend) {
 const SERVER_INSTRUCTIONS = [
     '本服务连接用户在 WorkBuddy 内打开的「学习空间」专题详情页。',
     '用户提到「这页 / 这篇 / 这个专题 / 当前资料」而对话中没有 [学习空间页面上下文] 时，调用 get_page_context；',
-    '用户要求生成笔记 / 测验 / 闪卡 / 课程，或消息中带有学习空间任务 requestId 而对话中没有 [待完成的生成任务] 时，先调用 get_page_context，严格按其中的技能、进度上报与交付要求执行；',
+    '用户要求生成笔记 / 测验 / 闪卡 / 课程 / 场景作品，或消息中带有学习空间任务 requestId 而对话中没有 [待完成的生成任务] 时，先调用 get_page_context，严格按其中的技能、进度上报与交付要求执行；',
     '调用 get_page_context 时，若用户本条消息里出现「学习空间任务 requestId：xxx」，把该 id 作为 requestId 入参原样传入（页面据此立即显示生成中），并把它作为本次回复的第一个动作，不要先输出大段文字；其它答疑 / 总结 / 闲聊场景不要传该入参；',
     'get_page_context 返回「当前没有学习空间页面上下文」时，告诉用户先打开专题详情页，并按返回的下一步（或调用 get_connector_status）给出状态与排查建议；',
+    '页面未连接期间不要假设或编造专题、资料、页码、选中文本、答疑专家或功能入口，也不要写「示范版」代替真实内容，请用户打开专题页或把原文粘贴到对话里；',
     `用户问「连上了吗 / 现在能做什么 / 页面怎么没反应」，或需要确认服务是否正常时，调用 ${STATUS_TOOL_NAME}；它不需要页面上下文，任何时候都可调用；`,
     '资料原文请通过上下文中的签名地址下载，不要在本地磁盘搜索同名文件；链接专题只给了网页链接时，先用联网搜索了解其公开信息，不要凭 URL 想象内容；',
     `执行页面登记的生成任务时，各阶段调用 ${PROGRESS_TOOL_NAME} 上报进度；`,

package/dist/types.js

@@ -5,8 +5,8 @@
  * 统一引用本文件，保证字段口径一致。
  */
 /**
- * 「新建专题」保留作用域：学习空间首页 WB 内「AI 生课」登记任务时以此代替专题 ID（此时专题尚不存在），
- * 交付时由 MCP 新建 ai_lesson 专题再上传产物。真实专题 ID 为 32 位十六进制，不会与之冲突。
- * 仅允许 `course` 类别使用。
+ * 「新建专题」保留作用域：学习空间首页 WB 内「AI 生课」/「精选场景」登记任务时以此代替专题 ID（此时专题尚不存在），
+ * 交付时由 MCP 新建专题再上传产物（course → ai_lesson 专题；scene → scene 专题）。
+ * 真实专题 ID 为 32 位十六进制，不会与之冲突。仅允许 `course` / `scene` 类别使用。
  */
 export const NEW_TOPIC_SCOPE = 'new-topic';

package/dist/wb-files.js

@@ -5,7 +5,7 @@
  * - 只接受绝对路径；rootDir 与 filePath 都做 realpath，真实路径必须严格位于 rootDir 之下（root 本身不允许）。
  * - 越界 / 不存在 / 非普通文件统一为同一条错误消息，不暴露文件是否存在，也不透出原始 errno 信息。
  * - 防 TOCTOU：open 后基于同一 FileHandle 做 stat 与读取；open 带 `O_NOFOLLOW`（防最后一段被替换为软链）
- *   与 `O_NONBLOCK`（防 FIFO 阻塞）；读取最多 `maxBytes + 1` 字节，防 stat 后被追加。
+ *   与 `O_NONBLOCK`（防 FIFO 阻塞）；按 stat 大小读取并多读 1 字节，防 stat 后被追加。
  */
 import { constants as fsConstants, promises as fs } from 'node:fs';
 import os from 'node:os';
@@ -20,6 +20,7 @@ const WB_FILE_ERROR_CODES = Object.freeze([
     'WB_FILE_FORBIDDEN',
     'WB_FILE_TOO_LARGE',
     'WB_FILE_NOT_ABSOLUTE',
+    'WB_FILE_CHANGED',
 ]);
 /** 1MB 字节数 */
 const MB = 1024 * 1024;
@@ -45,6 +46,10 @@ function tooLarge(maxBytes) {
     const limit = maxBytes % MB === 0 ? `${maxBytes / MB}MB` : `${maxBytes} 字节`;
     return createWbFileError('WB_FILE_TOO_LARGE', `文件超过 ${limit} 上限`);
 }
+/** 读取期间文件被追加（多为仍在写入） */
+function changedWhileReading() {
+    return createWbFileError('WB_FILE_CHANGED', '文件在读取过程中发生变化，请确认已写入完成后重试');
+}
 /**
  * 判断是否为 WB 文件读取错误（供 tools 层转换为可读文本）。
  * @param e 任意捕获值
@@ -115,10 +120,12 @@ export async function readWbFile(filePath, options = {}) {
             throw forbidden();
         if (stat.size > maxBytes)
             throw tooLarge(maxBytes);
-        // 多读 1 字节：stat 之后文件若被追加，仍能发现超限
-        const content = await orForbidden(readUpTo(handle, maxBytes + 1));
-        if (content.length > maxBytes)
-            throw tooLarge(maxBytes);
+        // 按实际大小分配（大上限时避免一次性分配上限字节）；多读 1 字节：stat 之后文件若被追加，仍能发现
+        const expected = stat.size;
+        const content = await orForbidden(readUpTo(handle, expected + 1));
+        if (content.length > expected) {
+            throw content.length > maxBytes ? tooLarge(maxBytes) : changedWhileReading();
+        }
         return { realPath, fileName: path.basename(realPath), content, size: content.length };
     }
     finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tencent-edu-assistant-connector",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "腾讯教育学习助手 · 专题 MCP Server：为 WorkBuddy 会话提供专题页面上下文、业务查询与产物落库能力",
   "bin": {

package/plugin/.codebuddy-plugin/marketplace.json

@@ -6,7 +6,7 @@
       "name": "tencent-edu-assistant",
       "source": "./plugins/tencent-edu-assistant",
       "description": "把学习空间专题页的专题 / 资料 / 阅读位置 / 专家上下文提供给 WorkBuddy 会话，并支持生成产物回填专题",
-      "version": "0.2.0"
+      "version": "0.3.0"
     }
   ]
 }

package/plugin/plugins/tencent-edu-assistant/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tencent-edu-assistant",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "把学习空间专题页的专题 / 资料 / 阅读位置 / 专家上下文提供给 WorkBuddy 会话，并支持生成产物回填专题",
   "author": {
     "name": "tencent"