跳转至

变量

在 MarkdownFlow 中使用变量

变量是 MarkdownFlow 中为共享上下文命名的进阶方式。它们作为占位符，在处理时被替换为实际值。

对于大多数单文档 MarkdownFlow 体验，交互控件不需要变量。直接写 ?[选项 A | 选项 B] 或 ?[...输入提示]，然后在后续提示词中自然引用用户的回答即可。当某个值由平台提供，或需要跨不同 MarkdownFlow 文档共享时，才使用变量。

基本语法

变量使用双大括号：

{{变量名}}

共享上下文示例：

向 {{用户名}} 打招呼，并提醒他们当前账户余额为 {{余额}}。

变量命名规则

变量名称区分大小写，必须遵循以下规则：

  • 可以包含：字母（包括中文、日文等 Unicode 字母）、数字和下划线
  • 不能包含：特殊字符、空格、标点符号或 } 字符
  • 不能为空：必须至少包含一个字符
  • 大括号与名称之间不能有空格：{{ var }} 不会被识别为变量

有效的变量名称

{{name}} ✓ 简单字母
{{userName}} ✓ 驼峰命名法
{{user_name}} ✓ 下划线命名法
{{UserName}} ✓ 帕斯卡命名法
{{user123}} ✓ 包含数字
{{_private}} ✓ 以下划线开头
{{CONSTANT}} ✓ 全大写
{{a}} ✓ 单个字符
{{123user}} ✓ 以数字开头
{{用户名}} ✓ Unicode 字符（中文）
{{ユーザー}} ✓ Unicode 字符（日文）
{{пользователь}} ✓ Unicode 字符（俄文）
{{utilisateur}} ✓ Unicode 字符（法文）

无效的变量名称

{{user}name}} ✗ 包含 } 字符
{{user name}} ✗ 名称内包含空格
{{user-name}} ✗ 包含连字符
{{user.name}} ✗ 包含点号
{{user@email}} ✗ 包含特殊字符
{{🚀rocket}} ✗ 包含表情符号
{{name[0]}} ✗ 包含方括号
{{user+id}} ✗ 包含加号
{{}} ✗ 空变量
{{   }} ✗ 只有空格
{{ name }} ✗ 大括号与名称之间有空格（不会被识别为变量）
{{ name}} ✗ 名称前有空格（不会被识别为变量）
{{name }} ✗ 名称后有空格（不会被识别为变量）

变量如何工作

1. 来源

变量从多个来源获取它们的值：

用于跨文档共享的命名交互输入：

请用户输入一个需要提供给后续 MarkdownFlow 文档的资料名称。
?[%{{共享资料名称}} ...请输入您的姓名]

在另一个 MarkdownFlow 文档中，为 {{共享资料名称}} 生成温暖的问候。

不要给普通的单文档交互添加 %{{变量名}}。命名变量形式用于共享状态。

系统预定义变量：

系统变量由平台预先定义，无需用户输入即可直接使用。不同平台提供不同的系统变量：

MarkdownFlow Playground：

  • {{browser_language}} - 用户的浏览器语言（例如 "en-US"、"zh-CN"）

AI-Shifu Platform：

  • {{sys_user_nickname}} - 用户的显示名称
  • {{sys_user_style}} - 用户偏好的内容风格
  • {{sys_user_background}} - 用户的背景信息
  • {{sys_user_language}} - 用户的语言偏好

2. 变量替换

在 LLM 处理内容之前，MarkdownFlow 智能体会将所有变量替换为实际值：

之前："为正在以 {{水平}} 水平学习 {{主题}} 的 {{用户名}} 生成个性化问候。"
之后："为正在以 初级水平 学习 Python 的 张三 生成个性化问候。"

然后 LLM 处理这个解析后的提示词，为读者生成实际内容。

3. 未赋值的变量

如果变量尚未赋值，将被替换为 "UNKNOWN"：

之前："为对 {{主题}} 感兴趣的 {{用户类型}} 生成内容。"
之后："为对 UNKNOWN 感兴趣的 UNKNOWN 生成内容。"

重要提示： 请确保在使用变量前为其赋值（通过共享交互状态或系统默认值），避免提示词中出现 "UNKNOWN"。当 LLM 接收到含有 "UNKNOWN" 的提示词时，可能会产生不可预测的结果。

不同上下文中的变量

当您使用共享变量时，它们可以出现在文档中的任何位置：

在文本中

生成一个让 {{用户名}} 感到亲切的个性化欢迎词。

在标题中

# 第 {{章节编号}} 章：{{章节标题}}

在列表中

以清晰的列表格式总结用户的产品选择：
- 选择的颜色：{{选定颜色}}
- 选择的尺寸：{{选定尺寸}}  
- 期望的数量：{{数量}}

在链接和图片中

[访问 {{网站名称}}]({{网站网址}})
![{{图片描述}}]({{图片路径}})

在表格中

创建一个格式化表格展示用户的账户信息：
| 属性 | 值 |
| ---- | --------------------- |
| 姓名 | {{用户名}} |
| 邮箱 | {{用户邮箱}} |
| 方案 | {{订阅方案}} |

在 HTML 中

<div class="{{theme_class}}">
  <span id="user-{{user_id}}">{{display_name}}</span>
</div>