给 AI agent 用的网页控制层：纯 Rust、自包含的二进制（Linux / macOS / Windows），零外部进程、零外部浏览器，内置取回/解析/会话/文档能力，提供 CLI 与 MCP server；另有可选的受限内置 JS 引擎（默认关闭，见 ADR-0005）。
项目状态 · 安装 · 快速开始 · 能力与现状 · English · 计划 · 发布流程 · 贡献指南 · 议题
v0.2.2 已发布（Release v0.2.2）：5 个目标、10 个压缩包 / 28 个资产（
webctl与webctl-mcp）+ shell / PowerShell 安装器；Linux 另提供 musl 静态资产。本版新增第 18 个工具web_search（默认 Bing，可选 bing/baidu/360，50–500ms 抖动、去重 + RRF、部分失败语义；LLM 摘要暂缓），见 CHANGELOG 与 ADR-0008。 v0.2.3 已发布（Release v0.2.3，2026-11-10；5 个目标、10 个压缩包 / 28 个资产，含 musl 静态）：搜索降噪 + 诚实降级与凭据接力——去广告（高置信剔除计filtered_ads、低置信is_ad）、exclude排除操作符 + 生效校验、同域折叠 + snippet 截断、结构化fallback_hint、WEBCTL_FALLBACK_TOOL声明 + SKILL 回退决策树、Playwright 兼容storage_state导出（0600/仅目标域/脱敏）；工具面仍 18 个。见 CHANGELOG 与 ROADMAP-0.2.3。
| 项 | 值 |
|---|---|
| 阶段 | P0 已完成：PLAN §5.2 的 PR 03–14 全部合并（真实 merge sha 见 PLAN §5.2.1）；cargo-dist 三平台发布流水线就绪 |
| 迭代 | 0.2.2（全网搜索）已发布（2026-11-10）：第 18 个工具 web_search（Bing/Baidu/360，随机抖动、去重 + RRF、部分失败语义）；M2 摘要暂缓；详见 Release v0.2.2、ROADMAP-0.2.2 与 ADR-0008 |
| 迭代 | 0.2.3（搜索降噪 + 诚实降级与凭据接力）已发布（Release v0.2.3，2026-11-10）：去广告 / exclude 排除操作符 / 同域折叠 + snippet 截断 / 结构化 fallback_hint / WEBCTL_FALLBACK_TOOL + SKILL 决策树 / Playwright 兼容 storage_state 导出；详见 ROADMAP-0.2.3 |
| 发布 | v0.2.3（Release，2026-11-10）：5 目标、10 个压缩包 / 28 个资产（含 musl 静态）+ 安装器；sha256sum -c、--version=0.2.3、caps --json ok、18 工具、release-e2e.sh（gnu/musl）均已实测；体积 gnu 35,215,368 B / musl 34,545,000 B（docs/RELEASE.md、ACCEPTANCE §7） |
| 计划文档 | docs/PLAN.md（v0.4，含 2026-10-16 的方向变更） |
| 事实依据 | docs/SURVEY.md（本机实测 + 公开仓库核对；其中 CDP 部分已成历史记录） |
| 形态 | Rust workspace，5 个 crate（webctl / webctl-core / webctl-web / webctl-mcp / webctl-js）；发布 2 个二进制：webctl（主 CLI，含 mcp 子命令）与 webctl-mcp（独立 MCP server 入口）。三平台；v0.1.1 起 Linux 同时提供 glibc 与 musl 静态两种资产；musl 静态由 CI 在 push main 时验证（#90） |
| 接口 | CLI（caps / fetch / config / cookies / mcp）+ MCP server（mcp__webctl__*，18 个工具） |
| 外部依赖 | 运行时零外部进程、零外部浏览器；不调用 curl/jq/pdftotext 等系统命令；JS 引擎（boa）是进程内库且默认关闭 |
| 发布物 | cargo-dist 生成的三平台压缩包（webctl 与 webctl-mcp 各一；Linux 含 glibc 与 musl 静态两种）+ shell/PowerShell 安装器（清单）；v0.2.3 已发布 |
| 前身 | playwright-crawler-helper（Python + Playwright，不再兼容维护） |
| 许可证 | MIT |
一套能力，全部在进程内实现（计划 §2）。下表如实标注合并进度——未合并的能力不算已支持：
| 能力域 | 内容 | 现状 |
|---|---|---|
| 取回 | HTTP(S)、重定向链、cookie jar、编码/压缩、内容类型路由、并发与限速、robots | ✅ 已合并（PR 02 / 08） |
| 解析 | HTML→DOM、正文提取、链接、表格、表单、JSON/XML、markdown | ✅ 已合并（PR 03） |
| 会话 | cookie 持久化、自动填表提交、CSRF、multipart、分页、登录态导入导出 | ✅ 已合并（PR 04 / 05） |
| 文档/数据 | PDF 文本层、JSON 查询子集、HTML→文本（pdftotext/pandoc/jq 的内置替代） |
✅ 已合并（PR 07） |
| CLI | 配置优先级、代理、输出格式、退出码、caps/fetch/config |
✅ 已合并（PR 10） |
| 抽取 | 选择器 / search / links / tables / forms / paginate 的结构化输出 |
✅ 已合并（PR 06） |
| 降级语义 | SPA/JS 页显式 DEGRADED/UNSUPPORTED，禁止"成功但 0 条" |
✅ 已合并（PR 09） |
| MCP | rmcp server + 18 工具 schema + SKILL.md（与 tools/list 强制一致） |
✅ 已合并（PR 11 建 15 个；#114 增至 16；0.2 M1 增至 17；0.2.2 增至 18） |
| 安全 | cookie 导出确认、信封/日志脱敏、路径与协议校验 | ✅ 已合并（PR 12） |
工具面定稿为 18 个内置工具（PLAN §3.7，embedded_data 于 0.1.2 加入、web_search 于 0.2.2 M1 加入）：
fetch / extract / search / links / tables / forms / fill_form / paginate /
session / cookies / json_query / doc_text / embedded_data / download / robots / resolve_site / caps / web_search。
CLI 子命令：caps / fetch / config / cookies / mcp；18 个工具由 MCP 工具面同时暴露（webctl mcp --list-tools）。
v0.4 取消了外部浏览器与外部 CLI（计划 §0）。下面这些是明确不支持，不是"以后再说"：
- 不执行 JS、不渲染 SPA：JS 注入内容与首屏水合拿不到 → 显式返回
DEGRADED/UNSUPPORTED，绝不伪装成"成功但 0 条"。 - 没有截图、没有真实布局几何：没有渲染器就没有像素，
screenshot、页面 PDF 打印、按坐标点击都不存在。 - 没有 OCR：纯 Rust 无成熟 OCR；扫描件 PDF 只给
UNSUPPORTED。 - 不承诺绕过 Cloudflare/验证码：识别到拦截页即
BLOCKED并给出诊断，只提供 TLS 指纹、合规请求头、限速与退避。
安装命令取自 v0.2.3 的真实资产（见 Release v0.2.3、清单见 docs/RELEASE.md §2）：
# Linux / macOS（安装 webctl；另有 webctl-mcp-installer.sh）
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Thatgfsj/webctl/releases/download/v0.2.3/webctl-installer.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/Thatgfsj/webctl/releases/download/v0.2.3/webctl-installer.ps1 | iex"也可以直接下载平台压缩包（如 webctl-x86_64-unknown-linux-gnu.tar.xz）并用其 .sha256 校验；本地验证方式见 docs/RELEASE.md §4。
git clone https://github.com/Thatgfsj/webctl.git
cd webctl
cargo build --release # 需要 cmake + C/C++ + libclang，见「构建」
./target/release/webctl --version # webctl 0.1.0
./target/release/webctl caps --json # 能力自检：不联网、不探测外部程序
./target/release/webctl fetch https://example.com/cargo build --release # Rust 1.98.1（固定于 rust-toolchain.toml）
cargo test # 全部离线：只连 127.0.0.1，不访问外网
cargo run -- caps --json运行时零外部依赖（单二进制、零外部进程、零外部浏览器；内置 JS 引擎默认关闭）；下面这些只在编译期需要：
| 构建期需求 | 为什么 | 怎么办 |
|---|---|---|
cmake + C/C++ 编译器 |
取回层用 wreq，默认 TLS 后端是 BoringSSL（btls-sys） |
发行版装 cmake + build-essential |
| libclang + clang 内建头 | BoringSSL 绑定由 bindgen 生成 | 装 libclang-dev / clang；最小环境可设 LIBCLANG_PATH 与 BINDGEN_EXTRA_CLANG_ARGS |
缺 libclang 的典型报错是 Unable to find libclang；只给到 .so 而缺头文件时报 'stddef.h' file not found。完整报错、修复命令与本机实测（首次全量构建 76s，2026-10-17 release 全量 1m52s）见 docs/spikes/wreq.md §4。
GitHub Actions 的 ubuntu / macOS / Windows 镜像自带上述依赖，无需额外步骤（main 上三平台 CI 全绿）。
CLI 配置按 CLI 参数 > 环境变量 > 配置文件 > 内置默认 合并。代理只认 WEBCTL_PROXY / 配置文件 proxy；宿主 HTTP_PROXY / HTTPS_PROXY / ALL_PROXY 一律忽略，未配置即直连。JSON 输出恒为单行，错误码 → 退出码为稳定映射。
webctl caps --json
webctl --config ./webctl.toml fetch https://example.com/
webctl --offline caps子命令：caps / fetch / config / cookies / mcp；环境变量清单、配置文件格式与完整退出码表见 docs/CONFIGURATION.md。
- 发布步骤、release note 模板、变更日志约定与发布 E2E 清单：docs/RELEASE.md。
- 体积 / 冷启动基线工具：
scripts/size-baseline.sh；记录：docs/size-baseline.json。- glibc release 本机实测 7,978,256 字节（约 7.61 MiB），
--version冷启动 p50 约 10–24 ms（全部 < 50 ms，CLI-12 本地通过）。 - musl 静态目标：
musl-staticCI 作业在 push main 时用固定版本 Bootlin（PR 阶段已跳过，见 docs/CI.md §8） musl C++ 工具链构建，并以file/ldd/readelf断言无动态依赖；v0.1.1 已产出该资产（22,612,520 字节，ldd报statically linked），并已在真实 Alpine(musl) 用户态跑通（见 ACCEPTANCE §7）。体积基线已回填（#90 已收口）。
- glibc release 本机实测 7,978,256 字节（约 7.61 MiB），
- 发布资产 E2E 冒烟：
scripts/release-e2e.sh（PKG-04 / PKG-06 / PKG-08）。
crates/
├─ webctl/ # bin：CLI 入口 + MCP 入口（feature 切换）
├─ webctl-core/ # envelope / 错误码 / 配置 / 能力自检 / 会话状态 / 安全脱敏
├─ webctl-web/ # 取回 + 解析 + 会话 + 文档与数据（全部内置）
└─ webctl-mcp/ # MCP server + 17 工具 schema + SKILL.md（PR 11 建 15 个，#114 增至 16，0.2 M1 增至 17）
拆分纪律：只有变更来源/节奏不同、且依赖方向单向无环时才拆 crate；其余同一 crate 内用目录分隔。
路线图按 PR 切片，每个 PR 一个 issue（先领 issue 再动手）：
- 全部议题：Thatgfsj/webctl issues
- 里程碑：P0 骨架与基线 → 内置取回与解析 → 会话与状态 → 抽取与文档 → MCP 工具面 → 发布
- 验收锚点（v0.4 重定）：静态版
quotes.toscrape.com/必须稳定取到 10 条；JS 版必须返回DEGRADED而非"成功但 0 条"。
先读 CONTRIBUTING.md：feat 前先写 issue 并领取批准、一个 PR 只做一类变更、单个 PR ≤1000 行（口径与排除项见该文件）。
历史探针脚本在 probes/cdp/：它们记录的是 v0.3 时代"手写 CDP 驱动 Edge"的实测结果，v0.4 已不再走这条路线，保留仅为可复查的历史证据。
webctl is a web-control layer for AI agents — a single pure-Rust binary with everything built in: no external processes, no browser, no JS engine. It provides an HTTP fetch engine, HTML/JSON/XML/PDF extraction, a protocol-level session engine, and a CLI plus an MCP server.
- Status: v0.2.2 released (https://github.com/Thatgfsj/webctl/releases/tag/v0.2.2) for Linux (glibc and musl static), macOS (aarch64 / x86_64) and Windows, with shell/PowerShell installers; see docs/RELEASE.md. The musl asset is produced by the release pipeline and statically asserted (
ldd=statically linked). - Runtime: zero subprocesses, zero browser, zero JS execution. JS-heavy pages degrade explicitly to
DEGRADED/UNSUPPORTEDinstead of silently returning "success with 0 results". - Capabilities shipped (PR 03–14 all merged): fetch (PR 02/08), parsing (PR 03), extraction (PR 06), document/data (PR 07), politeness (PR 08), degradation semantics (PR 09), CLI and config (PR 10), MCP server with 18 tools (PR 11 built 15; #114 added
embedded_data; 0.2 M1 addedresolve_site; 0.2.2 M1 addedweb_search), security hardening (PR 12), packaging (PR 14). The README table above is the source of truth. - Commands available today:
webctl caps,webctl fetch <url>,webctl config,webctl cookies,webctl mcp(the 18-tool surface). - Build:
cargo build --release(requires cmake, a C/C++ toolchain, and libclang at build time only). Rust 1.98.1, pinned inrust-toolchain.toml. - Docs: PLAN · RELEASE · TESTING · SPA baseline · CI · CONTRIBUTING.
- License: MIT.
MIT © 2026 Thatgfsj