botmux 2.9.1 → 2.9.3

package/dist/setup/verify-permissions.js

@@ -0,0 +1,207 @@
+/**
+ * 凭证 + 权限自检. 不阻塞 setup / daemon 启动, 任意失败都降级到"打印剩余步骤".
+ *
+ * 主路径只用:
+ * - {@link validateCredentials} —— 取一次 `tenant_access_token`, 通过才认为
+ *   AppID/Secret 有效. 没拿到才会让 setup 失败 (拒绝写 bots.json).
+ *
+ * 仅作为可选 helper, **未启用于 setup / start 主链路**:
+ * - {@link checkRequiredScopes} —— 调 `application.v6.scope.list` 比对 botmux
+ *   需要的 scope. 待 spike 用真实/可复现 mock 证明 grant_status 闭环后再启用.
+ * - {@link applyScopesUnverified} —— 调 `application.v6.scope.apply` 触发管理
+ *   员审批. Lark 文档表明它只能提交"已声明但未授权"的 scope, 不能给 manifest
+ *   加新 scope, 所以无法绕开"用户去开放平台勾"这步; 同样待 spike 后启用.
+ *
+ * 安全约束:
+ * - Secret 永远不进 console / 日志 / 错误链
+ * - 网络/接口错误一律返回结构化结果, 不抛
+ */
+import * as Lark from '@larksuiteoapi/node-sdk';
+/**
+ * botmux 运行所需的 scope. 这里**只用于检测/提示**, 不用于自动申请——飞书
+ * `scope.apply` 只能提交"已声明但未授权"的, 没法给应用 manifest 加新声明.
+ * scope 选择必须用户去开放平台勾.
+ */
+export const BOTMUX_REQUIRED_SCOPES = [
+    { name: 'im:message', desc: '收发消息', critical: true },
+    { name: 'im:message.group_at_msg', desc: '群消息接收', critical: true },
+    { name: 'im:resource', desc: '消息附件下载', critical: true },
+    { name: 'im:chat', desc: '群信息读取', critical: true },
+    { name: 'contact:user.base:readonly', desc: '用户基本信息', critical: true },
+    { name: 'im:message.group_at_msg.include_bot:readonly', desc: '跨 bot @ 事件', critical: false },
+    { name: 'application:application:self_manage', desc: '应用自查 (免审批)', critical: false },
+];
+export function buildScopeDeepLink(appId, scopeName, brand = 'feishu') {
+    const host = brand === 'lark' ? 'open.larksuite.com' : 'open.feishu.cn';
+    return `https://${host}/app/${appId}/auth?q=${encodeURIComponent(scopeName)}&op_from=openapi&token_type=tenant`;
+}
+export function buildEventSubDeepLink(appId, brand = 'feishu') {
+    const host = brand === 'lark' ? 'open.larksuite.com' : 'open.feishu.cn';
+    return `https://${host}/app/${appId}/dev-config/event-sub`;
+}
+export function buildAppHomeDeepLink(appId, brand = 'feishu') {
+    const host = brand === 'lark' ? 'open.larksuite.com' : 'open.feishu.cn';
+    return `https://${host}/app/${appId}`;
+}
+/**
+ * 用 AppID/Secret 取一次 tenant_access_token, 验证凭证可用.
+ *
+ * Secret 不进 error.message: 错误信息只来自飞书返回的 msg 字段或 axios 错误类型.
+ *
+ * Codex review #3: 加 AbortController + 总超时. 网络半挂时 `botmux setup` /
+ * `botmux start` 不能无限卡住; 超时归类为 network, 这样 setup 走"凭证校验失败
+ * 不写盘" 路径, start 走"network 只 WARN 继续"路径.
+ */
+export async function validateCredentials(appId, appSecret, brand = 'feishu', opts = {}) {
+    const budgetMs = opts.budgetMs ?? 10_000;
+    const host = brand === 'lark' ? 'open.larksuite.com' : 'open.feishu.cn';
+    const url = `https://${host}/open-apis/auth/v3/tenant_access_token/internal`;
+    // 自家 AbortController 控制总超时; 同时把上层传进来的 signal 也接上.
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), budgetMs);
+    if (opts.signal) {
+        if (opts.signal.aborted)
+            ac.abort();
+        else
+            opts.signal.addEventListener('abort', () => ac.abort(), { once: true });
+    }
+    // Codex review v2 follow-up: timer 必须覆盖 res.json() 阶段, 否则飞书极端半挂
+    // (body 半 chunk 后服务端不再发) 仍会卡住. clearTimeout 推迟到 JSON 解析之后.
+    let res;
+    let body;
+    try {
+        res = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            // 注意: 这是飞书唯一接受 appSecret 的端点; 其它端点全部用 token. 不要把
+            // secret 拼到 query string 或日志里.
+            body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+            signal: ac.signal,
+        });
+        body = await res.json();
+    }
+    catch (err) {
+        clearTimeout(timer);
+        // AbortError (fetch / json() 内部 / 我们自己 timeout) 全部归到 network
+        const isAbort = err?.name === 'AbortError' || ac.signal.aborted;
+        // JSON 解析错 (非 abort) 归 unknown, 保留旧行为
+        if (!isAbort && err instanceof SyntaxError) {
+            return { ok: false, error: 'unknown', message: `HTTP ${res?.status ?? '?'} 响应非 JSON` };
+        }
+        return {
+            ok: false,
+            error: 'network',
+            message: isAbort
+                ? `请求超时 (> ${budgetMs}ms)`
+                : `网络错误: ${err?.code ?? err?.message ?? 'unknown'}`,
+        };
+    }
+    clearTimeout(timer);
+    if (body?.code === 0 && typeof body.tenant_access_token === 'string') {
+        return { ok: true, tenantAccessToken: body.tenant_access_token, tokenExpiresIn: body.expire ?? 7200 };
+    }
+    // 飞书常见错误码:
+    // 10003 / 10012: app_id or app_secret invalid
+    // 10014: 应用未发布
+    // 99991663: app_secret invalid
+    if (body?.code === 10003 || body?.code === 10012 || body?.code === 99991663) {
+        return { ok: false, error: 'invalid_credentials', message: `凭证无效 (code=${body.code}): ${body.msg ?? ''}` };
+    }
+    return { ok: false, error: 'unknown', message: `code=${body?.code ?? '?'} msg=${body?.msg ?? ''}` };
+}
+/**
+ * 列出应用的 scope grant 状态, 比对 BOTMUX_REQUIRED_SCOPES.
+ *
+ * **不在主路径使用** — 待 spike 用真实/可复现 mock 证明 grant_status 含义和
+ * 状态闭环后再启用. 当前主路径只输出"剩余步骤 + 深链", 不做 grant_status 判定.
+ *
+ * scope.list 返回 shape (SDK type):
+ *   `{ data: { scopes: [{ scope_name, grant_status, scope_type }] } }`
+ * grant_status 含义未在官方文档明确, 但社区 SDK / 实测一般约定:
+ *   1 = 已申请未生效, 2 = 已生效. 启用前 spike 务必确认这个映射.
+ */
+export async function checkRequiredScopes(appId, appSecret, brand = 'feishu') {
+    const domain = brand === 'lark' ? Lark.Domain.Lark : Lark.Domain.Feishu;
+    const client = new Lark.Client({ appId, appSecret, domain, loggerLevel: Lark.LoggerLevel.error });
+    let resp;
+    try {
+        resp = await client.application.scope.list();
+    }
+    catch (err) {
+        return { ok: false, error: 'network', message: `scope.list 调用失败: ${err?.code ?? err?.message ?? 'unknown'}` };
+    }
+    // SDK 失败时不抛, 返回 { code, msg }
+    if (resp?.code === 99991672) {
+        return {
+            ok: false,
+            error: 'need_self_manage',
+            message: '应用缺少 application:application:self_manage 权限, 无法自查 scope 列表',
+        };
+    }
+    if (resp?.code !== 0) {
+        return { ok: false, error: 'unknown', message: `code=${resp?.code ?? '?'} msg=${resp?.msg ?? ''}` };
+    }
+    const scopes = resp?.data?.scopes ?? [];
+    // grant_status === 2 → granted (待 spike 确认这是正确映射)
+    const grantedNames = scopes
+        .filter((s) => s?.grant_status === 2 && typeof s?.scope_name === 'string')
+        .map((s) => s.scope_name);
+    const missingCritical = BOTMUX_REQUIRED_SCOPES.filter(s => s.critical && !grantedNames.includes(s.name));
+    const missingOptional = BOTMUX_REQUIRED_SCOPES.filter(s => !s.critical && !grantedNames.includes(s.name));
+    return { ok: true, granted: grantedNames, missingCritical, missingOptional };
+}
+export async function applyScopesUnverified(appId, appSecret, opts = {}) {
+    const brand = opts.brand ?? 'feishu';
+    const budgetMs = opts.budgetMs ?? 15_000;
+    const domain = brand === 'lark' ? Lark.Domain.Lark : Lark.Domain.Feishu;
+    const client = new Lark.Client({ appId, appSecret, domain, loggerLevel: Lark.LoggerLevel.error });
+    const timeout = new Promise((resolve) => {
+        const timer = setTimeout(() => resolve({ status: 'timeout', msg: `> ${budgetMs}ms` }), budgetMs);
+        opts.signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            resolve({ status: 'timeout', msg: 'aborted' });
+        }, { once: true });
+    });
+    const call = (async () => {
+        try {
+            const resp = await client.application.scope.apply();
+            const code = resp?.code;
+            const msg = resp?.msg;
+            if (code === 0)
+                return { status: 'submitted', code, msg };
+            if (code === 212001)
+                return { status: 'super_scope_only', code, msg };
+            if (code === 212002)
+                return { status: 'nothing_to_apply', code, msg };
+            if (code === 212003)
+                return { status: 'over_limit', code, msg };
+            if (code === 212004)
+                return { status: 'already_applied', code, msg };
+            return { status: 'error', code, msg };
+        }
+        catch (err) {
+            return { status: 'error', msg: err?.code ?? err?.message ?? 'unknown' };
+        }
+    })();
+    return Promise.race([call, timeout]);
+}
+// ─── Remaining-steps printer ──────────────────────────────────────────────
+/**
+ * setup 后 "还要手动点的步骤" 结构化数据. 跟 cli.ts 的 printRemainingSteps + README
+ * "5 分钟快速接入" 一致: 主线就两步 (权限申请 + 按需重定向 URL); PersonalAgent
+ * 应用默认订阅事件 + bot 能力, 不在主线提示, 收不到消息时见 README 的 fallback
+ * 自查清单.
+ */
+export function buildRemainingSteps(appId, brand = 'feishu') {
+    return [
+        {
+            title: '申请权限 (一次性导入完整 JSON 提交审批) — 进入「权限管理」→「批量导入/导出权限」, 粘贴 ~/.botmux/lark-scopes.json',
+            url: `${buildAppHomeDeepLink(appId, brand)}/auth`,
+        },
+        {
+            title: '添加重定向 URL http://127.0.0.1:9768/callback (按需, 用于 botmux 内 /login 跨用户调 API)',
+            url: `${buildAppHomeDeepLink(appId, brand)}/safe`,
+        },
+    ];
+}
+//# sourceMappingURL=verify-permissions.js.map

package/dist/setup/verify-permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-permissions.js","sourceRoot":"","sources":["../../src/setup/verify-permissions.ts"],"names":[],"mappings":"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"}

package/dist/skills/definitions.d.ts

@@ -14,4 +14,8 @@ export interface SkillDef {
     content: string;
 }
 export declare const BUILTIN_SKILLS: SkillDef[];
+/** Skills that earlier botmux versions installed but no longer ship. The
+ *  installer cleans these up so renamed skills don't linger as duplicates
+ *  in the CLI's skills directory. */
+export declare const RETIRED_SKILL_NAMES: string[];
 //# sourceMappingURL=definitions.d.ts.map

package/dist/skills/definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/skills/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,QAAQ;IACvB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;CACjB;AA2QD,eAAO,MAAM,cAAc,EAAE,QAAQ,EAKpC,CAAC"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/skills/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,QAAQ;IACvB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;CACjB;AAuXD,eAAO,MAAM,cAAc,EAAE,QAAQ,EAMpC,CAAC;AAEF;;qCAEqC;AACrC,eAAO,MAAM,mBAAmB,EAAE,MAAM,EAEvC,CAAC"}

package/dist/skills/definitions.js

@@ -9,7 +9,7 @@
  */
 const SCHEDULE_SKILL = `---
 name: botmux-schedule
-description: 当用户要求创建定时任务/提醒（"每天X点提醒"、"30分钟后"、"每周一"、"remind me"、"schedule"）时触发。使用 botmux schedule 命令操作定时任务（增删查改），支持 Lark 话题内自动路由。
+description: 在当前飞书/Lark 话题里创建、管理定时提醒（用 botmux schedule 命令，支持增删查改暂停恢复）。触发场景：用户说"每天X点"、"每周X"（任意星期，不限周一）、"每月X号"、"N分钟后/N小时后"、"明天X点"、"提醒我"、"定时任务"、"周期任务"、"recurring"、"reminder"、"crontab" 时；或显式提到 botmux schedule。到点后 daemon 会在原话题自动续一条消息并触发新 CLI 会话。注意区分：本 skill 是飞书话题内提醒；要在云端跑 remote agent 用 superpowers:schedule；要在当前会话循环跑 prompt 用 loop。
 ---
 
 # botmux-schedule — 定时任务
@@ -82,27 +82,43 @@ botmux schedule add "30m" "检查部署状态（调用 kubectl get pods 看看
 - botmux daemon 每 30 秒 tick 一次，到点会在**原话题**里自动续一条消息并把 prompt 喂给一个新的 CLI 会话
 - 工作目录与创建任务时一致
 - 如果原话题的会话还活着，prompt 会直接注入现有会话（不会开新会话）
+
+## 跨群发布场景（changelog 群、动态频道等）
+
+如果定时任务的目的是"把内容发到另一个群作为顶层消息"（而不是回复到当前话题），让 prompt 内部用 \`botmux send --top-level --chat-id <目标群>\` 即可。任务本身仍然创建在当前话题里——这样：
+
+- "🕐 task 开始执行" + 流式卡片留在你当前话题，方便监控
+- 实际内容作为顶层消息发到目标群，不绑定话题、不 @ 你
+
+\`\`\`bash
+botmux schedule add "每日11:00" "
+1. <做事>
+2. botmux send --top-level --chat-id oc_xxxxxxxxxxxx '推送内容...'
+"
+\`\`\`
+
+详见 \`botmux-send\` 技能的"顶层广播 / 跨群发布"章节。
 `;
-const THREAD_MESSAGES_SKILL = `---
-name: botmux-thread-messages
-description: 需要查看当前 Lark 话题的历史消息时触发。适合"看看这个话题之前聊了什么"、"最近的消息"、"上下文"类请求。在 CLI 会话内自动推断 session-id。
+const HISTORY_SKILL = `---
+name: botmux-history
+description: 需要查看当前飞书会话历史消息时触发。话题群拉话题内消息，普通群拉整群最近 N 条（默认 50，用 --limit 调节，最多 50/页）。适合"看看之前聊了什么"、"最近的消息"、"上下文"类请求。在 CLI 会话内自动推断 session-id。
 ---
 
-# botmux-thread-messages — 读取话题消息历史
+# botmux-history — 读取会话消息历史
 
-想回顾当前 Lark 话题里用户之前发过什么、别的机器人说了什么时使用。
+想回顾当前飞书会话里用户之前发过什么、别的机器人说了什么时使用。**话题群和普通群都支持**：话题群里只返回当前话题内的消息，普通群里返回整群最近 N 条（默认 50，按时间倒序取尾部、再按时间正序返回）。觉得历史太多就把 \`--limit\` 调小，需要更多上下文就调大。
 
 ## 用法
 
 \`\`\`bash
 # 拉取最近 50 条（默认）
-botmux thread messages
+botmux history
 
 # 拉取最近 100 条
-botmux thread messages --limit 100
+botmux history --limit 100
 
 # 指定 session-id（不在 CLI 会话内时用）
-botmux thread messages --session-id <uuid>
+botmux history --session-id <uuid>
 \`\`\`
 
 ## 输出
@@ -112,7 +128,9 @@ JSON 格式，字段：
 \`\`\`json
 {
   "sessionId": "...",
-  "threadId": "...",
+  "chatId": "...",
+  "scope": "thread" | "chat",
+  "rootMessageId": "...",     // 仅 scope=thread 时存在
   "messages": [
     { "messageId": "...", "senderId": "...", "senderType": "user|app", "msgType": "text|post|interactive", "content": "...", "createTime": "..." }
   ],
@@ -122,13 +140,62 @@ JSON 格式，字段：
 
 ## 注意
 
-- 只返回属于当前话题的消息（按 rootMessageId 过滤）
-- senderType="app" 表示机器人发的消息（包括 Claude Code / Codex / 其它 bot），"user" 表示用户
+- \`scope=thread\`：只返回属于当前话题的消息（按 rootMessageId 过滤）
+- \`scope=chat\`：返回当前群整群最近 N 条消息（不限于 session 创建之后，需要更老的就把 --limit 调大）
+- \`senderType="app"\` 表示机器人发的消息（包括 Claude Code / Codex / 其它 bot），\`"user"\` 表示用户
+- **合并转发**消息会自动展开：\`msgType\` 变为 \`merge_forward_expanded\`，\`content\` 是 \`<forwarded_messages>...</forwarded_messages>\` XML（含 \`<participants>\` 别名表 + 嵌套 \`<msg from="A">\` 节点），与 daemon 实时事件路径一致
 - 需要先把 JSON 读进来再做总结，不要直接把 JSON 扔给用户
 `;
+const QUOTED_SKILL = `---
+name: botmux-quoted
+description: 当 prompt 顶部出现 \`[用户引用了消息 用 botmux quoted om_xxx 查看]\` 提示时，用本技能按需读取被引用的那条消息内容。看到这种提示就该判断引用内容是否对当前任务必要，必要就调用，不必要就跳过。
+---
+
+# botmux-quoted — 读取被引用的消息
+
+用户在飞书里使用"引用回复" UI @ 机器人时，daemon 会在喂给你的 prompt 头部加一行：
+
+\`\`\`
+[用户引用了消息 用 botmux quoted om_xxx 查看]
+<用户的实际文字>
+\`\`\`
+
+看到这种提示，先判断引用内容是否对当前任务必要：必要就调用 \`botmux quoted om_xxx\` 拉取，不必要就忽略（不要无脑调用、污染上下文）。
+
+## 用法
+
+\`\`\`bash
+botmux quoted <message_id>
+\`\`\`
+
+\`message_id\` 直接从提示行里复制即可。
+
+## 输出
+
+JSON 格式，与 \`botmux history\` 的单条消息字段一致，并附带 \`resources\` 列表：
+
+\`\`\`json
+{
+  "messageId": "om_xxx",
+  "senderId": "ou_xxx",
+  "senderType": "user|app",
+  "msgType": "text|post|interactive|image|file|merge_forward_expanded",
+  "content": "...",
+  "createTime": "1234567890000",
+  "resources": [{"type":"image","key":"img_v3_xxx","name":"img_v3_xxx.jpg"}]
+}
+\`\`\`
+
+## 注意
+
+- 图片/文件渲染成 \`[图片 N]\` / \`[文件 N: name.pdf]\` 占位符（与 \`botmux history\` 一致），实际附件 key 在 \`resources\` 列表里
+- 卡片消息会被解析成可读文本
+- 合并转发消息会自动展开
+- 当前不支持自动下载附件本地化；要看图片实际内容，目前只能让用户单独转发或 \`botmux send\` 询问
+`;
 const SEND_SKILL = `---
 name: botmux-send
-description: 向飞书话题发送消息。用户在飞书上阅读看不到终端输出，需要用户看到的内容（关键结论、方案、最终结果、进度更新）必须通过 botmux send 发送。支持文本、图片、文件附件和 @mention。
+description: 向飞书话题发送消息。用户在飞书上阅读看不到终端输出，需要用户看到的内容（关键结论、方案、最终结果、进度更新）必须通过 botmux send 发送。支持图文混排（图片穿插在 markdown 正文中）、文本、图片/文件附件、@mention。
 ---
 
 # botmux-send — 向飞书话题发送消息
@@ -154,6 +221,8 @@ description: 向飞书话题发送消息。用户在飞书上阅读看不到终
 
 ### 纯文本（最常见）
 
+多行内容必须用 heredoc；不要写成 \`botmux send "第一行\\n第二行"\`，否则用户会在飞书里看到字面量 \`\\n\`。
+
 \`\`\`bash
 # 直接传参
 botmux send "分析完成，核心问题是 X"
@@ -172,6 +241,10 @@ EOF
 echo "构建成功 ✅" | botmux send
 \`\`\`
 
+> ⚠️ **重要：single-quoted heredoc \`<<'EOF'\` 内反引号直接写真反引号，不要加反斜杠转义。**
+> 原因：单引号 heredoc 已经禁用所有特殊字符解释（\`$\`、反斜杠、反引号一律按字面量处理）。再加反斜杠反而会把"反斜杠+反引号"作为字面字符混进 markdown，让 markdown-it 按 CommonMark 的 backslash-escape 处理——结果卡片里三反引号变成可见字符、代码块整段废掉。
+> 自检：写完 bash 命令后扫一眼，如果 EOF 块内**任何反引号前面带反斜杠**，删掉那个反斜杠。
+
 ### 可用的 markdown 语法（自动走卡片）
 
 | 语法 | 渲染 |
@@ -185,18 +258,34 @@ echo "构建成功 ✅" | botmux send
 | pipe 表格 | **原生 table 组件**（不是 monospace 伪表格） |
 | \`<at id=open_id></at>\` | @mention（一般用 \`--mention\` 自动注入，无需手写） |
 
-**图片混排**：\`--images\` 上传的本地图片默认追加到消息末尾。想在正文中指定位置，用占位符 \`![说明](img:N)\`（N 是 0-based 索引），会被替换成真正的 img_key。例：\`botmux send --images a.png --images b.png "前情\\n\\n![图1](img:0)\\n\\n中间文字\\n\\n![图2](img:1)"\`。
-
 **不支持**：外链图片 \`![](http://...)\`（飞书 markdown 元素只认本地上传的 img_key）、setext 标题（\`===\` 下划线式）、HTML 标签。
 
-### 带图片（内联显示）
+### 图文混排（图片穿插在正文中）
+
+\`--images <path>\` 上传本地图片（可重复）。在 markdown 正文中用占位符 \`![alt](img:N)\` 标记位置（\`N\` 是 0-based 索引，按 \`--images\` 给出的顺序对应）；不写占位符的图片自动追加到消息末尾。
 
 \`\`\`bash
-botmux send --images /tmp/screenshot.png <<'EOF'
-截图如上，红框部分是问题所在。
+# 单图：默认追加到末尾
+botmux send --images /tmp/screenshot.png "截图如上，红框部分是问题所在。"
+
+# 图文混排：占位符控制图片位置
+botmux send --images chart.png --images table.png <<'EOF'
+## 销售报告
+
+第一张是趋势图：
+
+![趋势](img:0)
+
+明细见下表：
+
+![明细](img:1)
+
+环比 +12%。
 EOF
 \`\`\`
 
+只支持本地路径上传，外链图片 \`![](http://...)\` 不会渲染。
+
 ### 带文件附件
 
 \`\`\`bash
@@ -216,6 +305,22 @@ botmux send --mention "ou_xxx:Aiden" "请 @Aiden 帮忙 review 这段代码"
 botmux send --mention ou_xxx "帮忙看下这段代码"
 \`\`\`
 
+### 顶层广播 / 跨群发布
+
+默认行为：消息**回复**到当前话题里。如果要把内容发到群里作为新的顶层消息（不绑定到任何已有话题），或要发到**另一个群**，用 \`--top-level\` 和 \`--chat-id\`。
+
+适用场景：定时任务把更新推到对外发布频道（changelog 群、动态群）；当前会话向另一个群广播通知。
+
+\`\`\`bash
+# 在当前群发顶层消息（不回复进当前话题）
+botmux send --top-level "📢 重要更新：xxx"
+
+# 跨群顶层发布（任意群，给定 chat_id）
+botmux send --top-level --chat-id oc_xxxxxxxxxxxx "📦 自动推送内容..."
+\`\`\`
+
+\`--top-level\` 模式下不会附加"发送给：@xxx / cc：xxx" 那行 footer（顶层广播没有特定收件人）。oncall 寻址也会跳过。
+
 ## 参数
 
 | 参数 | 说明 |
@@ -226,6 +331,8 @@ botmux send --mention ou_xxx "帮忙看下这段代码"
 | \`--files <path>\` | 附件文件，可重复多次，每个单独发送 |
 | \`--mention <open_id[:name]>\` | @mention，可重复。带 \`:name\` 时文本里的 \`@name\` 会被替换成 \<at\> 标签；只传 open_id 则在消息末尾追加 @。用 \`botmux bots list\` 查 open_id |
 | \`--card\` / \`--text\` | 强制卡片或纯文本模式（默认按 md 语法自动判断） |
+| \`--top-level\` | 发顶层消息（不回复进当前话题）；自动跳过"发送给/cc" footer |
+| \`--chat-id <oc_xxx>\` | 指定目标群（默认当前会话所在群）；常和 \`--top-level\` 一起用做跨群发布 |
 | \`--session-id <id>\` | 手动指定 session（通常自动推断，不需要传） |
 
 ## 输出
@@ -270,8 +377,15 @@ botmux send --mention "ou_yyy:Aiden" "请 @Aiden 帮忙处理"
 `;
 export const BUILTIN_SKILLS = [
     { name: 'botmux-schedule', content: SCHEDULE_SKILL },
-    { name: 'botmux-thread-messages', content: THREAD_MESSAGES_SKILL },
+    { name: 'botmux-history', content: HISTORY_SKILL },
+    { name: 'botmux-quoted', content: QUOTED_SKILL },
     { name: 'botmux-send', content: SEND_SKILL },
     { name: 'botmux-bots', content: BOTS_SKILL },
 ];
+/** Skills that earlier botmux versions installed but no longer ship. The
+ *  installer cleans these up so renamed skills don't linger as duplicates
+ *  in the CLI's skills directory. */
+export const RETIRED_SKILL_NAMES = [
+    'botmux-thread-messages',
+];
 //# sourceMappingURL=definitions.js.map

package/dist/skills/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/skills/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2EtB,CAAC;AAEF,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0C7B,CAAC;AAEF,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0GlB,CAAC;AAEF,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkClB,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAe;IACxC,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,cAAc,EAAE;IACpD,EAAE,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,qBAAqB,EAAE;IAClE,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,UAAU,EAAE;IAC5C,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,UAAU,EAAE;CAC7C,CAAC"}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/skills/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2FtB,CAAC;AAEF,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CrB,CAAC;AAEF,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8CpB,CAAC;AAEF,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkJlB,CAAC;AAEF,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkClB,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAe;IACxC,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,cAAc,EAAE;IACpD,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,EAAE;IAClD,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE;IAChD,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,UAAU,EAAE;IAC5C,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,UAAU,EAAE;CAC7C,CAAC;AAEF;;qCAEqC;AACrC,MAAM,CAAC,MAAM,mBAAmB,GAAa;IAC3C,wBAAwB;CACzB,CAAC"}

package/dist/skills/installer.d.ts

@@ -3,7 +3,9 @@
  * directory. Idempotent — only writes when content differs.
  *
  * Each skill becomes {skillsDir}/<name>/SKILL.md. Sub-directory layout
- * matches Claude Code / Gemini / OpenCode convention.
+ * matches Claude Code / Gemini / OpenCode convention. Retired skills (renamed
+ * or removed in a later version) are deleted from the directory so the CLI
+ * doesn't keep surfacing stale entries alongside their replacements.
  */
 export declare function ensureSkills(cliId: string, skillsDir: string | undefined): void;
 //# sourceMappingURL=installer.d.ts.map

package/dist/skills/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../src/skills/installer.ts"],"names":[],"mappings":"AAUA;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAoB/E"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../src/skills/installer.ts"],"names":[],"mappings":"AAUA;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAgC/E"}

package/dist/skills/installer.js

@@ -1,8 +1,8 @@
-import { writeFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
+import { writeFileSync, mkdirSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { logger } from '../utils/logger.js';
-import { BUILTIN_SKILLS } from './definitions.js';
+import { BUILTIN_SKILLS, RETIRED_SKILL_NAMES } from './definitions.js';
 function expandHome(p) {
     return p.startsWith('~') ? join(homedir(), p.slice(1)) : p;
 }
@@ -11,7 +11,9 @@ function expandHome(p) {
  * directory. Idempotent — only writes when content differs.
  *
  * Each skill becomes {skillsDir}/<name>/SKILL.md. Sub-directory layout
- * matches Claude Code / Gemini / OpenCode convention.
+ * matches Claude Code / Gemini / OpenCode convention. Retired skills (renamed
+ * or removed in a later version) are deleted from the directory so the CLI
+ * doesn't keep surfacing stale entries alongside their replacements.
  */
 export function ensureSkills(cliId, skillsDir) {
     if (!skillsDir)
@@ -38,5 +40,18 @@ export function ensureSkills(cliId, skillsDir) {
             logger.warn(`[skills] Failed to install ${skill.name} for ${cliId}: ${err.message}`);
         }
     }
+    // Clean up retired skill directories (e.g. botmux-thread-messages → botmux-history).
+    for (const retired of RETIRED_SKILL_NAMES) {
+        const retiredDir = join(dir, retired);
+        if (!existsSync(retiredDir))
+            continue;
+        try {
+            rmSync(retiredDir, { recursive: true, force: true });
+            logger.info(`[skills] Removed retired skill ${retired} for ${cliId}`);
+        }
+        catch (err) {
+            logger.warn(`[skills] Failed to remove retired skill ${retired} for ${cliId}: ${err.message}`);
+        }
+    }
 }
 //# sourceMappingURL=installer.js.map

package/dist/skills/installer.js.map

@@ -1 +1 @@
-{"version":3,"file":"installer.js","sourceRoot":"","sources":["../../src/skills/installer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,SAAS,UAAU,CAAC,CAAS;IAC3B,OAAO,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,SAA6B;IACvE,IAAI,CAAC,SAAS;QAAE,OAAO;IACvB,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;IAClC,IAAI,CAAC;QAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IAEnE,KAAK,MAAM,KAAK,IAAI,cAAc,EAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QAC7C,IAAI,CAAC;YACH,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC1B,MAAM,OAAO,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;gBACjD,IAAI,OAAO,KAAK,KAAK,CAAC,OAAO;oBAAE,SAAS;YAC1C,CAAC;YACD,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACzC,aAAa,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACjD,MAAM,CAAC,IAAI,CAAC,sBAAsB,KAAK,CAAC,IAAI,QAAQ,KAAK,MAAM,SAAS,EAAE,CAAC,CAAC;QAC9E,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,MAAM,CAAC,IAAI,CAAC,8BAA8B,KAAK,CAAC,IAAI,QAAQ,KAAK,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"installer.js","sourceRoot":"","sources":["../../src/skills/installer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACrF,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvE,SAAS,UAAU,CAAC,CAAS;IAC3B,OAAO,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,SAA6B;IACvE,IAAI,CAAC,SAAS;QAAE,OAAO;IACvB,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;IAClC,IAAI,CAAC;QAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IAEnE,KAAK,MAAM,KAAK,IAAI,cAAc,EAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QAC7C,IAAI,CAAC;YACH,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC1B,MAAM,OAAO,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;gBACjD,IAAI,OAAO,KAAK,KAAK,CAAC,OAAO;oBAAE,SAAS;YAC1C,CAAC;YACD,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACzC,aAAa,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACjD,MAAM,CAAC,IAAI,CAAC,sBAAsB,KAAK,CAAC,IAAI,QAAQ,KAAK,MAAM,SAAS,EAAE,CAAC,CAAC;QAC9E,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,MAAM,CAAC,IAAI,CAAC,8BAA8B,KAAK,CAAC,IAAI,QAAQ,KAAK,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IAED,qFAAqF;IACrF,KAAK,MAAM,OAAO,IAAI,mBAAmB,EAAE,CAAC;QAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACtC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;YAAE,SAAS;QACtC,IAAI,CAAC;YACH,MAAM,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACrD,MAAM,CAAC,IAAI,CAAC,kCAAkC,OAAO,QAAQ,KAAK,EAAE,CAAC,CAAC;QACxE,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,MAAM,CAAC,IAAI,CAAC,2CAA2C,OAAO,QAAQ,KAAK,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACjG,CAAC;IACH,CAAC;AACH,CAAC"}