腾讯开源 teamai-cli 深度拆解：9 款 AI 编码 Agent 统一管理、Git 原生团队级 Skill/Rules/MCP/Hooks 分发 + 知识库召回

腾讯开源 teamai-cli 深度拆解：9 款 AI 编码 Agent 的团队级统一 Harness

团队里每个人装的 Claude Code / Codex / Cursor / CodeBuddy 各写各的？Skill、规则、MCP 服务器各配各的？这篇看完知道怎么管。

本文提纲

  1. 问题：为什么 10 人团队用 AI Agent，3 个月后 Skill、规则、MCP 配置会全面分裂
  2. teamai-cli 项目档案：695 stars、TypeScript、npm 全局安装、2026.4 启动
  3. 一表看懂支持范围：9 款 Agent × 13 项能力（Harness 7 项 + KB 3 项 + Analytics 3 项）
  4. Git 原生分发模型：teamai push → MR → merge → teamai pull（会话启动自动同步）
  5. 团队级三大管控：Roles 按岗位同步、Tags 按主题订阅、Sources 跨团队订阅
  6. 团队 Hooks 事件系统：PreToolUse 拦截、工具匹配器、秘密扫描实际案例
  7. 团队级 MCP 服务器统一配置：一次声明，9 款工具各自写入原生格式
  8. 团队知识库三支柱：摩擦信号触发 Learnings 分享、Recall 子agent 自动召回、Codebase AST 依赖图
  9. Analytics 三件套：Weekly Digest、Privacy-Scrubbed Session、Dashboard
  10. 完整命令清单（20+）和 TheAIEra 团队落地建议
  11. 横向对比：Claude Code 原生 / Hermes Skill 体系 / teamai-cli 的适用场景

先给结论，再展开。teamai-cli 解决的是一个"团队规模到 10 人以上才会遇到"的问题。

  • 1-2 个人用 Claude Code：自己在 ~/.claude/skills/ 丢 5 个 Skill，AGENTS.md 写两句 rules，够用。
  • 5-8 人的小团队：口口相传 Skill 文件，建一个群里分享 zip，勉强能跑。
  • 10 人以上、跨多个 AI 工具（有人用 Claude Code、有人用 Codex、有人用 Cursor、有人用 CodeBuddy、有人公司内部 WorkBuddy）：分裂就在 3 个月内发生——
现象 结果
A 同学的 react-tsx-review Skill 是 v3 版，B 同学是 v1 版 同一个 review 任务，两个人的 Agent 输出规则不一样
Ops 组配了 k8s-deploy Skill，Dev 组没人知道 重复造轮子，质量还参差不齐
新入职同学花 3 天手动配每个工具的 Skill、Rules、MCP 配置成本直接变成 onboarding 第一道坎
有人在本项目的 .claude/AGENTS.md 写了一条项目规则，换 Codex 不生效 Agent 换了一个，团队沉淀全丢
全公司就一个内部 MCP 服务器地址，9 款工具的配置文件格式 9 种，每种都手动写 配置文档变成了运维噩梦
团队有人踩过一个坑，写了笔记，但新的 Agent 做任务时根本看不到 经验散落在 Notion，不复用，还重复踩

teamai-cli 就是为这个场景设计的：把所有 AI 编码 Agent 的共享资源（Skill/Rules/Docs/Env/Agents/Hooks/MCP/Learnings/CodebaseWiki/TeamWiki）放进一个 Git 仓库，管理员 merge 一次，所有成员下次开 AI 会话时自动同步到本地对应工具的目录里。

你甚至可以把它理解成"团队级 AI Harness 的包管理系统"——teamai init=订阅源、teamai pull=拉取最新版本、teamai push=发起升级 PR、roles/tags/source=包分组与依赖管理。

teamai-cli 项目档案

字段 值
仓库 https://github.com/Tencent/teamai-cli
定位 The team harness for AI agents（让每个 AI 编码 Agent 用上团队级最佳实践 harness）
创建 2026-04-27（4 个月）
Stars 695（截至 2026-08-30）
Forks 67
主语言 TypeScript 3.78MB（Python 16KB / JavaScript 3.4KB 配套）
安装 npm install -g teamai-cli
协议 MIT
CI 徽章 通过（GitHub Actions ci.yml）
模板组织 https://github.com/teamai-hub — 预生产用 Skill/Rules/Review Agents 模板仓库，点 Use this template 即可
Issues 12 open
Git 服务兼容 GitHub、GitLab、CNB（代码中国）、TGit（腾讯工蜂）、私有 Git

核心设计宣言（README 第一句）：

Git-native management of skills, rules, MCP, env vars, knowledge base, and more — across Claude Code / Codex / CodeBuddy / WorkBuddy / OpenCode and more.

Git-native 是关键词。它不是自己再发明一套网盘同步，也不是做 SaaS 后台。你的团队共享 Git 仓库就是唯一的真相源（Single Source of Truth），这让权限审计、版本回溯、Code Review、审批流、GitOps 流水线部署——所有现成工程化能力全部直接可用，不用重造。

一表看懂支持范围：9 款 Agent × 13 项能力

这是 README 给的能力矩阵，我把勾都对上号了：

MERMAID_BLOCK_0

  • Claude Code、Codex、Cursor、CodeBuddy、WorkBuddy 这 5 款：13 项全支持。
  • OpenCode：Harness 7 项 + KB 3 项 全支持，但没有 Analytics（session/digest/dashboard 不支持）。
  • OpenClaw：Harness 5 项（缺 agents/hooks 对应？），KB 3 项全，无 Analytics。
  • Hermes、DeepSeek Harness：支持更基础的 Harness 组合（skills/docs/env/MCP/rules 子集）+ KB 3 项，无 agents/hooks/analytics。

一个你没想到但很重要的点： WorkBuddy（腾讯自用 AI 编码 Agent）是全家桶，说明 teamai-cli 不是一个"腾讯先开源出来试水的项目"，是内部先真实用起来打磨过、然后把内部 WorkBuddy 适配逻辑和其他 8 款公开 Agent 一起开放出来。这种"内部产品先做、开源版和内部版走同一套代码"的路线，质量通常比 demo 型开源靠谱得多。

Git 原生分发模型：Push → Review & Merge → SessionStart 自动 Pull

这是整个系统的"心跳"：

teamai push  →  自动建分支 + 开 Merge Request
                   ↓ （团队 admin/reviewer 审批）
              合并入共享 Git 仓库 main
                   ↓
              任一成员本地 AI 工具启动会话
                SessionStart Hook 触发 teamai pull
                   ↓
              最新资源注入本地各 AI 工具目录

关键点：

① teamai pull 不是手动命令（除非你手动执行）。它被 SessionStart Hook 自动注入到每个已安装 AI 工具里——你一打开 Claude Code，teamai pull 先跑，保证 session 开始用的就是团队最新版本。项目级安装时，如果项目里还没有对应工具的 .claude/，会先建目录再拉。

② teamai push 不是 git push。它自动建分支、自动开 Merge Request、走正常团队 CR 流程。任何 Skill/Rules/MCP 配置变更都必须过 Code Review。这从根本上杜绝了"某个同学本地改了个 Skill 直接推给所有人"的事故——团队知识库是生产资产，不是共享文件夹。

③ 同步路径真的写到各工具 native 目录（README 明确写）：
- Skills → ~/.claude/skills/、~/.codex/skills/、~/.cursor/skills/、~/.codebuddy/skills/ 等
- Rules → AGENTS.md、.cursorrules 等不同工具的规则文件格式
- Env → 各工具 .env
- Agents → 各工具 agents/ 子目录
- MCP → 各工具 native 的 MCP 配置格式（这是最狠的，下面单独讲）

团队级三大管控：角色/标签/订阅源

管理员统一在团队 Git 仓库配置，生效于所有 teamai pull。

1. Roles：按岗位只同步该有的 Skill

teamai roles

定义 角色 → namespace 映射。新人 onboarding 时只给后端工程师角色，teamai pull 下来的就只有 skills/backend/ 这个 namespace 下的 Skill，不会看到 frontend/react-review、marketing/copywriter 这种不需要的资源。这在 30+ 人团队里非常关键——Skill 仓库 200+ 个目录时，什么都拉等于什么都找不到。

2. Tags：按主题订阅

teamai tags

给 Skills / Rules 打标签，成员订阅自己关心的标签。比如一个 "DevOps + 数据平台" 的同学订阅 tags：deploy、spark、mcp-gpu，pull 时就只同步带这些标签的资源。

3. Sources：跨团队订阅外部 Skill 仓库

# 订阅别的团队公开的 teamai 仓库
teamai source add https://github.com/other-team/teamai-public.git --name other-team

# 列出已订阅
teamai source list
# 浏览其他团队可订阅的 skill 列表
teamai source browse other-team
# 移除
teamai source remove other-team

这个设计非常关键。它意味着 teamai 的团队共享不是封闭在一个 Git 仓库里——公司里平台团队可以维护一个平台公共 teamai 仓库（含标准 CI/CD Skill、合规扫描 MCP、公司内部文档 MCP），数据团队维护数据仓库，业务团队维护业务线。每个团队只需要 teamai source add，就能订阅其他团队发布的公共资源。

团队 Hooks 事件系统：PreToolUse 拦截 + 工具匹配器

Hooks 用 hooks/hooks.yaml 声明，teamai pull 自动注入到每个 AI 工具的对应 hook 位置：

hooks:
  - id: block-secret
    description: Scan for secrets before commit
    event: PreToolUse          # 事件名：PreToolUse / SessionStart / SessionStop
    matcher: Bash              # 只对 Bash 类型 tool 调用触发
    command: 'bash -lc "~/.teamai/team-scripts/scan-secret.sh" || true'
    tools: [claude, cursor]    # 仅生效在 claude 和 cursor 两个工具（codex/codebuddy 不装这个）

管理命令：

teamai hooks list      # 看当前生效的所有 hook
teamai hooks inject    # 重新注入到所有已安装的 AI 工具
teamai hooks remove    # 移除所有 teamai 注入的 hook

这是团队合规的命门。常见会加的 hook：
- PreToolUse 匹配 Bash/GitCommit：跑 Gitleaks 或内部 secret 扫描脚本，检测到密钥就 exit 1，Agent 本次工具调用被阻止。
- PreToolUse 匹配 HttpRequest/外部域名：公司合规要求，禁止 Agent 调外部不受管控的 SaaS 域名。拦截记录走日志。
- SessionStart：teamai pull——这个是 teamai 默认就会注入的。
- SessionStop：摩擦评分检测（下一节知识库里讲），判断这次会话值不值得沉淀成 learning。

团队级 MCP 服务器统一配置：一次声明，9 种格式自动写入

这是我认为 teamai-cli 最"解决真痛点"的功能。我实际见过的团队，只要同时用 3 款以上 AI 工具，MCP 配置肯定乱成一锅粥：

  • Claude Code 用的是 ~/.claude/settings.json 里面的一个 JSON 数组
  • Codex 可能是 ~/.codex/mcp.json
  • Cursor 是 .cursor/mcp.json
  • CodeBuddy 又是另一套 YAML

MCP 服务器地址、token、headers、transport 每加一个都要手动改 4 份文件。加一次要 30 分钟。

teamai 的解法：只声明一次，拉的时候自动转换成每个工具的 native 格式。

# 仓库中的 mcp/mcp.yaml（单一真相源）
servers:
  - name: gpu-analysis
    transport: http            # stdio | http | sse
    url: https://example.com/api/mcp
    headers:
      Authorization: Bearer ${GPU_ANALYSIS_TOKEN}

管理命令：

teamai mcp list | inject | remove

这里有两个细节：
1. Secrets 用 ${VAR} 变量占位，不在仓库里存真实 token。成员本地环境变量里有 GPU_ANALYSIS_TOKEN，注入时替换。没设？那这个 MCP 配置对这个成员的本地文件留空，或报错让你填。
2. Transport 支持 stdio/http/sse 三种——这三类几乎覆盖了今天 MCP 协议所有部署形态。

知识库三支柱：Learnings / Recall / Codebase Graph

Harness 分发解决"团队所有人拿到同一套 Skill/Rules"。但真实团队还有一个更大的问题："某某同事之前踩过这个坑的经验，Agent 和新人怎么能用到？" teamai 做了三层。

支柱一：摩擦信号触发 Learnings 自动分享（SessionStop Hook）

核心洞察："顺利跑通的会话没什么好沉淀的，值得记的是你和 AI 打架的那些会话。"

每次会话结束，SessionStop Hook 运行摩擦评分——统计这些"值得记住"的信号：
- 你打断 / 纠正 AI 的次数
- 你拒绝了 AI 提议的工具调用次数
- AI 自己重复调用失败工具的重试次数

得分超过阈值，它会在会话末尾给你一段提示（原文直接给的文案）：

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

Task: Fix duplicate project-level Hook injection

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

这条提示是 per-session 最多一次——不会反复刷屏让你烦。点了 /teamai-share-learnings 后，teamai 自带的 Skill 会自动把这轮会话去隐私、总结成 learning 文档、开一个 MR 进团队共享仓库，不用你手动写。

支柱二：Recall 子 Agent 自动召回团队知识

这个功能默认关——团队管理员可在 teamai.yaml 设 sharing.recall.enabled: true 做默认，每个成员也能本地 override：

teamai recall enable     # 部署 teamai-recall 子agent 到所有 AI 工具的 agents/ 目录，注入规则
teamai recall disable    # 移除
teamai recall status     # 查看（团队默认 + 用户本地 override）

召回架构是 subagent 模式（不是 RAG 向量库 HTTP API 模式）：
- 每个 AI 工具的 agents/ 里多一个 teamai-recall 子 agent。
- 主 Agent 做任务之前，先调用这个子 agent。
- 子 agent 内部做三件事：
1. 先跑 relevance precheck（teamai recall --check）——判断当前任务和团队知识是否相关，不相关直接跳过，不给主 Agent 加干扰。
2. 相关就调用 CLI：teamai recall "<query>"，底层用 BM25 文本检索 + 依赖图 boost rerank。
3. 读匹配到的学习文档 / 代码图源文件，给主 Agent 返回结构化结果。

手动跑 CLI 可以测试召回效果：

$ teamai recall "port conflict"
[1/2] MR review caught a port-conflict bug | star 1 | user type
Author: member-a | Score: 18.5 | Tags: troubleshooting, networking

[2/2] Deployment configuration best practices | project type
Author: member-b | Score: 12.0 | Tags: deploy, config
Matched: conflict | Missing: port

为什么默认关？ 因为有隐性的 token 成本和信息暴露风险——不是每个团队都希望"所有会话自动去搜团队历史 learning"，尤其是涉及敏感信息的项目。先 opt-in，对的。

支柱三：Codebase Knowledge Graph（WASM tree-sitter 双轨 AST + 启发式）

# 导入单仓库
teamai import --from-repo https://github.com/org/repo
# 批量导入整个组织下所有仓库
teamai import --from-org myorg
# 批量 MR 列表
teamai import --from-repo-list list.txt --from-mr mrlist.txt --from-iwiki wiki_pages.txt
# 图健康检查
teamai codebase --lint

导入后生成结构化的图，写进 teamwiki/。召回的时候对 codebase 类型的结果做 graph-boosted rerank，而且召回结果会附一行 Sources: 列相关源代码路径——Agent 不用从 repo 根开始瞎转悠，直接从这些文件改起。

双轨解析：
- AST track（TypeScript/JavaScript/Python/Go）：WASM 版 tree-sitter 纯 JS 依赖，不需要装本地编译工具链。精确解析 import/require、调用点、TypeScript implements 产生带 confidence 权重的 DEPENDS_ON / REFERENCES / IMPLEMENTS 边，tag 是 code-ast。
- Heuristic track（Java/Rust/所有其他语言 + AST 失败时 fallback）：正则抽取，tag code-heuristic。

同一文件两条轨道都出结果时 AST 优先。设环境变量 TEAMAI_SKIP_AST=1 可以强制启发式-only 跑。AST 加载失败会记一个 AST_UNAVAILABLE gap。

WASM tree-sitter 这个选型非常漂亮——如果选本地原生 tree-sitter，装包要 node-gyp + C 编译器，npm install 的失败率在国内公司内网环境里至少 30%。WASM 纯 JS 依赖，跨平台不用编，AST 解析稍微慢一点但胜在 100% 能装上。AST 不行就 heuristic，不阻塞功能。工程感很足。

Analytics 三件套：Weekly Digest / Session Save / Dashboard

能力 命令 展示内容
Usage Weekly Digest teamai digest 周报：token 用量、对话量、干预率（成员打断/纠正 AI 的次数 / 总调用量）——干预率越高说明 Skill/Rules 越需要优化
Sessions teamai session save [--push] 每次会话的去隐私化摘要：工具调用序列、prompt turns 数、人工干预次数。--push 后喂给 digest 的 Session Highlights。
Dashboard teamai dashboard Web 实时看板：团队成员实时编码会话状态、干预次数、token 用量。

这里我最关注的指标是 干预率。团队 Leader 盯 token 用量没用——有人 token 用得多但产出高，有人省 token 但产出低。干预率是硬信号：某个成员的 Claude Code 干预率连续两周 40%+，基本就两种情况——要么这个成员的习惯和 AI 合不来需要教，要么团队针对他工作流的 Skill/Rules 覆盖不到位，该补了。

隐私脱敏是硬性设计：session save 的产物是 per-session summary，不含原始 prompt/输出内容，只记录高阶指标（turns、interventions、friction signals、工具类序列、任务一句话摘要）。合规团队不用先反对，可以看 schema 再评。

完整命令清单（20+）

命令 说明
teamai init <repo-url> OAuth 登录、连共享仓库、注册成员、注入所有 hooks（可选 --scope user 装 ~ 下）
teamai pull 拉团队资源、注入本地所有 AI 工具目录（通常 SessionStart 自动调）
teamai push 推本地变更到分支 + 自动开 Merge Request
teamai status 本地 vs 团队仓库 diff 摘要
teamai contribute 分享这次会话经验直接进团队 repo（类似 /teamai-share-learnings）
teamai recall <query> 搜团队知识库（BM25 + graph boost）；enable / disable / status 三开关
teamai import --from-repo / --from-org / --from-mr / --from-iwiki 生成团队代码 AST 知识图
teamai codebase --lint codebase graph 健康审计
teamai ci extract-mr --url <url> CI 流水线里用：从 MR 抽知识、评论区写建议、merge 后写 teamwiki
teamai members 成员列表
teamai roles 角色 → namespace 映射管理
teamai tags 标签管理
teamai skill exclude add/remove/list 本地个人不想同步的 skill（比如前端同学不需要 spark-deploy）
teamai source 跨团队订阅源管理
teamai remove <type> <name> 删除一个资源并开 MR
teamai hooks list/inject/remove hooks 注入管理
teamai mcp list/inject/remove MCP 服务器配置管理
teamai session save [--push] 去隐私会话摘要存月档 + push 给 digest
teamai digest 生成团队周报 digest（含 session highlights）
teamai doctor 自诊断：OAuth 过期、repo 连不上、某工具 hooks 注入失败…
teamai uninstall 从本机和所有 AI 工具里彻底卸载所有 teamai 资源

TheAIEra 团队怎么接？给一份 6 步最小落地清单

如果 TheAIEra 或者你们团队想从 0 到 1 接 teamai，别急着建模板。按这个顺序来：

  1. 建 teamai 共享 Git 仓库（1 小时）。先去 teamai-hub 挑一个生产用模板点 Use this template，别自己从空仓库建——模板里已经有技能骨架、hooks 示例、mcp.yaml 示例，省很多事。
  2. 2-3 个核心成员试装（半天）。先 npm install -g teamai-cli，然后 teamai init <新仓库> 选默认项目级 scope。跑 teamai pull 看 2-3 个常用工具（Claude Code/Codex/Cursor）目录里是不是真的有了同步内容，teamai doctor 看诊断报告全绿。
  3. 从最紧急的 3 项 MCP 服务器入手做统一配置（1 天）。先把你们 9 种格式的 MCP 全迁移成一份 mcp/mcp.yaml，全团队以后只维护这一份。这一步完成立刻见效——以前新人手动抄 token、填 headers 的 onboarding 时间直接砍没。
  4. 3 个 hooks 起步（1 天）：
    - SessionStart → teamai pull（teamai 会加，验证一下确实生效）
    - SessionStop → 摩擦评分（learnings 自动提示）
    - PreToolUse Bash/GitCommit → secret 扫描（选你们已经在用的扫描脚本接进去）
  5. 第一批 10 个 Skill 进仓库（2-3 天）。别贪多，挑团队每天都在用的 10 个 Skill：代码 review、项目 PR 模板、常见构建错误排查、CI 绿了但功能挂了的排查 checklist、MCP 常见调用封装……用 roles + tags 做 namespace 分。
  6. 启用 recall + codebase graph（1 天）：
    - 管理员先 teamai import --from-org 把组织代码图建出来，teamai codebase --lint 修 gap
    - teamai recall enable 全员启（或让成员自己 opt-in）
    - 跑 teamai dashboard 和 teamai digest 看第一轮数据和干预率基线

7 天内就应该能拿到真收益。别一上来追求"所有 13 项能力全跑通"，踩最深的坑先填。

横向对比：三种 Skill 管理体系怎么选

这半年写了好几篇不同体系的 Skill 文章，现在把三种不同粒度的方案摆在一起：

维度 Claude Code 原生单用户 Hermes research/llm-wiki Tencent teamai-cli
用户规模 单人 / 小团队（< 5 人） 单人 / 双人协作研究知识库 团队（10 人以上）多 Agent 协作
Agent 数量 1 款（Claude Code） 1 款（Hermes） 9 款统一（Claude/Codex/Cursor/CodeBuddy/WorkBuddy/OpenCode/OpenClaw/Hermes/DeepSeek Harness）
分发 手动拷贝 / 群里 zip / 共享网盘 单一本地目录 + Obsidian Sync 同步 Git 原生 push/MR/merge/pull + 会话启动自动同步
配置中心 无 / 每人自己配 本地 SCHEMA.md + 目录规范 团队仓库 mcp.yaml + hooks.yaml 单一真相源 + 自动格式转换
角色/订阅 无（什么都装） 无（面向个人） Roles 按岗位 + Tags 按主题 + Sources 跨团队订阅
知识沉淀 无（散落在会话里） 三层 wiki：raw/ + Layer2 + SCHEMA，LLM Wiki 工程实现 摩擦评分自动学习文档 + Recall subagent 召回 + AST 双轨代码依赖图 boost
合规/审计 无 无 MR 审批流 + GitOps 版本可追溯 + secret hook 拦截 + session 脱敏
数据看板 无（个人工具自带 metrics） 无 实时 dashboard + weekly digest 干预率/token/对话量
最适合的你 个人用 Claude Code 爽 研究员个人笔记、知识沉淀爱好者 企业 / 团队统一 AI 编码基础设施

选型一句话：

  • 你是自己一个人研究知识管理，或者团队小到 5 个人以下 → Hermes llm-wiki 的 SCHEMA/raw/三层 + Obsidian Sync，轻量又好用。
  • 你是开发者个人，用的 Agent 主要就是 Claude Code，团队也小 → Claude Code 原生 Skill 体系 + 团队内部共享群够用。
  • 你是团队 Leader / 平台负责人，团队 10+ 人、混用多款 AI Agent、需要统一管控 Skill/Rules/MCP、合规审计、数据看板 → 这就是 teamai-cli 的目标用户。

参考文档与链接

一个真实问题给你：你们团队现在多少人在用 AI 编码 Agent？Skill/Rules/MCP 是统一管理还是各写各的？评论区晒下数字，我猜 80% 是后者还没踩够坑。

作者: itech001
来源: 公众号：AI人工智能时代(the-ai-era)
网站: https://www.theaiera.top/
关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top

关注公众号，获取更多 AI 技术干货！

posted @ 2026-08-30 11:49  iTech  阅读(58)  评论(0)    收藏  举报