认证

Agent Analytics 使用三种不同的凭证。它们承担不同职责，不能互换。

代理会话 (`aas_*`)

代理会话用于：

在正常产品流程里，你通常不会手动粘贴这个令牌。托管审批流程会为代理或 CLI 创建它，并保存在本地供后续使用。

如果你之后想查看或撤销代理持有的登录，请打开 app.agentanalytics.sh，进入 Account Settings → Agent Sessions。

这个页面会显示当前活动的托管代理会话，例如：

当你想在服务器端撤销某一个会话时，就在这里点击 Disconnect。

API 密钥用于：

可以通过 X-API-Key 头或 ?key= 查询参数传递。

curl "https://api.agentanalytics.sh/stats?project=my-site&since=7d" \
  -H "X-API-Key: aak_..."

请把它当作密钥信息处理。

项目令牌用于：

这个 token 设计上就是公开的。它用于标识事件接收时对应的项目，因此本来就会出现在 HTML 中。

<script defer src="https://api.agentanalytics.sh/tracker.js"
        data-project="my-site"
        data-token="aat_..."></script>

不要把 API key 放进客户端 tracker 中。tracker 只使用公开的 project token。

如果你使用官方 CLI，它提供浏览器审批的本地 auth 命令：

npx --yes @agent-analytics/[email protected] login：启动浏览器审批，并保存本地 CLI session。
npx --yes @agent-analytics/[email protected] login --detached：为无界面或 issue/thread 风格的运行环境启动同样的流程，此时代理会把审批链接发给你，也可能要求你回贴 finish code。
npx --yes @agent-analytics/[email protected] auth status：显示本地 CLI auth 是否存在、config 存在哪里、当前使用哪种 credential store，但不会打印 token 值。
npx --yes @agent-analytics/[email protected] upgrade-link --detached：当 free 账户遇到付费分析任务时，生成给真人确认付款的交接链接。
npx --yes @agent-analytics/[email protected] logout：清除本地保存的 CLI auth；如果有已保存的 agent session ID 和可用 token material，会尽力撤销该 agent session。

logout 不是 logout-all-devices。浏览器 /auth/logout 仅支持 POST，只清除当前浏览器 session，不会断开 CLI agents。要明确断开选定的 agent sessions，请使用 Web 应用中的 Agent Sessions。

Scoped agent sessions 不能生成或轮换原始账户 API key。兼容性 API key 请在 dashboard 中管理。

Credential storage 是自动的。普通用户不需要设置环境变量。

macOS 和 Windows 默认把 CLI agent-session secret 存到系统 keychain。
Linux 和无界面运行环境默认使用 config-file storage。
已经存在的 file-stored session 会在下一次 authenticated command 时自动迁移到 native keychain（如果 native storage 可用）。
AGENT_ANALYTICS_CREDENTIAL_STORE 只是高级 troubleshooting override。支持的值是 auto、native、file。