PN 中台客诉 Skill

@pn-data/customer-service 使用文档。
当前内容已按服务端 CustomerSkill::skill() 对齐，只保留已开放能力。

• 当前版本：0.0.59

• 本次更新：新增客诉标签更新能力（updateCustomerServiceTags，服务端转发 pn_go update_customer_service_tags）

• Skill 主文档：customer-service/SKILL.md

• CLI 脚本：customer-service/customer_service.py

龙虾必看

• 术语统一：文档里的“未处理工单/待处理工单”统一指运营处理中工单（status=3）。
• 术语统一：“工单草稿”指未交给运营处理的工单，取待草稿客诉使用 getWaitingDraftTroubles。
• 数量口径：用户泛问“工单数量/几条工单”时，默认看运营处理中数量，使用 getOperationProcessingWorkOrderCount（脚本 --operation-processing-count）。
• 禁止误用：不要用 getWaitingDraftTroubles 返回数组长度当“工单总数”。
• 入口统一：协助工单语境下，“未处理工单/待处理工单”走运营处理中统计；“工单草稿”走 getWaitingDraftTroubles。
• 参数规则：work order 相关 skill（getWaitingDraftTroubles、getWaitingDraftTroubleById、updateWorkOrderDraft、updateDraft、markWorkOrderError、markWorkOrderOperationHandled、getOperationProcessingWorkOrderCount）请求体不传 pid。
• 调用约束：只有在提供客诉 subjectId 时，才调用 getTroubleDetailBySubjectId。
• Token 处理：当没有 PN_DATA_ANALYSIS_TOKEN 时，先看本地变量里有没有；有则直接执行 source ~/.zshrc 或 source ~/.bashrc。若没有则提示获取密钥：登录 pn_mid_v2 中台，点击右上角头像/菜单 -> 生成数据分析密钥（或设置/密钥相关入口），复制生成的 token（仅展示一次，请妥善保存）。
• 版本检查：使用 skill 前先确认版本是否最新；不是最新则自动更新（npm install @pn-data/customer-service@latest），并同步更新 .cursor/skills/customer-service/ 下内容。

客诉状态说明

与 client/src/customer/Trouble.vue 和 customer_service.py 的 TROUBLE_STATUS 对齐：

• -2：加急（Urgent）
• 0：未处理（Untreated）
• 1：已回复（Reply）
• 3：客服已处理（Completed）
• 10：用户已关闭（Close）

用于 getTroubleListByProject / getTroubleListForAllProjects 时，可在 data.status 里直接使用以上值；不确定时默认 -1（全部）。

当前可用能力（与 CustomerSkill.php 对齐）

/service/skill_for_customer_service：

• getWaitingDraftTroubles
• getWaitingDraftTroubleById
• updateWorkOrderDraft
• updateDraft
• markWorkOrderError
• markWorkOrderOperationHandled
• updateReplyDraft
• getTroubleDetailBySubjectId
• getTroubleListByProject
• getTroubleListForAllProjects
• updateCustomerServiceTags
• replyTroubleBySubjectId
• getOperationProcessingWorkOrderCount

/service/pn_data_analysis：

• listProject
• statisticCustomerServiceReply

配置

脚本和 Cursor Agent 调用 customer_service.py 时，必须能读到环境变量 PN_DATA_ANALYSIS_TOKEN，否则会报错并提示未配置。

获取密钥

1. 登录 pn_mid_v2 中台
2. 点击右上角头像/菜单 -> 生成数据分析密钥（或设置/密钥相关入口）
3. 复制生成的 token（仅展示一次，请妥善保存）

配置方式

方式一：写入 shell 配置文件（推荐，对本用户所有终端生效）

• macOS / Linux（zsh）：在 ~/.zshrc 末尾添加
  export PN_DATA_ANALYSIS_TOKEN="粘贴你的 token"
• bash：在 ~/.bashrc 或 ~/.bash_profile 末尾添加同一行

保存后执行一次：

source ~/.zshrc   # 或 source ~/.bashrc

方式二：仅当前终端会话

export PN_DATA_ANALYSIS_TOKEN="粘贴你的 token"

仅对当前 shell 有效，新开终端或 Cursor 新会话不会继承。

校验是否生效

echo $PN_DATA_ANALYSIS_TOKEN
# 或
printenv PN_DATA_ANALYSIS_TOKEN

有输出一长串 token 即表示已配置；为空则需检查配置文件是否写对、是否已 source。

其他可选环境变量

• PN_DATA_ANALYSIS_BASE（默认 https://pnv2.17995api.net）

脚本会自动尝试读取以下文件（已在 shell 导出的变量优先，不会覆盖）：

• customer-service/.env.customer-service
• customer-service/.env
• 项目根目录 .env.customer-service
• 项目根目录 .env

常用命令

# 项目列表
python3 customer-service/customer_service.py --list-projects

# 客服回复统计（时间范围）
python3 customer-service/customer_service.py --statistic-reply 1712505600 1712591999

# 待草稿客诉队列（队首 1 条）
python3 customer-service/customer_service.py --waiting-draft-troubles

# 按 subjectId 查询待草稿详情
python3 customer-service/customer_service.py --waiting-draft-trouble-by-id 123456

# 更新/新建工单草稿
python3 customer-service/customer_service.py --update-work-order-draft 123456 --title "工单标题" --content "工单内容"

# 同时更新工单草稿和回复草稿
python3 customer-service/customer_service.py --update-draft 123456 --work-order-title "工单标题" --work-order-content "工单内容" --reply-content "请先提供角色 ID，我们尽快核查"

# 按 subjectId 标记工单为错误
python3 customer-service/customer_service.py --mark-work-order-error 123456

# 按 subjectId 标记工单为运营已处理（title/content 必填）
python3 customer-service/customer_service.py --mark-work-order-operation-handled 123456 --title "处理结果标题" --content "处理结果正文"

# 更新 AI 回复草稿
python3 customer-service/customer_service.py --update-reply-draft 123456 --content "请先提供角色 ID，我们尽快核查"

# 客诉详情
python3 customer-service/customer_service.py --trouble-detail 123456

# 项目内客诉列表
python3 customer-service/customer_service.py --trouble-list-by-project 2000 --data-json '{"status": -1, "limit": 10, "page": 1}'

# 全项目客诉列表（eid=1 或 5）
python3 customer-service/customer_service.py --trouble-list-all-projects 1 --data-json '{"status": -1, "limit": 10, "page": 1}'

# 正式回复客诉
python3 customer-service/customer_service.py --reply-trouble 123456 --content "问题已修复，请重启游戏后重试"

# 运营处理中工单数
python3 customer-service/customer_service.py --operation-processing-count

# 更新客诉标签（最多 3 个；传 [] 清空）
python3 customer-service/customer_service.py --update-customer-service-tags 123456 --tags-json '["vip","bug"]'

# 解析 token
python3 customer-service/customer_service.py --show-pn-token

追加 --json 可输出原始 JSON。

客诉列表查询参数说明

--trouble-list-by-project 与 --trouble-list-all-projects 的 --data-json 参数含义一致（对应 Trouble.vue 的筛选项）：

• status：客诉状态，-1 全部、-2 加急、0 未处理、1 已回复、2 待处理、3 已完成、10 已关闭、11 已删除。
• appid：包 ID；-1 表示项目包，-2 表示全部包。
• serverid：服务器 ID；传 "" 表示全部服务器。
• language：语言代码；传 "" 表示全部语言。
• typeid：客诉分类 ID；传 "" 表示全部分类。
• gm_score：客服评分；传 "" 表示全部评分。
• paystar：VIP 星级；传 "" 表示全部等级。
• startTS / endTS：Unix 秒级时间范围；为空表示不限制时间。
• passportid：用户 UID（通行证 ID）。
• keywords：关键词（标题/内容检索）。
• onlyme：是否仅看我处理，yes/no。
• limit：每页条数（前端默认 30）。
• page：页码（从 1 开始）。

接口层参数补充：

• getTroubleListByProject：请求体顶层还需 pid（项目 ID）。
• getTroubleListForAllProjects：请求体顶层还需 eid（当前支持 1 或 5）。

安装

npm install @pn-data/customer-service

将 node_modules/@pn-data/customer-service/customer-service/ 和 README.md 复制或链接到 .cursor/skills/customer-service/。

License

MIT