docs: add P3 configuration implementation plan

This commit is contained in:
xiaoxixi 2026-07-26 22:21:54 +08:00
parent c6a3814530
commit 1e984eef66

View File

@ -0,0 +1,67 @@
# P3 配置 Implementation Plan
> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan.
**Goal:** 重构 WebUI 配置页SettingsPage增加实时 JSON 校验、配置大纲、重载状态卡、保存并热重载、放弃修改、未保存提示。
**Architecture:** 纯前端重构。所有后端端点已存在GET/PUT /api/config、GET/PUT /api/profiles/{name}、POST /api/config/reload、GET /api/config/reload/status。SettingsPage.svelte 重写为带配置大纲侧栏 + 重载状态卡 + 三操作按钮的布局。
**Tech Stack:** Svelte 5runes、bits-ui Tabs。
**关键设计决策:**
1. **布局**:左侧编辑区(现有 editor-card+ 右侧大纲/状态侧栏(仅 config.json 标签显示)。
2. **JSON 校验**`$derived` 实时 parse content显示错误信息或有效状态。
3. **配置大纲**:从 parsed config 提取顶层 key 列表,标注含密钥的 sectionproviders和需重启的字段gateway.host/port/workspace
4. **重载状态卡**onMount 起每 3s 轮询 `GET /api/config/reload/status`,显示 generation、phase badge、last_error。
5. **操作按钮**保存PUT /api/config、保存并热重载PUT 后 POST /api/config/reload、放弃修改重新 load
6. **未保存提示**:比较当前 content 与上次加载的 content不同则显示修改标记。
7. **USER.md / AGENTS.md 标签**:保持简单 textarea + 保存,无大纲/重载。
**验证约定:** `cd webui && npm run check && npm run build` + `cargo build`(验证 OUT_DIR 嵌入)。
---
## Task 1: SettingsPage 重构
**Files:**
- Modify: `webui/src/pages/SettingsPage.svelte`
- [ ] **Step 1: 重写 SettingsPage.svelte**
布局:
```
┌─────────────────────────────────────────────────────┐
│ [config.json] [USER.md] [AGENTS.md] [重载状态卡] │
├───────────────────────────────────┬─────────────────┤
│ editor-head: title + path │ 配置大纲 │
│ + 未保存标记 │ (仅 config) │
│ ───────────────────────────── │ │
│ textarea (JSON/Markdown) │ gateway ⚠重启 │
│ │ providers 🔑 │
│ │ agent │
│ │ channels │
│ │ memory │
│ │ scheduler │
│ ───────────────────────────── │ │
│ [保存] [保存并热重载] [放弃修改] │ │
│ notice / validation error │ │
└───────────────────────────────────┴─────────────────┘
```
功能:
- JSON 实时校验config 标签parse 失败显示红色错误行
- 未保存修改dirty 标记(对比 original content
- 保存PUT /api/config 或 PUT /api/profiles/{name}
- 保存并热重载:保存成功后 POST /api/config/reload显示结果
- 放弃修改:恢复为上次加载的 content
- 重载状态卡generation、phasebadge 着色、last_error
- 配置大纲:顶层 key 列表 + 标注
- [ ] **Step 2: 验证**`cd webui && npm run check && npm run build`
- [ ] **Step 3: Commit**`git add webui/src/pages/SettingsPage.svelte && git commit -m "feat(webui): enhanced settings page with outline, reload status, hot reload"`
## Task 2: 收尾
- [ ] **Step 1: 全量验证**`cargo build` + `cd webui && npm run check && npm run build`
- [ ] **Step 2: 版本号** — 1.6.0 → 1.7.0
- [ ] **Step 3: Commit**`git add Cargo.toml webui/package.json && git commit -m "chore(release): P3 configuration"`