Files
R8Forge/AGENTS.md
T
dsh b4ea79ba91 %synth: the cost model is a run option, not a per block metric line
`metric chars|flat|blocks` inside %synth meant the same truth table could be
searched twice for two call sites, and every library block had to spell out
`metric flat` to avoid the default.  The cost model belongs to the whole
assembly, so it is one now:

    r8forge <file.r8asm>                  flat (layout free), the default
    r8forge --synth-chars <file.r8asm>    charge the real .tp walk

flat stays the default because a library block is expanded at dozens of call
sites with different layouts: only a layout free result can share one cache
entry, and it is usually within a few percent (full_add: 95 vs 90 characters).
The chars search is far more expensive (full_add: 415M states, ~21 minutes,
~10 GB), which is exactly why it should be asked for on the command line.

`metric blocks` goes with it: block count is a poor proxy for tape length (and
it was only another way to ask for mode layers).

Implementation: the metric lives in the assembler (ast::synth_metric, default
1) and is set through r8asm::set_synth_metric() before import_file; the CLI in
tests/asm_test.cc parses --synth-chars / --synth-flat.  The cache key already
carried metric, so the committed entries still hit: assembling the library and
asm/test.r8asm gives byte identical tapes (28729 characters, byte_op_test all
green, all 13 examples green, synth_test still 8/8).

A `metric` line now fails with a message that names the flag instead of being
silently ignored.  examples/full_add_flat.r8asm and full_add_flat_spaced.r8asm
are removed: they only existed to demonstrate the per block metric (the flat
default makes them copies of full_add.r8asm).

Also repairs the mojibake in README's metric section: an earlier tool wrote
\x0c / \x08 / \x0d where \f, \b and \r belonged, which ate characters out of
"flat", "blocks", "biz/flb/rnz" and "rnz".  The section is rewritten for the
flag, and the %synth numbers in README/SPEC/AGENTS now match what the tree
prints.

New cache entry c16bf083bb0ccbc8.txt is full_add's stat table with mode layers
+ flat, which full_add_stat.r8asm now produces.
2026-11-07 23:44:01 +08:00

578 lines
41 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 给接手的 agent 的话
## 下一轮从这里开始(2026-11-07 交接:移位-恢复除法已落地)
**上一轮的任务做完了**:`clb_divmod` 已经是二进制长除法(`asm/divmod.r8asm`)。
契约看 `SPEC.md §7.6`,设计推理、踩过的坑和实测数据看 `§14`。摘要:
* 签名变成 `clb_divmod N D Q R S`:`Q` = 商、`R` = 余数,**N 和 D 都保持原样**,
`S` 起 **7 个连续草稿格**。11 个 cell,最小驱动纸带 **4499**(旧 4189)。
* 固定 **11 轮(位宽)**,`2047/1` 不再 HANG。步数(`drv/divmod.r8asm`):
`2047/10` 49.6 万 → **2.86 万**、`2047/2` 246 万 → **3.2 万**、`999/7` 34 万 →
**2.87 万**、`2047/1` HANG → **3.24 万**;16384 组里最坏 **32,383** 步。
**小 N/D 反而慢**(旧版 N/D 轮就结束)——和 `clb_mul` 一样的取舍。
* `clb_digits` 跟着换了布局(`S` 起 **13 格**,divmod 的草稿块从 `S+3` 开始):
`0=2047` 从 74 万降到 **14.5 万**步(最坏 164,867),`test_digits` 现在**穷举
全部 2048 个值**。纸带 10829 → 13717。
* 单点验证驱动:`drv/div_shift.r8asm`(跨格左移 + 注入那一步,`SPEC §14.4` 第 1 条)。
* 顺带修了两处**会骗人的东西**:`r8forge_derive` 以前不看汇编器的 error 位,漏
`%include`(`unknown macro`)时会拿**截断的纸带**跑出一个看起来正常的错答案
(这轮踩过一次,四个数字全变成 `'0'`);`raw_sub` 注释里把 Bo 的语义写反了
(Bo = 1 是"没借位"= `A >= B`,实测 15-10 → 1、10-15 → 0)。
**下一步可以做的(这轮没做)**:
* 想再快一档:`SPEC §14.6` 那条"开循环前预计算 `~D`、每轮走 `raw_add`",按单轮实测
差值估计 `clb_divmod` 28.6k → 约 17.6k 步,纸带基本不变;没换是因为 §14.3 指名
用 `raw_sub`,而它是上一轮专门为长除法加的。
* 纸带还能短:`clb_digits` 的布局没优化过(13 格草稿跨得很开,`.tp` 行走占了纸带的
七成);`clb_divmod` 里提交时那个 495 字符的 `copy` 也还是全展开的。
* 小 N/D 的慢是"固定 W 轮"的必然代价。真要治,得加"跳过前导 0 轮"(`R == 0` 的轮
只剩 Q 的旋转),但那会给**每一轮**加一次 `clb_nonzero`(约 300 步),大数反而更慢
—— 这轮权衡过,没做。
**别动**:`asm/` 里其它宏;`%synth` 的指令模型(改了就 bump `kModelVersion`);
`geometry.hh` 的位宽(真要改照 SPEC §13 的清单,四份虚拟机一起)。
**当前基线(都通过,别弄坏)**:
```sh
r8forge asm/test.r8asm # 28729 字符
r8forge_byte_op_test # 20 项(clb_divmod 16384 组、clb_digits 2048 个值)
r8forge_examples_test # examples/ 里 13 个程序,头部 `; out` 逐个核对
r8forge_macro_docs_test # 47 macros in 21 files
r8forge_synth_test examples/full_add.r8asm # all eight combinations ok
r8forge_derive verify_loop.r8asm -1 0=5 # out 5 0
```
**另一个仓库**:`../ROT-8-viz`(fork `dsh/ROT-8-viz`,`main` = `6e51df5`)有串行 7E1
(`-s` / `--parity` / `--stop` / `--7e1`),`clb_digits` 产出的 ASCII 正好能直接喂它的
`OUT`。那边的工作树也是干净的。
> **动手之前,先把这份文件从头读完**,再看 `SPEC.md`(本仓库自己的:`%synth` 指令 +
> `asm/` 里每个宏的契约、纸带长度、验证口径)、上游语言规格
> (`C:\Users\peng0\git\r8asm_rev-fork\SPEC.md`)和 `asm/lib.r8asm` 里的宏注释。
> 这条不是客套:上一轮我没先读,把「位移-加法乘法器比重复加法快」当成新发现又推了一遍。
> 那次它被否掉了(当时只认纸带长度),后来乘数一大就撞 500 万步上限,真的换成了移位-加法
> —— **而且它比重复加法还短**(5007 → 3977 字符),见「乘法器」。
> 下面「乘法器」「指令集语义」两节把要命的地方都写了 ——
> `dp` 净位移、`flb` 吃条件、`rol` = 10 次 `ror`、
> 位串行要的跨格移位该怎么拼。**尤其把「已经确认走不通的」那节看完**,
> 别把别人踩过的坑再踩一遍;想推翻某条结论,先照它写的验证方法实测一遍再改文字。
这个文件是给下一个会话(或者下一个 agent)看的交接说明。内容都是这个仓库里**实测过**的结论,
不是推测;每条后面基本都跟着一次失败的尝试,别再踩。
## 工作方式(上一轮踩到的)
* **超过 ~30 秒的命令一律丢后台**(`run_in_background`),前台只做短轮询。
一次搜索可以跑 680 秒、缓存预热 885 秒,前台干等会撞上客户端和 API 的传输超时。
* **别让大段 stderr 进上下文**。PowerShell 遇到原生命令出错会吐一整套 `NativeCommandError`
堆栈;用 `2>$null` 收干净,判断结果靠 `$LASTEXITCODE` 和 stdout。
* 写含中文的文件用编辑工具(UTF-8)。**不要用 PowerShell 做"读-改-写"**:这台机器上
`Get-Content` 默认按 GBK 读 UTF-8 文件,再 `Set-Content -Encoding utf8` 写回去就是
二次转码、整篇变乱码(`AGENTS.md` 就这么被我毁过一次,靠 `git checkout -- AGENTS.md`
救回来)。`Set-Content -Encoding ascii` 更糟,汉字直接变 `?`
(`examples/` 里那些带中文注释的 `.r8asm` 就这么坏过一次)。
* **构建要用 VS 自带的 cmake**:`build/` 是 `Visual Studio 18 2026` 生成器配的,
直接敲 PATH 上的 scoop cmake(4.4)会因为版本不一致重新配置,然后死在
`No preprocessor test for "PellesC"`。用这个:
```sh
"C:/Program Files/Microsoft Visual Studio/18/Community/Common7/IDE/CommonExtensions/Microsoft/CMake/CMake/bin/cmake.exe" \
--build build --config Release
```
* **`%synth` 的临时文件**:汇编器把生成的宏写到系统临时目录再 import,然后删掉。这台机器上
这一步**偶尔**会失败(`r8asm: cannot open 'C:\Users\...\Temp\xxx.synth.r8asm'`;同目录下
`cmd` 能写、`r8forge` 不能,原因没查清,重跑一次可能就好了)。现在代码会退回到**当前工作
目录**重试,stderr 留一句 `<临时目录> is not writable, using <cwd>`。看到这句不用管;
看到 `cannot write the synthesised macro anywhere` 才是真坏了。`*.synth.r8asm` 已在
`.gitignore` 里。
* 会话很长时传输容易失败,重要结论要落到 **commit message 和文件注释**里,别只留在对话里。
* **写结论之前先对虚拟机**:这个仓库最贵的一次事故就是虚拟机语义写错,然后在错的东西上
写了一整套"实测结论"(见「字节级运算」)。字节级结论必须能被 ROT-8-viz
(`C:\Users\peng0\git\ROT-8-viz`,权威实现)复现。
* **提交身份**:这个 repo 和 `C:\Users\peng0\git\ROT-8-viz` 的 local config 都是
`user.name = dsh`、`user.email = dsh@gitea.local`(凭证里那条 `git:https://gitea.starcells.ltd`
就是 `dsh@gitea.local`)。**agent 的提交用 dsh,不要用 `StarCells <peng080306@foxmail.com>`**
—— 那是仓库主人的身份。这条踩过:ROT-8-viz 一开始没配 user.name,我照抄了历史作者,
结果两个 repo 的提交都挂在了主人名下,后来用 `rebase --reset-author` / `filter-branch`
改回 dsh 并 force-push 才修好。`git commit` 报 `Author identity unknown` 就是这条配置又没了,
补 `git config user.name dsh` + `git config user.email dsh@gitea.local` 就行。
ROT-8-viz 上这个 local config 被清掉过两次(原因没查清),所以那边提交时更稳的写法是
直接带上:`git -c user.name=dsh -c user.email=dsh@gitea.local commit ...`。
* **推代码**:`origin` = `https://gitea.starcells.ltd/dsh/R8Forge.git`。这台机器上
schannel 会报 `schannel: AcquireCredentialsHandle failed: SEC_E_NO_CREDENTIALS`,
`fetch` / `push` 都得走 openssl 后端 —— 已经写在这个 repo 的 local config 里
(`git config http.sslBackend openssl`),正常 `git push` 就行。
如果当前会话的沙箱是 workspace-write,`push` 还要一次提权:git 的凭证助手要开命名管道,
沙箱会拒绝(`sh.exe: fatal error - couldn't create signal pipe, Win32 error 5` +
`could not read Username`);danger-full-access 下不需要。`fetch` 两种模式都不需要
(仓库可匿名读)。
## 构建与自检
```sh
# MSVC Release
cmake -S . -B build -G "Visual Studio 18 2026" -A x64
cmake --build build --config Release
# clang-cl(scoop 的 llvm,比 MSVC 严格,能抓出模板推导问题)
clang-cl /nologo /std:c++20 /EHsc /O2 /I include src/r8asm.cc src/synth.cc tests/asm_test.cc /Fe:r8forge.exe
```
自检:
```sh
r8forge asm/test.r8asm # 应 exit 0,28729 字符(3 轮 hash)
r8forge_synth_test examples/full_add.r8asm # all eight combinations ok
r8forge verify_clb_bit_add_nc.r8asm # 4 cell 加法切片(进位进->出)
r8forge verify_clb_bit_inc_nc.r8asm # 3 cell 自增切片,进位同样进->出
r8forge_derive verify_loop.r8asm -1 0=5 # 动态循环:跑 5 次,out 应该是 5 0
r8forge_byte_op_test # 字节级库:20 个操作穷举/抽样,这台机器约 10 秒
r8forge_macro_docs_test # asm/ 里每个宏的注释格式
```
`r8forge_byte_op_test` 是**唯一按返回值判断字节级对错的**;前三个只证明"汇编得出来"或
"位级正确"。
**`r8forge_derive` 会检查汇编错误**(2026-11 修的):`import_file` 只表示"文件打开了",
漏一条 `%include` 时汇编器会报 `unknown macro '...'` 并把 error 位置上、纸带是**截断**的。
以前 `derive` 不看这个标志,于是拿半截纸带跑出一个看起来正常的错答案(这轮实测踩到:
`clb_digits` 少了 `add_ip` 的 include,四个数字全变成 `'0'`)。现在它会打印
`could not assemble` 并返回 1 —— **看到 `out` 结果"太整齐"就先看 stderr**。
`r8forge_derive` 是验证工具:
```sh
r8forge_derive <file.r8asm> 4 0 2 # 按输入组合跑,打印 stat
r8forge_derive <file.r8asm> -1 0=100 1=50 # 指定 cell 初值跑一遍,打印 out
r8forge_derive <file.r8asm> -2 0=100 # 同上,另外倒出所有非零 cell
```
注意 `-1/-2` 是拿**汇编源码**跑的(内部会先 `import_file`),不能直接喂 `.rot8` 纸带。
`r8forge_tape_run <file.rot8> [addr=value...]` 是第二个实现,直接喂纸带,用来交叉验证
`derive`(两个实现同时写错的可能性比一个低)。
## 指令集语义(这些搞错会浪费一整轮)
```
'-' flb 翻转最低位 cells[dp] ^= 1
'+' ror 右旋整个 cell
'[' biz 最低位为 0 -> 跳到匹配的 ']' 之后
']' rnz 最低位为 1 -> 跳回匹配的 '['
```
**最后两条的关键在"最低位"三个字**:`biz`/`rnz` 判的是 `cell & 1`,不是"整格是否为零"。
权威实现是 `ROT-8-viz/src/rot8.c`:
```c
void rot8_biz(rot8_iter *iter) { if ((*(iter->mem_now) & 1) == 0) { ... } }
void rot8_rnz(rot8_iter *iter) { if ((*(iter->mem_now) & 1) == 1) { ... } }
```
由此推出两条**关键约束**:
1. **`set_0` = `[-]` 清的是最低位,不是整个 cell。**
`set_0` 把 255 变成 254、把 128 原样留着、把 5 变成 4。要清整个字节就
`%rep _CELL_SIZE { set_0; ror }`(`erase` 就是这么写的)。一个字节的位能读:
`ror` 若干次把目标位转到最低位,再 `biz`。
2. **合成的程序只碰每个 cell 的低 K 位**(K = 参与运算的输入位数),高位不追踪。
所以 `%synth` 出来的块只适用于"每格一位"的世界。
**写手写宏还有第三条**:`dp` 是**汇编期**算的常量,而 `[...]` 的 body 在运行期可能被跳过。
所以**每个条件块的身体必须回到它自己的条件 cell**(净位移 0),否则跳过路径和进入路径的
`dp` 会不一致,之后所有 `.tp` 全部错位 —— 症状是 `dp` 跑到 1023 这种地方(
`r8forge_tape_run --trace` 能直接看到)。库里的宏都遵守:`set_0` 的身体不移动、`clb_bit_mov`
的身体最后 `.tp before` 再 `flb`(顺便把条件吃掉)。
曾经这里还写过第三条("多字节 cell 的位读不出来")—— 那是把 `biz` 当成 Brainfuck 的
整格零判断推出来的,**错的**,已删。
## cell_size 与纸带长度是怎么用的
位宽叫 **`cell_size`**(一个 cell 多少 bit),纸带长度叫 `kDefaultMemoryCells`;
搜索器里"有多少个 CellBit 形参"叫 **`cell_argc`**(`r8veritas<cell_argc>`)。这三个名字
在两边的仓库里是统一的:C/C++ 侧 `cell_size`、搜索器侧 `cell_argc`、`.r8asm` 程序里看到的
常量仍是 `_CELL_SIZE`(那是源语言的常量,属于宏库的公开词汇,不要跟着改)。
两个默认值集中在 **`include/r8forge/geometry.hh`**,现在是 **11 位 / 259 格**:
```cpp
inline constexpr size_t kDefaultCellSize = 11;
inline constexpr size_t kDefaultMemoryCells = 259;
inline constexpr uint32_t kDefaultCellMask = (1u << kDefaultCellSize) - 1u;
```
位宽和长度**都不在指令集里**(`ROR` 只是在一个 cell 里转圈,纸带是环),所以它们只以
"参数 + 常量"的形式存在,落在三处。改位宽时照这个清单走:
1. **汇编器**:`import_file(path, cell_size)` 的第二个参数就是位宽,6 个调用点都传
`kDefaultCellSize`。`set_cell_size` 顺手把三个名字注入程序作用域:
`_CELL_SIZE`(位宽)、`_CELL_MAX = (1 << 位宽) - 1`、`_ROL_STEP = 位宽 - 1`。
宏里写 `%rep _CELL_SIZE { … }` 就自动跟着位宽走(`erase`、`rol`、所有字节级驱动都这么写),
所以**位级宏、`%synth` 切片、位运算天然与位宽无关** —— 实测 `r8forge_synth_test` 在
11 位下照样 8/8 全过。
2. **四份虚拟机**(`tests/synth_test.cc`、`tests/byte_op_test.cc`、`src/derive.cc`、
`tests/tape_run.cc`):cell 存 `uint16_t`、数组长 `kDefaultMemoryCells`、
旋转必须是 `(v >> 1) | ((v & 1) << (kDefaultCellSize - 1))`、输入输出掩码用
`kDefaultCellMask`。**四份要一起改**,少改一份就会出现"两个实现不一致"的假象。
3. **测试期望**:一律用 `kCellMask` / `kCellSize` 写,不要出现 `0xff`、`>> 8`、`256 - a`。
**注意 2048 % 256 == 0**,所以不少 8 位期望在 11 位下碰巧还成立(and/or/xor/not/dec/sub
就是),别把"没报错"当成"不用改" —— `neg`、`add`、`inc`、`mul` 一改位宽当场就错。
踩过的坑:
* **`.xor` 的常数按当前位宽解释**。`asm/test.r8asm` 原来写 `.xor (~126)+1` 想置 130,
11 位下变成 `2048-126 = 1922`;改成直接写 `.xor 130`。
* **纸带会变长**:`%rep _CELL_SIZE` 从 8 轮变 11 轮,`raw_add` 1647 → **2199** 字符,
`fibonacci` 8761 → **11959**。写死的长度断言要跟着改。
* **`output` 打印整个 cell 的值**,不再是一个字节;`out` 里出现 257、1088 这种数是对的
(`127+130 = 257`、`200*200 = 19*2048 + 1088`)。
* **交叉验证要先对齐几何**:几何一致时同一条纸带输出完全相同(`asm/test.r8asm` 两边都是
`1322 1786 1600 5 94 127`);不一致时不是谁错了,是两台不同的机器。workspace 里的
`ROT-8-viz/` 是 upstream `starcells/ROT-8` 的 fork(`origin` = `dsh/ROT-8-viz`,`main`),
默认 **11 位 x 259 格**,几何还能运行期改(`--cell` / `--mem`;默认值与字段在
`include/rot8/rot8.h`,名字就是 `cell_size` / `mem_size`)。对答案的办法:
`ROT-8-viz/build/Release/rot8_test.exe <tape.rot8>` 把每个 `OUT` 按行打出来,
和 `r8forge_derive <src.r8asm> -1` 的 `out` 逐位比即可。
* 位宽变大还有个正面效果:`fibonacci` 不再在 256 处回绕,现在跑出 **13 项**(到 233)。
* **旧 tape 换到新位宽上不只是算错,还可能永远跑不完**:按 8 位写死的程序里
`%rep 8` 只转了 8 圈,在 11 位下 cell 没转回原位,"循环到某位清零"的条件于是永远不成立。
实测把改默认值之前的 `test.r8asm` 纸带喂给 11 位的 `rot8_test --dump`,它会一直跑
(ROT-8-viz 的普通/`--dump` 模式没有步数上限)。**换位宽就重新汇编,别复用旧纸带。**
## 字节级运算(一个 cell 一个机器字,默认 11 位)
结论:**库里的字节级宏是对的,穷举全过**。`r8forge_byte_op_test` 实测(这台机器约 10 秒;
2026-11 把 `clb_divmod` 扩到 16384 组、`clb_digits` 扩到全部 2048 个值之后)。
下面的纸带长度都是 **11 位 cell** 下的值(8 位时代的数字见 git 历史):
| 宏 | 驱动 | 纸带 | 结果 |
|---|---|---|---|
| `raw_add`(a+b,含进位) | `drv/raw_add_byte.r8asm` | 2199 字符 | **65536/65536** |
| `raw_and` | `drv/raw_and_byte.r8asm` | 870 字符 | **65536/65536** |
| `raw_or` | `drv/raw_or_byte.r8asm` | 782 字符 | **65536/65536** |
| `raw_xor` | `drv/raw_xor_byte.r8asm` | 628 字符 | **65536/65536** |
| `raw_inc`(a+进位) | `drv/raw_inc_byte.r8asm` | 1619 字符 | **512/512** |
| **`clb_add_nc`(a+b+进位,4 cell)** | `drv/raw_add_nc_byte.r8asm` | **937 字符** | **65536/65536** |
| **`clb_inc_nc`(a+进位,3 cell)** | `drv/raw_inc_nc_byte.r8asm` | **586 字符** | **256/256** |
| **`clb_neg_nc`(~a+进位,3 cell)** | `drv/raw_neg_nc_byte.r8asm` | **610 字符** | **256/256**(取负) |
| 同上,进位 0 | `drv/raw_not_nc_byte.r8asm` | **609 字符** | **256/256**(反码 `~a`) |
| **`clb_sub_nc`(a-b,4 cell)** | `drv/raw_sub_nc_byte.r8asm` | **962 字符** | **65536/65536** |
| **`clb_not_ip`(~a,原地,1 cell)** | `drv/not_ip_byte.r8asm` | **23 字符** | **256/256** |
| **`clb_inc_ip`(a+1,原地,2 cell)** | `drv/inc_ip_byte.r8asm` | **89 字符** | **256/256** |
| **`clb_neg_ip`(-a,原地,2 cell)** | `drv/neg_ip_byte.r8asm` | **111 字符** | **256/256** |
| **`clb_dec_ip`(a-1,原地,2 cell)** | `drv/dec_ip_byte.r8asm` | **133 字符** | **256/256** |
| **`clb_nonzero`(a!=0 的标志,原地)** | `drv/nonzero_byte.r8asm` | **284 字符** | **256/256** |
| **`clb_add_ip`(a+=b,原地,4 cell)** | `drv/add_ip_byte.r8asm` | **726 字符** | **2048 抽样全过**(O(b) 运行) |
| **`clb_mul`(mc×mul → 两 cell 积,10 cell)** | `drv/mul_byte.r8asm` | **3977 字符** | **65536/65536**(O(位宽) 运行) |
| **`clb_ones`(数量 → 从末位起 N 个 1,4 cell)** | `drv/ones.r8asm` | **742 字符**(带 output)/ **828**(最小驱动) | **12 个计数全对**(N=0..11) |
| **`clb_divmod`(N div D / N mod D,11 cell)** | `drv/divmod.r8asm` | **4499 字符**(最小驱动)/ 4511(带 output) | **16384 组全对**(8 个除数 × 全部 2048 个被除数;固定 11 轮,最坏 32,383 步,`2047/1` 不再挂) |
| **`clb_digits`(整数 → 4 位 ASCII 十进制,18 cell)** | `drv/digits.r8asm` | **13717 字符**(最小驱动)/ 13741(带 output) | **全部 2048 个值全对**(最坏 164,867 步;2047 是 14.5 万步) |
| **`raw_sub`(A-B,**保留 A、B**,Bo = 没借位,7 cell)** | `drv/raw_sub.r8asm` | **≈2900 字符** | **9 组抽样全对**;长除法要用它(`clb_sub_nc` 会把操作数吃掉) |
| `asm/fibonacci.r8asm` | — | 11959 字符 | 跑出 13 项 `1 1 2 3 5 8 13 21 34 55 89 144 233` |
`raw_*` 保留操作数(A、B 原样还回来),`clb_*_nc` 把 A、B 吃干净 —— 所以后者能省掉
`Co` 和 `tmp`:**4 cell 加法/减法、3 cell 自增/取负**。两者都用轮转驱动,差别只在
"操作数要不要还回去"。
**`clb_*_nc` 的进位 cell 是真正的进位输入**:宏自己**不动**它的初值(曾经写错过 ——
加法里 `set_0`、自增里 `set_1`,那就不是输入了,而且把多字节串接堵死了)。
调用者给 0 就是普通运算,给 1 就是"自带 +1"的那种,或者把上一字节的进位输出接过来串。
### 补码
`-A = ~A + 1`、`A - B = A + ~B + 1`,所以取负/减法都是"取反 + 加法/自增",
那个 +1 由调用者通过进位输入给:
| 宏 | 做法 | Ci=1 | Ci=0 |
|---|---|---|---|
| `clb_neg_nc A S Ci` | 先 `clb_not_ip A` 把整个字节原地取反,再走 `clb_inc_nc` | `-A`(补码取负) | `~A`(反码) |
| `clb_sub_nc A B S Ci` | 先 `clb_not_ip B` 把整个字节原地取反,再走 `clb_add_nc` | `A - B` | `A - B - 1` |
**取调整字节一次、提到循环外面**,比"每 bit 取反一次"更短(也少两个 `flb` 包装):
8 位时代是 468 → 448、467 → 447、725 → 707;11 位下的实测值见上表(610 / 609 / 962)。
B 本来就会被加法吃掉,所以在原地取反它没有任何代价。
`clb_sub_nc` 的进位输出是**没有借位**(`A >= B` 时为 1),所以它顺带就是无符号比较;
`clb_neg_nc` 的进位输出只在 `A` 原本是 0 时为 1(`-0 = 0` 但确实进了位)。
取反必须发生在切片**外面**:想让 `%synth` 自己取反(表 `S=~A^Ci`、进位 `~A&Ci`,3 参数)
报 `no program up to 8 layers`。原因是模型只会"牺牲一个 cell → 条件翻转别的 cell",
A=0 时整块跳过、S 只能留在 0,而取反要求 A=0 时 S=1 —— "无条件翻转"表达不出来。
### 原地(结果回到原来的 cell)
| 宏 | 干什么 | cell | 纸带(11 位) | 穷举 |
|---|---|---|---|---|
| `clb_not_ip A` | `A = ~A`(反码) | 1 | **23** | 256/256 |
| `clb_inc_ip A T` | `A = A + 1` | 2 | **89** | 256/256 |
| `clb_neg_ip A T` | `A = -A`(补码取负) | 2 | **111** | 256/256 |
| `clb_dec_ip A T` | `A = A - 1` | 2 | **133** | 256/256 |
| `clb_nonzero B F T` | `F = (B != 0)`,B 不动 | 3 | **284** | 256/256 |
| `clb_add_ip A B T F` | `A += B`,B 被吃掉 | 4 | **726** | 2048 抽样 |
对比写回 S 的切片版:`clb_inc_nc` 586(3 cell)、`clb_neg_nc` 610(3 cell)——
**原地版短 5 倍、少一个 cell**。`clb_neg_ip` 就是 `clb_not_ip` + `clb_inc_ip`。
**"原地补码不可能"这个结论是错的,这里记一下它是怎么错的**(别再复现同样的推理):
* `%synth` 的四个原地表(`A←~A^Ci`、`A←A^Ci`、`A←A^B^Ci`、`A←A^~B^Ci`)确实全部报
`no program up to 8 layers`,原因是**一个合成块只有一个条件 cell**,区分不了
"A=1 且 Ci=0" 和 "A=1 且 Ci=1"。这一步是实测,没问题。
* 错在把它当成了整条路的结论。手写**不一定要照逐位进位链写**。
真正可行的算法换个思路,不去逐位测进位:
1. 用 `[ ... ]` 的自然语义(最低位非零就继续)把**最低位连续的 1 清掉**(`flb` + `ror`),
遇到第一个 0 时退出循环;
2. 那个 0 翻成 1 —— 输入是全 1(0xFF)时跳过,正好就是回绕那一格;
3. 剩下的位置只旋转,转满八格为止。
卡点变成"还要转几格",而 cell 只有两个。解法是**把计数塞进 T 的位里**:T 先做成 0xFF,
每转一格就 `set_0` + `ror` 消掉一个 1 —— 一串 1 的长度就是剩余圈数(每步 3 字符的移位寄存器
计数器,一圈正好数八格)。于是两个 cell 够用,而且比切片版短得多。
顺带纠正另一半:`[ ... ]` 的"跑了就必然消耗被测位"不是死路 —— 只要被测的是**计数器**,
不是数据。这条以前被写成"手写也做不到(2 cell)",错的。
原地取反仍然是最便宜的一个:`%rep _CELL_SIZE { flb; ror }`,一个 cell、23 字符。
自减用补码恒等式拼出来,不用新算法:`B - 1 = ~(-B)`,所以 `clb_dec_ip` = `clb_neg_ip` + `clb_not_ip`(133 字符)。
### 原地加法,以及"只有纸带长度是目标"这条
`clb_add_ip A B T F`:`A += B`,原地,4 个 cell(A、B、T、F),**726 字符**,
B 被吃干净。对比:`raw_add` 2199(6 cell,保留操作数)、`clb_add_nc` 937 + 每轮一次 `copy`。
**没有去写逐位的进位链加法**:全加器的进位是 `maj(a,b,c)`,也就是两两的合取,而每个条件测试
都会吃掉被测的那一位,所以要么先拷贝好几份位、要么嵌套测试 —— 又长又脆。
改成利用一件在本仓库里成立的事:**只有纸带长度是目标,运行步数不是**。
while B != 0: A += 1 ; B -= 1
循环体在纸带里只出现一次,所以长度和 B 的大小无关;代价是运行 O(B)(B=255 时约 30 万步,
`r8forge` 的上限是 500 万)。**这个取舍在别处也能用** —— 凡是"长度优先"的地方都可以想
"能不能用循环把代码压掉"。
剩下的难点是"B != 0"怎么测(`biz` 只测最低位)。`clb_nonzero B F T` 的做法:每位先把它
搬进工作位 T(这一步清掉 B 的那一位),若 T 是 1 就把 F **置一**并还原 B 的那一位,
转一格看下一位;八轮后 B 原样、F = (B != 0)。注意是 `set_1` 不是 `flb` —— 这里踩过:
`flb` 是翻转,偶数个 1 位会把标志翻回 0(3、5、255 都测错过)。
### 乘法器(`asm/mul.r8asm`)
`clb_mul MC MUL PL PH MCA S Ci T F NR`:`(PH:PL) = MC * MUL`,10 个 cell,**3977 字符**,
`r8forge_byte_op_test` 现在**穷举 65536 组**(0..255 × 0..255)全对,最坏运行 **26123 步**
(`2047 * 2047`,11 位下的整个域)。
用的是**二进制移位-加法**(竖式乘法),一位一位串:
A:PH = 0 ; C:F = 0 ; Q:PL = MUL
repeat _CELL_SIZE:
if Q & 1: (C:PH) += MC ; 一次 W 位加法,进位出到 F
(C:PH:PL) >>= 1 ; 跨格右移,最高位补 0,最低位(刚看的那位)丢掉
W 轮之后 `(PH:PL)` 就是积;`PL`(原来的 Q)被移空,所以 **MUL 结束为 0**,和原来的约定一样。
**为什么换掉重复加法**:重复加法的轮数 = `MUL` 的值,成本 ∝ MUL。`MUL = 2047` 时实测直接
`HANG after 5000000 steps`——也就是大乘数根本算不完。移位-加法的轮数 = 位宽,**跟操作数的
值无关**,11 位下封顶 26123 步:
| 算式 | 重复加法(旧) | 移位-加法(现在) |
|---|---|---|
| `82 * 141`(MC=82, MUL=141) | 358586 步 | **8374 步** |
| `82 * 141`(MC=141, MUL=82) | 214741 步 | **6974 步** |
| `255 * 255` | 733428 步 | **17785 步** |
| `100 * 403` | 1026648 步 | **10208 步** |
| `2047 * 2047` | **HANG**(>500 万步) | **26123 步** |
| `2047 * 0` | 270 步 | 1863 步 |
纸带同时短了:**5007 → 3977 字符**。代价只有一条:乘数是 0/1 这种小值时反而慢一点点
(旧版循环 0/1 次就完了,新版固定要转满 `_CELL_SIZE` 轮)——拿它换「乘数再大也不会挂」。
所以 `asm/test.r8asm` 里那条"永远把小操作数放 MUL"的规矩**已经没用了**(保留 141 只是
为了跟历史结果对得上)。
拼法上踩过两个坑:
* **跨格移位**:`(C:PH:PL) >>= 1` 得当成一个 2W+1 位的寄存器来移。做法是三格先各 `ror`
一格,把要注入的那一位搬到 bit0(`rol` 回来),用 `clb_bit_mov` 搬过去,再 `ror` 回去。
顺序必须是**低位那对先搬**(PH→PL 先做),否则 PH 的 bit0 已经被 F 覆盖了。
* **`biz`/`rnz` 是循环对,不是 if/else**:条件块的身体必须把被测位吃掉(最后一条 `flb`),
否则 `rnz` 看到还是 1 就跳回去 —— 第一版就是这么写成死循环的(现象:`out` 一个都没有、
计数器停在 0x7ff 没动)。被测的正好是 `PL` 的最低位,而它本来就要被右移丢掉,吃掉它
不影响移位。`set_0` / `clb_bit_mov` 身体里那个 `flb` 是同一个道理。
轮数用什么数:计数器 `NR` 先做成 `_CELL_SIZE` 个 1(`%rep _CELL_SIZE { set_1; ror }`),
每轮 `set_0` + `ror` 吃掉一个 —— 和 `clb_inc_ip` 数圈数是同一个法子。一串 1 的长度就是
剩余轮数,所以"做几轮"不占纸带长度,只占运行时间。
**设计上的教训(这一版)**:上一轮把"移位-加法"否掉了,理由是「只有纸带长度是目标」——
可那只说明**当时**的取舍,而且结论其实反了:移位-加法不但更短(3977 < 5007),
步数还少一到两个数量级。真正的原因不是它更长,而是把"跨格移位 + 条件累加"想复杂了 ——
`rol`/`ror` 加一条 `clb_bit_mov` 就能拼,三行的事。
**先看目标函数再选算法**这条本身没错,但目标函数里得把「500 万步上限」写进去:
长度优先的循环写法(`clb_add_ip`、旧的 `clb_mul`)在纸带上不吃亏,运行时间上会随值线性长大。
顺带纠正一个流传下来的说法:`raw_add` **不**吃掉操作数。实测 `5+3 → A=5 B=3 S=8`,
`255+255 → A=255 B=255 S=254 Co=1`。`asm/fibonacci.r8asm` 里"每圈都要重新复印"的注释
是过度保守(它确实复印了,但不复印也对)。
### 这次差点被写进文档的错误诊断(别再犯)
有一轮里,`raw_add` / `raw_and` / `copy` / `fibonacci` 全被判定"运行时是坏的",
理由是 `set_0` 对多字节 cell 不收敛、纸带跑到步数上限。**那是虚拟机写错了**:
仓库里有三份解释器(`tests/synth_test.cc`、`src/derive.cc`、`tests/tape_run.cc`)
把 `biz`/`rnz` 实现成了"整格是否为零"(Brainfuck 直觉),于是每个字节级程序
都变成死循环。改回 `& 1` 之后全部通过。
为什么之前没被发现:位级程序在两种语义下行为完全一样(0/1 的最低位就是它自己),
`%synth` 的表、`asm/test.r8asm`、`full_add` 全都不受影响;只有字节级驱动能区分。
**所以以后凡是"字节级看起来跑不动",第一个怀疑对象是虚拟机,不是库。**
验证方法:拿 `ROT-8-viz/build/rot8_test.exe` 跑同一条纸带对答案。
`tests/tape_run.cc` 现在是正确语义(`& 1`),可以直接对。
### 另一位一 cell 的实现在这里被删过一次(别再加回来)
"每个 bit 一个 cell、用 `clb_bit_add_nc` 串成 8 位加法器"这条路能跑通(32 cell,
1308 字符,65536 组合全对),但它是上面那个错误诊断的产物:既然一个 cell 能放一个字节、
位读得出来,就没必要为每个 bit 花一个 cell。R8Forge 之前也删过一次同样的东西
(交接文档原话:"8 位加法 25 个 cell,没有实用价值")。
**要拼字节级运算就用 `raw_*` / `clb_*_nc` / `clb_*_ip`。**
## %synth 相关
* 语法:`params N` + `mode tape|layers` + `layout ...`(可选,只在 `--synth-chars` 下有用)
+ 目标表 `stat ...` 或 `map ...`。`stat` 的项数必须是 `2^params`(3 参数要 8 项)。
参数是输入位 `%1..%K`、输出位、剩余草稿位(草稿位必须结束为 0,语义见 `compress_stat_space`)。
* **代价口径是隐式的**(源码里没有 `metric` 行了,写了会报错):默认 flat —— 不计 `.tp`
行走、结果与 cell 布局无关、缓存可跨调用点复用;`r8forge --synth-chars <file>` 才对这次
汇编里的**所有**块按真实布局算(`r8asm::set_synth_metric(0)`,CLI 在 `tests/asm_test.cc`)。
full_add 上两个口径分别是 95 / 90 字符。`metric blocks` 已删(块数不是纸带长度的好代理)。
* 缓存:`.r8forge_cache/`(**已入库**,克隆下来直接命中)。键 = 模型版本 + params + mode +
metric + **解析后的整张目标表**(+ layout,仅 chars)。改指令模型时要 bump
`kModelVersion`(`src/synth.cc`)。
* 缓存代价参考:`bit_raw_add` 的 flat 搜索 990,636,137 状态 / 680 秒 / ~22 GB 内存。
层数上限现在是 8(原来是 5,5 会把一些可行的表误判成不可能)。
## 已经验证可行的东西
| 东西 | 结论 |
|---|---|
| 库里的 7 个位运算块(and/or/xor/inc/add) | 合成版比手写短(8 位时代 1714 → 1666;位宽改了以后位级块不受影响,长度变的是字节级那层) |
| `asm/test.r8asm` 现在是一个 hash | 11 位下 **28729 字符**,`h = (h + c) * 141 mod 2048` 滚过 "R8F",跑出 `1322 1786 1600 5 94 127`(前三 = 三轮的 h,后三 = 三轮的 PH,即 `(h+c)*141 >> 11`)。只用 `clb_add_nc` + `clb_mul`,没有位运算 —— "会加减乘就能算 hash"的最小证明。`derive` 与 ROT-8-viz 两边逐位一致,**57330 步**(乘法器换成移位-加法之后,原来约 207 万步) |
| `clb_bit_add_nc`(4 cell 忽略进位切片) | flat 代价 **27**,完整全加器切片是 38;8/8 组合正确(与位宽无关) |
| `clb_bit_inc_nc`(3 cell 自增切片) | 表 `0 4 4 2 0 4 4 2`(3 参数)缓存里就有,4 blocks;4/4 组合正确(与位宽无关) |
| `clb_add_nc`(4 cell 加法) | 11 位下 937 字符,65536 组合全对;比 6 cell 的 `raw_add` 少 2 个 cell |
| `clb_inc_nc`(3 cell 自增/加 0-1) | 586 字符,256 组合全对;比 5 cell 的 `raw_inc` 少 2 个 cell |
| `clb_neg_nc`(3 cell 取负/取反) | 610 / 609 字符,各 256 组合全对(Ci=1 取负、Ci=0 反码) |
| `clb_sub_nc`(4 cell 减法) | 962 字符,65536 组合全对;进位输出顺带是无符号比较(A >= B) |
| `clb_not_ip`(1 cell 原地取反) | **23 字符**,256 组合全对 |
| `clb_inc_ip`(2 cell 原地自增) | **89 字符**,256 组合全对;切片版 `clb_inc_nc` 是 586 |
| `clb_neg_ip`(2 cell 原地取负) | **111 字符**,256 组合全对;切片版 `clb_neg_nc` 是 610 |
| `clb_dec_ip`(2 cell 原地自减) | **133 字符** = `neg` + `not`(`B-1 = ~(-B)`),256 全对 |
| `clb_nonzero`(非零标志) | **284 字符**,256 全对,B 保持原样 |
| `clb_add_ip`(4 cell 原地加) | **726 字符**,2048 抽样全对;`raw_add` 2199 |
| `clb_mul`(10 cell 乘法,积占两个 cell) | **3977 字符**,65536 组穷举全对;轮数只跟位宽有关(最坏 26123 步),跟 MUL 的值无关 |
| `clb_ones`(4 cell,数量 → 从末位起 N 个 1) | **828 字符**(最小驱动),N=0..11 全对;`rol` + `set_1` 就是 `B = 2B + 1`,A 当计数器吃干净 |
| `clb_ones` + `loop`/`endloop` | **动态循环**:次数由运行期数据决定。`verify_loop.r8asm` **939 字符**,N=0..11 正好跑 N 次(A=N、C=0,N=0 一圈不跑);嵌套也对(NO×MI,11×11=121)。见 SPEC §5.1 |
| `bit_raw_add`(6 cell 全加器切片) | 保留 A、B;字节级 `raw_add` 2199 字符,65536 组合全对 |
| `raw_and` / `raw_or` / `raw_xor` / `raw_inc` | 870 / 782 / 628 / 1619 字符,各 65536(inc 512)全对 |
| `asm/fibonacci.r8asm` | 11959 字符,跑出 13 项(`… 89 144 233`),比 8 位时代多 3 项 |
| `examples/` 里的例程 | **每组宏一份**,9 个程序(§10.3 的表)+ 4 个 `%synth` 例子。每个都是能跑的程序,头部 `; out ...` 是它打印什么;`r8forge_examples_test` 全部跑一遍逐项核对(缺那行也算失败),顺带打印纸带长度和步数 |
## 已经确认走不通的(别重试)
* **3 个 cell 做加法切片**:层数上限 5 和 8 都报 `no program up to N layers`
(3 cell 的**自增/取负**切片是有解的,两个操作数塞不进 3 个 cell)。
* **原地写回的 `%synth` 表**:`A←~A^Ci`、`A←A^Ci`、`A←A^B^Ci`、`A←A^~B^Ci` 四个表全部报
`no program up to 8 layers`。原因是一个合成块只有一个条件 cell,区分不了 "A=1 且 Ci=0"
和 "A=1 且 Ci=1"。**但手写可以**:换成"清连续 1 + 计数器旋转"的算法,2 cell 就够
(`clb_inc_ip` 89 字符、`clb_neg_ip` 111 字符,见「原地」)。别把这条读成"手写也不行"。
* **让切片自己在输入上取反**(表 `S=~A^Ci`、进位 `~A&Ci`,3 参数):`no program up to 8 layers`。
模型只会"牺牲一个 cell → 条件翻转别的 cell",输入为 0 时整块被跳过、S 只能保持 0,
表达不出"无条件翻转"。取反只能放在切片外面(一条 `flb`)。
* **4 cell 的加法切片要做到"保留 A、B"**:表改成保留 A、B 后报 `no program up to 8 layers`。
想拿回操作数只能用 6 cell 的 `bit_raw_add`。
**但这不等于"轮转需要保留操作数"** —— 这句以前写错过。轮转只是
"读走最低位 → 丢掉 → `ror`",吃掉操作数完全没问题:`clb_add_nc`(4 cell)就是这么跑的,
65536 组合全过。
* 字节级(2^16 项真值表)交给 `%synth`:搜索空间不可行。
* **删掉位级包装宏里的 `set_0`**(想法是"`%synth` 的 `stat` 已经把初值算进去了,
输出位不用先清"):**错的**。`stat` 表对输出位的初值是周期的(旧实现先清再算),
而 `compress_stat_space()` 把"初值不影响终值"的位从搜索初态里清成 0 —— 搜出来的块
只保证**初值为 0** 的调用点。2026-11 实测删掉 9 处 `set_0`:`raw_add`/`raw_and`/
`raw_or`/`raw_xor` 照样全过(轮转驱动每轮把结果写在 bit0 上就转走,输出位的 LSB
一直是 0),但 `clb_mul` 62064/65536 错、`clb_divmod` 14742/16384 错、
`clb_digits` 2048/2048 错(其中一个 HANG)。见 SPEC §3.6。
## 命名与注释格式(照 `SPEC.md`,别自己发明)
规格分两份:
* **本仓库的 `SPEC.md`**:`%synth` 指令、机器几何、**`asm/` 里每个宏的契约**
(签名 / 参数类型 / 吃什么留什么 / cell 数 / 纸带长度 / 由哪个测试验证)、
纸带长度的测量口径。加宏、改宏、写文档之前先看它。
* **上游语言规格**:`C:\Users\peng0\git\r8asm_rev-fork\SPEC.md`(`r8asm_rev` 里那份一模一样)。
语言、内建指令、运算符优先级、作用域、标准宏前缀都在里面。`%synth` 不在里面 ——
那是 R8Forge 自己的扩展,看本仓库的 `SPEC.md`。
* **ROT-8 指令集规格**:`C:\Users\peng0\git\ROT-8-viz\README.md`("1-Bit Brainfuck 变体",
指令表里写明 `BIZ`/`RNZ` 判 **LSB**)。
SPEC 第 136-150 行的标准宏前缀:
| 前缀 | 全称 | 含义 |
|---|---|---|
| `clb` | clobber | 破坏性宏,会破坏原始输入(多数情况是清零) |
| `bit` | bit | 对 cell 的 **LSB** 操作的宏 |
| `raw` | raw | 未经封装的宏,**通常要手动传入 tmp cell 作为实参** |
**`raw` 不是"暴露 cell 作为参数"**(这条以前写错过):`raw_add` 之所以叫 raw,
是因为它要你自己给 `Co` 和 `tmp` 那两个草稿 cell。`bit` 则说明所有 `CellBit` 形参
指的都是最低位 —— 这跟 `biz`/`rnz` 判 `& 1` 是同一件事:整套语言是围绕"1 位"设计的。
既有宏对号入座:
| 宏 | 为什么这么叫 |
|---|---|
| `raw_add` / `raw_and` / `raw_or` / `raw_xor` / `raw_inc` | 字节级,且草稿 cell 由调用者传 |
| `bit_raw_add`(6 cell) | 位级,且 `%6: buf` 是真正的草稿:内容无关,结束是垃圾 |
| `clb_bit_add_nc`(4 cell) | 四个 cell 都有意义,没有草稿 cell(所以没 `raw`),而 A、B 被吃掉(所以有 `clb`):第 3 个是"进→出"的进位,`A=0 B=0 进位入=1` 时 `S=1` |
| `clb_bit_inc_nc`(3 cell) | 同样:A 被吃掉,进位进→出,没有草稿 cell |
| `clb_add_nc`(4 cell)/ `clb_inc_nc`(3 cell) | 字节级版本,同样吃 A、B |
| `clb_neg_nc`(3 cell)/ `clb_sub_nc`(4 cell) | 补码取负/减法,同样吃 A(和 B) |
| `clb_not_ip` / `clb_inc_ip` / `clb_neg_ip` / `clb_dec_ip` / `clb_add_ip` | 同上再加 `_ip`(in place):结果回到原来的 cell,草稿 cell 由调用者传 |
| `clb_nonzero` | 破坏性的纯计算(把 B 抄成"非零"标志),不带 `_ip` 后缀 |
| `clb_ones` | 破坏性的纯计算(把"数量"展开成从末位起的一串 1,输入被吃干净);结果写在另一个 cell 里,所以也不带 `_ip` |
| `clb_divmod` | 破坏性的纯计算(除/取模,商 Q、余数 R 各落在自己的 cell 里,`S` 起 7 格草稿由调用者传);N、D 现在**保留**,`clb` 指的是 Q 和草稿块会被覆盖 |
| `clb_digits` | 破坏性的纯计算(整数 → 一串 ASCII 数字),输入被吃干净、结果写在连续区域里,所以不带 `_ip` |
| `loop` / `endloop` | 结构性的**宏对**(开/收一个运行时循环),不带前缀;不开 anchor 所以能嵌套,收口后 dp 停在计数器上 |
| `clb_bit_mov` | 位级搬运,并且把源吃掉 |
| `bit_copy` / `copy` | 位级/字节级拷贝,缓冲由调用者传(历史命名,少了 `raw`) |
| `set_0` / `set_1` / `erase` / `rol` / `step` / `back` / `output` | 基础操作,不带前缀 |
`%synth` 块名 = `<宏名>_synth`,包装的 `%macro` 用不带 `_synth` 的名字。
**后缀不是前缀**:`_nc` 是手写库留下的历史命名,`_ip` 是本仓库加的(in place,结果写回原来的
cell)。选名字时先按 SPEC 的三个前缀定位,再挑后缀。
宏里的注释:
```asm
; Macro clb_bit_add_nc
; %1: CellBit A
; %2: CellBit B
```
* `%this` 表示"dp 当前所指的 cell"(`set_0`、`clb_bit_mov` 都这么写)。
* 新宏先按上表选前缀。套不上的(块级、自己管草稿 cell 的)就在注释里写清吃什么、留下什么。
* **参数类型只用这五个**:`Cell`、`CellBit`、`Unit`、`UnitBit`、`Count`(纯数字,比如
`step` 的重复次数)。注释块贴在 `%macro` 上方,或者贴在生成它的 `%synth` 块上方,都行。
* `r8forge_macro_docs_test` 会检查 `asm/` 里每个 `%macro`:有没有注释块、
`; Macro <名字>` 和实际宏名是否一致、参数条数是否等于 argc、类型是否在上面这五个里。
加完新宏跑一下,别让它的输出从全绿变红。