Worker 服务

worker 服务是一个长期运行的 HTTP API，由 Express.js 构建，并由 Bun 原生管理。它通过 Claude Agent SDK 独立处理观察数据，而与钩子执行分开，以防止超时问题。

概览

技术：Express.js HTTP 服务器
运行时：Bun（如果缺失则自动安装）
进程管理器：通过 ProcessManager 进行本地 Bun 进程管理
端口：固定端口 37777（可通过 CLAUDE_MEM_WORKER_PORT 配置）
地点: src/services/worker-service.ts
已构建输出: plugin/scripts/worker-service.cjs
模型：可通过 CLAUDE_MEM_MODEL 环境变量配置（默认值：sonnet）

REST API 端点

该 Worker 服务暴露了 22 个 HTTP 端点，分为六类：

查看器和健康端点

1. 查看器界面

GET /

目的：提供基于网页的查看器界面（v5.1.0）

响应：包含嵌入式 React 应用程序的 HTML 页面

特点：

实时内存流可视化
无限滚动分页
项目筛选
基于 SSE 的实时更新
主题切换（浅色/深色模式）自 v5.1.2 起

2. 健康检查

GET /health

目的：检查 Worker 健康状态

回应:

json

{
  "status": "ok",
  "uptime": 12345,
  "port": 37777
}

3. 服务器发送事件流

GET /stream

目的：为观众界面提供实时更新

响应：带有事件的 SSE 流：

observation-created：已添加新观察
session-summary-created：已生成新摘要
user-prompt-created: 新提示已记录

活动形式：

event: observation-created
data: {"id": 123, "title": "...", ...}

数据检索端点

4. 获取提示

GET /api/prompts?project=my-project&limit=20&offset=0

目的：检索分页的用户提示

查询参数:

project（可选）：按项目名称筛选
limit（默认值：20）：结果数量
offset（默认值：0）：分页偏移量

回应:

json

{
  "prompts": [{
    "id": 1,
    "session_id": "abc123",
    "prompt": "User's prompt text",
    "prompt_number": 1,
    "created_at": "2025-11-06T10:30:00Z"
  }],
  "total": 150,
  "hasMore": true
}

5. 获取观察

GET /api/observations?project=my-project&limit=20&offset=0

目的：检索分页观测

查询参数:

project（可选）：按项目名称筛选
limit（默认值：20）：结果数量
offset（默认值：0）：分页偏移量

回应:

json

{
  "observations": [{
    "id": 123,
    "title": "Fix authentication bug",
    "type": "bugfix",
    "narrative": "...",
    "created_at": "2025-11-06T10:30:00Z"
  }],
  "total": 500,
  "hasMore": true
}

6. 获取摘要

GET /api/summaries?project=my-project&limit=20&offset=0

目的：检索分页的会话摘要

查询参数:

project（可选）：按项目名称筛选
limit（默认值：20）：结果数量
offset（默认值：0）：分页偏移量

回应:

json

{
  "summaries": [{
    "id": 456,
    "session_id": "abc123",
    "request": "User's original request",
    "completed": "Work finished",
    "created_at": "2025-11-06T10:30:00Z"
  }],
  "total": 100,
  "hasMore": true
}

7. 通过ID获取观察

GET /api/observation/:id

目的：通过其ID检索单个观察值

路径参数：

id（必填）：观察ID

回应:

json

{
  "id": 123,
  "sdk_session_id": "abc123",
  "project": "my-project",
  "type": "bugfix",
  "title": "Fix authentication bug",
  "narrative": "...",
  "created_at": "2025-11-06T10:30:00Z",
  "created_at_epoch": 1730886600000
}

错误响应 (404)：

json

{
  "error": "Observation #123 not found"
}

8. 通过ID获取观察（批量）

POST /api/observations/batch

目的：通过一次请求根据其ID检索多个观测

请求正文:

json

{
  "ids": [123, 456, 789],
  "orderBy": "date_desc",
  "limit": 10,
  "project": "my-project"
}

请求体参数：

ids（必填）：观测ID数组
orderBy（可选）：排序顺序 - date_desc 或 date_asc（默认：date_desc）
limit（可选）：返回的最大结果数量
project（可选）：按项目名称筛选

回应:

json

[
  {
    "id": 789,
    "sdk_session_id": "abc123",
    "project": "my-project",
    "type": "feature",
    "title": "Add new feature",
    "narrative": "...",
    "created_at": "2025-11-06T12:00:00Z",
    "created_at_epoch": 1730891400000
  },
  {
    "id": 456,
    "sdk_session_id": "abc124",
    "project": "my-project",
    "type": "bugfix",
    "title": "Fix authentication bug",
    "narrative": "...",
    "created_at": "2025-11-06T10:30:00Z",
    "created_at_epoch": 1730886600000
  }
]

错误响应:

400 Bad Request：{"error": "ids must be an array of numbers"}
400 Bad Request：{"error": "All ids must be integers"}

用例：该端点由 get_observations MCP 工具使用，用于在单个请求中高效检索多个观测，从而避免多个单独请求的开销。

9. 通过ID获取会话

GET /api/session/:id

目的：通过其 ID 检索单个会话

路径参数：

id（必填）：会话ID

回应:

json

{
  "id": 456,
  "sdk_session_id": "abc123",
  "project": "my-project",
  "request": "User's original request",
  "completed": "Work finished",
  "created_at": "2025-11-06T10:30:00Z"
}

错误响应 (404)：

json

{
  "error": "Session #456 not found"
}

10. 通过ID获取提示

GET /api/prompt/:id

目的：通过其 ID 检索单个用户提示

路径参数：

id（必填）：提示 ID

回应:

json

{
  "id": 1,
  "session_id": "abc123",
  "prompt": "User's prompt text",
  "prompt_number": 1,
  "created_at": "2025-11-06T10:30:00Z"
}

错误响应 (404)：

json

{
  "error": "Prompt #1 not found"
}

12. 获取统计数据

GET /api/stats

目的：按项目获取数据库统计信息

回应:

json

{
  "byProject": {
    "my-project": {
      "observations": 245,
      "summaries": 12,
      "prompts": 48
    },
    "other-project": {
      "observations": 156,
      "summaries": 8,
      "prompts": 32
    }
  },
  "total": {
    "observations": 401,
    "summaries": 20,
    "prompts": 80,
    "sessions": 20
  }
}

13. 获取项目

GET /api/projects

目的：从观测中获取不同项目的列表

回应:

json

{
  "projects": ["my-project", "other-project", "test-project"]
}

设置端点

14. 获取设置

GET /api/settings

目的：获取用户设置

回应:

json

{
  "sidebarOpen": true,
  "selectedProject": "my-project",
  "theme": "dark"
}

15. 保存设置

POST /api/settings

目的：保存用户设置

请求正文:

json

{
  "sidebarOpen": false,
  "selectedProject": "other-project",
  "theme": "light"
}

回应:

json

{
  "success": true
}

队列管理端点

16. 获取待处理队列状态

GET /api/pending-queue

目的：查看当前处理队列状态并识别卡住的消息

回应:

json

{
  "queue": {
    "messages": [
      {
        "id": 123,
        "session_db_id": 45,
        "claude_session_id": "abc123",
        "message_type": "observation",
        "status": "pending",
        "retry_count": 0,
        "created_at_epoch": 1730886600000,
        "started_processing_at_epoch": null,
        "completed_at_epoch": null
      }
    ],
    "totalPending": 5,
    "totalProcessing": 2,
    "totalFailed": 0,
    "stuckCount": 1
  },
  "recentlyProcessed": [
    {
      "id": 122,
      "session_db_id": 44,
      "status": "processed",
      "completed_at_epoch": 1730886500000
    }
  ],
  "sessionsWithPendingWork": [44, 45, 46]
}

状态定义:

pending：消息已排队，尚未处理
processing：消息当前正在被 SDK 代理处理
processed：消息发送成功
failed：消息在最大重试次数（默认3次）后发送失败

卡住检测：状态为 processing 超过 5 分钟的消息将被视为卡住，并计入 stuckCount

用例：在工作进程崩溃或重启后检查队列健康状况，以识别未处理的观测数据

17. 触发手动恢复

POST /api/pending-queue/process

目的：手动触发待处理队列的处理（取代 v5.x 中的自动恢复）

请求正文:

json

{
  "sessionLimit": 10
}

请求体参数：

sessionLimit（可选）：要处理的最大会话数（默认值：10，最大值：100）

回应:

json

{
  "success": true,
  "totalPendingSessions": 15,
  "sessionsStarted": 10,
  "sessionsSkipped": 2,
  "startedSessionIds": [44, 45, 46, 47, 48, 49, 50, 51, 52, 53]
}

响应字段:

totalPendingSessions：数据库中有未处理消息的总会话数
sessionsStarted：我们开始处理此请求的会话数量
sessionsSkipped：会话已在积极处理中（未重新启动）
startedSessionIds：已启动会话的数据库 ID

行为：

处理最多 sessionLimit 个有待处理工作的会话
跳过已经在处理中会话（防止重复代理）
为每个会话启动非阻塞 SDK 代理
立即返回状态（处理在后台继续进行）

用例：在Worker 进程崩溃或自动恢复被禁用时，手动恢复卡住的观测

恢复策略说明：从 v5.x 版本开始，工作节点启动时的自动恢复默认是禁用的。用户必须使用此端点或 CLI 工具 (bun scripts/check-pending-queue.ts) 手动触发恢复，以保持对重新处理的明确控制。

会话管理端点

19. 初始化会话

POST /sessions/:sessionDbId/init

请求正文:

json

{
  "sdk_session_id": "abc-123",
  "project": "my-project"
}

回应:

json

{
  "success": true,
  "session_id": "abc-123"
}

20. 添加观察

POST /sessions/:sessionDbId/observations

请求正文:

json

{
  "tool_name": "Read",
  "tool_input": {...},
  "tool_result": "...",
  "correlation_id": "xyz-789"
}

回应:

json

{
  "success": true,
  "observation_id": 123
}

21. 生成摘要

POST /sessions/:sessionDbId/summarize

请求正文:

json

{
  "trigger": "stop"
}

回应:

json

{
  "success": true,
  "summary_id": 456
}

22. 会话状态

GET /sessions/:sessionDbId/status

回应:

json

{
  "session_id": "abc-123",
  "status": "active",
  "observation_count": 42,
  "summary_count": 1
}

23. 删除会话

DELETE /sessions/:sessionDbId

回应:

json

{
  "success": true
}

注意：从 v4.1.0 开始，清理钩子不再调用此端点。会话将被标记为完成而不是删除，以允许Worker 进程优雅关闭。

面包过程管理

概览

该 Worker 由本地 ProcessManager 类管理，该类负责：

使用 Bun 运行时生成进程
在 ~/.claude-mem/worker.pid 进行 PID 文件跟踪
带自动重试的健康检查
使用 SIGTERM/SIGKILL 回退的优雅关闭

命令

bash

# Start worker (auto-starts on first session)
npm run worker:start

# Stop worker
npm run worker:stop

# Restart worker
npm run worker:restart

# View logs
npm run worker:logs

# Check status
npm run worker:status

自动启动行为

当 SessionStart 钩子触发时，Worker 服务会自动启动。手动启动是可选的。

面包要求

运行Worker 服务需要 Bun。如果未安装 Bun，smart-install 脚本将在第一次运行时自动安装它：

Windows: powershell -c "irm bun.sh/install.ps1 | iex"
macOS/Linux: curl -fsSL https://bun.sh/install | bash

你也可以通过以下方式手动安装：

winget install Oven-sh.Bun（Windows）
brew install oven-sh/bun/bun（macOS）

Claude 代理 SDK 集成

Worker 服务将观测结果路由到 Claude Agent SDK 以进行 AI 驱动的处理：

处理流程

观察队列：观测结果累积在内存中
SDK 处理：通过 Agent SDK 发送给 Claude 的观察结果
XML 解析：解析响应以获取结构化数据
数据库存储：处理后的观测数据存储在 SQLite 中

SDK组件

提示 (src/sdk/prompts.ts): 构建 XML 结构的提示
解析器 (src/sdk/parser.ts): 解析 Claude 的 XML 响应
Worker 进程 (src/sdk/worker.ts): 主 SDK 代理循环

模型配置

通过环境变量设置用于处理的 AI 模型：

bash

可用的速记模型（更新到最新版本）:

haiku - 快速、经济高效
sonnet - 平衡（默认）
opus - 最有能力

端口分配

该 Worker 使用固定端口（默认端口为 37777）进行一致的通信：

默认：端口 37777
覆盖：设置 CLAUDE_MEM_WORKER_PORT 环境变量
端口文件：${CLAUDE_PLUGIN_ROOT}/data/worker.port 跟踪当前端口

如果端口37777被占用，工作进程将无法启动。通过环境变量设置自定义端口。

数据存储

Worker 服务将数据存储在用户数据目录中：

~/.claude-mem/
├── claude-mem.db           # SQLite database (bun:sqlite)
├── worker.pid              # PID file for process tracking
├── settings.json           # User settings
└── logs/
    └── worker-YYYY-MM-DD.log  # Daily rotating logs

错误处理

该 Worker 实现了优雅降级：

数据库错误：已记录但不会导致服务崩溃
SDK 错误：使用指数退避重试
网络错误：已记录并跳过
无效输入：已验证并以错误响应被拒绝

性能

异步处理：观察结果以异步方式处理
内存队列：快速观测累积
批量处理：多个观测一起处理
连接池：SQLite 连接可重复使用

故障排除

有关常见问题及解决方法，请参见 Troubleshooting - Worker Issues。

Worker 服务 ​

概览 ​

REST API 端点 ​

查看器和健康端点 ​

1. 查看器界面 ​

2. 健康检查 ​

3. 服务器发送事件流 ​

数据检索端点 ​

4. 获取提示 ​

5. 获取观察 ​

6. 获取摘要 ​

7. 通过ID获取观察 ​

8. 通过ID获取观察（批量） ​

9. 通过ID获取会话 ​

10. 通过ID获取提示 ​

12. 获取统计数据 ​

13. 获取项目 ​

设置端点 ​

14. 获取设置 ​

15. 保存设置 ​

队列管理端点 ​

16. 获取待处理队列状态 ​

17. 触发手动恢复 ​

会话管理端点 ​

19. 初始化会话 ​

20. 添加观察 ​

21. 生成摘要 ​

22. 会话状态 ​

23. 删除会话 ​

面包过程管理 ​

概览 ​

命令 ​

自动启动行为 ​

面包要求 ​

Claude 代理 SDK 集成 ​

处理流程 ​

SDK组件 ​

模型配置 ​

端口分配 ​

数据存储 ​

错误处理 ​

性能 ​

故障排除 ​

Worker 服务

概览

REST API 端点

查看器和健康端点

1. 查看器界面

2. 健康检查

3. 服务器发送事件流

数据检索端点

4. 获取提示

5. 获取观察

6. 获取摘要

7. 通过ID获取观察

8. 通过ID获取观察（批量）

9. 通过ID获取会话

10. 通过ID获取提示

12. 获取统计数据

13. 获取项目

设置端点

14. 获取设置

15. 保存设置

队列管理端点

16. 获取待处理队列状态

17. 触发手动恢复

会话管理端点

19. 初始化会话

20. 添加观察

21. 生成摘要

22. 会话状态

23. 删除会话

面包过程管理

概览

命令

自动启动行为

面包要求

Claude 代理 SDK 集成

处理流程

SDK组件

模型配置

端口分配

数据存储

错误处理

性能

故障排除