🤖 Open-source, local-first alternative to Grok Bot, OpenAI dots and Claude Duet. Your own AI bots on any model: GPT, Claude, Gemini, Grok, DeepSeek, Kimi, GLM and 70+ more through one Modelflare key. Reach them in the app, WeChat or Feishu; they remember you, work in the background, run commands and use your computer. Pay per use.
Python ai-agentai-assistantchatbotclaudecomputer-usedeepseekdesktop-appdshelectronfeishugeminigptgrokllmlocal-firstmodelflaremulti-modelopenai-compatiblepersonal-ai-agentwechat
/**
* 飞书账号(accounts.ts):用用户身份读这个人能看到的会话和消息,只读。和飞书聊天渠道(channels/feishu)是两回事:
* 渠道账号用的是一个机器人应用,只能看到发给这个应用的消息。
*
* 添加账号(和官方 lark-cli 同一套流程):
* 1. 一键授权:用飞书扫码,飞书替用户创建一个个人应用,回 App ID 和 Secret。也可以填已有的自建应用,跳过这一步。
* 2. 设备授权:用户再确认一次,把读消息的权限授给这个应用,回 user_access_token 和 refresh token。
* 页面和桌面版都轮询流程状态(flow),不需要回调地址。
*/
import crypto from "node:crypto";
import QRCode from "qrcode";
import { logger } from "../log.js";
import { AccountStore, ConnectionError, LocalizedConnectionError, capped, clampLimit, wait, type ConnectedAccount, type FeishuBrand, type FeishuUserAuth } from "./accounts.js";
const log = logger("agent.feishu-account");
const HOSTS: Record<FeishuBrand, { accounts: string; open: string }> = {
feishu: { accounts: "https://accounts.feishu.cn", open: "https://open.feishu.cn" },
lark: { accounts: "https://accounts.larksuite.com", open: "https://open.larksuite.com" },
};
/** 读会话、读群聊和单聊消息、搜消息;offline_access 才有 refresh token */
export const FEISHU_SCOPES = "offline_access im:chat:read im:message.group_msg:get_as_user im:message.p2p_msg:get_as_user search:message";
const TIMEOUT_MS = 30_000;
const REFRESH_MARGIN_MS = 5 * 60_000;
const MAX_POLL_S = 60;
/** 飞书说令牌无效或过期的错误码:换一次令牌再试 */
const TOKEN_CODES = new Set([99991663, 99991668, 99991677, 20005]);
const RECONNECT = "Ask the user to re-authorize this account in Settings > Connections.";
/** 模型给的时间(ISO 或日期)转成秒。空就不限 */
function seconds(v: unknown, name: string): string | undefined {
if (typeof v !== "string" || !v.trim()) return undefined;
const ms = Date.parse(v.trim());
if (Number.isNaN(ms)) throw new ConnectionError(`${name} isn't a date. Use a form like 2026-11-01 or 2026-11-01T09:00:00+08:00.`, 400);
return String(Math.floor(ms / 1000));
}
/** 消息内容转成一行文字。飞书的内容是 JSON,各类型结构不同;图片、文件这些只说是什么 */
export function messageText(m: any): string {
if (m?.deleted) return "[deleted]";
const type = String(m?.msg_type ?? "");
let body: any;
try {
body = JSON.parse(String(m?.body?.content ?? ""));
} catch {
return String(m?.body?.content ?? "");
}
let text: string;
switch (type) {
case "text":
text = String(body?.text ?? "");
break;
case "post": {
const post = body?.content ? body : (Object.values(body ?? {})[0] as any);
const lines = (Array.isArray(post?.content) ? post.content : []).map((line: any[]) =>
(Array.isArray(line) ? line : []).map((el) => el?.text ?? (el?.tag === "img" ? "[image]" : el?.user_name ?? "")).join(""),
);
text = [post?.title, ...lines].filter(Boolean).join("\n");
break;
}
case "image":
text = "[image]";
break;
case "file":
text = `[file: ${body?.file_name ?? ""}]`;
break;
case "audio":
text = "[voice message]";
break;
case "media":
text = `[video: ${body?.file_name ?? ""}]`;
break;
case "sticker":
text = "[sticker]";
break;
case "interactive":
text = "[card message]";
break;
case "merge_forward":
text = "[forwarded messages]";
break;
case "system":
text = "[system message]";
break;
default:
text = `[${type || "message"}]`;
}
for (const mention of Array.isArray(m?.mentions) ? m.mentions : []) {
if (mention?.key && mention?.name) text = text.replaceAll(mention.key, `@${mention.name}`);
}
return text;
}
function messageLine(m: any, withChat = false): string {
const when = new Date(Number(m?.create_time) || 0).toISOString().slice(0, 16).replace("T", " ");
const who = m?.sender?.sender_name ?? m?.sender?.name ?? m?.sender?.id ?? "unknown";
return `[${when} UTC] ${who}${withChat && m?.chat_id ? ` (chat ${m.chat_id})` : ""}: ${messageText(m)}`;
}
export type FeishuFlowState = "create-app" | "authorize" | "done" | "failed";
export interface FeishuFlowView {
id: string;
state: FeishuFlowState;
/** 要用户打开或扫码的地址 */
url: string;
qr: string;
error: string;
label: string;
}
interface Flow extends Omit<FeishuFlowView, "error"> {
failure?: LocalizedConnectionError;
abort: AbortController;
}
export interface FeishuAccountsOptions {
accounts: AccountStore;
fetch?: () => typeof fetch | undefined;
timeoutMs?: number;
}
export class FeishuAccounts {
private refreshing = new Map<string, Promise<string>>();
private flows = new Map<string, Flow>();
constructor(private o: FeishuAccountsOptions) {}
private send(): typeof fetch {
return this.o.fetch?.() ?? fetch;
}
private deadline(signal?: AbortSignal): AbortSignal {
const timer = AbortSignal.timeout(this.o.timeoutMs ?? TIMEOUT_MS);
return signal ? AbortSignal.any([signal, timer]) : timer;
}
/** 执行一次工具调用,回给模型看的文字 */
async run(account: ConnectedAccount, op: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<string> {
switch (op) {
case "chats":
return this.chats(account, args, signal);
case "read":
return this.read(account, args, signal);
case "search":
return this.search(account, args, signal);
default:
throw new ConnectionError(`Unknown Feishu operation: ${op}`);
}
}
private async chats(account: ConnectedAccount, args: Record<string, unknown>, signal?: AbortSignal): Promise<string> {
const size = clampLimit(args.limit, 20, 100);
const cursor = typeof args.cursor === "string" && args.cursor ? `&page_token=${encodeURIComponent(args.cursor)}` : "";
const query = typeof args.query === "string" ? args.query.trim() : "";
const data = query
? await this.api(account, "POST", `/open-apis/im/v2/chats/search?page_size=${size}${cursor}`, { query }, signal)
: await this.api(account, "GET", `/open-apis/im/v1/chats?page_size=${size}&sort_type=ByActiveTimeDesc&types=p2p,group&user_id_type=open_id${cursor}`, undefined, signal);
const items: any[] = (Array.isArray(data?.items) ? data.items : []).map((x: any) => x?.meta_data ?? x);
if (!items.length) return "No chats found.";
return capped(
[
...items.map((c) => `- ${c?.name || "(direct message)"} | ${c?.chat_mode ?? "chat"} | chat_id: ${c?.chat_id}`),
...(data?.has_more && data?.page_token ? [`More chats: call again with cursor "${data.page_token}".`] : []),
].join("\n"),
);
}
private async read(account: ConnectedAccount, args: Record<string, unknown>, signal?: AbortSignal): Promise<string> {
const chat = typeof args.chat_id === "string" ? args.chat_id.trim() : "";
if (!chat) throw new ConnectionError("Missing chat_id. feishu_list_chats lists the chats.", 400);
const params = new URLSearchParams({
container_id_type: "chat",
container_id: chat,
sort_type: "ByCreateTimeDesc",
page_size: String(clampLimit(args.limit, 20, 50)),
card_msg_content_type: "raw_card_content",
with_sender_name: "true",
user_id_type: "open_id",
});
const start = seconds(args.start, "start");
const end = seconds(args.end, "end");
if (start) params.set("start_time", start);
if (end) params.set("end_time", end);
if (typeof args.cursor === "string" && args.cursor) params.set("page_token", args.cursor);
const data = await this.api(account, "GET", `/open-apis/im/v1/messages?${params}`, undefined, signal);
const items: any[] = Array.isArray(data?.items) ? data.items : [];
if (!items.length) return "No messages in this chat for that time.";
return capped(
[
"Newest first:",
...items.map((m) => messageLine(m)),
...(data?.has_more && data?.page_token ? [`Older messages: call again with cursor "${data.page_token}".`] : []),
].join("\n"),
);
}
private async search(account: ConnectedAccount, args: Record<string, unknown>, signal?: AbortSignal): Promise<string> {
const filter: Record<string, unknown> = {};
const time: Record<string, string> = {};
if (seconds(args.start, "start")) time.start_time = String(args.start).trim();
if (seconds(args.end, "end")) time.end_time = String(args.end).trim();
if (Object.keys(time).length) filter.time_range = time;
if (typeof args.chat_id === "string" && args.chat_id.trim()) filter.chat_ids = [args.chat_id.trim()];
const cursor = typeof args.cursor === "string" && args.cursor ? `&page_token=${encodeURIComponent(args.cursor)}` : "";
const found = await this.api(
account,
"POST",
`/open-apis/im/v1/messages/search?page_size=${clampLimit(args.limit, 20, 50)}${cursor}`,
{ query: typeof args.query === "string" ? args.query : "", ...(Object.keys(filter).length ? { filter } : {}) },
signal,
);
const ids: string[] = (Array.isArray(found?.items) ? found.items : []).map((x: any) => x?.meta_data?.message_id).filter(Boolean);
if (!ids.length) return "No matching messages.";
const params = new URLSearchParams({ card_msg_content_type: "raw_card_content", with_sender_name: "true", user_id_type: "open_id" });
for (const id of ids) params.append("message_ids", id);
const details = await this.api(account, "GET", `/open-apis/im/v1/messages/mget?${params}`, undefined, signal);
const items: any[] = Array.isArray(details?.items) ? details.items : [];
return capped(
[
...items.map((m) => messageLine(m, true)),
...(found?.has_more && found?.page_token ? [`More results: call again with cursor "${found.page_token}".`] : []),
].join("\n"),
);
}
private auth(account: ConnectedAccount): FeishuUserAuth {
const auth = this.o.accounts.get(account.id)?.auth ?? account.auth;
if (auth.kind !== "feishu-user") throw new ConnectionError("This isn't a Feishu account.");
return auth;
}
private async api(account: ConnectedAccount, method: string, path: string, body: unknown, signal: AbortSignal | undefined): Promise<any> {
const route = path.split("?")[0];
for (let attempt = 0; ; attempt++) {
const auth = this.auth(account);
const token = await this.token(account, signal, attempt > 0);
let res: Response;
try {
res = await this.send()(HOSTS[auth.brand].open + path, {
method,
headers: { authorization: `Bearer ${token}`, ...(body === undefined ? {} : { "content-type": "application/json; charset=utf-8" }) },
...(body === undefined ? {} : { body: JSON.stringify(body) }),
signal: this.deadline(signal),
});
} catch (e) {
if (signal?.aborted) throw e;
log.warn("feishu request failed", { route });
throw new ConnectionError("Could not reach Feishu. Try again in a moment.");
}
const data: any = await res.json().catch(() => undefined);
const code = Number(data?.code ?? (res.ok ? 0 : res.status));
if (code === 0) {
if (this.o.accounts.get(account.id)?.needsReauth) this.o.accounts.update(account.id, { needsReauth: false });
return data?.data;
}
if ((TOKEN_CODES.has(code) || res.status === 401) && attempt === 0) continue;
log.warn("feishu request refused", { route, status: res.status, code });
if (TOKEN_CODES.has(code) || res.status === 401) {
this.o.accounts.update(account.id, { needsReauth: true });
throw new ConnectionError(`Feishu rejected this account's sign-in. ${RECONNECT}`, 401);
}
throw new ConnectionError(`Feishu refused the request (${code}): ${String(data?.msg ?? "").slice(0, 300)}`, res.status);
}
}
private token(account: ConnectedAccount, signal: AbortSignal | undefined, force: boolean): Promise<string> {
const auth = this.auth(account);
if (!force && auth.expiresAt - Date.now() > REFRESH_MARGIN_MS) return Promise.resolve(auth.accessToken);
let job = this.refreshing.get(account.id);
if (!job) {
job = this.refresh(account, signal).finally(() => this.refreshing.delete(account.id));
this.refreshing.set(account.id, job);
}
return job;
}
/** 换令牌。refresh token 每次都会变,同一账号排队,新的马上落盘 */
private async refresh(account: ConnectedAccount, signal: AbortSignal | undefined): Promise<string> {
const auth = this.auth(account);
let data: any;
let status = 0;
try {
const res = await this.send()(`${HOSTS[auth.brand].open}/open-apis/authen/v2/oauth/token`, {
method: "POST",
headers: { "content-type": "application/json; charset=utf-8" },
body: JSON.stringify({ grant_type: "refresh_token", refresh_token: auth.refreshToken, client_id: auth.appId, client_secret: auth.appSecret }),
signal: this.deadline(signal),
});
status = res.status;
data = await res.json().catch(() => undefined);
} catch (e) {
if (signal?.aborted) throw e;
throw new ConnectionError("Could not reach Feishu. Try again in a moment.");
}
if (data?.access_token) {
this.o.accounts.update(account.id, {
needsReauth: false,
auth: { ...auth, accessToken: data.access_token, refreshToken: data.refresh_token || auth.refreshToken, expiresAt: Date.now() + (Number(data.expires_in) || 7200) * 1000 },
});
return data.access_token;
}
if (status >= 500 || status === 429) throw new ConnectionError("Feishu is temporarily unavailable. Try again in a moment.", status);
log.warn("feishu token refresh failed", { status, code: String(data?.code ?? data?.error ?? "") });
this.o.accounts.update(account.id, { needsReauth: true });
throw new ConnectionError(`This Feishu account's authorization has expired. ${RECONNECT}`, 401);
}
// ---------- 添加账号 ----------
/** 开始添加:给了 App ID 和 Secret 就用已有的应用,否则一键创建 */
startFlow(app?: { appId: string; appSecret: string; brand?: FeishuBrand }): FeishuFlowView {
return this.launch(app ? "authorize" : "create-app", (flow) => this.runFlow(flow, app));
}
/** 飞书聊天账号:只扫码创建应用,不要用户授权(聊天用的是应用身份)。done 把应用连上,回账号的名字 */
startAppFlow(done: (app: { appId: string; appSecret: string; brand: FeishuBrand }) => Promise<string>): FeishuFlowView {
return this.launch("create-app", async (flow) => {
const app = await this.createApp(flow, flow.abort.signal);
flow.label = await done(app);
flow.url = "";
flow.qr = "";
flow.state = "done";
});
}
private launch(state: FeishuFlowState, run: (flow: Flow) => Promise<void>): FeishuFlowView {
for (const [k, f] of this.flows) if (f.state === "done" || f.state === "failed") this.flows.delete(k);
const flow: Flow = { id: crypto.randomBytes(12).toString("hex"), state, url: "", qr: "", label: "", abort: new AbortController() };
this.flows.set(flow.id, flow);
run(flow).catch((e) => {
if (flow.abort.signal.aborted) return;
flow.state = "failed";
flow.failure = e instanceof LocalizedConnectionError ? e : new LocalizedConnectionError("connections.feishuAuthIncomplete");
log.warn("feishu flow failed", { reason: e instanceof Error ? e.message : String(e) });
});
return this.view(flow);
}
flow(id: string): FeishuFlowView | undefined {
const f = this.flows.get(id);
return f && this.view(f);
}
cancelFlow(id: string): void {
this.flows.get(id)?.abort.abort();
this.flows.delete(id);
}
private view(f: Flow): FeishuFlowView {
return { id: f.id, state: f.state, url: f.url, qr: f.qr, error: f.failure?.userMessage() ?? "", label: f.label };
}
private async showUrl(flow: Flow, state: FeishuFlowState, url: string): Promise<void> {
flow.state = state;
flow.url = url;
flow.qr = await QRCode.toDataURL(url, { margin: 1, width: 320 });
}
private async form(url: string, fields: Record<string, string>, signal: AbortSignal, headers: Record<string, string> = {}): Promise<{ status: number; data: any }> {
const res = await this.send()(url, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded", ...headers },
body: new URLSearchParams(fields).toString(),
signal: this.deadline(signal),
});
return { status: res.status, data: await res.json().catch(() => undefined) };
}
private async runFlow(flow: Flow, app?: { appId: string; appSecret: string; brand?: FeishuBrand }): Promise<void> {
const signal = flow.abort.signal;
const creds = app ? { appId: app.appId, appSecret: app.appSecret, brand: app.brand ?? ("feishu" as FeishuBrand) } : await this.createApp(flow, signal);
const tokens = await this.authorize(flow, creds, signal);
const me = await this.send()(`${HOSTS[creds.brand].open}/open-apis/authen/v1/user_info`, { headers: { authorization: `Bearer ${tokens.accessToken}` }, signal: this.deadline(signal) })
.then((r) => r.json())
.catch(() => undefined);
const info = (me as any)?.data ?? {};
const account = this.o.accounts.upsert({
service: "feishu",
label: String(info.name || info.en_name || "Feishu"),
identity: `${creds.brand}:${info.open_id || crypto.createHash("sha256").update(tokens.refreshToken).digest("hex").slice(0, 16)}`,
auth: { kind: "feishu-user", brand: creds.brand, appId: creds.appId, appSecret: creds.appSecret, ...tokens },
});
flow.label = account.label;
flow.url = "";
flow.qr = "";
flow.state = "done";
log.info("feishu account added", { brand: creds.brand });
}
/** 第 1 步:飞书替用户创建个人应用。飞书和 Lark 从同一个入口开始,轮询时飞书会告诉我们该换到哪个品牌 */
private async createApp(flow: Flow, signal: AbortSignal): Promise<{ appId: string; appSecret: string; brand: FeishuBrand }> {
const begin = await this.form(`${HOSTS.feishu.accounts}/oauth/v1/app/registration`, { action: "begin", archetype: "PersonalAgent", auth_method: "client_secret", request_user_info: "open_id tenant_brand" }, signal);
const device = String(begin.data?.device_code ?? "");
if (!device) throw new LocalizedConnectionError("connections.feishuStartRefused");
// 官方 CLI 也是自己拼这个页面地址,不用接口回的 verification_uri
await this.showUrl(flow, "create-app", begin.data.user_code ? `${HOSTS.feishu.open}/page/cli?user_code=${encodeURIComponent(String(begin.data.user_code))}&from=cli` : String(begin.data.verification_uri_complete ?? begin.data.verification_uri ?? ""));
let brand: FeishuBrand = "feishu";
let interval = Number(begin.data.interval) || 5;
const until = Date.now() + (Number(begin.data.expire_in ?? begin.data.expires_in) || 600) * 1000;
let first = false;
while (Date.now() < until) {
if (first) await wait(interval * 1000, signal);
first = true;
let data: any;
try {
data = (await this.form(`${HOSTS[brand].accounts}/oauth/v1/app/registration`, { action: "poll", device_code: device }, signal)).data;
} catch (e) {
if (signal.aborted) throw e;
interval = Math.min(interval + 1, MAX_POLL_S);
continue;
}
const tenant = data?.user_info?.tenant_brand;
if ((tenant === "lark" || tenant === "feishu") && tenant !== brand) {
brand = tenant;
first = false;
continue;
}
if (data?.client_id && data?.client_secret) return { appId: String(data.client_id), appSecret: String(data.client_secret), brand };
switch (data?.error) {
case undefined:
case "authorization_pending":
break;
case "slow_down":
interval = Math.min(interval + 5, MAX_POLL_S);
break;
case "access_denied":
throw new LocalizedConnectionError("connections.feishuDeclined");
default:
throw new LocalizedConnectionError("connections.feishuQrExpired");
}
}
throw new LocalizedConnectionError("connections.feishuQrExpired");
}
/** 第 2 步:设备授权,用户确认后拿到用户身份的令牌 */
private async authorize(flow: Flow, app: { appId: string; appSecret: string; brand: FeishuBrand }, signal: AbortSignal): Promise<{ accessToken: string; refreshToken: string; expiresAt: number }> {
const basic = Buffer.from(`${app.appId}:${app.appSecret}`).toString("base64");
const begin = await this.form(`${HOSTS[app.brand].accounts}/oauth/v1/device_authorization`, { client_id: app.appId, scope: FEISHU_SCOPES }, signal, { authorization: `Basic ${basic}` });
if (!begin.data?.device_code) {
log.warn("feishu device authorization refused", { status: begin.status, error: String(begin.data?.error ?? begin.data?.code ?? "") });
throw new LocalizedConnectionError("connections.feishuAppRefused");
}
await this.showUrl(flow, "authorize", String(begin.data.verification_uri_complete || begin.data.verification_uri));
let interval = Number(begin.data.interval) || 5;
const until = Date.now() + (Number(begin.data.expires_in) || 240) * 1000;
while (Date.now() < until) {
await wait(interval * 1000, signal);
let data: any;
try {
data = (await this.form(`${HOSTS[app.brand].open}/open-apis/authen/v2/oauth/token`, { grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code: String(begin.data.device_code), client_id: app.appId, client_secret: app.appSecret }, signal)).data;
} catch (e) {
if (signal.aborted) throw e;
interval = Math.min(interval + 1, MAX_POLL_S);
continue;
}
if (data?.access_token) {
if (!data.refresh_token) throw new LocalizedConnectionError("connections.feishuNoRefreshToken");
return { accessToken: data.access_token, refreshToken: data.refresh_token, expiresAt: Date.now() + (Number(data.expires_in) || 7200) * 1000 };
}
switch (data?.error) {
case "authorization_pending":
break;
case "slow_down":
interval = Math.min(interval + 5, MAX_POLL_S);
break;
case "access_denied":
throw new LocalizedConnectionError("connections.feishuDeclined");
case "expired_token":
case "invalid_grant":
throw new LocalizedConnectionError("connections.feishuAuthExpired");
default:
log.warn("feishu token poll refused", { code: String(data?.code ?? ""), error: String(data?.error ?? "") });
throw new LocalizedConnectionError("connections.feishuAuthIncomplete");
}
}
throw new LocalizedConnectionError("connections.feishuAuthExpired");
}
}