12 KiB
12 KiB
三省六部面板:换环境开发交接方案
日期:2026-11-08
当前版本:0.5.1
状态:侧栏化改造与残留清理均已实现并通过 34 项本地测试;尚未在真实 DSH Host 里做最终视觉验收。
这张图由
scripts/preview.mjs渲染真实组件树 + 真实 CSS,再用 headless Chrome 截图(440 CSS px × 2 DPR),不是 DSH Host 的运行截图,也不是 AI 生图。同一脚本还产出 360px 窄栏、深色主题与任务页:
重新生成(需要放开沙箱,Chrome 无头模式要建 mojo 命名管道):
node scripts/preview.mjs --width=440 --view=court --theme=light --name=panel-sidebar-440-light --out=docs/preview
node scripts/preview.mjs --width=360 --view=court --theme=light --name=panel-sidebar-360-light --out=docs/preview
node scripts/preview.mjs --width=440 --view=court --theme=dark --name=panel-sidebar-440-dark --out=docs/preview
node scripts/preview.mjs --width=440 --view=tasks --theme=light --name=panel-sidebar-tasks-440 --out=docs/preview
只想要中间 HTML、不调 Chrome 时加 --html-only。最终验收仍然必须在真实会话右侧栏里完成。
1. 一句话目标
不要再维护一套整页面板或第二套聊天界面。聊天全部使用 DSH 原生输入框;三省六部的朝堂编制、任务流转和部门配置只停留在会话右侧栏,并通过 @ 直接进入部门子会话。
2. 已经完成的部分
- 十席角色:丞相、中书省、尚书省、门下省、吏部、户部、礼部、兵部、刑部、工部。
- 朝堂图为「丞相 → 三省 → 六部」,六部两排三列,同属尚书省调度。
- 部门为实体卡片:字徽、边框、状态点和中文状态;选中态有蓝边、浅底和勾选标记。
- 插件只注册会话头部入口与右侧栏页签,不再注册
main、sidebar.panellist或sidebar.panellist.actions。 - 右侧栏包含「朝堂 / 任务」页签、2×2 统计卡、朝堂图、部门配置和任务列表。
- DSH 原生输入框注册
@来源,列出已有会话的部门;选中后进入该部门子会话。 - 进入部门子会话时自动选中对应部门;返回丞相主会话时恢复选中丞相。
- 移除 Agent 预设编辑、重复的「下旨」输入框和独立聊天摘要。
- 复用 DSH 主题变量,支持明亮、深色与窄侧栏布局。
- 0.5.1 清掉侧栏化残留:46 个不再渲染的
sl-*类、无调用点的SanshengPinRow/DockButton/SidebarIcon,以及三个无规则的幽灵类名。 - 会话头部开关在拿不到会话时把原因显示在开关旁,不再静默回退;CSS 与组件的一致性由测试兜住。
- 版本更新到
0.5.1;CHANGELOG.md、panel/README.md、docs/panel-design.md已同步。
3. 当前验证结果
在 C:\Users\qyh15\三省六部 执行:
$node = 'C:\Users\qyh15\AppData\Local\Programs\DeepSeek Harness\DeepSeek Harness.exe'
$env:ELECTRON_RUN_AS_NODE = '1'
& $node --check panel/lib/client.js
& $node --test --test-isolation=none test/policy.test.js panel/test/client.test.js
& $node scripts/check-install.mjs
结果:
- 语法检查通过。
- 34 项测试全部通过。
scripts/check-install.mjs通过:panel 以 link 方式安装,client bundle 已注册。modeEnabled: false只表示「上朝」模式尚未启用,不表示面板不可用。- 清理前后做了像素级 A/B:用同一份
scripts/preview.mjs、同一组参数,分别渲染 0.5.0 快照(.scratch/preview-baseline/client.snapshot.js)与 0.5.1 的panel/lib/client.js,五组(440/400/360 明亮、440 任务页、440 深色)截图的 sha256 逐字节相同,证明删掉的 CSS 与组件确实不在渲染路径上。 - 体积变化:内联 CSS 40,963 → 28,346 字符(−30.8%),HTML 52,261 → 39,596 字节(−24.2%)。
尚未完成:真实 DSH Host 的视觉截图验收。当前只有 Chromium 对真实组件树的渲染图。
4. 代码地图
| 文件 | 作用 | 当前注意点 |
|---|---|---|
panel/lib/client.js |
前端全部实现:CSS、React 组件、DSH 槽位、@ 来源、宿主适配 | 约 1890 行,单文件自包含 bundle;修改后必须跑 --check |
panel/lib/model.js |
十席定义、布局、状态、模型切换等纯逻辑 | 与 client 内自包含常量需要同步 |
panel/index.js |
策略侧 formation/decree 提示词 | 与前端职责保持一致 |
index.js |
Agent Preset 策略、角色工具权限 | 不得随意放宽写入/命令权限 |
panel/test/client.test.js |
面板结构与行为测试 | 使用最小 React 替身,useState 不自动更新 |
test/policy.test.js |
策略与权限测试 | 与客户端测试合计 34 项 |
scripts/check-install.mjs |
安装一致性检查 | 已改为校验右侧栏注册、拒绝旧的 main/panellist |
scripts/preview.mjs |
零依赖预览生成器:vm 加载真实 bundle → 渲染真实组件树 → HTML → headless Chrome 截图 | 需放开沙箱跑 Chrome;--html-only 只出 HTML |
docs/panel-design.md |
设计依据与验收标准 | 已更新到侧栏结构 |
CHANGELOG.md |
版本变更 | 顶部已切到 0.5.x 线 |
前端关键位置
SanshengPanel:右侧栏主组件,状态含sidebarView、selectedRole、activeChildId。SeatCard:部门实体卡片。courtStats:四张统计卡的数据投影。seatMentionOptions/createSeatMentionSource/registerSeatMentions:原生@来源。childRoleOf:由子会话 id 反查部门角色,用于自动选中。openSeatConversation/returnToLead:进入部门会话与返回丞相。apply:只注册三个原生槽位:conversation.session.header.actionssidebar.right.pane.tabsidebar.right.pane.tab.title
5. 不可破坏的决策
- 不恢复整页面板。不要把
main、sidebar.panellist加回来;这会让用户再次看到第二套聊天和重复入口。 - 不造第二套聊天存储。消息只在 DSH 原生会话里发送与保存。
- 不静默改投消息。普通
@文本不能自动把当前会话消息转发给别的 Agent;进入哪个会话,消息就发给谁。 - @ 只列已有会话的部门。未设官、无子会话的部门不能伪造入口。
- 权限不因界面变化而放宽。这只是客户端面板调整,不修改
index.js的工具边界。 - 版本历史只用 Git。不要创建
backup/、时间戳副本或“最终版”目录。
6. 换环境后的推进顺序
第 1 步:带走代码,而不是复制一堆副本
当前工作树有未提交改动。换环境前先在原环境提交一次,或生成 Git bundle:
cd C:\Users\qyh15\三省六部
git add -A
git commit -m "feat(panel): move court into sidebar and use native chat mentions"
如果目标环境不能直接访问原磁盘:
git bundle create sansheng-liubu-0.5.0.bundle --all
到新环境:
git clone sansheng-liubu-0.5.0.bundle 三省六部
不要手工拷贝整个工作区,也不要把 node_modules、.chrome-preview 或临时 HTML 带过去。
第 2 步:确认宿主与安装方式
新环境先确认:
- DSH 版本支持
sidebar.right.pane.tab与inputTriggers.registerSource。 - profile 的
dsh.profile.bundles含dsh-sansheng-liubu-panel。 - panel 以
link:或可编辑的开发方式安装,避免每次改代码都重新打包。 - 如需「上朝」模式,再执行
node scripts/mode.mjs on;面板本身不需要先开模式。
第 3 步:真实宿主验收
重启 DSH Host,不是只刷新浏览器。然后:
- 打开一个会话,确认右侧栏出现「三省六部」页签。
- 检查「朝堂 / 任务」切换;点击「在朝成员」「在办任务」统计卡。
- 在原生输入框输入
@,确认只出现已有会话的部门。 - 选择
@工部,确认进入工部子会话,右侧栏自动选中工部。 - 在工部会话发送一句话,确认消息进入工部而不是丞相会话。
- 点击「返回丞相」,确认回到父会话且选中恢复丞相。
- 在 360、400、440、480px 侧栏宽度下检查:无横向滚动、卡片名称和状态不被裁切。
- 切换 DSH 明亮/深色主题,确认没有刺眼白卡或不可读状态。
第 4 步:处理剩余技术债
这些不阻塞功能,但建议在下一个环境完成:
删除已不再渲染的旧 CSS:0.5.1 已删除 46 个死类、约 117 行规则(CSS 374 → 257 行)。删除未引用的:两者与SanshengPinRow、DockButton包装SidebarIcon导出均已删除(确认外部无消费方)。检查会话头部开关在“当前没有会话”时的反馈:0.5.1 已把失败原因显示在开关旁(role="status"),并有回归测试。- 视真实宿主表现,决定是否保留
remote.agentPresets注入;高级信息仍读取只读预设,不要贸然删除底层能力。 - 为真实右侧栏补一张宿主截图,替换/补充
panel-preview-sidebar.png作为验收证据。
7. 可直接粘贴给新环境 Agent 的交接提示
你在 C:\Users\qyh15\三省六部 继续一个 DSH Web 客户端插件项目(dsh-sansheng-liubu-panel,当前 0.5.1)。
用户目标:三省六部面板只存在于会话右侧栏;聊天必须复用 DSH 原生输入框;在原生输入框用 @ 选择部门后进入该部门子会话,并自动选中右侧对应部门;不要再恢复整页面板或第二套聊天。
先读:
- docs/panel-handoff.md
- docs/panel-design.md
- panel/lib/client.js 中 SanshengPanel、createSeatMentionSource、apply
- panel/test/client.test.js
- scripts/check-install.mjs
当前状态:侧栏化与残留清理已实现,34 项测试通过,check-install 通过,工作树可能尚未提交。不要创建备份目录。
请先:
1. 运行现有测试和 check-install,确认基线;
2. 在真实 DSH Host 重启后验收右侧栏、@ 导航、自动选中、返回丞相;
3. 修复真实宿主暴露的问题,并补回归测试;
4. ~~清理不再渲染的旧 CSS/组件~~(0.5.1 已完成,后续只需保持);
5. 更新 CHANGELOG、README 和设计文档,保持 0.5.x;
6. 用 Git 提交,不要建时间戳副本。
硬约束:
- 不注册 main、sidebar.panellist、sidebar.panellist.actions;
- 不新增聊天存储,不静默把消息转发给其他 Agent;
- @ 候选只含已有会话的部门;
- 不改变 index.js 的角色工具权限边界;
- 每个设计调整附一张新的实际预览图。
8. 验收标准
- 右侧栏可打开,朝堂与任务可切换。
- 十席完整,六部同属尚书省,无错误上下级连线。
- 部门卡片在窄栏仍清晰,名称与状态不裁切。
@只列已有会话的部门,选择后进入正确子会话。- 进入子会话自动选中对应部门,返回后恢复丞相。
- 原生输入框发送的消息不会误投给其他 Agent。
- 明亮/深色主题都可读,焦点与选中状态可见。
- 34 项测试、
node --check、git diff --check、check-install全部通过。 - 有真实 DSH Host 截图作为最终视觉证据。
9. 已知风险
- 静态预览不能证明 DSH 实际侧栏宽度、滚动容器和槽位渲染完全一致;必须实机验收。
better-sidebar与宿主自带sidebarRight两条注册路径都要验证;只测其中一条不够。- 测试用的最小 React 替身不会执行真实点击,交互问题需要宿主手测或补更真实的组件测试。
- 若新环境 DSH 版本没有
inputTriggers,@入口应静默不可用,但其余侧栏功能不能因此崩溃。



