teamai-cli 安装与初始化教程：npm 安装、建仓、团队接入全流程

这个教程解决什么问题

读完这篇你能做到：装好 teamai-cli、理解管理员与成员两种角色分工、完成仓库初始化、让团队成员全部接入。整个过程不复杂——本质上是「建一个 Git 仓库 + 跑两条命令」——但角色分工和仓库托管平台的选择需要先搞清楚。

Node.js 18 或更高版本（node -v 确认）
一个 Git 托管平台账号。teamai-cli 支持三类托管平台：GitHub、TGit（腾讯内网）、CNB——官方也贴心地区分了企业用户和个人开发者的路径
Git 已安装并配置好对应平台的访问凭证

npm install -g teamai-cli
teamai --version

全局安装后确认版本号正常输出即可。如果 npm 全局目录有权限问题（Linux/macOS 常见），用 npm config get prefix 检查全局路径是否可写，或改用 nvm 管理的 Node 环境。

teamai-cli 的接入流程分管理员和成员两条线，先分清楚你是什么角色：

角色	干什么	用哪条命令
管理员	创建团队仓库，成为第一个接入者	`teamai init <org>/TeamAi-<团队名>`
成员	接入已有仓库	`teamai init <仓库地址>`

管理员路径（GitHub/TGit/CNB）：先在托管平台上手动创建一个空仓库，官方建议命名 TeamAi-<团队名>（例如 TeamAi-Backend），然后在本地执行：

teamai init your-org/TeamAi-Backend

个人开发者路径：init 时指定的仓库不存在也没关系——teamai-cli 会自动创建仓库，不需要提前去网页上建。个人用户一条命令即可起步，这也是官方推荐个人开发者的方式。

用户级模式：如果想让配置作用于你的用户目录（对个人所有项目生效，而不是某个项目），init 时加 --scope user 参数。团队场景默认项目级，个人统一工具配置用 user 级。

管理员 init 完成后，把仓库地址发给团队成员。每个人只需要两条命令：

npm install -g teamai-cli
teamai init your-org/TeamAi-Backend

init 过程中 teamai 会拉取仓库内容，把 Skills、Rules、MCP 等配置分发到本机各 AI 工具的对应目录。成员执行完，打开 Claude Code 或 Cursor 就能看到团队共享的技能了。

权限说明：默认情况下普通成员只读仓库——只能 pull，不能 push。这是刻意设计：配置的分发要走审核流程（下一节讲 push 时展开）。需要写权限的成员由仓库管理员在托管平台侧授权。

init 完成后用这几条命令确认状态：

# 查看当前接入的仓库与同步状态
teamai status

# 列出所有已安装的技能
teamai list

# 查看某个技能的详情
teamai skill show <技能名>

teamai status 是日常最常用的健康检查——本地与远端是否有差异、哪些文件会被同步，一眼看清。

init 时认证失败：Git 凭证问题。GitHub 用户确认 gh auth status 或 SSH key 配置正确；TGit/CNB 用户确认平台 token 有效。

init 后工具里看不到 Skills：检查是否装了对应的 AI 工具（比如团队仓库里有 Claude Skills 但你本地没装 Claude Code），以及 --scope 参数是否用对——项目级和用户级的分发目录不同。

公司网络拉取 GitHub 仓库超时：企业内网环境走 TGit/CNB 托管路线，这正是 teamai-cli 支持多平台的意义。

本篇涉及的命令按使用顺序整理，接入阶段照着查即可：

命令	作用	说明
`node -v`	确认 Node 版本	需要 18 或更高版本
`npm install -g teamai-cli`	全局安装 CLI	Linux/macOS 留意全局目录权限
`teamai --version`	确认安装成功	正常输出版本号即可
`teamai init your-org/TeamAi-Backend`	管理员初始化	仓库需先在 GitHub/TGit/CNB 手动创建
`teamai init my-name/TeamAi-Personal`	个人开发者起步	仓库不存在会自动创建
`teamai init <仓库地址>`	成员接入已有仓库	配置自动分发到本机各工具目录
`teamai init <仓库> --scope user`	用户级模式	配置作用于个人所有项目
`teamai status`	查看接入与同步状态	接入后第一时间的健康检查
`teamai list`	列出已安装的技能	确认分发结果
`teamai skill show <技能名>`	查看技能详情	描述与适用范围一目了然
`gh auth status`	检查 GitHub 认证	init 失败时先查这条

三种接入路径的差异汇总：

两张表合起来的用法：先按路径对号入座，再按命令逐行执行。接入是一次性动作，命令不需要背——记不清参数时，任何子命令加 --help 都能看到说明，这是 npm CLI 的通用约定。

init 之前把这几项过一遍——接入阶段的大多数失败都出在下面这几条：

Node 版本达标：版本低于 18 时 npm 安装可能照常成功，问题会拖到运行时才暴露。node -v 十秒钟的事，别省。
Git 凭证先配好：init 要拉取（或创建）远端仓库，凭证缺失时的报错不一定指向认证问题。GitHub 用户用 gh auth status 或 SSH 连通性自测，TGit/CNB 用户确认平台 token 有效。
命名走统一前缀：组织里多个团队各建配置仓库时，TeamAi-<团队名> 前缀让「哪些是 teamai 配置仓库」一眼可辨，日后检索和权限管理成本最低。
scope 想清楚再装：用户级（--scope user）和项目级的分发目录不同，装错了要重走一遍接入。个人统一工具配置用 user 级，团队协作保持默认的项目级。
别用 sudo 装全局包：sudo npm install -g 能解一时权限之痛，但会把全局目录所有权搞乱，后续每次安装升级都被迫 sudo。权限报错时优先用 npm config get prefix 查全局路径，或改用 nvm 管理的 Node 环境。
确认目标工具已安装：teamai 负责把配置分发到各 AI 工具的目录，工具本身（Claude Code、Cursor 等）得先在你机器上——init 成功却看不到 Skills，多半卡在这一条。

仓库通了、配置同步了，建议立刻做两件事：

把你自己机器上已有的好 Skills 捐进团队仓库——用 teamai push 提交（流程见日常使用篇），这是仓库从空到有的第一桶金
配置 SessionStart Hook 自动同步——让 Claude Code 每次会话启动时自动 pull 最新配置，从此「忘更新配置」这个问题不存在了

团队接入只是起点，配置资产的日常运营——push、pull、审核、回滚——才是长期价值所在。