家庭积分

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

存储模式

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/sheet/<你的文档标识>"
}

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

核心规则

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

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

表格结构（在线模式）

在线表格只有 1 个数据 Sheet，包含以下 9 列：

• 第 1 行：表头（加粗、蓝底、居中）
• 第 2 行：累计合计（公式自动求和）
• 第 3 行起：数据记录

成员区分

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

参考事项库见 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：

   {"title": "家庭积分记录表", "file_type": "sheet"}
   

2. 提取返回的 file_id 和 url
3. 调用 mcp__tencent-docs__sheet.get_sheet_info 获取 sheet_id
4. 写入表头（9 列，含样式）和累计合计行
5. 调用 mcp__tencent-docs__manage.set_privilege 设置 policy=3（所有人可编辑）
6. 写入 config.json：{"online_doc_id": "", "online_sheet_id": "", "online_doc_url": ""}
7. 告知用户：

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

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

选项 2：加入已有表

1. 请用户粘贴文档链接（如 https://docs.qq.com/sheet/DSnF5WEN2bWNBd3Ro）
2. 从 URL 末尾提取 file_id：取 /sheet/ 之后的部分
3. 调用 mcp__tencent-docs__sheet.get_sheet_info，传入提取的 file_id，验证可访问
4. 提取返回的 sheet_id
5. 写入 config.json：{"online_doc_id": "<提取的file_id>", "online_sheet_id": "", "online_doc_url": "<原链接>"}
6. 告知用户：

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

记录积分

步骤 A：确定成员和事项

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

• "老公今天做了一顿饭" → 成员=老公，行为=做饭
• "大宝主动写完了作业" → 成员=大宝，行为=完成作业
• "二宝今天自己收拾了玩具" → 成员=二宝，行为=收拾玩具

步骤 B：搜索参考项

读取 references/reference_items.json：

import json
items = json.load(open('references/reference_items.json', 'r', encoding='utf-8'))

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

• 孩子类成员 → 优先 kids + all
• 成人类成员 → 优先 adults + all

步骤 C：向用户确认

🔍 [成员名] — 匹配到以下参考项：

1. [类别] 事项名称 — 基础X分，感动X~X分 [适用: adult/kid/all]
   事项描述

请选择匹配的编号，或告诉我基础分多少、感动分多少。
也可以直接说"就按第1个，感动+3"。

对于孩子：感动加分改称"鼓励加分"。

步骤 D：写入在线表格

先从 config.json 读取 online_doc_id 和 online_sheet_id。

读取当前所有数据（获取最后一行的序号）：

调用 mcp__tencent-docs__sheet.get_cell_data，参数中用 config.json 的值：

{"file_id": "", "sheet_id": "", "start_row": 2, "start_col": 0, "end_row": 150, "end_col": 0}

找到最后一个有数字序号的行（last_row），新数据写入 last_row + 1。

调用 mcp__tencent-docs__sheet.set_range_value：

{
  "file_id": "",
  "sheet_id": "",
  "values": [
    {"row": , "col": 0, "value_type": "NUMBER", "number_value": },
    {"row": , "col": 1, "value_type": "STRING", "string_value": "<日期>"},
    {"row": , "col": 2, "value_type": "STRING", "string_value": "<成员>"},
    {"row": , "col": 3, "value_type": "STRING", "string_value": "<描述>"},
    {"row": , "col": 4, "value_type": "STRING", "string_value": "<类别>"},
    {"row": , "col": 5, "value_type": "NUMBER", "number_value": <基础分>},
    {"row": , "col": 6, "value_type": "NUMBER", "number_value": <感动加分>},
    {"row": , "col": 7, "value_type": "FORMULA", "formula": "=F+G"},
    {"row": , "col": 8, "value_type": "STRING", "string_value": "<备注>"}
  ]
}

row 是 0-based 索引。Excel 行号 = row + 1。

查询统计

读取全部数据

从 config.json 读取配置，调用 mcp__tencent-docs__sheet.get_cell_data：

{"file_id": "", "sheet_id": "", "start_row": 0, "end_row": 200, "start_col": 0, "end_col": 8}

解析并计算

用 Python 解析返回的 cells 数组，按 row 组织为记录。row >= 2 且 col 0 为数字的为有效记录。

计算逻辑（在 Python 中执行，不依赖 openpyxl）：

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", "青铜成员"

统计项：

• 全家庭 total_points, record_count, unique_days
• 按 member 分组：各人的 total, count, level
• 按 category 分组：次数与总分
• 最近 5 条

展示格式

📊 家庭积分统计
━━━━━━━━━━━━━━━━━━
🌐 在线文档 · 实时共享
🏠 家庭累计：25 分 | 3 条记录 | 1 天

👤 各成员排名：
  老公  13分 LV1青铜 | 1次 | 烹饪美食
  大宝   7分 LV1青铜 | 1次 | 学习成长
  二宝   5分 LV1青铜 | 1次 | 行为习惯

📂 分类排行：
  烹饪美食 1次/13分 | 学习成长 1次/7分 | 行为习惯 1次/5分

📋 最近记录：
  2026/6/23 老公 主动做了一顿饭 +13分
  2026/6/23 大宝 主动完成了所有作业 +7分
  2026/6/23 二宝 自己收拾了玩具 +5分

浏览参考库

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

本地模式（fallback）

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

# 初始化
python scripts/init_workbook.py 

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

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

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

类别说明

重要提醒

1. 在线文档是共享的：全家人用同一份在线表格，数据实时同步。
2. 首次使用：创建者选「创建」，把链接发给家人；家人选「加入」，粘贴链接。
3. 孩子侧重鼓励：感动分改称鼓励分，关注成长过程。
4. 主动加倍仅成人：孩子不适用主动加倍规则。
5. 日期格式：统一 YYYY/MM/DD。
6. 在线模式不需要本地脚本：直接通过腾讯文档 API 读写，Python 只做搜索和统计计算。