xuanzhu 0.4.2 → 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 插件的
@@ -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": {
@@ -332,7 +334,7 @@ API Key 也可以来自环境变量，优先级低于配置文件：
 | `load_skill` | 加载指定技能的完整指南 | 否 |
 | `memory_read` | 读取项目记忆（长期记忆 + 最近日志） | 否 |
 | `memory_write` | 写入项目记忆（长期记忆 / 当日日志），长期记忆超限时自动精简 | 否 |
-| `memory_compact` | 用精简后的完整内容重写长期记忆（语义压缩） | 否 |
+| `memory_compact` | 用精简后的完整内容重写长期记忆（把新结论并入主题小节 / 语义压缩） | 否 |
 | `todo_write` | 创建 / 更新任务列表（每次提交完整列表） | 否 |
 | `task` | 派生子代理（默认 `code-explorer`）执行子任务，只返回结论；一轮内多个调用**并行**执行 | 否 |
 | `read_file` | 读取文件（带行号，支持偏移与行数限制） | 否 |
@@ -396,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）
 
@@ -532,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` 始终是唯一真实来源，你改完它模型下次读取即是新版 |
 
 记忆由玄猪自行维护：
@@ -542,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`，会自动创建
@@ -561,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` |