📦 deps(tsl): sync tsl-playbook from a71480a4

Source-Commit: a71480a4ae

skills/tsl-syntax-reference/references/03_values_and_literals.md

@@ -4,20 +4,24 @@
 
 ## 本篇职责
 
+<!-- section-id: syntax-03-001 -->
+
 回答“基本类型怎么写、数组和字符串怎么索引、字符串编码边界怎么写、哪些值规则属于语言级事实”。本页拥有整数、实数、字符串、布尔、`array(...)` 字面量和下标 / 区间规则；矩阵与集合扩展不在本页展开。
 
 ## 核心规则
 
+<!-- section-id: syntax-03-002 -->
+
+<!-- tags: 数组下标, 数组索引, 下标从几开始, 下标起点, 字符串下标, 二进制下标 -->
+
 - 最先掌握的几类值是：整数、实数、普通字符串、布尔和 `array(...)`。
 - 普通字符串既可以用双引号，也可以用单引号。
 - 同类引号本身可以通过连续写两个同类引号放进字符串里。
 - `\\`、`\"`、`\n` 这类基础转义可用。
 - `\t` 和 `\xNN` 这类转义也可用。
 - `\r`、`\r\n`、`\a`、`\b`、`\f`、`\v` 这些经典转义也可用。
-- `array(...)` 既可以写顺序数组，也可以写字符串键表。
-- 顺序数组下标从 `0` 开始。
-- `binary(...)` 创建的二进制缓冲区也用 `[]` 访问，并且下标从 `0` 开始。
-- 字符串下标从 `1` 开始。
+<!-- quickstart-rule: index-origins -->
+- `array(...)` 既可以写顺序数组，也可以写字符串键表；顺序数组和 `binary(...)` 二进制缓冲区下标从 `0` 开始，字符串下标从 `1` 开始。
 - `s[0]` 在运行时会越界，不要把字符串当成 0 基下标。
 - 字符串取子串用 `s[start:end]`，并且 `end` 是包含在结果里的。
 - 字符串替换子串用 `s[start:end] := "..."`。
@@ -33,6 +37,8 @@
 
 ## 可直接照写示例
 
+<!-- section-id: syntax-03-003 -->
+
 使用这些示例时遵守：
 
 - 只复制任务需要的值、字面量、下标或字符串片段，不要把多个示例拼成未写入文档的新语法。
@@ -164,7 +170,9 @@ C
 
 ### 字符串边界规则
 
-<!-- tags: 原始字符串, 多行字符串, 引号怎么转义, 字符串里带引号, 长文本 -->
+<!-- section-id: syntax-03-004 -->
+
+<!-- tags: 原始字符串, 多行字符串, 引号怎么转义, 字符串里带引号, 长文本, 宽字符串, 宽串前缀, utf8 转换, 编码转换, 字符码拼接, 二进制缓冲区, 字节读写 -->
 
 原始字符串 `%%` 的空白分隔、标识符和多行：
 
@@ -303,6 +311,14 @@ writeLn(b[1] = "1");
 - 说明二进制缓冲区的 `[]` 下标从 `0` 开始
 - 也说明二进制缓冲区项可以直接按单字节读写
 
+### 字符串子串读写
+
+<!-- section-id: syntax-03-005 -->
+
+<!-- tags: 取子串, 截取子串, 字符串区间, 替换子串, 删除子串, 插入子串, 插入字符串, 取字符串的一段 -->
+
+字符串子串统一用 `s[start:end]` 区间访问，`end` 包含在结果里；同一形态既能读取，也能替换、删除和插入。
+
 字符串子串读取：
 
 代码块身份：可直接照写示例
@@ -365,6 +381,8 @@ writeLn(s);
 
 ### 字符串 `$` 连接与拼装
 
+<!-- section-id: syntax-03-006 -->
+
 <!-- tags: 拼字符串, 字符串相加, 连接字符串, 数字转字符串拼接 -->
 
 `$` 用于字符串连接和类型转字符串拼装：
@@ -398,7 +416,9 @@ A=1 B=2.34 C=AAA
 
 ### 字符串 `like` 模式匹配
 
-<!-- tags: 通配符匹配, 正则匹配, 模糊匹配, 判断是否符合模式 -->
+<!-- section-id: syntax-03-007 -->
+
+<!-- tags: 通配符匹配, 正则匹配, 正则表达式, 模糊匹配, 判断是否符合模式 -->
 
 `like` 用于判断字符串是否符合指定模式（支持通配符和正则表达式）：
 
@@ -444,6 +464,8 @@ writeLn(result);
 
 ### `format` 格式化占位符
 
+<!-- section-id: syntax-03-008 -->
+
 <!-- tags: 格式化输出, 占位符, 补零, 保留小数, 拼装带格式的串 -->
 
 `format` 用于按占位符格式化输出：
@@ -468,6 +490,8 @@ writeLn(result);
 
 ### `formatdatetime` 日期格式化
 
+<!-- section-id: syntax-03-009 -->
+
 <!-- tags: 日期转字符串, 时间格式化, 年月日怎么输出, 日期显示格式 -->
 
 `formatdatetime` 用于将日期按指定格式输出：
@@ -493,6 +517,8 @@ writeLn(result);
 
 ## 默认生成模板
 
+<!-- section-id: syntax-03-010 -->
+
 如果你只是要抓住“基本类型 + array”的第一层，用这个最短例子：
 
 代码块身份：可直接照写示例
@@ -507,9 +533,12 @@ items := array(1, 2, 3);
 
 ## 禁止项
 
+<!-- section-id: syntax-03-011 -->
+
 - 用 `s[0]` 访问字符串首字符。
 - 误以为 `array(...)` 只能写顺序数组，不能写字符串键表。
 - 误以为字符串区间和数组一样从 `0` 开始。
+- 把字符串区间当成数组切片式的半开区间；`s[1:3]` 返回 `ABC` 而不是 `AB`，结束位会被包含进结果，正向示例见本页“字符串子串读写”。
 - 把 `s[index:0] := ...` 误解成“替换到第 0 位”。
 - 把二进制缓冲区也按字符串的 `1` 基下标去理解。
 - 在普通字符串示例里默认切到原始字符串、宽串 / UTF8 前缀、字符码或编码转换，却没有按本页字符串边界规则确认。
@@ -531,18 +560,3 @@ writeLn(s[0]);
 ```text
 String index out of bounds
 ```
-
-代码块身份：可直接照写示例
-
-```tsl
-s := "ABCDE";
-writeLn(s[1:3]);
-```
-
-不要把上面这个区间访问类比成数组切片的半开区间。按文档输出，它返回 `ABC`，不是 `AB`；字符串区间的结束位会被包含进结果。
-
-代码块身份：输出片段
-
-```text
-ABC
-```