QoderWake开源社区脚本插件提交新手全攻略：从零开始到官方市场发布
向QoderWake官方市场提交自研脚本或插件，并非填写表单那般简单。平台对可复用性、安全性及标准化设有严格门槛，必须依次跨过五道关卡，缺一不可。许多开发者提交受阻，往往源于遗漏了其中某一环节。以下逐条拆解五个步骤，明确每一步的具体执行要点。
一、确认脚本/插件满足基础收录标准
QoderWake官方市场收录插件，核心要求是可复用、可验证且依赖最小化。所有提交内容需通过自动化校验与人工抽检双重审核。不符合条件者直接拒收，无协商空间。
1、脚本必须是独立的可执行文件，能够通过qoderwake run或qoder-cli exec直接调用，不得依赖用户本地未声明的全局环境变量。简言之，即拿即用，无需用户额外配置。
2、插件包内必须包含标准的元数据文件qoderwake-manifest.json，其中name、version、event_type、required_permissions与entrypoint字段不可缺失。
3、所有代码需托管在公开的GitHub仓库中，主分支根目录下须包含README.md（涵盖功能说明、触发示例、权限描述）及LICENSE文件。许可证仅接受MIT、Apache-2.0、BSD-3-Clause三种。
4、代码中严禁出现硬编码凭证、未经沙箱隔离的系统级命令（例如rm -rf /、chmod 777等），亦不得调用未签名的二进制下载链接。一经发现，将触发永久性提交资格冻结，后果严重。
二、完成NPM包发布与语义化版本标记
QoderWake市场仅认可NPM作为分发源。所有插件必须以@qoderwake/xxx或@your-org/xxx的命名空间发布，并通过openclaw plugins install兼容协议验证。
1、在项目根目录执行npm init，name字段须以@qoderwake/开头（例如@qoderwake/db-backup），main指向入口文件，bin字段需映射CLI可执行名称（如"qw-db-backup": "./dist/index.js"）。
2、通过npm version patch生成符合SemVer规范的版本号，例如v1.0.1。注意，prerelease标签（如1.0.0-beta.1）被禁用，不可使用。
3、登录NPM账户后执行npm publish --access public。发布成功后，前往https://www.npmjs.com/package/你的包名确认页面可公开访问，同时检查files字段是否遗漏dist/或bin/目录。
三、提交GitHub PR至QoderWake官方收录清单仓库
官方市场的清单由qoderwake/community-plugins仓库中的registry.json文件驱动。新增条目必须通过Pull Request提交，由Maintainer团队进行合并前的安全扫描。这是整个流程中最关键的环节。
1、Fork仓库https://github.com/qoderwake/community-plugins，然后克隆至本地。
2、编辑registry.json文件，在plugins数组末尾添加新对象。字段包括：id（与NPM包名一致）、name（中文显示名）、description（50字内的功能摘要）、repo（GitHub仓库URL）、npm（NPM包URL）、author（作者GitHub ID）、verified（初始值设为false）。
3、提交PR时，标题格式须规范：[plugin] add @qoderwake/db-backup v1.0.1。正文中必须附带CI验证链接（来自qoderwake-ci自动检查结果），以及最小可行的测试命令示例。
4、Maintainer收到PR后，会运行qoderwake verify --package @qoderwake/db-backup。若返回✅ Verified: signature OK, sandbox pass, no high-risk ops，即代表验证通过，随后标记verified: true并合并至主干。
四、配置CI自动化签名与沙箱验证
所有新插件在收录前，必须通过QoderWake官方CI流水线的签名认证。此过程会生成一个不可篡改的.sig签名文件，并注入NPM包，用于运行时的完整性校验。简单说，即为插件加装“官方认证锁”。
1、在插件仓库根目录下添加.qoderwake.yml文件，声明构建任务：指定Node.js版本，启用sign: true，设置test_command: "npm run test"（测试必须存在且通过）。
2、推送.qoderwake.yml后，GitHub Actions会自动触发qoderwake-ci/sign工作流，生成dist/index.js.sig并上传至对应版本的NPM包中。
3、验证签名有效性：在任意环境执行qoderwake verify --local ./node_modules/@qoderwake/db-backup/dist/index.js，若输出Signature valid, issuer: qoderwake-root-ca-v2，则签名通过。
4、若签名失败，CI日志中会明确提示缺失SECURITY_CONTACT邮箱，或NOTARY_KEY_ID未在qoderwake-keys密钥环中注册。此时需立即补全并重新推送，无需犹豫。
五、设置权限声明与最小作用域执行策略
QoderWake运行时强制实施基于required_permissions的沙箱降权机制。插件必须明确声明所需能力，否则在未授权环境中会被静默拒绝执行。这也是许多插件审核被卡住的原因。
1、在qoderwake-manifest.json中定义required_permissions数组，仅允许以下值："fs:read"、"fs:write"、"network:outbound"、"env:read"、"process:exec"。多则无效，少则错误。
2、若插件需写入/backup/目录，必须声明"fs:write"。且代码中所有fs.writeFileSync的路径，都必须以path.join(qoderwake.env.WORKSPACE, "backup")为基点，严禁使用绝对路径。此举旨在将写入范围严格限定在工作区内。
3、调用child_process.exec之前，必须先通过qoderwake.runtime.allowCommand("tar", ["-czf"])白名单注册。未注册的命令将直接触发RuntimePermissionDeniedError异常，运行时立即报错。
4、在README.md的显眼位置注明权限用途。例如：“本插件申请fs:write仅用于将导出文件保存至用户配置的工作区路径，不涉及系统关键目录。”清晰说明既能帮助用户理解，也体现开发者的专业与坦诚。