wind_power_cal/.agents/skills/edge-python-agent/SKILL.md

name, description

name	description
edge-python-agent	edge_collector Python 独立 agent 开发规范。用于新增或修改 frpc agent、port forward agent、WiFi/4G 辅助进程、巡检脚本、数据分析脚本等 Python3 常驻或命令行工具时，统一配置、日志、systemd、资源占用、退出码和与 edge 主服务解耦要求。

edge_collector Python Agent

适用范围

• scripts/frp/start_*.py
• scripts/port_forward/start_*.py
• WiFi/4G 辅助脚本。
• 远程巡检和数据分析脚本。
• 需要 systemd 托管的 Python 常驻进程。

命名与位置

• 常驻启动脚本使用 start_ 前缀，保持现有风格。
• 按功能放到独立目录，例如 scripts/frp/、scripts/port_forward/。
• 不要把独立 agent 代码塞进 collector 或 configurator。

配置

• 配置文件放到运行目录的 config/ 或功能子目录。
• 支持配置缺失时生成默认文件，但不得覆盖已有配置。
• 动态配置必须被打包和同步规则排除，避免目标主机运行配置被覆盖。
• 密钥、Token、URL 不写死在代码中。

日志

• 使用 Python logging。
• 日志包含时间、级别、模块、关键状态。
• 不打印密钥、密码、Token。
• 高频循环日志要限流，避免 CPU/磁盘压力。
• 错误日志要保留具体原因，供前端展示更明确错误。

常驻进程要求

• 支持优雅退出 SIGTERM/SIGINT。
• 主循环有固定 sleep 或事件等待，禁止无休眠空转。
• 外部命令调用设置 timeout。
• 子进程必须回收。
• 网络请求必须设置连接和读取超时。
• 异常后退避重试，不要短时间无限重启。

systemd

服务文件应明确：

WorkingDirectory
ExecStart
Restart=on-failure
RestartSec
User
Environment

新增服务应独立，不替代已有 edge、frpc_agent 或其他服务，除非用户明确要求迁移。

CLI

建议支持：

--config <path>
--log-level <level>
--once
--dry-run

--once 适合调试和安装后验证。

验证

至少验证：

python3 -m py_compile scripts/<dir>/<file>.py
python3 scripts/<dir>/<file>.py --help

常驻服务验证：

systemctl status <service> --no-pager
journalctl -u <service> --since "5 min ago" --no-pager