docs: AGENTS.md 首行 DESC 同步 31→33（matrix-tools doc_wave）

AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — oekit/pkg
 
-> 微工具集 31 合 1（errors/bloomx/contextx/ctxscope/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/secretx/shellx/timex/cache/bufiox/strmap/singleflighttest/urlguard/webhook/cli/pack/procx/config/tarx/resumable；v0.10.0 起 uidgen/validator 拆至 kitx）；errors（v0.12.0 起）New/As/Is/Unwrap 与 stdlib 同型透传——下游哨兵/As 判定单 import 即可，类型同一性红线可完整执行；cache（v0.4.0 起）含缓存接口 CacheAside + BatchGetter 批量能力（MGet）+ LocalCache/SingleFlightCache + cachetest 契约（Run 真实时间 + RunWithClock 假时钟确定性 TTL 边界）+ Checker；LocalCache 时钟可注入（LocalConfig.Now——TTL/NullTTL 全路径确定性测试，v0.13.0 起）；v0.16.0 起 LocalCache 可选形状——NoBackgroundSweep 关闭后台清扫 goroutine（嵌入式/短命进程，公开 Sweep 手动清扫口）、CloneOnRead 读命中返回副本（调用方可改写不污染缓存）、EvictPolicy 可选 LRU（默认 FIFO 不变）、GetEx 区分未命中与值为 nil（新增能力以可选接口 Sweeper/HitGetter 外置，不破坏其它后端）；v0.23.0 起补 Peek 非删除式读（可选接口 PeekGetter 外置——读到过期条目只算不命中、不删除它，stale-if-error 兜底需要那份过期真值留在表内；SingleFlightCache 包装 LocalCache 时曾因前置检查走 Get 惰性删除而静默废掉 StaleIfError，#72）；container（v0.9.0 起，收编原 collectionx）泛型容器 Set/Ring/Queue/SafeMap + Map（sync.Map 背书）/Slice（并发安全）；mathx/jsonrepair（v0.11.0）Unstable 单边向上抖动 Upward / 宽松解析 UnmarshalLenient / 抽对象与抽数组对称原语 ExtractObject·ExtractArray（v0.18.0 起——多段数组与散文含 '{' 的数组文本不再整段作废，取首个口径与对象面一致）；timex/stringx（v0.7.0 起）时间段边界 BeginningOf/EndOf 七对（分/时/日/周/月/季/年，周起始显式参数）+ trie 多模式替换器 Replacer（最长匹配）/ NewMask 敏感词遮罩；stringx Masker（v0.16.0 起）正则脱敏——按形态分类打码（形态标签进掩码供审计读）+ 保留首尾各 ≤4 字符定位线索且不可复原（保留位封顶不随长度变化），规则表由调用方完全提供；singleflighttest（v0.8.0 起）singleflight 共享契约测试套件（internal 与 concurrency 双侧引用）；urlguard（v0.15.0 起）出站 SSRF 防护原语——CheckURL 字面量校验（私网/loopback/链路本地含云元数据 169.254.169.254/CGNAT/ULA/组播保留、.internal·.local·localhost 域名、scheme 白名单、IPv4-mapped IPv6 归一）+ DialFunc 拨号层预解析校验与实际 RemoteAddr 端点核对闭合 TOCTOU（Happy-Eyeballs 覆盖），构造态豁免 WithAllowPrivate/WithAllowCIDRs/WithAllowDomains，与 httpx WithDialFunc 一行组合（httpx#11）；cli（v0.16.0 起）框架无关可单测的子命令分发原语——App/Command + 退出码 0/1/2 写死在包里、usage 按 Summary 自动生成、不读 os.Args 不调 os.Exit（输出流全由调用方给）；pack（v0.16.0 起）迁移包容器原语——zip + manifest（格式版本/条数/每文件 SHA-256）+ JSONL 流式读写 + Inspect 体检一次列全问题并区分包损坏与版本不认识；config/tarx（v0.42.0 起）启动期静态配置加载管线（yaml+env 覆盖+必填汇总校验+敏感字段脱敏 dump，#329）+ 目录 tar 传输三件套（同口径预扫 Scan/流式写出 Write/防御式解包 Extract 跳过并点名 Zip Slip 穿越条目 + sha256 manifest 自证，#326）；v0.43.0 起三处收口——cache.Checker 构造期 fail-fast（nil refresh panic/WithClock(nil) 回退默认，#356）+ 刷新跑在 WithoutCancel 上（leader 断开不再把取消缓存成 failTTL 传染等待者，瞬态 Canceled 不入缓存，#352）+ SingleFlightCache 按调用注入路径不再按 key 合并（source 不可比较，合并即串味/丢 TTL/强刷退化；Refresh 与 load 分键，#353）；container.Ring 逻辑序归基（32 位平台高频写入不再回绕出负下标 panic，#354）；cache/pack/urlguard 三个裸 Option 改名 CheckerOption/WriterOption/GuardOption（#355，禁裸 Option 仓规收尾）；v0.44.0 起三面补齐——shellx 词法事实面 Analyze（tokenize：普通词/重定向运算符+目标/动态词三类事实分离 + HasRedirect/HasDynamic/按控制符分段，前缀规则判据不再被「git status > /etc/passwd」整类绕过，判不了就报错不尽力解析，#358）+ procx 子进程内存上限原语（WithMemoryLimit/MemGroup：cgroup v2 memory.max 创建·设置·清理 + MemoryLimitCapable 问询面，兑现失败 fail closed 拒绝执行不静默不限、OOM-kill 与非零退出可辨、换出面一并封死、非 Linux 如实降级，#359）+ resumable 分片上传/断点续传会话面（新包：会话创建/分片登记/断点查询/完成/中止/Sweep 状态机，CAS 进度·合并抢占·双源对账·孤儿清扫四坑单点化，纯内存状态面 + ChunkStore 接口化存储后端，#361）
+> 微工具集 33 合 1（errors/bloomx/contextx/ctxscope/container/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/secretx/shellx/timex/cache/bufiox/strmap/singleflighttest/urlguard/webhook/cli/pack/procx/config/tarx/resumable/distlock/reflectx；v0.10.0 起 uidgen/validator 拆至 kitx）；errors（v0.12.0 起）New/As/Is/Unwrap 与 stdlib 同型透传——下游哨兵/As 判定单 import 即可，类型同一性红线可完整执行；cache（v0.4.0 起）含缓存接口 CacheAside + BatchGetter 批量能力（MGet）+ LocalCache/SingleFlightCache + cachetest 契约（Run 真实时间 + RunWithClock 假时钟确定性 TTL 边界）+ Checker；LocalCache 时钟可注入（LocalConfig.Now——TTL/NullTTL 全路径确定性测试，v0.13.0 起）；v0.16.0 起 LocalCache 可选形状——NoBackgroundSweep 关闭后台清扫 goroutine（嵌入式/短命进程，公开 Sweep 手动清扫口）、CloneOnRead 读命中返回副本（调用方可改写不污染缓存）、EvictPolicy 可选 LRU（默认 FIFO 不变）、GetEx 区分未命中与值为 nil（新增能力以可选接口 Sweeper/HitGetter 外置，不破坏其它后端）；v0.23.0 起补 Peek 非删除式读（可选接口 PeekGetter 外置——读到过期条目只算不命中、不删除它，stale-if-error 兜底需要那份过期真值留在表内；SingleFlightCache 包装 LocalCache 时曾因前置检查走 Get 惰性删除而静默废掉 StaleIfError，#72）；container（v0.9.0 起，收编原 collectionx）泛型容器 Set/Ring/Queue/SafeMap + Map（sync.Map 背书）/Slice（并发安全）；mathx/jsonrepair（v0.11.0）Unstable 单边向上抖动 Upward / 宽松解析 UnmarshalLenient / 抽对象与抽数组对称原语 ExtractObject·ExtractArray（v0.18.0 起——多段数组与散文含 '{' 的数组文本不再整段作废，取首个口径与对象面一致）；timex/stringx（v0.7.0 起）时间段边界 BeginningOf/EndOf 七对（分/时/日/周/月/季/年，周起始显式参数）+ trie 多模式替换器 Replacer（最长匹配）/ NewMask 敏感词遮罩；stringx Masker（v0.16.0 起）正则脱敏——按形态分类打码（形态标签进掩码供审计读）+ 保留首尾各 ≤4 字符定位线索且不可复原（保留位封顶不随长度变化），规则表由调用方完全提供；singleflighttest（v0.8.0 起）singleflight 共享契约测试套件（internal 与 concurrency 双侧引用）；urlguard（v0.15.0 起）出站 SSRF 防护原语——CheckURL 字面量校验（私网/loopback/链路本地含云元数据 169.254.169.254/CGNAT/ULA/组播保留、.internal·.local·localhost 域名、scheme 白名单、IPv4-mapped IPv6 归一）+ DialFunc 拨号层预解析校验与实际 RemoteAddr 端点核对闭合 TOCTOU（Happy-Eyeballs 覆盖），构造态豁免 WithAllowPrivate/WithAllowCIDRs/WithAllowDomains，与 httpx WithDialFunc 一行组合（httpx#11）；cli（v0.16.0 起）框架无关可单测的子命令分发原语——App/Command + 退出码 0/1/2 写死在包里、usage 按 Summary 自动生成、不读 os.Args 不调 os.Exit（输出流全由调用方给）；pack（v0.16.0 起）迁移包容器原语——zip + manifest（格式版本/条数/每文件 SHA-256）+ JSONL 流式读写 + Inspect 体检一次列全问题并区分包损坏与版本不认识；config/tarx（v0.42.0 起）启动期静态配置加载管线（yaml+env 覆盖+必填汇总校验+敏感字段脱敏 dump，#329）+ 目录 tar 传输三件套（同口径预扫 Scan/流式写出 Write/防御式解包 Extract 跳过并点名 Zip Slip 穿越条目 + sha256 manifest 自证，#326）；v0.43.0 起三处收口——cache.Checker 构造期 fail-fast（nil refresh panic/WithClock(nil) 回退默认，#356）+ 刷新跑在 WithoutCancel 上（leader 断开不再把取消缓存成 failTTL 传染等待者，瞬态 Canceled 不入缓存，#352）+ SingleFlightCache 按调用注入路径不再按 key 合并（source 不可比较，合并即串味/丢 TTL/强刷退化；Refresh 与 load 分键，#353）；container.Ring 逻辑序归基（32 位平台高频写入不再回绕出负下标 panic，#354）；cache/pack/urlguard 三个裸 Option 改名 CheckerOption/WriterOption/GuardOption（#355，禁裸 Option 仓规收尾）；v0.44.0 起三面补齐——shellx 词法事实面 Analyze（tokenize：普通词/重定向运算符+目标/动态词三类事实分离 + HasRedirect/HasDynamic/按控制符分段，前缀规则判据不再被「git status > /etc/passwd」整类绕过，判不了就报错不尽力解析，#358）+ procx 子进程内存上限原语（WithMemoryLimit/MemGroup：cgroup v2 memory.max 创建·设置·清理 + MemoryLimitCapable 问询面，兑现失败 fail closed 拒绝执行不静默不限、OOM-kill 与非零退出可辨、换出面一并封死、非 Linux 如实降级，#359）+ resumable 分片上传/断点续传会话面（新包：会话创建/分片登记/断点查询/完成/中止/Sweep 状态机，CAS 进度·合并抢占·双源对账·孤儿清扫四坑单点化，纯内存状态面 + ChunkStore 接口化存储后端，#361）；v0.45.0 起单源收敛十一单 + 双契约单源——distlock 分布式锁后端中立契约（Locker 接口两仓并集 + 哨兵错误集以 redisx 文案为基准 + WithLock 用 WithoutCancel 释放纪律，零依赖，redisx/etcdx 双后端消费同一份代码、errors.Is 跨包同一值，etcdx#123 治本侧）+ errors.PanicError panic 收编单源（error 身份不丢 + goroutine 栈 + panic 值类型）+ urlguard 内置拒绝哨兵与 CIDR 清单跨仓单源（ErrBlockedRange/ErrBlockedDomain/ErrExoticLiteral/BlockedCIDRSpecs，core#132 pkg 侧）；v0.46.0 起 reflectx 反射深拷贝单源（DeepCopyValue 指针环防护 + struct 先整块值拷贝保未导出字段、可 Set 引用字段逐一递归替换的强语义——core/config 与 pkg/pagination 两份平行实现收敛于此，core#130 治本侧）+ config.SetFromString/DurationType 字符串按 reflect.Kind 解析落位单源（core#129 治本侧）
 > 当前版本：`v0.46.0` · module：`github.com/oekit/pkg` · org：[oekit = Open Easy Kit](https://oekit.github.io)
 
 ## 本仓包含