# 故障排除指南

## 常见问题

### 如何查看生成的报告？

报告保存在 `{data_dir}/` 对应子目录下：
- 周报：`weekly/`
- 月报：`monthly/`
- 季报：`quarterly/`
- 年报：`yearly/`

也可以直接告诉 Agent "显示本周周报"，Agent 会读取文件后直接展示内容。

### 可以修改已记录的工作日志吗？

可以，直接告诉 Agent：`"修改3月3日的工作日志，把开发时间改为4小时"` —— Agent 会找到对应日期的 JSON 文件并修改。

### 为什么第1周包含前一年的日期？

ISO 8601 标准规定第1周为包含1月4日的那一周，可能从前一年12月底开始。

### 智能解析会出错吗？

Agent 基于语义理解，准确率很高。如果遇到歧义，Agent 会通过交互式确认让用户验证，避免错误。

### 需要安装任何工具或脚本吗？

不需要。本技能完全由 Agent 直接读写 JSON 文件实现，无需安装任何 Python 环境或依赖，跨平台开箱即用。

---

## 数据问题

### 工作日志文件不存在

Agent 在记录日志时会自动创建 `{data_dir}/daily/` 目录和对应的 JSON 文件。如果目录不存在，Agent 应自动创建。

### 月报/季报/年报生成时缺少下级数据

| 场景 | 处理方式 |
|------|---------|
| 月报缺少某天日志 | 跳过缺失天数，按已有数据统计 |
| 月报缺少周报 | 直接从日志汇总，不依赖周报 |
| 季报缺少月报 | 从月内日志直接汇总 |
| 年报缺少季报 | 从全年日志直接汇总 |

### 跨季度/跨年度的数据归属

- 工作日志按 `date` 字段归属到对应周/月/季
- 如果某天的工作横跨多个 OKR，通过 `okr_id` 分别记录
- 季度 OKR 在季度结束后自动标记为 `completed` 或 `archived`

### JSON 文件损坏

1. 检查文件是否为合法 JSON（每行一个 JSON 对象，或整体一个 JSON 对象）
2. 如果文件损坏，从最近的备份恢复（如有）
3. Agent 应在写入前验证 JSON 格式，避免损坏

---

## 升级相关

### 从 Python 版本迁移数据

旧版（Python 脚本版）的数据文件格式与新版兼容，可直接使用。主要差异：

| 项目 | 旧版 | 新版 |
|------|------|------|
| 数据目录 | `~/.okr-work-manager/` | `{workspace}/.okr-work-manager/` |
| 日志格式 | 同 | 同 |
| 计划格式 | 同 | 同 |
| 报告生成 | Python 脚本 | Agent 直接生成 |

迁移步骤：
1. 将旧版 `.okr-work-manager/` 目录复制到 `{workspace}/` 下
2. 删除 Python 脚本和配置模板（`scripts/`、`config/`、`assets/`）
3. 保留 `daily/`、`plans/`、`weekly/`、`monthly/`、`quarterly/`、`yearly/` 目录及 JSON 文件
4. 保留 `okr_config.json` 和 `okr_progress.json`（如有）

---

## 快速检查清单

- [ ] 数据目录存在且可写？
- [ ] `okr_config.json` 格式正确？
- [ ] 当日日志文件存在？
- [ ] Agent 能正常读取 JSON 文件？