weaver-work-cli 0.1.6 → 0.1.7

package/dist/shortcuts/im/operations/shared.js

@@ -0,0 +1,442 @@
+import { imValidationError, imBusinessError } from '../errors.js';
+/**
+ * 分页约定（与源 skill `common.js` 一致）：
+ *   - `DEFAULT_PAGE_SIZE`：每页默认 50 条；
+ *   - `MAX_PAGE_SIZE`：单次请求最多 50 条（`num` 超过会被截断）；
+ *   - `MAX_AUTO_PAGES`：有界区间自动循环翻页的页数安全上限（防止把历史一次性拉完）；
+ *   - `AUTO_PAGE_INTERVAL_MS`：自动翻页时相邻两次请求的间隔，避免高频打服务端。
+ */
+export const DEFAULT_PAGE_SIZE = 50;
+export const MAX_PAGE_SIZE = 50;
+export const MAX_AUTO_PAGES = 100;
+export const AUTO_PAGE_INTERVAL_MS = 60;
+/** 时间范围收敛上限：显式时间范围跨度超过 7 天时，收敛为该范围「最后 7 个自然日」。 */
+export const TIME_RANGE_MAX_DAYS = 7;
+const SECONDS_PER_DAY = 24 * 3600;
+/**
+ * 禁止出现在输入对象中的键：
+ * - 原型污染防护：`__proto__`/`constructor`/`prototype`
+ * - 操作人红线：`user`/`sender`/`operator`（操作者由会话 eteamsid 识别，请求体一律不传）
+ */
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype', 'user', 'sender', 'operator']);
+export function asObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw imValidationError('input_not_object', '输入必须是 JSON 对象');
+    }
+    return value;
+}
+export function assertNoForbiddenKeys(input) {
+    for (const key of Object.keys(input)) {
+        if (FORBIDDEN_KEYS.has(key)) {
+            throw imValidationError('forbidden_key', `输入包含非法字段：${key}`);
+        }
+    }
+}
+/** 校验 uid/cid 非空且非 0（易秒办红线：uid/cid 不得为 0）。 */
+export function assertNonZeroId(value, field) {
+    if (value === undefined || value === null || value === '') {
+        throw imValidationError('id_required', `${field} 必填`);
+    }
+    const text = String(value).trim();
+    if (!/^\d+$/.test(text) || text === '0') {
+        throw imValidationError('id_invalid', `${field} 必须是非 0 数字 ID`);
+    }
+    return text;
+}
+/** 拆分逗号分隔 id 列表（uint64 按字符串保留），去空。 */
+export function splitIds(value, field) {
+    if (value === undefined || value === null || value === '') {
+        throw imValidationError('id_list_required', `${field} 必填`);
+    }
+    const list = String(value).split(',').map((s) => s.trim()).filter(Boolean);
+    if (list.length === 0) {
+        throw imValidationError('id_list_empty', `${field} 不能为空`);
+    }
+    for (const item of list) {
+        if (!/^\d+$/.test(item) || item === '0') {
+            throw imValidationError('id_invalid', `${field} 含非法 id（必须非 0 数字）：${item}`);
+        }
+    }
+    return list;
+}
+/** 无符号整数转换（uint32 等），拒绝小数/负数。 */
+export function toUint(value, field) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    const numeric = Number(value);
+    if (!Number.isInteger(numeric) || numeric < 0) {
+        throw imValidationError('number_invalid', `${field} 必须是非负整数`);
+    }
+    return numeric;
+}
+/** 正整数转换。 */
+export function toPositiveInt(value, field) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    const numeric = Number(value);
+    if (!Number.isInteger(numeric) || numeric <= 0) {
+        throw imValidationError('number_invalid', `${field} 必须是正整数`);
+    }
+    return numeric;
+}
+/** 移除值为 undefined 的键。 */
+export function compact(body) {
+    for (const key of Object.keys(body)) {
+        if (body[key] === undefined)
+            delete body[key];
+    }
+    return body;
+}
+/**
+ * 旧字段别名归一化（遵循 CLI 规范）：
+ *   - 只把 `aliases` 里登记的旧字段映射到 canonical 字段；
+ *   - canonical 与旧字段同时出现且取值不一致 → 结构化校验错误（禁止任一方静默覆盖）；
+ *   - 归一化后删除旧字段，保证后续 host/请求体只看到 canonical 字段。
+ */
+export function normalizeAliases(input, aliases) {
+    const out = { ...input };
+    for (const [canonical, oldKeys] of Object.entries(aliases)) {
+        for (const oldKey of oldKeys) {
+            if (!(oldKey in out))
+                continue;
+            const oldValue = out[oldKey];
+            if (oldValue === undefined || oldValue === null || oldValue === '') {
+                delete out[oldKey];
+                continue;
+            }
+            const canonicalValue = out[canonical];
+            const hasCanonical = canonicalValue !== undefined && canonicalValue !== null && canonicalValue !== '';
+            if (hasCanonical && JSON.stringify(canonicalValue) !== JSON.stringify(oldValue)) {
+                throw imValidationError('alias_conflict', `字段 ${canonical} 与旧字段 ${oldKey} 同时出现且取值不一致，请只保留一个`);
+            }
+            if (!hasCanonical)
+                out[canonical] = oldValue;
+            delete out[oldKey];
+        }
+    }
+    return out;
+}
+/** 时间（unix 秒）→ 消息 id 最小/最大值（fwutils MakeMinAndMaxIdByTm）。返回字符串（超 JS 安全整数）。 */
+export function makeMinMaxIdByTm(tmSec) {
+    if (!tmSec || tmSec <= 0)
+        return { min: '0', max: '0' };
+    const base = BigInt(Math.floor(tmSec)) * 1000000000n;
+    return { min: base.toString(), max: (base + 999999999n).toString() };
+}
+/**
+ * 解析时间参数为 unix 秒（按本地时区）：
+ *   - 10 位纯数字：视为 unix 秒
+ *   - YYYY-MM-DD：isEnd=false → 当天 00:00:00；isEnd=true → 当天 23:59:59
+ *   - YYYY-MM-DD HH:mm[:ss]
+ */
+export function parseTimeToSec(arg, isEnd) {
+    if (arg === undefined || arg === null || arg === '')
+        return 0;
+    const s = String(arg).trim();
+    if (/^\d{10}$/.test(s))
+        return Number(s);
+    const m = s.match(/^(\d{4})-(\d{1,2})-(\d{1,2})(?:[ T](\d{1,2}):(\d{1,2})(?::(\d{1,2}))?)?$/);
+    if (!m) {
+        throw imValidationError('time_invalid', `无法解析时间参数: ${s}（支持 unix 秒 / YYYY-MM-DD / YYYY-MM-DD HH:mm:ss）`);
+    }
+    const hh = m[4] !== undefined ? Number(m[4]) : (isEnd ? 23 : 0);
+    const mm = m[5] !== undefined ? Number(m[5]) : (isEnd ? 59 : 0);
+    const ss = m[6] !== undefined ? Number(m[6]) : (isEnd ? 59 : 0);
+    return Math.floor(new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]), hh, mm, ss).getTime() / 1000);
+}
+/** 当天 00:00:00 / 23:59:59 的 unix 秒（本地时区）。 */
+export function todayRange() {
+    const now = new Date();
+    const start = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 0, 0, 0);
+    const end = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 23, 59, 59);
+    return { fromSec: Math.floor(start.getTime() / 1000), toSec: Math.floor(end.getTime() / 1000) };
+}
+/**
+ * 时间范围收敛（强制约定，与源 skill `clampTimeRangeTo7Days` 一致）：
+ * 显式时间范围跨度 > 7 天时，**自动缩短为该范围最后 7 个自然日**（起点对齐到终点所在日 00:00:00 往前 6 天）。
+ *   - 「拉一年的消息」→ 最近 7 天；「拉上个月的消息」→ 上个月最后 7 天；
+ *   - 跨度 ≤ 7 天原样返回；
+ *   - 只给起点 → 终点按「现在」计算；只给终点 → 起点按「终点前 7 天」计算。
+ */
+export function clampTimeRangeTo7Days(fromSec, toSec) {
+    let f = Number(fromSec) > 0 ? Number(fromSec) : 0;
+    let t = Number(toSec) > 0 ? Number(toSec) : 0;
+    if (f <= 0 && t <= 0) {
+        return { fromSec: f, toSec: t, shrunk: false, origFromSec: f, origToSec: t };
+    }
+    const nowSec = Math.floor(Date.now() / 1000);
+    if (t <= 0)
+        t = nowSec;
+    if (f <= 0)
+        f = t - TIME_RANGE_MAX_DAYS * SECONDS_PER_DAY;
+    const maxSpan = TIME_RANGE_MAX_DAYS * SECONDS_PER_DAY;
+    if (t - f > maxSpan) {
+        const d = new Date(t * 1000);
+        const start = new Date(d.getFullYear(), d.getMonth(), d.getDate() - (TIME_RANGE_MAX_DAYS - 1), 0, 0, 0);
+        return {
+            fromSec: Math.floor(start.getTime() / 1000),
+            toSec: t,
+            shrunk: true,
+            origFromSec: f,
+            origToSec: t,
+        };
+    }
+    return { fromSec: f, toSec: t, shrunk: false, origFromSec: f, origToSec: t };
+}
+/** unix 秒 → `YYYY-MM-DD HH:mm:ss`（本地时区，用于口径与收敛提示）。 */
+export function formatSec(sec) {
+    const pad = (n) => String(n).padStart(2, '0');
+    const d = new Date(Number(sec) * 1000);
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+/** 时间范围收敛提示文案（Agent 展示结果时必须原样转述给用户）。 */
+export function timeRangeShrinkNotice(clamp) {
+    return `⚠️ 指定时间范围超过 ${TIME_RANGE_MAX_DAYS} 天，已自动缩短为该范围最后 ${TIME_RANGE_MAX_DAYS} 天：`
+        + `${formatSec(clamp.origFromSec)} ~ ${formatSec(clamp.origToSec)}`
+        + `  →  ${formatSec(clamp.fromSec)} ~ ${formatSec(clamp.toSec)}`
+        + `（如需更早历史，请分段指定 ≤ ${TIME_RANGE_MAX_DAYS} 天的时间范围）`;
+}
+/** 时间展示统一格式：YYYY/M/D HH:MM:SS（unix 秒输入）。 */
+export function formatFullTime(ts) {
+    if (ts === undefined || ts === null || ts === '')
+        return '-';
+    const d = new Date(Number(ts) * 1000);
+    if (Number.isNaN(d.getTime()))
+        return '-';
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}/${d.getMonth() + 1}/${d.getDate()} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+/** 校验枚举取值。 */
+export function assertEnum(value, allowed, field) {
+    const text = typeof value === 'string' ? value : String(value);
+    if (!allowed.includes(text)) {
+        throw imValidationError('enum_invalid', `${field} 取值必须是 ${allowed.join(' / ')} 之一`);
+    }
+    return text;
+}
+/** 从 IM 响应 JSON 中提取 actionMsg（路径多样兼容）。 */
+export function findActionMsg(value) {
+    const candidate = value?.data?.actionMsg ?? value?.actionMsg;
+    if (candidate === undefined || candidate === null)
+        return null;
+    return {
+        code: candidate.code !== undefined ? candidate.code : 0,
+        message: candidate.message ?? candidate.msg ?? '',
+    };
+}
+/** 判断 IM 业务是否成功（actionMsg.code === 0）。失败抛 business_error。 */
+export function assertImOk(value, actionLabel) {
+    const msg = findActionMsg(value);
+    if (msg === null) {
+        // 无 actionMsg 时回退顶层 code===200 && status 判定（sendDing 等路径）
+        if (Number(value?.code) === 200 && value?.status)
+            return;
+        throw imBusinessError('business_error', `${actionLabel}失败：缺少 actionMsg`, {
+            details: { raw: value },
+        });
+    }
+    if (Number(msg.code) === 0)
+        return;
+    const message = msg.message || `${actionLabel}失败（actionMsg.code=${msg.code}）`;
+    throw imBusinessError('action_failed', message, { code: msg.code });
+}
+/** 取出响应 data 主体（兼容 data.data.data / data.data 等路径）。 */
+export function unwrapInner(value) {
+    return value?.data?.data ?? value?.data;
+}
+/** 群成员条目判定（成员行至少含 uid 或 user 身份）。 */
+function isMemberRow(value) {
+    return Boolean(value) && typeof value === 'object' && (value.uid !== undefined || value.user !== undefined);
+}
+/**
+ * 从 getGroupUsers 响应主体提取成员数组。
+ * 兼容服务端历史形态：`users` / `members` / `datas`（含 `datas[].datas` 嵌套），
+ * 避免因响应包裹层不同导致「群内没有可接收成员」这类误判。
+ */
+export function extractGroupMembers(inner) {
+    if (!inner || typeof inner !== 'object')
+        return [];
+    for (const key of ['users', 'members']) {
+        const list = inner[key];
+        if (Array.isArray(list) && list.some(isMemberRow))
+            return list;
+    }
+    const datas = Array.isArray(inner.datas) ? inner.datas : [];
+    if (datas.some(isMemberRow))
+        return datas;
+    const nested = [];
+    for (const group of datas) {
+        if (Array.isArray(group?.datas))
+            nested.push(...group.datas);
+    }
+    return nested;
+}
+/**
+ * 当前登录用户 uid（易秒办 IM uid = E10 登录 userId）。
+ * 仅用于展示层识别「我」，请求体依旧不携带任何操作人字段。
+ */
+export async function resolveAuthUid(host) {
+    try {
+        const session = await host.getSession();
+        return str(session?.userId);
+    }
+    catch {
+        return '';
+    }
+}
+/** 消息页最小 ser_msgid（`hasMore` 时作为下一页 `start` 锚点；服务端返回含边界那条，需按 msgid 去重）。 */
+export function minMsgId(messages) {
+    let min = null;
+    for (const message of messages) {
+        const id = str(message?.msgid);
+        if (!/^\d+$/.test(id))
+            continue;
+        if (min === null || BigInt(id) < BigInt(min))
+            min = id;
+    }
+    return min ?? '';
+}
+/**
+ * 倒序分页拉取（与源 skill `common.js pagedPull` 一致）：
+ *   - `autoLoop=true`（有界区间 `end != 0`）→ 自动循环翻页直到区间内拉完再返回，受 MAX_AUTO_PAGES 页数上限保护；
+ *   - `autoLoop=false`（无界区间 `end = 0`，如 `latest:true`）→ 只拉一页，未拉完时 `hasMore=true`。
+ * 翻页约定：下一页 `start` = 本页最小消息 id；服务端返回「id ≤ start」且包含边界那条，因此按消息 id 去重。
+ */
+export async function pullPaged(options) {
+    const maxNum = Math.min(options.num > 0 ? options.num : DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE);
+    const idOf = options.idOf ?? ((row) => str(row?.ser_msgid));
+    const endBig = /^\d+$/.test(String(options.end ?? '')) ? BigInt(String(options.end)) : 0n;
+    const rows = [];
+    const seen = new Set();
+    let curStart = options.start;
+    let pages = 0;
+    let lastStart = '';
+    let exhausted = false;
+    let hasMore = false;
+    let cappedAtMaxPages = false;
+    for (;;) {
+        const page = await options.requestOnePage(curStart, options.end, maxNum);
+        pages += 1;
+        if (!page || page.length === 0) {
+            exhausted = true;
+            break;
+        }
+        let added = 0;
+        let minId = '';
+        for (const row of page) {
+            const id = idOf(row);
+            if (!/^\d+$/.test(id) || seen.has(id))
+                continue;
+            seen.add(id);
+            rows.push(row);
+            added += 1;
+            if (minId === '' || BigInt(id) < BigInt(minId))
+                minId = id;
+        }
+        if (added === 0 || minId === '') {
+            exhausted = true;
+            break;
+        }
+        lastStart = minId;
+        curStart = minId;
+        if (endBig > 0n && BigInt(curStart) <= endBig) {
+            exhausted = true;
+            break;
+        }
+        if (!options.autoLoop) {
+            // 单页模式：本页拉满即保守认为还有更旧消息（未拉满说明区间内已无更多）
+            if (page.length >= maxNum)
+                hasMore = endBig > 0n ? BigInt(curStart) > endBig : true;
+            break;
+        }
+        if (pages >= MAX_AUTO_PAGES) {
+            hasMore = true;
+            cappedAtMaxPages = true;
+            break;
+        }
+        if (AUTO_PAGE_INTERVAL_MS > 0) {
+            await new Promise((resolve) => setTimeout(resolve, AUTO_PAGE_INTERVAL_MS));
+        }
+    }
+    return { rows, pages, lastStart, exhausted, hasMore, autoPaged: options.autoLoop, cappedAtMaxPages };
+}
+/**
+ * 分页对外摘要：自动/单页口径、页数、下一页锚点与去重/继续提示。
+ * `hasMore=true` 时把 `nextStart` 作为下一次调用的 `start`（保持同一 `end`/时间范围）。
+ */
+export function paginationMeta(result, num) {
+    return {
+        pageSize: num,
+        pages: result.pages,
+        autoPaged: result.autoPaged,
+        maxAutoPages: MAX_AUTO_PAGES,
+        exhausted: result.exhausted,
+        hasMore: result.hasMore,
+        ...(result.hasMore && result.lastStart
+            ? {
+                nextStart: result.lastStart,
+                resumeHint: '需要更早数据时，用相同范围再次调用并传 start=nextStart（服务端会重复返回边界那条，已按消息 id 去重）',
+            }
+            : {}),
+        ...(result.cappedAtMaxPages
+            ? {
+                cappedAtMaxPages: true,
+                cappedNote: `已达单次自动翻页上限 ${MAX_AUTO_PAGES} 页，区间内仍有更旧数据，用 nextStart 继续`,
+            }
+            : {}),
+    };
+}
+/** 时间范围收敛的对外摘要（Agent 必须把 notice 原样转述给用户）。 */
+export function rangeShrinkMeta(clamp) {
+    return {
+        shrunk: true,
+        maxDays: TIME_RANGE_MAX_DAYS,
+        originalFrom: formatSec(clamp.origFromSec),
+        originalTo: formatSec(clamp.origToSec),
+        from: formatSec(clamp.fromSec),
+        to: formatSec(clamp.toSec),
+        notice: timeRangeShrinkNotice(clamp),
+    };
+}
+/** 消息按消息 id 从新到旧排序（与源 skill 展示口径一致：最新在前）。 */
+export function sortMessagesNewestFirst(messages) {
+    return messages.sort((a, b) => {
+        const ai = str(a.msgid);
+        const bi = str(b.msgid);
+        const aOk = /^\d+$/.test(ai);
+        const bOk = /^\d+$/.test(bi);
+        if (!aOk && !bOk)
+            return 0;
+        if (!aOk)
+            return 1;
+        if (!bOk)
+            return -1;
+        return BigInt(bi) === BigInt(ai) ? 0 : (BigInt(bi) > BigInt(ai) ? 1 : -1);
+    });
+}
+/** 枚举值转成 string（可能为字符串数字）。 */
+export function str(value) {
+    if (value === undefined || value === null)
+        return '';
+    return String(value);
+}
+/** 解析消息 JSON 字符串或对象。 */
+export function parseMsg(value) {
+    if (!value)
+        return null;
+    if (typeof value === 'string') {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (typeof value === 'object')
+        return value;
+    return null;
+}
+/**
+ * 媒体文件上传所需文件大小上限（消息图片/文件常规场景按服务端约束执行）。
+ */
+export const MAX_UPLOAD_BYTES = 1024 * 1024 * 200;

package/dist/shortcuts/{yimiaoban → im}/operations/types.js

@@ -1,6 +1,6 @@
 export const READ = 'read';
 export const WRITE = 'write';
-export function ymbSuccess(action, data, meta) {
+export function imSuccess(action, data, meta) {
     const payload = { ok: true, action, data };
     if (meta && Object.keys(meta).length > 0)
         payload.meta = meta;

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

@@ -0,0 +1,201 @@
+import { imValidationError } from '../errors.js';
+import { schemaOf, WRITE, } from './types.js';
+import { assertImOk, str, toUint, unwrapInner } from './shared.js';
+import { makeWritePair } from './write-util.js';
+/**
+ * 消息免打扰设置（`POST /api/em/msg/executeIm/user/setMsgRemind`）。
+ *
+ * 服务端契约（weaver-im-api `PathSetMsgRemind` + `MsgRemindInfo`）：
+ *   { "user": {cid,uid}, "data": { trans_id, dev, remind: MsgRemindInfo } }
+ *
+ * 本 operation 按会话维度设置提醒状态：
+ *   1 单聊会话 → `user`（对方 cid/uid）
+ *   2 群聊会话 → `group_id`
+ *   4 系统会话 → `group`（系统消息分组 id）
+ * `reminder`：0=消息接收提醒；1=消息接收但不提醒（免打扰）。
+ */
+const SESSION_TYPE_NAME = {
+    1: '单聊会话',
+    2: '群聊会话',
+    4: '系统会话',
+};
+const REMINDER_NAME = {
+    0: '消息接收提醒',
+    1: '消息接收但不提醒（免打扰）',
+};
+const USER_SESSION_TYPES = new Set([1]);
+const GROUP_ID_SESSION_TYPES = new Set([2]);
+/** 只读回查目标名称（失败不影响签发，仅用于摘要可读性）。 */
+async function resolveTargetLabel(plan, env) {
+    try {
+        if (GROUP_ID_SESSION_TYPES.has(plan.sessionType) && plan.groupId) {
+            const res = await env.host.request({
+                method: 'POST',
+                path: '/api/em/msg/executeIm/group/queryGroupInfo',
+                body: { trans_id: 0, type: 0, mask: 0, group_id: [plan.groupId], flag: 0 },
+                operation: 'im.user.setRemind.plan.group',
+            });
+            const info = (unwrapInner(res)?.datas || [])[0];
+            const name = str(info?.name);
+            return name ? `群「${name}」(${plan.groupId})` : `群 ${plan.groupId}`;
+        }
+        if (USER_SESSION_TYPES.has(plan.sessionType) && plan.user) {
+            const map = await env.host.resolveUsersByIds([plan.user.uid]);
+            const name = map[plan.user.uid]?.name;
+            return name ? `与「${name}」的会话(${plan.user.uid})` : `与 ${plan.user.uid} 的会话`;
+        }
+        if (plan.sessionType === 4 && plan.group !== undefined) {
+            const res = await env.host.request({
+                method: 'POST',
+                path: '/api/em/msg/executeIm/system-msg/syncGroupType',
+                body: { gids: [plan.group], tids: [], lang: 'zh_CN', showdel: 1 },
+                operation: 'im.user.setRemind.plan.sysgroup',
+            });
+            const groupName = str((unwrapInner(res)?.groups || [])[0]?.groupName);
+            const base = groupName ? `系统消息分组「${groupName}」(${plan.group})` : `系统消息分组 ${plan.group}`;
+            return base;
+        }
+    }
+    catch {
+        // 回查失败：仅用 id 描述目标
+    }
+    if (plan.groupId)
+        return `群 ${plan.groupId}`;
+    if (plan.user)
+        return `与 ${plan.user.uid} 的会话`;
+    if (plan.group !== undefined)
+        return `系统消息分组 ${plan.group}`;
+    return '会话免打扰设置';
+}
+const userSetRemindPair = makeWritePair({
+    action: 'im.user.setRemind',
+    async plan(args, env) {
+        const sessionType = toUint(args.sessionType, 'sessionType');
+        if (sessionType === undefined || SESSION_TYPE_NAME[sessionType] === undefined) {
+            throw imValidationError('session_type_invalid', 'sessionType 必填且仅支持会话维度：1 单聊会话、2 群聊会话、4 系统会话');
+        }
+        const reminder = toUint(args.reminder, 'reminder');
+        if (reminder === undefined || REMINDER_NAME[reminder] === undefined) {
+            throw imValidationError('reminder_invalid', 'reminder 必填且仅支持 0 消息接收提醒 / 1 消息接收但不提醒（免打扰）');
+        }
+        const plan = { sessionType, reminder };
+        if (USER_SESSION_TYPES.has(sessionType)) {
+            const uid = str(args.toUid);
+            const cid = str(args.toCid);
+            if (!uid || !cid || uid === '0' || cid === '0') {
+                throw imValidationError('target_required', `sessionType=${sessionType}（${SESSION_TYPE_NAME[sessionType]}）需要 toUid + toCid`);
+            }
+            plan.user = { cid, uid };
+        }
+        else if (GROUP_ID_SESSION_TYPES.has(sessionType)) {
+            const groupId = str(args.groupId);
+            if (!groupId || groupId === '0') {
+                throw imValidationError('target_required', `sessionType=${sessionType}（${SESSION_TYPE_NAME[sessionType]}）需要 groupId`);
+            }
+            plan.groupId = groupId;
+        }
+        else {
+            const group = toUint(args.group, 'group');
+            if (group === undefined || group <= 0) {
+                throw imValidationError('target_required', 'sessionType=4（系统会话）需要 group（系统消息分组 id）');
+            }
+            plan.group = group;
+        }
+        const target = await resolveTargetLabel(plan, env);
+        return {
+            summary: {
+                action: '设置消息免打扰',
+                target,
+                sessionType: plan.sessionType,
+                sessionTypeName: SESSION_TYPE_NAME[plan.sessionType],
+                reminder: plan.reminder,
+                reminderName: REMINDER_NAME[plan.reminder],
+                ...(plan.groupId ? { groupId: plan.groupId } : {}),
+                ...(plan.user ? { toUid: plan.user.uid, toCid: plan.user.cid } : {}),
+                ...(plan.group !== undefined ? { group: plan.group } : {}),
+                note: '仅修改当前登录人自己的会话提醒设置；reminder=0 接收并提醒，1 接收但不提醒（免打扰）。',
+            },
+            snapshot: plan,
+        };
+    },
+    async execute(plan, env) {
+        // 该接口在请求体里携带「修改者」，只能由 CLI 用当前登录人身份填充，调用方不可指定。
+        const self = await env.host.getSelfIdentity();
+        const remind = {
+            session_type: plan.sessionType,
+            reminder: plan.reminder,
+        };
+        if (plan.user)
+            remind.user = { cid: plan.user.cid, uid: plan.user.uid };
+        if (plan.groupId)
+            remind.group_id = plan.groupId;
+        if (plan.group !== undefined)
+            remind.group = plan.group;
+        const res = await env.host.request({
+            method: 'POST',
+            path: '/api/em/msg/executeIm/user/setMsgRemind',
+            body: {
+                user: { cid: self.cid, uid: self.uid },
+                data: { trans_id: 0, dev: 4, remind },
+            },
+            operation: 'im.user.setRemind',
+        });
+        assertImOk(res, '设置消息免打扰');
+        return {
+            sessionType: plan.sessionType,
+            sessionTypeName: SESSION_TYPE_NAME[plan.sessionType],
+            reminder: plan.reminder,
+            reminderName: REMINDER_NAME[plan.reminder],
+            ...(plan.groupId ? { groupId: plan.groupId } : {}),
+            ...(plan.user ? { toUid: plan.user.uid } : {}),
+            ...(plan.group !== undefined ? { group: plan.group } : {}),
+        };
+    },
+});
+const prepareSchema = {
+    ...schemaOf({
+        sessionType: {
+            type: 'integer',
+            enum: [1, 2, 4],
+            description: '会话类型（必填，仅会话维度）：1 单聊会话，2 群聊会话，4 系统会话',
+        },
+        reminder: {
+            type: 'integer',
+            enum: [0, 1],
+            description: '提醒值（必填）：0 消息接收提醒，1 消息接收但不提醒（免打扰）',
+        },
+        toUid: { type: 'string', pattern: '^\\d+$', description: 'sessionType=1（单聊会话）时的对方 uid' },
+        toCid: { type: 'string', pattern: '^\\d+$', description: 'sessionType=1（单聊会话）时的对方 cid' },
+        groupId: { type: 'string', pattern: '^\\d+$', description: 'sessionType=2（群聊会话）时的群 id' },
+        group: { type: 'integer', minimum: 1, description: 'sessionType=4（系统会话）时的系统消息分组 id' },
+    }, { required: ['sessionType', 'reminder'], description: '会话免打扰设置（单聊会话 / 群聊会话 / 系统会话）' }),
+};
+export const userRemindOperations = [
+    {
+        name: 'im.user.setRemind.prepare',
+        resource: 'user',
+        method: 'user.setRemind.prepare',
+        action: 'im.user.setRemind.prepare',
+        summary: '设置消息免打扰（prepare：校验目标 + 只读回查目标名称 + 签发确认）',
+        capability: 'user',
+        risk: 'read-before-write',
+        requiresConfirmation: true,
+        inputSchema: prepareSchema,
+        handler: userSetRemindPair.prepare,
+    },
+    {
+        name: 'im.user.setRemind.apply',
+        resource: 'user',
+        method: 'user.setRemind.apply',
+        action: 'im.user.setRemind.apply',
+        summary: '设置消息免打扰（apply：需 confirm:true + continuation）',
+        capability: 'user',
+        risk: WRITE,
+        requiresConfirmation: true,
+        inputSchema: schemaOf({
+            confirm: { type: 'boolean', description: '必须为 true' },
+            continuation: { type: 'string', minLength: 1 },
+        }, { required: ['confirm', 'continuation'], description: '设置消息免打扰（apply）' }),
+        handler: userSetRemindPair.apply,
+    },
+];