weichen
cf801f25d7
Why: Record the approved design for the interaction foundation phase — inbox/ command-bus/workspace mechanisms sink into the base system, domain views stay plugin territory (target-system strategy), decisions D25-D33. Evidence: proposal covers background, five UI principles, dialogue-completeness P0 constraint, module/repo split (Agent-System-UI, Agent-Command), contract sketch, task sequence T0-T5 and acceptance criteria. Impact: Becomes the design baseline for T0-T5 tasks across five repos. Refs: Agent-System-Dev feature/ui-foundation-r0
108 lines
11 KiB
Markdown
108 lines
11 KiB
Markdown
# 界面交互底座：任务收件箱、命令总线与工作区弹层 —— 设计与实施提案
|
||
|
||
状态：**已批准（2026-09-30 用户批准总体方案与 T0 实施计划）**；owner：weichen；主任务：Dev 仓 `feature/ui-foundation-r0`。
|
||
规范依据：Development-Guidelines（standards/module-contracts.md、standards/multi-repo.md、workflows/delivery.md）；本文是项目级消费，不复制其正文。
|
||
撰写日期：2026-09-30。
|
||
输入：目标系统设计全集（`~/downloads/agent-system-design`，01–09 文档 + V2.2.1 原型）；Agent-System 现状（v0.1.0 骨架）。
|
||
|
||
---
|
||
|
||
## 1. 背景与决策
|
||
|
||
### 1.1 战略
|
||
|
||
目标系统（智能研发管理系统：研发记忆与体系文档智能体，"两树一网"数据模型）**不直接实现**；先把 Agent-System 基座完善为 Kimi/Codex/Claude 级通用智能体工具（对话、检索研究、文档生成/总结），目标系统未来以插件形式承载。拆分判据：
|
||
|
||
- **通用交互机制 → 基座核心**：任务卡片收件箱、内联确认卡（双现/阻断/折叠）、命令总线（按钮与对话同源）、工作区弹出层、卡片↔消息互定位、徽标计数、拖拽投放、入口对称提示。
|
||
- **域数据与视图 → 插件**：文档树、追溯网、需求大表、变更单、记忆库笔记树、缺项分析、阶段门禁（目标系统 01–09 文档届时即插件需求基线）。
|
||
- **不采纳项**：按比例连续滚动同步（演示级实现，互定位已覆盖其价值）；全局顶栏（D26 否决）。
|
||
|
||
### 1.2 界面五原则（从目标系统提炼，成为基座通用准则）
|
||
|
||
1. **中栏做空**：中栏只有对话与上传；一切有后果的操作收敛为卡片上的显式点击。
|
||
2. **消息是事件流，卡片是状态对象**：异步任务的有生命周期状态常驻右栏收件箱，不塞时间流。
|
||
3. **页面 = 加速器与显微镜**：弹层只承担深读/批量/空间导航，不承载任何唯一步骤。
|
||
4. **待办不沉没**：待决策事项进收件箱（筛选 + 计数 + 置顶 + 双现投影）。
|
||
5. **一切可解释、确认即留痕**：卡片带来源锚点；确认动作回写对话时间线 + 审计。
|
||
|
||
### 1.3 对话完备性（P0 硬约束）
|
||
|
||
从打开系统到完成一轮完整工作**全程只碰中栏**：建/切项目、建/切会话、上传（拖拽/粘贴/路径）、查资料、生成/总结文档、工件查看导出、画像与设置增改、插件装卸——每项都是命令总线上的注册命令；插件注册的每个操作**必须**同时声明命令路径（manifest 验收项）。"零页面走查"（建项目→拖资料→查资料→生成文档→导出→归档，唯一点击=对话流内确认卡）为每期回归用例；T0 退回（卸载全部插件）后剧本仍须全程通过。
|
||
|
||
## 2. 决策（D25–D33，延续 D1–D24 编号）
|
||
|
||
| # | 决策 | 理由 |
|
||
|---|---|---|
|
||
| D25 | 右栏终态**纯收件箱**，分两步：R2 收件箱置首（tabs 暂留）→ R4 工作区落地后移除经典 tabs（Plan/Todos 变"当前任务"常驻卡；工件/代理/插件面板变工作区） | 保留 tabs 的成本在心智不在代码；右栏只回答"现在要我做什么" |
|
||
| D26 | **不加全局顶栏**；中栏会话头左侧加项目徽章；通知 = 收件箱计数 + tab 角标 + toast | 对话区垂直空间优先；与 Kimi/Claude/Codex 一致；将来要加是纯加法 |
|
||
| D27 | **保留 `/` 命令菜单**；命令总线统一后 `/`、自然语言、按钮、卡片 action 四入口同源（POST /api/commands/{id}，同一审计） | 与目标系统 V2.2.1"自然语言唯一"不冲突：两者同源不分叉；通用骨架保留效率入口，插件可配置隐藏 |
|
||
| D28 | UI 词汇新增 7 项：`progress / compare / tree / table / steps / tabs / timeline`；`graph` 远期，且追溯类视图强制"对象为中心 + 分组泳道 + 逐层展开 + 图标文字标签"，禁止力导向裸图 | 目标系统五视图的表达需要；追溯图"看不懂"教训（用户裁定）固化为设计约束 |
|
||
| D29 | 新仓 **Agent-System-UI**（Dev 仓 `modules/ui`）：UI 词汇渲染器 + 设计令牌 + 收件箱/卡片/工作区展示组件；纯展示（props 进 events 出）；v1 源码组合（vite/tsconfig `@ui` 别名），出现第二宿主再包装发版 | 渲染层可复用与独立测试；不为几个类型建仓的判据未被突破（组件库是独立职责） |
|
||
| D30 | 新仓 **Agent-Command**（Dev 仓 `deps/agent-command`）：命令 spec 格式、注册表、危险分级、执行结果四态（committed/accepted/rejected/unknown）、审计信封；纯 Go 无 I/O，宿主注入存储与执行；backend 经嵌套 submodule + replace 组合（`internal/cmdbus` 组合它，同 intentgate 之于 agent-intent） | 与 agent-intent 构成"识别→执行"分层的生态位；schema 权威在生态库，Core 只登记资产名（同 agent-intent 先例） |
|
||
| D31 | 对话完备性为基座 P0（见 1.3） | 用户裁定："从项目创建到结束都可通过纯对话完成"是硬要求 |
|
||
| D32 | 卡片↔消息锚点互定位做；按比例连续滚动同步不做 | 目标系统 8.2 自认演示级应换锚点联动 |
|
||
| D33 | `cardsvc` / `cmdbus` 为 backend **L1 包**（不拆仓）；模块卡写入 `modules/backend/policy/modules/`（项目既定约定的首次落地）；模块卡中写明升级拆仓触发条件 | 规范："不要为了复用两三个类型就新增一个独立公共仓库" |
|
||
|
||
## 3. 模块与仓网
|
||
|
||
### 3.1 既有仓职责增量
|
||
|
||
| 仓 | 增量 |
|
||
|---|---|
|
||
| Core | `activity.go`（ActivityCard 模型 + 状态机 + card.* 事件入信封）；`hitl.go` 增 AnchorMessageID / Blocked / BlockReason；`ui.go` 增 D28 七词汇类型；`plugin.go` Provides 增 `commands` / `workspaces`、WorkflowStep 增 `card` kind、Workspace 声明类型；ts/types.ts 与 golden 样本同步 |
|
||
| Backend | 新 L1 包 `internal/cardsvc`（卡片生命周期/存储/API/事件发布/摄取卡/编排卡/HITL 投影卡）与 `internal/cmdbus`（组合 Agent-Command：注册、执行分发、审计落盘、danger→内联确认卡收口）；server 增卡片与命令路由；ingest/squadadapter 产卡；`policy/modules/` 两张模块卡 |
|
||
| Frontend | Inbox 面板（收件箱/筛选/置顶/收纳/计数角标）、InlineConfirmCard（锚定内联/阻断/已决折叠/双现）、cardlink 互定位、拖拽投放区、OverlayHost 工作区弹层、⌘ 快捷键、左栏工作区快捷区 + 项目徽章 |
|
||
| Documents | 本提案、各任务验证记录、usage/插件开发指南更新 |
|
||
|
||
### 3.2 新仓接线（本提案 T0 落地）
|
||
|
||
- 建序：Gitea API 建仓（auto_init，描述按 §4）→ main 分支保护（禁直推 + 拒绝陈旧候选）→ 骨架与代码均经 feature 分支 + PR。
|
||
- Dev 仓：`git submodule add`（`modules/ui`、`deps/agent-command`）；Makefile：`contracts` 双份生成（frontend + ui）、`test` 增 test-ui、`pin` 清单加两仓；build 链 core→contracts→frontend（经别名编入 ui）→backend。
|
||
- Backend：嵌套 `.gitmodules` 加 `deps/agent-command` + `go.mod replace agent-command => ./deps/agent-command`（T0 只接线，T1 消费）。
|
||
- 依赖方向：`frontend → ui → core(类型)`；`backend → agent-command`；Core 不依赖任何新仓；无环。
|
||
|
||
## 4. 契约设计要点（实现以 Core 为权威）
|
||
|
||
```
|
||
ActivityCard{ ID, ProjectID, ConversationID, SourceRunID, AnchorMessageID,
|
||
Kind: progress|confirm|compare|review-list|result|error|status|<plugin>,
|
||
Title, Status: active|action_required|done|resolved|failed|dismissed,
|
||
Tone: ok|warn|danger|info, Body: []UINode, Actions: []UIAction,
|
||
Pinned, CreatedAt, UpdatedAt }
|
||
事件：card.created / card.updated / card.status / card.resolved（入现有信封，消费方未知类型静默忽略）
|
||
API：GET /api/conversations/{id}/cards · POST /api/cards/{id}/actions/{actionId} · POST /api/cards/{id}/pin|dismiss
|
||
HITLCard 增：AnchorMessageID, Blocked, BlockReason；UIAction 增 Command（绑定命令 id，未绑定降级发消息）
|
||
CommandSpec（Agent-Command）：{id,title,description,paramsSchema,danger:normal|high,binding}
|
||
danger=high 执行终点 = 内联确认卡；四入口 → POST /api/commands/{id} 同源审计
|
||
UI 词汇：progress{label,value,tone} compare{left,right} tree{nodes} table{columns,rows,rowActions}
|
||
steps{current,steps} tabs{tabs} timeline{items}
|
||
Workspace 声明（Core）：{id,title,icon,shortcut,badgeTool?,body:[]UINode,refreshTool?}
|
||
v1 边界：收件箱按会话聚合（与事件路由一致）；跨会话项目级收件箱为 follow-up
|
||
```
|
||
|
||
## 5. 实施计划
|
||
|
||
| 任务 | 内容 | 涉及仓 |
|
||
|---|---|---|
|
||
| T0（本任务，feature/ui-foundation-r0） | 本提案入库；两新仓建立与接线；UIRenderer+令牌迁入 ui（零行为变化）；Makefile/构建链调整 | documents / ui / agent-command / frontend / dev |
|
||
| T1 core-cards-commands | Core 契约扩展 + golden + ts；Agent-Command v0（spec/registry/validate/conformance） | core / agent-command / frontend / dev |
|
||
| T2 inbox | backend cardsvc + 摄取卡/编排卡/HITL 投影卡；ui 卡片组件；frontend 收件箱置首 + 角标；mock `#upload` 演示 | backend / ui / frontend / documents / dev |
|
||
| T3 command-bus | cmdbus + 命令 API + intentgate 同源 + 内置命令全清单 + 审计；InlineConfirmCard + cardlink + 拖拽投放 + 入口对称提示 | backend / ui / frontend / documents / dev |
|
||
| T4 workspaces | Workspace 声明 + pluginhost + OverlayHost + 七词汇渲染器 + DocViewer/AgentTracker 迁入 + ⌘ 快捷键 + 移除经典 tabs（当前任务常驻卡替代）+ example 插件扩展 | backend / ui / frontend / documents / dev |
|
||
| T5 polish-retreat | T0 退回回归（零页面走查仍通过）；状态灯形状+色双编码；收纳策略；文档更新 | 全部 / documents |
|
||
|
||
跨仓顺序遵守 multi-repo 五步：提供方（Core/Agent-Command）先合入 → 消费方适配 → 各仓 PR → Dev gitlink PR 固定组合 → 组合验证。
|
||
|
||
## 6. 验收
|
||
|
||
- 每任务验证记录入本仓 `docs/records/`；完成声明附 precheck / task-sync / test 三段输出（Dev 仓 AGENTS.md）。
|
||
- 证据矩阵：前端交互 = 组件测试 + 构建 + 真实浏览器用户流程；卡片事件纳入 Stream 游标/断连/终态对账验证；T5 零页面走查为系统级验收剧本。
|
||
- T0 特定验收：`make test` + `make build` 通过；前端渲染行为零变化（迁移为纯移动 + DocBridge 注入点，调用方接 store）；新仓 main 有保护、gitlink 固定。
|
||
|
||
## 7. 剩余项
|
||
|
||
- 追溯类视图（graph 词汇）待插件立项时按 D28 约束单独设计。
|
||
- 跨会话项目级收件箱（v1 边界外）。
|
||
- 通知聚合策略（右栏在线/收起角标/铃铛远期）在 T5 细化。
|
||
- 顶栏若未来需要（全局搜索/跨项目通知），按加法引入，不回改本决策。
|