# Agent Calendar/Inbox Stability Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** 修复 agent 日历分享失败、对话后日历不刷新、邀请信息不完整，并新增设置页一键清理本地缓存后强制重新拉取。

**Architecture:** 后端补齐 `calendar_share` 依赖注入与邀请 payload 字段，确保工具链与 API 路由行为一致。前端在 Chat 工具结果事件上增加日历刷新钩子，并在设置页提供缓存清理入口，复用既有 prewarm 机制触发重新拉取。协议文档同步更新 inbox 邀请结构，避免前后端契约漂移。

**Tech Stack:** FastAPI + SQLAlchemy + AgentScope tools, Flutter + CachedRepository + SharedPreferences cache.

---

### Task 1: 修复 calendar_share 在 Agent 工具链中的依赖缺失

**Files:**
- Modify: `backend/src/core/agentscope/tools/utils/calendar_domain.py`

**Steps:**
1. 在 `create_schedule_service` 注入 `SQLAlchemyUserRepository`。
2. 保持路由层与工具层对 `ScheduleItemService` 的依赖一致。
3. 回归验证 `calendar_share` 不再因为 actor lookup 依赖缺失而失败。

### Task 2: 扩充 calendar invite payload（邀请人 + 时间 + 描述）

**Files:**
- Modify: `backend/src/v1/schedule_items/service.py`
- Modify: `docs/protocols/models/inbox-messages.md`
- Test: `backend/tests/unit/v1/schedule_items/test_share.py`

**Steps:**
1. 在 `share` 中构建邀请消息时写入 `actor.phone`。
2. 在 `item` 中写入 `description/start_at/end_at/timezone`。
3. 更新协议文档 `CalendarInviteContent`。
4. 补充/更新单测断言新增字段。

### Task 3: 对话工具成功后触发日历缓存刷新钩子

**Files:**
- Modify: `apps/lib/features/chat/presentation/bloc/chat_bloc.dart`
- Modify: `apps/lib/features/chat/presentation/bloc/chat_bloc_events.dart`
- Modify: `apps/lib/app/di/injection.dart`
- Test: `apps/test/features/chat/presentation/bloc/chat_bloc_test.dart`

**Steps:**
1. 给 `ChatBloc` 增加可注入回调 `onCalendarMutated`。
2. 在 `ToolCallResultEvent` 中识别 `calendar_write` 成功/部分成功并触发回调。
3. DI 中将回调绑定为 `CalendarRepository.getDayEvents/getMonthEvents(forceRefresh: true)`。
4. 添加回归测试验证回调触发。

### Task 4: 设置页新增“清理缓存”并触发重新拉取

**Files:**
- Modify: `apps/lib/data/cache/cache_store.dart`
- Modify: `apps/lib/features/settings/presentation/screens/settings_screen.dart`
- Modify: `apps/lib/l10n/app_zh.arb`
- Modify: `apps/lib/l10n/app_en.arb`

**Steps:**
1. 在 `HybridCacheStore` 增加按前缀清理能力（`cache:`）。
2. 设置页在“检查更新”下新增“清理缓存”。
3. 点击后清理缓存并触发 prewarm + inbox 快照刷新。
4. 同步中英文文案并生成本地化代码。

### Task 5: 验证

**Commands:**
- `uv run pytest backend/tests/unit/v1/schedule_items/test_share.py backend/tests/unit/core/agentscope/test_calendar_tools.py -k "share or calendar_share"`
- `flutter test test/features/chat/presentation/bloc/chat_bloc_test.dart`
- `flutter analyze`

**Expected:**
- 后端分享链路测试通过，新增邀请字段存在。
- ChatBloc 回归测试通过，`calendar_write` 成功时触发刷新回调。
- Flutter 静态检查通过，无新增错误。