"""
pine_voice —— PineClaw Voice API 的本地【模拟】客户端。
真实的 PineClaw Voice API(https://pineclaw.com/ ,作者团队开发)是一套生产级
电话语音 API:你把「电话号码 + 目标 + 上下文」交给它,它的语音 Agent 会自动完成
拨号、IVR 菜单导航("查询请按 1,转人工请按 0")、与真人多轮对话、实时转录,
最后把整段通话浓缩成一份【结构化通话记录】返回。
本文件不接触真实电话网络,也不需要 PineClaw key。它用 OpenAI 扮演「被叫方」
(IVR 语音菜单 + 人工客服)与「去电的语音 Agent」进行一段多轮对话,从而在本地
复现同样的输入/输出契约:
record = make_phone_call(phone_number, goal, context)
返回的 record 与真实 API 的形状保持一致(transcript / goal_achieved / key_fields ...),
因此上层 ReAct Agent 的代码在切换到真实 PineClaw SDK 时几乎无需改动。
真实接入方式见本目录 README.md「真实接入 PineClaw」一节。
"""
from __future__ import annotations
import hashlib
import json
import os
import re
import time
import uuid
from dataclasses import dataclass, field, asdict
from typing import Any
from openai import OpenAI
# 默认聊天模型:当前便宜旗舰。可用 OPENAI_MODEL 覆盖(如 Moonshot 的 kimi-k3)。
_DEFAULT_MODEL = "gpt-5.6-luna"
def _map_openrouter_model(model: str) -> str:
"""把常见模型名映射为 OpenRouter 的 provider/model 形式。"""
if "/" in model: # 已是 provider/model,原样透传
return model
if model.startswith("gpt-"):
return "openai/" + model
if model.startswith("claude-"):
return "anthropic/claude-opus-4.8"
return "openai/gpt-5.6-luna"
# 延迟创建 client:缺 Key 时由 demo.py 给出友好提示,而非 import 期裸异常。
# 通用回退:优先 OPENAI_API_KEY(可选 OPENAI_BASE_URL 指向兼容网关,如 Moonshot),
# 否则用 OPENROUTER_API_KEY 走 OpenRouter,否则给出清晰错误。
# timeout + 自动重试,避免单次网络/SSL 抖动让整段模拟通话崩溃。
_client = None
_active_model = None
def _resolve() -> tuple[OpenAI, str]:
global _client, _active_model
if _client is not None:
return _client, _active_model
model = os.getenv("OPENAI_MODEL") or _DEFAULT_MODEL
if os.getenv("OPENAI_API_KEY"):
# 直连 OpenAI(或 OPENAI_BASE_URL 指定的兼容网关,如 Moonshot kimi-k3)。
_client = OpenAI(
base_url=os.getenv("OPENAI_BASE_URL") or None,
timeout=60.0,
max_retries=3,
)
_active_model = model
elif os.getenv("OPENROUTER_API_KEY"):
# 回退到 OpenRouter:注意 gpt-5.6* 直连 OpenAI 需组织实名认证,走 OpenRouter 免此步。
_client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.getenv("OPENROUTER_API_KEY"),
timeout=60.0,
max_retries=3,
)
_active_model = _map_openrouter_model(model)
else:
raise RuntimeError(
"未检测到 OPENAI_API_KEY 或 OPENROUTER_API_KEY。请在 .env / 环境变量中至少配置其一"
"(见 env.example),或用 python demo.py --dry-run 走完全离线的脚本演示。"
)
return _client, _active_model
def _get_client() -> OpenAI:
return _resolve()[0]
def default_model() -> str:
"""当前生效的聊天模型名(已按 OpenRouter 映射解析)。"""
return _resolve()[1]
# 一次模拟通话里「去电语音 Agent ↔ 被叫方」最多来回的轮数(一轮 = 双方各说一次)。
_MAX_TURNS = 8
# 结束标记:去电语音 Agent 认为通话目标已完成/无法推进时,在发言末尾附上它。
_END_TOKEN = "[END_CALL]"
# --------------------------------------------------------------------------- #
# 结构化通话记录 —— 与真实 PineClaw Voice API 返回体保持同一形状
# --------------------------------------------------------------------------- #
@dataclass
class CallRecord:
call_id: str
phone_number: str
goal: str
status: str # "completed" / "failed"
goal_achieved: bool # 是否达成通话目标
duration_seconds: int # 通话时长(模拟值)
summary: str # 一句话通话摘要
key_fields: dict[str, Any] # 从通话中抽取的关键信息(确认号、金额、时间...)
transcript: list[dict[str, str]] # 逐轮对话:{"speaker": ..., "text": ...}
follow_up_needed: bool # 是否仍需追问/再拨
follow_up_reason: str # 若需追问,原因是什么
def to_dict(self) -> dict[str, Any]:
return asdict(self)
# --------------------------------------------------------------------------- #
# 内部:调用 OpenAI 生成一次发言
# --------------------------------------------------------------------------- #
def _chat(
messages: list[dict[str, str]],
temperature: float = 0.7,
model: str | None = None,
) -> str:
resp = _get_client().chat.completions.create(
model=model or default_model(),
messages=messages,
temperature=temperature,
)
return (resp.choices[0].message.content or "").strip()
def _callee_system_prompt(goal: str, context: str) -> str:
"""被叫方:先当自动 IVR 语音菜单,被转人工后再扮演人工客服。"""
return (
"你在参与一段【电话客服】通话的角色扮演,扮演【被叫方】(企业客服热线)。\n"
"整通电话分两个阶段,请自然衔接:\n"
"1) 开场你是【自动语音应答(IVR)系统】:先播报欢迎语,再报一个简短的按键菜单"
"(例如『账单查询请按 1,业务办理请按 2,人工服务请按 0』)。\n"
"2) 当来电者选择转人工(按 0 或明确要求人工)后,你切换为【人工客服代表】,"
"自报工号,然后正常应答。\n\n"
"扮演要求:\n"
"- 全程用简体中文口语,像真实电话一样简短自然,不要旁白、不要括号动作。\n"
"- 你可以合理编造本企业的业务细节(如扣费原因、套餐、确认号),要具体、前后一致。\n"
f"- 来电者此行的目标大致是:{goal}\n"
"- 你不必无条件满足对方,可以先解释、再看情况处理;但对方礼貌且诉求合理时,"
"应能给出明确结论(原因/处理结果/确认号等)。\n"
"- 每次只说你(被叫方)这一方的一段话,不要替对方说话。"
)
def _caller_system_prompt(phone_number: str, goal: str, context: str) -> str:
"""去电的语音 Agent:代表用户拨打电话、导航 IVR、达成目标。"""
return (
"你是 PineClaw 电话语音 Agent,正代表用户拨打一通真实电话去办事。\n"
f"- 拨打号码:{phone_number}\n"
f"- 通话目标:{goal}\n"
f"- 已知上下文:{context or '(无额外上下文)'}\n\n"
"行为要求:\n"
"- 全程用简体中文口语,礼貌、简短、直奔目标。\n"
"- 开场若遇到 IVR 按键菜单,请明确说出你的选择(如『我按 0 转人工』)来导航。\n"
"- 接通人工后清晰说明来意,围绕目标追问,主动核对并记住关键信息"
"(金额、原因、确认号、时间等)。\n"
"- 目标达成、或对方明确无法处理时,礼貌道谢结束通话,并在该句结尾附上标记 "
f"{_END_TOKEN}。\n"
"- 每次只说你(来电者)这一方的一段话,不要替对方说话,也不要附加旁白。"
)
def _run_dialog(
phone_number: str, goal: str, context: str, model: str | None = None
) -> list[dict[str, str]]:
"""驱动两个 LLM 角色来回对话,产出逐轮 transcript。"""
caller_sys = _caller_system_prompt(phone_number, goal, context)
callee_sys = _callee_system_prompt(goal, context)
# 各自维护自己视角的消息历史。
caller_msgs = [{"role": "system", "content": caller_sys}]
callee_msgs = [{"role": "system", "content": callee_sys}]
transcript: list[dict[str, str]] = []
# 被叫方先开口(IVR 欢迎语 + 菜单)。
callee_msgs.append({"role": "user", "content": "(电话已接通,请开始。)"})
callee_line = _chat(callee_msgs, model=model)
callee_msgs.append({"role": "assistant", "content": callee_line})
caller_msgs.append({"role": "user", "content": callee_line})
transcript.append({"speaker": "被叫方", "text": callee_line})
for _ in range(_MAX_TURNS):
# 去电语音 Agent 发言
caller_line = _chat(caller_msgs, model=model)
ended = _END_TOKEN in caller_line
caller_line_clean = caller_line.replace(_END_TOKEN, "").strip()
caller_msgs.append({"role": "assistant", "content": caller_line})
callee_msgs.append({"role": "user", "content": caller_line_clean})
transcript.append({"speaker": "语音Agent", "text": caller_line_clean})
if ended:
break
# 被叫方回应
callee_line = _chat(callee_msgs, model=model)
callee_msgs.append({"role": "assistant", "content": callee_line})
caller_msgs.append({"role": "user", "content": callee_line})
transcript.append({"speaker": "被叫方", "text": callee_line})
return transcript
def _extract_structured(
goal: str, transcript: list[dict[str, str]], model: str | None = None
) -> dict[str, Any]:
"""通话结束后,用一次 LLM 调用把 transcript 归纳为结构化字段。"""
dialog_text = "\n".join(f"{t['speaker']}:{t['text']}" for t in transcript)
prompt = (
"下面是一段电话通话的完整转录。请你作为通话分析器,输出一个 JSON 对象,字段如下:\n"
' "goal_achieved": 布尔,本次通话是否达成了给定目标;\n'
' "summary": 字符串,一句话中文通话摘要;\n'
' "key_fields": 对象,从通话中抽取的关键信息键值对(如 扣费原因/涉及金额/'
"确认号/处理结果/预约时间 等,键用中文,没有就留空对象);\n"
' "follow_up_needed": 布尔,用户是否还需要进一步追问或再次拨打;\n'
' "follow_up_reason": 字符串,若需追问说明原因,否则空字符串。\n\n'
f"【通话目标】{goal}\n\n"
f"【通话转录】\n{dialog_text}\n\n"
"只输出 JSON,不要额外解释。"
)
raw = _chat(
[
{"role": "system", "content": "你是严谨的通话记录结构化器,只输出合法 JSON。"},
{"role": "user", "content": prompt},
],
temperature=0.0,
model=model,
)
structured = _safe_json(raw)
# 模型偶尔输出 JSON 数组等合法但非对象的 JSON;归一化为空 dict,
# 交给下游 .get 默认值兜底,而不是让 .get 在 list 上崩溃。
if not isinstance(structured, dict):
structured = {}
return structured
def _safe_json(raw: str) -> dict[str, Any]:
"""从模型输出里稳妥地取出 JSON(容忍 ```json 包裹)。"""
text = raw.strip()
text = re.sub(r"^```(?:json)?", "", text).strip()
text = re.sub(r"```$", "", text).strip()
try:
return json.loads(text)
except json.JSONDecodeError:
m = re.search(r"\{.*\}", text, re.DOTALL)
if m:
try:
return json.loads(m.group(0))
except json.JSONDecodeError:
pass
return {
"goal_achieved": False,
"summary": "(结构化解析失败,请查看原始 transcript)",
"key_fields": {},
"follow_up_needed": True,
"follow_up_reason": "通话记录未能被自动结构化。",
}
# --------------------------------------------------------------------------- #
# 离线 dry-run —— 完全不联网、不需要任何 API Key 的脚本化通话记录
# --------------------------------------------------------------------------- #
def _dryrun_record(phone_number: str, goal: str, context: str) -> dict[str, Any]:
"""
返回一份【脚本化】的结构化通话记录,全程不调用任何 API、不联网。
用途:当既没有电话账号、也没有 OPENAI_API_KEY 时,仍能把整条 ReAct 循环
(思考 → 调用 make_phone_call → 读取结构化记录 → 汇报)离线跑通,展示其形状。
transcript / key_fields 均为固定脚本,不代表任何真实通话。
"""
ctx = context or "(无额外上下文)"
# 由 goal 派生一个稳定、可复现的确认号(而非随机编造,便于对齐说明)。
conf = "PC" + hashlib.sha1(goal.encode("utf-8")).hexdigest()[:8].upper()
transcript = [
{"speaker": "被叫方", "text": "您好,欢迎致电客服热线。业务查询请按 1,人工服务请按 0。"},
{"speaker": "语音Agent", "text": "我按 0 转人工。"},
{"speaker": "被叫方", "text": "您好,人工客服工号 3021,请问有什么可以帮您?"},
{"speaker": "语音Agent", "text": f"你好,我这边的诉求是:{goal}。相关信息:{ctx}。"},
{"speaker": "被叫方",
"text": f"好的,已为您核实并受理,给您一个确认号 {conf},后续可凭此查询进度。"},
{"speaker": "语音Agent", "text": f"好的,确认号 {conf},我记下了,谢谢,再见。"},
]
record = CallRecord(
call_id="pc_dryrun_" + hashlib.sha1((phone_number + goal).encode()).hexdigest()[:8],
phone_number=phone_number,
goal=goal,
status="completed",
goal_achieved=True,
duration_seconds=12 * len(transcript) + 8,
summary=f"(dry-run 脚本模拟)已就“{goal}”联系 {phone_number} 并受理,确认号 {conf}。",
key_fields={"处理结果": "已受理", "确认号": conf, "对方号码": phone_number},
transcript=transcript,
follow_up_needed=False,
follow_up_reason="",
)
return record.to_dict()
# --------------------------------------------------------------------------- #
# 对外唯一入口 —— 对齐真实 PineClaw Voice API 的 make_phone_call
# --------------------------------------------------------------------------- #
def make_phone_call(
phone_number: str,
goal: str,
context: str = "",
*,
model: str | None = None,
dry_run: bool = False,
) -> dict[str, Any]:
"""
发起一通(模拟的)电话,由语音 Agent 全程完成,返回结构化通话记录(dict)。
参数:
phone_number: 被叫号码(本模拟不真正拨号,仅记录)。
goal: 本次通话要达成的目标,例如
"查询本月宽带账单为何多扣了 50 元并要求解释"。
context: 辅助上下文,如账号、姓名、已知信息等(可为空)。
model: 覆盖内部模拟对话所用的 OpenAI 模型(默认取 OPENAI_MODEL)。
dry_run: 若为真,则走完全离线的脚本化路径(不联网、不需要任何 API Key)。
返回:
CallRecord.to_dict(),包含 transcript / goal_achieved / key_fields 等。
"""
if dry_run:
return _dryrun_record(phone_number, goal, context)
started = time.time()
transcript = _run_dialog(phone_number, goal, context, model=model)
structured = _extract_structured(goal, transcript, model=model)
# 用对话轮数粗略折算一个「通话时长」,纯属演示展示用。
duration = 12 * len(transcript) + 8
# key_fields 可能是模型误输出的数组/标量等非对象类型,统一归一化为 dict。
key_fields = structured.get("key_fields")
if not isinstance(key_fields, dict):
key_fields = {}
record = CallRecord(
call_id=f"pc_{uuid.uuid4().hex[:12]}",
phone_number=phone_number,
goal=goal,
status="completed",
goal_achieved=bool(structured.get("goal_achieved", False)),
duration_seconds=duration,
summary=str(structured.get("summary", "")),
key_fields=key_fields,
transcript=transcript,
follow_up_needed=bool(structured.get("follow_up_needed", False)),
follow_up_reason=str(structured.get("follow_up_reason", "")),
)
_ = started # 真实 API 会用真实起止时间;此处 duration 为模拟值
return record.to_dict()