deepseek-harness/missions/tasks/20260721-1520-web-plugin-rfc/plugins.md

Web UI 业务分层与插件清单（依据 Figma 定稿重写）

业务层拆解：页面分层、slot 全量留位（含本次不实现的）、插件清单、互操作契约（props/actions）、全局配置、开工子集圈选。架构机制在 architecture.md/modules.md；视觉依据在 figma-analysis/（sidebar / conversation / flows-future 三份，节点 id 可回查 Figma）。 「维度」= 组件数据语境：global（与会话无关）/ session（绑定当前会话）/ toolcall（绑定单次工具调用）/ step（绑定 turn/step 定位，details 联动用）。

0. 页面总布局（Figma 定稿）

三栏，不再是两栏——details 是第一公民：

┌ Sidebar 300px ┐┌ Conversation（弹性）───────────────┐┌ Details 360px ┐
│ Logo+HARNESS  ││ Header: 面包屑(workspace/父session/ ││ (默认收起，    │
│ [New Session] ││   当前session) + Fork|Session log|  ││  打开时挤压     │
│ [Search]      ││   I/O Details 按钮排                ││  conversation) │
│ WorkSpace 区头 ││ Tab_Group: Chat|Trajectory|Waterfall││ 头: Turn·Step  │
│ ┌project 54h ┐││ ┌─ 视图区（当前激活一个）──────────┐ ││   定位+See in  │
│ │└session 34h│││ │ Chat: 消息流(user气泡右对齐/     │ ││   trajectory   │
│ │  └子session│││ │   assistant通栏/tool摘要行/统计行)│ ││ Switch: Input| │
│ └────────────┘││ └──────────────────────────────────┘ ││  Output|Meta   │
│ (session多级树,││ [回到底部浮钮]                       ││ Code-block 正文│
│  状态点4色)    ││ Composer 堆叠区: Goal pill/审批接管/  ││ ‹Prev|Next›    │
│ Handle(折叠把手)││   追问队列/附件条                    ││ [Add Feedback] │
│ Foot: Settings ││ 输入框: textarea + [+|Plan|Read-only]││                │
└───────────────┘│   + [模型 effort ▾][发送]            │└────────────────┘
                 └──────────────────────────────────────┘

关键定稿事实（详见三份解析报告）：

• details=360px 右栏、挤压式（非浮层）；打开后进入联动选择模式——左侧每条消息/step 可点击切换右侧内容（选中项蓝描边），另有 Prev/Next 步进。
• 审批不是消息卡，是 composer 换面板（琥珀状态条+意图行+命令行+三按钮）；Ask question 与审批合并同形态（注记 43:40435）。
• tool call 是单行摘要行（5 变体：Think/Search/Read/Bash/Others），无行内输出——输出走 details；状态色/spinner 设计未给，用 State 四色原语自补。
• State 四色状态原语全局复用（侧栏 cell/composer 状态条/hover 菜单/通知）：绿 #22C55E=new task completed、琥珀 #F59E0B=need approval、蓝渐变环 #5686FE=agent working、红 #EC1313=error。
• session 列表是多级树（session 下挂子 session，fork 粒度=user message，默认折叠逐级展开）。

0.1 布局动态规则（用户拍板 2026-07-21）

#	规则
1	两侧栏都可拖宽+可开合：sidebar 左右拖拽（Handle=拖拽把手，折叠按钮在 Logo 行的 panel_left）+开合；details 同样可拖宽+开合；conversation 纯弹性
2	窗口过小的让步顺序：自动缩小左右两侧，优先缩 details（details→sidebar→中栏兜底）；宽度是数值观看态（persist），不是布尔
3	输入框随中栏对等缩小，维持固定 padding（736/776 是上限不是定值）
4	滚动铆钉（挤压重排时保持阅读位置）不做——留 future work，等无限滚动组件一起
5	切 session 时 details 开合态暂时维持全局不动（不随 session 走）；架构上预留 per-session keyed 的升级位
6	Chat 之外的视图（Trajectory/Waterfall）打开 details 布局同样挤压——details 行为与视图无关
7	composer banner 堆叠不设上限就堆着（实际不会太多）；审批态=composer 整体换新面板（当前面板内容完全被审批提问+执行详情替换），不是"常态输入框顶上加条"
8	空态→有内容的转场：输入框是同一个组件的位置移动（居中大输入框→底部 composer），不是两个组件切换
9	树深层截断：标题 ... 省略号截断，不限深不横滚

1. slot 全量留位表

「实装」=本次波次做；「预留」=接口/注册表现在留位，实现后置；「不留」=将来加插件即可，不动接口。层级即所有权链（架构 §5）。

L 层（layout 拥有）

slot	kind/scope	状态	内容
sidebar	single/root	实装	sidebar 插件整栏占用（含折叠态——Handle+panel_left 双入口，折叠是 layout 观看态）
conversation	single/session	实装	conversation 骨架占用
details	single/session	实装（壳先行）	第三栏宿主：开合/挤压归 layout，内容归 details 插件——figma 完成度最高的区，网格第一天就留三栏
全局 toast 区	list/root	预留	右上角通知（New Task completed·1h ago，34:12110）；通知源=session 状态事件

S 层（sidebar 插件拥有）

slot	kind/scope	状态	内容
sidebar 区块注册	list/root	实装	projects 列表区块、（将来任意区块）
行级「…」菜单项	list（菜单条目）	预留	session:Rename/Fork/删除;workspace:Rename/New Workspace——菜单已画、条目将来随功能加
分组策略	内部枚举（非 slot）	实装 by-workspace	Group by WorkSpace✓/Update/Status 菜单已画；Update/Status 无稿后补

C 层（conversation 骨架拥有）

slot	kind/scope	状态	内容
conversation.views	list/session	实装	Chat（实装）/Trajectory（tab 留位零内容）/Waterfall（同）——tab 只在会话有内容时显示
视图 chrome 附件	视图注册项声明字段	预留（接口）	统计条 Chat 挂消息流尾、Traj/Waterfall 挂顶（修改List 明确）——视图声明自己的 header/footer 附件
视图激活锚点	activate(anchor?) 参数	预留（签名）	"See in trajectory" 跨视图深链定位 turn/step——实现后置,签名现在定
conversation.composer.banner	list/session	实装	输入框上方堆叠区：审批接管/Review Plan/Goal pill/追问队列共用（多来源按优先级堆叠）
conversation.composer.command	keyed/session	预留（注册表）	slash 命令：/Goal、Side Question、Fork from here、Skills??——命令来自不同插件,注册表必须开放
conversation.composer.accessory	list/session	预留	输入框下沿件：模式选择(Plan/Read-only)/模型+effort 选择器（实装为内置件）;context 进度指示（注记点名未画,留挂点）
附件条	内置件	预留	文件 chips（解析中/上传中/类型图标族,FILES 区稿）——依赖上传后端
Header 按钮排	list/session	预留	Fork/Session log/I/O Details 已画；做成小注册表,将来可加
conversation.detail（旧）	—	裁撤	被 L 层 details 第三栏取代（原"conversation 内侧板"设计已被 figma 推翻）

D 层（details 插件拥有）

slot	kind/scope	状态	内容
details 子 tab	list（Switch）	实装 Input/Output/Metadata	将来按 step 类型加子 tab（diff/terminal）——注册表化
内容渲染格式	内置（PLAIN▾ 下拉）	不留	面板内部功能
Add Feedback	内置+事件占名	预留（事件）	反馈上报通道,事件类型先占名

T 层（chat 视图拥有）

slot	kind/scope	状态	内容
toolview 具名注册表	独立 service（非匿名 slot key,见下）	实装	5 形态：think/search/read/bash + others 兜底——figma 直接给出"注册表+fallback"结构；Code Mode/Cordis 专属渲染将来注册进来
assistant footer 扩展位	list/session	预留	IconActions（copy/retry/like/dislike/share/分页）+ 统计行（cache hit/tokens/时长/turns/steps）为内置两件;将来可加
user 气泡 actions	内置	不留	copy/fork/edit + 分支分页器,内置实现

toolview 注册表升格为明确具名 service（用户拍板）：不走通用 slots 的 'conversation.chat.toolview' 字符串 key，chat-view 插件 provide 一个具名注册表 ctx.toolviews：

declare module 'cordis' { interface Context { toolviews: ToolViewRegistry } }
interface ToolViewRegistry {
  /** filter 缺省=全局注册;带 filter 则只对匹配的 agent scope 生效——
   *  同一 tool 名在不同 scope 可有不同渲染(如子 agent 的 bash 卡与主 agent 不同形态)。
   *  解析顺序: scope 精确匹配 > 全局注册 > others 兜底。 */
  register(tool: ToolName, component: FC<ToolViewProps>, filter?: { scope?: ScopeMatcher }): () => void
  resolve(tool: ToolName, scopeKey: ScopeKey): FC<ToolViewProps>   // chat/trajectory 渲染时查
}

理由：① toolview 是被 chat/trajectory/waterfall 多个视图共同消费的注册表（同一 tool 的行渲染+span 装饰将来同源），不是某一个坑的私产——具名 service 比挂在 chat 名下的 slot key 更诚实；② 面向 agent scope 的差异化注册（filter.scope）给 Code Mode/Cordis/subagent 场景留位：v1 大家都不带 filter（=全局），机制先立。SlotMap 通用表继续管布局类坑位；toolview 这类"按业务数据分发的组件注册表"从此走具名 service 模式（先例）。

2. 插件清单（业务）

2.1 sidebar（合并原 projects+sessions 两条：一个插件管整栏）

项	内容
负责	整栏：Logo 行/New Session 按钮/搜索框/WorkSpace 区头(分组菜单+新建 workspace)/session 多级树列表/Settings foot/折叠把手联动
树与状态	project 行 54h(标题+N sessions)/session 行 34h(标题+相对时间)；缩进步长 22px 多级；状态点 State 四色；hover:project 出…/+、session 时间换…
维度	全部 global（列表数据+树展开态+搜索 query+分组策略都是 root 域）
actions	router.open(id);sessions.create({cwd})(New Session/project 行 +/区头新建 workspace 三入口);树开合/搜索/分组切换（观看态）
后端缺口	树结构需要 parentId 链（现 lineage 已有）;「新完成未读」=完成时间>last-seen,本地观看态不上 host

2.2 conversation（骨架 owner）

项	内容
负责	Header（面包屑三级+按钮排+Tab_Group）/视图区/composer（输入框+banner 堆叠+队列）/回到底部/与 details 的 selection 联动发起端
维度	session（面包屑含父 session 链=session 嵌套展示）
actions	send(text,mode)/cancel();openDetails(target)（见 §3 selection 契约——从 toolcall 扩为 step 级）;视图切换;banner 堆叠管理
输入框细节	发送钮空文本 op0.4;运行中停止钮形态设计未给需自定;追问队列（edit/trash/send-now per item）;slash 触发命令菜单

2.3 chat-view（默认视图）

项	内容
负责	消息流：user 气泡（右对齐 #EDF3FE r22,失败重发态）/assistant 通栏 markdown/tool 摘要行分组（连续 tool 聚成 gap10 组,与叙述交替）/引用角标/source-item/footer(IconActions+统计行)/中断冻结
chrome	统计条挂消息流尾（视图 chrome 契约首例）
维度	session;MessageItem=session 切片;tool 行=toolcall
actions	loadOlder;点击 tool 行/消息 → 经注入 actions 转交 conversation 的 selection（openDetails）

2.4 工具行插件（toolview 注册项）

项	内容
形态	单行摘要行：16px 图标槽(收起=工具图标/展开=chevron)+标题+·+摘要(FILL 截断)；展开体=缩进灰文本；无行内输出
首批	think/search/read/bash 四形态+others 兜底（figma 5 变体 1:1）;fs 写/edit 暂走 others,diff 形态进 details 子 tab（后置）
状态	行级状态色设计未给——用 State 原语自补（running=蓝环/error=红,进契约）
维度	toolcall
actions	展开/收起（观看态）;点击行=selection 转交（详情在 details）

2.5 details（第三栏插件）

项	内容
负责	头部（Turn·Step 定位+See in trajectory+收起钮）/Input|Output|Metadata 三段/Code-block 正文（PLAIN▾）/Prev-Next 步进/Add Feedback
维度	step（当前 selection 指向的 turn/step;toolcall 是 step 的一种）
actions	selection 步进（Prev/Next）;跳 Trajectory（带锚点激活,签名预留）;关闭
联动	打开时 chat 流每条目可点击切换+选中蓝描边——selection 是 conversation 级共享状态,不是 details 私有（见 §3）

2.6 approvals（composer 接管，非消息卡）

项	内容
形态	输入框整体接管：琥珀状态条(#FEF5E7+Waiting for approval)+意图行+命令行+［Refuse/Allow once/Always allow this type］;Ask question 同形态不同按钮组;Review Plan 同族变体（单 Build 钮,注记"maybe no"存疑）
挂点	conversation.composer.banner（不是 timeline）
维度	session
actions	respond(approvalId, outcome, scope)——Always-allow-this-type 说明决策带持久化范围,接口要有 scope 字段;answer(rpcId, answers)
联动	审批态三处同步：composer 条+面包屑文案+侧栏状态点（同一状态源,各自订阅）

2.7 gantt-view → 改名 trajectory/waterfall 视图（占位）

Tab 留位零内容（TRACE WIP 零设计）。将来实现时：统计条挂顶（chrome 契约）、接收锚点激活、span 点击=selection 转交。

2.8 goal（slash 命令首个客户,P-III）

/Goal 命令+Ongoing Goal 常驻 pill（banner 堆叠区）;Side Question、Fork from here、Skills 同菜单后续。

2.9 empty-state（NEW SESSION/ONBOARDING）

无会话选中/新会话时 conversation 坑显示"Let's start building"居中输入框（Plan/Read-only/模型选择齐全）——归 conversation 骨架内置,不单独成插件。

2.10 zh/en 语言包、默认主题（含暗色）

纯注册。暗色是完整第二套 token（figma 双主题成对,注记点名输入框边框差异）——theme 插件第一天就带 light/dark 两字典。

3. 互操作契约（跨插件的三条通道）

1. selection 通道（新增,details 联动的核心）：conversation 骨架持有 selection: { turn, step } | null 观看态。写入方=chat 视图（点消息/tool 行）、details（Prev/Next）、将来 trajectory（点 span）；订阅方=details（切内容）、chat 视图（画蓝描边）。转交纪律照旧：组件调自己坑 owner 注入的 action,owner inject conversation 转调。openDetails(target) 契约从 toolcall 扩为 {turn, step}（toolcall 是特例）。
2. 状态原语（State 四色）：session 状态字典（done/warning/ongoing/error + 文案）是 conversation 级单一 source（host 状态+审批 pending 推导）,sidebar cell/composer 条/toast/面包屑各自订阅渲染——不各算各的。
3. actions 收敛：router 导航、sessions.create、conversation.send/cancel/openDetails、approvals.respond/answer(带 scope)、视图 activate(anchor?)。新插件先复用,不新增全局面。

4. 全局配置

项	内容
theme token 空间	figma 已给全量双主题（两份报告 §5/§7 的 token 表直接进 theme 插件字典）：表面/文字四级/边框两档/品牌蓝/状态四色/hover-选中(#263148 6%/10%)/圆角族/字号族——禁 hardcode,组件只用 token
i18n	稿内中英混排未统一（figma 备注）;UI 文案首发中文,英文包结构同置
用户偏好（Zustand persist）	主题选择/语言/sidebar 折叠+宽度/分组策略/树展开态/details 开合
后端能力开关	模式(Plan/Read-only)与模型/effort 选项由 host describe 供数;附件上传、remote session（"目前只有 local"）等能力位留字段

5. 分期（P-I 已圈定开工;P-II/III 仅架构预留,不排开发）

P-I 开工范围（用户圈定 2026-07-21：基本等同现有功能略微超出,面向新布局架构重设）

• layout 三栏骨架（拖宽/开合/让步规则 §0.1;details 栏=壳+极简内容——开合+选中 toolcall 的 args/result 原样展示即可,三段 Switch/Prev-Next/See-in-trajectory 全后置）
• sidebar（树列表/搜索/by-workspace 分组/状态点四色/新建三入口/拖宽折叠）
• conversation 骨架（Header 面包屑+tabs+composer 常态+空态同组件转场）
• chat-view（消息流:user 气泡/assistant markdown/tool 摘要行 5 形态/统计行/回到底部）
• theme 双主题（深色本来就有,light/dark 全量 token 两字典）
• selection 通道（机制入契约,P-I 只用到"点 tool 行→details 显示该 call"这一档）
• toolview 自定义组件验收样例：挑一个真实工具（bash 或 todo）以第三方姿势经 ctx.toolviews.register 实现专属行渲染——证明注册表全链可用（这就是"略微超出"的部分之一）

P-II / P-III（只讨论架构,不讨论开发——所有接口/注册表/事件占名已在 §1 留位,兑现时机另议）

P-II 位:approvals composer 换面板（含 Ask question 合并、Always-allow scope）/追问队列/slash 注册表与 Goal/toast/气泡失败与编辑分支/source-item。 P-III 位:Trajectory-Waterfall 视图/锚点深链/details 三段与子 tab/附件/context 指示/compact UI/行级菜单扩展/Update-Status 分组/Skills/remote 徽标。

明确不做（设计侧存疑/无稿）

Review Plan 卡（"maybe no"）等拍板;CODE MODE/CORDIS/PLUGIN 三区（零设计,toolviews 注册表已覆盖其唯一线索）;归档区（不存在）。