The calculator now behaves like the terminal tape from the previous commit:
every character is echoed, backspace edits the digit window, Enter commits the
line and prints the next prompt, and '.' puts its result on its own line:
> 12 34 + .
0046
> 12<BS>3 .
0013
> ^D
It is not the terminal's line buffer moved over: the calculator consumes one
character at a time, and replaying a buffered line would mean unrolling the
engine once per buffer cell, which does not fit. Line editing here is the
digit window: backspace shifts it right by one, pads a '0' in front, echoes
"space, backspace" and keeps accumulating.
Three things had to be learned the hard way, all recorded in docs/calc.md ?8:
* a borrowed constant cell gets eaten. KBS (the 8 that backspace subtracts)
lived in SC+5, and the operator step erases SC..SC+6 wholesale, so the first
byte after an operator was treated as a backspace -- every character of
"12 34 + ." came out as an erase. It is now loaded right before each use.
It also must not borrow R: the EOF test writes R every round.
* set_1 only forces the low bit; cells lent to the classifier have to be
re-initialised each round rather than assumed clean.
* the prompt after Enter has to be printed before the command dispatch and the
operators run, because EH (the "this was Enter" flag) borrows SC+3, which
mul uses as scratch -- the first version printed a prompt after every
multiplication.
The tape went 64983 -> 73624 characters (+8.6k: three copies for the window
shift alone are ~4.4k, the two subtracts ~3k). That is past the old
ROT-8-viz INS_SIZE of 65536; the current VM sizes its buffer from the tape and
runs 112802 characters at 16 bits and 336304 at 32 bits, so only the
historical budget is gone, not the ability to run it. Ducking under 65536
again would mean dropping line editing: echo plus the Enter prompt alone is
about +2.5k, still over.
Verified: ctest 8/8 (examples_test checks the new header stream), the width
matrix at 11, 16 and 32 bits (calc stream, terminal tape and the viz's serial
output all agree; 73624 / 112802 / 336304 characters), and docs/calc.md records
step counts for the whole session list -- "12 34 + ." is 287589 steps, about
17% more than before the front end.
14 KiB
给接手的 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 都能跑。 - 有符号数已经做完(SPEC §5.4 的约定、§7.10 的实现):
clb_digits_signed(-0042这种显示)、clb_divmod_signed(截断除法、余数随被除数)、计算器的一元负号 (examples/calc.r8asm)。加、减、乘按二补码天然正确,没有改。 - 计算器是 3 格 RPN 栈 + 终端外壳(73624 字符):数字压栈、运算符立刻算(弹二压一)、
.显示栈顶但不动栈;打字有回显、退格能改数字、回车提交并补提示符。旧的两寄存器版 算不了嵌套(1 2 + 3 4 * + .打0007,现在0015)。终端的实现与三个坑见docs/calc.md§8;代价是超过旧 INS_SIZE(65536)(现在 viz 按纸带长度分配缓冲, 16 位 112802、32 位 336304 都照跑)。 examples/term.r8asm是行编辑终端(21721 字符):4 格行缓冲 + 退格编辑 + 回车/EOF 提交 + 按行首字符分派命令(l长度、r反着打、q退出)。表头那组in lhi就能 测到整条分派链(EOF 会把没提交的行也提交掉)。- 全绿基线(这台机器约 1 分钟;命令见下)。
- 另一个仓库
../ROT-8-viz(forkdsh/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 -C Release -j 4` 一次跑完 8 条,约 12 秒。
# VS 是多配置生成器,**`-C Release` 不能省**,否则 8 条全报 "Not Run")
r8forge asm/test.r8asm # 62351 字符(除两个有符号包装宏外每个宏一次 + 每个语言特性)
r8forge_byte_op_test # 23 项(divmod 16384 组、digits 2048、digits_signed 2048、divmod_signed 4202、undigits 4096);8/11/16 位真跑,17 位以上打印 skipped
r8forge_examples_test # 19 个 example + asm/test.r8asm,核对头部 `; out`/`; in`
r8forge_macro_docs_test # 55 macros in 23 files
r8forge --opt asm/test.r8asm # 纸带窥孔优化 62351 -> 56338(>< 净位移、+ mod W、- mod 2)
r8forge_tape_opt in.rot8 out.rot8 # 同一优化,但作用在已有纸带上
r8forge_tape_run t.rot8 --profile # 剖面:指针移动占 66~73% 步数(实测,见下)
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 分钟)
powershell -File tests\widths.ps1 -Widths 32 # 32 位:整套 10 个 target 能建,byte_ops 只打印 skipped
位宽上限是 32(每份 VM 的 cell 都是 uint32_t;CMake 里 -DR8FORGE_CELL_SIZE 越界直接
FATAL_ERROR,所以别再指望 C++ 报错才发现)。想往上要按 SPEC §13 的清单同时改五份 VM、
geometry.hh、汇编器的立即数类型和 ROT-8-viz 的 rot8_data。drv/ 里的驱动必须
用 .var D _CELL_SIZE * 30103 / 100000 + 1 算位数 —— 写死 4 格导致 digits 三项在 8/16 位
一直挂着,2026-11 才修。
asm/test.r8asm 的纸带必须留在 65536 条指令以下(ROT-8-viz 的 INS_SIZE;现在的
虚拟机缓冲是按纸带长度现算的,这条是历史口径 + 交叉验证,别指望它)所以里面只有"每个宏
一次 + 两轮 hash",现在离上限只剩 ~3.2k。两个有符号包装宏不在里面:它们各自要把
clb_digits / clb_divmod 再展开一份(+12.1k / +5.6k)。它们的回归是
examples/signed_demo.r8asm(examples_test 会跑),穷举在 r8forge_byte_op_test。
r8forge_byte_op_test 是唯一按返回值判断字节级对错的;其它自检只证明"汇编得出来"或
"位级正确"。r8forge_derive 会检查汇编错误(漏 %include 时纸带是截断的,以前不看 error
位会跑出一个看起来正常的错答案)。
工作方式(踩过的)
-
写结论之前先对虚拟机:字节级结论必须能被 ROT-8-viz 复现。先确认那台机器的 viz 是重编过的—— 旧二进制的串行
INP只改低 7 位(2026-11 改成整格写入),症状是交互程序打出> 0000, 曾经被误判成"纸带坏了"。注意它现在默认串行输出, 要比数值流就加-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(默认串行)。 -
代价的大头是"走"不是"算":
tape_run --profile实测,计算器 71.1%、全家桶 73.0% 的步数是>/<,旋转只占 7%、翻转 46%。这台机器没有随机寻址,每次访问的代价就是15% 步数,正是因为它砍的是往返移动。|Δ地址|,所以布局才是性能旋钮:clb_digits的 13 格草稿重排一轮,全家桶 64513 -> 62351 字符、236439 -> 202159 步(SPEC §7.7);--opt再省 14 -
一次会话很难把结论留在对话里 —— 落进 commit message 和文件注释。
一条硬规矩:不许动机器语义
除了 INP/OUT 的语义(那是宿主接口,允许按需定义),机器语义在没有明确要求的情况下一个字都
不许改:8 条指令的行为、biz/rnz 判 LSB、+ 是右旋、- 翻最低位、步数怎么算、
内存是 259 格环、纸带从第一条指令跑到尾 —— 全部冻结。
这条规矩是有来由的:三份实现(derive / tape_run / ROT-8-viz)互为对拍,任何一边"顺手修一下"
都会让另外两边看起来是错的,而我们没有第二份规格可以裁决。要改语义,先在 SPEC 里写清楚、
再四份一起改(见 §13),否则只改工具和视图。
语义上会咬人的几条
'-' flb 翻转最低位 cell ^= 1
'+' ror 右旋整个 cell (注意:和 Brainfuck 的 +/- 不一样,写仿真器时别按常识猜)
'[' biz 最低位 0 -> 跳到匹配的 ']' 之后
']' rnz 最低位 1 -> 跳回匹配的 '['
biz/rnz判的是cell & 1,不是"整格是否为零"。所以set_0=[-]只清最低位 (255→254、128 原样、5→4),清整格要%rep _CELL_SIZE { set_0; ror }(erase)。- 条件块的身体必须回到它自己的条件 cell(净位移 0):
dp是汇编期常量,跳过/进入两条 路径的dp不一致之后所有.tp全部错位(症状:dp跑到 1023)。set_0的身体不移动、clb_bit_mov最后.tp before再flb(顺便吃掉条件)。 - 合成块只保证"输出位初值为 0" 的调用点(
compress_stat_space把初值无关的位清成 0), 所以位级包装宏里的set_0不能删 —— 删了clb_mul62064/65536 错、clb_divmod14742/16384 错、clb_digits2048/2048 错(其中一个 HANG)。见 SPEC §3.6。 - 位宽是
_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写成整格零判断,于是 所有字节级程序看起来都在死循环 —— 别再把库判成坏的。
刚做完的四件事:有符号数、RPN 栈、终端纸带、终端接上计算器
二补码、-0042 显示、截断除法、静默溢出,约定在 SPEC §5.4、实现在 §7.10。
clb_digits_signed / clb_divmod_signed 都是包装(真活还是 clb_digits /
clb_divmod 干的),加、减、乘一个字没改。两条容易踩的:
- 符号位靠
rol+bit_copy+ror读(49 字符)。别换clb_bit_mov—— 它吃掉源位, 于是1024会打成0000(examples/signed_demo.r8asm就是这条例子的回归)。 - 标志位在
biz/rnz里必须被吃掉才能退出,所以"用完还要留"的符号位要搬到另一格 (clb_bit_mov),这就是为什么clb_divmod_signed要 T1、T2、F 三格。
计算器接着换成了 3 格 RPN 栈(S0 栈顶 / S1 / S2):运算符立刻算、. 是真 peek、
一元负号按栈深判(DEPTH == 0)。旧的"两寄存器 + 待结算 OP"版本算不了嵌套
(1 2 + 3 4 * + . 打 0007,现在是 0015)。3 格是当时的纸带预算逼出来的:
一格一次 copy(约 500 字符),4 格就顶上 65536 —— 现在接了终端、纸带已经 73624,
所以这条预算不再是硬约束(4 格 = ~74.1k)。挪栈的次序不能反(从高往低搬)。
计算器最后接上了终端外壳(不是把 term.r8asm 的行缓冲搬进去):回显每个字符、
退格删数字窗口最后一位、回车提交并补 > 。三个坑值得记住:判据用的常量格会被
clb_sub_nc 吃掉 / 被运算整块 erase(要"用之前现装");set_1 只保证最低位是 1;
回车提示符必须赶在命令分派和运算之前打(EH 借的 SC+3 会被 mul 写掉)。
细节在 docs/calc.md §8。
examples/term.r8asm 又是另一种东西:**行缓冲(左对齐 + LEN)+ 退格编辑 + 回车/EOF 提交
- 命令分派**(
l长度、r反着打、q退出)。三条硬教训:
- "else" 必须用标志格写:
biz只在最低位是 1 时进身体,"没命中就做 B"不能靠推断 —— 先set_1一个 FLAG,命中那支清 0,出块再看。而且biz的条件格是当前 dp, 所以顺序必须是"先 set FLAG、再.tp到条件格、再 biz"(写反了就是每轮都命中)。 - 被减数会被吃掉:分类用的
clb_sub_nc吃操作数,所以回显/追加都要用副本 CE; 拿 C 当追加源的那一版,行缓冲永远是空的。 - 热单元格要挨着排:
copy/clb_sub_nc/clb_nonzero内部都有.tp,有的还在%rep _CELL_SIZE里 —— 常数格排到 22..28 时整条纸带 33k,挤进 0..27 就回到 21.7k。
下一步
候选、想清楚但没做的优化、以及工具侧的小尾巴都收在 TODO.md;
SPEC.md §12 是"别试"的结论,不是待办。眼下最靠前的是 TODO 里的"交互计算":
迷你 printf(终端纸带和计算器外壳都做完之后用处要重新评估)、以及栈要不要再深一格
(3 → 4 格现在没有预算障碍了)。
索引
| 想查 | 去哪儿 |
|---|---|
%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 |