打工人小账本 · 云端记账
用户随口说一句「午餐 25」「XX 项目 8 小时」，就用这个技能落到云端账本里。
数据面和网页版小账本、桌面端连接器是同一份，写完哪边都能看到，无需导入导出。
怎么跑
所有操作都通过一个零依赖的 Python 脚本完成（只用标准库）。
先切到本技能所在目录，再执行：
python3 scripts/ledger.py <子命令> [参数...]
python3 不存在时改用 python。网络是必须的（要连云端数据面）。
第一次用：先登录
先看状态：
python3 scripts/ledger.py status
如果是「❌ 未登录」，去问用户要小账本的邮箱和密码，然后：
python3 scripts/ledger.py login --email <邮箱> --password '<密码>'
登录成功后凭据保存在本机 ~/.worker-ledger/config.json（权限 600），
之后所有命令都会自动静默登录，不用再问。令牌过期（约 2 小时）时脚本会
拿本地凭据重新登录换新令牌，用户无感 —— 注意它不会去调平台的续期端点
（那个端点一旦调用不当会把连接器会话一起作废，所以刻意避开）。
> 用户不想给密码时，可以走验证码：login --email <邮箱>（不带 --password）会发验证码，
> 拿到用户给的 6 位码后执行 verify --code <验证码>。
> ⚠️ 不要把密码写进普通文本回复里，用完也别复述。
关于密码落盘（请如实告知用户）：为了让之后每次记账都不用重新登录，密码会以明文
保存在 ~/.worker-ledger/config.json（文件权限 600，只有当前用户可读），
并且只会被发往本应用自己的登录接口，不会发到任何第三方地址。
用户若不愿意，可以：把该文件里的 password 字段删掉（之后只保留邮箱，
每次用验证码登录），或者干脆只用手机浏览器打开网页版小账本。
工时（这个账本的主线）
「工时产生」= 收，「工时填报」= 支，两者分开记，余额 = 产生 − 填报。
# 记工时产生（干了活）
python3 scripts/ledger.py work add --project "XX集团供应链咨询" --hours 8
# 记工时填报（把工时报给项目）
python3 scripts/ledger.py work report --project "XX集团供应链咨询" --hours 6
# 工时看板：累计产生/填报/待填报 + 分项目明细（带唯一编码）
python3 scripts/ledger.py work board
# 工时明细（项目名后带编码）
python3 scripts/ledger.py work list --kind generated|reported [--project X|PRJ-001] [--limit 20]
# 删错的一条工时（ID 从 board/list 里取）
python3 scripts/ledger.py work del --kind generated|reported --id <client_id>
硬规则：填报不得超过该项目「已产生 − 已填报」的余额。脚本会自己拦下来并报错，
这时不要硬填，改成正确的项目名或先补记「工时产生」。
日期参数 --date 支持 今天（默认）昨天 前天 3天前 8月5日 2026-08-05。
项目与唯一编码
每个项目有一个唯一编码（PRJ-001 起，按最大号 +1），三端（网页版 / 桌面连接器 /
本技能）共用同一份项目表。用户不需要手工建项目：
work add/report里写一个新名字 → 自动建项目并分配编码，输出会提示「🆕 新建项目：X → 编码 PRJ-00N」- 写已有项目的名字（大小写、前后空格不敏感）→ 复用同一个项目，不重复建
- 也可以直接用编码当项目名，例如
--project PRJ-002，会自动换成正式项目名
# 项目清单（编码 / 名字 / ID）
python3 scripts/ledger.py projects list
# 改名（编码不变，同时把该项目的工时记录一起改名，不会留下孤儿记录）
python3 scripts/ledger.py projects rename --code PRJ-002 --new-name "Cxx 二期"
# 删项目（项目下还有工时记录时会拒绝，得先删工时）
python3 scripts/ledger.py projects delete --code PRJ-003
> 反过来说：不要为了「换个名字」新建一个项目 —— 那会多出一个编码，
> 历史工时还挂在旧项目上。要改名就用 projects rename。
收支
# 记一笔（type 省略就是支出；分类会按备注自动推断，也可 --category 指定）
python3 scripts/ledger.py add --amount 25 --note "午餐 黄焖鸡"
python3 scripts/ledger.py add --amount 12000 --note "工资到账" --type income
# 查
python3 scripts/ledger.py list --month 2026-10
python3 scripts/ledger.py list --keyword 外卖 --limit 10
python3 scripts/ledger.py list --from 昨天 --to 今天
# 月度小结：月到手收入 / 固定支出 / 弹性支出 / 本月结余 / 分类占比 / 自由基金安全垫
# （字段与排版和桌面端连接器的「月度总结」一致，另附一行折算工时）
python3 scripts/ledger.py summary
# 删
python3 scripts/ledger.py del --id <client_id>
分类只有 8 种：food 餐饮 / transport 交通 / shopping 购物 / fun 娱乐 /
home 居住 / health 医疗 / edu 教育 / other 其他。
时薪 / 薪资 / 自由基金
python3 scripts/ledger.py rate # 看真实时薪（会自动拆解公式）
python3 scripts/ledger.py salary --monthly 15000 --months 13 --cost 600 \
--workdays 22 --onsite 9 --commute 2 --overtime 1.5
python3 scripts/ledger.py fund --current 100000 --target 200000 --snapshot
python3 scripts/ledger.py fixed list
python3 scripts/ledger.py fixed add --name "房租" --amount 3500
python3 scripts/ledger.py fixed del --id <client_id>
真实时薪口径（与网页版同一套公式，不要另算）：
真实时薪 = (月到手 × 发薪月数 − 月工作成本 × 12)
───────────────────────────────────────────
(在岗 + 通勤 + 加班) × 月工作天数 × 12
汇报风格
脚本输出已经是给人看的表格，直接转述要点即可，不要贴原始 JSON。
记账成功后回一句确认（金额、分类、日期）。用户问「这个月花了多少」时，
用 summary 的结果回答，并可以把金额折算成工时（脚本已经算好了）。
出问题怎么办
| 现象 | 原因与处理 |
|---|---|
网络请求失败 |
环境访问不了 worker-ledger-55418.app.workbuddy.host。云端沙箱若禁网则本技能无法工作，老实告诉用户改用手机浏览器打开网页版小账本 |
python3: command not found |
换 python 试；都没有就说明沙箱没装 Python |
需要登录 / invalid_grant |
会话失效且本地没有可自动登录的凭据 → 重新走 login |
邮箱或密码不正确 |
真的错了；别反复重试，去问用户核对 |
填报超出余额 |
这是保护，不是 bug。先确认项目名，或补记工时产生 |
已经有项目叫「X（PRJ-00N）」了 |
projects rename 改成重名会被拦。换一个名字，或确认用户其实想复用那个已有项目 |
项目「X」下还有 N 条工时记录 |
删项目的保护。先用 work del 删掉工时，再删项目 |
权限不足 / 42501 |
登录态失效，重新登录后再试 |
| 连通正常但数据全是 0 | 技能包是独立登录的。确认 login 用的邮箱和网页版/桌面连接器完全一致；换了个邮箱就是另一个账号，数据互不可见 |
| 命令没输出、退出码 1 | 错误写在 stderr（例如 操作失败：…），按第一行判断即可；成功结果才走 stdout |
不要自己拼 HTTP 请求去调云端接口 —— 必须走 scripts/ledger.py，
否则很容易漏掉 Origin 头（平台据此校验来源，缺了会被判成「issued for another client」
而登录失败），或与网页版的业务口径产生偏差。
数据表结构与字段说明见 references/data-model.md。
