diff --git a/.gitignore b/.gitignore index 566a79c..92a8751 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,5 @@ build/ *.log *.synth.r8asm +# 本机手册(不入库) +AGENTS.local.md diff --git a/AGENTS.md b/AGENTS.md index d77c3ca..659c97d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,6 +3,10 @@ 这是 R8Forge 的工作手册:怎么干活、哪些坑已经踩过、现在交接到哪儿。**契约和数字不在 这里** —— 那在 [`SPEC.md`](SPEC.md);设计推理的长文在 [`docs/`](docs/)。 +这份文件**入库**,只写项目事实。只对某台机器/某个会话成立的东西(VS 的 cmake 路径、 +PowerShell 的编码坑、git 身份和 push 提权、临时目录抽风……)放在 `AGENTS.local.md`, +它被 `.gitignore` 忽略、换机器重新写一份。**新接手的环境先看那份。** + > 动手前请把这份文件读完(约 5 分钟),需要细节时再按索引跳。历史教训里最贵的一条是: > 有一轮把"移位-加法乘法器更快"当成新发现重推了一遍,其实早被否过又复活过 —— 结论都在 > `docs/byte-ops.md` 和 SPEC §12 里,先读再推翻。 @@ -19,10 +23,11 @@ ## 构建与自检 ```sh -# 构建要用 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 +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 字符(每个标准宏至少一次 + 每个语言特性) @@ -42,20 +47,6 @@ r8forge_derive verify_loop.r8asm -1 0=5 # out 5 0 ## 工作方式(踩过的) -* **超过 ~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 `(仓库主人的身份是 - `StarCells `,**别用**)。最稳的写法是每次带上: - `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`: @@ -65,10 +56,11 @@ r8forge_derive verify_loop.r8asm -1 0=5 # out 5 0 r8forge_tape_run [addr=value...] # 直接喂纸带的第二份实现 ``` -* **`%synth` 的临时文件**:汇编器把合成块写到系统临时目录再 import、然后删掉。这台机器上 - 偶尔失败,代码会退回当前目录重试并在 stderr 留一句 ` is not writable, using ` - —— 看到这句不用管;`cannot write the synthesised macro anywhere` 才是真坏了。 -* 会话很长时传输容易失败:**重要结论要落进 commit message 和文件注释**,别只留在对话里。 +* **提交身份是 `dsh`,不是仓库主人**:两个仓库都用 `dsh `(仓库主人的 + `StarCells ` 别用)。具体命令和本机的 git 配置见 `AGENTS.local.md`。 +* **数字要能被别人复现**:§1.3 的口径写死了怎么量(最小驱动、不带 `output`);改宏之后 + 顺手跑一遍基线,别只信自己这次跑出来的数。 +* 一次会话很难把结论留在对话里 —— **落进 commit message 和文件注释**。 ## 语义上会咬人的几条 @@ -128,5 +120,5 @@ r8forge_derive verify_loop.r8asm -1 0=5 # out 5 0 | `%synth` 语法语义、几何、宏契约、验证矩阵、边界、维护清单 | [`SPEC.md`](SPEC.md) | | 除法为什么这么写、实测步数、没做的优化 | [`docs/divmod.md`](docs/divmod.md) | | 字节级库的取舍、原地补码的突破、乘法器那一课 | [`docs/byte-ops.md`](docs/byte-ops.md) | -| 上游语言规格(`%synth` 不在里面) | `C:\Users\peng0\git\r8asm_rev-fork\SPEC.md` | +| 上游语言规格(`%synth` 不在里面) | `r8asm_rev/SPEC.md`(本机路径见 `AGENTS.local.md`) | | ROT-8 指令集(`BIZ`/`RNZ` 判 LSB) | `../ROT-8-viz/README.md` 与 `src/rot8.c` |