argo-search 1.0.1 → 2.9.7

package/sub-skills/local-search/smart_router.py

@@ -3,7 +3,7 @@
 
 根据查询特征将请求路由到最优本地引擎组合，覆盖：
 - 中文通用 / 中文新闻 / 代码 / 学术 / 参考百科 / 事实问答 / 垂直实体
-- 与 unified-search 的 route.py 解耦，local-search 内部使用
+- 与 unified-search 的 route.py 拆开，local-search 内部使用
 """
 
 from __future__ import annotations
@@ -22,6 +22,8 @@ if not logger.handlers:
 
 # 查询特征正则
 _RE_CHINESE = re.compile(r"[一-鿿]")
+_RE_KANA = re.compile(r"[\u3040-\u30ff]")
+_RE_HANGUL = re.compile(r"[\uac00-\ud7af]")
 _RE_ACADEMIC = re.compile(
     r"\b(paper|arxiv|preprint|doi|citation|abstract|journal|conference|"
     r"peer[-\s]?review|research|survey|review|thesis|dissertation)\b|"
@@ -60,10 +62,23 @@ CATEGORY_PRIORITY = {
     "academic": ["local_arxiv", "local_semantic_scholar", "local_crossref", "local_pubmed"],
     "code": ["local_github", "local_stackoverflow", "local_gitlab", "local_npm"],
     "news": ["local_bing_news", "local_google_news", "local_duckduckgo_news"],
-    "chinese": ["local_baidu", "local_sogou", "local_bing", "local_duckduckgo"],
+    # chinese 与主路径 route_combo._select_sub_engines 中文支对齐（2026-10-06 实测）：
+    # baidu 直连 0 结果移出；sogou（~1s 相关）/360（~1s）实测可用；yandex 殿后。
+    "chinese": ["local_sogou", "local_360", "local_yandex", "local_bing", "local_duckduckgo"],
+    # ja：yandex 实测覆盖最好；bing text 后端已被 ddgs 9.14.4 移除（auto 降级）
+    "japanese": ["local_yandex", "local_duckduckgo", "local_bing"],
+    # ko 同 ja
+    "korean": ["local_yandex", "local_duckduckgo"],
     "reference": ["local_wikipedia", "local_wiktionary", "local_wikiquote"],
     "vertical": ["local_openstreetmap", "local_imdb", "local_goodreads"],
-    "web_general": ["local_bing", "local_duckduckgo", "local_mojeek", "local_startpage"],
+    # web_general 顺序 = 实测可用性（2026-10-06 重排）：
+    # ddgs 9.14.4 起 text 后端仅 brave/duckduckgo/google/grokipedia/
+    # mojeek/startpage/wikipedia/yahoo/yandex——没有 bing，local_bing 的
+    # `-b bing` 已静默降级 auto（1.6-6s 随机波动，拖早停第二引擎的尾），
+    # 故移出 web_general（chinese 域仍保留作第 4 备选）。
+    # brave 对真实查询稳定 0 结果；yandex 是唯一稳定后端（~1.9s）置首，
+    # ddg/yahoo 次之（限流时 1s 级快速失败，不拖墙钟）。
+    "web_general": ["local_yandex", "local_duckduckgo", "local_yahoo", "local_brave", "local_bing"],
 }
 
 
@@ -71,9 +86,29 @@ def extract_features(query: str) -> dict[str, Any]:
     """提取查询特征向量。"""
     total = max(len(query), 1)
     chinese = len(_RE_CHINESE.findall(query))
+    # 主语言判定：优先复用 scripts/lang_detect 单来源
+    primary_lang = "en"
+    try:
+        from lang_detect import detect_language
+        primary_lang = detect_language(query)
+    except ImportError:
+        kana = len(_RE_KANA.findall(query))
+        hangul = len(_RE_HANGUL.findall(query))
+        if kana / total >= 0.15 or (kana and chinese / total >= 0.3):
+            primary_lang = "ja"
+        elif hangul / total >= 0.15:
+            primary_lang = "ko"
+        elif chinese / total >= 0.3:
+            primary_lang = "zh"
+        else:
+            primary_lang = "en"
     return {
         "chinese_ratio": chinese / total,
-        "is_chinese": chinese / total > 0.3,
+        # is_chinese：仅当真主语言为 zh 时标中文（日文汉字查询不再误入 chinese 分类）
+        "is_chinese": primary_lang == "zh" or (
+            primary_lang not in ("ja", "ko") and chinese / total > 0.3
+        ),
+        "primary_lang": primary_lang,
         "is_academic": bool(_RE_ACADEMIC.search(query)),
         "is_code": bool(_RE_CODE.search(query)),
         "is_news": bool(_RE_NEWS.search(query)),
@@ -116,6 +151,11 @@ def route_query(
 
     # 特征 → 候选分类
     candidates: list[tuple[str, float]] = []
+    # 日/韩主语言：优先对应语言的本地引擎分类
+    if features.get("primary_lang") == "ja":
+        candidates.append(("japanese", 1.0))
+    elif features.get("primary_lang") == "ko":
+        candidates.append(("korean", 1.0))
     if features["is_academic"]:
         candidates.append(("academic", 1.0))
     if features["is_code"]:
@@ -130,13 +170,13 @@ def route_query(
         # 事实查询优先百科与通用搜索
         candidates.append(("reference", 0.85))
         candidates.append(("web_general", 0.7))
-    if features["is_chinese"]:
+    if features["is_chinese"] and features.get("primary_lang") != "ja":
         candidates.append(("chinese", 0.85))
         # 中文新闻类查询增强
         if features["is_news"]:
             candidates.append(("news", 0.9))
 
-    # 兜底
+    # 保底
     if not candidates:
         candidates.append(("web_general", 0.5))
 
@@ -168,7 +208,7 @@ def route_query(
         if len(selected) >= max_engines:
             break
 
-    # 兜底：如果都没选到，返回前几个启用的可用引擎
+    # 保底：如果都没选到，返回前几个启用的可用引擎
     if not selected:
         selected = reg.list_engines(available_only=require_available, enabled_only=True)[:max_engines]
         reasons = [f"{e}(fallback)" for e in selected]

package/sub-skills/local-seek/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: local-seek
+version: 1.6.0
+description: 本机文件与代码内容搜索（rg/fd/mdfind/grep 统一入口 seek.py，工具输出即答案）。与 argo 联网搜索互补：搜本机目录、代码符号、文件名、文档全文、文件结构。触发：搜本地、找文件、找代码、本机搜 xx、代码在哪、统计本地命中。
+---
+
+# local-seek — 本地高效搜索（v1.6.0）
+
+搜本机文件和内容就从这里开始。**工具的输出就是答案**，不用再自己翻一遍。
+与 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 参数：
+
+```bash
+# 以下以 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 收不到）
+python3 sub-skills/local-seek/scripts/seek.py "词" --path . --include-noise  # repos/、tests/ 等与真源平权（默认排真源之后，仍搜得到）
+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 行的提交归属
+```
+
+内置智能行为（固定字符串回退、中文 2-gram 扩展、PCRE2 检测、结构搜索、
+git 联动等）自动生效，明细见 references/auto-behaviors.md。
+
+## 工具选择（何时换工具）
+
+| 场景 | 用 | 为什么 |
+|------|-----|--------|
+| 搜代码/正文关键词 | rg（默认） | 毫秒级，尊重 .gitignore，自动排除 node_modules 等 |
+| 只记得文件名 | --filename（fd） | 按文件名模糊匹配 |
+| 搜 PDF/邮件/已归档内容 | --spotlight（mdfind） | 用系统已建好的索引，不额外花时间（Windows/Linux 无此工具，改用 rg） |
+| 找代码模式（裸except/空catch等） | --structural | 按语义不按字符串 |
+| 追文件历史/单行归属 | --git-log / --git-blame | 免开终端敲 git |
+| 当前目录搜不到 | 先扩大 --path，再 --spotlight | 先窄后宽 |
+| 大仓库担心输出爆炸 | --count + --max 20 | 先看分布再深入 |
+
+## 执行纪律
+
+1. **先窄后宽**：先限定目录/扩展名，搜不到再扩大。禁止一开始就全盘扫。
+2. **先数后看**：--count 看分布，--context 0（默认）看命中行，最后才读文件。
+3. **指定类型**：代码场景加 --type（py,ts,go…），文档场景用 --scope doc。
+4. **绝对路径优先**：涉及读文件时用 read_file + 绝对路径。
+5. **不读整个文件**：L3 精读用行号偏移局部读取，命中上下文不够再扩。
+6. **结果为空先换词**：换同义词/拆词/去大小写，再换工具（fd→mdfind），
+   不要重复同一查询。
+7. **先结构后正文**：大文件先 --outline 看结构，再 --lines N-M 按需读取，
+   禁止直接 read_file 整个文件。
+8. **结构搜索按语义**：找「是不是有裸 except」这类问题用 --structural，
+   不要手写正则碰运气；可用语义清单见 references/structural-search.md。
+9. **git 只读标题**：--git-log 只给标题，够用就停；要看具体改动再手动 git show。
+
+## 排序与性能（v1.6.0）
+
+内容命中按 **BM25F 相关度重排**（实现文件不再被文档顺带提及淹没），池子按
+**文件轮转配额**（每文件 ≤8 行）；文件名场景用 **fzf FuzzyMatchV2** 评分。
+确定性不变：与 rg 发射序无关，并列分按 (路径,行号)。
+
+大树上的内容搜索可开 **FTS5 索引快路**：`ARGO_LOCAL_FTS=1`（默认关），
+首次对该目录先跑 `scripts/seek_fts.py rebuild <目录>` 预热，之后毫秒级返回；
+rg 永远兜底（索引未建成/带正则/零命中时自动回退）。明细见
+references/auto-behaviors.md。
+
+逃生门（默认行为已是最优，仅在回退/实验时用）：
+- `ARGO_SEEK_CONTENT_RERANK=0` 关闭内容重排，恢复 (路径,行号) 原序
+- `ARGO_SEEK_FRECENCY=1` 开启访问频次加成（实验项，默认关）
+- 排序质量用 `scripts/eval_rank.py` 评测（MRR/耗时，支持 --compare）
+
+## 配置
+
+排除规则与知识域：`sub-skills/local-seek/config/domains.yaml`
+查看当前规则：`python3 sub-skills/local-seek/scripts/seek.py --domains`
+
+## 参考
+
+按场景的完整命令配方（进阶，非常规操作再读）：
+
+- references/rg-recipes.md — rg 分场景配方（函数定义/跨文件引用/多词/正则）
+- references/auto-behaviors.md — 自动行为明细（重排/FTS/中文扩展/PCRE2/git）
+- references/fd-mdfind-recipes.md — fd 与 Spotlight 配方
+- references/strategies.md — 三层做法的详细说明，以及怎么少花 token
+- references/structural-search.md — 结构搜索手册（语义规则表/别名/扩展新规则）
+- references/git-integration.md — git 联动用法、场景与边界
+- references/remote-handoff.md — 本地搜不到时的扩大与联网交接清单

package/sub-skills/local-seek/config/domains.yaml

@@ -0,0 +1,20 @@
+# local-seek 搜索配置
+# 修改后即时生效，无需重启。
+
+# 附加排除规则（追加到内置默认排除之后）
+# 内置默认排除：node_modules .git __pycache__ .venv dist build target 等
+exclude:
+  - "*.min.js"
+  - "*.map"
+  - "*.lock"
+  - ".turbo"
+  - ".nyc_output"
+  - "*.egg-info"
+
+# 知识域：经常要搜的目录，填在这里可被 --domains 查询
+# 示例：- ~/Documents/notes
+knowledge_domains: []
+
+# 输出控制
+max_results: 30        # 默认最大结果数
+snippet_chars: 120     # 命中行截断长度

package/sub-skills/local-seek/references/auto-behaviors.md

@@ -0,0 +1,24 @@
+# seek.py 自动行为明细（按需读取）
+
+这些行为全部自动生效，无需手动指定；排障或想理解「为什么这么搜」时再读。
+从 SKILL.md 挪入（v1.6.0，触发即注入预算 7KB 的口径）。
+
+- **固定字符串**：查询是纯字面量时自动用 rg -F；含 regex 元字符但解析失败
+  （如 interface{}）自动回退 -F。
+- **中文扩展**：中文查询先按原词精确匹配，没命中再拆成 2 字词（2-gram）放宽
+  （如「数据抓取」放宽到「数据」「抓取」），这样能多搜到一些；--exact 关闭。
+- **PCRE2 检测**：查询含 look-around 时检查本机 rg 是否支持，不支持给出
+  明确提示而非报错。
+- **结构搜索**：--structural 按语义检索代码模式（裸 except、空 catch、
+  装饰函数、函数/类定义），中英文别名都认，零安装（rg -U 多行实现）。
+- **Git 联动**：--git-log / --git-blame 直接回答「这行谁改的、最近动过什么」，
+  文件不在仓库或未跟踪时给出明确区分，不报错。
+- **BM25F 内容重排**：文件名 2.0 / 目录 0.6 / 行文本 1.0 三字段，BM25+ 下界 +
+  逐字短语加成 + 文件级命中数先验；池子按文件轮转配额（每文件 ≤8 行）。
+  `ARGO_SEEK_CONTENT_RERANK=0` 关闭。
+- **fzf V2 文件名评分**：驼峰/边界/gap 惩罚，DP 最优对齐（junegunn/fzf 口径）。
+- **FTS5 索引快路**：`ARGO_LOCAL_FTS=1` 后，无正则元字符的内容查询走
+  SQLite FTS5 倒排索引（unicode61 + CJK 逐字短语），只在索引过期（TTL 120s）
+  时付一次增量刷新（rg --files 清单 + 改动文件重读，预算 1.5s）。rg 永远
+  兜底：索引未建成/查询带正则/零命中语义见 seek_fts.py docstring。大树首次
+  建索引较慢，先跑 `python3 scripts/seek_fts.py rebuild <目录>` 预热。

package/sub-skills/local-seek/references/fd-mdfind-recipes.md

@@ -0,0 +1,62 @@
+# fd 与 Spotlight（mdfind）配方
+
+## fd — 按文件名查找
+
+统一入口用 `seek.py "词" --filename`，手动配方：
+
+```bash
+# 文件名模糊匹配（忽略大小写）
+fd "login"
+
+# 指定目录
+fd "auth" ~/src
+
+# 限定扩展名
+fd -e py "schema"
+fd -e md -e txt "notes"
+
+# 只看目录
+fd -t d "config"
+
+# 隐藏文件
+fd -H ".*rc"
+```
+
+注意：fd 默认自动排除 .gitignore 中的内容，无需手动加 -E。
+
+## mdfind — macOS Spotlight 全盘兜底
+
+用系统预建索引，覆盖 rg 搜不到的东西（PDF 正文、邮件、已归档目录、图片元数据）。
+统一入口用 `seek.py "词" --spotlight`。
+
+```bash
+# 全盘搜索（走系统索引，毫秒级）
+mdfind "关键词"
+
+# 限定目录
+mdfind -onlyin ~/Documents "关键词"
+
+# 限定文件名
+mdfind -name "report"
+
+# 文件名+内容混合（kMDItem 查询语法）
+mdfind "kMDItemFSName == '*.pdf' && 关键词"
+
+# 只看最近修改
+mdfind "kMDItemFSContentChangeDate >= $time.today(-7) 关键词"
+```
+
+### 何时用 mdfind 而不是 rg
+
+| 信号 | 用 |
+|------|----|
+| 全盘搜，不知道文件在哪 | mdfind |
+| 搜 PDF/邮件/已归档内容 | mdfind |
+| 目录未建立 Spotlight 索引（外接盘/网络盘） | 退回 rg + 明确 --path |
+| 代码仓库内 | rg（永远优先） |
+
+### 坑
+
+- 外接盘、~/Library 部分目录可能未索引，mdfind 搜不到
+- mdfind 的查询是「关键词匹配」，中文分词效果取决于系统
+- 结果不带行号，定位到文件后需再 rg 找行

package/sub-skills/local-seek/references/git-integration.md

@@ -0,0 +1,54 @@
+# Git 联动手册（--git-log / --git-blame）
+
+本地搜索找到文件只是第一步，经常要接着回答「这行谁改的、为什么改、什么时候
+改的」。git 联动让 seek.py 直接给出答案，不用再开终端敲 git。
+
+## 用法
+
+```bash
+# 文件的最近提交历史（默认 10 条，oneline）
+python3 ~/.agents/skills/argo/sub-skills/local-seek/scripts/seek.py --git-log 文件路径
+
+# 某一行是谁在哪个提交改的
+python3 ~/.agents/skills/argo/sub-skills/local-seek/scripts/seek.py --git-blame 12 文件路径
+```
+
+文件路径作为位置参数（或 `--path`），两者互斥时位置参数优先。
+
+## 输出示例
+
+```text
+# --git-log
+local-seek: seek.py 最近 3 条提交
+cd02e96 补全结构搜索与 git 联动
+a1b2c3d 中文扩展：空格噪音修复
+
+# --git-blame 12
+local-seek: seek.py 第 12 行
+cd02e96f (taxueseek 2026-07-03 20:58:20 +0800 3)  ap.add_argument("--git-blame"...
+```
+
+## 适用场景
+
+| 场景 | 命令 | 读什么 |
+|------|------|--------|
+| 这文件最近在动什么 | --git-log | 提交标题序列 |
+| 某行代码的来历 | --git-blame N | 提交哈希、作者、时间 |
+| 拿到哈希后看完整改动 | --git-log 后再 `git -C 目录 show 哈希` | diff 正文 |
+| 谁改坏了某段逻辑 | --git-blame 定位行 → show 对应提交 | 上下文 |
+
+## 边界与局限
+
+- **未跟踪文件**：untracked（从未 git add）的文件无历史，报「无提交历史」，
+  不是错误。把文件 git add 后即有。
+- **仓库外文件**：不在任何 git 仓库内的文件报「不在 git 仓库中」。
+- **行号漂移**：blame 按当前行号定位，改动过的文件行号会移动，属正常。
+- **大文件历史**：--git-log 只读标题不看 diff，是低成本路径；要 diff 再手动
+  git show，不要指望 seek.py 输出正文。
+- **子模块/符号链接**：git -C 父目录 对符号链接指向的仓库无效，需先解析真实路径。
+
+## 与本地搜索的组合套路
+
+1. 搜到文件里的目标行：`seek.py "关键词" --path ~/repo --max 5`
+2. 定位关键行号后 blame：`seek.py --git-blame 行号 文件路径`
+3. 拿提交哈希再看 diff：`git -C ~/repo show 哈希`

package/sub-skills/local-seek/references/remote-handoff.md

@@ -0,0 +1,46 @@
+# 本地搜不到时的交接（remote-handoff）
+
+local-seek 只负责本机。本地无结果不意味着结束，按本清单逐步扩大，最后
+交接给联网搜索。判断标准写死在每一步，避免无限折腾。
+
+## 交接顺序（每步只做一次，失败即进下一步）
+
+```text
+L1 当前目录 rg 搜索（默认）
+  ↓ 无命中
+L2 --path 扩大到知识域（~/notes、~/Documents、技能库等）
+  ↓ 无命中
+L3 --spotlight 全盘兜底（mdfind，走 macOS 索引，覆盖 PDF/邮件/笔记）
+  ↓ 无命中
+L4 换词重试 1 次（同义词/拆词/去掉修饰词），仍无
+  ↓
+L5 交接联网：unified-search（多引擎聚合）或 argo（深度研究）
+```
+
+## 判断标准
+
+| 现象 | 结论 | 动作 |
+|------|------|------|
+| L1-L3 均无命中 | 本机确实没有，或不在已索引范围 | 进 L4 |
+| 换词后仍无 | 大概率是「没有这个内容」而非「没找到」 | 进 L5 |
+| L5 联网也无 | 内容不存在或太新未收录 | 如实告知，停止搜索 |
+| 命中但太少/太泛 | 不是交接问题，是词选得不好 | 回到 L2/L4 调整 |
+
+## 交接命令
+
+```bash
+# 本地最后一搏
+python3 ~/.agents/skills/argo/sub-skills/local-seek/scripts/seek.py "关键词" --spotlight
+
+# 联网：unified-search（多引擎，快）
+# 联网：argo 深度研究（学术/金融领域，带信源核验）
+```
+
+## 纪律
+
+- **禁止无限扩大**：每层只试一次，最多一轮换词，两轮无果就交接或停止。
+- **交接前确认需求边界**：用户要的是「我电脑里的文件」就别接出网；
+  要的是「这个事实/最新信息」就该直接联网，不必先搜本地。
+- **本地与联网并行**：需求两可时并行调用，互不阻塞，先到的先答。
+- **不把联网结果当本地文件**：交接后答案来自网络，措辞上要区分来源，
+  需要文件路径的请求不能用网页内容冒充。

package/sub-skills/local-seek/references/rg-recipes.md

@@ -0,0 +1,96 @@
+# rg 分场景配方
+
+统一入口 `seek.py` 已覆盖多数场景，以下配方用于非常规操作或手动微调。
+所有命令均尊重 .gitignore，自动排除 node_modules 等（见 config/domains.yaml）。
+
+## 基础
+
+```bash
+# 全文搜（当前目录）
+rg "关键词"
+
+# 指定目录
+rg "关键词" ~/notes
+
+# 忽略大小写
+rg -i "keyword"
+
+# 正则
+rg "func[0-9]+\(" src/
+
+# 固定字符串（避免正则转义，含特殊字符时用）
+rg -F "a.b[c]" .
+```
+
+## 定位类
+
+```bash
+# 只看文件名（最省 token，先看分布）
+rg -l "关键词" .
+rg --files-with-matches "关键词" .
+
+# 每文件命中数（先数后看）
+rg --count-matches "关键词" .
+
+# 只看行号不输出内容
+rg -l --line-number "关键词" .
+```
+
+## 上下文类
+
+```bash
+# 前后 N 行
+rg -C 2 "关键词" .
+rg -A 3 "关键词" .   # 只后文
+rg -B 1 "关键词" .   # 只前文
+
+# 输出到文件避免刷屏（超大批量时）
+rg "关键词" . > /tmp/rg_out.txt
+```
+
+## 类型过滤
+
+```bash
+# 按扩展名
+rg -g "*.py" "关键词" .
+rg -g "*.{py,ts,js}" "关键词" .
+
+# 排除
+rg -g "!test_*" "关键词" .
+rg -g "!*.min.js" "关键词" .
+```
+
+## 常用语义场景
+
+```bash
+# 函数/类定义在哪
+rg -n "def handle_request|class AuthService" src/
+# 跨语言：rg "function (getUser|setUser)" .
+
+# 跨文件引用（谁在调用某函数）
+rg "send_email\(" .
+
+# TODO/FIXME 盘点
+rg -n "TODO|FIXME|HACK" --type-add 'todo:*.{py,js,ts,go,rs}' -t todo .
+
+# 只搜中文
+rg -n "[\u4e00-\u9fff]" .
+
+# 找 JSON/YAML 里的键
+rg -n '"max_results"' config/
+
+# 日志排查（最近日志）
+rg "ERROR|panic" --glob "*.log" .
+```
+
+## 性能
+
+- 大仓库先 `--count` 或 `-l`，避免输出千行
+- 指定 `-g` 类型或目录，rg 只扫必要范围
+- 超过 30s 无结果：换词或换 mdfind（--spotlight），不要重复等待
+- rg 退出码：0=有匹配，1=无匹配，2=报错。脚本已处理，手动用时注意
+
+## 非代码文件（可选扩展）
+
+rga（ripgrep-all）未安装时可临时用 mdfind 覆盖 PDF/Office 场景；
+若常搜这类文件，装 rga：`brew install ripgrep-all`

package/sub-skills/local-seek/references/strategies.md

@@ -0,0 +1,52 @@
+# 渐进式策略与 token 纪律
+
+本 skill 的核心不是「更快地搜索」，而是「用最少的 token 拿到答案」。
+工具输出就是压缩结果，模型不该有探索成本。
+
+## 三层渐进（永远按此顺序）
+
+```
+L1 定位      seek.py "词" --count / --filename
+             → 输出「文件:命中数」或文件路径列表，每行 < 80 字符
+             ↓ 从中挑出最相关的 1-3 个文件
+L2 上下文    seek.py "词" --context 2 --path <该文件所在目录>
+             → 输出「路径:行号:命中行 ± 2 行」
+             ↓ 确定要精读的段落
+L3 精读      read_file 该文件，用行号偏移局部读取
+```
+
+任何一步已经能回答用户，就停。不要为完整性多搜。
+
+## 搜索范围扩大的顺序（先窄后宽）
+
+1. 当前目录 + 默认排除（最常命中）
+2. `--path` 扩大到知识域（~/notes、~/Documents 等，见 domains.yaml）
+3. `--spotlight` 全盘兜底
+
+禁止跳级：用户问「找代码里某个函数」却直接 mdfind 全盘，浪费且不准。
+
+## 输出量控制
+
+| 手段 | 效果 |
+|------|------|
+| `--max 20` | 截断结果数，防止刷屏 |
+| `--count` | 只报分布，不报内容 |
+| `--type py,ts` | 只扫目标类型 |
+| `--context 0`（默认） | 不输出上下文行 |
+| `-l` 手动模式 | 只列文件名 |
+
+## 常见失败与换词策略
+
+| 现象 | 处理 |
+|------|------|
+| 无匹配 | 换同义词/拆词/去掉修饰词，重试 1 次后换工具 |
+| 命中过多 | 加 `--type` / `--max` / 更具体的关键词（加引号做短语匹配） |
+| 结果太泛 | 指定目录缩小范围 |
+| 搜代码但命中注释/文档 | 换更精确的符号名或结构模式 |
+| Spotlight 搜不到 | 确认目录已索引；退回 rg + 明确 --path |
+
+## 与 Argo 的分工
+
+- 用户要「网上查」→ argo（联网）
+- 用户要「本地找/搜我的文件」→ local-seek
+- 混合需求（如「查网上的同时翻本地笔记」）→ 并行调用，互不干扰

package/sub-skills/local-seek/references/structural-search.md

@@ -0,0 +1,59 @@
+# 结构搜索手册（--structural）
+
+按「语义」而非「字符串」检索代码模式：找裸 except、空 catch、装饰函数这类
+「看着就知道有问题/有特征」的结构。零安装实现：rg -U 多行匹配 + 语言感知
+pattern，本机装 ast-grep 后可升级为 AST 精确匹配（见文末）。
+
+## 用法
+
+```bash
+# 按语义名或中文别名检索，输出同普通搜索（路径:行号:片段）
+python3 ~/.agents/skills/argo/sub-skills/local-seek/scripts/seek.py "裸except" --structural
+python3 ~/.agents/skills/argo/sub-skills/local-seek/scripts/seek.py "empty-catch" --structural --path ~/repo
+python3 ~/.agents/skills/argo/sub-skills/local-seek/scripts/seek.py "函数定义" --structural --path ~/repo --type py
+python3 ~/.agents/skills/argo/sub-skills/local-seek/scripts/seek.py "不存在语义" --structural   # 报可用列表
+```
+
+查询词可写语义名（empty-catch）或任意中文别名（空catch、裸异常），大小写不敏感。
+
+## 内置规则
+
+| 语义名 | 中文别名 | 查什么 | 覆盖语言 |
+|--------|---------|--------|---------|
+| empty-catch | 空catch、空捕获、空异常处理 | `catch (...) {}` 空体 | js/jsx/ts/tsx |
+| bare-except | 裸except、无类型except | `except:` 无异常类型 | py |
+| unwrapped-error | 错误未包装、裸return err | `return err` 直接返回错误 | go |
+| decorated-fn | 装饰函数、装饰器函数 | 带 `@decorator` 的函数定义 | py |
+| function-def | 函数定义、找函数 | 函数定义行 | py/js/ts/go/rs |
+| class-def | 类定义、找类 | 类/结构体定义行 | py/js/ts/go/java |
+
+## 实现说明
+
+- 每条规则 = 若干 (扩展名集合, 正则) 对，逐语言跑 `rg -U -i --line-number`。
+- `-U` 启用多行模式，decorated-fn 才能跨行匹配 `@装饰器\n def`。
+- 语言无命中（rg 退出码 1）静默跳过，不报错。
+- 与正文搜索共用排除规则（domains.yaml + --exclude）。
+- 局限：正则近似，非真实 AST。缩进风格怪异的代码、嵌套场景可能漏报；
+  `catch {}` 内只有注释也算空体（正则按字面空体判断）。
+
+## 扩展新规则
+
+在 seek.py 的 `STRUCTURAL_RULES` 字典追加一条：
+
+```python
+"todo-count": {
+    "aliases": ("待办统计", "todo盘点"),
+    "patterns": [
+        (("py", "js", "ts"), r"TODO|FIXME|HACK"),
+    ],
+},
+```
+
+规则键即语义名，aliases 提供中文入口，patterns 按语言给正则。
+加完跑 `python3 scripts/eval_seek.py` 确认无回归，再补一条结构用例。
+
+## 升级路径（装 ast-grep 后）
+
+ast-grep 能精确匹配 AST 节点（真·空 catch 块、未捕获的裸 except），
+消除正则的漏报误报。届时在 structural_search 里检测 `sg` 命令存在则优先
+AST，缺失时回落当前 rg -U 实现，行为对调用方透明。