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.
This commit is contained in:
1 parent
a82d95658e
commit
ebc7b7c72e
2 files changed
+17
-23
No files matched your search
@@ -9,3 +9,5 @@ build/
|
||||
*.log
|
||||
*.synth.r8asm
|
||||
|
||||
# 本机手册(不入库)
|
||||
AGENTS.local.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 <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`:
|
||||
|
||||
@@ -65,10 +56,11 @@ r8forge_derive verify_loop.r8asm -1 0=5 # out 5 0
|
||||
r8forge_tape_run <tape.rot8> [addr=value...] # 直接喂纸带的第二份实现
|
||||
```
|
||||
|
||||
* **`%synth` 的临时文件**:汇编器把合成块写到系统临时目录再 import、然后删掉。这台机器上
|
||||
偶尔失败,代码会退回当前目录重试并在 stderr 留一句 `<tmp> is not writable, using <cwd>`
|
||||
—— 看到这句不用管;`cannot write the synthesised macro anywhere` 才是真坏了。
|
||||
* 会话很长时传输容易失败:**重要结论要落进 commit message 和文件注释**,别只留在对话里。
|
||||
* **提交身份是 `dsh`,不是仓库主人**:两个仓库都用 `dsh <dsh@gitea.local>`(仓库主人的
|
||||
`StarCells <peng080306@foxmail.com>` 别用)。具体命令和本机的 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` |
|
||||
Reference in new issue
Block a user