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

12 KiB
Raw Blame History

三省六部面板:换环境开发交接方案

日期:2026-11-08 当前版本:0.5.1 状态:侧栏化改造与残留清理均已实现并通过 34 项本地测试;尚未在真实 DSH Host 里做最终视觉验收。

右侧栏 440px 明亮主题

这张图由 scripts/preview.mjs 渲染真实组件树 + 真实 CSS,再用 headless Chrome 截图(440 CSS px × 2 DPR),不是 DSH Host 的运行截图,也不是 AI 生图。同一脚本还产出 360px 窄栏、深色主题与任务页:

360px 窄栏

440px 深色主题

任务页

重新生成(需要放开沙箱,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.actions
    • sidebar.right.pane.tab
    • sidebar.right.pane.tab.title

5. 不可破坏的决策

  1. 不恢复整页面板。不要把 main、sidebar.panellist 加回来;这会让用户再次看到第二套聊天和重复入口。
  2. 不造第二套聊天存储。消息只在 DSH 原生会话里发送与保存。
  3. 不静默改投消息。普通 @ 文本不能自动把当前会话消息转发给别的 Agent;进入哪个会话,消息就发给谁。
  4. @ 只列已有会话的部门。未设官、无子会话的部门不能伪造入口。
  5. 权限不因界面变化而放宽。这只是客户端面板调整,不修改 index.js 的工具边界。
  6. 版本历史只用 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,不是只刷新浏览器。然后:

  1. 打开一个会话,确认右侧栏出现「三省六部」页签。
  2. 检查「朝堂 / 任务」切换;点击「在朝成员」「在办任务」统计卡。
  3. 在原生输入框输入 @,确认只出现已有会话的部门。
  4. 选择 @工部,确认进入工部子会话,右侧栏自动选中工部。
  5. 在工部会话发送一句话,确认消息进入工部而不是丞相会话。
  6. 点击「返回丞相」,确认回到父会话且选中恢复丞相。
  7. 在 360、400、440、480px 侧栏宽度下检查:无横向滚动、卡片名称和状态不被裁切。
  8. 切换 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,@ 入口应静默不可用,但其余侧栏功能不能因此崩溃。