weaver-work-cli 0.1.32 → 0.1.36

package/dist/shortcuts/im/operations/at-mention.js

@@ -0,0 +1,127 @@
+import { imValidationError } from '../errors.js';
+import { extractGroupMembers, isSystemMember, str, unwrapInner } from './shared.js';
+/**
+ * 群聊 @ 提及（@所有人 / @具体人）。
+ *
+ * 服务端契约（2026-10-29 实测 yunteams，群 1793244595701000005）：
+ * - 只能通过 `sendGroupMsg` 的 **`msg` 字段**（完整原生 msg JSON 字符串）携带 @；
+ *   `txt` 字段传 JSON 字符串会被服务端原样塞进 `dt[0].txt.v`，客户端直接显示 JSON 原文（踩坑确认）。
+ * - 原生结构：`{ bgc:'', cnt:'0', dev:5, display:'', dt:[{txt:{aus, ft:'china', next:'0', v}}],
+ *   guid:'0', idx:'0', opb:['received','reply'], scid, sname, suid, sysId:'', type:'1', ver:'1.0', weaOaId:'' }`
+ * - `txt.aus` 条目：@具体人 `{ cid:<人cid>, fd:'@', id:<人uid>, nm:<姓名>, t:'1' }`；
+ *   @所有人固定 `{ cid:'10000', fd:'@', id:'88', nm:'全体成员', t:'2' }`。
+ * - `txt.v` 中每个 @ 位置写占位符 `:@<id>;`（冒号+@+id+分号），其余文本原样保留；
+ *   客户端渲染时用 aus 把占位符还原为 `@<nm>`。
+ */
+/** @全体成员 的服务端固定条目。 */
+export const AT_ALL_ENTRY = { cid: '10000', fd: '@', id: '88', nm: '全体成员', t: '2' };
+function truthy(value) {
+    return value === true || value === 'true' || value === '1';
+}
+function uidList(value) {
+    if (value === undefined || value === null || value === '')
+        return [];
+    const raw = Array.isArray(value)
+        ? value.map((x) => str(x))
+        : String(value).split(/[,，;；\s]+/);
+    return raw.map((x) => x.trim()).filter((x) => x && x !== '0');
+}
+/** 调用方是否带了任何 @ 入参（含显式无效值，用于单聊报错）。 */
+export function hasAtInput(args) {
+    return args.atAll !== undefined || args.atUids !== undefined;
+}
+/**
+ * 解析 @ 入参为 aus 条目列表。
+ * @具体人必须逐个核实已在目标群（getGroupUsers，member_mask=6 只取 uid+cid），
+ * 不在群内直接拒绝（错误码 at_member_not_in_group）；姓名一律走 hrm 解析（不用 IM 返回的 name）。
+ */
+export async function resolveAtMentions(args, env, groupId) {
+    const atAll = truthy(args.atAll);
+    const atUids = uidList(args.atUids);
+    if (!atAll && !atUids.length)
+        return [];
+    const entries = [];
+    if (atAll)
+        entries.push({ ...AT_ALL_ENTRY });
+    if (atUids.length) {
+        let members = [];
+        try {
+            const res = await env.host.request({
+                method: 'POST',
+                path: '/api/em/msg/executeIm/group/getGroupUsers',
+                body: { group_id: groupId, type: 0, sync_type: 0, member_mask: 6, client_uc: '0' },
+                operation: 'im.msg.send.group.atMembers',
+            });
+            members = extractGroupMembers(unwrapInner(res));
+        }
+        catch (error) {
+            throw imValidationError('at_members_unavailable', `无法核实 @ 目标是否在群内：拉取群成员失败（${error instanceof Error ? error.message : String(error)}）`, { groupId, atUids });
+        }
+        const inGroup = new Map();
+        for (const m of members) {
+            if (isSystemMember(m))
+                continue;
+            inGroup.set(str(m.uid), str(m.cid));
+        }
+        const missing = atUids.filter((uid) => !inGroup.has(uid));
+        if (missing.length) {
+            throw imValidationError('at_member_not_in_group', `以下 @ 目标不在群 ${groupId} 内，已拒绝发送：${missing.join(', ')}`, { groupId, missing, atUids });
+        }
+        const personMap = await env.host.resolveUsersByIds([...new Set(atUids)]);
+        for (const uid of atUids) {
+            entries.push({ cid: inGroup.get(uid) || '', fd: '@', id: uid, nm: personMap[uid]?.name || uid, t: '1' });
+        }
+    }
+    return entries;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * 把 @ 入参落进文本：文本中出现的 `@<姓名>`（@全体成员兼认 `@所有人`）替换为 `:@<id>;` 占位符；
+ * 未在文本中出现的提及按传入顺序前置（`:@<id>;` 两空格分隔，仿客户端格式）。
+ * 返回原生 txt 需要的 `v`（占位文本）与 `aus`（按 v 中出现顺序）。
+ */
+export function buildAtText(text, entries) {
+    let v = String(text ?? '');
+    const used = new Set();
+    for (const entry of entries) {
+        const names = entry.t === '2' ? ['全体成员', '所有人'] : [entry.nm];
+        for (const nm of names) {
+            const re = new RegExp(`@${escapeRegExp(nm)}`, 'g');
+            if (!re.test(v))
+                continue;
+            v = v.replace(re, () => `:@${entry.id};`);
+            used.add(entry);
+            break;
+        }
+    }
+    const rest = entries.filter((e) => !used.has(e));
+    if (rest.length) {
+        const prefix = rest.map((e) => `:@${e.id};`).join('  ');
+        v = v.trim() ? `${prefix}  ${v}` : prefix;
+    }
+    const aus = [...used, ...rest];
+    return { v, aus };
+}
+/** 组装 sendGroupMsg 的 `msg` 字段值（完整原生 msg JSON 字符串）。 */
+export function buildAtMsgJson(v, aus, self, extra = {}) {
+    return JSON.stringify({
+        bgc: '',
+        cnt: '0',
+        dev: 5,
+        display: '',
+        dt: [{ txt: { aus, ft: 'china', next: '0', v } }],
+        guid: '0',
+        idx: '0',
+        opb: ['received', 'reply'],
+        scid: self.cid,
+        sname: self.name,
+        suid: self.uid,
+        sysId: '',
+        type: '1',
+        ver: '1.0',
+        weaOaId: '',
+        ...extra,
+    });
+}

package/dist/shortcuts/im/operations/file-user.js

@@ -72,7 +72,11 @@ const filePreview = {
         toUid: { type: 'string', description: '单聊场景对方 uid' },
         toCid: { type: 'string', description: '单聊场景对方 cid' },
         imgFormat: { type: 'string', enum: ['small', 'large', 'original'], description: '图片规格（默认 small）' },
-    }, { required: ['fileId', 'msgid'], description: '媒体预览 URL' }),
+    }, {
+        required: ['fileId', 'msgid'],
+        anyOf: [{ required: ['groupId'] }, { required: ['toUid', 'toCid'] }],
+        description: '媒体预览 URL（groupId 群聊 或 toUid+toCid 单聊，二选一）',
+    }),
     handler: async (args, { host }) => {
         const kind = String(args.kind ?? 'img') === 'video' ? 'video' : 'img';
         const fileId = String(args.fileId);
@@ -137,7 +141,11 @@ const fileDownload = {
         toCid: { type: 'string', description: '单聊场景对方 cid（与 groupId 二选一）' },
         imgFormat: { type: 'string', enum: ['small', 'large', 'original'], description: '图片规格（默认 small；要原图传 original）' },
         output: { type: 'string', minLength: 1, description: '本地输出文件路径（父目录必须存在，已存在则拒绝）' },
-    }, { required: ['fileId', 'msgid', 'output'], description: '媒体/文件落地到本地' }),
+    }, {
+        required: ['fileId', 'msgid', 'output'],
+        anyOf: [{ required: ['groupId'] }, { required: ['toUid', 'toCid'] }],
+        description: '媒体/文件落地到本地（groupId 群聊 或 toUid+toCid 单聊，二选一）',
+    }),
     handler: async (args, { host }) => {
         const fileId = String(args.fileId ?? '');
         const msgid = String(args.msgid ?? '');

package/dist/shortcuts/im/operations/group-read.js

@@ -1,6 +1,6 @@
 import { imValidationError } from '../errors.js';
 import { READ, schemaOf, imSuccess, } from './types.js';
-import { assertImOk, compact, extractGroupMembers, formatFullTime, splitIds, str, toPositiveInt, toUint, unwrapInner, } from './shared.js';
+import { assertImOk, compact, extractGroupMembers, formatFullTime, isSystemMember, splitIds, str, toPositiveInt, toUint, unwrapInner, } from './shared.js';
 const SEARCH_TYPE_MASK = {
     type: 1,
     key: 2,
@@ -153,7 +153,7 @@ const groupInfo = {
     inputSchema: schemaOf({
         groupIds: { type: 'array', items: { type: 'string' }, description: '群 id 列表（逗号串或数组）' },
         groupId: { type: 'string', description: '单群 id（groupIds 的便捷形式）' },
-    }, { description: 'groupIds / groupId 至少其一' }),
+    }, { requiredAny: ['groupIds', 'groupId'], description: '按群 id 查基础信息（groupIds / groupId 至少其一）' }),
     handler: async (args, { host }) => {
         let ids = [];
         if (Array.isArray(args.groupIds))
@@ -186,12 +186,23 @@ const groupInfo = {
             maskName: maskTypeName(Number(g.mask ?? 0)),
             userNum: g.user_num,
             maxNum: g.max_num,
-            hostUid: str(g.host_uid ?? g.hostUid ?? ''),
+            /** 群创建者 uid（服务端字段 host_uid）；**不是群主**，群主以 group.users 的 role=3 为准。 */
+            creatorUid: str(g.host_uid ?? g.hostUid ?? ''),
+            /** 群创建者 cid（服务端字段 host_cid），与 creatorUid 配对。 */
+            creatorCid: str(g.host_cid ?? g.hostCid ?? ''),
             state: Number(g.state ?? -1),
             stateName: stateName(Number(g.state ?? -1)),
             createTime: formatFullTime(g.create_time ?? g.createTime),
         }));
-        return imSuccess('im.group.info', { total: groups.length, groups });
+        return imSuccess('im.group.info', {
+            total: groups.length,
+            groups,
+            fieldNotes: {
+                creatorUid: '群创建者（host_uid），不是群主；创建后转让群主也不会变。',
+                creatorCid: '群创建者 cid（host_cid）。',
+                owner: '群主请用 im.group.users 的 role=3（或 im.group.admins）获取，不要用 creatorUid 判断。',
+            },
+        });
     },
 };
 /** 群成员列表。 */
@@ -233,7 +244,11 @@ const groupUsers = {
         const hasCid = (memberMask & 2) !== 0;
         const hasUid = (memberMask & 4) !== 0;
         const roleNames = { 0: '不可用', 1: '普通成员', 2: '管理员', 3: '群主', 4: '客户', 5: '负责人', 6: '协助人员' };
-        const personIds = members.map((m) => String(m?.uid ?? '')).filter((x) => x && x !== '0');
+        // 系统成员没有 hrm 资料，不必进解析批次（省一次无效 id，也避免被当成「解析失败」）
+        const personIds = members
+            .filter((m) => !isSystemMember(m))
+            .map((m) => String(m?.uid ?? ''))
+            .filter((x) => x && x !== '0');
         // 姓名一律走 hrm 解析（不看 member_mask 的 name 位，也不使用 IM 返回的 name 字段）
         const personMap = personIds.length ? await host.resolveUsersByIds([...new Set(personIds)]) : {};
         const rows = members.map((m) => ({
@@ -243,10 +258,16 @@ const groupUsers = {
             role: hasRole ? Number(m.role_type ?? m.role ?? -1) : undefined,
             roleName: hasRole ? roleNames[Number(m.role_type ?? m.role ?? -1)] ?? '-' : undefined,
             addTime: hasAddTime ? formatFullTime(m.add_time ?? m.addTime) : undefined,
+            /** 服务端自动补入的系统成员（可选功能，不是真实员工），统计真实成员时排除。 */
+            isSystem: hasCid ? isSystemMember(m) : undefined,
         }));
+        const personRows = rows.filter((row) => row.isSystem !== true);
         return imSuccess('im.group.users', {
             groupId,
+            /** 成员总数（含系统成员，即服务端返回的原始条数） */
             totalNum: inner?.total_num ?? rows.length,
+            /** 真实成员数（排除系统成员 cid=10002），判断「只剩自己」请用这个 */
+            personNum: personRows.length,
             endFlag: inner?.end_flag,
             serverUc: str(inner?.server_uc ?? ''),
             members: rows,

package/dist/shortcuts/im/operations/group-write.js

@@ -1,6 +1,6 @@
 import { imValidationError } from '../errors.js';
 import { schemaOf, WRITE, } from './types.js';
-import { assertImOk, compact, splitIds, str, toUint, unwrapInner } from './shared.js';
+import { assertImOk, compact, extractGroupMembers, isSystemMember, splitIds, str, toUint, unwrapInner } from './shared.js';
 import { makeWritePair } from './write-util.js';
 /** 解析 uid 列表为 {cid,uid} 成员，支持 failed 移除。 */
 async function resolveMembers(args, env) {
@@ -59,7 +59,7 @@ const groupCreatePair = makeWritePair({
         }
         const { users, failed, names: resolvedNames } = await resolveMembers(args, env);
         if (failed.length && args.removeFailed !== true) {
-            throw imValidationError('members_resolve_failed', `以下成员信息获取失败（cid/uid 缺失或为 0）：${failed.map((f) => f.name || f.uid).join('、')}；确认移除请传 removeFailed:true`, { details: failed });
+            throw imValidationError('members_resolve_failed', `以下成员信息获取失败（cid/uid 缺失或为 0）：${failed.map((f) => f.name || f.uid).join('、')}；确认移除请传 removeFailed:true`, failed);
         }
         if (users.length === 0)
             throw imValidationError('members_empty', '没有可入群的成员');
@@ -98,6 +98,8 @@ const groupCreatePair = makeWritePair({
                 members: users.map((u) => u.uid),
                 adminCount: admins.length,
                 removeFailed: args.removeFailed === true ? failed.map((f) => f.uid) : [],
+                /** 服务端可选能力：建群时会自动补入系统成员（cid=10002），实际成员数可能比 users 多 1。 */
+                systemMemberNote: '建群后服务端可能自动补入 1 个系统成员（cid=10002，群内系统消息载体，租户侧可选开启）；它不是真实员工，也不是本次传入的成员，不需要也不建议单独踢出。',
             },
             snapshot: { name, users, admins, failed, removeFailed: args.removeFailed === true },
         };
@@ -194,28 +196,29 @@ const groupExitPair = makeWritePair({
         if (!groupId || groupId === '0')
             throw imValidationError('id_invalid', 'groupId 必须非 0');
         /**
-         * 只读回查群人数与群主：实测「群主/最后一个成员退群」后该群会变成无主空群，
+         * 只读回查群主与真实人数：实测「群主/最后一个真实成员退群」后该群会变成无主空群，
          * 之后 join / destroy 都会被服务端拒绝（1210），必须由客户端或管理员处理。
          * 因此这两种情形要求调用方显式传 acknowledgeOrphanRisk:true 才签发 continuation。
+         *
+         * 群主判定只认 **成员列表的 role=3**（getGroupUsers）：group/queryGroupInfo 的 host_uid
+         * 是「群创建者」，转让群主后不会更新，用它判群主会误判（实测已复现）。
          */
         let memberCount;
         let isOwner = false;
         try {
-            const infoRes = await env.host.request({
+            const usersRes = await env.host.request({
                 method: 'POST',
-                path: '/api/em/msg/executeIm/group/queryGroupInfo',
-                body: { trans_id: 0, type: 0, mask: 0, group_id: [groupId], flag: 0 },
-                operation: 'im.group.exit.plan.info',
+                path: '/api/em/msg/executeIm/group/getGroupUsers',
+                body: { group_id: groupId, type: 0, sync_type: 0, member_mask: 142, client_uc: '0' },
+                operation: 'im.group.exit.plan.members',
             });
-            const info = (unwrapInner(infoRes)?.datas || [])[0];
-            if (info) {
-                const raw = info.user_num ?? info.userNum;
-                memberCount = raw === undefined || raw === null ? undefined : Number(raw);
-                const hostUid = str(info.host_uid ?? info.hostUid ?? '');
-                if (hostUid) {
-                    const self = await env.host.getSelfIdentity();
-                    isOwner = hostUid === String(self.uid);
-                }
+            const members = extractGroupMembers(unwrapInner(usersRes));
+            if (members.length) {
+                const self = await env.host.getSelfIdentity();
+                const selfRow = members.find((m) => str(m?.uid) === String(self.uid));
+                isOwner = Number(selfRow?.role_type ?? selfRow?.role ?? -1) === 3;
+                // 系统成员（cid=10002，产品可选能力）不是真实成员，不能算进「是否只剩自己」
+                memberCount = members.filter((m) => !isSystemMember(m)).length;
             }
         }
         catch {
@@ -223,7 +226,7 @@ const groupExitPair = makeWritePair({
         }
         const orphanRisk = isOwner || (memberCount !== undefined && memberCount <= 1);
         if (orphanRisk && args.acknowledgeOrphanRisk !== true) {
-            throw imValidationError('owner_exit_ack_required', `退群风险确认缺失：${isOwner ? '你是该群群主' : '你是该群最后一个成员'}，退群后该群会变成无主空群，之后 join/destroy 都会被服务端拒绝（1210），只能由客户端或管理员处理。确认仍要退群请传 acknowledgeOrphanRisk:true`, { details: { groupId, isOwner, memberCount } });
+            throw imValidationError('owner_exit_ack_required', `退群风险确认缺失：${isOwner ? '你是该群群主' : '你是该群最后一个成员'}，退群后该群会变成无主空群，之后 join/destroy 都会被服务端拒绝（1210），只能由客户端或管理员处理。确认仍要退群请传 acknowledgeOrphanRisk:true`, { groupId, isOwner, memberCount });
         }
         return {
             summary: {
@@ -537,12 +540,16 @@ const groupAnnounceModifyPair = makeWritePair({
         };
     },
 });
-function buildWriteDefinition(name, method, summary, inputProps, pair) {
+function buildWriteDefinition(name, method, summary, inputProps, pair, condition = {}) {
     const requiredInput = Object.keys(inputProps).filter((k) => {
         const prop = inputProps[k];
         return prop?.required === true;
     });
-    const prepareSchema = schemaOf({ ...inputProps, removeFailed: { type: 'boolean', description: '确认移除解析失败成员' } }, { required: requiredInput, description: summary });
+    const prepareSchema = schemaOf({ ...inputProps, removeFailed: { type: 'boolean', description: '确认移除解析失败成员' } }, {
+        ...condition,
+        required: [...new Set([...(condition.required || []), ...requiredInput])],
+        description: summary,
+    });
     return [
         {
             name: `${name}.prepare`,
@@ -579,30 +586,30 @@ const groupWriteOps = [
         name: { type: 'string', description: '群名（缺省自动生成）' },
         names: { type: 'array', items: { type: 'string' }, description: '与 users 顺序对应姓名（用于默认群名）' },
         admins: { type: 'array', items: { type: 'string' }, description: '管理员 uid' },
-    }, groupCreatePair),
+    }, groupCreatePair, { required: ['users'] }),
     ...buildWriteDefinition('im.group.invite', 'group.invite', '邀请成员入群', {
         groupId: { type: 'string', pattern: '^\\d+$', description: '群 id' },
         users: { type: 'array', items: { type: 'string' }, description: '被邀请 uid' },
-    }, groupInvitePair),
+    }, groupInvitePair, { required: ['groupId', 'users'] }),
     ...buildWriteDefinition('im.group.kick', 'group.kick', '踢出群成员', {
         groupId: { type: 'string', pattern: '^\\d+$', description: '群 id' },
         users: { type: 'array', items: { type: 'string' }, description: '被踢 uid' },
-    }, groupKickPair),
+    }, groupKickPair, { required: ['groupId', 'users'] }),
     ...buildWriteDefinition('im.group.exit', 'group.exit', '退出群聊', {
         groupId: { type: 'string', pattern: '^\\d+$', description: '群 id' },
         acknowledgeOrphanRisk: {
             type: 'boolean',
             description: '群主或最后一个成员退群时必须显式传 true（退群后该群会变成无主空群，无法再 join/destroy）',
         },
-    }, groupExitPair),
+    }, groupExitPair, { required: ['groupId'] }),
     ...buildWriteDefinition('im.group.destroy', 'group.destroy', '解散群聊（仅群主，不可恢复）', {
         groupId: { type: 'string', pattern: '^\\d+$', description: '群 id' },
-    }, groupDestroyPair),
+    }, groupDestroyPair, { required: ['groupId'] }),
     ...buildWriteDefinition('im.group.join', 'group.join', '申请加入群聊', {
         groupId: { type: 'string', pattern: '^\\d+$', description: '群 id（token 二选一）' },
         token: { type: 'string', description: '群 token/二维码加入' },
         mark: { type: 'string', maxLength: 100, description: '申请理由' },
-    }, groupJoinPair),
+    }, groupJoinPair, { requiredAny: ['groupId', 'token'] }),
     ...buildWriteDefinition('im.group.modify', 'group.modify', '批量修改群属性（batModGroupInfo）', {
         groupId: { type: 'string', pattern: '^\\d+$', description: '群 id' },
         num: { type: 'integer', description: '最大人数' },
@@ -614,7 +621,7 @@ const groupWriteOps = [
         creator: { type: 'string', description: '转让群主（单 uid）' },
         copyGroupids: { type: 'array', items: { type: 'string' }, description: '拷贝群列表' },
         gtId: { type: 'string', description: '关联群类型 id' },
-    }, groupModifyPair),
+    }, groupModifyPair, { required: ['groupId'] }),
     ...buildWriteDefinition('im.group.rename', 'group.rename', '修改群信息（一次一项：群名/历史/群主/显示/打扰/标记/gtid）', {
         groupId: { type: 'string', pattern: '^\\d+$', description: '群 id' },
         name: { type: 'string', description: '改群名' },
@@ -624,7 +631,7 @@ const groupWriteOps = [
         msgSetting: { type: 'integer', description: '消息打扰设置' },
         mark: { type: 'integer', description: '标记位' },
         gtid: { type: 'string', description: 'GTID' },
-    }, groupRenamePair),
+    }, groupRenamePair, { required: ['groupId'] }),
     ...buildWriteDefinition('im.group.announce.modify', 'group.announce.modify', '新增/修改/删除群公告', {
         groupId: { type: 'string', pattern: '^\\d+$', description: '群 id' },
         annouce: { type: 'string', description: '公告内容（删除时不需要）' },
@@ -633,6 +640,6 @@ const groupWriteOps = [
         notice: { type: 'integer', enum: [0, 1, 2], description: '0 发通知(默认)/1 不发/2 发并@全体' },
         fmark: { type: 'integer', enum: [0, 1], description: '新人必看' },
         related: { type: 'string', description: '关联附件 id' },
-    }, groupAnnounceModifyPair),
+    }, groupAnnounceModifyPair, { required: ['groupId'] }),
 ];
 export const groupWriteOperations = groupWriteOps;

package/dist/shortcuts/im/operations/msg-sync.js

@@ -2,6 +2,7 @@ import { imValidationError } from '../errors.js';
 import { READ, schemaOf, imSuccess, } from './types.js';
 import { assertImOk, clampTimeRangeTo7Days, compact, DEFAULT_PAGE_SIZE, formatFullTime, makeMinMaxIdByTm, paginationMeta, parseMsg, parseTimeToSec, pullPaged, rangeShrinkMeta, resolveAuthUid, sortMessagesNewestFirst, str, todayRange, unwrapInner, } from './shared.js';
 import { collapseNewlines, collectI18nIds, collectPersonIds, extractFiles, extractImgs, extractVideos, parseContent, senderName, } from './msg-parse.js';
+import { extractQuoteSummary } from './quote-mention.js';
 const MAX_MSG_ID = String((1n << 63n) - 1n);
 /**
  * 时间/最新/显式 id 计算 start/end（与源 skill 一致）：
@@ -151,6 +152,7 @@ async function enrichMessages(rawRows, host, options = {}) {
             });
         }
         const sender = senderName(msgObj || {}, row.from_uid, options.authUid, nameMap);
+        const quoteSummary = extractQuoteSummary(msgObj);
         enriched.push({
             msgid: str(row.ser_msgid),
             sender,
@@ -161,6 +163,9 @@ async function enrichMessages(rawRows, host, options = {}) {
             typeName: parsed.typeName,
             title: options.titleFirst ? parsed.title : undefined,
             content: collapseNewlines(parsed.content),
+            ...(quoteSummary
+                ? { quote: quoteSummary, quoteTime: Number(quoteSummary.msgtime) > 0 ? formatFullTime(Math.floor(Number(quoteSummary.msgtime) / 1000)) : undefined }
+                : {}),
             must: parsed.must,
             fileName: parsed.fileName,
             media,
@@ -401,7 +406,7 @@ const msgReadSingle = {
         toCid: { type: 'string', pattern: '^\\d+$', description: '对方 cid' },
         msgids: { type: 'array', items: { type: 'string' }, description: '自己发出的消息 id（最多 50）' },
         recvMsgids: { type: 'array', items: { type: 'string' }, description: '自己接收的消息 id（最多 50）' },
-    }, { required: ['toUid', 'toCid'], description: '查询单聊阅读状态（msgids/recvMsgids 至少其一）' }),
+    }, { required: ['toUid', 'toCid'], requiredAny: ['msgids', 'recvMsgids'], description: '查询单聊阅读状态（msgids / recvMsgids 至少其一）' }),
     handler: async (args, { host }) => {
         const hasSent = Array.isArray(args.msgids) && args.msgids.length > 0;
         const hasRecv = Array.isArray(args.recvMsgids) && args.recvMsgids.length > 0;
@@ -449,7 +454,7 @@ const msgReadGroup = {
         groupId: { type: 'string', pattern: '^\\d+$', description: '群 id' },
         msgids: { type: 'array', items: { type: 'string' }, description: '自己发出的消息 id（最多 50）' },
         recvMsgids: { type: 'array', items: { type: 'string' }, description: '别人发出的消息 id（最多 50）' },
-    }, { required: ['groupId'], description: '查询群消息阅读状态' }),
+    }, { required: ['groupId'], requiredAny: ['msgids', 'recvMsgids'], description: '查询群消息阅读状态（msgids / recvMsgids 至少其一）' }),
     handler: async (args, { host }) => {
         const hasSent = Array.isArray(args.msgids) && args.msgids.length > 0;
         const hasRecv = Array.isArray(args.recvMsgids) && args.recvMsgids.length > 0;

package/dist/shortcuts/im/operations/msg-write.js

@@ -3,6 +3,8 @@ import { resolve } from 'node:path';
 import { imValidationError } from '../errors.js';
 import { schemaOf, } from './types.js';
 import { assertImOk, compact, extractGroupMembers, str } from './shared.js';
+import { buildAtMsgJson, buildAtText, hasAtInput, resolveAtMentions } from './at-mention.js';
+import { hasQuoteInput, resolveQuotedRef } from './quote-mention.js';
 import { fileObjToFile, fileObjToImg, makeWritePair } from './write-util.js';
 /** 校验本地文件存在，返回绝对路径。 */
 function assertLocalFile(pathValue, field) {
@@ -37,7 +39,18 @@ const sendSinglePair = makeWritePair({
         if (!toUid || !toCid || toUid === '0' || toCid === '0') {
             throw imValidationError('id_invalid', 'toUid/toCid 必须非 0');
         }
+        if (hasAtInput(args)) {
+            throw imValidationError('at_not_supported', '@ 提及仅群聊消息支持（单聊发送不接受 atAll/atUids）');
+        }
+        if (args.replyMsgId !== undefined && args.replyMsgId !== null && args.replyMsgId !== '') {
+            throw imValidationError('reply_not_supported', '单聊仅支持引用（quoteMsgId），不支持回复（replyMsgId）');
+        }
         const content = normalizeContent(args);
+        // 引用（仅单聊·文本）：prepare 阶段在单聊会话内定位被引消息并组装 ref
+        const quote = hasQuoteInput(args) ? await resolveQuotedRef(args, env, { toUid, toCid }) : null;
+        if (quote && !content.txt) {
+            throw imValidationError('quote_requires_txt', 'quoteMsgId 仅支持文本消息（txt）');
+        }
         const summary = {
             action: '发送单聊消息',
             toUid,
@@ -51,6 +64,11 @@ const sendSinglePair = makeWritePair({
             snapshot.txt = content.txt;
             summary.textPreview = content.txt.length > 60 ? `${content.txt.slice(0, 60)}…` : content.txt;
         }
+        if (quote) {
+            snapshot.quoteKind = quote.kind;
+            snapshot.quoteRef = quote.ref;
+            summary.quote = { kind: quote.kind, quotedMsgId: quote.quotedMsgId, fromName: quote.fromName, textPreview: quote.text.length > 40 ? `${quote.text.slice(0, 40)}…` : quote.text };
+        }
         if (content.imgPath) {
             const abs = assertLocalFile(content.imgPath, 'img');
             snapshot.imgPath = abs;
@@ -65,8 +83,15 @@ const sendSinglePair = makeWritePair({
     },
     async execute(plan, env) {
         const body = { reciver: { cid: plan.toCid, uid: plan.toUid } };
-        if (plan.txt !== undefined)
+        const quoteRef = plan.quoteRef ?? null;
+        if (quoteRef) {
+            // 引用：完整原生 msg JSON 走 msg 字段（与群聊同款承载方式，实测单聊同样生效）
+            const self = await env.host.getSelfIdentity();
+            body.msg = buildAtMsgJson(String(plan.txt ?? ''), [], self, { ref: quoteRef });
+        }
+        else if (plan.txt !== undefined) {
             body.txt = plan.txt;
+        }
         if (plan.imgPath) {
             const fileObj = await env.host.uploadFile(plan.imgPath, { shareUsers: plan.toUid });
             body.img = fileObjToImg(fileObj);
@@ -93,12 +118,31 @@ const sendGroupPair = makeWritePair({
         if (!groupId || groupId === '0')
             throw imValidationError('id_invalid', 'groupId 必须非 0');
         const content = normalizeContent(args);
+        // @ 提及（仅群聊）：@具体人必须在群内（prepare 阶段逐个核实），@所有人走服务端固定 id=88
+        const atEntries = await resolveAtMentions(args, env, groupId);
+        if (atEntries.length && !content.txt) {
+            throw imValidationError('at_requires_txt', 'atAll/atUids 仅支持文本消息（txt）');
+        }
+        // 引用/回复（仅群聊文本）：prepare 阶段定位被引消息并组装 ref/rmsg
+        const quote = hasQuoteInput(args) ? await resolveQuotedRef(args, env, { groupId }) : null;
+        if (quote && !content.txt) {
+            throw imValidationError('quote_requires_txt', 'quoteMsgId/replyMsgId 仅支持文本消息（txt）');
+        }
         const summary = { action: '发送群聊消息', groupId, hasTxt: Boolean(content.txt), hasImg: Boolean(content.imgPath), hasFile: Boolean(content.filePath) };
         const snapshot = { groupId };
         if (content.txt) {
             snapshot.txt = content.txt;
             summary.textPreview = content.txt.length > 60 ? `${content.txt.slice(0, 60)}…` : content.txt;
         }
+        if (atEntries.length) {
+            snapshot.atEntries = atEntries;
+            summary.at = atEntries.map((e) => (e.t === '2' ? { target: 'ALL', name: e.nm, id: e.id } : { uid: e.id, cid: e.cid, name: e.nm }));
+        }
+        if (quote) {
+            snapshot.quoteKind = quote.kind;
+            snapshot.quoteRef = quote.ref;
+            summary.quote = { kind: quote.kind, quotedMsgId: quote.quotedMsgId, fromName: quote.fromName, textPreview: quote.text.length > 40 ? `${quote.text.slice(0, 40)}…` : quote.text };
+        }
         if (content.imgPath) {
             const abs = assertLocalFile(content.imgPath, 'img');
             snapshot.imgPath = abs;
@@ -113,8 +157,17 @@ const sendGroupPair = makeWritePair({
     },
     async execute(plan, env) {
         const body = { groupId: plan.groupId };
-        if (plan.txt !== undefined)
+        const atEntries = Array.isArray(plan.atEntries) ? plan.atEntries : [];
+        const quoteRef = plan.quoteRef ?? null;
+        if (atEntries.length || quoteRef) {
+            // @ / 引用 / 回复：完整原生 msg JSON 走 msg 字段（txt 字段无法携带 aus/ref，实测会被当纯文本展示）
+            const { v, aus } = buildAtText(String(plan.txt ?? ''), atEntries);
+            const self = await env.host.getSelfIdentity();
+            body.msg = buildAtMsgJson(v, aus, self, quoteRef ? { [plan.quoteKind === 'reply' ? 'rmsg' : 'ref']: quoteRef } : {});
+        }
+        else if (plan.txt !== undefined) {
             body.txt = plan.txt;
+        }
         if (plan.imgPath) {
             const fileObj = await env.host.uploadFile(plan.imgPath, { shareGroups: plan.groupId });
             body.img = fileObjToImg(fileObj);
@@ -516,7 +569,7 @@ const dingSendPair = makeWritePair({
         return { id: str(res?.data?.id ?? ''), msg: res?.data?.msg ?? '' };
     },
 });
-function buildMsgWriteDefinition(name, method, summary, inputProps, pair) {
+function buildMsgWriteDefinition(name, method, summary, inputProps, pair, condition = {}) {
     const requiredInput = Object.keys(inputProps).filter((k) => {
         const prop = inputProps[k];
         return prop?.required === true;
@@ -531,7 +584,7 @@ function buildMsgWriteDefinition(name, method, summary, inputProps, pair) {
             capability: 'msg',
             risk: 'read-before-write',
             requiresConfirmation: true,
-            inputSchema: schemaOf(inputProps, { required: requiredInput, description: summary }),
+            inputSchema: schemaOf(inputProps, { required: requiredInput, ...condition, description: summary }),
             handler: pair.prepare,
         },
         {
@@ -552,19 +605,27 @@ function buildMsgWriteDefinition(name, method, summary, inputProps, pair) {
     ];
 }
 const msgWriteOps = [
-    ...buildMsgWriteDefinition('im.msg.send.single', 'msg.send.single', '发送单聊消息（文本/图片/文件）', {
+    ...buildMsgWriteDefinition('im.msg.send.single', 'msg.send.single', '发送单聊消息（文本/图片/文件，文本支持引用）', {
         toUid: { type: 'string', pattern: '^\\d+$', description: '接收人 uid' },
         toCid: { type: 'string', pattern: '^\\d+$', description: '接收人 cid' },
         txt: { type: 'string', description: '文本内容' },
+        quoteMsgId: { type: 'string', pattern: '^\\d+$', description: '引用该消息（单聊仅支持引用，不支持回复；仅 txt 文本消息）；传单聊会话内消息 id（ser_msgid），prepare 阶段自动定位并组装 ref' },
         img: { type: 'string', description: '本地图片路径（发送前会上传到 E10 文件服务）' },
         file: { type: 'string', description: '本地文件路径' },
-    }, sendSinglePair),
-    ...buildMsgWriteDefinition('im.msg.send.group', 'msg.send.group', '发送群聊消息（文本/图片/文件）', {
+    }, sendSinglePair, {
+        required: ['toUid', 'toCid'],
+        requiredAny: ['txt', 'img', 'file'],
+    }),
+    ...buildMsgWriteDefinition('im.msg.send.group', 'msg.send.group', '发送群聊消息（文本/图片/文件，文本支持 @ 提及与引用/回复）', {
         groupId: { type: 'string', pattern: '^\\d+$', description: '群 id' },
-        txt: { type: 'string', description: '文本内容' },
+        txt: { type: 'string', description: '文本内容；@ 位置直接写 @<姓名>（如 @张三）或 @全体成员/@所有人' },
+        atAll: { type: 'boolean', description: '@全体成员（服务端固定 id=88），仅群聊、仅 txt 文本消息生效' },
+        atUids: { type: 'array', items: { type: 'string' }, description: '@具体人 uid 列表，仅群聊；prepare 阶段会逐个核实是否在群内，不在群内则拒绝发送' },
+        quoteMsgId: { type: 'string', pattern: '^\\d+$', description: '引用该消息（与 replyMsgId 互斥，仅群聊、仅 txt 文本消息）；传消息 id（ser_msgid），prepare 阶段自动定位被引消息并组装 ref' },
+        replyMsgId: { type: 'string', pattern: '^\\d+$', description: '回复该消息（与 quoteMsgId 互斥，仅群聊、仅 txt 文本消息）；传消息 id（ser_msgid），prepare 阶段自动定位被引消息并组装 rmsg' },
         img: { type: 'string', description: '本地图片路径' },
         file: { type: 'string', description: '本地文件路径' },
-    }, sendGroupPair),
+    }, sendGroupPair, { required: ['groupId'], requiredAny: ['txt', 'img', 'file'] }),
     ...buildMsgWriteDefinition('im.msg.withdraw', 'msg.withdraw', '撤回消息（单聊/群聊，限本人 2 分钟内）', {
         type: { type: 'string', enum: ['single', 'group'], description: 'single 或 group' },
         msgid: { type: 'string', pattern: '^\\d+$', description: '消息 id（ser_msgid）' },
@@ -588,6 +649,11 @@ const msgWriteOps = [
         toUids: { type: 'array', items: { type: 'string' }, description: '指定接收人 uid' },
         sendMsg: { type: 'integer', enum: [0, 1], description: '发短信（默认 1 发）' },
         showType: { type: 'integer', enum: [0, 1], description: '0 全体可见（默认）/1 仅发送人可见' },
-    }, dingSendPair),
+    }, dingSendPair, {
+        allOf: [
+            { anyOf: [{ required: ['groupId'] }, { required: ['toUid'] }] },
+            { anyOf: [{ required: ['txt'] }, { required: ['convertMsgid'] }] },
+        ],
+    }),
 ];
 export const msgWriteOperations = msgWriteOps;