teamai-cli 0.24.0-beta.1 → 0.24.0-beta.3

package/README.md

@@ -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
@@ -46,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
 
@@ -61,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>
@@ -81,6 +91,7 @@ Once initialized, every AI session automatically pulls the latest skills / rules
     <tr><td>Hermes</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td></tr>
     <tr><td>DeepSeek Harness</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td></tr>
     <tr><td>Qoder</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td></tr>
+    <tr><td>ZCode</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td></tr>
   </tbody>
 </table>
 
@@ -110,74 +121,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.
-
-### Team Hooks
-
-Declare custom hooks in `hooks/hooks.yaml` and `teamai pull` delivers them to every AI tool:
-
-```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]
-```
-
-```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.
+### What Gets Shared
 
-### Team Packages
+Each resource is delivered to every agent:
 
-Share and restore the team's npm packages and Claude Code plugins:
+| 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 |
 
-```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.
+For file formats and full workflows, see the [Usage Guide](docs/usage-guide.md).
 
-## Team Context
+## Team Context (beta)
 
 > Every agent understands how the team works.
 
@@ -227,7 +191,7 @@ Matched: conflict | Missing: port
 teamai import --from-repo https://github.com/org/repo
 teamai import --from-org myorg              # batch import all repos
 teamai codebase --extract /path/to/repo     # local extract into teamwiki/
-teamai codebase --lint                      # health check
+teamai codebase --lint --output /path/to/repo # check the locally extracted graph
 ```
 
 The graph stores components, interfaces, configs, and cross-repo import edges. `teamai recall` uses it for graph-boosted re-ranking.
@@ -240,10 +204,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 |
@@ -289,13 +263,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).

package/README.zh-CN.md

@@ -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) 生成。
+
 ## 快速开始
 
 ### 安装
@@ -46,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... |
 
 ## 功能概览
 
@@ -61,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>
@@ -81,6 +91,7 @@ teamai init https://github.com/yourorg/yourrepo --scope user
     <tr><td>Hermes</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td></tr>
     <tr><td>DeepSeek Harness</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">—</td><td align="center">—</td><td align="center">—</td></tr>
     <tr><td>Qoder</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td></tr>
+    <tr><td>ZCode</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">—</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td><td align="center">✓</td></tr>
   </tbody>
 </table>
 
@@ -110,74 +121,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
-
-在 `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`。
+### 分发内容
 
-### 团队包
+每类资源分发到每个 Agent：
 
-共享并一键恢复团队的 npm 包和 Claude Code 插件：
+| 资源 | 团队仓库中的位置 | 备注 |
+|------|------------------|------|
+| **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 实现 |
 
-```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#团队包)。
+文件格式与完整工作流见[使用指南](docs/usage-guide.zh-CN.md)。
 
-## Team Context
+## Team Context (beta)
 
 > Every agent understands how the team works.
 
@@ -227,7 +191,7 @@ Matched: conflict | Missing: port
 teamai import --from-repo https://github.com/org/repo
 teamai import --from-org myorg              # 批量导入所有仓库
 teamai codebase --extract /path/to/repo     # 本地提取到 teamwiki/
-teamai codebase --lint                      # 健康检查
+teamai codebase --lint --output /path/to/repo # 检查本地提取的图谱
 ```
 
 图谱存储组件、接口、配置和跨仓库依赖边。`teamai recall` 利用图谱进行增强排名。
@@ -240,10 +204,20 @@ teamai codebase --lint                      # 健康检查
 
 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 和知识的起点：
 
 | 能力 | 命令 | 呈现内容 |
@@ -289,13 +263,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) 生成。