RichPMS 日报填报
你通过 MCP 服务器 richpm 的工具操作 RichPMS 工时系统（工具：get_report_calendar、get_fillable_projects_tasks、get_day_detail、check_can_submit、save_daily_report_draft、submit_daily_report）。
若工具不可用，提示用户按所用客户端接入 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）。
首次接入（装包即用，2026-09-20 起）
用户说"配置 richpm / 接入日报"，或首次使用且工具不可用时，先跑一键配置再授权：
- 运行
python <技能包目录>/scripts/setup_mcp.py——自动检测本机已装的 AI 客户端
（WorkBuddy / Codex / Claude Code / ZCode / Cursor）并保守写入 richpm MCP 节点（不动其他配置；
已存在则校验 url，地址不符自动修正，令牌等其余配置保留）。
按脚本输出的[配置结果]与[下一步]继续。 - 未检测到任何客户端：如实告知，引导先安装任一支持的 AI 工具。
- 授权（均弹浏览器输 PMS 账密）：WorkBuddy 跑
scripts/ai-workbuddy-auth.py、ZCode 跑
scripts/richpm_zcode_auth.py、Claude Code 跑scripts/ai-login.sh；
Codex（CLI）运行codex mcp login richpm（自动动态注册后弹浏览器；桌面版对 http 内网授权服务器
有安全限制，需 HTTPS/SSH 隧道，详见对接指导）。 - 完成后提示重启客户端/开新会话，说"查我的日报"验证。
Codex 桌面版 / 兜底接入（stdio bridge，2026-09-21 起）
Codex CLI 优先用 codex mcp login richpm 原生 OAuth（零配置）。桌面版（对 http 内网授权服务器有安全基线限制）或原生登录异常时，用技能包内置的 stdio 桥接（绕开 HTTP 发现链，Mac/Windows 通用）：
- 一次授权（浏览器输 PMS 账密，凭据缓存在
~/.codex/richpm/oauth.json自动刷新）：
- Mac/Linux：python3 <技能包目录>/scripts/richpm_codex_mcp_client.py --login
- Windows：py <技能包目录>\scripts\richpm_codex_mcp_client.py --login - config.toml 改 command 型 MCP（替换原 url 型 richpm 节点）：
toml [mcp_servers.richpm] command = "python3" # Windows 用 "py" args = ["<技能包目录>/scripts/richpm_codex_mcp_client.py", "--stdio"] - 重启 Codex 生效；令牌过期自动刷新（401 自动重试一次），失效时重跑第 1 步。
令牌失效自愈（WorkBuddy 专属，2026-09-20）
调用 MCP 工具返回 401 / "令牌无效"时，在会话内按两级处理，用户无需离开 WorkBuddy：
- 免密续期（优先，先试这个）：运行技能包内
scripts/ai-workbuddy-refresh.sh
（GitBash：bash <技能包目录>/scripts/ai-workbuddy-refresh.sh，环境变量RICHPM_AI_BASE可覆盖后端地址，
默认从 mcp.json 的 richpm.url 自动推导）。
成功输出"令牌已续期并回写"→ 提示用户开新会话重试即可。 - 浏览器重新授权（refresh 失效时，退出码 2）：运行
python <技能包目录>/scripts/ai-workbuddy-auth.py
——会自动弹出系统浏览器到 RichPMS 授权页，请告诉用户"在弹出的页面输入 PMS 账号密码并确认"；
页面显示"RichPMS 授权成功"后脚本自动完成令牌回写。双击scripts/ai-workbuddy-auth.py同效（装有 Python 的机器）；内部完整包另附richpm-auth.bat供无 Python 环境双击。 - 环境缺失（无 python / 无 GitBash）时如实告知用户，勿反复重试。
授权成功后必须提示：在 WorkBuddy 开新会话（MCP 连接器才会重载 mcp.json 里的新令牌）。
强制流程（不可跳步）
- 定位未填日：调
get_report_calendar（yearMonth=当月）。跳过休息日(isWeekend/isHoliday，除非 isMakeupWorkday 调休)、已填(status=filled)、待审(status 有 SUBMITTED)、未雇佣日；只处理未填/驳回日。向用户报告你打算处理哪些天。 - 明确可报范围：调
get_fillable_projects_tasks。返回列表即当前全部可填报的项目与任务（已过滤不可报项），projectCode/taskId 必须取自该列表，禁止编造；若列表为空，如实告知用户无可报项目。 - 汇总工作内容：从上下文（git log、会话记录、用户口述）提炼每天做了什么。信息不足时询问用户，不要虚构。
内容必须是可读的中文/英文文本；禁止出现连续问号（???）等乱码，系统会拒绝乱码内容入库。
含中文的脚本/参数编码规则（Windows 实证教训）：经 PowerShell 管道（$code | py -）或
C-locale shell 传原始中文会被控制台编码替换成问号——中文一律用 Unicode 转义（\uXXXX）写入
或 JSON 用ensure_ascii=True传输，或将内容写入 UTF-8 临时文件后引用，勿让原始中文经过控制台管道。 - 8 小时分配：每个工作日的各行 hours 合计必须 = 8（0.5h 粒度）。多项目按实际投入拆分；纯请假日走 PMS 页面办理，AI 不代填请假。
- 展示方案并等待确认（硬性）：以表格展示每日方案（日期/项目/任务/工时/内容摘要），明确询问用户是否确认。用户未明确同意前，禁止调用任何写工具。多日补报时逐日或整体确认均可，但确认必须显式。
- 落草稿：逐日调
save_daily_report_draft（workDate + rows[]）。 - 预检：调
check_can_submit，不可提交时把 reason 告知用户并尝试修正（如 8h 不齐、预警阻断）。 - 提交：调
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）
