生成角色卡评估 · Generate Card Review

让 AI 对自己的角色卡做一次质量评估，产出 1–10 综合评分与结构化报告（细项评分、严重问题、亮点、优先改进、整体评价）。评分主要衡量角色卡的内容完整度与丰富度（而非文学质量）：

• 评分会写回卡片（cardReviewScore），分数越高，发布后获得的冷启动推荐权重越多。
• 综合评分达到 7.0 分及以上时，卡片会自动发布到官方 Telegram 频道（可用 skipAutoPublish 关闭）。
• 报告仅作者本人可见，不会展示给其他用户。

评估基于已保存的角色卡内容：如果刚修改过设定，请先调用 创建 / 编辑角色卡 保存，再发起评估。

接口地址

POST https://xiangcao.ai/api/gen-card-review

同步接口：AI 评审耗时较长（通常数十秒），请设置充足的请求超时，并避免对同一张卡重复并发提交。评估完成后可随时用 查询评估报告 取回最近一次结果。

鉴权

需要在请求头携带 API Key：

Authorization: Bearer <YOUR_API_KEY>

缺少或无效的 Token 会返回 401。只能评估自己创建的角色卡。

计费

• 每次评估消耗 500 积分（钻石），生成前扣费。
• 评估失败时，已扣积分会自动退还。

请求体（JSON）

interface GenCardReviewRequest {
  /** 要评估的角色卡 ID */
  characterId: string;
  /** true = 只出报告，不自动发布到频道；默认 false */
  skipAutoPublish?: boolean;
}

自动发布行为

未传 skipAutoPublish（或为 false）时，若综合评分 ≥ 7.0，卡片会自动发布到官方 Telegram 频道——与卡片可见性无关，即使 status 为归档也会发布。自动发布失败不影响评估结果的返回。只想拿报告、不想上频道时，请显式传 skipAutoPublish: true。

响应（JSON）

返回本次评估的完整文档：

评审报告结构 report

报告由 AI 生成，所有字段都可能缺失（模型偶尔漏返回），消费方请自行容错。

评审维度 dimensions

每个维度包含 score（1–10）与 issues（问题列表，每项含 description / evidence / suggestion）：

类型定义（TypeScript）

interface GenCardReviewResponse {
  /** 结构化评审报告 */
  report: CardReviewReport;
  /** 评估时间戳（毫秒） */
  createdAt: number;
  /** 发起评估的用户 ID */
  reviewedBy: string;
}

/** 所有字段均可能缺失，请容错处理 */
interface CardReviewReport {
  /** 综合评分（加权，1.0-10.0），≥ 7.0 自动发布 */
  overall_score?: number;
  /** 各维度评分与诊断 */
  dimensions?: Partial<Record<CardReviewDimensionKey, CardReviewDimension>>;
  /** 严重问题（必须修复） */
  critical_issues?: string[];
  /** 亮点 */
  highlights?: string[];
  /** 优先改进项（3-5 个，按重要性排序） */
  improvement_priority?: string[];
  /** 整体评价（150-300 字） */
  summary?: string;
}

type CardReviewDimensionKey =
  | "character_design"      // 角色塑造
  | "content_completeness"  // 内容完成度
  | "opening_experience"    // 开场体验
  | "interaction_design"    // 互动设计
  | "basic_compliance";     // 基础规范

interface CardReviewDimension {
  /** 维度评分 1-10 */
  score?: number;
  /** 具体问题列表 */
  issues?: CardReviewIssue[];
}

interface CardReviewIssue {
  /** 问题描述 */
  description?: string;
  /** 对应的原文引用（80 字以内） */
  evidence?: string;
  /** 改进建议 */
  suggestion?: string;
}

示例

请求（只出报告，不自动发布）：

curl -X POST "https://xiangcao.ai/api/gen-card-review" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "characterId": "card_abc123",
    "skipAutoPublish": true
  }'

响应（节选）：

{
  "report": {
    "overall_score": 7.6,
    "dimensions": {
      "character_design": { "score": 8, "issues": [] },
      "content_completeness": {
        "score": 7,
        "issues": [
          {
            "description": "世界观背景交代较少",
            "evidence": "描述中仅提到「都市悬疑」，未展开案件背景",
            "suggestion": "补充案件背景与角色动机，丰富 scenario 字段"
          }
        ]
      },
      "opening_experience": { "score": 8, "issues": [] },
      "interaction_design": { "score": 7, "issues": [] },
      "basic_compliance": { "score": 9, "issues": [] }
    },
    "critical_issues": [],
    "highlights": ["人物性格鲜明，开场白代入感强"],
    "improvement_priority": ["丰富场景设定", "补充对话示例", "完善状态追踪配置"],
    "summary": "整体完成度较高，角色形象与开场体验出色……"
  },
  "createdAt": 1752480000000,
  "reviewedBy": "user_001"
}

错误处理

出错时返回相应 HTTP 状态码及 JSON：{ "success": false, "error": "..." }。

相关接口

• 查询评估报告：取回最近一次评估结果。
• 创建 / 编辑角色卡：评估前先保存最新设定。