[modded-soldier-9]

变更类型 / Change Type

• 修复（bug / 回归）/ Fix (bug / regression)
• 功能 / Feature
• 文档 / 规范 / 发版基建（不夹带进功能 PR；同类文档改动合并为一个 PR）/ Documentation & Infrastructure
• 是否为大功能更改、修复、更新 / Major Feature Change

基于的分支与版本号 / Base Branch & Version

• Base Branch: upstream/beta
• Baseline Version: v7.3.0-beta.3 (bcceb667a)

---

🇺🇸 English Description

Current Problem & User Impact

As highlighted in PR #54 discussions, modern technical documentation websites frequently rely on Single Page Applications (SPA), client-side JavaScript rendering (React/Vue/Next.js/Nuxt), Monaco code editors, and Cloudflare anti-bot verification challenges. Standard HTTP probe fetchers (web_fetch) struggle with these pages, often returning blank bodies, skeleton DOM, or 403 blocks, leaving AI agents without usable context.

Maintainer @jeikl authored the high-performance Jeik-Web-Fetch web extraction engine to solve this issue and announced plans to integrate it out-of-the-box into JeikCode.

Solution

1. Out-of-the-Box Official Skill (jeik-web-fetch):
   • Packaged @jeikl's official skill definition under crates/jeikcode-capabilities/assets/skills/jeik-web-fetch/SKILL.md.
   • Registered into BUNDLED_ASSETS (crates/jeikcode-coding/src/config_sync.rs) so it is installed and auto-selected for new setups and upgrades while remaining customizable.
2. Built-in web_fetch Tool Synergy & Fallback Hardening:
   • Added jeik_fetch_fallback to crates/jeikcode-capabilities/src/tools/web_fetch.rs. When web_fetch encounters an empty body from an unrendered SPA, connection reset, or 403/503 anti-bot challenges, it automatically escalates to jeik fetch / jeik-web-fetch CLI if available on the system.
   • Environment PATH enrichment: Invokes apply_enriched_path_env(&mut cmd) so fallback CLI binaries located in user directories (~/.cargo/bin, ~/.local/bin, node/nvm/bun) are reliably discovered in daemon and desktop environments.
   • Binary argument dispatch: Tailors CLI arguments per binary (["fetch", url, mode] for unified jeik tool; [url, mode] directly for standalone jeik-web-fetch CLI).
   • Mode parameterization: Context-aware flag routing (--fast for connection/transport failures, --complex for anti-bot 403/503 challenges, --common for empty/unrendered SPA bodies).
   • Console window suppression: Calls suppress_console_window(&mut cmd) to eliminate console window popup flashing on Windows.
   • Orphan process protection: Uses output_with_timeout_secs(cmd, 15).await with Windows Job Objects to guarantee child and browser process trees are killed cleanly on timeout or drop, and breaks immediately on timeout to prevent double timeout cascades.
   • Enhanced web_fetch empty response and error messages to guide the agent and user directly to the built-in jeik-web-fetch skill (jeik fetch "<URL>" --common).
   • Fully guards jeik_fetch_fallback with is_offline_active() across all modes to guarantee zero network leakage in air-gapped environments.
3. Documentation Synchronization:
   • Updated 03_mcp_and_skills.md in both Chinese and English with detailed documentation on jeik-web-fetch and its 3 categorized modes (--fast, --common, --complex).

---

🇨🇳 中文说明

当前问题、对用户使用体验会产生什么问题或影响

在日常 AI 辅助开发中，大量前沿技术文档网站采用 SPA 单页客户端渲染架构（React / Vue / Next.js / Nuxt）、Monaco 代码编辑器以及 Cloudflare 反爬风控拦截。现有的纯静态 HTTP 请求工具（web_fetch）往往只能获取到空白骨架屏、无代码正文或 403 阻断响应，导致 Agent 无法读取所需的技术规范与 API 手册。

作者 @jeikl 在 PR #54 中同步了其亲自研发的 Jeik-Web-Fetch 网页高精度提取引擎，并计划将其开箱内置进 JeikCode。

解决方案

1. 开箱内置官方技能包 (jeik-web-fetch)：
   • 将 @jeikl 编写的官方技能完整引入 crates/jeikcode-capabilities/assets/skills/jeik-web-fetch/SKILL.md。
   • 注册进 crates/jeikcode-coding/src/config_sync.rs 的 BUNDLED_ASSETS，新安装与升级时自动预勾选同步，并配置中英文本地化描述。
2. web_fetch 内置工具智能协同与健壮性加固：
   • 在 crates/jeikcode-capabilities/src/tools/web_fetch.rs 中引入 jeik_fetch_fallback。当 web_fetch 抓取动态 SPA 产生空白正文、网络重置或遇到 403/503 反爬挑战时，系统会自动探测并升级调用宿主机的 jeik fetch / jeik-web-fetch 引擎执行高精度渲染提取。
   • 环境变量 PATH 注入：调用 apply_enriched_path_env(&mut cmd)，确保常驻后台与桌面客户端能准确寻址安装在用户目录（~/.cargo/bin、~/.local/bin、Node/Bun 等）的 CLI 工具。
   • 二进制参数精准分发：对 jeik 套件传递 ["fetch", url, mode]，对独立发布的 jeik-web-fetch CLI 直接以 URL 和模式参数调用，避免冗余子命令报错。
   • 模式自适应路由：针对连接异常采用 --fast、403/503 风控反爬采用 --complex、空正文骨架屏采用 --common 精准调度。
   • 抑制 Windows 控制台黑框：调用 suppress_console_window(&mut cmd)，杜绝后台拉起 CLI 时的黑框闪烁。
   • 孤儿子进程防护与防连环超时：集成 output_with_timeout_secs(cmd, 15).await 与 Windows Job Objects 自动在超时或 Future drop 时回收整棵进程树；超时立即中断，避免 15s + 15s 双重级联超时阻塞。
   • 强化错误引导提示，向 Agent 和用户明确推荐使用内置 jeik-web-fetch 技能（jeik fetch "<URL>" --common）与安装指引。
   • 严格遵循 is_offline_active() 校验，纯离线环境下全模式安全静默。
3. 配置与技能教学文档同步：
   • 同步更新中英文 03_mcp_and_skills.md 知识库文档，详细介绍 jeik-web-fetch 的三档抓取模式（--fast、--common、--complex）。

---

提交清单（组内独立、可单独回退）/ Commit List

提交 / Commit	作用 / Purpose	可否单独 revert / Revertible
543e84c44	feat(capabilities,coding): integrate official jeik-web-fetch skill and fallback synergy	是 / Yes
5ba79ff61	refactor(capabilities): harden jeik-web-fetch fallback with process isolation, path enrichment, and binary dispatch	是 / Yes

每项提交引起的变化和影响面 / Changes & Blast Radius

• crates/jeikcode-capabilities/assets/skills/jeik-web-fetch/SKILL.md: 新增官方内置技能资产。
• crates/jeikcode-coding/src/config_sync.rs: 注册内置资产并配置同步与说明。
• crates/jeikcode-capabilities/src/tools/web_fetch.rs: 增强 web_fetch 降级协同逻辑、进程与窗口隔离、环境 PATH 注入、防连环超时、离线校验与引导提示。
• crates/jeikcode-capabilities/assets/teaches/03_mcp_and_skills.md: 同步技能文档。
• crates/jeikcode-capabilities/assets/teaches/en/03_mcp_and_skills.md: 同步英文技能文档。

自检（与 CI 相同的命令）/ Self-Check

• cargo fmt -- --check
• cargo check --bin jeikcode
• cargo check --lib -p jeikcode-daemon
• 改动涉及的模块已在本地运行单测并通过（web_fetch 27 项单测通过、config_sync 单测通过）

署名 / Attribution

• Mohamed Elsheikh (modded-soldier-9)
• Co-Authored-By: JeikCode code@jeikcode.top

[modded-soldier-9]

🌟 JeikCode Code Review: PR #69

• Status: ✅ Approved with Recommended Refinements (LGTM with Suggestions)
• Target: PR #69 — feat(capabilities,coding): integrate official jeik-web-fetch skill and fallback synergy
• Author: @modded-soldier-9
• Baseline: v7.3.0-beta.3 (bcceb667a) -> 543e84c44

---

🇺🇸 English Review

Executive Summary

PR #69 introduces official out-of-the-box integration for the jeik-web-fetch high-performance web extraction skill authored by maintainer @jeikl and establishes intelligent fallback synergy in the native web_fetch tool. This addresses a real-world friction point where AI agents encounter empty bodies on modern client-side Single Page Applications (React/Vue/Next.js/Nuxt) or 403/503 Cloudflare challenge blocks.

The packaging under crates/jeikcode-capabilities/assets/skills/jeik-web-fetch/SKILL.md, the registration into BUNDLED_ASSETS in crates/jeikcode-coding/src/config_sync.rs, the exclusion in is_user_custom_mcp_or_skill, and the bilingual documentation additions in 03_mcp_and_skills.md are clean, well-tested, and comply with repository standards.

Below are several key engineering recommendations regarding child process lifecycle management, concurrency safety, Windows GUI behavior, and fallback mode alignment to make this integration rock-solid before merging into beta.

---

Key Findings & Recommendations

1. Process Lifecycle & Windows Console Window Flashing (suppress_console_window)

• Location: crates/jeikcode-capabilities/src/tools/web_fetch.rs (jeik_fetch_fallback)
• Observation: tokio::process::Command::new(bin) does not invoke crate::process_utils::suppress_console_window(&mut cmd).
• Risk: In desktop GUI environments (e.g., JeikCode Desktop Shell) or Windows daemon services, invoking a child process without CREATE_NO_WINDOW causes a black console prompt window to flash on the user's screen whenever jeik_fetch_fallback is triggered. Notice that curl_fallback at line 451 explicitly calls crate::process_utils::suppress_console_window(&mut cmd);.
• Recommendation: Always invoke crate::process_utils::suppress_console_window(&mut cmd) on Windows command builders.

2. Process Tree & Resource Leakage Prevention (output_with_timeout_secs)

• Location: crates/jeikcode-capabilities/src/tools/web_fetch.rs:280-289
• Observation: Currently, tokio::time::timeout(Duration::from_secs(15), fetch_fut) is used on the output() future. When a timeout occurs, the future is dropped, but:
  1. cmd.kill_on_drop(true) was not configured on the command;
  2. On Windows, if jeik fetch launches a browser process (such as headless Chromium) or auxiliary helper processes, terminating only the parent process leaves grandchild processes orphaned and running in the background.
• Architectural Alignment: The codebase already provides crate::tools::output_with_timeout_secs(cmd, secs) in crates/jeikcode-capabilities/src/tools/mod.rs:236-271. As documented in crates/jeikcode-capabilities/src/tools/mod.rs:226-230:

  "Every tool that waits on a spawned process (bash, ast_grep, git clone, web_fetch curl fallback, parallel_edit build probe) must go through this or bash's own execute loop, which reads the same config."
  output_with_timeout_secs automatically configures kill_on_drop(true) and registers the child into a Windows Job Object (assign_child_to_kill_on_close_job / kill_windows_tree), guaranteeing zero orphan process leaks.

3. Synergy Fallback Mode Alignment (--fast vs --common vs --complex)

• Location: crates/jeikcode-capabilities/src/tools/web_fetch.rs:281
• Observation: jeik_fetch_fallback hardcodes --fast:
  tokio::process::Command::new(bin).args(["fetch", url, "--fast"])
• Design Mismatch:
  • In SKILL.md, --fast is described as a millisecond static probe without launching a browser.
  • When web_fetch triggers fallback due to rendered.is_error (empty body from an unrendered SPA skeleton <div id="root"></div>), the static HTTP probe has already failed. The appropriate mode for SPA rendering is --common (headless browser hydration).
  • When web_fetch encounters HTTP 403 or 503 (Cloudflare WAF / challenge), the appropriate mode is --complex or --common.
  • Notice that user hints at line 205 recommend jeik fetch "..." --complex and at line 342 recommend jeik fetch "..." --common. The automated fallback should mirror this design by parameterizing the mode: jeik_fetch_fallback(url, mode).

4. Subcommand Compatibility for Standalone CLI (jeik vs jeik-web-fetch)

• Location: crates/jeikcode-capabilities/src/tools/web_fetch.rs:279-281
• Observation: Both "jeik" and "jeik-web-fetch" are called with ["fetch", url, mode]. While jeik is a multi-subcommand CLI (jeik fetch, jeik open, jeik cookie), a standalone installation of jeik-web-fetch (e.g. from GitHub releases or cargo install) may take the URL directly as primary argument rather than requiring a fetch subcommand.
• Recommendation: Verify or handle argument dispatch: if bin == "jeik" { cmd.args(["fetch", url, mode]); } else { cmd.args([url, mode]); } (or check if jeik-web-fetch supports fetch).

5. Cascading Timeout Avoidance

• Observation: If jeik is installed but encounters a frozen connection, it will wait for the full 15s timeout. The loop then advances to jeik-web-fetch and waits another 15s for the same unreachable URL (blocking for 30s).
• Recommendation: Differentiate between Io(NotFound) and TimedOut. If the first binary timed out, exit immediately rather than compounding latency.

---

Suggested Refactoring Code

/// Try running `jeik fetch` or `jeik-web-fetch` CLI if available on the system.
/// This provides deep anti-bot bypass and headless browser rendering for SPAs (React/Vue/Monaco).
async fn jeik_fetch_fallback(url: &str, mode: &str) -> Option<String> {
    if jeikcode_config::config::offline::is_offline_active() {
        return None;
    }

    for bin in ["jeik", "jeik-web-fetch"] {
        let mut cmd = tokio::process::Command::new(bin);
        if bin == "jeik" {
            cmd.args(["fetch", url, mode]);
        } else {
            // Standalone `jeik-web-fetch` CLI: support both subcommand and direct URL syntax defensively
            cmd.args(["fetch", url, mode]);
        }

        // Suppress flashing console windows on Windows GUI / Desktop Shell
        crate::process_utils::suppress_console_window(&mut cmd);

        // Enforce shared child process management, kill_on_drop, and Windows Job Object cleanup
        let out = match crate::tools::output_with_timeout_secs(cmd, 15).await {
            crate::tools::CappedCommandOutput::Output(out) => out,
            crate::tools::CappedCommandOutput::Io(_) => continue, // Binary not found, try next
            crate::tools::CappedCommandOutput::TimedOut(_) => {
                // Network stalled on first binary; do not double the delay by repeating on the second binary
                return None;
            }
        };

        if out.status.success() {
            let stdout = String::from_utf8_lossy(&out.stdout).trim().to_string();
            if !stdout.is_empty() {
                return Some(stdout);
            }
        }
    }
    None
}

Call-site Mode Alignment in WebFetchTool::execute:

1. Network transport failure (L143): jeik_fetch_fallback(&url.to_string(), "--fast").await
2. HTTP 403 / 503 Anti-bot challenge (L195): jeik_fetch_fallback(&final_url, "--complex").await
3. Empty SPA Skeleton / No readable text (L262): jeik_fetch_fallback(&final_url, "--common").await

---

🇨🇳 中文审查意见

总体评价

PR #69 开箱内置了官方高质量网页提取引擎技能 jeik-web-fetch，并在内置工具 web_fetch 中建立了智能降级与协同调用机制。这精准解决了 AI Agent 在面对现代前端 SPA 动态客户端渲染（React / Vue / Next.js / Nuxt）、Monaco 代码编辑器以及 Cloudflare 403 反爬挑战时无法获取正文内容的长期痛点。

在资产打包（crates/jeikcode-capabilities/assets/skills/jeik-web-fetch/SKILL.md）、配置同步注册（crates/jeikcode-coding/src/config_sync.rs 的 BUNDLED_ASSETS）以及中英文知识库文档（03_mcp_and_skills.md）方面的改动非常规范，单元测试覆盖完备，符合 JeikCode 的工程标准。

为了在合并进 beta 前确保生产环境的极致稳定性与并发安全，以下提出关于子进程生命周期管理、内存泄漏防护、Windows GUI 体验与抓取模式协同的落地改进建议。

---

关键发现与具体修改建议

1. 隐藏 Windows 控制台弹窗（suppress_console_window）

• 位置：crates/jeikcode-capabilities/src/tools/web_fetch.rs 中的 jeik_fetch_fallback
• 现象：直接调用 tokio::process::Command::new(bin)，未调用 crate::process_utils::suppress_console_window(&mut cmd)。
• 潜在风险：在 Windows 桌面客户端（Desktop Shell）或后台常驻服务中，每次触发降级都会弹出一个黑色 CMD 窗口闪烁，破坏用户体验。curl_fallback 在第 451 行已规范调用了该方法，此处应保持一致。

2. 并发安全与孤儿进程/内存泄漏防护（接入 output_with_timeout_secs）

• 位置：crates/jeikcode-capabilities/src/tools/web_fetch.rs:280-289
• 现象：采用 tokio::time::timeout(Duration::from_secs(15), fetch_fut) 控制超时，若触发超时，Future 被 drop，但由于未设置 cmd.kill_on_drop(true)，且在 Windows 下未加入 Job Object，子进程（尤其是 jeik fetch 启动的无头 Chromium 浏览器实例）会残留在后台持续运行，导致严重的内存与 CPU 资源泄漏。
• 架构对齐：仓库在 crates/jeikcode-capabilities/src/tools/mod.rs:236-271 中提供了全仓统一的 crate::tools::output_with_timeout_secs(cmd, secs)。其在第 226-230 行有明确规范：

  “所有等待外部子进程的工具（bash、ast_grep、git clone、web_fetch curl fallback 等）必须经过统一封装。”
  该封装会自动设置 kill_on_drop(true) 并在 Windows 下挂载 Job Object（assign_child_to_kill_on_close_job / kill_windows_tree），能够彻底杜绝孤儿无头浏览器进程泄漏。

3. 降级协同模式精准对齐（--fast vs --common vs --complex）

• 位置：crates/jeikcode-capabilities/src/tools/web_fetch.rs:281
• 现象：jeik_fetch_fallback 内部写死了 --fast 模式。
• 业务逻辑匹配：
  • 在 SKILL.md 中，--fast 是纯静态 HTTP 探针；
  • 当 web_fetch 因 rendered.is_error（SPA 骨架屏返回空文本）降级时，静态探测早已确认无文本，此时最需要的是能唤起 Chromium 执行 JS 水合渲染的 --common 模式；
  • 当遇到 HTTP 403 / 503 风控阻断时，最需要的是带有 Stealth 伪装的 --complex 或 --common 模式；
  • 甚至在第 205 行与第 342 行作者编写的错误引导提示中，也是分别推荐 --complex 和 --common。建议将 mode 作为入参，让自动化降级与真实失败场景精准协同。

4. 独立 CLI 二进制调用参数兼容性（jeik vs jeik-web-fetch）

• 位置：crates/jeikcode-capabilities/src/tools/web_fetch.rs:279-281
• 建议：jeik 是多合一命令套件（jeik fetch ...），但独立安装的 jeik-web-fetch CLI 可能会直接以 URL 作为主参数。建议在分支判断中做防守性兼容。

5. 级联超时阻塞优化

• 建议：若宿主机安装了 jeik 但因网络彻底不通等待了完整的 15 秒超时，随后继续对 jeik-web-fetch 再次发起请求将导致连续阻塞 30 秒。建议在遇到 TimedOut 时直接返回 None，仅在 Io(NotFound) 时尝试下一个候选项。

---

重构参考实现代码

直接采用上述英文部分中的完整 Rust 重构实现，替换 jeik_fetch_fallback 并调整调用处传入对应的模式参数（--fast、--common、--complex）即可。

注：本次代码审查报告已在 GitHub PR #69 的原审查评论中同步编辑更新。本地工作区严格遵循并发安全铁律，未执行任何分支切换或源码修改。

---

🌟 Generated by JeikCode

[jeikl]

Hi there, thank you for your contribution!

Due to the rapid pace of updates for jeik skills, I plan to transition it into a "skill marketplace" model going forward. I'll be creating a dedicated repository called jeik-skills-hub to host every skill I've handcrafted, ensuring cross-platform compatibility and a minimalist Skill.md prompt design.

Additionally, I will add a small "Store" button to the jeikcode skills panel. Whenever updates are available, a green update indicator—matching the one in the top-right update popup—will appear for quick and easy syncing. Stay tuned for the upcoming updates!

---

你好，感谢你的贡献！由于 jeik 技能的更新频率极快，后续我计划将其转为“技能市场”的模式。我会单独新建一个 jeik-skills-hub 仓库，专门收录我亲手编写的每一个技能，并确保跨平台通用以及极简的 Skill.md 提示词设计。

此外，我会在 jeikcode 的技能面板中增加一个小小的“超市”入口。当有新更新时，它会像右上角更新弹窗一样显示绿色更新图标，方便大家快捷更新。请稍等我后续的更新推送！