From ac48820a84c626a7d74f1cb993b3b87b8bb5caa4 Mon Sep 17 00:00:00 2001
From: "peng.li24" <734991033@qq.com>
Date: Sat, 5 Sep 2026 06:54:45 +0800
Subject: [PATCH] =?UTF-8?q?readme:=20=E5=A2=9E=E5=8A=A0=20Benchmark=20?=
 =?UTF-8?q?=E6=AE=B5=E8=90=BD=EF=BC=88=E8=B7=A8=E8=AF=AD=E8=A8=80/?=
 =?UTF-8?q?=E5=90=8E=E7=AB=AF=E5=9F=BA=E5=87=86=20harness=20=E5=85=A5?=
 =?UTF-8?q?=E5=8F=A3=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

指向 benchmark/（#223）：kvlang vs Python/Rust/C × shm/fs/redis，规模冻结、
版本化 results.csv 追踪演进。EN/CN 同步。
---
 README.md    | 18 ++++++++++++++++++
 README_CN.md | 16 ++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/README.md b/README.md
index 044e1ccd..3559712b 100644
--- a/README.md
+++ b/README.md
@@ -269,6 +269,24 @@ python3 tutorial/error_test.py               # all negative tests
 
 ---
 
+## Benchmark
+
+`benchmark/` is a cross-language, cross-backend performance harness. Each case is one
+algorithm implemented identically in kvlang / Python / Rust / C; kvlang runs on all three
+kvspace backends (`shm` / `fs` / `redis`) as separate columns, with the native/scripting
+versions as baselines. Scales are fixed for long-term comparability, and every run appends
+to a versioned `results.csv` — same host + case, sorted by version, gives the perf-evolution
+curve.
+
+```bash
+python3 benchmark/run.py            # all cases × three backends, appends results.csv
+python3 benchmark/run.py --show     # print recorded history
+```
+
+See [benchmark/README.md](benchmark/README.md) for cases, timing convention, and CSV schema.
+
+---
+
 ## Design Documentation
 
 In-depth design and implementation docs covering the full architecture:
diff --git a/README_CN.md b/README_CN.md
index 3e86e3d1..198e28fb 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -266,6 +266,22 @@ python3 tutorial/error_test.py               # 全部负例测试
 
 ---
 
+## Benchmark
+
+`benchmark/` 是跨语言、跨后端性能基准。每个 case 是同一算法的 kvlang / Python / Rust / C
+等价实现；kvlang 分别在三个 kvspace 后端（`shm` / `fs` / `redis`）上各跑一列，原生/脚本版本作基线。
+规模固定以保证长期可比，每次运行只追加到带版本号的 `results.csv`——按同机同 case、以 version
+排序即得性能演进曲线。
+
+```bash
+python3 benchmark/run.py            # 全部 case × 三后端，追加 results.csv
+python3 benchmark/run.py --show     # 打印历史记录
+```
+
+case、计时约定、CSV 字段见 [benchmark/README.md](benchmark/README.md)。
+
+---
+
 ## 设计文档
 
 深度设计与实现文档，覆盖全部架构：