teamai-cli 0.16.7 → 0.16.9

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="assets/teamai-cli-logo.svg" alt="teamai-cli" width="430">
+</p>
+
 # TeamAI — The team harness for AI agents
 
 > [English](README.md) | [简体中文](README.zh-CN.md)
@@ -79,8 +83,17 @@ The CLI picks a provider automatically from the repo URL:
 | `teamai source` | Manage cross-team skill subscription sources (`add`/`remove`/`list`/`browse`) |
 | `teamai contribute --file <path> [--scope <user\|project>]` | Push an AI-generated experience document to the team repo |
 | `teamai recall <query>` | Search the team knowledge base, automatically merging user + project scope results |
+| `teamai import --from-repo <url>` | Clone a remote repo and generate a per-repo summary under `docs/team-codebase/repos/<slug>.md`; AI recommends a business domain and persists the assignment to `.teamai/domains.yaml` |
+| `teamai import --from-repo-list <yaml>` | Batch import a whitelist of repos with concurrency control, then aggregate the results into per-domain views |
+| `teamai import --from-org <org> --bootstrap` | List every repo under an organization (GitHub or TGit), AI-cluster them into business domains, and run an interactive review before the first full sync |
+| `teamai import --from-iwiki <id> [--iwiki-dual]` | Import iWiki documents as learnings; in dual mode also extract business-API / external-knowledge / glossary sections into `docs/team-codebase/external-knowledge.md` |
+| `teamai cache --status \| --gc` | Inspect or garbage-collect the shallow-clone cache at `~/.teamai/cache/repos/` (LRU + size cap, default 5GB) |
+| `teamai codebase --lint [--fix]` | Cross-file consistency lint over `docs/team-codebase` and `.teamai/`; reports anchor / orphan / source-invalid / sync-stale issues; `--fix` applies low-risk mechanical fixes |
+| `teamai review [id] [--apply \| --reject \| --all-apply]` | Inspect and process pending codebase changes from `.teamai/pending-review.jsonl`; `--apply` patches in place via section anchors |
+| `teamai domains drift [url] [--apply \| --lock \| --apply-all]` | Inspect and resolve domain-drift signals; `--apply` reassigns the repo to the recommended domain and refreshes the aggregate views |
 | `teamai digest` | Generate a team AI usage weekly digest (skill leaderboard, new/updated skills, session summaries) |
 | `teamai hooks` | Manage AI-tool hooks (list / inject / remove) |
+| `teamai ci extract-mr --url <url> [--mode comment\|write\|both] [--individual-comments]` | CI pipeline integration: extract knowledge from MR/PR, post as comments, and write to team repo after merge. With `--individual-comments`, each suggestion is posted separately with reaction/reject support (GitHub 👎 / TGit ☝️) |
 | `teamai uninstall [--force]` | Uninstall teamai: remove hooks, rules, skills, env, docs, and `~/.teamai/` |
 | `teamai doctor` | Diagnose configuration problems |
 
@@ -292,6 +305,42 @@ Author: alice | Score: 12.0 | Tags: fuse, deploy
 - Searches implicitly upvote matched docs; good docs naturally float up over time.
 - Votes are written to each scope's own repo, so attribution stays correct.
 
+`teamai recall` results carry a `[<type>]` tag so callers can quickly tell which knowledge bucket a hit came from. The shared search index covers four categories:
+
+| Type | Source | Notes |
+|------|--------|-------|
+| `[learnings]` | `~/.teamai/learnings/*.md` | session experience documents |
+| `[docs]` | team repo `docs/**/*.md` | shared project knowledge |
+| `[rules]` | team repo `rules/**/*.md` | coding rules and conventions |
+| `[skills]` | team repo `skills/<name>/SKILL.md` | reusable AI skills |
+
+The index is rebuilt automatically on every `teamai pull`. Indexes built by older versions (no `version` field or missing `type`) are detected and rebuilt transparently on first use.
+
+### TodoWrite reminder hook
+
+`teamai pull` registers a PostToolUse hook on the `TodoWrite` tool. The first time a session writes a TODO list, the hook injects a one-time reminder asking the agent to invoke `teamai-recall` if it has not already done so. Per-session deduplication uses `~/.teamai/sessions/<sid>-todowrite-hint.json` (24 h TTL).
+
+To disable the reminder globally, set:
+
+```bash
+export TEAMAI_RECALL_DISABLED=1
+```
+
+The same env var also disables the auto-recall hook.
+
+### `agents` resource type
+
+The team repo can ship custom subagent definitions under a flat `agents/` directory (one `*.md` file per agent). They follow the same push / pull / remove semantics as `rules`:
+
+```text
+team-repo/
+  agents/
+    code-reviewer.md      # team-authored subagent
+    .removed              # tombstone (auto-managed by `teamai remove agents <name>`)
+```
+
+`teamai pull` copies them into every Tier-1 tool's `agents/` directory (e.g. `~/.claude/agents/`). The CLI built-in `teamai-recall.md` is deployed alongside team agents and is **excluded** from `teamai push` (it is CLI-managed, not team-managed).
+
 ## Update
 
 ```bash
@@ -317,6 +366,42 @@ Auto-update runs on the Stop hook at the end of a session. It can be controlled
 
 The user-level `updatePolicy` always wins over the team-level `autoUpdate`.
 
+## CI Integration
+
+TeamAI can integrate into your CI pipeline to automatically extract knowledge from every MR/PR:
+
+```
+MR opened/updated → CI extracts learning + codebase suggestions → posts as comments
+    → Reviewer rejects unwanted suggestions (GitHub 👎 / TGit ☝️)
+    → MR merged → CI writes approved items to team knowledge repo
+```
+
+### Quick Start
+
+```bash
+# Comment mode: post suggestions to MR (run on PR open/update)
+teamai ci extract-mr --url "$MR_URL" --mode comment --individual-comments
+
+# Write mode: write approved items to knowledge repo (run after merge)
+teamai ci extract-mr --url "$MR_URL" --mode write --team-repo ./team-repo --individual-comments
+```
+
+### CI Templates
+
+Ready-to-use templates in `examples/ci/`:
+
+| File | Platform |
+|------|----------|
+| `github-actions-mr-extract.yml` | GitHub Actions |
+| `coding-ci-mr-extract.yaml` | Coding CI (TGit + ZhiYan QCI) |
+
+### Reject Interaction
+
+| Platform | How to reject | Default |
+|----------|--------------|---------|
+| GitHub | Add 👎 reaction to the suggestion comment | Write all |
+| TGit | Add ☝️ emoji to the suggestion note | Write all |
+
 ## License
 
 [MIT](LICENSE)

package/README.zh-CN.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="assets/teamai-cli-logo.svg" alt="teamai-cli" width="430">
+</p>
+
 # TeamAI — The team harness for AI agents
 
 > [English](README.md) | [简体中文](README.zh-CN.md)
@@ -79,8 +83,17 @@ CLI 会根据用户传入的 repo URL 自动选择 provider：
 | `teamai source` | 管理跨团队 skill 订阅源（`add`/`remove`/`list`/`browse`） |
 | `teamai contribute --file <path> [--scope <user\|project>]` | 将 AI 生成的经验文档推送到团队仓库 |
 | `teamai recall <query>` | 搜索团队知识库，自动合并 user + project 双 scope 结果 |
+| `teamai import --from-repo <url>` | 拉取远端仓库并生成单仓视图 `docs/team-codebase/repos/<slug>.md`；AI 推荐业务域并写入 `.teamai/domains.yaml` |
+| `teamai import --from-repo-list <yaml>` | 按白名单批量导入多个仓库（支持并发），并按业务域聚合产出 |
+| `teamai import --from-org <org> --bootstrap` | 列出组织/group 下所有仓库（GitHub / TGit），AI 聚类为业务域，交互式 review 后完成首次全量同步 |
+| `teamai import --from-iwiki <id> [--iwiki-dual]` | 把 iWiki 文档导入为 learnings；dual 模式同时把业务接口 / 外部知识源 / 术语表抽取到 `docs/team-codebase/external-knowledge.md` |
+| `teamai cache --status \| --gc` | 查看或回收 shallow-clone 缓存目录 `~/.teamai/cache/repos/`（LRU + 容量上限，默认 5GB） |
+| `teamai codebase --lint [--fix]` | 对 `docs/team-codebase` 与 `.teamai/` 做跨文件一致性 lint；报告锚点 / 孤儿 / 源失效 / 同步陈旧等问题；`--fix` 应用低风险机械修复 |
+| `teamai review [id] [--apply \| --reject \| --all-apply]` | 浏览并处理 `.teamai/pending-review.jsonl` 中的待审 codebase 变更；`--apply` 通过章节锚点原地写入 |
+| `teamai domains drift [url] [--apply \| --lock \| --apply-all]` | 浏览并处理域漂移信号；`--apply` 把仓库重新归类到推荐域并刷新聚合视图 |
 | `teamai digest` | 生成团队 AI 使用周报（skill 排行、新增/更新 skill、session 摘要） |
 | `teamai hooks` | 管理 AI 工具 hooks（list / inject / remove） |
+| `teamai ci extract-mr --url <url> [--mode comment\|write\|both] [--individual-comments]` | CI 流水线集成：从 MR/PR 中提取知识，发布为评论，合并后写入团队知识仓库。使用 `--individual-comments` 时每条建议单独发布，支持 reaction/reject 交互（GitHub 👎 / TGit ☝️） |
 | `teamai uninstall [--force]` | 卸载 teamai：移除 hooks、rules、skills、env、docs、~/.teamai/ |
 | `teamai doctor` | 诊断配置问题 |
 
@@ -292,6 +305,42 @@ Author: alice | Score: 12.0 | Tags: fuse, deploy
 - 搜索自动投票，好文档自然浮到顶部
 - 投票按 scope 分别写入各自的 repo，归属正确
 
+`teamai recall` 的输出会给每条命中前置 `[<type>]` 标签，方便调用方快速判断知识来源。共享检索索引覆盖四类内容：
+
+| 类型 | 源路径 | 说明 |
+|------|--------|------|
+| `[learnings]` | `~/.teamai/learnings/*.md` | session 经验文档 |
+| `[docs]` | 团队仓库 `docs/**/*.md` | 共享项目知识 |
+| `[rules]` | 团队仓库 `rules/**/*.md` | 编码规则和约定 |
+| `[skills]` | 团队仓库 `skills/<name>/SKILL.md` | 可复用 AI skill |
+
+索引在每次 `teamai pull` 时自动重建。旧版索引（无 `version` 字段或缺少 `type`）会在首次使用时被自动检测并重建，对调用方透明
+
+### TodoWrite 提醒 hook
+
+`teamai pull` 会在 `TodoWrite` 工具上注册一个 PostToolUse hook。当 session 第一次写 TODO 列表时，hook 会注入一次性提醒，要求 agent 在尚未调用 `teamai-recall` 时先调用一次。session 级去重通过 `~/.teamai/sessions/<sid>-todowrite-hint.json` 实现（TTL 24 小时）
+
+如果要全局关闭该提醒，请设置：
+
+```bash
+export TEAMAI_RECALL_DISABLED=1
+```
+
+该环境变量同时也会关闭 auto-recall hook
+
+### `agents` 资源类型
+
+团队仓库可以在扁平的 `agents/` 目录下放置自定义 subagent 定义（每个 agent 一个 `*.md`），push / pull / remove 语义与 `rules` 保持一致：
+
+```text
+team-repo/
+  agents/
+    code-reviewer.md      # 团队作者编写的 subagent
+    .removed              # tombstone（由 `teamai remove agents <name>` 自动管理）
+```
+
+`teamai pull` 会把它们复制到每个 Tier-1 工具的 `agents/` 目录（例如 `~/.claude/agents/`）。CLI 内置的 `teamai-recall.md` 会与团队 agents 一起部署，并在 `teamai push` 时被自动排除（由 CLI 管理，不归团队仓库）
+
 ## 更新
 
 ```bash
@@ -317,6 +366,42 @@ npm update -g teamai-cli   # 或手动触发 npm 升级
 
 用户级 `updatePolicy` 始终优先于团队级 `autoUpdate`。
 
+## CI 集成
+
+TeamAI 可以集成到 CI 流水线中，从每次 MR/PR 自动提取知识：
+
+```
+MR 创建/更新 → CI 提取 learning + codebase 建议 → 以评论形式发布
+    → Reviewer 拒绝不需要的建议（GitHub 👎 / TGit ☝️）
+    → MR 合并 → CI 将已通过的条目写入团队知识仓库
+```
+
+### 快速开始
+
+```bash
+# Comment 模式：将建议发布到 MR（在 PR 打开/更新时运行）
+teamai ci extract-mr --url "$MR_URL" --mode comment --individual-comments
+
+# Write 模式：将已通过的条目写入知识仓库（在合并后运行）
+teamai ci extract-mr --url "$MR_URL" --mode write --team-repo ./team-repo --individual-comments
+```
+
+### CI 模板
+
+`examples/ci/` 目录下提供了开箱即用的模板：
+
+| 文件 | 平台 |
+|------|------|
+| `github-actions-mr-extract.yml` | GitHub Actions |
+| `coding-ci-mr-extract.yaml` | Coding CI（TGit + 智研 QCI） |
+
+### 拒绝交互
+
+| 平台 | 拒绝方式 | 默认行为 |
+|------|---------|---------|
+| GitHub | 对建议评论添加 👎 reaction | 全部写入 |
+| TGit | 对建议 note 添加 ☝️ emoji | 全部写入 |
+
 ## 许可证
 
 [MIT](LICENSE)

package/agents/teamai-recall.md

@@ -0,0 +1,97 @@
+---
+name: teamai-recall
+description: Search the team knowledge base (skills + learnings + docs + rules) and return a compact, structured summary with doc_ids — instead of dumping full knowledge content into the main conversation. Invoke this BEFORE any task involving code changes, troubleshooting, or design.
+tools: Bash, Read, Grep, Glob
+---
+
+# teamai-recall
+
+You are a knowledge retrieval agent for the **teamai** ecosystem. Your sole
+job is to search the local team knowledge base and return a **compact**
+structured summary to the main conversation. The main conversation will
+delegate tasks to you so its own context window is not polluted by raw
+knowledge content.
+
+## When you are invoked
+
+The main conversation invokes you with a **natural language task description**
+as input (e.g. "fix flaky integration tests", "design retry policy for
+upstream API"). Treat this as your query.
+
+## What you must do — step by step
+
+### Step 1 — Read the codebase manifest (optional but preferred)
+
+If `~/.teamai/docs/codebase.md` OR `docs/team-codebase/index.md` (in the
+current project) exists, read it first. It lists the team's repositories
+and their purposes. Extract a one-sentence repo-list summary to prepend to
+your final output. If neither file exists, **silently skip** this step —
+never error out.
+
+> Note: `teamai recall` already indexes team-codebase documents
+> (repos/*.md), so Step 3 will return codebase knowledge matches directly.
+
+### Step 2 — Extract keywords from the task description
+
+Pick 3–6 high-signal keywords from the user query. Strip filler words
+("the", "how", "please"). Mix English and Chinese terms when both appear.
+
+### Step 3 — Run the teamai recall command
+
+Execute:
+
+```bash
+teamai recall "<keyword1> <keyword2> ..."
+```
+
+This searches all four knowledge categories (`skills`, `learnings`,
+`docs`, `rules`) via the local search index. Capture the full output.
+
+If the command fails, knowledge base is empty, or returns zero hits,
+emit a single line `No relevant team knowledge found for: <query>` and
+stop.
+
+### Step 4 — Read the top hits
+
+For each hit returned by `teamai recall`, read the source file directly
+(use `Read`) and condense each into **one or two sentences**. Cap your
+total summary at ~1500 characters. Drop hits that on closer inspection
+are clearly off-topic.
+
+### Step 5 — Emit a structured response
+
+Return your output in **this exact format** to the main conversation:
+
+```
+## Team Knowledge Recall
+
+> Repos: <one-line repo summary from codebase.md, or omit this line>
+
+1. **[<type>] <doc_id>** — <file path>
+   <one-sentence summary>
+   Confidence: <high | medium | low>
+
+2. **[<type>] <doc_id>** — <file path>
+   <one-sentence summary>
+   Confidence: <high | medium | low>
+
+...
+
+<!-- teamai:recalled-doc-ids: [<id1>, <id2>, ...] -->
+```
+
+Where:
+- `<type>` is one of `skills` / `learnings` / `docs` / `rules`
+- `<doc_id>` is the filename without extension (e.g. `api-timeout-fix`)
+- The trailing HTML comment **must** list every doc_id you returned —
+  later phases (Phase 3 Stop hook) will parse this from the conversation
+  transcript.
+
+## Hard rules
+
+- **Do not** copy entire file contents into your response. Summarize.
+- **Do not** call `teamai recall` more than 3 times in one invocation.
+- **Do not** invoke other subagents.
+- If `teamai` CLI is not on PATH, return `teamai CLI not available` and stop.
+- Output total ≤ ~2000 characters. The whole point of using a subagent is
+  to keep the main conversation's context lean.