# Agent 对话页面体验优化设计

> 日期：2026-04-13
> 状态：待实施
> 范围：前端 agent 模块 + 后端 netaclaw 模块

## 1. 背景与问题

当前 Neta 项目的 agent 对话页面存在 4 个体验问题：

1. **Skill 视觉跳变**：执行中由 `skill-indicator.vue` 渲染进度条，完成后 `skillProgress` 被清空，Skill 记录转存到 `message.metadata.skillExecutions`，由 `message-item.vue` 重新渲染为"查看结果"按钮。两个完全不同的组件、不同的位置，造成视觉断裂。
2. **Token 计算不准**：前端用字符数粗估 token（中文 1.5 字符=1 token），与实际偏差大。
3. **Token UI 不直观**：统计条占据对话区顶部整行，信息密度低。
4. **缺少任务规划**：agent 每次裸跑，没有 todo/plan 工具，不会主动规划任务步骤。

5. **思考内容不流畅**：思考内容不是流式展示，等全部完成才一次性显示；默认折叠用户容易忽略；没有思考级别控制。
6. **LLM 适配器思考参数缺失**：后端已有 `thinking.ts` 基础框架和 `ThinkLevel` 类型，但 Anthropic/OpenAI 适配器未将思考参数传递给 API。

参考项目：
- **openclaw-main**：`update_plan` 工具；思考块虚线边框+半透明背景+呼吸动画；思考级别下拉选择器
- **hermes-agent-main**：`TodoStore` + `todo` 工具；多模型统一思考适配层；thinking_delta 流式推送；思考预算分级

用户选择 hermes 的 TodoStore 方案作为主要参考，思考 UI 参考 openclaw 的视觉设计。

## 2. 设计目标

- Skill 执行中→完成：同一个组件、同一个位置、CSS 过渡动画，无跳变
- Token 数据：前端零估算，100% 由后端推送真实数据
- Token UI：紧凑，不抢眼，hover 查看详情
- Todo 系统：后端 `todo` 工具 + 前端内嵌卡片，agent 主动规划，实时更新
- 思考内容：流式展示 + 呼吸动画 + 光标闪烁，思考→正文平滑过渡
- 思考级别：前端可选（off/minimal/low/medium/high/adaptive），会话级持久化
- 多模型适配：统一思考参数传递层，Anthropic/OpenAI/DeepSeek 各自映射

## 3. Todo 工具系统（后端）

### 3.1 TodoStore 类

文件：`packages/backend/src/modules/netaclaw/runtime/todo_store.ts`

完全参考 hermes 的 TodoStore 设计：

```typescript
interface TodoItem {
  id: string;        // agent 自选的唯一标识
  content: string;   // 任务描述
  status: 'pending' | 'in_progress' | 'completed' | 'cancelled';
}

interface TodoSummary {
  total: number;
  pending: number;
  in_progress: number;
  completed: number;
  cancelled: number;
}

class TodoStore {
  private items: TodoItem[] = [];

  /**
   * 写入 todo 列表
   * @param todos - 任务项数组
   * @param merge - false(默认)=全量替换，true=按 id 增量更新+追加新项
   * @returns 写入后的完整列表
   */
  write(todos: TodoItem[], merge: boolean = false): TodoItem[] {
    if (!merge) {
      // Replace 模式：全量替换，agent 重新规划时使用
      this.items = todos.map(t => this.validate(t));
    } else {
      // Merge 模式：按 id 匹配更新，未匹配的追加
      for (const todo of todos) {
        const validated = this.validate(todo);
        const existing = this.items.find(i => i.id === validated.id);
        if (existing) {
          Object.assign(existing, validated);
        } else {
          this.items.push(validated);
        }
      }
    }
    return this.read();
  }

  /** 读取当前列表（返回拷贝，防止外部篡改） */
  read(): TodoItem[] {
    return JSON.parse(JSON.stringify(this.items));
  }

  hasItems(): boolean {
    return this.items.length > 0;
  }

  getSummary(): TodoSummary {
    const s = { total: 0, pending: 0, in_progress: 0, completed: 0, cancelled: 0 };
    for (const item of this.items) {
      s.total++;
      s[item.status]++;
    }
    return s;
  }

  /**
   * 上下文压缩后注入，只保留 pending + in_progress 项
   * 返回人类可读格式，作为 user message 注入压缩后的历史
   */
  formatForInjection(): string | null {
    const active = this.items.filter(i => 
      i.status === 'pending' || i.status === 'in_progress'
    );
    if (active.length === 0) return null;

    const lines = active.map(i => {
      const marker = i.status === 'in_progress' ? '[>]' : '[ ]';
      return `- ${marker} ${i.id}. ${i.content} (${i.status})`;
    });
    return '[你的活跃任务列表在上下文压缩后被保留]\n' + lines.join('\n');
  }

  /**
   * 从历史消息中恢复 todo 状态（hydrate）
   * 倒序扫描消息，找到最近一次 todo 工具调用的返回值
   */
  static hydrateFromHistory(messages: any[]): TodoStore {
    const store = new TodoStore();
    for (let i = messages.length - 1; i >= 0; i--) {
      const msg = messages[i];
      if (msg.role === 'tool' && msg.toolName === 'todo') {
        try {
          const data = JSON.parse(msg.content);
          if (data.todos) {
            store.write(data.todos, false);
          }
        } catch {}
        break;
      }
    }
    return store;
  }

  private validate(item: Partial<TodoItem>): TodoItem {
    return {
      id: item.id || '?',
      content: item.content || '(无描述)',
      status: ['pending', 'in_progress', 'completed', 'cancelled'].includes(item.status!)
        ? item.status!
        : 'pending',
    };
  }
}
```

### 3.2 todo 工具定义

文件：`packages/backend/src/modules/netaclaw/tools/todo_tool.ts`

```typescript
const todoToolSchema = {
  name: 'todo',
  description: 
    '管理当前会话的任务列表。用于3步以上的复杂任务或用户提供多个任务时。\n'
    + '不传参数=读取当前列表。\n'
    + '传 todos 数组=写入。merge=false(默认)全量替换整个计划，merge=true 按 id 增量更新。\n'
    + '每个项: { id: string, content: string, status: pending|in_progress|completed|cancelled }\n'
    + '列表顺序=优先级。同一时间只能有一个 in_progress。\n'
    + '完成立即标记 completed。失败则 cancel 并添加修正项。\n'
    + '始终返回完整列表。',
  parameters: {
    type: 'object',
    properties: {
      todos: {
        type: 'array',
        description: '任务项数组。省略则读取当前列表。',
        items: {
          type: 'object',
          properties: {
            id: { type: 'string', description: '唯一标识' },
            content: { type: 'string', description: '任务描述' },
            status: {
              type: 'string',
              enum: ['pending', 'in_progress', 'completed', 'cancelled'],
              description: '当前状态',
            },
          },
          required: ['id', 'content', 'status'],
        },
      },
      merge: {
        type: 'boolean',
        description: 'true=按 id 增量更新+追加新项。false(默认)=全量替换整个列表。',
        default: false,
      },
    },
    required: [],
  },
};
```

工具返回值格式：
```json
{
  "todos": [
    { "id": "1", "content": "分析需求文档", "status": "completed" },
    { "id": "2", "content": "实现用户认证模块", "status": "in_progress" },
    { "id": "3", "content": "编写单元测试", "status": "pending" },
    { "id": "4", "content": "更新API文档", "status": "pending" }
  ],
  "summary": { "total": 4, "pending": 2, "in_progress": 1, "completed": 1, "cancelled": 0 }
}
```

### 3.3 集成到 ReAct 循环

- 每个 agent session 维护一个 `TodoStore` 实例
- 新建 session：空 TodoStore
- 恢复 session（gateway 模式）：`TodoStore.hydrateFromHistory(messages)` 从历史恢复
- agent 调用 `todo` 工具后：通过 WS 推送 `todo_update` 事件
- 上下文压缩时：调用 `todoStore.formatForInjection()`，非空则作为 user message 注入压缩后历史

## 4. Skill 统一组件（前端）

### 4.1 核心改动

废弃双组件方案（`skill-indicator.vue` + `message-item.vue` 内嵌历史），合并为 `skill-card.vue`。

**数据流对比**：

改造前（有跳变）：
```
skill_start → skillProgress[] 添加 → skill-indicator.vue 渲染
skill_end   → skillProgress[] 更新 status=done
done        → skillProgress[] 清空 → metadata.skillExecutions 接管
           → message-item.vue 重新渲染（跳变！）
```

改造后（无跳变）：
```
skill_start → skillProgress[] 添加 → skill-card.vue 渲染（status=running）
skill_end   → skillProgress[] 更新 status=done → skill-card.vue CSS 过渡（无跳变）
done        → skillProgress[] 保留不清空，同时写入 metadata 用于历史恢复
```

关键变化：`done` 事件**不再清空** `skillProgress`，组件始终由 `skillProgress` 驱动。

### 4.2 skill-card.vue

文件：`packages/frontend/src/modules/agent/components/skill-card.vue`

```vue
<template>
  <div class="skill-card" :class="[`skill-card--${status}`]">
    <!-- 头部：图标 + 名称 + 状态标签 -->
    <div class="skill-card__header">
      <el-icon :class="{ 'is-rotating': status === 'running' }">
        <Loading v-if="status === 'running'" />
        <CircleCheck v-else-if="status === 'done'" />
        <CircleClose v-else />
      </el-icon>
      <span class="skill-card__name">{{ label }}</span>
      <el-tag v-if="status === 'done'" size="small" type="success">完成</el-tag>
      <el-tag v-if="status === 'error'" size="small" type="danger">失败</el-tag>
    </div>

    <!-- 执行中：进度条 + 步骤描述 -->
    <transition name="fade">
      <div v-if="status === 'running'" class="skill-card__progress">
        <el-progress :percentage="percent" :stroke-width="4" />
        <span class="skill-card__step">{{ step || detail }}</span>
      </div>
    </transition>

    <!-- 完成后：查看结果按钮 -->
    <transition name="fade">
      <div v-if="status === 'done' && result" class="skill-card__result">
        <el-button text size="small" @click="showResult = !showResult">
          {{ showResult ? '收起' : '查看结果' }}
        </el-button>
      </div>
    </transition>

    <!-- 结果详情 -->
    <el-collapse-transition>
      <skill-result-viewer v-if="showResult" :result="result" :type="resultType" />
    </el-collapse-transition>
  </div>
</template>
```

CSS 过渡：
```css
.skill-card {
  transition: all 0.3s ease;
  border-left: 3px solid var(--skill-border-color);
}
.skill-card--running { --skill-border-color: var(--el-color-primary); }
.skill-card--done    { --skill-border-color: var(--el-color-success); }
.skill-card--error   { --skill-border-color: var(--el-color-danger); }

.fade-enter-active, .fade-leave-active { transition: opacity 0.3s ease; }
.fade-enter-from, .fade-leave-to { opacity: 0; }
```

### 4.3 store/chat.ts 改动

```typescript
// done 事件：不再清空 skillProgress
case 'done': {
  // 将 skillProgress 写入 metadata 用于历史恢复
  if (assistantMsg) {
    assistantMsg.metadata.skillExecutions = [...skillProgress.value];
    // 不再执行 skillProgress.value = []
  }
  break;
}

// 切换会话时才清空
function switchSession(newSessionId: string) {
  skillProgress.value = [];  // 切换时清空
  // ...加载新会话消息
}

// 加载历史消息时从 metadata 恢复
function restoreSkillProgress(messages: ChatMessage[]) {
  skillProgress.value = [];
  for (const msg of messages) {
    if (msg.metadata?.skillExecutions) {
      skillProgress.value.push(...msg.metadata.skillExecutions);
    }
  }
}
```

## 5. Token 统计系统改造

### 5.1 后端改动

`token_update` WS 事件增加 `context` 字段：

```typescript
interface TokenUpdateEvent {
  // 本轮对话的实时累计
  current: {
    inputTokens: number;
    outputTokens: number;
    totalTokens: number;
    apiCalls: number;
  };
  // 上下文窗口状态（新增）
  context: {
    usedTokens: number;   // 当前上下文已用 token
    maxTokens: number;    // 模型上下文窗口上限
    percent: number;      // 使用百分比（后端算好）
  };
}
```

推送时机：每次 LLM API 返回后推送。

### 5.2 前端改动

删除本地 token 估算逻辑：

```typescript
// 删除：estimateContextTokens 相关代码
// 删除：中文字符/其他字符的 token 估算公式

// 简化为：
const tokenUsage = ref<TokenUpdateEvent | null>(null);

case 'token_update': {
  tokenUsage.value = event.data;
  break;
}

case 'done': {
  if (assistantMsg && tokenUsage.value) {
    assistantMsg.metadata.tokenUsage = tokenUsage.value.current;
  }
  tokenUsage.value = null;
  break;
}
```

### 5.3 Token UI 重设计

从顶部统计条改为输入区右下角紧凑展示：

```
┌─ 对话区 ────────────────────────────────────┐
│                                              │
│  消息列表...                                 │
│                                              │
├──────────────────────────────────────────────┤
│ 输入框                                       │
│                                              │
│ [Agent选择]  [附件]         上下文 32% ●  2K │
└──────────────────────────────────────────────┘
```

文件：`packages/frontend/src/modules/agent/components/token-stats.vue`

```vue
<template>
  <div class="token-stats" :class="{ 'is-active': isRunning }">
    <!-- 执行中：实时数据 -->
    <template v-if="isRunning && tokenUsage">
      <span class="token-stats__realtime">
        ↑{{ formatTokens(tokenUsage.current.inputTokens) }}
        ↓{{ formatTokens(tokenUsage.current.outputTokens) }}
        · {{ tokenUsage.current.apiCalls }}次
      </span>
      <span class="token-stats__divider">|</span>
    </template>

    <!-- 上下文占比（始终显示） -->
    <el-tooltip :content="contextTooltip" placement="top">
      <span class="token-stats__context">
        上下文 {{ contextPercent }}%
        <span class="token-stats__dot" :style="{ background: dotColor }" />
      </span>
    </el-tooltip>
  </div>
</template>
```

格式化规则：`1234` → `1.2K`，`12345` → `12.3K`
颜色规则：≤50% 绿，50-80% 黄，>80% 红。

## 6. Todo 卡片前端组件

### 6.1 store/chat.ts 新增

```typescript
const todoItems = ref<TodoItem[]>([]);
const todoSummary = ref<TodoSummary | null>(null);

case 'todo_update': {
  todoItems.value = event.data.todos;
  todoSummary.value = event.data.summary;
  break;
}

// 切换会话时从历史恢复
function restoreTodoFromHistory(messages: ChatMessage[]) {
  for (let i = messages.length - 1; i >= 0; i--) {
    const msg = messages[i];
    if (msg.role === 'tool' && msg.metadata?.toolName === 'todo') {
      try {
        const data = JSON.parse(msg.content);
        todoItems.value = data.todos;
        todoSummary.value = data.summary;
      } catch {}
      return;
    }
  }
  todoItems.value = [];
  todoSummary.value = null;
}
```

### 6.2 todo-card.vue

文件：`packages/frontend/src/modules/agent/components/todo-card.vue`

```vue
<template>
  <div v-if="items.length" class="todo-card">
    <!-- 头部 -->
    <div class="todo-card__header" @click="collapsed = !collapsed">
      <span class="todo-card__icon">📋</span>
      <span class="todo-card__title">任务规划</span>
      <span class="todo-card__summary">
        {{ summary.completed }}/{{ summary.total }} 完成
      </span>
      <div class="todo-card__progress-bar">
        <div class="todo-card__progress-fill"
             :style="{ width: (summary.completed / summary.total * 100) + '%' }" />
      </div>
      <el-icon class="todo-card__toggle">
        <ArrowUp v-if="!collapsed" /><ArrowDown v-else />
      </el-icon>
    </div>

    <!-- 任务列表 -->
    <el-collapse-transition>
      <div v-if="!collapsed" class="todo-card__list">
        <transition-group name="todo-item">
          <div v-for="item in items" :key="item.id"
               class="todo-card__item"
               :class="[`todo-card__item--${item.status}`]">
            <span class="todo-card__status-icon">
              <template v-if="item.status === 'completed'">✅</template>
              <template v-else-if="item.status === 'in_progress'">
                <span class="todo-card__spinner" />
              </template>
              <template v-else-if="item.status === 'cancelled'">❌</template>
              <template v-else>⬚</template>
            </span>
            <span class="todo-card__content" :class="{
              'is-done': item.status === 'completed',
              'is-cancelled': item.status === 'cancelled',
              'is-active': item.status === 'in_progress'
            }">
              {{ item.content }}
            </span>
            <el-tag v-if="item.status === 'in_progress'"
                    size="small" type="primary" effect="light">
              进行中
            </el-tag>
          </div>
        </transition-group>
      </div>
    </el-collapse-transition>
  </div>
</template>
```

CSS 要点：
```css
.todo-card {
  margin: 8px 0;
  border-radius: 8px;
  border: 1px solid var(--el-border-color-lighter);
  background: var(--el-fill-color-lighter);
  overflow: hidden;
}
.todo-card__item { transition: all 0.3s ease; }
.todo-card__item--in_progress { background: var(--el-color-primary-light-9); }
.todo-card__content.is-done { text-decoration: line-through; color: var(--el-text-color-placeholder); }
.todo-card__content.is-active { font-weight: 600; color: var(--el-color-primary); }
.todo-card__spinner {
  display: inline-block; width: 14px; height: 14px;
  border: 2px solid var(--el-color-primary);
  border-top-color: transparent; border-radius: 50%;
  animation: spin 1s linear infinite;
}
```

### 6.3 chat.vue 布局

```vue
<div class="chat-messages" ref="messagesRef">
  <!-- 历史消息 -->
  <message-item v-for="msg in displayMessages" :key="msg.id" :message="msg" />

  <!-- Todo 卡片 -->
  <todo-card v-if="todoItems.length" :items="todoItems" :summary="todoSummary" />

  <!-- Skill 执行卡片 -->
  <skill-card v-for="sp in skillProgress" :key="sp.name" v-bind="sp" />

  <!-- 流式 assistant 消息 -->
  <message-item v-if="streamingMsg" :message="streamingMsg" />
</div>
```

## 7. 思考内容流式展示

### 7.1 问题现状

当前 Neta 后端已有的基础：
- `runtime/thinking.ts`：`resolveThinkingDefault(model)`、`isThinkingSupported(model)`、`ThinkLevel` 类型
- `plugins/plugin_entry.ts`：`LLMProviderConfig` 包含 `thinkLevel?: ThinkLevel`
- `plugins/llm_providers/anthropic.ts`：能提取 `block.type === 'thinking'` 块
- `plugins/llm_providers/openai.ts`：能提取 `reasoning_content` 字段
- `runtime/attempt.ts`：有 `onThinking?.(response.thinking)` 回调

缺失的部分：
- 适配器未将思考参数传递给 LLM API（Anthropic 没传 `thinking_budget`，OpenAI 没传 `reasoning_effort`）
- 前端不是流式展示思考内容
- 没有思考级别控制 UI
- 没有多模型统一适配层

### 7.2 后端：思考流式推送

将当前的一次性 `thinking` 事件改为流式 `thinking_delta`：

```typescript
// 新增 WS 事件
type: 'thinking_delta'   // 增量文本片段
data: { text: string }

type: 'thinking_done'    // 思考结束标记
data: {}

// 废弃
type: 'thinking'         // 被 thinking_delta + thinking_done 替代
```

**当前限制：** 现有 LLM 适配器（anthropic.ts/openai.ts）使用非流式 API 调用，`attempt.ts:38` 的 `onThinking?.(response.thinking)` 是一次性返回完整 thinking 文本。因此本次实现中 `thinking_delta` 实际为"收到即推"（一次性推送完整文本），而非逐字流式。前端组件已按流式设计，后续迭代将 LLM 适配器改为 streaming 模式后可无缝升级为真正逐字流式。

### 7.3 前端 store 改动

```typescript
// 新增状态
const isThinking = ref(false);
const thinkingStream = ref('');

case 'thinking_delta': {
  if (!isThinking.value) {
    isThinking.value = true;
    thinkingStream.value = '';
  }
  thinkingStream.value += event.data.text;
  break;
}

case 'thinking_done': {
  isThinking.value = false;
  if (assistantMsg) {
    assistantMsg.thinking = thinkingStream.value;
  }
  break;
}

// 正文 token 到达时自动结束思考状态
case 'token': {
  if (isThinking.value) {
    isThinking.value = false;
    if (assistantMsg) {
      assistantMsg.thinking = thinkingStream.value;
    }
  }
  // ...原有追加 content 逻辑
}
```

### 7.4 thinking-block.vue 组件

参考 openclaw 的视觉设计（虚线边框 + 半透明背景 + 呼吸动画）：

```vue
<template>
  <div class="thinking-block" :class="{ 'is-streaming': isStreaming }">
    <div class="thinking-block__header" @click="collapsed = !collapsed">
      <el-icon :class="{ 'is-rotating': isStreaming }">
        <Loading v-if="isStreaming" />
        <InfoFilled v-else />
      </el-icon>
      <span class="thinking-block__title">思考过程</span>
      <el-icon class="thinking-block__toggle">
        <ArrowUp v-if="!collapsed" /><ArrowDown v-else />
      </el-icon>
    </div>

    <el-collapse-transition>
      <div v-if="!collapsed" class="thinking-block__content" ref="contentRef">
        <div v-html="renderedMarkdown" />
        <span v-if="isStreaming" class="thinking-block__cursor" />
      </div>
    </el-collapse-transition>
  </div>
</template>
```

交互行为：
- 流式思考中：默认展开，内容逐字出现，末尾闪烁光标
- 思考完成后：自动折叠（CSS transition 0.3s），用户可点击重新展开
- 历史消息中的思考：默认折叠

CSS 样式（参考 openclaw `chat-thinking`）：

```css
.thinking-block {
  margin: 8px 0;
  padding: 10px 12px;
  border-radius: 8px;
  border: 1px dashed var(--el-border-color);
  background: var(--el-fill-color-lighter);
  font-size: 12px;
  line-height: 1.5;
  color: var(--el-text-color-secondary);
  transition: all 0.3s ease;
}

.thinking-block.is-streaming {
  animation: thinking-pulse 1.5s ease-in-out infinite;
}

@keyframes thinking-pulse {
  0%, 100% { border-color: var(--el-border-color); }
  50% { border-color: var(--el-color-primary-light-3); }
}

.thinking-block__cursor {
  display: inline-block;
  width: 2px; height: 14px;
  background: var(--el-color-primary);
  animation: blink 1s step-end infinite;
  vertical-align: text-bottom;
  margin-left: 2px;
}

@keyframes blink {
  50% { opacity: 0; }
}
```

### 7.5 在 chat.vue 中的位置

思考块嵌入在流式 assistant 消息内部，位于正文之前：

```vue
<message-item v-if="streamingMsg" :message="streamingMsg">
  <template #before-content>
    <thinking-block
      v-if="thinkingStream || streamingMsg.thinking"
      :content="isThinking ? thinkingStream : streamingMsg.thinking"
      :is-streaming="isThinking"
    />
  </template>
</message-item>
```

历史消息中同理，`message-item.vue` 检测 `msg.thinking` 字段渲染 `thinking-block`（默认折叠）。

## 8. 多模型思考适配层（后端）

参考 hermes 的多模型统一适配架构，补全 Neta 后端的思考参数传递链路。

### 8.1 统一思考配置接口

文件：`packages/backend/src/modules/netaclaw/runtime/thinking.ts`（已有，需扩展）

```typescript
// 已有的 ThinkLevel 类型
type ThinkLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'adaptive';

// 新增：各提供商的思考预算映射（参考 hermes THINKING_BUDGET）
const ANTHROPIC_BUDGET_MAP: Record<string, number> = {
  minimal: 2000,
  low: 4000,
  medium: 8000,
  high: 16000,
};

// 新增：Anthropic adaptive effort 映射（参考 hermes ADAPTIVE_EFFORT_MAP）
const ANTHROPIC_ADAPTIVE_MAP: Record<string, string> = {
  minimal: 'low',
  low: 'low',
  medium: 'medium',
  high: 'high',
  adaptive: 'medium',  // adaptive 模式下由模型自行决定
};

// 新增：检测模型是否支持 adaptive thinking（Claude 4.6+）
function supportsAdaptiveThinking(model: string): boolean {
  return /4[-.]6/.test(model);
}

// 新增：构建各提供商的思考参数
interface ThinkingParams {
  anthropic?: {
    thinking: { type: string; budget_tokens?: number; effort?: string };
    temperature?: number;
    maxTokensAdjust?: number;
    betas?: string[];
  };
  openai?: {
    reasoning_effort?: string;
    reasoning?: { enabled: boolean; effort?: string };
  };
}

function buildThinkingParams(
  supplier: string,
  model: string,
  level: ThinkLevel
): ThinkingParams {
  if (level === 'off') return {};

  const params: ThinkingParams = {};

  switch (supplier) {
    case 'anthropic': {
      if (supportsAdaptiveThinking(model)) {
        // Claude 4.6：adaptive thinking
        params.anthropic = {
          thinking: { type: 'adaptive' },
          betas: ['interleaved-thinking-2025-05-14'],
        };
        // adaptive 模式下通过 output_config.effort 控制
      } else {
        // 旧模型：手动 budget
        const budget = ANTHROPIC_BUDGET_MAP[level] || 8000;
        params.anthropic = {
          thinking: { type: 'enabled', budget_tokens: budget },
          temperature: 1.0,
          maxTokensAdjust: budget + 4096,
          betas: ['interleaved-thinking-2025-05-14'],
        };
      }
      break;
    }

    case 'openai':
    case 'deepseek': {
      // OpenAI 兼容：reasoning_effort 直接传递
      // 支持 o1/o3/deepseek-r1 等模型
      const effortMap: Record<string, string> = {
        minimal: 'low', low: 'low', medium: 'medium', high: 'high',
      };
      params.openai = {
        reasoning_effort: effortMap[level] || 'medium',
        reasoning: { enabled: true, effort: effortMap[level] || 'medium' },
      };
      break;
    }

    default: {
      // 其他提供商：不传思考参数，依赖模型自身行为
      break;
    }
  }

  return params;
}
```

### 8.2 Anthropic 适配器改动

文件：`plugins/llm_providers/anthropic.ts`

```typescript
// 当前：只提取思考块，没传思考参数
// 改为：根据 config.thinkLevel 构建并传递参数

import { buildThinkingParams, supportsAdaptiveThinking } from '../../runtime/thinking';

// 在构建 API 请求时：
const thinkParams = buildThinkingParams('anthropic', model, config.thinkLevel || 'off');

if (thinkParams.anthropic) {
  requestBody.thinking = thinkParams.anthropic.thinking;
  
  if (thinkParams.anthropic.temperature !== undefined) {
    requestBody.temperature = thinkParams.anthropic.temperature;
  }
  if (thinkParams.anthropic.maxTokensAdjust) {
    requestBody.max_tokens = Math.max(requestBody.max_tokens, thinkParams.anthropic.maxTokensAdjust);
  }
  
  // Beta headers
  if (thinkParams.anthropic.betas?.length) {
    headers['anthropic-beta'] = thinkParams.anthropic.betas.join(',');
  }
}

// 流式响应中提取 thinking_delta：
// 当收到 type === 'thinking_delta' 的 SSE 事件时
// 立即通过 onThinkingDelta?.(delta.thinking) 回调推送给 WS 层
```

### 8.3 OpenAI 适配器改动

文件：`plugins/llm_providers/openai.ts`

```typescript
import { buildThinkingParams } from '../../runtime/thinking';

const thinkParams = buildThinkingParams(config.supplier, model, config.thinkLevel || 'off');

if (thinkParams.openai) {
  // OpenAI / DeepSeek：通过 extra_body 传递
  requestBody.reasoning_effort = thinkParams.openai.reasoning_effort;
  // 或通过 reasoning 对象（部分提供商）
  // requestBody.reasoning = thinkParams.openai.reasoning;
}

// 流式响应中提取 reasoning delta：
// 检查 delta.reasoning_content 或 delta.reasoning 字段
// 通过 onThinkingDelta?.(text) 回调推送
```

### 8.4 Agent 运行时：会话级思考级别

文件：`runtime/agent.ts`

```typescript
// 当前：只用 resolveThinkingDefault(model) 硬编码默认值
// 改为：优先级链
const thinkLevel = session.thinkLevel          // 1. 用户在前端选择的（会话级）
  ?? agent.defaultThinkLevel                    // 2. agent 配置的默认值
  ?? resolveThinkingDefault(model);             // 3. 模型默认值

// 传入 LLMProviderConfig
const llmConfig: LLMProviderConfig = {
  ...baseConfig,
  thinkLevel,
};
```

### 8.5 模型能力检测增强

```typescript
// thinking.ts 扩展

interface ModelThinkingCapability {
  supported: boolean;
  adaptive: boolean;           // 是否支持 adaptive thinking
  levels: ThinkLevel[];        // 支持的级别列表
  defaultLevel: ThinkLevel;    // 默认级别
}

function getModelThinkingCapability(supplier: string, model: string): ModelThinkingCapability {
  // Anthropic Claude 4.6+
  if (supplier === 'anthropic' && supportsAdaptiveThinking(model)) {
    return {
      supported: true, adaptive: true,
      levels: ['off', 'minimal', 'low', 'medium', 'high', 'adaptive'],
      defaultLevel: 'adaptive',
    };
  }
  // Anthropic Claude 3.5/4.5（非 adaptive）
  if (supplier === 'anthropic') {
    return {
      supported: true, adaptive: false,
      levels: ['off', 'low', 'medium', 'high'],
      defaultLevel: 'medium',
    };
  }
  // OpenAI o1/o3
  if (supplier === 'openai' && /^(o1|o3)/.test(model)) {
    return {
      supported: true, adaptive: false,
      levels: ['off', 'low', 'medium', 'high'],
      defaultLevel: 'medium',
    };
  }
  // DeepSeek R1
  if (supplier === 'deepseek' && model.includes('r1')) {
    return {
      supported: true, adaptive: false,
      levels: ['off', 'low', 'medium', 'high'],
      defaultLevel: 'medium',
    };
  }
  // 不支持思考的模型
  return {
    supported: false, adaptive: false,
    levels: ['off'],
    defaultLevel: 'off',
  };
}
```

## 9. 思考级别控制（前端）

### 9.1 WS 协议：动态切换思考级别

```typescript
// 新增客户端→服务端消息
{
  type: 'set_thinking_level',
  data: { level: ThinkLevel }
}

// 后端收到后更新 session.thinkLevel，下次 LLM 调用生效
```

### 9.2 thinking-level-selector.vue

放在输入区域，与 Agent 选择器、附件按钮同行：

```
┌─ 对话区 ────────────────────────────────────────┐
│  消息列表...                                     │
├──────────────────────────────────────────────────┤
│ 输入框                                           │
│                                                  │
│ [Agent] [附件] [💭 中等 ▾]      上下文 32% ● 2K │
└──────────────────────────────────────────────────┘
```

```vue
<template>
  <el-select
    v-model="currentLevel"
    size="small"
    class="thinking-level-selector"
    :disabled="isRunning"
    @change="onLevelChange"
    placeholder="思考级别"
  >
    <el-option
      v-for="opt in availableLevels"
      :key="opt.value"
      :label="opt.label"
      :value="opt.value"
    />
  </el-select>
</template>

<script setup>
// 根据当前模型能力动态生成可选级别
const availableLevels = computed(() => {
  const cap = modelThinkingCapability.value;
  const labelMap = {
    off: '关闭', minimal: '极简', low: '低',
    medium: '中等', high: '高', adaptive: '自适应',
  };
  return cap.levels.map(l => ({ value: l, label: labelMap[l] }));
});
</script>
```

### 9.3 store/chat.ts 新增

```typescript
const thinkLevel = ref<ThinkLevel>('medium');
const modelThinkingCapability = ref<ModelThinkingCapability>({ ... });

function setThinkLevel(level: ThinkLevel) {
  thinkLevel.value = level;
  sendWSMessage({ type: 'set_thinking_level', data: { level } });
}

// 切换会话时恢复
function switchSession(sessionId: string) {
  // ...
  thinkLevel.value = session.thinkLevel ?? 'medium';
}

// 切换模型/Agent 时更新可选级别
function updateModelCapability(supplier: string, model: string) {
  // 通过 API 或本地映射获取模型思考能力
  modelThinkingCapability.value = getModelThinkingCapability(supplier, model);
  // 如果当前级别不在新模型支持范围内，回退到默认值
  if (!modelThinkingCapability.value.levels.includes(thinkLevel.value)) {
    setThinkLevel(modelThinkingCapability.value.defaultLevel);
  }
}
```

## 10. 对话列表适配

`chat-sidebar.vue` 会话项增加摘要行：

```vue
<div class="session-item__subtitle">
  <template v-if="session.todoSummary">
    <span class="session-item__todo-badge">
      📋 {{ session.todoSummary.completed }}/{{ session.todoSummary.total }}
    </span>
  </template>
  <template v-if="session.isRunning">
    <span class="session-item__running-dot" />
    <span>执行中...</span>
  </template>
  <template v-else>
    <span class="session-item__last-msg">{{ session.lastMessage }}</span>
  </template>
</div>
```

## 11. WS 事件协议变更汇总

| 事件类型 | 方向 | 变更 | 数据结构 |
|---------|------|------|---------|
| `todo_update` | 服务端→客户端 | **新增** | `{ todos: TodoItem[], summary: TodoSummary }` |
| `token_update` | 服务端→客户端 | **修改** | 增加 `context: { usedTokens, maxTokens, percent }` |
| `thinking_delta` | 服务端→客户端 | **新增** | `{ text: string }` |
| `thinking_done` | 服务端→客户端 | **新增** | `{}` |
| `set_thinking_level` | 客户端→服务端 | **新增** | `{ level: ThinkLevel }` |
| `thinking` | 服务端→客户端 | **废弃** | 被 `thinking_delta` + `thinking_done` 替代 |
| `skill_start` | 服务端→客户端 | 不变 | — |
| `skill_end` | 服务端→客户端 | 不变 | — |
| `done` | 服务端→客户端 | **修改** | 前端不再清空 skillProgress |

## 12. 完整文件改动清单

### 后端新增
| 文件 | 说明 |
|------|------|
| `modules/netaclaw/runtime/todo_store.ts` | TodoStore 类 |
| `modules/netaclaw/tools/todo_tool.ts` | todo 工具定义 + Schema + handler |

### 后端修改
| 文件 | 说明 |
|------|------|
| `modules/netaclaw/runtime/thinking.ts` | 扩展：`buildThinkingParams()`、`getModelThinkingCapability()`、预算映射常量 |
| `modules/netaclaw/plugins/llm_providers/anthropic.ts` | 传递 `thinking` 参数 + beta headers + 流式 `thinking_delta` 提取 |
| `modules/netaclaw/plugins/llm_providers/openai.ts` | 传递 `reasoning_effort` 参数 + 流式 reasoning delta 提取 |
| `modules/netaclaw/runtime/agent.ts` | 会话级思考级别优先级链、todo 工具注册 |
| `modules/netaclaw/runtime/attempt.ts` | `onThinkingDelta` 回调改为流式推送 |
| ReAct 循环主文件 | todo hydrate、压缩注入、推送 `todo_update` 事件 |
| WS gateway | 处理 `set_thinking_level` 客户端消息、`token_update` 增加 context 字段 |

### 前端新增
| 文件 | 说明 |
|------|------|
| `components/skill-card.vue` | 统一 Skill 卡片 |
| `components/todo-card.vue` | Todo 任务规划卡片 |
| `components/token-stats.vue` | 紧凑 Token 统计组件 |
| `components/thinking-block.vue` | 思考内容流式展示组件 |
| `components/thinking-level-selector.vue` | 思考级别下拉选择器 |

### 前端修改
| 文件 | 说明 |
|------|------|
| `store/chat.ts` | 新增 todo/thinking/thinkLevel 状态、`todo_update`/`thinking_delta`/`thinking_done`/`set_thinking_level` 事件处理、删除本地 token 估算、`done` 不清空 skillProgress |
| `views/chat.vue` | 布局：插入 todo-card + skill-card + thinking-block、token 统计移到输入区、思考级别选择器 |
| `components/message-item.vue` | 删除 Skill 执行历史渲染代码、删除旧思考折叠区块、改用 thinking-block 组件 |
| `components/chat-sidebar.vue` | 会话项增加 todo 进度和运行状态 |
| `hooks/websocket.ts` | 类型定义增加 `todo_update`、`thinking_delta`、`thinking_done`、`set_thinking_level` |
| `types/index.d.ts` | 新增 TodoItem、TodoSummary、ThinkLevel、ModelThinkingCapability 类型 |

### 前端删除
| 文件 | 说明 |
|------|------|
| `components/skill-indicator.vue` | 被 skill-card.vue 替代 |

## 13. 不在本次范围

- 上下文压缩/截断机制（后续迭代）
- 后端 ReAct 循环核心逻辑（只注册新工具 + 接入思考参数，不改执行流程）
- skill-result-viewer 及子组件（skill-card 内部复用）
- 语音对话功能
- Agent 列表和编辑页面
- 思考块签名管理（Anthropic 签名验证/剥离，参考 hermes 但复杂度高，后续迭代）