pi-windows-notifier 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +86 -67
  2. package/README.zh-TW.md +156 -0
  3. package/THIRD_PARTY_NOTICES.md +10 -11
  4. package/docs/verification.md +22 -19
  5. package/package.json +10 -1
package/README.md CHANGED
@@ -1,57 +1,69 @@
1
1
  # pi-windows-notifier
2
2
 
3
- Pi 的 Windows 本機通知 extension：需要授權、回答結構化問題，或整次模型回應結束時，提交右下角 Toast 並播放系統提示音。
3
+ [English](README.md) | [繁體中文](README.zh-TW.md)
4
4
 
5
- **Windows-only、零額外 runtime dependencies、沒有網路通知。** 只觀察事件，不批准權限、不代答，不改寫第三方工具。
5
+ Get a Windows notification when Pi needs your attention—or when it's finished responding. The extension shows a toast and plays a system sound for permission requests, structured questions, and completed, interrupted, or failed responses, even while you're looking at another window.
6
6
 
7
- ## 環境與安裝
7
+ Notifications stay on your machine and only tell you what happened. They don't include your questions, commands, file paths, or Pi's replies. The extension doesn't approve permissions or answer questions for you.
8
8
 
9
- - Windows 10／11、64 位元 Node.js 22.19+（x64 或 arm64）。
10
- - Pi 1.1.0+；開發型別檢查使用 1.1.0。舊版事件 API 不支援，沒有 fallback。
11
- - 僅互動式 TUI。RPC、print、JSON、非 Windows、32 位元 Node 停用通知，載入不拋錯。
12
- - 使用 Windows 內建 Windows PowerShell 5.1；不需要 ffplay、node-notifier 或另外下載 executable。
9
+ [GitHub](https://github.com/C-W-Z/pi-windows-notifier) · [npm](https://www.npmjs.com/package/pi-windows-notifier)
13
10
 
14
- 單次載入，不修改 Pi 設定：
11
+ ## Install
15
12
 
16
13
  ```bash
17
- pi -e D:/Pi/pi-windows-notifier
14
+ pi install npm:pi-windows-notifier
18
15
  ```
19
16
 
20
- 確認後，可自行安裝本地 package：
17
+ Start a new Pi session after installing. You don't need a config file to get started—all five notification types and their sounds are enabled by default.
18
+
19
+ You'll need:
20
+
21
+ - Windows 10 or 11.
22
+ - 64-bit Node.js 22.19 or newer (x64 or arm64).
23
+ - Pi 1.1.0 or newer.
24
+ - Windows PowerShell 5.1, included with Windows.
25
+
26
+ The extension only sends notifications in Pi's interactive terminal UI. It stays inactive in RPC, print, and JSON modes, on other operating systems, and with 32-bit Node.js. It doesn't support older Pi versions without the required UI events.
27
+
28
+ To uninstall:
21
29
 
22
30
  ```bash
23
- pi install D:/Pi/pi-windows-notifier
31
+ pi remove npm:pi-windows-notifier
24
32
  ```
25
33
 
26
- 目前只有本地 repository，未發布 npm，也沒有自動安裝到你的 Pi。使用此 package 不需要安裝開發依賴；只有開發與測試才需要 `npm ci --ignore-scripts`。
34
+ ## When it notifies you
27
35
 
28
- ## 提醒事件
29
-
30
- | 事件 | Toast 標題／內容 | 提示音 |
36
+ | Event | When you get a notification | Windows sound |
31
37
  |---|---|---|
32
- | permission | Pi／需要權限確認 | Exclamation |
33
- | question | Pi／有問題等待回答 | Exclamation |
34
- | completed | Pi／回應已完成 | Asterisk |
35
- | aborted | Pi／回應已中止 | Exclamation |
36
- | failed | Pi／回應失敗 | Exclamation |
38
+ | `permission` | Pi needs you to review a permission request | Exclamation |
39
+ | `question` | A supported question tool is waiting for your answer | Exclamation |
40
+ | `completed` | Pi has finished responding | Asterisk |
41
+ | `aborted` | The response was interrupted | Exclamation |
42
+ | `failed` | The response ended in an error | Exclamation |
43
+
44
+ The toast title is **Pi**. Notification text and the extension's command messages are currently in Traditional Chinese; there isn't a language setting yet.
45
+
46
+ Permission notifications work with `@gotgenes/pi-permission-system`, including requests forwarded from a subagent to its parent session. Requests that are automatically allowed or denied, or covered by an existing session approval, don't trigger a notification.
47
+
48
+ Question notifications work with `ask_user_question` (including RPIV Lean) and `plan_mode_question`. One questionnaire gets one notification, not one per question. Ordinary questions written in a model's reply and manually opened settings dialogs don't count.
37
49
 
38
- - **權限**：訂閱 `@gotgenes/pi-permission-system` 的 `permissions:ui_prompt`；自動 allow／deny、session approval 不提醒。支援轉送到父 session 的 subagent 詢問。
39
- - **提問**：支援 `ask_user_question`（包含 RPIV Lean）與 `plan_mode_question`。追蹤工具執行及真正等待 UI 的訊號，一次 questionnaire 只提醒一次，不按題數重複。
40
- - **回應結束**：僅在 `agent_settled` 發送。重試／續跑尚未結束時不報完成或失敗；重試成功只報完成，單一工具失敗不等於模型失敗。
41
- - 不辨識普通文字中的問句，不提醒單純手動設定 UI。不論終端是否在前景都提醒。
42
- - 提問與權限套件是可選整合來源，不是本 package 的 dependencies；沒有安裝時，回應結束通知仍可使用。
50
+ Response notifications wait until Pi has actually settled. They don't fire halfway through an automatic retry or continuation, and a failed tool call on its own doesn't count as a failed response.
43
51
 
44
- ### 提問辨識邊界
52
+ Permission and question packages are optional. You don't have to install them to get response notifications.
45
53
 
46
- Pi 的 UI 事件不含 toolCallId。只有恰好一個支援的提問工具正在執行，且沒有權限／已知不明 UI 佔用時才分類；不明時略過並記錄 `UI_AMBIGUOUS`，不攔截第三方 UI。另一個 UI 在提問 call 期間首次開啟時仍可能無法分辨，**不承諾任意並行 UI 的精確歸屬**。
54
+ ### A note about question detection
47
55
 
48
- `rpiv:ask-user:blocked` 是補充訊號，與共通 UI 共用去重。第三方套件可能自行發出 terminal bell；那不是本 package 的第二次音效，請使用該套件／終端自身的設定調整。
56
+ Pi's UI events don't say which tool opened a dialog. This extension only classifies a UI wait as a question when exactly one supported question tool is running and no permission prompt or known unrelated UI is occupying the wait. If the signals are ambiguous, it skips the notification and records `UI_AMBIGUOUS` rather than guessing.
49
57
 
50
- ## 設定
58
+ This can't reliably identify every possible combination of overlapping dialogs. RPIV's `rpiv:ask-user:blocked` event provides an additional signal and shares the same deduplication logic.
51
59
 
52
- 唯一位置：`~/.pi/agent/pi-windows-notifier/config.json`。
60
+ Some question packages also ring the terminal bell themselves. If you hear an extra sound, check that package's settings or your terminal's bell settings.
53
61
 
54
- 不讀專案設定，不建立／自動修改檔案，不移植舊套件設定。沒有檔案時預設全部開啟：
62
+ ## Settings
63
+
64
+ To change the defaults, create `~/.pi/agent/pi-windows-notifier/config.json`. On Windows, that's `.pi\agent\pi-windows-notifier\config.json` inside your user home folder.
65
+
66
+ The extension doesn't create or edit this file for you, and it doesn't read project-level settings. If the file doesn't exist, it uses these defaults:
55
67
 
56
68
  ```json
57
69
  {
@@ -66,65 +78,70 @@ Pi 的 UI 事件不含 toolCallId。只有恰好一個支援的提問工具正
66
78
  }
67
79
  ```
68
80
 
69
- 可以只提供要修改的欄位，例如完成時靜音：
81
+ You only need to include the values you want to change. For example, to keep completion toasts but turn off their sound:
70
82
 
71
83
  ```json
72
84
  { "events": { "completed": { "sound": false } } }
73
85
  ```
74
86
 
75
- 總開關 `enabled` 與事件 `enabled` 控制提交；`sound` 只控制 package 音效。runtime 驗證所有欄位，拒絕未知欄位，檔案上限 16 KiB。讀取／解析／驗證失敗時 **fail closed**，停用通知並顯示固定診斷碼，不輸出原始設定。
87
+ The top-level `enabled` switch controls everything. Each event's `enabled` switch controls both its toast and sound; `sound` only controls its sound.
76
88
 
77
- 修改後執行 `/windows-notifier reload`，取消舊工作並重新讀取，不寫設定。
89
+ After editing the file, run `/windows-notifier reload`. Unknown fields, invalid values, unreadable files, and files larger than 16 KiB disable notifications until you fix the settings and reload. Error messages won't print the file's contents.
78
90
 
79
- ## 指令
91
+ ## Commands
92
+
93
+ Run these inside Pi:
80
94
 
81
95
  ```text
82
96
  /windows-notifier status
83
97
  /windows-notifier reload
84
98
  /windows-notifier test
85
99
  /windows-notifier test permission
86
- /windows-notifier test question
87
- /windows-notifier test completed
88
- /windows-notifier test aborted
89
- /windows-notifier test failed
90
100
  ```
91
101
 
92
- `test` 預設為 completed，**會產生真實彈窗與提示音**，與自動通知共用開關、佇列、限流，不能繞過 disabled。`status` 只顯示有效開關、backend 狀態、佇列／丟棄數與固定診斷碼，不含工作內容。
102
+ - `status` shows the active settings, backend status, queue counters, and diagnostic codes—not your session content.
103
+ - `reload` reads the config again and cancels old notification work.
104
+ - `test` sends a completion notification by default. You can also choose `permission`, `question`, `completed`, `aborted`, or `failed`.
105
+
106
+ **Tests produce real notifications and sounds.** They follow the same switches, queue limits, and rate limits as automatic notifications, so they won't override a disabled event.
93
107
 
94
- ## 安全與資源限制
108
+ ## Privacy and process safety
95
109
 
96
- - 通知不含問題原文、命令、路徑、session 名稱、模型回答或錯誤原文。沒有 recap、遙測、外部通知服務或模型可呼叫的通知工具。
97
- - SystemRoot／windir 僅來自啟動 OS 環境；拒絕相對、UNC、device 路徑，PowerShell 使用絕對路徑，不搜尋 cwd／PATH。
98
- - `spawn` 不開 shell，使用固定 package cwd／腳本、`-NoProfile`、`-NonInteractive`、`-STA`。child environment 僅允許必要 Windows 路徑欄位，不繼承整份 agent environment 或 API tokens。
99
- - stdin 僅含事件 enum 與音效 boolean；helper 再驗證，從固定字串表生成 DOM text node，不拼接 XML／PowerShell，不使用 Invoke-Expression。
100
- - `-ExecutionPolicy Bypass` 只限該 child；不取得管理員權限、不更改永久設定，也不把 Execution Policy 當安全邊界。
101
- - 最多一個 helper、佇列上限 16、啟動至少間隔一秒、等待上限 30 秒。權限／提問優先；滿載先丟棄最舊回應結束項目，否則丟棄最舊等待項目。
102
- - child timeout 10 秒，stdout／stderr 各最多 8 KiB；只終止自有 child，不按名稱殺程序，不無限重試。若 OS 拒絕終止，等待 close，寧可暫停後續通知，不啟動第二個 helper。
103
- - 決策、問題結束、新 run、reload、session 重建及 shutdown 取消相應舊工作。已展示的 Toast 不撤回；程序啟動與 Windows 提交仍有取消競態。
104
- - 不支援背景音樂、自訂音效／音量、遠端通知、定期催答或點擊 Toast 後的自動操作。
110
+ This extension uses Windows' built-in notification and sound APIs through a fixed PowerShell script. You don't need a separate notification server or audio player. There are no network notifications, telemetry, or custom sound files.
105
111
 
106
- **威脅模型**：防護不可信專案內容與事件資料；假設 Windows 系統目錄、啟動 OS 環境與安裝的 package 可信。不防禦惡意同程序 extension、被竄改的 SystemRoot 或遭入侵帳號。Pi permission system 不是 extension 的 OS 沙盒。
112
+ - PowerShell is located using an absolute path under the startup environment's `SystemRoot` or `windir`, never the project directory or `PATH`.
113
+ - The helper runs without a shell. It receives only an event type and a sound switch, validates both, and builds the toast from fixed strings. It doesn't interpolate your content into PowerShell commands or XML.
114
+ - The child process gets a limited set of Windows environment variables, not Pi's full environment or API tokens. `-ExecutionPolicy Bypass` applies only to that child; it doesn't grant administrator access or change permanent settings. Execution Policy isn't treated as a security boundary.
115
+ - Only one helper runs at a time. The queue holds at most 16 notifications, launches are at least a second apart, queued work expires after 30 seconds, and the helper has a 10-second timeout. stdout and stderr are each capped at 8 KiB. Permission requests and questions take priority over response notifications.
116
+ - It only attempts to stop its own child process, never every process with the same name. If Windows refuses to stop that process, new helpers wait for it to close instead of piling up.
117
+ - Decisions, finished questions, new runs, reloads, session changes, and shutdown cancel the relevant old work. A toast already shown can't be taken back, and cancellation can race with submission to Windows.
107
118
 
108
- ## Windows 限制與排錯
119
+ These safeguards assume that Windows' system directories, Pi's startup environment, and installed packages are trustworthy. They don't protect against a malicious extension running in the same process or a compromised user account. Pi's permission system doesn't sandbox extensions at the OS level.
109
120
 
110
- 使用固定 `Microsoft.Windows.PowerShell` AppID，不寫 registry 或捷徑，來源可能顯示 **PowerShell**，文字標示 Pi。Toast 音效 silent，SystemSounds 分開播放，避免 backend 自己重複播放；沒有 NotifyIcon balloon、Console.Beep 或外部播放器 fallback。
121
+ ## FAQ
111
122
 
112
- 勿擾、Windows／PowerShell 通知設定、系統音效方案與靜音有最終控制權。**「已提交」不保證看見彈窗或聽到聲音**；played 只表示音效 API 呼叫成功。Toast 失敗仍嘗試音效，部分成功會如實回報。
123
+ ### Why aren't notifications showing up?
113
124
 
114
- | 診斷碼 | 意義 |
125
+ Windows still has the final say. Do Not Disturb, notification settings, your sound scheme, and muted audio can suppress a toast or sound even after the API accepts it.
126
+
127
+ The sender may appear as **PowerShell** because the extension uses the `Microsoft.Windows.PowerShell` AppID. The toast itself says **Pi**. Toast audio is disabled and the system sound is played separately to avoid a duplicate sound from this backend. If one fails, the other is still attempted. There is no fallback notification or audio player.
128
+
129
+ Use `/windows-notifier status` to check these codes:
130
+
131
+ | Code | What to check |
115
132
  |---|---|
116
- | CONFIG_INVALID／CONFIG_TOO_LARGE／CONFIG_READ_FAILED | 修正全域設定後 reload |
117
- | ENV_UNSUPPORTED | 目前不是支援的 Windows 64 位元 TUI |
118
- | BACKEND_UNAVAILABLE | SystemRoot／PowerShell／helper 不可用 |
119
- | UI_AMBIGUOUS／TOOLS_LIMIT | 歸屬不明或追蹤上限，保守略過 |
120
- | QUEUE_DROPPED | 滿載丟棄 |
121
- | HELPER_TIMEOUT／OUTPUT_LIMIT／LAUNCH_FAILED | 超時、輸出超限或啟動失敗 |
122
- | TOAST_FAILED／SOUND_FAILED／BOTH_FAILED | Windows 提交／音效失敗 |
123
- | INPUT_INVALID／INTERNAL_ERROR／HELPER_PROTOCOL | helper 協定不符，檢查安裝完整性 |
133
+ | `CONFIG_INVALID` / `CONFIG_TOO_LARGE` / `CONFIG_READ_FAILED` | Fix the global config file, then reload |
134
+ | `ENV_UNSUPPORTED` | Use a supported Windows 64-bit interactive Pi session |
135
+ | `BACKEND_UNAVAILABLE` | Check that the Windows paths, PowerShell, and helper are available |
136
+ | `UI_AMBIGUOUS` / `TOOLS_LIMIT` | A UI wait couldn't be identified safely, or tracking hit its limit |
137
+ | `QUEUE_DROPPED` | The queue was full and a notification was dropped |
138
+ | `HELPER_TIMEOUT` / `OUTPUT_LIMIT` / `LAUNCH_FAILED` | The helper timed out, produced too much output, or couldn't run |
139
+ | `TOAST_FAILED` / `SOUND_FAILED` / `BOTH_FAILED` | Windows rejected the toast, sound, or both |
140
+ | `INPUT_INVALID` / `INTERNAL_ERROR` / `HELPER_PROTOCOL` | Check the package installation and helper protocol |
124
141
 
125
- 自動錯誤最多每分鐘一次固定 TUI 警告，累計診斷在 status，不顯示原始 stderr。
142
+ Automatic errors show at most one terminal warning per minute. Status uses fixed diagnostic codes rather than raw PowerShell error output.
126
143
 
127
- ## 開發與驗證
144
+ ## Development
128
145
 
129
146
  ```bash
130
147
  npm ci --ignore-scripts
@@ -132,6 +149,8 @@ npm run verify
132
149
  npm pack --dry-run
133
150
  ```
134
151
 
135
- Node test runner 搭配假時鐘、假 event bus 與 mock launcher。Windows 額外執行 PowerShell 語法解析及無效輸入路徑，**一般 npm test 不發 Toast、不播放音效**。成功路徑的可見通知驗收另行確認，詳見 [驗證紀錄](docs/verification.md)。
152
+ Tests use a fake clock, event bus, and launcher. On Windows, they also check PowerShell syntax and invalid input handling. Normal `npm test` runs don't show toasts or play sounds. See the [verification notes (繁體中文)](docs/verification.md) for the test scope and remaining checks.
153
+
154
+ ## License
136
155
 
137
- MIT；來源與上游授權見 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。上游 checkout 位於 package 外部，不發布；沒有複製 pi-jingle 程式或音效，沒有引入 UniPi core。
156
+ MIT. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for upstream credits and license notices.
package/README.zh-TW.md ADDED
@@ -0,0 +1,156 @@
1
+ # pi-windows-notifier
2
+
3
+ [English](README.md) | [繁體中文](README.zh-TW.md)
4
+
5
+ 不用一直盯著 Pi。需要你確認權限、回答問題，或模型回應結束時，這個 extension 會跳出 Windows 通知並播放提示音。就算你正在看別的視窗，也會提醒。
6
+
7
+ 通知只告訴你發生了什麼事，不會帶出問題、命令、檔案路徑或模型回答，也不會替你批准權限或回答問題。所有提醒都在本機處理。
8
+
9
+ [GitHub](https://github.com/C-W-Z/pi-windows-notifier) · [npm](https://www.npmjs.com/package/pi-windows-notifier)
10
+
11
+ ## 安裝
12
+
13
+ ```bash
14
+ pi install npm:pi-windows-notifier
15
+ ```
16
+
17
+ 安裝後開一個新的 Pi session 就能使用，不用先寫設定檔。五種通知和提示音預設都會開啟。
18
+
19
+ 需要的環境：
20
+
21
+ - Windows 10 或 11。
22
+ - 64 位元 Node.js 22.19 以上，支援 x64 和 arm64。
23
+ - Pi 1.1.0 以上。
24
+ - Windows 內建的 Windows PowerShell 5.1。
25
+
26
+ 只在 Pi 的互動式終端介面啟用。RPC、print、JSON 模式、其他作業系統和 32 位元 Node.js 都不會發通知。缺少必要 UI 事件的舊版 Pi 不支援。
27
+
28
+ 移除套件：
29
+
30
+ ```bash
31
+ pi remove npm:pi-windows-notifier
32
+ ```
33
+
34
+ ## 什麼時候會提醒？
35
+
36
+ | 事件 | 通知內容 | Windows 提示音 |
37
+ |---|---|---|
38
+ | `permission` | 需要權限確認 | Exclamation |
39
+ | `question` | 有問題等待回答 | Exclamation |
40
+ | `completed` | 回應已完成 | Asterisk |
41
+ | `aborted` | 回應已中止 | Exclamation |
42
+ | `failed` | 回應失敗 | Exclamation |
43
+
44
+ 彈窗標題是 **Pi**。目前通知文字和指令提示都是繁體中文，還沒有語言切換設定。
45
+
46
+ **權限提醒**搭配 `@gotgenes/pi-permission-system` 使用，也支援從 subagent 轉送到父 session 的權限請求。自動允許、自動拒絕，或已經有 session approval 的請求不會提醒。
47
+
48
+ **問題提醒**支援 `ask_user_question`（包含 RPIV Lean）和 `plan_mode_question`。一份問卷只提醒一次，不會每一題都響。模型在一般文字回答裡寫的問句，以及你手動打開的設定介面，不算這裡的提問。
49
+
50
+ **回應結束提醒**會等 Pi 真正結束這次回應才發送，不會在自動重試或續跑途中提早報完成。單一工具出錯，也不等於整次模型回應失敗。
51
+
52
+ 權限和提問套件都是可選的；沒有安裝它們，仍然可以收到回應結束提醒。
53
+
54
+ ### 提問辨識的限制
55
+
56
+ Pi 的 UI 事件沒有說明是哪個工具開了視窗。因此，只有恰好一個支援的提問工具正在執行，而且沒有權限提示或已知的其他 UI 佔用時，才會把等待畫面的訊號當成提問。資訊不明確就略過，並記錄 `UI_AMBIGUOUS`，不硬猜來源。
57
+
58
+ 這個做法無法精確辨識所有重疊視窗的情況。RPIV 的 `rpiv:ask-user:blocked` 會提供額外訊號，並和共通 UI 事件一起去重。
59
+
60
+ 有些提問套件本身也會發出 terminal bell。如果聽到額外的聲音，請檢查該套件或終端的提示音設定。
61
+
62
+ ## 設定
63
+
64
+ 想改預設行為時，請自行建立 `~/.pi/agent/pi-windows-notifier/config.json`。在 Windows 上，就是使用者家目錄裡的 `.pi\agent\pi-windows-notifier\config.json`。
65
+
66
+ 套件不會替你建立或修改這個檔案，也不讀專案內的設定。沒有設定檔時，使用以下預設值：
67
+
68
+ ```json
69
+ {
70
+ "enabled": true,
71
+ "events": {
72
+ "permission": { "enabled": true, "sound": true },
73
+ "question": { "enabled": true, "sound": true },
74
+ "completed": { "enabled": true, "sound": true },
75
+ "aborted": { "enabled": true, "sound": true },
76
+ "failed": { "enabled": true, "sound": true }
77
+ }
78
+ }
79
+ ```
80
+
81
+ 只要寫想改的欄位就好。例如保留完成彈窗，但不要播放提示音：
82
+
83
+ ```json
84
+ { "events": { "completed": { "sound": false } } }
85
+ ```
86
+
87
+ 最外層的 `enabled` 是總開關。每個事件的 `enabled` 控制該類彈窗與音效，`sound` 則只控制音效。
88
+
89
+ 修改後執行 `/windows-notifier reload`。如果有未知欄位、值的型別不對、檔案無法讀取或超過 16 KiB，通知會先停用；修正後再 reload 即可。錯誤提示不會印出設定檔內容。
90
+
91
+ ## 指令
92
+
93
+ 在 Pi 裡執行：
94
+
95
+ ```text
96
+ /windows-notifier status
97
+ /windows-notifier reload
98
+ /windows-notifier test
99
+ /windows-notifier test permission
100
+ ```
101
+
102
+ - `status`：查看目前設定、backend 狀態、佇列計數和診斷碼，不會顯示 session 內容。
103
+ - `reload`：重新讀取設定，取消舊的通知工作。
104
+ - `test`：預設測試完成通知，也能指定 `permission`、`question`、`completed`、`aborted` 或 `failed`。
105
+
106
+ **測試會真的跳通知、播放音效。** 和自動通知一樣，它會遵守開關、佇列與限流，不會強行送出已停用的事件。
107
+
108
+ ## 隱私與程序安全
109
+
110
+ 套件透過固定的 PowerShell 腳本呼叫 Windows 內建通知和音效 API，不用另外裝通知服務或播放器。沒有網路通知、遙測或自訂音效檔。
111
+
112
+ - PowerShell 使用啟動環境的 `SystemRoot`／`windir` 下的絕對路徑，不從專案目錄或 `PATH` 搜尋。
113
+ - helper 不透過 shell 執行，只接收事件類型與音效開關。驗證後使用固定文字建立通知，不把工作內容拼進 PowerShell 命令或 XML。
114
+ - 子程序只拿到必要的 Windows 環境變數，不繼承 Pi 的完整環境或 API tokens。`-ExecutionPolicy Bypass` 只作用於該子程序，不會取得管理員權限或改動永久設定，也不把 Execution Policy 當成安全邊界。
115
+ - 同時最多一個 helper，佇列最多 16 筆，啟動至少間隔一秒。工作等待超過 30 秒會過期，helper 的 timeout 是 10 秒，stdout 和 stderr 各限制 8 KiB。權限和提問比回應結束通知優先。
116
+ - 只嘗試終止自己建立的子程序，不會按名稱關閉其他程序。如果 Windows 不允許終止，就等它結束，不會繼續堆出新的 helper。
117
+ - 權限決策、問題結束、新回應、reload、session 切換和 shutdown 都會取消相關舊工作。已經顯示的 Toast 無法收回，取消和提交給 Windows 之間仍可能發生競態。
118
+
119
+ 這些防護假設 Windows 系統目錄、Pi 啟動環境和已安裝套件可信。它們無法防禦同程序裡的惡意 extension，或已遭入侵的使用者帳號。Pi permission system 並不是 extension 的 OS 沙盒。
120
+
121
+ ## 常見問題
122
+
123
+ ### 為什麼沒看到通知？
124
+
125
+ Windows 仍然有最終決定權。勿擾模式、通知設定、系統音效方案和靜音，都可能讓已提交的通知沒有彈出或沒有聲音。
126
+
127
+ 因為使用 `Microsoft.Windows.PowerShell` AppID，通知來源可能顯示 **PowerShell**，但彈窗本身會寫 **Pi**。Toast 自帶的音效關閉，提示音另外播放，避免這個 backend 自己重複響兩次。彈窗和音效分開處理，一個失敗仍會嘗試另一個；沒有備用通知方式或播放器。
128
+
129
+ 可以用 `/windows-notifier status` 查看診斷碼：
130
+
131
+ | 診斷碼 | 意義或處理方式 |
132
+ |---|---|
133
+ | `CONFIG_INVALID`／`CONFIG_TOO_LARGE`／`CONFIG_READ_FAILED` | 修正全域設定檔後 reload |
134
+ | `ENV_UNSUPPORTED` | 請使用支援的 Windows 64 位元 Pi 互動式介面 |
135
+ | `BACKEND_UNAVAILABLE` | 檢查 Windows 路徑、PowerShell 和 helper 是否可用 |
136
+ | `UI_AMBIGUOUS`／`TOOLS_LIMIT` | 無法安全辨識 UI 來源，或追蹤已達上限 |
137
+ | `QUEUE_DROPPED` | 佇列已滿，有通知被丟棄 |
138
+ | `HELPER_TIMEOUT`／`OUTPUT_LIMIT`／`LAUNCH_FAILED` | helper 超時、輸出過多或啟動失敗 |
139
+ | `TOAST_FAILED`／`SOUND_FAILED`／`BOTH_FAILED` | Windows 彈窗、音效或兩者提交失敗 |
140
+ | `INPUT_INVALID`／`INTERNAL_ERROR`／`HELPER_PROTOCOL` | 檢查套件安裝與 helper 協定 |
141
+
142
+ 自動通知錯誤最多每分鐘顯示一次終端警告。診斷只使用固定代碼，不會帶出 PowerShell 原始錯誤內容。
143
+
144
+ ## 開發
145
+
146
+ ```bash
147
+ npm ci --ignore-scripts
148
+ npm run verify
149
+ npm pack --dry-run
150
+ ```
151
+
152
+ 測試使用假時鐘、event bus 和 launcher。Windows 上也會檢查 PowerShell 語法與無效輸入。一般 `npm test` 不會跳彈窗或播放音效；測試範圍與仍需確認的項目見[驗證紀錄](docs/verification.md)。
153
+
154
+ ## 授權
155
+
156
+ MIT。上游來源和授權聲明見 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
package/THIRD_PARTY_NOTICES.md CHANGED
@@ -1,11 +1,12 @@
1
- # 上游來源與授權
1
+ # Third-party notices
2
2
 
3
3
  ## pi-permission-windows-notifier
4
4
 
5
- - 來源：https://github.com/zhangyu-ch/pi-permission-windows-notifier
6
- - 參考：988decb1a28a38a6d5b8aa940ec2ceca22088c54
7
- - 範圍：權限事件、WinRT DOM text node、固定 PowerShell AppID、系統音效及 Toast silent。
8
- - 本 package 重寫執行檔定位、stdin 協定、資源限制、取消、設定與狀態機。沿用／改作片段保留以下原始 MIT 授權：
5
+ - Source: https://github.com/zhangyu-ch/pi-permission-windows-notifier
6
+ - Reference commit: `988decb1a28a38a6d5b8aa940ec2ceca22088c54`
7
+ - Referenced features: permission events, WinRT DOM text nodes, the fixed PowerShell AppID, system sounds, and silent toast audio.
8
+
9
+ This package rewrites executable resolution, the stdin protocol, resource limits, cancellation, configuration, and the state machine. The following original MIT notice is retained for reused or adapted portions:
9
10
 
10
11
  ```text
11
12
  MIT License
@@ -31,10 +32,8 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
31
32
  SOFTWARE.
32
33
  ```
33
34
 
34
- ## 其他研究參考
35
-
36
- - UniPi notify：https://github.com/Neuron-Mr-White/UniPi/tree/main/packages/notify，參考 6ac5da3。只參考事件／backend 分層概念，未複製程式碼或引入 UniPi core／node-notifier。
37
- - pi-jingle：https://github.com/Git-Monke/pi-jingle，參考 7e265ce。只參考事件音效概念，未複製程式碼或音效，因為尚未確認其授權。
38
- - Pi、permission system、RPIV／Lean、Plan mode 的本機型別及原始碼用於核對契約，不把第三方程式碼放入發布包。
35
+ ## Other references
39
36
 
40
- 本地上游 checkout 位於 `../references/upstream/`，不受此 repository 管理。
37
+ - [UniPi notify](https://github.com/Neuron-Mr-White/UniPi/tree/main/packages/notify), reference commit `6ac5da3`: consulted for event/backend separation. No code was copied, and neither UniPi core nor node-notifier is included.
38
+ - [pi-jingle](https://github.com/Git-Monke/pi-jingle), reference commit `7e265ce`: consulted for the idea of event-specific sounds. Its license was not confirmed during development, so no code or audio assets were copied.
39
+ - Pi, pi-permission-system, RPIV/Lean, and Plan mode APIs and source were consulted to verify integration contracts. Their source code is not bundled in this package.
package/docs/verification.md CHANGED
@@ -1,26 +1,29 @@
1
- # 驗證紀錄
1
+ # 驗證與已知限制
2
2
 
3
- ## 自動檢查
3
+ ## 自動驗證
4
4
 
5
- - 本機 Windows、Node.js 24.18.0；開發型別依賴 Pi 1.1.0。
6
- - TypeScript noEmit 與 Node test runner 通過：32 個測試，0 失敗、0 跳過。
7
- - extension 入口可由 Node TypeScript strip-types 匯入；factory 未在此檢查中執行。
8
- - npm pack --dry-run 通過，發布清單為 13 個核准檔案，不產生／發布 tarball。
9
- - Windows PowerShell 語法解析與無效輸入路徑已執行，不呼叫 Toast 或音效。
10
- - mock 接線涵蓋 permission、RPIV／Lean、Plan mode 及完成／中止／失敗。
11
- - 涵蓋去重、取消、不明 UI、重試／續跑、空 run、開關、最小 payload、cwd／PATH 污染防護、佇列／輸出上限、timeout、reload／shutdown 清理。
12
- - 開發依賴使用 npm install --ignore-scripts；當次 npm audit 回報 0 個已知漏洞，不代表完整供應鏈或 OS 安全稽核。
13
- - 發布包只允許 metadata、runtime 原始碼、固定 helper、README、驗證文件及授權，不含 node_modules、測試、設定或上游 checkout。
5
+ - TypeScript `tsc --noEmit` 與 Node test runner 通過；測試覆蓋設定驗證、權限與提問事件、回應狀態、去重取消、限流佇列、PowerShell launcher、資源清理與發布檔案清單。
6
+ - Windows 測試檢查固定 PowerShell helper 語法及無效輸入；不呼叫 Toast 成功路徑，也不播放系統音效。
7
+ - 發布包以 npm pack dry-run 核對；僅包含套件 metadata、runtime 原始碼、PowerShell helper、文件及授權。
14
8
 
15
- ## 實機驗收狀態
9
+ 執行完整檢查：
16
10
 
17
- 已經使用者明確同意，透過正式 scheduler／backend 依序執行 permission、question、completed、aborted、failed 五種成功路徑。五次皆回傳 submitted／OK；使用者確認五種都有右下角彈窗與提示音。所有自有 child 等待 close 後結束，沒有安裝套件或變更 Windows／Pi 設定。
11
+ ```bash
12
+ npm ci --ignore-scripts
13
+ npm run verify
14
+ npm pack --dry-run
15
+ ```
18
16
 
19
- 以下仍未完成實機端到端驗收：
17
+ ## 實機驗證範圍
20
18
 
21
- 1. 真實互動式 Pi 的 permission ask、RPIV Lean、Plan mode、正常結束、Esc 及模型失敗（目前為 mock 接線驗證）。
22
- 2. 第三方 terminal bell 是否造成額外聲響。
23
- 3. 勿擾／通知關閉／靜音行為。
24
- 4. 不同 extension 載入順序、reload、OS 程序監看及網路活動觀察（資源限制已由自動測試覆蓋）。
19
+ Windows backend 的五類通知（permission、question、completed、aborted、failed）曾逐一送出，並經人工確認有 Toast 彈窗與提示音。
25
20
 
26
- mock 通過不能替代以上場景；一般提交成功不代表保證送達。這次可見／可聽 backend 結果由使用者確認，不能推論所有 Windows 環境皆通過。未自動安裝到使用者 Pi、未變更通知設定、未發布 npm 或 push。
21
+ 這項 backend 驗證不等於所有 Pi 整合情境均已端到端驗收。以下項目仍需在實際使用環境確認：
22
+
23
+ - `pi-permission-system` 的 ask／轉送權限請求。
24
+ - RPIV Lean 與 Plan mode 的結構化問題，以及第三方 terminal bell 是否造成額外聲響。
25
+ - Pi 正常結束、中止、錯誤及自動重試／續跑時的通知分類。
26
+ - Windows 勿擾、通知停用、靜音設定下的行為。
27
+ - 不同 extension 載入順序及 reload 後的實際程序生命週期。
28
+
29
+ 自動測試使用 mock event bus 與 mock launcher，不能替代上述真實 Pi 工作流程。Windows 可能抑制通知或音效；helper 回報提交成功不保證使用者一定看見或聽見。
package/package.json CHANGED
@@ -1,9 +1,17 @@
1
1
  {
2
2
  "name": "pi-windows-notifier",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Pi 的 Windows Toast 與系統提示音：權限、結構化提問及回應結束通知。",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/C-W-Z/pi-windows-notifier.git"
10
+ },
11
+ "homepage": "https://github.com/C-W-Z/pi-windows-notifier#readme",
12
+ "bugs": {
13
+ "url": "https://github.com/C-W-Z/pi-windows-notifier/issues"
14
+ },
7
15
  "engines": {
8
16
  "node": ">=22.19.0"
9
17
  },
@@ -17,6 +25,7 @@
17
25
  "src/**/*.ts",
18
26
  "src/windows-notify.ps1",
19
27
  "README.md",
28
+ "README.zh-TW.md",
20
29
  "docs/verification.md",
21
30
  "LICENSE",
22
31
  "THIRD_PARTY_NOTICES.md"