Agent: components 261-280
This commit is contained in:
108 files changed
+6363
-7
No files matched your search
@@ -0,0 +1,47 @@
|
||||
# 261 ToolCallCard 工具调用卡片
|
||||
|
||||
## 用途
|
||||
|
||||
显示一次工具调用：工具名、状态、耗时，参数与结果可折叠，JSON 自动格式化并高亮。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
call := mujica.ToolCall{ID: "1", Name: "read_file", Args: "{\"path\":\"ledger.md\"}",
|
||||
Result: "{\"lines\":40}", State: mujica.AgentDone, Duration: 420 * time.Millisecond}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
mujica.ToolCallCard(c, call, mujica.ToolCallCardOptions{OpenArgs: true})
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func ToolCallCard(c *ui.Context, call ToolCall, opts ToolCallCardOptions) ChoiceResult`。`call.Name` 为空时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `OpenArgs` | `bool` | `false` | 参数区初始展开。 |
|
||||
| `OpenResult` | `bool` | `false` | 结果区初始展开。 |
|
||||
| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- `ToolCall` 字段：`ID`、`Name`、`Args`（JSON 或纯文本）、`Result`、`Error`（非空时替代结果并以错误色显示）、`State`、`Duration`。
|
||||
- `AgentState`：`AgentPending`、`AgentPlanning`、`AgentRunning`、`AgentWaiting`、`AgentDone`、`AgentFailed`、`AgentSkipped`，越界 panic。状态同时由图标形状和文字表达，不只靠颜色。
|
||||
- 仅完成或失败时显示耗时；合法 JSON 以两格缩进格式化，非 JSON 原样显示。
|
||||
- 结果超过 200 行时虚拟化，只构建可见行。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Changed()`：用户展开或折叠参数、结果。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 到“参数”“结果”折叠按钮，Enter / Space 展开或折叠。
|
||||
|
||||
## 限制
|
||||
|
||||
- 展开状态保存在卡片元素上；在列表中请用稳定 `Key` 包裹每张卡片。
|
||||
- 高亮只区分关键字、字符串、数字和标点，不做 JSON 结构校验提示。
|
||||
@@ -0,0 +1,47 @@
|
||||
# 262 ToolCallGroup 工具调用组
|
||||
|
||||
## 用途
|
||||
|
||||
把连续的工具调用折叠成一组，标题行显示调用次数、总耗时与失败数。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
open := false
|
||||
calls := []mujica.ToolCall{
|
||||
{ID: "a", Name: "list_dir", State: mujica.AgentDone, Duration: 300 * time.Millisecond},
|
||||
{ID: "b", Name: "read_file", State: mujica.AgentFailed, Error: "not found"},
|
||||
}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
mujica.ToolCallGroup(c, &open, calls, mujica.ToolCallGroupOptions{})
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func ToolCallGroup(c *ui.Context, open *bool, calls []ToolCall, opts ToolCallGroupOptions) ChoiceResult`。`open` 为 nil、调用 `ID` 为空或重复时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Title` | `string` | “N 次工具调用” | 替换内置标题。 |
|
||||
| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- 组的状态：有调用执行中为执行中，否则有失败为失败，否则为完成。
|
||||
- 失败数以文字“N 次失败”显示。
|
||||
- 展开后每次调用用 ToolCallCard 显示。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Changed()`：用户展开或折叠该组。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 到组标题，Enter / Space 展开或折叠；组内卡片各自可折叠。
|
||||
|
||||
## 限制
|
||||
|
||||
- 总耗时是各调用耗时之和，不扣除并行重叠。
|
||||
@@ -0,0 +1,51 @@
|
||||
# 263 ToolApprovalDialog 工具审批对话框
|
||||
|
||||
## 用途
|
||||
|
||||
工具执行前请求批准：显示工具名、执行理由和参数预览，允许或拒绝。遵循 Dialog 与 AlertDialog 规则。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
open := true
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
r := mujica.ToolApprovalDialog(c, &open, mujica.ToolApprovalOptions{
|
||||
Tool: "delete_files", Args: "{\"glob\":\"*.tmp\"}", Reason: "Clean the build folder.",
|
||||
})
|
||||
if r.Allowed {
|
||||
fmt.Println("run the tool")
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func ToolApprovalDialog(c *ui.Context, open *bool, opts ToolApprovalOptions) ToolApprovalResult`。`Tool` 为空时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Tool` | `string` | 必填 | 工具名。 |
|
||||
| `Args` | `string` | `""` | 参数，合法 JSON 会格式化高亮。 |
|
||||
| `Reason` | `string` | `""` | Agent 给出的理由，作为对话框说明。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- 打开时焦点在“拒绝”；点击遮罩不做任何事。
|
||||
- 参数过长时在预览区内滚动，按钮始终可见。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Allowed`：点击允许，或焦点在允许上按 Enter / Space。
|
||||
- `Denied`：点击拒绝、焦点在拒绝上按 Enter、或按 Escape。
|
||||
- `Element`：对话框面板，关闭时为 nil。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- 打开时焦点在拒绝，Enter 只触发聚焦按钮，必须 Tab 到“允许”才能批准。
|
||||
- Escape 等同拒绝；Tab 在对话框内循环；关闭后焦点回到打开者。
|
||||
|
||||
## 限制
|
||||
|
||||
- 输入法组合期间按 Escape 仍会拒绝（MyGo 不公开组合状态，`ui/editor.go:73`）。
|
||||
@@ -0,0 +1,48 @@
|
||||
# 264 PermissionPrompt 权限请求
|
||||
|
||||
## 用途
|
||||
|
||||
请求权限：允许一次、始终允许或拒绝，并说明“始终允许”覆盖的范围。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
open := true
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
r := mujica.PermissionPrompt(c, &open, mujica.PermissionPromptOptions{
|
||||
Title: "Write to the ledger?", Scope: "Write access to ~/court/ledger",
|
||||
})
|
||||
if r.Choice == mujica.PermissionAllowAlways {
|
||||
fmt.Println("remember the grant")
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func PermissionPrompt(c *ui.Context, open *bool, opts PermissionPromptOptions) PermissionResult`。`Title` 或 `Scope` 为空时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Title` | `string` | 必填 | 问题。 |
|
||||
| `Description` | `string` | `""` | 补充说明。 |
|
||||
| `Scope` | `string` | 必填 | “始终允许”覆盖的范围。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- 范围说明放在带锁形图标的框内。
|
||||
- 打开时焦点在“拒绝”，点击遮罩无效。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Choice`：本帧的选择，`PermissionAllowOnce`、`PermissionAllowAlways`、`PermissionDeny`；无选择为 `PermissionNone`。Escape 记为拒绝。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- 打开时焦点在拒绝；Tab 依次到“始终允许”“允许一次”；Enter 触发聚焦按钮；Escape 拒绝。
|
||||
|
||||
## 限制
|
||||
|
||||
- 组件不保存授权，记住“始终允许”由调用方负责。
|
||||
@@ -0,0 +1,51 @@
|
||||
# 265 AgentStepList 执行步骤列表
|
||||
|
||||
## 用途
|
||||
|
||||
以时间线显示 Agent 的执行步骤：当前步加框标出，步骤可展开详情，失败步提供重试。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
steps := []mujica.AgentStep{
|
||||
{ID: "read", Title: "Read the guest list", State: mujica.AgentDone, Duration: time.Second},
|
||||
{ID: "seat", Title: "Assign the seats", State: mujica.AgentFailed, Detail: "Table 4 is full."},
|
||||
{ID: "send", Title: "Send invitations", State: mujica.AgentPending},
|
||||
}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if r := mujica.AgentStepList(c, steps, mujica.AgentStepListOptions{}); r.Retry != "" {
|
||||
fmt.Println("retry", r.Retry)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func AgentStepList(c *ui.Context, steps []AgentStep, opts AgentStepListOptions) AgentStepListResult`。步骤 `ID` 为空或重复、`Title` 为空时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Disabled` | `bool` | `false` | 禁止展开与重试。 |
|
||||
| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- `AgentStep` 字段：`ID`、`Title`、`Detail`、`State`、`Duration`。
|
||||
- `AgentState`：`AgentPending`、`AgentPlanning`、`AgentRunning`、`AgentWaiting`、`AgentDone`、`AgentFailed`、`AgentSkipped`，越界 panic。状态同时由图标形状和文字表达，不只靠颜色。
|
||||
- 当前步是第一个执行中、等待或规划中的步骤，用选中底色、边框和“当前”文字标出。
|
||||
- 失败步下方显示“重试”。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Toggled`：本帧展开或折叠的步骤 ID。
|
||||
- `Retry`：本帧请求重试的步骤 ID。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 进入列表；↑ ↓ 在步骤与重试按钮间移动；Enter / Space 展开详情或重试。
|
||||
|
||||
## 限制
|
||||
|
||||
- 步骤数量较少时使用；列表不虚拟化。
|
||||
@@ -0,0 +1,49 @@
|
||||
# 266 AgentPlan 执行计划
|
||||
|
||||
## 用途
|
||||
|
||||
显示 Agent 的计划清单与进度：随 Agent 实时勾选，用户可勾选、跳过、恢复和新增项。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
items := []mujica.PlanItem{
|
||||
{ID: "a", Text: "Read the guest list", State: mujica.AgentDone},
|
||||
{ID: "b", Text: "Assign the seats", State: mujica.AgentRunning},
|
||||
{ID: "c", Text: "Order the flowers"},
|
||||
}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
mujica.AgentPlan(c, &items, mujica.AgentPlanOptions{})
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func AgentPlan(c *ui.Context, items *[]PlanItem, opts AgentPlanOptions) ChoiceResult`。`items` 为 nil、项 `ID` 重复或状态不是待办、进行中、完成、跳过之一时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Title` | `string` | “计划” | 标题。 |
|
||||
| `Disabled` | `bool` | `false` | 只读显示，隐藏跳过与新增。 |
|
||||
| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- `PlanItem` 字段：`ID`、`Text`、`State`（`AgentPending`、`AgentRunning`、`AgentDone`、`AgentSkipped`）。
|
||||
- 进度为“已完成 / 未跳过总数”，以文字和细进度条显示。
|
||||
- 跳过的项加删除线并禁用勾选；进行中的项显示“进行中”。
|
||||
- 新增项的 ID 自动生成为未使用的 `item-N`。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Changed()`：用户勾选、跳过、恢复或新增了项，`*items` 已更新。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 到每项的勾选框（Space 切换）、跳过或恢复按钮；在新增输入框中按 Enter 添加。
|
||||
|
||||
## 限制
|
||||
|
||||
- 空白内容不会被添加。
|
||||
@@ -0,0 +1,41 @@
|
||||
# 267 AgentStatus Agent 状态
|
||||
|
||||
## 用途
|
||||
|
||||
显示 Agent 当前状态：规划中、执行中、等待、完成、失败，用图标形状和文字表达，不只靠颜色。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
mujica.AgentStatus(c, mujica.AgentWaiting, mujica.AgentStatusOptions{})
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func AgentStatus(c *ui.Context, state AgentState, opts AgentStatusOptions) *ui.Element`。未知状态 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Label` | `string` | 内置状态词 | 替换显示的文字。 |
|
||||
| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- `AgentState`：`AgentPending`、`AgentPlanning`、`AgentRunning`、`AgentWaiting`、`AgentDone`、`AgentFailed`、`AgentSkipped`，越界 panic。状态同时由图标形状和文字表达，不只靠颜色。
|
||||
- 执行中显示旋转的菱形；`Still` 或系统减少动画时改为静态图标。
|
||||
|
||||
## 事件
|
||||
|
||||
- 无事件；屏幕阅读器以状态角色读出文字。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- 不获取焦点。
|
||||
|
||||
## 限制
|
||||
|
||||
- 状态动画只在显示时重绘，隐藏后停止。
|
||||
@@ -0,0 +1,42 @@
|
||||
# 268 AgentProgress Agent 进度
|
||||
|
||||
## 用途
|
||||
|
||||
显示整体进度和当前动作文字；时长未知时用不确定模式。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
mujica.AgentProgress(c, 0.4, mujica.AgentProgressOptions{Action: "Reading ledger.md"})
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func AgentProgress(c *ui.Context, value float64, opts AgentProgressOptions) *ui.Element`。确定模式下 `value` 不在 0 到 1 时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Label` | `string` | “进度” | 进度名称。 |
|
||||
| `Action` | `string` | `""` | 当前动作，如“正在读取 ledger.md”。 |
|
||||
| `Indeterminate` | `bool` | `false` | 不确定模式，忽略 value。 |
|
||||
| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- 确定模式显示百分比；不确定模式显示流动条，减少动画时为静态条加“进行中”。
|
||||
|
||||
## 事件
|
||||
|
||||
- 无事件；当前动作以状态角色读出。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- 不获取焦点。
|
||||
|
||||
## 限制
|
||||
|
||||
- 进度值由调用方计算。
|
||||
@@ -0,0 +1,45 @@
|
||||
# 269 SubAgentTree 子 Agent 树
|
||||
|
||||
## 用途
|
||||
|
||||
以树显示子 Agent 层级、各自任务与状态，可展开查看下级。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
agents := []mujica.SubAgent{{ID: "lead", Name: "Steward", State: mujica.AgentRunning, Children: []mujica.SubAgent{
|
||||
{ID: "cook", Name: "Cook", Task: "Plan the menu", State: mujica.AgentWaiting},
|
||||
}}}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
mujica.SubAgentTree(c, agents, mujica.SubAgentTreeOptions{})
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func SubAgentTree(c *ui.Context, roots []SubAgent, opts SubAgentTreeOptions) ChoiceResult`。`ID` 为空或重复、`Name` 为空时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Disabled` | `bool` | `false` | 禁止展开与折叠。 |
|
||||
| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- `SubAgent` 字段：`ID`、`Name`、`Task`、`State`、`Children`。
|
||||
- `AgentState`：`AgentPending`、`AgentPlanning`、`AgentRunning`、`AgentWaiting`、`AgentDone`、`AgentFailed`、`AgentSkipped`，越界 panic。状态同时由图标形状和文字表达，不只靠颜色。
|
||||
- 有下级的行显示箭头和“N 个子智能体”。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Changed()`：用户展开或折叠了某个 Agent。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 进入树；↑ ↓ 移动；→ 展开，← 折叠；Enter / Space 切换。
|
||||
|
||||
## 限制
|
||||
|
||||
- 树不虚拟化，适合几十到几百个 Agent。
|
||||
@@ -0,0 +1,48 @@
|
||||
# 270 FileChangeCard 文件变更卡片
|
||||
|
||||
## 用途
|
||||
|
||||
预览一个文件的变更：增删行数、首处修改附近的差异行，提供接受、拒绝和打开完整差异的入口。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
decision := mujica.FilePending
|
||||
change := mujica.FileChange{Path: "ledger.md", Old: "Guests: 40\n", New: "Guests: 42\n"}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if mujica.FileChangeCard(c, &decision, change, mujica.FileChangeCardOptions{}).OpenDiff {
|
||||
fmt.Println("open the full diff")
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func FileChangeCard(c *ui.Context, decision *FileDecision, change FileChange, opts FileChangeCardOptions) FileChangeResult`。`decision` 为 nil、`Path` 为空或 `Preview` 为负时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Preview` | `int` | 8 | 从首处修改前两行起显示的差异行数。 |
|
||||
| `Disabled` | `bool` | `false` | 禁止决定与打开差异。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- `FileChange` 字段：`Path`、`Old`、`New`；`Old` 为空表示新文件，`New` 为空表示删除。
|
||||
- 差异由 `internal.LineDiff`（Myers 行差异）计算，文本不变时只算一次。
|
||||
- 新增行带“+”、删除行带“−”和行号，颜色只是辅助。
|
||||
- 决定状态 `FilePending`、`FileAccepted`、`FileRejected` 以图标和文字显示；已决定后显示“撤销”。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Decided`：`*decision` 被用户改变。
|
||||
- `OpenDiff`：请求调用方打开完整差异。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 依次到“打开差异”“拒绝”“接受”（或“撤销”），Enter / Space 触发。
|
||||
|
||||
## 限制
|
||||
|
||||
- 只做行级差异；词级高亮由 Git 组扩展。
|
||||
@@ -0,0 +1,48 @@
|
||||
# 271 MultiFileDiffReview 多文件差异审阅
|
||||
|
||||
## 用途
|
||||
|
||||
审阅多个文件的变更：左侧文件列表，右侧所选文件的完整差异，逐文件接受或拒绝，全部接受，并显示审阅进度。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
files := []mujica.FileChange{
|
||||
{Path: "ledger.md", Old: "Guests: 40\n", New: "Guests: 42\n"},
|
||||
{Path: "menu.md", Old: "soup\n", New: "soup\ntart\n"},
|
||||
}
|
||||
decisions := make([]mujica.FileDecision, len(files))
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
mujica.MultiFileDiffReview(c, &decisions, files, mujica.MultiFileDiffReviewOptions{})
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func MultiFileDiffReview(c *ui.Context, decisions *[]FileDecision, files []FileChange, opts MultiFileDiffReviewOptions) ChoiceResult`。`decisions` 与 `files` 数量不同、`Path` 为空或重复、`Height` 为负时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Height` | `float32` | 420 | 组件高度。 |
|
||||
| `Disabled` | `bool` | `false` | 禁止选择与决定。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- 进度为“已审阅 N / 总数”，以文字和细进度条显示。
|
||||
- 所选文件用选中底色和左侧竖条标出。
|
||||
- 文件超过 200 个或差异超过 200 行时虚拟化。
|
||||
- “全部接受”只接受尚未决定的文件，全部决定后禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Changed()`：用户改变了任一文件的决定。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 进入文件列表；↑ ↓ 移动，Enter 选择；Tab 到右侧按钮后 Enter 接受或拒绝。
|
||||
|
||||
## 限制
|
||||
|
||||
- 文件很多时方向键只在已构建的可见行间移动，滚动后再继续。
|
||||
@@ -0,0 +1,48 @@
|
||||
# 272 CommandExecutionCard 命令执行卡片
|
||||
|
||||
## 用途
|
||||
|
||||
显示一条命令的执行：命令、工作目录、带 ANSI 颜色的输出、退出码与耗时，执行中可请求中止。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
run := mujica.CommandRun{Command: "go test ./...", Dir: "~/court", Running: true, Output: "\x1b[32mok\x1b[0m court\n"}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if mujica.CommandExecutionCard(c, run, mujica.CommandExecutionCardOptions{}).Changed() {
|
||||
fmt.Println("abort the process")
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func CommandExecutionCard(c *ui.Context, run CommandRun, opts CommandExecutionCardOptions) ChoiceResult`。`Command` 为空或 `Height` 为负时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Height` | `float32` | 240 | 输出区高度。 |
|
||||
| `Disabled` | `bool` | `false` | 禁止中止。 |
|
||||
| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- `CommandRun` 字段：`Command`、`Dir`、`Output`、`Running`、`ExitCode`、`Duration`。
|
||||
- 输出由 `internal.ParseAnsi` 解析，颜色映射到主题；样式可跨行延续；追加输出只解析新增行。
|
||||
- 输出虚拟化并跟随末尾，用户向上滚动后停止跟随。
|
||||
- 退出码以图标和“退出码 N”文字显示。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Changed()`：用户点击了“中止”；终止进程由调用方完成。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 到“中止”，Enter / Space 触发；输出区可滚动。
|
||||
|
||||
## 限制
|
||||
|
||||
- 只支持 SGR 颜色与样式，其它转义序列原样显示。
|
||||
- 不运行命令，也不提供 PTY。
|
||||
@@ -0,0 +1,45 @@
|
||||
# 273 ScreenshotStream Agent 画面流
|
||||
|
||||
## 用途
|
||||
|
||||
查看 Agent 的画面帧序列：默认跟随最新帧，可暂停并逐帧前后查看。帧由调用方提供。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
var st mujica.ScreenshotStreamState
|
||||
var frames []mujica.ScreenshotFrame // appended as the agent captures them
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
mujica.ScreenshotStream(c, &st, frames, mujica.ScreenshotStreamOptions{})
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func ScreenshotStream(c *ui.Context, st *ScreenshotStreamState, frames []ScreenshotFrame, opts ScreenshotStreamOptions) ChoiceResult`。`st` 为 nil、帧没有图像或 `Height` 为负时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Height` | `float32` | 280 | 画面区高度。 |
|
||||
| `Disabled` | `bool` | `false` | 禁止暂停与逐帧。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- `ScreenshotFrame` 字段：`Image`（`ui.ImageSource`）、`Caption`、`At`。
|
||||
- `ScreenshotStreamState` 字段：`Index`、`Paused`；未暂停时 `Index` 总是最后一帧。
|
||||
- 逐帧操作会自动暂停；“回到实时”恢复跟随。
|
||||
- 没有帧时显示“等待画面”。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Changed()`：用户暂停、恢复或移动了帧。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 到画面区：← → 逐帧，Space 暂停或恢复；上一帧、下一帧按钮同样可用。
|
||||
|
||||
## 限制
|
||||
|
||||
- 不解码视频，帧图像由调用方提供。
|
||||
@@ -0,0 +1,47 @@
|
||||
# 274 ArtifactPanel 产物面板
|
||||
|
||||
## 用途
|
||||
|
||||
展示 Agent 生成的产物：代码高亮显示，文档与网页由调用方的预览插槽渲染，可在预览与源码间切换，提供复制与导出。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
art := mujica.Artifact{Title: "seating.go", Language: "go", Content: "package court\n"}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if mujica.ArtifactPanel(c, art, mujica.ArtifactPanelOptions{}).Exported {
|
||||
fmt.Println("save the file")
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func ArtifactPanel(c *ui.Context, art Artifact, opts ArtifactPanelOptions) ArtifactPanelResult`。`Title` 为空、`Kind` 越界、文档或网页缺少 `Preview`、`Height` 为负时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Preview` | `func()` | `nil` | 预览插槽；文档与网页必填。 |
|
||||
| `Height` | `float32` | 320 | 内容区高度。 |
|
||||
| `Disabled` | `bool` | `false` | 禁止复制、导出与切换。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- `Artifact` 字段：`Title`、`Kind`（`ArtifactCode`、`ArtifactDocument`、`ArtifactWeb`）、`Language`、`Content`。
|
||||
- 预览与源码切换用选中底色加勾号标出当前项。
|
||||
- 复制后两秒内按钮显示“已复制”。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Copied`：内容已写入剪贴板。
|
||||
- `Exported`：请求调用方导出。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 到切换组，← → 移动，Enter / Space 选择；Tab 到复制、导出。
|
||||
|
||||
## 限制
|
||||
|
||||
- 不内置网页渲染，网页预览须由调用方提供（无 WebView）。
|
||||
@@ -0,0 +1,45 @@
|
||||
# 275 ArtifactVersionSwitcher 产物版本切换
|
||||
|
||||
## 用途
|
||||
|
||||
在产物的多个版本之间切换，并提供与上一版本比较差异的入口。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
current := 1
|
||||
versions := []mujica.ArtifactVersion{{Label: "v1", Note: "First draft"}, {Label: "v2", Note: "Added music"}}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if mujica.ArtifactVersionSwitcher(c, ¤t, versions, mujica.ArtifactVersionSwitcherOptions{}).Compare {
|
||||
fmt.Println("diff v1 and v2")
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func ArtifactVersionSwitcher(c *ui.Context, current *int, versions []ArtifactVersion, opts ArtifactVersionSwitcherOptions) ArtifactVersionResult`。没有版本、`*current` 越界或版本 `Label` 为空时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Disabled` | `bool` | `false` | 禁止切换与比较。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- 显示版本名、“N / 总数”和说明；第一个版本时“较早版本”禁用，最后一个时“较新版本”禁用。
|
||||
- 非第一个版本显示“与上一版本比较”。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Changed`：`*current` 改变。
|
||||
- `Compare`：请求比较当前版本与上一版本。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- 焦点在组件内时 ← → 切换版本；Tab 到各按钮，Enter / Space 触发。
|
||||
|
||||
## 限制
|
||||
|
||||
- 差异视图由调用方打开，可用 FileChangeCard 或 MultiFileDiffReview 呈现。
|
||||
@@ -0,0 +1,43 @@
|
||||
# 276 SandboxStatus 沙箱状态
|
||||
|
||||
## 用途
|
||||
|
||||
显示沙箱的运行状态、资源占用和剩余时间。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
info := mujica.SandboxInfo{Name: "sandbox-7", State: mujica.SandboxRunning,
|
||||
Resources: []mujica.SandboxResource{{Name: "CPU", Used: 1.5, Limit: 2, Unit: "cores"}}}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
mujica.SandboxStatus(c, info, mujica.SandboxStatusOptions{})
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func SandboxStatus(c *ui.Context, info SandboxInfo, opts SandboxStatusOptions) *ui.Element`。状态未知、资源名为空、`Limit` 不大于 0 或 `Used` 不在 0 到 `Limit` 之间时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- `SandboxInfo` 字段：`Name`、`State`（`SandboxStarting`、`SandboxRunning`、`SandboxStopped`、`SandboxFailed`）、`Resources`、`Expires`。
|
||||
- 每项资源显示“已用 / 上限 单位”与细条；达到 90% 时加警示图标和“接近上限”说明。
|
||||
- 设置 `Expires` 且运行中时显示剩余时间，每秒刷新；到时显示“已到时”。
|
||||
|
||||
## 事件
|
||||
|
||||
- 无事件。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- 不获取焦点。
|
||||
|
||||
## 限制
|
||||
|
||||
- 倒计时依赖界面帧，窗口隐藏时 MyGo 暂停帧，重新显示后立即校正。
|
||||
@@ -0,0 +1,46 @@
|
||||
# 277 MCPServerList MCP 服务器列表
|
||||
|
||||
## 用途
|
||||
|
||||
列出 MCP 服务器：连接状态、传输方式、工具数，提供启动、停止与重新连接回调。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
servers := []mujica.MCPServer{{ID: "fs", Name: "filesystem", Transport: "stdio", State: mujica.MCPConnected, Tools: 12}}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if r := mujica.MCPServerList(c, servers, mujica.MCPServerListOptions{}); r.Action == mujica.MCPStop {
|
||||
fmt.Println("stop", r.Server)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func MCPServerList(c *ui.Context, servers []MCPServer, opts MCPServerListOptions) MCPServerListResult`。`ID` 为空或重复、`Name` 为空、状态未知、`Tools` 为负、`MaxHeight` 为负时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `MaxHeight` | `float32` | 360 | 列表最大高度，超出后滚动。 |
|
||||
| `Disabled` | `bool` | `false` | 禁止所有操作。 |
|
||||
| `Still` | `bool` | `false` | 停止执行中动画；系统减少动画时也自动静止。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- `MCPServer` 字段：`ID`、`Name`、`Transport`、`State`（`MCPStopped`、`MCPConnecting`、`MCPConnected`、`MCPError`）、`Tools`、`Error`。
|
||||
- 已连接时显示“N 个工具”；连接失败时显示错误文字与“重新连接”。
|
||||
- 超过 200 台服务器时虚拟化。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Action`：本帧请求 `MCPStart`、`MCPStop` 或 `MCPReconnect`，`Server` 为对应 ID。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 依次到各行按钮，Enter / Space 触发。
|
||||
|
||||
## 限制
|
||||
|
||||
- 组件只发出请求，连接管理由调用方完成。
|
||||
@@ -0,0 +1,47 @@
|
||||
# 278 MemoryPanel 记忆面板
|
||||
|
||||
## 用途
|
||||
|
||||
列出 Agent 的记忆条目，支持搜索、行内编辑和确认后删除。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
entries := []mujica.MemoryEntry{{ID: "1", Text: "Lady Sakiko prefers the east wing.", Source: "Chat"}}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if r := mujica.MemoryPanel(c, &entries, mujica.MemoryPanelOptions{}); r.Deleted != "" {
|
||||
fmt.Println("forget", r.Deleted)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func MemoryPanel(c *ui.Context, entries *[]MemoryEntry, opts MemoryPanelOptions) MemoryPanelResult`。`entries` 为 nil、条目 `ID` 为空或 `MaxHeight` 为负时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `MaxHeight` | `float32` | 360 | 列表最大高度。 |
|
||||
| `Disabled` | `bool` | `false` | 只读，禁止搜索、编辑与删除。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- `MemoryEntry` 字段：`ID`、`Text`、`Source`。
|
||||
- 搜索不区分大小写，匹配内容与来源；只在搜索词或条目变化时重新筛选。
|
||||
- 编辑时出现文本框和保存、取消；删除前用 Popconfirm 确认，确认按钮为危险样式且默认聚焦取消。
|
||||
- 条目超过 200 条时虚拟化。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Edited`：本帧保存的条目 ID，`*entries` 已更新。
|
||||
- `Deleted`：本帧删除的条目 ID，已从 `*entries` 移除。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 到搜索框、各条的编辑与删除；删除确认中 Escape 取消。
|
||||
|
||||
## 限制
|
||||
|
||||
- 调用方原地修改条目文本而不改变切片长度时，筛选结果到下次搜索变化才更新。
|
||||
@@ -0,0 +1,46 @@
|
||||
# 279 CheckpointList 检查点列表
|
||||
|
||||
## 用途
|
||||
|
||||
列出 Agent 运行的检查点，标出当前点，回滚到其它检查点前要求确认。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
current := "c2"
|
||||
points := []mujica.Checkpoint{{ID: "c2", Label: "Menu drafted"}, {ID: "c1", Label: "Start"}}
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
if mujica.CheckpointList(c, ¤t, points, mujica.CheckpointListOptions{}).Changed() {
|
||||
fmt.Println("restore", current)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func CheckpointList(c *ui.Context, current *string, points []Checkpoint, opts CheckpointListOptions) ChoiceResult`。`current` 为 nil、`ID` 为空或重复、`Label` 为空、`MaxHeight` 为负时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `MaxHeight` | `float32` | 360 | 列表最大高度。 |
|
||||
| `Disabled` | `bool` | `false` | 禁止回滚。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- 当前点用实心菱形、选中底色和“当前”文字标出；其它点为空心菱形。
|
||||
- 回滚用 AlertDialog 确认：默认聚焦取消，Enter 不会直接回滚。
|
||||
- 超过 200 个检查点时虚拟化。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Changed()`：确认回滚后 `*current` 已改为目标 ID。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 到各“回滚”，Enter 打开确认；确认框内 Tab 到“回滚”再按 Enter。
|
||||
|
||||
## 限制
|
||||
|
||||
- 恢复文件与状态由调用方完成。
|
||||
@@ -0,0 +1,52 @@
|
||||
# 280 HumanInputRequest 人工输入请求
|
||||
|
||||
## 用途
|
||||
|
||||
Agent 向用户提问：显示问题、可选答案与自由回答，并提示剩余时间与超时。
|
||||
|
||||
## 最小示例
|
||||
|
||||
```go
|
||||
answer := ""
|
||||
view := func(c *ui.Context) {
|
||||
mujica.Use(c, mujica.Settings{})
|
||||
r := mujica.HumanInputRequest(c, &answer, mujica.HumanInputRequestOptions{
|
||||
Question: "Which hall?", Options: []string{"East wing", "Great hall"}, AllowFree: true,
|
||||
})
|
||||
if r.Submitted {
|
||||
fmt.Println("reply", answer)
|
||||
}
|
||||
}
|
||||
ui.Render(view, 400, 300, 1)
|
||||
```
|
||||
|
||||
签名：`func HumanInputRequest(c *ui.Context, answer *string, opts HumanInputRequestOptions) HumanInputResult`。`answer` 为 nil、`Question` 为空、既无选项又不允许自由回答时 panic。
|
||||
|
||||
## 参数
|
||||
|
||||
| 字段 | 类型 | 默认值 | 含义 |
|
||||
| --- | --- | --- | --- |
|
||||
| `Question` | `string` | 必填 | 问题。 |
|
||||
| `Options` | `[]string` | `nil` | 可选答案。 |
|
||||
| `AllowFree` | `bool` | `false` | 允许自由回答。 |
|
||||
| `Deadline` | `time.Time` | 零值 | 截止时间；零值不限时。 |
|
||||
| `Disabled` | `bool` | `false` | 禁止回答。 |
|
||||
|
||||
## 状态
|
||||
|
||||
- 选择选项会清空自由回答；输入自由回答会取代所选选项。
|
||||
- 剩余时间每秒刷新；到时显示“智能体已停止等待”并禁用。
|
||||
- 回答为空白时“发送回答”禁用。
|
||||
|
||||
## 事件
|
||||
|
||||
- `Submitted`：用户发送了 `*answer`。
|
||||
- `TimedOut`：截止时间在本帧到达（只报告一次）。
|
||||
|
||||
## 键盘操作
|
||||
|
||||
- Tab 进入选项组，方向键选择；Tab 到输入框，Enter 发送；或 Tab 到“发送回答”。
|
||||
|
||||
## 限制
|
||||
|
||||
- 超时只在界面帧中检测，窗口隐藏期间推迟到重新显示。
|
||||
Reference in new issue
Block a user