故障排查手册
先判断问题发生在哪一层：应用启动、权限、文件、任务理解、外部连接、自动化或交付格式。每次只验证一层，避免同时重装、改权限、换文件又改提示词。
收集最小现场#
- WorkBuddy 版本；
- 操作系统版本；
- 当前工作空间路径；
- 任务原文；
- 预期结果与实际结果；
- 完整报错或脱敏截图；
- 涉及的文件格式和大小；
- 是否连接微信、飞书、钉钉或第三方 Skill。
敏感文件不要上传到公开 issue。可用同格式的虚构样例复现。
应用无法安装或启动#
- 确认安装包来自官方网站；
- 核对 Windows / macOS 官方安装指南；
- 检查系统空间和版本；
- 查看安全软件或企业设备策略是否拦截；
- 重启后再次运行；
- 保留安装阶段的完整错误信息。
不要为了启动而关闭所有系统安全机制。若必须调整某项设置，记录改了什么并在验证后恢复。
看不到或无法写入文件#
| 现象 | 可能原因 | 处理 |
|---|---|---|
| 找不到文件 | 工作空间选错 | 核对根目录和文件名 |
| 能读不能写 | 系统权限或只读文件 | 检查目录权限、文件锁定 |
| 输出到了别处 | 任务未指定路径 | 固定 output/ |
| 原件被覆盖 | 输入输出混用 | 从备份恢复，重建隔离目录 |
| 某格式打不开 | 格式或文件损坏 | 用原应用验证，转为兼容副本 |
先用一个纯文本小文件验证读写，再回到复杂 Word、PPT 或表格。
任务卡住或反复确认#
检查是否：
- 任务范围过大；
- 缺少必要文件；
- 要求访问工作空间外路径；
- 需要未授权的系统能力；
- 外部服务登录过期；
- 提示中存在互相冲突的要求。
把任务拆成“材料清点 → 单一产物 → 验收”三段。若某步失败，就只排查该步。
结果不准确#
先区分“事实错误”和“格式不满意”。
事实错误的处理：
- 要求标出每个结论的来源；
- 提供缺失材料；
- 明确禁止猜测；
- 抽查关键数字、日期、姓名；
- 让不确定项写成“待确认”。
格式问题则提供目标模板、字段、篇幅和示例。不要用“更高级一点”这类无法验收的反馈。
连接器或 Skill 失败#
逐项检查：
- 服务账户是否仍登录；
- 授权范围是否满足任务；
- 连接器版本是否兼容；
- 目标资源对当前账号是否可见；
- 网络是否正常；
- 第三方 Skill 是否要求额外依赖或密钥。
先断开其他连接，只保留一个最小连接验证。第三方 Skill 要审查来源、脚本、权限和数据去向。
自动化没有运行#
- 确认自动化已启用；
- 检查触发时间、时区和重复规则；
- 确认运行设备与 WorkBuddy 状态满足要求；
- 检查输入文件是否存在；
- 查看最近执行记录与失败通知；
- 手动运行同一任务。
手动也失败，先修任务；手动成功而定时失败，再查触发条件与运行环境。
微信、飞书或钉钉接入失败#
- 机器人或应用是否被平台启用；
- 回调、令牌和权限是否按官方步骤配置；
- 发起人是否在允许范围；
- 群聊与私聊权限是否不同；
- 消息是否超过格式或大小限制；
- 令牌是否被撤销或过期。
不要在聊天截图中暴露密钥。必要时撤销旧凭证后重新生成。
文件做出来但不能用#
交付验收至少检查：
- 文件能打开；
- 文件名和输出位置正确；
- 字体、图片和表格未丢失；
- 数据列与公式仍正确；
- 关键信息能追溯原文；
- 没有多余临时文件；
- 原始材料未改变。
“任务显示完成”不等于交付通过。
提交反馈#
官方提供反馈入口说明。提交时使用最小复现、版本、系统、任务步骤和脱敏错误，能显著提高定位效率。