sophhub 0.2.3 → 0.2.4

package/skills/sophnet-schedule/src/IMPROVEMENTS.md

@@ -0,0 +1,145 @@
+# sophnet-schedule 改进记录
+
+## 2026-04-03 改进：提醒注册状态反馈
+
+### 问题描述
+
+之前的实现中，`add_event.py` 和 `import_events.py` 在注册 OpenClaw Cron 提醒任务时，如果失败会静默处理，用户和 Agent 无法知道提醒是否成功注册。
+
+### 改进内容
+
+#### 1. **add_event.py 改进**
+
+**改进前**：
+```python
+def _register_reminder(...) -> None:
+    try:
+        if append_job_if_absent(payload):
+            logger.warning(f"✅ 提醒任务已注册: {name}")
+    except Exception as e:
+        logger.warning(f"注册提醒失败（不影响日历写入）: {e}")
+```
+
+**改进后**：
+```python
+def _register_reminder(...) -> dict:
+    """返回提醒注册状态"""
+    try:
+        if append_job_if_absent(payload):
+            return {"registered": True, "existed": False, "error": None}
+        else:
+            return {"registered": True, "existed": True, "error": None}
+    except Exception as e:
+        return {"registered": False, "existed": False, "error": str(e)}
+```
+
+**返回 JSON 新增字段**：
+- `reminder_registered` (bool): 提醒是否成功注册
+- `reminder_existed` (bool): 提醒是否已存在
+- `reminder_error` (str | null): 提醒注册错误信息
+
+#### 2. **import_events.py 改进**
+
+**改进前**：
+```python
+if remind > 0:
+    try:
+        # ... 注册提醒 ...
+        append_job_if_absent(payload)
+    except Exception:
+        pass   # 静默失败
+```
+
+**改进后**：
+```python
+if remind > 0:
+    try:
+        # ... 注册提醒 ...
+        if append_job_if_absent(payload):
+            reminder_status["registered"] = True
+            reminder_status["existed"] = False
+        else:
+            reminder_status["registered"] = True
+            reminder_status["existed"] = True
+    except Exception as e:
+        reminder_status["error"] = str(e)
+```
+
+**每个事件返回结果新增字段**：
+- `reminder_registered` (bool)
+- `reminder_existed` (bool)
+- `reminder_error` (str | null)
+
+#### 3. **skill.md 文档更新**
+
+- **Step 2**：添加了返回字段说明，包含提醒注册状态字段
+- **Step 3**：更新了回复模板，根据提醒注册状态给出不同反馈
+- **示例对话**：展示了提醒注册失败时的回复方式
+
+### 使用示例
+
+**正常情况（提醒注册成功）**：
+```json
+{
+  "ok": true,
+  "provider": "local",
+  "event_id": "local_xxx",
+  "reminder_registered": true,
+  "reminder_existed": false,
+  "reminder_error": null
+}
+```
+
+**提醒已存在**：
+```json
+{
+  "ok": true,
+  "provider": "local",
+  "event_id": "local_xxx",
+  "reminder_registered": true,
+  "reminder_existed": true,
+  "reminder_error": null
+}
+```
+
+**提醒注册失败**：
+```json
+{
+  "ok": true,
+  "provider": "local",
+  "event_id": "local_xxx",
+  "reminder_registered": false,
+  "reminder_existed": false,
+  "reminder_error": "Permission denied: cannot write to jobs.json"
+}
+```
+
+### Agent 处理逻辑
+
+Agent 在收到返回结果后，应该检查：
+1. `ok` - 日程是否写入成功
+2. `provider` - 写入到 Google Calendar 还是本地存储
+3. `reminder_registered` - 提醒是否注册成功
+4. `reminder_error` - 如果提醒注册失败，显示错误信息
+
+根据这些字段组合回复，让用户了解：
+- 日程是否成功保存
+- 保存到哪个位置（Google Calendar / 本地）
+- 提醒是否成功注册
+- 如果提醒失败，是什么原因
+
+### 测试验证
+
+运行测试：
+```bash
+python3 tests/test_add_event.py
+```
+
+所有测试通过，包括新增的提醒注册状态字段验证。
+
+### 影响范围
+
+- ✅ 向后兼容：新增字段不影响现有功能
+- ✅ 测试覆盖：更新了测试用例
+- ✅ 文档完整：更新了 skill.md
+- ✅ 错误处理：改进了静默失败问题