trending/teamai-cli
1
0
Fork 0
mirror of https://github.com/Tencent/teamai-cli.git synced 2026-10-02 03:14:40 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #456 from Tencent/docs/readme-beta-layers

Browse Source 
docs(readme): tighten README and mark Context/Improvement as beta
This commit is contained in:
jeff
2026-09-09 16:17:39 +08:00
committed by GitHub
parent 8d3d66db49 ace8f2b42d
commit 224c0c4287
2 changed files with 86 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+43 -82
View File
@@ -13,6 +13,16 @@
TeamAI manages your team's skills, rules, MCP, and knowledge across Claude Code, Codex, CodeBuddy, WorkBuddy, OpenCode, Cursor, and other AI agents.
## Contributors
Thanks to everyone who has contributed to TeamAI!
<a href="https://github.com/Tencent/teamai-cli/graphs/contributors">
<img src="https://contrib.rocks/image?repo=Tencent/teamai-cli" alt="Contributors" />
</a>
Made with [contrib.rocks](https://contrib.rocks).
## Quick Start
### Install
@@ -25,8 +35,6 @@ npm install -g teamai-cli
Create a shared-experience repo on your git host (GitHub, GitLab, GitCode, CNB, TGit, or a private Git service), **grant write access to team members**, then run `teamai init https://github.com/yourorg/yourrepo`.
For self-hosted GitLab, set `GITLAB_URL` to your instance URL and `GITLAB_TOKEN` to a token with `api` scope before initializing. If `init` recognizes an unconfigured GitLab instance, it stops with setup instructions. Existing repos with `provider: git` also need `provider: gitlab` in the team repo's `teamai.yaml` to create MRs. See [GitLab setup](docs/providers.md#gitlab-provider含自托管).
> **No team repo yet?** Start from a template pre-loaded with production-ready skills, rules, and review agents. Browse the [teamai-hub](https://github.com/teamai-hub) org, click **Use this template**, then `teamai init` against your new repo.
### Team members
@@ -48,13 +56,13 @@ Once initialized, every AI session automatically pulls the latest skills / rules
## Product architecture
**Team Execution × Team Context × Team Improvement**:
**Team Execution × Team Context (beta) × Team Improvement (beta)**:
| Layer | Job | In this CLI today |
|-------|-----|-------------------|
| **Team Execution** | Make every agent work the team's way | `init` / `pull` / `push`, skills, rules, agents, hooks, MCP, env |
| **Team Context** | Make every agent understand the team | recall, learnings, codebase graph, teamwiki... |
| **Team Improvement** | Make every execution improve the team | friction-based share-learnings, sessions, digest, dashboard... |
| **Team Context** (beta) | Make every agent understand the team | recall, learnings, codebase graph, teamwiki... |
| **Team Improvement** (beta) | Make every execution improve the team | friction-based share-learnings, sessions, digest, dashboard... |
## Overview
@@ -63,8 +71,8 @@ Once initialized, every AI session automatically pulls the latest skills / rules
<tr>
<th rowspan="2">Agent</th>
<th colspan="7">Team Execution</th>
<th colspan="3">Team Context</th>
<th colspan="3">Team Improvement</th>
<th colspan="3">Team Context (beta)</th>
<th colspan="3">Team Improvement (beta)</th>
</tr>
<tr>
<th>skills</th><th>rules</th><th>docs</th><th>env</th><th>agents</th><th>hooks</th><th>mcp</th>
@@ -112,74 +120,27 @@ teamai push → create branch + MR → reviewer approves + merges
SessionStart hook → teamai pull → synced to local AI tools
```
Members push changes via `teamai push`, which opens a Merge Request for review. Re-running `teamai push` on a resource that is still waiting in an unmerged PR updates that PR in place instead of opening a duplicate. Once merged, `teamai pull` (triggered automatically on session start via the SessionStart hook) syncs the latest resources locally. Skills sync to `~/.claude/skills/`, `~/.codex/skills/`, `~/.cursor/skills/`, `~/.codebuddy/skills/`, etc. For Codex, an existing skill under `~/.agents/skills/` is updated there instead of duplicated under `~/.codex/skills/`. In a **project-scope** install, SessionStart first creates that tool's project root (e.g. `<project>/.claude`) if it is missing, then pulls into it — a bare `teamai pull` still will not invent agent directories.
### What Gets Shared
### Team Hooks
Each resource is delivered to every agent:
Declare custom hooks in `hooks/hooks.yaml` and `teamai pull` delivers them to every AI tool:
| Resource | In the team repo | Notes |
|----------|------------------|-------|
| **Skills** | `skills/<name>/SKILL.md` | |
| **Rules** | `rules/*.md` | |
| **Docs** | `docs/` | Foundational project docs; not all loaded by default (progressive disclosure) |
| **Agents** | `agents/<name>.yaml` | |
| **Culture** | `culture.md` | Team mission, values, and working principles — injected into each agent's CLAUDE.md / AGENTS.md so every session inherits them |
| **CLAUDE.md** | `claudemd/*.md` | |
| **Env** | `env/` | Shared team-level environment variables and switches; do not put secrets here |
| **Hooks** | `hooks/hooks.yaml` | |
| **MCP** | `mcp/mcp.yaml` | |
| **Packages** | `teamai.yaml` | Currently npm packages and Claude Code plugins only |
| **Models** | — | Not implemented for every provider yet |
```yaml
hooks:
- id: block-secret
description: Scan for secrets before commit
event: PreToolUse
matcher: Bash
command: 'bash -lc "~/.teamai/team-scripts/scan-secret.sh" || true'
tools: [claude, cursor]
```
For file formats and full workflows, see the [Usage Guide](docs/usage-guide.md).
```bash
teamai hooks list # list effective hooks
teamai hooks inject # re-reconcile into every installed tool
teamai hooks remove # remove all teamai-managed hooks
```
### Team MCP Servers
Declare once in `mcp/mcp.yaml`; `teamai pull` writes each tool's native config. Use `${VAR}` for secrets.
```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 Subscription Sources
Subscribe to additional skill repos — other teams' public repos, or shared/public repos within your own org:
```bash
teamai source add https://github.com/other-team/teamai-public.git --name other-team
teamai source list
teamai source browse other-team # browse available skills
teamai source remove other-team
```
The add/remove change takes effect locally right away, and subscribed skills sync on the next
`teamai pull`. Run `teamai push` when you want to share the `teamai.yaml` change with teammates.
### Team Packages
Share and restore the team's npm packages and Claude Code plugins:
```bash
teamai packages install typescript
teamai packages install typescript@5.9.2 --npm
teamai packages install code-review@claude-plugins-official
teamai push # Share the declarations
teamai packages # Install everything declared by the team
```
See the [Usage Guide](docs/usage-guide.md#team-packages) for the complete workflow and configuration.
## Team Context
## Team Context (beta)
> Every agent understands how the team works.
@@ -242,10 +203,20 @@ Edges come from two tracks that run together, with AST results taking precedence
The WASM parser is a pure-JavaScript dependency — no native toolchain is required. If it fails to load for any reason, extraction falls back to the heuristic track and records an `AST_UNAVAILABLE` gap. Set `TEAMAI_SKIP_AST=1` to force heuristic-only extraction.
## Team Improvement
## Team Improvement (beta)
> Every execution makes the entire team smarter.
### Maintenance
As skills and knowledge accumulate, prune what the team no longer uses. `teamai recall maintenance` archives low-confidence learnings and flags stale skills, rules, and docs for cleanup or updates:
```bash
teamai recall maintenance --prune --dry-run # preview
teamai recall maintenance --prune --archive # archive unused learnings
teamai recall maintenance --update-quality # draft updates for stale skills / docs
```
Insight into how the team actually uses its AI tools, and a starting point for turning session friction into shared skills, rules, and knowledge:
| Capability | Command | What it shows |
@@ -291,13 +262,3 @@ Insight into how the team actually uses its AI tools, and a starting point for t
## Contributing
PRs are welcome! Please read [CONTRIBUTING.md](.github/CONTRIBUTING.md) first.
## Contributors
Thanks to everyone who has contributed to TeamAI!
<a href="https://github.com/Tencent/teamai-cli/graphs/contributors">
<img src="https://contrib.rocks/image?repo=Tencent/teamai-cli" alt="Contributors" />
</a>
Made with [contrib.rocks](https://contrib.rocks).
README.zh-CN.md
+43 -82
View File
@@ -13,6 +13,16 @@
TeamAI 统一管理团队的 Skills、Rules、MCP 和知识，驾驭 Claude Code、Codex、CodeBuddy、WorkBuddy、OpenCode、Cursor 等 AI Agents。
## 贡献者
感谢每一位为 TeamAI 贡献代码的伙伴！
<a href="https://github.com/Tencent/teamai-cli/graphs/contributors">
<img src="https://contrib.rocks/image?repo=Tencent/teamai-cli" alt="Contributors" />
</a>
由 [contrib.rocks](https://contrib.rocks) 生成。
## 快速开始
### 安装
@@ -25,8 +35,6 @@ npm install -g teamai-cli
在 Git 托管平台（GitHub、GitLab、GitCode、CNB、TGit，或私有 Git 服务）创建共享经验仓库，**授予团队成员写权限**，然后运行 `teamai init https://github.com/yourorg/yourrepo`。
使用自建 GitLab 时，先将 `GITLAB_URL` 设为实例地址，并配置具有 `api` 权限的 `GITLAB_TOKEN`。若 `init` 探测到尚未配置的 GitLab 实例，会停止并提示配置方法。已有仓库若为 `provider: git`，还需把团队仓库 `teamai.yaml` 中的值改为 `provider: gitlab`，才能创建 MR。详见 [GitLab 配置](docs/providers.md#gitlab-provider含自托管)。
> **还没有团队仓库？** 可以从内置了成套 skills、rules、review agents 的模板起步。浏览 [teamai-hub](https://github.com/teamai-hub) org，点 **Use this template** 生成自己的仓库，再对它执行 `teamai init`。
### 团队成员
@@ -48,13 +56,13 @@ teamai init https://github.com/yourorg/yourrepo --scope user
## 产品架构
**Team Execution × Team Context × Team Improvement**：
**Team Execution × Team Context (beta) × Team Improvement (beta)**：
| 层 | 要解决的问题 | 当前 CLI 中的体现 |
|----|--------------|-------------------|
| **Team Execution** | 让每个 Agent 按团队的方式工作 | `init` / `pull` / `push`，skills、rules、agents、hooks、MCP、env |
| **Team Context** | 让每个 Agent 理解整个团队 | recall、learnings、代码知识图谱、teamwiki... |
| **Team Improvement** | 让每一次执行都成为团队能力的积累 | 基于摩擦信号的经验分享、sessions、digest、dashboard... |
| **Team Context** (beta) | 让每个 Agent 理解整个团队 | recall、learnings、代码知识图谱、teamwiki... |
| **Team Improvement** (beta) | 让每一次执行都成为团队能力的积累 | 基于摩擦信号的经验分享、sessions、digest、dashboard... |
## 功能概览
@@ -63,8 +71,8 @@ teamai init https://github.com/yourorg/yourrepo --scope user
<tr>
<th rowspan="2">Agent</th>
<th colspan="7">Team Execution</th>
<th colspan="3">Team Context</th>
<th colspan="3">Team Improvement</th>
<th colspan="3">Team Context (beta)</th>
<th colspan="3">Team Improvement (beta)</th>
</tr>
<tr>
<th>skills</th><th>rules</th><th>docs</th><th>env</th><th>agents</th><th>hooks</th><th>mcp</th>
@@ -112,74 +120,27 @@ teamai push → 创建分支 + MR → reviewer 审批合并
SessionStart hook → teamai pull → 同步到本地 AI 工具
```
成员通过 `teamai push` 提交变更并创建合并请求供审核。若某个资源已在未合并的 PR 中等待评审，再次对它执行 `teamai push` 会就地更新该 PR，而非新开一个重复的 PR。合并后，`teamai pull`（由 SessionStart hook 在会话启动时自动触发）将最新资源同步到本地。Skills 会同步到 `~/.claude/skills/`、`~/.codex/skills/`、`~/.cursor/skills/`、`~/.codebuddy/skills/` 等目录。对于 Codex，若 skill 已存在于 `~/.agents/skills/`，则会在原位置更新，不会在 `~/.codex/skills/` 创建重复副本。在 **project scope** 安装下，SessionStart 会先为当前工具创建项目根目录（例如 `<project>/.claude`），再 pull 写入；单独执行 `teamai pull` 仍不会凭空创建 Agent 目录。
### 分发内容
### 团队 Hooks
每类资源分发到每个 Agent：
在 `hooks/hooks.yaml` 中声明自定义 hooks，`teamai pull` 自动分发到所有 AI 工具：
| 资源 | 团队仓库中的位置 | 备注 |
|------|------------------|------|
| **Skills** | `skills/<name>/SKILL.md` | |
| **Rules** | `rules/*.md` | |
| **Docs** | `docs/` | 项目基础文档，默认不全量加载（渐进式披露） |
| **Agents** | `agents/<name>.yaml` | |
| **Culture** | `culture.md` | 团队使命、价值观与协作准则——注入各 Agent 的 CLAUDE.md / AGENTS.md，成为每次会话的行事底色 |
| **CLAUDE.md** | `claudemd/*.md` | |
| **Env** | `env/` | 通用环境变量、团队级开关；不建议直接放密钥 |
| **Hooks** | `hooks/hooks.yaml` | |
| **MCP** | `mcp/mcp.yaml` | |
| **Packages** | `teamai.yaml` | 目前只支持 npm 包和 Claude 插件 |
| **Models** | — | 暂时没有对全部 provider 实现 |
```yaml
hooks:
- id: block-secret
description: 提交前扫描密钥
event: PreToolUse
matcher: Bash
command: 'bash -lc "~/.teamai/team-scripts/scan-secret.sh" || true'
tools: [claude, cursor]
```
文件格式与完整工作流见[使用指南](docs/usage-guide.zh-CN.md)。
```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`。
### 团队包
共享并一键恢复团队的 npm 包和 Claude Code 插件：
```bash
teamai packages install typescript
teamai packages install typescript@5.9.2 --npm
teamai packages install code-review@claude-plugins-official
teamai push # 分享团队声明
teamai packages # 安装团队声明的全部包
```
完整工作流和配置见[使用指南](docs/usage-guide.zh-CN.md#团队包)。
## Team Context
## Team Context (beta)
> Every agent understands how the team works.
@@ -242,10 +203,20 @@ teamai codebase --lint --output /path/to/repo # 检查本地提取的图谱
WASM 解析器是纯 JavaScript 依赖，无需任何原生编译工具链。若因任何原因加载失败，提取会降级到启发式轨并记录一条 `AST_UNAVAILABLE` gap。设置 `TEAMAI_SKIP_AST=1` 可强制仅使用启发式提取。
## Team Improvement
## Team Improvement (beta)
> Every execution makes the entire team smarter.
### Maintenance
随着 skills 和知识积累，可以把团队不再使用的内容清掉。`teamai recall maintenance` 会归档低置信度 learnings，并标出过时的 skills、rules 和 docs，供清理或更新：
```bash
teamai recall maintenance --prune --dry-run # 预览
teamai recall maintenance --prune --archive # 归档无用 learnings
teamai recall maintenance --update-quality # 为过时 skills / docs 生成更新草稿
```
洞察团队实际如何使用 AI 工具，也是把 session 中的摩擦转化为共享 Skill、Rule 和知识的起点：
| 能力 | 命令 | 呈现内容 |
@@ -291,13 +262,3 @@ WASM 解析器是纯 JavaScript 依赖，无需任何原生编译工具链。若
## 贡献
欢迎提交 PR！请先阅读 [CONTRIBUTING.md](.github/CONTRIBUTING.md)。
## 贡献者
感谢每一位为 TeamAI 贡献代码的伙伴！
<a href="https://github.com/Tencent/teamai-cli/graphs/contributors">
<img src="https://contrib.rocks/image?repo=Tencent/teamai-cli" alt="Contributors" />
</a>
由 [contrib.rocks](https://contrib.rocks) 生成。