@zhushanwen/pi-system-prompt 1.0.2 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-system-prompt",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "System prompt injection extension for Pi — reads config and appends to system prompt",
   "type": "module",
   "main": "src/index.ts",
@@ -31,6 +31,9 @@
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8"
   },
+  "dependencies": {
+    "@zhushanwen/pi-extension-logger": "0.3.0"
+  },
   "scripts": {
     "typecheck": "npx tsc --noEmit",
     "test": "vitest run"

package/src/__tests__/system-prompt.test.ts

@@ -8,7 +8,7 @@
  *   swap 注入顺序两行的 mutant 会被顺序用例 kill）
  * - -nc / --no-context-files 守卫：global 注入跳过、append 不受影响
  * - global 候选选择：候选序优先、空白内容跳过继续找、目录缺失降级
- * - fail-safe：handler 全程 throw → return undefined + stderr 可观测；stderr 写失败的
+ * - fail-safe：handler 全程 throw → return undefined + logger.error 可观测；logger 自身抛错的
  *   终极兜底 console.debug；systemPrompt 非法类型的旧 quirk 锚定
  *
  * mock 策略（参照 msg-id-mapper 测试模式）：pi SDK import type 零运行时解析，
@@ -17,6 +17,14 @@
  * 运行：cd extensions/taiji/system-prompt && npx vitest run
  */
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}))
+vi.mock('@zhushanwen/pi-extension-logger', () => ({
+  getLogger: () => loggerMock,
+  createLogger: () => loggerMock,
+}))
+
 import { readFileSync, readdirSync, statSync } from 'node:fs'
 import path from 'node:path'
 import createExtension from '../index'
@@ -66,7 +74,11 @@ interface FsSetup {
   globalFiles?: Record<string, string | Error>
 }
 
+/** mtime 纪元：每次 setupFs 递增，模拟「文件被改写后 mtime 变化」。 */
+let mtimeEpoch = 0
+
 function setupFs(setup: FsSetup = {}): void {
+  mtimeEpoch += 1
   const { config = new Error("ENOENT: no such file or directory, open '" + CONFIG_PATH + "'") } = setup
   const { globalEntries = [], globalFiles = {} } = setup
   vi.mocked(readdirSync).mockImplementation(() => {
@@ -74,10 +86,18 @@ function setupFs(setup: FsSetup = {}): void {
     return globalEntries as unknown as string[]
   })
   vi.mocked(statSync).mockImplementation((p: unknown) => {
+    // config 文件可 stat（内容存在时）——cachedReadFileSync 先 stat 判 mtime 再读，
+    // config 缺失（Error）时 stat 同步 throw（等价 ENOENT）
+    if (String(p) === CONFIG_PATH) {
+      if (config instanceof Error) throw config
+      return { isFile: () => true, mtimeMs: mtimeEpoch } as unknown as ReturnType<typeof statSync>
+    }
     const name = path.basename(String(p))
     if (!(name in globalFiles)) throw new Error('ENOENT stat ' + String(p))
     if (globalFiles[name] instanceof Error) throw globalFiles[name]
-    return { isFile: () => true } as unknown as ReturnType<typeof statSync>
+    // mtimeMs 模拟真实 mtime：每次 setupFs 递增一次纪元——同一 setup 内稳定（缓存命中），
+    // 重新 setupFs（等价改文件）后变化（缓存失效重读），与 cachedReadFileSync 判变语义对齐。
+    return { isFile: () => true, mtimeMs: mtimeEpoch } as unknown as ReturnType<typeof statSync>
   })
   vi.mocked(readFileSync).mockImplementation((p: unknown) => {
     const fp = String(p)
@@ -259,8 +279,7 @@ describe('global 候选文件选择（readGlobalAgentsFile）', () => {
 })
 
 describe('fail-safe（外层 catch return undefined，永不阻断 agent loop）', () => {
-  it('handler 全程 throw（systemPrompt getter 抛错）→ return undefined + stderr 落盘可观测', () => {
-    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true)
+  it('handler 全程 throw（systemPrompt getter 抛错）→ return undefined + logger.error 落盘可观测', () => {
     const h = createHarness()
     const event = { type: 'before_agent_start', prompt: 'hi' } as unknown as BeforeAgentStartEvent
     Object.defineProperty(event, 'systemPrompt', {
@@ -269,16 +288,16 @@ describe('fail-safe（外层 catch return undefined，永不阻断 agent loop）
       },
     })
     expect(h.beforeAgentStart(event)).toBeUndefined()
-    expect(stderrSpy).toHaveBeenCalledWith(
-      expect.stringContaining('[xyz-system-prompt-extension] before_agent_start hook failed: Error: getter boom'),
+    expect(loggerMock.error).toHaveBeenCalledWith(
+      'before_agent_start hook failed: Error: getter boom',
     )
   })
 
-  it('stderr 写失败的终极兜底 → console.debug 吞掉，仍 return undefined', () => {
-    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => {
-      throw new Error('stderr gone')
+  it('logger 自身抛错的终极兜底 → stderr 兜底，仍 return undefined', () => {
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true)
+    loggerMock.error.mockImplementation(() => {
+      throw new Error('logger gone')
     })
-    const debugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {})
     const h = createHarness()
     const event = { type: 'before_agent_start', prompt: 'hi' } as unknown as BeforeAgentStartEvent
     Object.defineProperty(event, 'systemPrompt', {
@@ -287,9 +306,8 @@ describe('fail-safe（外层 catch return undefined，永不阻断 agent loop）
       },
     })
     expect(h.beforeAgentStart(event)).toBeUndefined()
-    expect(debugSpy).toHaveBeenCalledWith(
-      expect.stringContaining('[xyz-system-prompt-extension] stderr write also failed:'),
-      expect.any(Error),
+    expect(stderrSpy).toHaveBeenCalledWith(
+      expect.stringContaining('logHookFailure also failed'),
     )
   })
 
@@ -309,3 +327,33 @@ describe('fail-safe（外层 catch return undefined，永不阻断 agent loop）
     expect(h.beforeAgentStart(event)).toEqual({ systemPrompt: '\n\nAPPEND-TEXT' })
   })
 })
+
+describe('cachedReadFileSync（mtime 级内容缓存，KV-cache 稳定性改造）', () => {
+  it('文件未变时二次 hook 不再重复 readFileSync（缓存命中）', () => {
+    setupFs({
+      config: '{"append": {"enabled": true, "prompt": "P1"}}',
+      globalEntries: ['AGENTS.md'],
+      globalFiles: { 'AGENTS.md': '# GLOBAL' },
+    })
+    const r1 = runHook('base')
+    const reads1 = vi.mocked(readFileSync).mock.calls.length
+    const r2 = runHook('base')
+    expect(r2).toEqual(r1) // 两次注入结果逐字节一致
+    expect(vi.mocked(readFileSync).mock.calls.length).toBe(reads1) // 第二次全命中缓存，零重读
+  })
+
+  it('文件改写（mtime 变）后下一轮 hook 读到新内容（变更即生效语义保留）', () => {
+    setupFs({ config: '{"append": {"enabled": true, "prompt": "P1"}}' })
+    expect(runHook('base')).toEqual({ systemPrompt: 'base\n\nP1' })
+    // 模拟用户改写 append.prompt（setupFs 递增 mtime 纪元）
+    setupFs({ config: '{"append": {"enabled": true, "prompt": "P2"}}' })
+    expect(runHook('base')).toEqual({ systemPrompt: 'base\n\nP2' })
+  })
+
+  it('文件删除（stat throw）后缓存驱逐，注入降级为无 append', () => {
+    setupFs({ config: '{"append": {"enabled": true, "prompt": "P1"}}' })
+    expect(runHook('base')).toEqual({ systemPrompt: 'base\n\nP1' })
+    setupFs() // config 恢复默认 ENOENT
+    expect(runHook('base')).toBeUndefined()
+  })
+})

package/src/index.ts

@@ -2,7 +2,8 @@
  * System prompt injection extension for Pi.
  *
  * Registers a `before_agent_start` hook that:
- *  1. Reads <dataDir>/system-prompt.json every turn (never cached).
+ *  1. Reads <dataDir>/system-prompt.json every turn (mtime-cached, see
+ *     `cachedReadFileSync`).
  *  2. When `append.enabled === true` and `append.prompt` is non-blank,
  *     appends the user's text to the event's systemPrompt.
  *  3. Reads the global instructions file `~/.agents/AGENTS.md` (candidates
@@ -24,9 +25,37 @@ import path from 'node:path'
 import { homedir } from 'node:os'
 import { readFileSync, readdirSync, statSync } from 'node:fs'
 import type { ExtensionAPI, BeforeAgentStartEvent } from '@earendil-works/pi-coding-agent'
+import { getLogger } from '@zhushanwen/pi-extension-logger'
+
+const logger = getLogger('xyz-system-prompt-extension')
 
 const CONFIG_FILE = 'system-prompt.json'
 
+/**
+ * mtime 级文件内容缓存（KV-cache 稳定性改造）：每 turn 仍 stat 判变（文件被编辑后
+ * 下一轮即读到新内容，语义与逐 turn 重读一致），但 mtime 未变时跳过 readFileSync——
+ * 注入文本进每 turn system prompt，读盘路径上不引入额外开销。进程级缓存，per-process
+ * = per-session，生命周期对齐。stat/read 失败 → 驱逐条目返回 null。
+ *
+ * @data-owner 文件本身（mtime+size 判变读缓存，非派生权威，无第二写入者）
+ */
+const fileContentCache = new Map<string, { mtimeMs: number; size: number; content: string }>()
+
+function cachedReadFileSync(filePath: string): string | null {
+  try {
+    const stat = statSync(filePath)
+    const entry = fileContentCache.get(filePath)
+    // 双键判变：mtimeMs 相同粒度内被外部编辑器/脚本覆写且长度变化时 size 仍能命中
+    if (entry && entry.mtimeMs === stat.mtimeMs && entry.size === stat.size) return entry.content
+    const content = readFileSync(filePath, 'utf-8')
+    fileContentCache.set(filePath, { mtimeMs: stat.mtimeMs, size: stat.size, content })
+    return content
+  } catch {
+    fileContentCache.delete(filePath)
+    return null
+  }
+}
+
 /** Global instruction candidates, mirroring pi's loadContextFileFromDir. */
 const GLOBAL_AGENTS_CANDIDATES = ['AGENTS.md', 'AGENTS.MD', 'CLAUDE.md', 'CLAUDE.MD']
 
@@ -88,14 +117,14 @@ function readGlobalAgentsFile(): { path: string; content: string } | null {
     const filePath = path.join(dir, name)
     try {
       if (statSync(filePath).isFile()) {
-        const content = readFileSync(filePath, 'utf-8')
-        if (content.trim()) {
+        const content = cachedReadFileSync(filePath)
+        if (content !== null && content.trim()) {
           return { path: filePath, content }
         }
       }
     } catch (err) {
       // best-effort：候选文件 stat/read 失败（如权限）→ 试下一个候选，never throw into the agent loop。
-      console.debug('[xyz-system-prompt-extension] candidate file read failed, trying next:', err)
+      logger.debug('candidate file read failed, trying next', { detail: String(err) })
     }
   }
   return null
@@ -131,7 +160,9 @@ function readConfig(dataDir: string): {
 /** Read a JSON file and return it as an object; missing / malformed / non-object → null. */
 function readJsonIfValid(filePath: string): Record<string, unknown> | null {
   try {
-    const parsed: unknown = JSON.parse(readFileSync(filePath, 'utf-8'))
+    const raw = cachedReadFileSync(filePath)
+    if (raw === null) return null
+    const parsed: unknown = JSON.parse(raw)
     return isJsonObject(parsed) ? parsed : null
   } catch {
     return null
@@ -192,10 +223,14 @@ function buildSystemPrompt(event: BeforeAgentStartEvent): { systemPrompt: string
 function logHookFailure(err: unknown): void {
   try {
     const msg = err instanceof Error ? `${err.name}: ${err.message}` : String(err)
-    process.stderr.write(`[xyz-system-prompt-extension] before_agent_start hook failed: ${msg}\n`)
+    logger.error(`before_agent_start hook failed: ${msg}`)
   } catch (nestedErr) {
     // best-effort：stderr 写失败的终极兜底——console 内部吞错不会抛，仍不外泄到 agent loop。
-    console.debug('[xyz-system-prompt-extension] stderr write also failed:', nestedErr)
+    try {
+      process.stderr.write(`[xyz-system-prompt-extension] logHookFailure also failed: ${String(nestedErr)}\n`)
+    } catch {
+      /* 完全静默：两层兑底都失败时无处可写 */
+    }
   }
 }