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

package/docs/MAIN-CITY-GATE.md

@@ -0,0 +1,58 @@
+# 主城门禁（main-city gate）
+
+> 目标：任何会影响 DSH 端安全的动作——打包、发布、安装、部署、新建 profile——都必须先通过同一套可复核检查。门禁拿不到证据时 **fail-closed**，不允许「先上再补」。
+
+## 1. 七个入口
+
+| target | 何时 | 关键检查 |
+|---|---|---|
+| `source` | 提交/CI/发布前 | 版本、CHANGELOG/AUDIT、vendored contract 逐字节、关键防线文件、restart 默认 observe/不自动重启、build/publish 已接线 |
+| `package` | 打包完成后 | staged package 名称/版本/private/client/bundle；tarball sha256、sidecar、manifest、禁用产物条目、必需文件 |
+| `publish` | npm 发布前 | package 检查 + tag 与版本一致 + registry 同版本重复发布阻断（可显式 `--allow-existing`） |
+| `install` | 干净 profile 安装 | package + profile 路径/捆绑去重/patch 可解析 + 无活跃宿主 + 崩溃循环/safe-mode + 审计链 + 磁盘 |
+| `deploy` | 重启/部署前 | install 检查 + 备份（可 `--repair` 自动建）+ supervisor 证据 |
+| `workflows` | CI/发布工作流变更 | 必需 ci/release、禁止 pull_request_target/write-all/secrets inherit、禁止 PR 字段直接插值 run、必须接 source gate 与 build.mjs |
+| `profile` | 新建/覆盖 profile | 名称白名单、禁止 `desktop`/`plugin`、路径必须在 `$DSH_HOME/profiles`、磁盘、已存在须 `--force` + 自动备份 |
+
+## 2. 输出与退出码
+
+- JSON 报告写入 `dist/main-city-gate.json`；
+- `ok=false` 当且仅当存在 `blocker`；`warning` 不阻断但会进入评分；
+- 评分由 `scorer.scoreGateFindings` 折算 A–E：0 warning=A，1–2=B，3+=C，任何 blocker=E；
+- 退出码 0=GREEN，1=RED，2=用法错误。
+
+## 3. 与五个子插件的关系
+
+| 子插件 | 在主城门的职责 |
+|---|---|
+| restart-guard | 崩溃循环（15 分钟内 ≥3 次）自动进入安全模式并**永久放弃交接执行权**，直到人工 `clearSafeMode`；门禁把 safe-mode/崩溃循环当 blocker |
+| scorer | `scoreGateFindings` 把 findings 折成准入分；A/B 才放行 |
+| approver | 需要写 profile 时由门禁生成 `.gate-backups/<stamp>/`（审批式快照，不覆盖） |
+| auditor | 部署/安装/发布时校验 `audit.jsonl` 链；门禁结论写链（`main-city-gate`），链坏拒绝追加 |
+| healer | 输出修复建议；修复不确定时保持 fail-closed（`blockingOnUnknown`） |
+| 门禁/CI | build/publish/install/deploy 全部调用同一 CLI；CI hygiene/release guard 先跑 source gate |
+
+## 4. 常用命令
+
+```bash
+node tools/gate/main-city.mjs --target source
+node tools/gate/main-city.mjs --target package --package-dir dist/npm/package --tarball dist/dsh-fang-X.tgz
+node tools/gate/main-city.mjs --target publish --tag vX --check-registry
+node tools/gate/main-city.mjs --target install --home <DSH_HOME> --profile fang-x
+node tools/gate/main-city.mjs --target deploy  --home <DSH_HOME> --profile fang-x --repair
+node tools/gate/main-city.mjs --target profile --home <DSH_HOME> --profile demo --create
+```
+
+## 5. 人工解除崩溃循环安全模式
+
+1. 先读 `<dataDir>/restart/safe-mode.json` 与 `runtime-crash.jsonl`，确认崩溃原因；
+2. 在运行中的宿主里调用 `ctx.get('fangRestart').clearSafeMode({ by, note })`（或对应面板）；
+3. `clearSafeMode` 会把 crash ledger 改名为 `.cleared-<stamp>`，并写链式审计，下一次启动不会按旧证据重新触发；
+4. 重新跑 deploy gate；`runtime: no active crash loop` 与 `runtime: restart safe-mode clear` 必须为 PASS。
+
+## 6. 明确不做
+
+- 不自动「修复」产物 hash/sidecar（会掩盖损坏），只报修复建议；
+- 不自动清审计链或崩溃记录；
+- 不在门禁里调用网络（`--check-registry` 例外，且只读 registry 的 latest）；
+- 不改 DSH 核心文件；写 profile 仅限 `--repair` 备份和 `profile --create`。

package/docs/OVERLAY-MASTER-SWITCH.md

@@ -0,0 +1,35 @@
+# 宿主浮窗总开关（v3.3.2）
+
+## 目标
+
+母体（宿主）页面里，瓮城的决策浮标、红色告警、收件箱抽屉、Mother 浮窗、通知/弹层都是浮层。
+需要一键隐藏/显示，而不是逐个关闭；隐藏后还要能随时恢复。
+
+## 入口
+
+| 位置 | 形态 | 说明 |
+|---|---|---|
+| 宿主侧栏底部 | `浮窗` / `浮窗已隐藏` 按钮 | 常驻；其他浮窗全隐藏时仍然可见，作为恢复入口 |
+| 瓮城控制台面板头 | `隐藏浮窗` / `显示浮窗` 按钮 | 在控制台内直接切换 |
+| 偏好 | `localStorage['fang.overlays.hidden']` | `1` 隐藏 / `0` 显示；刷新、重启后保持 |
+| 跨窗口 | `storage` 事件 | 一个窗口切换，其他窗口同步 |
+
+## 行为
+
+1. 切换 `document.documentElement[data-fang-overlays]` 为 `hidden|visible`；
+2. CSS 统一隐藏以下瓮城浮层（`display:none!important`）：
+   - `.fang-relay-fab` / `.fang-relay-panel`（会话决策中继）
+   - `.fang-red-alert-stack` / `[data-fang-red-alerts]`（红色告警）
+   - `.fang-inbox-drawer` / `.fang-inbox-backdrop`（收件箱抽屉）
+   - `.mother-palette`（Mother 浮窗）
+   - `[data-fang-essence-notice]`（元主落地提示）
+   - `.fang-console .overlay`（确认/截图等弹层）
+   - `.fang-console .toast`（面板 toast）
+3. **不销毁 DOM、不关闭状态**：隐藏只是视觉开关；再显示时原样恢复（例如收件箱仍停在原分组/滚动位置）。
+4. 不隐藏宿主自己的 UI 与瓮城面板本身；开关按钮自身也不在隐藏列表里。
+
+## 明确不做
+
+- 不修改宿主的浮窗系统，不注入全局 CSS 变量；
+- 不把「隐藏」当成分身/元主 UI 锁（那是角色收敛，不是浮窗偏好）；
+- 不在隐藏时丢弃红色告警：告警仍在 DOM 中，恢复后可见；若需要真正处理，必须点开关显示后再处置。

package/docs/PACKAGE-RENAME-v3.3.3.md

@@ -0,0 +1,40 @@
+# npm 包改名：@twinsearth/fang-dsh-plugin
+
+生效版本：`v3.3.4`（v3.3.3 因 npm 402 未发布）
+
+## 新身份
+
+| 项 | 值 |
+|---|---|
+| npm 包名 | `@twinsearth/fang-dsh-plugin` |
+| 安装 | `dsh plugin --profile desktop add @twinsearth/fang-dsh-plugin@3.3.3` |
+| 本地开发 bundle 名 | `@twinsearth/fang-dsh-plugin`（构建时统一改写为新包名） |
+| 旧 npm 包名 | `@twinsearth/dsh-fang`（继续兼容，不再作为新发布身份） |
+
+## 为什么保留旧名兼容
+
+- 已安装旧包的 profile 仍能启动、升级；`FANG_PACKAGE_NAMES` / `FORK_BUNDLE_NAMES` 同时接受新旧名和本地 link。
+- 新 profile、安装 drill、发布门禁、npm registry 查询全部使用新名。
+- 旧包暂不自动 deprecate；如需公告迁移，单独执行 `npm deprecate` 并记录。
+
+## 市场状态（2026-11-14）
+
+当前 DSH `0.2.2-rc.1` 没有「官方插件市场」，文档明确「DSH 不内置任何索引源」。
+因此本版**只发布 npm，不提交任何市场收录**；官方市场上线后再按官方流程提交。
+社区 Open Plugin Market（dshopen.org）是第三方索引，本版未提交。
+
+## 验证
+
+```text
+source / workflows / package / publish gate GREEN
+全量测试见构建输出
+install drill 使用新包名安装并列出新 client.js
+```
+
+
+## 队列子插件默认关闭（同一版本）
+
+- `dsh-fang-queue-journal` 的 bundle 行默认 `disabled: true`；
+- 未启用时 host half 不提供 `fangQueueJournal`，journal/queue 路由返回 503；
+- client half 不加载；即使旧缓存残留，也会因能力探测失败而隐藏 UI；
+- 启用方式：在 profile 的 `cordis.patch.yml` 覆盖该行 `disabled: false`（或由后续设置界面提供开关）。

package/docs/PM-DECISION-POLICY.md

@@ -0,0 +1,61 @@
+# PM 主动开票策略（v3.1.25）
+
+> 目的：让「大模型主动开票」真正生效。决策中心链路一直是通的，但 PM 从不调用
+> `ask_user_choice` / `request_human_decision`，于是「开发一整天也看不到一张票」。
+>
+> 策略落在两处（因为模型只能看到第二处）：
+> 1. 本文件（人读）；
+> 2. **工具 description**（模型读）——由 `src/plugins/decision-center.mjs` 的
+>    `PM_DECISION_POLICY` / `PM_PROACTIVE_HINT` 注入，改策略就改那里。
+
+## 一、必须开票（mustAsk）
+
+| # | 情形 |
+|---|---|
+| 1 | 要在两个及以上合理方案里做取舍（架构 / 技术选型 / 交互形态），且代价不可忽略 |
+| 2 | 要执行不可逆或难以回滚的动作：删除数据、重置分支、强制推送、覆盖生产配置、发版 |
+| 3 | 要触碰凭据、权限、外部账号、付费资源或对外承诺 |
+| 4 | 需求存在歧义或缺失关键信息，不同理解会导致返工 |
+| 5 | 要越过既定范围（改用户没要求的模块、扩大 mandate、跨仓库操作） |
+| 6 | 发现阻塞缺陷但修复方案会改变对外行为 / 契约 |
+| 7 | 长时间任务（>10 分钟）需要中途改变方向 |
+
+## 二、不要开票（mustNotAsk）
+
+- 低风险、可回滚、在既定范围内的实现细节（命名、注释、内部结构、测试补全）；
+- 等价于「继续」的常规推进，以及取文件 / 跑测试 / 格式化这类机械操作；
+- 已经有明确约定的既定方案（此前已确认过）。
+
+> 判据：开票的成本是「打断一个人的注意力」，只有**决策代价 > 打断代价**时才开票。
+
+## 三、提问规则（rules）
+
+1. 一次只问一个决定点，问题要具体到「选哪个」或「能不能做」；
+2. 必须给 2–4 个可执行选项，推荐项放第一个并把标签后缀 `(推荐)`；
+3. `context` 写清：为什么需要人决定、每个选项的代价与风险、不决定的后果；
+4. `red` 用于**阻塞**（人不在就没法继续）；`yellow` / `blue` 用于「记录并继续」，不要滥用 red；
+5. **绝对不要因为「不确定」而把问题原样抛回给开发者** —— 先把能自己查的查清。
+
+## 四、AI 自动决策的边界（autoDecide）
+
+| 项 | 默认 | 说明 |
+|---|---|---|
+| `autoDecide.enabled` | `true` | 关闭后所有票都必须人工回答 |
+| `autoDecide.levels` | `["green"]` | 只对低注意力票自动决策 |
+| `autoDecide.minConfidence` | `0.8` | 建议置信度下限 |
+| `autoDecide.allowUnknownRisk` | `false` | 推荐项风险未知时是否允许自动 |
+
+**硬红线**：`red` 与任何 `isBlocking` 的票**永不自动决策**，必须人工显式选择。
+自动决策会写 `resolvedBy: "ai-auto"` 并记审计 `decision-ai-auto-resolved`。
+
+## 五、如何验证策略生效
+
+```bash
+# 1) 工具描述里应能看到策略（模型读得到）
+node -e "import('./src/plugins/decision-center.mjs').then(m=>console.log(m.PM_DECISION_POLICY.mustAsk.length))"
+
+# 2) 运行态：让 PM 遇到一个必然需要人决定的问题，观察是否出现新票
+curl -H "x-fang-auth: <token>" http://127.0.0.1:<port>/fang/api/decisions
+
+# 3) 收件箱：0 条时应看到常驻入口（半透明 + 计数 0）
+```

package/docs/WORKFLOW-UI.md

@@ -0,0 +1,86 @@
+# WORKFLOW-UI — 瓮城 UI 改动与发版固定流程
+
+> 状态：生效中（2026-11-10 起）。本文件是**后续会话的持久约束**；与 `docs/CRASH-SAFETY.md`
+> 一起进包、进测试、进发布门禁。违反本流程 = 发布门禁不通过，不是“建议”。
+
+## 0. 铁律
+
+1. **发布必须由人类显式授权。** 禁止自动执行 `release workflow`、`npm publish`、GitHub Release、
+   打 tag、移动 tag。完成修改与测试后先汇报，等确认再发。
+2. **不是所有修改都值得发版。** 文档/流程/无行为变化的重构可以只合并不发版；
+   版本号是否递增由人类确认。
+3. **发版后不再动 tag/文档。** 发布后文档状态固化为“以 registry / Release 为准”，
+   避免 v3.1.8 的“移动 tag → 重建 tarball → npm 与 Release 摘要不一致”返工。
+
+## 1. 先判定：纯样式 vs 结构/高度链
+
+| 判定 | 处理 | 目标 |
+|---|---|---|
+| 纯样式（颜色、间距、圆角、滚动条外观） | 只改 CSS + 1 个 DOM 契约测试 | ≤10 分钟 |
+| 结构/高度链（宿主容器 flex、`min-height`、滚动容器归属、overlay 层级） | 先画高度链与 DOM 归属，再改；必须加 DOM/CSS 契约测试 | 按预算 |
+| 交互/数据（滚动、拖拽、焦点、异步状态） | 加可自动化的行为测试；必要时做一次浏览器冒烟 | 按预算 |
+
+**检查点（改之前先回答）**：目标元素在哪个宿主容器里？宿主对它有 `height` 吗？
+滚动容器是不是“唯一的”？有没有内容在滚动容器之外（本次 v3.1.9 的根因就是元主卡片在滚动区外）？
+
+## 2. 浏览器冒烟：只在必要时，复用现成 harness
+
+- 只有涉及**宿主布局 / 滚动 / 拖拽 / 层叠**时才做真实浏览器冒烟；
+- 复用仓库已有工具/脚本，**不新建一次性 harness**；单次冒烟为上限，不反复迭代调试；
+- 冒烟必须记录：视口尺寸、输入方式（CDP 真实 wheel/drag 要写清楚）、前后指标、截图路径。
+
+## 3. 合并前一次性验证（最多 2 轮）
+
+```bash
+node --test test/<相关>.test.mjs      # 单测 / DOM 契约
+node --test test/                     # 本地全量（含 jsdom 套件）
+node tools/release/preflight.mjs      # 版本/许可/allowlist/client 解析/crash-safety/全量
+```
+
+- 全量 1 次绿灯即可；同一轮失败 → 修一次 → 复跑；**第 2 轮仍红就停下汇报**。
+- PR body 必须附：改动范围、根因、验证命令与结果、已知边界。
+
+## 4. 发版前置检查（硬门禁，缺一不发）
+
+发版前逐条确认，任何一项不满足先修环境、**不先打 tag**：
+
+1. `git ls-remote https://github.com/<repo> HEAD` 可达（runner 与本机都能访问 github.com）；
+2. self-hosted runner 在线且 idle；
+3. npm token 有效（`NPM_TOKEN` / 本地 secret 文件，可 `whoami` 或 dry-run 校验）；
+4. 目标版本号**未打 tag**、CHANGELOG 有对应 `## vX.Y.Z` 段、`FANG_VERSION` 与 `package.json` 一致；
+5. `node tools/release/preflight.mjs --e2e` 本地 GREEN，且构建产物通过
+   `crash-safety --package`（打包后二次验证）。
+
+发布顺序（只有人类授权后才执行）：
+`PR 合并 → 新 main 打注解 tag → release workflow → 校验 tests/build/Release/npm/healthz/final verify → 告知升级与重启方式`。
+
+## 5. 运行中的 profile 升级安全规程（2026-11-10 事故后新增）
+
+**禁止对正在运行的 DSH host 直接执行 `dsh plugin add` / 插件管理器改 profile。**
+2026-11-10 21:33 在运行中的 desktop profile 上执行升级，导致 DSH 崩溃、用户层被重置
+（bundles 变回默认、`cordis.patch.yml` 被模板覆盖）；已从 `.bak-*` 备份恢复。
+
+正确步骤：
+
+1. **停止 host**（或走宿主自带的“重启/退出”路径），确认没有进程占用 profile；
+2. 备份 `package.json`、`cordis.patch.yml`、`pnpm-workspace.yaml`、`pnpm-lock.yaml`
+   到 `profiles/<name>/.repair-<ts>/`（或 `.bak-*`）；
+3. 对**候选包**先冒烟，不先替换：`node tools/boot-guard.mjs --candidate-dir <下载解包目录> --json`；
+4. 安装/升级（优先 GUI 插件管理器，其次离线安装）；
+5. 装完对 profile 做 dry-run：`node tools/boot-guard.mjs --profile-dir <profile> --json`；
+6. 启动 host；若启动失败，用 `--apply` 禁用失败行或恢复备份后重启；
+7. 记录：升级前版本、候选包冒烟结果、装后 dry-run 结果、回滚路径。
+
+## 6. Token / 时间预算
+
+- 单 UI 改动：目标 **≤15 分钟**、验证 **≤2 轮**；
+- 超出预算立即停下汇报：**卡在哪、已试什么、是否继续深挖**，由人类决定；
+- 不做与需求无关的“顺手重构”；不新造工具（先找仓库已有工具）。
+
+## 7. 完成定义（Definition of Done）
+
+- [ ] 根因写清楚（不是“加了 overflow”）；
+- [ ] 测试覆盖该根因（DOM/CSS 契约或行为断言）；
+- [ ] 本地全量绿灯 / preflight GREEN；
+- [ ] 已记录边界与回滚路径；
+- [ ] 发布前得到人类显式授权（否则停在“待发布”状态）。

package/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="dsh-Fang">
+  <rect x="4" y="4" width="56" height="56" rx="12" fill="#0f172a"/>
+  <rect x="12" y="12" width="16" height="16" rx="3" fill="#38bdf8"/>
+  <rect x="36" y="12" width="16" height="16" rx="3" fill="#1e40af" opacity="0.9"/>
+  <rect x="12" y="36" width="16" height="16" rx="3" fill="#1e40af" opacity="0.7"/>
+  <rect x="36" y="36" width="16" height="16" rx="3" fill="#64748b" opacity="0.8"/>
+  <path d="M28 20h8M20 28v8M44 28v8M28 44h8" stroke="#94a3b8" stroke-width="2" stroke-linecap="round"/>
+</svg>

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Fangcheng: DSH's First Virtual Machine!",
+    "description": "Dsh-Fangcheng was born from a group of geeks who love tinkering — and have been burned by it more times than we can count. In the era of self-evolving AI, we believe that \"how to safely try something new\" matters more than \"the new thing itself\".\n\nIf you are one of these three, Fangcheng was built for you:\n1. The plugin-building maniac: writing N new plugins a day and changing code hundreds of times. You used to restart DSH after every edit; now you hot-reload inside Fangcheng, and a broken build rolls back instantly.\n2. The multi-tasker: one window for data analysis, one for a crawler, one for long-running tests. Fangcheng lets you open as many as you like without crashing — each in its own absolute isolation.\n3. The security worrier: unwilling to hand your client to third-party plugins, afraid of deleted files or stolen API keys. Fangcheng's review gates and independent sandboxes keep risky code boxed in."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "瓮城：DSH的第一台虚拟机！",
+    "description": "Dsh-瓮城，诞生于一群热爱折腾、也被折腾过无数次的极客之手。我们深知在“自进化 AI”时代，“如何安全地尝试新事物”比“新事物本身”更重要！\n\n如果你是以下三类人，瓮城就是为你量身定制的：\n1. 插件开发狂魔：每天要写 N 个新插件、改几百次代码。以前改一次重启一次 DSH；现在在瓮城里随便热更新，坏了直接秒回滚。\n2. 多任务并发狂：一个窗口跑数据分析，一个窗口写爬虫，一个窗口做长周期测试。瓮城让你像开浏览器一样“多开不崩”，并各跑各的绝对隔离。\n3. 安全焦虑症患者：不敢把客户端交给第三方插件，怕乱删文件、怕被盗取 API Key。瓮城的审核系统和独立沙箱，把危险代码安排得明明白白。"
+  }
+}

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@twinsearth/fang-dsh-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.3.5",
+  "private": false,
+  "type": "module",
+  "description": "dsh-Fang (瓮城) — mother/fork plugin development environment for DeepSeek Harness: one readonly mother, a disposable child dsh-Web per task.",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./compose": "./src/compose.mjs",
+    "./orchestrator": "./src/plugins/orchestrator.mjs",
+    "./forker": "./src/plugins/forker.mjs",
+    "./scorer": "./src/plugins/scorer.mjs",
+    "./umbrella": "./src/plugins/umbrella.mjs",
+    "./healer": "./src/plugins/healer.mjs",
+    "./approver": "./src/plugins/approver.mjs",
+    "./hot-reloader": "./src/plugins/hot-reloader.mjs",
+    "./restart-guard": "./src/plugins/restart-guard.mjs",
+    "./buffer-keeper": "./src/plugins/buffer-keeper.mjs",
+    "./auditor": "./src/plugins/auditor.mjs",
+    "./router": "./src/plugins/router.mjs",
+    "./adapter": "./src/plugins/adapter.mjs",
+    "./session-catalog": "./src/plugins/session-catalog.mjs",
+    "./client": {
+      "browser": "./client.js",
+      "default": "./client.js"
+    },
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./session-bridge": "./src/plugins/session-bridge.mjs",
+    "./session-sync": "./src/plugins/session-sync.mjs",
+    "./session-router": "./src/plugins/session-router.mjs",
+    "./decision-center": "./src/plugins/decision-center.mjs",
+    "./contract": "./src/contract/index.js"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": []
+    }
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=1 \"test/*.test.mjs\""
+  },
+  "license": "AGPL-3.0-or-later",
+  "engines": {
+    "node": ">=22"
+  },
+  "optionalDependencies": {
+    "@twinsearth/dsh-fang-queue-journal": "^0.1.7",
+    "@twinsearth/dsh-fang-web-entry": "0.1.1"
+  },
+  "devDependencies": {
+    "jsdom": "^31.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TwinsEarth/dsh-fang.git"
+  },
+  "homepage": "https://github.com/TwinsEarth/dsh-fang#readme",
+  "bugs": {
+    "url": "https://github.com/TwinsEarth/dsh-fang/issues"
+  },
+  "bin": {
+    "fangctl": "./tools/fangctl.mjs"
+  }
+}

package/sdk/README.md

@@ -0,0 +1,65 @@
+# dsh-Fang 生态层（MIT）
+
+这个目录是 dsh-Fang 的**生态层**，使用 [MIT 许可](../LICENSE-SDK)：
+插件 SDK、模板、示例都可以零摩擦复制、修改、二次分发，甚至闭源集成进你的产品。
+
+> 核心层（编排器/派生器/红线守卫/Adapter/容器执行器等）在 `src/` 下，使用 **AGPL-3.0**（见
+> `../LICENSE-CORE`）；商业层（Relay/企业功能）在 `../relay-server`、`../enterprise`，闭源。
+> 逐目录许可地图见 [`../NOTICE`](../NOTICE)。
+
+---
+
+## 1. 一个 dsh-Fang 插件长什么样
+
+Fang 插件就是一个 DSH bundle：一个 npm 包目录，带
+
+```
+my-plugin/
+├── package.json          # name + dsh.bundle.patch（+ 可选 dsh.client 声明浏览器半）
+├── cordis.patch.yml      # 安装时把本插件的 loader 行 insert 进 profile
+├── index.js              # Host 半：export const name/inject/Config/apply
+└── client.js             # 可选 Client 半：window.__ModuleLoader__.load({...})
+```
+
+安装（不需要发布到 npm）：
+
+```powershell
+# 在 DSH 会话里对 Agent 说：
+#   plugin_manager install_bundle(target="E:\path\to\my-plugin")
+# 或者由你的发布脚本调用 DSH 的 plugin_manager
+```
+
+## 2. 模板
+
+- [`templates/plugin/`](templates/plugin/) — 最小可安装插件（Host + 可选 Client + 图标 + locale）
+- [`examples/status-badge/`](examples/status-badge/) — 读取瓮城 `/fang/api/status` 并在输入框下方显示徽标
+  （演示"第三方插件如何安全调用 Fang 的公开 HTTP 面"）
+
+复制模板：
+
+```powershell
+Copy-Item -Recurse sdk\templates\plugin my-plugin
+# 改 package.json 里的 name / 行 id / patch 里的 id
+```
+
+## 3. 与瓮城核心交互的三种合法方式
+
+| 方式 | 适用 | 协议边界 |
+|---|---|---|
+| 读 `/fang/api/status`、`/fang/api/tasks`、`/fang/api/sessions` | 面板/徽标/旁路观察 | 只读 HTTP，最安全 |
+| `POST /fang/api/derive`、`/tasks/*`、`/promote` | 自动化工作流 | 写入前请遵守核心的配额与审批语义 |
+| Adapter 协议（仅分身内，`/fang/adapter/*`） | 分身内插件 | 需要分身 token；不要在母体调用 |
+
+> 插件与核心之间通过**公开 HTTP API** 交互时，你的插件是独立作品，可以自选许可证
+> （MIT/Apache/闭源均可）——这正是生态层 MIT 的意义。
+
+## 4. 需要遵守的少量规则
+
+- 不要从其他插件的 DOM / 样式表里"猜"布局；用 slots 与主题 token（`--dsw-alias-*`）。
+- Client 半不要 `require` 其他 DSH Client 包；React 来自浏览器模块表。
+- 定时器/监听器用 `ctx.effect` 注册清理。
+- 不要写 `$DSH_HOME/profiles/**`；通过 bundle/plugin_manager 安装。
+
+## 5. 贡献
+
+生态层（`sdk/`、`tools/fangctl.mjs`）的贡献同样需要签署 [CLA](../CLA.md)（为了让项目能双许可）。

package/sdk/examples/status-badge/README.md

@@ -0,0 +1,16 @@
+# status-badge（MIT 示例插件）
+
+演示第三方插件如何**只通过公开 HTTP 面**与瓮城交互：
+
+- `index.js`：Host 半，提供一个只读服务（证明插件已加载）；
+- `client.js`：Client 半，每 10s 拉一次 `GET /fang/api/status`，在输入框下方显示「瓮城 N/M」。
+- 不 import 任何瓮城内部模块 → 它是独立作品，可自由选许可证（本示例为 MIT）。
+
+安装：
+
+```powershell
+# DSH 会话里：
+#   plugin_manager install_bundle(target="<repo>\\sdk\\examples\\status-badge")
+```
+
+失败态：拉不到 `/fang/api/status` 时显示「瓮城离线」，不假装有数据。

package/sdk/examples/status-badge/client.js

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: MIT
+// Example client half: read dsh-Fang's public read-only HTTP surface and show it in the dock.
+// This demonstrates the recommended third-party integration: HTTP only, no host internals.
+window.__ModuleLoader__.load({
+  id: '@fang-example/status-badge',
+  factory(require) {
+    const React = require('react')
+    const h = React.createElement
+
+    function StatusBadge() {
+      const [view, setView] = React.useState({ state: 'loading', text: '瓮城 …' })
+      React.useEffect(() => {
+        let alive = true
+        const poll = async () => {
+          try {
+            const res = await fetch('/fang/api/status', { headers: { accept: 'application/json' } })
+            if (!res.ok) throw new Error('status ' + res.status)
+            const body = await res.json()
+            if (!alive) return
+            const ready = body?.tasks?.ready ?? 0
+            const max = body?.tasks?.max ?? '?'
+            setView({ state: 'ok', text: `瓮城 ${ready}/${max}`, version: body?.version })
+          } catch {
+            if (alive) setView({ state: 'off', text: '瓮城离线' })
+          }
+        }
+        poll()
+        const timer = setInterval(poll, 10000)
+        return () => { alive = false; clearInterval(timer) }
+      }, [])
+
+      const color = view.state === 'ok'
+        ? 'var(--dsw-alias-state-success, #22c55e)'
+        : view.state === 'off'
+          ? 'var(--dsw-alias-state-warning, #9ca3af)'
+          : 'var(--dsw-alias-state-business-primary, #2563eb)'
+      return h('div', {
+        title: view.version ? `dsh-Fang ${view.version}` : 'dsh-Fang 状态（第三方插件示例）',
+        style: {
+          display: 'inline-flex', alignItems: 'center', gap: 6, padding: '2px 8px', borderRadius: 999,
+          fontSize: 11, color: 'var(--dsw-alias-label-secondary, #888)',
+          border: '1px solid var(--dsw-alias-border, rgba(127,127,127,.3))',
+        },
+      },
+      h('span', { 'aria-hidden': true, style: { width: 6, height: 6, borderRadius: '50%', background: color } }),
+      h('span', null, view.text))
+    }
+
+    return {
+      inject: ['slots'],
+      apply(ctx) {
+        return ctx.slots.inject('conversation.composer.dock', () => ctx.slots.register({
+          name: 'conversation.composer.dock',
+          id: 'fang-example-status-badge',
+          order: 70,
+        }, (props) => h(StatusBadge, { ...props, ctx })))
+      },
+    }
+  },
+})

package/sdk/examples/status-badge/cordis.patch.yml

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MIT
+# Example plugin row: host half marks the plugin present; the client half talks to /fang/api/status.
+- insert:
+    - id: fang-example-status-badge
+      name: '@fang-example/status-badge'
+      config:
+        intervalMs: 10000

package/sdk/examples/status-badge/index.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+// Example host half: exposes a tiny service so the plugin is observable, and nothing else.
+export const name = 'fang-example-status-badge'
+export const inject = []
+
+export function apply(ctx, config) {
+  const cfg = { intervalMs: 10000, ...(config ?? {}) }
+  ctx.effect(() => ctx.provide('fangExampleStatusBadge', {
+    intervalMs: () => cfg.intervalMs,
+    at: new Date().toISOString(),
+  }))
+}

package/sdk/examples/status-badge/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@fang-example/status-badge",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Example MIT plugin: shows dsh-Fang status next to the composer (third-party plugin calling Fang's public HTTP surface).",
+  "exports": {
+    ".": "./index.js",
+    "./client": {
+      "browser": "./client.js",
+      "default": "./client.js"
+    }
+  },
+  "files": ["index.js", "client.js", "cordis.patch.yml"],
+  "license": "MIT",
+  "dsh": {
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": ["@deepseek-ai/dsh-client-connection"]
+    }
+  }
+}

package/sdk/templates/plugin/README.md

@@ -0,0 +1,36 @@
+# 插件模板（MIT）
+
+最小可安装的 DSH / dsh-Fang 插件，包含 Host 半（`index.js`）与可选的 Client 半（`client.js`）。
+
+## 用法
+
+```powershell
+Copy-Item -Recurse sdk\templates\plugin E:\my\my-plugin
+cd E:\my\my-plugin
+# 1) 改 package.json：name、dsh.client（不需要 UI 就删掉 dsh.client 与 client.js）
+# 2) 改 cordis.patch.yml：id 与 name 保持一致
+# 3) 在 DSH 会话里安装：
+#    plugin_manager install_bundle(target="E:\\my\\my-plugin")
+```
+
+## 结构
+
+| 文件 | 作用 |
+|---|---|
+| `package.json` | `dsh.bundle.patch` 让它成为可安装 bundle；`dsh.client` 声明浏览器半 |
+| `cordis.patch.yml` | 安装时把 `my-plugin` 这一行 insert 进 profile 的 loader 树 |
+| `index.js` | Host 半：`export const name / inject / apply`；用 `ctx.effect(ctx.provide(...))` 提供能力 |
+| `client.js` | Client 半：向 `conversation.composer.dock` 注册一个徽标（可删） |
+| `locale/en.json` | 界面上显示给用户的标题与描述（国际化） |
+| `icon.svg` | 插件图标；不要用上游/他人的图标 |
+
+## 可配置
+
+模板刻意**不带** `Config`，避免模板依赖 schema 库。需要配置时，把 schemastery（MIT）复制到
+`vendor/` 再 `export const Config = z.object({...})`——核心层的做法可直接参考。
+
+## 与瓮城交互
+
+第三方插件调用瓮城只看公开 HTTP 面：`/fang/api/status`、`/fang/api/tasks`、`/fang/api/sessions`、
+`POST /fang/api/derive` 等（见 [`../../README.md`](../../README.md)）。用 HTTP 交互时你的插件是独立作品，
+可以选择自己的许可证。

package/sdk/templates/plugin/client.js

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: MIT
+// dsh-Fang / DSH plugin template — optional Client half.
+//
+// Contract: window.__ModuleLoader__.load({ id: <package name>, factory(require) {...} })
+// React comes from the browser module table; do not require other DSH client packages.
+window.__ModuleLoader__.load({
+  id: '@your-scope/dsh-plugin-template',
+  factory(require) {
+    const React = require('react')
+    const h = React.createElement
+
+    function Badge() {
+      return h('div', {
+        title: 'my-plugin: 输入框下方的一个示例徽标',
+        style: {
+          display: 'inline-flex', alignItems: 'center', gap: 6,
+          padding: '2px 8px', borderRadius: 999, fontSize: 11,
+          color: 'var(--dsw-alias-label-secondary, #888)',
+          border: '1px solid var(--dsw-alias-border, rgba(127,127,127,.3))',
+        },
+      }, 'my-plugin')
+    }
+
+    return {
+      inject: ['slots'],
+      apply(ctx) {
+        return ctx.slots.inject('conversation.composer.dock', () => ctx.slots.register({
+          name: 'conversation.composer.dock',
+          id: 'my-plugin-badge',
+          order: 60,
+        }, (props) => h(Badge, { ...props, ctx })))
+      },
+    }
+  },
+})