腾讯广告鉴权

问题背景与目标

在使用腾讯广告 API（api.e.qq.com）进行数据查询、营销投放或数据分析时，首要步骤是完成身份鉴权。这个过程涉及获取、存储和使用敏感的 X-MKT-API-Key 凭证。直接管理这类 API 密钥面临几个具体挑战：

• 安全风险：密钥不应在对话或日志中明文暴露，避免意外泄露。
• 配置繁琐：手动在代码或配置文件中设置密钥，容易出错且不利于在不同工具或技能间共享。
• 状态不透明：缺乏一种快速机制来检查当前的鉴权状态是否有效，导致错误排查困难。

本技能 tencentads-auth 旨在通过标准化的对话式流程，引导用户安全、高效地完成腾讯广告 API 的鉴权配置，为后续所有 tencentads-* 系列技能提供统一的认证基础。

技能工作原理

该技能的核心是 安全的凭据存储与自动化的状态检查。它不执行广告业务逻辑，而是专注于管理认证生命周期。

核心能力与关键步骤

1. 前置状态检查：在触发任何鉴权流程前，技能会自动执行 auth-status.mjs 脚本。该脚本会读取本地存储的凭据，验证其有效性。如果返回状态为 "active"，则表明凭据有效，无需用户重复操作。

1. 对话式密钥配置：当需要配置或更新凭据时，Agent 会引导用户在对话中发送其 API Key（格式为 mkt_ 开头）。收到后，Agent 绝不 在回复中回显或重复此密钥内容，而是立即调用 auth-save-apikey.mjs 脚本进行安全保存。

1. 集中化凭据管理：所有 tencentads-* 技能共享一个统一的存储机制。保存的 API Key 被后续所有需要调用腾讯广告 API 的技能（例如，投放、报表技能）通过内部的 callApi 函数自动读取，实现了“一次配置，全局可用”。

1. 认证失败处理：当其他技能（如 tencentads-query）在调用 API 时遇到认证错误（例如，返回 AUTH_REQUIRED 或 AUTH_EXPIRED），它们会引用本技能。本技能随后引导用户重新提供密钥并更新，然后自动重试引发错误的原始操作。

脚本调用规范

• 所有脚本必须在技能根目录下运行。
• 参数传递统一使用显式命令行参数（例如 --api-key），而非传递 JSON 字符串，以确保跨操作系统的兼容性。
• 凭据保存脚本 auth-save-apikey.mjs 是敏感操作，必须由 Agent 直接调用，避免凭据通过其他渠道暴露。

使用边界与注意事项

• 前置依赖：必须先通过 npm install tencentads-cli@1.0.0 安装 CLI 工具，且环境需要 Node.js 20 或以上版本。
• 技能定位：本技能是一个基础服务组件，不提供直接的广告数据查询或操作能力。它的唯一目的是管理认证，所有广告操作能力由其他 tencentads-* 技能提供。
• 安全原则重申：严禁在对话窗口、日志或任何非安全存储位置回显、记录 API Key。Agent 的职责是作为一个安全的中介，处理密钥的获取与持久化。
• 凭据存储：凭据存储在本地文件系统中。在共享环境或多用户场景下，需注意文件系统的访问权限控制，以防止凭据被未授权访问。
• 适用范围：本技能仅适用于通过 tencentads-cli 及其关联技能调用腾讯广告 API 的场景。不适用于其他云服务或不基于此 CLI 框架的集成。