Tombi TOML 格式化与检查

要解决的问题

pyproject.toml、Cargo.toml 这类文件看起来简单，但一旦项目变大，问题会集中在几个地方：键名顺序漂移、缩进和引号风格不一致、表头层级写错、值类型不符合工具预期，或者某次合并把多余片段留在文件里。这些问题往往不会在编辑器里立刻暴露，而是在提交、CI 或依赖安装阶段才出现，排查成本比“提前看一眼”高得多。

这个技能关注的场景，是在 Agent 修改或生成 TOML 配置后、进入提交流程前，用 Tombi 做一次可重复的格式化与检查。它不是替代包管理器或构建系统，而是把“配置是否好看、是否自洽”这件事前移。

技能如何工作

核心能力依赖 Tombi 提供的三类入口：

• Formatter：对 TOML 文本做规范化处理，例如键排序、空白调整、表格层级整理，减少不同人或不同工具产生的风格差异。
• Linter：在解析结果上检查明显问题，例如非法 TOML、可疑键名、结构异常或不符合 Tombi 规则的内容，让错误在提交前被看见。
• Language Server：通过 LSP 把格式化和检查能力接入编辑器或 Agent 工作流，适合在修改文件时获得实时反馈。

典型使用路径可以概括为：

1. 定位本次变更涉及的 pyproject.toml、Cargo.toml 或其他 TOML 配置。
2. 对变更文件运行 Tombi 的格式化能力，让输出风格保持一致。
3. 对结果运行 lint / check，确认没有明显结构或语法问题。
4. 根据提示修复后重新检查，再进入提交或后续流程。

如果项目已经在使用 VS Code、JetBrains、Zed 或 Open VSX 相关集成，Tombi 的 LSP 能力也能让格式化与检查发生在编辑过程中，而不是等 Agent 生成完整文件后才开始。

适用边界与注意点

这个技能适合“配置文本治理”和“提交前验证”：它让 TOML 文件格式统一、基础问题更容易被发现。但它不能替代以下工作：

• 包版本、依赖来源和发布策略仍应由 pip、uv、cargo 等工具负责。
• Cargo 的依赖解析、编译语义和类型检查仍应以 Rust 工具链为准。
• 项目如果使用自定义 schema 或多个工具共享同一 TOML 文件，需要确认 Tombi 规则与项目约定一致。

另外，Tombi 的安装方式、版本兼容性和上游限制应以官方文档为准。对于大型仓库或历史文件，建议先在分支上对目标配置运行一次格式化和检查，确认 diff 符合预期，再合并到主分支。