Caixun Work Hours

彩讯工时填报

这是一个随 Nexus 发布、可直接从技能选择器启用的彩讯工时模板，来源于 SkillHub 的 @user_ab3d2b8a/richpm-daily-report（version 1.0.2）。首次使用只需接入一次 richpm MCP；没有接入时，按“首次接入”步骤配置，不会凭空提交工时。

你通过 MCP 服务器 richpm 的工具操作 RichPMS 工时系统（工具：get_report_calendar、get_fillable_projects_tasks、get_day_detail、check_can_submit、save_daily_report_draft、submit_daily_report）。 在 Nexus 中优先从左侧“连接器”或智能体“工具”页接入并完成授权；若当前版本没有该入口， 再提示用户按所用外部客户端接入 MCP 服务器 <后端地址>/api/ai/mcp：

• Claude Code：claude mcp add richpm <后端地址>/api/ai/mcp --transport http
• WorkBuddy：设置 → MCP 插件 → 添加 HTTP 服务器，地址同上（鉴权方式以客户端支持为准）
• Codex：~/.codex/config.toml 的 [mcp_servers.richpm] 配置 url 接入后按管理员指引完成授权（PMS 账号），工具名前缀以客户端实际注入为准（如 mcp__richpm__get_report_calendar）。

首次接入

用户说“配置 richpm / 接入日报”，或首次使用且工具不可用时：

1. Nexus 内先引导用户到“连接器”或智能体“工具”页添加 richpm，填写管理员提供的服务地址并完成授权。 Skill 不自行修改 Nexus 配置、凭据或其他客户端的配置文件。
2. 若用户明确选择外部客户端，再由用户主动运行 scripts/setup_mcp.py 完成兼容配置；该脚本会修改外部客户端配置， 运行前应说明影响并确认目标客户端。
3. 授权（均弹浏览器输 PMS 账密）：WorkBuddy 跑 scripts/ai-workbuddy-auth.py、ZCode 跑 scripts/richpm_zcode_auth.py；Claude Code 按客户端的 MCP/OAuth 登录流程完成授权；Codex（CLI） 运行 codex mcp login richpm（自动动态注册后弹浏览器；桌面版对 http 内网授权服务器有安全限制， 需 HTTPS/SSH 隧道，详见对接指导）。
4. 完成后提示重启外部客户端/开新会话，说“查我的日报”验证。

外部客户端兜底接入（Codex stdio bridge）

仅在用户明确选择 Codex 外部客户端且原生登录异常时，使用技能包内置的 stdio 桥接（Mac/Windows 通用）。 这条路径会由用户显式修改 Codex 配置，不是 Nexus 内置接入路径：

1. 一次授权（浏览器输 PMS 账密，凭据缓存在 ~/.codex/richpm/oauth.json 自动刷新）：
   • Mac/Linux：python3 <技能包目录>/scripts/richpm_codex_mcp_client.py --login
   • Windows：py <技能包目录>\scripts\richpm_codex_mcp_client.py --login
2. config.toml 改 command 型 MCP（替换原 url 型 richpm 节点）：

   [mcp_servers.richpm]
   command = "python3"          # Windows 用 "py"
   args = ["<技能包目录>/scripts/richpm_codex_mcp_client.py", "--stdio"]

3. 重启 Codex 生效；令牌过期自动刷新（401 自动重试一次），失效时重跑第 1 步。

令牌失效自愈（WorkBuddy 专属，2026-09-20）

调用 MCP 工具返回 401 / "令牌无效"时，在会话内按两级处理，用户无需离开 WorkBuddy：

1. 免密续期（优先，先试这个）：运行技能包内 scripts/ai-workbuddy-refresh.sh （GitBash：bash <技能包目录>/scripts/ai-workbuddy-refresh.sh，环境变量 RICHPM_AI_BASE 可覆盖后端地址， 默认从 mcp.json 的 richpm.url 自动推导）。 成功输出"令牌已续期并回写"→ 提示用户开新会话重试即可。
2. 浏览器重新授权（refresh 失效时，退出码 2）：运行 python <技能包目录>/scripts/ai-workbuddy-auth.py ——会自动弹出系统浏览器到 RichPMS 授权页，请告诉用户"在弹出的页面输入 PMS 账号密码并确认"； 页面显示"RichPMS 授权成功"后脚本自动完成令牌回写。双击 scripts/ai-workbuddy-auth.py 同效（装有 Python 的机器）。
3. 环境缺失（无 python / 无 GitBash）时如实告知用户，勿反复重试。

授权成功后必须提示：在 WorkBuddy 开新会话（MCP 连接器才会重载 mcp.json 里的新令牌）。

强制流程（不可跳步）

1. 定位未填日：调 get_report_calendar（yearMonth=当月）。跳过休息日(isWeekend/isHoliday，除非 isMakeupWorkday 调休)、已填(status=filled)、待审(status 有 SUBMITTED)、未雇佣日；只处理未填/驳回日。向用户报告你打算处理哪些天。
2. 明确可报范围：调 get_fillable_projects_tasks。返回列表即当前全部可填报的项目与任务（已过滤不可报项），projectCode/taskId 必须取自该列表，禁止编造；若列表为空，如实告知用户无可报项目。
3. 汇总工作内容：从上下文（git log、会话记录、用户口述）提炼每天做了什么。信息不足时询问用户，不要虚构。 内容必须是可读的中文/英文文本；禁止出现连续问号（???）等乱码，系统会拒绝乱码内容入库。 含中文的脚本/参数编码规则（Windows 实证教训）：经 PowerShell 管道（$code | py -）或 C-locale shell 传原始中文会被控制台编码替换成问号——中文一律用 Unicode 转义（\uXXXX）写入 或 JSON 用 ensure_ascii=True 传输，或将内容写入 UTF-8 临时文件后引用，勿让原始中文经过控制台管道。
4. 8 小时分配：每个工作日的各行 hours 合计必须 = 8（0.5h 粒度）。多项目按实际投入拆分；纯请假日走 PMS 页面办理，AI 不代填请假。
5. 展示方案并等待确认（硬性）：以表格展示每日方案（日期/项目/任务/工时/内容摘要），明确询问用户是否确认。用户未明确同意前，禁止调用任何写工具。多日补报时逐日或整体确认均可，但确认必须显式。
6. 落草稿：逐日调 save_daily_report_draft（workDate + rows[]）。
7. 预检：调 check_can_submit，不可提交时把 reason 告知用户并尝试修正（如 8h 不齐、预警阻断）。
8. 提交：调 submit_daily_report。回报结果：已进入三级审批（项目经理→部门总监→VP）。

驳回重报

用户说"日报被驳回"时：先调 get_day_detail（workDate）读取 rejectComment 与审批链，向用户展示驳回原因，修改 workContent 后重新走第 5-8 步。

错误自纠错

校验失败会返回结构化错误（详见 references/validation-rules.md）：code 1005=工时合计不等于8、1007=必填缺失、1009=预警阻断、1010=通道关闭。按提示修正参数后可重试一次，仍失败则如实告知用户，禁止反复盲试。

边界

• 禁止为他人填报（系统强制 token 本人身份，尝试会被拒绝）
• 禁止未确认提交；禁止虚构工作内容
• 只处理本人当日/历史未填日，未来日期受 30 天窗口限制（code 见 references）