Skip to content

Repository navigation

plugin-development.md

Latest commit

 

History

History
129 lines (85 loc) · 6.74 KB

plugin-development.md

File metadata and controls

129 lines (85 loc) · 6.74 KB
Raw

插件开发

plugins/* 中维护 DeepSeek Harness 的 harness 插件。插件开发前加载 $dsh Skill，确认目标 DSH 版本、Profile、Host/Client 边界、Slot、Service 和 Bundle 约束。

# 安装或更新 Skill
pnpx skills add tnnevol/skills --skill dsh -g

实现边界

:::warning 插件实现边界

官方 Harness 源码只用于查阅和调试，不直接修改。插件的 package.json、Peer Dependency、兼容声明和 @deepseek-ai/* 依赖必须与目标 DSH 版本一致。

新增注册、定时器、网络连接或观察器时，必须提供可逆清理，并验证 HMR、重复注册和真实 Profile 加载。

:::

基础检查

# 仓库内 CLI，版本与 FPK 运行时基线一致
pnpm exec dsh --version

# 检查所有 harness 插件和共享包
pnpm run check -- --packages --plugins

需要查看组合配置时（下列命令使用全局 dsh；要检查仓库内 profile，请先按本地 DSH Web 设置 DSH_HOME）：

dsh --profile web --dump-config
dsh --profile web --dump-config | grep -n -C 3 'dsh-fnos'

构建、启动和检查

# 交互选择 harness 插件、FPK 或文档
pnpm run build

# 构建指定 harness 插件
pnpm run build -- --plugin fnos

# 启动指定 harness 插件的 watch
pnpm run start -- --plugin fnos

# 检查所有 harness 插件和共享包
pnpm run check -- --packages --plugins

插件的 build、typecheck、test 和 check 写在各自的 package.json。Turbo 会根据 workspace 依赖先处理 @tnnevol/dsh-semi-ui，不要在根脚本中手工复制依赖步骤。

本地开发

插件的 dev 任务是常驻的 tsdown --watch，被 Turbo 通过 start 间接调度。它与共享包的关系有一条硬约束：

插件 bundle 需要解析 @tnnevol/dsh-semi-ui/lib/index.js。如果两边并行 tsdown，dsh-semi-ui 的 clean（默认删除 lib/）会让插件侧解析失败并报 Could not resolve '@tnnevol/dsh-semi-ui'。

因此共享包的 dev 是一次性构建（包内 turbo.json 覆盖 persistent: false），先完成；插件自己的 dev 保持常驻，并在 interruptible: true 下于依赖变化时被 turbo watch 重启。调度细节见 Turbo 任务。

测试布局

插件的单元测试集中放在 workspace 同级 tests/，通过 test 调用该 workspace 的 vitest.config.ts。新增测试应放入对应 workspace 的 tests/，按被测模块组织文件；不要把跨 workspace 的测试复制到根目录，也不要把测试混入 apps/ 下的 fnOS 应用目录。

内置 Skill 的上游同步检查（强制）

内置 skill 的插件（当前为 @tnnevol/dsh-midscene）在每次开发前必须检查内置 skill 是否有上游更新。理由：内置 skill 是 agent 理解该领域的唯一权威入口，上游修了错误或补了新 API 而插件还带旧版，agent 会照着过期资料干活，且这种偏差不会以任何方式报错。

检查对象与来源

插件内置 skill 上游 检查方式
6 个平台技能（browser / computer / android / ios / harmony / vitest-midscene-e2e） web-infra-dev/midscene-skills git -C <上游检出> log -1 --format=%H，与 skills/SOURCE.md 登记的提交比对
midscenejs tnnevol/skills（skills/midscenejs） 同上

检查步骤

# 1) 取上游当前版本（两处上游都要查）
git clone --depth 1 https://github.com/web-infra-dev/midscene-skills.git /tmp/midscene-skills
git -C /tmp/midscene-skills log -1 --format=%H
git clone --depth 1 git@github.com:tnnevol/skills.git /tmp/skills
git -C /tmp/skills log -1 --format=%H

# 2) 与插件内登记的提交比对（skills/SOURCE.md 的「上游提交」一行）
grep -n "上游提交" plugins/dsh-midscene-plugin/skills/SOURCE.md

比对结果的处理

情况 处理
提交一致 无需动作，在本次开发的记录里说明「已核对，无更新」
有更新 按 skills/SOURCE.md 的「同步方式」整目录覆盖（不需要重新施加补丁）
无法访问上游 如实记录「未能核对」及原因，不要假定无更新

内置技能不得修改：技能文件必须与上游逐字节一致，这样升级时整目录覆盖即可、且可用哈希核对。本环境的模型约束不写在技能文件里，而是由 src/host/skills.ts 的 BRIDGE_PRELUDE 在分发时注入（官方技能教 agent 去申请第三方 API key，与「本插件用 DSH 已有模型」冲突，故在分发内容前加一段环境说明）。把约束写进文件就又是一份需要每次同步时重新施加的补丁。

因此 plugins/*/skills/** 已从仓库 lint 中排除——它们是第三方原文，改格式即等于改动上游。

同步完成后更新 skills/SOURCE.md 的上游提交、同步日期、各文件 sha256：哈希由守卫测试核对，漏登记会报红。

插件截图## 插件截图

插件功能截图服务于两处：DSH 文档站页面（docs/plugins/）与插件市场收录（awesome-dsh-plugin、dsh-market 读取仓库内 screenshots.json）。截图只维护一份，统一放 docs/public/images/plugins/<插件名>/。

约束：

  • plugins/<插件名>/screenshots.json 声明 1–8 张截图，内容为 GitHub 托管的 https 绝对 URL（https://raw.githubusercontent.com/FNOSP/fnos-dsh/main/docs/public/images/plugins/...）。市场与收录流程不读 npm 包，截图不会进入 npm publish（各插件 files 白名单不含 screenshots.json 与图片）。
  • 不要在插件子目录内再复制一份 assets/ 截图，也不要用 ../ 相对路径引用插件目录之外的文件——收录校验会拒绝相对路径跳出插件目录。
  • 依赖 fnOS 宿主环境的插件（如 @tnnevol/dsh-fnos）在真机上补拍截图后再声明。
  • 发布前核对描述与截图不含账号昵称、手机号、账号 ID 等敏感信息；用浏览器演示截图时先在 DOM 层脱敏，不改插件代码。
  • 移动或改名 docs/public/images/plugins/ 下的图片时，必须同步更新对应插件的 screenshots.json——绝对 URL 在源文件移动后会静默失效。

相关页面

日期 变更
2026-10-13 「内置 Skill 的上游同步检查」按新约定修订：内置全部 6 个官方平台技能 + midscenejs，且技能文件与上游逐字节一致、不再打补丁；模型约束改由 BRIDGE_PRELUDE 在分发时注入。