JianFeeeee deeda22650 tools: 工具并发安全审计器（audit_parallel + annotate_parallel） ...

两个工具，都是为了让「这个工具能不能并发」有**可复现的依据**，而不是靠人眼扫。

## tools/audit_parallel.go —— 审计

为什么需要它：正则扫 `ToolDef` 字面量**不可靠**。用它审计主仓 27 个工具时，
把 `config_set` 判成"无共享写"，而它的 handler 其实在 `p.handleSet` 里且无锁 ——
原因：RegisterTool 第三个参数是方法名/闭包，正则看不到执行体。

本工具用 go/ast 从**注册点跟进到 handler 实现**，递归 3 层（带环检测），
输出三态：SAFE / SERIAL / UNKNOWN。
★ UNKNOWN 一律不声明并发安全 —— 追不到实现就不能声称安全。

### 开发它时踩的坑（都写在代码注释里）

- **通用 HTTP 包装器**：vanblog 的 manage_social / manage_settings 全走
  `p.do("GET"|"POST"|"PUT", ...)`，方法名毫无写操作迹象，纯靠名字匹配
  **全判成 SAFE** —— 而它们明确含 POST/PUT。审计工具给出与代码相反的结论，
  比不给结论更危险（人会信它）。改为按 HTTP 动词判定后，
  统计从 72/37 变为 46/63。
- **链式调用丢方法**：`p.sdk.Settings().Set(...)` 是三段链，只看最外层只得到
  "Settings"，`.Set` 整个丢失 ⇒ handleConfigure（写配置 + 启停服务）被判只读。
  改为收集整条链的所有方法名。
- **变量名 ≠ 类型名**：调用点写 `p.handleRead()`，定义处是
  `func (p *Plugin) handleRead()`。拿变量名去查类型索引**永远匹配不上**，
  143 个工具全报 UNKNOWN。须建"变量名 → 接收者类型"索引。
- **方法接收者不是局部变量**：example 里根本没有 `p := &Plugin{}`，
  p 是 Start 的接收者，局部变量索引全空。须把接收者变量名也纳入索引。
- **枚举被字符串污染**：verdict = "Serial:true" 而 report 只认三个枚举值
  ⇒ 全部落进 UNKNOWN，输出"共 13：UNKNOWN 13"，看着像工具没在工作。
- **作者声明必须优先**：我把"已声明"当 finding 记录后照常跑写入检测并
  **覆盖** verdict，于是 plugin_install（已标 Serial:true）被判 SAFE。

## tools/annotate_parallel/ —— 标注

按 SDK 风格插入声明项：Name 在首位，声明项在末尾（Parameters 之后、
handler 之前），不打散 gofmt 对齐。

插入点必须用**括号深度 + 记录进入深度 3 的行号**定位：
- `RegisterTool( =1, ToolDef{ =2, Parameters{ =3`
- 只判 depth==2 会在 `Name:` 行就返回（那行本来就是深度 2），
  插入点跑到 RegisterTool 之前，编译报 "expected 1 expression"
- 空 `properties: map[string]interface{}{}` 让深度**在同一行**进出平衡，
  所以"曾触及深度 3"也不能作门控，必须记行号
- 试过用正则找"最后一个顶层字段"，被嵌套 map 里的同形文本骗到，
  823 处错误重排把文件改坏 —— 文本匹配改结构体字面量就是这条路

用法：go build -o /tmp/annotate ./tools/annotate_parallel
     /tmp/annotate <file> <tool:parallel|serial:说明> ...

2026-09-27 16:17:04 +08:00

..

main.go

tools: 工具并发安全审计器（audit_parallel + annotate_parallel）

2026-09-27 16:17:04 +08:00