local-knowledge-retrieval

name	local-knowledge-retrieval
description	在本地 KnowledgeBase 目录中检索知识库内容。用户问题涉及“本地知识库”“知识库检索”“从本地文档回答问题”等时触发，严格按各知识库 README 规范执行检索。
allowed-tools	Read, Glob, Grep

本地知识库检索（Local Knowledge Retrieval）

面向本地文件系统中位于 KnowledgeBase/ 目录下的各类知识库，提供标准化的检索流程。目标是：在不同知识库结构与规范下，仍然保持一致的检索逻辑和结果质量。

触发条件识别（Phase 1）

当满足以下任一条件时，应优先考虑调用本技能：

• 用户明确提到“本地知识库”“本地文档知识库”“离线知识库”等
• 用户说明“从本地文档中找答案”“从知识库里查一下”“在 KnowledgeBase 里搜一下”等
• 上下文中提到具体知识库名称，并强调“本地”“本机”“仓库内”的知识
• 其他技能无法覆盖，而问题明显依赖项目内的本地文档或知识集合

调用后，本技能假定已获得：

• user_query: 用户自然语言问题（必需）
• specified_kb：用户显式指定的知识库名称或路径标识（可选）

知识库定位阶段（Phase 2）

知识库统一位于工作区根目录下的 KnowledgeBase/ 目录中，每个子目录代表一个独立知识库，其根目录下必须存在 README.md 作为规范说明文件。

2.1 用户已指定知识库

当 specified_kb 存在且可解析时：

• 将目标知识库根目录解析为：KnowledgeBase/<specified_kb>/
• 验证该目录是否存在
  • 若不存在：记录错误原因，转入“未找到相关知识”的分支
  • 若存在：继续进入 Phase 3

解析规则示例（按优先级）：

• 若用户提供完整路径片段，如 KnowledgeBase/XXX/，直接使用
• 否则将文本视为知识库目录名，如 Architecture → KnowledgeBase/Architecture/

2.2 用户未指定知识库

当 specified_kb 不存在时，需要基于 user_query 智能选择最可能相关的知识库：

• 使用 Glob 枚举 KnowledgeBase/ 下的直接子目录（知识库列表）
• 对每个知识库：
  • 读取其 README.md（见 Phase 3）
  • 粗略分析其适用范围、领域描述、关键词
• 将 user_query 中的核心名词、领域词与各知识库 README 中的描述进行匹配
• 选择匹配度最高的一个作为目标知识库

若没有任何知识库目录存在或没有 README 可用：

• 直接进入“未找到相关知识”分支，并说明原因（例如：“未检测到任何 KnowledgeBase/* 知识库”）

知识库使用准备（Phase 3）

进入目标知识库根目录（记为 KB_ROOT）后，必须首先读取并理解 KB_ROOT/README.md：

• 使用 Read 访问 KB_ROOT/README.md
• 从中提取以下关键信息：
  • 知识库的组织结构（例如：按主题、按模块、按日期等）
  • 推荐/规定的检索方法（例如：先看索引，再跳转到具体目录）
  • 命名约定和重要路径（例如：docs/, specs/, faq/ 等）
  • 任何特殊说明（例如：只使用某些后缀的文件，忽略草稿目录等）

在后续所有检索步骤中，必须优先遵循该 README 中的规范，不得随意忽略或跳过。

知识检索执行（Phase 4）

4.1 提取核心关键词

对 user_query 做轻量语义分析，提取关键词和约束：

• 领域/模块名（例如：“支付”“权限”“UI 布局”）
• 资源类型（例如：“设计文档”“接口说明”“配置说明”“FAQ”）
• 附加条件（例如：“最新版本”“v2 接口”“仅限后端实现”）

在内部状态中记录：

• keywords[]: 去重后关键词列表
• constraints[]: 额外限制条件

4.2 遵循 README 的检索方法

根据 KB_ROOT/README.md 中规定的检索方法来选择检索策略。常见模式包括但不限于：

• 先查索引文件（如 index.md、SUMMARY.md、目录导航文档），再跳转到具体条目
• 按模块目录组织（如 module-a/*, module-b/*），根据关键词选择模块再深入检索
• 已定义特定检索入口（如 search/, faq/, patterns/ 等）

在任何情况下：

• 优先使用 README 中明确指定的路径和文件作为入口
• 如果 README 未给出明确检索规则，再结合 Glob 和 Grep 进行关键词搜索

4.3 定位具体知识文件

在遵循 README 的前提下，结合 keywords[] 和 constraints[]：

• 使用 Glob 限定候选文件范围（例如：**/*.md, docs/**/*.md, specs/**/*.md 等）
• 使用 Grep 在候选文件中搜索关键词组合，优先保留命中多个关键词的文件
• 考虑以下优先级排序：
  • 命中多个关键词的文件 > 仅命中单个关键词
  • 位于 README 强调目录下的文件 > 其他目录
  • 文件名本身包含关键词的文件 > 仅内容命中的文件

得到一个按相关度排序的文件列表，并选取 Top N（例如 N=3~10）作为主要参考文件。

4.4 读取知识内容

对于选中的每个文件：

• 使用 Read 读取内容（必要时分段读取）
• 按需提取与 user_query 直接相关的段落、章节或小节
• 在内部记录：
  • file_path: 文件路径（相对 KB_ROOT）
  • snippets[]: 与问题高度相关的内容片段
  • score: 该文件与问题的相关性评分（相对值即可）

检索结果处理（Phase 5）

5.1 找到相关知识的情况

当存在至少一个包含有效 snippets[] 的文件时，需要生成清晰、结构化的回答。输出应包括两部分：

1. 答案总结（面向用户）

   • 使用用户问题的语言进行回答
   • 先给出简洁的直接回答或结论
   • 再补充关键要点、步骤或注意事项
   • 保持条理清晰，可使用小标题和列表结构

2. 来源说明（可选但推荐）

   • 列出用于回答问题的主要文件及路径（相对 KnowledgeBase/ 或 KB_ROOT）
   • 对每个文件简要说明其角色（例如：“接口规范”“架构说明”“使用手册”等）
   • 如有必要，引用部分关键信息片段，便于用户进一步查阅

回答时要显式声明：知识来源于本地 KnowledgeBase，而非网络或外部搜索。

5.2 未找到相关知识的情况

在以下任一情况发生时，应视为“未找到相关知识”：

• KnowledgeBase/ 目录不存在，或其中无任何知识库子目录
• 目标知识库根目录不存在，或缺失 README.md
• 按 README 规范检索后，没有任何文件命中关键词
• 虽然有命中文件，但内容与 user_query 显然不符，无法给出可靠回答

此时需要：

• 明确告知用户：“本地知识库中不存在相关知识”
• 简要说明判断依据，例如：
  • “未检测到 KnowledgeBase 目录”
  • “指定的知识库不存在或缺少 README.md”
  • “在相关知识库中未找到与问题关键词匹配的内容”
• 如果合适，可以建议用户：
  • 将相关文档补充到合适的知识库中
  • 或调整问题描述（例如增加模块/版本/场景信息）后再次尝试

技能输入输出接口（Phase 6）

输入约定

• user_query（string，必需）：用户的自然语言问题
• specified_kb（string，可选）：用户显式指定的知识库名或路径标识
• language（string，可选）：优先使用的回答语言；默认跟随 user_query

输出约定

输出应当是一个面向用户的自然语言回答，并在内部满足以下结构化信息：

• answer: 结构化的最终回答文本（包含结论与要点）
• kb_name: 实际使用的知识库名称或路径
• sources[]: 用于回答的文件列表（含相对路径及简要说明）
• found: 布尔值，表示是否在本地知识库中找到了相关知识
• notes: 补充信息（例如：可能的其他相关知识库、检索时的注意事项等）

在对话中呈现时：

• 若 found = true：重点展示 answer，并可简要列出 sources
• 若 found = false：必须包含“本地知识库中不存在相关知识”的明确提示

技能结束与复用

完成上述检索流程后：

• 本次调用结束，等待下一次触发
• 不在内部缓存用户问题的敏感信息
• 在后续会话中再次被调用时，仍需从知识库定位与 README 解析阶段重新开始，以保证与知识库最新状态保持一致

通过以上规范，本技能可以在不同场景下，对不同结构的本地知识库提供一致、可复用、可解释的检索体验。