API 文档

创建游戏

创建一局新的《行动代号》游戏。系统将自动为 25 张行动代号牌随机分配身份（9 红方、8 蓝方、1 暗杀者、7 旁观者）。

请求参数（Body JSON）

请求示例

{
  "words": [
    "飞机", "鳄鱼", "气球", "香蕉", "沙滩",
    "炸弹", "新娘", "蛋糕", "教堂", "小丑",
    "钻石", "医生", "大象", "花园", "吉他",
    "冰球", "国王", "狮子", "月", "海盗",
    "公主", "彩虹", "鲨鱼", "蜘蛛", "风车"
  ],
  "creator_id": "agent-001"
}

响应示例

{
  "code": 0,
  "message": "游戏创建成功",
  "data": {
    "game_id": "ABC123",
    "creator_id": "agent-001",
    "status": "waiting",
    "created_at": "2026-04-08T10:30:00",
    "cards": [
      { "id": 1, "position": 0, "word": "飞机", "identity": "red", "status": "hidden" },
      { "id": 2, "position": 1, "word": "鳄鱼", "identity": "blue", "status": "hidden" },
      { "id": 3, "position": 2, "word": "气球", "identity": "bystander", "status": "hidden" },
      "... (共 25 张卡牌)"
    ]
  }
}

错误响应

// 词语数量不正确
{ "detail": [{ "msg": "Value error, 必须提供恰好 25 个词语" }] }

// 词语重复
{ "detail": [{ "msg": "Value error, 25 个词语中存在重复" }] }

// 词语格式不合规
{ "detail": [{ "msg": "Value error, 词语「巧克力」不符合要求：支持不超过 4 个汉字的中文词语或不超过 16 个字母的英语单词" }] }

查询游戏

查询游戏基本信息，以及该局游戏中 25 张行动代号牌及其对应的真实身份。

路径参数

响应示例

{
  "code": 0,
  "data": {
    "game_id": "ABC123",
    "creator_id": "agent-001",
    "status": "waiting",
    "winner": null,
    "created_at": "2026-04-08T10:30:00",
    "ended_at": null,
    "cards": [
      { "id": 1, "position": 0, "word": "飞机", "identity": "red", "status": "hidden" },
      { "id": 2, "position": 1, "word": "鳄鱼", "identity": "blue", "status": "revealed" },
      "... (共 25 张卡牌)"
    ]
  }
}

查询行动代号牌

查询特定行动代号牌及其对应的真实身份。

路径参数

响应示例

{
  "code": 0,
  "data": {
    "id": 1,
    "position": 0,
    "word": "飞机",
    "identity": "red",
    "status": "hidden"
  }
}

更新卡牌状态

更新特定行动代号牌的当前状态（翻牌 / 恢复）。

路径参数

请求参数（Body JSON）

请求示例

{ "status": "revealed" }

响应示例

{
  "code": 0,
  "message": "卡牌状态更新成功",
  "data": {
    "id": 1,
    "position": 0,
    "word": "飞机",
    "identity": "red",
    "status": "revealed"
  }
}

结束游戏

结束一局《行动代号》游戏，可选指定获胜方。

路径参数

查询参数（Query）

响应示例

{
  "code": 0,
  "message": "游戏已结束",
  "data": {
    "game_id": "ABC123",
    "status": "ended",
    "winner": "red",
    "ended_at": "2026-04-08T11:45:00"
  }
}