- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
12 KiB
Executable File
markup, import, title, description
| markup | import | title | description | ||||
|---|---|---|---|---|---|---|---|
| occlusion |
|
lib/网络 | 中文 HTTP(S) 包装。可选 headers / content_type 经宿主别名绑定。 |
中文 HTTP(S) 包装。可选 headers / content_type 经宿主别名绑定。
处理 HTTP、响应数据和有界下载。
能力与边界:读取只需 network.read;可恢复请求的方法可动态变化,因此保守要求 network.write。响应头是 name/values 行记录,可用响应头值取值。下载还需 fs.write;旧接口保留原契约。
本文件就是调用和开发手册:直接导入此文件,或用 marqdo call 按下面的函数标题调用。参数表说明类型和默认值;未填默认值的参数必须提供。返回表是渐进契约,后文说明失败与边界。
实现入口:src/host/net.rs、src/host/net_ops.rs
开发时保持中英文语义一致,先组合公开库;仅在 OS 或算法边界添加宿主原语并声明效应。修改后运行 marqdo check --narrative-ratio 本文件,并执行 tests/stdlib_tasks.rs 的真实任务。
获取
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 地址 | any | 必填 | 目标 URL;HTTP 接口接受 http 或 https |
| headers | any | None | HTTP 头名称与值记录;None 不附加额外头 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 支持 HTTPS |
这里使用地址、headers=None。
调用效应:network.read。
支持 HTTPS。可选具名实参 headers=(映射)。
完成后返回*[支持 HTTPS](> host_http_get url=地址 headers=headers)*。
提交
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 地址 | any | 必填 | 目标 URL;HTTP 接口接受 http 或 https |
| 内容 | any | 必填 | 请求正文;文档操作中为替换正文 |
| content_type | any | None | HTTP 内容类型覆盖;None 使用接口默认值 |
| headers | any | None | HTTP 头名称与值记录;None 不附加额外头 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 默认 Content-Type 为 JSON |
这里使用地址、内容、content_type=None、headers=None。
调用效应:network.write。
默认 Content-Type 为 JSON。可选 content_type= / headers=。
完成后返回*[默认 Content-Type 为 JSON](> host_http_post url=地址 body=内容 content_type=content_type headers=headers)*。
提交流式
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 地址 | any | 必填 | 目标 URL;HTTP 接口接受 http 或 https |
| 内容 | any | 必填 | 请求正文;文档操作中为替换正文 |
| content_type | any | None | HTTP 内容类型覆盖;None 使用接口默认值 |
| headers | any | None | HTTP 头名称与值记录;None 不附加额外头 |
| 打印增量 | any | False | 是否在接收 SSE 时打印增量文本 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | POST 并消费 OpenAI 兼容 SSE |
这里使用地址、内容、content_type=None、headers=None、打印增量=False。
调用效应:network.write。
POST 并消费 OpenAI 兼容 SSE。返回 {status, events}(delta / done / error)。打印增量=真 时边读边打印增量文本。
完成后返回*[POST 并消费 OpenAI 兼容 SSE](> host_http_post_sse url=地址 body=内容 content_type=content_type headers=headers echo=打印增量)*。
解析流式
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 内容 | any | 必填 | 本操作读取、转换或输出的文本 |
| 打印增量 | any | False | 是否在接收 SSE 时打印增量文本 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 离线解析 OpenAI 聊天 SSE 正文为事件列表(不联网) |
这里使用内容、打印增量=False。
调用效应:pure。
离线解析 OpenAI 聊天 SSE 正文为事件列表(不联网)。
完成后返回*[离线解析 OpenAI 聊天 SSE 正文为事件列表(不联网)](> host_openai_sse_parse text=内容 echo=打印增量)*。
请求
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 方法 | any | 必填 | HTTP 方法,例如 GET 或 POST |
| 地址 | any | 必填 | 目标 URL;HTTP 接口接受 http 或 https |
| 正文 | any | None | 请求正文;文档操作中为替换正文 |
| content_type | any | None | HTTP 内容类型覆盖;None 使用接口默认值 |
| 表头 | any | None | HTTP 头名称与值记录;None 不附加额外头 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 可选 body= / content_type= / headers= |
这里使用方法、地址、正文=None、content_type=None、表头=None。
调用效应:network.write。
可选 body= / content_type= / headers=。
完成后返回*[可选 body= / content_type= / headers=](> host_http_request method=方法 url=地址 body=正文 content_type=content_type headers=表头)*。
编码地址
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 内容 | any | 必填 | 本操作读取、转换或输出的文本 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | 对 URL 段做百分号编码 |
这里使用内容。
调用效应:pure。
对 URL 段做百分号编码。
完成后返回*[对 URL 段做百分号编码](> host_url_encode text=内容)*。
解析Cookie
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 内容 | any | 必填 | 本操作读取、转换或输出的文本 |
| 是响应头 | any | False | 是否按响应头而非请求头解析 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 解析 Cookie 请求头(默认)或一个/多个 Set-Cookie 响应头(是响应头=真)为 {name, value, path, domain, expires, max_age, secure, http_only, same_site} 列表 |
这里使用内容、是响应头=False。
调用效应:pure。
直接调用此函数:
marqdo call lib/网络.mq.md 解析Cookie '内容="a=1; b=2"' --effects none --json
解析 Cookie 请求头(默认)或一个/多个 Set-Cookie 响应头(是响应头=真)为 {name, value, path, domain, expires, max_age, secure, http_only, same_site} 列表。
完成后返回*[解析 Cookie 请求头(默认)或一个/多个 Set-Cookie 响应头(是响应头=真)为 {name, value, path, domain, expires, max_age, secure, http_only, same_site} 列表](> host_cookie_parse text=内容 is_response=是响应头)*。
解析多部分
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 正文 | any | 必填 | 请求正文;文档操作中为替换正文 |
| 边界 | any | 必填 | Content-Type 头中的 multipart 分隔标记 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 解析 multipart/form-data 请求体(给定 boundary)为 {name, filename?, content_type?, value} 部件列表 |
这里使用正文、边界。
调用效应:pure。
解析 multipart/form-data 请求体(给定 boundary)为 {name, filename?, content_type?, value} 部件列表。
完成后返回*[解析 multipart/form-data 请求体(给定 boundary)为 {name, filename?, content_type?, value} 部件列表](> host_multipart_parse body=正文 boundary=边界)*。
解析Markdown
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 文本 | any | 必填 | 本操作读取、转换或输出的文本 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | 将 Markdown / GFM 解析为 HTML(纯转换,无网络 I/O) |
这里使用文本。
调用效应:pure。
将 Markdown / GFM 解析为 HTML(纯转换,无网络 I/O)。
完成后返回*[将 Markdown / GFM 解析为 HTML(纯转换,无网络 I/O)](> host_markdown_parse text=文本)*。
可恢复请求
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 方法 | text | 必填 | HTTP 方法,例如 GET 或 POST |
| 地址 | text | 必填 | 目标 URL;HTTP 接口接受 http 或 https |
| 正文 | any | None | 请求正文;文档操作中为替换正文 |
| 表头 | any | None | HTTP 头名称与值记录;None 不附加额外头 |
| 超时毫秒 | number | 30000 | 超时毫秒数;等待后检查操作结果 |
| 字节上限 | number | 8388608 | 读取或展开的字节上限;超限则失败 |
| 响应类型 | text | "text" | 响应正文表示:text 或 bytes |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 返回统一结果记录;value 含 status、headers、body。响应头为 name/values 行记录。动态方法需要 network |
这里使用方法、地址、正文=None、表头=None、超时毫秒=30000、字节上限=8388608、响应类型="text"。
调用效应:network.write。
正文可为文本、字节记录或空值;发送 JSON 前使用 json.stringify。请求头使用字典,响应头使用 name/values 行记录。输出参数和目标路径在联网前预检。
返回统一结果记录;value 含 status、headers、body。响应头为 name/values 行记录。动态方法需要 network.write;只读请求使用读取。HTTP 错误状态仍是响应,传输失败是错误。
完成后返回*[正文可为文本、字节记录或空值;发送 JSON 前使用 json.stringify](> host_http_request_result method=方法 url=地址 body=正文 headers=表头 timeout_ms=超时毫秒 max_bytes=字节上限 response=响应类型)*。
下载
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 地址 | text | 必填 | 目标 URL;HTTP 接口接受 http 或 https |
| 路径 | text | 必填 | 授权文件根目录内的路径 |
| 表头 | any | None | HTTP 头名称与值记录;None 不附加额外头 |
| 超时毫秒 | number | 30000 | 超时毫秒数;等待后检查操作结果 |
| 字节上限 | number | 67108864 | 读取或展开的字节上限;超限则失败 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 有界流式下载至文件;成功后原子替换,失败保留原文件。返回结果记录,value 含 status、headers、size、path;需要 network |
这里使用地址、路径、表头=None、超时毫秒=30000、字节上限=67108864。
调用效应:fs.write,network.read。
有界流式下载至文件;成功后原子替换,失败保留原文件。返回结果记录,value 含 status、headers、size、path;需要 network.read 与 fs.write。
完成后返回*[有界流式下载至文件;成功后原子替换,失败保留原文件](> host_http_download url=地址 path=路径 headers=表头 timeout_ms=超时毫秒 max_bytes=字节上限)*。
读取
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 地址 | text | 必填 | 目标 URL;HTTP 接口接受 http 或 https |
| 表头 | any | None | HTTP 头名称与值记录;None 不附加额外头 |
| 超时毫秒 | number | 30000 | 超时毫秒数;等待后检查操作结果 |
| 字节上限 | number | 8388608 | 读取或展开的字节上限;超限则失败 |
| 响应类型 | text | "text" | 响应正文表示:text 或 bytes |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 只读 GET 请求,返回统一结果记录;只需 network |
这里使用地址、表头=None、超时毫秒=30000、字节上限=8388608、响应类型="text"。
调用效应:network.read。
只读 GET 请求,返回统一结果记录;只需 network.read。响应头为 name/values 行记录,响应类型可选 text/bytes。
完成后返回*[只读 GET 请求,返回统一结果记录;只需 network.read](> host_http_get_result url=地址 headers=表头 timeout_ms=超时毫秒 max_bytes=字节上限 response=响应类型)*。
响应头值
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 响应头 | list | 必填 | 响应中的 headers 行记录 |
| 名称 | text | 必填 | 头部名称 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 同名头部的全部值 |
这里使用响应头、名称。
调用效应:pure。
从响应头行记录中按不区分大小写的名称取全部值;不存在返回空列表。请求的 headers 参数仍使用字典,响应 headers 使用行记录以保留任意名称和重复值。
得到**lower = 调用 to lower。
得到matches = [调用 where](table.where(list=响应头, key="name", value=lower))。
得到values = [调用 pluck](table.pluck(list=matches, key="values"))**。
完成后返回*调用 flatten*。