chanjing-auth

Chanjing OAuth 身份验证

为 Chanjing 平台的所有功能（数字人、TTS、背景音乐、音效）提供集中式身份验证管理。

适用场景

• 检查用户是否已通过 Chanjing 平台身份验证
• 引导用户完成 OAuth 登录流程
• 排查凭据或令牌问题
• 为 CI/CD 或无头环境设置身份验证

请勿用于： 实际调用 Chanjing 服务的 API → 委托给特定功能的技能（chanjing-digital-human 等）

---

快速开始

# Check current auth status
npx framevideo auth status

# Check if authenticated (exit code)
npx framevideo auth status --check

# Get status as JSON
npx framevideo auth status --json

如果尚未通过身份验证，请使用以下任一种身份验证方式。

---

核心概念

OAuth CLI 浏览器登录

标准身份验证流程：

1. 用户运行 framevideo auth login，或在 Studio 中点击登录
2. CLI 在浏览器中打开 Chanjing 授权页面
3. 用户在浏览器中批准授权
4. 浏览器重定向到本地回调服务
5. CLI 接收令牌并将其保存到凭据存储区
6. 所有 Chanjing 功能现在都可以访问平台

凭据存储

令牌存储在 ~/.chanjing/credentials（遵循 CHANJING_CONFIG_DIR 环境变量的设置）中的 oauth 块内：

{
  "oauth": {
    "access_token": "...",
    "refresh_token": "...",
    "expires_at": 1234567890
  }
}

**切勿读取、打印、记录或提交这些令牌。**请使用 packages/cli/src/auth/store.ts 中共享的身份验证存储 API。

插件 API 客户端

所有 Chanjing API 请求都使用 Authorization: Bearer <access_token> 请求头。客户端负责：

• 令牌过期时刷新令牌
• 遇到 401 时自动重试
• 报告错误

位置：packages/cli/src/tts/chanjingOpenapi.ts

---

身份验证方式

方式 1：交互式登录（推荐）

适用于开发和本地使用：

npx framevideo auth login

打开浏览器以完成 OAuth 流程。需要用户交互。

方式 2：Studio 登录（适合 Agent）

与 Agent 配合工作且缺少 OAuth 身份验证时：

1. 启动或复用预览服务：npx framevideo preview
2. 在浏览器中打开 Studio 项目 URL
3. 导航到 Digital Human、Voice 或账户面板
4. 点击登录按钮以启动 OAuth 流程
5. 完成浏览器授权
6. 使用 npx framevideo auth status 验证

这种方式为何优于仅提供 CLI 指引：

• 为用户提供可视化反馈
• 融入自然工作流
• Agent 可以轮询状态端点

方式 3：CI/CD 或无头环境

适用于没有浏览器的自动化环境：

1. 从交互式登录会话获取刷新令牌
2. 设置 CHANJING_REFRESH_TOKEN 环境变量
3. CLI 将使用刷新令牌获取访问令牌

**安全提示：**将刷新令牌视为机密信息。请使用安全的机密管理方式（GitHub Secrets、CI 保管库等）。

---

缺少凭据时的用户体验

当由 Agent 编写的工作流需要使用 Chanjing 功能，但缺少身份验证时：

如果预览可用（优先）：

1. 启动或复用 npx framevideo preview
2. 在内置浏览器中打开 Studio 项目 URL
3. 导航到需要使用 Chanjing 的面板（Digital Human、Voice、账户）
4. 点击登录以启动 OAuth CLI 浏览器登录
5. 用户完成浏览器授权
6. 重新检查身份验证状态，然后继续工作流

如果预览不可用：

改用仅提供 CLI 的指引：

npx framevideo auth login

然后继续工作流。

请勿：

• ❌ 预览可用时，仍仅提供环境变量指引
• ❌ 在凭据存储区之外打印或保存令牌
• ❌ 要求用户手动编辑 ~/.chanjing/credentials
• ❌ 使用已弃用的 app_id、secret_key 或 CHANJING_OPENAPI_ACCESS_TOKEN

---

Studio 集成

Studio 通过插件路由提供身份验证状态和登录界面。

身份验证状态端点

GET /api/projects/:id/chanjing/auth/status

返回：

{
  "authenticated": true,
  "user": {
    "id": "...",
    "name": "..."
  }
}

引导用户在 Studio 中登录后，可使用此端点轮询身份验证状态。

登录按钮

可在以下位置找到：

• Digital Human 面板（Studio → Digital Human → Login）
• Voice 面板（Studio → Voice → Login）
• 账户设置（Studio → Settings → Chanjing Account）

点击任一登录按钮都会触发相同的 OAuth CLI 浏览器登录流程。

---

故障排查

“Not authenticated” 错误

检查：

npx framevideo auth status

修复：

npx framevideo auth login

令牌过期

客户端会自动刷新令牌。如果刷新失败：

# Clear credentials and re-login
rm ~/.chanjing/credentials
npx framevideo auth login

“Invalid token” 或 401 错误

凭据存储可能已损坏：

# Inspect (redacted output)
npx framevideo auth status --json

# Clear and re-login
rm ~/.chanjing/credentials
npx framevideo auth login

CI/CD 身份验证失败

1. 确认已设置 CHANJING_REFRESH_TOKEN
2. 检查令牌是否已过期（刷新令牌通常有效期为 30-90 天）
3. 从交互式会话获取新的刷新令牌

---

与其他技能集成

chanjing-digital-human

使用此身份验证来：

• 列出数字人和语音
• 提交网站项目合成任务
• 轮询任务状态
• 下载生成的视频

chanjing-media（计划中）

使用此身份验证来：

• 列出并下载背景音乐
• 列出并下载音效

framevideo-media

不使用此身份验证。 本地 Kokoro TTS 离线运行，无需凭据。

---

安全最佳实践

1. 切勿打印令牌——不要在日志、错误消息或 Agent 响应中打印
2. 使用凭据存储 API——不要直接读取 ~/.chanjing/credentials
3. 不要将令牌提交到 Git——将凭据文件添加到 .gitignore
4. 保护 CI 密钥——使用密钥管理来存储 CHANJING_REFRESH_TOKEN
5. 不要复制独立脚本——复用共享身份验证客户端，不要重复实现

---

验证

完成身份验证后：

# Should show "authenticated: true"
npx framevideo auth status

# Should list available resources
npx framevideo chanjing music categories --json

如果两项都成功，则表示身份验证正常。

---

参考资料

• 身份验证存储实现：packages/cli/src/auth/store.ts
• 插件 API 客户端：packages/cli/src/tts/chanjingOpenapi.ts
• Studio 身份验证路由：参见 chanjing-digital-human 技能中的 references/studio-routes.md