企业官网建设流程全解析

去年下半年团队从 4 个人扩张到 14 个人之后，我发现了一个特别扎眼的现象：代码评审的意见质量方差变得非常大。同一份 PR，有人让 AI 从性能角度挑毛病，有人让 AI 从安全角度找问题，还有人直接把整段代码丢给 AI 问“你觉得这里有没有问题”。几轮迭代下来，最明显的变化不是代码质量提升了，而是评审意见的风格在每个人的浏览器标签页里分裂成了好几个流派：有人偏好长篇大论的分析报告，有人只想要三五行结论，还有人完全靠“感觉”判断 AI 回答靠不靠谱。

真正让我下定决心做点什么的事情发生在一次线上事故复盘会上。那次问题的根因在代码评审阶段其实已经暴露过，但当时负责评审的同事用的是自己的 AI 对话，提示词里没有要求 AI 重点排查“异常分支是否被正确关闭”，结果 AI 给出了一段正确但完全没用的泛泛而谈。会开完之后我在工位上想了很久，意识到团队缺的不是一个“更好用的 AI 聊天网页”，而是一个能把团队里关于 AI 协作的约定固化下来、让每个人都在同一条轨道上使用 AI 的工具。

我把目光投向了命令行，花了大概两周时间做出 teamai-cli 的初版，又断断续续打磨了一个月才敢在团队里铺开。这篇文章把整体设计思路、核心实现和落地过程中踩过的坑都整理出来，给同样在团队里做 AI 工具链的同学一个参考。如果你也在纠结“要不要自己搞一个内部 AI 工具”，或者已经在搞但不知道怎么设计命令体系和知识沉淀机制，这篇文章应该能帮你省掉一些试错成本。

1. 为什么我需要一条“团队AI命令行”而不只是“更好的聊天窗口”

1.1 网页版 AI 工具解决不了的三个问题

先说结论：网页版 AI 工具在个人生产力场景下已经很能打了，但一旦放到团队协作场景里，它有三个结构性的缺陷。

第一个问题是“约定无法沉淀”。团队里最有经验的几个同事，他们写提示词的思路、对 AI 输出质量的判断标准、甚至语气偏好，全都存在私人对话窗口里。这个人升职或者离职，等于把团队一部分隐性效率带走了。我在做 teamai-cli 之前做过一次统计，团队里 14 个人，日常用 AI 写的提示词大概有 20 多类场景，但其中将近一半的提示词是有人写过之后通过聊天记录转发给别人的，从来没有进入过任何团队共享的仓库。这太浪费了。

第二个问题是“上下文不共享”。每个人打开一个新的 AI 对话窗口，都要从头描述一遍项目背景、技术栈、代码结构、团队规范。对于新入职的同事尤其不友好——他得先花两周时间搞清楚“我们这个项目为什么这么写”，才有能力给 AI 提供高质量的上下文。但这些信息不是不存在，而是散落在文档、代码注释、群聊精华和老人脑子里，AI 工具完全接不上。

第三个问题是“成本与审计缺席”。月底拿到 API 账单的时候，只看到一笔总额，根本说不清楚是谁、在哪些任务上、花了多少钱。管理层如果问起来“我们上个月花在 AI 上的钱产出是什么”，我只能哑口无言。这不是钱多少的问题，是没有数据支撑决策的问题。

1.2 命令行工具的优势和适用边界

那为什么是命令行而不是做一个内部网页应用？我的判断依据很简单：团队里需要 AI 辅助的任务，绝大多数是“固定流程 + 可变参数”的结构化场景，比如评审一段代码、生成一周汇报、根据数据库表结构写 CRUD 接口、把一段错误日志转成排查报告。这类场景天然适合命令行：命令是确定的，参数是变化的，结果输出到终端或者文件里，可以被脚本消费，也可以被 CI 系统调用。

网页版内部工具当然也能做，但成本高出一个量级。要做 UI、要管登录会话、要维护一个前端项目、要处理浏览器兼容性。命令行工具则可以直接跑在每个人的开发机上，也可以跑在 CI 的 runner 里，一个二进制文件分发出去就行。我画了一张对比表给自己做决策参考：

最后一项“使用门槛”确实是我当时最担心的。后来实际落地发现，在技术团队里这个门槛比想象中低很多，因为大家每天都在用终端跑 git、npm、yarn，多一条 teamai 命令并不会有额外的学习成本。反倒是交互式 UI 一旦做得太复杂，才是真正劝退用户的东西。所以我在设计 teamai-cli 的时候给自己定了一条原则：默认交互要简单到“一次回车就能看到结果”，把复杂选项藏到 help 里，而不是摆到用户面前。

2. 命令树与配置中心：把团队的 AI“潜规则”写进配置文件

2.1 命令设计：主命令统一，子命令按场景划分

CLI 工具最容易犯的错误是命令设计得又散又乱。团队工具尤其怕这个，因为工具是给一群人用的，不是只给自己用的。我的设计思路是“一棵命令树，按场景走到底”：

teamai init # 初始化工作区，生成配置文件骨架 teamai auth login # 配置 API 凭证（推荐环境变量方式） teamai auth status # 查看当前凭证状态和生效的模型服务 teamai pkg list # 查看当前团队已安装的模板包列表 teamai pkg search # 在模板仓库中搜索可用模板 teamai pkg update # 拉取团队模板仓库最新内容 teamai run <template> [options] # 基于某个模板执行一次 AI 任务 teamai chat # 进入交互式对话模式（带团队上下文） teamai review [path] # 对指定目录/提交执行代码评审 teamai stats # 查看用量、成本、高频任务统计 teamai doctor # 环境自检：配置、密钥、网络连通性、模板版本

每个命令的设计都对应一个明确的团队使用场景。最开始有人建议我把run和review合并成一个命令，加一个--mode参数切换，我没有采纳。原因很简单：一个命令只干一件事，用户才能形成肌肉记忆。review就是评审、run就是执行任意模板任务，分开之后每个命令的 help 文档都短了一半，心智负担小很多。

doctor是我们后来加的，但它是全工具里使用率最高的命令之一。新成员入职配置环境的时候，经常会遇到密钥没设对、模板仓库权限没开通、Node 版本太低之类的问题。与其让他们反复猜，不如跑一条teamai doctor自动检查所有前置条件，直接告诉缺什么、怎么补。这一点强烈建议所有团队内部 CLI 工具都做，排查配置问题的成本能降一个量级。

2.2 配置层级与密钥安全

配置系统我设计成三层合并，优先级从低到高：

1. 全局配置：~/.teamai/config.json，存个人偏好，比如默认模型、输出语言、个人 API Key 的环境变量名。
2. 团队配置：项目仓库根目录下的teamai.config.json，跟随 git 提交，统一管理团队模板仓库地址、默认 Provider、成本预算、禁用命令列表。
3. 本地覆盖：项目目录下的.teamai/local.json，不进 git，存个人临时覆盖项或者本机特有的设置。

说一个实际例子，这就是一份简化后的teamai.config.json：

{ "$schema": "./schemas/teamai.config.schema.json", "provider": { "default": "qwen-plus", "providers": { "qwen-plus": { "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1", "model": "qwen-plus", "apiKeyEnv": "TEAMAI_QWEN_API_KEY" }, "glm-4": { "baseUrl": "https://open.bigmodel.cn/api/paas/v4", "model": "glm-4-air", "apiKeyEnv": "TEAMAI_GLM_API_KEY" }, "local-ollama": { "baseUrl": "http://localhost:11434/v1", "model": "qwen2.5-coder:7b", "apiKeyEnv": "TEAMAI_LOCAL_FAKE_KEY" } } }, "templateRepo": { "url": "git@github.com:your-org/teamai-templates.git", "branch": "main" }, "billing": { "currency": "CNY", "budgetPerUserPerDay": 15 } }

注意一个细节：配置文件里不直接写 API Key，而是写“环境变量名”。工具运行时从process.env里读实际值，找不到就给出提示并建议用teamai auth login写入系统凭据管理器。之所以不把密钥写进配置文件，是因为teamai.config.json是要提交到 git 里共享的，密钥一旦进去，即使后来删掉，也仍然活在 git 历史里，这是安全事故隐患。

teamai auth login命令的实现逻辑并不复杂：交互式询问用户要配哪个 Provider，然后让用户粘贴 API Key。粘贴时终端不回显，拿到后优先写入操作系统凭据管理器（macOS 钥匙串、Windows 凭据管理器、Linux libsecret），同时生成一条带注释的.env.example给用户参考。如果系统凭据管理器不可用（比如有些精简版 Linux 服务器），再降级到~/.teamai/credentials文件，权限位设为0600，只有当前用户可读写。

3. 模板包与 Git 同步：把提示词当成“代码”来管理

3.1 一个模板包里到底装了什么

teamai-cli 的核心概念是“模板包”（template package）。一个模板包对应一类具体的 AI 任务，目录结构长这样：

teamai-templates/ └── code-review/ ├── manifest.json # 元信息：版本、作者、说明、参数定义 ├── prompt.md # 提示词模板，带变量占位符 ├── schema.json # 参数校验规则（JSON Schema） ├── few-shots/ │ ├── good-review-1.md # 正面示例 │ ├── bad-review-1.md # 反面示例 │ └── context-understanding.md ├── rules.yaml # 团队约束：必须输出哪些部分、严禁哪些行为 └── output-schema.json # 期望输出的 JSON 结构

prompt.md是核心，它决定了 AI 以什么身份、按什么逻辑处理输入。以下是一份用于代码评审的简化版模板：

你是一名资深代码评审工程师，评审风格偏向「先理解、再挑错」。 请按以下步骤处理： 1. 阅读用户提供的代码变更（diff）。 2. 概括本次变更的意图，用 3 行以内说明。 3. 逐项检查以下风险点（只列出确实存在的问题）： - 并发安全与竞态条件 - 异常分支是否被正确关闭 - 数据校验是否充分 - 是否有明显的性能隐患 4. 每个问题必须引用具体代码行号，并给出修改建议。 5. 如果某类风险不存在，不要强行编造，明确写「未发现」。 团队约定： - 语气直接，不用客套话。 - 建议必须可执行，禁止说「需要进一步关注」这类空话。 - 用中文回答，代码和变量名保持英文。 以下是用户的代码变更： {{diffContent}}

配合输出结构约束output-schema.json，AI 返回的内容可以是结构化 JSON，方便 CLI 做校验、过滤、写文件。这样设计有一个实打实的好处：模板作者写的是“让 AI 按什么套路思考”，而不是“让 AI 说哪句话”，可迁移性很强；换一个模型服务商，只要更新manifest.json里的 model 字段，整个团队的执行标准就跟着切换了。

3.2 为什么选 Git 作为同步通道而不是自建服务

模板分发机制是 teamai-cli 架构里最关键的一个决策。我选了 Git 仓库作为模板的存储和同步通道，而不是搭一个中心化服务，核心原因是团队本来就在用 Git 管理代码，权限体系、评审流程、审计日志都是现成的，不需要额外引入一套新系统。

用 Git 分发模板有几个直接的好处：

• 模板变更走正常的 PR 评审流程，团队经验可以沉淀在 commit history 里，出了问题可以 blame。
• 模板版本跟随仓库打 tag，发版之前可以整体测试一遍，而不是“改了直接生效”。
• 完全离线可用。开发机上只要拉过一次，后续teamai run不需要联网到模板中心，只有真正调用模型 API 时才需要外网连通。
• 每个成员都能贡献模板。最早只有我自己写，后来后端、前端、测试的同学都开始提交自己的模板包，模板数量很快就超出了我的预期。

teamai pkg update的实现不复杂：内部执行git pull --rebase，然后读取仓库里的manifest.json列表，更新本地索引缓存。为了避免团队成员长时间不更新导致模板版本过期，我加了一个 TTL 机制——模板仓库 48 小时没有同步过，执行teamai run时会提示“模板已过期，建议先执行 teamai pkg update”。

值得注意的一点是，我没有做“自动同步”。原因很实际：自动 pull 在用户正执行任务时可能因为分支冲突、本地未提交改动等问题报错，这种不可预期的打断比“手动更新”更让人反感。所以最终产品逻辑是“显式触发，失败可重试”，这也是 CLI 工具设计里一个容易被忽略但很重要的原则——宁可多一步用户操作，也不要让工具在错误时机自作主张。

4. Provider 抽象与成本统计：别让 API 账单变成黑盒

4.1 Provider 接口与适配器设计

大模型服务商的 API 格式五花八门，虽然现在大部分服务都宣称兼容“OpenAI 格式”，但实际用起来仍然有细微差别：有的流式返回字段不同，有的鉴权方式不同，有的是按 token 计费但 token 口径不一致。如果 CLI 里直接写死某个厂商的 SDK，团队被绑死不说，想换一个性价比更高的模型还得改代码。

所以 teamai-cli 在架构上用了一个很薄的 Provider 抽象层。核心接口在 TypeScript 里是这样的：

interface Provider { id: string; chat(req: ChatRequest): Promise<ChatResponse>; stream(req: ChatRequest, onChunk: (chunk: string) => void): Promise<ChatResponse>; countTokens(text: string): Promise<number>; estimateCost(usage: Usage): number; }

ChatRequest里包含 model、messages、temperature、maxTokens 这些通用参数。ChatResponse里固定返回文本内容、原始 usage（promptTokens、completionTokens、totalTokens）以及耗时信息。

每种模型服务对应一个适配器：DASHSCOPE（通义千问）、智谱 AI、Ollama 本地模型。实现一个适配器通常只需要几千行代码，核心是格式转换和错误码映射。Provider 层还处理了“模型不存在”“上下文超限”“限流”这几类最常见的错误，统一翻译成人类能读懂的提示再抛给用户。

这个抽象层的价值在第四周就体现出来了。当时团队里有人想试用一款新出的国产模型，只更新了配置文件里provider段和apiKeyEnv，所有模板包一个字母都不用改，直接跑。等新模型试用期结束后切回原有模型，也只改一行配置。团队采用新模型的成本几乎降为零，这是当时做这个抽象时完全没想到的高频收益。

4.2 用量统计怎么做才准确

成本统计是团队里最容易被忽略但又最要命的功能。一开始很多成员不想记录用量，觉得“反正公司出钱，我又不超预算”。但真要等月底拿到账单再去拆分，根本分不清哪笔钱是哪次任务产生的，会导致整个 AI 工具链被管理层质疑“没产出”。

我的做法是：所有 Provider 的调用都走同一个记账模块，每次请求结束之后往本地 SQLite 数据库（.teamai/usage.sqlite3）写入一条记录：

时间戳 用户 团队 模板名 模型 输入token 输出token 预估成本(CNY) 返回码 耗时(ms)

estimateCost函数维护了一张价格表，不同模型服务商的单价不一样，有时候同一个服务商的不同模型版本价格也不一样。价格表通过配置文件维护，版本更新之后可以动态调整。

token 估算这里有一个值得分享的经验：不要完全依赖模型接口返回的 usage 字段，因为不同服务商对“一次对话消耗的 token 数”口径可能不同。更稳妥的做法是本地先用一个快速估算函数算一遍（中文场景大约 1 个汉字等于 1 到 1.5 个 token，英文大约 4 个字符等于 1 个 token），再用服务商返回的精确值做校准。误差控制在 10% 以内就够用了，因为成本统计的目的不是为了精确到分，而是为了看趋势和异常。

teamai stats命令的输出长这样：

团队 AI 用量汇总（近 7 天） ------------------------------------------- 总请求数: 1,284 总调用时长: 36.2 小时 预估总成本: ¥ 342.68 人均日成本: ¥ 4.85 (预算 ¥15/人/日) 高频模板 Top5: code-review 412 次 ¥112.30 weekly-report 298 次 ¥ 45.20 db-schema-analyze 175 次 ¥ 78.90 error-triage 162 次 ¥ 42.10 api-doc-gen 107 次 ¥ 31.60 ------------------------------------------- 超预算用户: 2 人（zhangsn / liqw）

有预算超出风险时，teamai run会先弹一个警告，默认不阻断操作，但如果某位用户连续三天超过日预算，就会自动提示“今天已超预算，请改用本地模型或精简任务”。

成本统计这个功能上线之后，团队管理人员对 AI 工具的态度明显从“担心乱花钱”变成了“能看到每一分钱花在哪”。工具想在一个组织里活下来，让使用情况透明化往往比功能强大更重要。

5. 终端交互体验：进度反馈、流式输出与交互式评审

5.1 技术选型：ink + react 还是 chalk 硬写

CLI 工具的交互体验是个非常容易被低估的坑。如果只是“敲命令、等结果、打印输出”这种最简单的模式，用 chalk 逐行打印就够了。但 teamai-cli 的不少场景是有状态的：比如流式输出需要持续刷新终端行、交互式评审需要展示多选项、长任务需要进度条和耗时统计。

我对比了两个技术路线：一是用 ink + react 做完整的终端 UI，二是用 chalk + readline + cli-progress 手写。最终选了 ink。原因不是它的动画漂亮，而是 React 的声明式状态管理在处理“多状态切换”时能省很多事。比如teamai run的过程有“校验参数 → 加载模板 → 请求模型 → 流式输出 → 输出后处理 → 写文件”六个阶段，用 React 写就是六个条件渲染分支，状态流转清晰直观。如果用 readline 手写，状态一多就容易出现终端光标位置错乱、闪烁、清屏时机不对等诡异问题。

还有一点很重要：ink 自带终端的优雅降级。在非 TTY 环境（比如 CI）里，它会自动禁用交互式组件，只输出纯文本，不会因为检测不到终端宽度就崩溃。这个能力让我可以放心地把teamai run跑在 GitLab CI 的 JOB 里，同一个命令既能人用又能机器用。

5.2 真实使用场景的终端画面

我写代码的时候有个习惯，总要先把“用户看到的画面”想清楚再动手写实现，不然做着做着就容易跑偏。teamai-cli 的一个典型 review 场景，终端输出是这样的：

$ teamai review --staged [加载模板] code-review v2.3.1（团队模板仓库已是最新） [初始化] 上下文构建完成：获取到 5 个文件变更，共 842 行新增 / 136 行删除 [模型调用] qwen-plus 已连接，开始流式生成… 评审意见概览： 1. [严重] user_service.go:87-103 并发写入未加锁。sync.Map 在并发 Delete 和 Load 同时发生时 会导致部分 key 在清理流程中被重复处理。建议改为 mutex + map 或确认并发语义。 2. [建议] api/handler.go:45 错误日志没有包含 request_id，排障时无法串联整个调用链。 建议在 logger.WithField("request_id", reqID) 后包装一层。 3. [提示] user_service.go:120 该函数可提取为独立工具方法以便单元测试。 生成时间: 8.2s | 输入 token: 2,310 | 输出 token: 486 | 预估成本: ¥0.18 是否将评审结果写入 review-output.md? (y/N)

这里有两个交互设计我觉得很关键。第一，结论先行。AI 生成的完整分析可能好几千字，但终端里只默认展示最关键的几条结论，想要全文可以输入y落盘到文件。第二，每条意见都强制绑定“文件:行号”，不让模型输出任何没有锚点的建议。落地的时候这条约束是在模板的rules.yaml里硬性规定的，不是靠提示词里“请附上行号”这种软性请求。

5.3 处理大上下文与小模型的双重限制

实际用起来最大的限制是模型上下文窗口。一个改动量稍大的 PR，diff 轻轻松松上万行，这超出了很多主流模型的单次输入上限。我处理这个问题的方式是“分层评审”：

1. 先按文件拆分 diff，按照文件类型和变更行数从大到小排序。
2. 对每个文件单独调用一次模型，要求输出“这个文件里发现了哪些问题”。
3. 所有文件的评审意见汇总之后，再调用一次模型做“去重、分级、生成总结”。

这样做的额外收益是，每个文件的问题定位更准确，不会因为上下文过长导致模型忘掉前面的内容。代价是 token 消耗会高一些（多了一次汇总调用），但总成本仍然在可接受范围内。经验数据是：一个 1000 行变更的 PR，拆成 4 到 6 个文件分别评审，比一次性塞进去的评审质量明显高一个档次。

对于本地小模型（比如 Ollama 跑的 7B 模型），上下文窗口更小，我的策略更保守：限制单次输入不超过 3000 token，超出的部分先让模型做一个“摘要提取”，再把摘要作为上下文传给后续调用。小模型做复杂推理确实能力有限，但它擅长按规则做格式化输出。所以本地模型的模板主要用于简单任务（日志分类、文案改写、格式转换）。

6. 落地期间踩到的坑：权限、并发、上下文与幻觉

6.1 密钥权限和跨平台问题

第一个坑来自密钥存储。最初版本为了省事直接把 API Key 写在了~/.teamai/config.json里，权限位设成 600，觉得这样就安全了。后来团队里一位同学在做安全审计的时候提出一个问题：这个文件对于进程内其他插件和 shell 历史都不设防，而且一旦config.json被同步工具上传到云盘，密钥就直接泄露了。

于是我把密钥存储改成“环境变量优先，系统凭据管理器兜底”的方案。但系统凭据管理器在 Linux 上的坑比想象中多：很多容器镜像没有安装 libsecret，macOS 钥匙串在 CI 环境里会弹 UI 框挂起，Windows 凭据管理器的命令行操作非常慢。最后妥协的结论是：

• 本地开发环境：推荐teamai auth login写入系统凭据管理器；如果不可用，写入~/.teamai/credentials（权限 600）。
• CI 环境：一律用 CI 平台的 secret 变量注入环境变量，不落盘。
• 公共开发机：不持久化任何密钥，每次执行前临时 export，用完进程退出即消失。

这个方案虽然不是最优雅的，但胜在“坏了立刻能定位问题”。teamai doctor里专门加了一项密钥检查：如果同时检测到环境变量和凭据文件里都有同一个 Provider 的 Key，会警告用户以环境变量为准，避免“改了环境变量不生效”的错觉。

6.2 并发同步的竞态问题

第二个坑来自teamai pkg update的并发同步。团队里 14 个人，每个人都有多个终端窗口，如果有人同时执行模板更新，git pull大概率会触发 lock file 冲突，轻则报错，重则本地模板仓库状态错乱。

我一开始的处理很简单：捕获 git 报错信息，提示“模板仓库忙，请稍后重试”。结果团队里另一位同学在代码评审里直接否了这条实现，他建议做一个互斥锁，同一个机器上同一个时间只允许一个pkg update进程在跑。实现方案用 Node.js 的open系统调用里wx标志创建锁文件：

import { open, rm } from 'node:fs/promises'; async function acquireLock(lockPath: string, timeoutMs = 5000): Promise<void> { const start = Date.now(); while (Date.now() - start < timeoutMs) { try { const handle = await open(lockPath, 'wx'); await handle.writeFile(`${process.pid}\n`); await handle.close(); return; } catch { await new Promise(resolve => setTimeout(resolve, 200)); } } throw new Error('另一个 teamai pkg update 正在执行，请稍后再试'); }

这个锁文件在进程退出时通过finally块删除。如果进程崩溃导致锁文件残留，pkg update会自动检查锁文件里记录的 PID 是否还活着，如果 PID 不存在了就删除锁文件重新执行。这个机制看着小，但避免了很多“模板仓库坏了只能手动删目录”的尴尬场景。

另一个和锁相关的问题是：不同项目仓库如果指向同一个模板仓库 URL，锁的 key 应该按仓库绝对路径算，而不是按命令执行目录算。否则同一台机器上两个项目同时执行pkg update还是会冲突。

6.3 大 Diff 截断与模型输入上限

第三个坑是意识形态层面上的：一开始我天真地认为“大模型能处理长文本”，直接把整个 diff 当成 prompt 的一部分扔过去，结果在模型端频繁触发“context length exceed”错误。评审一个大型 PR 几乎必然失败，只能看着终端输出一长串错误。

后来我调整了策略：模板包在执行前会自动计算输入内容的 token 估算值，如果超过模型最大上下文的一半（留出输出空间），就触发“分段处理”流程。分段逻辑按文件边界切分，绝不把同一个文件切开处理，因为代码评审的上下文完整性比单次处理量更重要。

真实场景下还有一类隐蔽的问题：diff 中包含大量第三方库的 lockfile 变更或者自动生成代码，这些东西喂给模型纯属浪费 token。我在工具里加了一个.teamaiignore机制，支持把这类路径排除在上下文构建之外。这个做法在铺开之后被团队广泛好评，因为大家很快发现了“喂给 AI 的内容质量比数量重要得多”。

6.4 “一本正经胡说八道”的评审意见

最后这个坑是最难通过技术手段解决的：模型幻觉。大模型在评审代码的时候，有相当概率会一本正经地指出一个根本不存在的“严重问题”。比如有一次它信誓旦旦地说某个函数存在整型溢出风险，但实际上那行代码的类型是个字符串。

我做了三个层面的防御。第一，在模板的rules.yaml里强制要求每条问题必须带行号和代码引用，并且专门写了一句话：“如果你怀疑存在问题但无法定位到具体行号，请标注为‘疑似’，不要使用确定语气”——模型对“疑似”这个词的服从度明显高于对“你确定吗”这类反问。

第二，工具会把“有明确行号且引用原文”的问题标记为“可验证”，把“疑似但无法定位”的标记为“待人工确认”。评审结果落盘时，两类问题用不同标签区分，人工评审员只需要优先看第一类。

第三，跑了一个阈值策略：如果某次评审输出的“严重问题”数量超过文件数量的 20%，我会在终端额外打一行提示“本次评审发现较多严重问题，建议人工复核”，希望降低用户无脑全盘接受 AI 意见的概率。

就算做了这么多，我仍然坚持团队里的核心原则：AI 评审意见只是“筛选器”，不是“裁判”。它的价值是把明显的问题快速捞出来，把人的精力留给真正需要判断力的地方。谁要是把 AI 评审结果直接当成最终代码审查结论，那是流程设计的问题，不是模型的错。

7. 上线两个月的复盘：哪些设计被验证了，哪些被推翻了

7.1 被反复验证的设计决策

第一，模板库 Git 化的方向走对了。上线第二周就有后端同事主动往模板仓库里提交了一个“数据库表结构评审”模板，后来测试同学也加了“测试用例补全”模板。团队自发的模板贡献是我最乐意看到的现象，这意味着工具真正变成了团队的基础设施，而不是一个人的自嗨。

第二，成本统计功能的表现超出预期。管理层看到预算看板之后，不但没有再质疑“AI 工具是乱花钱”，反而主动问能不能给团队加预算。因为每一笔钱都能对应到一次具体的任务产出，这是其他所有内部工具都做不到的透明度。

第三，“显式更新 + doctor 自检”这种相对保守的交互，在团队里反而很受欢迎。大家不会奇怪为什么功能没有自动升级，因为 git 的 workflow 本来就是“自己拉代码、自己体验新版”。团队技术成员普遍接受度高，这在一定程度上缓解了我最初担心的“开发者天生抵触新工具”的问题。

7.2 被现实推翻的设计

也有很多设计被现实打脸。第一个是 token 级语义缓存——我在第一版实现了一套“相同请求直接命中缓存”的机制，想着能够显著降本。结果上线之后发现收益极低，因为团队成员的真实任务是高度个性化的，几乎不会出现两次完全相同的请求。代码评审的 diff 每次都不一样，周报内容也每次都不一样。这个功能两个月后被我砍掉了，只保留了“完全相同请求”的哈希级简单缓存，命中率反而高了不少。

第二个是交互式 chat 子命令。我原本设想团队成员可以在这个 CLI 里完成所有 AI 交互，省得来回切换浏览器。但实际数据显示teamai chat的使用率只有teamai run的百分之几，大家还是习惯在专业聊天客户端里做自由对话。后来我想明白了：chat 模式与命令行场景天然不匹配，命令行工具擅长的是“一次输入、结构化输出”，而不是“多轮来回聊天”。chat 子命令被保留下来，但定位改成了“快速验证模板效果用的调试器”。

第三个是复杂的 YAML 工作流配置。早期版本支持通过 YAML 定义多步骤 AI 流水线，比如“先总结 diff → 再提取关键函数 → 最终生成评审报告”，我当时觉得这是团队工具的必备能力。但真正的用户行为是：80% 的人只用teamai run加一个模板名，加两个参数的都很少。复杂工作流配置变成了极少数人的玩具，而且维护成本很高。后来我把这个功能移除，只在teamai run里支持一个可选的--pipeline参数，指向一个简化的 JSON 数组配置，效果反而更清晰。

7.3 给后来者的建议

复盘完之后，我给自己总结了几条做团队内部 AI 工具的原则。

第一，先解决一个具体的痛点，再谈扩展。不要一上来就做一个“AI 全家桶”平台，那会让使用者无从下手。我们就是从“代码评审”这一个场景切入的，等大家习惯了这个工具体系，再慢慢加周报、文档生成、错误排查等场景。

第二，CLI 的输出格式必须“人和机器都能吃”。不要依赖终端颜色来传达关键信息，因为 CI 日志里颜色会丢失；不要用表格宽度依赖终端宽度，因为自动化脚本环境经常宽度是 0。坚持输出结构化数据（JSON）到 stdout，人类可读的展示写到 stderr 或者文件，这是命令行走入自动化的基本尊严。

第三，从第一天起就埋点统计。哪怕只是把每次调用的模型、耗时、成本写进本地日志，后期做任何改进都有了判断依据。等到工具被广泛使用之后再补，统计数据的缺失就永远补不回来了。

写在最后

如果让我用一个词总结 teamai-cli 这个项目给我的收获，我会选“可组合性”。命令行的终极价值不是它比网页工具更“酷”，而是它能被放进脚本、被 CI 调用、被定时任务触发、被其他工具消费。当团队的 AI 能力沉淀成一条条可执行的命令之后，它不再是一次性的聊天，而是一个可以被持续集成、持续改进的内部基础设施。

我现在的习惯是，任何重复超过三次的 AI 任务，都会花半小时把它固化成模板提交到团队仓库里。这个动作很轻，但累积起来的效用非常大。如果你也在考虑给自己的团队做一套 AI 工具链，我建议从一条最痛的命令开始，把它的交互和输出打磨到让人用了就回不去，然后让团队的口碑替你推广。