@turingflow/agent-kit 0.0.0-stage → 0.1.0

package/dist/server/handlers.js

@@ -0,0 +1,523 @@
+/**
+ * agent-kit · 服务端端点工厂（Next.js App Router）
+ *
+ * 第三方 Next.js 工程引入后，即可获得与 web 完全一致的四个端点能力，
+ * 无需重新实现上传 / 语音令牌 / ASR 转写等通用逻辑：
+ *
+ *   // app/api/chat/route.js
+ *   import { createChatHandler } from "agent-kit";
+ *   export const runtime = "nodejs";
+ *   export const { POST } = createChatHandler();
+ *
+ *   // app/api/upload/route.js
+ *   import { createUploadHandler } from "agent-kit";
+ *   export const { POST } = createUploadHandler();
+ *
+ *   // app/api/voice/token/route.js
+ *   import { createVoiceTokenHandler } from "agent-kit";
+ *   export const { POST } = createVoiceTokenHandler({ userResolver: async (req) => currentUser });
+ *
+ *   // app/api/voice/transcribe/route.js
+ *   import { createVoiceTranscribeHandler } from "agent-kit";
+ *   export const { POST } = createVoiceTranscribeHandler();
+ *
+ * 前端 ChatWindow 的默认端点路径（/api/chat、/api/upload、/api/voice/*）与之对应，零改动接入。
+ */
+import { createAgentStream, createAgentSessionStream, resolvePendingAsk, steerSession } from "./sdk.js";
+import { BrowserAgentService } from "./browser-agent-mcp.js";
+import { startSessionSweeper } from "./session-store.js";
+import { assertChatAccess, assertSessionAccess } from "./session-access.js";
+import { slog } from "./debug-log.js";
+import { createUploadHandler } from "./upload.js";
+import { createVoiceToken, verifyVoiceToken, transcribeVoice } from "./voice.js";
+import { readArtifact, listSessionArtifacts, ensureSessionDir, artifactRoot } from "./artifacts.js";
+import { verifySession } from "./auth/handlers.js";
+import { loadAuthConfig } from "./auth/config.js";
+import { setSessionTitleIfNotUserRenamed, isDbEnabled, getAgentSession } from "./auth/db.js";
+import path from "node:path";
+import fs from "node:fs";
+/** Windows 绝对路径 → CLI 可用的 bash 风格路径：D:\a\b → /d/a/b（CodeBuddy CLI 在 Windows 上执行工具时使用 bash 风格路径） */
+function toPosixPath(p) {
+    const m = String(p).match(/^([A-Za-z]):[\\/](.*)$/s);
+    if (m)
+        return `/${m[1].toLowerCase()}/${m[2].replace(/\\/g, "/")}`;
+    return String(p).replace(/\\/g, "/");
+}
+/** POST /api/chat：消息数组 → agent-kit 订阅对话流 → SSE 事件流（text/thinking/done/error） */
+export function createChatHandler(config = {}) {
+    // 附件真实目录：默认与 createUploadHandler 一致（<cwd>/public/uploads）。
+    // 注入给模型的路径一律用虚拟前缀 /attachments/<文件名>（相对 CLI cwd，真实存在于 <cwd>/attachments/）：
+    //  ① chat 端点会把附件复制到 <cwd>/attachments/，模型 Read 虚拟路径即直接命中，零路径改写依赖；
+    //  ② 模型上下文/思考/正文中出现的只有无害的虚拟路径，真实磁盘结构永不进入模型。
+    const attachmentRealDir = config.attachmentBaseDir ?? path.join(process.cwd(), "public", "uploads");
+    const attachmentUrlPrefix = (config.attachmentUrlPrefix ?? "/uploads").replace(/\/+$/, "");
+    // 附件相对可读路径统一为 attachments/<rel>（见 stageVirtualCopy 注释）
+    // 附件虚拟路径按会话隔离：模型只能 Read 本会话的附件。
+    // 实际可读路径由 stageVirtualCopy 决定（相对 CLI cwd 的 attachments/<rel>，
+    // 见 stageVirtualCopy 注释——SDK/CLI 无 pathAliases 能力，绝对虚拟路径在 Windows 上读不到）。
+    // existingContent：消息里已有内容（前端通常已把 "[附件] 文件名" 拼进用户消息），
+    // 已含附件名时不再重复拼接（避免同一附件名出现两次、浪费模型上下文）。
+    function attachmentHint(attachment, existingContent = "", readPath = "") {
+        if (!attachment || typeof attachment !== "object")
+            return "";
+        const url = String(attachment.url ?? "");
+        if (!url.startsWith(attachmentUrlPrefix))
+            return "";
+        const rel = url.slice(attachmentUrlPrefix.length).replace(/^\/+/, "");
+        const name = String(attachment.name ?? path.basename(url));
+        const nameAlreadyShown = existingContent.includes(`[附件] ${name}`) || existingContent.includes(`[附件]${name}`);
+        const finalReadPath = readPath || `attachments/${rel}`;
+        return `\n\n${nameAlreadyShown ? "" : `[附件] ${name}\n`}该附件已上传到服务端（工作区附件目录，具体路径无需关心）。\n需要分析该附件时，请直接用 Read 工具读取：${finalReadPath}（直接读取即可完成分析，无需查找其他位置）`;
+    }
+    /** 把附件复制到 CLI 进程 cwd 下的 attachments/<rel>（模型 Read 相对路径直接命中）。
+     *  关键背景：CodeBuddy SDK/CLI 没有 pathAliases 能力，canUseTool 的 updatedInput 改写
+     *  对 Read/Glob 也不生效（实测越界路径未被拦截）；绝对虚拟路径 /attachments/<sid>/<rel>
+     *  在 Windows 上会被解析到盘符根（C:\attachments\...），永远 "File does not exist"。
+     *  因此附件必须放进模型真实的工作目录：
+     *   - web 沙箱（无工作区）：CLI cwd = <用户 .agent>/<sid>（见 sdk.ts cwdOverride），
+     *     附件放到 <cwd>/attachments/<rel>，提示相对路径 attachments/<rel>；
+     *   - 有工作区（桌面 app 场景）：CLI cwd = 工作区根，同样放 <cwd>/attachments/<rel>。
+     *  返回相对可读路径（空串 = 无附件）。 */
+    async function stageVirtualCopy(rel, sid, workspaceDir) {
+        const cliCwd = workspaceDir && workspaceDir.trim()
+            ? path.resolve(workspaceDir.trim())
+            : path.join(artifactRoot(), sid);
+        const dstDir = path.join(cliCwd, "attachments");
+        const dst = path.join(dstDir, rel);
+        try {
+            await fs.promises.mkdir(dstDir, { recursive: true });
+            await fs.promises.copyFile(path.join(attachmentRealDir, rel), dst);
+        }
+        catch (err) {
+            // 复制失败不阻塞对话（模型仍可自行定位文件，protectedPaths 精确兜底防泄露）
+            console.error(`[agent-kit] stageVirtualCopy failed: ${err instanceof Error ? err.message : err}`);
+        }
+        return `attachments/${rel}`;
+    }
+    /** 提取附件相对路径（url 去掉前缀后的部分），无附件/前缀不符时返回空串 */
+    function attachmentRel(attachment) {
+        if (!attachment || typeof attachment !== "object")
+            return "";
+        const url = String(attachment.url ?? "");
+        if (!url.startsWith(attachmentUrlPrefix))
+            return "";
+        return url.slice(attachmentUrlPrefix.length).replace(/^\/+/, "");
+    }
+    async function POST(request) {
+        const body = (await request.json().catch(() => ({})));
+        const messages = Array.isArray(body.messages) ? body.messages : [];
+        if (messages.length === 0) {
+            return new Response("请先输入内容。", {
+                headers: { "Content-Type": "text/plain; charset=utf-8" },
+            });
+        }
+        // 用户选择的模型：前端模型下拉（agent 界面配置了 AGENT_MODEL_LIST 才显示）。
+        // 覆盖默认模型，session 流会在复用会话时 setModel 运行中切换，确保实际生效。
+        const userModel = typeof body.model === "string" && body.model.trim() ? body.model.trim() : undefined;
+        // 多轮上下文续接：前端每会话生成稳定 sessionId，首轮 resume=false（新建），
+        // 后续轮 resume=true（按 sessionId 加载历史 transcript）。无 sessionId 时不续接。
+        const sessionId = typeof body.sessionId === "string" && body.sessionId ? body.sessionId : undefined;
+        const resume = Boolean(sessionId) && body.resume === true;
+        // —— 安全隔离：会话归属校验（登录用户 DB 归属）——
+        // 无 sessionId 的 query 单发不涉及跨会话访问，跳过校验。
+        if (sessionId) {
+            const access = await assertChatAccess(request, sessionId, resume);
+            if (!access) {
+                // 诊断锚点：403 只有两种成因（未登录 / 库里查不到该 sessionId），
+                // 且后者在「前端注册用 sid、发送用 sdkSid」不一致时也会命中——必须能区分，
+                // 否则前端只会显示笼统的"会话不属于当前用户"，无从下手。
+                const u = verifySession(request, loadAuthConfig());
+                const dbOn = isDbEnabled();
+                let inDb = null;
+                if (u?.sub && dbOn) {
+                    try {
+                        const row = await getAgentSession(u.sub, sessionId);
+                        inDb = row ? "found" : "missing";
+                    }
+                    catch (e) {
+                        inDb = "query-error:" + (e instanceof Error ? e.message : String(e));
+                    }
+                }
+                console.error(`[agent-kit] chat 403: reason=${!u?.sub ? "unauthenticated" : dbOn ? `session-${inDb}` : "db-disabled"}` +
+                    ` resume=${resume} sid=${sessionId} user=${u?.sub ?? "(none)"}`);
+                return Response.json({ error: "无权限访问该会话（会话不属于当前用户，或未登录）" }, { status: 403 });
+            }
+        }
+        // —— 工作目录（沙箱范围，本地 app）——
+        // 权威来源：会话记录里的 workspace_dir（服务端持久化，切会话/重启后仍生效）；
+        // 首轮注册竞态（会话行还没落库）时回退请求体里的 workspaceDir。
+        const bodyWs = typeof body.workspaceDir === "string" && body.workspaceDir.trim()
+            ? body.workspaceDir.trim()
+            : undefined;
+        let workspaceDir = bodyWs;
+        // 会话归属的用户主体键（sub，titleSink 等流外闭包使用；try 内解析失败时为 undefined）
+        let verifiedUserId;
+        if (sessionId) {
+            try {
+                const u = verifySession(request, loadAuthConfig());
+                if (u?.sub)
+                    verifiedUserId = u.sub;
+                if (u?.sub && isDbEnabled()) {
+                    const row = await getAgentSession(u.sub, sessionId);
+                    if (row)
+                        workspaceDir = row.workspaceDir ?? workspaceDir;
+                }
+            }
+            catch {
+                /* DB 查询失败不阻塞对话（本地 app 路径已由 canUseTool 兜底） */
+            }
+        }
+        // 附件复制到 CLI 真实 cwd 下（模型 Read 相对路径 attachments/<rel> 直接命中，
+        // 零路径改写依赖；绝对虚拟路径 /attachments/... 在 Windows 上读不到，见 stageVirtualCopy 注释）；
+        // protectedPaths 同时登记 bash 风格与 Windows 风格的完整真实路径（模型若复述完整路径会精确换回虚拟路径），
+        // 精确字符串匹配，用户/文档中的合法路径不受影响。
+        const rel = attachmentRel(body.attachment);
+        let readPath = "";
+        if (rel && sessionId)
+            readPath = await stageVirtualCopy(rel, sessionId, workspaceDir);
+        const realAbs = rel ? path.join(attachmentRealDir, rel) : "";
+        // 把附件可读路径提示追加到最后一条 user 消息：模型用 Read 读相对路径即可。
+        // existingContent 传最近一条 user 消息原文，附件名已含在内时 hint 不再重复拼接。
+        let hint = "";
+        {
+            let lastUserContent = "";
+            for (let i = messages.length - 1; i >= 0; i--) {
+                const m = messages[i];
+                if (m?.role === "user") {
+                    lastUserContent = String(m.content ?? "");
+                    break;
+                }
+            }
+            hint = attachmentHint(body.attachment, lastUserContent, readPath);
+        }
+        if (hint) {
+            for (let i = messages.length - 1; i >= 0; i--) {
+                const m = messages[i];
+                if (m?.role === "user") {
+                    m.content = String(m.content ?? "") + hint;
+                    break;
+                }
+            }
+        }
+        // protectedPaths 同时登记 bash 风格与 Windows 风格的完整真实路径（模型若复述完整路径会精确换回虚拟路径），
+        // 精确字符串匹配，用户/文档中的合法路径不受影响。
+        const protectedPaths = rel ? [toPosixPath(realAbs), realAbs] : [];
+        // Session 常驻模式（有 sessionId）：会话跨轮复用同一 CLI 进程，支持运行中 steer；
+        // 无 sessionId 时退化为 query 单发（旧行为）。
+        slog(sessionId, "http.chat", {
+            messages: messages.length,
+            resume,
+            attachment: body.attachment ? body.attachment.name ?? null : null,
+            lastUserPreview: (() => {
+                for (let i = messages.length - 1; i >= 0; i--) {
+                    const m = messages[i];
+                    if (m?.role === "user")
+                        return String(m.content ?? "").slice(0, 500);
+                }
+                return "";
+            })(),
+        }, "info");
+        startSessionSweeper();
+        const stream = sessionId
+            ? createAgentSessionStream({
+                messages: messages,
+                signal: request.signal,
+                config: { ...config, model: userModel ?? config.model, protectedPaths, sessionId, workspaceDir },
+                titleSink: (title) => {
+                    // SDK 自动命名标题落库：用户手动改过（user_renamed）则不覆盖
+                    if (verifiedUserId && isDbEnabled() && sessionId) {
+                        void setSessionTitleIfNotUserRenamed(verifiedUserId, sessionId, title).catch(() => { });
+                    }
+                },
+            })
+            : createAgentStream({
+                messages: messages,
+                signal: request.signal,
+                config: { ...config, model: userModel ?? config.model, protectedPaths, sessionId, resume, workspaceDir },
+                titleSink: (title) => {
+                    if (verifiedUserId && isDbEnabled() && sessionId) {
+                        void setSessionTitleIfNotUserRenamed(verifiedUserId, sessionId, title).catch(() => { });
+                    }
+                },
+            });
+        return new Response(stream, {
+            headers: {
+                "Content-Type": "text/event-stream; charset=utf-8",
+                "Cache-Control": "no-store",
+                "X-Accel-Buffering": "no",
+            },
+        });
+    }
+    return { POST };
+}
+/** POST /api/chat/answer：前端提交 AskUserQuestion 答案。
+ *  body: { sessionId, answers: { "0": "选项label", "1": "..." } }
+ *  解开挂起在 canUseTool 里的 Promise，让 CLI 把答案作为 tool_result 喂回模型，模型在同一轮继续。 */
+export function createChatAnswerHandler() {
+    async function POST(request) {
+        const body = (await request.json().catch(() => ({})));
+        const sessionId = typeof body.sessionId === "string" ? body.sessionId : "";
+        const answers = body.answers && typeof body.answers === "object" && !Array.isArray(body.answers)
+            ? body.answers
+            : null;
+        if (!sessionId || !answers) {
+            return Response.json({ error: "缺少 sessionId 或 answers" }, { status: 400 });
+        }
+        // 安全隔离：只能向自己的会话提交答案。
+        // 注：此处 resume 传 false（与 chat 首轮一致）——answer 发生在本就已鉴权的活动会话内，
+        // 挂起的提问是进程内临时态，无需再用 resume=true 强制要求会话已在 DB 落库，避免“能聊天却提交答案 403”。
+        const access = await assertChatAccess(request, sessionId, false);
+        if (!access) {
+            return Response.json({ error: "无权限访问该会话" }, { status: 403 });
+        }
+        slog(sessionId, "http.answer", { answers }, "info");
+        const ok = resolvePendingAsk(sessionId, answers);
+        slog(sessionId, "http.answer.result", { ok }, "info");
+        return Response.json({ ok });
+    }
+    return { POST };
+}
+/** POST /api/chat/steer：运行中插入消息（steer）。
+ *  body: { sessionId, text }
+ *  走 Session 常驻会话的 CLI steer 通道（stream-json control_request，CLI >= 2.140.0）：
+ *  消息进入 SteerInputBuffer，在「下一次模型请求前」注入当前轮，不打断正在执行的工具。
+ *  返回 { ok, reason }：ok=true 已插入；ok=false 时 reason 说明（no_session/no_transport/
+ *  no_session_id/idle/stale/error）。idle 表示当前轮已结束（消息应按正常轮次发送）。 */
+export function createChatSteerHandler() {
+    async function POST(request) {
+        const body = (await request.json().catch(() => ({})));
+        const sessionId = typeof body.sessionId === "string" ? body.sessionId : "";
+        const text = typeof body.text === "string" ? body.text.trim() : "";
+        if (!sessionId || !text) {
+            return Response.json({ error: "缺少 sessionId 或 text" }, { status: 400 });
+        }
+        // 安全隔离：只能向自己的会话插入消息
+        const access = await assertChatAccess(request, sessionId, true);
+        if (!access) {
+            return Response.json({ error: "无权限访问该会话" }, { status: 403 });
+        }
+        slog(sessionId, "http.steer", { textLen: text.length, text }, "info");
+        const result = await steerSession(sessionId, text);
+        return Response.json({ ok: result.steered, reason: result.reason ?? null });
+    }
+    return { POST };
+}
+export function createVoiceTokenHandler(options = {}) {
+    async function POST(request) {
+        const user = (await options.userResolver?.(request)) ?? { userId: "dev-user", name: "测试用户" };
+        return Response.json(createVoiceToken(user, { ttlSeconds: options.ttlSeconds }));
+    }
+    return { POST };
+}
+/** POST /api/chat/browser-answer：control_browser 人工接管（图形验证码等）答案回传。
+ *  body: { sessionId: browser 会话 id（browser_ask 事件 data.id）, text, chatSessionId }
+ *  先校验会话归属（只能给自己的会话回答案），再把文本注入 BrowserAgentService 的等待者。
+ *  browser 会话 id 为随机短时令牌、不可枚举，且本端点只做「注入文本」单一动作，无数据读取面。 */
+export function createBrowserAnswerHandler() {
+    async function POST(request) {
+        const body = (await request.json().catch(() => ({})));
+        const browserId = typeof body.sessionId === "string" ? body.sessionId : "";
+        const text = typeof body.text === "string" ? body.text.trim() : "";
+        const chatSessionId = typeof body.chatSessionId === "string" ? body.chatSessionId : "";
+        if (!browserId || !text) {
+            return Response.json({ error: "缺少 sessionId 或 text" }, { status: 400 });
+        }
+        // 安全隔离：只能给自己的会话提交人工接管答案
+        if (chatSessionId) {
+            const access = await assertChatAccess(request, chatSessionId, true);
+            if (!access) {
+                return Response.json({ error: "无权限访问该会话" }, { status: 403 });
+            }
+        }
+        const ok = BrowserAgentService.get().input(browserId, text);
+        slog(browserId, "http.browser-answer", { ok, textLen: text.length }, "info");
+        return Response.json({ ok });
+    }
+    return { POST };
+}
+const MAX_AUDIO_BYTES = 20 * 1024 * 1024;
+/** POST /api/voice/transcribe：校验令牌 → ASR 转写 → { text } */
+export function createVoiceTranscribeHandler(options = {}) {
+    async function POST(request) {
+        const header = request.headers.get("authorization") || "";
+        const match = header.match(/^Bearer\s+(.+)$/i);
+        const auth = verifyVoiceToken(match?.[1] ?? null);
+        if (!auth) {
+            return Response.json({ error: "语音令牌无效或已过期，请重新获取" }, { status: 401 });
+        }
+        let form;
+        try {
+            form = await request.formData();
+        }
+        catch {
+            return Response.json({ error: "请求格式错误" }, { status: 400 });
+        }
+        const file = form.get("file");
+        if (!file || typeof file === "string" || !file.size) {
+            return Response.json({ error: "没有收到录音数据" }, { status: 400 });
+        }
+        if (file.size > MAX_AUDIO_BYTES) {
+            return Response.json({ error: "录音文件过大（超过 20MB）" }, { status: 413 });
+        }
+        try {
+            const result = await transcribeVoice({
+                bytes: Buffer.from(await file.arrayBuffer()),
+                mimeType: file.type,
+                fileName: file.name,
+            });
+            const text = (result.text || "").trim();
+            if (!text) {
+                return Response.json({ error: "没有识别到清晰的语音", code: "ASR_EMPTY_TRANSCRIPT" }, { status: 422 });
+            }
+            return Response.json({ text });
+        }
+        catch (error) {
+            console.error("[agent-kit voice/transcribe] failed", error);
+            return Response.json({ error: error instanceof Error ? error.message : "语音识别暂时不可用，请稍后重试" }, { status: 502 });
+        }
+    }
+    return { POST };
+}
+/** 一键获得全部端点：{ chat, chatAnswer, chatSteer, upload, voiceToken, voiceTranscribe, artifact } */
+export function agentKitHandlers(options = {}) {
+    return {
+        chat: createChatHandler(options.chat),
+        chatAnswer: createChatAnswerHandler(),
+        chatSteer: createChatSteerHandler(),
+        browserAnswer: createBrowserAnswerHandler(),
+        upload: createUploadHandler(options.upload),
+        voiceToken: createVoiceTokenHandler(options.voice),
+        voiceTranscribe: createVoiceTranscribeHandler(options.voice),
+        artifact: createArtifactHandler(),
+    };
+}
+/**
+ * GET /api/artifact?session=<sessionId>：产物端点，三种形态：
+ *  1. 不带 file 参数但带 list=1 → 返回该会话全部产物 JSON（{ artifacts: [{id,name,type,size}] }），
+ *     供「查看所有产物 (N)」按钮与右侧产物列表面板使用（递归含子目录）。
+ *  2. ?session=&file=<id> → 按会话隔离返回产物文件内容（预览：iframe / img / 文本）。
+ *  3. 在上述基础上带 download=1 → Content-Disposition: attachment，浏览器直接下载。
+ * 服务端二次校验文件必须落在 <sessionId> 目录内（readArtifact 防穿越），
+ * HTML 以 CSP sandbox 返回，前端再以 sandbox iframe 渲染，杜绝脚本执行与跨域访问。
+ */
+export function createArtifactHandler() {
+    async function GET(request) {
+        const url = new URL(request.url);
+        const session = url.searchParams.get("session") || "";
+        if (!session) {
+            return new Response("缺少 session 参数", { status: 400 });
+        }
+        // 安全隔离：登录用户只能访问自己名下的会话（DB 归属）
+        const access = await assertSessionAccess(request, session);
+        if (!access) {
+            return new Response("无权限访问该会话的产物（会话不属于当前用户，或票据无效/过期）", { status: 403 });
+        }
+        // 工作区模式：产物根随会话的 workspace_dir 变化（本地 app 选择目录后产物落在工作区内）
+        let workspaceDir;
+        try {
+            const u = verifySession(request, loadAuthConfig());
+            if (u?.sub && isDbEnabled()) {
+                const row = await getAgentSession(u.sub, session);
+                if (row)
+                    workspaceDir = row.workspaceDir ?? undefined;
+            }
+        }
+        catch {
+            /* 解析失败按无工作区处理 */
+        }
+        // 列表模式：?list=1
+        if (url.searchParams.get("list") !== null) {
+            const artifacts = await listSessionArtifacts(session, workspaceDir);
+            return Response.json({ artifacts });
+        }
+        // 打开产物目录：?dir=1（仅本地 app 前端调用）→ 返回「跟随文件」的目录：
+        // 有产物时返回最新产物的真实所在目录（模型写到任意位置的文件 → 其父目录；
+        // 会话目录内文件 → 会话目录），无产物时回落本会话产物目录。前端（Electron preload 桥）
+        // 据此调用主进程 shell.openPath 打开资源管理器。
+        if (url.searchParams.get("dir") !== null) {
+            const artifacts = await listSessionArtifacts(session, workspaceDir);
+            const latest = Array.isArray(artifacts) ? artifacts.find((a) => a.dir) : undefined;
+            const dir = latest?.dir ?? (await ensureSessionDir(session, workspaceDir));
+            return Response.json({ dir });
+        }
+        const file = url.searchParams.get("file") || "";
+        if (!file) {
+            return new Response("缺少 file 参数", { status: 400 });
+        }
+        const result = await readArtifact(session, file, workspaceDir);
+        if (!result) {
+            return new Response("文件不存在或无访问权限", { status: 404 });
+        }
+        const headers = {
+            "Content-Type": result.mime,
+            "Cache-Control": "private, no-store",
+            "X-Content-Type-Options": "nosniff",
+        };
+        // 下载模式：Content-Disposition attachment（文件名取最后一段，RFC 5987 编码支持中文）
+        if (url.searchParams.get("download") !== null) {
+            const fileName = file.split("/").pop() || "artifact";
+            headers["Content-Disposition"] = `attachment; filename*=UTF-8''${encodeURIComponent(fileName)}`;
+        }
+        else {
+            // HTML 文档沙箱化：禁止脚本与同域访问；其余类型收紧资源加载
+            if (result.mime.startsWith("text/html")) {
+                headers["Content-Security-Policy"] = "sandbox";
+            }
+            else {
+                headers["Content-Security-Policy"] =
+                    "default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; font-src 'self' data:";
+            }
+        }
+        // Buffer → Uint8Array 视图（零拷贝）后再作为响应体：规避 @types/node 26 的 Buffer 与 BodyInit 类型不兼容
+        return new Response(new Uint8Array(result.buf), { headers });
+    }
+    return { GET };
+}
+/**
+ * Catch-all 单路由：一个文件承载对话 / 上传 / 语音 / 产物端点。
+ * 第三方 Next.js 工程只需建一个文件（其余 /api 路径仍可自由使用，Next 静态路由优先）：
+ *
+ *   // app/api/[...agent]/route.js
+ *   import { createAgentApiRoute } from "agent-kit";
+ *   export const runtime = "nodejs";
+ *   export const POST = createAgentApiRoute({ chat: { continueSession: false } });
+ *
+ * 内部按路径段分发：/api/chat、/api/upload、/api/voice/token、/api/voice/transcribe；
+ * 未知路径返回 404。
+ *
+ * 注意：若要把会话 / 分享 / 认证等全部端点也一起挂载（应用端零新增路由文件），
+ * 改用 createAgentKitApi（同包导出），它是本函数 + 其余端点工厂的统一封装。
+ */
+export function createAgentApiRoute(options = {}) {
+    const handlers = agentKitHandlers(options);
+    async function POST(request, context = {}) {
+        const params = (await Promise.resolve(context.params ?? {}));
+        const segments = params.agent ?? [];
+        const [first, second] = segments;
+        if (first === "chat" && second === "answer")
+            return handlers.chatAnswer.POST(request);
+        if (first === "chat" && second === "steer")
+            return handlers.chatSteer.POST(request);
+        if (first === "chat" && second === "browser-answer")
+            return handlers.browserAnswer.POST(request);
+        if (first === "chat")
+            return handlers.chat.POST(request);
+        if (first === "upload")
+            return handlers.upload.POST(request);
+        if (first === "voice" && second === "token")
+            return handlers.voiceToken.POST(request);
+        if (first === "voice" && second === "transcribe")
+            return handlers.voiceTranscribe.POST(request);
+        return Response.json({ error: "未找到该端点（agent-kit 支持 /api/chat、/api/chat/answer、/api/chat/steer、/api/chat/browser-answer、/api/upload、/api/voice/token、/api/voice/transcribe）" }, { status: 404 });
+    }
+    // iframe / 浏览器直接加载产物走 GET（仅 artifact 端点需要）
+    async function GET(request, context = {}) {
+        const params = (await Promise.resolve(context.params ?? {}));
+        const segments = params.agent ?? [];
+        const [first] = segments;
+        if (first === "artifact")
+            return handlers.artifact.GET(request);
+        return Response.json({ error: "未找到该端点" }, { status: 404 });
+    }
+    return { POST, GET };
+}

package/dist/server/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * agent-kit · 入口
+ * 服务端 SDK：基于 CodeBuddy Agent SDK 的订阅式对话封装（模型默认 hy3），
+ * 外加即插即用的 Next.js 端点工厂（对话/上传/语音）。
+ */
+export { runSdkQuery, createAgentStream, createAgentSessionStream, defaultCanUseTool, withSessionDirGuard, withSandboxBoundary, FILE_TOOLS, WEB_DISALLOWED_TOOLS, resolvePendingAsk, steerSession, closeSession, AGENT_SERVICE_UNAVAILABLE, WEB_FETCH_TOOL_NAME } from "./sdk.js";
+export type { SdkConfig } from "./sdk.js";
+export { assertSessionAccess, assertChatAccess } from "./session-access.js";
+export type { SessionAccessKind } from "./session-access.js";
+export { Agent, createAgent } from "./agent.js";
+export type { AgentConfig } from "./agent.js";
+export { createWebFetchMcpServer, WebFetchService } from "./web-fetch.js";
+export type { WebFetchOptions, WebFetchResult, WebFetchImage } from "./web-fetch.js";
+export { createBrowserAgentMcpServer, BROWSER_AGENT_TOOL_NAME, BrowserAgentService } from "./browser-agent-mcp.js";
+export type { BrowserTaskResult } from "./browser-agent-mcp.js";
+export { readArtifact, listSessionArtifacts, mimeFor, ensureSessionDir } from "./artifacts.js";
+export { createChatHandler, createChatAnswerHandler, createChatSteerHandler, createBrowserAnswerHandler, createVoiceTokenHandler, createVoiceTranscribeHandler, agentKitHandlers, createAgentApiRoute, createArtifactHandler, } from "./handlers.js";
+export type { AgentKitHandlersOptions, VoiceHandlerOptions } from "./handlers.js";
+export { createAgentKitApi } from "./kit-api.js";
+export type { AgentKitApiOptions } from "./kit-api.js";
+export { createUploadHandler } from "./upload.js";
+export type { UploadOptions } from "./upload.js";
+export { getModelOptions, readCodeBuddyModels } from "./model-sources.js";
+export type { ServerModelOption } from "./model-sources.js";
+export * from "./auth/index.js";
+export { createSessionHandlers } from "./sessions.js";
+export { createShareHandlers } from "./share.js";
+export type { ShareHandlers } from "./share.js";
+export { createUserFilesHandlers, userFilesRoot, userKeyFor, safeUserFilePath } from "./user-files.js";
+export type { UserFileEntry } from "./user-files.js";

package/dist/server/index.js

@@ -0,0 +1,28 @@
+/**
+ * agent-kit · 入口
+ * 服务端 SDK：基于 CodeBuddy Agent SDK 的订阅式对话封装（模型默认 hy3），
+ * 外加即插即用的 Next.js 端点工厂（对话/上传/语音）。
+ */
+export { runSdkQuery, createAgentStream, createAgentSessionStream, defaultCanUseTool, withSessionDirGuard, withSandboxBoundary, FILE_TOOLS, WEB_DISALLOWED_TOOLS, resolvePendingAsk, steerSession, closeSession, AGENT_SERVICE_UNAVAILABLE, WEB_FETCH_TOOL_NAME } from "./sdk.js";
+// 会话访问控制（安全隔离）：登录用户 DB 归属
+export { assertSessionAccess, assertChatAccess } from "./session-access.js";
+export { Agent, createAgent } from "./agent.js";
+export { createWebFetchMcpServer, WebFetchService } from "./web-fetch.js";
+export { createBrowserAgentMcpServer, BROWSER_AGENT_TOOL_NAME, BrowserAgentService } from "./browser-agent-mcp.js";
+// 产物读取（Electron 本地版等非 Next.js 宿主复用）：按会话隔离读文件 / 列产物清单
+export { readArtifact, listSessionArtifacts, mimeFor, ensureSessionDir } from "./artifacts.js";
+// 端点工厂：第三方 Next.js 应用一行引入即可复用 chat/upload/voice 端点
+export { createChatHandler, createChatAnswerHandler, createChatSteerHandler, createBrowserAnswerHandler, createVoiceTokenHandler, createVoiceTranscribeHandler, agentKitHandlers, createAgentApiRoute, createArtifactHandler, } from "./handlers.js";
+// 统一 API 路由工厂：单 catch-all 挂载全部端点（对话/会话/分享/认证），应用端零新增代码
+export { createAgentKitApi } from "./kit-api.js";
+export { createUploadHandler } from "./upload.js";
+// 模型来源解析（通用能力）：models.json 自定义模型优先，否则 env AGENT_MODEL_LIST 兜底
+export { getModelOptions, readCodeBuddyModels } from "./model-sources.js";
+// 认证（钉钉 / 飞书），可复用：抽象层 + 具体实现 + 路由工厂 + 用户持久化
+export * from "./auth/index.js";
+// 会话管理（侧边栏会话列表增删改查）
+export { createSessionHandlers } from "./sessions.js";
+// 会话分享（外部只读访问 + 发送到 OA）
+export { createShareHandlers } from "./share.js";
+// 用户文件区（以登录用户 id 为目录名的用户可操作区：浏览/上传/下载/新建/重命名/删除）
+export { createUserFilesHandlers, userFilesRoot, userKeyFor, safeUserFilePath } from "./user-files.js";

package/dist/server/kit-api.d.ts

@@ -0,0 +1,23 @@
+import type { AgentKitHandlersOptions } from "./handlers.js";
+import type { LoginHandlersOptions } from "./auth/handlers.js";
+export interface AgentKitApiOptions {
+    /** 透传给对话 / 上传 / 语音端点工厂（含 allowBash、fallbackModel、userResolver 等） */
+    agent?: AgentKitHandlersOptions;
+    /** 透传给认证端点工厂（覆盖 env 读取的认证配置） */
+    login?: LoginHandlersOptions;
+}
+/** Next.js 路由上下文（params 在 Next 15 为 Promise，需兼容） */
+interface KitRouteContext {
+    params?: {
+        path?: string[];
+    } | Promise<{
+        path?: string[];
+    }>;
+}
+export declare function createAgentKitApi(options?: AgentKitApiOptions): {
+    GET: (request: Request, context?: KitRouteContext) => Promise<Response>;
+    POST: (request: Request, context?: KitRouteContext) => Promise<Response>;
+    PATCH: (request: Request, context?: KitRouteContext) => Promise<Response>;
+    DELETE: (request: Request, context?: KitRouteContext) => Promise<Response>;
+};
+export {};