dsh-htmlrun
把 html.run 的 HTML 发布能力从 agent skill 封装成 DeepSeek Harness（DSH）插件，让 DSH 会话内的模型可以直接把本地 HTML 发布成可分享链接。
> GitHub 仓库名与 npm 包名均为 dsh-htmlrun；harness 插件列表显示时会剥离 dsh- 前缀 → htmlrun；工具名、插件 name 均为 htmlrun。
用户："帮我把这个页面发布一下，发给我看看"
↓
DSH 模型调用动态工具 htmlrun (action=publish, file=...)
↓
插件通过 ctx.subprocess 调用 skill 自带 CLI（scripts/htmlrun.cjs）
↓
返回链接、版本、敏感词、指引等信息，由模型原样转达给用户目录结构
dsh-htmlrun/
├── README.md # 本文件
├── package.json # 组合包（bundle）manifest：包名 dsh-htmlrun，声明 dsh.bundle
├── cordis.patch.yml # 组合包 patch：条目 id=htmlrun，name=dsh-htmlrun
├── lib/
│ └── index.js # 插件真实模块入口（ESM，import defineTool + ctx.tools.register）
├── plugin/
│ └── htmlrun-publish/
│ └── host.js # 动态插件形态（code.host，会话内 cordis_define 用，免安装）
└── skill/ # 原始 htmlrun skill（v2.0.1，MIT，原样拷贝，随项目分发）
├── SKILL.md # skill 说明文档
├── scripts/htmlrun.cjs # 零依赖 CLI（Node >= 16），插件的实际执行体
└── references/api.md # html.run 服务端接口参考两种形态共享同一套执行逻辑（子进程调 CLI、token 存 ~/.htmlrun/config）：
- 动态插件（
plugin/htmlrun-publish/host.js）：会话内cordis_define加载，免安装、进程内临时； - 组合包（仓库根：
package.json+cordis.patch.yml+lib/index.js）：可安装进 profile 的正式形态，用于发布到社区。
原理
- 不重写 HTTP 层：插件的
execute用ctx.subprocess把node scripts/htmlrun.cjs <动作>作为子进程跑起来，输出原样透传给模型转达——行为与 skill 里 CLI 逐字节一致，包括激活二维码、敏感词、⚠ 已被限制访问、说明:/指引:等字段。 - 凭据互通：CLI 的 token 存在
~/.htmlrun/config，插件与终端里手工使用 CLI 是同一份凭据，无需重复激活。 - 为什么不直接用网络服务：DSH 动态插件沙箱禁用了
fetch/require，而ctx.web.fetch只支持无头 GET（无法发 POST + Authorization），调不了 html.run 的发布接口；ctx.fs写~会被 workspace-write 沙箱拒绝。ctx.subprocess是本地未加沙箱的子进程服务（dsh-bash-local同样用它），是唯一能完整跑 CLI 的路径。
快速开始（动态插件，会话级）
1. 确认本机有 Node（node --version，需 >= 16），并保证 skill/scripts/htmlrun.cjs 可用（本仓库自带）。 2. 在 DSH 会话中加载插件（把 plugin/htmlrun-publish/host.js 的内容作为 code.host）：
- cordis_define（新插件）：plugin.kind = "new"、idPrefix = "hpub"、code.host = host.js 全文； - cordis_run：激活后即向当前会话注册模型工具 htmlrun。
3. 之后直接对模型说"发布 xx.html / 更新一下链接"即可，模型会调用 htmlrun 工具。
CLI 路径解析
插件按以下顺序确定 htmlrun.cjs 的位置：
1. 调用时显式传 cliPath 参数（绝对路径）； 2. 当前 workspace 下的 skill/scripts/htmlrun.cjs（把本仓库作为 DSH workspace 时自动命中）； 3. 两者都找不到时返回明确错误，提示用户传 cliPath 或把仓库作为 workspace。
工具参数
| 参数 | 说明 |
|---|---|
action | 必填。check（检查/发起激活）· publish（发布或更新）· bind（配对码换 token）· login（手工配置 token）· logout（清除 token）· whoami（查看状态） |
file | publish 用：HTML 文件绝对路径或相对 workspace 路径 |
note | publish 用：本次发布/更新的简短说明（可选） |
forceNew | publish 用：强制新建工件拿全新链接（慎用；默认同路径自动更新原链接，版本 +1） |
noInline | publish 用：不内联本地资源（默认自动内联，只内联 HTML 所在目录内的文件） |
code | bind 用：管理端「绑定设备」给的 8 位配对码 |
token | login 用：手工配置的 publish token（h_ 开头） |
cliPath | 可选：覆盖 htmlrun.cjs 的位置 |
常见流程
- 首次使用：
action=check——未激活时返回激活链接与二维码，转达用户，等用户确认后再check一次；已激活则静默通过。 - 发布：
action=publish, file=...；成功后把输出里的链接:原样给用户，出现敏感词(N)/⚠ 已被限制访问/说明:/指引:时原样转达，不要说"发布成功"糊弄过去。 - 更新：改完内容后对同一文件路径再次
publish（不加forceNew），链接不变、版本 +1。 - token 纪律：token 明文不要出现在对话回复或日志里；
login只把h_开头的值传给工具，之后不要复述。
发布到插件社区
DeepSeek Harness 目前没有官方的中心化插件商店；官方推荐的插件分发方式是把插件打包成组合包（bundle）发布到 npm 或 GitHub，并在仓库打上 dsh-plugin 话题便于社区发现（官方 CONTRIBUTING 明确推荐，官方仓库暂不接受外部 PR）。本仓库根目录已经是标准 bundle 结构。
分发渠道（三选一）
1. GitHub（推荐，零构建门槛）
本插件是纯 JavaScript，无需构建，git 安装不需要 prepare 脚本授权：
# 推送到 GitHub 后，用户安装（仓库名 dsh-htmlrun）：
dsh plugin --profile <name> add github:iwker/dsh-htmlrun#<commit-sha>建议锁定 commit（#<sha>），防止仓库后续推送悄悄改变实际运行的代码。仓库创建后到 Settings → Topics 添加 dsh-plugin 话题。
2. npm 注册表
pnpm publish # 或 npm publish（需先登录；包名 dsh-htmlrun，npm 上尚无人占用）
# 用户安装：
dsh plugin --profile <name> add dsh-htmlrun发布到 npm 的内容由 package.json 的 files 字段控制（lib/、skill/scripts/、cordis.patch.yml、README.md），用户拿到的是预构建代码。安装后 harness 插件列表显示的标题是 htmlrun（dsh- 前缀由界面自动剥离）。
3. tarball（自建分发）
pnpm pack # 生成 dsh-htmlrun-0.1.1.tgz
# 用户安装：
dsh plugin --profile <name> add ./dsh-htmlrun-0.1.1.tgz安装后验证
dsh --profile <name> --dump-config # 应出现 "# == dsh-htmlrun" 层
dsh --profile <name> # 启动，然后在对话里让模型发布 HTML社区发现渠道
- GitHub 话题
dsh-plugin（官方推荐） - awesome-dsh-plugin（社区清单，PR 收录）
- awesome-deepseek-harness（社区清单，PR 收录）
- dshfind（社区插件市场）
与配置 key 的关系
本插件不需要为 DSH 配置任何 key：html.run 的 publish token 由 CLI 自行管理（~/.htmlrun/config）。若插件自身需要接入 DSH 的密钥体系（比如调用别的服务），官方做法是用 ctx.credentials 服务（见 host.js 里的说明），配置里只存环境变量名，值放 $DSH_HOME/.credentials.yaml 或启动环境变量。
已知边界
- 只支持单文件静态 HTML（CSS/JS 需内嵌或用本地相对引用；本地图片等资源由 CLI 自动内联）。
- 不支持需要构建、需要后端的完整项目；不支持自定义域名等 html.run 未提供的能力。
- 动态插件是进程内临时的，DSH 进程重启后需重新加载（
@hpub-1引用或重新 cordis_define）。 token保存在~/.htmlrun/config（0600），换机器/换路径发布会被视为新工件（path参与工件匹配）。
许可与来源
- 仓库根 bundle（
package.json、cordis.patch.yml、lib/index.js）与plugin/htmlrun-publish/host.js：本仓库作者编写，MIT。 skill/：原样拷贝自 html.run 官方发布的 htmlrun skill v2.0.1（MIT），随项目分发；升级请替换整个skill/目录，不要单独改scripts/htmlrun.cjs（其内部与服务端逐字节对齐，禁止私自分叉）。bundle 通过lib/index.js的import.meta.url相对引用skill/scripts/htmlrun.cjs，保持单一来源。