第一次使用TeamAI：新手必看的10件事与常见坑清单

第一次使用TeamAI新手必看的10件事与常见坑清单【免费下载链接】teamai-cliMake Every Team AI Native项目地址: https://gitcode.com/GitHub_Trending/te/teamai-cliTeamAIteamai-cli是一款免费的团队级 AI 协作 CLI 工具口号是 Make Every Team AI Native。它把一个 Git 仓库变成团队的共享大脑统一分发 Skills、Rules、MCP、文档和知识库并自动同步到 Claude Code、Codex、Cursor、CodeBuddy 等 AI 编程助手让团队每个人的 Agent 都站在同一份团队经验上工作。本文带你按顺序完成第一次使用最后附一份高频踩坑清单。完整文档见 docs/usage-guide.zh-CN.md英文版本见 docs/usage-guide.md。第1件一键安装 TeamAI CLI前提Node.js ≥ 20、Git 已安装。npm install -g teamai-cli teamai --version # 验证安装一行命令装完无需注册账号。它是纯本地 CLI团队数据只在你自己的 Git 托管平台GitHub、GitLab、GitCode、CNB、TGit 或自建 Git 服务上。第2件先搞懂「团队仓库」这个核心概念TeamAI 的一切围绕一个Team Repo团队仓库展开skills/团队技能AI 可调用的目录含 SKILL.mdrules/团队规范自动合并进 AI 工具配置docs/共享文档env/共享环境变量learnings/团队知识库大家的经验沉淀成员之间靠push → MR 评审合并 → pull的 Git 流程流转资源天然有版本、有评审、可回滚。第3件选择 Scope项目级 vs 用户级teamai init时最关键的决策是资源装到哪里维度Project Scope默认User Scope安装位置当前项目目录下用户主目录~/下适用场景项目特定的技能和规则跨项目的通用团队规范# 项目级默认在项目根目录执行 cd /path/to/my-project teamai init https://your-git-host/yourorg/yourteam-repo # 用户级 teamai init https://your-git-host/yourorg/yourteam-repo --scope user新手建议单人或单一项目用默认 project scope 即可两个 scope 也可以共存详见第 7 个坑。第4件记住「每次开 AI 会话自动同步」初始化后 TeamAI 会向你的 AI 工具注入 Hooks每次启动 AI 会话都会自动执行teamai pull把最新的团队 skills/rules 拉到本地无需手动操作。需要立即同步时可以手动执行teamai pull # 手动拉取 teamai pull --dry-run # 试运行不实际修改⚠️ 自动同步依赖工具的生命周期 Hooks 支持Claude Code、Codex、Cursor、CodeBuddy 等。暂不支持 Hooks 的工具需要在终端手动执行teamai pull。第5件用 status 和 list 建立「体检习惯」teamai status # 当前 scope、同步时间、资源统计 teamai list # 全部资源类型skills/rules/docs/env/agents/hooks/mcp teamai skill show name # 查看某个 skill 的来源、贡献者、安装位置养成遇到问题先teamai status的习惯80% 的新手疑惑都能直接看出来。第6件push 是把资源分享给团队的正确姿势自己写了新 skill 或 ruleteamai push # 扫描新增/修改的资源创建 MR注意两个设计细节push 走的是MR 流程团队管理员评审合并后才对全员生效已有未合并的 PR 时再次 push 会就地更新那个 PR不会重复创建。推送时SKILL.md缺失的name/descriptionfrontmatter 会被自动补全。第7件recall 检索团队知识团队知识库learnings不是摆设——AI 可以直接检索teamai recall API 超时 teamai recall GPU 内存不足teamai recall --check 关键词提供轻量相关性预检供 subagent 判断是否值得检索。知识库里低置信度、过时的内容可以用teamai recall maintenance定期清理高价值经验可用teamai recall promote提升为正式规则或技能。第8件contribute 把踩过的坑变成团队资产当你和 AI 的会话中踩了坑、被反复纠正TeamAI 会基于摩擦信号提醒你沉淀经验会话越长越顺反而不触发。手动方式teamai contribute --file /tmp/session.md内置的 teamai-share-learnings 技能 会指导 AI 帮你把经验整理成结构化 learning。仓库根目录learnings/对全团队共享多项目场景下learnings/project-id/子目录仅该项目可见。第9件了解三种进阶模式按需选单仓模式teamai init .让业务仓库自己充当团队仓库clone 即自动初始化适合小团队零成本起步HTTP 只读模式teamai init --http host --token key无需 git 权限只消费 skills/rules角色与标签teamai roles/teamai tags让不同职能的成员只同步自己需要的 skills管理员一次配置、全员生效。Git 平台适配细节见 docs/providers.md。第10件出问题先跑 doctorteamai doctor # 配置与环境诊断 teamai hooks inject # Hooks 丢失时重新注入teamai doctor会检查运行环境、hooks 状态、声明的包与插件是排障第一站。️ 新手常见坑清单#症状原因与解法1init提示「已初始化」交互模式下输入y覆盖或加--force跳过确认2init 后项目里没有.claude/目录预期行为init 不知道你开哪个 Agent首次用 Claude Code 打开项目时才会自动创建该目录并 pull3Hooks 没有自动触发依次执行teamai doctor诊断 teamai hooks inject重新注入4push 提示 no new resources detected正常——push 只检测新增或修改的资源无变更就无需推送5想删除已推送的资源用teamai remove skills name或teamai remove rules name别直接删本地文件6个人不想要某个共享 skillteamai skill exclude add nameteamai pull仅本地排除不影响他人7用户级和项目级资源打架两者可共存当前目录有 project 配置时以 project 优先需要组合时加--inherit-user-scope8单仓模式下把密钥写进env.yaml⚠️ 该文件会提交到 main 分发给所有人只放非敏感配置密钥留在本机环境9改了 skill 扩展名后 pull 冲突重命名如.md→.yaml需手动删除旧文件push 不会替你删10老版本升级后行为异常升级后首次init/pull/push会自动迁移旧.teamai/目录保留.teamai.bak/供回滚迁移后不要降级新手上手路径总结npm install -g teamai-cli → teamai init 团队仓库地址 → 打开 AI 工具自动 pull → teamai status 确认 → teamai push 分享第一个 skill → teamai recall 检索团队知识按这个顺序走完你就从个人使用 AI 升级为「团队 AI 原生」工作了。祝上手顺利【免费下载链接】teamai-cliMake Every Team AI Native项目地址: https://gitcode.com/GitHub_Trending/te/teamai-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考