@twinsearth/dsh-master 3.3.4 → 3.3.5

package/src/channel/stream-state.ts

@@ -0,0 +1,349 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+/**
+ * 流式消息状态机（3.3.5）。
+ *
+ * 结构（3.3.5 性能版）：**历史与当前流式分开**
+ *   state.history  —— 已定稿的消息数组，**引用稳定**：只有消息被定稿时才换新数组；
+ *   state.active   —— 当前正在流式的那条（或 null），每 chunk 只换这一个对象；
+ *   state.messages —— 兼容视图（history + active），供旧代码/简单渲染使用。
+ *
+ * 为什么要拆：每 chunk 都让 UI `map` 一遍上百条历史是 O(N) 的 reconciliation 开销，
+ * `React.memo` 只能省 DOM，省不了上层遍历。消费方应当：
+ *   * 历史列表订阅 `history`（引用没变就不重渲染）；
+ *   * 当前气泡只订阅 `active`（每次 chunk 只重渲染它）。
+ *
+ * 语义：
+ *   * 幂等：重复 `stream_start` 不新建第二条；重复 `card_choice` 原地更新；
+ *   * 容忍乱序：`stream_chunk` 早于 `stream_start` 只计数（orphan），不造数据；
+ *   * 块级锁：`card_*` 到达时先定稿当前气泡，再插入卡片，并释放流式槽位；
+ *   * 有界：历史条数、单条内容、选项数、快照大小都有上限。
+ */
+
+export const STREAM_LIMITS = Object.freeze({
+  maxMessages: 200,
+  maxContentChars: 200_000,
+  maxOptions: 20,
+  maxSnapshotBytes: 256 * 1024,
+})
+
+export const MESSAGE_KINDS = Object.freeze(['text', 'choice', 'doc', 'status', 'error'])
+
+function text(value) { return String(value ?? '') }
+
+function emptyState() {
+  return {
+    messages: [],
+    history: [],
+    active: null,
+    activeStreamId: null,
+    capabilities: null,
+    snapshot: null,
+    orphanChunks: 0,
+    ignored: 0,
+    truncated: 0,
+    lastError: null,
+  }
+}
+
+function capHistory(history) {
+  return history.length > STREAM_LIMITS.maxMessages
+    ? history.slice(history.length - STREAM_LIMITS.maxMessages)
+    : history
+}
+
+function capContent(content, truncatedBefore) {
+  const value = text(content)
+  if (value.length <= STREAM_LIMITS.maxContentChars) return { content: value, truncated: truncatedBefore }
+  return { content: value.slice(0, STREAM_LIMITS.maxContentChars), truncated: truncatedBefore + 1 }
+}
+
+/** 当前正在流式的那条消息；没有则 null。 */
+export function activeMessage(state) {
+  return state?.active ?? null
+}
+
+/** 是否有消息仍在流式输出（UI 据此切换“发送/停止”按钮）。 */
+export function isGenerating(state) {
+  return Boolean(state?.active && state.active.streaming === true)
+}
+
+/**
+ * 光标微状态（UI 直接消费，不要在组件里重复推导）：
+ *   * `thinking`   —— 收到 stream_start 但还没有第一个字：显示跳动点，不显示竖线；
+ *   * `streaming`  —— 正在吐字：竖线紧贴最后一个字符；
+ *   * `interrupted` —— 最近一条消息是被中止的：红色闪烁两次后收起；
+ *   * `idle`       —— 没有正在生成的内容。
+ */
+export function cursorState(state) {
+  if (state?.active && state.active.streaming === true) {
+    return text(state.active.content).length === 0 ? 'thinking' : 'streaming'
+  }
+  const history = Array.isArray(state?.history) ? state.history : []
+  const last = history.length > 0 ? history[history.length - 1] : null
+  if (last && last.interrupted === true) return 'interrupted'
+  return 'idle'
+}
+
+/**
+ * @param {{now?: () => number}} [options]
+ */
+export function createChatStream(options = {}) {
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  let state = emptyState()
+  const listeners = new Set()
+
+  const notify = () => { for (const listener of [...listeners]) { try { listener(state) } catch { /* 订阅者异常不影响状态机 */ } } }
+
+  /** 由 history + active 构造完整 state（messages 为兼容视图）。 */
+  function bundle(next, history, active) {
+    const trimmed = capHistory(history)
+    const activeValue = active ?? null
+    const messages = activeValue ? [...trimmed, activeValue] : trimmed
+    return {
+      ...state,
+      ...next,
+      history: trimmed,
+      active: activeValue,
+      activeStreamId: activeValue ? activeValue.id : null,
+      messages,
+    }
+  }
+
+  /** 把当前 active 定稿进 history（不改变 active 对象的 streaming 标记，调用方负责）。 */
+  function finalized(next, item) {
+    const active = state.active
+    const history = active ? [...state.history, { ...active, ...(item ?? {}) }] : state.history
+    return bundle(next, history, null)
+  }
+
+  function applyOne(message) {
+    const type = text(message?.type)
+    const id = text(message?.messageId ?? message?.id)
+
+    switch (type) {
+      case 'stream_start': {
+        if (!id) return state
+        const existingHistory = state.history.find((entry) => entry.id === id)
+        if (existingHistory) return state // 已定稿的同 id 消息不再复活
+        if (state.active && state.active.id === id) {
+          // 幂等：重复 start 保持同一条
+          return bundle({}, state.history, { ...state.active, streaming: true })
+        }
+        const role = text(message.role) === 'pjm' ? 'pjm' : 'pm'
+        const entry = { id, role, kind: 'text', content: '', streaming: true, at: now() }
+        const history = state.active ? [...state.history, { ...state.active, streaming: false }] : state.history
+        return bundle({}, history, entry)
+      }
+
+      case 'stream_chunk': {
+        if (!id) return state
+        if (!state.active || state.active.id !== id) {
+          return { ...state, orphanChunks: state.orphanChunks + 1 }
+        }
+        const content = `${text(state.active.content)}${text(message.delta)}`
+        const capped = capContent(content, state.truncated)
+        return bundle(
+          { truncated: capped.truncated },
+          state.history,
+          { ...state.active, content: capped.content, truncated: capped.content.length >= STREAM_LIMITS.maxContentChars },
+        )
+      }
+
+      case 'stream_end': {
+        if (!id) return state
+        if (!state.active || state.active.id !== id) return { ...state, orphanChunks: state.orphanChunks + 1 }
+        const full = text(message.fullContent)
+        const current = state.active
+        const finalContent = full.length > text(current.content).length
+          ? full.slice(0, STREAM_LIMITS.maxContentChars)
+          : current.content
+        const entry = {
+          ...current,
+          streaming: false,
+          interrupted: message.interrupted === true ? true : current.interrupted === true,
+          content: finalContent,
+        }
+        return bundle({}, [...state.history, entry], null)
+      }
+
+      case 'interrupted': {
+        if (!id) return state
+        if (!state.active || state.active.id !== id) return { ...state, orphanChunks: state.orphanChunks + 1 }
+        const saved = text(message.savedContent)
+        const current = state.active
+        const entry = {
+          ...current,
+          streaming: false,
+          interrupted: message.aborted !== false,
+          content: saved.length > text(current.content).length ? saved : current.content,
+        }
+        return bundle({}, [...state.history, entry], null)
+      }
+
+      case 'card_choice': {
+        if (!id) return state
+        const existing = state.history.findIndex((entry) => entry.id === id && entry.kind === 'choice')
+        const options = Array.isArray(message.options)
+          ? message.options.slice(0, STREAM_LIMITS.maxOptions).map((option) => (
+            typeof option === 'string' ? { label: option, value: option } : { label: text(option?.label), value: text(option?.value ?? option?.label) }
+          ))
+          : []
+        const card = {
+          id,
+          role: 'pm',
+          kind: 'choice',
+          content: text(message.question),
+          options,
+          answered: false,
+          answer: null,
+          streaming: false,
+          at: now(),
+        }
+        if (existing >= 0) {
+          const history = state.history.slice()
+          history[existing] = { ...history[existing], ...card }
+          return bundle({}, history, state.active)
+        }
+        const history = state.active
+          ? [...state.history, { ...state.active, streaming: false }, card]
+          : [...state.history, card]
+        return bundle({}, history, null)
+      }
+
+      case 'card_prd': {
+        if (!id) return state
+        const doc = {
+          id,
+          role: 'pm',
+          kind: 'doc',
+          content: text(message.title),
+          summary: text(message.summary ?? message.content ?? ''),
+          status: ['draft', 'approved', 'shipped'].includes(text(message.status)) ? text(message.status) : 'draft',
+          streaming: false,
+          at: now(),
+        }
+        const history = state.active
+          ? [...state.history, { ...state.active, streaming: false }, doc]
+          : [...state.history, doc]
+        return bundle({}, history, null)
+      }
+
+      case 'card_status': {
+        if (!id) return state
+        const progress = Math.max(0, Math.min(100, Number(message.progress) || 0))
+        const entry = {
+          id,
+          role: 'pjm',
+          kind: 'status',
+          content: text(message.content),
+          progress,
+          statusText: text(message.statusText),
+          streaming: false,
+          at: now(),
+        }
+        const existing = state.history.findIndex((item) => item.id === id && item.kind === 'status')
+        if (existing >= 0) {
+          const history = state.history.slice()
+          history[existing] = { ...history[existing], ...entry }
+          return bundle({}, history, state.active)
+        }
+        const history = state.active
+          ? [...state.history, { ...state.active, streaming: false }, entry]
+          : [...state.history, entry]
+        return bundle({}, history, null)
+      }
+
+      case 'error': {
+        const entry = {
+          id: id || `error-${now()}`,
+          role: 'system',
+          kind: 'error',
+          content: text(message.message),
+          code: text(message.code),
+          streaming: false,
+          at: now(),
+        }
+        const history = state.active
+          ? [...state.history, { ...state.active, streaming: false }, entry]
+          : [...state.history, entry]
+        return bundle({ lastError: entry }, history, null)
+      }
+
+      case 'dual': {
+        const snapshot = message.snapshot ?? null
+        let safeSnapshot = snapshot
+        try {
+          if (snapshot && JSON.stringify(snapshot).length > STREAM_LIMITS.maxSnapshotBytes) safeSnapshot = null
+        } catch { safeSnapshot = null }
+        return { ...state, snapshot: safeSnapshot }
+      }
+
+      case 'hello': {
+        return {
+          ...state,
+          capabilities: {
+            protocol: Number(message.protocol) || 0,
+            dualSnapshot: message?.capabilities?.dualSnapshot === true,
+            chat: message?.capabilities?.chat === true,
+            answer: message?.capabilities?.answer === true,
+            limitations: message?.limitations ?? null,
+          },
+        }
+      }
+
+      case 'pong':
+        return state
+
+      default:
+        return { ...state, ignored: state.ignored + 1 }
+    }
+  }
+
+  return {
+    getState: () => state,
+    apply: (message) => { state = applyOne(message); notify(); return state },
+    /**
+     * 用户回答选择题（本地乐观更新）：
+     *   * 只把那张卡片改成 answered 并写入 answer；
+     *   * 可选追加一条本地用户气泡（`local: true`）；
+     *   * history 换新数组，其余消息对象引用保持不变。
+     *   * 重复回答同一张卡片会被拒绝。
+     */
+    answerChoice: (messageId, value, options = {}) => {
+      const id = text(messageId)
+      const answer = text(value)
+      if (!id || !answer) return { ok: false, code: 'answer-incomplete', error: 'answerChoice requires messageId and value' }
+      const index = state.history.findIndex((entry) => entry.id === id)
+      if (index < 0) return { ok: false, code: 'choice-not-found', error: `no message with id ${id}` }
+      const current = state.history[index]
+      if (current.kind !== 'choice') return { ok: false, code: 'not-a-choice', error: `${id} is not a choice card` }
+      if (current.answered === true) return { ok: false, code: 'choice-already-answered', error: `choice ${id} was already answered` }
+      const history = state.history.slice()
+      history[index] = { ...current, answered: true, answer }
+      const echo = text(options.echo)
+      if (echo) {
+        history.push({ id: `local-${now()}`, role: 'user', kind: 'text', content: echo, local: true, streaming: false, at: now() })
+      }
+      state = bundle({}, history, state.active)
+      notify()
+      return { ok: true, state }
+    },
+    /** 批量应用，只通知一次（UI 可按帧 flush）。 */
+    applyBatch: (messages) => {
+      const list = Array.isArray(messages) ? messages : []
+      for (const message of list) state = applyOne(message)
+      if (list.length > 0) notify()
+      return state
+    },
+    /** 外部 store 订阅（配合 useSyncExternalStore）。返回取消订阅函数。 */
+    subscribe: (listener) => {
+      if (typeof listener !== 'function') return () => {}
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+    reset: () => { state = emptyState(); notify(); return state },
+  }
+}

package/src/channel/ws.ts

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+/**
+ * 最小 RFC 6455 服务端实现（不引入 `ws` 依赖）。
+ *
+ * 只覆盖本通道需要的能力：
+ *   * 握手：`Sec-WebSocket-Accept` = base64(sha1(key + GUID))；
+ *   * 收帧：客户端帧必须带掩码（RFC 要求），支持 7/16/64 位长度、分片续帧、close/ping/pong；
+ *   * 发帧：服务端文本帧不加掩码，另发 ping/close。
+ *
+ * 不做：permessage-deflate、二进制 payload 处理（收到即忽略）、扩展协商。
+ */
+
+import crypto from 'node:crypto'
+
+export const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
+export const WS_MAX_PAYLOAD = 256 * 1024
+
+export const OPCODE = Object.freeze({ continuation: 0x0, text: 0x1, binary: 0x2, close: 0x8, ping: 0x9, pong: 0xa })
+
+/** 计算握手 accept 值（RFC 6455 §1.3）。 */
+export function acceptKey(clientKey) {
+  return crypto.createHash('sha1').update(String(clientKey) + WS_GUID).digest('base64')
+}
+
+/** 是否是合法的 WebSocket 升级请求；返回具名原因以便拒绝时说明。 */
+export function validateUpgradeRequest(req) {
+  const headers = req?.headers ?? {}
+  const upgrade = String(headers.upgrade ?? '').toLowerCase()
+  const connection = String(headers.connection ?? '').toLowerCase()
+  const key = String(headers['sec-websocket-key'] ?? '').trim()
+  const version = String(headers['sec-websocket-version'] ?? '').trim()
+  if (upgrade !== 'websocket') return { ok: false, code: 'not-websocket-upgrade' }
+  if (!connection.split(',').map((part) => part.trim()).includes('upgrade')) return { ok: false, code: 'missing-connection-upgrade' }
+  if (!key || Buffer.from(key, 'base64').length !== 16) return { ok: false, code: 'invalid-websocket-key' }
+  if (version !== '13') return { ok: false, code: 'unsupported-websocket-version', version }
+  return { ok: true, key, accept: acceptKey(key) }
+}
+
+/** 生成 101 响应文本。 */
+export function upgradeResponse(accept) {
+  return [
+    'HTTP/1.1 101 Switching Protocols',
+    'Upgrade: websocket',
+    'Connection: Upgrade',
+    `Sec-WebSocket-Accept: ${accept}`,
+    '', '',
+  ].join('\r\n')
+}
+
+/** 生成拒绝响应（带状态码与具名原因）。 */
+export function rejectionResponse(status, code, message) {
+  const body = JSON.stringify({ ok: false, code, message })
+  return [
+    `HTTP/1.1 ${status} ${status === 401 ? 'Unauthorized' : status === 400 ? 'Bad Request' : 'Forbidden'}`,
+    'Content-Type: application/json; charset=utf-8',
+    `Content-Length: ${Buffer.byteLength(body)}`,
+    'Connection: close',
+    '', body,
+  ].join('\r\n')
+}
+
+function encodeFrame(opcode, payloadBuffer) {
+  const length = payloadBuffer.length
+  let header = null
+  if (length < 126) {
+    header = Buffer.alloc(2)
+    header[1] = length
+  } else if (length < 65536) {
+    header = Buffer.alloc(4)
+    header[1] = 126
+    header.writeUInt16BE(length, 2)
+  } else {
+    header = Buffer.alloc(10)
+    header[1] = 127
+    header.writeBigUInt64BE(BigInt(length), 2)
+  }
+  header[0] = 0x80 | opcode // FIN + opcode
+  return Buffer.concat([header, payloadBuffer])
+}
+
+export function encodeText(value) {
+  return encodeFrame(OPCODE.text, Buffer.from(String(value), 'utf8'))
+}
+
+export function encodeClose(code = 1000, reason = '') {
+  const reasonBuffer = Buffer.from(String(reason), 'utf8')
+  const payload = Buffer.alloc(2 + reasonBuffer.length)
+  payload.writeUInt16BE(Number(code) || 1000, 0)
+  reasonBuffer.copy(payload, 2)
+  return encodeFrame(OPCODE.close, payload)
+}
+
+export function encodePing() {
+  return encodeFrame(OPCODE.ping, Buffer.alloc(0))
+}
+
+export function encodePong(payload = Buffer.alloc(0)) {
+  return encodeFrame(OPCODE.pong, Buffer.from(payload))
+}
+
+/**
+ * 增量帧解析器。`push(buffer)` 返回本次解析出的完整消息与需要回应的控制帧。
+ * 超过 maxPayload 的帧返回 error 并停止后续解析（由调用方断开连接）。
+ */
+export function createFrameParser({ maxPayload = WS_MAX_PAYLOAD } = {}) {
+  let pending = Buffer.alloc(0)
+  let fragments = []
+  let fragmentOpcode = null
+
+  function takeMessage(opcode, payload) {
+    if (opcode === OPCODE.continuation) {
+      if (fragmentOpcode === null) return { error: 'unexpected-continuation' }
+      fragments.push(payload)
+      return null
+    }
+    fragments = [payload]
+    fragmentOpcode = opcode
+    return null
+  }
+
+  return {
+    push(chunk) {
+      pending = pending.length === 0 ? Buffer.from(chunk) : Buffer.concat([pending, chunk])
+      const messages = []
+      const controls = []
+      const errors = []
+      while (pending.length >= 2) {
+        const first = pending[0]
+        const second = pending[1]
+        const fin = (first & 0x80) !== 0
+        const opcode = first & 0x0f
+        const masked = (second & 0x80) !== 0
+        let length = second & 0x7f
+        let offset = 2
+        if (length === 126) {
+          if (pending.length < offset + 2) break
+          length = pending.readUInt16BE(offset)
+          offset += 2
+        } else if (length === 127) {
+          if (pending.length < offset + 8) break
+          const big = pending.readBigUInt64BE(offset)
+          if (big > BigInt(maxPayload)) { errors.push('payload-too-large'); return { messages, controls, errors } }
+          length = Number(big)
+          offset += 8
+        }
+        if (length > maxPayload) { errors.push('payload-too-large'); return { messages, controls, errors } }
+        if (!masked) { errors.push('client-frame-must-be-masked'); return { messages, controls, errors } }
+        if (pending.length < offset + 4 + length) break
+        const mask = pending.subarray(offset, offset + 4)
+        offset += 4
+        const payload = Buffer.from(pending.subarray(offset, offset + length))
+        for (let index = 0; index < payload.length; index += 1) payload[index] ^= mask[index % 4]
+        pending = pending.subarray(offset + length)
+
+        if (opcode === OPCODE.ping) { controls.push({ type: 'ping', payload }); continue }
+        if (opcode === OPCODE.pong) { controls.push({ type: 'pong', payload }); continue }
+        if (opcode === OPCODE.close) {
+          controls.push({ type: 'close', payload })
+          fragmentOpcode = null
+          fragments = []
+          continue
+        }
+        if (opcode === OPCODE.binary) { controls.push({ type: 'binary-ignored' }); continue }
+
+        const result = takeMessage(opcode, payload)
+        if (result && result.error) { errors.push(result.error); return { messages, controls, errors } }
+        if (fin) {
+          const merged = Buffer.concat(fragments)
+          const frameOpcode = fragmentOpcode
+          fragments = []
+          fragmentOpcode = null
+          if (frameOpcode === OPCODE.text) messages.push(merged.toString('utf8'))
+          else controls.push({ type: 'binary-ignored' })
+        }
+      }
+      return { messages, controls, errors }
+    },
+  }
+}

package/src/dual/documents.ts

@@ -105,3 +105,38 @@ export function renderClosureDocument(plan) {
     '#### 项目资料汇总', '', bullets(closure.artifacts), '',
   ].join('\n')
 }
+
+/** PM 的复核 + 复盘 + 总结（闭环第三步）。 */
+export function renderReviewDocument(review, { feedback = null, handoff = null } = {}) {
+  const checks = review.acceptanceChecks
+  const failed = checks.filter((check) => check.met !== true)
+  const out = [
+    `# 复核与复盘 · ${review.id}`, '',
+    `- 结论：**${review.verdict === 'accepted' ? '通过' : '退回修改'}**`,
+    `- 关联计划：${review.planId}`,
+    `- 关联 PRD：${review.prdId ?? '未关联'}`,
+    `- 反馈 ID：${review.feedbackId}`, '',
+    '## 一、复核：验收逐条核对', '',
+    '| 验收标准 | 结果 | 证据 | 备注 |',
+    '|---|---|---|---|',
+    ...checks.map((check) => `| ${cell(check.criterion)} | ${check.met ? '通过' : '未通过'} | ${cell(check.evidence.join('；') || '—')} | ${cell(check.note || '—')} |`), '',
+    failed.length > 0 ? `**未通过项**：${failed.map((check) => check.criterion).join('；')}` : '**全部验收项通过。**', '',
+  ]
+  if (feedback) {
+    out.push('## 二、执行回执（PJM 自反馈）', '', feedback.summary, '')
+    out.push(`- 步骤：${feedback.metrics.done}/${feedback.metrics.steps}（${feedback.metrics.percent}%）`)
+    out.push(`- 估时/实际：${feedback.metrics.estimatedMinutes} / ${feedback.metrics.actualMinutes} 分钟`)
+    if (feedback.deviations.length) out.push('- 偏差：', bullets(feedback.deviations))
+    if (feedback.openIssues.length) out.push('- 遗留问题：', bullets(feedback.openIssues))
+    out.push('')
+  }
+  if (handoff) {
+    out.push('## 三、交接对照', '', `- 交接包：${handoff.id}（${handoff.status}）`, `- 验收标准数：${handoff.acceptance.length}`, '')
+  }
+  out.push('## 四、复盘', '')
+  out.push('### 保持（做对了什么）', '', bullets(review.retrospective.kept), '')
+  out.push('### 改进（哪里不顺）', '', bullets(review.retrospective.improve), '')
+  out.push('### 经验（下次怎么做）', '', bullets(review.retrospective.lessons), '')
+  out.push('## 五、总结', '', review.summary, '')
+  return out.join('\n').trim() + '\n'
+}