@ai-zen/agents-sdk 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.9.3] - 2026-09-01
+
+### 🔧 Fixed
+
+- **`createAgent` 不再污染 Agent 定义模板（`definition.messages` 引用隔离）** — 创建 Agent 时对 `definition.messages` 做模板快照（`[...(definition.messages ?? [])]`）而非直接引用。此前把定义数组直接传给 `AgentContext.messages`（mutable 运行时数组），对话期间 `append()` 会反向把完整对话历史写入 `definition.messages`，导致：
+  - 任务迁移 `prune` 分支展开的是被污染的"完整历史"而非模板 → 旧消息既未被物理删除、也未被标记 `omit`，却能看到新注入的断点消息；
+  - `omit` 分支的 `preserveCount` 因 `definition.messages` 与 `agent.messages` 指向同一数组而等于全长 → 历史消息无法被标记 `omit`；
+  - `/new` 基于被污染的模板拷贝，新对话会继承旧历史。
+  - 顺带修复 Agent 定义缺少 `messages` 字段（`undefined`）时创建 Agent 的崩溃问题（`?? []` 兜底）。
+
+### ✅ Tests
+
+- `createAgent.test.ts` 新增：`append` 不污染 `definition.messages`（引用隔离）；Agent 定义缺少 `messages` 字段时正常创建
+
+## [0.9.2] - 2026-08-31
+
+### 🎯 Optimized
+
+- **默认 Agent 提示词重构（`DEFAULT_AGENT_DEFINITION`）** — 精简并统一风格：
+  - 人格设定调整为"幽默风趣、严谨可靠"
+  - 原有 8 条原则压缩为一条核心规则：遇到任何不明确、不确定、有矛盾或可能影响结果的状况，立即停下并直接询问用户，而不是自行脑补、猜测或硬干
+  - 新增"惜字如金"原则：只交代结果与必要说明，执行过程（工具调用、读写、搜索等）用户均已可见，不必再复述，以节省 token
+  - 保留护栏：主动调用工具、如实汇报、并只在你被指定的工作范围内行事
+  - 注入"当前操作系统"信息，动态使用 `process.platform`，适配不同平台
+- **`ViewImageTool` 增加本地 URL 校验** — 新增 `isLocalUrl()`，拒绝 `file://` 协议及指向本机回环地址（`localhost`/`127.0.0.1`/`[::1]`/`0.0.0.0`）的 http(s) URL（API 服务商无法下载访问），在调用早期直接报错；`function.description` 与 `path_or_url` 参数说明同步补充"不支持本地 URL，本地图片请使用文件路径"
+
 ## [0.9.1] - 2026-08-28
 
 ### 🔧 Fixed

package/dist/capabilities/implements/builtin/ViewImageTool.js

@@ -3,6 +3,16 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { SdkCallbackTool } from "../../../runtime/SdkCallbackTool.js";
 const SUPPORTED_EXT = [".jpg", ".jpeg", ".png", ".gif", ".webp"];
+/**
+ * 是否为"本地 URL"——指向本地/回环地址，API 服务商无法下载访问。
+ * 覆盖 file:// 等本地协议，以及指向本机的 http(s) 地址（localhost、127.0.0.1、[::1]、0.0.0.0）。
+ */
+function isLocalUrl(value) {
+    if (/^file:\/\//i.test(value))
+        return true;
+    const m = value.match(/^https?:\/\/([^/?#]+)/i);
+    return !!m && /^(localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0)$/i.test(m[1]);
+}
 /**
  * 查看图片工具 — 让 Agent 主动查看/分析一张图片。**仅对视觉模型可用**：
  * 由 `isAvailable(config, definition)` 声明（从 definition.modelId 解析模型，检查 Model.vision），
@@ -24,13 +34,13 @@ export class ViewImageTool extends SdkCallbackTool {
     }
     function = {
         name: "viewImage",
-        description: "查看一张图片并分析其内容。传入本地图片路径或 http(s) 图片 URL。本地图片会自动上传（Files API）后引用，网络图片直接引用。适合识别图片文字、描述图片内容、分析图表等。",
+        description: "查看一张图片并分析其内容。传入本地图片路径或 http(s) 图片 URL。本地图片会自动上传（Files API）后引用，网络图片直接引用。不支持本地 URL（如 file:// 协议、指向本机 localhost/127.0.0.1 的 http(s) 地址），本地图片请使用文件路径。适合识别图片文字、描述图片内容、分析图表等。",
         parameters: {
             type: "object",
             properties: {
                 path_or_url: {
                     type: "string",
-                    description: "本地图片路径（相对/绝对）或 http(s) 图片 URL。支持的格式：JPEG、PNG、GIF、WebP。",
+                    description: "本地图片路径（相对/绝对）或 http(s) 图片 URL。支持的格式：JPEG、PNG、GIF、WebP。不支持本地 URL（如 file:// 协议、指向本机 localhost/127.0.0.1 的 http(s) 地址），本地图片请使用文件路径。",
                 },
             },
             required: ["path_or_url"],
@@ -47,6 +57,10 @@ export class ViewImageTool extends SdkCallbackTool {
             return "viewImage 需要提供 path_or_url 参数（本地图片路径或 http(s) URL）。";
         }
         const value = target.trim();
+        // 拒绝服务商无法访问的"本地 URL"：file:// 等本地协议，或指向本机回环地址（localhost/127.0.0.1/[::1]/0.0.0.0）的 http(s) 地址
+        if (isLocalUrl(value)) {
+            return "不支持本地 URL（API 服务商无法下载访问）。本地图片请使用文件路径，而不是本地链接。";
+        }
         try {
             // 网络图片：直接返回 image_url 内容块（无需上传）
             if (/^https?:\/\//i.test(value)) {

package/dist/config/constants.js

@@ -10,14 +10,9 @@ export const DEFAULT_AGENT_DEFINITION = {
     name: "默认助手",
     description: "默认的 AI 助手，适用于日常问答和任务执行。",
     messages: [
-        Message.System(`你是一个严谨可靠的智能助手。请用中文回复，说话风格参照官方文件。
+        Message.System(`你是一个幽默风趣、严谨可靠的智能助手，请用中文回复。当前操作系统：${process.platform}。
 
-- 开动脑筋 — 主动思考、灵活运用工具，而不是机械执行
-- 实事求是 — 知之为知之，不知为不知，而不是凭空编造；如果用户意图不明确，应先提问澄清，而不是自行脑补
-- 一切行动听指挥 — 严格遵循用户指令，而不是自作主张
-- 安全第一 — 风险操作先告知确认，而不是盲目执行
-- 能打胜仗 — 写优秀的代码，而不是只限于能用的代码
-- 有矛盾就问 — 如果用户指令中存在自相矛盾之处，应指出矛盾并请求澄清，而不是自行取舍`),
+惜字如金：只交代结果和必要说明，执行过程（工具调用、读写、搜索等）用户均已可见，不必再复述。遇到任何不明确、不确定、有矛盾或可能影响结果的状况，立即停下并直接询问用户，而不是自行脑补、猜测或硬干。除此之外，主动调用工具、如实汇报，并只在你被指定的工作范围内行事。`),
     ],
     permissions: {
         tools: { allow: ["*"] },

package/dist/runtime/createAgent.js

@@ -32,7 +32,12 @@ export async function createAgent(provider, agentId) {
         client,
         model,
         modelConfig,
-        messages: definition.messages,
+        // 在 createAgent 层做模板快照（拷贝），隔离 definition.messages 的引用。
+        // AgentContext.messages 是 mutable 运行时数组，若直接把 definition.messages
+        // 传入，对话期间 append() 会反向污染 Agent 定义模板——definition.messages
+        // 被塞入完整历史后，迁移 prune/omit 失效、/new 继承旧历史。
+        // 快照后，运行时改动只作用于会话副本，模板保持纯净。
+        messages: [...(definition.messages ?? [])],
         tools,
     });
     return agent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,10 +16,10 @@
   "author": "LZQCN",
   "license": "MIT",
   "dependencies": {
+    "@ai-zen/agents-core": "^4.1.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dayjs": "^1.11.21",
-    "openai": "^7.5.0",
-    "@ai-zen/agents-core": "^4.1.0"
+    "openai": "^7.5.0"
   },
   "devDependencies": {
     "@types/node": "^24.12.2",