---
name: edge-python-agent
description: 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

服务文件应明确：

```text
WorkingDirectory
ExecStart
Restart=on-failure
RestartSec
User
Environment
```

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

## CLI

建议支持：

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

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

## 验证

至少验证：

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

常驻服务验证：

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