技能介绍

你要解决的问题

混合语言仓库里，格式化这件事很容易变成一团乱麻。一个仓库同时包含 Python、Go、TypeScript 和 Rust 代码时，你通常得按语言分别跑 black、gofmt、prettier、rustfmt，再在脚本里把它们拼起来。这种做法有两个老问题：一是顺序不可控，某个格式化器改动过的文件又被另一个顺手重排，最终 diff 里混进大量与本次改动无关的噪声；二是范围不可控，脚本里的格式化命令往往无差别处理所有文件，而不是只碰真正发生变更的部分，于是一次小改动能带出整仓库的重写。

这个技能如何工作

这个技能的做法不是发明新工具，而是把 treefmt 作为仓库级的单一编排层：

一份计划，多种语言：在仓库根目录维护一个 treefmt 配置文件，把所有要参与的格式化器登记进去，由一个命令统一调度，而不是按语言临时拼脚本。
并行执行：treefmt 以流水线方式并行驱动各格式化器，文件在语言匹配后直接交给对应的格式化器处理，不必为每种语言串行等待。
只碰变更文件：只有自上一次运行以来发生变化的文件才会被送入格式化器，避免无关重排，让生成的编辑变得可预测。
单一入口：对 agent 或 CI 来说，只需要发起同一个命令，即可覆盖整个仓库的格式化策略，结果由配置文件决定，而不是由某次临时拼凑的命令行决定。

典型步骤是：安装 treefmt 本体和你计划使用的各种底层格式化器，在仓库中放好配置文件，然后在 shell 中调用该命令。前置条件就是这四样：treefmt、各语言格式化器、仓库级配置、shell 访问权限。

适用边界与注意点

配置要随仓库演进：格式化规则完全来自那份配置文件，新增语言或升级格式化器时需要同步更新，否则新语言的文件会被直接跳过。
底层格式化器必须自己装好：treefmt 是编排层，不会替你安装 black、rustfmt 这些工具，缺失的语言格式化器意味着对应文件得不到处理。
增量行为依赖运行历史：只处理变更文件的能力建立在上一次运行的状态之上，CI 的干净 checkout 与本地缓存场景下观察到的格式化范围可能不一致。
不替代语言自身的格式化约定：它保证的是执行层面的统一和可预测，具体风格仍由各格式化器及其参数决定。

参考文档见 treefmt 官方站点，上游说明来自 numtide/treefmt。