@twinsearth/dsh-master 3.3.3 → 3.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/dsh-master",
-  "version": "3.3.3",
+  "version": "3.3.5",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -37,6 +37,10 @@
     "./contract": "./dist-host/contract/index.js",
     "./cost-optimizer": "./dist-host/plugins/cost-optimizer.js",
     "./dual-manager": "./dist-host/plugins/dual-manager.js",
+    "./pm-agent": "./dist-host/agents/pm-agent.js",
+    "./pjm-agent": "./dist-host/agents/pjm-agent.js",
+    "./engine": "./dist-host/engine/index.js",
+    "./channel/stream-state": "./dist-host/channel/stream-state.js",
     "./client": {
       "browser": "./client.js",
       "default": "./client.js"

package/src/agents/pjm-agent.ts

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+import { PJM_SYSTEM_PROMPT } from './prompts.ts'
+import { dualService, dualUnavailable, id, installAgent, jsonTool, objectSchema, objects, string, strings } from './toolkit.ts'
+
+export const name = 'dsh-master-pjm-agent'
+export const inject = ['systemPrompt', 'tools']
+
+/** PJM preset：项目计划、节点、隔离派发、结案；不替 PM 决定需求。 */
+export function apply(ctx) {
+  const dual = () => dualService(ctx)
+  const tools = [
+    jsonTool('pjm_create_plan', '把已确认 PRD 拆成 WBS 与七类项目计划；给 handoffId 时同时完成接单。', objectSchema({
+      prdId: id('PRD id'), handoffId: id('可选：PM 交接包 id'), title: string('项目计划标题'), how: string('实施路径'), where: string('执行场景'),
+      projectReview: strings('项目会审结论'), requirements: strings('项目需求与内容'),
+      steps: objects('WBS：id/title/prompt/owner/where/estimateMinutes/dependsOn/acceptance/kind'),
+      schedule: { type: 'object', description: 'startAt 与 milestones[]（title/owner/estimateMinutes/dependsOn）', additionalProperties: true },
+      team: objects('人员：role/owner/responsibility'),
+      quality: { type: 'object', description: 'tests[] / deployment[] / acceptance[]', additionalProperties: true },
+    }, ['prdId', 'steps']), async (args) => dual() ? dual().pjm.plan(args.prdId, args) : dualUnavailable()),
+    jsonTool('pjm_take_handoff', '接单：只有 PM 标记 ready 的交接包可以接走；needs-clarification 必须退回 PM。', objectSchema({
+      handoffId: id('交接包 id'), planId: id('可选：关联计划 id'),
+    }, ['handoffId']), async (args) => dual() ? dual().pjm.takeHandoff(args.handoffId, args) : dualUnavailable()),
+    jsonTool('pjm_report', '节点自反馈：执行中随时汇报进展/阻塞，blocked 必须写原因。', objectSchema({
+      planId: id('计划 id'), summary: string('节点摘要'),
+      status: { type: 'string', enum: ['progress', 'blocked', 'done'] },
+      stepId: id('可选：关联步骤'), blocker: string('阻塞原因（blocked 必填）'), evidence: strings('证据'),
+    }, ['planId', 'summary']), async (args) => dual() ? dual().pjm.report(args.planId, args) : dualUnavailable()),
+    jsonTool('pjm_submit_feedback', '项目级自反馈：计划全部步骤完成后提交给 PM 复核，写清交付、偏差、遗留问题与测试。', objectSchema({
+      planId: id('计划 id'), summary: string('执行总结（必填）'),
+      deviations: strings('相对计划的偏差'), openIssues: strings('遗留问题'), tests: strings('测试证据'),
+    }, ['planId', 'summary']), async (args) => dual() ? dual().pjm.submitFeedback(args.planId, args) : dualUnavailable()),
+    jsonTool('pjm_dispatch_step', '通过 fangForker.spawn 在隔离分身中执行一个 WBS 步骤；不可用会 fail-closed，不在宿主本地执行。', objectSchema({
+      planId: id('计划 id'), stepId: id('步骤 id'),
+    }, ['planId', 'stepId']), async (args) => dual() ? await dual().pjm.dispatch(args.planId, { stepId: args.stepId }) : dualUnavailable()),
+    jsonTool('pjm_complete_step', '记录步骤完成/失败、证据与实际用时；不得把失败写成完成。', objectSchema({
+      planId: id('计划 id'), stepId: id('步骤 id'),
+      status: { type: 'string', enum: ['done', 'failed'] }, summary: string('结果摘要'),
+      evidence: strings('测试/文件/报告证据'), actualMinutes: { type: 'number', description: '实际用时（分钟）' },
+    }, ['planId', 'stepId', 'status']), async (args) => dual() ? dual().pjm.completeStep(args.planId, args.stepId, args) : dualUnavailable()),
+    jsonTool('pjm_check_step', '查单个步骤真实状态：派发/执行/汇报、证据、用时与关联报告。结果来自计划与节点汇报，不是 VM 作业队列。', objectSchema({
+      planId: id('计划 id'), stepId: id('步骤 id'),
+    }, ['planId', 'stepId']), async (args) => dual() ? dual().pjm.checkStep(args.planId, args.stepId) : dualUnavailable()),
+    jsonTool('pjm_next_action', '读计划状态，返回 PJM 下一步唯一推荐动作与理由（纯建议，不执行）。', objectSchema({ planId: id('计划 id') }, ['planId']), async (args) => dual() ? dual().pjm.nextAction(args.planId) : dualUnavailable()),
+    jsonTool('pjm_project_status', '读取项目看板：完成/进行/待办/失败、估时、实际用时、是否可结案。', objectSchema({ planId: id('计划 id') }, ['planId']), async (args) => dual() ? dual().pjm.progress(args.planId) : dualUnavailable()),
+    jsonTool('pjm_write_project', '把项目计划与当前节点写成 workspace/docs/pjm 下的 Markdown。', objectSchema({ planId: id('计划 id') }, ['planId']), async (args, exec) => dual() ? await dual().pjm.writeProject(args.planId, { agent: exec.agent }) : dualUnavailable()),
+    jsonTool('pjm_close_project', '全部步骤完成后结案：写入总结、评审报告、验收与资料清单，并可生成结案文档。', objectSchema({
+      planId: id('计划 id'), summary: string('结案总结（必填）'), reviewReport: string('评审报告'),
+      acceptance: strings('验收记录'), artifacts: strings('项目资料路径'), write: { type: 'boolean', description: '是否同时写结案 Markdown，默认 true' },
+    }, ['planId', 'summary']), async (args, exec) => {
+      if (!dual()) return dualUnavailable()
+      const closed = dual().pjm.close(args.planId, args)
+      if (!closed.ok) return closed
+      if (args.write === false) return closed
+      const document = await dual().pjm.writeClosure(args.planId, { agent: exec.agent })
+      return { ...closed, document }
+    }),
+  ]
+  return installAgent(ctx, { prompt: PJM_SYSTEM_PROMPT, tools })
+}

package/src/agents/pm-agent.ts

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+import { PM_SYSTEM_PROMPT } from './prompts.ts'
+import { dualService, dualUnavailable, id, installAgent, jsonTool, objectSchema, objects, string, strings } from './toolkit.ts'
+
+export const name = 'dsh-master-pm-agent'
+export const inject = ['systemPrompt', 'tools']
+
+/** PM preset：只提供需求/盘点/文档工具，不提供任何执行或派生能力。 */
+export function apply(ctx) {
+  const dual = () => dualService(ctx)
+  const tools = [
+    jsonTool('pm_create_prd', '创建结构化产品需求文档（WHY/WHAT/模块/约束/验收），返回 PRD id。', objectSchema({
+      title: string('需求标题'), goal: string('要解决的问题与目标'),
+      why: string('背景与价值'), what: strings('功能范围'), architecture: string('架构说明'),
+      outcomes: strings('预期结果'), modules: objects('模块：name/result/architecture/status'),
+      priority: { type: 'string', enum: ['low', 'normal', 'high', 'critical'] },
+      constraints: strings('约束'), acceptance: strings('验收标准'), nonGoals: strings('非目标'),
+      assumptions: strings('假设'), openQuestions: strings('待澄清问题'), requester: string('请求方'),
+    }, ['title', 'goal']), async (args) => dual() ? dual().pm.createPrd(args) : dualUnavailable()),
+    jsonTool('pm_create_assessment', '保存六类产品现状盘点。completed 每项必须附 evidence；其它类给原因、计划、冲突或歧义。', objectSchema({
+      prdId: id('可选：关联的 PRD id'), title: string('盘点标题'), why: string('目标'), what: strings('范围'),
+      completed: objects('已完成：title/progress/evidence[]（证据必填）'),
+      unfinished: objects('未完成：title/reason/nextStep/progress'),
+      blocked: objects('受阻：title/reason/blocker/nextStep'),
+      planned: objects('已计划：title/plan/estimateMinutes/priority'),
+      conflicts: objects('冲突：title/question/options[{value,label,consequence}]'),
+      ambiguities: objects('歧义：title/question/currentInterpretation'),
+    }, ['title']), async (args) => dual() ? dual().pm.createAssessment(args) : dualUnavailable()),
+    jsonTool('pm_write_prd', '把 PRD（可带六类盘点）写成 workspace/docs/pm 下的 Markdown，返回文档路径。', objectSchema({
+      prdId: id('PRD id'), assessmentId: id('可选：关联的 Assessment id'),
+    }, ['prdId']), async (args, exec) => dual() ? await dual().pm.writePrd(args.prdId, { assessmentId: args.assessmentId, agent: exec.agent }) : dualUnavailable()),
+    jsonTool('pm_handoff_to_pjm', '把 PRD（可带盘点）打成交接包交给 PJM。有未决问题或冲突时不给 ready，必须先澄清。', objectSchema({
+      prdId: id('PRD id'), assessmentId: id('可选：关联的盘点 id'),
+      acceptance: strings('可选：覆盖 PRD 的验收标准'), openQuestions: strings('可选：补充未决问题'),
+    }, ['prdId']), async (args) => dual() ? dual().pm.createHandoff(args.prdId, args) : dualUnavailable()),
+    jsonTool('pm_review_feedback', '复核 PJM 的执行反馈：逐条验收给 met 布尔与证据，写复盘与总结；结论必须与验收一致。', objectSchema({
+      feedbackId: id('PJM 反馈 id'),
+      acceptanceChecks: objects('逐条验收：criterion/met(boolean)/evidence[]/note'),
+      verdict: { type: 'string', enum: ['accepted', 'changes-requested'] },
+      retrospective: { type: 'object', description: 'kept[] / improve[] / lessons[]', additionalProperties: true },
+      summary: string('复核总结（必填）'),
+      write: { type: 'boolean', description: '是否同时写复核文档，默认 true' },
+    }, ['feedbackId', 'acceptanceChecks', 'summary']), async (args, exec) => {
+      if (!dual()) return dualUnavailable()
+      const reviewed = dual().pm.reviewFeedback(args.feedbackId, args)
+      if (!reviewed.ok || args.write === false) return reviewed
+      const document = await dual().pm.writeReview(reviewed.review.id, { agent: exec.agent })
+      return { ...reviewed, document }
+    }),
+    jsonTool('pm_pipeline', '读一个 PRD 的闭环状态：drafted → handoff-ready / needs-clarification → planning → feedback → accepted / changes-requested。', objectSchema({ prdId: id('PRD id') }, ['prdId']), async (args) => dual() ? dual().pm.pipeline(args.prdId) : dualUnavailable()),
+    jsonTool('pm_next_action', '读闭环状态，返回 PM 下一步唯一推荐动作与理由（纯建议，不执行）。', objectSchema({ prdId: id('PRD id') }, ['prdId']), async (args) => dual() ? dual().pm.nextAction(args.prdId) : dualUnavailable()),
+    jsonTool('pm_list_prds', '列出当前 Host 中的 PRD、六类盘点、交接包与复核索引。', objectSchema({}), async () => dual() ? ({ ok: true, prds: dual().pm.listPrds().items, assessments: dual().pm.listAssessments().items, handoffs: dual().pm.listHandoffs().items, reviews: dual().pm.listReviews().items }) : dualUnavailable()),
+  ]
+  return installAgent(ctx, { prompt: PM_SYSTEM_PROMPT, tools })
+}

package/src/agents/prompts.ts

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+export const PM_AGENT_ID = 'master-pm'
+export const PJM_AGENT_ID = 'master-pjm'
+
+export const PM_SYSTEM_PROMPT = String.raw`# Role
+你是 DSH-Master「房主」的产品经理 Agent（PM，preset: master-pm）。你把用户和开发者的大白话转换成可核对、可验收的产品需求与文档。
+
+# Goals — WHY / WHAT
+1. WHY：说清解决什么问题、为什么值得做、达成什么目标。
+2. WHAT：说清功能、模块、架构、预期结果、约束、非目标和验收标准。
+3. 对现状做证据驱动的六类盘点：已完成、未完成、无法实现/受阻、已计划、冲突、歧义。
+
+# Workflow
+1. 先识别目标、范围、约束和未决项；重大歧义或不可逆选择必须用 ask_user_question 提出一个具体决策点，给 2–4 个选项并标推荐项。不要为琐碎实现细节打断用户。
+2. 盘点前先用 read/grep/glob 读取真实代码、测试和文档。没有证据的“完成”不得写 100%，不得把设计稿当成已交付。
+3. 用 pm_create_prd 保存结构化 PRD；用 pm_create_assessment 保存六类盘点。每个 completed 项必须附文件、测试或报告证据。
+4. 用 pm_write_prd 生成 Markdown 文档；需要用户打开时用 present 交付。
+5. **交接**：确认 PRD 有验收标准、且没有未决问题/冲突后，用 pm_handoff_to_pjm 交接给 PJM；不 ready 时先回去澄清，不得硬塞。
+6. **复核闭环**：PJM 提交反馈后用 pm_review_feedback 逐条核对验收（met + 证据），写复盘（kept/improve/lessons）与总结；结论必须与验收一致（有未达标就 changes-requested）。
+7. 用 pm_pipeline 查闭环阶段（drafted → handoff-ready → planning → feedback → accepted / changes-requested）。
+8. 不确定下一步时先调 pm_next_action：它给出唯一推荐动作（create_prd / create_assessment / clarify / handoff / review / done / blocked）与理由；按它走，不要自己跳步。
+
+# Rules
+- 不臆测、不伪造证据、不把“可以实现”写成“已经完成”。
+- 冲突必须列出冲突双方、影响、可选方案和需要用户重新判断的问题。
+- 歧义必须写出当前理解与待确认问题；用户未回答前不得把该理解当成事实。
+- PM 不写生产代码、不跑 shell、不发布、不安装、不调度 VM/分身。
+- 只有 PM 能复核 PJM 的交付；不得自己给自己复核，也不得替 PJM 编造执行结果。
+- 只写 PRD/盘点/复核文档；不改需求范围外的文件。
+
+# Output Format
+默认用简洁 Markdown 汇报，必须按任务需要包含：
+- WHY & WHAT
+- 六类现状矩阵：completed / unfinished / blocked / planned / conflicts / ambiguities
+- 冲突与歧义的用户决策点
+- 已保存的 PRD/Assessment id 与文档路径
+只输出已核实内容；未知、未验证、受限分别标明。`
+
+export const PJM_SYSTEM_PROMPT = String.raw`# Role
+你是 DSH-Master「房主」的项目经理 Agent（PJM，preset: master-pjm）。你把已确认的 PRD 变成可执行、可追踪、可验收的项目计划，并按节点汇报直至结案。
+
+# Goals — HOW / WHO / WHERE / WHEN
+1. HOW：把 PRD 拆成 WBS，每步写清 prompt、依赖、验收、估时。
+2. WHO：给每一步分配 owner 与责任；未分配必须写 unassigned，不得虚构人员。
+3. WHERE：明确执行场景（宿主、fork、workspace、DSH Web）；脏任务只能在隔离执行体中运行。
+4. WHEN：给里程碑与估时；估时是计划，不是承诺工期。
+
+# Workflow
+1. 项目会审：核对 PRD、验收标准、约束、未决问题；未决项未解决不得自行扩权。
+2. 接单：收到 PM 交接包后用 pjm_take_handoff 或 pjm_create_plan({handoffId}) 接单；交接包 needs-clarification 时退回 PM，不得硬开工。
+3. 用 pjm_create_plan 建立七类项目内容：项目会审、WBS、需求内容、时间、人员、测试部署验收、结案。
+4. 执行前申请隔离资源，通过 pjm_dispatch_step 走 fangForker.spawn；不可用就 fail-closed，绝不在母体/原身本地降级执行，不虚构 vm_create/vm_exec。
+5. **节点自反馈**：执行中随时用 pjm_report 汇报进展/阻塞（blocked 必须写原因）。
+6. **提交反馈**：全部步骤完成后用 pjm_submit_feedback 把交付、偏差、遗留问题、测试证据交给 PM 复核；不得在未完成时提交。
+7. 用 pjm_project_status 汇总节点，用 todo_write 跟踪当前工作；完成步骤时记录 summary/evidence/actualMinutes。
+8. 用 pjm_write_project 保存计划与节点报告。全部步骤完成后才能 pjm_close_project；结案必须有总结、验收记录、评审报告和资料清单，并交付文档。
+9. 不确定下一步时先调 pjm_next_action：它给出唯一推荐动作（take_handoff / return_to_pm / create_plan / dispatch / report / complete_feedback / close / done）与理由；按它走，不要跳步或重复派发。
+
+# Rules
+- 按时、按质、按量报告真实状态；失败、阻塞、未测量不得包装成完成。
+- 不发布、不部署到生产、不修改 profile、不触碰凭据，除非用户对该动作另行明确授权。
+- 不代替 PM 决定需求，不替用户回答选择题；阻塞时给出原因、影响、可选方案和所需决策。
+- 不给自己复核：交付是否正确由 PM 复核；PM 判 changes-requested 时按新的验收项重做。
+- 不做无限轮询；节点汇报写完成/进行/待办/失败及下一步。
+
+# Output Format
+- 项目会审与范围
+- WBS 看板（Todo / In Progress / Done / Failed）
+- Owner、场景、估时、实际用时与依赖
+- 测试/部署/交付/验收证据
+- 结案：评审报告、验收记录、资料汇总
+- 仍需人类决策的事项（如有）`

package/src/agents/toolkit.ts

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+import { SERVICE, masterError, safeGet } from '../kernel.ts'
+
+export function dualService(ctx) {
+  const service = safeGet(ctx, SERVICE.dual)
+  return service && service.pm && service.pjm ? service : null
+}
+
+export function dualUnavailable() {
+  return masterError('dual-service-unavailable', 'dshMasterDual is required; enable master-dual-manager in this Host')
+}
+
+/** 注册一个返回结构化 JSON 的模型工具；异常也转成具名错误，不吞掉。 */
+export function jsonTool(name, description, parameters, execute) {
+  return {
+    name,
+    description,
+    parameters,
+    output: {
+      schema: { type: 'object' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+    },
+    async execute(args, exec) {
+      try { return await execute(args && typeof args === 'object' ? args : {}, exec) }
+      catch (error) { return masterError('agent-tool-threw', String(error?.message ?? error), { tool: name }) }
+    },
+  }
+}
+
+/** 在 preset scope 内挂 persona 与 scoped tools，全部纳入 Cordis effect 生命周期。 */
+export function installAgent(ctx, { prompt, tools }) {
+  const systemPrompt = safeGet(ctx, 'systemPrompt')
+  const registry = safeGet(ctx, 'tools')
+  if (!systemPrompt || typeof systemPrompt.section !== 'function') {
+    return { ok: false, code: 'system-prompt-unavailable', error: 'ctx.systemPrompt with section() is required' }
+  }
+  if (!registry || typeof registry.register !== 'function') {
+    return { ok: false, code: 'tools-unavailable', error: 'ctx.tools with register() is required' }
+  }
+  const registered = []
+  try {
+    ctx.effect(() => systemPrompt.section({ name: 'deployment:persona-prefix', order: 0, text: prompt }))
+  } catch (error) {
+    return { ok: false, code: 'prompt-registration-failed', error: String(error?.message ?? error) }
+  }
+  for (const definition of tools) {
+    try {
+      ctx.effect(() => registry.register(definition))
+      registered.push(definition.name)
+    } catch (error) {
+      return { ok: false, code: 'tool-registration-failed', error: String(error?.message ?? error), tool: definition.name, registered }
+    }
+  }
+  return { ok: true, tools: registered }
+}
+
+export const objectSchema = (properties = {}, required = []) => ({ type: 'object', properties, required, additionalProperties: true })
+export const string = (description = '') => ({ type: 'string', description })
+export const strings = (description = '') => ({ type: 'array', items: { type: 'string' }, description })
+export const objects = (description = '') => ({ type: 'array', items: { type: 'object', additionalProperties: true }, description })
+export const id = (description) => ({ type: 'string', description })

package/src/channel/abort-registry.ts

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+/**
+ * 流式生成的取消登记表（3.3.5）。
+ *
+ * 为什么单独抽出来：中断的正确性取决于「谁在跑、谁负责停、停完是否清理」。
+ * 把它写成可测原语后，通道、会话桥、演示生产者都能复用同一套语义。
+ *
+ * 语义：
+ *   * `begin(key)` 拿到 `{ key, signal, abort, end }`；同一个 key 重复 begin 会**先中止旧的**（新的一轮覆盖旧的）。
+ *   * `abort(key)` 触发 signal 并保留登记，直到 `end()` 才真正清理 —— 这样“已中止但尚未收尾”可被观察。
+ *   * `end(key)` 幂等清理；调用后 `has(key)` 为 false。
+ *   * `abortAll()` 用于连接关闭 / 插件卸载，保证没有僵尸流。
+ *   * 所有方法都不抛（除了传入非法 key 返回 false）。
+ */
+
+export function createAbortRegistry() {
+  const entries = new Map()
+
+  function begin(key, { onAbort } = {}) {
+    const id = String(key ?? '')
+    if (!id) throw new Error('abort-registry: key is required')
+    // 同一 key 上已有生成：先中止旧的，避免两路流同时往同一个消息里写
+    const previous = entries.get(id)
+    if (previous) {
+      previous.abort('superseded')
+    }
+    const controller = new AbortController()
+    const entry = {
+      key: id,
+      controller,
+      signal: controller.signal,
+      aborted: false,
+      reason: null,
+      startedAt: Date.now(),
+      endedAt: null,
+    }
+    controller.signal.addEventListener('abort', () => {
+      entry.aborted = true
+      try { onAbort?.(entry.reason ?? controller.signal.reason ?? 'aborted') } catch { /* 回调异常不影响中止 */ }
+    }, { once: true })
+    entry.abort = (reason = 'user-interrupt') => {
+      if (controller.signal.aborted) return false
+      try { controller.abort(reason) } catch { /* ignore */ }
+      entry.reason = String(reason)
+      return true
+    }
+    entry.end = () => {
+      if (entries.get(id) === entry) entries.delete(id)
+      entry.endedAt = Date.now()
+      return true
+    }
+    entries.set(id, entry)
+    return entry
+  }
+
+  return {
+    begin,
+    has: (key) => entries.has(String(key ?? '')),
+    get: (key) => entries.get(String(key ?? '')) ?? null,
+    /** 中止并返回是否真的发生了中止。 */
+    abort: (key, reason = 'user-interrupt') => {
+      const entry = entries.get(String(key ?? ''))
+      if (!entry) return false
+      return entry.abort(reason)
+    },
+    abortAll: (reason = 'shutdown') => {
+      const aborted = []
+      for (const entry of entries.values()) {
+        if (entry.abort(reason)) aborted.push(entry.key)
+      }
+      return aborted
+    },
+    /** 结束并清理（幂等）。 */
+    end: (key) => {
+      const entry = entries.get(String(key ?? ''))
+      if (!entry) return false
+      return entry.end()
+    },
+    keys: () => [...entries.keys()],
+    size: () => entries.size,
+  }
+}

package/src/channel/protocol.ts

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+/**
+ * 智囊团通道协议（3.3.5）。
+ *
+ * 客户端 → 服务端：
+ *   { type: 'ping' }
+ *   { type: 'resync' }                          → 重新推一次快照
+ *   { type: 'chat', content: string, agent?: 'pm'|'pjm' }
+ *   { type: 'answer', callId: string, value: string }   ← 目前会返回 session-prompt-unavailable
+ *
+ * 服务端 → 客户端：
+ *   { type: 'hello', ... }                     连接建立（含协议版本与可用性）
+ *   { type: 'dual', snapshot }                 交接/计划/反馈/复核快照
+ *   { type: 'pong', at }
+ *   { type: 'error', code, message, detail? }
+ *
+ * 为什么 chat/answer 现在只返回错误：见 docs/CHANNEL-WEBSOCKET.md。
+ * 插件侧没有「向指定 preset 会话提交用户消息」的 Host API；假装能聊就是假聊天。
+ */
+
+export const CHANNEL_PROTOCOL_VERSION = 1
+export const CHANNEL_MAX_MESSAGE_BYTES = 64 * 1024
+export const CLIENT_MESSAGE_TYPES = Object.freeze(['ping', 'resync', 'chat', 'answer', 'interrupt'])
+
+function text(value) { return String(value ?? '').trim() }
+
+/**
+ * 解析并校验一条客户端消息；非法输入给出具名错误而不是抛。
+ */
+export function parseClientMessage(raw) {
+  if (typeof raw === 'string' && raw.length > CHANNEL_MAX_MESSAGE_BYTES) {
+    return { ok: false, code: 'message-too-large', error: `message exceeds ${CHANNEL_MAX_MESSAGE_BYTES} bytes` }
+  }
+  let body = null
+  if (typeof raw === 'string') {
+    try { body = JSON.parse(raw) } catch { return { ok: false, code: 'invalid-json', error: 'message must be JSON' } }
+  } else if (raw && typeof raw === 'object') {
+    body = raw
+  } else {
+    return { ok: false, code: 'invalid-message', error: 'message must be a JSON object' }
+  }
+  const type = text(body.type)
+  if (!CLIENT_MESSAGE_TYPES.includes(type)) {
+    return { ok: false, code: 'unknown-type', error: `unknown message type: ${type || '(empty)'}`, types: CLIENT_MESSAGE_TYPES }
+  }
+  if (type === 'chat') {
+    const content = text(body.content)
+    if (!content) return { ok: false, code: 'content-required', error: 'chat requires content' }
+    if (content.length > 8_000) return { ok: false, code: 'content-too-long', error: 'chat content exceeds 8000 characters' }
+    const agent = text(body.agent) || 'pm'
+    if (!['pm', 'pjm'].includes(agent)) return { ok: false, code: 'agent-invalid', error: 'agent must be pm or pjm' }
+    return { ok: true, message: { type, content, agent } }
+  }
+  if (type === 'answer') {
+    const callId = text(body.callId)
+    const value = text(body.value)
+    if (!callId || !value) return { ok: false, code: 'answer-incomplete', error: 'answer requires callId and value' }
+    return { ok: true, message: { type, callId, value } }
+  }
+  if (type === 'interrupt') {
+    // messageId 可选：省略表示“这一连接上所有正在生成的流都停”
+    const messageId = text(body.messageId)
+    return { ok: true, message: { type, messageId: messageId || null } }
+  }
+  return { ok: true, message: { type } }
+}
+
+/** 中断确认：`aborted` 表示是否真的掐断了一条在跑的流。 */
+export function interruptedMessage({ messageId, savedContent = '', aborted = true } = {}) {
+  return {
+    type: 'interrupted',
+    messageId: text(messageId) || null,
+    savedContent: String(savedContent ?? ''),
+    aborted: aborted === true,
+    at: Date.now(),
+  }
+}
+
+export function serverHello({ channelId, tokenRequired = true } = {}) {
+  return {
+    type: 'hello',
+    protocol: CHANNEL_PROTOCOL_VERSION,
+    channelId: text(channelId) || 'dsh-master-command-center',
+    capabilities: {
+      dualSnapshot: true,
+      chat: false,
+      answer: false,
+    },
+    limitations: {
+      chat: 'plugin cannot submit a user message into a preset agent session',
+      answer: 'user questions are answered inside their owning session',
+    },
+    tokenRequired: tokenRequired === true,
+    serverTime: Date.now(),
+  }
+}
+
+export function serverError(code, message, detail) {
+  const out = { type: 'error', code: text(code) || 'unknown', message: String(message ?? '') }
+  if (detail !== undefined) out.detail = detail
+  return out
+}
+
+/** 把 dual 快照包成通道消息（保持字段原样，不在这里加工业务语义）。 */
+export function dualMessage(snapshot) {
+  return { type: 'dual', snapshot: snapshot ?? null }
+}