teamai-cli 0.16.8 → 0.17.0

package/agents/teamai-recall.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Search the team knowledge base (skills + learnings + docs + rules + codebase graph) 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
 ---
 
@@ -20,16 +20,29 @@ upstream API"). Treat this as your query.
 
 ## What you must do — step by step
 
-### Step 1 — Read the codebase manifest (optional but preferred)
+### Step 1 — Classify question type and choose retrieval depth
 
-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.
+Determine if the query matches a G-document category:
 
-> Note: `teamai recall` already indexes team-codebase documents
-> (repos/*.md), so Step 3 will return codebase knowledge matches directly.
+| 问题关键词 | 类型 | 直接读取 |
+|-----------|------|---------|
+| 依赖/上游/下游/谁调用 | G1 | `teamwiki/evidence/code/<project>/docs/graph-g1-relations.md` |
+| 调用链/数据流/请求路径 | G2 | `teamwiki/evidence/code/<project>/docs/graph-g2-dataflow.md` |
+| 流程/场景/完整流程 | G5 | `teamwiki/evidence/code/<project>/docs/graph-g5-scenarios.md` |
+| 传递依赖/爆炸半径/影响 | G6 | `teamwiki/evidence/code/<project>/docs/graph-g6-multihop.md` |
+
+**If the query clearly matches a G-document type**: directly Read the
+corresponding file and extract relevant sections. Skip BM25 search.
+
+**Otherwise**: proceed to Step 2–3 for BM25 keyword search.
+
+> `teamai recall` supports three depth levels:
+> - `--depth context` (default): searches overview + modules + docs (best for most queries)
+> - `--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)
+
+Fallback: if no `teamwiki/`, check `~/.teamai/docs/codebase.md`. If
+none exists, silently skip.
 
 ### Step 2 — Extract keywords from the task description
 
@@ -38,25 +51,42 @@ Pick 3–6 high-signal keywords from the user query. Strip filler words
 
 ### Step 3 — Run the teamai recall command
 
-Execute:
+Execute with the appropriate depth:
 
 ```bash
+# Default: searches overview, modules, and docs (context layer)
 teamai recall "<keyword1> <keyword2> ..."
+
+# For precise symbol/line-number lookups, use lookup depth:
+teamai recall --depth lookup "<keyword1> <keyword2> ..."
 ```
 
 This searches all four knowledge categories (`skills`, `learnings`,
-`docs`, `rules`) via the local search index. Capture the full output.
+`docs`, `rules`) via the local search index, plus the codebase graph
+in `teamwiki/` with BM25 + graph-boost. Capture the full output.
+
+If the first call returns insufficient results, you may retry once with
+`--depth lookup` to broaden the search to raw symbol pages.
 
 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
+### Step 4 — Read the top hits and drill into codebase
 
 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.
+(use `Read`) and condense each into **one or two sentences**.
+
+**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.
+- 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
+  it to the user: "This area is not fully documented in the knowledge base."
+
+Cap your total summary at ~2000 characters. Drop hits that are off-topic.
 
 ### Step 5 — Emit a structured response
 
@@ -65,24 +95,43 @@ 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>
+> Repos: <one-line repo summary from router.md, or omit>
+
+### Relevant knowledge
 
 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>
+2. ...
+
+### Codebase context (if any codebase hits)
+
+**Module: <module_name>** (<project>)
+- Depends on: <list>
+- Depended by: <list>
+- Core components: `Foo`, `Bar`, `Baz` (top 5 by reference count)
+- Architecture: <one sentence from overview.md if available>
+
+### Gaps (if relevant)
 
-...
+⚠️ <gap description> — do not guess answers for this area.
 
 <!-- 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`)
+**Output structure rules:**
+
+- `<type>` is one of `skills` / `learnings` / `docs` / `rules` / `codebase`
+- `<doc_id>` is the filename without extension (e.g. `api-timeout-fix`).
+  For codebase hits, use the relative path within teamwiki/ (e.g. `evidence/code/hai_api/modules/business`)
+- **Codebase context section**: when a codebase hit is returned, include
+  the module's dependency direction and top 5 components **inline** — the
+  main conversation should not need a second Read to understand the module.
+  Extract this from `modules/<dir>.md` which you already read in Step 4.
+- **Gaps section**: only include if `gaps/detected.md` was relevant to the
+  query. This tells the main conversation to stop and ask the user rather
+  than hallucinating.
 - The trailing HTML comment **must** list every doc_id you returned —
   later phases (Phase 3 Stop hook) will parse this from the conversation
   transcript.
@@ -93,5 +142,13 @@ Where:
 - **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
+- Output total ≤ ~2500 characters. The whole point of using a subagent is
   to keep the main conversation's context lean.
+- For codebase hits, **prefer module summaries over raw facts pages** —
+  they give better signal-to-noise for the main conversation.
+- **Include module dependency + core components inline** so the main
+  conversation can act without a second retrieval round-trip.
+- If `teamwiki/gaps/detected.md` exists and is relevant, include the
+  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".