# 直连模型 Agent 能力 UI 设计

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 状态 | 已实施 |
| 版本 | 0.4 |
| 日期 | 2026-09-09 |
| 设计系统 | [GoodBuddy 统一界面设计系统](../../../UI-DESIGN.md) |
| 关联 PRD | [PRD](./prd.md) |
| 关联逻辑 | [功能逻辑设计](./logic-design.md) |

## 1. 信息架构

本功能不增加一级页面、Composer 按钮或 Runtime 专属工具栏。用户主要通过三处理解能力：

1. **设置 > MCP > 直连模型**：查看工作区文件和开发工具说明。
2. **聊天消息活动块**：查看命令和 Subagent 的实时状态与结果。
3. **运行记录**：按当前 Conversation 或 Task 查看聚合执行活动。

Job、Subjob 和 Run 继续是内部对象，不创建树形 UI、独立路由或操作菜单。

本地直连文本会话复用输入区已有的“压缩上下文”按钮，不依赖原生 Runtime 快照，
也不因自动压缩关闭或上下文低于触发阈值而隐藏。运行中或压缩中按钮禁用；图像连接、
远程通道会话和 SSH 项目不显示直连模型压缩入口。完成后沿用应用通知及压缩后上下文估算，
摘要随会话保存。压缩行为见[技术设计](./technical-design.md#101-本地直连手动压缩)。

## 2. 设置中的能力目录

直连模型工具目录使用两个本机开发分组：

```text
工作区文件
  搜索工作区
  读取工作区文本
  应用工作区补丁

开发工具
  进程执行
  使用当前用户权限运行 PowerShell、Bash 或 Sh 命令，默认在工作区执行，也可指定其他工作目录。
  编程 Subagent
  将聚焦任务委派给同一模型连接；继承当前能力范围和工作区。
```

要求：

- 这些工具默认属于直连模型，不提供持久 Switch。
- 设置目录只定义稳定工具能力，不增加 Shell 状态或重试控件；实际 Shell 标签在模型工具
  定义和进程结果中返回。
- Runtime 是 OpenCode、Continue 或 DeepSeek Harness 时，不在其原生能力清单中伪造这两项；
  用户需要理解差异时，在直连模型分组说明“Agent Runtime 使用自身工具”。
- 不把模型配置检查成功描述为命令或 Subagent 已经通过真实执行验证。

## 3. 进程活动块

复用现有对话工具活动视觉和语义，不创建页面专属卡片系统。

### 3.1 标题与摘要

正常执行状态的操作摘要遵循[工具操作摘要规则](../assistant-workbar/runtime-interactions.md#工具操作摘要)，从原始调用参数提取并在完成后保留；异常状态继续显示原有提示。

```text
进程执行
PowerShell · packages/app · npm test
```

- 命令只显示单行有界摘要，完整参数进入可展开详情。
- 工作区内目录显示相对路径，工作区根显示 `.`；工作区外目录显示规范化绝对路径。
- 不在摘要中显示完整环境或凭据。

### 3.2 状态

| 状态 | 文案 |
| --- | --- |
| pending | 等待运行 |
| running | 正在运行 |
| completed，exit 0 | 已完成 |
| completed，exit 非零 | 工具已完成，详情显示退出码 N |
| timeout | 工具已完成，详情显示 timeout |
| cancelled | 父请求活动显示已取消 |
| failed | 启动失败 |

状态必须同时有文字和状态图标，不能只依靠颜色。非零退出属于正常结构化工具结果，不显示为
GoodBuddy 服务崩溃。

### 3.3 结果详情

详情按以下顺序展示：

1. Shell、工作目录、耗时和退出码。
2. stdout。
3. stderr。
4. 预览省略提示与工具结果中的续读引用。

日志使用共享等宽字体和可选择文本。长输出在活动块内折叠，展开后仍保持工作栏和聊天布局
可用；不把完整日志复制为应用通知。

模型使用 `output_read` 续读时显示普通工具活动“续读工具输出”。活动展开只展示该次返回的
摘要，不等同于自动加载完整日志；当前不增加手动分页按钮。

## 4. Subagent 活动块

复用现有 `subagent` 消息块，并将系统执行者显示为“编程 Subagent”，不要求用户预先创建
专家。

```text
编程 Subagent
检查认证模块的测试失败并提出修复
正在运行 · 直连模型
```

终态：

- 完成：显示有界结果摘要，可展开查看当前预览；完整正文由模型通过输出续读工具取得。
- 失败：保留部分输出和错误。
- 取消：显示“父请求已取消”或准确取消原因。
- 排队：显示当前处于并发队列，不显示虚假百分比。

活动块不提供单独的“批准”“提高权限”或“继续递归”按钮。用户取消父请求即可取消子级。

## 5. 执行能力表达

- 模型工具没有手动调用入口，不显示模式按钮或子代理模式徽标。
- 工具使用当前用户权限，不声称 OS 沙箱或工作区隔离。
- 能力配置变更按既有生命周期作用于后续请求，运行中的 Subagent 保留请求归属。

## 6. 错误与通知

- 参数错误、命令退出、Subagent 失败和部分输出属于当前活动上下文，保留在对应活动块。
- Runtime 初始化、Shell 探测或全局服务失败可通过应用通知提示，并在设置状态卡提供重试。
- 同一错误不同时显示活动块副本和通知副本。
- 失败后保留用户 Prompt、命令摘要、工作目录和已有输出。
- 直连模型自动重试在消息底部区分“模型网络请求失败，等待重试（n/3，s 秒后）”与
  “〈模型名〉正在重试请求（n/3），等待响应”；只有退避结束且未取消才显示后者。
  初始请求显示“〈模型名〉请求处理中”，不把尚无输出的等待描述成思考。
- 不增加独立按钮、弹窗或通知副本；用户仍可使用当前停止操作取消请求。
  底部静态状态点、工具进展、待回答及终态优先规则由
  [消息底部请求状态](../assistant-workbar/runtime-interactions.md#消息底部请求状态)统一定义。

## 7. 键盘与无障碍

- 活动块展开按钮使用原生 `button`，提供 `aria-expanded` 和关联详情 ID。
- 状态变化通过现有活动区域的礼貌级 live region 发布，不逐个朗读流式日志。
- stdout/stderr 区域具有可见标签，不能只靠顺序区分。
- 焦点不会因后台状态更新自动移动。
- 取消父请求后的焦点保持在原取消按钮或恢复到 Composer。
- 浅色、深色和减少动态效果模式遵守统一设计系统。

## 8. 响应式

- 窄聊天区只保留工具名、状态和一行摘要，元数据换行到下一行。
- 日志区域横向滚动，不撑宽页面。
- 运行记录使用紧凑摘要，不复制完整 stdout/stderr；用户回到聊天活动块展开查看详情。