@ai-zen/agents-sdk 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [0.3.4] - 2026-07-27
+
+### 🎯 优化
+
+- **`AutoMigratePlugin` 钩子重命名** — `onHandoff` → `onMigrated`，语义更清晰：迁移前用 `onBeforeMigrate`（此时 `agent.messages` 仍是完整旧历史），迁移完成后用 `onMigrated`（交接文档已注入）
+- **`conversation-runner.ts` 保存逻辑修正** — 将保存旧对话从 `onMigrated`（原 `onHandoff`）移至 `onBeforeMigrate`，确保保存的是完整的旧对话历史，而非迁移后的新消息
+
+## [0.3.3] - 2026-07-27
+
+### 🎯 优化
+
+- **默认 SubAgent System Prompt 新增两条强制性要求**：
+  1. 信息不明确/模糊/缺失时拒绝执行，要求补充
+  2. 存在自相矛盾信息时指出矛盾，要求澄清
+- **默认 Agent System Prompt 新增原则**："有矛盾就问 — 如果用户指令中存在自相矛盾之处，应指出矛盾并请求澄清，而不是自行取舍"
+- **默认 SubAgent `function.description` 和 `task` 参数描述**同步更新，强调不明确信息将导致拒绝执行
+
 ## [0.3.2] - 2026-07-26
 
 ### 💥 破坏性变更

package/dist/config/constants.js

@@ -15,10 +15,11 @@ export const DEFAULT_AGENT_DEFINITION = {
             content: `你是一个严谨可靠的智能助手。请用中文回复，说话风格参照官方文件。
 
 - 开动脑筋 — 主动思考、灵活运用工具，而不是机械执行
-- 实事求是 — 知之为知之，不知为不知，而不是凭空编造
+- 实事求是 — 知之为知之，不知为不知，而不是凭空编造；如果用户意图不明确，应先提问澄清，而不是自行脑补
 - 一切行动听指挥 — 严格遵循用户指令，而不是自作主张
 - 安全第一 — 风险操作先告知确认，而不是盲目执行
-- 能打胜仗 — 写优秀的代码，而不是只限于能用的代码`,
+- 能打胜仗 — 写优秀的代码，而不是只限于能用的代码
+- 有矛盾就问 — 如果用户指令中存在自相矛盾之处，应指出矛盾并请求澄清，而不是自行取舍`,
         },
     ],
     permissions: {
@@ -41,7 +42,7 @@ export const DEFAULT_SUBAGENT_DEFINITION = {
     messages: [
         {
             role: AgentNS.Role.System,
-            content: "你是一个通用助手子 Agent，被父 Agent 委派来独立完成具体任务。请根据给定的任务描述，主动调用你的工具（文件读写、执行命令、搜索等）来分析和完成任务。完成任务后直接返回结果，不需要解释你的思考过程。",
+            content: "你是一个通用助手子 Agent，被父 Agent 委派来独立完成具体任务。请根据给定的任务描述，主动调用你的工具（文件读写、执行命令、搜索等）来分析和完成任务。完成任务后直接返回结果，不需要解释你的思考过程。\n\n⚠️ 强制性要求：\n1. 如果任务描述中存在任何不明确、模糊或缺失的信息（包括但不限于具体目标、文件路径、约束条件、预期产出等），你必须直接拒绝执行，并明确列出哪些信息不明确或缺失，要求父 Agent 提供更完整的任务上下文。不得自行假设、猜测或脑补任何信息。\n2. 如果任务描述中存在自相矛盾的信息（如相互冲突的要求、不一致的文件路径、矛盾的约束条件等），你必须及时指出矛盾之处，并要求父 Agent 澄清后再执行。",
         },
         { role: AgentNS.Role.User, content: "{{task}}" },
     ],
@@ -53,11 +54,11 @@ export const DEFAULT_SUBAGENT_DEFINITION = {
     },
     function: {
         name: "sub_agent_default",
-        description: "通用子 Agent，可独立完成各类任务。委派任务时必须提供完整的任务上下文，包括所有必要的背景信息、文件路径、具体要求和约束条件，确保子 Agent 无需追问即可独立执行。",
+        description: "通用子 Agent，可独立完成各类任务。⚠️ 委派任务时必须提供完整的任务上下文，包括所有必要的背景信息、文件路径、具体要求和约束条件，任何信息不明确将导致子 Agent 拒绝执行并要求补充信息。",
         parameters: {
             type: "object",
             properties: {
-                task: { type: "string", description: "完整的任务描述，必须包含所有必要的背景、目标、约束条件和上下文信息" },
+                task: { type: "string", description: "完整的任务描述，必须包含所有必要的背景、目标、约束条件和上下文信息。任何不明确的信息将导致子 Agent 拒绝执行。" },
             },
             required: ["task"],
             additionalProperties: false,

package/dist/plugin/AutoMigratePlugin.d.ts

@@ -3,10 +3,10 @@ import { SdkAgent } from "../runtime/SdkAgent.js";
 export interface AutoMigrateOptions {
     maxTokens: number;
     migrationAgent: SdkAgent;
-    /** 迁移开始前触发（promptTokens 刚超限时），可在此向用户展示迁移提示 */
+    /** 迁移开始前触发（promptTokens 刚超限时），此时 agent.messages 还是完整旧历史。适用于保存旧对话或向用户展示迁移提示。 */
     onBeforeMigrate?: (promptTokens: number, maxTokens: number, agent: SdkAgent) => void;
-    /** 迁移完成后触发（交接文档已注入 agent.messages），可在此保存对话等 */
-    onHandoff?: (handoffDoc: string, agent: SdkAgent) => void;
+    /** 迁移完成后触发，此时交接文档已注入 agent.messages。适用于 UI 更新等后处理。 */
+    onMigrated?: (handoffDoc: string, agent: SdkAgent) => void;
 }
 /**
  * 自动迁移插件。
@@ -18,7 +18,7 @@ export interface AutoMigrateOptions {
  * agent.use(new AutoMigratePlugin({
  *   maxTokens: 250_000,
  *   migrationAgent: anotherAgent,
- *   onHandoff: (doc, agent) => { ... },
+ *   onMigrated: (doc, agent) => { ... },
  * }));
  * ```
  */

package/dist/plugin/AutoMigratePlugin.js

@@ -12,7 +12,7 @@ const log = createLogger();
  * agent.use(new AutoMigratePlugin({
  *   maxTokens: 250_000,
  *   migrationAgent: anotherAgent,
- *   onHandoff: (doc, agent) => { ... },
+ *   onMigrated: (doc, agent) => { ... },
  * }));
  * ```
  */
@@ -23,7 +23,7 @@ export class AutoMigratePlugin {
     }
     async onAfterSend(ctx) {
         const { agent } = ctx;
-        const { maxTokens, migrationAgent, onBeforeMigrate, onHandoff } = this.options;
+        const { maxTokens, migrationAgent, onBeforeMigrate, onMigrated } = this.options;
         const promptTokens = agent.lastUsage?.prompt_tokens;
         if (promptTokens == null)
             return;
@@ -47,12 +47,12 @@ export class AutoMigratePlugin {
             // 仅替换消息列表，不重建 agent，保留所有引用和插件绑定
             agent.messages.length = 0;
             agent.messages.push(...agent.definition.messages, ...TaskMigrationService.createPostMessages(handoffDoc));
-            if (onHandoff) {
+            if (onMigrated) {
                 try {
-                    await onHandoff(handoffDoc, agent);
+                    await onMigrated(handoffDoc, agent);
                 }
                 catch (err) {
-                    log.error(`[autoMigrate] onHandoff 回调失败: ${err?.message ?? err}`);
+                    log.error(`[autoMigrate] onMigrated 回调失败: ${err?.message ?? err}`);
                 }
             }
         }

package/package.json

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