@shulex/cxclawctl 0.1.2 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +25 -22
- package/capabilities.lock.json +535 -131
- package/dist/cli.js +2203 -127
- package/dist/cli.js.map +1 -1
- package/package.json +20 -6
- package/requirements-cli.txt +0 -2
- package/skills/__lib__/__init__.py +0 -0
- package/skills/__lib__/skill-runtime/bootstrap.py +0 -134
- package/skills/__lib__/solvea-api/__init__.py +0 -0
- package/skills/__lib__/solvea-api/client.py +0 -1944
- package/skills/__lib__/solvea-api/dashboard.py +0 -100
- package/skills/__lib__/solvea-api/solvea_api.py +0 -1341
- package/skills/agent-analytics/SKILL.md +0 -74
- package/skills/agent-analytics/references/chat-report-fields.md +0 -36
- package/skills/agent-analytics/references/report-fields.md +0 -130
- package/skills/agent-analytics/references/transcript.md +0 -110
- package/skills/agent-builder/SKILL.md +0 -42
- package/skills/agent-builder/interfaces/fallback-chatflow.md +0 -47
- package/skills/agent-builder/references/chatflow/graph-spec.md +0 -259
- package/skills/agent-builder/references/chatflow/node-selection.md +0 -89
- package/skills/agent-builder/references/chatflow/nodes/agent.md +0 -350
- package/skills/agent-builder/references/chatflow/nodes/business-track.md +0 -43
- package/skills/agent-builder/references/chatflow/nodes/code.md +0 -157
- package/skills/agent-builder/references/chatflow/nodes/collect-order.md +0 -47
- package/skills/agent-builder/references/chatflow/nodes/finish.md +0 -34
- package/skills/agent-builder/references/chatflow/nodes/human-review.md +0 -60
- package/skills/agent-builder/references/chatflow/nodes/if-else.md +0 -100
- package/skills/agent-builder/references/chatflow/nodes/intent.md +0 -79
- package/skills/agent-builder/references/chatflow/nodes/knowledge-reply.md +0 -43
- package/skills/agent-builder/references/chatflow/nodes/llm.md +0 -117
- package/skills/agent-builder/references/chatflow/nodes/note.md +0 -38
- package/skills/agent-builder/references/chatflow/nodes/question.md +0 -97
- package/skills/agent-builder/references/chatflow/nodes/rag-reply.md +0 -68
- package/skills/agent-builder/references/chatflow/nodes/reply.md +0 -97
- package/skills/agent-builder/references/chatflow/nodes/start.md +0 -35
- package/skills/agent-builder/references/chatflow/nodes/sub-graph.md +0 -48
- package/skills/agent-builder/references/chatflow/nodes/tool.md +0 -138
- package/skills/agent-builder/references/chatflow/nodes/transfer-to-human.md +0 -63
- package/skills/agent-builder/references/chatflow/nodes/variable-assignment.md +0 -52
- package/skills/agent-builder/references/chatflow/nodes/variable-extract.md +0 -50
- package/skills/agent-builder/references/chatflow/nodes/variable-process.md +0 -70
- package/skills/agent-builder/references/chatflow/overview.md +0 -53
- package/skills/agent-builder/references/chatflow/visual-translation.md +0 -64
- package/skills/agent-builder/references/chatflow/workflow.md +0 -134
- package/skills/agent-builder/references/multi-agent/create-update.md +0 -185
- package/skills/agent-builder/references/multi-agent/graph-spec.md +0 -246
- package/skills/agent-builder/references/multi-agent/graph-structure.md +0 -12
- package/skills/agent-builder/references/multi-agent/migrate-to-chatflow.md +0 -13
- package/skills/agent-builder/references/multi-agent/migration/large.md +0 -554
- package/skills/agent-builder/references/multi-agent/migration/principles.md +0 -446
- package/skills/agent-builder/references/multi-agent/migration/small.md +0 -225
- package/skills/agent-builder/references/multi-agent/orchestration.md +0 -11
- package/skills/agent-builder/references/multi-agent/overview.md +0 -48
- package/skills/agent-builder/references/multi-agent/update.md +0 -128
- package/skills/agent-builder/references/multi-agent/workflow.md +0 -87
- package/skills/agent-builder/references/single-agent/overview.md +0 -48
- package/skills/agent-builder/references/single-agent/prompt.md +0 -16
- package/skills/agent-builder/references/single-agent/tools.md +0 -36
- package/skills/agent-builder/references/single-agent/voice.md +0 -46
- package/skills/agent-builder/references/tools/http-tool.md +0 -315
- package/skills/agent-builder/references/tools/mock-tool.md +0 -279
- package/skills/agent-builder/references/tools/overview.md +0 -46
- package/skills/agent-builder/references/tools/tool-config.md +0 -43
- package/skills/agent-builder/references/tools/x-token.md +0 -34
- package/skills/agent-builder/scripts/chatflow/chatflow_builder.py +0 -3458
- package/skills/agent-builder/scripts/chatflow/validate_graph.py +0 -1697
- package/skills/agent-builder/scripts/copy_marketplace_agent.py +0 -61
- package/skills/agent-builder/scripts/multi-agent/legacy_graph_analyzer.py +0 -5974
- package/skills/agent-builder/scripts/multi-agent/replay_compare.py +0 -679
- package/skills/agent-builder/scripts/patch_agent_tools.py +0 -135
- package/skills/agent-builder/scripts/tools/validate_tool_config.py +0 -384
- package/skills/agent-tester/SKILL.md +0 -35
- package/skills/agent-tester/batch-test/overview.md +0 -86
- package/skills/agent-tester/scripts/batch_test_sheet.py +0 -213
- package/skills/agent-tester/single-test/badcase-retest.md +0 -85
- package/skills/agent-tester/single-test/direct-test.md +0 -24
- package/skills/agent-tester/single-test/overview.md +0 -142
- package/skills/delivery/SKILL.md +0 -112
- package/skills/delivery/interfaces/classify.md +0 -38
- package/skills/delivery/interfaces/create-agents.md +0 -89
- package/skills/delivery/interfaces/delivery-test.md +0 -67
- package/skills/delivery/references/flow.md +0 -40
- package/skills/delivery/references/validation.md +0 -15
- package/skills/delivery/scripts/batch_test.py +0 -704
- package/skills/delivery/scripts/classify.py +0 -22
- package/skills/delivery/scripts/create_agents.py +0 -695
- package/skills/delivery/scripts/gen_delivery_report.py +0 -335
- package/skills/delivery/scripts/gen_excel.py +0 -234
- package/skills/delivery/scripts/gen_report.py +0 -208
- package/skills/delivery/scripts/plan.py +0 -163
- package/skills/delivery/scripts/render.py +0 -713
- package/skills/delivery/scripts/render_summary.py +0 -38
- package/skills/delivery/scripts/sample_history_cases.py +0 -109
- package/skills/kb-builder/SKILL.md +0 -80
- package/skills/kb-builder/interfaces/qa-upload.md +0 -55
- package/skills/kb-builder/interfaces/web-kb.md +0 -84
- package/skills/kb-builder/references/directory.md +0 -373
- package/skills/kb-builder/references/export.md +0 -282
- package/skills/kb-builder/references/isolation-keywords.md +0 -113
- package/skills/kb-builder/references/knowledge.md +0 -153
- package/skills/kb-builder/references/product.md +0 -52
- package/skills/kb-builder/references/qa-from-help-center.md +0 -58
- package/skills/kb-builder/references/qa-from-pdf.md +0 -94
- package/skills/kb-builder/references/qa-from-tickets.md +0 -168
- package/skills/kb-builder/references/qa-from-web.md +0 -98
- package/skills/kb-builder/references/qa-quality.md +0 -73
- package/skills/kb-builder/references/reply-template.md +0 -237
- package/skills/kb-builder/references/tag-isolation-migration.md +0 -61
- package/skills/kb-builder/references/tags.md +0 -45
- package/skills/kb-builder/references/upload.md +0 -130
- package/skills/kb-builder/scripts/batch_extract_ticket_qa.py +0 -333
- package/skills/kb-builder/scripts/build_directory_plan.py +0 -144
- package/skills/kb-builder/scripts/crawl_site.py +0 -433
- package/skills/kb-builder/scripts/create_dirs.py +0 -146
- package/skills/kb-builder/scripts/export_knowledge.py +0 -454
- package/skills/kb-builder/scripts/extract_ticket_qa.py +0 -441
- package/skills/kb-builder/scripts/extract_web_qa.py +0 -118
- package/skills/kb-builder/scripts/import_qa.py +0 -219
- package/skills/kb-builder/scripts/import_source_documents.py +0 -143
- package/skills/kb-builder/scripts/import_templates.py +0 -409
- package/skills/poc/SKILL.md +0 -125
- package/skills/poc/assets/default_manual.css +0 -279
- package/skills/poc/assets/notice_escalate.png +0 -0
- package/skills/poc/assets/notice_escalate2.png +0 -0
- package/skills/poc/assets/notice_new_chat.png +0 -0
- package/skills/poc/assets/poc_test_template.html +0 -645
- package/skills/poc/assets/poc_test_template.md +0 -104
- package/skills/poc/assets/step3_preview.png +0 -0
- package/skills/poc/assets/step4_order_note.png +0 -0
- package/skills/poc/interfaces/classify.md +0 -38
- package/skills/poc/interfaces/create-agents.md +0 -108
- package/skills/poc/interfaces/poc-test.md +0 -94
- package/skills/poc/references/flow.md +0 -47
- package/skills/poc/references/kb-directory.md +0 -22
- package/skills/poc/references/validation.md +0 -17
- package/skills/poc/scripts/classify.py +0 -22
- package/skills/poc/scripts/create_agents.py +0 -818
- package/skills/poc/scripts/gen_excel.py +0 -234
- package/skills/poc/scripts/gen_poc_manual.py +0 -249
- package/skills/poc/scripts/gen_report.py +0 -208
- package/skills/poc/scripts/inspect_chatflow.py +0 -209
- package/skills/poc/scripts/plan.py +0 -178
- package/skills/poc/scripts/poc_test.py +0 -495
- package/skills/poc/scripts/render.py +0 -713
- package/skills/poc/scripts/render_summary.py +0 -41
- package/skills/runtime-inspector/SKILL.md +0 -51
- package/skills/runtime-inspector/references/frontend-rendering.md +0 -126
- package/skills/runtime-inspector/references/model.md +0 -59
- package/skills/runtime-inspector/references/sandbox.md +0 -131
- package/skills/runtime-inspector/scripts/model_inspect.py +0 -68
- package/skills/runtime-inspector/scripts/prepare.py +0 -98
- package/skills/runtime-inspector/scripts/process.py +0 -84
- package/skills/runtime-inspector/scripts/read_state.py +0 -32
- package/skills/runtime-inspector/scripts/sandbox_inspect.py +0 -463
- package/skills/runtime-inspector/scripts/test_claude_proxy.py +0 -49
- package/skills/runtime-inspector/scripts/test_openai_proxy.py +0 -41
- package/skills/runtime-inspector/scripts/verify_persistence.py +0 -101
- package/skills/runtime-inspector/scripts/write_test.py +0 -41
- package/skills/setup/SKILL.md +0 -17
- package/skills/shulex-support/SKILL.md +0 -39
- package/skills/shulex-support/references/badcase-analysis/overview.md +0 -34
- package/skills/shulex-support/references/badcase-analysis/text/conversation-record.md +0 -105
- package/skills/shulex-support/references/badcase-analysis/text/core-flow.md +0 -89
- package/skills/shulex-support/references/badcase-analysis/text/log-query-rules.md +0 -36
- package/skills/shulex-support/references/badcase-analysis/text/m1-entry.md +0 -53
- package/skills/shulex-support/references/badcase-analysis/text/m10-chatflow-service.md +0 -259
- package/skills/shulex-support/references/badcase-analysis/text/m11-algorithm-service.md +0 -148
- package/skills/shulex-support/references/badcase-analysis/text/m12-quality-inspection.md +0 -57
- package/skills/shulex-support/references/badcase-analysis/text/m2-intent.md +0 -120
- package/skills/shulex-support/references/badcase-analysis/text/m3-strategy.md +0 -126
- package/skills/shulex-support/references/badcase-analysis/text/m4-aifield.md +0 -121
- package/skills/shulex-support/references/badcase-analysis/text/m5-agent.md +0 -208
- package/skills/shulex-support/references/badcase-analysis/text/m6-tool.md +0 -115
- package/skills/shulex-support/references/badcase-analysis/text/m7-reply.md +0 -72
- package/skills/shulex-support/references/badcase-analysis/text/m8-error.md +0 -92
- package/skills/shulex-support/references/badcase-analysis/text/m9-knowledge-search.md +0 -147
- package/skills/shulex-support/references/badcase-analysis/text/sls-query.md +0 -283
- package/skills/shulex-support/references/badcase-analysis/voice/core-flow.md +0 -77
- package/skills/shulex-support/references/badcase-analysis/voice/dependencies.md +0 -19
- package/skills/shulex-support/references/badcase-analysis/voice/platform-api.md +0 -23
- package/skills/shulex-support/references/badcase-analysis/voice/sls-playbook.md +0 -31
- package/skills/shulex-support/references/product-docs.md +0 -70
- package/skills/shulex-support/references/tickets.md +0 -184
- package/skills/shulex-support/scripts/support.py +0 -427
- package/skills/solvea-desk/SKILL.md +0 -39
- package/skills/solvea-desk/references/report/fields.md +0 -82
- package/skills/solvea-desk/references/report/report-design.md +0 -200
- package/skills/solvea-desk/references/report/report-template.html +0 -44
- package/skills/solvea-desk/references/report/report.css +0 -517
- package/skills/solvea-desk/references/report/workflow.md +0 -464
- package/skills/solvea-desk/references/tickets/query.md +0 -103
- package/skills/solvea-desk/references/tickets/tags.md +0 -83
- package/skills/solvea-desk/scripts/report/fetch_sources.py +0 -580
- package/skills/solvea-desk/scripts/report/render_report.py +0 -763
- package/skills/solvea-desk/scripts/tickets/desk_api.py +0 -73
- package/skills/solvea-desk/scripts/tickets/fetch_tickets.py +0 -403
- package/skills/solvea-desk/scripts/tickets/ticket_tags.py +0 -305
- package/skills/solvea-kit/SKILL.md +0 -84
- package/skills/solvea-kit/references/agent.md +0 -145
- package/skills/solvea-kit/references/chat.md +0 -244
- package/skills/solvea-kit/references/intent.md +0 -69
- package/skills/solvea-kit/references/plugin.md +0 -53
- package/skills/solvea-kit/references/quality-inspection.md +0 -75
- package/skills/solvea-kit/references/strategy.md +0 -62
- package/skills/solvea-kit/references/tagging.md +0 -231
- package/skills/solvea-kit/references/variables.md +0 -53
- package/skills/solvea-kit/scripts/generate_label_import_file.py +0 -151
- package/skills/solvea-kit/scripts/intent_classify.py +0 -843
|
@@ -1,39 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: solvea-desk
|
|
3
|
-
description: 查询、分析和管理 Shulex Desk / Tars 工单;支持当前工单筛选、历史报表及工单标签查询、绑定和解绑。
|
|
4
|
-
requires:
|
|
5
|
-
libs: []
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
# Shulex Desk
|
|
9
|
-
|
|
10
|
-
Shulex Desk / Tars 客服台工单的唯一入口。它与 GPT 标签树配置、CX 产品售后工单是不同的数据和操作面,不要混用。
|
|
11
|
-
|
|
12
|
-
## 场景路由
|
|
13
|
-
|
|
14
|
-
| 用户诉求 | 必读文档 |
|
|
15
|
-
|---|---|
|
|
16
|
-
| 当前工单列表、筛选、正文分类 | `/skills/solvea-desk/references/tickets/query.md` |
|
|
17
|
-
| 标签树、工单标签、绑定或解绑 | `/skills/solvea-desk/references/tickets/tags.md` |
|
|
18
|
-
| 指标、趋势、时效、明细、XLSX 或报表 | `/skills/solvea-desk/references/report/workflow.md` |
|
|
19
|
-
|
|
20
|
-
## 共用约束
|
|
21
|
-
|
|
22
|
-
- 查询和修改只使用上述文档指定的受控脚本,不直接 curl Tars 接口。
|
|
23
|
-
- 标签写入前必须确认目标工单和当前标签,并通过标签树或搜索获得准确的 Tars 标签 ID;不得使用 GPT 标签树 ID,也不得根据名称猜 ID。
|
|
24
|
-
- 向用户展示工单号、操作类型、标签名称和 ID,获得明确确认后才能向脚本传 `--confirm`。
|
|
25
|
-
- `aiTags` 只读;绑定和解绑只操作并核验 `userTags`。
|
|
26
|
-
- 搜索返回多个同名或相近标签路径时让用户选择,不自动取第一个。
|
|
27
|
-
- 新任务只写 `/workspace/state/solvea-desk/`、`/workspace/outputs/solvea-desk/` 和 `/workspace/tmp/solvea-desk/`。
|
|
28
|
-
|
|
29
|
-
## 历史报表任务
|
|
30
|
-
|
|
31
|
-
先读取 `/workspace/state/solvea-desk/latest_task.json`。新路径不存在时,可以**只读**检查 `/workspace/state/desk-report/latest_task.json` 及其 task 目录,以继续分析或重新渲染旧任务。
|
|
32
|
-
|
|
33
|
-
历史回退仅用于读取:任何新任务和新 fetch 都必须写入 `/workspace/state/solvea-desk/`,不得向旧 `desk-report` 目录写入。
|
|
34
|
-
|
|
35
|
-
## 相邻能力边界
|
|
36
|
-
|
|
37
|
-
- GPT 标签树、标签组、标签节点配置:使用 `solvea-kit`,接口位于 `/api_v2/gpt/label/project/...`。
|
|
38
|
-
- CX 产品售后咨询、创建或追加售后工单:使用 `shulex-support`。
|
|
39
|
-
- Agent 会话指标、趋势和原始会话下钻:使用 `agent-analytics`。
|
|
@@ -1,82 +0,0 @@
|
|
|
1
|
-
# Shulex Desk Fields
|
|
2
|
-
|
|
3
|
-
`datasource.xlsx` 默认读取 `data` sheet。接口字段使用驼峰命名,字段含义以本文件为准;不要要求或生成运行态 `schema.md`。本文件面向 Agent 做报表分析,只描述 `datasource.xlsx` 里可见字段、单位、口径和限制,不描述后端数据库表结构。
|
|
4
|
-
|
|
5
|
-
## 数据粒度与默认口径
|
|
6
|
-
|
|
7
|
-
- `data` sheet 一行代表一个工单,时间范围按工单创建时间筛选。
|
|
8
|
-
- 顶层字段可直接按 Excel 列读取和聚合;`messages` 是每个工单内的消息明细数组,需要先解析 JSON 字符串再展开统计。
|
|
9
|
-
- 时间字段由接口返回为时间值;分析时按用户要求的业务时区展示,默认使用北京时间。
|
|
10
|
-
- `replyTime`、`responder`、`isAiReply` 描述当前工单的最新有效对客回复。
|
|
11
|
-
- `firstReplyTime`、`firstReplyDuration` 描述当前工单的首次有效对客回复。
|
|
12
|
-
- `replyDuration` 单位是分钟,`resolutionDuration` 单位是小时。
|
|
13
|
-
- 广告、通知、AI 关单是否剔除取决于用户口径;默认报表需要说明是否使用了这些过滤条件。
|
|
14
|
-
|
|
15
|
-
## 顶层字段
|
|
16
|
-
|
|
17
|
-
| 模块 | 接口字段 | 中文字段 | 字段说明 | 必需性 | 用途 | 备注 |
|
|
18
|
-
|------|----------|----------|----------|--------|------|------|
|
|
19
|
-
| 工单标识 | `ticketId` | 工单ID | 工单唯一 ID,用于关联消息明细、回复明细和标签。 | 必需 | 工单去重、明细定位、关联导出 | 系统内部 ID;不要展示给业务用户作为唯一可读编号。 |
|
|
20
|
-
| 工单标识 | `ticketNumber` | 工单编号 | 对外展示的工单编号,便于客服和运营人员查询工单。 | 必需 | 页面展示、人工核对、导出识别 | 面向用户展示时优先使用该字段。 |
|
|
21
|
-
| 工单基础 | `ticketTitle` | 工单标题 | 工单展示标题;通常来自客户第一条消息主题或系统维护后的标题。 | 建议 | 明细展示、问题排查 | 不作为核心聚合字段。 |
|
|
22
|
-
| 工单基础 | `ticketStatus` | 工单状态 | 工单当前所处的处理状态。 | 必需 | 按 Processing / Open / Pending / Solved 等筛选 | 枚举以接口返回值为准,例如 `open` / `pending` / `solved` / `ai_handing`。 |
|
|
23
|
-
| 工单基础 | `channel` | 工单来源渠道 | 工单来源渠道,例如站内信、Email、livechat。 | 必需 | 按 Email / Livechat / Buyer Msg / Amazon / Shopify 等筛选、分组 | 渠道展示值以接口返回为准。 |
|
|
24
|
-
| 业务维度 | `store` | 店铺 | 客户咨询所关联的店铺。 | 必需 | 按店铺筛选、分组统计 | 为空时说明该工单没有可用店铺信息。 |
|
|
25
|
-
| 业务维度 | `brand` | 品牌 | 客户咨询所关联的品牌。 | 必需 | 按品牌筛选、分组统计 | 为空时不要按字段名猜测品牌。 |
|
|
26
|
-
| 业务维度 | `category` | 品类 | 客户咨询涉及的产品品类。 | 必需 | 按品类筛选、分组统计 | 为空时说明当前快照没有品类信息。 |
|
|
27
|
-
| 业务维度 | `tags` | 标签 | 当前工单已绑定且生效的标签列表。 | 必需 | 按标签筛选、做问题类型分析 | 可能是数组或 JSON 字符串;需要按多标签展开时先解析。 |
|
|
28
|
-
| 业务维度 | `platform` | 平台 | 客户咨询来源的平台,例如 Amazon、Shopify、eBay 等。 | 建议 | 按平台筛选、分组统计 | 为空时不等同于未知渠道。 |
|
|
29
|
-
| 业务维度 | `site` | 站点 | 客户咨询来源的国家、地区或站点。 | 建议 | 按 US / CA 等站点筛选、分组 | 接口可能已做站点/国家/地区回退。 |
|
|
30
|
-
| 人员维度 | `currentAssignee` | 当前负责人 | 当前负责处理该工单的客服。 | 必需 | 按当前客服筛选、看待处理归属 | 未分配工单返回空。 |
|
|
31
|
-
| 人员维度 | `resolver` | 解决人 | 最后将工单标记为已解决的人;如果由 AI 解决,则显示为 Solvea-AI。 | 必需 | 统计客服解决量、区分 AI/人工解决 | AI 关单时不要当成人工解决量。 |
|
|
32
|
-
| 人员维度 | `responder` | 回复人 | 最新有效对客回复的回复人;如果是 AI 回复,则显示为 Solvea-AI。 | 必需 | 统计回复量、平均响应时长、首响表现 | 只代表最新有效对客回复,不代表全量回复人。 |
|
|
33
|
-
| 人员维度 | `assigneeGroup` | 客服组/团队 | 该工单当前分配人归属的客服团队;优先使用工单团队,缺失时用负责人部门兜底。 | 建议 | 按团队/客服组统计绩效 | 不依赖姓名拆分。 |
|
|
34
|
-
| 客户维度 | `customerId` | 客户ID | 客户在系统中的唯一标识。 | 建议 | 客户去重、客户维度统计 | 仅适合内部关联,不建议直接对外展示。 |
|
|
35
|
-
| 客户维度 | `customerContact` | 客户邮箱/联系方式 | 客户邮箱或其他联系方式。 | 建议 | 关联同一客户、客户维度筛选 | 可能为空;不要在报表中泄露不必要的隐私信息。 |
|
|
36
|
-
| 时间字段 | `ticketCreatedAt` | 工单创建时间 | 工单在系统中创建的时间。 | 必需 | 新增工单量、按创建时间筛选、趋势统计 | `fetch_sources.py` 的时间窗按该字段筛选。 |
|
|
37
|
-
| 时间字段 | `customerMessageTime` | 客户来信时间 | 当前工单最早客户消息时间。 | 必需 | 消息量统计、响应时长起点 | 为空时首响/响应相关指标需要说明限制。 |
|
|
38
|
-
| 时间字段 | `firstReplyTime` | 首次回复时间 | 客户来信之后,客服或 AI 第一次有效对客回复时间。 | 必需 | 计算首响时长 | 只统计有效对客回复。 |
|
|
39
|
-
| 时间字段 | `replyTime` | 回复时间 | 最新有效对客回复发出的时间。 | 必需 | 回复趋势、响应表现 | 只代表最新有效对客回复时间。 |
|
|
40
|
-
| 时间字段 | `resolvedAt` | 解决时间 | 工单被标记为已解决的时间。 | 必需 | 已解决工单、解决率、解决趋势 | solved 工单缺少解决时间时返回空,解决率口径需说明。 |
|
|
41
|
-
| 时间字段 | `transferToAgentTime` | 转人工时间 | 工单从 AI 或自动流程转交给人工客服处理的时间。 | 必需 | AI 转人工后人工响应表现 | Human-in-loop 相关分析字段。 |
|
|
42
|
-
| 指标计算 | `replyDuration` | 回复时长 | 客户来信到最新有效对客回复之间的耗时。 | 必需 | 平均响应时长、超时回复 | 单位:分钟;连续来信/连续回复的细节由接口口径处理。 |
|
|
43
|
-
| 指标计算 | `firstReplyDuration` | 首响时长 | 客户来信到第一次有效对客回复之间的耗时。 | 必需 | 平均首次响应时长 | 单位:分钟;工单先转人工时,接口可能按转人工后人工首响口径计算。 |
|
|
44
|
-
| 指标计算 | `resolutionDuration` | 解决时长 | 工单从创建或转人工起点到解决之间的耗时。 | 必需 | 平均解决时长 | 单位:小时;解决时间缺失或时间倒挂会影响该值。 |
|
|
45
|
-
| 指标计算 | `isFirstReply` | 是否首次回复 | 标识当前工单是否已有首次有效对客回复。 | 必需 | 区分有无首响、首响覆盖率 | 返回 true/false。 |
|
|
46
|
-
| AI/口径 | `isAiReply` | 是否AI回复 | 标识最新有效对客回复是否由 AI 发出。 | 必需 | 区分 AI 回复和人工回复 | 只代表最新有效对客回复,不代表工单历史上是否曾有 AI 回复。 |
|
|
47
|
-
| AI/口径 | `isAiResolved` | 是否AI解决/AI关单 | 标识该工单是否由 AI 标记为已解决或关闭。 | 必需 | 支持排除 AI 关单、只看人工解决 | 统计人工解决量时需要排除。 |
|
|
48
|
-
| AI/口径 | `isAdvertising` | 是否广告工单 | 标识该工单是否被判定为广告或垃圾工单。 | 必需 | 默认报表口径剔除广告 | 是否剔除必须在口径说明里写清楚。 |
|
|
49
|
-
| AI/口径 | `isNotification` | 是否通知工单 | 标识该工单是否为通知类工单。 | 必需 | 默认报表口径剔除通知 | 是否剔除必须在口径说明里写清楚。 |
|
|
50
|
-
| 满意度 | `satisfactionScore` | 满意度分数 | 客户提交的满意度评分,取值 1-5,分数越高越满意。 | 可选 | 满意度(CSAT)统计、按评分分档、差评筛选 | 仅客户回收满意度调查后才有值;未发送或未回收时为空,空值不要按 0 计入均值或差评。 |
|
|
51
|
-
| 满意度 | `satisfactionFeedback` | 满意度反馈 | 客户提交满意度时填写的文字反馈。 | 可选 | 差评归因、客户原声摘录、好评/差评文本分析 | 多数工单为空,且只有提交了 `satisfactionScore` 才可能有;含主观/隐私信息,展示需注意脱敏。 |
|
|
52
|
-
| 消息维度 | `messages` | 消息明细 | 工单内客户消息、客服回复、AI 回复和系统消息的明细数组。 | 建议 | 展开对话、做消息趋势、响应时长、时段分析 | 在 `datasource.xlsx` 中通常是 JSON 字符串;分析前先解析。 |
|
|
53
|
-
|
|
54
|
-
## `messages[]` 子字段
|
|
55
|
-
|
|
56
|
-
`messages` 字段是一组消息明细。需要按消息粒度统计时,先对每行的 `messages` 做 JSON 解析,再把数组展开成消息明细表。
|
|
57
|
-
|
|
58
|
-
| 模块 | 接口字段 | 中文字段 | 字段说明 | 必需性 | 用途 | 备注 |
|
|
59
|
-
|------|----------|----------|----------|--------|------|------|
|
|
60
|
-
| 消息维度 | `ticketId` | 工单ID | 这条消息所属工单 ID。 | 必需 | 展开后回连工单维度 | 与顶层 `ticketId` 一致。 |
|
|
61
|
-
| 消息维度 | `messageId` | 消息ID | 消息或回复的唯一 ID。 | 必需 | 消息去重、明细定位 | 只在消息明细粒度使用。 |
|
|
62
|
-
| 消息维度 | `messageTime` | 每条消息时间 | 每条消息实际发生的时间。 | 必需 | 消息趋势、响应时长、时段分析 | messages 数组内每条消息都有 `messageTime`。 |
|
|
63
|
-
| 消息维度 | `messageType` | 消息类型 | 标识消息属于客户消息、人工回复、AI 回复或系统消息等具体类型。 | 必需 | 区分客户消息、客服回复、AI 回复、系统消息 | 展示值以接口返回为准。 |
|
|
64
|
-
| 消息维度 | `senderType` | 发送方类型 | 标识消息由谁发出。 | 必需 | 区分客户、客服、AI、系统消息 | 常见值:`customer` / `agent` / `ai` / `system`。 |
|
|
65
|
-
| 消息维度 | `isAiReply` | 是否AI回复 | 标识该条消息是否 AI 回复。 | 必需 | 按消息粒度统计 AI 回复 | 与顶层 `isAiReply` 不同;这里描述单条消息。 |
|
|
66
|
-
|
|
67
|
-
## 可直接计算的常见指标(建议口径)
|
|
68
|
-
|
|
69
|
-
以下指标是基于当前接口字段可直接计算的默认分析建议,不是业务官方固定口径。用户指定口径优先;用户改口径时,应基于同一份快照重算并在 `calculation_notes.json` 里说明过滤条件、分子分母和限制。
|
|
70
|
-
|
|
71
|
-
| 指标 | 默认算法 | 关键字段 | 口径提醒 |
|
|
72
|
-
|------|----------|----------|----------|
|
|
73
|
-
| 工单量 | 去重统计 `ticketId` | `ticketId` | 当前快照按工单创建时间筛选。 |
|
|
74
|
-
| 新增趋势 | 按 `ticketCreatedAt` 日期分组统计工单量 | `ticketCreatedAt` | 输出时说明时区。 |
|
|
75
|
-
| 解决率 | 已解决工单数 / 工单总数 | `ticketStatus`, `resolvedAt` | 是否只算统计范围内解决、是否剔除 AI 关单,要写清楚。 |
|
|
76
|
-
| 平均首响时长 | `firstReplyDuration` 的平均值 | `firstReplyDuration` | 单位分钟;空值不应按 0 计算。 |
|
|
77
|
-
| 平均回复时长 | `replyDuration` 的平均值 | `replyDuration` | 单位分钟;空值不应按 0 计算。 |
|
|
78
|
-
| 平均解决时长 | `resolutionDuration` 的平均值 | `resolutionDuration` | 单位小时;解决时间缺失会影响样本。 |
|
|
79
|
-
| AI 回复占比 | `isAiReply=true` 的工单数 / 有有效回复的工单数 | `isAiReply`, `replyTime` | 顶层口径按最新有效回复;历史消息维度需展开 `messages`。 |
|
|
80
|
-
| AI 解决占比 | `isAiResolved=true` 的工单数 / 已解决工单数 | `isAiResolved`, `ticketStatus` | 分母需说明是否只含已解决工单。 |
|
|
81
|
-
| 转人工量 | `transferToAgentTime` 非空的工单数 | `transferToAgentTime` | 仅代表已有转人工时间的工单。 |
|
|
82
|
-
| 平均满意度 | `satisfactionScore` 的平均值 | `satisfactionScore` | 分母只算有满意度评分的工单,空值不计入;需说明满意度回收率(有评分工单 / 工单总数)以免被低样本误导。 |
|
|
@@ -1,200 +0,0 @@
|
|
|
1
|
-
# Shulex Desk HTML Design
|
|
2
|
-
|
|
3
|
-
This document defines the visual and structural standard for `solvea-desk` HTML deliverables.
|
|
4
|
-
The renderer uses the sibling files:
|
|
5
|
-
|
|
6
|
-
- `report.css`: fixed self-contained CSS for the report.
|
|
7
|
-
- `report-template.html`: fixed semantic HTML shell with renderer placeholders.
|
|
8
|
-
|
|
9
|
-
Agents should not copy these files into `analysis.py`. Generate structured `report_data.json`, then call `scripts/report/render_report.py` to build the HTML.
|
|
10
|
-
|
|
11
|
-
## Design Read
|
|
12
|
-
|
|
13
|
-
This is an operational report for support leads and business operators. It should feel calm, precise, and audit-friendly: closer to a finance packet or executive operations memo than a marketing page.
|
|
14
|
-
|
|
15
|
-
Use the taste/frontend principles only selectively: readable hierarchy, restrained palette, stable density, and no generic AI decoration. This is not a landing page, portfolio, or brand hero.
|
|
16
|
-
|
|
17
|
-
Design goals:
|
|
18
|
-
|
|
19
|
-
- Make the first screen useful: show report title, time range, data freshness, and 3-5 key metrics.
|
|
20
|
-
- Make numbers easy to audit: every KPI must have a nearby short basis/definition.
|
|
21
|
-
- Make dense tables readable without looking like raw exports.
|
|
22
|
-
- Use a restrained palette and stable layout that prints cleanly.
|
|
23
|
-
- Keep the report self-contained: no remote fonts, no external CSS, no external JavaScript.
|
|
24
|
-
|
|
25
|
-
Avoid:
|
|
26
|
-
|
|
27
|
-
- Hero/landing-page composition, decorative gradients, glassmorphism, large empty visual sections.
|
|
28
|
-
- Nested cards and card-heavy dashboards.
|
|
29
|
-
- Emoji, playful copy, marketing taglines.
|
|
30
|
-
- Low-contrast grey text, tiny table text, or saturated single-hue themes.
|
|
31
|
-
|
|
32
|
-
## Report Data Contract
|
|
33
|
-
|
|
34
|
-
`analysis.py` writes `STATE_TASK_DIR/report_data.json`. The renderer accepts this shape:
|
|
35
|
-
|
|
36
|
-
```json
|
|
37
|
-
{
|
|
38
|
-
"report_slug": "assignee_group_weekly",
|
|
39
|
-
"title": "客服组周报",
|
|
40
|
-
"subtitle": "按客服组统计本周工单量、状态分布和 AI 解决情况。",
|
|
41
|
-
"range": "2026-06-01 至 2026-06-08(北京时间)",
|
|
42
|
-
"row_count": 55,
|
|
43
|
-
"truncated": false,
|
|
44
|
-
"generated_at": "2026-06-08T10:30:00+08:00",
|
|
45
|
-
"kpis": [
|
|
46
|
-
{"label": "工单总量", "value": "55", "basis": "按工单 ID 去重"}
|
|
47
|
-
],
|
|
48
|
-
"sections": [
|
|
49
|
-
{
|
|
50
|
-
"title": "客服组工单量",
|
|
51
|
-
"description": "按当前处理组汇总。",
|
|
52
|
-
"chart": {
|
|
53
|
-
"chartType": "bar",
|
|
54
|
-
"xKey": "group",
|
|
55
|
-
"yKey": "tickets",
|
|
56
|
-
"label": "工单数"
|
|
57
|
-
},
|
|
58
|
-
"columns": [
|
|
59
|
-
{"key": "group", "label": "客服组"},
|
|
60
|
-
{"key": "tickets", "label": "工单数", "numeric": true}
|
|
61
|
-
],
|
|
62
|
-
"rows": [
|
|
63
|
-
{"group": "CxjOnly", "tickets": 23}
|
|
64
|
-
],
|
|
65
|
-
"note": "未设置客服组的工单归入未分组。"
|
|
66
|
-
}
|
|
67
|
-
],
|
|
68
|
-
"footer": "本报告由 Shulex 基于当前账号授权范围内的工单快照生成,仅供运营分析使用。"
|
|
69
|
-
}
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
Rules:
|
|
73
|
-
|
|
74
|
-
- `report_slug` must be ASCII lowercase snake_case, for example `weekly_ticket_summary`.
|
|
75
|
-
- `report_data.json` must contain top-level `kpis` or `sections`; usually both. The renderer rejects free-form legacy shapes that only contain `overview`, `personal_performance`, `daily_trend`, or `status_distribution`.
|
|
76
|
-
- `row_count` means the raw snapshot row count from `fetch_sources.py`; `render_report.py` fills it from `manifest.json.row_counts` when omitted. Do not use filtered analysis sample size here.
|
|
77
|
-
- Visible labels should be Chinese business labels. Raw field names can appear only in short audit notes when necessary.
|
|
78
|
-
- Table columns should be ordered by business importance, not raw data order.
|
|
79
|
-
- Use `numeric: true` for numeric columns so the renderer can right-align and use tabular numbers.
|
|
80
|
-
- `sections[].chart` is optional. HTML reports support self-contained static `bar`、`line`、`pie`、`scatter` charts. Use the same chart type vocabulary as the `render_chart` tool.
|
|
81
|
-
- `bar`、`line`、`scatter` charts use `{"chartType": "bar|line|scatter", "xKey": "...", "yKey": "...", "label": "..."}`.
|
|
82
|
-
- `pie` charts use `{"chartType": "pie", "nameKey": "...", "valueKey": "...", "label": "..."}`. `xKey/yKey` can be used only when they clearly mean category/value.
|
|
83
|
-
- `chart_type` and `type` are accepted as aliases, but new `analysis.py` should write `chartType`.
|
|
84
|
-
- Chart sections always render a toggle: table is selected first, and the same `rows` can be viewed as the configured static chart.
|
|
85
|
-
- Agents must not generate chart HTML, CSS, JavaScript, or full ECharts options for HTML reports. The renderer builds the static chart from the same summary `rows`, so token cost stays close to a table plus a small chart config.
|
|
86
|
-
- Keep `sections[].rows` to report-sized summaries. Long raw detail belongs in `<report_slug>_detail.xlsx`.
|
|
87
|
-
- Do not put raw HTML in `report_data.json`; the renderer escapes values intentionally.
|
|
88
|
-
|
|
89
|
-
## Analysis Script Contract Template
|
|
90
|
-
|
|
91
|
-
`analysis.py` should define small local helpers before building `report_data`. This avoids the common failure where `columns` is written as `["日期", "工单数"]` instead of renderer-readable objects.
|
|
92
|
-
|
|
93
|
-
Copy this shape and fill it with the current report's metrics and summary rows:
|
|
94
|
-
|
|
95
|
-
```python
|
|
96
|
-
REPORT_SLUG = "weekly_ticket_summary"
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
def kpi(label, value, basis):
|
|
100
|
-
return {"label": label, "value": str(value), "basis": basis}
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
def col(key, label, numeric=False):
|
|
104
|
-
item = {"key": key, "label": label}
|
|
105
|
-
if numeric:
|
|
106
|
-
item["numeric"] = True
|
|
107
|
-
return item
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
def section(title, columns, rows, chart=None, description="", note=""):
|
|
111
|
-
return {
|
|
112
|
-
"title": title,
|
|
113
|
-
"description": description,
|
|
114
|
-
"columns": columns,
|
|
115
|
-
"rows": rows,
|
|
116
|
-
**({"chart": chart} if chart else {}),
|
|
117
|
-
**({"note": note} if note else {}),
|
|
118
|
-
}
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
daily_rows = [
|
|
122
|
-
{"date": "03-01", "tickets": 12},
|
|
123
|
-
{"date": "03-02", "tickets": 18},
|
|
124
|
-
]
|
|
125
|
-
|
|
126
|
-
report_data = {
|
|
127
|
-
"report_slug": REPORT_SLUG,
|
|
128
|
-
"title": "工单周报",
|
|
129
|
-
"range": "2026-03-01 至 2026-03-07(北京时间)",
|
|
130
|
-
"truncated": bool(manifest.get("truncated")),
|
|
131
|
-
"kpis": [
|
|
132
|
-
kpi("工单总量", total_tickets, "按工单 ID 去重"),
|
|
133
|
-
],
|
|
134
|
-
"sections": [
|
|
135
|
-
section(
|
|
136
|
-
"每日工单趋势",
|
|
137
|
-
[col("date", "日期"), col("tickets", "工单数", numeric=True)],
|
|
138
|
-
daily_rows,
|
|
139
|
-
chart={"chartType": "line", "xKey": "date", "yKey": "tickets", "label": "工单数"},
|
|
140
|
-
)
|
|
141
|
-
],
|
|
142
|
-
}
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
Rules for the template:
|
|
146
|
-
|
|
147
|
-
- `columns` 必须是对象数组,每个对象至少有 `key` 和 `label`;不要写成字符串数组。
|
|
148
|
-
- Every `rows` item must use the same keys declared in `columns`.
|
|
149
|
-
- Chart data comes from the same `rows`; do not create separate `x` / `series` fields for HTML.
|
|
150
|
-
- Run `render_report.py --validate-only` immediately after writing `report_data.json`.
|
|
151
|
-
|
|
152
|
-
## Page Structure
|
|
153
|
-
|
|
154
|
-
The renderer outputs this structure:
|
|
155
|
-
|
|
156
|
-
1. Report masthead
|
|
157
|
-
- Title
|
|
158
|
-
- Subtitle
|
|
159
|
-
- Meta strip: data range, row count, truncation status, generated time
|
|
160
|
-
2. KPI band
|
|
161
|
-
- 3-5 compact KPI blocks
|
|
162
|
-
- Each block has label, value, and one short basis line
|
|
163
|
-
3. Main sections
|
|
164
|
-
- Each section starts with an `h2`
|
|
165
|
-
- Optional static chart for compact trends or breakdowns; chart sections include a table/chart toggle by default
|
|
166
|
-
- Tables for comparisons and breakdowns when no chart is configured
|
|
167
|
-
- Short notes below tables for caveats
|
|
168
|
-
4. Calculation notes
|
|
169
|
-
- Compact formula / range / definition from `calculation_notes.json`
|
|
170
|
-
5. Footer
|
|
171
|
-
- Authorized snapshot statement and limitations
|
|
172
|
-
|
|
173
|
-
## Rendering
|
|
174
|
-
|
|
175
|
-
Use the renderer:
|
|
176
|
-
|
|
177
|
-
```bash
|
|
178
|
-
npx --yes @shulex/cxclawctl@latest script skills/solvea-desk/scripts/report/render_report.py \
|
|
179
|
-
--task-id "<task_id>" \
|
|
180
|
-
--report-slug "assignee_group_weekly"
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
Default paths:
|
|
184
|
-
|
|
185
|
-
- Input: `workspace/state/solvea-desk/<task_id>/report_data.json`
|
|
186
|
-
- Input: `workspace/state/solvea-desk/<task_id>/calculation_notes.json`
|
|
187
|
-
- Output: `workspace/outputs/solvea-desk/<task_id>/<report_slug>.html`
|
|
188
|
-
|
|
189
|
-
Use `--report-data`, `--notes`, or `--output` only for local debugging or unusual internal workflows.
|
|
190
|
-
|
|
191
|
-
## File Naming
|
|
192
|
-
|
|
193
|
-
The report file name must match the analysis scenario:
|
|
194
|
-
|
|
195
|
-
- Weekly summary: `weekly_ticket_summary.html`
|
|
196
|
-
- Assignee group breakdown: `assignee_group_weekly.html`
|
|
197
|
-
- Channel trend: `channel_trend.html`
|
|
198
|
-
- CSAT analysis: `csat_analysis.html`
|
|
199
|
-
|
|
200
|
-
When the user refines the same report, overwrite the same file. When the user starts a clearly different report, choose a new slug.
|
|
@@ -1,44 +0,0 @@
|
|
|
1
|
-
<!DOCTYPE html>
|
|
2
|
-
<html lang="zh-CN">
|
|
3
|
-
<head>
|
|
4
|
-
<meta charset="UTF-8">
|
|
5
|
-
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
6
|
-
<title>{{REPORT_TITLE}}</title>
|
|
7
|
-
<style>
|
|
8
|
-
{{REPORT_CSS}}
|
|
9
|
-
</style>
|
|
10
|
-
</head>
|
|
11
|
-
<body>
|
|
12
|
-
<main class="report">
|
|
13
|
-
<article class="sheet">
|
|
14
|
-
<header class="masthead">
|
|
15
|
-
<p class="eyebrow">Shulex Desk</p>
|
|
16
|
-
<h1>{{REPORT_TITLE}}</h1>
|
|
17
|
-
<p class="subtitle">{{REPORT_SUBTITLE}}</p>
|
|
18
|
-
<div class="meta-strip">
|
|
19
|
-
{{META_ITEMS}}
|
|
20
|
-
</div>
|
|
21
|
-
</header>
|
|
22
|
-
|
|
23
|
-
<section class="section">
|
|
24
|
-
<div class="kpi-grid">
|
|
25
|
-
{{KPI_BLOCKS}}
|
|
26
|
-
</div>
|
|
27
|
-
</section>
|
|
28
|
-
|
|
29
|
-
{{SECTIONS}}
|
|
30
|
-
|
|
31
|
-
<section class="section">
|
|
32
|
-
<h2>口径说明</h2>
|
|
33
|
-
<div class="formula-list">
|
|
34
|
-
{{FORMULA_NOTES}}
|
|
35
|
-
</div>
|
|
36
|
-
</section>
|
|
37
|
-
|
|
38
|
-
<footer class="footer">
|
|
39
|
-
{{FOOTER}}
|
|
40
|
-
</footer>
|
|
41
|
-
</article>
|
|
42
|
-
</main>
|
|
43
|
-
</body>
|
|
44
|
-
</html>
|