Community程式設計與開發github.com

Lisper

嚴格的 Common Lisp 與 Emacs Lisp 程式碼審查與生成,確保無警告編譯、結構化條件、衛生巨集、純函數核心、詞法綁定紀律、語義謂詞、已文件化符號,以及非破壞性列表語義。

Lisper 是什麼?

此技能專注於 Common Lisp 和 Emacs Lisp 程式碼的嚴格審查與生成。它將一系列斷言(assertions)作為核心規則,優先提供確切的程式碼事實而非個人品味,並要求使用者明確命名使斷言成立的套件、符號、結構體、條件、巨集展開、不變量、測試或副作用邊界。技能強調模型完整性,要求程式碼先建立領域模型(如使用 S-expressions、結構體或 CLOS 類別),再進行具體實作。它嚴格規範衛生巨集(hygienic macros)、詞法綁定(lexical binding)優先、純函數核心與副作用隔離、結構化條件與重啟(structured conditions and restarts)、不變量的命題式表達(如透過 deftype 或 smart constructors)、以及明確的 cons-cell 所有權語義。此外,技能也要求程式碼品質需以可重現的測試(如 ERT、FiveAM)作為見證,並遵守命名空間前綴、文件化規範、以及資源生命週期的動態範圍管理。它支援多種平台與工具,包括 Emacs Lisp 的 lexical-binding、checkdoc、package-lint,以及 Common Lisp 的 SBCL、ASDF 等,並提供形式邏輯註解(如 Pre、Post、Invariant)與語義謂詞(-p / p 結尾)的使用指南,以提升程式碼的可讀性與正確性。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/RyanKung/Lisper/tree/master

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Lisper 是做什麼的?

操作規則

將此技能視為一系列斷言。將每個斷言視為已滿足、已違反,或因使用者限制而明確推遲。偏好確切的程式碼事實而非個人品味。命名使斷言成立的套件、符號、結構體、條件、巨集展開、不變量、測試或副作用邊界。

陳述事實。命名見證者。不要爭論品味。

在報告 Common Lisp 或 Emacs Lisp 程式碼時,使用簡短的陳述句書寫:

  • 不變量存在於建構子中。
  • 動態範圍由 unwind-protect 界定。
  • 該巨集洩漏了求值順序。
  • 該條件是結構化的。
  • 破壞性列表操作改變了呼叫者的結構。
  • 該謂詞是裸的(未封裝)。
  • 編譯器警告仍然存在。
  • 緩衝區效果洩漏到純核心中。

斷言

  1. 程式碼描繪模型。S-表達式在成為文字之前就是語法樹。保留問題的每個真實狀態。使用符號、標記結構(defstruct / cl-defstruct)、CLOS 類別,或帶有顯式建構子的代數關聯列表/屬性列表。僅擦除那些在語義上未使用的區別。

  2. 高階函數在巨集重寫之前進行組合。Lisp 首先是 lambda 演算:函數是一等值,閉包攜帶詞法環境,柯里化(apply-partially 或返回 (lambda (x) ...))取代多參數管道。當同一結構出現兩次時,檢查它;當出現三次時,用高階組合子、柯里化閉包或泛型函數來抽象化——絕對不要用一個 10 參數的程序化輔助函數。僅在控制求值、綁定詞法符號或消除編譯時代碼模板時引入巨集。每個巨集必須最多從左到右求值一次值參數,並使用 gensym / make-symbol(with-gensyms)綁定臨時變量。

  3. 純資料轉換保持在鏡像(image)的可變世界之外。偏好 catamorphisms(cl-reduce / seq-reduce)、同態映射(mapcar / seq-keep)與謂詞管道(seq-filter),而非命令式的 let + setq + push + nreverse 迴圈。將純符號/列表/結構轉換與緩衝區變異、進程 I/O、檔案系統狀態、網路串流、計時器和全域特殊變數(*earmuffs*)分離。核心函數接收值並返回值。宿主效果保留在命名的邊界函數中。

  4. 詞法作用域是預設法則。每個 Emacs Lisp 檔案必須以 ;; -*- lexical-binding: t; -*- 開頭。Common Lisp 或 Emacs Lisp 中的每個動態特殊變數必須帶有 *earmuffs*(或在 CL 中常數用 +plus-signs+),並使用 let 進行動態綁定,而不是使用 setq / setf 全域變異,除非改變全域設定是明確的合約。

  5. 不變量是命題。首先在型別中表達不變量(使用 satisfies 的 deftype、ftype 宣告、defstruct :type 插槽),其次是智慧建構子(:constructor),再次是執行時斷言(check-type / cl-check-type),接著是測試,最後是註解。建構子是證明結構滿足其插槽不變量的證據。

  6. 條件是代數事實,而非原始字串。定義明確的條件層次結構(Common Lisp 中的 define-condition;Emacs Lisp 中的 define-error)。使用 error / cerror / signal 發送結構化條件,以便呼叫者可以使用 handler-case、handler-bind 或 condition-case 處理它們,而無需匹配錯誤訊息子字串。當恢復策略屬於呼叫者且機制屬於底層函數時,使用 Common Lisp 重啟(restart-case)。

  7. Cons-cell 所有權是一個語義聲明。除非函數的名稱和文檔字串明確聲明破壞性行為(nreverse、nconc、delete、sort、cl-delete、對共享 cons cell 的 setf),否則將輸入列表、樹和序列視為不可變。絕不要對引號文字 '(a b c) 或借用的呼叫者列表應用破壞性操作。僅在變異開始的邊界處複製結構(copy-list、copy-tree、copy-sequence)。

  8. 品質是被見證的,而非斷言的。零字節碼編譯器警告、零 checkdoc / package-lint 錯誤、以及零 SBCL STYLE-WARNING 診斷只是地板。為純轉換、巨集展開法則、邊界輸入、非局部退出下的動態清理以及修復的回歸問題添加 ERT(ert-deftest)或 FiveAM/Rove/Parachute 測試。測試名稱陳述了它所見證的命題。

  9. 文件化和命名空間前綴是公開合約的一部分。

    • 在 Common Lisp 中:定義明確的套件(defpackage / uiop:define-package),避免超出 :cl 的全域 :use 污染;為每個匯出的函數、巨集、類別、變數和條件撰寫文件。
    • 在 Emacs Lisp 中:為每個公開符號加上 <package>- 前綴,為每個內部符號加上 <package>-- 前綴;撰寫符合 checkdoc 規範的文檔字串,其第一行是完整的句子,並且參數引用是 UPPERCASE;正確宣告 Package-Requires 和 ;;; Commentary: 標頭。
  10. 資源生命週期由動態範圍界定。絕不要跨可能失敗的表達式配對手動分配和清理。將每個臨時緩衝區更改、點移動、檔案控制代碼、進程、套接字或鉤子安裝包裝在 unwind-protect(或 with-open-file、with-temp-buffer、save-excursion、save-restriction、save-match-data)中。非局部退出(throw、return-from、signal、error)必須保持全域狀態和緩衝區清潔。

  11. 大小和括號佈局是結構訊號。保持每個源檔案在 1000 行以下,每個 defun / defmacro 可執行主體(排除其文檔字串和 declare 形式)在 80 行以下。絕不要為了玩弄行數限制而截斷文檔字串、刪除解釋性註解,或將多個順序副作用形式打包到單行中。絕不要將閉合括號 ))) 單獨放在行尾。根據標準 Lisp 形式語義縮排(在每個 Elisp 巨集上宣告 (declare (indent ...)))。根據領域命題分割檔案和函數,而不是根據隨意的行數切片或模糊的 utils 桶。

  12. 邏輯需要命名。當表達領域命題時,不要在調用點暴露原始的 car/cdr/nth 鏈(cadddr)、巢狀的 assoc/plist-get 管線,或多子句的 and/or/not 表達式。定義命名存取器和以 -p 或 p 結尾的語義謂詞(例如 order-matchable-p、same-principal-p、session-active-p)。

模型完整性

在選擇套件、結構體和函數之前,命名使程式碼一致的正式模型。

對於巨集和語法轉換:

  • 巨集是從語法到語法的編譯器傳遞:$\text{AST}{\text{surface}} \to \text{AST}{\text{core}}$。
  • 指定表層語法(解構 lambda 列表)、綁定紀律、每個子形式的求值次數以及目標展開。
  • 使用 macroexpand-1 / macrostep 驗證衛生性:無自由符號捕獲、無對具有副作用的參數進行多次求值、無執行時 eval。
  • 如果巨集展開為定義,為宿主編譯器和檢查器保留原始碼位置和宣告(declare、文檔字串位置)。

對於互動狀態、緩衝區和並發進程:

  • 互動系統在成為緩衝區或執行緒之前是一個狀態轉換關係。
  • 將領域狀態值與渲染緩衝區(Emacs UI)或工作者執行緒/套接字(CL/Emacs 進程)分離。
  • 將非同步進程輸出(Emacs 進程過濾器/哨兵、CL 執行緒/通道)建模為離散事件,饋入總體狀態轉換:$\text{State} \times \text{Event} \to (\text{State} \times \text{List}[\text{Effect}])$。
  • Emacs Lisp 中的進程過濾器可能接收任意分塊邊界;在分派領域事件之前,明確地緩衝和解析不完整的幀。
  • 當計時器、哨兵或回調非同步觸發時,保護緩衝區局部狀態(defvar-local)免受已殺死緩衝區(buffer-live-p)的影響。

對於條件、重啟和非局部控制:

  • 將出了什麼問題(條件資料)與如何恢復(CL 中的重啟;Elisp 中的結構化處理程式)以及選擇哪種恢復(外部策略處理程式)分開。
  • 絕不要使用裸 (ignore-errors ...) 或 (condition-case nil ... (error nil)) 吞沒條件,除非已縮小確切忽略的條件類型,且回退值是有效的領域狀態。

形式邏輯註解

僅當形式註解能闡明 ftype、deftype 或 cl-defstruct 未能完全表達的證明義務時使用它們。在函數/形式內部使用 ;;,在頂層使用 ;;;,遵循標準 Lisp 註解層次結構(;;;; 節、;;; 頂層、;; 對齊於主體內、; 邊緣)。

;;; Pre: (and ( <= 0 start end (length sequence)) (listp sequence))
;;; Post: (and (equal result (subseq sequence start end))
;;;            (not (eq result sequence)))
(defun slice-copy-checked (sequence start end)
  "Return a fresh subsequence of SEQUENCE from START to END."
  (check-type sequence list)
  (assert (<= 0 start end (length sequence)))
  (copy-list (subseq sequence start end)))

;;; Invariant: (null (intersection (work-set-pending ws) (work-set-completed ws) :test #'equal))
;;; Preservation: `work-set-complete' removes ID from `pending' before consing onto `completed'.
(defstruct (work-set (:copier nil))
  (pending nil :type list)
  (completed nil :type list))

;;; Law: (equal (decode-packet (encode-packet x)) x) for all valid packet structs X.

偏好這些形式:

  • Pre:呼叫者必須滿足的條件。
  • Post:函數保證的條件,包括新鮮度/共享(eq vs equal)。
  • Invariant:在結構/緩衝區/會話操作中保持成立的命題。
  • Law:測試必須見證的代數或巨集展開關係。
  • Preservation:為何某個轉換或 unwind-protect 形式保持不變量為真。

語義謂詞

使用遵循 Lisp -p / p 慣例的命名謂詞來聲明性地表達領域邏輯:

  • 單詞根(Common Lisp 慣例):evenp、Orderp -> orderp、validp(或在 Elisp 中,對套件前綴符號一致使用 -p)。
  • 連字符根(CL 和 Elisp 均可):order-matchable-p、same-principal-p、lispm-session-live-p。

偏好:

(when (order-matchable-p order resting-order)
  (match-order book order resting-order))

(when (same-principal-p actor owner)
  (grant-access actor resource))

避免:

(when (and (not (eq (order-side order) (order-side resting-order)))
           (>= (order-price order) (order-price resting-order))
           (plusp (order-quantity order)))
  (match-order book order resting-order))

(when (and (equal (principal-id actor) (principal-id owner))
           (eq (principal-realm actor) (principal-realm owner)))
  (grant-access actor resource))

同時避免在領域邏輯中使用深層位置列表存取((cadddr record)、(nth 4 item));定義一個 defstruct / cl-defstruct 或命名存取器函數,以使調用點讀取領域概念而非 cons 拓撲。

實作紀律

從領域出發,並尊重方言的函數式語義。

  • 柯里化、部分應用和組合子:
    • 絕不要通過提取一個帶有 6+ 個位置參數(這些參數反映了呼叫者的 let* 綁定)的程序化輔助函數,或通過將 let* 切片成一次性使用的 foo--part-1 / foo--part-2 子程序,來分解長函數。
    • 絕不要引入「假柯里化」(例如 (lambda (getter-fn) (lambda () ...)))來模擬一個局部 let* 已提供的詞法作用域。
    • 相反地,將真正的領域不變量柯里化到詞法閉包中((defun domain--matcher (query role) (lambda (event) ...)) 或 (apply-partially #'fn fixed-arg)),並組合小的單元/二元轉換:$f \circ g = \lambda x. f(g(x))$。
    • 用接受步驟函數 (funcall step item) 並返回值的高階組合子取代重複的命令式輪詢、循環安全圖遍歷或資源括號模式。
  • 相等性精度:絕不要使用 eq 當需要 eql(數字/字元)、equal(結構性字串/列表)或 equalp / 領域相等性時。選擇與型別等價關係最匹配的最嚴格相等謂詞,並在鍵是字串或複合值時,向 assoc、member、gethash、remove 和 cl-find 顯式傳遞 :test #'equal。
  • Emacs Lisp 特例:
    • 第 1 行必須宣告 ;; -*- lexical-binding: t; -*-。
    • 使用 cl-lib(cl-defstruct、cl-loop、cl-destructuring-bind、cl-check-type),絕不使用已棄用的執行時 cl 套件。
    • 使用 save-excursion、save-restriction 和 save-match-data 保護所有點、標記、縮小和匹配資料副作用。
    • 偏好傳遞緩衝區或顯式 (with-current-buffer buf ...),而非跨非同步邊界假設 current-buffer。
    • 用 (declare (indent ...) (debug ...)) 註解巨集,以使縮排和 Edebug 檢測自動工作。
  • Common Lisp 特例:
    • 為公開領域函數宣告 (declaim (ftype (function (...) ...) name)),以便 SBCL 執行編譯時型別推斷和窮盡性檢查。
    • 使用 etypecase / ecase / ctypecase 而非開放式的 case / typecase,以便未處理的變體立即發出結構化型別錯誤訊號。
    • 避免讀取器表格污染和未匯出符號洩漏(pkg::internal-sym)。
    • 偏好 ASDF「package-inferred」或帶有清晰依賴 DAG 的顯式序列 :components。
  • 生產路徑中的禁止結構:
    • 無執行時 eval 用於分派函數或建構程式碼(改用 funcall、apply 或編譯時巨集)。
    • 無對未宣告自由變數的動態 setq。
    • 無對引號文字或非擁有的呼叫者列表進行原地變異(nconc、nreverse、delete、sort)。

…

[為翻譯而截斷]

相關技能