前言¶

在 DeepSeek Harness（DSH）里做带界面的能力时，常见做法是把状态塞进工具返回值，或单独起一个前端工程。若你只是想对照「地图层、角色、社会、叙事、T1/T2/T3」等概念做示意，又不想把对话页拆成两套应用，就需要一种能挂在宿主 Web UI 上、又能由本机 webServer 提供静态页与轻量 API 的插件形态。

下面介绍社区插件 @snow-the/dsh-w8-sandbox（维护者 snow-The）。它在 DSH Web 客户端注入可拖拽浮动窗口，内嵌 iframe 加载本机路由 /w8/ 下的沙盒示意页，并在 SkillHub 目录中归类为 admin-security（路由侧带有 Host/Origin 与浏览器鉴权围栏）。仓库当前无 README.md，本文事实来自 package.json、源码与 docs/compatibility.md。

这是什么¶

npm 包名 @snow-the/dsh-w8-sandbox，版本 0.1.0，许可证 MIT。package.json 中的描述为：w8 world sandbox demo，通过浮动 iframe 展示沙盒示意图（map layers、characters、society、narrative、T1/T2/T3）。

服务端入口 index.js 在存在 webServer 服务时注册 HTTP 路由；客户端 client.js 在 conversation.session.header.actions 槽位增加「沙盒」按钮，打开小窗并加载 /w8/。Cordis 清单通过 cordis.patch.yml 将插件 id dsh-w8-sandbox 插入宿主组合。

核心功能¶

Web 客户端：浮动沙盒窗口¶

客户端模块在页面挂载后，会在对话会话标题栏操作区注册按钮（文案为「🌍 沙盒」）。点击后创建固定定位、可拖拽与缩放的小窗，iframe 指向 /w8/；窗口位置与尺寸写入浏览器 localStorage，键名为 dsh.w8.rect。

package.json 声明的客户端依赖注入为：

• @deepseek-ai/dsh-client-locale
• @deepseek-ai/dsh-client-ui-conversation

并设置 dsh.client.platform 为 web、immediately 为 true，以便随 Web 会话尽早加载。

服务端：示意页与状态 API¶

在子上下文中注入 webServer 后，插件注册以下路由（均先经过请求围栏，见下一节）：

/w8/state 通过读取本地 w8 知识库目录下 CSV 行数统计（非 SQLite）。知识库根路径在源码中为：

join(process.env.USERPROFILE || '.', 'source', 'repos', 'w8', 'kb')

分别读取 data/books.csv、data/assets.csv、data/resources.csv；文件缺失时对应字段为 -1，页面会按「未挂载」处理，与空表区分。

web/sandbox.html 为 H3 六边形地图概念示意，包含图层选择（L0 地形至 L5 叙事）、T1/T2/T3 层级标识，以及书库/资产/资源等展示位；页面会请求 /w8/state 刷新计数。

路由安全（与 admin-security 分类相关）¶

index.js 为上述路由实现 createRequestFence：通过 ctx.get('connection') 调用宿主的 requestRejection，对 Host/Origin 与浏览器登录态做校验；未通过则 401/403，无法取得 connection 服务时返回 503，避免在无围栏情况下暴露本机路由。插件以当前 dsh 进程权限 读取知识库路径并响应 HTTP，安装前应自行审阅源码与 MIT 许可证。

版本与兼容性¶

package.json 中声明：

• peerDependencies：@deepseek-ai/dsh >=0.2.0-rc.1
• engines.dsh：>=0.2.1-rc.2 <0.3.0-0
• dsh.compatibility.dshReleases：0.2.0-rc.1、0.2.0-rc.2、0.2.1-rc.2
• dsh.compatibility.verifiedAgainst：0.2.1-rc.2

docs/compatibility.md 说明：宿主加载期实际门禁主要看 peerDependencies；dsh.compatibility 字段供人与 CI 阅读，宿主不直接读取。该文档亦注明未对端到端功能、浏览器 UI 挂载等做完整验证。

安装与启用¶

仓库根目录未提供 README.md，已抓取资料与 GitHub 目录中也没有写明 dsh plugin … 一类官方安装命令，本文不编造安装语句。可按以下途径操作：

1. 在 DSH 社区目录 SkillHub 插件页 查看是否有与当前 DSH 版本匹配的安装说明（SkillHub 为独立社区站点，与 DeepSeek / 幻方无官方从属关系）。
2. 在所用 DSH 发行版的插件管理文档中，以包名 @snow-the/dsh-w8-sandbox 或 GitHub 仓库 snow-The/dsh-w8-sandbox 为准完成安装。
3. 确认宿主版本满足上述 engines / peerDependencies 后启用 profile，并确保组合中包含可提供 webServer 的 Web 应用插件（无 webServer 时服务端路由不会注册，客户端按钮仍可能出现但 iframe 无法加载页面）。

典型用法¶

在插件已加载、且 webServer 可用的前提下：

1. 启动 DSH Web 界面（具体命令以你的 profile 与发行版文档为准；docs/compatibility.md 示例提到可用 dsh web --port <端口> --no-open 做本地启动测试）。
2. 打开任意对话会话，在会话标题栏操作区点击 🌍 沙盒。
3. 在弹出窗口中查看六边形地图示意；若已在本机放置 w8 知识库 CSV，刷新或等待页面拉取 /w8/state 后，书库/资产/资源计数会更新。

可选：按服务端源码中的路径准备 kb/data/*.csv，以便 /w8/state 返回非 -1 的统计值。Linux 环境下若未设置 USERPROFILE，默认相对当前用户目录下的 source/repos/w8/kb，需自行对齐实际目录或改环境变量。

适用场景与注意¶

适合：需要在 DSH Web 对话上下文中快速打开 w8 世界沙盒演示页，对照地图层、社会/叙事与 T1–T3 分层概念；同时希望路由走宿主统一的浏览器鉴权围栏，而不是裸露的 loopback 读接口。

注意：

• 插件逻辑在本机 dsh 进程内执行，可读取配置的知识库路径并注册 HTTP 路由；安装前请检查 源码 与许可证。
• 无 webServer 的 profile 下仅客户端部分可能加载，沙盒页面不可用。
• 知识库路径写死在服务端常量中，跨平台部署时要核对 USERPROFILE 与目录布局。
• GitHub 星标数为 0（截至资料抓取时），属早期演示插件，生产环境使用前请自行验证。

结尾¶

@snow-the/dsh-w8-sandbox 把 w8 世界沙盒示意嵌进 DSH Web：标题栏一键打开可拖拽小窗，本机 /w8/ 提供地图示意与 /w8/state 轻量统计，并对路由施加与宿主一致的连接围栏。目录与说明见 SkillHub，源码见 GitHub。