@twinsearth/dsh-master 0.0.0-stage → 3.2.9

package/docs/WORKER-AGENT-LOOP.md

@@ -0,0 +1,139 @@
+# Worker Agent Loop（v3.2.3）
+
+> 运行位置：**分身 VM 内**的 `dsh-superagent-worker` preset。  
+> 输入：Router 通过 `DSH_MASTER_TICKET` 注入的 Ticket；输出：结构化 WorkerResult（成功报告/失败报告）。
+
+## 1. 为什么是 while(true)
+
+模型每一轮只回答一件事：**继续调用工具，还是给出最终结论**。Agent Loop 本身不猜业务，
+循环条件不写“任务是否完成”，因为那要由模型判断。`while (true)` 的所有出口都是硬约束：
+
+| 出口 | 条件 | 结果 |
+|---|---|---|
+| 正常完成 | 模型返回 `tool_calls` 为空 | `phase=done`，finalAnswer = 最后一条 assistant content |
+| 步数熔断 | `stepIndex >= maxSteps`（默认 15） | `error.code=max-steps`，phase=failed |
+| Token 熔断 | 累计 usage.totalTokens > maxTokens（默认 50k） | `error.code=token-budget-exceeded` |
+| 墙钟熔断 | elapsed > maxWallClockMs（默认 15min） | `error.code=wall-clock-exceeded` |
+| 死循环 | 连续相同工具调用 > maxIdenticalToolRepeats（默认 3） | `error.code=dead-loop-detected` |
+| 上下文超长 | messages 序列化 > maxContextChars（默认 400k 字符） | `error.code=context-limit-exceeded`（防 OOM/超长请求） |
+| LLM 失败/超时 | 请求异常或超过 llmTimeoutMs（默认 120s） | `error.code=llm-call-failed / llm-timeout` |
+
+## 2. 状态机
+
+```text
+initializing → thinking ──(tool_calls)──→ executing_tool → thinking → … → reporting → done
+      │                                                     │
+      └─────────────────(no tool_calls)─────────────────────┘
+任意异常/预算耗尽 ───────────────────────────────────────────→ failed
+```
+
+每一步写入 `WorkerStep[]`（`thought/tool_call/tool_result/final_answer/error/phase`），
+并通过 `WorkerSink` 实时推送给宿主/日志；`snapshot()` 可在崩溃后由 Router 读取现场。
+
+## 3. 工具与安全边界
+
+| 工具 | 限制 |
+|---|---|
+| `fs_read_file` | workspace jail；≤256KB |
+| `fs_list_dir` | workspace jail；≤200 项 |
+| `fs_write_file` | workspace jail + **Mandate.scope** 内；≤1MB；realpath 防符号链接逃逸 |
+| `exec_shell_in_vm` | 必须 `mandate.allowShell`；命令黑名单（sudo/curl/wget/ssh/scp/git push/编码执行等）；cwd=workspace；超时/输出上限；失败文本回灌 |
+| `create_pr` | 只暴露接口；真实 PR 客户端由宿主注入，默认拒绝（不假装成功） |
+
+- 工具错误**不抛穿循环**：返回 `执行报错: …` 给模型自行纠错；只有预算/循环/墙钟终止 Worker；
+- 路径按 workspace 解析并二次校验 Mandate.scope，模型无法用 `../`、绝对路径或 symlink 越狱；
+- 工具执行统一走 `createToolRegistry.execute`，带 AbortSignal + 超时 + 异常隔离。
+
+## 4. 流式与可观测
+
+`WorkerSink` 提供四类事件：
+
+- `phase(phase)`：状态机迁移；
+- `step(step)`：结构化审计记录（可落盘到会话仓，崩溃后恢复）；
+- `stream(delta)`：模型文本块/工具名（无真 streaming 时按 240 字符分块模拟，可替换为真 delta）；
+- `log(message)`：人类可读日志。
+
+Cordis 入口（`worker/index.ts`）把这些事件转发为 `superagent:phase/step/stream/log`，
+完成/失败分别 emit `superagent:worker:done` / `superagent:worker:error`。
+宿主可每 2s 轮询 `getLatestStep()` 推送前端。
+
+## 5. 文件结构
+
+```text
+worker/
+├── types.ts        # Ticket/Step/Phase/Limits/LLM/Tool 类型（含默认限制）
+├── errors.ts       # 可分类错误 → Router 决定重试/报警
+├── prompt.ts       # System/User prompt（含注入防护）
+├── tools.ts        # 沙箱工具 + 路径 jail + Shell 黑名单 + 环境脱敏 + 进程树 kill
+├── agent-loop.ts   # SuperAgentWorker：状态机/熔断/死循环/审计/脱敏
+├── llm-http.ts     # OpenAI 兼容 HTTP LLM 适配器（key 不落日志）
+├── sink-http.ts    # Worker → Router 实时事件通道（per-ticket token）
+├── index.ts        # Cordis preset 入口（自动跑 + runWorker）
+├── main.ts         # CLI：node dist-worker/main.js
+└── tsconfig.worker.build.json → dist-worker/
+```
+
+## 6. 运行方式
+
+### 本地直接跑（Node 22.6+ 类型擦除，无需构建）
+
+```bash
+npm run build:worker   # tsc 编译到 dist-worker/
+node dist-worker/main.js
+```
+
+环境变量：
+
+```text
+DSH_MASTER_TICKET        Router 注入的 Ticket JSON（必填）
+WORKER_WORKSPACE         工作目录（默认 cwd）
+WORKER_LLM_BASE_URL      OpenAI 兼容端点（如 https://api.deepseek.com/v1）
+WORKER_LLM_API_KEY       模型 key（不打印）
+WORKER_LLM_MODEL         模型名（默认 deepseek-chat）
+WORKER_MAX_STEPS / WORKER_MAX_TOKENS / WORKER_MAX_WALL_CLOCK_MS  可选覆盖上限
+```
+
+stdout 只输出最终 WorkerResult JSON；日志走 stderr。
+
+### 类型检查
+
+```bash
+npm install
+npm run typecheck:worker   # tsc -p tsconfig.worker.json（strict + noEmit）
+```
+
+### 作为 Cordis preset
+
+```ts
+import { apply, runWorker } from './worker/index.ts'
+apply(ctx) // 监听 superagent:worker:start；也可直接 runWorker(ticket, deps)
+```
+
+## 7. 工程落地的理由
+
+- **安全外壳**：校验权在 Worker 代码，不在模型；越权直接返回系统拒绝文本；
+- **熔断**：步数/Token/墙钟三道硬红线，计费与 CPU 的兜底；
+- **容错**：工具失败作为观察结果回灌，模型可自行 debug；LLM 超时/预算错误分类上报；
+- **可追溯**：每步带 timestamp/tokenUsage，`snapshot()` 支持崩溃恢复与人工复盘；
+- **物理隔离**：以上都在分身 VM 内；Router/宿主不在 Worker 工具可达范围。
+
+## 8. 真实流式（3.2.5）
+
+- `LLMClient.chatStream?(request, onDelta)` 是可选能力：provider 支持 SSE 时逐 token 回调；
+- `chatStream` 的 delta 直接进 `WorkerSink.stream` → HTTP sink → Router `worker-events` → SSE/宿主 adapter；
+- 未实现 `chatStream` 的 provider 仍走 `chat()` + 分块模拟（行为不变）；
+- 同一 step 内不会同时出现「真实 delta」与「模拟分块」（`streamedThisStep` 守卫）。
+
+## 9. 回写与边界（3.2.5）
+
+- **LLM 工具循环已实现**（本文件第 1-4 节），并由真实 Host smoke 验证；
+- **结果回写**：Worker done → Router（SSE/worker-events）→ webhook / GitHub Issue 评论 / 飞书机器人；
+- **PR**：`create_pr` 工具可接真实 GitHub 客户端（`DSH_MASTER_GITHUB_TOKEN/REPO`），需要先把分支 push 到远端；
+- 回写默认关闭，失败只告警，不改变 Ticket 终态；token 不入日志/状态。
+
+- Worker preset 已用 tsc 构建到 `dist-worker/` 并接入 bundle 行 `master-superagent-loop`（fork only）；
+- Router 生成的 per-ticket token 通过 HTTP POST 把事件实时回传 Router；前端 SSE/WS 转发待 3.2.4；
+- 回写（webhook / GitHub Issue 评论）默认关闭，按宿主配置启用；失败只告警；
+- 跨进程派发桥需要宿主配置 `bridgeToken`（母体）与 `motherUrl/motherToken`（原身），默认关闭；
+- Shell 的 VM/容器隔离仍是主防线；未证明隔离时不要开启 `allowShell`；
+- PR 创建、浏览器实时 UI、Worker 并发/配额看护仍待 3.2.4+。

package/icon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="dsh-Master">
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="#0B1F33"/>
+  <path d="M14 30 L32 15 L50 30" fill="none" stroke="#4CC2FF" stroke-width="3.2" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M19 29 L19 47 L45 47 L45 29" fill="none" stroke="#E8F2FF" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="24" cy="38" r="3" fill="#4CC2FF"/>
+  <circle cx="32" cy="38" r="3" fill="#7DE2C3"/>
+  <circle cx="40" cy="38" r="3" fill="#FFB454"/>
+  <path d="M24 38 L32 38 L40 38" fill="none" stroke="#E8F2FF" stroke-width="1.4" stroke-dasharray="2 2"/>
+</svg>

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Master (dsh-Master)",
+    "description": "The main agent plugin parallel to dsh-Fang: hosts SuperAgent, cost optimizer, and PM/PJM dual managers."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "房主（dsh-Master）",
+    "description": "与瓮城 dsh-Fang 并行的主 Agent 插件：托管超级智能体、成本优化、PM/PJM 双主管三个子插件。"
+  }
+}

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@twinsearth/dsh-master",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.2.9",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "description": "Dsh-Master（房主）：与瓮城 dsh-Fang 并行的主 Agent 插件，托管 SuperAgent Router/Worker、HarnessMM、PM+PJM。",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "dsh-bundle",
+    "master",
+    "superagent",
+    "harnessmm",
+    "pm",
+    "pjm"
+  ],
+  "exports": {
+    ".": "./dist-host/index.js",
+    "./superagent-router": "./dist-host/plugins/superagent-router.js",
+    "./superagent-worker": "./dist-host/plugins/superagent-worker.js",
+    "./superagent-loop": "./dist-worker/index.js",
+    "./contract": "./dist-host/contract/index.js",
+    "./cost-optimizer": "./dist-host/plugins/cost-optimizer.js",
+    "./dual-manager": "./dist-host/plugins/dual-manager.js",
+    "./client": {
+      "browser": "./client.js",
+      "default": "./client.js"
+    },
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "src/**/*.ts",
+    "src/**/*.js",
+    "worker/**/*.ts",
+    "dist-worker/**/*.js",
+    "dist-host/**/*.js",
+    "types/*.d.ts",
+    "tsconfig.worker.json",
+    "tsconfig.worker.build.json",
+    "tsconfig.host.json",
+    "tsconfig.host.build.json",
+    "client.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "docs/**/*.md",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test --test-force-exit test/",
+    "test:clean": "node --test --test-concurrency=1 test/",
+    "test:worker": "node --test --test-force-exit test/worker-agent-loop.test.ts test/worker-tools.test.ts test/worker-llm-http.test.ts test/worker-sink-http.test.ts",
+    "typecheck:worker": "tsc -p tsconfig.worker.json",
+    "build:worker": "tsc -p tsconfig.worker.build.json",
+    "worker": "node dist-worker/main.js",
+    "check": "node --check client.js && tsc -p tsconfig.host.json && tsc -p tsconfig.worker.json",
+    "typecheck:host": "tsc -p tsconfig.host.json",
+    "build:host": "tsc -p tsconfig.host.build.json",
+    "build": "npm run build:host && npm run build:worker"
+  },
+  "devDependencies": {
+    "@twinsearth/dsh-fang-contract": "^1.0.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": []
+    }
+  },
+  "types": "./types/superagent.d.ts"
+}

package/src/contract/client.js

@@ -0,0 +1,86 @@
+// 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/src/contract/constants.js

@@ -0,0 +1,79 @@
+// 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/src/contract/envelope.js

@@ -0,0 +1,83 @@
+// 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
+}

package/src/contract/index.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang/dsh-Master contributors — see LICENSE.
+
+/**
+ * @twinsearth/dsh-fang-contract
+ *
+ * 瓮城（dsh-Fang）↔ 房主（dsh-Master）的独立版本化互联 SDK。
+ * 设计目标：
+ *   1. 双方独立升级：语义化版本 + hello 协商 + 未知字段忽略 + 方法版本裁剪；
+ *   2. 互联互通保底：local → http → file → legacy 四级传输自动降级；
+ *   3. 接口包可独立替换：更新本包即升级接口架构，旧方法在 MAJOR 内保持可调用。
+ */
+
+export * from './constants.js'
+export * from './envelope.js'
+export * from './negotiate.js'
+export * from './server.js'
+export * from './transports.js'
+export * from './client.js'

package/src/contract/negotiate.js

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang/dsh-Master contributors — see LICENSE.
+
+import {
+  CAPABILITIES,
+  CONTRACT_VERSION,
+  ERROR_CODES,
+  METHOD_VERSION,
+  METHODS,
+  MIN_COMPATIBLE_MAJOR,
+  PROTOCOL,
+  ROLES,
+} from './constants.js'
+
+export function parseVersion(value) {
+  const text = String(value ?? '').trim()
+  const match = /^(\d+)\.(\d+)(?:\.(\d+))?/.exec(text)
+  if (!match) return null
+  return {
+    major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3] ?? 0), text,
+  }
+}
+
+export function compareVersions(a, b) {
+  const pa = parseVersion(a)
+  const pb = parseVersion(b)
+  if (!pa || !pb) return 0
+  if (pa.major !== pb.major) return pa.major - pb.major
+  if (pa.minor !== pb.minor) return pa.minor - pb.minor
+  return pa.patch - pb.patch
+}
+
+/** 标准 hello payload（服务端暴露；客户端据此协商）。 */
+export function helloPayload({
+  role = 'mother',
+  instanceId = '',
+  version = CONTRACT_VERSION,
+  methods = Object.values(METHODS),
+  capabilities = CAPABILITIES,
+  transports = [],
+  startedAt = Date.now(),
+} = {}) {
+  return {
+    protocol: PROTOCOL,
+    contractVersion: String(version),
+    role: ROLES.includes(String(role)) ? String(role) : 'fork',
+    instanceId: String(instanceId ?? ''),
+    startedAt: Number(startedAt) || Date.now(),
+    methods: [...new Set(methods.map(String))],
+    capabilities: [...new Set(capabilities.map(String))],
+    transports: [...new Set(transports.map(String))],
+    features: {
+      idempotency: true,
+      envelopes: true,
+      fileOutbox: true,
+      versionNegotiation: true,
+    },
+  }
+}
+
+/**
+ * 双向版本协商。
+ * @param {object} local 本端 helloPayload
+ * @param {object} remote 对端 helloPayload
+ * @returns {{ok:boolean, compatible:boolean, fallback:'legacy'|null, reason?:string, version?:string, methods:string[], capabilities:string[], features:object}}
+ */
+export function negotiate(local, remote) {
+  const lv = parseVersion(local?.contractVersion)
+  const rv = parseVersion(remote?.contractVersion)
+  if (local?.protocol !== PROTOCOL || remote?.protocol !== PROTOCOL) {
+    return { ok: false, compatible: false, fallback: 'legacy', reason: 'protocol-mismatch', methods: [], capabilities: [], features: {} }
+  }
+  if (!lv || !rv) {
+    return { ok: false, compatible: false, fallback: 'legacy', reason: 'version-invalid', methods: [], capabilities: [], features: {} }
+  }
+  if (rv.major < MIN_COMPATIBLE_MAJOR) {
+    return { ok: false, compatible: false, fallback: 'legacy', reason: 'remote-too-old', methods: [], capabilities: [], features: {} }
+  }
+  if (rv.major > lv.major) {
+    return { ok: false, compatible: false, fallback: 'legacy', reason: 'remote-too-new', methods: [], capabilities: [], features: {} }
+  }
+  const localMethods = new Set(Array.isArray(local.methods) ? local.methods : [])
+  const methods = (Array.isArray(remote.methods) ? remote.methods : []).filter((method) => localMethods.has(method))
+  // 裁剪：方法所需契约 minor 不能高于双方共同支持的 minor。
+  const commonMinor = Math.min(lv.minor, rv.minor)
+  const supported = methods.filter((method) => {
+    const methodVersion = parseVersion(METHOD_VERSION[method] ?? '1.0')
+    return !methodVersion || methodVersion.minor <= commonMinor || methodVersion.major < lv.major
+  })
+  const localCaps = new Set(Array.isArray(local.capabilities) ? local.capabilities : [])
+  const capabilities = (Array.isArray(remote.capabilities) ? remote.capabilities : []).filter((cap) => localCaps.has(cap))
+  const version = `${Math.min(lv.major, rv.major)}.${commonMinor}.0`
+  return {
+    ok: true,
+    compatible: true,
+    fallback: null,
+    version,
+    methods: supported,
+    capabilities,
+    features: { ...(local.features ?? {}), ...(remote.features ?? {}) },
+  }
+}
+
+export function unsupportedMethodError(method) {
+  return { code: ERROR_CODES.UNSUPPORTED_METHOD, message: `unsupported method: ${String(method)}`, retryable: false }
+}