larkin 0.2.70

package/dist/feishu/channel-transport.cjs

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createChannelTransport = createChannelTransport;
+function createChannelTransport(options) {
+    const handle = ({ path: requestPath, pathNoQuery, method, body }) => {
+        if (/\/channels$/.test(pathNoQuery) && method === "POST") {
+            const name = String(body.name || "").replace(/^#/, "").trim();
+            if (!name)
+                return { ok: false, status: 400, error: "建群需要 name" };
+            const allowPublic = process.env.LARKIN_ALLOW_PUBLIC_CHAT === "1";
+            const privateChat = !(allowPublic && body.visibility === "public");
+            const args = ["im", "+chat-create", "--name", name, "--chat-mode", "group", "--type", privateChat ? "private" : "public", "--json"];
+            if (body.description)
+                args.push("--description", String(body.description).slice(0, 100));
+            if (options.dryRun)
+                args.push("--dry-run");
+            const result = options.larkJsonOut(args);
+            if (!result || result.ok === false)
+                return { ok: false, status: 400, error: (result && options.feishuError(result)) || "建群失败" };
+            const chatId = (result.data && (result.data.chat_id || result.data.chatId)) || "";
+            if (chatId)
+                options.rememberChannel(`#${name}`, chatId, { name, chat_mode: "group", chat_type: "group" });
+            return { ok: true, status: 200, data: { id: `#${name}`, name, type: privateChat ? "private" : "public", joined: true, chatId: chatId || null } };
+        }
+        if (/\/channels\/[^/]+\/members$/.test(pathNoQuery) && (method === "POST" || method === "DELETE")) {
+            const match = pathNoQuery.match(/\/channels\/([^/]+)\/members$/);
+            const target = decodeURIComponent(match[1]);
+            const chatId = options.resolveChatId(target);
+            if (!chatId)
+                return { ok: false, status: 404, error: `未知频道 ${target}` };
+            const raw = body.user || body.agent || "";
+            const resolved = options.resolveMemberTo(chatId, raw);
+            if (!resolved)
+                return { ok: false, status: 400, error: `无法识别成员 "${raw}"：请用 user_id(人) 或 app_id(cli_ 开头，bot)；也支持 open_id(ou_)/union_id(on_)。可先跑 larkin channel members 查看各成员 id。` };
+            const verb = method === "DELETE" ? "delete" : "create";
+            const args = ["im", "chat.members", verb, "--chat-id", chatId, "--member-id-type", resolved.type, "--data", JSON.stringify({ id_list: resolved.ids }), "--json"];
+            if (verb === "delete")
+                args.push("--yes");
+            if (options.dryRun)
+                args.push("--dry-run");
+            const result = options.larkJsonOut(args);
+            if (result?.ok === false)
+                return { ok: false, status: 400, error: options.feishuError(result) || "成员操作失败" };
+            return { ok: true, status: 200, data: { member: { name: String(raw).replace(/^@/, "") || resolved.ids[0] } } };
+        }
+        if (/\/channels\/[^/]+\/join$/.test(pathNoQuery) && method === "POST") {
+            return { ok: false, status: 400, error: "飞书 bot 无法主动加入群聊；请让群主/管理员在群设置里邀请本 bot 进群。" };
+        }
+        if (/\/channels\/[^/]+\/leave$/.test(pathNoQuery) && method === "POST") {
+            const match = pathNoQuery.match(/\/channels\/([^/]+)\/leave$/);
+            const target = decodeURIComponent(match[1]);
+            const chatId = options.resolveChatId(target);
+            const selfApp = options.selectedAgent.feishuAppId;
+            if (!chatId || !selfApp)
+                return { ok: false, status: 400, error: "无法确定 chat_id 或本 bot app_id，退群失败" };
+            const args = ["im", "chat.members", "delete", "--chat-id", chatId, "--member-id-type", "app_id", "--data", JSON.stringify({ id_list: [selfApp] }), "--yes", "--json"];
+            if (options.dryRun)
+                args.push("--dry-run");
+            const result = options.larkJsonOut(args);
+            if (result?.ok === false)
+                return { ok: false, status: 400, error: options.feishuError(result) || "退群失败" };
+            return { ok: true, status: 200, data: { ok: true } };
+        }
+        if (/\/channels\/[^/]+$/.test(pathNoQuery) && method === "PATCH") {
+            const match = pathNoQuery.match(/\/channels\/([^/]+)$/);
+            const target = decodeURIComponent(match[1]);
+            const chatId = options.resolveChatId(target);
+            if (!chatId)
+                return { ok: false, status: 404, error: `未知频道 ${target}` };
+            const newName = body.name !== undefined ? String(body.name).replace(/^#/, "").slice(0, 60) : undefined;
+            const args = ["im", "+chat-update", "--chat-id", chatId, "--json"];
+            if (newName !== undefined)
+                args.push("--name", newName);
+            if (body.description !== undefined)
+                args.push("--description", String(body.description).slice(0, 100));
+            if (newName === undefined && body.description === undefined)
+                return { ok: false, status: 400, error: "飞书群仅支持改名称/描述；public/private 无法通过更新变更。" };
+            if (options.dryRun)
+                args.push("--dry-run");
+            const result = options.larkJsonOut(args);
+            if (!result || result.ok === false)
+                return { ok: false, status: 400, error: (result && options.feishuError(result)) || "改群失败" };
+            options.invalidateChatMeta(chatId);
+            const meta = options.chatMeta(chatId);
+            const name = newName !== undefined ? newName : ((meta && meta.name) || target.replace(/^#/, ""));
+            return { ok: true, status: 200, data: { name, type: body.visibility === "private" ? "private" : "public" } };
+        }
+        if (/\/attachments\/[^/]+$/.test(pathNoQuery) && method === "GET") {
+            return { ok: false, status: 501, error: "附件下载/预览暂未接入 larkin（当前仅支持上传并发送附件）。" };
+        }
+        if (requestPath.includes("/channel-members") || /\/channels\/[^/]+\/members/.test(requestPath)) {
+            const match = requestPath.match(/\/channels\/([^/]+)\/members/);
+            const ref = match ? decodeURIComponent(match[1]) : (options.query(requestPath, "channel") || "");
+            const { chat_id: chatId, channel_type: channelType } = options.channelContext(ref);
+            let agents = [];
+            let humans = [];
+            if (chatId) {
+                const result = options.larkJsonOut(["im", "+chat-members-list", "--chat-id", chatId, "--member-id-type", "user_id", "--json"]);
+                if (result?.ok && result.data) {
+                    agents = (result.data.bots || []).map((bot) => ({ name: bot.name || bot.app_id || "bot", status: "active", id: bot.app_id || bot.member_id || null }));
+                    humans = (result.data.users || []).map((user) => ({ name: user.name || user.member_id || "user", description: null, id: user.member_id || null }));
+                }
+                else if (result?.ok === false) {
+                    const error = options.feishuError(result);
+                    if (error) {
+                        options.log(`members 报错→原样抛给 agent: ${error.slice(0, 120)}`);
+                        return { ok: false, status: result.error?.code === 99991672 ? 403 : 400, error };
+                    }
+                    options.log(`members 降级(空): ${JSON.stringify(result.error || {}).slice(0, 120)}`);
+                }
+            }
+            return { ok: true, status: 200, data: { channel: { ref, type: channelType }, agents, humans } };
+        }
+        if (requestPath.includes("/channel")) {
+            const match = requestPath.match(/\/channels\/([^/?]+)/);
+            const ref = match ? decodeURIComponent(match[1]) : (options.query(requestPath, "channel") || options.query(requestPath, "ref") || "");
+            if (ref) {
+                const { label, chatId, meta, ctx, topicShort } = options.channelLabel(ref);
+                const isThread = Boolean(topicShort);
+                const channel = {
+                    id: ref, name: label, joined: true, chatId: chatId || null,
+                    chatMode: (meta && meta.chat_mode) || null, chatType: (meta && meta.chat_type) || null,
+                    type: isThread ? "thread" : (String(ref).startsWith("dm:") ? "dm" : "channel"),
+                    threadId: isThread ? ((ctx && ctx.thread_id) || null) : null,
+                };
+                return { ok: true, status: 200, data: { channel, channels: [channel] } };
+            }
+            const map = options.mappedChannels();
+            const channels = Object.keys(map).slice(0, 20).map((target) => {
+                const meta = options.chatMeta(map[target]);
+                return { id: target, name: (meta && meta.name) || String(target).replace(/^#/, "").replace(/^dm:@/, ""), joined: true };
+            });
+            return { ok: true, status: 200, data: { channels } };
+        }
+        if (requestPath.includes("/profile")) {
+            const app = options.feishuAppInfo();
+            const botName = options.botDisplayName() || (app && app.name);
+            const name = botName || options.agentName;
+            return { ok: true, status: 200, data: {
+                    kind: "agent", id: options.agentId, isSelf: true, name, displayName: name,
+                    description: (app && app.description) || null, avatarUrl: (app && app.avatarUrl) || null,
+                    status: "active", serverRole: null, runtime: options.agentRuntime, model: options.agentModel,
+                    reasoningEffort: options.agentEffort, executionMode: "byoc", computerId: null,
+                    computerName: options.agentName, computerHostname: options.agentName, daemonVersion: null,
+                    creator: null, createdAgents: [], createdAt: options.selectedAgent.createdAt ?? options.unknownCreatedAt, deletedAt: null,
+                } };
+        }
+        return undefined;
+    };
+    return { handle };
+}

package/dist/feishu/channel-transport.mjs

@@ -0,0 +1,148 @@
+export function createChannelTransport(options) {
+    const handle = ({ path: requestPath, pathNoQuery, method, body }) => {
+        if (/\/channels$/.test(pathNoQuery) && method === "POST") {
+            const name = String(body.name || "").replace(/^#/, "").trim();
+            if (!name)
+                return { ok: false, status: 400, error: "建群需要 name" };
+            const allowPublic = process.env.LARKIN_ALLOW_PUBLIC_CHAT === "1";
+            const privateChat = !(allowPublic && body.visibility === "public");
+            const args = ["im", "+chat-create", "--name", name, "--chat-mode", "group", "--type", privateChat ? "private" : "public", "--json"];
+            if (body.description)
+                args.push("--description", String(body.description).slice(0, 100));
+            if (options.dryRun)
+                args.push("--dry-run");
+            const result = options.larkJsonOut(args);
+            if (!result || result.ok === false)
+                return { ok: false, status: 400, error: (result && options.feishuError(result)) || "建群失败" };
+            const chatId = (result.data && (result.data.chat_id || result.data.chatId)) || "";
+            if (chatId)
+                options.rememberChannel(`#${name}`, chatId, { name, chat_mode: "group", chat_type: "group" });
+            return { ok: true, status: 200, data: { id: `#${name}`, name, type: privateChat ? "private" : "public", joined: true, chatId: chatId || null } };
+        }
+        if (/\/channels\/[^/]+\/members$/.test(pathNoQuery) && (method === "POST" || method === "DELETE")) {
+            const match = pathNoQuery.match(/\/channels\/([^/]+)\/members$/);
+            const target = decodeURIComponent(match[1]);
+            const chatId = options.resolveChatId(target);
+            if (!chatId)
+                return { ok: false, status: 404, error: `未知频道 ${target}` };
+            const raw = body.user || body.agent || "";
+            const resolved = options.resolveMemberTo(chatId, raw);
+            if (!resolved)
+                return { ok: false, status: 400, error: `无法识别成员 "${raw}"：请用 user_id(人) 或 app_id(cli_ 开头，bot)；也支持 open_id(ou_)/union_id(on_)。可先跑 larkin channel members 查看各成员 id。` };
+            const verb = method === "DELETE" ? "delete" : "create";
+            const args = ["im", "chat.members", verb, "--chat-id", chatId, "--member-id-type", resolved.type, "--data", JSON.stringify({ id_list: resolved.ids }), "--json"];
+            if (verb === "delete")
+                args.push("--yes");
+            if (options.dryRun)
+                args.push("--dry-run");
+            const result = options.larkJsonOut(args);
+            if (result?.ok === false)
+                return { ok: false, status: 400, error: options.feishuError(result) || "成员操作失败" };
+            return { ok: true, status: 200, data: { member: { name: String(raw).replace(/^@/, "") || resolved.ids[0] } } };
+        }
+        if (/\/channels\/[^/]+\/join$/.test(pathNoQuery) && method === "POST") {
+            return { ok: false, status: 400, error: "飞书 bot 无法主动加入群聊；请让群主/管理员在群设置里邀请本 bot 进群。" };
+        }
+        if (/\/channels\/[^/]+\/leave$/.test(pathNoQuery) && method === "POST") {
+            const match = pathNoQuery.match(/\/channels\/([^/]+)\/leave$/);
+            const target = decodeURIComponent(match[1]);
+            const chatId = options.resolveChatId(target);
+            const selfApp = options.selectedAgent.feishuAppId;
+            if (!chatId || !selfApp)
+                return { ok: false, status: 400, error: "无法确定 chat_id 或本 bot app_id，退群失败" };
+            const args = ["im", "chat.members", "delete", "--chat-id", chatId, "--member-id-type", "app_id", "--data", JSON.stringify({ id_list: [selfApp] }), "--yes", "--json"];
+            if (options.dryRun)
+                args.push("--dry-run");
+            const result = options.larkJsonOut(args);
+            if (result?.ok === false)
+                return { ok: false, status: 400, error: options.feishuError(result) || "退群失败" };
+            return { ok: true, status: 200, data: { ok: true } };
+        }
+        if (/\/channels\/[^/]+$/.test(pathNoQuery) && method === "PATCH") {
+            const match = pathNoQuery.match(/\/channels\/([^/]+)$/);
+            const target = decodeURIComponent(match[1]);
+            const chatId = options.resolveChatId(target);
+            if (!chatId)
+                return { ok: false, status: 404, error: `未知频道 ${target}` };
+            const newName = body.name !== undefined ? String(body.name).replace(/^#/, "").slice(0, 60) : undefined;
+            const args = ["im", "+chat-update", "--chat-id", chatId, "--json"];
+            if (newName !== undefined)
+                args.push("--name", newName);
+            if (body.description !== undefined)
+                args.push("--description", String(body.description).slice(0, 100));
+            if (newName === undefined && body.description === undefined)
+                return { ok: false, status: 400, error: "飞书群仅支持改名称/描述；public/private 无法通过更新变更。" };
+            if (options.dryRun)
+                args.push("--dry-run");
+            const result = options.larkJsonOut(args);
+            if (!result || result.ok === false)
+                return { ok: false, status: 400, error: (result && options.feishuError(result)) || "改群失败" };
+            options.invalidateChatMeta(chatId);
+            const meta = options.chatMeta(chatId);
+            const name = newName !== undefined ? newName : ((meta && meta.name) || target.replace(/^#/, ""));
+            return { ok: true, status: 200, data: { name, type: body.visibility === "private" ? "private" : "public" } };
+        }
+        if (/\/attachments\/[^/]+$/.test(pathNoQuery) && method === "GET") {
+            return { ok: false, status: 501, error: "附件下载/预览暂未接入 larkin（当前仅支持上传并发送附件）。" };
+        }
+        if (requestPath.includes("/channel-members") || /\/channels\/[^/]+\/members/.test(requestPath)) {
+            const match = requestPath.match(/\/channels\/([^/]+)\/members/);
+            const ref = match ? decodeURIComponent(match[1]) : (options.query(requestPath, "channel") || "");
+            const { chat_id: chatId, channel_type: channelType } = options.channelContext(ref);
+            let agents = [];
+            let humans = [];
+            if (chatId) {
+                const result = options.larkJsonOut(["im", "+chat-members-list", "--chat-id", chatId, "--member-id-type", "user_id", "--json"]);
+                if (result?.ok && result.data) {
+                    agents = (result.data.bots || []).map((bot) => ({ name: bot.name || bot.app_id || "bot", status: "active", id: bot.app_id || bot.member_id || null }));
+                    humans = (result.data.users || []).map((user) => ({ name: user.name || user.member_id || "user", description: null, id: user.member_id || null }));
+                }
+                else if (result?.ok === false) {
+                    const error = options.feishuError(result);
+                    if (error) {
+                        options.log(`members 报错→原样抛给 agent: ${error.slice(0, 120)}`);
+                        return { ok: false, status: result.error?.code === 99991672 ? 403 : 400, error };
+                    }
+                    options.log(`members 降级(空): ${JSON.stringify(result.error || {}).slice(0, 120)}`);
+                }
+            }
+            return { ok: true, status: 200, data: { channel: { ref, type: channelType }, agents, humans } };
+        }
+        if (requestPath.includes("/channel")) {
+            const match = requestPath.match(/\/channels\/([^/?]+)/);
+            const ref = match ? decodeURIComponent(match[1]) : (options.query(requestPath, "channel") || options.query(requestPath, "ref") || "");
+            if (ref) {
+                const { label, chatId, meta, ctx, topicShort } = options.channelLabel(ref);
+                const isThread = Boolean(topicShort);
+                const channel = {
+                    id: ref, name: label, joined: true, chatId: chatId || null,
+                    chatMode: (meta && meta.chat_mode) || null, chatType: (meta && meta.chat_type) || null,
+                    type: isThread ? "thread" : (String(ref).startsWith("dm:") ? "dm" : "channel"),
+                    threadId: isThread ? ((ctx && ctx.thread_id) || null) : null,
+                };
+                return { ok: true, status: 200, data: { channel, channels: [channel] } };
+            }
+            const map = options.mappedChannels();
+            const channels = Object.keys(map).slice(0, 20).map((target) => {
+                const meta = options.chatMeta(map[target]);
+                return { id: target, name: (meta && meta.name) || String(target).replace(/^#/, "").replace(/^dm:@/, ""), joined: true };
+            });
+            return { ok: true, status: 200, data: { channels } };
+        }
+        if (requestPath.includes("/profile")) {
+            const app = options.feishuAppInfo();
+            const botName = options.botDisplayName() || (app && app.name);
+            const name = botName || options.agentName;
+            return { ok: true, status: 200, data: {
+                    kind: "agent", id: options.agentId, isSelf: true, name, displayName: name,
+                    description: (app && app.description) || null, avatarUrl: (app && app.avatarUrl) || null,
+                    status: "active", serverRole: null, runtime: options.agentRuntime, model: options.agentModel,
+                    reasoningEffort: options.agentEffort, executionMode: "byoc", computerId: null,
+                    computerName: options.agentName, computerHostname: options.agentName, daemonVersion: null,
+                    creator: null, createdAgents: [], createdAt: options.selectedAgent.createdAt ?? options.unknownCreatedAt, deletedAt: null,
+                } };
+        }
+        return undefined;
+    };
+    return { handle };
+}

package/dist/feishu/document-comment.cjs

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCUMENT_COMMENT_EVENT = void 0;
+exports.documentCommentEventId = documentCommentEventId;
+exports.documentCommentNoticeType = documentCommentNoticeType;
+exports.documentCommentMessageId = documentCommentMessageId;
+exports.documentCommentTarget = documentCommentTarget;
+exports.parseDocumentCommentTarget = parseDocumentCommentTarget;
+exports.extractDocumentCommentContent = extractDocumentCommentContent;
+exports.resolveDocumentCommentContext = resolveDocumentCommentContext;
+exports.projectDocumentCommentEnvelope = projectDocumentCommentEnvelope;
+const node_crypto_1 = require("node:crypto");
+exports.DOCUMENT_COMMENT_EVENT = "drive.notice.comment_add_v1";
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function rawEvent(event) {
+    return record(event.raw);
+}
+function documentCommentEventId(event) {
+    const raw = rawEvent(event);
+    const header = record(raw?.header);
+    const value = raw?.event_id ?? header?.event_id;
+    return typeof value === "string" && value ? value : null;
+}
+function documentCommentNoticeType(event) {
+    const raw = rawEvent(event);
+    const meta = record(raw?.notice_meta);
+    const value = raw?.notice_type ?? meta?.notice_type;
+    return typeof value === "string" && value ? value : event.replyId ? "add_reply" : "add_comment";
+}
+function documentCommentMessageId(agentId, event) {
+    // Feishu may redeliver the same semantic notice under a different event_id.
+    // The comment locator is the durable identity; event_id remains transport metadata only.
+    const stable = [agentId, event.fileType, event.fileToken, event.commentId, event.replyId || "", documentCommentNoticeType(event)];
+    return `doc_comment_${(0, node_crypto_1.createHash)("sha256").update(JSON.stringify(stable)).digest("hex").slice(0, 32)}`;
+}
+function documentCommentTarget(target, commentId, topLevel = false) {
+    return `document-comment:${target.fileType}:${target.fileToken}:${commentId}:${topLevel ? "top-level" : "in-thread"}`;
+}
+function parseDocumentCommentTarget(value) {
+    const match = /^document-comment:(doc|docx|sheet|file):([A-Za-z0-9_-]+):([A-Za-z0-9_-]+):(in-thread|top-level)$/.exec(value);
+    return match ? {
+        fileType: match[1], fileToken: match[2], commentId: match[3], topLevel: match[4] === "top-level",
+    } : null;
+}
+function extractDocumentCommentContent(fetched, replyId) {
+    const reply = replyId
+        ? fetched.replies.find((candidate) => candidate.reply_id === replyId)
+        : fetched.replies.at(-1);
+    if (!reply?.reply_id)
+        return null;
+    const content = (reply.content?.elements ?? []).map((element) => {
+        if (element.type === "text_run")
+            return element.text_run?.text ?? "";
+        if (element.type === "docs_link")
+            return element.docs_link?.url ?? "";
+        return "";
+    }).join("").trim();
+    return content ? { content, targetReplyId: reply.reply_id } : null;
+}
+async function resolveDocumentCommentContext(comments, event) {
+    const target = await comments.resolveTarget(event.fileToken, event.fileType);
+    if (!target)
+        return null;
+    const fetched = await comments.fetch(target, event.commentId);
+    if (!fetched)
+        return null;
+    const extracted = extractDocumentCommentContent(fetched, event.replyId);
+    if (!extracted)
+        return null;
+    return {
+        target,
+        content: extracted.content,
+        quote: fetched.quote?.trim() || null,
+        isWhole: fetched.isWhole,
+        targetReplyId: extracted.targetReplyId,
+        noticeType: documentCommentNoticeType(event),
+    };
+}
+function projectDocumentCommentEnvelope(input) {
+    const { agentId, event, context, subscription } = input;
+    const messageId = documentCommentMessageId(agentId, event);
+    const timestamp = Number.isFinite(event.timestamp) ? new Date(event.timestamp).toISOString() : new Date().toISOString();
+    const target = documentCommentTarget(context.target, event.commentId, context.isWhole);
+    return {
+        kind: "document_comment",
+        event_type: exports.DOCUMENT_COMMENT_EVENT,
+        message_id: messageId,
+        seq: Number.isSafeInteger(event.timestamp) && event.timestamp > 0 ? event.timestamp : 1,
+        target,
+        wake: true,
+        comment_subscription_mode: subscription.mode,
+        comment_subscription_status: subscription.status,
+        comment_subscription_source: subscription.source,
+        comment_subscription_dimension: subscription.dimension,
+        mentioned_bot: subscription.mentionedBot,
+        timestamp,
+        sender_id: event.operator.openId,
+        sender_name: event.operator.openId,
+        sender_type: "human",
+        content: context.content,
+        quote: context.quote,
+        notice_type: context.noticeType,
+        file_type: context.target.fileType,
+        file_token: context.target.fileToken,
+        source_file_type: event.fileType,
+        source_file_token: event.fileToken,
+        comment_id: event.commentId,
+        reply_id: event.replyId ?? null,
+        target_reply_id: context.targetReplyId,
+        is_whole: context.isWhole,
+        reply: {
+            command: "comment reply",
+            argv: ["comment", "reply", "--message-id", messageId, "--text", "<reply_text>"],
+            mode: context.isWhole ? "top-level-fallback" : "in-thread",
+            target,
+        },
+    };
+}

package/dist/feishu/document-comment.mjs

@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+export const DOCUMENT_COMMENT_EVENT = "drive.notice.comment_add_v1";
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function rawEvent(event) {
+    return record(event.raw);
+}
+export function documentCommentEventId(event) {
+    const raw = rawEvent(event);
+    const header = record(raw?.header);
+    const value = raw?.event_id ?? header?.event_id;
+    return typeof value === "string" && value ? value : null;
+}
+export function documentCommentNoticeType(event) {
+    const raw = rawEvent(event);
+    const meta = record(raw?.notice_meta);
+    const value = raw?.notice_type ?? meta?.notice_type;
+    return typeof value === "string" && value ? value : event.replyId ? "add_reply" : "add_comment";
+}
+export function documentCommentMessageId(agentId, event) {
+    // Feishu may redeliver the same semantic notice under a different event_id.
+    // The comment locator is the durable identity; event_id remains transport metadata only.
+    const stable = [agentId, event.fileType, event.fileToken, event.commentId, event.replyId || "", documentCommentNoticeType(event)];
+    return `doc_comment_${createHash("sha256").update(JSON.stringify(stable)).digest("hex").slice(0, 32)}`;
+}
+export function documentCommentTarget(target, commentId, topLevel = false) {
+    return `document-comment:${target.fileType}:${target.fileToken}:${commentId}:${topLevel ? "top-level" : "in-thread"}`;
+}
+export function parseDocumentCommentTarget(value) {
+    const match = /^document-comment:(doc|docx|sheet|file):([A-Za-z0-9_-]+):([A-Za-z0-9_-]+):(in-thread|top-level)$/.exec(value);
+    return match ? {
+        fileType: match[1], fileToken: match[2], commentId: match[3], topLevel: match[4] === "top-level",
+    } : null;
+}
+export function extractDocumentCommentContent(fetched, replyId) {
+    const reply = replyId
+        ? fetched.replies.find((candidate) => candidate.reply_id === replyId)
+        : fetched.replies.at(-1);
+    if (!reply?.reply_id)
+        return null;
+    const content = (reply.content?.elements ?? []).map((element) => {
+        if (element.type === "text_run")
+            return element.text_run?.text ?? "";
+        if (element.type === "docs_link")
+            return element.docs_link?.url ?? "";
+        return "";
+    }).join("").trim();
+    return content ? { content, targetReplyId: reply.reply_id } : null;
+}
+export async function resolveDocumentCommentContext(comments, event) {
+    const target = await comments.resolveTarget(event.fileToken, event.fileType);
+    if (!target)
+        return null;
+    const fetched = await comments.fetch(target, event.commentId);
+    if (!fetched)
+        return null;
+    const extracted = extractDocumentCommentContent(fetched, event.replyId);
+    if (!extracted)
+        return null;
+    return {
+        target,
+        content: extracted.content,
+        quote: fetched.quote?.trim() || null,
+        isWhole: fetched.isWhole,
+        targetReplyId: extracted.targetReplyId,
+        noticeType: documentCommentNoticeType(event),
+    };
+}
+export function projectDocumentCommentEnvelope(input) {
+    const { agentId, event, context, subscription } = input;
+    const messageId = documentCommentMessageId(agentId, event);
+    const timestamp = Number.isFinite(event.timestamp) ? new Date(event.timestamp).toISOString() : new Date().toISOString();
+    const target = documentCommentTarget(context.target, event.commentId, context.isWhole);
+    return {
+        kind: "document_comment",
+        event_type: DOCUMENT_COMMENT_EVENT,
+        message_id: messageId,
+        seq: Number.isSafeInteger(event.timestamp) && event.timestamp > 0 ? event.timestamp : 1,
+        target,
+        wake: true,
+        comment_subscription_mode: subscription.mode,
+        comment_subscription_status: subscription.status,
+        comment_subscription_source: subscription.source,
+        comment_subscription_dimension: subscription.dimension,
+        mentioned_bot: subscription.mentionedBot,
+        timestamp,
+        sender_id: event.operator.openId,
+        sender_name: event.operator.openId,
+        sender_type: "human",
+        content: context.content,
+        quote: context.quote,
+        notice_type: context.noticeType,
+        file_type: context.target.fileType,
+        file_token: context.target.fileToken,
+        source_file_type: event.fileType,
+        source_file_token: event.fileToken,
+        comment_id: event.commentId,
+        reply_id: event.replyId ?? null,
+        target_reply_id: context.targetReplyId,
+        is_whole: context.isWhole,
+        reply: {
+            command: "comment reply",
+            argv: ["comment", "reply", "--message-id", messageId, "--text", "<reply_text>"],
+            mode: context.isWhole ? "top-level-fallback" : "in-thread",
+            target,
+        },
+    };
+}