活动跟踪：代理程序 API（面向开发人员）

本指南面向开发人员。Kaam360 桌面代理程序通过位于 /api/agent/v1 的小型 Web API 与 Kaam360 通信。供 Postman 等工具使用的完整说明位于 /api/agent/v1/openapi.json。如何在 Kaam360 中设置跟踪，请参阅 活动跟踪指南。

每次调用的规则

• 只能通过 HTTPS。普通 HTTP 会被拒绝。
• 发送 JSON（Content-Type: application/json），截图除外，截图以表单方式上传。
• 登记之后，每次调用都把设备密钥作为 Authorization: Bearer 加密钥发送（以 kad_ 开头）。把它保存在系统的安全存储中（Windows DPAPI、macOS 钥匙串）。Kaam360 只保存它的指纹。
• 回复为 { "data": ... }。拒绝为 { "error": { "code", "message" } } 并带 HTTP 状态：401 表示密钥错误或已撤销（需重新登记），403 表示电脑已暂停或功能已关闭，413 表示一次发送太多，422 表示字段错误，429 表示调用太频繁（等待 Retry-After 中的秒数）。
• 绝不发送按键、输入的文字、密码，以及消息和文档的内容。网站只发送域名。

1. 登记：POST /register

发送 设备 中的登记代码、您为这次安装生成并保留的 id（installId）、电脑名称、os（windows 或 macos）、osVersion、agentVersion，以及（如知道）此人的工作邮箱。回复包含设备密钥（只显示这一次）和规则。同一地址每小时最多 20 次登记。

2. 连接：POST /heartbeat

每隔 heartbeatSeconds（默认五分钟）发送 agentVersion、电脑时钟（sentAtUtc）和等待发送的片段数量。回复包含当前规则（policy），以及电脑是否已暂停或尚未分配人员。用 GET /policy 只读取规则。

规则告诉代理程序：trackingEnabled（为 false 时不记录任何内容）、workHoursOnly 以及 workStart、workEnd、workDays 和时区、neverRecord（要跳过的程序和域名）、recordTitles、screenshots（enabled、intervalMinutes、blur、maxBytes）、idleMinutes、uploadBatchSize、maxBatchSlices、maxBufferDays、noticeText（首次启动时以及从托盘图标显示）和 minAgentVersion。

3. 发送活动：POST /activity

发送您自己的 batchId、sentAtUtc 和最多 1000 个片段（最多 1 MB）。每个片段包含 start 和 end（UTC）、app（程序）、title（仅在 recordTitles 开启时）、domain 和 idle。重复发送同一个 batchId 不会产生任何效果，因此连接中断后可以放心重试。回复说明保存了多少，以及其他片段被丢弃的原因：tracking_off、no_person、invalid、too_long（超过 4 小时）、future、too_old（超过 14 天）、never_record 或 outside_hours。电脑时钟偏差超过一分钟会被校正；超过一天会被拒绝。

4. 发送截图：POST /screenshots

仅在开启截图时。以表单上传 file（JPEG、PNG 或 WebP，最多 1 MB）、takenAtUtc、app、domain 和 blurred。blur 开启时请先模糊处理图片：清晰的图片会被拒绝。不要比间隔更频繁。绝不记录列表中的程序或工作时间以外的截图不会被保存。

离线

没有连接时把片段保存在电脑上（加密，最多 maxBufferDays 天），连接恢复后分批发送。

5. 更新：GET /update

每天调用一次 GET /update，带上 os（windows 或 macos）和代理程序的版本。答复包含 latestVersion、downloadUrl、sha256、sizeBytes、updateAvailable 和 updateRequired（代理程序比组织接受的最低版本旧）。只从同一 Kaam360 地址上的 downloadUrl 下载，运行前检查文件大小、SHA-256 指纹和代码签名。最新的安装程序也对所有人开放，地址为 /download/agent/windows（它是一个程序而不是数据：连接电脑靠的是登记代码）。Mac 安装包 (.pkg) 位于 /download/agent/macos；在 Mac 上请检查文件以 xar! 开头，并且当您的应用使用 Apple Developer ID 签名时，pkgutil --check-signature 显示的是同一团队。

Kaam360 构建的 Windows 代理程序遵循以上所有规定；其代码位于 Kaam360 源代码的 agents 文件夹中，docs/activity-agent.md 对其有说明。