@zhin.js/process-monitor 1.1.0 → 1.1.2

package/README.md

@@ -1,274 +1,53 @@
 # @zhin.js/process-monitor
 
-进程监控与重启通知插件，自动记录机器人重启情况并通知管理员。
+Zhin Plugin Runtime 的进程启动检测与状态查询插件。
 
-## 功能特性
+## 能力
 
-- ✅ **智能检测**：自动识别启动类型（首次启动/正常重启/异常崩溃）
-- ✅ **历史记录**：数据库持久化存储重启历史
-- ✅ **多渠道通知**：支持用户私聊、群组消息、邮件、Webhook
-- ✅ **统计分析**：重启次数、崩溃次数、累计运行时长
-- ✅ **健康检查**：定期检查进程状态（内存、运行时长）
-- ✅ **命令管理**：查看状态、历史记录、重置统计
+- 通过 `data/process-state.json` 记录启动 PID、启动时间、正常退出标记、重启次数和崩溃次数。
+- `process-status` Command 返回当前 PID、运行时长、内存和累计统计；Agent Tool 位于 `skills/process-monitor/tools/process-status/index.ts`，只在 Skill 激活后披露。
+- 可在首次启动、正常重启或异常崩溃后调用 HTTP Webhook。
+- 每个插件 owner 独立持有 `ProcessMonitor` 实例、状态和信号监听器；generation dispose 时自动清理监听器。
 
-## 安装
-
-### 方式一：从 npm 安装（发布后）
+## 安装与配置
 
 ```bash
 pnpm add @zhin.js/process-monitor
 ```
 
-### 方式二：本地开发
-
-如果你在 Zhin 项目中开发，插件已经在 workspace 中，直接在配置文件中启用即可：
-
-```yaml
-plugins:
-  - "@zhin.js/process-monitor"
-```
-
-## 配置
-
-在 `zhin.config.yml` 中配置：
-
 ```yaml
 plugins:
-  - "@zhin.js/process-monitor"
-
-process-monitor:
-  enabled: true                    # 是否启用
-  recordHistory: true              # 是否记录历史
-  maxHistoryRecords: 100           # 最大历史记录数
-  checkInterval: 60000             # 健康检查间隔（毫秒）
-  notifyOnStart: true              # 启动时通知
-  notifyOnRestart: true            # 重启时通知
-  notifyOnCrash: true              # 崩溃时通知
-  
-  notifyChannels:
-    # 方式一：发送给指定用户（私聊）
-    - type: user
-      target: "123456789"          # 用户 ID
-      platform: "icqq"             # 平台标识（可选，默认第一个适配器）
-    
-    # 方式二：发送到指定群组
-    - type: group
-      target: "987654321"          # 群组 ID
-      platform: "icqq"
-    
-    # 方式三：发送邮件（需配置邮件服务）
-    - type: email
-      target: "admin@example.com"
-    
-    # 方式四：Webhook 回调
-    - type: webhook
-      target: "https://your-webhook.com/notify"
-```
-
-## 使用
-
-### 查看状态
-
-```bash
-monitor --status
-# 或
-pm -s
-```
-
-输出示例：
-```
-📊 进程监控状态
-
-🚀 当前 PID: 12345
-⏱️  运行时长: 2天5小时30分钟
-💾 内存使用: 156 MB
-🔄 总重启: 3 次
-💥 崩溃: 1 次
-📈 累计运行: 15天8小时
-🖥️  主机: my-server
-💻 平台: linux-x64
-📦 Node: v23.7.0
-```
-
-### 查看重启历史
-
-```bash
-monitor --history        # 最近 10 条
-monitor --history 20     # 最近 20 条
-```
-
-输出示例：
-```
-📜 重启历史记录
-
-🔄 2026-02-05 14:30:25
-   原因: restart | PID: 12345
-   运行: 2天5小时30分钟
-
-💥 2026-02-03 09:15:10
-   原因: crash | PID: 11234
-   运行: 3小时45分钟
-
-🚀 2026-02-03 05:30:00
-   原因: start | PID: 11234
-```
-
-### 重置统计
-
-```bash
-monitor --reset
-```
-
-## 通知示例
-
-### 启动通知
-
+  process-monitor:
+    package: "@zhin.js/process-monitor"
+    config:
+      enabled: true
+      notifyOnStart: true
+      notifyOnRestart: true
+      notifyOnCrash: true
+      notifyChannels:
+        - type: webhook
+          target: "${PROCESS_MONITOR_WEBHOOK_URL}"
 ```
-🚀 【进程监控通知】
 
-📊 事件: 首次启动
-⏰ 时间: 2026-02-05 14:30:25
-🖥️  主机: my-server
-🔢 PID: 12345
-💻 平台: linux-x64
-📦 Node: v23.7.0
-💾 内存: 120 MB
-
-📈 统计:
-  • 总重启: 0 次
-  • 崩溃: 0 次
-  • 累计运行: 0秒
-```
-
-### 崩溃通知
-
-```
-💥 【进程监控通知】
-
-📊 事件: 异常崩溃
-⏰ 时间: 2026-02-05 18:45:30
-🖥️  主机: my-server
-🔢 PID: 12346
-💻 平台: linux-x64
-📦 Node: v23.7.0
-⏱️  运行时长: 4小时15分钟
-💾 内存: 256 MB
-
-📈 统计:
-  • 总重启: 3 次
-  • 崩溃: 1 次
-  • 累计运行: 15天8小时
-```
-
-## 工作原理
-
-### 启动检测
-
-1. **首次启动**：无历史状态文件
-2. **正常重启**：距上次启动 > 5 分钟
-3. **异常崩溃**：距上次启动 < 5 分钟
-
-### 数据持久化
-
-- **状态文件**：`data/process-state.json`
-  - 记录上次 PID、启动时间、统计数据
-  
-- **数据库表**：`process_restart_records`
-  - 完整的重启历史记录
-
-### 通知流程
-
-```
-进程启动 → 检测启动原因 → 记录数据库 → 判断是否通知 → 发送通知
-```
-
-## Webhook 数据格式
-
-POST 请求体：
+`notifyChannels` 当前只接受 `webhook`。Webhook 使用 `POST application/json`，正文包含：
 
 ```json
 {
   "event": "process_restart",
   "data": {
-    "timestamp": "2026-02-05T14:30:25.000Z",
-    "reason": "crash",
-    "exitCode": 1,
-    "uptime": 15300000,
-    "pid": 12346,
-    "hostname": "my-server",
+    "reason": "restart",
+    "timestamp": "2026-09-19T10:00:00.000Z",
+    "pid": 12345,
+    "hostname": "bot-host",
     "platform": "linux-x64",
-    "nodeVersion": "v23.7.0",
-    "memory": 256
+    "nodeVersion": "v24.0.0"
   },
   "stats": {
-    "restartCount": 3,
-    "crashCount": 1,
-    "totalUptime": 1324800000
+    "restartCount": 1,
+    "crashCount": 0,
+    "totalUptime": 3600000
   }
 }
 ```
 
-## 最佳实践
-
-### 生产环境配置
-
-```yaml
-process-monitor:
-  enabled: true
-  recordHistory: true
-  maxHistoryRecords: 200
-  checkInterval: 300000              # 5 分钟检查一次
-  notifyOnStart: true
-  notifyOnRestart: true
-  notifyOnCrash: true
-  
-  notifyChannels:
-    # 主管理员（私聊）
-    - type: user
-      target: "${ADMIN_USER_ID}"
-      platform: "icqq"
-    
-    # 运维群组
-    - type: group
-      target: "${OPS_GROUP_ID}"
-      platform: "icqq"
-    
-    # 监控系统 Webhook
-    - type: webhook
-      target: "${MONITORING_WEBHOOK_URL}"
-```
-
-### 配合系统服务
-
-与 systemd/launchd/NSSM 配合使用，实现：
-- **系统级监督**：守护进程崩溃自动重启
-- **应用级通知**：插件记录并通知管理员
-
-### 告警规则建议
-
-- 🟢 **正常重启**：记录即可，可选通知
-- 🟡 **频繁重启**：1小时内重启 > 3 次，需关注
-- 🔴 **持续崩溃**：5分钟内崩溃 > 2 次，立即处理
-
-## 故障排查
-
-### 通知未发送
-
-1. 检查配置：`notifyChannels` 是否正确
-2. 检查权限：机器人是否有发送消息权限
-3. 查看日志：是否有错误信息
-
-### 历史记录丢失
-
-1. 检查数据库连接
-2. 确认 `recordHistory: true`
-3. 查看 `data/process-state.json` 是否存在
-
-### 启动类型误判
-
-- 调整判断阈值（默认 5 分钟）
-- 检查系统时间是否正确
-
-## 许可证
-
-MIT License
+首次没有历史状态时记为 `start`；上次收到 `SIGTERM`/`SIGINT` 时记为 `restart`；未正常退出且五分钟内重新启动时记为 `crash`。

package/commands/{process-status.js → process-status/index.js}

@@ -1,9 +1,9 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { defineCommand } from 'zhin.js/command';
-import { formatProcessStatus } from "../lib/monitor.js";
+import { processMonitorToken } from "../../lib/monitor.js";
 export default defineCommand({
     description: '查看进程监控状态（PID、运行时长、重启统计）',
-    execute() {
-        return formatProcessStatus();
+    execute(context) {
+        return context.use(processMonitorToken).formatStatus();
     },
 });

package/commands/{process-status.ts → process-status/index.ts}

@@ -1,9 +1,9 @@
 import { defineCommand } from 'zhin.js/command';
-import { formatProcessStatus, type ProcessMonitorConfig } from '../src/monitor.js';
+import { processMonitorToken, type ProcessMonitorConfig } from '../../src/monitor.js';
 
 export default defineCommand<ProcessMonitorConfig>({
   description: '查看进程监控状态（PID、运行时长、重启统计）',
-  execute() {
-    return formatProcessStatus();
+  execute(context) {
+    return context.use(processMonitorToken).formatStatus();
   },
 });

package/lib/index.d.ts

@@ -1,3 +1,3 @@
-export { classifyStartup, formatProcessStatus, formatUptime, processState, resetProcessMonitorForTests, resolveProcessMonitorConfig, startProcessMonitor, startTime, } from './monitor.js';
-export type { NotifyChannel, ProcessMonitorConfig, ProcessState, StartupReason } from './monitor.js';
+export { classifyStartup, formatUptime, ProcessMonitor, processMonitorToken, resolveProcessMonitorConfig, } from './monitor.js';
+export type { NotifyChannel, ProcessMonitorConfig, ProcessMonitorOptions, ProcessState, ResolvedProcessMonitorConfig, StartupReason, } from './monitor.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,2BAA2B,EAC3B,2BAA2B,EAC3B,mBAAmB,EACnB,SAAS,GACV,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,EACZ,4BAA4B,EAC5B,aAAa,GACd,MAAM,cAAc,CAAC"}

package/lib/index.js

@@ -1,2 +1,2 @@
-export { classifyStartup, formatProcessStatus, formatUptime, processState, resetProcessMonitorForTests, resolveProcessMonitorConfig, startProcessMonitor, startTime, } from './monitor.js';
+export { classifyStartup, formatUptime, ProcessMonitor, processMonitorToken, resolveProcessMonitorConfig, } from './monitor.js';
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,2BAA2B,EAC3B,2BAA2B,EAC3B,mBAAmB,EACnB,SAAS,GACV,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,2BAA2B,GAC5B,MAAM,cAAc,CAAC"}

package/lib/monitor.d.ts

@@ -1,7 +1,6 @@
 export interface NotifyChannel {
-    type: 'user' | 'group' | 'webhook';
+    type: 'webhook';
     target: string;
-    platform?: string;
 }
 export interface ProcessMonitorConfig {
     enabled?: boolean;
@@ -13,31 +12,39 @@ export interface ProcessMonitorConfig {
 export interface ProcessState {
     lastPid?: number;
     lastStartTime?: number;
-    /** SIGTERM/SIGINT 正常退出时置 true，下次启动据此归为 restart 而非 crash。 */
     cleanExit?: boolean;
     restartCount: number;
     crashCount: number;
     totalUptime: number;
 }
-export declare let processState: ProcessState;
-export declare const startTime: number;
-export declare function resolveProcessMonitorConfig(raw: ProcessMonitorConfig | undefined): Required<Pick<ProcessMonitorConfig, 'enabled' | 'notifyOnStart' | 'notifyOnRestart' | 'notifyOnCrash'>> & {
+export type StartupReason = 'start' | 'restart' | 'crash';
+export type ResolvedProcessMonitorConfig = ReturnType<typeof resolveProcessMonitorConfig>;
+export declare const processMonitorToken: import("zhin.js").Token<ProcessMonitor>;
+export declare function resolveProcessMonitorConfig(raw: ProcessMonitorConfig | undefined): {
+    enabled: boolean;
     notifyChannels: NotifyChannel[];
+    notifyOnStart: boolean;
+    notifyOnRestart: boolean;
+    notifyOnCrash: boolean;
 };
 export declare function formatUptime(ms: number): string;
-export declare function formatProcessStatus(): string;
-export type StartupReason = 'start' | 'restart' | 'crash';
-/**
- * Classify this startup from persisted state.
- * - 同 PID（热重载，进程未退出）跳过判定，不算 restart/crash。
- * - 上次为 SIGTERM/SIGINT 正常退出（cleanExit）时归为 restart，即使间隔 <5min。
- */
 export declare function classifyStartup(state: ProcessState, currentPid: number, now?: number): {
     reason: StartupReason;
     uptime?: number;
 };
-/** Start monitoring once; returns disposer for lifecycle cleanup. */
-export declare function startProcessMonitor(rawConfig?: ProcessMonitorConfig): () => void;
-/** Test helper: reset module state without touching disk. */
-export declare function resetProcessMonitorForTests(): void;
+export interface ProcessMonitorOptions {
+    readonly stateFile?: string;
+    readonly now?: () => number;
+    readonly fetch?: typeof fetch;
+}
+/** One plugin owner's process statistics, persistence, notifications, and signal lifecycle. */
+export declare class ProcessMonitor {
+    #private;
+    constructor(config?: ProcessMonitorConfig, options?: ProcessMonitorOptions);
+    get state(): Readonly<ProcessState>;
+    get started(): boolean;
+    start(): void;
+    dispose(): void;
+    formatStatus(): string;
+}
 //# sourceMappingURL=monitor.d.ts.map

package/lib/monitor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"monitor.d.ts","sourceRoot":"","sources":["../src/monitor.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAID,eAAO,IAAI,YAAY,EAAE,YAIxB,CAAC;AAEF,eAAO,MAAM,SAAS,QAAa,CAAC;AAKpC,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,oBAAoB,GAAG,SAAS,GACpC,QAAQ,CACT,IAAI,CACF,oBAAoB,EACpB,SAAS,GAAG,eAAe,GAAG,iBAAiB,GAAG,eAAe,CAClE,CACF,GAAG;IAAE,cAAc,EAAE,aAAa,EAAE,CAAA;CAAE,CAQtC;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAU/C;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAgB5C;AAkGD,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,MAAM,EAClB,GAAG,SAAa,GACf;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAQ5C;AAuCD,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,SAAS,CAAC,EAAE,oBAAoB,GAAG,MAAM,IAAI,CA6BhF;AAED,6DAA6D;AAC7D,wBAAgB,2BAA2B,IAAI,IAAI,CAQlD"}
+{"version":3,"file":"monitor.d.ts","sourceRoot":"","sources":["../src/monitor.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;AAC1D,MAAM,MAAM,4BAA4B,GAAG,UAAU,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAE1F,eAAO,MAAM,mBAAmB,yCAG/B,CAAC;AAEF,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,oBAAoB,GAAG,SAAS;;;;;;EAQhF;AAED,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAS/C;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,MAAM,EAClB,GAAG,SAAa,GACf;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAO5C;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CAC/B;AAED,+FAA+F;AAC/F,qBAAa,cAAc;;gBAUb,MAAM,GAAE,oBAAyB,EAAE,OAAO,GAAE,qBAA0B;IAQlF,IAAI,KAAK,IAAI,QAAQ,CAAC,YAAY,CAAC,CAElC;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,KAAK,IAAI,IAAI;IAiBb,OAAO,IAAI,IAAI;IASf,YAAY,IAAI,MAAM;CA2EvB"}