im-agent 0.0.0-stage → 0.1.0

package/src/channels/feishu/message.ts

@@ -0,0 +1,115 @@
+// 飞书消息解析：文字 + 附件引用（还没下载）。
+import type { AttachmentKind } from "../../core/types.js";
+
+export type AttachmentRef = { kind: AttachmentKind; key: string; name?: string; durationMs?: number };
+export type ParsedMessage = { text: string; attachments: AttachmentRef[] };
+
+const UNSUPPORTED_TYPES: Record<string, string> = {
+  sticker: "表情包",
+  merge_forward: "合并转发",
+  interactive: "卡片",
+  share_chat: "群名片",
+  share_user: "个人名片",
+  location: "位置",
+  todo: "任务",
+  vote: "投票",
+};
+
+export function unsupportedTypeLabel(messageType: string | undefined): string {
+  return (messageType && UNSUPPORTED_TYPES[messageType]) ?? "这种";
+}
+
+/** 不认识的消息类型返回 null，调用方据此回一句「不支持」。 */
+export function parseMessage(message: { message_type?: string; content?: string }): ParsedMessage | null {
+  let content: any;
+  try {
+    content = JSON.parse(message.content ?? "{}");
+  } catch {
+    return null;
+  }
+  switch (message.message_type) {
+    case "text":
+      return { text: String(content.text ?? ""), attachments: [] };
+    case "image":
+      return content.image_key ? { text: "", attachments: [{ kind: "image", key: content.image_key }] } : null;
+    case "file":
+      return content.file_key
+        ? { text: "", attachments: [{ kind: "file", key: content.file_key, name: content.file_name }] }
+        : null;
+    case "audio":
+      return content.file_key
+        ? {
+            text: "",
+            attachments: [{ kind: "audio", key: content.file_key, durationMs: Number(content.duration) || undefined }],
+          }
+        : null;
+    case "media":
+      return content.file_key
+        ? {
+            text: "",
+            attachments: [
+              {
+                kind: "video",
+                key: content.file_key,
+                name: content.file_name,
+                durationMs: Number(content.duration) || undefined,
+              },
+            ],
+          }
+        : null;
+    case "post":
+      return parsePost(content);
+    default:
+      return null;
+  }
+}
+
+/** 富文本：文字按原顺序拼起来，图片和视频在原位置留个占位（「看第二张图」才对得上号）。 */
+function parsePost(content: any): ParsedMessage | null {
+  const body = Array.isArray(content?.content)
+    ? content
+    : Object.values(content ?? {}).find((v: any) => Array.isArray(v?.content));
+  if (!body) return null;
+  const attachments: AttachmentRef[] = [];
+  const lines: string[] = [];
+  if ((body as any).title) lines.push(String((body as any).title));
+  const count = (kind: AttachmentKind) => attachments.filter((a) => a.kind === kind).length;
+  for (const paragraph of (body as any).content as any[][]) {
+    if (!Array.isArray(paragraph)) continue;
+    let line = "";
+    for (const el of paragraph) {
+      switch (el?.tag) {
+        case "text":
+        case "md":
+          line += el.text ?? "";
+          break;
+        case "a":
+          line += el.text && el.href && el.text !== el.href ? `[${el.text}](${el.href})` : (el.href ?? el.text ?? "");
+          break;
+        case "at":
+          line += el.user_id ?? "";
+          break;
+        case "code_block":
+          line += `\n\`\`\`${el.language ?? ""}\n${el.text ?? ""}\n\`\`\`\n`;
+          break;
+        case "emotion":
+          line += el.emoji_type ? `[${el.emoji_type}]` : "";
+          break;
+        case "img":
+          if (el.image_key) {
+            attachments.push({ kind: "image", key: el.image_key });
+            line += `[图片${count("image")}]`;
+          }
+          break;
+        case "media":
+          if (el.file_key) {
+            attachments.push({ kind: "video", key: el.file_key });
+            line += `[视频${count("video")}]`;
+          }
+          break;
+      }
+    }
+    lines.push(line);
+  }
+  return { text: lines.join("\n"), attachments };
+}

package/src/channels/feishu/register.ts

@@ -0,0 +1,171 @@
+// 飞书应用注册：OAuth device-code flow。
+//
+// 扫码后一次拿全 appId / appSecret / 扫码人的 open_id，用户不用去开发者后台
+// 手抄任何东西。协议端点与字段取自飞书 accounts 域的 app registration 接口。
+import QRCode from "qrcode";
+
+export type FeishuDomain = "feishu" | "lark";
+
+const ACCOUNTS_URL: Record<FeishuDomain, string> = {
+  feishu: "https://accounts.feishu.cn",
+  lark: "https://accounts.larksuite.com",
+};
+const REGISTRATION_PATH = "/oauth/v1/app/registration";
+const REQUEST_TIMEOUT_MS = 10_000;
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const DEFAULT_EXPIRE_SECONDS = 600;
+
+export type RegistrationResult = {
+  appId: string;
+  appSecret: string;
+  domain: FeishuDomain;
+  openId?: string;
+};
+
+export type BeginResult = {
+  deviceCode: string;
+  qrUrl: string;
+  userCode: string;
+  interval: number;
+  expireIn: number;
+};
+
+export type PollOutcome =
+  | { status: "success"; result: RegistrationResult }
+  | { status: "access_denied" }
+  | { status: "expired" }
+  | { status: "timeout" }
+  | { status: "error"; message: string };
+
+type InitResponse = { nonce?: string; supported_auth_methods?: string[] };
+type BeginResponse = {
+  device_code: string;
+  verification_uri: string;
+  verification_uri_complete: string;
+  user_code: string;
+  interval: number;
+  expire_in: number;
+};
+type PollResponse = {
+  client_id?: string;
+  client_secret?: string;
+  user_info?: { open_id?: string; tenant_brand?: FeishuDomain };
+  error?: string;
+  error_description?: string;
+};
+
+async function post<T>(domain: FeishuDomain, body: Record<string, string>): Promise<T> {
+  const res = await fetch(`${ACCOUNTS_URL[domain]}${REGISTRATION_PATH}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(body).toString(),
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  // 待授权/错误状态也会以 4xx + JSON body 返回，所以不按状态码抛错。
+  return (await res.json()) as T;
+}
+
+/** 第一步：确认当前环境支持 client_secret 认证。 */
+export async function initRegistration(domain: FeishuDomain = "feishu"): Promise<void> {
+  const res = await post<InitResponse>(domain, { action: "init" });
+  if (!res.supported_auth_methods?.includes("client_secret")) {
+    throw new Error("当前环境不支持 client_secret 认证方式");
+  }
+}
+
+/** 第二步：开始设备码流程，拿到给用户扫的二维码地址。 */
+export async function beginRegistration(domain: FeishuDomain = "feishu"): Promise<BeginResult> {
+  const res = await post<BeginResponse>(domain, {
+    action: "begin",
+    archetype: "PersonalAgent",
+    auth_method: "client_secret",
+    request_user_info: "open_id",
+  });
+
+  const url = new URL(res.verification_uri_complete);
+  // 只接受飞书/Lark 自家域名，避免响应被污染后把用户引到别处
+  if (!/(^|\.)(feishu\.cn|larksuite\.com)$/.test(url.hostname)) {
+    throw new Error(`拒绝非飞书域名的验证地址：${url.hostname}`);
+  }
+
+  return {
+    deviceCode: res.device_code,
+    qrUrl: url.toString(),
+    userCode: res.user_code,
+    interval: Number.isFinite(res.interval) ? res.interval : DEFAULT_POLL_INTERVAL_SECONDS,
+    expireIn: Number.isFinite(res.expire_in) ? res.expire_in : DEFAULT_EXPIRE_SECONDS,
+  };
+}
+
+const sleep = (seconds: number) =>
+  new Promise((resolve) => setTimeout(resolve, Math.max(1, seconds) * 1000));
+
+/** 第三步：轮询直到用户在手机上确认。会根据 tenant_brand 自动切换 feishu/lark 域。 */
+export async function pollRegistration(params: {
+  deviceCode: string;
+  interval: number;
+  expireIn: number;
+  domain?: FeishuDomain;
+  onTick?: (secondsLeft: number) => void;
+}): Promise<PollOutcome> {
+  let domain: FeishuDomain = params.domain ?? "feishu";
+  let interval = params.interval;
+  let domainSwitched = false;
+  const deadline = Date.now() + params.expireIn * 1000;
+
+  while (Date.now() < deadline) {
+    let res: PollResponse;
+    try {
+      res = await post<PollResponse>(domain, {
+        action: "poll",
+        device_code: params.deviceCode,
+        tp: "ob_cli_app",
+      });
+    } catch {
+      await sleep(interval); // 网络抖动，继续轮询
+      continue;
+    }
+
+    // 租户在 Lark 侧时自动换域重试一次
+    if (!domainSwitched && res.user_info?.tenant_brand === "lark") {
+      domain = "lark";
+      domainSwitched = true;
+      continue;
+    }
+
+    if (res.client_id && res.client_secret) {
+      return {
+        status: "success",
+        result: {
+          appId: res.client_id,
+          appSecret: res.client_secret,
+          domain,
+          ...(res.user_info?.open_id ? { openId: res.user_info.open_id } : {}),
+        },
+      };
+    }
+
+    if (res.error === "slow_down") interval += 5;
+    else if (res.error === "access_denied") return { status: "access_denied" };
+    else if (res.error === "expired_token") return { status: "expired" };
+    else if (res.error && res.error !== "authorization_pending") {
+      return { status: "error", message: `${res.error}: ${res.error_description ?? "未知错误"}` };
+    }
+
+    params.onTick?.(Math.max(0, Math.round((deadline - Date.now()) / 1000)));
+    await sleep(interval);
+  }
+
+  return { status: "timeout" };
+}
+
+/** 终端里打印二维码。必须无边框输出，加了装饰框会破坏识别。 */
+export async function printQrCode(url: string): Promise<void> {
+  const output = await QRCode.toString(url, { type: "terminal", small: true });
+  process.stdout.write(output.endsWith("\n") ? output : `${output}\n`);
+}
+
+/** 给 Web 页面用的二维码（SVG 字符串）。 */
+export async function qrSvg(url: string): Promise<string> {
+  return QRCode.toString(url, { type: "svg", margin: 1, width: 240 });
+}

package/src/channels/feishu/turn-stream.ts

@@ -0,0 +1,98 @@
+// 一轮对话的输出编排：
+//   过程（思考 / 工具调用）→ 实时刷新的过程卡
+//   最终回复            → 普通消息，可复制可引用，不套卡片
+//
+// 全程串行执行。曾经踩过的坑：过程卡的 send 还没 await 完成，收尾就到了，
+// 于是多发一张卡，而先前那张永远停在中间态。
+export type TurnStreamDeps = {
+  sendCard: (card: unknown) => Promise<string | undefined>;
+  updateCard: (messageId: string, card: unknown) => Promise<boolean>;
+  renderProgress: (steps: string[], done: boolean, footer?: string) => unknown;
+  /** 发送最终回复（普通文本消息） */
+  sendReply: (text: string) => Promise<unknown>;
+  onError?: (err: unknown) => void;
+};
+
+export type TurnStreamOptions = {
+  minIntervalMs?: number;
+  maxEdits?: number;
+  now?: () => number;
+};
+
+export class TurnStream {
+  private steps: string[] = [];
+  private text = "";
+  private messageId: string | undefined;
+  private edits = 0;
+  private lastEdit = 0;
+  private chain: Promise<void> = Promise.resolve();
+
+  private readonly minIntervalMs: number;
+  private readonly maxEdits: number;
+  private readonly now: () => number;
+
+  constructor(
+    private readonly deps: TurnStreamDeps,
+    options: TurnStreamOptions = {},
+  ) {
+    this.minIntervalMs = options.minIntervalMs ?? 2000;
+    this.maxEdits = options.maxEdits ?? 15;
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  private enqueue(fn: () => Promise<void>): void {
+    this.chain = this.chain.then(fn).catch((err) => this.deps.onError?.(err));
+  }
+
+  /** 一条过程信息（思考片段 / 工具调用）。 */
+  addStep(step: string): void {
+    this.steps.push(step);
+    this.enqueue(async () => {
+      const now = this.now();
+      if (now - this.lastEdit < this.minIntervalMs || this.edits >= this.maxEdits) return;
+      this.lastEdit = now;
+      const card = this.deps.renderProgress(this.steps, false);
+      if (!this.messageId) {
+        this.messageId = await this.deps.sendCard(card);
+        return;
+      }
+      this.edits += 1;
+      await this.deps.updateCard(this.messageId, card);
+    });
+  }
+
+  /** 回复正文片段，累积起来备用。 */
+  addText(text: string): void {
+    this.text += text;
+  }
+
+  /**
+   * 收尾：过程卡定格为完成态，然后把最终回复作为普通消息发出去。
+   * 整轮没有过程时不会留下任何卡片 —— 简单问答就该只有一条回复。
+   */
+  finish(finalText: string, footer?: string): void {
+    this.enqueue(async () => {
+      if (this.messageId) {
+        await this.deps.updateCard(
+          this.messageId,
+          this.deps.renderProgress(this.steps, true, footer),
+        );
+      }
+      const reply = finalText.trim() || this.text.trim();
+      if (reply) await this.deps.sendReply(reply);
+      this.reset();
+    });
+  }
+
+  private reset(): void {
+    this.steps = [];
+    this.text = "";
+    this.messageId = undefined;
+    this.edits = 0;
+    this.lastEdit = 0;
+  }
+
+  async drain(): Promise<void> {
+    await this.chain;
+  }
+}