From 7da2b192d2be8c71d25fdc8587317130def1aab2 Mon Sep 17 00:00:00 2001 From: weichen Date: Wed, 30 Sep 2026 08:17:26 +0000 Subject: [PATCH] Update the usage guide for inbox, command bus, and workspaces; record T5 verification Why: T2-T4 changed the interaction foundation (pure-inbox rail, four-entrance command bus, overlay workspaces) and the guide still described the classic tabs; T5 acceptance also requires the verification record with the zero-page walkthrough. Evidence: zero-page walkthrough 12/12 PASS on a fresh real binary (fresh data dir: empty instance -> project/conversation -> slash commands -> #upload card lifecycle -> card action receipts -> tidy -> HITL block+resolve -> button-entrance dispatch -> plugin workspace declaration -> artifacts -> four-entrance audit); StatusLamp shape+color dual encoding asserted by ui suite; combo make test at pinned heads. Impact: usage guide sections 4.2-4.7/5/6.2/7 rewritten; new T5 record; no code change. Refs: docs/proposals/2026-09-30-ui-inbox-command-workspace.md T5; task card feature/polish-r1 --- docs/guides/usage.md | 55 +++++++++++++++++++++++++++++--------------- 1 file changed, 37 insertions(+), 18 deletions(-) diff --git a/docs/guides/usage.md b/docs/guides/usage.md index 6629adc..8ab710c 100644 --- a/docs/guides/usage.md +++ b/docs/guides/usage.md @@ -105,43 +105,59 @@ AGENT_SYSTEM_CONFIG=/etc/agent-system.json agent-system serve # 环境变量 - 选项卡：显示描述与**影响**（决策上下文契约：每个选项必须声明可能造成的影响）。 - 自由输入三分支路由：一般输入→澄清回答回填；`/` 开头→命令转轨；**命中已注册插件意图（agent-intent 闸门）→转轨为新任务**。示例插件注册了 `demo.show` 意图（命中「示例/演示」），HITL 挂起时输入「来个示例演示」即可观察转轨。 -### 4.2 Sub-agent 追踪 +### 4.2 收件箱与任务卡（右栏终态，D25） -- 右栏「代理」tab：任务树（对话任务 + 子代理，状态点动画）。 -- 点击任意节点 → **追踪弹窗**：状态、token/时长/工具用量徽标、**中间过程消息**（子代理产出已持久化）。 +右栏 = **收件箱** + 「当前任务」常驻卡（计划/待办并入，随对话实时更新）： + +- 任务卡七类（progress/confirm/compare/review-list/result/error/status）：状态灯**形状+色双编码**（◆ 待处理 ● 完成 ✓ 已确认 ✕ 失败 ◌ 已关闭——不只靠颜色）；置顶不随滚动；`#upload` 演示摄取→完成→冲突对比卡全周期。 +- 卡上动作即命令（card 入口，见 §5）；确认结论以**回执消息**进对话时间线留痕。 +- **收纳**：🧹 一键收纳完成卡（done→关闭；已确认卡盖章留痕不动）；右栏收起时角标显示待处理数。 +- 卡片↔消息**互定位**（D32）：消息内 `card:` 链接点击定位收件箱卡片；HITL/确认卡锚定发起消息内联双现。 + +### 4.3 工作区弹层（深读与治理视图，⌘1–9） + +工件/代理/插件面板不再占右栏 tab，统一为**工作区弹层**（Esc/遮罩关闭回对话现场；不承载唯一步骤）： + +- ⌘1 工件 · ⌘2 代理 · ⌘3+ 插件面板/插件声明工作区（example 插件含「治理总览」示例，⌘9）。 +- 左栏「工作区」快捷区同清单；会话头左侧为**项目徽章**（D26 不加全局顶栏）。 +- Sub-agent 追踪：代理工作区任务树点击任意节点 → 追踪弹窗（状态/用量徽标/中间过程消息）。 - 真实模型模式下，模型可经 `delegate_task` 派生子代理、经 `squad_orchestrate` 发起引擎编排（多步骤目标建议后者：计划确认 + 交付物把关）。 -### 4.3 计划 / 待办 +### 4.4 计划 / 待办 -右栏「计划 / 待办」实时更新（真实模型经 `update_plan` / `update_todos` 工具维护；mock `#agents` 演示）。 +并入右栏「当前任务」常驻卡（真实模型经 `update_plan` / `update_todos` 工具维护；mock `#agents` 演示）。 -### 4.4 工件 +### 4.5 工件 - 上传与模型产出统一入 Artifacts；`write_artifact` 工具可被模型调用。 - 查看：markdown 在线渲染；文本类可**编辑保存**；二进制（docx/pdf）下载；图片内联预览。 - 文档工件与上传文本自动进**知识索引**（全文检索）。 -### 4.5 知识检索 +### 4.6 知识检索 - API：`GET /api/knowledge/search?q=临床评价&project=`；对话内 `@knowledge` 注入；模型工具 `knowledge_search`。 - 中文检索：FTS5 分词对 CJK 无效时自动 LIKE 子串兜底（本版实测中文命中正常）。 -### 4.6 智能体画像（核心定制机制） +### 4.7 智能体画像（核心定制机制） 设置 → 智能体画像：内置「通用助手」（只读 T0 基线）+ 新建/导入/导出/编辑： - 系统提示、允许/确认/拒绝工具三清单（`*` 全部、`http.` 前缀族）、HITL 策略、预算（工具次数/轮次上限）。 - 导出为 JSON 迁移；会话头部下拉切换画像。 -## 5. 命令 +## 5. 命令总线（四入口同源，D27） -| 命令 | 作用 | -|---|---| -| `/help` | 命令列表 | -| `/new` | 新建会话 | -| `/mock on\|off` | 演示模式切换 | -| `/model <名称>` | 设置主模型 | -| `/profile ` | 切换会话画像 | +按钮、卡片 action、`/` 命令、对话意图四个入口命中同一命令产生**同一条执行与审计**（`POST /api/commands/{id}`；审计 `GET /api/commands/audit`）。注册表数据驱动（内置 + 插件 `provides.commands`）： + +| `/` 命令 | 命令 id | 作用 | +|---|---|---| +| `/help` | builtin.help | 命令列表 | +| `/new` | conversation.create | 新建会话 | +| `/mock on\|off` | runtime.mock | 演示模式切换 | +| `/model <名称>` | models.set | 设置主模型 | +| `/profile ` | conversation.profile | 切换会话画像 | + +`danger=high` 的命令（含插件命令）执行终点为**内联确认卡**：锚定发起消息、阻断待确认、已决折叠留痕（双现于收件箱）。 ## 6. 插件 @@ -153,8 +169,8 @@ AGENT_SYSTEM_CONFIG=/etc/agent-system.json agent-system serve # 环境变量 ### 6.2 示例插件（`example`） -随发布携带，覆盖五类注册能力：声明式 HTTP 工具（`http_echo`）、右栏面板（「示例面板」tab）、 -卡片模板（`note`）、意图 spec（`demo_intent`）、提示词模板、插件设置项（出现在设置中心）。 +随发布携带，覆盖七类注册能力：声明式 HTTP 工具（`http_echo`）、面板（工作区弹层呈现）、 +卡片模板（`note`）、意图 spec（`demo_intent`）、提示词模板、插件设置项，以及 **命令声明**（`example.echo`，经命令总线四入口可调）与**工作区声明**（`example.governance`「治理总览」，⌘9）。 ### 6.3 无代码自定义工具（声明式 HTTP） @@ -168,6 +184,9 @@ AGENT_SYSTEM_CONFIG=/etc/agent-system.json agent-system serve # 环境变量 消息与运行 POST /api/conversations/{id}/messages（含命令路由）· POST /api/runs/{id}/cancel · GET /api/runs/{id}（含子任务树） 事件流 GET /api/events?conversationId=&since=（SSE；Last-Event-ID 游标续传；心跳 15s） HITL POST /api/hitl/{id}/resolve {choiceId|freeText} +任务卡 GET /api/conversations/{id}/cards · POST /api/cards/{id}/actions/{actionId} · POST /api/cards/{id}/pin|dismiss +命令总线 GET /api/commands（注册表）· POST /api/commands/{id} {params,entrance,conversationId} · GET /api/commands/audit +工作区 GET /api/workspaces（插件工作区声明） 上传/工件 POST /api/projects/{id}/uploads（multipart，返回解析结果）· GET/PUT /api/artifacts/{id}/content 画像/设置 GET/POST /api/profiles · GET /api/settings · PUT /api/settings/user|project/{id}（schema 驱动） 工具/插件 GET/POST/DELETE /api/tools · GET /api/plugins · POST /api/plugins/reload · GET /api/registry（来源标记）