knowledge-retrieval

Knowledge Retrieval Skill

两种操作（与 enhance/baseline 数据模式正交）

本 Skill 有两种操作，默认是检索：

检索（默认 · 只读 · 无需任何参数）

直接说明检索诉求即可，不带任何标志。Agent 自动 config-info 探测 → 按 mode（enhance/baseline）走检索工作流。不写任何产物。

构建（--build / --update / --force · 写产物 · 显式触发）

首次接入或原始知识更新后调用，三态互斥、由用户显式选择：

• --build：首次全新构建（向量索引 + graphify 图谱）。
• --build --update：增量刷新（向量增量、graphify --update）。
• --build --force：强制重建（删 graphify-out + 向量 --force）。

触发方式：用户消息含上述标志，或明确要求"构建/刷新/重建知识库"。Agent 加载 reference/build.md 执行编排：装依赖(一次) → 装/检测 graphify → 建向量索引 → 图谱构建在主线程直接加载并运行 graphify skill（skill 方式，产物自动落盘）。构建完成后回到检索。

「检索 vs 构建」是做什么（读 / 写产物）；「enhance vs baseline」是数据怎么组织 （有 / 无知识模型）。二者正交，可任意组合，例如「baseline + 构建」= 无模型项目首次建 chunk 索引与图谱。--build 是 Skill 触发关键字，不是 CLI 子命令。

执行说明

在项目执行目录下运行（不要 cd 进 skill 安装目录，否则 CLI 找不到 knowledge.config.yaml）：

PYTHONPATH="${CLAUDE_SKILL_DIR}" python -m scripts.cli --pretty <subcommand> [args]

CLI 自动从当前目录逐级向上查找 knowledge.config.yaml；查找失败可追加 --config <绝对路径>。

⚠️ 图谱/代码检索在当前 skill 上下文内直接驱动 graphify CLI：确认 cwd 为项目根后，加载 reference/graph-query.md按其执行——它内部完成词表扩充 → 遍历 → 调 graphify query/path/explain，从 cwd 的 ./graphify-out/graph.json 读图。不嵌套调用 graphify skill，省去其构建期上下文。 检索基本只读；其中图查询会按 graph-query.md 写一条检索路径记录缓存（graphify save-result 回流 + reflect 的 LESSONS.md），用于增强后续检索命中，除此之外不写任何产物。需要全量子图时直接 Read ./graphify-out/graph.json。 构建会写产物，正文见 reference/build.md，仅在构建时按需加载。

---

阶段 0 · 能力探测（检索操作下，每次会话第一件事，必做，构建操作下可跳过）

先用一条命令摸清模式与各检索器/产物状态，后续所有门控都基于它：

PYTHONPATH="${CLAUDE_SKILL_DIR}" python -m scripts.cli --pretty config-info

返回示例：

{
  "config_path": "/proj/knowledge.config.yaml",
  "mode": "baseline",
  "raw_knowledge_dir": "./raw_knowledge",
  "vector_enabled": true,
  "vector_index_exists": false,
  "graph_enabled": true,
  "graph_path": "/proj/graphify-out/graph.json",
  "graph_exists": false
}

第一门控 · 模式路由（mode）：

• mode = "enhance" → 有知识模型。走完整工作流（阶段 1 理解模型 → typed 渐进检索），全原语可用。
• mode = "baseline" → 无知识模型。跳过阶段 1（无模型可理解），使用 vector-search（chunk 级）+ 加载 reference/graph-query.md 并按其执行 graphify 查询（query/path/explain） 双路召回；typed 类原语不可用（调用会返回 unavailable_in_baseline_mode）。