名称： wpstime-punchclock
描述： 在 WPS Time / NetTime (wpstime.com NetTime) 上自动执行上下班打卡。适用于设置打卡/配置打卡、上班/下班、开始休息/结束休息、开始午餐/结束午餐、查看状态等指令。运行 Playwright 流程，捕获屏幕截图，并回复简要确认信息。

WPS Time / NetTime 自动打卡

运行捆绑的 Playwright 脚本，使用 macOS 钥匙串凭证登录 WPS Time NetTime，执行请求的打卡操作（或状态检查），截取屏幕截图，并报告结果。

输入 → 操作

将用户意图映射到脚本的 --action 参数：

设置 / 凭证

• 设置打卡 / 配置打卡 / 设置时间打卡 → 运行设置流程

打卡操作

• 上班 → clock-in
• 下班 → clock-out
• 开始休息 → start-break
• 结束休息 → end-break (脚本中实现为 Clock In (end break))
• 开始午餐 → start-lunch
• 结束午餐 → end-lunch (脚本中实现为 Clock In (end lunch))
• 状态 / 检查状态 → status

首次设置 (每台机器 / 每个用户)

选项 A (推荐): 本地终端设置 (密码不会进入聊天记录)

运行交互式设置脚本，将凭证存储到 macOS 钥匙串：

cd {baseDir}/scripts
node ./setup.mjs

这会将凭证本地存储在钥匙串服务下：
- wpstime-punchclock.company (secret = 公司/通用 ID)
- wpstime-punchclock (account = 用户名, secret = 密码)

选项 B: 聊天向导设置 (包含密码；风险较高)

仅在用户明确要求基于聊天的设置，并接受密码将出现在聊天历史/日志中时使用。

工作流程：
1) 明确警告：
- 密码将通过聊天发送，并可能被聊天平台和网关日志存储。
- 推荐使用选项 A。
2) 如果他们仍然确认，分步收集 3 个字段：
- companyId
- username
- password
3) 在运行网关的同一台机器上，使用 security add-generic-password -U 存储到 macOS 钥匙串：

security add-generic-password -U -s "wpstime-punchclock.company" -a "company" -w "<companyId>"
security add-generic-password -U -s "wpstime-punchclock" -a "<username>" -w "<password>"

4) 切勿回显密码。存储后，运行 status 以验证登录是否有效。

工作流程

1) 运行打卡脚本 (默认无头模式)：

node {baseDir}/scripts/punchclock.mjs --action <action>

可选标志：
- --headless 0 用于调试
- --outDir <path> 控制截图输出路径

2) 解析 stdout JSON。
- 成功时：读取 performed、screenshotPath，并（可选）从 snippet 中提取关键字段。
- 失败时：报告 error，且不声明打卡成功。

3) 回复请求的频道，包含：
- 一行确认信息 (执行的操作)
- 有效状态/时间 (如果存在，尽力提供)
- 附加 screenshotPath 处的截图

4) 如果用户要求上班/下班，但其可能已处于该状态，建议先运行 status 或在操作后立即运行，以确认并避免重复打卡的混淆。

凭证 (macOS 钥匙串)

请勿将密钥存储在文件或提示中。使用钥匙串。

首选服务 (由 setup.mjs 使用)：
- 服务 wpstime-punchclock.company → secret = 公司/通用 ID
- 服务 wpstime-punchclock → account = 用户名, secret = 密码

向后兼容 (较旧的 OpenClaw 设置)：
- openclaw.wpstime.company
- openclaw.wpstime

如果缺失，打卡脚本将抛出错误。发生这种情况时，引导用户运行：

cd {baseDir}/scripts
node ./setup.mjs

然后重试请求的操作。

参考

如需更详细的操作手册，请阅读：
- references/PUNCHCLOCK_RUNBOOK.md