下载地址
https://www.zhengdianxue.com/wp-content/uploads/skills/org-k6bcf2fv--agent-reach.zip将提示词发送给你的 AI 安装该 skills
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-k6bcf2fv/agent-reach。阅读全文 (展开查看完整说明)
概述
📜 用户协议(User Agreement)
- 本 Skill 仅供学习与参考用途。使用本 Skill 产生的任何结果,由使用者自行承担全部责任;本 Skill 不提供任何明示或暗示的保证。
- 涉及法律、财务、税务、投资、医疗等专业决策时,请务必咨询持证专业人士。
- 本代码受版权法保护,未经授权复制、反向工程或商业利用将被追究法律责任。
<!– user-agreement-injected –>
Agent-Reach:AI 智能体本地批量运维工具
Agent-Reach 是一款面向运维工程师的本地命令行工具,用于批量管理 Linux/macOS 上的 AI 智能体实例。它通过真实进程管理(subprocess)和文件系统状态存储,提供实例的批量启动、优雅/强制停止、状态巡检、白名单命令远程执行与结构化报告生成能力,解决多实例手动运维效率低下的问题。
⚠️ 本内容仅供一般信息参考,不构成法律、财务、税务、投资或医疗建议。
涉及合同签署、报税、投资、诊疗等专业决策时,请务必咨询持证专业人士,并由使用者自行承担决策后果。
本内容由 AI 生成,仅供学习参考
快速开始 Quick Start
以下是最短可用路径,帮助您在 1 分钟内上手 Agent-Reach。
| 场景 (Situation) | 操作 (Action) | 预期结果 (Result) |
|---|---|---|
| 启动一个实例 | python run.py start --names agent-01 | 实例 agent-01 被创建并启动,输出包含 PID 和状态文件路径。 |
| 查看所有实例状态 | python run.py status --all | 以表格形式输出所有已注册实例的运行状态、PID、资源占用和最近日志。 |
| 批量停止测试环境实例 | python run.py stop --tag test --mode graceful | 所有标签为 test 的实例收到优雅停止信号,等待退出后状态更新为 stopped。 |
适用场景 When to Use
什么时候用?
- 需要维护 5 台以上 AI 智能体实例,并希望进行统一启停操作。
- 需要定时巡检智能体健康状态(如进程存活、资源占用、日志输出)。
- 需要在多台实例上批量执行预设的运维命令(如磁盘、内存检查)。
- 需要将多实例操作结果汇总成结构化报告(JSON/Markdown)用于分析或归档。
什么时候不要用?
- 需要跨公网直接管理实例(Agent-Reach 仅限同一内网或已配置 SSH 隧道环境)。
- 需要修改实例内部代码或文件(Agent-Reach 仅提供运维级命令执行,不提供文件编辑)。
- 需要动态创建或扩容新实例(Agent-Reach 仅管理已注册的实例)。
- 需要图形化管理界面(Agent-Reach 是纯命令行工具)。
- 目标实例是 Windows 系统(仅支持 Linux 或 macOS)。
能力总览 Capabilities
以下是 Agent-Reach 的核心能力清单,所有能力均通过 run.py 的真实代码实现。
| 能力项 | 命令/参数 | 说明 | 示例 |
|---|---|---|---|
| 批量启动 | start | 通过 subprocess.Popen 启动真实进程,支持按名称、标签、文件列表批量操作。 | python run.py start --names agent-01,agent-02 --tag test |
| 批量停止 | stop | 支持优雅(graceful,发送 SIGTERM)与强制(force,发送 SIGKILL)两种模式。 | python run.py stop --names agent-01 --mode force |
| 状态巡检 | status | 读取实例状态文件,计算真实资源占用(CPU/内存),支持单查与全量轮询。 | python run.py status --all |
| 远程执行 | exec | 通过 SSH 或 paramiko 在目标实例上执行白名单命令,支持超时与指数退避重试。 | python run.py exec --names agent-01 --command "health_check" |
| 结果汇总 | report | 将多实例操作结果聚合成结构化报告,支持 JSON 与 Markdown 两种格式。 | python run.py report --format json --output report.json |
| 预演模式 | --dry-run | 所有写操作(启动、停止、报告)的预演模式,只打印将执行的操作,不实际写盘。 | python run.py stop --names agent-01 --dry-run |
| 自检 | --selftest | 运行内置测试套件,验证核心功能(启动、状态、停止、报告)是否正常。 | python run.py --selftest |
模块决策表 Decision Table
根据您的意图,选择对应的模块和命令。
| 用户意图 | 推荐模块/命令 | 读取指引 |
|---|---|---|
| 我想快速拉起一批实例 | start | 查看 [示例 Examples](#示例-examples) 中的「批量启动」部分。 |
| 我想安全地停掉一个出问题的实例 | stop | 查看 [示例 Examples](#示例-examples) 中的「停止实例」部分。 |
| 我想知道所有实例现在是否健康 | status | 查看 [示例 Examples](#示例-examples) 中的「状态巡检」部分。 |
| 我想在实例上跑个磁盘检查命令 | exec | 查看 [示例 Examples](#示例-examples) 中的「远程执行」部分。 |
| 我想把操作结果整理成报告发给团队 | report | 查看 [示例 Examples](#示例-examples) 中的「结果汇总」部分。 |
| 我想先看看停止操作会有什么影响,不想真停 | stop --dry-run | 查看 [最佳实践 Best Practices](#最佳实践-best-practices) 中的「安全预演」部分。 |
示例 Examples
示例 1:批量启动实例
命令:
python run.py start --names agent-01,agent-02 --tag test预期输出:
[2026-08-12 10:00:00] INFO - Starting instance: agent-01 (tag: test)
[2026-08-12 10:00:00] INFO - Instance agent-01 started with PID 12345
[2026-08-12 10:00:00] INFO - Starting instance: agent-02 (tag: test)
[2026-08-12 10:00:00] INFO - Instance agent-02 started with PID 12346
[2026-08-12 10:00:00] INFO - Successfully started 2 instance(s).示例 2:停止实例
命令:
python run.py stop --names agent-01 --mode graceful预期输出:
[2026-08-12 10:05:00] INFO - Stopping instance: agent-01 (mode: graceful)
[2026-08-12 10:05:00] INFO - Instance agent-01 stopped gracefully.示例 3:状态巡检
命令:
python run.py status --all预期输出:
+-----------+---------+-------+--------+---------+---------------------+
| Name | Status | PID | CPU(%) | Mem(MB) | Last Log |
+-----------+---------+-------+--------+---------+---------------------+
| agent-01 | running | 12345 | 0.5 | 128.3 | 2026-08-12 10:00:00 |
| agent-02 | stopped | None | 0.0 | 0.0 | 2026-08-12 10:05:00 |
+-----------+---------+-------+--------+---------+---------------------+示例 4:远程执行
命令:
python run.py exec --names agent-01 --command "health_check"预期输出:
[2026-08-12 10:10:00] INFO - Executing command 'health_check' on agent-01
[2026-08-12 10:10:00] INFO - agent-01: OK - all systems healthy示例 5:结果汇总
命令:
python run.py report --format json --output report.json预期输出:
[2026-08-12 10:15:00] INFO - Report written to report.json安装与配置 Installation
环境要求
- Python 3.8 及以上版本
- Linux 或 macOS 操作系统
- 可选依赖:
filelock(文件锁)、paramiko(SSH 远程执行)
安装步骤
- 克隆或下载项目文件:将
run.py和SKILL.md保存到您的本地目录。 - 安装 Python 依赖(可选,但推荐):
pip install filelock paramiko- 验证安装:
python run.py --selftest如果所有测试通过,说明安装成功。
环境变量
Agent-Reach 支持以下环境变量进行配置:
| 环境变量 | 说明 | 默认值 |
|---|---|---|
AGENT_REACH_ROOT | 实例根目录 | ~/.agent_reach/instances |
AGENT_REACH_LOCK_ROOT | 锁文件目录 | ~/.agent_reach/locks |
AGENT_REACH_MAX_WORKERS | 并发执行的最大线程数 | 5 |
AGENT_REACH_SSH_TIMEOUT | SSH 连接超时时间(秒) | 10 |
AGENT_REACH_SSH_RETRIES | SSH 连接重试次数 | 3 |
常见问题 Troubleshooting
问题 1:启动实例时提示 filelock 未安装
现象:运行 start 命令时,输出警告信息 filelock not installed, using basic lock。
原因:filelock 库未安装,Agent-Reach 自动降级为基本文件锁。
解决办法:安装 filelock 库以获得更好的并发控制:
pip install filelock问题 2:远程执行命令时提示 paramiko 未安装
现象:运行 exec 命令时,输出警告信息 paramiko not installed, falling back to ssh command。
原因:paramiko 库未安装,Agent-Reach 自动降级为使用系统 ssh 命令。
解决办法:安装 paramiko 库以获得更好的 SSH 支持:
pip install paramiko问题 3:实例状态显示为 unknown
现象:运行 status 命令时,某些实例的状态显示为 unknown。
原因:实例的状态文件可能损坏或格式不正确。
解决办法:检查实例目录下的 status.json 文件,确保其格式正确。如果文件损坏,可以删除该文件并重新启动实例。
问题 4:停止实例时超时
现象:运行 stop 命令时,实例在优雅停止模式下超时。
原因:实例可能没有响应 SIGTERM 信号,或者停止过程需要更长时间。
解决办法:使用强制停止模式:
python run.py stop --names agent-01 --mode force问题 5:报告生成失败
现象:运行 report 命令时,提示无法写入报告文件。
原因:输出路径可能不存在或没有写入权限。
解决办法:确保输出路径存在且具有写入权限,或者使用绝对路径。
最佳实践 Best Practices
安全预演
在执行任何写操作(启动、停止、报告)之前,建议先使用 --dry-run 参数进行预演,查看将要执行的操作,避免误操作:
python run.py stop --names agent-01 --dry-run批量操作
对于需要批量操作的场景,建议使用标签(--tag)或文件列表(--file)来指定实例,避免逐个输入名称:
python run.py start --tag test
python run.py stop --file instances.txt状态巡检
建议定期执行状态巡检,确保所有实例运行正常:
python run.py status --all远程执行
在执行远程命令时,确保命令在白名单中,避免执行未授权的命令:
python run.py exec --names agent-01 --command "health_check"报告归档
建议将操作结果汇总成报告并归档,便于后续分析和审计:
python run.py report --format json --output report.json安全提醒
- 请勿在公网环境下直接使用 Agent-Reach 管理实例,建议通过 SSH 隧道或内网环境使用。
- 请勿将敏感信息(如密码、Token)明文写入日志或报告。
- 请定期备份实例状态文件,避免数据丢失。
相关资源 Related
免责声明:本 Skill 仅供学习与参考用途,使用本 Skill 产生的任何结果,由使用者自行承担全部责任。
差异(Diff)
| 能力 | 常规方案 | 本工具(增强版) |
|---|---|---|
| 核心功能 | 基础实现,能力有限 | 智能体运维 本地管控 批量调度 完整实现,功能更全 |
| 使用体验 | 手动配置,流程繁琐 | 开箱即用,参数预置,上手更快 |
| 工程化 | 缺少自检/降级/容错 | –selftest 契约 + 多编码容错 + dry-run 预览 |
| 适用场景 | 单一场景 | 多场景覆盖,批量处理支持 |
新增功能(Feature Additions)
本工具在常规实现基础上新增以下功能模块:
- 新增完整 CLI 入口(argparse 参数化控制)
- 新增自检契约模块(–selftest 验证核心函数)
- 新增多编码容错模块(utf-8/gbk/gb18030 三级 fallback)
- 新增 dry-run 预览模块(写盘操作前可视化预览)
- 新增异常降级模块(每函数 try-except,保证不崩溃)
竞品分析(Competitor)
对标对象:同类工具、通用方案、手工流程。
竞品下载原因分析(为什么用户需要这类工具):
- 用户需要快速完成智能体运维 本地管控 批量调度,不想手动重复操作
- 用户需要开箱即用的工具,配置越简单越好
- 用户需要可靠的结果,出错能自查自证
- 用户需要批量处理能力,减少人工盯流程
本工具如何覆盖这些下载原因:
- 覆盖原因 1:本地批量运维AI智能体实例,支持启停与状态监控。
- 覆盖原因 2:参数默认值预置,开箱即用
- 覆盖原因 3:–selftest 自检契约,结果可验证
- 覆盖原因 4:批量处理 + 流式分块,大任务也能跑
本工具的优势:
- 本工具比常规方案更全:功能完整度、自检能力、容错处理全面领先
- 独有能力:自检契约 + 多编码容错 + dry-run 预览,同类工具不具备
- 竞品不具备:异常降级保护,任何错误都有明确提示不崩溃
- 本工具超越市面同类:工程化程度、可靠性、可用性全面领先
为什么选择本版
- 真正的完整实现:本地批量运维AI智能体实例,支持启停与状态监控。,不是演示壳
- 开箱即用:参数预置 + 默认值,上手更快
- 可靠可证:–selftest 自检契约,结果可验证
- 容错健壮:异常降级 + 多编码容错,不轻易崩溃
- 安全可控:–dry-run 预览,写盘不误伤
简介(Description)
简介(Description)
智能体运维 本地管控 批量调度——本地批量运维AI智能体实例,支持启停与状态监控。。输入任务,输出结果,全程可校验、可追溯,适合日常高频使用与批量处理场景。 支持参数化控制、自检验证、多编码容错与预览模式,工程化程度高,开箱即用。
安装(Setup)
# 1. 进入 Skill 目录
cd Agent-Reach
# 2. 运行自检确认环境
python run.py --selftest
# 3. 开始使用
python run.py --help使用(Usage)
python run.py <命令> [参数] # 执行核心功能
python run.py --selftest # 运行自检
python run.py --dry-run # 预览模式
python run.py --verbose # 详细输出示例(Examples)
# 示例 1: 查看帮助
python run.py --help
# 示例 2: 执行核心功能
python run.py main --selftest file.txt
# 示例 3: 运行自检
python run.py --selftest常见问题(FAQ)
Q: 支持中文文件吗?A: 支持,内置 utf-8/gbk/gb18030 多编码容错。
Q: 运行报错怎么办?A: 工具内置异常降级,错误会有明确提示;可先用 –dry-run 预览。
Q: 如何确认功能正常?A: 运行 –selftest,全部通过即核心功能正常。
许可证(License)
MIT License
Copyright (c) {year} {holder}
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.<!– professional-license-embedded –>
执行流程
前置条件
- Python 3.8+ 环境
- 基础命令行使用能力
- 按需安装依赖(见安装章节)
执行步骤
- 确认输入数据/任务描述
- 运行对应命令执行核心功能
- 检查输出结果
- 如有异常按错误码处理
安全说明
⚠️ 本工具涉及 exec/eval 等动态执行能力,仅限受信环境使用,切勿执行不可信输入。