@ai-zen/agents-sdk 1.0.0-alpha.12 → 1.0.0-alpha.14

package/dist/types/index.d.ts

@@ -25,6 +25,35 @@ export interface EndpointCapabilities {
      */
     filesApi?: boolean;
 }
+/**
+ * 单个档位的请求参数补丁 —— 原样合并进模型请求参数。
+ *
+ * 各家协议差异全部关在补丁里，SDK 不解释、不硬编码任何键名：
+ *   OpenAI   → `{ reasoning_effort: "high" }`（没有 `thinking` 参数）
+ *   DeepSeek → `{ thinking: { type: "enabled" }, reasoning_effort: "high" }`
+ *   关闭     → `{ reasoning_effort: "none" }` 或 `{ thinking: { type: "disabled" } }`
+ */
+export type ReasoningPatch = Record<string, unknown>;
+/**
+ * 一个具名思考策略：档位名 → 参数补丁。
+ *
+ * `levels` 的键集合**就是**该策略的全部可选档位 —— 没有单独的「能否关闭思考」字段：
+ * 表里有 `off` 键就能关，没有就不能（如智谱 GLM-5.3 系，官方原文「其余输入将报错」）。
+ */
+export interface ReasoningPreset {
+    /** 用户改过 → SDK 初始化不再覆盖该策略（与 `Model.custom` 同构） */
+    custom?: boolean;
+    /** 档位名 → 参数补丁 */
+    levels: Record<string, ReasoningPatch>;
+}
+/**
+ * 思考策略表 —— `<basePath>/reasoning-presets.json` 的结构，出厂内容见
+ * `config/reasoning-presets.ts`。
+ *
+ * 键是策略名，由 `Model.reasoningPreset` 引用。**策略名一旦发布即视为稳定标识**
+ * （用户配置文件里写着它），改名等同破坏性变更。
+ */
+export type ReasoningPresets = Record<string, ReasoningPreset>;
 /** API 端点 */
 export interface Endpoint {
     id: string;
@@ -34,6 +63,24 @@ export interface Endpoint {
     description?: string;
     capabilities?: EndpointCapabilities;
 }
+/**
+ * 上下文用量阈值 —— 与模型的真实窗口无关，只描述「用量到了这条线该怎么办」。
+ *
+ * 两个阈值语义不同，消费方也不同：
+ *   - `handoff`：软线。`AutoMigratePlugin` 在响应返回后拿 `usage.prompt_tokens` 比它，
+ *     超过即触发任务交接（交接本身还要再发 1~2 次请求，所以这条线必须留足余量）。
+ *   - `guard`：硬线。`ContextGuardPlugin` 在**每次请求前**比它，超过即抛
+ *     `ContextOverflowError` 中断本轮——这是最后一道保护，宁可报错也不要发出必然失败的请求。
+ *
+ * 建议 `guard ≈ handoff × 1.5`，给交接留出缓冲；两者都是绝对值，配置里写多少就是多少，
+ * 不做任何倍数换算（阈值就该是能直接读懂的数字）。
+ */
+export interface TokenThresholds {
+    /** 交接阈值（软线）：prompt_tokens 超过它 → 触发任务交接 */
+    handoff: number;
+    /** 强行阻断阈值（硬线）：请求前用量超过它 → 中断本轮并报错 */
+    guard: number;
+}
 /** 模型配置，绑定一个 Endpoint */
 export interface Model {
     id: string;
@@ -41,15 +88,21 @@ export interface Model {
     endpointId: string;
     modelName?: string;
     /**
-     * 任务迁移（交接）触发阈值 —— **不是**模型的真实上下文窗口。
+     * 上下文用量阈值（交接软线 + 阻断硬线）。**不是**模型的真实上下文窗口。
      *
-     * AutoMigratePlugin 不估算、不学习：只在 API 响应返回后，用 `usage.prompt_tokens`
-     * 与该值比较，超过即触发交接迁移。建议取模型真实窗口的约 25%，为 response 留出空间。
+     * 历史字段 `maxContextTokens` / `maxContextChars` 已由 `config/migrate.ts`
+     * 迁移成这个结构体并删除。
      */
-    maxContextTokens: number;
-    /** 旧版字符数阈值（兼容迁移） */
-    maxContextChars?: number;
+    tokenThresholds: TokenThresholds;
     defaultParams?: Record<string, unknown>;
+    /**
+     * 思考策略名，引用 `reasoning-presets.json` 里的键。缺省视为不可调档。
+     *
+     * 为什么只存名字不存整张表：档位细节属于**厂商协议知识**，跟 SDK 版本一起演进；
+     * 配置只需要记录「这个型号套用哪套协议」。名字指向同目录下的策略表文件，
+     * 用户看得见、改得动，不必等 SDK 发版。
+     */
+    reasoningPreset?: string;
     /** 是否支持图片输入（视觉模型）。看图工具（view_image）仅对视觉模型启用；generate_image 是否返回图片内容块也据此判断 */
     vision?: boolean;
     description?: string;
@@ -69,6 +122,16 @@ export interface AgentDefinition {
     description?: string;
     messages: AgentNS.Message[];
     modelId?: string;
+    /**
+     * 该 Agent 的思考档位（可选），必须是该模型策略表 `levels` 里的键。
+     *
+     * 有了它，同一个模型可以给不同 Agent 配不同强度（编程 Agent `max`、闲聊 Agent `low`），
+     * 而模型本身的默认参数保持不变。未声明时沿用模型默认。
+     *
+     * 类型是 `string` 而非联合类型：档位名由策略表定义，各家本就不同名，
+     * 用一个全局枚举假装统一只会把厂商差异藏进字段里。合法性在运行时按表校验。
+     */
+    reasoningEffort?: string;
     permissions?: AgentPermissions;
     function?: AgentNS.FunctionDefine;
     createdAt: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "1.0.0-alpha.12",
+  "version": "1.0.0-alpha.14",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",