团队里几个人共用同一份 teamai-cli 配置——改动会互相覆盖吗？

会，但只在“共享层被多人直接编辑”的情况下才会。teamai-cli 这类命令行工具通常有多级配置：仓库里跟着 git 走的那份是共享层，用户目录和项目目录里的本地覆盖文件是各自一份。两个人先后改写同一份共享文件，对同一字段的修改会是后写覆盖先写；而改动落在本地覆盖层时，别人本地不会自动读到，也就不会互相影响。所以正确的顺序是先确认当前生效的是哪一份，再决定哪些字段该留在共享层。

能不能互相覆盖，取决于改动落在共享层还是本地覆盖层。共享层里同一字段被先后修改，会是后写覆盖先写，且往往没有冲突提示；本地覆盖层只影响本机，不会影响别人。处理方向：先用命令打印生效配置路径确认优先级，再把密钥、默认模型、本机路径这类因人而异的字段挪到本地覆盖文件，共享层只保留团队一致的默认值。边界：具体子命令名、配置文件名以本机 teamai-cli 版本的 `--help` 输出为准，下面的示例需要替换成你们实际的名字，不要照抄。

先确认当前生效的是哪一份配置文件

在讨论“会不会互相覆盖”之前，必须先知道进程实际读的是哪个文件。很多“找不到是谁改的哪一行”，本质是有人改的文件根本没被加载，或者被另一份更高优先级的文件盖掉了。先跑这几条（子命令名以 teamai-cli `--help` 为准，不同版本可能叫 config path、config which、config get-path）：

# 看当前版本支持哪些配置相关子命令
teamai-cli `--help`

# 打印本次实际生效的配置文件路径与合并结果
teamai-cli config path
teamai-cli config show `--resolved`

# 查单个字段最终取的是哪一层的值，便于定位被谁覆盖
teamai-cli config which model

# 环境变量也可能参与覆盖，一起看
env | grep -i teamai

候选路径与常见的优先级顺序，通常从高到低是这样，前一层覆盖后一层：

命令行参数（`--model` 这类一次性开关）
环境变量，例如 TEAMAI_API_KEY、TEAMAI_CONFIG
项目本地覆盖文件，如 .teamai/config.local.yaml（应当被 gitignore）
项目共享配置，如 .teamai/config.yaml（提交进仓库，多人共用）
用户级配置，如 ~/.config/teamai/config.yaml
系统级配置与本程序内置默认值

把 config show `--resolved` 的输出和 config which <字段> 的结果对照看，就能区分两种情况：字段值来自第 4 层，说明是共享文件被改了；来自第 2、3 层，说明是本机自己的覆盖在起作用，与别人无关。这一步做完再谈改动流程，否则容易在错误的文件上反复改。

把最容易冲突的字段挪出共享文件

降低冲突最直接的办法，是让共享层只剩“全团队应当一致”的少量字段，其余下沉到本地覆盖文件。落在共享层又因人而异的字段，通常包括：

密钥类：api_key、token、各类鉴权凭据；这类内容本就不该进仓库，共享文件里只保留占位或环境变量引用
默认模型与采样参数：model、temperature、max_tokens；个人调试时经常临时换，放共享层会天天撞车
接入地址：base_url、endpoint、网关域名；测试环境和正式环境往往不同
本机相关路径：缓存目录、日志目录、临时工作区
受本机资源限制的参数：并发数、超时、重试次数

共享层保留团队约定项，例如统一的默认模型别名、禁用的能力开关、组织级网关前缀。本地覆盖文件按同样的格式写，只写自己要改的字段，不要整份复制：

# .teamai/config.yaml —— 提交进仓库，多人共用，改动需要走流程
model: team-default
timeout_seconds: 60
# 不要在这里写密钥

# .teamai/config.local.yaml —— 每人一份，加入 .gitignore，不进仓库
model: my-test-model
base_url: https://gateway-test.example.com
api_key: ${TEAMAI_API_KEY}
log_dir: ~/.cache/teamai/logs

需要注意：并非所有版本都支持同目录的 config.local.yaml 自动合并。先用 teamai-cli config path 确认本地文件是否出现在加载列表里；如果版本不支持，可以改为完全依赖环境变量或启动参数，效果相近。

给共享配置的改动定一个最小流程

共享层既然是多人的，改动就需要可追溯、可回滚。一个够用的最小流程是三步：改前同步、改后验证、提交说明写清字段。

改前同步：先拉最新，避免在旧版本上改出覆盖别人的结果。
改后验证：跑校验命令，再看合并结果，确认没有意外字段被带出去。
提交说明：写清改了哪个字段、原值、新值、哪些人需要同步本地、用什么命令验证。

git pull `--rebase`

# 改完共享文件后先校验语法与必填项
teamai-cli config validate

# 再确认最终生效值与来源层级
teamai-cli config show `--resolved`
teamai-cli config which model

git diff .teamai/config.yaml
git add .teamai/config.yaml
git commit -m "config: model 由 team-default 改为 team-v2；影响：本地有 model 覆盖的成员不受影响；验证：config validate 通过"

提交说明里的“影响范围”一行最有用：明确列出哪些字段变了，成员据此判断自己本地是否需要调整覆盖文件。团队人数不多时，改完在群里贴一次 diff 和验证输出，通常比事后排查更省事。

本地改坏了怎么回到可用状态

本地覆盖文件写错格式、密钥填错、或者共享文件被人改成了不兼容的值，都要有一条不依赖他人的自救路径。核心是先备份，再还原，最后验证。

# 备份当前共享配置与本地覆盖文件
cp .teamai/config.yaml .teamai/config.yaml.bak.$(date +%s)
cp .teamai/config.local.yaml .teamai/config.local.yaml.bak.$(date +%s)

# 共享文件被改坏：丢弃本地未提交改动，回到仓库版本
git restore .teamai/config.yaml
# 或旧版本 git
git checkout -- .teamai/config.yaml

# 本地覆盖文件改坏：先移走，让程序回落到共享层
mv .teamai/config.local.yaml .teamai/config.local.yaml.broken

如果连共享层也不想用，可以用默认配置或最小配置启动一次，判断问题是否出在配置上。常见做法是临时屏蔽配置文件路径，具体参数名需按 help 确认：

# 临时清掉配置覆盖，用内置默认值启动
TEAMAI_CONFIG= teamai-cli config show `--resolved`

# 部分版本提供重置本地层的能力
teamai-cli config reset `--local`

teamai-cli config validate
teamai-cli config path

恢复是否成功，要看三件事：config validate 没有报错、config path 指回了预期的文件、生效值与预期一致。如果程序有连通性检查子命令（例如 ping 或 models list 之类），再跑一条最小调用确认可用，比只看配置文件更可靠。

把共用配置的边界写成团队约定

约定不需要长篇文档，一页纸写清边界就能减少大量重复沟通。建议至少覆盖下面几条，每一条都对应一个具体动作，而不是原则口号。

谁有权改共享层：指定一到两名配置 owner，其他人通过合并请求或找 owner 代改；共享层改动不直接推送
哪些字段只允许出现在本地覆盖层：密钥、默认模型、接入地址、本机路径、受本机资源限制的参数
密钥如何分发：不进仓库、不贴群聊，通过环境变量或团队既有的密钥管理方式注入；共享文件里只写变量名占位
多久轮换一次：按团队安全要求定一个周期（例如按季度，或人员变动时立即轮换），轮换后由 owner 通知并给出替换命令
冲突怎么处理：共享层出现同一字段的连续修改时，以提交说明中写清依据的那次为准，回滚用 git restore 或 revert，不用手抄旧值
验证基线：每次改共享层后贴出 config validate 与 config show `--resolved` 的输出片段，作为这轮改动的证据

这份约定和仓库里的共享配置文件放在一起，改配置的人顺手能看到。它不能让冲突消失，但能让冲突发生时，大家知道该看哪个文件、该找谁、该用什么命令回退。