DevFlow/docs/02-架构设计/aichat授权体验改进方案-2025-07-15.md

AIChat 授权功能体验改进方案

创建: 2025-07-15 | 状态: 待讨论

一、当前授权机制概览

1.1 核心流程

用户发送消息
  → Agentic Loop (最多 10 轮)
    → LLM 流式响应
    → 解析 tool_calls
    → 按风险等级分流:
        ├─ Low Risk  → 自动并行执行（join_all）
        ├─ Medium    → 暂停循环，等待人工审批
        └─ High      → 暂停循环，等待人工审批
    → 审批通过 → 执行工具 → try_continue_agent_loop 恢复循环
    → 审批拒绝 → tool_result="用户拒绝了此操作" → 恢复循环让 LLM 自行决策

1.2 工具风险分级矩阵

风险等级	工具	执行方式
Low	list_projects, list_tasks, list_ideas, list_trash, read_file, list_directory	自动执行，并行 join_all
Medium	create_project, create_task, create_idea, update_project, update_task, bind_directory, write_file	需人工审批
High	delete_project, restore_project, purge_project, delete_task, run_workflow, run_command	需人工审批

1.3 已实现的亮点

• 审计留痕：ai_tool_executions 表完整记录每次工具调用的状态、风险等级、决策者、请求时间和执行时间
• 断点恢复：应用重启后通过 restore_pending_approvals() 从数据库重建内存中的待审批状态
• 审批卡片可读化：build_approval_reason() 解析工具参数，拼接人类可读的审批理由
• generating 状态 RAII 守护：GeneratingGuard 确保无论正常退出还是 panic，generating 标志都能复位
• 数据变更联动刷新：工具执行成功后自动 emit df-data-changed 事件，前端自动刷新列表
• 安全防护：API Key 存 OS keyring、文件路径双层校验、write_file 覆盖前自动 .bak 备份 + 原子写

1.4 关键代码位置

模块	文件	职责
工具注册表	src-tauri/src/commands/ai/tool_registry.rs	工具定义 + 风险等级 + handler 同源
审批处理	src-tauri/src/commands/ai/audit.rs	工具调用审计 + pending 审批恢复 + 审批后状态回填
Agentic 循环	src-tauri/src/commands/ai/agentic.rs	流式接收 → 工具执行 → 结果回传 LLM → 循环
IPC 命令	src-tauri/src/commands/ai/commands.rs	ai_approve / ai_chat_send / ai_chat_stop 等
审批卡片 UI	src/components/ToolCard.vue	卡片渲染 + 参数展示 + 批准/拒绝按钮
卡片列表	src/components/ToolCardList.vue	多卡片折叠管理
聊天面板	src/components/AiChat.vue	消息列表 + 审批转发 + 输入区
AI Store	src/stores/ai.ts	模块级单例 state
发送/审批	src/composables/ai/useAiSend.ts	approveToolCall 乐观更新 + IPC 调用

---

二、用户体验痛点分析

痛点 1：逐个审批，无法批量操作

现象：当 AI 一次返回多个 Medium/High 工具调用时（比如同时创建 3 个任务 + 写 2 个文件），用户需要逐个点批准/拒绝。

根因：process_tool_calls（audit.rs）把每个待审批工具都推入 pending_approvals HashMap，前端为每个 pending 渲染独立的 ToolCard，每个卡片只有自己的"批准/拒绝"按钮。ToolCardList.vue 没有批量操作入口。

影响：高频交互场景下审批变成体力活，用户体验疲劳。

痛点 2：审批阻塞整个对话，期间无法输入

现象：审批等待期间 generating=true，用户虽然能上滑看历史，但无法发送新消息（sendMessage 会入队），也无法预知还有多少审批在排队。

根因：ai_chat_send（commands.rs:46）检查 session.generating 为 true 时拒绝新消息。审批等待期间 generating 保持 true（agentic.rs 的 guard.disarm() 保持 true 以便 try_continue 续生成）。

影响：用户处于"被动等待"状态，无法并行做其他事。

痛点 3：Medium 和 High 体验无差异

现象：两者都弹同样的审批卡片、同样的按钮，交互流程完全一致。

根因：process_tool_calls（audit.rs:103-120）中 Medium 和 High 走同一个 pending_approvals.insert 分支，区别仅在 build_approval_reason 的文案后缀（"请确认是否执行" vs "高风险，需人工批准"）。

影响：High 操作（如 purge_project 不可恢复）缺乏足够的警示力度，容易误操作。

痛点 4：write_file 审批信息不够直观

现象：write_file 是 Medium 风险，审批卡片只展示 path 和 content 参数。content 可能是几百行代码，在审批卡片里以 formatArgValue 截断到 300 字符展示。

根因：ToolCard.vue 的 toolArgsEntries → displayArgValue → formatArgValue 对超长值统一截断到 300 字符。

影响：用户无法看清要写入的完整内容，只能盲目批准。尤其覆盖已有文件时，用户不知道会改什么。

痛点 5：审批后无进度反馈

现象：点击"批准"后，卡片乐观置 running，但用户不知道：

• 工具正在执行还是已执行完等待 LLM 续生成
• 还有多少待审批在排队
• 整个 agentic 循环进行到第几轮

根因：前端没有全局的 agentic 循环进度指示器。AiAgentRound 事件虽然通知了轮次，但没有在 UI 上持久化展示。

影响：用户对系统状态缺乏掌控感，尤其在多轮工具调用时。

痛点 6：审批卡片可能被滚出视口

现象：当消息很多时，审批卡片可能被新消息推到上方滚出视口。

根因：AiChat.vue 的 collapseInactive 不会收起 pending_approval 卡片，但也不会自动滚动到 pending 卡片。没有全局徽标提醒。

影响：用户可能看不到待审批项，对话看起来"卡住了"但不知道在等什么。

---

三、改进方案

P0 — 快速改善体感

3.1 批量审批

方案：当同一轮有多个 pending 时，在 ToolCardList 顶部显示"全部批准(N) / 全部拒绝"按钮。

改动范围：

• ToolCardList.vue：新增批量操作栏，监听 toolCalls 中 pending_approval 数量
• useAiSend.ts：新增 approveAll(rejectAll) 方法，循环调用 ai_approve

交互：

┌─────────────────────────────────┐
│  ⏳ 3 项待审批                   │
│  [✓ 全部批准]  [✕ 全部拒绝]      │
├─────────────────────────────────┤
│  [工具卡片 1 - pending]          │
│  [工具卡片 2 - pending]          │
│  [工具卡片 3 - pending]          │
└─────────────────────────────────┘

3.2 审批计数器 + 跳转

方案：在输入框上方或 header 显示 ⏳ 2 项待审批，点击跳转到第一个 pending 卡片。

改动范围：

• AiChat.vue：header 区域增加审批徽标
• ToolCardList.vue：暴露 scrollToFirstPending 方法

交互：

┌──────────────────────────────────┐
│  🤖 助手          ⏳2   [+][×]   │  ← 徽标在 header
├──────────────────────────────────┤
│  ...消息列表...                    │
│  ┌─ 工具卡片 (pending) ──┐        │  ← 点击徽标滚动到此
│  │  创建任务：XXX         │        │
│  │  [批准] [拒绝]         │        │
│  └────────────────────────┘        │
├──────────────────────────────────┤
│  [输入框]                         │
└──────────────────────────────────┘

3.3 write_file diff 预览

方案：write_file 审批时，如果文件已存在，展示前后对比 diff 而非裸 content。

改动范围：

• 后端 tool_registry.rs：write_file handler 在执行前读取旧文件内容，返回 diff 信息（或前端请求 diff）
• ToolCard.vue：pending_approval + name=write_file 时渲染 diff 视图

交互：

┌─ 写入文件 src/main.rs (待审批) ──────┐
│                                       │
│  - fn main() {                        │  ← 红色：删除行
│  -     println!("hello");             │
│  + fn main() {                        │  ← 绿色：新增行
│  +     println!("hello, world");      │
│  +     setup_logging();               │
│                                       │
│  ⚠ 覆盖已有文件 (23→45 行)            │
│  [查看完整内容] [批准] [拒绝]          │
└───────────────────────────────────────┘

---

P1 — 增强控制力

3.4 自动审批策略（信任模式）

方案：Settings 中增加"自动审批"配置，用户可选择对特定风险等级或工具类型自动放行。

配置项：

Settings → AI → 自动审批策略
  ○ 严格模式（默认）：所有 Medium/High 需人工审批
  ○ 宽松模式：Medium 自动放行，High 需人工审批
  ○ 自定义：按工具类型选择
      ☑ write_file（workspace 内自动放行）
      ☑ create_task / create_idea（自动放行）
      ☐ delete_*（始终需审批）
      ☐ run_command（始终需审批）

改动范围：

• df-storage：app_settings 表存储配置（KV 已有 V13 表）
• audit.rs：process_tool_calls 读取配置，决定 Medium 工具是否进 pending 或直接执行
• Settings.vue：新增配置面板

3.5 High 二次确认

方案：delete/purge/run_command 等高风险操作，批准后弹出二次确认。

改动范围：

• ToolCard.vue：High 风险 + approved=true 时，先弹 inline 确认（"确定要永久删除？此操作不可恢复"）
• 或用现有 ConfirmDialog 组件

交互：

第一次点击"批准":
  → 卡片内弹出确认提示
  → "确定要永久删除项目「XXX」？此操作不可恢复"
  → [确认删除] [取消]

第二次点击"确认删除":
  → 才真正执行 ai_approve

3.6 审批超时

方案：可配置超时自动拒绝（默认 5 分钟），避免对话永久卡住。

改动范围：

• 后端：AiSession 增加 pending 审批的 created_at 时间戳，定时检查超时
• 或前端：useAiSend.ts 在 pending 时启动定时器，超时自动调 ai_approve(id, false)

---

P2 — 信息透明度

3.7 Agentic 进度条

方案：在消息区域底部显示循环进度。

改动范围：

• AiChat.vue：底部增加进度指示条
• useAiEvents.ts：处理 AiAgentRound 事件时更新进度

交互：

┌──────────────────────────────────┐
│  ...消息列表...                    │
│                                   │
│  🔄 循环 3/10 · ⏳2待审批 · ✅5完成 │  ← 底部进度条
├──────────────────────────────────┤
│  [输入框]                         │
└──────────────────────────────────┘

3.8 审批历史面板

方案：独立页面展示 ai_tool_executions 表的审计记录。

改动范围：

• 后端：新增 list_tool_executions IPC 命令（查询审计表）
• 前端：新增 AuditLog.vue 视图，表格展示历史记录

展示字段：

时间	工具	风险	状态	决策者	参数摘要	结果摘要

---

四、实施优先级建议

优先级	改进项	预估工作量	用户价值
P0	3.1 批量审批	0.5 天	🔥🔥🔥
P0	3.2 审批计数器 + 跳转	0.5 天	🔥🔥🔥
P0	3.3 write_file diff 预览	1 天	🔥🔥
P1	3.4 自动审批策略	1.5 天	🔥🔥🔥
P1	3.5 High 二次确认	0.5 天	🔥
P1	3.6 审批超时	0.5 天	🔥
P2	3.7 Agentic 进度条	0.5 天	🔥🔥
P2	3.8 审批历史面板	1 天	🔥

建议第一批落地：P0 三项（批量审批 + 计数器 + diff 预览），总计约 2 天工作量，覆盖最高频的体验痛点。