@zhushanwen/pi-session-reader 0.10.2 → 0.10.4

package/README.md

@@ -54,6 +54,16 @@ pi install npm:@zhushanwen/pi-session-reader
 pi --extension <repo>/extensions/universal/session-reader/index.ts "<prompt>"
 ```
 
+## 工具激活（deferred）
+
+`session_read` 工具为 `exposure: "deferred"`——不占常驻工具声明，由 pi 内置 `tool_search` 工具检索命中后按需激活。taiji 宿主内开箱即用（宿主启动时已激活 `tool_search`）；独立 pi 使用需在 `<agentDir>/settings.json`（默认 `~/.pi/agent/settings.json`）开启：
+
+```json
+{ "defaultTools": ["+tool_search"] }
+```
+
+`+` 前缀是增量修饰（保留 read/bash/edit/write 默认集）。未开启 `tool_search` 时该工具对模型不可见。
+
 ## 使用示例
 
 ```jsonc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "type": "module",
   "main": "index.ts",
   "taiji": {
@@ -17,14 +17,14 @@
   ],
   "dependencies": {
     "@zhushanwen/pi-extension-logger": "0.6.2",
-    "@zhushanwen/pi-ext-guards": "0.4.4",
+    "@zhushanwen/pi-ext-guards": "0.5.0",
     "@zhushanwen/session-core": "0.12.0",
     "@zhushanwen/zcode-session-source": "0.2.7"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8",
-    "@zhushanwen/subagent-core": "1.5.0"
+    "@zhushanwen/subagent-core": "1.5.2"
   },
   "files": [
     "index.ts",

package/src/__tests__/zcode-routing.test.ts

@@ -686,50 +686,42 @@ describe('pi 穿插不受影响：同 fixture 内 pi 会话读取与 zcode 调
 // D4 schema 零变化（快照逐字节对照 + 合法形态冒烟）
 // ---------------------------------------------------------------------------
 
-/** `session_read` 输入 schema 的 JSON 序列化快照（U9 改动前从基线实现抓取——D4「schema 零变化」的逐字节锚）。 */
+/** `session_read` 输入 schema 的 JSON 序列化快照（防无意漂移的逐字节锚）。
+ *
+ * 快照锚的意图 = 无意漂移拦截（参数增删 / 文案改动即红，迫使有意确认）；
+ * 有意的声明面压缩须同批重新生成快照。当前快照 = tool-declaration-slimming
+ * U-A1 压缩终态（D1 三层分工：action 功能语义唯一承载点 = 枚举 description；
+ * 工具 description 只留定位 + 边界；guidelines 只留纪律）。重新生成：
+ * tsx 起 extension 捕获 registerTool 的 parameters 后 JSON.stringify。
+ */
 const SCHEMA_SNAPSHOT =
-  '{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["find","f'
-    + 'amily","outline","expand","detail","search","export","extract","workflow","result","doctor"],"de'
-    + 'scription":"Action to perform: find (locate session), family (fork/subagent/workflow relations; '
-    + 'recursive=true returns nested execution tree), outline (turn-level overview), expand (single-tur'
-    + 'n entries), detail (full text of turns), search (full-text grep, single session or cross-session'
-    + ' over a comma-separated id list), export (materialize to file), extract (pull user messages / co'
-    + 'mmands / files / commits / tool results by type), workflow (workflow run overview: status/budget'
-    + '/steps; requires session, optional runId focuses one run; step call sessionId jumps to outline/d'
-    + 'etail), result (fetch a subagent session final result text — same content as its completion noti'
-    + 'ce; session = single id or comma-separated batch of at most 10, optional limit caps chars per it'
-    + 'em), doctor (show detected host environment and session-root diagnostics)."},"session":{"type":"'
-    + 'string","description":"Session id, uuid fragment (e.g. e6c96), subagent record id (sa-xxx, preci'
-    + 'se lookup), or absolute .jsonl path (~ or ~/ allowed). Required for family/outline/expand/detail'
-    + '/search/export/extract/workflow/result. result also accepts a comma-separated list of up to 10 i'
-    + 'ds. search also accepts a comma-separated list of up to 10 full ids (from find output) for cross'
-    + '-session search. # prefix auto-stripped."},"query":{"type":"string","description":"find action: '
-    + 'uuid fragment / filename / name keyword / \\"recent\\" (returns most recent N)."},"turns":{"type'
-    + '":"string","description":"detail/extract action: turn range, \\"T013-T015\\" or \\"T013\\"."},"t'
-    + 'urn":{"type":"string","description":"expand action: single turn, \\"T013\\"."},"pattern":{"type"'
-    + ':"string","description":"search action: substring or regex."},"scope":{"type":"string","enum":["'
-    + 'all","user","assistant","toolResult"],"description":"search action: scope filter. Default all."}'
-    + ',"format":{"type":"string","enum":["outline","full","family"],"description":"export action: mate'
-    + 'rialized form. Default outline."},"includeToolResult":{"type":"boolean","description":"detail/ex'
-    + 'port: include toolResult full text. Default false (omitted as noise)."},"includeThinking":{"type'
-    + '":"boolean","description":"detail: include thinking blocks. Default false (omitted as noise)."},'
-    + '"allBranches":{"type":"boolean","description":"outline (and export\'s outline section): include '
-    + 'abandoned side-branches. Not supported by family. Default false."},"granularity":{"type":"string'
-    + '","enum":["turn","entry"],"description":"outline: turn-level or entry-flat. Default turn."},"cwd'
-    + '":{"type":"string","description":"find: filter by cwd. Optional."},"source":{"type":"string","en'
-    + 'um":["main","subagent"],"description":"find and session-resolving actions: filter by source. \\"'
-    + 'main\\" = sessions/, \\"subagent\\" = subagents/. Default both (merged)."},"limit":{"type":"numb'
-    + 'er","minimum":1,"description":"find/search: max results. Default 20. result: max chars per item,'
-    + ' default 8000 (overlong text truncated with a pointer to the full file)."},"what":{"type":"strin'
-    + 'g","enum":["user-messages","commands","files","commits","tool-results"],"description":"extract a'
-    + 'ction: what to extract (required for extract)."},"tool":{"type":"string","description":"extract '
-    + 'action: filter commands/tool-results by tool name (e.g. \\"bash\\")."},"runId":{"type":"string",'
-    + '"description":"workflow action: focus a single run by runId (disambiguate multiple runs). Omit t'
-    + 'o see all run overviews."},"recursive":{"type":"boolean","description":"family action: return ne'
-    + 'sted execution tree (arbitrary-depth subagent↔workflow-call nesting, precise parentRecordId chai'
-    + 'n with flat-fallback for legacy records). Default false (flat family)."},"includeSubagents":{"ty'
-    + 'pe":"boolean","description":"doctor action: also scan the subagent session root (adds its file c'
-    + 'ount). Default false (path and existence only)."}}}';
+  '{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["find","famil'
+    + 'y","outline","expand","detail","search","export","extract","workflow","result","doctor"],"descriptio'
+    + 'n":"find (locate session), family (relations; recursive=tree), outline (turn overview), expand (one '
+    + 'turn), detail (full text), search (grep, cross-session, ≤10 ids), export (to file), extract (message'
+    + 's/commands/files/commits/tool results), workflow (run overview), result (subagent final text, batch '
+    + '≤10), doctor (environment diagnostics)."},"session":{"type":"string","description":"Session id, uuid'
+    + ' fragment (e6c96), subagent id (sa-xxx), or .jsonl path. Required by every action except find/doctor'
+    + '; result/search accept ≤10 comma-separated ids. # prefix auto-stripped."},"query":{"type":"string","'
+    + 'description":"find: uuid fragment / filename / name keyword / \\"recent\\" (recent N)."},"turns":{"typ'
+    + 'e":"string","description":"detail/extract: turn range \\"T013-T015\\" or \\"T013\\"."},"turn":{"type":"s'
+    + 'tring","description":"expand: turn \\"T013\\"."},"pattern":{"type":"string","description":"search: sub'
+    + 'string or regex."},"scope":{"type":"string","enum":["all","user","assistant","toolResult"],"descript'
+    + 'ion":"search: filter scope. Default all."},"format":{"type":"string","enum":["outline","full","famil'
+    + 'y"],"description":"export: materialized form. Default outline."},"includeToolResult":{"type":"boolea'
+    + 'n","description":"detail/export: include toolResult text. Default false."},"includeThinking":{"type"'
+    + ':"boolean","description":"detail: include thinking blocks. Default false."},"allBranches":{"type":"b'
+    + 'oolean","description":"outline/export: include abandoned side-branches. Default false."},"granularit'
+    + 'y":{"type":"string","enum":["turn","entry"],"description":"outline: turn-level or entry-flat. Defaul'
+    + 't turn."},"cwd":{"type":"string","description":"find: filter by cwd."},"source":{"type":"string","en'
+    + 'um":["main","subagent"],"description":"\\"main\\" = sessions/, \\"subagent\\" = subagents/. Default both'
+    + '."},"limit":{"type":"number","minimum":1,"description":"find/search: max results (default 20). resul'
+    + 't: max chars per item (default 8000, truncated with pointer)."},"what":{"type":"string","enum":["use'
+    + 'r-messages","commands","files","commits","tool-results"],"description":"extract: what to pull (requi'
+    + 'red)."},"tool":{"type":"string","description":"extract: filter by tool name (e.g. \\"bash\\")."},"runI'
+    + 'd":{"type":"string","description":"workflow: focus one run (omit = all)."},"recursive":{"type":"bool'
+    + 'ean","description":"family: nested execution tree. Default false (flat)."},"includeSubagents":{"type'
+    + '":"boolean","description":"doctor: also scan the subagent session root. Default false."}}}';
 
 describe('session_read schema 快照（D4：不加任何工具参数，逐字节一致）', () => {
   it('TypeBox schema JSON 序列化与基线快照逐字节一致', () => {
@@ -749,3 +741,30 @@ describe('session_read schema 快照（D4：不加任何工具参数，逐字节
     expect(Check(schema, { action: 'outline', session: 'e6c96' })).toBe(true)
   })
 })
+
+// ---------------------------------------------------------------------------
+// D2 锚词保留清单（index.ts guidelines 上方注释登记的清单在此逐词 grep 锚定）
+// ---------------------------------------------------------------------------
+
+describe('session_read 锚词保留清单（D2：guidelines 纪律逐词锚定）', () => {
+  // SCHEMA_SNAPSHOT 只逐字节锚 parameters schema，不覆盖 guidelines——本块是
+  // guidelines 锚词的机器防线：弱模型回归（P7/PB-weak）后对本工具声明面的
+  // 再压缩 / 措辞改动，逐词红灯迫使有意确认。清单与 index.ts 注释登记一致：
+  //   1. "Progressive reading"   —— 阅读纪律 outline → expand → detail
+  //   2. "Never read raw .jsonl" —— 禁直读原始 session 文件
+  //   3. "sa- ids route"         —— zcode 路由对 LLM 的唯一可见面（U9）
+  //   4. "👉 recovery hint"      —— 错误面恢复指针契约
+  //   5. "doctor"                —— 环境自检入口（另被上方快照 action 枚举间接锚定）
+  it('guidelines 5 锚词逐个在位（缺一词即红）', () => {
+    const registerTool = vi.fn()
+    const pi = { registerTool, registerCommand: vi.fn(), addAutocompleteProvider: vi.fn(), on: vi.fn() }
+    ;(sessionReaderExtension as unknown as (p: unknown) => void)(pi)
+    const toolDef = registerTool.mock.calls[0][0] as { promptGuidelines: string[] }
+    const guidelines = toolDef.promptGuidelines.join('\n')
+    expect(guidelines).toContain('Progressive reading')
+    expect(guidelines).toContain('Never read raw .jsonl')
+    expect(guidelines).toContain('sa- ids route')
+    expect(guidelines).toContain('👉 recovery hint')
+    expect(guidelines).toContain('doctor')
+  })
+})

package/src/index.ts

@@ -11,7 +11,7 @@ import { createSessionCommand } from './tui/session-command.js'
 /**
  * pi-session-reader extension 入口（M3 工具适配层）。
  *
- * 分层（同 scheduler/cw-tool）：
+ * 分层（同 scheduler）：
  * - tool-handler.ts：纯逻辑 handler，agentDir 注入，零 pi 依赖，可单测
  * - index.ts（本文件）：pi 依赖层，registerTool + getAgentDir() 调用 + execute 闭包
  *   （错误直接 throw 给 pi——pi-agent-core agent-loop 对 execute throw 置 isError:true，
@@ -37,57 +37,57 @@ const SessionReadSchema = Type.Object({
       'doctor',
     ],
     {
+      // tool-declaration-slimming D1 终态：action 功能语义唯一承载点（工具 description 只留
+      // 一句定位 + 边界；guidelines 只留纪律）。
       description:
-        'Action to perform: find (locate session), family (fork/subagent/workflow relations; recursive=true returns nested execution tree), outline (turn-level overview), expand (single-turn entries), detail (full text of turns), search (full-text grep, single session or cross-session over a comma-separated id list), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps; requires session, optional runId focuses one run; step call sessionId jumps to outline/detail), result (fetch a subagent session final result text — same content as its completion notice; session = single id or comma-separated batch of at most 10, optional limit caps chars per item), doctor (show detected host environment and session-root diagnostics).',
+        'find (locate session), family (relations; recursive=tree), outline (turn overview), expand (one turn), detail (full text), search (grep, cross-session, ≤10 ids), export (to file), extract (messages/commands/files/commits/tool results), workflow (run overview), result (subagent final text, batch ≤10), doctor (environment diagnostics).',
     },
   ),
   session: Type.Optional(
     Type.String({
       description:
-        'Session id, uuid fragment (e.g. e6c96), subagent record id (sa-xxx, precise lookup), or absolute .jsonl path (~ or ~/ allowed). Required for family/outline/expand/detail/search/export/extract/workflow/result. result also accepts a comma-separated list of up to 10 ids. search also accepts a comma-separated list of up to 10 full ids (from find output) for cross-session search. # prefix auto-stripped.',
+        'Session id, uuid fragment (e6c96), subagent id (sa-xxx), or .jsonl path. Required by every action except find/doctor; result/search accept ≤10 comma-separated ids. # prefix auto-stripped.',
     }),
   ),
   query: Type.Optional(
     Type.String({
-      description:
-        'find action: uuid fragment / filename / name keyword / "recent" (returns most recent N).',
+      description: 'find: uuid fragment / filename / name keyword / "recent" (recent N).',
     }),
   ),
   turns: Type.Optional(
     Type.String({
-      description: 'detail/extract action: turn range, "T013-T015" or "T013".',
+      description: 'detail/extract: turn range "T013-T015" or "T013".',
     }),
   ),
   turn: Type.Optional(
-    Type.String({ description: 'expand action: single turn, "T013".' }),
+    Type.String({ description: 'expand: turn "T013".' }),
   ),
   pattern: Type.Optional(
-    Type.String({ description: 'search action: substring or regex.' }),
+    Type.String({ description: 'search: substring or regex.' }),
   ),
   scope: Type.Optional(
     StringEnum(['all', 'user', 'assistant', 'toolResult'], {
-      description: 'search action: scope filter. Default all.',
+      description: 'search: filter scope. Default all.',
     }),
   ),
   format: Type.Optional(
     StringEnum(['outline', 'full', 'family'], {
-      description: 'export action: materialized form. Default outline.',
+      description: 'export: materialized form. Default outline.',
     }),
   ),
   includeToolResult: Type.Optional(
     Type.Boolean({
-      description: 'detail/export: include toolResult full text. Default false (omitted as noise).',
+      description: 'detail/export: include toolResult text. Default false.',
     }),
   ),
   includeThinking: Type.Optional(
     Type.Boolean({
-      description: 'detail: include thinking blocks. Default false (omitted as noise).',
+      description: 'detail: include thinking blocks. Default false.',
     }),
   ),
   allBranches: Type.Optional(
     Type.Boolean({
-      description:
-        "outline (and export's outline section): include abandoned side-branches. Not supported by family. Default false.",
+      description: 'outline/export: include abandoned side-branches. Default false.',
     }),
   ),
   granularity: Type.Optional(
@@ -96,12 +96,11 @@ const SessionReadSchema = Type.Object({
     }),
   ),
   cwd: Type.Optional(
-    Type.String({ description: 'find: filter by cwd. Optional.' }),
+    Type.String({ description: 'find: filter by cwd.' }),
   ),
   source: Type.Optional(
     StringEnum(['main', 'subagent'], {
-      description:
-        'find and session-resolving actions: filter by source. "main" = sessions/, "subagent" = subagents/. Default both (merged).',
+      description: '"main" = sessions/, "subagent" = subagents/. Default both.',
     }),
   ),
   limit: Type.Optional(
@@ -110,39 +109,35 @@ const SessionReadSchema = Type.Object({
       // 「无匹配 session」措辞面）；result 消费侧的 resolveResultLimit 防御保留
       //（可单测绕过 schema 的调用形态）。
       minimum: 1,
-      description:
-        'find/search: max results. Default 20. result: max chars per item, default 8000 (overlong text truncated with a pointer to the full file).',
+      description: 'find/search: max results (default 20). result: max chars per item (default 8000, truncated with pointer).',
     }),
   ),
   what: Type.Optional(
     StringEnum(
       ['user-messages', 'commands', 'files', 'commits', 'tool-results'],
       {
-        description: 'extract action: what to extract (required for extract).',
+        description: 'extract: what to pull (required).',
       },
     ),
   ),
   tool: Type.Optional(
     Type.String({
-      description: 'extract action: filter commands/tool-results by tool name (e.g. "bash").',
+      description: 'extract: filter by tool name (e.g. "bash").',
     }),
   ),
   runId: Type.Optional(
     Type.String({
-      description:
-        'workflow action: focus a single run by runId (disambiguate multiple runs). Omit to see all run overviews.',
+      description: 'workflow: focus one run (omit = all).',
     }),
   ),
   recursive: Type.Optional(
     Type.Boolean({
-      description:
-        'family action: return nested execution tree (arbitrary-depth subagent↔workflow-call nesting, precise parentRecordId chain with flat-fallback for legacy records). Default false (flat family).',
+      description: 'family: nested execution tree. Default false (flat).',
     }),
   ),
   includeSubagents: Type.Optional(
     Type.Boolean({
-      description:
-        'doctor action: also scan the subagent session root (adds its file count). Default false (path and existence only).',
+      description: 'doctor: also scan the subagent session root. Default false.',
     }),
   ),
 })
@@ -150,23 +145,26 @@ const SessionReadSchema = Type.Object({
 // ---- guidelines（注入 LLM，design §3.4）----
 
 const guidelines = [
-  'Progressive reading: outline (~1500 token overview) → expand (one turn) → detail (full text). Default omits toolResult/thinking noise.',
-  'find first to locate a session by uuid fragment or name. TUI #references are full uuids.',
-  'outline before detail. Never read raw .jsonl files—use this tool.',
-  'family traces fork parents/children, subagent sessions, and workflow runs.',
+  // tool-declaration-slimming D1 终态：纪律单点——action 逐个复述条已删（功能语义在
+  // schema action 枚举说明一处）；跨工具规则不在本工具重复（收敛点 = 注入段）。
+  // 锚词保留清单：Progressive reading / Never read raw .jsonl / sa- ids route /
+  // 👉 recovery hint / doctor——机器锚定唯一落点 = zcode-routing.test.ts 的锚词
+  // 保留清单 describe（逐词 toContain）；doctor 另被该文件 SCHEMA_SNAPSHOT 的
+  // action 枚举间接锚定。tool-prompt 契约不锚本工具 guidelines（其 A8 是 subagent
+  // 工具内指向本工具的交叉引用，非本清单的锚）。
+  'Progressive reading: outline (~1500 tokens) → expand (one turn) → detail; defaults omit toolResult/thinking noise.',
+  'find first (uuid fragment / name); TUI #references are full uuids. Never read raw .jsonl—use this tool.',
   // zcode 路由（U9）对 LLM 的唯一可见面：sa-id 输入自动路由，无需任何参数；首遇
-  // zcode_* 错误码前先有背景预告（schema 面按设计 D4 零变化，不在此重复）
-  'sa- ids route transparently to pi or zcode engine sessions; sess_ prefixed ids are not accepted—use the sa- id from the completion notice.',
-  'extract what=<type> to pull user messages / commands / files / commits / tool results across turns (optional tool= filter for commands/tool-results).',
-  "workflow action to see workflow run overviews (status/budget/steps). Each step's call sessionId can jump to outline/detail for deep reading.",
-  "result action to fetch a subagent's final result text (same content as its completion notice): session takes a single sa-id/uuid/path or a comma-separated batch of at most 10; optional limit caps chars per item (default 8000, truncated items carry a pointer to the full file).",
-  'Errors carry a 👉 recovery hint—follow it to retry in one step.',
-  'Unsure about the host environment (pure pi vs taiji) or where session roots live? Run action:"doctor" first—it prints the detected environment and every candidate session root.',
+  // zcode_* 错误码前先有背景预告。
+  'sa- ids route transparently to pi or zcode engine sessions; sess_ prefixed ids are not accepted—use the completion-notice sa- id.',
+  'Errors carry a 👉 recovery hint—follow it to retry.',
+  'Unsure about host environment or session roots? Run action:"doctor".',
 ]
 
-// ---- 工具 description（design §3.4，照搬措辞）----
+// ---- 工具 description（tool-declaration-slimming D1 终态：一句定位 + 阅读纪律指针 + 边界；
+// action 一览与参数功能语义唯一承载点 = SessionReadSchema 的 action 枚举说明）----
 
-const description = `Read pi session files (conversation history) by semantic structure instead of raw bytes. Use when you need to review another session, trace a fork/subagent/workflow family, or locate a past decision. Eleven actions: find (locate by name/uuid fragment), family (fork/subagent/workflow relations), outline (turn-level overview, ~1500 token), expand (single-turn entry list), detail (full text of turns), search (full-text grep across a session, or cross-session over a comma-separated id list ≤10 from find output), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps, step call sessionId jumps to outline/detail), result (fetch a subagent session final result text, same content as its completion notice; single id or comma-separated batch ≤10, optional limit chars per item default 8000), doctor (show detected host environment and session-root diagnostics). Progressive reading: outline → expand → detail. Do NOT use for the current session (the host provides current-session access) or to edit sessions (pi has /resume /fork).`
+const description = `Read pi session files (conversation history) by semantic structure, not raw bytes. Progressive reading: outline → expand → detail. Do NOT use for the current session (the host provides it) or to edit sessions (pi has /resume /fork).`
 
 /**
  * 已注册过 TUI provider/command 的 pi 实例集合。
@@ -198,6 +196,9 @@ export default function sessionReaderExtension(pi: ExtensionAPI): void {
   pi.registerTool({
     name: 'session_read',
     label: 'Session Reader',
+    // deferred（tool-declaration-slimming D4）：不常驻声明，tool_search 命中即激活；
+    // 迁移写入的 +tool_search 条目（runtime pi-codemode-settings）承载检索入口
+    exposure: 'deferred',
     description,
     parameters: SessionReadSchema,
     promptGuidelines: guidelines,

package/src/tool-handler.ts

@@ -1,7 +1,7 @@
 /**
  * [M3 工具适配层] session_read 工具的纯逻辑 handler（design §3.4 接口规格）。
  *
- * 分层约定（同 scheduler/cw-tool）：本文件零 pi 依赖——agentDir 作参数注入，
+ * 分层约定（同 scheduler）：本文件零 pi 依赖——agentDir 作参数注入，
  * 不调用 getAgentDir()，可完全单测；pi 注册与 getAgentDir() 调用在 index.ts。
  *
  * 按 action 分发到 11 条路径，串联基座解析（session-core parse）+ M1 core（tree/turns/render）+ M2 discovery