@turingflow/agent-kit 0.0.0-stage → 0.1.1

package/dist/server/auth/handlers.d.ts

@@ -0,0 +1,27 @@
+import type { AuthConfig, SessionUser } from "./types.js";
+/** 校验请求中的会话 Cookie，返回 SessionUser 或 null。 */
+export declare function verifySession(request: Request, config: AuthConfig): SessionUser | null;
+/** 便捷方法：自动读取认证配置并校验会话。 */
+export declare function getSessionUser(request: Request): SessionUser | null;
+export interface LoginHandlers {
+    login: {
+        GET: (request: Request) => Promise<Response> | Response;
+    };
+    callback: {
+        GET: (request: Request) => Promise<Response> | Response;
+    };
+    sso: {
+        POST: (request: Request) => Promise<Response> | Response;
+    };
+    session: {
+        GET: (request: Request) => Promise<Response> | Response;
+    };
+    logout: {
+        POST: (request: Request) => Promise<Response> | Response;
+    };
+}
+export interface LoginHandlersOptions {
+    /** 覆盖从 env 读取的认证配置（测试注入用） */
+    config?: AuthConfig;
+}
+export declare function createLoginHandlers(options?: LoginHandlersOptions): LoginHandlers;

package/dist/server/auth/handlers.js

@@ -0,0 +1,297 @@
+/**
+ * agent-kit · 登录路由工厂（Next.js App Router）
+ *
+ * 第三方 Next.js 工程一行引入即可获得完整登录能力，无需重写 OAuth / 回调 / 免登 / 会话 /
+ * 登出逻辑：
+ *
+ *   // app/api/auth/login/route.js
+ *   import { createLoginHandlers } from "agent-kit";
+ *   export const runtime = "nodejs";
+ *   export const { GET } = createLoginHandlers().login;
+ *
+ *   // app/api/auth/callback/route.js  -> .callback
+ *   // app/api/auth/sso/route.js       -> .sso
+ *   // app/api/auth/session/route.js   -> .session
+ *   // app/api/auth/logout/route.js    -> .logout
+ *
+ * 设计要点：
+ *   - 采用标准 Web Response + 手写 Set-Cookie，不依赖 next/server，保证 agent-kit 自包含、可复用；
+ *   - 仅暴露 AuthProvider 抽象与归一化 AuthUser，不感知钉钉/飞书差异；
+ *   - 数据库落库（users 表 upsert）在已配置 Postgres 时生效。
+ */
+import { loadAuthConfig } from "./config.js";
+import { createSessionToken, verifySessionToken, toSessionUser, generateState, sessionCookieOptions, stateCookieOptions, } from "./session.js";
+import { createProvider, createProviderFor } from "./providers/index.js";
+import { getLoginOptions } from "./login-options.js";
+import { upsertUser, touchLastLogin, isDbEnabled } from "./db.js";
+const SESSION_COOKIE = "agent_session";
+const STATE_COOKIE = "agent_oauth_state";
+const NEXT_COOKIE = "agent_login_next";
+// ----------------------------- Cookie 工具（手写，避免引入 next/server） -----------------------------
+function getCookie(request, name) {
+    const header = request.headers.get("cookie");
+    if (!header)
+        return undefined;
+    for (const part of header.split(";")) {
+        const idx = part.indexOf("=");
+        if (idx < 0)
+            continue;
+        const key = part.slice(0, idx).trim();
+        if (key === name)
+            return decodeURIComponent(part.slice(idx + 1).trim());
+    }
+    return undefined;
+}
+function setCookie(headers, name, value, opts) {
+    const parts = [
+        `${name}=${encodeURIComponent(value)}`,
+        `Path=${opts.path}`,
+        `Max-Age=${opts.maxAge}`,
+        "HttpOnly",
+        "SameSite=Lax",
+    ];
+    if (opts.secure)
+        parts.push("Secure");
+    headers.append("Set-Cookie", parts.join("; "));
+}
+function clearCookie(headers, name, path, secure = false) {
+    const parts = [`${name}=`, `Path=${path}`, "Max-Age=0", "HttpOnly"];
+    // 必须与下发时一致（secure 时 SameSite=None 才能匹配清除 Secure Cookie）
+    parts.push(secure ? "SameSite=None" : "SameSite=Lax");
+    if (secure)
+        parts.push("Secure");
+    headers.append("Set-Cookie", parts.join("; "));
+}
+/** 解析对外 origin：优先 env（APP_PUBLIC_URL），否则用请求头（x-forwarded-host / host）推断。
+ *  注意：不能依赖 `new URL(request.url).origin`——Next.js dev 模式下 request.url 的 host 固定为
+ *  localhost（忽略实际 Host header），会导致回调地址与真实访问地址不一致。 */
+function publicOrigin(request, config) {
+    if (config.publicUrl)
+        return config.publicUrl;
+    const proto = request.headers.get("x-forwarded-proto") || "http";
+    const host = request.headers.get("x-forwarded-host") || request.headers.get("host");
+    if (host)
+        return `${proto}://${host}`;
+    try {
+        return new URL(request.url).origin;
+    }
+    catch {
+        return `${proto}://localhost`;
+    }
+}
+function redirect(url) {
+    return new Response(null, { status: 302, headers: { Location: url } });
+}
+function safeNext(value, config) {
+    // 防止开放重定向：仅允许跳回本站 basePath 下的路径
+    const prefix = config.cookiePath; // 通常等于 basePath
+    // 兜底必须去尾斜杠再拼，避免 cookiePath="/" 时拼出 "//"（protocol-relative URL，
+    // new URL("//", base) 抛 Invalid URL，导致登录成功后回跳失败）
+    const fallback = `${prefix.replace(/\/+$/, "")}/`;
+    return value && value.startsWith(prefix) ? value : fallback;
+}
+function loginError(request, config, reason) {
+    const url = new URL(`${publicOrigin(request, config)}${config.cookiePath.replace(/\/+$/, "")}/login`);
+    url.searchParams.set("error", reason);
+    return redirect(url.toString());
+}
+// ----------------------------- 会话读取 -----------------------------
+/** 校验请求中的会话 Cookie，返回 SessionUser 或 null。 */
+export function verifySession(request, config) {
+    return verifySessionToken(getCookie(request, SESSION_COOKIE), config.sessionSecret);
+}
+/** 便捷方法：自动读取认证配置并校验会话。 */
+export function getSessionUser(request) {
+    return verifySession(request, loadAuthConfig());
+}
+// ----------------------------- 登录后置：落库 + 写会话 -----------------------------
+async function finalizeLogin(authUser, request, config, next) {
+    // 落库仅用于同步企业档案 / OAuth 令牌（users 表）；用户主体键一律用 provider 侧
+    // 标识（sub = provider:unionId），不再把内部自增 id 写进会话。
+    if (isDbEnabled()) {
+        try {
+            const dbUser = await upsertUser(authUser);
+            if (dbUser)
+                await touchLastLogin(dbUser.id);
+        }
+        catch (e) {
+            console.error("[agent-kit auth] user upsert failed (login continues)", e instanceof Error ? e.message : e);
+        }
+    }
+    const sessionUser = toSessionUser(authUser);
+    const token = createSessionToken(sessionUser, config.sessionSecret);
+    const headers = new Headers();
+    setCookie(headers, SESSION_COOKIE, token, sessionCookieOptions(config.cookiePath, config.secureCookie));
+    clearCookie(headers, STATE_COOKIE, config.cookiePath, config.secureCookie);
+    clearCookie(headers, NEXT_COOKIE, config.cookiePath, config.secureCookie);
+    // 客户端免登（sso）返回 JSON；网页 OAuth 回调返回重定向。
+    // 注意：两个分支都必须携带同一组 headers（含会话 Set-Cookie）——直接复用 Headers 实例，
+    // 不能用 Object.fromEntries 展开（多个 Set-Cookie 会被合并破坏）。
+    const isSso = request.method === "POST";
+    if (isSso) {
+        headers.set("Content-Type", "application/json");
+        return new Response(JSON.stringify({ ok: true, next }), {
+            status: 200,
+            headers,
+        });
+    }
+    headers.set("Location", new URL(next, publicOrigin(request, config)).toString());
+    return new Response(null, { status: 302, headers });
+}
+export function createLoginHandlers(options = {}) {
+    const config = options.config ?? loadAuthConfig();
+    const mainProvider = createProvider(config);
+    // 按指定方式执行登录：dingtalk/feishu → 跳 OAuth 授权页（dev 免登已移除）。
+    // builtin（自建账号体系）留口子：登录系统尚未实现，这里直接返回 config 错误；
+    // 后续实现时在此分支加入「校验用户名密码 → finalizeLogin」即可。
+    function loginWith(request, id) {
+        if (id !== "dingtalk" && id !== "feishu")
+            return loginError(request, config, "config");
+        const provider = createProviderFor(config, id);
+        if (!provider)
+            return loginError(request, config, "config");
+        const state = generateState();
+        const origin = publicOrigin(request, config);
+        // cookiePath 去尾斜杠再拼，避免 "/" 时拼出 "//api/auth/callback"
+        const callbackBase = `${origin}${config.cookiePath.replace(/\/+$/, "")}/api/auth/callback`;
+        const redirectUri = id === "dingtalk"
+            ? config.dingtalk.redirectUri || callbackBase
+            : config.feishu.redirectUri || callbackBase;
+        const authUrl = provider.getAuthorizeUrl(redirectUri, state);
+        // 诊断锚点：打印实际回调 URI，便于核对应用后台「重定向 URL」白名单是否包含它
+        //（白名单不匹配是 OAuth code 换取失败的最常见原因：返回 200 + 无 access_token）
+        console.log(`[agent-kit auth] ${id} login redirect redirect_uri=${redirectUri} clientId=${config.dingtalk.clientId || config.feishu.appId ? "set" : "missing"}`);
+        const headers = new Headers();
+        // state cookie 携带 provider 前缀（adaptive 模式回调时据此路由到对应平台）：
+        //   值格式 `${id}:${state}`；旧格式（无前缀，单方式遗留 cookie）回调时回退 mainProvider
+        setCookie(headers, STATE_COOKIE, `${id}:${state}`, stateCookieOptions(config.cookiePath, config.secureCookie));
+        const next = safeNext(new URL(request.url).searchParams.get("next") || "", config);
+        setCookie(headers, NEXT_COOKIE, next, stateCookieOptions(config.cookiePath, config.secureCookie));
+        headers.set("Location", authUrl);
+        return new Response(null, { status: 302, headers });
+    }
+    // GET /api/auth/login：
+    //   - ?provider=xxx：按指定方式（登录页选择器按钮发出）
+    //   - 无 provider：AUTH_PROVIDER 只有一个真实方式 → 直接跳转；
+    //     多个 → 返回清单（登录页渲染选择器）；无 → 配置错误
+    function loginGET(request) {
+        const requested = new URL(request.url).searchParams.get("provider")?.toLowerCase() || "";
+        if (requested)
+            return loginWith(request, requested);
+        const options = getLoginOptions(config);
+        const total = options.providers.length;
+        if (total === 0)
+            return loginError(request, config, "config");
+        if (total === 1) {
+            return loginWith(request, options.providers[0].id);
+        }
+        // 多登录方式：正常由登录页选择器带 ?provider= 请求；这里兜底返回清单
+        return new Response(JSON.stringify({ message: "请选择登录方式", providers: options.providers }), { status: 200, headers: { "Content-Type": "application/json" } });
+    }
+    // GET /api/auth/callback：OAuth 回跳，用 code 换用户 → 落库 → 写会话 → 重定向
+    async function callbackGET(request) {
+        const url = new URL(request.url);
+        const code = url.searchParams.get("authCode") || url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+        const expectedState = getCookie(request, STATE_COOKIE);
+        if (!code || !state || !expectedState || state !== expectedState.split(":").slice(1).join(":")) {
+            return loginError(request, config, "state");
+        }
+        try {
+            // adaptive 模式：state cookie 带 `${provider}:` 前缀，据此路由到对应平台；
+            // 旧格式（无前缀，单方式遗留 cookie）回退 mainProvider
+            const prefix = expectedState.split(":")[0];
+            const provider = prefix === "dingtalk" || prefix === "feishu" ? createProviderFor(config, prefix) : mainProvider;
+            if (!provider)
+                return loginError(request, config, "config");
+            const authUser = await provider.exchangeOAuthCode(code);
+            const next = safeNext(getCookie(request, NEXT_COOKIE), config);
+            return await finalizeLogin(authUser, request, config, next);
+        }
+        catch (e) {
+            console.error("[agent-kit auth] login callback failed", e);
+            return loginError(request, config, "network");
+        }
+    }
+    // POST /api/auth/sso：客户端内 JSAPI 免登（钉钉/飞书），body { code, next, provider? }
+    async function ssoPOST(request) {
+        const body = (await request.json().catch(() => ({})));
+        const requested = body.provider?.toLowerCase();
+        const targetId = requested === "dingtalk" || requested === "feishu"
+            ? requested
+            : config.method === "dingtalk" || config.method === "feishu"
+                ? config.method
+                : null;
+        const provider = targetId ? createProviderFor(config, targetId) : mainProvider;
+        if (!provider || !provider.exchangeClientCode) {
+            return new Response(JSON.stringify({ message: "当前认证方式不支持客户端免登" }), {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        if (!body.code) {
+            return new Response(JSON.stringify({ message: "缺少免登码" }), {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        try {
+            const authUser = await provider.exchangeClientCode(body.code);
+            const next = safeNext(body.next || "", config);
+            return await finalizeLogin(authUser, request, config, next);
+        }
+        catch (e) {
+            console.error("[agent-kit auth] client SSO failed", e);
+            return new Response(JSON.stringify({ message: "免登失败，请重试" }), {
+                status: 401,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+    }
+    // GET /api/auth/session：返回当前会话状态
+    async function sessionGET(request) {
+        const user = verifySession(request, config);
+        if (!user) {
+            // 诊断锚点：未登录时区分「请求没带 cookie」与「cookie 无效（签名/过期/secret 变化）」
+            const raw = getCookie(request, SESSION_COOKIE);
+            console.log(`[agent-kit auth] session unauthenticated: cookie=${raw ? "present" : "absent"}` +
+                (raw ? ` len=${raw.length}` : "") +
+                ` origin=${request.headers.get("origin") ?? "same"} cookiePath=${config.cookiePath}`);
+            return new Response(JSON.stringify({ authenticated: false }), {
+                status: 401,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
+        return new Response(JSON.stringify({
+            authenticated: true,
+            user: {
+                name: user.name,
+                avatar: user.avatar,
+                provider: user.provider,
+                sub: user.sub,
+                unionId: user.unionId,
+            },
+        }), { status: 200, headers: { "Content-Type": "application/json" } });
+    }
+    // POST /api/auth/logout：清除会话 Cookie
+    async function logoutPOST() {
+        const headers = new Headers();
+        clearCookie(headers, SESSION_COOKIE, config.cookiePath);
+        // Headers → 普通对象（forEach 兼容 undici-types 与 lib.dom 的 Headers 类型差异）
+        const headerObj = {};
+        headers.forEach((value, key) => {
+            headerObj[key] = value;
+        });
+        return new Response(JSON.stringify({ ok: true }), {
+            status: 200,
+            headers: { "Content-Type": "application/json", ...headerObj },
+        });
+    }
+    return {
+        login: { GET: loginGET },
+        callback: { GET: callbackGET },
+        sso: { POST: ssoPOST },
+        session: { GET: sessionGET },
+        logout: { POST: logoutPOST },
+    };
+}

package/dist/server/auth/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * agent-kit · 认证模块统一出口
+ *
+ * 公共、可复用代码全部收敛于此；具体路由接线（app 侧）只消费本出口，不感知内部实现。
+ */
+export type { AuthUser, AuthProvider, AuthProviderId, SessionUser, AuthConfig } from "./types.js";
+export { loadAuthConfig, isAuthEnabled, isMethodConfigured, parseAuthProviders } from "./config.js";
+export { getLoginOptions } from "./login-options.js";
+export type { LoginOption, LoginOptions } from "./login-options.js";
+export { createSessionToken, verifySessionToken, generateState, toSessionUser, sessionCookieOptions, stateCookieOptions, } from "./session.js";
+export { createProvider, createProviderFor, createDingTalkProvider, createFeishuProvider } from "./providers/index.js";
+export { createLoginHandlers, verifySession, getSessionUser } from "./handlers.js";
+export type { LoginHandlers, LoginHandlersOptions } from "./handlers.js";
+export { migrate, upsertUser, findUserByProvider, touchLastLogin, getPool, isDbEnabled, createAgentSession, listAgentSessions, getAgentSession, renameAgentSession, deleteAgentSession, addAgentMessage, listAgentMessages, } from "./db.js";
+export type { DbUser, AgentSessionRow, AgentMessageRow } from "./db.js";

package/dist/server/auth/index.js

@@ -0,0 +1,14 @@
+// 配置
+export { loadAuthConfig, isAuthEnabled, isMethodConfigured, parseAuthProviders } from "./config.js";
+// 登录方式清单（服务端登录页决策）
+export { getLoginOptions } from "./login-options.js";
+// 会话与 Cookie
+export { createSessionToken, verifySessionToken, generateState, toSessionUser, sessionCookieOptions, stateCookieOptions, } from "./session.js";
+// 提供方工厂
+export { createProvider, createProviderFor, createDingTalkProvider, createFeishuProvider } from "./providers/index.js";
+// 路由工厂
+export { createLoginHandlers, verifySession, getSessionUser } from "./handlers.js";
+// 数据库（PostgreSQL 用户持久化）
+export { migrate, upsertUser, findUserByProvider, touchLastLogin, getPool, isDbEnabled, 
+// 会话与消息（agent_sessions / agent_messages）
+createAgentSession, listAgentSessions, getAgentSession, renameAgentSession, deleteAgentSession, addAgentMessage, listAgentMessages, } from "./db.js";

package/dist/server/auth/login-options.d.ts

@@ -0,0 +1,14 @@
+import type { AuthConfig } from "./types.js";
+export interface LoginOption {
+    /** 登录方式标识（OAuth 平台 / 自建 builtin；builtin 待实现，类型上先留口子） */
+    id: "dingtalk" | "feishu" | "builtin";
+    /** 展示名（登录页按钮文案） */
+    name: string;
+}
+export interface LoginOptions {
+    /** 可用的真实登录方式（已过滤未配置项），空表示无可点选的登录按钮 */
+    providers: LoginOption[];
+    /** 会话 Cookie 路径（= Next basePath，如 /agent），登录页跳转均基于它 */
+    cookiePath: string;
+}
+export declare function getLoginOptions(config?: AuthConfig): LoginOptions;

package/dist/server/auth/login-options.js

@@ -0,0 +1,50 @@
+/**
+ * agent-kit · 登录方式清单（服务端）
+ *
+ * 由 AUTH_PROVIDER 解析出「登录页应如何呈现」的完整决策输入：
+ *   - providers：可用的真实登录方式（OAuth 平台已按 env 过滤是否配置完整）
+ *
+ * 宿主登录页使用范式：
+ *   const options = getLoginOptions();
+ *   const total = options.providers.length;
+ *   if (total === 1) {
+ *     // 单个真实登录方式 → 服务端直接 302 到 /api/auth/login?provider=xxx
+ *   }
+ *   // total > 1 → 渲染 <LoginPage providers={options.providers} />
+ */
+import { loadAuthConfig, isMethodConfigured } from "./config.js";
+const OPTION_NAMES = {
+    dingtalk: "钉钉登录",
+    feishu: "飞书登录",
+    // builtin：自建账号登录（待实现；isMethodConfigured 恒 false 期间不会出现在清单里）
+    builtin: "账号登录",
+};
+export function getLoginOptions(config) {
+    const cfg = config ?? loadAuthConfig();
+    const providers = [];
+    const seen = new Set();
+    for (const m of cfg.methods) {
+        if (m === "none")
+            continue;
+        // adaptive：展开为两个候选 OAuth 平台，各自按 env 是否齐全过滤。
+        // 展开后的清单驱动登录页：钉钉/飞书客户端内自动定向，普通浏览器渲染选择器。
+        if (m === "adaptive") {
+            for (const cand of ["dingtalk", "feishu"]) {
+                if (!isMethodConfigured(cfg, cand))
+                    continue;
+                if (seen.has(cand))
+                    continue;
+                seen.add(cand);
+                providers.push({ id: cand, name: OPTION_NAMES[cand] });
+            }
+            continue;
+        }
+        if (!isMethodConfigured(cfg, m))
+            continue; // OAuth env 不全 / dev 未开启 → 不可选
+        if (seen.has(m))
+            continue;
+        seen.add(m);
+        providers.push({ id: m, name: OPTION_NAMES[m] });
+    }
+    return { providers, cookiePath: cfg.cookiePath };
+}

package/dist/server/auth/providers/dingtalk.d.ts

@@ -0,0 +1,16 @@
+/**
+ * agent-kit · 钉钉认证提供方
+ *
+ * 参考 D:\Project\hotline 的钉钉登录实现，提炼为与框架无关的纯逻辑：
+ *   - 网页 OAuth：login.dingtalk.com 授权 → 用 authCode 换 userAccessToken → 读 contact/users/me
+ *   - 客户端内 JSAPI 免登：dd.requestAuthCode 拿到 code → 用企业凭证换 app token →
+ *     getuserinfo 拿 userid → topapi/v2/user/get 拿档案
+ * 全部归一化为 AuthUser，具体路由接线在 app 侧。
+ */
+import type { AuthProvider } from "../types.js";
+export interface DingTalkProviderConfig {
+    clientId: string;
+    clientSecret: string;
+    corpId: string;
+}
+export declare function createDingTalkProvider(cfg: DingTalkProviderConfig): AuthProvider;

package/dist/server/auth/providers/dingtalk.js

@@ -0,0 +1,177 @@
+const OAUTH_AUTHORIZE = "https://login.dingtalk.com/oauth2/auth";
+const API = "https://api.dingtalk.com";
+const OAPI = "https://oapi.dingtalk.com";
+export function createDingTalkProvider(cfg) {
+    const id = "dingtalk";
+    function isConfigured() {
+        return Boolean(cfg.clientId && cfg.clientSecret && cfg.corpId);
+    }
+    function getAuthorizeUrl(redirectUri, state) {
+        const url = new URL(OAUTH_AUTHORIZE);
+        url.searchParams.set("redirect_uri", redirectUri);
+        url.searchParams.set("response_type", "code");
+        url.searchParams.set("client_id", cfg.clientId);
+        url.searchParams.set("scope", "openid");
+        url.searchParams.set("prompt", "consent");
+        url.searchParams.set("state", state);
+        return url.toString();
+    }
+    /** 网页 OAuth：authCode → userAccessToken → 通讯录个人信息（contact/users/me）。 */
+    async function exchangeOAuthCode(code) {
+        const tokenRes = await fetch(`${API}/v1.0/oauth2/userAccessToken`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                clientId: cfg.clientId,
+                clientSecret: cfg.clientSecret,
+                code,
+                grantType: "authorization_code",
+            }),
+            cache: "no-store",
+        });
+        const tokenJson = (await tokenRes.json().catch(() => ({})));
+        if (!tokenRes.ok || !tokenJson.accessToken) {
+            throw new Error(`钉钉 userAccessToken 换取失败 (${tokenRes.status})`);
+        }
+        // 校验登录归属组织（防止非本企业账号登录）
+        if (cfg.corpId && tokenJson.corpId && tokenJson.corpId !== cfg.corpId) {
+            throw new Error("当前钉钉账号不属于本企业组织");
+        }
+        const profileRes = await fetch(`${API}/v1.0/contact/users/me`, {
+            headers: { "x-acs-dingtalk-access-token": tokenJson.accessToken },
+            cache: "no-store",
+        });
+        const p = (await profileRes.json().catch(() => ({})));
+        const unionId = p.unionId || "";
+        const openId = p.openId || "";
+        // OAuth 路径的 /v1.0/contact/users/me 只返回 unionId/openId，不返回企业内 userid；
+        // 发送到钉钉会话（message/send_to_conversation 的 sender）必须用 userid，这里用
+        // unionId 经 getbyunionid 实时解析并写入 userCode，避免用户表 user_code 为空导致分享失败。
+        let userCode = "";
+        if (unionId) {
+            try {
+                const appToken = await getAppToken();
+                userCode = await resolveUserIdByUnionId(appToken, unionId);
+            }
+            catch {
+                // 解析失败不阻断登录；发送链路还有 unionId 兜底
+            }
+        }
+        if (!profileRes.ok || (!unionId && !openId)) {
+            // OAuth code + accessToken 已证明钉钉身份，缺通讯录权限不应让合法登录失败
+            console.warn("[dingtalk] profile 不可读，仅以已验证身份继续登录");
+            return {
+                provider: id,
+                unionId: unionId || `verified:${tokenJson.accessToken.slice(0, 16)}`,
+                openId,
+                userCode,
+                name: "钉钉用户",
+                raw: { ...p, _verified: true },
+            };
+        }
+        return {
+            provider: id,
+            unionId,
+            openId,
+            userCode,
+            name: p.nick || p.name || "钉钉用户",
+            avatar: p.avatarUrl || "",
+            mobile: p.mobile || "",
+            email: p.email || "",
+            raw: p,
+        };
+    }
+    /** 企业应用 app token（client_credentials）。 */
+    async function getAppToken() {
+        const appTokenRes = await fetch(`${API}/v1.0/oauth2/${encodeURIComponent(cfg.corpId)}/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                client_id: cfg.clientId,
+                client_secret: cfg.clientSecret,
+                grant_type: "client_credentials",
+            }),
+            cache: "no-store",
+        });
+        const appTokenJson = (await appTokenRes.json().catch(() => ({})));
+        if (!appTokenRes.ok || !appTokenJson.access_token) {
+            throw new Error(`钉钉 app token 换取失败 (${appTokenRes.status})`);
+        }
+        return appTokenJson.access_token;
+    }
+    /** 根据 unionId 解析企业内 userid（POST /topapi/v2/user/getbyunionid；旧路径 /topapi/user/getbyunionid 自动回退）。 */
+    async function resolveUserIdByUnionId(appToken, unionId) {
+        const body = JSON.stringify({ unionid: unionId });
+        for (const path of ["topapi/v2/user/getbyunionid", "topapi/user/getbyunionid"]) {
+            try {
+                const res = await fetch(`${OAPI}/${path}?access_token=${encodeURIComponent(appToken)}`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body,
+                    cache: "no-store",
+                });
+                const json = (await res.json().catch(() => ({})));
+                if (res.ok && json.errcode === 0 && json.result?.userid)
+                    return json.result.userid;
+            }
+            catch {
+                // 换路径重试
+            }
+        }
+        return "";
+    }
+    /** 客户端内 JSAPI 免登：code → app token → getuserinfo(userid) → user/get(档案)。 */
+    async function exchangeClientCode(code) {
+        const accessToken = await getAppToken();
+        const infoRes = await fetch(`${OAPI}/topapi/v2/user/getuserinfo?access_token=${encodeURIComponent(accessToken)}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ code }),
+            cache: "no-store",
+        });
+        const infoJson = (await infoRes.json().catch(() => ({})));
+        const userId = infoJson.result?.userid;
+        if (!infoRes.ok || infoJson.errcode !== 0 || !userId) {
+            throw new Error(`钉钉免登码验证失败 (${infoJson.errcode})`);
+        }
+        // 拉通讯录档案（缺权限时降级，不阻断登录）
+        let profile = {};
+        try {
+            const profileRes = await fetch(`${OAPI}/topapi/v2/user/get?access_token=${encodeURIComponent(accessToken)}`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ userid: userId, language: "zh_CN" }),
+                cache: "no-store",
+            });
+            const profileJson = (await profileRes.json().catch(() => ({})));
+            if (profileRes.ok && profileJson.errcode === 0 && profileJson.result) {
+                profile = profileJson.result;
+            }
+            else {
+                console.warn("[dingtalk] 免登档案读取不可用，仅以 userid 建会话");
+            }
+        }
+        catch (e) {
+            console.warn("[dingtalk] 免登档案读取异常", e instanceof Error ? e.message : e);
+        }
+        return {
+            provider: id,
+            unionId: String(profile.unionid || userId),
+            openId: "",
+            userCode: userId,
+            name: String(profile.name || "钉钉用户"),
+            avatar: String(profile.avatar || ""),
+            mobile: String(profile.mobile || ""),
+            deptName: Array.isArray(profile.dept_id_list) ? undefined : undefined,
+            raw: profile,
+        };
+    }
+    return {
+        id,
+        supportsClientSso: true,
+        isConfigured,
+        getAuthorizeUrl,
+        exchangeOAuthCode,
+        exchangeClientCode,
+    };
+}

package/dist/server/auth/providers/feishu.d.ts

@@ -0,0 +1,15 @@
+/**
+ * agent-kit · 飞书认证提供方
+ *
+ * 与钉钉对称实现，统一归一到 AuthUser：
+ *   - 网页 OAuth：open.feishu.cn 授权 → app_access_token → OIDC user_access_token → user_info
+ *   - 客户端内 JSSDK 免登：tt.requestAuthCode 拿到的 code 同样走 OIDC 换取（飞书 code 通用）
+ * 默认域名 open.feishu.cn（中国区），可用 FS_BASE_URL 覆盖（国际版 app.feishu.com）。
+ */
+import type { AuthProvider } from "../types.js";
+export interface FeishuProviderConfig {
+    appId: string;
+    appSecret: string;
+    baseUrl: string;
+}
+export declare function createFeishuProvider(cfg: FeishuProviderConfig): AuthProvider;