From 939269b1c5c987360ac6ab31251747314c41cb2b Mon Sep 17 00:00:00 2001
From: LiuEnder <lchandmr.black@foxmail.com>
Date: Mon, 9 Mar 2026 19:57:24 +0800
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0readme.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 readme.md | 171 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 170 insertions(+), 1 deletion(-)

diff --git a/readme.md b/readme.md
index ec288cb..ec30e27 100644
--- a/readme.md
+++ b/readme.md
@@ -1,2 +1,171 @@
-# goldworm_js
+# 工商银行黄金价格监控与推送脚本
 
+这是一个基于 Node.js 的自动化脚本，用于定时监控中国工商银行（ICBC）官网的黄金递延（T+D）价格，并通过 ServerChan（方糖服务）将价格提醒推送至微信。脚本支持价格突破报警、多维度趋势分析、防骚扰冷却机制以及收盘价记录等功能。
+
+## ✨ 核心功能
+
+*   **定时抓取**：自动访问工商银行黄金价格页面，并使用 Puppeteer 解析实时价格。
+*   **智能推送**：
+    *   **变化触发**：当价格在设定时间窗口内波动超过阈值时推送。
+    *   **特殊价位**：可设置一组目标价位，当价格“穿过”任一目标价时立即推送特殊提醒。
+    *   **收盘推送**：在每日收盘时段（可配置）自动记录并推送收盘价。
+*   **趋势分析**：自动计算并报告一小时变化量、七日变化量，以及七日、十四日、二十八日的价格趋势（上涨/下跌/持平）。
+*   **灵活配置**：所有运行参数（如采样间隔、价格阈值、禁用时段、冷却时间等）均在脚本内 `CONFIG` 对象中集中管理，易于修改。
+*   **数据持久化**：自动将价格历史、收盘价、开盘价及推送状态保存至本地 JSON 文件。
+*   **多Key推送**：支持配置多个 ServerChan SendKey，向多个微信终端同时推送消息。
+
+## 🚀 快速开始
+
+### 1. 获取项目
+```bash
+git clone http://43.135.34.133:53000/LiuEnder/goldworm_js
+cd gold-price-monitor
+```
+
+### 2. 安装项目依赖
+```bash
+npm install
+```
+此步骤将安装 `puppeteer-core` 和 `serverchan-sdk`。
+
+### 3. 安装 Chrome/Chromium 浏览器
+**本脚本使用 `puppeteer-core`，它需要系统中已安装一个兼容的 Chrome 或 Chromium 浏览器，但不会自动下载。**
+
+*   **在 Ubuntu/Debian 系统上安装 Chromium**：
+    ```bash
+    sudo apt update
+    sudo apt install -y chromium-browser
+    ```
+*   **在 CentOS/RHEL 系统上安装 Chromium**：
+    ```bash
+    sudo yum install -y epel-release
+    sudo yum install -y chromium
+    ```
+*   对于其他操作系统，请从 https://www.google.com/chrome/ 或相应包管理器安装。
+
+安装后，需要找到浏览器的可执行文件路径。通常位于：
+- `/usr/bin/chromium-browser` (Chromium on Linux)
+- `/usr/bin/google-chrome` (Chrome on Linux)
+- `C:\Program Files\Google\Chrome\Application\chrome.exe` (Windows)
+
+### 4. 配置环境变量
+脚本运行需要两个关键环境变量：
+
+1.  **ServerChan 推送密钥 (`PUSH_KEYT`)**：
+    *   前往 https://sc3.ft07.com/ 登录并获取您的 `SendKey`。
+    *   **设置环境变量**（以下为Linux/macOS示例，永久生效请添加到 `~/.bashrc` 或 `~/.zshrc`）：
+    ```bash
+    export PUSH_KEYT="SCTxxxxxx...你的SendKey"
+    # 如果需要配置多个Key，用分号(;)分隔
+    # export PUSH_KEYT="Key1;Key2;Key3"
+    ```
+
+2.  **Chrome 浏览器路径 (`CHROME_PATH`)**（可选但推荐）：
+    *   如果您安装的浏览器不在脚本默认的 `/usr/bin/chromium-browser`，则必须设置此变量。
+    ```bash
+    export CHROME_PATH="/usr/bin/chromium-browser" # 或您的实际路径
+    # 例如在macOS上可能是：`export CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"`
+    ```
+
+### 5. 运行脚本
+```bash
+# 直接运行一次（测试用）
+node GoldPriceV6cooldown.js
+
+# 或使用 npm 脚本
+npm start
+```
+首次运行会创建数据文件 `gold_data.json` 并开始监控。检查控制台输出以确认运行成功。
+
+## ⚙️ 详细配置
+
+脚本的主要行为由文件顶部的 `CONFIG` 对象控制。您可以根据需要修改：
+
+```javascript
+const CONFIG = {
+  changeThresholdYuan: 1.0, // 触发普通推送的1小时价格变化阈值（元/克）
+  changeWindowMinutes: 60,  // 计算变化量的时间窗口（分钟）
+  sampleIntervalMinutes: 2, // 抓取价格的采样间隔（分钟）
+  pricePrecisionDigits: 2,  // 价格显示和计算的小数位数
+  enableTimedPush: true,    // 是否启用定时推送（变化触发和收盘推送）
+  enableSpecialAlert: true, // 是否启用特殊价格提醒
+  pushIntervalMinutes: 60,  // 普通推送的最小间隔（分钟），防骚扰
+  forcePushTest: false,     // 设为 true 可测试推送功能，运行一次即退出
+  disabledWindows: [12001500], // 禁止推送的时间段，格式 [开始时间结束时间]，如 12001500 表示 12:00-15:00
+  enableSpecialForcePush: true, // 特殊价格提醒是否忽略禁用时间段
+  enableSpecialBypassInterval: true, // 特殊价格提醒是否忽略推送间隔限制
+  coolDownMinutesForSinglePrice: 90, // 单个特殊价位的默认冷却时间（分钟）
+  resetOtherSpecialCooldownOnHit: true, // 触发一个特殊价位时，是否重置其他价位的冷却
+  // 为特定价位设置独立的冷却时间（分钟），未配置的价位使用默认值
+  specialPriceCoolDownMinutes: {
+    // “600”: 120, // 例如，当价格达到600元时，冷却时间设为120分钟
+  },
+};
+```
+
+**特殊价格目标设置**：
+在 `CONFIG` 对象下方，找到 `SPECIAL_PRICE_TARGETS` 数组，将您关心的价位填入。
+```javascript
+const SPECIAL_PRICE_TARGETS = [500, 520, 550]; // 例如，设置500、520、550元为目标价位
+```
+
+## 🏃 生产环境部署
+
+建议使用进程管理工具（如 **PM2**）来保证脚本持续运行。
+
+1.  **全局安装 PM2**：
+    ```bash
+    npm install -g pm2
+    ```
+
+2.  **使用 PM2 启动服务**（确保已在项目目录中）：
+    ```bash
+    # 启动并命名进程
+    pm2 start GoldPriceV6cooldown.js --name gold-monitor
+    # 设置开机自启（根据PM2提示操作）
+    pm2 startup
+    pm2 save
+    ```
+
+3.  **常用 PM2 命令**：
+    ```bash
+    pm2 logs gold-monitor      # 查看实时日志
+    pm2 status                 # 查看所有进程状态
+    pm2 stop gold-monitor     # 停止服务
+    pm2 restart gold-monitor  # 重启服务
+    pm2 monit                 # 打开监控面板
+    ```
+
+**通过 Crontab 或青龙面板调度**：
+如果您希望脚本在特定时间运行（而非持续后台运行），可以配置定时任务。例如，每天在交易时间运行：
+```bash
+# 每天9点到22点，每30分钟运行一次
+*/30 9-22 * * * cd /path/to/your/project && node GoldPriceV6cooldown.js >> /tmp/gold_monitor.log 2>&1
+```
+请注意，脚本内部已包含定时循环逻辑 (`sampleIntervalMinutes`)，如果通过外部Cron调用，通常只需调用一次，脚本会自行循环并在收盘时间退出。
+
+## 📁 文件说明
+
+- `GoldPriceV6cooldown.js` - 主脚本文件
+- `gold_data.json` - 运行时自动生成的数据文件（记录价格历史、推送状态等）
+- `package.json` - 项目依赖定义
+- `.gitignore` - Git忽略文件配置
+- `README.md` - 本说明文件
+
+## ⚠️ 重要注意事项
+
+1.  **合规使用**：本工具仅用于个人学习与技术研究。请合理设置请求频率，避免对工商银行服务器造成不必要的压力。使用请遵守网站相关规定。
+2.  **选择器更新**：如果目标网页结构改版，可能需要更新脚本中的 `PRICE_SELECTOR` 变量。您可以使用浏览器的开发者工具检查元素。
+3.  **推送频率限制**：免费版 ServerChan 有推送次数限制，请合理配置 `pushIntervalMinutes` 和 `coolDownMinutesForSinglePrice` 等参数。
+4.  **环境变量安全**：务必通过环境变量设置 `PUSH_KEYT`，切勿将其直接写入代码或提交至版本库。
+5.  **浏览器路径**：在非标准路径安装 Chrome/Chromium 时，**必须**正确设置 `CHROME_PATH` 环境变量，否则脚本将无法启动浏览器。
+
+## 🔧 故障排查
+
+- **错误：无法启动浏览器**：确认 `CHROME_PATH` 环境变量已设置且路径正确。也可尝试在脚本中直接修改 `puppeteer.launch` 的 `executablePath` 参数。
+- **无推送**：检查 `PUSH_KEYT` 环境变量是否设置正确；查看控制台日志确认价格是否成功抓取及触发条件是否满足。
+- **推送过于频繁**：调整 `CONFIG.pushIntervalMinutes` 和 `CONFIG.changeThresholdYuan` 参数。
+
+## 📄 开源协议
+
+本项目基于 GPLv3 协议开源。
\ No newline at end of file