@turingflow/agent-kit 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,100 @@
+export function createFeishuProvider(cfg) {
+    const id = "feishu";
+    const base = cfg.baseUrl;
+    function isConfigured() {
+        return Boolean(cfg.appId && cfg.appSecret);
+    }
+    function getAuthorizeUrl(redirectUri, state) {
+        const url = new URL(`${base}/open-apis/authen/v1/authorize`);
+        url.searchParams.set("app_id", cfg.appId);
+        url.searchParams.set("redirect_uri", redirectUri);
+        url.searchParams.set("response_type", "code");
+        // 空格分隔：im:message = 用户身份读取/发送消息（分享「以当前用户身份发消息」）；
+        // offline_access = 换取 refresh_token（user_access_token 2h 过期后刷新续期）
+        url.searchParams.set("scope", "im:message offline_access");
+        url.searchParams.set("state", state);
+        return url.toString();
+    }
+    /** 取企业内部应用 app_access_token（仅支持 internal；ISV 应用需 app_ticket 流程，未实现）。 */
+    async function getAppAccessToken() {
+        const res = await fetch(`${base}/open-apis/auth/v3/app_access_token/internal`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ app_id: cfg.appId, app_secret: cfg.appSecret }),
+            cache: "no-store",
+        });
+        const json = (await res.json().catch(() => ({})));
+        const token = json.app_access_token || json.data?.app_access_token;
+        if (!res.ok || !token) {
+            throw new Error(`飞书 app_access_token 换取失败 (${res.status})`);
+        }
+        return token;
+    }
+    /** OIDC：用 authorization_code 换 user_access_token（网页与客户端 code 通用）。 */
+    async function exchangeOidcCode(code) {
+        const appAccessToken = await getAppAccessToken();
+        const tokenRes = await fetch(`${base}/open-apis/authen/v1/oidc/access_token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                grant_type: "authorization_code",
+                code,
+                app_access_token: appAccessToken,
+            }),
+            cache: "no-store",
+        });
+        const tokenJson = (await tokenRes.json().catch(() => ({})));
+        const data = tokenJson.data || tokenJson;
+        const userAccessToken = data.access_token || tokenJson.access_token;
+        if (!tokenRes.ok || !userAccessToken) {
+            // 附带飞书业务错误码/信息（HTTP 200 + JSON 错误），便于定位 20003 等
+            const detail = tokenJson.code != null ? `code=${tokenJson.code} msg=${tokenJson.msg ?? ""}` : "";
+            throw new Error(`飞书 user_access_token 换取失败 (${tokenRes.status}) ${detail}`.trim());
+        }
+        const infoRes = await fetch(`${base}/open-apis/authen/v1/user_info`, {
+            headers: { Authorization: `Bearer ${userAccessToken}` },
+            cache: "no-store",
+        });
+        const infoJson = (await infoRes.json().catch(() => ({})));
+        const u = infoJson.data || infoJson;
+        // 令牌随用户落库（oauthToken），供「以当前用户身份发消息」等服务端调用使用；
+        // refresh_token 仅在申请了 offline_access scope 时返回
+        const oauthToken = {
+            accessToken: userAccessToken,
+            refreshToken: data.refresh_token || undefined,
+        };
+        const unionId = String(u.union_id || u.unionId || "");
+        const openId = String(u.open_id || u.openId || "");
+        if (!infoRes.ok || (!unionId && !openId)) {
+            console.warn("[feishu] user_info 不可读，仅以已验证身份继续登录");
+            return {
+                provider: id,
+                unionId: unionId || `verified:${userAccessToken.slice(0, 16)}`,
+                openId,
+                name: "飞书用户",
+                oauthToken,
+                raw: { ...u, _verified: true },
+            };
+        }
+        return {
+            provider: id,
+            unionId,
+            openId,
+            userCode: String(u.employee_id || u.employeeId || ""),
+            name: String(u.name || "飞书用户"),
+            avatar: String(u.avatar_url || u.avatarUrl || ""),
+            email: String(u.email || ""),
+            mobile: String(u.mobile || ""),
+            oauthToken,
+            raw: u,
+        };
+    }
+    return {
+        id,
+        supportsClientSso: true,
+        isConfigured,
+        getAuthorizeUrl,
+        exchangeOAuthCode: exchangeOidcCode,
+        exchangeClientCode: exchangeOidcCode,
+    };
+}

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

@@ -0,0 +1,13 @@
+/**
+ * agent-kit · 认证提供方工厂
+ *
+ * 按 method / 指定方式返回对应的认证提供方实例；未配置或非具体平台时返回 null。
+ * 上层只依赖 AuthProvider 抽象，不感知具体平台。
+ */
+import type { AuthConfig, AuthProvider, AuthProviderId } from "../types.js";
+/** 按指定平台 id 构造提供方实例（不依赖 config.method；多方式场景下按按钮逐个取）。 */
+export declare function createProviderFor(config: AuthConfig, id: AuthProviderId): AuthProvider | null;
+/** 根据认证配置构造当前主启用的提供方；method 非具体平台或对应平台未配置时返回 null。 */
+export declare function createProvider(config: AuthConfig): AuthProvider | null;
+export { createDingTalkProvider } from "./dingtalk.js";
+export { createFeishuProvider } from "./feishu.js";

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

@@ -0,0 +1,24 @@
+import { createDingTalkProvider } from "./dingtalk.js";
+import { createFeishuProvider } from "./feishu.js";
+/** 按指定平台 id 构造提供方实例（不依赖 config.method；多方式场景下按按钮逐个取）。 */
+export function createProviderFor(config, id) {
+    if (id === "dingtalk") {
+        const p = createDingTalkProvider(config.dingtalk);
+        return p.isConfigured() ? p : null;
+    }
+    if (id === "feishu") {
+        const p = createFeishuProvider(config.feishu);
+        return p.isConfigured() ? p : null;
+    }
+    return null;
+}
+/** 根据认证配置构造当前主启用的提供方；method 非具体平台或对应平台未配置时返回 null。 */
+export function createProvider(config) {
+    if (config.method === "dingtalk")
+        return createProviderFor(config, "dingtalk");
+    if (config.method === "feishu")
+        return createProviderFor(config, "feishu");
+    return null;
+}
+export { createDingTalkProvider } from "./dingtalk.js";
+export { createFeishuProvider } from "./feishu.js";

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

@@ -0,0 +1,48 @@
+import type { AuthUser, SessionUser } from "./types.js";
+/** 生成一次性 state（防 CSRF），用于 OAuth 授权跳转。 */
+export declare function generateState(): string;
+/** 由归一化用户构造会话用户（sub = provider:unionId，作为全链路用户主体键）。 */
+export declare function toSessionUser(user: AuthUser): SessionUser;
+/**
+ * 解析主体键 `${provider}:${unionId}` → { provider, unionId }。
+ * unionId 自身可能含 `:`，故只按**第一个** `:` 切分。
+ * 非法（缺 `:`）时返回 provider=""、unionId=原串，交由调用方决定是否视为未登录。
+ */
+export declare function parseSessionKey(sub: string): {
+    provider: string;
+    unionId: string;
+};
+/** 签发会话 token。 */
+export declare function createSessionToken(sessionUser: SessionUser, secret: string): string;
+/** 验证并解析会话 token；失效 / 篡改 / 过期均返回 null。 */
+export declare function verifySessionToken(token: string | undefined | null, secret: string): SessionUser | null;
+export interface CookieOptions {
+    path: string;
+    secure: boolean;
+    maxAgeSeconds?: number;
+}
+/**
+ * 标准会话 Cookie 选项。
+ * - secure=false（本地 http / 同 site 场景，如桌面端 dev）：SameSite=Lax，无 Secure。
+ *   桌面端正确姿势：主进程把页面 host 统一为 127.0.0.1（与引擎同 site），Lax cookie 随
+ *   fetch 正常携带。
+ * - secure=true：SameSite=None + Secure。注意：Chromium 的 Secure cookie 例外仅限
+ *   localhost 主机名，**不含 127.0.0.1**——在 http://127.0.0.1 上 Secure cookie 会被浏览器
+ *   拒绝发送（存储有、请求不带，表现为"每次启动都要重新登录"），因此本地 http 引擎
+ *   绝不能开 secure。
+ */
+export declare function sessionCookieOptions(cookiePath: string, secure: boolean, maxAgeSeconds?: number): {
+    httpOnly: boolean;
+    sameSite: "none" | "lax";
+    secure: boolean;
+    path: string;
+    maxAge: number;
+};
+/** 短期（10 分钟）state Cookie 选项，用于 OAuth 往返校验（同会话策略）。 */
+export declare function stateCookieOptions(cookiePath: string, secure: boolean, maxAgeSeconds?: number): {
+    httpOnly: boolean;
+    sameSite: "none" | "lax";
+    secure: boolean;
+    path: string;
+    maxAge: number;
+};

package/dist/server/auth/session.js

@@ -0,0 +1,108 @@
+/**
+ * agent-kit · 会话与 Cookie 工具
+ *
+ * 会话采用「无状态签名 token」：payload 经 base64url 编码，再用 HMAC-SHA256 签名，
+ * 写入 httpOnly Cookie。验证时不查库即可确认身份未被篡改，过期由 exp 字段控制。
+ * 与 hotline 思路一致，但全部参数化（密钥 / Cookie 名 / 路径由调用方传入），
+ * 不写死任何项目专属常量，便于多 app 复用。
+ */
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+const SESSION_MAX_AGE_SECONDS = 60 * 60 * 24 * 7; // 7 天
+function base64UrlEncode(input) {
+    return Buffer.from(input)
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/g, "");
+}
+function base64UrlDecode(input) {
+    const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+    return Buffer.from(padded, "base64");
+}
+function sign(value, secret) {
+    return base64UrlEncode(createHmac("sha256", secret).update(value).digest());
+}
+/** 生成一次性 state（防 CSRF），用于 OAuth 授权跳转。 */
+export function generateState() {
+    return randomUUID();
+}
+/** 由归一化用户构造会话用户（sub = provider:unionId，作为全链路用户主体键）。 */
+export function toSessionUser(user) {
+    return {
+        sub: `${user.provider}:${user.unionId}`,
+        provider: user.provider,
+        unionId: user.unionId,
+        openId: user.openId,
+        name: user.name || "用户",
+        avatar: user.avatar || "",
+        exp: Math.floor(Date.now() / 1000) + SESSION_MAX_AGE_SECONDS,
+    };
+}
+/**
+ * 解析主体键 `${provider}:${unionId}` → { provider, unionId }。
+ * unionId 自身可能含 `:`，故只按**第一个** `:` 切分。
+ * 非法（缺 `:`）时返回 provider=""、unionId=原串，交由调用方决定是否视为未登录。
+ */
+export function parseSessionKey(sub) {
+    const idx = sub.indexOf(":");
+    if (idx < 0)
+        return { provider: "", unionId: sub };
+    return { provider: sub.slice(0, idx), unionId: sub.slice(idx + 1) };
+}
+/** 签发会话 token。 */
+export function createSessionToken(sessionUser, secret) {
+    const payload = base64UrlEncode(JSON.stringify(sessionUser));
+    return `${payload}.${sign(payload, secret)}`;
+}
+/** 验证并解析会话 token；失效 / 篡改 / 过期均返回 null。 */
+export function verifySessionToken(token, secret) {
+    if (!token || !token.includes("."))
+        return null;
+    const [payload, signature] = token.split(".");
+    if (!payload || !signature)
+        return null;
+    const expected = sign(payload, secret);
+    const a = Buffer.from(signature);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length || !timingSafeEqual(a, b))
+        return null;
+    try {
+        const user = JSON.parse(base64UrlDecode(payload).toString("utf8"));
+        if (!user.sub || !user.exp || user.exp <= Math.floor(Date.now() / 1000))
+            return null;
+        return user;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 标准会话 Cookie 选项。
+ * - secure=false（本地 http / 同 site 场景，如桌面端 dev）：SameSite=Lax，无 Secure。
+ *   桌面端正确姿势：主进程把页面 host 统一为 127.0.0.1（与引擎同 site），Lax cookie 随
+ *   fetch 正常携带。
+ * - secure=true：SameSite=None + Secure。注意：Chromium 的 Secure cookie 例外仅限
+ *   localhost 主机名，**不含 127.0.0.1**——在 http://127.0.0.1 上 Secure cookie 会被浏览器
+ *   拒绝发送（存储有、请求不带，表现为"每次启动都要重新登录"），因此本地 http 引擎
+ *   绝不能开 secure。
+ */
+export function sessionCookieOptions(cookiePath, secure, maxAgeSeconds = SESSION_MAX_AGE_SECONDS) {
+    return {
+        httpOnly: true,
+        sameSite: (secure ? "none" : "lax"),
+        secure,
+        path: cookiePath,
+        maxAge: maxAgeSeconds,
+    };
+}
+/** 短期（10 分钟）state Cookie 选项，用于 OAuth 往返校验（同会话策略）。 */
+export function stateCookieOptions(cookiePath, secure, maxAgeSeconds = 10 * 60) {
+    return {
+        httpOnly: true,
+        sameSite: (secure ? "none" : "lax"),
+        secure,
+        path: cookiePath,
+        maxAge: maxAgeSeconds,
+    };
+}

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

@@ -0,0 +1,118 @@
+/**
+ * agent-kit · 认证类型定义
+ *
+ * 抽象层核心：所有认证提供方（钉钉 / 飞书 / 自建 builtin）都归一化为 AuthUser；
+ * 上层（会话、数据库、路由）只认 AuthUser，不关心来自哪个平台。
+ */
+export type AuthProviderId = "dingtalk" | "feishu" | "builtin";
+/**
+ * AUTH_PROVIDER 合法取值：OAuth 平台 + builtin（自建账号体系）+ adaptive + none 关闭。
+ * builtin 目前仅留口子：类型 / 配置解析 / 登录页均认可该方式，
+ * 但「自建登录系统（页面 + 用户名密码会话）」尚未实现——
+ * isMethodConfigured("builtin") 暂恒 false，因此 builtin 暂不会出现在登录方式清单里。
+ * adaptive：按客户端 UA 自动决定走钉钉还是飞书（钉钉 App → 钉钉免登/OAuth，飞书 App → 飞书 OAuth，
+ * 其他浏览器 → 渲染登录方式选择器）。配置上要求至少一个 OAuth 平台 env 齐全才能启用。
+ */
+export type AuthMethod = AuthProviderId | "none" | "adaptive";
+/** 归一化后的用户身份（跨提供方统一结构）。 */
+export interface AuthUser {
+    /** 来源平台 */
+    provider: AuthProviderId;
+    /** 跨应用唯一 ID（钉钉 unionid / 飞书 union_id）—— 数据库主匹配键 */
+    unionId: string;
+    /** 企业内唯一 ID（钉钉 openId / 飞书 open_id） */
+    openId: string;
+    /** 企业内部工号（钉钉 userid / 飞书 employee_id），可为空 */
+    userCode?: string;
+    /** 展示名 */
+    name: string;
+    /** 头像 URL */
+    avatar?: string;
+    /** 邮箱（提供方返回时才有） */
+    email?: string;
+    /** 手机号（提供方返回时才有） */
+    mobile?: string;
+    /** 部门名（钉钉通讯录可解析；飞书需额外权限） */
+    deptName?: string;
+    /** OAuth 令牌（不落 session，仅用于落库持久化：飞书用户身份发消息等场景） */
+    oauthToken?: {
+        accessToken: string;
+        refreshToken?: string;
+    };
+    /** 提供方原始档案（落库到 raw_profile），便于扩展字段 */
+    raw?: Record<string, unknown>;
+}
+/** 写入会话 Cookie 的精简用户（无敏感字段）。 */
+export interface SessionUser {
+    /** 用户主体键：${provider}:${unionId} —— 全链路（会话 / 归属 / 分享 / DB）以此为准 */
+    sub: string;
+    provider: AuthProviderId;
+    unionId: string;
+    openId: string;
+    name: string;
+    avatar?: string;
+    exp: number;
+}
+/**
+ * 认证提供方抽象接口。
+ * 每个具体实现（钉钉 / 飞书）只需实现：构建网页 OAuth 授权 URL、用网页 code 换用户、
+ * 以及可选的客户端内 JSAPI 免登 code 换用户。
+ *
+ * 注意：builtin（自建账号体系）不是 OAuth 平台，不实现本接口；
+ * 其登录系统（页面 + 用户名密码校验 + 会话签发）后续单独实现，届时复用 finalizeLogin 落库与会话。
+ */
+export interface AuthProvider {
+    /** 提供方标识 */
+    readonly id: AuthProviderId;
+    /** 是否支持客户端内 JSAPI 免登（钉钉/飞书均支持） */
+    readonly supportsClientSso: boolean;
+    /** 是否已配置完该方式所需的全部 env（未配置时不应启用） */
+    isConfigured(): boolean;
+    /** 构建网页 OAuth 授权 URL（用户扫码 / 授权页） */
+    getAuthorizeUrl(redirectUri: string, state: string): string;
+    /** 用网页 OAuth 的 auth code 换取归一化用户 */
+    exchangeOAuthCode(code: string, redirectUri?: string): Promise<AuthUser>;
+    /** 用客户端内 JSAPI 免登 code 换取归一化用户（可选） */
+    exchangeClientCode?(code: string): Promise<AuthUser>;
+}
+/** 认证配置（由 env 解析，见 config.ts）。 */
+export interface AuthConfig {
+    /**
+     * AUTH_PROVIDER 完整解析结果（按 `,` 或 `|` 分隔、去重、过滤非法值、忽略 none 与其它值共存时的 none）。
+     * 可含 builtin / dingtalk / feishu；顺序即展示顺序。
+     */
+    methods: AuthMethod[];
+    /**
+     * 主认证方式（methods 中第一个非 none 的值；不存在时 "none"）。
+     * 保留给单方式场景与历史逻辑：dingtalk | feishu | builtin | adaptive | none
+     */
+    method: "dingtalk" | "feishu" | "builtin" | "adaptive" | "none";
+    /** 对外基础地址（拼接回调跳转用），如 http://localhost:3100 */
+    publicUrl: string;
+    /** 会话 Cookie 路径（需与 Next basePath 一致，如 /agent） */
+    cookiePath: string;
+    /** 会话签名密钥 */
+    sessionSecret: string;
+    /** Cookie 是否 secure */
+    secureCookie: boolean;
+    /** 钉钉配置（method=dingtalk 时必填） */
+    dingtalk: {
+        clientId: string;
+        clientSecret: string;
+        corpId: string;
+        /** 企业内部应用微应用 AgentId（env DD_AGENT_ID）。H5 JSAPI 前端鉴权（分享到钉钉会话）必填 */
+        agentId: string;
+        /** 机器人 code（env DD_ROBOT_CODE，可选）。发送群消息用；未配置时默认用 clientId（企业内部应用机器人 code = AppKey） */
+        robotCode?: string;
+        /** 互动卡片模板 ID（env DD_CARD_TEMPLATE_ID）。用户身份发送分享（sendMessageToGroup）必填；在钉钉开发者后台「卡片平台」创建模板后获取 */
+        cardTemplateId?: string;
+        redirectUri?: string;
+    };
+    /** 飞书配置（method=feishu 时必填）。仅支持企业内部应用（isv 应用商店应用未实现） */
+    feishu: {
+        appId: string;
+        appSecret: string;
+        baseUrl: string;
+        redirectUri?: string;
+    };
+}

package/dist/server/auth/types.js

@@ -0,0 +1,7 @@
+/**
+ * agent-kit · 认证类型定义
+ *
+ * 抽象层核心：所有认证提供方（钉钉 / 飞书 / 自建 builtin）都归一化为 AuthUser；
+ * 上层（会话、数据库、路由）只认 AuthUser，不关心来自哪个平台。
+ */
+export {};

package/dist/server/browser-agent-mcp.d.ts

@@ -0,0 +1,67 @@
+/**
+ * agent-kit · browser-agent MCP 工具（computer use：AI 自主控制浏览器）
+ *
+ * 设计：把"浏览器操作智能体"封装成一个 MCP 工具 control_browser(task)，由聊天模型（hy3）
+ * 在对话中**自主决定**何时调用——无需用户在 UI 上手动触发。
+ *
+ * 工具内部是一个纯视觉 computer-use 循环（与 web-fetch 同款 Playwright 持久上下文）：
+ *   截图 → 把截图作为图片发给 hy3（allowedTools:[] 关掉工具、maxTurns:1 不自循环，仅做视觉
+ *   推理输出动作 JSON）→ 解析并执行（click/type/scroll/navigate/wait/done/ask）→ 循环。
+ *
+ * 关键能力：
+ *   - 全程通过 SSE 事件（screenshot / thinking / action / done / ask / finished）外发，
+ *     聊天模型经 canUseTool 拦截时注册订阅者，过程事件同步转发进聊天 SSE，
+ *     前端 thinking 展开区实时展示浏览器截图与动作（headless 无独立窗口）。
+ *   - 单例 BrowserAgentService 同时服务「手动入口（/api/browser/session）」与
+ *     「自主 control_browser 工具」，二者共用同一会话注册表，避免重复实现。
+ *   - 容错解析：容忍 Markdown 代码块、尾随逗号；连续无效操作（疑似卡死）自动停止。
+ *
+ * 暴露：control_browser(task: string, max_steps?: number) → { summary, finalUrl, finalTitle, steps }
+ */
+import { type SdkMcpServerResult } from "@tencent-ai/agent-sdk";
+export interface BrowserTaskResult {
+    summary: string;
+    finalUrl: string;
+    finalTitle: string;
+    steps: string[];
+    stopped: boolean;
+}
+/**
+ * BrowserAgentService：浏览器 computer-use 单例。
+ * 同时服务「手动入口（/api/browser/session）」与「自主 control_browser 工具」。
+ * 同一时刻串行执行一个任务（共享 profile 目录）。
+ */
+export declare class BrowserAgentService {
+    private static instance;
+    private queue;
+    private readonly profileDir;
+    private sessions;
+    /** 下一个任务的聊天流订阅者：control_browser 工具经 canUseTool 拦截时设置，
+     *  run() 创建会话后自动挂到该会话，浏览器过程事件同步转发进聊天 SSE。 */
+    private pendingSubscriber;
+    private constructor();
+    static get(): BrowserAgentService;
+    /** 注册下一个任务的聊天流订阅者（canUseTool 拦截 control_browser 时调用） */
+    setPendingSubscriber(cb: (event: string, data: unknown) => void): void;
+    /** 启动一个浏览器任务（异步执行），立即返回会话 id 与完成 Promise。
+     *  headless 模式无可见窗口；过程事件经 subscriber 转发进聊天 thinking 展示。 */
+    run(task: string, maxSteps?: number, notify?: boolean): {
+        id: string;
+        done: Promise<BrowserTaskResult>;
+    };
+    /** 自主工具调用入口：返回最终结论（headless 无弹窗；过程事件进聊天 thinking） */
+    runTask(task: string, maxSteps?: number): Promise<BrowserTaskResult>;
+    /** 把已存在的会话 SSE 流挂到某个控制面板（手动入口或自主模式自动弹窗都走这里） */
+    attach(id: string): ReadableStream<Uint8Array>;
+    input(id: string, text: string): boolean;
+    stop(id: string): boolean;
+    private doRun;
+    private waitForHuman;
+    private execute;
+}
+/** 每次调用创建独立 McpServer 实例（绝不共享）：agent-sdk 每个 query 的 transport 都会对
+ *  传入实例调用 server.connect()，而 MCP Protocol 实例只允许 connect 一次；共享实例在并发
+ *  或先后复用时抛 "Already connected to a transport"。薄壳开销可忽略（BrowserAgentService 为单例）。 */
+export declare function createBrowserAgentMcpServer(): SdkMcpServerResult;
+/** 工具在模型上下文中暴露的名称（server 名连字符转下划线） */
+export declare const BROWSER_AGENT_TOOL_NAME = "mcp__browser_agent__control_browser";