企业官网建设流程全解析

这周你问AI要过几次代码评审意见？我数了数自己上午的操作：打开网页、粘贴diff、复制回复、贴回群里，同样的动作重复了三遍。然后我意识到，团队里至少有四个人在干一模一样的事，提示词各写各的，上下文各贴各的，最后AI到底给过什么建议、哪个commit采纳了，谁也说不清。

teamai-cli就是我为这个现状写的命令行工具。它把AI能力收进终端，让团队在同一个管道里跑提示词、消费模型、输出结构化结果。它不是一个聊天框，而是一条流水线：输入是可脚本化的内容（git diff、日志、代码片段），输出是直接可用的产物（commit message、评审意见、文档段落）。这篇文章不聊概念，直接讲它的设计思路、最小实现，以及我在真实团队里跑出来的经验。

1. 从聊天框到命令行：团队AI工作流为什么需要一次“降维”

1.1 三个真实痛点：提示词、上下文、审计

先说第一个，提示词不统一。你让团队里三个人用AI做代码评审，大概率会拿到三个不同风格的模板：有人让AI挑bug，有人让AI看命名，有人什么都往上贴。AI的表现高度依赖提示词，团队没有统一模板，结果就是每个人得到的质量方差极大。有些人觉得AI很好用，有些人觉得纯属浪费时间，本质不是模型差，是输入差。

第二个痛点是上下文割裂。一个人早上问AI“帮我看看这个函数有没有并发问题”，下午又贴同一段代码问“帮我优化一下”，AI根本不记得上午聊过什么。切到网页、切到桌面端、切到IDE插件，每一次切换都意味着重新交代背景。对于写代码的人来说，最自然的上下文本来就在git、文件系统、终端环境里，却要手动复制出来再粘进聊天框，这是巨大的信息损耗。

第三个痛点是不可审计。团队用AI产生的所有交互都在个人工具里，管理员看不到，团队负责人看不到，连使用者自己都很难回溯：上周让AI改过哪段代码？当时给了什么建议？后来改了没有？在合规需求越来越普遍的背景下，这其实是迟早要解决的问题。命令行工具天然有日志、有输出、有退出码，接入CI、接入流水线之后，每一步都有迹可循。

1.2 命令行不是倒退，而是给AI装上“工位”

有人听到CLI第一反应是：都什么年代了，还教用户敲命令？这里要分清一个概念：teamai-cli不是给普通用户用的聊天替代品，它服务的对象是开发者和自动化管道。开发者的工作环境本来就是shell，git、grep、jq、docker全在终端里，AI接入终端意味着AI可以就地消费这些工具的输出，而不是让人去四处复制。

命令行带来的另一个好处是组合性。聊天界面里你只能手动输入和复制，CLI里你可以写脚本、加管道、接CI、挂git hook。比如提交代码前自动跑一遍AI风格检查，这个动作在聊天框里永远不可能实现，但在CLI里就是一行配置的事。可以类比成：网页聊天是打车，CLI是给你一辆车和一条可以编程的公路，学习成本高一点，但能做到的事情完全不是一个量级。

2. teamai-cli的整体骨架：定位、模块划分与选型取舍

2.1 定位：只做管道，不做聊天室

teamai-cli一开始就做了一个关键取舍：不做交互式聊天。我知道这个决定会劝退一部分人，但换个角度想，如果又做一个终端版ChatGPT，那就等于把一个已经有无数成熟方案的问题再做一遍。团队缺的不是又一个聊天入口，而是把AI嵌入现有工作流的能力。

所以teamai-cli的核心抽象是pipeline（管道）。一次执行流程包含输入收集、提示词渲染、模型调用、结果解析、输出落地五个阶段。你可以把它想象成一个加工车间：原料进来（diff、日志、文本），经过设定的工序（模板、模型、解析器），产出合格零件（消息、评审报告、文档）。每条管道都是强类型的、可配置的、可重复执行的，这才是团队协作需要的东西。

2.2 模块划分：config / provider / pipeline / output / cache

我早期写工具喜欢把所有逻辑堆在一个文件里，但teamai-cli这种要长期演进、要给别人用的项目，模块边界必须一开始就划清楚。现在整个工程分成五块，结构稳定之后几乎没有大改过：

• config：负责读取和校验配置，支持全局配置加项目配置合并，保证每个团队可以有自己的默认值。
• provider：模型适配层，屏蔽不同服务商的API差异。内部定义统一接口，外部通过base_url、model、apiKey等参数实例化。
• pipeline：管道引擎，负责编排模板、模型调用、工具函数和数据流转。
• output：所有命令的输出都走这层，支持human可读、json、markdown等格式。
• cache：本地缓存层，存历史结果和中间产物，避免重复调用模型烧钱。

这个划分唯一的缺点是想得很美，落地时容易导致过度设计，所以我在实现时做了硬约束：任何模块不允许循环依赖，任何模块必须能单独测试。

2.3 技术栈选择与理由

技术栈选型是Node.js + TypeScript + Commander。说实话，写CLI工具Python也很顺，Typer + Pydantic非常能打。但teamai-cli有一个特殊需求：要和前端团队的现有工具链无缝接合，将来想嵌入构建流程、和ESLint/Prettier的配置共用一个项目，Node生态天然更顺。

TypeScript的核心价值不是类型本身，而是让管道的输入输出有了契约。每条管道的输出是string还是对象，下一个阶段怎么消费，在编译期就能卡住一大批错误。Commander则是最主流的CLI参数解析库，命令、参数、帮助文档都是现成的，不需要自己造轮子。打包用esbuild，依赖用pnpm，测试用vitest，整套组合都很常规，维护成本低。

3. 半小时搭出最小可用版本：目录结构、配置定义与核心命令

3.1 目录结构与入口设计

先看最小可用版本的目录结构，这不是摆设，每一个文件夹都有它的职责：

teamai/ bin/ teamai.js src/ commands/ run.ts list.ts config.ts core/ pipeline.ts provider.ts cache.ts templates/ commit.ts review.ts utils/ git.ts output.ts config/ defaults.json package.json tsconfig.json

入口文件bin/teamai.js就是在package.json里通过bin字段注册的可执行文件，实际逻辑在src/commands里。run.ts是核心，它读取用户在命令行里指定的pipeline名字，然后找到对应的配置和模板，跑完五个阶段。

3.2 配置文件的schema设计

配置是teamai-cli的命门。团队协作里，配置文件本身就是一种团队资产，它会进git仓库，会被code review，所以schema必须稳定。

{ "provider": { "baseUrl": "https://api.example.internal/v1", "model": "deepseek-chat", "apiKeyEnv": "TEAMAI_API_KEY" }, "pipelines": { "commit-message": { "template": "commit", "input": { "type": "git-diff", "target": "HEAD~1" }, "temperature": 0.2, "maxTokens": 500 }, "code-review": { "template": "review", "input": { "type": "git-diff", "target": "origin/main...HEAD" }, "temperature": 0.1, "maxTokens": 3000 } } }

几个设计点值得展开。apiKey不直接写在配置里，而是指向一个环境变量名，这避免把密钥提交进仓库；temperature在管道级别配置，因为生成commit message要保守，写周报可以稍微放开一点；input.type用了git-diff，意味着pipeline开始时会自动执行git命令收集输入，这是teamai-cli和通用聊天窗口最本质的区别。

3.3 三个核心命令的实现思路

最小可用版本只需要三个命令：run、list、config。

run是主命令，逻辑如下：

const config = loadConfig(projectRoot); const pipelineConfig = config.pipelines[name]; if (!pipelineConfig) { console.error(`pipeline "${name}" not found`); process.exit(1); } const input = await collectInput(pipelineConfig.input); const template = loadTemplate(pipelineConfig.template); const prompt = renderTemplate(template, input); const result = await callModel({ provider: config.provider, messages: [{ role: "user", content: prompt }], temperature: pipelineConfig.temperature, maxTokens: pipelineConfig.maxTokens, }); writeOutput(result);

list命令就是把config.pipelines里的key按表格打出来，方便团队看现在有哪些可用的管道。config命令支持打印当前生效的合并配置，调试时非常有用。这三个命令加起来不到三百行，已经能覆盖日常使用。

4. 模型接入层与工具调用机制：teamai-cli的灵魂

4.1 统一模型接口

当时市面上各家模型API格式还不统一，我见过从请求格式到token计算方式都完全不同的情况。如果每接一家就改一遍pipeline逻辑，那项目很快就会被服务商锁定。所以我定义了一个极简的统一接口：

interface ChatProvider { chat(request: ChatRequest): Promise<ChatResponse>; countTokens(text: string): number; }

实现这个接口的时候，只需要把各家SDK的请求格式转换成内部的ChatRequest结构。baseUrl和apiKey从配置注入，请求库直接fetch，不引入大依赖。这个抽象层最直接的好处是：想换模型服务商时，改动只发生在provider目录，pipeline和模板完全不动。

关于模型选型，我的经验是生产任务和开发任务要分开。生成commit message这种高频低风险任务用便宜的小模型就够，代码评审这种低频高价值任务才上强推理模型。在teamai-cli里就是provider配置不同而已，同一个命令，换个model字段，成本差出好几倍。

4.2 工具调用与管道编排

管道里最有价值的一个设计是工具的引入。模型本身读不到git仓库的状态，但CLI可以。teamai-cli允许管道配置里声明tools，每个tool本质是一个可执行的函数，模型在生成过程中可以触发。

const tools = { list_files: async (dir: string) => { return await exec(`find ${dir} -type f | head -50`); }, read_file: async (path: string) => { return await fs.readFile(path, "utf-8"); }, git_log: async (range: string) => { return await exec(`git log --pretty=format:"%h %s" ${range}`); } };

为什么这个机制重要？因为它把AI的“读代码”能力从检索式变成了任务驱动式。传统聊天窗口里，你得先把代码文件内容手动贴给AI；而在管道里，AI可以根据任务需要自己调用工具去读文件、查日志、列目录。这相当于给了AI一双手，而不只是一张嘴。

管道编排上我分成五步：collect → render → call → parse → output。collect阶段负责把外部输入（diff、日志、文件内容）拉进来；render阶段把模板和输入拼成完整prompt；call阶段调用模型；parse阶段处理模型可能返回markdown包裹、JSON包装等格式；output阶段按用户指定的格式落地。每个阶段都是独立的中间件函数，可以单独测试，这是整个项目最稳定的一块。

4.3 上下文管理策略

聊到上下文，这是团队用AI最容易踩的坑。一次性把整个仓库塞给模型不现实，token会爆，成本会炸。teamai-cli的默认策略是“最小上下文”：管道只携带当前任务真正需要的输入，code-review管道默认只带diff的变更内容，而不是整个文件。

有些场景确实需要全程会话，比如让AI连续分析多个文件并保持之前的判断。我加入了会话模式，启动时指定sessionId，管道会把历史消息追加为上下文，同时设置一个滑动窗口：超出窗口的历史消息自动截断成摘要。这是我自己实现的简化版“Memory压缩”，别指望它和商业产品的效果一样好，但在CLI管道里够用。

5. 团队场景中的三条典型工作流：从commit message到周报生成

5.1 git提交信息生成

第一个场景最刚需：git commit message。以前团队commit message五花八门，有"fix bug"的，有"更新"的，扯皮成本特别高。teamai-cli的commit-message管道做了一件事：跑git diff拿到最近的变更，然后根据一个团队约定的模板生成提交信息。

$ teamai run commit-message --target HEAD~1 feat(api): 增加用户批量导入接口 - 新增 /api/v1/users/import 路由 - 支持 CSV 和 JSON 两种格式 - 重复邮箱默认跳过并返回错误明细

生成之后不会直接替你提交，而是输出到stdout，你review一遍再自己git commit。这背后的理念是：AI负责草稿，人负责决策。别让工具自动提交代码，这是我在一次把README写进提交信息的事故之后得到的教训。

集成方式也很简单，在.git/hooks/prepare-commit-msg里加两行，其中把teamai run commit-message的输出作为默认模板，已经完全够团队日常使用。

5.2 自动补全Code Review建议

第二个场景是Code Review辅助。传统review流程全靠人肉看diff，重要问题经常漏掉，而且资深工程师的时间最贵，不能全都耗在低级问题上。

teamai-cli的code-review管道会做三件事：先收集当前分支相对主干的所有diff，然后按文件切割，分别送去模型评审，最后把各部分结果合并成一份markdown报告：

## 评审报告 ### src/services/user.ts - 严重：importUser在批量插入时未捕获唯一键冲突 - 建议：改用upsert或先做exist检查，否则并发场景下会丢数据 - 建议：加一个requestId字段，方便链路追踪 ### src/cli/run.ts - 提示：process.exit(1)前记得刷新输出缓冲，否则错误信息可能被截断

这份报告会生成在项目.mr-review目录下，并且带一个缓存：如果diff的sha256没变，不会再重复调模型。实测下来，团队花费在基础风格问题上的时间明显减少，review可以聚焦在架构和并发等真正需要人的判断的问题上。

5.3 基于代码改动的文档更新

第三个场景最容易被忽视，但对长期维护价值最大：文档更新。以前每次发版改接口，文档总跟不上，等有人发现文档和代码不一致的时候，距离真相已经隔了三四个版本。

teamai-cli的changelog管道每次跑release前自动更新。实现上就一个思路：收集从上次tag到现在的所有commit message，交给模型按规范排序归类，生成待发布的changelog草稿。注意是草稿，最终还是要人来确认。这类管道出的活，只要模板设计合理，可采纳率可以达到八成以上，剩下两成是需要补充PR链接、issue编号这类需要额外来源才能获取的信息。

6. 实测中的坑：模型波动、限流、上下文爆炸与排查链路

6.1 模型返回不稳定的根因与重试策略

第一类坑是模型返回不稳定。最常见的是要求输出JSON，结果模型返回了带markdown代码块包裹的文本。你直接把整个字符串JSON.parse，必挂。第一次遇到时我以为是网络问题，排查了半天才发现是模型在输出外面包了```json。

根因定位后，我做了两层防御。第一层是parse阶段先剥离常见的包裹符号，再尝试解析；第二层是在prompt里显式声明“不要输出任何解释，只输出JSON”，同时temperature调低到0.1。即便这样，还是会有偶发失败，所以又加了一版“带重试的解析器”：解析失败时把错误信息喂回给模型，让它自己修正输出。实测重试一轮的成功率能到95%以上。

还有一个隐蔽的坑：模型输出的换行和缩进在传递到下一阶段时会被markdown吞掉。如果管道接着要生成文件，必须在输出的解析阶段保留空白字符，否则生成出来的文件格式全乱。

6.2 并发请求被限流的处理

第二类坑是限流。code-review管道一开始是串行请求，一次diff一百个文件可能要等好几分钟，我加了并发控制，结果立刻触发模型服务的限流——报错信息一长串，什么rate limit exceeded。

排查时我没急着调大并发数，而是先看了模型服务返回的响应头，里面有关键信息：x-ratelimit-limit、x-ratelimit-remaining、x-ratelimit-reset。我照着这个做了一层客户端限流：按剩余配额决定下一批请求数量，同时用指数退避处理429。核心逻辑不复杂：

async function callWithRetry(request) { for (let attempt = 1; attempt <= maxAttempts; attempt++) { try { return await request(); } catch (err) { if (err.status === 429) { const waitMs = Math.min(1000 * 2 ** attempt + randomJitter(), 10000); await sleep(waitMs); continue; } throw err; } } }

这里关键的不是指数退避本身，而是randomJitter。并发请求全部退避到同一时间再重试，依然会同时撞上限流，加一点随机抖动可以让重试分布更均匀。这种细节，只有被真实流量打过才知道。

6.3 上下文长度失控问题

第三类坑是上下文长度失控。AI用着用着突然报token超限，一问是有人手动指定了sessionId，反复跑同一个会话任务，历史越攒越长。这种问题在本地小范围测试时根本发现不了，因为你自己只跑一两次，等到团队天天用，几万人次的会话叠加，问题立刻爆发。

我在管道层加了上下文预算机制：给每个会话设定maxContextTokens，每次追加消息之前先算当前总长度，如果超过预算就把最早的消息替换成一条摘要。摘要本身也调用模型生成，但这个成本比超限后重跑一次低得多。调度上再配合一个硬规则：会话模式默认不开放给高频管道，只有明确需要连续对话的能力才开启。

还有一个几乎人人都踩过的坑：把代码文件整个塞进上下文，明明只有两个函数变了。teamai-cli后来加了--context-lines参数，只截取diff对应的上下文行，省token效果立竿见影。

7. 进阶优化：缓存、成本控制与团队反馈闭环

7.1 本地缓存与增量检测

缓存是我最得意也最后悔加晚的一个模块。teamai-cli的缓存逻辑基于内容寻址：任何输入（diff、配置文件、prompt模板）先算sha256，如果命中缓存则直接返回历史结果，不调用模型。刚开始只做了表层缓存，后来发现管道输入经常只有微小变化，比如commit多了一条，整批缓存就失效了。

我换成增量缓存后，显著提升了体验。比如code-review管道，一个分支连续提交几次，diff大部分是重叠的。我记录文件级别的diff缓存，每次只对新增和变更的文件调用模型，旧结果直接复用。实测下来，中期分支的评审成本能降到首次评审的30%左右。

7.2 成本估算与优化

谈到成本，很多团队负责人第一反应是“AI写代码能花多少钱”，我用一次真实任务算了一笔账。假设一个执行评审的diff平均是3万token，用中等模型每百万token几十块钱，一次评审单跑成本就在一两块钱。一天几百次request，一个月就是几千块。这还不算失败重试的成本。所以我把成本监控做进了管道：

• 每次call记录prompt_token和completion_token
• 按模型单价换算成估算成本
• 输出到日志末尾，同时推给团队的企业微信webhook

这个功能让全组都变成了成本敏感的用户，从那以后，再没人把一个几十MB的文件直接丢给模型了。还有一层优化是模型分级：commit message这类基础任务固定用小模型，只有复杂推理任务才放大模型。这个策略让月成本直接降了一半。

7.3 反馈闭环

最后说说团队反馈闭环。工具做出来如果没有人反馈，一定会僵化。teamai-cli在输出端做了一个约定：管道产出的结果文件头部会带metadata，包含模型、时间、pipeline版本和输入摘要。这样团队review的时候如果发现结果有问题，可以直接在文档里@模型名或pipeline名，负责人能很快定位是哪条管道、哪个模板、哪个模型出的问题。

我把反馈分成两类：一是质量反馈，“结果不好”，这种我会去调提示词模板或换更强的模型；二是流程反馈，“这个管道不该存在”，这种我会反思是不是流程设计反了。两条路分开走，工具才会越用越顺。

写teamai-cli这个项目本身也给我上了一课，工具的核心从来不是技术多炫，而是团队真的愿意用。命令行降低了自动化成本，但提高了使用门槛，所以模板、配置、文档这些“非核心代码”反而决定了最终能不能落地。我的建议是：如果你也想做类似的团队AI工具，先找一条最高频的流水线跑通，比如commit message，用它验证整个管线，再去扩展评审和文档场景。工具是会随着使用长大的，不要试图第一版就完美。