webctl
给 AI agent 用的网页控制层：纯 Rust、自包含的二进制（Linux / macOS / Windows），零外部进程、零外部浏览器，内置取回/解析/会话/文档能力，提供 CLI 与 MCP server；另有可选的受限内置 JS 引擎（默认关闭，见 ADR-0005）。
项目状态 · 安装 · 快速开始 · 能力与现状 · English · 计划 · 发布流程 · 贡献指南 · 议题
v0.2.0 已发布（Release v0.2.0）：5 个目标、10 个压缩包 / 28 个资产（
webctl与webctl-mcp）+ shell / PowerShell 安装器；Linux 另提供 musl 静态资产。本版新增第 17 个工具resolve_site（L1–L5 通道）与浏览器上下文注入，见 CHANGELOG。
项目状态
能力与现状
一套能力，全部在进程内实现（计划 §2）。下表如实标注合并进度——未合并的能力不算已支持：
工具面定稿为 17 个内置工具（PLAN §3.7，embedded_data 于 0.1.2 加入）：
fetch / extract / search / links / tables / forms / fill_form / paginate /
session / cookies / json_query / doc_text / embedded_data / download / robots / resolve_site / caps。
CLI 子命令：caps / fetch / config / cookies / mcp；17 个工具由 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.0 的真实资产（见 Release v0.2.0、清单见 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.0/webctl-installer.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy Bypass -c "irm https://github.com/Thatgfsj/webctl/releases/download/v0.2.0/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 引擎默认关闭）；下面这些只在编译期需要：
缺 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 配置按 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 已不再走这条路线，保留仅为可复查的历史证据。
English
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.0 released (https://github.com/Thatgfsj/webctl/releases/tag/v0.2.0) 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 17 tools (PR 11 built 15; #114 added
embedded_data; 0.2 M1 addedresolve_site), 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 17-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
