@zhushanwen/pi-rename-session 0.2.0 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@ Pi rename-session 扩展 — 新 session 首 turn 完成后，自动生成会话
 ## 功能
 
 - 新 session 的**首个 turn** 完成后自动生成简短标题（3-8 个词，跟随对话语言）
-- 复用主 turn 完整上下文发起独立 LLM 调用，命中 kvcache，几乎不产生额外成本
+- **独立选模**：标题生成用独立的 `ModelSelector` 配置（默认 `scoped`，取 `settings.json` enabledModels 首个可用），不搭便车主 session 的昂贵模型
 - 标题直接 `setSessionName` 落库，不进 session history（不污染对话记录）
 - fire-and-forget：任何失败（LLM 调用 / 提取 / auth / 读取）都静默跳过，保留原 label，绝不阻断 agent 循环
 - **子 session 自动排除**：subagent 子进程 session 不触发 rename（避免给临时产物起名）
@@ -16,25 +16,48 @@ Pi rename-session 扩展 — 新 session 首 turn 完成后，自动生成会话
 pi install npm:@zhushanwen/pi-rename-session
 ```
 
-## 开关
+## 配置
 
-文件存在 = 开启。默认**关闭**，需显式开启。
+配置文件：`<agentDir>/config/rename-session-ext-config.json`（`<agentDir>` 默认 `~/.pi/agent`，`PI_CODING_AGENT_DIR` 可覆盖；xyz-agent 隔离环境为 `~/.xyz-agent/pi/agent`）。
 
-- **原生 pi 用户**：手动创建开关文件
-  ```bash
-  touch ~/.pi/agent/auto-rename-enabled
-  ```
-- **xyz-agent 用户**：通过 settings 的开关控制（由 xyz-agent 桥接到同一个开关文件）
+```json
+{
+  "enabled": true,
+  "model": { "type": "scoped" },
+  "maxTitleLength": 50
+}
+```
+
+| 字段 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `enabled` | `boolean` | `false` | 自动重命名开关（受 flag 文件覆盖，见下） |
+| `model` | `ModelSelector` | `{ "type": "scoped" }` | 标题生成模型，四形式见 config skill（`ref` / `fallback` / `available` / `scoped`） |
+| `maxTitleLength` | `number` | `50` | 标题最大长度（Unicode 码点数，须正整数） |
+
+文件缺失/坏 JSON 返回默认值，不抛错。改完保存即生效（mtime 读时刷新，每个 `turn_end` 重新 load）。
+
+## 开关优先级（重要）
+
+`enabled` 有两层来源，优先级从高到低：
 
-开关文件路径可通过 `PI_CODING_AGENT_DIR` 环境变量覆盖基础目录（默认 `~/.pi/agent`）。
+1. **`<agentDir>/auto-rename-enabled` flag 文件**（存在 = 开）：xyz-agent runtime 的开关契约——桌面端 SystemPage 开关、首启默认开启都写这个文件。**xyz-agent 用户请通过桌面端开关或 `/auto-rename` 命令管理，不要手改 JSON 的 `enabled`**（flag 存在时永远视为开，手改会被覆盖）。
+2. **config 的 `enabled` 字段**（默认 false）：flag 不存在时生效，是原生 pi CLI 用户的开关。
+
+## 命令
+
+```
+/auto-rename          # 查看当前状态
+/auto-rename on       # 开启（创建 flag 文件）
+/auto-rename off      # 关闭（写 config.enabled=false + 删 flag，双写同步）
+```
 
 ## 工作原理
 
 1. **监听 `turn_end`**：每个 turn 完成时触发。
-2. **开关 + subagent 过滤**：开关关闭则直接返回；session 路径含 `subagents` 段则视为子进程 session，跳过。
+2. **开关 + subagent 过滤**：开关关闭（flag 不存在且 `enabled=false`）直接返回；session 路径含 `subagents` 段视为子进程 session，跳过。
 3. **首 turn 判定**：统计 session entries 中 `assistant` 回复数，===1 才是首 turn（后续 turn 不重复 rename）。
-4. **LLM 生成标题**：复用主 turn 的完整上下文（system prompt + tools + messages），追加一条 rename 指令的 user message，发起一次独立 LLM 调用。由于前缀与主 turn 字节级一致，能命中 kvcache，显著省成本。
-5. **落库**：调 `setSessionName` 写入标题。**不**写入 session history（不调用 `appendEntry`），对话记录不受影响。
+4. **LLM 生成标题**：复用对话 messages 前缀（与主 turn 字节级一致，命中 kvcache），但用**独立精简 system prompt**（<200 字符，非整个 agent prompt）+ 显式 `tools: []`（纯文本生成，不暴露工具），按 `config.model` 独立选模发起一次 LLM 调用。
+5. **落库**：调 `setSessionName` 写入清洗后的标题（去首尾引号/markdown 强调标记，按 Unicode 码点截断）。**不**写入 session history，对话记录不受影响。
 
 ## 子 session 自动排除
 
@@ -48,9 +71,11 @@ rename-session/
 ├── package.json
 ├── vitest.config.ts
 ├── README.md
+├── skills/rename-session-ext-config/SKILL.md   # 配置指南（pi 内 agent 可发现）
 └── src/
-    ├── index.ts          # 工厂入口（注册 turn_end handler）
-    ├── pure.ts           # 纯函数（countAssistantReplies / extractTitle / isEnabled / CONFIG）
-    ├── llm.ts            # callRenameLLM（动态 import completeSimple，复用主 turn 上下文）
-    └── __tests__/        # 单测（pure 纯函数 + llm mock + index 集成）
+    ├── index.ts          # 工厂入口（注册 turn_end handler + /auto-rename 命令）
+    ├── commands.ts       # /auto-rename on|off|status 命令
+    ├── llm.ts            # callRenameLLM / buildMessages / isSubagentSession
+    ├── pure.ts           # 纯函数（loadRenameConfig / setAutoRenameSwitch / countAssistantReplies / cleanTitle）
+    └── __tests__/        # 单测（pure / commands / llm mock / index 集成）
 ```

package/package.json

@@ -1,29 +1,35 @@
 {
   "name": "@zhushanwen/pi-rename-session",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "index.ts",
   "pi": {
     "extensions": [
       "./index.ts"
     ],
-    "skills": []
+    "skills": [
+      "./skills"
+    ]
   },
   "keywords": [
     "pi-package"
   ],
+  "dependencies": {
+    "@zhushanwen/pi-llm-shared": "0.2.0"
+  },
   "devDependencies": {
     "vitest": "^4.1.8"
   },
   "files": [
     "index.ts",
     "src/**/*.ts",
+    "skills/",
     "vitest.config.ts"
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-ai": "*",
-    "@sinclair/typebox": "*"
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -32,7 +38,7 @@
     "@earendil-works/pi-ai": {
       "optional": true
     },
-    "@sinclair/typebox": {
+    "typebox": {
       "optional": true
     }
   },

package/skills/rename-session-ext-config/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: rename-session-ext-config
+description: "配置 @zhushanwen/pi-rename-session（会话自动重命名）时加载。含配置文件路径、RenameSessionConfig schema、ModelSelector 四形式、触发时机（首 turn）、maxTitleLength 约束、默认值、示例、生效时机、开关优先级（flag 覆盖）。触发词：配置重命名、rename 配置、自动标题、rename-session config、auto-rename 设置、首 turn、触发时机、开关不生效。"
+---
+
+# rename-session 配置指南
+
+> @zhushanwen/pi-rename-session：新 session 首 turn 完成后，用独立小模型生成会话标题（不搭便车主 session 的昂贵模型）。
+
+## 配置文件位置
+
+`<agentDir>/config/rename-session-ext-config.json`
+
+- `<agentDir>` = pi agent 目录（`PI_CODING_AGENT_DIR` 覆盖，默认 `~/.pi/agent`；xyz-agent 隔离环境为 `~/.xyz-agent/pi/agent`）
+- 走 llm-shared 泛型 config（config/ 子目录 + getAgentDir 派生 + mtime+size 缓存 + 原子写）
+- 文件缺失/坏 JSON 返回默认值，不抛错
+
+## 何时触发重命名（重要）
+
+**仅在新 session 的第一个 turn 完成后触发一次**（判定条件：session 内 assistant 回复数 === 1）。
+
+- 已存在的多 turn session **不会回溯重命名**——开启 `enabled` 后只对之后新建的 session 生效
+- 每个 session 最多重命名一次（首 turn 后不再触发）
+- 若首 turn 时 LLM 调用失败，静默跳过保留原标题，不重试
+
+> 改完配置「没看到 session 被重命名」的常见原因：当前 session 已过首 turn。新建一个 session 测试。
+
+## Schema
+
+```ts
+interface RenameSessionConfig {
+  enabled: boolean;        // 自动重命名开关，默认 false
+  model: ModelSelector;    // 标题生成模型，默认 { type: "scoped" }
+  maxTitleLength: number;  // 标题最大长度（Unicode 码点），默认 50
+}
+```
+
+### ModelSelector 四形式（llm-shared 共用）
+
+| type | 形式 | 语义 |
+|---|---|---|
+| `ref` | `{type:"ref", ref:"provider/modelId"}` | 精确指定（需配 auth） |
+| `fallback` | `{type:"fallback", refs:[...]}` | 按序尝试首个可用 |
+| `available` | `{type:"available"}` | getAvailable() 首个（配 auth 的全量池） |
+| `scoped` | `{type:"scoped"}` | 读 settings.json 的 enabledModels 取首个可用（默认） |
+
+> scoped 读的是用户启用列表（settings.json），不是凭证——凭证走 ctx.modelRegistry。enabledModels 支持 `*` 通配（如 `"anthropic/*"`），顺序即优先级。
+
+### maxTitleLength 约束
+
+必须是**正整数**（`Number.isInteger && > 0`）。传小数（`50.5`）、0、负数、非数字都会回落默认值 50。截断按 Unicode 码点（不会截断多字节字符）。
+
+## 默认值
+
+```json
+{ "enabled": false, "model": { "type": "scoped" }, "maxTitleLength": 50 }
+```
+
+## 配置示例
+
+固定用便宜模型生成标题：
+```json
+{
+  "enabled": true,
+  "model": { "type": "ref", "ref": "deepseek/deepseek-chat" },
+  "maxTitleLength": 50
+}
+```
+
+多 provider 容错：
+```json
+{
+  "enabled": true,
+  "model": { "type": "fallback", "refs": ["zhipu/glm-4-flash", "deepseek/deepseek-chat"] }
+}
+```
+
+零配置（用用户启用列表首个）：只需把 enabled 设 true，model 保持默认 scoped。
+
+## 配置生效时机
+
+配置走 mtime+size 读时刷新（每个 `turn_end` 都重新 load）。改完 JSON 保存后，**下一个新 session 的首 turn** 即按新配置触发（已过首 turn 的 session 不受影响）。
+
+## 排除项
+
+subagent 子进程 session 不重命名（`isSubagentSession` 判定 session 目录）——子 session 是临时产物，重命名会产生噪音。如果你发现某个 session 没被重命名，先确认它不是 subagent session。
+
+## 开关优先级（重要）
+
+`enabled` 有两层来源，优先级从高到低：
+
+1. **`<agentDir>/auto-rename-enabled` flag 文件**（存在 = 开）：这是 xyz-agent runtime 的开关契约（SystemPage 开关 / 首启默认开启都写这个文件，live 检查每次 turn_end 生效）。**xyz-agent 用户不要手改 JSON 里的 enabled**——桌面端的开关状态存在 flag 文件里，手改 JSON 会被 flag 覆盖（flag 存在时永远视为开）。
+2. **config 的 `enabled` 字段**（默认 false）：flag 不存在时生效，是原生 pi CLI 用户的开关（手改 JSON 或 `/auto-rename on|off` 命令）。
+
+`/auto-rename on` 只创建 flag；`/auto-rename off` 写 config.enabled=false + 删 flag（双写同步）。旧版升级用户：旧 flag 文件保留不动，仍作为开关生效，无需任何迁移操作。
+
+## LLM 调用特性
+
+- 独立 model（不搭便车主 session 模型）
+- 独立精简 system prompt（~75 字符，非整个 agent prompt）
+- 不传 tools（纯文本标题生成）
+- fire-and-forget（不阻塞 turn_end handler）
+- model 不可用 → 静默跳过（日志 `[rename-session] model not available, skipping`），不阻断主对话

package/src/__tests__/commands.test.ts

@@ -2,66 +2,89 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { clearConfigCache } from "@zhushanwen/pi-llm-shared";
 
 import { executeAutoRenameCommand } from "../commands.js";
 
 /**
- * executeAutoRenameCommand 依赖模块级 CONFIG.switchFilePath，用 vi.mock("./pure.js")
- * 注入可控路径，避免读写真实 ~/.pi/agent 目录。
+ * executeAutoRenameCommand 读写 `<agentDir>/config/rename-session-ext-config.json`（经 llm-shared loadConfig/saveConfig，
+ * 路径走 getAgentDir）。用 PI_CODING_AGENT_DIR 隔离到临时目录，避免读写真实 ~/.pi/agent。
+ * 每次写入后 clearConfigCache 确保读盘（不命中 mtime 缓存），验证真实落盘行为。
  */
-vi.mock("../pure.js", async (importActual) => {
-	const actual = await importActual<typeof import("../pure.js")>();
-	const tmpFile = path.join(os.tmpdir(), `rename-cmd-${Date.now()}-enabled`);
-	return {
-		...actual,
-		CONFIG: { ...actual.CONFIG, switchFilePath: tmpFile },
-		isEnabled: (p: string) => fs.existsSync(p),
-		setSwitch: actual.setSwitch,
-	};
-});
+describe("executeAutoRenameCommand", () => {
+	let tmpAgentDir: string;
+	let origEnv: string | undefined;
 
-// 被测模块须在 vi.mock 之后 import（vitest 提升 vi.mock）
-import { CONFIG as MOCKED_CONFIG } from "../pure.js";
+	beforeEach(() => {
+		tmpAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "rename-cmd-"));
+		origEnv = process.env.PI_CODING_AGENT_DIR;
+		process.env.PI_CODING_AGENT_DIR = tmpAgentDir;
+		clearConfigCache();
+	});
 
-describe("executeAutoRenameCommand", () => {
 	afterEach(() => {
-		try { fs.unlinkSync(MOCKED_CONFIG.switchFilePath); } catch (e) { console.debug("cleanup skip:", e); }
+		if (origEnv === undefined) delete process.env.PI_CODING_AGENT_DIR;
+		else process.env.PI_CODING_AGENT_DIR = origEnv;
+		clearConfigCache();
+		fs.rmSync(tmpAgentDir, { recursive: true, force: true });
 	});
 
-	it("无参数 → 显示当前状态 + 用法", () => {
+	function configPath(): string {
+		return path.join(tmpAgentDir, "config", "rename-session-ext-config.json");
+	}
+
+	it("无参数 → 显示当前状态（默认关闭）+ 用法", () => {
 		const msg = executeAutoRenameCommand("");
 		expect(msg).toContain("自动重命名会话");
+		expect(msg).toContain("已关闭");
 		expect(msg).toContain("用法");
 	});
 
 	it("status → 同无参数", () => {
-		const msg = executeAutoRenameCommand("status");
-		expect(msg).toContain("自动重命名会话");
+		expect(executeAutoRenameCommand("status")).toContain("已关闭");
 	});
 
-	it("on → 开启并创建文件", () => {
+	it("on → 创建 flag 文件（不写 config，避免残留 enabled=true）", () => {
 		const msg = executeAutoRenameCommand("on");
 		expect(msg).toContain("已开启");
-		expect(fs.existsSync(MOCKED_CONFIG.switchFilePath)).toBe(true);
+		// 开启走 flag 契约（live 覆盖源），不落 config
+		expect(fs.existsSync(path.join(tmpAgentDir, "auto-rename-enabled"))).toBe(true);
+		expect(fs.existsSync(configPath())).toBe(false);
+	});
+
+	it("on 后 status 显示已开启（缓存一致，无需 clearConfigCache）", () => {
+		executeAutoRenameCommand("on");
+		expect(executeAutoRenameCommand("status")).toContain("已开启");
 	});
 
-	it("off → 关闭并删除文件", () => {
-		fs.writeFileSync(MOCKED_CONFIG.switchFilePath, "");
+	it("off → 写 config.enabled=false 落盘 + 删除 flag（双写同步）", () => {
+		executeAutoRenameCommand("on");
 		const msg = executeAutoRenameCommand("off");
 		expect(msg).toContain("已关闭");
-		expect(fs.existsSync(MOCKED_CONFIG.switchFilePath)).toBe(false);
+		clearConfigCache();
+		const raw = JSON.parse(fs.readFileSync(configPath(), "utf-8"));
+		expect(raw.enabled).toBe(false);
+		expect(fs.existsSync(path.join(tmpAgentDir, "auto-rename-enabled"))).toBe(false);
 	});
 
 	it("enable/disable 作为 on/off 别名", () => {
-		expect(executeAutoRenameCommand("enable")).toContain("已开启");
-		expect(fs.existsSync(MOCKED_CONFIG.switchFilePath)).toBe(true);
-		expect(executeAutoRenameCommand("disable")).toContain("已关闭");
+		executeAutoRenameCommand("enable");
+		clearConfigCache();
+		expect(executeAutoRenameCommand("status")).toContain("已开启");
+		executeAutoRenameCommand("disable");
+		clearConfigCache();
+		expect(executeAutoRenameCommand("status")).toContain("已关闭");
 	});
 
 	it("大小写不敏感（ON / Off）", () => {
-		expect(executeAutoRenameCommand("ON")).toContain("已开启");
-		expect(executeAutoRenameCommand("Off")).toContain("已关闭");
+		executeAutoRenameCommand("ON");
+		clearConfigCache();
+		expect(executeAutoRenameCommand("status")).toContain("已开启");
+		executeAutoRenameCommand("Off");
+		clearConfigCache();
+		expect(executeAutoRenameCommand("status")).toContain("已关闭");
 	});
 
 	it("未知参数 → 提示用法", () => {
@@ -69,4 +92,24 @@ describe("executeAutoRenameCommand", () => {
 		expect(msg).toContain("未知参数");
 		expect(msg).toContain("用法");
 	});
+
+	it("on 不动 config（手写 enabled/model/maxTitleLength 均保留）", () => {
+		// 预置含自定义 model + maxTitleLength 的配置
+		fs.mkdirSync(path.dirname(configPath()), { recursive: true });
+		fs.writeFileSync(
+			configPath(),
+			JSON.stringify({ enabled: false, model: { type: "available" }, maxTitleLength: 30 }),
+		);
+		clearConfigCache();
+
+		executeAutoRenameCommand("on");
+		clearConfigCache();
+
+		// on 只建 flag，config 原封不动（enabled 仍 false，但 loadRenameConfig 被 flag 覆盖为 true）
+		const raw = JSON.parse(fs.readFileSync(configPath(), "utf-8"));
+		expect(raw.enabled).toBe(false);
+		expect(raw.model).toEqual({ type: "available" });
+		expect(raw.maxTitleLength).toBe(30);
+		expect(executeAutoRenameCommand("status")).toContain("已开启");
+	});
 });