讀者與完成目標
這篇適合已經能使用 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。
圖中的 today $0.00 · 3 sessions、this $0.00、–/1M 與 cache –,依序對應今日帳本、本次工作階段、上下文與快取資訊。它們的計算範圍與缺值狀態,會在下方逐項說明。
終端機的實際畫面
終端機也能顯示同一組 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. 確認終端機使用的版本
在終端機輸入:
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
mkdir -p my-tool-counter/.claude-plugin my-tool-counter/hooks my-tool-counter/tests
cd my-tool-counterWindows/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。
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
{
"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
{
"modules": ["./register.mjs"]
}./register.mjs 是相對於 hooks.json 的位置,因此兩個檔案放在同一層。若錯寫成 ./hooks/register.mjs,就會指到多一層的路徑。
hooks/register.mjs
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,先執行:
claude plugin validate .檢查結果應包含 session.start、tool.call、command.run{command=my-tool-count},以及 $.command.register。如果入口檔找不到、JSON 格式錯誤,或預期的事件沒有出現,先修正再繼續。
驗證器也可能列出市集上架所需的 README、授權或圖示要求。一般本機驗證與 --profile directory 的上架檢查有不同目的;請閱讀最後的驗證結果及每一項訊息,不必為了本機練習先申請市集發布。
接著啟動一個新工作階段:
claude --plugin-dir .進入 Claude Code 後輸入:
/my-tool-count若這個新工作階段尚未呼叫工具,應顯示「已觀察到 0 次工具呼叫嘗試」,介面可能另加套件名稱。你也可用 /plugin 查看載入狀態。若指令不在清單,先排查載入,不要把它改成一般訊息反覆送給模型。
要觀察數字增加,可在這個練習目錄另建一份不含敏感內容的 demo.txt,再請 Claude:「只讀取這個練習資料夾的 demo.txt,完成後停止。」依既有權限處理讀檔,完成後再輸入 /my-tool-count。實際次數取決於工具呼叫,無須固定等於一。
--plugin-dir 載入只適用於這次啟動,沒有把這個 Mod 登記成永久安裝。一般操作產生的 Claude 對話紀錄仍依原本設定保存。官方本機載入與開發說明
5. 修改後確認熱重載與狀態重設
保留剛才的互動工作階段,在編輯器把回傳文字改為:
return { text: `工具呼叫嘗試:${attempts} 次` };儲存後留意 Mod 重新載入的提示,再輸入 /my-tool-count。應看到新文字。互動工作階段會監看本機載入的資料夾;若修改由 Claude 在回合中完成,重載可能等到回合結束。
這個例子的 attempts 放在 register 裡,重載後會重新建立,所以數字回到零。要跨重載保存數值時,應改用適合的狀態保存機制,並另測資料生命週期。
若沒有看到變更,確認你改的是實際載入的同一個資料夾,重新驗證後再開新工作階段。請 Claude 修改目前已載入的 Mod 時,仍保留介面要求的檔案修改核准。
開發時也可查看宿主產生的 .claude-plugin/types/ 型別宣告。API 有版本差異時,以實際使用版本產生的宣告為準;這個 JavaScript 入門例子不需先設定 TypeScript 編譯流程。
6. 用離線測試確認計數與原流程
把第 5 步的回傳文字改回原版,讓它和下面測試一致,再建立 tests/counter.test.ts:
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 後執行:
claude plugin test .這裡的測試套件用 stub(測試替身)代替真正的讀檔與拒絕回應;demo.txt 不需存在,也不會送出模型請求。測試應為 2 pass、0 fail。若出現找不到測試,先確認副檔名為 .test.ts 或 .test.tsx,並放在 Mod 目錄內。官方離線測試說明
第一個測試同時確認計數與原工具結果保留;第二個固定了「嘗試次數」的語意。它們測的是事件處理,實際介面的指令登記、畫面與重載仍依第 4、5 步確認。
7. vibeClaudeMods 的常用載入流程
已有 vibeTool 原始碼的人,可以先單獨載入其中一個 Mod。例如切到 vibeClaudeMods 後:
claude --plugin-dir ./quick-actions用同樣方式驗證它的程式與離線測試:
claude plugin validate ./quick-actions
claude plugin test ./quick-actionsquick-actions 透過 ui.render 處理 AbovePrompt 區域,保留其他 Mod 原本繪製的內容後再加按鈕。讀它的程式時,可沿著「繪製條件 → 按鈕 → 指令或請求 → 失敗回饋」追下去。若只是觀察畫面,先不要點 Handoff、Resume 或 Clear;這些按鈕會各自觸發工作。
每次啟動都載入的設定登記
如果你已確認套件內容與使用範圍,在 vibeClaudeMods 目錄先預覽登記結果:
macOS
python3 -B install.py --dry-runWindows
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 執行、互動式熱重載及各宿主的實際畫面,需在目標環境逐項確認。

