菲律宾地理编码服务

要解决的问题

菲律宾的行政区划层级复杂：从群岛（island groups）到大区（regions）、省（provinces）、市（cities）与市镇（municipalities），再到最基层的村（barangays），中间还夹着选区（districts）和 sub-municipality。如果直接对接 PSGC（Philippine Standard Geographic Code）数据，就得自己实现层级遍历、代码校验和名称检索，这些逻辑在各项目里重复造轮子很容易出错——尤其是当用户用自然语言提问时，比如「马尼拉大都会有哪些城市」，并没有提供任何行政区代码。

技能如何工作

这个技能把 PSGC 的完整层级封装成一组 MCP 工具，模型只充当路由层：理解意图、选择函数、提取参数，再由 scripts.tools 中的函数以关键字参数调用 API。能力大致分三类：

• 按层级遍历：每个行政层级都有「列出全部」和「按代码取单个」两组函数，如 get_region_provinces、get_province_cities_municipalities、get_city_barangays，并支持跨层查询，例如直接取某个 island group 下的全部 barangay。
• 名称检索：search_by_name 可跨层级按名称搜索，可选 type 过滤层级、limit 限制条数，适合用户只给出地名、没有代码的场景。
• 代码校验与溯源：validate_code 判断代码是否存在并返回类型；get_hierarchy 返回某个代码的完整父级链路。

执行流程有强制顺序：先检查 scripts.config.settings.api_key 是否为空，为空则通过 AskUserQuestion 向用户索取，再用 scripts.config.set_api_key(key) 保存。密钥缺位时禁止编造数据；参数不完整时同样必须先向用户追问。

适用边界

• 必须配置 API 密钥。数据来自外部 API，技能本身不内置离线数据集，没有密钥就没有任何结果。
• 只覆盖菲律宾 PSGC 范围内的行政地理实体，不包含坐标、距离计算或其他国家的数据。
• 工具返回的是原始 dict，后续如何整理展示取决于调用方。