# AI 助手插件 · AI 视图优化计划 · 返工

> 本文档为 2026-08-26-AI-assistant-improvement.md 的返工
## 一、文档信息

| 字段 | 内容 |
|------|------|
| 创建日期 | 2026-08-27 |
| 状态 | 规划（待执行） |
| 涉及范围 | AI 视图：皮肤系统、web_search 多来源、会话树形分支、返回导航 |
| 关联计划 | `2026-08-26-AI-assistant-improvement.md`（本计划为其中 Task 的返工） |

## 二、背景与目标

本次返工聚焦 4 个问题域：

1. **Bug 1/10（返工）**：AI 视图渲染色已由 theme 统一，修复效果完美，但范围过大——根源是当前 theme 仅 8 平色、过于单一，难以支撑复杂的 AI 主题 DIY。
2. **Bug 2**：搜索工具统一入口，让 web_search 支持 arxiv / github 作为 mode 参数，并支持三来源（网络、arxiv、github）三合一召回。
3. **Bug 7（返工）**：旧实现与需求漂移——对话应是「一棵树」而非「一条直线」，不同分支不应当作不同会话管理。
4. **新 Bug**：AI 视图通往数据中心 / 插件中心 / 设置面板后的左上角返回浮珠在安卓上不易点击（摄像头遮挡）。

## 三、任务分解

### Task 一：AI 视图皮肤包「DIY your own greenix」

**问题**
- Bug 1/10（返工）：AI 视图渲染色已被 theme 统一（见「六、参考经验」基线），但 theme 8 平色过于单一，无法支撑复杂 AI 主题 DIY。

**决策 1｜新建插件类型：agent 皮肤包**
- AI 视图**不再归 theme 管**，新建插件类型「agent 皮肤包」
- 皮肤包构成：**单个 manifest.json + png/svg 等图片资源**，无 Python/Dart 代码
- 在 `evg-base\docs\plugin-registry\examples` 新增示例插件：
```
example-skin-evergreen-logo
└── skin
    ├── manifest.json
    ├── logo_desktop.svg   # 平板横板 / 电脑版使用，自适应大小
    └── logo_mobile.svg    # 平板竖版 / 手机版使用，自适应大小
```

- logo 来源：`evg-base\assets\branding\logo-ink.svg` 或 `evg-base\assets\branding\logo.svg`（绿意不息 logo）

**DIY 内容候选清单**（多选，组合成一个「皮肤包」）：

*候选 A · 对话背景 DIY（皮肤）*
- A1 纯色 / 渐变色背景：自选对话页底色
- A2 图片背景：使用本地图片 png/svg 作为对话背景，叠加半透明遮罩保证文字可读
- A3 背景模糊度 / 透明度可调

*候选 B · 按钮显隐控制*
- B1 工具栏按钮：输入框上方按钮栏（联网搜索、工具、skill 管理等）逐项可隐藏
- B2 消息操作按钮：每条消息的复制 / 重新生成 / edit 等操作，可统一隐藏

*候选 C · 思考栏渲染*
- C1 思考栏配色独立：AI 思考栏渲染色从全局 theme 解耦，单独由 skin 包定制
- C2 思考栏形态：默认展开 / 默认折叠 / 收起动画提供选项
- C3 思考栏中各类工具调用卡片的背景、指示图标等可 DIY

*候选 D · 消息气泡样式*
- D1 气泡：圆角大小、气泡底色、最大宽度
- D2 字体：字号、行高、代码块风格

*候选 E · 你自己补充*
- AI助手里可DIY的地方实在太多了，用户头像，AI头像等等，思考栏透明度，“思考栏”的标题渲染等等，AI思考栏显示与否等等等等。既然要做皮肤包,自然可以做得丰富一些, 看到什么AI助手插件特有的渲染大胆加上便是

**决策 1.2｜默认皮肤包**：提供默认皮肤包，未加装任何皮肤包时可用——像现在的亮暗色 theme 一样直接编码内置。

**决策 1.3｜设置项**：设置面板提供切换皮肤包的设置项——与现在的 theme 切换一致。

**验收**：新示例 `example-skin-evergreen-logo` 同步放入evg-base\docs\plugin-registry\assets并在evg-base\docs\plugin-registry\plugins.json中补写，使其可作为皮肤包安装并生效；未装皮肤包时有默认皮肤包兜底；设置面板可切换皮肤包；候选 A/B/C/D 中被选中的 DIY 项按皮肤包配置生效，否则按默认值填充

### Task 二：web_search 多来源召回

**问题**
- Bug 2：希望把 arxiv 和 github 作为 `web_search` 的 `mode` 参数来处理；也支持 web_search 三处来源（网络、arxiv、github）三合一一并召回。

**决策**
- `web_search` 新增 `mode` 参数：`arxiv`、`github`（与现有网络来源并列）
- 支持三来源（网络、arxiv、github）三合一一并召回

**验收**：`web_search` 可按 mode 指定单一来源，也可三合一召回；召回结果区分来源。评估可复用 08-26 计划的搜索找回探针（见「五、风险与注意事项」）。这样就可以统一多平台搜索工具，避免AI记忆和需要多次调用tool的负担

### Task 三：会话树形分支（返工）

**问题**
- Bug 7（返工）：现在的实现是错误的，究其根本是旧实现已与实际需求漂移，在规划时又错误复用了先前的错误的实现。
- 期望一句话：**对话不再是「一条直线」，而是「一棵树」**——任一轮对话都可以长出多个后续走向（分支），用户可以随时回到某个分叉点，左右切换查看不同分支的走向。

**目标语义**

*举例（两个分支从同一轮消息处分开）：*
```text
分支1：用户: hi → AI: hello → 用户: ok   → AI: 怎么了？
分支2：用户: hi → AI: hello → 用户: ok啊 → AI: 好的
```

*实际存储（树形结构，按对话轮次分层，可以用孩子兄弟节点的二叉树实现——便于后面的切换兄弟分支的操作）：*
```text
depth 0 ── agent_loop_id = 0   用户: hi → AI: hello
depth 1 ── agent_loop_id = 1   ├─ 分支1: 用户: ok   → AI: 怎么了？
                               └─ 分支2: 用户: ok啊 → AI: 好的
```

*实际 UI（在分叉的这条消息下方出现分支切换条）：*
```text
用户: hi
AI: hello
用户: ok            ← 此条消息下方出现分支切换条（是消息下面出现分支切换条而非会话名下面）
   ◀  1 / 2  ▶      ← 左移 / 右移按钮 + 当前分支序号指示
AI: 怎么了？
```

**与现状的关键区别**：**不是**把不同分支当作不同会话管理——这是错误的。一个会话是一棵树，而非树的一条边。

**关联**：为 2026-08-26 计划 Task 六 Bug 7（撤回改 edit/branch 工具）的返工；08-26 约束仍有效——分支不与工作区挂钩，工作区变更不可逆。

**验收**：同一会话内支持从任意一轮消息分叉；分叉点下方出现分支切换条（◀ 1/2 ▶）；左右切换可见不同分支走向；分支作为树的节点存储而非独立会话。

### Task 四：返回导航浮珠优化

**问题**
- 新 Bug：AI 视图里通往数据中心、插件中心和设置面板后，回来的那个左上角返回浮珠不容易点击——安卓上有摄像头遮挡。

**决策**
- 此处恐牵一发而动全身，需谨慎评估影响面。
- **面板自带返回**：三个面板（数据中心 / 插件中心 / 设置面板）各自加上与 AI 助手同款的返回入口（AppBar）——当且仅当 AI 视图下显示。
- **左上角浮珠直接移除**。

**验收**：AI 视图下三个面板均有同款返回入口；左上角返回浮珠已移除；其余视图/模式导航不受影响。

## 四、任务依赖与执行顺序

| Task | 依赖 | 说明 |
|------|------|------|
| Task 一（皮肤包） | 无 | 插件类型 + 示例 + 默认包 + 设置项，建议先行 |
| Task 二（web_search） | 无 | 独立 |
| Task 三（会话树） | 无 | 存储层 + UI 改动较大，独立于皮肤包 |
| Task 四（返回导航） | 无 | 影响面需评估，涉及三个面板 |

各 Task 相互独立，可按任意顺序实施；建议按「影响面小的先做」排期。

## 五、风险与注意事项

- **Bug 1/10 返工范围控制**：AI 视图渲染色已 theme 化（见参考经验基线），skin 包解耦时须明确「功能色」与「语义色」边界，避免破坏既有深色适配。
- **返回浮珠移除牵一发动全身**：先评估三个面板的导航链路与测试依赖，再动手。
- **会话树改动大**：涉及存储结构（按轮次分层 + agent_loop_id）与 UI（分支切换条），需回归现有会话功能。
- **搜索评估**：Bug 2 的评估可复用 08-26 计划 Task 二的搜索找回测试探针（预设关键词观察召回全面/专业/可靠/时效，多轮迭代），而非 fail/pass。
- **记忆文件不入 git**：本文档内置的关键经验为长期保存依据。

## 六、参考经验（脱敏）

*经验 1｜AI 视图渲染色 theme 化基线（Bug 1/10 返工的出发点）*
- 已完成：AI 助手模板灰/黑白/大面积蓝全部映射 `colorScheme` 语义色，深色模式自动适配；仅保留少量小面积品牌色与功能色 chip。
- 常用映射：`grey.shade100/300` → `surfaceContainerLow/Lowest`；`grey.shade400/600/800` → `outlineVariant/onSurfaceVariant`；`black87` → `onSurface`；primary 背景上的 `white` → `onPrimary`；blue 系 → `primary/primaryContainer`。
- 思考栏渲染色属于「功能色」保留部分（如思考过程语义色 0xFFF5F5F5 / 0xFFE53935 / 0xFFF57C00 / 0xFFFFF8E1 等）——C1 解耦时重点在此，需界定哪些思考过程色可被 skin 包覆盖、哪些是语义色不可乱改。

*经验 2｜AppBar 滚动变灰黑（Task 四面板自带返回若走 AppBar 需注意）*
- AppBar 未显式设 `backgroundColor` 时，`scrolledUnder` 状态背景回退到 `colorScheme.surfaceContainer`（深色主题近黑）。
- 修复：显式 `backgroundColor: colorScheme.surfaceContainerLowest`；`surfaceTintColor` 只去 tint 叠加、不阻止底色切换。
- 三个面板新增返回 AppBar 时，若内容可滚动须显式设背景色。