From 0b029b325ed7457ccc13fa64518847315d542be9 Mon Sep 17 00:00:00 2001 From: hyper Date: Sat, 12 Sep 2026 22:51:12 +0800 Subject: [PATCH] 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. --- .agents/skills/tttk-authoring/SKILL.md | 4 +- docs/cli.md | 4 +- src/components/journal/VariableView.tsx | 2 +- src/components/journal/types/var.tsx | 2 +- src/doc-entries/journal-set.md | 88 +++++++++++++++---------- 5 files changed, 59 insertions(+), 41 deletions(-) diff --git a/.agents/skills/tttk-authoring/SKILL.md b/.agents/skills/tttk-authoring/SKILL.md index dbf0bd1..c2a7376 100644 --- a/.agents/skills/tttk-authoring/SKILL.md +++ b/.agents/skills/tttk-authoring/SKILL.md @@ -60,7 +60,7 @@ Fenced blocks are dispatched by the `role=` attribute in the info string: |---|---| | ` ```csv role=spark-table ` | Body is CSV; replaced with `:md-table[./csv_]`. First column header must be a dice formula (`d6`, `2d6+1`, …). | | ` ```markdown role=spark-table ` | Body is a GFM pipe table; converted to CSV, then same as above. | -| ` ```csv role=declare ` | Defines reactive variables / tag modifiers. Block is stripped. | +| ` ```yaml role=declare ` | YAML `vars:` / `tags:` maps defining reactive variables and tag modifiers. Block is stripped. | | ` ``` role=file ` | Body stored as text content, block stripped, referenced by its derived id. | | ` ```yaml role=tag ` | Kept intact; rendered as a custom element from YAML (`tag:`, `body:`, …). | | ` ``` ` (no role) | Rendered as a normal visible code block. | @@ -109,7 +109,7 @@ Warnings are usually real too: | Code | Meaning | |---|---| | `TTTK-R002` | spark-table first header is not a dice formula | -| `TTTK-R004` | `role=declare` row skipped (empty `key` or `expr`) | +| `TTTK-R004` | `role=declare` block declares nothing | | `TTTK-C002` | reference resolves to an unexpected file type | | `TTTK-L002` | `#section` matches no heading | | `TTTK-A001` | icon missing under `assets/` | diff --git a/docs/cli.md b/docs/cli.md index 9855e78..3ab61ed 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -115,8 +115,8 @@ content/adventures/hollow-mill/adventure.md | `TTTK-D002` | error | 属性块畸形（例如未加引号的值中含空格） | | `TTTK-R001` | error | 未知的代码块 `role=`（块内容会被静默丢弃） | | `TTTK-R002` | warning | `role=spark-table` 首列表头不是骰点公式 | -| `TTTK-R003` | error | `role=declare` 解析失败（缺少 `key`/`expr` 等） | -| `TTTK-R004` | warning | `role=declare` 中 `key`/`expr` 为空的行被跳过 | +| `TTTK-R003` | error | `role=declare` 解析失败（YAML 非法或结构不符） | +| `TTTK-R004` | warning | `role=declare` 块没有声明任何变量或标签修饰符 | | `TTTK-R005` | error | `role=tag` 的 YAML 无法解析 | | `TTTK-R006` | error | `role=tag` 缺少 `tag:` 或元素未知 | | `TTTK-C001` | error | 内容引用无法解析（文件不存在，或内联 id 未定义） | diff --git a/src/components/journal/VariableView.tsx b/src/components/journal/VariableView.tsx index 288e296..0ca3f84 100644 --- a/src/components/journal/VariableView.tsx +++ b/src/components/journal/VariableView.tsx @@ -53,7 +53,7 @@ export const VariableView: Component = () => { when={hasAnyData()} fallback={

- 暂无变量定义。在文档中使用 ```csv role=declare 代码块定义变量。 + 暂无变量定义。在文档中使用 ```yaml role=declare 代码块定义变量。

} > diff --git a/src/components/journal/types/var.tsx b/src/components/journal/types/var.tsx index 8160326..6e21eac 100644 --- a/src/components/journal/types/var.tsx +++ b/src/components/journal/types/var.tsx @@ -4,7 +4,7 @@ * Emitters: gm, player * Command: /set $key expression * - * Variable declarations and tag modifiers are authored in ```csv role=declare + * Variable declarations and tag modifiers are authored in ```yaml role=declare * code blocks in markdown documents. The stream carries `set` mutations that * build up the runtime variable store additively. */ diff --git a/src/doc-entries/journal-set.md b/src/doc-entries/journal-set.md index aa2b838..f81309d 100644 --- a/src/doc-entries/journal-set.md +++ b/src/doc-entries/journal-set.md @@ -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 中输入：