ewankb-query

name	ewankb-query
description	查询 ewankb 知识库。默认图谱查询，也可指定 kb 或 deep 双路对比模式。查询结果自动穿透到源代码层，验证规格与实现的一致性。
trigger	/ewankb-query

/ewankb-query

用法

/ewankb-query <问题>                        # 图谱查询（默认）
/ewankb-query graph <问题>                  # 图谱查询
/ewankb-query kb <问题>                     # 文档检索
/ewankb-query deep <问题>                   # 双路对比查询

执行步骤

1. 定位知识库 + 自动拉取

ewankb preflight --query --dir .

解析 JSON：kb_dir 是知识库路径。

preflight 失败处理（仅关注查询相关 blocker）：

• 使用 --query 模式时，no_llm_config 和 no_api_key 不会出现在 blockers 中（查询不需要 LLM）
• 如果 blockers 包含 no_project_config → 不要立即停止，先检查全局知识库：

  PYTHONIOENCODING=utf-8 python ~/.claude/skills/ewankb-hub/scan.py --json
  

  • 如果返回了 KB 列表（至少一个）→ 当前目录没有项目级知识库，但机器上有全局知识库可用。提示用户：

    当前目录下没有项目级知识库，但检测到以下全局知识库：
    
    | 库名 | 名称 | 概述 |
    |------|------|------|
    | ... | ... | ... |
    
    请使用 /ewankb-hub <库名> <问题> 查询全局知识库。
    

    然后停止。
  • 如果返回空 → 提示用户运行 /ewankb init 初始化知识库，停止
• 如果 blockers 包含 no_source / no_domains / no_knowledgeBase / no_graph → 知识库不完整，提示用户运行 /ewankb --build-graph，停止
• 如果 graph.exists: false 且需要 graph 查询 → 提示先运行 /ewankb --build-graph，停止

自动拉取（消费者无需手动 pull）：

• 如果 kb_dir 是 git 仓库，检查是否有 remote 配置：

  cd "{kb_dir}"
  git remote -v
  

• 如果有 remote，静默拉取最新：

  git pull --rebase origin main 2>&1 || true
  

• 如果 kb_dir 不存在但用户提供了 git 仓库地址，自动 clone：

  git clone <仓库地址> "{kb_dir}"
  

如果 graph.exists: false 且需要 graph 查询，提示先运行 /ewankb --build-graph。

2. 判断查询模式

根据用户输入确定模式：

• /ewankb-query <问题>（无子命令）→ 图谱模式（步骤 3A）
• /ewankb-query graph <问题> → 图谱模式（步骤 3A）
• /ewankb-query kb <问题> → kb 模式（步骤 3B）
• /ewankb-query deep <问题> → 双路对比模式（步骤 3C）

3A. Graph 模式（仅图谱）

ewankb query "用户问题" --json --dir "{kb_dir}"

如果 ewankb 命令不可用，请先运行 pip install ewankb。

解析 JSON 结果并解读：

1. matched_start_nodes 为空： → 告知用户图中未找到匹配节点，建议：

   • 尝试更短的关键词（如"付款额度" → "付款"）
   • 尝试用英文术语（如"overdraft"、"payment"）
   • 检查 query_analysis.extracted_keywords 是否合理
   • 建议用 /ewankb-query kb "同一问题" 切换到文档检索

2. matched_start_nodes 非空： → 基于 nodes 和 edges 用自然语言合成回答：

   • 从 matched_start_nodes 出发，描述直接关联的概念
   • 引用 source_file、source_location、relation 作为证据
   • 如果图的深度不足以覆盖问题范围，如实说明
   • 不要编造图中没有的关系
   • 参考 graphify 的做法：基于图的边关系做有限推理

示例解读：

根据图谱分析：
- 找到 2 个与"预付款"相关的节点
- 预付款执行付款 → calls → 付款计划
  来源：domains/收付款管理/README.md

这表明预付款流程和付款计划存在调用关系。但图中没有包含具体的额度计算逻辑，
可能需要查看 `/ewankb-query kb` 文档检索来获取更详细的计算规则。

回答末尾附建议："想看原文？试 /ewankb-query kb \"同一问题\""

3B. KB 模式（仅文档）

ewankb query-kb "用户问题" --dir "{kb_dir}"

如果高分文档内容被截断，用 Read 工具读取完整内容后再回答。

关联代码为空时的处理： 如果高分文档的"关联代码"章节为空（如"（未找到直接对应的代码文件）"），不要把问题留给用户，而是自动触发代码穿透（步骤 3D）来查找对应的源代码文件。

回答末尾附建议："想看关联？试 /ewankb-query graph \"同一问题\"；想看代码实现？结果中已包含代码穿透"

3C. 双路对比模式（deep）

用 Agent 工具并行启动两个 subagent（同一条消息）：

Subagent A（graph）：

执行 ewankb query "{问题}" --dir "{kb_dir}"，分析结果（涉及哪些节点、边、域）。从结果中提取技术术语（字段名、类名、API路径等），用于代码穿透。

Subagent B（kb）：

执行 ewankb query-kb "{问题}" --dir "{kb_dir}"，对高分文档用 Read 工具读取完整内容，分析结果。从文档内容中提取技术术语（字段名、类名、API路径、表名等），用于代码穿透。如果文档的"关联代码"为空，标记需要代码穿透。

对比 + 歧义处理：

• 两路结果一致 → 合并汇总回答
• 存在歧义 → 向 subagent 追问具体歧义点，追问结果继续对比，还有歧义就再追问，直到一致（最多 5 轮）

代码穿透：Subagent A/B 完成后，汇总两路提取的技术术语，执行代码穿透（步骤 3D），重点比对规格描述 vs 实际实现的差异。

最终回答格式：

## 回答
[综合回答]
## 信息来源
- 图谱：[关键发现]
- 文档：[关键发现]
- 代码：[关键发现]（如有代码穿透结果）
## 代码验证（如有差异）
- [规格 vs 实现] {差异描述}
- 证据：{源文件路径}:{行号}
## 差异说明（如有）

3D. 代码穿透（source/repos/ 搜索）

无论哪种查询模式，在获得知识库/图谱结果后，执行代码穿透来验证规格与实现的一致性。

执行前提：

• {kb_dir}/source/repos/ 目录存在且非空 → 执行代码穿透
• {kb_dir}/source/repos/ 目录不存在或为空 → 跳过，在回答中注明"无法执行代码穿透（源代码目录不可用）"
• 用户问题纯业务描述，不含任何可映射到代码的实体（如"什么是合同管理"） → 跳过
• 知识库文档的"关联代码"已完整覆盖问题范围 → 跳过

步骤 1：提取技术术语

从知识库/图谱查询结果中提取可用于搜索源代码的技术关键词：

来源类型	可提取的术语	示例
接口文档	API路径、请求参数名、响应字段名	/contract/info/page, contractCode, createUserName
需求文档	表名、字段代码、业务实体编码	contract_archive_info, contract_code
图谱节点	source_file 中的路径片段、类名	ContractInfoRest
文档正文	任何明确提及的技术标识	config.js, advanceUser

同时从中文术语推断可能的技术命名：

• 业务实体 → 可能的模块/目录名（如"合同管理" → contractManage、ContractInfo）
• 业务动作 → 可能的 API/方法名（如"查询合同" → searchContract、contractPage）

步骤 2：搜索源代码

用提取的技术术语在 {kb_dir}/source/repos/ 中搜索：

• Glob 搜索：按文件名模式定位关键文件
  • 前端：*{module}*/config.*、*{module}*/Index.vue、*{module}*Api.*
  • 后端：*{Module}*Controller*、*{Module}*Service*、*{Module}*Rest*
• Grep 搜索：按字段名、类名、API路径在关键目录中搜索
  • 优先搜索前端仓库的 config/views/api 目录
  • 优先搜索后端仓库的 Controller/Service/Feign 目录

步骤 3：补充回答

将源代码搜索结果作为补充信息纳入回答：

• 如果知识库文档的"关联代码"为空，用代码穿透结果填充，引用具体源文件路径和行号
• 如果知识库文档与源代码存在差异（如规格说基础字段但代码实现为配置列），必须标注差异，并注明代码证据的文件路径和行号
• 回答中增加"代码验证"章节，引用具体源文件路径和行号
• 如果代码穿透未找到相关代码，如实说明，不编造

步骤 4：代码穿透结果的呈现

在回答中新增可选章节：

## 代码验证
- [规格 vs 实现] {差异描述}（如有差异）
  证据：{源文件路径}:{行号}
- [关联代码补充] {知识库文档中缺失的代码关联}（如关联代码为空）
  来源：{源文件路径}:{行号}

4. 回答约束

严格模式约束：用户选择了哪种查询模式，就只用该模式的结果回答。禁止因为认为结果不理想而自动切换或追加其他模式的查询。如果某种模式返回结果较少或为空，如实告知用户结果有限，并建议用户自行尝试其他模式，而不是替用户切换。

代码穿透是所有模式的标配：代码穿透不是一种独立查询模式，而是每种模式回答后的验证步骤。即使严格模式约束下，代码穿透仍然执行，因为它不切换查询模式，而是在已有结果上做验证。

• 回答信息来源包括三层：知识库文档、知识图谱、源代码（通过代码穿透获得）
• 只用知识库和源代码中的实际信息回答，不编造
• 引用具体文件路径、类名、文档标题
• 结论优先：先给出结论，再展开推断过程和细节
• 面向非技术人员：关于代码的描述不要占大篇幅，除非提问者专门问代码细节
• 保持原问题：回答标题和检索关键词必须使用用户的原始提问，禁止在检索前将业务语言改写为技术术语（如把"出库直发单"改写为"CZF"）。改写会缩小搜索范围，导致漏掉上游源头逻辑。如果检索结果中发现了对应的技术编码，在回答正文中补充说明即可，但不能用它替换原问题。
• 溯源到底：当问题是"X 是怎么解析/产生/来的"这类溯源型提问时，找到一层解析逻辑后不能停，必须继续追问"这个输入值又是谁设置的"，直到追溯到系统边界（上游推送的原始字段）。只描述中间某一层映射机制不算完整回答。
• 规格与实现必须对齐：当知识库文档描述了业务规则或功能定义，而源代码的实际实现与文档存在差异时，必须标注差异并在"代码验证"章节中说明。这是回答质量的关键维度——用户往往需要知道"实际怎么做"而非仅"规范怎么写"。