# gaea-teamai-cli
**Repository Path**: DannyJones/gaea-teamai-cli
## Basic Information
- **Project Name**: gaea-teamai-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-28
- **Last Updated**: 2026-08-28
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# TeamAI — The team harness for AI agents
> [English](README.md) | [简体中文](README.zh-CN.md)
[](https://github.com/Tencent/teamai-cli/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/teamai-cli)
[](https://www.npmjs.com/package/teamai-cli)
[](LICENSE)
面向 AI 智能体的团队 Harness 管理和分发工具。
通过 Git 统一管理 skills、rules、mcp、环境变量、知识库等 Harness，驾驭 Claude Code / Codex / CodeBuddy / WorkBuddy / OpenCode 等多种 AI 工具。
## 快速开始
### 安装
```bash
npm install -g teamai-cli
```
### 团队管理员 / 个人使用者
在 Git 托管平台（GitHub、GitLab、CNB、TGit，或私有 Git 服务）创建共享经验仓库，**授予团队成员写权限**，然后运行 `teamai init https://github.com/yourorg/yourrepo`。
> **还没有团队仓库？** 可以从内置了成套 skills、rules、review agents 的模板起步。浏览 [teamai-hub](https://github.com/teamai-hub) org，点 **Use this template** 生成自己的仓库，再对它执行 `teamai init`。
### 团队成员
```bash
# 二选一：按你想要的安装范围选择其中一条
# 项目级初始化（默认，资源安装到项目目录下）
cd /path/to/my-project
teamai init https://github.com/yourorg/yourrepo
# 或者，用户级初始化（资源安装到 ~/ 下）
teamai init https://github.com/yourorg/yourrepo --scope user
```
初始化完成后，每次开启 AI 会话时都会自动拉取管理员发布的 skills / rules 等 Harness 更新，无需手动同步。
> **完整使用指南**：[docs/usage-guide.zh-CN.md](docs/usage-guide.zh-CN.md)（[English](docs/usage-guide.md)）— 涵盖从团队创建到日常使用的全流程。
## 功能概览
| Agent |
Harness |
知识库 |
使用分析 |
| skills | rules | docs | env | agents | hooks | mcp |
learnings | codebase | teamwiki |
usage | sessions | dashboard |
| Claude Code | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Codex | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Cursor | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| CodeBuddy | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| OpenCode | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | — | — |
| WorkBuddy | ✓ | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| OpenClaw | ✓ | ✓ | ✓ | ✓ | — | — | — | ✓ | ✓ | ✓ | — | — | — |
| Hermes | ✓ | — | ✓ | ✓ | — | — | — | ✓ | ✓ | ✓ | — | — | — |
| DeepSeek Harness | ✓ | — | ✓ | — | — | — | — | ✓ | ✓ | ✓ | — | — | — |
**Git 托管平台** —— GitHub · GitLab · CNB · TGit · 私有 Git 服务。
### 分发策略
管理员一次配置、随 `teamai pull` 分发给每位成员的团队级设置：
| 能力 | 命令 | 作用 |
|------|------|------|
| **角色（Roles）** | `teamai roles` | 定义「角色 → 命名空间」映射，让每位成员只同步与自身角色匹配的 skills。 |
| **标签（Tags）** | `teamai tags` | 给 skills / rules 打标签，成员只订阅自己需要的标签。 |
| **订阅源（Sources）** | `teamai source` | 订阅额外的 skill 仓库——其他团队的公开仓库，或本团队内的公共/共享仓库；已订阅的 skills 会在 pull 时自动同步。 |
### 使用分析
洞察团队实际如何使用 AI 工具：
| 能力 | 命令 | 呈现内容 |
|------|------|----------|
| **用量（Usage）** | `teamai digest` | 团队周报——token 用量、会话量、干预率。 |
| **会话（Sessions）** | `teamai session save` | 脱敏的单会话摘要（工具序列、对话轮次、干预次数），喂给周报的 Session Highlights。 |
| **看板（Dashboard）** | `teamai dashboard` | Web 看板，实时展示成员的编码会话状态、干预次数和 token 用量。 |
## Harness 管理和分发
TeamAI 把 skills、rules、docs、hooks 统一存放在共享 Git 仓库，通过「push → 评审合并 → pull」的流程分发到每位成员的本地 AI 工具，并支持订阅其他团队或公共仓库的 Harness。
### 工作原理
```
teamai push → 创建分支 + MR → reviewer 审批合并
↓
SessionStart hook → teamai pull → 同步到本地 AI 工具
```
成员通过 `teamai push` 提交变更并创建合并请求供审核。合并后，`teamai pull`（由 SessionStart hook 在会话启动时自动触发）将最新资源同步到本地。Skills 会同步到 `~/.claude/skills/`、`~/.codex/skills/`、`~/.cursor/skills/`、`~/.codebuddy/skills/` 等目录。在 **project scope** 安装下，SessionStart 会先为当前工具创建项目根目录（例如 `/.claude`），再 pull 写入；单独执行 `teamai pull` 仍不会凭空创建 Agent 目录。
### 团队 Hooks
在 `hooks/hooks.yaml` 中声明自定义 hooks，`teamai pull` 自动分发到所有 AI 工具：
```yaml
hooks:
- id: block-secret
description: 提交前扫描密钥
event: PreToolUse
matcher: Bash
command: 'bash -lc "~/.teamai/team-scripts/scan-secret.sh" || true'
tools: [claude, cursor]
```
```bash
teamai hooks list # 查看生效的 hooks
teamai hooks inject # 重新注入到每个已安装的工具
teamai hooks remove # 移除所有 teamai 管理的 hooks
```
### 团队 MCP Server
在 `mcp/mcp.yaml` 中声明一次，`teamai pull` 按各工具原生格式写入。密钥用 `${VAR}`。
```yaml
servers:
- name: gpu-analysis
transport: http # stdio | http | sse
url: https://example.com/api/mcp
headers:
Authorization: Bearer ${GPU_ANALYSIS_TOKEN}
```
```bash
teamai mcp list | inject | remove
```
### Skill 订阅源
订阅额外的 skill 仓库——其他团队的公开仓库，或本团队内的公共/共享仓库：
```bash
teamai source add https://github.com/other-team/teamai-public.git --name other-team
teamai source list
teamai source browse other-team # 浏览可用 skills
teamai source remove other-team
```
添加/移除会立即在本机生效，订阅的 skills 会在下一次 `teamai pull` 时同步。需要将
`teamai.yaml` 的改动分享给团队成员时，再运行 `teamai push`。
## 知识库
除了分发 Harness，TeamAI 还把团队沉淀的经验和代码结构组织成可检索的知识库，让 AI 在需要时自动召回。
### 自动经验沉淀
Session 结束时，Stop hook 按**摩擦信号**对 session 评分——这些信号表明本次 session 踩到了值得记录的东西：你打断或纠正了 AI、拒绝了某次工具调用，或 AI 反复重试出错的工具。又长又顺（工具调用很多但没有摩擦）的 session 不会触发；真正较劲过的 session 才会。达标后 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.
```
提示会列出实际触发它的非零摩擦信号；如果能取得首个任务摘要，还会在脱敏、单行化后附上任务上下文。`/teamai-share-learnings` skill 自动总结 session 经验并推送到团队仓库。每个 session 最多提示一次。
### 团队知识检索
让 AI 在执行任务前自动检索团队积累的知识。该功能**默认关闭**，需显式开启——团队可在 `teamai.yaml` 设 `sharing.recall.enabled: true` 作为默认值，成员也可本地覆盖：
```bash
teamai recall enable # 开启：部署 teamai-recall 子 agent + 注入引导规则
teamai recall disable # 关闭：移除子 agent 和规则
teamai recall status # 查看生效状态（团队默认 + 用户覆盖）
```
**通过子 agent 检索**：开启后 `teamai pull` 会把内置的 `teamai-recall` 子 agent 部署到各 AI 工具的 `agents/` 目录。AI 在任务开始前调用它——由子 agent 提取关键词、执行检索、读取命中的源文件，最后返回结构化的团队知识摘要。subagent 会先做相关性预检（`teamai recall --check`），当任务与团队知识无关时直接跳过检索。子 agent 底层调用的仍是 `teamai recall` 命令，也可手动直接运行：
```bash
$ 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
```
### 代码知识图谱
`teamai import` 将源码仓库解析为 `teamwiki/` 下的结构化图谱，实现结构感知的检索：
```bash
teamai import --from-repo https://github.com/org/repo
teamai import --from-org myorg # 批量导入所有仓库
teamai codebase --lint # 健康检查
```
图谱存储组件、接口、配置和跨仓库依赖边。`teamai recall` 利用图谱进行增强排名。
当召回命中 codebase 页面时，结果会附带一行 `Sources:`，列出相关源文件路径，供 agent 直接作为代码改动的入口，无需重新探索代码库。
## 命令一览
| 命令 | 说明 |
|------|------|
| `teamai init` | 初始化：OAuth 登录、关联仓库、注册成员、注入 hooks |
| `teamai pull` | 拉取团队资源并注入到本地 AI 工具 |
| `teamai push` | 推送本地资源到分支并创建合并请求 |
| `teamai status` | 显示本地与团队仓库的差异 |
| `teamai contribute` | 将 session 经验分享到团队仓库 |
| `teamai recall ` | 搜索团队知识库（BM25 + 图谱增强） |
| `teamai recall enable/disable/status` | 开关或查看 recall 状态 |
| `teamai import` | 导入知识（`--dir`、`--from-repo`、`--from-org`、`--from-repo-list`、`--from-mr`、`--from-iwiki`） |
| `teamai codebase --lint` | 知识图谱健康检查 |
| `teamai ci extract-mr --url ` | CI：从 MR 提取知识、发评论、合并后写入 |
| `teamai members` | 查看团队成员 |
| `teamai roles` | 管理团队角色和命名空间 |
| `teamai tags` | 管理基于标签的 skill/rule 过滤 |
| `teamai skill exclude add/remove/list` | 管理不参与本地同步的 skills（[使用指南](docs/usage-guide.zh-CN.md#排除个人不需要的-skill)） |
| `teamai source` | 管理 skill 订阅源（其他团队或本团队公共仓库） |
| `teamai remove ` | 删除资源并创建 MR |
| `teamai session save` | 将脱敏后的 session 摘要记录到月度日志（`--push` 可喂给 `digest`） |
| `teamai digest` | 生成团队周报 |
| `teamai doctor` | 诊断配置问题 |
| `teamai uninstall` | 移除所有 teamai 资源和 hooks |
## 许可证
[MIT](LICENSE)
## 贡献
欢迎提交 PR！请先阅读 [CONTRIBUTING.md](.github/CONTRIBUTING.md)。