wecom-cleaner-agent

name	wecom-cleaner-agent
description	用于执行和编排 wecom-cleaner 的无交互 Agent 技能。当任务涉及企业微信缓存盘点、年月清理、全量空间治理、批次恢复、回收区治理、系统自检、检查更新或程序升级，并要求高效执行与结构化反馈时触发。

wecom-cleaner-agent

目标

• 用最少命令完成目标动作。
• 默认安全（先预演，再按授权执行真实动作）。
• 输出“用户可读任务卡片”，避免技术键值堆砌。

强制规则

1. 全程只用无交互命令（禁止直接运行 wecom-cleaner 进入 TUI）。
2. v2 主控制面优先使用新 CLI 子命令；现有脚本入口属于兼容壳层，优先用于报告呈现。
3. 破坏性动作（清理/治理/恢复/回收区治理）默认预演；真实执行必须有明确授权。
4. 回退到 CLI 时，优先使用公共 v2 子命令；只读动作走 inspect ...，破坏性动作走 plan ... -> apply ... -> verify ... 或对应确认子命令，禁止混用旧顶层旗标。
5. 升级动作默认只做检查或预演（--execute false）；真实升级必须有明确授权。
6. 若预演命中为 0，必须结束并说明“无需执行”，不得继续真实执行。
7. 最终汇报必须是中文用户视角，先结论再细节，并解释关键指标含义。
8. 禁止在终端回显完整 JSON；只输出人类可读摘要。

动作到脚本映射（必须）

• 年月清理：scripts/cleanup_monthly_report.sh
• 会话分析（只读）：scripts/analysis_report.sh
• 全量空间治理：scripts/space_governance_report.sh
• 恢复已删除批次：scripts/restore_batch_report.sh
• 回收区治理：scripts/recycle_maintain_report.sh
• 系统自检：scripts/doctor_report.sh
• 检查更新：scripts/check_update_report.sh
• 程序升级：scripts/upgrade_report.sh
• skills 同步：回退到 wecom-cleaner skills sync --ack SKILLS_SYNC --output agent-json

调用顺序：

1. 先判断用户意图对应哪个动作。
2. 直接调用对应脚本。
3. 脚本失败时，才回退到 v2 子命令（如 wecom-cleaner inspect ... / plan ... / recover ... / update ... / skills ...）手工流程。
4. 回退流程里优先读取 data.taskCard 与 data.taskPhases，再读取 summary/data.report 细节。

脚本调用约定

• 默认 --execute false（仅预演 / 不落地）。
• 用户明确“现在执行/开始清理/确认执行”时才传 --execute true。
• 破坏性动作脚本内部会做：预演 ->（可选）真实执行 ->（可选）复核。
• 升级脚本默认“检查 + 预演”；只有明确授权才执行真实升级。
• CLI 回退时：
  • 只读动作：wecom-cleaner inspect ... --output agent-json
  • 年月清理/全量治理：先 wecom-cleaner plan ... --output agent-json，再按授权执行 wecom-cleaner apply <plan-id> --ack APPLY
  • 恢复/回收区/服务/升级/skills：直接走各自的确认入口（如 recover ... --ack ...、update apply ... --ack UPGRADE、skills sync --ack SKILLS_SYNC）

推荐参数：

• --root <path>：显式指定 Profile 根目录（在多环境时强烈建议）。
• --state-root <path>：显式指定状态目录（便于审计与回放）。
• --accounts all|current|id1,id2：明确账号范围。
• --external-roots-source all：优先纳入自动探测目录，避免漏扫用户自定义文件存储位置。

最终汇报规范（对用户）

每次都要给“任务卡片”风格输出，至少包含：

1. 结果结论：是否完成、是否真实执行、是否无需执行。
2. 用户范围：账号范围、数据范围（月份/类别/批次/策略）。
3. 关键统计：命中数量、预计/实际释放（或恢复）空间、成功/跳过/失败、批次号。
4. 分布明细：按类别、按月份、按路径（Top 路径样例）。
5. 安全状态：引擎、耗时、告警数、错误数。
6. 指标释义：解释“命中目标、预计释放、批次号、复核剩余”等含义。

异常处理

• 参数错误（退出码 2）：说明缺失参数并给出可执行示例。
• 缺少确认（退出码 3）：提示需加 --execute true（脚本）或对应确认参数（如 --ack APPLY / --ack RESTORE / --ack UPGRADE）。
• 业务失败（退出码 1）：提取 errors.code/message，给出下一步排查建议。
• 若发现 warnings 或 errors 非空，结论里必须明确标注。

参考资料

• 命令参考：references/commands.md
• 脚本目录：scripts/