dsh-lark-agent 0.3.3 → 0.4.0

package/dist/lark-cli.d.ts

@@ -1,4 +1,5 @@
-import type { ReplyPayload } from './replies.js';
+import { type ReplyPayload } from './replies.js';
+import { type TopicReceipt } from './topic-store.js';
 export type LarkEventKey = 'im.message.receive_v1' | 'card.action.trigger' | 'application.bot.menu_v6';
 export interface LarkCliOptions {
     executable?: string;
@@ -46,6 +47,17 @@ export declare class LarkCli {
     sendUser(openId: string, text: string, options: {
         idempotencyKey: string;
     }): Promise<void>;
+    /** Open a native topic and keep its raw receipt; the reply shortcut drops thread_id. */
+    openTopic(target: {
+        chatId: string;
+        messageId?: string;
+    }, title: string, options: {
+        idempotencyKey: string;
+        chatType?: 'p2p' | 'group';
+        textOnly?: boolean;
+    }): Promise<TopicReceipt>;
+    /** Optional read enrichment. A missing link must never cause another topic creation. */
+    topicLink(messageId: string): Promise<string | undefined>;
     /** Create a short-lived loading card; its receipt stays inside the bridge. */
     createFeedback(target: {
         openId: string;

package/dist/lark-cli.js

@@ -2,6 +2,9 @@ import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { basename, dirname, isAbsolute } from 'node:path';
 import { StringDecoder } from 'node:string_decoder';
+import { renderPanel } from './replies.js';
+import { topicLink } from './topic-store.js';
+import { topicEntryPanel } from './topic-cards.js';
 const DEFAULT_EVENT_KEY = 'im.message.receive_v1';
 const MAX_OUTPUT_BYTES = 1_048_576;
 const MAX_STDERR_LINE_BYTES = 65_536;
@@ -326,6 +329,65 @@ export class LarkCli {
     sendUser(openId, text, options) {
         return this.sendRichUser(openId, { kind: 'text', text }, options);
     }
+    /** Open a native topic and keep its raw receipt; the reply shortcut drops thread_id. */
+    async openTopic(target, title, options) {
+        if (!target || typeof target.chatId !== 'string' || !/^oc_[A-Za-z0-9_-]{1,128}$/.test(target.chatId)
+            || (target.messageId !== undefined && !/^om_[A-Za-z0-9_-]{1,256}$/.test(target.messageId))
+            || typeof title !== 'string' || !title.trim() || Array.from(title).length > 80 || /[\u0000-\u001f\u007f-\u009f]/.test(title)
+            || !/^[A-Za-z0-9._:-]{1,45}$/.test(options?.idempotencyKey)
+            || (options.chatType !== undefined && options.chatType !== 'p2p' && options.chatType !== 'group')
+            || (options.textOnly !== undefined && typeof options.textOnly !== 'boolean'))
+            throw new Error('Invalid Lark topic target.');
+        const text = `话题：${title}\n请在这个话题里继续。${options.chatType === 'group' ? '群聊中每条消息仍需 @机器人。' : ''}`;
+        const request = async (path, data, params) => {
+            const result = await this.executeJson(['api', 'POST', path, ...(params ? ['--params', params] : []),
+                '--data', '-', '--as', 'bot', '--format', 'json'], JSON.stringify(data), 'reply', this.commandTimeoutMs);
+            this.confirmFeedback(result);
+            const receipt = result.data;
+            if (!receipt || typeof receipt.message_id !== 'string' || !/^om_[A-Za-z0-9_-]{1,256}$/.test(receipt.message_id)
+                || receipt.chat_id !== target.chatId)
+                throw new Error('Lark topic creation was not confirmed; delivery is unknown.');
+            return receipt;
+        };
+        let anchor = target.messageId;
+        let receipt;
+        if (!anchor) {
+            // Menu events and replies inside another topic cannot be used as a new root.
+            // Confirm the root before replying; never invent a message ID or retry an unknown send.
+            const content = options.textOnly ? JSON.stringify({ text }) : this.feedbackContent(renderPanel(topicEntryPanel(title, options.chatType ?? 'p2p')));
+            receipt = await request('/open-apis/im/v1/messages', { receive_id: target.chatId, msg_type: options.textOnly ? 'text' : 'interactive',
+                content, uuid: `${options.idempotencyKey}:root` }, '{"receive_id_type":"chat_id"}');
+            anchor = receipt.message_id;
+        }
+        if (!receipt?.thread_id)
+            receipt = await request(`/open-apis/im/v1/messages/${anchor}/reply`, { msg_type: 'text', content: JSON.stringify({ text: target.messageId ? text : `在这里发送消息继续。${options.chatType === 'group' ? '每条消息仍需 @机器人。' : ''}` }),
+                reply_in_thread: true, uuid: `${options.idempotencyKey}:open` });
+        if (typeof receipt.thread_id !== 'string' || !/^(?:om|omt)_[A-Za-z0-9_-]{1,256}$/.test(receipt.thread_id)) {
+            throw new Error('Lark topic creation did not return a thread ID; delivery is unknown.');
+        }
+        const messageId = receipt.message_id;
+        const link = await this.topicLink(messageId);
+        return { threadId: receipt.thread_id, messageId, ...(link ? { link } : {}) };
+    }
+    /** Optional read enrichment. A missing link must never cause another topic creation. */
+    async topicLink(messageId) {
+        if (!/^om_[A-Za-z0-9_-]{1,256}$/.test(messageId))
+            throw new Error('Invalid Lark topic anchor.');
+        try {
+            const result = await this.executeJson(['im', '+messages-mget', '--message-ids', messageId, '--no-reactions',
+                '--as', 'bot', '--format', 'json'], '', 'read', Math.min(this.commandTimeoutMs, 5_000));
+            this.confirmFeedback(result);
+            const data = result.data;
+            const rows = data?.messages ?? result.messages;
+            if (!Array.isArray(rows))
+                return;
+            const message = rows.find(row => row && typeof row === 'object' && row.message_id === messageId);
+            return topicLink(message?.thread_app_link) ?? topicLink(message?.message_app_link);
+        }
+        catch {
+            return;
+        }
+    }
     /** Create a short-lived loading card; its receipt stays inside the bridge. */
     async createFeedback(target, payload, options) {
         const content = this.feedbackContent(payload);
@@ -601,7 +663,7 @@ export class LarkCli {
         if (this.stopped)
             return Promise.reject(new Error('Lark transport is stopped.'));
         const label = `Lark ${operation} command`;
-        const uncertain = operation === 'progress' || operation === 'card' ? 'result is unknown.' : 'delivery is unknown.';
+        const uncertain = operation === 'progress' || operation === 'card' || operation === 'read' ? 'result is unknown.' : 'delivery is unknown.';
         return new Promise((resolve, reject) => {
             let child;
             try {

package/dist/onboarding/host.js

@@ -4,12 +4,13 @@ import { constants, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { delimiter, join, resolve } from 'node:path';
 import { createBotService, BotServiceStartError } from '../bot-service.js';
-import { checkRuntimeCompatibility, DshRuntime } from '../dsh-runtime.js';
+import { checkRuntimeCompatibility } from '../dsh-runtime.js';
 import { acquireLock, LockHeldError } from '../lock.js';
 import { ConnectionController, SetupError } from './controller.js';
 import { ConnectionStore } from './store.js';
 import { LarkPlatform } from './lark-platform.js';
 import { npmLatest, UpdateCheck } from './updates.js';
+import { checkConnectionModel } from './model-check.js';
 const endpoints = new Set(['status', 'profiles', 'create', 'use-profile', 'recheck', 'cancel',
     'renew-pairing', 'confirm-owner', 'pause', 'resume', 'disconnect', 'enable-documents', 'cancel-documents']);
 const failure = (message) => ({ ok: false, error: { code: 'internal', message, details: {} } });
@@ -229,21 +230,7 @@ export async function applyOnboarding(ctx, options = {}) {
     const executable = await findLarkExecutable(options.executable);
     const controller = new ConnectionController({ store: new ConnectionStore(directory), platform: new LarkPlatform({ executable }), executable,
         checkRuntime: () => requireRuntime(ctx),
-        preflight: async (config, signal) => {
-            const policy = config.users[0];
-            const timeout = AbortSignal.timeout(45_000);
-            const combined = AbortSignal.any([signal, timeout]);
-            const session = await new DshRuntime(ctx).create({ ...policy, provider: config.provider, model: config.model });
-            try {
-                const result = await session.run('这是飞书连接测试，请只回复“连接成功”。', combined);
-                if (!(typeof result === 'string' ? result : result.text).trim())
-                    throw new SetupError('模型没有返回内容，请检查模型设置后重试。');
-                await session.checkpoint();
-            }
-            finally {
-                await session.dispose();
-            }
-        },
+        preflight: (config, signal) => checkConnectionModel(ctx, config, signal),
         start: async (config, signal, health, pairedChat) => {
             signal.throwIfAborted();
             const service = await createBotService(ctx, config, health, { directChat: pairedChat });
@@ -258,7 +245,8 @@ export async function applyOnboarding(ctx, options = {}) {
                     throw new BotServiceStartError(service);
                 throw error;
             }
-        }, });
+        },
+    });
     const installed = installedPackage();
     const updates = new UpdateCheck(installed?.version, options.latestRelease
         ?? (signal => installed ? npmLatest(installed.name, signal) : Promise.resolve(undefined)));

package/dist/onboarding/model-check.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { BotConfig } from '../config.js';
+export declare const CONNECTION_TEST_PROMPT = "\u8FD9\u662F\u98DE\u4E66\u8FDE\u63A5\u6D4B\u8BD5\uFF0C\u8BF7\u53EA\u56DE\u590D\u201C\u8FDE\u63A5\u6210\u529F\u201D\u3002";
+/** One model call, without an Agent or a durable conversation to clean up. */
+export declare function checkConnectionModel(ctx: Context, config: Pick<BotConfig, 'provider' | 'model'>, signal: AbortSignal): Promise<void>;

package/dist/onboarding/model-check.js

@@ -0,0 +1,51 @@
+import { createUserMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+import { SetupError } from './controller.js';
+export const CONNECTION_TEST_PROMPT = '这是飞书连接测试，请只回复“连接成功”。';
+/** One model call, without an Agent or a durable conversation to clean up. */
+export async function checkConnectionModel(ctx, config, signal) {
+    const timeout = AbortSignal.timeout(45_000);
+    const combined = AbortSignal.any([signal, timeout]);
+    try {
+        combined.throwIfAborted();
+        const selection = config.provider && config.model ? { provider: config.provider, model: config.model }
+            : ctx.get('agentDefaultModel')?.currentSelection?.();
+        const llm = ctx.get('llm');
+        if (!selection?.provider || !selection.model || typeof llm?.stream !== 'function') {
+            throw new SetupError('请先在 dsh 的模型设置中选择可用模型，然后回来继续连接飞书。');
+        }
+        let text = false, finished = false;
+        for await (const chunk of llm.stream({
+            provider: selection.provider, model: selection.model,
+            ...(selection.reasoningEffort === undefined ? {} : { reasoningEffort: ReasoningEffortId(selection.reasoningEffort) }),
+            messages: [createUserMessage({ source: { kind: 'user' }, content: [{ type: 'text', text: CONNECTION_TEST_PROMPT }] })],
+            tools: [], signal: combined,
+        })) {
+            combined.throwIfAborted();
+            if (chunk.type === 'text-delta')
+                text ||= Boolean(chunk.text.trim());
+            if (chunk.type === 'block-end' && chunk.block.type === 'text')
+                text ||= Boolean(chunk.block.text.trim());
+            if (chunk.type === 'finish') {
+                if (chunk.reason.kind === 'error' || chunk.reason.kind === 'aborted' || chunk.reason.kind === 'tool-calls') {
+                    throw new SetupError('模型连接测试失败，请检查模型设置后重试。');
+                }
+                finished = true;
+            }
+        }
+        combined.throwIfAborted();
+        if (!finished)
+            throw new SetupError('模型连接测试未完成，请检查模型设置后重试。');
+        if (!text)
+            throw new SetupError('模型没有返回内容，请检查模型设置后重试。');
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw new SetupError('连接已取消。');
+        if (timeout.aborted)
+            throw new SetupError('模型连接测试超时，请检查模型设置后重试。');
+        if (error instanceof SetupError)
+            throw error;
+        throw new SetupError('模型连接测试失败，请检查模型设置后重试。');
+    }
+}
+//# sourceMappingURL=model-check.js.map

package/dist/replies.d.ts

@@ -44,6 +44,22 @@ export interface ReplyPanel {
     }[];
     actions?: ReplyAction[];
     actionColumns?: 1 | 2 | 3;
+    /** Trusted catalog controls; option values and callbacks are supplied by the application. */
+    select?: {
+        placeholder: string;
+        options: {
+            label: string;
+            value: string;
+        }[];
+        value: Record<string, string>;
+        initialOption?: string;
+        disabled?: boolean;
+    };
+    search?: {
+        query: string;
+        value: Record<string, string>;
+        disabled?: boolean;
+    };
     note?: string;
 }
 /**

package/dist/replies.js

@@ -32,13 +32,21 @@ function externalUrl(value) {
         return false;
     }
 }
-/** Turn unsupported links into visible inert text; preserve ordinary web links. */
+function escapeProse(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/** Lark takes Markdown hrefs literally: HTML escaping '&' changes their query keys. */
+function linkDestination(url) {
+    return url.replace(/&(?=(?:#(?:x[0-9a-f]+|[0-9]+)|[a-z][a-z0-9]*;))/gi, '%26')
+        .replace(/["'`]/g, character => '%' + character.charCodeAt(0).toString(16).toUpperCase());
+}
+/** Escape prose and disable unsupported links while retaining safe HTTP(S) destinations. */
 function safeLinks(text) {
     let result = '', cursor = 0;
     while (cursor < text.length) {
         const start = text.indexOf('](', cursor);
         if (start < 0)
-            return result + text.slice(cursor);
+            return result + escapeProse(text.slice(cursor));
         let end = start + 2, depth = 1;
         for (; end < text.length; end++) {
             if (text[end] === '\\') {
@@ -51,12 +59,13 @@ function safeLinks(text) {
                 break;
         }
         if (end >= text.length)
-            return result + text.slice(cursor);
+            return result + escapeProse(text.slice(cursor));
         const destination = text.slice(start + 2, end).trim();
-        const url = destination.match(/^(<[^>]+>|\S+?)(?:\s+["'][\s\S]*["'])?$/)?.[1]?.replace(/^<|>$/g, '') ?? '';
-        result += text.slice(cursor, start) + (externalUrl(url)
-            ? text.slice(start, end + 1)
-            : `]（${destination}）`);
+        const parts = destination.match(/^(<[^>]+>|\S+?)(\s+["'][\s\S]*["'])?$/);
+        const url = parts?.[1]?.replace(/^<|>$/g, '') ?? '';
+        result += escapeProse(text.slice(cursor, start)) + (externalUrl(url)
+            ? `](${linkDestination(url)}${escapeProse(parts?.[2] ?? '')})`
+            : `]（${escapeProse(destination)}）`);
         cursor = end + 1;
     }
     return result;
@@ -65,10 +74,9 @@ function prose(text) {
     let output = text
         .replace(/<(https?:\/\/[^<>\s]+)>/gi, (_match, url) => externalUrl(url) ? `[${url}](${url})` : url)
         .replace(/!\[/g, '[');
-    output = safeLinks(output);
     output = output.replace(/^( {0,3}\[[^\]\n]+\]):\s*(<?\S+>?)(.*)$/gm, (line, label, destination) => externalUrl(destination.replace(/^<|>$/g, '')) ? line : line.replace(`${label}:`, `${label}：`));
-    // Escape entities too, so an encoded <at> cannot become an active tag after decoding.
-    output = output.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    // Prose still escapes entities so encoded native tags cannot become active.
+    output = safeLinks(output);
     return output.replace(/^[ \t]*\|?\s*:?-{3,}:?\s*(?:\|\s*:?-{3,}:?\s*)+\|?[ \t]*$/gm, line => {
         const cells = line.trim().replace(/^\||\|$/g, '').split('|');
         return `| ${cells.map(() => ':---').join(' | ')} |`;
@@ -169,7 +177,8 @@ export function renderPanel(panel) {
     const metrics = (panel.metrics ?? []).filter(metric => metric.label.trim() || metric.value.trim());
     const fallbackText = safePlainText([panel.title, panel.subtitle, panel.status?.text,
         ...metrics.map(metric => [`${metric.label}：${metric.value}`, metric.note].filter(Boolean).join('\n')),
-        ...panel.sections.map(section => [section.title, section.text].filter(Boolean).join('\n')), panel.note]
+        ...panel.sections.map(section => [section.title, section.text].filter(Boolean).join('\n')),
+        ...(panel.select?.options.map(option => `${option.label}\n/resume ${option.value}`) ?? []), panel.note]
         .filter(Boolean).join('\n\n'));
     const elements = [];
     const actions = panel.actions ?? [];
@@ -187,6 +196,23 @@ export function renderPanel(panel) {
             ], { background_style: 'grey', padding: '10px 12px 10px 12px' })),
         });
     }
+    if (panel.search)
+        elements.push({ tag: 'form', name: 'dsh_sessions_search_form', direction: 'vertical',
+            elements: [{ tag: 'column_set', flex_mode: 'none', horizontal_spacing: '8px', margin: '0px', columns: [column([
+                            { tag: 'input', name: 'query', input_type: 'text', placeholder: title('搜索话题标题'), default_value: panel.search.query,
+                                max_length: 80, width: 'fill', disabled: Boolean(panel.search.disabled) },
+                        ]), column([
+                            { tag: 'button', name: 'dsh_sessions_search', text: title('搜索'), type: 'default', width: 'default',
+                                action_type: 'form_submit', form_action_type: 'submit', form_name: 'dsh_sessions_search_form',
+                                disabled: Boolean(panel.search.disabled), behaviors: [{ type: 'callback', value: { ...panel.search.value } }] },
+                        ], { width: 'auto' })] }] });
+    if (panel.select)
+        elements.push({ tag: 'select_static', name: 'dsh_session_picker', width: 'fill',
+            placeholder: title(panel.select.placeholder), disabled: Boolean(panel.select.disabled),
+            ...(panel.select.initialOption ? { initial_option: panel.select.initialOption } : {}),
+            options: panel.select.options.map(option => ({ text: title(safePlainText(option.label)), value: option.value })),
+            behaviors: [{ type: 'callback', value: { ...panel.select.value } }],
+        });
     for (const section of panel.sections) {
         if (!section.text.trim() && !section.title?.trim())
             continue;

package/dist/session-controls.d.ts

@@ -0,0 +1,34 @@
+import type { SavedSession } from './session-store.js';
+import { type ReplyAction, type ReplyPanel } from './replies.js';
+export interface SessionView {
+    page: number;
+    query: string;
+}
+export interface SessionChoice extends SavedSession {
+    link?: string;
+}
+export declare const SESSION_PAGE_SIZE = 20;
+export declare const SESSION_QUERY_LENGTH = 80;
+export declare function sessionQuery(value: unknown): string | undefined;
+/** The query travels inside the signed command, never as an executable command fragment. */
+export declare function sessionViewCommand(kind: 'page' | 'pick', view: SessionView): string;
+export declare function sessionViewCommandParse(command: string): {
+    kind: 'page' | 'pick';
+    view: SessionView;
+} | undefined;
+export declare function sessionPage<T extends SessionChoice>(sessions: readonly T[], view: SessionView): {
+    items: T[];
+    total: number;
+    pages: number;
+    view: {
+        page: number;
+        query: string;
+    };
+};
+/** A short picker stays the same height as the catalog grows. Only its selected topic gets a detail row. */
+export declare function sessionControlPanel(sessions: readonly SessionChoice[], currentId: string | undefined, action: (label: string, command: string) => ReplyAction | undefined, options?: {
+    view?: SessionView;
+    selectedId?: string;
+    busy?: boolean;
+    status?: ReplyPanel['status'];
+}): ReplyPanel;

package/dist/session-controls.js

@@ -0,0 +1,66 @@
+import { plainLabel } from './replies.js';
+export const SESSION_PAGE_SIZE = 20;
+export const SESSION_QUERY_LENGTH = 80;
+export function sessionQuery(value) {
+    if (typeof value !== 'string' || Array.from(value).length > SESSION_QUERY_LENGTH || /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/u.test(value))
+        return;
+    return value.normalize('NFC').trim();
+}
+/** The query travels inside the signed command, never as an executable command fragment. */
+export function sessionViewCommand(kind, view) {
+    return `/sessions ${kind} ${view.page + 1}${view.query ? ` ${Buffer.from(view.query).toString('base64url')}` : ''}`;
+}
+export function sessionViewCommandParse(command) {
+    const match = /^\/sessions (page|pick) ([1-9][0-9]?)(?: ([A-Za-z0-9_-]{1,428}))?$/.exec(command);
+    if (!match)
+        return;
+    const query = match[3] ? Buffer.from(match[3], 'base64url').toString('utf8') : '';
+    if (sessionQuery(query) !== query || (match[3] && Buffer.from(query).toString('base64url') !== match[3]))
+        return;
+    return { kind: match[1], view: { page: Number(match[2]) - 1, query } };
+}
+export function sessionPage(sessions, view) {
+    const query = view.query.normalize('NFC').toLocaleLowerCase();
+    const matches = sessions.filter(session => session.title.normalize('NFC').toLocaleLowerCase().includes(query))
+        .sort((a, b) => b.updatedAt - a.updatedAt || a.id.localeCompare(b.id));
+    const pages = Math.max(1, Math.ceil(matches.length / SESSION_PAGE_SIZE));
+    const page = Math.max(0, Math.min(view.page, pages - 1));
+    return { items: matches.slice(page * SESSION_PAGE_SIZE, (page + 1) * SESSION_PAGE_SIZE), total: matches.length, pages, view: { ...view, page } };
+}
+/** A short picker stays the same height as the catalog grows. Only its selected topic gets a detail row. */
+export function sessionControlPanel(sessions, currentId, action, options = {}) {
+    const page = sessionPage(sessions, options.view ?? { page: 0, query: '' });
+    const selected = sessions.find(session => session.id === (options.selectedId ?? currentId));
+    const selectedVisible = page.items.some(session => session.id === selected?.id);
+    const pick = action('选择话题', sessionViewCommand('pick', page.view));
+    const search = action('搜索', '/sessions search');
+    const actions = [
+        ...(page.view.page > 0 ? [action('上一页', sessionViewCommand('page', { ...page.view, page: page.view.page - 1 }))] : []),
+        ...(page.view.page + 1 < page.pages ? [action('下一页', sessionViewCommand('page', { ...page.view, page: page.view.page + 1 }))] : []),
+        action('新建话题', '/new'),
+    ].filter((item) => Boolean(item));
+    const duplicates = new Map();
+    const dateFormat = new Intl.DateTimeFormat('zh-CN', { month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', hour12: false });
+    for (const session of page.items) {
+        const title = plainLabel(session.title, 30);
+        duplicates.set(title, (duplicates.get(title) ?? 0) + 1);
+    }
+    const count = page.view.query ? `找到 ${page.total} 个话题 · 共 ${sessions.length} 个` : `共 ${sessions.length} 个话题 · 最近活跃优先`;
+    return { title: '以前的对话', summary: page.view.query ? `搜索历史话题：${page.total} 个结果，可选择话题继续` : `浏览 ${sessions.length} 个历史话题，选择后打开继续聊天`,
+        subtitle: count, ...(options.status ? { status: options.status, tone: options.status.tone } : {}),
+        ...(search ? { search: { query: page.view.query, value: search.value, disabled: options.busy } } : {}),
+        ...(pick && page.items.length ? { select: { placeholder: '选择一个话题继续聊天', value: pick.value, disabled: options.busy,
+                ...(selectedVisible ? { initialOption: selected.id } : {}),
+                options: page.items.map(session => {
+                    const title = plainLabel(session.title, 30);
+                    const date = dateFormat.format(session.updatedAt);
+                    return { value: session.id, label: `${title}${Array.from(session.title).length > 30 ? '…' : ''} · ${date}${duplicates.get(title) > 1 ? ` · ${session.id.slice(-4)}` : ''}` };
+                }) } } : {}),
+        sections: !page.total ? [{ text: sessions.length ? '没有找到匹配的话题。换个关键词，或清空搜索查看全部。' : '还没有历史话题。直接发消息，就会开始新的对话。' }]
+            : !pick ? page.items.map(session => ({ title: plainLabel(session.title, 60), text: `/resume ${session.id}` }))
+                : selected ? [{ ...(!selectedVisible ? { title: plainLabel(selected.title, 60) } : {}), text: selected.link ? `[打开话题继续](${selected.link})`
+                            : selected.id === currentId ? '当前正在聊的话题' : '话题入口暂不可用，请在聊天中找到对应话题后继续。' }] : [],
+        actions, actionColumns: actions.length === 1 ? 1 : actions.length === 2 ? 2 : 3,
+        note: `第 ${page.view.page + 1} / ${page.pages} 页${page.view.query ? ' · 清空搜索可查看全部话题' : ''}${!pick ? '\n文字操作：/sessions detail；/resume <ID>' : ''}`, };
+}
+//# sourceMappingURL=session-controls.js.map

package/dist/session-store.d.ts

@@ -1,6 +1,8 @@
 export interface SessionContext {
     ownerKey: string;
     conversationKey: string;
+    /** A topic may point at one historical session without changing its siblings' active selection. */
+    sessionId?: string;
 }
 export interface SavedSession {
     id: string;

package/dist/session-store.js

@@ -30,7 +30,8 @@ function validKey(value) {
         && value === value.trim() && !CONTROLS.test(value);
 }
 function validateContext(value) {
-    if (!value || !validKey(value.ownerKey) || !validKey(value.conversationKey))
+    if (!value || !validKey(value.ownerKey) || !validKey(value.conversationKey)
+        || (value.sessionId !== undefined && (typeof value.sessionId !== 'string' || !SESSION_ID.test(value.sessionId))))
         throw new SessionStoreError('INVALID_INPUT');
 }
 function titleText(value) {
@@ -175,7 +176,7 @@ export class SessionStore {
     }
     mutate(context, update) {
         // Snapshot caller-owned identity before an earlier queued mutation awaits I/O.
-        const identity = { ownerKey: context?.ownerKey, conversationKey: context?.conversationKey };
+        const identity = { ...context };
         const job = this.tail.then(async () => {
             this.assertAvailable();
             validateContext(identity);
@@ -196,7 +197,9 @@ export class SessionStore {
         await this.tail;
         this.assertAvailable();
         const entry = this.locate(this.document, identity);
-        const current = entry?.sessions.find(session => session.id === entry.activeId);
+        const current = entry?.sessions.find(session => session.id === (identity.sessionId ?? entry.activeId));
+        if (identity.sessionId && !current)
+            throw new SessionStoreError('NOT_FOUND');
         return current && { ...current };
     }
     async list(context) {
@@ -210,6 +213,8 @@ export class SessionStore {
     add(context, nativeId, title = '新会话') {
         const identity = { ...context };
         return this.mutate(identity, draft => {
+            if (identity.sessionId !== undefined)
+                throw new SessionStoreError('INVALID_INPUT');
             if (!NATIVE_ID.test(nativeId))
                 throw new SessionStoreError('INVALID_INPUT');
             const safeTitle = titleText(title);
@@ -228,7 +233,7 @@ export class SessionStore {
             const time = this.nextTimestamp(draft);
             const session = { id, nativeId, title: safeTitle, createdAt: time, updatedAt: time };
             if (!entry) {
-                entry = { ...identity, activeId: null, sessions: [] };
+                entry = { ownerKey: identity.ownerKey, conversationKey: identity.conversationKey, activeId: null, sessions: [] };
                 draft.contexts.push(entry);
             }
             entry.sessions.push(session);
@@ -275,8 +280,8 @@ export class SessionStore {
         const identity = { ...context };
         return this.mutate(identity, draft => {
             const entry = this.locate(draft, identity);
-            const changed = Boolean(entry?.activeId);
-            if (entry)
+            const changed = Boolean(entry?.activeId && (!identity.sessionId || identity.sessionId === entry.activeId));
+            if (entry && changed)
                 entry.activeId = null;
             return { value: undefined, changed };
         });
@@ -286,7 +291,7 @@ export class SessionStore {
         return this.mutate(identity, draft => {
             const safeTitle = titleText(title);
             const entry = this.locate(draft, identity);
-            const session = entry?.sessions.find(candidate => candidate.id === entry.activeId);
+            const session = entry?.sessions.find(candidate => candidate.id === (identity.sessionId ?? entry.activeId));
             if (!session)
                 throw new SessionStoreError('NO_CURRENT');
             session.title = safeTitle;

package/dist/topic-cards.d.ts

@@ -0,0 +1,3 @@
+import type { ReplyPanel } from './replies.js';
+/** The entry itself owns the native thread; it needs no separate navigation confirmation. */
+export declare function topicEntryPanel(title: string, chatType: 'p2p' | 'group'): ReplyPanel;

package/dist/topic-cards.js

@@ -0,0 +1,8 @@
+/** The entry itself owns the native thread; it needs no separate navigation confirmation. */
+export function topicEntryPanel(title, chatType) {
+    return { title, summary: `${title}，在话题内继续对话`,
+        sections: [{ text: '在下方点「回复话题」，继续聊天。' }],
+        ...(chatType === 'group' ? { note: '群聊中每条消息仍需 @机器人。' } : {}),
+    };
+}
+//# sourceMappingURL=topic-cards.js.map

package/dist/topic-store.d.ts

@@ -0,0 +1,40 @@
+export interface TopicScope {
+    ownerKey: string;
+    chatKey: string;
+}
+export interface TopicReceipt {
+    threadId: string;
+    messageId: string;
+    link?: string;
+}
+/** Keys come exclusively from verified events and confirmed bot receipts. No message text is stored. */
+export interface TopicBinding extends TopicScope, TopicReceipt {
+    laneKey: string;
+    conversationKey: string;
+    sessionId?: string;
+    groupAccessKey?: string;
+}
+type ErrorCode = 'INVALID_INPUT' | 'CORRUPT' | 'CONFLICT' | 'CAPACITY' | 'WRITE_FAILED' | 'UNAVAILABLE';
+export declare class TopicStoreError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode);
+}
+/** Use only links returned by Lark's read API/CLI enrichment; never synthesize a deep link. */
+export declare function topicLink(value: unknown): string | undefined;
+/** The state lock owns this store. Ambiguous publication poisons it until restart. */
+export declare class TopicStore {
+    private readonly directory;
+    private entries;
+    private tail;
+    private unavailable;
+    private constructor();
+    static open(directory: string): Promise<TopicStore>;
+    private validate;
+    private assertAvailable;
+    list(scope: TopicScope): Promise<TopicBinding[]>;
+    get(scope: TopicScope, threadId: string): Promise<TopicBinding | undefined>;
+    occupied(chatKey: string, threadId: string): Promise<boolean>;
+    record(binding: TopicBinding): Promise<TopicBinding>;
+    private persist;
+}
+export {};