✨ feat(ai-entry): 优化AI助手贴边入口交互体验

- 将 AI 助手入口从侧栏工具区迁移为主内容区右侧贴边标签
- 调整打开态贴边标签锚点到面板左外沿，避免遮挡头部操作区
- 重排侧栏顶部工具布局，恢复四项按钮的稳定网格结构
- 新增 aiEntryLayout 布局辅助与回归测试，覆盖打开态附着位置

docs/superpowers/plans/2026-03-28-ai-edge-handle-entry.md

@@ -0,0 +1,87 @@
+# AI Edge Handle Entry Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 将 AI 助手入口从标题栏移除，改为主内容区右侧的 `A2` 贴边标签入口，并保持现有 AI 面板开关与聊天逻辑不变。
+
+**Architecture:** 保留现有 `App.tsx` 作为 AI 入口装配点，不改 AI 面板展开方向和 store 状态。通过 `aiEntryLayout.ts` 承载可测试的布局/样式决策，让 `App.tsx` 只负责在“主内容关闭态”和“面板展开态”两个壳层里挂载同一个贴边标签。
+
+**Tech Stack:** React 18, TypeScript, Ant Design, Vitest, Vite
+
+---
+
+## File Map
+
+- Modify: `frontend/src/App.tsx`
+  - 移除标题栏 AI 入口渲染与相关样式状态
+  - 在主内容区右边缘挂载关闭态入口
+  - 在 AI 面板外沿挂载打开态入口
+- Modify: `frontend/src/utils/aiEntryLayout.ts`
+  - 将现有标题栏专用布局 helper 改为右侧贴边标签 helper
+  - 保留 `SIDEBAR_UTILITY_ITEM_KEYS`
+- Modify: `frontend/src/utils/aiEntryLayout.test.ts`
+  - 先写失败测试，锁定入口位置、附着位置和贴边标签样式约束
+- Modify: `docs/需求追踪/需求进度追踪-AI助手入口迁移到应用顶栏右侧-20260328.md`
+  - 同步“设计已切换到右侧贴边标签方案”和后续验证状态
+
+## Chunk 1: Layout Contract Regression
+
+### Task 1: 把布局辅助契约改成“右侧贴边标签”
+
+**Files:**
+- Modify: `frontend/src/utils/aiEntryLayout.test.ts`
+- Modify: `frontend/src/utils/aiEntryLayout.ts`
+
+- [ ] **Step 1: 写失败测试，锁定新的布局语义**
+- [ ] **Step 2: 运行测试，确认它因旧契约而失败**
+- [ ] **Step 3: 用最小改动实现新的 helper 契约**
+- [ ] **Step 4: 重新运行测试，确认 helper 契约变绿**
+- [ ] **Step 5: 提交这一小块**
+
+## Chunk 2: Remove Titlebar Entry
+
+### Task 2: 从标题栏彻底移除 AI 入口
+
+**Files:**
+- Modify: `frontend/src/App.tsx`
+
+- [ ] **Step 1: 写出本次要删除的标题栏入口代码清单**
+- [ ] **Step 2: 删除标题栏 AI 入口相关状态与 JSX**
+- [ ] **Step 3: 运行前端构建，确认清理后没有遗留引用**
+- [ ] **Step 4: 提交标题栏清理**
+
+## Chunk 3: Mount The Edge Handle
+
+### Task 3: 在主内容区右边缘挂载关闭态贴边标签
+
+**Files:**
+- Modify: `frontend/src/App.tsx`
+- Modify: `frontend/src/utils/aiEntryLayout.ts`
+
+- [ ] **Step 1: 为关闭态入口写最小布局决策代码**
+- [ ] **Step 2: 把主内容横向容器改成可承载绝对定位标签**
+- [ ] **Step 3: 运行构建，确认关闭态入口接入不破坏布局**
+- [ ] **Step 4: 提交关闭态入口挂载**
+
+### Task 4: 打开 AI 面板时让标签贴住面板外沿
+
+**Files:**
+- Modify: `frontend/src/App.tsx`
+
+- [ ] **Step 1: 给 AI 面板外层加一个仅负责贴边标签定位的壳层**
+- [ ] **Step 2: 用附着位置决策保证开关态只渲染一个入口**
+- [ ] **Step 3: 重新运行 helper 测试和构建**
+- [ ] **Step 4: 提交打开态连续关系**
+
+## Chunk 4: Manual Verification And Docs
+
+### Task 5: 手工验证空间关系，再更新追踪文档
+
+**Files:**
+- Modify: `docs/需求追踪/需求进度追踪-AI助手入口迁移到应用顶栏右侧-20260328.md`
+
+- [ ] **Step 1: 启动本地开发环境做手工验证**
+- [ ] **Step 2: 如发现重叠，优先调整偏移而不是改回胶囊按钮**
+- [ ] **Step 3: 运行最终验证命令**
+- [ ] **Step 4: 更新需求追踪文档**
+- [ ] **Step 5: 提交收尾文档与验证结果**

docs/superpowers/specs/2026-03-28-ai-edge-handle-entry-design.md

@@ -0,0 +1,158 @@
+# AI 助手入口重设计：右侧贴边标签方案
+
+## 1. 背景
+
+当前 AI 助手入口已经尝试过两种方案：
+
+1. 标题栏右侧、靠近窗口控制按钮的胶囊按钮
+2. 标题栏左侧、紧跟应用标题的胶囊按钮
+
+这两种方案都存在同一个问题：入口仍然被感知为“标题栏按钮”或“全局工具按钮”，而不是“从右侧展开的协作面板入口”。用户已经明确选择将 AI 助手定义为协作入口，而非标题栏功能按钮或左侧工作流工具。
+
+本次设计目标是重新定义 AI 助手入口的空间归属关系，让入口与右侧 AI 面板形成直接、自然的视觉和交互映射。
+
+## 2. 设计目标
+
+- 让 AI 入口看起来像右侧面板的入口，而不是标题栏按钮
+- 让入口位置与 AI 面板展开方向保持一致
+- 降低入口对标题栏和主工作区视觉层级的干扰
+- 保持现有 AI 面板开关逻辑、面板位置、聊天状态和快捷键不变
+- 保持左侧 `Sider` 顶部工具组为四个常规工具入口，不再放回 AI
+
+## 3. 非目标
+
+- 不修改 AI 面板本体的信息架构
+- 不修改 AI 聊天、会话、模型、上下文逻辑
+- 不新增 AI 专属状态存储字段
+- 不重新设计标题栏
+- 不把 AI 面板改成左侧抽屉或底部抽屉
+
+## 4. 已评估方案
+
+### 方案 A：标题栏入口
+
+把 AI 放在标题栏右侧或标题后方。
+
+结论：放弃。
+
+原因：
+
+- 容易被识别成窗口级按钮，而不是右侧协作面板入口
+- 入口与 AI 面板的空间关系过远
+- 标题栏承担拖拽、双击、窗口控制等系统职责，额外入口容易显得突兀
+
+### 方案 B：内容区悬浮胶囊
+
+把 AI 入口放在内容区右上角，作为脱离标题栏的悬浮按钮。
+
+结论：未采用。
+
+原因：
+
+- 比标题栏好，但仍然像“漂浮的按钮”
+- 视觉上还是偏独立动作，而不是面板把手
+- 容易与未来内容区工具条或右上角操作区冲突
+
+### 方案 C：右侧贴边入口
+
+把 AI 入口挂在主内容区右边缘、贴近 AI 面板出现位置。
+
+结论：采用。
+
+原因：
+
+- 最符合“右侧面板从这里展开”的直觉
+- 可以脱离标题栏和窗口控制区
+- 与 AI 面板的视觉关系最强
+- 更符合“协作入口”而不是“工具按钮”的产品定位
+
+## 5. 最终方案
+
+### 5.1 位置
+
+- AI 入口彻底离开标题栏
+- AI 入口不再出现在左侧 `Sider` 顶部工具组
+- 入口挂载在主内容区容器内部，而不是窗口根节点
+- 位置锚点是主内容区最右侧边缘，即现有 AI 面板展开出来的那条边
+- 默认位于内容区右上方，明显低于标题栏底边，避免再与标题栏形成视觉混淆
+
+### 5.2 形态
+
+选定形态为 `A2：上角贴边标签`。
+
+入口外观定义如下：
+
+- 采用“半嵌入式贴边标签”而不是完整胶囊按钮
+- 标签右侧贴边，左侧圆角外露
+- 默认文案收敛为 `AI`
+- 保留一个轻量机器人图标，用于快速识别
+- 视觉风格使用面板边框色、弱背景和轻圆角
+- 不使用强阴影、不使用主按钮视觉、不做明显浮层感
+
+目标效果是：入口更像右侧协作面板的标签，而不是单独悬浮的交互控件。
+
+### 5.3 状态
+
+关闭态：
+
+- 标签保持低存在感
+- 弱背景、弱边框、常规文字色
+- 保证可发现，但不抢主内容注意力
+
+悬停态：
+
+- 仅做轻微提亮
+- 允许边框轻微增强
+- 不放大、不上浮、不出现明显浮层阴影
+
+打开态：
+
+- 标签切换到 AI 激活色
+- 视觉上与右侧 AI 面板顶部外沿形成连续感
+- 不隐藏入口，让用户明确知道“标签已经展开成右侧这块面板”
+
+## 6. 交互定义
+
+- 点击贴边标签时，仍然调用现有 AI 面板开关逻辑
+- AI 面板继续从右侧展开，不改变方向
+- 关闭面板后，标签恢复为单独的贴边入口
+- 打开面板时，标签保留在面板外沿作为“已展开标识”
+- 当面板宽度被拖动时，标签始终贴在面板外沿，不与主内容区脱节
+- 在窄窗口下优先保证标签可点击，必要时继续保留 `AI` 简写，不要求展开成长文案
+
+## 7. 实现边界
+
+- 主入口显示与定位由 `App.tsx` 管理
+- AI 面板本身只保留现有展开、关闭和宽度调整行为
+- 状态继续复用现有 `aiPanelVisible`、`toggleAIPanel`、`setAIPanelVisible`
+- 不新增持久化字段，不改 store 结构
+- 左侧 `Sider` 顶部继续保留四个工具按钮：`工具 / 代理 / 主题 / 关于`
+- 标题栏恢复为纯窗口级区域，不继续承载 AI 入口
+
+## 8. 验证口径
+
+实现后重点验证以下事项：
+
+1. 关闭态时，右侧贴边标签是否自然，不像悬浮按钮
+2. 打开态时，标签是否与 AI 面板形成清晰连续关系
+3. 拖动 AI 面板宽度后，标签是否仍贴在面板外沿
+4. 窄窗口下标签是否仍可点击，不与内容区遮挡
+5. 标题栏空白区、窗口控制按钮、左侧侧栏工具组是否恢复干净，不再承担 AI 入口职责
+
+## 9. 风险与注意事项
+
+- 贴边标签如果做得过大，会重新变成“漂浮按钮”
+- 贴边标签如果做得过窄，会影响关闭态可发现性
+- 标签定位需要明确绑定主内容区右边界，而不是整个窗口最右边界，否则在不同布局状态下容易错位
+- 打开态与面板外沿的连续关系必须处理好，否则会显得像两个无关控件
+
+## 10. 决策结论
+
+本次 AI 助手入口重设计的最终结论是：
+
+- 不再使用标题栏入口
+- 不回退到左侧工具条入口
+- 采用主内容区右侧的贴边标签方案
+- 采用 `A2` 形态，即“上角贴边标签”
+
+这是当前最符合“协作入口”定位的方案，也是最能解释 AI 面板空间来源的方案。