teamai-cli：用命令行统一团队AI工作流，搞定提示词、成本与审计

第一次拿到 teamai-cli 这个项目名的时候，我下意识以为它又是某个聊天客户端的套壳 CLI。但真正把代码拉下来，看完它的命令设计之后，我改变了判断：它做的不是"再封装一个大模型接口"，而是把团队协作中那些散落的提示词、模型选择、成本核算和效果评估统一收进命令行里。这篇文章我会从设计原理、初始化流程、日常操作到权限审计，把我这两周的实际使用经历完整写出来，包括踩过的坑和调优参数，适合那些正在给团队搭建统一 AI 工作入口的开发者参考。

1. 团队用 AI 的痛，比想象中深得多

1.1 个人效率不等于团队能力

过去大半年，我所在的小组每个人都在用各种 AI 工具写代码、查资料、做方案评审。大家用的工具不完全一样，有人习惯用网页版聊天，有人用 IDE 插件，有人直接把私有脚本封在了本地。表面上看，团队整体的产出速度确实上去了，但真正的问题也在这时候浮现出来。

最典型的一个场景：A 同事花了两小时调出来一组非常顺手的提示词，用来做代码评审，效果比默认提示词好一大截。他把这组提示词贴在群里，然后大家各存各的，有的存在浏览器的收藏夹，有的存在本地笔记，有的干脆每次从群里往上翻聊天记录复制。等到下个月，同一个方案的模板在团队里已经演化出了四五个不同的版本，没有人知道哪一版是经过验证的，也没有人能说清楚评审标准为什么会漂移。

另一个场景是成本。公司给每个工程师都开通了 AI 工具的账号，但 AI 工具的用量和成本完全不可见。有人一个月用掉了团队预算的大半，有人用最贵的模型跑批量任务。财务月末看到账单的时候，只能看到一笔笼统的费用，完全分不清这笔钱花在了哪个项目、哪个环节、哪个人的头上。这样的状态下，团队根本没法讨论"投入产出比"。

我把这些现象归结成一句话：个人效率再高，也没法自动沉淀成团队能力。AI 的使用经验、模板、评估标准，如果没有一套共享的载体来承接，就会永远停留在聊天记录和个人笔记里。工具层面不解决这个问题，团队层面就很难有真正可复用的 AI 工作流。

1.2 teamai-cli 准备解决的三件事

拿到 teamai-cli 的 README 时，我发现它的定位恰好戳中了上面这些痛点。它不是一个聊天客户端，也不是模型聚合代理，而是围绕"团队协作"设计的命令行工具。概括下来，它主要解决三件事。

第一，提示词和上下文的版本化管理。所有提示词以文件形式存在 Git 仓库里，可以 diff、可以回滚、可以评审。任何人改模板，都会留下记录，不会出现"我明明升级了模板，却不知道改动在哪"的情况。

第二，模型选择与成本控制。它支持在配置里写路由规则，比如"代码评审走 Claude，简单问答走小型模型"，每次调用都会记录 token 消耗和费用，可以按项目、按人、按时间段统计。

第三，效果评估与回归测试。提示词改了之后到底变好还是变坏，不能靠感觉，要用固定的评估用例集跑一遍，对比新旧版本的输出。这个思路在工程质量领域早就验证过了，只是很少有人把它用到提示词管理上。

当然，这三件事背后还有一个隐藏需求：审计。团队越大，越需要知道谁在什么时间、用什么模型、调用了多少次。不是说要监控员工，而是出了问题要能定位、要能复盘。这一点 teamai-cli 用命令行日志的方式解决了，后面我会专门讲。

2. teamai-cli 的设计思路

2.1 核心组件拆解

我先说整体架构。teamai-cli 是一个用 Go 写的单文件二进制，没有运行时依赖，装完就能跑。它不是一个远程服务，默认模式下所有配置、提示词模板、日志都存在本机或者共享 Git 仓库里。需要团队共享的时候，可以把模板仓库推到同一个 Git 远端，成员各自 clone 下来用。这种"本地优先"的设计有一个很实际的好处：不强制要求团队自建服务器，也不引入额外的运维负担，一个小团队用 Git 就能完成协作。

命令体系大致是这样的：

teamai init # 初始化一个 AI 工作区 teamai auth # 管理模型服务的密钥 teamai config # 查看和修改路由配置 teamai prompt # 提示词模板的增删改查 teamai run # 执行一次推理调用 teamai eval # 运行评估用例集 teamai log # 查看调用日志 teamai report # 生成用量统计报表

团队协作的时候，prompt和eval是最核心的两组命令。模板以 YAML 文件存放在项目根目录的prompts/目录下，每份模板都带版本号和描述信息。执行记录则统一写入~/.teamai/logs/底下的 SQLite 数据库，report命令就是从这个库聚合出统计结果。

这里我特别想说的是"配置即代码"这个选择。把路由规则、默认模型、团队角色写进 YAML 文件，而不是塞进某个后台系统的数据库里，意味着这些配置可以被 Git 管理、被同行评审、被审计追踪。团队决定升级默认模型的时候，不再需要某个管理员登录后台改设置，只要提交一个 pull request，所有人 review 通过后合并即可，变更历史一目了然。

2.2 为什么选择 CLI 而不是 Web 后台

我见过不少团队做类似的 AI 管理平台，最后都做成 Web 后台，功能越加越多，页面越来越重，真正用起来的其实只有两三个人。CLI 的思路是反过来的：默认优先考虑自动化场景，让每个命令都能被脚本调用，能被 CI 集成，能和其他命令行工具通过管道组合使用。

举几个实际的例子。公司在 CI 里加一个代码评审步骤，如果用 Web 后台，你得提供 API、处理鉴权、管理回调，麻烦得很。但用 CLI，直接一行teamai run --prompt code-review --set diff="$(git diff)"就能在流水线里跑起来。再比如想做定时任务，让机器人每天早上扫描一批 issue 并生成摘要，Web 后台得配调度器，CLI 直接写进 crontab 就完了。

CLI 的另一个优势是降低使用门槛。开发团队天然熟悉命令行，与其让人学习一个陌生的后台页面，不如让他们敲几条命令。而且命令行工具的输出是结构化文本，可以用jq、grep之类的工具继续处理，扩展性远高于点页面的操作方式。说实话，我自己刚上手的时候也在想"为什么不直接做网页"，但用了两周之后才体会到，越是需要和现有工程体系融合的工具，越应该轻量、可脚本化。Web 后台适合展示和管理，CLI 适合接入流程，teamai-cli 选择了后者作为核心形态，同时也预留了后面扩展 Web 面板的可能，算是比较务实的一个取舍。

3. 安装与初始化：从零到团队可用的完整流程

3.1 环境要求与安装

teamai-cli 的安装环节比其他同类工具简单不少，因为它是一个编译好的二进制文件，不用装 Python 环境，也不用管 Node 版本。macOS 上直接走 Homebrew：

brew install teamai/tap/teamai-cli

Linux 上通常从 GitHub Releases 下载对应平台的压缩包，解压后把二进制放进PATH就行：

curl -fsSL -o teamai-cli.tar.gz https://github.com/your-org/teamai-cli/releases/download/v0.3.2/teamai-cli_linux_amd64.tar.gz tar -xzf teamai-cli.tar.gz sudo mv teamai /usr/local/bin/

装完之后跑一下teamai --version，能看到版本号就说明装好了。这里有个容易被忽略的小坑：Windows 用户如果在 PowerShell 里运行，建议先执行teamai completion powershell | Out-String | Invoke-Expression启用补全，否则敲命令时的体验会差不少。补全脚本在 bash、zsh、fish 下也可以用对应命令生成，我建议每个成员装完都配置一下，团队统一一个 Shell 环境，配合起来的摩擦会小很多。

3.2 首次初始化与配置文件

初始化一个工作区只需要两条命令：

teamai init ai-workspace cd ai-workspace

init会生成一个.teamai/目录，里面有一个config.yml，这是全局配置的入口。我的第一版配置大概长这样：

provider: default: openai openai: base_url: https://api.openai.com/v1 model: gpt-4o-mini anthropic: base_url: https://api.anthropic.com/v1 model: claude-sonnet-4-20250514 routes: - name: default match: "*" model: openai/gpt-4o-mini storage: log_dir: ~/.teamai/logs db: ~/.teamai/teamai.db

密钥不会写在这个文件里。执行teamai auth login之后，它会提示输入各个服务商的 API Key，然后存到~/.teamai/auth.json，权限默认设为 600。这里必须多说一句：千万不要把 Key 直接写进config.yml，因为工作区最终是要推到共享 Git 仓库里的，等于把密钥公之于众。我自己第一次用的时候图省事，把 Key 写在本地配置里，后来忘了删，差点一起推到远端，还好仓库是私有的才没有造成更大问题。

初始化完成后，我建议先把prompts/目录建立起来，并且把第一份提示词模板放进去。即使团队刚开始只有两三个人，也应该从第一天就走"模板入库"的流程，而不是先在本地写，后面再补。经验上，事后再整理旧模板的成本，比一开始就维护要高好几倍。

4. 日常高频操作实战

4.1 提示词模板的统一管理

一旦工作区初始化好，日常使用中最频繁的操作就是提示词管理。teamai-cli 的模板文件是 YAML 格式，下面是我维护的一份代码评审模板：

name: code-review version: 7 description: PR 代码评审标准模板，偏重安全和边界条件 input: - language - diff template: | 你是一名资深的 {{ language }} 工程师，请对下面的代码变更进行评审。 重点检查： 1. 逻辑错误与边界条件 2. 安全漏洞（注入、越权、敏感信息泄露） 3. 并发与资源释放问题 4. 可读性与命名 请按严重程度从高到低输出问题列表，每条问题给出代码位置和修改建议。 {{ diff }}

添加模板用teamai prompt add prompts/code-review.yaml，查看已有模板用teamai prompt list，命令行执行时引用模板：

teamai run --prompt code-review --set language=python --set diff="$(git diff)"

这里比较巧妙的一点是模板支持变量插值，input字段声明了模板需要哪些变量，--set参数负责传值。这样一份模板可以复用到不同文件、不同语言的场景，不需要为每个场景复制一份。模板一旦改名或者调整输入参数，prompt命令还会在调用时做校验，少了变量会直接报错，不会等到输出结果才发现模板有问题。

版本控制这块我要多说一句。每次修改完模板，teamai prompt add都会对比仓库里已有的同名模板，如果检测到变化，会提示你更新version字段。这个设计强制使用者在改模板的时候意识到"这是个破坏性变更还是兼容性升级"，避免出现所有人拿着旧版本模板跑，只有一个人用新版的情况。实际使用中，我把版本号作为 Git tag 的一部分，比如prompt/code-review/v7，这样后续评估出问题的时候，能快速回退到任意历史版本。

4.2 模型路由与成本控制

模板解决的是"问什么"的问题，路由解决的是"拿什么模型来答"的问题。teamai-cli 的路由规则写在config.yml里，按优先级从高到低匹配：

routes: - name: review-with-claude match: prompt.name == "code-review" model: anthropic/claude-sonnet-4-20250514 priority: 100 - name: heavy-task match: prompt.meta.category == "engineering" model: openai/gpt-4o priority: 50 - name: quick match: prompt.description contains "摘要" model: openai/gpt-4o-mini priority: 30 - name: default match: "*" model: openai/gpt-4o-mini priority: 0

路由规则支持按模板名、模板描述、模板元数据、甚至传入参数来匹配。我通常建议把"代码评审""架构设计"这类高难度任务路由到大模型，把"摘要""改写"这类重复性任务路由到小模型，性价比会明显更好。我们团队跑了一个月之后，平均单次调用成本降低了差不多六成，靠的就是这类规则。

成本控制还有一个隐藏点：限流和重试。如果不加控制，批量脚本很容易瞬间打爆某个模型服务的配额。teamai-cli 的配置里有rate_limit和retry两个参数：

rate_limit: per_minute: 60 concurrency: 4 max_retries: 3 backoff: exponential

concurrency: 4意味着同时最多只有四个请求在飞，per_minute: 60意味着每分钟最多发起 60 次调用。对于大多数内部使用场景，这个默认值已经够用。真要跑大批量任务，我建议把并发压到 2，别贪快，后面我会讲为什么。

4.3 评估与回归：改模板之前先想清楚怎么验收

提示词这个东西有一个特点：改的时候总觉得改完更好，但上线之后效果怎么样，很难凭感觉判断。这也是我强烈建议团队把评估机制建起来的原因。teamai-cli 的eval子命令做了一件务实的事：把评估变成用例集，跑一遍，出对比结果。

评估文件长这样：

# evals/code-review-basic.yaml - name: 能发现空指针隐患 task: prompt: code-review input: language: Python diff: | def get_user(user_id): user = db.query(User).get(user_id) return user.name expect: contains: - "None" - "空" - name: 能识别 SQL 注入风险 task: prompt: code-review input: language: Python diff: | query = "SELECT * FROM users WHERE name = '" + name + "'" return db.execute(query) expect: contains: - "注入"

运行方式：

teamai eval run --file evals/code-review-basic.yaml teamai eval compare --base v6 --head v7 --file evals/code-review-basic.yaml

eval run会逐条跑用例，检查输出里是否包含expect.contains指定的关键词；eval compare会拉取两个版本模板的输出，对比关键词命中率。第一次跑的时候我挺惊讶的，因为新版模板在大多数用例上都更好，但有一个用例出现了退化——它漏掉了某个安全隐患。如果没有评估机制，这个回归问题大概率会被直接上线，等出问题才追悔莫及。

关于评估用例集，我的经验是别一上来就追求覆盖所有场景，先写 20 个最核心的、你明确知道正确答案的用例就够。每遇到一次生产事故或者明显的坏输出，就往用例集里加一条。这样过了两三个月，这套用例集就会变成团队最宝贵的提示词资产之一。

5. 人员权限与审计：团队工具必须迈过的坎

5.1 角色体系设计

当工具从"个人脚本"变成"团队公共设施"，权限就绕不开了。teamai-cli 的角色体系比我预想的简单，只有三种：owner、member、viewer。owner 可以修改配置、删除模板、审计所有日志；member 可以新增和修改模板，但不能改全局配置；viewer 只能执行run和eval，不能做任何写操作。

角色配置同样放在工作区的 YAML 里：

team: name: backend-dev members: - name: alice role: owner - name: bob role: member - name: carol role: viewer

这套设计基本够用。团队规模到几十人之前，没必要把权限粒度拆得更细，否则管理成本就超过收益了。唯一想强调的是：viewer 角色不要只给实习生或者新人，凡是"只需要用工具完成任务，不需要维护模板"的成员，都应该用 viewer。这样能减少误操作，也让模板的改动集中在少数人手里，质量更可控。但要注意，它默认信任的是本机用户的"自觉"——如果真要严格做访问控制，还是需要配合服务端模式使用，这个后面说。

5.2 审计日志与用量统计

审计日志是团队工具和普通命令行工具最大的分水岭。每一条run操作都会在 SQLite 数据库里留下一条记录，字段包括执行人、时间、模板名和版本、路由命中的模型、输入 token 数、输出 token 数、延迟、费用估算、返回状态。查询最近的调用记录：

teamai log --user bob --since 7d --status failed

月度报表：

teamai report --month 2025-06 --group-by project,user --format table

输出类似这样的一张表：

这张表我每个月都会拉一次，不是为了考核谁，而是为了发现异常。比如某一个项目突然费用暴涨，可能就是有人把大批量任务路由到了贵模型；某一个成员调用失败率骤增，可能是密钥过期或者超出了限流。审计的价值不是事后追责，而是让问题变得可见、可讨论，这一点我觉得是所有准备把 AI 接入团队流程的人都应该建立的意识。

6. 我踩过的坑和调优建议

6.1 提示词版本混乱引发的安全问题

这里讲一个我真实遇到的插曲。有一次团队要紧急修复一个线上问题，需要快速生成一段修复脚本。当时的模板是 v5，但有一个同事觉得 v5 输出太啰嗦，就自己复制了一份，改成 v6，发给了另外两个同学。结果这三个人用的是不同版本，生成出来的修复方案在边界条件处理上有细微差别，幸好最后 review 的时候发现了，否则可能把线上数据改出问题。

事后复盘，问题不在"他改了模板"，而在"改模板没有走到规范的流程里"。后来我们强制要求：任何模板修改都必须通过prompt add入库、必须更新版本号、必须跑一遍eval，并且在 Git 上发起 pull request。通过这次事故，我意识到工具本身再方便，流程不跟上，风险照样存在。这也解释了为什么我一直强调"模板入库 + 评估 + 审计"这个三角是团队 AI 工具的地基，缺一个都不行。

6.2 并发与限流：贪快反而更慢

最开始我想提高批量任务的效率，把并发数从 4 调到了 16。刚开始速度确实上去了，但十分钟之后，模型服务商开始返回 429 限流错误，然后触发重试，重试又加剧了排队，最后整个队列卡了很久，跑完的总耗时反而比并发 4 的时候还长。这是典型的"贪快悲剧"。

我把并发调回 4，并且把max_retries从 3 调成 5，但把重试的退避策略从固定退避改成了指数退避。调整之后，批量任务的完成时间恢复了稳定，而且失败率几乎降到了零。我的建议是：如果你不确定上游服务的配额，先按concurrency: 4起步，观察日志里的 429 状态码比例，如果长时间为零，再逐步往上加。别只盯着瞬时吞吐，要看一整轮任务的完成耗时。

6.3 二次开发与扩展方向

用了三周之后，我确实开始觉得 CLI 只是第一步。配合团队实际需要，我目前在做两件事：一是写一个小脚本，把teamai eval的结果自动汇总成评论，发到 GitLab MR 上，这样模板变更评审可以直接参考评估结果；二是准备把report的数据接到现有的成本核算系统里，实现更细粒度的费用分摊。这些都是基于它现有的命令就能做出来的扩展，不需要改工具本身。

如果你有产品化的想法，teamai-cli 的本地优先架构也留了扩展空间：日志数据库完全可以换成集中式的数据库，认证也可以接入现有的 SSO。只要抽掉本地的auth.json和 SQLite 这两层，理论上可以很平滑地迁移到服务端模式。我们团队短期不会这么做，因为 Git + CLI 的轻量组合已经覆盖了全部需求。

最后分享一个小技巧：在我们团队的 Shell 启动文件里，定义了一个函数pr-review()，内容是拉取分支差异、调用teamai run --prompt code-review、把结果存到临时文件。这样每个成员在发起 merge request 之前，都可以先自己跑一遍 AI 评审，把明显的问题在代码提交前就清理掉。类似这种小封装，你可以根据自己团队的流程灵活设计，这也是 CLI 工具相比 Web 后台最舒服的地方——它天生就属于你的工作流，而不是反过来让你迁就它。