Skills
skills/skills.netease.im/cw-retriever

cw-retriever

SKILL.md

本地知识库检索 Skill（cw-retriever）

知识库目录说明

  • 知识库存放在一个根目录下，包含多种文件类型（.md/.txt、.pdf、.xlsx 等），通常按类型或业务用途拆分为多级子目录
  • 采用分层目录索引文件：
    • 根目录有一个 data_structure.md，说明主要的「领域目录」及其用途，并为每个重要子目录/文件提供一句话业务摘要和若干 Tags（高频搜索词）
    • 每个领域目录下可以有自己的 data_structure.md，说明该目录下有哪些子目录/文件及各自用途，同样需要为关键文件维护「摘要 + Tags」信息，方便在 grep 阶段以极低成本定位到目标子目录
    • 更深一层的子目录也可以继续有 data_structure.md，形成多级索引树
    • 对于深层但极其重要的文件，应在根目录的 data_structure.md 中建立“虚拟软链接”条目（记录相对路径 + 摘要 + Tags），实现语义扁平化，减少递归查找层数
  • 知识库根目录约定：
    • 默认认为知识库位于当前项目根目录下的 knowledge/ 目录
    • 如果用户在对话中明确指定了其他路径，则以用户指定的路径为准
    • 当默认路径不存在时，应向用户确认实际的知识库根目录位置
    • 所有由检索过程生成的临时文件（如 .txt/.csv/.png 等）必须统一放在知识库根目录下的 tmp/ 目录中

data_structure.md 推荐模版

根目录 knowledge/data_structure.md 建议采用类似结构（可用表格或列表形式表达）：

  • 顶部说明本知识库整体用途与主要领域
  • 之后按「领域目录 / 关键文件」列出：
    • 路径：相对知识库根目录的路径，如 sales/、sales/Q1/report_2023.xlsx
    • 类型：dir / file / virtual-link
    • 摘要：一句话说明业务含义和时间/地域范围
    • Tags：与该目录/文件高频相关的检索词（中英文皆可）

示例（列表形式）：

  • sales/

    • 类型：dir
    • 摘要：公司销售相关数据与报表，按年度/季度拆分
    • Tags：销售，Sales，营收，GMV

  • sales/Q1/

    • 类型：dir
    • 摘要：某年 Q1 销售与回款明细，按大区拆分
    • Tags：Q1，一季度，华北，华南，回款

  • sales/Q1/sales_Q1.xlsx

    • 类型：file
    • 摘要：包含华北/华南等大区 Q1 销售额与回款统计，含按客户维度明细
    • Tags：销售额，回款，Region，客户

  • sales/annual/summary_2023.pdf

    • 类型：file
    • 摘要：2023 全年销售与利润总结报告，按产品线与区域汇总
    • Tags：年度报告，2023，利润，毛利，产品线

  • sales_2023_Q1_core.xlsx

    • 类型：virtual-link
    • 真实路径：sales/Q1/sales_Q1.xlsx
    • 摘要：（虚拟软链接）2023 Q1 核心销售与回款数据，常用于高频查询
    • Tags：高频，核心指标，销售对账

在各子目录下的 data_structure.md 可以采用同样结构，只需省略根路径前缀。

定位知识库根目录

  1. 优先听用户：如果用户给了路径（如 ./docs、./knowledge-personal），直接使用
  2. 默认根目录：否则使用 knowledge/
  3. 使用 shell 检查目录是否存在：test -d knowledge && echo "exists"
  4. 禁止使用 Glob 判断目录存在性（Glob 只返回文件路径，不返回目录本身）
  5. 如果默认目录不存在，明确告诉用户并让其指定实际路径

关键原则：先学习，再处理

遇到 PDF 或 Excel 文件时的强制检查清单：

  • ✅ 已读取对应的 references 文档学习处理方法
  • ✅ 已理解推荐的工具和命令
  • ✅ 已将文件处理（提取/转换）完成
  • ⏭️ 现在可以开始检索

禁止行为：

  • ❌ 在未读取 pdf_reading.md 的情况下直接尝试处理 PDF
  • ❌ 在未读取 excel_reading.md 的情况下直接尝试处理 Excel
  • ❌ 跳过文件处理步骤，直接对原始 PDF/Excel 进行检索

总体流程

1. 理解用户需求

  • 提取主题/领域关键词（如"销售报表""系统架构""接口文档"）
  • 识别时间或范围限定（如"2023 年 Q1""最近版本"）
  • 确定需要的输出类型（解释、摘要、具体字段数值等）
  • 确定知识库根目录

2. 分层查看目录索引

  • 使用「当前工作目录」概念，从知识库根目录开始
  • 在当前目录下查找 data_structure.md：
    • 使用 Read 读取前 300 行了解目录结构
    • 基于用户问题挑选最相关的子目录或文件
  • 对候选子目录：递归进入，继续查找其中的 data_structure.md
  • 对候选业务文件：收集为最终的检索目标列表

3. 学习文件处理方法（遇到 PDF/Excel 时强制执行）

4. 按文件类型执行处理和检索

对每类候选文件，按照下面的策略执行：

Markdown/文本文件

  1. 使用 Grep 定位关键词（支持多词联合，如 "API" + "超时"）
  2. 对于 Markdown/说明文档类文件：采用动态上下文切片，每个命中点建议读取匹配行前后各 20 行
  3. 对于纯文本或日志文件：根据实际密度，通常前后 10-20 行
  4. 对于代码文件：只需匹配行前后各 3-5 行即可，避免噪声过多
  5. 始终通过 Read 读取局部区域，避免整文件读取

PDF 文件

  1. 先读取 references/pdf_reading.md 学习方法
  2. 采用阶梯式（分级）提取策略：
    • Level 1：优先使用 pdftotext -f 1 -l 1 input.pdf tmp/input_p1.txt 仅提取第 1 页（通常包含目录或摘要），基于该页内容快速判断相关性
    • Level 2：确认 PDF 与问题高度相关时，再执行全量 pdftotext input.pdf tmp/input_full.txt，输出到 tmp/ 目录中的临时文件
  3. 对提取出的 .txt 文件使用 grep 检索，并根据文件类型（通常视为长文本/报告）按命中点前后各 10-20 行进行上下文切片
  4. 所有 PDF 转换产生的文本文件必须带有清晰的文件名映射信息（如原始文件名 + _p1 或 _full），避免重复转换；同一会话中对同一 PDF 不得重复执行相同级别的转换

Excel 文件

  1. 先读取 references/excel_reading.md 和 references/excel_analysis.md
  2. 始终先进行Schema 预读：使用 pandas.read_excel(..., nrows=5) 读取少量行，明确列名和数据类型（Dtypes），并将该结构信息缓存为会话内的元数据（如列清单、关键业务列）
  3. 在充分理解用户问题后（例如“查金额”“看回款时间”“比对地区销量”），基于 Schema 只选择必要的列，强制在 read_excel 中使用 usecols 参数进行列过滤式读取，尽量避免加载不相关列
  4. 对于大表或多 Sheet 情况，优先从摘要/汇总 Sheet 开始（可由 references/excel_analysis.md 中的推荐模式指导）
  5. 使用过滤和聚合方法检索数据，尽量在 DataFrame 层完成筛选/分组/聚合，避免反复全表扫描
  6. 同一会话中，对同一 Excel 文件的 Schema 预读只允许进行一次，应复用已缓存的列结构信息

5. 迭代检索（最多 5 次）

  1. 基于问题生成/更新检索关键词（含同义词、扩展词）
  2. 选择尚未充分检索的文件或文件部分；对已经完成 PDF 转文本/Excel Schema 解析的文件，优先复用结果，禁止重复执行同一转换操作
  3. 为提升命中率，尽量将用户问题拆解为「核心词 + 属性词」组合（如 "API" + "超时"、"销售" + "华南" 等），在 grep/正则搜索时使用 word1.*word2 或 word2.*word1 的联合模式提高精准度
  4. 执行检索，并按文件类型应用合适的上下文窗口（Markdown/报告类偏大，代码类偏小）
  5. 分析获取的上下文片段，判断是否足够回答问题
  6. 如果连续多轮检索仍然命中稀少或噪声较多，需要回溯到更高一层的 data_structure.md，重新审视当前目录是否选错或是否存在更合适的子目录/文件

终止条件：

  • 找到足够支撑回答的上下文；或
  • 已达到 5 次尝试仍未找到合适信息

6. 答案组织与溯源

  • 给出清晰、直接的回答
  • 指出使用过的文件名和大致位置（章节、行数、页数）
  • 如果答案基于推断或信息不完全，明确标注不确定性

公共检索原则

关键词选择策略

  • 从用户问题提取 3-8 个关键词（含英文缩写、同义词）
  • 可组合词组（如 "销售 报表"、"API 接口 超时"）
  • 包含业务词、技术术语、常见缩写（如 "uv"、"pv"、"GMV"）
  • 当初始关键词检索命中率较低时，应参考 references/ 中的行业术语/同义词表，自动扩展同义词或近义表达（如将“利润”扩展为“净利/收益/毛利”等），再发起新一轮检索

references/ 术语与同义词库（建议约定）

为提升自动扩展效果，推荐在知识库根目录维护 references/ 子目录，并约定：

  • references/terms_business.md：业务术语与同义词
    • 建议用表格或列表形式记录：
      • 业务词：如 利润
      • 同义词/近义词：如 净利，收益，毛利
      • 典型上下文/示例：简要说明这些词在报表/文档中常见的组合（如“利润表”“净利润率”）
  • references/terms_tech.md：技术/系统相关术语
    • 包含接口、模块、缩写（如 API、TPS、QPS、超时/Timeout 等）的常见别名

在检索流程中：

  • 遇到命中率低或 0 命中的情况时，优先从上述术语库中查找当前关键词的同义词集合，并自动扩展检索词
  • 对于 Excel/报表场景，可特别关注字段名的常见别称（如 amount/金额/amt），用于推断 usecols 和聚合逻辑

grep 检索基本原则

  • 始终指定精准的 include 和 path，避免搜索整个目录
  • 对每个命中只读取匹配附近的局部区域（上下若干行），行数随文件类型动态调整（Markdown/报告类比代码类更大，代码类更小）
  • 支持多关键词联合匹配（如使用 grep -E "word1.*word2|word2.*word1"）以提升召回精度和降低噪声
  • 保存「文件名 + 位置信息 + 文本片段」，并在会话内维护一个已处理文件缓存：
    • 对同一个大型 PDF，若已完成某一级别的 pdftotext 转换，本轮会话内不得重复执行相同转换
    • 对同一个 Excel 文件，若已完成 Schema 预读和列清单记录，应直接复用缓存信息
    • 对命中的文本/Markdown 文件，可记录已检索过的行段范围，避免对同一大段反复扫描

注意事项

  • 禁止使用网络搜索获取知识库内容
  • 禁止直接读取整个大文件
  • 始终先通过索引、目录、关键词等方式缩小范围后再读

安全与清理协议

  • 所有中间产物（如 PDF 转出的 .txt、Excel 导出的中间 .csv 或分析图表 .png 等）必须统一写入知识库根目录下的 tmp/ 目录，禁止散落在业务目录中
  • 临时文件命名应携带来源文件名和用途信息（如 report_2023Q1_p1.txt、sales_detail_schema.json 等），方便在会话内复用和追踪
  • 在单次检索任务结束时，应说明本次任务中可能生成的临时文件类型，并建议由上层调度或定期脚本清理 tmp/ 目录中过期文件，避免磁盘空间膨胀影响后续检索
  • 在描述检索过程时，注意标明哪些文件是“原始知识库文件”，哪些是“临时转换文件”，避免误将临时文件当作正式资料引用

回答风格

  • 尽量用用户提问的语言（中文/英文）作答
  • 先给出结论，再给出简要依据
  • 列出引用的文件和大致位置，例如：
    • 来源：design/api_gateway.md 第 100 行附近
    • 来源：reports/2023_Q1_sales.xlsx Summary 工作表

信息缺失时

  • 明确说明在当前知识库中没有找到完全匹配的信息
  • 不臆造事实
  • 提示用户可以如何帮助缩小范围：
    • 指定更具体的目录/文件
    • 提供更精确的关键词或字段名
    • 指定时间/版本范围
Installs
1
Source
skills.netease.…6bd90a10
First Seen
Apr 21, 2026