@ai-zen/cli 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [0.9.0] - 2026-09-30
+
+### 💥 破坏性变更
+
+- **升级 `@ai-zen/agents-sdk` 到 `1.0.0-alpha.0`（Provider → Scope 架构重构）** — SDK 1.0.0-alpha.0 将全局入口对象 `Provider` 改名为 `Scope`，把四类能力来源疏散为 5 个可组合的 `ScopePlugin`，并移除 `Provider.create()`（改为显式装配）。CLI 侧同步适配 `src/agent-creator.ts`：
+  - 导入 `Scope` / `allInOne` 取代 `Provider`
+  - `Provider.create({ config, agentsDir, subAgentsPaths, skillsPaths, toolsPaths, mcpPaths })` → `new Scope({ config, agentsDir }).use(...allInOne({ subAgentsPaths, skillsPaths, toolsPaths, mcpPaths }))` + `await scope.init()`
+  - 单例/工厂改名：`getProvider` → `getScope`、`resetProvider` → `resetScope`；`createAgent` 内部改调 `sdkCreateAgent(scope, agentId)`
+  - 依赖声明由 `^0.12.0` 改为精确 `1.0.0-alpha.0`（alpha 阶段锁定）
+
+### 📝 文档
+
+- 中英 README 与 `docs/zh|en/{tools,mcp,skills}.md`：`Provider` / `getProvider()` 同步为 `Scope` / `getScope()`
+- `docs/zh|en/getting-started.md`：运行时依赖版本同步为 `@ai-zen/agents-sdk` `1.0.0-alpha.0`
+- `docs/manifest.json`：版本号同步为 `0.9.0`
+
+### ✅ 测试
+
+- `tsc --noEmit`（`tsconfig.test.json`）与 `npm run build` 零错误
+- 全量单测 9 文件 / 74 用例通过
+- e2e 6 用例通过（含真实 DeepSeek API 对话，验证 CLI → SDK `1.0.0-alpha.0` → API 全链路）
+
+## [0.8.2] - 2026-09-29
+
+### ⚠️ 依赖升级
+
+- **`@ai-zen/agents-sdk` 升至 `^0.12.0`** — SDK 0.12.0 新增内置工具 `inspectFile`（内置工具类 19 → 20）、`readFile` 的 `range` 分批读取参数，新增配置项 `maxToolOutput`（缺省 32768 字符）与工具输出保护行为，并精简了 `batchEdit` 的输出。该版本**无破坏性变更**，CLI 源码无需适配：类型与默认配置全量委托 SDK，`src/version.ts` 由实际安装版本读取，工具清单由 SDK 静态注册表自动发现，故版本横幅随之显示 sdk `0.12.0`
+
+### 📝 文档
+
+- 同步内置工具计数 19 → 20：中英 README、`docs/zh|en/tools.md`、`docs/zh|en/index.md` 与 `docs/manifest.json`
+- 工具表补充 `inspectFile`（勘察文件结构概况），并为 `readFile` 补注 `range` 参数
+- `docs/zh|en/tools.md` 新增「输出保护」说明：超限时 `exec` / `findText` / `glob` / `ls` 落盘并返回警告，`readFile` / `inspectFile` 仅警告不落盘
+- `docs/zh|en/getting-started.md` 的运行时依赖版本同步为 `@ai-zen/agents-sdk` `^0.12.0`
+
+### ✅ 测试
+
+- 沿用既有 9 文件 / 74 用例，全部通过；`tsc --noEmit` 与 `npm run build`（`0.8.2`）均通过
+
 ## [0.8.1] - 2026-09-28
 
 ### 🚀 新功能

package/README.md

@@ -204,12 +204,13 @@ Same-named servers in higher priority override lower ones.
 
 ## Built-in Tools
 
-The CLI provides 19 built-in tools, implemented by `@ai-zen/agents-sdk`. Tool availability is self-declared by each tool via `isAvailable(config, definition)` at build time (when the model is already known):
+The CLI provides 20 built-in tools, implemented by `@ai-zen/agents-sdk`. Tool availability is self-declared by each tool via `isAvailable(config, definition)` at build time (when the model is already known):
 
 | Tool | Description |
 |------|-------------|
 | `cwd` | Get current working directory |
-| `readFile` | Read file contents |
+| `readFile` | Read file contents (supports `range` for partial reads) |
+| `inspectFile` | Inspect file structure (lines, chars, column widths, line-ending style) without reading content |
 | `writeFile` | Write content to file |
 | `edit` | Replace text in files (single replacement) |
 | `batchEdit` | Batch replace text in files |
@@ -242,9 +243,9 @@ In addition to built-in tools, the SDK provides 5 dynamic loading tools that are
 
 ## Tool Assembly Pipeline
 
-Tools are assembled in three phases by the SDK's `Provider` capability pipeline:
+Tools are assembled in three phases by the SDK's `Scope` capability pipeline:
 
-1. **Discovery** — Scan filesystem for built-in tools, user tools, SubAgents, Skills, and MCP servers. All 19 built-in tools are discovered unconditionally (no filtering at this stage)
+1. **Discovery** — Scan filesystem for built-in tools, user tools, SubAgents, Skills, and MCP servers. All 20 built-in tools are discovered unconditionally (no filtering at this stage)
 2. **Filtering** — Apply permissions (`allow`/`deny`), security exclusions (recursion protection), and each tool's self-declared `isAvailable(config, definition)` (availability is decided at build time when the model is known; e.g. `viewImage` only for vision models, `generateImage` requires `defaultImageModel`)
 3. **Instantiation** — Map filtered names to `Tool` instances and register dynamic loaders
 

package/README.zh.md

@@ -204,12 +204,13 @@ MCP 服务器配置从多个来源合并（优先级从高到低）：
 
 ## 内置工具
 
-CLI 提供 19 个内置工具，由 `@ai-zen/agents-sdk` 实现。工具可用性由各工具在构建阶段（模型已知时）通过 `isAvailable(config, definition)` 自声明：
+CLI 提供 20 个内置工具，由 `@ai-zen/agents-sdk` 实现。工具可用性由各工具在构建阶段（模型已知时）通过 `isAvailable(config, definition)` 自声明：
 
 | 工具 | 说明 |
 |------|------|
 | `cwd` | 获取当前工作目录 |
-| `readFile` | 读取文件内容 |
+| `readFile` | 读取文件内容（支持 `range` 分批读取） |
+| `inspectFile` | 勘察文件结构概况（行数、字符数、列宽分布、行尾风格），不读取内容 |
 | `writeFile` | 写入文件 |
 | `edit` | 替换文件中的文本（单次替换） |
 | `batchEdit` | 批量编辑文本 |
@@ -242,9 +243,9 @@ CLI 提供 19 个内置工具，由 `@ai-zen/agents-sdk` 实现。工具可用
 
 ## 工具装配流程
 
-工具装配由 SDK 的 `Provider` 能力管线管理，分为三个阶段：
+工具装配由 SDK 的 `Scope` 能力管线管理，分为三个阶段：
 
-1. **发现** — 扫描文件系统获取内置工具、用户工具、SubAgent、Skill 和 MCP 服务器。19 个内置工具全部无条件发现（此阶段不做过滤）
+1. **发现** — 扫描文件系统获取内置工具、用户工具、SubAgent、Skill 和 MCP 服务器。20 个内置工具全部无条件发现（此阶段不做过滤）
 2. **过滤** — 应用权限（`allow`/`deny`）、安全排除（递归保护），以及各工具自声明的 `isAvailable(config, definition)`（在模型已知的构建阶段判断可用性；如 `viewImage` 仅视觉模型、`generateImage` 需配置 `defaultImageModel`）
 3. **实例化** — 将过滤后的名称映射为 `Tool` 实例，注册动态加载器
 

package/dist/agent-creator.d.ts

@@ -1,13 +1,13 @@
 /**
  * Agent 创建 — CLI 层
  *
- * 委托给 @ai-zen/agents-sdk 的 Provider。
- * CLI 层负责：组装路径、构建 Provider 单例、注册默认插件。
+ * 委托给 @ai-zen/agents-sdk 的 Scope。
+ * CLI 层负责：组装路径、构建 Scope 单例、装配能力插件。
  */
-import { Provider, SdkAgent } from "@ai-zen/agents-sdk";
+import { Scope, SdkAgent } from "@ai-zen/agents-sdk";
 import type { AgentNS } from "@ai-zen/agents-core";
-export declare function getProvider(): Promise<Provider>;
-export declare function resetProvider(): void;
+export declare function getScope(): Promise<Scope>;
+export declare function resetScope(): void;
 export interface CreateAgentOptions {
     messages?: AgentNS.Message[];
     agentId?: string;

package/dist/agent-creator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-creator.d.ts","sourceRoot":"","sources":["../src/agent-creator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EACL,QAAQ,EAER,QAAQ,EACT,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAiBnD,wBAAsB,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC,CAyCrD;AAED,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAID,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAchF"}
+{"version":3,"file":"agent-creator.d.ts","sourceRoot":"","sources":["../src/agent-creator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EACL,KAAK,EAGL,QAAQ,EACT,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAiBnD,wBAAsB,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC,CA8C/C;AAED,wBAAgB,UAAU,IAAI,IAAI,CAEjC;AAID,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAchF"}

package/dist/agent-creator.js

@@ -1,21 +1,21 @@
 /**
  * Agent 创建 — CLI 层
  *
- * 委托给 @ai-zen/agents-sdk 的 Provider。
- * CLI 层负责：组装路径、构建 Provider 单例、注册默认插件。
+ * 委托给 @ai-zen/agents-sdk 的 Scope。
+ * CLI 层负责：组装路径、构建 Scope 单例、装配能力插件。
  */
 import { existsSync } from "fs";
 import { join } from "path";
-import { Provider, createAgent as sdkCreateAgent, } from "@ai-zen/agents-sdk";
+import { Scope, allInOne, createAgent as sdkCreateAgent, } from "@ai-zen/agents-sdk";
 import { AGENTS_DIR, SUB_AGENTS_DIR, SKILLS_DIR, TOOLS_DIR, AI_ZEN_DIR, PROJECT_SUB_AGENTS_DIR, PROJECT_SKILLS_DIR, PROJECT_TOOLS_DIR, USER_AGENTS_SKILLS_DIR, USER_AGENTS_MCP_CONFIG_FILE, PROJECT_AGENTS_SKILLS_DIR, PROJECT_AGENTS_MCP_CONFIG_FILE, } from "./config.js";
 import { readConfig } from "./config.js";
-// ==================== Provider 创建（单例）====================
-let _provider = null;
+// ==================== Scope 创建（单例）====================
+let _scope = null;
 /** existsSync 的别名，用于数组 .filter() 场景 */
 const exists = existsSync;
-export async function getProvider() {
-    if (_provider)
-        return _provider;
+export async function getScope() {
+    if (_scope)
+        return _scope;
     const config = await readConfig();
     // MCP 配置合并优先级（从高到低）：
     //   1. 项目/.mcp.json
@@ -41,24 +41,26 @@ export async function getProvider() {
         SKILLS_DIR,
         USER_AGENTS_SKILLS_DIR,
     ].filter(exists);
-    _provider = await Provider.create({
+    _scope = new Scope({
         config,
         agentsDir: AGENTS_DIR,
+    }).use(...allInOne({
         subAgentsPaths: [PROJECT_SUB_AGENTS_DIR, SUB_AGENTS_DIR].filter(exists),
         skillsPaths,
         toolsPaths: [PROJECT_TOOLS_DIR, TOOLS_DIR].filter(exists),
         mcpPaths,
-    });
-    return _provider;
+    }));
+    await _scope.init();
+    return _scope;
 }
-export function resetProvider() {
-    _provider = null;
+export function resetScope() {
+    _scope = null;
 }
 export async function createAgent(options) {
     const { messages, agentId } = options;
-    const provider = await getProvider();
+    const scope = await getScope();
     // 始终从磁盘读取 Agent 定义（含 permissions、工具配置等）
-    const agent = await sdkCreateAgent(provider, agentId || "default");
+    const agent = await sdkCreateAgent(scope, agentId || "default");
     // 有历史消息时替换（恢复草稿/已保存对话）。
     // 拷贝而非直接引用：恢复的数组来自草稿/对话存档，直接引用会让后续 append 改写传入数组。
     if (messages && messages.length > 0) {

package/dist/agent-creator.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-creator.js","sourceRoot":"","sources":["../src/agent-creator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EACL,QAAQ,EACR,WAAW,IAAI,cAAc,GAE9B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EACjD,UAAU,EACV,sBAAsB,EAAE,kBAAkB,EAAE,iBAAiB,EAC7D,sBAAsB,EAAE,2BAA2B,EACnD,yBAAyB,EAAE,8BAA8B,GAC1D,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,2DAA2D;AAE3D,IAAI,SAAS,GAAoB,IAAI,CAAC;AAEtC,uCAAuC;AACvC,MAAM,MAAM,GAAG,UAAU,CAAC;AAE1B,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAEhC,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAElC,qBAAqB;IACrB,oBAAoB;IACpB,2BAA2B;IAC3B,8CAA8C;IAC9C,0BAA0B;IAC1B,gDAAgD;IAChD,MAAM,QAAQ,GAAG;QACf,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,WAAW,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC;QAC1C,8BAA8B;QAC9B,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC;QAC5B,2BAA2B;KAC5B,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAEjB,sBAAsB;IACtB,0BAA0B;IAC1B,8CAA8C;IAC9C,yBAAyB;IACzB,gDAAgD;IAChD,MAAM,WAAW,GAAG;QAClB,kBAAkB;QAClB,yBAAyB;QACzB,UAAU;QACV,sBAAsB;KACvB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAEjB,SAAS,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC;QAChC,MAAM;QACN,SAAS,EAAE,UAAU;QACrB,cAAc,EAAE,CAAC,sBAAsB,EAAE,cAAc,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;QACvE,WAAW;QACX,UAAU,EAAE,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;QACzD,QAAQ;KACT,CAAC,CAAC;IAEH,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,SAAS,GAAG,IAAI,CAAC;AACnB,CAAC;AASD,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAA2B;IAC3D,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACtC,MAAM,QAAQ,GAAG,MAAM,WAAW,EAAE,CAAC;IAErC,wCAAwC;IACxC,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,OAAO,IAAI,SAAS,CAAC,CAAC;IAEnE,wBAAwB;IACxB,kDAAkD;IAClD,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,KAAK,CAAC,QAAQ,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"agent-creator.js","sourceRoot":"","sources":["../src/agent-creator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EACL,KAAK,EACL,QAAQ,EACR,WAAW,IAAI,cAAc,GAE9B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EACjD,UAAU,EACV,sBAAsB,EAAE,kBAAkB,EAAE,iBAAiB,EAC7D,sBAAsB,EAAE,2BAA2B,EACnD,yBAAyB,EAAE,8BAA8B,GAC1D,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,wDAAwD;AAExD,IAAI,MAAM,GAAiB,IAAI,CAAC;AAEhC,uCAAuC;AACvC,MAAM,MAAM,GAAG,UAAU,CAAC;AAE1B,MAAM,CAAC,KAAK,UAAU,QAAQ;IAC5B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAElC,qBAAqB;IACrB,oBAAoB;IACpB,2BAA2B;IAC3B,8CAA8C;IAC9C,0BAA0B;IAC1B,gDAAgD;IAChD,MAAM,QAAQ,GAAG;QACf,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,WAAW,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC;QAC1C,8BAA8B;QAC9B,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC;QAC5B,2BAA2B;KAC5B,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAEjB,sBAAsB;IACtB,0BAA0B;IAC1B,8CAA8C;IAC9C,yBAAyB;IACzB,gDAAgD;IAChD,MAAM,WAAW,GAAG;QAClB,kBAAkB;QAClB,yBAAyB;QACzB,UAAU;QACV,sBAAsB;KACvB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAEjB,MAAM,GAAG,IAAI,KAAK,CAAC;QACjB,MAAM;QACN,SAAS,EAAE,UAAU;KACtB,CAAC,CAAC,GAAG,CACJ,GAAG,QAAQ,CAAC;QACV,cAAc,EAAE,CAAC,sBAAsB,EAAE,cAAc,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;QACvE,WAAW;QACX,UAAU,EAAE,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;QACzD,QAAQ;KACT,CAAC,CACH,CAAC;IAEF,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;IAEpB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC;AASD,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAA2B;IAC3D,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACtC,MAAM,KAAK,GAAG,MAAM,QAAQ,EAAE,CAAC;IAE/B,wCAAwC;IACxC,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,KAAK,EAAE,OAAO,IAAI,SAAS,CAAC,CAAC;IAEhE,wBAAwB;IACxB,kDAAkD;IAClD,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,KAAK,CAAC,QAAQ,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/cli",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "AI-ZEN CLI - interactive conversation terminal with file tools and draft recovery",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,7 +21,7 @@
   "license": "MIT",
   "dependencies": {
     "@ai-zen/agents-core": "^4.3.0",
-    "@ai-zen/agents-sdk": "^0.11.0",
+    "@ai-zen/agents-sdk": "1.0.0-alpha.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "chalk": "^5.3.0",
     "dayjs": "^1.11.21",