# 给大语言模型 (Large Language Models, LLMs) 的语法指南

[纯文本版](https://raw.githubusercontent.com/dramark-md/dramark/refs/heads/main/docs/guide/llm-syntax-guide.md)

本指南基于 [DraMark Language Specification](https://github.com/dramark-md/dramark/blob/main/spec/spec.md)（v0.4.1，2026-03-19），面向需要让 LLM 生成 DraMark 文本的场景。

目标：让模型稳定产出“可解析、少歧义、可直接落地”的剧本文本。

## 一、先记 10 条硬规则

1. 角色声明必须独占一行：`@角色名`。  
2. `@@` 独占一行表示退出角色语境。  
3. 唱段用 `$$` 包裹，支持 `$$ 标题`。  
4. 唱段内可用 `!! ... !!` 临时切到念白段落。  
5. 译配起始必须是 `= `（等号后有空格），退出是独占一行 `=`。  
6. 行内 Tech Cue 是 `<<...>>`，必须同一行闭合。  
7. 块级 Tech Cue 用 `<<< ... >>>` 或多行 `<<<` 到 `>>>`（也兼容回退闭合 `<<<`）。  
8. 注释 `%` 作为行内注释时，前面必须有空白。  
9. `---` / 标题 `#` 是结构边界，会触发状态重置（根级有效）。  
10. 代码保护区最高优先级：围栏代码块和行内代码里的 DraMark 标记全部失效。

## 二、推荐输出骨架（给 LLM 的默认模板）

```dramark
---
meta:
  title: 标题
  author: 作者
translation:
  enabled: false
---

# 第一幕

场景说明（GlobalBlock）。

@角色A
台词一。

@角色B [情绪]
台词二。{动作} <<LX01 GO>>
@@

角色B说完后的舞台调度、场景描述（GlobalBlock）。

@角色A
下一段台词。

---

$$ 歌曲标题
@角色A
唱词 A

!!
@角色B
这里是唱段中的念白
!!

@角色A
继续唱词
$$
```

**关键模式**：`@角色` 进入 → 台词 → `@@` 退出 → 场景动作 → `@下一角色` 进入。没有 `@@` 的话，场景动作会被当成上一个角色的台词。

## 三、状态机思维（生成时最重要）

可把生成过程理解为一个块栈：

- 默认在 GlobalBlock（念白/场景动作语境）
- `@` 进入 CharacterBlock
- `@@` 退出 CharacterBlock，回到 GlobalBlock（**写场景动作前必须先 `@@`**）
- `= ` 进入 TranslationBlock
- `$$` 进入 SongBlock
- `!!` 在 SongBlock 内开启/关闭 SpokenSegment
- `<<<` 进入 TechCueBlock，`>>>` 或回退 `<<<` 关闭
- `---` / `#` 重置到 GlobalBlock（同时关闭 CharacterBlock 等）

遇到不兼容新指令时，先关内层再开外层。闭合顺序可记为：

`CommentBlockState -> TechCueBlock -> TranslationBlock -> CharacterBlock -> SongBlock`

**常见错误**：在 `@角色` 后直接写场景动作（没有 `@@`），结果场景动作被当作台词。

## 四、译配输出规范（LLM 高发错误区）

正确：

```dramark
@冉阿让
= Who am I?
我是谁？
= Can I conceal myself?
我能否隐瞒真相？
```

错误示例：

```dramark
@冉阿让
=Who am I?   % 错：等号后缺空格，不是译配起始
```

显式退出译配：

```dramark
=
回到普通对白。
```

## 五、角色名与歧义规避

- 支持空格角色名，推荐加引号：`@"冉 阿让"`。  
- 可选多角色声明：`@Peter Pan @Wendy [aside]`。  
- 不要写 `@角色 台词同一行`（strict 模式会降级为普通文本并报警告）。

## 六、Tech Cue 生成策略

- 行内短提示优先：`<<SND: THUNDER>>`。  
- 多行调度用块级：

```dramark
<<< LX
面光渐暗 <<LX01-FADE>>
追光预备 <<LX02-READY>>
>>>
```

- 在 TechCueBlock 外看到 `>>>`，通常应按 CommonMark 处理，不要强行当 DraMark 闭合。  
- 块级 Tech Cue 不做块级嵌套（内部 `<<< ...` 默认当文本，除非作为对称回退闭合条件满足）。

## 七、注释与转义

- 行首 `%` 是注释行。  
- 行内注释必须写成 `文本 空格% 注释`。  
- 需要字面量符号时使用转义：`\@ \% \$ \{ \} \< \> \= \``。

## 八、代码保护区（必须遵守）

以下区域内，LLM 不应触发任何 DraMark 语义：

- 围栏代码块（``` 或 ~~~）
- 行内代码（`...`）

示例（应全部按字面量保留）：

````dramark
```cpp
vector<vector<int>> a;
std::cout << "Hello >>";
```
````

## 九、给 LLM 的“生成约束提示词”可复用片段

```text
你在输出 DraMark（v0.4.1）时必须遵守：
1) @角色声明独占一行；不要写成"@角色 台词同一行"。
2) 需要在角色台词之间写场景动作时，必须先写 @@ 退出角色。
3) 译配起始使用"= 空格原文"；单独"="表示退出译配。
4) 唱段使用 $$ 包裹；唱段内可用 !!...!! 插入念白。
5) 行内 Tech Cue 必须是同一行内闭合的 <<...>>。
6) 代码块和行内代码中的特殊符号全部视为普通文本。
7) 若不确定，优先生成简单、可闭合、少嵌套结构。
```

## 十、最小自检清单（输出后）

1. 是否存在 `@角色 台词同一行`？有则改为两行。  
2. 是否在 `@角色` 后直接写场景动作（忘了 `@@`）？有则在中间插入 `@@`。  
3. 是否把 `=原文` 写成了无空格形式？有则改为 `= 原文`。  
4. 每个 `$$`、`!!`、`<<<` 是否都能闭合？  
5. `<<...>>` 是否都在同一物理行闭合？  
6. 代码块/行内代码内是否误用了 DraMark 语义解释？

通过以上检查，通常即可得到稳定可解析的 DraMark 文本。