@zqagent/core 0.2.20 → 0.3.6

package/dist/types-BYyXWWPW.d.ts

@@ -0,0 +1,237 @@
+import { ModelCapability } from '@zqagent/shared/model-capabilities';
+
+/** 一次提交的附件总大小上限（原文件字节数，不含 base64 膨胀） */
+declare const MAX_ATTACHMENT_BYTES: number;
+/** 一次提交的附件个数上限（DeepSeek 单请求最多 600 张，这里只是防误操作） */
+declare const MAX_ATTACHMENTS = 4;
+/** 单个附件 */
+interface MessageAttachment {
+    /** 原始文件名（展示 + 供应商侧提示用） */
+    name: string;
+    /** MIME 类型（如 image/png），与 dataUrl 内声明的一致 */
+    mimeType: string;
+    /** `data:<mime>;base64,<payload>` */
+    dataUrl: string;
+}
+/** 附件校验失败（调用方转成 400，避免把供应商的晦涩报错暴露给用户） */
+declare class AttachmentError extends Error {
+    constructor(message: string);
+}
+/** 附件的实际字节数（按 base64 长度反推，不真正解码） */
+declare function attachmentBytes(a: MessageAttachment): number;
+/**
+ * 校验并规范化请求里的附件。
+ *
+ * 返回 `undefined` 表示「没有附件」。**不再限制类型**：任何文件都可以随消息
+ * 发送，能直接给模型读的走内联，不能的落到工作目录（见 `splitByCapability`）。
+ * 只有结构性错误（不是 data URL、超限）才抛 `AttachmentError`，由 HTTP /
+ * 指令层转成 400——静默丢弃会让用户以为文件发出去了。
+ */
+declare function normalizeAttachments(v: unknown): MessageAttachment[] | undefined;
+/**
+ * 按「当前模型的输入能力」把附件分成两拨：
+ *
+ *   - `inline`：模型能直接读的（图片/音频/视频，且该模态已勾选），内联进请求；
+ *   - `workspace`：其余全部——模型没开能力的模态，以及 PDF / 表格 / 压缩包
+ *     这类模型根本不吃的文件。它们会被写进工作目录，路径交给助手去读。
+ *
+ * `capabilities` 为 `undefined` 表示调用方没提供模型能力（例如直接使用 core
+ * 的集成方、CLI）：沿用旧行为，凡是模态可识别的都内联，避免把图片莫名存盘。
+ */
+declare function splitByCapability(attachments: MessageAttachment[] | undefined, capabilities: ModelCapability[] | undefined): {
+    inline: MessageAttachment[];
+    workspace: MessageAttachment[];
+};
+/**
+ * 已落盘的附件引用（消息 / 事件 / 轮次索引里只带它，不带 base64）。
+ *
+ * `path` 相对会话目录（如 `attachments/1712-0-shot.png`），前端按
+ * `readSessionAttachment` 取回内容。
+ */
+interface StoredAttachment {
+    /** 原始文件名（展示用） */
+    name: string;
+    /** MIME 类型 */
+    mimeType: string;
+    /** 原始字节数 */
+    size: number;
+    /** 相对会话目录的路径（POSIX 分隔符） */
+    path: string;
+}
+/** 附件目录名（相对会话目录） */
+declare const ATTACHMENT_DIR = "attachments";
+/**
+ * 把附件字节写到会话目录下的 `attachments/`，返回轻量引用。
+ *
+ * 落盘失败不影响本轮请求（附件仍会内联给模型），只在返回里跳过该条；
+ * 写盘用「时间戳 + 序号」前缀保证同一会话内不重名。
+ */
+declare function saveAttachments(sessionDir: string, attachments: MessageAttachment[] | undefined): StoredAttachment[];
+/**
+ * 附件落到**工作目录**（模型读不了、交给助手用文件工具去读的那一拨）。
+ *
+ * 与 `saveAttachments` 的区别：
+ *   - 位置：工作目录下的 `uploads/`，是助手能用 `read_file` 等工具直接读到的路径；
+ *   - 命名：保留原文件名（助手和用户都认得出），重名时自动加 `-2`、`-3`；
+ *   - 返回相对工作目录的路径，写进消息里给模型看。
+ */
+declare const UPLOAD_DIR = "uploads";
+/** 落盘到工作目录后的引用（`path` 相对工作目录） */
+interface WorkspaceFileRef {
+    name: string;
+    mimeType: string;
+    size: number;
+    path: string;
+}
+/**
+ * 写入工作目录。单个文件失败不影响其余文件（返回里跳过该条），
+ * 也不影响本轮请求——调用方按返回结果决定提到哪些文件。
+ */
+declare function saveAttachmentsToWorkspace(workspaceRoot: string, attachments: MessageAttachment[] | undefined): WorkspaceFileRef[];
+declare function buildWorkspaceFileNotice(files: WorkspaceFileRef[]): string;
+/**
+ * 读取已落盘的附件（聊天记录里的缩略图 / 大图）。
+ *
+ * `relPath` 必须落在 `attachments/` 下且是单层文件名：拒绝 `..`、子目录与
+ * 其它目录，避免这条只读接口被用来读会话目录里的别的东西。
+ */
+declare function readStoredAttachment(sessionDir: string, relPath: string): {
+    name: string;
+    mimeType: string;
+    size: number;
+    base64: string;
+};
+/** 剥掉所有消息上的附件（落盘 / 事件 / 会话摘要用） */
+declare function stripAttachments<T>(messages: T[]): T[];
+/** 消息是否带非图片附件（Responses API 只支持图片，需要降级到 Chat） */
+declare function hasNonImageAttachments(messages: {
+    attachments?: MessageAttachment[];
+}[]): boolean;
+
+/**
+ * 基础类型定义
+ *
+ * 与 Python 版 zqagent 对齐的基础类型。这里定义了 Agent 引擎内部
+ * 流转的核心数据模型：LLM 工具调用、助手回复、Token 用量、流式 chunk、
+ * 对话消息以及 OpenAI 工具 Schema。
+ */
+
+/** LLM 请求的工具调用 */
+interface ToolCall {
+    /** 工具调用 ID（OpenAI 格式，用于把 tool 结果消息关联回对应的调用） */
+    id: string;
+    /** 工具名称 */
+    name: string;
+    /** 工具参数（已解析为对象的形态） */
+    arguments: Record<string, unknown>;
+}
+/** LLM 一次回复 */
+interface AssistantTurn {
+    /** 回复正文文本；无文本时为 null */
+    text: string | null;
+    /** 本次回复请求的工具调用列表（可能为空） */
+    toolCalls: ToolCall[];
+    /** 结束原因（stop / tool_calls / length 等），由 Provider 提供 */
+    finishReason: string | null;
+    /** 推理过程内容（如 OpenAI o 系列模型的 reasoning_content） */
+    reasoning: string | null;
+    /** 本次调用的 Token 用量统计 */
+    usage: TokenUsage | null;
+}
+/** 标准化的 Token 用量 */
+interface TokenUsage {
+    /** 输入 token 数 */
+    input: number;
+    /** 输出 token 数 */
+    output: number;
+    /** 命中缓存（缓存读取）的 token 数 */
+    cacheRead: number;
+    /** 写入缓存的 token 数 */
+    cacheWrite: number;
+}
+/** 流式输出的单个 chunk */
+interface StreamChunk {
+    /** 文本增量；该 chunk 无文本时为 null */
+    content: string | null;
+    /** 推理内容增量 */
+    reasoning: string | null;
+    /**
+     * 工具调用：流式过程中为 null；
+     * 流结束的最终 chunk 中，有工具调用时为完整列表，否则为 null
+     */
+    toolCalls: ToolCall[] | null;
+    /** 累计 Token 用量（OpenAI 在流结束前的最后一个 chunk 中返回） */
+    usage: TokenUsage | null;
+    /** 结束原因（仅在流结束 chunk 中出现） */
+    finishReason: string | null;
+}
+/** 对话消息 */
+interface Message {
+    /** 本轮任务ID */
+    taskId?: string;
+    /** 消息角色 */
+    role: "system" | "user" | "assistant" | "tool" | "notice";
+    /** 消息正文 */
+    content: string;
+    /**
+     * 用户消息的附件（图片/音频/视频，base64 data URL）。
+     *
+     * 仅在产生它的这一轮里发给模型：`_finalizeOutbound` 会剥离历史轮次的附件，
+     * 落盘前也会被 `stripAttachments` 去掉（见 `engine/attachments.ts`）。
+     */
+    attachments?: MessageAttachment[];
+    /**
+     * 同一批附件的落盘引用（轻量，会随消息一起落盘）。
+     *
+     * 控制台用它在用户消息上方渲染缩略图、在聊天详情里回看；字节本体存在
+     * `sessions/<id>/attachments/` 下。
+     */
+    attachmentRefs?: StoredAttachment[];
+    /** 附加来源信息（展示用） */
+    source?: Record<string, unknown>;
+    /** 展示用的替代文本（展示用） */
+    _display?: string;
+    /** 消息时间戳 */
+    ts?: number;
+    /** 推理过程文本（assistant 消息） */
+    reasoning?: string;
+    /** Token 用量（assistant 消息） */
+    usage?: Record<string, unknown>;
+    /** 关联的工具调用 ID（tool 消息回填用） */
+    tool_call_id?: string;
+    /** 工具调用名称（tool 消息回填用） */
+    tool_call_name?: string;
+    /** 工具调用列表（assistant 消息，OpenAI 格式） */
+    tool_calls?: {
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }[];
+    /** 通知类型：错误 / 中断 / 上下文压缩 / 模型切换 */
+    kind?: "error" | "interrupted" | "compacted" | "model_switch" | "retry";
+    /** 通知附加文本 */
+    text?: string;
+}
+/**
+ * 推理强度（reasoning effort）
+ *
+ * 控制模型在生成答案前投入的推理计算量（OpenAI 的
+ * reasoning_effort / Responses 的 reasoning.effort 参数）。
+ * 仅对支持该参数的非 DeepSeek 模型生效（DeepSeek 用 thinking
+ * 布尔开关，不支持级别控制，Provider 层会跳过）。
+ */
+type ReasoningEffort = "low" | "medium" | "high";
+/** OpenAI 工具 Schema */
+interface ToolSchema {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+
+export { ATTACHMENT_DIR as A, type Message as M, type ReasoningEffort as R, type StreamChunk as S, type TokenUsage as T, UPLOAD_DIR as U, type WorkspaceFileRef as W, type ToolSchema as a, type MessageAttachment as b, type StoredAttachment as c, type AssistantTurn as d, AttachmentError as e, MAX_ATTACHMENTS as f, MAX_ATTACHMENT_BYTES as g, type ToolCall as h, attachmentBytes as i, buildWorkspaceFileNotice as j, hasNonImageAttachments as k, saveAttachmentsToWorkspace as l, splitByCapability as m, normalizeAttachments as n, stripAttachments as o, readStoredAttachment as r, saveAttachments as s };

package/package.json

@@ -1,15 +1,12 @@
 {
   "name": "@zqagent/core",
-  "version": "0.2.20",
+  "version": "0.3.6",
   "description": "TypeScript agent engine core — TurnEngine, ToolRegistry, PermissionEngine, OpenAI provider with 18 built-in tools",
   "author": "成都志前科技有限公司",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "bin": {
-    "zqagent": "./bin/zqagent"
-  },
   "exports": {
     ".": {
       "import": {
@@ -21,16 +18,6 @@
         "default": "./dist/index.cjs"
       }
     },
-    "./server": {
-      "import": {
-        "types": "./dist/server/index.d.ts",
-        "default": "./dist/server/index.js"
-      },
-      "require": {
-        "types": "./dist/server/index.d.cts",
-        "default": "./dist/server/index.cjs"
-      }
-    },
     "./tools/fs": {
       "import": {
         "types": "./dist/tools/files.d.ts",
@@ -141,6 +128,16 @@
         "default": "./dist/tools/explore.cjs"
       }
     },
+    "./internal/*": {
+      "import": {
+        "types": "./dist/internal/*.d.ts",
+        "default": "./dist/internal/*.js"
+      },
+      "require": {
+        "types": "./dist/internal/*.d.cts",
+        "default": "./dist/internal/*.cjs"
+      }
+    },
     "./tools/media": {
       "import": {
         "types": "./dist/tools/media.d.ts",
@@ -154,36 +151,22 @@
   },
   "files": [
     "dist/",
-    "bin/",
     "SECURITY.md",
     "CONTRIBUTING.md"
   ],
-  "scripts": {
-    "dev": "tsx src/cli/index.ts",
-    "start": "tsx src/cli/index.ts",
-    "server": "tsx src/server/index.ts",
-    "build": "tsup",
-    "watch": "tsup --watch",
-    "build:sea": "tsup --config tsup.sea.config.ts",
-    "build:cli-bin": "node scripts/build_cli_binary.mjs",
-    "probes:sea": "node scripts/make_sea_probes.mjs",
-    "fetch:busybox": "node scripts/fetch_busybox_windows.mjs",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "@zqagent/shared": "0.1.0",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.1.11",
     "cli-table3": "^0.6.5",
-    "dotenv": "^16.4.0",
+    "debug": "^4.4.3",
     "markdown-it": "^15.0.2",
     "node-emoji": "^2.2.0",
     "node-fetch": "^2.7.0",
-    "nodemailer": "^10.0.16",
     "openai": "^4.73.0",
-    "socks-proxy-agent": "^9.0.0",
-    "ws": "^8.22.0"
+    "socks": "^2.8.9",
+    "socks-proxy-agent": "^9.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
@@ -191,13 +174,13 @@
     "@types/node-fetch": "^2.6.13",
     "@types/nodemailer": "^8.0.2",
     "@types/ws": "^8.18.2",
-    "@zqagent/shared": "workspace:*",
-    "postject": "^1.0.0-alpha.6",
     "tsup": "^8.5.1",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
     "vitest": "^4.1.10",
-    "zod": "^3.25.76"
+    "werift": "0.25.2",
+    "zod": "^3.25.76",
+    "ws": "^8.22.0"
   },
   "keywords": [
     "ai-agent",
@@ -215,5 +198,11 @@
     "type": "git",
     "url": "https://github.com/zqagent/zqagent.git"
   },
-  "homepage": "https://agent.cd-zq.com/"
-}
+  "homepage": "https://agent.cd-zq.com/",
+  "scripts": {
+    "build": "tsup",
+    "watch": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/bin/zqagent

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import "../dist/cli/index.js";