docs: 讲清"值传递的开销只在 New 这一次", 并补上浅拷贝/深拷贝的分岔

两处之前没说清楚的地方。

一、值传递的代价只发生在构造那一次, 不影响之后的操作

原来只列了 New(值) 3227ns vs New(&v) 25ns, 容易被读成"传值之后一直慢"。
实际上构造完成后两者的内部表示完全相同(都是类型描述符 + 地址), 后续
Get/Set 走同一条代码路径:

                     构造后 Get          构造后 Set
  New(v)  传值构造    49.7ns / 2 allocs   27.2ns / 0 allocs
  New(&v) 传指针构造  50.3ns / 2 allocs   27.1ns / 0 allocs

差异在噪声范围内。所以要看的是**构造频次**而不是访问频次: 构造一次访问很多次
的话那点开销会被摊薄; 每个请求都构造、对象又含 map/slice 时才值得计较。

二、流程图补上值分支内部的二次分岔

图是在 needsClone 那次优化之前画的, 一直写着"传值 = DeepClone", 已经不准:

  不含引用成分(纯值 struct/数组/字符串) -> 逐字节浅拷贝, 约 85 ns
    字符串虽然内部有指针, 但底层数组不可变, 共享是安全的
  含指针/切片/map/interface(递归包含字段与数组元素) -> DeepClone

这也是"能不能 copy 一份再取指针"的答案: 纯值类型可以(库里已经这么做了),
含引用的类型不行 —— 浅拷贝只复制 slice/map 的头部, 底层数据仍与调用方共享,
写入会穿透, 那就不再是隔离副本了。

顺带把代价数字更正为实测值(原来写的 1518ns/44allocs 是另一个更小的样本)。

docs/flow.md

@@ -49,9 +49,35 @@
 | | 做法 | 代价 | 语义 |
 |---|---|---|---|
 | **传指针** `New(&v)` | 直接借用该指针 | 约 25 ns,零拷贝 | 写入**直接反映到原数据** |
-| **传值** `New(v)` | `DeepClone` 递归复制整个对象图 | **约 1518 ns / 44 allocs**(10 元素 + map 的对象) | 写入**不影响原数据** |
+| **传值 + 纯值类型** | 逐字节浅拷贝 | 约 85 ns | 写入**不影响原数据** |
+| **传值 + 含引用成分** | `DeepClone` 递归复制整个对象图 | 10 键嵌套 map 约 **3227 ns / 119 allocs** | 写入**不影响原数据** |
 
-**传值比传指针贵约 60 倍**,而且随对象规模增长。如果不需要副本语义,一律传指针。
+传值这一支还要再分一次,依据是类型描述符里预先算好的 `needsClone`
+(构建期算一次,不在热路径):
+
+- **不含引用成分**(纯值 struct、数组、字符串)→ 逐字节复制就已经完全独立了。
+  字符串虽然内部有指针,但底层数组不可变,共享是安全的。
+- **含指针 / 切片 / map / interface**(递归包含字段与数组元素)→ 必须 `DeepClone`。
+  只做浅拷贝的话,slice 和 map 复制的只是**头部**,底层数据仍与调用方共享,
+  写入会穿透过去 —— 这正是"能不能只 copy 一份再取指针"这个问题的答案:
+  对纯值类型可以(库里已经这么做了),对含引用的类型不行。
+
+**这笔开销只发生在 `New` 这一次,不影响之后的任何操作。**
+构造完成后两者的内部表示完全相同(都是"类型描述符 + 地址"),
+后续 `Get`/`Set` 走的是同一条代码路径:
+
+| | 构造后 `Get` | 构造后 `Set` |
+|---|---|---|
+| `New(v)` 传值构造 | 49.7 ns / 2 allocs | 27.2 ns / 0 allocs |
+| `New(&v)` 传指针构造 | 50.3 ns / 2 allocs | 27.1 ns / 0 allocs |
+
+所以判断标准是**构造频次**,不是访问频次:
+
+- 构造一次、访问很多次 → 传值的那点开销会被摊薄,可以忽略
+- 每个请求都构造(比如把查询结果包成 R)、而且对象含 map/slice → 这时候
+  那 3227 ns 是实打实的,值得改成传指针
+
+不需要副本语义就传指针;取不到地址的表达式先落一个局部变量。
 
 `DeepClone` 还有一个已知限制:**遇到循环引用会栈溢出**(`CloneValue` 没有已访问集合)。
 这是旧实现就有的行为,当前实现直接复用了它,所以两边表现一致 ——