企业官网建设流程全解析

• 人工智能
• AI Agent
• 即时通讯
• 后端
• 本地部署
• 语音

本指南以 extensions/feishu/PUBLISHING.md 为主线，完整讲解如何将 openclaw-cn 仓库中的飞书频道插件@openclaw-cn/feishu作为独立 npm 包发布。内容覆盖发布前的准备与构建、语义化版本管理、npm 发布命令、CHANGELOG 维护、发布后验证，并结合仓库源码深入剖析 Workspace 模式与 NPM 模式双轨并行的加载原理。读完本文，你将掌握一套可直接复制的 npm 插件发布流程，并理解插件在开发环境与用户安装环境之间的行为差异。

一、为什么要把 feishu 插件独立发布

在 openclaw-cn 仓库中，extensions/feishu/目录承载了飞书（Larksuite）频道插件的完整实现：既有index.ts插件入口，也有src/下的 48 个业务模块（渠道接入、文档、表格、多维表格、日历、任务、Wiki、权限等工具集）。它面临两种截然不同的使用场景：

• Workspace 模式（开发环境）：插件直接以 TypeScript 源码形式存在于仓库中，供本地开发、联调与测试；
• NPM 模式（用户安装）：通过npx openclaw-cn plugins install @openclaw-cn/feishu或npm install @openclaw-cn/feishu独立安装，用户在任意基于 openclaw / openclaw-cn 的环境中使用。

将插件作为独立 npm 包发布，意味着用户无需克隆整个仓库、无需接触源码即可获得与仓库内版本一致的功能；而仓库维护者则需要保证同一份源码在"源码即时运行"与"预编译产物运行"两种模式下行为一致。这正是PUBLISHING.md所称的"双模式兼容性"（dual-mode compatibility）。

二、发布前的准备工作

2.1 环境要求

• 使用pnpm作为包管理器（仓库根 package.json 声明"packageManager": "pnpm@10.23.0"，Node 要求>=22.12.0）；
• 已安装 npm CLI 并拥有可发布的 npm 账户；
• 在仓库根目录执行pnpm install，确保依赖（@larksuiteoapi/node-sdk、@sinclair/typebox、zod）就绪。

2.2 理解 package.json 的发布相关字段

发布行为完全由 extensions/feishu/package.json 决定，发布前务必理解以下关键字段：

其中files白名单与根 package.json 的"!extensions/feishu/**"排除规则、extensions/feishu/.npmignore 共同决定：发布时只携带插件清单、说明文档与dist/编译产物，tsconfig.json、测试文件、源码等一律不进入 tarball，从而保证包体积精简且无源码污染。

2.3 清理与编译

在extensions/feishu目录内依次执行：

# 进入扩展目录 cd extensions/feishu # 清理旧构建（等价于 rm -rf dist，见 package.json 的 scripts.clean） pnpm clean # 编译为 dist/（等价于 tsc，见 scripts.build） pnpm build # 验证编译产物 ls -la dist/

scripts.build直接调用tsc，由 extensions/feishu/tsconfig.json 控制编译行为：

• outDir: ./dist、rootDir: .：以index.ts为根编译，产物输出到dist/；
• declaration: true、declarationMap: true、sourceMap: true：同时生成.d.ts类型声明与源码映射；
• module: ES2022、moduleResolution: bundler：与包的 ESM 格式匹配；
• include: ["index.ts", "src/**/*.ts"]，exclude: ["**/*.test.ts"]：只编译正式源码，跳过测试。

2.4 验证编译产物

构建成功后应看到（与PUBLISHING.md的期望一致）：

• dist/index.js—— 编译后的 JavaScript 入口；
• dist/index.d.ts—— TypeScript 类型声明；
• dist/src/—— 源码编译后的模块版本（channel.js、client.js、docx.js、drive.js等，对应index.ts中注册的九大工具模块）；
• .d.ts.map/.js.map—— 源码映射文件，便于调试与 IDE 跳转。

三、版本管理

3.1 语义化版本规则

编辑 extensions/feishu/package.json 中的version字段。版本号遵循语义化版本规范：

• 主版本号（major）：不兼容的 API 变更，例如渠道接口签名重构、配置 Schema 破坏性调整；
• 次版本号（minor）：向后兼容的功能新增，例如新增文档/表格工具模块；
• 修订号（patch）：向后兼容的问题修复。

示例：

{ "version": "2026.2.1" }

3.2 与主仓库版本对齐：plugins:sync

从源码结构看，仓库还提供了版本同步机制：根 package.json 的plugins:sync脚本指向 scripts/sync-plugin-versions.ts，该脚本会遍历extensions/*/package.json，将所有扩展包版本号同步为主仓库版本，并自动在扩展的CHANGELOG.md顶部补写版本条目。在发布 feishu 扩展时，可先通过该脚本让扩展版本与主仓库保持一致，再按需调整，避免版本散落不一致。

四、发布到 npm

4.1 前置要求

# 已安装 npm CLI # 已登录 npm 账户 npm login

4.2 发布命令

# 验证登录状态 npm whoami # 发布到 npm 公开仓库（@openclaw-cn 为 scoped 包，必须显式声明 public 访问级别） npm publish --access public # 如果账户启用了两步验证（OTP），追加一次性验证码 npm publish --otp=YOUR_OTP_CODE

说明：--access public与package.json中publishConfig.access: "public"作用等价，二者同时配置可双保险；--otp用于 2FA 环境，OTP 码可通过认证器应用获取。

4.3 发布检查

# 验证发布成功，输出最新版本号 npm view @openclaw-cn/feishu version # 查看包完整信息（描述、版本、dist-tags、依赖等） npm info @openclaw-cn/feishu # 在干净目录中下载并测试安装 npm install @openclaw-cn/feishu

五、更新 CHANGELOG

发布完成后，在项目根目录的 CHANGELOG.md 顶部按以下格式追加条目（保持版本降序排列，与现有## 0.2.0、## 0.1.9等条目风格一致）：

## v2026.2.1 ### 新增 - Feishu 扩展作为独立 npm 包发布 (@openclaw-cn/feishu@2026.2.1) ### 修复 - [列出修复内容]

CHANGELOG 是用户判断是否升级的重要依据，破坏性变更必须在此处明确标注迁移路径。仓库根 CHANGELOG.md 的既有条目可作为格式范本。

六、发布后验证

发布不是终点，以下三项验证可确保包在真实用户环境中可用：

# 1. 检查 npm 包是否可安装（在干净的临时目录执行） npm install @openclaw-cn/feishu # 2. 验证类型检查（基于 dist/index.d.ts 与 package 内类型声明） npx tsc --noEmit # 3. 测试运行时加载（在 openclaw-cn 项目中确认插件被识别） openclaw-cn plugins list

其中第 3 步与仓库的 CLI 插件管理能力对应：openclaw-cn plugins list会列出已发现与已加载的插件；openclaw-cn plugins install @openclaw-cn/feishu可用于从 npm 安装；openclaw-cn plugins doctor可诊断加载失败原因（详见 docs/cli/plugins.md）。若插件列表中出现feishu且状态为loaded，说明发布内容可被运行时正确识别。

七、双模式兼容性深入：源码运行与预编译运行

PUBLISHING.md的核心技术要点是"双模式兼容性"，理解它需要结合插件加载器的实现。

7.1 Workspace 模式（开发环境）

• 使用 TypeScript 源码（index.ts）；
• 通过jiti在运行时即时编译；
• 适合本地开发与快速迭代。

仓库 src/plugins/loader.ts 给出了底层依据：插件加载器创建 jiti 实例时extensions覆盖了.ts/.tsx/.mjs/.js等类型，cache在开发环境（NODE_ENV !== "development"时关闭缓存）被禁用，确保源码改动即时生效；同时通过alias将openclaw/plugin-sdk、openclaw-cn/plugin-sdk等别名指向仓库内 SDK 目录，保证工作区内插件能解析到同一份 plugin-sdk 类型与实现。

7.2 NPM 模式（用户安装）

• 使用预编译的 JavaScript（dist/index.js）；
• 携带类型声明文件（dist/index.d.ts）；
• 适合独立使用。

该模式由package.json的main/types/exports字段驱动，加载器无需编译即可import插件入口。从源码结构看，loader.ts在候选插件source文件存在时通过jiti(candidate.source)加载（src/plugins/loader.ts），npm 安装后的路径指向dist/index.js，走的是"读取预编译产物"的快速路径。

7.3 类型映射

feishu 包在src/下提供plugin-sdk.d.ts（extensions/feishu/src/plugin-sdk.d.ts），声明了ClawdbotPluginApi、PluginRuntime、ChannelPlugin等接口与emptyPluginConfigSchema等函数，确保 TypeScript 用户在两种模式下都能获得完整类型提示。该声明同时兼容上游openclaw与openclaw-cn两种宿主，与 extensions/feishu/index.ts 中"同时支持 openclaw（上游）与 openclaw-cn（中文分支）"的注释相互印证。

7.4 双模式行为一致性

从源码看，插件入口 extensions/feishu/index.ts 无论以何种模式加载，都执行同一套注册逻辑：调用api.registerChannel注册渠道插件、注册九个工具模块（文档docx、云文档drive、Wiki、权限perm、多维表格bitable、即时消息im、任务task、日历calendar、表格sheets），每个模块的注册失败会被捕获并记录日志，不影响其余模块。这意味着"同一份注册代码，两种加载路径"，只要dist/由当前源码编译而来，两种模式的渠道能力与工具集就是一致的。

八、常见问题（Q&A）

Q: 如何处理破坏性变更？

A: 发布为新的主版本号（如2.0.0），并在 CHANGELOG 中清楚标注变更内容与迁移说明。语义化版本的主版本号递增即用于标识此类不兼容变更。

Q: 如何取消已发布的版本？

A: 在发布 72 小时内，可使用：

npm unpublish @openclaw-cn/feishu@VERSION

注意：npm unpublish仅限 72 小时窗口，且可能导致用户依赖损坏，应谨慎使用；超过窗口需联系 npm 支持处理。

Q: 如何发布预发布版本（beta）？

A: 发布时使用预发布标签：

npm publish --tag beta # 用户安装 beta 版本 npm install @openclaw-cn/feishu@beta

使用--tag可以维持latest标签指向稳定版，避免用户默认安装到未稳定的预发布版本。

Q: 如何同时更新 GitHub 和 npm？

A: 按顺序执行：

1. 在 GitHub 上创建 Release（标记版本，对应docs/reference/RELEASING.md中"Tag and push"的流程）；
2. npm publish发布到 npm 仓库；
3. 更新 CHANGELOG。

从仓库的发布实践看（docs/reference/RELEASING.md），完整流程还包括git tag vX.Y.Z && git push origin vX.Y.Z打标签，并在 Release 正文附带完整 changelog 片段。

九、发布清单速查

extensions/feishu/PUBLISH_CHECKLIST.md 提供了发布全流程的快速参考，可将其作为每次发布的 SOP：

预检

• 版本号已更新（package.json）
• CHANGELOG 已更新（GitHub）
• 所有测试通过（pnpm test）
• 代码已提交到 main 分支

构建 & 发布

# 1️⃣ 编译 cd extensions/feishu pnpm clean && pnpm build # 2️⃣ 验证编译产物 ls dist/index.js dist/index.d.ts # 3️⃣ 发布 npm publish # 4️⃣ 验证 npm view @openclaw-cn/feishu version

发布后

• 在 GitHub 创建 Release（标记版本）
• 更新项目 README 中的版本号
• 通知用户新版本发布

故障排除

十、相关文档

• 主仓库发布指南：docs/reference/RELEASING.md
• CHANGELOG 维护规范：CONTRIBUTING.md
• 插件 CLI 管理命令：docs/cli/plugins.md
• 飞书渠道使用与配置：docs/channels/feishu.md
• 飞书插件源码与配置：extensions/feishu/README.md

• 人工智能
• AI Agent
• 即时通讯
• 后端
• 本地部署
• 语音