@twinsearth/fang-dsh-plugin 0.0.0-stage → 3.3.4

package/cordis.patch.yml

@@ -0,0 +1,163 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+# dsh-Fang v1.0.0 — bundle layer.
+# One installable bundle; one loader row per plugin. The row order is a dependency
+# order: auditor/forker/buffer feed the middle tier, orchestrator comes last.
+- insert:
+    - id: fang-auditor
+      name: '@twinsearth/fang-dsh-plugin/auditor'
+      config:
+        dataRoot: ''
+        bootSelfCheck: true
+
+    - id: fang-forker
+      name: '@twinsearth/fang-dsh-plugin/forker'
+      config:
+        cliPath: ''
+        profileTemplate: ''
+        startTimeoutMs: 60000
+        maxForks: 8
+        supervise: false
+        maxRestarts: 3
+        backoffBaseMs: 1000
+        backoffMaxMs: 30000
+        backoffJitter: 0.2
+        healthPath: /
+
+    - id: fang-buffer-keeper
+      name: '@twinsearth/fang-dsh-plugin/buffer-keeper'
+      config:
+        root: ''
+        settleMs: 750
+        pollMs: 250
+
+    - id: fang-scorer
+      name: '@twinsearth/fang-dsh-plugin/scorer'
+      config:
+        allowlist: []
+
+    - id: fang-umbrella
+      name: '@twinsearth/fang-dsh-plugin/umbrella'
+      config:
+        bufferRoot: ''
+        productionRoot: ''
+        allowPaths: []
+        networkAllowlist: []
+        credentialPatterns: []
+        destructivePatterns: []
+        lifecyclePatterns: []
+        lifecycleTools: []
+        gradeFloorTable: umbrella
+        cacheSize: 200
+        auditDecisions: true
+
+    - id: fang-healer
+      name: '@twinsearth/fang-dsh-plugin/healer'
+      config:
+        blockingOnUnknown: true
+        reservedIds: []
+
+    - id: fang-router
+      name: '@twinsearth/fang-dsh-plugin/router'
+      config:
+        containerAvailable: false
+        trustedPlugins: []
+
+    - id: fang-approver
+      name: '@twinsearth/fang-dsh-plugin/approver'
+      config:
+        defaultTtlMs: 300000
+        remindAt: 0.5
+        authMode: manual
+        strictRedLine: true
+        backupRoot: ''
+
+    - id: fang-hot-reloader
+      name: '@twinsearth/fang-dsh-plugin/hot-reloader'
+      config:
+        healthWindowMs: 300
+        healthMaxNewHandles: 2
+        requireApprovalForSwap: true
+
+    - id: fang-restart-guard
+      name: '@twinsearth/fang-dsh-plugin/restart-guard'
+      config:
+        mode: observe
+        authMode: manual
+        strictRedLine: true
+        allowProcessRestart: false
+        autoPromoteAfterHours: 24
+
+    - id: fang-adapter
+      name: '@twinsearth/fang-dsh-plugin/adapter'
+      config:
+        prefix: /fang
+        taskId: ''
+        auditLimit: 500
+        commandTimeoutMs: 10000
+
+    - id: fang-session-catalog
+      name: '@twinsearth/fang-dsh-plugin/session-catalog'
+      config:
+        limit: 50
+        allowArchived: false
+        previewMaxChars: 2000
+
+    - id: fang-session-bridge
+      name: '@twinsearth/fang-dsh-plugin/session-bridge'
+      config:
+        dshHome: ""
+        prefix: /fang
+        timeoutMs: 15000
+
+    - id: fang-session-sync
+      name: '@twinsearth/fang-dsh-plugin/session-sync'
+      config:
+        sessionsRoot: ""
+        bundleRoot: ""
+        maxBundleBytes: 536870912
+
+    - id: fang-session-router
+      name: '@twinsearth/fang-dsh-plugin/session-router'
+      config:
+        sameMachine: true
+        bridgeEnabled: true
+        needsRealtime: false
+
+    - id: fang-decision-center
+      name: '@twinsearth/fang-dsh-plugin/decision-center'
+      config:
+        maxTickets: 500
+        maxPendingRed: 30
+        defaultTimeoutMinutes: 360
+        tickMs: 5000
+        registerTool: true
+
+    - id: fang-orchestrator
+      name: '@twinsearth/fang-dsh-plugin'
+      config:
+        role: mother
+        maxForks: 8
+        autoReapIdleMinutes: 0
+        routes:
+          enabled: true
+          prefix: /fang
+        contract:
+          enabled: true
+          token: ''
+          fileDir: ''
+          pathPrefix: /fang/api/contract
+
+    # Child plugin of the fang bundle: composer draft/queue journal (client half).
+    # The main Web panel is the fang client half itself (package.json dsh.client),
+    # so the plugin is fully usable without the PC Electron client.
+    - id: fang-web-entry
+      name: '@twinsearth/dsh-fang-web-entry'
+
+    # v3.3.3: default OFF. Draft/queue recovery is optional; the host half
+    # provides fangQueueJournal only when this row is enabled, and without it
+    # the orchestrator returns 503 queue-journal-disabled for journal/queue
+    # routes. The client half is not loaded, so its composer UI stays hidden.
+    - id: fang-queue-journal
+      name: '@twinsearth/dsh-fang-queue-journal'
+      disabled: true

package/defaults/umbrella-rules.yaml

@@ -0,0 +1,113 @@
+# dsh-Fang v2.8.1 — Umbrella 推荐基线配置（随包分发，项目不可替换，只能叠加）
+#
+# 加载顺序（后加载的层按 id 覆盖先加载的层；未列出的规则保持内置默认）：
+#   1) 本文件（包内基线）                    ← defaults/umbrella-rules.yaml
+#   2) 项目级 <project>/.dsh/umbrella-rules.yaml（插件配置 rulesFile）
+#   3) 环境级 $UMBRELLA_RULES_PATH（CI/部署注入，可选）
+#
+# 锁定语义：带 non-negotiable / hard-deny 标签的规则不可被**关闭**、不可被**降低灯色**；
+# 允许项目追加 pattern（扩大覆盖面）或提升灯色（更严格）。
+# 项目尝试关闭硬规则 → 该层错误；若该层 failOnInvalidPattern: true → 整层拒绝，回退到基线。
+#
+# 说明：本文件刻意**只显式写硬规则与兜底**。可调规则留空 = 使用内置默认值，
+# 项目按需在自己的叠加层里覆盖（示例见文件末尾注释与 docs/RULES-BASELINE.md）。
+
+version: 1
+
+settings:
+  failOnUnknownRule: false      # 未知 id 只警告，不阻断（基线可能领先于代码）
+  failOnInvalidPattern: true    # 正则/声明式规则编译失败视为配置错误，整层拒绝（宁可不启动）
+  rejectUnsafeRegex: true       # 拒绝明显灾难回溯的正则形状
+
+rules:
+  # ── 硬规则：显式锁定（不可关闭、不可降级）──────────────────────────────
+  - id: dsh-lifecycle
+    enabled: true
+    light: red
+    priority: 10
+    reason: "DSH 宿主的生命周期动作（重启/终止/进程级），必须转交 restart-guard 审批"
+    tags: [hard-deny, non-negotiable, delegate-to-restart-guard]
+
+  - id: destructive-command
+    enabled: true
+    light: red
+    priority: 20
+    reason: "破坏性 shell 命令（rm -rf / format / shutdown / 强制推送等），一律红色"
+    tags: [hard-deny, non-negotiable]
+
+  - id: credential-access
+    enabled: true
+    light: red
+    priority: 30
+    reason: "读取凭据路径（.ssh/.aws/.gnupg/.git-credentials 等），唯一硬拒绝出口"
+    tags: [hard-deny, non-negotiable]
+
+  # ── 兜底：安全网（不可关闭）──────────────────────────────────────────────
+  # 未登记的工具/没有可识别目标时落到这里；优先级 9999 保证它永远最后。
+  - id: unknown-tool
+    enabled: true
+    light: yellow
+    priority: 9999
+    reason: "未知工具或目标：行为不可预测，保守判黄（需审批）"
+    tags: [conservative, non-negotiable]
+
+# ── 可调规则：留空 = 使用内置默认。下面是**推荐值**（注释形式），项目按需覆盖 ──
+#
+# 用于参考的默认（与 DEFAULT_RULE_PRIORITIES 一致）：
+#   network-allowlisted   blue    40     外连命中允许列表 → 放行 + 标记
+#   network-egress        yellow  50     外连未在允许列表 → 拆审批
+#   dynamic-import        yellow  60     动态加载未评分模块 → 先扫描
+#   write-in-buffer       blue    70     写沙箱缓冲区 → 放行 + 标记
+#   write-in-allowlist    blue    80     写允许列表路径 → 放行 + 标记
+#   write-production      yellow  90     写生产区 → 需审批
+#   write-outside-buffer  yellow  100    写越界 → 需审批
+#   exec-read-only        blue    110    只读 shell（无重定向）→ 放行 + 标记
+#   exec-side-effect      yellow  120    shell 有副作用 → 需审批
+#   read-in-buffer        green   130    读沙箱缓冲区 → 自动放行
+#   read-outside-buffer   blue    140    读缓冲区外 → 放行 + 标记
+#
+# 项目级覆盖示例（写在 <project>/.dsh/umbrella-rules.yaml）：
+#
+# version: 1
+# settings:
+#   failOnInvalidPattern: true
+# rules:
+#   # 更严格：越界写从黄升红
+#   - id: write-outside-buffer
+#     light: red
+#     reason: "本项目：任何越界写都直接拒绝"
+#
+#   # 更严格：生产区写也需要人工审批（升红）
+#   - id: write-production
+#     light: red
+#
+#   # 追加凭据 pattern（硬规则允许"扩大覆盖面"，不允许关闭）
+#   - id: credential-access
+#     pathPatterns:
+#       - re: "\\.npmrc$"
+#         label: "npm registry token"
+#       - re: "secrets[\\\\/]"
+#         label: "project secrets directory"
+#
+#   # 项目专属声明式规则
+#   - id: project-build-guard
+#     category: destructive
+#     light: red
+#     reason: "禁止删除构建目录"
+#     priority: 25
+#     match:
+#       kind: command-pattern
+#       patterns:
+#         - re: "\\brm\\s+-rf\\s+(?:dist|build|out)\\b"
+#           label: "delete build directory"
+#     evidence:
+#       kind: pattern-match
+#
+#   # 以下写法会被拒绝（硬规则锁定）：
+#   # - id: destructive-command
+#   #   enabled: false      # → "cannot be disabled"
+#   # - id: credential-access
+#   #   light: yellow       # → "light cannot be lowered from red to yellow"
+#
+# 注意：`light: blue` 不能把 network-egress 变成"内网放行"——它的谓词看 allowHosts；
+# 要放行内网域请把它们加入 policy.networkAllowlist，而不是只改灯色。

package/docs/CONTRACT-INTEROP.md

@@ -0,0 +1,77 @@
+# 房主 ↔ 瓮城 互联契约（v3.2.4）
+
+> 目标：**双方独立升级/发布，仍能互联互通**；接口架构可通过更新契约包整体替换，
+> 同时保留多级保底通讯。  
+> 实现：`@twinsearth/dsh-fang-contract` 1.0.x（源码独立仓，另见 `TwinsEarth/dsh-fang-contract`），
+> 两侧各自内嵌**同一份** `src/contract/` 源码（无运行时 npm 依赖），版本号一致。
+
+## 1. 契约内容
+
+- 方法表：`contract.hello/health`、`fang.fork.spawn/stop/list`、`fang.decision.create/resolve`、
+  `fang.session.list`、`fang.orchestrator.status`；
+- 信封：`protocol=fang-master, protocolVersion=1, id, method, params, meta`；
+- 版本协商：`hello` 返回 `contractVersion / role / methods / capabilities / transports`，
+  `negotiate()` 裁剪双方方法交集；MAJOR 不兼容时自动降级；
+- 错误码：`unsupported-method / unsupported-version / transport-* / all-transports-failed` 等。
+
+## 2. 四级保底传输
+
+```text
+local  同 Host DSH 服务 fangContract（零网络，首选）
+  ↓ 不可用/超时
+http   POST /fang/api/contract/{hello,invoke}（Bearer token）
+  ↓ 不可用/超时
+file   同一文件系统 outbox/inbox（requests/*.json → responses/*.json）
+  ↓ 不可用/超时
+legacy 直接调用 3.1.x 旧服务键（fangForker / fangDecisionCenter 等）
+```
+
+业务错误（如 `ticket-invalid`）**不降级**，避免重复副作用；传输/协议/未知方法才降级。
+每次尝试记录在 `client.attempts()`，状态可观测。
+
+## 2.5 零配置（v3.1.16 / 房主 3.2.5）
+
+瓮城原身运行态的 spawn 环境新增 `DSH_FANG_MOTHER=<母体 dataDir>`；房主 Router 检测到该变量后
+自动使用 `<母体 dataDir>/contract-outbox` 作为 `dispatch.contractFileDir`，无需手工配置：
+
+```text
+原身 Host（essence Router）
+  env: DSH_FANG_ROLE=fork / DSH_FANG_ESSENCE=1 / DSH_FANG_MOTHER=<母体 dataDir>
+    ↓ dispatch.contract=true（自动 file 桥）
+<母体 dataDir>/contract-outbox/requests → responses
+    ↓
+母体 Host（Fang contract service）→ 真实 fork
+```
+
+HTTP 桥需要两个凭据：契约 Bearer token + 安装级 `x-fang-auth`；房主通过
+`dispatch.motherToken` 与 `dispatch.motherAuthToken` 提供（SDK 侧为可选 `headers`）。
+
+## 3. 两侧实现位置
+
+| 侧 | 文件 | 内容 |
+|---|---|---|
+| 瓮城 dsh-Fang v3.1.15 | `src/contract/` + `src/plugins/orchestrator.mjs` | 内嵌契约 SDK；mother 提供 `fangContract` 服务；HTTP `/fang/api/contract/*`；可选 file outbox server |
+| 房主 dsh-Master v3.2.4 | `src/contract/` + `src/superagent/dispatch.mjs` | 内嵌同一 SDK；派发优先 contract（local/http/file/legacy），失败再回退本地 forker/母体 bridge |
+
+两侧都不 import 对方内部源码，只依赖契约包稳定接口。
+
+## 4. 独立升级 / 完全替换流程
+
+1. 修改并发布契约包（源码仓 `dsh-fang-contract`，版本 `x.y.z`）；
+2. 将 `src/contract/` 同步到两侧（同源文件，`CONTRACT_VERSION` 一致）；
+3. MINOR：双方可不同时升级；`hello` 协商后使用方法交集，旧端自动降级；
+4. MAJOR：新方法同时保留 `method@old` 一个 MINOR 周期（双写），两侧逐侧升级；
+5. 观察 `client.attempts()` / `describe()` 的 transport 命中与降级；
+6. 旧 MAJOR 下线前至少保留一个 MINOR 周期的 legacy 传输。
+
+> npm 上 `@twinsearth/dsh-fang-contract@1.0.0` 首次发布被 npm **staged publishing**
+> 置为 `0.0.0-stage` 占位（需 2FA/stage 审批后才能成为正式版本）；  
+> 本次两个主包采用“同源内嵌 + 独立源码仓”的方式先行发布，待 npm 正式可用后
+> 可改为依赖 npm 包，无需改协议/代码。
+
+## 5. 安全
+
+- HTTP 契约必须 Bearer token（两侧各自配置 `contract.token` / `dispatch.motherToken`）；
+- env 只透传 `DSH_MASTER_*`；契约响应/状态不含 key/token/私钥；
+- file outbox 目录须在受控本机路径，由 OS 账户隔离；
+- legacy 传输只调用既有服务键，不扩大权限。

package/docs/CRASH-SAFETY.md

@@ -0,0 +1,69 @@
+# CRASH-SAFETY — 瓮城防崩溃方案（防线、强制点、运行手册）
+
+> 状态：生效中（2026-11-10 起固化）。与 `docs/WORKFLOW-UI.md` 一起受测试/打包/发布门禁保护。
+> 发布动作遵循 `docs/WORKFLOW-UI.md` §0：**发布必须由人类显式授权**，禁止自动 release/npm/GitHub Release。
+> 目标：**插件树坏一行，不拖垮宿主；分身崩溃，不扩散；配置变更，可回滚。**
+
+## 1. 威胁模型
+
+| 威胁 | 后果 | 现有防线 |
+|---|---|---|
+| 插件 bundle 某行解析失败 / 模块缺失 / `apply()` 抛错 | 宿主启动崩溃或半启动 | boot-guard 启动前自检 + 失败行 `disabled` + 安全模式 |
+| 插件崩溃把宿主 fiber 带走 / 反复崩 | 母体不可用 / 崩溃循环 | Cordis fiber 隔离 + RestartGuard 唯一重启闸门 |
+| 分身进程崩溃 / 事件循环耗尽 / `process.exit()` | 任务失败、端口/资源泄漏 | 独立进程 + 独立 `DSH_HOME` + 退避重启 + 孤儿回收 |
+| 角色/权限边界被绕过 | 越权写母体 | role fail-closed（`roleGate`/`roleAllows`） |
+| 崩溃后状态丢失/重复执行 | 重复任务、丢事件 | fork meta（crashCount/restartCount/lastError）+ 待处理缓冲 + 未清洁启动检测 |
+| 升级把运行中的 profile 改坏 | 客户端崩溃、用户配置丢失 | 升级安全规程（停 host、备份、候选包冒烟、装后 dry-run、回滚） |
+
+## 2. 防线清单（代码事实）
+
+| 防线 | 入口 | 行为 |
+|---|---|---|
+| boot-guard | `src/lib/boot-guard.mjs`、`tools/boot-guard.mjs` | 解析 fang bundle 行；重复 id / 模块解析 / 隔离子进程 `import` 且导出 `apply()`；失败行可 `--apply` 写成 `disabled:true`（写前备份）；`--safe-mode` 全禁 fang 行；`--candidate-dir` 用于更新候选包冒烟 |
+| RestartGuard | `src/plugins/restart-guard.mjs` | `classifyRisk` / `decide` / `findGrant`；母体重启唯一入口，默认只到审批/审计，不直接退出进程 |
+| 分身隔离与监督 | `src/plugins/forker.mjs`、`src/lib/fork-supervisor.mjs` | 每任务独立进程 + 独立 `DSH_HOME`；`planRestart` 指数退避 + 最大次数；`reconcileOrphans` 只回收死亡孤儿、不 kill 活实例；`writeForkMeta` 原子写 meta |
+| 角色 fail-closed | `src/kernel/role.mjs` | `roleGate` / `roleAllows`：未知角色默认拒绝，不默认放行 |
+| 待处理缓冲 | `src/plugins/buffer-keeper.mjs` | pending 观察 + digest 兜底 + 静默窗口；时间戳缺失时补观测时间，避免误判 |
+| 未清洁启动检测 | `src/lib/desktop-launch.mjs` | `readUncleanBoot` / `runBootGuard` / `resolveDesktopLaunch`：桌面启动前检测上次崩溃并跑 guard |
+
+## 3. 强制点矩阵（改坏就红）
+
+| 环节 | 命令/文件 | 覆盖 |
+|---|---|---|
+| 单测 | `test/boot-guard.test.mjs`、`test/desktop-launch.test.mjs`、`test/fork-supervisor.test.mjs`、**`test/crash-safety.test.mjs`（新增）** | 行解析/隔离冒烟/禁用写回；未清洁启动；退避/孤儿；门禁工具自身 |
+| 发布前源码门禁 | `node tools/release/preflight.mjs` → `crash-safety --json` | 防线文件存在、纯函数导出、插件闸门 token、client 半浏览器安全、文档与打包清单 |
+| 打包后门禁 | `node tools/release/build.mjs` → `crash-safety --package dist/npm/package --tarball …` | **最终产物**内必需防线文件、版本/client 声明、候选包 `apply()` 冒烟、manifest sha256、tarball 内约束文档 |
+| 发布 | release workflow build job（内置 `build.mjs` → preflight + crash-safety） | 未过 crash-safety 的产物不会进入 GitHub Release / npm |
+
+## 4. 运行手册
+
+### 4.1 启动前自检（profile 有 Fang）
+
+```bash
+node tools/boot-guard.mjs --profile-dir <profile> --json        # dry-run，只读
+node tools/boot-guard.mjs --profile-dir <profile> --apply       # 禁用失败行（备份后写 profile patch）
+node tools/boot-guard.mjs --profile-dir <profile> --safe-mode   # 全禁 fang 行（救急）
+```
+
+### 4.2 升级候选包（不碰运行中的 profile）
+
+```bash
+node tools/boot-guard.mjs --candidate-dir <解包后的候选包目录> --json  # 入口存在 + apply() 冒烟
+# 停 host → 备份 profile 用户层 → 安装 → 装后 dry-run → 启动 → 失败则恢复备份/--apply
+```
+
+### 4.3 崩溃后处置顺序
+
+1. 先看 `fang-meta.json` 的 `crashCount/lastError` 与宿主日志，确认是分身还是母体；
+2. 分身：等监督重启（opt-in）或手动重启；孤儿按 `reconcileOrphans` 规则处理，不 kill 活实例；
+3. 母体：走 RestartGuard 审批；启动前跑 boot-guard dry-run，确认不是插件树坏行；
+4. 若确认是某行插件：`--apply` 禁用该行并记录，恢复后单独排查该插件；
+5. 复盘：把新发现的崩溃模式补进本文件和 `test/crash-safety.test.mjs`。
+
+## 5. 边界（诚实）
+
+- 不承诺宿主内核/Node 自身崩溃恢复；Cordis fiber 隔离只覆盖插件生命周期错误。
+- 分身与母体是**同用户、同 ACL**，不是权限隔离；`DSH_HOME` 隔离只防数据串写。
+- 桌面 Electron 壳（`dsh-fang-desktop/panel`）是另一套 UI，不在 web 控制台门禁覆盖内。
+- `crash-safety` 是**静态+冒烟**门禁，不是形式化证明；它保证“已知防线还在、产物能加载”，
+  不保证任意新插件逻辑无崩溃。

package/docs/DECISION-RELAY.md

@@ -0,0 +1,46 @@
+# DECISION-RELAY — 会话内决策中继（v3.1.13）
+
+## 目标
+
+决策中心不再只在母体「收件箱」里处理：**每个会话自己**在右侧显示待决策入口，
+用户在该会话里直接选 A/B/C/D 或输入决定，Agent 收到结果后继续任务。
+总体界面仍在母体：收件箱（侧栏入口 + 右侧抽屉）保持原样，汇总所有会话/分身的待决策。
+
+## 行为
+
+1. **悬浮入口**：当前会话存在 `pending` 决策时，右侧边缘出现红色「◈ 待选 N」悬浮按钮；
+   没有待决策时不显示（避免干扰）。入口只在**母体 Web** 注册——分身/元宝运行态不显示
+   （决策由母体的收件箱统一处理）。
+2. **从右向左滑出**：点击按钮，决策栏从右侧滑入（`translateX` 过渡 + 遮罩），`Esc` 或点遮罩关闭。
+3. **按会话过滤**：只显示 `source.sessionId === 当前会话` 的 ticket；其他会话/分身的票留在收件箱。
+4. **选择或输入**：
+   - 预置选项按 **A/B/C/D** 标号显示（超过 4 个继续 E、F…），点击即提交 `option.value`；
+   - 直接在输入框写决定（如“按 B 方案，先灰度 10%”），提交后作为 **custom decision**；
+   - 无预置选项的 green/ack 票显示「确认收到（ACK）」。
+5. 提交后按钮计数实时更新；没有待决策时按钮消失，面板提示为空。
+
+## 服务端语义
+
+`POST /fang/api/decisions/resolve` 新增可选字段 `custom`：
+
+- 仅在**显式**传 `custom` 时生效（不是“任意未知 option 都放过”）；
+- 去空白、上限 2000 字符；`resolvedOption = custom`、`resolvedPayload = {custom}`、
+  `resolutionNote = custom`、ticket 标记 `customInput: true`；
+- 未传 custom 的未知 option 仍按原逻辑拒绝（`unknown-option`，fail-closed）；
+- Agent 的 `request_human_decision` 返回值 `selectedValue` 即用户输入/选项值，据此继续。
+
+## 代码位置
+
+| 文件 | 作用 |
+|---|---|
+| `client.js` | `mountDecisionRelay()`：悬浮按钮 + 右滑面板 + A/B/C/D + 自定义输入；slot `conversation.session.header.utilities`；store 新增 `resolveCustom()` |
+| `src/plugins/decision-center.mjs` | `resolve()` 接受 `custom`；`publicTicket` 暴露 `customInput` |
+| `src/plugins/orchestrator.mjs` | `/fang/api/decisions/resolve` 透传 `custom` |
+| `test/decision-relay-dom.test.mjs` | 入口/面板/选项/自定义输入/会话过滤/fork 不挂载 |
+| `test/decision-center.test.mjs` | custom 解析 + 未知 option 仍 fail-closed |
+
+## 边界
+
+- 只在母体 Web 的会话里出现；分身 Web 的决策仍在母体收件箱处理。
+- 悬浮按钮依赖 DSH 会话 header utilities 槽与 sessionId 标准属性；DSH 大版本升级需回归对应 DOM 测试。
+- 自定义输入会作为决定原文写入 ticket/审计，注意不要输入密钥等敏感信息。

package/docs/DSH-ARCHITECTURE-MAP.md

@@ -0,0 +1,73 @@
+# DSH 系统架构 × 瓮城安全边界（v3.3.0）
+
+> 依据：DeepSeek Harness 0.2.2 架构文档与仓库内实际代码（`dsh --profile <name> --dump-config` 是最终事实）。
+> 本文只记录「哪些层会影响主城安全、瓮城在哪一层设闸」。逐文件行号会随 DSH 版本变化，结论以能力边界为准。
+
+## 1. 分层总图
+
+```text
+入口：dsh CLI / Web / Electron / SDK / ACP
+  └─ Profile（$DSH_HOME/profiles/<name>）
+       ├─ 有序 bundles（dsh-base / dsh-web-app / 树外插件）
+       ├─ profile cordis.patch.yml
+       └─ home 级 cordis.patch.yml + CLI --patch
+            └─ Cordis 插件树（一切皆是插件）
+                 ├─ Host Plane：llm / sessions / tools / sandbox / approval / subagents / presets
+                 ├─ Agent Plane：每个 Agent 的 tools / prompt sections / delegation
+                 └─ Session：append-only SessionEvent 日志（模型可见 ⟺ 已记录）
+```
+
+## 2. 与主城安全直接相关的十层
+
+| 层 | DSH 机制 | 失败后果 | 瓮城闸门 |
+|---|---|---|---|
+| Profile 组合 | bundles 有序 + patch 逐层覆盖 | 缺 bundle/重复/坏 patch → 起不来或半残 | `profile` gate：路径、名称、bundles 去重、patch 解析、磁盘 |
+| 插件生命周期 | Cordis Fiber；PENDING/LOADING/ACTIVE/FAILED；effect 可回收 | 注册泄漏/依赖缺失 → 静默无能力 | boot-guard + 关键防线文件 + 插件冒烟 |
+| Host/Agent 平面 | 注册表与工具作用域隔离 | 把 host 注册表塞进 isolate → 名称解析失败 | 不在门禁里改 profile 层，只做只读校验 |
+| Agent Loop | turn/step/工具批次；错误恢复 append-only | 半途崩溃留下不一致历史 | restart safe-mode + 审计链 |
+| Session 日志 | 追加式、版本化、可重建 | 篡改/删行会让重放失真 | `audit` 链 + Session 版本校验（DSH 自身） |
+| 工具执行 | tools/pre-execute → guard → execute → post-execute | 权限绕过/危险命令 | DSH guard/approval/sandbox 原生；瓮城不削弱默认值 |
+| Guard/Approval/Sandbox | 三层安全，fail-closed | 静默放行不可回滚动作 | restart 默认 observe；自动重启默认 false；崩溃循环直接 disarm |
+| Preset/HMR | 修订保留；活 Agent 组合稳定 | 热替换失败拖垮进程 | 门禁不热改 profile；变更必须 restart 路径 |
+| KV Cache | 前缀稳定是硬约束 | 无关安全，但错误重试造成成本/时序异常 | 门禁报告只读，不改请求前缀 |
+| 打包/发布 | bundle 分发即代码执行 | 坏产物/错标签/重复发布污染 registry | `package` / `publish` gate；sha256/manifest/tag 校验 |
+
+## 3. 瓮城 18 个子插件的职责与主城关系
+
+| 子插件 | 关键风险 | 现有保护 | v3.3.0 增量 |
+|---|---|---|---|
+| orchestrator | 路由/派生/状态机 | 鉴权、fail-closed、配额 | 新 profile 建前过 gate |
+| forker | 子进程/端口/配置锁 | 端口池、退避、孤儿回收、只读修复 | `provision` 新建 profile 过 gate |
+| restart-guard | 交接执行权 = 进程退出/重启 | 三重门禁 + 审批 + supervisor 契约 | **崩溃循环 15m≥3 → safe-mode，人工清除前永不 handoff** |
+| restart-supervisor/watchdog | 外部拉起 | 授权清单 + 回执 + boot-guard | 增加 deploy gate（含备份/审计链/崩溃循环） |
+| approver | 快照/回滚会覆盖目录 | digest 校验、代际、TTL | 门禁写 profile 前自动 `.gate-backups` |
+| auditor | 审计链是最后证据 | 全链重算 + 篡改检测 | 部署/安装/发布前验链；门禁结论入链 |
+| scorer | 静态评分 | A–E 分档、C3 宽限、veto | **scoreGateFindings：0 warning=A，1–2=B，3+=C，blocker=E** |
+| healer | 修复建议不得放行 | 只读、UNKNOWN fail-closed | **gateRepairPlan：blocker→可执行修复建议** |
+| decision-center | 通知/审批/阻塞 | 红阻塞、黄蓝绿状态机 | 不作为主城放行依据；不绕过 restart/approval |
+| session-* / imports | 会话复制/恢复 | 有界读取、摘要大小限制 | profile gate 校验路径与磁盘 |
+| essence/mirror/compat | 元主/镜像升级 | 指纹、备份、兼容矩阵 | install/deploy gate 校验 profile |
+| hot-reloader | 热替换 | 只做可回收注册 | 主城变更不允许热替换 profile |
+| buffer/queue-journal | 持久化队列 | journal/outbox | 门禁不删除运行数据 |
+| adapter/approver 客户端 | 跨进程通信 | Bearer/HMAC | 门禁不联网 |
+
+## 4. 为什么必须 fail-closed
+
+1. **Cordis 的注册是副作用**：一个坏插件可以在 ACTIVE 后注册工具/服务，进程看似正常但能力错误。
+2. **Profile 是分层覆盖**：任何时候都可能出现「上一层覆盖导致另一层失效」，只看源码无法证明最终组合。
+3. **Session 是唯一真相源**：日志损坏后，resume/fork/transcript 全部失真，重装后仍可能复现。
+4. **重启是唯一把代码变成新事实的动作**：在崩溃循环/审计链断裂时重启，很可能只是把故障带入下一次启动。
+5. **DSH 明确是 Developer Preview**：沙箱/审批降低风险但不保证隔离；对不可信输入应使用一次性环境。
+
+## 5. 门禁的最小信任链
+
+```text
+源码（版本/文档/契约/防线）
+  → 产物（sha256/sidecar/manifest/必需文件）
+  → 发布（tag/版本/registry 幂等）
+  → 安装（profile 路径/无活宿主/磁盘）
+  → 部署（备份/审计链/崩溃循环/supervisor）
+  → 运行（restart-guard 三重门禁 + safe-mode）
+```
+
+任何一环缺少证据 = blocker；不允许「先跑起来再说」。

package/docs/FORK-SEED.md

@@ -0,0 +1,64 @@
+# FORK-SEED — 派生分身的默认第三方插件
+
+> v3.1.12 起：新机器 / 新用户的干净分身不再只有 `base + web-app + fang`，而是按
+> “安装不激活 / 安装并激活”两组清单带上默认第三方插件。
+
+## 默认清单（2026-11-11）
+
+安装不激活（只进 `dependencies` + `node_modules`，不加入 profile bundles）：
+
+```text
+@twinsearth/dsh-2xray
+@michengai/dsh-agency-agents
+dsh-better-sidebar
+dsh-context
+@liustack/modlens
+@liustack/modsearch
+```
+
+安装并激活（额外写入 `dsh.profile.bundles`，分身启动即加载）：
+
+```text
+dshmarket
+@twinsearth/dsh-im2a-plugin
+@openviking/dsh-memory-plugin
+@twinsearth/w2m-dsh-plugin
+```
+
+## 行为
+
+- 位置：`fang-forker` 插件 Config 的 `forkSeed`：
+  - `enabled`（默认 true）；
+  - `install[]`、`activate[]`（默认值即上面的清单）。
+- 时机：**每次 spawn**（首次派生与崩溃重启都会走）在启动 DSH 子进程前执行；
+  已按指纹缓存，首次安装后重启只重新打 profile patch，不重复安装。
+- 安装：独立 seed home（`<forksRoot>/.plugin-seed/seed-<fingerprint>`）里用 DSH 自带 pnpm
+  执行 `dsh plugin --profile seed add ...`；模块树以 hardlink 合并进分身的 `node_modules`，
+  不替换 mother 镜像里的运行时包。
+- 两种派生入口（开发者推荐 / 绿色“派生新分身”）都走同一个 `Forker.spawn`，因此清单一致。
+- 失败不阻塞分身启动：结果在 spawn 返回值 `forkSeed`（`ok/error/detail/cached`）与审计中可见。
+- 环境变量 `DSH_FANG_FORK_SEED=0` 可全局关闭（e2e/CI 使用，避免每次联网装包）。
+
+## 自定义
+
+在母亲 profile 的 Cordis 覆盖层里改 `fang-forker` 的 config，例如：
+
+```yaml
+- id: fang-forker
+  config:
+    forkSeed:
+      enabled: true
+      install:
+        - '@twinsearth/dsh-2xray'
+      activate:
+        - dshmarket
+```
+
+`install` 只装不激活；`activate` 会同时进依赖与 profile bundles。包名会做格式校验，
+非法名（路径、参数注入）会被忽略。
+
+## 边界
+
+- 首次派生需要联网从 npm 安装；离线时分会话仍可启动，只是 `forkSeed.ok=false`。
+- 仅作用于**任务分身**；元宝运行态（`essence-runtime`）继续继承元宝自己的模块树。
+- 已在运行的旧分身在下次重启时补装（配置回放后重新打 patch）。