insentek-api-skill

SKILL.md

---
name: insentek-openapi
version: 1.2.2
description: >
  通过自然语言查询 insentek（东方智感）物联网设备数据。
  支持土壤墒情仪、气象站、见厘液位计等多种设备类型的实时数据、
  历史数据、趋势分析、跨设备对比与数据导出。
api_base_url: https://openapi.ecois.info
author: insentek-api-skills
guardrails:
  raw_data_output: PROHIBITED
  dry_run_preview_rows: 5
  max_chat_rows: 200
  max_export_rows: 50000
---

<!--
  Note: `api_base_url` above is informational only; it is not consumed by
  any script. To override at runtime, set the INSENTEK_API_BASE environment
  variable before invoking scripts/insentek_cli.py.
-->


# Insentek OpenAPI Skill

> 轻量 Runtime Contract。完整交互规范见 `docs/interaction.md`，分析策略见 `docs/analysis.md`。
> 兼容平台：OpenClaw、Hermes-Agent、Claude Code、ChatGPT

---

## 1. Routing

用户意图 → 工具路由：

| L1 意图 | L2 输出 | 调用 |
|---------|---------|------|
| 查询数据 | 对话展示 | `query_device` → `query_data` → 按输出格式回复 |
| 查询数据 | 文件导出 | `query_device` → `export_*` → 返回文件路径 |
| 生成报告 | 文件导出 | `query_device` → `query_data` → 分析 → `write_html` |
| 对比设备 | 对话展示 | `query_device` (xN) → `query_data` (xN) → 对比表格 |
| 对比设备 | 文件导出 | `query_device` (xN) → `query_data` (xN) → `export_excel` |

**任何一层意图不明确时，MUST 向用户确认，不得假设。** 详见 `docs/interaction.md` Section 1。

---

## 2. Tools

**认证约束（MUST）：** Agent **禁止**向用户索要 `appid` 或 `secret`，也 **禁止**在对话中接收、存储或回显这些凭据。凭据仅通过 CLI 在本地配置：

```bash
npx @insentek/openapi-skill login       # 配置（加密保存）
npx @insentek/openapi-skill logout      # 清除
npx @insentek/openapi-skill auth status # 查看连接状态
```

> npm 包名为 `@insentek/openapi-skill`（已发布到 npm registry）。`insentek-api-skill` 是它的可执行别名，**仅在该包已被安装时**可用。**所有 `npx` 调用都应使用 scoped 包名** `@insentek/openapi-skill`，否则未安装的用户机器会得到 "npm ERR! 404"。

### 命令分工（MUST）

| 用途 | 工具 | 示例 |
|------|------|------|
| 安装 / 更新 skill | `npx @insentek/openapi-skill` | `install -r openclaw -s workspace -y` |
| 配置 / 清除凭据 | `npx @insentek/openapi-skill login/logout` | `npx @insentek/openapi-skill login` |
| 查连接状态 | `npx @insentek/openapi-skill auth status` | — |
| 查安装路径 / 脚本位置 | `npx @insentek/openapi-skill info/status/doctor --json` | 见下方「脚本路径解析」 |
| **查询 API** | `python3 <SKILL_ROOT>/scripts/insentek_cli.py` | `python3 .../insentek_cli.py devices` |

### 脚本路径解析（MUST，API 调用前）

Agent 工作目录通常**不是** skill 安装目录。**禁止**使用相对路径 `python3 scripts/insentek_cli.py ...`。

**首次 API 调用前**，或脚本路径未知 / 返回「文件找不到」时，**必须先**查实际安装位置。`info --json` 会列出所有 runtime × scope 的解析结果及 `installed` 标记，无需提前知道用户是哪种安装：

```bash
npx @insentek/openapi-skill info --json
```

从输出中遍历 `runtimes[].scopes[]`，挑选第一个 `installed: true` 的条目，将其 `installDir` 作为 `${SKILL_ROOT}`，将 `scripts.cli` / `scripts.exportExcel` / `scripts.writeHtml` 作为脚本绝对路径，并将 `python.command`（如 `python3` / `py` / `python`）作为 `${PYTHON}`。解析后在**本会话内缓存**，后续 API 调用复用，**不要**重复猜测路径。

如果用户已经明确告诉过你 runtime / scope（例如刚刚 `install -r openclaw -s workspace -y`），也可以用 `status --json` 精确查询：

```bash
npx @insentek/openapi-skill status -r openclaw -s workspace --json
# 或 -r claude -s global / -s project，按用户场景选择
```

OpenClaw workspace 常见路径（仅供参考，**以 info/status 返回为准**）：
`~/.openclaw/workspace/skills/insentek-openapi`

**禁止（MUST NOT）：**
- `python3 scripts/insentek_cli.py ...` — 相对路径在 OpenClaw 等环境下会失败
- `npx insentek-api-skill ...` — npm registry 上没有这个包名，对未安装本包的新用户会 404
- `npx @insentek/openapi-skill devices` — `devices` 不是顶层命令，会被 commander 当成 `install` 的子命令而触发安装流程
- 文件找不到时乱试其它命令 — **应重新 `info --json`**

用户说「配置好了，继续吧」→ 从**中断前的意图**继续；若已有 `${SKILL_ROOT}` 直接调 API，**不要**重新 login。

若工具返回 `authentication_required` 或 HTTP 401/403，**STOP** 并 **原样** 向用户展示以下固定文案（不得改写、不得追加索要 secret）：

```
这台电脑还没有连接 Insentek API，需要先完成一次本地配置，通常 1 分钟就好。

请在终端运行：

npx @insentek/openapi-skill login

按提示输入 appid 和 secret 即可（加密保存在本机，无需发到这个对话）。配置完成后回来继续提问，我接着帮你处理。
```

---

### query_device

查询设备信息：列表、详情、别名解析。

```json
{
  "page": { "type": "integer", "default": 1 },
  "limit": { "type": "integer", "default": 20 },
  "sn": { "type": "string", "description": "设备序列号，与 alias 二选一" },
  "alias": { "type": "string", "description": "设备别名，支持部分匹配" }
}
```

```bash
# 列表（${SKILL_ROOT} / ${PYTHON} 由 info --json 解析，见上方）
${PYTHON} ${SKILL_ROOT}/scripts/insentek_cli.py devices [--page ${page}] [--limit ${limit}]
# 详情
${PYTHON} ${SKILL_ROOT}/scripts/insentek_cli.py device --sn ${sn}
```

> `${PYTHON}` 在 macOS/Linux 默认为 `python3`，Windows 默认为 `python`（亦可为 `py`）；以 `info --json` 输出的 `python.command` 为准。**禁止**使用裸 `python`——在 macOS 系统默认配置、新版 Ubuntu/Fedora 等环境下 `python` 命令不存在或指向 Python 2，会直接失败。

**注意：** `--token` 变为可选。若未提供且已配置持久化凭据，脚本自动获取。

**行为：** alias → 模糊匹配 → 多匹配时反问用户 → 单匹配时缓存 alias→sn 映射。

---

### query_data

查询设备历史数据或实时数据。

```json
{
  "sn": { "type": "string", "required": true },
  "time_expression": { "type": "string", "description": "自然语言时间描述，如'现在'、'昨天'、'最近7天'。不传默认最近24小时。" },
  "range": { "type": "string", "description": "YYYYMMDD,YYYYMMDD，由 time_expression 自动计算" },
  "includeParameters": { "type": "string", "description": "指定参数，逗号分隔，如 moisture,temperature" }
}
```

```bash
# 历史数据
${PYTHON} ${SKILL_ROOT}/scripts/insentek_cli.py data --sn ${sn} --range ${range} [--include-params ${params}]

# 预览（调试/验证用）
${PYTHON} ${SKILL_ROOT}/scripts/insentek_cli.py data --sn ${sn} --range ${range} --dry-run

# 实时数据（latest）
${PYTHON} ${SKILL_ROOT}/scripts/insentek_cli.py latest --sn ${sn}
```

**注意：** `--token` 变为可选。若未提供且已配置持久化凭据，脚本自动获取。

时间表达式解析见 `docs/interaction.md` Section 2。

---

### export_csv / export_excel / export_json

用户意图明确为"导出/下载"时调用，而非 `query_data`。

```bash
# CSV
${PYTHON} ${SKILL_ROOT}/scripts/insentek_cli.py export --sn ${sn} --range ${range} --format csv --output ${file}.csv

# Excel
${PYTHON} ${SKILL_ROOT}/scripts/export_excel.py --sn ${sn} --range ${range} --output ${file}.xlsx

# JSON
${PYTHON} ${SKILL_ROOT}/scripts/insentek_cli.py export --sn ${sn} --range ${range} --format json --output ${file}.json
```

**注意：** `--token` 变为可选。若未提供且已配置持久化凭据，脚本自动获取。

所有导出脚本均支持 `--dry-run`。

---

### write_html

Agent 完成数据分析后，将动态生成的 HTML 内容写入文件。**推荐**使用 `--input-file` 避免 shell 转义吞掉换行 / 引号 / 反斜杠：

```bash
# 1. 先把 HTML 内容写到临时文件（写文件工具按平台决定）
#    e.g. write to /tmp/report.html or %TEMP%\report.html
# 2. 然后调用 write_html.py 落盘
${PYTHON} ${SKILL_ROOT}/scripts/write_html.py --input-file ${tmp_html} --output ${file}.html

# 也支持 stdin（注意 echo 会破坏 HTML 中的换行/引号，仅用于简单片段）：
echo "${html_content}" | ${PYTHON} ${SKILL_ROOT}/scripts/write_html.py --output ${file}.html
```

---

## 3. Guardrails

### 3.1 硬限制

| 限制项 | 规则 | 超限处理 |
|--------|------|----------|
| 单次查询跨度 | ≤ 365 天 | 拒绝，提供拆分选项 |
| 历史回溯 | ≤ 3 年 | 拒绝，提示最早日期 |
| 对话展示 | ≤ 200 条 | 展示摘要 + 首尾各 10 条抽样 |
| 文件导出 | ≤ 50,000 条 | 拒绝，建议缩小范围或分批 |

### 3.2 数据可用性校验（MUST）

`query_data` 返回后，检查实际数据范围 vs 请求范围：

```
requested_days = 用户请求的天数
actual_days    = 实际返回数据的天数
coverage       = actual_days / requested_days

IF coverage < 0.5 OR actual_days < 7:
  → STOP
  → 告知用户实际范围，询问是否继续
  → 等待确认后才可生成报告/分析
ELSE IF actual_range < requested_range:
  → 继续，但报告 MUST 使用 actual_range 标注
```

### 3.3 原始数据输出禁令（MUST）

Agent **禁止**将原始传感器全量数据输出到对话中。

| 场景 | 处理 |
|------|------|
| "看看数据" | 统计摘要 + 首尾各 5 条 |
| "调试" | `--dry-run` 预览 |
| "给我原始数据" | 引导导出 CSV/Excel |
| "全部发给我" | 拒绝，解释 Token 限制 |

完整输出格式规范见 `docs/interaction.md` Section 4。

---

## 4. Authentication

### 4.1 CLI 本地凭据（唯一方式）

用户 **必须** 通过 CLI 在本地配置凭据，Agent **不得** 在对话中收集 appid/secret：

```bash
npx @insentek/openapi-skill login
npx @insentek/openapi-skill logout
npx @insentek/openapi-skill auth status
```

凭据加密保存在 `~/.config/insentek/credentials.json`（文件权限 600）。

### 4.2 Agent 行为约束（MUST）

| 场景 | Agent 行为 |
|------|-----------|
| 用户首次使用 / 未连接 | 展示 Section 2 固定引导文案，**禁止**索要 secret |
| 用户主动发送 appid/secret | **拒绝接收**，说明请改用 CLI login |
| 401/403 / `authentication_required` | 展示 Section 2 固定引导文案，STOP |
| 用户要求"重新认证" | 引导 `npx @insentek/openapi-skill login`（更新）或 `logout` 后再 `login` |

### 4.3 Token 获取策略

脚本**管理 token 生命周期**，实现缓存 + 自动刷新机制：
- CLI `login` 验证凭据后，凭据和 token 一并加密保存
- 后续各命令 `--token` 参数变为可选
- 未提供 `--token` 时，脚本**优先从配置文件读取缓存的 token**
- 请求 API 时如果返回 401/403，脚本**自动刷新 token** 并重试一次
- 刷新失败则返回 `authentication_required`，Agent 引导用户重新 `login`
- 不检查 token 过期时间，靠 HTTP 401/403 触发刷新

### 4.4 Token 缓存流程

```
请求 API
  ├── 使用缓存 token
  ├── 成功 → 返回数据
  └── 401/403 → 调用 /v3/token 获取新 token → 更新配置文件 → 重试请求
        └── 仍失败 → 返回 authentication_required → 引导 CLI login
```

### 4.5 安全说明

- Secret **绝不**出现在对话、日志或 Agent 上下文中
- 凭据文件权限 600，内容 AES-256-GCM 加密（机器绑定密钥）
- Token 缓存有效期约 2 小时，靠 HTTP 401/403 触发自动刷新

---

**向后兼容：** 所有命令仍支持 `--token` 参数，现有调用方式不受影响。

---

## 5. Environment Check

首次交互前，在解析 `${SKILL_ROOT}` / `${PYTHON}` 后执行：

```bash
${PYTHON} ${SKILL_ROOT}/scripts/insentek_cli.py check
```

关键项失败时 STOP，可选项失败时降级运行并告知用户。

若 `${PYTHON}` 解析失败（`info --json` 的 `python.ok` 为 `false`），说明本机没有可用的 Python 3.10+，**STOP** 并原样向用户展示：

```
当前电脑没有可用的 Python（需要 3.10 或更高版本）。请先安装 Python：

- macOS: brew install python
- Ubuntu/Debian: sudo apt install python3 python3-pip
- Fedora: sudo dnf install python3
- Windows: 到 https://www.python.org/downloads/ 下载安装包，安装时勾选 "Add Python to PATH"

安装完成后请回来继续提问，我接着帮你处理。
```

若 `checks.credentials.ok` 为 `false`，展示 Section 2 固定引导文案，**禁止**继续调用 API 或向用户索要 secret。

---

## 6. Error Handling

| HTTP | 处理 |
|------|------|
| 200 | 正常处理 |
| 400 | 检查参数格式后重试 |
| 401/403 | **STOP**，展示 CLI login 引导文案，**禁止**向用户索要 secret |
| 脚本找不到 / ENOENT | **STOP**，执行 `status --json` 或 `info --json` 解析 `${SKILL_ROOT}`，**禁止**乱试 npx 子命令 |
| 404 | 确认设备 SN/别名 |
| 429 | 限流，等待后重试 |
| 500 | 指数退避重试 3 次 |

脚本返回 `"success": false` 且 `error` 为 `authentication_required` 时，展示 Section 2 固定引导文案并 STOP。其他错误解析 `error`/`message` 字段：含"范围/限制"则解释护栏，否则展示友好错误。

---

## Notes

- **Pagination**: `page` starts at 1.
- **Values**: Nested `{node_name: {parameter_code: value}}`
- **Alias**: Case-insensitive partial match on `alias`.
- **Param names**: Use Chinese names from `/description` endpoint for display.
- **Script-first**: API 用 `${PYTHON} ${SKILL_ROOT}/scripts/insentek_cli.py`；`${SKILL_ROOT}` 和 `${PYTHON}` 由 `info --json` 解析（`runtimes[].scopes[]` 中 `installed: true` 的条目对应 `installDir` / `scripts.cli` / `python.command`）
- **Dry-run**: Append `--dry-run` for preview; never output raw data to chat.
- **Reference**: Edge cases → `reference/api-doc.md` (OpenAPI v3.1.9).