teamai-cli 0.18.0 → 0.20.0-beta.0

package/CHANGELOG.md

@@ -6,12 +6,16 @@ All notable changes to this project will be documented in this file. See [standa
 
 ### 💥 破坏性变更
 
+- **`teamai init` 默认 scope 改为 project**（#250）：未传 `--scope` 时安装到 `<cwd>/.teamai/` 与 `<cwd>/.claude/...`，不再默认装到 `~/`。恢复旧行为：`teamai init <repo> --scope user`
+  - 远端 `teamai.yaml.scope` 不再锁定本机安装位置（`validateScopeMatch` 已移除）；本地 scope 仅由 CLI 决定
+  - 新建默认 `teamai.yaml` 不再写入 `scope:` 字段
 - **移除 `auto-recall` PostToolUse hook**：不再在 `Bash`/`Grep`/`WebSearch`/`WebFetch` 工具调用后被动、隐式地自动搜索团队知识库——这条链路噪音大、命中率低，且与更早前上线的 `teamai-recall` subagent（任务开始前主动检索，支持 codebase 图谱 drill-down、输出结构化摘要）功能重叠。已安装环境的 hooks 配置会在下次 `teamai pull` / `hooks inject` 时自动清理，无需手动迁移
   - `contribute-check` 的知识空白检测（Phase 2）改为由 `teamai recall`（手动 + `teamai-recall` subagent 均会触发）记录召回质量，缓存格式不变，功能保留
   - `TEAMAI_RECALL_DISABLED=1` 现在控制 `teamai recall` 的质量记录而非 auto-recall hook
 
 ### ✨ 新功能
 
+- **`teamai init <repo>` 位置参数**（#250）：推荐写法；`--repo` 永久保留为等价别名（无 deprecation 警告）
 - **跨 agent skills 视图**：`teamai list` 新增 `--source <repo|local|all>` 和 `--agent <id>` 参数（默认 `--source all`）。`local` / `all` 模式会扫描所有已安装 AI agent 的 skills 目录，每个 skill 标注来源 `[team]` / `[builtin]` / `[source:<name>]` / `[local-only]`。`--verbose` 时展开每个 agent 的 skill 列表与描述摘要。未安装的 agent 不出现在输出里
 - **Known agents 注册表**：内置 28 个 AI agent 路径（Claude Code / Cursor / Codex / Gemini CLI / Aider / Augment / Hermes / Copilot / KiloCode / Kiro / OpenCode / Qoder / Trae / Windsurf / WorkBuddy 等），自动检测哪些已安装。`teamai.yaml` 中显式配置的 `toolPaths` 优先生效
 - **`teamai skill` 子命令组**：

package/README.md

@@ -30,23 +30,46 @@ npm install -g teamai-cli
 
 ### Team admin / solo user
 
-Create a shared-experience repo on your git host (GitHub, TGit, or CNB), **grant write access to team members**, then have them run `teamai init --repo https://github.com/yourorg/yourrepo`.
+Create a shared-experience repo on your git host (GitHub, TGit, or CNB), **grant write access to team members**, then have them run `teamai init https://github.com/yourorg/yourrepo`.
 
 > Solo use needs no separate repo setup: `teamai init` checks the target repo and creates it automatically if it doesn't exist.
 
+> **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
 
 ```bash
-# User-scope init (default, resources installed under ~/)
-teamai init --repo https://github.com/yourorg/yourrepo
+# Project-scope init (default, resources installed under the project directory)
+cd /path/to/my-project
+teamai init https://github.com/yourorg/yourrepo
 
-# Project-scope init (resources installed under the project directory)
+# User-scope init (resources installed under ~/)
+teamai init https://github.com/yourorg/yourrepo --scope user
+
+# Optional layered setup: keep a project repo active while inheriting safe
+# resources and searchable knowledge from an initialized user-scope repo
 cd /path/to/my-project
-teamai init --repo https://github.com/yourorg/yourrepo --scope project
+teamai init https://github.com/yourorg/project-repo --inherit-user-scope
 ```
 
 Once initialized, every AI session automatically pulls the latest skills / rules and other Harness updates published by admins — no manual sync needed.
 
+### Single-repo mode (the business repo *is* the team repo)
+
+No separate team repo. Run `teamai init .` inside an existing project and its own git repo becomes the team repo:
+
+```bash
+cd /path/to/my-project
+teamai init .          # or: teamai init --self
+```
+
+- **Knowledge** (skills / rules / docs / learnings) is committed to your repo's **main branch** under `.teamai/`, so a plain `git clone` already carries the whole team setup.
+- **Reports** (member registrations, session summaries, votes, usage stats) go to a separate **`teamai-reports` orphan branch** — they never touch main.
+- **Clone = initialized.** When a teammate clones the repo, the next `teamai` command (or AI session) auto-detects the `mode: self` marker in `.teamai/teamai.yaml` and finishes local setup automatically — no need to re-type repo/role.
+- All of teamai's git operations run in isolated worktrees, so your working tree and current branch are never touched.
+
+After `teamai init .`, commit `.teamai/` (skills, rules, docs, learnings, `teamai.yaml`, `.gitignore`) and `.claude/settings.json` to main so teammates get auto-initialized on clone.
+
 > **Full usage guide:** [docs/usage-guide.md](docs/usage-guide.md) ([中文版](docs/usage-guide.zh-CN.md)) — covers everything from team creation to day-to-day use.
 
 ## Harness Management & Distribution
@@ -122,10 +145,14 @@ Beyond distributing the Harness, TeamAI organizes accumulated team experience an
 When a session ends, the Stop hook scores it by **friction** — signals that the session hit something worth remembering: you interrupted or corrected the AI, denied a tool call, or the AI had to retry failing tools. A long-but-routine session (lots of tool calls, no friction) does not trigger; a session where you actually fought a problem does. If the score is high enough, the AI suggests:
 
 ```
-建议运行 /teamai-share-learnings 总结本次 session 的经验并分享给团队。
+[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.
 ```
 
-The `/teamai-share-learnings` skill summarizes the session and pushes a learning document directly to the team repo. Each session is prompted at most once.
+The hint names the non-zero friction signals that triggered it and, when available, includes a redacted, single-line summary of the first task. The `/teamai-share-learnings` skill summarizes the session and pushes a learning document directly to the team repo. Each session is prompted at most once.
 
 ### Team Knowledge Recall
 
@@ -153,7 +180,7 @@ Author: member-b | Score: 12.0 | Tags: deploy, config
 - **Shared search index** (`search-index.json`): four categories — learnings (session experience), docs (team docs), rules (coding rules), and skills (each `SKILL.md`) — sourced from the corresponding team-repo directories, (re)built on `teamai pull` / `teamai contribute`.
 - **Codebase knowledge graph** (`teamwiki/`): produced by `teamai import`, queried live at search time.
 
-Ranking uses BM25 + graph-boost, merges dual-scope (user + project) results tagged with origin, and implicitly upvotes matched docs so good content floats up over time.
+Ranking uses BM25 + graph-boost. When the current working directory contains a project-scope config, Recall searches that project; if the project enables `--inherit-user-scope`, it then searches user knowledge, tags each result with its origin, and lets an identical project entry override the user entry. Without a project config in the current directory, Recall searches the user scope. Active-scope hits are implicitly upvoted; inherited user hits remain read-only while the project is active.
 
 ### Codebase Knowledge Graph
 

package/README.zh-CN.md

@@ -30,23 +30,46 @@ npm install -g teamai-cli
 
 ### 团队管理员 / 个人使用者
 
-在 Git 托管平台（GitHub、TGit 或 CNB）创建共享经验仓库，**授予团队成员写权限**，然后让他们运行 `teamai init --repo https://github.com/yourorg/yourrepo`。
+在 Git 托管平台（GitHub、TGit 或 CNB）创建共享经验仓库，**授予团队成员写权限**，然后让他们运行 `teamai init https://github.com/yourorg/yourrepo`。
 
 > 个人使用无需单独建仓：`teamai init` 会检查目标仓库，不存在时自动创建。
 
+> **还没有团队仓库？** 可以从内置了成套 skills、rules、review agents 的模板起步。浏览 [teamai-hub](https://github.com/teamai-hub) org，点 **Use this template** 生成自己的仓库，再对它执行 `teamai init`。
+
 ### 团队成员
 
 ```bash
-# 用户级初始化（默认，资源安装到 ~/ 下）
-teamai init --repo https://github.com/yourorg/yourrepo
+# 项目级初始化（默认，资源安装到项目目录下）
+cd /path/to/my-project
+teamai init https://github.com/yourorg/yourrepo
 
-# 项目级初始化（资源安装到项目目录下）
+# 用户级初始化（资源安装到 ~/ 下）
+teamai init https://github.com/yourorg/yourrepo --scope user
+
+# 可选的分层模式：项目仓库保持为当前 scope，同时继承已初始化的
+# user scope 中的安全资源和可检索知识
 cd /path/to/my-project
-teamai init --repo https://github.com/yourorg/yourrepo --scope project
+teamai init https://github.com/yourorg/project-repo --inherit-user-scope
 ```
 
 初始化完成后，每次开启 AI 会话时都会自动拉取管理员发布的 skills / rules 等 Harness 更新，无需手动同步。
 
+### 单仓模式（业务仓即团队仓）
+
+无需单独的团队仓库。在已有项目里运行 `teamai init .`，让它自己的 git 仓库直接充当团队仓：
+
+```bash
+cd /path/to/my-project
+teamai init .          # 或：teamai init --self
+```
+
+- **知识资产**（skills / rules / docs / learnings）提交到仓库 **main 分支**的 `.teamai/` 目录，因此一次普通 `git clone` 就带上了整套团队配置。
+- **上报数据**（成员注册、会话摘要、投票、使用统计）走独立的 **`teamai-reports` 孤儿分支** —— 永不污染 main。
+- **克隆即初始化。** 团队成员 clone 仓库后，下一条 `teamai` 命令（或 AI 会话）会自动识别 `.teamai/teamai.yaml` 里的 `mode: self` 标记并自动完成本机初始化 —— 无需手抄 repo/role 参数。
+- teamai 的所有 git 操作都在隔离的 worktree 中进行，绝不触碰你的工作区和当前分支。
+
+执行 `teamai init .` 后，把 `.teamai/`（skills、rules、docs、learnings、`teamai.yaml`、`.gitignore`）和 `.claude/settings.json` 提交到 main，团队成员 clone 后即可自动初始化。
+
 > **完整使用指南**：[docs/usage-guide.zh-CN.md](docs/usage-guide.zh-CN.md)（[English](docs/usage-guide.md)）— 涵盖从团队创建到日常使用的全流程。
 
 ## Harness 管理和分发
@@ -119,13 +142,17 @@ teamai source remove other-team
 
 ### 自动经验沉淀
 
-Session 结束时，Stop hook 按**摩擦信号**对 session 评分——这些信号表明本次 session 踩到了值得记录的东西：你打断或纠正了 AI、拒绝了某次工具调用，或 AI 反复重试出错的工具。又长又顺（工具调用很多但没有摩擦）的 session 不会触发；真正较劲过的 session 才会。达标后 AI 会建议：
+Session 结束时，Stop hook 按**摩擦信号**对 session 评分——这些信号表明本次 session 踩到了值得记录的东西：你打断或纠正了 AI、拒绝了某次工具调用，或 AI 反复重试出错的工具。又长又顺（工具调用很多但没有摩擦）的 session 不会触发；真正较劲过的 session 才会。达标后 AI 会显示如下英文提示：
 
 ```
-建议运行 /teamai-share-learnings 总结本次 session 的经验并分享给团队。
+[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 最多提示一次。
+提示会列出实际触发它的非零摩擦信号；如果能取得首个任务摘要，还会在脱敏、单行化后附上任务上下文。`/teamai-share-learnings` skill 自动总结 session 经验并推送到团队仓库。每个 session 最多提示一次。
 
 ### 团队知识检索
 
@@ -153,7 +180,7 @@ Author: member-b | Score: 12.0 | Tags: deploy, config
 - **共享检索索引**（`search-index.json`）：learnings（session 经验）、docs（团队文档）、rules（编码规则）、skills（各 `SKILL.md`）四类，源自团队仓库对应目录，在 `teamai pull` / `teamai contribute` 时构建重建。
 - **代码知识图谱**（`teamwiki/`）：由 `teamai import` 生成，检索时实时查询。
 
-排序采用 BM25 + 图谱增强，合并用户 / 项目双 scope 结果并标注来源；搜索会隐式为命中文档投票，优质内容自然上浮。
+排序采用 BM25 + 图谱增强。当前工作目录包含 project scope 配置时，Recall 先检索该项目；如果项目启用了 `--inherit-user-scope`，再检索 user 知识并标注结果来源，相同条目由 project 版本覆盖 user 版本。当前目录没有 project 配置时，Recall 检索 user scope。当前 scope 的命中会隐式投票，项目运行期间继承的 user 命中保持只读。
 
 ### 代码知识图谱
 

package/agents/teamai-recall.md

@@ -32,10 +32,40 @@ teamai recall --check "<3-6 keywords from the task>"
   meaningful coverage for this task. Emit exactly one line
   `No relevant team knowledge found for: <query>` and **stop** — do not
   proceed to Step 1–5, do not read any files, do not run a full recall.
-- If the output starts with `RELEVANT`: continue to Step 1.
+- If the output starts with `RELEVANT`: check complexity (see below),
+  then continue to Step 1 or take the LOW shortcut.
 - If the command fails or `teamai` is not on PATH: skip the precheck and
   continue to Step 1 (do not block on precheck failure).
 
+#### Complexity quick-judge (after RELEVANT)
+
+> **Format dependency**: The LOW shortcut parses `title=` and `sources=` from `--check` stdout. If `emitCheckVerdict` output format changes, update this section.
+
+Scan the original task description for complexity signals:
+
+**LOW signals** (all must hold):
+- Task targets a single file or a single field/parameter change
+- Keywords present: 改名/rename/修改名称/修改字段/add parameter/加参数/
+  改配置/change config/update constant/修改常量/加个字段/加一个参数
+- No multi-module interaction, no new flow/controller/class creation
+
+**If LOW and `--check` output includes `title=` and `sources=`**: use them
+directly to construct a short response (≤500 chars):
+
+```
+Relevant knowledge: <title from --check output>
+Suggested files: <sources from --check output>
+<!-- teamai:recalled-doc-ids: [] -->
+```
+
+**Stop here** — skip Steps 1–5 entirely.
+
+**If LOW but `--check` output lacks `sources=`**: run
+`teamai recall <keywords> --depth context`, take only the top-1 result's
+title + Sources, return the same short format above, and skip Steps 1–5.
+
+**If not LOW**: continue to Step 1 as normal.
+
 ### Step 1 — Classify question type and choose retrieval depth
 
 Determine if the query matches a G-document category:
@@ -57,6 +87,19 @@ corresponding file and extract relevant sections. Skip BM25 search.
 > - `--depth lookup`: searches ALL evidence pages including raw symbol lists (for precise file:line lookups)
 > - `--depth route`: returns the router table only (use when you need to discover what projects exist)
 
+**Task complexity heuristic — choose depth by task type:**
+
+| Signal in query | Task type | Depth | Rationale |
+|-----------------|-----------|-------|-----------|
+| feature/新功能/新增功能/大功能/redesign/重构整个/multi-file | Feature (large) | `--depth lookup` | Need full file coverage to avoid missing files |
+| 添加/修改/如何改/实现/implement/refactor | Edit (medium) | `--depth lookup` | Need symbol-level anchors |
+| bugfix/修复/fix/patch/typo/单文件/one-file | Bugfix (small) | `--depth context` | Fast pass; skip graph-index drill-down |
+
+For **bugfix/small** tasks: use `--depth context` only, skip the
+graph-index.json deep read in the edit/change section below, and keep
+output ≤ 1500 characters. The main conversation already knows which
+file to fix.
+
 **Edit/change queries** (keywords: 新增/添加/修改/如何改/重构/实现; how to add/change/modify/implement): use `--depth lookup` in Step 3 so facts/relation pages are visible. After BM25 recall, also read these directly (bypassing BM25 ranking uncertainty):
 1. `teamwiki/evidence/code/<project>/.indices/graph-index.json` (priority; fall back to `teamwiki/.indices/graph-index.json` if absent) — when surfacing edges, pick 1–3 entry files most relevant to the task and read only their forward direct-dep edges (`from` == entry file); skip reverse expansion (each edge: `{from, to, relation}` — from/to are file paths, relation is type e.g. DEPENDS_ON)
 2. `Sources:` file anchors listed in any matching facts pages (component.md / interface.md)
@@ -149,6 +192,16 @@ Suggested reading order: <contract/types first> → <impl> → ...
 
 > Edges capped at 10; see graph-index.json for full graph. Keep this section ≤ 300 characters. Omit this section for non-edit queries.
 
+### Candidate change files
+
+If the `teamai recall` output contains a
+`--- Candidate change files ---` section, reproduce it here verbatim.
+These are source files and their forward dependencies from the code
+graph — the main conversation should check whether its planned
+changes cover all of them.
+
+If no candidate files section was returned, omit this heading entirely.
+
 ### Gaps (if relevant)
 
 ⚠️ <gap description> — do not guess answers for this area.