TabNine 项目级配置指南：利用 `.tabnine` 文件管理团队学习与隐私数据

• 开发工具
• AI 应用

TabNine 是一款支持全语言、以深度学习驱动的代码自动补全工具，其团队版提供了"团队学习（Team Learning）"能力，让团队可以基于共享代码持续训练、改进补全模型。本指南基于仓库中的 TabNineProjectConfigurations.md 文档，系统讲解项目级配置文件.tabnine的结构、字段语义、完整配置示例以及如何在 VCS 项目中正确使用它，帮助你在享受团队学习带来的补全质量提升的同时，精确控制哪些文件参与训练、哪些文件必须被排除。

什么是项目级配置：.tabnine文件

在 TabNine 中，"项目（Project）" 的定义非常明确：一个包含 VCS 根目录（如.git目录）的文件夹，或包含.tabnine_root标记的目录，都属于一个项目。也就是说，TabNine 以版本库为边界来划分代码单元，这决定了它的索引与数据收集范围。

在此基础上，在项目根目录放置一个名为.tabnine的文件，即可对该项目施加特殊配置。该文件不会被 TabNine 当作代码索引进补全模型，而是作为项目级开关，主要用于团队学习（Team Learning）相关的数据收集控制。

项目的典型目录结构如下：

project-root/ ├── .git └── .tabnine <<<<< this configuration file └── ...

project-root/下必须有.git（或其他 VCS 根、.tabnine_root）作为项目边界标记，.tabnine与.git同级放置于根目录。TabNine 各编辑器客户端（VS Code、Vim、Sublime Text、Atom 等）会自动读取该文件，无需任何额外安装步骤。

.tabnine文件格式与字段

.tabnine文件使用JSON格式，当前支持两个顶层字段：

两个字段的语义要点如下：

• disableTeamLearning：仅对团队成员有意义。团队学习是 TabNine 团队版的功能：在获得团队授权后，TabNine 会收集团队成员代码用于训练、持续改进补全模型。如果某项目包含敏感代码、客户专有逻辑或你不希望进入团队训练集的内容，可将其设为true以整体关闭该项目的数据收集。
• teamLearningIgnore：一种细粒度排除机制。通过路径掩码精确指定哪些文件/目录不参与团队学习，同时保持项目内其余文件的团队学习开启。掩码格式与.gitignore完全一致，这意味着你已有的.gitignore经验（如*、src/tests、相对路径等）可直接复用。

两个字段是互补关系：一个是从项目整体层面"一刀切"关闭训练，另一个是从文件层面精确排除，二者可单独使用也可组合使用。

完整配置示例

示例一：忽略敏感文件，保留其余训练

忽略我的 secrets 和 passwords 文件中的所有内容

{ "disableTeamLearning": false, "teamLearningIgnore" : ["myFile.txt", "someOtherFile.abc"] }

这里显式声明disableTeamLearning: false（即保持团队学习开启），同时用teamLearningIgnore精确排除myFile.txt与someOtherFile.abc。适用于：项目整体可以参与团队学习，但个别文件包含密钥、口令等敏感内容的情况。

示例二：忽略整个测试目录

忽略 tests 文件夹下的所有内容

{ "teamLearningIgnore" : ["src/tests", "build/tests"] }

注意，这里disableTeamLearning字段被省略，因此隐式为false，即团队学习保持开启。teamLearningIgnore采用与.gitignore相同的目录路径写法（src/tests、build/tests），可精确指向项目内任意层级的目录，是"排除测试代码，保留业务代码训练"的典型配置。

示例三：不收集该项目的任何数据

don't collect data for this project

{ "disableTeamLearning" : true }

当项目包含客户专有代码、未公开的商业逻辑或处于保密 NDA 范围内时，仅设置一个字段即可整体关闭该项目的数据收集，是最简单直接的"隐私开关"。

示例四：等效的全局排除写法

equivalent to a catch all mask

{ "disableTeamLearning" : false, "teamLearningIgnore" : ["*"] }

teamLearningIgnore: ["*"]是.gitignore中的通配符写法，表示忽略全部路径。从效果上看，它与示例三（disableTeamLearning: true）等效，但语义不同：前者是"团队学习开着，但用通配掩码排除一切文件"，后者是"直接关闭团队学习"。这组对照示例清晰地展示了两种达成同一目标、但表达方式不同的配置思路。

配置语义与背后的团队学习机制

结合 CHANGELOG.md 中的版本记录，可以更好地理解这两个字段所处的功能背景：

• v3.8.2（2021-10-28）引入了 "Team Data Collection V2.0"，说明团队数据收集是 TabNine 持续演进的核心能力之一（见 CHANGELOG.md 附近版本段）；
• 随后的版本中持续修复团队数据收集的小 bug（v3.8.9，见 CHANGELOG.md）、调整团队相关 UI（v3.7.21 "hide teamai toggle for free teams"，见 CHANGELOG.md），说明团队学习/数据收集是团队版用户界面的重要组成部分；
• v4.0.13 曾移除全局配置中的team_ai_local_collection选项（见 CHANGELOG.md），结合本指南可以发现，团队数据收集的控制从全局配置迁移到了以项目为粒度的.tabnine文件——这正是项目级配置存在的意义：把数据收集的决策权下放到每个仓库，由仓库所有者按项目实际情况决定。

从源码结构看（本仓库为 TabNine 后端仓库，后端本体闭源，仓库内仅含配置与文档，见 README.md），TabNine 各编辑器客户端在启动时会探测当前工作目录是否为 VCS 项目根，并在根目录查找.tabnine文件、解析其中的 JSON 字段，随后将解析结果应用于团队学习数据收集流程。仓库中的 HowToWriteAClient.md 描述了客户端通过标准输入输出与 TabNine 二进制通信的机制，.tabnine文件正是这类客户端行为约定的项目级配置入口。

最佳实践与常见问题

1. 什么时候用disableTeamLearning，什么时候用teamLearningIgnore？

• 项目整体不应参与团队训练（如保密项目、外部客户仓库）→ 用disableTeamLearning: true，一个字段解决问题；
• 项目可参与训练，但需排除特定敏感文件或目录（密钥文件、测试代码、构建产物）→ 用teamLearningIgnore，并且可省略disableTeamLearning（隐式false）保持训练开启。

2. 掩码语法参照.gitignore

teamLearningIgnore的每个条目都与.gitignore条目格式一致，你可以沿用已有的.gitignore心智模型：*匹配一切、src/tests匹配相对路径目录、myFile.txt匹配具体文件名。因此团队既有的.gitignore规则可以很方便地映射为团队学习的排除规则。

3. 敏感文件的双重保险

最稳妥的做法是同时利用 VCS 自身的保护机制与.tabnine：将含密钥/口令的文件加入.gitignore（不进版本库），同时在.tabnine的teamLearningIgnore中列出这些文件（不参与团队学习）。两者互不替代，但叠加使用可以最大程度降低敏感数据外泄风险。

4. 配置变更即时生效

.tabnine是项目内的普通文本文件，编辑后保存即可；无需重新安装客户端或重启编辑器（部分客户端可能需要重新打开文件以重新触发项目配置解析，具体以你所使用的客户端行为为准）。

5. 保持文件合法 JSON

.tabnine必须满足 JSON 语法：使用双引号包裹键名与字符串、逗号分隔字段、最后一个字段后不带尾随逗号。示例中的写法（如"teamLearningIgnore" : ["src/tests", "build/tests"]）均可直接复制使用。

小结

.tabnine是 TabNine 团队学习体系中的项目级控制面，通过两个 JSON 字段即可完成从"整体关闭训练"到"细粒度排除文件"的全部隐私管理需求：

• disableTeamLearning控制项目整体是否参与团队训练（默认false）；
• teamLearningIgnore以.gitignore兼容语法精确排除参与训练的文件（默认[]）。

将.tabnine放入 VCS 项目根目录（与.git同级），即可让团队在共享代码训练、持续提升补全质量的同时，守住敏感数据的边界。对于团队管理员与项目维护者，这是一份可直接落地的项目级配置规范。

• 开发工具
• AI 应用