xuanzhu 0.2.0 → 0.3.0

package/README.md

@@ -32,6 +32,16 @@ xzh                 # 启动
 - **默认全自动**：`autoApprove` 默认为 `true`，**所有工具都直接执行、不做任何确认** —— 包括写文件、执行命令、读取工作区之外的文件，以及读取凭据类文件（`~/.ssh`、`.env`、`~/.xzh/config.json` 等）。开箱即用，不打断。`/auto off` 可切换为写文件与执行命令逐项确认。
   - 如果希望读取凭据类文件时确认一次（防止密钥被读进上下文后转交给模型服务商），把 `confirmSensitiveRead` 设为 `true`，默认关闭。
 - **多轮自主执行**：自动串联工具调用完成任务，可随时 `Ctrl+C` 中断。
+- **任务拆分**：3 步以上的复杂任务会先用 `todo_write` 列出计划并逐步更新，
+  顶部信息区实时显示进度条（`任务 2/5` 与当前进行项）。
+- **子代理协作（可并行）**：需要大范围调研（跨多个文件 / 目录 / 命名约定）时，用 `task`
+  派生 `code-explorer` 子代理独立完成，**只把结论带回主对话** —— 中间过程不会挤占主上下文。
+  一轮里并列发出多个 `task` 时会**并发执行**（默认最多 4 个，见 `maxParallelAgents`）。
+  子代理定义集中在 `src/subagents/`，可继续扩展。
+- **长期记忆自动精简**：`MEMORY.md` 只追加、会越写越长；**达到阈值（默认 6000 字符）
+  自动触发** —— 先去重，仍超限就裁剪最旧的条目（最新结论优先保留），无需模型同意。
+- **图片输入**：`Ctrl+V`（或 `/image`）读取系统剪贴板里的图片作为附件发给模型，
+  也支持拖拽图片文件路径；Linux / Windows / macOS 均可用。
 
 ## 环境要求
 
@@ -145,7 +155,7 @@ xzh
 | `xzh config edit` | 使用 `nano` 编辑配置文件 |
 | `xzh config path` | 打印配置文件路径 |
 | `xzh config init` | 生成默认配置文件 |
-| `xzh setup` | 检查并自动安装技能依赖（playwright / officecli 等） |
+| `xzh setup` | 检查并自动安装依赖（玄猪自身 + 技能：playwright / officecli / 剪贴板工具等） |
 | `xzh --help` | 查看帮助 |
 | `xzh --version` | 查看版本 |
 
@@ -173,6 +183,8 @@ XZH_HOME=/path/to/dir xzh          # 改用 /path/to/dir/config.json
   "temperature": 0.2,
   "maxToolRounds": 200,
   "autoApprove": true,
+  "memoryMaxChars": 6000,
+  "maxParallelAgents": 4,
   "intent": { "enabled": false },
   "providers": {
     "deepseek": {
@@ -206,6 +218,7 @@ xzh model all                          # 查看所有内置可用模型
 xzh model add openai gpt-4o 20         # 新增（权重 20）
 xzh model weight openai/gpt-4o 5       # 调整权重
 xzh model context openai/gpt-4o 128000 # 调整上下文窗口（留空则自动推断）
+xzh model vision openai/gpt-4o on      # 标注支持图片输入（推断不出来时用）
 xzh model remove openai/gpt-4o         # 删除（id / 模型名 / 序号均可）
 xzh model reset                        # 全部恢复默认权重
 ```
@@ -294,7 +307,10 @@ API Key 也可以来自环境变量，优先级低于配置文件：
 | `list_skills` | 列出玄猪可用的全部技能 | 否 |
 | `load_skill` | 加载指定技能的完整指南 | 否 |
 | `memory_read` | 读取项目记忆（长期记忆 + 最近日志） | 否 |
-| `memory_write` | 写入项目记忆（长期记忆 / 当日日志） | 否 |
+| `memory_write` | 写入项目记忆（长期记忆 / 当日日志），长期记忆超限时自动精简 | 否 |
+| `memory_compact` | 用精简后的完整内容重写长期记忆（语义压缩） | 否 |
+| `todo_write` | 创建 / 更新任务列表（每次提交完整列表） | 否 |
+| `task` | 派生子代理（默认 `code-explorer`）执行子任务，只返回结论；一轮内多个调用**并行**执行 | 否 |
 | `read_file` | 读取文件（带行号，支持偏移与行数限制） | 否 |
 | `list_dir` | 列出目录内容 | 否 |
 | `glob` | 按 `**` / `*` / `?` 模式查找文件 | 否 |
@@ -303,6 +319,101 @@ API Key 也可以来自环境变量，优先级低于配置文件：
 | `edit_file` | 精确文本替换 | 是 |
 | `bash` | 执行 shell 命令 | 是 |
 
+## 任务拆分与子代理
+
+**任务拆分**：任务需要 3 步以上、或用户一次提出多项要求时，玄猪会先用 `todo_write`
+把计划写成结构化列表，每完成一步就更新状态。列表显示在顶部信息区（`任务 2/5` +
+进行中项），比"它说自己做到哪了"更可靠。
+
+**子代理**：`task` 工具会**新建一个独立的 Agent 实例**去完成一件子任务，只有最终结论
+回到主对话。用途是把"翻几十个文件"这类调研的中间过程隔离出去，避免主上下文被塞满。
+
+**并行执行**：一轮回复里并列发出**多个** `task` 调用时，这些子代理会**并发运行**，
+结果按原调用顺序回灌 —— 多路调研的总耗时取决于最慢的一路，而不是各条相加。
+并发上限由 `maxParallelAgents`（默认 `4`）控制，设为 `1` 即退化为串行；硬上限 16。
+有先后依赖的任务应分轮发起（下一轮才能看到上一轮结论）。
+
+> 只有声明了 `parallelSafe` 的工具会进入并行批次（目前仅 `task`）。写文件、编辑、
+> 执行命令这类工具有副作用且可能互相依赖，始终按顺序串行执行，不会被并行化。
+
+内置一个子代理，通过 `subagent_name` 指定（默认即它）：
+
+| 子代理 | 能力 | 何时用 |
+| --- | --- | --- |
+| `code-explorer` | **只读**（`read_file` / `list_dir` / `glob` / `grep` / `list_skills` / `load_skill`） | 跨多个文件、目录或命名约定的搜索；单次 `read_file` / `grep` 覆盖不了的探索 |
+
+`task` 的参数：
+
+| 参数 | 说明 |
+| --- | --- |
+| `description` | 子任务的一句话说明（界面显示 + 结果摘要） |
+| `prompt` | 交给子代理的完整任务描述。**子代理看不到主对话**，必须自包含；`code-explorer` 还应在其中写明探索力度（`quick` / `medium` / `very thorough`） |
+| `subagent_name` | 要派生的子代理名称，默认 `code-explorer` |
+
+约束：子代理恒不提供 `task`（禁止无界递归）、`todo_write` 与 `memory_write` / `memory_compact`
+（任务列表与记忆由主代理统一维护）。它的工具活动以 `[code-explorer: <任务说明>]` 前缀显示在
+输出区 —— 并行时会交错，前缀里的任务说明用于区分是谁在输出；危险操作确认仍会转发给你
+（并行时多个确认会**排队**逐个弹出，不会互相覆盖）。
+
+> **扩展新的子代理**：在 `src/subagents/` 下实现 `SubAgentDefinition`（名称、给主代理看的
+> 描述、工具白名单、系统提示词），再加进 `src/subagents/index.ts` 的 `SUBAGENTS` 数组即可。
+> `task` 的参数枚举、可用工具与提示词都会自动跟随，无需改别处。
+
+**触发时机不需要配置**：`task` 与其他工具一样**每次请求都会发给模型**（没有开关）。
+但只靠提示词写「大范围调研时用它」是不够的 —— 模型判定不了「多大算大」，实测就是不调用。
+因此除了把触发条件写成可判定的阈值（"预计要读 3 个以上文件 / 要反复 glob grep"），还加了一道
+**确定性提醒**：当本轮只读调研累计达到 **8 次**或 **4 万字符**时，会在工具结果末尾追加一条
+`[系统提醒]`（整轮只提醒一次，已在用子代理时不提醒），把「该委托了」直接摆到模型面前。
+
+想确认某个工具到底有没有发出去：`/tools` 会列出本轮发给模型的全部工具及其说明。
+
+**长期记忆自动精简**：`MEMORY.md` 只追加、会无界增长，而它每次启动都要注入提示词。
+因此**达到 `memoryMaxChars`（默认 6000）就自动触发**，不需要模型同意：
+
+- 先去除正文完全相同的重复块（无损）；
+- 仍超限则**从最旧的块开始裁剪**（最新的结论优先保留）；
+- 触发时机：会话启动、`/switch` 切换目录、以及每次 `memory_write`（scope=long）之后；
+  精简结果会在输出区提示（如"长期记忆已自动精简（去除 2 条重复记录、裁剪 1 条最旧记录）"）。
+- 设 `memoryMaxChars: 0` 表示不限制长度（此时只去重、不裁剪）。
+- 自动裁剪无法解决"单条记录本身过长"（再裁就整条丢），这种情况会在提示词里要求模型用
+  `memory_compact` 做语义压缩。
+
+## 图片输入（Ctrl+V）
+
+在输入框按 **Ctrl+V**（或 `/image`、`/paste`）会把**系统剪贴板里的图片**加为本轮附件，
+输入框显示 `[图片1]` 占位；回车连同正文一起发给模型。退格删掉占位即取消该图片。
+
+> **为什么不能"直接右键粘贴"**：终端与程序之间只有字节流，粘贴只能传**文本** ——
+> 剪贴板里只有图片时，绝大多数终端在粘贴时**什么都不发送**，程序无从感知。
+> 所以改由玄猪**主动读取系统剪贴板**。
+
+| 平台 | 用到的工具 | 缺依赖时 |
+| --- | --- | --- |
+| Linux | `wl-paste`（Wayland，`wl-clipboard` 包）或 `xclip`（X11） | **自动安装**（弹一次确认；支持 apt / dnf / yum / pacman / zypper / apk） |
+| Windows | 内置 PowerShell | 无需安装 |
+| macOS | `pngpaste`，否则内置 `osascript` | 无需安装（有内置退路） |
+
+Linux 上缺少剪贴板工具时，Ctrl+V 会**弹出确认框并自动安装**（会临时离开界面，以便输入 sudo
+密码，装完自动回到界面）。也可以提前一次性装好：`xzh setup`（同时覆盖玄猪自身依赖与技能 CLI）。
+
+- 终端把 Ctrl+V 当成自己的粘贴键时（如 Windows Terminal），`\x16` 到不了玄猪 —— 改用 `/image`。
+- 剪贴板里没有图片时会**退化为普通文本粘贴**，不会吞掉内容。
+- **拖拽图片文件到终端**同样支持：只要某一行**只有一个图片文件路径**，提交时会自动转成附件。
+  这条通路不依赖任何终端协议，覆盖面最广。
+- 单张图片上限 **5 MB**；超过则忽略并提示。
+- **模型必须支持视觉**：`glm-4v` / `qwen-vl` / `gpt-4o` / `claude` / `gemini` 等。
+  `xzh model list` 会给支持的模型标上「视觉」；推断不出来时用
+  `xzh model vision <id> on` 手动标注。模型不支持时玄猪会**拒绝附加**，
+  而不是发出去换一个 400（那会把整轮正文一起作废）。
+- **自定义端点默认按"支持图片"处理**：`custom` provider 的模型名由你自己填，
+  按名字推断必然失效 —— 若也拒绝，等于"自定义模型永远用不了图片"。
+  若该端点其实不支持，请求会被服务端拒绝，此时玄猪会**识别出来并自动去掉图片重试一次**，
+  你的正文不会被作废，并提示你 `xzh model vision <id> off` 彻底关掉（避免每次都白试一次）。
+  `xzh model add` 会就这一点询问一次，也可以用第 5 个位置参数直接指定：
+  `xzh model add custom my-model 10 128000 off`。
+- 图片只在**本轮**随请求发送；历史里的旧图片会自动降级为 `[图片已省略：image/png]`，
+  避免 base64 把上下文撑爆。
+
 ## 项目目录（.xuanzhu/）
 
 首次在某个项目中运行 `xzh` 时，会在项目根自动创建 `.xuanzhu/`，用于保存**项目级记忆与规则**
@@ -320,6 +431,11 @@ API Key 也可以来自环境变量，优先级低于配置文件：
 - 需要更多历史时调用 `memory_read`；**每完成一件实质工作后**必须调用 `memory_write` 记录结论
   （技术方案、项目约定、踩过的坑、重要发现）。这条要求同时写在系统提示词的「核心原则」里，
   明确要求**在给出最终答复前先写记忆** —— 此前措辞偏弱（「可调用」），实测几乎不会触发
+- 长期记忆是**只追加**的，长期使用会越写越长，而它每次启动都要注入提示词（节选 1500 字符），
+  过长会让重要结论被截断。因此**达到 `memoryMaxChars`（默认 6000 字符）即自动触发精简**
+  （无需模型发起，时机见上面的"长期记忆自动精简"）：先去重，仍超限则裁剪最旧的块。
+- 只有当**单条记录本身就超过上限**（自动裁剪删无可删）时，提示词才会要求模型
+  `memory_read` 读全文、再用 `memory_compact` 重写为精简版本（合并同主题、删除过时条目）。
 - `.xuanzhu` **始终**位于当前项目路径之下，**不做任何向上查找**：在 `/a/b/c` 工作就只用
   `/a/b/c/.xuanzhu`，即使 `/a` 或 `/a/b` 下已有 `.xuanzhu` 也不会复用
 - **启动时**与 **`/switch` 切换目录时**，若该目录下尚无 `.xuanzhu`，会自动创建
@@ -352,7 +468,8 @@ API Key 也可以来自环境变量，优先级低于配置文件：
 上表中的 CLI 由玄猪负责安装，**无需用户单独安装**：
 
 - 在对话中加载技能时（`load_skill`），玄猪会先检测依赖；若缺失，请求一次确认后自动安装并验证。
-- 也可主动运行 `xzh setup`，一次性检查并安装所有内置技能的依赖。
+- 也可主动运行 `xzh setup`，一次性检查并安装**玄猪自身依赖（剪贴板工具）与全部内置技能的依赖**。
+  `xzh setup` 把终端交给安装命令，因此 `sudo` 能正常提示输入密码。
 
 ### 自定义技能
 
@@ -447,7 +564,7 @@ description: 一句话说明该技能的用途与适用场景
 kitty / Ghostty 会把该 xterm 兼容序列映射成「所有按键都用转义码上报」而破坏普通输入，
 故玄猪对这两类终端不发送请求，请改用 `Alt+Enter` 或在终端侧自行配置。
 
-界面内命令：`/help`、`/clear`、`/copy [N|all]`、`/mouse`、`/reset`、`/cwd`、`/switch <目录>`、`/term`、`/model`、`/auto [on|off]`、`/intent [on|off]`、`/exit`。
+界面内命令：`/help`、`/clear`、`/tools`、`/image`、`/copy [N|all]`、`/mouse`、`/reset`、`/cwd`、`/switch <目录>`、`/term`、`/model`、`/auto [on|off]`、`/intent [on|off]`、`/exit`。
 
 ### 选中与复制