tracking-pettracer-location

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tracking PetTracer pet location

追踪PetTracer宠物位置

Why this exists

开发背景

PetTracer exposes an (unofficial) web portal API used by their apps/website. This skill gives a reliable, low-drama workflow for:

Current location (latest known point)
Recent route/history (time-windowed points)
Near-real-time updates (WebSocket push, optional)

It is designed to minimise API load (be respectful) and to produce consistent, copy/paste-friendly outputs.

PetTracer开放了一个（非官方）网页门户API供其应用/网站使用。本工具提供可靠、低复杂度的工作流，支持：

当前位置（最新已知点位）
近期路线/历史记录（时间窗口内的点位）
近实时更新（WebSocket推送，可选）

工具设计旨在最小化API负载（保持友好调用），并生成一致、便于复制粘贴的输出结果。

Quick start

快速开始

Snapshot location (recommended default)

快照定位（推荐默认方式）

Set credentials (prefer env vars, not CLI args):

bash

export PETTRACER_USERNAME="you@example.com"
export PETTRACER_PASSWORD="••••••••"

List devices:

bash

python scripts/pettracer_cli.py list --format json --pretty

Locate a pet:

By name:

bash

python scripts/pettracer_cli.py locate --pet "Fluffy" --format json --pretty

By id:

bash

python scripts/pettracer_cli.py locate --device-id 12345 --format json --pretty

If the account has exactly one collar, you can omit
```
--pet/--device-id
```
:

bash

python scripts/pettracer_cli.py locate --format json --pretty

设置凭据（优先使用环境变量，而非命令行参数）：

bash

export PETTRACER_USERNAME="you@example.com"
export PETTRACER_PASSWORD="••••••••"

列出设备：

bash

python scripts/pettracer_cli.py list --format json --pretty

定位宠物：

通过名称：

bash

python scripts/pettracer_cli.py locate --pet "Fluffy" --format json --pretty

通过ID：

bash

python scripts/pettracer_cli.py locate --device-id 12345 --format json --pretty

如果账户仅有一个项圈，可省略
```
--pet/--device-id
```
参数：

bash

python scripts/pettracer_cli.py locate --format json --pretty

Get location history (last 6 hours)

获取位置历史记录（最近6小时）

bash

python scripts/pettracer_cli.py history --pet "Fluffy" --hours 6 --format json --pretty

bash

python scripts/pettracer_cli.py history --pet "Fluffy" --hours 6 --format json --pretty

Core workflow the agent should follow

代理应遵循的核心工作流

1) Decide: snapshot vs history vs live updates

1) 选择模式：快照、历史记录或实时更新

Snapshot: user asks “where is X right now?” → use
```
locate
```
.
History: user asks “where has X been today/last hour?” → use
```
history
```
.
Live: user wants continuous updates → use WebSocket (see references/websocket.md).

Default to snapshot unless the user explicitly wants a route or live tracking.

快照：用户询问“X现在在哪里？” → 使用
```
locate
```
命令。
历史记录：用户询问“X今天/过去一小时去过哪里？” → 使用
```
history
```
命令。
实时：用户需要持续更新 → 使用WebSocket（详见references/websocket.md）。

除非用户明确需要路线或实时追踪，否则默认使用快照模式。

2) Authenticate safely

2) 安全认证

Preferred order:

Use
```
PETTRACER_TOKEN
```
if already available.

Else login with

PETTRACER_USERNAME

PETTRACER_PASSWORD

(or

PETTRACER_EMAIL

Never ask the user to paste tokens into chat. Ask them to set env vars or store secrets in their vault.

Optional overrides (useful for debugging / future-proofing):

PETTRACER_API_BASE

(REST base; default

https://portal.pettracer.com/api

)

PETTRACER_WS_BASE

(WebSocket base; default

wss://pt.pettracer.com/sc

)

优先顺序：

若已存在
```
PETTRACER_TOKEN
```
则直接使用。

否则使用

PETTRACER_USERNAME

PETTRACER_PASSWORD

（或

PETTRACER_EMAIL

）登录。

绝对不要要求用户在聊天框中粘贴令牌。请引导用户设置环境变量或将密钥存储在密码管理器中。

可选覆盖配置（用于调试/适配未来变更）：

PETTRACER_API_BASE

（REST接口基础地址；默认值

https://portal.pettracer.com/api

）

PETTRACER_WS_BASE

（WebSocket基础地址；默认值

wss://pt.pettracer.com/sc

）

3) Identify the right device

3) 识别正确设备

Fetch devices via

GET /api/map/getccs

(wrapped by

pettracer_cli.py list

Match by
```
details.name
```
case-insensitively.
If multiple matches: show a disambiguation list (id + name) and ask the user which one.
If no match: show available device names.
If the account has exactly one collar, you can default to it.

通过
```
GET /api/map/getccs
```
接口获取设备列表（由
```
pettracer_cli.py list
```
命令封装）。
不区分大小写匹配
```
details.name
```
字段。
若存在多个匹配项：显示消歧列表（ID + 名称）并询问用户选择。
若无匹配项：显示可用设备名称。
若账户仅有一个项圈，可默认选择该设备。

4) Fetch location data

4) 获取位置数据

Current location comes from
```
device.lastPos
```
(collars) or top-level
```
posLat/posLong
```
(HomeStations):
- ```
posLat
```
  ,
```
posLong
```
- ```
timeMeasure
```
  (timestamp)
- ```
acc
```
  (accuracy, metres) or
```
horiPrec
```
  (fallback)

History uses

POST /api/map/getccpositions

with:

```
devId
```
,
```
filterTime
```
(ms),
```
toTime
```
(ms)

See references/endpoints.md and references/data-model.md.

当前位置来自
```
device.lastPos
```
（项圈）或顶级字段
```
posLat/posLong
```
（家庭基站）：
- ```
posLat
```
  （纬度）、
```
posLong
```
  （经度）
- ```
timeMeasure
```
  （时间戳）
- ```
acc
```
  （精度，单位米）或
```
horiPrec
```
  （备选字段）
历史记录使用
```
POST /api/map/getccpositions
```
接口，参数包括：
- ```
devId
```
  、
```
filterTime
```
  （毫秒）、
```
toTime
```
  （毫秒）

详见references/endpoints.md和references/data-model.md。

5) Present results consistently

5) 一致呈现结果

When reporting location, include:

Pet name + device id
Coordinates (lat, lon)
Last update time
Accuracy (if present)
How old the fix is (seconds/minutes since last fix), if possible
Optional: a map link (Google Maps + OpenStreetMap)

Preferred JSON shape (for tool-to-tool handoff):

json

{
  "pet": { "id": 12345, "name": "Fluffy" },
  "last_fix": {
    "lat": 48.137154,
    "lon": 11.576124,
    "time": "2026-02-25T12:34:56+00:00",
    "accuracy_m": 12
  },
  "last_fix_age_s": 90,
  "battery_mv": 4012,
  "battery_percent_est": 78,
  "home": false,
  "links": {
    "google_maps": "https://www.google.com/maps?q=48.137154,11.576124",
    "openstreetmap": "https://www.openstreetmap.org/?mlat=48.137154&mlon=11.576124#map=18/48.137154/11.576124"
  }
}

Notes:

```
battery_percent_est
```
is an estimate derived from voltage (PetTracer reports millivolts, not %).
If there’s no GPS fix, report
```
error=no_recent_fix
```
and include
```
last_contact
```
.

报告位置时需包含：

宠物名称 + 设备ID
坐标（纬度、经度）
最后更新时间
精度（若存在）
定位数据的时效性（自上次定位以来的秒数/分钟数，若可获取）
可选：地图链接（Google Maps + OpenStreetMap）

工具间交互推荐JSON格式：

json

{
  "pet": { "id": 12345, "name": "Fluffy" },
  "last_fix": {
    "lat": 48.137154,
    "lon": 11.576124,
    "time": "2026-02-25T12:34:56+00:00",
    "accuracy_m": 12
  },
  "last_fix_age_s": 90,
  "battery_mv": 4012,
  "battery_percent_est": 78,
  "home": false,
  "links": {
    "google_maps": "https://www.google.com/maps?q=48.137154,11.576124",
    "openstreetmap": "https://www.openstreetmap.org/?mlat=48.137154&mlon=11.576124#map=18/48.137154/11.576124"
  }
}

注意：

```
battery_percent_est
```
是根据电压估算的数值（PetTracer仅报告毫伏值，而非百分比）。
若无GPS定位数据，需报告
```
error=no_recent_fix
```
并包含
```
last_contact
```
（最后联系时间）。

Live tracking (optional, avoid aggressive polling)

实时追踪（可选，避免高频轮询）

If you need frequent updates:

Prefer WebSocket push (avoid aggressive polling).
Only fall back to polling if WebSocket is not possible; keep polling ≥ 60s by default.

Install dependency:

bash

pip install aiohttp

Then run:

bash

python scripts/pettracer_watch.py --pet "Fluffy"

See:

references/websocket.md
```
scripts/pettracer_watch.py
```
for a working SockJS/STOMP implementation.

若需要频繁更新：

优先使用WebSocket推送（避免高频轮询）。
仅在WebSocket不可用时才退回到轮询模式；默认轮询间隔≥60秒。

安装依赖：

bash

pip install aiohttp

运行命令：

bash

python scripts/pettracer_watch.py --pet "Fluffy"

详见：

references/websocket.md
```
scripts/pettracer_watch.py
```
（已实现的SockJS/STOMP示例）

Troubleshooting playbook

故障排查指南

No location /

lastPos

is missing

无位置数据 /

lastPos

字段缺失

Common reasons:

Collar hasn’t reported a GPS fix recently (indoors, low signal).
Battery low / collar off.
Subscription expired.

Action:

Report “no recent fix” and show
```
lastContact
```
if available.
Suggest switching to a higher-frequency mode (Fast/Live) in the PetTracer app/portal only if the user asks (see references/modes.md).

常见原因：

项圈近期未上报GPS定位（室内环境、信号弱）。
电量低 / 项圈已关闭。
订阅已过期。

处理步骤：

报告“无近期定位数据”，若有则显示
```
lastContact
```
（最后联系时间）。
仅在用户询问时，建议在PetTracer应用/门户中切换至高频率模式（快速/实时）（详见references/modes.md）。

Auth failures (401 / invalid_auth)

认证失败（401 / invalid_auth）

Re-login to obtain a fresh
```
access_token
```
.
Confirm the login payload uses keys
```
login
```
+
```
password
```
(not
```
username
```
).

重新登录获取新的
```
access_token
```
。
确认登录请求体使用
```
login
```
+
```
password
```
作为键名（而非
```
username
```
）。

Rate limiting / service respect

速率限制 / 服务友好性

Avoid tight loops against
```
/map/getccs
```
.
Prefer WebSocket for near-real-time tracking.

避免对
```
/map/getccs
```
接口进行循环调用。
近实时追踪优先使用WebSocket。

THE EXACT PROMPT — Location response format

位置响应格式规范

Use this when the user wants a human-readable answer:

Give the pet’s latest known PetTracer location.

Include:
- Pet name + device id
- Time of last fix (and last contact if different)
- Coordinates + map link(s)
- Accuracy (metres) if present
- One-line assessment: “recent fix” vs “stale fix” (use last_fix_age_s if available; interpret in the context of the current tracking mode)

当用户需要易读的人工回复时，遵循以下格式：

提供宠物的最新PetTracer定位信息。

需包含：
- 宠物名称 + 设备ID
- 最后定位时间（若最后联系时间不同则一并显示）
- 坐标 + 地图链接
- 精度（单位米，若存在）
- 一行评估结论：“近期定位”或“过期定位”（若可获取last_fix_age_s则使用该值；结合当前追踪模式判断）

tracking-pettracer-location

Original

Translation

Tracking PetTracer pet location

追踪PetTracer宠物位置

Why this exists

开发背景

Quick start

快速开始

Snapshot location (recommended default)

快照定位（推荐默认方式）

Get location history (last 6 hours)

获取位置历史记录（最近6小时）

Core workflow the agent should follow

代理应遵循的核心工作流

1) Decide: snapshot vs history vs live updates

1) 选择模式：快照、历史记录或实时更新

2) Authenticate safely

2) 安全认证

3) Identify the right device

3) 识别正确设备

4) Fetch location data

4) 获取位置数据

5) Present results consistently

5) 一致呈现结果

Live tracking (optional, avoid aggressive polling)

实时追踪（可选，避免高频轮询）

Troubleshooting playbook

故障排查指南

No location /
`lastPos`
is missing

无位置数据 /
`lastPos`
字段缺失

Auth failures (401 / invalid_auth)

认证失败（401 / invalid_auth）

Rate limiting / service respect

速率限制 / 服务友好性

THE EXACT PROMPT — Location response format

位置响应格式规范

tracking-pettracer-location

Original

Translation

Tracking PetTracer pet location

追踪PetTracer宠物位置

Why this exists

开发背景

Quick start

快速开始

Snapshot location (recommended default)

快照定位（推荐默认方式）

Get location history (last 6 hours)

获取位置历史记录（最近6小时）

Core workflow the agent should follow

代理应遵循的核心工作流

1) Decide: snapshot vs history vs live updates

1) 选择模式：快照、历史记录或实时更新

2) Authenticate safely

2) 安全认证

3) Identify the right device

3) 识别正确设备

4) Fetch location data

4) 获取位置数据

5) Present results consistently

5) 一致呈现结果

Live tracking (optional, avoid aggressive polling)

实时追踪（可选，避免高频轮询）

Troubleshooting playbook

故障排查指南

No location / lastPos is missing

无位置数据 / lastPos字段缺失

Auth failures (401 / invalid_auth)

认证失败（401 / invalid_auth）

Rate limiting / service respect

速率限制 / 服务友好性

THE EXACT PROMPT — Location response format

位置响应格式规范

No location /
`lastPos`
is missing

无位置数据 /
`lastPos`
字段缺失