Files
R8Forge/AGENTS.md
T
dsh ca72e19b0b tape_opt: the peephole pass -- 10% off the flagship tape with identical output
r8forge_tape_opt rewrites a tape with three run-local rules:

  > <   a maximal run of pointer moves becomes its net displacement
  +     a run becomes (length % _CELL_SIZE), a whole turn is a no-op
  -     a run becomes (length % 2), two flips cancel

The nice part is what it does NOT do: it never looks at brackets.  '[' and ']' are
not in any of the three character classes, so they always end a run, and within a
run only the net matters (the pointer moves are pure additions and nothing in
between is observable).  Keeping every run's net keeps the pointer identical at
every surviving character, brackets included, so the pairing that the machine
finds by scanning cannot change; and since bracket characters are never added or
removed, a run can never be merged across one.  No stack, no offset table, one
linear pass.

Measured, with tape_run's out stream compared before and after (and the reference
machine on the flagship's -n stream, same 93 values):

  asm/test.r8asm      64513 -> 58060   (-6453, 10.0%)
  examples/calc.r8asm 62585 -> 54863   (-7722, 12.3%)   "12 34 + ." identical
  examples/term.r8asm  3467 ->  3402   (  -65,  1.9%)   "hi" identical

Step counts unchanged (the removed instructions did nothing).  Not yet wired into
`r8forge` itself: the pipeline is `r8forge f.r8asm > t.rot8 && r8forge_tape_opt
t.rot8 t2.rot8`, and a --opt flag can wrap that later.
2026-11-18 10:29:53 +08:00

7.6 KiB
Raw Blame History

给接手的 agent 的话

这是 R8Forge 的工作手册:怎么干活、哪些坑已经踩过、现在交接到哪儿。契约和数字不在 这里 —— 那在 SPEC.md;设计推理的长文在 docs/。

这份文件入库,只写项目事实。只对某台机器/某个会话成立的东西(VS 的 cmake 路径、 PowerShell 的编码坑、git 身份和 push 提权、临时目录抽风……)放在 AGENTS.local.md, 它被 .gitignore 忽略、换机器重新写一份。新接手的环境先看那份。

动手前请把这份文件读完(约 5 分钟),需要细节时再按索引跳。历史教训里最贵的一条是: 有一轮把"移位-加法乘法器更快"当成新发现重推了一遍,其实早被否过又复活过 —— 结论都在 docs/byte-ops.md 和 SPEC §12 里,先读再推翻。

现在是什么状态

  • 汇编器 + 搜索器 + 标准库都齐了:%synth 汇编期合成、位级/字节级/原地/乘除/数字 转换(clb_digits ↔ clb_undigits)、动态循环、串行 ASCII I/O 都能跑。
  • 全绿基线(这台机器约 1 分钟;命令见下)。
  • 另一个仓库 ../ROT-8-viz(fork dsh/ROT-8-viz,分支 main)是权威虚拟机 + 可视化:默认 I/O 是串行 ASCII(cell ≥ 8 位),数值 I/O 用 -n / --numbers, 另有 7E1 帧(--parity / --stop / --7e1)。clb_digits 产出的 ASCII 直接喂它的 OUT。

构建与自检

cmake -S . -B build -G "Visual Studio 18 2026" -A x64
cmake --build build --config Release

# 注意:必须用给 build/ 配的那个 cmake(PATH 上的另一个版本会重新配置,然后死在
# "No preprocessor test for PellesC")。本机路径见 AGENTS.local.md。

# 当前基线:都通过,别弄坏(`ctest --test-dir build -j 4` 一次跑完 8 条,约 9 秒)
r8forge asm/test.r8asm                      # 64513 字符(除 raw_puts_dyn 外每个宏一次 + 每个语言特性)
r8forge_byte_op_test                        # 21 项(divmod 16384 组、digits 2048、undigits 4096)
r8forge_examples_test                       # 18 个 example + asm/test.r8asm,核对头部 `;   out`/`;   in`
r8forge_macro_docs_test                     # 53 macros in 23 files
r8forge_tape_opt in.rot8 out.rot8           # 纸带窥孔优化:>< 净位移、+ mod W、- mod 2(全家桶 −10%)
r8forge_synth_test examples/full_add.r8asm  # all eight combinations ok
r8forge_derive verify_loop.r8asm -1 0=5     # out 5 0
powershell -File tests\widths.ps1             # 位宽矩阵:每个位宽一套工具链 + 断言(约 20 分钟)

asm/test.r8asm 的纸带必须留在 65536 条指令以下(ROT-8-viz 的 INS_SIZE),所以里面 只有"每个宏一次 + 两轮 hash",现在离上限只剩 ~1k。加东西前先算长度。

r8forge_byte_op_test 是唯一按返回值判断字节级对错的;其它自检只证明"汇编得出来"或 "位级正确"。r8forge_derive 会检查汇编错误(漏 %include 时纸带是截断的,以前不看 error 位会跑出一个看起来正常的错答案)。

工作方式(踩过的)

  • 写结论之前先对虚拟机:字节级结论必须能被 ROT-8-viz 复现。注意它现在默认串行输出, 要比数值流就加 -n:

    ROT-8-viz/build/Release/rot8_test.exe -n <tape.rot8>   # 每个 OUT 打一行十进制
    r8forge_derive <src.r8asm> -1                          # 另一份实现,out 逐位比
    r8forge_tape_run <tape.rot8> [addr=value...]           # 直接喂纸带的第二份实现
    
  • 提交身份是 dsh,不是仓库主人:两个仓库都用 dsh <dsh@gitea.local>(仓库主人的 StarCells <peng080306@foxmail.com> 别用)。具体命令和本机的 git 配置见 AGENTS.local.md。

  • 数字要能被别人复现:§1.3 的口径写死了怎么量(最小驱动、不带 output);改宏之后 顺手跑一遍基线,别只信自己这次跑出来的数。

  • 交互程序这样测:r8forge_tape_run t.rot8 -i "12+34="(字符喂给 inp,低 7 位,读空后为 0), r8forge_derive <src> 0 -i "..." 是同一份输入的第二个实现;例程把输入写在头部 ; in ...,r8forge_examples_test 会自动喂。实时终端那一侧在 ROT-8-viz(默认串行)。

  • 一次会话很难把结论留在对话里 —— 落进 commit message 和文件注释。

语义上会咬人的几条

'-'  flb  翻转最低位        cell ^= 1
'+'  ror  右旋整个 cell     (注意:和 Brainfuck 的 +/- 不一样,写仿真器时别按常识猜)
'['  biz  最低位 0 -> 跳到匹配的 ']' 之后
']'  rnz  最低位 1 -> 跳回匹配的 '['
  1. biz/rnz 判的是 cell & 1,不是"整格是否为零"。所以 set_0 = [-] 只清最低位 (255→254、128 原样、5→4),清整格要 %rep _CELL_SIZE { set_0; ror }(erase)。
  2. 条件块的身体必须回到它自己的条件 cell(净位移 0):dp 是汇编期常量,跳过/进入两条 路径的 dp 不一致之后所有 .tp 全部错位(症状:dp 跑到 1023)。set_0 的身体不移动、 clb_bit_mov 最后 .tp before 再 flb(顺便吃掉条件)。
  3. 合成块只保证"输出位初值为 0" 的调用点(compress_stat_space 把初值无关的位清成 0), 所以位级包装宏里的 set_0 不能删 —— 删了 clb_mul 62064/65536 错、clb_divmod 14742/16384 错、clb_digits 2048/2048 错(其中一个 HANG)。见 SPEC §3.6。
  4. 位宽是 _CELL_SIZE(默认 11),宏里写 %rep _CELL_SIZE 就与位宽无关;改几何要照 SPEC §13 的清单四份虚拟机一起改。换位宽后旧纸带要重新汇编(写死的 %rep 8 在新位宽下 可能永远跑不完)。

已经确认走不通的(别重试,理由见 SPEC §12)

  • 3 个 cell 的加法切片:层数 5/8 都报 no program up to N layers(3 cell 的自增/取负 切片有解,两个操作数塞不进 3 个 cell)。
  • 原地写回的 %synth 表(A←~A^Ci 等四个)全部无解 —— 一个合成块只有一个条件 cell, 区分不了 "A=1 且 Ci=0" 和 "A=1 且 Ci=1"。但手写可以:clb_inc_ip 是 89 字符。
  • 让切片自己在输入上取反、4 cell 加法切片保留 A、B:都无解。想保留操作数用 6 cell 的 bit_raw_add。
  • 字节级真值表(2^16 项)交给 %synth:搜索空间不可行。
  • "每个 bit 一个 cell"再拼字节级运算:能跑通但没有意义,实现已删(一个 cell 能放一个字节、 位也读得出来)。要拼字节级就用 raw_* / clb_*_nc / clb_*_ip。
  • 字节级程序"跑不动"先怀疑虚拟机:仓库里曾有三份解释器把 biz 写成整格零判断,于是 所有字节级程序看起来都在死循环 —— 别再把库判成坏的。

下一步

候选、想清楚但没做的优化、以及工具侧的小尾巴都收在 TODO.md; SPEC.md §12 是"别试"的结论,不是待办。

索引

想查 去哪儿
%synth 语法语义、几何、宏契约、验证矩阵、边界、维护清单 SPEC.md
除法为什么这么写、实测步数、没做的优化 docs/divmod.md
字节级库的取舍、原地补码的突破、乘法器那一课 docs/byte-ops.md
上游语言规格(%synth 不在里面) r8asm_rev/SPEC.md(本机路径见 AGENTS.local.md)
ROT-8 指令集(BIZ/RNZ 判 LSB) ../ROT-8-viz/README.md 与 src/rot8.c