libcst重构必须用csttransformer而非visitor，因visitor只读；需重写leave_*方法返回新节点，注意导入改写、参数插入、变量重命名等细节及性能优化。
libcst 重构必须用 CSTtransformer，不是 Visitor
因为 Visitor 只读不改，想替换节点、增删语句，必须继承 CSTTransformer 并重写对应 leave_* 方法。常见错误是误用 visit_* 返回新节点——它会被忽略，代码毫无变化。
实操建议：
立即学习“Python免费学习笔记（深入）”；
-
leave_*方法接收旧节点和更新后的子节点，必须显式返回新节点（哪怕只是原样返回） - 修改函数体时，别直接改
node.body列表；要用cst.ensure_type(...)配合cst.IndentedBlock构造新 body - 如果目标是重命名变量，得同时处理
leave_Name和leave_AssignTarget，否则漏掉赋值左侧
替换函数调用要小心参数顺序和逗号尾随（trailing comma）
比如把 json.loads(s) 改成 json.loads(s, strict=False)，看似简单，但 libcst 对逗号敏感：原调用若带尾随逗号（json.loads(s,)），直接插入新参数会导致语法错误。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 用
node.args获取参数列表，别硬拼字符串 - 新增参数前，先检查最后一个
Arg是否有comma；有则复用，没有就新建一个带comma的Arg - 用
cst.Arg构造新参数时，comma字段必须显式设为cst.Comma()或None，不能留空
模块级导入重构容易破坏相对导入路径
把 from .utils import helper 改成 from mypkg.utils import helper 看似直白，但 libcst 不自动修正同文件内后续的 helper() 调用——它仍指向原相对导入绑定，运行时可能报 NameError。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 改导入语句后，必须同步扫描整个模块的
Name节点，判断是否属于该导入的 alias（需比对node.value和导入目标） - 相对导入（
relative属性 > 0）转绝对导入时，得结合当前文件路径计算真实包名，libcst 本身不提供此信息，得外部传入 - 别依赖
cst.Module.body索引找导入位置；用cst.findall定位更稳，尤其当有多个ImportFrom混在一起时
性能瓶颈常在 cst.parse_module 和多次遍历
对大文件（>5k 行）反复调用 cst.parse_module + module.visit + module.deep_replace，会明显变慢。libcst 的 AST 是不可变结构，每次修改都生成全新树，没缓存机制。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 一次性 parse，然后链式调用多个
transform，避免中间deep_replace - 不要为每个小修改单独跑一遍 transform；把所有规则合并进一个
CSTTransformer子类里处理 - 调试时加
sys.setrecursionlimit(10000)，否则深层嵌套函数容易RecursionError
事情说清了就结束。真正难的不是写 transformer，是判断哪些节点该动、哪些上下文要连带更新——比如装饰器、类型注解、字符串格式化里的表达式，libcst 全部当成普通 CST 节点，但语义上它们根本不会执行。