dsh-sansheng-liubu/docs/panel-design.md

172 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 三省六部面板设计方案
日期:2026-11-08
状态:已落地到 0.5.1 面板;实现位于 `panel/lib/client.js`。
## 1. 目标与范围
让每个部门拥有明确、易识别、可点击的卡片边界,贴合 DSH 原生主题。朝堂编制与任务流转统一收进会话右侧栏,聊天复用 DSH 原生输入框和消息流,不再维护整页面板或第二套对话摘要。本轮不新增聊天引擎,不修改角色策略、权限或调度机制。
用户要求:每轮设计调整附一张新生成的预览图。版本历史使用 Git,不建立时间戳备份或多个最终版。
## 2. 预览依据
0.5.4 的预览图由 `scripts/preview.mjs` 生成:脚本用 vm 加载**真实的** `panel/lib/client.js`,用会重渲染的 hooks 替身跑真实组件树,把结果序列化成 HTML,再用 headless Chrome 截图。因此它是真实 CSS + 真实 DOM 的渲染结果,不是生成式模拟图。
440px 明亮主题:
![右侧栏 440px 明亮主题](preview/panel-sidebar-440-light.png)
371px(当前宿主实测的侧栏宽度;最近活动独占一行):
![右侧栏 371px](preview/panel-sidebar-371-light.png)
360px 窄栏(检查不裁切):
![右侧栏 360px 窄栏](preview/panel-sidebar-360-light.png)
320px 极窄栏(三省与六部降为单列):
![右侧栏 320px 单列](preview/panel-sidebar-320-light.png)
440px 深色主题:
![右侧栏 440px 深色主题](preview/panel-sidebar-440-dark.png)
任务页:
![任务页](preview/panel-sidebar-tasks-440.png)
左侧栏导航行的观感(展开/折叠/激活态,以及 main 重定向桩的两种文案):
![左侧栏导航行](preview/panel-nav-entry.png)
重新生成的方式写在 `docs/panel-handoff.md` 顶部。截图只覆盖组件在给定容器宽度下的表现,**不覆盖**宿主槽位宽度、滚动容器与真实主题变量注入;最终验收仍需在 DSH Host 中截图确认。统计数字 10 / 3 / 4 是测试替身给的示例数据,不得硬编码为真实数据。
## 3. 面板结构
面板只存在于会话右侧栏。从上到下:状态行 → 朝堂/任务页签 → 统计区 → 丞相 → 三省 → 六部分组 → 当前部门配置。
入口有两个,行为完全等价,都只做「把朝堂停靠到当前会话的右侧栏」:会话头部的「三省」开关,和左侧栏底部的常驻入口(`sidebar.footer.action`);后者折叠侧栏时只剩「三省」字标,展开时带文字与失败原因。左侧栏不承载面板内容,也不提供第二套聊天。
- 状态行:协作状态、`输入 @ 选择部门` 提示;在子会话中显示“返回丞相”。
- 页签:朝堂与任务二选一;点击统计卡也可切换,切换不改变当前选中的部门。
- 统计区:在朝成员、运行中、在办任务、已完成,右侧栏固定两列两行。
- 丞相:居中单卡,连接中书省、尚书省、门下省。
- 三省:从左到右为中书省、尚书省、门下省。
- 六部:放入带“六部 · 尚书省调度”标题的浅底色容器,仅由尚书省连接到整个组。
- 六部第一排:吏部、户部、礼部;第二排:兵部、刑部、工部。
- 两排只是视觉换行,不能用连线暗示吏部管理兵部、户部管理刑部等关系。
- 配置区:显示所选部门名称、固定职责、模型、推理等级、保存设置按钮与“与该部门对话”入口。移除重复指令输入框及“Agent 预设”输入与应用按钮;消息在对应原生会话发送,部门角色由系统配置。
十席清单:丞相、中书省、尚书省、门下省、吏部、户部、礼部、兵部、刑部、工部。
## 4. 部门卡片规范
| 项目 | 规划值或行为 |
| --- | --- |
| 底色 | 独立实色表面,与工作区背景明确分离 |
| 常态边框 | 1px 清晰蓝灰实线;不得仅靠阴影区分 |
| 圆角 | 10–12px |
| 内边距 | 10–12px |
| 卡片间距 | 10–12px |
| 建议最小宽度 | 104px;不足时减少列数 |
| 建议最小高度 | 80–88px,由内容撑高,不裁切 |
| 字徽 | 28–32px 淡蓝底字徽,准确使用丞/中/尚/门/吏/户/礼/兵/刑/工 |
| 名称 | 13–14px,中等至粗体,完整可读 |
| 状态 | 11–12px,状态点与文字并存 |
| 点击范围 | 整张卡片,不只部门名称 |
名称和状态是卡片主要信息。长模型名、最近消息和配置细节集中到下方详情区,避免卡片成为密集文本块。尺寸是实现起点,应在真实侧栏宽度下验证。
## 5. 状态与交互
- 常态:白色或主题表面底色、清晰边框、轻微阴影。
- 悬停:边框略加深,底色轻微变化,不改变卡片尺寸。
- 选中:蓝色描边、浅蓝底、右上角勾选标记;通过内描边或等宽边框避免布局跳动。
- 键盘焦点:独立可见焦点环;使用原生按钮语义和选中状态属性。
- 运行中:绿色状态点 + “运行中”;待命:中性状态点 + “待命”。
- 失败:红色状态点 + “失败”,不把整卡大面积涂红。
- 未设官:虚线边框 + “未设官”;可查看职责,但不能对不存在的会话发送指令。
- 右侧栏提供「朝堂 / 任务」页签;点击「在朝成员」或「在办任务」统计卡分别切到对应页,切换不丢失当前选择。
- 聊天不在侧栏内重复实现;主会话与部门子会话都使用 DSH 原生消息流和输入框。
- 点击卡片只切换配置对象;“与该部门对话”负责跳转,避免误触导航。
- 发送期间按钮显示进度并防止重复提交;错误在当前配置区域说明。
## 6. 主题与层次
复用 DSH 的背景、表面、文字、边框和强调色变量。蓝色回退为 #4D6BFE;明亮模式的视觉参考为浅灰工作区、白色卡片和浅蓝选中底色。
深色模式保持同一结构,使用宿主深色表面与边框;不得保留刺眼白卡。状态同时使用文字和颜色,正文对比度以至少 4.5:1 为目标,可交互边界与焦点以至少 3:1 为目标。连接线比部门卡片边框更弱,但仍可辨认。
六部分组底色比工作区略深或略偏蓝,组内每个部门仍保持独立边框。配置区使用独立卡片,“与该部门对话”为主要入口,“保存模型设置”为次要按钮;消息发送按钮只存在于对应会话输入区。
## 7. 空间与响应式
按面板实际容器宽度适配,不能只依赖整个浏览器窗口宽度。
- 实现方式:`.sl-root` 声明 `container-type:inline-size;container-name:slpanel`,所有断点写成 `@container slpanel (max-width: …)`;`panel/lib/client.js` 里不得再出现视口 `@media (max-width: …)` 断点,`panel/test/client.test.js` 有回归测试守着这条。
- 1180px / 980px:整页与双栏形态的切换;侧栏形态下这两档不会生效。
- 620px 及以下:统计两列两行;三省与六部降为两列,卡片保持 104px 以上的可读宽度。
- 330px 及以下:三省与六部降为单列;组织层级用分组标题表达,不再强行绘制横线。
- 极窄宽度:使用单列卡片和分组标签,隐藏无法准确表达关系的树形横线,保留组织语义。
- 统计卡建议每张高64–72px,避免占据过多首屏空间。
- 采用自然纵向滚动,不固定过小高度导致文字截断;表单窄屏改为上下排列。
- 部门配置里的「最近活动」独占一行,最多两行后省略;不得与状态文字排在同一行互相挤压。
- 不直接按1024px生成图等比缩小;在320、360、371、400、440、480px容器中检查实际可读性。
## 8. 数据与实现边界
继续使用现有成员和任务投影生成统计,运行状态与任务状态分别计算。选择部门后配置区同步切换,复用已有会话导航、模型和指令发送逻辑。底层预设与部门角色配置保留,由系统管理;移除面向普通用户的手动预设切换入口,不因此删除底层角色初始化。
后续授权实现后,主要修改 panel/lib/client.js 中的卡片、组织分组和样式;必要的纯布局逻辑可放入 panel/lib/model.js。行为变化才补对应回归测试,不以字符串断言代替视觉验证。此方案不要求引入新的UI库,也不要求修改后端权限。
## 9. 部门设置与子 Agent 对话
本节取代上一轮设置卡中“发送任务”输入框的设计。用户指出给丞相下任务本来就在主会话,真正需要明确的是如何与子 Agent 对话。右侧栏里对应的是底部的「正在丞相主会话 / 与某部对话」按钮,见第 2 节的真实渲染图。
### 对话路径
- 给丞相下任务:在丞相主会话的原生输入框发送。
- 与部门聊天:选中部门卡片 → 点击“与工部对话”等具体入口 → 打开该成员现有的可继续子会话。
- 快捷入口:在 DSH 原生输入框输入 `@` → 选择已设官部门 → 直接进入该部门子会话,在同一个原生输入框继续输入并发送。候选只包含已有会话的部门;选择动作本身就是导航,不把当前会话中的普通文字静默改投给其他 Agent。
- 选中同步:进入某部门子会话时,右侧朝堂图自动选中该部门并切换配置区;返回丞相主会话时恢复选中丞相。切换只跟随实际会话,不按普通文本猜测接收人。
- 子会话显示历史消息、当前接收部门和原生消息输入框,支持继续追问与补充;不另造一套聊天存储或发送机制。
- 顶部提供“返回丞相主会话”,明确父子关系。原有“打开会话”入口改用具体接收方文案,降低歧义。
- 点击卡片仅选择部门;真正进入会话必须通过明确入口,避免误触跳转。
- 未设官或没有可继续会话时,入口不可用并解释原因;不能静默创建重复成员或将消息转发给其他角色。
- 子会话消息与主会话分别保存。不要暗示私聊内容会自动同步给丞相;如后续需要汇报功能,应单独规划明确的转发动作。
- 直接对话不改变部门权限、分工与审批边界。
### 设置卡
1. 身份:字徽、部门名称、职责摘要;固定职责应由实际角色绑定支持。
2. 模型:模型下拉、模型支持的推理等级、单一“保存模型设置”按钮;未修改时禁用,成功或失败有明确反馈。同名模型才补充友好的提供商名称。
3. 对话入口:“与工部对话”或“返回丞相主会话”。已处于该成员会话时显示“正在对话”,避免重复导航。
移除设置卡里的“下旨给丞相”、任务输入框、“下旨”或“发送任务”按钮;移除 Agent 预设输入、应用按钮和加载提示。内部标识可放入默认折叠的只读高级信息。底层预设仍由系统管理,旧会话角色不匹配时明确提示,不静默改写。
宽屏模型与推理等级并排,窄栏上下排列。预览图中的模型与推理等级只是示意,真实选项严格由模型能力目录决定。图中遗漏的统计区、卡片字徽和状态仍以其他章节为准,本图重点表示对话位置。
专项验收:设置区无重复消息输入框;子会话能查看历史并继续发送;实际接收方与会话标题一致;返回主会话不丢失历史;未设官入口正确禁用;不自动同步私聊或绕过既有权限。
## 10. 后续实施顺序
1. 建立卡片表面、边框、间距与状态样式。
2. 整理丞相、三省、六部分组与连接线。
3. 压缩统计区,梳理部门配置区。
4. 验证宿主明亮/深色主题和真实窄栏宽度。
5. 运行现有回归测试,检查会话跳转、模型选择和发送指令。
6. 获取真实界面截图,与设计图比对后再宣告视觉验收。
## 11. 验收标准
- 十席完整、无重复,吏部和礼部文字正确。
- 未选中的部门也有清晰边框,不能看起来只是浮动文字。
- 选中、运行、失败、未设官和键盘焦点可以区分。
- 六部全部属于尚书省,不产生错误的上下级连线。
- 统计使用实时投影,图片中的示例数字不会进入逻辑。
- 窄栏没有横向溢出,名称与状态不被裁切。
- 明亮与深色均可读,配置功能与会话入口保持可用。
- 真实界面视觉检查和必要回归测试都通过;生成模拟图不能替代实际截图验收。