tencent-edu-assistant-connector 0.1.2 → 0.1.4

package/README.md

@@ -51,7 +51,11 @@ npx -y tencent-edu-assistant-connector@latest install
 
 **在 WorkBuddy 中点了停止，页面仍显示生成中**
 
-使用连接器时，页面会在一段时间无进度后显示「可能已停止」，可重新生成。使用插件时，重新执行安装命令并重启 WorkBuddy。
+连接器会在用户点停止后 1 秒内把该会话下正在生成的任务全部转为「已暂停」（通过旁路监听本机 WorkBuddy 会话文件，只提取任务 ID 与会话 ID，不读取对话内容）。若该机制未生效（`GET http://127.0.0.1:3101/bridge/health` 的 `transcriptWatch` 不是 `watching`），页面会在长时间无进度后显示「可能已停止」，可重新生成。使用插件时，重新执行安装命令并重启 WorkBuddy。
+
+**点了「生成」后页面没有立刻进入生成中**
+
+连接器形态下页面需要先拿到「已发送」信号。旁路监听在用户按回车后约 0.3 秒即可感知；若 `transcriptWatch` 不为 `watching`，则要等模型首次调用工具（通常几秒）。新开会话的第一条任务会额外慢约 3 秒（WorkBuddy 首次写入会话文件的开销）。
 
 **交付失败**
 

package/dist/bridge.js

@@ -7,7 +7,7 @@
  *
  * | 方法 路径 | 成功响应 |
  * |---|---|
- * | `GET /health` | `{ ok: true, service, version }` |
+ * | `GET /health` | `{ ok: true, service, version, transcriptWatch? }`（`transcriptWatch` 为 `watching` / `off` / `unavailable`，未注入监听时省略该字段） |
  * | `POST /pair` | `{ key }` |
  * | `POST /context` | `{ ok: true, updatedAt }`（心跳即重复全量上报） |
  * | `POST /context/clear` | `{ ok: true }` |
@@ -337,7 +337,12 @@ export function createBridgeRouter(deps) {
     registerHookRoutes(router, { contextStore, generationStore, logger: deps.logger ?? STDERR_LOGGER });
     router.use(express.json({ limit: BODY_LIMIT }));
     router.get('/health', (_req, res) => {
-        res.json({ ok: true, service: PACKAGE_NAME, version: deps.version });
+        const body = { ok: true, service: PACKAGE_NAME, version: deps.version };
+        // 连接器形态下页面 / 排障需要确认旁路监听是否生效；未注入时不改变响应结构
+        const transcriptWatch = deps.transcriptWatch?.();
+        if (transcriptWatch !== undefined)
+            body['transcriptWatch'] = transcriptWatch;
+        res.json(body);
     });
     router.post('/pair', (_req, res) => {
         res.json({ key: pairing.issue() });

package/dist/generation-store.js

@@ -465,6 +465,18 @@ export function createGenerationStore(options = {}) {
             }
             return changed;
         },
+        markSentByRequestId(requestId, sessionId) {
+            prune();
+            const found = findLive(requestId);
+            if (!found)
+                return false;
+            const [key, task] = found;
+            const next = applyMarkSent(task, now(), sessionId);
+            if (next === task)
+                return false;
+            slots.set(key, next);
+            return true;
+        },
         finalStop(sessionId, reason, currentTopicId) {
             if (!isFinalStopReason(reason))
                 return [];

package/dist/http.js

@@ -198,6 +198,7 @@ export function createHttpApp(deps) {
         landedStore: deps.landedStore,
         pairing,
         version: deps.version,
+        transcriptWatch: deps.transcriptWatch,
         logger,
     }));
     if (mcp.enabled) {

package/dist/internal.js

@@ -28,6 +28,7 @@ export const INTERNAL_TOOL_NAMES = Object.freeze([
     'listExperts',
     'deliverFile',
     'reportGenerationProgress',
+    'markPromptSent',
 ]);
 /** leader 不可达（切换中）时的提示 */
 export const LEADER_UNAVAILABLE_MESSAGE = '腾讯教育学习助手 本地服务正在切换，请稍后重试';
@@ -77,6 +78,10 @@ const TOOL_BINDERS = new Map([
         'reportGenerationProgress',
         bindTool(z.object({ requestId: z.string().min(1).max(128), report: z.object(PROGRESS_REPORT_SHAPE) }), (backend, args) => backend.reportGenerationProgress(args.requestId, args.report)),
     ],
+    [
+        'markPromptSent',
+        bindTool(z.object({ requestId: z.string().min(1).max(128), sessionId: z.string().max(128).optional() }), (backend, args) => backend.markPromptSent(args.requestId, args.sessionId)),
+    ],
 ]);
 /** 请求体 schema */
 const internalBodySchema = z.object({ args: z.unknown().optional() });
@@ -300,5 +305,6 @@ export function createForwardingToolBackend(options) {
         listExperts: () => call('listExperts', {}, timeoutMs),
         deliverFile: async (requestId, filePath) => (await call('deliverFile', { requestId, filePath }, deliverTimeoutMs)),
         reportGenerationProgress: async (requestId, report) => (await call('reportGenerationProgress', { requestId, report }, timeoutMs)),
+        markPromptSent: async (requestId, sessionId) => (await call('markPromptSent', sessionId === undefined ? { requestId } : { requestId, sessionId }, timeoutMs)),
     };
 }

package/dist/leader.js

@@ -89,6 +89,7 @@ function createPortInUseBackend(port) {
         listExperts: fail,
         deliverFile: fail,
         reportGenerationProgress: fail,
+        markPromptSent: fail,
     };
 }
 /**

package/dist/stdio.js

@@ -33,6 +33,7 @@ import { contextStore } from './context-store.js';
 import { DAEMON_IDLE_ENV, DAEMON_SUBCOMMAND, ensureDaemon, ensureDaemonIfAbsent, isDaemonEnabled, parseDaemonIdleMs, runDaemon, } from './daemon.js';
 import { generationStore } from './generation-store.js';
 import { createHttpApp } from './http.js';
+import { createTranscriptWatcher, TRANSCRIPT_WATCH_ENV } from './transcript-watch.js';
 import { isInstallerCommand, runInstaller } from './installer.js';
 import { landedStore } from './landed-store.js';
 import { startLeaderOrFollower } from './leader.js';
@@ -119,6 +120,7 @@ function createUnavailableBackend(message) {
         listExperts: fail,
         deliverFile: fail,
         reportGenerationProgress: fail,
+        markPromptSent: fail,
     };
 }
 /**
@@ -135,6 +137,7 @@ function createDynamicBackend(current) {
         listExperts: () => current().listExperts(),
         deliverFile: (requestId, filePath) => current().deliverFile(requestId, filePath),
         reportGenerationProgress: (requestId, report) => current().reportGenerationProgress(requestId, report),
+        markPromptSent: (requestId, sessionId) => current().markPromptSent(requestId, sessionId),
     };
 }
 /**
@@ -150,16 +153,23 @@ function resolveHome(env) {
  * @param env 环境变量
  * @param extra daemon 钩子与 follower 接管前置动作
  */
-function startElection(config, env, extra = {}) {
+async function startElection(config, env, extra = {}) {
     const localBackend = createLocalToolBackend();
     const pairing = createPairingStore();
     const version = readPackageVersion();
-    return startLeaderOrFollower({
+    // 连接器形态没有 Hook，只能靠旁路监听 WB 会话文件获得「用户已发送 / 已暂停」；只在 leader 启动
+    const transcriptWatcher = createTranscriptWatcher({
+        generationStore,
+        getCurrentTopicId: () => contextStore.getPublic()?.topicId,
+        enabled: env[TRANSCRIPT_WATCH_ENV] !== '0',
+    });
+    const handle = await startLeaderOrFollower({
         port: config.app.port,
         home: resolveHome(env),
         localBackend,
         unavailableRetryMs: config.unavailableRetryMs,
         beforeTakeover: extra.beforeTakeover,
+        onBecomeLeader: () => transcriptWatcher.start(),
         createApp: (secret) => createHttpApp({
             backend: localBackend,
             contextStore,
@@ -168,11 +178,20 @@ function startElection(config, env, extra = {}) {
             pairing,
             config: config.app,
             version,
+            transcriptWatch: () => transcriptWatcher.status(),
             mcp: { enabled: false },
             internal: { secret, onShutdown: extra.hooks?.onShutdown },
             onRequest: extra.hooks?.onRequest,
         }),
     });
+    return {
+        role: () => handle.role(),
+        backend: () => handle.backend(),
+        close: async () => {
+            transcriptWatcher.stop();
+            await handle.close();
+        },
+    };
 }
 /**
  * 后台常驻服务参数：入口为本文件（`dist/stdio.js`），环境变量原样继承。

package/dist/tools.js

@@ -292,6 +292,13 @@ export function createLocalToolBackend(deps = {}) {
                 throw new Error(PROGRESS_FAILURE_MESSAGES[result.reason]);
             return { requestId, status: result.status };
         },
+        markPromptSent: async (requestId, sessionId) => {
+            // 只迁移命中的那一个任务：不含 requestId 的答疑对话不会走到这里，天然不影响正常对话
+            const changed = resolved.generationStore.markSentByRequestId(requestId, sessionId);
+            if (changed)
+                resolved.contextStore.markPromptSent();
+            return changed;
+        },
     };
 }
 /**
@@ -384,7 +391,20 @@ function registerContextTools(server, backend) {
             '以及页面登记的 [待完成的生成任务]（requestId、技能包、产物文件名、表单参数、进度上报与交付要求）。' +
             '用户要求生成笔记 / 测验 / 闪卡 / 课程，或消息中出现学习空间任务 requestId 时，必须先调用本工具获取任务要求再执行。' +
             '资料原文只能通过返回的签名地址下载读取，禁止在本地磁盘搜索同名文件。',
-    }, () => runTool(async () => {
+        inputSchema: {
+            requestId: z
+                .string()
+                .min(1)
+                .max(128)
+                .optional()
+                .describe('仅当用户本条消息里出现「学习空间任务 requestId：xxx」时原样传入；用于让页面立即进入生成中。' +
+                '普通答疑 / 总结 / 闲聊不要传。'),
+        },
+    }, ({ requestId }, extra) => runTool(async () => {
+        // 连接器形态没有 UserPromptSubmit Hook：由模型回传的 requestId 兜底把该任务标为「已发送」，
+        // 只影响该 requestId，未传时不改变任何状态（正常对话零影响）。
+        if (requestId !== undefined)
+            await backend.markPromptSent(requestId, extra?.sessionId).catch(() => false);
         const [ctx, tasks] = await Promise.all([backend.getPageContext(), backend.getPendingTasks()]);
         return renderPageContext(ctx, tasks);
     }));
@@ -509,6 +529,7 @@ const SERVER_INSTRUCTIONS = [
     '本服务连接用户在 WorkBuddy 内打开的「学习空间」专题详情页。',
     '用户提到「这页 / 这篇 / 这个专题 / 当前资料」而对话中没有 [学习空间页面上下文] 时，调用 get_page_context；',
     '用户要求生成笔记 / 测验 / 闪卡 / 课程，或消息中带有学习空间任务 requestId 而对话中没有 [待完成的生成任务] 时，先调用 get_page_context，严格按其中的技能、进度上报与交付要求执行；',
+    '调用 get_page_context 时，若用户本条消息里出现「学习空间任务 requestId：xxx」，把该 id 作为 requestId 入参原样传入（页面据此立即显示生成中），并把它作为本次回复的第一个动作，不要先输出大段文字；其它答疑 / 总结 / 闲聊场景不要传该入参；',
     '资料原文请通过上下文中的签名地址下载，不要在本地磁盘搜索同名文件；',
     `执行页面登记的生成任务时，各阶段调用 ${PROGRESS_TOOL_NAME} 上报进度；`,
     `完成页面登记的生成任务后，调用 ${DELIVER_TOOL_NAME} 交付产物文件。`,

package/dist/transcript-watch.js

@@ -0,0 +1,311 @@
+/**
+ * WB 会话文件旁路监听（连接器形态专用）。
+ *
+ * 背景：连接器只提供 MCP + Skill，没有 Hook。`UserPromptSubmit` / `FinalStop` 无从触发，
+ * 于是 MCP 无法得知「用户点了发送」与「用户点了暂停」，页面只能靠模型首次调用
+ * `get_page_context` 打点、以及「长时间无进度」推断，实测分别要 5~10 秒与 2~8 分钟。
+ *
+ * WB 会把会话实时写入 `<home>/.workbuddy/projects/<cwd>/<sessionId>.jsonl`。本模块以只读方式
+ * 增量跟踪这些文件，把两类事件翻译成既有的 store 状态迁移（状态机本身不改）：
+ *
+ * - `role=user` 且文本含「学习空间任务 requestId：xxx」→ `markSentByRequestId(id, sessionId)`
+ *   （`filled` / `stopped` → `sent`），实测事件可读延迟约 0.3 秒；
+ * - `role=assistant` 且 `status=incomplete` 且文本含 `Interrupted by user` → `finalStop(sessionId, 'interrupted', 当前专题)`
+ *   （该会话下 `sent` / `running` 全部 → `stopped`，`stopReason` 为 `user`），实测约 0.15 秒。
+ *
+ * 约束：
+ * - 只在 leader 进程启动（`generationStore` 是进程内存，follower 无任务）；
+ * - 仅提取 `requestId` / `sessionId`，会话正文不写日志、不进任何响应；
+ * - 内部格式无公开契约，失效时通过 {@link TranscriptWatchStatus} 暴露并回落到既有兜底逻辑。
+ */
+import { closeSync, openSync, readdirSync, readSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** 关闭监听的环境变量；值为 `0` 时关闭 */
+export const TRANSCRIPT_WATCH_ENV = 'LB_TOPIC_MCP_TRANSCRIPT_WATCH';
+/** 默认轮询间隔（毫秒） */
+export const DEFAULT_TRANSCRIPT_POLL_INTERVAL_MS = 200;
+/** 默认只跟踪最近改动过的会话文件（毫秒） */
+export const DEFAULT_TRANSCRIPT_ACTIVE_WINDOW_MS = 30 * 60 * 1000;
+/** 默认单轮单文件最大读取字节数 */
+export const DEFAULT_TRANSCRIPT_MAX_READ_BYTES = 256 * 1024;
+/** 会话 ID 最大长度（与 `bridge.ts` 的 `parseHookSessionId` 口径一致） */
+const SESSION_ID_MAX_CHARS = 128;
+/** 用户暂停时 WB 写入 assistant 消息的固定文案 */
+const INTERRUPTED_TEXT = 'Interrupted by user';
+/** 会话文件名后缀 */
+const SESSION_FILE_EXTENSION = '.jsonl';
+/** 换行字节 */
+const NEWLINE_BYTE = 0x0a;
+/**
+ * 任务引用正则：匹配页面填入的「学习空间任务 requestId：xxx」，容忍空白与包裹的引号 / 反引号。
+ * 捕获组为 requestId（UUID 形态，仅含字母、数字、下划线与连字符）。
+ */
+const TASK_REFERENCE_PATTERN = /学习空间任务\s*requestId\s*[：:]\s*[`'"“”]?([A-Za-z0-9_-]{1,128})/u;
+/**
+ * 解析是否启用。
+ * @param value 显式选项；为 `undefined` 时读环境变量
+ * @param env 环境变量表
+ */
+function resolveEnabled(value, env) {
+    if (value !== undefined)
+        return value;
+    return env[TRANSCRIPT_WATCH_ENV] !== '0';
+}
+/**
+ * 默认会话文件根目录。
+ */
+export function resolveTranscriptRoot() {
+    return join(homedir(), '.workbuddy', 'projects');
+}
+/**
+ * 判断路径是否为可读目录。
+ * @param path 路径
+ */
+function isReadableDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 判断文件是否在活跃窗口内改动过。
+ * @param path 文件路径
+ * @param windowMs 活跃窗口（毫秒）
+ * @param nowMs 当前时间戳
+ */
+function isRecentlyModified(path, windowMs, nowMs) {
+    try {
+        return nowMs - statSync(path).mtimeMs <= windowMs;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 会话 ID 校验：与 Hook 的 `session_id` 口径一致，非空且不超过上限。
+ * @param value 原始字段值
+ */
+function parseSessionId(value) {
+    return typeof value === 'string' && value.length >= 1 && value.length <= SESSION_ID_MAX_CHARS
+        ? value
+        : undefined;
+}
+/**
+ * 提取 message 的文本内容：兼容字符串与内容块数组（只取 `text` 字段）。
+ * @param content 原始 `content` 字段
+ */
+function extractText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    const parts = [];
+    for (const block of content) {
+        if (typeof block !== 'object' || block === null)
+            continue;
+        const text = block['text'];
+        if (typeof text === 'string')
+            parts.push(text);
+    }
+    return parts.join('\n');
+}
+/**
+ * 从文本中提取任务 requestId。
+ * @param text 消息文本
+ */
+function matchRequestId(text) {
+    const matched = TASK_REFERENCE_PATTERN.exec(text);
+    const requestId = matched?.[1];
+    return typeof requestId === 'string' && requestId !== '' ? requestId : undefined;
+}
+/**
+ * 创建会话文件监听器。
+ * @param options 选项
+ */
+export function createTranscriptWatcher(options) {
+    const { generationStore, getCurrentTopicId, root = resolveTranscriptRoot(), pollIntervalMs = DEFAULT_TRANSCRIPT_POLL_INTERVAL_MS, activeWindowMs = DEFAULT_TRANSCRIPT_ACTIVE_WINDOW_MS, maxReadBytes = DEFAULT_TRANSCRIPT_MAX_READ_BYTES, now = Date.now, logger = (message) => {
+        process.stderr.write(`${message}\n`);
+    }, } = options;
+    const enabled = resolveEnabled(options.enabled, process.env);
+    /** 已读到的字节位置 */
+    const offsets = new Map();
+    let state = 'off';
+    let timer;
+    /**
+     * 处理一行事件（非 message / 无法解析 / 不匹配规则的行直接忽略）。
+     * @param line 单行文本
+     */
+    function handleLine(line) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            return;
+        }
+        if (typeof parsed !== 'object' || parsed === null)
+            return;
+        const record = parsed;
+        if (record['type'] !== 'message')
+            return;
+        const sessionId = parseSessionId(record['sessionId']);
+        if (record['role'] === 'user') {
+            const requestId = matchRequestId(extractText(record['content']));
+            if (requestId === undefined)
+                return;
+            if (generationStore.markSentByRequestId(requestId, sessionId)) {
+                logger(`[transcript] 用户已发送，任务 ${requestId} 进入生成中`);
+            }
+            return;
+        }
+        if (record['role'] !== 'assistant' || record['status'] !== 'incomplete')
+            return;
+        if (!extractText(record['content']).includes(INTERRUPTED_TEXT))
+            return;
+        if (sessionId === undefined)
+            return;
+        const stopped = generationStore.finalStop(sessionId, 'interrupted', getCurrentTopicId());
+        if (stopped.length > 0) {
+            logger(`[transcript] 用户已取消，已暂停 ${stopped.length} 个任务`);
+        }
+    }
+    /**
+     * 读取单个文件的新增内容；只处理以换行结尾的完整行，避免半行解析。
+     * @param file 会话文件路径
+     */
+    function readAppendedFile(file) {
+        let size;
+        try {
+            size = statSync(file).size;
+        }
+        catch {
+            offsets.delete(file);
+            return;
+        }
+        const known = offsets.get(file);
+        // 首次发现：大文件只读尾部（避免启动时全量读取），小文件从头读（不丢新会话首批事件）；
+        // 已知文件变短说明被截断 / 轮转（WB 重建会话文件），必须从头重读，否则会漏掉新写入的事件
+        const start = known === undefined ? Math.max(0, size - maxReadBytes) : size < known ? 0 : known;
+        if (size <= start) {
+            offsets.set(file, size);
+            return;
+        }
+        const length = Math.min(size - start, maxReadBytes);
+        const buffer = Buffer.alloc(length);
+        let bytesRead = 0;
+        let fd;
+        try {
+            fd = openSync(file, 'r');
+            bytesRead = readSync(fd, buffer, 0, length, start);
+        }
+        catch {
+            offsets.delete(file);
+            return;
+        }
+        finally {
+            if (fd !== undefined)
+                closeSync(fd);
+        }
+        if (bytesRead <= 0)
+            return;
+        const breakIndex = buffer.lastIndexOf(NEWLINE_BYTE, bytesRead - 1);
+        if (breakIndex < 0) {
+            // 无完整行：读满上限说明是超长单行，直接跳过，避免永久卡住
+            if (bytesRead >= maxReadBytes)
+                offsets.set(file, start + bytesRead);
+            return;
+        }
+        const complete = buffer.subarray(0, breakIndex + 1);
+        offsets.set(file, start + complete.length);
+        for (const line of complete.toString('utf8').split('\n')) {
+            handleLine(line);
+        }
+    }
+    /**
+     * 列出需要跟踪的会话文件（根目录下的 `.jsonl` 与一级子目录内的 `.jsonl`）。
+     */
+    function listSessionFiles() {
+        const files = [];
+        const nowMs = now();
+        let entries;
+        try {
+            entries = readdirSync(root, { withFileTypes: true });
+        }
+        catch {
+            return files;
+        }
+        for (const entry of entries) {
+            const full = join(root, entry.name);
+            if (entry.isFile()) {
+                if (entry.name.endsWith(SESSION_FILE_EXTENSION) && isRecentlyModified(full, activeWindowMs, nowMs)) {
+                    files.push(full);
+                }
+                continue;
+            }
+            if (!entry.isDirectory())
+                continue;
+            let inner;
+            try {
+                inner = readdirSync(full, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const file of inner) {
+                if (!file.isFile() || !file.name.endsWith(SESSION_FILE_EXTENSION))
+                    continue;
+                const path = join(full, file.name);
+                if (isRecentlyModified(path, activeWindowMs, nowMs))
+                    files.push(path);
+            }
+        }
+        return files;
+    }
+    /**
+     * 立即扫描一轮：只读取活跃会话文件的新增内容。
+     */
+    async function scanOnce() {
+        if (state !== 'watching')
+            return;
+        for (const file of listSessionFiles()) {
+            readAppendedFile(file);
+        }
+    }
+    return {
+        start() {
+            if (state === 'watching')
+                return;
+            if (!enabled) {
+                state = 'off';
+                return;
+            }
+            if (!isReadableDirectory(root)) {
+                state = 'unavailable';
+                logger('[transcript] 未找到 WB 会话目录，监听未启用');
+                return;
+            }
+            state = 'watching';
+            timer = setInterval(() => {
+                void scanOnce();
+            }, pollIntervalMs);
+            timer.unref?.();
+        },
+        stop() {
+            if (timer !== undefined) {
+                clearInterval(timer);
+                timer = undefined;
+            }
+            state = 'off';
+        },
+        status() {
+            return state;
+        },
+        scanOnce,
+    };
+}

package/package.json

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

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

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