2026/9/10 22:24:46
FEATURED · 精选文章 
OpenHuman System Utilities 原生工具族shell、脚本执行、时间、通知与工作区自省全解析【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhumanOpenHuman 为 Agent 内置了一整套开箱即用的原生工具Native Tools其中 System Utilities 是包罗万象的杂项工具族——涵盖 shell 命令执行、Node/Python 脚本、单次定时任务、Pushover 推送、SQL 记录、LSP 查询、工作区自省与代理配置等小而锋利的工具。本文以官方文档 system-and-utilities.md 为骨架深入对应源码实现帮你掌握这套工具族的每个成员、参数细节与底层安全机制从而更高效地驱动 OpenHuman Agent 完成跑命令、做计算、看时间、发通知这类日常杂务。工具族全景12 个成员一览System Utilities 是文档中的catch-all family兜底工具族专门处理那些不适合归入 Web Search、Coder、Memory 等更大工具族的零碎环节。官方文档列出的成员如下工具作用shell执行 shell 命令输出有界、捕获退出码node_exec运行 Node.js 代码片段适合一次性脚本npm_exec运行npm/pnpm/yarn脚本python_exec运行 Python 3 代码片段或.py脚本current_time获取任意时区的当前时间支持格式化选项schedule一次性在 T 时刻做某事循环任务见 Cronpushover向你的设备发送推送通知insert_sql_record向 Agent 的结构化工作区 SQL 存储追加一行lsp查询语言服务器定义、引用、诊断workspace_state检查当前工作区——打开的文件、近期编辑、环境信息proxy_config读取或修改出站请求的代理配置tool_stats自省——本次会话中用了哪些工具、各用了几次从源码来看实际注册的工具比文档表格更多在 src/openhuman/tools/impl/system/mod.rs 中还能看到detect_tools探测机器上可用的运行时/工具、install_tool安装缺失的运行时、resolve_time、retrieve_tool_output取回先前命令的输出、update_check/update_apply检查与应用 OpenHuman 更新等成员它们与文档列举的 12 个工具共用同一套安全与审计基础设施。适用场景什么时候该用它官方文档给出四类典型用途这也是这套工具族的设计意图工作流中的零碎环节——那些不属于任何更大工具族的边角步骤。帮我跑一下这条命令告诉我打印了什么——最直接的 shell 交互模式。时间感知行为——例如用户那边现在几点这类问题无需在提示词中硬编码时区假设直接交给current_time。让 Agent 在长任务跑完后主动通知你——通过pushover或schedule实现做完叫我。一个关键的使用建议来自文档的 See also文件系统重的工作优先用专用工具Coder 中的读写/编辑/patch 工具而不是shell循环性任务优先用 Cron Scheduling而不是一次性schedule。深入shell有界输出、退出码与三层安全防线shell是这套工具族里最重要的成员。其实现位于 src/openhuman/tools/impl/system/shell.rs几个关键设计值得展开1. 输出有界Bounded output单条 stdout 与 stderr 各自被截断到 1 MBMAX_OUTPUT_BYTES 1_048_576超出部分追加... [output truncated at 1MB]提示防止 OOM见 shell.rs 第 15-16 行与第 468-481 行。返回给模型历史记录的结果进一步限制在约 30k 字符max_result_size_chars避免find /、依赖安装这类超长输出撑爆上下文需要完整内容时Agent 可以用 head/tail/grep 跟进。工具描述明确提示只回传 stdout/stderr静默计算或只写文件的脚本不会返回任何内容必须主动print/echo或随后读取文件。2. 退出码与双流捕获Capture exit code失败时不再只丢 stderr而是通过 command_output.rs 统一渲染出Command failed (exit code N) stdout stderr 三段式结果并对两个高频不可重试码给出明确提示127命令/依赖未找到不在 PATH应安装或声明依赖不要盲目重试同一命令126权限不足或不可执行通常是沙箱限制应上报阻塞或请求提权其他退出码不附加提示避免对普通应用失败做多余解读。 这一设计解决了模型因丢失 exit code 与 stdout 而陷入无限重试的循环issue #4095。3. 环境隔离与安全子进程先env_clear()清空环境再只放行SAFE_ENV_VARS白名单PATH、HOME、TERM、LANG等系统功能性变量绝不包含 API Key 等机密防止机密泄漏到子进程CWE-200。将TMPDIR/TMP/TEMP重定向到 OpenHuman 的 scratch 目录/tmp/openhuman让python3 tempfile、mktemp等写入落到受信任的沙箱化位置而非全局共享的/tmp。每次调用写入审计日志CommandExecutionLogchanneltool:shell记录命令、是否获批、是否放行、是否成功、耗时审计失败只告警、不阻塞工具调用。4. 超时策略shell 没有默认超时——构建、测试套件、求解器等合法长命令可以跑数分钟issue #4023。只有调用方显式传入timeout_secs范围 1..3600时才启用墙钟超时0表示显式禁用。参数 schema 中还支持可选的category字段read/write/network/install/destructive作为只升不降escalate-only的风险自声明它能提高审批门槛如把 write 标记为 destructive但绝不会降低运行时依据命令分类得出的审批要求。5. 命令分类与审批门shell通过SecurityPolicy::classify_command对命令分类Write/Network/Destructive 类命令在完整权限模式下需要经过ApprovalGate人工审批Block 模式只读与结构化守卫在run_with_security内强制执行。此外还有跨 profile 写守卫check_cross_profile_command见 mod.rs 第 94-150 行对命令中形似路径的 token 与 profile 自己的工作区比对阻止一个 profile 修改另一个 profile 的工作区。6. 沙箱路由与托管运行时注入当 Agent 的SandboxMode为Sandboxed时shell会改用SandboxPolicy将命令路由到 Docker 或 OS 级沙箱后端执行且安全预检依旧生效。同时若托管 Node 已通过NodeBootstrap解析成功shell 会透明地在 PATH 前缀插入托管 Node 的bin/目录对python/pip/python3开头的命令则惰性解析托管 Python 运行时保证pip install foo与python3 -m foo落在同一个解释器上见 shell.rs 第 655-701 行。脚本执行三兄弟node_exec、npm_exec、python_exec这三者把跑脚本从 shell 中独立出来提供更精确的输入结构与托管运行时保障。node_execnode_exec.rs支持两种互斥输入模式模式参数实际调用内联代码inline_code: console.log(11)node -e code脚本路径script_path: scripts/run.js 可选argsnode path args...脚本路径相对于工作区解析逃逸工作区的路径会被文件系统助手拒绝。Node 运行时通过NodeBootstrap在首次调用时解析——如果 PATH 上没有兼容的node会自动下载并解压一份托管 Node 发行版后续调用复用缓存安装。输出同样只回传 stdout/stderr且单流上限 1MBtimeout_secs上限为 1800 秒同样无默认超时。npm_execnpm_exec.rs用于运行npm/pnpm/yarn脚本适合触发 package.json 中定义的build、test、lint等任务。python_exec运行 Python 3 代码片段或.py脚本与 shell 的 Python 注入共享同一套PythonBootstrap保证解释器与依赖一致。这三者连同shell统称 shell-family 工具共享 command_output.rs 的失败渲染与 1MB 输出截断确保失败信息形状在原生与沙箱两条路径上完全一致。时间与定时current_time、resolve_time与schedulecurrent_timecurrent_time.rs是一个只读工具让 Agent 在不 shell 出去调date的情况下获得现在的锚点用于提醒、调度、相对日期解析。返回结构包含utcRFC3339 格式 UTC 时间秒级精度local与local_timezone机器本地时间unix_secondsUnix 时间戳weekday本地星期几可选timezone参数IANA 名称如America/Los_Angeles、Asia/Kolkata传入后附加requested_timezone的转换结果与星期几时区名无效时返回requested_timezone_error提示不会让调用崩溃。工具描述中给出了最佳实践在调度提醒/cron 任务之前或用户提到10 分钟后明天今晚这类相对时间时先调用current_time获得时间锚点。schedule是文档中明确提到的一次性工具——do this once at time T适用于不需要重复执行的单次提醒或单次任务凡是需要周期性执行的官方文档明确指向 Cron Scheduling 家族cron_add/cron_list/cron_update/cron_remove/cron_run/cron_runs。源码中还存在resolve_time工具用于把3 小时后下周四这类自然语言相对时间解析为具体时间点。通知与存储pushover与insert_sql_recordpushoverpushover.rs让 Agent 在长任务完成时主动向你推送通知。它读取工作区.env文件中的PUSHOVER_TOKEN与PUSHOVER_USER_KEY两个凭据支持export前缀、引号包裹与行内#注释请求发送到https://api.pushover.net/1/messages.json请求超时 15 秒。参数包括必填的message与可选的title。这意味着你只需在工作区.env中配置好 Pushover 凭据Agent 就能做完叫你无需额外注册 MCP 服务或插件市场。insert_sql_record向 Agent 的结构化工作区 SQL 存储追加一行适合让 Agent 以结构化方式沉淀每次运行的元数据或结果后续可查询回溯。自省与配置workspace_state、tool_stats、proxy_configworkspace_state检查当前工作区——打开的文件、近期编辑、环境信息让 Agent 在动手前快速确认自己身处什么上下文。tool_stats会话级自省——本次会话已经用过哪些工具、各用了几次帮助 Agent 评估是否过度依赖某个工具或路径。proxy_config读取或修改出站请求的代理配置。这与 OpenHuman 的整体安全模型一致网络类工具默认走托管代理除非你显式切换到 SearXNG 等自托管路径见 native-tools README 中的说明。进阶lsp与语言服务器能力开关lsp工具允许 Agent 查询语言服务器获取定义definitions、引用references与诊断diagnostics信息。从 mod.rs 可以看到该工具受环境变量LSP_ENABLED_ENV控制lsp_capability_enabled函数负责判断开关说明 LSP 能力默认可能不启用需要显式开启后 Agent 才能用它做代码导航式查询。安全模型小结所有工具共享同一套边界无论文档表格里的哪个工具最终都落在 OpenHuman 统一的安全边界内native-tools README 总结为四条一致的错误处理零安装摩擦所有工具内置于进程无需插件市场、API Key 或注册 MCP 服务器所有输出免费经过 Smart Token Compression 压缩控制工具输出成本可预测的安全边界——文件系统工具遵守工作区作用域网络工具默认走托管代理。system模块还提供security_for_tool_contextmod.rs 第 68-88 行把会话的 WorkspaceDescriptor 提升为可读写 trusted root让 shell/python/node/npm 的路径解析与文件工具保持步调一致——既能读编辑一个 checkout也能在同一目录内构建、测试、提交。总结System Utilities 是 OpenHuman Agent 工具腰带上的瑞士军刀shell提供有界输出、退出码与多层安全护栏的命令执行node_exec/npm_exec/python_exec提供带托管运行时保障的脚本执行current_time/schedule支撑时间感知行为pushover让长任务主动通知你workspace_state/tool_stats/proxy_config/lsp则负责自省与配置。理解每个工具的输入结构、输出约束与安全边界你就能编写出更稳健的 Agent 工作流——把跑命令、做计算、看时间、发通知这些杂务放心交给这套内置工具族。【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OpenHuman System Utilities 原生工具族：shell、脚本执行、时间、通知与工作区自省全解析
OpenHuman System Utilities 原生工具族shell、脚本执行、时间、通知与工作区自省全解析【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhumanOpenHuman 为 Agent 内置了一整套开箱即用的原生工具Native Tools其中 System Utilities 是包罗万象的杂项工具族——涵盖 shell 命令执行、Node/Python 脚本、单次定时任务、Pushover 推送、SQL 记录、LSP 查询、工作区自省与代理配置等小而锋利的工具。本文以官方文档 system-and-utilities.md 为骨架深入对应源码实现帮你掌握这套工具族的每个成员、参数细节与底层安全机制从而更高效地驱动 OpenHuman Agent 完成跑命令、做计算、看时间、发通知这类日常杂务。工具族全景12 个成员一览System Utilities 是文档中的catch-all family兜底工具族专门处理那些不适合归入 Web Search、Coder、Memory 等更大工具族的零碎环节。官方文档列出的成员如下工具作用shell执行 shell 命令输出有界、捕获退出码node_exec运行 Node.js 代码片段适合一次性脚本npm_exec运行npm/pnpm/yarn脚本python_exec运行 Python 3 代码片段或.py脚本current_time获取任意时区的当前时间支持格式化选项schedule一次性在 T 时刻做某事循环任务见 Cronpushover向你的设备发送推送通知insert_sql_record向 Agent 的结构化工作区 SQL 存储追加一行lsp查询语言服务器定义、引用、诊断workspace_state检查当前工作区——打开的文件、近期编辑、环境信息proxy_config读取或修改出站请求的代理配置tool_stats自省——本次会话中用了哪些工具、各用了几次从源码来看实际注册的工具比文档表格更多在 src/openhuman/tools/impl/system/mod.rs 中还能看到detect_tools探测机器上可用的运行时/工具、install_tool安装缺失的运行时、resolve_time、retrieve_tool_output取回先前命令的输出、update_check/update_apply检查与应用 OpenHuman 更新等成员它们与文档列举的 12 个工具共用同一套安全与审计基础设施。适用场景什么时候该用它官方文档给出四类典型用途这也是这套工具族的设计意图工作流中的零碎环节——那些不属于任何更大工具族的边角步骤。帮我跑一下这条命令告诉我打印了什么——最直接的 shell 交互模式。时间感知行为——例如用户那边现在几点这类问题无需在提示词中硬编码时区假设直接交给current_time。让 Agent 在长任务跑完后主动通知你——通过pushover或schedule实现做完叫我。一个关键的使用建议来自文档的 See also文件系统重的工作优先用专用工具Coder 中的读写/编辑/patch 工具而不是shell循环性任务优先用 Cron Scheduling而不是一次性schedule。深入shell有界输出、退出码与三层安全防线shell是这套工具族里最重要的成员。其实现位于 src/openhuman/tools/impl/system/shell.rs几个关键设计值得展开1. 输出有界Bounded output单条 stdout 与 stderr 各自被截断到 1 MBMAX_OUTPUT_BYTES 1_048_576超出部分追加... [output truncated at 1MB]提示防止 OOM见 shell.rs 第 15-16 行与第 468-481 行。返回给模型历史记录的结果进一步限制在约 30k 字符max_result_size_chars避免find /、依赖安装这类超长输出撑爆上下文需要完整内容时Agent 可以用 head/tail/grep 跟进。工具描述明确提示只回传 stdout/stderr静默计算或只写文件的脚本不会返回任何内容必须主动print/echo或随后读取文件。2. 退出码与双流捕获Capture exit code失败时不再只丢 stderr而是通过 command_output.rs 统一渲染出Command failed (exit code N) stdout stderr 三段式结果并对两个高频不可重试码给出明确提示127命令/依赖未找到不在 PATH应安装或声明依赖不要盲目重试同一命令126权限不足或不可执行通常是沙箱限制应上报阻塞或请求提权其他退出码不附加提示避免对普通应用失败做多余解读。 这一设计解决了模型因丢失 exit code 与 stdout 而陷入无限重试的循环issue #4095。3. 环境隔离与安全子进程先env_clear()清空环境再只放行SAFE_ENV_VARS白名单PATH、HOME、TERM、LANG等系统功能性变量绝不包含 API Key 等机密防止机密泄漏到子进程CWE-200。将TMPDIR/TMP/TEMP重定向到 OpenHuman 的 scratch 目录/tmp/openhuman让python3 tempfile、mktemp等写入落到受信任的沙箱化位置而非全局共享的/tmp。每次调用写入审计日志CommandExecutionLogchanneltool:shell记录命令、是否获批、是否放行、是否成功、耗时审计失败只告警、不阻塞工具调用。4. 超时策略shell 没有默认超时——构建、测试套件、求解器等合法长命令可以跑数分钟issue #4023。只有调用方显式传入timeout_secs范围 1..3600时才启用墙钟超时0表示显式禁用。参数 schema 中还支持可选的category字段read/write/network/install/destructive作为只升不降escalate-only的风险自声明它能提高审批门槛如把 write 标记为 destructive但绝不会降低运行时依据命令分类得出的审批要求。5. 命令分类与审批门shell通过SecurityPolicy::classify_command对命令分类Write/Network/Destructive 类命令在完整权限模式下需要经过ApprovalGate人工审批Block 模式只读与结构化守卫在run_with_security内强制执行。此外还有跨 profile 写守卫check_cross_profile_command见 mod.rs 第 94-150 行对命令中形似路径的 token 与 profile 自己的工作区比对阻止一个 profile 修改另一个 profile 的工作区。6. 沙箱路由与托管运行时注入当 Agent 的SandboxMode为Sandboxed时shell会改用SandboxPolicy将命令路由到 Docker 或 OS 级沙箱后端执行且安全预检依旧生效。同时若托管 Node 已通过NodeBootstrap解析成功shell 会透明地在 PATH 前缀插入托管 Node 的bin/目录对python/pip/python3开头的命令则惰性解析托管 Python 运行时保证pip install foo与python3 -m foo落在同一个解释器上见 shell.rs 第 655-701 行。脚本执行三兄弟node_exec、npm_exec、python_exec这三者把跑脚本从 shell 中独立出来提供更精确的输入结构与托管运行时保障。node_execnode_exec.rs支持两种互斥输入模式模式参数实际调用内联代码inline_code: console.log(11)node -e code脚本路径script_path: scripts/run.js 可选argsnode path args...脚本路径相对于工作区解析逃逸工作区的路径会被文件系统助手拒绝。Node 运行时通过NodeBootstrap在首次调用时解析——如果 PATH 上没有兼容的node会自动下载并解压一份托管 Node 发行版后续调用复用缓存安装。输出同样只回传 stdout/stderr且单流上限 1MBtimeout_secs上限为 1800 秒同样无默认超时。npm_execnpm_exec.rs用于运行npm/pnpm/yarn脚本适合触发 package.json 中定义的build、test、lint等任务。python_exec运行 Python 3 代码片段或.py脚本与 shell 的 Python 注入共享同一套PythonBootstrap保证解释器与依赖一致。这三者连同shell统称 shell-family 工具共享 command_output.rs 的失败渲染与 1MB 输出截断确保失败信息形状在原生与沙箱两条路径上完全一致。时间与定时current_time、resolve_time与schedulecurrent_timecurrent_time.rs是一个只读工具让 Agent 在不 shell 出去调date的情况下获得现在的锚点用于提醒、调度、相对日期解析。返回结构包含utcRFC3339 格式 UTC 时间秒级精度local与local_timezone机器本地时间unix_secondsUnix 时间戳weekday本地星期几可选timezone参数IANA 名称如America/Los_Angeles、Asia/Kolkata传入后附加requested_timezone的转换结果与星期几时区名无效时返回requested_timezone_error提示不会让调用崩溃。工具描述中给出了最佳实践在调度提醒/cron 任务之前或用户提到10 分钟后明天今晚这类相对时间时先调用current_time获得时间锚点。schedule是文档中明确提到的一次性工具——do this once at time T适用于不需要重复执行的单次提醒或单次任务凡是需要周期性执行的官方文档明确指向 Cron Scheduling 家族cron_add/cron_list/cron_update/cron_remove/cron_run/cron_runs。源码中还存在resolve_time工具用于把3 小时后下周四这类自然语言相对时间解析为具体时间点。通知与存储pushover与insert_sql_recordpushoverpushover.rs让 Agent 在长任务完成时主动向你推送通知。它读取工作区.env文件中的PUSHOVER_TOKEN与PUSHOVER_USER_KEY两个凭据支持export前缀、引号包裹与行内#注释请求发送到https://api.pushover.net/1/messages.json请求超时 15 秒。参数包括必填的message与可选的title。这意味着你只需在工作区.env中配置好 Pushover 凭据Agent 就能做完叫你无需额外注册 MCP 服务或插件市场。insert_sql_record向 Agent 的结构化工作区 SQL 存储追加一行适合让 Agent 以结构化方式沉淀每次运行的元数据或结果后续可查询回溯。自省与配置workspace_state、tool_stats、proxy_configworkspace_state检查当前工作区——打开的文件、近期编辑、环境信息让 Agent 在动手前快速确认自己身处什么上下文。tool_stats会话级自省——本次会话已经用过哪些工具、各用了几次帮助 Agent 评估是否过度依赖某个工具或路径。proxy_config读取或修改出站请求的代理配置。这与 OpenHuman 的整体安全模型一致网络类工具默认走托管代理除非你显式切换到 SearXNG 等自托管路径见 native-tools README 中的说明。进阶lsp与语言服务器能力开关lsp工具允许 Agent 查询语言服务器获取定义definitions、引用references与诊断diagnostics信息。从 mod.rs 可以看到该工具受环境变量LSP_ENABLED_ENV控制lsp_capability_enabled函数负责判断开关说明 LSP 能力默认可能不启用需要显式开启后 Agent 才能用它做代码导航式查询。安全模型小结所有工具共享同一套边界无论文档表格里的哪个工具最终都落在 OpenHuman 统一的安全边界内native-tools README 总结为四条一致的错误处理零安装摩擦所有工具内置于进程无需插件市场、API Key 或注册 MCP 服务器所有输出免费经过 Smart Token Compression 压缩控制工具输出成本可预测的安全边界——文件系统工具遵守工作区作用域网络工具默认走托管代理。system模块还提供security_for_tool_contextmod.rs 第 68-88 行把会话的 WorkspaceDescriptor 提升为可读写 trusted root让 shell/python/node/npm 的路径解析与文件工具保持步调一致——既能读编辑一个 checkout也能在同一目录内构建、测试、提交。总结System Utilities 是 OpenHuman Agent 工具腰带上的瑞士军刀shell提供有界输出、退出码与多层安全护栏的命令执行node_exec/npm_exec/python_exec提供带托管运行时保障的脚本执行current_time/schedule支撑时间感知行为pushover让长任务主动通知你workspace_state/tool_stats/proxy_config/lsp则负责自省与配置。理解每个工具的输入结构、输出约束与安全边界你就能编写出更稳健的 Agent 工作流——把跑命令、做计算、看时间、发通知这些杂务放心交给这套内置工具族。【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
