SuperAPI AI Directory

ego-search

General & other

View repository

Updated 11-16 11:17

About this skill

ego-search (argo sub-skill)

ego-search is argo'slogin-state professional searchsub-skill (v1.6 full state):

  • Dual runtimes retained:ego lite(ego-browser) and WebBridge (user browser extension bridge)complementary, not mutually substitutable
  • Either one available is enough:search / fetch / act / api is available when at least one runtime is online
  • Isolated from regular retrieval: login-state results cache_eligible=false, forbidden from entering the public SearchCache
  • Aggregation can be fused: output carries merge_with_public_ok=true, the analysis layer can feed both public + login result paths together into evidence

Professional search mode (off by default)

This sub-skill involves a real browserlogin-state inheritance, for security and reliability reasonsoff by default. After enabling, search/fetch/act/api and direct browser operations become available; when not enabled, calls will be rejected and the enable command will be prompted.

# 开启(必须由用户明确要求「开启专业搜索模式」后执行)
python3 sub-skills/ego-search/scripts/ego_search.py enable
# 关闭
python3 sub-skills/ego-search/scripts/ego_search.py disable
# 查看状态
python3 sub-skills/ego-search/scripts/ego_search.py status
  • Discipline: the Agent must not enable it on its own—only run when the user explicitly expresses intent to enable enable。
  • When not enabled, it is likewise forbidden to use heredoc to directly connect to the browser runtime to bypass the gate.
  • State is persisted in ~/.local/state/ego-search/pro-mode.json, and remains in effect long-term after enabling until manually disabled.

Positioning and upgrade decisions

When the main system's API/HTML retrieval coverage is insufficient, upgrade to ego-search:

Scenario Regular retrieval What ego-search supplements
Login-walled content (Zhihu/Xiaohongshu/Weibo/X/WeChat Official Accounts/membership sites) Cannot get the body text Task space inherits login state, searches and scrapes
JS-rendered / SPA / lazy-loaded pages May be an empty shell Extract after the real browser executes JS
Anti-crawling / Cloudflare protection (best effort) HTTP failure Real browser attempt, heavy protection may fail
Dynamic search requiring interaction (pagination / "load more" / form filtering) A single request is not enough act or ego-browser heredoc multi-step
Search engine real-time SERP (Google/Bing/Baidu) May be blocked by anti-crawling Structured extraction of real SERP
Deeply nested iframe pages Often hangs Snapshot specialty
Known same-origin API URL DOM incomplete api + browserFetch
Unknown XHR URL not yet obtained — Not in the CLI; heredoc self-probe or get the URL first then api

Decision order:

常规检索(快、省 token)
  → 结果不足 / 正文拿不到 / 需要登录态
    → ego-search search|fetch|act|api(pro-mode 开启)
      → 更复杂多步 → ego-browser nodejs heredoc
高后果结论 → 证据核验

Dependencies and environment

  • Official project:ego lite → https://lite.ego.app/(official website); WebBridge → https://www.kimi.com/zh-cn/help/kimi-webbridge/kimi-webbridge-introduction(Kimi WebBridge official help center).
  • Browser runtime(macOS app) and Runtime command ego-browser(~/.local/bin)。
  • Confirm before first use:command -v ego-browser. If not installed, complete installation according to references/install.md .
  • Runtime dependencies are self-managed by the installer package; this sub-skill does not duplicate an installation script.
  • Login state comes from runtime onboarding (Chrome data can be imported); login states for different sites are maintained by the user at runtime.

Quick start (ego_search.py CLI)

# 首次使用:先开启专业搜索模式(需用户确认;开启后长期生效)
python3 sub-skills/ego-search/scripts/ego_search.py enable

# 探测运行时与专业模式(--fix 幂等启 WebBridge 桥)
python3 sub-skills/ego-search/scripts/ego_search.py status [--fix]

# 浏览器态搜索(真实 SERP,输出 argo JSON schema)
#   --runtime auto(默认: 有 ego 用 ego,否则 webbridge) | ego | webbridge
python3 sub-skills/ego-search/scripts/ego_search.py search "AI agent 浏览器自动化" --engine bing --n 8

# 强制登录态站点搜索(如知乎/小红书,需登录态)
python3 sub-skills/ego-search/scripts/ego_search.py search "site:zhihu.com AI 搜索" --engine bing

# 浏览器态正文提取(JS 渲染/反爬/登录墙页面)
python3 sub-skills/ego-search/scripts/ego_search.py fetch "https://example.com/article" --focus 关键词

# 同源 API 数据直取(登录态站点接口)
python3 sub-skills/ego-search/scripts/ego_search.py api "https://www.zhihu.com/api/v4/search_v3?t=general&q=AI代理&limit=5" --origin "https://www.zhihu.com"

# 指定任务空间名(同一目标的多轮操作复用同名空间)
python3 sub-skills/ego-search/scripts/ego_search.py search "竞品分析" --task-space "竞品调研"

Output convention:JSON to stdout(machine-readable, can be piped to evidence.py / parsed and fed to RRF), logs to stderr.

Login-state provenance (mandatory)

All search / fetch / act / api outputs include:

Field Value Meaning
login_state_used true Browser login state was used
auth_partition login Auth partition label (cookies are not written)
cache_eligible false ForbiddenWriting to the argo public SearchCache / set_fetch
search_partition login Isolated from the regular public search partition
merge_with_public_ok true AllowedSent together with public results into evidence during aggregate analysis
runtime ego | webbridge Runtime actually used

Public library path ~/.cache/unified-search/cache.db at the set / set_engine / set_fetch entry point will hard-reject such payloads. Login-state results do not cache the body by default.

Isolation from and fusion with regular search

Stage Rule
Retrieval public (argo) and login (this skill) run separately, with separate caches and separate partitions
Cache login never enters the argo public cache; the two paths do not soft-hit each other
Aggregation The Agent may pass both paths' results / body text to evidence or report generation; use source / runtime / search_partition to distinguish weight and trust context

Security and long-term login-state usability

Control Default Description
Professional mode gate Off Requires user enable before running login-state retrieval
URL guard Block fetch/api/navigate http(s) only, localhost/literal private IPs blocked by default;EGO_SEARCH_STRICT_SSRF=1 full DNS;ARGO_ALLOW_PRIVATE_URLS=1 allowed
Task space cleanup Close space ego path defaults to completeTaskSpace keep:false, preventing tab accumulation
--keep-space / --site See right Multi-round keep-alive;--site zhihu.com → site:zhihu.com and keep by default
Login-wall quality signal On fetch/act outputs quality.auth_wall_suspected / login_likely_ok
WebBridge session Does not automatically close_session Avoid accidentally closing user tabs
Public cache Reject writes cache_eligible=false + SearchCache hard guard
Analysis fusion merge Cached in isolation from public results; during aggregation use merge --public --login
Fallback auto Either installation is sufficient; ego is preferred, falling back to WebBridge on failure

Login-state stability recommendations:

  1. Multiple rounds on the same site:--site zhihu.com(or --task-space site:zhihu.com --keep-space)
  2. Single-shot evidence gathering: default is fine (space closes after the run)
  3. quality.login_likely_ok=false → Retry after logging in manually in the ego App or the user's Chrome
  4. Do not write the login state body into the public cache; for aggregation use merge

search mode

Open the real results page of the specified search engine,js() extract a structured SERP, and output:

{
  "query": "AI agent 浏览器自动化",
  "engine": "ego_browser_bing",
  "source": "ego-browser",
  "url": "https://cn.bing.com/search?q=...",
  "results": [
    {"title": "...", "url": "https://...", "snippet": "..."}
  ],
  "count": 8,
  "fetch_method": "browser",
  "login_state_used": true,
  "auth_partition": "login",
  "cache_eligible": false
}
  • --engine:bing(default, most stable) / baidu(Chinese) / google(requires network reachability, may trigger a verification challenge).
  • --n: number of results (default 8).
  • Note: the SERP itself is aretrieval entry point, not body-text evidence—high-consequence conclusions must fetch open the results page and obtain the body text before making a judgment (consistent with argo's discipline that "SERP chains must not be used as a source of body text").

fetch mode

Browser-state body text extraction. Prefer article/main/[role=main] and other semantic containers, fall back to document.body.innerText, output { url, title, content, word_count, fetch_method: "browser" }, and the body text can be piped to argo for quality-signal analysis.

  • --focus 关键词: if passed, return only paragraphs containing or near that keyword (reduces tokens).

api mode

Browser contextsame-origin API data direct fetch(v1.1.0). First open the target site page (inheriting the login state), then use browserFetch to request the same-origin endpoint from that page context, and get back structured JSON/text. Covers scenarios that DOM extraction cannot:

  • SPA/XHR lazy-load truncation: the page renders only the first few screens, while the full data is in the API → fetch the API directly to get everything.
  • Logged-in private data: personal/search endpoints of a logged-in site → page cookies are carried with the request.
  • In-site API search: call the site's search API directly (e.g., Zhihu search_v3), which is cleaner than parsing the SERP.
{
  "api_url": "https://www.zhihu.com/api/v4/search_v3?t=general&q=...",
  "page_url": "https://www.zhihu.com/",
  "page_title": "(1 条消息) 首页 - 知乎",
  "data": { "paging": {...}, "data": [...] },
  "data_type": "json",
  "fetch_method": "browser_api"
}
  • --origin: the URL of the page in the logged-in context.By default, takes the same origin as the API URL(scheme://host); for cross-subdomain scenarios (e.g., cn.bing.com requesting www.bing.com) it must be specified explicitly, otherwise browserFetch fails due to the same-origin constraint.
  • data_type:json / text / error(cross-origin, network errors, etc. are normalized to error, and the script does not crash).
  • Large response truncation:data when it exceeds 100KB is truncated and marked with truncated: true、data_type plus a _truncated suffix.
  • Positioning: api mode output is "raw data", for the Agent to analyze and judge,not SERP evidence, and high-consequence conclusions still require argo_evidence verification.

act mode

Runs common chained actions such as "search → open results → grab body text" in one go. Supports --engine bing|baidu|google(same table as search, default bing). Output includes query / results / detail and login-state provenance. For more complex multi-step interactions (login, forms, pagination, comparing multiple pages) use ego-browser nodejs heredoc; ego_search.py , which covers only high-frequency deterministic paths.

Working with the argo main system

  1. Evidence pipeline: ego-search output is aligned with the argo schema,results can be fed directly to python3 scripts/evidence.py "查询词" --stdin --json for Selection×Absorption scoring; body text can be reused with content_signals / content_security checks.
  2. RRF fusion:source=ego-browser / engine=ego_browser_<engine> can participate in multi-source deduplication; the envelope will mark that login_state_used=true。must notwrite the results of this path into the public SearchCache.
  3. Layered query discipline: Factual questions maintain argo's 2–3 subquery discipline (source requirements / comparison / subject), ego-search is used for the "logged-in state/dynamic content" path among them, and does not replace the argo engine's full recall.
  4. Anti-pollution: The content safety engine operates as usual;cache isolationrelies on cache_eligible=false + SearchCache hard guard.
  5. Cache strategy: By default, logged-in state bodies are not cached; if short caching is done in the future, it must use an independent store ~/.cache/ego-search/, with keys containing auth_partition, and soft-hit public combos are prohibited.

Read on demand

Complex interactions, heredoc full helper quick reference, task space ownership discipline → references/browser-runtime.md; installation details → references/install.md; upgrade to the original runtime → references/original-ego-upgrade.md。

Reference

  • Browser runtime details:references/install.md(dependency installation)