PWA · Livewire 4 · v454

📘 不用刷新頁面，筆記就像 App 一樣跟手

核心理念：把 AI、搜尋與手勢放在同一條「超順滑動線」上——寫得快、找得到、滑一下就能換篇。下面用最少時間帶你認識各項核心操作與設計細節。

無感更新 Keep 式卡片 光點導引 AI 隨行
快速跳轉： 安裝· 首頁· 摘要與分享· 閱讀· 時間軸· 編輯· AI· 個人資料· 開發(安裝)
⚡

輸入即同步

列表、標籤與搜尋走 Livewire，少掉整頁轉圈；手指停在同一個殼裡，思緒不斷線。

🎯

找得到、看得見

多關鍵字、標籤塞進搜尋列；內文還有會呼吸的光點導引，長文也能一秒鎖定。

✨

手勢操作順暢

滑動換篇、雙擊進編輯、置頂與拖曳排序——常用動作集中在同一套介面中完成。

1

PWA 安裝與更新

Android

點擊「安裝」按鈕或 Chrome 選單中的「安裝應用程式」。

iOS (Safari)

點擊底部的分享按鈕 ，選擇「加入主畫面」。

主畫面圖示：為何 iPhone 與 Android 看起來不一樣？

  • Android 依 Web App Manifest 的圖示（含 maskable）裁成圓形等形狀，系統常會「放大填滿」，主體看起來較滿。
  • iPhone（Safari → 加入主畫面） 主要使用 apple-touch-icon，會把整張方形圖放進主畫面圓角方塊；若素材本身四周留白多，圖案會顯得比 Android「小」一圈。
  • 本站對僅供 iOS 主畫面的圖示另外做了放大後取中央裁切，縮小兩平台落差；請務必從 /app/notes 安裝以套用正確捷徑。若仍想微調體感，站方可調環境變數 NOTES_APPLE_TOUCH_ICON_SCALE（預設約 1.12；數值愈大主體愈滿，過大可能裁到邊角）。
立即開啟 PWA 介面

重要：請務必於 /app/notes 路徑下執行安裝，而非傳統 Web 版 (/notes)。

版本更新： 點擊頭像選單中的「更新App」可強制刷新 Service Worker 並更新至 v454。
2

首頁：高效檢索與響應式導覽

動態載入技術 (Livewire)

採用 Livewire 4 驅動，列表更新、搜尋與過濾皆為「無感更新」，無需重新整理網頁即可實時同步資料庫狀態。

全平台響應式設計

系統會自動偵測裝置寬度：寬螢幕 以 Keep 風格卡片網格自動多欄排列；窄螢幕 改為單欄堆疊，維持觸控友善的預覽與操作。

Keep List：卡片列表（示意）

首頁列表元件為 tables.keep-list，黃底卡片、標題、預覽摘錄、標籤與更新時間的配置如下（靜態示意，非即時資料）。

本週會議紀錄
整理 Q2 預算與人力配置，待決項目：外包報價…
工作 重要
3 小時前
買菜清單
牛奶、雞蛋、菠菜、豆腐…
生活
昨天
加密備忘
（已加密時不顯示預覽）
上週

橘色外框表示目前選取中的卡片（單擊選取；雙擊進入編輯）。

  • 極速置頂： 點卡片右上 （提示為「移至最頂」）。播放短動畫後，該筆會排到列表最前並寫入排序；成功時會提示「已移至最頂部」。（版面左欄／右欄會用不同淡出方向，僅為視覺效果。）
  • 拖拉排序： 按住 握把拖曳卡片即可調整順序並存回資料庫。當搜尋框有關鍵字或已套用標籤過濾時，為避免與篩選結果混淆，會暫停拖拉排序；清空搜尋與標籤後即可再次拖曳。
  • 載入更多： 列表採分段載入，滑到底會出現「載入更多…」自動銜接下一批項目。

雙擊進編輯 · 水波紋（互動示意）

首頁列表與真實 App 一致：單擊選取卡片；雙擊會在您點擊的位置出現藍色水波紋（實作為附加於 document.body、與正式版相同的圓形動畫），再進入編輯。請在下方卡片上雙擊（或行動裝置快速連點兩下）—漣漪會從觸點長出；此為手冊內嵌示意，不會真的開啟編輯頁。

示意：在卡片上雙擊
與 Keep List 相同的雙擊辨識間隔（約 250ms）。請在任意位置雙擊—漣漪中心會對準您的游標／指尖。
互動示意
手冊示意 · 非真實資料

桌面：雙擊；行動裝置：在卡片上快速連點兩下（約半秒內、位置相近）。

  • 內容頁：閱讀時雙擊標題、內文或圖片區即可直達編輯表單；Card-Tool 預設收合，因此不必先展開滑桿再找「修改」— 詳見 §4。

搜尋框與標籤 (Tag) 整合

可以哦 重要 待辦事項
搜尋...
  • 標籤融合： 選取的標籤會直接顯示於搜尋框內，節省縱向空間。
  • 繽紛色彩識別： 系統會為不同標籤 自動生成隨機顏色，透過高度色彩對比提升項目的視覺辨識度。
  • 橫向捲動： 當標籤過多時，搜尋框內部支援 橫向滑動，不會撐開介面。
  • 掃把按鈕 ： 位於搜尋框右側，點擊即可 一鍵清空 所有關鍵字與標籤過濾。
  • 智慧多關鍵字搜尋： 支援以 「空格」 區隔多個關鍵字，系統將精準過濾出同時符合所有條件的內容。
  • 筆記本 Icon ： 點擊左上角可進行列表硬重置，並重置捲動位置。
  • 雙擊項目： 觸發與 App 相同的水波紋後進入編輯（見上方「雙擊進編輯 · 水波紋」互動示意）。
  • Keep List 卡片： 極速置頂、拖拉排序與載入更多 — 版面與操作說明見上一區「Keep List：卡片列表（示意）」。
3

筆記本首頁標籤分享與 生成式AI 多內容摘要

AI 多內容摘要

當您選取某個標籤時，點擊底部工具列的 摘要 鈕，系統會將該標籤下最新的 20 篇筆記交給 AI 進行深度彙整。

  • 進階對話修正： 生成初始摘要後，您可以直接透過對話框輸入進一步的指示（如：「請重點標註日期」、「改用列表呈現」），AI 會即時進行二次微調。
  • 儲存為新筆記： 滿意內容後，點擊「儲存為筆記」，系統會自動建立一篇包含參考來源連結的新筆記，並自動置頂於列表最上方。
  • 智慧來源引用： 儲存的摘要底部會自動補上參考資料的連結（如：/content/2），確保資訊可溯源。

標籤專屬分享

點擊底部工具列的 鈕，可針對目前篩選的標籤產生專屬分享連結。

  • 快速傳遞： 連結會自動複製到剪貼簿，方便您快速分享給團隊成員。
  • 即時同步： 分享頁面的內容會隨著該標籤下的筆記更新而即時同步，不需重複產生連結。
提示： 執行摘要時，AI 會優先分析「文字內容」與「圖片描述」，讓跨筆記的資訊整合更加精準。
4

內容頁：Card-Tool 與 智慧高亮

🛠️ Card-Tool 工具組（預設隱藏）

閱讀筆記時，包含通知、書籤、加密、分享、歷史以及刪除／修改在內的整條 Card-Tool 操作列預設為收合，不會一直佔據標頭下方—畫面上主要只看見返回、標題與右上角的滑桿圖示等精簡元件。

需要進階操作時，請點右上角 滑桿圖示 （「展開或收合內容操作列」）才會拉出下方浮動工具列。

通知
書籤
加密
分享
歷史
設計理念：大熱區操作
為了提升行動端效率，「分享」與「歷史」按鈕保留文字標籤以擴大點擊範圍，確保單手操作大拇指也能輕鬆命中。
為何預設藏起來： 閱讀時以內容為主；若每次進頁都展開整條工具列，會擠壓版面也容易誤觸。雙擊進編輯（見下方）讓您在不必先展開 Card-Tool的情況下就能改筆記。
刪除與極速刪除： 預設點 Card-Tool 內的「刪除」會先跳出確認對話（例如「確定要刪除此文章嗎？」），避免誤刪。若您已確定要刪除，可先按住 Ctrl（Windows／Linux）或 ⌘ Command（Mac），再點「刪除」— 將不經詢問、直接刪除該筆並返回列表（請謹慎使用）。按住修飾鍵時，刪除鈕會出現心跳動畫提示目前為極速刪除模式。

下方為循環播放之視覺示意（動畫曲線與 App 內 delete-btn-heartbeat 一致）：

刪除 僅示意，無法點擊

光點導引視覺特效

當您在頁面內執行關鍵字查找時，系統會自動標註關鍵字：

「光點導引」
（實時視覺特效演示：呼吸背景 + 光點旋轉導引）
  • 動態導引： 關鍵字將以 光點導引動畫 進行視覺提示，讓您在長文中秒速定位。
  • 圖檔 OCR 支援： 若您的筆記包含圖片，系統會自動識別圖中文字並標註 導引框。

滑動換篇

向左/右滑動快速切換相鄰筆記。

雙擊編輯

核心：在閱讀畫面上對標題、內文或圖片區雙擊，即可直覺進入編輯表單— Card-Tool 預設收合時，您不必先點滑桿展開再找「修改」，省下展開工具列與對準按鈕的步驟。

若您已展開 Card-Tool，仍可依習慣按「修改」進編輯。雙擊時會有與 §2「互動示意」相同的水波紋；成功進入後，標題或內容區會再短暫套上心跳動畫提示。

底部工具列 (Toggle Bar)

截圖模式
滑動切換
光點導引
設計細節：滑動切換 vs. 拷備模式
由於 PWA 支援左右滑動換篇，當您需要 「選取並拷備 (Copy)」 內文時，建議將「滑動切換」關閉。此時系統會進入「拷備模式」，您的手指滑動動作將不再觸發換篇，讓您能專注且精準地選取並複製文字內容。
5

時間軸：點擊 Card-Tool 內的「歷史」開啟

請先點標頭右上角 滑桿 展開 Card-Tool（預設為收合），再於工具列中點 歷史，即可開啟該筆記的完整時間軸，追蹤所有版本變更：

圖示 變更類型 說明
AI 修改 AI 助理執行的格式微調。
AI 新增 由 AI 多模態輸入生成。
手動修改 一般編輯模式下的更新。
時間軸支援「差異對比 (Diff)」，可清楚查看每一版內容的增刪變化。
6

表單編輯：智慧輸入與返回微調

返回微調 (Silent Save)

返回
➔ 離開表單並存檔！！

當您在編輯筆記後點擊左上角 「返回」 鈕，系統會自動執行 Silent Save：儲存修改，但 「不會」 更新內容的時間。

智慧標籤管理

可以哦 新增標籤...
快選:
  • 動態新增與刪除： 直接輸入文字即可建立新標籤；點擊標籤上的 「x」 即可立即移除。
  • 智慧快選： 系統會根據您的使用習慣列出 「快選標籤」，一鍵即可完成分類，無需重複輸入。
  • 拖拉排序： 支援標籤間的拖拉移動，方便您調整分類的優先順序。
  • 極速截圖上傳： 支援直接使用 Cmd/Ctrl + V 貼上圖片，系統會自動處理上傳並插入編輯器。
  • AI 助理： 點擊表單內的 AI 按鈕，支援 PDF/圖片分析，執行多輪格式修正。
  • 智慧貼上： 攔截 MD/Excel 表格自動轉化為高品質 HTML 結構。
快速鍵：Cmd/Ctrl + S (儲存) | E (編輯) | B (返回) | V (貼上圖檔)
7

私人 AI 助理 (Beta)：您的隨身知識執事

Status: Beta - 此功能目前處於測試階段，將持續優化指令理解能力。

智能調校工具列

ollama:gemma4:26b
  • 模型切換： 支援選擇不同的 AI 模型，依據任務複雜度靈活調整。
  • 「快速」開關： 開啟後進入極速回應模式，略過模型生成直接觸發意圖工具。

這是一個結合了 多模態支援 與 即時工具 的對話介面：

多模態視覺理解 (Vision Support)

助理不僅能讀文字，更能「看」懂您的截圖與照片：

  • 圖片內容描述： 您可以問「這張圖在說什麼？」助理會精準描述圖中的場景、物件與關鍵訊息。
  • 影像資訊擷取： 支援從複雜的數據圖表中擷取重點，並直接轉化為筆記文字。

常用指令範例：

  • 新增筆記： 「幫我加一則筆記，內容是下午三點要開會」
  • 內容檢索： 「顯示最近三篇筆記」或 「幫我查關於『專案計畫』的內容」
  • 即時翻譯： 直接貼上外文並輸入 「翻中文」。
技術核心：AppAgent 的精雕細琢

AppAgent.php 擁有高達 7000+ 行 的深度邏輯：

  • 多模態融合： 統一處理圖像分析、OCR 檢索與意圖識別。
  • s2t 精準轉化： 內建 PHP intl 擴展驅動的簡繁轉換 (S to T)。
  • 意圖導向的 Agent 調度： 將生成式 AI 直接掛載於系統工具之上。
8

個人資料與書籤（Web Profile）

點選右上角頭像選單中的「個人資料」，即可進入 Web 版 Profile 頁（網址形如 /profile/{id}，{id} 為您的使用者編號）。

  • Passkey（建議必做）： 在 Profile 的 Passkey 分頁可綁定裝置金鑰。之後登入時，手機上常可直接以指紋、臉部辨識或系統內建驗證方式完成，免重複打密碼；實際可選驗證方式依裝置、瀏覽器與 OS 而異（亦可在桌機搭配安全金鑰或系統驗證）。
  • 大頭照： 於 Profile 左側資訊卡可使用拍照或相簿上傳／更換頭像。
  • 自介與檔頭： 可維護暱稱、職稱／頭銜與自我介紹等顯示資訊。
  • 書籤： 在 Profile 內可檢視與管理已加入書籤的筆記（例如我的書籤分頁及側欄統計連結），與 MCP／API 設定無關。
9

開發者專區：API 與 MCP 整合

什麼是 MCP Server？ MCP（Model Context Protocol，模型上下文協議）是一種開放標準，讓 AI 助理軟體（例如 Cursor、Claude、Grok）能透過協定與外部系統銜接。MCP Server 即該協議下的伺服端：可走本機 stdio（note-mcp-server）或雲端連接器（Streamable HTTP，note-mcp-cloud-server），並註冊多個「工具」（如下表）；助理呼叫工具時再轉成對您Notes API 的 HTTP 請求。它扮演助理與筆記站台之間的轉接器，可在不把整庫資料直接交給模型的前提下，進行列舉、讀寫筆記、看板與推播等操作。

  • API 支援： 透過個人 API Key 與 Notes API 連線，進行自動化連動。
  • MCP 整合： 以 MCP 掛載 Notes API，在外部助理內以標準工具呼叫後端——可實際讀寫筆記、看板與推播，而非僅將文字脈絡餵給模型。下表依現行 note-mcp-server／雲端連接器整理；標註「連接器」者為雲端專用（本機版無）。
誰來安裝？ MCP 需在您的裝置上設定啟動指令與環境變數（含 API 位址與金鑰），並涉及站台是否開放、個人授權與資安規範。請洽網站管理者確認是否提供、並取得安裝步驟、範例設定或正式支援管道。

情境示意：一句話如何進筆記

例如您在助理裡說：「說明如何修正，並加到我的筆記」——模型不會憑空「記住」，而是呼叫工具寫入後端；流程可簡化成四步（實際耗時依網路與模型而異，助理介面可能顯示「執行工具中」）。

MCP 工具一覽

工具名稱 說明
連線與區塊
note_info 回傳連線資訊（站台網址、版號、transport 等），確認目前連到哪台主機／協定。
block_list 列出可操作區塊（看板／筆記本等）。含 can_add、can_move_into、status_tag_options。一般區塊用此；真看板請優先 kanban_list。
筆記讀寫
list_notes 列出／搜尋個人筆記本（GET）。可傳 search、tag、分頁（預設每頁 10）。不含看板項目；看板請用 kanban_items。
read_note 依 c_id 讀取單筆（GET；可 c_id=last）。看板卡另回 status_tag、priority、assignee、subtasks[]、fk_c_id。
create_note 新增筆記（POST）。content 必填；可選 title、b_id、tags、status_tag、priority、fk_c_id。看板頂層必須帶狀態（status_tag 或 tags 含該看板狀態名）；未提供 API 會拒絕並請助理詢問使用者。
update_note 修改既有筆記（POST）。需 c_id；可改內容／標題；tags 整包覆寫、add_tags 追加。看板狀態／優先度／受託人請用 change_task，勿用 tags 整包改狀態。
move_note 搬移筆記至另一區塊（POST action=move）。需 c_id、to_b_id；移入看板時 status_tag 必填。
delete_note 刪除筆記（POST：c_id + action=delete）。
tag 依標籤名稱搜尋個人筆記本內容（與 list_notes(tag=…) 類似，非看板狀態篩選）。
看板
kanban_list 列出可操作看板（GET action=kanban_list）。回傳 b_id、column_status（狀態欄名稱，因看板而異）、status_tag_options、in_progress_columns。建立／查詢前必先讀狀態名，勿寫死「執行中」等字串。
kanban_items 列出看板項目（GET action=kanban_items）。必填 b_id；可依 status_tag（須為該看板 column_status 名稱）、status_group（in_progress／active／terminal）、mine、search 過濾。
add_subtask 在父任務下建立子任務（POST action=add_subtask）。寫入同一看板、設 fk_c_id；預設繼承父狀態、priority=Medium。
change_task 變更看板任務屬性（POST action=change_task）：status_tag／priority／assignee_user_id。改狀態請用此工具。
bind_subtask 將同看板未綁定項目設為子任務（POST action=bind_subtask：parent_c_id、child_c_id）。
unbind_subtask 解除子任務綁定（POST action=unbind_subtask：child_c_id → fk_c_id=0）。
圖片、推播、瞬時通道
upload_image 上傳圖片（multipart／base64），回傳永久 URL；再以 <img> 寫入 create_note／update_note。有圖才上傳、無圖省略。
upload_image_from_url 連接器 由遠端 URL 抓圖並上傳至筆記站（雲端連接器專用；避開沙盒無法讀本機檔）。
upload_image_inbox_begin／upload_image_inbox_status 連接器 雲端圖片上傳信箱：先 begin 取得上傳指示，再 status 查詢完成後的永久 URL。
send_push 發送 Web Push（POST action=push）。message 必填；可選 title、url、image。此為直接推播通道，不是建筆記。
put_tunnel 寫入「瞬時通道」暫存（POST action=put_tunnel；單槽覆寫）。text／image_base64／file_base64 擇一。
put_tunnel_inbox_begin／put_tunnel_inbox_status 連接器 雲端瞬時通道寫入信箱（大檔／沙盒場景）；流程同圖片 inbox。
read_tunnel 讀取瞬時通道（GET action=read_tunnel）。預設讀取後清空（consume=true）；無資料回 status=empty（HTTP 200）。

實際參數與錯誤碼以您站台之 Notes API 為準；完整 REST 說明可對 API 基底網址加上 /help 查閱。看板狀態名稱以各看板 column_status 為準，勿假設固定字串。

請先登入後開啟 MCP 設定（路徑 /app/notes/mcp/install）：預設連接器分頁可複製 Remote URL 與 NOTES_API_BASE；本機分頁可產生 curl／mcp.json 設定。

準備好體驗流暢的手勢與筆記流程了嗎？
從首頁 Keep 卡片到光點導引，建議實際操作以熟悉完整流程。
開啟 PWA 筆記