QMAI/docs/superpowers/specs/2026-07-02-agent-workflow-thought-process-design.md

Agent 思考过程重构设计

日期：2026-07-02

背景

当前 AI 会话和 AI 大纲中的“思考过程”主要由工具调用记录直接映射成短句列表，信息过于简略。用户需要它更接近 Codex、TRAE Code 等 Agent 工具的过程流：能看到任务阶段、使用技能、调用工具、读取了哪些资料、阶段判断和生成校验，同时这些内容必须可以折叠，不能污染最终回答正文。

本设计只覆盖“思考过程”的展示与轻量数据组织，不改变模型生成正文的业务目标，不自动写入章节或大纲，不放宽写入确认。

目标

1. 思考过程改为纵向 Agent 工作流，而不是简单工具列表。
2. 默认展开当前正在执行的阶段，其余阶段折叠。
3. 显示使用了什么技能、调用了什么工具、读取了什么章节/大纲/记忆/推演。
4. 每个阶段显示一句可读的关键判断，展开后显示该阶段的详细过程。
5. 最终回答保持任务对应格式：章节任务只显示小说章节，细纲任务只显示细纲，大纲任务只显示大纲内容。
6. AI 会话和 AI 大纲都使用同一套过程展示设计。
7. 工具详情保留，但作为技术详情折叠显示，默认不干扰用户阅读。

非目标

1. 不展示模型内部不可控的逐 token 隐私推理，只展示产品可解释的过程摘要、阶段判断和工具证据。
2. 不重构所有 Agent 执行链路。
3. 不改变写入类工具的确认规则。
4. 不把过程文本追加到 message.content。
5. 不做新的多 Agent 编排功能。

推荐方案

采用混合重构方案：

1. 保留现有 toolCalls、contextTrace、ToolCallTimeline。
2. 新增一层轻量的 workflow steps 显示模型，把现有数据组织成用户能理解的阶段。
3. 对少量现有数据无法稳定表达的信息增加显式字段，例如使用技能、阶段判断、结果校验。

这样可以快速做出用户需要的过程流，又避免重做底层工具调用系统。

交互设计

整体结构

新增 AgentWorkflowPanel 作为统一入口，替代当前 AgentToolCallMessage 中的简短步骤列表。

顶部显示：

• 思考过程
• 总状态：运行中、已完成、等待确认、失败
• 任务耗时
• 总阶段数
• 一键展开/收起

主体为纵向过程流，每个阶段是一条可折叠记录。

默认展开规则

1. 有 running 阶段时，自动展开当前运行阶段。
2. 没有运行阶段但有 approval_required 阶段时，展开等待用户确认阶段。
3. 全部完成后，默认折叠所有阶段，只保留摘要。
4. 用户手动展开或折叠后，本条消息内保持用户操作状态。
5. 最终结果已经返回后，不允许仍显示“正在读取”并持续转圈；未结束的工具调用必须被结算为完成、失败或取消。

阶段设计

1. 任务理解

摘要示例：

识别为“生成章节细纲”，需要读取总大纲和目标章节。

展开内容：

• 用户请求类型
• 识别到的任务意图
• 路由来源
• 置信度
• 是否需要加载小说上下文

对于“测试”“你好”这类明显闲聊或测试输入，不应展示复杂上下文加载流程。

2. 使用技能

摘要示例：

应用“章节细纲生成”工作流，约束输出为细纲格式。

展开内容：

• 技能名称
• 技能用途
• 技能来源
• 对输出格式的约束

如果本轮没有显式技能，则显示：

本轮未调用专用技能。

3. 上下文准备

摘要示例：

已读取总大纲、chapter-017、人物记忆 2 条。

展开内容：

• 已读取章节
• 已读取大纲
• 已读取记忆
• 已读取推演
• 已读取历史会话
• 被跳过或无法读取的资料
• 上下文预算和裁剪情况

读取类内容必须显示对象名，例如：

• 读取章节《chapter-017》
• 读取大纲《总大纲》
• 读取记忆《人物设定》

4. 工具调用

摘要示例：

调用 5 个工具，4 个完成，1 个等待确认。

展开内容默认显示中文业务描述：

• 列出所有章节
• 读取章节《chapter-017》
• 读取大纲《总大纲》
• 生成写入草稿，等待用户确认

技术详情继续使用 ToolCallTimeline，放在二级折叠区域：

查看原始工具详情

其中可以看到工具名、参数、返回预览、状态和错误。

5. 思考与决策

摘要示例：

判断本轮应输出章节细纲，不应返回分析报告。

展开内容：

• 为什么需要这些资料
• 当前阶段形成的关键判断
• 输出边界
• 风险提示

这里展示的是产品可解释的过程摘要，不展示不可控的模型隐私推理。

6. 生成与校验

摘要示例：

结果已按“章节细纲”格式校验。

展开内容：

• 期望输出类型：章节、细纲、大纲、记忆、伏笔分析、普通问答
• 实际输出类型
• 是否包含无关分析
• 是否缺少标题、分节、正文、保存确认等必要内容
• 校验警告

如果用户要求“生成小说章节”，最终正文必须是小说章节格式；如果结果变成分析说明，面板需要显示校验异常，方便后续重试或修正。

视觉设计

参考 TRAE/Codex 风格，采用轻量纵向过程流，而不是大面积蓝底卡片列表。

禁止的呈现方式

当前截图中的样式必须废弃：

1. 不使用整块浅蓝色背景包住全部思考过程。
2. 不把每一步做成一条圆角浅蓝卡片。
3. 不重复显示大量同类卡片，例如连续多条“整理资料范围”。
4. 不把过程区做成像表单列表、通知列表或日志面板。
5. 不让“工具详情”按钮成为视觉重点。

这类样式显得老旧，并且会把简单过程放大成沉重的信息块。

新呈现方式

采用“文本过程流 + 细分隔 + 局部展开”的样式：

1. 外层背景保持透明或接近聊天背景，只用左侧细线、轻量图标和小标题组织层级。
2. 每个阶段默认是一行过程摘要，视觉上像 Agent 正在汇报工作，而不是像卡片列表。
3. 当前运行阶段可以有非常轻的背景高亮，但不能使用整行大圆角卡片堆叠。
4. 阶段之间使用留白和细分隔，不使用厚边框。
5. 已完成阶段显示为简洁文本，例如：已读取 1 个章节，2 条记忆，1 个大纲。
6. 正在执行阶段显示一句自然语言，例如：正在读取章节《chapter-017》。
7. 展开内容在阶段下方缩进显示，使用小号文本和项目符号，不再套一层卡片。
8. 技术工具名默认隐藏，放入“查看工具详情”的二级折叠区。

信息密度

1. 阶段标题使用 13-14px，摘要使用 12-13px，避免在聊天侧栏里显得拥挤。
2. 默认视图只显示阶段标题和一句摘要。
3. 同类工具调用需要合并摘要，例如多次 list_* 合并为“整理资料范围”，不要重复刷屏。
4. 读取类工具可以在展开内容里逐条列出目标对象。
5. 长内容必须换行，文件名和章节名不能撑破聊天框。
6. 移动或窄宽度下保持单列，不出现横向滚动。
7. 最终回答区域与过程面板视觉分离，避免用户误以为过程文本属于正文。

推荐视觉结构

示例：

思考过程  ·  任务耗时 1m 4s

任务理解  >
识别为章节细纲生成，需要读取大纲与目标章节。

上下文准备  v
正在读取章节《chapter-017》
  - 已读取大纲《总大纲》
  - 已读取记忆《人物设定》
  - 已读取章节《chapter-017》

生成与校验  >
将按章节细纲格式输出，正文区不显示过程分析。

这个结构的重点是“像 Agent 在汇报处理进度”，不是“把每个工具调用包装成一个卡片”。

数据模型

新增显示模型：

type AgentWorkflowStepStatus =
  | "pending"
  | "running"
  | "done"
  | "approval_required"
  | "error"
  | "cancelled"

interface AgentWorkflowStep {
  id: string
  kind:
    | "intent"
    | "skill"
    | "context"
    | "tool"
    | "decision"
    | "validation"
  title: string
  summary: string
  status: AgentWorkflowStepStatus
  details: AgentWorkflowDetail[]
  startedAt?: number
  finishedAt?: number
}

interface AgentWorkflowDetail {
  label: string
  value: string
  tone?: "default" | "muted" | "warning" | "error" | "success"
}

该模型是 UI 显示层，不替代底层工具调用记录。

数据来源

AI 会话

组合来源：

• message.agentToolCalls
• message.contextTrace
• contextTrace.contextInfo
• contextTrace.toolCalls
• contextTrace.contextInfo.resultProtocol

AI 大纲

第一阶段组合来源：

• outlineChat 的工具调用记录
• 大纲引用、读取和写入工具的参数

后续如 AI 大纲需要更完整的上下文追踪，再补齐 contextTrace 数据接入。

文件影响范围

预计修改或新增：

• src/components/chat/agent-tool-call-message.tsx
• src/components/chat/tool-call-timeline.tsx
• src/components/chat/chat-message.tsx
• src/components/sources/outline-chat-panel.tsx
• src/lib/agent/workflow-trace.ts
• src/components/chat/agent-workflow-panel.tsx

预计测试：

• src/components/chat/agent-tool-call-message.spec.tsx
• src/components/chat/chat-message.spec.tsx
• src/components/sources/outline-chat-panel.spec.tsx
• src/lib/agent/workflow-trace.spec.ts

错误与边界处理

1. 工具调用缺少参数时，显示通用描述，不暴露 undefined。
2. 资料读取失败时，阶段状态为失败，并显示失败对象和错误摘要。
3. 最终结果完成后，仍处于 running 的工具调用必须被结算，防止转圈残留。
4. 写入类工具必须保留等待用户确认状态，不允许面板触发自动保存。
5. 没有任何工具记录时，不显示空面板。
6. 技术详情中的原始参数过长时只显示预览，避免撑破界面。

测试与验证

1. 单元测试：从 toolCalls 和 contextTrace 生成正确的工作流阶段。
2. 组件测试：当前运行阶段默认展开，其余折叠。
3. 组件测试：读取章节、读取大纲、读取记忆显示具体对象名。
4. 组件测试：最终完成后不显示运行中图标。
5. 组件测试：写入类工具显示等待确认，并保留确认/拒绝操作。
6. 回归测试：最终回答内容不包含思考过程文本。
7. 视觉验证：AI 会话窄宽度和 50% 宽度下内容不溢出。
8. 构建验证：运行项目已有 typecheck、相关 mock 测试和 build。

成功标准

1. 用户能像在 Codex/TRAE 中一样看到阶段化过程流。
2. 当前执行阶段自动展开，已完成阶段默认折叠。
3. 读取了哪个章节、哪个记忆、哪个大纲能清楚显示。
4. 使用技能和工具调用能在过程里看到。
5. 最终正文保持干净，不混入过程分析。
6. AI 会话和 AI 大纲表现一致。
7. 没有破坏写入确认和现有工具调用逻辑。
8. 思考过程不再使用整块蓝底加多条圆角卡片的老式列表样式。