TeamAI实战：统一团队AI工作流，彻底告别配置混乱与协作摩擦

上个月我们把 TeamAI 接进团队的 AI 工作流之后，解决了之前一直没找到好办法处理的几个问题：

◉

每个成员本地的 skills 和 rules 版本不统一，同一个需求在不同人那里跑出来的结果不一样。
◉

hook 配置靠口头同步，有人忘了配某个安全扫描脚本，那次差点把测试环境的密钥提交上去。
◉

新成员 onboarding 要手动把各种配置拷到本地，漏一步就要花时间排查。

TeamAI 的定位不是另一个 AI 编码工具。它把 skills、rules、docs、hooks 统一放在 Git 仓库里管理，然后分发给 Claude Code、Codex、CodeBuddy、Cursor 这些工具。成员每次开启会话，SessionStart hook 自动触发 teamai pull，把最新资源同步到本地。

这篇文章把配置流程和几个核心功能走一遍。

teamai init 接上团队仓库

团队里第一个人用的时候需要建一个仓库。可以在 teamai-hub 组织里找模板仓库点 “Use this template”，生成自己的仓库，然后执行：

teamai init https://github.com/yourorg/yourrepo

这条命令做三件事：OAuth 登录、关联仓库、把资源拉下来注入到本地 AI 工具。如果仓库还不存在，init 会自动创建。

团队成员加入指向同一个仓库就行。scope 默认是 project，资源装在当前项目目录下：

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

--scope user 装在用户目录，全局生效：

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

第三种是分层模式，项目 scope 保持当前配置，同时继承已初始化的 user scope 资源：

teamai init https://github.com/yourorg/project-repo --inherit-user-scope

项目 scope 的优先级高于 user scope，同名资源用 project 版本覆盖。

初始化完成后，每次 AI 会话启动，teamai pull 会被自动触发，不需要手动同步。

push 和 MR 走评审流程

修改了本地 skill 或 rule 之后，用 teamai push 提交：

teamai push

命令自动创建分支、提交变更、发起合并请求。reviewer 审批通过合并后，其他成员运行 teamai pull 才会拿到更新。

这个流程强制评审。之前遇到过直接 push 到主分支导致 hook 配置写错、所有人会话启动报错的情况，后来规定所有变更走 push + MR 流程，至少一个人 review。

hooks 配置统一分发

hooks 在 hooks/hooks.yaml 里声明，teamai pull 自动分发到各 AI 工具。

一个典型的密钥扫描 hook：

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

event: PreToolUse 加上 matcher: Bash，在 Bash 工具执行前触发。如果扫描脚本检测到密钥返回非零退出码，这次调用就被拦截。|| true 保证脚本非零时不阻断整个流程，只记录告警。

tools 字段指定这个 hook 只注入到 claude 和 cursor。不同 AI 工具的 hook 机制不一样，TeamAI 把声明转成各工具原生格式写入对应位置。

查看当前生效的 hooks：

teamai hooks list

重新注入或移除：

teamai hooks inject
teamai hooks remove

remove 只移除 teamai 管理的 hooks，手写的其他 hook 不受影响。

MCP Server 一次声明多工具同步

MCP 配置和 hooks 类似。mcp/mcp.yaml 里声明，teamai pull 按各工具原生格式写入：

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

密钥用环境变量引用，不写死在文件里。transport 支持 stdio、http、sse。

管理命令：

teamai mcp list
teamai mcp inject
teamai mcp remove

经验沉淀：摩擦信号触发记录

TeamAI 在 session 结束时通过 Stop hook 按摩擦信号评分。信号包括你打断 AI、纠正回复、拒绝工具调用、AI 反复重试失败的工具。

长 session 但一路顺畅、没有摩擦，不会触发。只有真正较劲过的 session 才会达标。

达标后 AI 显示一段英文提示，列出实际触发的信号和任务摘要。这时跑 /teamai-share-learnings，skill 自动总结 session 经验并推送到团队仓库。每个 session 最多提示一次。

分享的内容进入检索索引，后续其他成员遇到类似问题能用 teamai recall 搜到。标题、日期、作者、内容完全相同的条目自动去重，同一条 learning 分享两次不占两个名额。

知识检索：AI 主动查团队历史

recall 功能默认关闭，需要显式开启。团队在 teamai.yaml 设 sharing.recall.enabled: true 作为默认值，成员也可以本地覆盖：

teamai recall enable
teamai recall disable
teamai recall status

开启后 teamai pull 把 teamai-recall 子 agent 部署到各 AI 工具的 agents/ 目录。AI 在任务开始前调用它。子 agent 先做相关性预检，任务跟团队知识无关就跳过。

底层命令可以手动跑：

$ 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

第二条结果只命中了 “conflict” 没覆盖 “port”，输出里补一行 Missing: port。判断权留给调用方，recall 不过滤。

多 scope 情况：当前目录有 project scope 配置时先检索项目知识；如果项目启用了 --inherit-user-scope，再检索 user 知识并标注来源。同名条目 project 覆盖 user。当前目录没有 project 配置时只检索 user scope。

检索内容覆盖四类：learnings（session 经验）、docs（团队文档）、rules（编码规则）、skills（SKILL.md）。在 teamai pull 或 teamai contribute 时构建成 search-index.json。代码知识图谱由 teamai import 生成，检索时实时查询。

排序用 BM25 加图谱增强。当前 scope 的命中隐式投票，继承来的 user 命中只读。

代码知识图谱 import

teamai import 把源码仓库解析成图谱存在 teamwiki/ 下：

teamai import --from-repo https://github.com/org/repo
teamai import --from-org myorg

--from-org 批量导入组织下所有仓库。支持从 MR、iWiki 导入。

图谱存了组件、接口、配置和跨仓库依赖边。teamai recall 利用它做增强排名。命中 codebase 页面时，结果附带 Sources: 列出相关源文件路径，子 agent 直接当改动入口。

健康检查：

teamai codebase --lint

跨团队 skill 订阅

订阅其他团队的公开 skill 仓库：

teamai source add https://github.com/other-team/teamai-public.git --name other-team
teamai source list
teamai source browse other-team

browse 查看可用 skill，决定是否保留。移除订阅：

teamai source remove other-team

订阅的 skills 在 teamai pull 时自动同步到本地，同步的是 skill 定义，不是整个仓库。

其他日常命令

排除本地不需要的 skill：

teamai skill exclude add <skill-name>
teamai skill exclude list
teamai skill exclude remove <skill-name>

查看本地和团队仓库的差异：

teamai status

删除资源并创建 MR：

teamai remove <type> <name>

诊断配置问题：

teamai doctor

移除所有 teamai 资源和 hooks：

teamai uninstall

全局选项 --dry-run 和 --verbose 可以加在任意命令后面，先看执行计划再动手。

操作清单速览

操作	命令
首次接入团队仓库	`teamai init https://github.com/yourorg/yourrepo`
用户级安装	`teamai init <repo> --scope user`
分层继承	`teamai init <repo> --inherit-user-scope`
提交变更	`teamai push`
手动拉取更新	`teamai pull`
查看 hooks	`teamai hooks list`
注入 hooks	`teamai hooks inject`
移除 hooks	`teamai hooks remove`
查看 MCP	`teamai mcp list`
开启 recall	`teamai recall enable`
关闭 recall	`teamai recall disable`
检索知识	`teamai recall "query"`
导入代码图谱	`teamai import --from-repo <url>`
订阅外部 skill	`teamai source add <repo> --name <name>`
诊断	`teamai doctor`

FAQ

teamai init 和 teamai pull 的区别是什么？

init 做初始化：OAuth 登录、关联仓库、注册成员、注入 hooks。pull 只拉取资源并注入到本地 AI 工具。init 会执行一次 pull，后续更新只用 pull。

project scope 和 user scope 选哪个？

项目 scope 把资源装在项目目录下，不同项目可以用不同配置。user scope 装在用户目录全局生效。如果多个项目共用同一套 rules 和 hooks，user scope 更省事。如果每个项目有独立规范，用 project scope。

–inherit-user-scope 是什么场景用的？

项目有自己的一套配置，但想继承 user scope 里的安全资源（比如密钥扫描 hook）和可检索知识。project 优先级更高，同名资源用 project 版本。

recall 为什么默认关闭？

子 agent 会在任务开始前额外执行一次检索，增加 token 消耗和响应延迟。团队评估过知识检索带来的收益大于成本之后再开启更合适。

teamai push 和直接 git push 有什么区别？

push 自动创建分支和 MR，走评审流程。直接 git push 绕过评审，变更可能未被 review 就合入。如果团队有 CI 检查 MR 的流程，push 能保证每条变更都经过检查。

跨团队订阅的 skill 会占用本地空间吗？

同步的是 skill 定义文件（SKILL.md 和关联脚本），不是整个仓库。占用空间不大。不想用了执行 teamai source remove <name> 移除。

移除 teamai 之后原来的 hooks 还在吗？

teamai uninstall 只移除 teamai 管理的 hooks。手写的 hook 配置不会动。如果不确定，先跑 teamai hooks list 看哪些是 teamai 注入的，再决定是否 uninstall。