kenaz 0.3.22 → 0.3.23

package/core/dev/KENAZ_AGENT_CONNECT_v1_SPEC.md

@@ -1,139 +0,0 @@
-# Kenaz Agent Connect v1 — 規格草案
-
-- 狀態：草案 v0.4（2026-09-08 深夜；v0.3 之後用戶再收斂：**拿掉 relay**，接口 = 深連結 + 網站 MCP，見第 6 節 Q10）
-- **v0.4 的核心收斂**：三方接口只剩兩個東西 —— 一個 `kenaz://connect` 深連結格式、一份「網站 MCP 該長什麼樣」的最小約定。沒有 relay、沒有 WebSocket、沒有配對憑證交換。
-- 適用範圍：**限 Kenaz 自家生態系網站**，不對外公開推（用戶決定，見 Q6）
-- 前身：Agent Hub（TASK_1928 M1、TASK_1929 M2、TASK_1930、TASK_1931）與 FlowPix 側的 `bridge/CONTRACT.md`「Relay v1」
-- 進行中的相依：TASK_1932（Relay v1 合約對齊，A 期基線，已 merge）；TASK_1933 已取消；B 期 = TASK_1935
-
-## 0. 一句話
-
-**任何網站只要照 Kenaz 的 SDK 開發，就能用一個深連結在用戶本機喚醒 Kenaz、經用戶審批後開啟一個掛著該網站 MCP 的 Ansuz 會話；之後網站與 agent 之間的一切都走網站自己的 MCP。** FlowPix 是第一個實驗場域，不是標準的擁有者。
-
-三方接口（v0.4）：
-- **Web → Kenaz**：深連結 `kenaz://connect?site=&mcp=&token=[&prompt=]`。用戶按「連接」那一下就是 launch，沒有另外的 launch 訊息。
-- **Kenaz → Web**：沒有回程通道。網站靠 agent 呼叫它的 MCP 得知「連上了」（`kenaz_hello` 慣例工具，見 2.3），逾時未呼叫就顯示「請安裝 Kenaz」。
-- **Agent ↔ Web**：只透過網站的 MCP 工具，bearer = 深連結裡的一次性 token，由網站自己簽發與驗證。
-
-明確的非目標：這不是 OAuth、不是帳號系統、不做用戶身份聯邦。「透過 Kenaz 登入 agent」的意思是把網站和本機 agent 串起來，網站不需要知道用戶是誰。也不再有 relay：v0.3 之前 relay 存在的理由（雲端後端把 headless 工作推到用戶機器）已隨 generate_* 廢止；剩下的喚醒、憑證、狀態回報三個功能分別由深連結、網站 token、MCP 工具呼叫取代（Q10）。
-
-## 1. 現況盤點（2026-09-08，main dcc2f5529）
-
-| 面向 | 現況 | 對標準的意義 |
-|---|---|---|
-| 信任模型 | 一次配對、每動作審批、per-origin 憑證與四態權限（unauthorized／once／always／blocked），HUD 審批視窗 | **保留**，這是 wallet-connect 形狀，已 live 驗證 |
-| 連線方向 | Kenaz 對外撥 WSS，用戶機器不開 port，AI 憑證不出機器 | **保留**，是產品核心賣點 |
-| 執行 | 網站請求 → 依用戶 dispatch 設定選 claude／codex → 預配網站 MCP（bearer 走環境變數）→ headless RESULT_FILE 或 interactive terminal 分頁 | **收斂**：只留 interactive 分頁 + Ansuz 人格；headless／RESULT_FILE 廢止 |
-| 協定文件 | `bridge/CONTRACT.md` 在 FlowPix repo；Kenaz 的 protocol.rs 是跟隨者，欄位漂移靠雙方來回文件對帳 | **要翻轉**：標準住在 Kenaz |
-| relay | 每個網站自己跑（FlowPix `relay.mjs`）；token 由網站自己的 relay 簽發 | **要翻轉**：Kenaz 託管，網站註冊 |
-| 訊息型別 | `generate_image`、`generate_text`、`agent.launch` 三個硬編 enum 變體，欄位是 FlowPix 產品需求 | **要收斂**：只剩 agent.launch；generate_* 廢止（網站工具走 MCP） |
-| 網站端整合 | FlowPix 手寫 `RelaySiteClient`、深連結組字串、事件狀態機 | **要包裝成 SDK** |
-| 安裝 | 0.2.228／0.2.229 未簽章，Google Drive 判違規（TASK_1921 只清了內容） | **前置**：陌生網站的用戶要能安裝 |
-
-## 2. 四根柱子
-
-### 2.1 協定所有權與版本
-
-- 規格文件住在本 repo（本檔案演進為 `dev/specs/agent-connect/PROTOCOL.md`），FlowPix 的 CONTRACT.md「Relay v1」章節改為引用。
-- `pair.begin` 新增 `protocol_version: "1"`；relay 與 Kenaz 對不支援的版本回 `pair.denied {code:"protocol_unsupported"}`。沒有這個欄位，第二個網站出現時就無法演進。
-- conformance test suite 由 Kenaz 提供（JSON 範例 + 假 relay + 假網站），網站與 relay 實作都跑同一套。FlowPix 現有 `test_relay_contract.py` 的「三方一致」思路直接吸收。
-- 所有新增訊息型別必須先進規格再進 protocol.rs；protocol.rs 檔頭的「等待定稿契約」清單在 v1 凍結後刪除。
-
-### 2.2 網站身份與憑證（取代 relay 託管與註冊）
-
-- 沒有 relay 就沒有「relay 驗過的 origin」。審批卡顯示的是 **MCP URL 的 host**（agent 真正會連的對象）與 site origin（自稱），兩者都顯示，host 是主要識別。
-- 憑證：網站在深連結放一次性 `token`（綁定它自己的用戶 session、短 TTL），Kenaz 把它當 MCP 的 `Authorization: Bearer <token>` 帶給 agent（走環境變數，不落盤、不進命令列，沿用 M2 機制）；網站的 MCP 端點自己驗這個 token。發 token 與驗 token 是同一方，不需要第三方。
-- 網站註冊、site_key、託管 relay：**全部取消**（Q1／Q2 作廢）。生態系內網站只需要遵守深連結格式與 MCP 約定。
-- 自架 relay 的相容：無。v0.3 的 relay 路徑整段移除（TASK_1939）。
-
-### 2.3 協定：深連結 + 網站 MCP 約定（v0.4）
-
-**完整權威規格：`dev/specs/agent-connect/PROTOCOL.md`（v0.4，TASK_1939）** ——本節是摘要；深連結參數表、網站 MCP 最小約定、審批卡格式、廢止清單（v0.3 relay 全部訊息）以該檔為準，任何欄位有出入時以該檔更新。
-
-深連結：
-```
-kenaz://connect?site=<url-encoded origin>&mcp=<url-encoded https MCP url>&token=<one-time token>[&prompt=<url-encoded text>][&agent=claude|codex][&v=1]
-```
-| 參數 | 必填 | 說明 |
-|---|---|---|
-| site | 是 | 網站 origin（https；dev 模式允許 localhost／127.0.0.1／[::1] 的 http） |
-| mcp | 是 | 網站 MCP 端點（https；dev 模式同上）。審批卡以其 host 為主要識別 |
-| token | 是 | 一次性 bearer，≤512 字元；Kenaz 不解讀 |
-| prompt | 否 | 起始 prompt（URL 長度限制約 2 KB；長內容請放在 MCP 工具裡讓 agent 自己取） |
-| agent | 否 | 指定 CLI；省略依用戶 dispatch 設定 |
-| v | 否 | 協定版本，缺省 1；不支援的版本 Kenaz 顯示 toast 拒絕 |
-
-Kenaz 收到後：驗格式 → 審批卡（site、MCP host、agent/model、cwd=Dashboard 當前專案、prompt 前 120 字；一次／永遠允許／封鎖以 site origin 為單位）→ 允許則在 Dashboard 開終端分頁：用戶的 CLI + Ansuz 人格（session.js elixir 輸出，--no-muninn）+ 預配 `{mcpServers:{<name>:{type:"http",url:<mcp>,headers:{Authorization:"Bearer <token>"}}}}`，prompt 作為第一則使用者訊息。
-
-網站 MCP 最小約定（SDK 提供範本）：
-- 必須接受 `Authorization: Bearer <token>` 並驗證它是自己簽發、未過期、未撤銷。
-- 建議提供 `kenaz_hello` 工具（無參數，回 `{ok:true}`）：Ansuz 人格會在會話開始時呼叫一次，網站據此把 UI 從「已開啟 Kenaz」切到「已連線」；逾時（建議 60 秒）未收到即顯示安裝指引。
-- 其餘工具完全由網站定義；Kenaz 不列舉、不審核。會話結束沒有通知；網站以 token 撤銷或閒置逾時處理。
-
-廢止：pair.*、agent.status、agent.launch、approval.*（線上）、agent.launched／unavailable／exited、error、protocol_version（改為深連結 `v=`）、relay 全部角色、sites.json 的 session_credential／relay_url 欄位（origin 四態權限保留）。
-
-### 2.4 SDK
-
-**開發者接入指南：`dev/specs/agent-connect/SDK_GUIDE.md`（TASK_1940，2026-09-08）** ——10 分鐘接入、深連結/MCP 約定的讀者導向說明、審批 UX、開發模式、測試、toast 疑難排解對照表，加上可跑的零依賴範例 `dev/specs/agent-connect/examples/minimal-site/`（`node server.js` 三行指令起來，`node --test` 煙霧測試涵蓋 bearer 401 對照組）。這是本節設想的兩個套件正式打包前，網站開發者實際可用的接入路徑——下面兩個套件仍是規劃中，尚未實作：
-
-- `@kenaz/connect`（瀏覽器，未實作）：`isInstalled()`（深連結探測 + 逾時 fallback 到下載頁）、`buildConnectUrl({site, mcp, token, prompt?, agent?})`、`<KenazConnectButton>`、以及等待 `kenaz_hello` 的狀態機（由網站後端透過自己的通道回報給前端）。SDK_GUIDE.md 的範例目前用手寫的 `buildConnectUrl` + 輪詢達成同樣效果。
-- `@kenaz/connect-mcp`（Node，之後 Python，未實作）：網站 MCP 的骨架 —— bearer 驗證中介、`kenaz_hello` 工具、token 簽發／撤銷 helper。網站把自己的工具掛上去。SDK_GUIDE.md 的範例目前是手寫的最小 Node http 伺服器，示範同樣的約定。
-- 假 Kenaz（模擬「收到深連結 → 呼叫 kenaz_hello」）尚未隨 SDK 發佈；SDK_GUIDE.md §6 記錄了目前唯一已驗證可行的替代方案——直接用 curl／`node --test` 模擬 Kenaz 會發出的 MCP 呼叫。
-- 版本策略：SDK 主版本 = 深連結 `v`。
-
-
-## 3. Kenaz 側要動的地方（TASK_1939）
-
-| 區域 | 改動 |
-|---|---|
-| deep_link.rs | 參數改為 site／mcp／token／prompt?／agent?／v?；mcp 必填 |
-| relay_client.rs | **刪除** |
-| protocol.rs | **刪除**（沒有線上協定） |
-| launch.rs | 保留 interactive + Ansuz 人格 + MCP 預配；bearer 改為深連結 token；入口改為深連結 handler 直接呼叫 |
-| approval.rs／ApprovalCard | pairing 卡消失，只剩 launch 卡；顯示 site、MCP host、agent/model、cwd、prompt |
-| permissions.rs／sites.json | 去掉 session_credential／relay_url／mcp_url；保留 origin 四態 |
-| mod.rs | 深連結 handler：parse → approval → launch；拒絕 → toast |
-| 假 relay／conformance | 假 relay 與 site 角色刪除；conformance 改為「深連結 fixture + 假 MCP（含 kenaz_hello）」 |
-| http routes | /api/agent-hub/status 只回 origins 權限表 |
-
-
-## 4. 前置條件
-
-1. **程式碼簽章**：未簽章安裝包已被 Google Drive 判違規；生態系網站的用戶第一步就是安裝。需要 EV 或 OV 憑證 + 建置流程接入（`build:kenaz` 已有 Tauri 更新簽章，這是另一件事）。
-2. **訂閱條款**：**不查、不對外公開**（用戶決定 Q6，2026-09-08）。標準只在 Kenaz 自家生態系網站使用，條款風險由自家網站承擔。若日後要對外開放，此項重新打開。
-3. **跨平台深連結**：只在 Windows 驗過。macOS `CFBundleURLTypes` 由 bundler 產生但未測；Linux 未處理。
-
-## 5. 分期
-
-| 期 | 內容 | 出口條件 |
-|---|---|---|
-| A（完成） | Relay v1 對齊（TASK_1932）作為 FlowPix 基線；v0.3 硬切（TASK_1936／1937／1938）已 merge，live 驗到 agent.launched | 歷史 |
-| B | TASK_1939：移除 relay，深連結 + 網站 MCP；PROTOCOL.md 改寫；conformance 改為深連結 + 假 MCP | 從瀏覽器點一次深連結 → 審批 → 終端分頁 Ansuz banner → 假 MCP 收到 kenaz_hello |
-| C | SDK 兩個套件 + 假 Kenaz + 文件 | **app.kenazai.com**（Q5）用 SDK 接通，零人工對帳 |
-| D | 簽章、macOS 深連結 | 生態系內所有網站可用；不對外公開 |
-
-
-## 6. 已決定事項（用戶，2026-09-08）
-
-| # | 問題 | 決定 | 影響 |
-|---|---|---|---|
-| Q1 | 託管 relay 落點 | **獨立 service**（agent-connect-relay），可同台 VM | C 期新 binary；不改 yggdrasil-relay |
-| Q2 | 網站註冊 | **先人工發 site_key** | relay 設定檔；不做自助頁 |
-| Q3 | capability 命名空間 | **開放網站自訂**（`<site>.<name>`） | 配對宣告帶 description／requires_mcp；通用執行模板；審批卡標示網站提供的說明為不受信任文字 |
-| Q4 | 舊型別 adapter | **不做，B 期硬切** | FlowPix 同步改送 envelope；`protocol_version` 讓錯配明確失敗 |
-| Q5 | 第二個實驗場域 | **app.kenazai.com** | D 期 SDK 第一個真實用戶 |
-| Q6 | 訂閱條款查證 | **不查，只限自家生態系** | 第 4 節第 2 項關閉；E 期不含對外公開 |
-| Q7 | 「開啟 Ansuz」的形式 | **Interactive 終端分頁 + Ansuz 人格 + 網站 MCP** | 無 headless；generate_*／result／presign 廢止；capability 概念移除（Q3 作廢） |
-| Q8 | agent 的 cwd | **Dashboard 當前專案** | 審批卡必須顯示 cwd；網站不可指定 |
-| Q9 | 1932／1933 | **1932 照 merge，1933 取消** | FlowPix A 期不中斷；presign 不再需要 |
-| Q10 | relay 要不要拿掉 | **拿掉**（2026-09-08 晚） | 接口 = 深連結 + 網站 MCP；Q1／Q2（託管 relay、site_key）作廢；1936／1938 的 relay 對齊成為廢碼；TASK_1939 |
-
-Ansuz 的保留意見（記錄，不阻擋）：Q6 不查條款表示第三方訂閱 CLI 被網站驅動的合規性未被驗證，生態系內網站要自行承擔。Q3 的疑慮因 Q7 移除 capability 概念而消失。Q8 讓網站 prompt 驅動的 agent 在用戶專案裡有寫入能力，靠審批卡顯示 cwd 與每次審批把關。
-
-B 期實作卡：TASK_1939（移除 relay）。TASK_1935 父卡的 v0.3 子卡 1936／1937／1938 已 merge，屬 A 期收尾。
-
-## 7. 與現有工作的關係
-
-- TASK_1932／1933 不受影響，照 Relay v1 做完；它們是 A 期。
-- 1933 之後不再新增 FlowPix 專屬訊息型別；任何新需求先進本規格的 capability 清單。
-- FlowPix 的需求文件、CONTRACT.md、參考實作與 Kenaz 的回覆文件（共 10 份）作為 v1 的歷史來源歸檔在 `dev/specs/agent-connect/history/`（B 期已做，TASK_1938）。