vibeClaudeMods · 實作教學

Claude Code 個人 Mod
製作教學:本機載入與開發測試

vibeClaudeMods 把常用操作按鈕與用量、快取資訊放進 Claude Code。這篇用實際畫面說明各項功能與 VS Code、終端機、官方 App 的適用方式,再帶你製作小型個人 Mod,完成本機載入與開發測試。

Luke HouJavaScript 入門Windows/macOS發布
Claude Code 個人 Mod 教學插畫,呈現模組製作、本機載入與開發測試流程。
  1. 01建立檔案manifest + hooks
  2. 02靜態驗證plugin validate
  3. 03本機載入--plugin-dir
  4. 04修改重載hot reload
  5. 05離線測試plugin test
本篇目錄與範例下載下載計數器範例 ↓

讀者與完成目標

這篇適合已經能使用 Claude Code、會開啟終端機,也能用文字編輯器修改檔案的讀者。範例使用少量 JavaScript;進階的設定登記會用到 Python。

你會先看懂五個按鈕與 ledger 資訊的用途,並能依實際使用介面選擇載入方式。完成實作後,你會有一個 my-tool-counter 資料夾,能在 Claude Code 輸入 /my-tool-count 查看工具呼叫嘗試次數,並知道如何修改、重載與測試它。範例可從本頁目錄下方下載,解壓縮後對照三個主要檔案閱讀。

實際畫面與三種使用介面

這套 Mods 可用在 VS Code 的 Claude Code 擴充、終端機,以及 Claude 官方 App 的 Code 頁籤。功能會依所在介面顯示;載入同一份程式,也要分別確認按鈕與狀態列。

VS Code 擴充的實際畫面

下面是 VS Code 原生 Claude Code 面板。上排是 quick-actions 的五個按鈕;下排標示 ledger plugin 的資訊列,來自 today-cost 這個資料夾中的 Mod。

VS Code 的 Claude Code 面板,上方有 effort、Handoff、Resume、Compact、Clear 五個按鈕,下方 ledger 顯示今日用量、工作階段數、本次用量、上下文與快取狀態。
圖 1|VS Code 擴充的實際畫面。可對照五個操作按鈕與 ledger 資訊列;窄螢幕可左右捲動,點圖可看原尺寸。

圖中的 today $0.00 · 3 sessions、this $0.00、–/1M 與 cache –,依序對應今日帳本、本次工作階段、上下文與快取資訊。它們的計算範圍與缺值狀態,會在下方逐項說明。

終端機的實際畫面

終端機也能顯示同一組 quick-actions 按鈕,外觀會跟著終端機的字型、寬度與 Claude Code 介面呈現。

終端機中的 Claude Code,頂端顯示 effort、Handoff、Resume、Compact、Clear 五個 quick-actions 按鈕,下方有更新通知、輸入區及既有的專案與模型狀態資訊。
圖 2|終端機的實際畫面。quick-actions 對應最上方五個按鈕;黃色更新提示、底部路徑、分支、模型與時鐘,沿用 Claude Code 與既有終端機設定。

三種介面的功能與載入差異

使用介面 quick-actions today-cost/ledger 載入與確認方式
終端機執行 claude,含 VS Code 內建終端機 可顯示五個按鈕 目前程式在純終端機模式停用;終端機另可使用既有 Coralline 狀態列 開發時用 --plugin-dir;常用時可登記來源,再開新工作階段。
VS Code 原生 Claude Code 擴充面板 可顯示五個按鈕 可顯示;圖 1 即為這個介面 使用這個宿主實際讀取的設定登記來源,再開新對話確認;擴充有自己的 Claude Code 版本。
Claude 官方 App 的 Code 頁籤、本機工作階段 可顯示五個按鈕 程式包含 desktop 介面的顯示分支 確認 App 的 Code 工作階段讀取到來源設定,再開新工作階段;可用 /status 查看其中的 Claude Code 版本。

官方文件列出 Mods 在這三種介面的支援。VS Code 的 Mod 繪圖需擴充版本 2.1.299 以上;不取得功能開關(feature flags)的服務環境需 2.1.304 以上。官方 App 這裡指 Code 頁籤;一般聊天頁籤不在這個載入流程內,App 的 WSL 工作階段目前也不支援 Plugins。官方 Mods 介面支援、VS Code Mod 繪圖說明

vibeClaudeMods 的功能與操作

這篇介紹 quick-actions 與 today-cost 兩個本地 Mod。各項功能分別放在自己的資料夾,方便獨立載入與測試。

quick-actions 的五個按鈕

按鈕 實際執行的動作 使用時要知道的事
effort 執行 /effort,依 medium → high → low → medium 循環切換 尚未取得目前值時只顯示 effort,第一次按下切到 high;切換指的是模型的思考努力程度。
Handoff 送出請求,請 Claude 依 handoff-safe Skill 寫交接文件 需要該 Skill 存在;文件預設放在目前專案的 agent_handoff/。找不到 Skill 時只顯示提示。
Resume 找出目前專案最新的交接文件,請 Claude 讀取、列出下一步並詢問是否執行 以交接檔名中的時間判斷新舊。沒有資料夾或交接檔時只提示;執行前仍會詢問使用者。
Compact 執行 /compact,整理目前對話上下文 會提示已開始,並顯示指令回傳結果;處理未結束前會忽略重複點擊。對話太少時可能回覆無法壓縮。
Clear 執行 /clear,清除目前對話上下文 開新任務前若要保留工作脈絡,可先完成交接文件。

effort 的目前值來自主對話的模型請求與 /effort 執行紀錄。VS Code 底部的模型/effort 標籤可能沒有跟著由 Mod 發起的切換更新,判斷時要對照按鈕與實際請求資訊。

Handoff 與 Resume 會送出請求交由 Claude 處理,後續可能使用模型與檔案工具;其他三個按鈕則執行對應的 Claude Code 指令。模型回應中或有問卷時,整排按鈕會隱藏,避免操作排隊後在錯誤時機清除對話。quick-actions 也會保留同區域內其他 Mod 已繪製的內容。

ledger 的用量、上下文與快取資訊

程式放在 today-cost/,Plugin 名稱則是 ledger,所以畫面顯示 ledger plugin。圖 1 的資訊列包含以下內容:

顯示項目 代表什麼 如何判讀
today $… 本機今日帳本中,各工作階段的當日成本合計 依電腦的本地日期累計,跨日延續的工作階段會扣除先前基準;帳本與 Coralline 共用。
… sessions 今日帳本記錄的工作階段數 圖中的 3 sessions 是帳本記錄數;其中也可能有目前未執行或成本為零的工作階段。
this $… Claude Code 提供的目前工作階段成本 是本次工作階段的累計值,可能跨日;和「今日新增成本」的範圍不同。
…% …k/…k 或 –/1M 目前上下文用量與視窗大小 第一次取得主對話回應前可能只有視窗大小,例如圖中的 –/1M;它和帳號剩餘額度分開計算。
cache 5m/cache 1h 與剩餘時間 從主對話紀錄推得的 Prompt Cache(提示快取)有效期間 – 表示尚未取得對應資訊;? 表示有回應但缺少可辨識的快取期限;expired 表示倒數已結束。

金額保留到小數點後兩位,範圍限於本機帳本與宿主提供的成本資訊,適合觀察使用情況;帳號或組織的實際費用仍以服務帳單核對。

快取期限依對話紀錄中的 ephemeral_5m/ephemeral_1h 寫入資訊判斷,混合寫入時採較短的期限。畫面每 10 秒重畫倒數;成本與上下文有變化時會更新帳本,另有每 60 秒的定期刷新。這些更新不會主動送出新的模型請求,倒數也只是依紀錄估算的顯示,後續是否命中快取仍要看實際回應用量。

在已啟用 ledger 的圖形介面輸入 /today-cost,可刷新並列出今日合計、工作階段數、本次成本與快取資訊。純終端機不會自動登記這個指令;若同一工作階段之後接上 VS Code 或官方 App,程式會重新判斷顯示條件。

背景、問題與限制

Mod 是放在 Plugin(外掛套件)裡的 JavaScript/TypeScript 事件處理程式。Claude Code 啟動工作階段、呼叫工具或繪製介面時,會把事件交給已登記的處理函式。你可以觀察事件、保留原本流程,或針對自己的指令回傳結果。

公司限制要先分清楚

「禁止從市集安裝外掛」和「禁止執行任何自製 Mod」可能是不同範圍。先向管理員確認本機自製套件是否在允許範圍;若公司明確禁止,應停在原始碼閱讀與申請審核。

本文所說的本機開發載入,是用 --plugin-dir 指向資料夾。組織可用 disableSideloadFlags 拒絕這種啟動方式,也可限制哪些 Mods 能執行。遇到管理政策阻擋時,保留錯誤訊息交給管理員,不修改受管設定。官方設定參考

Mod 以你的使用者權限在本機執行,應只載入你理解並信任的程式碼。本機載入也不會讓 Claude 的一般模型對話變成離線;資料可否送往模型服務,仍依帳號與公司的使用規範判斷。

做法與關鍵取捨

這個練習依序經過「建立三個檔案 → 靜態驗證 → 單次載入 → 修改重載 → 離線測試」。先用單次載入熟悉行為,最後再考慮要不要登記成每次啟動都載入的工具。

1. 確認終端機使用的版本

在終端機輸入:

sh
claude --version
claude plugin validate --help
claude plugin test --help

應能看到版本及兩個子命令的說明。本文範例以 macOS 的 Claude Code 2.1.308 核對;若顯示找不到 claude,先處理 CLI 安裝或 PATH。若沒有 plugin test,請依組織允許的方式確認版本,暫停後面的測試步驟。

VS Code 擴充、Claude Desktop 與終端機 CLI 可能使用不同版本。這一步確認的是目前終端機呼叫到的 CLI;實際介面另在載入後確認。

2. 建立一個獨立的練習資料夾

先切到你允許放置個人練習的目錄,例如自己的開發資料夾。下面兩組指令依作業系統擇一執行;下載範例者可直接切到解壓縮後的 my-tool-counter。

macOS/Bash

bash
mkdir -p my-tool-counter/.claude-plugin my-tool-counter/hooks my-tool-counter/tests
cd my-tool-counter

Windows/PowerShell

powershell
New-Item -ItemType Directory -Force -Path "my-tool-counter/.claude-plugin", "my-tool-counter/hooks", "my-tool-counter/tests" | Out-Null
Set-Location "my-tool-counter"

在編輯器中開啟這個資料夾,建立以下檔案,全部存成 UTF-8。Windows 要留意檔案沒有被另存成 plugin.json.txt。

text
my-tool-counter/
├── .claude-plugin/
│   └── plugin.json
├── hooks/
│   ├── hooks.json
│   └── register.mjs
└── tests/
    └── counter.test.ts  ← 第 6 步再加入

plugin.json 告訴 Claude Code 套件是誰;hooks.json 指出要載入哪個程式;register.mjs 才是功能本身。副檔名 .mjs 表示 JavaScript 模組,這個範例不需另外安裝 npm 套件。

3. 寫入身分、入口與事件處理程式

.claude-plugin/plugin.json

json
{
    "name": "my-tool-counter",
    "version": "0.1.0",
    "description": "A local practice mod that counts tool call attempts",
    "author": {
        "name": "Luke Hou"
    }
}

自行製作新套件時,將名稱、描述與作者換成自己的資訊。若一併更改資料夾或指令名稱,後面的載入路徑與測試也要對應調整。

hooks/hooks.json

json
{
    "modules": ["./register.mjs"]
}

./register.mjs 是相對於 hooks.json 的位置,因此兩個檔案放在同一層。若錯寫成 ./hooks/register.mjs,就會指到多一層的路徑。

hooks/register.mjs

javascript
export function register(on) {
    let attempts = 0;

    on('session.start', async ($, event, next) => {
        await $.command.register({
            name: 'my-tool-count',
            description: '顯示這個 Mod 載入後觀察到的工具呼叫次數'
        });
        return next(event);
    });

    on('tool.call', async ($, event, next) => {
        attempts += 1;
        return next(event);
    });

    on('command.run', { command: 'my-tool-count' }, async () => {
        return { text: `已觀察到 ${attempts} 次工具呼叫嘗試` };
    });
}

register(on) 在 Mod 載入時登記事件。$ 提供 Claude Code 的功能,例如登記指令;event 是當次事件資料;next(event) 把事件交給下一個處理者,讓原有流程繼續。

這裡有兩種處理方式:session.start 與 tool.call 做完自己的工作後繼續傳遞;command.run 只接住 /my-tool-count,直接回傳要顯示的文字。其他指令不符合篩選條件,會沿原本流程處理。事件與 API 參考

計數發生在工具準備執行時,所以被後續規則拒絕、或最後執行失敗的呼叫,也可能計入。它適合觀察嘗試次數;若要統計成功結果,還需要另外設計判斷條件。

4. 驗證與單次工作階段載入

保持終端機位於 my-tool-counter,先執行:

sh
claude plugin validate .

檢查結果應包含 session.start、tool.call、command.run{command=my-tool-count},以及 $.command.register。如果入口檔找不到、JSON 格式錯誤,或預期的事件沒有出現,先修正再繼續。

驗證器也可能列出市集上架所需的 README、授權或圖示要求。一般本機驗證與 --profile directory 的上架檢查有不同目的;請閱讀最後的驗證結果及每一項訊息,不必為了本機練習先申請市集發布。

接著啟動一個新工作階段:

sh
claude --plugin-dir .

進入 Claude Code 後輸入:

text
/my-tool-count

若這個新工作階段尚未呼叫工具,應顯示「已觀察到 0 次工具呼叫嘗試」,介面可能另加套件名稱。你也可用 /plugin 查看載入狀態。若指令不在清單,先排查載入,不要把它改成一般訊息反覆送給模型。

要觀察數字增加,可在這個練習目錄另建一份不含敏感內容的 demo.txt,再請 Claude:「只讀取這個練習資料夾的 demo.txt,完成後停止。」依既有權限處理讀檔,完成後再輸入 /my-tool-count。實際次數取決於工具呼叫,無須固定等於一。

--plugin-dir 載入只適用於這次啟動,沒有把這個 Mod 登記成永久安裝。一般操作產生的 Claude 對話紀錄仍依原本設定保存。官方本機載入與開發說明

5. 修改後確認熱重載與狀態重設

保留剛才的互動工作階段,在編輯器把回傳文字改為:

javascript
return { text: `工具呼叫嘗試:${attempts} 次` };

儲存後留意 Mod 重新載入的提示,再輸入 /my-tool-count。應看到新文字。互動工作階段會監看本機載入的資料夾;若修改由 Claude 在回合中完成,重載可能等到回合結束。

這個例子的 attempts 放在 register 裡,重載後會重新建立,所以數字回到零。要跨重載保存數值時,應改用適合的狀態保存機制,並另測資料生命週期。

若沒有看到變更,確認你改的是實際載入的同一個資料夾,重新驗證後再開新工作階段。請 Claude 修改目前已載入的 Mod 時,仍保留介面要求的檔案修改核准。

開發時也可查看宿主產生的 .claude-plugin/types/ 型別宣告。API 有版本差異時,以實際使用版本產生的宣告為準;這個 JavaScript 入門例子不需先設定 TypeScript 編譯流程。

6. 用離線測試確認計數與原流程

把第 5 步的回傳文字改回原版,讓它和下面測試一致,再建立 tests/counter.test.ts:

typescript
import { expect, test } from 'claude-code/testing';

test('兩次呼叫會累計,原本的工具結果也會傳回', async ($, on) => {
    on('tool.call', () => ({ result: 'fake-result' }));

    const result = await $.tool.call({ tool: 'Read', file_path: 'demo.txt' });
    await $.tool.call({ tool: 'Read', file_path: 'demo.txt' });
    const answer = await $.command.run({ command: 'my-tool-count', args: '' });

    expect(result.result).toBe('fake-result');
    expect(answer.text).toBe('已觀察到 2 次工具呼叫嘗試');
});

test('下游拒絕時仍會記為一次嘗試', async ($, on) => {
    on('tool.call', () => ({ deny: 'blocked-by-test' }));

    const result = await $.tool.call({ tool: 'Read', file_path: 'demo.txt' });
    const answer = await $.command.run({ command: 'my-tool-count', args: '' });

    expect(result.deny).toBe('blocked-by-test');
    expect(answer.text).toBe('已觀察到 1 次工具呼叫嘗試');
});

另開終端機,切到 my-tool-counter 後執行:

sh
claude plugin test .

這裡的測試套件用 stub(測試替身)代替真正的讀檔與拒絕回應;demo.txt 不需存在,也不會送出模型請求。測試應為 2 pass、0 fail。若出現找不到測試,先確認副檔名為 .test.ts 或 .test.tsx,並放在 Mod 目錄內。官方離線測試說明

第一個測試同時確認計數與原工具結果保留;第二個固定了「嘗試次數」的語意。它們測的是事件處理,實際介面的指令登記、畫面與重載仍依第 4、5 步確認。

7. vibeClaudeMods 的常用載入流程

已有 vibeTool 原始碼的人,可以先單獨載入其中一個 Mod。例如切到 vibeClaudeMods 後:

sh
claude --plugin-dir ./quick-actions

用同樣方式驗證它的程式與離線測試:

sh
claude plugin validate ./quick-actions
claude plugin test ./quick-actions

quick-actions 透過 ui.render 處理 AbovePrompt 區域,保留其他 Mod 原本繪製的內容後再加按鈕。讀它的程式時,可沿著「繪製條件 → 按鈕 → 指令或請求 → 失敗回饋」追下去。若只是觀察畫面,先不要點 Handoff、Resume 或 Clear;這些按鈕會各自觸發工作。

每次啟動都載入的設定登記

如果你已確認套件內容與使用範圍,在 vibeClaudeMods 目錄先預覽登記結果:

macOS

bash
python3 -B install.py --dry-run

Windows

powershell
py -3 -B install.py --dry-run

確認列出的套件都是你要載入的,再用相同的 Python 指令移除 --dry-run 執行。這一步會修改使用者層級 ~/.claude/settings.json 的 env.CLAUDE_CODE_PLUGIN_DIRS,影響後續工作階段;原檔存在且內容要變動時,腳本會先備份。它不會另外複製 Mod。

腳本會登記同層含 .claude-plugin/plugin.json 的資料夾,並排除含 .claude-plugin/offline-only 的項目。目前 quick-actions、today-cost 可被掃描登記。若你只想試一個 Mod,繼續使用 --plugin-dir 即可。

這套環境變數登記是 vibeClaudeMods 現有腳本的做法;使用其他 Claude Code 版本或介面時,仍要確認載入結果。多路徑分隔符號由腳本依系統處理,Windows 使用 ;,macOS/Linux 使用 :,不要整段照抄另一台電腦的路徑。

修改情況 後續操作
修改已登記 Mod 的程式 不需重新登記;確認互動重載,或開新工作階段。
新增、刪除、改名 Mod,或調整 offline-only 重新 dry-run、核對結果後登記,再開新工作階段。
repo 搬家或換電腦 在新位置重新 dry-run、核對並登記。

在三種介面確認載入結果

  • 終端機:用 --plugin-dir 試跑,或在登記後重新執行 claude。確認 quick-actions 的五個按鈕;純終端機不會因載入 today-cost 就出現 ledger 列。
  • VS Code 擴充:登記後,在原生 Claude Code 面板開啟新的工作階段,確認 quick-actions 與 ledger。把 claude --plugin-dir … 輸入內建終端機,開啟的仍是 CLI 介面;這個旗標也不是要貼進聊天輸入框的指令。
  • 官方 App:在 Code 頁籤選擇本機專案並建立新的工作階段,確認相同的按鈕與 ledger 列。用 /status 核對 Code 工作階段的引擎版本,無須拿 App 的一般聊天頁籤尋找這些元件。

三者使用同一個使用者與設定目錄時,可共用 Claude Code 的設定;若使用不同的 CLAUDE_CONFIG_DIR,需逐一核對。install.py 預設寫入 ~/.claude/settings.json,使用自訂設定目錄時,應以它的 --settings 選項指定該目錄內的 settings.json,並先 dry-run。官方 App 共用設定、VS Code 設定

停止載入與還原

使用 --plugin-dir 的練習,結束該工作階段後,下一次不帶這個參數啟動即可。如果你已使用安裝腳本登記,先備份目前的 settings.json,再只移除 env.CLAUDE_CODE_PLUGIN_DIRS 裡對應的 Mod 路徑,保留其他設定與外部套件路徑,並開新工作階段確認。

不要直接用舊備份覆蓋整份設定,避免一併撤回後來新增的其他設定。若要恢復舊版,應先比較兩份內容;已登記多個 Mod 時,也要留意所在系統的路徑分隔符號。

證據、驗證與已知限制

常見問題可從哪裡查

現象 先檢查 下一步
載入後找不到 /my-tool-count --plugin-dir 是否指到含 .claude-plugin 與 hooks 的根目錄;JSON、模組路徑與事件名稱 執行 plugin validate,修正明確錯誤後開新工作階段。
儲存後仍是舊文字 編輯檔案與載入路徑是否同一份;回合是否已結束 重新驗證,再開新工作階段確認。
數字突然歸零 是否剛重載 Mod 或開了新工作階段 本例為記憶體計數;需長期累計時另設保存機制。
plugin test 找不到案例 檔名及所在目錄 使用 .test.ts/.test.tsx;不要把測試放在 Mod 資料夾外。
組織政策拒絕本機載入或執行 hooks 啟動錯誤與管理員允許範圍 停止載入,把訊息交給管理員確認。
CLI 能用,VS Code 或 Desktop 沒顯示 實際宿主版本、是否重開工作階段、元件支援範圍 分別驗證目標介面;不要用 CLI 測試結果代替畫面確認。

完成時應能核對的結果

  • 能逐一說明 quick-actions 五個按鈕與 ledger 各欄位,並分清三種介面的顯示條件。
  • 三個主要檔案各自負責身分、模組路徑與事件處理,plugin validate 能辨識預期事件。
  • 新工作階段能直接執行 /my-tool-count;觀察工具呼叫後,可解釋數字代表的範圍。
  • 修改回傳文字後能看到新內容,也知道記憶體計數為何重設。
  • 兩項離線測試通過;能區分測試替身、真實工具執行與介面驗證。
  • 能停止單次載入;若使用設定登記,也知道只移除對應路徑的還原方式。

本文的教學範例已在 macOS、Claude Code 2.1.308 完成靜態驗證與兩項離線測試。Windows 指令提供對應操作方式;Windows 執行、互動式熱重載及各宿主的實際畫面,需在目標環境逐項確認。

延伸閱讀與來源

返回教學總覽 回到文章開頭 ↑