im-agent 0.1.1 → 0.2.1

package/README.md

@@ -48,7 +48,7 @@ im-agent service install
 | `im-agent service install \| uninstall \| restart \| status` | 开机自启 |
 | `im-agent doctor` | 体检 |
 
-聊天里的命令（飞书和 Web 通用）：`/new` `/fork` `/sessions [all]` `/resume <id>` `/model [名称]` `/effort <程度>` `/agent [名称]`（或者直接发 `/claude`、`/codex`）`/stop` `/cd <目录>` `/pwd` `/status` `/approve <id> allow-once|allow-always|deny` `/help`
+聊天里的命令（飞书和 Web 通用；Web 输入框打 `/` 会弹出命令补全，飞书里打 `/` 会弹出机器人的指令面板（im-agent 自动注册，约 5～8 分钟生效；只发一个 `/` 也会回一张可点击的命令卡片），顺序和显示项在 设置 → 命令 里调整）：`/new` `/fork` `/sessions [all]` `/resume <id>` `/model [名称]` `/effort <程度>` `/agent [名称]`（或者直接发 `/claude`、`/codex`）`/stop` `/cd <目录>` `/pwd` `/status` `/approve <id> allow-once|allow-always|allow-session|deny` `/help`
 
 ## 安全
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "im-agent",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "type": "module",
   "description": "把飞书（以及以后的 Telegram 等）和 Web 页面桥接到本机 Claude Code / Codex：聊天驱动、卡片审批、会话与模型切换",
   "keywords": [

package/src/agents/claude/account.ts

@@ -0,0 +1,100 @@
+// 账号额度：Claude 订阅的 5 小时 / 7 天用量窗口，和 Codex 那边的 account.ts 对齐。
+//
+// 数据来自 SDK 的 usage 控制请求 —— 也就是 Claude Code 里 `/usage` 背后的那份结构化数据，
+// 通过探针 query 读取（见 probe.ts）。
+//
+// 注意：SDK 把它标成了 EXPERIMENTAL，方法名以后会改。改了的话这里只会读失败，
+// /status 少几行而已，不影响别的。
+import { cachedProbe, withProbe } from "./probe.js";
+
+type Window = { utilization: number | null; resets_at: string | null } | null | undefined;
+
+type LimitRow = {
+  kind: string;
+  group: string;
+  percent: number;
+  resets_at: string | null;
+  severity?: string;
+  scope?: { model?: { display_name: string } | null; surface?: { display_name: string } | null } | null;
+};
+
+export type ClaudeUsage = {
+  subscriptionType: string | null;
+  rows: { label: string; percent: number; resetsAt: string | null; severity?: string }[];
+};
+
+function labelOf(row: LimitRow): string {
+  const scope = row.scope?.model?.display_name || row.scope?.surface?.display_name;
+  const base = row.kind === "session" ? "5 小时" : row.group === "weekly" ? "7 天" : row.kind;
+  return scope ? `${base}（${scope}）` : base;
+}
+
+function normalize(res: {
+  subscription_type: string | null;
+  rate_limits_available: boolean;
+  rate_limits: Record<string, unknown> | null;
+}): ClaudeUsage | null {
+  if (!res.rate_limits_available || !res.rate_limits) return null;
+  const rl = res.rate_limits;
+  const limits = rl.limits as LimitRow[] | null | undefined;
+  let rows: ClaudeUsage["rows"];
+  if (Array.isArray(limits)) {
+    // 新版服务端直接给出要显示哪些行、什么顺序，照单全收
+    rows = limits.map((r) => ({
+      label: labelOf(r),
+      percent: r.percent,
+      resetsAt: r.resets_at,
+      ...(r.severity ? { severity: r.severity } : {}),
+    }));
+  } else {
+    // 老格式兜底：只认两个主窗口
+    rows = [];
+    for (const [key, label] of [
+      ["five_hour", "5 小时"],
+      ["seven_day", "7 天"],
+    ] as const) {
+      const w = rl[key] as Window;
+      if (w && w.utilization != null) rows.push({ label, percent: w.utilization, resetsAt: w.resets_at });
+    }
+  }
+  return { subscriptionType: res.subscription_type, rows };
+}
+
+async function fetchUsage(): Promise<ClaudeUsage | null> {
+  const res = await withProbe((q) =>
+    q.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET({ skipBehaviors: true }),
+  );
+  return normalize(res as Parameters<typeof normalize>[0]);
+}
+
+/**
+ * 同 Codex：缓存 60 秒，挡住连敲几次 /status，又不至于数字明显过期。
+ * 读不到额度不该让整条 /status 失败 —— 它只是其中几行，所以失败时给 null。
+ */
+export const readUsage = cachedProbe(60_000, "额度", fetchUsage, null);
+
+/** 距离重置还有多久，和 Codex 那边同一个说法 */
+function untilReset(resetsAt: string | null, now = Date.now()): string {
+  if (!resetsAt) return "";
+  const ms = Date.parse(resetsAt);
+  if (Number.isNaN(ms)) return "";
+  const seconds = Math.floor((ms - now) / 1000);
+  if (seconds <= 0) return "即将重置";
+  const days = Math.floor(seconds / 86400);
+  const hours = Math.floor((seconds % 86400) / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  if (days > 0) return `${days} 天 ${hours} 小时后重置`;
+  if (hours > 0) return `${hours} 小时 ${minutes} 分后重置`;
+  return `${minutes} 分钟后重置`;
+}
+
+/** 渲染成 /status 里的几行；没有可显示的就返回空数组（API key / Bedrock 之类没有订阅额度） */
+export function describeUsage(usage: ClaudeUsage | null, now = Date.now()): string[] {
+  if (!usage || usage.rows.length === 0) return [];
+  const rows = usage.rows.map((r) => {
+    const reset = untilReset(r.resetsAt, now);
+    return `  ${r.label}　已用 ${Math.round(r.percent)}%${reset ? `　${reset}` : ""}`;
+  });
+  if (usage.rows.some((r) => r.percent >= 100)) rows.push("  ⚠️ 已达上限，等窗口重置后才能继续");
+  return [`额度${usage.subscriptionType ? `（${usage.subscriptionType}）` : ""}`, ...rows];
+}

package/src/agents/claude/driver.ts

@@ -7,6 +7,8 @@ import {
   getSessionMessages,
   listSessions,
 } from "@anthropic-ai/claude-agent-sdk";
+import os from "node:os";
+import type { AgentCommand } from "../../core/command-catalog.js";
 import { config } from "../../core/config.js";
 import type {
   AgentDriver,
@@ -19,8 +21,43 @@ import type {
   SessionOptions,
   SessionSummary,
 } from "../../core/types.js";
+import { describeUsage, readUsage } from "./account.js";
+import { cachedProbe, withProbe } from "./probe.js";
 import { diagnose } from "./errors.js";
-import { ClaudeSession, describeToolUse, summarize } from "./session.js";
+import { ClaudeSession, describeToolUse, summarize, toModelInfo } from "./session.js";
+
+/** 模型列表几乎不变，缓存 10 分钟；读失败抛给设置页，让它退回手填 */
+const readCatalog = cachedProbe(10 * 60_000, "模型列表", () => withProbe(async (q) => toModelInfo(await q.supportedModels())));
+
+/**
+ * 斜杠命令（skills、/compact 这些）。项目目录里可能有自己的命令，所以按 cwd 分开缓存；
+ * 装了新 skill 最多 5 分钟后出现。读不到就只显示 im-agent 自己的命令。
+ */
+const commandReaders = new Map<string, () => Promise<AgentCommand[]>>();
+function readCommands(cwd: string): Promise<AgentCommand[]> {
+  let reader = commandReaders.get(cwd);
+  if (!reader) {
+    // 目录数量一般很少；万一很多，丢掉最早的，别无限涨
+    if (commandReaders.size >= 50) commandReaders.delete(commandReaders.keys().next().value!);
+    reader = cachedProbe(
+      5 * 60_000,
+      "Claude 命令列表",
+      () =>
+        withProbe(
+          async (q) =>
+            (await q.supportedCommands()).map((c) => ({
+              name: c.name,
+              description: c.description,
+              ...(c.argumentHint ? { args: c.argumentHint } : {}),
+            })),
+          cwd,
+        ),
+      [] as AgentCommand[],
+    );
+    commandReaders.set(cwd, reader);
+  }
+  return reader();
+}
 
 /** sessionId 会被拼进路径，先验形，防 /resume ../../x 越界 */
 const SESSION_ID = /^[A-Za-z0-9_-]{8,64}$/;
@@ -131,6 +168,14 @@ export class ClaudeDriver implements AgentDriver {
     return (session as ClaudeSession).listModels();
   }
 
+  catalog(): Promise<ModelInfo[]> {
+    return readCatalog();
+  }
+
+  commands(cwd?: string): Promise<AgentCommand[]> {
+    return readCommands(cwd ?? os.homedir());
+  }
+
   async defaults(): Promise<RuntimeInfo> {
     const c = config().agents.claude;
     return {
@@ -140,7 +185,7 @@ export class ClaudeDriver implements AgentDriver {
   }
 
   async statusLines(): Promise<string[]> {
-    return [];
+    return describeUsage(await readUsage());
   }
 
   diagnose(err: unknown) {

package/src/agents/claude/permissions.ts

@@ -3,6 +3,7 @@
 // Codex 把「总是允许」做进了协议（acceptForSession / execpolicy 补丁），Claude 没有，
 // 只能自己记一份名单。特征刻意保守：Bash 只认命令的第一个词，文件类只认所在目录。
 // 宁可多问几次，也不要因为特征太宽而放行了本不该放行的东西。
+import os from "node:os";
 import path from "node:path";
 import { dataDir, readJson, writeJsonAtomic } from "../../home.js";
 import type { QuestionSpec } from "../../core/types.js";
@@ -143,7 +144,39 @@ export function signatureOf(toolName: string, input: Record<string, unknown>): s
 
 export function isPreApproved(toolName: string, signature: string): boolean {
   // 防绕过靠的是 signatureOf：复合命令拿到的是 BashExact 签名，命中不了 Bash:<首词>
-  return isRememberableSignature(toolName, signature) && load().includes(signature);
+  if (!isRememberableSignature(toolName, signature)) return false;
+  const list = load();
+  if (list.includes(signature)) return true;
+  return coveredBySubdirectoryRule(toolName, signature, list);
+}
+
+const DIR_TOOLS = new Set(["Edit", "Write", "NotebookEdit"]);
+
+/**
+ * 按目录记的批准连带子目录：批准过 /home/me/project，改 project/src/core 下的文件不用再问。
+ * 以前只认完全相同的目录，项目里每进一个子目录都要再点一次，点到后来就是闭眼点 —— 那才不安全。
+ *
+ * 两道收口：
+ *   - 太宽的批准不往下延伸：/、家目录、家目录的上级。批准过「在家目录下新建文件」
+ *     不等于能改 ~/.ssh、~/.bashrc；
+ *   - 不延伸进隐藏目录（.git/hooks、.github/workflows、.husky…）：往那里写东西等于
+ *     让它下次自动执行。真要改，单独批一次那个目录。
+ */
+function coveredBySubdirectoryRule(toolName: string, signature: string, list: string[]): boolean {
+  if (!DIR_TOOLS.has(toolName)) return false;
+  const target = signature.slice(toolName.length + 1);
+  const home = os.homedir();
+  for (const entry of list) {
+    if (!entry.startsWith(`${toolName}:`)) continue;
+    const approved = entry.slice(toolName.length + 1);
+    if (!path.isAbsolute(approved)) continue;
+    if (approved === path.parse(approved).root || approved === home || home.startsWith(`${approved}${path.sep}`)) continue;
+    const rel = path.relative(approved, target);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) continue;
+    if (rel.split(path.sep).some((part) => part.startsWith("."))) continue;
+    return true;
+  }
+  return false;
 }
 
 export function rememberAlways(signature: string): void {
@@ -168,7 +201,7 @@ export function alwaysLabelOf(toolName: string, signature: string): string {
   if (toolName === "Bash") {
     return signature.startsWith("BashExact:") ? "总是允许这条完全相同的命令" : `总是允许 ${signature.slice(5)} 开头的单条命令`;
   }
-  if (signature.includes(":")) return `总是允许在该目录下${toolName === "Write" ? "新建" : "修改"}`;
+  if (signature.includes(":")) return `总是允许在该目录及子目录下${toolName === "Write" ? "新建" : "修改"}`;
   return `总是允许 ${toolName}`;
 }
 

package/src/agents/claude/probe.ts

@@ -0,0 +1,54 @@
+// 「探针」query：拉一个从不发消息的 CLI 进程，只用来问控制请求（额度、模型列表），问完就关。
+//
+// 这些控制方法挂在 Query 上，正常要借活会话才能问；但 /status、设置页不该依赖
+// 「当前恰好有活会话」。不发消息就不耗 token，代价只是起一次进程（两三秒）。
+import os from "node:os";
+import { query, type Query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import { agentEnvironment } from "../../core/agent-env.js";
+
+/** 永远不产出消息的输入流：query 必须是流式输入模式才能发控制请求 */
+async function* silence(): AsyncGenerator<SDKUserMessage> {
+  await new Promise<never>(() => {});
+}
+
+/** cwd 会影响项目级的东西（.claude/commands、项目 skills），不关心就用家目录 */
+export async function withProbe<T>(fn: (q: Query) => Promise<T>, cwd = os.homedir()): Promise<T> {
+  const q = query({ prompt: silence(), options: { cwd, env: agentEnvironment() } });
+  try {
+    return await fn(q);
+  } finally {
+    q.close();
+  }
+}
+
+/**
+ * 带缓存、并发合并的读取：同一时刻多个调用方共用一次探针，结果缓存 ttl 毫秒。
+ * 给了 fallback 就是「读不到也无所谓」：失败记日志、返回并缓存 fallback，免得每次都再等几秒；
+ * 没给就把错误抛给调用方，也不缓存，下次重试。
+ */
+export function cachedProbe<T>(
+  ttl: number,
+  what: string,
+  fetch: () => Promise<T>,
+  ...fallback: [] | [T]
+): () => Promise<T> {
+  let cache: { at: number; value: T } | null = null;
+  let inflight: Promise<T> | null = null;
+  return () => {
+    if (cache && Date.now() - cache.at < ttl) return Promise.resolve(cache.value);
+    inflight ??= fetch()
+      .catch((err) => {
+        console.error(`[${what}] 读取失败:`, err instanceof Error ? err.message : err);
+        if (fallback.length === 0) throw err;
+        return fallback[0] as T;
+      })
+      .then((value) => {
+        cache = { at: Date.now(), value };
+        return value;
+      })
+      .finally(() => {
+        inflight = null;
+      });
+    return inflight;
+  };
+}

package/src/agents/claude/session.ts

@@ -27,12 +27,22 @@ import {
   alwaysLabelOf,
   describeToolCall,
   isPreApproved,
+  isRememberable,
   isRememberableSignature,
   parseQuestions,
   rememberAlways,
   signatureOf,
 } from "./permissions.js";
 
+export function toModelInfo(models: Awaited<ReturnType<Query["supportedModels"]>>): ModelInfo[] {
+  return models.map((m) => ({
+    id: m.value,
+    label: m.displayName || m.value,
+    ...(m.description ? { description: m.description } : {}),
+    ...(m.supportedEffortLevels?.length ? { efforts: [...m.supportedEffortLevels] } : {}),
+  }));
+}
+
 class AsyncQueue<T> {
   private items: T[] = [];
   private waiting: ((result: IteratorResult<T>) => void)[] = [];
@@ -125,6 +135,11 @@ export class ClaudeSession implements AgentSession {
    */
   private turnBusy = false;
   private pending: UserInput[] = [];
+  /**
+   * 用户点过「本会话全部允许」。只在内存里：这个对象一换（/new、切目录、切 agent、
+   * 恢复历史、进程重启），就重新逐条询问。
+   */
+  private allowAll = false;
 
   constructor(
     private readonly opts: SessionOptions,
@@ -152,8 +167,9 @@ export class ClaudeSession implements AgentSession {
       options: {
         cwd: this.opts.cwd,
         env: agentEnvironment(),
-        // 必须是 default：bypassPermissions 会让 canUseTool 变成死代码
-        permissionMode: "default",
+        // 只能是 default 或 acceptEdits：bypassPermissions 会让 canUseTool 变成死代码。
+        // acceptEdits 只放行工作目录（含附件目录）内的改文件，其它照样走 canUseTool
+        permissionMode: this.opts.autoEdit ? "acceptEdits" : "default",
         // 逐字输出给 Web 用；飞书渠道直接忽略这些片段
         includePartialMessages: true,
         ...(this.opts.model ? { model: this.opts.model } : {}),
@@ -255,6 +271,10 @@ export class ClaudeSession implements AgentSession {
       if (answered) return answered;
     }
 
+    // 提问、批准计划这类不是「安全确认」，而是要用户真的做决定，全部允许也照样问
+    const sessionable = isRememberable(toolName);
+    if (sessionable && this.allowAll) return { behavior: "allow", updatedInput: input };
+
     const signature = signatureOf(toolName, input);
     if (isPreApproved(toolName, signature)) return { behavior: "allow", updatedInput: input };
 
@@ -263,9 +283,14 @@ export class ClaudeSession implements AgentSession {
       title: `需要授权：${toolName}`,
       detail: describeToolCall(toolName, input),
       ...(isRememberableSignature(toolName, signature) ? { alwaysLabel: alwaysLabelOf(toolName, signature) } : {}),
+      ...(sessionable ? { allowSession: true } : {}),
     });
     if (outcome.settlement === "allow-always" && isRememberableSignature(toolName, signature)) rememberAlways(signature);
-    if (outcome.settlement === "allow-once" || outcome.settlement === "allow-always") {
+    if (outcome.settlement === "allow-session") {
+      if (!this.allowAll) this.events.onStep("warning", "🔓 本会话内后续操作不再询问（/new 或切换会话后恢复逐条确认）");
+      this.allowAll = true;
+    }
+    if (outcome.settlement === "allow-once" || outcome.settlement === "allow-always" || outcome.settlement === "allow-session") {
       return { behavior: "allow", updatedInput: input };
     }
     const why =
@@ -342,13 +367,13 @@ export class ClaudeSession implements AgentSession {
 
   async listModels(): Promise<ModelInfo[]> {
     this.start();
-    const models = await this.q!.supportedModels();
-    return models.map((m) => ({
-      id: m.value,
-      label: m.displayName || m.value,
-      ...(m.description ? { description: m.description } : {}),
-      ...(m.supportedEffortLevels?.length ? { efforts: [...m.supportedEffortLevels] } : {}),
-    }));
+    return toModelInfo(await this.q!.supportedModels());
+  }
+
+  async setAutoEdit(on: boolean): Promise<void> {
+    this.opts.autoEdit = on;
+    // 还没起 CLI 就不用管：下次拉起时按 opts 来
+    if (this.q) await this.q.setPermissionMode(on ? "acceptEdits" : "default");
   }
 
   async setModel(model?: string, effort?: string): Promise<void> {

package/src/agents/codex/driver.ts

@@ -155,6 +155,10 @@ export class CodexDriver implements AgentDriver {
       }));
   }
 
+  catalog(): Promise<ModelInfo[]> {
+    return this.listModels();
+  }
+
   /** config.toml 里的默认值（config/read），不需要为此建 thread。 */
   async defaults(): Promise<RuntimeInfo> {
     const c = config().agents.codex;

package/src/agents/codex/session.ts

@@ -10,6 +10,8 @@ import type {
   AgentEvents,
   AgentSession,
   InteractionHost,
+  InteractionOutcome,
+  InteractionSpec,
   QuestionSpec,
   RuntimeInfo,
   SessionOptions,
@@ -113,7 +115,7 @@ function describePermissions(params: PermissionsApprovalParams): string {
 }
 
 function allowed(s: Settlement): boolean {
-  return s === "allow-once" || s === "allow-always";
+  return s === "allow-once" || s === "allow-always" || s === "allow-session";
 }
 
 type ParsedQuestion = QuestionSpec & { secret: boolean };
@@ -176,6 +178,8 @@ export class CodexSession implements AgentSession {
   private opening: Promise<string> | null = null;
   private detached = false;
   private runtime: RuntimeInfo = {};
+  /** 用户点过「本会话全部允许」。只在内存里，会话对象一换就重新逐条询问。 */
+  private allowAll = false;
   private replyText = "";
   private lastTokens: number | undefined;
   /** 分叉已经真正完成（拿到并接管了新 thread）。失败了不算，重试还要接着分叉 */
@@ -473,6 +477,16 @@ export class CodexSession implements AgentSession {
 
   // ---------- 反向请求：审批与提问 ----------
 
+  /** 审批都走这里：带上「本会话全部允许」按钮，点了就记住。 */
+  private async ask(spec: Extract<InteractionSpec, { kind: "approval" }>): Promise<InteractionOutcome> {
+    const outcome = await this.host({ ...spec, allowSession: true });
+    if (outcome.settlement === "allow-session") {
+      if (!this.allowAll) this.events.onStep("warning", "🔓 本会话内后续操作不再询问（/new 或切换会话后恢复逐条确认）");
+      this.allowAll = true;
+    }
+    return outcome;
+  }
+
   /**
    * 每一条都**必须**返回点什么 —— 漏回一次，Codex 那一轮就永远挂在等审批上。
    * 未知方法也要按它自己的协议结构明确拒绝。
@@ -481,8 +495,9 @@ export class CodexSession implements AgentSession {
     switch (method) {
       case "item/commandExecution/requestApproval": {
         const req = params as CommandExecutionApprovalParams;
+        if (this.allowAll) return { decision: "acceptForSession" };
         const amendment = req.proposedExecpolicyAmendment ?? null;
-        const outcome = await this.host({
+        const outcome = await this.ask({
           kind: "approval",
           title: req.kind === "writeStdin" ? "需要授权：向运行中的命令输入" : "需要授权：执行命令",
           detail: describeCommand(req),
@@ -491,6 +506,7 @@ export class CodexSession implements AgentSession {
         });
         const s = outcome.settlement;
         if (s === "allow-once") return { decision: "accept" };
+        if (s === "allow-session") return { decision: "acceptForSession" };
         if (s === "allow-always") {
           return {
             decision: amendment
@@ -504,7 +520,8 @@ export class CodexSession implements AgentSession {
 
       case "item/fileChange/requestApproval": {
         const req = params as FileChangeApprovalParams;
-        const outcome = await this.host({
+        if (this.allowAll) return { decision: "acceptForSession" };
+        const outcome = await this.ask({
           kind: "approval",
           title: "需要授权：改动文件",
           detail: describeFileChange(req),
@@ -512,14 +529,15 @@ export class CodexSession implements AgentSession {
         });
         const s = outcome.settlement;
         if (s === "allow-once") return { decision: "accept" };
-        if (s === "allow-always") return { decision: "acceptForSession" };
+        if (s === "allow-always" || s === "allow-session") return { decision: "acceptForSession" };
         if (s === "cancelled") return { decision: "cancel" };
         return { decision: "decline" };
       }
 
       case "item/permissions/requestApproval": {
         const req = params as PermissionsApprovalParams;
-        const outcome = await this.host({
+        if (this.allowAll) return { permissions: req.permissions ?? {}, scope: "session" };
+        const outcome = await this.ask({
           kind: "approval",
           title: "需要授权：额外权限",
           detail: describePermissions(req),
@@ -528,7 +546,7 @@ export class CodexSession implements AgentSession {
         if (!allowed(outcome.settlement)) return { permissions: {}, scope: "turn" };
         return {
           permissions: req.permissions ?? {},
-          scope: outcome.settlement === "allow-always" ? "session" : "turn",
+          scope: outcome.settlement === "allow-once" ? "turn" : "session",
         };
       }
 

package/src/channels/feishu/bot.ts

@@ -17,9 +17,12 @@ import { getConversation, updateConversation } from "../../core/store.js";
 import { adoptFile, KIND_LABEL } from "../../core/uploads.js";
 import type { SavedAttachment } from "../../core/types.js";
 import { FeishuClient } from "./client.js";
+import { SlashSync } from "./slash-sync.js";
+import type { CommandEntry } from "../../core/command-catalog.js";
 import {
   agentPickerCard,
   approvalCard,
+  commandListCard,
   modelPickerCard,
   progressCard,
   questionCard,
@@ -56,8 +59,27 @@ export class FeishuBot {
   private stopped = false;
   status: BotStatus = { state: "stopped", since: Date.now() };
 
+  /** 飞书输入框里「/」弹出的指令面板 */
+  readonly slash: SlashSync;
+  private slashTimer: NodeJS.Timeout | null = null;
+
   constructor(readonly cfg: FeishuBotConfig) {
     this.client = new FeishuClient(cfg.appId, cfg.appSecret, cfg.domain, `飞书:${cfg.name}`);
+    this.slash = new SlashSync(this.client.lark, () => this.slashCommands(), `[飞书:${cfg.name}]`);
+  }
+
+  /**
+   * 这个机器人该注册的命令：默认 agent 的命令表在前，其它可用 agent 的原生命令接在后面。
+   * 飞书的指令面板是整个应用一份，不分会话，没法跟着每个会话当前的 agent 变。
+   */
+  private async slashCommands(): Promise<CommandEntry[]> {
+    const agents = [this.cfg.defaultAgent, ...this.cfg.agents.filter((a) => a !== this.cfg.defaultAgent)];
+    const out: CommandEntry[] = [];
+    for (const agent of agents) {
+      if (!hub.driver(agent)) continue;
+      out.push(...(await hub.commandCatalog(agent, { allowedAgents: this.cfg.agents })));
+    }
+    return out;
   }
 
   get id(): string {
@@ -120,10 +142,17 @@ export class FeishuBot {
 
     this.connect();
     this.startWatchdog();
+    // 等 agent 起来再同步（Claude 的原生命令要起进程读）；之后每 6 小时对一次账，新装的 skill 会跟上
+    this.slash.request(15_000);
+    this.slashTimer = setInterval(() => this.slash.request(0), 6 * 3600_000);
+    this.slashTimer.unref?.();
   }
 
   stop(): void {
     this.stopped = true;
+    this.slash.stop();
+    if (this.slashTimer) clearInterval(this.slashTimer);
+    this.slashTimer = null;
     for (const off of this.offs.splice(0)) off();
     if (this.watchdog) clearInterval(this.watchdog);
     this.watchdog = null;
@@ -486,6 +515,12 @@ export class FeishuBot {
       case "agents":
         await this.client.sendCard(chatId, agentPickerCard({ ...reply, sessionKey: key, ctx }));
         return;
+      case "commands":
+        await this.client.sendCard(
+          chatId,
+          commandListCard({ agentLabel: hub.label(reply.agent), commands: reply.commands, sessionKey: key, ctx }),
+        );
+        return;
       case "none":
         return;
     }
@@ -595,9 +630,34 @@ export class FeishuBot {
       case "agent":
         this.background(envelope.k, () => hub.setAgent(envelope.k, envelope.g, this.allowedAgents()));
         return { toast: { type: "success", content: `正在切换到 ${hub.label(envelope.g)}` } };
+      case "cmd":
+        return this.runCardCommand(envelope.k, `/${envelope.c}`);
     }
   }
 
+  /**
+   * 命令表上点「执行」：等同于用户自己发了这条命令。
+   * im-agent 的命令就地执行并回卡片；agent 原生命令（skills 等）当一条消息发给 agent。
+   */
+  private runCardCommand(key: string, text: string): CardResponse {
+    if (!this.mine(key) || !getConversation(key)) {
+      return { toast: { type: "error", content: "这条会话已不存在，请重新发一次「/」。" } };
+    }
+    const command = parseCommand(text);
+    if (command.kind === "chat") {
+      const origin = { channel: "feishu", channelId: this.cfg.id, name: "飞书" };
+      const gen = hub.generation(key);
+      this.enqueue(key, async () => hub.send(key, { text, attachments: [] }, origin, gen));
+      return { toast: { type: "success", content: `已发送 ${text}` } };
+    }
+    const chatId = this.chatIdOf(key);
+    void hub
+      .command(key, command, { allowedAgents: this.allowedAgents(), by: "飞书命令" })
+      .then((reply) => this.renderReply(key, reply))
+      .catch((err) => this.client.sendText(chatId, `出错了：${err instanceof Error ? err.message : String(err)}`));
+    return { toast: { type: "info", content: `正在执行 ${text}` } };
+  }
+
   /** 卡片回调里耗时的操作：先应答，做完在会话里回一句。 */
   private background(key: string, task: () => Promise<string>): void {
     if (!this.mine(key) || !getConversation(key)) return;