xuanzhu 0.1.0 → 0.1.2

package/README.md

@@ -118,6 +118,7 @@ xzh
 | `xzh model add <provider> <model> [权重]` | 新增模型（默认权重 `10`） |
 | `xzh model remove <id\|序号>` | 删除模型 |
 | `xzh model weight <id\|序号> <权重>` | 调整模型的调用权重 |
+| `xzh model context <id\|序号> <大小>` | 调整上下文窗口（token，支持 `128k` / `1M`） |
 | `xzh model reset` | 把全部模型权重恢复为默认值 |
 | `xzh config` | 查看当前配置（API Key 脱敏） |
 | `xzh config edit` | 使用 `nano` 编辑配置文件 |
@@ -129,7 +130,15 @@ xzh
 
 ## 配置
 
-配置文件位于 `~/.xzh/config.json`（权限 `600`）：
+配置文件位于 `~/.xzh/config.json`（权限 `600`）。可用环境变量 `XZH_HOME` 整体重定向 ——
+它指向**全局目录本身**（不是家目录）：
+
+```bash
+XZH_HOME=/path/to/dir xzh          # 改用 /path/to/dir/config.json
+```
+
+适用于多环境并行（本机 / 远程 / 容器各持一份配置互不干扰）。设置后**不会**执行
+`~/.xuanzhu` 的旧目录迁移 —— 那是为你显式指定的新位置，不该把家目录里的旧数据搬进去。
 
 ```json
 {
@@ -166,6 +175,8 @@ xzh
 | 自动降级 | 若还有**尚未尝试过**的可用模型，切换到权重最高的那个并重试（单次请求内每个模型最多尝试一次，最多切换 3 次） |
 | 不做空转 | 只有一个模型（或权重耗尽重置回它自己）时**不重试**，直接报错并附上当前模型信息 |
 | 权重耗尽 | 当**所有模型权重都为 0** 时，在终端警告并把全部权重重置回 `10` |
+| 配置错误不降权 | 密钥无效 / 无权限 / 模型名或端点不存在时**不扣权重、不写盘**，只提示检查配置 —— 配置不改就永远失败，扣权重只会把其他可用模型一起拖下水 |
+| 上下文超限不降权 | 超出模型窗口时**收敛历史后自动重试**，也不扣权重（见上一节） |
 
 ```bash
 xzh model                              # 交互式菜单
@@ -173,12 +184,36 @@ xzh model list                         # 查看已配置的模型与权重
 xzh model all                          # 查看所有内置可用模型
 xzh model add openai gpt-4o 20         # 新增（权重 20）
 xzh model weight openai/gpt-4o 5       # 调整权重
+xzh model context openai/gpt-4o 128k   # 调整上下文窗口（留空则自动推断）
 xzh model remove openai/gpt-4o         # 删除（id / 模型名 / 序号均可）
 xzh model reset                        # 全部恢复默认权重
 ```
 
 当前使用的模型与权重会显示在界面顶部与状态栏（如 `gpt-4o w6`），降级切换时输出区会给出提示。
 
+### 上下文窗口的作用
+
+`contextWindow` 不只是记录信息 —— 它决定**每次请求能带多长的历史**：
+
+- 玄猪按 `contextWindow × 80%` 得出输入预算（余量留给本次回复与估算误差），
+  再减去系统提示词的占用，剩下的额度给对话历史。
+- 超出额度时采取**分层处理**：先压缩**老旧的大块工具输出**（保留头尾、砍掉中段），
+  压缩后仍放不下才从最老的消息整条丢弃。这样不会为了腾空间而丢掉「用户最初提的要求」，
+  却留着一条已经过期的 `ls` 结果。最近的对话始终优先保留；
+  若某条消息自身就超预算，则截断它的正文，而不是整条丢弃。
+- 未配置该值时会按模型名自动推断（`xzh model all` 与 `xzh model list` 会显示推断结果）。
+  推断表只覆盖常见模型，小众或私有部署的模型名会退回保守的 32k ——
+  若你的模型窗口更大，请用 `xzh model context <id> <大小>` 显式指定，
+  否则历史会被裁得比必要得更短。
+
+> 裁剪依据是**估算**的 token 数（中文约 1 字符/token，英文与代码约 3.5 字符/token），
+> 不依赖 tokenizer，属保守近似。项目规则（`.xuanzhu/rules.md`）与 `systemPromptExtra`
+> 会全文进入系统提示词，写得过长会挤占历史额度 —— 占去窗口一半以上时界面会给出提示。
+
+若估算偏差导致仍然超限（服务端返回 `context_length_exceeded` 一类错误），玄猪会
+**把预算收敛到一半再自动重试一次**，而不会把它当成模型故障去降权或切换模型 ——
+换模型拿同样长的消息重发只会同样失败，还会白白扣掉权重。
+
 ### 意图分析（可选，默认关闭）
 
 启用后，**每条消息都会先用模板包裹、向模型发起一次独立请求**，返回的分析结果再作为本次输入交给主流程。适合需求含糊时先让模型"猜准意图"。
@@ -386,7 +421,20 @@ description: 一句话说明该技能的用途与适用场景
 kitty / Ghostty 会把该 xterm 兼容序列映射成「所有按键都用转义码上报」而破坏普通输入，
 故玄猪对这两类终端不发送请求，请改用 `Ctrl+J` 或在终端侧自行配置。
 
-界面内命令：`/help`、`/clear`、`/reset`、`/cwd`、`/switch <目录>`、`/term`、`/model`、`/auto [on|off]`、`/intent [on|off]`、`/exit`。
+界面内命令：`/help`、`/clear`、`/copy [N|all]`、`/mouse`、`/reset`、`/cwd`、`/switch <目录>`、`/term`、`/model`、`/auto [on|off]`、`/intent [on|off]`、`/exit`。
+
+### 选中与复制（重要）
+
+玄猪为了支持滚轮滚动**捕获了鼠标**，这会禁用终端的原生拖拽选择，因此在界面里直接框选通常选不中。三种办法：
+
+| 方式 | 说明 |
+| --- | --- |
+| **按住 Shift 拖拽** | 多数终端（VS Code、Windows Terminal、iTerm2、GNOME Terminal…）会用 Shift 绕过应用级鼠标捕获，**最省事** |
+| `/mouse` | 关闭鼠标捕获，之后可用鼠标直接框选复制；代价是滚轮不再滚动。再执行一次恢复 |
+| `/copy` | 让玄猪主动把输出区写入系统剪贴板（OSC 52，无需手动选择）。支持 `/copy 100`（最近 100 行）、`/copy 100-200`（按行号范围）、`/copy last`（最近一次对话，含提问）、`/copy all`（全部） |
+
+> `/copy` 依赖终端支持 OSC 52。少数终端（如默认配置的 GNOME Terminal）出于安全会忽略该序列，
+> 此时粘贴出来是空的，请改用 Shift 拖拽。
 
 默认开启自动批准（`autoApprove: true`），所有工具——包括写文件与执行命令——都会直接执行、不再询问；
 执行 `/auto off` 可切换为逐项确认，设置会持久保存到配置文件。