Files
R8Forge/AGENTS.md
T
dsh ebc7b7c72e docs: split the machine-local half of AGENTS.md into an ignored AGENTS.local.md
AGENTS.md was carrying two kinds of things: project facts (semantics traps, the
do-not-retry list, baselines, pointers) and this-machine facts (the Visual Studio
cmake path, PowerShell's GBK read-modify-write trap, the git identity and the
sandbox elevation needed to push, the flaky %synth temp file, "put slow commands
in the background").  Only the first kind belongs in a repo: a contributor on
another machine gets noise from the second, and half of it goes stale the moment
the box changes.

So AGENTS.md keeps the project (124 lines) and points at AGENTS.local.md for the
rest; AGENTS.local.md is gitignored, so a fresh clone simply re-creates it for its
own machine.  The commit identity rule stays in AGENTS.md (it is repo policy) and
now defers the mechanics to the local file.

No content is lost: the moved bullets are byte-identical apart from the framing.
2026-11-09 16:37:54 +08:00

7.8 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。

# 当前基线:都通过,别弄坏
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 位会跑出一个看起来正常的错答案)。

工作方式(踩过的)

  • 写结论之前先对虚拟机:字节级结论必须能被 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);改宏之后 顺手跑一遍基线,别只信自己这次跑出来的数。

  • 一次会话很难把结论留在对话里 —— 落进 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 不在里面) r8asm_rev/SPEC.md(本机路径见 AGENTS.local.md)
ROT-8 指令集(BIZ/RNZ 判 LSB) ../ROT-8-viz/README.md 与 src/rot8.c