openclaw-weixin

简体中文

English

简体中文

English

主题

贡献指南 ​

English

本仓库是 Tencent/openclaw-weixin 的社区维护发行版。除非经批准实施独立规划的破坏性迁移，贡献必须保留 openclaw-weixin 插件/channel ID 及其现有配置和状态路径。

前置条件 ​

  • Node.js 24.16.0
  • npm

请使用 .nvmrc 中指定的 Node.js 版本作为推荐开发环境。发布的包支持 Node.js >=22.22.3，包括 Node.js 24 和 26。CI 会验证 Node.js 22.22.3 的精确下限、推荐的 Node.js 24.16.0 环境，以及当前 Node.js 26 运行时。

OpenClaw 兼容矩阵 ​

最低支持宿主仍为 2026.6.1，锁文件 SDK 和构建元数据固定为 2026.9.4。CI 使用 以下明确组合，不对所有宿主、Node.js 版本和操作系统做全排列：

OpenClaw 目标Node.js运行平台验证方式
2026.6.1（最低宿主）24.15.0Ubuntu兼容性
2026.7.1（旧版宿主）22.22.3Ubuntu兼容性
2026.8.2（旧版 SDK）24.15.0Ubuntu、Windows兼容性
2026.9.1（9 月首个稳定版）24.15.0Ubuntu兼容性
2026.9.2（旧版 SDK / Node.js 22 下限）22.22.3Ubuntu兼容性
2026.9.4（锁文件 SDK）24.16.0Ubuntu、Windows完整
2026.9.4（当前运行时）26Ubuntu兼容性
beta（浮动 npm dist-tag）24（当前补丁版）Ubuntu兼容性

完整验证运行 npm run check，Ubuntu 作业还运行 npm run pack:check 和 npm run audit:all。兼容性验证在不修改锁文件的前提下安装目标宿主，对固定目标 断言实际安装的精确版本，再使用该宿主运行 npm run typecheck 和 npm run build。

依赖安装使用 Node.js 24.16.0（beta 使用 24.x 当前补丁版），随后再切换到矩阵列出的 运行时。OpenClaw 2026.9.4 要求 Node.js >=24.16.0 <25 || >=26.1.0，因此 Node.js 22 作业保留旧版宿主；插件自身的 Node.js 22.22.3 下限不变。

两种方式都会在全新进程中对刚构建的插件运行 node scripts/check-host-compatibility.mjs，覆盖真实 SDK 导入、插件/channel 注册、 typing 回调、配置变更以及渠道 ID/别名解析。独立的 node scripts/check-plugin-install-update.mjs 验证的是仓库已发布的包，而非当前源码。

beta 作业跟随 Node.js 24 的当前补丁版本，以适应新宿主提高运行时下限；仅该作业启用 setup-node 的 check-latest 查询，避免复用 runner 缓存中的旧补丁。固定宿主作业仍 保留各自明确的 Node.js 版本。

CI 会记录 beta 实际解析到的精确版本。该标签可能指向稳定版，也可能落后于最新稳定版， 因此不能替代固定的 2026.9.1、2026.9.2 和 2026.9.4 作业。此矩阵描述 CI 覆盖范围，不代表 所有未来 2026.9.x 版本或未列出的平台组合均已验证，也不能替代人工整体验证。

选择贡献路径 ​

报告 Bug ​

提交前先搜索现有 issue，然后使用 Bug Report 表单。请提供受影响的插件、OpenClaw、Node.js 和平台版本，最后正常工作的版本组合（未知或 从未正常工作时写 未知 / 从未正常工作）、最小复现步骤、预期与实际结果，以及脱敏后的 关键诊断信息。

关键诊断可以保留事件名、白名单内的错误码或状态码、计数、大小、耗时、重试次数和版本。 提交前必须移除 token、context token、账号或用户标识、消息正文、二维码数据、URL 查询 参数、原始文件系统路径、任意错误文本和堆栈。自动化客户端也必须在本地按相同字段和规则 完成脱敏；不得附加原始日志、配置或状态文件。

疑似安全漏洞必须通过 GitHub 私密漏洞报告 提交，不得创建公开 issue。

修复 Bug ​

优先选择已经分诊且具有可观察测试判据的 issue。仓库委派的 Bug 修复必须带有 agent:ready 标签；maintainer-only 任务不得委派。按照 AGENTS.md 和架构指南 工作，先复现原始故障，再同时添加定向回归测试和反例。

兼容性修复必须保留旧版受支持行为和当前行为的测试用例。涉及 OpenClaw API 边界时，应 覆盖最低支持宿主、lockfile/当前宿主，并在相关时覆盖浮动 beta。状态格式改动必须分别覆盖 旧状态迁移和当前格式写入。不得为了让新版本通过而删除或弱化旧版本测试。

提议或实现新功能 ​

推荐先提交 Feature Request， 但这不是强制前置条件。范围明确的小型功能在使用场景、验收标准、非目标和替代方案清楚时 可以直接提交 PR；较大、高风险或影响兼容性的改动应在实现前先与维护者确认范围。

开发 ​

安装 lockfile 中记录的精确依赖版本：

shell
npm ci

请阅读 AGENTS.md 和架构指南，了解仓库约束、 生命周期和数据流。无论改动是手动编写还是借助编码 Agent 完成，都必须遵守这些规则。

迭代时运行一个受影响的测试套件：

shell
npm run test:unit -- src/path/to/file.test.ts

运行快速的类型检查、样式检查和单元测试验证流程：

shell
npm run check:fast

运行与 CI 相同的格式化、lint、类型检查、覆盖率测试和构建：

shell
npm run check

以与 CI 和发布相同的严重性阈值审计插件随附的生产依赖。开发工具以及由宿主提供的 OpenClaw peer dependency 会被排除：

shell
npm run audit:deps

使用以下命令应用仓库格式：

shell
npm run format

修改入口点、构建输出或包元数据时，检查 npm 包内容：

shell
npm pack --dry-run --ignore-scripts

仓库更严格的包契约检查为：

shell
npm run pack:check

Registry 包检查 ​

执行 npm run check 和 npm run pack:check 后，创建一个源 tarball，并在仓库外派生两个 registry 包：

shell
npm pack --ignore-scripts --pack-destination <source-output>
node scripts/prepare-npm-package.mjs <source-output> <npm-output>
node scripts/prepare-clawhub-package.mjs <source-output> <clawhub-output>
mkdir <clawpack-root>
tar -xzf <clawhub-output>/openclaw-wechat-<version>.tgz -C <clawpack-root>

源 README 的直接命令先列 ClawHub。npm 转换器只将直接命令顺序改为 npm-first， 所有 registry 均保留同一安装提示词：已装沿原来源更新到最新版，新装优先 ClawHub、 npm 兜底。ClawHub 转换器保留直接命令顺序，将暂存标题和包元数据改为 openclaw-wechat，并使用英文主 README。两个转换器都不改变 openclaw-weixin 插件和 channel ID。

使用固定版本的 ClawHub 验证器，并将其报告目录置于检出目录外；随后在不提供凭据的情况下预览发布：

shell
npx --yes clawhub@0.23.3 package validate <clawpack-root>/package \
  --out <report-output> --openclaw-version 2026.9.4 --json
npx --yes clawhub@0.23.3 package publish \
  <clawhub-output>/openclaw-wechat-<version>.tgz \
  --family code-plugin --owner newfuture --display-name WeChat \
  --categories channels --topics wechat,weixin,messaging \
  --source-repo NewFuture/openclaw-weixin --source-commit <commit-sha> \
  --source-ref <git-ref> --dry-run --json

这些命令验证的是下一个候选版本；它们不会发布或修改现有的公开 ClawHub 发行版。 .github/workflows/clawhub-publish.yml 仅针对 pull request 执行这种无需凭据的验证。 生产 npmjs、ClawHub 和 GitHub Packages 发布会从精确的 release tag 并行启动； GitHub Release 的收尾工作会等待三个作业全部完成。npmjs 和 ClawHub 分别使用受保护的 npm-publish 和 clawhub-publish 作业。两个目标都缺失时，等待两个环境均进入 Pending，在 Review deployments 中同时选择二者，然后只点击一次 Approve and deploy；UI 操作是共享的，但 OIDC 信任仍然相互隔离。各作业以成功的 发布响应为完成依据，不会在写入 registry 后立即回读确认。不要向 pull-request 工作流 添加生产发布调度、id-token: write 或长期有效的 registry 凭据。在真正的 ClawHub 命令启动前，release 工作流会持久化一个 check run，以及一个由 tag 和 commit 精确 限定、保留 90 天的 Actions artifact。ClawHub 独立于 npmjs 上传并存储自己的 ClawPack；显式 clawhub: 安装器会直接下载该 artifact。在任一发布边界之后发起新的 ClawHub 请求时，必须具备可核验的权威尝试记录和明确的恢复授权。

npmjs 和 GitHub Packages 无需保持无缺口的发布历史。当精确的当前目标不存在且 registry latest 更低时，其发布检查允许存在一个尚未发布的中间仓库版本。GitHub Packages 还会在发布前立即重新检查精确目标和 latest。绝不可移动不可变的跳过 tag 来填补 registry 缺口；应准备并发布下一个版本。

编辑 Markdown 文档或 docs/site/ 中的文件后，将文档网站构建到 docs/site/dist/（与 GitHub Pages 运行的命令相同）。该站点是一个 VitePress 项目，拥有自己的依赖，以保持已发布的包 manifest 不受影响；其测试使用 Node.js 运行，而不是根目录的 Vitest 项目：

shell
npm ci --prefix docs/site
npm test --prefix docs/site
npm run build --prefix docs/site

使用 npm run dev --prefix docs/site 通过热重载预览站点，或使用任意静态文件服务器 提供 docs/site/dist/。两个命令都会先将仓库 Markdown 复制到 docs/site/content/，因此务必编辑原始文档。生成的 content/ 和 dist/ 目录被 Git 忽略；在 docs/site/ 内只提交源文件。

简体中文是网站默认语言，发布在站点根路径；英文发布在 /en/ 下。没有翻译的文档仍会在 每种语言中发布，保留现有语言的 Markdown 内容并附上未翻译提示，因此应在 docs/site/.vitepress/docs.mjs 中按已存在的语言源注册新页面。

Agent 辅助工作 ​

对于仓库维护者可能委派的工作，请使用 AI-ready Implementation Task issue 表单明确 范围和可观察测试判据。agent:ready 表示任务可以委派；risk:privileged 标记鉴权、 持久状态、工作流、发布、安全或包/插件元数据；maintainer-only 表示不得委派实现。 仓库委派任务产生的 PR 必须关联该任务，并说明可观察结果、定向判据、最高风险和剩余 不确定性。不得向 Agent 提供微信凭据，也不得让其访问真实后端。

.github/workflows/copilot-setup-steps.yml 使用 npm ci 准备标准 Node.js 24.16.0 环境，但不能替代定向测试或 npm run check。

维护报告预览 ​

.github/workflows/maintenance-report.md 定义仅面向 main 的手动 gh-aw 报告， 使用 Copilot CLI 以中文总结最近七天默认分支的变更和已合并 PR。输出仅以 staged 模式预览在 Actions step summary 中，不创建 issue 或 PR、不修改标签、不重跑工作流， 也不执行发布；不读取原始 CI 日志或用户状态。 GitHub 工具使用显式白名单，仅允许读取提交、读取文件、列出提交和搜索 PR；不授权 agent 调用评论、仓库搜索或 star 接口。

首次运行前，维护者需在仓库 Actions secret 中配置 COPILOT_GITHUB_TOKEN： 使用具有 Copilot 推理权限的个人账号创建 fine-grained token，授予账号级 Copilot Requests: Read。不得提供微信凭据，也无需为报告开启 Actions 创建 PR 权限。staged 模式仍消耗推理额度：主 agent 预算为 100 AIC，最多 20 轮， 执行 step 超时为 10 分钟；威胁检测另有 50 AIC 预算。这些是用量限制，不是账单保证。

使用固定版本编译器，并同时提交源文件和生成的锁文件：

shell
gh extension install github/gh-aw --pin v0.88.2
gh aw compile maintenance-report --strict --validate

工作流文件合入 main 后，通过 gh aw run maintenance-report --ref main 手动运行并查看 Actions 摘要。可用 gh aw disable maintenance-report 停用， 并检查是否仍有排队或运行中的任务。当前没有定时运行或自动实施阶段。

整机实测 ​

自动化测试不得调用真实微信后端、执行二维码登录或使用开发者的 OpenClaw 状态。改变运行时 行为的 PR 必须在 PR 模板中另行记录由人工完成的整机实测：

  • 操作系统和架构、Node.js、OpenClaw，以及插件版本或 commit；
  • 安装方式和每个测试场景；
  • 预期结果与实际结果；
  • 符合上述报告规则的脱敏关键诊断。

整机实测应使用隔离的非生产测试账号。不得在 PR 中包含凭据、二维码数据、账号标识或私聊 内容。实测结果只证明列出的环境和场景，不能替代自动化回归测试。Agent 可以先创建将本节 标为 等待人工实测 的 draft PR，但在人工补充结果前不得进入可合并状态。不影响运行时 行为的改动可以填写 不适用，但必须说明无需运行时实测的原因。

Pull request 要求 ​

  • 保持改动聚焦，并为行为变更加入测试。
  • 列出完整的受影响测试矩阵：原始故障、反例，以及每个受影响的互斥分支、错误出口和持久化 边界。
  • 兼容性修复必须保留旧版本和当前版本测试，并记录实际运行的兼容性组合。
  • 运行时行为改动必须包含上述整机实测结果。
  • 为面向用户的文档更新 README.md 和 README_EN.md。
  • 当改动影响用户时，更新两份 changelog。仅文档改动无需 changelog 条目。
  • 从测试、日志、截图和 issue 描述中移除凭据、账号标识符、二维码和私信内容。
  • Pull request 会接受 Copilot code review，并且必须解决审阅线程。规则集不要求人工批准； 最终合并决定仍由维护者负责。
  • PR 达到可合并状态前必须通过 npm run check，以及受影响区域要求的所有额外验证。
  • 审阅并对提交的所有改动负责，包括由 AI 协助完成的改动。