家庭积分

记录全家成员的日常好表现，按人分别计分，累计晋级王者段位。支持老公、老婆、大宝、二宝、三宝等任意家庭成员。

存储模式

Skill 支持两种存储模式，根据配置自动选择：

模式判断

检查配置文件 config.json（与 SKILL.md 同目录）是否存在且包含 online_doc_id：

• 存在且有效 → 在线模式，读取配置中的文档信息
• 不存在或无效 → 进入首次初始化流程

在线模式配置（config.json）

文件位于 ~/.workbuddy/skills/family-points/config.json，结构：

{
  "online_doc_id": "<文档ID>",
  "online_sheet_id": "<SheetID>",
  "online_doc_url": "https://docs.qq.com/smartsheet/<文档标识>",
  "doc_type": "smartsheet"
}

该文件由首次初始化时自动生成，不同用户各有自己的配置。

核心规则

• 基础分：对照事项参考库取分（2~20 分不等，因类别而异）
• 感动加分：超出预期的暖心行为，额外 0~5 分
• 主动加倍（成人适用）：主动做的行为基础分可上浮 20%~50%
• 进步加分（孩子适用）：学习/习惯方面比之前进步，额外 3~10 分
• 鼓励为主：对孩子以鼓励为导向，进步远比满分重要
• 公平公正：家庭成员间计分标准一致

等级体系：青铜成员 → 白银 → 黄金 → 铂金 → 钻石 → 星耀 → 最强王者 → 荣耀王者 → 传奇王者 → 百星王者

智能表格结构

> 注：智能表格部分默认字段（单选/数字/日期/图片/文本）无法删除，保留不用即可。

成员区分

记录时通过「家庭成员」字段区分。支持任意中文名称：老公、老婆、大宝、二宝、三宝、爸爸、妈妈等。

参考事项库见 references/reference_items.json（105 项），每条含 applicable_to：
- all — 全家通用
- adults — 成人
- kids — 孩子

在线模式工作流程

首次初始化（交互式）

当 Skill 被触发，但 config.json 不存在时，先问用户选择：

🔧 家庭积分 — 首次设置

请选择：
1. 创建新家庭积分表（建好后把链接分享给家人）
2. 加入已有家庭积分表（输入家人分享给你的文档链接）

请回复 1 或 2。

选项 1：创建新表

1. 调用 mcp__tencent-docs__manage.create_file：
   json {"title": "家庭积分记录表", "file_type": "smartsheet"}
2. 提取返回的 file_id 和 url
3. 调用 mcp__tencent-docs__smartsheet.list_tables 获取默认 sheet_id
4. 调用 mcp__tencent-docs__smartsheet.add_fields 添加业务字段：
   json { "file_id": "<file_id>", "sheet_id": "<sheet_id>", "fields": [ {"field_title":"序号","field_type":"number","property_number":{"decimal_places":0,"use_separate":false}}, {"field_title":"日期","field_type":"dateTime","property_date_time":{"format":"yyyy/m/d","auto_fill":false}}, {"field_title":"家庭成员","field_type":"singleSelect","property_single_select":{"options":[ {"text":"老公","style":3},{"text":"老婆","style":4}, {"text":"大宝","style":1},{"text":"二宝","style":2},{"text":"三宝","style":5} ]}}, {"field_title":"事项描述","field_type":"text"}, {"field_title":"事项类别","field_type":"singleSelect","property_single_select":{"options":[ {"text":"家务劳动","style":4},{"text":"烹饪美食","style":2},{"text":"关爱家人","style":1}, {"text":"育儿带娃","style":3},{"text":"学习成长","style":5},{"text":"行为习惯","style":6}, {"text":"健康运动","style":4},{"text":"精神品质","style":5},{"text":"家庭维护","style":7},{"text":"自定义","style":8} ]}}, {"field_title":"基础分","field_type":"number","property_number":{"decimal_places":0,"use_separate":false}}, {"field_title":"感动加分","field_type":"number","property_number":{"decimal_places":0,"use_separate":false}}, {"field_title":"总分","field_type":"number","property_number":{"decimal_places":0,"use_separate":false}}, {"field_title":"备注","field_type":"text"} ] }
   > 注意："日期"/"文本"等字段名可能与默认字段冲突，冲突时跳过该字段，使用默认字段代替（如用默认"文本"字段记录事项描述）。
5. 调用 mcp__tencent-docs__manage.set_privilege 设置 policy=3（所有人可编辑）
6. 写入 config.json：包含 online_doc_id, online_sheet_id, online_doc_url, doc_type
7. 告知用户：

✅ 家庭积分表已创建！
📎 文档链接：https://docs.qq.com/smartsheet/XXXXX
🔗 已设为「所有人可编辑」

👉 把上面的链接发给家人，让他们在 WorkBuddy 里
   选「加入已有表格」并粘贴这个链接，就能协作啦！

选项 2：加入已有表

1. 请用户粘贴文档链接（如 https://docs.qq.com/smartsheet/XXX）
2. 从 URL 末尾提取 file_id：取 /smartsheet/ 之后的部分
3. 调用 mcp__tencent-docs__smartsheet.list_tables，传入提取的 file_id，验证可访问
4. 提取返回的 sheet_id
5. 写入 config.json
6. 告知用户：

✅ 已加入家庭积分表！
现在全家人都在同一份表格里协作 🤝

记录积分

步骤 A：确定成员和事项

从用户输入中识别「谁」做了「什么」：

• "老公今天做了一顿饭" → 成员=老公，行为=做饭
• "大宝主动写完了作业" → 成员=大宝，行为=完成作业

步骤 B：搜索参考项

读取 references/reference_items.json，用关键词做子串匹配（name + desc + category），取 top 8 结果。优先展示 applicable_to 与成员类型匹配的。

步骤 C：向用户确认

展示匹配结果并让用户确认基础分和感动分。孩子用"鼓励加分"代替"感动加分"。

步骤 D：写入智能表格

先从 config.json 读取配置。

获取最后序号：调用 mcp__tencent-docs__smartsheet.list_records 读取所有记录：

{"file_id": "<online_doc_id>", "sheet_id": "<online_sheet_id>", "sort": [{"field_title":"序号","desc":true}], "limit":1}

从返回结果取最大序号 + 1 作为新序号。

写入记录：调用 mcp__tencent-docs__smartsheet.add_records：

{
  "file_id": "<online_doc_id>",
  "sheet_id": "<online_sheet_id>",
  "records": [{
    "field_values": [
      {"field":"序号","number_value":<new_id>},
      {"field":"日期","string_value":"<Timestamp>"},
      {"field":"家庭成员","option_value":{"items":[{"text":"<成员>","style":"<style>"}]}},
      {"field":"文本","text_value":{"items":[{"text":"<描述>","type":"text"}]}},
      {"field":"事项类别","option_value":{"items":[{"text":"<类别>","style":"<style>"}]}},
      {"field":"数字","number_value":<基础分>},
      {"field":"感动加分","number_value":<感动分>},
      {"field":"总分","number_value":<基础分+感动分>},
      {"field":"备注","text_value":{"items":[{"text":"<备注>","type":"text"}]}}
    ]
  }]
}

> 重要：日期格式 — dateTime 字段使用毫秒级 Unix 时间戳字符串（如 "1782144000000" = 2026/6/23）。
>
> 重要：自动计算总分 — 写入时必须将 总分 字段设置为 基础分 + 感动加分 的和。
>
> 重要：字段名映射 — 智能表格中「事项描述」使用默认"文本"字段，"基础分"使用默认"数字"字段。
>
> 家庭成员样式映射：老公=3(蓝), 老婆=4(绿), 大宝=1(红), 二宝=2(橙), 三宝=5(紫)
>
> 事项类别样式映射：关爱家人=1(红), 烹饪美食=2(橙), 育儿带娃=3(蓝), 家务劳动/健康运动=4(绿), 学习成长/精神品质=5(紫), 行为习惯=6(粉), 家庭维护=7(灰), 自定义=8(白)

更新/删除记录

更新：mcp__tencent-docs__smartsheet.update_records，传入 record_id 和需修改的 field_values。更新后重新计算总分 = 基础分 + 感动加分并写入。

删除：mcp__tencent-docs__smartsheet.delete_records，传入 record_ids 数组。

查询统计

读取全部数据

调用 mcp__tencent-docs__smartsheet.list_records，不设 limit 一次拉取全部：

{"file_id": "<online_doc_id>", "sheet_id": "<online_sheet_id>"}

解析并自动计算合计

解析返回的 records 数组，每条记录从 field_values 中提取各字段值。

自动计算合计统计（每次查询实时计算）：

# 遍历所有记录，累加
total_base = 0       # 基础分合计
total_bonus = 0      # 感动分合计
total_points = 0     # 总分合计
record_count = 0     # 记录数
member_stats = {}    # 按成员分组: {member: {total, count}}
category_stats = {}  # 按类别分组: {category: {total, count}}

for record in records:
    values = {fv["field"]: fv for fv in record["field_values"]}
    member = values.get("家庭成员", {}).get("reference_value", {}).get("items", [""])[0]
    category = values.get("事项类别", {}).get("reference_value", {}).get("items", [""])[0]
    base = values.get("数字", {}).get("number_value", 0) or 0
    bonus = values.get("感动加分", {}).get("number_value", 0) or 0
    total = values.get("总分", {}).get("number_value", 0) or 0
    note = (values.get("备注", {}).get("text_value", {}).get("items", [{}])[0] or {}).get("text", "")
    seq = values.get("序号", {}).get("number_value", 0) or 0
    date_val = values.get("日期", {}).get("string_value", "")

    total_base += base
    total_bonus += bonus
    total_points += total
    record_count += 1

    # 按成员分组
    if member not in member_stats:
        member_stats[member] = {"total": 0, "count": 0}
    member_stats[member]["total"] += total
    member_stats[member]["count"] += 1

    # 按类别分组
    if category not in category_stats:
        category_stats[category] = {"total": 0, "count": 0}
    category_stats[category]["total"] += total
    category_stats[category]["count"] += 1

等级计算：

LEVELS = [
    ("LV1", 0, 50, "青铜成员"),
    ("LV2", 51, 150, "白银成员"),
    ("LV3", 151, 300, "黄金成员"),
    ("LV4", 301, 500, "铂金成员"),
    ("LV5", 501, 800, "钻石成员"),
    ("LV6", 801, 1200, "星耀成员"),
    ("LV7", 1201, 1800, "最强王者"),
    ("LV8", 1801, 2500, "荣耀王者"),
    ("LV9", 2501, 3500, "传奇王者"),
    ("LV10", 3501, 99999, "百星王者"),
]

def calc_level(pts):
    for lv, lo, hi, title in LEVELS:
        if lo <= pts <= hi:
            return lv, title
    return "LV1", "青铜成员"

展示格式

📊 家庭积分统计
━━━━━━━━━━━━━━━━━━
🌐 在线智能表格 · 实时共享
🏠 家庭累计：61 分 | 7 条记录 | 基础52 + 感动9

👤 各成员排名：
  老婆  61分 LV2白银成员 | 7次 | 家务劳动为主

📂 分类排行：
  家务劳动 4次/28分 | 育儿带娃 2次/19分 | 关爱家人 1次/14分

📋 最近记录：
  2026/6/23 老婆 送了佑佑上学 +7分
  ...

增删改后自动统计

每次添加、更新或删除记录后，必须立即按上述统计逻辑计算并展示最新合计数据，让用户确认操作结果和数据一致性。

浏览参考库

直接读取 references/reference_items.json，按类别和 applicable_to 分组展示。

本地模式（fallback）

如果在线文档不可用或用户明确要求本地模式，回退到以下脚本：

# 初始化
python scripts/init_workbook.py <output_path>

# 搜索
python scripts/add_record.py search "<关键词>"

# 添加（参数含成员名）
python scripts/add_record.py add <workbook> <成员> <日期> "<描述>" "<类别>" <基础分> <加分> "<备注>"

# 查询
python scripts/query_stats.py <workbook> [成员过滤]

类别说明

重要提醒

1. 智能表格是共享的：全家人用同一份智能表格，数据实时同步。
2. 首次使用：创建者选「创建」，把链接发给家人；家人选「加入」，粘贴链接。
3. 孩子侧重鼓励：感动分改称鼓励分，关注成长过程。
4. 主动加倍仅成人：孩子不适用主动加倍规则。
5. 日期格式：智能表格中日期为毫秒级时间戳字符串。
6. 总分自动计算：写入/更新时总分 = 基础分 + 感动加分，确保数据一致。
7. 增删改后即时统计：每次操作后立即计算并展示最新合计数据。
8. 在线模式不需要本地脚本：直接通过腾讯文档智能表格 API 读写。