@turingflow/agent-kit 0.0.0-stage → 0.1.1

package/dist/server/user-files.d.ts

@@ -0,0 +1,28 @@
+/** 用户文件区在产物根下的目录名（点开头 = 中间产物，不会被产物收集扫到） */
+export declare const USER_FILES_DIR_NAME = "users";
+/** 目录名派生：sub（provider:unionId）→ 安全的单层目录名。
+ *  ':' 在 Windows 非法 → 换成 '_'；再叠 8 位 hash 防不同 sub 清洗后撞名。 */
+export declare function userKeyFor(sub: string): string;
+/** 用户文件区根目录：<产物根>/users/<userKey>/ */
+export declare function userFilesRoot(sub: string): string;
+/**
+ * 把用户传入的相对路径解析为绝对路径，并强制落在 root 内。
+ * 返回 null 表示非法（穿越 / 绝对路径 / 空路径 / 越界）。
+ * 与产物读取同一套思路：先清洗再复核，不信任任何客户端输入。
+ */
+export declare function safeUserFilePath(root: string, rel: unknown): string | null;
+/** 当前请求者：登录用户 sub（主体键）。未登录返回 null。
+ *  目录名只由此派生，前端无法指定他人目录。 */
+export declare function currentUserSub(request: Request): string | null;
+export interface UserFileEntry {
+    name: string;
+    path: string;
+    isDir: boolean;
+    size: number;
+    mtimeMs: number;
+}
+export declare function createUserFilesHandlers(): {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+    DELETE: (request: Request) => Promise<Response>;
+};

package/dist/server/user-files.js

@@ -0,0 +1,311 @@
+/**
+ * agent-kit · 用户文件区（User Files）：以登录用户 id 为目录名的**用户可操作区**
+ *
+ * 背景：产物（artifact）是「模型写给用户看的」，落<产物根>/<会话id>/，随会话隔离。
+ * 但用户往往需要一块**自己能改**的地方：上传原始资料、下载成品、清理中间件、
+ * 沉淀跨会话复用的资料。这类需求此前没有落点——模型只能写会话目录，用户只能看。
+ *
+ * 目录：<产物根>/users/<userKey>/，userKey = 由主体键 sub（`provider:unionId`）派生：
+ *   - 同一用户跨会话共享同一份文件（不按会话再分层，避免会话堆积导致文件失联）；
+ *   - 用户之间天然隔离：目录名由服务端从登录态派生，**不接受前端传入**。
+ *
+ * 权限边界（本模块是"放开"的口子，必须收紧）：
+ *   - 入口必须登录，且目录名只从 verifySession 的 sub 派生（伪造不了他人目录）；
+ *   - 所有路径经 safeUserFilePath 归一 + 边界复核，`..`、绝对路径、符号链接一律拒绝；
+ *   - 只在本模块自己的 users/ 子树内活动，够不到会话产物、服务端代码、其他用户数据；
+ *   - 不与模型沙箱混用：模型的可写 allowRoots 不包含用户目录（除非显式开启），
+ *     用户对自己目录的操作也不经过模型，因此与「防模型乱改服务」的目标不冲突。
+ *
+ * 端点（挂载见 kit-api.ts 的 /api/user-files/*）：
+ *   GET    /api/user-files?path=<相对路径>   列目录（path 为空 = 根）
+ *   POST   /api/user-files                  上传（multipart，字段名 file；可选 path 指定子目录）
+ *   GET    /api/user-files/raw?path=<相对>   下载 / 预览单个文件内容
+ *   DELETE /api/user-files?path=<相对>       删除文件或空目录
+ *   POST   /api/user-files/mkdir            新建子目录 { path }
+ *   POST   /api/user-files/rename           重命名/移动 { from, to }
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { artifactRoot, mimeFor, sanitizeArtifactName } from "./artifacts.js";
+import { verifySession } from "./auth/handlers.js";
+import { loadAuthConfig } from "./auth/config.js";
+/** 用户文件区在产物根下的目录名（点开头 = 中间产物，不会被产物收集扫到） */
+export const USER_FILES_DIR_NAME = "users";
+/** 单文件上传上限（默认 50MB，比附件的 20MB 宽：这里放的是资料/成品，不是聊天图） */
+const MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
+/** 目录名派生：sub（provider:unionId）→ 安全的单层目录名。
+ *  ':' 在 Windows 非法 → 换成 '_'；再叠 8 位 hash 防不同 sub 清洗后撞名。 */
+export function userKeyFor(sub) {
+    const cleaned = String(sub || "").replace(/[^a-zA-Z0-9_-]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 64);
+    let h = 5381;
+    for (let i = 0; i < sub.length; i++)
+        h = ((h << 5) + h + sub.charCodeAt(i)) | 0;
+    const hash = (h >>> 0).toString(16).padStart(8, "0").slice(0, 8);
+    return cleaned ? `${cleaned}_${hash}` : `user_${hash}`;
+}
+/** 用户文件区根目录：<产物根>/users/<userKey>/ */
+export function userFilesRoot(sub) {
+    return path.join(artifactRoot(), USER_FILES_DIR_NAME, userKeyFor(sub));
+}
+/**
+ * 把用户传入的相对路径解析为绝对路径，并强制落在 root 内。
+ * 返回 null 表示非法（穿越 / 绝对路径 / 空路径 / 越界）。
+ * 与产物读取同一套思路：先清洗再复核，不信任任何客户端输入。
+ */
+export function safeUserFilePath(root, rel) {
+    const raw = String(rel ?? "").trim();
+    // 绝对路径、盘符、UNC 一律拒绝——用户区只接受相对路径
+    if (!raw)
+        return root;
+    if (path.isAbsolute(raw) || /^[a-zA-Z]:/.test(raw) || raw.includes("\0"))
+        return null;
+    const cleaned = sanitizeArtifactName(raw.replace(/\\/g, "/"));
+    const abs = path.resolve(root, cleaned);
+    const base = path.resolve(root);
+    if (abs !== base && !abs.startsWith(base + path.sep))
+        return null;
+    return abs;
+}
+function json(data, status = 200) {
+    return new Response(JSON.stringify(data), {
+        status,
+        headers: { "Content-Type": "application/json; charset=utf-8" },
+    });
+}
+const err = (msg, status) => json({ error: msg }, status);
+/** 当前请求者：登录用户 sub（主体键）。未登录返回 null。
+ *  目录名只由此派生，前端无法指定他人目录。 */
+export function currentUserSub(request) {
+    const user = verifySession(request, loadAuthConfig());
+    return user?.sub ?? null;
+}
+/** 列目录（不递归）。path 为空返回根。 */
+async function listDir(root, rel) {
+    const dir = safeUserFilePath(root, rel);
+    if (!dir)
+        return { error: "非法路径", status: 400 };
+    let dirents;
+    try {
+        dirents = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT")
+            return { entries: [] };
+        if (code === "ENOTDIR")
+            return { error: "不是目录", status: 400 };
+        return { error: "读取目录失败", status: 500 };
+    }
+    const entries = [];
+    for (const d of dirents) {
+        // 隐藏项（点开头）不对用户暴露，避免与内部元数据混淆
+        if (d.name.startsWith("."))
+            continue;
+        const abs = path.join(dir, d.name);
+        try {
+            const st = await fs.stat(abs);
+            entries.push({
+                name: d.name,
+                path: path.relative(root, abs).split(path.sep).join("/"),
+                isDir: st.isDirectory(),
+                size: st.isDirectory() ? 0 : st.size,
+                mtimeMs: st.mtimeMs,
+            });
+        }
+        catch {
+            /* 并发删除等：跳过该条 */
+        }
+    }
+    // 目录在前；同类按名称自然序
+    entries.sort((a, b) => (a.isDir === b.isDir ? a.name.localeCompare(b.name) : a.isDir ? -1 : 1));
+    return { entries };
+}
+export function createUserFilesHandlers() {
+    /** 取 root + 校验登录；未登录返回 401 */
+    async function resolve(request) {
+        const sub = currentUserSub(request);
+        if (!sub)
+            return err("未登录", 401);
+        const root = userFilesRoot(sub);
+        try {
+            await fs.mkdir(root, { recursive: true });
+        }
+        catch {
+            return err("用户目录不可用", 500);
+        }
+        return { root, sub };
+    }
+    async function GET(request) {
+        const ctx = await resolve(request);
+        if (ctx instanceof Response)
+            return ctx;
+        const url = new URL(request.url);
+        const raw = url.searchParams.get("path") ?? "";
+        // /raw = 下载/预览单个文件
+        if (url.searchParams.get("raw") !== null) {
+            const abs = safeUserFilePath(ctx.root, raw);
+            if (!abs)
+                return err("非法路径", 400);
+            let st;
+            try {
+                st = await fs.stat(abs);
+            }
+            catch {
+                return err("文件不存在", 404);
+            }
+            if (st.isDirectory())
+                return err("目标是目录", 400);
+            const buf = await fs.readFile(abs).catch(() => null);
+            if (!buf)
+                return err("读取失败", 500);
+            const headers = {
+                "Content-Type": mimeFor(raw),
+                "Cache-Control": "private, no-store",
+                "X-Content-Type-Options": "nosniff",
+            };
+            if (url.searchParams.get("download") !== null) {
+                headers["Content-Disposition"] =
+                    `attachment; filename*=UTF-8''${encodeURIComponent(path.basename(abs))}`;
+            }
+            else if (mimeFor(raw).startsWith("text/html")) {
+                // HTML 预览沙箱化，与产物预览一致
+                headers["Content-Security-Policy"] = "sandbox";
+            }
+            return new Response(new Uint8Array(buf), { headers });
+        }
+        const res = await listDir(ctx.root, raw);
+        if ("error" in res)
+            return err(res.error, res.status);
+        return json({ path: sanitizeArtifactName(raw.replace(/\\/g, "/")), entries: res.entries });
+    }
+    async function POST(request) {
+        const ctx = await resolve(request);
+        if (ctx instanceof Response)
+            return ctx;
+        const url = new URL(request.url);
+        const op = url.pathname.endsWith("/mkdir") ? "mkdir" : url.pathname.endsWith("/rename") ? "rename" : "upload";
+        if (op === "mkdir" || op === "rename") {
+            let body;
+            try {
+                body = await request.json();
+            }
+            catch {
+                return err("请求格式错误", 400);
+            }
+            if (op === "mkdir") {
+                const abs = safeUserFilePath(ctx.root, body.path);
+                if (!abs)
+                    return err("非法路径", 400);
+                if (abs === path.resolve(ctx.root))
+                    return err("不能创建根目录", 400);
+                try {
+                    await fs.mkdir(abs, { recursive: false });
+                }
+                catch (e) {
+                    const code = e.code;
+                    if (code === "EEXIST")
+                        return err("同名目录已存在", 409);
+                    if (code === "ENOENT")
+                        return err("父目录不存在", 404);
+                    return err("创建失败", 500);
+                }
+                return json({ ok: true, path: path.relative(ctx.root, abs).split(path.sep).join("/") });
+            }
+            // rename：from/to 都要在自己的目录内，且目标不存在（不做隐式覆盖）
+            const from = safeUserFilePath(ctx.root, body.from);
+            const to = safeUserFilePath(ctx.root, body.to);
+            if (!from || !to)
+                return err("非法路径", 400);
+            if (from === path.resolve(ctx.root) || to === path.resolve(ctx.root))
+                return err("不能重命名根目录", 400);
+            const toStat = await fs.stat(to).catch(() => null);
+            if (toStat)
+                return err("目标已存在", 409);
+            try {
+                await fs.rename(from, to);
+            }
+            catch (e) {
+                const code = e.code;
+                if (code === "ENOENT")
+                    return err("源不存在", 404);
+                return err("重命名失败", 500);
+            }
+            return json({ ok: true, path: path.relative(ctx.root, to).split(path.sep).join("/") });
+        }
+        // upload：multipart，字段名 file；可选 query path = 目标子目录
+        let form;
+        try {
+            form = await request.formData();
+        }
+        catch {
+            return err("请求格式错误", 400);
+        }
+        const file = form.get("file");
+        if (!file || typeof file === "string")
+            return err("没有收到文件", 400);
+        const buf = Buffer.from(await file.arrayBuffer());
+        if (buf.length > MAX_UPLOAD_BYTES) {
+            return err(`文件超过 ${Math.floor(MAX_UPLOAD_BYTES / 1024 / 1024)}MB 上限`, 400);
+        }
+        const dir = safeUserFilePath(ctx.root, url.searchParams.get("path") ?? "");
+        if (!dir)
+            return err("非法路径", 400);
+        // 保留原文件名（去路径成分 + 清洗），同名自动加 (n) 后缀，不静默覆盖
+        const rawName = path.basename(String(file.name || "file")).replace(/[\\/:*?"<>|\s]+/g, "_");
+        const base = sanitizeArtifactName(rawName);
+        let name = base;
+        for (let i = 1; i < 1000; i++) {
+            const exists = await fs.stat(path.join(dir, name)).then(() => true).catch(() => false);
+            if (!exists)
+                break;
+            const dot = base.lastIndexOf(".");
+            name = dot > 0 ? `${base.slice(0, dot)}(${i})${base.slice(dot)}` : `${base}(${i})`;
+        }
+        try {
+            await fs.mkdir(dir, { recursive: true });
+            await fs.writeFile(path.join(dir, name), buf);
+        }
+        catch {
+            return err("保存失败", 500);
+        }
+        return json({
+            ok: true,
+            name,
+            size: buf.length,
+            path: path.relative(ctx.root, path.join(dir, name)).split(path.sep).join("/"),
+        });
+    }
+    async function DELETE(request) {
+        const ctx = await resolve(request);
+        if (ctx instanceof Response)
+            return ctx;
+        const url = new URL(request.url);
+        const abs = safeUserFilePath(ctx.root, url.searchParams.get("path") ?? "");
+        if (!abs)
+            return err("非法路径", 400);
+        if (abs === path.resolve(ctx.root))
+            return err("不能删除根目录", 400);
+        let st;
+        try {
+            st = await fs.stat(abs);
+        }
+        catch {
+            return err("目标不存在", 404);
+        }
+        try {
+            // 目录必须为空才删——递归删除风险太高，宁可让用户自己一层层清
+            if (st.isDirectory())
+                await fs.rmdir(abs);
+            else
+                await fs.unlink(abs);
+        }
+        catch (e) {
+            const code = e.code;
+            if (["ENOTEMPTY", "EEXIST"].includes(code ?? ""))
+                return err("目录非空，请先清空", 409);
+            return err("删除失败", 500);
+        }
+        return json({ ok: true });
+    }
+    return { GET, POST, DELETE };
+}

package/dist/server/voice.d.ts

@@ -0,0 +1,25 @@
+export interface VoiceUser {
+    userId?: string;
+    name?: string;
+    sub?: string;
+    nick?: string;
+}
+export declare function createVoiceToken(user: VoiceUser, { ttlSeconds }?: {
+    ttlSeconds?: number;
+}): {
+    token: string;
+    tokenType: string;
+    expiresAt: number;
+};
+export declare function verifyVoiceToken(token: string | null | undefined): {
+    purpose?: string;
+    exp?: number;
+} | null;
+export declare function transcribeVoice({ bytes, mimeType, fileName, }: {
+    bytes: Buffer;
+    mimeType: string;
+    fileName: string;
+}): Promise<{
+    text: string;
+    provider: string;
+}>;

package/dist/server/voice.js

@@ -0,0 +1,61 @@
+/**
+ * agent-kit · 语音输入服务端（Next.js App Router 通用 handler）
+ *
+ * 短时令牌（HMAC-SHA256 签名，默认 10 分钟有效）+ ASR 转写。
+ * 前端录音前先取 token，再带 Bearer token 调 transcribe 接口。
+ * 默认转写后端：BrandAgent / 小米 MiMo（见 transcription/xiaomi-mimo.ts）。
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { transcribeWithXiaomiMimo } from "./transcription/xiaomi-mimo.js";
+const DEFAULT_TTL_MS = 10 * 60 * 1000;
+function tokenSecret() {
+    return (process.env.AGENT_KIT_VOICE_TOKEN_SECRET ||
+        process.env.HOTLINE_ASR_TOKEN_SECRET ||
+        process.env.HOTLINE_SESSION_SECRET ||
+        "agent-kit-2026");
+}
+function sign(value) {
+    return createHmac("sha256", tokenSecret()).update(value).digest("base64url");
+}
+export function createVoiceToken(user, { ttlSeconds } = {}) {
+    const ttlMs = Math.min(DEFAULT_TTL_MS, Math.max(60_000, (Number(ttlSeconds) || 600) * 1000));
+    const payload = Buffer.from(JSON.stringify({
+        purpose: "agent-kit-voice",
+        sub: user.userId || user.sub || "user",
+        name: user.name || user.nick || "",
+        exp: Date.now() + ttlMs,
+    })).toString("base64url");
+    return { token: `${payload}.${sign(payload)}`, tokenType: "Bearer", expiresAt: Date.now() + ttlMs };
+}
+export function verifyVoiceToken(token) {
+    if (!token || !token.includes("."))
+        return null;
+    const [payload, signature] = token.split(".");
+    if (!payload || !signature)
+        return null;
+    const expected = Buffer.from(sign(payload));
+    const provided = Buffer.from(signature);
+    if (provided.length !== expected.length || !timingSafeEqual(provided, expected))
+        return null;
+    try {
+        const data = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+        if (data.purpose !== "agent-kit-voice")
+            return null;
+        if (typeof data.exp !== "number" || data.exp <= Date.now())
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+// 按环境变量选择转写后端（默认小米 MiMo，经 BrandAgent 平台）。
+export async function transcribeVoice({ bytes, mimeType, fileName, }) {
+    const provider = (process.env.AGENT_KIT_ASR_PROVIDER || process.env.HOTLINE_ASR_PROVIDER || "xiaomi")
+        .trim()
+        .toLowerCase();
+    if (provider === "tencent" || provider === "tencent-cloud") {
+        throw new Error("腾讯云转写未接入（agent-kit 默认提供 BrandAgent / 小米 MiMo）");
+    }
+    return transcribeWithXiaomiMimo({ bytes, mimeType, fileName });
+}

package/dist/server/web-fetch.d.ts

@@ -0,0 +1,71 @@
+/**
+ * agent-kit · web-fetch MCP 工具（方案B：真实浏览器抓取，正文 + 图片）
+ *
+ * 背景：CodeBuddy 内置网页抓取工具能渲染正文，但内容清洗管线会剥离 <img>；
+ * 而今日头条等反爬站图片 CDN 对冷 HTTP 请求一律 403，图片必须在页面会话内抓取。
+ *
+ * 本模块用 Playwright 持久浏览器上下文（launchPersistentContext）实现：
+ *   - 真实 Chromium 执行页面 JS（自动过 __ac_signature 类签名挑战）；
+ *   - 图片在页面上下文内 fetch（携带会话），绕开图片 CDN 403；
+ *   - 持久 userDataDir 复用登录态/会话，降低反复建连开销。
+ *
+ * 对外暴露一个 MCP 工具：fetch_webpage(url, maxImages?, maxTextChars?)
+ * 返回：{ title, text, images: [{ url, mediaType, bytes, base64 }] }
+ */
+import { type Page } from "playwright";
+import { type SdkMcpServerResult } from "@tencent-ai/agent-sdk";
+export interface WebFetchOptions {
+    /** 最大返回图片数（0 = 不抓图），默认 3 */
+    maxImages?: number;
+    /** 正文最大字符数，默认 60000 */
+    maxTextChars?: number;
+    /** 单张图片最大字节数，默认 800KB，超限跳过 */
+    maxBytesPerImage?: number;
+    /** 页面渲染等待上限（ms），默认 25s */
+    navigationTimeoutMs?: number;
+    /** 持久上下文 userDataDir（默认 <cwd>/.web-fetch-profile） */
+    profileDir?: string;
+    /** 是否无头模式，默认 true */
+    headless?: boolean;
+}
+export interface WebFetchImage {
+    url: string;
+    mediaType: string;
+    bytes: number;
+    base64: string;
+}
+export interface WebFetchResult {
+    url: string;
+    title: string;
+    text: string;
+    images: WebFetchImage[];
+    imageSkipped: number;
+    truncated: boolean;
+}
+/** 是否头条系图片 URL（仅用于头条页图片去重范围；普通页面取 article 内全部图片） */
+export declare function isMediaUrl(u: string): boolean;
+export declare function collectImageUrls(page: Page): Promise<string[]>;
+/**
+ * WebFetchService：单例浏览器（持久上下文），串行处理请求。
+ * 浏览器实例跨请求复用；每个请求独立 page，处理完即关。
+ */
+export declare class WebFetchService {
+    private static instance;
+    private contextPromise;
+    private queue;
+    private readonly opts;
+    private constructor();
+    static get(opts?: WebFetchOptions): WebFetchService;
+    private context;
+    /** 串行执行（同一浏览器上下文同一时刻只跑一个请求） */
+    private run;
+    /** 抓取单个网页：正文 + 图片（base64） */
+    fetchWebpage(url: string, opts?: WebFetchOptions): Promise<WebFetchResult>;
+    private doFetch;
+    /** 释放浏览器（进程退出时调用） */
+    close(): Promise<void>;
+}
+/** 每次调用创建独立 McpServer 实例（绝不共享）：agent-sdk 每个 query 的 transport 都会对
+ *  传入实例调用 server.connect()，而 MCP Protocol 实例只允许 connect 一次；共享实例在并发
+ *  或先后复用时抛 "Already connected to a transport"。薄壳开销可忽略（WebFetchService 为单例）。 */
+export declare function createWebFetchMcpServer(opts?: WebFetchOptions): SdkMcpServerResult;