Topic Index Command

Overview

Resolve xlb query phrases into a title command for the local API, then return Markdown index content.

When to Use

• User input contains xlb as a query trigger.
• User gives >.../ command directly and expects passthrough.
• User asks for topic index/navigation instead of narrative explanation.
• User wants direct Markdown output from the knowledge source.

Interaction Rule

• If input matches any trigger pattern below, execute directly without extra questions.
• If input mentions xlb but no topic can be extracted, ask:
  • 请发送你要查询的指令，例如：xlb >Vibe Coding/AI超元域 或 xlb ??Vibe Coding

Trigger Mapping

• xlb >vibe coding/vib -> title=>vibe coding/vib (strip xlb , payload passthrough)
• xlb ??vibe coding -> title=??vibe coding (strip xlb , payload passthrough)
• xlb ->vibe coding/: -> title=->vibe coding/: (strip xlb , payload passthrough to API)
• xlb >vibe coding/searchin: -> title=>vibe coding/searchin: (related-topic edges only)
• xlb >vibe coding/command: -> title=>vibe coding/command: (executable command edges only)
• 查询xlb vibe coding主题 -> title=>vibe coding/
• >AI Model/ -> title=>AI Model/ (direct passthrough)

Execute

Run:

skills/xlb-topic-index/scripts/fetch-topic-index.sh "xlb ??Vibe Coding"

The script performs:

• POST http://localhost:5000/getPluginInfo
• form fields:
  • title=<resolved command>
  • url=
  • markdown=

Output Rule

• Return API response Markdown directly.
• Do not paraphrase unless the user asks for analysis.

Local URL Opening (built-in, no external dependency)

• This project has native URL-open capability for local apps, no dependency on /Users/wowdd1/App/*.sh.
• Single URL:
  • skills/xlb-topic-index/scripts/xlb-open-url.sh "https://example.com" chrome
  • python3 skills/xlb-topic-index/scripts/xlb_rag_pipeline.py open-url --url "https://example.com" --app chrome
  • python3 skills/xlb-topic-index/scripts/xlb_rag_pipeline.py open-url --url "https://example.com" --app dia
  • python3 skills/xlb-topic-index/scripts/xlb_rag_pipeline.py open-url --url "https://example.com" --app atlas
• Open links from search result JSON:
  • python3 skills/xlb-topic-index/scripts/xlb_rag_pipeline.py open-hits --hits-json-file /tmp/xlb-search.json --app chrome --limit 3
• Optional integration with retrieve script:
  • XLB_OPEN_HITS=1 XLB_OPEN_APP=chrome XLB_OPEN_LIMIT=2 skills/xlb-topic-index/scripts/retrieve-topic-index.sh "xlb >vibe coding/:" "codex cli"

Capability Routing Rule (for network content)

• Before fetching external URL content, discover capabilities each run:
  • python3 skills/xlb-topic-index/scripts/xlb_rag_pipeline.py discover
• If discover result contains suitable network skills or MCP tools, use them first.
• If no suitable skill/MCP capability exists, fallback to this skill's local scripts.
• Fallback policy: this skill must always remain runnable standalone (no hard dependency on external skills).
• Optional external route hook:
  • Set XLB_EXTERNAL_ROUTE_CMD=/path/to/command
  • Command contract: cmd "<input>" "<retrieval_query>" and prints final output when it handles the request.
  • If external command exits non-zero or prints empty, fallback to local pipeline.

Code Retrieval Mode (efficient)

• Use code-based retrieval instead of full markdown dump when user asks to search/analyze:
  • skills/xlb-topic-index/scripts/retrieve-topic-index.sh "xlb >vibe coding/coding" "codex cli"
• This mode does:
  1. Cache raw markdown
  2. Incremental update: if raw hash unchanged, skip re-ingest
  3. Parse markdown to virtual file tree
  4. Build sqlite index
  5. Optional concurrent prefetch of top-k URLs (XLB_PREFETCH_ARTIFACTS=1)
     • HTML links are converted to markdown/text artifacts (not stored as raw HTML)
     • External HTML converter is optional and preferred when configured
  6. Return top-k hits by query, or iterative rounds with stop strategy (XLB_ITERATIVE_SEARCH=1)

Performance Flags

• XLB_FORCE_REFRESH=1 force refresh markdown from API
• XLB_RAW_CACHE_TTL_SEC=300 raw cache TTL value used only when XLB_AUTO_REFRESH_ON_QUERY=1
• XLB_AUTO_REFRESH_ON_QUERY=0 (default) do not auto refresh by TTL; only user explicit refresh (XLB_FORCE_REFRESH=1) or cache miss will fetch
• XLB_STORAGE_PROFILE=minimal (default) keep compact cache (raw + db + jsonl/topics), no large VFS tree
• XLB_STORAGE_PROFILE=full enable VFS folder/file materialization for folder-style browsing
• XLB_OUTPUT=json force JSON output for no-query mode (returns raw file reference instead of full markdown text)
• XLB_FORCE_REINDEX=1 force re-ingest even when cache hash unchanged
• XLB_PREFETCH_ARTIFACTS=1 enable concurrent URL artifact prefetch
• XLB_MAX_WORKERS=6 control prefetch concurrency
• XLB_TOPK=8 control returned hit count
• XLB_HTML_MODE=markdown|text choose HTML conversion output format
• XLB_HTML_CONVERTER_BIN=/path/to/script optional external converter command
• XLB_HTML_CONVERTER_TOOL_ID=url-to-markdown tool id passed to external converter
• XLB_HTML_CONVERT_TIMEOUT_SEC=20 timeout for external converter execution
• XLB_ITERATIVE_SEARCH=1 enable iterative retrieval summary output
• XLB_MAX_ITER=5 max iterative rounds
• XLB_GAIN_THRESHOLD=0.05 low-gain threshold
• XLB_LOW_GAIN_ROUNDS=3 consecutive low-gain rounds before stop
• XLB_DISCOVER_CACHE_TTL_SEC=30 capability discovery cache TTL (seconds)
• XLB_OPEN_HITS=1 open top hit URLs after retrieval (local app automation)
• XLB_OPEN_APP=chrome|dia|atlas|default target app for opened URLs
• XLB_OPEN_LIMIT=1 number of URLs to open
• XLB_OPEN_DRY_RUN=1 print open plan only, do not trigger app actions

?? Multi-Topic Behavior

• For inputs like xlb ??vibe coding (without retrieval query), the script returns a topic suggestion JSON.
• Each topic item includes:
  • topic, count, samples
  • entry_query (for example >Vibe Coding/)
  • entry_input (for example xlb >Vibe Coding/)
• If multiple topics are returned, pick one entry_input and run it for focused retrieval.

Network Confirmation Policy

• Default is confirmation-required for expensive network expansion steps.
• XLB_REQUIRE_NETWORK_CONFIRMATION=1 (default): external route + prefetch disabled unless confirmed.
• XLB_NETWORK_CONFIRMED=1: allow network-expensive actions for current command.
• XLB_SHOW_CONFIRM_TEMPLATE=1 (default): print standardized confirmation template to stderr when network expansion is blocked.
• Default behavior without confirmation: only local index search + URL metadata output.

Example:

XLB_PREFETCH_ARTIFACTS=1 \
XLB_HTML_MODE=markdown \
XLB_HTML_CONVERTER_BIN=/path/to/url-convert.sh \
XLB_HTML_CONVERTER_TOOL_ID=url-to-markdown \
skills/xlb-topic-index/scripts/retrieve-topic-index.sh "xlb >vibe coding/coding" "agent skills"

Benchmark (before/after)

python3 skills/xlb-topic-index/bench/run_benchmark.py \
  --queries-file skills/xlb-topic-index/bench/queries.txt \
  --runs 3 \
  --topk 8

Interop for Other Skills

• Cache contract reference: skills/xlb-topic-index/references/cache-interop.md
• Resolve user input to stable cache key:
  • python3 skills/xlb-topic-index/scripts/xlb_rag_pipeline.py resolve-input --input "xlb >vibe coding/coding"
• Export cache usage guide from meta:
  • python3 skills/xlb-topic-index/scripts/xlb_rag_pipeline.py describe-cache --meta-path "skills/xlb-topic-index/cache/index/<HASH>.meta.json" --format markdown
• Program-first data files:
  • skills/xlb-topic-index/cache/dataset/snap-<HASH>.nodes.jsonl
  • skills/xlb-topic-index/cache/dataset/snap-<HASH>.topics.json
  • skills/xlb-topic-index/cache/dataset/snap-<HASH>.navigation.json

Query Edge Semantics (for auto exploration)

• searchin section -> topic_navigation edges:
  • usually “related topics”, for example >AI Model -> normalized executable >AI Model/
• command section -> knowledge_search edges:
  • executable knowledge-search commands, including bracket style like search(>vibe coding/vibe) -> executable >vibe coding/vibe
• External skill can choose either:
  • follow topic_navigation to jump to another topic
  • run knowledge_search to deepen inside current domain
• Prefer section-specific commands for efficient edge collection:
  • >topic/searchin: for topic-to-topic traversal
  • >topic/command: for command/deep-search traversal

Auto Explore Command

• Use:
  • python3 skills/xlb-topic-index/scripts/xlb_rag_pipeline.py explore-next --meta-path "skills/xlb-topic-index/cache/index/<HASH>.meta.json" --strategy topic_first --dry-run
• Remove --dry-run to execute next hop directly.
• Useful flags:
  • --strategy topic_first|search_first|mixed
  • --visited-file <path> --update-visited to avoid repeated edges
  • --include-other-queries to allow ??... style fallback edges

Explore Loop (dedupe + budget + priority)

• Use:
  • python3 skills/xlb-topic-index/scripts/xlb_rag_pipeline.py explore-loop --seed-input "xlb >vibe coding/:" --edge-strategy searchin_command_backlink --max-steps 12 --max-depth 4 --max-seconds 90 --visited-file /tmp/xlb-visited.json --visited-topics-file /tmp/xlb-visited-topics.json --update-visited
• Behavior:
  • Auto uses >topic/searchin: and >topic/command: to collect next edges.
  • Applies visited dedupe (visited-file + visited-topics-file) to avoid loops.
  • Stops by budget (max-steps / max-depth / max-seconds).
  • Edge priority default is searchin -> command -> backlink.

One-Click Wrapper

• Use:
  • skills/xlb-topic-index/scripts/xlb-auto-explore.sh "vibe coding"
  • skills/xlb-topic-index/scripts/xlb-auto-explore.sh "xlb >vibe coding/:"
  • skills/xlb-topic-index/scripts/xlb-auto-explore.sh "xlb auto vibe coding"
• Wrapper defaults:
  • persistent visited files under skills/xlb-topic-index/cache/
  • strategy searchin_command_backlink
  • budget 12 steps / depth 4 / 90s
• Override with env vars:
  • XLB_AUTO_MAX_STEPS, XLB_AUTO_MAX_DEPTH, XLB_AUTO_MAX_SECONDS
  • XLB_AUTO_EDGE_STRATEGY, XLB_AUTO_INCLUDE_BACKLINKS, XLB_AUTO_UPDATE_VISITED

Graph Backlink Query (->)

• Input:
  • xlb ->vibe coding/:
• Meaning:
  • This is a server-side command and is passed through as title=->vibe coding/:.
  • retrieve-topic-index.sh should not local-intercept this command.
• Local graph helper (explicit, optional):
  • python3 skills/xlb-topic-index/scripts/xlb_rag_pipeline.py graph-neighbors --index-dir skills/xlb-topic-index/cache/index --target-title "->vibe coding/:"
  • Used only when you explicitly want cache-based local graph exploration.

Error Handling

• API unreachable: report connection failure and suggest checking local service on port 5000.
• Empty response: return a short warning and ask whether to retry with a broader command (for example >Vibe Coding/).
• Empty input only: ask user to provide any non-empty title command.