@zhushanwen/pi-evolve-daily 0.1.6 → 0.1.8

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@zhushanwen/pi-evolve-daily",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Daily evolution data collector — runs Python analyzer on first session of the day.",
   "type": "module",
+  "license": "MIT",
   "main": "src/index.ts",
   "pi": {
     "extensions": [

package/src/detectors/compact.ts

@@ -12,6 +12,12 @@ export interface CompactTrackedItem {
   detail?: string;
 }
 
+// ── ID generation constants ──────────────────────────
+
+const RANDOM_ID_RADIX = 36;
+const RANDOM_ID_SLICE_START = 2;
+const RANDOM_ID_SLICE_END = 7;
+
 export function createCompactDetector(problem: ProblemDefinition) {
   return {
     problemId: problem.id,
@@ -25,7 +31,7 @@ export function createCompactDetector(problem: ProblemDefinition) {
       compactionEntry?: { tokensBefore?: number };
     }): CompactTrackedItem {
       return {
-        id: `compact-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+        id: `compact-${Date.now()}-${Math.random().toString(RANDOM_ID_RADIX).slice(RANDOM_ID_SLICE_START, RANDOM_ID_SLICE_END)}`,
         problemId: problem.id as "compact-frequency",
         sessionId: "",
         tokensBefore: event.compactionEntry?.tokensBefore ?? 0,

package/src/detectors/goal-quality.ts

@@ -2,6 +2,12 @@
 
 import type { ProblemDefinition } from "../problems";
 
+// ── ID generation constants ──────────────────────────
+
+const RANDOM_ID_RADIX = 36;
+const RANDOM_ID_SLICE_START = 2;
+const RANDOM_ID_SLICE_END = 7;
+
 export interface GoalQualityTrackedItem {
   id: string;
   problemId: "goal-task-quality";
@@ -37,7 +43,7 @@ export function createGoalQualityDetector(problem: ProblemDefinition) {
       const total = tasks.length;
 
       return {
-        id: `goal-quality-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+        id: `goal-quality-${Date.now()}-${Math.random().toString(RANDOM_ID_RADIX).slice(RANDOM_ID_SLICE_START, RANDOM_ID_SLICE_END)}`,
         problemId: problem.id as "goal-task-quality",
         sessionId: "",
         goalId: "",

package/src/detectors/param-error.ts

@@ -2,6 +2,13 @@
 
 import type { ProblemDefinition } from "../problems";
 
+// ── ID generation constants ──────────────────────────
+
+const RANDOM_ID_RADIX = 36;
+const RANDOM_ID_SLICE_START = 2;
+const RANDOM_ID_SLICE_END = 7;
+const ERROR_PREVIEW_MAX_LENGTH = 200;
+
 export interface ParamErrorTrackedItem {
   id: string;
   problemId: "tool-param-validation";
@@ -70,12 +77,12 @@ export function createParamErrorDetector(problem: ProblemDefinition) {
     }): ParamErrorTrackedItem {
       const errorMessage = event.content ?? "";
       return {
-        id: `param-error-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+        id: `param-error-${Date.now()}-${Math.random().toString(RANDOM_ID_RADIX).slice(RANDOM_ID_SLICE_START, RANDOM_ID_SLICE_END)}`,
         problemId: problem.id as "tool-param-validation",
         sessionId: "",
         toolName: event.toolName ?? "unknown",
         errorType: classifyError(errorMessage),
-        errorPreview: errorMessage.slice(0, 200),
+        errorPreview: errorMessage.slice(0, ERROR_PREVIEW_MAX_LENGTH),
         status: "pending",
       };
     },

package/src/detectors/subagent-result.ts

@@ -2,6 +2,12 @@
 
 import type { ProblemDefinition } from "../problems";
 
+// ── ID generation constants ──────────────────────────
+
+const RANDOM_ID_RADIX = 36;
+const RANDOM_ID_SLICE_START = 2;
+const RANDOM_ID_SLICE_END = 7;
+
 export interface SubagentTrackedItem {
   id: string;
   problemId: "subagent-efficiency";
@@ -45,7 +51,7 @@ export function createSubagentDetector(problem: ProblemDefinition) {
       taskPrompt?: string;
     }): SubagentTrackedItem {
       return {
-        id: `subagent-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+        id: `subagent-${Date.now()}-${Math.random().toString(RANDOM_ID_RADIX).slice(RANDOM_ID_SLICE_START, RANDOM_ID_SLICE_END)}`,
         problemId: problem.id as "subagent-efficiency",
         sessionId: "",
         taskType: classifyTaskType(event.taskPrompt ?? ""),

package/src/index.ts

@@ -1,16 +1,17 @@
 // packages/evolve-daily/src/index.ts
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { existsSync, unlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { PROBLEM_REGISTRY } from "./problems";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
 import { createCompactDetector } from "./detectors/compact";
-import { createSubagentDetector } from "./detectors/subagent-result";
-import { createParamErrorDetector } from "./detectors/param-error";
 import { createGoalQualityDetector } from "./detectors/goal-quality";
+import { createParamErrorDetector } from "./detectors/param-error";
+import { createSubagentDetector } from "./detectors/subagent-result";
+import { PROBLEM_REGISTRY } from "./problems";
 import { createTracker } from "./trackers/core";
 import { skillExecutionConfig } from "./trackers/skill-execution";
 
@@ -21,6 +22,12 @@ const ANALYZER_PATH = join(EXT_DIR, "..", "analyzer", "analyze.py");
 // 运行时数据目录使用 Pi 平台约定路径（homedir + .pi/agent/）
 const REPORTS_DIR = join(homedir(), ".pi", "agent", "evolution-data", "daily-reports");
 
+const DATE_SLICE_END = 10;
+const ANALYZER_TIMEOUT_MS = 30_000;
+
+/** Pi API 的 on 方法重载签名（覆盖非标事件名） */
+type PiOnAny = { on(event: string, handler: (...args: unknown[]) => Promise<void> | void): void };
+
 /** tool_result 事件中匹配的工具结果 detector */
 interface ToolResultDetector {
   problemId: string;
@@ -30,8 +37,8 @@ interface ToolResultDetector {
 
 export default function evolveDailyExtension(pi: ExtensionAPI) {
   // ── L1: session_start 时调用 Python analyzer ──
-  pi.on("session_start", async () => {
-    const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+  pi.on("session_start", async (_event: unknown, ctx: ExtensionContext) => {
+    const today = new Date().toISOString().slice(0, DATE_SLICE_END); // YYYY-MM-DD
     const reportPath = join(REPORTS_DIR, `${today}.json`);
 
     if (existsSync(reportPath)) return;
@@ -48,12 +55,13 @@ export default function evolveDailyExtension(pi: ExtensionAPI) {
           "--output",
           reportPath,
         ],
-        { timeout: 30_000 }
+        { timeout: ANALYZER_TIMEOUT_MS, signal: ctx.signal }
       );
     } catch (e) {
       // Clean up partial output if analyzer failed mid-write
       try {
         unlinkSync(reportPath);
+      // eslint-disable-next-line taste/no-silent-catch
       } catch {
         /* already gone */
       }
@@ -69,9 +77,10 @@ export default function evolveDailyExtension(pi: ExtensionAPI) {
     PROBLEM_REGISTRY.find((p) => p.id === "compact-frequency")!
   );
 
-  (pi.on as any)("session_compact", async (event: Record<string, unknown>) => {
+  (pi as unknown as PiOnAny).on("session_compact", async (event: unknown) => {
+    const ev = event as Record<string, unknown>;
     try {
-      const item = compactDetector.createItem(event);
+      const item = compactDetector.createItem(ev);
       pi.appendEntry("evolve-feedback", {
         problemId: item.problemId,
         itemId: item.id,
@@ -79,6 +88,7 @@ export default function evolveDailyExtension(pi: ExtensionAPI) {
         detail: item.detail ?? null,
         timestamp: new Date().toISOString(),
       });
+    // eslint-disable-next-line taste/no-silent-catch
     } catch (e) {
       console.error(
         `[evolve-daily] compact detector error:`,
@@ -101,13 +111,14 @@ export default function evolveDailyExtension(pi: ExtensionAPI) {
     ),
   ];
 
-  (pi.on as any)(
+  (pi as unknown as PiOnAny).on(
     "tool_result",
-    async (event: Record<string, unknown>, _ctx?: unknown) => {
+    async (event: unknown, _ctx?: unknown) => {
+      const ev = event as Record<string, unknown>;
       for (const detector of toolDetectors) {
         try {
-          if (detector.match(event)) {
-            const item = detector.createItem(event);
+          if (detector.match(ev)) {
+            const item = detector.createItem(ev);
             pi.appendEntry("evolve-feedback", {
               problemId: item.problemId,
               itemId: item.id,
@@ -116,6 +127,7 @@ export default function evolveDailyExtension(pi: ExtensionAPI) {
               timestamp: new Date().toISOString(),
             });
           }
+        // eslint-disable-next-line taste/no-silent-catch
         } catch (e) {
           console.error(
             `[evolve-daily] detector ${detector.problemId} error:`,

package/src/problems.ts

@@ -49,17 +49,34 @@ interface TrackedItemTemplate {
   status: string;
 }
 
+// ── Severity thresholds ──────────────────────────────
+
+const COMPACT_HIGH_THRESHOLD = 3;
+const COMPACT_MEDIUM_THRESHOLD = 2;
+const CONTEXT_UTILIZATION_MEDIUM = 0.7;
+const CONTEXT_UTILIZATION_HIGH = 0.9;
+const GOAL_LOW_COMPLETION_HIGH = 0.5;
+const GOAL_HIGH_CANCEL = 0.4;
+const GOAL_LOW_COMPLETION_MEDIUM = 0.7;
+const GOAL_MEDIUM_CANCEL = 0.2;
+const SUBAGENT_FAILURE_MEDIUM = 0.2;
+const SUBAGENT_FAILURE_HIGH = 0.4;
+const PARAM_ERROR_MEDIUM = 0.1;
+const PARAM_ERROR_HIGH = 0.25;
+const WORKFLOW_PHASE_RATIO_HIGH = 0.7;
+const WORKFLOW_PHASE_RATIO_MEDIUM = 0.5;
+
 export const PROBLEM_REGISTRY: ProblemDefinition[] = [
   {
     id: "compact-frequency",
-    name: "Compact 频率",
+    name: "Compact Frequency",
     category: "context",
     severity: {
       metric: "custom",
       custom: (data) => {
         const rate = data.compactsPerSession as number;
-        if (rate >= 3) return "high";
-        if (rate >= 2) return "medium";
+        if (rate >= COMPACT_HIGH_THRESHOLD) return "high";
+        if (rate >= COMPACT_MEDIUM_THRESHOLD) return "medium";
         return "low";
       },
     },
@@ -68,103 +85,103 @@ export const PROBLEM_REGISTRY: ProblemDefinition[] = [
       match: { custom: "compactDetector" },
       template: { category: "context-pressure" },
       steering:
-        "检测到 Compact 触发(id={{id}})。请评估是否丢失了关键上下文。如有丢失，update status=error, detail='丢失的内容'。如无影响，update status=completed。",
+        "Compact triggered (id={{id}}). Evaluate whether critical context was lost. If lost, update status=error, detail='what was lost'. If unaffected, update status=completed.",
     },
     analysis: {
       extractor: "compact",
       minerRules: ["compact-high-frequency", "compact-early-trigger"],
     },
     suggestion: {
-      title: "优化 Compact 频率",
-      description: "Compact 频率过高，说明上下文管理效率低",
+      title: "Optimize Compact Frequency",
+      description: "High compact frequency indicates inefficient context management",
       defaultSeverity: "medium",
     },
   },
   {
     id: "context-utilization",
-    name: "上下文窗口利用率",
+    name: "Context Window Utilization",
     category: "context",
     severity: {
       metric: "rate",
-      thresholds: { medium: 0.7, high: 0.9 },
+      thresholds: { medium: CONTEXT_UTILIZATION_MEDIUM, high: CONTEXT_UTILIZATION_HIGH },
     },
     detector: {
       events: ["turn_end"],
       match: { custom: "contextUtilizationMatcher" },
       template: { category: "context-pressure" },
       steering:
-        "当前上下文利用率 {{usageRate}}(id={{id}})。如接近上限，update status=completed, detail='需要 compact'。如充足，update status=dismissed。",
+        "Current context utilization {{usageRate}} (id={{id}}). If near limit, update status=completed, detail='needs compact'. If sufficient, update status=dismissed.",
     },
     analysis: {
       extractor: "context",
       minerRules: ["context-high-utilization"],
     },
     suggestion: {
-      title: "优化上下文利用率",
-      description: "上下文利用率持续偏高，会触发频繁 compact",
+      title: "Optimize Context Utilization",
+      description: "Persistently high context utilization triggers frequent compacts",
       defaultSeverity: "medium",
     },
   },
   {
     id: "subagent-efficiency",
-    name: "Subagent 调度效率",
+    name: "Subagent Scheduling Efficiency",
     category: "subagent",
     severity: {
       metric: "rate",
-      thresholds: { medium: 0.2, high: 0.4 },
+      thresholds: { medium: SUBAGENT_FAILURE_MEDIUM, high: SUBAGENT_FAILURE_HIGH },
     },
     detector: {
       events: ["tool_result"],
       match: { toolName: "subagent", custom: "subagentResultMatcher" },
       template: { category: "subagent" },
       steering:
-        "Subagent 任务完成(id={{id}})。exitCode={{exitCode}}, 耗时={{duration}}。如结果满意，update status=completed。如需重做，update status=error, detail='问题原因'。",
+        "Subagent task completed (id={{id}}). exitCode={{exitCode}}, duration={{duration}}. If satisfactory, update status=completed. If retry needed, update status=error, detail='reason'.",
     },
     analysis: {
       extractor: "subagent",
       minerRules: ["subagent-failure-rate", "subagent-high-retry"],
     },
     suggestion: {
-      title: "优化 Subagent 调度效率",
-      description: "Subagent 失败率或重试率过高",
+      title: "Optimize Subagent Scheduling",
+      description: "High subagent failure or retry rate",
       defaultSeverity: "medium",
     },
   },
   {
     id: "tool-param-validation",
-    name: "工具参数校验失败",
+    name: "Tool Parameter Validation Failure",
     category: "tool",
     severity: {
       metric: "rate",
-      thresholds: { medium: 0.1, high: 0.25 },
+      thresholds: { medium: PARAM_ERROR_MEDIUM, high: PARAM_ERROR_HIGH },
     },
     detector: {
       events: ["tool_result"],
       match: { isError: true, custom: "paramErrorMatcher" },
       template: { category: "tool-error" },
       steering:
-        "检测到 {{toolName}} 参数错误(id={{id}})。错误: {{errorPreview}}。如已理解原因，update status=completed, detail='错误原因和修正方式'。如不确定，update status=error。",
+        "Detected {{toolName}} parameter error (id={{id}}). Error: {{errorPreview}}. If cause understood, update status=completed, detail='cause and fix'. If unclear, update status=error.",
     },
     analysis: {
       extractor: "tool_errors",
       minerRules: ["param-error-rate", "edit-match-failure", "low-self-correction"],
     },
     suggestion: {
-      title: "降低工具参数错误率",
-      description: "参数错误率高，说明 AI 不理解工具用法",
+      title: "Reduce Tool Parameter Error Rate",
+      description: "High parameter error rate suggests the AI does not understand tool usage",
       defaultSeverity: "high",
     },
   },
   {
     id: "workflow-phase-duration",
-    name: "工作流阶段耗时",
+    name: "Workflow Phase Duration",
     category: "workflow",
     severity: {
       metric: "custom",
       custom: (data) => {
         const maxPhaseRatio = data.maxPhaseDurationRatio as number;
-        if (maxPhaseRatio > 0.7) return "high";
-        if (maxPhaseRatio > 0.5) return "medium";
+        if (maxPhaseRatio > WORKFLOW_PHASE_RATIO_HIGH) return "high";
+        if (maxPhaseRatio > WORKFLOW_PHASE_RATIO_MEDIUM) return "medium";
         return "low";
       },
     },
@@ -173,29 +190,29 @@ export const PROBLEM_REGISTRY: ProblemDefinition[] = [
       match: { toolName: ["coding-workflow-gate", "coding-workflow-phase-start"] },
       template: { category: "workflow" },
       steering:
-        "工作流阶段 {{phase}} 完成(id={{id}})。gate={{gateResult}}, 耗时={{duration}}。如阶段顺利，update status=completed。如有问题，update status=error, detail='问题描述'。",
+        "Workflow phase {{phase}} completed (id={{id}}). gate={{gateResult}}, duration={{duration}}. If smooth, update status=completed. If issues, update status=error, detail='issue description'.",
     },
     analysis: {
       extractor: "workflow",
       minerRules: ["workflow-slow-phase", "workflow-gate-retry"],
     },
     suggestion: {
-      title: "优化工作流阶段效率",
-      description: "某阶段耗时占比过高或 gate 重试频繁",
+      title: "Optimize Workflow Phase Efficiency",
+      description: "Disproportionate phase duration or frequent gate retries",
       defaultSeverity: "medium",
     },
   },
   {
     id: "goal-task-quality",
-    name: "Goal 任务拆分质量",
+    name: "Goal Task Decomposition Quality",
     category: "workflow",
     severity: {
       metric: "custom",
       custom: (data) => {
         const completionRate = data.taskCompletionRate as number;
         const cancelRate = data.taskCancelRate as number;
-        if (completionRate < 0.5 || cancelRate > 0.4) return "high";
-        if (completionRate < 0.7 || cancelRate > 0.2) return "medium";
+        if (completionRate < GOAL_LOW_COMPLETION_HIGH || cancelRate > GOAL_HIGH_CANCEL) return "high";
+        if (completionRate < GOAL_LOW_COMPLETION_MEDIUM || cancelRate > GOAL_MEDIUM_CANCEL) return "medium";
         return "low";
       },
     },
@@ -204,7 +221,7 @@ export const PROBLEM_REGISTRY: ProblemDefinition[] = [
       match: { toolName: "goal_manager", custom: "goalQualityMatcher" },
       template: { category: "workflow" },
       steering:
-        "Goal 任务更新(id={{id}})。任务完成率={{completionRate}}。如目标达成，update status=completed, detail='目标完成情况'。如遇到困难，update status=error, detail='困难描述'。",
+        "Goal task updated (id={{id}}). Completion rate={{completionRate}}. If objective met, update status=completed, detail='completion summary'. If blocked, update status=error, detail='blocker description'.",
     },
     analysis: {
       extractor: "goal_quality",
@@ -216,8 +233,8 @@ export const PROBLEM_REGISTRY: ProblemDefinition[] = [
       ],
     },
     suggestion: {
-      title: "优化 Goal 任务拆分质量",
-      description: "任务完成率低或 Evidence 质量低",
+      title: "Optimize Goal Task Decomposition",
+      description: "Low task completion rate or poor evidence quality",
       defaultSeverity: "high",
     },
   },

package/src/trackers/core.ts

@@ -13,7 +13,7 @@ import type {
   Theme,
 } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
-
+import type { Static } from "typebox";
 
 import {
   canTransition,
@@ -21,13 +21,46 @@ import {
   deserializeState,
   isTerminalStatus,
   serializeState,
-  TrackerParams,
-
   type TrackedItem,
+  type TrackedItemStatus,
   type TrackerDetails,
+  TrackerParams,
   type TrackerRuntimeState,
 } from "./types";
 
+// ── Pi SDK custom event API type ──────────────────────
+
+type PiOnAny = {
+  on(event: string, handler: (...args: unknown[]) => unknown): void;
+};
+
+// ── Stale context detection ──────────────────────────
+
+const STALE_CONTEXT_PATTERNS = [
+  "Extension context no longer active",
+  "aborted",
+  "context canceled",
+  "stale context",
+  "stalecontext",
+];
+
+/** Detect errors that indicate the Pi session has been torn down (compact/reload/exit). */
+function isStaleContextError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const msg = error.message.toLowerCase();
+  return STALE_CONTEXT_PATTERNS.some((p) => msg.includes(p));
+}
+
+// ── Tool execute/render param types ──────────────────
+
+type RenderOptions = { expanded?: boolean };
+
+type ToolResult = {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown> | undefined;
+  isError?: boolean;
+};
+
 // ── Tracker 配置接口（避免 types.ts 引入 Pi API 类型）──
 
 export interface TrackerConfig<TMeta = Record<string, unknown>> {
@@ -78,7 +111,7 @@ function formatItemList<TMeta>(
   items: TrackedItem<TMeta>[],
   trackerName: string,
 ): string {
-  if (items.length === 0) return `无活跃追踪（${trackerName}）。`;
+  if (items.length === 0) return `No active tracked items (${trackerName}).`;
   return items
     .map(
       (item) =>
@@ -89,6 +122,74 @@ function formatItemList<TMeta>(
     .join("\n");
 }
 
+// ── Tool render helpers (extracted to keep createTracker ≤300 lines) ──
+
+function renderTrackerCall<TMeta>(
+  args: Record<string, unknown>,
+  config: TrackerConfig<TMeta>,
+  theme: Theme,
+): Text {
+  const parts = [
+    theme.fg("toolTitle", theme.bold(`${config.toolName} `)),
+    theme.fg("muted", String(args.action ?? "")),
+  ];
+  if (args.id !== undefined)
+    parts.push(theme.fg("accent", `#${String(args.id)}`));
+  if (args.status !== undefined)
+    parts.push(theme.fg("warning", String(args.status)));
+  if (args.detail !== undefined)
+    parts.push(theme.fg("dim", `"${String(args.detail)}"`));
+  return new Text(parts.join(" "), 0, 0);
+}
+
+function renderTrackerResult<TMeta>(
+  result: ToolResult,
+  options: RenderOptions,
+  config: TrackerConfig<TMeta>,
+  theme: Theme,
+): Text {
+  if (config.renderResult && result.details) {
+    return config.renderResult(
+      result.details as unknown as TrackerDetails<TMeta>,
+      options,
+      theme,
+    );
+  }
+
+  if (!result.details) {
+    return new Text(theme.fg("dim", "(no details)"), 0, 0);
+  }
+
+  // 框架默认渲染
+  const details = result.details as unknown as TrackerDetails<TMeta>;
+  if (details.error) {
+    return new Text(
+      theme.fg("error", `[${config.name}] Error: ${details.error}`),
+      0,
+      0,
+    );
+  }
+
+  const prefix = theme.fg("accent", `[${config.name}] `);
+  const summary = `${details.action}: ${details.items.length} items`;
+
+  if (!options.expanded) {
+    return new Text(prefix + theme.fg("dim", summary), 0, 0);
+  }
+
+  const items = details.items
+    .map((item) => {
+      const terminal = isTerminalStatus(item.status) ? " ✓" : "";
+      return `  #${item.id} ${item.name} [${item.status}]${terminal}`;
+    })
+    .join("\n");
+  return new Text(
+    prefix + summary + "\n" + theme.fg("dim", items),
+    0,
+    0,
+  );
+}
+
 // ── 工厂函数 ────────────────────────────────────────
 
 export function createTracker<TMeta>(
@@ -100,8 +201,19 @@ export function createTracker<TMeta>(
   // ── 持久化 + GC ───────────────────────────────────
 
   function persistState(ctx: ExtensionContext): void {
-    pi.appendEntry(config.entryType, serializeState(state));
-    const entries = ctx.sessionManager.getEntries();
+    let entries: SessionEntry[];
+    try {
+      pi.appendEntry(config.entryType, serializeState(state));
+      entries = ctx.sessionManager.getEntries();
+    } catch (e) {
+      if (isStaleContextError(e)) {
+        console.warn(
+          `[${config.name}] skip persist: stale context (${(e as Error).message})`,
+        );
+        return;
+      }
+      throw e;
+    }
     const staleIndices: number[] = [];
     let foundLatest = false;
     for (let i = entries.length - 1; i >= 0; i--) {
@@ -121,7 +233,19 @@ export function createTracker<TMeta>(
   // ── 状态恢复 ──────────────────────────────────────
 
   function reconstructState(ctx: ExtensionContext): void {
-    const entries = ctx.sessionManager.getEntries();
+    let entries: SessionEntry[];
+    try {
+      entries = ctx.sessionManager.getEntries();
+    } catch (e) {
+      if (isStaleContextError(e)) {
+        console.warn(
+          `[${config.name}] skip reconstruct: stale context (${(e as Error).message})`,
+        );
+        state = createInitialState<TMeta>();
+        return;
+      }
+      throw e;
+    }
     const allTypes = [config.entryType, ...(config.legacyEntryTypes ?? [])];
 
     let latestData: Record<string, unknown> | undefined;
@@ -181,10 +305,10 @@ export function createTracker<TMeta>(
   // ── Event: triggerEvent (e.g. tool_call) ───────────
 
   // Pi 事件系统支持任意字符串事件名，但类型定义不完整（与 session_compact 同）
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  (pi as any).on(
+  (pi as unknown as PiOnAny).on(
     config.triggerEvent,
-    async (event: unknown, ctx: ExtensionContext) => {
+    async (event, nextCtx) => {
+      const ctx = nextCtx as ExtensionContext;
       const match = config.triggerMatch(event);
       if (!match) return;
 
@@ -223,10 +347,11 @@ export function createTracker<TMeta>(
 
   // ── Event: turn_end（remind 检查）─────────────────
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  (pi as any).on(
+  (pi as unknown as PiOnAny).on(
     "turn_end",
-    async (event: Record<string, unknown>, ctx: ExtensionContext) => {
+    async (rawEvent, nextCtx) => {
+      const event = rawEvent as Record<string, unknown>;
+      const ctx = nextCtx as ExtensionContext;
       const eventTurnIndex = event.turnIndex;
       if (typeof eventTurnIndex === "number") {
         state.currentTurnIndex = eventTurnIndex;
@@ -285,8 +410,7 @@ export function createTracker<TMeta>(
     pi.registerMessageRenderer(
       customType,
       (
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        message: any,
+        message: { content: string | unknown },
         _options: unknown,
         theme: Theme,
       ) => {
@@ -313,14 +437,13 @@ export function createTracker<TMeta>(
     promptGuidelines: config.promptGuidelines,
     parameters: TrackerParams,
 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async execute(
       _toolCallId: string,
-      params: any,
-      _signal: any,
-      _onUpdate: any,
+      params: Static<typeof TrackerParams>,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
       ctx: ExtensionContext,
-    ): Promise<any> {
+    ): Promise<ToolResult> {
       // ── list ──
       if (params.action === "list") {
         return {
@@ -339,30 +462,32 @@ export function createTracker<TMeta>(
       }
 
       // ── update ──
-      if (params.id === undefined) {
-        return { content: [{ type: "text", text: "update 操作需要 id 参数" }], isError: true };
+      const updateId = params.id as number | undefined;
+      const updateStatus = params.status as string | undefined;
+      if (updateId === undefined) {
+        return { content: [{ type: "text", text: "update action requires id parameter" }], details: undefined, isError: true };
       }
-      if (params.status === undefined) {
-        return { content: [{ type: "text", text: "update 操作需要 status 参数" }], isError: true };
+      if (updateStatus === undefined) {
+        return { content: [{ type: "text", text: "update action requires status parameter" }], details: undefined, isError: true };
       }
 
       const itemIndex = state.items.findIndex(
-        (item) => item.id === params.id,
+        (item) => item.id === updateId,
       );
       if (itemIndex === -1) {
-        return { content: [{ type: "text", text: `TrackedItem id=${params.id} 不存在` }], isError: true };
+        return { content: [{ type: "text", text: `TrackedItem id=${updateId} not found` }], details: undefined, isError: true };
       }
 
       const item = state.items[itemIndex];
-      if (!canTransition(item.status, params.status)) {
-        return { content: [{ type: "text", text: `非法转换: ${item.status} → ${params.status}（当前 ${item.status}，终态不可变更或该路径不允许）` }], isError: true };
+      if (!canTransition(item.status, updateStatus as TrackedItemStatus)) {
+        return { content: [{ type: "text", text: `Invalid transition: ${item.status} → ${updateStatus} (current: ${item.status}, terminal states are immutable or path not allowed)` }], details: undefined, isError: true };
       }
 
       // 执行转换
-      item.status = params.status;
-      item.detail = params.detail ?? item.detail;
+      item.status = updateStatus as TrackedItemStatus;
+      item.detail = (params.detail as string | undefined | null) ?? item.detail;
 
-      if (params.status === "error") {
+      if (updateStatus === "error") {
         item.errorCount += 1;
         if (item.errorCount >= config.errorThreshold) {
           await pi.sendUserMessage(config.steering.onError(item), {
@@ -373,7 +498,7 @@ export function createTracker<TMeta>(
 
       persistState(ctx);
 
-      const statusText = isTerminalStatus(item.status) ? "（终态）" : "";
+      const statusText = isTerminalStatus(item.status) ? " (terminal)" : "";
       return {
         content: [
           {
@@ -390,68 +515,21 @@ export function createTracker<TMeta>(
       };
     },
 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     renderCall(
-      args: any,
+      args: Record<string, unknown>,
       theme: Theme,
       _context?: unknown,
     ) {
-      const parts = [
-        theme.fg("toolTitle", theme.bold(`${config.toolName} `)),
-        theme.fg("muted", String(args.action ?? "")),
-      ];
-      if (args.id !== undefined)
-        parts.push(theme.fg("accent", `#${String(args.id)}`));
-      if (args.status !== undefined)
-        parts.push(theme.fg("warning", String(args.status)));
-      if (args.detail !== undefined)
-        parts.push(theme.fg("dim", `"${String(args.detail)}"`));
-      return new Text(parts.join(" "), 0, 0);
+      return renderTrackerCall(args, config, theme);
     },
 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     renderResult(
-      result: any,
-      options: any,
+      result: { content: Array<{ type: "text"; text?: string } | { type: "image"; data: string; mimeType: string }>; details?: Record<string, unknown> },
+      _options: unknown,
       theme: Theme,
       _context?: unknown,
     ) {
-      if (config.renderResult) {
-        return config.renderResult(
-          result.details as TrackerDetails<TMeta>,
-          options,
-          theme,
-        );
-      }
-
-      // 框架默认渲染
-      const details = result.details as TrackerDetails<TMeta>;
-      if (details.error) {
-        return new Text(
-          theme.fg("error", `[${config.name}] 错误: ${details.error}`),
-          0,
-          0,
-        );
-      }
-
-      const prefix = theme.fg("accent", `[${config.name}] `);
-      const summary = `${details.action}: ${details.items.length} items`;
-
-      if (!options.expanded) {
-        return new Text(prefix + theme.fg("dim", summary), 0, 0);
-      }
-
-      const items = details.items
-        .map((item) => {
-          const terminal = isTerminalStatus(item.status) ? " ✓" : "";
-          return `  #${item.id} ${item.name} [${item.status}]${terminal}`;
-        })
-        .join("\n");
-      return new Text(
-        prefix + summary + "\n" + theme.fg("dim", items),
-        0,
-        0,
-      );
+      return renderTrackerResult(result as ToolResult, { expanded: (_options as Record<string, unknown> | undefined)?.expanded as boolean | undefined }, config, theme);
     },
   });
 }

package/src/trackers/skill-execution.ts

@@ -5,8 +5,8 @@
  * 追踪 skill 的加载、执行、异常、记录全生命周期。
  */
 
-import type { TrackedItem } from "./types";
 import type { TrackerConfig } from "./core";
+import type { TrackedItem } from "./types";
 
 // ── Metadata 类型 ───────────────────────────────────
 
@@ -32,9 +32,9 @@ export function extractSkillName(path: string): string | null {
 
 function loadedSteeringPrompt(name: string, id: number): string {
   return (
-    `[SKILL-STATE] skill "${name}" 已加载并开始追踪（id=${id}）。\n` +
-    `执行完成后调用 skill_state(action=update, id=${id}, status=completed)。\n` +
-    `遇到困难时调用 skill_state(action=update, id=${id}, status=error, detail="原因")。`
+    `[SKILL-STATE] skill "${name}" loaded and tracking started (id=${id}).\n` +
+    `When done, call skill_state(action=update, id=${id}, status=completed).\n` +
+    `If blocked, call skill_state(action=update, id=${id}, status=error, detail="reason").`
   );
 }
 
@@ -42,17 +42,17 @@ function remindSteeringPrompt(
   name: string,
   turnsSinceLoad: number,
 ): string {
-  return `[SKILL-STATE] skill "${name}" 已加载 ${turnsSinceLoad} turn 未终态，请调用 skill_state 工具流转状态。`;
+  return `[SKILL-STATE] skill "${name}" loaded ${turnsSinceLoad} turns ago without reaching terminal state. Please call skill_state to update its status.`;
 }
 
 function errorForceRecordPrompt(item: TrackedItem<SkillMeta>): string {
   return (
-    `[SKILL-STATE] skill "${item.name}" 异常次数已达 ${item.errorCount} 次，需要记录问题。\n` +
-    `请立即调用 subagent 工具（background 模式），任务如下：\n` +
-    `1. 读取 ${item.metadata.skillMdPath}\n` +
-    `2. 根据当前 session 上下文分析 skill "${item.name}" 执行中遇到的问题\n` +
-    `3. 生成结构化问题记录（skill 名称、异常次数、问题描述、改进建议）\n` +
-    `完成后调用 skill_state(action=update, id=${item.id}, status=recorded) 标记记录完成。`
+    `[SKILL-STATE] skill "${item.name}" has reached ${item.errorCount} errors — issue recording required.\n` +
+    `Immediately call the subagent tool (background mode) with this task:\n` +
+    `1. Read ${item.metadata.skillMdPath}\n` +
+    `2. Analyze issues encountered during skill "${item.name}" execution based on current session context\n` +
+    `3. Generate a structured issue record (skill name, error count, issue description, improvement suggestions)\n` +
+    `After completion, call skill_state(action=update, id=${item.id}, status=recorded).`
   );
 }
 
@@ -62,7 +62,7 @@ function agentStartContextPrompt(items: TrackedItem<SkillMeta>[]): string {
     (item) => `  - "${item.name}" (id=${item.id}, status=${item.status})`,
   );
   return (
-    `[SKILL-STATE] 以下 skill 正在追踪中，请适时调用 skill_state 工具流转状态：\n` +
+    `[SKILL-STATE] The following skills are being tracked — call skill_state to update their status when appropriate:\n` +
     lines.join("\n")
   );
 }
@@ -74,17 +74,17 @@ export const skillExecutionConfig: TrackerConfig<SkillMeta> = {
   toolName: "skill_state",
   label: "Skill State",
   description:
-    "管理 skill 执行追踪状态。" +
-    "\n\n可用 action：" +
-    "\n- list：查看所有 TrackedItem" +
-    "\n- update：更新 TrackedItem 状态（需要 id 和 status）",
-  promptSnippet: "追踪 skill 执行状态，自动检测 skill 加载",
+    "Manage skill execution tracking state." +
+    "\n\nAvailable actions:" +
+    "\n- list: View all TrackedItems" +
+    "\n- update: Update TrackedItem status (requires id and status)",
+  promptSnippet: "Track skill execution status with automatic skill load detection",
   promptGuidelines: [
-    "[触发] skill 加载时自动创建追踪，无需手动创建",
-    "[流转] 执行完成后用 update status=completed 标记成功",
-    "[异常] 遇到困难时用 update status=error 标记异常",
-    "[记录] 异常累积 2 次后系统会要求记录问题，完成后 update status=recorded",
-    "[查询] 随时用 list 查看所有追踪状态",
+    "[Trigger] Tracking is auto-created when a skill loads — no manual creation needed",
+    "[Transition] After execution, use update status=completed to mark success",
+    "[Error] When blocked, use update status=error to mark the exception",
+    "[Record] After 2 accumulated errors, the system requests issue recording — when done, update status=recorded",
+    "[Query] Use list anytime to view all tracking states",
   ],
 
   triggerEvent: "tool_call",

package/src/trackers/types.ts

@@ -79,15 +79,15 @@ export interface TrackerDetails<
 export const TrackerParams = Type.Object({
   action: StringEnum(["update", "list"] as const),
   id: Type.Optional(
-    Type.Number({ description: "TrackedItem ID（update 必填）" }),
+    Type.Number({ description: "TrackedItem ID (required for update)" }),
   ),
   status: Type.Optional(
     StringEnum(["completed", "error", "recorded"] as const, {
-      description: "目标状态（update 必填）",
+      description: "Target status (required for update)",
     }),
   ),
   detail: Type.Optional(
-    Type.String({ description: "附加说明（如 error 原因）" }),
+    Type.String({ description: "Additional notes (e.g. error reason)" }),
   ),
 });