先說結論： 就這一個月的觀察下來，把網站弄成「AI 友善」，最老派的方法反而最實在。

一個月前，我把這個部落格的 agent-ready（AI 準備度）分數從 8 分刷到了 58 分。當時憑直覺做了一些設定，現在累積了 4,000 多筆數據，剛好可以回頭驗證。結果發現：當初弄得最花俏、拿最高分的那些設定，其實都只有「打分數的掃描器」在看；而我自認最得意的「專屬乾淨格式」採用率只有 2%。真正把 AI 流量帶進來的，反而是最傳統的 robots.txt 網站宣告。

打開儀表板：社群流量還是把 AI 壓著打 ​

原本隱約覺得 AI 流量會噴發出一大塊。

結果打開數據一看，有點意外，最大宗的還是大家在 FB 或 LINE 貼網址時，系統自動來抓「預覽圖與摘要」的社群流量，佔了將近一半（48%）。

我把 AI 機器人分成三類：「為了回答網友問題來查資料的」（像 ChatGPT）、「到處抓文章回去當訓練材料的」（像 GPTBot），以及「單純來打分數的掃描器」。這三類加起來只佔了 22%，比想像中少，而且幾乎都是 ChatGPT 跟 Perplexity 帶來的。

第一個校正： AI 流量確實起來了，但傳統的社群分享本來就是這個 blog 的命脈，AI 流量還沒大到能把它壓過去。

well-known 的 666 次請求看起來最熱鬧，拆開全是同一個東西 ​

看數據時發現，/.well-known（一個專門放 AI 說明書的隱藏路徑）被打了 666 次，當下想說「哇，這麼受歡迎？」

結果攤開一看： 全都是「評分掃描器」跟「Chrome 瀏覽器的預載功能」在自嗨。真正的 AI（像 ChatGPT）根本沒來戳過這裡。

更好笑的是，後台留了 600 多次「找不到網頁 (404)」的錯誤紀錄。原來是掃描器瘋狂在問我當初故意不做的那些「拿高分專用端點」。這證明了原文裡的決定是對的：千萬不要光看「請求次數」就以為有市場需求，跑去硬寫那些功能，真的會被掃描器騙去白忙一場。

那個我最得意的改造，採用率 2% ​

這段真的是自己打臉。

上次改造中，我最得意的就是「Markdown 內容協商」，也就是說，只要 AI 告訴我「我想看乾淨的文字 (Markdown)」，我就直接給它，幫它省去解讀複雜網頁標籤 (HTML) 的麻煩。

結果這 28 天下來： AI 總共來了 500 多次，只有 10 次主動要求這個乾淨格式，採用率慘不忍睹的只有 2%。而唯一 100% 捧場用這功能的，笑死，全都是我自己拿工具在手動測試的紀錄。

技術上這機制設計得很漂亮，但現實是：現在的主流 LLM 早就習慣硬啃 HTML 了，它們根本不會主動要求乾淨格式。當初覺得「架構乾淨＝會被大量採用」，實在跳太快了。當成一個長線投資可以，但當下它就是只有 2% 的採用率。

5/8 那天到底發生什麼事 ​

平常每天流量大概 100 多次，5/8 那天突然衝到快 300 次。那天我也沒發新文章，第一反應是「哪個爬蟲壞掉了？」。

拆開 Log 一看，原來是 Perplexity、GPTBot 這些大廠的爬蟲，終於把這個 blog 排進了「定期巡邏名單」，連兩三年前的老文章都被它們翻出來重新看過一輪。

順便發現的雷達： 做完這些設定後，大概要等個「一到兩週」，大廠的生態系才會真正把你掃進去。太早看數據沒什麼意義，因為大環境還沒認識你。

原本寫最短的那條，反而帶量最大 ​

上次文章裡我只簡單帶過 robots.txt（傳統的爬蟲規則）的設定，覺得最沒梗，結果把資料攤開看，它才是真正的大魔王。

bot_article 3,557 個事件佔全部 83%。真正帶 bot 流量的就是這層：bot 透過正常爬蟲管道進來抓 HTML 文章頁。

當初設定 robots.txt 時，我用 Content Signals 標了偏好：可以即時回答網友（ai-input=yes），但別當訓練資料（ai-train=no）。從數據看，AI 真的有在尊重這個宣告，被引用去回答問題的次數是當訓練資料的 2.2 倍（單看上一篇甚至到 5:1）。

這點直接改變了我的寫作策略：以後寫技術文，與其寫落落長的長文去拚 Google 搜尋，不如把每個段落的「結論」寫清楚，讓 AI 好摘錄。一篇文章被 ChatGPT 抓 30 次去回答網友，那種感覺跟單純被 Google 索引是完全不同的，它是真正意義上的「被即時引用」。

Is It Agent Ready? 真的 Ready 嗎 ​

測驗工具給了我 58 分，看起來是 Ready 了。但看完這 28 天的數據，我會這樣解讀：

真正帶來 83% 流量的，是最傳統的 robots.txt 宣告，因為所有 AI 本來就懂這套老規矩。 而讓我從 8 分衝到 58 分的那些「進階 AI 改造」，真實 AI 的使用率幾乎是零。

這個分數，量測的其實是「對掃描器的友善度」；至於「AI 真的會怎麼用你的站」，它根本量不到。基礎建設我們已經鋪好了，但那些進階的玩法，目前只能等整個 AI 生態系慢慢跟上。也許半年後再回來看，那 2% 的採用率才會開始往上爬吧。

AI Agent 時代的前端開發，正在從 UX（User Experience）延伸到 AX（Agent Experience），也就是把網站同時設計給人類跟 AI agent 使用。對 Vue 開發者來說，這代表 component、store、route 跟 tool 之間的關係要重新整理一輪。WebMCP 這類規格只是入口；核心變化是前端工程師的工作範圍會擴大，以前歸在後端 API doc 範圍的 tool 命名、description 文案、權限邊界，正在往瀏覽器這一端推。

幾天前我寫了一篇〈讓網站直接跟 AI Agent 對話：初試 WebMCP〉，聚焦在規格本身、navigator.modelContext 怎麼用、demo 怎麼跑，想了解 WebMCP 細節的話建議先看那篇。寫完之後我意識到還有一塊沒寫：身為一個寫了多年 Vue 的前端開發者，我自己面對這波浪潮時在想什麼？Vue 的哪些結構特性剛好對得上 AX、哪些反而會變成負擔？這篇就是回答這個問題的個人筆記。

從 UX 到 AX：AI Agent 時代的響應式設計 ​

打開這個話題，日本工程師 takoratta 在一篇文章裡把 AX 類比成「AI 時代的響應式設計」，這個比喻蠻有意思的，我讀完之後覺得確實是這樣。

回想一下 web 過去三十年的兩次大轉折。90 年代末瀏覽器戰爭打完，W3C 把 HTML / CSS / JS 標準收束起來，讓網站不用為每個瀏覽器寫一份程式碼。 2010 年前後智慧型手機普及，新的用戶端類型（行動裝置）冒出來，網站得學會同時服務不同螢幕尺寸的訪客，Responsive Web Design（RWD）變成共識。 2026 年的此刻，新的用戶端又出現了：AI agent。它沒有眼睛、不看畫面、不點按鈕，讀的是結構化的 tool schema 跟自然語言描述。 網站得再學一次「同時服務多種前提的訪客」，這次的差異在於「人類視覺 vs 結構化 tool call」。

不過這個類比也有邊界。RWD 處理的是呈現層配接，「換個 viewport 看到合適版本」就完事；AX 處理的是能力暴露跟操作邊界，「agent 能呼叫什麼、傳什麼、後果是什麼」。所以 AX 的安全性、權限模型、稽核這些東西會比 RWD 更核心，光把 RWD 經驗搬過來不夠用。

換個角度看，網站的訪客正在分化成三種：人類、傳統 crawler（搜尋引擎、AI 訓練爬蟲）、即時操作的 agent。前兩種都還是「讀」資訊，差別只在誰來消化；第三種是「操作」資訊，讀完之後會直接呼叫 tool 改變狀態。AX 真正想處理的是這第三種訪客，他們對網站的期待已經超過「給我可讀的 HTML」這層，需要的是一份可呼叫的能力清單。

這就是 AX 想處理的問題。

AX 是什麼 ​

AX 是 Agent Experience 的縮寫，由 Netlify 共同創辦人 Matt Biilmann 提出，agentexperience.ax 上有官方定義：「AI agent 在跟產品、平台或系統互動時得到的整體體驗」。它跟 UX（User Experience）、DX（Developer Experience）是同一個概念家族，差別只在受眾從人類使用者、開發者擴大到了 agent。

套到網站場景，AX 講的是當 agent（語言模型、瀏覽器內建的 AI、自動化腳本）成為訪客時，我們為這類非人類用戶端設計的操作體驗。過去網站的預設訪客只有一種，有眼睛、會操作滑鼠跟觸控的人類，所有資訊都塞在渲染完的視覺層；agent 想介入只能靠截圖猜按鈕位置或爬 DOM 反推語意，品質一直很差。WebMCP 跟 NLWeb 這類規格冒出來，等於是讓網站第一次能對 agent 說「這頁有哪些操作、輸入是什麼、後果是什麼」。AX 在描述的就是這種對話品質。

要先 caveat 一下，這篇主要從 WebMCP 角度切入 AX，但 AX 本身是更廣的概念，跟 NLWeb、Browser Agent、未來的其他 agent-facing API 都有交集。WebMCP 只是目前最具體可動手的一條路徑。

跟 UX 對照看比較容易抓到邊界。UX 想的是視覺層級、互動回饋、頁面節奏這類人眼在意的事；AX 想的是 tool 命名要不要白話、description 文案夠不夠精準讓 LLM 一次選對、錯誤訊息有沒有告訴 agent「為什麼錯、要怎麼修」、哪些動作要強制人類二次確認。失敗模式也不一樣，UX 失敗是使用者點不到、找不到；AX 失敗是 agent 選錯工具、塞錯參數、無腦重試把 server 打掛。

AX 跟 SEO / a11y / semantic HTML 的關係 ​

AX 容易被混進現有的 SEO、accessibility、semantic HTML 這幾條既有討論裡。我自己一開始也想過「這不就是 a11y 換個名詞嗎」，後來想清楚三者其實在處理不同層面的問題。SEO 處理「內容能不能被搜尋引擎理解、進 index、出現在搜尋結果」；accessibility 處理「人類使用者（特別是有輔助科技需求的）能不能順利操作網站」；AX 處理「agent 能不能搞清楚這個網站允許我做哪些事、要丟什麼參數、做了會發生什麼後果」。

三者會共享一些基礎，例如語意化 HTML、清楚的狀態、穩定的資訊結構。但 AX 多出一層 capability design：網站除了被讀，還可以被呼叫。這層是 SEO 跟 a11y 都沒在處理的。

AX 把哪些工作推到前端 ​

AX 對前端工程師最直接的影響，是工作邊界正在重畫。

過去前端跟後端有一條相對清楚的分工線：後端負責 API 設計、命名、文案、權限模型；前端負責把資料拿來渲染、處理互動。tool 命名好不好、description 文案精不精確、權限邊界畫在哪，這些是 API doc 的事，前端讀文件來用就好。

WebMCP 把這條線往前端拉了。至少從目前 draft API 的形態來看，tool 註冊發生在瀏覽器，跟著 component 生命週期走，跟 UI 文案共用同一份 i18n，輸入 schema 通常借用前端已有的 form validation library（Zod、VeeValidate）。換句話說，以前你寫一份 API spec 給後端，他幫你做一支 endpoint 出來；現在你直接在 Vue component 裡 registerTool，description 文案就是你寫，輸入 schema 就是你的 form schema，errors 訊息就是你 UI 顯示的那份。

工作量轉移之外，連帶把幾個過去看似後端責任的東西，實質變成前端設計問題：

Tool 命名跟 description 文案 LLM 選工具靠的就是這兩個欄位，寫得好可以一次選對，寫不好就會誤呼叫或無腦重試。這是寫作問題，需要思考的是：讀者（模型）在什麼情境會看到這段文字、它需要什麼資訊才能做正確判斷。前端工程師寫 UX 文案累積的肌肉記憶其實很接近，只是受眾換了。

權限邊界 哪些 tool 可以給 agent 自由呼叫、哪些必須走 requestUserInteraction、哪些角色才看得到、跨頁的時候要不要回收，這些以前是後端 authorization 在管的事，現在會散落在 component 跟 store 裡。Vue 開發者過去靠 router guard 跟 provide/inject 處理 UI 層權限，同一套機制現在要延伸到 tool 層。

錯誤訊息的 agent 版本 給人類看的錯誤訊息可以是「請稍後再試」，給 agent 看必須是結構化、可動作的：為什麼錯、缺什麼參數、要怎麼修、能不能重試。前端要學會同一個錯誤寫兩份文案，一份給人、一份給 agent。

UI 跟 tool definition 的 drift 問題 ​

這幾個工作推到前端之後，會浮現一個維運核心問題：UI 跟 tool definition 各改各的。

我自己第一次體會到嚴重性，是試著把 demo 裡的搜尋欄位改了一個欄位名，UI 沒事（因為是表單渲染），但對應的 search_products tool 的 inputSchema 我忘了改，agent 還在用舊欄位名呼叫。Browser 端不會報錯，只回 200 加空陣列，模型以為「沒搜到」就再試一次，變成失敗迴圈。

這種 drift 在純後端 API 時代不太發生，因為 API 跟 UI 之間有 contract，改 API 一定要改 client，IDE 會跳紅字。但 WebMCP 的 tool 定義跟 UI 都在前端，沒有編譯時期的強制連動，改 UI 忘記改 tool 是最容易發生的事。

這是 AX 帶給前端工程師最具體的維運債，也是接下來看 Vue 結構優勢的時候，最值得拿來檢驗各種設計選擇的標準：這個寫法會讓 drift 變嚴重，還是減輕？

為什麼我認為 Vue.js 適合 AX？ ​

走完 AX 的概念框架，接下來想拉回到具體技術棧上。我自己寫了多年 Vue，在實際試做 WebMCP demo 的時候，有幾個瞬間意識到一件事：AX 場景需要的東西，Vue 的 mental model 早就準備好了。以下整理五個契合點。

Reactivity 跟 tool 狀態天生匹配 ​

WebMCP 最核心的循環是：agent 觀察狀態 → 呼叫 tool → 觀察狀態變化。Vue 的 reactivity 系統把這件事做到極致，tool 內部改一個 ref 或 store，UI 自動 re-render，agent 下一次讀畫面就看到新狀態。

我自己寫 React 寫到類似場景時，常會在 hook dependency、closure freshness、memoization 邊界這些地方多花力氣；Vue 的 ref / computed / store 模型比較貼近「狀態變了，UI 跟 agent 的觀察結果會一起更新」這種直覺，這層在 Vue 幾乎零成本。對 AX 場景特別重要，因為 agent 每次呼叫 tool 預期的是「執行完狀態就該變」，如果中間有同步問題，agent 會以為操作失敗去重試。

Pinia action 是 tool wrapper 的好入口 ​

Vue.js 開發生態圈的 Pinia action 在形狀上很接近一個 tool：具名、集中副作用、可回傳結果。 把現有的 store action 用 registerTool 包一層，agent 立刻就能呼叫，而且因為 action 本來就是 component 在用的，等於人類使用者跟 agent 共用同一份業務邏輯，不會分裂。

一個 Pinia action 要真的變成 production-ready 的 tool，我自己評估至少要補五件事：

• runtime input schema（Zod 或 valibot，光靠 TypeScript 型別不夠，因為 agent 傳的是 JSON）
• agent-readable description（寫給 LLM 看的自然語言文案，跟給 IDE intellisense 看的 JSDoc 是兩回事）
• 權限檢查（這個 action 該不該開放給 agent、目前角色能不能用）
• agent-friendly 錯誤語意（回傳結構化原因，不只是 throw）
• audit log（這次呼叫是 agent 還是人類觸發、傳了什麼參數）

寫一個 defineMcpTool() helper 從 store 自動註冊只是起點，真正的工作量在補上面這五件事。 但起點接近終點這件事仍是 Vue 的優勢，React 那邊把分散在 reducer / hook / context 的副作用收斂成 tool 起手式更遠。

Composition API 生命週期 = tool scope ​

onMounted 註冊、onBeforeUnmount 取消註冊，這個 pattern 把 tool 的可用範圍跟 component 生命週期綁在一起，做出來的效果是：agent 看到的工具集會跟著使用者導航自然變化。

舉個例子，結帳頁才出現的 applyCoupon tool，在使用者離開結帳頁的瞬間就消失。對 LLM 而言這是大幅降噪，看到 5 個情境相關 tool 比看到 50 個全站 tool 選擇品質好太多。Composition API 的 setup 函式天然就是執行這種註冊邏輯的地方，寫起來像呼吸一樣自然。

SFC 讓 tool 定義跟 UI 住在一起，抑制 drift ​

回到上一節說的 drift 問題。SFC 是 Vue 對抗這個問題的天然優勢：tool 定義可以寫在控制它的 component 旁邊，改 UI 的時候很難不看到 tool 定義也得改。

對比一下集中註冊 pattern：有的設計是把所有 tool 集中在一個 tools.ts 或 mcp-server.ts 裡定義，改 UI 的人根本不會開啟那個檔案，drift 機率最大化。SFC 把兩者放在同一個檔案的兩個 <script> 段，physical proximity 帶來的 cognitive coupling 是零成本的維運債抵抗力。

這當然不是銀彈，跨頁流程的 tool 還是得放 store 或全域 composable，不能塞 component。但對「這頁能做的事」這類常見場景，SFC 結構是最佳解。

vue-router 的 meta + Pinia 補完權限與 context ​

最後一塊是路由跟 context。WebMCP tool 常常需要知道目前的登入狀態、feature flag、使用者角色，如果每個 tool 自己拉這些資訊會很重。

Vue 的標準作法裡，這類共享 context 通常已經住在 Pinia store（useAuthStore、useFeatureFlagStore），useMcpTool 直接 import 過來用即可。vue-router 則補上「路由級」這層：用 route.meta.requiresAdmin 標註權限門檻，讓 tool 註冊邏輯讀 meta 決定要不要曝露 tool 給 agent。

具體配合方式長這樣。先在 vue-router 的 routes 定義裡標權限：

// router/routes.ts
import type { RouteRecordRaw } from 'vue-router'

export const routes: RouteRecordRaw[] = [
  {
    path: '/admin/users',
    component: () => import('@/views/admin/UserList.vue'),
    meta: { requiresAdmin: true }
  }
  // 其他路由 ...
]

接著在 admin 頁面 component 的 <script setup lang="ts"> 內，讀 route.meta 跟 Pinia auth store 一起判斷，條件不符就乾脆不呼叫 useMcpTool，agent 自然看不到這個 tool：

// components/admin/UserActions.vue 的 <script setup lang="ts"> 內容
import { useRoute } from 'vue-router'
import { useAuthStore } from '@/stores/auth'
import { useMcpTool } from '@/composables/useMcpTool'

const route = useRoute()
const auth = useAuthStore()

// 雙重檢查：路由標 requiresAdmin + 當前角色是 admin
if (route.meta.requiresAdmin && auth.role === 'admin') {
  useMcpTool({
    name: 'delete_user',
    description: '刪除指定使用者帳號（永久動作，僅 admin 可呼叫）',
    inputSchema: {
      type: 'object',
      properties: {
        userId: { type: 'string', description: '要刪除的使用者 ID' }
      },
      required: ['userId']
    },
    async execute(input: { userId: string }) {
      const res = await fetch(`/api/admin/users/${input.userId}`, {
        method: 'DELETE'
      })
      return {
        content: [{ type: 'text', text: JSON.stringify(await res.json()) }]
      }
    }
  })
}

整套機制都在 Vue 既有 mental model 之內，不用引入額外的依賴注入機制。Server 端當然還要再驗一次權限，client-side 條件式註冊只是降低 tool 暴露面，不能當成最終守線。

Vue 開發者的最小切入點 ​

理論講完，實作上我自己會建議的最小切入路徑長這樣。

第一步：從 read-only tool 開始 ​

不要一開始就把寫入類 tool 開出來。先選 3 到 5 個 read-only 的查詢類 action（搜尋、篩選、看詳情、看清單），包成 tool 觀察 agent 行為。這個階段的目標只有兩個：

• 觀察 LLM 怎麼選擇你的 tool：description 寫得夠不夠精準？常常選錯的話文案要怎麼改？
• 觀察 agent 的呼叫頻率跟錯誤模式：會不會無腦重試？errors 訊息夠不夠 agent 友善？

跑兩三天之後再決定要不要開寫入類 tool。這比一次全開安全很多，也讓你有時間建立 audit log 跟監控。

第二步：Pinia action 包成 tool 的範本 ​

我自己用的範本大概長這樣（假設用 Pinia + Zod，比舊文 demo 多了 store 整合跟 schema 重用）：

先在 stores/products.ts 集中業務邏輯：

// stores/products.ts
import { defineStore } from 'pinia'
import { ref } from 'vue'

interface Product { id: string; name: string; price: number }

export const useProductStore = defineStore('products', () => {
  const items = ref<Product[]>([])

  async function searchProducts(input: { query: string; maxPrice?: number }) {
    const params = new URLSearchParams()
    params.set('query', input.query)
    if (input.maxPrice !== undefined) params.set('maxPrice', String(input.maxPrice))
    const res = await fetch('/api/search?' + params.toString())
    items.value = await res.json()
    return items.value
  }

  return { items, searchProducts }
})

接著抽一個極薄的 composable 處理 WebMCP 註冊與生命週期：

// composables/useMcpTool.ts
import { onMounted } from 'vue'

type McpToolDefinition = {
  name: string
  description: string
  inputSchema: unknown
  annotations?: Record<string, unknown>
  execute: (input: unknown) => Promise<{
    content: Array<{ type: 'text'; text: string }>
  }>
}

export function useMcpTool(definition: McpToolDefinition) {
  onMounted(() => {
    if (typeof navigator === 'undefined') return
    if (!('modelContext' in navigator)) return
    ;(navigator as any).modelContext.registerTool(definition)
  })
  // 規格目前還沒明確的 unregister API，現階段先把註冊綁在 component lifecycle 上，真正的 dispose 等規格補完再接
}

最後在 component 的 <script setup lang="ts"> 內把 store action 包成 tool，schema 重用同一份 Zod 定義：

// components/ProductSearch.vue 的 <script setup lang="ts"> 內容
import { z } from 'zod'
import { zodToJsonSchema } from 'zod-to-json-schema'
import { useMcpTool } from '@/composables/useMcpTool'
import { useProductStore } from '@/stores/products'

const store = useProductStore()

const searchInputSchema = z.object({
  query: z.string().describe('搜尋關鍵字'),
  maxPrice: z.number().optional().describe('價格上限，單位 TWD')
})

useMcpTool({
  name: 'search_products',
  description: '搜尋咖啡豆商品。支援關鍵字、價格上限過濾。回傳符合條件的商品列表。',
  inputSchema: zodToJsonSchema(searchInputSchema),
  annotations: { readOnlyHint: true },
  async execute(input: unknown) {
    const parsed = searchInputSchema.parse(input)
    const result = await store.searchProducts(parsed)
    return { content: [{ type: 'text', text: JSON.stringify(result) }] }
  }
})

幾個重點。searchInputSchema 這個 Zod schema 同時餵給 tool 的 inputSchema 跟 execute 的 runtime parse，確保 agent 傳什麼進來都先過一次驗證。description 寫得比一般 JSDoc 仔細，因為 LLM 沒有其他資訊可參考。useMcpTool 是極薄的 wrapper，只處理特性偵測跟生命週期，不做任何業務假設。

第三步：動態 scope tool，跟著畫面或路由走 ​

不要把所有 tool 在 app 啟動時一次註冊完。用 component 生命週期或路由切換做動態 scope：

• 結帳頁才註冊 apply_coupon、place_order
• 商品列表頁才註冊 add_to_cart
• 後台才註冊 delete_user、reset_password

這樣 agent 在任何時刻看到的 tool 集合都跟使用者當下情境對齊，選擇品質好很多。

第四步：別太早抽 useMcp() 框架層 ​

WebMCP 還在 Community Group draft，API 形狀、permission model、最佳實踐都可能變動。太早把一套 useMcpComposable() 抽成內部框架，相當於把不穩定 proposal 凍結進 API，之後 spec 改一下整個 codebase 都要連動。

我的判斷標準是「同一段 composable 在第三個專案複製貼上」才考慮抽出來，而且只抽薄框架層（SSR 守衛、生命週期），業務邏輯留 example/recipe，不要進 core。

Vue 場景的劣勢與務實決策 ​

寫到這裡都在講 Vue 的好，接下來換一段誠實的反面。Vue 不是萬能，有些 AX 場景反而是 Vue 的短處。

SSR / hydration 邊界要嚴格守 ​

這個是 Nuxt / VitePress 場景必踩的雷。WebMCP 註冊邏輯如果不小心放在 module top-level、plugin 初始化、setup 同步階段、或 Nuxt 的 universal plugin，server 端執行會直接炸，因為 navigator 不存在。

守則只有一條：註冊邏輯嚴格放在 client-only lifecycle。具體做法是 onMounted 內部、if (import.meta.env.SSR) return 守衛、Nuxt 的 .client.ts plugin 命名。只要嚴守 client-only，SSR 風險可控，危險的是不小心放到 universal scope。

Tool boundary 的資料正規化是新手坑 ​

WebMCP 的 tool execute 函式，輸入輸出原則上只該傳 plain JSON-compatible data。但 Vue component 裡的 ref / reactive / computed 是 proxy，如果直接把 reactive 物件回傳給 agent，可能會出現幾種問題：

• proxy identity 跟 raw identity 不同，跨邊界比對會錯
• 巢狀 ref / computed 被序列化成意外形狀
• class instance、Date、Map、Set、File、Blob、function 跨邊界本來就不安全
• tool schema 預期 plain JSON，proxy 物件不一定符合

解法是必要時用 toRaw()、unref()、schema parse、structuredClone() 做正規化。Code review 應該把這個列為重點檢查項，因為一旦寫錯，測試在瀏覽器裡跑常常看不出問題，只有 agent 端的回應品質會慢慢崩壞。

Component 邊界 ≠ tool 邊界 ​

跨頁流程是 Vue + WebMCP 最不順手的地方。例如電商結帳橫跨「購物車 → 確認地址 → 選付款 → 完成」三四頁，這條 flow 上的 tool 不能放任何單一 component，因為 component 一卸載 tool 就消失。

這時候 tool 必須放 store 或全域 composable，意味著「tool 跟 UI 住在一起」的好處在跨流程場景失效。一個專案會混用兩種風格（component-scoped 跟 store-scoped），一致性會下降，新進工程師需要學會分辨「什麼時候放哪」。

我目前能想到比較順的解法有三條，不能說完美，但都比「亂放」好：

(a) Layout component 當 tool scope 跨頁 flow 通常會有共用 layout（例如 <CheckoutLayout> 包住結帳的四頁），把 flow 級 tool 的 useMcpTool() 呼叫放在 layout 的 setup 函式裡，讓 layout 的生命週期當 tool scope。使用者進入 /checkout/* 路由就註冊，離開整個 layout 才卸載。這個寫法保留了「tool 跟 UI 住在一起」的好處，又解決 component 一頁一卸載的問題。

(b) 流程級 composable 顯式管理 scope 如果 flow 由多個獨立 component 組合，沒有共用容器，可以寫一個 flow-level composable，由 flow 入口呼叫、出口呼叫 dispose：

// flows/checkout/useCheckoutFlowTools.ts
export function useCheckoutFlowTools() {
  if (typeof navigator === 'undefined' || !('modelContext' in navigator)) {
    return () => {}
  }
  const ctx = (navigator as any).modelContext

  ctx.registerTool({ name: 'apply_coupon', /* ... */ })
  ctx.registerTool({ name: 'place_order', /* ... */ })

  // flow 退出時呼叫，進行清理
  return () => {
    // WebMCP unregister API 規格成熟後接上
  }
}

把 register / dispose 兩端寫在同一個檔案，code review 比塞在 store 裡更看得出 scope 範圍。要 caveat 的是 WebMCP 規格目前沒明確的 unregister API，dispose 函式現階段比較像佔位，實務上靠 page 卸載清掉註冊狀態，等規格補完才能真正做 cross-flow 清理。

(c) vue-router navigation guard 最後一條走路由：beforeEach 進入 flow 時呼叫 register，afterEach 偵測離開時呼叫 dispose。邏輯集中在 router 設定檔，所有 flow 級 tool 都在同一個地方管理；缺點是跟 component 距離拉遠，drift 風險回來了。

實務上我會優先試 (a)，layout-driven 既符合 Vue 慣例、又抑制 drift；(b) 留給沒共用 layout 但邊界仍清楚的場景；(c) 通常是 codebase 已經習慣「集中註冊」風格才用。團隊裡訂一條清楚規則（例如「flow 級 tool 一律走 layout，store 只放純資料、不放 tool 註冊」），新進工程師才不會混亂。

Bundle size 對 agent-first 場景不划算 ​

Vue 3 + Pinia + Router + WebMCP runtime 加起來大致落在數十 KB gzip 等級（實際數字以你的 bundle analyzer 為準，受 tree-shaking 跟用量影響）。對一般 SPA 這個 size 沒問題，但對 agent-first 場景（API doc、純內部工具、純 agent endpoint）就完全不划算。

agent 不需要 reactivity、不需要 component 樹、不需要 router，給它一套完整 reactive SPA stack 等於 99% 的能力它用不到。這類場景用原生 JS 寫一支百來行的 WebMCP 註冊腳本反而乾淨。

Devtools 跨兩個世界 ​

Vue Devtools 看不到 MCP 呼叫，MCP Inspector 看不到 reactivity 訊號。沒有單一介面同時看到「tool → action → state → re-render」這條鏈路，debug 的時候要自己埋 trace，在兩個 devtools 之間切換對照。這個目前無解，只能等生態成熟。

決策樹 ​

整理一下什麼場景值得用 Vue 做 WebMCP、什麼不值得：

順帶補一個常見誤解。對純內容站（部落格、行銷頁、文件站）而言，先把 semantic HTML、結構化資料（Schema.org）、清楚的標題層級整理乾淨，對 AI crawler 跟 Browser Agent 的幫助比直接做 WebMCP 還大。WebMCP 走的是 navigator.modelContext.registerTool()，繞過 DOM；做語意化 HTML 服務的是另一群讀 DOM 的 AI 訪客（搜尋爬蟲、Computer Use 那類）。沒做 WebMCP 不等於對 AI 擺爛，看你想接的是哪種訪客。

動工前該寫的兩份清單 ​

最後是我覺得對成熟網站引入 WebMCP 最關鍵的一個動作：在 sprint kickoff 前，跟團隊一起花一個下午寫兩份清單。這兩份清單會直接決定後續排程的優先順序，也避免做著做著，一個寫入類 tool 偷偷溜上 production。

清單一：現有 API 哪些可安全包成 tool ​

把站上所有 API endpoint 列出來，對每一支問三個問題：

三題都通過的優先做，可以包成 read-only tool 馬上上線；通過兩題的次之，補一補就能上；只通過一題或全敗的最後做，可能要先改 API 才包得起來。這個分級會直接餵給 sprint planning 的 backlog，避免「想到什麼就先做什麼」的隨機開發節奏。

清單二：哪些操作絕對不開放給 agent ​

這份清單可能比清單一還重要。常見的紅線項目大概可以分成五類：

• 不可逆動作：刪除使用者、刪除訂單、清空購物車、移除上傳檔案
• 金流相關：變更付款資訊、轉帳、退款核可、修改訂閱方案
• 權限變更：升降級角色、加減團隊成員、產生 API key、變更 SSO 設定
• 對外通訊：寄客訴信、發出工單、推播通知、群發 email
• 法規敏感：個資存取、醫療紀錄、未成年資訊、跨境資料傳輸

這些動作就算上 requestUserInteraction 二次確認都未必夠，因為 agent 可以在前面的對話誘導使用者「等下會跳出確認框，按確認就好」。 安全做法是直接從 tool 列表排除，只留人類走 UI，agent 想做就主動跟使用者說「這個我不能幫你，請你自己操作」。

兩份清單怎麼用 ​

寫完之後，把清單一的優先順序帶進 sprint planning，把清單二的紅線寫進 code review checklist（PR 加 tool 之前，reviewer 先檢查 tool 名稱有沒有撞到紅線）。 每個 sprint 結束更新一次：新的 API 上線就追加到清單一，業務變化就調整紅線範圍。清單寫完歸檔不更新，等於沒寫。

後記 ​

寫到這裡，我自己對 AX 這件事的感覺是，它不會在一兩個月內顛覆前端工作，但會在一兩年內慢慢滲透進每個 Vue 開發者的日常。Pinia action 多寫兩行 description、表單多走一次 Zod schema、router meta 多塞一個 agentAccessible flag，這些小動作累積起來，就是這個世代前端工程師的新基本功。

身為 Vue 的開發者，我認為 Vue.js 在這場轉型裡的位置是有利的。 Vue reactivity 對「state 同時餵 UI 跟 agent」近乎零成本，Pinia 對 tool 註冊起手式接近終點，SFC 對 drift 抑制天然有效。 這些都是 mental model 上的契合，不是套件數量的堆疊。

寫這篇的同時，好友 Paul Li 拿 Yahoo!拍賣的頁面做了一個 WebMCP demo。他註冊了兩個 tool，demo 影片裡示範 agent 辨識「找預算內的 Nintendo Switch 2」這類使用者意圖時，會直接呼叫對應 tool 跳到最精準的搜尋結果頁，跳過視覺辨識跟 DOM 解析那套。

雖然這還只是 demo 不是上線版本，但能在大型電商規模的頁面上跑出兩個 tool 的差異就已經很有意義，至少能說明動手實驗的成本沒大家想像中高。

至於 WebMCP 規格本身會不會像 Schema.org / microformats 那樣熱鬧開場、最後普及不如預期？老實說我也不知道。 但 Vue.js 的開發生態圈上，做 AX 的邊際成本不高、回頭成本也不高，先從 read-only tool 開始試水溫，觀察一陣子再加碼，我覺得是合理的賭注策略。

週末去五倍上了 Cash 哥的 Classic TDD Workshop，重新走了一輪經典的 Potter TDD Kata。

雖然多年前我也上過 91 哥的 TDD 課程，但這次跟著 Cash 哥的節奏重做一次， 除了複習 TDD 的基本精神與流程之外，最大的收穫重新理清 TDD 在開發時的思考順序，以及現今 AI 時代下 TDD 帶來的價值。

Kata 題目本身不難，這篇文章想把 Red、Green、Refactor 完整走過一遍之後，記錄一下 TDD 在我腦中留下了什麼。

題目的需求很單純：哈利波特一套五本，單本 100 元，2 本不同 95 折、3 本 9 折、4 本 8 折、5 本 75 折。要實作 add(cart, book) 跟 calculatePrice(cart) 兩個 function：add 把書加進購物車並回傳新的 cart，calculatePrice 根據購物車的內容算出最便宜的總價。

不只是「先寫測試」 ​

如果是不理解 TDD 的朋友，我想大家對 TDD 的印象可能大多停在表面的「先寫測試」。 所以我覺得如果只把 Red-Green-Refactor 三步當流程記下來，這篇筆記就很容易流於表面。

但 TDD 真正的價值，是它逼出一個開發時的思考順序。「TDD 的順序 = 你對問題的理解順序。」測試先寫成什麼樣，反映的就是你對需求理解到什麼程度。

1. 先回答需求是什麼 ​

Potter Kata 表面在算價格，但需求其實有兩層：購物車要能加入書，價格計算要符合折扣規則，而且要找出最便宜的分組方式。這兩層如果沒先拆開，很容易把題目看成「套折扣公式」，最後寫出一個只能處理單純情境的版本。

所以 TDD 第一個帶來的價值，其實是逼自己先回答：這題到底在解什麼問題？哪些行為是外部真的看得見的？哪些只是我腦中以為合理、但需求其實沒有保證的事？

2. 把抽象需求拆成可驗證的例子 ​

需求一抽象就容易漏邊界。第二步先別急著寫程式，把情境列出來：空購物車怎麼算、一本書怎麼算、多本不同書怎麼套折扣、有重複書怎麼拆組、哪些案例會揭露錯誤的演算法。情境列完之後，這份清單本身就是需求，測試只是把它寫成跑得動的形式。

3. 測試的順序本身在推動設計 ​

Cash 的 commit 順序看起來瑣碎，但每一個 [red] 都只往前推一小步。先測 1 本書、再測 2 本同書、再測 2 本不同、3 本不同、4 本不同、5 本不同，最後才放重複書的 case。這樣排的好處是，每一次失敗都只告訴你一個新的訊息，不會一次把整題複雜度全部灌進來。

也呼應 TDD 一個我覺得很重要的精神：把問題切到夠小，小到每次只需要做一個決定。

4. 先寫失敗的測試，再寫剛好通過的程式 ​

「先寫測試」這句話的重點我認為是控制開發的衝動。

如果先寫程式碼，很容易直接跳進自己熟悉的解法，事後再補測試替它背書。 但如果先讓測試失敗，思考重點會變成：我現在要保證的是哪個行為？我希望下一個失敗訊息告訴我什麼？我是不是正在為還沒被要求的東西提早設計？

而「剛好通過」是另一道煞車。它在提醒自己不要超前設計：忍住不要一次把所有情境都寫完，忍住不要在還沒需要時就先抽象化，忍住不要把重構和解題混在同一步。

Cash 在課堂上講得更直接：「學會忍住，工程師的通病就是會忍不住一口氣做完，剛開始學 TDD 的人會很不習慣，因為太慢了。」TDD 的節奏感很大一部分就是來自這種克制。

看起來慢，其實正是 TDD 的設計。每一步只走一格雖然看起來很瑣碎，但換來的是任何一刻測試紅燈都能精準回退。把這個工程師通病先壓下去，這套節奏才跑得起來。

跟著 Cash 的步驟走一遍 ​

Cash 哥在課堂上提供的示範 repo 從 init 到完成總共 80 多個 commit， 每一個都標 [red]、[green] 或 [refactor]，每一個都只動很少的程式碼。

如果是不熟 TDD 的朋友，第一次看這串 commit 應該會覺得：「這也太瑣碎了吧。」 但自己跟著重做一次之後，就會懂這個粒度的意義。

而且 Cash 在課堂上特別強調過：每一個紅燈、綠燈、重構都應該各自 commit。除了版本管控的好處之外，更實際的影響是每一步變更都被獨立記錄下來，出問題時可以乾淨地回到上一個綠燈，重構壞掉時也能精準看出是哪一個小步驟動到了行為。這在團隊協作時會更明顯，其他人從 commit 流就能讀出你解題的節奏，而不是只看到一個塞滿邏輯的大 PR。

這個習慣聽起來很瑣碎，但走完一輪就會發現它跟 TDD 的安全感是綁在一起的。

起手式：Fake It ​

第一個 [red] 時，calculatePrice 還只是空殼，add 則先用最直接的 immutable 寫法回傳新購物車：

export function add(cart, book) {
    return [...cart, book];
}

export function calculatePrice(cart) {
    return undefined;
}

對應的測試是「一本書應該回傳 100」。Red 之後緊接著 [green]，但這一步沒去湊真正的計算邏輯，只把 return 改成：

export function calculatePrice(cart) {
    return 100;
}

這就是 Kent Beck 講的 Fake It：第一次綠燈不需要通用，只需要通過當前測試。對我這種拿到題目就想直接寫對的人來說，這一步特別有教育意義，它逼你先確認「測試真的能抓到正確答案」、「pipeline 真的能跑完一輪」，這兩件事比演算法早。接著才是 refactor，把 100 抽成 BOOK_PRICE 常數。

一個 commit 一件事，乾淨俐落。

Triangulation：用第二個案例逼出泛化 ​

下一個 [red] 加了「同一本書買兩次應該回 200」的測試。[green] 是這樣的：

function calculatePrice(cart) {
    if (cart.length === 2) return 100 * 2;
    return BOOK_PRICE;
}

還是 hardcode，但已經出現分支。緊接著的 refactor 才是亮點，分兩步走：

// step 1: [refactor] - duplicate code
if (cart.length === 2) return BOOK_PRICE * cart.length;
return BOOK_PRICE * cart.length;

// step 2: [refactor] - remove duplicate
return BOOK_PRICE * cart.length;

第一步先讓兩個分支「故意長得一樣」，第二步才把 if 砍掉。這個技巧叫 duplicate-then-remove，看起來多此一舉，但好處是每個 commit 都維持綠燈。如果直接把 if 跟分支內容一起改，重構過程中萬一壞掉，就找不出是哪一步出的事。

這就是 Triangulation 的精神：用兩個案例同時夾住正確答案，把 hardcode 的個案逼成通用解。

原本我習慣的是「想出通用解再寫」，TDD 想要的是「先寫個案、再被測試逼出通用解」。

從 if 鏈演化成 lookup table ​

到了三本不同書 (price 1, 2, 3)，[green] 又是一個分支：

if (cart[0] === 1 && cart[1] === 2 && cart[2] === 3) return BOOK_PRICE * cart.length * 0.9;
if (cart[0] === 1 && cart[1] === 2)                  return BOOK_PRICE * cart.length * 0.95;
return BOOK_PRICE * cart.length;

接下來 7 個 refactor commit，每一個都只改一點點，逐步把 if 鏈轉成 discountLookup 對照表 + new Set(cart).size 的查表寫法：

const discountLookup = { 1: 1, 2: 0.95, 3: 0.9 };
const distinctBooks = new Set(cart);
return BOOK_PRICE * cart.length * discountLookup[distinctBooks.size];

到這一步之後，4 本和 5 本的 case 只要在 discountLookup 多加兩行就直接綠燈，連 calculatePrice 本體都不用改。 如果不是用 TDD 的方式，我可能會直接就寫成 lookup 形式，但沒體會到的差別是：這個 lookup 是被多個 case 慢慢逼出來的形狀，先有需求，才有對應的結構。

Cash 在這段特別提醒過一句我印象很深的話：「想一下每一個重構的流程，為什麼要這樣做、重構的順序很重要。」

這幾個 commit 的順序回頭看完全不是隨手排的：先把 discountLookup 跟原本的 if 分支並存放著，再一個分支一個分支地改用 lookup，接著導入 new Set(cart) 把判斷依據從 hardcode 的 index 換成 distinctBooks.size，最後把 lookup 補齊到 1 本書的分支也能套用，這時候三個 if 分支才終於長得一模一樣，砍 if 才安全。

如果中間隨便調換一步，例如先用 distinctBooks.size 當查表 key、但 lookup 裡還沒有對應的條目，馬上就會踩到 undefined 把測試打紅。

重構真正在做的事情是「在保持綠燈的前提下、一步一格把結構往前推」，至於程式變不變漂亮，是順帶的結果，這個前提決定了你能用什麼順序。

卡關時的勇氣：Suspend Test ​

接下來 [red] price 1, 2, 1（買兩次第 1 本加一次第 2 本，期望 290）就把整個 distinct-set 解法打爆了。distinctSet.size 是 2，套錯折扣，得到 285，差 5 元。

這時候很多人（包括我自己）會直接動 calculatePrice，硬塞分支去通過測試。但 Cash 做的事是 [red] price 1, 2, 1 - comment，把這個測試先註解起來。

這個動作叫 Suspend Test。如果當前測試對現在的程式碼來說「跨度太大」，與其硬塞，不如把它擱著，drill down 去開更小的 helper 函式，等基礎建好再回來。這個動作的核心是承認自己現在還沒有足夠的工具，先去打造工具、再回頭解這個 case。

Drill Down：用 TDD 開 helper 函式 ​

接下來 30 多個 commit 全部在開兩個輔助函式：countBooks 跟 groupBook，而且每個 helper 自己也是完整的 red-green-refactor 循環。

countBooks 從 {1:1} 的 hardcode 開始，經過 fake it、用 cart[0]、改 for of、加分支處理重複，最後演化成：

function countBooks(cart) {
    const counts = {};
    for (const book of cart) {
        counts[book] = (counts[book] || 0) + 1;
    }
    return counts;
}

countBooks 解的是「每一本出現幾次」，groupBook 解的是「根據這些次數，先切出一組組可計價的書」。前者把資料整理成可推理的形狀，後者才開始處理折扣分組。

groupBook 也是一樣，從 [[1]] 的 hardcode 開始，逐步加進「拿 distinct 書」、「按最大重複數開 N 組」、「把每本書平均分配到各組」，演化成：

function groupBook(cart) {
    const counts = countBooks(cart);
    const volumes = Object.keys(counts);
    const groups = [];
    const maxGroupCount = Math.max(...Object.values(counts));

    for (let i = 0; i < maxGroupCount; i++) groups.push([]);
    for (const volume of volumes) {
        for (let i = 0; i < counts[volume]; i++) {
            groups[i].push(+volume);
        }
    }
    return groups;
}

這個分組策略目前的巧妙之處，是它直接照「最多重複幾本書」開 N 組，再把每本書水平攤到各組。[1,2,1,2] 自然變成 [[1,2],[1,2]]，每組都吃滿 5% 折扣。沒有窮舉、沒有遞迴，純粹是被一連串小 case 逼出來的形狀。不過這個策略還不是 Potter Kata 的終點，後面有更難的最佳分組案例會再暴露它的限制。

回到主測試 ​

helper 都建好之後，[red] price 1, 2, 1 - uncomment 把原本擱著的測試恢復，[green] 用 groupBook 重寫 calculatePrice：

function calculatePrice(cart) {
    const groups = groupBook(cart);
    let price = 0;
    for (const group of groups) {
        price += BOOK_PRICE * group.length * discountLookup[group.length];
    }
    return price;
}

到這裡所有測試都通過。再加一個 [1,2,1,2] 的 case，發現不用動任何程式碼也直接綠燈，演化出來的解法天然支援它。這個瞬間我覺得是最爽的：你會發現自己一路小步走下來的程式，已經默默支援了新的需求，根本沒有刻意去「設計」可重用性。

「TDD 是浮現設計（Emergent Design）的方式，讓設計從解決問題的過程中浮現出來。」一路上每個小決定都只解決當下的測試，但這些決定累加起來，就是後面那個剛好接得住新 case 的形狀。

從這趟重做學到的 TDD 技法 ​

回頭整理 Cash 示範用到的招式，每一個或許我們在 Kent Beck 的《TDD by Example》書裡都聽過名字， 但真正走過一遍之後，才會體會到它們在實際操作中的意義。

Fake It Till You Make It。第一次綠燈直接 hardcode，先確認測試 pipeline 跑得起來，演算法之後再說。

Triangulation。等第二、第三個 case 出現，才把 hardcode 推往泛化。設計是被一個個 case 逼出來的形狀，自己事先想破頭也想不到那麼貼切。

Duplicate-then-Remove。要刪 if 分支前，先把每個分支變成一樣的程式碼，再砍 if。每個中間 commit 都還能跑，壞掉就回得去。

Suspend Test。當前 case 對現在的程式碼跨度太大，先註解起來，drill down 開更小的 helper。擱著聽起來像放棄，其實是承認手上還缺工具，先去打造它。

Child Test。被 suspend 的測試底下，每個 helper 函式自己也跑完整的 red-green-refactor。整個過程是巢狀展開的 TDD，會在 helper 裡再開一輪完整循環。

Merciless Refactoring。每個小重構都是獨立 commit，連抽變數、改 for 迴圈都各自一筆。不混在實作裡，因為混了之後就分不清哪一步壞掉。而且每一步的順序本身就是設計，隨手換個順序，中間某一步就會打破綠燈，安全網就破了。

延伸的挑戰：最佳分組的 case ​

老實說，Cash 示範的 commit 序列收在 [1,2,1,2] → 380 這個 case，演化出來的「按最大重複數平均拆組」解法剛好能處理它。

但我自己在練習時其實還加了一個更難的 case: ['A','A','B','B','C','C','D','E'] → 640 ，結果發現這才是真正麻煩的地方。 XD

這個 case 會打爆任何「平均拆組」的策略，因為最佳解是 ABCD + ABCE（兩組四本不同 = 640）而不是 ABCDE + ABC（五本加三本 = 645）。

Cash 在課堂上提過一句很關鍵的話：「你的演算法會影響到你對 TDD 的設計，因為你的每一步都很小，所以當你發現改不下去的時候，就應該要停下來調整。」面對 640 這個 case，「平均拆組」就是改不下去的時刻，這個訊號要說的是該回頭重新看演算法，硬撐著繼續塞分支只會越改越亂。

我自己第一次寫的時候是直接跳到 bitmask 窮舉 + memoization 把它一次解掉。事後想其實方向是對的（真的需要換演算法），但跳得太大，整個 TDD 的演化過程被自己折掉了。

比較理想的做法是把這個 case suspend 起來，drill down 到一個更通用的 split 函式，用 baby steps 把它推回去。不然就算最後寫出來了，過程中也會一直打紅燈，完全失去 TDD 的安全感。

回頭看這整段卡關，「TDD 可以幫你發現問題，但不完全幫你解決演算法。」紅燈會告訴你「現在的解法不夠用」，但要換成什麼演算法、要怎麼換，這一步還是得靠開發者自己想。

TDD 的節奏感 ​

做完這次練習之後，比起記住術語，我更想留住的是這個順序，或者說節奏感：先用紅燈建立規格，再用綠燈完成行為，最後靠測試保護重構，而且這三步是「每一個 case」都跑一輪，不是整個專案只跑一輪。

對應到實際操作的順序大概是這樣：先搞懂需求、不急著寫解法；先把需求拆成情境、不急著寫完整架構；先安排測試順序、讓每一步只增加一點複雜度；先讓測試失敗、確認真的有抓到缺口；先寫剛好通過的程式、不偷跑；最後才重構，讓測試當安全網。

平常自己寫程式時，這套順序最容易破功的地方就是「忍住不超前」這一步。

常常是寫一寫覺得「反正等下也要寫到」就提前抽象、提前寫成通用解，最後測試已經被實作牽著走，而不是反過來規範實作。Potter Kata 是個剛剛好的尺寸，可以把這個順序硬性走完一遍，提醒自己：先 TDD 才能把這題拆得簡單，題目本身並沒有比較簡單。

TDD 的價值：讓 AI 快跑的安全網 ​

雖然現在已經是 AI Coding 時代，自己一行一行手刻 code 的機會其實越來越少。但走完這趟之後我反而更覺得，TDD 真正留下的東西，是它逼你在動手前先把需求、行為、邊界想清楚的那套思考順序。「寫測試」這個動作本身只是表象。

當 AI 寫 code 的速度快到一個程度，「先寫測試」反而從手刻時代被嫌慢的瓶頸，變成了唯一還跟得上 AI 速度的 spec 形式。 手刻時代沒先寫測試，頂多事後補救比較痛；AI 時代沒先寫測試，你根本不知道 AI 生出來的那一坨東西到底對不對。

以前 TDD 那種「忍住不超前」的克制看起來像在拖慢進度，但到了 AI 時代它反而成了讓 AI 可以放心快跑的安全網。

而最近也常被拿來討論的 SDD（Spec-Driven Development）剛好補上另一塊：先把需求寫成結構化的 spec 文件，AI 再照著 spec 生 code。 SDD 把人腦中模糊的需求外化成 AI 讀得懂的文字，TDD 則把同一份意圖翻譯成可執行的測試邊界。一個給 AI 看「要做什麼」，一個在跑完後驗證「有沒有做對」。

SDD 定義任務需求，TDD 用測試框住行為邊界，AI 負責在這個範圍內填滿實作。 三件事各司其職，1 + 1 才能大於 2。

WebMCP 是讓網站直接把功能暴露給 AI Agent 的新 Web 平台 API，由 Google 跟 Microsoft 主導，目前還在 W3C Web Machine Learning Community Group 的草案階段。核心 API 是 navigator.modelContext.registerTool()，網站把可呼叫的 JavaScript function 註冊上去，Agent 就能直接照 schema 呼叫，省掉「截圖認 UI 推按鈕」那一套。

前陣子做 Agent Ready 改造時，這項我刻意沒做，理由是 Chrome 還在 Early Preview、spec 也還在改、對靜態網站 cp 值不對等。 這幾天花點時間把官方文件、幾份訪談、社群 polyfill 都翻過一輪，也動手寫了一個小 demo 實際跑過，整理成這篇學習筆記。

Demo 單獨放在 kuro-roasters-webmcp 那個 repo 了，這裡聚焦記錄一下 WebMCP 大致的介紹，以及開發者會踩到什麼坑、我猜想的未來可能的發展方向等等。

為什麼要有 WebMCP ​

AI Agent 要操作網頁目前有兩條路。

一條是後端 API 或 MCP server，優點是穩、可控，但前提是要看網站有開放。 多數站台沒有，有的話還要處理 OAuth、API key、rate limit 這些東西。

另一條是現在最常見的 Browser Agent（Claude Computer Use、OpenAI Operator 那類），讓模型看畫面、認 UI、決定要點哪個按鈕；不用網站配合，但每一步都要塞截圖或整份 DOM 進 context，又慢又貴、網站改個 class 名稱就壞。

WebMCP 切第三條路：讓網站自己把能做的事用 Agent 看得懂的結構講清楚。與其讓模型從畫面去猜，不如網站主動宣告一組 JavaScript function，每個都有名字、自然語言描述、input schema，Agent 直接照 schema 呼叫就好。Scalekit 的 explainer 裡有個挺具體的對比：「新增一個叫 Drugstore 的分店，然後加一支護唇膏」這種任務，傳統 Browser Agent 要 30 到 60 秒，走 WebMCP tool call 大約 5 秒搞定。差別不只是快慢，是一個要截十幾張圖、一個是兩次 function call 就完事。

WebMCP 目前是 W3C Web Machine Learning Community Group 孵化中的 Draft Community Group Report（寫這篇時草案版本是 2026-04-23，還在迭代），明確不是 W3C Standard、也不在 Standards Track，Google 跟 Microsoft 主導推進。Chrome 146 Canary 起開放 Early Preview Program，其他瀏覽器還沒原生支援，但 Mozilla 跟 Apple 的工程師都有參與 working group，不是完全缺席。

WebMCP 怎麼用？ ​

核心 API 就一個入口：navigator.modelContext.registerTool()。一個 tool 的註冊長這樣：

if ('modelContext' in navigator) {
  navigator.modelContext.registerTool({
    name: 'search_products',
    description: '搜尋商品。支援關鍵字、價格上限過濾。',
    inputSchema: {
      type: 'object',
      properties: {
        query:    { type: 'string', description: '搜尋關鍵字' },
        maxPrice: { type: 'number', description: '價格上限' }
      }
    },
    annotations: { readOnlyHint: true },
    async execute(input) {
      const res = await fetch('/api/search?' + new URLSearchParams(input));
      return { content: [{ type: 'text', text: JSON.stringify(await res.json()) }] };
    }
  });
}

幾個細節值得特別提一下。description 是模型判斷要不要呼叫這個 tool 的主要依據，寫成自然語言、把觸發情境講清楚會比較可靠。 inputSchema 就是 JSON Schema，enum、required、minimum 這些常見屬性都支援。 annotations.readOnlyHint: true 代表這個 tool 不會改動狀態，Agent 可以直接呼叫不用確認。 execute 拿到結構化 input，規格把回傳定成 Promise<any> 沒強制結構；實務上為了跟 MCP 生態（@mcp-b/global polyfill、各家 MCP client）相容，慣例會包成 { content: [{ type: 'text', text: ... }] } 這種 MCP-style wrapper。整個流程跟 DOM 無關。

會改狀態或有敏感操作的 tool，慣例是透過 client.requestUserInteraction() 把確認權交還給使用者。這個 API 已經寫進規格，但具體演算法（例如瀏覽器要怎麼呈現確認對話框）還是 TODO，所以現階段更像是安全最佳實務、還不算強制規範：

navigator.modelContext.registerTool({
  name: 'place_order',
  description: '送出訂單',
  async execute(input, client) {
    const confirmed = await client.requestUserInteraction(async () => {
      return showConfirmationDialog({ items: cart.items, total });
    });
    if (!confirmed) {
      return { content: [{ type: 'text', text: JSON.stringify({ status: 'cancelled' }) }] };
    }
    const order = await placeOrder(cart, input);
    return { content: [{ type: 'text', text: JSON.stringify(order) }] };
  }
});

規格裡還規劃了一套「declarative API」，讓既有的 <form> 加 toolname / tooldescription / toolautosubmit 三個屬性就能自動轉成 tool。主規格文件裡這一章還沒寫完，不過 working group 開了 GitHub issue #22 跟一個 declarative-example repo 在推進。動手做的時候還是先走 imperative 這條比較實在。

其他瀏覽器沒原生 API 時可以用 @mcp-b/global polyfill，一行 script tag 就好，預設「有原生就不動、沒原生就補上一個功能相容的 navigator.modelContext」。要注意的是 polyfill 只補 API 表面，一般瀏覽器沒有內建 Agent 會去呼叫它，要真的讓 Agent 自動操作還是得 Chrome Canary；自己串一個 LLM 當驅動則隨便哪個瀏覽器都行，demo repo 的 Gemini 範例就是這樣跑的。

WebMCP 帶來什麼效益 ​

從三個角色各自看一次。

對網站開發者最大的誘因是不用為 Agent 重做一套 API。原本頁面裡就有的 JavaScript function，包個 registerTool 就能被 Agent 使用，邏輯不用重寫；想限縮 Agent 可以做的事也簡單，就決定要註冊哪些 tool、寫什麼 description。Token 成本這塊差距也很驚人：走 DOM 截圖的路線一次互動常常要塞數千到上萬 tokens，換成結構化 tool call 大多壓在幾百 tokens 以內，對收費模型來說差異一到兩個量級。

對使用者是可控性跟可見性同時變好。requestUserInteraction 讓寫入操作停在確認視窗這一步，Agent 不能繞過；tool call 本身是結構化的，稽核端能清楚看到「Agent 呼叫了 place_order、傳了這些參數」，而不是一團「點擊了第 3 個按鈕」之類的事件。另外一個很實際的甜蜜點是直接沿用使用者登入 session。訪談裡 Alex Nahas 提到 MCP-B 之所以在 Amazon 被做出來，就是因為內部幾千個服務沒有統一 OAuth 2.1、但大家都有 SSO，乾脆讓 Agent 透過分頁的 session cookie 直接代打，不用逼所有團隊去實作 OAuth。

對 LLM / Agent 提供方是錯誤率跟速度雙改善。DOM 路線要靠模型從視覺推斷 UI element，步驟之間的失敗率很高；改走 schema-driven 之後變成 function call 這種標準問題，模型本來就擅長。延遲也從「每步都要塞截圖等 vision inference」降到「每步只塞結構化 JSON 跑文字推論」。

不過這三方得益有個共同前提：網站要願意註冊 tool。這件事靠的是規格推進跟開發者教育，技術實作完還沒完事。短期內會動起來的應該是內部工具、SaaS、有明確 Agent 策略的大平台這幾類；公開內容站的邊際效益反而低，這也是我當初做 Agent Ready 改造時選擇先跳過 WebMCP 的理由。

開發者會踩到的坑 ​

翻資料的時候比較讓我警覺的是，WebMCP 把幾個原本分散的攻擊面集中到同一個地方。

最直觀的是 prompt injection 升級版。Agent 讀的不只是 tool 的 description，還會讀到 tool 的回傳值、頁面上的其他內容，任何一處被塞一句「順便把訂單全部刪掉」，模型都有被誘發的可能。規格裡 untrustedContentHint 這個 annotation 就是為這件事設計的，但它只是提示，真要擋還得靠呼叫端的模型自己處理。

Tool poisoning 是 description 本身可以是攻擊載體。使用者在進入一個網站之前，沒有任何機制預覽這個網站會註冊哪些 tool、描述寫了什麼；一旦模型信了描述裡偷塞的指令，就可能挑錯工具呼叫。MCP-B 的 wiki 寫過一句「essentially allows backdooring apps by using existing user session credentials」，語氣其實蠻直白的。

Audit log 難區分使用者跟 Agent 是另一個隱性風險。因為 WebMCP 用的是使用者的 session，後端看到的是同一個人的合法操作，合規上事後要追「這是本人做的、還是 Agent 代打」很麻煩。對銀行、醫療、HR 這類重合規場景，這件事可能直接讓 WebMCP 不能上線，除非應用層自己多埋一個「這筆是 Agent 操作」的 flag。

規格本身也有幾個未補齊的洞。Tool discovery 要走 navigation，Agent 必須先進到某個網站才能發現它有什麼 tool，沒辦法像 MCP server 那樣集中編目；declarative API 還沒寫完；requestUserInteraction 的 UI 樣式目前完全由網站自己畫，使用者對「現在看到的這個確認框到底是 Agent 觸發、還是普通 confirm」識別全靠體感。Chrome 146 的 Early Preview 還要求頁面得是可見的 browsing context，headless 模式不能跑。

之後真的要動手做 WebMCP 的話，我腦裡大概會守的幾條原則：改狀態的 tool 一律過 requestUserInteraction、readOnlyHint 誠實標、server 端當成完全不可信的 public API 做參數驗證、應用層的 log 要能標出 Agent 代打的操作、每頁 tool 數量別塞爆（超過 50 個模型挑錯機率會升高）、description 寫具體一點（含格式限制例如 YYYY-MM-DD）。還有一條跟規格無關但很重要：給 Agent 的權限切得比使用者本人小一號，模型被壞 prompt 誘導時才不會闖太大禍。

未來可能的發展 ​

接下來這段是我基於目前規格缺口跟社群討論的推測，看看參考就好。 但如果真的都動起來了，我認為兩三年後的 Web 生態肯定會跟現在很不一樣。

瀏覽器支援是最有可能先動起來的一塊。Chrome 146 Canary 的原生實作已經出來；Edge 同屬 Chromium 生態又有 Microsoft 參與規格編輯，後續機率相對高，但目前沒有正式時程。Firefox 跟 Safari 只在 W3C working group 看得到工程師身影，沒有公開承諾，跟不跟、什麼時候跟都是未知。整體來說 Chromium 這系接下來的動態最可預期，其他三家就是看。

Declarative API 成熟會大幅降低接入門檻。現在走 imperative 要寫一套 JS，對大量簡單表單（聯絡我們、訂閱電子報、站內搜尋）其實殺雞用牛刀；等 <form toolname="..."> 這種宣告式介面補完，接 Agent 會變成類似加 aria-label 的小動作，電商跟 SaaS 的 onboarding 流程是最可能先動起來的一塊。

跨來源 tool 共享在 v1 被明確排除（只允許同來源註冊 tool），但已經被列為未來規劃。使用場景很清楚：「找台北評分最高的五家餐廳、一次訂全」這種任務需要 Agent 在多個網站之間協調，全走同一個分頁做不到。怎麼在保護使用者資料的前提下允許 cross-origin invocation 是個懸而未決的設計題，類比起來可能會長成 postMessage 加明確使用者確認的混合體。

Tool discoverability 是另一個未解的題，可能對生態影響比規格本身還大。目前 Agent 必須先 navigate 到某個網站才知道它有什麼 tool，沒有類似 MCP server catalog 的集中索引。社群有人在推 agenticweb.md 這類 machine-readable 發現規範，邏輯大概是「跟 robots.txt 放一起、內容是這個 domain 提供哪些 tool 的結構化清單」。這個方向如果定下來，「SEO」這個詞大概會有一半含義跟著改寫。

PWA 加背景執行則是比較遠但蠻有意思的可能性。如果 PWA manifest 可以宣告哪些 tool 是「不用打開 UI 就能執行」的，Agent 在沒有可見分頁的情境下也能呼叫，像「每週五下午幫我檢查購物清單，有特價就加入」這種背景代理任務就做得到了。這算是 WebMCP 從「陪使用者操作當前分頁」擴張到「代理使用者在後台跑任務」的一條可能路徑。

這些方向加起來指的是同一件事：整個 Web 正在從「給人看的頁面」變成「人跟 Agent 共用的互動介面」。短期內會動起來的大概還是內部工具、SaaS、重點電商；但如果 Edge / Firefox / Safari 一年內都跟上、跨來源跟 discovery 也有共識，兩年後的 Web 生態會跟現在很不一樣。

想動手玩玩 WebMCP ​

這次的 Demo 我另外放在 kuro-roasters-webmcp 這個 repo，線上版直接開 https://kuro.tw/kuro-roasters-webmcp/ 就能玩，方便大家感受一下 WebMCP 的使用流程場景。

Demo 場景是假想的咖啡豆選購店，註冊五個 WebMCP tool（搜尋、看商品、加入購物車、看購物車、結帳），再接上 Gemini function calling，讓讀者能用自然語言直接操作整個頁面，不需 Chrome Canary 也能試，我覺得挺適合拿來玩玩看、也能當作參考範例。 其中的技術細節（TOOL_DEFS 集中管理、polyfill 行為、agent loop 怎麼串 Gemini）寫在那邊的 README，這篇就不展開多說了。

參考資料 ​

• WebMCP 規格草稿
• WebMCP GitHub Repo
• Chrome 官方 blog：WebMCP is available for early preview
• Chrome 官方 blog：When to use WebMCP and MCP
• Scalekit：WebMCP explained
• Arcade 訪談 Alex Nahas
• MCP-B Wiki：Known Security Issues With WebMCP
• @mcp-b/global npm 頁面
• Gemini function calling 官方文件
• awesome-webmcp

最近 Cloudflare 推出了一個有趣的小工具 Is It Agent Ready?，用來評估你的網站對 AI Agent 的友善程度。

剛好拿自己的部落格去掃了一下，分數 8 分 Not Ready，真慘。 看了一輪檢查項目，覺得有些確實值得做，就順手做了兩輪改造，最後把分數推到 58 分 Level 4 Agent-Integrated，也順便把「哪些該做、哪些不必做」的判斷整理起來。

什麼是 isitagentready.com？ ​

這是 Cloudflare 維運的一個靜態檢查工具，給它一個網址，就會從幾個面向評估你的網站準備好「被 AI Agent 使用」了沒。這裡的 Agent 指的不只是傳統爬蟲，還包括會代替使用者瀏覽網站、呼叫 API、做決策的新一代 AI 應用。

評分分四大類（另加一個 Commerce 類別為選配，不計分）：

• Discoverability 可發現性：sitemap、robots.txt、Link response headers
• Content 內容：是否支援 Markdown Negotiation，也就是當 Agent 要求 markdown 格式時，能否直接給它乾淨的 markdown 而不是 HTML
• Bot Access Control 機器人存取控制：robots.txt 裡是否明確聲明 AI 爬蟲規則、是否有 Content Signals、是否實作 Web Bot Auth
• API, Auth, MCP & Skill Discovery：API Catalog、OAuth/OIDC、MCP Server Card、Agent Skills index、WebMCP 等

每個檢查項目都有明確的 Goal、Issue、How to implement，還附上對應 RFC 和實作參考，整體體驗蠻不錯的。

初始分數：8 分 ​

第一次掃描結果很慘：

• Discoverability：1/3，只有 sitemap 過關
• Content：0/1
• Bot Access Control：0/2
• API, Auth, MCP & Skill Discovery：0/6

VitePress 本身有內建 sitemap，這是唯一白撿的分數，其他全軍覆沒，笑死。

第一輪改造：robots.txt 與 Link headers ​

這兩項是成本最低的全壘打，做完分數從 8 直接跳到 42（Level 2 Bot-Aware）。

robots.txt ​

在 docs/public/robots.txt 建立一份同時滿足三個檢查項目的 robots.txt：

User-agent: *
Allow: /

# AI crawlers 明確允許（技術筆記希望被 AI 搜尋發現）
User-agent: GPTBot
Allow: /

User-agent: ClaudeBot
Allow: /

User-agent: PerplexityBot
Allow: /

User-agent: Google-Extended
Allow: /

# Content Signals (https://contentsignals.org)
# search=yes: 允許搜尋索引
# ai-input=yes: 允許作為 AI 即時回答的輸入
# ai-train=no: 不允許作為訓練資料
Content-Signal: search=yes, ai-input=yes, ai-train=no

Sitemap: https://kurohsu.dev/sitemap.xml

這邊有幾個設計值得說明：

第一，對 AI 爬蟲我選擇 Allow。技術筆記本來就是寫給人看的，被 AI 在回答時引用到對流量反而是加分。

第二，Content-Signal 是 Cloudflare 在 2025 年提出、夾在 robots.txt 裡的新指令（詳見 Content Signals Policy 與 contentsignals.org）。在它出現之前，robots.txt 只能用 Allow / Disallow 粗略表達「能不能爬」，但「爬了之後能拿去做什麼」一直是模糊地帶。Content Signals 把內容用途拆成三個獨立訊號，每一個都用 yes 或 no 表達：

• search：允許被用在傳統搜尋索引，也就是回連結跟短摘要的那種搜尋結果，不包含 AI 生成的摘要
• ai-input：允許被 LLM 在即時回答時當作引用來源，典型情境是 RAG（retrieval-augmented generation）
• ai-train：允許被拿去訓練或微調 AI 模型

寫法是在 User-agent 區塊裡加一行 Content-Signal: ...，多個訊號用逗號分隔。沒列到的訊號代表「不表達意見」，而不是預設反對。

我的選擇是 search=yes, ai-input=yes, ai-train=no，允許被搜尋與即時引用，但不允許當訓練素材。這裡順帶澄清一個我自己也差點搞錯的細節：Cloudflare 託管 robots.txt 的預設值其實是 search=yes, ai-train=no，並不會代替使用者自動聲明 ai-input，官方理由是無法預判客戶偏好，不想替人決定。

不過有一點要先講清楚：Content Signals 只是聲明，不是技術強制。它依賴各家 AI 爬蟲自主遵守，本質上跟 robots.txt 的 Disallow 是同樣道理。這不是防火牆，比較像是把意願攤在陽光下，讓合規的 bot 有所依據，也讓後續的法律或政策討論有個可以指的對象。

第三，Sitemap: 指令放最後，讓爬蟲不用自己猜 sitemap 在哪，雖然傳統但很實用。

Link response headers ​

RFC 8288 定義的 Link header，目的是讓 Agent 不需要解析 HTML 就能找到站台的重要資源。

這個站架在 Vercel 上，所以在 vercel.json 加：

{
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "Link",
          "value": "</sitemap.xml>; rel=\"sitemap\", </feed.xml>; rel=\"alternate\"; type=\"application/rss+xml\", </atom.xml>; rel=\"alternate\"; type=\"application/atom+xml\", </feed.json>; rel=\"alternate\"; type=\"application/feed+json\""
        }
      ]
    }
  ]
}

一條 Link header 指向 sitemap、RSS、Atom、JSON Feed，這樣 Agent 拿到首頁 response 的當下就能找到所有訂閱管道。

做完這兩項，重新掃描：42 分。Discoverability 3/3，Bot Access Control 2/3（Web Bot Auth 是選配的加密簽章驗證，對個人站台來說過度了），短時間內能撿的分都撿起來了。

第二輪改造：Markdown Negotiation 與 Agent Skills ​

第一輪處理掉了「只需要加檔案就能解」的項目。接下來要拉分，只剩下兩個實際對 Agent 有用的：Markdown Negotiation（Content 類）與 Agent Skills index（API 類）。

Markdown Negotiation ​

Agent 跟瀏覽器的需求不一樣。瀏覽器要 HTML 加樣式，Agent 只想要乾淨的文本。Markdown Negotiation 的做法是，同一個 URL 依據 request 的 Accept header 回傳不同格式：瀏覽器給 HTML，Agent 要求 text/markdown 就給 markdown。

我的做法分兩步。

第一步，在 VitePress buildEnd hook 加一個產生器，把每篇文章的原始 .md（去掉 frontmatter）輸出到 dist 對應的扁平路徑：

// scripts/generateMarkdownFiles.ts
export async function generateMarkdownFiles(config: SiteConfig) {
  const outDir = config.outDir
  const docsDir = path.resolve(config.srcDir)

  for (const category of ['notes', 'learn', 'misc']) {
    const files = walkMarkdownFiles(path.join(docsDir, category))
    for (const absPath of files) {
      const raw = fs.readFileSync(absPath, 'utf-8')
      const { data: frontmatter, content } = matter(raw)
      if (frontmatter.draft) continue

      const slug = path.basename(absPath).replace(/\.md$/, '')
      const outPath = path.join(outDir, category, `${slug}.md`)
      fs.mkdirSync(path.dirname(outPath), { recursive: true })
      fs.writeFileSync(outPath, content.trimStart(), 'utf-8')
    }
  }
  // ... 還會產生 index.md 與 about.md
}

產出後，docs/.vitepress/dist/ 底下就會同時有 notes/article.html 和 notes/article.md 兩個檔案。

第二步，在 vercel.json 加條件式 rewrite 和 Content-Type override：

{
  "rewrites": [
    {
      "source": "/:category(notes|learn|misc)/:slug.html",
      "has": [
        { "type": "header", "key": "accept", "value": ".*text/markdown.*" }
      ],
      "destination": "/:category/:slug.md"
    }
  ],
  "headers": [
    {
      "source": "/:category(notes|learn|misc)/:slug.html",
      "has": [
        { "type": "header", "key": "accept", "value": ".*text/markdown.*" }
      ],
      "headers": [
        { "key": "Content-Type", "value": "text/markdown; charset=utf-8" },
        { "key": "Vary", "value": "Accept" }
      ]
    }
  ]
}

重點是 has 條件，只有當 request header 含 Accept: text/markdown 時才會觸發 rewrite，瀏覽器的 Accept 不包含這個值，日常瀏覽完全不受影響。

Vary: Accept 則是告訴 CDN 要依照 Accept 分別快取不同版本，避免把 markdown 版本回給瀏覽器，或反過來。

Agent Skills index ​

這是 Cloudflare 推動中的新興 discovery 規範（目前 RFC 還在 v0.2.0，規格仍在演進），位置在 /.well-known/agent-skills/index.json，用來讓站台「告訴 Agent 我這裡能做什麼」。

對純內容站來說，合理的 skill 有兩個：

1. read-article-as-markdown：Agent 可以透過 Accept negotiation 拿到任何文章的 markdown
2. discover-articles：Agent 可以透過 sitemap、RSS、tag 頁等方式列出文章

我在 docs/public/.well-known/agent-skills/ 建了兩個 skill 描述檔（markdown 格式），再寫一個 build script 讀取這些檔案、計算 sha256，輸出 index.json：

// scripts/generateAgentSkills.ts
const index = {
  $schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
  skills: SKILLS.map(skill => ({
    name: skill.name,
    type: 'skill-md',
    description: skill.description,
    url: `${siteUrl}/${skill.path}`,
    digest: sha256Digest(path.join(outDir, skill.path))
  }))
}

Skill 描述檔用 markdown 寫，方便人類也能讀；digest 則提供完整性比對的基礎，讓消費端有能力驗證檔案沒被動過手腳。不過這條信任鏈成不成立，終究還是要看 Agent 那端是否真的實作了驗證流程。

為什麼剩下的五項我選擇不做 ​

檢查報告還剩五個紅燈：API Catalog、OAuth/OIDC Discovery、OAuth Protected Resource、MCP Server Card、WebMCP。 這些我選擇暫時不實作，硬湊只會變成 cargo-cult，分數是好看了，但對個人部落格來說毫無實際意義，甚至可能因為多了沒必要的 endpoint 反而誤導 Agent。

API Catalog (RFC 9727) 要求列出站上的 API 加 OpenAPI spec 加 health endpoint。純靜態部落格根本沒有 API，把 feed.json 當 API 硬塞是在誤導 Agent。

OAuth/OIDC Discovery 需要你有 OAuth server 或 OpenID provider。這個站零認證，發布空的 metadata 會告訴 Agent「這裡可以拿 token」然後什麼都沒有，反而破壞信任。

OAuth Protected Resource 同上，要有「被保護的資源」才有意義。

MCP Server Card 是 MCP server 的名片，前提是你真的跑了一個 MCP server。只貼 card 沒有對應 endpoint，Agent 連過來就 404。這倒是一個有點意思的延伸題目，像是做一個「用 MCP 協議查部落格內容」的 server，不過那是另一個獨立專案了，不是加個檔案能解決的事。

WebMCP 是目前唯一對內容站可能有意義的，但現階段還在 Chrome 早期預覽計畫（Early Preview Program）階段，要報名才能拿到文件和 demo，spec 也還在變動。靜態網站為了這件事特別載入 client runtime script 成本不對等，等跨瀏覽器都支援再來做 CP 值會好很多。（後來還是花時間補做了一輪，研究筆記跟 demo 寫在 初試 WebMCP 那篇。）

最終分數與一些觀察 ​

兩輪改造結束，分數從 8 推到 58 分 Level 4 Agent-Integrated：

Discoverability、Content、Bot Access Control 三個類別都是滿分，API / Auth / MCP & Skill Discovery 拿到 1/6（Agent Skills index 過關）。對一個純內容靜態部落格來說已經接近上限了，剩下的 40 分是給有 API、有認證、有 MCP 基礎設施的站台準備的。

有幾個觀察值得記錄：

第一，「分數」不是目的。isitagentready.com 的檢查清單本質上是一份 best-practices，不同類型的站台適用的項目也不一樣。個人部落格硬追到 100 分，代表你在發布一堆假的 endpoint，對真正的 Agent 反而是雜訊。

第二，Markdown Negotiation 是最實用的一項。當 AI Agent 幫使用者讀你的文章時，省掉 HTML 解析這一層可以大幅降低雜訊，這個改動對內容可讀性最有感，分數反而是順帶的。

第三，Cloudflare 這套檢查會順帶把 robots.txt 的 AI 爬蟲規則、Content Signals 這些新規範一次推給你。就算不打算做 MCP，前半段的 Discoverability 跟 Bot Access Control 還是很值得跑一次，花不到十分鐘就能補完。

第四點是個保留：這篇目前都停在「能力層」，也就是「站台現在有能力被乾淨地抓、被 well-known 路徑發現」。但實際上到底有沒有 Agent 真的送 Accept: text/markdown、/.well-known/agent-skills/index.json 被誰抓走過、Link header 有沒有被解析，這些「成果層」的問題都還得靠 access log 才能回答，而我目前還沒有足夠資料。等累積一段時間的觀測再來寫一篇 follow-up 對照，應該會比分數本身有意義得多。

一個月後的 follow-up 寫在 Is It Agent Ready? 一個月後的 bot 流量實測：28 天 4,264 筆 bot 流量資料攤開，當初三條觀察有兩條成立、一條寫錯了。

用 Claude Code 一段時間之後，漸漸發現有些任務每次都要重新跟 Claude 解釋一遍背景：「我們的 commit 格式是這樣」、「記得用這個框架的慣例」、「這個專案有這些規則」。

Skills 就是為了解決這個問題而生的，讓你把這些重複的知識和流程打包起來，之後直接叫出來用就好。

什麼是 Skills？ ​

Skills 是一種「可攜式的指令包」，本質上是一個資料夾，裡面放了 Claude 需要知道的知識、腳本和資源。 當你啟動一個 Skill，Claude 就會自動載入對應的指令，不需要你每次重新說明。

官方的 anthropics/skills 倉庫提供了幾個現成的範例：

• pdf / docx / xlsx / pptx：讀取和分析各種文件格式
• webapp-testing：用 Playwright 測試本地網頁應用程式
• algorithmic-art：用 p5.js 生成演算法藝術
• brand-guidelines：套用品牌設計規範
• mcp-builder：快速建立 MCP 工具

這些只是範本，更有趣的是你可以自己做一個符合自己需求的 Skill。

Skills 的結構 ​

每個 Skill 是一個資料夾，裡面至少要有一個 SKILL.md：

my-skill/
├── SKILL.md          # 必要，Skill 的核心定義
├── scripts/          # 可選，Python / Bash / JS 腳本（確定性任務）
├── references/       # 可選，補充文件，供 Claude 按需參考
└── assets/           # 可選，輸出用的靜態資源（模板、字體、圖片等）

scripts/、references/、assets/ 三個目錄的定位不一樣，值得區分清楚：

• scripts/ 放的是 Claude 會去執行的程式碼，像是確定性的格式轉換、資料處理
• references/ 放的是文件，Claude 在需要時會讀進 context 參考
• assets/ 放的是輸出用的檔案，像是 PowerPoint 模板、字體、Logo，不是讓 Claude 讀的，而是讓 Claude 拿來用的

SKILL.md 的格式 ​

SKILL.md 用 YAML frontmatter 加上 Markdown 內文：

---
name: my-skill
description: This skill should be used when the user asks to "do X", "handle Y", or mentions Z-related topic. Describe what this skill does and when to trigger it.
---

# 詳細的操作指令

...

Frontmatter 有幾個欄位：

有兩個寫法慣例值得注意。Description 要用第三人稱格式，也就是「This skill should be used when the user asks to...」，不是「Use this skill when...」。

至於 SKILL.md 的內文，則建議用祈使句，動詞開頭的直接指令，而不是「You should do...」這樣的第二人稱。

三層載入機制 ​

Skills 設計了一個漸進式載入機制，避免每次都把所有資訊塞進 context：

第一層：隨時在場（約 100 words） 只有 name 和 description 會一直在 context 裡。Claude 用這個判斷哪個 Skill 需要啟動。

第二層：啟動時載入 當 Claude 判斷你的需求符合這個 Skill，才會把 SKILL.md 的內文讀進來。 建議控制在 500 行以內，大約 1,500 到 2,000 words 是理想範圍。

第三層：按需載入 scripts/、references/、assets/ 只在真的需要時才載入。 大量的參考文件或資料放這裡，不會一開始就佔用 context。

這個機制讓你可以安裝很多個 Skill，但 token 消耗依然受控。

一個真實的 Skill 範例 ​

xlsx Skill 的 description 是個很好的範本，看它怎麼把觸發情境列得非常具體：

---
name: xlsx
description: "Use this skill any time a spreadsheet file is the primary input or output.
  This means any task where the user wants to: open, read, edit, or fix an existing
  .xlsx, .xlsm, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting,
  charting, cleaning messy data); create a new spreadsheet from scratch or from other
  data sources; or convert between tabular file formats. Trigger especially when the
  user references a spreadsheet file by name or path — even casually (like \"the xlsx
  in my downloads\") — and wants something done to it or produced from it. Do NOT trigger
  when the primary deliverable is a Word document, HTML report, standalone Python script,
  database pipeline, or Google Sheets API integration, even if tabular data is involved."
license: Proprietary. LICENSE.txt has complete terms
---

注意幾點：觸發條件列得很細，包含使用者可能說的各種方式；更重要的是，它還明確說了什麼情況下不要觸發，避免搶到不屬於自己的任務。

SKILL.md 的內文也同樣具體，以 xlsx Skill 為例，裡面直接給了操作模式、錯誤處理流程，甚至連 Excel 公式的顏色編碼規範都定義好了，Claude 執行任務時完全不需要自己摸索。

安裝現有的 Skills ​

官方 Skills 可以透過 plugin 市集安裝：

/plugin marketplace add anthropics/skills

裝好之後，直接自然地跟 Claude 說就可以觸發，不用記指令：

幫我分析這份 contract.pdf 裡的付款條款

把 sales_report.xlsx 的季度資料加上一欄 profit margin

Claude 會自動判斷要用哪個 Skill 來處理。

用 Skill Creator 打造自己的 Skill ​

官方提供了 Skill Creator plugin，這是專門用來開發和測試 Skill 的工具包。它本身也是一個 Skill，安裝後只要告訴 Claude 你想建立或改善一個 Skill，它就會自動觸發。

整個開發流程是一個迭代迴圈：定義需求、撰寫草稿、跑測試、看結果、修改、再跑。

具體來說：

首先，Skill Creator 會問你幾個問題：這個 Skill 要做什麼、什麼情況下應該觸發、輸出格式是什麼、有沒有邊界情況要注意。問完之後，它會幫你產生 SKILL.md 草稿，並建立 2–3 個測試案例存成 evals/evals.json：

{
  "skill_name": "my-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "使用者的實際需求",
      "expected_output": "期望的輸出描述",
      "files": []
    }
  ]
}

測試怎麼跑 ​

接著 Skill Creator 會對每個測試案例同時跑兩個版本：一個「有 Skill」，一個「沒有 Skill」（改善現有 Skill 時則是跑舊版本作為 baseline）。 兩個版本平行執行，跑完之後透過 eval viewer 讓你瀏覽輸出結果，留下反饋。

在等待執行的過程中，Skill Creator 不會閒著，它會同時草擬定量評估的 assertions，也就是針對每個測試案例寫下可客觀判斷的期望，例如「輸出包含欄位 X」、「使用了腳本 Y」。 等結果出來，就會有 Grader 子代理自動評估每個 assertion 是否通過。

三個幕後子代理 ​

Skill Creator 內建三個專屬子代理，各司其職：

Grader（評分者）負責把 assertion 對照執行紀錄和輸出檔案逐條評判，通過或不通過、附上具體證據。它有個有趣的工作：除了評估你預先定義的 assertions，它還會主動從輸出中提取隱含的宣稱（例如「此 Skill 產生了 12 個欄位」），然後一一查核，補抓你沒寫到的盲點。更重要的是，它也會批判 evals 本身，如果某個 assertion 太容易通過（例如只檢查檔案存在而不檢查內容），它會指出來。

Comparator（比較者）是盲測。它收到兩份輸出，但不知道哪份是哪個 Skill 產生的，純粹從「內容正確性、完整性、準確性」和「結構組織、格式、易用性」六個維度各給 1–5 分，加總得出 1–10 的總分，選出贏家。 去掉身份資訊是為了避免偏見。

Analyzer（分析者）是 Comparator 之後的後處理。它「解盲」，知道了哪份輸出是哪個 Skill 的，然後去讀兩個 Skill 的 SKILL.md 和執行紀錄，找出「贏家為什麼贏、輸家哪裡輸了」，最後給出有優先級（high / medium / low）的改善建議，分類包括指令措辭、腳本工具、範例覆蓋、錯誤處理等。

Description 優化 ​

Skill 做得差不多之後，Skill Creator 還提供一個獨立的 description 優化流程，專門解決 undertrigger（觸發率不足）的問題。

它會先產生 20 個觸發評估查詢，其中 8–10 個「應該觸發」，8–10 個「不應該觸發」。這些查詢要夠具體，不能是「格式化這份資料」這種空泛描述，而是要像真實使用者會說的：帶有檔案路徑、公司名稱、個人背景的完整情境句。

你看過這些查詢、確認沒問題之後，優化腳本會跑起來：把查詢集 60% 用於訓練、40% 留作測試，每個查詢跑三次取觸發率均值，然後讓 Claude 開啟延伸思考（extended thinking）提出改進的 description，再重新評估，最多迭代五輪。最後用測試集的分數（而非訓練集）選出最佳版本，避免過擬合。

這個流程跑完，你會得到一個更新的 description，Skill Creator 會把前後版本和分數一起展示給你確認。

觸發機制的一個微妙點 ​

有一件事值得知道：Claude 只會在「自己處理不來」的任務上去查 Skill。太簡單的一步請求，例如「讀一下這個 PDF」，即使 description 完全吻合，也可能不觸發 Skill，因為 Claude 覺得自己直接處理就好了。 複雜、多步驟、或需要專業知識的任務才會可靠地觸發。所以測試案例要設計得夠有深度，才能真正測試出 description 的觸發品質。

寫好 Description 是關鍵 ​

測試幾個 Skill 下來，發現 description 寫得好不好，直接決定了 Skill 能不能在對的時機自動觸發。

Skill Creator 的文件裡提到一個觀察：Skill 的問題通常不是「亂觸發」，而是「沒有觸發」（undertrigger）。解法是讓 description 更「主動」，把所有相關的使用情境都明確列出來，即使使用者沒有用精確的關鍵字。

來看個例子，假設你在做一個 dashboard 生成 Skill：

❌ 太模糊，容易漏觸發：

description: 建立資料視覺化介面。

✅ 明確列出觸發情境：

description: This skill should be used when the user asks to build a dashboard or data visualization interface. Use this skill whenever the user mentions dashboards, internal metrics, data display, or wants to visualize any kind of company data, even if they don't explicitly say "dashboard".

另外，description 也值得說明不觸發的邊界，特別是當你的 Skill 和其他 Skill 的領域有重疊時，像 xlsx Skill 那樣明確排除「主要產出是 HTML 報表」的情況。

實作時踩過的坑 ​

1. name 和資料夾名稱要完全一致 ​

SKILL.md 裡的 name 欄位必須和資料夾名稱相同，否則 Skill 無法正確載入。

2. SKILL.md 要主動指向子目錄資源 ​

Claude 不會自動掃描 references/ 裡面有什麼，你需要在 SKILL.md 內文裡明確告訴它：

## 延伸資源

需要更詳細的規則時，參考：
- **`references/formatting-guide.md`** — 格式規範細節
- **`scripts/validate.py`** — 格式驗證腳本

忘記這步的話，那些精心準備的參考文件就白費了。

3. SKILL.md 內文不要塞太多 ​

SKILL.md 啟動時整個讀進 context，建議控制在 1,500 到 2,000 words 左右。 大量的參考資料、邊界情況說明、詳細範例，都搬到 references/ 目錄，按需載入。

4. description 不要超過 1024 字元 ​

description 雖然要寫得完整，但有字元上限，而且它一直佔用 context，重點放在「觸發情境」和「做什麼」就好，不需要把整個操作流程都塞進去。

自己從零寫一個 Skill ​

如果不用 Skill Creator，從零開始寫一個最簡單的 Skill 也不複雜，只要一個資料夾加一個 SKILL.md。這裡用一個 commit message 規範的 Skill 來示範整個流程。

先建立資料夾，名稱就是 Skill 的 name：

mkdir -p ~/.claude/skills/commit-helper

放在 ~/.claude/skills/ 下的 Skill 是個人全域的，在你的任何專案都有效。 如果只想在特定專案使用，可以放在專案根目錄的 .claude/skills/ 下，這個資料夾也可以 commit 進 repo 跟著版控。

不過有個反直覺的地方：當兩個層級存在同名 Skill 時，全域 Skill 的優先級高於專案 Skill。所以如果全域已經有一個 commit-helper，專案裡的同名版本不會生效。

接著建立 SKILL.md：

---
name: commit-helper
description: This skill should be used when the user wants to write a commit message,
  asks "how should I commit this", or is about to run git commit. Guides writing
  conventional commit messages following the Conventional Commits specification.
---

# Commit Message 指引

Follow the Conventional Commits format: `type(scope): description`

Types: feat, fix, docs, style, refactor, test, chore

Rules:
- Keep the subject line under 72 characters
- Use present tense ("add feature", not "added feature")
- No period at the end of the subject line
- Reference issue numbers when relevant: `fix(auth): correct token expiry (#123)`

Examples:
Input: 新增使用者登入功能，用 JWT 處理 token
Output: feat(auth): add JWT-based user authentication

Input: 修復購物車數量計算錯誤
Output: fix(cart): correct item quantity calculation

這樣就完成了。來拆解每個部分：

name 欄位對應資料夾名稱，必須完全一致。命名規則是小寫字母、數字和連字號，不能有大寫。

description 是 Claude 判斷要不要啟動這個 Skill 的唯一依據。它一直在 context 裡，所以要寫得精準但不囉嗦。這裡用第三人稱格式（This skill should be used when...），並且明確列出幾種觸發場景：「想寫 commit message」、「問 how should I commit this」、「要跑 git commit」。 這三種說法分別對應不同使用者的口頭習慣，都能觸發。

內文 用祈使句寫直接指令（Follow、Keep、Use），不用「你應該...」這樣的第二人稱。最後的 Examples 區塊很重要，因為 Input/Output 的對比比起文字描述更直接，Claude 更容易理解期望的輸出格式。

存好之後，開一個新的對話，之後只要說「幫我寫這次的 commit」，Claude 就會套用這套規則來建議 commit message，不用每次再解釋格式。

這個例子雖然簡單，但可以感受到把知識寫成 Skill 帶來的幾個具體好處。

第一個是一致性。以前每次請 Claude 寫 commit message，它的風格多少會有差異，有時用過去式、有時用中文。寫成 Skill 之後，每次都會照固定格式輸出，整個 git log 風格統一，之後 changelog 也好自動生成。

第二個是可以隨時疊加細節。需求可以一直增長：這個月 code review 之後發現 scope 的寫法有爭議，直接去改 SKILL.md 就好；下次加入新成員，把 Skill 資料夾複製給他，規範同步就完成了。 相比在 chat 裡每次貼上規則，Skill 是可以持續維護的。

第三個是不佔任何 context，除非真的要寫 commit。skills 的 description 雖然一直在，但它很短，只要不觸發，完整的 commit 規則不會干擾其他任何對話。 這和在 CLAUDE.md 裡寫死規則不一樣，CLAUDE.md 的內容從打開專案的那一刻起就全部進 context，不管當下的任務是不是跟 commit 有關。

Skills 和 CLAUDE.md 的差異 ​

用過 CLAUDE.md 的人可能會有個疑問：兩者都是給 Claude 的指令，到底有什麼不同？

簡單說：CLAUDE.md 是「這個專案的說明書」，Skills 是「你個人的工具包」。

舉個具體例子。這個部落格的 VitePress 目錄結構、frontmatter 格式、URL rewrite 邏輯，適合放在 CLAUDE.md，因為這些是這個 repo 特有的，換個專案就沒用了。但「寫 conventional commit」、「處理 Excel 檔案」、「套用品牌設計規範」這類知識，放在 Skills 更合適，因為在任何專案都能直接用。

兩者可以並存，互補。

CLAUDE.md 告訴 Claude「這個專案是什麼」，Skills 告訴 Claude「遇到 X 情況要怎麼做」。

團隊開發時怎麼共享 Skills ​

個人 Skill 寫好之後，下一個問題通常是：怎麼讓整個團隊都用到？

最直接的方式是把 Skills 放進專案的版本控制。在 repo 根目錄建立 .claude/skills/，把 Skill 資料夾放進去，commit 上去，之後 clone 這個 repo 的人就自動拿到這些 Skills。這特別適合和專案強相關的 Skill，例如「按照這個 codebase 的命名慣例產生 component」，放全域沒有意義，但放 repo 裡就能讓所有貢獻者共享同一套規則。

如果 Skill 不屬於某個特定 repo，而是整個組織都想用的通用工具，可以另外建一個獨立的 skills repo，然後用 plugin marketplace 的方式發佈：

/plugin marketplace add your-org/skills

這樣成員只要執行一次安裝，就能用到所有共享的 Skills，之後更新也只要在 repo 上改，不用每個人手動同步。anthropics/skills 就是這個模式。

第三個管道是把 Skill 打包成 .skill 檔案。Skill Creator 裡有一個 package_skill.py 腳本，可以把整個 Skill 資料夾打包成單一檔案，方便透過 Slack、email 或 PR 傳給同事，接收方直接安裝就好，不需要接觸 repo。

Skill 什麼時候該拆、什麼時候該合 ​

寫幾個 Skill 之後，難免會碰到這個問題：兩件事該放在同一個 Skill 裡，還是分開？

傾向分開的情況： 兩個功能的觸發時機根本不同，強行放在一起只會讓 description 越來越難寫，而且 Claude 可能因為無法精確判斷而誤觸發。例如「產生測試案例」和「跑 E2E 測試」，雖然都跟測試有關，但前者是在寫 code 的當下觸發，後者是準備部署的時候觸發，分開讓兩個 description 都能寫得更精準。另外，當 SKILL.md 的內文開始逼近 500 行，也是一個該考慮拆分的訊號，可以把其中一個領域移到獨立 Skill，再用 references/ 的方式讓它們按需互相參照。

傾向合在一起的情況： 兩個任務幾乎總是同時出現，每次用一個必然也用另一個，拆開反而增加維護成本。或者兩個任務共用大量的背景知識，合在一起可以讓這些知識只寫一次。

最實用的判斷方式是問：「這兩件事的觸發場景，我能用一句話說清楚嗎？」如果 description 需要塞很多「也可以用來做 Y，以及 Z」，通常就是一個應該拆分的訊號。

總結 ​

Skills 解決的是「重複解釋背景」的問題，把工作流程、規範或領域知識打包成可以隨時叫用的工具。Skill Creator 讓開發流程有了明確的迭代結構；project-level 的 .claude/skills/ 讓 Skills 可以跟著 repo 走、隨團隊共享；拆或合的判斷則回歸到一個問題：這個 Skill 的觸發時機，能不能用一句話說清楚。

如果你有某個任務需要每隔幾天就跟 Claude 重新解釋一遍，那大概就是值得做成 Skill 的候選。最小可行的 Skill 只需要一個資料夾加一個 SKILL.md，門檻很低，可以先試試看效果。

如果你是從 V1 就開始用 Vue 開發的朋友，一定知道 Vue.js 重要的核心特性就是只關注於 view layout 的呈現與 Components 系統，提供最小化且必要的功能給開發者。 其他的功能都可以自由選用第三方套件來完成，這也是為什麼被稱為「漸進式框架」的原因。

所以，如果我們用 Vue.js 來開發網站，且想使用 ajax 從遠端取得資源的時候，也許有些人會選用 jQuery ($.get / $.ajax ...等) ，也有些人會用 vue-resource 來做搭配。 早期官方推薦 vue-resource，到了 V2 官方的推薦 lib 改為 Axios 或是直接用原生 Fetch API。

不過很可惜，除了包山包海的 jQuery 之外，其他目前都還不支援 jsonp 這樣的做法。 也就是說，如果你的專案上需要用到 jsonp ，而且又不希望掛上一大包的 jQuery，這裡有個簡單的套件可以幫助你。 (順便自己筆記)

首先先安裝 jsonp 這個套件。

$ npm install jsonp --save

或

$ yarn add jsonp

然後在你的程式碼內這樣使用：

import jsonp from 'jsonp'

jsonp('http://www.example.com/foo', { /* DATA HERE */ },
  function (err, data) {
    if (err) {
      console.error(err.message);
    } else {
      console.log(data);
    }
  });

就可以了。

昨天看到 caesar 大大發表的 react & CSS 另類新選擇，講的其實是 styled-components + react 的 CSS 處理方案。 現今的幾個主流前端框架大多也有類似的做法，身為 Vue 的擁護者，這裡就來簡單說明一下 Vue 的處理方式。

先從早期的 CSS 管理方案開始說起吧。

CSS 預處理器、CSS 命名與架構學 ​

這麼多年來，CSS 的管理一直都是開發者的夢靨，很大的原因在於 CSS 的程式化與 JavaScript 相比其實是相對困難的， 尤其在於 JS 至少還有它的 scope 可以切分，而 CSS 在這點是相對弱勢的，所有的 CSS 樣式都是 global scoped。 如果頁面上的模組過多，管理起來更是難以維護。 嚴格來說，CSS 本身甚至都不能算是個程式語言。

所以，早期在程式面會有所謂的 LESS, SASS, Stylus 等這樣的工具，藉由 preprocessor (預處理器) 來做編譯，可以做到繼承、重用、複寫等功能。 另一方面，除了上述說的透過工具的預先編譯外，也有另一派人馬提倡的是，由 CSS 的命名學 / 架構論 來完成 CSS 模組的管理與複用。

在幾年前 (2014) ，小弟也有針對此類 CSS 方法論在前端社群聚會做分享，有興趣的朋友可以看下面這份投影片：

簡單來說，就是透過命名規則，來做到 CSS 架構的管理。 但大家都知道，訂出了 convention ，要是沒有嚴格檢查是否遵守，其實跟沒有一樣 XD

CSS Modules ​

所以後來出現了比較符合人性的 CSS Modules，透過工具來處理先前那些人工命名規範要做的事。 也就是說，由 Webpack 做了 BEM 的事情。 過去 BEM 是人工手動做，而 Webpack 是交給工具自動化做，用類似 Javascript module 的方式來處理 CSS。

講了大半個篇幅，終於要講到目前的主流： CSS in JS / styled-components 了。

CSS in JS / All in JS ​

CSS in JS 的概念最早是由 React 社群所提出，支持與不支持的兩派在社群當中也有著激烈的論戰。 我過去也是反對此類做法，但目前保持中立態度看待。 XD

過去我剛入行的時候，前輩大力倡導 HTML / CSS / JavaScript 三者負責的領域要切得越乾淨越好，簡單來說，inline-style 與 inline-script 都是禁止的。 一旦 inline-style 與 inline-script 寫得越多，程式碼就會像義大利麵般攪在一起難以維護。

而自從 component-based 的前端工具出現後，過去的原則漸漸被打破。 像 React ，就有下面這樣的寫法。

const style = {
  'color': 'red',
  'fontSize': '46px'
};

const clickHandler = () => alert('hi'); 

ReactDOM.render(
  <h1 style={style} onclick={clickHandler}>
     Hello, world!
  </h1>,
  document.getElementById('example')
);

將一個網頁元件 (H1) 的樣式、事件與結構，通通封裝在一份程式碼當中。

而 Vue 也有類似的做法，像 Vue 提供的 Vue 元件檔：

/* HTML */
<template>
  <h1 @click="clickHandler">{{ msg }}</h1>
</template>

/* script */
<script>
module.exports = {
  data: function() {
    return {
      msg: 'Hello, world!'
    }
  },
  methods:{
    clickHandler(){
      alert('hi');
    }
  }
}
</script>

/* scoped CSS */
<style scoped>
h1 {
  color: red;
  font-size: 46px;
}
</style>

在 Vue 元件檔，透過上面這樣的方式提供了一個 template (HTML)、script 以及帶有 scoped 的 style 樣式，也仍然可以保有過去 HTML、CSS 與 JS 分離的開發體驗。 但本質上仍是 all-in-JS 的變種語法糖就是了 XD

值得一提的是，當 style 標籤加上 scoped 屬性，那麼在 Vue 元件檔經過編譯後，會自動在元件上打上一個隨機的屬性，再透過 CSS Attribute Selector 的特性來做到 CSS scope 的切分，使得即便是在不同元件檔裡的 h1 也能有 CSS 樣式不互相干擾的效果。 當然開發起來，比起 JSX、或是 inline-style 等的方式，這種折衷的作法更合我的胃口 😁

上週在 Vue 社群圈有個令人興奮的熱門新聞: CodePen 可以支援 .vue 檔案了！

Check it out - you can use `.vue` files in CodePen Projects easily:https://t.co/Cd3Qr11xYQ pic.twitter.com/QvtIXxKRUk

— Chris Coyier (@chriscoyier) 2017年6月30日

身為使用 Vue 的開發者聽到這樣的消息當然感到相當開心，但同時也不禁感到好奇，CodePen 是如何做到不須透過 webpack 編譯 vue 檔案，就可以將 .vue 的 component 如實顯示到網頁中。

大家都知道，在網頁開發的世界中，前端是沒有秘密的。 打開了開發工具，才知道原來是透過 http-vue-loader 這個工具做到的。

http-vue-loader 這套工具可提供開發者直接在網頁環境中載入 .Vue File，無需透過 nodeJS 環境編譯，也不需要 Build 的步驟。

用法很簡單，首先在網頁上載入 Vue 與 http-vue-loader，如下

  <script src="https://unpkg.com/vue"></script>
  <script src="https://unpkg.com/http-vue-loader"></script>

接著，假設我們有一個 my-component.vue 的檔案：

<template>
    <div class="hello">Hello {{who}}</div>
</template>

<script>
module.exports = {
    data: function() {
        return {
            who: 'world'
        }
    }
}
</script>

<style>
.hello {
    background-color: #ffe;
}
</style>

那麼，我們就可以在 components 內透過 httpVueLoader 來載入我們的子元件：

<div id="my-app">
  <my-component></my-component>
</div>

<script type="text/javascript">
  new Vue({
    el: '#my-app',
    components: {
      'my-component': httpVueLoader('my-component.vue')
    }
  });
</script>

當然，httpVueLoader 也提供了類似 Vue.component('my-component', { ... }) 的宣告方式:

  httpVueLoaderRegister(Vue, 'my-component.vue');

  new Vue({
      components: [
          'my-component'
      },

或是將 httpVueLoader 當作 Plugin 來使用：

  Vue.use(httpVueLoader);

  new Vue({
    components: {
        'my-component': 'url:my-component.vue'
    },
    ...

甚至是 Array 的形式也可以：

    new Vue({
        components: [
            'url:my-component.vue'
        },
        ...

需要注意的是，httpVueLoader 目前僅支援 Vue 2 以上的版本，而作者也在專案內說明， httpVueLoader 只是提供一個簡便的測試與開發環境，方便開發者不需要透過繁複的編譯過程才能使用 vue file 進行開發。

若是要發佈到線上的專案，建議還是需要透過工具編譯打包，會有更好的效能以及更佳的支援度喔。

前幾天在 VueTW 活動結束後，有朋友來問：Vue 的開發環境能不能在 local 端建立 proxy 服務來解決跨域讀取後端的 API， 隔壁棚的 Angular CLI 好像有這功能，Vue-CLI 是不是也能做到。

(使用 Angular 開發專案的朋友，這裏推薦參考 Will 保哥這篇文章：如何在 Angular CLI 建立的 Angular 2 開發環境呼叫遠端 RESTful APIs)。

使用 Vue 的朋友，別著急莫緊張，Vue-CLI 也有提供類似功能喔。

注意： 本文撰寫時，使用 Node v8.0.0 / NPM 5.0.0 與 yarn v0.24.6，Vue-CLI 為 2.8.2。

實際執行情況可能因執行環境的版本會有所差異。

首先，第一步當然是先安裝 Vue-CLI:

• NPM:

$ npm install -g vue-cli

• YARN:

$ yarn global add vue-cli

安裝好了之後，接著我們透過 Vue-CLI 來建立新專案，樣板的部分我們選用 webpack，然後執行：

 $ vue init webpack test

上面指令中的 test 是專案名稱，這裏請自行取名替換成你要的名稱。 為了節省時間，範例裡只安裝必要的套件，其他選項可依你的需要選用安裝。

接著切換至新增好的目錄後，安裝相關套件。

• NPM:

$ cd test
$ npm i
$ npm run dev

• YARN:

$ cd test
$ yarn
$ yarn dev

安裝完成並執行 dev-server 之後，應該會自動開啟瀏覽器 http://localhost:8080/ 並看到畫面：

到目前為止已經建立起一個基本的 Vue 專案了。

接著，我們以 Data.Taipei 的 Youbike臺北市公共自行車即時資訊 作為本次的範例。

VueJS 的核心並沒有提供 Ajax 這樣的功能，所以在發送遠端請求的時候，我們要先安裝 axios 這樣的套件來協助我們，當然你想要用 jQuery AJAX 或是 Fetch API 也是 ok 的。

安裝方式：

• NPM:

$ npm install --save axios vue-axios

• YARN:

$ yarn add axios vue-axios

安裝完畢後，我們打開 App.vue 檔，並加上 import 以及 Vue.use 來載入外部的套件：

import Vue from 'vue'
import axios from 'axios'
import VueAxios from 'vue-axios'

Vue.use(VueAxios, axios)

接著，我們在 Vue 實體的 create hook 裡面來送出 GET 請求試試：

  created(){
    Vue.axios.get('http://data.taipei/youbike').then((response) => {
      console.log(response.data)
    })
  },

像這樣：

存檔後再次開啟 dev-server，毫無意外地，你應該會看到像這樣的錯誤：

因為遠端的 API 並沒有開啟 CORS 協定，所以我們無法跨域存取這個資源。 不過還好，Vue-CLI 的 dev server 整合了 http-proxy-middleware。 這個工具替我們在 local 端建立一個代理層，讓我們在開發時期就可以很方便的呼叫遠端的 HTTP API。

套件的部分，Vue-CLI 都幫我們準備好了，接著打開專案下 config/index.js 這個檔案，然後編輯 proxyTable: {} 的部分。

修改 config/index.js 如下：

  proxyTable: {
    '/data': {                        // 自訂 local 端的位置
      target: 'http://data.taipei/',  // 遠端 URL Domain
      changeOrigin: true,
      pathRewrite: {
        '^/data': ''
      }
    }
  },

經過這樣設定後，http://data.taipei/ 網域內的資源，都會在 local 端以 /data 的形式被代理，也就是說，像 http://data.taipei/youbike 這樣的遠端資源，我們就可以在 local 端用 /data/youbike 來取得。

所以，再回到 App.vue，這裏將原本的 http://data.taipei/youbike 改成 /data/youbike，像這樣：

  created(){
    Vue.axios.get('/data/youbike').then((response) => {
      console.log(response.data)
    })
  },

接著，記得要重開 dev-server，執行 $ npm run dev 或 $ yarn dev 。

最後，在網頁讀取完成後，打開 console 就可以看到，遠端的 youbike 資訊已經可以正確取得囉。

詳細的 http-proxy-middleware 設定可以參考這裡：

• https://github.com/chimurai/http-proxy-middleware#http-proxy-middleware-options
• https://vuejs-templates.github.io/webpack/proxy.html

延續上回 [VueJS] 在 v-for 列表中透過 filter 完成搜尋與分頁的功能 這篇的說明， 這次我們來看看，自從 VueJS 更新到 V2 拿掉了內建的 filterBy、limitBy 等好用的 filter 後，要如何修改才能做到分頁的功能。

首先看到原本 V1 的範例，是這樣的，這裡透過 limitBy countOfPage pageStart 來完成分頁，如下：

  <tr v-for="r in rows 
    | filterBy filter_name in 'name' 

---

    | recordLength 'filteredRowCount' 
    | limitBy countOfPage pageStart ">
    <td>{{ (currPage-1) * countOfPage + $index + 1 }}</td>
    <td>{{ r.name }}</td>
    <td>{{ r.age }}</td>
    <td>{{ r.gender }}</td>
  </tr>

因為從 V2 開始，filterBy 、 limitBy 、 orderBy 都沒有了，所以我們直接移除掉：

  <tr v-for="r in rows">
    <td>{{ (currPage-1) * countOfPage + $index + 1 }}</td>
    <td>{{ r.name }}</td>
    <td>{{ r.age }}</td>
    <td>{{ r.gender }}</td>
  </tr>

這時應該會出現錯誤，因為 $index 的寫法也更新了，所以改一下 v-for 的內容：

  <tr v-for="(r, index) in rows">
    <td>{{ (currPage-1) * countOfPage + index + 1 }}</td>
    <td>{{ r.name }}</td>
    <td>{{ r.age }}</td>
    <td>{{ r.gender }}</td>
  </tr>

到目前為止，至少可以看到程式正常運作，但相對地分頁與搜尋的功能也沒了，所以接下來先來處理搜尋的部份。

首先，在 computed 屬性，我們新增一個叫做 filteredRows 的屬性，用來處理與 filter_name 比對後的結果：

  filteredRows: function(){
    // 因為 JavaScript 的 filter 有分大小寫，
    // 所以這裡將 filter_name 與 rows[n].name 通通轉小寫方便比對。
    var filter_name = this.filter_name.toLowerCase();
    
    // 如果 filter_name 有內容，回傳過濾後的資料，否則將原本的 rows 回傳。
    return ( this.filter_name.trim() !== '' ) ? 
        this.rows.filter(function(d){ return d.name.toLowerCase().indexOf(filter_name) > -1; }) : 
        this.rows;
  },

然後將 html 內的 rows 換成 filteredRows

  <tr v-for="(r, index) in filteredRows">
    <td>{{ (currPage-1) * countOfPage + index + 1 }}</td>
    <td>{{ r.name }}</td>
    <td>{{ r.age }}</td>
    <td>{{ r.gender }}</td>
  </tr>

name 搜尋的部份到這裡就算完成了，接著回頭來處理分頁。

處理分頁之前，先看到底下的分頁按鈕， n in range 在 V2 的寫法也有不同，原本的索引會由 0 開始，但從 V2 開始會由 1 開始，所以需要把原本的：

<div class="pagination">
    <ul>
    <li v-bind:class="{'disabled': (currPage === 1)}" 
        @click.prevent="setPage(currPage-1)"><a href="#">Prev</a></li>
    <li v-for="n in totalPage"
        v-bind:class="{'active': (currPage === (n+1))}" 
        @click.prevent="setPage(n+1)"><a href="#">{{n+1}}</a></li>
    <li v-bind:class="{'disabled': (currPage === totalPage)}" 
        @click.prevent="setPage(currPage+1)"><a href="#">Next</a></li>
    </ul>
</div>

改寫成：

<div class="pagination">
    <ul>
    <li v-bind:class="{'disabled': (currPage === 1)}" 
        @click.prevent="setPage(currPage-1)"><a href="#">Prev</a></li>
    <li v-for="n in totalPage"
        v-bind:class="{'active': (currPage === (n))}" 
        @click.prevent="setPage(n)"><a href="#">{{n}}</a></li>
    <li v-bind:class="{'disabled': (currPage === totalPage)}" 
        @click.prevent="setPage(currPage+1)"><a href="#">Next</a></li>
    </ul>
</div>

顯示就會是正常的從 1 開始了。

再來處理顯示筆數時，需要的會有 pageStart 、 countOfPage 與 totalPage 這三個部分，其中 totalPage 會跟先前提到的 搜尋 比較有關係，因為總頁數不對，算出來的分頁也會有問題。

原本的 totalPage 長這樣：

  totalPage: function(){
    if( this.filter_name.trim() === '' ) {
        return Math.ceil(this.rows.length / this.countOfPage);
    }
    else{
        return Math.ceil(this.filteredRowCount / this.countOfPage);
    }
  }

因為資料在先前都交給 filteredRows 處理了，所以可以改寫成

  totalPage: function(){
    return Math.ceil(this.filteredRows.length / this.countOfPage);
  }

實際執行會發現最底下的分頁按鈕已經會隨著 Filter 的結果筆數而有所不同：

最後，再回到處理每頁顯示資料量的部分。

在沒有了 limitBy 之後，顯示筆數的部份我們可以透過 JavaScript 的 slice 來處理，當然也可以寫在 computed 屬性。 但這個範例只是單純在顯示作切換，所以可以直接寫在 view 上，像這樣將 filteredRows 改寫成 filteredRows.slice(pageStart, pageStart + countOfPage)：

對 slice 不熟的朋友可參考： MDN: Array.prototype.slice()

  <tr v-for="(r, index) in filteredRows.slice(pageStart, pageStart + countOfPage)">
    <td>{{ (currPage-1) * countOfPage + index + 1 }}</td>
    <td>{{ r.name }}</td>
    <td>{{ r.age }}</td>
    <td>{{ r.gender }}</td>
  </tr>

就完成了從 V1 更新到 V2 的過程了。

完整更新的範例可在此參考：
JS Bin on jsbin.com

相信大家都知道 Google Map 在多年以前就開放了「街景檢視」這樣的服務，當然 Google Map API 也提供了給開發者使用相關的 API 服務：「Street View Service」來開發地圖的應用。

除了原本在 Google Map 上面就有的街景檢視之外，透過 Street View API 開發者可以自由地在街景地圖上加入標示項，作法就跟平時在地圖上加入 marker 一樣：

  var marker = new google.maps.Marker({
    map: map,

---

    icon: '//chart.googleapis.com/chart?chst=d_map_pin_icon&chld=train|ffff00',
    position: {lat: 25.051269, lng: 121.512386}
  });

如下圖黃色 icon：

這個時候我們切換成街景檢視的時候，你會發現還需要自己手動調整角度才能找到 icon 的位置：
(如下地圖，可按右下角按鈕切換街景)

需要將視角往左邊移動後才能找到 icon 的位置。

那麼，是否有更好的方式可以讓 Google 街景可以自動判斷視角方向呢？

有的，可以利用 Google Map 所提供的 Geometry Library 來協助我們計算兩點之間的角度。

在 Google Maps API 內，「方向」是以與正北的角度來定義，也就是從正北 (0 度) 的順時針方向計算的角度，可以使用 computeHeading() 方法，將兩個 from 和 to 的 LatLng 物件傳遞給它，來計算兩個位置之間的方向。

如下：

var heading = google.maps.geometry.spherical.computeHeading(from_latLng, target_latlng);

google.maps.geometry.spherical.computeHeading( ) 就會回傳兩點之間的角度，接著，我們就可以透過 panorama.setPov({ heading: heading, pitch: 0 }); 來指定街景的預設角度了。

Vue 提供了相當好用的 debug 工具 (Chrome 套件)， Vue.js devtools，在安裝之後當你用 Chrome 開啟 Vue 專案時，Chrome 的開發者工具會多出一個 Vue 的 Tab，然後把 Vue Instance 裡的屬性通通列出來：

在預設開啟 debug mode 時，按下 Vue devtools 的 icon 你會看到這樣畫面：

這時候打開 Chrome 開發者工具， vue 專案中所有 Instance 的屬性資料通通一覽無遺。

但是當專案完成要上線的時候，就應該要將 debug mode 關閉，尤其在屬性可能會存有較為機敏性資料的時候。 關閉的方式也很簡單，加上這兩行就可以了：

Vue.config.debug = false;
Vue.config.devtools = false;

關閉後，再開啟 Vue 專案，雖然 icon 偵測到 Vue.js 會亮起來，但是你會看到這樣訊息：

這時候 Chrome 開發者工具的 Vue tab 就不會出現了。

但是，在建置專案的時候，常常會忘記手動調整 debug mode，導致上線的專案會是開啟 debug mode 的版本， 是否可以在 webpack 啟動的時候自動判斷目前環境呢？

以 Vue-CLI 提供的 package.json 為例，他提供了兩個預設的 scripts， dev 用在開發專案時使用，而 build 則用於建置 production 使用：

圖中可以看到，在 build 模式下多了 NODE_ENV=production 這個參數。

這時候我們就可以利用 NODE_ENV 這個參數來判斷使否開啟 debug mode：

import Vue from 'vue'
import App from './App.vue'

const isDebug_mode = process.env.NODE_ENV !== 'production';

Vue.config.debug = isDebug_mode;
Vue.config.devtools = isDebug_mode;

這樣 Vue.config.debug 的版本就會自動依照執行階段的不同而有不同的設定了。

這兩天 JavaScript 圈子的最大新聞應該就是 Facebook 發布了一套新的 JavaScript 套件管理工具 Yarn，感覺來勢洶洶勢不可擋。 實際花了一點時間試用，表現的確也比過去 npm 好很多，尤其過去 npm install 速度過慢，套件相依衝突的問題，目前在 Yarn 還沒遇到。 即使是剛開始 yarn run scripts 無法帶入參數的問題，在發布的第二天也快速地更新 (v0.15.1) 解決了。 👍

有關 Yarn 介紹的部分，已經有其他前輩分享了，推薦可以看看這篇 取代 npm 的新利器 Yarn。

既然 Yarn 號稱可以用來取代 npm，那麼身為 Vue 的愛好者，也想馬上來試試 Vue-cli 這套 Vue 的樣板工具包是否也可以透過 yarn 來單獨執行。

既然要取代 npm，那麼第一件事情就是把 npm 整包幹掉，關於刪掉 npm modules 的過程我是參考 stackoverflow 的這篇: Command to remove all npm modules globally?，但實際上 Yarn 與 npm 是可以和平共存的，不一定要把 npm 幹掉才能跑 Yarn ，這裡只是想簡單做個試驗，啾咪 ^.<

然後安裝 Yarn。 執行 curl -o- -L https://yarnpkg.com/install.sh | bash 即可。

第一步：安裝 vue-cli ​

很簡單，把原本的 npm install -g vue-cli 改成 yarn global add vue-cli 就可以了。執行的時候像這樣：

而安裝完畢後，執行 yarn vue 應該可以看到這樣的畫面。

每執行完一個指令還會告訴你它跑了多久喔，非常囂張 (誤)。

第二步：初始化 Vue 專案 ​

接著，就來初始化我們的 Vue 專案。 Vue-cli 這個 scaffolding 工具官方目前提供了幾種 template 讓開發者自行選擇， 像是大家常見的 webpack、browserify 都有。當然也可以挑選什麼都沒有的 simple: 就是最基本的 Vue 專案這樣。 如果想更詳細了解各種 template 細節的話，可以到 vue-templates 的 Repo 去看。

這裡我就選擇拿「webpack-simple」當範例。

執行 yarn vue init webpack-simple my-project

因為 VueJS 目前已經發佈至 2.0 版了，所以你會看到 Vue-cli 很貼心地提醒你現在安裝的是 2.0 的版本。 若你想安裝的是 1.x 版本的話，可以改成
yarn vue init webpack-simple#1.0 my-project 即可。

然後，Vue-cli 會幫我們建立一個新目錄 my-project。

透過 cd my-project 切換到新專案目錄後，我們將原本的 npm install 改成直接執行 yarn 即可。

第三步：啟動並執行 vue 專案 ​

最後，直接執行 yarn run dev 應該會看到像這樣的畫面。

打開你的瀏覽器連到 http://localhost:8080/ 看到 Hello Vue! 的字樣就代表成功執行囉！

最近在爬 Vue 的原始碼的時候，意外發現兩個沒看過的 event：compositionstart 與 compositionend。 查了一下 MDN 才發現這些叫做「Composition Events」的 event 是從 DOM Level 3 之後才新增的。

介紹 Composition Events 之前先來談談 DOM API 過去對輸入框偵測變化的幾個方式。

一般來說，常見的表單輸入框如: <input type="text"> 如果要動態監聽輸入框的文字變化時， 大多會透過監聽 keydown、keypress、keyup 等鍵盤事件來判斷 value 是否變動，但如果是透過複製貼上之類的操作，就無法透過鍵盤事件來判斷。

而即使是 change 事件則是要在使用者改變內容，且焦點離開輸入框的前一刻才會被觸發。

所以後來有了 input 事件， input 事件會在輸入框的內容被改變時即時觸發，確實也解決了過去在 onChange 以及鍵盤相關事件帶來的不少問題。

新的問題來了！

通常像這樣的搜尋框，我們會用類似 autocomplete 的方式給使用者搜尋建議 (以 google 為例)：

如上圖，在輸入中文的時候，通常會需要透過注音之類的輸入法來做拼字，但是在大部分的情況下，自動給「注音符號」或是「拼音文字」搜尋建議是沒有太大意義的。

回到主題。這個時候就需要透過 Composition Events 來為輸入框做增強。 透過 Composition Events 我們可以觀察使用者在輸入框內開啟輸入法 (Input Method Editor, IME) 時，組字或選字的狀態。

Composition Events 提供三個事件給開發者監聽：分別是 compositionstart 、 compositionend ，以及 compositionupdate。

• compositionstart: 輸入框內開啟輸入法，且正在拼字時觸發。
• compositionupdate:輸入框內開啟輸入法，且正在拼字或選字時更改了內容時觸發。
• compositionend: 輸入框內開啟輸入法，拼字或選字完成，正要送出至輸入框時觸發。

可以看到，如果要確認使用者輸入完成並送出文字時，可以透過 compositionend 來做最後確認。
附上 JSBin Demo: http://jsbin.com/mofepimiqo/1/edit?js,console,output

最後則是大家都很關心的瀏覽器支援度。以目前來說，mobile 平台上可能還不太 ok，但是 Desktop 平台上表現看起來相當不錯，可以大膽地使用囉。

參考資料：

大部分資料是從這裡來的: Vue 1.0.0 binding syntax cheatsheet，再加上對 Vue 2.0 補充的部分。

<!-- normal directive -->
<div v-if="ok"></div>

<!-- directive with argument -->
<button v-on:click="onClick"></button>

---


<!-- v-on with argument + key modifier -->
<input v-on:keyup.enter="handleEnter">

<!-- literal modifier: pass literal string to directive for Vue 1.x, -->
<!-- but deprecated in 2.0 -->
<a v-link.literal="/a/b/c"></a>

<!-- binding an attribute with v-bind -->
<img v-bind:src="imgSrc">
<a v-bind:href="baseURL + '/path'">

<!-- shorthand: colon for v-bind -->
<img :src="imgSrc">
<a :href="baseURL + '/path'">

<!-- shorthand: @ for v-on -->
<button @click="onClick"></button>

<!-- key modifier -->
<input @keyup.enter="handleEnter">

<!-- stop/prevent modifier -->
<button @click.stop="onClick"></button>
<form @submit.prevent></form>

<!-- props for Vue 1.x -->
<!-- .once and .sync are deprecated in 2.0 -->
<my-comp
  prop="literal string"
  v-bind:prop="defaultOneWay"
  v-bind:prop.sync="twoWay"
  v-bind:prop.once="oneTime">
</my-comp>

<!-- props with one time binding for Vue 2.0 -->
<my-comp
  prop="literal string"
  v-bind:prop="defaultOneWay"
  v-once>
</my-comp>

<!-- component with props and custom events, in shorthand -->
<item-list
  :items="items"
  :open.sync="isListOpen"
  @ready="onItemsReady"
  @update="onItemsUpdate">
</item-list>

<!-- v-el and v-ref now just use the argument -->

<!-- registers vm.$refs.child for Vue 1.x -->
<comp v-ref:child></comp>

<!-- registers vm.$refs.child for Vue 2.0 -->
<comp ref:child></comp>

<!-- registers vm.$els.node for Vue 1.x, but deprecated in 2.0 -->
<div v-el:node></div>

狂賀！ Vue 2.0 終於正式發佈！

關於 Vue 2.0 的新特性，作者也在官方 Blog - Vue 2.0 is Here! (中文翻譯) 一文中敘述地相當詳細，這裡就不多說。

如果你也與我一樣是從 V1 就開始接觸的開發者，一定都知道 VueJS 最核心的一部分是 Component，而 Component 是由實體 (Vue Instance) 來實作。 在這篇文章，我們就來談談 Vue 1.x 與 2.x 元件實體的差異。

Vue 2.0 元件實體註冊 ​

像上面這樣的網站，我們可以將它抽象化為一棵「元件樹」，而每個元件樹都會有個根節點，或稱為根實體 (root Vue instance)。

那麼，每個 Vue 元件樹的根實體其實是透過 Vue 這個建構函式所產生：

var vm = new Vue({
  // options
});

將 Vue 元件與實體 DOM 結合的方式有兩種，一種是直接寫在 el option 內：

var vm = new Vue({
  el: '#app'
});

而另一種方式則是透過 $mount 來指定節點：

var vm = new Vue({
  // options without 'el'
});

vm.$mount('#app');

這部分跟 Vue 1.x 的註冊是完全一樣的，但是需要注意的是，在 vue 1.x 允許開發者以 <body> 或 <html> 作為根實體的掛載點， 但到了 VueJS 2.0 後，只能透過 獨立的節點掛載 ，如: div 等。 否則會產生錯誤，警告訊息如下：

“Do not mount Vue to <html> or <body> - mount to normal elements instead.“

換成用獨立的 DOM 節點，如 <div id="app"></div>，就可以正常運作了。

Vue 2.0 元件實體的生命週期 ​

基本上 Vue 2.0 實體生命週期中，大部分的階段都與 Vue 1.x 是一樣的，最大的不同在於 lifecycle hook 名稱的改變，以及在元件被掛載 mounted 之後，還新增了 beforeUpdate 以及 updated 這兩組偵測更新的 hook。

vue 1.x 的 init 變成 beforeCreate ， beforeCompiled 改為 beforeMount。 而原本的 complied 與 ready 則是統一收斂成 mounted。

另外需要注意的是，若元件本身是透過 server-side rendering 的話，除了 beforeCreate 以及 created 以外的所有 hook 都不會被呼叫 (參考資料)。

有關元件 V-DOM 的重新渲染與更新後面再提，其他部分則與 Vue 1.x 大同小異。

在大部分情況下，透過元件的 template 屬性，或是直接寫在 HTML 中就已經足夠操作你的元件了。 不過若是你想完全透過 JavaScript 來操作你的元件，那麼可以使用 render 這個 function 直接來寫底層的 virtual-DOM 來取代 template 屬性。 VueJS 2.0 的 virtual DOM 機制，是採用 snabbdom 這個 virtual DOM 的 library 來實作的。

可以使用 createElement 這個 function 來建立你的元件內容：

// @returns {VNode}
createElement(
  // {String | Object | Function}
  // An HTML tag name, component options, or function
  // returning one of these. Required.
  'div',
  // {Object}
  // A data object corresponding to the attributes
  // you would use in a template. Optional.
  {
    // (see details in the next section below)
  },
  // {String | Array}
  // Children VNodes. Optional.
  [
    createElement('h1', 'hello world')
    createElement(MyComponent, {
      props: {
        someProp: 'foo'
      }
    }),
    'bar'
  ]
)

官方也提供了一個完整的 render function 範例：

var getChildrenTextContent = function (children) {
  return children.map(function (node) {
    return node.children
      ? getChildrenTextContent(node.children)
      : node.text
  }).join('')
}
Vue.component('anchored-heading', {
  render: function (createElement) {
    // create kebabCase id
    var headingId = getChildrenTextContent(this.$slots.default)
      .toLowerCase()
      .replace(/\W+/g, '-')
      .replace(/(^\-|\-$)/g, '')

    return createElement(
      'h' + this.level,
      [
        createElement('a', {
          attrs: {
            name: headingId,
            href: '#' + headingId
          }
        }, this.$slots.default)
      ]
    )
  },
  props: {
    level: {
      type: Number,
      required: true
    }
  }
})

當然，你可能跟我一樣覺得一層又一層的 createElement 看了總是讓人厭煩，你也可以透過這個 Plugin: babel-plugin-transform-vue-jsx，來做 JSX 語法的轉換，如果你曾是 react 應用程式的開發者，應該對 JSX 語法不陌生。 寫起來會像這樣：

import AnchoredHeading from './AnchoredHeading.vue'

new Vue({
  el: '#demo',
  render (h) {
    return (
      <AnchoredHeading level={1}>
        <span>Hello</span> world!
      </AnchoredHeading>
    )
  }
})

在預設情況中，VueJS 2.0 會將 template 內的 HTML 透過 parse 轉換成 AST，再自動轉換優化成 render function 去建立 virtual DOM。 在建立 virtual DOM 之後，透過 observe 機制與資料進行綁定，再 compile 成實體的 DOM 並渲染至網頁上：

前面說過，VueJS 2.0 會將 template 內的 HTML 自動編譯成 render function，下面這是官方文件以 Vue.compile 提供的 demo：

<!-- template -->
<div>
  <h1>I'm a template!</h1>
  <p v-if="message">
    {{ message }}
  </p>
  <p v-else>
    No message.
  </p>
</div>

// render:
function anonymous() {
  with(this){return _h('div',[_m(0),(message)?_h('p',[_s(message)]):_h('p',["No message."])])}
}

// staticRenderFns:
_m(0): function anonymous() {
  with(this){return _h('h1',["I'm a template!"])}
}

最後，我們來看看元件內狀態的追蹤變化。有寫過 VueJS 1.x 的朋友應該知道，元件實體內有個 option 叫 data， 這個 data 物件就是用來存放元件內狀態/資料的地方。

與 Vue 1.x 相同的地方是，data 物件透過 Object.defineProperty() 來為元件內各屬性設定 「getter」與「setter」。 就在 data 屬性被存取修改時，會透過 getter/setter 來通知物件內屬性的變化，當先前設定好的 setter 被呼叫的時候，會去觸發 watcher 重新計算，也就會導致 DOM 的更新與重新渲染。

與 Vue 1.x 不同的是，Vue 1.x 是透過 directive 來重新渲染 DOM 內容：

而 Vue 2.0 在通知 watcher 更新時，會去呼叫前面介紹的 「render function」與更新後的 data 去做更新後再次渲染，概念與 1.x 大致相同。 但更新 DOM 的手法不同，減少了不必要的比對，也因此大幅度提升了效能。

Vue JS 自今年四月 (2016/04) 發佈 Vue 2.0 preview 版本至今也有五個月了，在新舊版本的交替之中，開發者最關心的一定是「我的專案能不能升到 Vue 2.0」、「升上去會不會爆」、「專案該用那個版本來開發」，「聽說隔壁那個 ng 升級幾乎等於砍掉重練」 之類的問題。

不過幸好，Vue 1.0 與 Vue 2.0 有 90% 的 API 是相同的，過去在 Vue 1.x 的核心概念到 Vue 2.0 一樣可以沿用，而且又多了些新特性。

這裡有一份官方的升級建議，有點長，如果沒有耐心讀的話，沒關係，這裡介紹你好物:
Vue migration helper。

傳說中的升級小幫手 Vue migration helper: https://github.com/vuejs/vue-migration-helper

使用方式很簡單，打開 terminal 透過 npm 安裝後，在你的專案目錄下執行 vue-migration-helper，小幫手就會幫你掃描整份專案，然後給你修改的建議了。

完整的安裝與使用方式：

# install
$ npm install --global git://github.com/vuejs/vue-migration-helper.git

# navigate to a Vue 1.x project directory
$ cd path/to/my-vue-project

# scan all files in the current directory
$ vue-migration-helper

拿之前的某份範例試試，就像這樣：

花惹發，滿坑滿谷的升級建議

依照 migration helper 給的建議一一修正後，再次執行專案，檢查一下 console，是否有噴錯，如果沒有錯誤，那麼專案的升級也就差不多了。

不過要注意，目前 Vue migration helper 還在 beta 階段，如果未來要再更新至新版的話，直接再次執行 npm install --global git://github.com/vuejs/vue-migration-helper.git 重新安裝一次就好。

最後，鄉親啊，如果你正要開啟新專案，建議現在就可以直接從 Vue 2.0 進入喔！

有用過 Vue.js 開發的朋友一定知道它提供的 filter 功能十分強大，在 v-for 列表中使用 filterBy 可以在一行內完成列表搜尋的功能：

  <div id="filter-by-example">
    <input v-model="n">
    <ul>

---

      <!-- 透過 input 欄位的 v-model n 與 user.name 做模糊比對 -->
      <li v-for="user in users | filterBy n in 'name'">
        {{ user.name }}
      </li>
    </ul>
  </div>

若是要限制顯示的筆數也能用 limitBy 做到，進而完成分頁的功能。

  <!-- 只顯示前 10 個元素 -->
  <div v-for="item in items | limitBy 10"></div>

  <!-- 顯示第 5 到 15 筆元素-->
  <div v-for="item in items | limitBy 10 5"></div>

這次遇到的問題是這樣的，如果我們想要同時完成「搜尋」與「分頁」的需求，光靠 filterBy 與 limitBy 就不是那麼容易做到，還好 Vue.js 提供了自訂 filter 的功能：先用 filterBy 過濾，再透過自訂 recordLength 記錄過濾後的資料數量，最後再用 limitBy 搭配頁籤切換頁面。 小心 filter 的順序，filter 會依序執行，然後再繼續下個 filter。

  <tr v-for=" r in rows
               | filterBy filter_name in 'name'
               | recordLength 'filteredRowCount'
               | limitBy countOfPage pageStart ">
      <td>......</td>
  </tr>

然後是自定的 filter recordLength： result 代表傳入的資料， key 則是從 view 帶入的參數，這個範例是 filteredRowCount。

這裡透過 vm.$set 來將過濾後的數量指定至 vue 實體，以便可以直接在 Vue 實體使用。

  Vue.filter('recordLength', function (result, key) {
    this.$set(key, result.length);
    return result;
  });

最後在頁籤的部分，我們就可以簡單透過 filter_name 欄位是否空白來切換是否透過 filteredRowCount 計算總頁數:

  totalPage: function(){
    if( this.filter_name.trim() === '' ) {
      return Math.ceil(this.rows.length / this.countOfPage);
    }
    else{
      return Math.ceil(this.filteredRowCount / this.countOfPage);
    }
  }

完整的 demo 如下:

JS Bin on jsbin.com

利用 d3-js 我們可以很輕易地產生我們想要的圖表，以最常見的長條圖為例，只要透過 scale (比例尺) 與 axis (軸線)，再加上一點 SVG 的基礎知識，像這樣的長條圖一下子就可以生成。

[Code]

但是，像這樣尺寸的圖表，往往都會因為太大而不適合在手機螢幕上呈現。還好 SVG 有著向量圖形的特性，可以自由縮放，這篇就來簡單介紹 d3-js 的長條圖如何也能做出 rwd 的效果。

在上面的程式碼內，我們可以看到，原先設定的寬高是寫死的 960 與 500 (未扣除邊界)

  var margin = 40,
      width = 960 - margin*2,
      height = 500 - margin*2;

所以第一步，我們先將外層的 .content 元素設定成寬高 100%，然後把原先寫死的寬高改成由程式去抓取實際的寬高

.content{
  display: block;
  width: 100%;
  height: 100%;
  min-width: 300px;
  max-width: 960px;
  max-height: 500px;
  overflow: hidden;
}

 // 將尺寸改成即時取得的寬高
 width = parseInt(d3.select(".content").style("width"), 10) - margin*2;
 height = parseInt(d3.select(".content").style("height"), 10) - margin*2;