Files
R8Forge/AGENTS.md
T
dsh a82d95658e docs: one home per fact -- README as the front door, SPEC as the contract, AGENTS as the manual
The three documents had grown to 2038 lines and quoted each other: 2199 appeared
seven times, 3977 ten times, AGENTS carried a 200-line copy of SPEC's byte-level
tables while README carried another 155-line copy still showing 8-bit-era numbers
(clb_add_nc 688, clb_not_ip 17, ...) that are wrong at 11 bits.

Split by responsibility, keep every fact exactly once:

  README.md   front door: what it is, 30-second build+run, directory map, where
              to read next                                     547 -> 143 lines
  SPEC.md     the contract: %synth, geometry, every macro's signature / cells /
              tape length / who verifies it, test matrix, boundaries, maintenance
                                                               901 -> 807 lines
  AGENTS.md   the manual: hard rules, build and self-check commands, the traps,
              current state, next candidates, do-not-touch list
                                                               590 -> 132 lines

Long-form reasoning moves into docs/ instead of being dropped:

  docs/divmod.md    the shift-restore division story (was SPEC 14, 102 lines;
                    renumbered 1..6, SPEC keeps a pointer and the references in
                    SPEC 7.6 and asm/divmod.r8asm now point there)
  docs/byte-ops.md  the byte-level design history (was README's 155-line section,
                    rewritten with 11-bit numbers since the old ones were
                    measured at 8 bits)

Also fixes what the dedupe exposed: SPEC no longer claims only the multiplier has
a step bound, and raw_sub's comment no longer repeats the retracted "1.48M steps"
figure. Every section reference in the tree resolves; the baseline still passes
(asm/test.r8asm 64513 characters, 21 byte-op items, 14 examples, 48 macros).
2026-11-09 16:34:15 +08:00

8.6 KiB
Raw Blame History

给接手的 agent 的话

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

动手前请把这份文件读完(约 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。

构建与自检

# 构建要用 build/ 配的那个 cmake(PATH 上的另一个版本会重新配置,然后死在
# "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

# 当前基线:都通过,别弄坏
r8forge asm/test.r8asm                      # 64513 字符(每个标准宏至少一次 + 每个语言特性)
r8forge_byte_op_test                        # 21 项(divmod 16384 组、digits 2048、undigits 4096)
r8forge_examples_test                       # 14 个 example + asm/test.r8asm,核对头部 `;   out`
r8forge_macro_docs_test                     # 48 macros in 22 files
r8forge_synth_test examples/full_add.r8asm  # all eight combinations ok
r8forge_derive verify_loop.r8asm -1 0=5     # out 5 0

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

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

工作方式(踩过的)

  • 超过 ~30 秒的命令丢后台(run_in_background),前台只做短轮询 —— 前台干等会撞上 客户端/API 的传输超时。

  • 别让大段 stderr 进上下文:PowerShell 遇到原生命令出错会吐 NativeCommandError 堆栈, 用 2>$null 收干净,判断靠 $LASTEXITCODE 和 stdout。

  • 写中文文件用 edit/write 工具,不要用 PowerShell 做"读-改-写":这台机器上 Get-Content 按 GBK 读 UTF-8,再写回去整篇乱码;Set-Content -Encoding ascii 更糟, 汉字直接变 ?。

  • 提交身份:两个仓库都用 dsh <dsh@gitea.local>(仓库主人的身份是 StarCells <peng080306@foxmail.com>,别用)。最稳的写法是每次带上: git -c user.name=dsh -c user.email=dsh@gitea.local commit -F msg.txt (msg 文件用 Set-Content -Encoding ascii,正文写英文)。

  • push 要提权:origin 是 gitea,http.sslBackend openssl 已经配好,但 workspace-write 沙箱会拦住 git 凭证助手的命名管道 —— push 时用 sandbox_permissions: danger-full-access; fetch 不需要。

  • 写结论之前先对虚拟机:字节级结论必须能被 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...]           # 直接喂纸带的第二份实现
    
  • %synth 的临时文件:汇编器把合成块写到系统临时目录再 import、然后删掉。这台机器上 偶尔失败,代码会退回当前目录重试并在 stderr 留一句 <tmp> is not writable, using <cwd> —— 看到这句不用管;cannot write the synthesised macro anywhere 才是真坏了。

  • 会话很长时传输容易失败:重要结论要落进 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 写成整格零判断,于是 所有字节级程序看起来都在死循环 —— 别再把库判成坏的。

下一步的候选(这轮没做)

按"先文档、再代码"的顺序,候选清单:

  1. 交互式 RPN 计算器(examples/rpn_calc.r8asm):串行读字符 → 数字串用 clb_undigits 攒成整数 → 几个 cell 的栈上算 + - * / → clb_digits 打回去。第一个真正有交互的 R8 程序。
  2. r8forge --opt:纸带级窥孔优化(><、--、11 个 ++、重复清位……),要能重算跳转 偏移;配一个 tape diff 证明 OUT 流不变。收益面最大。
  3. --profile:统计每段宏/每个 cell 的步数占比和 .tp 行走距离,用数据决定下一步优化谁。
  4. %synth --verify:把缓存里每条结果按对应表的所有输入重跑一遍,给"缓存已入库"兜底。
  5. 文本/画面:clb_puts + 迷你 printf;或者把 259 格当帧缓冲做终端动画(串行下 \r 可以原地重绘)。

别动:其它宏(改之前先看 SPEC 的契约和 docs/)、%synth 指令模型(改了 bump kModelVersion)、geometry.hh 的位宽(真要改照 SPEC §13 四份 VM 一起)。

索引

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