@twinsearth/dsh-master 0.0.0-stage → 3.2.8

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# dsh-Master（房主）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 与瓮城 **dsh-Fang** 并行的主 Agent 插件。  
+> 当前版本：`3.2.8`（审计修复发布线；tag / GitHub Release / NPM public）。
+> 仓库：https://github.com/TwinsEarth/dsh-Master
+
+## 这是什么
+
+dsh-Master 不接管瓮城的「母体 / 原身 / 分身」生命周期；它是一块**并列的主插件**，
+在自己的名字空间里托管 Agent 子插件，并通过 DSH 服务键与瓮城协作：
+
+```text
+DSH Host
+├── 瓮城 bundle (dsh-Fang)                    房主 bundle (dsh-Master)
+│   mirror / essence / derived                core（主 Agent 控制面）
+│   fangForker / fangDecisionCenter  ◄──────  ├── superagent-router   （essence）
+│   fangSessionCatalog                       ├── superagent-worker   （fork）
+│                                            ├── cost-optimizer       （fork）
+│                                            └── dual-manager         （mother/essence）
+└── 协作只走服务键；任一方向失败一律 fail-closed，不本地降级执行
+```
+
+## 子插件
+
+| 子插件 | 行 id | 允许角色 | 路线图 | 已交付 |
+|---|---|---|---|---|
+| SuperAgent Router | `master-superagent-router` | **essence only** | 3.2.1/3.2.3 | Webhook/Ticket/Mandate、渐进信任、本地或母体桥派发、Worker 实时事件、回写 |
+| SuperAgent Worker | `master-superagent-worker` | **fork only** | 3.2.1 | Ticket 上下文、Mandate 守卫 |
+| Worker Agent Loop | `master-superagent-loop` | **fork only** | 3.2.3 | tsc 编译 preset；有 Ticket 自动跑多轮工具循环并流式回传 |
+| 成本优化 HarnessMM | `master-cost-optimizer` | **fork only** | 3.3.0 | observe 层：token 估算、实测记录 |
+| 双主管 PM + PJM | `master-dual-manager` | **mother / essence** | 3.4.0 | PRD/计划/调度/决策中心澄清 |
+
+## 本地开发
+
+```bash
+npm install          # devDeps: typescript + @types/node（仅类型检查/构建用）
+npm test             # node:test 全量（含 worker/*.ts 测试）
+npm run typecheck:worker   # tsc strict 类型检查
+npm run build:worker       # tsc 构建 dist-worker/（DSH 实际加载的 preset）
+node dist-worker/main.js   # CLI（需 DSH_MASTER_TICKET + LLM/流式配置）
+```
+
+仓库运行态零依赖。运行时全部加载**编译后的 JS**：
+
+- 房主 Host/插件：`src/**/*.ts` → `npm run build:host` → `dist-host/`；
+- Worker preset：`worker/**/*.ts` → `npm run build:worker` → `dist-worker/`；
+- 浏览器侧 `client.js` 保持 JS（DSH client module 运行时加载）；
+- 对外类型：`types/superagent.d.ts`；
+- `npm test` 直接由 Node 26 类型擦除执行 TS 源码/测试；production 用 dist JS。
+
+```bash
+npm run typecheck:host && npm run build:host
+npm run typecheck:worker && npm run build:worker
+npm run build   # 两者一起
+dsh plugin add <package>  # 加载 dist-host/dist-worker
+```
+
+## 安装（审核通过后）
+
+```bash
+# 目前请勿安装/发布；审核通过后：
+# dsh plugin add @twinsearth/dsh-master   （发布后）
+# 或以本地 bundle 目录安装
+```
+
+安装后：
+
+- 插件目录多出 **房主（dsh-Master）** + 五个子插件行（Router / Worker / Loop / HarnessMM / PM+PJM）；
+- 侧栏底部出现「◈ 房主」入口，打开只读状态抽屉（角色/子插件矩阵/瓮城协作状态）；
+- 角色边界在代码里强制：Router 只在 essence、Worker/成本只 fork、双主管只 mother/essence；
+- SuperAgent 默认 **observe**，不会自动接单。
+
+## 文档
+
+- [房主 ↔ 瓮城 互联契约](docs/INTEROP.md)
+- [真实 Host 集成 smoke（3.2.7）](docs/SMOKE-3.2.7.md)
+- [v3.2.7 全面审计与实机复盘](docs/REVIEW-v3.2.7.md)
+- [Worker Agent Loop](docs/WORKER-AGENT-LOOP.md)
+- [SuperAgent v3.2.1 设计与契约](docs/SUPERAGENT.md)
+- [架构设计](docs/ARCHITECTURE.md)
+- [路线图（3.2.0–3.4.0）](docs/ROADMAP.md)
+- [安全边界](docs/SECURITY.md)
+- [变更记录](docs/CHANGELOG.md)
+
+## 状态
+
+- 3.2.8 发布线：与瓮城通过 fang-master contract 1.0 互联（local/http/file/legacy 四级保底）；GitHub Release + NPM public。
+- 当前工作树完成新一轮审计修复：工具名/死循环阈值、Router 鉴权与生命周期、真实路由分流、契约幂等与超时、PR 护栏与交付、飞书加密、长 Shell 后台作业、成本实测接线、PJM 派生契约。
+- 验收：`npm run check` / `npm run build` / `npm test` 全绿；真实双 Host/fork 落库、工具写读、SSE、回写、配额与桥清理断言通过。详见复盘文档。
+- 后续修复尚未发布，也未安装到用户主 profile；发布仍需明确指令。

package/client.js

@@ -0,0 +1,263 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+
+/**
+ * Dsh-Master（房主）Web Client：侧栏「房主」入口 + 只读状态抽屉。
+ *
+ * 只做观察面板（3.2.0 架构骨架）：展示角色、三个子插件的激活状态、与瓮城的
+ * 服务协作状态。数据来自 core 的只读路由 `/dsh-master/api/status`。
+ * 不写任何业务状态，不接管宿主根节点。
+ */
+window.__ModuleLoader__.load({
+  id: '@twinsearth/dsh-master',
+  factory(require) {
+    const React = require('react')
+    const h = React.createElement
+
+    const S = {
+      panel: {
+        position: 'fixed', top: 0, right: 0, bottom: 0, width: 'min(380px, 92vw)',
+        zIndex: 2147482800, background: '#fff', borderLeft: '1px solid rgba(16,17,20,.12)',
+        boxShadow: '-16px 0 40px rgba(16,17,20,.16)', display: 'flex', flexDirection: 'column',
+        fontFamily: '-apple-system,BlinkMacSystemFont,"Segoe UI","Microsoft YaHei",sans-serif',
+        fontSize: 13, color: '#1D1D1F',
+      },
+      head: { display: 'flex', alignItems: 'center', gap: 8, padding: '14px 16px', borderBottom: '1px solid rgba(16,17,20,.08)' },
+      title: { fontSize: 14, fontWeight: 700 },
+      sub: { fontSize: 11.5, color: '#86868B' },
+      close: { marginLeft: 'auto', width: 28, height: 28, borderRadius: 8, border: '1px solid rgba(16,17,20,.12)', background: '#fff', color: '#5F6368', cursor: 'pointer' },
+      body: { flex: 1, overflowY: 'auto', padding: '12px 14px 18px', display: 'flex', flexDirection: 'column', gap: 10 },
+      card: { border: '1px solid rgba(16,17,20,.1)', borderRadius: 12, padding: '10px 11px', background: '#FAFAFC', display: 'flex', flexDirection: 'column', gap: 4 },
+      row: { display: 'flex', alignItems: 'center', gap: 6, flexWrap: 'wrap' },
+      name: { fontSize: 13, fontWeight: 600 },
+      tag: { display: 'inline-flex', alignItems: 'center', height: 18, padding: '0 6px', borderRadius: 6, fontSize: 10.5, fontWeight: 700, background: '#F2F2F5', color: '#5F6368' },
+      desc: { fontSize: 12, color: '#5F6368' },
+      ok: { color: '#17803D', fontWeight: 600 },
+      off: { color: '#B45309', fontWeight: 600 },
+      error: { fontSize: 12, color: '#C8102E' },
+      fab: {
+        display: 'inline-flex', alignItems: 'center', gap: 6, height: 28, padding: '0 9px',
+        borderRadius: 8, border: '1px solid rgba(16,17,20,.12)', background: '#fff', color: '#1D1D1F',
+        cursor: 'pointer', fontSize: 12.5, fontWeight: 600, fontFamily: 'inherit',
+      },
+      banner: { position: 'fixed', top: 0, right: 0, bottom: 0, left: 0, zIndex: 2147482799, background: 'rgba(18,19,22,.18)' },
+    }
+
+    const tag = (text, color) => h('span', { style: { ...S.tag, ...(color ? { color, background: 'rgba(16,17,20,.05)' } : {}) } }, text)
+
+    function SubpluginCard({ item }) {
+      const color = item.active ? S.ok : S.off
+      return h('div', { style: S.card },
+        h('div', { style: S.row },
+          h('span', { style: S.name }, item.name),
+          tag(item.nameEn),
+          tag('roadmap ' + item.roadmap),
+          h('span', { style: { marginLeft: 'auto', fontSize: 11.5, ...color } }, item.active ? '已激活' : '未激活')),
+        h('div', { style: S.desc }, item.description),
+        h('div', { style: S.desc },
+          '允许角色：' + (item.allowedRoles || []).join(' / '),
+          item.blockedReason ? ' · ' + item.blockedReason : ''),
+        item.capabilities && item.capabilities.length > 0
+          ? h('div', { style: S.desc }, '能力：' + item.capabilities.join(' · '))
+          : null,
+      )
+    }
+
+    function FangCard({ cooperation }) {
+      if (!cooperation) return null
+      const entries = Object.entries(cooperation.services || {})
+      return h('div', { style: S.card },
+        h('div', { style: S.row },
+          h('span', { style: S.name }, '与瓮城协作'),
+          tag(cooperation.contract || 'dsh-fang'),
+          h('span', { style: { marginLeft: 'auto', fontSize: 11.5, ...(cooperation.available ? S.ok : S.off) } },
+            cooperation.available ? '在线' : '未发现')),
+        entries.length === 0
+          ? h('div', { style: S.desc }, '未发现瓮城服务；房主子插件会 fail-closed。')
+          : entries.map(([alias, info]) => h('div', { key: alias, style: S.desc },
+              alias + ' → ' + info.service + ' ' + (info.available ? '✓' : '×'))),
+      )
+    }
+
+    /** v3.2.7：实时事件流（SSE）+ token 轮换；只读，不写宿主状态。 */
+    function LiveFeed() {
+      const [events, setEvents] = React.useState([])
+      const [routerStatus, setRouterStatus] = React.useState(null)
+      const [error, setError] = React.useState('')
+      React.useEffect(() => {
+        let alive = true
+        let source = null
+        let rotateTimer = null
+        let currentToken = ''
+        const append = (event) => {
+          setEvents((prev) => prev.concat([event]).slice(-20))
+        }
+        /**
+         * v3.2.7：上游可能把多个 delta 合并成一批（fork 启动期阻塞会把 SSE 报文在
+         * socket 里积压后一次排空）。直接 append 会让卡片"跳变"一次；
+         * 这里把 stream 增量排进节拍队列，按 ~70ms 逐个上屏，保证视觉上逐字流动。
+         */
+        const deltaQueue = []
+        let pacing = null
+        const paceStreamDeltas = () => {
+          if (pacing || deltaQueue.length === 0) return
+          pacing = setTimeout(() => {
+            pacing = null
+            const next = deltaQueue.shift()
+            if (next) append(next)
+            paceStreamDeltas()
+          }, 70)
+        }
+        const appendPaced = (event) => {
+          const isStreamDelta = event && event.type === 'stream' && event.payload && event.payload.content
+          if (!isStreamDelta) { append(event); return }
+          deltaQueue.push(event)
+          if (deltaQueue.length > 40) deltaQueue.splice(0, deltaQueue.length - 40)
+          paceStreamDeltas()
+        }
+        // 供 ssr/jsdom 测试断言使用（不影响正常渲染）
+        if (typeof window !== 'undefined') window.__fangLiveFeedQueue = deltaQueue
+        const loadStatus = async () => {
+          try {
+            const response = await fetch('/dsh-master/api/superagent/status', { headers: { accept: 'application/json' } })
+            const body = await response.json().catch(() => null)
+            if (alive && body) setRouterStatus(body)
+          } catch { /* 状态可选 */ }
+        }
+        const connect = async (oldToken = currentToken) => {
+          try {
+            const response = await fetch('/dsh-master/api/superagent/stream-token', {
+              method: 'POST',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify(oldToken ? { token: oldToken } : {}),
+            })
+            const body = await response.json().catch(() => null)
+            if (!alive) return
+            if (!response.ok || !body?.token) { setError(`实时流 token 获取失败（HTTP ${response.status}）`); return }
+            source?.close()
+            currentToken = String(body.token)
+            source = new EventSource(`/dsh-master/api/superagent/stream?token=${encodeURIComponent(body.token)}`)
+            source.addEventListener('worker-event', (event) => {
+              try { appendPaced(JSON.parse(event.data)) } catch { /* ignore */ }
+            })
+            source.onerror = () => { if (alive) setError('实时流连接中断（将自动重连）') }
+            setError('')
+          } catch (err) {
+            if (alive) setError('实时流连接失败：' + String(err && err.message ? err.message : err))
+          }
+        }
+        void connect()
+        const statusTimer = setInterval(loadStatus, 5000)
+        loadStatus()
+        rotateTimer = setInterval(() => { void connect(currentToken) }, 4 * 60 * 1000)
+        return () => {
+          alive = false
+          clearInterval(statusTimer)
+          clearInterval(rotateTimer)
+          try { source?.close() } catch { /* ignore */ }
+          if (pacing) { clearTimeout(pacing); pacing = null }
+          deltaQueue.length = 0
+          currentToken = ''
+          if (typeof window !== 'undefined' && window.__fangLiveFeedQueue === deltaQueue) delete window.__fangLiveFeedQueue
+        }
+      }, [])
+      const quota = routerStatus && routerStatus.quota
+      // v3.2.7：真实流式文本（provider 的 token delta 经 SSE 到达），只保留尾部。
+      const streamedText = events
+        .filter((event) => event && event.type === 'stream' && event.payload && event.payload.content)
+        .map((event) => String(event.payload.content))
+        .join('')
+        .slice(-400)
+      const lastToolEvent = events
+        .filter((event) => event && event.type === 'stream' && event.payload && event.payload.toolName)
+        .slice(-1)[0]
+      const toolFinished = lastToolEvent && events.some((event) => event && event.type === 'done'
+        && String(event.ticketId ?? '') === String(lastToolEvent.ticketId ?? '')
+        && Number(event.at ?? 0) >= Number(lastToolEvent.at ?? 0))
+      const streamedTool = toolFinished ? '' : (lastToolEvent ? String(lastToolEvent.payload.toolName) : '')
+      return h('div', { style: S.card },
+        h('div', { style: S.row },
+          h('span', { style: S.name }, '实时事件流'),
+          tag(routerStatus ? `SSE ${routerStatus.streaming?.clients ?? 0}` : 'SSE'),
+          routerStatus && routerStatus.streaming?.hostAdapter ? tag('宿主 adapter') : null,
+          quota ? tag(`并发 ${quota.active ?? 0}/${quota.maxConcurrent ?? '?'}`) : null,
+          h('span', { style: { marginLeft: 'auto', fontSize: 11, ...(error ? S.error : S.desc) } }, error || 'live')),
+        streamedText
+          ? h('div', { style: { ...S.desc, whiteSpace: 'pre-wrap', maxHeight: 120, overflow: 'auto', fontFamily: 'monospace' } }, streamedText)
+          : null,
+        streamedTool ? h('div', { style: S.desc }, `工具中：${streamedTool}`) : null,
+        events.length === 0
+          ? h('div', { style: S.desc }, '暂无 Worker 事件；派发 Worker 后会实时出现。')
+          : events.slice(-8).reverse().map((event, index) => h('div', { key: index, style: S.desc },
+              `${String(event.type ?? 'event')} · ${String(event.ticketId ?? '')} · ${event.step?.type ?? event.payload?.phase ?? ''}`)),
+        h('div', { style: S.desc }, 'SSE token 每 4 分钟轮换；token 审计见状态接口。'),
+      )
+    }
+
+    function MasterPanel({ onClose }) {
+      const [status, setStatus] = React.useState(null)
+      const [error, setError] = React.useState('')
+
+      React.useEffect(() => {
+        let alive = true
+        const load = async () => {
+          try {
+            const response = await fetch('/dsh-master/api/status', { headers: { accept: 'application/json' } })
+            const body = await response.json().catch(() => null)
+            if (!alive) return
+            if (!response.ok || !body) setError(`状态读取失败（HTTP ${response.status}）`)
+            else { setStatus(body); setError('') }
+          } catch (err) {
+            if (alive) setError('状态读取失败：' + String(err && err.message ? err.message : err))
+          }
+        }
+        void load()
+        const timer = setInterval(load, 5000)
+        return () => { alive = false; clearInterval(timer) }
+      }, [])
+
+      const items = status && Array.isArray(status.subplugins) ? status.subplugins : []
+      return h('div', null,
+        h('div', { style: S.fab, role: 'presentation' }),
+        h('aside', { style: S.panel, 'aria-label': '房主状态' },
+          h('div', { style: S.head },
+            h('span', { style: S.title }, '房主 · dsh-Master'),
+            h('span', { style: S.sub }, status ? `${status.version} · ${status.role}` : '读取中'),
+            h('button', { type: 'button', style: S.close, title: '关闭', onClick: onClose }, '×')),
+          h('div', { style: S.body },
+            error ? h('div', { style: S.error }, error) : null,
+            status ? h('div', { style: S.card },
+              h('div', { style: S.row }, h('span', { style: S.name }, '主 Agent 控制面'), tag('与瓮城并行')),
+              h('div', { style: S.desc }, '角色：' + status.role + ' · 版本：' + status.version),
+              h('div', { style: S.desc }, '运行：' + Math.max(1, Math.round((status.uptimeMs || 0) / 60000)) + ' 分钟'),
+            ) : null,
+            ...items.map((item) => h(SubpluginCard, { key: item.id, item })),
+            h(FangCard, { cooperation: status && status.cooperation }),
+            h(LiveFeed),
+            h('div', { style: S.desc }, '3.2.7：真实流式（SSE）+ token 轮换/审计 + Worker 并发配额 + 宿主 adapter；未发布。'),
+          )),
+      )
+    }
+
+    /** sidebar.footer.action 槽：一个「房主」按钮，点击打开状态抽屉。 */
+    function MasterSeat() {
+      const [open, setOpen] = React.useState(false)
+      return h('div', null,
+        h('button', { type: 'button', style: S.fab, title: '房主 · 主 Agent 控制面', onClick: () => setOpen(true) }, '◈ 房主'),
+        open ? h(MasterPanel, { onClose: () => setOpen(false) }) : null,
+      )
+    }
+
+    return {
+      inject: ['slots'],
+      apply(ctx) {
+        ctx.slots.inject('sidebar.footer.action', () => ctx.slots.register({
+          name: 'sidebar.footer.action',
+          id: 'dsh-master-home',
+          order: 79,
+          label: '房主',
+        }, MasterSeat))
+      },
+    }
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,71 @@
+# Dsh-Master（房主）bundle
+#
+# 与瓮城 dsh-Fang 并行：本 bundle 只插入房主自己的行，不覆盖 fang 的任何行。
+# v3.2.3：Worker Agent Loop 编译产物（dist-worker）作为独立 preset 行接入；
+# Router 增加母体派发桥、Worker 实时事件与结果回写。
+# 角色边界在插件代码里强制（见 src/kernel.mjs ROLE_MATRIX 与 docs/SECURITY.md）。
+- insert:
+    - id: master-core
+      name: '@twinsearth/dsh-master'
+      config:
+        enabled: true
+        bridgeToken: ''
+        bridgeTokenRotateMs: 1800000
+        bridgeTokenGraceMs: 300000
+        tokenAuditLimit: 500
+        dispatch:
+          homeDir: ''
+          cliPath: ''
+          profile: ''
+    - id: master-superagent-router
+      name: '@twinsearth/dsh-master/superagent-router'
+      config:
+        enabled: true
+        trustMode: observe
+        allowedActors: []
+        requireMention: true
+        allowedSources: [github, feishu]
+        repoAllowlist: []
+        streamTokenTtlMs: 21600000
+        uiTokenTtlMs: 600000
+        streamTokenRequired: true
+        workerQuota:
+          enabled: true
+          maxConcurrent: 2
+          maxPerSource: 0
+        dispatch:
+          homeDir: ''
+          cliPath: ''
+          profile: ''
+          motherUrl: ''
+          motherToken: ''
+          motherAuthToken: ''
+          contract: true
+          contractFileDir: ''
+        writeback:
+          url: ''
+          token: ''
+          githubToken: ''
+          feishuWebhookUrl: ''
+          feishuSignSecret: ''
+    - id: master-superagent-worker
+      name: '@twinsearth/dsh-master/superagent-worker'
+      config:
+        enabled: true
+    - id: master-superagent-loop
+      name: '@twinsearth/dsh-master/superagent-loop'
+      config:
+        enabled: true
+        autorun: true
+        model: ''
+        workspace: ''
+    - id: master-cost-optimizer
+      name: '@twinsearth/dsh-master/cost-optimizer'
+      config:
+        enabled: true
+        mode: observe
+        targetSavingsRatio: 0.8
+    - id: master-dual-manager
+      name: '@twinsearth/dsh-master/dual-manager'
+      config:
+        enabled: true

package/dist-host/contract/client.js

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang/dsh-Master contributors — see LICENSE.
+import { DEFAULT_TRANSPORT_ORDER, METHODS } from './constants.js';
+import { createFileTransport, createHttpTransport, createLegacyTransport, createLocalTransport, createTransportRouter, } from './transports.js';
+/**
+ * 客户端门面：一次配置，按 local → http → file → legacy 自动降级。
+ *
+ * @param {{
+ *  ctx?: object,
+ *  config?: {httpBaseUrl?:string, httpToken?:string, fileDir?:string, order?:string[], timeoutMs?:number},
+ *  fetchImpl?: typeof fetch,
+ *  logger?: object,
+ *  instanceId?: string,
+ * }} options
+ */
+export function createContractClient(options = {}) {
+    const { ctx = null, config = {}, fetchImpl = fetch, logger = null, instanceId = 'contract-client' } = options;
+    const transports = [];
+    if (ctx)
+        transports.push(createLocalTransport({ ctx }));
+    if (config.httpBaseUrl)
+        transports.push(createHttpTransport({
+            baseUrl: config.httpBaseUrl,
+            token: config.httpToken,
+            headers: config.httpHeaders,
+            fetchImpl,
+            timeoutMs: config.timeoutMs,
+            pathPrefix: config.pathPrefix,
+        }));
+    if (config.fileDir)
+        transports.push(createFileTransport({
+            dir: config.fileDir,
+            pollMs: config.filePollMs,
+            timeoutMs: config.fileTimeoutMs,
+        }));
+    if (ctx)
+        transports.push(createLegacyTransport({ ctx }));
+    const order = Array.isArray(config.order) && config.order.length > 0 ? config.order : DEFAULT_TRANSPORT_ORDER;
+    const router = createTransportRouter({
+        transports,
+        order,
+        localHello: null,
+        logger,
+    });
+    let lastHello = null;
+    let helloPromise = null;
+    const client = {
+        instanceId,
+        transports: () => router.transports(),
+        describe: () => ({
+            instanceId,
+            routes: router.describe(),
+            hello: lastHello,
+        }),
+        attempts: () => router.attempts(),
+        async hello(force = false) {
+            if (!force && lastHello)
+                return lastHello;
+            if (!force && helloPromise)
+                return helloPromise;
+            helloPromise = (async () => {
+                const result = await router.hello();
+                lastHello = result;
+                return result;
+            })().finally(() => { helloPromise = null; });
+            return helloPromise;
+        },
+        async invoke(method, params, invokeOptions = {}) {
+            const result = await router.invoke(method, params, { timeoutMs: config.timeoutMs, ...invokeOptions });
+            return result;
+        },
+        async health() { return await client.invoke(METHODS.HEALTH, null); },
+        async spawnFork(params, invokeOptions = {}) { return await client.invoke(METHODS.FORK_SPAWN, params, invokeOptions); },
+        async stopFork(params, invokeOptions = {}) { return await client.invoke(METHODS.FORK_STOP, params, invokeOptions); },
+        async listForks(params = {}, invokeOptions = {}) { return await client.invoke(METHODS.FORK_LIST, params, invokeOptions); },
+        async createDecision(params, invokeOptions = {}) { return await client.invoke(METHODS.DECISION_CREATE, params, invokeOptions); },
+        async resolveDecision(params, invokeOptions = {}) { return await client.invoke(METHODS.DECISION_RESOLVE, params, invokeOptions); },
+        async listSessions(params = {}, invokeOptions = {}) { return await client.invoke(METHODS.SESSION_LIST, params, invokeOptions); },
+        async orchestratorStatus(params = {}, invokeOptions = {}) { return await client.invoke(METHODS.ORCHESTRATOR_STATUS, params, invokeOptions); },
+    };
+    return client;
+}

package/dist-host/contract/constants.js

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang/dsh-Master contributors — see LICENSE.
+/**
+ * 契约常量与兼容规则（contract SDK 1.x）。
+ *
+ * 稳定承诺：
+ *   * MAJOR 相同的版本保证“旧字段可读、旧方法可调、未知字段忽略”；
+ *   * 新增能力只通过 METHODS/CAPABILITIES 扩展，不改变既有方法语义；
+ *   * 删除/改义必须升 MAJOR，并保留至少一个 MINOR 周期的双写（method@1 与 method@2）。
+ */
+export const CONTRACT_PACKAGE = '@twinsearth/dsh-fang-contract';
+export const CONTRACT_VERSION = '1.0.0';
+export const PROTOCOL = 'fang-master';
+export const PROTOCOL_VERSION = 1;
+export const MIN_COMPATIBLE_MAJOR = 1;
+/** 稳定方法名（新方法只能追加）。 */
+export const METHODS = Object.freeze({
+    HELLO: 'contract.hello',
+    HEALTH: 'contract.health',
+    FORK_SPAWN: 'fang.fork.spawn',
+    FORK_STOP: 'fang.fork.stop',
+    FORK_LIST: 'fang.fork.list',
+    DECISION_CREATE: 'fang.decision.create',
+    DECISION_RESOLVE: 'fang.decision.resolve',
+    SESSION_LIST: 'fang.session.list',
+    ORCHESTRATOR_STATUS: 'fang.orchestrator.status',
+});
+/** 方法 → 契约版本（用于协商后的方法裁剪）。 */
+export const METHOD_VERSION = Object.freeze({
+    [METHODS.HELLO]: '1.0',
+    [METHODS.HEALTH]: '1.0',
+    [METHODS.FORK_SPAWN]: '1.0',
+    [METHODS.FORK_STOP]: '1.0',
+    [METHODS.FORK_LIST]: '1.0',
+    [METHODS.DECISION_CREATE]: '1.0',
+    [METHODS.DECISION_RESOLVE]: '1.0',
+    [METHODS.SESSION_LIST]: '1.0',
+    [METHODS.ORCHESTRATOR_STATUS]: '1.0',
+});
+export const CAPABILITIES = Object.freeze([
+    'sync', 'async', 'idempotent', 'stream-events', 'file-outbox',
+]);
+export const ROLES = Object.freeze(['mother', 'essence', 'fork']);
+export const ERROR_CODES = Object.freeze({
+    INVALID_ENVELOPE: 'invalid-envelope',
+    UNSUPPORTED_METHOD: 'unsupported-method',
+    UNSUPPORTED_VERSION: 'unsupported-version',
+    INCOMPATIBLE: 'contract-incompatible',
+    TRANSPORT_UNAVAILABLE: 'transport-unavailable',
+    TRANSPORT_TIMEOUT: 'transport-timeout',
+    TRANSPORT_HTTP_ERROR: 'transport-http-error',
+    REMOTE_ERROR: 'remote-error',
+    ALL_TRANSPORTS_FAILED: 'all-transports-failed',
+    HANDLER_THREW: 'handler-threw',
+});
+/**
+ * 兜底顺序（从快到慢）：
+ *   local  —— 同一 Host 的 DSH 服务（零网络、首选）
+ *   http   —— 母体/原身 HTTP 契约端点
+ *   file   —— 同一文件系统的 outbox/inbox（HTTP 不可用/被防火墙拦）
+ *   legacy —— 直接调用 3.1.x 的旧 DSH 服务键（接口包被替换/新端点不存在时）
+ */
+export const DEFAULT_TRANSPORT_ORDER = Object.freeze(['local', 'http', 'file', 'legacy']);
+/** 3.1.x 及更早的旧服务键（只读兼容；不新增语义）。 */
+export const LEGACY_SERVICE_KEYS = Object.freeze({
+    forker: 'fangForker',
+    decisionCenter: 'fangDecisionCenter',
+    sessionCatalog: 'fangSessionCatalog',
+    orchestrator: 'fang',
+});

package/dist-host/contract/envelope.js

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang/dsh-Master contributors — see LICENSE.
+import crypto from 'node:crypto';
+import { ERROR_CODES, PROTOCOL, PROTOCOL_VERSION } from './constants.js';
+export function newId(prefix = 'msg') {
+    return `${prefix}_${crypto.randomUUID()}`;
+}
+/** 创建请求信封；未知字段由接收方忽略（兼容规则）。 */
+export function createEnvelope({ method, params = null, id, source = '', instanceId = '', timeoutMs = 30_000, meta = {} } = {}) {
+    if (!method || typeof method !== 'string')
+        throw new Error('method is required');
+    return {
+        protocol: PROTOCOL,
+        protocolVersion: PROTOCOL_VERSION,
+        id: String(id ?? newId('req')),
+        method: String(method),
+        params: params ?? null,
+        meta: {
+            at: Date.now(),
+            deadline: Date.now() + Math.max(1, Number(timeoutMs) || 30_000),
+            source: String(source ?? ''),
+            instanceId: String(instanceId ?? ''),
+            ...(meta && typeof meta === 'object' ? meta : {}),
+        },
+    };
+}
+/** 校验请求/响应信封；返回 {ok, errors, envelope}。 */
+export function validateEnvelope(value, { response = false } = {}) {
+    const errors = [];
+    const raw = value && typeof value === 'object' ? value : {};
+    if (raw.protocol !== PROTOCOL)
+        errors.push(`protocol-invalid:${String(raw.protocol)}`);
+    if (raw.protocolVersion !== PROTOCOL_VERSION)
+        errors.push(`protocol-version-invalid:${String(raw.protocolVersion)}`);
+    if (!raw.id)
+        errors.push('id-required');
+    if (response) {
+        if (typeof raw.ok !== 'boolean')
+            errors.push('ok-required');
+        if (raw.ok === false && !raw.error?.code)
+            errors.push('error-code-required');
+    }
+    else if (!raw.method) {
+        errors.push('method-required');
+    }
+    return { ok: errors.length === 0, errors, envelope: raw };
+}
+export function createResponse({ id, result, error, meta = {} } = {}) {
+    const base = {
+        protocol: PROTOCOL,
+        protocolVersion: PROTOCOL_VERSION,
+        id: String(id ?? newId('res')),
+        ok: !error,
+        meta: { at: Date.now(), ...(meta && typeof meta === 'object' ? meta : {}) },
+    };
+    if (error)
+        return { ...base, error: normalizeError(error) };
+    return { ...base, result: result ?? null };
+}
+export function normalizeError(error, fallbackCode = ERROR_CODES.REMOTE_ERROR) {
+    if (!error)
+        return { code: fallbackCode, message: String(fallbackCode), retryable: false };
+    if (typeof error === 'string')
+        return { code: fallbackCode, message: error, retryable: false };
+    return {
+        code: String(error.code ?? fallbackCode),
+        message: String(error.message ?? error.error ?? fallbackCode),
+        retryable: error.retryable === true,
+        ...(error.detail === undefined ? {} : { detail: error.detail }),
+    };
+}
+export class ContractTransportError extends Error {
+    constructor(code, message, { transport = '', detail = null, retryable = false } = {}) {
+        super(String(message ?? code));
+        this.name = 'ContractTransportError';
+        this.code = String(code);
+        this.transport = String(transport);
+        this.detail = detail;
+        this.retryable = retryable === true;
+    }
+}
+export function isCompatibleResponse(value) {
+    return validateEnvelope(value, { response: true }).ok;
+}