TeamAI CLI 详细部署教程

1. 项目简介

TeamAI CLI 是腾讯开源的团队级 AI 编程助手管理工具，核心目标是让整个团队的开发规范同步到每个程序员的 AI 编程助手中。它将团队的 Skills、Rules、Docs、MCP 服务器和环境配置全部收敛到一个 Git 仓库，团队成员只需运行一次初始化命令，此后每次启动 AI 编程助手都会自动拉取最新配置。

核心特性：

  • Git 原生分发：所有配置通过 Git 管理，天然支持分支、PR、Code Review，可追溯每一条规则的修改历史
  • 多 Agent 统一配置：同一套配置同步到团队所有成员使用的不同 AI 编程助手
  • 自动拉取更新：利用 SessionStart hook，每次启动 AI session 自动执行 teamai pull，团队规范实时保持最新
  • 角色与标签过滤：通过 teamai roles 和 teamai tags 控制不同成员只看到自己需要的 skills，避免信息过载
  • 团队知识沉淀：内置 Team Context 功能，agent 可调用 recall/teamwiki 等工具，将团队知识沉淀为可检索资产
  • 经验自动分享：会话结束时根据摩擦信号（friction）自动评分，高分会话会提示用户分享经验

支持的 AI Agent：

Agent Harness Knowledge Base Analytics
Claude Code ✓ ✓ ✓
Codex ✓ ✓ ✓
Cursor ✓ ✓ ✓
CodeBuddy ✓ ✓ ✓
OpenCode ✓ — —
WorkBuddy ✓ ✓ ✓
OpenClaw ✓ ✓ —
Hermes ✓ ✓ —
DeepSeek Harness ✓ ✓ —

Git 托管平台支持： GitHub、GitLab、GitCode、CNB、TGit 或私有 Git 服务。

2. 部署前准备

2.1 环境要求

根据官方文档，部署需要满足以下条件：

  • Node.js：≥ 18
  • Git：已安装
  • TGit 用户：还需安装 gf CLI
  • CNB 用户：还需安装 cnb CLI

说明：teamai init 时会自动安装所需的 CLI 工具。

2.2 验证环境

1
2
node --version
git --version

2.3 安装方式选择

方式 适用场景 优势
npm 全局安装 常规使用 一行命令完成
指定 registry 安装 企业内网 使用腾讯内网源

3. 安装步骤

3.1 npm 全局安装

打开终端，执行以下命令：

1
npm install -g teamai-cli

3.2 企业内网安装（可选）

如果处于腾讯内网环境，可以使用内网 registry 安装：

1
npm install -g @tencent/teamai-cli --registry=http://r.tnpm.oa.com

3.3 验证安装

1
teamai --version

如果显示版本号，说明安装成功。

4. 团队管理员初始化

如果你是新团队的管理员，需要先创建团队共享仓库，然后完成初始化。只需一位管理员完成，其他成员可直接跳到第 5 节。

4.1 创建团队仓库

在 Git 托管平台（GitHub、GitLab、GitCode、CNB、TGit 或私有 Git 服务）创建一个空仓库，命名建议为 TeamAi-<团队名>，并授予团队成员写权限。

可选：也可以从 teamai-hub 模板组织起步，该模板内置了成套 skills、rules、review agents，点击 “Use this template” 生成自己的仓库后直接执行初始化。

4.2 项目级初始化（默认）

资源安装到项目目录下（<project>/.claude/skills/ 等），适用于项目特定的技能和规则：

1
2
cd /path/to/my-project
teamai init https://github.com/yourorg/yourrepo

生成的目录结构：

text

1
2
3
4
5
6
7
/path/to/my-project/
├── .teamai/                     # 项目级配置
│   ├── config.yaml
│   └── team-repo/
├── .claude/skills/              # 项目级 skills（自动同步）
├── .claude/rules/               # 项目级 rules（自动同步）
└── src/

4.3 用户级初始化（可选）

资源安装到用户主目录（~/.claude/skills/ 等），适用于通用团队规范和跨项目技能：

1
teamai init https://github.com/yourorg/yourrepo --scope user

用户级初始化的目录结构：

text

1
2
3
4
5
6
7
8
9
~/.teamai/
├── config.yaml          # 本地配置
├── team-repo/            # 团队仓库克隆
│   ├── teamai.yaml      # 远程团队配置
│   ├── skills/ rules/ docs/ env/ members/
│   ├── manifest/roles.yaml
│   └── learnings/       # 团队知识库
~/.claude/skills/        # 团队 skills（自动同步）
~/.claude/rules/         # 团队 rules（自动同步）

4.4 非交互式初始化（CI/CD 场景）

适合 CI/CD 或 AI agent 自动化场景：

1
teamai init <group>/TeamAi-<team> --scope project --role hai_dev --force

参数说明：

参数 说明
[repo] / --repo <url> 团队仓库地址
`–scope <project user>`
--role <id> 直接指定 primaryRole，跳过角色交互选择
--force 覆盖已有配置，跳过确认提示

4.5 单仓库模式（业务仓库即团队仓库）

如果你希望将现有项目的 Git 仓库直接作为团队仓库，可以在项目内运行：

1
2
cd /path/to/my-project
teamai init . --agent claude,codex

选择要设置的 AI 工具：

  • --agent <name...>：显式列表，支持 claude、codex、cursor、codebuddy、workbuddy、dsh
  • 交互模式：显示多选菜单
  • 非交互模式：自动镜像已安装的 AI 工具

数据分支拆分：

数据类型 位置 随 git clone 传播
知识（skills/rules/docs/learnings） 主分支 .teamai/ ✅ 是
报告（members/sessions/votes/stats） teamai-reports 孤儿分支 推送到 origin
机器本地（config/token/state） .teamai/（gitignored） ❌ 否

5. 团队成员接入

团队成员只需执行一次初始化命令，之后每次 AI session 启动时都会自动拉取管理员发布的最新资源。

5.1 项目级接入

1
2
cd /path/to/my-project
teamai init https://github.com/yourorg/yourrepo

5.2 克隆即初始化

因为知识和 mode: self 标记已提交到主分支，克隆仓库的成员会自动初始化：下一次 teamai 命令或 AI session 检测到标记后，会自动写入本地配置、注入 hooks 并注册到 reports 分支。

6. 核心功能使用

6.1 Harness 管理与分发

TeamAI 通过“push → review & merge → pull”流程分发配置：

text

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

推送变更：

1
teamai push

拉取更新： 每次 AI session 启动时自动执行，无需手动操作。

6.2 技能订阅源

订阅其他团队或组织内的共享技能仓库：

1
2
3
4
5
6
7
8
9
10
11
# 添加订阅源
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

添加/移除立即在本地生效，订阅的 skills 会在下次 teamai pull 时同步。

6.3 团队包管理

共享和恢复团队的 npm 包及 Claude Code 插件：

1
2
3
4
5
6
7
# 安装单个包
teamai packages install typescript
teamai packages install typescript@5.9.2 --npm
teamai packages install code-review@claude-plugins-official

# 安装团队声明的所有包
teamai packages

6.4 团队知识召回

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

1
2
3
4
5
6
7
8
# 启用召回
teamai recall enable

# 禁用召回
teamai recall disable

# 查看当前状态
teamai recall status

手动搜索：

1
teamai recall "port conflict"

召回结果会带有 [type] 标签，标识知识来源：

类型 来源
[learnings] ~/.teamai/learnings/*.md
[docs] 团队仓库 docs/**/*.md
[rules] 团队仓库 rules/**/*.md
[skills] 团队仓库 skills/<name>/SKILL.md

6.5 自动经验分享

会话结束时，Stop hook 会根据摩擦信号（你打断或纠正 AI、拒绝工具调用、AI 重试失败工具）对会话评分。评分足够高时，AI 会提示：

text

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

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

你可以运行 /teamai-share-learnings 将经验总结推送到团队仓库。团队可以通过 sharing.contributeHint.enabled: false 关闭此提示。

6.6 代码知识图谱（teamwiki）

解析源码仓库并生成结构化知识图谱：

1
2
3
teamai codebase --extract
# 或
teamai import --from-repo

生成的目录结构：

text

1
2
3
4
teamwiki/
├── router.md               # 导航中心
├── index.md                # 全局索引
├── hot.md

7. 分发控制

管理员可配置团队级设置，随 teamai pull 分发给每位成员：

能力 命令 作用
角色（Roles） teamai roles 定义「角色 → 命名空间」映射，让每位成员只同步与自身角色匹配的 skills
标签（Tags） teamai tags 给 skills/rules 打标签，成员只订阅自己需要的标签
订阅源（Sources） teamai source 订阅额外的 skill 仓库

8. 常见问题与解决方案

8.1 初始化时仓库不存在

问题：运行 teamai init 时提示仓库不存在。

解决方案：确保仓库已创建并授予了写权限。也可以直接运行 teamai init，不存在时会提示自动创建。

8.2 角色交互选择卡住

问题：仓库启用了角色化 skills（存在 manifest/roles.yaml），初始化时要求交互式选择角色。

解决方案：使用 --role <id> 参数跳过交互选择。

8.3 项目里没有 Agent 根目录

问题：teamai pull 跳过了某些工具。

解决方案：这是正常行为。各 Agent 的项目根目录（.claude/、.cursor/ 等）会在 SessionStart 时按刚打开的工具创建。单独执行 teamai pull 仍会跳过项目里还不存在根目录的工具，因此不会给尚未在本项目打开过的 Agent 凭空建目录。

8.4 召回功能无效

问题：启用召回后 AI 没有使用召回功能。

解决方案：检查 teamai recall status 查看有效状态。注意团队默认值和用户覆盖的关系：用户配置（~/.teamai/config.yaml 中的 recallEnabled）优先级高于团队默认值。也可以通过环境变量 TEAMAI_RECALL_DISABLED=1 强制禁用所有召回 hooks。

8.5 Windows 环境问题

问题：Windows 上 home 目录解析错误。

解决方案：项目在 releases 中已修复多个 Windows 相关问题，包括通过 getUserHome 解析用户 home 目录、使用 fileURLToPath 解析内置 agents 目录等。确保使用最新版本。

9. 注意事项

根据官方文档，使用时请注意：

  • env.yaml 存储明文：在单仓库模式下，.teamai/env/env.yaml 会提交到主分支，因此会传播给所有克隆仓库的人。只存放非机密的共享配置，真实机密应保存在自己的未跟踪环境中
  • 单仓库模式限制：将一个团队设置绑定到一个业务仓库。如果需要在多个业务仓库间共享团队知识库，应使用独立团队仓库
  • Agent 文件重命名：如果重命名 agent 的扩展名（如 helper.md → helper.yaml），需要删除旧文件，否则两个同名 stem 的文件会在 pull 时冲突
  • 安全修复：项目在 releases 中修复了多个安全问题，包括 scp 风格凭证泄露、simple-git RCE 等，建议使用最新版本

10. 部署架构总结

部署方式 适用场景 初始化命令 特点
项目级 项目特定技能和规则 teamai init <repo> 资源安装到项目目录
用户级 通用团队规范 teamai init <repo> --scope user 资源安装到 ~/
单仓库模式 业务仓库即团队仓库 teamai init . --agent claude,codex 无需独立团队仓库
组织+项目双层 组织级+项目级知识 先 user 后 project + --inherit-user-scope 支持知识继承

TeamAI CLI 的部署核心是安装 npm 包并完成一次 teamai init 初始化。管理员负责创建团队仓库并发布配置，成员只需运行一次初始化命令，之后每次 AI session 启动时会自动拉取最新规范。该工具将团队 AI 配置的管理从“散落在各人本地”转变为“Git 仓库集中管理、Code Review 审核、自动同步分发”的模式，适合希望统一团队 AI 编程规范的工程团队使用。