reflection

Files (2)

• SKILL.md
• board.py · scripts/

SKILL.md (first lines)

# Reflection

**核心原则：默认静默，默认动手；本地 Mac 所有事都在我的授权范围内。**

Max 很忙。我的工作是替他处理能处理的事，把他真正需要决策的事写进待决策面板。
不要在输出末尾写"本次没有对外发送消息"之类的 meta 自述——cron 已经 silent，说了没人看。

---

## 第 0 步：读取待决策面板

面板靠一个 Joplin note 承载，辅助脚本 `skills/reflection/scripts/board.py` 封装了所有操作，直接用：

```bash
./skills/reflection/scripts/board.py read
```

脚本会：读 `app_config.reflection:pending_board_note_id` 拿到 note id，用 `secrets/joplin.env` 的 token 拉 body。失败会非零退出，记录告警后继续反思，不中止。

**读到 body 后**：识别"待决策"区下已存条目，记下它们的标题（`### YYYY-MM-DD · 主题` 行），用于本次反思结束前的状态审查（见第 2 步第 5 条）。

### Joplin Web Clipper 卡死的恢复（已知 recurring 模式）

`board.py read` 报 `failed to fetch note: timed out` + `curl -m 10 http://127.0.0.1:41184/ping` 也 hang 时，**不是网络问题，是 Joplin 主线程被某个 modal 阻塞**——最常见是升级提示框（"有更新可用"），偶尔也有同步冲突弹窗。Web Clipper 服务跑在 Electron 主进程，native dialog 一弹，HTTP server accept 但不处理请求。

恢复（A 级，本机操作）：

1. `desktop activate Joplin` + `desktop screenshot` 看是否有阻塞 modal
2. **有 modal**：找到"取消"按钮坐标，`desktop click` 关掉。立刻 `curl /ping` 验证恢复
3. **无 modal 但端口仍 hang**：`pkill -KILL -f /Applications/Joplin.app` → `open -a Joplin` → 等 15s → 重新截图（重启后大概率会再弹同一个升级提示），按上一步处理
4. 如果是升级提示，把版本号写进 skippedVersions 防止 12h 后再弹：
   ```bash
   sqlite3 "$HOME/.config/joplin-desktop/database.sqlite" \
     "UPDATE key_values SET value='[\"<旧已跳过版本>\",\"<新版本号>\"]' WHERE key='updateCheck::skippedVersions'"
   ```
   旧值用 `SELECT value FROM key_values WHERE key='updateCheck::skippedVersions'` 先读出来再合并

升级 Joplin 本身是选型决策，**永远 B 级**，不要替 Max 升。

---

## 第 1 步：数据采集（感知层）

依次执行以下扫描，任一失败跳过该路即可：

### 1.1 MaxClaw 基线

```bash
cd /path/to/maxclaw && git log --oneline -10
git status --short                       # 长期 dirty 也是信号
sqlite3 data/maxclaw.db "SELECT name, datetime(last_run_at/1000,'unixepoch','localtime') FROM cron_jobs ORDER BY last_run_at DESC LIMIT 8"
sqlite3 data/maxclaw.db "SELECT event_type, message, created_at FROM sub_agent_events WHERE event_type IN ('failed','timeout') AND created_at > (strftime('%s','now')*1000 - 86400000) ORDER BY created_at DESC LIMIT 10"
sqlite3 data/maxclaw.db "SELECT status, error_message, count(*) FROM sub_agent_tasks WHERE status IN ('failed','timeout') AND started_at > (strftime('%s','now')*1000 - 7*86400000) GROUP BY error_message ORDER BY count(*) DESC LIMIT 10"
```

### 1.2 Tool 失败扫描（近 72h，关键新增）

```bash
sqlite3 data/maxclaw.db "
  SELECT datetime(created_at/1000,'unixepoch','localtime') as t, substr(content,1,300)
  FROM chunks
  WHERE role='tool'
    AND created_at > (strftime('%s','now')*1000 - 72*3600*1000)
    -- 只看真正的 tool result 顶层失败/异常信号，避免把文件读取/search_memory/上一轮 reflection 扫描结果里的嵌套文本误判为新失败
    AND content NOT LIKE '{"path":"%/skills/reflection/SKILL.md"%'
    AND content NOT LIKE '{"success":true,"query":%'
    AND content NOT LIKE '%## tool failures 72h%'
    AND (
      content LIKE '{"success":false,%'
      OR content LIKE '{"exitCode":1,%' OR content LIKE '{"exitCode": 1,%'
      OR content LIKE '{"exitCode":2,%' OR content LIKE '{"exitCode": 2,%'
      OR content LIKE '{"exitCode":127,%' OR content LIKE '{"exitCode": 127,%'
      OR (content LIKE '{"success":true,"device":%' AND (content LIKE '%command not found%' OR content LIKE '%Permission denied%'))
    )
  ORDER BY created_at DESC LIMIT 40
"
```

**分析要点**：
- 忽略**探索性失败**（一次性的 `ls 不存在的路径`、grep 没命中之类，这是正常探索行为）
- 聚焦**反复出现的同一错误**（同一命令在不同 session 失败 ≥ 2 次 → 系统性问题）
- 聚焦**依赖缺失**（command not found）和**权限异常**（Permission denied）

### 1.3 未竟之事扫描（近 14 天）

```bash
sqlite3 data/maxclaw.db "
  SELECT datetime(created_at/1000,'unixepoch','localtime') as t, session_id, substr(content,1,300)
  FROM chunks
  WHERE created_at > (strftime('%s','now')*1000 - 14*86400000)
    AND role IN ('user','assistant')
    AND (content LIKE '%TODO%' OR content LIKE '%待修%' OR content LIKE '%暂时%'
         OR content LIKE '%临时%' OR content LIKE '%之后再%' OR content LIKE '%后面再%'
         OR content LIKE '%先这样%' OR content LIKE '%下次%' OR content LIKE '%待验证%'
         OR content LIKE '%等有空%' OR content LIKE '%稍后%')
  ORDER BY created_at DESC LIMIT 30
"
```

**分析要点**：区分"一次性口头话"和"真 commitment"。判断依据：同一主题反复出现 / Max 明确说"记一下"/"回头做"。

### 1.4 外部依赖 health check

```bash
# 仅检查本机需要的 CLI；远端服务（qBittorrent/Joplin 等）走下面的 API 拨号
for bin in copilot codex gh ssh ollama node bun python3 sqlite3 curl jq; do
  if ! which "$bin" >/dev/null 2>&1; then
    echo "MISSING: $bin"
  fi
done
```

关键 API 拨号（可选，失败不算异常）：
```bash
curl -sf -m 5 "http://127.0.0.1:41184/ping" >/dev/null || echo "DOWN: joplin-webclipper"
curl -sf -m 5 "https://vikunja.example.com/api/v1/info" >/dev/null || echo "DOWN: vikunja"
```

对比上一次 health check 结果（存在 `app_config.reflection:deps_last_snapshot` 的 JSON）。有变化才进下一步分析。结束时更新这个 snapshot。

From maxesisn/maxclaw-oss, MIT.

More from maxesisn/maxclaw-oss