Community编程与开发github.com

lisper

严格的 Common Lisp 和 Emacs Lisp 代码审查与生成,确保编译无警告、结构化条件、卫生宏、纯函数核心、词法绑定纪律、语义谓词、文档化符号以及非破坏性列表语义。在需要模型完备性、宏卫生、条件/重启设计、缓冲区/进程边界隔离、checkdoc/package-lint/sblint 合规以及代码规模可控时使用。

lisper 是什么?

Lisper 技能为 AI 代理(如 Claude Code 或 Cursor)提供了一个严格的 Lisp 编程纪律框架。它包含 12 条核心断言,涵盖了从模型驱动的 S-表达式设计、高阶函数组合优先于宏、纯数据转换与副作用的隔离,到资源生命周期管理、代码质量规范(零编译器警告、检查工具合规)以及语义谓词的命名约定。该技能支持 Common Lisp 和 Emacs Lisp 两大方言,并针对每种方言提供了具体的最佳实践。它强调代码应准确反映问题域模型,使用结构化条件(conditions)和重启机制(restarts)进行错误处理,以及利用词法作用域、卫生宏(hygienic macros)和组合子(combinators)来构建可靠、可维护的 Lisp 系统。

兼容平台~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. 纯数据转换保持在镜像的可变世界之外。优先使用 catamorphisms(cl-reduce / seq-reduce)、同态映射(mapcar / seq-keep)和谓词管道(seq-filter),而不是命令式的 let + setq + push + nreverse 循环。将纯符号/列表/结构转换与缓冲区修改、进程 IO、文件系统状态、网络流、定时器和全局特殊变量(*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 单元所有权是一个语义声明。将输入列表、树和序列视为不可变的,除非函数名和文档字符串显式声明了破坏性行为(nreverse、nconc、delete、sort、cl-delete、setf 于共享 cons 单元上)。绝不对引用字面量('(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 注释层次结构(;;;; 节,;;; 顶层,;; 对齐体内,; 边距)。

;;; 前置条件:(and ( <= 0 start end (length sequence)) (listp sequence))
;;; 后置条件:(and (equal result (subseq sequence start end))
;;;            (not (eq result sequence)))
(defun slice-copy-checked (sequence start end)
  "返回从 START 到 END 的 SEQUENCE 的一个新子序列。"
  (check-type sequence list)
  (assert (<= 0 start end (length sequence)))
  (copy-list (subseq sequence start end)))

;;; 不变量:(null (intersection (work-set-pending ws) (work-set-completed ws) :test #'equal))
;;; 保持性:`work-set-complete' 在将 ID 加入 `completed` 之前将其从 `pending' 移除。
(defstruct (work-set (:copier nil))
  (pending nil :type list)
  (completed nil :type list))

;;; 法则:(equal (decode-packet (encode-packet x)) x) 对所有有效的包结构体 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) 并返回值的高阶组合子替换重复的命令式轮询、循环安全的图遍历或资源支架模式。
  • 相等性精度:绝不在需要 eql(数字/字符)、equal(结构字符串/列表)或 equalp / 领域相等性的地方使用 eq。选择与类型的等价关系匹配的最严格的相等性谓词,并在键是字符串或复合值时显式地向 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 保护所有 point、mark、narrowing 和 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 或显式序列 :components 与清晰的依赖 DAG。
  • 生产路径中的禁止构造:
    • 无运行时 eval 来分派函数或构造代码(使用 funcall、apply 或编译时宏)。
    • 无对未声明的自由变量的动态 setq。
    • 无对引用字面量或非拥有的调用者列表的原地修改(nconc、nreverse、delete、sort)。

相关技能