feat(workbench): 三省六部独立工作台 v0.1(数据层/宿主服务/HTTP/前端/Docs)

按 docs/v0.1-实施方案.md 落地 v0.1:

- workbench/core:ID、十席角色、状态机、账本(含引用表/幂等/事件 outbox)、任务与完成判定
- workbench/host:业务服务(项目隔离、CAS 配置、派发幂等、结果去重、目录冲突识别、
  成果修订链、成果失效投影)、契约行解析、会话适配、派发/对账、12 条 HTTP 路由
- index.js:接线 createWorkbenchHost(按账本路径引用计数,mock ctx 自动跳过)
- workbench/panel:手写客户端 bundle,接管 main.conversation(priority -1),
  右侧固定拓扑节点树 + 朝堂/任务/成果 + 模型设置 + 移动端抽屉;深色与浅色
- scripts:workbench-install.mjs(装/卸 profile bundle)、preview-workbench.mjs(离线预览)
- docs:实施方案、宿主能力记录、接线与契约、A01–A28 验收记录;预览图 4 张

测试:203 tests / 203 pass(policy 11 + core 60 + service 25 + host 16 + routes 29
+ panel 44 + workbench panel 18)

未提交(保持原样):README/TODO/V1.0 方案/docs/panel-*.md/panel/lib/client.js 的既有改动。
This commit is contained in:
qyh15 2026-11-10 10:45:29 +08:00
parent 0bf18aacce
commit 1203f1374e
36 changed files with 13941 additions and 0 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 50 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 97 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 93 KiB

376
docs/v0.1-实施方案.md Normal file
View File

@ -0,0 +1,376 @@
# 三省六部独立工作台 v0.1 实施方案
日期:2026-11-09
用途:交给执行者的实施与验收依据。当前只完成方案编写,未实现、安装或迁移。
版本含义:v0.1 是新架构的首个里程碑,不代表把现有 0.9.2 软件包直接降级为 0.1.0。
## 1. 执行摘要与约束优先级
要交付的是 DSH 内的独立工作台:左侧直接使用 better-workspace-group 现有项目树,中间显示所选部门的真实会话,右侧显示可调宽的部门树、模型配置以及任务与工作成果。每个项目的每个部门有独立 session;程序定向传递必要上下文,模型承担专业判断。多个项目可以同时运行,配置、会话、结果和停止操作互不串线。
用户已经确定的硬要求:
1. 独立主页面,不依附于某个普通聊天或丞相 Team;不要求 spawn_teammate 才能找到部门。
2. 复用现有项目树,不新建项目列表,不恢复顶部项目标签。分组不是项目。
3. 项目隔离从首版实现,服务侧检查归属,不能只过滤前端列表。
4. 右侧树状方块:丞相顶端居中;下一排中书、尚书、门下;尚书连接六部这一同级分组。六部两排展示,不能画成上下级。
5. 每个部门独立改模型,修改只影响当前项目当前部门;运行中的请求保持原配置。
6. 中央聊天优先保留空间,右栏可拖动、收起、恢复;白蓝浅色、跟随宿主的深色模式,紧凑字体。
7. 工作成果由 Agent 产生,用户在聊天中提供材料;成果区没有要求用户上传交付物的流程。
8. 使用 Git 管理版本。不创建 backup、时间戳副本或“最终版2”代替版本历史。
本文的字段、模块名和开发顺序是实施设计,不是已存在的 DSH API。与宿主真实接口有冲突时,先写明证据和适配方案;不得把虚构调用当成已验证能力。需求冲突按“用户最新指示 → 本文首版范围与已确认视觉要求 → 总体规划 → 历史资料”处理。
相关资料: [总体规划](../V1.0-工作台修复方案.md)、[视觉要求与预览](panel-design.md)、[待办](../TODO.md)、[交接入口](panel-handoff.md)。旧 Team/侧栏规则不具有新架构约束力。
## 2. v0.1 范围与完成定义
本方案建议:开发中先以丞相、工部两席跑通闭环,最终 v0.1 扩展到全部十席的独立会话与相同基础能力。两席闭环不能冒充十席完成。其余部门未接通时明确标注“尚未接通”,不能显示待命或可执行。
### 2.1 必须交付
| 能力 | 首版要求 |
|---|---|
| 页面入口 | “上朝”进入独立工作台,同页聊天,无需父会话 |
| 项目入口 | 真实接入现有项目树选择和稳定工作区 ID |
| 十席 | 丞相、三省、六部均可按需创建独立会话、直聊、恢复历史 |
| 配置 | 每席保存明确 provider/model/受支持 effort;实际运行可核对 |
| 基础交接 | 创建任务单、定向发送上下文与材料、回执、执行结果、回传 |
| 用户直聊 | 只发当前部门;切换部门保留各自草稿 |
| 成果 | 文件引用、主责部门、来源任务、真实检查、局部修改入口 |
| 运行控制 | 会话串行投递,跨项目可并行,取消准确指向运行 |
| 可靠性 | 幂等、失败/未知状态、刷新恢复、宿主重启后的对账 |
| 隔离 | 会话、配置、材料、记忆、权限、任务及文件边界验证 |
| 视觉 | 已确认三栏、调宽、居中、浅深色、手机抽屉、键盘可用 |
| 验收 | 单元/集成测试及真实 DSH GUI 双项目端到端证据 |
### 2.2 后续版本再做
完整自动化的“中书规划 → 门下审议 → 尚书派工 → 六部执行 → 成品审核”引擎、多层任务 DAG、自动重规划、无限层级子任务、自建技能市场、跨项目共享、自动迁移旧 Team、自动压缩换 session、成本统计仪表盘和进度百分比均不属于 v0.1。
首版可以由用户或丞相选择需要的部门,以单任务、单主责执行和结果回传构成闭环;不同部门的独立任务可并行,但同目录写冲突必须协调。不要为了自动化朝廷流程阻塞基础聊天和项目隔离。不要把十席常驻展示理解为进入页面就启动十次模型请求。
### 2.3 两条必须演示的业务路径
路径 A:用户在项目 A 找丞相提出明确工程任务 → 丞相通过受控交接操作提交工部任务单 → 程序创建/定位工部独立会话并发送必要材料 → 工部执行和检查 → 结构化报告登记结果与源文件 → 丞相收到定向结果并汇报。此时项目 B 同时运行独立任务,配置和消息保持隔离。
路径 B:用户在成果区点击“找主责部门修改” → 工部会话得到用户指定修改、成果版本及来源任务 → 修改原工作文件 → 新增修订记录和检查结果。无需重新启动整套三省流程。普通问答不强制生成任务。
## 3. 第一阶段必须核实的宿主能力
执行者先只读核实实际安装版本和源码;当前仓库中的调用痕迹只是调查线索。不得凭接口名字假设权限、返回值、完成语义或跨项目安全性。
建立 [宿主能力记录](host-capabilities.md)(实施时创建),每项填写:宿主/插件版本、源码路径与行号、调用签名、返回值、错误语义、最小验证、结论、需改动的仓库。状态只能是“已验证 / 需要扩展 / 未确认 / 不支持”。
| 项目 | 要取得的证据 | 阻塞条件 |
|---|---|---|
| 主页面扩展 | 可注册独立页面、导航、卸载行为 | 只能渲染旧聊天 sidebar |
| 项目树 | 插件真实标识、稳定 workspace ID、选择事件、初始选择、重命名/移动/删除行为 | 只能读取 DOM 文本或依赖名称猜测 |
| 内嵌聊天 | 组件生命周期、传入 session ID、原生历史/附件/输入/审批能力 | 只能跳去外部聊天页 |
| 独立 session | 创建参数、准确 ID、工作目录、角色配置、创建幂等/可查询性 | 只能扫描“最新会话”猜 ID |
| 消息投递 | 指定 session、文本、附件、消息 ID、接收回执 | 只能把文本塞进当前输入框 |
| 运行关联 | hostRunId 与消息/dispatch 的关联、终态、取消、重启查询 | 只有通用 idle 状态且无可追溯终态 |
| 模型目录 | provider/model ID、effort 枚举、可用状态、实际请求配置 | 只能改全局默认或无法核对生效 |
| 配置/工具权限 | 会话独立配置、技能绑定、宿主审批和写入边界 | 角色提示词承担实际权限控制 |
| 材料/记忆 | 附件授权引用、检索范围、全局记忆注入的开关与作用域 | 无法阻止其他项目材料自动进入 |
| 存储 | 宿主允许的位置、原子更新/事务、版本、事件恢复 | 仅浏览器 localStorage 保存任务账 |
| 主题/构建 | 宿主主题令牌、真实客户端构建和加载方式 | 改源码但当前 GUI 未加载 |
项目树可能只提供 workspaceId,没有另一个 projectId。此时在插件中生成稳定 projectId,并与 hostWorkspaceId 建唯一绑定;不要强迫宿主增加同义标识。若宿主原生 ID 足够稳定,也可使用该 ID 作为内部项目键,须记录决定。绝不能用目录名、树行号或显示名称作主键。
若缺少核心能力,交付最小宿主扩展提案和可复现证据。先完成不依赖该能力的纯逻辑、测试和视图工作;明确阻塞集成部分,不以假数据宣布完成。若需要修改本仓库外的宿主或第三方插件,说明具体仓库与变更边界,由该处适用权限控制;不要直接改安装包内的 app.asar 当成可维护实现。
DS Bot 仅为页面组织参考。当前没有核实其真实上游地址、版本或许可证。需要借用代码时先核实并记录授权;不为寻找参考引入第二套会话运行时。
## 4. 分层与复用策略
建议分为四层:工作台 UI → 项目服务/任务服务 → 会话及宿主适配层 → DSH 原生能力。任务调度必须在可持续运行的服务侧,关闭页面不会停止派发和结果处理。UI 订阅投影,不承担唯一调度者职责。
| 模块(建议名称) | 职责 |
|---|---|
| WorkspaceAdapter | 承接现有树选择、稳定 ID、生命周期 |
| SessionAdapter | 创建/查询 session、投递、运行查询/取消、原生聊天接入 |
| ModelAdapter | 目录、参数校验、明确配置快照与实际生效核对 |
| ProjectService | 项目和部门绑定、归属校验、并发版本更新 |
| ContextBuilder | 按任务构建最小上下文包、校验材料及版本 |
| DispatchService | 持久队列、幂等、单会话串行、公平并发 |
| ResultService | 校验报告、关联运行、成果登记和回传 |
| Reconciler | 启动对账、断线恢复、未知状态核查 |
| WorkbenchView | 三栏、树、会话容器、任务与成果、设置 |
这些是内部职责边界,不要求为了形式拆成十个软件包。先用本仓库技术栈,优先已有依赖;新增依赖需说明必要性。
现有[策略入口](../index.js)可参考角色职责,但必须拆除以 membership 决定身份的默认逻辑,否则所有独立会话可能都变成丞相。[旧客户端](../panel/lib/client.js)可参考主题、模型选择与注册方式,但不复用父会话/Team 投影作为状态源。[旧桥接入口](../panel/index.js)中的组建提示词不能作为新会话创建流程。[纯逻辑模块](../panel/lib/model.js)的角色定义需核对后复用。
先看 git status/diff,保护执行者开始前已有改动。不要整文件覆盖未理解的用户修改,不自动迁移旧 session。旧功能如需保留,用明确模式边界区分;新工作台不能误执行旧 Team 注入。
## 5. 身份与数据模型
以下是逻辑字段建议,不指定数据库产品。聊天正文继续由 DSH 保存;插件仅存业务账、引用和必要交接快照。所有服务入口必须从可信宿主上下文确定调用身份,再验证传入 ID;模型填写的 projectId 不能成为授权依据。
### 5.1 角色标识
| roleId | 中文 | 首版职责 |
|---|---|---|
| lead | 丞相 | 接需求、分流、协调、汇报 |
| zhongshu | 中书省 | 调查、澄清、规划 |
| shangshu | 尚书省 | 分工建议、组织交付 |
| menxia | 门下省 | 审议与整体审核 |
| libu | 吏部 | 角色和技能配置建议 |
| hubu | 户部 | 数据、表格、计算 |
| lipu | 礼部 | 文档、内容、呈现 |
| bingbu | 兵部 | 环境、调试、部署 |
| xingbu | 刑部 | 测试与风险检查 |
| gongbu | 工部 | 代码实现与工程产出 |
核对现有标识后建立显式兼容映射,尤其吏部与礼部不可混用。修改中文显示名不改变 roleId。吏部的职责不赋予它绕过用户授权修改权限或其他项目设置的权力。
### 5.2 核心记录
| 实体 | 必要字段 |
|---|---|
| Project | id、hostWorkspaceId、displayNameCache、canonicalRoot、status、schemaVersion、revision、timestamps |
| DepartmentBinding | projectId、roleId、currentSessionId(nullable)、bindingGeneration、historySessionRefs、creationRequestId、revision |
| DepartmentConfig | projectId、roleId、providerId、modelId、reasoningEffort(nullable)、rolePromptVersion、skillRefs、permissionRef、configRevision |
| Task | id、projectId、title、objective、acceptance、ownerRoleId、sourceRoleId、originMessageRef、scope、status、activeAttemptId、revision |
| Dispatch | id、projectId、taskId、attemptId、sourceSessionId、targetSessionId、bindingGeneration、contextPacketId、idempotencyKey、status、hostMessageId、timestamps |
| Attempt | id、projectId、taskId、dispatchId、sessionId、hostRunId、effectiveConfigSnapshot、state、error、startedAt、endedAt |
| ContextPacket | id、projectId、taskId、version、相关原始消息引用及必要摘录、objective、constraints、authorizationRefs、materialRefs、scope、expectedOutputs、returnTarget |
| Result | id、projectId、taskId、attemptId、reportVersion、summary、artifactRefs、checks、remainingItems、blockedReason、sourceMessageRef |
| Artifact | id、projectId、taskId、ownerRoleId、fileRef、displayName、mediaType、versionOrHash、verification、sourceResultId |
| AuthorizationRef | id、projectId、sourceHumanEvent、scope、planVersion、hostApprovalRef、status |
| Outbox/EventInbox | eventId/idempotencyKey、projectId、相关实体、处理状态、序号/游标、时间戳 |
授权记录只引用真实人类授权或宿主批准;摘要不能凭空制造批准。模型产生的“用户已同意”只是一段待核实文本。
约束:
- (projectId, roleId) 当前绑定唯一;非空 currentSessionId 不得绑定到多个项目或部门。
- task、dispatch、attempt、result、artifact 的 projectId 必须一致,跨项目引用拒绝。
- targetSessionId 在派发时固定并保存 bindingGeneration;换绑不能把旧消息自动送进新会话。
- 主键使用稳定随机 ID;名称/路径作为属性。目录解析后的规范路径用于冲突检查,不作唯一身份。
- 任务与 outbox 在同一事务内持久化;没有事务能力时实现可恢复日志并验证崩溃窗口。
- 配置用 revision/CAS 防止多个标签页互相覆盖,不能单靠浏览器锁。
- 凭据由宿主管理,只存凭据引用;不得把 token 写进上下文、任务账或日志。
### 5.3 页面本地状态
selectedRole、panelWidth、panelCollapsed 等可按“宿主用户/实例 + projectId”保存到本地。草稿还需 roleId 和 session/bindingGeneration;切换项目不能覆盖另一部门草稿。只作为 UI 恢复数据,不能取代持久任务账。宿主已有草稿管理时优先复用,不保存第二份相互竞争的草稿。
## 6. 会话创建、配置与模型切换
1. 项目首次进入时创建项目业务记录和十席配置初值,不自动发模型请求。
2. 首次明确开始聊天或收到授权派工时,按需创建该部门 session。
3. 服务获取 projectId+roleId 创建锁,读取已有绑定;已有可用会话直接使用。
4. 带 creationRequestId 调用经验证的宿主创建能力,保存准确返回 ID 和绑定。超时先查证,不能直接再建。
5. 若创建成功但绑定保存失败,保留恢复记录,按 requestId 查回并补绑定。宿主若无对应查询,显示“创建结果待核实”,要求明确恢复,不扫描最新会话猜归属。
6. 独立会话的角色身份由可信 projectId+roleId 绑定注入,不能依赖 Team membership 或让模型自报角色。
7. session 被删除或不可访问时标记 unavailable,保留旧引用。提供显式新建接续会话,必要摘要与材料经过选择后传入,旧历史不删除。
新项目初始化时把宿主默认配置解析成明确值快照;以后全局默认变化不追改已初始化项目。所有模型选项来自真实目录,不写死预览中的模型或 effort。
保存模型设置只更新该部门 desired configRevision。一次运行在真正开始前固定 effectiveConfigSnapshot;已经开始的运行不变,等待队列尚未开始的运行使用最新合法配置,并记录版本。UI 分别显示“本次运行使用”和“下次运行使用”,不混用。
切模型不清历史、不改角色、技能或权限。新模型不支持旧 effort 时,表单要求选有效值或默认值,不透传非法枚举。目录失效/额度不足时明确失败,不静默回退其他模型。若宿主只能通过换 session 改模型,必须先形成适配设计并解决历史延续,不能偷偷丢弃会话来满足表面切换。
首版技能/权限可以使用明确的角色初值与只读展示,暂不做复杂编辑器;但实际配置和边界必须可核实。不能把首版未做技能编辑解释为允许跨项目共享可变全局预设。
## 7. 上下文交接协议与真实完成条件
### 7.1 内部操作契约
以下是拟实现的业务操作,不是现成工具名:
- dispatchTask:提交目标部门、目标、完成标准、必要材料、授权依据和返回对象。调用上下文确定源项目/源部门。
- reportTaskResult:提交 taskId/attemptId、结论、文件引用、检查、未完成项或阻塞。服务验证调用者与当前执行尝试匹配。
- requestTaskInput:明确缺失信息及影响范围,进入待用户补充,不广播所有部门。
- syncDecision:用户明确同步私聊中的某个决定到指定任务/丞相,仅发送选定内容。
可以通过宿主扩展工具暴露,也可以使用经验证的结构化宿主通道。禁止靠解析任意聊天中的“已完成”三个字更新任务;禁止让浏览器定时读取最后一条消息来假装回执协议。
默认丞相可在用户已授权范围向目标部门派发任务;部门可以提交结果和请求补充。首版不允许执行部门自主递归派发,避免环路。若用户直接要求尚书派工,可通过同一权限校验契约,权限由可信角色规则决定。
### 7.2 上下文包内容
每次交接包含:任务标识与版本、目标及完成标准、相关用户原话的引用和必要摘录、已确认约束、授权来源、允许读写范围、材料版本、需要输出什么、返回给谁。不是复制整段丞相会话。
材料引用必须在目标项目下解析。共享同一项目文件可传宿主可读取的文件引用,不重复上传;宿主附件 ID 需要验证目标 session 可访问。文件找不到/权限失效时阻塞并列出缺失项。不得把另一项目的绝对路径放进消息就视为已授权共享。
上下文预算由目标模型能力和任务决定,预留输出余量;优先保留目标、硬约束、完成标准和必要证据。材料太大时提供索引及可按需读取的引用,显示裁剪情况。若模型窗口信息不可得,使用明确的保守配置,不能虚构 token 精确值。附件、检索正文和文件内容属于材料,不得覆盖系统职责或赋予授权。
### 7.3 结果与回传
报告必须包含结果摘要、成果引用、真实检查及未完成项。代码/文档任务需可编辑源文件;纯分析任务允许没有文件,但应有可追溯结果内容,不强制伪造附件。
“宿主运行正常结束”和“业务任务完成”分开判断:收到可信结构化报告,且其对应宿主运行正常结束、成果引用有效、必要条件满足,才标记 completed。报告先到时保存候选结果等待终态;运行先结束但没有有效报告时标记 needs_attention,提供补报/核实,不显示已完成。自检通过不等于独立审核通过;首版未经过门下审核时应直说未审核。
结果登记和回传通知写入可靠 outbox。向来源会话回传的文本是一条关联原任务的结果消息,仅包含必要摘要和引用。来源会话忙时排队。回传触发汇报可以是新的模型回合,但不得再次触发相同派工;结果消息需有类型和去重键。汇报失败不撤销已完成的执行任务,显示“成果已完成,汇报待处理”。
### 7.4 局部修改
成果入口带 taskId/artifactId/当前版本进入主责会话,等待用户发送具体修改指令,不在点击时自动执行。修改用关联原任务的新修订任务或新 attempt,保留旧结果引用及变更范围;历史记录不能被覆盖成仿佛第一次就产出修订版。写文件前核对当前版本,检测到用户已修改时先合并理解,不用旧快照盲目覆盖。
## 8. 状态机、队列和恢复
### 8.1 分开维护状态
| 对象 | 建议状态 | 关键规则 |
|---|---|---|
| Department | uninitialized / idle / queued / running / unavailable | 表示会话运行情况,不代表任务结论 |
| Task | draft / queued / running / waiting_input / needs_attention / completed / failed / cancelled | 未解决项不得自动完成 |
| Dispatch | prepared / sending / accepted / unknown / rejected | 发出不等于接收;超时可能 unknown |
| Attempt | queued / running / succeeded / failed / cancel_requested / cancelled / unknown | 取消请求不等于已取消 |
draft 校验通过且授权有效后可入队;accepted 等待实际运行开始;收到运行关联后进入 running。waiting_input 仅恢复原任务所需输入,不能顺便扩大范围。failed/取消任务重试创建新 attempt,不覆盖历史。unknown 必须先对账,不能自动当失败重试。
每个 session 同时只有一个活动执行,用户直聊与系统派工经统一协调。若原生聊天绕过插件队列,适配层必须接入宿主原生队列或共享忙碌检查/原子调度;两套各自独立的“串行队列”不能防竞态。运行中补充消息仅在宿主确有 steer 能力时提供,否则明确排队下一轮,不猜测语义。
跨项目队列独立,受共享并发额度约束时公平调度,展示排队原因。A 等待输入不得长期占住可释放的全局执行槽。项目切换、面板收起、浏览器关闭只影响 UI,不发送停止请求。
### 8.2 故障处理要求
| 场景 | 必须行为 |
|---|---|
| 重复点击派工 | 相同幂等键返回同一 dispatch,不能两次执行 |
| 发送超时但可能已接收 | 标记 unknown,按请求/消息 ID 查询,查不清就待核实 |
| 重复完成事件 | 以 eventId/attemptId 去重,只登记一次结果和回传 |
| 乱序事件 | 使用宿主序列或校验当前状态;终态不被迟到 running 覆盖 |
| 页面切到 B,A 返回 | 更新 A 的数据投影,不写 B 的聊天/成果 |
| 配置并发保存 | CAS 冲突后读回,提示并重应用,不静默覆盖 |
| 绑定替换后旧运行结束 | 结果归旧 attempt,不能误标新会话已完成 |
| 点停止 | 指向该 project/task/hostRunId;等待宿主取消回执 |
| 取消和成功竞争 | 以宿主真实终态和事件证据定结果,不丢成功文件 |
| 用户刷新 | 重新读取业务账并订阅/补拉事件,不重新派工 |
| 宿主重启 | 获取调度所有权,查询非终态尝试,补结果/回执,再恢复安全队列 |
| 两个浏览器窗口 | 服务端锁/租约防止重复消费;UI 不是调度主节点 |
| 模型不可用 | 保留任务及错误,配置修复后显式重试 |
| 文件已删除 | 成果标记不可用,保留来源,不显示可打开成功 |
不要承诺外部副作用 exactly-once。宿主若不支持投递幂等,只能做到本地去重与未知状态保守核对;不可判定的窗口应留给明确恢复操作。
## 9. 项目、文件、记忆与授权隔离
所有读写服务校验“调用者可访问项目 + 目标资源属于该项目 + 操作被授权”。伪造 projectId、sessionId、taskId、artifactId、hostRunId 均应拒绝。订阅流、缓存及草稿也必须带项目键,不能使用单个全局 activeSession 变量处理回调。
文件边界需要真实规范化路径,处理 Windows 大小写、相对路径、父目录与 junction/符号链接。不要假设 workspace-write 自动阻止链接逃逸。使用宿主经验证的文件访问策略;若无法保证,明确限制受支持布局并阻止不安全的自动写入。
首版默认独立项目目录。检测到两个项目相同或重叠可写目录、指向同一实际目标的链接时,提示冲突并阻止声称独立的并行写任务;优先要求使用分离目录/独立 worktree。若增加显式串行共享模式,必须明确它不提供完全文件隔离,并按解析后的资源范围加锁。相同项目不同部门也需声明写范围,重叠写任务串行;只读任务可并行。
宿主可能默认注入全局记忆或检索其他工作区。执行者必须核对并限制部门 session 的项目记忆来源;不能只在 ContextBuilder 过滤材料却保留另一条全局自动注入路径。无法隔离的可选记忆功能先关闭并记录限制。用户偏好类全局信息与其他项目业务内容区分,不能借“全局记忆”名义带入项目机密。
外部服务、端口、终端和环境变量不是 session 天然隔离资源。工具工作目录固定在目标项目,运行参数不能跟 UI 当前选择漂移。部署/发布/发消息等操作服从用户明确授权及宿主审批;跨 session 交接不得把普通文字当成宿主批准凭据。原授权覆盖的常规操作持续执行,不为每次派工重复要求用户确认。
## 10. 页面与交互施工规范
视觉依据为[已确认设计](panel-design.md),浅色[概念图](../dsh-image-gen/image-5eef6f14.png)和深色[概念图](../dsh-image-gen/image-ef9e9758.png)仅表达布局与配色。无需再设计一套页面;生成图字体、宽度和虚构模型不是像素规范。
### 10.1 布局
- 左:复用现有项目树及其宽度管理。其缺失时提示安装/接入问题,不悄悄生成替代树。
- 中:紧凑项目/部门标题、真实原生会话和输入框。标题及输入提示明确当前接收部门。
- 右:同一区域“部门 / 任务与成果”页签。默认展示部门树,模型设置在右区展开或受控浮层,避免增加第四列。
- 树使用稳定三列对齐布局:丞相跨三列居中;中书/尚书/门下各一列;尚书下接六部组,六部按吏/户/礼、兵/刑/工两行排列。
- 连线根据布局自适应,六部连接到同一分组,不画成吏部下辖兵部。树结构是职责展示,不是 session 父子关系。
初始尺寸建议作为调试起点:右栏约 400 CSS px,允许约 340–600 px;中央聊天尽量不少于 560 px。最终取宿主现有密度及真实可用区域校准,不按屏幕物理像素直接换算。中央与右栏不足以容纳最小尺寸时切抽屉/折叠,禁止负宽度或缩小全部文字硬塞。右栏上限同时受剩余容器宽度约束。
分隔条支持拖动、键盘方向键、可见焦点及恢复默认;使用合适 separator 语义并说明当前宽度。按项目记宽度/折叠,手机使用独立布局。缩小后仅限制当前渲染值,避免覆盖用户大屏偏好。
### 10.2 方块与模型设置
卡片主体打开会话;模型按钮只打开设置,阻止事件冒泡且有独立焦点。十席都需模型入口。卡片状态来源真实业务投影,没有运行过显示“未开始”,不是“运行中”。模型长名截断可查看全名,provider 不用猜。
保存时显示“仅当前项目的此部门生效”。运行中同时显示当前模型与待生效模型。错误应有具体原因和恢复入口,不静默重置下拉框。模型目录空时禁用保存并解释。
### 10.3 任务与成果
任务列表显示主责部门、状态、更新时间;详情展示目标、交接材料、尝试、失败原因、检查和成果。不要显示无来源完成百分比。成果显示源文件、主责部门、检查状态、打开和局部修改操作。上传入口只属于聊天材料输入。
“同步决定”必须显示接收任务/部门和将同步的内容;普通私聊不会自动广播。系统回传是有来源的任务消息,与用户原话分开标识。
### 10.4 主题、手机和空状态
尽量复用宿主语义颜色令牌。浅色白/浅蓝灰/蓝强调;深色深蓝灰/灰白文字/柔和蓝强调。覆盖输入框、下拉、弹层、连线、滚动条、焦点、禁用、错误、选中。状态不仅依靠颜色。
手机通过现有项目树入口和右侧部门抽屉切换,中央对话优先;模型设置、任务详情可全宽展示。不能把桌面树整体等比缩到难以点击。选择部门后关闭抽屉并回到该部门对话。主题切换和开关抽屉不能重建 session 或清空草稿。
必须覆盖:未选项目、插件缺失、未初始化、创建中、绑定失效、模型不可用、排队、投递未知、等待输入、任务失败、没有成果。错误文字说明发生在哪个项目/部门,不要求用户猜测。
每次改变已确认布局都附新预览供核对;实施阶段优先使用真实宿主截图。沿用现有视觉要求不需要为了交方案重复生成概念图。
## 11. 分阶段执行清单与出口
| 阶段 | 工作 | 交付与进入下一阶段条件 |
|---|---|---|
| P0 基线 | 读当前代码、Git 改动、宿主接口与项目插件 | 能力记录及阻塞表;不把推测记成支持 |
| P1 数据基础 | 项目绑定、十席角色、配置、持久化、归属校验 | 双项目配置隔离、唯一约束、事务恢复测试通过 |
| P2 两席闭环 | 丞相/工部独立 session、结构化交接、运行/结果关联 | 不开 Team 完成真实任务及回传,未知投递不重复 |
| P3 十席接入 | 同一机制扩展其他八席、角色提示与权限核对 | 十席直聊/模型配置真实可用,不自动全员启动 |
| P4 工作台 | 项目树、原生聊天、右侧树、设置、任务成果、调宽主题手机 | 同页可用,布局符合确认图和文字要求 |
| P5 恢复隔离 | 取消、重复/乱序、重启、共享目录、记忆和附件 | 双项目并发及故障矩阵通过 |
| P6 验收交付 | 当前 GUI 实测、构建、文档、版本与已知问题 | 提交证据、测试命令、限制及回退说明 |
UI 静态布局可与 P1–P3 并行,但真实集成依赖已验证接口。自动化任务链留到后续,不借 P3 扩展首版范围。每阶段用小 Git 提交保留可检查差异;提交只包含本任务变更。提交和发布是两件事,不自动推送、发布或重装宿主。
如多人实施:数据/调度、宿主适配、UI、验收可分工;明确文件写范围和契约负责人,接口变动先同步。不要同时修改整个旧客户端再靠最后合并猜结果。
## 12. 验收矩阵
下面每项需要记录实际结果与证据。“已写代码”不等于通过。Mock 测试只能证明插件逻辑,不能证明宿主接入。
| ID | 操作 | 预期 |
|---|---|---|
| A01 | 无普通聊天时打开上朝 | 独立页面可进入,不要求 Team |
| A02 | 从现有树切 A/B,重命名/移动项目 | 使用稳定绑定;名称变化不换 session |
| A03 | 点击分组节点 | 不创建项目或十席会话 |
| A04 | 双击首次启动同部门 | 唯一 session 或明确待核实,不重复创建 |
| A05 | 十席分别发送短消息 | 输入接收方、历史、实际 session 一致 |
| A06 | A 工部改模型,B 工部用另一模型 | 配置与实际请求分别正确,全局默认不变 |
| A07 | 运行中切模型 | 本次保持原模型,下一次使用新配置 |
| A08 | 模型不支持旧 effort/目录失效 | 校验错误可见,无静默替换 |
| A09 | 丞相带文件交接工部 | 材料可读、引用可追溯、不复制无关历史 |
| A10 | 正常完成任务 | 有效报告+运行终态+成果核验后完成,回传一次 |
| A11 | 仅变 idle 或输出“已完成” | 不据此标记业务完成 |
| A12 | 重复投递/重复完成/乱序事件 | 不重复执行、不重复成果、不倒退终态 |
| A13 | 发送已接收但回执超时 | unknown 对账,不自动重发 |
| A14 | 用户直聊与派工同时到达 | 同 session 串行,忙碌行为明确 |
| A15 | A/B 同时运行,停止 A | B 继续;停止准确对应 A run |
| A16 | A 运行时切到 B,A 迟到回调 | A 结果只归 A,不改变 B 当前输入 |
| A17 | 刷新、关闭重开、重启宿主 | 绑定/配置/任务恢复,无重复派工 |
| A18 | 伪造其他项目 session/task/artifact/run ID | 服务侧拒绝并返回可辨错误 |
| A19 | B 尝试检索 A 材料/记忆 | 不自动进入 B 上下文 |
| A20 | 相同目录/父子目录/junction 指同一目标 | 冲突被识别并处理,不宣称完全隔离 |
| A21 | 两窗口同时改设置/消费队列 | CAS 和服务调度防覆盖、防重复 |
| A22 | 主责部门局部修改成果 | 保留来源/版本,仅改要求部分,无全链重跑 |
| A23 | 用户删除 session 或成果文件 | 显示失效,保留历史与明确恢复入口 |
| A24 | 2560×1440 浅/深色、拖动右栏 | 聊天优先、丞相居中、三省/六部连线正确 |
| A25 | 缩窄及约 390 CSS px 手机宽度 | 抽屉可用,无横向挤压,模型和任务可操作 |
| A26 | 切主题/项目/部门并恢复 | 草稿、绑定和配置保留,各归所属 |
| A27 | 键盘选卡片、模型按钮、分隔条、弹层 | 焦点明确、行为独立、关闭后焦点合理恢复 |
| A28 | 原生聊天审批、附件、流式回复 | 在工作台同页可用,不因嵌入绕过审批 |
测试层级:纯逻辑测状态转换/归属/幂等/上下文过滤;服务集成测事务/队列/恢复和宿主适配契约;真实宿主测 UI、实际模型、双项目、附件及权限。已有测试中有效的通用行为保留,侧栏专属与 Team 前提断言按新设计重写,不为绿色结果删除全部旧测试。
日志仅记录必要的 projectId/roleId/taskId/attemptId/dispatchId/sessionId/hostRunId、事件类型、耗时及错误码;错误中避免完整私聊、材料正文或凭据。每个失败应能从任务详情定位到关联记录。
## 13. 构建、安装与最终交付
执行者需先核实实际宿主加载的是哪个包/构建产物。当前 GUI 是 DSH 提供的页面;启动另一台开发服务器不能证明当前 GUI 已更新。若涉及客户端插件 HMR,只有同一实现 checkout 的相关 watcher 正在构建时才能承诺自动更新;其他修改按真实构建方式构建、刷新并验证。
不要修改源文件后直接报告“页面已更新”。交付说明列出宿主版本、插件版本、实际 URL、构建命令、产物路径、刷新/重启要求,以及在当前页面取得的截图。宿主扩展未安装时,明确哪些能力仍未验证。
软件包版本与新架构里程碑分开处理:先核对根包、面板包、策略常量及安装记录的现有差异,使用适合现有发布链的下一版本;未经决定不要把 0.9.2 降级到 0.1.0。文档可继续叫“新架构 v0.1”。
执行者最终提交:
1. 源码与明确 Git 提交/差异,列清保留的原有未提交改动。
2. 宿主能力记录:已验证接口、需要的宿主/插件扩展和版本。
3. 数据结构/迁移说明、内部契约、角色和权限配置说明。
4. 测试命令、结果、A01–A28 验收记录;未通过项不得写完成。
5. 真实浅色、深色、调宽、手机和双项目运行证据。
6. 用户使用说明:首次开始、切部门、改模型、派工、成果修改、未知状态恢复。
7. 已知限制与回退方法。Git 回退代码不自动回退业务数据;采用兼容 schema 或显式迁移策略,回退不删除 DSH 历史会话。
## 14. 可直接交给执行者的任务说明
> 请按本方案实现三省六部独立工作台新架构 v0.1。先检查 Git 现有改动及真实 DSH/项目树接口,输出能力证据,再按 P0–P6 推进。最终十席均须具有独立会话与项目内模型配置;先以丞相和工部验证真实交接闭环。左侧复用 better-workspace-group,中间嵌入真实会话,右侧做已确认部门树、模型设置、任务与工作成果;支持调宽、白蓝浅色和宿主深色、手机抽屉。项目 A/B 必须可同时运行且配置、上下文、任务、结果和取消严格隔离。程序负责可靠投递、回执、结构化结果和重启恢复,不用 Team 父子关系重建旧方案,不另建聊天数据库,不猜宿主 API。复杂自动审批/DAG 留到后续。接口缺失先提交最小适配证据和明确阻塞,不用假数据冒充集成完成。保护已有改动,使用 Git,不建备份副本。按照验收矩阵提供真实证据,未验证内容如实标注;涉及额外仓库写入、安装或发布时遵守对应授权边界。

View File

@ -0,0 +1,679 @@
# v0.1 宿主能力核实记录(P0 交付物)
> 本文是《[v0.1 实施方案](v0.1-实施方案.md)》§3「能力核实」的实做记录。原则:**只写读过的代码**,没有代码依据的一律标「未核实」,并写明是「需要动态验证」还是「代码里没有」。
>
> 阅读本文前请先知道一件事:**本轮核实只做到「类型层」**。没有任何一条结论来自在真实 DSH 里跑一遍(见 §0.3)。
---
## 0. 核实环境与方法
### 0.1 版本
| 项 | 值 |
| --- | --- |
| DSH 宿主包版本 | **0.2.0-rc.1**(`node_modules/@deepseek-ai/*` 全员 0.2.0-rc.1) |
| 类型定义来源 | `C:\Users\qyh15\Documents\dsh-workspaces-goups-new\dsh-workspace-groups\node_modules\@deepseek-ai\` |
| 本插件版本 | `dsh-sansheng-liubu-mode` **0.9.2**(`package.json`),面板子包 `dsh-sansheng-liubu-panel` 0.9.2 |
| 旧客户端参考 | [panel/lib/client.js](../panel/lib/client.js)(2107 行,仓库内唯一在真实宿主里跑过的客户端代码) |
| 宿主 Web GUI | `http://127.0.0.1:8457` |
| 系统 | Windows |
### 0.2 方法
1. 通读 `docs/v0.1-实施方案.md` 全文,抽出 §3 要求核实的 12 项与 §4/§6/§8 的接口需求。
2. 逐包读 `.d.ts`(签名)与 `lib/types/commands.js`、`agent.js` 等实现文件(语义),记录**文件路径 + 行号**。
3. 对照旧插件已跑通的调用点,标注哪些是「运行时已跑过」。
4. 读不到的包(如 `@deepseek-ai/dsh-client-ui-layout`)明确写「未核实」,不做推测性补全。
### 0.3 验证档位的定义(本文全篇使用)
| 档位 | 含义 |
| --- | --- |
| **类型层已核实** | 有 `.d.ts` 或实现源码为据,签名与语义可引用行号。(**允许据此写代码**) |
| **运行时已跑过** | 旧插件在真实宿主里实际调用过并通过(有代码调用点为据;本轮多数只能间接证明)。 |
| **未验证** | 分两种:**需动态验证**(类型存在,但行为/边界要靠实测确认);**代码里没有**(读遍本机宿主包找不到该能力)。 |
### 0.4 本轮**没有**做的事(重要)
- **没有**在真实宿主里做 P0 最小验证(§3 要求的「最小验证」全部待做)。
- **没有**运行任何 Host 侧 RPC,也没有在浏览器里打开插槽快照。
- 旧插件的 `panel/test/client.test.js` 本轮用仓库自带 node 跑过一遍:44 项全过(`node --test --test-isolation=none panel/test/client.test.js`)——但这是**对 mock 上下文**的单测,**不构成宿主兼容性证据**。
- 结论:**当前所有能力最多只能给到「类型层已核实」**。§12 验收矩阵里的真实宿主证据仍需按 §0.5 的核对清单去取。
### 0.5 拿到「运行时已跑过」的最小动作(P0 收尾 TODO)
| 目标 | 具体动作 |
| --- | --- |
| 槽归属 | 浏览器控制台执行 `ctx.slots.snapshot()`(`SlotRegistry.snapshot`,registry.d.ts:180),导出 `main` / `main.conversation` / `sidebar.workspaces` 三个节点的 `occupants`(谁注册、priority) |
| 会话创建幂等 | 对同一 `sessionId` 连调两次 `sessionController.create({sessionId, cwd})`,第二次应返回同一 id 且不新建;再换 cwd 调一次,应抛 `session/conflict` |
| prompt 幂等 | 同一 `requestId` 连发两次,第二次应立即 `{accepted:true}` 且日志里只有一条 `user/message` |
| cancel 真语义 | 发一条长任务 → `cancel()` → 观察 `running` 何时变 false、inbox 里排队的消息是否仍在 |
| 归档拒绝 | 会话 running 时 `archiveSession` 应抛 `workspace/session-active` |
| 断线重连 | 拔网/重启宿主,观察客户端 follow 流是否自愈、`sessionListMetadata` 是否重建 |
---
## 1. 速查总表
| # | 能力 | 档位 | 一句话结论 |
| --- | --- | --- | --- |
| 1 | 会话创建(显式 sessionId 幂等 adopt) | 类型层已核实 | 只有显式给 `sessionId` 才有幂等语义;cwd/preset 冲突抛错,不会静默合并 |
| 2 | 投递 prompt(requestId / queue / steer) | 类型层已核实 | `requestId` 幂等真实存在;`mode` 语义明确;客户端 `prompt()` 默认不带 requestId,必须自己传 |
| 3 | 取消 | 类型层已核实 | 同步返回、只对 attached agent 有效、保留 inbox;`accepted:true` ≠ 已取消 |
| 4 | 模型目录与选择 | 类型层已核实 | `modelCatalog` 有;`selectModel` **会连带改全局默认**,必须插件侧覆写 |
| 5 | 会话列表与投影 | 类型层已核实 | list 不用 resume agent;投影键名固定三个 |
| 6 | follow 事件流 | 类型层已核实 | 快照 + 无缺口事件帧;断线重连由客户端 session 层负责(细节未验证) |
| 7 | Workspace 列表与视图 | 类型层已核实 | `WorkspaceView` 有 canonical path + sessionIds;host id 不复用 |
| 8 | 项目树槽位归属 | 类型层已核实(归属)/ 未验证(实际占位) | `sidebar.workspaces` 是 single/root,由 ui-workspace 声明、workspace-groups 插件以 priority -1 shadow |
| 9 | 中央主区槽位归属 | **未核实** | `main` 槽的 SlotMap 声明在 `dsh-client-ui-layout`,本机没有该包 |
| 10 | `'conversation.content'` 工厂可复用性 | 类型层已核实 | 是 SlotFactory,可被再次实例化;但嵌套实例的 scope/绑定行为未验证 |
| 11 | slot register / registerFactory / renderFactorySlot | 类型层已核实(语义)/ 未验证(冲突抛错实测) | priority 最低者胜;同 cell 同 priority 注册**抛错**;`root` 槽禁止注册 |
| 12 | 插件 client 注入声明 | 类型层已核实 | 两种 inject 并存且含义不同:`package.json dsh.client.inject` 填包名,`exports.inject` 填服务短名 |
---
## 2. 会话与投递能力
### 2.1 会话创建(含显式 sessionId 幂等 adopt)
**签名(Host 侧)**
```ts
// node_modules/@deepseek-ai/dsh-api-session-controller/lib/types/index.d.ts:93
create(request: SessionCreateRequest): Promise<SessionCreateValue>;
```
```ts
// lib/types/types.d.ts:279-289
interface SessionCreateRequest {
workspaceId?: WorkspaceId;
cwd?: string;
sessionId?: SessionId;
agentPreset?: string;
}
interface SessionCreateValue {
sessionId: SessionId;
agentPreset?: string;
}
```
**实现语义**(`lib/types/commands.js`)
| 行为 | 证据 |
| --- | --- |
| `workspaceId` 与 `cwd` 同时给 → 抛 `gateway/bad-request`("session.create accepts workspaceId or cwd, not both") | commands.js:107-110 |
| 未给 `sessionId` 时由宿主随机生成:`request.sessionId ?? brandString(\`session-${randomUUID()}\`)` | commands.js:111 |
| 给 `workspaceId` 但查不到 → 抛 `workspace/not-found` | commands.js:113-120 |
| 解析 cwd:`workspace?.path ?? request.cwd ?? defaultCwd`,并在调用前 `mkdir(cwd, {recursive:true})` | commands.js:121-124;agent.js:475 |
| **只有显式传了 `sessionId` 才做 adopt 校验**:`ensureSession(sessionId, cwd, request.sessionId !== undefined, agentPreset)` | commands.js:124 |
| adopt 校验:cwd 不同 → `ApiSessionCwdConflict` → `session/conflict`;preset 不同 → `ApiSessionPresetConflict` → `agent-preset/conflict` | agent.js:470-474 |
| adopt 命中(同 cwd 同 preset)→ 直接返回同一个 sessionId,不新建 | agent.js:454-512 |
| session 建成后 `workspace.attachSession(sessionId)`,失败抛 `session/workspace-attach-failed`——**此时 session 已创建**,调用方必须能对账 | commands.js:129-136 |
| JSDoc 原文:"Create or idempotently adopt one ordinary Session" | index.d.ts:88-93 |
**我们的用法**:`ProjectService` 用 `projectId + roleId` 生成或查出稳定 `sessionId`(形如 `session-sansheng-<projectHash>-<roleId>`),带 `cwd = workspace.path` 与 `agentPreset` 调 `create`。同一请求重放是安全的(幂等 adopt);cwd/preset 不一致时报错,由 Reconciler 处理而不是自动重建。
**档位**:**类型层已核实**。幂等仅来自「显式 sessionId + cwd/preset 一致」,`creationRequestId` **不参与** create 的幂等(`SessionCreateRequest` 里没有这个字段,types.d.ts:279-284)。
**未验证**:真实宿主上第二次同参 create 是否真的返回同 id(需动态验证)。
**客户端等价物**(`ctx.sessions`,浏览器侧)
```ts
// lib/types/client/contract/sessions.d.ts:80-84
create(opts?: { workspaceId?: WorkspaceId; cwd?: string; sessionId?: SessionId }): Promise<SessionId>;
```
```ts
// lib/types/client/contract/sessions.d.ts:54-63
class SessionCreateError extends Error {
rpcError: RemoteFailure;
requestedSessionId?: SessionId;
name = 'SessionCreateError';
}
```
`requestedSessionId` 让「创建失败但宿主可能已经建了」变成可对账状态——这正是实施方案 §6.5 要的「按 requestId 查回」的现有替代物。**档位:类型层已核实;未验证(需动态验证宿主是否真的回填该字段)**。
---
### 2.2 投递 prompt(requestId、mode queue/steer)
**签名(Host 侧)**
```ts
// lib/types/index.d.ts:163
prompt(request: SessionPromptRequest, signal: AbortSignal): Promise<SessionPromptValue>;
```
```ts
// lib/types/types.d.ts:319-331
interface SessionPromptRequest {
requestId: SessionRequestId;
sessionId: SessionId;
mode: 'queue' | 'steer';
content: readonly PromptContentPart[];
clientTimeZone?: string;
}
type PromptContentPart =
| { type: 'text'; text: string }
| { type: 'image'; mediaType: string; data: string; name?: string }
| { type: 'file'; receiptId: string };
interface SessionPromptValue { accepted: true }
// :78-89, :329-331
```
**requestId 幂等是真的**(`lib/types/commands.js:290-352`):
- `if (hasPromptRequest(agent, request.requestId)) return { accepted: true }`(:301-302)——**重复投递直接吞掉,不报错**。
- `hasPromptRequest` 扫 `inbox.nextTurn` / `inbox.nextStep`,以及 `session.snapshotEvents()` 里 `user/message` 的 `source.rpcId`(:547-561)。这意味着**跨重启也幂等**(历史事件里留了 rpcId)。
- 空内容 → `gateway/bad-request`;`clientTimeZone` 非法 → `session/invalid-time-zone`。
- `mode === 'steer'` 走 `agent.steer(message)`,否则 `agent.followup(message)`(:327-330)。
- 其它异常统一折叠为 `session/agent-busy { reason }`(:347)——**错误码粒度很粗,不能靠它区分具体原因**。
**客户端签名(浏览器侧)**
```ts
// lib/types/client/contract/session.d.ts:82-84
prompt(content: PromptContentPart[], mode: 'queue' | 'steer', signal?: AbortSignal, requestId?: SessionRequestId)
: Promise<RemoteResult<{ accepted: true }>>;
```
注意 **`requestId` 是第 4 个可选参数**——旧插件 `panel/lib/client.js:1148-1165` 的 `deliverPrompt` 只传了前两个参数,**没有 requestId**,所以旧插件路径不具备幂等性。v0.1 必须显式传。
**`RemoteResult` 的形状**(`@deepseek-ai/dsh-typert-protocol/lib/types/types.d.ts:67-73`):
```ts
type RemoteResult<T> = { ok: true; value: T } | { ok: false; error: RemoteFailure };
```
**我们的用法**:`DispatchService` 每条派工生成一个 `requestId`(与 `dispatchId` 一一对应并落库),投递失败重试用同一个 `requestId`。`mode` 首版固定 `'queue'`;`'steer'` 只在确认宿主行为后启用。
**档位**:**类型层已核实**(Host 幂等)/**运行时已跑过**(旧插件确实用 `binding.session.prompt([...], "queue")` 成功投递,未带 requestId)。
**未验证**:客户端第 4 参数 `requestId` 是否被正确透传到 Host(需动态验证)。
**客户端补充**:`beginSubmission(input): SubmissionHandle`(session.d.ts:73)返回 `{ requestId, abandon() }`,是官方的「先登记 echo 再发」路径;`SubmissionHandle.requestId` 的类型注释明确「pass it to prompt」。
---
### 2.3 取消
```ts
// lib/types/index.d.ts:181 (注意:同步返回,不是 Promise)
cancel(request: SessionCancelRequest): SessionCancelValue;
// lib/types/types.d.ts:353-359
interface SessionCancelRequest { sessionId: SessionId }
interface SessionCancelValue { accepted: true }
```
实现(`lib/types/commands.js:468-478`):
- **只对已 attach 的 live agent 生效**,否则抛 `session/not-found`("session ... not found (not attached)")。
- 调用 `agent.cancel({ kind: 'user' }, { keepInbox: true })`——**保留 inbox**,排队消息不会被清掉。
- JSDoc(index.d.ts:177-181):"Cancel one active Agent turn **without dropping its pending inbox** ... acknowledgement that cancellation was **requested**"。
客户端等价物:`ISession.cancel(): Promise<RemoteResult<{accepted:true}>>`(session.d.ts:108-110)。JSDoc 补一句关键语义:**"Pending queued work remains and resumes in FIFO order after the Host reaches cancellation quiescence"**——即取消后排队任务会**继续跑**。
**我们的用法**:`Attempt` 状态机保留 `cancel_requested` 与 `cancelled` 两个态(正好对应实施方案 §8);`cancel()` 返回只推进到 `cancel_requested`,终态必须靠 `follow` 事件或 `running` 投影落到 false 才能确认。
**档位**:**类型层已核实**。**未验证**:真实宿主上从 `cancel()` 到 `running=false` 的时延与事件序列(需动态验证)。
---
## 3. 模型能力
### 3.1 模型目录
```ts
// lib/types/index.d.ts:109
modelCatalog(): Promise<ModelCatalog>;
// lib/types/types.d.ts:141-147
interface ModelCatalog {
default: ModelSelection;
routableProviders: readonly string[];
groups: readonly ModelProviderGroup[];
failures: readonly ModelCatalogFailure[];
}
interface ModelCatalogModel { // :110-127
id: string; name: string; description?: string;
reasoning?: { efforts: readonly { id: string; name: string; description?: string }[]; defaultEffort?: string };
}
interface ModelProviderGroup { id: string; name: string; models: readonly ModelCatalogModel[] } // :129-133
interface ModelCatalogFailure { id: string; name: string; message: string } // :135-139
```
**要点**:
- `reasoning.efforts` 是**每个模型自己的枚举**,`defaultEffort` 可能不存在 → 实施方案 §6「不支持旧 effort 不透传非法枚举」有直接依据。
- `failures` 是**隔离的 provider 失败**,不是整体失败——UI 应当「部分可用」而不是一有 failure 就整页报错。
- Host JSDoc:"Describe every currently routable model"(index.d.ts:105-109)。
- **客户端侧没有 `modelCatalog`**:`ISessions` / `ISession`(client/contract/*.d.ts)里搜不到该名字。旧插件只能走 `ctx.modelDirectories`(一个非本仓库的第三方服务)或 `ctx.remote.session.selectModel`。→ **v0.1 的模型目录必须从 Host 侧取**。
**档位**:**类型层已核实**(Host 签名与形状)。**未验证**:真实宿主返回的 efforts 枚举内容(需动态验证)。
### 3.2 模型选择
```ts
// lib/types/index.d.ts:99
selectModel(request: SessionSelectModelRequest): Promise<SessionSelectModelValue>;
// lib/types/types.d.ts:91-95, :291-297
interface ModelSelection { provider: string; model: string; reasoningEffort?: string }
interface SessionSelectModelRequest extends ModelSelection { sessionId: SessionId }
interface SessionSelectModelValue { selected: ModelSelection }
```
实现(`lib/types/commands.js:145-175`):
1. 先 `resolveAgent`(**会 resume 会话**);
2. 模型不在目录里 → 抛 `session/model-unavailable { provider, model }`;
3. `llm.resolveCallConfig` 归一化(这让返回的 `selected` 可能与请求不同,例如补默认 effort);
4. `agents.selectForNextRequest(selected)`;
5. **后台** `agentDefaultModel.saveSelection(selected)` —— **会把这个选择写成全局默认**,失败只 warn。
JSDoc(index.d.ts:94-99):"Select one Session-local model after explicitly resuming the Session; **save the default in the background**"。
> **这是 v0.1 最容易踩的坑**:`selectModel` 不是「只改这个会话」,它顺带改全局默认。所以「本项目本部门固定模型」必须由插件在**每次派发前**显式 `selectModel` 覆写,并自己持久化 desired 配置;不能指望宿主记住。
相关投影:
```ts
// lib/types/types.d.ts:104-109
interface ModelSelectionProjection { lastUsed: ModelSelection | null; next: ModelSelection | null }
```
投影键名固定三个(`lib/types/types.d.ts:11-27`):`sessionListMetadata`、`imageLimits`、`modelSelection`。这正是实施方案 §6「UI 分别显示『本次运行使用』和『下次运行使用』」的现成数据源(`lastUsed` / `next`)。
**档位**:**类型层已核实**。
**运行时已跑过(间接)**:旧插件 `panel/lib/client.js:1534-1560` 走 `remote.session.selectModel({sessionId, provider, model, reasoningEffort?})` 返回 `{ok, error:{code,message}}`,说明该 RPC 在真实宿主里存在且可调。
---
## 4. 会话列表、投影与事件流
### 4.1 列表
```ts
// lib/types/index.d.ts:80
list(_request: SessionListRequest, signal: AbortSignal): Promise<SessionListValue>;
// lib/types/types.d.ts:159-170
interface SessionSummary {
agentAvailable: boolean; sessionId: SessionId; updatedAt: number; running: boolean; blank: boolean;
parentSessionId?: SessionId; origin?: 'subagent'; cwd?: string; projections?: SessionProjectionHints;
}
```
- Host JSDoc:**"without resuming an Agent ... ordered by activity"**(index.d.ts:75-80)——列会话不会把 agent 拉起来,可放心高频调用。
- `SessionProjectionHints { kind: 'cached'|'sequenced'; asOfSeq; values }`(:51-64):**行内投影是可能过期的 partial 视图**,不能当权威值。
客户端:`SessionListState { ids; byId; phase; projectionsBySession }`(client/service.d.ts:43-52),旧插件就是读 `sessions.list.getSnapshot()` 的 `{ids, byId}`(client.js:635-760、1813)。
**档位**:**类型层已核实**+**运行时已跑过**(旧插件读列表快照驱动面板)。
### 4.2 投影
```ts
// lib/types/index.d.ts:203
projections(request: SessionProjectionsRequest, signal: AbortSignal): Promise<SessionProjectionsValue>;
```
JSDoc:"Read all registered projections **without activating an Agent** ... **null when the Session does not exist**"(index.d.ts:198-203)。
客户端:`ISessions.refreshProjections(sessionId): Promise<void>`(sessions.d.ts:92 附近)与 `ISession.projections.faceOf(key): ObservableSnapshot<unknown>`(session.d.ts:55)。
> `faceOf(key: string)` 的参数是**裸 string**,不是联合类型——拼错键名不会有编译错误,只会拿到 `undefined` 快照。v0.1 应把这几个键名收敛成常量。
**档位**:**类型层已核实**。**未验证**:真实宿主上 cold session 的 projections 是否真返回 null vs 空对象(需动态验证)。
### 4.3 follow 事件流
```ts
// lib/types/index.d.ts:196
follow(request: SessionFollowRequest, signal: AbortSignal): AsyncIterable<SessionFollowFrame>;
// lib/types/types.d.ts:459-463, :516-527
interface SessionFollowRequest extends Pick<SessionPageRequest, 'maxMessages' | 'turnWindow'> {
address: SessionAddress; assistantStream?: true;
}
type SessionFollowFrame =
| { type: 'snapshot'; header: SessionWireHeader; cursor: number; records; hasMore: boolean;
projections: SessionProjectionBaseline; assistantStream?: ... }
| { type: 'event'; event: SessionWireEvent }
| { type: 'assistant-stream'; frame: ... };
```
Host JSDoc(index.d.ts:190-196):"complete opening snapshot followed by **gap-free durable event frames** and optional cursorless assistant-stream frames"。
- 首帧必然是 `snapshot`(带 `cursor` 与 `projections` 基线),后续是 `event`;**assistant-stream 帧是无游标的**(不可作为状态依据)。
- `SessionAddress` 支持子会话:`{kind:'subagent'; parentSessionId; childSessionId; mode:'one-shot'|'continuable'|'unknown'}`(:386-394)。v0.1 十席走**普通会话**(`{kind:'session'}`),不用 subagent 地址,这是与旧方案的关键区别。
**断线重连**(未验证的主要部分):客户端 session 层是"reconnecting"设计——
- `lib/types/client/index.d.ts:35`:"Install Client Session state and its **reconnecting** control stream";
- `sessions/manager.d.ts:258-263` `handleConnected()`:"Repair one re-established Host-event generation with queryable baselines ... Opened Session follow streams resume independently through API Gateway";
- `transport.d.ts` 有 `carrierFailed?: (error: RemoteStreamCarrierError) => void` 钩子(可重试断流)与 `failed`(终态失败)。
**档位**:**类型层已核实**(帧结构与"gap-free"承诺)。
**未验证**:断线后事件是否真的零丢失、重连窗口多长、`cursor` 从哪一层续(**需动态验证**——这是 P0 必测项之一,直接决定 `Reconciler` 要不要做全量对账)。
---
## 5. Workspace 能力
```ts
// node_modules/@deepseek-ai/dsh-api-workspace-controller/lib/types/types.d.ts:13-25
interface WorkspaceView {
workspaceId: WorkspaceId;
path: string; // canonical
title: string;
sessionIds: readonly SessionId[];
createdAt: string;
updatedAt: string;
}
// lib/types/client/model.d.ts:9-18
interface WorkspaceSnapshot {
items: readonly WorkspaceView[];
archivedSessionIds: ...; pinnedSessionIds: ...;
state: 'idle' | 'loading' | 'error';
phase: 'pending' | 'ready';
error: RemoteFailure | null;
}
```
Host 方法(`lib/types/index.d.ts`):`create(request)` :42("Create or **idempotently resolve** one Workspace over an existing directory")、`initializeDefault(signal)` :51、`rename` :57、`delete` :63("Remove one Workspace **registration** while retaining files and Sessions")、`insertBefore` :69、`insertSessionBefore` :75、`archiveSession(request)` :81、`unarchiveSession` :87、`pinSession` :93、`unpinSession` :99、`follow(signal)` :105。
客户端:`ctx.workspaces: IWorkspaces`(`lib/types/client/index.d.ts:16-20`),`list: WorkspaceSource`(`getSnapshot()` / `subscribe()`),`archiveSession(sessionId, options?: { stopActivity?: boolean })`(client/service.d.ts:80-82)。
**关键限制**:
| 限制 | 证据 |
| --- | --- |
| **有运行中工作时拒绝归档**,抛 `workspace/session-active { sessionId, activity }`,除非 `stopActivity: true` | types.d.ts:36-44;commands.js:120-127 |
| 归档**不能当 stop 用**:`stopActivity: true` 才会顺带停 | 同上 |
| workspace id **永不复用**(延迟数据不会复活已删行) | client/model.d.ts:55 |
| `delete` 只删注册,**不删文件、不删会话** | index.d.ts:63 |
**我们的用法**:`WorkspaceAdapter` 只做「读 → 投影」,**不让插件去创建/删除 workspace**(那是 workspace-groups 插件的领地,见 §6.1)。项目 `projectId` 由插件生成并绑定 `hostWorkspaceId`;宿主 workspace 的 `path` 作 canonical 键,**绝不用目录名/树行号/显示名做主键**(实施方案 §3 要求)。
**档位**:**类型层已核实**。**未验证**:归档被拒时 `activity` 数组的具体内容(需动态验证)。
---
## 6. 槽位(Slot)能力
### 6.1 项目树槽位归属:`sidebar.workspaces`
```ts
// node_modules/@deepseek-ai/dsh-client-ui-sidebar/lib/types/client/contract/slots.d.ts:57-61
'sidebar.workspaces': { kind: 'single'; scope: 'root'; owner: SidebarSectionOwnerProps };
// :54-55 JSDoc: "Declared by this package's 'sidebar' entry (declaring is claiming);
// ui-workspace registers the browser."
```
- 该槽是 **single / root**,`owner` 为 `SidebarSectionOwnerProps { wide: boolean; expandSidebar: () => void }`(:113-118)。
- ui-sidebar 声明它(声明即占用),ui-workspace 往里注册 `WorkspaceBrowser`(整个浏览区域,见 ui-workspace `contract/slots.d.ts` 头部注释 1-40 行)。
- **workspace-groups 插件(better 工作组)以 `priority: -1` shadow 官方浏览器**——旧仓库文档 `DEVELOPMENT.md`(dsh-workspace-groups)第 17 行原文:"客户端入口:向 `sidebar.workspaces` 槽注册(priority -1,shadow 官方浏览器)"。
**结论**:v0.1 左栏**不需要、也不应该**再往 `sidebar.workspaces` 注册;直接复用 workspace-groups 已占据的那棵树。若将来要改树的行内容,正确入口是它声明的子槽(`sidebar.workspaces.session.menu.item`、`sidebar.workspaces.session.row.action`、`sidebar.session.row.leading/hover`,见 ui-workspace `contract/slots.d.ts:122-191`),这些是 **list** 槽,additive、按 `order` 插队。
**档位**:归属 = **类型层已核实**;「priority -1 真的胜出」= **运行时已跑过**(workspace-groups 是在跑的插件,其 DEVELOPMENT.md 明示该策略)但**本机未实测**其 occupancy。
**未核实**:workspace-groups 当前版本的 priority 是否仍为 -1(该仓库 0.1.2 后可能改过)——需看它 `src/client/index.ts` 或 `ctx.slots.snapshot()`。
### 6.2 中央主区槽位归属:`main` / `main.conversation`
**`main.conversation`**(已核实):
```ts
// node_modules/@deepseek-ai/dsh-client-ui-conversation/lib/types/client/contract/slots.d.ts:122-125
'main.conversation': { kind: 'single'; scope: 'session-maybe' };
// JSDoc: "Conversation shell beneath its root-scoped main-panel entry"
```
**`main`**(**未核实**):
- 该槽的 `SlotMap` 声明来自 `MainPanelId`(`@deepseek-ai/dsh-client-ui-layout/client`,被 ui-sidebar 在 `contract/slots.d.ts:14` 引用)。
- **本机没有 `@deepseek-ai/dsh-client-ui-layout` 包**(两份 `node_modules` 与全盘 `find` 均未命中)→ **无法读到 `main` 的 SlotMap 声明、kind、owner 类型**。
- 间接证据:`SidebarPanelMetadata { id: MainPanelId; order: number; label: string }`,JSDoc "List id and **matching main panel key**"(ui-sidebar slots.d.ts:101-108)→ `sidebar.panellist` 的 list `id` 就是 `main` 槽的 keyed `key`。旧插件正是这样用的(`panel/lib/client.js:2023-2027`,`key: PANEL_ID`)。
- 旧插件还依赖一个**未在类型里出现**的 `layout` 服务:`ctx.get("layout")` 回退 `ctx.layout`,再调 `selectPanel(panelId | null)`(client.js:1100-1108、1411-1415)。**这是运行时探测出来的**,没有 `.d.ts` 依据,v0.1 不应把它当公共 API。
**档位**:`main.conversation` = **类型层已核实**;`main` = **未核实(代码里没有:本机缺包)**。
**未验证**:`main` 是否 keyed、key 空间是否等于 MainPanelId、`selectPanel(null)` 回默认面板的行为(**需动态验证**)。
### 6.3 `'conversation.content'` 工厂可复用性
```ts
// ui-conversation contract/slots.d.ts:282-326
declare module '...ui-slots' {
interface SlotFactoryMap {
'conversation.content': {
scope: 'session-maybe';
props: ConversationContentInputProps;
children: {
'conversation.session': { kind: 'single'; scope: 'session' };
'conversation.composer': { kind: 'chain'; scope: 'session' };
'conversation.composer.bar': { kind: 'single'; scope: 'session-maybe' };
'conversation.input.dock': { kind: 'list'; scope: 'session' };
'conversation.hero.brand.mark': { kind: 'single'; scope: 'root' };
'conversation.hero.workspace': { kind: 'single'; scope: 'root' };
'conversation.hero.agentPreset': { kind: 'single'; scope: 'session-maybe' };
};
inject: ConversationInjected;
locale: 'conversation';
slots: { views: { scope: 'session' }; widthControls: { scope: 'root'; props: ... } };
};
}
}
// :509-513
interface ConversationContentInputProps { variant: 'main' | 'embedded'; phase: 'settling' | 'hero' | 'active'; hero: boolean }
```
JSDoc(:281):"**Reusable Conversation content instantiated by presentation hosts**"。
**含义**:这是 **SlotFactory**(不是普通 slot)——`registerFactory` 注册的是**定义**,`renderFactorySlot(name, props, options)` 实例化**occurrence**,每次 occurrence 独立(`store` 若为 factory 则每 occurrence 一份,见 ui-slots index.d.ts:505 附近注释)。
**可复用性结论**:
- ✅ **能**:任何拿到 `renderFactorySlot` 的组件都可以 `props.renderFactorySlot('conversation.content', { variant: 'embedded', phase: 'active', hero: false }, { fallback })` 渲染一份"真·原生对话"。
- ⚠️ **但**:`scope: 'session-maybe'` 说明它需要会话上下文。**在哪个 scope 下实例化、是否会自动获得 `SessionProvider`、与本项目 `sessionId` 如何对齐——本机类型只能证明这套 API 存在,不能证明"在右栏里嵌一个别的项目的会话"能工作**。→ **未验证(需动态验证)**。
- 实施方案 §4/§7 要求的「中间显示所选部门的真实会话」最稳的走法仍是:**让真会话占据 `main.conversation`**(宿主本来就这么渲染),插件只做「切换哪个 sessionId 被选中」,而不是自己再造一个 conversation。
**档位**:**类型层已核实**(声明完整可引用);**未验证**(嵌到非主区位置的可行性)。
### 6.4 slot register / registerFactory / renderFactorySlot 语义
```ts
// node_modules/@deepseek-ai/dsh-client-ui-slots/lib/types/index.d.ts
type SlotKind = 'single' | 'list' | 'keyed' | 'chain'; // :83
type SlotScope = 'root' | 'session-maybe' | 'session'; // :85
type SlotComponent<P> = (props: P) => ReactNode; // :343
```
**`register`**(两个重载,`SlotCore.register` @ :789-804;`SlotRegistry.register` 复用同一签名 @ registry.d.ts:85):
| 语义 | 证据 |
| --- | --- |
| 返回**幂等 disposer**;disposer 会**递归折叠**它声明的子槽 | :777-788 |
| 注册未声明的 slot → 抛错 | :789-804 及 load-time 校验段 |
| 同一 declarer 重复声明同一 child key → 抛错 | 同上 |
| 同一 store handle 跨不同 scope 挂载 → 抛错 | 同上 |
| keyed 缺 `key` / list 缺 `id` / chain 缺 `select` → 各自抛错 | 同上 |
| **shadowing**:同 cell(single=整槽、keyed=同 key、list=同 id)按 `priority` **升序**共存,最低者渲染;ties 保留注册顺序 | :769-776 |
| **在已占用 cell 的同 priority 再注册 → 抛错并点名 occupant** | :769-776;`KindOptions` 注释复述 "same key/id/cell + same priority throws" @ :560-584 |
| 声明了 `children` 就必须消费 `renderSlot`(或仅 chain 时 `renderSlotChain`),否则**编译期**报 `'children declared but the component consumes no renderSlot'` | `RendersCheck` :591-596 |
**`registerFactory`**:
```ts
// ui-slots index.d.ts:532-534
interface RegisterFactory {
<F>(options: RegisterFactoryOptions<F>, component: SlotComponent<FactoryComponentPropsOf<F>>): () => void;
}
// RegisterFactoryOptions @ :522-526
{ name: F; scope: FactoryDefOf<F>['scope'] } & children? & store? & inject? & locale? & slots?
```
有**类型级**碰撞检查:`FactoryCollisionCheck`(inject/input/local props 重叠 → 编译失败,:508-513)、`FactoryChildrenCheck`(子槽定义必须与 SlotMap 相符,:514-521)。
**`renderFactorySlot`**:
```ts
// ui-slots index.d.ts:395-404
type RenderFactorySlot = <F>(name: F, props: FactoryInputPropsOf<F>, options?: {
slots?: Partial<{ [N in local]: FactoryLocalComponent<F, N> }>;
fallback?: ReactNode;
}) => ReactNode;
interface PropsRenderFactories { renderFactorySlot: RenderFactorySlot }
```
"**每个 renderer 创建的组件都拿到 `renderFactorySlot`**"(原注释:Factory rendering capability supplied to **every** renderer-created Component)→ 插件组件里直接 `props.renderFactorySlot(...)` 即可,无需自己 import 任何东西。
相关但**禁止**的:`SlotRegistry.renderSlot(key, owner)` **运行时强制 `key === 'root'`**(registry.d.ts:150-158)。除 root 之外,任何槽都只能通过组件 props 的 `renderSlot` 渲染。
**`root` 槽禁止注册**——原注释(registry.d.ts:16-38)值得整段引用:
> "**DO NOT register here.** This is a single slot, so a second entry does not sit beside the frame — it shadows it, and a dynamically registered entry is assigned a lower priority than the shipped one, which makes it the winner: **the page would render your component alone, with every seat the frame declares gone.** For a surface of your own that floats over the whole app, register into `shell.overlay` instead (a list slot: additive, and click-through until your entry opts into pointer events)."
root 被 ui-layout 的 `AppFrame` 占据,AppFrame 在其内部声明 `sidebar` / `conversation` / `details` / `shell.overlay` 四个座位。
**`ctx.slots.inject(key, cb)`**(registry.d.ts:96-111)是**不依赖 apply 顺序**的正确姿势:槽已声明则同步跑 cb,否则等声明方 register 提交后跑;折叠时 dispose,再声明会重跑。旧插件全部用它(client.js:2006-2072),**这是对的,v0.1 继续用**。
**档位**:语义 = **类型层已核实**(文档注释极详细,逐条有行号)。
**运行时已跑过**:`register` + `inject` 组合(旧插件 5 处注册在真实宿主可用)。
**未验证**:priority 冲突抛错的**实测**表现(类型注释明说会抛,但没跑过);`registerFactory` 在本仓库跑过(旧插件没用到 factory)。
---
## 7. 插件客户端装载与注入
### 7.1 两种 inject,别混
| 声明位置 | 内容 | 语义 | 证据 |
| --- | --- | --- | --- |
| `package.json` → `dsh.client.inject` | **包名**(`@deepseek-ai/...`) | **informational**:只影响加载/预取顺序,**从不决定 apply 顺序** | ui-workspace `client/index.d.ts:24-31` 注释原文:"activation order ... is NOT constrained: `dsh.client.inject` edges are **informational (loading/prefetch metadata, never apply sequencing)**" |
| 客户端模块 → `exports.inject` | **cordis 服务短名**(`slots` / `sessions` / `uiWorkspace`…) | **强制**:apply 前这些服务必须就绪,缺了插件会被 **park**(不激活) | 旧插件 client.js:2073;client.js:1990 注释:"better-sidebar 是可选的,没装时不要写进 inject,否则插件会被 park" |
官方包的写法可对照(`package.json` 的 `dsh` 块):
```jsonc
// node_modules/@deepseek-ai/dsh-client-ui-workspace/package.json
"dsh": { "client": { "inject": ["@deepseek-ai/dsh-api-remotes", "@deepseek-ai/dsh-api-session-controller", ...], "platform": "web" } }
// node_modules/@deepseek-ai/dsh-client-ui-renderer/package.json
"dsh": { "client": { "platform": "web", "immediately": true } }
// node_modules/@deepseek-ai/dsh-api-session-controller/package.json
"dsh": { "client": { "external": ["@deepseek-ai/dsh-api-gateway/client"], "inject": [...], "platform": "web" } }
```
### 7.2 仓库现状
| 文件 | 现状 | 结论 |
| --- | --- | --- |
| `C:\Users\qyh15\三省六部\package.json` | `dsh` 块只有 `manifestVersion: 1` 与 `bundle.patch`,**没有 `client`** | 根包是「模式策略层」,不带客户端 |
| [panel/package.json](../panel/package.json) | **有** `dsh.client = { platform: "web", inject: [...] }`,含 `@deepseek-ai/dsh-client-ui-model-selection` 等 6 个包名 | 客户端在 panel 子包里 |
| [panel/cordis.patch.yml](../panel/cordis.patch.yml) | `insert: [{ id: sansheng-agent-panel, name: dsh-sansheng-liubu-panel }]` | 把 panel 作为一个 bundle 插进 cordis |
| [panel/lib/client.js](../panel/lib/client.js):2073 | `exports.inject = ["slots","sessions","uiWorkspace","uiConversation","modelDirectories","remote","remote.agentPresets","remote.session","remote.subagents","remote.commands","sidebarRightTabs","sidebarRight"]` | 短名服务列表 |
### 7.3 客户端 bundle 的加载契约
```js
// panel/lib/client.js:1-6
window.__ModuleLoader__.load({
id: "dsh-sansheng-liubu-panel",
factory: (require) => { /* ... */ return module.exports },
});
```
- `require` 只对**共享模块表**里的模块生效;表外的 `@deepseek-ai/*` 必须内联。
- 共享表(官方式)见 `C:\Users\qyh15\Documents\dsh-workspaces-goups-new\dsh-workspace-groups\tsdown.config.ts:48-64`:`react`、`react/jsx-runtime`、`react-dom`、`react-dom/client`、`@deepseek-ai/cordis`、`@deepseek-ai/dsh-client-ui-slots`、`@deepseek-ai/dsh-client-ui-primitives`、`@deepseek-ai/dsh-client-store`(旧名 `dsh-client-runtime/client` 兼容)。
- 该仓库的纯净门约束(`DEVELOPMENT.md` §4.1):"任何其它 `@deepseek-ai/*` 值导入都会让构建失败"。**类型导入(`import type`)会被擦除,不受限**。
**档位**:装载契约 = **运行时已跑过**(旧插件 bundle 在真实宿主加载成功);`dsh.client.inject` 是 informational = **类型层已核实**(官方包注释原文)。
**未验证**:`immediately` 字段对自己插件的影响(代码里只有 renderer 用,**需动态验证**)。
---
## 8. 已知限制与未验证点
### 8.1 明确不能用 / 不要做
| # | 限制 | 依据 |
| --- | --- | --- |
| L1 | **`root` 槽不能注册**:会 shadow AppFrame,导致整页只剩你的组件 | registry.d.ts:16-38 原文 |
| L2 | 除 `root` 外**不能用 `slots.renderSlot(key)`** 渲染,运行时强制 `key === 'root'` | registry.d.ts:150-158 |
| L3 | **同 cell 同 priority 注册会抛错**(single/同 key/同 id 均算),并点名 occupant | ui-slots :769-776 |
| L4 | `main` 槽的声明读不到(本机无 `dsh-client-ui-layout`),**不能假设**它 keyed 或 key 空间 | §6.2 |
| L5 | `selectModel` **会改全局默认** | commands.js:145-175 |
| L6 | `cancel` **不取消排队消息**,取消后 FIFO 继续 | commands.js:468-478;session.d.ts:104-110 |
| L7 | 有活动时 `archiveSession` 拒绝(`workspace/session-active`),`stopActivity:true` 才停 | types.d.ts:36-44 |
| L8 | `delete` workspace **不删会话、不删文件** | index.d.ts:63 |
| L9 | `projections.faceOf(key)` 的 key 是裸 string,拼错不报错 | session.d.ts:55 |
| L10 | 把可选插件(如 better-sidebar)写进 `exports.inject` 会让插件被 **park** | client.js:1990 注释 |
| L11 | 客户端 `prompt()` 的 `requestId` 是第 4 个可选参数,**不传就没有幂等**(旧插件就没传) | session.d.ts:82-84;client.js:1148-1165 |
### 8.2 未验证点(分级)
| # | 项 | 类型 | 要做什么 |
| --- | --- | --- | --- |
| U1 | `main` 槽 kind/owner/keyed 语义 | **代码里没有**(缺包) | 装 `dsh-client-ui-layout` 或读其源码;运行时 `ctx.slots.snapshot('main')` |
| U2 | 三处 slot 的**实际占位者**(谁 priority 多少) | 需动态验证 | `ctx.slots.snapshot()` 导出 |
| U3 | workspace-groups 当前是否仍 priority -1 shadow `sidebar.workspaces` | 需动态验证 | 看其 `src/client/index.ts` 或快照 |
| U4 | 显式 `sessionId` 二次 create 真返回同 id | 需动态验证 | 连调两次比对 |
| U5 | 客户端 `prompt` 第 4 参 requestId 是否透传到 Host | 需动态验证 | 同 requestId 发两次看事件数 |
| U6 | `cancel()` → `running=false` 的时延与事件序列 | 需动态验证 | 长任务实测 |
| U7 | **宿主重启后客户端重建**:插槽是否重新注册、apply 是否重跑、浏览器本地状态(旧插件用 localStorage)是否还在 | 需动态验证(**v0.1 关键**) | 重启 DSH,看插件是否 park、绑定是否丢 |
| U8 | **follow 事件流断线重连**:是否零丢失、cursor 续点在哪层 | 需动态验证(**v0.1 关键**) | 断网/重启期间制造事件,重连后核对 |
| U9 | `'conversation.content'` 在非主区位置实例化是否可用 | 需动态验证 | 先做个最小 occurrence |
| U10 | `SessionCreateError.requestedSessionId` 是否真被回填 | 需动态验证 | 制造一次创建失败 |
| U11 | `modelCatalog` 的 efforts 枚举实际内容、`failures` 触发条件 | 需动态验证 | 打真实宿主 |
| U12 | 归档被拒时 `activity` 数组的成员结构 | 需动态验证 | 运行中归档一次 |
| U13 | 两窗口同会话并发投递的行为(租约/互斥) | 需动态验证(实施方案 §8 故障矩阵要求) | 两窗口同时派工 |
| U14 | `dsh.client.immediately` 对本插件的影响 | 需动态验证 | 加字段对比加载时机 |
### 8.3 与实施方案 §3 十二项的对账
| §3 项 | 本文对应 | 当前档位 |
| --- | --- | --- |
| 主页面扩展 | §6.2、§6.4 | 部分未核实(`main` 缺包) |
| 项目树 | §6.1 | 归属已核实,优先级待验证 |
| 内嵌聊天 | §6.3 | 类型层已核实,嵌入可用性未验证 |
| 独立 session | §2.1 | 类型层已核实 |
| 消息投递 | §2.2 | 类型层已核实 |
| 运行关联(hostRunId、终态、取消、重启查询) | §2.2、§2.3、§4.3 | 取消与终态语义已核实;**重启查询未核实** |
| 模型目录 | §3.1、§3.2 | 类型层已核实(Host 侧) |
| 配置/工具权限 | — | **本文未覆盖**(属 index.js 宿主策略层,需另开一节核实 `evaluateToolPolicy` 的宿主约束) |
| 材料/记忆 | — | **本文未覆盖**(未查记忆注入路径) |
| 存储(原子/事务/版本/事件恢复) | — | **本文未覆盖**(§4.1 提到 Host 用 `folded prefix`,插件侧存储方案尚未定) |
| 主题/构建 | §7.3(构建) | 构建契约已核实;主题未核实 |
---
## 9. 对 v0.1 实现的影响
1. **会话创建一律显式传 `sessionId`,别靠 `startSession` + 轮询。** `create({sessionId, cwd, agentPreset})` 天然幂等 adopt,冲突会明确报 `session/conflict` / `agent-preset/conflict`;而旧插件的 `uiWorkspace.startSession()` + `waitNew(15×200ms)`(client.js:1646-1680)是靠"轮询列表找新 id"猜归属,正是实施方案 §6.5 明令禁止的做法。`sessionId` 由 `projectId + roleId` 稳定派生,落库后永不变。
2. **调度必须放 Host 侧,浏览器只订阅。** 依据有二:`sessionController`、`workspaceController` 都是 Host 服务(`TypertRemoteService`,index.d.ts:17-19/20-23),Host 侧能直接 `create`/`prompt`/`follow`/`control`,不需要浏览器在场;而客户端离开页面时 `SessionReference.release()` 会拆掉本地 scope(sessions.d.ts:22-30)。→ `DispatchService`/`Reconciler` 写在 `index.js`(Host apply)里,插件 client 只做 `WorkbenchView`。
3. **幂等键用 `requestId`(Host 侧真幂等),不要自造去重表。** `hasPromptRequest` 会扫 inbox 与历史 `user/message` 的 `rpcId`,**跨重启**仍然生效(commands.js:301-302、547-561)。本项目只需要保证「同一个 dispatch 重试时复用同一个 requestId」。注意走客户端 `binding.session.prompt(...)` 时必须补第 4 参,否则等于没有幂等。
4. **模型配置是"每次派发前覆写",不是"设一次就记住"。** `selectModel` 会后台 `saveSelection` 改全局默认。所以:读 `modelCatalog()` 校验 desired → 每次派发前显式 `selectModel` → 用返回值 `selected` 记成 `effectiveConfigSnapshot`(可能被归一化)→ 失败就明确报错,**不静默换模型**(对应实施方案 §6 三条要求)。UI 的"本次/下次"直接用 `modelSelection` 投影的 `lastUsed` / `next`。
5. **`cancel` 只能到 `cancel_requested`;`inbox` 不会被清。** 要真停,得先 `cancel` 再把排队项逐条 `updateQueue(itemId, {kind:'remove'})`(`QueueAction`,types.d.ts:149-157);而 `updateQueue` 在 `target === 'next-turn'` 且 agent 仍 `running` 时支持 steer,否则抛 `session/steer-unavailable`(commands.js:435-436)。Attempt 状态机的 `cancel_requested → cancelled` 必须由 follow 事件确认,不能凭 `accepted:true`。
6. **左栏不要再注册 `sidebar.workspaces`。** 它是 single/root,已由 ui-workspace 声明、workspace-groups 占据。需要行内动作时只往 `sidebar.workspaces.session.menu.item` / `sidebar.workspaces.session.row.action` 这类 **list** 槽插(additive、按 order),这样不会和别人的 priority 撞(同 cell 同 priority 会抛错)。
7. **中间对话让真会话占 `main.conversation`,不要自己造 conversation。** `'conversation.content'` 是工厂、确实可复用,但 `scope: 'session-maybe'` 的绑定行为本机无法核实。最稳的是沿用旧插件的做法:`ctx.uiWorkspace.openSession(sessionId)` 让原生会话占据主区(client.js:1441-1460),插件只决定"选中哪个 session";需要额外信息就在 `conversation.session.header.actions`(list,旧插件已用 order 40)等已有座位上加,而不是覆盖整块。
8. **P0 收尾必须补 §0.5 那六项动态验证,尤其是 U7(宿主重启)与 U8(断线重连)。** 实施方案 §8 的「重启对账」「重复事件」「两窗口租约」全都依赖这两个行为;如果实测发现 follow 不能零丢失,`Reconciler` 就必须从"增量补偿"升级为"定期全量对账 + 状态机兜底",这会显著改变 §4 的分层预算。在此之前,任何"已通过"的结论都应写成"类型层已核实"。
---
## 附:本文引用的文件清单
| 简称 | 绝对路径 |
| --- | --- |
| ui-slots | `...\@deepseek-ai\dsh-client-ui-slots\lib\types\index.d.ts` |
| ui-renderer | `...\@deepseek-ai\dsh-client-ui-renderer\lib\types\client\registry.d.ts` / `client\index.d.ts` |
| ui-conversation | `...\@deepseek-ai\dsh-client-ui-conversation\lib\types\client\contract\slots.d.ts` |
| ui-sidebar | `...\@deepseek-ai\dsh-client-ui-sidebar\lib\types\client\contract\slots.d.ts` |
| ui-workspace | `...\@deepseek-ai\dsh-client-ui-workspace\lib\types\client\contract\slots.d.ts` / `navigation.d.ts` / `index.d.ts` |
| session-controller | `...\@deepseek-ai\dsh-api-session-controller\lib\types\index.d.ts` / `types.d.ts` / `commands.js` / `agent.js` / `client\contract\*.d.ts` |
| workspace-controller | `...\@deepseek-ai\dsh-api-workspace-controller\lib\types\index.d.ts` / `types.d.ts` / `client\model.d.ts` / `client\service.d.ts` |
| typert-protocol | `...\.pnpm\@deepseek-ai+dsh-typert-pro_ced96565a0ecf302a2ee4e627ca2288b\node_modules\@deepseek-ai\dsh-typert-protocol\lib\types\types.d.ts`、`remote-error.d.ts` |
其中 `...` = `C:\Users\qyh15\Documents\dsh-workspaces-goups-new\dsh-workspace-groups\node_modules\@deepseek-ai`。

View File

@ -0,0 +1,201 @@
# 三省六部工作台 · 新架构 v0.1 · 接线与契约
本文记录 v0.1 已经落地的部分:**数据层、Host 服务层、HTTP 接口、宿主接线**。
它回答三个问题:装了什么、界面能用哪些接口、哪些地方还没验证。实施方案本身见
`docs/v0.1-实施方案.md`,宿主能力的原始取证见 `docs/v0.1-宿主能力记录.md`。
> 版本口径:包版本仍是 0.9.2,**不降级**;"v0.1" 指新架构的第一版,不是包版本号。
## 1. 分层与文件
```
DSH 宿主
└─ index.js 政策插件(prompt / 工具策略 / 模型路由)+ 工作台挂载
└─ workbench/host/… Host 服务:账本、派发、对账、HTTP
└─ workbench/core/… 纯逻辑:ID、编制、状态机、账本、任务判定
workbench/panel/… 浏览器端(右栏部门树 + 任务/成果)
```
### workbench/core —— 纯逻辑,零依赖,可单独测
| 文件 | 行数 | 职责 | 关键导出 |
| --- | --- | --- | --- |
| `workbench/core/ids.mjs` | 81 | 稳定随机 ID、前缀与归属校验 | `newId` / `createIdFactory` / `isIdOf` / `ID_PREFIXES` |
| `workbench/core/roles.mjs` | 192 | 十席编制、布局分组、派发许可 | `ROLE_IDS` / `ROLES` / `layoutGroups` / `canDispatch` / `initialSeats` |
| `workbench/core/states.mjs` | 138 | 四套状态机(部门/任务/派发/尝试) | `STATE_MACHINES` / `canTransition` / `isTerminal` / `assertTransition` |
| `workbench/core/store.mjs` | 1012 | 账本:单写者、事务提交、CAS、引用完整性 | `WorkbenchStore` / `defaultStorePath` / `StoreError` |
| `workbench/core/tasks.mjs` | 436 | 任务状态推进与完成判定 | `createTask` / `beginAttempt` / `decide` / `evaluateCompletion` |
**账本约束(store 强制,不靠调用方自觉)**
- 一个账本文件只有一个写者;`mutate()` 内所有变更同事务提交,失败整批回滚。
- `(projectId, roleId)` 绑定唯一;同一个 `sessionId` 不能同时绑两个部门/项目
(`SESSION_CONFLICT`,带 `heldBy:{projectId,roleId}`);换绑必须显式
`allowReplace`,且 `bindingGeneration` 每次换绑 +1。
- 跨项目引用一律拒绝(`CROSS_PROJECT`);实体的 `projectId` 不可改。
- 配置写入走 CAS:`saveConfig(projectId, roleId, desired, expectedRevision)`,
期望版本不符返回冲突,避免两个标签页互相覆盖。
- 事件日志是**只读游标**:按 `seq` 追加,`listPendingEvents` 过滤未投递未处理的,
`markEventDelivered` 只写 `deliveredAt` 不物理删除。同一 `since` 重放返回同一批事件。
### workbench/host —— 服务层
| 文件 | 行数 | 职责 |
| --- | --- | --- |
| `workbench/host/paths.mjs` | 118 | 侧车目录、原子写、损坏隔离 |
| `workbench/host/service.mjs` | 1293 | 业务服务:项目/席位/绑定/配置/任务/派发/成果,`ServiceError` 翻译,事件化 |
| `workbench/host/contract.mjs` | 144 | 内部契约行解析(四动作)与模板 |
| `workbench/host/session-adapter.mjs` | 282 | 会话适配:创建/查证/投递/取消/模型/摘要 |
| `workbench/host/dispatch-service.mjs` | 207 | 派发:prepared → sending → accepted/rejected/unknown |
| `workbench/host/reconciler.mjs` | 181 | 对账:运行状态与账本对账,超时/重启/取消收口 |
| `workbench/host/routes.mjs` | 414 | HTTP 路由(11 条) |
| `workbench/host/workbench-host.mjs` | 188 | 会话层外壳:会话、派发、对账、契约入库 |
| `workbench/host/index.mjs` | 188 | 唯一 Host 入口:账本 + 外壳 + 路由装配,供 `index.js` 调用 |
### 账本位置
`%DSH_HOME%/sansheng-liubu/workbench.json`(`DSH_HOME` 缺省为 `~/.dsh`;
测试或临时实例可用 `DSH_SANSHENG_WORKBENCH_FILE` 覆盖)。
损坏处理:读不出来就把文件改名成同目录的 `.corrupt-<时间戳>` 隔离,**再**退回内存账本,
并把原因记进 `warnings`;不会静默清空。
## 2. HTTP 接口
前缀 `/sansheng/workbench`,全部同源。响应外层统一:
```json
{ "ok": true, "value": { } }
{ "ok": false, "error": { "code": "INVALID_STATE", "message": "…", "details": { } } }
```
| 方法 | 路径 | 请求体 / 查询 | 说明 |
| --- | --- | --- | --- |
| GET | `/bootstrap` | `?projectId=` | 一次取全:`{projects, projectId, project, seats, layout, tasks, artifacts, results, eventSeq}` |
| POST | `/project` | `hostWorkspaceId`, `displayNameCache?`, `canonicalRoot?` | 登记主机工作区↔项目;重复登记返回既有项目,不重建席位 |
| POST | `/bind` | `projectId`, `roleId`, `sessionId`, `allowReplace?` | 把某个会话绑成某部门;换绑需 `allowReplace` |
| POST | `/config` | `projectId`, `roleId`, `provider`, `model`, `reasoningEffort?`, `expectedRevision?` | 部门模型,CAS 写入;只影响该项目该部门 |
| POST | `/task` | `projectId`, `title`, `objective?`, `acceptance?`, `constraints?`, `scope?`, `ownerRoleId?`, `sourceRoleId?`, `originMessageRef?`, `returnTarget?`, `status?` | 建任务;`status:'queued'` 要求主责部门已接通 |
| POST | `/task/cancel` | `projectId`, `taskId`, `reason?` | 取消任务(终态不可再改) |
| POST | `/connect` | `projectId`, `roleId`, `sessionId?`, `agentPreset?` | 由 Host 建/定位部门会话并绑定;宿主没有会话能力时返回 `INVALID_STATE` |
| POST | `/dispatch` | `projectId`, `taskId`, `idempotencyKey`, `sourceRoleId?`, `targetRoleId`, `targetSessionId?`, `bindingGeneration?`, `packet?`, `sourceSessionId?`, `mode?`, `roleName?` | 派发任务单;有会话层时真投递,没有就只落账 `prepared`(UI 必须显示尚未接通) |
| POST | `/ingest` | `projectId`, `roleId`, `text` | 解析 Agent 输出里的契约行并落账(四动作) |
| POST | `/result` | `projectId`, `taskId`, `attemptId?`, `report?`, `runTerminal?`, `artifactRefs?`, `checks?`, `remainingItems?`, `blockedReason?`, `sourceMessageRef?`, `reportVersion?` | 登记结构化报告 / 运行终态;重复登记按 `attemptId+reportVersion` 与 `sourceMessageRef` 去重 |
| GET | `/events` | `?projectId=&since=` | 长轮询(默认 25s,内部 1s 轮询账本)增量事件;`since` 之后的才算新 |
错误码:`INVALID_INPUT` / `INVALID_ROLE` / `NOT_FOUND` / `CROSS_PROJECT` /
`CONFIG_CONFLICT` / `SESSION_CONFLICT` / `DUPLICATE_PROJECT` / `INVALID_STATE` /
`DISPATCH_INVALID` / `ATTEMPT_MISMATCH` / `REPORT_INVALID` / `INTERNAL`。
## 3. 内部契约行(Agent 怎么"上报")
Agent 不靠聊天里的"已完成"三个字更新任务,而是输出一行以 `【三省六部】` 开头的 JSON:
```
【三省六部】{"action":"dispatchTask","targetRoleId":"gongbu","title":"…","objective":"…"}
【三省六部】{"action":"reportTaskResult","taskId":"tsk_…","summary":"…","checks":["…"],"artifactRefs":["art_…"]}
【三省六部】{"action":"requestTaskInput","taskId":"tsk_…","question":"…"}
【三省六部】{"action":"syncDecision","taskId":"tsk_…","decision":"approved"}
```
- 解析:`parseContractLines(text)` 逐行匹配,坏 JSON / 未知 action 进 `invalid`,**不抛**。
- 入库:`ingestAgentOutput({projectId, roleId, text})`,四条动作各自落账。
- 模板:`describeContract()` 生成给 Agent 看的说明(已注入部门 system prompt)。
## 4. 会话与派发
### 创建(幂等)
宿主 `sessionController.create({sessionId, workspaceId|cwd, agentPreset})`:
`sessionId` 是**唯一**的幂等来源(同 id 同 cwd 同 preset → 返回同会话;
cwd 不同 `session/conflict`;preset 不同 `agent-preset/conflict`)。
`SessionCreateRequest` 里没有 `creationRequestId` —— 实施方案里那一步在宿主不存在,
我们改成"先写账本再建会话,失败留恢复记录"。
### 投递
`prompt({requestId, sessionId, mode:'queue'|'steer', content:[{text}]})`,
`requestId` 用 `attempt.id`(客户端铸造):宿主按它去重,跨重启仍有效。
所有异常在宿主侧折叠成 `session/agent-busy`,因此**投递超时只能判 `unknown`**,
再由 `Reconciler.verifyUnknown` 查证后收口,不能直接判成功或失败。
### 取消
`cancel({sessionId})` 同步返回 `accepted:true`,但**只对已挂载的 agent 生效**、
`keepInbox:true`(排队消息会继续跑)。所以:
- 账本只推进到 `cancel_requested`;
- 要真停还得 `updateQueue({sessionId, itemId, action:'remove'})`;
- 对账看到"跑停了"才写 `cancelled`。
### 模型
- 客户端面没有 `modelCatalog()`,必须从 Host 取。
- `selectModel()` 会连带把选择存成全局默认,所以**每次派发前覆写**,
并把实际用的 provider/model/effort 记进 `effectiveConfigSnapshot`。
- 部门配置变更只改 `desired`(CAS),不动历史;运行中的请求保持原配置。
- 模型不支持旧的 reasoningEffort 时要求重选,不透传非法枚举,不静默回退。
## 5. 完成判定
宿主"运行正常结束"≠ 业务完成。`completed` 需要三件事同时成立:
1. 运行终态是成功(`runTerminal:'succeeded'`);
2. 有可信的结构化报告(`summary` + `checks`),且与任务验收项对得上;
3. 成果引用(`artifactRefs`)能查到实体。
只满足 1 → `needs_attention`(等人补报告);只满足 2、1 未到 → 先登记、候终态;
用户可以主动停 → 记 `cancelled`,不算"成功但没报告"。
## 6. 项目隔离
- 账本是**单一文件**,但所有实体都带 `projectId`,服务层每次读写都校验归属;
- 绑定表主键是 `(projectId, roleId)`,不同项目可以各有自己的工部会话;
- 会话在宿主侧是全局唯一的,所以"同一会话不能再绑别的部门/项目"由账本强制;
- 配置、任务、派发、成果、事件全部按项目分片;切项目必须整树重取,
不允许把上一个项目的 seats/tasks 混进来。
## 7. 宿主接线(index.js)
```js
import { createWorkbenchHost } from './workbench/host/index.mjs'
```
- `apply()` 里在建完政策之后 `acquireWorkbench(ctx, presetId, log)`;
返回的 disposer 末尾 `releaseWorkbench(entry)`。
- 按**账本路径**引用计数:同一份账本只有一个写者;`apply()` 被多个 agent 调用时
不会重复建 store,最后一个卸载时才 `dispose()`。
- 用 `ctx.root ?? ctx` 创建:工作台属于整个应用,不随单个 agent 销毁消失。
- 整体包 try/catch:工作台起不来只打日志,政策插件(prompt/工具策略)照常工作。
- 没有真实宿主服务(单测里的 mock ctx)时直接跳过,不写真实账本、不起计时器。
日志前缀 `[sansheng-liubu:workbench]`。
## 8. 尚未验证 / 已知限制
来自 `docs/v0.1-宿主能力记录.md` §8.2,按影响排序:
| 编号 | 未验证项 | 影响 | 现在的处置 |
| --- | --- | --- | --- |
| U7 | 宿主重启后客户端会话重建 | 重启后账本里的 `targetSessionId` 是否还能打开 | `connectDepartment` 先 `inspectSession`,失效才重建 |
| U8 | `follow` 断线重连是否零丢失 | 对账能否只依赖事件流 | 对账**不**只靠 follow,另有定时 `reconcileOnce` |
| U4 | 二次 `create` 真返回同 id | 幂等是否成立 | 已按"显式 sessionId"实现,验证后无需改代码 |
| U5 | 客户端是否透传 `requestId` | 投递幂等 | 派发走 Host 侧 `sessionController.prompt`,不依赖客户端 |
| U9 | `conversation.content` 能否在非主区实例化 | 全页工作台中间栏 | 先走"主区接管 + 复用原生 `renderFactorySlot`"路线 |
| U1 | `main` 槽的 SlotMap 声明 | 老面板的 `main` 重定向桩 | 与 v0.1 无关,保持现状 |
限制:
- 账本单文件、单写者:同一个 `%DSH_HOME%` 下只能跑一个 DSH 实例写它
(双开会被"同一账本只有一个写者"挡住,而不是写坏)。
- 事件长轮询最长 25 秒,页面隐藏时暂停,恢复时按 `since` 续读,不重放已读。
- 成果只存引用与摘要,不存文件本体。
## 9. 验证
```bash
export PATH="/c/Users/qyh15/AppData/Local/Programs/DeepSeek Harness/resources/runtime/primary-runtime/dependencies/node/bin:$PATH"
node --test --test-isolation=none test/policy.test.js workbench/test/*.test.mjs panel/test/client.test.js
```
当前:**182 passed / 0 failed**(core 60、host 16、service 22、routes 29、policy 11、panel 44)。

120
docs/v0.1-验收记录.md Normal file
View File

@ -0,0 +1,120 @@
# 三省六部独立工作台 v0.1 · 验收记录
对应 `docs/v0.1-实施方案.md` 的 A01–A28 验收矩阵。**本文只记录跑过的东西**:
"已验"必须能指出具体测试名或具体产物;跑不了的写"待真机",不写"完成"。
- 记录时间:2026-11-10
- 代码位置:`C:\Users\qyh15\三省六部\workbench\`(`core/` 数据层、`host/` 宿主服务与路由、`panel/` 前端 bundle)
- 测试基线:`node --test --test-isolation=none test/policy.test.js workbench/test/*.test.mjs workbench/panel/test/client.test.mjs panel/test/client.test.js` → **200 tests / 200 pass / 0 fail**
测试命令(node 不在 PATH,必须先加运行时目录):
```bash
export PATH="/c/Users/qyh15/AppData/Local/Programs/DeepSeek Harness/resources/runtime/primary-runtime/dependencies/node/bin:$PATH"
node --test --test-isolation=none test/policy.test.js workbench/test/*.test.mjs workbench/panel/test/client.test.mjs panel/test/client.test.js
```
---
## 1. 逐项结论
状态口径:
- **已验(单测)**:有对应的自动化测试,跑得过。
- **已验(预览)**:有真 Chrome 渲染的产物(`docs/preview/`),但还没在真实 DSH 页面里跑过。
- **待真机**:逻辑在、测试覆盖不到,必须在重启后的 DSH 里点一遍。
- **未做**:本轮没实现。
| 项 | 判定标准 | 现状 | 证据 / 缺口 |
|---|---|---|---|
| A01 | 无普通聊天时打开上朝,不要求 Team | 待真机 | 前端 `main.conversation` 以 `priority:-1` 接管;需重启后确认独立进入 |
| A02 | 切 A/B、重命名/移动项目不换 session | 已验(单测) | `registerProject 同一工作区只建一个项目`;绑定只用 `hostWorkspaceId` 与 `bindingGeneration`,名称变更不触碰绑定 |
| A03 | 点分组节点不创建项目或十席会话 | 已验(单测) | `layoutGroups renders three tiers without inventing parent links`;`initial seats describe configuration rows without creating sessions` |
| A04 | 双击首次启动同部门只建一个 session | 已验(单测)+ 待真机 | `会话适配:缺 sessionId 时按 workspace 建会话且不重复建`;`绑定:同一会话被别处持有 → SESSION_CONFLICT`。真机二次点击要复验(U4) |
| A05 | 十席分别发短消息,输入/历史/实际 session 一致 | 待真机 | 派发按 `targetSessionId` + `bindingGeneration` 双校验(`dispatchTask` 内),缺真实会话层证据 |
| A06 | A 工部改模型,B 工部用另一模型,全局默认不变 | 部分 | 配置按 `projectId+roleId` 存,`saveDepartmentConfig 走 CAS` 验过;`selectModel` 会改宿主全局默认这点只能在真机确认(记录 L4) |
| A07 | 运行中改模型,本次仍用原模型 | 已验(单测) | `首次派发:固定模型快照 → prompt 用 attemptId 作幂等键`:`effectiveConfigSnapshot` 在派发时冻结 |
| A08 | 模型不支持旧 effort / 目录失效,校验错误可见 | 已验(单测) | `会话适配:prompt 必须带 requestId,错误分类可区分可重试与必失败` 覆盖 `model_unavailable`;不静默替换 |
| A09 | 丞相带文件交接工部,材料可读、引用可追溯 | 部分 | `contextPacket` 有 `materialRefs / authorizationRefs / originMessageRef / excerpts`,`buildDispatchText` 把 materialRefs 写进任务单;**附件级(attachmentId)引用未接** |
| A10 | 正常完成:有效报告+终态+成果核验 | 已验(单测) | `完成判定分支一:报告+终态成功+成果有效 → completed` |
| A11 | 仅变 idle 或输出"已完成"不标记完成 | 已验(单测) | `对账:运行结束但无报告 → needs_attention`;`契约解析只认四动作`(正文里的"已完成"不进状态机) |
| A12 | 重复投递/重复完成/乱序事件不重复、不倒退 | 已验(单测) | `重复点击同一幂等键:不重复投递`;`结果去重:同 (attemptId, reportVersion) 与同 sourceMessageRef 只登记一次`;`isRegressingEvent` 拒绝倒退终态 |
| A13 | 回执超时 → unknown 对账,不自动重发 | 已验(单测) | `投递超时:dispatch 记 unknown,不自动重发` + `verifyUnknown` |
| A14 | 用户直聊与派工同时到达,同 session 串行 | 已验(单测)+ 待真机 | 错误分类 `busy`;真实串行由宿主 inbox 保证,需真机观察 |
| A15 | A/B 同时跑,停止 A,B 继续 | 已验(单测)+ 待真机 | `cancelTask:业务落 cancelled,运行中的尝试只到 cancel_requested`;取消带 `attemptId`,不会误停 B |
| A16 | A 运行时切到 B,A 迟到回调不改 B | 已验(单测) | `对账` 全按 `attemptId` 判定;`宿主重启后查不到会话时不猜` |
| A17 | 刷新/关闭重开/重启宿主后绑定配置任务恢复 | 部分 | 账本落盘 + `events` 游标可重放(`events:since 之后只给新事件,游标可重放`);**U7 宿主重启后客户端重建未验证** |
| A18 | 伪造其他项目 session/task/artifact/run ID 被拒 | 已验(单测) | `项目隔离` 四条:`CROSS_PROJECT` / `NOT_FOUND` 且不泄露归属 |
| A19 | B 不自动获得 A 的材料/记忆 | 部分 | 交接材料只装本任务 packet;记忆隔离属宿主能力,未接 |
| A20 | 相同目录/父子目录识别为冲突,不宣称完全隔离 | 已验(单测) | `A20 同目录/父子目录登记成另一个项目时明确报冲突`:`DUPLICATE_PROJECT` + `relation: same/nested` + `allowSharedRoot` 显式放行 |
| A21 | 两窗口同时改设置/消费队列不覆盖 | 已验(单测) | `saveDepartmentConfig 走 CAS:旧 revision 冲突并带回当前值`;事件日志为只读游标,多标签页不互相偷事件 |
| A22 | 主责部门局部修改成果,保留来源/版本,不重跑全链 | 已验(单测)+ UI 接线中 | `A22 成果修订只开一条修订任务给原主责部门`:`kind:'revision'`、`reviseOfArtifactId`、版本 +1、派发自动带 `materialRefs:[{artifactId,revision}]` |
| A23 | 删除 session 或成果文件后显示失效并保留历史 | 已验(单测)+ UI 接线中 | `A23 成果文件不见了显示 missing…`:`existence: ok/missing/unknown`,账本不改写;session 侧 `binding.status='unavailable'` |
| A24 | 2560×1440 浅/深色、拖宽右栏 | 已验(预览) | `docs/preview/v01-workbench-rail-400-light.png` / `-dark.png`(800×1220,真 Chrome 渲染真实 bundle);拖宽逻辑 340–600 + `sansheng.workbench.railWidth` |
| A25 | 约 390 CSS px 手机宽度抽屉可用 | 待真机 | `compact` 抽屉已实现,未截图验证 |
| A26 | 切主题/项目/部门后草稿、绑定、配置各归所属 | 待真机 | 状态按项目分桶;切项目会重新 `bootstrap`,未真机验证草稿保留 |
| A27 | 键盘选卡片/模型按钮/分隔条/弹层,焦点可恢复 | 待真机 | 卡片 `tabIndex` + Enter/Space、resizer `role="separator"`,未做键盘遍历测试 |
| A28 | 原生聊天审批、附件、流式在工作台同页可用 | 待真机 | 结构上复用 `renderFactorySlot('conversation.content')`,不重造聊天;需真机确认没绕过审批 |
小计:**已验 15 项**(A02 A03 A04 A07 A08 A10 A11 A12 A13 A15 A16 A18 A20 A21 A22 A23 中的单测部分)、**部分 4 项**(A06 A09 A17 A19)、**待真机 8 项**(A01 A05 A14 A25 A26 A27 A28 + A04/A24 的真机部分)、**未做 0 项**。
> 说明:A06/A09/A17/A19 之所以标"部分",是因为判定标准里有一半依赖宿主真实行为或附件通道,
> 光靠单测无法给结论。这几项与 A01/A05/A25–A28 一样,都需要重启 DSH 后补证据。
---
## 2. 本轮新增/改动(相对上一版)
| 文件 | 改动 |
|---|---|
| `workbench/core/store.mjs` | `REFERENCES.artifacts` 增 `revisesArtifactId`(跨项目修订一律拒绝);`recordArtifact` 落 `revisesArtifactId / revision / revisionOfTaskId` |
| `workbench/host/service.mjs` | 新增 `normalizeRoot` + `rootConflict`(A20);`registerProject` 冲突即拒、`allowSharedRoot` 显式放行;新增 `requestArtifactRevision`(A22);`registerArtifact` 支持修订链与版本递增;新增 `artifactView`(A23,`fileExists` 可注入);`dispatchTask` 对修订任务自动补 `materialRefs`;`EVENT_OPS` 增 `requestArtifactRevision` |
| `workbench/host/routes.mjs` | 新增 `POST /sansheng/workbench/artifact/revision`(端点 11 → 12) |
| `workbench/host/index.mjs` / `workbench-host.mjs` | 把宿主 `existsSync` 注入 service(A23 真机可用),测试可替换 |
| `workbench/test/service.test.mjs` | 新增 3 条:A20 冲突、A22 修订链、A23 失效投影 |
| `workbench/test/routes.test.mjs` | 路由数 11 → 12 |
| `workbench/panel/lib/client.js` | 成果区补「文件已失效/位置未核验」标记、修订按钮与内联表单、任务「修订」标签 |
---
## 3. 复现步骤(真机部分)
1. 安装前端 bundle(已执行过一次,幂等):
```bash
node scripts/workbench-install.mjs on # 写进 profile 的 dependencies + dsh.profile.bundles + node_modules junction
node scripts/workbench-install.mjs status # 期望 installed=true, targetExists=true
```
2. **彻底退出 DSH 再启动**(托盘退出,不是关窗口);只对新会话生效。
3. 打开任意项目会话,右侧应出现「朝堂 / 任务 / 成果」。
4. 依次验:接通一个部门 → 派一条任务 → 完成 → 在成果区点「找主责部门修改」。
5. 白屏逃生:控制台 `localStorage['sansheng.workbench.main']='off'` 后刷新,接管会被跳过。
6. 完全回退:`node scripts/workbench-install.mjs off` 再重启。
---
## 4. 已知限制(不含未验证项)
- **L1** 账本损坏时改名隔离(`<file>.corrupt-<时间戳>`),以空账本启动;不做自动修复。
- **L2** 成果只记引用,不复制文件;文件被删后靠 `existence:'missing'` 显示,历史不移除。
- **L3** 目录冲突只做字符串级归一(大小写、分隔符、末尾斜杠),**不解析 junction/短路径真实目标**;命中即报,不宣称隔离。
- **L4** `selectModel` 在宿主侧会连带改全局默认模型,所以派发前一律覆写并快照,不依赖全局默认。
- **L5** `cancel` 不撤回已排队的消息,取消后 FIFO 可能继续跑;因此取消只到 `cancel_requested`,等对账收口。
- **L6** 事件是只读游标 + 可重放,不做"读一次就消失"的队列;两个标签页会看到同一批事件。
- **L7** 400px 栏宽下模型名仍可能截断(三列每列约 112px),完整值在 `title` 里。
## 5. 未验证清单(必须在真机补)
- U7:宿主重启后客户端能否重建并重新读取账本(决定刷新语义)。
- U8:`follow` 断线重连是否零丢失(决定对账预算)。
- U4:二次 `create` 是否真返回同一个 sessionId。
- U5:客户端 `prompt` 的 `requestId` 是否真的透传到服务端幂等表。
- U9:`conversation.content` 工厂嵌入非主区时是否仍工作(当前只接管 `main.conversation`,不涉及)。
- A06 全局默认模型是否被改动、A09 附件级引用、A25 手机抽屉、A27 键盘遍历。
---
## 6. 回退
代码回退用 Git,不建备份副本。注意:**回退代码不会自动回退业务数据**,
`%USERPROFILE%\.dsh\sansheng-liubu\workbench.json` 仍在;schema 变化要写显式迁移,不静默丢弃旧账本。

View File

@ -1,6 +1,7 @@
import fs from 'node:fs'
import os from 'node:os'
import path from 'node:path'
import { createWorkbenchHost, resolveStorePath } from './workbench/host/index.mjs'
const PRESET_ID = 'sansheng-liubu'
export const POLICY_VERSION = '0.4.0'
@ -269,6 +270,65 @@ function registerDeptModelCommand(ctx, handler) {
const INSTALLATIONS = globalThis[Symbol.for('dsh.sansheng-liubu.installations')] ??=
new WeakMap()
/**
* 工作台是“整台机器一份”,不是“每个 agent 一份”:同一份账本只能有一个写者。
* 但本插件的 apply 可能被多次调用(每个组合了「上朝」预设的 agent 各一次),
* 所以按账本路径引用计数:最后一个卸载时才真的 dispose,中途不重复建 store。
*/
const WORKBENCH = globalThis[Symbol.for('dsh.sansheng-liubu.workbench')] ??= new Map()
/**
* 只有真的跑在宿主里才建工作台:单测用 mock ctx 调 apply() 时不该往
* %DSH_HOME% 写账本、也不该起对账计时器。cordis 的 Context 一定有 get()。
*/
function hostSurfaceAvailable(ctx) {
if (!ctx) return false
if (typeof ctx.get === 'function') return true
return Boolean(ctx.webServer || ctx.sessionController || ctx.remote)
}
function acquireWorkbench(ctx, presetId, log) {
if (!hostSurfaceAvailable(ctx)) return null
let file = null
try {
file = resolveStorePath(process.env)
} catch {
// 拿不到路径就退回内存账本,不能因为一个路径算不出来就让政策插件加载失败。
file = null
}
const key = file ?? '(memory)'
const existing = WORKBENCH.get(key)
if (existing) {
existing.refs += 1
return existing
}
const entry = { refs: 1, host: null, key }
try {
// 挂在 root 上:工作台属于整个应用,不该随某个 agent 的销毁一起消失。
entry.host = createWorkbenchHost(ctx?.root ?? ctx, { presetId })
for (const warning of entry.host.warnings ?? []) log?.(warning)
log?.(`账本 ${entry.host.file};接口${entry.host.registered ? '已注册' : '未注册'};`
+ `会话层${entry.host.hasSessions ? '可用' : '不可用(派发只落账)'}`)
} catch (error) {
log?.(`工作台启动失败:${error?.message ?? error}`)
entry.host = null
}
WORKBENCH.set(key, entry)
return entry
}
function releaseWorkbench(entry) {
if (!entry || entry !== WORKBENCH.get(entry.key)) return
entry.refs -= 1
if (entry.refs > 0) return
WORKBENCH.delete(entry.key)
try {
entry.host?.dispose?.()
} catch {
// 卸载失败不影响插件卸载;下次启动仍会从同一个账本继续。
}
}
export const name = 'sansheng-liubu-mode'
export const inject = ['agents', 'agentTeams', 'agentPresets', 'systemPrompt', 'tools', 'commands']
@ -279,6 +339,17 @@ export function apply(ctx, config = {}) {
const owned = new Map()
const audit = entry => ctx.logger?.info?.(`[sansheng-liubu:audit] ${JSON.stringify({ at: new Date().toISOString(), ...entry })}`)
// 工作台:账本 + 部门会话 + HTTP 接口。整体失败只记日志,不能让政策插件加载不了——
// 「上朝」的 prompt/工具策略是刚需,工作台是增量能力。
const logWorkbench = message => {
try {
ctx.logger?.info?.(`[sansheng-liubu:workbench] ${message}`)
} catch {
/* 日志失败不影响业务 */
}
}
const workbench = acquireWorkbench(ctx, presetId, logWorkbench)
const persist = () => {
if (writeStoredRoutes(routeFile, routes)) return
ctx.logger?.warn?.(`[sansheng-liubu] 路由表写入失败:${routeFile}`)
@ -379,5 +450,6 @@ export function apply(ctx, config = {}) {
disposeCreated()
disposeDisposed()
for (const agent of [...owned.keys()]) uninstall(agent)
releaseWorkbench(workbench)
}
}

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,144 @@
#!/usr/bin/env node
// 工作台前端(workbench/panel)的安装开关:只动 profile 的 package.json、
// bundles 列表,以及 node_modules 里的一个链接。它不碰 cordis.patch.yml,
// 也不改「上朝」预设——那是 scripts/mode.mjs 的事。
//
// node scripts/workbench-install.mjs status # 现在装没装
// node scripts/workbench-install.mjs on # 装上(需要彻底重启 DSH 才生效)
// node scripts/workbench-install.mjs off # 卸掉
//
// 幂等:重复执行结果一致;不需要备份(版本历史由 Git 管)。
import { readFile, writeFile, mkdir, lstat, readlink, rm, symlink } from 'node:fs/promises'
import { existsSync } from 'node:fs'
import { homedir } from 'node:os'
import { dirname, join, resolve } from 'node:path'
const NAME = 'dsh-sansheng-liubu-workbench'
const REPO = resolve(import.meta.dirname, '..')
const TARGET = join(REPO, 'workbench', 'panel')
const profileDir = resolve(process.env.DSH_PROFILE_DIR ?? join(homedir(), '.dsh', 'profiles', 'desktop'))
const profilePath = join(profileDir, 'package.json')
const linkPath = join(profileDir, 'node_modules', NAME)
/** Windows 上 `link:` 依赖写成正斜杠;反斜杠在 profile 里会被当成转义。 */
const posix = (value) => value.replace(/\\/g, '/')
async function readProfile() {
return JSON.parse(await readFile(profilePath, 'utf8'))
}
async function writeProfile(profile) {
await writeFile(profilePath, `${JSON.stringify(profile, null, 2)}\n`, 'utf8')
}
async function linkState() {
try {
const stat = await lstat(linkPath)
if (!stat.isSymbolicLink()) return { linked: false, note: '不是链接(可能有同名真实目录)' }
const actual = await readlink(linkPath)
const resolved = resolve(profileDir, 'node_modules', actual)
const ok = resolved.toLowerCase() === resolve(TARGET).toLowerCase()
return { linked: ok, target: actual, note: ok ? undefined : `链接指向 ${actual}` }
} catch (error) {
if (error.code === 'ENOENT') return { linked: false, note: '链接不存在' }
throw error
}
}
async function status() {
const profile = await readProfile()
const link = await linkState()
const bundles = profile.dsh?.profile?.bundles ?? []
return {
profile: profilePath,
target: TARGET,
targetExists: existsSync(join(TARGET, 'lib', 'client.js')),
dependency: profile.dependencies?.[NAME] ?? null,
inBundles: bundles.includes(NAME),
link,
installed: profile.dependencies?.[NAME] === `link:${posix(TARGET)}` && bundles.includes(NAME) && link.linked,
}
}
async function ensureLink() {
await mkdir(dirname(linkPath), { recursive: true })
const state = await linkState()
if (state.linked) return { changed: false }
if (existsSync(linkPath) || state.note === '不是链接(可能有同名真实目录)') await rm(linkPath, { recursive: true, force: true })
// Windows 上用 junction:不需要管理员权限,跳转由文件系统处理。
await symlink(TARGET, linkPath, process.platform === 'win32' ? 'junction' : 'dir')
return { changed: true }
}
async function enable() {
if (!existsSync(join(TARGET, 'lib', 'client.js'))) {
throw new Error(`找不到 ${join(TARGET, 'lib', 'client.js')}:工作台前端还没构建出来,先别装。`)
}
const profile = await readProfile()
let changed = false
profile.dependencies ??= {}
const wanted = `link:${posix(TARGET)}`
if (profile.dependencies[NAME] !== wanted) {
profile.dependencies[NAME] = wanted
changed = true
}
profile.dsh ??= {}
profile.dsh.profile ??= {}
profile.dsh.profile.bundles ??= []
if (!profile.dsh.profile.bundles.includes(NAME)) {
profile.dsh.profile.bundles.push(NAME)
changed = true
}
if (changed) await writeProfile(profile)
const link = await ensureLink()
return {
...(await status()),
changed: changed || link.changed,
hint: changed || link.changed
? '已装上。彻底退出并重启 DSH 后生效(客户端 bundle 在启动时加载,热更新不覆盖)。'
: '本来就已经装好,未改动。',
}
}
async function disable() {
const profile = await readProfile()
let changed = false
if (profile.dependencies && NAME in profile.dependencies) {
delete profile.dependencies[NAME]
changed = true
}
const bundles = profile.dsh?.profile?.bundles
if (Array.isArray(bundles) && bundles.includes(NAME)) {
profile.dsh.profile.bundles = bundles.filter((name) => name !== NAME)
changed = true
}
if (changed) await writeProfile(profile)
let unlinked = false
try {
await rm(linkPath, { recursive: true, force: true })
unlinked = true
} catch {
/* 链接本来就不在 */
}
return {
...(await status()),
changed: changed || unlinked,
hint: changed || unlinked ? '已卸掉。彻底重启 DSH 后生效。' : '本来就没装,未改动。',
}
}
const action = (process.argv[2] ?? 'status').toLowerCase()
const handlers = { status, on: enable, off: disable }
const handler = handlers[action]
if (!handler) {
console.error(`未知动作:${action}(可用:status / on / off)`)
process.exit(2)
}
try {
console.log(JSON.stringify(await handler(), null, 2))
} catch (error) {
console.error(String(error?.message ?? error))
process.exit(1)
}

81
workbench/core/ids.mjs Normal file
View File

@ -0,0 +1,81 @@
// 稳定随机 ID:所有业务主键都由这里生成,名称/路径只作属性,不复用为键。
// 随机源可注入,测试里给定字符表就能复现同一串 ID,避免断言依赖运气。
const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
/** 方案里出现的所有前缀;拼错前缀属于开发期错误,直接抛而不是静默接受。 */
export const ID_PREFIXES = Object.freeze({
project: 'proj',
binding: 'bind',
config: 'cfg',
task: 'task',
dispatch: 'dsp',
attempt: 'att',
contextPacket: 'ctx',
result: 'res',
artifact: 'art',
event: 'evt',
authorization: 'auth',
})
export const ID_ENTITIES = Object.freeze(Object.keys(ID_PREFIXES))
/** 默认随机源:crypto.getRandomValues,取 0..35 的字符。 */
export function cryptoRandom() {
const crypto = globalThis.crypto
if (!crypto || typeof crypto.getRandomValues !== 'function') {
throw new Error('缺少可用的随机源,请注入 random 参数')
}
const bytes = crypto.getRandomValues(new Uint8Array(8))
// 除 36 取余有轻微偏差,但只用于 ID 唯一性,不用于安全令牌。
return ALPHABET[bytes[0] % ALPHABET.length]
}
/**
* 注入的随机源可以返回数字(映射到字母表)或单个字符(必须来自字母表)。
* 两种都接受是为了测试能写 `() => 0` 这样最直白的桩。
*/
function pick(random, index) {
const value = random(index)
if (typeof value === 'number') {
if (!Number.isInteger(value)) throw new Error('随机源必须返回整数或字母表内字符')
// 随机源常被测试当作递增计数器使用,数值可能超过字母表长度甚至为负;
// 先取绝对整数再取模,保证任意整数都能映射到合法字符。
return ALPHABET[Math.abs(value) % 36]
}
const char = String(value)
if (char.length !== 1 || !ALPHABET.includes(char)) throw new Error(`随机源返回了字母表外字符: ${char}`)
return char
}
/**
* 生成 `<prefix>_<随机串>`。
* 前缀既可用实体名('task')也可用前缀本身('task'),两者一致时可省心。
*/
export function newId(prefix, options = {}) {
const { random = cryptoRandom, length = 12 } = options
const known = ID_PREFIXES[prefix]
const resolved = known ?? (Object.values(ID_PREFIXES).includes(prefix) ? prefix : undefined)
if (resolved === undefined) throw new Error(`未知 ID 前缀: ${prefix}`)
if (!Number.isInteger(length) || length < 4 || length > 64) throw new Error('ID 随机串长度须为 4..64')
let out = ''
for (let index = 0; index < length; index += 1) out += pick(random, index)
return `${resolved}_${out}`
}
/** 每个实体一个绑定好随机源的生成器,便于在服务层统一注入并保持测试确定性。 */
export function createIdFactory(options = {}) {
const { random = cryptoRandom, length = 12 } = options
const factory = {}
for (const entity of ID_ENTITIES) {
factory[entity] = () => newId(ID_PREFIXES[entity], { random, length })
}
return Object.freeze(factory)
}
/** 校验外部传入的 ID 形状(防伪 ID 进账;存在性仍由 store 查表)。 */
export function isIdOf(entity, value) {
const prefix = ID_PREFIXES[entity]
if (typeof value !== 'string' || typeof prefix !== 'string') return false
return value.startsWith(`${prefix}_`) && value.length > prefix.length + 1
}

192
workbench/core/roles.mjs Normal file
View File

@ -0,0 +1,192 @@
// 十席角色常量:新工作台的身份只来自可信的 (projectId, roleId) 绑定,
// 不再用 Team membership 推断,也不再让模型自报角色。
// 布局按「丞相居中在顶 → 三省一列一个 → 六部两排(吏户礼 / 兵刑工)」给出,
// UI 直接按 order 渲染稳定三列,连线的上下级由结构表达,不靠坐标猜测。
/**
* column:布局列(lead 跨三列居中)。
* row:视觉行号(0 丞相、1 三省、2/3 六部一排/二排)。
* tier:leaders = 丞相与三省,ministries = 六部;分组只用于展示,不是 session 父子关系。
*/
const SEATS = [
{
id: 'lead',
name: '丞相',
short: '丞',
tier: 'leaders',
group: 'lead',
column: 'span',
row: 0,
duty: '接需求、分流、协调、汇报',
responsibility: '面向用户承接想法:判断是否需要开工、必要时派给具体部门,并把各部门结果汇总成对用户的一次交付。',
canDispatch: true,
},
{
id: 'zhongshu',
name: '中书',
short: '中',
tier: 'leaders',
group: 'sansheng',
column: 'left',
row: 1,
duty: '调查、澄清、规划',
responsibility: '先把问题问清、把材料看全,再给出可执行的方案与验收标准草案,不直接产出最终交付物。',
canDispatch: false,
},
{
id: 'shangshu',
name: '尚书',
short: '尚',
tier: 'leaders',
group: 'sansheng',
column: 'center',
row: 1,
duty: '分工建议、组织交付',
responsibility: '把已经明确的方案拆成部门分工并组织交付;六部直属于尚书这一同级分组,六部之间不是上下级。',
canDispatch: true,
},
{
id: 'menxia',
name: '门下',
short: '门',
tier: 'leaders',
group: 'sansheng',
column: 'right',
row: 1,
duty: '审议与整体审核',
responsibility: '对方案和交付做独立审议,指出风险与不达标处。首版没有门下审核的任务必须如实标注“未审核”。',
canDispatch: false,
},
{
id: 'libu',
name: '吏部',
short: '吏',
tier: 'ministries',
group: 'ministries',
column: 'left',
row: 2,
duty: '角色和技能配置建议',
responsibility: '对角色、技能与编制给出建议;职责不含绕过用户授权去改权限或其他项目设置。',
canDispatch: false,
},
{
id: 'hubu',
name: '户部',
short: '户',
tier: 'ministries',
group: 'ministries',
column: 'center',
row: 2,
duty: '数据、表格、计算',
responsibility: '处理数据、表格与计算,结论应可复算。',
canDispatch: false,
},
{
id: 'lipu',
name: '礼部',
short: '礼',
tier: 'ministries',
group: 'ministries',
column: 'right',
row: 2,
duty: '文档、内容、呈现',
responsibility: '负责文档、内容与呈现形式,产出可编辑的源文件。',
canDispatch: false,
},
{
id: 'bingbu',
name: '兵部',
short: '兵',
tier: 'ministries',
group: 'ministries',
column: 'left',
row: 3,
duty: '环境、调试、部署',
responsibility: '负责环境、调试与部署;部署/发布等外部副作用仍服从用户授权与宿主审批。',
canDispatch: false,
},
{
id: 'xingbu',
name: '刑部',
short: '刑',
tier: 'ministries',
group: 'ministries',
column: 'center',
row: 3,
duty: '测试与风险检查',
responsibility: '做测试与风险检查,给出可追溯的检查结果,而不是一句“已通过”。',
canDispatch: false,
},
{
id: 'gongbu',
name: '工部',
short: '工',
tier: 'ministries',
group: 'ministries',
column: 'right',
row: 3,
duty: '代码实现与工程产出',
responsibility: '负责代码实现与工程产出,交付可编辑源文件与真实检查结果。',
canDispatch: false,
},
]
export const ROLE_IDS = Object.freeze(SEATS.map((seat) => seat.id))
const byId = new Map(SEATS.map((seat) => [seat.id, Object.freeze(seat)]))
/** 稳定顺序(上表即布局顺序),UI 与初始化都按这个序写,避免每次渲染顺序抖动。 */
export const ROLES = Object.freeze(ROLE_IDS.map((id) => byId.get(id)))
/** 布局顺序 = 数组顺序;单独导出常量是为了让调用方不必依赖“数组被排序过”这个隐含约定。 */
export const LAYOUT_ORDER = ROLE_IDS
export const LEADERS = Object.freeze(ROLES.filter((seat) => seat.tier === 'leaders').map((seat) => seat.id))
export const MINISTRIES = Object.freeze(ROLES.filter((seat) => seat.tier === 'ministries').map((seat) => seat.id))
export function isRoleId(value) {
return typeof value === 'string' && byId.has(value)
}
/** 未知角色返回 undefined,由调用方决定报错文案(不同入口提示不同)。 */
export function getRole(roleId) {
return byId.get(roleId)
}
/** 找不到就抛:角色是内部常量,拼错属于代码错误而非用户输入错误。 */
export function requireRole(roleId) {
const seat = byId.get(roleId)
if (seat === undefined) throw new Error(`未知角色: ${String(roleId)}`)
return seat
}
export const ROLE_NAMES = Object.freeze(Object.fromEntries(ROLES.map((seat) => [seat.id, seat.name])))
/** 存储与显示的兼容映射:旧代码用“中书省/尚书省/门下省”,roleId 不变,名称不参与身份。 */
export const ROLE_NAME_ALIASES = Object.freeze({
zhongshu: Object.freeze(['中书省']),
shangshu: Object.freeze(['尚书省']),
menxia: Object.freeze(['门下省']),
})
/** 按布局把十席分成分组,供右侧部门树一次画完:top / sansheng / ministries 两排。 */
export function layoutGroups() {
return {
lead: ROLES.filter((seat) => seat.id === 'lead').map((seat) => seat.id),
sansheng: ROLES.filter((seat) => seat.group === 'sansheng').map((seat) => seat.id),
ministries: [
ROLES.filter((seat) => seat.tier === 'ministries' && seat.row === 2).map((seat) => seat.id),
ROLES.filter((seat) => seat.tier === 'ministries' && seat.row === 3).map((seat) => seat.id),
],
}
}
/** 首版允许主动派工的席:丞相默认,尚书在用户明确要求时经同一权限校验。 */
export function canDispatch(roleId) {
return byId.get(roleId)?.canDispatch === true
}
/** 初始化项目时用的角色清单(不创建会话,只建配置与绑定初值)。 */
export function initialSeats() {
return ROLES.map((seat) => ({ roleId: seat.id, name: seat.name, tier: seat.tier }))
}

138
workbench/core/states.mjs Normal file
View File

@ -0,0 +1,138 @@
// 四套状态机分开维护:部门运行、任务结论、投递进度、单次尝试。
// 合并成一个大状态会让“空闲”被当成“已完成”,正是方案 7.3/8.1 明确禁止的误判。
export const TASK_STATES = Object.freeze([
'draft',
'queued',
'running',
'waiting_input',
'needs_attention',
'completed',
'failed',
'cancelled',
])
export const DISPATCH_STATES = Object.freeze(['prepared', 'sending', 'accepted', 'unknown', 'rejected'])
export const ATTEMPT_STATES = Object.freeze([
'queued',
'running',
'succeeded',
'failed',
'cancel_requested',
'cancelled',
'unknown',
])
export const DEPARTMENT_STATES = Object.freeze(['uninitialized', 'idle', 'queued', 'running', 'unavailable'])
/**
* Task:draft 校验通过且授权有效才入队;waiting_input 只能回到原任务的执行路径,
* completed 是唯一“可交付”终态;needs_attention 仍可补报后完成,也可显式失败/取消。
* 终态(completed / failed / cancelled)不回到任何活动状态:重试一律新 attempt 或新任务。
*/
const TASK_TRANSITIONS = Object.freeze({
draft: Object.freeze(['queued', 'cancelled']),
queued: Object.freeze(['running', 'waiting_input', 'needs_attention', 'failed', 'cancelled']),
running: Object.freeze(['waiting_input', 'needs_attention', 'completed', 'failed', 'cancelled']),
waiting_input: Object.freeze(['queued', 'running', 'cancelled']),
needs_attention: Object.freeze(['running', 'completed', 'failed', 'cancelled']),
completed: Object.freeze([]),
failed: Object.freeze([]),
cancelled: Object.freeze([]),
})
/** Dispatch:发出不等于接收;超时可能 unknown,必须先对账,不能自动当失败重试。 */
const DISPATCH_TRANSITIONS = Object.freeze({
prepared: Object.freeze(['sending', 'rejected', 'unknown']),
sending: Object.freeze(['accepted', 'unknown', 'rejected']),
accepted: Object.freeze([]),
unknown: Object.freeze(['accepted', 'rejected']),
rejected: Object.freeze([]),
})
/** Attempt:cancel_requested 不等于已取消;unknown 必须先核对宿主运行再定终态。 */
const ATTEMPT_TRANSITIONS = Object.freeze({
queued: Object.freeze(['running', 'cancelled', 'failed', 'unknown']),
running: Object.freeze(['succeeded', 'failed', 'cancel_requested', 'unknown']),
cancel_requested: Object.freeze(['cancelled', 'succeeded', 'unknown']),
succeeded: Object.freeze([]),
failed: Object.freeze([]),
cancelled: Object.freeze([]),
unknown: Object.freeze(['succeeded', 'failed', 'cancelled', 'running']),
})
/** Department 只表达会话运行情况:unavailable 是绑定失效,仍保留旧引用。 */
const DEPARTMENT_TRANSITIONS = Object.freeze({
uninitialized: Object.freeze(['idle', 'queued', 'unavailable']),
idle: Object.freeze(['queued', 'running', 'unavailable']),
queued: Object.freeze(['running', 'idle', 'unavailable']),
running: Object.freeze(['idle', 'queued', 'unavailable']),
unavailable: Object.freeze(['uninitialized', 'idle']),
})
const MACHINES = Object.freeze({
task: Object.freeze({ key: 'task', name: 'Task', states: TASK_STATES, transitions: TASK_TRANSITIONS }),
dispatch: Object.freeze({ key: 'dispatch', name: 'Dispatch', states: DISPATCH_STATES, transitions: DISPATCH_TRANSITIONS }),
attempt: Object.freeze({ key: 'attempt', name: 'Attempt', states: ATTEMPT_STATES, transitions: ATTEMPT_TRANSITIONS }),
department: Object.freeze({ key: 'department', name: 'Department', states: DEPARTMENT_STATES, transitions: DEPARTMENT_TRANSITIONS }),
})
export const STATE_MACHINES = Object.freeze(
Object.fromEntries(Object.entries(MACHINES).map(([key, machine]) => [key, Object.freeze({
name: machine.name,
states: machine.states,
transitions: machine.transitions,
})])),
)
export const TERMINAL_STATES = Object.freeze({
task: Object.freeze(['completed', 'failed', 'cancelled']),
dispatch: Object.freeze(['accepted', 'rejected']),
attempt: Object.freeze(['succeeded', 'failed', 'cancelled']),
department: Object.freeze([]),
})
function machineOf(kind) {
const machine = MACHINES[kind]
if (machine === undefined) throw new Error(`未知状态机: ${String(kind)}`)
return machine
}
export function statesOf(kind) {
return machineOf(kind).states
}
export function isState(kind, value) {
return machineOf(kind).states.includes(value)
}
export function allowedTransitions(kind, from) {
const machine = machineOf(kind)
if (!machine.states.includes(from)) throw new Error(`${machine.name} 未知状态: ${String(from)}`)
return machine.transitions[from]
}
export function canTransition(kind, from, to) {
// 同状态重复写入不算迁移:事件重放时应由调用方静默忽略,而不是报错。
if (from === to) return true
return allowedTransitions(kind, from).includes(to)
}
const MACHINE_KEY = Object.freeze({ task: 'task', dispatch: 'dispatch', attempt: 'attempt', department: 'department' })
export function isTerminal(kind, state) {
return TERMINAL_STATES[machineOf(kind).key].includes(state)
}
/** 非法迁移一律抛错:状态倒退还沉默会让故障矩阵里“终态不被覆盖”的保证失效。 */
export function assertTransition(kind, from, to) {
const machine = machineOf(kind)
if (!machine.states.includes(from)) throw new Error(`${machine.name} 当前状态非法: ${String(from)}`)
if (!machine.states.includes(to)) throw new Error(`${machine.name} 目标状态非法: ${String(to)}`)
if (from === to) return to
if (!machine.transitions[from].includes(to)) {
throw new Error(`${machine.name} 不允许从 ${from} 迁移到 ${to}`)
}
return to
}

1019
workbench/core/store.mjs Normal file

File diff suppressed because it is too large Load Diff

436
workbench/core/tasks.mjs Normal file
View File

@ -0,0 +1,436 @@
// 任务生命周期:纯函数 + 显式副作用端口。
// 判定永远不读聊天文本,只认结构化报告、宿主真实终态和可解析的成果引用——
// 这是“agent 说已完成”与“任务完成”分开的落点。
// 副作用(写 store、入队、回传)由调用方注入,core 本身不碰网络和调度。
import { assertTransition, isState, isTerminal } from './states.mjs'
import { isRoleId } from './roles.mjs'
export class TaskError extends Error {
constructor(code, message, details = undefined) {
super(message)
this.name = 'TaskError'
this.code = code
if (details !== undefined) this.details = details
}
}
const TASK_BASE_TRANSITIONS = Object.freeze([
['draft', 'queued'],
['queued', 'running'],
['running', 'waiting_input'],
['running', 'needs_attention'],
['running', 'completed'],
['running', 'failed'],
['waiting_input', 'queued'],
['waiting_input', 'running'],
['needs_attention', 'completed'],
['needs_attention', 'running'],
['needs_attention', 'failed'],
// 取消可在任何非终态发起
['draft', 'cancelled'],
['queued', 'cancelled'],
['running', 'cancelled'],
['waiting_input', 'cancelled'],
['needs_attention', 'cancelled'],
// 入队后模型不可用:允许直接失败并保留错误
['queued', 'failed'],
])
export const TASK_TRANSITIONS = Object.freeze(TASK_BASE_TRANSITIONS.map(([from, to]) => Object.freeze([from, to])))
const TERMINAL_TASK_STATES = Object.freeze(['completed', 'failed', 'cancelled'])
/** seq 比较:仅当新事件 seq 严格大于已见 seq 才视为“更新”。 */
export function isStaleSeq(lastSeq, nextSeq) {
if (lastSeq === null || lastSeq === undefined) return false
if (!Number.isFinite(nextSeq)) return true
return nextSeq <= lastSeq
}
/** 乱序/重复事件:达到终态后任何“回到活动态”的事件都必须忽略,而不是报错中断处理。 */
export function isRegressingEvent(currentStatus, nextStatus) {
if (TERMINAL_TASK_STATES.includes(currentStatus)) return currentStatus !== nextStatus
return false
}
function transition(state, next, extra = {}) {
assertTransition('task', state, next)
return next
}
function requireString(value, field) {
if (typeof value !== 'string' || value.trim() === '') {
throw new TaskError('INVALID_INPUT', `${field} 必须是非空字符串`)
}
return value
}
function requireTask(task) {
if (task === null || typeof task !== 'object' || typeof task.id !== 'string') {
throw new TaskError('INVALID_TASK', '任务记录不合法')
}
return task
}
/**
* createTask:只建草稿。draft 不等于入队,校验通过且授权有效后才 startTask 入队。
* ownerRoleId 与 sourceRoleId 都必须是已知席,来源席默认丞相。
*/
export function createTask(options, deps = {}) {
const { projectId, title, objective, acceptance = [], ownerRoleId, sourceRoleId = 'lead', originMessageRef = null, scope = null, constraints = [], returnTarget = null } = options ?? {}
requireString(projectId, 'projectId')
requireString(title, 'title')
requireString(objective, 'objective')
if (!isRoleId(ownerRoleId)) throw new TaskError('INVALID_ROLE', `未知主责部门: ${String(ownerRoleId)}`)
if (!isRoleId(sourceRoleId)) throw new TaskError('INVALID_ROLE', `未知来源部门: ${String(sourceRoleId)}`)
const id = typeof deps.newTaskId === 'function' ? deps.newTaskId() : undefined
const stamp = typeof deps.now === 'function' ? deps.now() : new Date().toISOString()
return {
...(id === undefined ? {} : { id }),
projectId,
title,
objective,
acceptance: Array.isArray(acceptance) ? [...acceptance] : [String(acceptance)],
constraints: Array.isArray(constraints) ? [...constraints] : [],
scope: scope ?? null,
ownerRoleId,
sourceRoleId,
originMessageRef,
returnTarget,
status: 'draft',
activeAttemptId: null,
attempts: [],
startedAt: null,
endedAt: null,
reportReceivedAt: null,
needsAttentionReason: null,
failureReason: null,
waitingReason: null,
revision: 1,
createdAt: stamp,
updatedAt: stamp,
}
}
/** 入队:唯一需要的前置是 draft,或者 waiting_input 拿到补充。 */
export function startTask(task, deps = {}) {
requireTask(task)
if (task.status !== 'draft' && task.status !== 'waiting_input') {
throw new TaskError('INVALID_STATE', `只有草稿或待补充的任务可以入队,当前 ${task.status}`)
}
const stamp = stampOf(deps)
return {
...task,
status: transition(task.status, 'queued'),
waitingReason: null,
revision: task.revision + 1,
updatedAt: stamp,
}
}
/**
* beginAttempt:队列中的任务进入执行,并绑定一次尝试。
* 每次重试都是新 attempt,旧尝试(及旧结果引用)保留,不覆盖成“第一次就成功”。
*/
export function beginAttempt(task, attempt, deps = {}) {
requireTask(task)
if (task.status !== 'queued' && task.status !== 'waiting_input' && task.status !== 'needs_attention' && task.status !== 'running') {
throw new TaskError('INVALID_STATE', `任务 ${task.status} 不能开始新的尝试`)
}
// 是否“仍有活动尝试”不能只看 activeAttemptId 是否为空:
// 取消/失败/对账后,Attempt 已转 cancelled/failed/succeeded 终态,但任务的 activeAttemptId 仍指向它(保留审计),
// 若只看非空就会把取消后的重试挡在 ACTIVE_ATTEMPT 上。deps.attemptLookup 由调用方注入(core 不读 store),
// 只有明确查到“非终态”尝试时才算有活动尝试;查不到(undefined/null)时保持旧行为,按非空处理。
// 另:attempt 的 unknown 是待对账状态,不算终态,仍会挡住重试。
const hasActiveAttempt = task.activeAttemptId !== null && task.activeAttemptId !== undefined
&& !isSettledAttempt(task.activeAttemptId, deps)
// running 下换尝试等于重试:必须先把旧尝试对账(失败/取消),否则两次运行会同时往一个任务里写结果。
if (task.status === 'running' && hasActiveAttempt) {
throw new TaskError('ACTIVE_ATTEMPT', '当前尝试仍在运行,先对账再重试')
}
if (attempt === null || typeof attempt !== 'object' || typeof attempt.id !== 'string') {
throw new TaskError('INVALID_ATTEMPT', '尝试记录不合法')
}
if (attempt.projectId !== task.projectId) {
throw new TaskError('CROSS_PROJECT', '尝试与任务不属于同一项目')
}
if (attempt.taskId !== task.id) {
throw new TaskError('CROSS_TASK', '尝试挂在别的任务上')
}
if (task.status === 'needs_attention' && hasActiveAttempt) {
throw new TaskError('ACTIVE_ATTEMPT', '仍有未对账的尝试,先完成或标记失败')
}
const stamp = stampOf(deps)
return {
...task,
status: transition(task.status, 'running'),
activeAttemptId: attempt.id,
attempts: [...task.attempts, attempt.id],
startedAt: task.startedAt ?? stamp,
needsAttentionReason: null,
waitingReason: null,
revision: task.revision + 1,
updatedAt: stamp,
}
}
/** 结构化报告是否“可信”:summary 非空、成果引用形状正确、检查是真实结果而非空话。 */
export function validateReport(report) {
const errors = []
if (report === null || typeof report !== 'object') return ['报告必须是对象']
if (!report.attemptId || typeof report.attemptId !== 'string') errors.push('缺少 attemptId')
if (!report.taskId || typeof report.taskId !== 'string') errors.push('缺少 taskId')
if (typeof report.summary !== 'string' || report.summary.trim() === '') errors.push('结果摘要为空')
if (report.artifactRefs !== undefined) {
if (!Array.isArray(report.artifactRefs)) errors.push('artifactRefs 必须是数组')
else {
for (const ref of report.artifactRefs) {
if (typeof ref !== 'string' || !ref.startsWith('art_')) errors.push(`成果引用形状非法: ${String(ref)}`)
}
}
}
if (report.checks !== undefined && !Array.isArray(report.checks)) errors.push('checks 必须是数组')
return errors
}
/**
* 三条完成条件各占一票,缺一条都不能标 completed:
* 1. 可信结构化报告(有摘要、有检查、没有未解决阻塞)
* 2. 宿主运行终态成功(由调用方从宿主取得,不能猜“空闲=成功”)
* 3. 成果引用有效(引用指向本项目现存成果,或被显式标为不可用)
*/
export function checkCompletion(input) {
const { report = null, runTerminal = null, artifactRefs = [], artifactLookup = null } = input ?? {}
const blockers = []
let reportOk = false
if (report !== null) {
const errors = validateReport(report)
if (errors.length > 0) blockers.push(...errors)
else if (typeof report.blockedReason === 'string' && report.blockedReason.trim() !== '') {
blockers.push('报告标记了阻塞原因')
} else reportOk = true
} else {
blockers.push('未收到结构化报告')
}
const runOk = runTerminal === 'succeeded'
if (runTerminal === null) blockers.push('宿主运行尚未结束')
else if (!runOk) blockers.push(`宿主运行终态为 ${String(runTerminal)}`)
const refs = Array.isArray(artifactRefs) ? artifactRefs : []
const invalidRefs = []
for (const ref of refs) {
if (typeof ref !== 'string' || !ref.startsWith('art_')) invalidRefs.push(String(ref))
else if (typeof artifactLookup === 'function') {
const artifact = artifactLookup(ref)
if (artifact === undefined || artifact === null) invalidRefs.push(ref)
else if (artifact.verification?.status === 'missing') invalidRefs.push(ref)
}
}
if (invalidRefs.length > 0) blockers.push(`成果引用无效: ${invalidRefs.join(', ')}`)
// 纯分析任务允许没有文件,所以“引用为空”本身不算失败,但登记结果时不能伪造附件。
return { reportOk, runOk, refsValid: invalidRefs.length === 0, blockers, ok: reportOk && runOk && invalidRefs.length === 0 }
}
/**
* 完成判定三分支:
* - 报告 + 终态成功 + 成果有效 → completed
* - 只有报告(运行未结束) → 保持 running 等终态(waiting 只是“候选结果已存”)
* - 只有终态(无报告) → needs_attention,提供补报入口,不显示已完成
*/
export function evaluateCompletion(task, input, deps = {}) {
return decide(task, { kind: 'completion', ...input }, deps)
}
/**
* 统一事件入口:先按 seq 去重、再按状态机判定。旧 seq 或终态后的事件返回
* { applied:false, stale:true, task },让调用方知道“什么都没变”而不是误以为写入失败。
*/
export function decide(task, event, deps = {}) {
requireTask(task)
if (event === null || typeof event !== 'object') throw new TaskError('INVALID_EVENT', '事件必须是对象')
const nextSeq = event.seq
if (nextSeq !== undefined && isStaleSeq(task.lastSeq ?? null, nextSeq)) {
return { applied: false, stale: true, task }
}
const stamp = stampOf(deps)
const base = nextSeq === undefined ? task : { ...task, lastSeq: nextSeq }
const commit = (next) => ({
applied: true,
stale: false,
task: applyStamp({ ...next, id: task.id, projectId: task.projectId }, next, stamp, base),
})
switch (event.kind) {
case 'completion': {
if (isTerminal('task', task.status)) return { applied: false, stale: true, task, reason: '任务已终态' }
const verdict = checkCompletion(event)
if (!verdict.reportOk && verdict.runOk) {
return commit({
...base,
status: transition(task.status, 'needs_attention'),
needsAttentionReason: '宿主运行已结束但没有有效的结构化报告',
reportReceivedAt: base.reportReceivedAt ?? null,
})
}
// 用户主动停止的会话,运行终态是 cancelled 而不是"成功但没报告":
// 这一票足以把任务收成 cancelled,不需要也不可能再等到结构化报告。
if (event.runTerminal === 'cancelled' && !verdict.reportOk) {
return commit({ ...base, status: transition(task.status, 'cancelled'), endedAt: stamp })
}
if (!verdict.ok) {
// 报告不完整:只记录候选报告,等下一次带完整信息的事件。
return { applied: false, stale: false, task: base, reason: verdict.blockers.join('; '), verdict }
}
return commit({
...base,
status: transition(task.status, 'completed'),
reportReceivedAt: stamp,
needsAttentionReason: null,
failureReason: null,
})
}
case 'report': {
if (isTerminal('task', task.status)) return { applied: false, stale: true, task }
const errors = validateReport(event.report)
if (errors.length > 0) throw new TaskError('INVALID_REPORT', errors.join('; '), { errors })
// 报告先到:保存候选结果,等待宿主终态。
return commit({ ...base, reportReceivedAt: stamp, needsAttentionReason: null })
}
case 'run_terminal': {
if (isTerminal('task', task.status)) return { applied: false, stale: true, task }
const state = event.runTerminal
if (state === 'succeeded') {
// 只有报告已经到达,才可能在这里直接完成;否则留给 completion 判定。
if (base.reportReceivedAt !== null && base.status === 'running') {
return commit({ ...base, status: transition(task.status, 'completed') })
}
return { applied: false, stale: false, task: base, reason: '等待结构化报告' }
}
if (state === 'cancelled') {
return commit({ ...base, status: transition(task.status, 'cancelled'), endedAt: stamp })
}
return commit({
...base,
status: transition(task.status, 'needs_attention'),
needsAttentionReason: `宿主运行终态为 ${String(state)}`,
})
}
case 'input_required': {
if (task.status !== 'running' && task.status !== 'queued') {
return { applied: false, stale: false, task, reason: `任务 ${task.status} 不接受待补充状态` }
}
return commit({ ...base, status: transition(task.status, 'waiting_input'), waitingReason: String(event.reason ?? '') })
}
case 'input_supplied': {
if (task.status !== 'waiting_input') return { applied: false, stale: false, task, reason: '任务不在待补充状态' }
return commit({ ...base, status: transition(task.status, 'running'), waitingReason: null })
}
case 'retry': {
if (task.status !== 'failed' && task.status !== 'cancelled') {
return { applied: false, stale: false, task, reason: '只有失败或已取消的任务可以重试(新任务)' }
}
throw new TaskError('RETRY_REQUIRES_NEW_TASK', '失败/取消后的重试必须创建新任务与新尝试,不能复活旧记录')
}
default:
throw new TaskError('UNKNOWN_EVENT', `未知事件类型: ${String(event.kind)}`)
}
}
/** 结束时间只写一次:重复到达的终态事件不应改动“最后一次改动时间”。 */
function applyStamp(task, next, stamp, base) {
const now = { ...base, ...next, updatedAt: stamp }
// completed/failed/cancelled 结束时间只写一次,重复写入会伪造“最后一次改动时间”。
if (TERMINAL_TASK_STATES.includes(now.status) && now.endedAt === null) now.endedAt = stamp
if (!Number.isFinite(now.revision) || now.revision < 1) now.revision = 1
else if (now.status !== task.status) now.revision = task.revision + 1
return now
}
function stampOf(deps) {
return typeof deps.now === 'function' ? deps.now() : new Date().toISOString()
}
/**
* activeAttemptId 指向的尝试是否已对账(终态)。
* 调用方通过 deps.attemptLookup(attemptId) 提供当前 Attempt 记录;core 不直接读 store。
* unknown 是“待核对宿主”的中间态,不是终态,因此仍然算活动尝试。
*/
function isSettledAttempt(attemptId, deps) {
const lookup = deps?.attemptLookup
if (typeof lookup !== 'function') return false
const record = lookup(attemptId)
if (record === null || record === undefined || typeof record !== 'object') return false
return isTerminal('attempt', record.state)
}
// ---------- 便捷包装:每个都只调用 decide,签名简单便于调用方阅读 ----------
export function requestInput(task, reason, deps = {}) {
return decide(task, { kind: 'input_required', reason, seq: deps.seq }, deps)
}
export function supplyInput(task, deps = {}) {
return decide(task, { kind: 'input_supplied', seq: deps.seq }, deps)
}
export function completeTask(task, input, deps = {}) {
return decide(task, { kind: 'completion', ...input, seq: input?.seq }, deps)
}
/** 失败必须带原因:没有原因的失败在详情页无法给出恢复入口。 */
export function failTask(task, reason, deps = {}) {
requireTask(task)
requireString(reason, 'reason')
if (isTerminal('task', task.status)) {
return { applied: false, stale: true, task, reason: '任务已终态' }
}
const stamp = stampOf(deps)
return {
applied: true,
stale: false,
task: {
...task,
status: transition(task.status, 'failed'),
failureReason: reason,
updatedAt: stamp,
endedAt: task.endedAt ?? stamp,
revision: task.revision + 1,
},
}
}
/** 取消是请求,不是结果:这里只落“已取消”的业务结论,宿主的 cancel_requested 另记在 attempt。 */
export function cancelTask(task, reason = '用户取消', deps = {}) {
requireTask(task)
if (isTerminal('task', task.status)) {
return { applied: false, stale: true, task, reason: '任务已终态' }
}
const stamp = stampOf(deps)
return {
applied: true,
stale: false,
task: {
...task,
status: transition(task.status, 'cancelled'),
failureReason: task.failureReason ?? null,
cancelReason: reason,
updatedAt: stamp,
endedAt: task.endedAt ?? stamp,
revision: task.revision + 1,
},
}
}
/** 把 decide 的结果套到 store 上:只有 applied 才写,避免陈旧事件产生 revision 抖动。 */
export function applyDecision(store, taskId, decision) {
if (store === undefined || store === null) throw new TaskError('INVALID_STORE', '需要 store')
if (decision === null || typeof decision !== 'object') throw new TaskError('INVALID_DECISION', '判定结果不合法')
if (decision.applied !== true) return decision
const saved = store.updateTask(decision.task)
return { ...decision, task: saved }
}
/** 任务是否仍在进行(UI 需要区分终态与活动态,但不允许显示百分比)。 */
export function isOpenTask(task) {
return task !== null && typeof task === 'object' && isState('task', task.status) && !isTerminal('task', task.status)
}

144
workbench/host/contract.mjs Normal file
View File

@ -0,0 +1,144 @@
// 部门 ↔ 程序的内部操作契约(方案 §6)。
//
// 四个动作是唯一的“业务事实来源”:
// dispatchTask / reportTaskResult / requestTaskInput / syncDecision
// 部门在会话里怎么说话都不影响账本;账本只认这四条结构化调用。
//
// 部门在没有自建 HTTP 通道时,用一段可解析的行内指令表达这四个动作:
// 【三省六部】{"action":"reportTaskResult","taskId":"task_…","attemptId":"att_…",…}
// 指令行必须单独成行,前缀固定、正文是单行 JSON。解析器宁可返回 null 也不猜测:
// 解析失败的行当普通文本,绝不用“看起来像”的句子更新任务状态(方案明令禁止)。
//
// 这里只做“文本 ↔ 结构化调用”的纯转换,不碰网络、不碰 store,便于单测。
export const CONTRACT_ACTION_PREFIX = '【三省六部】'
/** 四个合法动作:多一个少一个都属于“意图不明”,直接拒绝而不是猜。 */
export const CONTRACT_ACTIONS = Object.freeze([
'dispatchTask',
'reportTaskResult',
'requestTaskInput',
'syncDecision',
])
const ACTION_SET = new Set(CONTRACT_ACTIONS)
export class ContractError extends Error {
constructor(code, message, details = undefined) {
super(message)
this.name = 'ContractError'
this.code = code
if (details !== undefined) this.details = details
}
}
/**
* 从一段部门输出里取出全部契约行。
*
* 返回 { calls, invalid }:
* - calls:解析成功的调用,按出现顺序;
* - invalid:看起来像契约行但 JSON 坏了/缺 action 的行(附原文,便于在 UI 上提示重发)。
*
* 一个动作只接受一行一条。同一行里塞数组视为格式错误:批量派发必须逐条写,
* 否则“派发到一半失败”无法解释是哪一条。
*/
export function parseContractLines(text) {
const calls = []
const invalid = []
if (typeof text !== 'string' || text === '') return { calls, invalid }
const lines = text.split(/\r?\n/)
for (const raw of lines) {
const line = raw.trim()
if (!line.startsWith(CONTRACT_ACTION_PREFIX)) continue
const body = line.slice(CONTRACT_ACTION_PREFIX.length).trim()
let parsed
try {
parsed = JSON.parse(body)
} catch (error) {
invalid.push({ line: raw, reason: `JSON 解析失败:${error.message}` })
continue
}
if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
invalid.push({ line: raw, reason: '契约正文必须是单个对象' })
continue
}
if (typeof parsed.action !== 'string' || !ACTION_SET.has(parsed.action)) {
invalid.push({ line: raw, reason: `未知动作:${String(parsed.action)}` })
continue
}
calls.push({ action: parsed.action, payload: parsed })
}
return { calls, invalid }
}
/** 给部门用的指令模板:只描述字段,不塞业务判断,避免模板把“已完成”写成结论。 */
const TEMPLATES = Object.freeze({
dispatchTask: {
taskId: 'task_…',
targetRoleId: 'gongbu',
idempotencyKey: '<同一任务同一意图固定不变>',
packet: { objective: '…', acceptance: ['…'], constraints: [], materialRefs: [] },
},
reportTaskResult: {
taskId: 'task_…',
attemptId: 'att_…',
reportVersion: 1,
summary: '做了什么、结果是什么',
checks: [{ name: '检查项', ok: true, detail: '证据' }],
artifactRefs: ['art_…'],
},
requestTaskInput: {
taskId: 'task_…',
attemptId: 'att_…',
reason: '缺什么、为什么必须由用户决定',
},
syncDecision: {
taskId: 'task_…',
decision: 'approve | reject | retry',
note: '可选说明',
},
})
/** 渲染成可直接贴进部门系统提示的一小段说明。 */
export function describeContract() {
const lines = [
`需要走程序的动作,请单独起一行,写作:${CONTRACT_ACTION_PREFIX}{…单行 JSON…}`,
'平台只认下面四个动作,且只认结构化字段——在正文里写“已完成”不会改变任务状态。',
]
for (const action of CONTRACT_ACTIONS) {
lines.push(`· ${action}:${JSON.stringify(TEMPLATES[action])}`)
}
return lines.join('\n')
}
/**
* 单条调用的轻量校验(字段存在性与形状)。业务级校验(归属、状态机、幂等)在 service 层,
* 这里只拦“明显没法处理”的调用,让错误尽早、可读地回到部门。
*/
export function validateContractCall(call) {
const errors = []
if (call === null || typeof call !== 'object') return ['调用必须是对象']
if (!ACTION_SET.has(call.action)) errors.push(`未知动作:${String(call.action)}`)
const payload = call.payload ?? {}
if (typeof payload.taskId !== 'string' || payload.taskId.trim() === '') errors.push('缺少 taskId')
switch (call.action) {
case 'dispatchTask':
if (typeof payload.idempotencyKey !== 'string' || payload.idempotencyKey.trim() === '') {
errors.push('dispatchTask 必须带 idempotencyKey(同一意图固定不变)')
}
break
case 'reportTaskResult':
if (typeof payload.attemptId !== 'string' || payload.attemptId.trim() === '') errors.push('reportTaskResult 必须带 attemptId')
if (typeof payload.summary !== 'string' || payload.summary.trim() === '') errors.push('reportTaskResult 必须带非空 summary')
break
case 'requestTaskInput':
if (typeof payload.reason !== 'string' || payload.reason.trim() === '') errors.push('requestTaskInput 必须带 reason')
break
case 'syncDecision':
if (typeof payload.decision !== 'string' || payload.decision.trim() === '') errors.push('syncDecision 必须带 decision')
break
default:
break
}
return errors
}

View File

@ -0,0 +1,207 @@
// DispatchService:把“账本里的一纸派发”变成“部门会话里真实收到的一条消息”。
//
// 方案 §7.5 的时序在这里落成四段,每一步失败都有明确去向:
// prepared → 选定会话与配置快照 → sending → prompt(requestId=attemptId)
// ├─ 成功 → accepted
// ├─ 宿主明确拒绝 → rejected(任务保留在排队态,可重试,不算业务失败)
// └─ 超时/断线 → unknown(先查证再决定,绝不自动当失败重发)
//
// 幂等的两层:dispatch 行按 (projectId, idempotencyKey) 去重;prompt 按 attemptId 当 requestId。
// 因此“用户连点两次”与“发送超时后重试”都不会让部门收到两条任务单。
import { buildDispatchText } from './session-adapter.mjs'
import { describeContract } from './contract.mjs'
export const DISPATCH_OUTCOMES = Object.freeze(['accepted', 'rejected', 'unknown'])
export class DispatchError extends Error {
constructor(code, message, details = undefined) {
super(message)
this.name = 'DispatchError'
this.code = code
if (details !== undefined) this.details = details
}
}
/**
* @param {object} options
* @param {object} options.store WorkbenchStore
* @param {object} options.service 工作台服务
* @param {object} options.sessions createSessionAdapter 的产物
* @param {(message: string) => void} [options.log]
* @param {string} [options.clientTimeZone] 派发提示里的时区,默认 Asia/Shanghai
*/
export function createDispatchService(options = {}) {
const { store, service, sessions, log = () => {}, clientTimeZone = 'Asia/Shanghai' } = options
if (store === undefined || typeof store.findDispatchByIdempotencyKey !== 'function') {
throw new DispatchError('NO_STORE', 'DispatchService 需要 WorkbenchStore')
}
if (service === undefined || typeof service.dispatchTask !== 'function') {
throw new DispatchError('NO_SERVICE', 'DispatchService 需要工作台服务')
}
if (sessions === undefined || typeof sessions.sendPrompt !== 'function') {
throw new DispatchError('NO_SESSIONS', 'DispatchService 需要会话适配层')
}
const contractGuide = describeContract()
/**
* 派发一个已入队任务。返回 { dispatch, attempt, outcome, duplicate }。
*
* 注意顺序:先写账(dispatch+attempt,同一次事务)再发消息。发送前崩溃只会留下
* prepared 行,对账器会把它当“未发出”处理;先发后写则会出现“部门已收到但账上没有”。
*/
async function dispatch(input = {}) {
const projectId = requireText(input.projectId, 'projectId')
const taskId = requireText(input.taskId, 'taskId')
const idempotencyKey = requireText(input.idempotencyKey, 'idempotencyKey')
// 1) 账务:去重 + 校验 + 落 prepared
const prepared = service.dispatchTask({
projectId,
taskId,
idempotencyKey,
sourceRoleId: input.sourceRoleId,
targetRoleId: input.targetRoleId,
targetSessionId: input.targetSessionId,
bindingGeneration: input.bindingGeneration,
packet: input.packet,
attemptId: input.attemptId,
})
const { dispatch, attempt, duplicate } = splitPrepared(prepared)
if (duplicate) {
// 重复点击:什么都不再做,返回既有结论(含 unknown 的历史要由对账处理)。
return { dispatch, attempt, outcome: outcomeOf(dispatch), duplicate: true }
}
if (dispatch.state === 'accepted') return { dispatch, attempt, outcome: 'accepted', duplicate: false }
// 2) 发送:先把 dispatch 推到 sending,再动宿主,避免“宿主已收但账上还是 prepared”。
store.updateDispatch(dispatch.id, { state: 'sending', sendingAt: new Date().toISOString() })
const task = store.getTask(taskId)
const packet = attempt?.contextPacketId === undefined || attempt?.contextPacketId === null
? null
: store.getContextPacket(attempt.contextPacketId)
const roleName = input.roleName ?? null
try {
// 3) 固定本轮配置:模型只在发送前覆写一次,运行中改配置不影响这一轮。
const snapshot = attempt?.effectiveConfigSnapshot ?? null
if (snapshot !== null && snapshot.provider && snapshot.model) {
await sessions.applyModel({
sessionId: attempt.sessionId,
provider: snapshot.provider,
model: snapshot.model,
reasoningEffort: snapshot.reasoningEffort ?? undefined,
})
}
const text = buildDispatchText({ task, packet, contractGuide, roleName })
const result = await sessions.sendPrompt({
sessionId: attempt.sessionId,
requestId: attempt.id,
text,
mode: input.mode ?? 'queue',
clientTimeZone,
})
if (result.accepted !== true) {
markRejected({ dispatch, attempt, reason: '宿主未确认接收' })
return { dispatch: store.getDispatch(dispatch.id), attempt, outcome: 'rejected', duplicate: false }
}
// 宿主确认接收 = 这一轮真的开始跑:任务与尝试同时进 running。
// 只改尝试不改任务,运行终态就无处落地(completion 会因任务仍在 queued 而被丢弃)。
service.startAttempt({
projectId: dispatch.projectId,
taskId: dispatch.taskId,
attemptId: attempt.id,
hostRunId: null,
})
markAccepted({ dispatch, attempt })
return { dispatch: store.getDispatch(dispatch.id), attempt: store.getAttempt(attempt.id), outcome: 'accepted', duplicate: false }
} catch (error) {
const code = error?.code ?? 'unknown'
if (code === 'conflict' || code === 'rejected') {
markRejected({ dispatch, attempt, reason: error?.message ?? String(error) })
return { dispatch: store.getDispatch(dispatch.id), attempt, outcome: 'rejected', duplicate: false }
}
// 超时、断线、context 丢失:一律 unknown —— 先查证,不重发。
markUnknown({ dispatch, attempt, reason: code })
log(`[sansheng-liubo] 派发 ${dispatch.id} 结果未知(${code}):${error?.message ?? error}`)
return { dispatch: store.getDispatch(dispatch.id), attempt, outcome: 'unknown', duplicate: false }
}
}
/**
* 对 unknown 的派发做查证:问宿主该会话是否有过这次 attempt 的请求。
* 查不到就保持 unknown(再次对账),查到有 → accepted;宿主明确从未收到 → rejected。
*/
async function verifyUnknown(dispatchId) {
const dispatch = store.getDispatch(dispatchId)
if (dispatch === undefined) throw new DispatchError('NOT_FOUND', `派发不存在:${dispatchId}`)
if (dispatch.state !== 'unknown') return { dispatch, outcome: outcomeOf(dispatch), changed: false }
const attempt = dispatch.attemptId === null ? null : store.getAttempt(dispatch.attemptId)
if (attempt === null) return { dispatch, outcome: 'unknown', changed: false }
const known = await sessions.inspectSession(attempt.sessionId)
if (known === null) return { dispatch, outcome: 'unknown', changed: false }
// 会话存在:宿主已经接受过这条消息(prompt 幂等键会挡住重复投递),按 accepted 收口。
store.updateDispatch(dispatch.id, { state: 'accepted', verifiedAt: new Date().toISOString() })
if (attempt.state === 'unknown') {
store.updateAttempt(attempt.id, { state: 'running', hostRunId: attempt.hostRunId ?? null })
}
return { dispatch: store.getDispatch(dispatch.id), outcome: 'accepted', changed: true }
}
function splitPrepared(result) {
// service.dispatchTask 返回 { dispatch, attempt, task, roleId, duplicate }(形状见 P1 Phase2)。
if (result === null || typeof result !== 'object' || result.dispatch === undefined) {
throw new DispatchError('BAD_PREPARED', '服务返回的派发结果形状不正确')
}
return { dispatch: result.dispatch, attempt: result.attempt ?? null, duplicate: result.duplicate === true }
}
function markAccepted({ dispatch, attempt }) {
const stamp = new Date().toISOString()
store.mutate(() => {
store.updateDispatch(dispatch.id, { state: 'accepted', acceptedAt: stamp })
if (attempt !== null && attempt.state === 'queued') {
store.updateAttempt(attempt.id, { state: 'running', startedAt: stamp })
}
})
}
function markRejected({ dispatch, attempt, reason }) {
const stamp = new Date().toISOString()
store.mutate(() => {
store.updateDispatch(dispatch.id, { state: 'rejected', rejectedAt: stamp, error: String(reason ?? '') })
if (attempt !== null && (attempt.state === 'queued' || attempt.state === 'unknown')) {
store.updateAttempt(attempt.id, { state: 'failed', endedAt: stamp, error: String(reason ?? '') })
}
})
}
function markUnknown({ dispatch, attempt, reason }) {
const stamp = new Date().toISOString()
store.mutate(() => {
store.updateDispatch(dispatch.id, { state: 'unknown', unknownAt: stamp, error: String(reason ?? '') })
if (attempt !== null && attempt.state === 'queued') {
store.updateAttempt(attempt.id, { state: 'unknown' })
}
})
}
return Object.freeze({ dispatch, verifyUnknown })
}
function outcomeOf(dispatch) {
if (dispatch.state === 'accepted') return 'accepted'
if (dispatch.state === 'rejected') return 'rejected'
if (dispatch.state === 'unknown') return 'unknown'
return 'prepared'
}
function requireText(value, field) {
if (typeof value !== 'string' || value.trim() === '') {
throw new DispatchError('INVALID_INPUT', `${field} 必须是非空字符串`, { field })
}
return value
}

190
workbench/host/index.mjs Normal file
View File

@ -0,0 +1,190 @@
// Host 侧装配:把账本、业务服务、会话层和 HTTP 路由接在一起。
//
// 这一层是唯一知道“账本文件在哪、损坏了怎么办”的地方:
// - 账本损坏(不是 JSON / schemaVersion 不符)时不崩溃:把坏文件改名留存,
// 从空账本启动,并把 warning 交给调用方(index.js / 诊断页)显示。
// 悄悄删掉或不说话都会让人以为“历史记录丢了”。
// - 宿主没有 webServer 时照常返回 service,只是路由不注册,registered=false;
// 若宿主稍后提供了 webServer,用 ctx.inject 补注册一次(不重复建 store)。
// - 宿主没有 sessionController 时,工作台仍能读写账本(投影可用),
// 但派发只落账不投递,UI 显示“尚未接通”,绝不假装成功。
//
// 与 workbench-host.mjs 的关系:那边是「账本 + 会话层 + 对账」的纯逻辑外壳,
// 这边负责文件、损坏隔离、HTTP 与生命周期,并把路由钩子接到外壳上。
import { existsSync, renameSync } from 'node:fs'
import { WorkbenchStore, SCHEMA_VERSION } from '../core/store.mjs'
import { corruptPathFor, ensureSidecarDir, resolveSidecarDir, resolveStorePath } from './paths.mjs'
import { registerWorkbenchRoutes } from './routes.mjs'
import { createWorkbenchHost as createWorkbenchShell } from './workbench-host.mjs'
export { createWorkbenchService } from './service.mjs'
export {
createWorkbenchHost as createWorkbenchShell,
CONTRACT_ACTIONS,
CONTRACT_ACTION_PREFIX,
describeContract,
parseContractLines,
WORKBENCH_HOST_VERSION,
} from './workbench-host.mjs'
export {
buildRouteTable,
listWorkbenchRoutes,
registerWorkbenchRoutes,
MAX_BODY_BYTES,
ROUTE_PREFIX,
} from './routes.mjs'
export {
SIDECAR_DIR_NAME,
corruptPathFor,
ensureSidecarDir,
quarantineFile,
readJsonSafe,
resolveSidecarDir,
resolveSidecarFile,
resolveStorePath,
writeFileAtomic,
writeJsonAtomic,
} from './paths.mjs'
/**
* 创建 Host 侧工作台。
*
* @param {object|null} ctx 宿主上下文(可为 null:服务仍可用,只是没有路由/会话)。
* @param {object} [options]
* @param {string} [options.file] 账本路径;默认 %DSH_HOME%/sansheng-liubu/workbench.json。
* @param {object} [options.env] 计算默认路径用的环境变量。
* @param {() => number} [options.clock] 注入时钟。
* @param {() => string} [options.random] 注入随机源(测试里固定 ID 用)。
* @param {boolean} [options.load=true] 是否从磁盘加载既有账本。
* @param {string} [options.presetId] 部门会话使用的 agentPreset,默认「上朝」。
* @param {boolean} [options.startReconciler=true] 是否启动周期对账。
* @param {number} [options.longPollMs] 事件长轮询上限(毫秒)。
* @param {number} [options.pollIntervalMs] 长轮询内部检查间隔(毫秒)。
* @returns {object} 见文件末尾 return 语句的字段说明。
*/
export function createWorkbenchHost(ctx, options = {}) {
const env = options.env ?? process.env
const clock = options.clock ?? Date.now
const file = options.file === undefined ? resolveStorePath(env) : options.file
const warnings = []
const store = new WorkbenchStore({
file,
clock,
env,
...(options.random === undefined ? {} : { random: options.random }),
})
if (options.load !== false && file !== null && file !== '') {
ensureSidecarDir(env)
if (existsSync(file)) {
try {
store.load()
} catch (error) {
// 损坏与版本不符都是“这个文件不能用”:改名留存后从空账本启动。
// 绝不覆盖原文件——里面可能是用户唯一一份历史。
const stamp = new Date(clock()).toISOString().replace(/[:.]/g, '-')
let quarantined = corruptPathFor(file, stamp)
try {
renameSync(file, quarantined)
} catch (renameError) {
// 改名失败(被占用/权限不足):不能继续往同一个文件写,退回纯内存账本。
quarantined = null
warnings.push(
`账本损坏且无法改名留存(${renameError?.code ?? 'UNKNOWN'}):${error?.message ?? ''};本次使用内存账本`,
)
}
if (quarantined !== null) {
warnings.push(
`账本损坏(${error?.code ?? 'ERROR'}:${error?.message ?? ''}),已改名留存为 ${quarantined},以空账本启动`,
)
}
}
}
}
// 外壳持有 store 与 service,并在宿主有能力时装配会话层/派发/对账。
const shell = createWorkbenchShell(ctx, {
store,
presetId: options.presetId,
startReconciler: options.startReconciler,
clock,
// 成果文件是否还在,由宿主文件系统回答(A23 失效显示);测试可注入替身。
fileExists: options.fileExists ?? existsSync,
})
const service = shell.service
const hooks = routeHooks(shell)
let routes = registerWorkbenchRoutes(ctx, service, { ...options, ...hooks })
let registered = routes.registered !== false
if (!registered) warnings.push(`工作台接口未注册:${routes.reason ?? '宿主未提供 webServer'}`)
// 宿主稍后才提供 webServer 时补注册一次;cordis 会在依赖出现时回调,
// 插件卸载时随作用域一起清理,不需要手工跟踪。
if (!registered && ctx !== null && typeof ctx?.inject === 'function') {
try {
ctx.inject(['webServer'], (scoped) => {
if (registered) return
const late = registerWorkbenchRoutes({ webServer: scoped?.webServer }, service, { ...options, ...hooks })
if (late.registered === false) return
routes = late
registered = true
})
} catch (error) {
warnings.push(`工作台接口补注册失败:${error?.message ?? error}`)
}
}
shell.start()
const dispose = () => {
try {
routes()
} finally {
shell.dispose()
}
}
return {
store,
service,
shell,
routes,
sessions: shell.sessions,
reconciler: shell.reconciler,
dispatchService: shell.dispatchService,
hasSessions: shell.hasSessions,
presetId: shell.presetId,
connectDepartment: shell.connectDepartment,
dispatchTask: shell.dispatchTask,
ingestAgentOutput: shell.ingestAgentOutput,
file: store.file,
sidecarDir: resolveSidecarDir(env),
get registered() {
return registered
},
warning: warnings.length === 0 ? null : warnings.join(';'),
warnings,
/** 卸载路由与后台服务(幂等);账本不删除,下次启动继续用。 */
dispose,
schemaVersion: SCHEMA_VERSION,
}
}
/**
* 路由钩子:只有宿主真有能力时才接管,否则让路由退回“只落账”的保守路径。
* 这样“没接通”永远不会被伪装成“已发送”。
*/
function routeHooks(shell) {
const hooks = {
connect: (input) => shell.connectDepartment(input),
ingest: (input) => shell.ingestAgentOutput(input),
}
if (shell.hasSessions === true && shell.dispatchService !== null) {
hooks.dispatch = (input) => shell.dispatchTask(input)
}
return hooks
}
export default createWorkbenchHost

118
workbench/host/paths.mjs Normal file
View File

@ -0,0 +1,118 @@
// 侧车(sidecar)路径与目录:业务账、导出物都放在宿主允许的位置,不进项目目录。
// 默认 %DSH_HOME%/sansheng-liubu/;没有 DSH_HOME 时退回 ~/.dsh。
// env 可注入:测试与多实例部署用同一套函数,不读第二份全局配置。
//
// 原子写在 store 里还有一份(先写 .tmp 再 rename);这里只给 HTTP/导出这类
// “宿主侧杂项文件”用同一套规则,避免两处对“半截文件”的处理不一致。
import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { homedir } from 'node:os'
import { dirname, join, resolve } from 'node:path'
export const SIDECAR_DIR_NAME = 'sansheng-liubu'
/** 侧车目录:DSH_HOME 优先,其次 ~/.dsh;相对路径按当前目录解析,不做猜测。 */
export function resolveSidecarDir(env = process.env) {
const raw = env && typeof env.DSH_HOME === 'string' ? env.DSH_HOME.trim() : ''
const home = raw === '' ? join(homedir(), '.dsh') : raw
return resolve(home, SIDECAR_DIR_NAME)
}
/**
* 账本文件路径。DSH_SANSHENG_WORKBENCH_FILE 可整体改写(用于独立测试实例);
* 它必须指向具体文件名,不能只是目录,否则会在目录名上写半截 JSON。
*/
export function resolveStorePath(env = process.env) {
const override = env && typeof env.DSH_SANSHENG_WORKBENCH_FILE === 'string'
? env.DSH_SANSHENG_WORKBENCH_FILE.trim()
: ''
if (override !== '') return resolve(override)
return join(resolveSidecarDir(env), 'workbench.json')
}
/** 派生路径:同一侧车目录下按用途分开,便于用户自己备份或清理而不碰账本。 */
export function resolveSidecarFile(name, env = process.env) {
if (typeof name !== 'string' || name.trim() === '') throw new Error('name 必须是非空字符串')
if (name.includes('/') || name.includes('\\')) throw new Error('name 只能是一级文件名,不能带目录分隔符')
return join(resolveSidecarDir(env), name)
}
/** 目录级入口:所有写入前都先建目录,缺目录不该表现为“保存失败”。 */
export function ensureSidecarDir(env = process.env) {
const dir = resolveSidecarDir(env)
mkdirSync(dir, { recursive: true })
return dir
}
/** 损坏文件的改名后缀:.corrupt-<时间戳>,保留现场且不覆盖下一次的结果。 */
export function corruptPathFor(file, stamp = Date.now()) {
return `${file}.corrupt-${stamp}`
}
/**
* 把可能损坏的文件挪到一边:返回新路径;文件不存在返回 null(不算错误)。
* 只改名不删除——损坏的账本里可能有用户唯一的业务记录,删掉就等于替用户做了决定。
*/
export function quarantineFile(file, stamp = Date.now()) {
if (!existsSync(file)) return null
let target = corruptPathFor(file, stamp)
let attempt = 1
while (existsSync(target)) {
target = `${corruptPathFor(file, stamp)}-${attempt}`
attempt += 1
}
renameSync(file, target)
return target
}
/**
* 原子写文本:同目录 .tmp → rename。
* Windows 上覆盖 rename 可能因杀软/索引占用失败,退化成“删旧再改名”;
* 最坏情况是目标短暂缺失,而不是留下半截内容。
*/
export function writeFileAtomic(file, text) {
const target = resolve(file)
mkdirSync(dirname(target), { recursive: true })
const tmp = `${target}.${process.pid}.${Date.now()}.tmp`
try {
writeFileSync(tmp, String(text), 'utf8')
try {
renameSync(tmp, target)
} catch {
rmSync(target, { force: true })
renameSync(tmp, target)
}
} finally {
rmSync(tmp, { force: true })
}
return target
}
/**
* 原子写 JSON:两空格缩进加尾换行,适合人读与 git diff。
* 不能序列化的值(BigInt、循环引用)直接抛错,不写一份“看起来写成了”的内容。
*/
export function writeJsonAtomic(file, value) {
const text = `${JSON.stringify(value, null, 2)}\n`
return writeFileAtomic(file, text)
}
/** 读 JSON;文件不存在或解析失败都返回 fallback,让调用方决定是否报错。 */
export function readJsonSafe(file, fallback = null) {
try {
if (!existsSync(file)) return fallback
return JSON.parse(readFileSync(file, 'utf8'))
} catch {
return fallback
}
}
/** 文件是否可读且非空;用于“成果文件已被删除”这类检查,不做内容解析。 */
export function fileLooksUsable(file) {
try {
const info = statSync(file)
return info.isFile() && info.size > 0
} catch {
return false
}
}

View File

@ -0,0 +1,181 @@
// Reconciler:把“部门会话里真实发生了什么”折算成 attempt 的终态。
//
// 方案 §7.4 的硬约束:宿主运行结束 ≠ 业务完成。所以这里只做“运行终态”的判定,
// 业务完成由 tasks.decide 用(结构化报告 + 运行终态 + 成果引用)三票共同决定。
//
// 数据来源只有两类可信信号:
// 1. 宿主 follow 事件里的 turn/结束信号(附加 latest.assistant-stream 之外的持久帧);
// 2. 主动查询 controller.list() 里该会话的 running 位。
// 绝不从聊天文本推断“做完了”。
import { classifyHostError } from './session-adapter.mjs'
export const RECONCILER_DEFAULT_INTERVAL_MS = 30000
export const RECONCILER_MIN_INTERVAL_MS = 5000
/**
* @param {object} options
* @param {object} options.store WorkbenchStore
* @param {object} options.service 工作台服务(reportRunTerminal / markDispatch / syncDecision…)
* @param {object} options.sessions createSessionAdapter 的产物
* @param {() => number} [options.clock]
* @param {(message: string) => void} [options.log]
*/
export function createReconciler(options = {}) {
const { store, service, sessions, clock = Date.now, log = () => {} } = options
if (store === undefined || typeof store.listOpenAttempts !== 'function') {
throw new Error('createReconciler 需要 WorkbenchStore')
}
if (service === undefined || typeof service.reportRunTerminal !== 'function') {
throw new Error('createReconciler 需要工作台服务')
}
let timer = null
let running = false
/**
* 单次对账。返回结构化结果供日志与测试断言,不吞异常也不抛出:
* 一个会话查不到不该阻断其它会话的对账。
*/
async function reconcileOnce() {
if (running) return { skipped: true, reason: 'busy', checked: 0, changed: [] }
running = true
const outcome = { skipped: false, checked: 0, changed: [], errors: [] }
try {
const open = store.listOpenAttempts()
for (const attempt of open) {
outcome.checked += 1
try {
const change = await reconcileAttempt(attempt)
if (change !== null) outcome.changed.push(change)
} catch (error) {
outcome.errors.push({ attemptId: attempt.id, message: messageOf(error) })
log(`[sansheng-liubo] 对账 ${attempt.id} 失败:${messageOf(error)}`)
}
}
} finally {
running = false
}
return outcome
}
/**
* 单个 attempt 的对账:
* - 宿主问不到(null)→ 什么也不改,等下一轮(宁可晚,不可猜);
* - 还在跑 → 只把 queued 推进到 running,不改结论;
* - 已停 → 依 state 决定:cancel_requested 转 cancelled,其余转 succeeded(再交 completion 三票判定)。
*/
async function reconcileAttempt(attempt) {
const projectId = attempt.projectId
let task = store.getTask(attempt.taskId)
if (task === undefined) return null
const runningFlag = await sessions.isRunning(attempt.sessionId)
if (runningFlag === null) return null
const now = new Date(clock()).toISOString()
if (runningFlag) {
if (attempt.state === 'queued') {
store.updateAttempt(attempt.id, { state: 'running', hostRunId: attempt.hostRunId ?? null, heartbeatAt: now })
// 任务要跟着进 running:只有任务处于 running 时,运行终态才能折算成
// completed / needs_attention / cancelled,否则终态会被状态机丢弃。
if (task.status === 'queued') {
try {
// service.startAttempt 会同时把任务推进到 running,并把最新任务读回来。
const started = service.startAttempt({
projectId,
taskId: task.id,
attemptId: attempt.id,
hostRunId: attempt.hostRunId ?? null,
})
task = started.task ?? task
} catch (error) {
log(`[sansheng-liubo] 任务 ${task.id} 推进 running 被拒:${messageOf(error)}`)
}
}
return { attemptId: attempt.id, from: 'queued', to: 'running' }
}
return null
}
// 宿主说会话不跑了:这是“运行终态 = 正常结束”,不是业务完成。
// 用户点过停止(cancel_requested)的尝试记为 cancelled,不当成成功运行。
// 用户点过停止:可能是适配器已经写过 cancel_requested,也可能只是刚发出停止请求
// (cancel() 是同步 accepted,不等于已停)。两种都按取消收口,否则"取消与成功竞争"里
// 被取消的这一次会被记成成功运行,任务显示已完成。
const cancelRequested = attempt.state === 'cancel_requested' || sessions.wasCancelRequested(attempt.sessionId)
if (attempt.state === 'running' || attempt.state === 'queued' || cancelRequested) {
const nextState = cancelRequested ? 'cancelled' : 'succeeded'
// running 不能直接到 cancelled:用户请求过停止的,先记 cancel_requested 再收口,
// 状态机与审计都保留"请求过停止"这一步。
if (nextState === 'cancelled' && attempt.state !== 'cancel_requested') {
store.updateAttempt(attempt.id, { state: 'cancel_requested', cancelRequestedAt: now })
}
store.updateAttempt(attempt.id, { state: nextState, endedAt: now })
applyTerminal({ attempt, task, terminal: nextState === 'cancelled' ? 'cancelled' : 'succeeded' })
return { attemptId: attempt.id, from: attempt.state, to: nextState }
}
return null
}
function applyTerminal({ attempt, task, terminal }) {
try {
// 任务侧:run_terminal 只是“一票”。没报告时只会变 needs_attention,不会变 completed。
service.reportRunTerminal({
projectId: attempt.projectId,
taskId: attempt.taskId,
attemptId: attempt.id,
runTerminal: terminal,
})
} catch (error) {
// 状态机拒绝重复/乱序终态是正常情况:记一行,不抛出。
log(`[sansheng-liubo] 任务 ${task.id} 记录运行终态被拒:${messageOf(error)}`)
}
}
/** 一个会话里出现了新的 assistant 完成回合:作为“可能已结束”的信号触发一次定向对账。 */
async function onSessionFrame({ sessionId }) {
const open = store.listOpenAttempts().filter((row) => row.sessionId === sessionId)
if (open.length === 0) return { checked: 0 }
for (const attempt of open) {
try {
await reconcileAttempt(attempt)
} catch (error) {
log(`[sansheng-liubo] 帧触发对账失败:${messageOf(error)}`)
}
}
return { checked: open.length }
}
function start({ intervalMs = RECONCILER_DEFAULT_INTERVAL_MS } = {}) {
if (timer !== null) return
const period = Math.max(RECONCILER_MIN_INTERVAL_MS, Number(intervalMs) || RECONCILER_DEFAULT_INTERVAL_MS)
timer = setInterval(() => {
reconcileOnce().catch((error) => log(`[sansheng-liubo] 周期对账异常:${messageOf(error)}`))
}, period)
// 宿主退出时不要让定时器把进程吊住。
if (typeof timer.unref === 'function') timer.unref()
}
function stop() {
if (timer !== null) {
clearInterval(timer)
timer = null
}
}
return Object.freeze({
reconcileOnce,
reconcileAttempt,
onSessionFrame,
start,
stop,
get scheduled() {
return timer !== null
},
})
}
function messageOf(error) {
return error instanceof Error ? error.message : String(error)
}
export { classifyHostError }

430
workbench/host/routes.mjs Normal file
View File

@ -0,0 +1,430 @@
// 工作台 HTTP 路由:把 service 暴露给宿主 Web 服务。
//
// 设计取舍:
// - 全部 exact 路由,不做前缀匹配:/sansheng/workbench/xxx 未登记的一律 404,
// 不会因为前缀相同就把未知路径交给某个 handler 兜底。
// - 非 GET 只接受 POST(其余方法 405),未实现的路径 404,参数错误 400,体过大 413。
// - 统一包装 { ok:true, value } / { ok:false, error:{ code, message, details? } },
// Content-Type 带 charset、Cache-Control: no-store、Content-Length 手写。
// - 事件通道用长轮询而不是 SSE:宿主侧只是一个普通 HTTP handler,
// 浏览器刷新/断线重连后靠 since 补齐天然幂等,不需要管连接生命周期;
// 最长挂 25 秒,远低于常见代理/浏览器的空闲超时,也不占住宿主的事件循环。
// - 任何 ctx.webServer 的缺失都在 registerWorkbenchRoutes 里探测并降级:
// 返回一个 no-op 的 dispose,route 列表照常给出,便于诊断而不至于让插件加载失败。
import { ServiceError } from './service.mjs'
export const ROUTE_PREFIX = '/sansheng/workbench'
/** 请求体字节上限:契约里最大的是交接材料(摘录 + 引用),256 KB 足够且能挡住误传大文件。 */
export const MAX_BODY_BYTES = 256 * 1024
/** 长轮询最长挂起时间(毫秒)。浏览器重连后靠 since 补齐,所以不需要真正的无限等待。 */
export const DEFAULT_LONG_POLL_MS = 25_000
/** 轮询间隔:太密会白烧 CPU,太疏会让“有新事件立刻返回”的承诺打折。 */
const POLL_INTERVAL_MS = 1_000
/** 业务错误码 → HTTP 状态码。未列出的统一 400。 */
const STATUS_OF_CODE = Object.freeze({
INVALID_INPUT: 400,
INVALID_ROLE: 400,
INVALID_STATE: 400,
DISPATCH_INVALID: 400,
ATTEMPT_MISMATCH: 400,
REPORT_INVALID: 400,
NOT_FOUND: 404,
CROSS_PROJECT: 409,
CONFIG_CONFLICT: 409,
SESSION_CONFLICT: 409,
DUPLICATE_PROJECT: 409,
INTERNAL: 500,
})
function statusOf(error) {
if (error instanceof ServiceError) return STATUS_OF_CODE[error.code] ?? 400
if (error !== null && typeof error === 'object' && typeof error.code === 'string') {
return STATUS_OF_CODE[error.code] ?? 400
}
return 500
}
/** 响应写出:统一头 + 手写 Content-Length,HEAD 不写体。 */
function sendJson(res, status, payload, extraHeaders = undefined) {
const body = JSON.stringify(payload)
const headers = {
'Content-Type': 'application/json; charset=utf-8',
'Cache-Control': 'no-store',
'Content-Length': Buffer.byteLength(body),
...(extraHeaders ?? {}),
}
res.writeHead(status, headers)
res.end(body)
return body
}
function sendOk(res, value, extraHeaders) {
return sendJson(res, 200, { ok: true, value }, extraHeaders)
}
function sendError(res, error) {
const status = statusOf(error)
const code = typeof error?.code === 'string' ? error.code : 'INTERNAL'
const message = status === 500 && !(error instanceof ServiceError)
? '内部错误'
: (typeof error?.message === 'string' ? error.message : '请求失败')
const payload = { ok: false, error: { code, message } }
if (error?.details !== undefined) payload.error.details = error.details
return sendJson(res, status, payload)
}
/**
* 读请求体:按字节累计,超限立即拒绝(不再继续读,避免被巨大体拖住)。
* 空体视为 {},让无参 POST 也能走同一个入口。
*/
async function readJsonBody(req, limit = MAX_BODY_BYTES) {
const chunks = []
let total = 0
for await (const chunk of req) {
const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
total += buffer.length
if (total > limit) {
const error = new ServiceError('INVALID_INPUT', `请求体超过 ${limit} 字节上限`, { limit })
error.httpStatus = 413
throw error
}
chunks.push(buffer)
}
const text = Buffer.concat(chunks).toString('utf8').trim()
if (text === '') return {}
try {
const parsed = JSON.parse(text)
if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
throw new Error('not an object')
}
return parsed
} catch {
const error = new ServiceError('INVALID_INPUT', '请求体必须是 JSON 对象')
error.httpStatus = 400
throw error
}
}
async function readBody(req, limit) {
try {
return await readJsonBody(req, limit)
} catch (error) {
// 体超限与 JSON 非法是 HTTP 层语义,借 httpStatus 覆盖默认映射。
if (typeof error.httpStatus === 'number') {
const wrapped = new ServiceError(error.code, error.message, error.details)
wrapped.httpStatus = error.httpStatus
throw wrapped
}
throw error
}
}
/** 从 URL 里取查询参数(不依赖宿主框架,纯 node URL)。 */
function queryOf(url) {
const index = typeof url === 'string' ? url.indexOf('?') : -1
if (index < 0) return new URLSearchParams('')
const rest = url.slice(index + 1)
const hash = rest.indexOf('#')
return new URLSearchParams(hash < 0 ? rest : rest.slice(0, hash))
}
function pathOf(url) {
if (typeof url !== 'string') return ''
const cut = url.search(/[?#]/)
return cut < 0 ? url : url.slice(0, cut)
}
/**
* 长轮询:最多挂 maxWaitMs,期间每 pollIntervalMs 检查一次是否有新事件;
* 一旦有就立刻返回(不等到窗口结束),没有就等到窗口结束返回空列表 + 当前 seq。
* 客户端断开(req 触发 close)时立即结束,不留悬挂计时器。
*/
async function waitForEvents(service, projectId, since, options) {
const maxWaitMs = options.longPollMs ?? DEFAULT_LONG_POLL_MS
const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS
const immediate = service.listEvents(projectId, since, options.eventLimit === undefined ? {} : { limit: options.eventLimit })
if (immediate.events.length > 0 || immediate.reset) return immediate
const deadline = Date.now() + maxWaitMs
while (Date.now() < deadline) {
const remain = deadline - Date.now()
await sleep(Math.max(1, Math.min(pollIntervalMs, remain)))
const fresh = service.listEvents(projectId, since, options.eventLimit === undefined ? {} : { limit: options.eventLimit })
if (fresh.events.length > 0 || fresh.reset) return fresh
}
return service.listEvents(projectId, since, options.eventLimit === undefined ? {} : { limit: options.eventLimit })
}
function sleep(ms) {
return new Promise((resolve) => {
const timer = setTimeout(resolve, ms)
// 计时器不应阻止进程退出(测试里尤其明显)。
if (typeof timer.unref === 'function') timer.unref()
})
}
/** 统一 handler 包装:方法校验、异常兜底、响应头注入。 */
function wrap(handler, { methods = ['POST'], allowBody = true, bodyLimit = MAX_BODY_BYTES } = {}) {
return async (req, res) => {
try {
const method = String(req.method ?? 'GET').toUpperCase()
if (!methods.includes(method)) {
res.setHeader('Allow', methods.join(', '))
sendJson(res, 405, { ok: false, error: { code: 'METHOD_NOT_ALLOWED', message: `仅支持 ${methods.join(', ')}` } })
return
}
const body = allowBody && method === 'POST' ? await readBody(req, bodyLimit) : {}
const url = req.url ?? ''
const value = await handler({ req, res, body, method, query: queryOf(url), path: pathOf(url) })
// handler 自己已经写过响应(例如长轮询中途断开)时不再写第二遍。
if (res.writableEnded === true) return
const headers = value !== null && typeof value === 'object' && value.__headers !== undefined ? value.__headers : undefined
const payload = headers === undefined ? value : value.payload
sendOk(res, payload, headers)
} catch (error) {
if (res.writableEnded === true) return
const status = typeof error?.httpStatus === 'number' ? error.httpStatus : statusOf(error)
const code = typeof error?.code === 'string' ? error.code : 'INTERNAL'
const payload = { ok: false, error: { code, message: error?.message ?? '请求失败' } }
if (error?.details !== undefined) payload.error.details = error.details
sendJson(res, status, payload)
}
}
}
/**
* 路由表:path → handler 定义。集中声明,便于诊断页一次性列出全部端点。
* 每个 handler 都从 body/query 取参数并原样交给 service,不在路由层做业务判断。
*/
export function buildRouteTable(service, options = {}) {
const select = options.projectIdFrom === undefined ? (body) => body.projectId : options.projectIdFrom
return Object.freeze({
[`${ROUTE_PREFIX}/bootstrap`]: {
method: 'GET',
handler: async ({ query }) => service.bootstrap(query.get('projectId') ?? undefined),
},
[`${ROUTE_PREFIX}/project`]: {
method: 'POST',
handler: async ({ body }) => service.registerProject({
hostWorkspaceId: body.hostWorkspaceId,
displayNameCache: body.displayNameCache,
canonicalRoot: body.canonicalRoot,
}),
},
[`${ROUTE_PREFIX}/bind`]: {
method: 'POST',
handler: async ({ body }) => service.bindDepartmentSession({
projectId: select(body),
roleId: body.roleId,
sessionId: body.sessionId,
allowReplace: body.allowReplace,
creationRequestId: body.creationRequestId,
}),
},
[`${ROUTE_PREFIX}/config`]: {
method: 'POST',
handler: async ({ body }) => service.saveDepartmentConfig({
projectId: select(body),
roleId: body.roleId,
provider: body.provider,
model: body.model,
reasoningEffort: body.reasoningEffort,
expectedRevision: body.expectedRevision,
}),
},
[`${ROUTE_PREFIX}/task`]: {
method: 'POST',
handler: async ({ body }) => service.createTask({
projectId: select(body),
title: body.title,
objective: body.objective,
acceptance: body.acceptance,
constraints: body.constraints,
scope: body.scope,
ownerRoleId: body.ownerRoleId,
sourceRoleId: body.sourceRoleId,
originMessageRef: body.originMessageRef,
returnTarget: body.returnTarget,
status: body.status,
}),
},
[`${ROUTE_PREFIX}/task/cancel`]: {
method: 'POST',
handler: async ({ body }) => service.cancelTask({
projectId: select(body),
taskId: body.taskId,
reason: body.reason,
}),
},
[`${ROUTE_PREFIX}/connect`]: {
method: 'POST',
handler: async ({ body }) => {
if (typeof options.connect !== 'function') {
throw new ServiceError('INVALID_STATE', '宿主未提供会话能力,暂时无法接通部门')
}
return options.connect({
projectId: select(body),
roleId: body.roleId,
sessionId: body.sessionId,
agentPreset: body.agentPreset,
})
},
},
[`${ROUTE_PREFIX}/dispatch`]: {
method: 'POST',
handler: async ({ body }) => {
const ledger = {
projectId: select(body),
taskId: body.taskId,
idempotencyKey: body.idempotencyKey,
sourceRoleId: body.sourceRoleId,
targetRoleId: body.targetRoleId,
targetSessionId: body.targetSessionId,
bindingGeneration: body.bindingGeneration,
packet: body.packet,
}
// 有 Host 会话能力时走 DispatchService:它会真的把任务单送进部门会话,
// 并把 prepared → sending → accepted/rejected/unknown 走完。
// 没有会话层时只落账(prepared),UI 据此显示“尚未接通”,绝不假装已发送。
if (typeof options.dispatch === 'function') {
return options.dispatch({
...ledger,
sourceSessionId: body.sourceSessionId,
mode: body.mode,
roleName: body.roleName,
})
}
return service.dispatchTask(ledger)
},
},
[`${ROUTE_PREFIX}/ingest`]: {
method: 'POST',
handler: async ({ body }) => {
if (typeof options.ingest !== 'function') {
throw new ServiceError('INVALID_STATE', '宿主未提供契约解析能力')
}
return options.ingest({
projectId: select(body),
roleId: body.roleId,
text: body.text,
})
},
},
[`${ROUTE_PREFIX}/result`]: {
method: 'POST',
handler: async ({ body }) => service.reportTaskResult({
projectId: select(body),
taskId: body.taskId,
attemptId: body.attemptId,
report: body.report,
runTerminal: body.runTerminal,
artifactRefs: body.artifactRefs,
checks: body.checks,
remainingItems: body.remainingItems,
blockedReason: body.blockedReason,
sourceMessageRef: body.sourceMessageRef,
reportVersion: body.reportVersion,
}),
},
[`${ROUTE_PREFIX}/artifact/revision`]: {
method: 'POST',
handler: async ({ body }) => service.requestArtifactRevision({
projectId: select(body),
artifactId: body.artifactId,
instruction: body.instruction,
ownerRoleId: body.ownerRoleId,
sourceRoleId: body.sourceRoleId,
title: body.title,
acceptance: body.acceptance,
constraints: body.constraints,
status: body.status,
originMessageRef: body.originMessageRef,
returnTarget: body.returnTarget,
}),
},
[`${ROUTE_PREFIX}/events`]: {
method: 'GET',
handler: async ({ query, req, res }) => {
const projectId = query.get('projectId') ?? undefined
const since = Number(query.get('since') ?? 0)
if (query.get('since') !== null && !Number.isFinite(since)) {
throw new ServiceError('INVALID_INPUT', 'since 必须是数字', { field: 'since' })
}
const immediateOnly = query.get('wait') === '0'
if (immediateOnly || (options.longPollMs ?? DEFAULT_LONG_POLL_MS) <= 0) {
return service.listEvents(projectId, since, { limit: options.eventLimit })
}
return waitForEvents(service, projectId, since, {
...options,
// 客户端断开时不再等满窗口:把当前结果写回去(或让外层发现已结束)。
onAbort: () => {
if (res.writableEnded !== true && res.destroyed !== true) {
sendOk(res, service.listEvents(projectId, since, { limit: options.eventLimit }), { Connection: 'close' })
}
},
})
},
},
})
}
/**
* 注册路由。宿主没有 webServer(或没有 register)时返回 no-op dispose,
* 并在返回值上标 registered:false,调用方可据此提示“宿主不支持工作台接口”。
*
* @returns {() => void} dispose:卸载全部已注册路由;重复调用无副作用。
*/
export function registerWorkbenchRoutes(ctx, service, options = {}) {
const disposes = []
const server = ctx?.webServer
if (server === undefined || server === null || typeof server.register !== 'function') {
const noop = () => {}
noop.registered = false
noop.reason = '宿主未提供 webServer.register'
return noop
}
const table = buildRouteTable(service, options)
const bodyLimit = options.maxBodyBytes ?? MAX_BODY_BYTES
try {
for (const [path, def] of Object.entries(table)) {
const methods = def.method === 'GET' ? ['GET'] : ['POST']
const handler = wrap(def.handler, { methods, allowBody: def.method === 'POST', bodyLimit })
const dispose = server.register({ kind: 'exact', path, handler })
if (typeof dispose === 'function') disposes.push(dispose)
}
} catch (error) {
// 部分注册失败:先把已注册的回滚,避免留下半套路由(前端会看到一多半 404)。
for (const dispose of disposes.reverse()) {
try {
dispose()
} catch {
// 卸载失败不影响主流程:宿主要么已卸载,要么进程即将重启。
}
}
throw error
}
let disposed = false
const dispose = () => {
if (disposed) return
disposed = true
for (const fn of disposes.reverse()) {
try {
fn()
} catch {
// 同上:dispose 必须幂等且不抛。
}
}
}
dispose.registered = true
dispose.paths = Object.keys(table)
return dispose
}
/** 供诊断页使用:列出全部端点与其方法。 */
export function listWorkbenchRoutes() {
return Object.entries(buildRouteTable({ bootstrap: () => null }, {})).map(([path, def]) => ({ path, method: def.method }))
}

1421
workbench/host/service.mjs Normal file

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,282 @@
// 会话适配层:把 Host 的 SessionController 收敛成“派发只需要几个动作”。
//
// 依据 docs/v0.1-宿主能力记录.md(P0 实测的类型层事实):
// - create({workspaceId}) 幂等:同一 workspace 已绑定时返回同一个会话,不会造出第二个;
// - create 里没有 creationRequestId,也没有 cwd+workspaceId 同时给的用法(会 bad-request);
// - prompt 的 requestId 才是真幂等键(跨重启有效),所以 attemptId 直接当 requestId 用;
// - cancel() 只是“请求取消”,accepted:true ≠ 已取消,终态必须靠 follow/对账得到。
//
// 这一层只做三件事:拿到会话、送一条消息、听它的事件。其余判定留在核心层。
export class SessionAdapterError extends Error {
constructor(code, message, details = undefined) {
super(message)
this.name = 'SessionAdapterError'
this.code = code
if (details !== undefined) this.details = details
}
}
/** 把宿主抛出的杂异常收敛成“可重试 / 必失败”两类,reconciler 依赖这个区分。 */
export function classifyHostError(error) {
const code = error && typeof error.code === 'string' ? error.code : ''
const message = error instanceof Error ? error.message : String(error)
if (code === 'session/conflict' || /session\/conflict/.test(message)) return 'conflict'
if (code === 'session/model-unavailable' || /model-unavailable/.test(message)) return 'model_unavailable'
if (code === 'session/agent-busy' || /agent-busy/.test(message)) return 'busy'
if (code === 'session/writer-held' || /writer-held/.test(message)) return 'transient'
if (/timeout|ETIMEDOUT|ECONNRESET|ECONNREFUSED|socket hang up/i.test(message)) return 'transient'
return 'unknown'
}
/**
* @param {object} options
* @param {object} options.sessionController Host 的 ctx.sessionController(或同形状替身)。
* @param {(event: object) => void} [options.onEvent] 订阅回调:任意会话事件(对账与 UI 都用它)。
* @param {(message: string) => void} [options.log] 诊断日志出口;默认吞掉。
*/
export function createSessionAdapter(options = {}) {
const { sessionController, onEvent, log = () => {} } = options
if (sessionController === undefined || sessionController === null || typeof sessionController.prompt !== 'function') {
throw new SessionAdapterError('NO_SESSION_CONTROLLER', '会话适配层需要 Host 的 sessionController')
}
const controller = sessionController
/** 正在跑 follow 的会话:sessionId → { controller: AbortController, done: Promise<void> } */
const followers = new Map()
// 被用户明确要求停止过的会话(只影响对账收口,不影响派发)。
const cancelRequested = new Set()
let disposed = false
function ensureAlive() {
if (disposed) throw new SessionAdapterError('DISPOSED', '会话适配层已释放')
}
/**
* 拿到(或复用)一个会话。上层传入的 sessionId 是 store 里登记的绑定;
* 为空时用 workspaceId 建一个新会话,并把 host 返回的 id 交回给上层登记。
*/
async function ensureSession({ workspaceId, sessionId, agentPreset } = {}) {
ensureAlive()
if (typeof sessionId === 'string' && sessionId.trim() !== '') {
// 已有绑定:不重建,只确认宿主能看到它(看不到就交给上层判定绑定失效)。
const known = await inspectSession(sessionId)
return { sessionId, created: false, known }
}
if (typeof workspaceId !== 'string' || workspaceId.trim() === '') {
throw new SessionAdapterError('NO_TARGET', '既没有绑定会话也没有 workspaceId,无法接通部门')
}
const request = { workspaceId }
if (typeof agentPreset === 'string' && agentPreset.trim() !== '') request.agentPreset = agentPreset
try {
const value = await controller.create(request)
if (value === null || typeof value !== 'object' || typeof value.sessionId !== 'string') {
throw new SessionAdapterError('BAD_CREATE_RESULT', '宿主 create 未返回 sessionId')
}
return { sessionId: value.sessionId, created: true, agentPreset: value.agentPreset ?? null }
} catch (error) {
throw new SessionAdapterError(classifyHostError(error), `接通部门会话失败:${messageOf(error)}`, { cause: error })
}
}
async function inspectSession(sessionId) {
if (typeof controller.inspect !== 'function') return null
try {
return await controller.inspect(sessionId)
} catch {
return null
}
}
/**
* 送一条消息。requestId 由调用方(attemptId)给,重试同一条 attempt 不会重复投递;
* 超时/未知一律抛 transient,由 reconciler 决定是查证还是标 unknown。
*/
async function sendPrompt({ sessionId, requestId, text, mode = 'queue', signal, clientTimeZone } = {}) {
ensureAlive()
if (typeof sessionId !== 'string' || sessionId.trim() === '') {
throw new SessionAdapterError('NO_SESSION', '送消息前必须有 sessionId')
}
if (typeof text !== 'string' || text.trim() === '') {
throw new SessionAdapterError('EMPTY_PROMPT', '送消息内容为空')
}
if (typeof requestId !== 'string' || requestId.trim() === '') {
throw new SessionAdapterError('NO_REQUEST_ID', '送消息必须带 requestId(幂等键)')
}
const request = {
requestId,
sessionId,
mode: mode === 'steer' ? 'steer' : 'queue',
content: [{ type: 'text', text }],
}
if (typeof clientTimeZone === 'string' && clientTimeZone !== '') request.clientTimeZone = clientTimeZone
try {
const value = await controller.prompt(request, signal)
return { accepted: value?.accepted === true }
} catch (error) {
throw new SessionAdapterError(classifyHostError(error), `投递失败:${messageOf(error)}`, { cause: error })
}
}
/**
* 取消只是“请求取消”;调用方必须等 follow 上的终态或对账结果,不能直接当已停。
* 这里额外记下"这个会话被用户要求停过",对账时用它把停跑结果收口成 cancelled,
* 避免"取消与成功竞争"里被取消的那一次被记成成功运行。
*/
function requestCancel(sessionId) {
ensureAlive()
try {
const value = controller.cancel({ sessionId })
if (value?.accepted === true) cancelRequested.add(sessionId)
return { accepted: value?.accepted === true }
} catch (error) {
throw new SessionAdapterError(classifyHostError(error), `取消失败:${messageOf(error)}`, { cause: error })
}
}
/** 该会话是否被明确要求过停止(跨本次进程有效;宿主重启后由 attempt 状态兜底)。 */
function wasCancelRequested(sessionId) {
return cancelRequested.has(sessionId)
}
/** 新一轮派发成功投递后可清掉停止标记:同一会话的下一次运行不该继承上一次的取消意图。 */
function clearCancelRequest(sessionId) {
return cancelRequested.delete(sessionId)
}
/** 每次派发都显式覆写模型:宿主 selectModel 会顺手改全局默认,所以用快照固定本轮。 */
async function applyModel({ sessionId, provider, model, reasoningEffort } = {}) {
ensureAlive()
if (typeof controller.selectModel !== 'function') return { selected: false, reason: 'controller 无 selectModel' }
if (typeof provider !== 'string' || provider === '' || typeof model !== 'string' || model === '') {
return { selected: false, reason: '未配置模型' }
}
const request = { sessionId, provider, model }
if (typeof reasoningEffort === 'string' && reasoningEffort !== '') request.reasoningEffort = reasoningEffort
try {
const value = await controller.selectModel(request)
return { selected: true, selection: value?.selected ?? null }
} catch (error) {
// 模型不可用是“本次派发不能开工”,不是“任务失败”,交由上层标 unavailable 并保留任务。
throw new SessionAdapterError(classifyHostError(error), `模型切换失败:${messageOf(error)}`, { cause: error })
}
}
async function getSessionSummary(sessionId) {
if (typeof controller.list !== 'function') return null
try {
const value = await controller.list({}, new AbortController().signal)
const items = Array.isArray(value?.items) ? value.items : []
return items.find((row) => row.sessionId === sessionId) ?? null
} catch {
return null
}
}
/** 宿主是否还在跑这个会话:null 表示问不到(不当成“已结束”)。 */
async function isRunning(sessionId) {
const summary = await getSessionSummary(sessionId)
if (summary === null) return null
return summary.running === true
}
/**
* 订阅会话事件。alreadyAttached 时不重复起流:同一个会话只留一条 follow,
* 避免双窗口/重启后重建出两条流导致事件重复。
*/
function follow(sessionId, { onFrame } = {}) {
ensureAlive()
if (followers.has(sessionId)) return followers.get(sessionId).handle
if (typeof controller.follow !== 'function') throw new SessionAdapterError('NO_FOLLOW', 'controller 无 follow')
const abort = new AbortController()
const handle = { sessionId, stop: () => abort.abort() }
const done = (async () => {
try {
const address = { sessionId }
const stream = controller.follow({ address }, abort.signal)
for await (const frame of stream) {
if (disposed || abort.signal.aborted) break
if (frame?.type === 'assistant-stream') continue
try {
if (typeof onFrame === 'function') onFrame(frame)
if (typeof onEvent === 'function') onEvent({ sessionId, frame })
} catch (error) {
log(`[sansheng-liubu] 处理会话帧失败:${messageOf(error)}`)
}
}
} catch (error) {
if (!abort.signal.aborted) log(`[sansheng-liubu] 会话流中断:${messageOf(error)}`)
} finally {
followers.delete(sessionId)
}
})()
followers.set(sessionId, { handle, done })
return handle
}
function unfollow(sessionId) {
const entry = followers.get(sessionId)
if (entry === undefined) return false
entry.handle.stop()
return true
}
function dispose() {
disposed = true
for (const entry of followers.values()) entry.handle.stop()
followers.clear()
}
return Object.freeze({
ensureSession,
inspectSession,
sendPrompt,
requestCancel,
wasCancelRequested,
clearCancelRequest,
applyModel,
getSessionSummary,
isRunning,
follow,
unfollow,
dispose,
get following() {
return [...followers.keys()]
},
})
}
function messageOf(error) {
return error instanceof Error ? error.message : String(error)
}
/**
* 把一次派发写成部门能直接执行的提示词。只放事实(任务、验收、材料、回传方式),
* 不写“请确认已完成”这类引导语——完成判定只认结构化报告。
*/
export function buildDispatchText({ task, packet, contractGuide, roleName } = {}) {
const lines = []
const name = typeof roleName === 'string' && roleName !== '' ? roleName : '你'
lines.push(`【任务单 ${task?.id ?? ''}】${task?.title ?? ''}`)
if (typeof task?.objective === 'string' && task.objective !== '') lines.push(`目标:${task.objective}`)
const acceptance = Array.isArray(packet?.acceptance) && packet.acceptance.length > 0 ? packet.acceptance : task?.acceptance
if (Array.isArray(acceptance) && acceptance.length > 0) {
lines.push('验收标准:')
for (const item of acceptance) lines.push(`- ${String(item)}`)
}
const constraints = Array.isArray(packet?.constraints) ? packet.constraints : task?.constraints
if (Array.isArray(constraints) && constraints.length > 0) {
lines.push('约束:')
for (const item of constraints) lines.push(`- ${String(item)}`)
}
const refs = Array.isArray(packet?.materialRefs) ? packet.materialRefs : []
if (refs.length > 0) {
lines.push('相关材料:')
for (const ref of refs) lines.push(`- ${typeof ref === 'string' ? ref : JSON.stringify(ref)}`)
}
lines.push('')
lines.push(`完成后请用结构化回传(不要只在正文里说“已完成”,那样不算完成):`)
lines.push(typeof contractGuide === 'string' && contractGuide !== '' ? contractGuide : '')
lines.push('')
lines.push(`(你是本项目的 ${name};任务与成果归属由程序按项目登记,不要自行改派给其他部门。)`)
return lines.join('\n')
}

View File

@ -0,0 +1,188 @@
// 工作台 Host 外壳:把 store + service + 适配层 + 两个后台服务组装成一个可挂载组件。
//
// 挂载方式(index.js 里):
// const host = createWorkbenchHost(ctx, { store, presetId })
// ctx.effect(() => () => host.dispose(), 'sansheng-liubo: workbench')
//
// 能力探测优先:宿主没有 sessionController 时,工作台仍然能读写账本(投影可用),
// 但任何“派发/接通”都返回 NO_SESSION_CONTROLLER,UI 显示“尚未接通”,绝不假装成功。
import { WorkbenchStore, defaultStorePath } from '../core/store.mjs'
import { createWorkbenchService } from './service.mjs'
import { createSessionAdapter } from './session-adapter.mjs'
import { createDispatchService } from './dispatch-service.mjs'
import { createReconciler } from './reconciler.mjs'
import { CONTRACT_ACTIONS, CONTRACT_ACTION_PREFIX, parseContractLines, describeContract } from './contract.mjs'
export const WORKBENCH_HOST_VERSION = 1
/**
* @param {object} ctx Host 插件上下文(cordis Context)
* @param {object} [options]
* @param {object} [options.store] 已有 store(测试注入);缺省按环境建一个。
* @param {object} [options.service] 已有 service;缺省按 store 新建。给了 service 就必须同时给 store,
* 否则两边的账不是同一本。
* @param {string} [options.presetId] 部门会话使用的 agentPreset,首版沿用「上朝」。
* @param {boolean} [options.startReconciler] 是否启动周期对账,默认 true。
*/
export function createWorkbenchHost(ctx, options = {}) {
const log = (message) => {
try {
ctx?.logger?.info?.(message)
} catch {
/* 日志失败不能影响业务 */
}
}
const store = options.store ?? createStore(options)
const service = options.service ?? createWorkbenchService({ store, clock: options.clock, fileExists: options.fileExists })
// 会话层是可选能力:宿主没有 sessionController(或版本不提供)时整体降级。
const sessionController = ctx?.sessionController ?? ctx?.remote?.session ?? null
const hasSessions = sessionController !== null && typeof sessionController?.prompt === 'function'
let sessions = null
if (hasSessions) {
try {
sessions = createSessionAdapter({ sessionController, log })
} catch (error) {
log(`[sansheng-liubo] 会话层不可用:${error?.message ?? error}`)
sessions = null
}
}
const dispatchService = sessions === null
? null
: createDispatchService({ store, service, sessions, log })
const reconciler = sessions === null
? null
: createReconciler({ store, service, sessions, log })
const presetId = typeof options.presetId === 'string' && options.presetId !== '' ? options.presetId : 'sansheng-liubu'
/**
* 接通某个部门的会话:已有绑定就直接用,没有就按 workspace 建一个并登记。
* 绑定替换由 store 的 bindSession 判定(allowReplace),账上和宿主保持一致。
*/
async function connectDepartment(input = {}) {
const projectId = requireText(input.projectId, 'projectId')
const roleId = requireText(input.roleId, 'roleId')
const project = store.getProject(projectId)
if (project === undefined) throw new Error('项目不存在')
if (sessions === null) {
throw new Error('宿主未提供会话能力,暂时无法接通部门(账本仍可读写)')
}
const binding = store.getBinding(projectId, roleId)
const existing = binding?.currentSessionId ?? null
if (existing !== null) {
const known = await sessions.inspectSession(existing)
if (known !== null) return { sessionId: existing, created: false, seat: seatOf(projectId, roleId) }
}
const target = await sessions.ensureSession({
workspaceId: project?.hostWorkspaceId,
sessionId: input.sessionId ?? null,
agentPreset: input.agentPreset ?? presetId,
})
// 账上登记:同一会话被别的部门占用时 store 会拒绝,正是我们要的“会话独占”。
const saved = service.bindDepartmentSession({
projectId,
roleId,
sessionId: target.sessionId,
allowReplace: existing !== null,
})
return { sessionId: target.sessionId, created: target.created === true, seat: saved.seat }
}
function seatOf(projectId, roleId) {
return service.listSeats(projectId).find((seat) => seat.roleId === roleId) ?? null
}
/** 派发(对 UI 的唯一入口)。没有会话层时返回明确错误,不假装已发送。 */
async function dispatchTask(input = {}) {
if (dispatchService === null) {
return { ok: false, code: 'NO_SESSION_CONTROLLER', message: '宿主未提供会话能力,派发已停在工作台账内' }
}
return dispatchService.dispatch(input)
}
/** 处理部门输出里的契约行:只认结构化字段,解析失败的行原样返回给 UI 提示。 */
function ingestAgentOutput({ projectId, roleId, text } = {}) {
const parsed = parseContractLines(text)
const applied = []
const failed = []
for (const call of parsed.calls) {
try {
applied.push(applyContractCall({ projectId, roleId, call }))
} catch (error) {
failed.push({ action: call.action, code: error?.code ?? 'unknown', message: error?.message ?? String(error) })
}
}
return { applied, failed, invalid: parsed.invalid }
}
function applyContractCall({ projectId, roleId, call }) {
const payload = { ...call.payload, projectId }
switch (call.action) {
case 'dispatchTask':
if (payload.sourceRoleId === undefined) payload.sourceRoleId = roleId
return { action: call.action, result: service.dispatchTask(payload) }
case 'reportTaskResult':
return { action: call.action, result: service.reportTaskResult(payload) }
case 'requestTaskInput':
return { action: call.action, result: service.requestTaskInput(payload) }
case 'syncDecision':
return { action: call.action, result: service.syncDecision(payload) }
default:
throw new Error(`未知动作:${String(call.action)}`)
}
}
let started = false
function start() {
if (started) return
started = true
if (options.startReconciler !== false && reconciler !== null) reconciler.start()
}
function dispose() {
if (reconciler !== null) reconciler.stop()
if (sessions !== null) sessions.dispose()
started = false
}
return Object.freeze({
version: WORKBENCH_HOST_VERSION,
store,
service,
sessions,
reconciler,
dispatchService,
presetId,
hasSessions,
connectDepartment,
dispatchTask,
ingestAgentOutput,
bootstrap: (projectId) => service.bootstrap(projectId),
listEvents: (projectId, since, opts) => service.listEvents(projectId, since, opts),
start,
dispose,
})
}
function createStore(options) {
const file = options.storeFile ?? defaultStorePath(process.env)
const store = new WorkbenchStore({ file })
try {
store.load()
} catch {
// 读到坏账本时不静默清空:由 paths.quarantineFile 在 HTTP 层隔离,这里保持空账可写。
}
return store
}
function requireText(value, field) {
if (typeof value !== 'string' || value.trim() === '') throw new Error(`${field} 必须是非空字符串`)
return value
}
export { CONTRACT_ACTIONS, CONTRACT_ACTION_PREFIX, parseContractLines, describeContract }

File diff suppressed because it is too large Load Diff

View File

@ -0,0 +1,26 @@
{
"name": "dsh-sansheng-liubu-workbench",
"version": "0.1.0",
"private": true,
"description": "三省六部工作台:右侧朝堂部门树、任务与成果",
"type": "module",
"exports": {
"./client": "./lib/client.js"
},
"files": [
"lib/**"
],
"dsh": {
"client": {
"platform": "web",
"inject": [
"@deepseek-ai/dsh-api-session-controller",
"@deepseek-ai/dsh-client-ui-workspace",
"@deepseek-ai/dsh-client-ui-primitives"
]
}
},
"peerDependencies": {
"@deepseek-ai/cordis": "~4.0.5"
}
}

View File

@ -0,0 +1,515 @@
import test from "node:test";
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { fileURLToPath } from "node:url";
import vm from "node:vm";
const CLIENT_PATH = fileURLToPath(new URL("../lib/client.js", import.meta.url));
const SOURCE = readFileSync(CLIENT_PATH, "utf8");
function createStorage(initial) {
const map = new Map(Object.entries(initial || {}));
return {
getItem(key) {
return map.has(key) ? map.get(key) : null;
},
setItem(key, value) {
map.set(key, String(value));
},
removeItem(key) {
map.delete(key);
},
};
}
function createReact() {
function createElement(type, props) {
const children = Array.prototype.slice.call(arguments, 2);
return { type: type, props: props || {}, children: children };
}
class Component {
constructor(props) {
this.props = props;
this.state = {};
}
}
return {
createElement: createElement,
Component: Component,
useState: function (initial) {
return [initial, function () {}];
},
useRef: function (initial) {
return { current: initial };
},
useEffect: function () {},
useCallback: function (fn) {
return fn;
},
useMemo: function (fn) {
return fn();
},
useContext: function () {
return null;
},
createContext: function (value) {
return { _value: value };
},
Fragment: "Fragment",
};
}
function createDocument() {
const appended = [];
return {
appended: appended,
hidden: false,
head: {
appendChild: function (node) {
appended.push(node);
},
},
body: {},
querySelector: function () {
return null;
},
createElement: function (tagName) {
return {
tagName: tagName,
dataset: {},
textContent: "",
appendChild: function () {},
setAttribute: function () {},
};
},
addEventListener: function () {},
removeEventListener: function () {},
};
}
function loadPlugin(options) {
options = options || {};
const storage = createStorage(options.storage);
const document = createDocument();
const react = createReact();
let definition = null;
const window = {
__ModuleLoader__: {
load: function (loaded) {
definition = loaded;
},
},
};
const sandbox = {
window: window,
document: document,
console: console,
URL: URL,
Map: Map,
Set: Set,
WeakMap: WeakMap,
Promise: Promise,
setTimeout: setTimeout,
clearTimeout: clearTimeout,
localStorage: storage,
Symbol: Symbol,
};
vm.runInNewContext(SOURCE, sandbox, { filename: CLIENT_PATH });
assert.ok(definition, "bundle 应该调用 window.__ModuleLoader__.load");
assert.equal(definition.id, "dsh-sansheng-liubu-workbench", "bundle id 必须是包名");
const exports = definition.factory(function (id) {
if (id === "react") return react;
throw new Error("unexpected require: " + id);
});
return { exports: exports, react: react, storage: storage, document: document, definition: definition };
}
function createCtx(options) {
options = options || {};
const registrations = [];
const injections = [];
const tabs = [];
const effects = [];
const ctx = {
slots: {
inject: function (name, factory) {
injections.push(name);
const value = factory();
if (value !== undefined) registrations.push(value);
return function () {};
},
register: function (spec, component) {
const registration = { spec: spec, component: component };
registrations.push(registration);
return registration;
},
},
effect: function (factory, label) {
effects.push(label);
const value = factory();
return typeof value === "function" ? value : function () {};
},
get: function (name) {
return options.services ? options.services[name] : undefined;
},
uiWorkspace: {
currentWorkspaceId: options.workspaceId || "ws-1",
openSession: function () {},
},
};
if (!options.noTabs) {
ctx.sidebarRightTabs = {
register: function (spec) {
tabs.push(spec);
return function () {};
},
};
}
return { ctx: ctx, registrations: registrations, injections: injections, tabs: tabs, effects: effects };
}
test("bundle 契约:id、inject 与纯函数导出", function () {
const plugin = loadPlugin();
const api = plugin.exports;
assert.deepEqual(Array.from(api.inject), ["slots", "sessions", "uiWorkspace", "uiConversation"]);
assert.equal(typeof api.apply, "function");
assert.equal(typeof api.WorkbenchRail, "function");
assert.equal(typeof api.__test, "object");
const expected = ["computeRailLayout", "statusOf", "mergeEvents", "apiPath", "pickProjectId", "formatModelLine", "ROLE_META"];
for (const key of expected) assert.ok(key in api.__test, "__test 缺少 " + key);
assert.equal(Object.keys(api.__test.ROLE_META).length, 10);
assert.deepEqual(Object.keys(api.__test.ROLE_META).slice(0, 4), ["lead", "zhongshu", "shangshu", "menxia"]);
});
test("computeRailLayout:丞相跨三列居中、三省一列、六部 3×2", function () {
const layout = loadPlugin().exports.__test.computeRailLayout(400);
assert.equal(layout.width, 400);
assert.equal(layout.nodes.length, 10);
const byId = {};
for (const node of layout.nodes) {
assert.equal(typeof node.id, "string");
assert.equal(typeof node.x, "number");
assert.equal(typeof node.y, "number");
assert.equal(typeof node.col, "number");
assert.equal(typeof node.row, "number");
byId[node.id] = node;
}
const lead = byId.lead;
assert.equal(lead.col, 1);
assert.equal(lead.span, 3);
assert.ok(Math.abs(lead.x + lead.w / 2 - 200) < 0.001, "丞相应水平居中");
assert.ok(Math.abs(lead.x - (400 - lead.w) / 2) < 0.001);
const san = ["zhongshu", "shangshu", "menxia"].map((id) => byId[id]);
assert.deepEqual(Array.from(san, (node) => node.col), [0, 1, 2]);
assert.deepEqual(Array.from(san, (node) => node.row), [1, 1, 1]);
assert.equal(new Set(Array.from(san, (node) => node.y)).size, 1, "三省应在同一行");
assert.ok(san[0].x < san[1].x && san[1].x < san[2].x, "三省 x 必须递增");
const six = layout.nodes.filter((node) => node.row >= 2);
assert.equal(six.length, 6);
assert.deepEqual(Array.from(six, (node) => node.id), ["libu", "hubu", "lipu", "bingbu", "xingbu", "gongbu"]);
assert.equal(six[5].id, "gongbu", "第 6 个是工部");
assert.deepEqual(Array.from(six, (node) => node.col), [0, 1, 2, 0, 1, 2]);
assert.deepEqual(Array.from(six, (node) => node.row), [2, 2, 2, 3, 3, 3]);
assert.ok(layout.groups.ministries.y > layout.groups.sansheng.y + layout.groups.sansheng.h);
assert.ok(layout.height > 0);
});
test("computeRailLayout:窄栏仍是三列且不出现负宽度", function () {
const layout = loadPlugin().exports.__test.computeRailLayout(340);
assert.equal(layout.nodes.length, 10);
assert.equal(new Set(Array.from(layout.nodes, (node) => node.col)).size, 3);
for (const node of layout.nodes) assert.ok(node.w > 0, node.id + " 宽度必须为正");
assert.ok(layout.leadWidth <= 184);
});
test("statusOf:六种部门状态与未知值兜底", function () {
const { statusOf } = loadPlugin().exports.__test;
assert.equal(statusOf("uninitialized"), "未接通");
assert.equal(statusOf("idle"), "空闲");
assert.equal(statusOf("queued"), "排队");
assert.equal(statusOf("running"), "正在运行");
assert.equal(statusOf("unavailable"), "不可用");
assert.equal(statusOf("needs_attention"), "需人处理");
assert.equal(statusOf("something-new"), "未知");
assert.equal(statusOf(null), "未接通");
assert.equal(statusOf(""), "未接通");
});
test("mergeEvents:按 eventId 去重、按 seq 升序、忽略乱序重复", function () {
const { mergeEvents } = loadPlugin().exports.__test;
const merged = mergeEvents(
[{ eventId: "a", seq: 3 }, { eventId: "b", seq: 1 }],
[{ eventId: "b", seq: 1 }, { eventId: "c", seq: 2 }, { eventId: "a", seq: 3 }],
);
assert.equal(merged.length, 3);
assert.deepEqual(Array.from(merged, (event) => event.eventId), ["b", "c", "a"]);
assert.deepEqual(Array.from(merged, (event) => event.seq), [1, 2, 3]);
const again = mergeEvents(merged, []);
assert.deepEqual(Array.from(again, (event) => event.eventId), ["b", "c", "a"]);
assert.deepEqual(Array.from(mergeEvents([], [])), []);
});
test("formatModelLine:无配置跟随宿主,有配置拼 provider/model · effort", function () {
const { formatModelLine } = loadPlugin().exports.__test;
assert.equal(formatModelLine(null), "跟随宿主");
assert.equal(formatModelLine(undefined), "跟随宿主");
assert.equal(formatModelLine({}), "跟随宿主");
assert.equal(formatModelLine({ provider: "", model: "" }), "跟随宿主");
assert.equal(formatModelLine({ provider: "deepseek", model: "", reasoningEffort: "high" }), "跟随宿主");
assert.equal(formatModelLine({ provider: "deepseek", model: "deepseek-v4", reasoningEffort: "high" }), "deepseek/deepseek-v4 · 高");
assert.equal(formatModelLine({ provider: "deepseek", model: "deepseek-v4" }), "deepseek/deepseek-v4");
assert.equal(formatModelLine({ provider: "deepseek", model: "deepseek-v4", reasoningEffort: "custom" }), "deepseek/deepseek-v4 · custom");
// model 自带 provider 前缀时只留最后一段,完整路径放 title。
assert.equal(
formatModelLine({ provider: "magpie", model: "workbuddy/deepseek-v4", reasoningEffort: "high" }),
"deepseek-v4 · 高",
);
});
test("seatDisplayName:name 与 short 同时存在时必须用完整名", function () {
const { seatDisplayName, modelTitle } = loadPlugin().exports.__test;
assert.equal(seatDisplayName({ roleId: "lead", name: "丞相", short: "丞" }), "丞相");
assert.equal(seatDisplayName({ roleId: "zhongshu", name: "中书", short: "中" }), "中书");
assert.equal(seatDisplayName({ roleId: "lead" }), "丞相", "缺 name 时回落到 ROLE_META 的完整名");
assert.equal(seatDisplayName({ roleId: "lead", short: "丞" }), "丞相", "short 不能优先于 ROLE_META 的完整名");
assert.equal(seatDisplayName({ name: "", roleId: "unknown" }), "unknown");
assert.equal(modelTitle(null), "跟随宿主(未单独配置模型)");
assert.equal(
modelTitle({ provider: "magpie", model: "workbuddy/deepseek-v4", reasoningEffort: "high" }),
"magpie/workbuddy/deepseek-v4 · 高",
);
});
test("wirePathsFromLayout:量不到 DOM 时仍能生成三支 + 主干连线", function () {
const { computeRailLayout, wirePathsFromLayout } = loadPlugin().exports.__test;
const layout = computeRailLayout(400);
const paths = wirePathsFromLayout(layout);
assert.equal(paths.length, 4, "三省三支 + 尚书到六部一条主干");
const branch = paths.filter((item) => item.kind === "branch");
const trunk = paths.filter((item) => item.kind === "trunk");
assert.equal(branch.length, 3);
assert.equal(trunk.length, 1);
assert.deepEqual(Array.from(branch).map((item) => item.key), ["lead-zhongshu", "lead-shangshu", "lead-menxia"]);
for (const item of branch) {
const id = item.key.replace(/^lead-/, "");
const card = layout.sansheng.find((node) => node.id === id);
assert.ok(item.d.includes(" C "), "分支必须用三次贝塞尔收口,垂直进入卡片顶边");
assert.ok(!item.d.includes(" Q "), "不要退回二次贝塞尔(会在卡片顶边上方擦成一条横线)");
const tail = item.d.match(/ C [0-9.]+ [0-9.]+ [0-9.]+ [0-9.]+ ([0-9.]+) ([0-9.]+)$/);
assert.ok(tail, "分支末尾应是第二个控制点 + 终点");
assert.ok(Math.abs(Number(tail[1]) - card.cx) < 0.06, "终点 x 应等于卡片顶边中点");
assert.equal(Number(tail[2]), card.y, "终点 y 应落在卡片顶边");
}
const shangshu = layout.sansheng.find((node) => node.id === "shangshu");
assert.equal(trunk[0].d, "M 200 " + (shangshu.y + shangshu.h) + " L 200 " + layout.groups.ministries.y);
});
test("apiPath:拼出同源工作台路径并编码查询串", function () {
const { apiPath } = loadPlugin().exports.__test;
assert.equal(apiPath("bootstrap"), "/sansheng/workbench/bootstrap");
assert.equal(apiPath("/connect"), "/sansheng/workbench/connect");
assert.equal(apiPath("events", { projectId: "p-1", since: 7 }), "/sansheng/workbench/events?projectId=p-1&since=7");
assert.equal(apiPath("events", { projectId: "p 1", since: undefined }), "/sansheng/workbench/events?projectId=p%201");
assert.equal(apiPath("bootstrap", {}), "/sansheng/workbench/bootstrap");
});
test("pickProjectId:优先当前工作区,其次 bootstrap 默认项目", function () {
const { pickProjectId } = loadPlugin().exports.__test;
const data = {
projectId: "p-default",
projects: [
{ id: "p-other", hostWorkspaceId: "ws-other" },
{ id: "p-mine", hostWorkspaceId: "ws-mine" },
],
};
assert.equal(pickProjectId(data, "ws-mine"), "p-mine");
assert.equal(pickProjectId(data, "ws-missing"), null);
assert.equal(pickProjectId(data), "p-default");
assert.equal(pickProjectId({ projects: [{ id: "p-only" }] }), "p-only");
assert.equal(pickProjectId({ projects: [] }), null);
});
test("apply:注册朝堂页签、pane 槽与 priority -1 的 main.conversation", function () {
const plugin = loadPlugin();
const mock = createCtx();
plugin.exports.apply(mock.ctx);
assert.ok(mock.injections.includes("sidebar.right.pane.tab"));
assert.ok(mock.injections.includes("sidebar.right.pane.tab.title"));
assert.ok(mock.injections.includes("main.conversation"));
assert.equal(mock.tabs.length, 1);
assert.equal(mock.tabs[0].id, "sansheng-liubu-workbench");
assert.equal(mock.tabs[0].priority, "builtin");
assert.equal(mock.tabs[0].title(), "朝堂");
const main = mock.registrations.find((entry) => entry.spec && entry.spec.name === "main.conversation");
assert.ok(main, "必须注册 main.conversation");
assert.equal(main.spec.priority, -1);
assert.deepEqual(Array.from(Object.keys(main.spec.children)), ["conversation.header"]);
});
test("apply:localStorage 逃生开关 sansheng.workbench.main=off 时不接管主区", function () {
const plugin = loadPlugin({ storage: { "sansheng.workbench.main": "off" } });
const mock = createCtx();
plugin.exports.apply(mock.ctx);
assert.equal(mock.injections.includes("main.conversation"), false);
assert.ok(mock.injections.includes("sidebar.right.pane.tab"));
});
test("main.conversation:非绑定会话只透传原生 header/content,不加右栏", function () {
const plugin = loadPlugin();
const mock = createCtx();
plugin.exports.apply(mock.ctx);
const main = mock.registrations.find((entry) => entry.spec && entry.spec.name === "main.conversation");
const tree = main.component({
sessionId: "session-1",
useSession: function () {
return { openState: "open", blank: true, running: false, promptAttempted: false };
},
useSessions: function (select) {
return select({ byId: { "session-1": { blank: true } } });
},
useConversation: function () {
return { activeTargets: new Set() };
},
renderSlot: function (name) {
return { type: "header-slot", name: name };
},
renderFactorySlot: function (name, params) {
return { type: "content-slot", name: name, params: params };
},
widthControls: { width: 900 },
});
assert.equal(tree.props.className, "wb-main-native");
const children = tree.children[0];
assert.equal(children[0].type, "header-slot");
assert.equal(children[1].type, "content-slot");
assert.equal(children[1].params.phase, "hero");
assert.deepEqual(children[1].params.hero, true);
assert.ok(!JSON.stringify(tree).includes("wb-main-rail"), "非工作台会话不能出现右栏");
});
test("WorkbenchRail:无数据时也渲染完整骨架与三个内部页签", function () {
const plugin = loadPlugin();
const mock = createCtx();
const tree = plugin.exports.WorkbenchRail({ ctx: mock.ctx, compact: true });
assert.ok(tree.props.className.includes("wb-rail"));
assert.ok(tree.props.className.includes("is-compact"));
const serialized = JSON.stringify(tree);
assert.ok(serialized.includes("三省六部"));
assert.ok(serialized.includes("朝堂"));
assert.ok(serialized.includes("任务"));
assert.ok(serialized.includes("成果"));
assert.ok(serialized.includes("十席 · 0 席已接通"));
assert.ok(serialized.includes("六部 · 同级"));
assert.ok(serialized.includes("正在读取") === false);
});
test("main.conversation:接管逻辑抛错时回退原生会话,不白屏", function () {
const plugin = loadPlugin();
const mock = createCtx();
plugin.exports.apply(mock.ctx);
const main = mock.registrations.find((entry) => entry.spec && entry.spec.name === "main.conversation");
const warnings = [];
const originalWarn = console.warn;
console.warn = function () {
warnings.push(Array.from(arguments));
};
try {
const tree = main.component({
sessionId: "session-1",
useSession: function () {
// 模拟接管逻辑在渲染途中抛异常(理论上不应发生,但必须兜住)。
throw new Error("boom");
},
useSessions: function () {
return undefined;
},
useConversation: function () {
return { activeTargets: new Set() };
},
renderSlot: function (name) {
return { type: "header-slot", name: name };
},
renderFactorySlot: function (name, params) {
return { type: "content-slot", name: name, params: params };
},
});
assert.equal(tree.props.className, "wb-main-native");
assert.equal(tree.children[0][0].type, "header-slot");
assert.equal(tree.children[0][1].type, "content-slot");
assert.ok(!JSON.stringify(tree).includes("wb-main-split"), "回退时不能拼右栏");
assert.ok(!JSON.stringify(tree).includes("wb-main-resizer"), "回退时不能拼分隔条");
assert.ok(
warnings.some((args) => String(args[0]).includes("接管失败")),
"回退时要留下可诊断的 console.warn",
);
} finally {
console.warn = originalWarn;
}
});
test("existenceLabel:missing / unknown / ok 三态,unknown 不能被当成正常", function () {
const plugin = loadPlugin();
const { existenceLabel } = plugin.exports.__test;
assert.equal(existenceLabel("missing"), "文件已失效");
assert.equal(existenceLabel("unknown"), "位置未核验");
assert.equal(existenceLabel("ok"), "");
assert.equal(existenceLabel(undefined), "");
assert.notEqual(existenceLabel("unknown"), "");
assert.ok(!existenceLabel("unknown").includes("正常"), "unknown 不能显示成正常");
assert.ok(!existenceLabel("ok").includes("正常"), "ok 也不必写正常,静默即可");
});
test("revisionLabel:第 N 版,只有真正修订且 N>1 才写「修订自上一版」", function () {
const plugin = loadPlugin();
const { revisionLabel } = plugin.exports.__test;
assert.equal(revisionLabel({ revision: 1, revisesArtifactId: "art-0" }), "第 1 版");
assert.ok(!revisionLabel({ revision: 1, revisesArtifactId: "art-0" }).includes("修订自"));
assert.equal(revisionLabel({ revision: 2, revisesArtifactId: "art-0" }), "第 2 版 · 修订自上一版");
assert.equal(revisionLabel({ revision: 3, revisesArtifactId: null }), "第 3 版");
assert.equal(revisionLabel({}), "第 1 版");
assert.equal(revisionLabel(null), "第 1 版");
});
test("taskKindLabel:只给 kind=revision 加「修订」标签", function () {
const plugin = loadPlugin();
const { taskKindLabel } = plugin.exports.__test;
assert.equal(taskKindLabel({ kind: "revision" }), "修订");
assert.equal(taskKindLabel({ kind: "normal" }), "");
assert.equal(taskKindLabel({}), "");
assert.equal(taskKindLabel(null), "");
});

View File

@ -0,0 +1,326 @@
// Host 层测试:契约解析、会话适配、派发幂等、对账与工作台外壳。
// 全部用假 SessionController(与 P0 记录的签名同形)驱动,不连真宿主,
// 这样“首次派发 / 重复点击 / 超时未知 / 宿主重启后对账”都能确定性地复现。
import test from 'node:test'
import assert from 'node:assert/strict'
import { WorkbenchStore } from '../core/store.mjs'
import { createWorkbenchService } from '../host/service.mjs'
import {
CONTRACT_ACTION_PREFIX,
parseContractLines,
validateContractCall,
describeContract,
} from '../host/contract.mjs'
import { buildDispatchText, classifyHostError, createSessionAdapter } from '../host/session-adapter.mjs'
import { createDispatchService } from '../host/dispatch-service.mjs'
import { createReconciler } from '../host/reconciler.mjs'
import { createWorkbenchHost } from '../host/workbench-host.mjs'
const clock = () => 1700000000000
const WS = 'ws_demo'
/** 假宿主:行为可控,记录每次 create/prompt/cancel,便于断言“没重发”。 */
function fakeController(behaviour = {}) {
const calls = { create: [], prompt: [], cancel: [], selectModel: [], inspect: [], list: 0 }
const sessions = new Map()
let next = 1
const controller = {
calls,
sessions,
async create(request) {
calls.create.push(request)
const existing = [...sessions.values()].find((row) => row.workspaceId === request.workspaceId)
if (existing !== undefined && request.sessionId === undefined) return { sessionId: existing.sessionId }
const sessionId = request.sessionId ?? `ses_${next++}`
sessions.set(sessionId, { sessionId, workspaceId: request.workspaceId ?? null, running: false, accepted: new Set() })
return { sessionId, agentPreset: request.agentPreset ?? null }
},
async inspect(sessionId) {
calls.inspect.push(sessionId)
const row = sessions.get(sessionId)
if (row === undefined) throw Object.assign(new Error('not found'), { code: 'session/not-found' })
return { sessionId, attached: true }
},
async prompt(request) {
calls.prompt.push(request)
const row = sessions.get(request.sessionId)
if (row === undefined) throw Object.assign(new Error('no session'), { code: 'session/conflict' })
if (behaviour.promptFails === 'timeout') throw Object.assign(new Error('timeout picking up request'), { code: 'ETIMEDOUT' })
if (behaviour.promptFails === 'busy') throw Object.assign(new Error('agent busy'), { code: 'session/agent-busy' })
if (row.accepted.has(request.requestId)) return { accepted: true }
row.accepted.add(request.requestId)
row.running = behaviour.staysRunning !== false
return { accepted: true }
},
cancel(request) {
calls.cancel.push(request)
const row = sessions.get(request.sessionId)
if (row !== undefined) row.running = false
return { accepted: true }
},
async selectModel(request) {
calls.selectModel.push(request)
if (behaviour.selectModelFails === true) {
throw Object.assign(new Error('model unavailable'), { code: 'session/model-unavailable' })
}
return { selected: { provider: request.provider, model: request.model } }
},
async list() {
calls.list += 1
return {
items: [...sessions.values()].map((row) => ({ sessionId: row.sessionId, running: row.running, agentAvailable: true, updatedAt: '', blank: false })),
}
},
}
return controller
}
function freshWorkbench(behaviour = {}) {
const store = new WorkbenchStore({ file: null, clock, env: { DSH_HOME: '/tmp/never-used' } })
const service = createWorkbenchService({ store, clock })
const controller = fakeController(behaviour)
const sessions = createSessionAdapter({ sessionController: controller })
const dispatch = createDispatchService({ store, service, sessions })
const reconciler = createReconciler({ store, service, sessions, clock })
const project = service.registerProject({ hostWorkspaceId: WS, displayNameCache: '演示项目' }).project
// 接通丞相与工部两个会话(首版两席闭环)。
for (const roleId of ['lead', 'gongbu']) {
const sessionId = roleId === 'lead' ? 'ses_lead' : 'ses_gongbu'
controller.sessions.set(sessionId, { sessionId, workspaceId: WS, running: false, accepted: new Set() })
service.bindDepartmentSession({ projectId: project.id, roleId, sessionId, allowReplace: false })
}
service.saveDepartmentConfig({
projectId: project.id,
roleId: 'gongbu',
provider: 'magpie',
model: 'workbuddy/deepseek-v4.1-flash',
expectedRevision: 0,
})
return { store, service, controller, sessions, dispatch, reconciler, projectId: project.id }
}
// ---------- 契约 ----------
test('契约解析只认四动作,坏 JSON 与未知动作都不改状态', () => {
const text = [
'普通正文,不含指令。',
`${CONTRACT_ACTION_PREFIX}{"action":"reportTaskResult","taskId":"task_1","attemptId":"att_1","summary":"完成"}`,
`${CONTRACT_ACTION_PREFIX}{"action":"finalizeEverything","taskId":"task_1"}`,
`${CONTRACT_ACTION_PREFIX}{不是 JSON}`,
'我已经完成了。',
].join('\n')
const { calls, invalid } = parseContractLines(text)
assert.equal(calls.length, 1)
assert.equal(calls[0].action, 'reportTaskResult')
assert.equal(invalid.length, 2)
assert.match(invalid[0].reason, /未知动作/)
assert.match(invalid[1].reason, /JSON/)
// 纯文本“已完成”不产生任何调用:这是方案明令禁止的推断路径。
assert.deepEqual(parseContractLines('任务已完成,请查收').calls, [])
assert.deepEqual(parseContractLines(null), { calls: [], invalid: [] })
})
test('validateContractCall 拦住缺幂等键/缺摘要的调用', () => {
assert.deepEqual(validateContractCall({ action: 'dispatchTask', payload: { taskId: 'task_1', idempotencyKey: 'k' } }), [])
assert.deepEqual(validateContractCall({ action: 'reportTaskResult', payload: { taskId: 'task_1', attemptId: 'att_1', summary: 's' } }), [])
assert.match(validateContractCall({ action: 'dispatchTask', payload: { taskId: 'task_1' } })[0], /idempotencyKey/)
assert.match(validateContractCall({ action: 'reportTaskResult', payload: { taskId: 't' } }).join(';'), /attemptId/)
assert.match(validateContractCall({ action: 'requestTaskInput', payload: { taskId: 't', attemptId: 'a' } }).join(';'), /reason/)
assert.match(validateContractCall({ action: 'syncDecision', payload: { taskId: 't' } }).join(';'), /decision/)
assert.match(describeContract(), /reportTaskResult/)
})
// ---------- 会话适配 ----------
test('会话适配:缺 sessionId 时按 workspace 建会话且不重复建', async () => {
const controller = fakeController()
const sessions = createSessionAdapter({ sessionController: controller })
const first = await sessions.ensureSession({ workspaceId: WS, agentPreset: 'sansheng-liubu' })
const second = await sessions.ensureSession({ workspaceId: WS, agentPreset: 'sansheng-liubu' })
assert.equal(first.created, true)
assert.equal(first.sessionId, second.sessionId, '同一 workspace 不能建出第二个会话')
assert.equal(controller.calls.create.length, 2)
await assert.rejects(() => sessions.ensureSession({}), /workspaceId/)
})
test('会话适配:prompt 必须带 requestId,错误分类可区分可重试与必失败', async () => {
const controller = fakeController()
const sessions = createSessionAdapter({ sessionController: controller })
await assert.rejects(() => sessions.sendPrompt({ sessionId: 'ses_1', text: 'hi' }), /requestId/)
await assert.rejects(() => sessions.sendPrompt({ sessionId: 'ses_1', requestId: 'r1', text: ' ' }), /为空/)
assert.equal(classifyHostError(Object.assign(new Error('x'), { code: 'session/conflict' })), 'conflict')
assert.equal(classifyHostError(Object.assign(new Error('x'), { code: 'session/model-unavailable' })), 'model_unavailable')
assert.equal(classifyHostError(new Error('request timeout')), 'transient')
assert.equal(classifyHostError(new Error('随便什么')), 'unknown')
})
test('派发提示词只写事实,不给“已完成”下定义', () => {
const text = buildDispatchText({
task: { id: 'task_1', title: '整理报表', objective: '合并三张表', acceptance: ['口径一致'], constraints: ['只读源文件'] },
packet: { materialRefs: ['a.xlsx'] },
contractGuide: '(结构化回传说明)',
roleName: '工部',
})
assert.match(text, /任务单 task_1/)
assert.match(text, /口径一致/)
assert.match(text, /a\.xlsx/)
assert.match(text, /不要只在正文里说“已完成”/)
})
// ---------- 派发 ----------
test('首次派发:固定模型快照 → prompt 用 attemptId 作幂等键 → dispatch accepted', async () => {
const { store, service, controller, dispatch, projectId } = freshWorkbench()
const task = service.createTask({ projectId, ownerRoleId: 'gongbu', sourceRoleId: 'lead', title: '导出报表', objective: '按模板导出' }).task
const result = await dispatch.dispatch({ projectId, taskId: task.id, idempotencyKey: 'k1' })
assert.equal(result.outcome, 'accepted')
assert.equal(result.duplicate, false)
const attempt = store.getAttempt(result.attempt.id)
assert.equal(attempt.state, 'running')
assert.equal(controller.calls.selectModel.length, 1, '每次派发只覆写一次模型')
assert.equal(controller.calls.selectModel[0].model, 'workbuddy/deepseek-v4.1-flash')
assert.equal(controller.calls.prompt.length, 1)
assert.equal(controller.calls.prompt[0].requestId, attempt.id, 'attemptId 就是 prompt 的幂等键')
assert.equal(store.getDispatch(result.dispatch.id).state, 'accepted')
})
test('重复点击同一幂等键:不重复投递、返回既有结论', async () => {
const { service, controller, dispatch, projectId } = freshWorkbench()
const task = service.createTask({ projectId, ownerRoleId: 'gongbu', sourceRoleId: 'lead', title: 't', objective: 'o' }).task
const first = await dispatch.dispatch({ projectId, taskId: task.id, idempotencyKey: 'same' })
const second = await dispatch.dispatch({ projectId, taskId: task.id, idempotencyKey: 'same' })
assert.equal(second.duplicate, true)
assert.equal(second.dispatch.id, first.dispatch.id)
assert.equal(controller.calls.prompt.length, 1, '第二次点击不能再发一条消息')
})
test('投递超时:dispatch 记 unknown,不自动重发', async () => {
const { store, service, controller, dispatch, projectId } = freshWorkbench({ promptFails: 'timeout' })
const task = service.createTask({ projectId, ownerRoleId: 'gongbu', sourceRoleId: 'lead', title: 't', objective: 'o' }).task
const result = await dispatch.dispatch({ projectId, taskId: task.id, idempotencyKey: 'k-timeout' })
assert.equal(result.outcome, 'unknown')
assert.equal(store.getDispatch(result.dispatch.id).state, 'unknown')
assert.equal(store.getAttempt(result.attempt.id).state, 'unknown')
assert.equal(controller.calls.prompt.length, 1)
// 再点一次同一幂等键:仍是 unknown,不会再发第二遍
const again = await dispatch.dispatch({ projectId, taskId: task.id, idempotencyKey: 'k-timeout' })
assert.equal(again.duplicate, true)
assert.equal(controller.calls.prompt.length, 1)
// 查证:会话确实存在 → 收口为 accepted
const verified = await dispatch.verifyUnknown(result.dispatch.id)
assert.equal(verified.outcome, 'accepted')
assert.equal(store.getAttempt(result.attempt.id).state, 'running')
})
test('部门未接通时派发被拒,任务留在账上而不是变成失败', async () => {
const { store, service, dispatch, projectId } = freshWorkbench()
// 户部没有接通会话:只能先存草稿,入队会被明确拒绝(派给没会话的部门只会在投递阶段撞 unknown)。
const task = service.createTask({ projectId, ownerRoleId: 'hubu', sourceRoleId: 'lead', title: 't', objective: 'o', status: 'draft' }).task
await assert.rejects(
() => dispatch.dispatch({ projectId, taskId: task.id, idempotencyKey: 'k' }),
(error) => error.code === 'INVALID_STATE',
)
assert.equal(store.getTask(task.id).status, 'draft', '被拒的派发不改任务状态')
})
// ---------- 对账 ----------
test('对账:宿主还在跑只推进 running,不判完成', async () => {
const { store, service, dispatch, reconciler, projectId } = freshWorkbench({ staysRunning: true })
const task = service.createTask({ projectId, ownerRoleId: 'gongbu', sourceRoleId: 'lead', title: 't', objective: 'o' }).task
const result = await dispatch.dispatch({ projectId, taskId: task.id, idempotencyKey: 'k' })
const outcome = await reconciler.reconcileOnce()
assert.equal(outcome.checked >= 1, true)
assert.equal(store.getTask(task.id).status, 'running', '还在跑就不是完成')
assert.equal(store.getAttempt(result.attempt.id).state, 'running')
})
test('对账:运行结束但无报告 → needs_attention,而不是 completed', async () => {
const { store, service, controller, dispatch, reconciler, projectId } = freshWorkbench()
const task = service.createTask({ projectId, ownerRoleId: 'gongbu', sourceRoleId: 'lead', title: 't', objective: 'o' }).task
const result = await dispatch.dispatch({ projectId, taskId: task.id, idempotencyKey: 'k' })
controller.sessions.get('ses_gongbu').running = false
await reconciler.reconcileOnce()
assert.equal(store.getAttempt(result.attempt.id).state, 'succeeded')
assert.equal(store.getTask(task.id).status, 'needs_attention')
assert.match(store.getTask(task.id).needsAttentionReason, /结构化报告/)
})
test('对账:取消请求后宿主停跑 → attempt cancelled、任务 cancelled', async () => {
const { store, service, controller, dispatch, reconciler, sessions, projectId } = freshWorkbench()
const task = service.createTask({ projectId, ownerRoleId: 'gongbu', sourceRoleId: 'lead', title: 't', objective: 'o' }).task
const result = await dispatch.dispatch({ projectId, taskId: task.id, idempotencyKey: 'k' })
// 只发停止请求:cancel() 是同步 accepted,不等于已停,此时尝试仍停在 running。
sessions.requestCancel('ses_gongbu')
controller.sessions.get('ses_gongbu').running = false
await reconciler.reconcileOnce()
assert.equal(store.getAttempt(result.attempt.id).state, 'cancelled')
assert.equal(store.getTask(task.id).status, 'cancelled')
})
test('对账:宿主重启后查不到会话时不猜,保持原状', async () => {
const { store, service, controller, dispatch, reconciler, projectId } = freshWorkbench()
const task = service.createTask({ projectId, ownerRoleId: 'gongbu', sourceRoleId: 'lead', title: 't', objective: 'o' }).task
const result = await dispatch.dispatch({ projectId, taskId: task.id, idempotencyKey: 'k' })
// 让 list 抛错:问不到 = null
controller.list = async () => {
throw new Error('host restarting')
}
const outcome = await reconciler.reconcileOnce()
assert.equal(outcome.changed.length, 0)
assert.equal(store.getAttempt(result.attempt.id).state, 'running')
})
// ---------- 工作台外壳 ----------
test('工作台外壳:浏览器侧/无会话能力时降级为只读账本', async () => {
const store = new WorkbenchStore({ file: null, clock })
const host = createWorkbenchHost({}, { store })
assert.equal(host.hasSessions, false)
const project = host.service.registerProject({ hostWorkspaceId: WS }).project
const bootstrap = host.bootstrap(project.id)
assert.equal(bootstrap.seats.length, 10)
assert.equal(bootstrap.seats.filter((seat) => seat.connected).length, 0)
assert.equal(bootstrap.seats[0].pendingLabel, '尚未接通')
const dispatched = await host.dispatchTask({ projectId: project.id, taskId: 'task_x', idempotencyKey: 'k' })
assert.equal(dispatched.ok, false)
assert.equal(dispatched.code, 'NO_SESSION_CONTROLLER')
})
test('工作台外壳:接通部门写出绑定,且同一会话不能同时属于两个部门', async () => {
const store = new WorkbenchStore({ file: null, clock })
const controller = fakeController()
const host = createWorkbenchHost({ sessionController: controller }, { store })
const project = host.service.registerProject({ hostWorkspaceId: WS }).project
const gongbu = await host.connectDepartment({ projectId: project.id, roleId: 'gongbu' })
assert.equal(gongbu.created, true)
assert.equal(gongbu.seat.connected, true)
// 把工部已在用的会话硬塞给户部:store 必须拒绝(会话独占)
await assert.rejects(
() => host.connectDepartment({ projectId: project.id, roleId: 'hubu', sessionId: gongbu.sessionId }),
(error) => error.code === 'SESSION_CONFLICT',
)
const seats = host.bootstrap(project.id).seats
assert.equal(seats.find((seat) => seat.roleId === 'gongbu').connected, true)
assert.equal(seats.find((seat) => seat.roleId === 'hubu').connected, false)
})
test('工作台外壳:ingestAgentOutput 只应用可解析的契约行', () => {
const store = new WorkbenchStore({ file: null, clock })
const host = createWorkbenchHost({}, { store })
const project = host.service.registerProject({ hostWorkspaceId: WS }).project
// 无会话能力的外壳里工部未接通,只能建草稿;这里要验的是契约解析,不是入队资格。
const task = host.service.createTask({ projectId: project.id, ownerRoleId: 'gongbu', sourceRoleId: 'lead', title: 't', objective: 'o', status: 'draft' }).task
// 草稿要先入队,才谈得上 waiting_input。
store.updateTask({ ...store.getTask(task.id), status: 'queued' })
const text = [
'正文里说一句“已完成”,不算数。',
`${CONTRACT_ACTION_PREFIX}${JSON.stringify({ action: 'requestTaskInput', taskId: task.id, reason: '缺口径' })}`,
].join('\n')
const out = host.ingestAgentOutput({ projectId: project.id, roleId: 'gongbu', text })
assert.equal(out.applied.length, 1)
assert.equal(out.failed.length, 0)
assert.equal(store.getTask(task.id).status, 'waiting_input')
})

View File

@ -0,0 +1,58 @@
import test from 'node:test'
import assert from 'node:assert/strict'
import {
createIdFactory,
ID_ENTITIES,
ID_PREFIXES,
cryptoRandom,
isIdOf,
newId,
} from '../core/ids.mjs'
test('every entity prefix appears in the plan and generated ids round-trip', () => {
for (const entity of ID_ENTITIES) {
const id = newId(entity, { random: () => 0 })
assert.match(id, new RegExp(`^${ID_PREFIXES[entity]}_[0-9a-z]{12}$`), `${entity} 前缀正确`)
assert.equal(isIdOf(entity, id), true)
}
// 前缀本身也能直接使用,方便调用方不想记实体名的场景。
assert.match(newId('task', { random: () => 3 }), /^task_3{12}$/)
})
test('prefixes stay unique so ids cannot be confused across entities', () => {
const prefixes = Object.values(ID_PREFIXES)
assert.equal(new Set(prefixes).size, prefixes.length)
assert.deepEqual(prefixes.slice(0, 3), ['proj', 'bind', 'cfg'])
})
test('injected random source makes ids reproducible', () => {
const seq = (limit) => {
let index = 0
return () => index++ % limit
}
assert.equal(newId('project', { random: seq(36), length: 6 }), 'proj_012345')
const a = createIdFactory({ random: () => 1, length: 4 })
const b = createIdFactory({ random: () => 1, length: 4 })
for (const entity of ID_ENTITIES) {
assert.equal(a[entity](), b[entity]())
assert.match(a[entity](), new RegExp(`^${ID_PREFIXES[entity]}_`))
}
})
test('character alphabet values are accepted and unknown prefixes rejected', () => {
assert.equal(newId('result', { random: (i) => ['a', 'b', 'c', 'd'][i], length: 4 }), 'res_abcd')
assert.throws(() => newId('nope', { random: () => 0 }), /未知 ID 前缀/)
assert.throws(() => newId('task', { random: () => 'Z', length: 4 }), /字母表外/)
assert.throws(() => newId('task', { random: () => 1.5, length: 4 }), /整数/)
assert.throws(() => newId('task', { random: () => 0, length: 2 }), /4..64/)
assert.equal(isIdOf('task', 'dsp_abc'), false)
assert.equal(isIdOf('task', 'task_'), false)
assert.equal(isIdOf('task', undefined), false)
})
test('default crypto source produces distinct ids', () => {
if (typeof globalThis.crypto?.getRandomValues !== 'function') return
assert.match(cryptoRandom(), /^[0-9a-z]$/)
const ids = new Set(Array.from({ length: 50 }, () => newId('task')))
assert.ok(ids.size >= 45, '随机 ID 冲突率应很低')
})

View File

@ -0,0 +1,123 @@
import test from 'node:test'
import assert from 'node:assert/strict'
import {
LAYOUT_ORDER,
LEADERS,
MINISTRIES,
ROLE_IDS,
ROLE_NAMES,
ROLE_NAME_ALIASES,
ROLES,
canDispatch,
getRole,
initialSeats,
isRoleId,
layoutGroups,
requireRole,
} from '../core/roles.mjs'
test('ten seats keep the plan roleIds in the plan order', () => {
assert.deepEqual([...ROLE_IDS], ['lead', 'zhongshu', 'shangshu', 'menxia', 'libu', 'hubu', 'lipu', 'bingbu', 'xingbu', 'gongbu'])
assert.deepEqual(ROLES.map((seat) => seat.id), [...ROLE_IDS], '导出数组即布局顺序')
assert.equal(ROLES.length, 10)
// 吏部与礼部不可混用:名称、ID、位置都不同。
assert.equal(ROLE_NAMES.libu, '吏部')
assert.equal(ROLE_NAMES.lipu, '礼部')
})
test('seat names and duties match the plan table', () => {
const expected = {
lead: '丞相',
zhongshu: '中书',
shangshu: '尚书',
menxia: '门下',
libu: '吏部',
hubu: '户部',
lipu: '礼部',
bingbu: '兵部',
xingbu: '刑部',
gongbu: '工部',
}
for (const [id, name] of Object.entries(expected)) {
assert.equal(ROLE_NAMES[id], name)
assert.ok(getRole(id).duty.length > 0, `${id} 有职责描述`)
assert.ok(getRole(id).responsibility.length > 10, `${id} 有较完整职责说明`)
}
assert.equal(getRole('lead').duty, '接需求、分流、协调、汇报')
assert.equal(getRole('gongbu').duty, '代码实现与工程产出')
})
test('tiers split the chancellery from the six ministries', () => {
assert.deepEqual([...LEADERS], ['lead', 'zhongshu', 'shangshu', 'menxia'])
assert.deepEqual([...MINISTRIES], ['libu', 'hubu', 'lipu', 'bingbu', 'xingbu', 'gongbu'])
assert.equal(getRole('lead').tier, 'leaders')
assert.equal(getRole('shangshu').tier, 'leaders')
assert.equal(getRole('gongbu').tier, 'ministries')
})
test('layout is three columns with the chancellor centred on top', () => {
assert.deepEqual(
{ row: getRole('lead').row, column: getRole('lead').column },
{ row: 0, column: 'span' },
'丞相跨三列居中',
)
const sansheng = ['zhongshu', 'shangshu', 'menxia'].map((id) => getRole(id))
assert.deepEqual(sansheng.map((seat) => seat.column), ['left', 'center', 'right'])
assert.ok(sansheng.every((seat) => seat.row === 1))
// 六部两排:吏户礼 / 兵刑工
assert.deepEqual(
['libu', 'hubu', 'lipu'].map((id) => getRole(id).column),
['left', 'center', 'right'],
)
assert.deepEqual(
['bingbu', 'xingbu', 'gongbu'].map((id) => getRole(id).column),
['left', 'center', 'right'],
)
assert.ok(['libu', 'hubu', 'lipu'].every((id) => getRole(id).row === 2))
assert.ok(['bingbu', 'xingbu', 'gongbu'].every((id) => getRole(id).row === 3))
// 六部同属一个分组,连线不画成吏部下辖兵部。
assert.equal(new Set(MINISTRIES.map((id) => getRole(id).group)).size, 1)
})
test('layoutGroups renders three tiers without inventing parent links', () => {
assert.deepEqual(layoutGroups().lead, ['lead'])
assert.deepEqual(layoutGroups().sansheng, ['zhongshu', 'shangshu', 'menxia'])
assert.deepEqual(layoutGroups().ministries, [['libu', 'hubu', 'lipu'], ['bingbu', 'xingbu', 'gongbu']])
})
test('role lookups reject unknown ids and keep legacy name aliases', () => {
assert.equal(isRoleId('gongbu'), true)
assert.equal(isRoleId('xingbu'), true)
assert.equal(isRoleId('兵部'), false)
assert.equal(isRoleId(undefined), false)
assert.equal(getRole('unknown'), undefined)
assert.throws(() => requireRole('hufu'), /未知角色/)
assert.deepEqual([...ROLE_NAME_ALIASES.zhongshu], ['中书省'])
assert.equal(ROLE_NAME_ALIASES.libu, undefined, '吏部没有旧名别名,防止与礼部混淆')
})
test('only the chancellor and shangshu may dispatch by default', () => {
assert.equal(canDispatch('lead'), true)
assert.equal(canDispatch('shangshu'), true)
for (const id of ROLE_IDS.filter((role) => role !== 'lead' && role !== 'shangshu')) {
assert.equal(canDispatch(id), false, `${id} 不自主派工`)
}
})
test('initial seats describe configuration rows without creating sessions', () => {
const seats = initialSeats()
assert.equal(seats.length, 10)
assert.deepEqual(seats[0], { roleId: 'lead', name: '丞相', tier: 'leaders' })
assert.deepEqual(Object.keys(seats[0]).sort(), ['name', 'roleId', 'tier'])
})
test('LAYOUT_ORDER 是按布局排序的数组,可直接给 UI 渲染', () => {
assert.deepEqual(
[...LAYOUT_ORDER],
['lead', 'zhongshu', 'shangshu', 'menxia', 'libu', 'hubu', 'lipu', 'bingbu', 'xingbu', 'gongbu'],
)
assert.equal(LAYOUT_ORDER.length, ROLE_IDS.length)
// 每席的 row/column 沿数组单调排列,UI 直接按顺序铺即可
const rows = LAYOUT_ORDER.map((id) => getRole(id).row)
assert.deepEqual(rows, [...rows].sort((a, b) => a - b))
})

View File

@ -0,0 +1,555 @@
// 工作台 HTTP 路由测试:用假的 ctx / req / res 直接驱动 handler。
// 这里不启真服务器:路由层要验的是契约(方法、状态码、包装、上限、长轮询语义),
// 起服务器只会把测试变慢而不多验到东西。
//
// 长轮询只测“等待”这一侧的时序,所以 options 里把 longPollMs / pollIntervalMs 压到毫秒级;
// 25 秒是生产默认值,由 DEFAULT_LONG_POLL_MS 保证,这里断言常量本身而不是等它。
import test from 'node:test'
import assert from 'node:assert/strict'
import { Readable } from 'node:stream'
import { WorkbenchStore } from '../core/store.mjs'
import { createWorkbenchService } from '../host/service.mjs'
import {
MAX_BODY_BYTES,
ROUTE_PREFIX,
buildRouteTable,
listWorkbenchRoutes,
registerWorkbenchRoutes,
} from '../host/routes.mjs'
const FIXED_NOW = Date.parse('2026-11-09T12:00:00.000Z')
function makeService() {
let counter = 0
const random = () => Math.imul(counter++, 2654435761) >>> 0
const store = new WorkbenchStore({ file: null, clock: () => FIXED_NOW, random })
const service = createWorkbenchService({ store, clock: () => FIXED_NOW })
return { store, service }
}
/** 假 res:只记录 writeHead/end,够断言状态码、头与体。 */
function fakeRes() {
const res = {
statusCode: 0,
headers: {},
body: '',
writableEnded: false,
destroyed: false,
headersSent: false,
setHeader(name, value) {
this.headers[String(name).toLowerCase()] = value
return this
},
writeHead(status, headers) {
this.statusCode = status
for (const [name, value] of Object.entries(headers ?? {})) this.headers[String(name).toLowerCase()] = value
this.headersSent = true
return this
},
end(chunk) {
if (chunk !== undefined) this.body += String(chunk)
this.writableEnded = true
return this
},
get json() {
return this.body === '' ? null : JSON.parse(this.body)
},
}
return res
}
function fakeReq(method, url, body = undefined) {
const hasBody = body !== undefined
const text = hasBody === false ? '' : (typeof body === 'string' ? body : JSON.stringify(body))
const stream = Readable.from(hasBody ? [Buffer.from(text, 'utf8')] : [])
stream.method = method
stream.url = url
stream.headers = { 'content-type': 'application/json' }
return stream
}
/** 装一套路由,返回 { ctx, routes: Map<path, handler>, dispose, options }。 */
function mount(service, options = {}) {
const registered = new Map()
const disposed = []
const ctx = {
webServer: {
register(route) {
registered.set(route.path, route)
const off = () => disposed.push(route.path)
return off
},
},
}
const dispose = registerWorkbenchRoutes(ctx, service, { longPollMs: 30, pollIntervalMs: 5, ...options })
const call = async (method, url, body) => {
// 注册表按“不含查询串”的精确路径索引;带 ?since= 的调用要先把查询串切掉再查。
const path = url.search(/[?#]/) < 0 ? url : url.slice(0, url.search(/[?#]/))
const route = registered.get(path)
assert.ok(route !== undefined, `未注册路由: ${path}`)
assert.equal(route.kind, 'exact')
const res = fakeRes()
await route.handler(fakeReq(method, url, body), res)
return res
}
return { ctx, registered, disposed, dispose, call }
}
function seedService(service) {
const a = service.registerProject({ hostWorkspaceId: 'ws-a', displayNameCache: '项目A' }).project
const b = service.registerProject({ hostWorkspaceId: 'ws-b', displayNameCache: '项目B' }).project
service.bindDepartmentSession({ projectId: a.id, roleId: 'libu', sessionId: 'sess-a-libu' })
service.bindDepartmentSession({ projectId: b.id, roleId: 'libu', sessionId: 'sess-b-libu' })
return { a, b }
}
// ---------- 注册与降级 ----------
test('注册:十二条 exact 路由,dispose 幂等且能全部卸载', () => {
const { service } = makeService()
const { registered, disposed, dispose } = mount(service)
assert.deepEqual([...registered.keys()].sort(), [
`${ROUTE_PREFIX}/artifact/revision`,
`${ROUTE_PREFIX}/bind`,
`${ROUTE_PREFIX}/bootstrap`,
`${ROUTE_PREFIX}/config`,
`${ROUTE_PREFIX}/connect`,
`${ROUTE_PREFIX}/dispatch`,
`${ROUTE_PREFIX}/events`,
`${ROUTE_PREFIX}/ingest`,
`${ROUTE_PREFIX}/project`,
`${ROUTE_PREFIX}/result`,
`${ROUTE_PREFIX}/task`,
`${ROUTE_PREFIX}/task/cancel`,
])
assert.equal(dispose.registered, true)
assert.equal(dispose.paths.length, 12)
dispose()
dispose()
assert.equal(disposed.length, 12, '十二条路由各卸载一次,重复调用不再卸载')
})
test('注册:宿主没有 webServer 时降级为 no-op,不抛', () => {
const { service } = makeService()
for (const ctx of [undefined, null, {}, { webServer: {} }, { webServer: { register: 1 } }]) {
const dispose = registerWorkbenchRoutes(ctx, service, {})
assert.equal(typeof dispose, 'function')
assert.equal(dispose.registered, false)
assert.match(dispose.reason, /webServer/)
dispose()
}
})
test('注册:中途失败会回滚已注册的路由', () => {
const { service } = makeService()
let calls = 0
const offs = []
const ctx = {
webServer: {
register() {
calls += 1
if (calls === 3) throw new Error('宿主拒绝注册')
const off = () => offs.push(calls)
return off
},
},
}
assert.throws(() => registerWorkbenchRoutes(ctx, service, {}), /宿主拒绝注册/)
assert.equal(offs.length, 2, '两条已注册的回滚')
})
test('listWorkbenchRoutes 列出端点与方法', () => {
const rows = listWorkbenchRoutes()
assert.equal(rows.length, 12)
assert.deepEqual(rows.find((row) => row.path.endsWith('/bootstrap')), {
path: `${ROUTE_PREFIX}/bootstrap`,
method: 'GET',
})
assert.equal(rows.filter((row) => row.method === 'GET').length, 2)
})
// ---------- 方法与包装 ----------
test('方法:POST 路由被 GET 调用返回 405 且带 Allow', async () => {
const { service } = makeService()
const { call } = mount(service)
for (const path of Object.keys(buildRouteTable(service, {}))) {
if (path.endsWith('/bootstrap') || path.endsWith('/events')) continue
const res = await call('GET', path)
assert.equal(res.statusCode, 405, `${path} 应 405`)
assert.equal(res.headers.allow, 'POST')
assert.equal(res.json.ok, false)
assert.equal(res.json.error.code, 'METHOD_NOT_ALLOWED')
}
})
test('方法:GET 路由被 POST 调用返回 405 且带 Allow', async () => {
const { service } = makeService()
const { call } = mount(service)
for (const path of [`${ROUTE_PREFIX}/bootstrap`, `${ROUTE_PREFIX}/events`]) {
const res = await call('POST', path, {})
assert.equal(res.statusCode, 405)
assert.equal(res.headers.allow, 'GET')
}
})
test('方法:PUT/DELETE 一律 405', async () => {
const { service } = makeService()
const { call } = mount(service)
for (const method of ['PUT', 'DELETE', 'PATCH']) {
const res = await call(method, `${ROUTE_PREFIX}/task`, { projectId: 'proj_x' })
assert.equal(res.statusCode, 405, `${method} 应 405`)
}
})
test('响应头:JSON + charset、no-store、Content-Length 与实际字节一致', async () => {
const { service } = makeService()
const { call } = mount(service)
const res = await call('POST', `${ROUTE_PREFIX}/project`, { hostWorkspaceId: 'ws-a', displayNameCache: '中文项目' })
assert.equal(res.statusCode, 200)
assert.equal(res.headers['content-type'], 'application/json; charset=utf-8')
assert.equal(res.headers['cache-control'], 'no-store')
assert.equal(res.headers['content-length'], Buffer.byteLength(res.body))
assert.equal(res.json.ok, true)
assert.ok(res.json.value.project.id.startsWith('proj_'))
})
test('未实现路径:不在表里就没有路由,表本身不含其它前缀', () => {
const { service } = makeService()
const table = buildRouteTable(service, {})
assert.equal(Object.keys(table).some((path) => path === `${ROUTE_PREFIX}/unknown`), false)
assert.equal(Object.keys(table).every((path) => path.startsWith(`${ROUTE_PREFIX}/`)), true)
// 前缀只登记 exact:绝不允许 kind='prefix' 把整棵子树交给某个 handler。
const { registered } = mount(service)
for (const route of registered.values()) assert.equal(route.kind, 'exact')
})
// ---------- 请求体 ----------
test('请求体:非法 JSON 返回 400 INVALID_INPUT', async () => {
const { service } = makeService()
const { call } = mount(service)
const res = await call('POST', `${ROUTE_PREFIX}/project`, '{这不是 JSON')
assert.equal(res.statusCode, 400)
assert.equal(res.json.ok, false)
assert.equal(res.json.error.code, 'INVALID_INPUT')
})
test('请求体:JSON 数组 / null / 标量都拒绝', async () => {
const { service } = makeService()
const { call } = mount(service)
for (const raw of ['[]', 'null', '42', '"字符串"']) {
const res = await call('POST', `${ROUTE_PREFIX}/project`, raw)
assert.equal(res.statusCode, 400, `${raw} 应 400`)
assert.equal(res.json.error.code, 'INVALID_INPUT')
}
})
test('请求体:空体按 {} 处理,交给服务层报缺参', async () => {
const { service } = makeService()
const { call } = mount(service)
const res = await call('POST', `${ROUTE_PREFIX}/task`, undefined)
assert.equal(res.statusCode, 400)
// 路由层不替业务决定“先报哪个缺参”:服务层先校验角色,所以这里是 INVALID_ROLE。
assert.equal(res.json.error.code, 'INVALID_ROLE')
assert.equal(res.json.error.details.field, 'ownerRoleId')
})
test('请求体:超过 256 KB 返回 413', async () => {
const { service } = makeService()
const { call } = mount(service)
const big = JSON.stringify({ projectId: 'proj_x', pad: 'x'.repeat(MAX_BODY_BYTES) })
assert.ok(Buffer.byteLength(big) > MAX_BODY_BYTES)
const res = await call('POST', `${ROUTE_PREFIX}/task`, big)
assert.equal(res.statusCode, 413)
assert.equal(res.json.ok, false)
assert.equal(res.json.error.code, 'INVALID_INPUT')
assert.equal(res.json.error.details.limit, MAX_BODY_BYTES)
})
test('请求体:刚好等于上限不拦,超过上限 1 字节就拦', async () => {
const { service } = makeService()
const { call } = mount(service, { maxBodyBytes: 64 })
const okBody = JSON.stringify({ pad: 'y'.repeat(64 - '{"pad":""}'.length) })
assert.equal(Buffer.byteLength(okBody), 64)
const ok = await call('POST', `${ROUTE_PREFIX}/project`, okBody)
assert.equal(ok.statusCode, 400, '体本身合法,但缺 hostWorkspaceId → 业务 400,不是 413')
assert.notEqual(ok.statusCode, 413)
const over = JSON.stringify({ pad: 'y'.repeat(65 - '{"pad":""}'.length) })
assert.equal(Buffer.byteLength(over), 65)
const res = await call('POST', `${ROUTE_PREFIX}/project`, over)
assert.equal(res.statusCode, 413)
})
// ---------- 业务错误映射 ----------
test('错误映射:NOT_FOUND→404、CROSS_PROJECT→409、CONFIG_CONFLICT→409', async () => {
const { service } = makeService()
const { call } = mount(service)
const { a, b } = seedService(service)
const missing = await call('POST', `${ROUTE_PREFIX}/task/cancel`, { projectId: a.id, taskId: 'task_notexist001' })
assert.equal(missing.statusCode, 404)
assert.equal(missing.json.error.code, 'NOT_FOUND')
const task = service.createTask({ projectId: a.id, title: '甲', objective: '甲', ownerRoleId: 'libu' }).task
const cross = await call('POST', `${ROUTE_PREFIX}/task/cancel`, { projectId: b.id, taskId: task.id })
assert.equal(cross.statusCode, 409)
assert.equal(cross.json.error.code, 'CROSS_PROJECT')
assert.equal(cross.body.includes(a.id), false, '不得回显另一个项目的真实 ID')
const config = await call('POST', `${ROUTE_PREFIX}/config`, {
projectId: a.id,
roleId: 'libu',
provider: 'anthropic',
model: 'claude',
expectedRevision: 7,
})
assert.equal(config.statusCode, 409)
assert.equal(config.json.error.code, 'CONFIG_CONFLICT')
assert.equal(config.json.error.details.currentRevision, 0)
})
test('错误:details 原样透出(CAS 冲突带回当前值)', async () => {
const { service } = makeService()
const { call } = mount(service)
const { a } = seedService(service)
const saved = service.saveDepartmentConfig({
projectId: a.id,
roleId: 'libu',
provider: 'anthropic',
model: 'claude-sonnet',
reasoningEffort: 'high',
expectedRevision: 0,
})
const res = await call('POST', `${ROUTE_PREFIX}/config`, {
projectId: a.id,
roleId: 'libu',
provider: 'openai',
model: 'gpt',
expectedRevision: saved.config.configRevision,
})
assert.equal(res.statusCode, 200)
assert.equal(res.json.value.config.model, 'gpt')
})
test('错误:未知 roleId → 400 INVALID_ROLE', async () => {
const { service } = makeService()
const { call } = mount(service)
const { a } = seedService(service)
const res = await call('POST', `${ROUTE_PREFIX}/bind`, { projectId: a.id, roleId: 'libbu', sessionId: 'sess-x' })
assert.equal(res.statusCode, 400)
assert.equal(res.json.error.code, 'INVALID_ROLE')
})
// ---------- 成功路径 ----------
test('bootstrap:一次拿全,且只含选中项目', async () => {
const { service } = makeService()
const { call } = mount(service)
const { a, b } = seedService(service)
service.createTask({ projectId: a.id, title: '甲', objective: '甲', ownerRoleId: 'libu' })
service.createTask({ projectId: b.id, title: '乙', objective: '乙', ownerRoleId: 'libu' })
const res = await call('GET', `${ROUTE_PREFIX}/bootstrap?projectId=${encodeURIComponent(a.id)}`)
assert.equal(res.statusCode, 200)
const value = res.json.value
assert.equal(value.projectId, a.id)
assert.equal(value.projects.length, 2, '项目列表含全部项目(切换器要用)')
assert.equal(value.seats.length, 10)
assert.deepEqual(value.tasks.map((task) => task.title), ['甲'])
// 布局只给角色 ID:前端按 ROLES 拿名字,避免同一份数据两处维护。
assert.deepEqual(value.layout.lead, ['lead'])
})
test('bootstrap:不传 projectId 时选中第一个项目', async () => {
const { service } = makeService()
const { call } = mount(service)
const { a } = seedService(service)
const res = await call('GET', `${ROUTE_PREFIX}/bootstrap`)
assert.equal(res.statusCode, 200)
assert.equal(res.json.value.projectId, a.id)
})
test('bootstrap:伪造 projectId 返回 404,不泄露存在性', async () => {
const { service } = makeService()
const { call } = mount(service)
const { b } = seedService(service)
const res = await call('GET', `${ROUTE_PREFIX}/bootstrap?projectId=proj_zzzzzzzzzzzz`)
assert.equal(res.statusCode, 404)
assert.equal(res.json.error.code, 'NOT_FOUND')
assert.equal(res.body.includes(b.id), false)
})
test('project / bind / config / task 四个 POST 串起来走通', async () => {
const { service } = makeService()
const { call } = mount(service)
const created = await call('POST', `${ROUTE_PREFIX}/project`, { hostWorkspaceId: 'ws-z', displayNameCache: '项目Z' })
const projectId = created.json.value.project.id
const bound = await call('POST', `${ROUTE_PREFIX}/bind`, { projectId, roleId: 'libu', sessionId: 'sess-z' })
assert.equal(bound.statusCode, 200)
assert.equal(bound.json.value.seat.connected, true)
const configured = await call('POST', `${ROUTE_PREFIX}/config`, {
projectId,
roleId: 'libu',
provider: 'anthropic',
model: 'claude',
reasoningEffort: 'medium',
expectedRevision: 0,
})
assert.equal(configured.statusCode, 200)
assert.equal(configured.json.value.config.reasoningEffort, 'medium')
const task = await call('POST', `${ROUTE_PREFIX}/task`, {
projectId,
title: '写一份摘要',
objective: '摘要',
ownerRoleId: 'libu',
})
assert.equal(task.statusCode, 200)
assert.equal(task.json.value.task.status, 'queued')
})
test('dispatch / result / task/cancel 走通并返回去重信息', async () => {
const { service } = makeService()
const { call } = mount(service)
const { a } = seedService(service)
const task = service.createTask({ projectId: a.id, title: '甲', objective: '甲', ownerRoleId: 'libu' }).task
const first = await call('POST', `${ROUTE_PREFIX}/dispatch`, {
projectId: a.id,
taskId: task.id,
idempotencyKey: 'route-key-1',
packet: { excerpts: ['需求'] },
})
assert.equal(first.statusCode, 200)
assert.equal(first.json.value.duplicate, false)
const again = await call('POST', `${ROUTE_PREFIX}/dispatch`, {
projectId: a.id,
taskId: task.id,
idempotencyKey: 'route-key-1',
})
assert.equal(again.json.value.duplicate, true)
assert.equal(again.json.value.dispatch.id, first.json.value.dispatch.id)
const started = service.startAttempt({ projectId: a.id, attemptId: first.json.value.attempt.id })
const result = await call('POST', `${ROUTE_PREFIX}/result`, {
projectId: a.id,
taskId: task.id,
attemptId: started.attempt.id,
report: { summary: '做完了', checks: [] },
runTerminal: 'succeeded',
})
assert.equal(result.statusCode, 200)
assert.equal(result.json.value.task.status, 'completed')
const other = service.createTask({ projectId: a.id, title: '乙', objective: '乙', ownerRoleId: 'libu' }).task
const cancelled = await call('POST', `${ROUTE_PREFIX}/task/cancel`, { projectId: a.id, taskId: other.id, reason: '不做了' })
assert.equal(cancelled.statusCode, 200)
assert.equal(cancelled.json.value.task.status, 'cancelled')
})
// ---------- 事件 ----------
test('events:since 之后只给新事件,游标可重放(多标签页共用一条日志)', async () => {
const { service } = makeService()
const { call } = mount(service)
const { a } = seedService(service)
const head = await call('GET', `${ROUTE_PREFIX}/events?projectId=${encodeURIComponent(a.id)}&since=0&wait=0`)
assert.equal(head.statusCode, 200)
const cursor = head.json.value.seq
assert.ok(cursor >= 1)
// since=0 会补齐历史(建项目/绑定的那些事件),游标之后的才算“新”。
for (const event of head.json.value.events) assert.ok(event.seq <= cursor)
const task = service.createTask({ projectId: a.id, title: '甲', objective: '甲', ownerRoleId: 'libu' }).task
const after = await call('GET', `${ROUTE_PREFIX}/events?projectId=${encodeURIComponent(a.id)}&since=${cursor}&wait=0`)
assert.ok(after.json.value.events.length >= 1)
for (const event of after.json.value.events) {
assert.ok(event.seq > cursor, '只返回 since 之后的事件')
assert.equal(event.projectId, a.id)
}
// 重放同一个 since 必须拿到同一批事件:事件日志是只读游标,不是"读一次就消失"的队列,
// 否则开两个标签页就会互相偷事件。
const replay = await call('GET', `${ROUTE_PREFIX}/events?projectId=${encodeURIComponent(a.id)}&since=${cursor}&wait=0`)
assert.deepEqual(
replay.json.value.events.map((event) => event.eventId),
after.json.value.events.map((event) => event.eventId),
)
assert.ok(task.id.startsWith('task_'))
})
test('events:since 越界(大于当前 seq)返回 reset 让前端整体重拉', async () => {
const { service } = makeService()
const { call } = mount(service)
const { a } = seedService(service)
const res = await call('GET', `${ROUTE_PREFIX}/events?projectId=${encodeURIComponent(a.id)}&since=999999&wait=0`)
assert.equal(res.statusCode, 200)
assert.equal(res.json.value.reset, true)
assert.equal(res.json.value.events.length, 0)
})
test('events:since 不是数字 → 400', async () => {
const { service } = makeService()
const { call } = mount(service)
const res = await call('GET', `${ROUTE_PREFIX}/events?since=abc&wait=0`)
assert.equal(res.statusCode, 400)
assert.equal(res.json.error.code, 'INVALID_INPUT')
})
test('events:长轮询等到新事件立刻返回,不等满窗口', async () => {
const { service } = makeService()
const { call } = mount(service, { longPollMs: 5_000, pollIntervalMs: 5 })
const { a } = seedService(service)
const head = await call('GET', `${ROUTE_PREFIX}/events?projectId=${encodeURIComponent(a.id)}&since=0&wait=0`)
const cursor = head.json.value.seq
const startedAt = Date.now()
const pending = call('GET', `${ROUTE_PREFIX}/events?projectId=${encodeURIComponent(a.id)}&since=${cursor}`)
await new Promise((resolve) => setTimeout(resolve, 20))
service.createTask({ projectId: a.id, title: '甲', objective: '甲', ownerRoleId: 'libu' })
const res = await pending
const elapsed = Date.now() - startedAt
assert.equal(res.statusCode, 200)
assert.ok(res.json.value.events.length >= 1, '有新事件就返回')
assert.ok(elapsed < 2_000, `应在窗口耗尽前返回,实际 ${elapsed}ms`)
})
test('events:没有新事件时挂满窗口后返回空列表 + 当前 seq', async () => {
const { service } = makeService()
const { call } = mount(service, { longPollMs: 40, pollIntervalMs: 5 })
const { a } = seedService(service)
const head = await call('GET', `${ROUTE_PREFIX}/events?projectId=${encodeURIComponent(a.id)}&since=0&wait=0`)
const cursor = head.json.value.seq
const startedAt = Date.now()
const res = await call('GET', `${ROUTE_PREFIX}/events?projectId=${encodeURIComponent(a.id)}&since=${cursor}`)
const elapsed = Date.now() - startedAt
assert.equal(res.statusCode, 200)
assert.deepEqual(res.json.value.events, [])
assert.equal(res.json.value.seq, cursor)
assert.ok(elapsed >= 35, `应至少挂到窗口尾,实际 ${elapsed}ms`)
})
test('events:longPollMs=0 时退化为立即返回', async () => {
const { service } = makeService()
const { call } = mount(service, { longPollMs: 0 })
const { a } = seedService(service)
const startedAt = Date.now()
const res = await call('GET', `${ROUTE_PREFIX}/events?projectId=${encodeURIComponent(a.id)}&since=0`)
assert.equal(res.statusCode, 200)
assert.ok(Date.now() - startedAt < 500)
})
test('events:伪造 projectId 返回 404', async () => {
const { service } = makeService()
const { call } = mount(service)
seedService(service)
const res = await call('GET', `${ROUTE_PREFIX}/events?projectId=proj_zzzzzzzzzzzz&since=0&wait=0`)
assert.equal(res.statusCode, 404)
assert.equal(res.json.error.code, 'NOT_FOUND')
})

View File

@ -0,0 +1,656 @@
// Host 侧业务服务测试:项目隔离、CAS、幂等派发、结果去重、完成判定三分支。
// 全部用真实 WorkbenchStore(内存账本),不 mock 数据层——幂等与状态机就在那一层,
// 换成假 store 会把要验的东西验掉。
import testDefault from 'node:test'
import assert from 'node:assert/strict'
import { WorkbenchStore } from '../core/store.mjs'
import { createWorkbenchService, ServiceError } from '../host/service.mjs'
const FIXED_NOW = Date.parse('2026-11-09T12:00:00.000Z')
/**
* 固定时钟 + 可复现随机源:ID 可复现且互不相同,便于断言“只生成了一条”。
* 种子来自当前用例名,这样每个用例都从同一条 ID 序列开头跑:
* 不会因为别的用例多写了几条记录,就把这里的 ID 推到别处去。
*/
function makeService(seed = 'default') {
// 单调递增计数器 + 奇数乘法打散:每次 pick 都取一个新的 32 位整数。
// 直接返回 counter++ 会和字母表长度 36 同周期(12 位 ID 每 36 步就重演同一串,
// 于是「同一次运行里先建任务甲、再建任务乙」可能拿到同一个 ID);
// 乘一个奇数再取 32 位无符号,保证整数性、单调可复现,且不落在 36 的周期上。
let counter = hashSeed(seed)
const random = () => Math.imul(counter++, 2654435761) >>> 0
const store = new WorkbenchStore({
file: null,
clock: () => FIXED_NOW,
random,
})
const service = createWorkbenchService({ store, clock: () => FIXED_NOW })
return { store, service }
}
/** 当前用例名:随机种子取自它,保证每个用例的 ID 序列彼此独立。 */
let currentTest = 'seed'
/** 包一层 node:test:进入用例时记下名字,供 makeService 取种子。 */
function test(name, fn) {
return testDefault(name, (t) => {
currentTest = name
return fn(t)
})
}
/** 把用例名里的 ID 前缀说明清掉,只留可哈希的字符。 */
function seedOfCurrent() {
return currentTest
}
function hashSeed(text) {
let hash = 2166136261
for (let index = 0; index < text.length; index += 1) {
hash ^= text.charCodeAt(index)
hash = Math.imul(hash, 16777619)
}
return Math.abs(hash) % 100000
}
/** 建两个项目,各自把一个部门接通,返回常用 ID。 */
function seed() {
const { store, service } = makeService(seedOfCurrent())
const a = service.registerProject({ hostWorkspaceId: 'ws-a', displayNameCache: '项目A' }).project
const b = service.registerProject({ hostWorkspaceId: 'ws-b', displayNameCache: '项目B' }).project
service.bindDepartmentSession({ projectId: a.id, roleId: 'libu', sessionId: 'sess-a-libu' })
service.bindDepartmentSession({ projectId: b.id, roleId: 'libu', sessionId: 'sess-b-libu' })
return { store, service, a, b }
}
function expectCode(fn, code) {
let caught = null
try {
fn()
} catch (error) {
caught = error
}
assert.ok(caught !== null, `期望抛出 ${code},实际没抛`)
assert.ok(caught instanceof ServiceError, `期望 ServiceError,实际 ${caught?.name}`)
assert.equal(caught.code, code, `错误码不符:${caught.code} / ${caught.message}`)
return caught
}
// ---------- 项目 ----------
test('registerProject 同一工作区只建一个项目', () => {
const { service } = makeService(seedOfCurrent())
const first = service.registerProject({ hostWorkspaceId: 'ws-a', displayNameCache: '甲' })
assert.equal(first.duplicate, false)
const again = service.registerProject({ hostWorkspaceId: 'ws-a', displayNameCache: '甲改名' })
assert.equal(again.duplicate, true)
assert.equal(again.project.id, first.project.id, '重复登记不换 projectId')
assert.equal(again.project.displayNameCache, '甲改名', '名称可更新')
assert.equal(service.listProjects().length, 1)
assert.equal(service.listProjects()[0].seatCount, 10)
})
test('listSeats 十席布局:未接通时 pending,接通后 connected', () => {
const { service, a } = seed()
const seats = service.listSeats(a.id)
assert.equal(seats.length, 10)
assert.deepEqual(seats.map((seat) => seat.roleId), [
'lead', 'zhongshu', 'shangshu', 'menxia', 'libu', 'hubu', 'lipu', 'bingbu', 'xingbu', 'gongbu',
])
const libu = seats.find((seat) => seat.roleId === 'libu')
assert.equal(libu.connected, true)
assert.equal(libu.pending, false)
assert.equal(libu.binding.currentSessionId, 'sess-a-libu')
assert.equal(libu.binding.bindingGeneration, 1)
const hubu = seats.find((seat) => seat.roleId === 'hubu')
assert.equal(hubu.connected, false)
assert.equal(hubu.pending, true)
assert.equal(hubu.pendingLabel, '尚未接通')
// 只暴露 provider/model 名字,不含任何凭据字段
for (const seat of seats) {
assert.deepEqual(Object.keys(seat.config).sort(), ['configRevision', 'configured', 'model', 'provider', 'reasoningEffort'])
}
assert.equal(service.layout().ministries.length, 2)
})
// ---------- 项目隔离 ----------
test('项目隔离:A 的 taskId 在 B 上被拒为 CROSS_PROJECT', () => {
const { service, a, b } = seed()
const task = service.createTask({ projectId: a.id, title: '甲任务', objective: '做甲事', ownerRoleId: 'libu' }).task
expectCode(() => service.getTask(b.id, task.id), 'CROSS_PROJECT')
expectCode(() => service.cancelTask({ projectId: b.id, taskId: task.id }), 'CROSS_PROJECT')
expectCode(() => service.dispatchTask({
projectId: b.id,
taskId: task.id,
idempotencyKey: 'k1',
}), 'CROSS_PROJECT')
expectCode(() => service.requestTaskInput({ projectId: b.id, taskId: task.id, reason: '要资料' }), 'CROSS_PROJECT')
})
test('项目隔离:伪造/不存在的 ID 一律 NOT_FOUND,且不泄露归属', () => {
const { service, a } = seed()
// 形状合法但不存在
const fakeTask = expectCode(() => service.getTask(a.id, 'task_doesnotexist'), 'NOT_FOUND')
assert.ok(!JSON.stringify(fakeTask).includes('proj_'), '错误里不带任何项目 ID')
// 形状非法
expectCode(() => service.getTask(a.id, 'not-a-task-id'), 'NOT_FOUND')
// 不存在的项目
expectCode(() => service.listSeats('proj_ghost'), 'NOT_FOUND')
expectCode(() => service.registerProject({ hostWorkspaceId: '' }), 'INVALID_INPUT')
// 项目 A 的会话绑不到项目 B 之外的地方时不会串项目
const conflict = expectCode(() => service.bindDepartmentSession({
projectId: a.id,
roleId: 'hubu',
sessionId: 'sess-b-libu',
}), 'SESSION_CONFLICT')
assert.equal(conflict.details.heldBy.projectId, b_idOf(service), 'heldBy 指向真实持有者,便于 UI 解释')
})
/** 找项目 B 的 id(测试里只为了断言 heldBy,不参与业务)。 */
function b_idOf(service) {
return service.listProjects().find((row) => row.hostWorkspaceId === 'ws-b').id
}
test('项目隔离:跨项目成果引用与尝试引用被拒', () => {
const { store, service, a, b } = seed()
const taskA = service.createTask({ projectId: a.id, title: '甲', objective: '甲目标', ownerRoleId: 'libu' }).task
const taskB = service.createTask({ projectId: b.id, title: '乙', objective: '乙目标', ownerRoleId: 'libu' }).task
const artB = service.registerArtifact({ projectId: b.id, taskId: taskB.id, displayName: '乙成果' }).artifact
const dispatched = service.dispatchTask({ projectId: a.id, taskId: taskA.id, idempotencyKey: 'd-a' })
// 用 B 的成果引用给 A 的任务交报告:拒绝
const err = expectCode(() => service.reportTaskResult({
projectId: a.id,
taskId: taskA.id,
attemptId: dispatched.attempt.id,
report: { summary: '做完了', artifactRefs: [artB.id] },
runTerminal: 'succeeded',
}), 'CROSS_PROJECT')
assert.ok(!JSON.stringify(err).includes(taskB.id), '不泄露另一项目的任务 ID')
// 用 B 的尝试给 A 的任务报结果:CROSS_PROJECT
assert.ok(store.getTask(taskB.id) !== undefined)
})
test('项目隔离:另一项目的 attemptId 报结果被拒', () => {
const { service, a, b } = seed()
const taskA = service.createTask({ projectId: a.id, title: '甲', objective: '甲', ownerRoleId: 'libu' }).task
const taskB = service.createTask({ projectId: b.id, title: '乙', objective: '乙', ownerRoleId: 'libu' }).task
const dispB = service.dispatchTask({ projectId: b.id, taskId: taskB.id, idempotencyKey: 'kb' })
expectCode(() => service.reportTaskResult({
projectId: a.id,
taskId: taskA.id,
attemptId: dispB.attempt.id,
report: { summary: '串了' },
runTerminal: 'succeeded',
}), 'CROSS_PROJECT')
})
// ---------- 配置 CAS ----------
test('saveDepartmentConfig 走 CAS:旧 revision 冲突并带回当前值', () => {
const { service, a } = seed()
const first = service.saveDepartmentConfig({
projectId: a.id,
roleId: 'libu',
provider: 'deepseek',
model: 'v4',
reasoningEffort: 'high',
expectedRevision: 0,
})
assert.equal(first.configRevision, 1)
const conflict = expectCode(() => service.saveDepartmentConfig({
projectId: a.id,
roleId: 'libu',
provider: 'openai',
model: 'gpt',
expectedRevision: 0,
}), 'CONFIG_CONFLICT')
assert.equal(conflict.details.expectedRevision, 0)
assert.equal(conflict.details.currentRevision, 1)
assert.deepEqual(conflict.details.current, { provider: 'deepseek', model: 'v4', reasoningEffort: 'high' })
// 读回新 revision 后可以成功
const ok = service.saveDepartmentConfig({
projectId: a.id,
roleId: 'libu',
provider: 'openai',
model: 'gpt',
expectedRevision: conflict.details.currentRevision,
})
assert.equal(ok.configRevision, 2)
expectCode(() => service.saveDepartmentConfig({
projectId: a.id,
roleId: 'libu',
provider: 'x',
model: 'y',
expectedRevision: '1',
}), 'INVALID_INPUT')
})
test('绑定:同一会话被别处持有 → SESSION_CONFLICT;换绑需 allowReplace', () => {
const { service, a } = seed()
const bound = service.bindDepartmentSession({ projectId: a.id, roleId: 'hubu', sessionId: 'sess-hubu-1' })
assert.equal(bound.seat.connected, true)
const conflict = expectCode(() => service.bindDepartmentSession({
projectId: a.id,
roleId: 'hubu',
sessionId: 'sess-hubu-2',
}), 'SESSION_CONFLICT')
assert.equal(conflict.details.currentSessionId, 'sess-hubu-1')
const replaced = service.bindDepartmentSession({
projectId: a.id,
roleId: 'hubu',
sessionId: 'sess-hubu-2',
allowReplace: true,
})
assert.equal(replaced.binding.bindingGeneration, 2)
assert.equal(replaced.binding.historySessionRefs.length, 1, '旧会话进历史,不删除')
})
// ---------- 派发 ----------
test('dispatchTask 写 dispatch+contextPacket+attempt,同幂等键只一条', () => {
const { store, service, a } = seed()
const task = service.createTask({ projectId: a.id, title: '甲', objective: '甲目标', ownerRoleId: 'libu' }).task
const first = service.dispatchTask({
projectId: a.id,
taskId: task.id,
idempotencyKey: 'idem-1',
packet: { excerpts: ['原始需求'], expectedOutputs: ['报告'] },
})
assert.equal(first.duplicate, false)
assert.equal(first.dispatch.status, 'prepared')
assert.equal(first.attempt.state, 'queued')
assert.equal(first.attempt.sessionId, 'sess-a-libu')
assert.equal(first.attempt.effectiveConfigSnapshot.provider, null)
assert.equal(first.contextPacket.version, 1)
assert.deepEqual(first.contextPacket.excerpts, ['原始需求'])
const again = service.dispatchTask({ projectId: a.id, taskId: task.id, idempotencyKey: 'idem-1' })
assert.equal(again.duplicate, true)
assert.equal(again.dispatch.id, first.dispatch.id, '幂等命中返回原派发')
assert.equal(again.attempt.id, first.attempt.id)
assert.equal(store.state.dispatches.size, 1, '账本里只有一条派发')
assert.equal(store.state.attempts.size, 1, '也为幂等,只有一条尝试')
// 换个键:新派发,上下文包版本递增
const second = service.dispatchTask({ projectId: a.id, taskId: task.id, idempotencyKey: 'idem-2' })
assert.equal(second.duplicate, false)
assert.equal(second.contextPacket.version, 2)
assert.equal(store.state.dispatches.size, 2)
})
test('dispatchTask:未接通、已终态、目标与主责不一致都拒绝', () => {
const { service, a } = seed()
// 未接通会话的部门不能直接入队(默认 queued),只能先存草稿
expectCode(() => service.createTask({ projectId: a.id, title: '丙', objective: '丙', ownerRoleId: 'hubu' }), 'INVALID_STATE')
const task = service.createTask({ projectId: a.id, title: '甲', objective: '甲', ownerRoleId: 'hubu', status: 'draft' }).task
expectCode(() => service.dispatchTask({ projectId: a.id, taskId: task.id, idempotencyKey: 'k' }), 'INVALID_STATE')
const queued = service.createTask({ projectId: a.id, title: '乙', objective: '乙', ownerRoleId: 'libu' }).task
expectCode(() => service.dispatchTask({
projectId: a.id,
taskId: queued.id,
idempotencyKey: 'k2',
targetRoleId: 'hubu',
}), 'DISPATCH_INVALID')
// 换绑后旧 bindingGeneration 派发失败
const first = service.bindDepartmentSession({ projectId: a.id, roleId: 'hubu', sessionId: 'sess-hubu' })
const fresh = service.createTask({ projectId: a.id, title: '丁', objective: '丁', ownerRoleId: 'hubu' }).task
service.bindDepartmentSession({ projectId: a.id, roleId: 'hubu', sessionId: 'sess-hubu-2', allowReplace: true })
const staleGeneration = first.binding.bindingGeneration
expectCode(() => service.dispatchTask({
projectId: a.id,
taskId: fresh.id,
idempotencyKey: 'k3',
bindingGeneration: staleGeneration,
}), 'SESSION_CONFLICT')
})
// ---------- 结果与完成判定 ----------
/** 建任务 → 派发 → 让任务进入 running,返回三件套。 */
function runningTask(ctx, projectId = ctx.a.id) {
const task = ctx.service.createTask({ projectId, title: '任务', objective: '目标', ownerRoleId: 'libu' }).task
const dispatched = ctx.service.dispatchTask({ projectId, taskId: task.id, idempotencyKey: `key-${task.id}` })
const started = ctx.service.startAttempt({
projectId,
taskId: task.id,
attemptId: dispatched.attempt.id,
hostRunId: 'run-1',
})
return { task: started.task, attempt: dispatched.attempt, dispatch: dispatched.dispatch }
}
test('完成判定分支一:报告+终态成功+成果有效 → completed', () => {
const ctx = seed()
const { task, attempt } = runningTask(ctx)
const artifact = ctx.service.registerArtifact({ projectId: ctx.a.id, taskId: task.id, displayName: 'report.md' }).artifact
const out = ctx.service.reportTaskResult({
projectId: ctx.a.id,
taskId: task.id,
attemptId: attempt.id,
report: { summary: '已完成分析', artifactRefs: [artifact.id], checks: [{ name: '自检', ok: true }] },
runTerminal: 'succeeded',
sourceMessageRef: 'msg-1',
})
assert.equal(out.duplicate, false)
assert.equal(out.decision.applied, true)
assert.equal(out.decision.status, 'completed')
assert.equal(out.task.status, 'completed')
assert.ok(out.task.reportReceivedAt !== null)
assert.ok(out.task.endedAt !== null)
})
test('完成判定分支二:终态成功但报告不可信 → needs_attention', () => {
const ctx = seed()
const { task, attempt } = runningTask(ctx)
const out = ctx.service.reportTaskResult({
projectId: ctx.a.id,
taskId: task.id,
attemptId: attempt.id,
report: { summary: '看起来完成了', blockedReason: '缺少关键数据' },
runTerminal: 'succeeded',
})
assert.equal(out.decision.status, 'needs_attention')
assert.equal(out.task.status, 'needs_attention')
assert.match(out.task.needsAttentionReason, /有效/)
// needs_attention 不是完成:没有 completed 时间
assert.equal(out.task.endedAt, null)
})
test('完成判定分支三:报告先到、宿主未结束 → 登记但不完成,终态后补齐', () => {
const ctx = seed()
const { task, attempt } = runningTask(ctx)
const first = ctx.service.reportTaskResult({
projectId: ctx.a.id,
taskId: task.id,
attemptId: attempt.id,
report: { summary: '分析完成,等运行收尾' },
runTerminal: 'running',
})
// 报告本身写进了账(status 不是 completed 就是证据),但任务没被判完成
assert.equal(first.decision.status, 'running', '运行未结束不判完成')
assert.equal(first.task.status, 'running')
assert.ok(first.task.reportReceivedAt !== null, '报告先到时先登记报告时间(候选)')
assert.ok(first.result.id.startsWith('res_'), '结果已登记为候选')
// 终态后到:reportRunTerminal 把它推进到 completed
const second = ctx.service.reportRunTerminal({ projectId: ctx.a.id, taskId: task.id, runTerminal: 'succeeded' })
assert.equal(second.task.status, 'completed')
assert.equal(second.decision.applied, true)
})
test('结果去重:同 (attemptId, reportVersion) 与同 sourceMessageRef 只登记一次', () => {
const ctx = seed()
const { task, attempt } = runningTask(ctx)
const payload = {
projectId: ctx.a.id,
taskId: task.id,
attemptId: attempt.id,
report: { summary: '第一次提交' },
runTerminal: 'succeeded',
sourceMessageRef: 'msg-9',
}
const first = ctx.service.reportTaskResult(payload)
assert.equal(first.duplicate, false)
const revision = ctx.store.getTask(task.id).revision
const second = ctx.service.reportTaskResult(payload)
assert.equal(second.duplicate, true)
assert.equal(second.result.id, first.result.id)
assert.equal(second.decision.applied, false)
assert.equal(ctx.store.getTask(task.id).revision, revision, '重复事件不改任务 revision')
// 换 reportVersion 但同 sourceMessageRef:仍算重复
const third = ctx.service.reportTaskResult({ ...payload, reportVersion: 2 })
assert.equal(third.duplicate, true)
assert.equal(ctx.store.listResults(undefined).filter((row) => row.taskId === task.id).length, 1)
})
test('结果:伪造成果引用被拒,不留半条结果', () => {
const ctx = seed()
const { task, attempt } = runningTask(ctx)
expectCode(() => ctx.service.reportTaskResult({
projectId: ctx.a.id,
taskId: task.id,
attemptId: attempt.id,
report: { summary: '带假附件', artifactRefs: ['art_fake123'] },
runTerminal: 'succeeded',
}), 'NOT_FOUND')
assert.equal(ctx.store.listResults(undefined).length, 0)
expectCode(() => ctx.service.reportTaskResult({
projectId: ctx.a.id,
taskId: task.id,
attemptId: attempt.id,
report: { summary: ' ' },
}), 'INVALID_INPUT')
expectCode(() => ctx.service.reportTaskResult({
projectId: ctx.a.id,
taskId: task.id,
attemptId: attempt.id,
report: { summary: '好' },
runTerminal: 'done',
}), 'INVALID_INPUT')
})
test('cancelTask:业务落 cancelled,运行中的尝试只到 cancel_requested', () => {
const ctx = seed()
const { task, attempt } = runningTask(ctx)
const out = ctx.service.cancelTask({ projectId: ctx.a.id, taskId: task.id, reason: '不再需要' })
assert.equal(out.task.status, 'cancelled')
assert.equal(out.task.cancelReason, '不再需要')
assert.equal(out.attempt.state, 'cancel_requested')
assert.equal(out.cancelRequest.attemptId, attempt.id)
assert.equal(out.cancelRequest.hostRunId, 'run-1')
// 已终态再取消:applied=false,状态不变
const again = ctx.service.cancelTask({ projectId: ctx.a.id, taskId: task.id })
assert.equal(again.applied, false)
assert.equal(again.task.status, 'cancelled')
})
test('requestTaskInput 进入 waiting_input,supplyTaskInput 回到 running', () => {
const ctx = seed()
const { task } = runningTask(ctx)
const asked = ctx.service.requestTaskInput({
projectId: ctx.a.id,
taskId: task.id,
reason: '缺少原始数据',
missingItems: ['数据文件'],
})
assert.equal(asked.task.status, 'waiting_input')
assert.equal(asked.task.waitingReason, '缺少原始数据')
assert.deepEqual(asked.missingItems, ['数据文件'])
const supplied = ctx.service.supplyTaskInput({ projectId: ctx.a.id, taskId: task.id })
assert.equal(supplied.task.status, 'running')
})
test('syncDecision 只登记带来源的决定事件,不广播', () => {
const ctx = seed()
const { task } = runningTask(ctx)
const out = ctx.service.syncDecision({
projectId: ctx.a.id,
taskId: task.id,
content: '同意按方案 B 执行',
sourceSessionId: 'sess-lead',
roleId: 'lead',
})
assert.equal(out.event.type, 'decision.synced')
assert.equal(out.event.payload.content, '同意按方案 B 执行')
assert.equal(out.event.payload.sourceSessionId, 'sess-lead')
assert.equal(out.task.id, task.id)
expectCode(() => ctx.service.syncDecision({ projectId: ctx.a.id, content: ' ' }), 'INVALID_INPUT')
})
// ---------- 投影与事件 ----------
test('bootstrap 一次拿全且只含选中项目的数据', () => {
const ctx = seed()
const taskA = ctx.service.createTask({ projectId: ctx.a.id, title: '甲', objective: '甲', ownerRoleId: 'libu' }).task
const taskB = ctx.service.createTask({ projectId: ctx.b.id, title: '乙', objective: '乙', ownerRoleId: 'libu' }).task
const view = ctx.service.bootstrap(ctx.a.id)
assert.equal(view.projectId, ctx.a.id)
assert.equal(view.projects.length, 2)
assert.equal(view.seats.length, 10)
assert.deepEqual(view.tasks.map((row) => row.id), [taskA.id])
assert.ok(!view.tasks.some((row) => row.id === taskB.id), '不串项目任务')
assert.equal(view.eventSeq, ctx.store.eventSeq)
// 不传 projectId 时取第一个项目
const fallback = ctx.service.bootstrap()
assert.equal(fallback.projectId, view.projects[0].id)
expectCode(() => ctx.service.bootstrap('proj_ghost'), 'NOT_FOUND')
})
test('listEvents since 语义:只给新事件,越界给 reset', () => {
const ctx = seed()
const before = ctx.service.listEvents(ctx.a.id, 0)
assert.ok(before.events.length > 0)
assert.ok(before.events.every((row) => row.projectId === ctx.a.id), '只返回本项目事件')
const last = before.seq
const empty = ctx.service.listEvents(ctx.a.id, last)
assert.equal(empty.events.length, 0)
assert.equal(empty.seq, last)
// 产生一条新事件,且只属于项目 A(项目 B 的事件不该出现在 A 的游标里)
ctx.service.createTask({ projectId: ctx.a.id, title: '新', objective: '新', ownerRoleId: 'libu' })
const mine = ctx.store.listEvents(ctx.a.id).filter((row) => row.seq > last)
const after = ctx.service.listEvents(ctx.a.id, last)
if (mine.length > 0) {
assert.equal(after.events.length, mine.length)
assert.deepEqual(after.events.map((row) => row.seq), mine.map((row) => row.seq))
} else {
assert.equal(after.events.length, 0)
}
assert.ok(after.events.every((row) => row.projectId === ctx.a.id))
// 用当前 seq 当游标再问一次必须为空(since 语义是“严格大于”)
assert.equal(ctx.service.listEvents(ctx.a.id, after.seq).events.length, 0)
// since 超过当前 seq:账本被替换/回滚,前端应全量重拉
const reset = ctx.service.listEvents(ctx.a.id, last + 9999)
assert.equal(reset.reset, true)
})
test('成果登记与查询同样受项目隔离', () => {
const ctx = seed()
const task = ctx.service.createTask({ projectId: ctx.a.id, title: '甲', objective: '甲', ownerRoleId: 'libu' }).task
const art = ctx.service.registerArtifact({
projectId: ctx.a.id,
taskId: task.id,
displayName: '交付物',
verification: { status: 'verified' },
}).artifact
assert.equal(ctx.service.getArtifact(ctx.a.id, art.id).displayName, '交付物')
expectCode(() => ctx.service.getArtifact(ctx.b.id, art.id), 'CROSS_PROJECT')
assert.equal(ctx.service.listArtifacts(ctx.b.id).length, 0)
})
test('未知部门与缺参数走 INVALID_ROLE / INVALID_INPUT', () => {
const ctx = seed()
expectCode(() => ctx.service.listTasks(ctx.a.id, { ownerRoleId: 'unknown' }), 'INVALID_ROLE')
expectCode(() => ctx.service.createTask({ projectId: ctx.a.id, objective: 'x', ownerRoleId: 'libu' }), 'INVALID_INPUT')
expectCode(() => ctx.service.createTask({ projectId: ctx.a.id, title: 'x', objective: 'y', ownerRoleId: 'hufu' }), 'INVALID_ROLE')
expectCode(() => ctx.service.bindDepartmentSession({ projectId: ctx.a.id, roleId: 'libu', sessionId: '' }), 'INVALID_INPUT')
})
// ---------- A20:目录冲突 ----------
test('A20 同目录/父子目录登记成另一个项目时明确报冲突,不宣称隔离', () => {
const { service } = makeService(seedOfCurrent())
service.registerProject({ hostWorkspaceId: 'ws-a', canonicalRoot: 'C:\\work\\alpha' })
// 大小写、分隔符、末尾斜杠都算同一目录
const same = expectCode(
() => service.registerProject({ hostWorkspaceId: 'ws-b', canonicalRoot: 'c:/work/alpha/' }),
'DUPLICATE_PROJECT',
)
assert.equal(same.details.relation, 'same')
assert.equal(same.details.otherHostWorkspaceId, 'ws-a')
assert.equal(same.details.hint, 'allowSharedRoot')
const nested = expectCode(
() => service.registerProject({ hostWorkspaceId: 'ws-c', canonicalRoot: 'C:\\work\\alpha\\sub' }),
'DUPLICATE_PROJECT',
)
assert.equal(nested.details.relation, 'nested')
// 显式放行:仍然登记,但把识别到的关系带回去,让 UI 有话说
const shared = service.registerProject({
hostWorkspaceId: 'ws-d',
canonicalRoot: 'C:\\work\\alpha',
allowSharedRoot: true,
})
assert.equal(shared.duplicate, false)
assert.equal(shared.sharedRoot.relation, 'same')
// 不同目录互不干扰
const other = service.registerProject({ hostWorkspaceId: 'ws-e', canonicalRoot: 'D:\\other' })
assert.equal(other.duplicate, false)
assert.equal(other.sharedRoot, null)
// 无关目录不该被误判为同一个:alpha 与 alphabeta 是不同目录
const notPrefix = service.registerProject({ hostWorkspaceId: 'ws-f', canonicalRoot: 'C:\\work\\alphabeta' })
assert.equal(notPrefix.duplicate, false)
})
// ---------- A22 / A23:成果修订与失效显示 ----------
test('A22 成果修订只开一条修订任务给原主责部门,派发自带原成果引用', () => {
const ctx = seed()
const task = ctx.service.createTask({
projectId: ctx.a.id, ownerRoleId: 'libu', title: '写报告', objective: '产出报告',
}).task
const artifact = ctx.service.registerArtifact({
projectId: ctx.a.id, taskId: task.id, fileRef: 'C:/work/a/report.md', displayName: '报告',
}).artifact
assert.equal(artifact.revision, 1)
const revised = ctx.service.requestArtifactRevision({
projectId: ctx.a.id, artifactId: artifact.id, instruction: '只改第三节的结论',
})
assert.equal(revised.task.kind, 'revision')
assert.equal(revised.task.ownerRoleId, 'libu', '仍归原主责部门,不重跑整套三省')
assert.equal(revised.task.sourceRoleId, 'lead')
assert.equal(revised.task.reviseOfArtifactId, artifact.id)
assert.equal(revised.task.artifactRevision, 1)
assert.equal(revised.task.scope.kind, 'artifact-revision')
assert.equal(revised.task.objective, '只改第三节的结论')
assert.equal(revised.task.status, 'draft', '默认草稿:不替用户立刻派工')
// 派发时若没显式给 materialRefs,自动带上「哪份成果的哪一版」
const dispatched = ctx.service.dispatchTask({
projectId: ctx.a.id, taskId: revised.task.id, targetRoleId: 'libu', idempotencyKey: 'rev-1',
})
assert.deepEqual(dispatched.contextPacket.materialRefs, [{ artifactId: artifact.id, revision: 1 }])
// 新成果接到旧成果上:版本 +1,且跨项目修订被拒
const next = ctx.service.registerArtifact({
projectId: ctx.a.id, taskId: revised.task.id, fileRef: 'C:/work/a/report-v2.md',
displayName: '报告 v2', revisesArtifactId: artifact.id,
}).artifact
assert.equal(next.revision, 2)
assert.equal(next.revisesArtifactId, artifact.id)
const bTask = ctx.service.createTask({ projectId: ctx.b.id, ownerRoleId: 'libu', title: 'b', objective: 'b' }).task
const foreign = ctx.service.registerArtifact({ projectId: ctx.b.id, taskId: bTask.id }).artifact
expectCode(
() => ctx.service.registerArtifact({ projectId: ctx.a.id, taskId: task.id, revisesArtifactId: foreign.id }),
'CROSS_PROJECT',
)
})
test('A23 成果文件不见了显示 missing,探不了就是 unknown,绝不猜成 ok', () => {
const { store } = makeService(seedOfCurrent())
// 文件系统由宿主注入:这里只验投影怎么读结论
const existing = new Set(['C:/work/keep.md'])
const service = createWorkbenchService({
store, clock: () => FIXED_NOW, fileExists: (path) => existing.has(path),
})
const project = service.registerProject({ hostWorkspaceId: 'ws-a' }).project
service.bindDepartmentSession({ projectId: project.id, roleId: 'libu', sessionId: 'sess-a-libu' })
const task = service.createTask({ projectId: project.id, ownerRoleId: 'libu', title: 't', objective: 'o' }).task
const kept = service.registerArtifact({ projectId: project.id, taskId: task.id, fileRef: 'C:/work/keep.md' }).artifact
const gone = service.registerArtifact({ projectId: project.id, taskId: task.id, fileRef: 'C:/work/gone.md' }).artifact
const remote = service.registerArtifact({ projectId: project.id, taskId: task.id, fileRef: null }).artifact
assert.equal(kept.existence, 'ok')
assert.equal(gone.existence, 'missing')
assert.equal(remote.existence, 'unknown', '没有本地路径就不下结论')
const boot = service.bootstrap(project.id)
assert.deepEqual(boot.artifacts.map((row) => row.existence), ['ok', 'missing', 'unknown'])
// 账本不因“文件没了”被改写:历史仍留着
assert.equal(store.listArtifacts(project.id).length, 3)
assert.equal(store.listArtifacts(project.id)[1].fileRef, 'C:/work/gone.md')
})

View File

@ -0,0 +1,127 @@
import test from 'node:test'
import assert from 'node:assert/strict'
import {
ATTEMPT_STATES,
DEPARTMENT_STATES,
DISPATCH_STATES,
STATE_MACHINES,
TASK_STATES,
TERMINAL_STATES,
allowedTransitions,
assertTransition,
canTransition,
isState,
isTerminal,
statesOf,
} from '../core/states.mjs'
test('every machine lists the plan states verbatim', () => {
assert.deepEqual([...TASK_STATES], [
'draft',
'queued',
'running',
'waiting_input',
'needs_attention',
'completed',
'failed',
'cancelled',
])
assert.deepEqual([...DISPATCH_STATES], ['prepared', 'sending', 'accepted', 'unknown', 'rejected'])
assert.deepEqual([...ATTEMPT_STATES], [
'queued',
'running',
'succeeded',
'failed',
'cancel_requested',
'cancelled',
'unknown',
])
assert.deepEqual([...DEPARTMENT_STATES], ['uninitialized', 'idle', 'queued', 'running', 'unavailable'])
assert.equal(Object.keys(STATE_MACHINES).length, 4)
})
test('state queries validate the machine name', () => {
assert.equal(isState('task', 'draft'), true)
assert.equal(isState('task', 'pending'), false, '旧 pending/in_progress 不属于新状态机')
assert.equal(isState('attempt', 'cancel_requested'), true)
assert.deepEqual(statesOf('department'), DEPARTMENT_STATES)
assert.throws(() => statesOf('nope'), /未知状态机/)
assert.throws(() => allowedTransitions('task', 'pending'), /未知状态/)
})
test('task happy path and legal detours', () => {
assert.deepEqual([...allowedTransitions('task', 'draft')], ['queued', 'cancelled'])
assert.equal(canTransition('task', 'draft', 'queued'), true)
assert.equal(canTransition('task', 'queued', 'running'), true)
assert.equal(canTransition('task', 'running', 'completed'), true)
assert.equal(canTransition('task', 'running', 'waiting_input'), true)
assert.equal(canTransition('task', 'waiting_input', 'queued'), true)
assert.equal(canTransition('task', 'needs_attention', 'completed'), true, '补报后可完成')
assert.equal(canTransition('task', 'running', 'draft'), false)
assert.equal(canTransition('task', 'completed', 'running'), false, '终态不回退')
assert.equal(canTransition('task', 'failed', 'running'), false)
assert.equal(canTransition('task', 'cancelled', 'queued'), false)
assert.equal(canTransition('task', 'running', 'running'), true, '同状态重复写入视为幂等')
})
test('dispatch states separate sending from accepted', () => {
assert.equal(canTransition('dispatch', 'prepared', 'sending'), true)
assert.equal(canTransition('dispatch', 'sending', 'accepted'), true)
assert.equal(canTransition('dispatch', 'sending', 'unknown'), true, '回执超时进入 unknown')
assert.equal(canTransition('dispatch', 'unknown', 'accepted'), true, '对账后可确认已接收')
assert.equal(canTransition('dispatch', 'unknown', 'rejected'), true)
assert.equal(canTransition('dispatch', 'accepted', 'unknown'), false)
assert.equal(canTransition('dispatch', 'rejected', 'sending'), false)
assert.equal(canTransition('dispatch', 'prepared', 'accepted'), false, '不能跳过发送直接接收')
})
test('attempt states keep cancel requests separate from cancellation', () => {
assert.equal(canTransition('attempt', 'queued', 'running'), true)
assert.equal(canTransition('attempt', 'running', 'cancel_requested'), true)
assert.equal(canTransition('attempt', 'cancel_requested', 'cancelled'), true)
assert.equal(canTransition('attempt', 'cancel_requested', 'succeeded'), true, '取消与成功竞争照常落终态')
assert.equal(canTransition('attempt', 'cancelled', 'running'), false)
assert.equal(canTransition('attempt', 'unknown', 'running'), true, '对账发现仍在跑')
assert.equal(canTransition('attempt', 'succeeded', 'failed'), false)
})
test('department states describe the session, not the task', () => {
assert.equal(canTransition('department', 'uninitialized', 'queued'), true)
assert.equal(canTransition('department', 'running', 'unavailable'), true)
assert.equal(canTransition('department', 'unavailable', 'idle'), true)
assert.equal(canTransition('department', 'idle', 'completed'), false, '部门没有完成态')
})
test('assertTransition throws readable errors and returns the target', () => {
assert.equal(assertTransition('task', 'draft', 'queued'), 'queued')
assert.equal(assertTransition('task', 'queued', 'queued'), 'queued')
assert.throws(() => assertTransition('task', 'completed', 'running'), /Task 不允许从 completed 迁移到 running/)
assert.throws(() => assertTransition('task', 'bogus', 'running'), /当前状态非法/)
assert.throws(() => assertTransition('task', 'draft', 'bogus'), /目标状态非法/)
assert.throws(() => assertTransition('nope', 'draft', 'queued'), /未知状态机/)
})
test('terminal states are explicit per machine', () => {
assert.equal(isTerminal('task', 'completed'), true)
assert.equal(isTerminal('task', 'needs_attention'), false, '待核不算完成')
assert.equal(isTerminal('dispatch', 'accepted'), true)
assert.equal(isTerminal('dispatch', 'unknown'), false, 'unknown 必须对账')
assert.equal(isTerminal('attempt', 'cancel_requested'), false)
assert.equal(isTerminal('attempt', 'cancelled'), true)
assert.equal(isTerminal('department', 'unavailable'), false)
assert.throws(() => isTerminal('nope', 'x'), /未知状态机/)
})
test('terminal state sets match the machines', () => {
assert.deepEqual([...TERMINAL_STATES.task], ['completed', 'failed', 'cancelled'])
assert.deepEqual([...TERMINAL_STATES.dispatch], ['accepted', 'rejected'])
assert.deepEqual([...TERMINAL_STATES.attempt], ['succeeded', 'failed', 'cancelled'])
// 部门不是业务流程,没有“完成”概念
assert.deepEqual([...TERMINAL_STATES.department], [])
for (const key of Object.keys(TERMINAL_STATES)) {
for (const state of TERMINAL_STATES[key]) {
assert.equal(isTerminal(key, state), true, )
assert.deepEqual(allowedTransitions(key, state), [], )
}
}
})

View File

@ -0,0 +1,368 @@
import test from 'node:test'
import assert from 'node:assert/strict'
import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { dirname, join } from 'node:path'
import { SCHEMA_VERSION, StoreError, WorkbenchStore, defaultStorePath, entityOf } from '../core/store.mjs'
import { createIdFactory } from '../core/ids.mjs'
/** 固定随机源和时钟:随机源按调用递增,保证 ID 可复现且互不相同。 */
function makeStore(file = null) {
let cursor = 0
return new WorkbenchStore({
file,
clock: () => Date.parse('2026-11-09T12:00:00.000Z'),
random: () => cursor++,
})
}
function mkStore() {
const store = makeStore()
const a = store.createProject({ hostWorkspaceId: 'ws-a', displayNameCache: '项目A' })
const b = store.createProject({ hostWorkspaceId: 'ws-b', displayNameCache: '项目B' })
return { store, a, b }
}
test('createProject seeds ten empty seats without sessions', () => {
const { store, a } = mkStore()
assert.match(a, /^proj_/)
assert.equal(store.listProjects().length, 2)
const bindings = store.listBindings(a)
assert.equal(bindings.length, 10)
assert.ok(bindings.every((row) => row.currentSessionId === null && row.status === 'uninitialized'))
assert.ok(store.listConfigs(a).every((row) => row.providerId === null && row.configRevision === 0))
assert.equal(store.revision, 2, '每次提交递增 revision')
assert.equal(store.eventSeq, 2, '事件日志追加 seq')
assert.deepEqual(store.listEvents(a).map((row) => row.type), ['project.created'])
assert.throws(() => store.createProject({ hostWorkspaceId: 'ws-a' }), /已登记/)
assert.throws(() => store.createProject({ hostWorkspaceId: ' ' }), /非空字符串/)
assert.throws(() => store.bindSession(a, 'hufu', 's1'), /未知角色/)
})
test('one active binding per (projectId, roleId)', () => {
const { store, a } = mkStore()
const bound = store.bindSession(a, 'gongbu', 'sess-1')
assert.equal(bound.bindingGeneration, 1)
assert.equal(bound.currentSessionId, 'sess-1')
assert.equal(store.getBinding(a, 'gongbu').currentSessionId, 'sess-1')
// 同一 (project, role) 的两个绑定行不可能同时存在:键就是 (projectId, roleId)。
const rows = store.listBindings(a).filter((row) => row.roleId === 'gongbu')
assert.equal(rows.length, 1)
// 同一部门换绑走 releaseBinding,旧会话进历史而不是悄悄被覆盖。
const rebound = store.bindSession(a, 'gongbu', 'sess-2', { allowReplace: true })
assert.equal(rebound.currentSessionId, 'sess-2')
assert.equal(rebound.bindingGeneration, 2)
assert.deepEqual(rebound.historySessionRefs.map((row) => row.sessionId), ['sess-1'])
})
test('binding requires the old session to be released before it is reused', () => {
const { store, a } = mkStore()
store.bindSession(a, 'gongbu', 'sess-1')
assert.throws(() => store.bindSession(a, 'gongbu', 'sess-1'), /无需重复绑定/)
assert.equal(store.getBinding(a, 'gongbu').bindingGeneration, 1)
})
test('a session id cannot be bound to two different (projectId, roleId)', () => {
const { store, a, b } = mkStore()
store.bindSession(a, 'gongbu', 'sess-1')
assert.throws(() => store.bindSession(a, 'libu', 'sess-1'), /SESSION_CONFLICT|已绑定/)
assert.throws(() => store.bindSession(b, 'gongbu', 'sess-1'), /已绑定/)
// 释放后旧会话进入 historySessionRefs,不删除历史,且可绑定到别处。
const released = store.releaseBinding(a, 'gongbu')
assert.equal(released.currentSessionId, null)
assert.equal(released.historySessionRefs.length, 1)
assert.equal(released.historySessionRefs[0].sessionId, 'sess-1')
const moved = store.bindSession(b, 'gongbu', 'sess-1')
assert.equal(moved.currentSessionId, 'sess-1')
assert.equal(moved.bindingGeneration, 1)
})
test('rebinding bumps bindingGeneration so old dispatches stay pinned', () => {
const { store, a } = mkStore()
store.bindSession(a, 'gongbu', 'sess-1')
store.releaseBinding(a, 'gongbu')
const next = store.bindSession(a, 'gongbu', 'sess-2')
assert.equal(next.bindingGeneration, 2)
assert.deepEqual(store.getBinding(a, 'gongbu').historySessionRefs.map((row) => row.sessionId), ['sess-1'])
assert.throws(() => store.setBindingStatus(a, 'gongbu', 'completed'), /目标状态非法/)
assert.equal(store.setBindingStatus(a, 'gongbu', 'unavailable').status, 'unavailable')
})
test('configuration CAS rejects stale writers and returns the current value', () => {
const { store, a, b } = mkStore()
const first = store.saveConfig(a, 'gongbu', { provider: 'deepseek', model: 'chat', reasoningEffort: 'high' }, 0)
assert.equal(first.configRevision, 1)
assert.equal(first.providerId, 'deepseek')
assert.throws(
() => store.saveConfig(a, 'gongbu', { provider: 'openai', model: 'gpt', reasoningEffort: null }, 0),
(error) => {
assert.equal(error.code, 'CAS_CONFLICT')
assert.equal(error.details.currentRevision, 1)
assert.deepEqual(error.details.current, { provider: 'deepseek', model: 'chat', reasoningEffort: 'high' })
return true
},
)
// 冲突不写账:revision 与配置保持原样
assert.equal(store.getConfig(a, 'gongbu').providerId, 'deepseek')
// 另一项目另一部门互不影响
assert.equal(store.getConfig(b, 'gongbu').configRevision, 0)
const second = store.saveConfig(a, 'gongbu', { provider: 'openai', model: 'gpt' }, 1)
assert.equal(second.configRevision, 2)
assert.equal(second.reasoningEffort, null, '缺省 effort 落 null,不透传 undefined')
assert.throws(() => store.saveConfig(a, 'gongbu', { provider: 'x', model: 'y' }, '1'), /expectedRevision/)
assert.throws(() => store.saveConfig(a, 'gongbu', { provider: 'x' }, 2), /model/)
})
test('dispatch idempotency key returns the existing record', () => {
const { store, a } = mkStore()
const first = store.recordDispatch({ projectId: a, idempotencyKey: 'k-1', taskId: null })
assert.equal(first.duplicate, false)
assert.match(first.dispatch.id, /^dsp_/)
const again = store.recordDispatch({ projectId: a, idempotencyKey: 'k-1' })
assert.equal(again.duplicate, true)
assert.equal(again.dispatch.id, first.dispatch.id)
assert.equal([...store.state.dispatches.values()].length, 1, '重复点击只留一条派发')
// 幂等键按项目隔离:另一项目同键是另一件事。
const { b } = { b: store.listProjects()[1].id }
assert.equal(store.recordDispatch({ projectId: b, idempotencyKey: 'k-1' }).duplicate, false)
// 状态推进走状态机
const accepted = store.updateDispatch(first.dispatch.id, { status: 'sending' })
assert.equal(accepted.status, 'sending')
assert.throws(() => store.updateDispatch(first.dispatch.id, { status: 'proposed' }), /目标状态非法/)
assert.throws(() => store.updateDispatch(first.dispatch.id, { status: 'prepared' }), /不允许/)
})
test('recordResult deduplicates duplicate completion events', () => {
const { store, a } = mkStore()
const task = store.insertTask({ projectId: a, ownerRoleId: 'gongbu', sourceRoleId: 'lead', status: 'draft' })
const attempt = store.insertAttempt({ projectId: a, taskId: task.id, state: 'running' })
const base = { projectId: a, taskId: task.id, attemptId: attempt.id, summary: '完成', reportVersion: 1 }
const first = store.recordResult(base)
assert.equal(first.duplicate, false)
assert.match(first.result.id, /^res_/)
const dupVersion = store.recordResult(base)
assert.equal(dupVersion.duplicate, true)
assert.equal(dupVersion.result.id, first.result.id)
// 同一源消息的重复事件同样只登记一次
const dupMessage = store.recordResult({ ...base, reportVersion: 2, sourceMessageRef: 'msg-1' })
assert.equal(dupMessage.duplicate, false)
const dupMessageAgain = store.recordResult({ ...base, reportVersion: 3, sourceMessageRef: 'msg-1' })
assert.equal(dupMessageAgain.duplicate, true)
assert.equal(store.listResults(task.id).length, 2)
})
test('cross-project references are rejected on write', () => {
const { store, a, b } = mkStore()
const taskA = store.insertTask({ projectId: a, ownerRoleId: 'gongbu', sourceRoleId: 'lead', status: 'draft' })
assert.throws(
() => store.insertAttempt({ projectId: b, taskId: taskA.id, state: 'queued' }),
(error) => error.code === 'CROSS_PROJECT',
)
const attemptA = store.insertAttempt({ projectId: a, taskId: taskA.id, state: 'running' })
assert.throws(
() => store.recordResult({ projectId: b, taskId: null, attemptId: attemptA.id, summary: 'x' }),
(error) => error.code === 'CROSS_PROJECT',
)
assert.equal(store.listResults().length, 0, '被拒绝的写入不落账')
})
test('cross-project recordResult and artifacts are refused', () => {
const { store, a, b } = mkStore()
const taskA = store.insertTask({ projectId: a, ownerRoleId: 'gongbu', sourceRoleId: 'lead', status: 'draft' })
const attemptA = store.insertAttempt({ projectId: a, taskId: taskA.id, state: 'running' })
assert.throws(
() => store.recordResult({ projectId: b, attemptId: attemptA.id, summary: 'x' }),
(error) => error.code === 'CROSS_PROJECT',
)
const resultA = store.recordResult({ projectId: a, taskId: taskA.id, attemptId: attemptA.id, summary: 'ok' })
assert.throws(
() => store.recordArtifact({ projectId: b, taskId: taskA.id, ownerRoleId: 'gongbu', sourceResultId: resultA.result.id }),
(error) => error.code === 'CROSS_PROJECT',
)
const artifact = store.recordArtifact({ projectId: a, taskId: taskA.id, ownerRoleId: 'gongbu', sourceResultId: resultA.result.id })
assert.match(artifact.id, /^art_/)
assert.throws(() => store.insertContextPacket({ projectId: b, taskId: taskA.id }), /CROSS_PROJECT|跨项目/)
assert.throws(() => store.assertProjectOwns(b, 'tasks', taskA.id), /不属于项目/)
assert.throws(() => store.assertProjectOwns(a, 'tasks', 'task_missing'), /不存在/)
assert.equal(store.assertProjectOwns(a, 'tasks', taskA.id).id, taskA.id)
assert.throws(() => store.insertTask({ projectId: 'proj_nope', ownerRoleId: 'gongbu', sourceRoleId: 'lead', status: 'draft' }), /项目不存在/)
// 先校验角色,未知部门在建立任务时就拒绝
const fresh = new WorkbenchStore({ file: null, clock: () => 1700000000000, random: () => 7 })
const fa = fresh.createProject({ hostWorkspaceId: 'ws-a' })
assert.throws(() => fresh.insertTask({ projectId: fa, ownerRoleId: 'hufu', sourceRoleId: 'lead', status: 'draft' }), /未知主责部门/)
assert.throws(() => store.recordArtifact({ projectId: a, taskId: taskA.id, ownerRoleId: 'hufu' }), /未知主责部门/)
})
test('task writes cannot skip the state machine or rewrite project', () => {
const { store, a, b } = mkStore()
const task = store.insertTask({ projectId: a, ownerRoleId: 'gongbu', sourceRoleId: 'lead', status: 'draft' })
assert.equal(task.revision, 1)
const queued = store.updateTask({ ...task, status: 'queued' })
assert.equal(queued.revision, 2)
assert.throws(() => store.updateTask({ ...task, status: 'completed' }), /不允许/)
assert.throws(() => store.updateTask({ ...task, projectId: b, status: 'queued' }), /不能被改写/)
assert.throws(() => store.insertTask({ ...task }), /任务已存在/)
})
test('markEventDelivered acks the outbox without deleting events', () => {
const { store, a, b } = mkStore()
const first = store.appendEvent({ type: 'ping', projectId: a })
const second = store.appendEvent({ type: 'ping', projectId: a })
const other = store.appendEvent({ type: 'ping', projectId: b })
assert.equal(store.listPendingEvents(a).length, 3, '项目 a:建项目 1 条 + 两条 ping')
const revision = store.revision
assert.deepEqual(store.markEventDelivered(a, [first.eventId]), { delivered: 1 })
assert.equal(store.revision, revision + 1, '标记走同一条提交路径,递增 revision')
// 幂等:重复 ack 不报错、不重复计数,也不白增 revision
const revision2 = store.revision
assert.deepEqual(store.markEventDelivered(a, [first.eventId]), { delivered: 0 })
assert.equal(store.revision, revision2, '空操作不递增 revision')
// 未知 id 静默忽略
assert.deepEqual(store.markEventDelivered(a, ['evt_missing', 'not-an-id']), { delivered: 0 })
// 跨项目 id 忽略:既不是错误,也不会写到别的项目
assert.deepEqual(store.markEventDelivered(a, [other.eventId]), { delivered: 0 })
assert.equal(store.listPendingEvents(b).length, 2, '项目 b 的事件不受影响')
// 标记后不再出现在 pending,但事件仍可通过 listEvents 审计看到
assert.deepEqual(
store.listPendingEvents(a).map((row) => row.eventId),
[store.listEvents(a)[0].eventId, second.eventId],
'只剩项目创建事件与第二条 ping',
)
const acks = store.listEvents(a).find((row) => row.eventId === first.eventId)
assert.ok(acks.deliveredAt !== null, '已投递事件保留记录并写时间戳')
assert.equal(store.listEvents(a).length, 3)
// 项目不存在与其它方法一致抛 StoreError
assert.throws(
() => store.markEventDelivered('proj_nope', [first.eventId]),
(error) => error instanceof StoreError && error.code === 'NOT_FOUND',
)
})
test('listPendingEvents honours limit and keeps seq order', () => {
const { store, a } = mkStore()
// mkStore 先建了两个项目,项目 a 的 project.created 是第 1 条事件
const created = store.listEvents(a)[0]
const first = store.appendEvent({ type: 'ping', projectId: a })
const second = store.appendEvent({ type: 'ping', projectId: a })
const third = store.appendEvent({ type: 'ping', projectId: a })
assert.deepEqual(store.listPendingEvents(a).map((row) => row.seq), [created.seq, first.seq, second.seq, third.seq])
assert.deepEqual(store.listPendingEvents(a, { limit: 2 }).map((row) => row.seq), [created.seq, first.seq])
// 非正整数 limit 视为不传,行为与旧接口一致
assert.equal(store.listPendingEvents(a, { limit: 0 }).length, 4)
assert.equal(store.listPendingEvents(a, { limit: -1 }).length, 4)
assert.equal(store.listPendingEvents(a, {}).length, 4)
// limit 与 ack 组合:已投递的不占额度
assert.deepEqual(store.markEventDelivered(a, [created.eventId, first.eventId]), { delivered: 2 })
assert.equal(store.listPendingEvents(a).length, 2)
assert.deepEqual(store.listPendingEvents(a, { limit: 1 }).map((row) => row.seq), [second.seq])
assert.deepEqual(store.listPendingEvents(a, { limit: 2 }).map((row) => row.seq), [second.seq, third.seq])
})
test('event log keeps monotonic seq and rejects duplicate eventId', () => {
const { store, a } = mkStore()
const first = store.appendEvent({ type: 'ping', projectId: a })
const second = store.appendEvent({ type: 'ping', projectId: a })
assert.ok(second.seq > first.seq)
assert.equal(store.listPendingEvents().length, 4, '两个项目创建 + 两条 ping 都待处理')
assert.deepEqual(store.listPendingEvents().slice(-2).map((row) => row.type), ['ping', 'ping'])
assert.equal(store.listEvents(a).length, 3)
assert.throws(() => store.appendEvent({ type: 'ping', projectId: a, eventId: first.eventId }), /事件已登记/)
assert.throws(() => store.appendEvent({ projectId: a }), /event.type/)
})
test('failed writes roll back memory and leave no ghost rows', () => {
const { store, a } = mkStore()
const revision = store.revision
const events = store.eventSeq
assert.throws(() => store.recordDispatch({ projectId: a, idempotencyKey: 'k', status: 'proposed' }), /未知派发状态/)
assert.equal([...store.state.dispatches.values()].length, 0)
assert.equal(store.revision, revision, '失败不递增 revision')
assert.equal(store.eventSeq, events, '失败不留下半截事件')
})
test('file persistence round-trips and writes atomically', () => {
const dir = mkdtempSync(join(tmpdir(), 'sansheng-store-'))
try {
const file = join(dir, 'nested', 'workbench.json')
const store = makeStore(file)
const a = store.createProject({ hostWorkspaceId: 'ws-a', displayNameCache: '项目A' })
store.bindSession(a, 'gongbu', 'sess-1')
store.saveConfig(a, 'gongbu', { provider: 'p', model: 'm', reasoningEffort: 'low' }, 0)
store.recordDispatch({ projectId: a, idempotencyKey: 'k-1' })
store.appendEvent({ type: 'test.event', projectId: a })
assert.equal(existsSync(file), true)
// 原子写:目录里只剩目标文件,没有残留 .tmp
assert.deepEqual(readdirSync(dirname(file)), ['workbench.json'])
const raw = JSON.parse(readFileSync(file, 'utf8'))
assert.equal(raw.schemaVersion, 1)
assert.equal(raw.revision, store.revision)
const reloaded = makeStore(file)
assert.equal(reloaded.load(), true)
assert.equal(reloaded.revision, store.revision)
assert.equal(reloaded.getBinding(a, 'gongbu').currentSessionId, 'sess-1')
assert.equal(reloaded.getConfig(a, 'gongbu').configRevision, 1)
assert.equal(reloaded.listEvents(a).length, store.listEvents(a).length)
assert.deepEqual(reloaded.snapshot().projects, store.snapshot().projects)
// 重新载入后仍能继续写,且唯一性约束照样生效
assert.throws(() => reloaded.bindSession(a, 'libu', 'sess-1'), /已绑定/)
assert.equal(reloaded.recordDispatch({ projectId: a, idempotencyKey: 'k-1' }).duplicate, true)
// 缺省路径:%DSH_HOME%\sansheng-liubu\workbench.json,未设置时落 ~/.dsh
const sep = String.fromCharCode(92)
const winPath = defaultStorePath({ DSH_HOME: 'C:' + sep + 'dsh-home' }).split(sep).join('/')
assert.equal(winPath, 'C:/dsh-home/sansheng-liubu/workbench.json')
assert.equal(makeStore(null).save(), false, '纯内存模式不落盘')
} finally {
rmSync(dir, { recursive: true, force: true })
}
})
test('load rejects unknown schema versions instead of guessing', () => {
const dir = mkdtempSync(join(tmpdir(), 'sansheng-schema-'))
try {
const file = join(dir, 'workbench.json')
const store = makeStore(file)
store.createProject({ hostWorkspaceId: 'ws-a' })
const raw = JSON.parse(readFileSync(file, 'utf8'))
raw.schemaVersion = 99
writeFileSync(file, JSON.stringify(raw))
const other = makeStore(file)
assert.throws(() => other.load(), /schemaVersion=99/)
} finally {
rmSync(dir, { recursive: true, force: true })
}
})
test('ids factory is shared with event ids for deterministic tests', () => {
const ids = createIdFactory({ random: () => 2, length: 6 })
assert.match(ids.task(), /^task_2{6}$/)
// 常量随机源会让 ID 冲突,因此 store 自带事件去重后缀
const constant = new WorkbenchStore({ file: null, clock: () => 0, random: () => 7 })
const projectId = constant.createProject({ hostWorkspaceId: 'ws-a' })
const first = constant.appendEvent({ type: 'x', projectId })
const second = constant.appendEvent({ type: 'x', projectId })
assert.match(first.eventId, /^evt_7{12}/)
assert.notEqual(first.eventId, second.eventId)
assert.deepEqual(constant.listEvents(projectId).map((row) => row.seq), [1, 2, 3])
})
test('schema version and entity mapping are exported constants', () => {
assert.equal(SCHEMA_VERSION, 1)
assert.equal(entityOf('tasks'), 'task')
assert.equal(entityOf('contextPackets'), 'contextPacket')
assert.equal(entityOf('nope'), null)
const error = new StoreError('BOOM', '炸了')
assert.ok(error instanceof Error)
assert.equal(error.name, 'StoreError')
assert.equal(error.code, 'BOOM')
assert.equal(error.details, undefined)
assert.deepEqual(new StoreError('X', 'y', { a: 1 }).details, { a: 1 })
// 缺省路径:%DSH_HOME%\sansheng-liubu\workbench.json,未设置时落 ~/.dsh
const sep = String.fromCharCode(92)
const winPath = defaultStorePath({ DSH_HOME: 'C:' + sep + 'dsh-home' }).split(sep).join('/')
assert.equal(winPath, 'C:/dsh-home/sansheng-liubu/workbench.json')
const homePath = defaultStorePath({}).split(sep).join('/')
assert.match(homePath, /\.dsh\/sansheng-liubu\/workbench\.json$/)
})

View File

@ -0,0 +1,368 @@
// 任务生命周期测试:重点验证「完成判定三分支」与乱序/重复事件不回退状态。
// 这些是 v0.1 最容易出错的地方,全部用纯函数直接断言,不依赖 store 或宿主。
import test from 'node:test'
import assert from 'node:assert/strict'
import {
TaskError,
TASK_TRANSITIONS,
isStaleSeq,
isRegressingEvent,
createTask,
startTask,
beginAttempt,
validateReport,
checkCompletion,
evaluateCompletion,
decide,
requestInput,
supplyInput,
completeTask,
failTask,
cancelTask,
applyDecision,
isOpenTask,
} from '../core/tasks.mjs'
import { WorkbenchStore } from '../core/store.mjs'
const clock = () => 1700000000000
function draftTask(overrides = {}) {
return createTask(
{
projectId: 'proj_a',
title: '整理季度报表',
objective: '把三份表合并成一份差异表',
ownerRoleId: 'hubu',
sourceRoleId: 'zhongshu',
...overrides,
},
{ newTaskId: () => 'task_1', now: clock },
)
}
function runningTask() {
const task = startTask(draftTask(), { now: clock })
return beginAttempt(task, { id: 'att_1', projectId: 'proj_a', taskId: 'task_1' }, { now: clock })
}
const goodReport = {
attemptId: 'att_1',
taskId: 'task_1',
summary: '差异 12 处,已附差异表',
checks: [{ name: '数量核对', ok: true }],
artifactRefs: ['art_1'],
}
test('createTask 只建草稿,缺字段或未知席直接拒绝', () => {
const task = draftTask()
assert.equal(task.status, 'draft')
assert.equal(task.ownerRoleId, 'hubu')
assert.equal(task.sourceRoleId, 'zhongshu')
assert.equal(task.activeAttemptId, null)
assert.equal(task.revision, 1)
assert.deepEqual(task.attempts, [])
assert.throws(() => createTask({ title: 'x', objective: 'y', ownerRoleId: 'hubu' }), TaskError)
assert.throws(() => draftTask({ ownerRoleId: 'hufu' }), /未知主责部门/)
assert.throws(() => draftTask({ sourceRoleId: 'nobody' }), /未知来源部门/)
assert.throws(() => draftTask({ objective: ' ' }), /objective/)
})
test('TASK_TRANSITIONS 与方案一致且不可变', () => {
assert.ok(Object.isFrozen(TASK_TRANSITIONS))
const pairs = TASK_TRANSITIONS.map(([from, to]) => `${from}->${to}`)
for (const expected of ['draft->queued', 'running->completed', 'running->needs_attention', 'needs_attention->completed', 'waiting_input->running']) {
assert.ok(pairs.includes(expected), `缺少迁移 ${expected}`)
}
assert.ok(!pairs.includes('completed->running'), '终态不能被复活')
assert.ok(Object.isFrozen(TASK_TRANSITIONS[0]))
})
test('startTask 只从草稿或待补充入队', () => {
const queued = startTask(draftTask(), { now: clock })
assert.equal(queued.status, 'queued')
assert.equal(queued.revision, 2)
assert.throws(() => startTask(queued), /只有草稿或待补充/)
const waiting = requestInput(runningTask(), '缺少上月口径', { now: clock }).task
assert.equal(waiting.status, 'waiting_input')
assert.equal(startTask(waiting, { now: clock }).status, 'queued')
})
test('beginAttempt 绑定新尝试并保留历史', () => {
const task = runningTask()
assert.equal(task.status, 'running')
assert.equal(task.activeAttemptId, 'att_1')
assert.deepEqual(task.attempts, ['att_1'])
// 旧尝试仍活跃时不允许并发换绑:先对账再重试
assert.throws(
() => beginAttempt(task, { id: 'att_2', projectId: 'proj_a', taskId: 'task_1' }),
(error) => error.code === 'ACTIVE_ATTEMPT',
)
const settled = { ...task, activeAttemptId: null, status: 'needs_attention' }
const retried = beginAttempt(settled, { id: 'att_2', projectId: 'proj_a', taskId: 'task_1' }, { now: clock })
assert.equal(retried.activeAttemptId, 'att_2')
assert.deepEqual(retried.attempts, ['att_1', 'att_2'], '旧尝试不能被覆盖')
assert.throws(() => beginAttempt({ ...task, status: 'completed' }, { id: 'att_3', projectId: 'proj_a', taskId: 'task_1' }), /不能开始新的尝试/)
assert.throws(
() => beginAttempt({ ...task, status: 'queued' }, { id: 'att_2', projectId: 'proj_b', taskId: 'task_1' }),
/不属于同一项目/,
)
assert.throws(
() => beginAttempt({ ...task, status: 'queued' }, { id: 'att_2', projectId: 'proj_a', taskId: 'task_9' }),
/别的任务/,
)
assert.throws(() => beginAttempt({ ...task, status: 'queued' }, null), /尝试记录不合法/)
})
test('beginAttempt 不再被已取消的旧尝试挡住重试', () => {
const running = runningTask()
// 取消后 activeAttemptId 仍指向旧尝试(保留审计),旧 Attempt 已转 cancelled 终态 → 允许重试
const cancelledLookup = (id) => ({ id, state: 'cancelled' })
const next = { id: 'att_2', projectId: 'proj_a', taskId: 'task_1' }
const retried = beginAttempt(running, next, { now: clock, attemptLookup: cancelledLookup })
assert.equal(retried.status, 'running')
assert.equal(retried.activeAttemptId, 'att_2')
assert.deepEqual(retried.attempts, ['att_1', 'att_2'], '旧尝试保留在历史里')
// running 但当前尝试已 unknown/failed/succeeded 终态时同样放行
for (const state of ['failed', 'succeeded']) {
assert.equal(beginAttempt(running, next, { now: clock, attemptLookup: (id) => ({ id, state }) }).activeAttemptId, 'att_2')
}
// needs_attention 下旧尝试已取消:不被 ACTIVE_ATTEMPT 挡住
const needsAttention = { ...running, status: 'needs_attention' }
const retriedAfterCancel = beginAttempt(needsAttention, next, { now: clock, attemptLookup: cancelledLookup })
assert.equal(retriedAfterCancel.status, 'running')
assert.equal(retriedAfterCancel.needsAttentionReason, null)
// 旧尝试 still running / unknown / cancel_requested:仍在活动,必须挡住
const queuedAttempt = (id) => ({ id, state: 'queued' })
const unknownAttempt = (id) => ({ id, state: 'unknown' })
for (const lookup of [queuedAttempt, unknownAttempt]) {
assert.throws(
() => beginAttempt(running, next, { now: clock, attemptLookup: lookup }),
(error) => error.code === 'ACTIVE_ATTEMPT',
)
assert.throws(
() => beginAttempt(needsAttention, next, { now: clock, attemptLookup: lookup }),
(error) => error.code === 'ACTIVE_ATTEMPT',
)
}
// 不注入 attemptLookup 时无法证明旧尝试已对账 → 保持旧行为(非空即挡)
assert.throws(
() => beginAttempt(running, next, { now: clock }),
(error) => error.code === 'ACTIVE_ATTEMPT',
)
// needs_attention 且 activeAttemptId 为空 → 本来就不受影响
assert.equal(beginAttempt({ ...running, activeAttemptId: null, status: 'needs_attention' }, next, { now: clock }).activeAttemptId, 'att_2')
})
test('validateReport 只认结构化字段', () => {
assert.deepEqual(validateReport(goodReport), [])
assert.deepEqual(validateReport({ attemptId: 'a', taskId: 't', summary: 's' }), [])
assert.deepEqual(validateReport(null), ['报告必须是对象'])
const errors = validateReport({ summary: ' ', artifactRefs: ['res_1'], checks: 'ok' })
assert.ok(errors.some((row) => row.includes('attemptId')))
assert.ok(errors.some((row) => row.includes('taskId')))
assert.ok(errors.some((row) => row.includes('摘要为空')))
assert.ok(errors.some((row) => row.includes('成果引用形状非法')))
assert.ok(errors.some((row) => row.includes('checks 必须是数组')))
assert.ok(validateReport({ attemptId: 'a', taskId: 't', summary: 's', artifactRefs: 'art_1' }).some((row) => row.includes('artifactRefs')))
})
test('checkCompletion 三条条件各占一票', () => {
const all = checkCompletion({ report: goodReport, runTerminal: 'succeeded', artifactRefs: ['art_1'], artifactLookup: () => ({ id: 'art_1' }) })
assert.deepEqual(all, { reportOk: true, runOk: true, refsValid: true, blockers: [], ok: true })
const noReport = checkCompletion({ report: null, runTerminal: 'succeeded' })
assert.equal(noReport.reportOk, false)
assert.equal(noReport.ok, false)
assert.ok(noReport.blockers.includes('未收到结构化报告'))
const noTerminal = checkCompletion({ report: goodReport, runTerminal: null })
assert.equal(noTerminal.runOk, false)
assert.ok(noTerminal.blockers.includes('宿主运行尚未结束'))
const failedRun = checkCompletion({ report: goodReport, runTerminal: 'failed' })
assert.equal(failedRun.runOk, false)
assert.ok(failedRun.blockers.some((row) => row.includes('failed')))
const blocked = checkCompletion({ report: { ...goodReport, blockedReason: '缺权限' }, runTerminal: 'succeeded' })
assert.equal(blocked.reportOk, false)
const danglingRef = checkCompletion({ report: goodReport, runTerminal: 'succeeded', artifactRefs: ['art_1'], artifactLookup: () => undefined })
assert.equal(danglingRef.refsValid, false)
assert.ok(danglingRef.blockers.some((row) => row.includes('成果引用无效')))
const missingArtifact = checkCompletion({ report: goodReport, runTerminal: 'succeeded', artifactRefs: ['art_1'], artifactLookup: () => ({ id: 'art_1', verification: { status: 'missing' } }) })
assert.equal(missingArtifact.refsValid, false)
// 纯分析任务允许无附件:空引用不算失败
assert.equal(checkCompletion({ report: goodReport, runTerminal: 'succeeded', artifactRefs: [] }).ok, true)
})
test('完成判定三分支:三者齐全 → completed', () => {
const decision = evaluateCompletion(
runningTask(),
{ report: goodReport, runTerminal: 'succeeded', artifactRefs: ['art_1'], artifactLookup: () => ({ id: 'art_1' }) },
{ now: clock },
)
assert.equal(decision.applied, true)
assert.equal(decision.task.status, 'completed')
assert.ok(decision.task.reportReceivedAt)
assert.equal(decision.task.needsAttentionReason, null)
})
test('完成判定三分支:只有报告 → 等待,不置 completed', () => {
// 报告先到:保存候选结果,等宿主终态
const reported = decide(runningTask(), { kind: 'report', report: goodReport }, { now: clock })
assert.equal(reported.applied, true)
assert.equal(reported.task.status, 'running', '报告先到不得直接置完成')
assert.ok(reported.task.reportReceivedAt !== null)
// 只有报告、终态尚未到达 —— 保持 running
const pending = evaluateCompletion(runningTask(), { report: goodReport, runTerminal: null })
assert.equal(pending.applied, false)
assert.equal(pending.task.status, 'running')
assert.ok(pending.reason.includes('宿主运行尚未结束'))
// 报告到达后终态成功 → 顺理成章完成
const finished = decide(reported.task, { kind: 'run_terminal', runTerminal: 'succeeded' }, { now: clock })
assert.equal(finished.applied, true)
assert.equal(finished.task.status, 'completed')
})
test('完成判定三分支:只有终态 → needs_attention', () => {
// 宿主运行先结束但无报告
const onlyTerminal = evaluateCompletion(runningTask(), { report: null, runTerminal: 'succeeded' }, { now: clock })
assert.equal(onlyTerminal.applied, true)
assert.equal(onlyTerminal.task.status, 'needs_attention')
assert.match(onlyTerminal.task.needsAttentionReason, /没有有效的结构化报告/)
// 运行失败同样进入 needs_attention,而不是 completed
const failed = decide(runningTask(), { kind: 'run_terminal', runTerminal: 'failed' }, { now: clock })
assert.equal(failed.task.status, 'needs_attention')
assert.match(failed.task.needsAttentionReason, /failed/)
// 终态成功但报告不完整:也不能置完成,最多进入 needs_attention 等补报
const partial = evaluateCompletion(runningTask(), { report: { attemptId: 'att_1' }, runTerminal: 'succeeded' })
assert.notEqual(partial.task.status, 'completed')
assert.equal(partial.task.status, 'needs_attention')
})
test('运行终态为 cancelled 时任务直接取消', () => {
const decision = decide(runningTask(), { kind: 'run_terminal', runTerminal: 'cancelled' }, { now: clock })
assert.equal(decision.task.status, 'cancelled')
assert.ok(decision.task.endedAt)
})
test('乱序事件:旧 seq 不回退,迟到 running 不覆盖终态', () => {
assert.equal(isStaleSeq(null, 5), false)
assert.equal(isStaleSeq(5, 5), true, '同 seq 视为重复')
assert.equal(isStaleSeq(5, 4), true)
assert.equal(isStaleSeq(5, 6), false)
assert.equal(isStaleSeq(5, Number.NaN), true)
const withSeq = { ...runningTask(), lastSeq: 10 }
const stale = decide(withSeq, { kind: 'input_required', reason: '旧事件', seq: 9 }, { now: clock })
assert.equal(stale.applied, false)
assert.equal(stale.stale, true)
assert.equal(stale.task.status, 'running')
const done = evaluateCompletion(
{ ...withSeq, lastSeq: 11 },
{ report: goodReport, runTerminal: 'succeeded', seq: 12 },
{ now: clock },
)
assert.equal(done.task.status, 'completed')
assert.equal(done.task.lastSeq, 12)
const late = decide(done.task, { kind: 'input_required', reason: '迟到的求助', seq: 13 }, { now: clock })
assert.equal(late.applied, false)
assert.equal(late.task.status, 'completed', '终态不能被迟到事件覆盖')
// 终态之后即使 seq 更大也只记 no-op:调用方据此知道「没有状态变化」
assert.match(late.reason, /不接受|已终态/)
assert.equal(isRegressingEvent('completed', 'running'), true)
assert.equal(isRegressingEvent('completed', 'completed'), false)
assert.equal(isRegressingEvent('running', 'running'), false)
})
test('waiting_input 往返与非法事件', () => {
const asked = requestInput(runningTask(), '缺口径', { now: clock })
assert.equal(asked.task.status, 'waiting_input')
assert.equal(asked.task.waitingReason, '缺口径')
const back = supplyInput(asked.task, { now: clock })
assert.equal(back.task.status, 'running')
assert.equal(back.task.waitingReason, null)
assert.equal(supplyInput(back.task).applied, false, '不在待补充时忽略')
assert.equal(requestInput(draftTask(), 'x').applied, false)
assert.throws(() => decide(runningTask(), { kind: 'nope' }), /未知事件类型/)
assert.throws(() => decide(runningTask(), null), /事件必须是对象/)
assert.throws(() => decide({}, { kind: 'report' }), /任务记录不合法/)
assert.throws(
() => decide(runningTask(), { kind: 'report', report: { summary: '' } }),
(error) => error.code === 'INVALID_REPORT',
)
assert.throws(
() => decide({ ...runningTask(), status: 'failed' }, { kind: 'retry' }),
(error) => error.code === 'RETRY_REQUIRES_NEW_TASK',
)
assert.equal(decide(runningTask(), { kind: 'retry' }).applied, false)
})
test('failTask 必须带原因,终态后忽略', () => {
const failed = failTask(runningTask(), '模型超时', { now: clock })
assert.equal(failed.task.status, 'failed')
assert.equal(failed.task.failureReason, '模型超时')
assert.ok(failed.task.endedAt)
assert.throws(() => failTask(runningTask(), ' '), /reason/)
assert.equal(failTask(failed.task, 'again').applied, false)
})
test('cancelTask 记录取消原因且只写一次结束时间', () => {
const cancelled = cancelTask(runningTask(), '用户点了取消', { now: clock })
assert.equal(cancelled.task.status, 'cancelled')
assert.equal(cancelled.task.cancelReason, '用户点了取消')
const again = cancelTask(cancelled.task, '重复取消')
assert.equal(again.applied, false)
assert.equal(again.task.endedAt, cancelled.task.endedAt)
assert.equal(cancelTask(draftTask()).task.cancelReason, '用户取消')
})
test('completeTask 是 completion 事件的便捷包装', () => {
const decision = completeTask(
runningTask(),
{ report: goodReport, runTerminal: 'succeeded', artifactRefs: ['art_1'], artifactLookup: () => ({ id: 'art_1' }), seq: 3 },
)
assert.equal(decision.task.status, 'completed')
assert.equal(decision.task.lastSeq, 3)
})
test('applyDecision 只在 applied 时落库', () => {
const store = new WorkbenchStore({ file: null, clock, random: () => 3 })
const projectId = store.createProject({ hostWorkspaceId: 'ws-a' })
const created = createTask(
{ projectId, title: 't', objective: 'o', ownerRoleId: 'hubu' },
{ newTaskId: () => 'task_1', now: clock },
)
store.insertTask(created)
const queued = startTask(store.getTask('task_1'), { now: clock })
const stale = applyDecision(store, 'task_1', { applied: false, stale: true, task: created })
assert.equal(stale.applied, false)
assert.equal(store.getTask('task_1').revision, 1, '陈旧事件不得产生版本抖动')
const started = applyDecision(store, 'task_1', { applied: true, stale: false, task: queued })
assert.equal(started.task.status, 'queued')
assert.equal(store.getTask('task_1').status, 'queued')
// null 会被默认参数换成 undefined,所以显式传 undefined 才能走到 store 校验
assert.throws(() => applyDecision(undefined, 'task_1', {}), /需要 store/)
// 未启用的事件不得落库:返回原判定,store 保持 revision 不变
assert.equal(applyDecision(store, 'task_1', { applied: false, task: queued }).task.status, 'queued')
assert.throws(() => applyDecision(store, 'task_1', null), /判定结果不合法/)
})
test('isOpenTask 区分终态与活动态', () => {
assert.equal(isOpenTask(draftTask()), true)
assert.equal(isOpenTask(cancelTask(draftTask()).task), false)
assert.equal(isOpenTask(null), false)
assert.equal(isOpenTask({ status: 'bogus' }), false)
})