Files

T

Zhengshou Lai 1bead9a6d8 chore: persist memories and excerpts under knowledge/ instead of .claude/

Move documented and skill paths to knowledge/memories and knowledge/files
(project root, mappable to @knowledge) to reduce sandbox issues on .claude/.
Update CLAUDE.md memory protocol, update-mykb-* skills, and settings.local.json
bootstrap check for core.json.

Made-with: Cursor

2026-04-09 10:36:00 +08:00

16 KiB

Raw Blame History

name, description

name	description
update-mykb-files	Local filesystem RAG-style retrieval: user path, @ files, or workspace—no fixed KB root; prefer data_structure.md then grep/limited Read; PDF/Excel only after this skill's references. Save reusable clips to project knowledge/files/ (Cursor @knowledge); pointers in knowledge/memories via update-mykb-memories. Avoid writing under .claude/ when restricted. Triggers: update-mykb-files; 检索/查资料/找文件/在某目录/摘录/存档; local search, find in folder, read my PDF, grep project, save excerpt, knowledge base on disk.

name

description

update-mykb-files

Local filesystem RAG-style retrieval: user path, @ files, or workspace—no fixed KB root; prefer data_structure.md then grep/limited Read; PDF/Excel only after this skill's references. Save reusable clips to project knowledge/files/ (Cursor @knowledge); pointers in knowledge/memories via update-mykb-memories. Avoid writing under .claude/ when restricted. Triggers: update-mykb-files; 检索/查资料/找文件/在某目录/摘录/存档; local search, find in folder, read my PDF, grep project, save excerpt, knowledge base on disk.

本地文件检索与摘录（update-mykb-files）

检索范围与目录结构

对象：本机文件系统上、当前工具与环境允许访问的任意目录与文件（绝对路径、~/…、相对工作区路径等）。不因 skill 名称限制在某个子树；若沙盒或权限收窄，以实际能读到的路径为准。用户反复使用的资料根路径可记在 update-mykb-memories，减少每次重新确认。
资料往往放在一个检索根目录下，包含多种类型（如 .md/.txt、.pdf、.xlsx 等），可按业务拆多级子目录。
可选采用分层目录索引文件（有则用，无则靠路径/文件名与 grep 渐进查）：
- 某层目录可有 data_structure.md，说明子目录与文件的用途。
- 子目录可继续嵌套 data_structure.md，形成索引树。
检索根目录怎么定（优先级）：
- 用户在对话里写明路径（最优先）。
- 否则从上下文推断：@ 引用、已打开文件所在目录、问题中的路径、当前工作区根等；推断仍模糊时追问用户，勿臆造目录。
- 读与写分离：读的是上面确定的任意路径；摘录落盘默认写到当前项目下的 knowledge/files/（见下文；可用 @knowledge），勿与「被读的资料目录」混为一谈。
单个业务文件可能很大：
- 不要直接用 Read 读取整文件
- 对 PDF、Excel 使用对应 Skill 进行结构化处理后，再结合 grep/局部读取做精细检索

摘录池：`knowledge/files/`

用途：在日常对话或阅览任意被检索文件时，若出现以后还可能引用的内容（定义、结论、命令、表格摘要、长引用片段），写入当前项目下的 knowledge/files/，便于后续用 Grep/Read 复用；不要把整本 PDF/整表原样拷入，优先摘要 + 来源路径。
与 update-mykb-memories 分工：极短、稳定的事实与偏好写入 knowledge/memories/（见 skill update-mykb-memories）；较长说明、摘录、结构化笔记放 knowledge/files/。
路径：根目录为仓库内 knowledge/files/（不存在则创建；父级 knowledge/ 与 Cursor @knowledge 对应）。可选子目录：clips/、notes/、exports/。
命名：YYYY-MM-DD_<主题简写>.md 或 <domain>_<topic>.md；单文件控制体量，必要时拆篇。
内容建议：每条摘录开头用简短元信息（来源文件/URL、日期、一两句用途），正文用 Markdown；避免敏感凭证。
检索：回答后续问题时，若与已存摘录相关，可对 knowledge/files/ 做 Grep 或 Read，与对原始资料的检索同一套渐进式原则。

定位检索根目录与存在性

路径来源：用户显式给出的目录或文件路径优先；否则用上下文可核对的根（如工作区根、某 @ 文件的上级目录），并在不确定时让用户确认。
存在性：对将要作为检索起点的目录，用 shell 检查，例如 test -d "<检索根>"（将 <检索根> 换成实际路径）。禁止使用仅靠 Glob 的结果推断「目录是否存在」：Glob 只返回文件路径，不返回目录本身，空结果无法区分「目录不存在」与「目录存在但无匹配文件」。
确认存在后再展开：只有 test -d（或对单文件 test -f）通过后，才在该路径下用 Glob/Grep 递归检索；把该路径作为工具参数里的 path，例如：
- 索引文件：pattern="**/data_structure.md", path="<检索根>"
- 某类文本：pattern="**/*.md", path="<检索根>"
未给出范围时：不要猜测本机上的随机目录；说明需要用户指定「从哪个目录或哪些文件查」。

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

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

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

禁止行为：

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

总体流程

理解用户需求
- 读用户问题，提取：
  - 主题/领域关键词（如“销售报表”“系统架构”“接口文档”）
  - 时间或范围限定（如“2023 年 Q1”“最近版本”）
  - 需要的输出类型（解释、摘要、具体字段数值等）
- 确定检索根目录或具体文件列表：
  - 用户是否在问题中指定了路径或 @ 了文件/文件夹。
  - 否则从工作区、打开文件等上下文推断；仍不明确则询问用户，不设固定默认资料目录。
  - 路径须用 test -d / test -f 等方式确认可访问后再深入检索。
分层查看目录索引 data_structure.md（若存在）
- 使用一个「当前工作目录」的概念：
  - 从已确定的检索根目录开始（须先按上文确认存在；不可用 shell 的「当前工作目录」偷换概念）。
- 在当前工作目录下，如果存在 data_structure.md：
  - 使用 Read 读取该文件的前若干行（例如 limit=300），必要时分段继续读取。
  - 目标：
    - 了解当前目录下有哪些子目录和文件
    - 理解每个子目录/文件的用途说明
  - 基于用户问题，挑选最相关的若干个子目录或文件，构成候选集合。
- 对于候选子目录：
  - 递归进入该子目录，将其作为新的「当前工作目录」，继续查找其中的 data_structure.md 并重复上述过程。
  - 在递归过程中，避免一次性深入所有分支，优先沿着与问题最相关的路径向下钻取。
- 对于候选业务文件（md/文本、PDF、Excel 等）：
  - 在完成必要的目录层级探索后，收集这些文件为最终的检索目标列表。
- 在优先级排序时：
  - 优先选择用途说明与问题主题高度匹配的领域目录和文件
  - 其次考虑时间/版本等约束（如果索引中有体现）
  - 通用说明类文档（如 README.md、总体设计类文档）放在较后优先级
学习文件处理方法（遇到 PDF/Excel 时强制执行）
- 在处理 PDF 文件前：
  - 必须先读取 references/pdf_reading.md（位于本 skill 的 references/，不是被检索资料目录）学习提取方法
  - 重点了解：pdftotext 命令、pdfplumber 用法、表格提取方法
- 在处理 Excel 文件前：
  - 必须先读取 references/excel_reading.md学习读取方法
  - 必须先读取 references/excel_analysis.md学习分析方法
  - 重点了解：pandas 读取、列筛选、数据过滤
- 目的：确保使用正确的工具和方法，避免盲目检索
按文件类型执行处理和检索
- 使用刚学到的方法处理文件（提取、转换、结构化）
- 对每类候选文件，按照下面「Markdown/文本」「PDF」「Excel」策略执行
- 总原则：
  - 优先从最相关、最精确的文件开始
  - 每个文件内都渐进式地局部检索，避免一次性加载全内容
  - 若当前文件得不到满意信息，切换到下一个候选文件
迭代检索
- 所有文件类型都使用统一的「多轮迭代检索机制」（见上文公共检索原则）
答案组织与溯源
- 汇总多轮检索得到的上下文，综合回答用户问题。
- 尽量：
  - 给出清晰、直接的回答
  - 指出使用过的文件名（必要时包含大致位置，如章节或大概行数/页数）
- 如果答案基于推断或信息不完全：
  - 明确标注假设与不确定性
  - 提示用户可以补充更具体的文件范围或关键词

公共检索原则

关键词选择策略

从用户问题提取 3-8 个关键词（含可能的英文缩写、同义词、上位/下位词）
可组合词组（如 "销售报表"、"API 接口超时"）
必要时包含业务词、技术术语、常见缩写（如 "uv"、"pv"、"GMV"）

grep 检索基本原则

始终指定尽量精准的 include 和 path，避免搜索整个目录
pattern 优先尝试问题中的核心名词、术语，再尝试同义词
对于每个命中，只读取匹配附近的局部区域（上下若干行）
保存「文件名 + 位置信息 + 文本片段」

多轮迭代检索机制（最多 5 次）

所有文件类型都采用统一的迭代策略：

迭代控制
- 维护「已尝试检索次数」计数，最多 5 次
- 每次检索后累加计数
每轮迭代流程
1. 基于问题生成/更新检索关键词（可包括同义词、扩展词）
2. 选择尚未充分检索的文件或文件部分
3. 执行检索（grep/局部读取/专用 Skill 调用）
4. 分析获取的上下文片段
5. 判断是否足够回答问题
终止条件
- 找到足够支撑回答的上下文；或
- 已达到 5 次尝试仍未找到合适信息
信息不足时的处理
- 明确告知用户信息缺失或可能不在已约定的检索范围内
- 提供已找到的最接近信息，并说明不确定性
- 提示用户可以如何缩小范围（更具体的文件名、关键词、时间范围等）

注意事项

禁止用 Glob 的「有无匹配文件」代替目录存在性判断；目录是否存在应通过 shell（如 test -d）检查。
使用本 skill 做本地文件检索时，禁止使用网络搜索等其他工具替代磁盘上的资料
若用户明确要求「记住」且是短事实，交给 update-mykb-memories；若需保存可检索的长摘录，写入 knowledge/files/（见上文）。

针对不同文件类型的具体策略

1. Markdown / 文本类文件（.md, .txt, .log 等）

候选文件选择
- 根据 data_structure.md 和文件名、路径判断相关度
- 优先检索标题和目录类文件（如汇总文档、设计总览）
grep 定位与局部读取
- 使用 Grep 工具对指定候选文件，include 限定具体后缀（如 "*.md"）
- 对于有匹配的文件，使用 Read 仅读取匹配附近的局部区域：
  - 通过行号偏移和 limit 控制读取（例如从匹配行附近往前后各读取几十行）
  - 避免整文件读取
特殊处理
- 如内容仅是目录/标题，根据链接或小节名继续定位深入内容
- 应用「多轮迭代检索机制」（见上文公共检索原则）

2. PDF 文件检索策略

工作流：

首先：读取处理方法指南
- 在处理任何 PDF 之前，必须先读取 references/pdf_reading.md（位于本 skill 的 references/，不是被检索资料目录）
- 重点了解：pdftotext 命令、pdfplumber 用法、表格提取方法、快速决策表
选择候选 PDF
- 根据 data_structure.md 中的描述，选择最相关的 1-3 个文件
- 如果用户指明具体 PDF 文件，则优先使用该文件
应用学到的方法提取文本
- 使用 pdf_reading.md 中推荐的工具（优先 pdftotext 或 pdfplumber）
- 重要：使用 pdftotext input.pdf output.txt 将文本提取到文件，不要直接输出到 stdout（避免占用大量 token）
- 如需提取表格，使用 pdfplumber 的表格提取功能
对提取结果执行检索
- 使用 grep 对提取的文本进行关键词搜索
- 对于每个命中，提取命中附近范围的上下文（上下数十行或相邻几页）
- 保存「文件名 + 页码/大致位置 + 文本片段」
- 应用「多轮迭代检索机制」（见上文公共检索原则）

3. Excel 文件检索策略