kids-points-v2 - 积分助手 V2 📊

简单、可靠的儿童积分管理工具。V2 相比 1.x 版本做了全面重构：记账稳定性、CLI 对接能力、轻量化都大幅提升。

✨ V2 核心特性

🎯 使用方式

直接给飞书 bot 发自然语言就行：

今天完成了汉字抄写 2 课，口算题卡 2 篇全对
积分消费 买零食花了 20 分
现在多少分？
今日积分

Bot 会自动识别语意 + 记账 + 回报结果。

🛠️ CLI 接口

# 走完整 8 步 pipeline（LLM 识别 + 记账 + 返 reply）
python3 runtime/cli.py "今天数学加 1 分"

# 查余额（不走 LLM）
python3 runtime/cli.py balance

# 今日积分
python3 runtime/cli.py today

# 历史记录
python3 runtime/cli.py history

退出码：0 成功 / 1 数据库错误 / 2 参数错误。

📁 项目结构

kids-points-v2/
├── runtime/                  # V2 Python runtime（核心逻辑）
│   ├── cli.py                # CLI 入口
│   ├── db.py                 # SQLite 操作层
│   ├── pipeline.py           # 8 步处理 pipeline
│   ├── llm_config.py         # LLM 配置单入口
│   ├── config.yaml.example   # 配置模板（复制为 config.yaml 使用）
│   └── data/                 # SQLite 账本位置
├── skill/                    # OpenClaw skill 包装层
│   ├── SKILL.md
│   ├── agent-handler.js      # OpenClaw dispatch 入口
│   ├── build.sh              # ClawHub 发布打包
│   └── scripts/
│       └── handle_feishu.py  # V2 skill handler
├── extensions/               # 扩展项目（点阵屏看板等）
├── docs/                     # 内部文档
├── README.md
├── LICENSE
└── .gitignore

🔌 依赖

• Python 3.8+
• OpenClaw（消息分发）
• LLM API（OpenAI Chat Completions 兼容协议）

🚀 安装与配置

配置 LLM

复制示例配置并填入你的信息：

cp runtime/config.yaml.example runtime/config.yaml
# 编辑 config.yaml，填入 api_url / model / key_source

key_source 推荐用环境变量引用，例如 env:OPENAI_API_KEY，然后把 key 放到 shell 环境变量里。

自定义 runtime 路径（高级）

如果你想用其他位置的 runtime，设环境变量：

export KIDS_POINTS_RUNTIME_DIR=/path/to/your/kids-points-runtime

优先级：KIDS_POINTS_RUNTIME_DIR env > 项目根内嵌 runtime/ 默认值。

⚠️ 已知行为

📦 分支说明

开发者：日常在 dev 分支 work，定期 merge 到 main 后 push。

📦 配套项目

• 桌面积分版（点阵屏硬件展示）：在 extensions/ 目录

用心记录每一次进步。 🌟

🌐 English Summary

Kids Points V2 is a lightweight, reliable family-points tracker that lives in your Feishu (Lark) chat. Send a natural-language sentence — "completed 2 Chinese copybook pages, got all math flashcards right" — and the bot extracts intent, writes to a SQLite ledger, and replies with the result.

Why V2 (vs. the 1.x line)

• SQLite storage replaces plain-text ledgers: concurrent writes and power-loss no longer corrupt the book.
• LLM-based intent parsing via llm_config.py adapts to colloquial Chinese, regional phrasing, and each family's wording, instead of brittle regexes.
• CLI-first: runtime/cli.py exposes balance / today / history and the full pipeline, so agents, cron jobs, and shell scripts can drive the ledger without going through OpenClaw.
• Feishu full coverage: group chats and direct messages — V1 was DMs only.
• Deduplication by messageId: idempotent under retries and replays.
• Lighter footprint: ASR/TTS is delegated to Feishu itself, so the skill no longer ships an embedded voice pipeline.

Install (3 steps)

cp runtime/config.yaml.example runtime/config.yaml   # then fill in api_url / model / key_source
clawhub install kids-points-v2
# Configure your OpenClaw dispatch to route Feishu messages to the skill handler

CLI quick reference

python3 runtime/cli.py "added 1 point for math today"   # full pipeline
python3 runtime/cli.py balance                          # current balance (no LLM)
python3 runtime/cli.py today                            # today's earnings
python3 runtime/cli.py history                          # recent ledger entries

Exit codes: 0 success / 1 database error / 2 argument error.

Requirements: Python 3.8+, OpenClaw for Feishu dispatch, any LLM API speaking the OpenAI Chat Completions protocol.

See README.en.md in the repository for the full English README, including the optional HUB75 LED-matrix dashboard extension under extensions/.