@ai-zen/cli 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [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
+
+### 🚀 新功能
+
+- **Skill 子 Agent 纳入子 Agent 上下文护栏与流式渲染** — 依托 SDK 0.11.0 将 `call_skill_sub_agent` 统一到 `AgentToolLazy`，技能子 Agent 自此与常规 SubAgent 共享同一套委派边界（`onSubAgentStart` / `onSubAgentEnd` 钩子与 `sub-agent-start` / `sub-agent-end` 事件）。故 0.8.0 引入的 `SubAgentGuardInstallerPlugin` 与子 Agent 流式渲染**自动覆盖**该路径，本次 CLI 无源码改动（0.8.0 CHANGELOG「覆盖范围」中「技能子 Agent 不在覆盖范围」的说明随之失效）
+
+### ⚠️ 依赖升级
+
+- **`@ai-zen/agents-core` 升至 `^4.3.0`、`@ai-zen/agents-sdk` 升至 `^0.11.0`** — `src/version.ts` 由实际安装版本读取，版本横幅随之显示 core `4.3.0` / sdk `0.11.0`。SDK 0.11.0 的破坏性变更（`createCallSkillSubAgentTool` 移除第三参 `provider`）仅影响直接调用该工厂函数的代码；CLI 经 `Provider.instantiate` 间接使用，无需适配
+
+### ✅ 测试
+
+- 沿用既有 9 文件 / 74 用例，全部通过；`tsc --noEmit` 与 `npm run build`（`0.8.1`）均通过
+
 ## [0.8.0] - 2026-09-28
 
 ### 🚀 新功能

package/README.md

@@ -84,7 +84,7 @@ When the API response's `usage.prompt_tokens` exceeds the model's `maxContextTok
 
 You can also manually trigger a migration at any time by typing `/migrate` in the conversation — no need to wait for the token limit. Both automatic and manual migration delegate to the SDK's `TaskMigrationService`, so the handoff document is always produced consistently.
 
-The same context guard also applies to **sub-agents**: at each delegation boundary (`onSubAgentStart`) the CLI installs the same `ContextGuardPlugin` (same `maxTokens`) onto the newly built sub-agent, so a delegated sub-agent is interrupted as soon as its context exceeds the hard limit. This is transparent — a normally-running sub-agent is unaffected.
+The same context guard also applies to **sub-agents**: at each delegation boundary (`onSubAgentStart`) the CLI installs the same `ContextGuardPlugin` (same `maxTokens`) onto the newly built sub-agent, so a delegated sub-agent (including the Skill sub-agent created by `call_skill_sub_agent`) is interrupted as soon as its context exceeds the hard limit. This is transparent — a normally-running sub-agent is unaffected.
 
 The migration prompt template includes:
 - **Conversation Breakpoint** — Last user/AI exchange verbatim
@@ -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 |
@@ -244,11 +245,11 @@ In addition to built-in tools, the SDK provides 5 dynamic loading tools that are
 
 Tools are assembled in three phases by the SDK's `Provider` 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
 
-Each Agent has independent permissions — no inheritance between parent Agent and SubAgent. The only exception is the temporary Skill sub-agent (created by `call_skill_sub_agent`), which inherits the caller's permissions as a transient conversation proxy rather than an independent entity.
+Each Agent has independent permissions — no inheritance between parent Agent and SubAgent. The only exception is the temporary Skill sub-agent (created by `call_skill_sub_agent`), which reuses the caller's tool set without a second permission pass, as a transient conversation proxy rather than an independent entity.
 
 ## Permission Model
 

package/README.zh.md

@@ -84,7 +84,7 @@ zen 你好，请介绍一下你自己。
 
 你也可以在对话中随时输入 `/migrate` 手动触发迁移，而无需等待 token 超限。手动与自动迁移均委托给 SDK 的 `TaskMigrationService`，交接文档生成始终一致。
 
-同样的上下文护栏也作用于**子 Agent**：每次委派边界（`onSubAgentStart`）CLI 都会把同一个 `ContextGuardPlugin`（同一 `maxTokens`）安插到新建的子 Agent 上，因此被委派的子 Agent 在上下文超出硬上限时同样会被中断。该过程是透明的，正常运行的子 Agent 不受影响。
+同样的上下文护栏也作用于**子 Agent**：每次委派边界（`onSubAgentStart`）CLI 都会把同一个 `ContextGuardPlugin`（同一 `maxTokens`）安插到新建的子 Agent 上，因此被委派的子 Agent（含 `call_skill_sub_agent` 创建的技能子 Agent）在上下文超出硬上限时同样会被中断。该过程是透明的，正常运行的子 Agent 不受影响。
 
 迁移提示词模板包含：
 - **对话断点** — 最后一段对话原文引用
@@ -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` | 批量编辑文本 |
@@ -244,11 +245,11 @@ CLI 提供 19 个内置工具，由 `@ai-zen/agents-sdk` 实现。工具可用
 
 工具装配由 SDK 的 `Provider` 能力管线管理，分为三个阶段：
 
-1. **发现** — 扫描文件系统获取内置工具、用户工具、SubAgent、Skill 和 MCP 服务器。19 个内置工具全部无条件发现（此阶段不做过滤）
+1. **发现** — 扫描文件系统获取内置工具、用户工具、SubAgent、Skill 和 MCP 服务器。20 个内置工具全部无条件发现（此阶段不做过滤）
 2. **过滤** — 应用权限（`allow`/`deny`）、安全排除（递归保护），以及各工具自声明的 `isAvailable(config, definition)`（在模型已知的构建阶段判断可用性；如 `viewImage` 仅视觉模型、`generateImage` 需配置 `defaultImageModel`）
 3. **实例化** — 将过滤后的名称映射为 `Tool` 实例，注册动态加载器
 
-每个 Agent 拥有独立的权限配置，父 Agent 与 SubAgent 之间不继承权限。唯一的例外是 `call_skill_sub_agent` 创建的临时 Skill 子 Agent——它是临时的对话分身而非独立实体，因此继承调用者的权限。
+每个 Agent 拥有独立的权限配置，父 Agent 与 SubAgent 之间不继承权限。唯一的例外是 `call_skill_sub_agent` 创建的临时 Skill 子 Agent——它是临时的对话分身而非独立实体，因此沿用调用者的工具能力（不再走第二遍权限过滤）。
 
 ## 权限模型
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/cli",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "AI-ZEN CLI - interactive conversation terminal with file tools and draft recovery",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,8 +20,8 @@
   "author": "LZQCN",
   "license": "MIT",
   "dependencies": {
-    "@ai-zen/agents-core": "^4.2.0",
-    "@ai-zen/agents-sdk": "^0.10.0",
+    "@ai-zen/agents-core": "^4.3.0",
+    "@ai-zen/agents-sdk": "^0.12.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "chalk": "^5.3.0",
     "dayjs": "^1.11.21",