Mephisto — VS Code 扩展

Mephisto 叙事引擎的 VS Code 扩展，为编写 .meph 契约文件提供语法高亮、实时诊断、代码补全、悬停提示、跳转定义、文档格式化和大纲视图。

语法指南

注释（`#`）

以 # 开头的行被视为注释，在解析时会被忽略：

# 这是一个注释
# 注释可以出现在任何位置

注意：行尾注释（如 - name: value # 注释）不支持。# 必须位于行首（或前面只有空格）才能被识别为注释。

区块结构

Mephisto 文件由若干个区块组成，每个区块以 【区块名】 开头：

区块名	说明
`【角色名】`	当前角色的名称，单行文本
`【锚点】`	键值对列表，用于存储静态设定
`【世界观】`	纯文本，描述世界背景
`【角色背景】`	纯文本，描述角色背景故事
`【开局场景】`	纯文本，描述初始场景
`【状态】`	键值对列表，存储运行时状态变量
`【规则】`	规则列表，定义条件-动作响应
`【记忆】`	纯文本列表，存储角色记忆条目
`【历史】`	对话记录列表，格式 `- fate/assistant: 内容`

未知区块名会被当作"草稿区块"处理，不报错。

列表条目

以 - 开头的行表示列表条目：

- 条目一
- 条目二

键值对

在 【锚点】 和 【状态】 区块中使用，支持中文冒号和英文冒号：

- 键: 值
- 键：值

规则语法

在 【规则】 区块中使用：

[规则名] if 条件 -> 动作
[规则名] if 条件 -> [group:组名] 动作   # 互斥组：同组规则互斥触发
[规则名] if 条件 -> 注入 "内容"          # 注入记忆（不直接输出）
[规则名] if 条件 -> 状态.键 = 新值       # 修改状态

条件支持：

字符串比较：包含 "关键词"、不包含 "关键词"
状态比较：状态.键 == 值、状态.键 != 值、状态.键 > 数值
逻辑运算符：&&、||

占位符变量

在字符串中使用 {变量名} 引用区块内容：

【角色名】
梅菲斯特

【规则】
[低语] if true -> 注入 "{角色名}在黑暗中低语"

支持在双引号 " 和中文引号 “” 内高亮。

历史记录

- fate: 命运的指令内容
- assistant: 角色的回应内容

支持 \n 转义表示换行。

特性

Mephisto 编辑器总览

✨ 语法高亮

元素	颜色示例
注释 `#`	灰色
区块名 `【角色名】`	黄色
规则关键字 `if`、`->`	紫色
字符串 `"..."` `“…”`	绿色
`{变量名}`	青色
`状态.键`	蓝色
`注入`	紫色
`fate`/`assistant`	青色
规则名 `[规则名]`	黄色
数字 `100`	橙色
运算符 `&&` `==` `!=`	白色

🔍 实时诊断

打开 .meph 文件时自动检查：

❌ 内容出现在任何区块之外
❌ 区块标题格式错误（缺少 【 或 】）
❌ 重复的区块名
❌ 规则缺少 -> 分隔符
❌ 键值对缺少 : 或 ：
❌ 规则名、条件、动作为空

🔧 代码补全

类型	触发方式
区块名	在 `【】` 之间输入任意字符（已存在的区块自动过滤）
状态键	输入 `状态.`
规则名	在 `【规则】` 区块中输入 `[`
动作	在 `->` 后输入
规则模板	在 `【规则】` 区块中输入 `rule`

规则模板

输入	展开结果
`rule` ⭾	`[规则名] if 条件 -> 动作`
`rulei` ⭾	`[规则名] if 条件 -> 注入 "内容"`
`ruleg` ⭾	`[规则名] if 条件 -> [group:组名] 动作`

选择后按 Tab 在占位符之间跳转填写。

🖱️ 悬停提示

元素	显示内容
状态键	当前值、数据类型（字符串/整数/布尔值）、行号
规则名	条件、动作、互斥组、行号
锚点键	值、行号
`fate`	"命运的指令，由用户输入推动叙事"
`assistant`	"角色的回应，由 LLM 生成或规则驱动"

🎯 跳转到定义

Ctrl+点击 或 F12：

{角色名} → 跳转到 【角色名】 区块的内容行
状态.键 → 跳转到 【状态】 区块中对应的键值对定义

📝 文档格式化

使用 Shift+Alt+F 格式化整个文档：

规则	效果
区块标题顶格	所有 `【区块名】` 左对齐
内容缩进	区块内容统一缩进 2 个空格
空行压缩	连续多个空行压缩为 1 个
规则表达式规范化	运算符之间空格统一为单个

📋 大纲视图

在 VS Code 的大纲面板中查看文档的区块结构，点击快速跳转。

⌨️ 自动缩进

操作	效果
`【区块名】` 后按 Enter	自动缩进
列表行 `-` 后按 Enter	自动延续 `-`
注释行 `#` 后按 Enter	自动延续 `#`
规则定义行末按 Enter	保持缩进

使用

创建一个 .meph 文件
开始编写你的契约
实时诊断会自动检测语法错误
使用 Ctrl+Space 触发代码补全
使用 Shift+Alt+F 格式化文档
使用 Ctrl+点击 跳转到定义

测试

项目包含 26 个测试用例，覆盖诊断、补全、悬停、跳转定义、格式化等功能：

pnpm test

Mephisto

yuelinghuashu