chore: 清理仓库——移除本地配置/损坏文档/失真架构图，删除两处冗余分层

[NeverENG]

两类清理：不该在仓库里的东西，和代码里的冗余分层。

一、不该在仓库里的东西

文件	为何移除
.claude/settings.local.json	Claude Code 的每机本地配置（文件名里的 .local 即其定位），随开发者机器而异
goroutine.prof	一次 pprof 采样的产物
5 个 .bat	手工 Windows 脚本；项目在 macOS 开发、CI 跑 Linux，raft 下两个只是 go test 的包装
导学-BanDB.md、面经-BanDB.md、AGENTS.md	我误提交的（见下）

.gitignore 相应放宽为整个 .claude/，并加 *.prof 与那三个个人文件。根目录 CLAUDE.md 不受影响（它在 .claude/ 之外，是随仓库分发的协作规范）。

需要交代的错误

那三个文件本是未跟踪的，被我在「修正 Mata 拼写」那次提交的 git add -A 里连带入库，而且推上了 main —— 该 commit 的说明只写了拼写修正，完全没提这三个文件。同类问题在本会话中发生三次，前两次我在 push 前发现并重建了历史，这次没有。根因是本仓库里 git mv 会立即暂存重命名，git add -A 随之把无关的未跟踪文件一并纳入。后续一律按显式路径暂存。此处从仓库移除但保留工作区副本。

二、内容已失真的文档

判定标准是客观的，不是我的口味：这批文件无法按 UTF-8 解码——GBK 编码在迁移中未转换的残留，终端里显示为乱码（如「使用指�?」）。而且全部指向 E:\Code\bandb 这个不存在的路径，以及 cmd/server/server.go 这个不存在的文件。

cmd/ban-cli/README.md   150 行   PowerShell 用法 + 已删除的 run.bat
raft/TEST_README.md     189 行
raft/README_TESTS.md    110 行
raft/TEST_REPORT.md     276 行   手写的测试报告

三份 raft 测试文档合计 575 行且互相重叠。手写的测试报告在测试一改即过期，CI 与 go test 才是事实来源。

architecture-diagram.md 单独说：它画的是「MVCC 事务管理层」「事务管理器」「分配 ReadTS/WriteTS」「快照视图」「TxnID」——这些在代码里出现 0 次，本项目没有任何 MVCC 或事务实现。一张画错的架构图比没有架构图更糟：读者会据此去代码里找根本不存在的组件。README 里那张与实现一致的图保留。

docs/ 下 15 篇带日期的迭代记录全部保留——它们记的是「遇到什么问题、为何这么选」，不会过期。

三、代码里的冗余分层

storage.Engine 删除

删掉无人使用的 apply 通道后，它的 8 个方法已全部退化为一行转发（Put/Get/Delete/Scan/SnapshotLive/Close/FlushToSSTable 都直接调同名的 MemTable 方法），不承载逻辑、不做适配，只是调用链上多出的一跳。KVServer 与压测代码改为直接持 *MemTable。

顺带记录一处未处理的职责问题：MemTable 自身持有 sst *SSTable 并负责 getFromSSTables/FlushToSSTable/CompactSSTable——它实际上就是整个 LSM 引擎，而不只是一张内存表，名字与职责不符。理清需要拆分类型，属独立改动。

cmd/ban-cli 改用 SDK

CLI 仍带着自己 224 行的帧编解码，是全仓第 4 份线格式实现。删除后两种模式统一走 SDK，并因此免费获得超时、有界重试与 ErrKeyNotFound：get 不存在的键不再报「读取失败」，而是明确提示并以退出码 3 返回，便于脚本判别。

顺带修两处既有缺陷：

• 命令行模式下地址硬编码 localhost:8080，无法指定 → 改为 -addr。
• usage 宣称 client <addr> 进入交互模式，但 main 把「有位置参数」一律路由到命令模式，地址会被当成未知命令——这条文档里的用法从来无法执行。现按标准 flag 解析。

验证

go build ./...（含 -tags pprof）、go vet ./...、go test -race ./...、gofmt 全绿。CLI 两种模式已对真实服务端实测：put/get/delete/scan 正常，键不存在返回退出码 3。

净减约 1400 行。

🤖 Generated with Claude Code

[github-actions]

🐯 BanGD 数据库内核评审

整体风险：🟢 低

变更总结：本 PR 完成两类清理，本质是「重构所有权边界 + 收紧工程纪律」。

一、仓库清污：移除 settings.local.json（每机配置）、goroutine.prof（pprof 产物）、5 个手工 .bat 脚本、误提交的个人材料（导学-BanDB.md/面经-BanDB.md/AGENTS.md），以及三份 GBK 乱码的 raft 测试文档和一张与实现严重不符（虚构 MVCC/事务层）的架构图。这是把「不应属于仓库生命周期、会随开发者/编码环境漂移的状态」从版本控制的所有权中剥离——与数据库里「本地中间态/日志不该进 WAL」是同一件事。.gitignore 相应收紧为整目录忽略，并新增历史误提交文件的忽略规则。

二、代码分层瘦身：删除 storage.Engine——它已退化成纯转发层（8 个方法全部一行调 MemTable），不承载逻辑也不做适配，纯粹是调用链上多余的一跳。KVServer 与压测代码改为直接持 *MemTable，消除了「适配层之外还套着一层适配」的职责边界模糊。顺带把 cmd/ban-cli 从第 4 份手写帧编解码改为统一走 client SDK，消除了线格式实现的第 4 份拷贝，并免费获得超时/重试/ErrKeyNotFound 语义，同时修正了地址硬编码与 usage 与实际路由不符两处缺陷。

改动不触及存储格式、WAL 记录格式或任何并发不变量，仅作结构性重构与仓库卫生，净减约 1400 行。

本评审不阻塞合入；架构级建议以 Issue 形式跟踪，普通问题在下方内联列出。

架构问题（共 2 项）

• [错误处理] 退出码 3 属硬编码魔法值，缺统一契约 cmd/ban-cli/main.go → 🐯 [错误处理] 退出码 3 属硬编码魔法值，缺统一契约 · main.go #263
• [schema] MemTable 名不副实，实为整个 LSM 引擎 service/fsm.go → 🐯 [schema] MemTable 名不副实，实为整个 LSM 引擎 · fsm.go #264

普通问题（共 2 项）

⚠️ [重要 · 错误处理] cmd/ban-cli/main.go:47 runCommand 错误路径下不打印 usage 却返回退出码 2

• put/get/delete 参数不足分支返回退出码 2（本意是「用法错误」），但并未调用 usage() 或打印任何用法提示——用户只会看到「用法: ban-cli put 」一行，与 default 分支（未知命令会打印 usage）的行为不一致。既有的 usage 契约未在这些分支统一落地。
• 建议：在这些 arg 校验失败分支统一先调 usage()（或至少补齐用法提示），再返回 2，让「用法错误」类型的退出码有统一的用户体验。

💡 [建议 · 错误处理] cmd/ban-cli/interactive.go:140 交互 hit 的 get 分支缺少对条带空值的校验

• 交互模式的 handleGet 拿到 value 后直接 fmt.Printf("\"%s\"\n", string(value))。命令模式 main.go 里 get 分支对空 value（len==0）会打印空串，行为一致，但交互模式对 ErrProtocol 等解析类错误没有单列处理（如 SDK 可能返回 ErrProtocol），仅归入通用 ❌ 错误 打印——与命令模式用 errors.Is(err, bandb.ErrKeyNotFound) 判别语义的粒度不对称。
• 建议：在 handleGet 中对 ErrKeyNotFound 之外再对 errors.Is(err, bandb.ErrProtocol) 这类协议错误做专门提示（键值解析失败），与命令模式保持行为一致。

---

_{本次评审消耗 token：共 286161 tokens（输入 269348，输出 4909，缓存命中 11904，缓存写入 0）｜维度 [concurrency, memory, lock, storage, schema]｜补充阅读周边文件 [client/client.go, storage/memtable.go, pkg/proto/scan.go, pkg/predicate/predicate.go]｜对抗式复核 3 票/条，过滤疑似误报 0 条}