# 直连模型 Agent 能力 UI 设计

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 状态 | 已实施 |
| 版本 | 0.3 |
| 日期 | 2026-09-03 |
| 设计系统 | [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、独立路由或操作菜单。

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

在现有直连模型工具目录增加“编程能力”分组：

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

要求：

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

## 3. 进程活动块

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

### 3.1 标题与摘要

```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. 截断提示。

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

## 4. Subagent 活动块

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

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

终态：

- 完成：显示有界结果摘要，可展开查看完整返回。
- 失败：保留部分输出和错误。
- 取消：显示“父请求已取消”或准确取消原因。
- 排队：显示当前处于并发队列，不显示虚假百分比。

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

## 5. Ask/Execute 表达

- Ask 中不显示不可用的进程按钮，因为模型工具没有手动调用入口。
- Ask Subagent 活动明确显示“只读”。
- Execute 活动显示“当前用户权限”，不声称 OS 沙箱或工作区隔离。
- 如果用户从 Ask 切到 Execute，只有下一条请求使用新模式；运行中的 Subagent 不切换。

## 6. 错误与通知

- 参数错误、命令退出、Subagent 失败和部分输出属于当前活动上下文，保留在对应活动块。
- Runtime 初始化、Shell 探测或全局服务失败可通过应用通知提示，并在设置状态卡提供重试。
- 同一错误不同时显示活动块副本和通知副本。
- 失败后保留用户 Prompt、命令摘要、工作目录和已有输出。
- 直连模型自动重试通过现有聊天状态显示“模型网络请求失败，正在重试（n/3）”，不增加
  独立按钮、弹窗或通知副本；用户仍可使用当前停止操作取消请求。

## 7. 键盘与无障碍

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

## 8. 响应式

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