CMS后端前端插件系统【免费下载链接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress项目地址https://gitcode.com/gh_mirrors/emdas/emdash点击查看免费下载导读本文是 EmDash CMS 沙箱插件sandboxed plugin发布流程的完整技术指南围绕emdash-cms/plugin-cli的注册表发布能力展开覆盖发布前元数据校验、本地手工发布、GitHub Actions 自动化委托发布、Changesets 集成以及发布验证边界。读完本文你将掌握从emdash-plugin validate到release setup的完整发布链路理解包 profile 与 release 记录如何归属 Atmosphere 账户由emdash-plugin.jsonc中的publisher指定并能在自己的插件仓库中落地可复现的发布工作流。本文对应的核心参考文档为 skills/creating-plugins/references/publishing.md同一份文档也随各模板分发包内置如 templates/marketing-cloudflare/.agents/skills/creating-plugins/references/publishing.md源码依据来自 packages/plugin-cli 的实现与测试。一、发布前置条件一份合格的包元数据在首次发布之前插件包必须满足以下硬性要求来源publishing.md 的 Required package metadata 一节emdash-cms/plugin-cli已安装到插件包中仓库当前版本为 0.11.0见 packages/plugin-cli/package.json其 bin 名为emdash-plugin一个唯一的插件slug一个 publisher DID 或 Atmosphere handlepackage.json或emdash-plugin.jsonc中声明版本号一个 license、至少一位 author、至少一个 security contact声明的 capabilities 与 allowed hosts 必须与插件实现一致一个规范的、公开的 GitHubrepo用于委托发布delegated releases。emdash-plugin.jsonc是发布的核心身份与信任契约文件。从 packages/plugin-cli/src/manifest/schema.ts 的 Zod schema 可以看到字段层面的细节约束license非空 SPDX 表达式长度不超过 256 字符例如MIT、Apache-2.0、MIT OR Apache-2.0。SPDX 语法本身的校验由注册表 aggregator 完成但 CLI 会在网络请求前先拒绝空串和纯空白值让错误更早暴露author / security支持单数与复数两种写法author/security或authors/securityContacts但同一字段不能混用两种形式。security contact 强制要求 url 与 email 至少提供一个slug 与版本由emdash-cms/plugin-types的PLUGIN_SLUG_RE、PLUGIN_VERSION_RE等规则约束长度与格式。schema 采用.strict()严格模式未知字段会被直接拒绝这能捕获licens: MIT这类拼写错误而不是让它们静默通过。同时id完整 AT URI 需要 publisher DID、type、slug、lastUpdated、artifacts.package等字段由 CLI 在发布时自动推导发布者无需手写。从 packages/plugin-cli/src/commands/validate.ts 的注释可以看出CLI 不会在validate阶段检查发布时的不变量例如 license 仅在首次发布时必需、后续发布忽略这些检查位于publishRelease中且需要网络访问。validate是快速、离线的健康检查适合接入pre-commit或 CI。二、发布前校验emdash-plugin validate在插件目录下运行pnpm exec emdash-plugin validate该命令针对 v1 schema 校验emdash-plugin.jsonc并离线解析{ file }形式的 section 引用——读取其内容并强制执行每 section 的字节/字素上限与路径逃逸防护让坏的引用在发布前就失败而不是等到 publish 时。命令退出码约定0manifest 通过 schema 校验1校验失败详细信息输出到 stderr人类可读模式或 stdoutJSON 模式2用法错误如--json组合不合法。支持--json参数输出机器可读结果成功时为{ ok: true, path, hosting }失败时为{ ok: false, error: { code, message, issues } }。validate也是所有后续发布命令的第一道关卡保证进入网络流程的是结构合法的 manifest。三、本地发布loginpublish当维护者从自己的电脑发起发布时使用本地发布流程pnpm exec emdash-plugin login alice.example.com pnpm exec emdash-plugin publish3.1 登录emdash-plugin login handle-or-did从 packages/plugin-cli/src/commands/login.ts 的实现看登录是完整的 atproto OAuth 交互流程CLI 启动一个 loopback HTTP 服务器在浏览器中打开授权服务器的授权 URL等待回调、兑换授权码并把会话持久化到凭据存储默认~/.emdash/credentials.json。登录成功后CLI 会记录 publisher 的 DID/handle/PDS供后续注册表命令识别当前发布者并打印Logged in as ...、DID 与 PDS 信息。支持--json输出{ did, handle, displayName, pds }。3.2 发布emdash-plugin publishpublish命令负责构建并校验 bundle、把产物文件上传到发布者的个人数据服务器PDS、创建包 release 记录。源码位于 packages/plugin-cli/src/commands/publish.ts几个关键行为值得注意Publisher 一致性检查发布前会校验 manifest 中固定的publisher与当前活跃会话的 DID 是否一致。DID 比较是离线的verbatim 比较只有 manifest 固定的是 handle 时才做解析因此用错账户发布会在毫秒级失败而不是在拉取完 tarball 之后构建与大小限制默认将插件打包为 gzip tarball 并上传到 PDS。压缩后的包 blob 上限为 256 KiBMAX_PACKAGE_BLOB_BYTES超出时提示改用--url外部托管publish命令在内存中缓冲 tarball 的硬上限为 384 KiBMAX_TARBALL_BYTES外部托管--url显式使用外部托管 tarball 时CLI 仍会下载该 URL必须按消费者将获取的字节计算 checksum并校验--local提供的本地副本与远程字节一致multihash 比对防止陈旧上传。--url必须是https:且主机不能是 localhost、内网地址、.local域名等非公网主机源码中有一整套 IPv4/IPv6/NAT64/6to4 私网地址检测逻辑Blob 权限检查上传 tarball 需要 OAuth 授权的blob:application/gzipscope上传 listing 图片icon/banner/screenshots需要blob:image/*。若当前授权缺少这些 scopeCLI 会提示先logout再重新登录以授予 blob 上传权限--allow-overwrite默认拒绝覆盖已存在的slug:versionrelease因为发布版本不可变aggregator 和 labeler 可能将任何变更视为下架事件。只有确定没有消费者安装该版本时才应显式启用--jsonstdout 只输出单行 JSONprofile/release URI、cid、checksum、hosting、page URL 等人类可读的进度走 stderr便于emdash-plugin publish --json | jq管道消费首次发布专用字段license、author、security contact 在首次发布时写入 profile后续发布忽略这些字段已有 profile 记录优先需要修改时使用emdash-plugin update-packagedry-run 打印 diff--yes应用。发布成功后输出使用注册表标识符publisher-handle/slug打印最终的插件页面 URL并给出跟踪命令emdash-plugin info handle slug --version version --watch在审核通过之前info读取的是 labeler 当前的检查结果不会返回未经审核的包元数据——聚合器不会返回未获批的包详情见 packages/plugin-cli/src/commands/info.ts 的printListingStatusUnapproved package details are not returned by the registry.。3.3 不发布先查看emdash-plugin bundlebundle用于在不发布的情况下检查 tarball 内容。它执行与publish相同的构建与校验管线bundlePlugin适合在提交发布前审查打包产物、核对文件清单与 manifest 内容。3.4 跟踪列表状态emdash-plugin infoinfo是只读命令无需认证。第一个位置参数可以是 handlealice.example.com走resolvePackage服务器端解析或 DID走getPackage直查。结合--watch时CLI 每 5 秒轮询一次WATCH_INTERVAL_MS最长 10 分钟WATCH_TIMEOUT_MS直到包公开、需要人工关注blocked/error/review 状态或超时。--version可以只跟踪某个具体 release 版本的检查结果。四、自动化仓库发布release setup当发布流程应跑在 GitHub Actions 中而不是维护者本地时使用自动化仓库发布。从某个插件包而非 monorepo 根目录生成共享工作流若在其他目录运行命令需传入--dir plugin-directorypnpm exec emdash-plugin release setup从 packages/plugin-cli/src/release-setup.ts 的实现看命令会准备当前已签名的包 profile并把.github/workflows/emdash-release.yml写到 Git 仓库根目录RELEASE_WORKFLOW_PATH常量如果 manifest 省略了reposetup 会检测 Git 的originremote 并预填仓库提示setup 不会 push 该文件该工作流被仓库内所有插件包共享且不需要任何 Actions secret触发方式可选auto默认检测到 Changesets 则用 changesets否则用 tags、changesets、tags、manual当仓库根目录存在.changeset/config.json时交互式 setup 会提供Follow Changesets releases选项生成的工作流接收 Changesets Action 的 published-package JSON只发布同时包含emdash-plugin.jsonc的包。Changesets 配置中的baseBranch、privatePackages等会被读取和校验无效配置会以CHANGESETS_CONFIG_INVALID拒绝。默认的发布服务地址为https://releases.emdashcms.comDEFAULT_RELEASE_SERVICE_URL工作流引用的 Action ref 默认为mainDEFAULT_RELEASE_ACTION_REF。4.1 连接 Changesets Action v2将现有 release job 的输出暴露出来并调用生成的工作流jobs: release: # Keep the existing runner, permissions, and steps. outputs: published: ${{ steps.changesets.outputs.published }} published-packages: ${{ steps.changesets.outputs[published-packages] }} publish-emdash-plugins: needs: release if: needs.release.outputs.published true uses: ./.github/workflows/emdash-release.yml with: published-packages: ${{ needs.release.outputs[published-packages] }} permissions: contents: read id-token: write attestations: write对于 Changesets Action v1改用规范化的 job 输出${{ steps.changesets.outputs.publishedPackages }}。私有仅 EmDash 包private EmDash-only packages要求同时设置privatePackages.version: true与privatePackages.tag: true并把无关的私有包加入ignore。4.2 不使用 Changesetstag 触发不使用 Changesets 时生成的工作流以slugversion形式发布 taggit tag gallery1.2.3 git push origin gallery1.2.34.3 工作流内部机制release prepare工作流通过生成它的那个精确版本的插件 CLI 运行release prepare。该命令恰好找到一个 slug 与 tag 匹配的emdash-plugin.jsonc要求 manifest 中的版本与 tag 版本一致构建该包并为其 provenanceSigstore与 release Actions 写出输出重复 slug、缺少包、版本不匹配都会在 attestation见证之前停止。因此发布者只需 push tag工作流会自动完成构建、签名与发布全程无需维护者本地环境。五、GitHub OIDC 与发布审批第一次运行会使用 GitHub OpenID Connect 请求建立仓库连接repository connection。服务端会先检查发起包的已签名 profile 是否指向同一个仓库确认后才创建请求。发布者在 release dashboard 中批准以下范围仓库repository工作流文件workflow fileref 范围ref scope环境environment。手动运行在首次使用某个分支时会请求审批确认后会添加该范围而不会移除已批准的 tag 或分支。后续的包只有在已签名 profile 指向该仓库时才能复用已批准的仓库范围。由旧版工作流创建的包级package-scoped批准会保持包级直到某个未匹配的包或 ref 被显式批准为仓库连接。发布确认仍是包级别的escalation-only策略在声明访问权限提升时需要审批always策略则对每次发布都要求审批。从 packages/plugin-cli/src/commands/release.ts 可以看到emdash-plugin release下完整的子命令家族approve、reject、delegate、revoke、workload、enrol、submit、dry-run、plan、prepare、setup、status、cancel。其中submit从 GitHub Actions OIDC 提交委托发布支持--no-wait、--wait-for-approval、--poll-interval-seconds、--timeout-minutes等参数dry-run验证委托发布准入但不创建 intentstatus/cancel读取或取消未发布的委托发布 intent。六、发布第二个包profile setup与多包工作流在不改动工作流的前提下准备另一个包Changesets 用户把它加入 changesettag 用户 push 它的 tagpnpm exec emdash-plugin profile setup --dir packages/comments git tag comments1.0.0 git push origin comments1.0.0profile setup确认 profile 已发布后会打印两条后续命令手动发布用emdash-plugin publishGitHub Actions 用emdash-plugin release setup。这意味着同一个仓库可以承载多个插件包共享同一份emdash-release.yml工作流每个包通过自己的 tag或 changeset独立触发发布。七、验证边界发布服务核验什么发布服务release service在接收产物前会验证以下全部维度来源publishing.md 的 Verification boundaries 一节GitHub 仓库与 owner ID工作流workflow、ref、环境environmentcommit、run、runner包 profilebundle 校验和checksummanifest 身份identity声明的访问权限declared access原始 Sigstore provenance。只有仓库工作流与已签名包 profile 都授权该 run 之后服务才会接受产物。值得强调的设计是元数据审核与发布验证是分离的。注册表审核registry moderation覆盖展示给用户的包元数据与媒体安装installation独立验证 release 记录、bundle 校验和与声明访问权限发布服务验证的是供应链与身份链路OIDC、Sigstore、profile 签名。因此一个插件即使通过了发布验证其 listing 元数据仍可能处于 labeler 审核中不会立刻出现在公开注册表而消费者安装时又会独立做一遍校验形成多层防线。八、从发布文档到更深的仓库以上内容以 skills/creating-plugins/references/publishing.md 为骨架CLI 源码为佐证。若想继续深入仓库内还有这些直接相关的资源插件开发总览skills/creating-plugins/SKILL.mdcapabilities 声明表、沙箱边界、测试宿主等CLI 包定义与 bin 映射packages/plugin-cli/package.json发布命令实现packages/plugin-cli/src/commands/publish.ts、packages/plugin-cli/src/commands/validate.ts、packages/plugin-cli/src/commands/login.ts、packages/plugin-cli/src/commands/info.ts工作流生成与 Changesets 检测packages/plugin-cli/src/release-setup.ts、packages/plugin-cli/src/release-prepare.ts委托发布服务的技术规格docs/technical-specs/delegated-release-service.md、docs/technical-specs/delegated-release-service-operations.md、docs/technical-specs/delegated-release-service-implementation-plan.md、docs/technical-specs/delegated-release-service-g0-conformance.md发布服务实现apps/release-service。最后提醒两点发布实践一是所有关键校验manifest 合法性、版本一致性、URL 公网可达性、blob scope、发布者身份匹配都在 CLI 本地尽早失败发布命令是幂等与可审计的--json输出可直接被 CI 消费二是版本不可变与多层验证意味着发布即承诺——首次发布前务必用validate和bundle检查用info --watch跟踪审核状态让每次发布都在受控、可追溯的路径上完成。赞分享CMS后端前端插件系统【免费下载链接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress项目地址https://gitcode.com/gh_mirrors/emdas/emdash点击查看免费下载相关推荐EmDash 沙箱插件发布指南从 emdash-plugin.jsonc 校验到 GitHub Actions 委托发布EmDash 沙箱插件发布指南从 emdash plugin.jsonc 校验到 GitHub Actions 委托发布 本文面向 EmDash基于 AstCMS后端前端插件系统EmDash 沙箱插件发布实战从本地 publish 到 GitHub Actions 自动化委托发布EmDash 沙箱插件发布实战从本地 publish 到 GitHub Actions 自动化委托发布 本篇技术指南完整讲解 EmDash基于 AstroCMS后端前端插件系统EmDash 插件发布实战从 emdash-plugin CLI 校验到 GitHub 委托发布的完整指南EmDash 插件发布实战从 emdash plugin CLI 校验到 GitHub 委托发布的完整指南 EmDash 是一个基于 Astro 的全栈 TyCMS后端前端插件系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考