前言¶
DeepSeek Harness（DSH）的动态插件运行在沙箱环境中，通常被限制直接发起网络请求或使用 Node.js 的 require。html.run 需要通过特定的接口发布 HTML 文件，无法直接通过标准的 ctx.web.fetch 调用。
dsh-htmlrun 插件通过 ctx.subprocess 调用零依赖的本地 CLI（htmlrun.cjs）来绕过沙箱限制。它将 html.run 的发布能力封装为 DSH 模型可调用的工具，让模型能够在会话内直接将本地 HTML 文件转换为可分享的链接。
插件定位¶
- 名称：dsh-htmlrun
- 作者：iwker
- 类型：DSH 模型工具插件（联网工具类）
- 许可证：MIT
- 核心价值：将 html.run 的 CLI 发布流程封装为模型工具，无需人工复制链接。
核心功能¶
该插件提供以下能力：
- CLI 封装：调用项目自带的
scripts/htmlrun.cjs执行具体操作，包括激活、发布、更新、检查状态等。 - 模型工具集成：在 DSH 会话中注册名为
htmlrun的工具，模型可直接调用。 - 认证管理：无需为 DSH 插件单独配置 Key。html.run 的认证 Token 存储在
~/.htmlrun/config中，与终端使用 CLI 保持一致。 - 支持的命令：
check：检查登录状态，未激活时返回激活链接与二维码。publish：发布或更新 HTML 文件。bind：通过配对码绑定设备。login/logout：手工配置或清除 Token。whoami：查看当前状态。
安装¶
推荐通过 GitHub 安装，并锁定 commit SHA 以确保版本一致。
dsh plugin --profile <name> add github:iwker/dsh-htmlrun#<commit-sha>
安装后，插件会作为组合包（bundle）加载到 DSH 配置中。
使用方法¶
工具参数¶
调用 htmlrun 工具时，需传入以下参数：
| 参数 | 类型 | 说明 |
|---|---|---|
action |
string | 必填。执行动作：check, publish, bind, login, logout, whoami |
file |
string | publish 动作必填。HTML 文件的绝对路径或相对于 workspace 的路径 |
note |
string | publish 动作用。本次发布的简短说明（可选） |
forceNew |
boolean | publish 动作用。强制新建工件拿全新链接（默认同路径自动更新，版本 +1） |
noInline |
boolean | publish 动作用。不内联本地资源（默认自动内联同级目录文件） |
code |
string | bind 动作用。8 位配对码 |
token |
string | login 动作用。html.run 的 publish token（h_ 开头） |
cliPath |
string | 可选。覆盖 htmlrun.cjs 的执行路径 |
典型流程¶
- 检查状态：模型首先调用
action=check。若未激活，CLI 会输出激活链接和二维码，模型需将这些信息转达给用户；用户确认后，再次check静默通过。 - 发布内容：模型调用
action=publish, file=<文件路径>。 - 结果反馈：CLI 返回链接、版本号、敏感词提示等信息，模型需将这些原始输出转达给用户，而不是简单的“发布成功”。
常见操作示例¶
- 更新链接：修改完 HTML 内容后，对同一文件路径再次调用
action=publish（不加forceNew），链接不变，版本号自动 +1。 - Token 管理：Token 明文不应出现在对话回复或日志中。
login时仅传递h_开头的值，后续操作由 CLI 内部读取配置。
限制与注意事项¶
- 单文件限制：仅支持单文件静态 HTML。CSS/JS 需内联或使用本地相对引用，图片等资源由 CLI 自动处理。
- 环境要求：依赖 Node.js >= 16。
htmlrun.cjs为零依赖，但需在插件进程或工作区中可用。 - 动态插件特性：动态插件形态是进程内临时的。DSH 进程重启后，需要重新加载插件（通过
cordis_define或重新安装）。 - Token 位置：Token 存储在
~/.htmlrun/config（权限 0600）。换机器或换路径发布会被视为新工件。
生态与来源¶
本插件由 iwker 维护，遵循 MIT 许可证。
* 插件本体：作者编写，MIT。
* Skill 源码：原样拷贝自 html.run 官方发布的 skill v2.0.1（MIT），随项目分发。
总结¶
dsh-htmlrun 解决了 DSH 沙箱环境下无法直接调用 html.run 发布接口的问题。它通过复用成熟的 CLI 工具，为模型提供了可靠的本地文件发布能力，适合需要将生成的 HTML 页面直接分享给用户的场景。
