teamai-cli 0.17.6 → 0.17.7

package/README.md

@@ -79,7 +79,7 @@ hooks:
 
 ```bash
 teamai hooks list      # list effective hooks
-teamai hooks inject    # force-reconcile into all tools
+teamai hooks inject    # re-reconcile into every installed tool
 teamai hooks remove    # remove all teamai-managed hooks
 ```
 
@@ -120,7 +120,7 @@ teamai recall disable    # off: remove the subagent and rules
 teamai recall status     # show effective state (team default + user override)
 ```
 
-**Search runs via a subagent**: once enabled, `teamai pull` deploys the built-in `teamai-recall` subagent into each AI tool's `agents/` directory. The AI invokes it before a task — the subagent extracts keywords, runs the search, reads the matched source files, and returns a structured summary of team knowledge. Under the hood it shells out to the `teamai recall` command, which you can also run manually:
+**Search runs via a subagent**: once enabled, `teamai pull` deploys the built-in `teamai-recall` subagent into each AI tool's `agents/` directory. The AI invokes it before a task — the subagent extracts keywords, runs the search, reads the matched source files, and returns a structured summary of team knowledge. The subagent first runs a relevance precheck (`teamai recall --check`) and skips retrieval entirely when the task is unrelated to team knowledge. Under the hood it shells out to the `teamai recall` command, which you can also run manually:
 
 ```bash
 $ teamai recall "port conflict"
@@ -149,6 +149,7 @@ teamai codebase --lint                      # health check
 ```
 
 The graph stores components, interfaces, configs, and cross-repo import edges. `teamai recall` uses it for graph-boosted re-ranking.
+When a recall hit comes from a codebase page, the result includes a `Sources:` line listing the relevant source file paths — giving agents a direct starting point for code changes instead of re-exploring the repo.
 
 ## Commands
 

package/README.zh-CN.md

@@ -79,7 +79,7 @@ hooks:
 
 ```bash
 teamai hooks list      # 查看生效的 hooks
-teamai hooks inject    # 强制重新注入到所有工具
+teamai hooks inject    # 重新注入到每个已安装的工具
 teamai hooks remove    # 移除所有 teamai 管理的 hooks
 ```
 
@@ -120,7 +120,7 @@ teamai recall disable    # 关闭：移除子 agent 和规则
 teamai recall status     # 查看生效状态（团队默认 + 用户覆盖）
 ```
 
-**通过子 agent 检索**：开启后 `teamai pull` 会把内置的 `teamai-recall` 子 agent 部署到各 AI 工具的 `agents/` 目录。AI 在任务开始前调用它——由子 agent 提取关键词、执行检索、读取命中的源文件，最后返回结构化的团队知识摘要。子 agent 底层调用的仍是 `teamai recall` 命令，也可手动直接运行：
+**通过子 agent 检索**：开启后 `teamai pull` 会把内置的 `teamai-recall` 子 agent 部署到各 AI 工具的 `agents/` 目录。AI 在任务开始前调用它——由子 agent 提取关键词、执行检索、读取命中的源文件，最后返回结构化的团队知识摘要。subagent 会先做相关性预检（`teamai recall --check`），当任务与团队知识无关时直接跳过检索。子 agent 底层调用的仍是 `teamai recall` 命令，也可手动直接运行：
 
 ```bash
 $ teamai recall "port conflict"
@@ -149,6 +149,7 @@ teamai codebase --lint                      # 健康检查
 ```
 
 图谱存储组件、接口、配置和跨仓库依赖边。`teamai recall` 利用图谱进行增强排名。
+当召回命中 codebase 页面时，结果会附带一行 `Sources:`，列出相关源文件路径，供 agent 直接作为代码改动的入口，无需重新探索代码库。
 
 ## 命令一览
 

package/agents/teamai-recall.md

@@ -20,6 +20,22 @@ upstream API"). Treat this as your query.
 
 ## What you must do — step by step
 
+### Step 0 — Relevance precheck (fail fast)
+
+Before any classification or search, run a single lightweight precheck:
+
+```bash
+teamai recall --check "<3-6 keywords from the task>"
+```
+
+- If the output starts with `NOT_RELEVANT`: the team knowledge base has no
+  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 command fails or `teamai` is not on PATH: skip the precheck and
+  continue to Step 1 (do not block on precheck failure).
+
 ### Step 1 — Classify question type and choose retrieval depth
 
 Determine if the query matches a G-document category:
@@ -41,6 +57,13 @@ 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)
 
+**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)
+3. `dependency-paths.md` in the same project docs dir when line-level call anchors are needed
+
+(`<project>` extracted from recall result file paths, or from `router.md`.)
+
 Fallback: if no `teamwiki/`, check `~/.teamai/docs/codebase.md`. If
 none exists, silently skip.
 
@@ -80,7 +103,10 @@ For each hit returned by `teamai recall`, read the source file directly
 **For codebase hits** (path contains `teamwiki/evidence/`):
 - If the hit is a raw facts page (component.md, interface.md), prefer
   reading the corresponding **module summary** (`modules/<dir>.md`) instead —
-  it's more concise and shows dependencies.
+  it's more concise and shows dependencies. **Exception for edit queries**:
+  retain the `Sources:` file anchors from the facts page (do not discard them
+  in favour of the module summary alone); cross-reference those anchor files
+  against graph-index.json edges to surface dependency relationships.
 - If you need architectural context (why a module exists, design decisions),
   check `overview.md` in the same project directory.
 - If the hit mentions a knowledge gap (from `gaps/detected.md`), relay
@@ -113,6 +139,16 @@ Return your output in **this exact format** to the main conversation:
 - Core components: `Foo`, `Bar`, `Baz` (top 5 by reference count)
 - Architecture: <one sentence from overview.md if available>
 
+### Change entry points (edit queries only)
+
+Relevant files (from graph-index.json: first pick 1–3 entry files most relevant to the query from Sources anchors + keywords; then list only their forward direct-dep edges where `from` == entry file; skip self-edges (from == to); do not expand reverse edges — they blow up):
+- `<file_a>` ──<RELATION>──> `<file_b>`
+- ...
+
+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.
+
 ### Gaps (if relevant)
 
 ⚠️ <gap description> — do not guess answers for this area.
@@ -153,3 +189,5 @@ Return your output in **this exact format** to the main conversation:
   Gaps section so the main conversation does not hallucinate.
 - When zero hits are found but `teamwiki/` exists, check if the query
   relates to a known gap before returning "no knowledge found".
+- When `teamai recall --check` returns `NOT_RELEVANT`, do not continue — return the no-knowledge line and stop. The precheck exists to avoid wasted retrieval on unrelated tasks.
+- **Do not invent call relationships.** The "Change entry points" section must be derived solely from graph-index.json edges and dependency-paths.md. If those files are absent or do not cover the queried files, write `relation data not covered` and omit the section — do not guess.