TongyiDai/employee-care

员工关怀

能做什么

读飞书花名册（生日 + 入职日期），每天检测当天是否有员工过生日或入职周年；命中后为每人写一段结合其部门/岗位的个性化祝福（藏头诗 / 走心小短句），配一张庆祝主图，做成飞书互动卡片，先发给运行者本人预览、确认后再以用户本人账号私聊发给员工。支持定时每日运行、多员工并列处理。内置生产级保障：幂等去重（不重复打扰）、离职过滤、同天生日+周年合并双喜卡、多人同天合并花名卡（一眼看全今天有谁）、运行回执（发了谁/失败/跳过），并在安装时主动询问是否提前提醒直属领导。

花名册文件在首次运行时由 skill 主动搜索用户飞书资产、带链接让用户确认，不需要用户手填 token。主图用豆包/方舟(Ark)生图（默认“一群 3D 小人一起庆祝”的简单主题），无 Key 或生图失败时自动降级为纯文字卡。

流程

Step 0 · 首次配置（安装时主动问清）

第一次用时，先问清三件事再往下走，别用默认值蒙混：

1. 数据源：有没有现成花名册文件？有 → 路径 A；没有或想用飞书人事在职数据 → 路径 B（CoreHR 直连）。
2. 领导提醒：要不要在员工生日/周年前一天顺便私聊提醒其直属领导，让领导也送句祝福？（可选提前天数，默认 1 天；开或不开都行）——见 references/leader-notify.md。
3. 定时：要不要每天自动跑？默认 10:30 Asia/Shanghai，可自选时间。

把这三项选择记下来，作为之后每日循环的配置。

Step 1 · 定位并读取花名册

按 references/data-sources.md，数据源二选一：

• 路径 A · 花名册文件（默认）：lark-cli drive +search 搜用户飞书资产，读表头核对关键字段（必需：姓名 + 至少一个日期列生日/入职日期；可选：部门、岗位、open_id、状态），把带链接 + 字段核对结论给用户确认；用户说“都不是”或候选缺关键字段则请其自行提供。按类型（bitable 用 lark-base、sheet 用 lark-sheets）读取。
• 路径 B · CoreHR 直连：没有花名册文件、或想直接用飞书人事在职数据时，python3 scripts/extract_corehr.py（封装 people-cli 的 CoreHR employees/search，已实测可取到姓名/生日/入职日期/open_id/部门/状态）。需 corehr:employee:read + corehr:person.date_of_birth:read 权限。

优先问用户「有没有现成花名册文件」；有走 A，没有或明确想用人事数据走 B。两条路径都归一化成同一份 people 列表并写临时 JSON：

[{"name":"张三","open_id":"ou_xxx","department":"研发中台","role":"后端工程师","birthday":"1994-08-25","hire_date":"2021-08-25","status":"hired"}]

open_id 预览阶段可为空（路径 A 可用 lark-contact 按姓名+部门反查补齐；路径 B 直接带 open_id），发给员工前必须补齐。

Step 2 · 检测当天命中（含离职过滤、双喜合并）

python3 scripts/match_today.py --roster <tmp.json> --tz Asia/Shanghai

返回 celebrations（一人一条，kind 为 birthday/anniversary/both）、inactive（离职/停用，已过滤不发）、skipped（无可用日期）。脚本已处理：闰年 Feb-29→Feb-28、入职当天不算周年、未知出生年份 age=null、同天生日+周年合并为 both（发一张双喜卡，不发两张）、按 status 列过滤离职/停用（长假不自动过滤，但回显 status 供人工把关）。celebrations 为空则当天无人，安静结束。

Step 3 · 幂等去重

python3 scripts/match_today.py ... | python3 scripts/run_state.py filter --date <today> --source <花名册标识>

过滤掉今天已成功发过的人（防定时重复触发 / 手动+自动重复发）。取返回的 todo 列表继续。

Step 4 · 写个性化祝福

按 references/blessing.md，为 todo 里每个人分别生成（藏头诗默认；或走心小短句），结合部门/岗位意象。both 双喜的人一段话同时点到生日与周年。多人时避免雷同句式。真诚克制，不喊口号、不堆 emoji，直接给成品文案。

Step 5 · 生成主图 + 做卡片 + 预览发送 + 记账

卡片架构已固化在 scripts/build_card.py，每次都用它生成——产出的 Card 2.0 JSON 已按 lark-im 的 P0–P7「好看的标准」设计，精美一致、可渲染，不手写 JSON。--kind 支持 birthday/anniversary/both（双喜卡）。主图默认“一群 3D 小人庆祝”（用户可自选），用 Ark 生图后把 img_key 传给脚本；无 Key/失败则不传，脚本自动降级纯文字卡。细节（生图 prompt、礼物 CTA、发送）见 references/card.md。

python3 scripts/build_card.py --kind birthday --name 张三 --department 研发中台 --role 后端工程师 \
  --date-label "8月25日" --wish $'张灯结彩逢生辰，\n三载耕耘链路深。' \
  [--img-key img_v3_xxx] [--gift-url https://... --gift-text 领取生日礼物]

卡片以用户本人账号发送（默认身份，豆包企业版/飞书自动关联当前用户租户的 CLI 代发；勿写死 bot 或固定 open_id）。发送用 lark-cli im +messages-send，卡片写文件后用 --content "$(cat file)" 传入（--content 不支持 @file；勿用 echo 中转，会损坏 JSON）。先发给运行者本人预览：

python3 scripts/build_card.py --kind birthday --name 张三 ... > /tmp/card.json
lark-cli im +messages-send --user-id <self ou_...> --msg-type interactive --content "$(cat /tmp/card.json)" --dry-run  # 先验证
lark-cli im +messages-send --user-id <self ou_...> --msg-type interactive --content "$(cat /tmp/card.json)"

用户确认后，再逐一发给员工本人的 open_id。每发一人立即记账，成功/失败都记：

python3 scripts/run_state.py mark --date <today> --source <花名册标识> --open-id <ou_...> --status sent --name 张三

多人同天：除每人各自的个性化卡外，用 --roundup 出一张合并花名卡（一眼看全今天有谁、按生日/周年/双喜分标签），默认发给运行者做总览预览；用户同意后也可发到团队群做公开庆祝。

python3 scripts/match_today.py --roster <tmp.json> | python3 scripts/build_card.py --roundup --date-label "8月25日" > /tmp/roundup.json

批量跑完 run_state.py report --date <today> --source <...> 出一份回执（发了谁 / 谁失败 / 原因），连同 inactive、skipped 一并汇报给运营者。详见 references/card.md。

Step 6 · 提前提醒直属领导（按 Step 0 的选择）

若 Step 0 用户选了开启，按 references/leader-notify.md：提前 N 天（默认 1 天）解析将过生日/周年员工的直属领导，私聊提醒领导送祝福。缺 scope/查不到领导则跳过、如实告知，不影响本人祝福卡。Step 0 没问或用户选了不开，则不提醒。

Step 7 · 定时运行（可选）

用户要“每天自动跑”时，按 references/scheduling.md 调用宿主 automation 工具创建每日循环任务（默认 10:30 Asia/Shanghai，用户可自选）并回读确认；宿主无法唤起推理时如实告知需手动触发。

铁律

• 先预览后发送：默认所有祝福卡片先发给运行者本人，用户明确确认后才发给员工。
• 不重复打扰：发送前用 run_state.py filter 去重，同一员工当天不发第二张；每发一人立即 mark 记账。
• 不给离职员工发：按 status 过滤离职/停用；inactive 与无 open_id 的人在预览/回执里显式列出，交人工把关。
• 一人一卡、逐条个性化：不同员工不复用同一段文案；同天生日+周年合并为一张双喜卡。
• 隐私与租户隔离：只读最小必要字段，不落盘员工敏感信息（台账只存 open_id+状态，可弃）；发卡前确认 lark-cli profile 指向正确租户，公司与个人飞书严格隔离。
• 不臆造：读不到日期/open_id 就如实告知，不编造；无生图 Key 或生图失败就降级发纯文字卡，不编 img_key；礼物领取链接由用户提供，没给就不加，不编 URL。
• 认边界：500 人以上、要完全无人值守的大规模场景，建议改用飞书多维表格「定时分批获取记录」自动化，如实告知用户。
• 可移植（开源要求）：面向所有豆包企业版用户与任意 Agent（Codex/Claude Code/Cursor 等）。不写死任何本机特例——不硬编码 open_id / app_id / profile 名 / bot 身份 / 已授权 scope；身份用环境默认（用户本人账号），文件路径、租户、花名册来源都在运行时发现或由用户确认。缺 scope 时按 CLI 提示引导授权，不假设已授权。

资源

• scripts/match_today.py — 当天命中检测：一人一条、both 双喜合并、离职过滤、闰年与年数计算。
• scripts/extract_corehr.py — 用 people-cli 直连 CoreHR 抽取在职员工并归一化（路径 B 数据源）。
• scripts/build_card.py — 固化的精美卡片构造器：产出满足 P0–P7 的 Card 2.0 JSON，支持生日/周年/双喜配色、部门岗位、主图、礼物按钮、批量输出、多人合并花名卡（--roundup）。
• scripts/run_state.py — 幂等去重台账 + 运行汇报（filter/mark/report）。
• references/data-sources.md — 花名册关键字段 schema、搜索飞书资产定位、字段核对确认、读取与归一化。
• references/blessing.md — 藏头诗 / 小短句的写作要求与示例。
• references/card.md — 固化卡片架构说明、build_card.py 用法、生图 prompt、礼物 CTA、发送。
• references/leader-notify.md — （可选）提前提醒直属领导。
• references/scheduling.md — 每日定时运行的开启与循环任务体。