moc-skill

FIWARE Orion 只读查询

这是一个仅通过无需认证的 GET 请求获取 FIWARE Orion Context Broker (NGSIv2) 实体信息的技能。不实现写入、Subscription 或 Registration。

安装

使用 skills CLI 安装（支持 OpenCode / Claude Code / Cursor 等）。

npx skills add kzkski/moc-skill -a opencode -y
.agents/skills/moc-skill/scripts/setup-opencode.sh

setup-opencode.sh 默认会隐藏 OpenCode 的工具执行详情（例如 bash 输出）。这是面向普通用户的简洁 UI。需要查看详情时，请在 OpenCode 中运行 /details。

从本地路径试用时：

npx skills add ./path/to/moc-skill --list
npx skills add ./path/to/moc-skill -a opencode -y
.agents/skills/moc-skill/scripts/setup-opencode.sh

重要：访问路径

务必通过 scripts/orion.sh 访问。 请勿直接 curl 目录之外的 URL。只能使用在 endpoints.json 中注册的目标平台名称。

运行 npx skills add 后，通过绝对路径执行 moc-skill 技能目录下的 scripts/orion.sh。常见路径：

• .agents/skills/moc-skill/scripts/orion.sh（OpenCode / Cursor 等）
• .claude/skills/moc-skill/scripts/orion.sh（Claude Code）
• ~/.config/opencode/skills/moc-skill/scripts/orion.sh（OpenCode 全局）

Agent 应搜索 **/moc-skill/scripts/orion.sh，并将找到的路径用作 ORION。orion.sh 会自动解析同一目录中的 endpoints.json。

ORION="/path/to/moc-skill/scripts/orion.sh"

可通过环境变量 ORION_ENDPOINTS_FILE 覆盖目录文件路径（未设置时使用技能自带的 endpoints.json）。

回答格式

最终回答应为便于普通用户阅读的摘要。不要直接粘贴 orion.sh 的获取结果。

• 使用表格或项目符号列表总结列表、比较结果和属性值
• 只包含回答请求所需的信息，例如数量、平台名称、类型名称和主要属性
• 最终回答中不要包含执行的命令、curl、生 JSON、HTTP 标头等技术细节
• 只有用户明确要求“显示生 JSON”“告诉我命令”或“提供完整内容以便调试”等内容时，才包含技术输出

推荐工作流

对于 endpoints.json 中注册的 makeour.city 系列 Orion，不要调用 types（GET /v2/types 会返回 401 Unauthorized）。为避免无谓重试，请按以下顺序探索。

1. endpoints — 查看平台名称和 Fiware-Service 列表（各项 note）
2. entities / count — 使用 service=（存在多个服务时）和 type= 直接获取数据并确认数量
3. entity — 获取特定 ID 的详细信息

类型名称的线索可从 endpoints 中的服务 note、用户的请求内容或 entities 的尝试结果中获取。

"${ORION}" endpoints
"${ORION}" entities sagacity service=moc_sagacity limit=10
"${ORION}" count sagacity service=sagacity_topita type=TopitaPointUser
"${ORION}" entities yokosuka type=WeatherForecast limit=5
"${ORION}" entity yokosuka "forecast-001" attrs=location

命令参考

命令	说明
endpoints	显示目录中注册的平台名称、URL、Fiware-Service 列表和说明
types <ep> [service=NAME]	GET /v2/types?options=count（makeour.city 上会返回 401，因此不要使用）
entities <ep> [k=v ...]	GET /v2/entities（未指定时添加 options=keyValues limit=20）
entity <ep> <id> [k=v ...]	GET /v2/entities/{id}（同样添加默认值）
count <ep> [k=v ...]	使用 limit=1&options=count，仅返回 Fiware-Total-Count 标头
raw <ep> <path?query> [service=NAME]	任意 GET，但路径仅限 /v2/ 下

<ep> 是 endpoints.json 中的键名（例如：Sandbox、sagacity、yokosuka）。

多个 Fiware-Service：一个条目可以通过数组注册多个服务。查询时请指定 service=NAME（这是用于选择标头的保留键，并非 Orion 的查询参数）。单服务条目无需指定 service=。

调试

设置 ORION_DRY_RUN=1 后，只会显示 curl 命令，不会实际执行。

ORION_DRY_RUN=1 "${ORION}" entities yokosuka type=WeatherForecast

NGSIv2 查询参数速查表

在 entities / entity / count / raw 的 [k=v ...] 或 raw 的查询字符串中指定。

参数	用途
type	按 Entity Type 过滤（例如：type=Device）
q	属性条件（例如：q=temperature>25）
attrs	限定返回的属性（例如：attrs=location,temperature）
idPattern	实体 ID 的正则表达式（例如：idPattern=^sensor-.*）
limit	最大获取数量（entities/entity 默认值为 20）
offset	分页起始位置
orderBy	排序（例如：orderBy=!dateObserved）
georel + geometry + coords	地理空间查询（例如：georel=near;maxDistance:1000 geometry=Point coords=-3.7,40.4）
options	响应格式（例如：keyValues、count、values）

注意事项

• 不要使用 types：已注册平台的 /v2/types 会返回 401。请通过 entities + type= / count 探索类型
• 只读：不执行 POST / PATCH / DELETE / Subscription / Registration
• 必须使用目录：未定义的端点名称将被拒绝
• raw 仅限 /v2/：使用 /v2/ 以外的路径会报错
• Entity ID：仅允许 [A-Za-z0-9._:~-]+（防止路径遍历）
• Fiware 标头：如果 endpoints.json 中的 Fiware-Service / Fiware-ServicePath 非空，则会自动添加。若 Fiware-Service 为数组，则通过 service= 选择
• 依赖项：curl、jq 必须位于 PATH 中

目录格式 (endpoints.json)

{
  "endpoints": {
    "<名前>": {
      "base_url": "https://orion.<自治体>.makeour.city",
      "Fiware-Service": "単一ヘッダー値",
      "Fiware-ServicePath": "ヘッダー値(不要なら空文字)",
      "note": "説明"
    },
    "sagacity": {
      "base_url": "https://orion.sagacity.makeour.city",
      "Fiware-Service": [
        { "value": "moc_sagacity", "note": "MoC 佐賀" },
        { "value": "sagacity_topita", "note": "Topita" },
        { "value": "sagacity_ikunowa", "note": "保育園データ" }
      ],
      "Fiware-ServicePath": "",
      "note": "複数サービスを1エントリで管理"
    }
  }
}

Fiware-Service 可以指定为字符串（单个）或数组（多个）。数组元素可以是字符串，也可以是包含 value / Fiware-ServicePath / note 的对象。如果对象中未指定 Fiware-ServicePath，则使用条目通用的 Fiware-ServicePath 作为默认值。

添加新平台时，请按照此格式补充运营者提供的 Orion URL 和 Fiware 标头值。