social-app/docs/plans/2026-03-30-agent-calendar-inbox-stability.md

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 静态检查通过，无新增错误。