# hecong_dsh_plugins **Repository Path**: hecong9402/hecong_dsh_plugins ## Basic Information - **Project Name**: hecong_dsh_plugins - **Description**: 自定义dsh插件集合。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-30 - **Last Updated**: 2026-11-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: dsh-plugins ## README # hecong-plugins 一组跑在 **DeepSeek Harness(DSH)** 上的自研 Cordis 插件:媒体生成、语音、识图、小说、短视频、直播、2D 桌宠(规划中)、插件可观测与桌面外壳。 本仓库**不是 DSH 源码仓库**,而是一份独立开发、可整体搬运的插件集合。 > 想要"拿下来就能跑"?**先跑这一条**: > > ```sh > node scripts/bootstrap.mjs > ``` > > 它会装构建依赖、修好依赖软链、构建全部产物,然后自检。跑完再 `node scripts/preflight.mjs`(退出码 0 才谈启动 DSH)。 --- ## 1. 前置条件 | 项 | 要求 | 说明 | |---|---|---| | Node.js | **>= 18**(实测 v22 / v24 均可) | 纯 ESM,无 TypeScript 构建步骤 | | npm | 任意版本 | 只在 `bootstrap` 时用一次,装两个构建期依赖 | | 网络 | 首次需要 | 装 `esbuild`(构建客户端 bundle)与 `winbox`(窗口引擎);之后可离线 | | DSH | 已装并可运行 | 插件靠 DSH 提供的 `webServer` / `tools` / `slots` 等服务 | | ffmpeg + ffprobe | **仅短视频域需要** | 缺了不影响 DSH 启动,只有 `compose_*` / `storyboard_assemble` 报错 | | DashScope API Key | **仅生成类功能需要** | 出图 / 出视频 / TTS / 转写 / 识图;不配则对应工具报缺 key | | 中文字体 | 仅短视频烧字幕需要 | 缺字体时字幕会显示成方块 | **OS**:本仓库在 Linux 上开发与实测。路径处理全部走 `node:path` 且不依赖任何绝对路径,理论上 macOS 可用;Windows 未验证(`node_modules` 软链与 `ffmpeg` 调用方式可能需调整)。 --- ## 2. 安装(三步) ```sh git clone <本仓库地址> hecong-plugins cd hecong-plugins node scripts/bootstrap.mjs # ① 一键初始化(装依赖 + 建软链 + 构建 + 自检) node scripts/preflight.mjs # ② 启动前预检(退出码 0 = 可安全启动) ``` `bootstrap.mjs` 的参数: ```sh node scripts/bootstrap.mjs # 全套:依赖 + 软链 + 构建 + 自检 node scripts/bootstrap.mjs --no-build # 只准备依赖 node scripts/bootstrap.mjs --check-only # 只自检(交接验收 / CI 用) ``` 它是**幂等**的:重复跑不会坏,正确就跳过。 ### 为什么必须有这一步 本仓库**不把构建产物与第三方依赖入库**(`各插件的 lib/`、`node_modules/` 都在 `.gitignore` 里), 所以"克隆完直接跑"一定失败——这不是坏了,是缺了构建这一步。典型报错: - 自测:`Cannot find module '<插件>/lib/index.js'` - 窗口管理器:`bundle 不存在:…/lib/client.js(先在该插件目录跑 node build.mjs)` --- ## 3. 接到 DSH 上 ### 3.1 只挂三个"元插件" DSH 的 web profile 配置(`$DSH_HOME/profiles/web/cordis.patch.yml`)**只留三行**: ```yaml - insert: - id: plugin-insight name: <仓库绝对路径>/platform/plugin-insight/src/index.js - id: window-manager name: <仓库绝对路径>/shell/window-manager/lib/index.js - id: dsh-logger name: <仓库绝对路径>/platform/dsh-logger/src/index.js ``` 其余自研插件**全部由窗口管理器在运行时自己装载**(清单见 `shell/window-manager/apps.json` 的 `autoload`), 所以它们"装得上、也卸得掉",不需要重启。这三个元插件是自举链的根(`window-manager` 依赖 `plugin-insight` 解析依赖图; `dsh-logger` 要能在别的插件出问题时工作,所以不能挂在别人之后),**改它们只能重启**。 > 把 `<仓库绝对路径>` 换成你自己的克隆路径 —— 这是**唯一**需要你手填绝对路径的地方 > (仓库内部一切路径都相对化/自动定位,不含任何作者机路径)。 ### 3.2 依赖软链(一般不用管) 若某个工作台在窗口里报 "bundle 不存在",说明对应插件没构建:`cd <插件目录> && node build.mjs`。 ### 3.3 打开页面:DSH 0.2 要带 token 0.2 起 `dsh web` 会给 `/` 与 `/api` 加**浏览器令牌**:裸开 `http://127.0.0.1:3080` 返回 **401**, 必须用启动时打印的 `http://127.0.0.1:3080/?token=…`(它会把 token 换成 cookie)。 **插件自己的路由(`/wm`、`/shortvideo`…)不在那道门里**,所以它们各自带了一层 `guardRoute()` 栅栏(跨站 / 跨源 / DNS rebinding 一律 403;详见根 `AGENTS.md` 的「安全约定」)。 ### 3.4 agent 预设:0.2 起是"组合里的一行" 旧版把预设放 `$DSH_HOME/.agent-presets//`;**0.2 不再读这个目录**。现在写一行 `@deepseek-ai/dsh-agent-preset`,`config.plugins` 就是原来的行列表;预设里**提供服务**的插件 (`novel-core`、`storyboard-core` 等)必须包在带 `isolate` 的 `cordis:group` 里, 否则该预设会被判 `broken`。完整配方(实测通过)见 `AGENTS.md` 的「热重载覆盖不到谁」一节。 --- ## 4. 验证装好了 ```sh node scripts/bootstrap.mjs --check-only # 依赖与产物齐备 node scripts/preflight.mjs # host/client 两半都能加载(务必退出码 0) node scripts/count-assertions.mjs # 跑遍全部自测并统计断言数 ``` 启动 DSH 后,页面不应出现 `Failed to load plugins`;侧栏应该能看到「窗口中心」, 里面列出各工作台(生图 / 视频 / 音频 / 小说 / 短视频 / 直播 / 插件工作台…)。 --- ## 5. 目录结构 ``` hecong-plugins/ ├── plugins.manifest.json # 仓库根标记 + 功能域清单(域 = 目录) ├── scripts/ # 工具:bootstrap / preflight / 各离线自测 ├── .dsh/skills/ # 本仓库给 agent 用的技能 ├── <域>/README.md # 域说明(用途 / 成员 / 数据流) ├── <域>/AGENTS.md # 域级约定(进该域干活时自动加载) └── <域>/<插件>/ # src/index.js(+ lib/)、package.json、README.md、build.mjs ``` 功能域:`media` `audio` `vision` `routing` `novel` `shortvideo` `live` `desktop-pet` `platform` `shell` `uncategorized`。 --- ## 6. 常见问题 | 症状 | 原因 | 处理 | |---|---|---| | `Cannot find module '…/lib/index.js'` | 没构建 | `node scripts/bootstrap.mjs` | | `bundle 不存在:…/lib/client.js` | 该插件没构建 | `cd <插件目录> && node build.mjs` | | `Cannot find module 'scripts/lib/tool-schema.mjs'` | 旧版本的 `.gitignore` 把它当构建产物忽略了 | 拉最新代码(该规则已修) | | 预检报 `lib/ 不存在` | 同第 1 行 | `node scripts/bootstrap.mjs` | | 短视频合成报 `spawn ffmpeg ENOENT` | 没装 ffmpeg | `apt install ffmpeg`(或对应平台命令) | | 字幕显示成方块 | 缺 CJK 字体 | 装 Noto Sans CJK | | 生成类工具报缺 key | 没配 DashScope | 配 `DASHSCOPE_API_KEY` 等(见各域 README) | | 启动报 `EADDRINUSE …:3080` | 端口被占(多半是上一个 DSH 没退干净) | `pkill -f "apps/cli/src/bin.ts web"` 后再启动 | | 某个插件目录改名/移动后工作台里消失 | 登记表没同步 | 见 `AGENTS.md`「移动或改名插件后必须同步」 | --- ## 7. 给开发者 改插件前先读: - **`AGENTS.md`**(根):仓库约定、硬约束、功能域表、自测清单。 - 技能 `plugin-conventions`:写/改插件的完整约定。 - 技能 `dsh-plugin-preflight`:改完怎么验、什么时候才能让人重启。 - 各域的 `<域>/AGENTS.md`:进该域干活时自动加载。 **三条不能忘的**:① 改完 host 插件先跑 `node scripts/preflight.mjs`; ② 新插件登记只写「插件 README 的 `## 上下游`」+「`apps.json`」,不碰 DSH 配置; ③ 别靠重启试——每个链路都有离线自测,几秒出结果。 --- ## 8. 可移植性说明(给搬运这份仓库的人) 这份仓库被设计成**可以放在任意目录、任意用户名下运行**: - 仓库根靠**向上查找 `plugins.manifest.json`** 定位,不靠 `../..` 猜层级; - 一切插件路径(`apps.json` 的 `path`/`hostPath`)写**仓库根相对路径**,由 window-manager 在运行时拼绝对路径; - 脚本(`preflight` / `bootstrap` / 各测试)从**自身文件位置**推导仓库根,不写死任何机器路径; - 数据根默认落在**当前用户的家目录**(如 `~/novel`、`~/short-video`),可用环境变量覆盖 (`NOVEL_ROOT` / `SHORTVIDEO_ROOT` / `COMPOSE_ROOT` …); - 依赖软链用**相对路径**(曾经是提交进 git 的绝对路径,换机器就成死链)。 **需要你自己配的只有三样**:`cordis.patch.yml` 里三个元插件的绝对路径、DashScope 密钥、以及可选的路径类环境变量。 --- ## 9. 许可 **MIT License** —— 全文见仓库根的 [`LICENSE`](LICENSE),版权归 **hecong**(2026)。 简单说:你可以自由使用、修改、分发、商用,**唯一的要求是保留版权声明与许可声明**; 软件按"现状"提供,不含任何担保。每个插件包的 `package.json` 也都带 `"license": "MIT"` 字段。 **第三方依赖**:仓库内的代码是自研的,但运行时依赖第三方包,它们各有自己的许可—— 例如 `window-manager` 打包进前端的 **winbox**(Apache-2.0,装在 `shell/window-manager/deps/`)。 MIT 只覆盖本仓库自己的代码,**不改变**这些依赖的许可。