@zhushanwen/pi-rename-session 0.5.4 → 0.6.0

package/README.md

@@ -42,10 +42,12 @@ pi install npm:@zhushanwen/pi-rename-session
 
 ## 开关优先级（重要）
 
-`enabled` 有两层来源，优先级从高到低：
+`enabled` 有四层来源，优先级从高到低（`src/pure.ts` `loadRenameConfig`）：
 
-1. **`<agentDir>/auto-rename-enabled` flag 文件**（存在 = 开）：xyz-agent runtime 的开关契约——桌面端 SystemPage 开关、首启默认开启都写这个文件。**xyz-agent 用户请通过桌面端开关或 `/auto-rename` 命令管理，不要手改 JSON 的 `enabled`**（flag 存在时永远视为开，手改会被覆盖）。
-2. **config 的 `enabled` 字段**（默认 false）：flag 不存在时生效，是原生 pi CLI 用户的开关。
+1. **`PI_RENAME_*` 环境变量**（最高，live 读取）：`PI_RENAME_ENABLED=true/false` 显式设置时最终生效，flag 文件也被覆盖（仅显式设置该变量时压制 flag）。适用于容器化部署、CI/CD 等场景。
+2. **`<agentDir>/auto-rename-enabled` flag 文件**（存在 = 开）：xyz-agent runtime 的开关契约——桌面端 SystemPage 开关、首启默认开启都写这个文件。**xyz-agent 用户请通过桌面端开关或 `/auto-rename` 命令管理，不要手改 JSON 的 `enabled`**（flag 存在时视为开，手改会被覆盖）。
+3. **config 的 `enabled` 字段**（默认 false）：环境变量未设 `PI_RENAME_ENABLED` 且 flag 不存在时生效，是原生 pi CLI 用户的开关。
+4. **默认值**（false）：以上三层均未设置时。
 
 ## 命令
 
@@ -79,9 +81,14 @@ rename 是 best-effort 副作用，任何失败静默跳过、绝不阻断 agent
 | 落库前发现已有手动名 | skip（name exists），不覆盖 |
 | 标题模型不可用 | 记日志静默跳过 |
 
-### debug 证据链（`XYZ_AGENT_DEBUG=1`）
+### 日志通道（appendEntry 常开 + debug 文件日志）
 
-`console.warn` 输出，前缀 `[rename-session]`。下列 8 条 debug 日志的**文案字面值是 E2E 断言硬契约**（变更须同步 `e2e/` 场景脚本与单测）：
+所有日志经 `@zhushanwen/pi-extension-logger` 输出，两个通道：
+
+- **appendEntry（session entry，常开）**：`logger.warn` / `logger.error` 写入 session JSONL 的 custom entry（`type: "custom"`、`customType: "rename-session:log"`），不进 LLM 上下文、不显 TUI。`data.message` 由 logger 自动补 `[rename-session]` 前缀，格式为 `msg + 结构化 data`（error 等详情在 entry `data.data` 字段，不冒号拼接进 message）。
+- **文件日志（`XYZ_AGENT_DEBUG=1` 时）**：`<agentDir>/logs/rename-session-<date>.log`。
+
+下列 8 条 debug 日志（仅 `XYZ_AGENT_DEBUG=1` 时经 `logger.warn` 发出）的**文案字面值是 E2E 断言硬契约**（断言对象 = appendEntry entry 的 message 内容；变更须同步 `e2e/` 场景脚本与单测）：
 
 | # | 日志 | 发出侧 | 含义 |
 |---|---|---|---|
@@ -94,7 +101,7 @@ rename 是 best-effort 副作用，任何失败静默跳过、绝不阻断 agent
 | 7 | `LLM request messages: <JSON>` | llm | 传给 callLLM 的 messages 内省（role + text 的 head 200 码点 + … + tail 100 码点预览，截断单位与 truncateForTitle 统一为 Unicode 码点），在请求发起前打出 |
 | 8 | `rename with model <provider>/<id>` | llm | 成功路径模型记录（原常开日志；为避免污染 Pi 输入框改为 debug 输出，带 t=ISO 时间戳） |
 
-另有两条**非 debug 常开**日志：`rename LLM call failed: <err>`（调用失败/超时；超时时 llm-shared callLLM 内部的 extractText 将空错误文本归一为 `unknown error`——extension 侧 `result.error ?? "unknown error"` 只兜 null/undefined，空串兜底发生在 llm-shared 层）、`model not available, skipping`（选模失败）。handler 侧日志带 `t=<ISO时间>` 与 `turnIndex`；llm 侧带 `t=<ISO时间>`、无 turnIndex。
+另有两条**非 debug 常开**日志（无条件经 `logger.warn` 落 appendEntry entry）：`rename LLM call failed`（`logger.warn(msg, { error })` 形态，error 详情在结构化 data 字段；超时时 llm-shared callLLM 内部的 extractText 将空错误文本归一为 `unknown error`——extension 侧 `result.error ?? "unknown error"` 只兜 null/undefined，空串兜底发生在 llm-shared 层）、`model not available, skipping`（选模失败）。handler 侧日志 message 带 `t=<ISO时间>` 与 `turnIndex`；llm 侧带 `t=<ISO时间>`、无 turnIndex。
 
 ## E2E 验收
 
@@ -136,7 +143,7 @@ rename-session/
 ├── skills/rename-session-ext-config/SKILL.md   # 配置指南（pi 内 agent 可发现）
 └── src/
     ├── index.ts          # 工厂入口（注册 turn_end handler + /auto-rename 命令）
-    ├── commands.ts       # /auto-rename on|off|status 命令
+    ├── commands.ts       # /auto-rename on|off|status 命令（enable/disable 别名）
     ├── llm.ts            # callRenameLLM / 两段输入构造 / debug 内省 / 超时
     ├── pure.ts           # 纯函数（配置 / 首轮计数 / cleanTitle）
     └── __tests__/        # 单测（pure / commands / llm mock / index 集成）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-rename-session",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {
@@ -32,8 +32,8 @@
     "pi-package"
   ],
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.3.1",
-    "@zhushanwen/pi-llm-shared": "0.4.2"
+    "@zhushanwen/pi-extension-logger": "0.4.0",
+    "@zhushanwen/pi-llm-shared": "0.5.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",

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

@@ -114,11 +114,12 @@ subagent 子进程 session 不重命名（`isSubagentSession` 判定 session 目
 
 ## 开关优先级（重要）
 
-`enabled` 有三层来源，优先级从高到低：
+`enabled` 有四层来源，优先级从高到低（`src/pure.ts` `loadRenameConfig`）：
 
-1. **环境变量 `PI_RENAME_ENABLED`**（最高优先级）：适用于容器化部署、CI/CD 等场景。`true`/`false` 字符串，live 读取。覆盖 flag 文件和配置文件。
-2. **`<agentDir>/auto-rename-enabled` flag 文件**（存在 = 开）：这是 xyz-agent runtime 的开关契约（SystemPage 开关 / 首启默认开启都写这个文件，live 检查每次 turn_end 生效）。**xyz-agent 用户不要手改 JSON 里的 enabled**——桌面端的开关状态存在 flag 文件里，手改 JSON 会被 flag 覆盖（flag 存在时永远视为开）。
-3. **config 的 `enabled` 字段**（默认 false）：flag 不存在时生效，是原生 pi CLI 用户的开关（手改 JSON 或 `/auto-rename on|off` 命令）。
+1. **环境变量 `PI_RENAME_ENABLED`**（最高优先级）：适用于容器化部署、CI/CD 等场景。`true`/`false` 字符串，live 读取。显式设置时覆盖 flag 文件和配置文件（`PI_RENAME_ENABLED=false` 即使 flag 存在也禁用重命名）。
+2. **`<agentDir>/auto-rename-enabled` flag 文件**（存在 = 开）：这是 xyz-agent runtime 的开关契约（SystemPage 开关 / 首启默认开启都写这个文件，live 检查每次 turn_end 生效）。**xyz-agent 用户不要手改 JSON 里的 enabled**——桌面端的开关状态存在 flag 文件里，手改 JSON 会被 flag 覆盖（环境变量未显式设置 `PI_RENAME_ENABLED` 时，flag 存在即视为开）。
+3. **config 的 `enabled` 字段**（默认 false）：环境变量未设置且 flag 不存在时生效，是原生 pi CLI 用户的开关（手改 JSON 或 `/auto-rename on|off` 命令）。
+4. **默认值**（false）：以上三层均未设置时。
 
 `/auto-rename on` 只创建 flag；`/auto-rename off` 写 config.enabled=false + 删 flag（双写同步）。旧版升级用户：旧 flag 文件保留不动，仍作为开关生效，无需任何迁移操作。
 

package/src/__tests__/index.test.ts

@@ -36,7 +36,7 @@ import { callLLM, resolveModel } from "@zhushanwen/pi-llm-shared";
 import renameSessionExtension from "../index";
 import { type RenameSessionConfig, loadRenameConfig } from "../pure.js";
 
-// 每用例收尾统一还原：console spy 恢复 + stub 的 XYZ_AGENT_DEBUG 还原，
+// 每用例收尾统一还原：logger mock 恢复 + stub 的 XYZ_AGENT_DEBUG 还原，
 // 防泄漏到后续用例（debug 开关 live 读 process.env，依赖 stubEnv/unstubAllEnvs 成对）
 afterEach(() => {
 	vi.restoreAllMocks();
@@ -247,13 +247,13 @@ describe("renameSessionExtension", () => {
 		vi.mocked(loadRenameConfig).mockReturnValue(ENABLED_CONFIG);
 		vi.mocked(resolveModel).mockReturnValue(STUB_MODEL);
 		// ok:false 即可满足断言需要（callLLM 被调 + 不落库），聚焦触发判定本身
-		vi.mocked(callLLM).mockResolvedValue({ ok: false, error: "by-design", recoverable: true });
+		vi.mocked(callLLM).mockResolvedValue({ ok: false, error: "by-design" });
 
 		const FINAL_TEXT = "最终回复：已修复登录超时";
 		const stopMessage = { stopReason: "stop", content: [{ type: "text", text: FINAL_TEXT }] };
 
-		// 组1（区分性数据）：旧 countAssistantReplies=2 不触发 vs 新成功计数=1 触发——
-		// index 若仍用旧计数函数（忘接线 wave-1 纯函数），本组红（接线回归防护）
+		// 组1（区分性数据）：旧判定（数全部 assistant 回复）=2 不触发 vs 新成功计数（只数 stop）=1 触发——
+		// index 若仍用旧计数逻辑（不看 stopReason，忘接线 wave-1 纯函数），本组红（接线回归防护）
 		const toolUseRound = [
 			{ type: "message", message: { role: "user", content: "帮我修复登录超时" } },
 			{ type: "message", message: { role: "assistant", stopReason: "toolUse", content: [] } },
@@ -322,7 +322,7 @@ describe("renameSessionExtension", () => {
 	it("LTC8: callLLM 返回 {ok:false} → callRenameLLM 返回 null，不调 setSessionName", async () => {
 		vi.mocked(loadRenameConfig).mockReturnValue(ENABLED_CONFIG);
 		vi.mocked(resolveModel).mockReturnValue(STUB_MODEL);
-		vi.mocked(callLLM).mockResolvedValue({ ok: false, error: "boom", recoverable: true });
+		vi.mocked(callLLM).mockResolvedValue({ ok: false, error: "boom" });
 
 		await fire(setup, createMockCtx());
 		// handler 内 callRenameLLM 是 detached promise（fire-and-forget），等其 settle 后断言

package/src/__tests__/llm.test.ts

@@ -36,7 +36,7 @@ import {
 } from "../llm.js";
 import { type RenameSessionConfig } from "../pure.js";
 
-// 每用例收尾统一还原：console spy 恢复 + stub 的 XYZ_AGENT_DEBUG 还原，
+// 每用例收尾统一还原：logger mock 恢复 + stub 的 XYZ_AGENT_DEBUG 还原，
 // 防泄漏到后续用例（debug 开关 live 读 process.env，依赖 stubEnv/unstubAllEnvs 成对）
 afterEach(() => {
 	vi.restoreAllMocks();
@@ -324,7 +324,7 @@ describe("callRenameLLM", () => {
 
 	it("callLLM 返回 {ok:false} → 返回 null（静默跳过，不抛错）", async () => {
 		vi.mocked(resolveModel).mockReturnValue(STUB_MODEL);
-		vi.mocked(callLLM).mockResolvedValue({ ok: false, error: "boom", recoverable: true });
+		vi.mocked(callLLM).mockResolvedValue({ ok: false, error: "boom" });
 		const result = await callRenameLLM(createCtx(), BASE_CONFIG, FINAL_MESSAGE);
 		expect(result).toBeNull();
 	});
@@ -498,7 +498,7 @@ describe("callRenameLLM", () => {
 
 	it("TC7: callLLM ok:false（超时/模型错误）→ 返回 null 不抛错（失败归一静默跳过）", async () => {
 		vi.mocked(resolveModel).mockReturnValue(STUB_MODEL);
-		vi.mocked(callLLM).mockResolvedValue({ ok: false, error: "timeout", recoverable: true });
+		vi.mocked(callLLM).mockResolvedValue({ ok: false, error: "timeout" });
 		await expect(callRenameLLM(createCtx(), BASE_CONFIG, FINAL_MESSAGE)).resolves.toBeNull();
 	});
 
@@ -558,7 +558,7 @@ describe("callRenameLLM A1 日志", () => {
 		vi.clearAllMocks();
 	});
 
-	it("TC1: resolveModel null → console 输出 '[rename-session] model not available, skipping'，返回 null", async () => {
+	it("TC1: resolveModel null → logger.warn('model not available, skipping')（前缀由真实 logger 补），返回 null", async () => {
 		loggerMock.warn.mockClear();
 		vi.mocked(resolveModel).mockReturnValue(null);
 		const result = await callRenameLLM(createCtx(), BASE_CONFIG, FINAL_MESSAGE);
@@ -566,10 +566,10 @@ describe("callRenameLLM A1 日志", () => {
 		expect(loggerMock.warn).toHaveBeenCalledWith("model not available, skipping");
 	});
 
-	it("TC2: callLLM {ok:false} → console 输出 '[rename-session] rename LLM call failed: <error>'，返回 null", async () => {
+	it("TC2: callLLM {ok:false} → logger.warn('rename LLM call failed', {error})（前缀由真实 logger 补），返回 null", async () => {
 		loggerMock.warn.mockClear();
 		vi.mocked(resolveModel).mockReturnValue(STUB_MODEL);
-		vi.mocked(callLLM).mockResolvedValue({ ok: false, error: "boom", recoverable: true });
+		vi.mocked(callLLM).mockResolvedValue({ ok: false, error: "boom" });
 		const result = await callRenameLLM(createCtx(), BASE_CONFIG, FINAL_MESSAGE);
 		expect(result).toBeNull();
 		expect(loggerMock.warn).toHaveBeenCalledWith("rename LLM call failed", { error: "boom" });
@@ -578,7 +578,7 @@ describe("callRenameLLM A1 日志", () => {
 	it("TC2b: callLLM {ok:false} → 不输出 'rename with model' 成功日志（B2 位置修正：成功日志已移到 result.ok 分支后），但仍输出 failed 日志", async () => {
 		loggerMock.warn.mockClear();
 		vi.mocked(resolveModel).mockReturnValue(STUB_MODEL);
-		vi.mocked(callLLM).mockResolvedValue({ ok: false, error: "boom", recoverable: true });
+		vi.mocked(callLLM).mockResolvedValue({ ok: false, error: "boom" });
 		const result = await callRenameLLM(createCtx(), BASE_CONFIG, FINAL_MESSAGE);
 		expect(result).toBeNull();
 		// 失败分支仍输出 failed 日志

package/src/__tests__/pure.test.ts

@@ -9,7 +9,6 @@ import { clearConfigCache, getConfigPath } from "@zhushanwen/pi-llm-shared";
 import {
 	DEFAULT_RENAME_CONFIG,
 	cleanTitle,
-	countAssistantReplies,
 	countSuccessfulAssistantReplies,
 	loadRenameConfig,
 	normalizeRenameConfig,
@@ -17,49 +16,6 @@ import {
 	setAutoRenameSwitch,
 } from "../pure.js";
 
-// ────────────────────────────────────────────────────
-// countAssistantReplies（保留，不变）
-// ────────────────────────────────────────────────────
-
-describe("countAssistantReplies", () => {
-	it("[user, assistant] → 1", () => {
-		const entries = [
-			{ type: "message", message: { role: "user" } },
-			{ type: "message", message: { role: "assistant" } },
-		];
-		expect(countAssistantReplies(entries)).toBe(1);
-	});
-
-	it("[user, assistant, user, assistant] → 2", () => {
-		const entries = [
-			{ type: "message", message: { role: "user" } },
-			{ type: "message", message: { role: "assistant" } },
-			{ type: "message", message: { role: "user" } },
-			{ type: "message", message: { role: "assistant" } },
-		];
-		expect(countAssistantReplies(entries)).toBe(2);
-	});
-
-	it("过滤非 message（thinkingLevelChange / modelChange）→ 1", () => {
-		const entries = [
-			{ type: "thinkingLevelChange" },
-			{ type: "message", message: { role: "user" } },
-			{ type: "message", message: { role: "assistant" } },
-			{ type: "modelChange" },
-		];
-		expect(countAssistantReplies(entries)).toBe(1);
-	});
-
-	it("[user, assistant, toolResult entry] → 1（非 message entry 不计）", () => {
-		const entries = [
-			{ type: "message", message: { role: "user" } },
-			{ type: "message", message: { role: "assistant" } },
-			{ type: "toolResult" },
-		];
-		expect(countAssistantReplies(entries)).toBe(1);
-	});
-});
-
 // ────────────────────────────────────────────────────
 // countSuccessfulAssistantReplies（D6：触发判定改用的成功-turn 计数）
 // ────────────────────────────────────────────────────

package/src/commands.ts

@@ -13,10 +13,10 @@ import { loadRenameConfig, saveRenameConfig, setAutoRenameSwitch } from "./pure.
  * - on → 只创建 flag（不写 config.enabled=true：避免 config 残留 true 导致旧 runtime 删 flag 后仍开启的错位）
  * - off → 先写 config.enabled=false（覆盖手写的 true），再删 flag（flag 是覆盖源，必须移除才真正关闭）
  *
- * 用法：
- *   /auto-rename         — 查看当前状态
- *   /auto-rename on      — 开启
- *   /auto-rename off     — 关闭
+ * 用法（enable/disable 是 on/off 的别名）：
+ *   /auto-rename                  — 查看当前状态
+ *   /auto-rename on | enable      — 开启
+ *   /auto-rename off | disable    — 关闭
  */
 export function executeAutoRenameCommand(args: string): string {
 	const trimmed = args.trim().toLowerCase();
@@ -24,7 +24,7 @@ export function executeAutoRenameCommand(args: string): string {
 	if (trimmed === "" || trimmed === "status") {
 		const { enabled } = loadRenameConfig();
 		const state = enabled ? "已开启 ✓" : "已关闭 ✗";
-		return `自动重命名会话：${state}\n用法：/auto-rename on | off | status`;
+		return `自动重命名会话：${state}\n用法：/auto-rename on | off | status（别名 enable / disable）`;
 	}
 
 	if (trimmed === "on" || trimmed === "enable") {
@@ -38,18 +38,20 @@ export function executeAutoRenameCommand(args: string): string {
 		return result.success ? "已关闭：自动重命名会话" : `设置失败：${result.error}`;
 	}
 
-	return `未知参数 "${args.trim()}"。\n用法：/auto-rename on | off | status`;
+	return `未知参数 "${args.trim()}"。\n用法：/auto-rename on | off | status（别名 enable / disable）`;
 }
 
 /** 注册 /auto-rename 命令。 */
 export function registerAutoRenameCommand(pi: ExtensionAPI): void {
 	pi.registerCommand("auto-rename", {
-		description: "控制自动重命名会话功能。/auto-rename [on|off|status]",
+		description: "控制自动重命名会话功能。/auto-rename [on|off|status]（别名 enable/disable）",
 		getArgumentCompletions(prefix: string) {
 			const trimmed = prefix.trimStart().toLowerCase();
 			const opts = [
 				{ label: "on", value: "on", description: "开启自动重命名" },
 				{ label: "off", value: "off", description: "关闭自动重命名" },
+				{ label: "enable", value: "enable", description: "开启自动重命名（on 别名）" },
+				{ label: "disable", value: "disable", description: "关闭自动重命名（off 别名）" },
 				{ label: "status", value: "status", description: "查看当前状态" },
 			];
 			return trimmed === "" ? opts : opts.filter((o) => o.label.startsWith(trimmed));

package/src/index.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
 
 import { registerAutoRenameCommand } from "./commands.js";
 import { callRenameLLM, debugLog as llmDebugLog, isSubagentSession } from "./llm.js";
@@ -26,6 +26,11 @@ interface TurnEndLikeEvent {
  * 新 session 首个成功 turn 完成后，用独立模型生成会话标题并 setSessionName 落库。
  */
 export default function renameSessionExtension(pi: ExtensionAPI): void {
+	// 日志通道注入（extension-logger 两阶段初始化：工厂拿 pi → setPiHandle，最早期调用）。
+	// 不注入则 logger.warn/error 只有文件日志通道（XYZ_AGENT_DEBUG=1），appendEntry
+	// （session entry，README「debug 证据链」的 E2E 断言数据源）不生效。
+	setPiHandle(pi);
+
 	registerAutoRenameCommand(pi);
 
 	pi.on("turn_end", async (event: TurnEndLikeEvent, ctx: ExtensionContext) => {

package/src/pure.ts

@@ -268,24 +268,6 @@ interface EntryLike {
 	message?: { role?: string; stopReason?: string };
 }
 
-/**
- * 数 session 中 assistant 回复数。用于判定首 turn（===1）。
- * 判定条件：entry.type === "message" && entry.message.role === "assistant"
- * （pi 内部 session-manager.ts 同款模式）。
- *
- * 注意：触发判定使用 countSuccessfulAssistantReplies（index.ts 已切换；不看 stopReason
- * 无法区分「iteration 结束」与「轮次结束」，见设计 D6）。本函数仅为兼容保留。
- */
-export function countAssistantReplies(entries: ReadonlyArray<EntryLike>): number {
-	let count = 0;
-	for (const entry of entries) {
-		if (entry.type === "message" && entry.message?.role === "assistant") {
-			count++;
-		}
-	}
-	return count;
-}
-
 /**
  * 数 session 中「成功完成」的 assistant 回复数（stopReason === "stop"），触发判定用（===1 触发 rename）。
  *