xuanzhu 0.4.2 → 0.4.4

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 插件的
@@ -196,7 +198,7 @@ XZH_HOME=/path/to/dir xzh          # 改用 /path/to/dir/config.json
   "temperature": 0.2,
   "maxToolRounds": 200,
   "autoApprove": true,
-  "memoryMaxChars": 6000,
+  "memoryMaxChars": 12000,
   "maxParallelAgents": 4,
   "intent": { "enabled": false },
   "providers": {
@@ -222,6 +224,7 @@ XZH_HOME=/path/to/dir xzh          # 改用 /path/to/dir/config.json
 | 调用失败 | 自动切换到列表里的**下一个**（走到末尾会绕回表头），单次请求内每个模型最多试一次 |
 | 全部失败 | 直到所有模型都试过才报错，并说明「已配置的模型都试过了」 |
 | 记住结果 | 每次切换都会写回配置，下次启动直接用最后成功的那个 |
+| 会话内手动切换 | `/model` 列出已配置模型并让你选（↑ ↓ 或数字直选，Enter 确认、Esc 取消）；也可 `/model 2`、`/model <id / 模型名>` 一步到位。选中即写回配置 —— 与自动回退共用同一个「上次使用」的记录 |
 | 配置错误不回退 | 密钥无效 / 无权限 / 模型名或端点不存在时**不切换、不写盘**，只提示检查配置 —— 配置不改就永远失败，换模型只会把整条回退链白走一遍 |
 | 上下文超限不回退 | 超出模型窗口时**收敛历史后自动重试**，也不切换模型（见上一节） |
 | `Ctrl+C` / `Ctrl+D` 中断 | 不算失败，不触发回退 |
@@ -239,7 +242,7 @@ xzh model remove openai/gpt-4o         # 删除（id / 模型名 / 序号均可
 ```
 
 想让某个模型**不参与回退**，直接 `xzh model remove` 删掉即可。当前使用的模型显示在界面顶部与状态栏，
-发生回退时输出区会给出提示。
+发生回退时输出区会给出提示；想临时换一个用，直接在对话里 `/model` 选（`xzh model` 仍是增删改的入口）。
 
 > ⚠️ `xzh model add` 的位置参数自 v0.5 起**整体前移一位**（原来的 `[权重]` 已取消）：
 > 现在是 `add <provider> <model> [上下文窗口] [on|off]`。
@@ -258,6 +261,10 @@ xzh model remove openai/gpt-4o         # 删除（id / 模型名 / 序号均可
   推断表只覆盖常见模型，小众或私有部署的模型名会退回保守的 32k ——
   若你的模型窗口更大，请用 `xzh model context <id> <大小>` 显式指定，
   否则历史会被裁得比必要得更短。
+- **裁剪后会明确告诉模型「这不是完整历史」**：历史一旦被裁过，之后每次请求都会附上一条说明，
+  要求它不要拿残缺的旧任务当依据接着做，先回应用户**当前**这条消息。原因是裁剪是静默的，
+  模型看到一段从中途开始的历史时，很容易把上文里没做完的旧任务当成「用户正等我做完」——
+  实测中用户只发了句「在吗」，它却接着去起服务、查凭据。
 
 > 裁剪依据是**估算**的 token 数（中文约 1 字符/token，英文与代码约 3.5 字符/token），
 > 不依赖 tokenizer，属保守近似。项目规则（`.xuanzhu/rules.md`）与 `systemPromptExtra`
@@ -332,7 +339,7 @@ API Key 也可以来自环境变量，优先级低于配置文件：
 | `load_skill` | 加载指定技能的完整指南 | 否 |
 | `memory_read` | 读取项目记忆（长期记忆 + 最近日志） | 否 |
 | `memory_write` | 写入项目记忆（长期记忆 / 当日日志），长期记忆超限时自动精简 | 否 |
-| `memory_compact` | 用精简后的完整内容重写长期记忆（语义压缩） | 否 |
+| `memory_compact` | 用精简后的完整内容重写长期记忆（把新结论并入主题小节 / 语义压缩） | 否 |
 | `todo_write` | 创建 / 更新任务列表（每次提交完整列表） | 否 |
 | `task` | 派生子代理（默认 `code-explorer`）执行子任务，只返回结论；一轮内多个调用**并行**执行 | 否 |
 | `read_file` | 读取文件（带行号，支持偏移与行数限制） | 否 |
@@ -396,16 +403,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）
 
@@ -532,8 +544,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` 始终是唯一真实来源，你改完它模型下次读取即是新版 |
 
 记忆由玄猪自行维护：
@@ -542,11 +554,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`，会自动创建
@@ -561,13 +578,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` |
@@ -676,7 +694,7 @@ description: 一句话说明该技能的用途与适用场景
 kitty / Ghostty 会把该 xterm 兼容序列映射成「所有按键都用转义码上报」而破坏普通输入，
 故玄猪对这两类终端不发送请求，请改用 `Alt+Enter` 或在终端侧自行配置。
 
-界面内命令：`/help`、`/clear`、`/tools`、`/image`、`/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 [编号|id|模型名]`、`/auto [on|off]`、`/intent [on|off]`、`/exit`。
 
 ### 选中与复制