docs(declare): document the YAML declare format

Update the journal-set doc entry, the CLI diagnostic table, and the
authoring skill, along with the in-app empty-state hint and the var
message comment.
This commit is contained in:
hyper
2026-09-12 22:51:12 +08:00
parent 0ac9a833e4
commit 0b029b325e
5 changed files with 59 additions and 41 deletions
+53 -35
View File
@@ -3,11 +3,11 @@ tag: journal-set
icon: 🔢
title: 变量系统
description: 在文档中声明变量和标签,通过 /set 命令设置变量值,自动计算派生变量和标签效果。
syntax: '```csv role=declare'
syntax: '```yaml role=declare'
props:
- name: 定义文件
type: —
desc: 在任意 .md 文档中使用 ```csv role=declare 代码块定义变量和标签
desc: 在任意 .md 文档中使用 ```yaml role=declare 代码块定义变量和标签
- name: 命令
type: —
desc: /set $key expression | /set $key #tag1:count1;#tag2:count2
@@ -28,37 +28,48 @@ props:
## 代码块语法
```csv role=declare
tag,threshold,key,expr
,,$hp,$con*5+$mod_hp
,,$ac,10+$dex
#warrior,1,$mod_hp,20
#warrior,2,$mod_str,1
以 `yaml role=declare` 代码块定义,正文为 YAML:
```yaml role=declare
vars:
$hp: $con*5 + $mod_hp
$ac: 10 + $dex
tags:
warrior:
1:
$mod_hp: 20
2:
$mod_str: 1
```
| 列 | 说明 |
| 键 | 说明 |
|---|---|
| `tag` | 标签名(空表示普通变量声明) |
| `threshold` | 激活阈值(可选,默认 `1`)。标签计数值 ≥ 阈值时激活 |
| `key` | 变量名,以 `$` 开头 |
| `expr` | 表达式,支持数字、`$var` 引用、骰子、算术、函数 |
| `vars` | 变量声明映射:`$name: 表达式` |
| `tags` | 标签修饰符映射:`标签名 → 阈值 → {$目标: 增量}` |
标签名可以带或不带 `#` 前缀。阈值是正整数:标签计数值达到该值时,修饰符生效。
数字会被当作数值,其余一律作为表达式文本(如 `$con*5+$mod_hp`)。
### 声明类型
**普通声明**(tag 为空):`$key` 是一个派生变量,其值由表达式计算。当依赖变量变化时自动重新计算。
**普通声明**(`vars`):`$key` 是一个派生变量,其值由表达式计算。当依赖变量变化时自动重新计算。
```csv role=declare
tag,key,expr
,$hp,$con*5+$mod_hp
,$ac,10+$dex
```yaml role=declare
vars:
$hp: $con*5 + $mod_hp
$ac: 10 + $dex
```
**标签修饰符**(tag 非空):当源变量的标签映射中 `#tag` 的计数值 ≥ `threshold` 时,`$key` 加上表达式的计算结果。修饰符按阈值独立激活。
**标签修饰符**(`tags`):当源变量的标签映射中 `#tag` 的计数值 ≥ 阈值时,`$key` 加上该值。同一标签的多个阈值会叠加,修饰符按阈值独立激活。
```csv role=declare
tag,threshold,key,expr
#warrior,1,$mod_hp,20
#warrior,2,$mod_str,1
```yaml role=declare
tags:
warrior:
1:
$mod_hp: 20
2:
$mod_str: 1
```
上例中:
@@ -141,10 +152,13 @@ tag,threshold,key,expr
阈值允许同一标签产生不同层级的效果:
```csv role=declare
tag,threshold,key,expr
#warrior,1,$mod_hp,10
#warrior,3,$mod_hp,20
```yaml role=declare
tags:
warrior:
1:
$mod_hp: 10
3:
$mod_hp: 20
```
- `#warrior` 计数 1-2:`$mod_hp` +10
@@ -174,14 +188,18 @@ tag,threshold,key,expr
在文档中定义:
```csv role=declare
tag,threshold,key,expr
,,$con,10
,,$dex,12
,,$hp,$con*5+$mod_hp
,,$ac,10+$dex
#warrior,1,$mod_hp,20
#warrior,2,$mod_str,1
```yaml role=declare
vars:
$con: 10
$dex: 12
$hp: $con*5 + $mod_hp
$ac: 10 + $dex
tags:
warrior:
1:
$mod_hp: 20
2:
$mod_str: 1
```
在 Journal 中输入: