jinzd-ai-cli 0.1.21 → 0.1.23

package/CLAUDE.md

@@ -52,7 +52,7 @@ src/
 │   └── manager.ts                  # McpManager（多服务器管理，工具发现与注册，MCP→Tool 转换）
 └── tools/
     ├── types.ts                    # ToolDefinition / ToolCall / ToolResult / DangerLevel / getDangerLevel
-    ├── registry.ts                 # ToolRegistry（注册全部内置工具，共14个）
+    ├── registry.ts                 # ToolRegistry（注册全部内置工具，共15个）
     ├── executor.ts                 # ToolExecutor（确认逻辑 + printToolCall/printToolResult）
     └── builtin/
         ├── bash.ts                 # bash 工具（Windows: PowerShell + Buffer→UTF-8；Unix: $SHELL）
@@ -62,7 +62,8 @@ src/
         ├── run-interactive.ts      # run_interactive 工具（spawn 直连可执行文件，stdin_lines 依次输入）
         ├── ask-user.ts             # ask_user 工具（agentic 循环中向用户提问，等待文本回答）
         ├── write-todos.ts          # write_todos 工具（任务拆解与进度跟踪，终端实时渲染）
-        └── google-search.ts        # google_search 工具（Google Custom Search API 搜索网页）
+        ├── google-search.ts        # google_search 工具（Google Custom Search API 搜索网页）
+        └── spawn-agent.ts          # spawn_agent 工具（独立子代理 agentic 循环 + SubAgentExecutor）
 ```
 
 ## 常用命令
@@ -205,6 +206,7 @@ AICLI_NO_STREAM          设为 1 禁用流式输出
 | `ask_user` | safe | AI 在 agentic 循环中向用户提问，等待文本回答后继续执行 |
 | `write_todos` | safe | AI 拆解复杂任务为子任务列表，终端实时渲染进度（pending/in_progress/completed） |
 | `google_search` | safe | Google Custom Search API 搜索网页，需配置 API Key + Search Engine ID (cx) |
+| `spawn_agent` | safe | 委派独立子代理执行特定任务（隔离对话 + agentic 循环，write 自动确认，destructive 阻止） |
 | `mcp__*` | safe | MCP 服务器暴露的动态工具（命名格式：`mcp__<serverId>__<toolName>`） |
 
 ### 危险级别与确认机制
@@ -308,7 +310,7 @@ const stdinLines = Array.isArray(rawStdin) ? rawStdin.map(String)
 - [x] **`/compact` 上下文压缩**（2026-02-25）：调用当前 provider 生成对话摘要，替换 session.messages 前 N 条为 user/assistant 摘要对，保留最近 4 条。`session.compact()` 方法 + `repl.compactSession()` + `/compact [instruction]` 命令。
 - [x] **Headless 非交互模式（`-p` flag）**（2026-02-25）：`echo "..." | aicli -p "review"` 单轮对话后退出，`--json` 输出 `{content,provider,model,usage}`，支持 stdin 内容拼接，解锁 CI/CD 脚本场景。
 - [x] **Plan Mode 规划模式**（2026-02-25）：`/plan` 进入只读规划（AI 只能用只读工具白名单），提示符显示 `[PLAN]` 黄色标记，`/plan execute` 切回正常模式，`/plan exit` 放弃计划。
-- [ ] **Sub-agents 系统**：`spawn_agent` 工具在子进程中运行独立 agentic 循环，支持并行任务分解。
+- [x] **Sub-agents 系统**（2026-02-27）：`spawn_agent` 工具在同进程中运行独立 agentic 循环。子代理拥有隔离对话、过滤后的工具集（SUBAGENT_ALLOWED_TOOLS）、自动确认 write 操作、阻止 destructive 操作。SubAgentExecutor 带前缀终端输出。
 
 ### P1 — 重要差距
 - [ ] **Agent Skills 系统**：可复用的专业技能包（`.aicli/skills/`）
@@ -333,6 +335,41 @@ const stdinLines = Array.isArray(rawStdin) ? rawStdin.map(String)
 - [ ] **web_fetch DNS 解析时 SSRF 防护**：当前只检查 URL hostname 字符串，若 hostname 是域名（非裸 IP）则未检查其解析后的 IP 是否为私有地址。需在发起请求后对实际连接 IP 做二次校验（复杂，低频风险）。
 - [ ] **`persistentCwd` 全局状态**：bash 工具的当前工作目录是模块级全局变量，多 session 并发时可能串扰。现阶段单 session REPL 无影响，GUI 多会话扩展时需重构为 per-session 状态。
 
+## 本轮开发完成记录（2026-02-27，v0.1.21 → v0.1.22）
+
+### 新增功能：Sub-Agent 子代理系统（`spawn_agent` 工具）
+
+**背景**：P0 路线图最后一个核心功能。允许主 AI 将复杂子任务委派给独立子代理执行，子代理拥有隔离对话和 agentic 循环。
+
+**实现**：
+- 新增 `src/tools/builtin/spawn-agent.ts`：
+  - `spawnAgentContext` 共享上下文对象（遵循 streamToFileContext 模式，由 repl.ts 注入）
+  - `SubAgentExecutor` 类：子代理专用工具执行器，write 自动确认、destructive 直接阻止、带 `  ┃ ` 前缀的嵌套终端输出
+  - 独立 agentic 循环：chatWithTools → executeAll → buildToolResultMessages，最多 max_rounds 轮
+  - 子代理 system prompt：继承父级 system prompt + 子代理模式说明（任务规则、工具限制）
+- `src/core/constants.ts`：新增 `SUBAGENT_DEFAULT_MAX_ROUNDS`(10) / `SUBAGENT_MAX_ROUNDS_LIMIT`(15) / `SUBAGENT_ALLOWED_TOOLS`(11个工具白名单)
+- `src/tools/registry.ts`：新增 `unregister(name)` 方法（供子代理创建过滤工具集）；注册 `spawnAgentTool`
+- `src/tools/types.ts`：`getDangerLevel` 中 `spawn_agent` → `safe`
+- `src/repl/repl.ts`：handleChatWithTools 中注入 spawnAgentContext（provider/model/systemPrompt/modelParams/configManager）
+
+**工具参数**：
+- `task`（string, required）：子代理任务描述，包含所有必要上下文
+- `max_rounds`（number, optional, default 10, 限制 1-15）：最大工具调用轮次
+
+**安全设计**：
+- 递归防护：子代理工具集不含 `spawn_agent`
+- 用户交互隔离：子代理无 `ask_user`、`save_memory`、`save_last_response`
+- 破坏性操作阻止：`destructive` 级别工具调用直接返回错误
+- 写操作自动确认：`write` 级别无需用户确认（主 AI 已明确委派）
+- 轮次上限：max_rounds 限制在 1-15，防止无限循环
+
+**终端输出**：子代理工具调用和结果使用 `  ┃ ` 前缀 + 箱形边框（┏/┗），清晰区分父级与子代理输出
+
+### 架构变更
+- `src/repl/renderer.ts`：`/about` 工具计数 14 → 15，新增 `spawn_agent` 条目和 Sub-Agent 特性条目
+
+---
+
 ## 本轮开发完成记录（2026-02-25，v0.1.18 → v0.1.20）
 
 ### Bug 修复：Kimi XML 伪工具调用（v0.1.19）