@zhushanwen/pi-unified-hooks 0.2.7 → 0.2.9

package/README.md

@@ -12,7 +12,7 @@
 >
 > 迁移指引：`pi uninstall npm:@zhushanwen/pi-unified-hooks` 后 `pi install npm:@zhushanwen/pi-base-tool-enhance`。两者同时安装会对 bash 产生双重拦截，务必先卸载本包。
 
-统一 hooks 管理器 — 将散落的 hooks 收集到一个扩展中统一维护，每个 hook 可独立启用/禁用。
+统一 hooks 管理器 — 将散落的 hooks 收集到一个扩展中统一维护。hook 为自包含模块，全部注册；setup 失败的 hook 标记为 disabled，并在 session_start 时提醒。
 
 ## 功能
 
@@ -20,27 +20,17 @@
 
 | Hook | 说明 |
 |------|------|
-| `edit-whitespace-autofix` | edit 工具因空白字符不匹配失败时，自动注入 steering 让 AI 修复空白并重试 |
-| `tool-error-handler` | 记录所有工具执行错误到控制台，方便调试 |
+| `tool-error-handler` | 工具执行错误经 appendEntry 写入 session JSONL（customType `unified-hooks:tool-error`），便于事后排查 |
+| `network-timeout-guard` | 网络类 bash 命令未设 timeout 时 block，提示 AI 补 timeout 或开代理 |
+| `test-timeout-guard` | 测试类 bash 命令未设 timeout 时 block，提示 AI 补 timeout |
 
 ### 扩展方式
 
 在 `src/hooks/` 下新建 hook 模块，然后在 `src/index.ts` 的 `hookModules` 数组中注册即可。
 
-## 安装
-
-```bash
-# symlink 方式（开发推荐；globalExtDir 平铺布局，目标不带分组层）
-ln -s /path/to/xyz-pi-extensions-workspace/main/packages/unified-hooks \
-      ~/.pi/agent/extensions/unified-hooks
-
-# npm 方式（正式）
-pi install npm:@zhushanwen/pi-unified-hooks
-```
-
 ## 使用
 
-安装后自动生效。edit 空白修复无需配置，工具错误日志自动输出到控制台。
+加载后自动生效，无需配置。工具错误经 appendEntry 写入 session JSONL（customType `unified-hooks:tool-error`），不弹 TUI 通知；各 hook 的注册结果（enabled/disabled）记录在 `unified-hooks:loaded` customEntry。
 
 ## 文件结构
 
@@ -50,5 +40,7 @@ unified-hooks/
 └── src/
     ├── index.ts               # 入口 — hook 注册
     └── hooks/
-        └── tool-error-handler.ts  # 工具错误处理
+        ├── tool-error-handler.ts    # 工具错误处理（appendEntry 审计）
+        ├── network-timeout-guard.ts # 网络命令超时守卫
+        └── test-timeout-guard.ts    # 测试命令超时守卫
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-unified-hooks",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "[DEPRECATED] Unified hooks extension - collect scattered hooks in one place for easy maintenance",
   "deprecated": "Superseded by @zhushanwen/pi-base-tool-enhance — install that instead; test-command guarding, tool-error audit and configurable timeouts are all covered.",
   "main": "index.ts",
@@ -20,10 +20,10 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.3.0"
+    "@zhushanwen/pi-extension-logger": "0.4.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.1"
+    "@earendil-works/pi-coding-agent": "^0.84.4"
   },
   "peerDependenciesMeta": {},
   "devDependencies": {

package/src/__tests__/session-start-handler.test.ts

@@ -131,6 +131,7 @@ describe("session_start handler", () => {
 
 	it("does not throw when ctx.ui is undefined (headless / RPC session)", () => {
 		// [HISTORICAL] headless 会话 ctx.ui 为 undefined，旧实现直接 ctx.ui.notify 会 NPE。
+		// pi 现版本 ctx.ui 恒为对象（runner 默认 noOpUIContext），本用例仅保留防御。
 		const pi = createMockPi();
 		const ctx = { ui: undefined } as unknown as HookContext;
 

package/src/hooks/network-timeout-guard.ts

@@ -3,7 +3,7 @@
  *
  * Intercepts bash tool calls that involve network operations.
  * Blocks execution if no timeout is set and the command appears to be network-bound,
- * prompting the AI to add timeout or use async mode.
+ * prompting the AI to add a timeout (or enable a proxy for overseas access).
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

package/src/index.ts

@@ -2,7 +2,8 @@
  * Unified Hooks Extension
  *
  * Collects scattered hooks in one place for easy maintenance.
- * Each hook is a self-contained module that can be enabled/disabled independently.
+ * Each hook is a self-contained module. All hooks are registered unconditionally;
+ * a hook whose setup throws is marked disabled (reported via session_start).
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";