im-agent 0.0.0-stage → 0.1.0

package/src/channels/feishu/cards.ts

@@ -0,0 +1,309 @@
+// 卡片构造，全部使用 JSON 2.0。
+//
+// 2.0 与 1.0 的三处硬差异（踩过坑，别改回去）：
+//   1. 没有 `tag: "action"` 容器，按钮直接作为 element；横排要用 column_set 包 column
+//   2. 回调数据不在按钮的 value 上，而是 behaviors: [{ type: "callback", value }]
+//   3. 没有 `tag: "note"`，小字提示只能并进 markdown
+import { createEnvelope, type CardCtx, type EnvelopeAction } from "./envelope.js";
+import { answerTextOf, SETTLEMENT_LABEL, type Interaction } from "../../core/interactions.js";
+import type { ModelInfo, SessionSummary } from "../../core/types.js";
+
+function button(
+  label: string,
+  action: EnvelopeAction,
+  ctx: CardCtx,
+  type: "default" | "primary" | "danger" = "default",
+) {
+  return {
+    tag: "button",
+    text: { tag: "plain_text", content: label },
+    type,
+    behaviors: [{ type: "callback", value: createEnvelope(action, ctx) }],
+  };
+}
+
+function buttonRow(buttons: ReturnType<typeof button>[]) {
+  return {
+    tag: "column_set",
+    flex_mode: "flow",
+    horizontal_spacing: "8px",
+    columns: buttons.map((b) => ({ tag: "column", width: "auto", elements: [b] })),
+  };
+}
+
+/** 截断过长的文本，避免卡片超限；保留头尾更利于判断。 */
+export function clip(text: string, max = 1500): string {
+  if (text.length <= max) return text;
+  const head = text.slice(0, Math.floor(max * 0.7));
+  const tail = text.slice(-Math.floor(max * 0.2));
+  return `${head}\n\n… (省略 ${text.length - head.length - tail.length} 字) …\n\n${tail}`;
+}
+
+// update_multi 必须显式为 true：更新卡片接口要求前后 config 都声明它
+const baseConfig = { width_mode: "fill", update_multi: true };
+
+function card(elements: unknown[], header?: { title: string; template: string }) {
+  return {
+    schema: "2.0",
+    config: baseConfig,
+    ...(header ? { header: { title: { tag: "plain_text", content: header.title }, template: header.template } } : {}),
+    body: { elements },
+  };
+}
+
+// ---------- 交互 ----------
+
+/** 审批卡：三档决策。请求 id 印在正文里，卡片失效时还能手打 /approve 兜底。 */
+export function approvalCard(interaction: Interaction, ctx: CardCtx) {
+  const spec = interaction.spec;
+  if (spec.kind !== "approval") throw new Error("不是审批");
+  const id = interaction.id;
+  const buttons = [
+    button("允许一次", { a: "approval", r: id, d: "allow-once" }, ctx, "primary"),
+    ...(spec.alwaysLabel ? [button(spec.alwaysLabel, { a: "approval", r: id, d: "allow-always" }, ctx)] : []),
+    button("拒绝", { a: "approval", r: id, d: "deny" }, ctx, "danger"),
+  ];
+  return card(
+    [
+      { tag: "markdown", content: clip(spec.detail) },
+      { tag: "hr" },
+      buttonRow(buttons),
+      { tag: "markdown", content: `请求 \`${id}\`　按钮失效时可发送：\`/approve ${id} allow-once\`` },
+    ],
+    { title: spec.title, template: "orange" },
+  );
+}
+
+/** 提问卡：有状态，每点一下就用最新的勾选重渲。全单选且都选完自动收束，多选要点「提交」。 */
+export function questionCard(interaction: Interaction, ctx: CardCtx, agentLabel: string) {
+  const spec = interaction.spec;
+  if (spec.kind !== "question") throw new Error("不是提问");
+  const id = interaction.id;
+  const needsSubmit = spec.questions.some((q) => q.multiSelect);
+  const elements: unknown[] = [];
+  spec.questions.forEach((q, qi) => {
+    if (qi > 0) elements.push({ tag: "hr" });
+    const picked = interaction.selections[qi] ?? [];
+    elements.push({ tag: "markdown", content: `**${q.header}**　${q.question}${q.multiSelect ? "（可多选）" : ""}` });
+    if (q.options.length > 0) {
+      elements.push(
+        buttonRow(
+          q.options.map((opt, oi) => {
+            const on = picked.includes(oi);
+            const next: 0 | 1 = q.multiSelect && on ? 0 : 1;
+            return button(
+              `${on ? "✅ " : ""}${clip(opt.label, 30)}`,
+              { a: "ask", r: id, q: qi, o: oi, v: next },
+              ctx,
+              on ? "primary" : "default",
+            );
+          }),
+        ),
+      );
+      const notes = q.options
+        .filter((opt) => opt.description)
+        .map((opt) => `**${opt.label}** — ${opt.description}`)
+        .join("\n");
+      if (notes) elements.push({ tag: "markdown", content: clip(notes, 800) });
+    } else {
+      elements.push({ tag: "markdown", content: "_这一问需要你直接回一句话。_" });
+    }
+  });
+  elements.push({ tag: "hr" });
+  elements.push(
+    buttonRow([
+      ...(needsSubmit ? [button("提交", { a: "ask-submit", r: id }, ctx, "primary")] : []),
+      button("跳过", { a: "ask-skip", r: id }, ctx),
+    ]),
+  );
+  elements.push({ tag: "markdown", content: "选项都不合适？**直接发一条消息**就当作你的回答。" });
+  return card(elements, { title: spec.title || `${agentLabel} 想确认一下`, template: "violet" });
+}
+
+/** 收束后的卡：原地替换，避免重复点击和状态歧义。 */
+export function settledCard(interaction: Interaction) {
+  const settled = interaction.settled;
+  const settlement = settled?.settlement ?? "cancelled";
+  const by = settled?.by ?? "";
+  if (interaction.spec.kind === "approval") {
+    const ok = settlement === "allow-once" || settlement === "allow-always";
+    const label =
+      settlement === "allow-always"
+        ? `已允许（${interaction.spec.alwaysLabel ?? "后续同类自动放行"}）`
+        : SETTLEMENT_LABEL[settlement];
+    return card([{ tag: "markdown", content: `请求 \`${interaction.id}\`　${by}` }], {
+      title: `${label}：${interaction.spec.title.replace(/^需要授权：/, "")}`,
+      template: ok ? "green" : "grey",
+    });
+  }
+  const answers = answerTextOf(interaction);
+  const answered = interaction.spec.questions.filter((q) => answers[q.question]);
+  const empty = answered.length === 0;
+  const lines = answered.map((q) => `**${q.header}**　${q.question}\n→ ${answers[q.question]}`);
+  return card(
+    [
+      { tag: "markdown", content: clip(empty ? `${SETTLEMENT_LABEL[settlement]}。${by ? `（${by}）` : ""}` : lines.join("\n\n"), 2000) },
+      ...(!empty && by ? [{ tag: "markdown", content: by }] : []),
+    ],
+    { title: empty ? "未作答" : "已回答", template: empty ? "grey" : "green" },
+  );
+}
+
+// ---------- 过程与回复 ----------
+
+/** 过程卡：进行中展开，完成后折叠成一行摘要。 */
+export function progressCard(params: { steps: string[]; done?: boolean; footer?: string }) {
+  const body = clip(params.steps.length > 0 ? params.steps.join("\n") : "…", 2000);
+  if (!params.done) return card([{ tag: "markdown", content: body }]);
+  const summary = `已完成 ${params.steps.length} 步${params.footer ? `　${params.footer}` : ""}`;
+  return card([
+    {
+      tag: "collapsible_panel",
+      expanded: false,
+      header: {
+        title: { tag: "plain_text", content: summary },
+        vertical_align: "center",
+        icon: { tag: "standard_icon", token: "down-small-ccm_outlined", size: "16px 16px" },
+      },
+      padding: "8px 8px 8px 8px",
+      elements: [{ tag: "markdown", content: body }],
+    },
+  ]);
+}
+
+/** 回复卡：飞书纯文本不渲染 markdown，所以回复必须走卡片。刻意做到最简。 */
+export function replyCard(text: string) {
+  return card([{ tag: "markdown", content: clip(text, 4000) }]);
+}
+
+// ---------- 命令结果 ----------
+
+export function modelPickerCard(params: {
+  agentLabel: string;
+  models: ModelInfo[];
+  current?: string;
+  currentEffort?: string;
+  effortSupported: boolean;
+  sessionKey: string;
+  ctx: CardCtx;
+}) {
+  const elements: unknown[] = [
+    {
+      tag: "markdown",
+      content: `${params.agentLabel}　当前：**${params.current ?? "默认模型"}**${
+        params.currentEffort ? `　思考 **${params.currentEffort}**` : ""
+      }`,
+    },
+    { tag: "hr" },
+    buttonRow(
+      params.models
+        .slice(0, 12)
+        .map((m) =>
+          button(
+            `${m.label}${m.id === params.current ? " ✅" : ""}`,
+            { a: "model", m: m.id, k: params.sessionKey },
+            params.ctx,
+          ),
+        ),
+    ),
+  ];
+  const efforts =
+    params.models.find((m) => m.id === params.current)?.efforts ??
+    params.models.find((m) => m.efforts?.length)?.efforts ??
+    [];
+  if (params.effortSupported && efforts.length > 0) {
+    elements.push({ tag: "hr" }, { tag: "markdown", content: "**思考程度**" });
+    elements.push(
+      buttonRow(
+        efforts
+          .slice(0, 8)
+          .map((e) =>
+            button(`${e}${e === params.currentEffort ? " ✅" : ""}`, { a: "effort", f: e, k: params.sessionKey }, params.ctx),
+          ),
+      ),
+    );
+  }
+  return card(elements, { title: "切换模型", template: "blue" });
+}
+
+export function agentPickerCard(params: {
+  agents: { id: string; label: string }[];
+  current: string;
+  sessionKey: string;
+  ctx: CardCtx;
+}) {
+  return card(
+    [
+      { tag: "markdown", content: "每个 agent 的会话各自保留，切回来能接着聊。" },
+      buttonRow(
+        params.agents.map((a) =>
+          button(
+            `${a.label}${a.id === params.current ? " ✅" : ""}`,
+            { a: "agent", g: a.id, k: params.sessionKey },
+            params.ctx,
+            a.id === params.current ? "primary" : "default",
+          ),
+        ),
+      ),
+    ],
+    { title: "切换 Agent", template: "blue" },
+  );
+}
+
+export function sessionListCard(params: {
+  agentLabel: string;
+  sessions: SessionSummary[];
+  current?: string;
+  cwd: string;
+  allDirs: boolean;
+  fellBack: boolean;
+  sessionKey: string;
+  ctx: CardCtx;
+}) {
+  const elements: unknown[] = [
+    {
+      tag: "markdown",
+      content: `${params.agentLabel}　${
+        params.allDirs
+          ? params.fellBack
+            ? `\`${params.cwd}\` 下没有历史会话，已列出**所有目录**的最近会话`
+            : "所有目录的最近会话"
+          : `目录 \`${params.cwd}\``
+      }`,
+    },
+  ];
+  params.sessions.forEach((entry, index) => {
+    const isCurrent = entry.id === params.current;
+    elements.push({ tag: "hr" });
+    elements.push({
+      tag: "markdown",
+      content:
+        `**${index + 1}. ${entry.title}**${isCurrent ? "　✅ 当前" : ""}\n` +
+        (params.allDirs && entry.cwd ? `\`${entry.cwd}\`\n` : "") +
+        `\`${entry.id}\`　${relativeTime(entry.updatedAt)}`,
+    });
+    if (!isCurrent) {
+      elements.push(
+        buttonRow([
+          button(
+            "恢复这条",
+            { a: "resume", s: entry.id, k: params.sessionKey, ...(entry.cwd ? { c: entry.cwd } : {}) },
+            params.ctx,
+          ),
+        ]),
+      );
+    }
+  });
+  return card(elements, { title: "历史会话", template: "blue" });
+}
+
+export function relativeTime(ts: number, now = Date.now()): string {
+  const minutes = Math.floor((now - ts) / 60_000);
+  if (minutes < 1) return "刚刚";
+  if (minutes < 60) return `${minutes} 分钟前`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours} 小时前`;
+  const days = Math.floor(hours / 24);
+  if (days < 30) return `${days} 天前`;
+  return new Date(ts).toLocaleDateString("zh-CN");
+}

package/src/channels/feishu/client.ts

@@ -0,0 +1,185 @@
+// 飞书客户端封装：一个机器人一个实例（以前是全局单例，现在一个进程可以跑多个机器人）。
+import fs from "node:fs";
+import * as Lark from "@larksuiteoapi/node-sdk";
+
+function errData(err: unknown): { code?: number; msg?: string } | undefined {
+  return (err as { response?: { data?: { code?: number; msg?: string } } })?.response?.data;
+}
+
+function rememberBounded<K, V>(map: Map<K, V>, key: K, value: V, max = 500): void {
+  map.set(key, value);
+  if (map.size > max) {
+    const oldest = map.keys().next().value;
+    if (oldest !== undefined) map.delete(oldest);
+  }
+}
+
+export class FeishuClient {
+  readonly lark: Lark.Client;
+  /** message_id → card_id；cardkit 的全量更新要求 sequence 严格递增，每张卡自己记着 */
+  private cardIdByMessage = new Map<string, string>();
+  private sequenceByCard = new Map<string, number>();
+
+  constructor(
+    private readonly appId: string,
+    private readonly appSecret: string,
+    domain: "feishu" | "lark",
+    private readonly tag: string,
+  ) {
+    this.lark = new Lark.Client({
+      appId,
+      appSecret,
+      domain: domain === "lark" ? Lark.Domain.Lark : Lark.Domain.Feishu,
+    });
+  }
+
+  async sendText(chatId: string, text: string): Promise<string | undefined> {
+    try {
+      const res = await this.lark.im.v1.message.create({
+        params: { receive_id_type: "chat_id" },
+        data: { receive_id: chatId, msg_type: "text", content: JSON.stringify({ text }) },
+      });
+      return res.data?.message_id;
+    } catch (err) {
+      const data = errData(err);
+      console.error(`[${this.tag}] 发消息失败:`, data ? `code=${data.code} msg=${data.msg}` : err);
+      return undefined;
+    }
+  }
+
+  async sendCard(chatId: string, card: unknown): Promise<string | undefined> {
+    try {
+      const res = await this.lark.im.v1.message.create({
+        params: { receive_id_type: "chat_id" },
+        data: { receive_id: chatId, msg_type: "interactive", content: JSON.stringify(card) },
+      });
+      const messageId = res.data?.message_id;
+      if (!messageId) console.warn(`[${this.tag}] 发卡成功但没拿到 message_id，该卡片将无法更新`);
+      return messageId;
+    } catch (err) {
+      const data = errData(err);
+      console.error(`[${this.tag}] 发卡片失败:`, data ? `code=${data.code} msg=${data.msg}` : err);
+      return undefined;
+    }
+  }
+
+  private async resolveCardId(messageId: string): Promise<string | undefined> {
+    const cached = this.cardIdByMessage.get(messageId);
+    if (cached) return cached;
+    try {
+      const res = await this.lark.cardkit.v1.card.idConvert({ data: { message_id: messageId } });
+      const cardId = res.data?.card_id;
+      if (cardId) rememberBounded(this.cardIdByMessage, messageId, cardId);
+      return cardId;
+    } catch (err) {
+      const data = errData(err);
+      console.warn(`[${this.tag}] message_id ${messageId} 转 card_id 失败:`, data ? `code=${data.code}` : String(err));
+      return undefined;
+    }
+  }
+
+  /**
+   * 原地更新卡片。走 cardkit 的全量更新：它是 JSON 2.0 卡片的正规通道。
+   * 老的 im.v1.message.patch 对 2.0 卡片不可靠（带交互组件的更新不动），只作回退。
+   */
+  async updateCard(messageId: string, card: unknown): Promise<boolean> {
+    const cardId = await this.resolveCardId(messageId);
+    if (cardId) {
+      const sequence = (this.sequenceByCard.get(cardId) ?? Math.floor(Date.now() / 1000)) + 1;
+      rememberBounded(this.sequenceByCard, cardId, sequence);
+      try {
+        const res = await this.lark.cardkit.v1.card.update({
+          path: { card_id: cardId },
+          data: { card: { type: "card_json", data: JSON.stringify(card) }, sequence },
+        });
+        if (res.code === 0) return true;
+        console.warn(`[${this.tag}] cardkit 更新 ${cardId} 被拒绝: code=${res.code} msg=${res.msg}`);
+      } catch (err) {
+        const data = errData(err);
+        console.warn(`[${this.tag}] cardkit 更新 ${cardId} 失败:`, data ? `code=${data.code} msg=${data.msg}` : String(err));
+      }
+    }
+    try {
+      const res = await this.lark.im.v1.message.patch({
+        path: { message_id: messageId },
+        data: { content: JSON.stringify(card) },
+      });
+      return res.code === 0;
+    } catch (err) {
+      const data = errData(err);
+      console.warn(`[${this.tag}] 更新卡片 ${messageId} 失败:`, data ? `code=${data.code} msg=${data.msg}` : String(err));
+      return false;
+    }
+  }
+
+  /** 飞书没有给机器人开放 typing 指示器，表情回复是最接近的替代。 */
+  async addTypingReaction(messageId: string): Promise<string | undefined> {
+    try {
+      const res = await this.lark.im.v1.messageReaction.create({
+        path: { message_id: messageId },
+        data: { reaction_type: { emoji_type: "Typing" } },
+      });
+      return res.data?.reaction_id;
+    } catch (err) {
+      console.warn(`[${this.tag}] 加表情失败:`, err instanceof Error ? err.message : err);
+      return undefined;
+    }
+  }
+
+  async removeReaction(messageId: string, reactionId: string): Promise<void> {
+    try {
+      await this.lark.im.v1.messageReaction.delete({
+        path: { message_id: messageId, reaction_id: reactionId },
+      });
+    } catch (err) {
+      console.warn(`[${this.tag}] 删表情失败:`, err instanceof Error ? err.message : err);
+    }
+  }
+
+  /** 下载消息里的资源到 target。失败时把飞书的错误码翻成人话抛出来。 */
+  async downloadResource(messageId: string, fileKey: string, type: "image" | "file", target: string): Promise<void> {
+    try {
+      const res = await this.lark.im.v1.messageResource.get({
+        path: { message_id: messageId, file_key: fileKey },
+        params: { type },
+      });
+      await res.writeFile(target);
+    } catch (err) {
+      fs.rmSync(target, { force: true });
+      const data = await readErrorBody(err);
+      if (data?.code === 99991672 || data?.code === 99991679) {
+        throw new Error("飞书应用缺少「获取与上传图片或文件资源」(im:resource) 权限");
+      }
+      if (data) throw new Error(`飞书返回 code=${data.code} ${(data.msg ?? "").slice(0, 120)}`.trim());
+      throw err instanceof Error ? err : new Error(String(err));
+    }
+  }
+
+  /** 测试连通性：拿一次 tenant token 就知道 appId / secret 对不对。 */
+  async probe(): Promise<{ ok: boolean; message: string }> {
+    try {
+      const res = await this.lark.auth.v3.tenantAccessToken.internal({
+        data: { app_id: this.appId, app_secret: this.appSecret },
+      });
+      return res.code === 0 ? { ok: true, message: "凭据有效" } : { ok: false, message: `code=${res.code} ${res.msg}` };
+    } catch (err) {
+      return { ok: false, message: err instanceof Error ? err.message : String(err) };
+    }
+  }
+}
+
+/** 下载接口按二进制流请求，出错时响应体也是一个流，得先读出来再解析。 */
+async function readErrorBody(err: unknown): Promise<{ code?: number; msg?: string } | undefined> {
+  const raw = (err as { response?: { data?: unknown } })?.response?.data;
+  if (!raw) return undefined;
+  if (typeof (raw as AsyncIterable<unknown>)[Symbol.asyncIterator] !== "function") {
+    return raw as { code?: number; msg?: string };
+  }
+  try {
+    let body = "";
+    for await (const chunk of raw as AsyncIterable<Buffer | string>) body += chunk.toString();
+    return JSON.parse(body);
+  } catch {
+    return undefined;
+  }
+}

package/src/channels/feishu/envelope.ts

@@ -0,0 +1,112 @@
+// 卡片按钮里携带的交互信封。
+//
+// 信任模型：信封本身是明文、不签名，它不是凭证，只是「这张卡片期望由谁、在哪、
+// 在什么期限前点」的声明。真正的信任锚在服务端：
+//   1. 飞书回调里的 operator.open_id 由平台签发，客户端伪造不了；
+//   2. 请求 id 必须命中服务端的待处理表，且点击者要通过授权判断。
+// 所以信封挡的是「同群别人替你点」「过期后补点」「卡片被转发到别的会话点」。
+//
+// ask 的 v 是「点完之后该是选中(1)还是未选中(0)」，而不是「切换」：飞书会重投回调，
+// 切换语义在重投下不幂等。
+import type { ApprovalDecision } from "../../core/types.js";
+
+export const ENVELOPE_VERSION = "aim2";
+
+/** k 是会话键：卡片回调里拿不到 thread_id，凡是作用于某条会话的动作都得带上它。 */
+export type EnvelopeAction =
+  | { a: "approval"; r: string; d: ApprovalDecision }
+  | { a: "ask"; r: string; q: number; o: number; v: 0 | 1 }
+  | { a: "ask-submit"; r: string }
+  | { a: "ask-skip"; r: string }
+  | { a: "model"; m: string; k: string }
+  | { a: "effort"; f: string; k: string }
+  | { a: "agent"; g: string; k: string }
+  | { a: "resume"; s: string; k: string; c?: string };
+
+export type CardEnvelope = EnvelopeAction & {
+  oc: typeof ENVELOPE_VERSION;
+  /** 期望的点击人 open_id；不带表示任何授权用户都能点（比如 Web 上发起的那一轮） */
+  u?: string;
+  /** 期望的会话 chat_id */
+  h?: string;
+  /** 过期时间戳（ms） */
+  e: number;
+};
+
+export type CardCtx = { operatorOpenId?: string; chatId?: string; expiresAt: number };
+
+export type DecodeFailure = "malformed" | "stale" | "wrong_user" | "wrong_conversation" | "not_allowed";
+
+export function createEnvelope(action: EnvelopeAction, ctx: CardCtx): CardEnvelope {
+  return {
+    oc: ENVELOPE_VERSION,
+    ...action,
+    ...(ctx.operatorOpenId ? { u: ctx.operatorOpenId } : {}),
+    ...(ctx.chatId ? { h: ctx.chatId } : {}),
+    e: ctx.expiresAt,
+  } as CardEnvelope;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function decodeEnvelope(params: {
+  value: unknown;
+  operatorOpenId: string | undefined;
+  chatId: string | undefined;
+  isAllowed: (openId: string | undefined) => boolean;
+  now?: number;
+}): { ok: true; envelope: CardEnvelope } | { ok: false; reason: DecodeFailure } {
+  const { value, operatorOpenId, chatId, isAllowed, now = Date.now() } = params;
+  if (!isRecord(value) || value.oc !== ENVELOPE_VERSION || typeof value.a !== "string") {
+    return { ok: false, reason: "malformed" };
+  }
+  if (typeof value.e !== "number" || !Number.isFinite(value.e)) return { ok: false, reason: "malformed" };
+  if (value.e < now) return { ok: false, reason: "stale" };
+  const operator = operatorOpenId?.trim().toLowerCase();
+  if (typeof value.u === "string" && value.u.trim().toLowerCase() !== operator) {
+    return { ok: false, reason: "wrong_user" };
+  }
+  if (typeof value.h === "string" && value.h.trim() !== (chatId ?? "").trim()) {
+    return { ok: false, reason: "wrong_conversation" };
+  }
+  if (!validAction(value)) return { ok: false, reason: "malformed" };
+  // 白名单是最后也是最硬的一道
+  if (!isAllowed(operatorOpenId)) return { ok: false, reason: "not_allowed" };
+  return { ok: true, envelope: value as CardEnvelope };
+}
+
+const str = (v: unknown): v is string => typeof v === "string" && v.length > 0 && v.length < 512;
+const idx = (v: unknown): v is number => typeof v === "number" && Number.isInteger(v) && v >= 0 && v < 100;
+
+/** 每种动作的字段逐个验类型：信封是明文，别让一个畸形的值流进 agent。 */
+function validAction(v: Record<string, unknown>): boolean {
+  switch (v.a) {
+    case "approval":
+      return str(v.r) && (v.d === "allow-once" || v.d === "allow-always" || v.d === "deny");
+    case "ask":
+      return str(v.r) && idx(v.q) && idx(v.o) && (v.v === 0 || v.v === 1);
+    case "ask-submit":
+    case "ask-skip":
+      return str(v.r);
+    case "model":
+      return str(v.m) && str(v.k);
+    case "effort":
+      return str(v.f) && str(v.k);
+    case "agent":
+      return str(v.g) && str(v.k);
+    case "resume":
+      return str(v.s) && str(v.k) && (v.c === undefined || str(v.c));
+    default:
+      return false;
+  }
+}
+
+export const DECODE_FAILURE_TEXT: Record<DecodeFailure, string> = {
+  malformed: "这个按钮的数据已损坏（或来自旧版本的卡片），请重新发起操作。",
+  stale: "这张卡片已过期，请重新发起操作。",
+  wrong_user: "这张卡片不是发给你的，只有发起人本人可以操作。",
+  wrong_conversation: "这张卡片属于另一个会话，不能在这里操作。",
+  not_allowed: "你不在这台机器的授权名单里。",
+};

package/src/channels/feishu/index.ts

@@ -0,0 +1,52 @@
+// 飞书渠道：按配置拉起 / 停掉机器人。Web 上改了机器人配置，这里就地对账，不用重启进程。
+import { config, onConfigChange, type FeishuBotConfig } from "../../core/config.js";
+import { watchPairing } from "../../core/pairing.js";
+import { FeishuBot } from "./bot.js";
+
+const bots = new Map<string, FeishuBot>();
+
+function fingerprint(cfg: FeishuBotConfig): string {
+  // allowFrom / agents 变了不必重连，直接换配置对象即可；凭据变了才要重建连接
+  return JSON.stringify([cfg.appId, cfg.appSecret, cfg.domain, cfg.enabled]);
+}
+
+function reconcile(list: FeishuBotConfig[]): void {
+  const wanted = new Map(list.filter((b) => b.enabled && b.appId && b.appSecret).map((b) => [b.id, b]));
+  for (const [id, bot] of bots) {
+    const next = wanted.get(id);
+    if (!next || fingerprint(next) !== fingerprint(bot.cfg)) {
+      bot.stop();
+      bots.delete(id);
+      console.log(`[飞书] 已停止机器人 ${bot.cfg.name}`);
+    }
+  }
+  for (const [id, cfg] of wanted) {
+    const existing = bots.get(id);
+    if (existing) {
+      Object.assign(existing.cfg, cfg);
+      continue;
+    }
+    const bot = new FeishuBot({ ...cfg });
+    bots.set(id, bot);
+    bot.start();
+    console.log(`[飞书] 已启动机器人 ${cfg.name}（agent：${cfg.agents.join("、")}）`);
+  }
+}
+
+export function startFeishu(): void {
+  reconcile(config().feishu.bots);
+  onConfigChange((next) => reconcile(next.feishu.bots));
+  // 配对被批准（Web 上点的，或终端里另一个进程批的）：通知等着的人
+  watchPairing((channelId, _userId, chatId) => {
+    if (chatId) bots.get(channelId)?.notifyApproved(chatId);
+  });
+}
+
+export function stopFeishu(): void {
+  for (const bot of bots.values()) bot.stop();
+  bots.clear();
+}
+
+export function feishuBots(): FeishuBot[] {
+  return [...bots.values()];
+}