@turingflow/agent-kit 0.0.0-stage → 0.1.0

package/dist/server/cli.js

@@ -0,0 +1,112 @@
+/**
+ * agent-kit · CLI（订阅对话演示/冒烟）
+ * CodeBuddy 订阅的 login / logout 已移出 SDK，由宿主应用实现
+ * （参考 apps/web/scripts/codebuddy-auth.mjs + npm run login / logout）。
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import path from "node:path";
+import { runSdkQuery } from "./sdk.js";
+const DEMO_SESSION = [
+    "你好",
+    "你是谁",
+    "帮我写一个 hello.py",
+    "运行一下 hello.py",
+    "再见",
+];
+function loadDotEnv() {
+    // 级联加载（仅设置尚未存在的变量，进程 env 优先级最高）：
+    //   1) AGENT_ENV_FILE 显式指定的宿主 env 文件；
+    //   2) <cwd>/.env —— 宿主应用根目录（npm 安装场景）；
+    //   3) 源码仓库约定 apps/web/.env（仅 monorepo 开发，路径存在才命中）；
+    //   4) kit 本地 .env（gitignore，仅临时联调）。
+    const candidates = [
+        process.env.AGENT_ENV_FILE?.trim() ? path.resolve(process.env.AGENT_ENV_FILE.trim()) : "",
+        path.resolve(process.cwd(), ".env"),
+        path.resolve(import.meta.dirname, "../../../../apps/web/.env"),
+        path.join(import.meta.dirname, "..", ".env"),
+    ].filter(Boolean);
+    for (const envPath of candidates) {
+        if (!existsSync(envPath))
+            continue;
+        for (const line of readFileSync(envPath, "utf-8").split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const eq = trimmed.indexOf("=");
+            if (eq < 0)
+                continue;
+            const key = trimmed.slice(0, eq).trim();
+            const value = trimmed.slice(eq + 1).trim();
+            if (!(key in process.env))
+                process.env[key] = value;
+        }
+    }
+}
+async function runDemo() {
+    console.log("agent-kit 预设会话（CodeBuddy 订阅对话）");
+    for (const msg of DEMO_SESSION) {
+        console.log(`\nYou> ${msg}`);
+        try {
+            console.log(`Agent> ${await runSdkQuery(msg)}`);
+        }
+        catch (err) {
+            console.error(`对话失败：${err instanceof Error ? err.message : err}`);
+            console.error("提示：请先在宿主应用中执行登录命令（如 web 的 npm run login）。");
+            break;
+        }
+    }
+}
+async function runInteractive() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    console.log("agent-kit 订阅对话已启动（hy3），exit 退出。");
+    try {
+        while (true) {
+            let msg;
+            try {
+                msg = (await rl.question("\nYou> ")).trim();
+            }
+            catch {
+                break;
+            }
+            if (!msg)
+                continue;
+            if (["exit", "quit", "退出", "再见"].includes(msg.toLowerCase())) {
+                console.log("再见！");
+                break;
+            }
+            try {
+                console.log(`Agent> ${await runSdkQuery(msg)}`);
+            }
+            catch (err) {
+                console.error(`对话失败：${err instanceof Error ? err.message : err}`);
+            }
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+function printUsage() {
+    console.log(`agent-kit CLI — 用法：
+  npm run demo     预设订阅对话冒烟
+  无参数            交互式订阅对话
+（CodeBuddy 订阅登录/登出见宿主应用：web 的 npm run login / npm run logout）`);
+}
+async function main() {
+    loadDotEnv();
+    const args = process.argv.slice(2);
+    if (args.includes("--demo") || args.includes("demo")) {
+        await runDemo();
+        return;
+    }
+    if (args.includes("-h") || args.includes("--help") || args.includes("help")) {
+        printUsage();
+        return;
+    }
+    await runInteractive();
+}
+main().catch((err) => {
+    console.error(`出错：${err instanceof Error ? err.message : err}`);
+    process.exitCode = 1;
+});

package/dist/server/debug-log.d.ts

@@ -0,0 +1,25 @@
+/**
+ * agent-kit · 按会话落盘的调试日志（服务端）
+ *
+ * 用途：对话链路出问题时，拿"最近一个会话"的日志文件即可还原完整时间线：
+ * HTTP 请求 → Session 复用/创建 → CLI 消息流（模型/文本/思考/工具/结果）→ SSE 下发 → steer/interrupt。
+ *
+ * 设计：
+ *  - 每个 sessionId 一个文件：<logDir>/<sid>.log，每行一条 JSON（时间戳/级别/事件/明细）；
+ *  - 级别：debug < info < warn < error，env AGENT_KIT_LOG_LEVEL 控制（默认 debug，最详细）；
+ *  - 目录：env AGENT_KIT_LOG_DIR 覆盖，默认 <进程 cwd>/logs/sessions（web 下即 apps/web/logs/sessions）；
+ *  - 写入 fire-and-forget，按文件串行（promise 链）防交错；日志失败绝不影响对话主链路；
+ *  - 流式输出（text/thinking delta、SSE 帧）不逐块记日志，只保留关键锚点：
+ *    turn.start / turn.send / turn.done / turn.error / cli.system / cli.model /
+ *    cli.tool_use / cli.tool_result / cli.stream.end / cli.result；
+ *  - 明细里的长文本统一 clip 截断，保证文件可读且不爆炸。
+ */
+export declare function logDir(): string;
+/**
+ * 写一条会话日志。
+ * @param sid  会话 ID（无会话的请求传空，落到 _server.log）
+ * @param event 事件名，点分层级，如 "turn.start"、"cli.tool_use"、"steer.response"
+ * @param detail 明细（值中的长字符串自动截断）
+ * @param level  日志级别，默认 debug
+ */
+export declare function slog(sid: string | null | undefined, event: string, detail?: Record<string, unknown>, level?: "debug" | "info" | "warn" | "error"): void;

package/dist/server/debug-log.js

@@ -0,0 +1,86 @@
+/**
+ * agent-kit · 按会话落盘的调试日志（服务端）
+ *
+ * 用途：对话链路出问题时，拿"最近一个会话"的日志文件即可还原完整时间线：
+ * HTTP 请求 → Session 复用/创建 → CLI 消息流（模型/文本/思考/工具/结果）→ SSE 下发 → steer/interrupt。
+ *
+ * 设计：
+ *  - 每个 sessionId 一个文件：<logDir>/<sid>.log，每行一条 JSON（时间戳/级别/事件/明细）；
+ *  - 级别：debug < info < warn < error，env AGENT_KIT_LOG_LEVEL 控制（默认 debug，最详细）；
+ *  - 目录：env AGENT_KIT_LOG_DIR 覆盖，默认 <进程 cwd>/logs/sessions（web 下即 apps/web/logs/sessions）；
+ *  - 写入 fire-and-forget，按文件串行（promise 链）防交错；日志失败绝不影响对话主链路；
+ *  - 流式输出（text/thinking delta、SSE 帧）不逐块记日志，只保留关键锚点：
+ *    turn.start / turn.send / turn.done / turn.error / cli.system / cli.model /
+ *    cli.tool_use / cli.tool_result / cli.stream.end / cli.result；
+ *  - 明细里的长文本统一 clip 截断，保证文件可读且不爆炸。
+ */
+import fs from "node:fs";
+import path from "node:path";
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+let levelCache = null;
+function levelThreshold() {
+    if (levelCache == null) {
+        const raw = String(process.env.AGENT_KIT_LOG_LEVEL || "debug").trim().toLowerCase();
+        levelCache = LEVELS[raw] ?? LEVELS.debug;
+    }
+    return levelCache;
+}
+export function logDir() {
+    return process.env.AGENT_KIT_LOG_DIR?.trim()
+        ? path.resolve(process.env.AGENT_KIT_LOG_DIR.trim())
+        : path.resolve(process.cwd(), "logs", "sessions");
+}
+/** 长文本截断：日志可读性优先，超长部分标注省略长度 */
+function clip(v, max = 2000) {
+    if (typeof v !== "string")
+        return v;
+    if (v.length <= max)
+        return v;
+    return `${v.slice(0, max)}…[+${v.length - max} chars]`;
+}
+// 每个日志文件一条写入队列，串行追加避免并发交错
+const writeQueues = new Map();
+let dirReady = null;
+/** 首次写入前确保日志目录存在（slog 之前因目录缺失而全部静默失败，导致问题无法从日志排查） */
+function ensureDir() {
+    if (!dirReady) {
+        dirReady = fs.promises
+            .mkdir(logDir(), { recursive: true })
+            .then(() => undefined)
+            .catch(() => undefined);
+    }
+    return dirReady ?? Promise.resolve();
+}
+function appendLine(file, line) {
+    const prev = writeQueues.get(file) ?? ensureDir();
+    const next = prev
+        .then(() => fs.promises.appendFile(file, line, "utf8"))
+        .catch(() => { });
+    writeQueues.set(file, next);
+    // 队列防无限增长：写完且仍是当前尾项时清掉
+    void next.then(() => {
+        if (writeQueues.get(file) === next)
+            writeQueues.delete(file);
+    });
+}
+/**
+ * 写一条会话日志。
+ * @param sid  会话 ID（无会话的请求传空，落到 _server.log）
+ * @param event 事件名，点分层级，如 "turn.start"、"cli.tool_use"、"steer.response"
+ * @param detail 明细（值中的长字符串自动截断）
+ * @param level  日志级别，默认 debug
+ */
+export function slog(sid, event, detail = {}, level = "debug") {
+    try {
+        if (LEVELS[level] < levelThreshold())
+            return;
+        const safeSid = String(sid || "_server").replace(/[^\w.-]/g, "_").slice(0, 120) || "_server";
+        const file = path.join(logDir(), `${safeSid}.log`);
+        const record = { t: new Date().toISOString(), lvl: level, ev: event, ...detail };
+        // detail 里的长字符串统一截断
+        for (const k of Object.keys(record))
+            record[k] = clip(record[k]);
+        appendLine(file, `${JSON.stringify(record)}\n`);
+    }
+    catch { /* ignore */ }
+}

package/dist/server/handlers.d.ts

@@ -0,0 +1,141 @@
+/**
+ * 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 { type SdkConfig } from "./sdk.js";
+import { type UploadOptions } from "./upload.js";
+import { type VoiceUser } from "./voice.js";
+export interface VoiceHandlerOptions {
+    /** 令牌 TTL（秒），默认 600 */
+    ttlSeconds?: number;
+    /** 从请求解析当前用户（写入令牌 sub/name）；默认固定测试用户 */
+    userResolver?: (request: Request) => VoiceUser | null | Promise<VoiceUser | null>;
+}
+export interface AgentKitHandlersOptions {
+    /** 透传给 createAgentStream 的 SDK 配置 */
+    chat?: SdkConfig;
+    /** 附件上传配置 */
+    upload?: UploadOptions;
+    /** 语音输入配置 */
+    voice?: VoiceHandlerOptions;
+}
+/** POST /api/chat：消息数组 → agent-kit 订阅对话流 → SSE 事件流（text/thinking/done/error） */
+export declare function createChatHandler(config?: SdkConfig): {
+    POST: (request: Request) => Promise<Response>;
+};
+/** POST /api/chat/answer：前端提交 AskUserQuestion 答案。
+ *  body: { sessionId, answers: { "0": "选项label", "1": "..." } }
+ *  解开挂起在 canUseTool 里的 Promise，让 CLI 把答案作为 tool_result 喂回模型，模型在同一轮继续。 */
+export declare function createChatAnswerHandler(): {
+    POST: (request: Request) => Promise<Response>;
+};
+/** 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 declare function createChatSteerHandler(): {
+    POST: (request: Request) => Promise<Response>;
+};
+export declare function createVoiceTokenHandler(options?: VoiceHandlerOptions): {
+    POST: (request: Request) => Promise<Response>;
+};
+/** POST /api/chat/browser-answer：control_browser 人工接管（图形验证码等）答案回传。
+ *  body: { sessionId: browser 会话 id（browser_ask 事件 data.id）, text, chatSessionId }
+ *  先校验会话归属（只能给自己的会话回答案），再把文本注入 BrowserAgentService 的等待者。
+ *  browser 会话 id 为随机短时令牌、不可枚举，且本端点只做「注入文本」单一动作，无数据读取面。 */
+export declare function createBrowserAnswerHandler(): {
+    POST: (request: Request) => Promise<Response>;
+};
+/** POST /api/voice/transcribe：校验令牌 → ASR 转写 → { text } */
+export declare function createVoiceTranscribeHandler(options?: VoiceHandlerOptions): {
+    POST: (request: Request) => Promise<Response>;
+};
+/** 一键获得全部端点：{ chat, chatAnswer, chatSteer, upload, voiceToken, voiceTranscribe, artifact } */
+export declare function agentKitHandlers(options?: AgentKitHandlersOptions): {
+    chat: {
+        POST: (request: Request) => Promise<Response>;
+    };
+    chatAnswer: {
+        POST: (request: Request) => Promise<Response>;
+    };
+    chatSteer: {
+        POST: (request: Request) => Promise<Response>;
+    };
+    browserAnswer: {
+        POST: (request: Request) => Promise<Response>;
+    };
+    upload: {
+        POST: (request: Request) => Promise<Response>;
+    };
+    voiceToken: {
+        POST: (request: Request) => Promise<Response>;
+    };
+    voiceTranscribe: {
+        POST: (request: Request) => Promise<Response>;
+    };
+    artifact: {
+        GET: (request: Request) => Promise<Response>;
+    };
+};
+/**
+ * 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 declare function createArtifactHandler(): {
+    GET: (request: Request) => Promise<Response>;
+};
+interface RouteContext {
+    params?: {
+        agent?: string[];
+    } | Promise<{
+        agent?: string[];
+    }>;
+}
+/**
+ * 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 declare function createAgentApiRoute(options?: AgentKitHandlersOptions): {
+    POST: (request: Request, context?: RouteContext) => Promise<Response>;
+    GET: (request: Request, context?: RouteContext) => Promise<Response>;
+};
+export {};