@ai-zen/agents-sdk 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [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
+
+- **SDK-produced messages now always carry an `id`, aligned with core 4.1.0's required `Message.id`** — `TaskMigrationService.createPostMessages()` returns a `Message.User`, and the default agent / sub-agent definitions (`DEFAULT_AGENT_DEFINITION` / `DEFAULT_SUBAGENT_DEFINITION`) build their messages via `Message.System` / `Message.User`. This removes the last places where a bare object literal `{ role, content }` was assigned to `AgentNS.Message`, which would now fail to compile under core 4.1.0 (where `Message.id` is non-optional). Consumers no longer need to patch a missing `id` on SDK-generated messages (e.g. a desktop-side `ensureId` bridge)
+- **No breaking change to public API** — only internal message construction was switched to the `Message` factory methods; exported types and method signatures are unchanged
+
+### ✅ Tests
+
+- SDK suite re-checked green against core 4.1.0 (`Message.id` required)
+
 ## [0.9.0] - 2026-08-28
 
 ### 🎯 Optimized

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

@@ -1,4 +1,4 @@
-import { AgentNS } from "@ai-zen/agents-core";
+import { Message } from "@ai-zen/agents-core";
 // ---------------------------------------------------------------------------
 // 默认 Agent
 // ---------------------------------------------------------------------------
@@ -10,17 +10,9 @@ export const DEFAULT_AGENT_DEFINITION = {
     name: "默认助手",
     description: "默认的 AI 助手，适用于日常问答和任务执行。",
     messages: [
-        {
-            role: AgentNS.Role.System,
-            content: `你是一个严谨可靠的智能助手。请用中文回复，说话风格参照官方文件。
+        Message.System(`你是一个幽默风趣、严谨可靠的智能助手，请用中文回复。当前操作系统：${process.platform}。
 
-- 开动脑筋 — 主动思考、灵活运用工具，而不是机械执行
-- 实事求是 — 知之为知之，不知为不知，而不是凭空编造；如果用户意图不明确，应先提问澄清，而不是自行脑补
-- 一切行动听指挥 — 严格遵循用户指令，而不是自作主张
-- 安全第一 — 风险操作先告知确认，而不是盲目执行
-- 能打胜仗 — 写优秀的代码，而不是只限于能用的代码
-- 有矛盾就问 — 如果用户指令中存在自相矛盾之处，应指出矛盾并请求澄清，而不是自行取舍`,
-        },
+惜字如金：只交代结果和必要说明，执行过程（工具调用、读写、搜索等）用户均已可见，不必再复述。遇到任何不明确、不确定、有矛盾或可能影响结果的状况，立即停下并直接询问用户，而不是自行脑补、猜测或硬干。除此之外，主动调用工具、如实汇报，并只在你被指定的工作范围内行事。`),
     ],
     permissions: {
         tools: { allow: ["*"] },
@@ -40,11 +32,8 @@ export const DEFAULT_SUBAGENT_DEFINITION = {
     name: "通用助手",
     description: "一个通用的子 Agent，擅长独立完成各类任务。",
     messages: [
-        {
-            role: AgentNS.Role.System,
-            content: "你是一个通用助手子 Agent，被父 Agent 委派来独立完成具体任务。请根据给定的任务描述，主动调用你的工具（文件读写、执行命令、搜索等）来分析和完成任务。完成任务后直接返回结果，不需要解释你的思考过程。\n\n⚠️ 强制性要求：\n1. 如果任务描述中存在任何不明确、模糊或缺失的信息（包括但不限于具体目标、文件路径、约束条件、预期产出等），你必须直接拒绝执行，并明确列出哪些信息不明确或缺失，要求父 Agent 提供更完整的任务上下文。不得自行假设、猜测或脑补任何信息。\n2. 如果任务描述中存在自相矛盾的信息（如相互冲突的要求、不一致的文件路径、矛盾的约束条件等），你必须及时指出矛盾之处，并要求父 Agent 澄清后再执行。",
-        },
-        { role: AgentNS.Role.User, content: "{{task}}" },
+        Message.System("你是一个通用助手子 Agent，被父 Agent 委派来独立完成具体任务。请根据给定的任务描述，主动调用你的工具（文件读写、执行命令、搜索等）来分析和完成任务。完成任务后直接返回结果，不需要解释你的思考过程。\n\n⚠️ 强制性要求：\n1. 如果任务描述中存在任何不明确、模糊或缺失的信息（包括但不限于具体目标、文件路径、约束条件、预期产出等），你必须直接拒绝执行，并明确列出哪些信息不明确或缺失，要求父 Agent 提供更完整的任务上下文。不得自行假设、猜测或脑补任何信息。\n2. 如果任务描述中存在自相矛盾的信息（如相互冲突的要求、不一致的文件路径、矛盾的约束条件等），你必须及时指出矛盾之处，并要求父 Agent 澄清后再执行。"),
+        Message.User("{{task}}"),
     ],
     permissions: {
         tools: { allow: ["*"] },

package/dist/runtime/TaskMigrationService.js

@@ -1,4 +1,4 @@
-import { AgentNS } from "@ai-zen/agents-core";
+import { Message } from "@ai-zen/agents-core";
 import { getLogger } from "../shared/logger.js";
 /**
  * 任务迁移服务。
@@ -83,7 +83,7 @@ export class TaskMigrationService {
             "",
             "请确认你已理解以上内容，然后询问用户接下来需要什么帮助。",
         ].join("\n");
-        return [{ role: AgentNS.Role.User, content }];
+        return [Message.User(content)];
     }
     /**
      * 序列化消息为 `[role]: content` 文本，供模型理解完整对话历史。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,7 +19,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dayjs": "^1.11.21",
     "openai": "^7.5.0",
-    "@ai-zen/agents-core": "^4.0.0"
+    "@ai-zen/agents-core": "^4.1.0"
   },
   "devDependencies": {
     "@types/node": "^24.12.2",