kenaz 0.3.21 → 0.3.23

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

@@ -1,915 +0,0 @@
-# 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`