蝉镜凭证守护

功能说明

仅通过本地命令引导用户配置或校验蝉镜的 AK/SK 与 Token，并打开登录页面；不在对话中索取密钥。可与其他蝉镜相关技能配合使用。

运行依赖

• python3 以及 scripts/chanjing_config.py、scripts/open_login_page.py、scripts/chanjing_get_token.py 等脚本文件

环境变量与机器可读声明

• 环境变量键名与说明：**manifest.yaml**（environment 段）及本文
• 变量、写盘路径与权限：**manifest.yaml**

使用命令

• ClawHub（slug 以注册表为准）：clawhub run chanjing-credentials-guard
• 本仓库：python skills/chanjing-credentials-guard/scripts/chanjing_config.py --status

何时运行

1. 当用户请求配置或获取蝉镜密钥（AK/SK）时：使用此技能引导本地配置。
2. 在调用蝉镜 API 前发现凭证缺失或无效时：使用此技能恢复本地配置。

该技能为本地凭证引导工具，非跨技能运行时依赖。

执行流程

1. 检查本地 AK/SK 是否存在
   └─ 不存在 → 执行 open_login_page.py（在默认浏览器中打开登录页）→ 提示用户运行本地配置命令
   └─ 存在 → 继续

2. 检查本地 Token 是否存在且未过期
   └─ 不存在 → 调用 API 请求或刷新 Token → 保存结果
   └─ 存在 → 继续

3. 提示用户继续执行目标操作

凭证存储（AK/SK 从配置文件读取）

AK/SK 与 Token 均从同一配置文件读取。路径与格式遵循本技能中的脚本 **scripts/chanjing_config.py**。

• 路径：~/.chanjing/credentials.json（目录路径由环境变量 **CHANJING_OPENAPI_CREDENTIALS_DIR 覆盖，兼容 CHANJING_CONFIG_DIR**）
• 格式：

{
  "app_id": "您的 Access Key",
  "secret_key": "您的 Secret Key",
  "access_token": "可选，自动生成",
  "expire_in": 1721289220
}

expire_in 为 Unix 时间戳。Token 有效期约为 24 小时；建议在到期前 5 分钟刷新。

当 AK/SK 缺失时

当本地 app_id 或 secret_key 缺失时：

1. 打开登录页面：执行 open_login_page.py 脚本，在默认浏览器中打开蝉镜登录页（https://www.chanjing.cc/openapi/login）。
2. 要求用户在本地运行配置命令：

- 仅显示命令；用户需在终端中手动执行。

1. 禁止在聊天中索取密钥：

- 不得要求用户将 AK/SK 粘贴至对话中。

- 不得在聊天摘要中回显或存储 AK/SK。

1. 配置完成后：

- 提示用户运行状态检查命令，再继续执行目标操作。

设置 AK/SK 的命令（任选其一）：

python scripts/chanjing_config.py --ak <your_app_id> --sk <your_secret_key>
python skills/chanjing-credentials-guard/scripts/chanjing_config.py --ak <your_app_id> --sk <your_secret_key>

手动打开登录页的命令：python skills/chanjing-credentials-guard/scripts/open_login_page.py

当用户希望生成密钥时的引导流程

当用户明确表示要生成蝉镜密钥、获取密钥或配置 AK/SK时，请按以下流程操作：

第一步：检查是否已配置

检查本地 AK/SK 是否已存在（读取 ~/.chanjing/credentials.json 中 app_id 和 secret_key 是否非空），或运行以下命令确认状态：

python skills/chanjing-credentials-guard/scripts/chanjing_config.py --status

第二步：根据结果分支处理

• 若已配置：询问用户是否要覆盖本地配置。

- 若是，继续执行引导步骤。

- 若否，停止操作。

• 若未配置：直接执行下方“引导步骤”。

引导步骤（未配置或用户确认重新配置时）

1. **执行 open_login_page.py**：在默认浏览器中打开蝉镜登录页面。
2. 清晰说明页面流程：

- 新用户会自动注册，当前页面将显示 App ID 和 Secret Key，并提供复制按钮。

- 已有用户可能被重定向至控制台；请告知其前往左侧菜单的 API 密钥 页面查看或重置密钥。

1. 提示用户运行本地命令配置 AK/SK：

   python skills/chanjing-credentials-guard/scripts/chanjing_config.py --ak <your_app_id> --sk <your_secret_key>

1. 密钥处理规则：

- 不得要求用户在聊天中粘贴 AK/SK。

- 若用户仍执意在聊天中分享密钥，请提醒其立即轮换密钥，并继续使用本地命令方式完成配置。

1. 配置完成后：

- 执行状态检查：

python skills/chanjing-credentials-guard/scripts/chanjing_config.py --status

- 确认无误后，继续执行目标蝉镜操作。

Token API（详见 chanjing-openapi.yaml）

POST https://open-api.chanjing.cc/open/v1/access_token
Content-Type: application/json

请求体：

{
  "app_id": "{{app_id}}",
  "secret_key": "{{secret_key}}"
}

成功响应（code: 0）：

{
  "code": 0,
  "msg": "success",
  "data": {
    "access_token": "xxx",
    "expire_in": 1721289220
  }
}

• expire_in：Token 过期时间的 Unix 时间戳
• 若 code !== 0，表示 AK/SK 无效或请求失败

验证逻辑

1. AK/SK：从配置文件读取（路径与格式见上文，依据 chanjing_config.py）；确保 app_id 与 secret_key 均不为空。
2. Token：确保 access_token 存在，且 expire_in > 当前时间 + 300（提前 5 分钟刷新）。
3. Token 刷新：调用上述 API，将返回的 access_token 与 expire_in 写回文件。

快捷方式：运行 python skills/chanjing-credentials-guard/scripts/chanjing_get_token.py；成功时输出 access_token，失败时输出引导信息。

安全边界

• 本技能仅处理本地凭证引导。
• 不需要安装钩子或系统级权限。
• 不应自动执行无关技能。
• 不应通过聊天内容接收 AK/SK。

Shell 配置

Chanjing 凭据保护

快速开始

# 打开登录页面（当 AK/SK 缺失时会自动运行）
python skills/chanjing-credentials-guard/scripts/open_login_page.py

# 手动设置 AK/SK
python skills/chanjing-credentials-guard/scripts/chanjing_config.py --ak <app_id> --sk <secret_key>

# 查看当前状态
python skills/chanjing-credentials-guard/scripts/chanjing_config.py --status

与其他技能的协作

• 其他 Chanjing 技能可能使用相同的本地配置路径和格式，但应保持各自的运行时认证逻辑。
• 当用户明确请求凭据指导时，本工具可作为可选的设置辅助。

参考资料

• [reference.md](reference.md)：API 和存储格式详情
• chanjing-openapi.yaml：/access_token、dto.OpenAccessTokenReq、dto.OpenAccessTokenResp