@ai-zen/agents-sdk 0.12.0 → 1.0.0-alpha.1

package/CHANGELOG.md

@@ -1,94 +1,161 @@
 # Changelog
 
+## [1.0.0-alpha.1] - 2026-10-03
+
+### 💥 Breaking Changes
+
+- **Factory model catalog refreshed (verified against vendor sources on 2026-10-03)** — every stale or retired model ID in `DEFAULT_APP_CONFIG.models` is replaced:
+  - **OpenAI**: `gpt-5.5` → `gpt-6-astra` / `gpt-6.1-sol` / `gpt-6-luna`
+  - **Zhipu**: `glm-5.1` / `glm-5v-turbo` → `glm-5.3` / `glm-5.3-flash` / `glm-5.3-flashx`
+  - **DeepSeek**: `deepseek-v4-pro` / `deepseek-v4-flash` / `deepseek-v4-flash-vision-exp` → `deepseek-flash`. The two V4-Flash variants were retired by the vendor, and V4-Pro requests are routed to V4.1-Flash.
+  - Defaults: `defaultModel` / `defaultMigrationModel` move from `deepseek-v4-flash` to `deepseek-flash`.
+- **`Model.maxContextTokens` semantics clarified — it is the task-migration (handoff) trigger threshold, not the model context window** — `AutoMigratePlugin` does not estimate or learn: it only compares `usage.prompt_tokens` from the API response against this value. The previous comment read "上下文窗口 token 上限" ("context window token limit"), which is why values had been filled in with raw window sizes. Values are now ~25% of the real window (250K for ≥1M-window models), except `glm-4.7-flash` (200K window) which uses 100K.
+
+### 🚀 New Features
+
+- **Managed model catalog sync (`custom` opt-out)** — `ConfigManager.ensureDefaultConfig()` now reconciles the factory catalog on every `bootstrap()`. Entries in `models` / `imageModels` that do **not** carry `custom: true` are dropped and replaced by the latest `DEFAULT_APP_CONFIG` definitions; entries marked `custom: true` are treated as user-owned and kept verbatim (user wins on id collision, no duplicates). A dangling `defaultModel` / `defaultImageModel` / `defaultMigrationModel` falls back to the factory default, so no reference is ever left pointing at a removed model. `endpoints` are never managed. The sync is idempotent — it only writes when something actually changed. Implemented in `ConfigManager.syncManagedModels`.
+- **`Model` / `ImageModel` gained an optional `custom?: boolean` field** — marks an entry as user-owned so the factory sync leaves it untouched.
+
+### ✅ Tests
+
+- Added coverage for the model catalog sync: stale non-custom entries replaced, `custom: true` entries preserved, user version winning on id collision without duplication, image models reconciled, dangling default IDs falling back, and idempotency across repeated calls.
+- E2E model IDs updated to the current vendor names (`deepseek-flash`).
+
+### 📄 Docs
+
+- Current-version references in `docs/zh` and `docs/en` updated to `1.0.0-alpha.1`.
+- `DEFAULT_APP_CONFIG` row in `sdk-design-v0.md` updated to the new model catalog.
+
+## [1.0.0-alpha.0] - 2026-09-30
+
+### 💥 Breaking Changes
+
+- **`Provider` renamed to `Scope` (fully removed, no compatibility alias)** — `runtime/Provider.ts` is migrated to `scope/Scope.ts`. All `provider` fields / params / variables are renamed to `scope`: `SdkAgent.provider` → `SdkAgent.scope`, `createAgent(scope, …)`, `createModel(scope, …)`, `createSubAgentTool(def, scope)`. `FilterOutput` / `ExcludeOptions` / `FilterOptions` move from `runtime/Provider` to `scope/Scope` accordingly.
+- **Capability sources "delegated" to `ScopePlugin` (new capability-plugin contract)** — `Scope` degrades to a pure orchestration container: it only holds `config` / `cwd` / `env` / `agentsDir` and orchestrates the three-stage pipeline (discover → filter → instantiate). The four capability sources previously hard-coded in `Provider.refresh/filter/instantiate` are split into **5 standard plugins**, each self-containing its discovery state and instantiation logic:
+  - `BuiltinToolsScopePlugin` (`id: "builtin"`) — 20 built-in tool classes
+  - `UserToolsScopePlugin` (`id: "user-tools"`) — `tools/*.js`
+  - `SkillsScopePlugin` (`id: "skills"`) — `SKILL.md` + `load_skill` / `call_skill_sub_agent`
+  - `McpScopePlugin` (`id: "mcp"`) — `mcp.json` + a private `McpConnectionManager` + `load_mcp` / `call_mcp_tool` / `read_mcp_resource`
+  - `SubAgentsScopePlugin` (`id: "subagents"`) — `sub-agents/*.json`
+- **`Scope` no longer accepts capability-source paths, nor exposes an aggregated candidate set** — `new Provider({ config, cwd, agentsDir, skillsPaths, toolsPaths, subAgentsPaths, mcpPaths })` → `new Scope({ config, cwd, agentsDir })`. Paths are now held by the plugins (pass absolute paths, or pass relative ones that each plugin joins against `scope.cwd` during `discover()`). `Scope` no longer has `builtinTools` / `userTools` / `subagents` / `skills` / `mcps` / `mcpManager` fields.
+- **`Provider.create()` removed** — replaced by explicit assembly: `new Scope({...}).use(...plugins)` → `await scope.init()`. (The static `create` shortcut is removed for now, to be revisited later.)
+- **Plugins must be assembled explicitly** — `Scope` registers no default plugins itself; without assembly it has "empty capabilities". The convenience factory `allInOne({ skillsPaths, toolsPaths, subAgentsPaths, mcpPaths })` always returns the 5 standard plugins for one-shot assembly.
+
+### 🚀 New Features
+
+- **New `ScopePlugin` extension point** — contract `{ id; discover?; candidates; instantiate; dispose? }`, an extension point independent of core's `AgentPlugin` (Agent runtime hooks):
+  - `discover?(scope, { silent })` — stage 1 · discovery (may be async, re-scans internally)
+  - `candidates(scope, definition)` — stage 2 · contribute four-dimension candidate names (including availability checks, e.g. a synchronous `isAvailable`)
+  - `instantiate(scope, filtered)` — stage 3 · produce `Tool[]` from the allowed names after filtering
+  - `dispose?()` — release (e.g. disconnect MCP)
+- **New `Scope` API**: `use(...plugins)` (chainable, variadic), `getPluginById(id)` (for external code / plugins to query plugin state), `plugins` (read-only view), `init()` / `refresh({ silent })` / `filter()` / `instantiate()` / `buildTools()` / `dispose()`. Calling `use()` after `init()` throws.
+- **`dispose()` symmetric with `init()`** — calls each plugin's `dispose()` in reverse order; `McpScopePlugin.dispose()` → `mcpManager.disconnectAll()`, so MCP long-lived connections no longer rely solely on an idle timeout.
+- **`allInOne()` convenience factory** — always returns the 5 standard plugins; order is priority (`builtin → user-tools → skills → mcp → subagents`; on dedupe, later registrations override earlier ones, so user tools can still override same-named built-in tools).
+- **`McpScopePlugin.hasConfig()`** — lets `UnknownToolHintPlugin` determine "whether MCP config exists" (replacing a direct read of `provider.mcpPaths`).
+
+### 🛠 Optimized
+
+- **`UnknownToolHintPlugin` constructor now takes `{ scope }`** — it learns the MCP config via `scope.getPluginById(McpScopePlugin.ID)?.hasConfig()`; behavior semantics are unchanged (config present but `call_mcp_tool` denied → hint about permission; available → guide usage; no config → just hint that it doesn't exist).
+- **`AutoRefreshToolsPlugin`** — now goes through `agent.scope.refresh()` / `agent.scope.buildTools()`.
+- **Progressive-disclosure (lazy-loading) design unchanged** — the schema of `load_skill` / `call_skill_sub_agent` / `load_mcp` / `call_mcp_tool` / `read_mcp_resource`, enum disclosure (`createDisclosureParam`), the `include_manifest` switch, `touch` renewal, and `call_skill_sub_agent` reusing the parent tool set while excluding itself to prevent recursion — all **preserved verbatim**, merely moved from `Provider.instantiate()` to the `instantiate()` of `SkillsScopePlugin` / `McpScopePlugin`. Permission semantics are unchanged (denying `load_*` on the `tools` dimension cuts off the disclosure channel; denied skills/mcps never enter an enum).
+
+### 📄 Docs
+
+- Added [`docs/sdk-design-v1.md`](docs/sdk-design-v1.md) (the v1 design source of truth, covering the Scope / ScopePlugin architecture, the five plugins, and a migration guide); the old doc is renamed to [`docs/sdk-design-v0.md`](docs/sdk-design-v0.md).
+
+### ✅ Tests
+
+- All tests migrated to Scope + ScopePlugin: `capabilities.test.ts` rewritten to be organized by plugin dimension (built-in / SubAgent / Skill / MCP / user tools + lifecycle), with `createAgent` / `createModel` / `SdkAgent` / `UnknownToolHint` / `AutoRefreshTools` / `subAgentTools` / `integration` / `e2e-*` updated accordingly. SDK suite: **498 passed / 2 skipped** (including chat / view-image e2e against the real DeepSeek API).
+
 ## [0.12.0] - 2026-09-29
 
 ### 🚀 New Features
 
-- **统一工具输出保护（`maxToolOutput`）** — `AppConfig` 新增 `maxToolOutput?: number`（字符数，缺省 32768；出厂 `DEFAULT_APP_CONFIG` 已写入该值）。新增输出保护骨架 `guardOutput()`（`capabilities/implements/builtin/outputGuard.ts`）：工具以三个回调自陈策略——`isOverLimit(content)`（工具自读 config 判定，含合计口径）、`dump(dir, content)`（落盘文件清单，缺省即"只警告不落盘"）、`buildWarning(ctx)`（返回体，含预览与统计）；骨架只负责"判定 → 未超限原样返回 / 超限时落盘"两件事。落盘目录为 `<os.tmpdir()>/ai-zen/tool-output/<工具名>-<时间戳>-<随机串>/`，每次调用独立互不覆盖，不做自清理（依赖系统对临时目录的策略）。已接入：
-  - **`exec`** — `stdout + stderr` 合计超限即分文件落盘 `stdout.log` / `stderr.log`，返回警告 + 各流头尾预览（各 1000 字符）+ 字符数/行数统计，原 `exitCode` / `killed` / `terminated` 字段保留；
-  - **`findText`** — 落盘 `result.json`，返回警告 + 头部预览（1000 字符）；既有 `maxMatches` / `maxFileSize` / `maxLineLength` 参数保持不变；
-  - **`glob` / `ls`** — 落盘 `result.json`，返回警告 + 头部预览，并提示缩小范围的方式（更精确的 `pattern` / `exclude`，或改用 `glob`）；
-  - **`readFile`** — 超限**不落盘**，仅返回警告并提示使用 `range` 分批读取。
-  - 另导出 `headPreview()` / `headTailPreview()` 供各工具按需组织预览（预览文本由工具自行生成）。
-- **`readFile` 新增 `range` 参数（可选）** — `range: [起始行, 起始列, 结束行, 结束列]`，行列均 0-based、`-1` 表示末位；如 `[0, 0, 100, -1]` 表示"第 0 行第 0 列读到第 100 行最后一列"。300KB 读取阈值保持不变——读取阈值（能否读）与输出阈值（是否落盘）互相独立。
-- **新增 `inspectFile` 工具（`InspectFileTool`）** — 勘察文件结构概况，不做内容读取，与 `readFile` 的 `range` 配套（先看结构，再决定读取范围）。返回 `path` / `bytes` / `lines` / `chars` / `maxCol` / `lineIndexOfMaxCol`（0-based）/ `avgCol` / `lineEnding`（`LF` / `CRLF` / `mixed`）；可选 `withColCountMap: true` 返回"行索引 → 列数"对象映射。流式扫描，**不受 300KB 读取阈值限制**；列数按字符数计、不含行尾换行符；明细超限时不落盘，仅返回概况 + 提示"文件规模超出可处理范围"。内置工具类由 19 个增至 20 个。
-- **`batchEdit` 输出精简** — 成功项不再回显原文与新文，全部成功时返回 `{ result: "success", replacedCount }`；存在未匹配项时返回 `{ result: "partial", replacedCount, failed: [{ oldText, newText, reason }] }`，仅回显有问题的原文与新文，避免大段文本回显撑大输出。
-- **`AgentDefinition` 新增 `custom` 字段** — 为 `true` 时 SDK 初始化不触碰该 Agent 的内置内容（如默认提示词）。出厂 `DEFAULT_AGENT_DEFINITION` 携带 `custom: false`：`ensureDefaultAgent()` 在 `custom !== true` 时**仅同步出厂提示词**（`name` / `permissions` / `modelId` 等用户改动保留），提示词一致时不写盘、不动 `updatedAt`（比较时忽略随机生成的 message `id`，避免时间戳漂移）。
-- **默认 Agent 提示词调整** — 去掉原有法则，改为两条：① 需要用户决策时，一次只问一个问题；② 当前对话基于 Node.js 驱动，可编写 Node.js 脚本执行复杂任务并通过 `exec` 工具运行。
+- **Unified tool output protection (`maxToolOutput`)** — `AppConfig` gains `maxToolOutput?: number` (in characters, default 32768; the factory `DEFAULT_APP_CONFIG` already writes this value). New output-protection skeleton `guardOutput()` (`capabilities/implements/builtin/outputGuard.ts`): tools declare their policy via three callbacks — `isOverLimit(content)` (the tool reads config itself to decide, including a combined measure), `dump(dir, content)` (the dumped-file list; the default is "warn only, no dump"), `buildWarning(ctx)` (the return body, with preview and stats); the skeleton only does two things: "decide → return as-is when under the limit / dump when over". The dump directory is `<os.tmpdir()>/ai-zen/tool-output/<tool>-<timestamp>-<random>/`, isolated and non-overwriting per call, with no self-cleanup (relying on the OS's policy for temp directories). Wired into:
+  - **`exec`** — when `stdout + stderr` combined exceed the limit, they are dumped to separate files `stdout.log` / `stderr.log`, returning a warning + head/tail preview per stream (1000 chars each) + char/line counts; the original `exitCode` / `killed` / `terminated` fields are preserved;
+  - **`findText`** — dumps `result.json`, returns a warning + head preview (1000 chars); the existing `maxMatches` / `maxFileSize` / `maxLineLength` params are unchanged;
+  - **`glob` / `ls`** — dumps `result.json`, returns a warning + head preview, and hints how to narrow the scope (a more precise `pattern` / `exclude`, or switching to `glob`);
+  - **`readFile`** — does **not** dump on overflow, only returns a warning and suggests batched reads via `range`.
+  - Also exports `headPreview()` / `headTailPreview()` for tools to build previews as needed (the preview text is generated by each tool itself).
+- **`readFile` gains a `range` param (optional)** — `range: [startLine, startCol, endLine, endCol]`, all 0-based, with `-1` meaning the last index; e.g. `[0, 0, 100, -1]` means "read from line 0 col 0 through line 100's last column". The 300KB read threshold is unchanged — the read threshold (whether a file can be read) and the output threshold (whether to dump) are independent.
+- **New `inspectFile` tool (`InspectFileTool`)** — surveys a file's structural overview without reading content, complementing `readFile`'s `range` (look at the structure first, then decide the read range). Returns `path` / `bytes` / `lines` / `chars` / `maxCol` / `lineIndexOfMaxCol` (0-based) / `avgCol` / `lineEnding` (`LF` / `CRLF` / `mixed`); an optional `withColCountMap: true` returns a "line index → column count" object map. Streamed scan, **not limited by the 300KB read threshold**; columns are counted as characters, excluding the line-ending newline; on overflow the detail is not dumped, only the overview plus a hint that "the file scale exceeds the processable range". Built-in tool classes increased from 19 to 20.
+- **`batchEdit` output slimmed down** — successful items no longer echo the old and new text; when all succeed it returns `{ result: "success", replacedCount }`; when there are unmatched items it returns `{ result: "partial", replacedCount, failed: [{ oldText, newText, reason }] }`, echoing only the problematic old and new text, so large blocks aren't echoed back to inflate the output.
+- **`AgentDefinition` gains a `custom` field** — when `true`, SDK init does not touch the Agent's built-in content (e.g. the default prompt). The factory `DEFAULT_AGENT_DEFINITION` carries `custom: false`: `ensureDefaultAgent()` **syncs only the factory prompt** when `custom !== true` (user changes to `name` / `permissions` / `modelId` etc. are preserved), and when the prompt is identical it writes nothing and leaves `updatedAt` untouched (randomly generated message `id`s are ignored in the comparison to avoid timestamp drift).
+- **Default Agent prompt adjusted** — the original rules are replaced by two: ① when a user decision is needed, ask only one question at a time; ② the current conversation is Node.js-driven, so you can write Node.js scripts to perform complex tasks and run them via the `exec` tool.
 
 ### ✅ Tests
 
-- 新增 `outputGuard.test.ts`（骨架：未超限原样返回 / 超限落盘并返回警告 / 无 `dump` 时只警告 / 目录隔离 / `headPreview` 与 `headTailPreview`）、`InspectFileTool.test.ts`（概况字段、`colCountMap` 映射、CRLF 与 mixed、末行无换行、空文件、300KB 以上文件、明细超限降级、目录与不存在路径）及各工具的超限/范围读取用例；`ConfigManager.bootstrap.test.ts` 覆盖 `custom: true` 跳过、仅同步提示词、一致时不写盘。SDK 全量 **499 passed / 6 skipped**
+- Added `outputGuard.test.ts` (skeleton: return as-is under the limit / dump + warning over the limit / warn-only without `dump` / directory isolation / `headPreview` and `headTailPreview`), `InspectFileTool.test.ts` (overview fields, the `colCountMap` map, CRLF and mixed, no trailing newline on the last line, empty files, files over 300KB, detail-overflow degradation, directories and non-existent paths), and overflow/range-read cases for each tool; `ConfigManager.bootstrap.test.ts` covers `custom: true` skipping, syncing only the prompt, and not writing when identical. SDK suite: **499 passed / 6 skipped**
 
 ## [0.11.0] - 2026-09-28
 
 ### 💥 Breaking Changes
 
-- **`createCallSkillSubAgentTool` 移除第三参 `provider`** — Skill 子 Agent 不再经 `provider.buildTools(parent.definition, …)` 重新解析工具集，改为**直接沿用父 Agent 的工具集**（`ctx.agent.tools`），仅剔除 `call_skill_sub_agent` 自身：Skill 子 Agent 作为一次性对话分身，沿用调用者的能力而不再走第二遍权限过滤，同时避免 skill 链式自递归。传入 `Provider` 的调用方需删除该实参
+- **`createCallSkillSubAgentTool` drops the third param `provider`** — the Skill sub-agent no longer re-resolves its tool set via `provider.buildTools(parent.definition, …)`; instead it **reuses the parent Agent's tool set directly** (`ctx.agent.tools`), excluding only `call_skill_sub_agent` itself: as a one-shot conversational clone, the Skill sub-agent reuses the caller's capabilities without a second permission pass, while also preventing chained skill self-recursion. Callers that passed a `Provider` must drop that argument
 
 ### 🚀 New Features
 
-- **Skill 子 Agent 纳入统一委派边界** — `call_skill_sub_agent` 由 `AgentToolLazy` 承载（原为就地实现的 `CallbackTool`），因此与常规 SubAgent 工具共享同一套 `onSubAgentStart` / `onSubAgentEnd` 插件钩子与 `sub-agent-start` / `sub-agent-end` 事件。将护栏装配到 `ctx.subAgent` 的消费方（如上下文护栏）与渲染子 Agent 流式输出的消费方（如 CLI），自此均覆盖该路径
+- **Skill sub-agent brought into the unified delegation boundary** — `call_skill_sub_agent` is now backed by `AgentToolLazy` (previously an in-place `CallbackTool`), so it shares the same `onSubAgentStart` / `onSubAgentEnd` plugin hooks and `sub-agent-start` / `sub-agent-end` events as regular SubAgent tools. Consumers that plug guards into `ctx.subAgent` (e.g. a context guard) and those that render sub-agent streaming output (e.g. the CLI) now cover this path
 
 ### 🛠 Optimized
 
-- **Skill 子 Agent 的构建收敛到 `buildAgent`** — 子 Agent 的初始消息（`System(SKILL.md 内容)` + `User(task)`）改由 `buildAgent` 决定（依托 core 4.3.0 的 `messages` 可选），原先手写的 abort 联动与返回值处理一并删除，交由工具基类统一实现
-- **校验失败改为抛错** — `skill_id` 不存在、或 Skill 未声明 `sub-agent: true` 时抛出错误（原为返回提示文本）；正常路径由 `skill_id` 枚举限定，不触发
-- **依赖 `@ai-zen/agents-core` 升至 `^4.3.0`** — 依赖声明保持 `workspace:^`，由 pnpm 在发布时展开为 `^4.3.0`。core 4.3.0 使 `AgentToolLazy.messages` 变为可选
+- **Skill sub-agent construction consolidated into `buildAgent`** — the sub-agent's initial messages (`System(SKILL.md content)` + `User(task)`) are now decided by `buildAgent` (leveraging core 4.3.0's optional `messages`); the previously hand-written abort linkage and return-value handling are deleted, delegated to the tool base class for a unified implementation
+- **Validation failures now throw** — a missing `skill_id`, or a Skill that doesn't declare `sub-agent: true`, now throws an error (previously it returned a hint text); the normal path is constrained by the `skill_id` enum, so it isn't triggered
+- **Dependency `@ai-zen/agents-core` bumped to `^4.3.0`** — the dependency declaration stays `workspace:^`, expanded to `^4.3.0` by pnpm at publish time. core 4.3.0 makes `AgentToolLazy.messages` optional
 
 ### ✅ Tests
 
-- `skillTools.test.ts` 中 `createCallSkillSubAgentTool` 用例重写为围绕 `AgentToolLazy`：工具契约不变、未知 Skill 抛错、非子 Agent Skill 抛错、委派边界（`onSubAgentStart` 与 `sub-agent-start` 分发、子 Agent 沿用父工具集且剔除自身、初始消息取自 SKILL.md 与 `task`）；SDK 全量 **463 passed / 6 skipped**
+- The `createCallSkillSubAgentTool` cases in `skillTools.test.ts` are rewritten around `AgentToolLazy`: tool contract unchanged, unknown Skill throws, non-sub-agent Skill throws, delegation boundary (`onSubAgentStart` and `sub-agent-start` dispatch, the child reusing the parent tool set while excluding itself, initial messages drawn from SKILL.md and `task`); SDK suite: **463 passed / 6 skipped**
 
 ## [0.10.0] - 2026-09-28
 
 ### 🚀 New Features
 
-- **`load_mcp` 新增 `include_manifest` 开关（可选布尔，默认 `true`）** — 默认行为逐字不变（返回 `{ tools, resources }` 完整清单，tools 含完整 `inputSchema`）；显式传 `false` 时仅建立连接并返回摘要 `{ server, connected, tools: 数量, resources: 数量 }`，不返回任何工具/资源定义。用于「进程重启后连接已失效、但上文中已存在该清单」的场景：只重建连接，不重复向上下文灌入数十 KB 的工具定义，节省 token。完整清单仍留在 `McpConnectionManager` 内，`call_mcp_tool` / `read_mcp_resource` 行为不变；`server` 参数枚举、工具名表与 `DYNAMIC_TOOL_NAMES` 均未变动（前缀缓存结构不变）。失败路径与已连接路径的语义在两种模式下一致；`docs/sdk-design.md` §9 同步更新
+- **`load_mcp` gains an `include_manifest` switch (optional boolean, default `true`)** — the default behavior is unchanged verbatim (returns the full `{ tools, resources }` manifest, with tools carrying the full `inputSchema`); passing `false` explicitly only establishes the connection and returns a summary `{ server, connected, tools: count, resources: count }`, without any tool/resource definitions. It serves the "connection has gone stale after a process restart, but the manifest already exists in context" scenario: rebuild the connection only, without re-injecting tens of KB of tool definitions into the context, saving tokens. The full manifest stays inside `McpConnectionManager`, and `call_mcp_tool` / `read_mcp_resource` behavior is unchanged; the `server` param enum, the tool-name table, and `DYNAMIC_TOOL_NAMES` are all unchanged (the prefix-cache structure is unaffected). The failure-path and already-connected-path semantics are identical in both modes; `docs/sdk-design.md` §9 updated accordingly
 
 ### 🛠 Optimized
 
-- **依赖 `@ai-zen/agents-core` 升至 `^4.2.0`** — 依赖声明保持 `workspace:^`，由 pnpm 在发布时展开为 `^4.2.0`。core 4.2.0 新增子 Agent 委派阻塞钩子 `onSubAgentStart` / `onSubAgentEnd`，并将原有事件 `sub-agent` 更名为 `sub-agent-start`（core 侧破坏性变更）；SDK 内部不监听该事件，源码无需适配。监听该事件的消费方需同步更名
+- **Dependency `@ai-zen/agents-core` bumped to `^4.2.0`** — the dependency declaration stays `workspace:^`, expanded to `^4.2.0` by pnpm at publish time. core 4.2.0 adds the sub-agent delegation blocking hooks `onSubAgentStart` / `onSubAgentEnd` and renames the existing `sub-agent` event to `sub-agent-start` (a core-side breaking change); the SDK doesn't listen to that event internally, so no source adaptation is needed. Consumers listening to that event must rename accordingly
 
 ### ✅ Tests
 
-- `mcpTools.test.ts` 新增 4 个用例：静默 + 未连接、静默 + 已连接、显式 `true`、静默 + 连接失败；SDK 全量 **461 passed / 6 skipped**
+- `mcpTools.test.ts` gains 4 cases: silent + not connected, silent + connected, explicit `true`, silent + connection failure; SDK suite: **461 passed / 6 skipped**
 
 ## [0.9.4] - 2026-09-20
 
 ### 🔧 Fixed
 
-- **MCP `sse` transport 改为真正的 SSE 连接（`SSEClientTransport`）** — 此前 `http` 与 `sse` 合并处理，统一使用 `StreamableHTTPClientTransport`（Streamable HTTP：POST 发送消息 + 可选 SSE 流），使配置声明 `type: "sse"` 的旧版 HTTP+SSE 服务器（GET 建立 SSE 流、POST 到 endpoint 发送消息）实际运行在不匹配的协议栈上。现按 transport 拆分：`http` → `StreamableHTTPClientTransport`，`sse` → `SSEClientTransport`（均为官方 SDK 内置实现）。`headers` 仍经 `requestInit` 透传，由 SDK 统一应用于 SSE 建流（GET）与消息发送（POST）请求；缺少 `url` 时的报错行为保持不变。`McpServerConfig.transport` 注释与 `docs/sdk-design.md` §10/§11 同步更新
+- **MCP `sse` transport switched to a real SSE connection (`SSEClientTransport`)** — previously `http` and `sse` were handled together, both using `StreamableHTTPClientTransport` (Streamable HTTP: POST to send messages + an optional SSE stream), which made legacy HTTP+SSE servers declared as `type: "sse"` (GET to open the SSE stream, POST to the endpoint to send messages) actually run on a mismatched protocol stack. Now they are split by transport: `http` → `StreamableHTTPClientTransport`, `sse` → `SSEClientTransport` (both built-in official SDK implementations). `headers` are still passed through via `requestInit`, applied uniformly by the SDK to the SSE stream setup (GET) and message-sending (POST) requests; the error behavior when `url` is missing is unchanged. The `McpServerConfig.transport` comment and `docs/sdk-design.md` §10/§11 updated accordingly
 
 ### ✅ Tests
 
-- 针对真实 MCP 服务器（`packages/test-project/mcp-servers/sse-server.mjs`，旧版 HTTP+SSE 协议）验证通过：建立连接、工具发现（`echo` / `add`）、工具调用、断开重连；并确认运行时 transport 实例为 `SSEClientTransport`
+- Verified against a real MCP server (`packages/test-project/mcp-servers/sse-server.mjs`, legacy HTTP+SSE protocol): connection setup, tool discovery (`echo` / `add`), tool calls, and disconnect/reconnect; and confirmed the runtime transport instance is `SSEClientTransport`
 
 ## [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 的崩溃问题（`?? []` 兜底）。
+- **`createAgent` no longer pollutes the Agent definition template (`definition.messages` reference isolation)** — when creating an Agent, `definition.messages` is now snapshot (`[...(definition.messages ?? [])]`) instead of being referenced directly. Previously the definition array was passed straight to `AgentContext.messages` (a mutable runtime array), so during a conversation `append()` would write the full conversation history back into `definition.messages`, causing:
+  - the task-migration `prune` branch to expand the polluted "full history" instead of the template → old messages were neither physically deleted nor marked `omit`, yet the newly injected breakpoint message was visible;
+  - the `omit` branch's `preserveCount` to equal the full length because `definition.messages` and `agent.messages` pointed to the same array → history messages could not be marked `omit`;
+  - `/new` to copy from the polluted template, so a new conversation inherited the old history.
+  - Also fixes a crash when creating an Agent whose definition lacks a `messages` field (`undefined`) (with a `?? []` fallback).
 
 ### ✅ Tests
 
-- `createAgent.test.ts` 新增：`append` 不污染 `definition.messages`（引用隔离）；Agent 定义缺少 `messages` 字段时正常创建
+- `createAgent.test.ts` gains: `append` does not pollute `definition.messages` (reference isolation); an Agent whose definition lacks a `messages` field is created normally
 
 ## [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，本地图片请使用文件路径"
+- **Default Agent prompt refactored (`DEFAULT_AGENT_DEFINITION`)** — streamlined and stylistically unified:
+  - the persona is set to "witty and humorous, rigorous and reliable"
+  - the original 8 principles are compressed into one core rule: whenever you hit any situation that is unclear, uncertain, contradictory, or that might affect the result, stop immediately and ask the user directly, rather than filling in the gaps yourself, guessing, or forcing ahead
+  - a new "terse" principle: state only the result and necessary explanation; the execution process (tool calls, reads/writes, searches, etc.) is already visible to the user, so don't restate it, to save tokens
+  - guards retained: proactively call tools, report faithfully, and act only within the scope you've been assigned
+  - injects "current operating system" info, dynamically using `process.platform` to adapt to different platforms
+- **`ViewImageTool` gains a local-URL check** — a new `isLocalUrl()` rejects the `file://` protocol and http(s) URLs pointing to local loopback addresses (`localhost`/`127.0.0.1`/`[::1]`/`0.0.0.0`) (API providers cannot download them), erroring early in the call; `function.description` and the `path_or_url` param description now add "local URLs are not supported; use a file path for local images"
 
 ## [0.9.1] - 2026-08-28
 

package/README.md

@@ -4,7 +4,7 @@ AI-Zen SDK — shared business logic layer providing a unified Agent runtime for
 
 ## Source of Truth
 
-**[`docs/sdk-design.md`](./docs/sdk-design.md)** is the single source of truth for this package's design. All implementations must stay consistent with the document.
+**[`docs/sdk-design-v1.md`](./docs/sdk-design-v1.md)** is the single source of truth for this package's design. All implementations must stay consistent with the document. (Pre-refactor design is kept in [`docs/sdk-design-v0.md`](./docs/sdk-design-v0.md).)
 
 ## Architecture
 
@@ -18,23 +18,24 @@ Desktop ──┘                    │
 ## Module Layering
 
 ```
-types        ← pure types, zero business dependencies (incl. ToolEnv)
-config       ← ConfigManager + constants: config.json read/write + directory setup + factory defaults
-crud         ← capability-entity CRUD (Agent definitions, etc.; conversations/drafts are persisted by each consumer)
-capabilities ← capability discovery & assembly (built-in + user + MCP + Skill + SubAgent)
-runtime      ← Provider + model factory + Agent assembly + MCP connection management + task migration + SdkCallbackTool base
-plugin       ← Agent plugins (autoMigrate, autoRefreshTools, contextGuard, unknownToolHint)
-shared       ← logging, errors
+types         ← pure types, zero business dependencies (incl. ToolEnv)
+config        ← ConfigManager + constants: config.json read/write + directory setup + factory defaults
+crud          ← capability-entity CRUD (Agent definitions; conversations/drafts are persisted by each consumer)
+runtime       ← model factory + Agent assembly + task migration (createModel / createAgent / SdkAgent / TaskMigrationService)
+scope         ← Scope orchestration container + ScopePlugin contract + PermissionEvaluator / disclosure + plugins/ (5 self-contained capability sources: discovery + tools + plugin)
+agent-plugins ← Agent plugins (autoMigrate, autoRefreshTools, contextGuard, unknownToolHint)
+shared        ← logging, errors
 ```
 
-Dependency direction: `plugin → runtime → capabilities → crud → config → types`. Upper layers depend on lower layers, never the other way around.
+Dependency direction: `agent-plugins → runtime → scope`; `runtime → scope / crud / shared / types`, `scope → types / shared`. Upper layers depend on lower layers.
 
 ## Core Concepts
 
 | Entity | Description |
 |--------|-------------|
-| **Provider** | Global context + capability registry, holding config, paths (incl. `cwd`), model factory, and MCP manager; integrates discovery → filtering → instantiation |
-| **ToolEnv** | Tool environment `{ cwd, config }`; injected when the Provider instantiates built-in tools, serving as the base for relative path resolution and config reads |
+| **Scope** | Orchestration container: global context (`config` / `cwd` / `agentsDir`) + the three-phase capability pipeline (discover → filter → instantiate) + plugin registry. Explicitly assembled via `scope.use(...)` |
+| **ScopePlugin** | Capability plugin (the v1 extension point): self-owns one capability source's discovery state, candidate names, and instantiation (`discover` / `candidates` / `instantiate` / `dispose`). 5 standard plugins ship out of the box, assembled via `allInOne()` |
+| **ToolEnv** | Tool environment `{ cwd, config }`; injected when the built-in-tools plugin (`BuiltinToolsScopePlugin`) instantiates tools, serving as the base for relative path resolution and config reads |
 | **SdkCallbackTool** | Abstract base for built-in tools: `env` constructor injection + subclass `call()` + `resolve()` relative path resolution |
 | **SdkAgent** | Extends the Core Agent, carries SDK metadata, supports `use()` plugin registration |
 | **AgentPlugin** | Plugin interface (`onInit`, `onBeforeSend`, `onAfterSend`, `onInnerLoopStart`, `onInnerLoopEnd`, `onInnerLoopsStart`, `onInnerLoopsEnd`, `onToolCall`, `onUnknownTool`, `onSubAgentStart`, `onSubAgentEnd`) |
@@ -57,17 +58,24 @@ Agent.permissions
 ## Consumption
 
 ```typescript
-const provider = await Provider.create({
+const scope = new Scope({
   config,
-  cwd: "/path/to/workspace", // one working directory per Provider; parallel sessions don't interfere
-  ...paths,
-});
-const agent = await createAgent(provider, "my-agent");
+  cwd: "/path/to/workspace", // one working directory per Scope; parallel sessions don't interfere
+  agentsDir,
+}).use(
+  ...allInOne({ skillsPaths, toolsPaths, subAgentsPaths, mcpPaths }),
+);
+await scope.init();
+
+const agent = await createAgent(scope, "my-agent");
 const migrationService = new TaskMigrationService({ onMigrated }); // migrates via the agent's own model client
 agent.use(new AutoMigratePlugin({ service: migrationService, maxTokens }));
 agent.use(new AutoRefreshToolsPlugin());
+agent.use(new UnknownToolHintPlugin({ scope }));
 await agent.init();
 await agent.send("Hello");
+
+await scope.dispose(); // disconnect MCP, release plugin resources
 ```
 
 ## Development Status
@@ -77,14 +85,14 @@ await agent.send("Hello");
 | `types` | ✅ Implemented — core entities, permission model, MCP types complete |
 | `config` | ✅ Implemented — ConfigManager + factory defaults + one-shot bootstrap |
 | `crud` | ✅ Implemented — capability-entity CRUD for Agents, etc. (conversations/drafts persisted by each consumer) |
-| `capabilities` | ✅ Implemented — discovery + permission filtering + safe pre-filtering + enumeration disclosure |
-| `runtime` | ✅ Implemented — Provider, createAgent, MCP connection management, task migration |
-| `plugin` | ✅ Implemented — AutoMigratePlugin / AutoRefreshToolsPlugin / ContextGuardPlugin / UnknownToolHintPlugin |
+| `scope` | ✅ Implemented — Scope + ScopePlugin + 5 standard plugins (builtin / user-tools / skills / mcp / subagents) + allInOne |
+| `runtime` | ✅ Implemented — createAgent, MCP connection management, task migration |
+| `agent-plugins` | ✅ Implemented — AutoMigratePlugin / AutoRefreshToolsPlugin / ContextGuardPlugin / UnknownToolHintPlugin |
 | `shared` | ✅ Implemented — SdkError + injectable Logger |
 
 ## Built-in Tools
 
-All built-in tools are classes (extending `SdkCallbackTool`), instantiated by the Provider with a `ToolEnv` — one set of instances per Provider, with `cwd` injected and relative paths resolved against `Provider.cwd`, never depending on the global `process.cwd()`.
+All built-in tools are classes (extending `SdkCallbackTool`), instantiated by the built-in-tools plugin (`BuiltinToolsScopePlugin`) with a `ToolEnv` — one set of instances per Scope, with `cwd` injected and relative paths resolved against `Scope.cwd`, never depending on the global `process.cwd()`.
 
 | Tool | Description |
 |------|-------------|
@@ -114,7 +122,7 @@ Conditionally injected based on the active model / config:
 | `generateImage` | Only when `defaultImageModel` is configured | Generate an image from a text description |
 | `viewImage` | Only for vision models (the agent's `modelId` resolves to a model with `vision: true`) | View / analyze an image: local images are auto-uploaded via the Files API, network URLs are referenced directly |
 
-Tool output protection: `AppConfig.maxToolOutput` (in characters, default 32768) is the unified ceiling for tool output. Each tool handles overflow itself — `exec` dumps `stdout.log` / `stderr.log` separately (returning head/tail previews per stream), `findText` / `glob` / `ls` dump `result.json` (returning a head preview), and `readFile` only warns and suggests batched reads via `range`. Dumps go to `<tmpdir>/ai-zen/tool-output/<tool>-<timestamp>-<random>/`, one directory per call, with no self-cleanup. See [`docs/sdk-design.md` §7](docs/sdk-design.md).
+Tool output protection: `AppConfig.maxToolOutput` (in characters, default 32768) is the unified ceiling for tool output. Each tool handles overflow itself — `exec` dumps `stdout.log` / `stderr.log` separately (returning head/tail previews per stream), `findText` / `glob` / `ls` dump `result.json` (returning a head preview), and `readFile` only warns and suggests batched reads via `range`. Dumps go to `<tmpdir>/ai-zen/tool-output/<tool>-<timestamp>-<random>/`, one directory per call, with no self-cleanup. See [`docs/sdk-design-v1.md` §12](docs/sdk-design-v1.md).
 
 ## Built-in Plugins
 

package/README.zh.md

@@ -4,7 +4,7 @@ AI-Zen SDK — 共享业务逻辑层，为 CLI 和 Desktop 提供统一的 Agent
 
 ## 真相源
 
-**[`docs/sdk-design.md`](./docs/sdk-design.md)** 是本包的唯一设计真相源。所有实现必须与文档一致。
+**[`docs/sdk-design-v1.md`](./docs/sdk-design-v1.md)** 是本包的唯一设计真相源。所有实现必须与文档一致。（重构前的设计保留在 [`docs/sdk-design-v0.md`](./docs/sdk-design-v0.md)。）
 ## 架构
 
 ```
@@ -17,23 +17,24 @@ Desktop ──┘                    │
 ## 模块分层
 
 ```
-types        ← 纯类型，零业务依赖（含 ToolEnv 工具环境）
-config       ← ConfigManager + constants：读写 config.json + 目录初始化 + 出厂默认
-crud         ← 能力实体 CRUD（Agent 定义等；会话/草稿已下放给各端自行持久化）
-capabilities ← 能力发现与装配（内置 + 用户 + MCP + Skill + SubAgent）
-runtime      ← Provider + 模型工厂 + Agent 组装 + MCP 连接管理 + 任务迁移 + SdkCallbackTool 工具基类
-plugin       ← Agent 插件（autoMigrate、autoRefreshTools、contextGuard、unknownToolHint）
-shared       ← 日志、错误
+types         ← 纯类型，零业务依赖（含 ToolEnv 工具环境）
+config        ← ConfigManager + constants：读写 config.json + 目录初始化 + 出厂默认
+crud          ← 能力实体 CRUD（Agent 定义等；会话/草稿已下放给各端自行持久化）
+runtime       ← 模型工厂 + Agent 组装 + 任务迁移（createModel / createAgent / SdkAgent / TaskMigrationService）
+scope         ← Scope 编排容器 + ScopePlugin 契约 + PermissionEvaluator / disclosure + plugins/（5 个自包含能力来源：发现 + 工具 + 插件）
+agent-plugins ← Agent 插件（autoMigrate、autoRefreshTools、contextGuard、unknownToolHint）
+shared        ← 日志、错误
 ```
 
-依赖方向：`plugin → runtime → capabilities → crud → config → types`，上层依赖下层，反之不行。
+依赖方向：`agent-plugins → runtime → scope`；`runtime → scope / crud / shared / types`，`scope → types / shared`。上层依赖下层，反之不行。
 
 ## 核心概念
 
 | 实体 | 说明 |
 |------|------|
-| **Provider** | 全局上下文 + 能力注册表，持有配置、路径（含 `cwd`）、模型工厂、MCP 管理器，整合发现 → 过滤 → 实例化 |
-| **ToolEnv** | 工具环境 `{ cwd, config }`，Provider 实例化内置工具时注入，作为相对路径解析与配置读取的基准 |
+| **Scope** | 编排容器：全局上下文（`config` / `cwd` / `agentsDir`）+ 三阶段能力管线（发现 → 过滤 → 实例化）+ 插件注册表。经 `scope.use(...)` 显式装配 |
+| **ScopePlugin** | 能力插件（v1 扩展点）：自持一类能力的发现状态、候选名与实例化（`discover` / `candidates` / `instantiate` / `dispose`）。内置 5 个标准插件，经 `allInOne()` 一键装配 |
+| **ToolEnv** | 工具环境 `{ cwd, config }`，内置工具插件（`BuiltinToolsScopePlugin`）实例化工具时注入，作为相对路径解析与配置读取的基准 |
 | **SdkCallbackTool** | 内置工具抽象基类：`env` 构造注入 + 子类实现 `call()` + `resolve()` 相对路径解析 |
 | **SdkAgent** | 继承 Core Agent，携带 SDK 元数据，支持 `use()` 插件注册 |
 | **AgentPlugin** | 插件接口（`onInit`, `onBeforeSend`, `onAfterSend`, `onInnerLoopStart`, `onInnerLoopEnd`, `onInnerLoopsStart`, `onInnerLoopsEnd`, `onToolCall`, `onUnknownTool`, `onSubAgentStart`, `onSubAgentEnd`） |
@@ -56,17 +57,24 @@ Agent.permissions
 ## 消费模式
 
 ```typescript
-const provider = await Provider.create({
+const scope = new Scope({
   config,
-  cwd: "/path/to/workspace", // 每个 Provider 一个工作目录，多会话并行互不干扰
-  ...paths,
-});
-const agent = await createAgent(provider, "my-agent");
+  cwd: "/path/to/workspace", // 每个 Scope 一个工作目录，多会话并行互不干扰
+  agentsDir,
+}).use(
+  ...allInOne({ skillsPaths, toolsPaths, subAgentsPaths, mcpPaths }),
+);
+await scope.init();
+
+const agent = await createAgent(scope, "my-agent");
 const migrationService = new TaskMigrationService({ onMigrated }); // 迁移复用传入 agent 自身的模型调用
 agent.use(new AutoMigratePlugin({ service: migrationService, maxTokens }));
 agent.use(new AutoRefreshToolsPlugin());
+agent.use(new UnknownToolHintPlugin({ scope }));
 await agent.init();
 await agent.send("你好");
+
+await scope.dispose(); // 断开 MCP、释放插件资源
 ```
 
 ## 开发状态
@@ -76,14 +84,14 @@ await agent.send("你好");
 | `types` | ✅ 已实现 — 核心实体、权限模型、MCP 类型完整 |
 | `config` | ✅ 已实现 — ConfigManager + 出厂默认配置 + 一键 bootstrap |
 | `crud` | ✅ 已实现 — Agent 等能力实体 CRUD（会话/草稿由各端自行持久化） |
-| `capabilities` | ✅ 已实现 — 发现 + 权限过滤 + 安全预过滤 + 枚举披露 |
-| `runtime` | ✅ 已实现 — Provider、createAgent、MCP 连接管理、任务迁移 |
-| `plugin` | ✅ 已实现 — AutoMigratePlugin / AutoRefreshToolsPlugin / ContextGuardPlugin / UnknownToolHintPlugin |
+| `scope` | ✅ 已实现 — Scope + ScopePlugin + 5 个标准插件（builtin / user-tools / skills / mcp / subagents）+ allInOne |
+| `runtime` | ✅ 已实现 — createAgent、MCP 连接管理、任务迁移 |
+| `agent-plugins` | ✅ 已实现 — AutoMigratePlugin / AutoRefreshToolsPlugin / ContextGuardPlugin / UnknownToolHintPlugin |
 | `shared` | ✅ 已实现 — SdkError + 可注入 Logger |
 
 ## 内置工具
 
-内置工具全部类化（继承 `SdkCallbackTool`），由 Provider 用 `ToolEnv` 实例化——每个 Provider 一套实例，`cwd` 注入，相对路径以 `Provider.cwd` 为基准，不依赖全局 `process.cwd()`。
+内置工具全部类化（继承 `SdkCallbackTool`），由内置工具插件（`BuiltinToolsScopePlugin`）用 `ToolEnv` 实例化——每个 Scope 一套实例，`cwd` 注入，相对路径以 `Scope.cwd` 为基准，不依赖全局 `process.cwd()`。
 
 | 工具 | 说明 |
 |------|------|
@@ -113,7 +121,7 @@ await agent.send("你好");
 | `generateImage` | 配置了 `defaultImageModel` 才注册 | 根据文字描述生成图片 |
 | `viewImage` | 仅视觉模型可用（Agent 的 `modelId` 解析为 `vision: true` 的模型） | 查看/分析图片：本地图片自动经 Files API 上传，网络 URL 直接引用 |
 
-工具输出保护：`AppConfig.maxToolOutput`（字符数，缺省 32768）是工具输出的统一上限，超限时由各工具自行处置——`exec` 分文件落盘 `stdout.log` / `stderr.log`（返回各流头尾预览），`findText` / `glob` / `ls` 落盘 `result.json`（返回头部预览），`readFile` 仅警告并提示用 `range` 分批读取。落盘目录为 `<tmpdir>/ai-zen/tool-output/<工具名>-<时间戳>-<随机串>/`，每次调用独立、不自清理。详见 [`docs/sdk-design.md` §7](docs/sdk-design.md)。
+工具输出保护：`AppConfig.maxToolOutput`（字符数，缺省 32768）是工具输出的统一上限，超限时由各工具自行处置——`exec` 分文件落盘 `stdout.log` / `stderr.log`（返回各流头尾预览），`findText` / `glob` / `ls` 落盘 `result.json`（返回头部预览），`readFile` 仅警告并提示用 `range` 分批读取。落盘目录为 `<tmpdir>/ai-zen/tool-output/<工具名>-<时间戳>-<随机串>/`，每次调用独立、不自清理。详见 [`docs/sdk-design-v1.md` §12](docs/sdk-design-v1.md)。
 
 ## 内置插件
 

package/dist/{plugin → agent-plugins}/AutoRefreshToolsPlugin.js

@@ -9,8 +9,8 @@
 export class AutoRefreshToolsPlugin {
     async onBeforeSend(ctx) {
         const agent = ctx.agent;
-        await agent.provider.refresh({ silent: true });
-        agent.tools = agent.provider.buildTools(agent.definition, {
+        await agent.scope.refresh({ silent: true });
+        agent.tools = agent.scope.buildTools(agent.definition, {
             exclude: {
                 subagents: agent.definition.function?.name
                     ? [agent.definition.function.name]

package/dist/{plugin → agent-plugins}/UnknownToolHintPlugin.d.ts

@@ -1,5 +1,5 @@
 import type { AgentPlugin, UnknownToolContext } from "@ai-zen/agents-core";
-import type { Provider } from "../runtime/Provider.js";
+import type { Scope } from "../scope/Scope.js";
 /**
  * 未知工具智能提示插件 — MCP 场景引导。
  *
@@ -8,14 +8,16 @@ import type { Provider } from "../runtime/Provider.js";
  *   - 有 MCP 配置且 `call_mcp_tool` 可用 → 提示使用 `call_mcp_tool`
  *   - 否则 → 仅提示工具不存在
  *
- * 由调用方显式注册（`agent.use(new UnknownToolHintPlugin({ provider }))`）。
+ * 由调用方显式注册（`agent.use(new UnknownToolHintPlugin({ scope }))`）。
  * 未注册时，Agent 回落到底层的简单文本默认提示（core 内建）。
+ *
+ * 是否"有 MCP 配置"经 `scope.getPluginById(McpScopePlugin.ID)` 查询 MCP 插件获得。
  */
 export declare class UnknownToolHintPlugin implements AgentPlugin {
-    /** 全局 Provider 实例 */
-    private readonly provider;
+    /** 全局 Scope 实例 */
+    private readonly scope;
     constructor(options: {
-        provider: Provider;
+        scope: Scope;
     });
     onUnknownTool(ctx: UnknownToolContext): string | undefined;
 }

package/dist/{plugin → agent-plugins}/UnknownToolHintPlugin.js

@@ -1,3 +1,4 @@
+import { McpScopePlugin } from "../scope/plugins/mcp/McpScopePlugin.js";
 /**
  * 未知工具智能提示插件 — MCP 场景引导。
  *
@@ -6,18 +7,21 @@
  *   - 有 MCP 配置且 `call_mcp_tool` 可用 → 提示使用 `call_mcp_tool`
  *   - 否则 → 仅提示工具不存在
  *
- * 由调用方显式注册（`agent.use(new UnknownToolHintPlugin({ provider }))`）。
+ * 由调用方显式注册（`agent.use(new UnknownToolHintPlugin({ scope }))`）。
  * 未注册时，Agent 回落到底层的简单文本默认提示（core 内建）。
+ *
+ * 是否"有 MCP 配置"经 `scope.getPluginById(McpScopePlugin.ID)` 查询 MCP 插件获得。
  */
 export class UnknownToolHintPlugin {
-    /** 全局 Provider 实例 */
-    provider;
+    /** 全局 Scope 实例 */
+    scope;
     constructor(options) {
-        this.provider = options.provider;
+        this.scope = options.scope;
     }
     onUnknownTool(ctx) {
         const toolName = ctx.toolCall.function?.name ?? "未知";
-        const hasMcpConfig = this.provider.mcpPaths.length > 0;
+        const mcpPlugin = this.scope.getPluginById(McpScopePlugin.ID);
+        const hasMcpConfig = mcpPlugin?.hasConfig() ?? false;
         const hasCallMcpTool = ctx.availableTools.some((t) => t.function.name === "call_mcp_tool");
         if (hasMcpConfig && !hasCallMcpTool) {
             return `工具 "${toolName}" 不存在。当前有 MCP 服务器配置，但 call_mcp_tool 权限已被禁用，如需使用 MCP 工具请调整权限。`;

package/dist/config/ConfigManager.d.ts

@@ -18,6 +18,11 @@ export declare class ConfigManager {
     ensureDirs(): Promise<void>;
     /**
      * 确保 config.json 存在。不存在时写入出厂默认配置 DSL。
+     *
+     * 已存在时执行「出厂模型清单同步」（见 syncManagedModels）：
+     * models / imageModels 中凡是**没有** `custom: true` 的条目一律视为出厂托管，
+     * 会被移除并替换为 DEFAULT_APP_CONFIG 中的最新定义；标了 `custom: true` 的
+     * 条目视为用户自有，原样保留。同步结果与磁盘内容一致时不写盘。
      */
     ensureDefaultConfig(): Promise<AppConfig>;
     /**
@@ -70,4 +75,16 @@ export declare class ConfigManager {
     /** 原子写 JSON 文件（先写 .tmp 再 rename，避免半成品）。 */
     private writeJson;
 }
+/**
+ * 同步出厂托管的模型清单（与默认 Agent 的 custom 机制一致）。
+ *
+ * 规则：
+ * - 未标 `custom: true` 的条目 → 由 SDK 托管，从结果中移除，改用 defaults 中的最新定义；
+ * - 标了 `custom: true` 的条目 → 用户自有，原样保留；与出厂定义同 id 时用户版本优先；
+ * - 默认模型 ID（defaultModel / defaultImageModel / defaultMigrationModel）
+ *   在合并后若已不存在 → 回退到出厂默认，避免悬空引用。
+ *
+ * 端点（endpoints）不参与托管，始终保持用户配置。
+ */
+export declare function syncManagedModels(config: AppConfig): AppConfig;
 export { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";