DSH Hub Workshop

插件开发与市场指南

这份指南面向希望把 Skill、MCP、Cordis 扩展、Web UI 或其他社区项目放进 DSH Hub Workshop 的开发者。目标有两个：

  1. 少量修改就能进入市场发现：第三方项目不需要改变现有分发方式，也不要求发布 npm 包。
  2. 讲清当前公开接入路径：Profile Bundle 可进入事务验证；Repository Plugin 只保留为配置候选并自动阻断；其余项目使用无执行权限的引导接入。

市场准入、协议归属和管理能力是三个维度。Cordis 虽然来自上游开源项目，但在官方 Harness 中已经被 vendor、固定并作为 SDK 底层插件模型维护，因此普通 Cordis 插件应标记为“官方 SDK 接入”，不能与 Fabric、旧 dshx / Marisa 等第三方格式混为一类。普通 Cordis 插件仍属于“引导接入”，只有发布为 Profile Bundle 后才进入 OMDSH 的事务安装与 generation 恢复。

五分钟最短路径

如果项目已经能用，通常只需要：

  1. 在仓库中保留实际可运行的代码或静态资产；
  2. README 写清用途、当前安装方式、依赖、权限和已知限制；
  3. 添加许可说明，或明确标注私有测试/未声明许可边界；
  4. 选择一个准备接受审核的 40 位 Git commit；
  5. 在 Author Studio 生成 submission manifest，并提交扩展收录申请。

这条路径不要求改造项目结构。自动化只读取固定 commit，不执行项目代码。扫描完整且没有高风险信号的项目可进入低风险收录流程；其余项目会保留在待审核或待修复清单。

让 AI 帮你完成最小接入

如果项目已经存在，可以把下面的 Prompt 交给能访问仓库的编码 AI。它会先判断项目的真实形态，再做最小改动；不会为了获得安装按钮强行改造成 Profile Bundle，也不会直接修改 DSH Hub Workshop 的 Catalog、Registry 或生成文件。

推荐流程是：AI 修改并验证作者仓库 → 作者审阅后提交 commit → 在 Author Studio 填写或核对事实 → GitHub 自动扫描与收录。AI 的报告是填写辅助，不是 submission manifest，也不代表安全审核或官方认证。

你正在当前插件仓库中工作。请在不重写项目核心、不增加第二套 Loader 或常驻 daemon、不把第三方格式伪装成官方协议的前提下，以最小修改让它可以接入 DSH Hub Workshop。

工作前：
- 完整读取仓库内适用的 AGENTS.md、README、许可文件、package manifest、lockfile、入口、构建配置和测试。
- 不输出或提交 Token、密钥、私有链接、个人绝对路径及本机配置。
- 不执行来历不明的安装脚本、远程脚本或二进制；需要执行现有项目命令时，先判断其用途和风险。

按以下顺序工作：

1. 先审计，暂不修改。报告项目根目录、实际功能、入口、构建与测试方式、依赖、权限、网络/文件/Shell/native 能力、外部副作用、许可和当前安装方式。

2. 只根据仓库中可验证的事实选择一种接入形态：
   - 官方 Profile Bundle：仅当项目真实提供 dsh.bundle.patch、可解析的 cordis.patch.yml，以及禁用安装脚本后仍可使用的已提交运行时制品时选择。
   - Repository Plugin 配置候选：仅当项目已经真实提供 .dsh-plugin/package.json 时保留固定来源证据；当前公共 Runtime 未提供可核验的对应契约，因此不得声称可安装。
   - 官方 Agent Preset：仅当项目真实提供 agent.cordis.yml 时选择；它是会话级组合，当前只做固定来源与接入说明，不获得自动导入或 generation 恢复。
   - 官方 Cordis SDK 接入：项目遵循官方 ctx/effect/fiber/dispose 生命周期，但尚未发布为 Profile Bundle。
   - 第三方接入：Skill、MCP、Fabric、旧 dshx / Marisa、源码补丁或其他现有格式只保留发现与接入说明。
   无法确认时选择“第三方接入”。无缝安装是可选能力，不是市场准入门槛。

3. 实施最小改动：
   - 在 README 补齐用途、项目边界、安装/接入方式、兼容性、依赖、权限、测试、已知限制、是否需要重启，以及不能被 generation 恢复的外部副作用。
   - 补充或明确许可边界；无法确认的信息写“未知/未声明”，不要猜测。
   - 固定生产依赖并保留受支持的 lockfile。lifecycle script、native 制品和动态下载只有在功能确实需要时才保留，并明确披露。
   - 可选添加仓库内的图标、封面和最多 4 张截图；不要从 README 猜测市场图片。
   - 只有仓库天然符合当前公开契约时，才新增或修正 Profile Bundle 的 package.json、cordis.patch.yml 和预构建运行时文件。不要新造 .dsh-plugin，也不要为了显示安装按钮包装任意 MCP、源码工具或第三方管理器。
   - 不修改 dsh-hub 的 catalog.json、registry*.json、workshop*.json、生成页面或签名文件；这些由 Author Studio、扫描器和 CI 生成。

4. 使用仓库已有的 test、lint、typecheck、build 和最小启动/关闭测试验证。不要为了让测试通过而降低安全边界。如果必须依赖未公开或无法核验的 Harness 内部 API，请停止改造并说明阻塞点。

5. 最终只输出：
   - 选择的接入形态及证据；
   - 修改文件与原因；
   - 已运行的检查及结果；
   - 权限、外部副作用和剩余风险；
   - 建议填写到 Author Studio 的 Project、Release、兼容性、管理方式和声明字段；
   - 需要作者人工确认的事项。

不要虚构版本、兼容性、下载量、作者、许可证或回滚能力。不要自行 commit、push、创建 Release 或提交市场；完成本地修改和验证后等待作者审阅。作者确认后应创建一个固定 commit，并在 https://hub.0.org.cn/publish.html 生成正式 submission manifest。

这段 Prompt 故意不要求 AI 生成最终 JSON：项目事实可能在修改过程中变化，而 commit 只有作者确认后才固定。Author Studio 才是 submission manifest 的唯一生成入口，市场构建流水线再从该 manifest 投影 Catalog、Registry 和 Workshop 展示数据。

Workshop 如何识别扩展形态

项目的实际形态 市场标记 DSH Hub Workshop / OMDSH 的行为
官方 Profile Bundle 事务托管 在 candidate Profile 中安装和校验
Repository Plugin 配置候选 当前阻断 只保留固定来源证据；公共契约可核验后重新测试
官方 Agent Preset 官方会话配置 展示固定来源与组合说明；当前不由 OMDSH 自动导入
Cordis 插件 引导接入 只展示固定来源与生命周期说明；不生成不可用的 SDK 命令
未封装为 Repository Plugin 的 Skill / MCP 第三方接入 展示固定来源、版本、兼容性和风险事实
Fabric、深层 Hook、旧 dshx / Marisa 或源码补丁 第三方接入 仅作兼容性说明，不调用其工具或执行安装

以项目真实形态为准。不要为了显示安装按钮而伪造 Profile Bundle、Repository Plugin 或回滚能力。

让 Agent 理解插件生态

Harness Agent 不需要抓取网页或执行第三方仓库代码。它可以读取三个有边界的静态接口：plugin-types.json 用于理解分类，plugins.json 用于解释项目用途，ecosystem.json 用于分析固定 Release 的依赖声明、运行证据和已发布组合。

ecosystem.json 绑定同一份签名 Registry snapshot，但不包含安装命令、adapter spec、验证者身份或秘密。Agent 只能从声明过的 relations、成功 Run Record 和组合 useCases 确定性地回答依赖、兼容性与任务推荐；缺少事实时必须回答“未知”。修复只允许返回不可执行的差异预览，真正应用仍由 OMDSH candidate、官方 Profile/Bundle 校验和用户确认完成。

编写一个 Skill

最小 Skill 只需要一个目录和 SKILL.md：

my-skill/
└── SKILL.md

---
name: session-summary
description: 当用户要求整理会话时，生成带结论、证据和后续行动的结构化摘要。
---

# Session Summary

1. 先提取已经确认的结论。
2. 区分事实、推断和未解决问题。
3. 最后列出可执行的后续行动。

建议遵循这些规则：

如果项目已经包含 Repository Plugin 目录，可以按下面结构保留为配置接入候选；当前指南不建议新建这种结构，也不据此授予安装权限：

.dsh-plugin/
├── package.json
└── skills/
    └── session-summary/
        └── SKILL.md

{
  "name": "session-summary",
  "version": "0.1.0",
  "private": true,
  "description": "Structured session summary Skill",
  "dsh": {
    "skills": ["skills"]
  }
}

静态 Skill 不需要安装脚本或构建步骤。市场 Release 会固定到类似下面的来源：

github:owner/repository#<40位commit>&path:/.dsh-plugin

该来源只用于静态审核和未来兼容跟踪。当前公共 Runtime 没有可核验的对应 Schema 与 Loader，所以入库状态会保持阻断。

编写 MCP

MCP 继续遵循 MCP 自己的协议和进程边界，DSH Hub Workshop 不发明另一套 MCP SDK。开发时至少保证：

已有 MCP 统一以“第三方接入”收录。Workshop 只展示固定来源和兼容事实，不代为启动 MCP、调用第三方管理器或执行项目命令。

编写 Cordis / Web UI 扩展

运行时扩展继续使用官方 Cordis 生命周期：通过 ctx 获取服务，在 effect/fiber 中注册资源，并在 dispose 时解除监听、定时器和 UI 注入。插件自己的外部副作用仍由插件负责；generation 恢复只能恢复 Profile 制品和配置选择，不能撤销已经发送的消息、数据库写入或远程 API 操作。

当前 Workshop 只记录 Cordis 插件的固定公开来源、生命周期说明、权限和测试事实，不生成安装命令，也不声称公共 SDK 包可用。项目若有自己可公开核验的接入方式，应在固定 commit 的 README 中说明；Workshop 仍只提供阅读引导。

如果扩展本身按官方 Profile Bundle 发布，OMDSH 可以提供无缝安装。最小结构是：

my-extension/
├── package.json
├── cordis.patch.yml
└── index.js

{
  "name": "@owner/session-notes",
  "version": "0.1.0",
  "type": "module",
  "main": "./index.js",
  "exports": {
    ".": "./index.js",
    "./cordis.patch.yml": "./cordis.patch.yml"
  },
  "files": ["index.js", "cordis.patch.yml"],
  "dsh": {
    "bundle": {
      "patch": "./cordis.patch.yml"
    }
  }
}

- insert:
    - id: owner-session-notes
      name: '@owner/session-notes'

无缝安装要求固定 commit 或精确版本，并且在禁用安装脚本时仍可运行。因此请提交运行时 JavaScript 和必要静态资产，不要依赖用户安装时执行 prepare、postinstall 或下载远程二进制。可以参考公开的 插件模板。

分享官方 Agent Preset

Agent Preset 是官方的会话级 Agent 组合，不是 Profile Bundle，也不是新的插件 Loader。仓库可以把 agent.cordis.yml、可选的 preset.yml、本地 Skill 与资源作为一个可审阅目录提交；组合引用的包仍必须能在目标 Harness 中解析，文件中不得包含 Token、私人路径或机器专属配置。

当前 Workshop 只记录固定 commit、用途、所需插件和接入说明，不把外部 Preset 自动写入用户的本机 roster，也不把任意组合文本放进签名 Registry。官方尚未提供稳定的外部导入契约，因此这类项目保持引导接入；等上游提供导入边界后，再增加一个窄 adapter，而不是让 Recipe 或 WorkshopBridge 直接写目录。Recipe 继续只组合固定 Project/Release，Preset 的挂载、Skill 分层和失败保护继续由官方 Harness 负责。

发布社区整合包

整合包类似 Minecraft Modpack：它不是新 Loader，而是一个有版本、用途、文档、兼容范围和更新通道的长期组合。Oh My DSH 是社区维护的旗舰整合包；DSH Hub 是允许不同维护者发布许多整合包的中立平台。

在 Author Studio 选择“整合包 / 发行版”，只需填写双语名称和用途，并从已通过收录门禁的事务型 Profile Bundle Release 中选择组件。Studio 会生成严格的 omdsh-distribution/v1 纯数据 manifest；作者把它提交到自己的 GitHub 仓库，再用 40 位固定 commit 和相对 JSON 路径发起整合包收录申请。

现有收录流水线只读取该固定 commit 下的一份、最大 64 KiB 的 JSON，并检查所有 Project/Release 是否真实存在、处于 active 且已经 auto-listed 或 reviewed，并支持单 candidate 事务应用；review-required 与 blocked 仍会失败关闭。它不扫描或执行投稿仓库代码。验证通过后只生成一个草稿 Recipe 候选 PR，由维护者审阅，不自动合并。

整合包本身不会获得新的 Registry 权限，也不能携带安装命令、包 spec、脚本、Token、本机路径或任意配置。每个组件保留自身 Release 的审核、风险和安装能力。当前 Recipe v1 只投影该发行版的当前版本，历史版本继续由维护仓库保存；应用仍走“用户审阅差异 → OMDSH candidate → 官方 Profile/Bundle 校验 → 用户确认切换”。

如果只是分享一个固定列表而不准备长期维护品牌、兼容性和升级，请使用合集；如果要分享一个独立能力，请发布项目。

市场准入标准

最低准入：允许被发现

项目至少需要满足：

未声明许可的项目可以被索引为 Not declared，但使用和再分发权利可能受限。补充标准许可证能显著降低用户和维护者的判断成本。

自动收录与人工复核

扫描事实 处理方式
固定来源、扫描完整、无高风险信号 可形成低风险自动收录候选
文件/Shell/网络/凭据等权限与功能一致 复核用途后可收录，并保留风险标签
native、lifecycle script、动态下载、可信发布者申请 进入人工复核
依赖未锁定、扫描截断、结构不完整 needs-fix，补齐后重审
Critical 漏洞或明确恶意行为 blocked

静态扫描通过不等于安全担保。收录只表示项目可以在市场中被发现；它不会自动启用插件，也不会扩大 Harness 权限。

推荐准入：获得无缝安装

无缝安装是推荐能力，不是市场硬门槛。当前只有 Profile Bundle 可以在完成 RC.6 全生命周期验证和人工审核后申请“使用 OMDSH 安装”。Repository Plugin 配置候选自动阻断；Cordis 与其他格式统一使用无执行权限的引导接入。

OMDSH 只负责 candidate generation、Registry 校验和跨重启 generation 恢复；实际执行使用当前公开 DSH Profile/Bundle 生命周期。其他适配器只有在公共契约可核验并完成回归后才能加入。

可选：添加“已跑通”记录

“已跑通”不影响收录、风险等级或安装权限，只把项目声明与真实运行结果分开。验证者固定一个 Workshop Release，在明确的 DSH snapshot、Profile 和平台中完成安装、等待 runtime ready，并执行一个有名称的真实任务；随后把不含密钥和私人数据的 GitHub Actions、Issue 或 PR 作为证据，向 run-records.json 提交一条符合 run-records.schema.json 的记录。

第二位验证者必须使用相同 Release 和环境重新运行，并用 reproduces 指向第一条记录。只有这样页面才显示“第二位验证者已复现”。失败尝试继续留在对应 GitHub Issue 中，不会被包装成成功记录，也不会因此阻止项目被发现。

可选：声明结构化依赖

结构化依赖不影响项目被发现，也不要求作者学习新的 Loader。作者只需在 README 和 Author Studio 中如实说明必需/可选依赖；维护者审核时可以把它们映射为 Catalog 中的固定 Release 关系：

{
  "relations": {
    "required": [{ "projectId": "provider", "releaseId": "provider@1.0.0" }],
    "optional": []
  }
}

关系必须指向已经存在的 Project/Release，不能指向浮动分支，也不能自依赖或在必需/可选列表中重复。省略 relations 表示“尚未声明”，显式空数组才表示作者声明当前版本没有对应依赖。它只用于 Workshop 解释组合条件，不会进入 Registry、自动安装依赖或扩大执行权限。

项目页的“组合就绪度”只从这份声明、当前 Release 的成功 Run Record 和已发布合集派生。页面给出的下一步是确定性缺口提示，不会调用模型、修改仓库或自动生成 Recipe。

组合预检、推荐与修复候选

配置页会在用户展开“组合检查”时，用当前 Workshop/Recipe 静态数据核对固定 Release 是否可用、必需依赖是否包含、是否存在依赖环、是否有成功 Run Record，以及恢复和外部副作用边界。not-declared 始终显示为“证据待补”，不会被解释成“没有依赖”。推荐只按这些已知事实排序，不读取仓库、不调用模型，也不增加 Registry 权限。

自动修复目前只生成不可执行的 repairPreview：仅当一个已经声明的必需依赖指向现有、可用的固定 Release，而组合漏掉它时，才预览需要补入的 Project/Release。它不会修代码、选择浮动版本、修改作者仓库或写入当前 Profile。后续 Runtime 接入仍必须遵循“用户审阅差异 → OMDSH candidate → 官方 Profile/Bundle 校验 → 用户确认切换”的路径；外部文件、数据库和网络副作用不在代际恢复范围内。

可选：声明组合适用任务

合集或 Recipe 维护者可以为一个固定组合声明 1-5 个双语 useCases：

{
  "useCases": [
    {
      "id": "customize-web-interface",
      "title": "定制 Web 界面",
      "translations": { "en": "Customize the Web interface" }
    }
  ]
}

配置页只匹配这些明确声明的标题和 ID。相同任务可以对应多个组合，单个组合内不能重复任务 ID。缺少 useCases 只表示尚未声明适用任务；系统不会从项目简介、标签或 README 推断，也不会调用模型、自动创建 Recipe 或授予安装权限。这些用途只进入 Workshop/Recipe 展示 feed，不进入签名 Registry。

Release 与更新建议

每个可发布版本建议包含：

不要从分支、tag 名称或 Git 历史猜测 Release。历史版本应由作者显式提交；有问题的 Release 使用 yank/revoke，而不是删除历史事实。

项目图标、封面与截图

媒体完全可选，不影响收录。作者可以在 Author Studio 中声明固定 commit 内、相对项目根目录的图标、封面和最多 4 张截图；系统只使用这些明确声明的路径，并检查文件存在、静态图片格式和体积，不会从 README 或仓库中猜图。发现卡片依次选择封面、第一张截图和图标，紧凑图标位依次选择图标和封面；没有媒体、私有图片不可访问或加载失败时，统一退回按插件类型与分类生成的默认封面。当前支持小写扩展名的 PNG、JPEG、WebP 和 AVIF，单张不超过 2 MiB、总计不超过 8 MiB。发布新版本时，Author Studio 会带出当前路径；继续使用的图片会在新 commit 中重新核验，清空字段则移除项目媒体。

社区与竞品参考

社区 值得复用的部分 DSH Hub Workshop 的取舍
Steam Workshop 统一发现、订阅/取消订阅、合集、作者页面，以及宿主内外一致的 Workshop 入口 复用体验模型；不自建文件托管、评分和 Steam 式下载客户端
CurseForge Project、File/Release、兼容版本、Mod Loader、依赖关系和发布通道 复用严谨数据模型；Release 固定到 Git commit，不伪造下载量或历史版本
Koishi 插件模块化、生命周期/服务约定、开发与发布指南、控制台市场安装 学习低门槛开发与宿主内管理；不要求社区插件迁移到新的 Loader 或统一包仓库
VS Code Marketplace manifest、可打包制品、发布前自动检查、稳定 publisher/project 身份 学习结构化声明和自动预检；当前继续复用 GitHub 身份与 Release，不增加账号系统
GitHub 仓库、身份、Release、Issue、Discussion 和 Reaction 直接作为社区基础设施，避免自建评论、身份、文件 CDN 和审核后台
pi.dev/packages 简单、目录优先的发现体验 保留轻量搜索入口，同时补足安装能力和风险边界

采用这些参考后，最终分工仍然是：Steam 式发现体验、CurseForge 式项目/版本模型、GitHub 社区基础设施、官方 Harness 安装与生命周期、OMDSH 的审核和事务补充。

没有照搬的部分同样重要：当前不需要常驻 daemon、第二套 Loader、独立账户、评论数据库、下载 CDN、评分系统或强制 npm 发布。只有跨设备订阅确有需求时，才考虑增加只同步 Project/Release/Collection ID 的可选服务。

参考资料

提交前检查清单