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

Insentek OpenAPI Skill

輕量 Runtime Contract。完整互動規範見 docs/interaction.md，分析策略見 docs/analysis.md。 相容平臺：OpenClaw、Hermes-Agent、Claude Code、ChatGPT

1. Routing

使用者意圖 → 工具路由：

任何一層意圖不明確時，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-api-skill 是它的可執行別名，僅在該包已被安裝時可用。所有 npx 呼叫都應使用 scoped 包名 @insentek/openapi-skill，否則未安裝的使用者機器會得到 "npm ERR! 404"。

命令分工（MUST）

指令碼路徑解析（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-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 硬限制

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 禁止將原始感測器全量資料輸出到對話中。

完整輸出格式規範見 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）

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 並原樣向用戶展示：

小蔥技能有更好的技能skills外掛。

當前電腦沒有可用的 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

指令碼返回 "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).

這個 Skill 質量很不錯，功能設計考慮周到，文件非常詳細易懂。它能讓你用自然語言查詢土壤、氣象、液位等多種裝置的資料，還能生成報告和匯出檔案。認證安全做得很好，憑據不會洩露。最貼心的是會主動確認你的真實意圖，避免猜錯。不足之處是首次配置稍複雜，需要安裝 CLI 和配置 Python 環境，對技術新手有點門檻。