Management Dashboard Skill

管理驾驶舱 · 管理者日报生成

硬性约束（必守）

本技能只做「录音 AI 总结内容」的管理分析与报表生成，数据源唯一为录音服务返回的 ai_summary_content 字段，不是当前对话里的文字、也不是 Agent 臆测。

完成前不得结束任务：完成 步骤 1（session_status）→ 2（main.py）→ 3（返回文件路径）。contents 为空时 main.py 仍须生成 HTML，禁止提前结束。

目标

1. 直接调用宿主「当前会话」查询（OpenClaw：session_status，sessionKey="current"），从返回的 agentId 获取 agentId。
2. 调用录音服务 POST /api/recordings/asr-completed/page，以 agentId 分页拉取 AI 总结内容。
3. 使用 LLM 分析所有 AI 总结：生成包含六大板块的管理驾驶舱数据。
4. 生成适配手机/PC 的 HTML 报表，保存到 skill 目录下的 reports/ 子目录。
5. 向用户返回 生成的文件路径。

常见触发说法：系统驾驶舱、system dashboard（中英文均可触发）。

LegionClaw 运行约定

• 会话形态：agent::<渠道>:<用户 id>；渠道为空时为三段 agent::<用户 id>（无 ::）。
• 执行位置：curl 与 Python 脚本须在 LegionClaw 任务运行环境执行；环境需能访问录音服务（见下文接口）。
• 成功判定：HTTP 2xx 且响应 JSON code === 0（数值零）。
• 零条数据：contents 为空数组时，仍生成 HTML 空报表（各指标为 0），并返回文件路径。

请求体参数

• 用户未明确查询时间范围：固定按「近一周」 换算并传入 startTime / endTime（endTime = 当前时间，startTime = 当前时间 − 7 天）。
• 用户明确说了范围（如「近三天」「上周」「6 月 1 日到 6 月 4 日」）：按话术换算为 YYYY-MM-DD HH:mm:ss 后传入。
• 每次请求应同时包含 agentId、uuid、startTime、endTime 四个字段。

{
  "agentId": "",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "startTime": "2026-06-07 00:00:00",
  "endTime": "2026-06-08 23:59:59"
}

从用户话术换算时间（Agent 必做）

在运行环境用当前时间作 endTime（除非用户明确指定结束时间）。startTime = 结束时间往前推对应天数。

成功响应（示例结构）

{
  "code": 0,
  "msg": "success",
  "data": {
    "userId": "",
    "orgId": "",
    "startTime": "2026-05-07T00:00:00",
    "endTime": "2026-06-08T23:59:59",
    "isAdmin": true,
    "contents": [
      {
        "aiSummaryContent": "# **会议纪要**\n\n## 会议总结\n\n本次会议...",
        "email": null,
        "memberName": null,
        "mobile": null,
        "orgId": null,
        "orgName": null,
        "userId": "e7a9123e12c54f06bf75a1e931beef87",
        "userName": "17639418027"
      },
      {
        "aiSummaryContent": "# **会议纪要**\n\n## 会议总结\n\n本次会议...",
        "userId": "d8db9fe5eb1a4880bc57dd7852edeb08",
        "userName": "18762097213"
      }
    ],
    "currentPage": 1,
    "pageSize": 20,
    "total": 45,
    "totalPages": 3,
    "completed": false
  }
}

关键字段：

分页逻辑：

1. 首次请求：生成新的 uuid，发送请求
2. 检查 data.completed：
   • 若为 false：使用相同的 uuid 再次请求，获取下一页
   • 若为 true：所有数据已获取完毕，停止分页
3. 累积所有页的 contents 到同一个数组

用户回复规范

接口失败（code 非 0、网络错误）：正文一行 + 可选收尾提问。禁止过程描述。

• code 为 4001 / 5001：正文取接口 msg
• 其他失败：取 msg，无则用「暂未获取到数据」

接口成功但 contents 为空（code=0）：禁止回复「暂无可统计数据」「未查到录音数据」等而不生成报表。必须执行 main.py 生成空报表，按下方「零条数据」示例返回文件路径。

agentId 自动获取（必做 · 直接查当前会话）

必须先调用宿主「当前会话」查询 agentId，再拉数。 不得在未调用步骤 1 前回复「无法获取语音数据」。

禁止行为

获取步骤（按序执行）

步骤 0 — 用户消息已带 agentId

• 用户明确给出 agentId → 直接采用，可跳过步骤 1。

步骤 1 — 当前会话查询（主路径，必须执行）

在 LegionClaw / OpenClaw 宿主上调用内置会话工具：

Agent 操作说明：

1. 调用 session_status，传入 sessionKey="current"。
2. 从返回 JSON 中读取 agentId 字段。
3. 校验 agentId 非空后，再执行分页请求。

步骤 2 — 仍为空（仅此情况可索要）

已调用当前会话查询（session_status current），仍无法获取 agentId。
请确认本任务是否绑定当前 LegionClaw 会话，或直接提供 **agentId**。

执行前自检

• 已调用 session_status + sessionKey="current"
• 已从返回的 agentId 字段得到非空值
• 已生成分页用的 uuid
• 已执行分页 curl 获取所有 contents，未仅凭对话生成分析
• 无论 contents 是否为空，均完成 HTML 生成并返回文件路径

分析方式（核心）

只分析接口返回的 AI 总结内容，生成管理驾驶舱报表。

LLM 分析（步骤 6 · 必做）

1. 将所有 contents 中的 aiSummaryContent 按发言人 userName 合并为一个大文本。
2. 调用 LLM，使用步骤 6 中的 prompt 模板。
3. 解析 LLM 返回的 JSON，验证所有必需字段存在。

执行步骤

1. 【必做】 调用 session_status（sessionKey="current"） 获取 agentId；不得跳过。

2. 【必做 · 唯一入口】 调用 main.py 完成拉数、分析、生成 HTML（空数据也会生成空报表）：

python3 skills/management-dashboard/main.py "${USER_INPUT}" "${AGENTID}"

工作目录为技能目录时：

python3 main.py "${USER_INPUT}" "${AGENTID}"

1. 解析 main.py 输出（取最后一行 JSON）：

   • success: true：向用户返回 message 与 file_path（无论 data_count 是否为 0）
   • success: false：仅返回 message（接口错误，不生成 HTML）

2. 按 用户回复规范 返回结果。

禁止跳过 main.py 自行 curl 后在空数据时文字回复；

---

附录：手动 curl 分页（仅供调试，Agent 勿用此路径替代 main.py）

1. 根据用户对话换算时间（见上表）。
2. 分页拉取录音数据：

# 生成 UUID
UUID=$(python3 -c "import uuid; print(str(uuid.uuid4()))")

# 从 config.py 读取 API 地址
API_BASE_URL=$(python3 -c "import sys; sys.path.insert(0, 'skills/management-dashboard'); from config import API_BASE_URL; print(API_BASE_URL)")

# 首次请求
END_TIME=$(date "+%Y-%m-%d %H:%M:%S")
START_TIME=$(date -v-1d "+%Y-%m-%d %H:%M:%S")  # macOS; Linux: date -d '1 day ago'

curl -sS -X POST "${API_BASE_URL}/api/recordings/asr-completed/page" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{\"agentId\":\"${AGENTID}\",\"uuid\":\"${UUID}\",\"startTime\":\"${START_TIME}\",\"endTime\":\"${END_TIME}\"}" \
  -o /tmp/dashboard_page_1.json

# 检查 completed 字段
COMPLETED=$(python3 -c "import json; d=json.load(open('/tmp/dashboard_page_1.json')); print(d['data']['completed'])")

# 若 completed=false，继续请求下一页（使用相同的 UUID）
PAGE=2
while [ "$COMPLETED" = "False" ] || [ "$COMPLETED" = "false" ]; do
  curl -sS -X POST "${API_BASE_URL}/api/recordings/asr-completed/page" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d "{\"agentId\":\"${AGENTID}\",\"uuid\":\"${UUID}\",\"startTime\":\"${START_TIME}\",\"endTime\":\"${END_TIME}\"}" \
    -o "/tmp/dashboard_page_${PAGE}.json"
  
  COMPLETED=$(python3 -c "import json; d=json.load(open('/tmp/dashboard_page_${PAGE}.json')); print(d['data']['completed'])")
  PAGE=$((PAGE + 1))
done

1. 合并所有页的 contents 并检查是否为空：

python3 -c "
import json, glob

all_contents = []
for f in sorted(glob.glob('/tmp/dashboard_page_*.json')):
    d = json.load(open(f, encoding='utf-8'))
    contents = (d.get('data') or {}).get('contents') or []
    
    # 新格式：contents 为对象数组，提取 aiSummaryContent 和 userName
    for item in contents:
        if isinstance(item, dict):
            all_contents.append({
                'aiSummaryContent': item.get('aiSummaryContent', ''),
                'userName': item.get('userName') or item.get('memberName') or '',
                'userId': item.get('userId', ''),
            })
        else:
            # 兼容旧格式：纯字符串
            all_contents.append({
                'aiSummaryContent': str(item),
                'userName': '',
                'userId': '',
            })

print(f'total_contents={len(all_contents)}')

# 保存到文件供后续使用（空数组也保存）
json.dump(all_contents, open('/tmp/dashboard_all_contents.json', 'w', encoding='utf-8'), ensure_ascii=False)
"

1. 若 contents 条数为 0：跳过 LLM，使用空分析结果，继续生成 HTML（见步骤 6～7）。

2. 调用 LLM 分析（contents 非空时必做；为空时跳过）→ 保存分析结果为 /tmp/dashboard_analysis.json。

使用以下 prompt 模板（注意：使用 aiSummaryContent 字段进行分析，使用 userName 字段进行成员评分）：

你是一个专业的销售团队管理分析师。请分析以下录音 AI 总结内容，生成管理驾驶舱报表数据。

团队：{team_name}
日期：{date_str}
成员分组统计：{user_groups_str}

【重要规则】
- **数据来源唯一性**：所有分析必须严格基于下方「录音内容」中的 AI 总结文本，禁止使用历史数据、外部数据或自行编造数据。
- **成员姓名**：必须严格使用上方「成员分组统计」中列出的姓名，禁止虚构、编造或使用 userId/数字ID 作为姓名。
- **无法识别时跳过**：如果录音内容中无法识别到具体成员姓名或关键信息，不要猜测，直接跳过该条记录的分析。
- **top_performers 和 needs_improvement**：其中的 name 字段必须是成员分组统计中存在的姓名。
- **数值必须来自原文**：所有统计数据（客户数、录音时长、拜访次数等）必须从录音 AI 总结内容中提取，禁止凭空编造。如果原文中未提及某项数据，返回 0 或空值。

录音内容（每条记录包含发言人信息）：
{combined_contents}

请从以下维度进行分析，并以 JSON 格式返回：

1. **团队资产沉淀大盘**（长期累积维度）
   - total_customers: 历史累积拜访客户总量（整数）
   - month_customers: 本月至今累积拜访（整数）
   - today_customers: 今日新增实地拜访（整数）
   - avg_per_person: 人均长期维护客群深度（整数）

2. **每日外勤实地效能监测**
   - total_recording_minutes: 今日双向有效录音总时长（分钟，整数）
   - avg_minutes_per_person: 人均日面谈时长（分钟，浮点数）
   - total_visits: 今日实地有效面谈总数（整数）
   - avg_visits_per_person: 人均日均实地探店次数（浮点数）
   - customer_distribution: 客群结构分布
     * old_customer_maintenance: 老客维护与转介绍（整数）
     * new_customer_prospecting: 陌生新商圈扫街（整数）
   - regional_distribution: 产业带轨迹分布（数组，每项包含 region 和 visit_count）

3. **当日合规与红线监控**
   - compliance_metrics: 合规指标数组，每项包含：
     * metric_name: 监控指标名称
     * achievement_rate: 达成率（百分比字符串，如 "100%"）
     * status: 状态（"正常" / "警告" / "危险"）
     * ai_audit_opinion: AI 每日穿透审计意见

4. **当日 RM 业务水平排行**
   - top_performers: 优秀 RM 数组（最多3名），每项包含：
     * rank: 排名（1, 2, 3）
     * region: 片区
     * name: 姓名
     * score: 得分（百分制）
     * behavior_description: 销冠/高水平行为描述
   - needs_improvement: 待提升 RM 数组，每项包含：
     * region: 片区
     * name: 姓名
     * score: 得分
     * problem_diagnosis: 问题诊断
   - user_scores: 按成员分组统计得分（数组），每项包含：
     * user_name: 成员姓名（必须与上方成员分组统计中的姓名一致）
     * total_score: 总分
     * avg_score: 平均分
     * recording_count: 录音条数（必须与上方成员分组统计中的条数一致）
     * top_score: 最高分
     * min_score: 最低分

5. **当日线索转化效率**
   - lead_conversion:
     * a_level_count: A 级商机数量
     * a_level_details: A 级详情描述
     * b_level_count: B 级商机数量
     * b_level_followup: B 级跟进建议
     * c_level_count: C 级商机数量
     * c_level_interception: C 级 AI 拦截核查

6. **管理者跟进与靶向督导建议**
   - management_suggestions: 建议数组，每项包含：
     * title: 建议标题
     * content: 建议内容

请确保返回的是合法的 JSON 格式，不要包含其他文字说明。

回复示例

接口错误（4001 / 5001）

当前用户非管理员，拒绝执行

请问您是否需要我们协助联系管理员开通权限？

零条数据（仍生成报表）

已根据 2026-06-23 13:16:00 至 2026-06-23 14:16:00 生成管理驾驶舱报告（当前查询周期暂无录音数据）。

报表已保存至：`skills/management-dashboard/reports/系统驾驶舱报告_2026-06-23.html`

<!-- 请问您是否希望扩大时间范围后重新查询？ -->

成功生成报表

已根据 2026-06-07 00:00:00 至 2026-06-14 23:59:59（近一周）的 45 条录音 AI 总结，生成管理驾驶舱报告。

报表已保存至：`skills/management-dashboard/reports/系统驾驶舱报告_2026-06-07_06-14.html`

文件结构

management-dashboard-skill/
├── SKILL.md                    # 本文件
├── main.py                     # 主逻辑入口
├── analyzer.py                 # LLM 分析模块
├── html_generator.py           # HTML 生成器
├── utils.py                    # 工具函数
├── config.py                   # 配置文件
├── requirements.txt            # Python 依赖
├── reports/                    # 报表输出目录（自动创建）
└── README.md                   # 说明文档

配置说明

所有配置集中在 config.py 文件中，修改该文件即可：

# API 配置（唯一配置位置，其他文档引用此文件）
API_BASE_URL = os.getenv('API_BASE_URL', 'http://your-api-server:port')
API_ENDPOINT = '/api/recordings/asr-completed/page'

# 分页配置
DEFAULT_PAGE_SIZE = 20
DEFAULT_DAYS = 7  # 默认查询最近 7 天（一周）

如需修改 API 地址，请直接编辑 config.py 文件中的 API_BASE_URL。

文件编码规范（必守 · 全平台展示）

生成的报表须在 iOS / Android / iPad / PC / 微信小程序 WebView 上正确显示中文，统一使用 UTF-8：

HTML 头部必须包含（html_generator.py 已内置，禁止删除）：

写入 HTML 时必须调用 utils.write_html_file() 或等价地使用：

with open(path, 'w', encoding='utf-8-sig', newline='\n') as f:
    f.write(html)

禁止：使用系统默认编码、gbk/gb2312、或不指定 encoding 参数写文件。

若报表通过 HTTP 服务访问，服务端响应头须包含：Content-Type: text/html; charset=utf-8。

注意事项

1. LLM 调用：需要在 main.py 的 _get_llm_client() 方法中实现实际的 OpenClaw LLM 调用逻辑。
2. API 地址：确保 config.py 中的 API_BASE_URL 配置正确。
3. 输出目录：reports/ 目录会自动创建，无需手动配置。
4. 网络访问：Skill 需要访问录音查询 API，确保网络连通。
5. 分页逻辑：必须使用相同的 uuid 进行分页请求，直到 completed=true。
6. 文件编码：严格遵守上文「文件编码规范」，HTML 必须用 utf-8-sig 写入。

故障排查

问题：接口调用失败

解决：检查 config.py 中的 API_BASE_URL 是否正确，确保 API 服务正常运行。

问题：LLM 返回空结果

解决：检查 main.py 中的 _get_llm_client() 实现，确保 OpenClaw LLM 调用正常。

问题：数据为空但未生成报表

解决：检查 main.py 是否在 contents 为空时提前 return；空数据应继续走 analyzer._empty_result() 和 HTML 生成。