insentek-openapi

通过自然语言查询 insentek（东方智感）物联网设备数据。 支持土壤墒情仪、气象站、见厘液位计等多种设备类型的实时数据、 历史数据、趋势分析、跨设备对比与数据导出。

<!-- 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 在本地配置：

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

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

命令分工（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 标记，无需提前知道用户是哪种安装：

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 精确查询：

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-openapi ... / 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

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

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

# 列表（${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

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

{
  "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" }
}

# 历史数据
${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。

# 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 转义吞掉换行 / 引号 / 反斜杠：

# 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：

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} 后执行：

${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).