Refresh config pages in realtime

docs/superpowers/plans/2026-04-07-config-pages-realtime.md

@@ -0,0 +1,133 @@
+# Config Pages Realtime Refresh Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 让 Boss Web 的配置页在配置状态发生变化后自动刷新。
+
+**Architecture:** 为配置类状态引入专用 SSE 事件，状态写入函数统一发布事件，页面通过 `RealtimeRefresh` 订阅对应事件完成无侵入刷新。实现保持在现有 `boss-events -> /api/v1/events -> RealtimeRefresh` 链路内，不新增新的推送通道。
+
+**Tech Stack:** Next.js App Router, TypeScript, Node test runner, SSE
+
+---
+
+### Task 1: 写红灯测试
+
+**Files:**
+- Create: `tests/config-pages-realtime-refresh.test.ts`
+- Create: `tests/config-state-events.test.ts`
+
+- [ ] **Step 1: 写页面接线失败测试**
+
+```ts
+assert.match(source, /<RealtimeRefresh/, "expected page to render RealtimeRefresh");
+assert.match(source, /events=\{\["ai_accounts\.updated"\]\}/, "expected ai accounts page to refresh on ai account updates");
+```
+
+- [ ] **Step 2: 运行页面测试确认失败**
+
+Run: `npx tsx --test tests/config-pages-realtime-refresh.test.ts`
+Expected: FAIL，提示目标页面还没有接 `RealtimeRefresh` 或事件名不存在。
+
+- [ ] **Step 3: 写事件发布失败测试**
+
+```ts
+await saveAiAccount({ label: "主 GPT", role: "primary", provider: "openai_api", displayName: "OpenAI", apiKey: "sk-test", setActive: true });
+assert.equal(events.at(-1)?.event, "ai_accounts.updated");
+```
+
+- [ ] **Step 4: 运行事件测试确认失败**
+
+Run: `npx tsx --test tests/config-state-events.test.ts`
+Expected: FAIL，提示没有发布新事件。
+
+### Task 2: 补状态事件
+
+**Files:**
+- Modify: `src/lib/boss-events.ts`
+- Modify: `src/lib/boss-data.ts`
+
+- [ ] **Step 1: 扩展事件类型定义**
+
+```ts
+  | "ai_accounts.updated"
+  | "storage.updated"
+  | "master_agent.settings.updated";
+```
+
+- [ ] **Step 2: 在 AI 账号写入路径发布事件**
+
+```ts
+publishBossEvent("ai_accounts.updated");
+```
+
+- [ ] **Step 3: 在附件存储写入路径发布事件**
+
+```ts
+publishBossEvent("storage.updated");
+```
+
+- [ ] **Step 4: 在主 Agent 设置写入路径发布事件**
+
+```ts
+publishBossEvent("master_agent.settings.updated", { projectId: "master-agent" });
+```
+
+- [ ] **Step 5: 跑事件测试确认转绿**
+
+Run: `npx tsx --test tests/config-state-events.test.ts`
+Expected: PASS
+
+### Task 3: 补页面实时刷新
+
+**Files:**
+- Modify: `src/app/me/ai-accounts/page.tsx`
+- Modify: `src/app/me/storage/page.tsx`
+- Modify: `src/app/me/master-agent/page.tsx`
+- Modify: `src/app/me/master-agent/takeover/page.tsx`
+
+- [ ] **Step 1: 给四个页面引入 `RealtimeRefresh`**
+
+```ts
+import { RealtimeRefresh } from "@/components/app-runtime";
+```
+
+- [ ] **Step 2: 给每个页面接上最小事件集合**
+
+```tsx
+<RealtimeRefresh events={["ai_accounts.updated"]} />
+<RealtimeRefresh events={["storage.updated"]} />
+<RealtimeRefresh events={["master_agent.settings.updated"]} />
+```
+
+- [ ] **Step 3: 跑页面测试确认转绿**
+
+Run: `npx tsx --test tests/config-pages-realtime-refresh.test.ts`
+Expected: PASS
+
+### Task 4: 全量验证
+
+**Files:**
+- Test: `tests/config-pages-realtime-refresh.test.ts`
+- Test: `tests/config-state-events.test.ts`
+
+- [ ] **Step 1: 跑本轮相关测试**
+
+Run: `npx tsx --test tests/config-pages-realtime-refresh.test.ts tests/config-state-events.test.ts tests/realtime-refresh-utils.test.ts tests/project-scoped-realtime-refresh.test.ts tests/status-pages-realtime-refresh.test.ts`
+Expected: PASS
+
+- [ ] **Step 2: 跑 lint**
+
+Run: `npm run lint`
+Expected: exit code 0
+
+- [ ] **Step 3: 跑 build**
+
+Run: `npm run build`
+Expected: exit code 0
+
+- [ ] **Step 4: 提交**
+
+```bash
+git add docs/superpowers/specs/2026-04-07-config-pages-realtime-design.md docs/superpowers/plans/2026-04-07-config-pages-realtime.md tests/config-pages-realtime-refresh.test.ts tests/config-state-events.test.ts src/lib/boss-events.ts src/lib/boss-data.ts src/app/me/ai-accounts/page.tsx src/app/me/storage/page.tsx src/app/me/master-agent/page.tsx src/app/me/master-agent/takeover/page.tsx
+git commit -m "Refresh config pages in realtime"
+```