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

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: 写页面接线失败测试

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: 写事件发布失败测试

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: 扩展事件类型定义

  | "ai_accounts.updated"
  | "storage.updated"
  | "master_agent.settings.updated";

• Step 2: 在 AI 账号写入路径发布事件

publishBossEvent("ai_accounts.updated");

• Step 3: 在附件存储写入路径发布事件

publishBossEvent("storage.updated");

• Step 4: 在主 Agent 设置写入路径发布事件

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

import { RealtimeRefresh } from "@/components/app-runtime";

• Step 2: 给每个页面接上最小事件集合

<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: 提交

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"