They used to write the carry cell themselves -- set_0 inside clb_add_nc, set_1
inside clb_inc_nc / clb_neg_nc / clb_sub_nc -- which made the parameter a lie: a
cell the caller passes and the callee overwrites is not a carry input, it is a
scratch cell wearing a carry's name. It also ruled out the thing a carry is for:
multi byte arithmetic. The carry out of the low byte could not be handed to the
high byte, because the high byte's call would zero (or one) it first.
Now the macros only read it, and the caller decides:
clb_add_nc A B S Ci S = A + B + Ci Ci = 0 plain add, or chained
clb_inc_nc A S Ci S = A + Ci Ci = 1 gives A + 1
clb_neg_nc A S Ci S = ~A + Ci Ci = 1 gives -A, Ci = 0 gives ~A
clb_sub_nc A B S Ci S = A + ~B + Ci Ci = 1 gives A - B, Ci = 0 A-B-1
which also turns the negate into two operations for free: two's complement
negation at Ci=1 and the ones' complement (~A) at Ci=0. The second one has its
own driver and test now (drv/raw_not_nc_byte.r8asm).
The drivers set the bit explicitly before the call, which is where that
instruction belongs -- the tapes end up the same length as before (688/430/468/725
instead of 693/433/471/730: one setup instruction moved out of the macro).
All nine byte level operations still pass, and the docs (AGENTS.md, README.md and
the four file headers) now state the carry in contract instead of describing a
constant.
17 KiB
给接手的 agent 的话
这个文件是给下一个会话(或者下一个 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/full_add_flat*.r8asm就这么坏过一次)。 -
构建要用 VS 自带的 cmake:
build/是Visual Studio 18 2026生成器配的, 直接敲 PATH 上的 scoop cmake(4.4)会因为版本不一致重新配置,然后死在No preprocessor test for "PellesC"。用这个:"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,权威实现)复现。 -
推代码:
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两种模式都不需要 (仓库可匿名读)。
构建与自检
# 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
自检:
r8forge asm/test.r8asm # 应 exit 0,1666 字符,7/7 命中缓存
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_byte_op_test # 字节级库:9 个操作穷举,0.7 秒
r8forge_macro_docs_test # asm/ 里每个宏的注释格式
r8forge_byte_op_test 是唯一按返回值判断字节级对错的;前三个只证明"汇编得出来"或
"位级正确"。
r8forge_derive 是验证工具:
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:
void rot8_biz(rot8_iter *iter) { if ((*(iter->mem_now) & 1) == 0) { ... } }
void rot8_rnz(rot8_iter *iter) { if ((*(iter->mem_now) & 1) == 1) { ... } }
由此推出两条关键约束:
set_0=[-]清的是最低位,不是整个 cell。set_0把 255 变成 254、把 128 原样留着、把 5 变成 4。要清整个字节就%rep _CELL_SIZE { set_0; ror }(erase就是这么写的)。一个字节的位能读:ror若干次把目标位转到最低位,再biz。- 合成的程序只碰每个 cell 的低 K 位(K = 参与运算的输入位数),高位不追踪。
所以
%synth出来的块只适用于"每格一位"的世界。
曾经这里还写过第三条("多字节 cell 的位读不出来")—— 那是把 biz 当成 Brainfuck 的
整格零判断推出来的,错的,已删。
字节级运算(一个 cell 一个字节)
结论:库里的字节级宏是对的,穷举全过。r8forge_byte_op_test 实测(0.7 秒):
| 宏 | 驱动 | 纸带 | 结果 |
|---|---|---|---|
raw_add(a+b,含进位) |
drv/raw_add_byte.r8asm |
1647 字符 | 65536/65536 |
raw_and |
drv/raw_and_byte.r8asm |
639 字符 | 65536/65536 |
raw_or |
drv/raw_or_byte.r8asm |
575 字符 | 65536/65536 |
raw_xor |
drv/raw_xor_byte.r8asm |
463 字符 | 65536/65536 |
raw_inc(a+进位) |
drv/raw_inc_byte.r8asm |
1214 字符 | 512/512 |
clb_add_nc(a+b+进位,4 cell) |
drv/raw_add_nc_byte.r8asm |
688 字符 | 65536/65536 |
clb_inc_nc(a+进位,3 cell) |
drv/raw_inc_nc_byte.r8asm |
430 字符 | 256/256 |
clb_neg_nc(~a+进位,3 cell) |
drv/raw_neg_nc_byte.r8asm |
468 字符 | 256/256(取负) |
| 同上,进位 0 | drv/raw_not_nc_byte.r8asm |
467 字符 | 256/256(反码 ~a) |
clb_sub_nc(a-b,4 cell) |
drv/raw_sub_nc_byte.r8asm |
725 字符 | 65536/65536 |
asm/fibonacci.r8asm |
— | 8761 字符 | 跑出 1 1 2 3 5 8 13 21 34 55,和文件注释一致 |
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 |
每轮 flb 取反 A 的最低位,再 clb_bit_inc_nc |
-A(补码取负) |
~A(反码) |
clb_sub_nc A B S Ci |
每轮 flb 取反 B 的最低位,再 clb_bit_add_nc |
A - B |
A - B - 1 |
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 —— "无条件翻转"表达不出来。
顺带纠正一个流传下来的说法: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。
%synth 相关
- 语法:
params N+mode tape|layers+metric chars|flat|blocks+layout ...(可选)- 目标表
stat ...或map ...。stat的项数必须是2^params(3 参数要 8 项)。 参数是输入位%1..%K、输出位、剩余草稿位(草稿位必须结束为 0,语义见compress_stat_space)。
- 目标表
metric flat:不计.tp行走代价 → 结果与 cell 布局无关、缓存可跨调用点复用。metric chars才是按实际布局最优。库里的块统一用flat。- 缓存:
.r8forge_cache/(已入库,克隆下来直接命中)。键 = 模型版本 + params + mode + metric + 解析后的整张目标表(+ layout,仅 chars)。改指令模型时要 bumpkModelVersion(src/synth.cc)。 - 缓存代价参考:
bit_raw_add的 flat 搜索 990,636,137 状态 / 680 秒 / ~22 GB 内存。 层数上限现在是 8(原来是 5,5 会把一些可行的表误判成不可能)。
已经验证可行的东西
| 东西 | 结论 |
|---|---|
| 库里的 7 个位运算块(and/or/xor/inc/add) | 合成版比手写短:asm/test.r8asm 1714 → 1666 字符 |
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;纸带 54 字符,4/4 组合正确 |
clb_add_nc(4 cell 字节加法) |
688 字符,65536 组合全对;比 6 cell 的 raw_add 少 2 个 cell、短 959 字符 |
clb_inc_nc(3 cell 字节自增/加 0-1) |
430 字符,256 组合全对;比 5 cell 的 raw_inc 少 2 个 cell |
clb_neg_nc(3 cell 取负/取反) |
468 / 467 字符,各 256 组合全对(Ci=1 取负、Ci=0 反码) |
clb_sub_nc(4 cell 减法) |
725 字符,65536 组合全对;进位输出顺带是无符号比较(A >= B) |
bit_raw_add(6 cell 全加器切片) |
保留 A、B;字节级 raw_add 1647 字符,65536 组合全对 |
raw_and / raw_or / raw_xor / raw_inc |
639 / 575 / 463 / 1214 字符,各 65536(inc 512)全对 |
asm/fibonacci.r8asm |
8761 字符,跑出 10 项斐波那契,和注释一致 |
已经确认走不通的(别重试)
- 3 个 cell 做加法切片:层数上限 5 和 8 都报
no program up to N layers(3 cell 的自增/取负切片是有解的,两个操作数塞不进 3 个 cell)。 - 让切片自己在输入上取反(表
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:搜索空间不可行。
命名与注释格式(照 SPEC.md,别自己发明)
R8ASM 的语言规格不在这个仓库里:
SPEC.md:C:\Users\peng0\git\r8asm_rev-fork\SPEC.md(r8asm_rev里那份一模一样)。 语言、内建指令、运算符优先级、作用域、标准宏前缀都在里面。%synth不在里面 —— 那是 R8Forge 自己的扩展,只有本仓库的 README 有文档。- 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_bit_mov |
位级搬运,并且把源吃掉 |
bit_copy / copy |
位级/字节级拷贝,缓冲由调用者传(历史命名,少了 raw) |
set_0 / set_1 / erase / rol / step / back / output |
基础操作,不带前缀 |
%synth 块名 = <宏名>_synth,包装的 %macro 用不带 _synth 的名字。
宏里的注释:
; 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、类型是否在上面这五个里。 加完新宏跑一下,别让它的输出从全绿变红。