dsh-lark-agent 0.3.2 → 0.4.0

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 {};

package/dist/topic-store.js

@@ -0,0 +1,192 @@
+import { constants } from 'node:fs';
+import { chmod, mkdir, open, rename, unlink } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+export class TopicStoreError extends Error {
+    code;
+    constructor(code) {
+        super({ INVALID_INPUT: '话题参数无效。', CORRUPT: '话题目录损坏，请管理员检查备份；已有记录未被清空。',
+            CONFLICT: '话题绑定已变化，请重新打开历史对话。', CAPACITY: '话题数量已达到上限，已有话题会保留。',
+            WRITE_FAILED: '话题目录保存失败，请稍后重试。', UNAVAILABLE: '话题目录的保存结果未能确认，请管理员检查后重新启动。' }[code]);
+        this.code = code;
+        this.name = 'TopicStoreError';
+    }
+}
+const KEY = /^[a-f0-9]{64}$/;
+const MESSAGE = /^om_[A-Za-z0-9_-]{1,256}$/;
+const THREAD = /^(?:om|omt)_[A-Za-z0-9_-]{1,256}$/;
+const MAX_TOPICS = 10_000;
+const MAX_OWNER_TOPICS = 1000;
+const MAX_BYTES = 8 * 1024 * 1024;
+/** Use only links returned by Lark's read API/CLI enrichment; never synthesize a deep link. */
+export function topicLink(value) {
+    if (typeof value !== 'string' || value.length > 4096)
+        return;
+    try {
+        const url = new URL(value);
+        if (url.protocol === 'https:' && !url.username && !url.password && !url.port
+            && ['applink.feishu.cn', 'applink.larksuite.com'].includes(url.hostname)
+            && /^\/client\/(?:thread\/open|chat\/open|message\/link\/open)$/.test(url.pathname))
+            return url.href;
+    }
+    catch { /* An unavailable link does not invalidate a confirmed topic. */ }
+}
+function validScope(scope) {
+    return Boolean(scope && typeof scope.ownerKey === 'string' && KEY.test(scope.ownerKey)
+        && typeof scope.chatKey === 'string' && KEY.test(scope.chatKey));
+}
+function parseBinding(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new TopicStoreError('INVALID_INPUT');
+    const item = value;
+    if (!validScope(item) || typeof item.laneKey !== 'string' || !KEY.test(item.laneKey)
+        || typeof item.conversationKey !== 'string' || !KEY.test(item.conversationKey)
+        || typeof item.threadId !== 'string' || !THREAD.test(item.threadId)
+        || typeof item.messageId !== 'string' || !MESSAGE.test(item.messageId)
+        || (item.sessionId !== undefined && (typeof item.sessionId !== 'string' || !/^[a-f0-9]{12}$/.test(item.sessionId)))
+        || (item.groupAccessKey !== undefined && (typeof item.groupAccessKey !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(item.groupAccessKey)))
+        || (item.link !== undefined && topicLink(item.link) !== item.link))
+        throw new TopicStoreError('INVALID_INPUT');
+    return { ownerKey: item.ownerKey, chatKey: item.chatKey, laneKey: item.laneKey, conversationKey: item.conversationKey,
+        threadId: item.threadId, messageId: item.messageId,
+        ...(item.sessionId === undefined ? {} : { sessionId: item.sessionId }),
+        ...(item.groupAccessKey === undefined ? {} : { groupAccessKey: item.groupAccessKey }),
+        ...(item.link === undefined ? {} : { link: item.link }) };
+}
+function sameScope(a, b) { return a.ownerKey === b.ownerKey && a.chatKey === b.chatKey; }
+/** The state lock owns this store. Ambiguous publication poisons it until restart. */
+export class TopicStore {
+    directory;
+    entries = [];
+    tail = Promise.resolve();
+    unavailable = false;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    static async open(directory) {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await chmod(directory, 0o700);
+        const store = new TopicStore(directory);
+        let handle;
+        try {
+            handle = await open(join(directory, 'topics.json'), constants.O_RDONLY | constants.O_NOFOLLOW);
+            const info = await handle.stat();
+            if (!info.isFile() || info.size > MAX_BYTES)
+                throw new Error();
+            const bytes = await handle.readFile();
+            if (bytes.length > MAX_BYTES)
+                throw new Error();
+            const data = JSON.parse(bytes.toString('utf8'));
+            if (!data || typeof data !== 'object' || Array.isArray(data) || !('version' in data) || data.version !== 1
+                || !('topics' in data) || !Array.isArray(data.topics) || data.topics.length > MAX_TOPICS)
+                throw new Error();
+            store.entries = data.topics.map(parseBinding);
+            store.validate(store.entries);
+            await handle.chmod(0o600);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw new TopicStoreError('CORRUPT');
+        }
+        finally {
+            await handle?.close();
+        }
+        return store;
+    }
+    validate(entries) {
+        const threads = new Set(), lanes = new Set(), sessions = new Set(), owners = new Map();
+        for (const item of entries) {
+            const thread = JSON.stringify([item.chatKey, item.threadId]);
+            if (threads.has(thread) || lanes.has(item.laneKey) || (item.sessionId && sessions.has(item.sessionId)))
+                throw new TopicStoreError('CONFLICT');
+            threads.add(thread);
+            lanes.add(item.laneKey);
+            if (item.sessionId)
+                sessions.add(item.sessionId);
+            const count = (owners.get(item.ownerKey) ?? 0) + 1;
+            owners.set(item.ownerKey, count);
+            if (count > MAX_OWNER_TOPICS || entries.length > MAX_TOPICS)
+                throw new TopicStoreError('CAPACITY');
+        }
+    }
+    assertAvailable() { if (this.unavailable)
+        throw new TopicStoreError('UNAVAILABLE'); }
+    async list(scope) {
+        if (!validScope(scope))
+            throw new TopicStoreError('INVALID_INPUT');
+        const identity = { ...scope };
+        await this.tail;
+        this.assertAvailable();
+        return this.entries.filter(item => sameScope(identity, item)).map(item => ({ ...item }));
+    }
+    async get(scope, threadId) {
+        return (await this.list(scope)).find(item => item.threadId === threadId);
+    }
+    async occupied(chatKey, threadId) {
+        if (!KEY.test(chatKey) || !THREAD.test(threadId))
+            throw new TopicStoreError('INVALID_INPUT');
+        await this.tail;
+        this.assertAvailable();
+        return this.entries.some(item => item.chatKey === chatKey && item.threadId === threadId);
+    }
+    record(binding) {
+        // Snapshot the caller before queued I/O, and retain only the schema's fields.
+        const next = parseBinding(binding);
+        const job = this.tail.then(async () => {
+            this.assertAvailable();
+            const existing = this.entries.find(item => item.chatKey === next.chatKey && item.threadId === next.threadId);
+            if (existing) {
+                if (!sameScope(existing, next) || existing.laneKey !== next.laneKey || existing.conversationKey !== next.conversationKey
+                    || existing.groupAccessKey !== next.groupAccessKey || (existing.sessionId && existing.sessionId !== next.sessionId))
+                    throw new TopicStoreError('CONFLICT');
+                // A later event must not move the topic's stable anchor or discard its selected session/link.
+                next.messageId = existing.messageId;
+                next.sessionId ??= existing.sessionId;
+                next.link ??= existing.link;
+                if (JSON.stringify(existing) === JSON.stringify(next))
+                    return { ...existing };
+            }
+            const entries = this.entries.filter(item => item !== existing).concat(next);
+            this.validate(entries);
+            await this.persist(entries);
+            this.entries = entries;
+            return { ...next };
+        });
+        this.tail = job.then(() => undefined, () => undefined);
+        return job;
+    }
+    async persist(topics) {
+        const contents = JSON.stringify({ version: 1, topics }) + '\n';
+        // Long read-enriched links count toward the same bound used when reopening.
+        if (Buffer.byteLength(contents) > MAX_BYTES)
+            throw new TopicStoreError('CAPACITY');
+        const temporary = join(this.directory, `topics.${randomUUID()}.tmp`);
+        let publicationAttempted = false;
+        try {
+            const handle = await open(temporary, 'wx', 0o600);
+            try {
+                await handle.writeFile(contents);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            publicationAttempted = true;
+            await rename(temporary, join(this.directory, 'topics.json'));
+            const directory = await open(this.directory, 'r');
+            try {
+                await directory.sync();
+            }
+            finally {
+                await directory.close();
+            }
+        }
+        catch {
+            if (publicationAttempted)
+                this.unavailable = true;
+            await unlink(temporary).catch(() => undefined);
+            throw new TopicStoreError(publicationAttempted ? 'UNAVAILABLE' : 'WRITE_FAILED');
+        }
+    }
+}
+//# sourceMappingURL=topic-store.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-lark-agent",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Reach your DeepSeek Harness assistant from Feishu / Lark: a dsh plugin built on the official Lark CLI",
   "keywords": [
     "deepseek",