check-in-report-skill

Background

本 skill 配合 check-in-manager-skill 使用，负责统计分析和报告生成。

数据来源（v4 更新）：

• 活动配置：check-in-manager-skill/activities/{group_id}/{activity_id}.txt（自然语言规则描述）
• 打卡记录：check-in-manager-skill/records/{group_id}/{activity_id}/YYYY-MM-DD.json（结构化记录）

Activity ID 格式（v4 简化）：{类型}_{创建者}_{时间戳}

• 示例：running_ceceilyqi_1775702066、reading_bob_1775702401
• 纯英文/数字，无中文（详见 check-in-manager-skill 的 Activity ID v4 规范）

群组隔离：通过 group_id 实现目录级隔离，每个群的活动和记录完全独立

Workflow

Step 1 — 解析请求

确定：

• 时间周期：本日/本周/本月/自定义区间/历史累计
• 报告类型：进度排名（A）| 周期结算（B）| 跨周期对比（C）| 催办提醒（D）
• 目标活动：未指定时扫描当前群活动列表

模板说明见 references/report-templates.md。

Step 2 — 定位数据

获取群组 ID：

chat_id = inbound_metadata["chat_id"]  # "wecom:T14370047A"
# 安全获取 group_id，不存在/为空则用处理后的 chat_id
group_id = inbound_metadata.get("group_id") or chat_id.replace(":", "_").replace("#", "_").replace("/", "_")

定位目录（相对路径）：

CURRENT_SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILLS_DIR="$(dirname "$CURRENT_SKILL_DIR")"
MANAGER_DIR="${SKILLS_DIR}/check-in-manager-skill"
ACTIVITIES_DIR="${MANAGER_DIR}/activities/${GROUP_ID}"
RECORDS_DIR="${MANAGER_DIR}/records/${GROUP_ID}"

扫描活动：

ls ${ACTIVITIES_DIR}/*.txt  # 仅当前群

读取规则：

cat ${ACTIVITIES_DIR}/{activity_id}.txt

提取：活动名、达标线、核心指标、排序方向、惩罚机制、特殊规则。

加载记录：

python3 scripts/load_records.py \
  ${RECORDS_DIR}/{activity_id} \
  <start_date> <end_date>

Step 3 — 统计计算

基本调用：

python3 scripts/calc_stats.py '<records_json>' '<members_json>' \
  --mode <mode> --metric <field> [--metric2 <field2>] [--factor <num>]

7种计算模式：

输出格式（原始数值）：

{
  "老张": {
    "count": 3,
    "value": 3.95,        // ⚠️ 原始数值，无单位
    "records": [...]
  }
}

关键点：

• ✅ value 是纯数值（如 3.95），不是格式化字符串（如 3'57"/km）
• ✅ 无打卡记录的成员自动返回 value: 0, count: 0
• ✅ 保留 records 数组供二次分析

Step 4 — 格式化与报告生成

4.1 单位转换（AI 负责）

从活动规则 TXT 提取单位定义，将原始数值转换为可读文本：

配速转换代码（核心）：

minutes = int(pace_raw)
seconds = (pace_raw - minutes) * 60
result = f"{minutes}'{int(seconds)}\"/km"

4.2 生成报告

根据 Step 1 确定的报告类型，使用 references/report-templates.md 对应模板：

报告要求：

• ✅ 全员覆盖（未打卡成员也要列出）
• ✅ 格式化后的指标（不是原始数值）
• ✅ 结尾鼓励语

Step 5 — 回复用户

使用消息工具将报告推送给用户。

Constraints

• 数据真实性：仅使用 records/{group_id}/{activity_id}/ 中的实际记录
• 全员覆盖：未打卡成员也必须在报告中列出
• 规则驱动：达标线、排序方向、核心指标 100% 来自活动 TXT 文件
• 群组隔离：只统计当前群数据，不跨群访问

路径约定（v4）

相对路径发现：

CURRENT_SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
MANAGER_DIR="$(dirname "$CURRENT_SKILL_DIR")/check-in-manager-skill"

目录结构：

skills/
├── check-in-manager-skill/
│   ├── activities/{group_id}/{activity_id}.txt
│   └── records/{group_id}/{activity_id}/YYYY-MM-DD.json
└── check-in-report-skill/
    ├── SKILL.md
    └── scripts/

Activity ID 格式：{类型}_{创建者}_{时间戳}（纯英文/数字）

群组 ID 格式：wecom_T14370047A（从 chat_id 转换）

工具脚本