kenaz 0.0.0-stage → 0.3.2

package/core/dev/specs/agent-connect/SDK_GUIDE.md

@@ -0,0 +1,915 @@
+# Kenaz Agent Connect — SDK 開發指南 (SDK_GUIDE.md)
+
+給生態系網站開發者的接入文件。讀完本檔 + 跑過 `examples/minimal-site/`，你
+應該能在 30 分鐘內讓自己的網站完成一次「連接 Kenaz → 審批 → 終端分頁 →
+你的網站收到 `kenaz_hello`」的完整流程。
+
+- 協定權威規格：`./PROTOCOL.md`（v0.4）——本檔每一個參數、錯誤訊息、行為都
+  對照該檔與 Kenaz 目前 main 上的實作，不臆測未實作的功能。
+- 可跑範例：`./examples/minimal-site/`（零 npm 依賴的 Node 專案，`node
+  server.js` 三行指令起來）。
+- 適用範圍：**Kenaz 自家生態系網站**（目前是 app.kenazai.com、FlowPix），
+  不對外公開推廣。
+
+你不需要知道 Kenaz 內部怎麼運作——只需要知道深連結長什麼樣、你的 MCP 端點
+要滿足什麼約定，以及使用者會看到什麼畫面。
+
+---
+
+## 0. 心智模型
+
+```
+你的網站（瀏覽器）              使用者本機的 Kenaz             你的網站（後端 MCP）
+      │                                │                              │
+      │ 1. 按「連接」                   │                              │
+      │──── kenaz://connect?... ─────>│                              │
+      │        (OS 開啟 Kenaz)         │                              │
+      │                                │ 2. 顯示審批卡（第 3 節）        │
+      │                                │    使用者按下「允許」          │
+      │                                │ 3. 開一個終端分頁，                    │
+      │                                │    agent 掛著你的 MCP           │
+      │                                │────── kenaz_hello ──────────>│
+      │                                │                              │ 4. 記錄「已連線」
+      │<─────────（你自己的通道，例如輪詢/SSE）───────────────────────│
+      │ 5. UI 顯示「已連線」                                            │
+```
+
+三個事實決定了整份文件的形狀：
+
+1. **深連結本身就是完整的請求。** 沒有事先的配對步驟，沒有 relay，沒有
+   WebSocket。使用者按下「連接」那一下（同意深連結）就是 launch 本身。
+2. **Kenaz 沒有回程通道。** 你的網站完全靠 agent 呼叫你自己 MCP 的
+   `kenaz_hello` 工具才知道「連上了」。深連結送出去之後，Kenaz 不會再告訴
+   你任何事——不管是審批被拒絕、使用者沒裝 Kenaz、還是 agent 執行失敗。
+3. **Bearer 驗證是你的責任，不是 Kenaz 的。** Kenaz 只是把深連結裡的
+   `token` 原樣轉交給 agent 當 `Authorization: Bearer <token>`。誰簽發、
+   誰驗證、TTL 多長、怎麼撤銷，全部由你決定。
+
+---
+
+## 1. 10 分鐘接入
+
+### 步驟一：簽 token
+
+你的後端在使用者按下「連接」時，簽發一個一次性 bearer token（不要重複使用
+上一次連接時發過的 token），綁定你自己的用戶 session：
+
+```js
+import crypto from 'node:crypto';
+const token = crypto.randomBytes(24).toString('base64url'); // 或任何你熟悉的簽發方式
+// 存起來：token -> { userId, createdAt, ttl }，用你自己的 session 系統
+```
+
+Token 的唯一硬性限制（deep_link.rs 會驗證，見第 2 節）：長度 ≤ 512 字元，
+字元集限 `[A-Za-z0-9._-]`。除此之外由你自己決定形狀——JWT、隨機字串、資料
+庫查得到的 opaque ID 都可以，只要你自己的 MCP 端點認得它。
+
+### 步驟二：組深連結
+
+```js
+const params = new URLSearchParams({
+  site: 'https://your-site.example',       // 你的網站 origin
+  mcp: 'https://your-site.example/mcp',    // 你的 MCP 端點（完整 URL）
+  token,
+});
+const deepLink = `kenaz://connect?${params.toString()}`;
+```
+
+前端拿到這個 URL 後直接導覽過去（`window.location.href = deepLink` 或一個
+`<a href>`）：瀏覽器會把 `kenaz://` 交給 OS，OS 交給 Kenaz（若已安裝）。
+
+### 步驟三：MCP 加 bearer 驗證與 `kenaz_hello`
+
+你的 MCP 端點（任何符合 MCP Streamable HTTP 的伺服器都可以）必須：
+
+```js
+// 偽代碼——完整可跑版本見 examples/minimal-site/server.js
+function handleMcpRequest(req, res) {
+  const auth = req.headers['authorization']; // "Bearer <token>"
+  if (!isValidToken(auth)) { res.writeHead(401); res.end(); return; }
+  // ...JSON-RPC dispatch，至少要有 kenaz_hello 工具（見第 3 節）
+}
+```
+
+做完這三步，你的網站就符合 Kenaz Agent Connect 的最小約定了。完整範例見
+`examples/minimal-site/`。
+
+---
+
+## 2. 深連結
+
+### 格式
+
+```
+kenaz://connect?site=<url-encoded https origin>&mcp=<url-encoded https MCP url>&token=<one-time token>[&prompt=<url-encoded text>][&agent=claude|codex][&v=1]
+```
+
+### 參數表
+
+| 參數 | 必填 | 說明 |
+|---|---|---|
+| `site` | 是 | 你的網站 origin。正式環境必須是 `https://...`。開發模式（見第 5 節）允許 `http://localhost` / `http://127.0.0.1` / `http://[::1]`。Kenaz 用 `Url::origin()` 正規化，去掉 path/query/fragment。 |
+| `mcp` | 是 | 你的 MCP 端點，**完整 URL（含 path）**。scheme 規則與 `site` 相同。**審批卡上顯示的主要識別是這個 URL 的 host**，不是 `site`——沒有 relay 驗證過的 origin，`mcp` 是 agent 真正會連的對象。 |
+| `token` | 是 | 一次性 bearer，≤512 字元，字元集限 `[A-Za-z0-9._-]`。Kenaz 不解讀、不落盤——只在這次啟動期間以環境變數形式交給 agent 當 MCP 的 `Authorization: Bearer` 值。 |
+| `prompt` | 否 | 起始 prompt，交給 agent 當第一則訊息。**省略時由 Kenaz 保證仍有第一個 turn**——Kenaz 自己補一句開場訊息觸發它，你不必也不應該為了讓 agent 動起來而塞 `prompt=`（見第 9 節）。 |
+| `agent` | 否 | 指定 CLI，`"claude"` 或 `"codex"`。省略時依使用者自己的預設設定；顯式指定但使用者沒裝該 CLI 時 launch 直接失敗，**不會靜默退回別的 CLI**。 |
+| `v` | 否 | 協定版本，缺省 `"1"`。目前只有 `"1"` 是合法值；其他值一律 toast 拒絕，不出審批卡。 |
+
+任何其他未知參數一律靜默忽略，不拒絕；只有格式不合法（scheme 錯、`token`
+過長、`v` 不支援等）才拒絕。
+
+### URL 編碼規則
+
+每個參數值都要 `encodeURIComponent`（JS 的 `URLSearchParams` 會自動做這件
+事——見第 1 節範例）。`site`/`mcp` 是完整 URL，所以本身就含有會被
+percent-encode 的字元（`:`、`/`），這是預期行為，不是 bug。
+
+### 長度限制與「大內容放哪裡」
+
+深連結整體長度在 Windows 上約有 **2 KB** 限制（作業系統層級，不是 Kenaz 定
+的）。這代表：
+
+- `prompt` 只放**簡短**的起始指示。
+- 任何長內容（畫布狀態、文件全文、使用者的完整輸入）**不要塞進
+  `prompt=`**——讓 agent 呼叫你自己 MCP 的其他工具去讀取，你的工具回傳內容
+  或一個可再次 fetch 的 URL 即可。這也是第 3 節「大檔案走 URL」的同一個
+  原則：深連結和 MCP 工具的回應都不是傳大檔案的地方，讓 agent 自己再發一
+  次請求去拿。
+- `prompt` 支援任意 UTF-8（含 CJK），你只要照正常的
+  `encodeURIComponent` percent-encode 即可；Windows 上把內嵌 prompt 正確
+  解碼（不會被系統 ANSI codepage 亂碼化）是 Kenaz 這一側的責任，不需要你
+  額外處理。
+
+### `v` 版本
+
+省略時視為 `"1"`。目前整個協定只有版本 `"1"`；`v=999` 這種未來/錯誤的版本
+號會被**明確拒絕**（toast「protocol version unsupported: 999」），不會被
+當成 `"1"` 靜默處理，也不會出審批卡。這是刻意設計：深連結本身就是唯一的請
+求，沒有線上協商步驟能事後補救版本不合的情況，所以必須在這裡就失敗大聲。
+
+### `agent` 的語意
+
+- 省略：用使用者自己在 Kenaz 裡設定的預設 CLI/model。
+- 指定 `"claude"` 或 `"codex"`：**只有這兩個字面值**合法（但注意：`agent=`
+  不合法值目前不會被 deep_link.rs 拒絕——它會原樣往後傳，直到
+  `launch::execute` 內部解析 CLI 時才會因為「這個 CLI 不存在/未安裝」而
+  失敗，見第 6 節疑難排解表）。
+- 指定了但使用者沒裝該 CLI：**launch 直接失敗**，不會退回使用者的預設
+  CLI——設計上你的 `agent=` 指定要不就完全生效，要不就明確失敗，不會有「我
+  以為在跑 codex 結果其實在跑 claude」這種混淆。
+
+---
+
+## 3. 網站 MCP 最小約定
+
+任何網站只要提供一個符合下列約定的 MCP 端點，就能被 Kenaz 的深連結串接。
+Kenaz **不列舉、不審核、不限制**你的 MCP 提供什麼工具——這一節只講「必須
+有」和「建議有」的最小子集。
+
+### 3.1 Bearer 驗證：簽發、TTL、撤銷建議
+
+- 每個請求的 `Authorization: Bearer <token>` 必須被你的伺服器驗證是**自己
+  簽發、未過期、未撤銷**的。Kenaz 完全不驗證這個 token——它只是深連結裡
+  那串字元的原樣轉交者。這是你的網站唯一需要信任的邊界。
+- **簽發**：每次使用者按下「連接」都簽一個新的 token，不要重複使用上一次
+  的。把 token 綁定到你自己的登入 session，這樣即使 token 外洩，攻擊者能
+  做的事也被限制在那個使用者的權限範圍內。
+- **TTL**：建議短——這個 token 只需要活到這次終端分頁的session 期間。過期
+  就讓後續的 MCP 呼叫全部 401。
+- **撤銷**：如果你的網站有「登出」或「撤銷授權」功能，記得同時讓對應的
+  token 立刻失效，不要只靠 TTL 到期。
+
+### 3.1b `X-Kenaz-Session` header（選讀）與工具權限（TASK_1947）
+
+- 除了 `Authorization: Bearer <token>`，Kenaz 對每個請求還會**一律**多送一
+  個 `X-Kenaz-Session: <launch_id>` header。`<launch_id>` 是 Kenaz 在這次
+  啟動一開始就產生的 uuid v4，同一次深連結啟動的存續期間固定不變。
+- 這個 header 是**選讀**的——bearer 仍是唯一你必須驗證的邊界（見 3.1）。
+  它存在的用途：如果你想分辨「這次 MCP 呼叫屬於哪一次連接」，`launch_id`
+  比單純用 token 對應更直接——同一個 token 理論上可能被同一使用者的多個
+  分頁/連接重用，但 `launch_id` 保證每次啟動獨一無二。
+- 範例（claude 分支預配的 MCP config JSON，見
+  `dev/specs/agent-connect/PROTOCOL.md` §2 fixture
+  `mcp.config_with_session_header`）：
+
+  ```json
+  {"mcpServers": {"flowpix": {"type": "http", "url": "https://flowpix.app/mcp", "headers": {"Authorization": "Bearer a1b2c3d4e5f60718293a4b5c6d7e8f90", "X-Kenaz-Session": "1b0d6b9a-8f2a-4c56-8abc-9f9e9c9d9e9f"}}}}
+  ```
+
+- **本機除錯**：使用者自己在本機呼叫 `GET /api/agent-hub/status` 時，每個
+  origin 底下會列出 `sessions[]`（`session_id` 就是這個 `launch_id`、還有
+  `agent`/`model`/`cwd`/`started_at`/`alive`）——這是給使用者自己排查
+  「Kenaz 現在覺得有幾個連線活著」用的本機端點，不是你的網站能呼叫的（僅
+  限 `127.0.0.1`，見第 4 節「被封鎖後怎麼辦」）。
+- **工具權限**：使用者在審批卡按下允許，等於同意了這個 session 使用你的
+  MCP 工具——claude 分支因此會在啟動前對你的 MCP 做一次 `tools/list` 探
+  測，把**依 tool annotations 判定為安全**的工具加進
+  `--allowedTools`，讓 agent 呼叫那些工具時不用再跳一次終端機權限詢問；
+  沒被判定為安全的工具維持逐次詢問。這個允許清單**只**涵蓋你這個 MCP
+  server 的工具，不會放寬到別的工具。判定規則、探測失敗時的退回行為見
+  3.1c。codex 分支目前沒有等效的「只允許某個 MCP」設定可加、也不套用
+  annotations 分級（查證結論見 PROTOCOL.md「codex 限制」一節）——如果使
+  用者用 codex 跑你的網站，第一次工具呼叫是否會跳審批目前未完全驗證。
+
+### 3.1c `--allowedTools` 依 tool annotations 分級（TASK_1949，Agent Connect C-1b）
+
+- **這是什麼**：3.1b 提到 claude 分支會預先允許部分工具跳過終端機權限詢
+  問——這一節說明「部分」是怎麼判定的。MCP 規格的 tool `annotations`
+  （`readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`）
+  讓你不用發明新協定就能告訴 Kenaz「這個工具有沒有後果」。
+- **判定規則**：你的 `tools/list` 回應裡，一個工具的
+  `annotations.readOnlyHint == true` **或** `annotations.destructiveHint ==
+  false` 時，會被加進 `--allowedTools`。**沒有 `annotations` 物件、或有
+  `annotations` 但沒寫 `destructiveHint`，一律不會被預先允許**——MCP 規
+  格對 `destructiveHint` 的預設值就是 `true`，Kenaz 沿用這個保守預設，不
+  是自創規則。範例（見 PROTOCOL.md §2 fixture
+  `mcp.tools_list_with_annotations`）：
+
+  ```json
+  {"jsonrpc": "2.0", "id": 1, "result": {"tools": [{"name": "kenaz_hello", "annotations": {"destructiveHint": false, "idempotentHint": true}}, {"name": "kenaz_wait_for_message", "annotations": {"readOnlyHint": true}}, {"name": "echo", "annotations": {"readOnlyHint": true}}, {"name": "delete_all_data", "annotations": {"destructiveHint": true}}]}}
+  ```
+
+  這個範例裡只有前三個工具會被預先允許；`delete_all_data`
+  （`destructiveHint: true`）維持每次呼叫都跳終端機詢問。
+- **探測時機與逾時**：Kenaz 在組出啟動腳本前，對你的 `mcp=` 端點送一次
+  `tools/list` JSON-RPC 請求（header 與其他 MCP 呼叫相同：`Authorization:
+  Bearer <token>` + `X-Kenaz-Session`），**逾時 3 秒**。
+- **探測失敗時的退回**：逾時、HTTP 非 2xx、回應不是合法 JSON、或回應裡
+  沒有 `result.tools` 陣列——**任何一種都不會預先允許任何工具**（不是退
+  回舊版的全部允許，也不代表你的 MCP 整個不能用），並且會在啟動的終端
+  分頁第一行印出失敗原因，方便你自己的使用者（或你自己除錯時）看到
+  「為什麼每次工具呼叫都要按一下」。探測成功時同樣會印一行摘要（例如
+  `pre-allowed 2/4 MCP tools by annotations`）。
+- **你不需要做任何事才能運作**——不標 annotations 完全不影響功能，你的
+  工具照樣能被呼叫，唯一差別是每次呼叫都會在終端機多跳一次確認。標了
+  annotations 純粹是幫使用者少按幾次。
+
+### 3.2 `kenaz_hello`：回應形狀與逾時處理
+
+- **建議**（不是強制，但沒有它你的網站永遠不知道有沒有連上）提供一個
+  `kenaz_hello` 工具：**無參數**，成功回：
+
+  ```json
+  {"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "{\"ok\":true}"}], "isError": false}}
+  ```
+
+  對應的呼叫長這樣：
+
+  ```json
+  {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "kenaz_hello", "arguments": {}}}
+  ```
+
+- Kenaz 注入給 agent 的人格會在處理 `prompt` **之前**呼叫這個工具一次
+  ——這是你的網站得知「Kenaz 真的連上了」的**唯一方式**（沒有回程通道，
+  見第 0 節）。
+- **逾時處理**：建議設 **60 秒**。深連結送出去之後，如果 60 秒內沒有收到
+  `kenaz_hello` 呼叫，就把前端 UI 從「連線中」切到「請安裝 Kenaz」之類的
+  安裝指引（第 4 節有完整的偵測/fallback 邏輯）。60 秒逾時涵蓋了「使用者
+  沒裝 Kenaz」「使用者拒絕了審批卡」「使用者封鎖了你的網站」這幾種你**分
+  辨不出來**的情況——見第 6 節疑難排解。
+
+### 3.3 工具命名：`mcp__<name>__` 前綴由 Kenaz 決定
+
+Kenaz 把你的 MCP 掛給 agent 時，會用一個從你的 **`mcp=` URL 的 hostname**
+衍生出來的名字當作 MCP server 名稱，agent 看到的完整工具名稱因此是
+`mcp__<name>__<你的工具名>`：
+
+- `mcp=https://flowpix.app/mcp` → `<name>` = `flowpix` → agent 呼叫的是
+  `mcp__flowpix__kenaz_hello`
+- `mcp=https://sub.example.com/mcp` → `<name>` = `sub`（取 hostname 第一個
+  `.` 之前的 label）
+- 衍生規則：hostname 的第一個 label，非英數字元一律換成 `_`；解析失敗或
+  結果是空字串則用 `site` 當預設名。
+
+**你完全不用自己決定或宣告這個前綴**——你只要決定你自己的工具名（例如
+`kenaz_hello`、`echo`），Kenaz 會自動加上從你的 MCP hostname 衍生的
+server 名稱前綴。這代表：你的 `mcp=` hostname 最好是穩定、看起來像正常英
+數字元的網域名稱，不要依賴前綴本身帶有特殊語意。
+
+### 3.4 其餘工具完全自訂
+
+你的產品邏輯（生圖、寫回、查詢……）全部經由自訂的 MCP 工具與 agent 互動，
+Kenaz 對這段流量完全不可見。設計這些工具時記得：
+
+- **大檔案走 URL**：工具的回應不要塞入大量二進位或超長文字——回傳一個
+  你自己網站可以再次驗證 bearer 後提供內容的 URL，讓 agent 用你的其他機
+  制（例如你自己網站上的一個已認證下載端點）去取，而不是塞進單一次
+  JSON-RPC 回應裡。這與深連結 `prompt=` 的 2 KB 限制是同一個設計原則的兩
+  處體現。
+- **沒有結束通知**：agent 的終端分頁何時關閉，你的網站不會被告知。用
+  token 撤銷或閒置逾時回收狀態，不要假設有「已結束」事件。
+
+---
+
+## 4. 使用者體驗
+
+### 審批卡上會顯示什麼
+
+使用者按下深連結、Kenaz 判斷這個 origin 不是 `always`/`blocked` 狀態時，
+會跳出一張審批卡，內容固定是：
+
+```
+{site} → MCP {mcp_host} → {agent}/{model} · cwd {絕對路徑} · {prompt 前 120 字}
+```
+
+- **site**：深連結 `site=` 的 origin（你的網站自稱，未經第三方驗證）。
+- **MCP host**：`mcp=` URL 的 hostname——**這是主要識別**，因為沒有 relay
+  驗證過的 origin，這個 host 才是 agent 真正會連上的對象。
+- **agent/model**：實際會用的 CLI 與 model（沒指定 `agent=` 就是使用者的
+  預設值）。
+- **cwd**：agent 會在哪個資料夾執行——**永遠是 Kenaz Dashboard 目前開啟的
+  專案，你的網站不能指定**。這一項刻意不可省略：使用者按允許前必須知道
+  這次操作會發生在哪個資料夾。
+- **prompt 前 120 字**：你的 `prompt=`（若有）截斷到 120 個字元。
+
+### 一次／永遠允許／拒絕／封鎖是什麼意思
+
+Per-origin 四態，鍵值是你的 `site=` origin（不是 `mcp=`）：
+
+| 狀態 | 意義 | 下一次同一 origin 的深連結會發生什麼 |
+|---|---|---|
+| `unauthorized`（初次） | 從沒授權過 | 出審批卡 |
+| `once`（使用者按「允許」） | 這次允許，下次再問 | 出審批卡 |
+| `always`（使用者按「永遠允許」） | 跳過審批卡 | **直接執行**（仍會在本機記一筆事件） |
+| `blocked`（使用者按「封鎖」，或手動編輯設定檔） | 完全不信任這個 origin | **直接拒絕，連 toast 都只在 Kenaz 本機顯示，你的網站完全看不到** |
+
+一個被使用者暫停的 Agent Hub（tray「Pause Agent Hub」）會擋下**所有**深連
+結，包含 `always` 狀態的 origin，而且同樣不出審批卡。
+
+### 被封鎖後怎麼辦
+
+**你的網站完全無法得知自己被封鎖了**——沒有回程通道，被封鎖的請求和「使
+用者根本沒裝 Kenaz」在你的網站端看起來一模一樣（都是 `kenaz_hello`
+逾時，見第 3.2 節與第 6 節）。能解除封鎖的只有使用者自己，在自己的機器
+上，透過下面任一方式：
+
+- Kenaz 本機的狀態 API（`http://127.0.0.1:18080`，僅限本機呼叫）：
+  - `GET /api/agent-hub/status` 列出所有 origin 目前的狀態。
+  - `POST /api/agent-hub/revoke {"origin": "https://your-site.example"}`
+    會**整筆刪除**這個 origin 的紀錄（含 `blocked` 狀態），下一次深連結
+    會重新從 `unauthorized` 出審批卡。
+- 或直接編輯 `~/.kenaz/agent_hub/sites.json`，把該 origin 的 `state` 改掉
+  （Kenaz 每次請求都重新讀檔，不吃記憶體快取，改完立即生效）。
+
+**你的網站文件應該教使用者**：如果「連接」按了很久都沒反應，除了「還沒安
+裝 Kenaz」之外，也可能是之前不小心按過「封鎖」——請使用者自己去確認。
+
+### 「請安裝 Kenaz」的偵測與 fallback
+
+因為沒有回程通道，偵測「使用者沒裝 Kenaz」的**唯一**方法是逾時：
+
+1. 導覽到 `kenaz://connect?...`。
+2. 同時開始輪詢（或用你自己的推播通道）等待 `kenaz_hello` 被呼叫。
+3. 一段時間（建議跟 `kenaz_hello` 的 60 秒逾時對齊）內沒有收到，就顯示
+   「請安裝 Kenaz」的安裝指引頁面 / 下載連結。
+
+`examples/minimal-site/public/index.html` 有這個邏輯的完整實作
+（`pollStatus` + `HELLO_TIMEOUT_MS`），可以直接參考或複製。注意：瀏覽器對
+未註冊的自訂 scheme 導覽通常是靜默失敗（頁面不會跳轉、不會拋錯），所以
+**不要**指望用 `catch` 或 `beforeunload` 之類的事件偵測「有沒有裝」——用
+逾時輪詢才是唯一可靠的做法。
+
+---
+
+## 5. 開發模式
+
+正式環境的 `site=`/`mcp=` 必須是 `https://`。要在本機用
+`http://localhost` / `http://127.0.0.1` / `http://[::1]` 測試（例如你的
+開發伺服器還沒有 HTTPS），需要 Kenaz 端也進入開發模式：
+
+- **`KENAZ_AGENT_HUB_DEV=1`**：設這個環境變數啟動 Kenaz，或者
+- Kenaz 本身是 **debug build**（`cfg!(debug_assertions)`）——本機 `cargo
+  tauri dev` 跑起來的版本預設就滿足這個條件，不需要額外設環境變數。
+
+**環境變數只在行程啟動當下讀取一次**。這代表：
+
+- 如果 Kenaz 已經在背景執行（含縮到 tray），**改環境變數不會讓正在跑的那
+  個行程生效**——必須先從 tray 選單選「Quit」讓 Kenaz **完整退出**（不是
+  關視窗，關視窗通常只是縮到 tray），再重新啟動一次帶著
+  `KENAZ_AGENT_HUB_DEV=1` 的行程。
+- 這是最常見的「明明設了環境變數，dev 深連結還是被拒絕」的原因——見第 6
+  節疑難排解表。
+
+**Dev 深連結指向 `target\debug` 的行為**：Debug build 在啟動時（`.setup()`
+內）會呼叫 `register_all()`，把 OS 的 `kenaz://` scheme 註冊指向**這次啟
+動的那個執行檔**（通常是 `target\debug\kenaz-dashboard.exe`）。這代表：
+
+- 如果你的機器上同時有「一般安裝的 Kenaz」和「本機 build 的 dev
+  Kenaz」，dev build 一啟動就會把 `kenaz://` 的 OS 註冊**改指向自己**，
+  之後所有 `kenaz://connect` 深連結（包含正式網站點出來的）都會打開 dev
+  版本，直到你重新安裝/啟動正式版覆蓋回去。開發時如果發現深連結打開了不
+  預期的 Kenaz 視窗，先檢查是不是這個原因。
+
+---
+
+## 6. 測試
+
+### 對自己的 MCP 端點做煙霧測試（不需要 Kenaz）
+
+你不需要真的裝 Kenaz 才能驗證你的 MCP 端點符不符合第 3 節的約定——因為
+Kenaz 對你的 MCP 來說就是「一個會帶著正確 bearer 呼叫 `kenaz_hello`、以及
+帶著錯誤/缺失 bearer 呼叫任何工具」的 HTTP client，這兩件事你可以直接用
+`curl` 或任何 HTTP client 模擬：
+
+```bash
+# 1. 錯誤 bearer 必須 401
+curl -i -X POST https://your-site.example/mcp \
+  -H 'content-type: application/json' \
+  -H 'authorization: Bearer wrong-token' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"kenaz_hello","arguments":{}}}'
+
+# 2. 正確 bearer 呼叫 kenaz_hello 必須回 {"ok":true}
+curl -i -X POST https://your-site.example/mcp \
+  -H 'content-type: application/json' \
+  -H 'authorization: Bearer <一個你自己簽發的合法 token>' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"kenaz_hello","arguments":{}}}'
+```
+
+`examples/minimal-site/test/smoke.test.mjs` 是這個模式的完整
+`node --test` 版本（起一個真的 HTTP server、真的送請求、結束時關閉伺
+服器），可以直接拿來當你自己 MCP 端點測試的樣板——把 `createServer()` 換
+成你自己的伺服器啟動函式即可。
+
+**目前沒有一個「假 Kenaz」npm 套件**能自動幫你送出 `kenaz://connect` 並模
+擬 agent 呼叫 `kenaz_hello`（SDK 規格 §2.4 把它列為 C 期產出，尚未發佈）
+——上面的 curl / smoke test 手法就是目前**唯一已驗證可行**的「不裝 Kenaz
+也能測」方式：既然 Kenaz 對你的 MCP 來說只是「一個會呼叫工具的 HTTP
+client」，直接模擬那個 client 的行為，比等一個尚未存在的模擬器更直接。
+
+### Conformance suite（Kenaz 這一側的測試）
+
+`dashboard/scripts/agent-connect-conformance/run.mjs` 是 Kenaz 專案自己
+的 conformance suite，驗證兩件事：
+
+1. `PROTOCOL.md` 裡的 `#### Fixture: deep_link.*` / `mcp.*` 區塊都是合法
+   JSON，且深連結 fixture 的形狀符合第 2 節的參數表。
+2. Kenaz 自己的假 MCP（`dashboard/scripts/agent-hub-fake-mcp.mjs`）確實會
+   對錯誤 bearer 回 401、對 `kenaz_hello` 回 `{"ok":true}` 並記錄呼叫。
+
+這個 suite **目前測的是 Kenaz 自己的假 MCP，不是可以指向任意第三方 MCP
+URL 的通用工具**——它不是你驗證自己網站 MCP 端點的方式；你的驗證方式是上
+面的 curl / smoke test。它們驗證的是同一件事（bearer 401 + `kenaz_hello`
+形狀），只是分別跑在 Kenaz 這一側與你這一側。跑法：
+
+```bash
+node --test dashboard/scripts/agent-connect-conformance/run.mjs
+```
+
+### 對真 Kenaz 做一次端到端連接（需要安裝或本機跑 Kenaz）
+
+1. 依第 5 節設定開發模式並完整重啟 Kenaz。
+2. 跑起 `examples/minimal-site/`（`node server.js`）。
+3. 瀏覽器打開範例頁面，按「連接 Kenaz」。
+4. 預期看到：審批卡（site/MCP host/agent/model/cwd/prompt 都符合第 4 節格
+   式）→ 按「允許」→ Dashboard 開一個新的終端分頁 → agent 在處理 prompt
+   之前呼叫 `mcp__<name>__kenaz_hello` → 範例頁面的輪詢偵測到「已連線」。
+
+---
+
+## 7. 疑難排解
+
+### Toast 訊息對照表
+
+Kenaz 拒絕深連結時，只會在**自己本機**顯示一個 toast（你的網站看不到，
+沒有回程通道）。下表逐字對照 Kenaz 目前 main 上
+`dashboard/src-tauri/src/features/agent_hub/deep_link.rs` 的
+`DeepLinkError` Display 實作與 `mod.rs::handle_incoming_url` 組出的完整
+toast 文字：
+
+| 情況 | 完整 toast 文字 | 你該怎麼修 |
+|---|---|---|
+| URL 完全無法解析 | `Rejected deep link: not a parseable URL` | 檢查有沒有漏編碼、字串是不是完整的 URL |
+| scheme 不是 `kenaz` | `Rejected deep link: unsupported scheme: <scheme>` | 確認開頭是 `kenaz://` |
+| host 不是 `connect` | `Rejected deep link: not a connect action` | 確認是 `kenaz://connect?...`，不是別的 action |
+| 缺少必填欄位 | `Rejected deep link: missing field: site` / `mcp` / `token` | 檢查第 2 節參數表——`site`/`mcp`/`token` 三個都必填 |
+| `site` 不是合法 URL | `Rejected deep link: site is not a parseable URL` | 確認 `site=` 是一個完整、可解析的 URL |
+| `site` scheme 不允許 | `Rejected deep link: site scheme not allowed: http` | 正式環境用 `https://`；本機測試需要開發模式（第 5 節）且 host 必須是 `localhost`/`127.0.0.1`/`[::1]` 其中之一（bracket 形式的 `[::1]`，其他 IPv6 位址不算） |
+| `mcp` 不是合法 URL | `Rejected deep link: mcp is not a parseable URL` | 確認 `mcp=` 是一個完整、可解析的 URL |
+| `mcp` scheme 不允許 | `Rejected deep link: mcp scheme not allowed: http` | 同上，`mcp=` 適用一模一樣的 https/開發模式規則 |
+| `token` 是空字串 | `Rejected deep link: token is empty` | `token=` 不能是空值 |
+| `token` 超過 512 bytes | `Rejected deep link: token too long: <n> bytes` | 縮短你的 token；大內容走第 3.4 節「大檔案走 URL」 |
+| `token` 含不合法字元 | `Rejected deep link: token has invalid characters` | 字元集只能是 `[A-Za-z0-9._-]` |
+| `v` 不是 Kenaz 支援的版本 | `Rejected deep link: protocol version unsupported: <v>` | 目前只支援 `v=1`（或省略）；不要自己編一個版本號 |
+| Agent Hub 被使用者暫停（tray「Pause Agent Hub」） | `Agent Hub is paused` | 這是使用者自己的選擇，你的網站無法繞過；只能等使用者自己恢復 |
+| origin 是 `blocked` 狀態 | `<你的 site origin> is blocked` | 見第 4 節「被封鎖後怎麼辦」——只有使用者自己能解除 |
+| 使用者在審批卡按了「拒絕」 | （不會 toast——只是安靜地不執行；`Decision::Deny`） | 這是正常拒絕流程，不是錯誤；你的網站一樣只能靠逾時偵測 |
+| Launch 本身失敗（審批通過**之後**） | `[<error_code>] <錯誤訊息>`，例如 `[agent_unavailable] requested agent "codex" is not installed (probed \`codex --version\`)` 或 `[not_logged_in] codex is not logged in — run \`codex login\` before this site can generate anything` | 通常是使用者本機環境問題（CLI 沒裝、沒登入），不是你網站端能修的；`agent=` 若指定了不存在的 CLI 會落在這裡，不是落在深連結驗證階段 |
+
+**重要**：以上全部只在 Kenaz 本機顯示，你的網站永遠看不到。你能做的只有
+第 4 節講的逾時偵測 + fallback 頁面，以及在你自己的文件裡引導使用者去看
+Kenaz 視窗的 toast。
+
+### 常見錯誤
+
+- **「按了連接沒反應」**：先確認瀏覽器有沒有跳出「要不要用 Kenaz 開啟這個
+  連結」的系統對話框——大部分瀏覽器對未安裝的自訂 scheme 是完全靜默的，
+  不會有任何視覺回饋。用第 4 節的逾時偵測，不要假設「沒反應」等於使用者
+  看到了什麼。
+- **「dev 模式設了環境變數還是被拒絕 `site scheme not allowed: http`」**
+  ：Kenaz 沒有完整重啟過（見第 5 節——環境變數只在行程啟動當下讀一次，
+  必須先 tray Quit 再重開）。
+- **「MCP 一直收不到 `kenaz_hello`，但審批卡有出現而且我按了允許」**：先
+  用第 6 節的 curl 手法確認你的 MCP 端點本身沒問題（bearer 對得上、
+  `kenaz_hello` 回應形狀正確）。如果 MCP 端點本身沒問題，通常是 agent
+  端啟動失敗（見上面「Launch 本身失敗」那一列的 toast），跟你的網站/MCP
+  無關。
+- **「同一個 origin 明明按過永遠允許，這次又跳審批卡」**：檢查是不是換了
+  `mcp=` 的 hostname 或整個換了瀏覽器/使用者 profile——四態權限的 key 是
+  `site=` 的 origin，不是 `mcp=`，正常情況下換 `mcp=` 不會重置狀態，但如
+  果連 `site=` 都變了（例如從 `https://your-site.example` 換成
+  `https://www.your-site.example`）就是不同 origin，會重新從
+  `unauthorized` 開始。
+
+---
+
+## 8. 安全
+
+- **Token 不可重用**：每次「連接」都簽一個新的一次性 token，不要把同一個
+  值發給下一次連接請求——重用會讓你失去「這個 token 對應哪一次連接」的可
+  追蹤性，也讓撤銷變得沒有意義。
+- **不要把長期憑證放進深連結**：深連結的 `token=` 只應該是一個短命、限定
+  用途的 bearer，绑定這一次連接。不要把使用者的長期 API key、OAuth
+  refresh token 之類的東西直接塞進 `token=`——深連結會經過 OS 的 URL
+  handler，也可能被瀏覽器歷史記錄或系統日誌留下痕跡。
+- **MCP 只信 bearer，不要信任何其他隱含的信任來源**：Kenaz 不會替你驗證
+  `token`；你的 MCP 端點收到的每一個請求都要自己驗證
+  `Authorization: Bearer <token>`，不要假設「請求是從 Kenaz 打來的所以一
+  定合法」——任何知道你 MCP URL 的人都可以直接對它送 HTTP 請求，繞過整個
+  深連結流程。
+
+---
+
+## 9. 持續對話：`kenaz_wait_for_message`（TASK_1948，FlowPix S2）
+
+第 3 節的 `kenaz_hello` 只解決「連上了沒」——如果你的網站想在那之後**繼續
+跟 agent 對話**（例如你自己的聊天 UI 使用者又打了一行字，或畫布又產生了新
+的狀態要交給 agent 處理），過去唯一的做法是自己在 `prompt=` 或某個工具的
+回應裡塞一堆「請持續呼叫我」的 prompt 工程指令，效果不穩定也不可測試。
+v0.4 把這件事收斂成一個**可選的**約定工具，讓「agent 會不會一直聽」這件事
+從你的 prompt 措辭搬進 Kenaz 人格本身。
+
+### 這是什麼
+
+你的 MCP 若在 `tools/list` 多提供一個無參數工具 `kenaz_wait_for_message`，
+Kenaz 注入的 Ansuz 人格會在呼叫過 `kenaz_hello`、處理完 `prompt` 之後，
+**自動反覆呼叫它**，不需要你在 prompt 裡寫任何「請持續輪詢」之類的指
+令——完全不提供這個工具的網站，行為與現在完全一樣（agent 只呼叫一次
+`kenaz_hello`，之後就照 prompt 跟你其餘的工具互動，不會提起、也不會呼叫
+一個不存在的工具）。
+
+**`prompt` 省略時由 Kenaz 保證**（TASK_1956）：CLI 的第一個位置參數就是互
+動式會話的第一則使用者訊息，省略/空字串在機制上等於「沒有第一個
+turn」——連 Kenaz 注入的人格本身都不會被 agent 讀到，`kenaz_hello`／
+`kenaz_wait_for_message` 這整套約定自然也就永遠不會發生。Kenaz 因此在
+`prompt` 為空/空白時，自己補一句純 ASCII 的開場訊息（帶你的 `site`
+origin）當作這第一則訊息，讓上面這段流程照樣跑起來。**這代表你完全不需
+要、也不應該**為了讓 agent「動起來」而自己塞一句 `prompt=` 當觸發
+器——那正是這個約定原本要讓你省掉的 prompt 工程。
+
+### 回應形狀
+
+```json
+{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "kenaz_wait_for_message", "arguments": {}}}
+```
+
+```json
+{"jsonrpc": "2.0", "id": 2, "result": {"content": [{"type": "text", "text": "{\"message\":\"add a red circle to the canvas\",\"message_id\":\"m_1\",\"end\":false}"}], "isError": false}}
+```
+
+- `message` 非 `null`：agent 把它當成使用者的下一則指令執行，執行完再呼叫
+  一次。
+- `message` 為 `null`：目前沒有新訊息，不是錯誤——agent 直接再呼叫一次
+  （這是**預期的常態**，不是逾時或失敗）。
+- `end` 為 `true`（可省略，預設 `false`）：agent 停止呼叫，告知使用者對話
+  已結束。
+- agent 連續呼叫這個工具失敗（逾時、拋錯、連線失敗）達 **3 次**，也會停
+  止並告知使用者——你不需要自己實作「停止」邏輯之外的任何額外信號。
+
+完整的權威規格見 `./PROTOCOL.md` 第 2 節第 5 點；`examples/minimal-site/
+server.js` 有一份可跑的參考實作（記憶體信箱：`POST /message` 投遞，
+`kenaz_wait_for_message` 長輪詢拉取，見該範例的 README「持續對話」一節）。
+
+### 用長輪詢實作，不是短輪詢——這個成本算在使用者頭上
+
+**這是本節唯一的強制條款**：`kenaz_wait_for_message` 的每一次呼叫都是一次
+真實的 agent turn，成本由**呼叫它的 Kenaz 使用者自己的訂閱額度**承擔，不
+是你網站的成本。這代表：
+
+- 你的伺服器端實作**必須**用長輪詢——收到請求後，如果暫時沒有新訊息，先
+  阻塞著（建議 **20-25 秒**）等新訊息進來，逾時了才回 `message: null`；
+  不要立刻回應。
+- **不得**用短輪詢（例如每 1 秒就回一次 `null`，靠 agent 自己在 1 秒後再
+  呼叫一次）——這會讓 agent 為了等你的下一則訊息，高頻率地消耗使用者的
+  訂閱額度，而這個消耗對你的網站完全免費、對使用者卻是真金白銀。把長輪
+  詢窗口拉長，是你對使用者訂閱額度的責任，不是效能優化的選項。
+
+### 跟 FlowPix 自己的信箱模式的對照
+
+如果你已經有一套「使用者訊息 → 佇列 → worker 拉取處理」的信箱/佇列架
+構（FlowPix 內部原本就是這樣：畫布事件先進一個佇列，worker 再消費），
+`kenaz_wait_for_message` 幾乎是直接把你信箱的**消費端**換成「agent 呼叫
+的 MCP 工具」而已：
+
+| FlowPix 原有信箱模式 | `kenaz_wait_for_message` |
+|---|---|
+| worker 對佇列做長輪詢 / blocking pop | agent 對你的 MCP 工具做長輪詢式呼叫 |
+| 佇列裡的一筆訊息 | 回應裡的 `message` 欄位 |
+| 訊息的唯一 ID（供去重/確認） | `message_id` 欄位 |
+| worker 收到「關閉佇列」信號就停止消費 | 回應裡的 `end: true` |
+| 佇列基礎設施掛了，worker 重試幾次後放棄 | 連續呼叫失敗 3 次，agent 放棄並告知使用者 |
+
+差異只在於：你的信箱現在多了一個**消費者是 Kenaz 使用者本人的 agent
+turn**，每次消費都有真實成本（見上一節）——這也是為什麼即使你已經有一套
+成熟的信箱架構，也不建議把它原本對內部 worker 用的短輪詢頻率原封不動套
+用到這個工具上。
+
+### 這節不涵蓋什麼
+
+- **不涵蓋 agent 輸出串流回你的網站**（S3，未分期）——`kenaz_wait_for_
+  message` 只是「網站 → agent」單向的訊息投遞，agent 執行過程或結果不會
+  透過這個機制串流回你的網站；如果你需要看到執行進度，一樣得靠你自己另
+  外設計的工具（例如 agent 主動呼叫的一個「回報進度」工具）。
+- **不涵蓋 agent 主動通知「我結束了」**（S4，未分期）——`end: true` 只是
+  你告訴 agent「別再問了」，不是 agent 告訴你「我做完了」；agent 結束一
+  段對話（不管是你送了 `end: true`，還是使用者自己叫它停）之後，終端分頁
+  何時關閉、agent 進程是否還活著，你的網站依然無從得知（第 3.4 節「沒有
+  結束通知」的限制在這裡同樣成立）。
+- **不改變審批卡文案**——目前的審批卡（第 4 節）不會因為你的 MCP 有沒有
+  `kenaz_wait_for_message` 而顯示任何額外內容。
+
+---
+
+## 10. 未安裝流程：偵測 + 導向安裝頁（TASK_1950）
+
+第 4 節「請安裝 Kenaz 的偵測與 fallback」講的是**一般性**的逾時
+fallback——60 秒沒收到 `kenaz_hello` 就顯示一段安裝指引文字，而且刻意把
+「沒裝」「使用者拒絕審批」「使用者封鎖了你的網站」三種情況混在一起，因為
+網站真的分辨不出來（第 0 節「沒有回程通道」）。
+
+這一節加的是一個**更快、專門針對「可能沒裝」的獨立偵測層**，用途不是取
+代第 4 節的 60 秒一般性 fallback，而是在它之前先做一次快速判斷、**主動導
+覽**到安裝頁（不只是顯示一段文字），並把原始深連結透過 `return=` 帶過
+去，讓使用者裝完 Kenaz 之後不用再按一次「連接」。`@kenaz/connect` 這個
+SDK npm 套件本身**尚未實作**（C 期產出，見 §6「目前沒有一個『假
+Kenaz』npm 套件」段落同樣的分期狀態）——這一節記錄的是它的目標行為，
+`examples/minimal-site/` 用零依賴的原生 JS 先示範同一套邏輯，供現在就要
+接入的網站參考。
+
+### 流程圖
+
+```
+使用者按「連接」
+      │
+      ▼
+組深連結 kenaz://connect?...（第 2 節）→ 記下 startedAt
+      │
+      ▼
+window.location.href = 深連結（同一分頁導覽，OS 靜默失敗或開啟 Kenaz）
+      │
+      ▼
+開始輪詢自己後端的連線狀態（例如 GET /api/status/:token）──┐
+      │                                                    │
+      │ 每次輪詢檢查：                                        │ 每 1 秒
+      ▼                                                    │
+  已收到 kenaz_hello？──是──> 顯示「已連線」，結束                │
+      │否                                                   │
+      ▼                                                    │
+  now - startedAt >= NOT_INSTALLED_TIMEOUT_MS（預設 8 秒）？──否─┘
+      │是
+      ▼
+導覽到安裝頁：installUrl + "?return=" + encodeURIComponent(原始深連結)
+      │
+      ▼
+（使用者在安裝頁下載、安裝、Kenaz 完成 scheme 註冊）
+      │
+      ▼
+安裝頁重新觸發 return= 裡的那條深連結
+      │
+      ▼
+回到第 2 節的深連結流程（審批卡 → 終端分頁 → kenaz_hello）
+```
+
+### 逾時判定：8 秒預設，backend 沒收到 `kenaz_hello` 為準
+
+- **預設 8 秒**（`examples/minimal-site` 裡的 `NOT_INSTALLED_TIMEOUT_MS`，
+  可調——見下方「minimal-site 怎麼示範」）。比第 4 節的 60 秒短得多，因
+  為這裡的目的是快速把「大概率沒裝」的使用者送去安裝頁，不是給審批卡的
+  使用者充分反應時間。
+- **判定依據**：網站自己的後端在這個時間窗內有沒有收到 agent 呼叫
+  `kenaz_hello`（第 3.2 節）——輪詢自己後端的連線狀態端點，跟第 4 節同一
+  個機制，只是時間窗更短。
+- **瀏覽器 blur/visibilitychange 不是主要依據**：導覽到 `kenaz://` 這類
+  自訂 scheme 時，部分瀏覽器/OS 組合會短暫觸發分頁失焦（跳出「要不要用
+  Kenaz 開啟」的系統對話框，或 OS 真的切到 Kenaz 視窗），可以拿來當一個
+  **加速捷徑**（例如「分頁在 1 秒內重新拿到焦點」，八成是系統對話框被使
+  用者選了「取消」，可以提早判定沒裝）——但這個訊號在不同瀏覽器、不同
+  OS 上是否觸發、觸發時機都不一致，**不能當成唯一或主要判定依據**，`kenaz_hello`
+  逾時仍然是唯一可靠的來源。
+- **已知的取捨（未解決，如實記錄）**：8 秒對於「已經裝了 Kenaz，但使用
+  者還沒看到/還沒按審批卡」的使用者是會誤判的——審批卡跳出、使用者切
+  去讀別的視窗、8 秒內沒按「允許」，一樣會被導去安裝頁。這是這個設計故
+  意接受的假陽性，換取「真的沒裝」的使用者不用等到 60 秒才知道要去哪
+  裡。如果你的網站場景使用者反應通常較慢，把
+  `NOT_INSTALLED_TIMEOUT_MS`/`KENAZ_INSTALL_TIMEOUT_MS` 調大一些即可——這
+  就是它必須是可調參數、不能寫死的原因。
+
+### 安裝頁 URL 從哪裡來——這是一個可設定參數，不是臆造的路由
+
+**目前沒有已知的 `app.kenazai.com` 安裝頁路由**，本檔不臆造一個。查證
+`dashboard/scripts/publish-release.js` 得到的實際事實：
+
+- Kenaz 的正式安裝檔上傳到 Supabase Storage 的 `kenaz-release` bucket
+  （`publish-release.js` 第 19 行 `const BUCKET = 'kenaz-release'`）。
+- 下載 URL 形狀：
+  `{SUPABASE_URL}/storage/v1/object/public/kenaz-release/{version}/{encodeURIComponent(nsisZip檔名)}`
+  （第 113-115 行）。
+- `latest.json` 上傳到同一個 bucket 的根目錄（`{SUPABASE_URL}/storage/v1/
+  object/public/kenaz-release/latest.json`），內容形狀是
+  `{version, notes, pub_date, platforms: {"windows-x86_64": {url,
+  signature}}}`（第 117-127 行）——這是 Tauri updater 消費的格式，不是給
+  瀏覽器直接開的人類可讀安裝頁。
+- `SUPABASE_URL` 本身**不在本 repo 裡**（`publish-release.js` 從
+  gitignored 的 `.env.local` 讀取，第 21-35 行）——因此本檔**無法引用**
+  正式環境的實際 bucket URL，只能引用上面這個結構事實。
+
+**結論**：在 Kenaz 提供一個正式的人類可讀安裝頁之前，`installUrl` 是
+SDK/範例的一個**必填設定參數**，不是硬編碼常數：
+
+- `examples/minimal-site/server.js` 讀取環境變數 `KENAZ_INSTALL_URL`
+  （沒設時退回一個明顯是佔位符的預設值
+  `https://kenaz-install.example/placeholder`，`.example` TLD 保證不會意
+  外解析成真的網域），伺服器端把它注入 `public/index.html` 連接按鈕的
+  `data-install-url` 屬性。
+- 在 Kenaz 提供正式安裝頁之前，網站可以自行把這個參數指向：**(a)** 自
+  家的下載頁（自己寫「請安裝 Kenaz」+ 下載連結 + 裝完後手動再按一次「連
+  接」），或 **(b)** 一個會去讀 `latest.json`、解析出
+  `platforms['windows-x86_64'].url` 再自動觸發下載的輕量頁面。無論哪
+  種，`return=` 參數（下一節）都應該由網站自己的頁面在裝完之後負責重新
+  觸發，而不是假設 Kenaz 的安裝程式本身會處理 `return=`——目前的 NSIS 安
+  裝程式沒有讀取/處理任何啟動參數的已知邏輯（未在本任務驗證範圍內找到相
+  反證據，也未逐行查證安裝程式腳本；如果之後要做到「安裝完自動觸發
+  `return=`」，需要另外驗證/修改安裝程式，這不在本任務 scope 內）。
+
+### `return=`：帶原始深連結，以及一個目前沒有協定層數字保證的 TTL 風險
+
+`return=` 的值是**原始的 `kenaz://connect?...` 深連結**，整個字串經
+`URLSearchParams.set('return', deepLink)` 處理（等同
+`encodeURIComponent`，見 `examples/minimal-site/public/install-redirect.js`
+的 `buildInstallRedirectUrl()`）。
+
+**查證 TTL 數字的結果（更正一個容易望文生義的假設）**：`PROTOCOL.md` §2
+點 1 與本檔 §3.1 都只寫「TTL：建議短——這個 token 只需要活到這次終端分
+頁的 session 期間」，**沒有任何具體秒數**——Kenaz 完全不驗證、不落盤這個
+token（第 0 節「沒有回程通道」的同一個事實：Kenaz 只是原樣轉交），TTL
+純粹是網站自己的決定，協定層沒有規定任何數字。
+
+這對「未安裝流程」有一個實際後果：使用者從按下「連接」到裝完 Kenaz、
+`return=` 裡的深連結被重新觸發，中間可能經過**任意長**的時間（下載、安
+裝、可能還要重開機）——遠超過「一個終端分頁 session 的存續期間」這個一
+般性 TTL 假設所預期的量級。如果網站的 token 依照 §3.1 的一般建議設得很
+短，`return=` 重新觸發時很可能已經過期，導致裝完 Kenaz 後审批卡看起來
+正常跳出、agent 也啟動了，但呼叫 `kenaz_hello` 時網站的 bearer 驗證卻
+401——使用者會卡在「裝都裝了怎麼還是連不上」。
+
+**建議（本檔的建議，不是協定規定）**：網站在替「未安裝流程」產生 token
+時，要嘛（a）給這個特定用途的 token 一個明顯更寬容的 TTL（例如以「分
+鐘」而非「這一個 session」為單位），要嘛（b）更穩妥的做法——`return=`
+不要直接指向裸的 `kenaz://` 深連結，而是指回網站自己的一個頁面
+（例如 `https://your-site.example/connect?resume=1`），讓那個頁面重新
+執行第 1 節「步驟一：簽 token」+「步驟二：組深連結」重新簽發一個全新
+token，再導覽到新組出的深連結——這樣就完全不用假設任何 TTL 撐得過使用
+者離開網站的這段時間。`examples/minimal-site` 目前示範的是最直接的
+(a) 類做法的簡化版（沿用原深連結字面值），選 (b) 的網站需要自己加一個
+resume 路由，這不在本任務 scope 內、範例沒有實作。
+
+### minimal-site 怎麼示範
+
+`examples/minimal-site/public/install-redirect.js` 是這段邏輯的**純函
+數**實作（刻意抽成獨立檔案而不是塞進 `index.html` 的 inline script，因
+為同一份邏輯要同時被瀏覽器跟 `node --test` 匯入，見該檔案的檔頭註解）：
+
+- `hasInstallTimedOut({ startedAt, timeoutMs, now })`：逾時判定，`now`
+  可外部注入方便測試。
+- `buildInstallRedirectUrl(installUrl, deepLink)`：組出帶 `return=` 的安
+  裝頁 URL。
+- `resolveInstallRedirect({ connected, startedAt, timeoutMs, installUrl,
+  deepLink, now })`：單一決策入口——`connected` 為真或還沒逾時都回
+  `null`（`connected` 的檢查優先於逾時檢查，逾時後才收到的「已連線」回
+  應不應該還被導去安裝頁），逾時且未連線才回傳導向 URL。
+
+`public/index.html` 的連接按鈕透過 `data-install-url` /
+`data-not-installed-timeout-ms` 兩個屬性讀取設定（`server.js` 的
+`renderIndexHtml()` 從 `KENAZ_INSTALL_URL` / `KENAZ_INSTALL_TIMEOUT_MS`
+環境變數注入，見該檔案），輪詢迴圈每次都呼叫
+`resolveInstallRedirect()`，拿到非 `null` 就直接
+`window.location.href = redirectUrl` 導覽過去。
+
+`test/smoke.test.mjs` 用 200ms 的短逾時（而不是真的 8 秒）驗證這條路徑
+（TASK_1950 AC1）：
+
+- 逾時前呼叫 `resolveInstallRedirect` 必須回 `null`。
+- 逾時後（且 `connected: false`）必須回傳一個 URL，其 `return=` 參數解
+  碼後**等於原始深連結字串**。
+- 對照組：`connected: true` 時，就算已經遠遠超過逾時，也絕不能回傳導向
+  URL（`feedback_probe_needs_control_group` 這條記憶——沒有對照組的通過
+  證明不了邏輯是對的，只證明程式碼跑起來沒拋錯）。
+- 額外驗證 `GET /` 真的把設定值注入進 HTML、`GET /install-redirect.js`
+  把同一份模組當真的靜態檔案提供（不是另外複製一份給瀏覽器用）。
+
+跑法：
+
+```bash
+node --test dev/specs/agent-connect/examples/minimal-site/test/smoke.test.mjs
+```
+
+### 冷啟動：Windows 上的深連結能不能被剛啟動的 Kenaz 接住？
+
+這是本節最需要如實記錄的部分——**已修復（TASK_1953）：Kenaz 啟動時讀取
+`get_current` 補處理；待實機冷啟動驗證**，不是「已驗證可行」：
+
+1. `tauri-plugin-deep-link` 2.4.10（`Cargo.lock` 釘的版本）在**它自己的
+   plugin `.setup()` 階段**（`init_deep_link()`，套件原始碼
+   `src/lib.rs` 第 68-79 行）就會呼叫
+   `handle_cli_arguments(std::env::args())`（第 196-220 行）：Windows／
+   Linux 上，如果啟動參數只有一個且能解析成一個符合設定 scheme 的 URL，
+   會把它存進 `self.current`（供 `get_current()` 讀取）**並且**立刻
+   `self.app.emit("deep-link://new-url", vec![url])`。
+2. `on_open_url()`（同檔案第 514-524 行）的實作就是
+   `app.listen("deep-link://new-url", ...)`——一個標準的 Tauri event
+   listener，**不會**補送監聽之前就發生過的事件。
+3. Tauri 2.10.2 的 `Builder::build()`（`tauri` crate `src/app.rs` 第
+   2094 行起）會呼叫 `app.manager.initialize_plugins(handle)`（第 2286
+   行附近），這一步會跑過每個 plugin 自己的 `.setup()`——包含上面第 1 點
+   的 `handle_cli_arguments` 呼叫與事件 emit。這整個 `build()` 呼叫，發
+   生在 KenazAI 自己那個 app 層級的 `.setup(|app| {...})` 閉包（`lib.rs`
+   第 1331 行起）**執行之前**——後者是被 `src/app.rs` 裡另一個自由函式
+   `setup<R>()`（第 2371 行 `app.ran_setup = true`）呼叫的，而那個自由函
+   式是在 `App::run()` 的事件迴圈裡才觸發，時間點晚於 `build()`。
+4. KenazAI 自己的
+   `dashboard/src-tauri/src/features/agent_hub/mod.rs`
+   `install_deep_link_handler()`（第 111-139 行）是在上述第 3 點「較晚」
+   的那個 `.setup()` 閉包裡才呼叫（`lib.rs` 第 1400 行），而且**只**呼叫
+   `on_open_url()`——通篇 `dashboard/src-tauri/src/` 搜尋 `get_current()`
+   在 deep-link 這個 extension 上的呼叫，結果是**零筆**。
+
+四點合起來：**在 Windows 上，一個真正的「Kenaz 完全沒在跑，直接靠雙擊
+`kenaz://connect?...` 冷啟動」的情境下，`handle_cli_arguments` 在 plugin
+setup 階段 emit 的那個事件，此時還沒有任何 listener 訂閱它（`on_open_
+url` 要等到後面的 app-level `.setup()` 才註冊）——這個事件因此被靜靜地
+丟掉。這是 TASK_1950 查證當下（沒有任何地方呼叫 `get_current()`）的實際
+狀態，會導致不出審批卡、不出 toast、什麼都不會發生——跟「使用者根本沒
+看到任何反應」的現象一模一樣。
+
+**已修復（TASK_1953）**：`install_deep_link_handler()`
+（`dashboard/src-tauri/src/features/agent_hub/mod.rs`）在註冊完
+`on_open_url` 之後，補一次 `app.deep_link().get_current()`——若冷啟動時
+plugin setup 階段已經捕獲但尚未被任何 listener 處理的 URL 存在，會逐一
+餵進與 `on_open_url` 完全相同的 `handle_incoming_url()` 路徑（兩者共用
+同一個 `spawn_handle_url` helper，不重複解析邏輯）；`get_current()` 回
+`Err`/`None` 時只 `tracing::debug!` 靜默記錄，不影響啟動。已在執行時的
+第二次啟動（single-instance 轉發）走的是另一條路徑（見下段），不會與
+`get_current()` 重複處理同一個 URL。
+
+這個修復連同上面 1-4 點的查證，完全基於閱讀 `tauri-plugin-deep-link`
+2.4.10 與 `tauri` 2.10.2 的原始碼（本機 cargo registry cache）加上
+KenazAI 自己的原始碼——**尚未做過真的冷啟動實機測試**（TASK_1953 同樣
+在 worktree 中完成，worktree 規則禁止對正在跑的 live tauri dev 動任何
+東西，也不能啟動一個新的 Kenaz 行程）。單實例轉發（已在執行時的第二次
+啟動）走 `tauri-plugin-single-instance` 的 `deep-link` feature，
+TASK_1928 已實測正常，不受本次修復影響、也不在待驗證範圍內。
+
+**實機冷啟動驗證步驟**（待主線程或有桌面環境的人執行）：
+
+1. 完整關閉所有 Kenaz 行程（含 tray 常駐；dev 模式下也要停掉 `tauri
+   dev`，因為 dev 模式的 `register_all()` 會把 `kenaz://` 指到
+   `target/debug` 的 exe，需要重新啟動一次乾淨的行程來吃到冷啟動路徑）。
+2. 在瀏覽器網址列直接開啟一個合法的 `kenaz://connect?...` 深連結
+   （帶上 `origin`/`mcp`/`token`/`prompt` 等必要參數，見本檔第 2/3 節）。
+3. 預期：OS 拉起 Kenaz 主行程後，視窗前景顯示審批卡（而不是靜默無反應、
+   也不是網站端 `kenaz_hello` 逾時後被 TASK_1950 的未安裝流程誤判成
+   「未安裝」）。
+4. 按下「允許」後應正常走完 §0 心智模型的第 3-5 步（開終端分頁、agent
+   掛上網站的 MCP、網站收到 `kenaz_hello`）。
+
+**AC3 判定**：程式碼修復已完成並可 code review 驗證（見上），但「實機冷
+啟動時 OS 真的會如描述般拉起行程並吃到這條路徑」仍是**待驗證**——這裡
+誠實記錄為「已修復，待實機驗證」，不是「已驗證沒問題」。
+
+---
+
+## 參考
+
+- `./PROTOCOL.md`（v0.4，本檔每個行為的權威來源）
+- `./examples/minimal-site/`（可跑範例 + `node --test` 煙霧測試，含
+  `kenaz_wait_for_message` 信箱參考實作、§10「未安裝流程」的
+  `install-redirect.js` 參考實作）
+- `dev/KENAZ_AGENT_CONNECT_v1_SPEC.md`（規格總覽，含分期與已決定事項）
+- Kenaz 側實作（僅供對照，你不需要讀這些就能接入）：
+  `dashboard/src-tauri/src/features/agent_hub/{deep_link,mod,launch,permissions,approval}.rs`
+- 假 MCP（Kenaz 自己的 conformance 用，不是你要跑的東西）：
+  `dashboard/scripts/agent-hub-fake-mcp.mjs`
+- 安裝檔發布腳本（§10「安裝頁 URL 從哪裡來」的事實來源）：
+  `dashboard/scripts/publish-release.js`
+- deep-link 冷啟動查證（§10 最後一節）的原始碼來源：
+  `tauri-plugin-deep-link` 2.4.10（cargo registry cache）、`tauri` 2.10.2
+  `src/app.rs`