节点手册：HTTP 请求与 Web 工具-ChengOS 可视化工作流编排 · MCP 原生支持

适用版本：ChengOS v0.1.0+ ｜最后核对：2026-08-13 ｜来源：crates/cheng-nodes/src/nodes/builtin/tools

与系统之外打交道的一组。tools/http 是原始请求；tools/web 高一层，提供抓取、提取正文、爬取、下载等操作 —— 当你要的是内容而不是响应体时优先用它。 tools/fetch_repository 拉取技能源，tools/ssh 执行远程命令，tools/mail 覆盖收发邮件。 tools/http 与 tools/web 都提供两种模式：手动模式由工作流填齐全部参数，LLM 模式交给模型填写。浏览器节点位于可选的编译特性之后，不在默认构建中。

HTTP 请求 — `tools/http`

向指定 URL 发送 HTTP 请求,支持手动和 LLM 模式.

输入

字段	类型	必填	默认值	说明
`credential_id`	string	—	`null`	HTTP 认证凭证 ID(可选,用于 Bearer Token 或 Basic Auth). 控件：`credential-select`
`mode`	enum	—	`manual`	执行模式:Manual=用户填写所有参数,Llm=LLM 自动填写参数. 控件：`select`. 取值：`manual` (手动模式：用户在前端填写所有参数), `llm` (LLM 模式：LLM 通过 ReAct 调用时填充参数)
`url`	string	—	`null`	目标 URL(LLM 模式下由 LLM 填写,手动模式下由用户填写)
`method`	enum	—	`GET`	HTTP 方法. 控件：`select`. 取值：`GET`, `POST`, `PUT`, `DELETE`, `PATCH`
`headers`	object	—	`null`	自定义请求头(可选)
`body`	string	—	`null`	请求体(JSON 字符串或表单数据). 控件：`code-editor`
`timeout_seconds`	integer	—	`30`	超时时间(秒). 控件：`number`
`body_artifact`	object	—	`null`	用作请求体的工件引用（大上传时优先于内联 body）
`body_artifact_uri`	string	—	`null`	用作请求体的 artifact:// URI
`request_profile`	enum	—	`general`	静态配置：general（默认）或 discovery（只读 HTTPS GET 检查）。取值：`general` (General-purpose HTTP (backward compatible).), `discovery` (Read-only discovery: HTTPS GET only, no credentials/headers/body.)

输出

字段	类型	说明
`mode`	string	执行模式
`timeout_seconds`	integer	超时时间(秒)
`status_code`	integer	HTTP 响应状态码
`body`	string	已废弃的有界内联响应文本；大/二进制响应使用 body_artifact
`body_artifact`	object	响应体过大或二进制时持有完整响应体的工件
`body_preview`	string	面向 LLM 的有界响应体预览
`body_bytes`	integer	观察/声明的响应体总大小（字节）（分块响应可能未知）
`retained_bytes`	integer	实际保留/存储的字节数；截断时区分存储大小与远程总大小
`location`	string	3xx 响应的规范化、已验证重定向目标（自动重定向保持禁用）
`body_mime_type`	string	响应体 MIME 类型
`body_sha256`	string	响应体内容哈希
`download_filename`	string	响应载荷的建议文件名
`body_truncated`	boolean	内联 body/preview 是否相对于完整响应被截断
`headers`	object	响应头
`elapsed_ms`	integer	请求耗时(毫秒)
`credential_used`	boolean	是否使用了凭证认证

Web 工具套件 — `tools/web`

综合性 Web 套件：HTTP 请求、网页读取、元数据、结构化提取、正文抽取、下载、爬取与搜索。

输入

字段	类型	必填	默认值	说明
`mode`	enum	—	`manual`	Execution mode — mirrors the concept used by `tools/http`. 取值：`manual` (Manual mode: the user/workflow supplies every parameter.), `llm` (LLM mode: the agent may fill selected fields during tool use.)
`operation`	enum	—	`fetch`	The nine supported web operations. 取值：`request`, `check`, `fetch`, `metadata`, `extract`, `article`, `download`, `crawl`, `search`
`credential_id`	string	—	`null`	凭证
`url`	string	—	`null`	URL
`method`	enum	—	`GET`	HTTP methods supported by `request` / `check`. 取值：`GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`
`headers`	object	—	`null`	请求头
`body`	string	—	`null`	请求体
`query`	string	—	`null`	搜索查询
`selector`	string	—	`null`	选择器
`extract_mode`	enum	—	`text`	Extraction mode for the `extract` operation. 取值：`text`, `html`, `markdown`, `attr`, `json`
`attribute_name`	string	—	`null`	属性名
`output_format`	enum	—	`markdown`	Output format for `fetch` and per-page crawl conversion. 取值：`raw_html`, `text`, `markdown`
`include_headers`	boolean	—	`false`	包含全部响应头
`header_filter`	array	—	`null`	响应头过滤白名单
`save_path`	string	—	`null`	保存路径
`allowed_mime_types`	array	—	`null`	允许的 MIME 类型
`overwrite`	boolean	—	`false`	允许覆盖
`max_download_bytes`	integer	—	`52428800`	download 操作的独立大小上限（下载通常比上下文响应体更大，因此有独立限制）。
`max_response_bytes`	integer	—	`1048576`	最大响应字节数
`page_character_limit`	integer	—	`20000`	单页字符上限
`max_total_bytes`	integer	—	`200000`	爬取总字节预算
`max_total_tokens`	integer	—	`50000`	爬取总 Token 预算
`max_depth`	integer	—	`2`	最大深度
`max_pages`	integer	—	`20`	最大页数
`same_origin_only`	boolean	—	`true`	仅同源
`allowed_domains`	array	—	`null`	允许的域名
`respect_robots`	boolean	—	`true`	遵守 robots.txt
`crawl_delay_ms`	integer	—	`500`	爬取间隔（毫秒）
`concurrency`	integer	—	`2`	并发数
`search_provider`	enum	—	`tavily`	搜索服务：tavily 或 searxng。控件：`select`. 取值：`tavily`, `searxng`
`search_base_url`	string	—	`null`	自托管搜索提供商（如 SearXNG）的静态基础 URL。视为运营方配置，绝非 LLM 控制的任意端点。
`max_results`	integer	—	`5`	最大结果数
`search_page`	integer	—	`1`	搜索页码
`search_include_content`	boolean	—	`false`	包含正文内容
`timeout_seconds`	integer	—	`30`	超时时间（秒）

输出

字段	类型	说明
`mode`	string	执行模式
`operation`	string	操作
`url`	string	请求 URL
`final_url`	string	最终 URL
`status_code`	integer	状态码
`content_type`	string	内容类型
`elapsed_ms`	integer	耗时（毫秒）
`body_truncated`	boolean	响应体被截断
`result_truncated`	boolean	结果被截断
`spa_detected`	boolean	检测到 SPA
`warnings`	array<string>	警告
`credential_used`	boolean	使用了凭证
`result`	any	操作特定的载荷（参见各操作的结果结构体）。

获取技能源码 — `tools/fetch_repository`

将远程技能源(通过浅克隆 git 仓库或单个 HTTP URL)获取到沙盒临时目录,并返回采集的文件负载.

输入

字段	类型	必填	默认值	说明
`source_type`	string	—	`repository`	repository \
`source_location`	string	—	`""`	仓库克隆 URL,HTTPS 文档 URL,或粘贴内容的短标识符(仅作为 source_type 为 pasted_text / skill_md 时的标签使用).
`source_content`	string	—	`null`	内联文件内容.pasted_text / skill_md 类型必需,repository / url 类型忽略.
`branch`	string	—	`null`	Git 分支(可选,仅仓库类型)
`harvest_mode`	string	—	`skill_package`	skill_package（默认）\
`llm_inline_max_bytes`	integer	—	`50000`	将完整源码文本以内联方式返回,最多到此字节数;超过则写入文件并返回路径.0 表示始终返回路径.
`allow_insecure_schemes`	boolean	—	`false`	允许 http/ssh/git URL(默认仅 https)
`legacy_inline_files`	boolean	—	`false`	已废弃兼容：同时内联输出完整 `files[].content`（有严格总字节上限）。默认关闭 — 正常执行返回文件工件加有界 `llm_preview`。
`sandbox_root`	string	—	`null`	引擎注入的沙箱根目录（与 `file_ops_hub` 同权限）。非 LLM 可调用 — 工作流引擎通过 `apply_effective_sandbox_root` 注入，使 `fetch_repository` 写入与 `file_ops_hub` 读取相同的根目录。

输出

字段	类型	说明
`success`	boolean	成功
`package_path`	string	与 `file_ops_hub` 和 `validate_skill_spec` 共享的工作区相对包目录，如 `skills/example-skill`。
`files`	array<object>	已废弃兼容：内联完整文件载荷。除非设置 `legacy_inline_files`（且有严格字节上限），否则为空。请改用 `files_manifest` / `repository_artifact`。
`files_manifest`	array<object>	每文件的工件元数据（路径、大小、MIME、工件引用）。下游节点解析每个工件以恢复完整文件内容。
`existing_files`	array<string>	目标包已存在时的工作区相对文件列表。此信息分支不创建新工件或读取文件内容。
`repository_artifact`	object	完整获取的源作为单个 JSON 包工件（`{ files: [{ path, content }] }`），供整个仓库的消费者使用。
`manifest_artifact`	object	清单过大时持有完整清单的可选工件。
`llm_preview`	string	有界的 LLM 预览：源 URL、提交、每文件大小和预算内的小摘录。不含完整文件内容。
`total_files`	integer	收获的文件总数。
`total_bytes`	integer	所有收获文件的总字节数。
`warnings`	array<string>	已省略文件（二进制、超大、排除、密钥）和全局截断（达到上限）的结构化警告。不含文件内容。
`llm_text`	string	获取文件的文本渲染,格式化为可直接连接到 ai/llm.user_message 或 agent/react_agent.task.
`source_snapshot_artifact`	object	受信任的完整源快照工件（每个接受的常规文件，逐字节）。这是 Agent 转发给 `tools/write_skill_package` 的唯一引用；它从不自行重建源字节。
`source_manifest`	array<object>	源快照的完整（或有界内联）清单：每文件的路径、类型、大小、SHA-256 和文本可读性。
`source_manifest_artifact`	object	清单过大无法内联时作为 JSON 工件持有完整清单。
`source_file_count`	integer	源快照中的文件数量。
`source_total_bytes`	integer	源快照的总字节数。
`source_scan_truncated`	boolean	仅当快照无法完整表示时为 true。为 true 时必须拒绝激活 — 部分树永远不是自包含的 Skill。
`commit_hash`	string	提交哈希
`source_url`	string	源地址
`error`	string	错误

SSH 执行器 — `tools/ssh`

通过 SSH 在远程主机上执行命令,内置审批门,风险分类命令和只读执行策略,并呈现 4 种不同的拒绝原因(rejected/skipped/timed_out/policy_denied),方便 Agent 正确重新规划.

输入

字段	类型	必填	默认值	说明
`host`	string	✅	—	远程主机(主机名或 IP)
`port`	integer	—	`22`	远程 SSH 端口. 控件：`number`
`credential_id`	string	—	`null`	SSH 凭证——私钥或密码(通过凭证仓库解析). 控件：`credential-select`
`command`	string	—	`""`	在远程主机上执行的命令. 控件：`code-editor`
`working_dir`	string	—	`null`	执行命令前的可选工作目录.
`timeout_ms`	integer	—	`30000`	单命令执行超时时间(毫秒). 控件：`number`
`strict_host_key_checking`	boolean	—	`true`	TOFU(首次信任使用):首次连接主机时弹出用户审批确认指纹;后续连接使用受信任的指纹.仅在自动化测试时禁用. 控件：`switch`
`read_only_mode`	boolean	—	`false`	硬策略:启用时,任何非只读命令都会被拒绝,无需经过审批. 控件：`switch`
`approval_required_at_or_above`	enum	—	`medium`	触发审批门的风险阈值(默认 Medium). 控件：`select`. 取值：`low`, `medium`, `high`, `critical`
`approval_timeout_secs`	integer	—	`300`	等待用户决策的秒数,超时后自动拒绝(默认 300). 控件：`number`

输出

字段	类型	说明
`success`	boolean	命令执行成功且返回 0.
`exit_code`	integer	远程进程退出码.
`stdout`	string	捕获的标准输出.
`stderr`	string	捕获的标准错误.
`duration_ms`	integer	墙钟执行时间.
`host`	string	目标主机回显,用于可追溯性.
`command`	string	命令回显,用于可追溯性.
`risk_level`	string	此命令的风险分类.
`rejection_type`	string	区分执行,审批和策略结果.
`reason`	string	用户或策略给出的原因文本.
`approval_request_id`	string	匹配审批总线事件的 UUID.
`observation`	string	面向 Agent 的观察文本,带有 [APPROVAL_*] 前缀.

邮件工具 — `tools/mail`

通过 IMAP/SMTP 协议操作真实邮件：发送、读取、搜索、移动、标记、回复、转发等

输入

字段	类型	必填	默认值	说明
`imap_credential_id`	string	—	`null`	IMAP 凭证,用于接收操作(读取,搜索,移动,删除等 – ListEmails/SearchEmails/GetEmail/MoveEmail 等). 控件：`credential-select`
`smtp_credential_id`	string	—	`null`	SMTP 凭证,用于发送操作(SendEmail/ReplyEmail/ForwardEmail). 控件：`credential-select`
`operation`	enum	—	—	要执行的邮件操作类型. 控件：`select`. 取值：`send_email` (发送邮件（需 SMTP 配置）), `list_emails` (获取邮件列表（需 IMAP 配置）), `search_emails` (搜索邮件（需 IMAP 配置）), `get_email` (获取邮件详情及正文（需 IMAP 配置）), `move_email` (移动邮件到指定文件夹), `copy_email` (复制邮件到指定文件夹), `delete_email` (删除邮件), `mark_as_read` (标记邮件为已读), `mark_as_unread` (标记邮件为未读), `list_folders` (列出所有邮件文件夹), `reply_email` (回复邮件（需 IMAP + SMTP 配置）), `forward_email` (转发邮件（需 IMAP + SMTP 配置）)
`display_name`	string	—	—	发件人显示名称(如张三),留空仅显示邮箱地址
`folder`	string	—	`INBOX`	邮件文件夹名称(默认 INBOX,已发送通常为 Sent 或 [Gmail]/Sent Mail)
`page`	integer	—	`1`	页码从 1 开始(默认 1,最新邮件在第 1 页)
`page_size`	integer	—	`20`	每页邮件数量(默认 20,最大 50)
`to`	string	—	—	收件人邮箱地址,多个地址用逗号分隔
`cc`	string	—	—	抄送邮箱地址,多个地址用逗号分隔
`bcc`	string	—	—	密送邮箱地址,多个地址用逗号分隔
`subject`	string	—	—	邮件主题
`body`	string	—	—	邮件正文内容
`format`	enum	—	—	正文格式:text(纯文本),html(HTML),both(同时发送,推荐). 取值：`text` (纯文本), `html` (HTML 格式), `both` (同时发送纯文本和 HTML（推荐，兼容性最好）)
`query`	string	—	—	IMAP 搜索语法:FROM “sender@example.com”,SUBJECT “关键词”,UNSEEN(未读),SINCE “1-Jan-2024”,可组合使用
`email_id`	string	—	—	邮件唯一标识符(从 ListEmails/SearchEmails 结果的 id 字段获取)
`target_folder`	string	—	—	移动或复制邮件的目标文件夹名称(如 Archive,Trash,[Gmail]/All Mail)
`attachments`	array<object>	—	—	要发送的附件（推荐工件引用；也允许小内联文本）
`include_attachments`	boolean	—	`false`	GetEmail：下载并将附件正文持久化为工件

输出

字段	类型	说明
`success`	boolean	操作是否成功
`message`	string	操作结果描述
`emails`	array<object>	邮件列表
`folders`	array<string>	邮件文件夹名称列表
`page`	integer	当前页码
`count`	integer	本次返回的邮件数量
`total_count`	integer	文件夹中的邮件总数(仅 ListEmails 提供)

下一步

文章版权归作者所有，未经允许请勿转载。

THE END

节点手册

节点手册：HTTP 请求与 Web 工具

HTTP 请求 — tools/http

输入

输出

Web 工具套件 — tools/web

输入

输出

获取技能源码 — tools/fetch_repository

输入

输出

SSH 执行器 — tools/ssh

输入

输出

邮件工具 — tools/mail

输入

输出

下一步

请登录后发表评论

HTTP 请求 — `tools/http`

Web 工具套件 — `tools/web`

获取技能源码 — `tools/fetch_repository`

SSH 执行器 — `tools/ssh`

邮件工具 — `tools/mail`