taxueseek / local-seek

Name: taxueseek/local-seek
Author: taxueseek

本机文件与代码内容搜索（rg/fd/mdfind/grep 统一入口 seek.py，工具输出即答案）。与 argo 联网搜索互补：搜本机目录、代码符号、文件名、文档全文、文件结构。触发：搜本地、找文件、找代码、本机搜 xx、代码在哪、统计本地命中。

Version

SKILL.md

6.8 KB

local-seek — 本地高效搜索（v1.4.1）

搜本机文件和内容就从这里开始。工具的输出就是答案，不用再自己翻一遍。
与 Argo（联网搜索）分工：Argo 搜网络，本技能搜本机。

三层递进：先定位、再看上下文、最后精读

不要一上来就读文件。一层层往里走，每层的结果都不多：

层	干什么	命令	输出量
L1 定位	找到「在哪个文件」	seek.py "词" --count 或 --filename	每文件一行
L2 上下文	看命中位置附近	seek.py "词" --context 2	每命中 3 行
L3 精读	读关键段落	read_file 按行号局部读取	按需

每次搜索先想清楚停在哪一层，默认只做第一层。

统一入口

所有搜索都走本技能里的 scripts/seek.py（相对 argo 根：sub-skills/local-seek/scripts/seek.py），
由它决定用哪个工具，不要自己拼 rg/fd 参数：

# 以下以 argo 安装根为 cwd；或写死 $ARGO_HOME/sub-skills/local-seek/scripts/seek.py
python3 sub-skills/local-seek/scripts/seek.py "查询词"                 # 默认：当前目录全文
python3 sub-skills/local-seek/scripts/seek.py "查询词" --path ~/notes   # 指定目录
python3 sub-skills/local-seek/scripts/seek.py "词" --path ~/.agents --dot  # 连以 . 开头的目录和软链一起搜；搜 ~/.agents、~/.zcode 时要加（Spotlight 收不到这类目录，--dot 对 --spotlight 没用）
python3 sub-skills/local-seek/scripts/seek.py "词" --path . --include-noise  # repos/、tests/、tmp/、日期归档目录与真源平权（默认这些排在真源之后，但**仍然搜得到**）
python3 sub-skills/local-seek/scripts/seek.py "查询词" --count          # 先数命中，再决定是否深入
python3 sub-skills/local-seek/scripts/seek.py "查询词" --filename       # 按文件名
python3 sub-skills/local-seek/scripts/seek.py "查询词" --spotlight      # 全盘兜底（PDF/邮件/笔记）
python3 sub-skills/local-seek/scripts/seek.py "查询词" --type py,ts
python3 sub-skills/local-seek/scripts/seek.py "查询词" --json           # 结构化输出
python3 sub-skills/local-seek/scripts/seek.py "查询词" --exact          # 关闭中文扩展，精确匹配
python3 sub-skills/local-seek/scripts/seek.py "查询词" --exclude 某文件 # 额外排除（可重复）
python3 sub-skills/local-seek/scripts/seek.py --outline 文件路径        # 文件结构（def/class/标题/顶层key）
python3 sub-skills/local-seek/scripts/seek.py --lines 10-50 文件路径    # 按行读取，替代 read_file 全文
python3 sub-skills/local-seek/scripts/seek.py "裸except" --structural   # 结构搜索（空catch/裸except/装饰函数等）
python3 sub-skills/local-seek/scripts/seek.py --git-log 文件路径        # 文件的最近提交历史
python3 sub-skills/local-seek/scripts/seek.py --git-blame 12 文件路径   # 第 12 行的提交归属

内置智能行为（无需手动指定）：

固定字符串：查询是纯字面量时自动用 rg -F；含 regex 元字符但解析失败
（如 interface{}）自动回退 -F。
中文扩展：中文查询先按原词精确匹配，没命中再拆成 2 字词（2-gram）放宽
（如「数据抓取」放宽到「数据」「抓取」），这样能多搜到一些；--exact 关闭。
PCRE2 检测：查询含 look-around 时检查本机 rg 是否支持，不支持给出
明确提示而非报错。
结构搜索：--structural 按语义检索代码模式（裸 except、空 catch、
装饰函数、函数/类定义），中英文别名都认，零安装（rg -U 多行实现）。
Git 联动：--git-log / --git-blame 直接回答「这行谁改的、最近动过什么」，
文件不在仓库或未跟踪时给出明确区分，不报错。

工具选择（何时换工具）

场景	用	为什么
搜代码/正文关键词	rg（默认）	毫秒级，尊重 .gitignore，自动排除 node_modules 等
只记得文件名	--filename（fd）	按文件名模糊匹配
搜 PDF/邮件/已归档内容	--spotlight（mdfind）	用 macOS 已经建好的系统索引，不额外花时间（Windows/Linux 上没有，改用 rg 搜正文）
找代码模式（裸except/空catch等）	--structural	按语义不按字符串
追文件历史/单行归属	--git-log / --git-blame	免开终端敲 git
当前目录搜不到	先扩大 --path，再 --spotlight	先窄后宽
大仓库担心输出爆炸	--count + --max 20	先看分布再深入

执行纪律

先窄后宽：先限定目录/扩展名，搜不到再扩大。禁止一开始就全盘扫。
先数后看：--count 看分布，--context 0（默认）看命中行，最后才读文件。
指定类型：代码场景加 --type（py,ts,go…），文档场景用 --scope doc。
绝对路径优先：涉及读文件时用 read_file + 绝对路径。
不读整个文件：L3 精读用行号偏移局部读取，命中上下文不够再扩。
结果为空先换词：换同义词/拆词/去大小写，再换工具（fd→mdfind），
不要重复同一查询。
中文搜索：rg 原生支持 UTF-8，直接搜中文；长中文词会自动放宽匹配，
多搜到一些，原词命中优先。
先结构后正文：大文件先 --outline 看结构，再 --lines N-M 按需读取，
禁止直接 read_file 整个文件。
结构搜索按语义：找「是不是有裸 except」这类问题用 --structural，
不要手写正则碰运气；可用语义清单见 references/structural-search.md。
git 只读标题：--git-log 只给标题，够用就停；要看具体改动再手动 git show，
不让 seek.py 输出整段正文。

配置

排除规则与知识域：sub-skills/local-seek/config/domains.yaml
查看当前规则：python3 sub-skills/local-seek/scripts/seek.py --domains

参考

按场景的完整命令配方（进阶，非常规操作再读）：

references/rg-recipes.md — rg 分场景配方（函数定义/跨文件引用/多词/正则）
references/fd-mdfind-recipes.md — fd 与 Spotlight 配方
references/strategies.md — 三层做法的详细说明，以及怎么少花 token
references/structural-search.md — 结构搜索手册（语义规则表/别名/扩展新规则）
references/git-integration.md — git 联动用法、场景与边界
references/remote-handoff.md — 本地搜不到时的扩大与联网交接清单