docs: collect every leftover TODO into one file

"Not done yet" was scattered: AGENTS had a five item candidate list, docs/divmod.md
had a "no optimisation we skipped" section, README pointed at neither, and the
tree carried one genuine code marker nobody had noticed -- src/r8asm.cc:154
still says "TODO: FILL THE BLANK" above the ROT8_NODE macro (inherited from
upstream, so it is recorded rather than changed).

TODO.md now holds all of it, each item with why it matters and where to start:

  interaction   the desk calculator (input plumbing is already in place)
  tools         --opt peephole + tape diff, --profile, %synth --verify, CI
  text/picture  clb_puts + mini printf, 259 cells as a frame buffer
  skipped opts  clb_divmod's ~D precompute, clb_digits layout, the 495 char copy
  not TODOs     SPEC 12 "we already proved this cannot work" stays out of it

AGENTS' candidate section shrinks to a pointer, README gains a row in both of its
index tables, and docs/divmod.md 6 is linked from the optimisation entry instead
of being rewritten.
This commit is contained in:
dsh committed 2026-11-09 17:22:25 +08:00
1 parent d9689f81ba
commit 0d08fdc838
3 files changed
+50 -14

No files matched your search

+3 -14
View File
@@ -100,21 +100,10 @@ r8forge_derive verify_loop.r8asm -1 0=5 # out 5 0
* **字节级程序"跑不动"先怀疑虚拟机**:仓库里曾有三份解释器把 `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 一起)。
候选、想清楚但没做的优化、以及工具侧的小尾巴都收在 [`TODO.md`](TODO.md);
`SPEC.md` §12 是"别试"的结论,不是待办。
## 索引
+2
View File
@@ -13,6 +13,7 @@ ROT-8(1-Bit Brainfuck)的**汇编器** + **汇编期合成器**,一个仓
| `%synth` 完整语法、机器几何、**每个宏的契约**(吃什么留什么、几个 cell、纸带多长、谁验证) | [`SPEC.md`](SPEC.md) |
| 怎么干活、踩过的坑、当前交接、别动清单 | [`AGENTS.md`](AGENTS.md) |
| 设计推理长文(为什么这么写、失败的尝试) | [`docs/`](docs/) |
| 还没做的事(候选、优化、工具) | [`TODO.md`](TODO.md) |
## 30 秒上手
@@ -141,3 +142,4 @@ build/Release/r8forge_derive verify_loop.r8asm -1 0=5 # 动态循环:out
* [`AGENTS.md`](AGENTS.md) —— 工作手册:构建/自检命令、硬规则、坑、当前交接。
* [`docs/divmod.md`](docs/divmod.md) —— `clb_divmod` 的移位-恢复除法:每轮状态、坑、实测。
* [`docs/byte-ops.md`](docs/byte-ops.md) —— 字节级库的设计推理与教训。
* [`TODO.md`](TODO.md) —— 还没做的事:交互计算器、纸带优化器、`--profile`、缓存体检、CI。
+45
View File
@@ -0,0 +1,45 @@
# TODO
"还没做"的事都收在这一个文件里,别散在 README/AGENTS/docs 中。每条写清楚**为什么值得做**和
**从哪开始**;做完就删掉(历史在 git log 里)。`SPEC.md` §12 那张"已经确认走不通"的表是
**结论**,不是待办,别混进来。
## 交互式计算
* **桌上计算器**(`examples/calc.r8asm`):输入 `12+34=` 输出 `46`,支持 `+ - * /`。
条件已经齐了:`inp` 在三个 VM 里都有实现、`tape_run`/`derive` 能用 `-i` 脚本化喂输入、
例程头部能声明 `; in ...`;数字用 `clb_undigits` 攒、回打用 `clb_digits`、
四则用 `clb_add_nc` / `clb_mul` / `clb_divmod`(都穷举验证过)。
要设计的是**字符分派**:`'0'..'9'`(0x30..0x39)bit4 是 1,`'*' '+' '-' '/'`
(0x2A..0x2F)bit4 是 0 —— 一次 `ror` + `biz` 就能分开;运算符再按 `t = C - 0x2A`
的小整数链式比较。先写 `drv/calc_lex.r8asm` 单点验证分派,再拼整机。
## 工具
* **`r8forge --opt`:纸带级窥孔优化**(收益面最大):`><`、`<>`、`--`、11 个 `++`、
重复清位…… 要能重算跳转偏移。配套 `r8forge_tape_diff`(比较两条纸带的 OUT 流和步数)
证明等价 —— 一次改动全库受益。
* **`--profile`**:统计每段宏/每个 cell 的步数占比和 `.tp` 行走距离,用数据决定下一步优化谁
(现在"`.tp` 行走占七成"还是估的)。
* **`%synth --verify`**:把 `.r8forge_cache/` 里每条结果按对应表的所有输入重跑一遍,
给"缓存已入库"兜底 —— 一条坏条目会让每次构建静默用错块。
* **CI**:`enable_testing()` + 六条 `add_test`,再接一个 workflow,push 即跑全套(现在 46 万组
验证只能靠人记得敲命令)。**ROT-8-viz 那边更值得先做**:它目前零测试,串行默认 / `-n` /
几何 / 7E1 全靠手测,而它又是权威虚拟机。
* **`src/r8asm.cc:154`** 有个上游留下的 `// TODO: FILL THE BLANK`(`ROT8_NODE` 宏的
children 是空的)。那是继承来的实现,先记着,别顺手改。
## 文本与画面
* **`clb_puts` + 迷你 `printf`**:现在只能一个 cell 一个字符地打,缺"把一段 cell 当字符串
打出来"和 `%d`/`%c`/`%s` 的格式化,例程就能打印整句话而不是光秃秃的数字。
* **把 259 格当帧缓冲**:串行下 `\r`(0x0D)能原地重绘,1 bit/cell 的 16×16 位图或 8×8
生命游戏都能塞进纸带,`rot8_test --live` 里直接看它动。
## 想清楚但没做的优化
* **`clb_divmod` 预计算 `~D`**:单轮 2019 → 973 步,估计 28.6k → 17.6k 步,纸带净 −76;
没换是因为当时指名用 `raw_sub`。细节和注意事项见 [`docs/divmod.md`](docs/divmod.md) 第 6 节。
* **`clb_digits` 的布局**:13 格草稿跨得很开,`.tp` 行走占了纸带的大头;重排草稿格应该能
明显缩短(未实测)。
* **`clb_divmod` 里那个 495 字符的提交 `copy`**:还是全展开的,可以想压缩的办法。