@tencent-rtc/trtc-agent-skills 0.1.0

package/skills/trtc-search/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: trtc-search
+description: >
+  Discovers matching slices from the TRTC knowledge base given a natural-language
+  query. Use when onboarding or docs needs to find slice IDs for a feature
+  description, symptom, error code, or pattern query. Accepts (product, platform,
+  query, intent) and returns matched slices with confidence and source attribution.
+  Not user-facing — callers compose the final answer from returned results.
+---
+
+# TRTC Knowledge Base Search
+
+You search the TRTC knowledge base to find relevant atomic capabilities (slices) and integration scenarios. You handle multi-product, cross-platform searches with a structured strategy chain and return a machine-readable response.
+
+---
+
+## Response Contract (read this first)
+
+Every call returns exactly this shape. The calling skill (`docs` / `onboarding`) reads fields by name — do NOT improvise the format, do NOT collapse fields into prose.
+
+```yaml
+response:
+  status: matched | no_match | no_slice | ambiguous_product | status_planned
+  matches:                             # populated when status ∈ {matched, status_planned}; empty otherwise
+    - slice_id: <product/ability>      # e.g. live/barrage
+      confidence: high | medium | low
+      match_strategy: exact | tag | product-keyword | cross-related | fuzzy
+      content_loaded: full | summary | index-only
+      file_paths_read: [...]           # actual file paths opened this turn (relative to repo root)
+      related: [...]                   # one-hop related slice_ids NOT already in matches
+  ambiguous_candidates: [...]          # populated ONLY when status = ambiguous_product, e.g. [live, chat]
+  reason: "..."                        # populated ONLY when status ≠ matched; one-sentence cause
+```
+
+### status semantics
+
+| status | Meaning | matches | ambiguous_candidates | reason |
+|--------|---------|---------|----------------------|--------|
+| `matched` | ≥ 1 slice found with usable content | non-empty | — | — |
+| `status_planned` | slice exists in index but content not yet written | non-empty, `content_loaded: index-only` | — | "slice `<id>` is status: planned" |
+| `no_slice` | product exists but has zero slices in KB (e.g., Call, Conference at early stage) | empty | — | "product `<id>` has no slices in KB" |
+| `no_match` | search ran to exhaustion without finding relevant slices | empty | — | one-line cause (e.g., "error code 99999 not in any slice.error_codes or body text") |
+| `ambiguous_product` | product was null AND fuzzy-only hits span multiple products | empty | non-empty (e.g., `[live, chat]`) | "query plausibly matches multiple products; ask user" |
+
+### confidence → match_strategy mapping
+
+Confidence is derived from match_strategy, not judged separately:
+
+- `high` ← `exact` or `tag`
+- `medium` ← `product-keyword` or `cross-related`
+- `low` ← `fuzzy`
+
+Callers should use `confidence` for quick guards (e.g., `if response.matches[0].confidence == 'high': answer from slice, skip llms.txt`) and `match_strategy` for traceability when debugging.
+
+### What callers do with each status
+
+- `matched` → read `matches[].file_paths_read`, compose answer from slice contents.
+- `status_planned` → show the slice's index-level description; fall through to caller's fallback (docs → llms.txt).
+- `no_slice` / `no_match` → caller falls back to its own escape route (docs: llms.txt lookup; onboarding: ask user / degrade).
+- `ambiguous_product` → caller asks the user which of `ambiguous_candidates` they mean, then re-calls search with the confirmed product.
+
+---
+
+## Inputs (from calling skill: `docs` or `onboarding`)
+
+- **product**: Identified product (chat/call/rtc-engine/live/conference), or `null` if ambiguous
+- **platform**: Identified platform (web/android/ios/flutter/electron), or `null`
+- **query**: The user's original question / keywords
+- **intent**: one of the values listed below.
+
+> **Authoritative enum**: this file is the canonical source for the set of `intent` values search accepts. Callers (`docs`, `onboarding`) MUST only pass a value from this list and MUST map their own domain intent (e.g. docs' `slice-lookup`, onboarding's Path B free-text symptom) to one of these four. When this list changes, callers update their mapping tables. The list:
+
+- `error-code` — from `docs`: query contains a numeric error code. Prioritize `exact`; on miss, run full-text digit search before other strategies.
+- `pattern` — from `docs`: user asks for the official pattern of X, or compares X vs Y. Prioritize `tag`.
+- `feature` — from `docs` (implementation method lookup) or `onboarding` (user described a feature in natural language): need to find the corresponding slice ID. Prioritize `tag` / `product-keyword`. When multiple slices match, return summaries (`content_loaded: summary`) for the caller to present as a selection list.
+- `troubleshoot` — from `onboarding` Path B: user described a symptom in free text, need to find the slice(s) with relevant troubleshooting content. Match against slice troubleshooting sections and in-file `error_codes` sections.
+
+---
+
+## Search Workflow
+
+### Step 1: Read the index
+
+Read `${CLAUDE_PLUGIN_ROOT}/knowledge-base/index.yaml` to get the catalog. Fields present at the index level:
+
+- **products**: `id`, `name`, `description`, `llms_file` (`llms_file` is used by the `docs` skill, not by search)
+- **cross_product_relations**: `id`, `products`, `slices`, `description`
+- **slices**: `id`, `name`, `tags`, `platforms`, `file`, `description`, `status`
+- **scenarios**: `id`, `name`, `slices`, `file`, `description`, `status`
+
+> **Fields NOT in index.yaml** (common misconception — don't assume them on the index):
+> - `error_codes` — lives inside the slice file body as an `## 错误码` / `## error_codes` section. To check it, the `file` path must be read.
+> - `related` — same: lives inside slice file frontmatter/body, not in index.
+> - `platform_files[platform]` — there is no such index field. Platform-specific content lives at `slices/{product}/{platform}/{ability}.md` on disk. To check availability, try reading that path; if it doesn't exist, there is no platform-specific slice for that pairing.
+
+> **Out of scope**: do NOT read llms files, do NOT fetch official doc URLs. If the caller needs a doc URL (e.g., fallback when no slice matches an error code), return `status: no_match` and let the calling skill (`docs`) do the llms.txt lookup.
+
+### Step 2: Five-Strategy Matching (by priority)
+
+Try strategies in order; collect matches. Earlier strategies have higher priority. Higher priority wins on rank; ties broken by tag-intersection count.
+
+| # | match_strategy | Triggers on | How to match |
+|---|---------------|-------------|--------------|
+| 1 | `exact` | query contains a numeric error code, a known slice_id like `chat/multi-instance`, or a scenario_id | (a) If an error code: look inside each slice's `file` for its `## 错误码` / `## error_codes` section and match the code. On `intent=error-code` miss, additionally grep all slice file bodies for the digit sequence (covers codes mentioned in troubleshooting prose). (b) If a slice_id or scenario_id: direct lookup in index arrays. |
+| 2 | `tag` | after exact (or alongside when no error code) | Extract keywords from the query (LLM does Chinese↔English bidirectionally on its own; consult the "Keyword Hints" table below only for non-intuitive SDK naming). Intersect with each slice's `tags`. Rank by intersection count. |
+| 3 | `product-keyword` | `product` is set AND tag didn't produce a high-confidence hit | Within that product's slices, fuzzy-match against `name` (higher weight) and `description`. Both Chinese and English terms. |
+| 4 | `cross-related` | `tag` or `product-keyword` produced a partial hit AND either (a) query contains signals of a second product, or (b) the initial hit set feels incomplete | Expand via `cross_product_relations` entries whose `products` overlap, OR follow the already-matched slice's `related` list (read from slice file) for one hop. Fold those into matches at medium confidence. |
+| 5 | `fuzzy` | no strategy 1-4 produced anything | Last-resort: use Keyword Hints for bidirectional expansion, match against scenario `name` + `description`, or match slice `description` without tag overlap. All hits are `confidence: low`. |
+
+#### Intent-driven priority adjustments
+
+| intent | Priority hint |
+|--------|---------------|
+| `error-code` | `exact` runs first; on miss AND `intent=error-code`, run full-text digit grep before strategy 2. Return immediately on strategy-1 hit. |
+| `pattern` | Run all strategies, but rank `tag` hits above `product-keyword`. |
+| `feature` | `tag` and `product-keyword` prioritized. If ≥ 4 matches total, downgrade all `content_loaded` to `summary` so the caller can present a selection. |
+| `troubleshoot` | Prefer slices whose body has a troubleshooting section relevant to the described symptom. Check in-file `error_codes` and 排障 sections when reading for rank. |
+
+#### product=null degradation
+
+When `product` is `null`:
+
+- Strategies `exact` and `tag` run normally (they don't need product). If either yields a `confidence: high` hit, return `status: matched` — do NOT trigger ambiguity.
+- `product-keyword` is skipped (it requires product).
+- `cross-related` and `fuzzy` run as full-catalog searches, capped at **5** matches, ranked by tag-intersection count (ties: `name` match > `description` match).
+- If all remaining results are `confidence: low` (fuzzy only) AND they span ≥ 2 products, return `status: ambiguous_product` with `ambiguous_candidates` listing the distinct products seen. DO NOT return low-confidence results — force the caller to disambiguate first.
+- If fuzzy hits stay within one product, return them normally as `matched`.
+
+### Step 3: Platform Filtering
+
+If `platform` is specified:
+
+- Filter results to slices whose `platforms` array contains the requested platform.
+- Keep cross-platform overviews (slices present at `slices/{product}/{ability}.md` with no platform subpath) as secondary results — they're generally useful.
+- Framework-to-platform mapping (applied at the caller's layer but repeated here as reference):
+  - React / Vue → Web
+  - Kotlin → Android
+  - Swift / Objective-C → iOS
+  - Dart → Flutter
+
+If the user needs code but hasn't specified a platform, surface that fact via `reason` (`"platform required for code example"`) — the caller asks.
+
+### Step 4: Progressive Content Loading
+
+Set `content_loaded` per match based on result-set size:
+
+- **Top 1-3 matches in `matches[]`** → read the full slice file at `${CLAUDE_PLUGIN_ROOT}/${CLAUDE_PLUGIN_ROOT}/knowledge-base/{slice.file}`; if a platform-specific file exists at `${CLAUDE_PLUGIN_ROOT}/knowledge-base/slices/{product}/{platform}/{ability}.md`, read that too. Set `content_loaded: full`.
+- **4+ matches** (typical on `intent=feature` ambiguity) → do NOT read each file; return index-level fields only (name, description, tags). Set `content_loaded: summary`. Let the caller present a selection.
+- **Slice with `status: planned`** → do NOT try to open its `file` (it likely doesn't exist yet). Use the index description. Set `content_loaded: index-only` and set top-level `status: status_planned` on the response.
+
+Record every file actually read in `matches[].file_paths_read`. This is the caller's canonical source for "which files grounded the answer".
+
+### Step 5: Build the response
+
+Fill the Response Contract based on Step 2-4 results:
+
+| Situation | response.status | matches | extras |
+|-----------|----------------|---------|--------|
+| Strategies 1-5 produced content-loadable hits | `matched` | populated; confidence derived from match_strategy | — |
+| Hits all pointed at planned slices | `status_planned` | populated with `content_loaded: index-only` | `reason: "slice <id> is status: planned"` |
+| product exists in index but has zero slices | `no_slice` | empty | `reason: "product <id> has no slices in KB"` |
+| product=null AND only fuzzy hits spanning ≥ 2 products | `ambiguous_product` | empty | `ambiguous_candidates: [...]`, `reason: "..."` |
+| Strategies exhausted, nothing relevant at any confidence | `no_match` | empty | `reason: "..."` (be specific — error code not found / no tag overlap / etc.) |
+
+> **Display rules live with the caller**, not with search. search only reports `file_paths_read`; it does not dictate how the caller quotes code, when to include snippets, or how to render confidence. See `../trtc-docs/SKILL.md` Step 3 and `onboarding/reference/path-a2-integrate.md` slice-loading block for those rules.
+
+---
+
+## Keyword Hints (non-intuitive mappings only)
+
+Bidirectional Chinese↔English translation for common vocabulary is delegated to the LLM — it already understands that "弹幕" ≈ barrage/danmu, "美颜" ≈ beauty, "进房" ≈ enter-room. This table lists **only mappings that are NOT obvious from translation alone** — cases where the user's colloquial term differs from the SDK's internal naming.
+
+| User phrasing | SDK tag / keyword | Why it needs a hint |
+|---------------|--------------------|---------------------|
+| 互踢 | `kick-offline`, `multi-instance` | Not an SDK term; the root capability is multi-instance login conflict |
+| PK | `battle`, `BattleStore` | "PK" is colloquial; SDK names it battle |
+| 黑屏 | `setLiveID`, `black-screen` | The usual root cause is a missed `setLiveID` call, not obvious from "black screen" |
+| 跨房连线 | `co-host`, `CoHostStore` | SDK-proprietary term |
+| 连麦 | `co-guest`, `seat`, `CoGuestStore` | SDK uses `co-guest`, not the more literal `co-mic` |
+| 踢人 | `kick`, `kickUserOutOfRoom` | Exact method name is non-intuitive |
+| 音效 | `audio-effect`, `changer`, `reverb`, `ear-monitor` | Multiple sub-capabilities under one colloquial term |
+| 观众 | `audience`, `LiveAudienceStore` | Associated Store name is not what a user would guess |
+
+For any phrasing NOT listed: let the LLM do its own Chinese↔English bridging, then match against `tags` / `name` / `description` directly. Do NOT expand this table defensively with obvious translations — it only pays for its maintenance cost on the non-obvious ones.
+
+---
+
+## Edge Cases
+
+### Missing content
+
+| Scenario | status | Handling |
+|----------|--------|----------|
+| Product exists in index but has no slices (e.g., call, conference at early phase) | `no_slice` | `matches: []`, `reason: "product <id> has no slices in KB"` — caller (docs) falls back to llms.txt |
+| Matched slice has `status: planned` in index | `status_planned` | `matches[].content_loaded: index-only`, use index description; caller decides fallback |
+| Platform requested but no platform-specific file at `slices/{product}/{platform}/{ability}.md` | `matched` | Return product-level overview with `content_loaded: full`, `reason: "no platform-specific file for <platform>"` — caller tells the user in their own language that the platform-specific code example isn't yet in the KB; do NOT synthesize code |
+
+### Cross-product questions
+
+| Scenario | Handling |
+|----------|---------|
+| "直播+弹幕" (Live+Chat) | `tag` hits live/* + query contains chat signal → `cross-related` expands via `cross_product_relations` → matches include slices from both products |
+| "视频通话+聊天" (Call+Chat) | Same pattern: `tag`/`product-keyword` initial hits + `cross-related` expansion |
+| "该用哪个产品？" | Out of scope — return `no_match` with `reason: "product-selection question, not a slice lookup"`; caller (root / onboarding) handles product identification |
+
+### Search ambiguity
+
+| Scenario | Handling |
+|----------|---------|
+| Vague single-term query like "消息" with product=null | `tag` returns many chat/* hits → `matched` with `content_loaded: summary` for the top 3-5; caller presents selection |
+| Mixed Chinese-English "怎么 kick offline" | LLM bridges "kick offline" → Keyword Hints row for 互踢 → `tag` match |
+| Only an error code like "6208" | `exact` (strategy 1) → `matched`, confidence `high` |
+| Error code not in any slice | `no_match`, `reason: "error code <code> not in any slice.error_codes or body text"` — caller (docs) falls back to llms.txt |
+
+### Platform edge cases
+
+| Scenario | Handling |
+|----------|---------|
+| Conceptual question, no platform needed | Return product-level overview only; `platform` argument can be null |
+| Needs code but no platform specified | Return `matched` with whatever was found; set `reason: "platform required for code example"` — caller asks |
+| React/Vue → Web, Kotlin → Android, Swift/ObjC → iOS, Dart → Flutter | Caller normalizes; search accepts the normalized platform |