数学公式速写 huanglianqi/dsh-math-snippets

dsh-math-snippets

LaTeX-Suite 风格的 DSH 网页编辑器中的片段展开。触发表基于 Obsidian LaTeX Suite 自身的默认配置构建——相同的触发器、相同的自动/Tab 划分、相同的制表位编号——因此肌肉记忆可以直接迁移过来。

$// → $\frac{}{}$ 无需 Tab：自动片段在输入时即展开 $sum → $\sum_{i=1}^{n} $ $ff → $\frac{}{}$ 本插件的简短配对，按 Tab 或单独触发 mk → $$ 数学环境之外，光标位于美元符号之间 dm → $$⏎⏎$$ 行间公式，光标位于空行上 $@a → $\alpha LaTeX Suite 的希腊字母拼写，同样自动 $sr → $^{2} 以及 _、cb、rd、、->、34 先将光标置于分子，然后是分母，最后是分式之后。

安装 sh
dsh plugin --profile add dsh-math-snippets

之后重启 harness（配置文件的 bundle 列表在启动时读取），然后重新加载 GUI 页面。

改为从检出目录安装

在配置文件的 cordis.patch.yml 中添加一行： yaml
- insert:
- id: math-snippets
name: 'file:///path/to/dsh-math-snippets/index.js'

与 LaTeX Suite 的一致性

该表并非手写的近似实现：它由 LaTeX Suite 的 src/default_snippets.js 生成，保留每一个可以表示为纯字符串片段的条目。142 个标签，其中 138 个为自动，4 个保留在 Tab 上。

| 相同 | 触发器词汇表（//、@a、sr、cb、rd、_、、->、=、!=、oo、sum、lim、dint、hat、bar、vec、norm、ceil、floor、text、…），哪些触发器是自动的、哪些需要 Tab，w 词边界标志，以及 $0、$1、$2 制表位顺序 |
| 相同 | ${1:\infty} 占位符语法可以解析（默认文本会被丢弃——见下文） |
| 不同 | LaTeX Suite 刻意保留在 Tab 上的四个——par、\sum、\prod、\int——在这里也保留在 Tab 上，这正是重点 |
| 不同 | dm 不会像 LaTeX Suite 那样前置换行符。在笔记中你总是希望行间公式独占一行；而在聊天编辑器中，常见情况是你已经位于空行上，那个换行符会留下一个空的首段 |
| 不同 | 输入时不进行公式的隐藏/渲染，不自动放大括号，不支持向后展开，不支持正则/可视/函数片段，并且 ${1:x} 占位符文本不会被预选中：shell 没有暴露选择接口，因此空位是空的 |

片段表

首次启动时，宿主端会将一个可编辑的表写入 ~/.dsh/math-snippets.json，其中包含所有内置触发器，并在以下位置提供生效的表： /plugin/math-snippets/table。浏览器端每分钟重新读取一次该路由，因此编辑无需重启或刷新页面即可生效。

每个条目为 { "body": "...", "auto": true }：

| 字段 | 含义 |
| body | 触发器展开后的内容。$0、$1、$2……是占位符，按 Tab 键会按数字顺序依次访问它们；也接受 ${1:\infty} 这种写法。没有占位符的 body 会把光标留在文本之后。 |
| auto | 为 true 时，在完成触发器的按键上直接展开，无需按 Tab。此处默认如此，与 LaTeX Suite 一致。 |
| open | 为 true 时允许触发器在数学环境之外生效（用于 mk 和 dm，它们是你进入数学环境的方式）。其他所有条目仅在 $…$、$$…$$、\(…\) 或 \[…\] 内触发。 |
| word | 为 true 时还要求触发器后跟一个分隔符，因此 dmx 中的 dm 仍被视为一个单词。取自 LaTeX Suite 的 w 标志。 |
| desc | 供你自己使用的自由格式备注；展开器不会使用它。 |

示例——添加你自己的条目： json {
"snippets": {
"capm": { "body": "$E[R_i]=R_f+\\beta_i(E[R_m]-R_f)$", "auto": true },
"npv": { "body": "\\mathrm{NPV}=\\sum_{t=0}^{n}\\frac{CF_t}{(1+r)^t}" },
"par": { "body": "\\frac", "auto": true }
}
}

文件中的标签会逐字段覆盖同名的内置标签，因此一个仅重述了 body 的条目会保留内置标签的 open/auto/word 开关——而显式的 "auto": false 则会关闭其中一个。最后这一点正是逃生出口：如果某个自动触发器在你还在输入一个单词时就触发了，就把那个标签改为按 Tab 触发。

两种标签

| 标签 | 类型 | 匹配方式 |
| ff、sum、alp | 裸词 | 光标前的整个单词（xff 是词元 xff，而非 ff） |
| //、@a、_、sr | 字面串 | 光标前的精确字符；表中匹配最长的条目胜出 |

当标签全为字母时是裸词，否则是字面串，因此 //、_、、->、@a 和 :e 都有效。有两项例外规则使字面串不会在 URL 中触发，与 shell 自身的 / 规则相呼应：紧跟在另一个斜杠之后的斜杠不会触发（/// 无效），而 scheme: 冒号之后的斜杠对也不会触发，因此 https:// 永远不会激活分数。

工作原理

shell 已经公开了四个接缝，无需编辑 DOM，也无需 fork 编辑器：

1. 光标来自 shell.projection，即编辑器自身的投影产物
（{ detectText, clipboardText, selection, caret }）。caret 是
detectText 中的一个偏移量——与输入 span 使用的坐标空间相同——因此无需从 DOM 中测量任何内容。
2. 替换以 shell 为其自身输入触发源安装的作用域输入事件进行派发：
actx.bail(actx, "slash/input-insert-text", { text, span })，其中
actx = sessions.scope(sessionId)，span = { start, end, draftRev }。shell
会拒绝 draftRev 不再匹配的 span，因此过期的按键永远不会破坏草稿。
3. 这个洞不需要 caret API，因为 shell 总是把 caret 留在它插入的内容之后。因此展开是先放尾部，再把头部放在尾部起始处的折叠点——头部把尾部向右推，caret 最终正好落在洞里。这就是为什么第二次插入使用 start === end。
4. 不用 Tab 打字依赖 keyup，而不是草稿订阅：到那时字符已经提交，shell 也已经重新投影，而且它是一个普通事件，而不是在编辑器自身更新中引发的通知，所以插入走的是与 Tab 本会走的相同作用域路径。

行为与限制

- 默认自动，Tab 始终可用。 除 par、\sum、\prod 和 \int（LaTeX Suite 保留在 Tab 上的四个）之外，每个标签都会在输入时展开；Tab 可以展开其中任何一个，其余标签从不需要 Tab。
- 只有当确实应用了某些内容时，Tab 才会被消耗。 其他每一次按键，以及每一个不匹配的触发器，都会原样通过——包括 Tab 的通常含义。
- Tab 会遍历这些洞。 下一个洞每次都会被重新查找——遍历会从 caret 向前搜索正文中位于两个洞之间的字面量——因此在洞中输入任意数量的内容都不会使任何东西移动，而在洞内输入的展开仍然优先于遍历。将 caret 移回你被放入的洞之前，或者带有文件 chip 的草稿（检测坐标和剪贴板坐标在那里会分歧），都会让遍历停止并把 Tab 交还。遍历并非没有代价：shell 不发布裸 caret 移动，所以每次跳转都是一次编辑，会写回它所替换的确切文本——草稿最终保持不变，但跳转会消耗一个撤销步骤。
- 散文是安全的。 没有 "open": true 的片段永远不会在数学环境之外触发，所以在句子中输入 sum 不会有任何效果。紧贴数字的 $ 会被解读为货币符号，所以 costs $5 and $10 不是数学。代码 span 和围栏代码块会被整体跳过。
- LaTeX 命令永远不会是触发器。 单词路径会拒绝紧跟在 \、/、@ 或 # 后面的触发器，因此输入 \operatorname 不会触发 op。只有三个显式字面标签 \sum、\prod 和 \int 会匹配反斜杠，而且它们仅限 Tab。
- 自动在较长的单词上仍可能出人意料。 输入 par 没问题（仅限 Tab），但一个以自动触发器开头的裸词会在触发器处展开，所以 integral 会变成 \int…egral。word: true 只防护触发器后面已经跟着字符的情况。按标签用 "auto": false 修复它，或者按 Cmd/Ctrl+Z——撤销步骤会恢复所输入的触发器。
- 整个单词才是触发器。 xff 产生 token xff，而不是 ff：单词片段永远不能从单词中间触发。字面触发器仍然可以在那里触发，因为 x// 在 LaTeX Suite 中也是分数。
- 正文中的 $ 是洞标记。 字面 $ 目前无法写在正文中，而 ${1:default} 会丢失其默认文本。

诊断 sh
curl -s http://127.0.0.1:/plugin/math-snippets/status # 已挂载 + 计数
curl -s http://127.0.0.1:/plugin/math-snippets/table # 生效的表格

仅限回环 Host。

测试 sh
npm test

62 条断言，无测试框架，无浏览器。分两层：按键路径针对一个模拟 shell 的 span 语义的假 composer 运行（span 替换、插入后的光标位置、折叠插入、过期修订拒绝），因此空位放置、制表位遍历和自动路径都在真正重要的层面被断言——即生成的文本以及光标最终落在哪里——随后 seat 本身再针对假文档和假 shell 进行渲染，因此依赖接线、composer 门控、捕获监听器及其清理也都得到了检验。

兼容性

针对 dsh 0.1.5-rc.2 编写并验证（客户端包 0.1.5-rc.2，DSH Desktop 2.0.13）。投影产物和 slash/input-insert-text 契约是从该版本的源码中读取的；更新的 shell 可能会改动其中任意一个。

许可证

MIT