@bulolo/hermes-link 0.3.0 → 0.3.2

package/README.md

@@ -1,6 +1,31 @@
-# @bulolo/hermes-link
+<div align="center">
 
-本地伴随服务，为 [Hermes Agent](https://github.com/nousresearch/hermes-agent) 提供 API 接入能力，支持公网、局域网直连。
+# hermes-link
+
+**Hermes Agent 本地接入层**
+
+为 [Hermes Agent](https://github.com/nousresearch/hermes-agent) 提供完整的客户端 API、多设备鉴权与对话管理，支持局域网 / 公网直连。
+
+[![npm](https://img.shields.io/npm/v/@bulolo/hermes-link?color=cb3837&logo=npm)](https://www.npmjs.com/package/@bulolo/hermes-link)
+[![Node](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![License](https://img.shields.io/badge/License-MIT-blue)](#)
+[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](#)
+
+简体中文 | [English](./README.en.md)
+
+[npm 包](https://www.npmjs.com/package/@bulolo/hermes-link)
+
+<p>
+  <a href="https://github.com/bulolo/HermesLink">
+    <img src="https://img.shields.io/badge/⭐_Star-项目-yellow?style=for-the-badge&logo=github" alt="Star 项目"/>
+  </a>
+</p>
+
+**如果这个项目对你有帮助，请点击右上角 ⭐ Star 支持一下，这是对开发者最大的鼓励！**
+
+</div>
+
+---
 
 ## 概述
 
@@ -9,7 +34,7 @@ Hermes Link 是一个运行在本机的后台 HTTP 服务，默认监听 `http:/
 所有 API 请求分为两类：
 
 - **无需鉴权**：`/pair`、`/api/v1/bootstrap`
-- **需要 Bearer Token**：其余接口均需 `Authorization: Bearer hpat_xxx`，通过配对流程获取
+- **需要 Bearer Token**：其余接口均需 `Authorization: Bearer hlat_xxx`，通过配对流程获取
 
 ## 为什么需要 HermesLink？
 
@@ -190,7 +215,7 @@ curl -s -X POST http://localhost:18642/api/v1/auth/device-session \
 
 ---
 
-> **Token 有效期**：access_token 15 分钟，refresh_token 90 天。access_token 过期后用 refresh_token 换新，无需重新配对。
+> **Token 有效期**：access_token 2 小时，refresh_token 90 天。access_token 过期后用 refresh_token 换新，无需重新配对。
 
 ## 命令一览
 
@@ -223,15 +248,15 @@ hermeslink config set log-level debug         # 日志级别：debug / info / wa
 
 ## API 参考
 
-服务默认监听 `http://0.0.0.0:18642`。所有需要鉴权的接口均使用 Bearer Token（`hpat_` 前缀）。
+服务默认监听 `http://0.0.0.0:18642`。所有需要鉴权的接口均使用 Bearer Token（`hlat_` 前缀）。
 
 ### Token 说明
 
 | Token | 前缀 | 有效期 | 用途 |
 |-------|------|--------|------|
 | Connect Token | 无前缀（base64url）| 5 分钟，一次性 | 兑换 access_token |
-| Access Token | `hpat_` | 15 分钟 | 所有 API 请求 |
-| Refresh Token | `hprt_` | 90 天 | 刷新 access_token |
+| Access Token | `hlat_` | 2 小时 | 所有 API 请求 |
+| Refresh Token | `hlrt_` | 90 天 | 刷新 access_token |
 
 ### 无需鉴权
 
@@ -242,7 +267,7 @@ hermeslink config set log-level debug         # 日志级别：debug / info / wa
 
 ### 认证 / 设备
 
-所有以下接口需要 Header：`Authorization: Bearer hpat_xxx`
+所有以下接口需要 Header：`Authorization: Bearer hlat_xxx`
 
 | 方法 | 路径 | 说明 |
 |------|------|------|
@@ -251,7 +276,7 @@ hermeslink config set log-level debug         # 日志级别：debug / info / wa
 | POST | `/api/v1/auth/refresh` | 用 refresh_token 换新 access_token |
 | POST | `/api/v1/auth/logout` | 撤销 refresh_token |
 
-**POST `/api/v1/auth/device-session`** 的 Authorization 头需放 **connect_token**（不是 hpat_），Body：
+**POST `/api/v1/auth/device-session`** 的 Authorization 头需放 **connect_token**（不是 hlat_），Body：
 
 ```json
 {
@@ -267,15 +292,15 @@ hermeslink config set log-level debug         # 日志级别：debug / info / wa
 {
   "ok": true,
   "device": { "device_id": "dev_xxx", "label": "我的设备", "platform": "ios" },
-  "access_token":  { "token": "hpat_xxx", "expires_at": "2026-05-08T13:00:00Z" },
-  "refresh_token": { "token": "hprt_xxx", "expires_at": "2026-08-06T12:00:00Z" }
+  "access_token":  { "token": "hlat_xxx", "expires_at": "2026-05-08T13:00:00Z" },
+  "refresh_token": { "token": "hlrt_xxx", "expires_at": "2026-08-06T12:00:00Z" }
 }
 ```
 
 **POST `/api/v1/auth/refresh`** Body：
 
 ```json
-{ "refresh_token": "hprt_xxx" }
+{ "refresh_token": "hlrt_xxx" }
 ```
 
 ### 配对
@@ -316,38 +341,144 @@ hermeslink config set log-level debug         # 日志级别：debug / info / wa
 
 ### 对话（Conversations）
 
+#### 活跃对话
+
 | 方法 | 路径 | 说明 |
 |------|------|------|
-| GET | `/api/v1/conversations` | 列出所有对话（`?limit=20&cursor=xxx`） |
-| GET | `/api/v1/conversations/search` | 搜索对话（`?q=关键词`） |
+| GET | `/api/v1/conversations` | 列出活跃对话（`?limit=20&cursor=xxx`） |
+| GET | `/api/v1/conversations/search` | 搜索活跃对话（`?q=关键词`） |
 | POST | `/api/v1/conversations` | 新建对话 |
-| DELETE | `/api/v1/conversations` | 批量删除对话 |
+| DELETE | `/api/v1/conversations` | 批量删除对话（`{"conversation_ids":["conv_xxx"]}`） |
 | DELETE | `/api/v1/conversations/:id` | 删除单个对话 |
-| GET | `/api/v1/conversations/:id/messages` | 获取对话消息列表 |
+| GET | `/api/v1/conversations/:id/messages` | 获取对话消息列表（含 `runtime` 上下文信息） |
 | POST | `/api/v1/conversations/:id/messages` | 发送消息 |
 | GET | `/api/v1/conversations/:id/events` | SSE 实时事件流 |
 | GET | `/api/v1/conversations/events` | 所有对话事件流（SSE） |
 | PATCH | `/api/v1/conversations/:id/title` | 重命名对话（`{"title":"新标题"}`） |
-| PATCH | `/api/v1/conversations/:id/model` | 切换模型 |
+| PATCH | `/api/v1/conversations/:id/model` | 切换模型（`{"model_id":"xxx"}`） |
 | PATCH | `/api/v1/conversations/:id/profile` | 切换 profile |
 | POST | `/api/v1/conversations/:id/ack` | 确认已读 |
-| POST | `/api/v1/conversations/clear-plans` | 创建批量清理计划 |
-| GET | `/api/v1/conversations/clear-plans/:planId` | 查询清理计划状态 |
-| POST | `/api/v1/conversations/clear-plans/:planId/execute` | 执行清理计划 |
 | POST | `/api/v1/conversations/:id/runs/:runId/cancel` | 取消对话内的某次执行 |
-| POST | `/api/v1/conversations/:id/approvals/:approvalId/approve` | 审批工具调用（允许） |
+| POST | `/api/v1/conversations/:id/approvals/:approvalId/approve` | 审批工具调用（允许，`{"scope":"once\|session\|always"}`） |
 | POST | `/api/v1/conversations/:id/approvals/:approvalId/deny` | 审批工具调用（拒绝） |
 | POST | `/api/v1/conversations/:id/blobs` | 上传附件 |
 | GET | `/api/v1/conversations/:id/blobs/:blobId` | 下载附件 |
 | DELETE | `/api/v1/conversations/:id/blobs/:blobId` | 删除附件 |
 
+#### 归档对话
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/v1/conversations/archived` | 列出已归档对话（`?limit=20&cursor=xxx`） |
+| GET | `/api/v1/conversations/archived/search` | 搜索已归档对话（`?q=关键词`） |
+| POST | `/api/v1/conversations/:id/archive` | 归档对话（发送新消息时自动恢复为活跃） |
+| POST | `/api/v1/conversations/:id/unarchive` | 取消归档 |
+
+#### 批量清理计划
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/v1/conversations/clear-plans` | 创建批量删除计划（`{"target_status":"active\|archived"}`） |
+| GET | `/api/v1/conversations/clear-plans/:planId` | 查询计划状态 |
+| POST | `/api/v1/conversations/clear-plans/:planId/execute` | 执行计划（批量删除） |
+
+#### 批量归档计划
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/v1/conversations/archive-plans` | 创建批量归档计划（`{"exclude_conversation_ids":[]}`） |
+| GET | `/api/v1/conversations/archive-plans/:planId` | 查询计划状态 |
+| POST | `/api/v1/conversations/archive-plans/:planId/execute` | 执行计划（批量归档） |
+
+#### 响应结构说明
+
+**ConversationSummary**（对话列表每项）：
+
+```json
+{
+  "id": "conv_xxx",
+  "title": "对话标题",
+  "created_at": "2026-05-09T00:00:00.000Z",
+  "updated_at": "2026-05-09T00:00:00.000Z",
+  "last_event_seq": 12,
+  "usage": { "input_tokens": 100, "output_tokens": 200, "total_tokens": 300, "updated_at": "..." },
+  "profile": { "uid": "prof_xxx", "name": "default", "display_name": "default", "avatar_url": null },
+  "last_message": { "id": "msg_xxx", "role": "assistant", "content_preview": "消息摘要..." }
+}
+```
+
+**GET `/api/v1/conversations/:id/messages`** 响应新增 `runtime` 字段：
+
+```json
+{
+  "ok": true,
+  "messages": [...],
+  "last_event_seq": 12,
+  "runtime": {
+    "profile": { "name": "default", "display_name": "default", "avatar_url": null },
+    "model": { "id": "claude-3-5-sonnet", "provider": "anthropic", "context_window": 200000 },
+    "context": { "input_tokens": 100, "output_tokens": 200, "total_tokens": 300, "usage_percent": 0, "source": "estimated" }
+  },
+  "page": { "limit": 50, "has_more_before": false, "has_more_after": false, "oldest_message_id": "...", "newest_message_id": "..." }
+}
+```
+
+**LinkMessage**（消息对象）：
+
+```json
+{
+  "id": "msg_xxx",
+  "schema_version": 1,
+  "conversation_id": "conv_xxx",
+  "role": "user|assistant|tool|system",
+  "status": "queued|streaming|completed|failed|cancelled",
+  "created_at": "...",
+  "updated_at": "...",
+  "sender": { "id": "app_user", "type": "human|agent|system|tool", "display_name": "Me" },
+  "parts": [{ "type": "text", "text": "消息内容" }],
+  "attachments": [],
+  "blocks": [],
+  "agent_events": [],
+  "approvals": []
+}
+```
+
+**DELETE `/api/v1/conversations/:id`** 响应新增字段：
+
+```json
+{
+  "ok": true,
+  "conversation_id": "conv_xxx",
+  "hermes_deleted": false,
+  "deleted_at": "2026-05-09T00:00:00.000Z"
+}
+```
+
 ### 统计
 
 | 方法 | 路径 | 说明 |
 |------|------|------|
-| GET | `/api/v1/statistics` | 全局使用统计（对话、消息数等） |
+| GET | `/api/v1/statistics` | 全局使用统计（`?profile=xxx&profile_uid=xxx`） |
 | GET | `/api/v1/statistics/usage` | Token 用量统计（`?days=7&from=2026-05-01&to=2026-05-08&model=xxx&profile=xxx`） |
 
+**GET `/api/v1/statistics`** 响应：
+
+```json
+{
+  "ok": true,
+  "statistics": {
+    "conversations": { "total": 10, "active": 8, "archived": 1, "deleted": 1 },
+    "tokens": { "input_tokens": 5000, "output_tokens": 8000, "total_tokens": 13000 },
+    "messages": { "total": 120 },
+    "runs": { "total": 50 },
+    "models": { "total": 0 },
+    "profiles": { "total": 0 },
+    "skills": { "total": 0 },
+    "tools": { "total": 0 }
+  }
+}
+```
+
 ### 模型（Models）
 
 | 方法 | 路径 | 说明 |