@xyagent/cli 0.0.1

package/src-ext/runtime/_shared/slashCommandRouter.mjs

@@ -0,0 +1,1346 @@
+/**
+ * slashCommandRouter.mjs — Bridge-side slash command interception.
+ *
+ * 远程 chat 通道里收到 `/foo` 时怎么处理:
+ *
+ *   not-slash       — 普通文本或 claude 上要透传给 CLI 的 slash, bridge 不拦
+ *   passthrough     — 标记 slash 但仍透传给 CLI(claude 部分命令 CLI 真支持)
+ *   client-reset    — bridge 自己处理 + 清 thread→session 映射(/clear)
+ *   bridge-synth    — bridge 合成响应, **不**调用 CLI
+ *   unsupported     — 极少见 fallback(理论上 default-export 之后不会出现)
+ *
+ * 设计原则:
+ *   - claude `--print --input-format stream-json` 模式对部分 slash 会发
+ *     synthetic assistant 消息(model="<synthetic>"), parser 端已经能透出来。
+ *     这些命令走 not-slash 让 CLI 自己说话。
+ *   - codex MCP `tools/call codex` 不识别任何 slash, 一律 bridge-synth, 避免
+ *     LLM 拿到 slash 当 prompt 幻觉应答(典型隐性事故 /clear)。
+ *   - 凡是远程语境下没意义的命令(账号/退出),已经从 App 端 seed 移除, 不会
+ *     再传过来; 但 router 仍兜底返回简短说明, 万一用户手动打。
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { execCliSafe, probeClaudeSystemInit } from "./cliExec.mjs";
+import { collectCodexCustomCommands } from "../codex/codexCustomCommandsCollector.mjs";
+
+/**
+ * 进程级缓存 claude system/init 输出。第一次实测 spawn 一次, 后续命中复用。
+ * Bridge 重启清空(claude CLI 升级后会自然 re-probe)。
+ *
+ * 缓存按 cwd 分键：init 里的 slash_commands 含**工作区级**自定义命令
+ * (.claude/commands/)，不同工作区清单不同，混用会把 A 工作区的自定义命令
+ * 误判成「不支持」(P0#25)。forceFresh 给「未知命令」路径用——用户刚创建的
+ * 自定义命令不在旧缓存里，必须绕过缓存重探一次才能判死。
+ */
+let _claudeInitCache = null; // { cwd, init }
+async function getClaudeInit(ctx, { forceFresh = false } = {}) {
+  // 用 "in" 检测 key 是否存在，允许注入明确的 null（probe 失败场景的测试）
+  if (ctx && "claudeInit" in ctx) return ctx.claudeInit;
+  const cwd = ctx?.cwd || "";
+  if (!forceFresh && _claudeInitCache && _claudeInitCache.cwd === cwd) {
+    return _claudeInitCache.init;
+  }
+  const init = await probeClaudeSystemInit({ cwd: ctx?.cwd, timeoutMs: 8000 });
+  if (init) _claudeInitCache = { cwd, init };
+  return init;
+}
+
+// 允许 `:` 以匹配插件/自定义命令命名空间（如 /my-plugin:init）。
+const SLASH_RE = /^\s*(\/[a-zA-Z][\w:-]*)(?:\s+([\s\S]*))?\s*$/;
+
+/**
+ * 解析并分类。
+ *
+ * @param {string} input
+ * @param {"claude"|"codex"|string} runtime
+ * @param {object} [bridgeCtx] — bridge 状态, 用于合成 codex 响应:
+ *   {
+ *     version: string,           // CLI 版本
+ *     cwd: string,               // bridge 工作目录
+ *     gwId: string,              // bridge gw_id
+ *     threadId: string,          // agentlink thread_id
+ *     sessionId: string|null,    // CLI internal session/threadId
+ *     model: string|null,        // 当前 model
+ *     sessionConfigured: {...}|null,  // codex MCP session_configured payload
+ *   }
+ */
+export async function classifySlashCommand(input, runtime, bridgeCtx) {
+  const m = SLASH_RE.exec(typeof input === "string" ? input : "");
+  if (!m) return { kind: "not-slash" };
+  const command = m[1].toLowerCase();
+  const args = (m[2] || "").trim();
+  const ctx = bridgeCtx || {};
+
+  if (runtime === "claude") {
+    // /clear: 必须 bridge 层拦截清 session map
+    if (command === "/clear") {
+      return {
+        kind: "client-reset",
+        command,
+        ackText: "已清除 Claude Code 远程会话上下文,下一条消息将从新会话开始。",
+      };
+    }
+    // CLI 真正会执行的命令 → passthrough 让 CLI 自己跑（保留 args，原文透传）
+    if (CLAUDE_CLI_HANDLED.has(command)) {
+      return { kind: "passthrough", command };
+    }
+    // TUI 对齐: print 模式不可用但有明确动作语义的命令 → 改写为等效 prompt 真跑
+    if (CLAUDE_PROMPT_REWRITES[command]) {
+      return {
+        kind: "prompt-rewrite",
+        command,
+        rewrittenInput: CLAUDE_PROMPT_REWRITES[command](args),
+      };
+    }
+    // 插件/自定义命令命名空间（带 :）→ 一律透传，存在性交给 claude 校验
+    if (command.includes(":")) {
+      return { kind: "passthrough", command };
+    }
+    // bridge 有等价合成实现的命令 → bridge-synth
+    if (CLAUDE_HANDLERS[command]) {
+      const text = await synthesizeClaudeSlashResponse(command, args, ctx);
+      if (text != null) {
+        // handler 返回 { __kind: "interrupt_session_pick" } 信号对象时，改为 interrupt-session-pick kind
+        if (typeof text === "object" && text.__kind === "interrupt_session_pick") {
+          return { kind: "interrupt-session-pick", command };
+        }
+        return { kind: "bridge-synth", command, responseText: text };
+      }
+      return { kind: "not-slash" };
+    }
+    // 未知命令：探 claude system/init 的 slash_commands 活体清单。
+    // 命中（用户自定义 ~/.claude/commands / skill 命令）→ 透传真跑；
+    // 未命中 → __default__ 合成提示，避免英文 "Unknown command" 直出。
+    const bare = command.slice(1);
+    const hitKnown = (init) => {
+      const known = Array.isArray(init?.slash_commands) ? init.slash_commands : [];
+      return known.some((c) => String(c).toLowerCase() === bare);
+    };
+    let init = await getClaudeInit(ctx);
+    let hit = hitKnown(init);
+    if (!hit && !ctx?.claudeInit) {
+      // 缓存可能 stale：用户刚创建的自定义命令不在旧清单里 (P0#25)。
+      // 判死前强制 re-probe 一次（未知命令低频，~1s 探活成本可接受）。
+      init = await getClaudeInit(ctx, { forceFresh: true });
+      hit = hitKnown(init);
+    }
+    if (hit) {
+      return { kind: "passthrough", command };
+    }
+    // 把 probe 结果注入 ctx，让 __default__ 区分「probe 成功 miss」和「probe null」
+    const ctxWithInit = { ...ctx, _claudeProbeInit: init };
+    const text = await synthesizeClaudeSlashResponse(command, args, ctxWithInit);
+    return { kind: "bridge-synth", command, responseText: text };
+  }
+
+  if (runtime === "codex") {
+    if (command === "/clear" || command === "/new") {
+      return {
+        kind: "client-reset",
+        command,
+        ackText: command === "/clear"
+          ? "已清除 Codex 远程会话上下文,下一条消息将从新会话开始。"
+          : "已开新 Codex 会话(上下文已清空),发消息开始对话。",
+      };
+    }
+    // bridge-synth 内置命令优先（防止同名自定义命令覆盖 /help /status 等）
+    if (CODEX_HANDLERS[command]) {
+      const text = await synthesizeCodexSlashResponse(command, args, ctx);
+      if (text != null) {
+        if (typeof text === "object" && text.__kind === "interrupt_session_pick") {
+          return { kind: "interrupt-session-pick", command };
+        }
+        return { kind: "bridge-synth", command, responseText: text };
+      }
+      return { kind: "not-slash" };
+    }
+    // codex 自定义命令 expand 路径
+    {
+      const bare = command.slice(1);
+      const promptsDir = ctx?._codexPromptsDir || join(homedir(), ".codex", "prompts");
+      // 用注入的 stale 列表（测试）或从磁盘扫描
+      let customCmds;
+      if (ctx?._codexCustomCommands) {
+        customCmds = ctx._codexCustomCommands;
+      } else {
+        customCmds = await collectCodexCustomCommands({ _promptsDir: promptsDir });
+      }
+      const isCustom = customCmds.some((c) => c.command === command);
+      if (isCustom) {
+        const promptFile = join(promptsDir, `${bare}.md`);
+        if (!existsSync(promptFile)) {
+          // stale 缓存场景：命令在列表但文件不存在 → 兜底 not-slash
+          return { kind: "not-slash" };
+        }
+        try {
+          const rawContent = readFileSync(promptFile, "utf8");
+          // 去掉 frontmatter，只取正文
+          const bodyMatch = /^---\n[\s\S]*?\n---\n?([\s\S]*)$/.exec(rawContent);
+          const body = bodyMatch ? bodyMatch[1].trim() : rawContent.trim();
+          // 占位符替换
+          const tokens = args ? args.split(/\s+/) : [];
+          let expanded = body
+            .replace(/\$ARGUMENTS/g, args)
+            .replace(/\$([1-9])/g, (_, n) => tokens[Number(n) - 1] ?? "");
+          return { kind: "codex-custom-expand", command, expandedPrompt: expanded };
+        } catch {
+          return { kind: "not-slash" };
+        }
+      }
+    }
+    // 未知命令：走 codex __default__ 合成
+    const text = await synthesizeCodexSlashResponse(command, args, ctx);
+    if (text != null) {
+      if (typeof text === "object" && text.__kind === "interrupt_session_pick") {
+        return { kind: "interrupt-session-pick", command };
+      }
+      return { kind: "bridge-synth", command, responseText: text };
+    }
+    return { kind: "not-slash" };
+  }
+
+  if (runtime === "hermes") {
+    if (command === "/clear" || command === "/new") {
+      return {
+        kind: "client-reset",
+        command,
+        ackText: command === "/clear"
+          ? "已清除当前 Hermes 会话历史,下一条消息将从新会话开始。"
+          : "已开新 Hermes 会话(历史清空),发消息开始对话。",
+      };
+    }
+    const text = await synthesizeHermesSlashResponse(command, args, ctx);
+    if (text != null) {
+      if (typeof text === "object" && text.__kind === "interrupt_session_pick") {
+        return { kind: "interrupt-session-pick", command };
+      }
+      return { kind: "bridge-synth", command, responseText: text };
+    }
+    return { kind: "not-slash" };
+  }
+
+  return { kind: "not-slash" };
+}
+
+/** Claude CLI 在 `--print --input-format stream-json` 下会真实执行的命令,
+ * bridge 原文透传即可(synthetic 快回复由 stdoutParser 抓 text, LLM-backed
+ * 长任务走正常事件流, 远程照样可流式看到进度)。
+ *
+ * 注: /init /review /security-review 是 LLM-backed 长任务(分钟级)。曾经为它们
+ * bridge-synth 说明文档, 但用户预期是「真的执行」(P0: /init + 跟随内容被丢弃,
+ * 只回帮助文案), 故改为透传真跑, 跟随内容(args)随原文一起进入 claude。 */
+const CLAUDE_CLI_HANDLED = new Set([
+  "/compact",         // 真跑 compaction(秒级返回, 即使无内容也快)
+  "/context",         // 显示 token 用量表(同步, 秒级)
+  "/init",            // 真跑 CLAUDE.md 初始化(LLM-backed, 流式可见)
+  "/review",          // 真跑代码评审
+  "/security-review", // 真跑安全审查
+  "/cost",            // 实测(claude 2.1.170): print 模式真返回订阅配额, 弃用 PTY 探测
+  "/usage",           // 同上
+]);
+
+/** TUI 对齐(P1#22): 这些命令 print 模式不可用("isn't available"), 但 TUI 里有
+ * 明确动作语义 —— 改写成等效自然语言 prompt 让 claude 真跑, 行为与 TUI 一致。
+ * （实测 2.1.170: /diff /recap 等在 print 模式只回 "isn't available"。） */
+const CLAUDE_PROMPT_REWRITES = {
+  "/diff": (args) =>
+    args
+      ? `请用 Bash 工具执行 git diff ${args}，把结果按文件整理返回（带代码块格式）。`
+      : "请用 Bash 工具执行 git status 和 git diff（如有 staged 改动再补 git diff --cached），把当前改动按文件整理返回（带代码块格式）。",
+  "/recap": (args) =>
+    args
+      ? `请回顾我们这个会话的内容，围绕「${args}」做一个结构化总结：做了什么、改了哪些文件、还有什么待办。`
+      : "请回顾我们这个会话的内容，做一个结构化总结：聊了什么、做了哪些改动、结论与待办事项。",
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Claude synth — 所有 seed 命令保证有响应
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function synthesizeClaudeSlashResponse(command, args, ctx) {
+  const handler = CLAUDE_HANDLERS[command];
+  if (handler) return await handler(ctx, args, command);
+  // 未知 slash → 走 __default__, 保证用户永远不会拿到"暂不支持"那种空洞回复
+  return await CLAUDE_HANDLERS.__default__(ctx, args, command);
+}
+
+const CLAUDE_HANDLERS = {
+  "/help": (ctx) => [
+    "Claude Code 远程会话命令清单(完整版):",
+    "",
+    "── 会话控制 ─────────────────────────────",
+    "  /clear              清除上下文, 下一条消息开新会话",
+    "  /compact            压缩历史以释放上下文窗口(CLI 真跑)",
+    "  /context            查看当前 token 用量分布(CLI 真显示)",
+    "  /resume             续接最近会话(本机才可用,远程由 thread 续接代替)",
+    "  /rewind             回退到上一轮(远程不可用)",
+    "  /branch             分支当前会话(本机才可用)",
+    "  /recap              快速回顾当前会话",
+    "  /rename             重命名当前会话",
+    "",
+    "── 信息查看 ─────────────────────────────",
+    "  /status             会话状态(版本/cwd/gw_id/thread_id)",
+    "  /model              当前模型",
+    "  /cost  /usage       订阅/计费信息",
+    "  /diff               git diff(本机才可用, 远程直接让 AI 跑)",
+    "  /doctor             健康检查",
+    "  /export             导出会话历史",
+    "",
+    "── 配置 / 管理 ────────────────────────",
+    "  /config             配置概览",
+    "  /permissions        权限设置说明",
+    "  /hooks              hooks 配置",
+    "  /mcp                MCP server 列表",
+    "  /memory             记忆系统说明",
+    "",
+    "── 智能体 / 技能 ──────────────────────",
+    "  /agents             subagent 列表",
+    "  /skills             skills 库说明",
+    "",
+    "── 评审 ─────────────────────────────────",
+    "  /review             代码评审(CLI 真跑)",
+    "  /security-review    安全审查(CLI 真跑)",
+    "",
+    "── 反馈 ─────────────────────────────────",
+    "  /feedback           提交反馈",
+    "",
+    "用法: 在输入框点击「系统指令」chip 选命令,或直接打 `/xxx` 发送。",
+  ].join("\n"),
+
+  "/status": async (ctx) => {
+    const init = await getClaudeInit(ctx);
+    const lines = ["Claude Code 远程会话状态:"];
+    lines.push(`  Claude Code 版本  : ${init?.claude_code_version || ctx.version || "未知"}`);
+    lines.push(`  当前模型          : ${init?.model || ctx.model || "未知"}`);
+    lines.push(`  工作目录(cwd)     : ${init?.cwd || ctx.cwd || "未知"}`);
+    if (init?.permissionMode) lines.push(`  权限模式          : ${init.permissionMode}`);
+    if (init?.output_style) lines.push(`  输出风格          : ${init.output_style}`);
+    if (init?.apiKeySource) lines.push(`  API key 来源      : ${init.apiKeySource}`);
+    if (Array.isArray(init?.mcp_servers)) lines.push(`  MCP server 数     : ${init.mcp_servers.length}`);
+    if (Array.isArray(init?.agents)) lines.push(`  Subagent 数       : ${init.agents.length}`);
+    if (Array.isArray(init?.skills)) lines.push(`  Skill 数          : ${init.skills.length}`);
+    if (ctx.gwId) lines.push(`  Bridge gateway id : ${ctx.gwId}`);
+    if (ctx.threadId) lines.push(`  对话 thread id    : ${ctx.threadId}`);
+    lines.push(`  claude session id : ${ctx.sessionId || "(尚未建立, 下一条消息时分配)"}`);
+    lines.push("");
+    lines.push("精确 token 用量请发 /context 查看, 速率限制发 /usage。");
+    return lines.join("\n");
+  },
+
+  "/model": async (ctx) => {
+    const init = await getClaudeInit(ctx);
+    if (init?.model) {
+      const lines = [`当前 Claude Code 模型(实时, 从 claude --print 探到):`];
+      lines.push(`  ▸ 模型 id     : ${init.model}`);
+      if (init.apiKeySource) lines.push(`  ▸ API key 来源: ${init.apiKeySource}`);
+      if (init.claude_code_version) lines.push(`  ▸ CLI 版本    : ${init.claude_code_version}`);
+      lines.push("");
+      lines.push("切换模型: 在 App 顶部「模型」入口选择, 或在本机 ~/.claude/settings.json");
+      lines.push("`model` 字段改后重启 bridge。");
+      return lines.join("\n");
+    }
+    if (ctx.model) return `当前 Claude Code 模型: ${ctx.model}\n\n切换模型请用 App 顶部「模型」入口。`;
+    return "当前 Claude Code 模型未知(probeClaudeSystemInit 超时)。请用 App 顶部「模型」入口选择, 或在本机终端 `claude` 后 /model 查看。";
+  },
+
+  "/version": async (ctx) => {
+    const real = await execCliSafe("claude", ["--version"], { timeoutMs: 4000 });
+    if (real) return `Claude Code 版本(实时):\n  ${real}`;
+    return ctx.version ? `Claude Code ${ctx.version}` : "Claude Code 版本未知";
+  },
+
+  // /cost /usage 已移入 CLAUDE_CLI_HANDLED 透传真跑(P1#22)，不再 PTY 探测。
+
+  "/agents": () => [
+    "Claude Code subagent 列表(管理 UI 限本机交互模式):",
+    "",
+    "  ▸ 远程会话仍能用 subagent:",
+    "    - 普通对话里直接说「让 code-reviewer 审一下当前 diff」",
+    "      或「派一个 general-purpose agent 搜全仓里的 TODO」",
+    "    - Claude 会自动 dispatch Task / Agent 工具调用相应 subagent",
+    "    - subagent 输出在 App 里以「subagent_ref」事件块展示(可展开看子任务详情)",
+    "",
+    "  ▸ 你装了哪些自定义 subagent,可在本机终端 `claude` 进 REPL 后",
+    "    输入 `/agents` 查看完整管理 UI。",
+  ].join("\n"),
+
+  "/skills": () => [
+    "Claude Code Skills:",
+    "",
+    "  ▸ Skill 是 Claude Code 的「触发名 + 指令包」机制, 比如 `/init` 实际就是",
+    "    一个 skill。用法: 在对话里直接打 `/<skill-name>` 即可触发。",
+    "  ▸ 完整 skill 管理(查看 / 启用 / 禁用 / 安装新 skill) 仅在本机交互模式可用。",
+    "    本机终端执行 `claude`, 进 REPL 后输入 `/skills` 看完整 UI。",
+    "  ▸ 第三方 plugins 也会自动注册 skill,远程能用,但管理走本机。",
+  ].join("\n"),
+
+  "/memory": () => [
+    "Claude Code 记忆(auto-memory)系统:",
+    "",
+    "  ▸ Claude 会自动把对话里值得记住的信息(用户偏好/项目惯例/反馈/重要决定)",
+    "    写入 ~/.claude/projects/<project>/memory/ 下的 MEMORY.md 索引 + 独立",
+    "    分类 markdown 文件。每次对话开始 Claude 会自动加载 MEMORY.md 作为",
+    "    系统提示一部分。",
+    "  ▸ 远程会话也会触发自动记忆。手动让 Claude 记: 直接在对话里说",
+    "    「记住:我们这边项目用 ...」就行。",
+    "  ▸ 完整记忆管理 UI(查看/编辑/删除单条记忆)仅本机 REPL 模式 `/memory` 可用。",
+  ].join("\n"),
+
+  "/permissions": async (ctx) => {
+    const init = await getClaudeInit(ctx);
+    const lines = ["Claude Code 权限配置(实时, 从 claude --print system/init 探到):"];
+    if (init?.permissionMode) lines.push(`  ▸ 当前 permission mode : ${init.permissionMode}`);
+    else lines.push("  ▸ 当前 permission mode : 未知(探测超时)");
+    if (Array.isArray(init?.tools)) lines.push(`  ▸ 当前可用工具数       : ${init.tools.length}`);
+    if (init?.apiKeySource) lines.push(`  ▸ API key 来源         : ${init.apiKeySource}`);
+    lines.push("");
+    lines.push("permissionMode 取值:");
+    lines.push("  • default          — 工具调用前弹审批");
+    lines.push("  • acceptEdits      — Edit/Write 自动通过, 其它仍审批");
+    lines.push("  • bypassPermissions — 全部自动通过(--print 远程会话默认)");
+    lines.push("  • plan             — 只跑 plan, 不执行写操作");
+    lines.push("  • auto             — 按工具类别自动判");
+    lines.push("");
+    lines.push("修改: 编辑 ~/.claude/settings.json 的 `permissions` / `permissionMode`,");
+    lines.push("或编辑项目 `.claude/settings.json`, 重启 bridge 生效。");
+    lines.push("");
+    lines.push("── AgentLink Bridge 审批模式 ────────────────────────────────");
+    lines.push("AGENTLINK_CLAUDE_PERMISSION_MODE=approval  启用 App 审批弹窗");
+    lines.push("  • 每次需要权限的工具调用, App 弹出「同意/拒绝」审批卡。");
+    lines.push("  • 10 分钟无响应自动 deny（不会永久阻塞）。");
+    lines.push("  ⚠️ 重要：approval 模式使用 --setting-sources project，");
+    lines.push("     ~/.claude/settings.json 中配置的工具 allow 规则（如 Bash(*)）");
+    lines.push("     在此模式下不生效。如需自动放行某些工具，请在工作区的");
+    lines.push("     .claude/settings.json 中配置。");
+    lines.push("  默认值 bypassPermissions 不变，approval 为显式 opt-in。");
+    return lines.join("\n");
+  },
+
+  "/resume": () => ({ __kind: "interrupt_session_pick" }),
+
+  "/rewind": () => [
+    "Claude Code /rewind 不可用于远程会话:",
+    "",
+    "  ▸ 远程模式 `claude --print` 单 turn 推进, 没有 REPL 的可视化时间线。",
+    "  ▸ 想撤销上一轮: 删掉最近一条对话消息(App 里长按消息删除)即可。",
+    "  ▸ 想从某个早期节点 fork: App 聊天列表新建对话即可。",
+  ].join("\n"),
+
+  "/branch": () => [
+    "Claude Code /branch 不可用于远程会话:",
+    "",
+    "  ▸ /branch 在本机 REPL 模式从当前点开新分支 session。",
+    "  ▸ 远程语境下等价做法: App 聊天列表「新建对话」+ 把当前对话的关键上下文",
+    "    复制过去, 等于一个手动 branch。",
+  ].join("\n"),
+
+  // /diff 已走 prompt-rewrite 真跑(P1#22)。
+
+  "/config": async (ctx) => {
+    const init = await getClaudeInit(ctx);
+    const lines = ["Claude Code 配置(实时, 从 claude --print system/init 探到):"];
+    lines.push(`  ▸ Claude Code 版本 : ${init?.claude_code_version || ctx.version || "未知"}`);
+    lines.push(`  ▸ 当前模型         : ${init?.model || ctx.model || "未知"}`);
+    lines.push(`  ▸ 工作目录(cwd)   : ${init?.cwd || ctx.cwd || "未知"}`);
+    if (init?.permissionMode) lines.push(`  ▸ 权限模式         : ${init.permissionMode}`);
+    if (init?.output_style) lines.push(`  ▸ 输出风格         : ${init.output_style}`);
+    if (init?.apiKeySource) lines.push(`  ▸ API key 来源     : ${init.apiKeySource}`);
+    if (init?.analytics_disabled !== undefined) lines.push(`  ▸ analytics        : ${init.analytics_disabled ? "disabled" : "enabled"}`);
+    if (init?.fast_mode_state) lines.push(`  ▸ fast mode        : ${init.fast_mode_state}`);
+    if (Array.isArray(init?.mcp_servers)) lines.push(`  ▸ MCP server 数    : ${init.mcp_servers.length}`);
+    if (Array.isArray(init?.agents)) lines.push(`  ▸ Subagent 数      : ${init.agents.length}`);
+    if (Array.isArray(init?.skills)) lines.push(`  ▸ Skill 数         : ${init.skills.length}`);
+    if (Array.isArray(init?.plugins)) lines.push(`  ▸ Plugin 数        : ${init.plugins.length}`);
+    if (init?.memory_paths) lines.push(`  ▸ 记忆路径         : ${JSON.stringify(init.memory_paths)}`);
+    lines.push("");
+    lines.push("完整配置看本机:");
+    lines.push("  ~/.claude/settings.json(用户级) / .claude/settings.json(项目级) /");
+    lines.push("  .claude/settings.local.json(本地级)");
+    lines.push("改后重启 bridge 生效。");
+    return lines.join("\n");
+  },
+
+  "/hooks": () => [
+    "Claude Code Hooks 配置:",
+    "",
+    "  ▸ Hooks 在 ~/.claude/settings.json(或项目 .claude/settings.json)的 `hooks`",
+    "    字段配置,支持事件: PreToolUse / PostToolUse / SessionStart / SessionEnd /",
+    "    UserPromptSubmit / Stop / Notification 等。",
+    "  ▸ Hook 执行 shell 命令 / 脚本, 可以拦截 / 修改 / 拒绝工具调用。",
+    "  ▸ 远程会话里 hooks 跟本机一样生效(bridge 起的 claude 进程读同一份配置)。",
+    "  ▸ 想现场编辑 hooks 配置,请用本机终端: `claude config edit` 或直接改 settings.json。",
+  ].join("\n"),
+
+  "/mcp": async () => {
+    // 真起 `claude mcp list` 拿用户级 + 项目级 MCP 配置(权威)
+    const real = await execCliSafe("claude", ["mcp", "list"], { timeoutMs: 5000 });
+    if (real && real.length > 0) {
+      return [
+        "Claude Code MCP server(实时, 来自 `claude mcp list`):",
+        "",
+        real,
+        "",
+        "管理: `claude mcp add <name> <cmd>` / `claude mcp remove <name>`,",
+        "或在 ~/.claude/settings.json 的 `mcpServers` 字段编辑。",
+      ].join("\n");
+    }
+    return [
+      "Claude Code 当前没有挂载任何 MCP server(claude mcp list 输出空)。",
+      "",
+      "挂载方式:",
+      "  ▸ 本机终端: `claude mcp add <name> <command>`(项目级)",
+      "  ▸ 编辑 ~/.claude/settings.json 加 `mcpServers.<name>`(用户级)",
+      "  ▸ 项目根加 .mcp.json(repo 级, 团队共享)",
+    ].join("\n");
+  },
+
+  "/doctor": async (ctx) => {
+    const init = await getClaudeInit(ctx);
+    const lines = ["Claude Code 健康检查(远程探到):"];
+    lines.push(`  ▸ Claude Code 版本 : ${init?.claude_code_version || ctx.version || "未知"}`);
+    lines.push(`  ▸ Bridge 工作目录  : ${init?.cwd || ctx.cwd || "未知"}`);
+    lines.push(`  ▸ Bridge gateway   : ${ctx.gwId || "未知"}`);
+    lines.push(`  ▸ probe 链路       : ${init ? "✓ claude --print system/init 探测成功" : "✗ 探测超时, 检查 claude binary 是否安装"}`);
+    if (init) {
+      lines.push(`  ▸ 模型 / Mode      : ${init.model || "?"} / ${init.permissionMode || "?"}`);
+      lines.push(`  ▸ MCP / Agents     : ${init.mcp_servers?.length ?? 0} server / ${init.agents?.length ?? 0} agent`);
+      lines.push(`  ▸ Skills / Plugins : ${init.skills?.length ?? 0} skill / ${init.plugins?.length ?? 0} plugin`);
+      if (init.fast_mode_state) lines.push(`  ▸ fast_mode_state  : ${init.fast_mode_state}`);
+    }
+    lines.push("");
+    lines.push("更深的更新检查 / 配置语法校验请在本机终端跑 `claude doctor`(它会写");
+    lines.push("~/.claude/ 状态文件, 远程会话不触发避免污染本机配置)。");
+    return lines.join("\n");
+  },
+
+  "/export": () => [
+    "Claude Code 会话导出:",
+    "",
+    "  ▸ 远程会话天然存档 — 整段事件流在服务端 thread 里, App 聊天页可滚动",
+    "    查看历史, 长按消息可分享 / 复制。",
+    "  ▸ 本机磁盘上的 session jsonl 文件在 ~/.claude/projects/<cwd-hash>/<session>.jsonl,",
+    "    那是 claude --resume 用的内部状态, 不建议直接读。",
+    "  ▸ 想批量导出多个 thread 的对话, 后续可以在 App「我的」页加导出入口(目前没有)。",
+  ].join("\n"),
+
+  // /recap 已走 prompt-rewrite 真跑(P1#22)。
+
+  "/rename": () => [
+    "Claude Code 会话重命名:",
+    "",
+    "  ▸ 远程会话的标题在 App 聊天列表里, 长按对应对话条目即可重命名。",
+    "  ▸ 本机 REPL 的 `/rename` 改的是磁盘 session 文件名, 跟远程是两套独立存储。",
+  ].join("\n"),
+
+  "/feedback": () => [
+    "提交 Claude Code / 本远程会话反馈:",
+    "",
+    "  ▸ 直接在 App「我的」→「意见反馈」入口提交, 会带上 client 版本 + 当前",
+    "    thread/run id, 帮我们快速定位。",
+    "  ▸ Claude Code 本体 bug 也可以去 https://github.com/anthropics/claude-code/issues 报。",
+  ].join("\n"),
+
+  // /init /review /security-review 已移入 CLAUDE_CLI_HANDLED 透传真跑(P0 修复),
+  // 不再 bridge-synth。
+
+  // ── 兜底: 任何未列入的 slash 都给一段简短提示, 同时建议改用 App / 自然语言
+  __default__: (ctx, _args, command) => {
+    // probe 成功（_claudeProbeInit 非 null）且命令 miss → 明确告知「未知指令」
+    if (ctx?._claudeProbeInit !== null && ctx?._claudeProbeInit !== undefined) {
+      return `未知指令——当前主机的 Claude Code 中未找到 ${command}。`;
+    }
+    // probe 失败/超时（init = null），无法断言命令不存在 → 保留原有含糊兜底
+    return [
+      `「${command}」是 Claude Code CLI 的本机交互命令,`,
+      "在远程会话语境下没有等价 UI。",
+      "",
+      "替代做法:",
+      "  ▸ 直接用自然语言告诉 Claude 你想做什么,大部分 CLI 命令的功能都能",
+      "    通过对话完成(例如想看 git status,直接说「跑一下 git status」)。",
+      "  ▸ 系统级操作请去本机终端 `claude` 跑。",
+    ].join("\n");
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Codex synth — 所有 seed 命令保证有响应
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function synthesizeCodexSlashResponse(command, args, ctx) {
+  const handler = CODEX_HANDLERS[command];
+  if (handler) return await handler(ctx, args, command);
+  return await CODEX_HANDLERS.__default__(ctx, args, command);
+}
+
+const CODEX_HANDLERS = {
+  "/help": () => [
+    "Codex 远程会话命令清单(完整版, 全部走 bridge 合成):",
+    "",
+    "── 会话控制 ─────────────────────────────",
+    "  /clear /new       开新会话(真 evict MCP 进程, fresh codex session)",
+    "  /compact          上下文压缩(远程不支持, 用 /clear 替代)",
+    "  /resume /fork     续接/分叉说明",
+    "",
+    "── 信息查看 ─────────────────────────────",
+    "  /status           会话状态(model / cwd / approval / session id 等)",
+    "  /model            当前模型 + provider",
+    "  /cost             计费/用量说明",
+    "",
+    "── 权限 / 沙箱 / 审批 ────────────────────",
+    "  /permissions      权限 profile(file_system + network 真值)",
+    "  /sandbox          同 /permissions",
+    "  /approvals        审批策略(approval_policy + reviewer 真值)",
+    "",
+    "── 工具 / 扩展 ──────────────────────────",
+    "  /mcp              挂载的 MCP server 列表(真实)",
+    "  /agent            agent 配置说明",
+    "  /apps             apps 子系统说明",
+    "  /plugins          plugins 子系统说明",
+    "  /personality      personality 子系统说明",
+    "  /experimental     experimental flag 说明",
+    "",
+    "── 任务 / 控制 ──────────────────────────",
+    "  /plan             plan 模式说明",
+    "  /fast             fast 模式说明",
+    "  /ps               进程/任务列表说明",
+    "  /stop             停止当前任务说明",
+    "  /mention          @ 提及说明",
+    "  /init             生成 AGENTS.md 提示",
+    "  /diff             git diff 说明",
+    "  /review           代码评审说明",
+    "  /copy             复制说明",
+    "  /feedback         反馈入口",
+    "",
+    "  /help             显示本帮助",
+    "",
+    "用法: 输入框点「系统指令」chip 选, 或直接打 `/xxx`。",
+  ].join("\n"),
+
+  "/status": (ctx) => {
+    const cfg = ctx.sessionConfigured;
+    const lines = ["Codex 远程会话状态:"];
+    if (ctx.version) lines.push(`  codex CLI 版本    : ${ctx.version}`);
+    if (cfg?.model) lines.push(`  模型              : ${cfg.model}${cfg.model_provider_id ? ` (provider=${cfg.model_provider_id})` : ""}`);
+    else if (ctx.model) lines.push(`  模型              : ${ctx.model}`);
+    if (cfg?.cwd || ctx.cwd) lines.push(`  工作目录(cwd)     : ${cfg?.cwd || ctx.cwd}`);
+    if (cfg?.approval_policy) lines.push(`  审批策略          : ${cfg.approval_policy}`);
+    if (cfg?.reasoning_effort) lines.push(`  推理强度          : ${cfg.reasoning_effort}`);
+    if (ctx.gwId) lines.push(`  Bridge gateway id : ${ctx.gwId}`);
+    if (ctx.threadId) lines.push(`  对话 thread id    : ${ctx.threadId}`);
+    lines.push(`  codex session id  : ${cfg?.session_id || ctx.sessionId || "(尚未建立, 下一条消息时分配)"}`);
+    if (cfg?.captured_at) lines.push(`  数据采集时间      : ${cfg.captured_at}`);
+    if (!cfg) {
+      lines.push("");
+      lines.push("(尚无 codex MCP session_configured 数据 — 先发一条普通消息让");
+      lines.push(" bridge 启动 codex MCP, 再发 /status 就能看到 model / approval 真实配置。)");
+    }
+    return lines.join("\n");
+  },
+
+  "/cost": (ctx, args, cmd) => readCodexAuthCost(cmd || "/cost"),
+  // /usage: 跟 claude /usage 对齐, 显示 5h(primary) + weekly(secondary) 额度
+  "/usage": (ctx, args, cmd) => formatCodexUsage(ctx, cmd || "/usage"),
+
+  "/model": (ctx) => {
+    const cfg = ctx.sessionConfigured;
+    if (cfg?.model) {
+      const provider = cfg.model_provider_id ? ` (provider=${cfg.model_provider_id})` : "";
+      return `当前 Codex 模型: ${cfg.model}${provider}\n\n切换模型: 改 ~/.codex/config.toml 的 model 字段并重启 bridge, 或用 App 顶部「模型」入口。`;
+    }
+    if (ctx.model) return `当前 Codex 模型: ${ctx.model}\n\n切换模型: 改 ~/.codex/config.toml 后重启 bridge。`;
+    return "当前 Codex 模型未知(尚未与 codex MCP 建立 session)。先发一条普通消息触发 codex 启动, 然后再发 /model。";
+  },
+
+  "/version": async (ctx) => {
+    // 真起 `codex --version` 拿权威版本
+    const real = await execCliSafe("codex", ["--version"], { timeoutMs: 4000 });
+    if (real) return `Codex CLI 版本(实时):\n  ${real}`;
+    return ctx.version ? `Codex CLI ${ctx.version}` : "Codex CLI 版本未知";
+  },
+
+  "/permissions": (ctx) => formatCodexPermissions(ctx.sessionConfigured),
+  "/sandbox":     (ctx) => formatCodexPermissions(ctx.sessionConfigured),
+
+  "/approvals": (ctx) => {
+    const cfg = ctx.sessionConfigured;
+    if (!cfg) return "审批策略未知 — 尚未与 codex MCP 建立 session。先发一条普通消息触发 codex 启动,再发 /approvals。";
+    const lines = ["Codex 远程会话审批策略:"];
+    if (cfg.approval_policy) lines.push(`  策略         : ${cfg.approval_policy}`);
+    if (cfg.approvals_reviewer) lines.push(`  审批人       : ${cfg.approvals_reviewer}`);
+    lines.push("");
+    lines.push("策略说明:");
+    lines.push("  • on-request   — codex 主动请求时才弹审批");
+    lines.push("  • on-failure   — 命令失败时才请求审批");
+    lines.push("  • never        — 不需要审批(全自动)");
+    lines.push("  • untrusted    — 任何不受信操作都要审批");
+    lines.push("");
+    lines.push("修改: 编辑 ~/.codex/config.toml 的 approval_policy 后重启 bridge。");
+    return lines.join("\n");
+  },
+
+  "/mcp": async (ctx) => {
+    // 优先用 `codex mcp list` 真起 CLI 拿权威表格(列名: Name Command Args Env Cwd Status Auth)
+    const real = await execCliSafe("codex", ["mcp", "list"], { timeoutMs: 5000 });
+    if (real && real.length > 0) {
+      return [
+        "Codex MCP 服务器列表(实时, 来自 `codex mcp list`):",
+        "",
+        real,
+        "",
+        "管理: 在本机终端用 `codex mcp add <name> ...` / `codex mcp remove <name>`,",
+        "或编辑 ~/.codex/config.toml 的 [mcp_servers.<name>] 段后重启 bridge。",
+      ].join("\n");
+    }
+    // 退回到 sessionConfigured(运行中 MCP 进程上报)
+    const cfg = ctx.sessionConfigured;
+    if (cfg?.mcp_servers) {
+      const servers = cfg.mcp_servers;
+      const lines = ["Codex 当前运行的 MCP 服务器(来自 session_configured):"];
+      if (Array.isArray(servers)) {
+        if (servers.length === 0) return "codex 当前会话没挂载任何外部 MCP server。";
+        for (const s of servers) {
+          if (typeof s === "string") lines.push(`  • ${s}`);
+          else if (s && typeof s === "object") lines.push(`  • ${s.name || JSON.stringify(s)}`);
+        }
+        return lines.join("\n");
+      } else if (typeof servers === "object") {
+        const keys = Object.keys(servers);
+        if (keys.length === 0) return "codex 当前会话没挂载任何外部 MCP server。";
+        for (const k of keys) lines.push(`  • ${k}`);
+        return lines.join("\n");
+      }
+    }
+    return "codex 没挂载任何外部 MCP server, 也未与 codex MCP 建立 session。\n\n挂载: 本机执行 `codex mcp add <name> <cmd>` 或改 ~/.codex/config.toml。";
+  },
+
+  "/compact": () => [
+    "Codex 远程会话不支持 /compact:",
+    "",
+    "  ▸ codex MCP 协议没有暴露 compaction API, bridge 拿不到压缩接口。",
+    "  ▸ 上下文太长时, 请发 /clear 重新开始; 或在 App 聊天列表新建对话。",
+    "  ▸ 想保留关键信息: 先让 codex 总结一下当前对话, 复制摘要, /clear 后",
+    "    把摘要作为第一条消息粘进去。",
+  ].join("\n"),
+
+  "/init": () => [
+    "Codex /init(生成 AGENTS.md):",
+    "",
+    "  ▸ 远程会话不能直接写本机文件(codex MCP 在受限沙箱里)。",
+    "  ▸ 替代做法: 直接说「在 cwd 下生成一个 AGENTS.md, 描述项目结构 + 关键命令」,",
+    "    codex 会用文件写入工具搞定; 写入路径受 file_system 白名单约束(/permissions 看)。",
+    "  ▸ 想精准走交互模式 /init 流程: 本机终端 `codex` 进 TUI 后执行。",
+  ].join("\n"),
+
+  "/diff": () => [
+    "Codex /diff:",
+    "",
+    "  ▸ 远程会话不能直接显示 git diff UI。说「跑 git diff 把改动给我」,",
+    "    codex 会调 bash 工具执行 git 命令并把结果返回(受 file_system 白名单约束)。",
+    "  ▸ 想看 staged diff: 「跑 git diff --cached」; 想对比某 commit: 「跑 git diff HEAD~1」。",
+    "  ▸ 本机 `codex apply` 子命令能把 codex 上轮 diff 直接 git apply 到工作树。",
+  ].join("\n"),
+
+  "/review": () => [
+    "Codex 代码评审:",
+    "",
+    "  ▸ 远程会话: 直接说「帮我 review 最近的 git diff」或具体到某文件,",
+    "    codex 会读文件 / 跑 git 工具完成。",
+    "  ▸ 本机也可用 `codex review` 子命令做整仓评审(非交互, 适合 CI)。",
+  ].join("\n"),
+
+  "/resume": () => ({ __kind: "interrupt_session_pick" }),
+
+  "/fork": () => [
+    "Codex 分叉(fork)说明:",
+    "",
+    "  ▸ 在 App 聊天列表「新建对话」= fork 出新 codex session, 上下文不带过去。",
+    "  ▸ 想从某条历史消息分叉: 暂未直接支持, 可以复制那条消息文本到新对话作为开头。",
+    "  ▸ 本机 `codex fork` 子命令能从磁盘 session 分叉(远程不可用)。",
+  ].join("\n"),
+
+  "/plugins": async () => {
+    // codex 没有 `codex plugin list` 子命令(只有 marketplace),所以直接
+    // 解析 ~/.codex/config.toml 的 [plugins.<name>] 段拿真实状态。
+    const cfgPath = join(homedir(), ".codex", "config.toml");
+    let body;
+    try {
+      body = readFileSync(cfgPath, "utf8");
+    } catch (err) {
+      return [
+        "Codex 插件状态: 无法读取 ~/.codex/config.toml",
+        `  原因: ${err?.message || err}`,
+        "",
+        "如果你没用过 codex, 这是正常的(config 在首次登录时生成)。",
+      ].join("\n");
+    }
+    // 找所有形如 [plugins."xxx"] 或 [plugins.xxx] 的段
+    const headerRe = /^\[plugins\.(?:"([^"]+)"|([\w.-]+))\]\s*$/gm;
+    const plugins = [];
+    let m;
+    while ((m = headerRe.exec(body)) !== null) {
+      const name = m[1] || m[2];
+      // 找紧跟在 header 后面的 enabled = true/false
+      const startIdx = m.index + m[0].length;
+      // 截取到下一个 [ 或文件末尾
+      const nextHeader = body.indexOf("\n[", startIdx);
+      const sectionBody = body.slice(startIdx, nextHeader < 0 ? body.length : nextHeader);
+      const enabledMatch = /^\s*enabled\s*=\s*(true|false)/m.exec(sectionBody);
+      plugins.push({
+        name,
+        enabled: enabledMatch ? enabledMatch[1] === "true" : null,
+      });
+    }
+    if (plugins.length === 0) {
+      return [
+        "Codex 插件: 当前没有安装任何插件。",
+        "",
+        "安装方式(本机终端): `codex plugin marketplace add <owner/repo>` 添加 marketplace,",
+        "然后用 codex desktop app 或 TUI 启用具体插件。",
+        "",
+        `配置文件: ${cfgPath}(查找 [plugins.*] 段)`,
+      ].join("\n");
+    }
+    const lines = [`Codex 插件列表(实时, 来自 ${cfgPath}):`, ""];
+    for (const p of plugins) {
+      const status = p.enabled === null ? "?" : (p.enabled ? "✓ enabled" : "✗ disabled");
+      lines.push(`  ${status.padEnd(12)} ${p.name}`);
+    }
+    lines.push("");
+    lines.push("管理: codex desktop app 内启用/禁用, 或直接改 config.toml 后重启 bridge。");
+    return lines.join("\n");
+  },
+
+  "/agent": () => [
+    "Codex Agent 配置:",
+    "",
+    "  ▸ codex 的 agent 行为由 ~/.codex/config.toml 控制(model / approval /",
+    "    sandbox / reasoning_effort 等), bridge 启动时一次性载入。",
+    "  ▸ 改后重启 bridge 生效。当前实际配置看 /status 和 /permissions。",
+    "  ▸ 高级 agent profile(switch 不同任务的 model+sandbox 组合)走本机 codex TUI。",
+  ].join("\n"),
+
+  "/apps": () => [
+    "Codex Apps:",
+    "",
+    "  ▸ codex apps 是 OpenAI 生态里跨工具的应用容器,在 codex desktop app 里管理,",
+    "    远程会话(bridge 模式)看不到 apps 状态。",
+    "  ▸ 本机执行 `codex app` 进 desktop app 入口。",
+  ].join("\n"),
+
+  "/personality": () => [
+    "Codex Personality:",
+    "",
+    "  ▸ personality 控制 codex 的回复风格(简洁/详尽/学究等),配置在 codex desktop",
+    "    app 或 ~/.codex/config.toml。",
+    "  ▸ 远程会话用当前配置, 想临时改风格直接说「以后回答都简短点」即可,",
+    "    codex 会按指令调整, 等价于设了 personality。",
+  ].join("\n"),
+
+  "/experimental": async () => {
+    // 真起 `codex features list` 拿权威列表(每行: <name> <stage> <enabled>)
+    const real = await execCliSafe("codex", ["features", "list"], { timeoutMs: 5000 });
+    if (real && real.length > 0) {
+      return [
+        "Codex 实验性特性(实时, 来自 `codex features list`):",
+        "",
+        real,
+        "",
+        "管理: `codex features enable <name>` / `codex features disable <name>`,",
+        "或编辑 ~/.codex/config.toml 的 [features] 段后重启 bridge。",
+      ].join("\n");
+    }
+    return [
+      "Codex 实验性特性: 当前 codex CLI 未返回 feature 列表(可能未登录或 binary 版本不支持)。",
+      "",
+      "查看: 本机 `codex features list`。",
+      "管理: `codex features enable <name>` / `codex features disable <name>`,",
+      "或编辑 ~/.codex/config.toml 的 [features] 段后重启 bridge。",
+    ].join("\n");
+  },
+
+  "/plan": () => [
+    "Codex Plan 模式:",
+    "",
+    "  ▸ Plan 模式让 codex 先输出多步骤计划, 再逐步执行。远程会话 codex 在",
+    "    multi-step 任务里会自动生成 turn/plan/updated 事件(App 顶部 todo 面板",
+    "    展示)。",
+    "  ▸ 强制开 plan 模式: 直接说「先给我一个 plan, 不要立即动手」, codex 会按",
+    "    plan 流程走。",
+    "  ▸ 本机 TUI 的 /plan 切换按钮在远程没有 UI 入口, 用对话指令即可。",
+  ].join("\n"),
+
+  "/fast": () => [
+    "Codex Fast 模式:",
+    "",
+    "  ▸ Fast 模式降低 reasoning_effort 提速。当前 reasoning_effort 看 /status。",
+    "  ▸ 想临时切到 fast: 直接说「这次任务用最快档,别想太多」, codex 会自动调整;",
+    "    或改 ~/.codex/config.toml 的 reasoning_effort = \"low\" 后重启 bridge。",
+  ].join("\n"),
+
+  "/ps": () => [
+    "Codex 任务进程列表:",
+    "",
+    "  ▸ codex 本机 TUI 的 /ps 列出后台跑的 task,远程会话 bridge 是单 turn 模型",
+    "    (turn 完即返回), 没有后台 task 概念。",
+    "  ▸ 想看 bridge 上跑过的 turn 历史: 滚动 App 聊天页向上看。",
+    "  ▸ 想看 codex 本机历史 session: 本机 `codex resume` 或 `codex ls`。",
+  ].join("\n"),
+
+  "/stop": () => [
+    "Codex /stop:",
+    "",
+    "  ▸ 远程会话停止当前 run: App 聊天页输入框右侧停止按钮(streaming 时显示)。",
+    "  ▸ 等价 codex 内部的 abort 事件, bridge 会把 turn 取消并清理。",
+    "  ▸ 强制关掉整个 codex MCP 进程: 发 /clear, bridge 会 evict MCP 并下一条消息开新会话。",
+  ].join("\n"),
+
+  "/mention": () => [
+    "Codex /mention(@ 引用):",
+    "",
+    "  ▸ codex 本机 TUI 的 /mention 用于 @ 文件 / 符号, 给上下文加锚点。",
+    "  ▸ 远程会话: 直接在消息里写文件路径(`src/foo.ts`) / 函数名, codex 会自动",
+    "    用 Read / Grep 工具去找。",
+  ].join("\n"),
+
+  "/copy": () => [
+    "Codex /copy(复制):",
+    "",
+    "  ▸ codex 本机 TUI 的 /copy 把上轮回复拷到剪贴板。",
+    "  ▸ 远程会话: App 聊天页长按消息有「复制」选项。",
+  ].join("\n"),
+
+  "/feedback": () => [
+    "提交 Codex / 本远程会话反馈:",
+    "",
+    "  ▸ App「我的」→「意见反馈」入口提交, 会带上 codex 版本 + 当前 thread/run id,",
+    "    帮我们快速定位。",
+    "  ▸ Codex 本体 bug 也可以去 https://github.com/openai/codex/issues 报。",
+  ].join("\n"),
+
+  // 兜底
+  __default__: (_ctx, _args, command) => [
+    `「${command}」是 Codex CLI 的本机交互命令, 远程会话受 codex MCP 协议限制,`,
+    "没有等价的 UI 入口。",
+    "",
+    "替代做法:",
+    "  ▸ 直接用自然语言告诉 codex 你想做什么(大部分 CLI 命令的功能都能通过对话完成,",
+    "    比如「跑 git status」「读 src/foo.ts 第 20 行」「装 ABC npm 包」)。",
+    "  ▸ 系统级 / 配置类操作请去本机终端 `codex` 跑。",
+  ].join("\n"),
+};
+
+/**
+ * Codex /usage — 跟 claude /usage 对齐, 显示 5h(primary) + weekly(secondary) 配额。
+ * 数据源优先级:
+ *   1. ctx.rateLimits — 当前 thread 在 codex MCP 跑过至少一轮后捕获的最新 rate_limits
+ *      (来自 codex/event msg.type=token_count, 跟 codex 跟 OpenAI 拉到的同一份)
+ *   2. ~/.codex/sessions/<最近 jsonl>/event_msg.token_count.rate_limits — fallback,
+ *      bridge 刚启 / 当前 thread 还没跑过 turn 时, 读本机最近一次 codex 跑的会话
+ *      jsonl 拿最新一条 rate_limits(可能稍旧, 但比"未知"强)
+ */
+function formatCodexUsage(ctx, command) {
+  let rl = ctx.rateLimits || null;
+  let source = "当前 thread 实时";
+  if (!rl) {
+    rl = readLatestCodexRateLimits();
+    if (rl) source = "本机最近一次 codex 会话(可能不是最新)";
+  }
+  if (!rl) {
+    return [
+      `Codex ${command}: 还没探到 rate_limits 数据。`,
+      "",
+      "  ▸ 远程会话: 先在当前 thread 发一条普通消息让 codex MCP 跑一轮, 再发 /usage,",
+      "    bridge 会从 codex/event token_count 抓 5h + weekly 额度。",
+      "  ▸ 本机: 在终端跑 `codex` 进 TUI 跑一轮 turn 也行(会写 ~/.codex/sessions/),",
+      "    bridge 下次 /usage 就能从最近 jsonl 里 fallback 读到。",
+    ].join("\n");
+  }
+  const lines = [`Codex ${command}(实时, ${source}):`];
+  if (rl.plan_type) lines.push(`  套餐         : ${rl.plan_type}`);
+  if (rl.primary) {
+    const window = rl.primary.window_minutes;
+    const label = window === 300 ? "5h 滚动窗口  " : `${window} 分钟窗口`;
+    const pct = rl.primary.used_percent;
+    let line = `  ${label}: 用量 ${pct}%`;
+    if (rl.primary.resets_at) line += `, ${formatResetsRelative(rl.primary.resets_at)} 后重置`;
+    lines.push(line);
+  }
+  if (rl.secondary) {
+    const window = rl.secondary.window_minutes;
+    const label = window === 10080 ? "weekly 窗口  " : `${window} 分钟窗口`;
+    const pct = rl.secondary.used_percent;
+    let line = `  ${label}: 用量 ${pct}%`;
+    if (rl.secondary.resets_at) line += `, ${formatResetsRelative(rl.secondary.resets_at)} 后重置`;
+    lines.push(line);
+  }
+  if (rl.credits) {
+    if (rl.credits.unlimited) lines.push("  额外信息     : 无限额度");
+    else if (rl.credits.has_credits) lines.push(`  额外信息     : 有 credit 余额 ${rl.credits.balance ?? "未知"}`);
+  }
+  if (rl.rate_limit_reached_type) lines.push(`  已触达限制   : ${rl.rate_limit_reached_type}`);
+  if (rl.captured_at) lines.push(`  数据采集时间 : ${rl.captured_at}`);
+  lines.push("");
+  lines.push("(数据来自 codex MCP 的 token_count 事件, 跟 codex 自己跟 OpenAI 拉到的是同一份。");
+  lines.push(" 精确明细: console.openai.com/usage 网页查。)");
+  return lines.join("\n");
+}
+
+/**
+ * 读 ~/.codex/sessions/ 下最近一条 jsonl, 从最后往前找 event_msg.token_count.rate_limits。
+ * Fallback 用, 在 bridge 没活体捕获时给个"虽然旧但真"的数据。
+ */
+function readLatestCodexRateLimits() {
+  try {
+    const sessionsDir = join(homedir(), ".codex", "sessions");
+    // 按时间戳新到旧扫(目录格式: yyyy/mm/dd/), 一次只读一份
+    const newestFile = findNewestCodexSession(sessionsDir);
+    if (!newestFile) return null;
+    const body = readFileSync(newestFile, "utf8");
+    const lines = body.split("\n");
+    // 从后往前找 token_count
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i].trim();
+      if (!line) continue;
+      if (!line.includes('"rate_limits"')) continue;
+      try {
+        const obj = JSON.parse(line);
+        const payload = obj?.payload;
+        if (payload?.type === "token_count" && payload.rate_limits) {
+          return {
+            ...payload.rate_limits,
+            captured_at: obj.timestamp || null,
+          };
+        }
+      } catch { /* skip */ }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function findNewestCodexSession(rootDir) {
+  try {
+    // 递归到最深一级取 mtime 最新的 .jsonl
+    const stack = [rootDir];
+    let best = null;
+    let bestMtime = 0;
+    while (stack.length) {
+      const dir = stack.pop();
+      let entries;
+      try { entries = readdirSync(dir); } catch { continue; }
+      for (const name of entries) {
+        const full = join(dir, name);
+        let st;
+        try { st = statSync(full); } catch { continue; }
+        if (st.isDirectory()) {
+          stack.push(full);
+        } else if (name.endsWith(".jsonl")) {
+          const mt = st.mtimeMs;
+          if (mt > bestMtime) { bestMtime = mt; best = full; }
+        }
+      }
+    }
+    return best;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 解析 ~/.codex/auth.json 的 id_token JWT, 拿订阅状态 / 计费方式 / 套餐类型。
+ * 真实数据(codex 自己读这份文件判 plan), 不是合成模板。
+ */
+function readCodexAuthCost(command) {
+  const authPath = join(homedir(), ".codex", "auth.json");
+  let auth;
+  try {
+    auth = JSON.parse(readFileSync(authPath, "utf8"));
+  } catch (err) {
+    return [
+      `Codex ${command}: 无法读取 ${authPath}`,
+      `  原因: ${err?.message || err}`,
+      "",
+      "如果你没登录 codex, 先在本机跑 `codex login`。",
+    ].join("\n");
+  }
+  const lines = [`Codex ${command}(实时, 来自 ~/.codex/auth.json):`];
+  if (auth.auth_mode) lines.push(`  ▸ 认证方式      : ${auth.auth_mode}`);
+  // 解 JWT id_token 拿 chatgpt_plan_type / subscription_active_until / email
+  const idToken = auth?.tokens?.id_token;
+  if (typeof idToken === "string") {
+    const payload = decodeJwtPayload(idToken);
+    const chatgpt = payload && payload["https://api.openai.com/auth"];
+    if (chatgpt) {
+      if (chatgpt.chatgpt_plan_type) lines.push(`  ▸ ChatGPT 套餐  : ${chatgpt.chatgpt_plan_type}`);
+      if (chatgpt.chatgpt_subscription_active_until) {
+        const until = chatgpt.chatgpt_subscription_active_until;
+        lines.push(`  ▸ 订阅到期      : ${until}`);
+      }
+      if (chatgpt.chatgpt_subscription_last_checked) {
+        lines.push(`  ▸ 上次校验时间  : ${chatgpt.chatgpt_subscription_last_checked}`);
+      }
+      if (Array.isArray(chatgpt.organizations) && chatgpt.organizations.length > 0) {
+        const org = chatgpt.organizations[0];
+        lines.push(`  ▸ 组织 / 角色   : ${org.title || org.id} / ${org.role || "?"}`);
+      }
+    }
+    if (payload?.email) lines.push(`  ▸ 登录账号      : ${payload.email}`);
+  }
+  if (auth.last_refresh) lines.push(`  ▸ 令牌刷新时间  : ${auth.last_refresh}`);
+  lines.push("");
+  lines.push("说明: codex MCP 协议没暴露按 turn 的 token / USD 明细, 这里给的是");
+  lines.push("订阅 / 计费方式总览 —— 跟 codex CLI 自己读的是同一份 auth.json。");
+  lines.push("精确明细: console.openai.com/usage (网页登录后看)。");
+  return lines.join("\n");
+}
+
+/**
+ * 解 JWT 中间段(payload), 不验签, 仅用于读取声明字段。失败返回 null。
+ */
+function decodeJwtPayload(token) {
+  try {
+    const parts = token.split(".");
+    if (parts.length < 2) return null;
+    // base64url → base64
+    const b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    // 补 padding
+    const padded = b64 + "=".repeat((4 - (b64.length % 4)) % 4);
+    return JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hermes synth — 仅覆盖 bridge 真有数据的命令
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// Bridge 状态可用:
+//   ctx.model         pre.model
+//   ctx.apiBaseUrl    pre.apiBaseUrl (LLM endpoint)
+//   ctx.backend       "http"/"command"/"responses"
+//   ctx.cwd, ctx.gwId, ctx.threadId
+//   ctx.historyFn     async () => [{user, assistant}, ...] (从 sessionStore)
+//   ctx.usageStats    { tokens, cost, turns } (从 usageReporter)
+//
+// 不支持的命令(/undo /retry /branch /title /steer /queue /yolo /reasoning /fast
+// /verbose /personality /compress /sessions /save /reload-* /tools /skills /agents)
+// 走 __default__ 兜底, 解释为什么远程拿不到 + 怎么替代。
+async function synthesizeHermesSlashResponse(command, args, ctx) {
+  const handler = HERMES_HANDLERS[command];
+  if (handler) return await handler(ctx, args, command);
+  return await HERMES_HANDLERS.__default__(ctx, args, command);
+}
+
+const HERMES_HANDLERS = {
+  "/help": (ctx) => [
+    "Hermes 远程会话支持的系统指令(bridge 有真实数据可合成):",
+    "",
+    "  /clear /new    清除当前对话上下文",
+    "  /status        会话状态(model/cwd/backend/history 长度)",
+    "  /usage         token / cost 用量(由 bridge usageReporter 累计)",
+    "  /model         当前模型 + LLM endpoint",
+    "  /version       bridge 版本",
+    "  /history       本会话历史 turn 列表",
+    "  /save          导出会话历史到 JSON",
+    "  /stop          停止当前回合(用 App 输入框旁边的停止键即可)",
+    "  /help          显示本帮助",
+    "",
+    "Hermes 其它官方命令(/undo /retry /branch /rollback /steer /queue /title",
+    "/sessions /personality /reasoning /fast /verbose /yolo /compress /reload-*",
+    "/tools /skills /agents) 远程会话拿不到对应数据, 在本机 `hermes` TUI 用。",
+  ].join("\n"),
+
+  "/status": async (ctx) => {
+    const lines = ["Hermes 远程会话状态:"];
+    if (ctx.model) lines.push(`  当前模型     : ${ctx.model}`);
+    if (ctx.apiBaseUrl) lines.push(`  LLM endpoint : ${ctx.apiBaseUrl}`);
+    if (ctx.backend) lines.push(`  backend      : ${ctx.backend}`);
+    if (ctx.cwd) lines.push(`  cwd          : ${ctx.cwd}`);
+    if (ctx.gwId) lines.push(`  gateway id   : ${ctx.gwId}`);
+    if (ctx.threadId) lines.push(`  thread id    : ${ctx.threadId}`);
+    if (typeof ctx.historyFn === "function") {
+      try {
+        const hist = await ctx.historyFn();
+        const turns = Array.isArray(hist) ? hist.length / 2 : 0;
+        lines.push(`  历史 turn 数 : ${Math.floor(turns)}`);
+      } catch { /* ignore */ }
+    }
+    return lines.join("\n");
+  },
+
+  "/usage": (ctx) => {
+    const u = ctx.usageStats;
+    const lines = ["Hermes 远程会话用量(bridge 累计):"];
+    if (u?.tokens) {
+      lines.push(`  输入 token   : ${u.tokens.input ?? 0}`);
+      lines.push(`  输出 token   : ${u.tokens.output ?? 0}`);
+      lines.push(`  缓存 input   : ${u.tokens.cached_input ?? 0}`);
+      lines.push(`  推理 output  : ${u.tokens.reasoning_output ?? 0}`);
+      lines.push(`  累计 total   : ${u.tokens.total ?? 0}`);
+    } else {
+      lines.push("  本次 bridge 启动后还没积累 token 数据。");
+    }
+    if (u?.cost) {
+      if (u.cost.total_usd) lines.push(`  累计 USD     : $${Number(u.cost.total_usd).toFixed(4)}`);
+      if (u.cost.turns) lines.push(`  累计 turn 数 : ${u.cost.turns}`);
+      if (u.cost.duration_ms) lines.push(`  累计耗时(ms) : ${u.cost.duration_ms}`);
+    }
+    lines.push("");
+    lines.push("(注意: bridge 重启会清零, 这只是当前进程内的累计。");
+    lines.push(" 账户级总用量请去对应 LLM provider 后台查。)");
+    return lines.join("\n");
+  },
+
+  "/model": (ctx) => {
+    const lines = ["Hermes 当前模型配置:"];
+    if (ctx.model) lines.push(`  模型 id      : ${ctx.model}`);
+    if (ctx.apiBaseUrl) lines.push(`  LLM endpoint : ${ctx.apiBaseUrl}`);
+    if (ctx.backend) lines.push(`  backend 类型 : ${ctx.backend}`);
+    lines.push("");
+    lines.push("切换模型: 编辑 ~/.hermes/.env 的 HERMES_BRIDGE_MODEL 字段后重启 bridge,");
+    lines.push("或用 App 顶部「模型」入口(如果支持)。");
+    return lines.join("\n");
+  },
+
+  "/version": (ctx) => {
+    return ctx.version
+      ? `Hermes bridge 版本: ${ctx.version}`
+      : "Hermes bridge 版本未知(bridge 未上报)";
+  },
+
+  "/history": async (ctx) => {
+    if (typeof ctx.historyFn !== "function") {
+      return "Hermes 会话历史: bridge 未注入 historyFn, 无法读取。";
+    }
+    let hist;
+    try { hist = await ctx.historyFn(); } catch (err) {
+      return `Hermes 会话历史: 读取失败 — ${err?.message || err}`;
+    }
+    if (!Array.isArray(hist) || hist.length === 0) {
+      return "Hermes 会话历史: 当前还没有任何 turn(本 bridge 启动后)。";
+    }
+    const lines = [`Hermes 会话历史(${Math.floor(hist.length / 2)} 个 turn):`, ""];
+    let turnIdx = 0;
+    for (let i = 0; i < hist.length; i++) {
+      const m = hist[i];
+      const role = m?.role;
+      if (role !== "user" && role !== "assistant") continue;
+      if (role === "user") turnIdx += 1;
+      const tag = role === "user" ? `[User #${turnIdx}]` : `[Hermes #${turnIdx}]`;
+      const text = typeof m.content === "string" ? m.content : "";
+      const preview = text.length > 200 ? text.slice(0, 200) + "…" : text;
+      lines.push(`${tag} ${preview}`);
+      if (lines.length > 40) { lines.push("…(更多 turn 省略)"); break; }
+    }
+    return lines.join("\n");
+  },
+
+  "/save": async (ctx) => {
+    if (typeof ctx.historyFn !== "function") {
+      return "Hermes /save: bridge 没注入 historyFn, 无法导出。";
+    }
+    let hist;
+    try { hist = await ctx.historyFn(); } catch (err) {
+      return `Hermes /save 失败: ${err?.message || err}`;
+    }
+    if (!Array.isArray(hist) || hist.length === 0) {
+      return "Hermes /save: 当前会话还没有任何 turn 可保存。";
+    }
+    // 写到 /tmp/hermes-session-<gwId>-<timestamp>.json
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const fname = `/tmp/hermes-session-${ctx.gwId || "unknown"}-${ts}.json`;
+    try {
+      const fs = await import("node:fs/promises");
+      await fs.writeFile(fname, JSON.stringify({
+        gw_id: ctx.gwId, thread_id: ctx.threadId, model: ctx.model,
+        saved_at: new Date().toISOString(), history: hist,
+      }, null, 2), "utf8");
+      return [
+        `Hermes 会话已导出到本机:`,
+        `  ${fname}`,
+        `  共 ${Math.floor(hist.length / 2)} 个 turn`,
+      ].join("\n");
+    } catch (err) {
+      return `Hermes /save: 写文件失败 — ${err?.message || err}`;
+    }
+  },
+
+  "/resume": () => ({ __kind: "interrupt_session_pick" }),
+
+  "/stop": () => [
+    "Hermes /stop: 远程会话停止当前回合的方式 —",
+    "",
+    "  ▸ App 聊天页输入框右侧, AI 在打字时会显示「停止」按钮, 点它即可。",
+    "  ▸ bridge 收到停止信号会取消当前 LLM 请求并清理。",
+    "  ▸ 在对话里发 /stop 文本本身不停 — 因为消息要先发出去才会被读到, 那时回合",
+    "    已经在跑了。",
+  ].join("\n"),
+
+  // 兜底: 不支持的命令简短说明 + 替代做法
+  __default__: (_ctx, _args, command) => [
+    `「${command}」远程 Hermes 会话没有等价行为(bridge 是 thin LLM wrapper,`,
+    "没有 hermes-agent 的会话状态机)。",
+    "",
+    "想要这种功能, 在装了 `hermes` 的本机终端跑该命令。",
+    "远程可用的命令: /clear /new /status /usage /model /version /history /save",
+    "/stop /help。",
+  ].join("\n"),
+};
+
+function formatResetsRelative(resetsAt) {
+  if (!Number.isFinite(resetsAt)) return "(未知时间)";
+  const diffMs = (resetsAt * 1000) - Date.now();
+  if (diffMs <= 0) return "已重置";
+  const mins = Math.round(diffMs / 60000);
+  if (mins < 60) return `${mins} 分钟`;
+  const h = Math.floor(mins / 60), m = mins % 60;
+  return m === 0 ? `${h} 小时` : `${h} 小时 ${m} 分钟`;
+}
+
+function formatCodexPermissions(cfg) {
+  if (!cfg) return "权限/沙箱配置未知 — 尚未与 codex MCP 建立 session。先发一条普通消息触发 codex 启动, 然后再发 /permissions 即可看到真实配置。";
+  const lines = ["Codex 远程会话权限 / 沙箱:"];
+  const ap = cfg.active_permission_profile;
+  if (ap?.id) lines.push(`  激活 profile      : ${ap.id}`);
+  const pp = cfg.permission_profile;
+  if (pp?.type) lines.push(`  permission 类型   : ${pp.type}`);
+  if (pp?.file_system) {
+    lines.push(`  文件系统:`);
+    const fs = pp.file_system;
+    if (fs.type) lines.push(`    访问模式        : ${fs.type}`);
+    const entries = Array.isArray(fs.entries) ? fs.entries : [];
+    if (entries.length > 0) {
+      lines.push(`    白名单(${entries.length} 条):`);
+      for (const e of entries.slice(0, 10)) {
+        const p = e?.path;
+        const pathDisp = p?.type === "special" ? `<${p.value?.kind || "?"}>` : (p?.value || String(p || "?"));
+        lines.push(`      - ${pathDisp}  (${e?.access || "?"})`);
+      }
+      if (entries.length > 10) lines.push(`      ... 还有 ${entries.length - 10} 条`);
+    }
+  }
+  if (pp?.network) lines.push(`  网络访问          : ${pp.network}`);
+  if (cfg.approval_policy) lines.push(`  审批策略          : ${cfg.approval_policy}`);
+  if (cfg.approvals_reviewer) lines.push(`  审批人            : ${cfg.approvals_reviewer}`);
+  lines.push("");
+  lines.push("(数据由 bridge 在 codex MCP 启动时从 `session_configured` 事件读取,");
+  lines.push(" 是 codex CLI 真实活体状态, 不是合成模板。)");
+  return lines.join("\n");
+}
+
+/**
+ * 给 handleRequest 的 onChunk 用的便捷封装。
+ */
+export async function emitAssistantText(onChunk, text) {
+  if (!text) {
+    await onChunk({ event: "response.completed" });
+    return;
+  }
+  await onChunk({ event: "response.output_text.delta", delta: text });
+  await onChunk({ event: "response.completed" });
+}