复现已有算法

2026-07-14 15:43:18 +08:00
parent abebd2a683
commit 50b8111fd9
860 changed files with 182250 additions and 18 deletions
@@ -0,0 +1,88 @@
+---
+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
+```