@twinsearth/dsh-master 0.0.0-stage → 3.2.9

package/README.md

@@ -1,3 +1,94 @@
-# 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.9`（面板交互修复线；tag / GitHub Release / NPM public）。
+> 仓库：https://github.com/TwinsEarth/dsh-Master
+
+[![DSH 0.2.2-rc.1](https://img.shields.io/badge/DSH-0.2.2--rc.1-4D6BFE?style=flat)](https://github.com/deepseek-ai/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
+
+## 这是什么
+
+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.9 发布线：房主面板改注册到 `shell.overlay` 常驻浮层——点击面板之外不收起、侧栏「房主」按钮二次点击收起、正文独立滚动；新增无浏览器 hook 运行时行为测试（开关、无 outside-click 监听、滚动容器、SSE 失败不卸载面板）。
+- 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` 全绿（188/188）；真实双 Host/fork 落库、工具写读、SSE、回写、配额与桥清理断言通过。详见复盘文档。
+- 发布不等于安装：本流程不修改任何用户 profile（当前 desktop profile 仍为 3.2.8，升级需另行授权）。

package/client.js

@@ -0,0 +1,334 @@
+// 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`。
+ * 不写任何业务状态，不接管宿主根节点。
+ *
+ * 面板与按钮分离（3.2.9）：按钮注册在 `sidebar.footer.action`，面板注册在
+ * `shell.overlay`（DSH 的整框浮层，位于所有列与滚动容器之外，且本身
+ * click-through）。两者通过模块级 store 共享「是否展开」：
+ * - 点击页面其他位置不会关闭面板（浮层没有 outside-click 收回逻辑）；
+ * - 再次点击「房主」按钮由 `togglePanel()` 收起；
+ * - 面板固定 viewport 高度，正文 `overflow-y: auto`，长内容可滚动查看。
+ */
+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',
+        // shell.overlay 整层是 click-through：面板自己opt-in接收指针事件，
+        // 面板之外的点击穿透到下面的应用，不会触发任何收回。
+        pointerEvents: 'auto',
+      },
+      head: {
+        flex: '0 0 auto', 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 1 auto', minHeight: 0, overflowY: 'auto', overscrollBehavior: 'contain',
+        scrollbarGutter: 'stable', scrollbarWidth: 'thin',
+        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',
+      },
+      fabOpen: {
+        display: 'inline-flex', alignItems: 'center', gap: 6, height: 28, padding: '0 9px',
+        borderRadius: 8, border: '1px solid rgba(16,17,20,.24)', background: '#F2F2F5', color: '#1D1D1F',
+        cursor: 'pointer', fontSize: 12.5, fontWeight: 600, fontFamily: 'inherit',
+      },
+    }
+
+    /**
+     * 面板展开状态：按钮（sidebar.footer.action）与面板（shell.overlay）是两个
+     * 独立注册的组件，状态必须放在模块级 store 里，不能放在任一组件内部。
+     */
+    const panelState = { open: false }
+    const panelListeners = new Set()
+    const getPanelOpen = () => panelState.open
+    const setPanelOpen = (next) => {
+      const value = Boolean(next)
+      if (panelState.open === value) return
+      panelState.open = value
+      for (const listener of panelListeners) {
+        try { listener() } catch { /* 订阅者异常不影响其他订阅者 */ }
+      }
+    }
+    const togglePanel = () => setPanelOpen(!panelState.open)
+    const subscribePanel = (listener) => {
+      panelListeners.add(listener)
+      return () => { panelListeners.delete(listener) }
+    }
+    function usePanelOpen() {
+      const [open, setOpen] = React.useState(getPanelOpen)
+      React.useEffect(() => subscribePanel(() => setOpen(getPanelOpen())), [])
+      return open
+    }
+
+    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() {
+      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('aside', { style: S.panel, id: 'dsh-master-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: '收起面板',
+            'aria-label': '收起房主面板',
+            onClick: () => setPanelOpen(false),
+          }, '×')),
+        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.9：面板常驻（点面板外不收起、按钮二次点击收起、长内容可滚动）；实时流（SSE）+ token 轮换/审计 + Worker 并发配额。'),
+        ))
+    }
+
+    /** shell.overlay：整框浮层里的面板本体；关闭时不渲染任何节点。 */
+    function MasterOverlay() {
+      const open = usePanelOpen()
+      return open ? h(MasterPanel) : null
+    }
+
+    /**
+     * sidebar.footer.action 槽：一个「房主」按钮。
+     * 再点一次收起面板（之前只 setOpen(true)，面板打开后按钮无法关闭）。
+     */
+    function MasterSeat() {
+      const open = usePanelOpen()
+      return h('button', {
+        type: 'button',
+        style: open ? S.fabOpen : S.fab,
+        title: open ? '房主 · 点击收起控制面' : '房主 · 主 Agent 控制面',
+        'aria-expanded': open ? 'true' : 'false',
+        'aria-controls': 'dsh-master-panel',
+        onClick: () => togglePanel(),
+      }, '◈ 房主')
+    }
+
+    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))
+        // 面板放在 shell.overlay：位于所有列与滚动容器之外，且整层 click-through，
+        // 因此不会随侧栏（或宿主弹层）卸载，点击面板外也不会收回。
+        ctx.slots.inject('shell.overlay', () => ctx.slots.register({
+          name: 'shell.overlay',
+          id: 'dsh-master-panel',
+          order: 78,
+          label: '房主面板',
+        }, MasterOverlay))
+      },
+    }
+  },
+})

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',
+});