# coxn 使用手册 —— 配置参考

本手册介绍 coxswain（coxn）的每一项用户配置：配置文件在哪、怎么写、每个选项的含义与默认值。
运行 / 构建说明见 [README](../README.md)，整体设计见 [designs/clj-editor.md](../designs/clj-editor.md)。

## 目录

1. [配置文件与加载机制](#1-配置文件与加载机制)
2. [init.clj 里可用的 API](#2-initclj-里可用的-api)
3. [核心选项](#3-核心选项)
4. [LSP 选项](#4-lsp-选项)
5. [项目树（treemacs）选项](#5-项目树treemacs选项)
6. [Clojure REPL（CIDER）选项](#6-clojure-replcider选项)
7. [Common Lisp REPL（SLIME）选项](#7-common-lisp-replslime选项)
8. [其它 layer 的选项（helm / tree-sitter）](#8-其它-layer-的选项)
9. [Layer 选用](#9-layer-选用)
10. [主题与 face](#10-主题与-face)
11. [界面语言](#11-界面语言)
12. [钩子与事件](#12-钩子与事件)
13. [键位绑定](#13-键位绑定)
14. [buffer 级配置：EditorConfig 与 file-local](#14-buffer-级配置editorconfig-与-file-local)
15. [环境变量与系统属性](#15-环境变量与系统属性)
16. [一份完整的 init.clj 示例](#16-一份完整的-initclj-示例)

## 1. 配置文件与加载机制

配置文件是 `init.clj`（Clojure 代码，不是 EDN），位置：

| 平台 | 路径 |
|---|---|
| Linux / FreeBSD | `~/.config/coxn/init.clj`（设了 `$XDG_CONFIG_HOME` 则为 `$XDG_CONFIG_HOME/coxn/init.clj`） |
| Windows | `%APPDATA%/coxn/init.clj` |
| 任意平台 | `$COXN_INIT` 指定的文件优先 |

在编辑器里按 `M-m f e d`（`coxswain-find-dotfile`）直接打开它。

要点：

- init.clj 在 `coxn.user` 命名空间里加载，**先于编辑器状态建立**。所以 `set-option!`、`bind-key!`
  这类调用先记入队列，状态建好后依次套上；配置里也可以直接写任意 Clojure 代码。
- 选项的取值优先级：**用户 `set-option!` > layer 默认值 > 核心默认值**（`coxn.editor/opt`）。
- 配置写错了不会挡住启动：错误信息显示在 echo area（`Error in …/init.clj: …`）。
- 运行中按 `M-:`（`eval-expression`）可以在同一个 `coxn.user` 环境里试配置，
  `*ed*` 绑定为当前编辑器状态；`set-option!` 等调用立即生效。

## 2. init.clj 里可用的 API

`coxn.user` 里预置了这些函数（`clojure.core` 全部可用，另 require 了
`coxn.editor`（别名 `ed`，含 `defcommand`）、`coxn.keymap`（`km`）、`coxn.i18n`、
`coxn.hooks`、`coxn.bus`、`coxn.config`、`coxn.layers`）：

| API | 作用 |
|---|---|
| `(set-option! k v)` | 设选项，如 `(set-option! :tab-width 4)`。全部选项见下文各节 |
| `(bind-key! "C-c g" 'find-file)` | 绑全局键 |
| `(unbind-key! "C-c g")` | 解绑 |
| `(prefix-name! "C-c l" "lsp")` | 给前缀键起名（which-key 显示用） |
| `(set-theme! :doom-dark)` | 换主题（见 §10） |
| `(set-face! :region {:bg "#3a3a5a"})` | 覆盖单个 face，换主题后仍生效（见 §10） |
| `(register-theme! {...})` | 注册自己的主题（见 §10） |
| `(palette :space-dark)` / `(palette-with pal :keyword "#ff79c6")` | 取 / 小改内置调色板 |
| `(add-hook! :after-save-hook f)` / `(remove-hook! ...)` | 挂钩子；`f` 收 editor 返回 editor（见 §12） |
| `(subscribe! :document-opened f)` / `(unsubscribe! ...)` | 订阅事实事件；`f` 收 `[event payload]`（见 §12） |
| `(configuration-layers! [:treemacs :lsp ...])` | 选用 layer；不调用 = 全部启用（见 §9） |
| `(set-language! :zh)` | 界面语言（见 §11） |
| `(defcommand name "doc" [ed] ...)` | 定义自己的命令（注册进 `M-x`） |

## 3. 核心选项

核心默认值在 `coxn.editor/default-options`。全部用 `(set-option! 键 值)` 设置。

### 3.1 编辑与缩进

| 选项 | 默认 | 说明 |
|---|---|---|
| `:tab-width` | `8` | Tab 字符的显示宽度（照 Emacs）。EditorConfig 的 `tab_width` / file-local 可按 buffer 覆盖 |
| `:indent-offset` | `4` | 每级缩进的空格数。语言主模式可自带默认（Clojure / Lisp 系是 2）；EditorConfig / file-local 可按 buffer 覆盖 |
| `:fill-column` | `70` | `M-q`（fill-paragraph）与 auto-fill 的行宽（Emacs 默认 70） |
| `:electric-pair` | `false` | 自动补全括号 / 引号（`M-x electric-pair-mode` 开关；Emacs 默认关） |
| `:show-paren` | `true` | 高亮匹配的括号（show-paren-mode，Emacs 28 起默认开） |
| `:line-move-visual` | `true` | `C-n` / `C-p` 按屏幕行走（长行折行时逐屏幕行；Emacs 默认） |
| `:scroll-margin` | `0` | 预留（Emacs scroll-margin 的对应项；当前版本尚未消费） |

### 3.2 界面与显示

| 选项 | 默认 | 说明 |
|---|---|---|
| `:display-line-numbers` | `false` | 行号。`M-x display-line-numbers-mode`（当前 buffer）/ `global-display-line-numbers-mode`（全局） |
| `:mouse` | `true` | 终端鼠标（xterm-mouse-mode）。开着时 Shift+拖动仍是终端自己的选择；`M-x xterm-mouse-mode` 开关 |
| `:extended-keys` | `true` | kitty 键盘协议 / modifyOtherKeys：让终端送得出 `C-;` `C-?` `C-S-a` 等组合键 |
| `:which-key-delay-ms` | `500` | 按下前缀键后多久弹出 which-key 提示 |
| `:tab-bar-mode` | `false` | 顶部标签栏（`M-x tab-bar-mode` 开关） |
| `:minibuffer-display` | `:bottom` | minibuffer（`M-x` / `C-x C-f` 等）位置：`:bottom` 底部 helm 样式（spacemacs 手感）；`:popup` 屏幕中央浮框（vertico-posframe 手感） |
| `:eldoc-display` | `:echo` | 自动函数提示画在哪：`:echo` 最底下一行（不打扰编辑）；`:popup` 自动弹浮框。`M-m t E` 切换。`M-m h g` 的主动查看小框不受此项影响 |
| `:color-depth` | `:auto` | 色深：`:auto` 按终端自动探测（`COLORTERM` / `TERM` / Windows Terminal）；`24` 强制真彩；`8` 强制 256 色档（用主题里人挑的降级色） |
| `:text-scale` | `1.0` | 文字缩放倍数（Emacs text-scale-mode）：`C-x C-+` / `C-x C-=` 放大、`C-x C--` 缩小、`C-x C-0` 复位，每档 ×1.2，范围 0.2–8.0，`C-u 3 C-x C-+` 一次 3 档。GUI 按新字号重算行列；TUI 字号由终端决定，只记倍数。注意：与 Emacs 不同，这里是全局的 |

### 3.3 补全

| 选项 | 默认 | 说明 |
|---|---|---|
| `:completion-auto` | `true` | 打字停下自动弹补全（corfu 手感）。`M-m t a` 开关 |
| `:completion-auto-delay-ms` | `150` | 停下多久后自动弹 |
| `:completion-auto-prefix` | `2` | 符号至少打够几个字符才自动弹（`.` `->` `::` 这类触发字符不受此限） |
| `:completion-sync-wait-ms` | `300` | 补全请求发出后先同步等这么久：来源都回来了就当场出结果，否则转异步浮框（不超过 `:lsp-timeout-ms`） |

### 3.4 文件、自动保存与持久化

| 选项 | 默认 | 说明 |
|---|---|---|
| `:auto-revert` | `true` | buffer 没改过、文件在外面被改了 ⇒ 自动重读 |
| `:auto-save` | `true` | 自动把改过的 buffer 存一份副本（不碰原文件） |
| `:auto-save-interval` | `300` | 每多少次按键触发一次自动保存 |
| `:auto-save-timeout-ms` | `30000` | 空闲多少毫秒触发一次自动保存 |
| `:auto-save-dir` | `<cache>/auto-save` | 自动保存目录；文件名照 Emacs 编码（`/#路径编码#`） |
| `:make-backup-files` | `true` | 每次会话第一次存盘前，把原文件复制一份备份 |
| `:backup-dir` | `<cache>/backup` | 备份目录（文件名 `路径编码~`） |
| `:save-place` | `true` | 记住每个文件的 point / 窗口位置，重开恢复（文件改动后靠上下文找回） |
| `:save-place-file` | `<config>/save-place.edn` | save-place 的存储文件 |
| `:bookmark-file` | `<config>/bookmarks.edn` | 书签（`C-x r m` / `C-x r b`）的存储文件 |
| `:projects-file` | `<config>/projects.edn` | 认识的项目清单的存储文件（`M-x project-forget-project` 等用） |

`<config>` / `<cache>` 见 §15。

### 3.5 GUI 字体（仅 coxn-gui；TUI 忽略这些）

默认全部 `nil` = 跟系统：主字体取系统等宽，CJK / 符号 / emoji 走系统 fontconfig 回退
（CJK 拿等宽黑体保双格对齐）。覆盖时给**优先级列表**，取第一个已安装的（照 spacemacs my-fonts.el）：

| 选项 | 默认 | 说明 |
|---|---|---|
| `:gui-font` | `nil` | 主字体，如 `["JetBrains Mono" "Fira Code"]` |
| `:gui-font-size` | `nil`（= 14） | 字号，单位 sp（桌面端 ≈ px；照 Emacs `:size`），如 `14` |
| `:gui-font-cjk` | `nil` | 全角 / 汉字字体，如 `["Noto Sans Mono CJK SC"]` |
| `:gui-font-symbol` | `nil` | 箭头 / 符号字体，如 `["Symbola"]` |
| `:gui-font-emoji` | `nil` | 彩色 emoji 字体，如 `["Noto Color Emoji"]` |

### 3.6 搜索与进程输出

| 选项 | 默认 | 说明 |
|---|---|---|
| `:grep-program` | `nil` | 项目 grep 用哪个程序（`"rg"` / `"grep"`）。nil = 装了 rg 用 rg，否则 grep |
| `:repos-scan` | `nil` | `magit-repos-view`（`C-x p G`）扫描 git 仓库的根目录。nil = 当前项目根的上一级目录，再否则当前工作目录 |
| `:repl-buffer-maximum-size` | `1000000` | REPL / 进程输出 buffer 最多留多少字符（照 comint-buffer-maximum-size），超了从开头截到行首；`0` = 不限 |

## 4. LSP 选项

LSP 由 `:lsp` layer 提供（默认启用）。layer 默认值在 `coxn.layers.lsp`，
超时类默认值在核心 `default-options`。

### 4.1 行为开关

| 选项 | 默认 | 说明 |
|---|---|---|
| `:lsp-auto` | `true` | 打开有对应服务器的文件时自动 attach（`-Dcoxn.lsp.auto=false` 可改默认）。`M-x lsp` 手动 attach |
| `:lsp-auto-install` | `true` | PATH 找不到服务器时从官方源（GitHub releases / Eclipse / npm）异步下载到 `<config>/lsp/<name>`，装好自动重试。`M-x lsp-install-server` 手动装 |
| `:lsp-confirm-edits` | `true` | WorkspaceEdit（重命名等）先显示 diff 预览，`C-c C-c` 才应用 |
| `:lsp-on-type-formatting` | `true` | 触发字符（如 clangd 的 `.` `;`）之后按服务器要求自动格式化 |
| `:lsp-code-action-light` | `true` | point 处有诊断且停了 500ms ⇒ mode line 显示 💡（有可用 code action） |
| `:lsp-inlay-hints` | `false` | inlay hints（类型 / 参数名）。`M-x lsp-inlay-hints-mode`（`M-m m T i`）开关 |

### 4.2 超时

| 选项 | 默认 | 说明 |
|---|---|---|
| `:lsp-timeout-ms` | `3000` | 跳定义 / 重命名 / 格式化 / 补全等同步请求的超时 |
| `:lsp-eldoc-delay-ms` | `300` | point 停下多久后问函数提示（nREPL / LSP 共用） |
| `:lsp-sync-wait-ms` | `200` | 用户命令发的请求先同步等这么久，回来了当场出结果，否则转异步（不超过 `:lsp-timeout-ms`） |
| `:lsp-file-operation-timeout-ms` | `1500` | 改名 / 删文件前问服务器 willRename/willDelete  edits 最多等多久（且不超过 `:lsp-timeout-ms`），超时就当服务器没给编辑、照常动文件 |

### 4.3 服务器与服务器设置（无默认值，按需设）

| 选项 | 说明 |
|---|---|
| `:lsp-servers` | `{主模式 [[命令 参数…] …]}`，与各语言 layer 的内置清单**合并**（同模式覆盖）。按顺序找第一个装了的命令；参数里的 `:workspace-dir` 会换成 `<cache>/lsp/<命令>/<项目根哈希>`（jdtls 需要）。例：`(set-option! :lsp-servers {:c++ [["clangd" "--background-index" "--clang-tidy"]]})` |
| `:lsp-settings` | `{服务器命令名 设置map}`，按服务器名**深合并**到内置默认设置上；发给 initializationOptions.settings、workspace/didChangeConfiguration、workspace/configuration 三处。内置默认给了 jdtls（参数名 inlay hint 等）与 typescript-language-server（inlay hints 常用档）。例：`(set-option! :lsp-settings {"jdtls" {:java {:inlayHints {:parameterNames {:enabled "all"}}}}})` |
| `:lsp-init-options` | `{主模式 initializationOptions}`，initialize 时额外带给服务器 |
| `:lsp-connect` | `(fn [mode root])` 返回 `{:in :out :process}` 的替身连接，**测试用**，一般不设 |

## 5. 项目树（treemacs）选项

`:treemacs` layer（默认启用）。`C-x t t` / `M-m f t` 开关项目树。

| 选项 | 默认 | 说明 |
|---|---|---|
| `:treemacs-width` | `35` | 侧栏宽度（列） |
| `:treemacs-wide-toggle-width` | `70` | 树里按 `W` 加宽到这个值 / 再按回原宽 |
| `:treemacs-collapse-dirs` | `3` | 只有一个子目录的目录连起来显示（`src/demo`），最多连几层 |
| `:treemacs-show-hidden` | `true` | 显示隐藏文件（`.` 开头；`.git` 永远不显示） |
| `:treemacs-follow-mode` | `true` | 树跟随当前 buffer 的文件 |
| `:treemacs-filewatch-mode` | `true` | 文件监视重画（每 2 秒查一次） |
| `:treemacs-git-mode` | `true` | 按 git 状态给节点着色 |
| `:treemacs-sorting` | `:alphabetic-case-insensitive-asc` | 排序；目录永远在文件前。可选：`:alphabetic-asc` `:alphabetic-desc` `:alphabetic-case-insensitive-asc` `:alphabetic-case-insensitive-desc` `:size-asc` `:size-desc` `:mod-time-asc` `:mod-time-desc` |
| `:treemacs-space-between-root-nodes` | `false` | 多项目工作区里项目之间空一行吗 |
| `:treemacs-auto-hide-min-width` | `80` | 屏幕比这窄就不显示项目树；`nil` = 不自动藏 |
| `:treemacs-persist-file` | `<config>/treemacs-persist.edn` | 工作区（项目清单 / 展开状态）的存储文件 |

## 6. Clojure REPL（CIDER）选项

`:cider` layer（默认启用；自动带上 `:clojure` 语言基座）。`M-m m '` jack-in。

| 选项 | 默认 | 说明 |
|---|---|---|
| `:nrepl-version` | `"1.3.1"` | jack-in 时注入的 nREPL 版本 |
| `:cider-nrepl-version` | `"0.52.1"` | jack-in 时注入的 cider-nrepl 中间件版本 |
| `:cider-inject-middleware` | `true` | 注入 cider-nrepl 中间件（补全 / 文档 / 测试等增强）；关掉则只有裸 nREPL |
| `:cider-clojure-cli-aliases` | `nil` | deps.edn 项目 jack-in 时带上的别名，如 `":dev:test"`（拼在 `-M` 后） |
| `:cider-repl-pop-on-connect` | `true` | 连上后自动在另一个窗口弹出 REPL buffer |
| `:cider-show-error-buffer` | `true` | 求值出错时自动弹 `*cider-error*`（RET 跳到栈帧源码） |
| `:cider-shadow-default-build` | `nil` | shadow-cljs jack-in（`C-c M-J`）问 build 时的默认值，如 `:app`；`nil` = node-repl |

## 7. Common Lisp REPL（SLIME）选项

`:slime` layer（默认启用；自动带上 `:lisp` 语言基座）。`M-x slime` / `M-m m '`。

| 选项 | 默认 | 说明 |
|---|---|---|
| `:inferior-lisp-program` | `"sbcl"` | `M-x slime` 起哪个 Lisp。`C-u M-x slime` 从装了的里选 |
| `:slime-lisp-implementations` | `{}` | 实现表 `{名字 实现}`；实现可以是程序名 `"sbcl"`、带参数的向量 `["sbcl" "--dynamic-space-size" "4096"]`、或 `{:program [...] :eval-flag "..."}`。设了之后 `C-u M-x slime` 从这里选 |
| `:slime-swank-loader` | `nil` | 指定 slime 的 `swank-loader.lisp` 路径（支持 `~`）；nil = 从 quicklisp 载 `swank/exts`（需要 `~/quicklisp/setup.lisp`） |
| `:slime-completion` | `:simple` | 补全方式：`:simple` 普通前缀补全；`:fuzzy` 走 swank-fuzzy（`m-v-b` 这类缩写也能补） |
| `:slime-repl-history-size` | `200` | REPL 输入历史留多少条 |
| `:slime-compile-file-options` | `nil` | 编译文件时附加给 `swank:compile-file-for-emacs` 的参数（如 `[:verbose nil]` 这类 plist 片段） |
| `:slime-filename-translations` | `[]` | 本地 ⇄ Lisp 端路径翻译（远程 / 容器场景）：`[{:host-re "正则" :to-lisp (fn [path] ...) :from-lisp (fn [path] ...)}]`；`:host-re` 空 = 匹配所有路径 |
| `:clhs-root` | `"http://www.lispworks.com/documentation/HyperSpec/"` | CLHS 文档根地址（`M-m m h h` 查符号用）；可指向本地 `file://` 镜像 |

## 8. 其它 layer 的选项

### helm layer

minibuffer 本来就是 helm 手感（源标题 / 选中行 / flex 匹配 / orderless 分词）。
本 layer 贡献以下默认值（当前版本 minibuffer 行为内置，这些选项尚未被逐项消费，先作为约定保留）：

| 选项 | 默认 |
|---|---|
| `:helm-fuzzy-matching` | `true` |
| `:helm-follow-mode` | `false` |
| `:helm-display-bottom` | `true` |
| `:helm-completion-style` | `:helm` |

minibuffer 的位置请用核心的 `:minibuffer-display`（§3.2）。

### tree-sitter layer

| 选项 | 默认 | 说明 |
|---|---|---|
| `:tree-sitter` | `true` | 声明性默认值。**实际开关由 layer 选用决定**：`configuration-layers!` 里不含 `:tree-sitter` 就没有高亮，sexp 导航 / 缩进退回无树算法 |

## 9. Layer 选用

```clojure
(configuration-layers! [:tree-sitter :lsp :treemacs :git :clojure :cider :cpp])
```

- **不调用 = 全部内置 layer 都启用**（照 spacemacs 的 dotspacemacs-configuration-layers）。
- 没选中的 layer：不加载命令、不给键位、不挂钩子、它的选项没有默认值。
- 依赖自动带上：选 `:slime` 自动带 `:lisp`；选 `:cider` 自动带 `:clojure`。
- 选了 `:lsp` 时，各语言 layer 清单里的主模式自动挂上 lsp-deferred。

内置 layer（默认加载序）：

| layer | 内容 |
|---|---|
| `:tree-sitter` | 语法高亮 + 结构化编辑（sexp 导航 / 按树缩进） |
| `:lsp` | LSP 客户端：跳定义 / 引用 / 重命名 / 格式化 / 诊断 / 补全 / inlay hints |
| `:helm` | minibuffer 补全默认项 |
| `:treemacs` | 项目树侧栏 |
| `:git` | magit-status / log / blame / diff / repos，vc，smerge 合并冲突（项目与 grep 是核心功能，不在此 layer） |
| `:lisp` | Common Lisp 语言基座（主模式 / alive-lsp·cl-lsp 清单） |
| `:clojure` | Clojure 语言基座（clojure-lsp 清单） |
| `:cider` | Clojure nREPL REPL |
| `:slime` | Common Lisp SWANK REPL |
| `:erlang` | Erlang（ELP / erlang_ls） |
| `:elixir` | Elixir（elixir-ls） |
| `:cpp` | C / C++（clangd） |
| `:java` | Java（jdtls） |
| `:kotlin` | Kotlin（kotlin-language-server） |
| `:javascript` | JS / TS / TSX（typescript-language-server） |
| `:html` | HTML |
| `:css` | CSS |
| `:markdown` | Markdown |

## 10. 主题与 face

### 换主题

```clojure
(set-theme! :doom-dark)
```

- 内置 14 套：`:space-dark` `:space-light` `:doom-dark` `:doom-light`
  `:everforest-dark`（默认）`:everforest-light` `:token-dark` `:token-light`
  `:token-flint-dark` `:token-flint-light` `:token-temper-dark` `:token-temper-light`
  `:paper-light` `:paper-dark`，另有 `:terminal`（跟随终端底色，不刷正文底色）。
- `M-x load-theme` 交互选择（名字用自己的正文色画、带色块）；`M-m T n` 轮换。
- 交互选择记在 `<config>/theme.edn`，下次启动先用它；init.clj 的 `set-theme!` 压过它。

### 覆盖 face

```clojure
(set-face! :region {:bg "#3a3a5a"})
(set-face! :font-lock-comment-face {:fg "#7f8c98" :italic true})
```

颜色写 `"#rrggbb"` 或 `[r g b]`；可用属性：`:fg` `:bg` `:bold` `:italic`
`:underline` `:underline-color`。覆盖存在 `:face-overrides`，**换主题后照样生效**。

### 注册自己的主题

```clojure
;; 调色板式：拿内置调色板小改几个槽
(register-theme!
  {:name :my-dark :label "我的深色"
   :palette (palette-with (palette :space-dark) :keyword "#ff79c6")})

;; 差异式：只写要改的 face，其余回退到 :base（默认默认主题；:none = 不回退）
(register-theme!
  {:name :my-paper :label "我的纸张" :base :paper-light
   :faces {:region {:bg "#e8e0d0"} :cursor {:bg "#333333"}}})

(set-theme! :my-dark)
```

调色板槽名照 spacemacs-theme（`:bg1` `:base` `:keyword` `:func` `:comment` …，
全表见 `resources/coxn/themes.edn` 的 `:slots`）；每槽一个 `"#rrggbb"`，
或 `["#真彩" "#256色档"]` 两档。

## 11. 界面语言

```clojure
(set-language! :zh)   ; 已注册：en（源语言）/ zh
```

优先级：**init.clj > 持久化（`<config>/language.edn`）> 环境变量 > 默认 en**。
环境变量顺序：`COXN_LANGUAGE` > `LC_ALL` > `LC_MESSAGES` > `LANG`（`zh_CN.UTF-8` 这类取 `zh`）。
`M-x i18n-set-language` 交互切换并持久化；`M-x i18n-missing` 看当前语言还差哪些没翻。

自己的译文可以在 init.clj 里补：

```clojure
(coxn.i18n/catalog-merge! :zh {"Some message" "某条消息"})
```

## 12. 钩子与事件

### 钩子（hooks）

```clojure
(add-hook! :after-save-hook (fn [ed] (ed/message ed "saved!") ed))
```

函数收 editor、返回 editor；抛错只写 echo area，不中断编辑。可用钩子：

| 钩子 | 时机 |
|---|---|
| `:after-init-hook` | 启动完成后 |
| `:find-file-hook` | 打开文件后 |
| `:after-save-hook` | 存盘后 |
| `:kill-buffer-hook` | 关 buffer 前（在被关的 buffer 里跑） |
| `:kill-emacs-hook` | 退出时 |
| `:post-command-hook` | 每个输入事件之后 |
| `:post-self-insert-hook` | 自插入字符之后 |
| `:window-change-hook` | 窗口布局变化后 |
| `:tick-hook` | 主循环每轮（参数 now 毫秒） |
| `:change-major-mode-hook` / `:after-change-major-mode-hook` | 主模式切换前 / 后 |
| `<模式>-mode-hook`（如 `:clojure-mode-hook` `:prog-mode-hook`） | 进入主模式后 |
| `<次要模式>-hook`（如 `:slime-mode-hook`） | 次要模式开 / 关之后 |

`add-hook!` 第三参给深度（-100..100，缺省 0；`true` = 90，照 Emacs APPEND）。
buffer 局部钩子用 `coxn.hooks/add-local-hook`。

### 事件（bus）

```clojure
(subscribe! :document-opened (fn [event {:keys [buffer path new?]}] ...))
```

事件是**已发生的事实**（过去式 + 不可变 payload），handler 不返回 editor、不能 veto。
当前内置：`:document-opened`（`{:buffer :path :new?}`）、`:document-renamed`
（`{:buffer :new-buffer :path}`）。`subscribe!` 返回退订函数。

## 13. 键位绑定

```clojure
(bind-key! "C-c g" 'find-file)          ; 全局键
(unbind-key! "C-c g")
(prefix-name! "C-c l" "lsp")            ; which-key 里前缀的名字
```

键的写法照 Emacs：`C-` `M-` `S-` 组合，`"C-x C-f"` 这类空格分隔的序列。
命令名用符号（`M-x` 里看到的名字）。自己的命令：

```clojure
(defcommand my-hello "打个招呼。" [ed]
  (ed/message ed "hello!"))
(bind-key! "C-c h" 'my-hello)
```

## 14. buffer 级配置：EditorConfig 与 file-local

这两类配置只影响单个 buffer，优先于全局选项。

### EditorConfig

打开文件时从所在目录向上找 `.editorconfig`（`root = true` 处停止向上；
靠近文件的 section 覆盖上面的）。支持的标准属性：

| 属性 | 效果 |
|---|---|
| `indent_style` | `space` / `tab` |
| `indent_size` | 缩进宽度（`tab` = 用 tab_width） |
| `tab_width` | Tab 显示宽度 |
| `end_of_line` | `lf` / `crlf` |
| `trim_trailing_whitespace` | 存盘时删行尾空白 |
| `insert_final_newline` | 存盘时保证文末换行 |
| `max_line_length` | 行宽上限 |

### file-local variables

只认白名单，**绝不 eval 文件里的代码**。两种写法：

```c
/* -*- mode: c; indent-offset: 2; tab-width: 4 -*- */
```

或文件尾：

```
Local Variables:
fill-column: 80
End:
```

白名单：`mode`（只能切到已登记的主模式）、`comment-start`、`comment-end`、
`fill-column`、`indent-offset`、`tab-width`、`indent-style`、`insert-spaces?`、
`eol`、`trim-trailing?`、`final-newline?`、`truncate-lines`、`eval-minibuffer?`。

## 15. 环境变量与系统属性

| 变量 / 属性 | 作用 |
|---|---|
| `COXN_INIT` | 指定 init.clj 路径（优先于默认位置） |
| `COXN_LANGUAGE` | 界面语言（优先于 `LC_ALL` / `LC_MESSAGES` / `LANG`；init.clj 与持久化压过它） |
| `XDG_CONFIG_HOME` | 配置目录 `<config>` = `$XDG_CONFIG_HOME/coxn`（Linux/FreeBSD；缺省 `~/.config/coxn`；Windows 用 `%APPDATA%/coxn`） |
| `XDG_CACHE_HOME` | 缓存目录 `<cache>` = `$XDG_CACHE_HOME/coxn`（缺省 `~/.cache/coxn`；Windows 用 `%LOCALAPPDATA%/coxn`）。自动保存 / 备份 / LSP 自动安装都在这下面 |
| `COXN_DEBUG` | 设了 ⇒ TUI 开调试日志 |
| `COXN_NATIVE_PATH` | GUI 找 tree-sitter 动态库的额外目录（开发用） |
| `COLORTERM` / `TERM` / `WT_SESSION` | `:color-depth :auto` 的探测依据 |
| `-Dcoxn.config.dir` / `-Dcoxn.cache.dir` | 便携安装 / 测试：把配置 / 缓存目录指到别处（此时不做旧目录迁移） |
| `-Dcoxn.lsp.auto=false` | 把 `:lsp-auto` 的默认值改为关 |
| `COXN_JDK` | 构建用：`clojure -T:build dist` 打包用的 JDK 路径 |

## 16. 一份完整的 init.clj 示例

```clojure
;; ~/.config/coxn/init.clj

;; 选用 layer（不写 = 全开）
(configuration-layers!
  [:tree-sitter :lsp :treemacs :git :helm
   :clojure :cider :cpp :java :javascript :html :css :markdown])

;; 编辑
(set-option! :tab-width 4)
(set-option! :indent-offset 4)
(set-option! :fill-column 80)
(set-option! :electric-pair true)
(set-option! :display-line-numbers true)

;; 界面
(set-theme! :doom-dark)
(set-face! :region {:bg "#3a3a5a"})
(set-option! :minibuffer-display :bottom)
(set-option! :eldoc-display :echo)
(set-language! :zh)

;; GUI 字体（TUI 忽略）
(set-option! :gui-font ["JetBrains Mono" "Fira Code"])
(set-option! :gui-font-size 14)
(set-option! :gui-font-cjk ["Noto Sans Mono CJK SC"])

;; 补全 / LSP
(set-option! :completion-auto-delay-ms 200)
(set-option! :lsp-inlay-hints true)
(set-option! :lsp-servers {:c++ [["clangd" "--background-index" "--clang-tidy"]]})
(set-option! :lsp-settings
  {"jdtls" {:java {:inlayHints {:parameterNames {:enabled "all"}}}}})

;; 项目树
(set-option! :treemacs-width 40)
(set-option! :treemacs-follow-mode true)

;; REPL
(set-option! :cider-clojure-cli-aliases ":dev:test")
(set-option! :inferior-lisp-program "sbcl")
(set-option! :slime-completion :fuzzy)

;; 键位与钩子
(bind-key! "C-c g" 'find-file)
(add-hook! :after-save-hook
  (fn [ed] (ed/message ed "saved %s" (or (:file (ed/cur-buffer ed)) "?")) ed))
```
