@zhushanwen/pi-system-prompt 1.0.2 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-system-prompt",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "System prompt injection extension for Pi — reads config and appends to system prompt",
   "type": "module",
   "main": "src/index.ts",

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

@@ -66,7 +66,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 +78,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)
@@ -309,3 +321,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
@@ -27,6 +28,31 @@ import type { ExtensionAPI, BeforeAgentStartEvent } from '@earendil-works/pi-cod
 
 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,8 +114,8 @@ 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 }
         }
       }
@@ -131,7 +157,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