botmux 3.16.0 → 3.17.0

package/dist/cli.js

@@ -41,6 +41,7 @@ import { findAncestorSessionContext as findLiveAncestorSessionContext, resolveSe
 import { resolveBotmuxDataDir } from './core/data-dir.js';
 import { dashboardSecretPath } from './core/dashboard-secret.js';
 import { acceptedDispatchBotAppIds, activeConversationBotOpenIds, buildDispatchCompletionBrief, parseDispatchBotSpec, buildDispatchMessages, buildRepoPrimeText, buildReportContent, eligibleAutoMentionAliases, foldableChatSessionAppIds, offTopicSubBotTopic, resolveReportPlacement, resolveReportRecipient, resolveSendTarget, threadRootForReachability } from './core/dispatch.js';
+import { withBotSteerDirective } from './core/bot-steer-directive.js';
 import { pickTurnReplyTarget, collectTurnWindowParticipants } from './core/reply-target.js';
 import { enableAutostart, disableAutostart, autostartStatus, refreshAutostart } from './autostart.js';
 import { tmuxEnv } from './setup/ensure-tmux.js';
@@ -111,6 +112,7 @@ import { collaborationHelp, formatBotInfoEntriesForCli, formatChatBotsForCli, }
 import { ensureBotChatGrantMatrix, requestExactChatGrant } from './cli/exact-chat-grant-client.js';
 import { buildFooterAddressing, hasKnownBotMention, knownBotOpenIdsFromCrossRef, orderedFooterRecipients, stripCodeSpans, } from './utils/bot-routing.js';
 import { isLocale, localeForBot, setDefaultLocale, SUPPORTED_LOCALES, t } from './i18n/index.js';
+import { registerPromptOverrideResolver } from './skills/effective-builtins.js';
 import { chatAppLink, larkHosts, normalizeBrand } from './im/lark/lark-hosts.js';
 import { mergeDashboardConfig, mergeGlobalConfig, readGlobalConfig, setGlobalLocale, globalConfigPath } from './global-config.js';
 import { createWhiteboard, ensureDefaultWhiteboard, getWhiteboard, listWhiteboards, readWhiteboard, whiteboardEnabled, whiteboardPath, } from './services/whiteboard-store.js';
@@ -135,6 +137,9 @@ import { isSuspendableBackendType, killPersistentBackendTarget, probePersistentB
     const cfg = readGlobalConfig();
     if (cfg.lang)
         setDefaultLocale(cfg.lang);
+    // Wire user prompt-key overrides into t() so CLI-side prompt building (e.g.
+    // `botmux skill show`, catalog rendering) honours customizations. Idempotent.
+    registerPromptOverrideResolver();
 }
 // CLI subcommands (send/thread/bots/list/etc) print JSON to stdout for
 // callers to parse. Transitive logger.info calls from shared modules would
@@ -6576,8 +6581,13 @@ botmux v${getVersion()} — IM ↔ AI 编程 CLI 桥接
     @ 硬门：每条回复须三选一 --mention/--mention-back/--no-mention，否则报错不发。
     按内容价值选：有实质结论要对方看/确认/决策→--mention-back(或--mention点名)；
     纯记录/低优先级进度/简短确认→--no-mention；没信息量的"收到"不如不发。
+    Bot→Bot 默认进入 Queue；要显式调整对方活跃的 Codex App turn，把 @steer 写成
+    正文首个语义行（可放在收件人 @ 行之后）。接收端会消费该指令，不交给模型。
     （可设 BOTMUX_REQUIRE_MENTION_DECISION=false 关闭硬门）
   bots list                            列出当前群聊中的机器人（含 open_id）
+  bots invite --chat <chatId> --team <id> --agent <appId>...
+                                       往「已存在的团队群」补人：把同团队、已 opt-in 的 agent + 各自 owner 一起拉进；
+                                       详见 \`botmux bots invite --help\`
   history [--limit N] [--scope session|thread|chat|ambient] [--with-card-json]
                                        拉取当前会话的消息历史 (JSON)。默认按 session scope：话题/话题群 → 话题内，普通群 → 整群；
                                        thread 会话里可用 --scope ambient 读取 thread 外的群聊上下文；
@@ -9994,8 +10004,9 @@ async function cmdDispatch(rest) {
                         派单前按双方 receiver 视角建立并回读 talk-only exact chatGrant，
                         发送后等待目标 session 接单确认；不支持 --repo 管理命令
   --bot <spec>          兼容外部/旧链路；spec = open_id[:名字[:角色]]，不保证本机双向授权
-  --brief <text>        子项目简报 / 追加内容
+  --brief <text>        子项目简报 / 追加内容；首个语义行写 @steer 可显式调整活跃 Codex App turn
   --brief-file <path>   从文件读取简报
+  --steer               在简报前注入通用 @steer 指令；普通 dispatch 默认仍进入 Queue
   --repo <path>         预设子 bot 工作目录（绝对路径，需在子 bot 所在机器上存在）
   --standby             仅 --repo 待命，不派简报
   --into <root_id>      回到已有话题线程追加（与 --title/种子互斥）
@@ -10014,6 +10025,7 @@ async function cmdDispatch(rest) {
     const repo = argValue(rest, '--repo');
     const intoRoot = argValue(rest, '--into');
     const standby = rest.includes('--standby');
+    const steer = rest.includes('--steer');
     const botSpecs = argValues(rest, '--bot');
     const botAppSpecs = argValues(rest, '--bot-app');
     let brief = argValue(rest, '--brief') ?? '';
@@ -10037,6 +10049,10 @@ async function cmdDispatch(rest) {
         console.error('--standby 与 --into 不能同用。');
         process.exit(1);
     }
+    if (standby && steer) {
+        console.error('--standby 与 --steer 不能同用（待命模式没有简报可调整当前 turn）。');
+        process.exit(1);
+    }
     if (botAppSpecs.length > 0 && repo) {
         console.error('--bot-app 仅自动建立 talk-only chatGrant，不能授权 /repo 管理命令；请使用驻守 Bot 的默认工作目录，或另走显式 operate 信任链路。');
         process.exit(1);
@@ -10045,6 +10061,8 @@ async function cmdDispatch(rest) {
         console.error('缺少简报。用 --brief 或 --brief-file 指定（仅 --standby 模式可省略）。');
         process.exit(1);
     }
+    if (steer)
+        brief = withBotSteerDirective(brief);
     if (!intoRoot && !title.trim()) {
         console.error('新开话题需要 --title。往已有话题追加请用 --into <root_id>。');
         process.exit(1);
@@ -11743,6 +11761,21 @@ async function cmdUserPromptHook() {
 }
 async function cmdBots(sub, rest) {
     process.env.SESSION_DATA_DIR ??= resolveDataDir();
+    if (sub === '--help' || sub === '-h' || sub === 'help') {
+        console.log(`
+botmux bots — 机器人协作花名册 / 团队补人
+
+子命令:
+  bots list [--scope chat|team] [--team <id>] [--session-id ID]
+             列出机器人。默认 chat scope：当前飞书群内的 bot（含 open_id、能力标签、能否可靠 @到）；
+             --scope team：跨机列出同团队、已 opt-in 的 agent（按专长发现，供拉群 / 补人）。
+  bots invite --chat <chatId> --team <id> --agent <appId>...
+             往「已存在的团队群」补人：把同团队、已 opt-in 的 agent + 各自 owner 一起拉进。
+
+补人（invite）的完整参数与 403 前置条件见 \`botmux bots invite --help\`。
+`);
+        return;
+    }
     // `bots invite`：往**已存在的团队群**补人（同 team、已 opt-in 的 agent + 各自 owner），
     // 打平台端点4（machine-auth）。独立子命令——与「建新群」的 create-group 语义分开，
     // 不再靠 create-group --chat 区分（那个入口易被误读成"建群"）。在会话/transport 闸门前分流。
@@ -11753,6 +11786,7 @@ async function cmdBots(sub, rest) {
     if (sub !== 'list' && sub !== 'ls' && sub !== '') {
         console.error('用法: botmux bots list [--scope chat|team] [--team <id>] [--session-id ID]');
         console.error('      botmux bots invite --chat <chatId> --team <id> --agent <appId>...');
+        console.error('（完整说明见 botmux bots --help）');
         process.exit(1);
     }
     // `--scope team`：跨机发现同团队、已 opt-in 的 agent（打平台端点2，machine-auth）。
@@ -11950,6 +11984,47 @@ async function tryAutoAddPlatformBot(chatId, platformAppId) {
  * {ok, chatId, invalidBotIds, invalidOwnerUnionIds, teamId}；invalid* 非空 → 非零退出。
  */
 async function cmdBotsInvite(rest) {
+    if (rest.includes('--help') || rest.includes('-h')) {
+        console.log(`
+botmux bots invite — 往「已存在的团队群」补人（同团队、已 opt-in 的 agent + 各自 owner）
+
+用法:
+  botmux bots invite --chat <chatId> --team <teamId> --agent <appId> [--agent ...]
+                     [--json-status]
+
+参数:
+  --chat <chatId>  必填。目标群 chatId（oc_...）。须满足下列前置条件（否则平台按 403 拒绝，见下）。
+  --team <teamId>  团队 id。省略时：本机唯一团队自动用它，多个团队要求显式指定（不猜）。
+  --agent <appId>  至少一个、可多次、按 appId 去重。appId 从 \`botmux bots list --scope team\` 发现。
+  --json-status    可选；在 stdout 单行 chatId 后追加一行 {ok, chatId, invalidBotIds,
+                   invalidOwnerUnionIds, teamId}；invalid* 非空 → 非零退出。
+
+行为:
+  - 全程 machine-auth，只认 appId、不需要 @（发起人在别人 bot 进群前根本 @不到它）。
+  - 补人恒把 agent + 各自 owner 一起拉进群；已在群内视作成功（幂等）。
+  - 授权 / opt-in 闸 / 大厅排除全在平台，CLI 零判断、只如实展示平台判定。
+  - 平台机器人（BotmuxPlatform）不在目标群时，会自动用群内本机 bot 当代理把它拉进群再重试；
+    自动添加失败（需群主审批 / 代理 bot 无成员管理 scope）时给出手动添加引导。
+
+前置条件（不满足平台按 403 拒绝，平台按 error code 分型）:
+  - 平台机器人（BotmuxPlatform）已在群里     → 否则 platform_bot_not_in_chat（先把它拉进群）
+  - 你本人已在该群                          → 否则 requester_not_in_chat（只能往你自己在场的群补人）
+  - 非机器人大厅                            → 否则 chat_is_hall（大厅是 bot-only 身份登记群）
+  - 每个 --agent 都已 opt-in 进该团队        → 否则 not_in_team_bots（其 owner 需在平台「管理机器人」把它加进团队；
+                                              提示会点出具体被拒的 agent，部分失败也会在 invalidBotIds 里列出）
+
+与相邻命令的区别（别混）:
+  - create-group --team：把同团队、已 opt-in 的别人机器上的 agent + 各自 owner 新建成一个聚焦新群。
+  - bots invite --chat：群已经在了、且平台机器人也在，往里补同团队的人（含各自 owner）。
+  - /invite（飞书群内 slash）：把 bot 加进当前群，走飞书原生加成员，限同租户；命令本身只拉 bot，
+    owner 由被拉 bot 的 daemon 在入群事件里补拉（默认开启，可 per-bot 关，且需其 daemon 在线）——
+    区别于本命令/create-group 由平台原子带上 owner（不依赖对方 daemon 在线）。
+
+输出:
+  - 成功 stdout 输出单行 chatId（与 create-group 一致）；失败 / 部分失败 stderr 打提示并非零退出。
+`);
+        return;
+    }
     const { addTeamGroupMembers, fetchTeams, describeTeamAgentsFailure, rateLimitRetryHint, shouldTryAutoAddPlatformBot } = await import('./platform/team-agents-client.js');
     const jsonStatus = rest.includes('--json-status');
     const chatArg = (argValue(rest, '--chat') ?? '').trim();
@@ -12331,6 +12406,12 @@ function getVersion() {
     }
 }
 const command = process.argv[2];
+const ROOT_FLEET_MUTATION_COMMANDS = new Set(['start', 'stop', 'restart', 'upgrade', 'update']);
+if (ROOT_FLEET_MUTATION_COMMANDS.has(command ?? '')
+    && process.argv.slice(3).some(arg => arg === '--help' || arg === '-h')) {
+    showHelp();
+    process.exit(0);
+}
 // Workflow safety gate (Slice C0): a CLI invoked inside a workflow
 // subagent worker (BOTMUX_WORKFLOW=1, set by v3/ephemeral-pool) must not
 // trigger chat-facing effects, schedule mutations, or recursively authorize /
@@ -13263,6 +13344,16 @@ switch (command) {
         process.exitCode = result.code;
         break;
     }
+    case 'customize': {
+        const { runCustomizeCommand } = await import('./core/skills/customize-command.js');
+        const result = runCustomizeCommand(process.argv.slice(3));
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        process.exitCode = result.code;
+        break;
+    }
     case 'mcp': {
         const sub = process.argv[3] ?? '';
         if (sub !== 'serve') {