lencx/opsail
GitHub: lencx/opsail
Opsail 是一个模块化的 Rust CLI 工具，为 AI 代理提供可组合的数据操作，首个功能是将静态 HTML 转换为 Markdown、净化 HTML 或结构化 JSON。
Stars: 9 | Forks: 0
# Opsail
English | [简体中文](https://github.com/lencx/opsail/blob/main/README.zh-CN.md)
Opsail 是一个模块化的 Rust CLI，专为软件代理（software agents）所需的小型、可组合操作而设计。它的首个操作 `read`，可以将来自 HTTP(S) URL、本地文件或标准输入的静态 HTML，转换为易读的 Markdown、净化后的 HTML 或带有版本控制的 JSON。
Opsail 仅提取其接收到的 HTML；它不会执行 JavaScript、维护浏览器会话、对网站进行身份验证、抓取链接或与页面进行交互。
| Crate | 版本 | 描述 |
| --- | --- | --- |
| [`opsail`](https://crates.io/crates/opsail) | [](https://crates.io/crates/opsail) | 代理操作 CLI 及统一命令入口点 |
| [`opsail-read`](https://crates.io/crates/opsail-read) | [](https://crates.io/crates/opsail-read) | 从静态 HTML 中提取干净的 Markdown、净化的 HTML 和结构化的 JSON |
## 安装说明
Opsail 需要 Rust 1.97 或更高版本。从 crates.io 安装最新版本：
```
cargo install opsail
```
验证安装：
```
opsail --version
```
## 读取 HTML
默认输出为 Markdown：
```
opsail read https://example.com/article
opsail read ./article.html
opsail read - < article.html
```
选择其他表示形式、为非 URL 输入解析相对链接、提取单个字段，或将结果写入文件：
```
opsail read ./article.html --format html --output cleaned.html
opsail read - --base-url https://example.com/articles/ < article.html
opsail read ./article.html --format json
opsail read ./article.html --property title
```
`extract` 是 `read` 的可见别名。运行 `opsail read --help` 可查看请求标头、超时、字节限制和输出选项。
### 输出契约
数据会被写入 stdout，或写入 `--output PATH`。诊断信息和提取警告会被写入 stderr，因此通过管道（pipe）传输 stdout 是安全的。每种成功的表示形式末尾都会带有一个换行符。下游关闭的管道会被视为成功终止。
| 退出代码 | 含义 |
| --- | --- |
| `0` | 成功的命令、帮助或版本输出 |
| `1` | 获取、提取、序列化或写入失败 |
| `2` | 无效的命令行用法 |
`--format json` 会生成 schema 版本为 `1` 的输出，包含以下顶级字段：
```
schemaVersion
content
contentHtml
metadata
source
extraction
quality
warnings
```
`content` 是 Markdown，而 `contentHtml` 是净化的 HTML。元数据（Metadata）包括标题，以及在可用时包含作者、描述、站点、发布时间戳、图像、网站图标（favicon）、语言、方向、规范 URL 和域名。来源、提取和质量对象（objects）会记录出处及有用的置信度信号。
`--property` 接受：
```
content, markdown, contentHtml, html, title, author, description, site,
published, modified, image, favicon, language, direction, url, canonicalUrl, domain,
wordCount, quality, source, extraction
```
使用 `--format json` 时，提取出的属性是有效的 JSON。使用 Markdown 或 HTML 格式时，标量属性为纯文本，而结构化属性为格式化输出的 JSON。
### 默认设置与限制
- 最大输入：5 MiB；可使用正数的 `--max-bytes` 值覆盖。
- 最大解析 DOM：50,000 个元素和 256 层嵌套。
- HTTP(S) 超时：连接超时为 5 秒，整体超时为 15 秒；`--timeout` 会覆盖整体超时设置。
- 重定向限制：10 次。
- URL 输入和 `--base-url` 必须使用 HTTP(S)，且不能包含内嵌的用户名/密码凭据。
- 字符解码会依次考虑 BOM、HTTP 字符集、HTML 元数据、UTF-8 有效性，然后是 Windows-1252 回退机制。
- 获取的响应体（body）必须看起来像 HTML。如果声明了媒体类型，它必须是 HTML 或可容忍的通用文本/二进制类型。
- 文件输入必须是常规文件。除非提供了 `--base-url`，否则其链接保持相对状态。URL 输入会根据最终响应的 URL 解析链接。
字节和 DOM 限制仅限制了常见的资源耗尽途径；它们并非安全沙箱。URL 获取可以到达宿主网络允许的目标，并遵循系统代理。请将提取的文本和链接视为不受信任的内容，并在嵌入式代理中强制执行网络、文件系统和下游执行策略。
## 贡献指南
开发环境设置、模块边界、测试规则和验证命令记录在 [CONTRIBUTING.md](https://github.com/lencx/opsail/blob/main/CONTRIBUTING.md) 中。
## 许可证
Apache License 2.0
标签：AI代理工具, Homebrew安装, HTML转Markdown, Rust, SOC Prime, 可视化界面, 多模态安全, 开发工具, 文档结构分析, 网络流量审计, 通知系统, 防御加固