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/apiis 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 toreferences/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:
- Multiple rounds on the same site:
--site zhihu.com(or--task-space site:zhihu.com --keep-space) - Single-shot evidence gathering: default is fine (space closes after the run)
quality.login_likely_ok=false→ Retry after logging in manually in the ego App or the user's Chrome- 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
fetchopen 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.comrequestingwww.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:
datawhen it exceeds 100KB is truncated and marked withtruncated: true、data_typeplus a_truncatedsuffix. - Positioning: api mode output is "raw data", for the Agent to analyze and judge,not SERP evidence,
and high-consequence conclusions still require
argo_evidenceverification.
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
- Evidence pipeline: ego-search output is aligned with the argo schema,
resultscan be fed directly topython3 scripts/evidence.py "查询词" --stdin --jsonfor Selection×Absorption scoring; body text can be reused withcontent_signals/content_securitychecks. - RRF fusion:
source=ego-browser/engine=ego_browser_<engine>can participate in multi-source deduplication; the envelope will mark thatlogin_state_used=true。must notwrite the results of this path into the public SearchCache. - 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.
- Anti-pollution: The content safety engine operates as usual;cache isolationrelies on
cache_eligible=false+ SearchCache hard guard. - 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 containingauth_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)