Squashed 'docs/standards/playbook/' changes from c3f8137..25d895d

25d895d 🐛 fix(gitea_workflow): clean up temp repos after job steps 2bc3b11 🐛 fix(gitea_workflow): clean up temporary repo dirs in workflows 98c3f30 📝 docs(agent_rules): allow plan execution on current branch 16c7230 📝 docs(prompts): define custom verify layering 8efc4dd 🐛 fix(skills): quote commit-message description bc8498f 🐛 fix(ci): install tomli for gitea tests 55cda3b 🐛 fix(tests): report missing toml parser clearly c0729c7 🐛 fix(playbook): import Optional for cli compatibility 63e24bf 📦 deps(skills): sync thirdparty skills d2f9356 🐛 fix(ci): isolate gitea workflow repos 588b81d 🐛 fix(ci): inline gitea workflow bootstrap e0b1c3a ♻️ refactor(skills): standardize first-party skill contracts 2c5050d ♻️ refactor(skills): rename repo skills source dir f049dfb 📦 deps(skills): drop duplicate first-party superpowers skills 234b335 ✨ feat(workflow): add superpowers planning and execution state tracking c1702a6 📝 docs(markdown): format tracked markdown and drop stale templates 2325409 📝 docs(markdown): clarify optional markdownlint usage 214c44e 🔧 chore(markdown): add markdownlint baseline and lint fixes a22b324 📝 docs(templates): add execution and memory-bank prompt templates 223a797 📝 docs(templates): update README for Claude Code and current features 4ac8672 📝 docs: simplify README + platform-agnostic tools + auto-create local rules 2431c9d 📝 docs: add claude_md config and use cross-platform paths d64b248 📝 docs: fix README.md inaccuracies and add Claude Code info c8d6bf2 🐛 fix(playbook): use relative paths in CLAUDE.md when not at project root 6518f0f ✨ feat(playbook): auto-create CLAUDE.md with path discovery 6ec9a45 ✨ feat(skills): add skill_link symlink support + platform-agnostic prompt 9f8b6b5 📝 docs: update README and config example for Claude Code support 79cff6c 📝 docs(skills): add Claude Code platform support 452c6f5 ✨ feat(playbook): auto-inject AGENTS.md into CLAUDE.md e1dbf3c 🐛 fix(skills): remove dual-path from commit-message skill f3a7259 🔧 chore(ci): use prepare_repo.sh in both workflows da08212 🔧 chore(ci): extract prepare_repo.sh and clean up workflows 7ade85e 🗑️ remove(tsl): drop syntax_book/, data/ source and build script f94dba0 ♻️ refactor(skills): update playbook.py and tests for thirdparty/ layout b3df412 ♻️ refactor(skills): separate thirdparty skills into thirdparty/ subdirectory 64950e7 📦 deps(skills): sync thirdparty skills a2e3cb0 ✨ feat(playbook): add no_backup deploy controls 8609d59 🐛 fix(docs): repair reference catalog source links 956da11 🐛 fix(playbook): publish hidden ci test fixes 3f67754 📦 deps(skills): sync thirdparty skills 08ca87b 📦 deps(skills): add karpathy thirdparty sync 96b705b 📝 docs(tsl): rebuild canonical syntax and routing manual 3ed5052 📦 deps(skills): sync thirdparty skills 60108dd 📦 deps(skills): sync thirdparty skills da85d4e 🐛 fix(thirdparty): prune nested project snapshots a2a697e 📦 deps(skills): sync thirdparty skills 9df610a 🐛 fix(thirdparty): exclude duplicated superpowers skills 33dd5bb 🐛 fix(thirdparty): preserve optional manifest fields 91b0ea7 🐛 fix(thirdparty): preserve manifest during snapshot update 2e26f98 🔧 chore(thirdparty): generalize skills sync pipeline 5b9c1e3 📦 deps(skills): sync superpowers 2f2d34a 📝 docs(readme): normalize subtree command spacing 62db7db 🐛 fix(ci): serialize superpowers update and sync 3463223 🐛 fix(ci): use literal superpowers sync paths 48f6de8 📦 deps(skills): sync superpowers 4b23529 🔧 chore(ci): merge superpowers update and sync workflow a56d75b 📦 deps(skills): sync superpowers 84bcefa 🔧 chore(ci): use ci[bot] commit author name 00a07e5 📦 deps(skills): sync superpowers 7b84daf 🐛 fix(templates): enforce main loop progress tracking 51373d7 🔧 chore(ci): automate superpowers sync workflow eaaa39c 🐛 fix(ci): prevent stale superpowers sync from restoring skills block 79755c6 📦 deps(skills): sync superpowers 836d878 📦 deps(skills): sync superpowers 8216c9f 📦 deps(skills): sync superpowers 9439505 🐛 fix(playbook): address reported repo issues git-subtree-dir: docs/standards/playbook git-subtree-split: 25d895d8b3f56624ccfe99ad7289e9eb49e0f316
2026-05-24 13:04:14 +08:00
parent 35e6a301aa
commit 3d83740f88
292 changed files with 30774 additions and 218828 deletions
@@ -0,0 +1,175 @@
+# Matrix Deep Dive
+
+文档类型：语法主线
+是否可直接用于生成代码：是
+是否含已验证可执行示例：是
+是否含已验证反例：是
+遇到不确定时跳转到：[13_matrix_and_collections.md](13_matrix_and_collections.md)、[27_fmarray.md](27_fmarray.md)、[25_set_operations.md](25_set_operations.md)
+
+手册位置：第 26 篇，共 32 篇。上一篇：[25_set_operations.md](25_set_operations.md)。下一篇：[27_fmarray.md](27_fmarray.md)。
+
+这一篇开始讲真正的矩阵语法主干：矩阵初始化、数列构造，以及怎样读取矩阵的行列大小和索引。它和 [13_matrix_and_collections.md](13_matrix_and_collections.md) 的分工是：`13` 只讲数组与矩阵样数据，这一篇开始讲矩阵专用构造与大小接口。
+
+## 这一篇解决什么问题
+
+回答“怎样直接构造全零矩阵、全一矩阵、随机矩阵、单位矩阵、空矩阵和数列数组，以及怎样拿到矩阵的行数、列数、行索引和列索引”。
+
+## 必须记住的规则
+
+- `Zeros(...)`、`Ones(...)`、`Rand(...)`、`Nils(...)`、`Eye(...)` 都可以直接用于矩阵初始化。
+- `Zeros(3)`、`Ones(3)`、`Nils(2)` 这类单参数写法可以直接生成一维结果。
+- `Zeros(2, 3)`、`Rand(2, 3)` 这类双参数写法可以直接生成二维矩阵。
+- `Zeros(2, array("A", "B"))` 这种写法可以直接生成带列名的二维结果。
+- `Eye(3)` 生成的是 `3 x 3` 单位矩阵，不是一维数组。
+- `->` 用来生成数列；默认步长是 `1`，也可以显式传入步长和索引数组。
+- `MSize(A)` 返回 `array(行数, 列数)`。
+- `MSize(A, 1)` 返回行索引数组和列索引数组。
+- `MRows(A)` / `MCols(A)` 默认返回数量；第二个参数写成 `1` 时返回索引数组。
+
+## 已验证语法
+
+### 矩阵初始化
+
+代码块身份：已验证可执行示例
+
+```tsl
+program test;
+begin
+    Z1 := Zeros(3);
+    Z2 := Zeros(2, 3);
+    O1 := Ones(3);
+    N1 := Nils(2);
+    E1 := Eye(3);
+    R1 := Rand(2, 3);
+    T1 := Zeros(2, array("A", "B"));
+end.
+```
+
+已验证运行结果：
+
+- `Zeros(3)` 的长度是 `3`，前三个元素依次是 `0`、`0`、`0`
+- `Zeros(2, 3)` 的行数是 `2`、列数是 `3`，第一行前三个元素是 `0`、`0`、`0`
+- `Ones(3)` 的前三个元素依次是 `1`、`1`、`1`
+- `Nils(2)` 已验证可直接生成长度为 `2` 的结果
+- `Eye(3)` 的行数是 `3`、列数是 `3`，并且 `(0,0)`、`(1,1)`、`(2,2)` 为 `1`，`(0,1)`、`(1,0)` 为 `0`
+- `Rand(2, 3)` 的行数是 `2`、列数是 `3`
+- `Zeros(2, array("A", "B"))` 的行数是 `2`、列数是 `2`，并且 `T1[0]["A"]`、`T1[0]["B"]`、`T1[1]["A"]`、`T1[1]["B"]` 都是 `0`
+
+### `->` 数列数组初始化
+
+默认步长为 `1`：
+
+代码块身份：已验证可执行示例
+
+```tsl
+program test;
+begin
+    S1 := 1 -> 5;
+end.
+```
+
+已验证运行结果：
+
+- `S1` 是 `array(1, 2, 3, 4, 5)`
+
+显式指定步长：
+
+代码块身份：已验证可执行示例
+
+```tsl
+program test;
+begin
+    S2 := array(2.5, 0.5) -> 5;
+end.
+```
+
+已验证运行结果：
+
+- `S2` 的长度是 `6`
+- 六个元素依次是 `2.5`、`3`、`3.5`、`4`、`4.5`、`5`
+
+显式指定索引数组：
+
+代码块身份：已验证可执行示例
+
+```tsl
+program test;
+begin
+    S3 := array(0, 1, array("A", "B", "C", "D", "E", "F")) -> 5;
+end.
+```
+
+已验证运行结果：
+
+- `S3` 的长度是 `6`
+- `S3["A"]` 到 `S3["F"]` 依次是 `0`、`1`、`2`、`3`、`4`、`5`
+
+### `MSize`、`MRows`、`MCols`
+
+代码块身份：已验证可执行示例
+
+```tsl
+program test;
+begin
+    A := array(
+        ("A": 1, "B": 2),
+        ("A": 11, "B": 22),
+        ("A": 21, "B": 32)
+    );
+    SizeInfo := MSize(A);
+    SizeIndex := MSize(A, 1);
+    RowCount := MRows(A);
+    RowIndex := MRows(A, 1);
+    ColCount := MCols(A);
+    ColIndex := MCols(A, 1);
+end.
+```
+
+已验证运行结果：
+
+- `MSize(A)` 返回 `array(3, 2)`
+- `MSize(A, 1)` 的第一项是 `array(0, 1, 2)`，第二项是 `array("A", "B")`
+- `MRows(A)` 返回 `3`
+- `MRows(A, 1)` 返回 `array(0, 1, 2)`
+- `MCols(A)` 返回 `2`
+- `MCols(A, 1)` 返回 `array("A", "B")`
+
+## 最小可编译示例
+
+如果你只想先记住最短矩阵构造，从这个开始：
+
+代码块身份：已验证可执行示例
+
+```tsl
+M := Zeros(2, 3);
+```
+
+## 常见误写
+
+- 把 `Eye(3)` 当成一维数组。
+- 以为 `MRows(A, 1)` 和 `MCols(A, 1)` 返回的还是数量。
+- 写带步长的 `->` 时，漏掉外层 `array(...)`。
+- 还在普通数组页里硬塞矩阵专用大小接口。
+
+代码块身份：反例 / 不可照写
+
+```text
+S := 2.5, 0.5 -> 5;
+```
+
+上面这种写法不对。显式步长模式需要写成 `array(2.5, 0.5) -> 5`。
+
+代码块身份：反例 / 不可照写
+
+```text
+Cols := MCols(A, 1);
+```
+
+不要把上面这一句的返回值当成数字 `2`。当前解释器下，`MCols(A, 1)` 返回的是列索引数组，例如 `array("A", "B")`。
+
+## 跳转指引
+
+- 回看数组与嵌套数组：见 [13_matrix_and_collections.md](13_matrix_and_collections.md)
+- 看结果集过滤：见 [14_resultset_and_filters.md](14_resultset_and_filters.md)
+- 看集合运算：见 [25_set_operations.md](25_set_operations.md)
+- 进入 `FMArray`：见 [27_fmarray.md](27_fmarray.md)