Espanso 完整使用指南

Espanso 是什麼

Espanso 是跨應用程式的文字展開工具。你輸入一段預先定義的觸發文字，它就會自動替換成完整內容。

輸入

;email

展開結果

ericx790101@gmail.com

常見用途包含：

常用回覆與個人資料
程式碼片段與 Git 指令
AI 提示詞與任務交接模板
日期、時間、UUID 與 Shell 輸出
Markdown、Issue、會議與 Email 範本

Espanso 使用 YAML 管理規則，設定檔可以直接使用 Git 版控，適合建立長期、可攜、跨應用程式的個人輸入系統。

一、在 macOS 安裝

brew install --cask espanso

完成後從「應用程式」開啟 Espanso。第一次啟動時，依序設定：

系統設定 → 隱私權與安全性 → 輔助使用 → 開啟 Espanso。
若仍無法展開，再檢查「輸入監控」。
重新啟動 Espanso。

測試是否正常

在備忘錄或 VS Code 輸入：

:espanso

正常情況會替換成：

Hi there!

二、理解核心概念

每一條 Espanso 規則主要由兩個欄位構成：

trigger: 觸發文字
replace: 替換結果

- trigger: ";email"
  replace: "ericx790101@gmail.com"

建議統一使用分號作為前綴，例如 ;email、;git-log、;ai-review。分號較不容易出現在一般中文與英文內容中。

三、找到設定檔

espanso path

macOS 常見目錄：

~/Library/Application Support/espanso

主要目錄結構：

espanso/
├── config/
│   └── default.yml
└── match/
    └── base.yml

config/：控制 Espanso 行為。
match/：存放文字展開規則。

使用 VS Code 開啟：

code "$(espanso path)"

四、建立第一組規則

編輯 match/base.yml：

matches:
  - trigger: ";email"
    replace: "ericx790101@gmail.com"

  - trigger: ";name"
    replace: "Danny Chou"

  - trigger: ";github"
    replace: "https://github.com/ericx790101"

儲存後，Espanso 通常會自動重新載入。若未生效，執行：

espanso restart

五、多行文字

YAML 的 | 可以保留換行：

matches:
  - trigger: ";contact"
    replace: |
      Danny Chou
      Frontend Engineer
      Email: ericx790101@gmail.com
      GitHub: @ericx790101

Markdown 文件模板

- trigger: ";md-note"
  replace: |
    # 標題

    ## 背景

    ## 問題

    ## 分析

    ## 結論

    ## 後續行動

Git Commit 模板

- trigger: ";git-commit"
  replace: |
    feat(scope): summary

    - change:
    - reason:
    - impact:
    - test:

六、游標定位

使用 $|$ 指定展開後的游標位置：

- trigger: ";log"
  replace: "console.log('$|$');"

Vue 3 元件模板

- trigger: ";vue-component"
  replace: |
    <script setup>
    $|$
    </script>

    <template>
      <div class=""></div>
    </template>

    <style lang="scss" scoped>
    </style>

VS Code 會自動縮排，多行文字搭配游標定位時可能出現偏移。複雜程式碼模板通常更適合使用 VS Code Snippets。

七、避免誤觸

使用特殊前綴

只替換完整單字

- trigger: "teh"
  replace: "the"
  word: true

word: true 適合英文拼字修正；中文因缺少空格分詞，不適合大量使用。

八、多個觸發詞共用內容

matches:
  - triggers:
      - ";mail"
      - ";email"
      - ";gmail"
    replace: "ericx790101@gmail.com"

別名適合處理容易忘記的 trigger，但不宜過度使用，否則規則命名會失去一致性。

九、日期與時間

插入今天日期

matches:
  - trigger: ";date"
    replace: "{{today}}"
    vars:
      - name: today
        type: date
        params:
          format: "%Y-%m-%d"

完整日期時間

- trigger: ";datetime"
  replace: "{{datetime}}"
  vars:
    - name: datetime
      type: date
      params:
        format: "%Y-%m-%d %H:%M:%S"

格式	意義
`%Y`	四位數年份
`%m`	月份
`%d`	日期
`%H`	24 小時制小時
`%M`	分鐘
`%S`	秒

每日紀錄模板

- trigger: ";daily"
  replace: |
    # {{today}}

    ## 今日目標

    - $|$

    ## 完成事項

    ## 問題紀錄

    ## 明日行動
  vars:
    - name: today
      type: date
      params:
        format: "%Y-%m-%d"

十、使用表單輸入動態內容

matches:
  - trigger: ";meeting"
    form: |
      # [[title]]

      日期：[[date]]
      參與者：[[participants]]

      ## 討論事項

      [[content]]

      ## 行動項目

多行欄位

- trigger: ";issue"
  form: |
    ## 問題

    [[problem]]

    ## 重現步驟

    [[steps]]

    ## 預期結果

    [[expected]]

    ## 實際結果

    [[actual]]
  form_fields:
    problem:
      multiline: true
    steps:
      multiline: true
    expected:
      multiline: true
    actual:
      multiline: true

十一、下拉選項

matches:
  - trigger: ";task"
    form: |
      任務：[[title]]
      類型：[[type]]
      優先級：[[priority]]
    form_fields:
      type:
        type: choice
        values:
          - Feature
          - Bug
          - Refactor
          - Documentation
      priority:
        type: choice
        values:
          - P0
          - P1
          - P2
          - P3

十二、執行 Shell 指令

插入 UUID

- trigger: ";uuid"
  replace: "{{uuid}}"
  vars:
    - name: uuid
      type: shell
      params:
        cmd: "uuidgen | tr '[:upper:]' '[:lower:]'"

插入 Unix timestamp

- trigger: ";timestamp"
  replace: "{{timestamp}}"
  vars:
    - name: timestamp
      type: shell
      params:
        cmd: "date +%s"

處理剪貼簿內容

- trigger: ";lower"
  replace: "{{output}}"
  vars:
    - name: clipboard
      type: clipboard
    - name: output
      type: shell
      params:
        cmd: "printf '%s' \"$ESPANSO_CLIPBOARD\" | tr '[:upper:]' '[:lower:]'"

不要把 API Key、密碼、Access Token 或私密憑證直接寫進 YAML。設定檔是純文字，也可能被 Git 同步。

十三、按用途拆分規則

match/
├── base.yml
├── personal.yml
├── development.yml
├── git.yml
├── ai-prompts.yml
├── markdown.yml
└── work.yml

personal.yml

matches:
  - trigger: ";email"
    replace: "ericx790101@gmail.com"

  - trigger: ";name"
    replace: "Danny Chou"

git.yml

matches:
  - trigger: ";git-status"
    replace: "git status"

  - trigger: ";git-log"
    replace: "git log --oneline --graph --decorate --all"

  - trigger: ";git-clean"
    replace: "git branch --merged | grep -vE '(^\\*|main|master|develop)'"

十四、Vue 3 常用片段

defineProps

- trigger: ";vue-props"
  replace: |
    const props = defineProps({
      $|$
    });

defineEmits

- trigger: ";vue-emits"
  replace: |
    const emit = defineEmits([
      '$|$',
    ]);

Computed

- trigger: ";vue-computed"
  replace: |
    const $|$ = computed(() => {

    });

Watch

- trigger: ";vue-watch"
  replace: |
    watch(
      () => $|$,
      (value, previousValue) => {

      },
    );

Espanso 適合跨應用程式文字。涉及多個 Tab Stop、語言限定與智慧縮排的程式碼模板，應優先使用 VS Code Snippets。

十五、建立 AI 提示詞快捷指令

Code Review 提示詞

matches:
  - trigger: ";ai-review"
    label: "AI：程式碼審查"
    force_mode: clipboard
    replace: |
      請審查以下程式碼變更。

      審查面向：
      1. 功能正確性
      2. 邊界條件
      3. Vue 反應性問題
      4. 元件契約
      5. 非同步與錯誤處理
      6. 安全性
      7. 可讀性與可維護性
      8. 測試完整性

      僅回報具有實際影響且能明確驗證的問題。
      每個問題包含：
      - 嚴重程度
      - 檔案與位置
      - 問題原因
      - 觸發條件
      - 修正方式

TDD 提示詞

- trigger: ";ai-tdd"
  label: "AI：TDD 任務流程"
  force_mode: clipboard
  replace: |
    使用 TDD 執行此任務：

    1. 先理解需求與現有行為
    2. 找出可觀察的輸入與輸出
    3. 先建立失敗測試
    4. 執行測試並確認失敗原因正確
    5. 實作最低限度程式碼
    6. 執行測試確認通過
    7. 重構並保持測試通過
    8. 執行完整 lint、typecheck 與測試

    禁止先修改正式程式碼再補測試。

任務交接提示詞

- trigger: ";ai-handoff"
  label: "AI：任務交接文件"
  force_mode: clipboard
  replace: |
    請產生本次任務交接紀錄，包含：

    ## 任務目標

    ## 已完成內容

    ## 修改檔案

    ## 關鍵設計決策

    ## 測試結果

    ## 已知限制

    ## 尚未完成事項

    ## 下一步建議

    使用 Markdown 格式，內容必須能讓下一個 AI 代理直接接手。

十六、搜尋已有片段

Espanso 可以透過搜尋列查找 Match。macOS 常見快捷鍵：

Option + Space

建議為每一個規則加入 label：

- trigger: ";ai-review"
  label: "AI：程式碼審查提示詞"
  replace: |
    請審查以下程式碼變更。

十七、常用管理指令

用途	指令
查看狀態	`espanso status`
啟動	`espanso start`
停止	`espanso stop`
重新啟動	`espanso restart`
設定路徑	`espanso path`
版本	`espanso --version`
完整說明	`espanso --help`

十八、VS Code 中無法正常展開

常見現象：

少字或文字順序錯誤
長文字只貼上一部分
中文輸入法展開異常
多行內容縮排錯亂

強制使用剪貼簿模式

- trigger: ";ai-review"
  force_mode: clipboard
  replace: |
    很長的提示詞內容

強制使用按鍵模式

- trigger: ";test"
  force_mode: keys
  replace: "測試文字"

多行中文、長提示詞與 Markdown 模板通常優先使用 force_mode: clipboard。

十九、推薦起始設定

將以下內容放入 match/base.yml：

matches:
  - trigger: ";email"
    label: "個人 Email"
    replace: "ericx790101@gmail.com"

  - trigger: ";name"
    label: "英文姓名"
    replace: "Danny Chou"

  - trigger: ";date"
    label: "今天日期"
    replace: "{{today}}"
    vars:
      - name: today
        type: date
        params:
          format: "%Y-%m-%d"

  - trigger: ";uuid"
    label: "產生 UUID"
    replace: "{{uuid}}"
    vars:
      - name: uuid
        type: shell
        params:
          cmd: "uuidgen | tr '[:upper:]' '[:lower:]'"

  - trigger: ";ai-review"
    label: "AI：程式碼審查"
    force_mode: clipboard
    replace: |
      請審查以下程式碼變更。

      審查面向：
      1. 功能正確性
      2. 邊界條件
      3. Vue 反應性問題
      4. 元件契約
      5. 非同步與錯誤處理
      6. 安全性
      7. 可讀性與可維護性
      8. 測試完整性

      僅回報能明確驗證並具有實際影響的問題。

  - trigger: ";ai-handoff"
    label: "AI：任務交接文件"
    force_mode: clipboard
    replace: |
      請產生本次任務交接紀錄：

      ## 任務目標

      ## 已完成內容

      ## 修改檔案

      ## 設計決策

      ## 測試結果

      ## 已知限制

      ## 尚未完成事項

      ## 下一步

二十、長期使用策略

不要在第一天建立數百個規則。使用以下判斷方式：

同一段內容輸入第 2 次
→ 暫時保留

同一段內容輸入第 3 次
→ 建立 Espanso Match

建議命名分類：

前綴	用途	範例
`;me-`	個人資料	`;me-email`
`;git-`	Git 指令	`;git-log`
`;ai-`	AI 提示詞	`;ai-review`
`;md-`	Markdown 模板	`;md-handoff`
`;vue-`	Vue 片段	`;vue-component`
`;work-`	工作回覆	`;work-confirm`

最終目標不是累積大量縮寫，而是建立一套有一致命名、能搜尋、可維護、可同步的個人輸入系統。