hardly

hardly

一个通用、内容中立的 CLI 和 MCP 服务，用于读取和捕获 HAR 文件，并将其转换为客户端 SDK 所需的信息：端点、表单和标签、数据与媒体类型，以及凭据和身份验证的工作方式。

为什么选择 hardly

浏览器 HAR 捕获文件通常有数十 MB。读取这些文件的 Agent 会消耗大量令牌，却仍会遗漏结构信息。hardly 会将 HAR 流式导入 SQLite 一次，然后通过 MCP（以及配套 CLI）提供小巧、已脱敏、可分页的工具。响应正文会截断，机密会脱敏，列表会分页：你几乎不必读取整个文件。

hardly 了解各种技术（HTML 表单、ASP.NET WebForms、GraphQL、OAuth/OIDC、Cookie/CSRF、机器人拦截页、ArcGIS REST 等）和资源类型（JSON、CSV、HTML 表格、PDF、图片等），但不针对任何特定网站。下游 SDK 使用各自的方案和词汇。参见 docs/scope.md。

安装

pip install hardly                  # or: pipx install hardly / uv tool install hardly
pip install 'hardly[capture]' && python -m playwright install chromium   # optional: record HARs

要参与 hardly 项目开发：pip install -e ".[dev]"（CONTRIBUTING.md）。

Python 3.10+。请提供输出路径来保存文件，否则不会写入任何内容。 除非传入 output_path，否则所有内容都保存在内存中（hardly session open HAR -o index.db）。Python： with open_session(har) as s: ...（integrating.md）。

60 秒快速入门

hardly guide mode                             # which of the three modes fits
hardly session overview path/to/capture.har   # counts per server, method and status
hardly session site-brief path/to/capture.har # one-screen digest of a server-rendered site
hardly endpoint list path/to/capture.har --host api.example.com
hardly session report path/to/capture.har     # one-pass findings with severity
hardly write export path/to/capture.har --format openapi -o api.yaml
hardly write export path/to/capture.har --format client_python --host api.example.com -o client.py

对于 Agent，请从 hardly_guide_task_plan(goal, har_path, url) 开始（CLI： hardly guide task-plan --goal ...）：它会返回一个有序计划，其中包含示例调用和当前环境状态。

名称说明操作效果

CLI 和 MCP 服务使用同一套词汇：命令名称就是去掉 hardly_ 前缀后的工具名称 （hardly_session_open 对应 hardly session open HAR，hardly_send_entry 对应 hardly send entry HAR 12 --confirm）。

第一个词	含义
send	向真实服务发送请求；需要 confirm=true（CLI 中为 --confirm），否则只返回计划
write	写入文件；除非设置 overwrite=true（--overwrite），否则不会覆盖已有文件
browser	操作或读取真实浏览器
其他任何词	只读取已加载的数据

合并工具接收 sections 列表，例如 hardly_auth_report(sections=['credentials', 'cookies'])。参考：docs/tools.md（71 个工具）、docs/cli.md （命令）；稳定性承诺：docs/api-stability.md。

三种模式

模式	适用场景	入口
archive	已有 HAR 文件	hardly_session_open(har_path)，然后使用 hardly_session_site_brief / hardly_endpoint_list
headless	只有 URL；Agent 可以操作页面	hardly_browser_capture_discover(url, analyze=true, confirm=true)（CLI hardly browser capture-discover URL --analyze --confirm）
interactive	机器人拦截页、验证码、MFA、复杂界面	hardly_browser_start(headed=true)，询问用户，然后使用 hardly_browser_stop

捕获完成后，使用返回的 session_id 继续以 archive 模式操作。hardly 绝不会绕过验证码或机器人拦截页：它会识别这些情况，并提示你停止、询问用户或在其他地方重新运行 （docs/gate-policy.md）。详情：docs/capture.md。

安装并运行，无需克隆

uvx hardly serve                              # MCP server over stdio (archive mode)
uvx --from 'hardly[capture]' hardly browser --help   # with the Playwright capture extra
pipx install 'hardly[capture]'                # or install the CLI permanently
hardly skill install                          # copy the Agent Skill into ~/.claude/skills/hardly

已发布软件包的 MCP 客户端配置：

{ "mcpServers": { "hardly": { "command": "uvx", "args": ["hardly", "serve"] } } }

浏览器捕获需要本地安装（安装 [capture] extra，然后运行 python -m playwright install chromium； 有头捕获需要显示器）。容器镜像 ghcr.io/b1tninja/hardly（多架构，每次发布时构建）仅用于归档和无头分析；请将工作目录挂载到 /workspace。 发布和验证详情：docs/releasing.md。

MCP 设置（Cursor 等）

本地 venv（推荐；有头捕获需要显示器）：

{
  "mcpServers": {
    "hardly": {
      "command": "/path/to/hardly/.venv/bin/python",
      "args": ["-m", "hardly"]
    }
  }
}

Windows 上请使用 ...\\.venv\\Scripts\\python.exe。hardly serve 会启动同一服务。

Docker（仅用于离线分析；请挂载工作目录）：

python scripts/build_image.py       # builds hardly-mcp:latest (Windows: scripts\deploy-docker.ps1)

{
  "mcpServers": {
    "hardly": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
               "-v", "/home/me/work:/workspace",
               "-e", "HARDLY_WORKSPACE=/workspace",
               "hardly-mcp:latest"]
    }
  }
}

挂载路径下的主机路径会映射到 /workspace/...。若要跳过本地构建，请使用已发布的镜像 ghcr.io/b1tninja/hardly:latest 替代 hardly-mcp:latest。

Agent 入门

• hardly_guide_task_plan、hardly_guide_mode、hardly_server_status（MCP 已过期？请重启服务）， hardly_guide_help(topic)。
• MCP 提示词：analyze_har、discover_apis、capture_portal、document_api、find_auth_flow、 reverse_engineer_api、build_client_sdk、diagnose_blocked_capture、verify_client。
• MCP 资源：hardly://cheatsheet 和 hardly://docs/<name>（打包的文档）。
• Agent Skill：hardly skill install [--dest DIR]（默认 ~/.claude/skills/hardly），或 hardly skill print。来源：skills/hardly。

文档

文档	内容
docs/README.md	所有文档的索引
docs/scope.md	范围内与范围外的内容；变更检查清单
docs/cheatsheet.md	一页式快速参考
docs/concepts.md	会话、索引、脱敏、模式
docs/sdk-workflow.md	从捕获到客户端 SDK，分步说明
docs/reporting.md	hardly_session_report 的发现
docs/catalog.md	目标目录、TargetAdapter、批量验证
docs/capture.md	无头和交互式捕获、操作指南、环境变量
docs/technologies.md	各项技术的检测内容
docs/architecture.md	数据流和设计规则
docs/troubleshooting.md	首次使用时的常见问题
docs/tools.md	所有 MCP 工具的生成式参考文档
docs/cli.md	CLI 语法和所有命令（生成）
docs/api-stability.md	公开内容及 v1 兼容性政策
docs/api-decisions.md	v1 名称的选择方式；旧名称到新名称的对应关系

库的使用

from hardly import open_session

with open_session("capture.har") as s:      # in memory; pass output_path= to save the index
    print(s.conn.execute("select count(*) from entries").fetchone()[0])

开发和测试

pytest -q                 # offline; HARDLY_LIVE_CAPTURE=1 enables live Playwright tests
ruff check .

针对公开演示站点进行实时压力测试（不使用私人 HAR）：运行 hardly soak live --list，然后运行 hardly soak live（或使用 --ids datatables-ajax,quotes-login,…）。目录涵盖回环 WebForms／令牌登录、HTML／AJAX 表格、表单登录、GraphQL 和 JSON／OpenAPI——参见 hardly.live_targets 和 docs/test-targets.md。 参见 CONTRIBUTING.md、AGENTS.md；发布说明见 CHANGELOG.md。

安全

HAR 文件通常包含有效密码和会话令牌。hardly 默认会进行脱敏，但请将捕获内容视为机密：不要提交或分享；如果凭据泄露，请轮换凭据。仅将 hardly 用于你获准访问的目标。参见 SECURITY.md。

许可证

MPL-2.0。生成的输出（存根、OpenAPI、报告）不在许可范围内；参见 NOTICE.md。