腾讯开源TeamAI-CLI：简介、原理、实战

在CLI复兴里提到CLI对于Agent的价值与意义。

TeamAI-CLI

腾讯开源开源（GitHub，771 Star，75 Fork）面向AI智能体的团队Harness管理和分发工具，把技能、规则、钩子（Hooks）、文档、MCP配置放进共享Git仓库、再同步给Claude Code等各种编码Agent的CLI工具。

适用场景：

• 团队统一AI编程助手规则和安全检查
• 大公司跨团队共享AI技能和最佳实践
• 沉淀团队踩坑经验，避免重复踩坑
• 管理多个AI工具的MCP Server配置

核心逻辑

• 管理员创建共享仓库（支持GitHub、GitLab、GitCode、TGit、CNB），成员 teamai init 绑定
• 在某个Agent里调好Skill、Rule、钩子，teamai push推到新分支并自动开MR
• 评审合并后，其他成员的SessionStart钩子自动执行teamai pull，把资源写进各自Agent的目录，如~/.claude/skills/、~/.codex/skills/...
• 使用teamai source add订阅别的团队公开的Skill仓库，形成跨团队的经验联邦

版本管理用Git，评审用MR，触发用钩子，检索用BM25。

资产类型：

• skills：Markdown技能卡，可被CC等工具识别；
• rules：团队编码规范、审查规则；
• docs：项目文档、流程说明；
• hooks：自定义SessionStart、PreToolUse等；
• mcp：团队MCP Server配置。

分发链路：push→创建MR→评审合并→pull注入，所有git操作都在隔离worktree里完成，不会污染成员当前的工作区和分支。知识资产进仓库主分支的.teamai/目录；成员注册、会话摘要、投票、使用统计等上报数据走独立的teamai-reports孤儿分支，避免把Git主分支弄脏。

TeamAI把所有状态收敛到Git，而不是自建服务端。架构大致四层：

• 团队Git仓库：主分支放.teamai/知识资产，孤儿分支放上报数据，teamwiki/ 放teamai import生成的代码知识图谱；
• teamai CLI：init / pull / push / recall / import等命令，基于simple-git操作仓库；
• 注入层：把skills、hooks、mcp、recall子Agent写到各AI工具约定的本地目录；
• AI工具层：Claude Code、CodeBuddy、WorkBuddy等最终消费这些配置。

用Git托管，天然获得版本、分支、MR评审和回滚能力；代价是整个团队必须依赖同一个Git平台，且仓库权限要配好。

基本功能

在Git托管平台创建共享经验仓库，授予团队成员写权限，运行teamai init <repo>。

团队成员通过如下命令获取经验：

# 项目级初始化（默认，资源安装到项目目录下）
cd /path/to/my-project
teamai init <repo>
# 或用户级初始化（资源安装到 ~/ 下）
teamai init <repo> --scope user

初始化完成后，每次开启AI会话时都会自动拉取管理员发布的skills、rules等Harness更新，无需手动同步。

分发策略

管理员一次配置、随 teamai pull 分发给每位成员的团队级设置：

能力	命令	作用
角色（Roles）	teamai roles	定义「角色→命名空间」映射，让每位成员只同步与自身角色匹配的skills
标签（Tags）	teamai tags	给skills/rules打标签，成员只订阅自己需要的标签
订阅源（Sources）	teamai source	订阅额外的skill仓库------其他团队的公开仓库，或本团队内的公共/共享仓库；已订阅的skills会在pull时自动同步

使用分析

洞察团队实际如何使用 I工具：

能力	命令	呈现内容
用量（Usage）	teamai digest	团队周报------token用量、会话量、干预率
会话（Sessions）	teamai session save	脱敏的单会话摘要（工具序列、对话轮次、干预次数），喂给周报的Session Highlights
看板（Dashboard）	teamai dashboard	Web看板，实时展示成员的编码会话状态、干预次数和token用量
知识库健康（KBHealth）	teamai dashboard→KBHealth	内置于看板的报告页面，展示知识库使用情况与健康状态------各类型覆盖率、高频召回条目、沉默条目、召回趋势、作者贡献及维护控制台

Harness 管理和分发

TeamAI 把 skills、rules、docs、钩子统一存放在共享 Git 仓库，通过「push → 评审合并 → pull」的流程分发到每位成员的本地 AI 工具，并支持订阅其他团队或公共仓库的 Harness。

工作原理

teamai push → 创建分支 + MR → reviewer 审批合并
                                    ↓
           SessionStart hook → teamai pull → 同步到本地 AI 工具

成员通过 teamai push 提交变更并创建合并请求供审核。若某个资源已在未合并的 PR 中等待评审，再次对它执行 teamai push 会就地更新该 PR，而非新开一个重复的 PR。合并后，teamai pull（由 SessionStart 钩子在会话启动时自动触发）将最新资源同步到本地。Skills 会同步到 ~/.claude/skills/、~/.codex/skills/、~/.cursor/skills/、~/.codebuddy/skills/ 等目录。在 project scope 安装下，SessionStart 会先为当前工具创建项目根目录（例如 <project>/.claude），再 pull 写入；单独执行 teamai pull 仍不会凭空创建 Agent 目录。

团队钩子

在 hooks/hooks.yaml 中声明自定义钩子，teamai pull 自动分发到所有 AI 工具：

hooks:
  - id: block-secret
    description: 提交前扫描密钥
    event: PreToolUse
    matcher: Bash
    command: 'bash -lc "~/.teamai/team-scripts/scan-secret.sh" || true'
    tools: [claude, cursor]

命令行示例：

teamai hooks list      # 查看生效钩子
teamai hooks inject    # 重新注入到每个已安装的工具
teamai hooks remove    # 移除所有teamai管理的钩子

团队 MCP Server

在 mcp/mcp.yaml 中声明一次，teamai pull 按各工具原生格式写入。密钥用 ${VAR}。

servers:
  - name: gpu-analysis
    transport: http            # stdio | http | sse
    url: https://example.com/api/mcp
    headers:
      Authorization: Bearer ${GPU_ANALYSIS_TOKEN}

命令行示例：

teamai mcp list | inject | remove

Skill 订阅源

订阅额外skill仓库，其他团队的公开仓库，或本团队内的公共/共享仓库：

teamai source add https://github.com/other-team/teamai-public.git --name other-team
teamai source list
teamai source browse other-team    # 浏览可用 skills
teamai source remove other-team

添加/移除会立即在本机生效，订阅的skills会在下一次teamai pull时同步。需要将teamai.yaml的改动分享给团队成员时，再运行teamai push。

团队包

共享并一键恢复团队的 npm 包和 Claude Code 插件：

teamai install typescript
teamai install typescript@5.9.2 --npm
teamai install code-review@claude-plugins-official
teamai push       # 分享团队声明
teamai install    # 安装团队声明的全部包

完整工作流和配置见使用指南。

知识库

TeamAI还把团队沉淀的经验和代码结构组织成可检索的知识库，让AI在需要时自动召回。

自动经验沉淀

Session结束时，Stop钩子按摩擦信号对session评分，这些信号表明本次session踩到值得记录的东西：打断或纠正AI、拒绝某次工具调用，或AI反复重试出错的工具。又长又顺（工具调用很多但没有摩擦）的session不会触发；真正较劲过的session才会。达标后AI会显示如下英文提示：

[teamai] This session may contain a problem worth documenting: you interrupted the AI twice, the AI retried failing tools 8 times.

Task: Fix duplicate project-level Hook injection

Consider running /teamai-share-learnings to summarize what you learned and share it with your team.

提示会列出实际触发它的非零摩擦信号；如果能取得首个任务摘要，还会在脱敏、单行化后附上任务上下文。/teamai-share-learnings skill 自动总结 session 经验并推送到团队仓库。每个 session 最多提示一次。

团队知识检索

让AI在执行任务前自动检索团队积累的知识，该功能默认关闭，需显式开启。团队可在 teamai.yaml 设 sharing.recall.enabled: true 作为默认值，成员也可本地覆盖：

teamai recall enable     # 开启：部署 teamai-recall 子 agent + 注入引导规则
teamai recall disable    # 关闭：移除子 agent 和规则
teamai recall status     # 查看生效状态（团队默认 + 用户覆盖）

通过子Agent检索：开启后teamai pull会把内置teamai-recall子Agent部署到各AI工具的agents/目录。AI在任务开始前调用它，由子Agent提取关键词、执行检索、读取命中的源文件，最后返回结构化的团队知识摘要。子Agent会先做相关性预检（teamai recall --check），当任务与团队知识无关时直接跳过检索。子Agent底层调用的仍是teamai recall命令，也可手动直接运行：

$ teamai recall "port conflict"
[1/2] MR review caught a port-conflict bug ★1 [user]
Author: member-a | Score: 18.5 | Tags: troubleshooting, networking

[2/2] Deployment configuration best practices [project]
Author: member-b | Score: 12.0 | Tags: deploy, config
Matched: conflict | Missing: port

代码知识图谱

teamai import将源码仓库解析为teamwiki/下的结构化图谱，实现结构感知的检索：

teamai import --from-repo https://github.com/org/repo
teamai import --from-org myorg              # 批量导入所有仓库
teamai codebase --lint                      # 健康检查

图谱存储组件、接口、配置和跨仓库依赖边。teamai recall利用图谱进行增强排名。当召回命中codebase页面时，结果会附带一行Sources:，列出相关源文件路径，供Agent直接作为代码改动的入口，无需重新探索代码库。

依赖边来自两条并行的提取轨道，重叠时以AST结果优先：

• AST轨（TypeScript/JavaScript、Python、Go）：使用WASM版Tree-Sitter解析器，将import/require、调用点、以及 TS implements子句解析为精确的文件到文件DEPENDS_ON/REFERENCES/IMPLEMENTS边（标记为code-ast，带置信度权重）
• 启发式轨（所有语言，含Java/Rust）：基于正则的提取（标记为code-heuristic），同时覆盖AST轨未支持的语言。

WASM解析器是纯JavaScript依赖，无需任何原生编译工具链。若因任何原因加载失败，提取会降级到启发式轨并记录一条AST_UNAVAILABLE gap。设置TEAMAI_SKIP_AST=1可强制仅使用启发式提取。

命令一览

命令	说明
teamai init	初始化：OAuth登录、关联仓库、注册成员、注入钩子
teamai pull	拉取团队资源并注入到本地AI工具
teamai push	推送本地资源到分支并创建合并请求
teamai install [target]	安装团队npm包和Claude插件；带target时同步更新声明
teamai status	显示本地与团队仓库的差异
teamai contribute	将session经验分享到团队仓库
teamai recall <query>	搜索团队知识库（BM25+图谱增强）
teamai recall enable/disable/status	开关或查看recall状态
teamai recall promote [learningId]	将高置信度learning晋升为正式知识（skills/rules/docs）
teamai recall maintenance	维护知识库健康：清理低置信度learnings、回写置信度、标记过时条目
teamai import	导入知识（--dir、--from-repo、--from-org、--from-repo-list、--from-mr、--from-iwiki）
teamai codebase --lint	知识图谱健康检查
teamai ci extract-mr --url <url>	CI：从MR提取知识、发评论、合并后写入
teamai members	查看团队成员
teamai roles	管理团队角色和命名空间
teamai tags	管理基于标签的skill/rule过滤
teamai skill exclude add/remove/list	管理不参与本地同步的skills（使用指南）
teamai source	管理skill订阅源（其他团队或本团队公共仓库）
teamai remove <type> <name>	删除资源并创建MR
teamai session save	将脱敏后的session摘要记录到月度日志（--push可喂给digest）
teamai digest	生成团队周报
teamai doctor	诊断配置问题
teamai uninstall	移除所有teamai资源和钩子

实战

基于npm安装：npm install -g teamai-cli

基于源码部署：

git clone https://github.com/Tencent/teamai-cli.git
cd teamai-cli
npm install
npm run build # tsup打包
npm test # vitest
npm run test:e2e # e2e用例