tencent-edu-assistant-connector 0.1.4 → 0.2.0

package/README.md

@@ -39,9 +39,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/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;
 /** 一分钟（毫秒） */

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/hook-text.js

@@ -9,7 +9,7 @@
  * - 不输出 token（`GenerationTask.token` 不参与渲染）。
  * - 所有外部来源字符串的尖括号替换为全角，防止伪造 `</system-reminder>` 等标签；单行字段的换行折叠为空格。
  * - 总长不超过 `maxChars`。截断优先级（先保留 → 先截断）：头部（专题信息）与未完成任务段始终保留；
- *   正文段按「阅读位置 → 选区 → 专家 → 文件清单」排列，只从正文尾部截断，因此签名地址很长的文件清单最先被截断，
+ *   正文段按「阅读位置 → 选区 → 专家 → 学习网页 → 文件清单」排列，只从正文尾部截断，因此签名地址很长的文件清单最先被截断，
  *   清单说明行提示模型可调用 `get_page_context` 获取全部文件。头部与任务段本身超长时，先把各任务的表单参数
  *   压缩到 {@link PARAMS_COMPACT_MAX_CHARS} 字（requestId / 进度上报 / 交付要求行完整保留）再重试；仍超长才退化为整体截断。
  */
@@ -109,12 +109,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];
@@ -342,7 +365,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/tools.js

@@ -9,6 +9,7 @@
 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 { contextStore as defaultContextStore } from './context-store.js';
 import { uploadArtifactToTopic } from './cos-upload.js';
 import { generationStore as defaultGenerationStore, isUnfinishedStatus } from './generation-store.js';
@@ -22,8 +23,27 @@ import { readPackageVersion } from './version.js';
 import { isWbFileError, readWbFile } from './wb-files.js';
 /** 无页面上下文时的提示 */
 export const NO_CONTEXT_MESSAGE = '当前没有学习空间页面上下文，请让用户先在 WorkBuddy 中打开专题详情页';
-/** 无页面上下文时工具返回给模型的完整提示文本（get_page_context 与查询类工具同源） */
-const NO_CONTEXT_TOOL_TEXT = `${NO_CONTEXT_MESSAGE}。在此之前只能基于用户在对话中描述的内容作答。`;
+/** 连接状态工具名（无需页面上下文即可调用，用于自检与排查） */
+const STATUS_TOOL_NAME = 'get_connector_status';
+/** 本机服务端口（`LB_TOPIC_MCP_PORT` 与 stdio 入口同源；非法或缺省时用默认端口） */
+function localPort() {
+    const raw = process.env.LB_TOPIC_MCP_PORT?.trim() ?? '';
+    const port = /^\d+$/.test(raw) ? Number(raw) : Number.NaN;
+    return port >= 1 && port <= 65_535 ? port : DEFAULT_PORT;
+}
+/**
+ * 无页面上下文时工具返回给模型的完整提示文本（get_page_context 与查询类工具同源）。
+ *
+ * 首次使用最常见的情形就是「还没打开专题页」：这里明确说明连接器本身是好的、端口在哪里、
+ * 打开页面后会自动连接，并指向自检工具，避免模型只回一句「没有上下文」后无法继续。
+ */
+function noContextToolText() {
+    return [
+        `${NO_CONTEXT_MESSAGE}。`,
+        `连接器本身运行正常（v${readPackageVersion()}，本机 127.0.0.1:${localPort()}），用户打开专题详情页后 1~2 秒内会自动连接。`,
+        '在此之前只能基于用户在对话中描述的内容作答；需要排查连接问题时调用 get_connector_status。',
+    ].join('');
+}
 /** 无页面上下文错误码（follower 经 HTTP 转发时按 code 跨进程还原） */
 export const NO_CONTEXT_ERROR_CODE = 'LB_NO_PAGE_CONTEXT';
 /** 创建无页面上下文错误（消息为 {@link NO_CONTEXT_MESSAGE}） */
@@ -333,7 +353,7 @@ async function runTool(run) {
     }
     catch (error) {
         if (isNoContextError(error))
-            return { content: [{ type: 'text', text: NO_CONTEXT_TOOL_TEXT }] };
+            return { content: [{ type: 'text', text: noContextToolText() }] };
         return { isError: true, content: [{ type: 'text', text: `调用失败：${describeError(error)}` }] };
     }
 }
@@ -345,7 +365,7 @@ async function runTool(run) {
  */
 function renderPageContext(ctx, tasks) {
     if (!ctx && tasks.length === 0)
-        return NO_CONTEXT_TOOL_TEXT;
+        return noContextToolText();
     return buildHookText({ context: ctx, pendingTasks: tasks, maxChars: Number.MAX_SAFE_INTEGER });
 }
 /**
@@ -380,11 +400,118 @@ function renderDelivered(result) {
     ].join('');
 }
 /**
- * 注册上下文类工具：get_page_context、get_active_expert。
+ * 相对时间文案（用于状态里的「N 秒前更新」）。
+ * @param elapsedMs 距今毫秒数
+ */
+function formatElapsed(elapsedMs) {
+    if (!Number.isFinite(elapsedMs) || elapsedMs < 1000)
+        return '刚刚';
+    const seconds = Math.floor(elapsedMs / 1000);
+    if (seconds < 60)
+        return `${seconds} 秒前`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes} 分钟前`;
+    return `${Math.floor(minutes / 60)} 小时前`;
+}
+/**
+ * 待完成任务按类别汇总，如「（笔记 1、测验 2）」；无任务时为空串。
+ * @param tasks 待完成任务
+ */
+function summarizeTaskKinds(tasks) {
+    const counts = new Map();
+    for (const task of tasks)
+        counts.set(task.kind, (counts.get(task.kind) ?? 0) + 1);
+    if (counts.size === 0)
+        return '';
+    const parts = [...counts].map(([kind, count]) => `${KIND_LABELS[kind]} ${count}`);
+    return `（${parts.join('、')}）`;
+}
+/** 已连接 / 未连接都适用的能力说明 */
+const STATUS_CAPABILITIES = [
+    '能做什么：',
+    '1. 基于当前专题资料答疑：总结、讲解、翻译、出题；',
+    '2. 按专题页的生成按钮产出笔记 / 测验 / 闪卡 / 互动课程，并自动回填专题；',
+    '3. 学习空间首页「AI 生课」：围绕一个问题生成互动课程并新建专题。',
+].join('\n');
+/** 未连接时的下一步与排查建议 */
+const STATUS_NEXT_STEPS = [
+    '下一步：',
+    '1. 在 WorkBuddy 中打开「腾讯教育学习助手 · 学习空间」，进入任意专题详情页；',
+    '2. 页面会在 1~2 秒内自动连接，再调用本工具会显示「已连接」；',
+    '3. 连接后直接提问，或在专题页点击生成按钮。',
+    '排查：确认 WorkBuddy「连接器」中「腾讯教育学习助手」已启用；首次安装需等下载完成；发送任意消息后刷新页面；提示端口被占用时，关闭占用该端口的程序即可自动恢复。',
+].join('\n');
+/** 已连接时的下一步 */
+const STATUS_CONNECTED_NEXT = '下一步：直接提问，或在学习空间专题页点击生成按钮。';
+/**
+ * 单行化外部来源字段：尖括号转全角、换行折叠为空格，防止伪造状态行。
+ * @param value 外部来源字符串
+ */
+function oneLine(value) {
+    return escapeAngleBrackets(value).replace(/\s*[\r\n]+\s*/g, ' ');
+}
+/**
+ * 渲染连接状态（始终可读，不依赖页面上下文）：本机服务、页面连接、待完成任务、能力与下一步。
+ * @param context 当前页面上下文；`null` 表示未连接
+ * @param tasks 待完成的生成任务
+ * @param problem 本机服务异常信息；`null` 表示服务正常
+ */
+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);
+        return lines.join('\n');
+    }
+    lines.push('- 本机服务：运行中');
+    if (context) {
+        const details = [`专题《${oneLine(context.topicTitle) || '未命名'}》(id=${oneLine(context.topicId)})`];
+        if (context.webLink)
+            details.push(`学习网页 ${oneLine(context.webLink.url)}`);
+        else
+            details.push(`资料 ${context.files.length} 份`);
+        if (context.expert)
+            details.push(`答疑专家：${oneLine(context.expert.name)}`);
+        details.push(`${formatElapsed(Date.now() - context.updatedAt)}更新`);
+        lines.push(`- 页面连接：已连接 · ${details.join(' · ')}`);
+    }
+    else {
+        lines.push('- 页面连接：未连接（还没有收到学习空间页面的上报）');
+    }
+    lines.push(`- 待完成的生成任务：${tasks.length} 个${summarizeTaskKinds(tasks)}`);
+    lines.push('', STATUS_CAPABILITIES, '', context ? STATUS_CONNECTED_NEXT : STATUS_NEXT_STEPS);
+    return lines.join('\n');
+}
+/**
+ * 注册自检工具：get_connector_status。
+ * 不依赖页面上下文与后端接口，服务异常（如端口被占用）时也返回可读状态。
+ * @param server MCP Server
+ * @param backend 执行层
+ */
+function registerStatusTool(server, backend) {
+    server.registerTool(STATUS_TOOL_NAME, {
+        title: '查看连接器状态',
+        description: '查看本机连接器是否正常、是否已连上学习空间页面、当前专题与待完成生成任务，并给出下一步操作与排查建议。' +
+            '用户问「连上了吗 / 现在能做什么 / 页面怎么没反应」，或页面提示未连接时调用；本工具不需要页面上下文，任何时候都可调用。',
+    }, () => runTool(async () => {
+        try {
+            const [context, tasks] = await Promise.all([backend.getPageContext(), backend.getPendingTasks()]);
+            return renderConnectorStatus(context, tasks, null);
+        }
+        catch (error) {
+            // 自检工具本身不应失败：把服务异常渲染成状态，便于用户按提示处理
+            return renderConnectorStatus(null, [], describeError(error));
+        }
+    }));
+}
+/**
+ * 注册上下文类工具：get_page_context、get_active_expert、get_connector_status。
  * @param server MCP Server
  * @param backend 执行层
  */
 function registerContextTools(server, backend) {
+    registerStatusTool(server, backend);
     server.registerTool('get_page_context', {
         title: '读取当前页面上下文',
         description: '读取用户在「学习空间 · 专题详情」页面的上下文：专题、全部文件清单（已签名下载地址）、阅读位置、答疑专家、选中文本，' +
@@ -514,7 +641,7 @@ function registerProgressTool(server, backend) {
     }));
 }
 /**
- * 注册全部 7 个工具。
+ * 注册全部 8 个工具。
  * @param server MCP Server
  * @param backend 执行层
  */
@@ -530,7 +657,9 @@ const SERVER_INSTRUCTIONS = [
     '用户提到「这页 / 这篇 / 这个专题 / 当前资料」而对话中没有 [学习空间页面上下文] 时，调用 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} 上报进度；`,
     `完成页面登记的生成任务后，调用 ${DELIVER_TOOL_NAME} 交付产物文件。`,
 ].join('\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tencent-edu-assistant-connector",
-  "version": "0.1.4",
+  "version": "0.2.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.1.4"
+      "version": "0.2.0"
     }
   ]
 }

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

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