docs: design agent workflow thinking panel

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

@@ -0,0 +1,288 @@
+# 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. 阶段标题使用 13-14px，摘要使用 12-13px，避免在聊天侧栏里显得拥挤。
+3. 默认视图只显示阶段标题和一句摘要。
+4. 展开内容使用浅边框或缩进，不使用重卡片嵌套。
+5. 长内容必须换行，文件名和章节名不能撑破聊天框。
+6. 移动或窄宽度下保持单列，不出现横向滚动。
+7. 最终回答区域与过程面板视觉分离，避免用户误以为过程文本属于正文。
+
+## 数据模型
+
+新增显示模型：
+
+```ts
+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. 没有破坏写入确认和现有工具调用逻辑。