PN 中台 客诉 / Customer Service

Cursor Agent Skill — 文档与说明 pn_mid_v2 中台项目列表（listProject）、客诉列表、客诉详情、正式回复客诉（troubleReply / OP_CS_POSTS_REPLY）、回复草稿、中台协助工单（work_order：取最旧 getOldestWaitingWorkOrder、按 id 获取 getWorkOrderById（两者均不传 pid，返回结构一致，含 troubles 与 recentWorkOrders）；按 id 更新正文 updateWorkOrderById（更新 data.title/content，不改状态）；getWorkOrderWaitingList 已废弃；updateWorkOrder 不传 pid，支持两条流转：WAITING -> REVIEWING（需 title+content）与 OPERATION_HANDLED -> DONE（可不传 title/content）；另有 UPDATE_WORK_ORDER_STATUS、详情 data.workOrder、CREATE_WORK_ORDER、前端 LIST_OPERATION_PROCESSING_WORK_ORDERS 等）及相关接口（ProjectManager::getListForPnDataAnalysis、Api::OP_CS_SUBJECT_*、OP_CS_AI_APPROVE、SkillManager::forCustomerService、Customer::skill / Customer::op、WorkOrder 等）。细则以 customer-service/SKILL.md 为准。

Skill 版本：v0.0.32（以 customer-service/SKILL.md 顶部为准）。发布 @pn-data/customer-service 时请保持 package.json 的 version 与本版本一致。
完整约定与代码位置见 customer-service/SKILL.md。

本版要点（v0.0.32，发布用）

• 给龙虾 / Agent（协助工单怎么说都一样）：用户或指令若写「取未处理工单」「待处理工单」「工单列表」等（skill_for_customer_service / 协助工单语境，非客诉 troubleList），一律调用 api=getOldestWaitingWorkOrder；同项目多条摘要只看响应 recentWorkOrders。勿再对接 getWorkOrderWaitingList。
• 给龙虾 / Agent（术语统一）：「龙虾队列」=「龙虾客诉队列」= 协助工单（均指 skill_for_customer_service 语境下的中台协助工单）；在龙虾使用 skill 功能时，面向龙虾的话术与提示中不再提及“工单”字样，统一使用「龙虾队列 / 龙虾客诉队列」。
• 新增工单 skill：getWorkOrderById（按工单 id 取工单，返回结构同最旧工单）与 updateWorkOrderById（按工单 id 更新 title/content，不改状态）。
• 接口名统一：updateWorkOrderContentById 为旧名，已统一替换为 updateWorkOrderById；新接入请仅使用 updateWorkOrderById。
• updateWorkOrder 状态分支：status=0 时必填 title + content（写入 work_order.data 并转审核中）；status=4 时可仅传工单 id（转已完成）。
• getOldestWaitingWorkOrder 附加 recentWorkOrders：与当前待处理工单同一项目下，按更新时间倒序 20 条工单，每项仅 title、content（便于 Agent 参考近期协助摘要）。id / subjectId / data / troubles 等含义不变。
• 工单技能不带 pid：POST /service/skill_for_customer_service（或 3037）中 api=getOldestWaitingWorkOrder / api=getWorkOrderById / api=updateWorkOrder / api=updateWorkOrderById 的 Body 不要求、不携带 projectId/pid；forCustomerService 只做 Token 与 user，无 setRequest。UPDATE_WORK_ORDER_STATUS、LIST_OPERATION_PROCESSING_WORK_ORDERS 等业务 API 仍须按中台约定传 pid（见 TroubleDetail.vue、WorkOrderList.vue）。
• 本版（0.0.32）：龙虾术语统一为 「龙虾队列」=「龙虾客诉队列」= 协助工单（非「协助工单队列」）；README / SKILL.md 已同步；按 id 更新正文接口名统一为 updateWorkOrderById。
• 全库最旧工单：WorkOrder::getOldestWaiting()（当前会返回等待处理或运营已处理）；troubles 按工单所属 pid 解 Project 后 fetchTroubleListByUid（缺 subjectId 时首部补足）。
• 给龙虾 / Agent（执行规则）：
  • 取到 status=0（待处理）工单：先生成 AI 回复草稿，再调用 updateWorkOrder（带 title + content）把工单置为 STATUS_REVIEWING。
  • 取到 status=4（运营已处理）工单：参考工单 title/content 生成新的 AI 回复草稿，再调用 updateWorkOrder（仅 id）把工单置为 STATUS_DONE。
• 给龙虾 / Agent（主单与参考客诉）：响应根级 subjectId = 主要客诉；troubles 中其余 id 为参考客诉。正式回复、草稿、审核以根级 subjectId 为准。
• 客诉详情：OP_CS_SUBJECT_DETAIL 可合并 data.workOrder。
• 工单状态（中台 work_order.status）：0 等待处理、1 审核中、2 已完成、3 运营处理中、4 运营已处理（流转与列表 API 见 SKILL.md）。
• 前端协助工单「直接回复」：走 OP_CS_AI_APPROVE + subjectId / workOrderId（见 SKILL.md）。

何时使用

• 用户问：项目列表、listProject、客诉列表、客诉详情、正式回复、troubleReply、回复草稿、协助工单、取最旧工单、getOldestWaitingWorkOrder、按 id 取工单、getWorkOrderById、按 id 更新正文、updateWorkOrderById、recentWorkOrders、updateWorkOrder、工单 title、skill_for_customer_service、无 pid 工单、work_order、CREATE_WORK_ORDER、UPDATE_WORK_ORDER_STATUS、运营工单列表、……
• 需要查找或修改客诉 / 工单相关代码（Customer、SkillManager、Api、WorkOrder、TroubleDetail）。

配置

| 环境变量 | 用途 | |----------|------| | PN_DATA_ANALYSIS_TOKEN | pn_data_analysis 与 skill_for_customer_service 共用：X-Pn-Token | | AI_REPLY_API_KEY | 回复草稿 /api/ai/reply-draft |

可选：PN_DATA_ANALYSIS_BASE、AI_REPLY_BASE_URL（默认与 PN_DATA_ANALYSIS_BASE 一致）。

获取项目列表 / 客诉列表 / 客诉详情

python3 customer-service/customer_service.py --list-projects
python3 customer-service/customer_service.py <pid>
python3 customer-service/customer_service.py <pid> --detail <troubleId> --json

详见 SKILL.md。

协助工单（脚本与 HTTP 均不传 pid）

SkillManager::forCustomerService → Customer::skill。Body 仅需 api（以及对应参数），不要带 pid。

# 全库最早一条等待处理工单（JSON 中含 troubles；另含 recentWorkOrders：同项目 20 条 title/content）
python3 customer-service/customer_service.py --oldest-waiting-work-order
python3 customer-service/customer_service.py --oldest-waiting-work-order --json

# 按工单 id 获取（返回结构同上）
python3 customer-service/customer_service.py --get-work-order-by-id 42
python3 customer-service/customer_service.py --get-work-order-by-id 42 --json

# 更新工单（status=0 时需 title/content -> 审核中；status=4 时可仅 id -> 已完成）
python3 customer-service/customer_service.py --update-work-order <工单id> --work-order-title "标题" --work-order-content "工单正文"
python3 customer-service/customer_service.py --update-work-order 42 --work-order-title "…" --work-order-content "…" --json
python3 customer-service/customer_service.py --update-work-order 42

# 仅更新工单正文（不改变状态）
python3 customer-service/customer_service.py --update-work-order-by-id 42 --work-order-title "标题" --work-order-content "工单正文"
python3 customer-service/customer_service.py --update-work-order-by-id 42 --work-order-title "…" --work-order-content "…" --json

详见 SKILL.md「待处理协助工单」「更新协助工单」。

正式回复 / 回复草稿

仍须 pid（与客诉项目上下文一致），示例见 SKILL.md。

功能入口一览

| 功能 | 方式 | 说明 | |------|------|------| | 项目列表 | 脚本 | --list-projects，pn_data_analysis / listProject | | 客诉列表/详情/回复 | 脚本 / pn_data_analysis | 需 <pid>（与工单技能不同） | | 最早待处理工单 | 脚本 / HTTP | --oldest-waiting-work-order；Body { "api": "getOldestWaitingWorkOrder" }，无 pid；响应含 recentWorkOrders（同项目 20 条摘要） | | 按 id 获取工单 | 脚本 / HTTP | --get-work-order-by-id；Body { "api": "getWorkOrderById", "id": <id> }，无 pid；返回结构同最旧工单 | | 更新协助工单 | 脚本 / HTTP | --update-work-order + --work-order-title + --work-order-content；Body 无 pid，WorkOrder::getById | | 按 id 更新工单正文 | 脚本 / HTTP | --update-work-order-by-id + title/content；Body { "api":"updateWorkOrderById", "id":..., "title":"...", "content":"..." }，无 pid（旧名 updateWorkOrderContentById 已废弃） | | 工单状态 / 运营列表 | 中台 API | UPDATE_WORK_ORDER_STATUS（829）、LIST_OPERATION_PROCESSING_WORK_ORDERS（830）等，需 pid（见 SKILL / 前端） | | 回复草稿 | 脚本 | --draft-subject / --draft-content，需 AI_REPLY_API_KEY |

安装

npm install @pn-data/customer-service
# 将 node_modules/@pn-data/customer-service/ 下 customer-service/ 与 README 复制或链接到 .cursor/skills/customer-service/

Skill 主文档：.cursor/skills/customer-service/customer-service/SKILL.md。

发布前检查

npm view @pn-data/customer-service version --registry https://registry.npmjs.org/

确认 package.json version 与 SKILL.md 顶部 Skill 版本 一致后 npm publish。

License

MIT