argo-search 2.9.7 → 2.9.8

package/sub-skills/js-run/tests/test_jsrun.py

@@ -1,165 +0,0 @@
-#!/usr/bin/env python3
-"""jsrun 最小核测试（金标考卷驱动）。
-
-直接运行：python3 tests/test_jsrun.py（也可 pytest 收集）。
-依赖：mini-racer（pip install mini-racer）。
-"""
-from __future__ import annotations
-
-import importlib.util
-import sys
-import time
-from pathlib import Path
-
-import pytest
-
-# mini-racer 是 js-run 的可选依赖（V8 沙箱）。没装的机器上这 10 条用例会
-# 全部 RuntimeError，把主套件染红——而缺依赖本应是 skip，不是失败
-# （2026-10-18 实测：主套件 4236 passed / 4 failed，其中 1 条就是这里）。
-# 用模块级 pytestmark 而不是 importorskip：后者会让收集数为 0，旧版 pytest
-# 返回 rc=5（no tests collected），外层 sub-skills 套件门照样红。
-pytestmark = pytest.mark.skipif(
-    importlib.util.find_spec("py_mini_racer") is None,
-    reason="js-run 可选依赖 mini-racer 未安装",
-)
-
-HERE = Path(__file__).parent
-sys.path.insert(0, str(HERE.parent / "scripts"))
-
-from jsrun import JsRun  # noqa: E402
-
-CHALLENGE = (HERE / "fixtures" / "challenge_like.js").read_text(encoding="utf-8")
-
-
-def test_env_probe():
-    with JsRun() as jr:
-        out = jr.run("({ua: navigator.userAgent, p: navigator.platform, wd: navigator.webdriver})")
-        assert out["ua"].startswith("Mozilla/5.0"), out
-        assert out["p"] == "Win32"
-        assert out["wd"] is False
-
-
-def test_challenge_token_and_cookie():
-    with JsRun() as jr:
-        out = jr.run(CHALLENGE)
-        assert out["token"], out
-        assert out["issued"] is False, "advance 前定时器不该触发"
-        jr.advance(3000)
-        assert jr.run("issued_global_check()") if False else True
-        cookie = jr.get_cookie()
-        assert cookie.startswith("__jsl_clearance="), cookie
-        assert out["token"] in cookie
-
-
-def test_initial_state_extraction():
-    # 数据埋在 JS 里的提取场景：window.__INITIAL_STATE__ 直取
-    with JsRun() as jr:
-        jr.run("window.__INITIAL_STATE__ = {list: [1,2,3], meta: {title: 'js 数据'}}")
-        out = jr.run("window.__INITIAL_STATE__")
-        assert out == {"list": [1, 2, 3], "meta": {"title": "js 数据"}}
-
-
-def test_logical_timer_instant():
-    with JsRun() as jr:
-        jr.run("var x = 0; setTimeout(function(){ x = 42; }, 5000);")
-        assert jr.run("x") == 0
-        fired = jr.advance(5000)
-        assert fired == 1
-        assert jr.run("x") == 42
-
-
-def test_entropy_differs_across_contexts():
-    with JsRun() as a, JsRun() as b:
-        va = a.run("Array.from(crypto.getRandomValues(new Uint8Array(8)))")
-        vb = b.run("Array.from(crypto.getRandomValues(new Uint8Array(8)))")
-        assert va != vb, "不同上下文的熵应不同"
-        assert len(va) == 8 and all(isinstance(x, int) and 0 <= x <= 255 for x in va)
-
-
-def test_environment_override():
-    with JsRun(environment={"navigator": {"userAgent": "TestUA/1.0"}}) as jr:
-        assert jr.run("navigator.userAgent") == "TestUA/1.0"
-        assert jr.run("navigator.platform") == "Win32"  # 未覆盖字段保持默认
-
-
-def test_speed_budget():
-    # 量化门：上下文创建 + 环境垫片 + 一次求值 < 100ms（iv8 实测 18ms 为基线）
-    t0 = time.perf_counter()
-    with JsRun() as jr:
-        jr.run("navigator.userAgent")
-    dt_ms = (time.perf_counter() - t0) * 1000
-    assert dt_ms < 100, f"冷启动 {dt_ms:.1f}ms 超预算"
-
-
-def test_atob_rejects_invalid_chars():
-    # 非法 base64 字符应报错，不静默映射
-    with JsRun() as jr:
-        try:
-            jr.run('atob("!!invalid!!")')
-            assert False, "应抛异常"
-        except (RuntimeError, Exception):
-            pass  # 预期行为
-        # 合法 base64 正常
-        out = jr.run('atob("aGVsbG8=")')
-        assert out == "hello", out
-
-
-def test_run_timeout():
-    # 死循环脚本应超时
-    with JsRun() as jr:
-        try:
-            jr.run('while(true){}', timeout_ms=500)
-            assert False, "应超时"
-        except TimeoutError:
-            pass  # 预期行为
-
-
-def test_close_releases():
-    # close 后上下文应不可用
-    jr = JsRun()
-    jr.close()
-    try:
-        jr.run('1+1')
-        assert False, "close 后应不可用"
-    except (AttributeError, RuntimeError, Exception):
-        pass  # 预期行为
-
-
-def test_run_in_worker_thread():
-    # 回归：此前用 signal.SIGALRM，在工作线程（crawl/research/mcp_server）
-    # 必抛 ValueError: signal only works in main thread
-    import threading
-
-    out_box: dict = {}
-
-    def _worker():
-        try:
-            with JsRun() as jr:
-                out_box["val"] = jr.run("navigator.platform + ':' + (20 + 22)")
-                try:
-                    jr.run("while(true){}", timeout_ms=200)
-                    out_box["timeout_ok"] = False
-                except TimeoutError:
-                    out_box["timeout_ok"] = True
-        except BaseException as e:
-            out_box["err"] = e
-
-    t = threading.Thread(target=_worker)
-    t.start()
-    t.join(timeout=5)
-    assert "err" not in out_box, f"工作线程执行失败: {out_box.get('err')!r}"
-    assert out_box.get("val") == "Win32:42"
-    assert out_box.get("timeout_ok") is True
-
-
-if __name__ == "__main__":
-    fails = 0
-    for name, fn in sorted(globals().items()):
-        if name.startswith("test_") and callable(fn):
-            try:
-                fn()
-                print(f"PASS {name}")
-            except AssertionError as e:
-                fails += 1
-                print(f"FAIL {name}: {e}")
-    sys.exit(1 if fails else 0)

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

@@ -1,24 +0,0 @@
-# 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

@@ -1,62 +0,0 @@
-# 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

@@ -1,54 +0,0 @@
-# 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

@@ -1,46 +0,0 @@
-# 本地搜不到时的交接（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

@@ -1,96 +0,0 @@
-# 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

@@ -1,52 +0,0 @@
-# 渐进式策略与 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

@@ -1,59 +0,0 @@
-# 结构搜索手册（--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 实现，行为对调用方透明。