201 lines
7.0 KiB
Markdown
201 lines
7.0 KiB
Markdown
---
|
||
name: 小黑日报助手数据查询
|
||
description: 查询小黑日报助手的本地数据服务。支持工作时间线、工作报告、时段热力图、应用使用时长等维度的数据查询。当用户询问"今天做了什么"、"查询日报"、"工作效率分析"、"最近的工作时间线"、"看看我这几天的工作"、"热力图"、"各应用使用时长"等问题时自动触发。
|
||
---
|
||
|
||
# 小黑日报助手数据查询
|
||
|
||
## 概述
|
||
|
||
小黑日报助手是一个本地运行的 HTTP 数据服务（`http://198.120.0.250:8088`），提供了工作时间追踪、日报生成、时段热力图、应用使用时长统计等数据查询能力。本 Skill 封装了该服务的接口，让 Agent 能够通过自然语言理解用户意图后调用对应接口。
|
||
|
||
## 执行规则
|
||
|
||
### 强制规则
|
||
|
||
1. **每次收到用户查询请求前**，必须先调用 `GET http://198.120.0.250:8088/` 拉取最新 API 文档（该接口返回 Markdown）。所有后续接口调用必须以最新文档为准，绝对不可依赖记忆。
|
||
2. 解析 Markdown 文档后，动态选择接口并构造请求。
|
||
3. 使用 `fetch_webpage` 工具发起所有 HTTP 请求。
|
||
|
||
### 响应格式
|
||
|
||
所有业务接口统一返回 JSON：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `code` | 0 = 成功；400 = 参数错误；404 = 接口不存在；500 = 服务器错误 |
|
||
| `message` | 提示信息 |
|
||
| `data` | 业务数据，结构因接口而异 |
|
||
|
||
### 日期时间参数约定
|
||
|
||
- 支持 `YYYY-MM-DD`（日期精度，自动覆盖 00:00~23:59）和 `YYYY-MM-DD HH:mm:ss`（秒精度）
|
||
- 未传参数时：时间线/报告/应用时长默认查询**今天**；热力图默认查询**近 7 天**
|
||
- 本 Skill 统一使用 `YYYY-MM-DD` 日期精度格式
|
||
|
||
---
|
||
|
||
## 接口速查
|
||
|
||
> 以下为当前已知接口列表，最终以 `GET /` 实时拉取的 Markdown 文档为准。
|
||
|
||
| 接口 | 路径 | 用途 | 默认时间范围 |
|
||
|------|------|------|-------------|
|
||
| 文档 | `GET /` | 获取最新 API 文档（Markdown） | - |
|
||
| 工作时间线 | `GET /api/timeline` | 查询工作记录列表 | 今天 |
|
||
| 工作报告 | `GET /api/report` | 查询日报/周报/月报 | 今天 |
|
||
| 时段热力图 | `GET /api/heat-map` | 查询每日 24 小时工作分布 | 近 7 天 |
|
||
| 应用使用时长 | `GET /api/app-usage` | 查询各应用使用时长排行 | 今天 |
|
||
|
||
### 接口 2：查询工作时间线
|
||
|
||
```
|
||
GET /api/timeline?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
|
||
```
|
||
|
||
**data 字段**：`id`, `startTime`(ISO8601), `endTime`(ISO8601), `category`(开发/会议等), `summary`(内容摘要), `details`, `confidence`(AI置信度), `source`(screenshot/manual), `createdAt`, `updatedAt`
|
||
|
||
### 接口 3：查询工作报告
|
||
|
||
```
|
||
GET /api/report?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
|
||
```
|
||
|
||
**data 字段**：`id`, `type`(daily/weekly/monthly), `title`, `content`(Markdown), `startDate`, `endDate`, `style`, `status`(completed/pending/failed), `language`, `createdAt`, `updatedAt`
|
||
|
||
### 接口 4：查询时段热力图
|
||
|
||
```
|
||
GET /api/heat-map?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
|
||
```
|
||
|
||
**data 字段**：`date`, `hourlyCounts`(长度为24的number[]), `focusMinutes`(专注时长分钟), `totalRecords`(非闲置记录总数), `topCategory`, `activePeriod`(活跃时段如"09:00 — 18:00")
|
||
|
||
### 接口 5：查询应用使用时长
|
||
|
||
```
|
||
GET /api/app-usage?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
|
||
```
|
||
|
||
**data 字段**：`appName`, `totalDurationSec`(秒), `firstUsedAt`(ISO8601), `lastUsedAt`(ISO8601)。按 `totalDurationSec` 降序排列。
|
||
|
||
---
|
||
|
||
## 工作流程
|
||
|
||
### 完整执行步骤
|
||
|
||
```
|
||
用户提问 → 解析意图与时间范围
|
||
→ GET / 拉取最新 API 文档
|
||
→ 匹配合适的接口
|
||
→ 构造 GET 请求（拼接 query 参数）
|
||
→ fetch_webpage 发送请求
|
||
→ 解析 JSON 响应
|
||
→ 用中文总结数据，呈现给用户
|
||
```
|
||
|
||
### Step 1: 解析用户意图
|
||
|
||
从用户问题中识别查询类型：
|
||
|
||
| 用户表述 | 接口 |
|
||
|---------|------|
|
||
| "今天做了什么"、"工作时间线"、"工作记录" | `/api/timeline` |
|
||
| "日报"、"周报"、"报告"、"今天报告写了什么" | `/api/report` |
|
||
| "热力图"、"效率分析"、"哪个时段最忙"、"工作分布" | `/api/heat-map` |
|
||
| "哪些应用"、"应用使用排行"、"哪个APP用的最久" | `/api/app-usage` |
|
||
|
||
可以从一帧提示中识别多类意图，并行调用多个接口。
|
||
|
||
### Step 2: 解析时间范围
|
||
|
||
- "今天" → 不传参数（接口默认今天）
|
||
- "昨天" → `startDate=YYYY-MM-DD(昨天)&endDate=YYYY-MM-DD(昨天)`
|
||
- "最近3天" → `startDate=3天前&endDate=今天`
|
||
- "上周" → `startDate=上周一&endDate=上周日`
|
||
- "5月15号" → `startDate=2026-05-15&endDate=2026-05-15`
|
||
- "5月1号到5月15号" → `startDate=2026-05-01&endDate=2026-05-15`
|
||
|
||
**日期计算规则**：所有日期统一使用 `YYYY-MM-DD` 格式。如用户说话时未指定年份，默认为当前年（基于对话 session 的 current date 推断）。
|
||
|
||
### Step 3: 拉取最新文档
|
||
|
||
```bash
|
||
GET http://198.120.0.250:8088/
|
||
```
|
||
|
||
用 `fetch_webpage` 工具请求，拿到 Markdown 文档后解析接口列表。
|
||
|
||
### Step 4: 调用业务接口
|
||
|
||
示例：
|
||
|
||
```bash
|
||
# 查询今天的工作时间线
|
||
GET http://198.120.0.250:8088/api/timeline
|
||
|
||
# 查询 5月1日到5月15日的工作报告
|
||
GET http://198.120.0.250:8088/api/report?startDate=2026-05-01&endDate=2026-05-15
|
||
```
|
||
|
||
用 `fetch_webpage` 工具，传入对应 URL 和描述性 query。
|
||
|
||
### Step 5: 呈现结果
|
||
|
||
将返回的 JSON 数据用**中文自然语言**总结呈现。原则：
|
||
- 工作时间线：按时间段列出，标注分类和摘要
|
||
- 工作报告：显示 Markdown 内容（如果多篇，逐篇列出标题和摘要）
|
||
- 热力图：描述峰值时段和活跃分布
|
||
- 应用时长：按使用时长降序列出并标注占比
|
||
|
||
---
|
||
|
||
## 错误处理
|
||
|
||
| 错误码 | 处理方式 |
|
||
|--------|----------|
|
||
| 400 | 检查日期格式是否正确（须为 `YYYY-MM-DD`） |
|
||
| 404 | 接口不存在 → 重新拉取 `GET /` 确认接口列表 |
|
||
| 500 | 向用户说明服务器内部错误，建议稍后重试 |
|
||
| 网络不通 | 向用户说明无法连接 `198.120.0.250:8088`，请确认服务是否运行 |
|
||
|
||
---
|
||
|
||
## 示例对话
|
||
|
||
**用户**："我今天做了什么？"
|
||
|
||
**Agent 行为**：
|
||
1. `fetch_webpage("http://198.120.0.250:8088/")` → 拿到 API 文档
|
||
2. 识别意图：工作时间线 → `/api/timeline`
|
||
3. 识别时间："今天" → 不传参数
|
||
4. `fetch_webpage("http://198.120.0.250:8088/api/timeline")` → 拿到 data
|
||
5. 呈现：
|
||
|
||
> 📊 **今天的工作时间线**
|
||
>
|
||
> | 时间 | 分类 | 内容 |
|
||
> |------|------|------|
|
||
> | 09:00-09:30 | 开发 | 修复登录页 bug |
|
||
> | 09:30-10:00 | 会议 | 每日站会 |
|
||
> | ... | | |
|
||
|
||
---
|
||
|
||
**用户**："看看我最近一周的效率怎么样"
|
||
|
||
**Agent 行为**：
|
||
1. 拉取文档
|
||
2. 识别意图：热力图 + 工作报告 → 并行调用 `/api/heat-map` 和 `/api/report`
|
||
3. 识别时间："最近一周" → `startDate=7天前&endDate=今天`
|
||
4. 拿到数据后，用热力图分析每日活跃分布，用报告看周报内容，整合呈现
|