TeamAI CLI 部署与使用教程

TeamAI 是一款由腾讯开发的开源 CLI 工具，旨在帮助团队统一管理 AI 编程助手（如 Claude Code、Codex、Cursor 等）的技能、规则、MCP 和知识。通过一个共享的 Git 仓库，实现团队 AI 工作流的标准化和知识沉淀。本教程将指导你完成从安装到团队使用的全过程。

一、核心概念与架构

TeamAI 围绕三个核心层级构建，让团队从“用 AI”进化到“让 AI 按团队方式工作”：

层级	目标	核心功能
Team Execution (团队执行)	让每个 AI 代理按团队方式工作	通过 `init/pull/push` 同步技能(skills)、规则(rules)、代理(agents)、钩子(hooks)、MCP 和环境变量。
Team Context (团队上下文)	让每个 AI 代理理解团队	包含自动经验分享(learnings)、知识库检索(recall)和代码库图谱(codebase graph)。
Team Improvement (团队改进)	让每次执行改进团队	通过使用统计(digest)、会话分析(sessions)和仪表盘(dashboard)驱动持续优化。

工作流程：管理员将团队资源推送到 Git 仓库 -> 成员通过 teamai pull 同步到本地 AI 工具 -> AI 会话自动应用这些配置。成员的经验可通过 /teamai-share-learnings 技能沉淀回团队知识库。

二、部署步骤

步骤 1：安装 TeamAI CLI

全局安装 (推荐)

1	npm install -g teamai-cli

安装完成后，可通过 teamai --version 验证。

步骤 2：准备团队共享仓库

创建仓库：在 GitHub、GitLab、GitCode 等 Git 服务上创建一个新仓库，用于存放团队的 AI 配置文件。
获取模板（可选）：访问 teamai-hub 组织，浏览预置了生产级技能和规则模板。点击 “Use this template” 快速生成包含最佳实践的仓库。
权限设置：确保所有团队成员对该仓库有写入权限。

步骤 3：管理员/独立用户初始化

1. 初始化本地环境

1 2	# 将 yourrepo 替换为你的团队仓库地址 teamai init https://github.com/yourorg/yourrepo

此命令会引导你完成 OAuth 登录、链接团队仓库并注册为团队成员。

步骤 4：团队成员初始化

团队成员在各自的项目或用户目录下初始化，拉取团队配置。

项目级初始化 (推荐，配置仅当前项目生效)

1
2
3

cd /path/to/your/project
teamai init https://github.com/yourorg/yourrepo
# 默认 --scope project，会在项目目录下创建 .claude, .codex 等目录

用户级初始化 (配置对当前用户的所有项目生效)

1 2	teamai init https://github.com/yourorg/yourrepo --scope user # 配置会安装到 ~/.claude, ~/.codex 等用户目录

初始化后，TeamAI 会自动注入钩子(Hooks)，确保每次 AI 会话启动时自动执行 teamai pull，同步最新的团队配置，无需手动操作。

三、核心团队协作工作流

3.1 分享新技能或规则 (Push 流程)

当你想为团队贡献一个新的技能(skill)或规则(rule)时：

添加资源：在本地 ~/.teamai/ 或项目 .teamai/ 目录下创建或修改相应的技能/规则文件。
推送变更：
1
teamai push
此命令会创建一个新分支并打开一个合并请求(MR/PR)供审核。
审核与合并：团队其他成员审阅 MR，通过后合并到主分支。
自动同步：其他成员在下次启动 AI 会话时，钩子会自动执行 teamai pull 拉取更新。成员也可手动运行 teamai pull 立即同步。

3.2 使用团队 MCP 服务器

在团队仓库的 mcp/mcp.yaml 中声明 MCP 服务器：

servers:
  - name: gpu-analysis
    transport: http
    url: https://example.com/api/mcp
    headers:
      Authorization: Bearer ${GPU_ANALYSIS_TOKEN} # 使用环境变量保护敏感信息

成员运行 teamai pull 后，这些 MCP 配置会自动写入各 AI 工具（如 Claude Code、Cursor）的本地配置文件中。相关命令：

teamai mcp list # 查看当前生效的 MCP
teamai mcp inject # 手动重新注入配置

3.3 管理订阅源 (Source)

团队可以订阅其他团队或公共的 Skill 仓库：

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

添加后，下次 teamai pull 会自动同步订阅源的技能。

3.4 安装团队包 (Package)

共享和管理团队的 npm 包或 Claude Code 插件：

teamai install typescript           # 安装并声明为团队依赖
teamai install code-review@claude-plugins-official
teamai push                         # 分享声明文件
# 其他成员运行以下命令安装所有声明的包
teamai install

四、高级功能：团队上下文与改进

4.1 启用团队知识召回 (Recall)

让 AI 在任务开始前自动搜索团队积累的知识。此功能默认关闭，需要主动启用。

管理员：可在 teamai.yaml 中设置 sharing.recall.enabled: true 作为团队默认值。
成员：可在本地覆盖设置。

1
2
3

teamai recall enable   # 启用：部署 recall 子代理并注入规则
teamai recall disable  # 禁用
teamai recall status   # 查看当前状态

启用后，teamai pull 会部署内置的 teamai-recall 子代理。AI 会在执行任务前调用它，搜索知识库并返回结构化摘要。

4.2 导入代码库知识图谱

teamai import 命令解析代码仓库，构建结构化知识图谱，增强召回效果。

# 导入单个仓库
teamai import --from-repo https://github.com/org/repo
# 导入组织下的所有仓库
teamai import --from-org myorg
# 检查知识图谱健康度
teamai codebase --lint

该图谱存储组件、接口、配置及跨仓库依赖关系，使 teamai recall 能进行图增强的检索排序。

4.3 查看团队使用情况

生成周报：teamai digest 生成包含 token 使用量、对话量和干预率的团队周报。
查看仪表盘：teamai dashboard 启动 Web 仪表盘，实时查看成员编码状态、干预次数和 token 使用情况，以及知识库健康度。

五、常用命令速查

命令	说明
`teamai init <repo-url>`	初始化团队仓库
`teamai pull`	拉取并注入最新团队配置
`teamai push`	推送变更并创建 MR
`teamai status`	显示本地与团队仓库的差异
`teamai recall <query>`	手动搜索团队知识库
`teamai install [target]`	安装团队声明的包
`teamai source add/remove/list`	管理 Skill 订阅源
`teamai mcp list/inject/remove`	管理 MCP 服务器
`teamai roles` / `teamai tags`	管理角色和标签过滤
`teamai doctor`	诊断配置问题
`teamai uninstall`	移除所有 TeamAI 资源

六、部署清单

步骤	操作	关键点
1. 安装 CLI	`npm install -g teamai-cli`	确保 Node.js 环境
2. 准备团队仓库	在 Git 平台创建仓库，获取权限	成员需有写权限；可从模板创建
3. 初始化	`teamai init <repo-url>`	管理员和成员均需初始化，注意 `--scope`
4. 配置与推送	添加技能/规则，运行 `teamai push`	遵循“审查-合并”流程
5. 成员同步	运行 `teamai pull` 或启动 AI 会话	钩子会自动同步
6. (可选) 启用高级功能	启用 `recall`，导入知识图谱	提升 AI 上下文理解能力