xuanzhu 0.4.1 → 0.4.3

package/README.md

@@ -40,8 +40,10 @@ xzh                 # 启动
   测试日志同样不进主上下文。
   一轮里并列发出多个 `task` 时会**并发执行**（默认最多 4 个，见 `maxParallelAgents`）。
   子代理定义集中在 `src/subagents/`，可继续扩展。
-- **长期记忆自动精简**：`MEMORY.md` 只追加、会越写越长；**达到阈值（默认 6000 字符）
-  自动触发** —— 先去重，仍超限就裁剪最旧的条目（最新结论优先保留），无需模型同意。
+- **长期记忆按主题整理**：`MEMORY.md` 是**结论库**而不是流水账 —— 同一主题的新结论并进已有
+  小节（`memory_compact`），只写稳定事实 + 依据（`file::func` / 命令）+ 原因与解法，细节留在
+  项目文档里只留指针。**达到阈值（默认 12000 字符）自动精简**：先去重，仍超限就裁剪最旧的
+  **追加块**（最新结论优先保留）；按主题整理的稳定小节不会被自动删，那种情况会要求模型压缩。
 - **图片输入**：`Ctrl+V`（或 `/image`）读取系统剪贴板里的图片作为附件发给模型，
   也支持拖拽图片文件路径；Linux / Windows / macOS 均可用。
 - **手机设备桥**：把脚本推到手机上的 **AutoJs6** / AutoX.js 运行并回收日志，等价于 VSCode 插件的
@@ -129,10 +131,10 @@ npm unlink -g xuanzhu && npm i -g xuanzhu
 ## 快速开始
 
 ```bash
-# 1. 配置模型与服务商（交互式，可添加多个模型并设置调用权重）
+# 1. 配置模型与服务商（交互式，可添加多个模型）
 xzh model
 
-# 2. 启动玄猪（自动使用权重最高的模型）
+# 2. 启动玄猪（默认使用上次用过的模型）
 xzh
 ```
 
@@ -148,14 +150,13 @@ xzh
 | --- | --- |
 | `xzh` | 在当前目录启动全屏交互界面 |
 | `xzh <目录>` | 在指定项目目录启动，例如 `xzh /home` |
-| `xzh model` | 交互式管理多模型（新增 / 删除 / 调整权重 / 查看全部） |
-| `xzh model list` | 列出**已配置**的模型与调用权重 |
+| `xzh model` | 交互式管理多模型（新增 / 删除 / 查看全部） |
+| `xzh model list` | 列出**已配置**的模型（按回退顺序） |
 | `xzh model all` | 列出**所有内置可用**的模型（按服务商分组，标注已配置项） |
-| `xzh model add <provider> <model> [权重]` | 新增模型（默认权重 `10`） |
+| `xzh model add <provider> <model> [上下文窗口] [on\|off]` | 新增模型（末尾 `on`/`off` = 是否支持图片输入） |
 | `xzh model remove <id\|序号>` | 删除模型 |
-| `xzh model weight <id\|序号> <权重>` | 调整模型的调用权重 |
 | `xzh model context <id\|序号> <大小>` | 调整上下文窗口（token，如 `128000`） |
-| `xzh model reset` | 把全部模型权重恢复为默认值 |
+| `xzh model vision <id\|序号> <on\|off>` | 标注是否支持图片输入 |
 | `xzh config` | 查看当前配置（API Key 脱敏） |
 | `xzh config edit` | 使用 `nano` 编辑配置文件 |
 | `xzh config path` | 打印配置文件路径 |
@@ -191,13 +192,13 @@ XZH_HOME=/path/to/dir xzh          # 改用 /path/to/dir/config.json
   "provider": "deepseek",
   "model": "deepseek-chat",
   "models": [
-    { "id": "deepseek/deepseek-chat", "provider": "deepseek", "model": "deepseek-chat", "weight": 10 },
-    { "id": "openai/gpt-4o", "provider": "openai", "model": "gpt-4o", "weight": 6 }
+    { "id": "deepseek/deepseek-chat", "provider": "deepseek", "model": "deepseek-chat" },
+    { "id": "openai/gpt-4o", "provider": "openai", "model": "gpt-4o" }
   ],
   "temperature": 0.2,
   "maxToolRounds": 200,
   "autoApprove": true,
-  "memoryMaxChars": 6000,
+  "memoryMaxChars": 12000,
   "maxParallelAgents": 4,
   "intent": { "enabled": false },
   "providers": {
@@ -209,35 +210,41 @@ XZH_HOME=/path/to/dir xzh          # 改用 /path/to/dir/config.json
 }
 ```
 
-> 旧版配置（只有 `provider` / `model`、没有 `models`）依然可用：会被视为一个权重为 `10` 的模型。
+> 旧版配置（只有 `provider` / `model`、没有 `models`）依然可用：会被视为唯一的一个模型。
+> 旧配置里的 `weight` / `decayed` 字段已废弃，读取时会被忽略、下次保存时自动清掉。
 
-### 多模型与调用权重
+### 多模型与自动回退
 
-`models` 可配置多个模型，每个模型带一个**调用权重**（默认 `10`）：
+`models` 可配置多个模型，**列表顺序就是优先级**（没有权重）：
 
 | 行为 | 说明 |
 | --- | --- |
-| 启动选择 | 优先加载**权重最高**的模型 |
-| 调用失败 | 该模型权重 **-1**（`Ctrl+C` 主动中断不算失败） |
-| 自动降级 | 若还有**尚未尝试过**的可用模型，切换到权重最高的那个并重试（单次请求内每个模型最多尝试一次，最多切换 3 次） |
-| 不做空转 | 只有一个模型（或权重耗尽重置回它自己）时**不重试**，直接报错并附上当前模型信息 |
-| 权重耗尽 | 当**所有模型权重都为 0** 时，在终端警告并把全部权重重置回 `10` |
-| 配置错误不降权 | 密钥无效 / 无权限 / 模型名或端点不存在时**不扣权重、不写盘**，只提示检查配置 —— 配置不改就永远失败，扣权重只会把其他可用模型一起拖下水 |
-| 上下文超限不降权 | 超出模型窗口时**收敛历史后自动重试**，也不扣权重（见上一节） |
+| 默认选择 | 使用**上次用过的**那个模型（记在 `provider` / `model` 里，随每次切换更新） |
+| 上次那个不在了 | 退回列表**第一项**（被删除、或配置里没有记录） |
+| 调用失败 | 自动切换到列表里的**下一个**（走到末尾会绕回表头），单次请求内每个模型最多试一次 |
+| 全部失败 | 直到所有模型都试过才报错，并说明「已配置的模型都试过了」 |
+| 记住结果 | 每次切换都会写回配置，下次启动直接用最后成功的那个 |
+| 配置错误不回退 | 密钥无效 / 无权限 / 模型名或端点不存在时**不切换、不写盘**，只提示检查配置 —— 配置不改就永远失败，换模型只会把整条回退链白走一遍 |
+| 上下文超限不回退 | 超出模型窗口时**收敛历史后自动重试**，也不切换模型（见上一节） |
+| `Ctrl+C` / `Ctrl+D` 中断 | 不算失败，不触发回退 |
 
 ```bash
 xzh model                              # 交互式菜单
-xzh model list                         # 查看已配置的模型与权重
+xzh model list                         # 查看已配置的模型（按回退顺序，❯ 标出当前使用）
 xzh model all                          # 查看所有内置可用模型
-xzh model add openai gpt-4o 20         # 新增（权重 20）
-xzh model weight openai/gpt-4o 5       # 调整权重
+xzh model add openai gpt-4o            # 新增（追加到末尾，成为最后一道回退）
+xzh model add openai gpt-4o 128000     # 顺带指定上下文窗口
+xzh model add openai gpt-4o 128000 on  # 再顺带标注支持图片输入
 xzh model context openai/gpt-4o 128000 # 调整上下文窗口（留空则自动推断）
 xzh model vision openai/gpt-4o on      # 标注支持图片输入（推断不出来时用）
 xzh model remove openai/gpt-4o         # 删除（id / 模型名 / 序号均可）
-xzh model reset                        # 全部恢复默认权重
 ```
 
-当前使用的模型与权重会显示在界面顶部与状态栏（如 `gpt-4o w6`），降级切换时输出区会给出提示。
+想让某个模型**不参与回退**，直接 `xzh model remove` 删掉即可。当前使用的模型显示在界面顶部与状态栏，
+发生回退时输出区会给出提示。
+
+> ⚠️ `xzh model add` 的位置参数自 v0.5 起**整体前移一位**（原来的 `[权重]` 已取消）：
+> 现在是 `add <provider> <model> [上下文窗口] [on|off]`。
 
 ### 上下文窗口的作用
 
@@ -264,8 +271,8 @@ xzh model reset                        # 全部恢复默认权重
 > 保守余量必须留住（放宽反而更容易撞窗口）。
 
 若估算偏差导致仍然超限（服务端返回 `context_length_exceeded` 一类错误），玄猪会
-**把预算收敛到一半再自动重试一次**，而不会把它当成模型故障去降权或切换模型 ——
-换模型拿同样长的消息重发只会同样失败，还会白白扣掉权重。
+**把预算收敛到一半再自动重试一次**，而不会把它当成模型故障去切换模型 ——
+换模型拿同样长的消息重发只会同样失败，还会白白走一遍回退链。
 
 ### 意图分析（可选，默认关闭）
 
@@ -290,7 +297,7 @@ xzh --no-intent         # 仅本次启动强制关闭
 
 - 意图请求**不携带工具声明**，也不写入对话历史（保持主流程上下文干净）
 - 分析结果会先展示在输出区（附原始消息），便于你确认它理解对了
-- 失败或返回为空时**自动回退**为你的原始输入，不影响主流程，也不会因此降低模型权重
+- 失败或返回为空时**自动回退**为你的原始输入，不影响主流程，也不会因此触发模型回退
 - 代价：每条消息多一次模型请求（token 消耗约翻倍），故默认关闭
 
 API Key 也可以来自环境变量，优先级低于配置文件：
@@ -327,7 +334,7 @@ API Key 也可以来自环境变量，优先级低于配置文件：
 | `load_skill` | 加载指定技能的完整指南 | 否 |
 | `memory_read` | 读取项目记忆（长期记忆 + 最近日志） | 否 |
 | `memory_write` | 写入项目记忆（长期记忆 / 当日日志），长期记忆超限时自动精简 | 否 |
-| `memory_compact` | 用精简后的完整内容重写长期记忆（语义压缩） | 否 |
+| `memory_compact` | 用精简后的完整内容重写长期记忆（把新结论并入主题小节 / 语义压缩） | 否 |
 | `todo_write` | 创建 / 更新任务列表（每次提交完整列表） | 否 |
 | `task` | 派生子代理（默认 `code-explorer`）执行子任务，只返回结论；一轮内多个调用**并行**执行 | 否 |
 | `read_file` | 读取文件（带行号，支持偏移与行数限制） | 否 |
@@ -391,16 +398,21 @@ API Key 也可以来自环境变量，优先级低于配置文件：
 
 想确认某个工具到底有没有发出去：`/tools` 会列出本轮发给模型的全部工具及其说明。
 
-**长期记忆自动精简**：`MEMORY.md` 只追加、会无界增长，而它每次启动都要注入提示词。
-因此**达到 `memoryMaxChars`（默认 6000）就自动触发**，不需要模型同意：
+**长期记忆自动精简**：`MEMORY.md` 会无界增长，而它每次启动都要注入提示词。
+因此**达到 `memoryMaxChars`（默认 12000）就自动触发**，不需要模型同意：
 
 - 先去除正文完全相同的重复块（无损）；
-- 仍超限则**从最旧的块开始裁剪**（最新的结论优先保留）；
+- 仍超限则**从最旧的「追加块」开始裁剪**（`## 时间戳`，即 `memory_write` 追加的流水块，
+  最新的结论优先保留）；
+- **按主题整理的稳定小节（`## 环境与部署` 之类）不参与自动裁剪** —— 它们的顺序是重要性
+  而非时间，自动删掉等于静默抹掉项目事实；**最后一块追加块也永不丢**（往往是刚写进来、
+  还没并进主题的结论）；
 - 触发时机：会话启动、`/switch` 切换目录、以及每次 `memory_write`（scope=long）之后；
-  精简结果会在输出区提示（如"长期记忆已自动精简（去除 2 条重复记录、裁剪 1 条最旧记录）"）。
+  精简结果会在输出区提示（如"长期记忆已自动精简（去除 2 条重复记录、裁剪 1 条最旧的追加记录）"）。
 - 设 `memoryMaxChars: 0` 表示不限制长度（此时只去重、不裁剪）。
-- 自动裁剪无法解决"单条记录本身过长"（再裁就整条丢），这种情况会在提示词里要求模型用
-  `memory_compact` 做语义压缩。
+- 自动层做不到收敛时（剩下的都是主题小节，或"单条记录本身过长"），会要求模型立刻用
+  `memory_compact` 做语义压缩：`memory_write` 的返回里会直接给出提示，系统提示词也会带
+  「⚠ 长期记忆仍然过长」段落。
 
 ## 图片输入（Ctrl+V）
 
@@ -527,8 +539,8 @@ AutoX.js 那侧也可用环境变量 `XZH_DEVICE_PORT` 指定端口。
 
 | 路径 | 用途 |
 | --- | --- |
-| `.xuanzhu/memory/MEMORY.md` | 长期记忆：稳定的项目结论与约定，启动时会注入系统提示词（节选） |
-| `.xuanzhu/memory/YYYY-MM-DD.md` | 每日日志：按天追加的过程记录 |
+| `.xuanzhu/memory/MEMORY.md` | 长期记忆：**按主题整理的结论库**（稳定事实、口径与踩坑），启动时会注入系统提示词（节选） |
+| `.xuanzhu/memory/YYYY-MM-DD.md` | 每日日志：按天追加的进展与过程记录 |
 | `.xuanzhu/rules.md` | 项目规则，内容作为「项目级指令」注入系统提示词。**首次初始化时若项目根已有 `AGENTS.md`**，则写入一条「必须严格按照 `AGENTS.md` 执行」的指令（而非复制其内容）—— 这样 `AGENTS.md` 始终是唯一真实来源，你改完它模型下次读取即是新版 |
 
 记忆由玄猪自行维护：
@@ -537,11 +549,16 @@ AutoX.js 那侧也可用环境变量 `XZH_DEVICE_PORT` 指定端口。
 - 需要更多历史时调用 `memory_read`；**每完成一件实质工作后**必须调用 `memory_write` 记录结论
   （技术方案、项目约定、踩过的坑、重要发现）。这条要求同时写在系统提示词的「核心原则」里，
   明确要求**在给出最终答复前先写记忆** —— 此前措辞偏弱（「可调用」），实测几乎不会触发
-- 长期记忆是**只追加**的，长期使用会越写越长，而它每次启动都要注入提示词（节选 1500 字符），
-  过长会让重要结论被截断。因此**达到 `memoryMaxChars`（默认 6000 字符）即自动触发精简**
-  （无需模型发起，时机见上面的"长期记忆自动精简"）：先去重，仍超限则裁剪最旧的块。
-- 只有当**单条记录本身就超过上限**（自动裁剪删无可删）时，提示词才会要求模型
-  `memory_read` 读全文、再用 `memory_compact` 重写为精简版本（合并同主题、删除过时条目）。
+- 长期记忆**不是流水账**：系统提示词要求按主题分小节（`## 环境与部署`、`## 权限机制`…），
+  同一主题的新结论用 `memory_compact` 并进已有小节（`memory_write` 只用于全新主题）；
+  只写稳定结论 + 依据（`file::func` / 命令 / 表名）+ 原因与解法，危险操作标 `⚠`；
+  版本叙事与长篇论证留在项目文档里，记忆只留**指针**；过时或被推翻的内容要删掉
+- 长期记忆会越写越长，而它每次启动都要注入提示词（节选 1500 字符），过长会让重要结论被截断。
+  因此**达到 `memoryMaxChars`（默认 12000 字符）即自动触发精简**（无需模型发起，时机见上面的
+  "长期记忆自动精简"）：先去重，仍超限则裁剪最旧的**追加块**；按主题整理的稳定小节不受影响
+- 自动层收敛不了时（剩下的都是主题小节，或**单条记录本身就超过上限**），`memory_write` 的返回
+  与系统提示词都会要求模型 `memory_read` 读全文、再用 `memory_compact` 重写为精简版本
+  （合并同主题、删除过时条目、细节挪进文档只留指针）
 - `.xuanzhu` **始终**位于当前项目路径之下，**不做任何向上查找**：在 `/a/b/c` 工作就只用
   `/a/b/c/.xuanzhu`，即使 `/a` 或 `/a/b` 下已有 `.xuanzhu` 也不会复用
 - **启动时**与 **`/switch` 切换目录时**，若该目录下尚无 `.xuanzhu`，会自动创建
@@ -556,13 +573,14 @@ AutoX.js 那侧也可用环境变量 `XZH_DEVICE_PORT` 指定端口。
 当任务涉及某个领域时，玄猪会先 `list_skills` 查看可用技能、再 `load_skill` 加载完整指南
 （加载时自动安装并验证其依赖），然后借助 `bash` 执行指南中描述的命令。
 
-随包内置 18 个技能，常用如下：
+随包内置 19 个技能，常用如下：
 
 | 技能 | 领域 | 依赖 |
 | --- | --- | --- |
 | `playwright` | 浏览器自动化、端到端测试、网页验证（**默认用系统已安装的 Chrome**，减少反爬拦截） | `playwright-cli`（`npm i -g @playwright/cli@latest`） |
 | `officecli` | Word / Excel / PowerPoint 文档创建与读写 | `officecli`（单二进制，见技能内安装说明） |
 | `autojs6` | **操作真实 Android 手机**：点击、滑动、输入、读界面、启动应用（脚本由设备桥推到手机上执行） | 无（手机需装 AutoJs6，见「手机设备桥」） |
+| `release` | **发版流程**：版本号 / CHANGELOG / 构建与测试 / `npm publish` / 等 registry 同步 / 推送 GitHub / 发布后校验（含逐步清单与踩坑） | 无（用 `npm` / `git`） |
 | `github` / `gitlab` | 仓库、Issue、PR / MR | `gh` / `glab` |
 | `jira` / `linear` | 项目管理 | 对应 CLI |
 | `aws` / `kubernetes` | 云资源与容器编排 | `aws` / `kubectl` |
@@ -732,8 +750,10 @@ XZH_KITTY_KEYS=1 xzh
 默认开启自动批准（`autoApprove: true`），所有工具——包括写文件与执行命令——都会直接执行、不再询问；
 执行 `/auto off` 可切换为逐项确认，设置会持久保存到配置文件。
 
-其中 `/switch <目录>` 可在对话中切换项目目录：相对路径基于当前目录解析，支持 `~` 展开；
-切换后所有文件读写与命令执行都会作用于新目录，且对话上下文保留（如需清空可执行 `/reset`）。
+其中 `/switch <目录>` 用于切换项目：相对路径基于当前目录解析，支持 `~` 展开。
+切换后所有文件读写与命令执行都会作用于新目录，并且会**自动载入该项目最近一次会话**接着聊
+（会话文件也随之换到该项目名下；当前对话已存档在原项目，切回后 `/resume` 可找回）。
+若该项目还没有历史会话，则是全新开局。
 
 ## 项目结构
 
@@ -791,15 +811,21 @@ registry 已可见（npm 有 staging 阶段，期间 `npm view` / `npm install`
 
 - **[CodeBuddy](https://github.com/olasunkanmi-SE/codebuddy)** —— 作者
   [Oyinlola Olasunkanmi Raymond](https://github.com/olasunkanmi-SE)。
-  玄猪由该项目改造而来（移除编辑器依赖、改为纯粹的终端形态），
-  并依 MIT 许可**保留其原始版权声明**。
+  玄猪由该项目改造而来，依 MIT 许可**保留其原始版权声明**。
+  
 - **[Playwright](https://github.com/microsoft/playwright)** —— 由 Microsoft 开源。
   内置的 `playwright` 技能基于它实现浏览器自动化与端到端测试。
+
 - **[AutoJs6](https://github.com/SuperMonster003/AutoJs6)** —— 作者 SuperMonster003。
   手机设备桥（`xzh device`）的两套线协议都对着它的实现逐一核对，
   内置的 `autojs6` 技能也按它的源码整理而成 ——
   这才让「用脚本操作手机」成为可照做的能力，而不是让模型盲写。
 
+- **[OfficeCLI](https://github.com/iOfficeAI/OfficeCLI)** —— 由 iOfficeAI 开源。
+  内置的 `officecli` 技能基于它读写与自动化 Word / Excel / PowerPoint
+  （技能内容整理自该项目仓库的 `SKILL.md` 及其参考文件）；
+  它是零依赖的单文件 CLI、无需安装 Office，`xzh setup` 会一并装好。
+
 同时也感谢所有直接与间接依赖的开源项目，以及 npm 生态中的众多工具
 （完整清单见 `package.json`）。