@reskill/agent-aware-server

Agent-aware Server 提供 HTTP API 来收集用户交互行为和页面报错信息，并通过智能检测器主动发现问题。

English

功能特性

1. 数据收集

• 行为数据收集：从 http://localhost:4100 接收 SDK 上报的用户交互数据
• 错误数据收集：收集运行时错误、Promise 异常和 Console 错误

2. 智能检测器

重构后的架构包含两个独立的检测器：

BehaviorDetector（行为检测器）

• 检测消极的用户交互行为
• 触发条件：
  • 挫折指数 >= 70（Critical）
  • 挫折指数 50-70（Warning）
  • 愤怒点击 >= 3 次（Warning）
  • 死点击 >= 2 次（Warning）
• 输出文件：.agent-aware/alert/behavior.json

AlertDetector（错误检测器）

• 检测高危的运行时错误
• 触发条件：
  • 错误数 >= 1（Critical）
• 输出文件：.agent-aware/alert/error.json

3. 数据存储

所有数据统一存储到用户项目根目录的 .agent-aware/ 目录：

.agent-aware/
├── alert/               # 检测告警文件（供 Agent 监控）
│   ├── behavior.json    # 行为检测告警（最多 100 条历史）
│   └── error.json       # 错误检测告警（最多 100 条历史）
└── detail/              # 详细数据文件（供 HTTP API 查询）
    ├── behaviors.json   # 行为详细数据（最多 1000 条）
    └── errors.json      # 错误详细数据（最多 1000 条）

使用方式

安装（推荐项目级别开发依赖）

npm install --save-dev @reskill/agent-aware-server

启动服务

方式 1：使用 CLI（推荐）

# 默认启动（输出到当前目录）
npx agent-aware-server start

# 指定项目根目录
npx agent-aware-server start --project-root /path/to/project

# 使用环境变量（优先级最高）
USER_PROJECT_ROOT=/path/to/project npx agent-aware-server start

方式 2：编程方式

import { serve } from '@hono/node-server'
import { createHttpApi } from '@reskill/agent-aware-server/httpApi'
import { BehaviorStore } from '@reskill/agent-aware-server/store/behaviorStore'
import { ErrorStore } from '@reskill/agent-aware-server/store/errorStore'
import { BehaviorDetector } from '@reskill/agent-aware-server/detector/behaviorDetector'
import { AlertDetector } from '@reskill/agent-aware-server/detector/alertDetector'

const PORT = 4100
const PROJECT_ROOT = process.env.USER_PROJECT_ROOT || process.cwd()

// 所有组件统一使用 PROJECT_ROOT，数据存储在 .agent-aware/ 目录下
const store = new BehaviorStore(PROJECT_ROOT)
const errorStore = new ErrorStore(PROJECT_ROOT)
const behaviorDetector = new BehaviorDetector(PROJECT_ROOT)
const alertDetector = new AlertDetector(PROJECT_ROOT)

const app = createHttpApi(store, errorStore, behaviorDetector, alertDetector)

serve({
  fetch: app.fetch,
  port: PORT,
})

console.log(`Server running on http://localhost:${PORT}`)

HTTP API

行为相关

• POST /behaviors - 接收行为数据（SDK 上报）
• GET /behaviors - 查询行为数据
  • 参数：types（可选）、limit（可选）
• GET /behaviors/summary - 获取行为摘要
• GET /hotspots - 获取交互热点
  • 参数：limit（可选）
• DELETE /behaviors - 清空行为数据

错误相关

• POST /errors - 接收错误数据（SDK 上报）
• GET /errors - 查询错误数据
  • 参数：errorTypes（可选）、limit（可选）
• GET /errors/summary - 获取错误摘要
• DELETE /errors - 清空错误数据

健康检查

• GET /health - 健康检查

项目根目录配置

检测器输出文件的位置由以下优先级决定：

1. 环境变量 USER_PROJECT_ROOT（优先级最高）
2. 启动参数 --project-root
3. 默认值 process.cwd()（当前工作目录）

输出文件示例

告警文件保留历史记录（最多 100 条），新格式如下：

alert/behavior.json

{
  "version": "1.0",
  "alerts": [
    {
      "timestamp": "2026-01-30T10:30:00.000Z",
      "severity": "critical",
      "type": "frustration",
      "summary": "检测到用户挫折行为",
      "details": {
        "frustrationScore": 75,
        "rageClickCount": 5,
        "deadClickCount": 3,
        "totalInteractions": 50
      }
    }
  ]
}

alert/error.json

{
  "version": "1.0",
  "alerts": [
    {
      "timestamp": "2026-01-30T10:30:00.000Z",
      "severity": "critical",
      "type": "error",
      "summary": "检测到 3 个运行时错误",
      "details": {
        "totalErrors": 3,
        "runtimeErrorCount": 2,
        "unhandledRejectionCount": 1,
        "consoleErrorCount": 0,
        "recentErrors": [
          {
            "id": "uuid-1",
            "timestamp": 1738233000000,
            "errorType": "runtime",
            "message": "Cannot read property 'foo' of undefined"
          }
        ]
      }
    }
  ]
}

冷却期机制

为避免告警风暴，每个检测器都有 10 秒的冷却期：

• 同一检测器的文件写入间隔至少 10 秒
• 冷却期内的新问题会累积到下次写入

架构说明

基于 SPEC-SRV-005: Detector 架构重构

设计原则

1. 职责分离：BehaviorDetector 和 AlertDetector 各司其职
2. 异步检测：检测逻辑不阻塞 API 响应
3. 容错设计：文件写入失败不影响数据接收
4. 独立工作：每个检测器独立工作，互不干扰

开发

运行测试

npm test

构建

npm run build

License

MIT