Kl

在这个宿主里怎么调 kl（先读这一段，它覆盖下文的路径推导）

这份 skill 跑在 MyContext 桌面端的 agent 里。宿主已经把可用的 kl 放进 PATH 首位，所以：

• 直接用裸 kl —— kl status / kl ask "…" / kl context <id>。
• 不要推导 KL_REPO，也不要拼 "$KL_REPO/kl" 或 .venv/bin/python kl_cli.py。下文那套"从 SKILL.md 上跳三级"的规则 在这个宿主里得到的是 skill 资源目录，那里没有可执行文件 —— 会失败。
• 不要用管道、重定向或任何其他命令（| head、| jq、2>&1、 cat、pwd …）。权限层只放行 kl 本身，带管道的整条命令会被 直接拒绝执行。输出太长时用 kl 自己的参数控制（如 -k 限条数、 --pretty），而不是截断。
• kl-server 由宿主启动并保持运行，不需要 kl start。

下文是上游原文，其中的路径推导与启动说明按上面这几条替换。

Knowledge Graph Query (kl)

CLI tool for querying a spatio-temporal knowledge graph built from DingTalk workplace messages and other exported sources. It contains entities and facts, plus optional experimental multi-resolution communities. Discover capabilities before checking status or querying.

Architecture: kl CLI is a thin HTTP client talking to kl-server (port 8200). The server keeps Qdrant + SQLite warm in memory. All commands require the server to be running.

Mandatory capability discovery

Before running status or choosing any query command, call:

kl capabilities --json

On Windows use the invocation form documented below, but keep capabilities --json as the first CLI arguments. Parse commands and use only entries whose enabled value is true; never infer availability from this static skill text. In particular, global-search, community, members, and the communities search collection are experimental and normally disabled. ask is always available and is the primary retrieval command. If discovery fails because the server is not running, start the server, then retry capability discovery before querying.

Invoking kl (any directory, macOS & Windows)

The examples below write kl ... / ./kl ... for brevity, but the repo can be installed anywhere, so never hardcode a path. Discover the repo root at runtime, then invoke kl relative to it.

Discover the repo root (call it KL_REPO):

• This skill file lives at <repo>/skills/kl/SKILL.md, so the repo root is three directories up from this file — if you know this file's path, use its ../../...
• Otherwise walk up from the current directory until you find the marker files (the kl script + kl_cli.py):

  # macOS / Linux
  KL_REPO="$PWD"
  while [ "$KL_REPO" != "/" ] && [ ! -f "$KL_REPO/kl_cli.py" ]; do
    KL_REPO="$(dirname "$KL_REPO")"
  done
  

  # Windows (PowerShell)
  $KL_REPO = (Get-Location).Path
  while ($KL_REPO -and -not (Test-Path (Join-Path $KL_REPO 'kl_cli.py'))) {
    $KL_REPO = Split-Path $KL_REPO -Parent
  }
  

Then invoke it (works from any directory):

• macOS / Linux — the kl wrapper cds into its own directory, so calling it via $KL_REPO works from anywhere:

  "$KL_REPO/kl" status
  "$KL_REPO/kl" ask "..."
  

  Equivalent direct form: "$KL_REPO/.venv/bin/python" "$KL_REPO/kl_cli.py" status.
• Portable rule of thumb: if ./kl fails (wrong directory, or Windows), fall back to invoking the venv interpreter on kl_cli.py with the same arguments — the venv Python is at .venv/bin/python on macOS/Linux and .venv/Scripts/python.exe on Windows. On Windows, see the dedicated section below for bash-specific syntax and encoding requirements.

Invoking on Windows (read this if you are on win32)

AIAssist agents run in bash on Windows, not PowerShell. The macOS/Linux examples above ($KL_REPO/kl) and old PowerShell snippets (& "$KL_REPO\.venv\...") neither works in the agent's bash shell. Use the patterns below instead.

1. Always set PYTHONUTF8=1

Windows defaults to GBK / cp1252 for console encoding. Without PYTHONUTF8=1, any print() or log line containing Chinese characters (group names, entity names, fact text) will crash with UnicodeEncodeError or produce garbled output you cannot read. Set it as the first thing before any kl command:

export PYTHONUTF8=1

Or prefix every invocation inline:

PYTHONUTF8=1 "$KL_REPO/.venv/Scripts/python.exe" "$KL_REPO/kl_cli.py" status

2. Use bash syntax: forward slashes, not backslashes

The venv Python lives at .venv/Scripts/python.exe (note: Scripts, not bin). In bash, use forward slashes throughout — backslashes are escape characters in bash, so "$KL_REPO\.venv\Scripts\..." will break.

# Discover the repo root (agent runs in bash, not PowerShell)
KL_REPO="$PWD"
while [ "$KL_REPO" != "/" ] && [ ! -f "$KL_REPO/kl_cli.py" ]; do
  KL_REPO="$(dirname "$KL_REPO")"
done

# All subsequent calls use forward slashes
PYTHONUTF8=1 "$KL_REPO/.venv/Scripts/python.exe" "$KL_REPO/kl_cli.py" status
PYTHONUTF8=1 "$KL_REPO/.venv/Scripts/python.exe" "$KL_REPO/kl_cli.py" ask "你的问题" --pretty

3. Environment variables: use export, not set

The .env file in the repo uses Windows CMD set syntax, which bash cannot source. Instead, export each variable explicitly in bash before starting the server or querying:

export PYTHONUTF8=1
export KL_DATA_DIR="$KL_REPO/data"
export KL_DWS_EXPORT_DIR="$KL_REPO/dataset/<your-export-dir>"
export KL_EMBED_BASE_URL=<your-embed-endpoint>/v1
export KL_EMBED_MODEL=Qwen3-Embedding-0.6B
export KL_EMBED_API_KEY=<your-key>
export KL_EMBEDDING_DIM=1024
export KL_EMBED_SEND_DIMENSIONS=0
export KL_LLM_BASE_URL=<your-llm-endpoint>
export KL_LLM_MODEL=qwen3.6-flash
export ANTHROPIC_AUTH_TOKEN=<your-token>
export DISABLE_AIOHTTP_TRANSPORT=True
export KL_SERVER_PORT=8200

4. Start the server in bash (not via ./kl)

The ./kl wrapper script may not work on Windows. Start the server directly. Prerequisite: all environment variables from section 3 must be exported in the same shell session first — the server needs KL_EMBED_*, KL_LLM_*, etc. to function:

# (env vars from section 3 must already be exported in this shell)

PYTHONUTF8=1 "$KL_REPO/.venv/Scripts/python.exe" "$KL_REPO/kl_server.py" &
sleep 15  # Qdrant warmup
PYTHONUTF8=1 "$KL_REPO/.venv/Scripts/python.exe" "$KL_REPO/kl_cli.py" status

5. Quick reference: the complete pattern

# One-time per session: discover repo + set encoding
export PYTHONUTF8=1
KL_REPO="$PWD"
while [ "$KL_REPO" != "/" ] && [ ! -f "$KL_REPO/kl_cli.py" ]; do
  KL_REPO="$(dirname "$KL_REPO")"
done
export KL_REPO

# Environment variables (adjust paths/values for your setup)
export KL_DATA_DIR="$KL_REPO/data"
export KL_DWS_EXPORT_DIR="$KL_REPO/dataset/<your-export-dir>"
export KL_EMBED_BASE_URL=<your-embed-endpoint>/v1
export KL_EMBED_MODEL=Qwen3-Embedding-0.6B
export KL_EMBED_API_KEY=<your-key>
export KL_EMBEDDING_DIM=1024
export KL_EMBED_SEND_DIMENSIONS=0
export KL_LLM_BASE_URL=<your-llm-endpoint>
export KL_LLM_MODEL=qwen3.6-flash
export ANTHROPIC_AUTH_TOKEN=<your-token>
export DISABLE_AIOHTTP_TRANSPORT=True
export KL_SERVER_PORT=8200

# Start server (if not already running)
PYTHONUTF8=1 "$KL_REPO/.venv/Scripts/python.exe" "$KL_REPO/kl_server.py" &
sleep 15

# Query
PYTHONUTF8=1 "$KL_REPO/.venv/Scripts/python.exe" "$KL_REPO/kl_cli.py" status
PYTHONUTF8=1 "$KL_REPO/.venv/Scripts/python.exe" "$KL_REPO/kl_cli.py" ask "session打标进度" --pretty

6. Request timeout

The CLI HTTP timeout defaults to 120 seconds (configurable via KL_CLI_TIMEOUT). If kl ask times out, it usually means Phase-2 LLM synthesis is slow — the server may still complete the request; check kl status for server health. To allow more time:

export KL_CLI_TIMEOUT=180  # 3 minutes

End to End (build → ingest → query)

First-time setup from a raw DWS export to answering questions. Steps 1–4 are the one-time build; after that you only use step 5 (query), and re-run the ingest when new data arrives.

# 1. BUILD: install deps + point at your endpoints and data (env-only, no
#    secrets are baked into the repo). Put the config in a local .env file
#    (gitignored) and source it before starting the server:
pip install -r requirements.txt
set -a; source .env; set +a          # load KL_* + ANTHROPIC_AUTH_TOKEN

The repo ships a .env at the project root (gitignored — never commit it) with working endpoints. Nothing auto-loads it, so you must source it as above. It sets:

# data + export
export KL_DATA_DIR=./data                      # where knowledge.db + qdrant land
export KL_DWS_EXPORT_DIR=/path/to/dws_export   # the exported source folders

# embedding: PAI-EAS Qwen3-Embedding-0.6B (1024-dim). URL MUST end in /v1;
# KL_EMBEDDING_DIM MUST match the model (1024) — it is baked into the Qdrant
# collections, so changing models later requires wiping + re-embedding.
export KL_EMBED_BASE_URL=<your-embed-endpoint>/v1
export KL_EMBED_MODEL=Qwen3-Embedding-0.6B
export KL_EMBED_API_KEY=<embedding-api-key>   # real value lives only in .env
export KL_EMBEDDING_DIM=1024
export KL_EMBED_SEND_DIMENSIONS=0

# extraction/synthesis LLM: qwen3.6-flash (Anthropic-compatible base;
# do NOT append /v1 — litellm adds /v1/messages itself).
export KL_LLM_BASE_URL=https://example.com/apps/anthropic
export KL_LLM_MODEL=qwen3.6-flash
export ANTHROPIC_AUTH_TOKEN=<api-key>   # real value lives only in .env

# 2. SERVE: start the retrieval server first (ingest runs inside it).
./kl start
kl status                                      # wait for "status": "ready"

# 3. INGEST: drive the whole build through the running server. This runs
#    Phase A (chunk+embed every source) → Phase B (LLM extract + build+embed
#    the graph) → the improve step (ENTITY_SIMILAR/FACT_SIMILAR edges +
#    communities L0–L3), then hot-swaps the new graph in. Non-blocking.
kl ingest -d "$KL_DWS_EXPORT_DIR"              # omit -d to use $KL_DWS_EXPORT_DIR
kl status                                      # poll: "Ingest: running NN% (phase)"

# 4. COMMUNITY SUMMARIES (optional but recommended): kl ingest builds the
#    community structure but NOT their summaries/vectors. These two steps add
#    1–2 sentence summaries and make `search -c communities` work.
python -m kl_graph.periodic.community_summarizer   # 1–2 sentence summary/community
python scripts/embed_communities.py                # embed summaries (search -c communities)

# 5. QUERY: ask questions (see Retrieval Patterns below).
kl ask "who decided to use e2b for sandbox" -k 5
kl context <fact_id>                               # ground the answer in source

Notes:

• kl ingest upserts into the current DB (deterministic UUID5 ids mean re-ingesting never duplicates entities/facts); it has no wipe flag, so for a truly clean rebuild rm -rf "$KL_DATA_DIR" before step 2. --no-improve skips the community/PageRank step; -c N raises extraction concurrency.
• For a cold/scripted build without a running server, the offline equivalents are python -m scripts.ingest --fresh-db (Phase A + B, --fresh-db wipes knowledge.db — which now holds the extraction cache, so the cache is cleared too) followed by python -m scripts.improve --skip-llm-judge. kl ingest is the preferred path when the server is up.
• Community columns (community_L0..L3) come from the improve step; without it community/members are empty and entity shows no community labels.

Commands

# Lifecycle
kl capabilities --json # REQUIRED FIRST: live enabled/disabled query commands
kl status              # Server status + DB stats (+ ingest progress)
kl start               # Start kl-server (retrieval)
kl start embedding [--model P] [--dp N] [--tp N] [--port 8100] [--gpu-util 0.4]
kl stop                # Stop both servers
kl stop embedding      # Stop only the embedding server
kl ingest [-c N] [-d PATH] [--no-improve]  # in-server background ingest (Phase A + B)

# All commands require kl-server running (kl start)
kl entity "<name>"     # Entity lookup by name (substring); shows id +
                       #   communities + top edges + facts about it (id + text)
                       #   + ENTITY_SIMILAR neighbors ("similar", with names)
kl entity --id <id>    # Same, but look up by entity id (exact or prefix).
                       #   Add --no-similar to skip the ENTITY_SIMILAR block.
kl facts <entity_id>   # Facts ABOUT an entity (id + text), confidence-sorted
kl facts --fact-id <id>  # A single fact by its id (exact/prefix); minimal —
                       #   use `kl context` for full source provenance
kl expand <entity_id>  # [DEPRECATED] ENTITY_SIMILAR neighbors — same as the
                       #   "similar" block of `kl entity --id <id>`
kl community [-l L0|L1|L2|L3] [-t entity|fact] [--id N]  # capability-gated
kl members <id> [-l L1] [-t entity]                       # capability-gated
kl context <fact_id>   # Source message + context + entities
kl timeline "<entity>" [--from YYYY-MM-DD] [--to YYYY-MM-DD]
kl stats               # Detailed statistics
kl search "<query>" [-c chunks|messages|facts|entities|communities] [-k 10]  # vector ANN, one collection
kl ask "<question>" [-k 10] [--phase2|--no-phase2] [--entity NAME] [--entity-type TYPE] [--fact-type TYPE] [--seed-k 6] [--radius 1] [--max-nodes 40]
kl global-search "<question>" [--user "<name>"] [--json]  # experimental; use only when capability says enabled
kl hop -n <node_id> -c '<cursor_json>'   # expand one node one hop deeper (no LLM/embed)

Ingest is two phases (kl ingest for in-server background ingest, or python -m scripts.ingest for a cold/scripted build): Phase A loads + chunks + embeds every source folder (chat + wiki/mail/ work/…) into SQLite chunks + Qdrant — no LLM, dense/BM25 recall works after this. Phase B runs LLM entity/fact extraction over all chunks, then builds and embeds the graph (the only LLM-billed phase; results are cached per chunk). Watch progress with kl status (Ingest: running NN% (phase)).

Run the full ingest (Phase A + Phase B) — kl ingest does both. But you don't have to wait for Phase B: the service is usable as soon as Phase A completes (search/ask work off dense + BM25 recall), so start querying while Phase B is still running. Phase B then improves performance/accuracy by adding the entity/fact graph on top — check kl status to see when it lands.

Offline build (needs KL_DWS_EXPORT_DIR, KL_DATA_DIR, ANTHROPIC_AUTH_TOKEN, KL_EMBED_API_KEY in the env):

python -m scripts.ingest --fresh-db                # Phase A + Phase B (fresh)
python -m scripts.improve --skip-llm-judge         # ENTITY_SIMILAR/FACT_SIMILAR + communities L0–L3
python -m kl_graph.periodic.community_summarizer   # 1–2 sentence summary/community
python scripts/embed_communities.py                # embed summaries (search -c communities)

• With no flag, scripts.ingest runs the full pipeline with smart resume: if Phase A is fully done (every chunk persisted and embedded) it skips to Phase B, else it re-runs Phase A. --phase-a = chunk+embed only (no LLM).
• --fresh-db wipes knowledge.db + the Qdrant dir. The extraction cache now lives in the extraction_cache table inside knowledge.db, so --fresh-db clears it too. To rebuild the graph without re-billing the LLM (reusing the cache), run python -m scripts.ingest --build-only without --fresh-db. To wipe everything, rm -rf "$KL_DATA_DIR" first.
• Ids are deterministic UUID5s of normalized content, so re-ingesting never duplicates entities/facts.
• Community columns (community_L0..L3) are created only by scripts.improve (or kl ingest unless --no-improve); without them community/members are empty and entity shows no community labels.

To ingest a new export into the running server (non-blocking — it keeps serving and hot-swaps the new graph in when done):

kl ingest -d /path/to/dws_export     # start Phase A → B in the background
kl status                            # poll: "Ingest: running NN% (phase_a|phase_b)"
# -c N raises LLM extraction concurrency (default 8); --no-improve skips
# community detection/PageRank; omit -d to use $KL_DWS_EXPORT_DIR.

search returns raw nearest-neighbor hits from a single collection (default facts; other collections: chunks/messages, entities, communities — chunks is the unified retrieval-unit collection for all embedded source content, and messages is a backward-compat alias for it). ask runs the full engine over chunks+facts (dense+sparse+RRF) and walks the depth-1 graph from the entities/facts the query extracted. Agent callers must derive the retrieval intent themselves and pass repeatable --entity, --entity-type, and --fact-type flags using the values advertised by capabilities; this skips the server-side rewrite LLM while retaining server-side entity resolution. Also pass --no-phase2 and synthesize from the returned evidence. Plain clients may omit intent and let the server rewrite, or request a synthesized answer with --phase2. Output is JSON by default; add --pretty for a human view, or --json to force JSON explicitly. (The browsing commands like entity / community also support --json.)

ask returns retrieval + a hoppable subgraph

A single kl ask "<query>" call returns both flat recall and an interactive graph view:

• items: the embedding-recalled items (dense+sparse+RRF fused facts+chunks), cut at top_k. This is the flat vector recall.
• answer: LLM synthesis, or null when --no-phase2 is set.
• seeds: entry nodes as {id, label} (ent:<uuid>/fact:<uuid> + name/text).
• nodes: seeds (hop 0) plus the hop-1 frontier reached from them, each resolved to {id, type, score, hop, name|text, ...}.
• edges: {from, to, from_label, to_label, type, weight} — the walkable edges (ABOUT/INVOLVES); *_label inline the endpoint name/text so an edge is self-describing. from/to are node ids in nodes.
• expandable: {id, label} for nodes that still have further un-walked edges.
• cursor: opaque walk state — pass it to kl hop to expand a node one more hop (no LLM, no embed).

When the graph is not built the walk fields come back empty (mode="chunks_only") and only items are populated.

To go deeper, feed an expandable id + the cursor to kl hop (pass the .id from an expandable/seeds entry):

kl hop -n <expandable_id> -c '<cursor json from ask>' --pretty

hop returns only the newly revealed frontier (nodes/edges) plus an updated cursor — the server is stateless between hops, so merge the frontier into the graph you already hold and chain hop again with the new cursor. It never re-embeds or calls the LLM.

Note the decay: each hop multiplies a node's score by λ (default 0.6) and drops branches below mini_threshold (0.2). With these defaults real query seeds (~0.5–0.6) reach depth 2 and a strong seed reaches depth 3 — a node survives while score × 0.6^hop ≥ 0.2. Weak/deep nodes eventually return an empty hop; that is the expected stop signal, not an error.

graph / hop are the interactive GraphRAG mode — see "Interactive Graph Walk" below. The embedding server (kl start embedding) is only needed on a GPU host; retrieval itself uses the remote embedding endpoint, so kl start alone is enough for querying.

Command Best Practices

How to use kl well, in priority order:

1. Discover capabilities first. Run kl capabilities --json and use only commands whose live enabled value is true. Then run kl status to inspect health and ingestion progress. If the server is unavailable, start it and retry capabilities before selecting a query command.
2. Plan before you query. Think about what the user is really asking and which commands answer it; don't fire commands blindly (see the Query strategy callout under Retrieval Patterns).
3. Start with kl ask, avoid kl search. kl ask is the primary entry point (hybrid retrieval + graph walk); reserve kl search for narrow single-collection lookups kl ask can't serve. For conceptual, person-scoped "what has X been about / what are my recent tasks" questions that need aggregation rather than a single hit, use kl global-search only when the live capabilities report it enabled (see Retrieval Pattern 8).
4. Trace before you trust. Ground every claim in source: take a fact_id from ask/entity/facts/timeline and run kl context <fact_id> to see the original message before reporting it.
5. Discriminate semantic relevance before drilling. kl ask and kl search return nearest-neighbour hits by embedding similarity — this surfaces keyword-overlap results that may be semantically unrelated to your actual question (e.g. a query about "session 打标障碍" may return results about model evaluation timeouts or billing identification simply because they share the words "session", "超时", or "标识"). Before running kl context, hopping the graph, or synthesizing an answer, pause and ask: does this result actually address the user's question, or does it just share vocabulary? Filter out the irrelevant hits, note which results genuinely match, and do not follow irrelevant paths into context or hop — that wastes the query budget and pollutes the answer with off-topic evidence. When in doubt, rephrase the query with more specific terms rather than stacking broad keywords.
6. Chain by id, not by name. Every id kl prints is traceable (entity → entity_id → kl facts → fact_id → kl context). Prefer ids when chaining — names aren't unique (e.g. two 周强 entities), so a name-based timeline/entity may mix them up.
7. Show evidence, then conclude. Quote the raw kl output first, then give your synthesis (see the Answering callout under Retrieval Patterns).
8. Respect the budget. Cap at ~10 commands per question; stop once you have ≥3 grounded facts or two consecutive queries add nothing new (see Search Budget & Stop Criteria).
9. Use --json for chaining, --pretty for humans. Query commands emit JSON by default (easy to parse ids out of); pass --pretty when showing a person a result. --json always wins if both are given.
10. Widen before narrowing on empty results. If kl ask comes back thin, try a broader phrasing or kl community to find the right neighborhood, then drill via kl members → kl context.

Latency Profile

ask is slower when it escalates to Phase-2 synthesis (an extra LLM call). Embeddings are served by the configured remote endpoint (KL_EMBED_* env vars); the embedding dimension is fixed at build time, so changing models requires a full re-embed.

Retrieval Patterns

Query strategy (read first). Before running any kl command, think carefully about what the user is actually asking and which commands will answer it — plan the sequence, don't fire commands blindly. Always start a search with kl ask (hybrid retrieval + graph walk + optional synthesis); it is the primary entry point. Avoid kl search — it is a low-level single-collection vector ANN and should only be used for narrow, specific lookups when kl ask clearly can't serve the need.

Answering — show evidence, then conclude. To make results trustworthy, first quote the original text you got from kl (the raw message/fact content, verified with kl context where possible), then give your conclusion drawn from it. Lead with the source evidence, follow with your synthesis — never present a conclusion without the underlying kl output it rests on.

Semantic mismatch — filter before you drill. Embedding-based retrieval (ask, search) ranks by vector proximity, which measures keyword overlap, not topical relevance. A result about "session 超时" in a model-benchmarking conversation is not an obstacle to "session 打标" work, even though both contain "session" and "超时". Before spending context or hop calls on any hit, ask: "Is this about the same topic the user asked about, or does it just share words?" Discard the misses silently, do not summarize them as "evidence found but not relevant" — that wastes the reader's attention. If fewer than 3 hits survive the filter, rephrase the query with more specific terms (e.g. "session 打标 进度" instead of "session 打标 障碍 超时 模型 训练") and query again, rather than padding the answer with off-topic results.

1. Direct Answer (factual questions)

kl ask "who decided to use e2b for sandbox" -k 5 \
  --entity e2b --entity-type SYSTEM --fact-type DECISION --no-phase2
kl context <best_fact_id>                          # ground the answer in source

2. Entity Deep-Dive (about a person/project/system)

kl entity "周强"                    # id + "similar" (ENTITY_SIMILAR) + top facts (with fact_ids)
kl facts <entity_id>                 # all facts ABOUT it (fact_id + text)
kl context <fact_id>                 # ground a fact in its source message
kl community -l L2 --id <community_id>
kl members <community_id> -l L2 -t fact
kl timeline "周强" --from 2026-06-01

Id-driven trace-back (no name round-trip): every id kl prints is traceable. kl entity returns an entity_id plus the facts about it; feed the entity_id back with kl entity --id <id> (or kl facts <entity_id> for the full list), then any fact_id to kl context for the exact source message (or kl facts --fact-id <id> for just the fact text). The similar block also shows each ENTITY_SIMILAR neighbor's name + full entity_id, so you can kl entity --id/kl facts on those too. Prefer ids over names when chaining — names aren't unique (e.g. two 周强 entities).

(To find a person/system when unsure of the exact surface form, use kl search "<term>" -c entities for a semantic entity lookup.)

3. Broad Survey (exploratory)

kl search "sandbox architecture" -c communities -k 5  # Find relevant communities
kl members <community_id> -l L2 -t fact               # Read the facts
kl context <fact_id>                                   # Ground in source

Or browse linearly:

kl community -l L1 -t entity    # Team-level (best starting point)
kl community -l L2 --id 8       # Drill into a project
kl members 8 -l L2 -t entity    # Who's in it?

4. Alias Resolution

kl entity "张伟"
kl entity --id <entity_id>       # the "similar" block lists ENTITY_SIMILAR links

5. Timeline

kl timeline "InkFlow" --from 2026-06-01 --to 2026-07-01

6. Topic Discovery

kl community -l L1 -t fact      # What topics exist?
kl community -l L2 -t fact --id 5  # Detail on one
kl members 5 -l L2 -t fact         # Read facts

7. Interactive Graph Walk (relationship / multi-hop questions)

Use ask when the question is about how things connect (who works with whom, what a decision depends on, how a system relates to a project). A single ask call already returns both flat recall (items) and a hoppable subgraph (seeds/nodes/edges/expandable + a cursor) — walked from the entities/facts the query extracted. There is no separate graph command; the walk is built into ask.

kl ask "e2b 部署平台和谁相关" --seed-k 6 --max-nodes 40   # items + seeds + hop-1 subgraph (JSON)
kl ask "e2b 部署平台和谁相关" --pretty                    # human view + expandable ids

The response includes nodes, edges, an expandable list of node ids, and a cursor object. To go deeper, expand a specific node one hop with hop, passing the cursor back so visited state and decay carry over:

# take an id from "expandable" and the "cursor" object from the ask response
kl hop -n "ent:<id>" -c '<cursor-json-from-previous-response>'

Notes:

• Node ids are namespaced: ent:<entity_id> and fact:<fact_id>.
• If the graph isn't built, ask falls back to mode="chunks_only" (flat vector hits) in the same response shape — check the mode field.
• hop does no embedding/LLM (pure in-memory walk) — cheap to chain.
• Ground any interesting fact node with kl context <fact_id> as usual.

8. Global Search (experimental, capability-gated)

Use this pattern only when kl capabilities --json reports commands.global-search.enabled=true. Otherwise use ask, facts, and timeline; do not call the disabled command.

Use kl global-search when the question is conceptual and person-scoped — it must be aggregated over everything a person has been involved in, not answered by any single chunk/fact. Canonical example: "我最近的任务是什么" (what are my recent tasks?), "这个人主要负责什么" (what does this person mainly work on?). Where ask does flat recall + a depth-1 graph walk, global-search resolves the person to a Person entity, collects that person's community summaries across L0–L3, and runs a GraphRAG-style map-reduce over them (strict-JSON key points scored 0–100 → drop score-0 → importance-sort → token-budgeted reduce → grounded markdown with [Data: Communities (...)] citations).

kl global-search "我最近的任务是什么" --user "孙亮"   # explicit person
kl global-search "这个人主要负责什么"                    # identity via DWS get-self
kl global-search "我最近的任务是什么" --json            # full wire shape for chaining

Identity resolution precedence: --user <name> → DWS get-self (the CLI shells out to dws contact user get-self for the logged-in user) → otherwise the server's KL_CURRENT_USER. The response carries reason, communities (the selected {level, community_id, member_count}), citations, and diagnostics (map/reduce call counts, latency).

When there is no grounding — the name doesn't resolve (reason=identity_unresolved), or the person has no community memberships (reason=no_communities) — it returns a canned bilingual no-data answer in ~0 ms with ZERO LLM calls plus a remediation hint (e.g. run python -m scripts.improve). It never falls back to a corpus-wide search or errors out.

Requires the community layer to be built and summarized: kl ingest / scripts.improve create the community_L0..L3 columns, and python -m kl_graph.periodic.community_summarizer generates the summaries this command reads. Without summaries every query returns no_communities.

Caveat — summaries are name-based, not task-based (today). Community summaries are built from member names/aliases, so a person whose graph neighborhood is dominated by identity/HR material may get a thin, honest "can't pin down concrete tasks" answer even on the ok path. That is a data limitation, not a retrieval bug — prefer ask/facts/timeline for specific, dateable task lookups, and use global-search for the high-level "what has this person been about" shape.

Community Hierarchy

Drill-down pattern for navigating the graph:

L0 (org-level)       -> "Which team?"
L1 (team-level)      -> "Which project?"       <- BEST STARTING POINT
L2 (project-level)   -> "Which component?"
L3 (component-level) -> "Specific facts + evidence"

Search Budget & Stop Criteria

When to STOP drilling

• You have ≥3 grounded facts (with kl context verification) that genuinely match the user's question and answer it
• You've reached L3 community level (most granular — no further drill-down)
• Two consecutive queries returned no new semantically relevant information
• The user's question is answered with high confidence from existing results
• A query returns only keyword-overlap hits with no topically relevant result — rephrase and retry once; if still no match, report what you found rather than forcing off-topic evidence into the answer

Rejection signals — do NOT drill into these

• The result shares keywords ("session", "超时", "模型") but discusses a different topic (benchmarking, billing, deployment) than what the user asked
• The surrounding context (kl context) reveals the conversation is about a different project or task than the question targets
• A fact's subject_entity or object_entity is unrelated to the question's domain — the connection is coincidental keyword overlap, not topical similarity
• A graph hop expands into entities/facts that are clearly off-topic from the seed — stop expanding that branch immediately

Query budget per question

• Simple factual: 2-3 commands (ask → context → done)
• Entity deep-dive: 4-6 commands (entity → facts → context, or entity → community → members → timeline → context)
• Broad survey: 5-8 commands (community L1 → pick → L2 → members → context × 2-3)
• Relationship / multi-hop: ask (walks the graph) → hop (× 1-2 on expandable ids) → context
• Maximum: 10 commands per question before synthesizing what you have

Confidence signals

• Fact type=DECISION with confidence≥0.9 → high reliability
• Multiple facts from different messages saying the same thing → confirmed
• Single fact from one message → report but flag as single-source
• Community summary matching your query with score≥0.8 → right neighborhood

Key Notes

• Entity names are Chinese and English: "周强", "InkFlow", "VS Code"
• Fact IDs support prefix match: kl context 49d8370a
• High-degree entities (>200 edges) get auto-filtered to last 90 days on timeline (use --from/--to to override)
• Check kl status first — if server not running, use kl start
• Time range: 2025-09 to 2026-07

多图谱检索（宿主注入 KL_GRAPHS_JSON 时）

本宿主可能同时运行多个 kl-server —— 一个数据来源一个，各自独立的 图库与端口，彼此物理隔离（这是隐私边界：来源之间不做 JOIN）。

KL_SERVER_PORT 只指向其中一个。若环境里还有 KL_GRAPHS_JSON， 它是一个 {"<来源名>": <端口>} 的映射，列出全部可查的图：

# 例：{"dingtalk":8200,"feishu":8201}
echo "$KL_GRAPHS_JSON"

问一个跨来源的问题时，逐个图各问一次，然后在回答里合并。 先看一眼有哪些图，再对每个端口各发一条命令：

echo "$KL_GRAPHS_JSON"
# 假设读到 {"dingtalk":8200,"feishu":8201}，就发两条：
KL_SERVER_PORT=8200 kl ask "<question>" --pretty
KL_SERVER_PORT=8201 kl ask "<question>" --pretty

不要写 shell 循环去解析那个 JSON —— 你已经读到了它的内容， 直接按读到的端口逐条发命令。宿主的命令白名单只放行 kl 与 KL_SERVER_PORT=<n> kl ... 这两种形态，别的写法会被拒。

两条要求：

• 不要把一个来源的事实归到另一个来源。回答里涉及具体事实时说清它来自哪个。
• 某个图查不通时说出来，不要静默只用另一个的结果 —— 那会让用户以为 搜过了全部来源。

没有 KL_GRAPHS_JSON 时忽略本节，按 KL_SERVER_PORT 查那一个图即可。