dsh-sansheng-liubu/V1.0-工作台修复方案.md

14 KiB
Raw Permalink Blame History

三省六部 v1.0 工作台修复方案

日期:2026-11-07
审查基线:master / dd62068,代码版本 0.3.1。
文档性质:实施建议与验收方案;不代表代码已修复或宿主集成已验证。

1. 目标与范围

将三省六部做成一个可直接工作的工作台:用户在同一页面完成下达任务、确认方案、查看部门执行、打开交付文件和定向修改。底层继续使用 DSH 会话与 Agent Teams,但由程序管理绑定与生命周期,不要求用户反复手动新建聊天、切换预设或组建朝班。

优先完成三省六部自身 v1.0,再评估 DS Bot 适配。当前不迁移运行时、不 fork DS Bot、不重写 DSH,也不为工作台重新实现已有文件树或通用聊天编辑器。

保留已确认原则:

  • 丞相负责分流与协调,中书负责规划,门下负责审议与验收,尚书负责执行调度,六部按专业执行。
  • 门下准奏不等于用户授权;执行必须在用户批准范围内。
  • 只启动需要的部门,不为凑六部拆任务。
  • 用户指定部门时直接投递原话、附件与修改范围。
  • 首次交付统一审核;交付后的定向修改默认不重走完整流程。
  • 模型由用户配置,技能绑定角色;不硬编码禁止某个模型家族。

2. 当前完成情况与阻断原因

已有基础:插件入口、预设、角色提示词、面板入口、部分会话导航与投递、模型路由、工具 guard、任务依赖准入检查。现有 22 个单元测试通过,但没有覆盖开新朝堂的完整路径。

问题 证据位置 影响与处理方向
未定义的投递函数 panel/lib/client.js:1074 sendPrompt 不是当前作用域变量,创建会话后触发 ReferenceError;提取共用投递函数,所有入口调用同一实现
依靠新 ID 猜测创建结果 panel/lib/client.js:1048–1060 可能重复创建或误认并发会话;核实宿主契约,以返回标识或关联事件精确绑定
错误被吞掉或显示成功 panel/lib/client.js:1050,1066–1074 用户无法确定是否送达;统一结构化错误与界面状态
成员创建职责冲突 index.js:81、panel/lib/client.js:1084 尚书不能创建 teammate;尚书提出需求,由 Lead 执行创建
模型选择被覆盖 index.js:215–220 界面选择与实际请求不一致;统一配置来源与生效规则
权限覆盖不完整 index.js:132–154 未枚举工具默认放行,任务准入不等于授权;建立与宿主配合的权限检查
角色与文档不一致 index.js:54–60、TODO.md 实现只有工礼兵,未补齐六部;按已确认职责对齐
版本口径不一致 package.json、CHANGELOG.md、TODO.md 无法凭文档判断交付状态;发布时依据实际验证统一

以上是源码和已有复现支持的发现。DSH startSession 的准确契约尚未核实,不能假定它一定返回 session ID,也不能先编造接口再开发。

3. 工作台交互

建议布局:

顶部:项目 / 当前任务 / 总体状态 / 设置
左侧:复用现有文件树 + 任务入口 + 交付入口
中间:所选部门对话、方案与授权卡片、任务输入
右侧:丞相—三省—六部组织图 + 所选角色配置
底部:当前阶段、等待对象、阻塞原因、最近产出

工作台打开时应立即展示结构。部门卡片常驻,执行成员按需建立;尚未启动的部门显示“未启动”,不能冒充在线成员。没有任务时显示可用的输入区,不以“组建朝班成功”作为页面可用的前提。

用户点击部门后,在工作台中显示对应对话。若宿主不提供可嵌入对话组件,先验证可用扩展点,再确定替代呈现;不得以自动跳转普通聊天页冒充完成工作台验收。

4. 实施阶段

阶段 A:核实宿主接口并确定实现边界

先核实以下能力的真实签名、返回值、异步错误和版本兼容性:

  1. 工作区定位、会话创建、预设应用、会话读取及订阅。
  2. 指定会话投递文本与附件、接收回执、运行中消息的处理语义。
  3. 工作台内嵌对话或复用聊天组件的扩展点。
  4. Lead 创建成员、成员身份、任务依赖与完成事件。
  5. 角色模型/推理等级切换及实际生效时点。
  6. better-sidebar 文件树复用及页面注册接口。
  7. 宿主权限与人工审批凭证、共享任务元数据能否保存所需字段。

产出一份接口核对表,逐项标注“已验证 / 不支持 / 待验证”。若会话创建只能触发 UI 草稿而不真正建档,应采用宿主支持的服务路径或扩展点,不再使用轮询猜测弥补契约差异。

完成标准:可通过最小实验准确创建并识别一个指定工作区和预设的会话,获得明确的投递结果;确认中间对话区的可实现方式。

阶段 B:修复会话连接与错误处理(最高优先级)

  • 将投递逻辑提取为有明确作用域的共用函数,供普通下旨、组建指令及工作台调用;不依赖不确定的 this 绑定。
  • 用明确的创建结果或请求关联事件绑定会话;禁止选取“任意新出现的会话”。
  • 对同一创建动作实行 single-flight,运行中禁用重复提交;超时进入“结果待确认”,先对账,不自动再次创建。
  • 不吞同步异常、Promise rejection 或投递失败。统一返回 ok、stage、sessionId(已知时)、errorCode、用户可读说明和允许的恢复动作。
  • 会话创建成功但投递失败时保留绑定,只允许向该会话重试投递;不能返回完整成功,也不自动删除用户会话。
  • 消息重试需核对宿主是否支持幂等标识或送达查询。结果不明时提示用户确认,不能盲目重复投递。
  • 将普通 lastAction 变量改为可订阅状态,及时显示创建、投递、失败和恢复进度。
  • 所有按钮路径具备错误捕获和清理逻辑;卸载页面时清理订阅与计时器。

完成标准:单击只产生一个目标会话;并发创建其他会话不误投;投递失败不显示成功;恢复操作不重复建会话。

阶段 C:建立工作台状态与持久绑定

建议拆分职责,不直接在大型客户端 bundle 内堆叠新逻辑:

  • 宿主适配层:封装经验证的 DSH API。
  • 工作台状态层:维护绑定、选择、加载状态和错误。
  • 流程层:管理授权、依赖与交接。
  • 展示层:组织图、对话、任务、配置和产出视图。

具体文件拆分应先确认现有源码与构建来源;如果客户端是构建产物,修改源文件并重新构建,避免源文件和 bundle 各维护一套逻辑。

建议数据模型:

对象 必需信息
工作台绑定 schemaVersion、workspaceId、工作台实例 ID、Lead sessionId、role→member/session 映射
任务 原始请求、目标部门、计划版本、负责人、依赖、允许范围、状态、产出引用
授权记录 用户动作来源、批准的计划版本与范围、时间、失效/撤销状态
审核记录 计划或成品、对象版本、结论、证据、次数、未解决问题
交付记录 文件引用、可编辑源文件、主责部门、验证状态

通过宿主允许的存储服务持久化。以 workspaceId 与工作台实例标识隔离,不用“最新会话”自动覆盖已有绑定。模型输出、角色消息或任务标题不能伪造用户授权。

刷新后核验会话是否仍存在、工作区是否匹配。会话缺失时显示可恢复状态,保留记录;重新绑定应明确展示对象,不能静默绑定其他会话。

成员可用性和任务状态分别展示:成员 inactive 不代表任务完成;任务完成必须有结果记录。

完成标准:刷新、切换项目、重启后恢复正确绑定;同一页面完成部门切换、投递、查看任务与打开产出。

阶段 D:统一角色、模型和流程

角色补齐为丞相、三省、吏户礼兵刑工六部。各角色职责以当前 TODO 已确认内容为准,角色 ID 必须唯一,避免吏部与礼部拼音重名。角色元数据集中定义,界面、提示词和策略共用。

创建与派工职责:尚书提出依赖、分工和成员需求;Lead 创建需要的成员;执行部门领取就绪任务。普通问答不强制创建全套任务链。

模型配置:统一用户选择、持久配置和请求路由的来源;明确角色覆盖与默认继承关系。删除与已确认选型冲突的硬编码限制。显示实际 provider/model/推理等级;不可用时报告错误或提供选择,不静默更换模型。

首次交付流程:

接收需求 → 中书拟案 → 门下审议 → 用户确认
        → 尚书按依赖派工 → 所需部门执行与自检
        → 尚书组织完整产出 → 门下审核 → 交付

程序应验证:

  • 用户确认绑定具体计划版本和范围;计划扩大或实质变化后需重新确认。
  • 调度须同时满足用户授权、前置任务完成、负责人及写入范围有效。
  • 独立任务可以并行,冲突写入按顺序执行或采用已验证的隔离机制。
  • 防止同一任务因重复事件被多次派发;失败只阻塞依赖分支。
  • 计划审议与成品审核分别计数,默认各一次;不得自行无限返工。
  • 审核后的修正与未复审状态如实记录,不能修正后自动标为审核通过。
  • 用户指定部门的局部修改直接投递,默认不重新拟案、合成和发布;扩大范围才重新请求确认。

完成标准:分别跑通单部门任务、并行任务、串行依赖与定向修改,能够说明每次推进依据的授权和完成证据。

阶段 E:补齐权限执行与交付

  • 明确哪些限制由宿主沙箱、审批系统承担,哪些由插件承担;插件不能绕过宿主权限。
  • 按工具能力与副作用检查准入,不把“未在黑名单中”视为只读安全。
  • 未知或未分类工具先阻止本次执行并说明所需授权,避免无声放行。
  • 文件写入检查真实目标与允许范围;路径归一化和链接处理交给可信文件服务,不能只用字符串前缀判断。
  • 命令行与远程执行不能仅凭存在 writeScopes 就视为安全;受宿主沙箱和权限档位约束。无法证明范围约束时不得声称已实现强隔离。
  • 用户审批凭证由可信宿主或界面操作产生,不接受模型自行填写的 humanSigned 作为真实签字。
  • 检查现有 approval、writeScopes 等字段与宿主任务 schema 的兼容性;不支持时使用经过验证的插件存储映射,不能往宿主塞未支持字段。
  • 首次交付附文件、可编辑源文件、主责部门、审核结果、修正情况及未完成项。

完成标准:只读角色写入、未授权执行、越界写入和未知副作用工具不能绕过检查;正常获授权任务能够完成。

阶段 F:v1.0 验收与发布

测试分三层:纯逻辑单测、宿主适配集成测试、当前 DSH GUI 人工可见的端到端验收。现有 22 个测试保留,不以数量代替行为覆盖。

场景 必须看到的结果
首次打开工作台 页面结构可用,可输入任务,未启动部门状态明确
创建慢、失败、重复点击 不重复创建,阶段及恢复动作准确
同时创建其他会话 不误认、不误投、不污染其他对话
创建成功但消息失败 显示部分完成状态,保留准确会话绑定
刷新或重启 恢复原工作台任务与会话;缺失对象明确提示
用户未确认计划 不进入执行
改模型及推理等级 下一次实际请求使用所选配置
多部门并行和依赖 只启动就绪任务,写入冲突受控,无重复派发
审核不通过或执行失败 留下证据,按规则修正或报告阻塞,不假报成功
打开交付和定向修改 可打开源文件并直接联系主责部门,不强制全流程重跑

按影响面重建 Web 产物,并在当前实际 DSH GUI 中刷新验证;不能另起一个服务后声称原 GUI 已更新。宿主插件代码变化若需重启,应明确重启后再验证。

通过后统一 package、面板版本、README、CHANGELOG 和 TODO。保留真实恢复历史,将旧规划标明历史状态,不编造过去版本的验收记录。按独立变更使用 Git 记录与回退,不创建时间戳备份。

5. 推荐拆分与实施次序

  1. 连接层修复:接口核对、确定性绑定、投递函数、错误状态、回归测试。
  2. 工作台基础:状态存储、刷新恢复、同页对话与部门选择、文件和任务入口。
  3. 角色与配置:补齐六部、集中角色定义、按需创建、模型配置实际生效。
  4. 流程与权限:可信用户授权、依赖与防重、审核次数、权限及范围检查。
  5. 交付与验收:产出映射、定向修改、完整宿主验收、文档与 v1.0 版本对齐。

第 1 项应先独立完成并验证。之后界面与角色配置可在边界明确时并行;涉及同一客户端文件、共享状态结构或接口的改动必须先约定再合并。每一项完成都应提供可复核结果,不先改版本号再补实现。

6. DS Bot 后续事项

v1.0 完成后再评估 DS Bot 的长期 Bot、群聊派活、阶段 Goal、分层记忆、独立模型与审批机制。先核对接口、版本、许可证、迁移和维护成本,再决定配置复用、薄插件适配或其他方式。

本方案不承诺 DS Bot 可直接承载现有三省六部,也不把公开文档能力等同本机兼容验证。

参考:https://github.com/Fei2411/DS-Bot/blob/main/README.zh.md

7. v1.0 最终完成标准

用户始终留在三省六部工作台中,能完成“下任务 → 确认方案 → 按需执行 → 查看产出 → 指定部门修改”;会话不串线、消息不误投、失败不假报、模型配置真实生效、授权边界可验证、刷新后可恢复,并有当前宿主上的验证证据。