SDK 使用指南

我们提供了 Python SDK（位于 sdk.py），封装了底层的 stdio 二进制通信协议，可以直接调用。

快速开始

from sdk import SDK

sdk = SDK()

# 游戏启动时会收到一条欢迎消息，需要先消费掉
welcome = sdk._receive()

# 获取背景
resp = sdk.request("background")
print(resp["background"])

# 与 NPC 对话
resp = sdk.request("chat", npc="XiaoDingAng", question="案发时你在哪？", evidences=[])
print(resp["reply"])            # NPC 回复
print(resp["unlock_testimony"]) # 新解锁的证言

# 提交答案
resp = sdk.request("answer", murderer="某人", motivation="动机...", method="手法...")

API 一览

方法	说明
sdk.request(action, **kwargs)	通用方法，发送任意 action 请求并返回响应字典
sdk.call_llm(**kwargs)	调用 LLM（通过游戏代理），参数透传给 OpenAI 接口

request 方法支持所有上文 API 章节中列出的 action，使用方式：

# 所有 action 均通过 request 调用，kwargs 作为 JSON 字段发送
sdk.request("background")
sdk.request("stage")
sdk.request("hint")
sdk.request("npcs")
sdk.request("marks")
sdk.request("testimony")
sdk.request("others")
sdk.request("achievements")
sdk.request("chat", npc="NPC名", question="问题", evidences=["证据ID"])
sdk.request("answer", murderer="凶手", motivation="动机", method="手法")

调用 LLM

通过 call_llm 方法可以让游戏服务器代理你的 LLM 调用请求，无需本地配置 API KEY：

resp = sdk.call_llm(
    model="qwen-max",
    messages=[
        {"role": "system", "content": "你是一个推理助手"},
        {"role": "user", "content": "根据以下线索分析凶手..."}
    ],
    temperature=0.7,
)
if "error" not in resp:
    answer = resp["choices"][0]["message"]["content"]
else:
    print(f"调用失败: {resp['error']}")

通信协议说明

SDK 底层采用二进制帧协议，无需手动处理：

• 发送：4 字节大端序长度前缀 + UTF-8 编码的 JSON 字符串
• 接收：4 字节头部 + 一行 JSON 字符串（\n 结尾）

注意事项

• stdout 被用于与 Judger 通信，日志必须输出到 stderr
• 游戏启动后会先收到一条欢迎消息，需要先调用 sdk._receive() 消费掉，再开始正常交互
• 多剧本模式下，提交 answer 后会自动切换到下一个剧本，需要重新获取背景和 NPC 列表
• call_llm 不支持流式响应，使用前请检查响应中是否存在 error 字段