STL syntax highlighting

给你 .md 里的 STL（Semantic Tension Language，语义张力语言）代码块做 6 色 token 高亮——让 STL 知识图谱语句在 markdown 里像代码一样可读，而不是一团乱码。

这是什么 / 谁会用

STL 是一个把"语义关系"写成可读字符串的小语言：

[Source] -> [Target] ::mod(key=value, key=value)

它最初是 STG (Semantic Tension Graph) 项目的输入格式——但任何人想把"知识图谱片段、引用关系、断言、思维节点"嵌进 markdown 里，都可以用它。

你需要这个能力如果：

✅ 你在写研究笔记，需要表达节点之间的关系（"A 蕴含 B"、"X 反驳 Y"）
✅ 你做知识管理，希望文档里直接写知识图谱片段
✅ 你写复杂主题的结构化笔记（理论之间的关系、概念依赖、决策链）
✅ 你想给 AI agents 喂结构化语义（LLM 容易学 STL）
❌ 你只写普通文章——这能力你大概率用不到，可以跳过本篇

Basic syntax

把 STL 语句包在 ```stl 代码块里：

```stl
[REST_API] -> [HTTP_Layer] ::mod(rule="definitional", confidence=1.0, description="REST 建立在 HTTP 语义之上")
```

渲染：6 色 token 着色，让 anchor / arrow / key / value / 关键字 / 注释一目了然。

Token 着色

Rho 内置的 STL grammar 把 STL 切成 6 类 token，每类一种颜色：

Token	例子	颜色（典型 dark theme）
Anchor	`[User_Profile]`、`[Module:Auth]`	青绿 (cyan)
Arrow	`->`、`→`	黄 (yellow)
Modifier key	`rule=`、`confidence=`、`action=`	紫 (purple)
Modifier value (string)	`"depends_on"`	绿 (green)
Modifier value (number)	`0.99`、`100`	橙 (orange)
Comment	`# 这是注释`	灰 (gray)

具体颜色随主题（light / dark / 自定义）变化，但6 类语义角色固定。

跟 Annotate 是两回事：annotate 是手工标注任意文本，stl 是自动按 STL grammar 高亮 STL 代码。一个手动一个自动。

Examples

Example 1：最简边

```stl
[A] -> [B] ::mod(rule="causal", strength=0.8)
```

渲染：[A] 和 [B] 青绿，-> 黄，rule= 和 strength= 紫，"causal" 绿，0.8 橙。一行能看清"这是 A 因果引发 B 强度 0.8"。

Example 2：研究笔记里嵌入语义网络

气候变化的因果链概览：

```stl
[Climate_Change] -> [Greenhouse_Gas_Emissions] ::mod(rule="causal", confidence=0.97, strength=0.92, description="主因果驱动")
[Greenhouse_Gas_Emissions] -> [CO2] ::mod(action="dominated_by", confidence=0.95)
[CO2] -> [Fossil_Fuel_Burning] ::mod(action="primarily_from", confidence=0.95)
[CO2] -> [Deforestation] ::mod(action="also_from", confidence=0.85)
[Climate_Change] -> [Sea_Level_Rise] ::mod(action="leads_to", confidence=0.90)
```

注意 confidence 从 0.97 (强证据) 递减到 0.85 (二级因素仍在量化)。

渲染：5 行 STL 整齐高亮，confidence 数字（橙色）跟正文叙述形成视觉呼应。

Example 3：含注释 + 多 modifier

```stl
# 数据库选型决策记录 (2026-05-14)
[Database_Choice] -> [PostgreSQL] ::mod(
  rule="empirical",
  confidence=0.95,
  action="selected_over",
  alternatives="MySQL, MongoDB, DynamoDB",
  occurred_time="2026-05-14",
  lesson="JSONB 支持 + 成熟生态 + ACID 完整 + 团队熟悉"
)
```

渲染：注释行灰色，多行 modifier 缩进；每个 key/value 对色编。比单行更易读，跨行的语义结构清晰。

Example 4：跟普通代码块对比同写法

普通 ` ```text ` 代码块（无高亮）：

\```text
[A] -> [B] ::mod(rule="causal")
\```

Rho 的 ` ```stl ` 代码块（有高亮）：

```stl
[A] -> [B] ::mod(rule="causal")
```

渲染：两块字符内容完全相同，但下方 stl 块每个 token 着色，语义结构一眼可见。差别就是 fenced block 的 lang 标签。

Plain-text fallback behavior

stl lang 是标准 markdown fenced code block lang 标签。在不支持 STL grammar 的 reader 里：

```stl
[A] -> [B] ::mod(rule="causal")
```

→ 显示为普通代码块（等宽字体、灰底）——内容完全可读，只是失去 6 色 token 编码。

具体各 reader：

Reader	渲染效果
Rho	完整 6 色高亮
GitHub web	普通代码块（无 STL 高亮，但内容清晰）
Obsidian	同上（除非装了 STL highlight 插件）
VS Code 默认预览	同上
任何 markdown reader	至少识别为 code block，等宽字体

Rho 用 highlight.js / lowlight 系统注册 STL grammar，所以任何接入 hljs / lowlight 的 reader 都能集成同一份 STL grammar。Rho 提供导出函数：
import hljs from 'highlight.js';
import { stlLanguage } from '@rho/md';
hljs.registerLanguage('stl', stlLanguage);

Common pitfalls

1. 把 STL 写成 markdown 链接语法

[A] -> [B]

→ 这看起来像 markdown 链接 [A] 但没有 (url)，markdown 解析器会保留原文。没问题——不会被错误解析为链接。但要注意：

[A](http://...) -> [B]   ← ❌ 这会变成真链接，破坏 STL 解析

STL 中的 [X] 不应跟 (...) 紧接。

2. anchor 名含空格

[User Profile] -> [...]   ← ⚠️ 部分 reader 解析未定义
[User_Profile] -> [...]   ← ✅ 推荐：用 `_` 替代空格

STL spec 推荐 anchor 名使用 [A-Za-z0-9_:-] 字符，不含空格。需要"看着是空格"时用 _、-、:。

3. value 含双引号

[A] -> [B] ::mod(description="he said "hello"")     ← ❌ 嵌套引号 broken

→ 嵌套未转义的 ASCII 双引号会提前 close 字符串，整段 STL 解析报废。解决：

用中文/全角 「」 / ""
或转义 \"（部分解析器支持）
或用单引号包外层（如果支持）

4. modifier 之间忘记逗号

[A] -> [B] ::mod(rule="causal" confidence=0.8)     ← ❌ 缺逗号
[A] -> [B] ::mod(rule="causal", confidence=0.8)    ← ✅

5. 用 stl 高亮非 STL 内容

function foo() { return 1; }     ← ❌ 这不是 STL，高亮会乱

→ STL grammar 只识别 STL 语法 token，喂给它 JS / Python / 其他东西会乱标色或完全不标。只在真正是 STL 的代码块上用 ```stl lang label。

6. 想要做"普通文本里强调 STL 风格的字符串"

正文里随手写 [A] -> [B] 这样的伪 STL 想要高亮     ← ❌ 不工作

→ STL 高亮只在 fenced code block 里生效。正文里的 [A] -> [B] 字符串只会被 markdown 当成"破链接 + 文本 + 文本"。如果要在正文中强调 STL 表达式，包成 inline code： `[A] -> [B] ::mod(rule="causal")` —— 不会高亮，但至少视觉上像代码。