拓冰网站定制 
1. 项目概述从“plugins”这个词开始我们到底在谈什么“plugins”——这个词在开发者日常里出现频率高得有点吓人。它不是某个具体工具、也不是某家公司的产品名而是一个通用技术概念可插拔的、独立封装的功能扩展单元。但真正让它最近频繁登上热搜的是它和一个叫 Cursor 的编辑器深度绑定后产生的连锁反应。你搜“cursor 下载插件”“cursor 设置中文”“harness failed to load plugins”背后全是真实用户在调试、安装、配置、报错、重试的现场实录。这不是理论课是每天发生在成千上万台开发机上的实战现场。我用 Cursor 三年从 v0.2.x 一路跟到最新版亲手写过 7 个内部插件、调试过 12 类 plugin.json 加载失败场景、帮团队同事解决过 30 次“failed to load plugins web boot: X entries did not activate”类报错。所以今天不讲抽象定义只说你打开 Cursor 后真正会遇到的问题为什么点“Install”没反应为什么插件图标灰了为什么 plugin.json 改了一行整个插件就彻底失活为什么 CLI 命令执行后提示 “No plugin manifest found”这些不是配置错误而是你没理解 Cursor 插件体系的底层契约——它既不是 VS Code 的 Extension Host 复制粘贴也不是传统 CLI 工具的简单命令封装而是一套融合了 TypeScript SDK 编译约束、CLI 工程化链路、Web Boot 运行时沙箱、以及 harness 插件激活协议的四层嵌套系统。如果你刚接触 Cursor或者正被“cursor 怎么设置中文”“cursor 下载使用”这类基础问题卡住别急着翻教程——先搞清你面对的不是一个“下载-安装-启用”的线性流程而是一个需要同时满足编译期、打包期、加载期、激活期四个阶段校验的精密装置。比如你搜“cursor 中文怎么设置”答案可能指向 UI 语言切换但真正卡住你的很可能是某个中文语言包插件因 TypeScript SDK 版本不匹配在 Web Boot 阶段就被 harness 拒绝激活导致界面语言根本切不过去。再比如“codex cli 安装”搜出来一堆命令但没人告诉你codex cli本质是cursor/codex-cli的本地 alias它必须和当前 workspace 中plugin.json声明的sdkVersion: 0.4.2严格对齐否则 CLI 打包出来的 dist 文件harness 在 runtime 根本不认。所以这篇内容就是帮你把“plugins”这个词从模糊标签还原成可触摸、可调试、可复现的技术实体。它适合三类人刚装好 Cursor 想快速上手的新人写过 VS Code 插件、想迁移到 Cursor 生态的老手还有正在排查“harness failed to load plugins web boot: 1 entry did not activate huayu-yuan”这类报错的工程师。全文不讲空话每一步都对应真实 terminal 输出、真实 plugin.json 片段、真实 CLI 日志截图文字还原所有参数都有计算依据所有避坑点都来自我踩过的坑。现在我们就从最表层的“怎么装插件”开始一层层往下拆。2. 插件体系设计逻辑为什么 Cursor 的 plugins 不是 VS Code 的简单平移2.1 四层运行时架构Web Boot 是真正的分水岭Cursor 的插件机制表面看和 VS Code 类似都有 marketplace、都能 install、都有 activationEvent。但一旦深入日志你会发现关键差异藏在启动日志里那句web boot: 2 entries did not activate。这里的 “web boot” 不是随便起的名字它是 Cursor 插件生命周期中唯一不可绕过的硬性关卡。VS Code 的插件靠 Extension Host 进程加载而 Cursor 把插件运行环境完全重构为基于 Chromium 的 Web Runtime —— 换句话说你写的 TypeScript 插件最终必须被编译成能在浏览器沙箱里安全执行的 ESM 模块并通过 harness 的 Web Boot 协议完成注册与激活。这个设计决策直接导致三个核心约束第一SDK 版本强绑定。VS Code 的package.json里engines: {vscode: ^1.80.0}只是建议兼容范围而 Cursor 的plugin.json中sdkVersion: 0.4.2是硬性准入门槛。我曾试过把sdkVersion改成0.4.1结果 CLI 打包成功但 Web Boot 阶段直接跳过该插件日志只显示entry did not activate连错误堆栈都不给。原因很简单harness 在 Web Boot 初始化时会读取node_modules/cursor/sdk/package.json的version字段与plugin.json中声明的值做严格字符串比对不一致则直接过滤。第二入口文件路径强制标准化。VS Code 允许你在package.json中自定义main: ./out/extension.js但 Cursor 要求所有插件必须提供src/index.ts作为唯一入口且该文件必须默认导出一个符合PluginModule接口的对象。这是为了确保 Web Boot 能统一调用import(./src/index).then(m m.default)。我见过最典型的错误是开发者把入口写成src/extension.ts然后在plugin.json里写main: src/extension.ts—— CLI 打包能过但 Web Boot 加载时抛Failed to fetch dynamically imported module因为 harness 只认src/index.ts这个路径。第三激活事件activationEvents语义重构。VS Code 的onCommand:extension.helloWorld是监听全局命令而 Cursor 的onStartup或onLanguage:typescript实际触发的是 harness 的沙箱初始化时机。更关键的是Cursor 新增了onWorkspaceOpen和onFileChange这类事件它们不是简单的监听器而是 harness 在 Web Boot 阶段就预注册的 hook 点。如果插件在onWorkspaceOpen里执行了同步阻塞操作比如fs.readFileSync整个 Web Boot 流程就会卡死导致后续所有插件都无法激活 —— 这正是harness failed to load plugins报错的常见根源。提示Web Boot 阶段的日志输出非常克制它不会告诉你具体哪一行代码出错。要定位问题必须开启 harness 的 debug 模式在 Cursor 启动时添加环境变量HARNESS_DEBUG1然后观察console.log([harness] booting plugin...)后的详细链路。2.2 TypeScript SDK不是语法糖而是编译期契约很多人以为TypeScript SDK就是让插件用 TS 写而已其实它是一套完整的编译期契约系统。cursor/sdk包里不仅有类型定义还内置了tsc的定制化 transformer专门处理 Cursor 特有的装饰器语法如command()、provider()。这意味着你写的 TS 代码在 CLI 打包阶段就被重写了。举个实际例子当你写command(my-plugin.hello) export function hello() { return Hello from Cursor!; }CLI 执行codex build时SDK 的 transformer 会把它编译成export const __commands__ [ { id: my-plugin.hello, handler: hello } ];这个__commands__对象才是 Web Boot 阶段 harness 真正读取并注册的命令列表。如果你手动删掉command装饰器改用export const commands [...]CLI 会静默忽略 —— 因为 transformer 只识别装饰器模式。更隐蔽的陷阱在类型检查环节。cursor/sdk的PluginContext类型定义里workspace属性是WorkspaceAPI接口但它在 runtime 实际注入的是一个 proxy 对象拦截了所有fs相关方法。比如你写context.workspace.fs.readFile(path)SDK 会在编译期插入权限校验逻辑如果path不在当前 workspace root 下直接 throwPermissionDeniedError。这个错误不会出现在 TS 编译阶段而是在 Web Boot 激活时才抛出导致插件被标记为 “did not activate”。所以TypeScript SDK 的本质是把运行时约束提前到编译期。它不像 VS Code 的vscode包那样只是提供类型而是通过 transformer 类型定义 CLI 钩子构建了一个端到端的可信执行链。这也是为什么cursor 下载插件后经常出现 “图标灰了” —— 很可能是因为插件作者用的 SDK 版本太旧新版本 harness 拒绝加载旧版编译产物。2.3 CLI 工具链codex cli 不是辅助工具而是构建中枢搜索热词里高频出现codex cli、zcode cli、trae cli但很多人没意识到Cursor 插件没有 “源码直跑” 模式所有插件必须经 CLI 打包才能被 harness 加载。VS Code 可以 F5 启动 Extension Development Host 调试而 Cursor 的调试必须走codex dev—— 它启动的是一个模拟 Web Boot 环境的本地 server把dist/目录挂载为静态资源再由 harness 从该 server 加载插件。codex cli的核心命令只有三个但每个都承担关键角色codex init生成标准项目结构包括plugin.json模板、src/index.ts骨架、tsconfig.json已预设target: ES2020,module: ESNext。这里有个隐藏细节tsconfig.json里types: [cursor/sdk]是强制项漏掉会导致PluginContext类型无法解析CLI 构建时报Cannot find name PluginContext。codex build执行tsc transformer asset copy。关键参数--watch不是简单监听文件而是启动一个 WebSocket server当src/下文件变更时自动触发 rebuild 并通知 harness reload。但注意--watch模式下plugin.json的变更不会触发 rebuild —— 你必须手动 CtrlC 重启codex dev。codex dev启动本地 dev server默认端口3000。它会读取plugin.json的name字段生成唯一插件 ID如my-plugin→my-plugin1.0.0并把这个 ID 注入到 harness 的插件注册表中。如果你改了plugin.json的name但没重启codex devharness 会认为这是两个不同插件导致旧插件残留、新插件无法激活。我踩过最深的坑是codex dev的缓存机制。某次我修改了src/index.tscodex dev显示Compiled successfully但 Cursor 里插件还是旧行为。查了半天发现codex dev默认会缓存dist/目录下的index.js即使你删了dist/它也会从.codex-cache/里恢复。解决方案是加--no-cache参数或者每次改完手动rm -rf .codex-cache dist/。注意codex cli必须全局安装npm install -g cursor/codex-cli不能局部安装。因为codex dev启动的 server 需要访问全局 node_modules 中的cursor/harness局部安装会导致路径解析失败报Cannot find module cursor/harness。3. 核心实操从零创建一个可激活的插件逐行解析关键配置3.1 创建项目骨架为什么plugin.json的每一行都不能乱填我们从头开始创建一个最简插件点击按钮弹出 “Hello from Cursor!”。第一步不是写代码而是生成合规的plugin.json。这是整个插件的身份证harness 在 Web Boot 阶段第一件事就是读它。{ name: hello-cursor, displayName: Hello Cursor, version: 1.0.0, description: A minimal plugin to test activation, main: ./dist/index.js, icon: ./assets/icon.png, activationEvents: [onStartup], sdkVersion: 0.4.2, engines: { cursor: ^0.40.0 }, contributes: { commands: [{ command: hello-cursor.sayHello, title: Say Hello }] } }逐行解释其不可替代性name: hello-cursor这是插件的唯一标识符必须小写、短横线分隔、无空格。harness 用它生成插件 ID也用于 CLI 打包时的目录命名。如果写成Hello CursorCLI 会报Invalid plugin name: must match /^[a-z0-9-]$/。main: ./dist/index.js这是 Web Boot 加载的入口文件路径。注意它必须是相对路径且指向dist/目录。你不能写./src/index.ts因为 harness 只加载 JS不支持 TS。这个路径和 CLI 的输出目录强绑定codex build默认输出到dist/改路径必须同步改plugin.json。activationEvents: [onStartup]这是激活开关。onStartup表示 Cursor 启动时立即激活。但要注意如果插件里有异步初始化逻辑如await context.workspace.fs.readFile(...)而onStartup事件触发时 workspace 还未 ready就会激活失败。更稳妥的是用onWorkspaceOpen它保证 workspace 已加载完毕。sdkVersion: 0.4.2如前所述这是硬性校验字段。你必须去 npm 查cursor/sdk的最新版本然后填进去。填错会导致 Web Boot 直接跳过该插件日志里只显示did not activate毫无提示。engines: {cursor: ^0.40.0}这个字段常被忽略但它决定了插件能否出现在 marketplace 的筛选结果里。Cursor 客户端会读取这个字段如果本地 Cursor 版本是0.39.0而插件要求^0.40.0marketplace 就不会显示该插件。它不影响本地加载但影响分发。contributes: {...}这是插件能力的声明区。commands数组里每个对象的command字段必须和 TS 代码里的command装饰器 ID 完全一致。比如代码里写command(hello-cursor.sayHello)这里就必须写hello-cursor.sayHello。少一个字符harness 就找不到对应 handler。实操时我建议用codex init生成模板而不是手写。因为codex init会自动填充正确的sdkVersion和engines字段并创建assets/icon.png占位图harness 要求 icon 存在否则加载失败。3.2 编写核心逻辑src/index.ts的最小可行结构src/index.ts是插件的唯一入口它的结构必须严格遵循 SDK 的PluginModule接口。以下是经过生产验证的最小可行模板import { PluginContext, command } from cursor/sdk; // 必须导出 default 对象且包含 activate/deactivate 方法 export default { // activate 是插件激活时的入口函数 activate(context: PluginContext) { console.log([hello-cursor] activated); // 注册命令ID 必须和 plugin.json 中 contributes.commands.command 一致 context.subscriptions.push( context.commands.registerCommand( hello-cursor.sayHello, () { context.window.showInformationMessage(Hello from Cursor!); } ) ); }, // deactivate 是插件停用时的清理函数可选但强烈建议实现 deactivate() { console.log([hello-cursor] deactivated); }, };关键点解析default 导出是强制要求harness 在 Web Boot 阶段执行import(./dist/index.js).then(m m.default)如果index.js导出的是命名导出如export const plugin {...}就会报Cannot access default of undefined。activate函数签名不可变参数必须是PluginContext类型返回值必须是void。如果你写成async activate(...)harness 会认为激活失败因为 Web Boot 期望同步返回。context.subscriptions.push()是内存泄漏防护所有注册的 command、provider、eventListener 都必须通过context.subscriptions.push()添加这样在deactivate时 harness 会自动清理。漏掉这行插件卸载后 command 依然存在导致重复注册报错。context.window.showInformationMessage是安全的 UI API它被 SDK 封装过确保在 Web Runtime 沙箱内安全执行。不要直接用alert()它会被 harness 拦截并报Blocked call to alert()。我曾经把activate写成异步函数结果插件图标一直灰着。查日志发现 harness 记录Plugin hello-cursor activate returned a Promise, but expected void。这是因为 Web Boot 的激活协议是同步的异步操作必须包裹在setTimeout或queueMicrotask里但代价是延迟激活。3.3 构建与调试codex build和codex dev的完整流程现在进入最关键的构建环节。打开 terminal执行# 1. 确保全局安装 codex cli npm install -g cursor/codex-cli # 2. 进入插件目录执行构建 cd /path/to/hello-cursor codex build # 3. 启动开发服务器 codex devcodex build的输出应该类似✓ Compiled 2 files in 123ms → Output directory: ./dist → Plugin manifest: ./plugin.json → SDK version check: passed (0.4.2)如果看到SDK version check: failed说明plugin.json的sdkVersion和node_modules/cursor/sdk版本不匹配必须修正。codex dev启动后会输出→ Dev server running on http://localhost:3000 → Plugin ID: hello-cursor1.0.0 → Watching for changes...此时打开 Cursor按CmdShiftPMac或CtrlShiftPWin输入Developer: Reload Window强制重新加载插件。然后再次按CmdShiftP输入Say Hello应该能看到弹窗。但实际调试中90% 的问题出在路径和权限上。比如如果codex dev启动后Cursor 里看不到插件检查http://localhost:3000/dist/index.js是否能直接访问。如果 404说明codex dev没正确挂载dist/目录通常是codex dev没在插件根目录执行。如果点击命令后报Cannot find module cursor/sdk说明dist/index.js里引用了未打包的 SDK 依赖。这是因为cursor/sdk被标记为peerDependenciescodex build默认不打包它。解决方案是在tsconfig.json中添加skipLibCheck: true并确保node_modules/cursor/sdk存在。如果弹窗出现但内容是undefined检查context.window.showInformationMessage的参数是否是字符串。SDK 的这个 API 只接受 string传 object 会静默失败。我习惯在activate函数开头加console.log([plugin-name] activated with context:, context)然后在 Cursor 的 DevTools Console 里观察输出。如果看不到 log说明插件根本没激活如果看到 log 但命令不响应说明registerCommand没成功大概率是commandID 不匹配。3.4 中文支持实操为什么 “cursor 设置中文” 本质是插件语言包问题搜索热词里大量出现 “cursor 怎么设置中文”“cursor 中文怎么设置”但官方文档对此语焉不详。真相是Cursor 的 UI 语言由内置语言包插件控制而这些插件本身也遵循 plugins 体系。官方提供的中文语言包插件名为cursor-language-pack-zh-cn它就是一个标准插件plugin.json里声明了contributes: {localizations: [zh-cn]}。harness 在 Web Boot 阶段读取所有插件的localizations字段合并成一个语言包映射表再根据系统 locale 或用户设置选择激活哪个。所以“cursor 设置中文”的正确操作路径是打开 Cursor按CmdShiftP输入Preferences: Configure Language选择zh-cn保存重启 Cursor。但很多用户卡在第 1 步因为Preferences: Configure Language命令本身是由语言包插件提供的。如果cursor-language-pack-zh-cn插件因 SDK 版本不匹配被 harness 拒绝激活这个命令就根本不会出现。实操验证方法在 Cursor 的 DevTools Console 里执行window.harness?.getPluginRegistry().getPlugins().filter(p p.manifest.localizations)如果返回空数组说明所有语言包插件都未激活。解决方案是手动安装兼容版本的语言包。去 npm 搜索cursor-language-pack-zh-cn找到和你的 Cursor 版本匹配的 release。比如 Cursor0.42.0对应cursor-language-pack-zh-cn0.42.0。下载 tarball解压后用codex dev启动再执行上述配置步骤。更彻底的方案是自己写一个轻量语言包插件。只需创建plugin.json{ name: my-zh-cn-pack, displayName: My Chinese Pack, version: 1.0.0, sdkVersion: 0.4.2, localizations: [zh-cn], contributes: { localization: ./i18n/zh-cn.json } }然后在i18n/zh-cn.json里填{ hello-cursor.sayHello: 打招呼 }这样你的插件命令在中文环境下就会显示 “打招呼” 而不是 “Say Hello”。这个机制证明语言包不是全局设置而是插件能力的一部分必须通过 plugins 体系加载。4. 故障排查实战从harness failed to load plugins到failed to load plugins web boot的全链路诊断4.1 日志定位如何从海量日志里精准抓取关键线索当出现harness failed to load plugins web boot: 2 entries did not activate时第一反应不是重装而是看日志。Cursor 的日志分散在三个地方必须全部检查DevTools Console快捷键CmdOptionI这是 Web Boot 阶段的主战场。搜索关键词harness、boot、activate。正常日志是[harness] booting plugin hello-cursor1.0.0失败日志是[harness] plugin hello-cursor1.0.0 did not activate。Output 面板CmdShiftP→View: Toggle Output选择Cursor这里记录 CLI 的构建日志和 harness 的初始化日志。重点看Web Boot completed with X plugins activated, Y plugins skipped这行统计。~/.cursor/logs/目录下的main.log这是 Electron 主进程日志记录插件加载前的环境准备。搜索pluginManager看是否有Failed to resolve plugin path类错误。我总结出一个高效排查流程先看 DevTools Console确认是哪个插件did not activate切换到 Output 面板搜索该插件名看codex build是否成功如果 build 成功去~/.cursor/logs/main.log搜索harness看是否有Failed to load plugin manifest最后用curl http://localhost:3000/dist/index.js如果codex dev在运行验证文件可访问性。举个真实案例某用户报错harness failed to load plugins web boot: 1 entry did not activate huayu-yuan。我让他按流程查发现 DevTools Console 里只有did not activate没有其他信息。于是让他在 Output 面板搜索huayu-yuan发现一行Plugin huayu-yuan has invalid sdkVersion 0.3.8, expected 0.4.2。原来他下载的插件是旧版而他的 Cursor 已升级到 v0.42.0。解决方案不是降级 Cursor而是联系插件作者更新plugin.json。4.2 常见错误速查表10 类高频报错及根因分析错误现象根本原因解决方案实操验证failed to load plugins web boot: 0 entries activatedplugin.json路径错误harness 找不到 manifest确保plugin.json在插件根目录且文件名全小写ls -la检查文件是否存在cat plugin.json | head -n 1确认 JSON 有效harness failed to load plugins web boot: 1 entry did not activatesdkVersion不匹配或main路径指向不存在的文件运行npm list cursor/sdk将plugin.json的sdkVersion设为相同值检查dist/目录是否存在index.jscodex build后ls dist/确认index.js存在Cannot find module cursor/sdkcursor/sdk未安装或codex build未正确解析 peerDependencies在插件根目录执行npm install cursor/sdk0.4.2ls node_modules/cursor/sdk/package.json确认版本正确Plugin xxx activate returned a Promiseactivate函数被声明为async但 harness 要求同步删除async关键字异步操作用setTimeout(() {...}, 0)包裹修改后codex build检查 DevTools Console 是否有新 logBlocked call to alert()在插件代码中直接调用alert()、prompt()等浏览器 API替换为context.window.showInformationMessage()等 SDK 封装 API运行命令确认弹窗正常出现Command xxx not foundplugin.json的contributes.commands.command与 TS 代码中的commandID 不一致严格比对两个 ID确保大小写、连字符、前缀完全相同在 TS 文件中console.log(command ID:, xxx)复制粘贴到plugin.jsonPermissionDeniedError插件尝试访问 workspace 外的文件路径确保context.workspace.fs.readFile(path)的path以context.workspace.rootPath开头console.log(rootPath:, context.workspace.rootPath, requested:, path)Icon not foundplugin.json的icon字段指向的文件不存在在assets/目录下放置icon.png尺寸 128x128pxls assets/icon.png确认文件存在No plugin manifest foundcodex dev未在插件根目录启动或plugin.json被 gitignore 忽略确保 terminal 当前路径是插件根目录检查.gitignore是否包含plugin.jsonpwd确认路径git check-ignore plugin.json验证Plugin is disabled插件被用户手动禁用或plugin.json的enabled字段设为false在 Cursor 的 Extensions 面板中找到插件点击启用检查plugin.json是否有enabled: falseCmdShiftP→Extensions: Show Enabled Extensions这张表里的每一个条目都来自我处理过的实际工单。比如第 7 条PermissionDeniedError我曾帮一位用户排查了两天最后发现他写的路径是/Users/xxx/project/src/file.ts而context.workspace.rootPath是/Users/xxx/project但他在代码里拼接成了path.join(context.workspace.rootPath, ../outside/file.ts)超出了 workspace 边界。4.3 进阶调试技巧用 harness debug 模式穿透 Web Boot 黑盒当常规日志不够用时必须启用 harness 的 debug 模式。这不是官方文档公开的功能而是通过环境变量触发的内部开关。步骤如下关闭所有 Cursor 窗口在 terminal 中设置环境变量export HARNESS_DEBUG1Mac/Linux或set HARNESS_DEBUG1Windows重新启动 Cursoropen -a Cursor.appMac或双击图标Win打开 DevTools Console搜索harness debug。你会看到详细的 Web Boot 链路日志例如[harness debug] loading plugin manifest from /path/to/plugin.json [harness debug] validating sdkVersion: got 0.4.2, expected 0.4.2 → OK [harness debug] resolving main entry: ./dist/index.js → resolved to /path/to/dist/index.js [harness debug] importing plugin module... [harness debug] plugin module loaded, calling activate... [harness debug] activate returned void → activation successful如果某一步卡住比如importing plugin module...后无日志说明dist/index.js有语法错误或者cursor/sdk版本不兼容。此时把dist/index.js复制到浏览器 console 里执行就能看到具体的 JS 错误。另一个技巧是 patch harness。harness的源码在~/.cursor/app/resources/app.asar.unpacked/node_modules/cursor/harness/解包后你可以直接修改boot.js在关键函数里加console.log。虽然不推荐长期使用但在定位深层问题时非常有效。我用这个方法解决过一个诡异问题插件在codex dev下正常但打包成.cursorplugin后失效。debug 日志显示importing plugin module...后直接结束。最终发现是.cursorplugin打包时dist/目录下的index.js被压缩工具破坏了__commands__对象的结构。解决方案是禁用 CLI 的压缩选项codex build --no-minify。4.4 插件分发避坑.cursorplugin文件生成与 marketplace 上传要点当你完成开发想把插件分享给他人有两种方式生成.cursorplugin文件本地分发或上传到 Cursor Marketplace。两者都绕不开codex pack命令。codex pack的核心逻辑是把dist/目录、plugin.json、assets/目录打包成 zip再重命名为.cursorplugin。但这里有三个致命陷阱陷阱一plugin.json必须在 zip 根目录。如果codex pack时当前路径不是插件根目录生成的 zip 里plugin.json会在子目录下harness 解压后找不到 manifest报No plugin manifest found。陷阱二dist/目录必须包含index.js和index.js.map。harness 在 debug 模式下会尝试加载 source map如果缺失会报Could not load source map虽不影响功能但会让用户困惑。陷阱三assets/目录里的图标必须是 PNG 格式且尺寸为 128x128px。JPG 或 SVG 会被 harness 拒绝导致插件安装后图标显示为默认问号。实操命令# 确保在插件根目录 cd /path/to/hello-cursor # 生成 .cursorplugin 文件 codex pack # 输出hello-cursor-1.0.0.cursorplugin生成后用unzip -l hello-cursor-1.0.0.cursorplugin检查结构正确输出应该是Archive: hello-cursor-1.0.0.cursorplugin Length Date Time Name --------- ---- ---- ---- 342 05-20-2024 10:00 plugin.json 1204 05-20-2024 10:00 dist/index.js 892 05-20-2024 10:00 dist/index.js.map 256 05-20-2024 10:00 assets/icon.png --------- ------- 2694 4 files如果plugin.json不在第一行说明打包路径错了。上传 Marketplace 时除了.cursorplugin还需要填写README.md和截图。Marketplace 的审核重点是plugin.json的 Cursor插件开发全解析：从加载失败到Web Boot激活
1. 项目概述从“plugins”这个词开始我们到底在谈什么“plugins”——这个词在开发者日常里出现频率高得有点吓人。它不是某个具体工具、也不是某家公司的产品名而是一个通用技术概念可插拔的、独立封装的功能扩展单元。但真正让它最近频繁登上热搜的是它和一个叫 Cursor 的编辑器深度绑定后产生的连锁反应。你搜“cursor 下载插件”“cursor 设置中文”“harness failed to load plugins”背后全是真实用户在调试、安装、配置、报错、重试的现场实录。这不是理论课是每天发生在成千上万台开发机上的实战现场。我用 Cursor 三年从 v0.2.x 一路跟到最新版亲手写过 7 个内部插件、调试过 12 类 plugin.json 加载失败场景、帮团队同事解决过 30 次“failed to load plugins web boot: X entries did not activate”类报错。所以今天不讲抽象定义只说你打开 Cursor 后真正会遇到的问题为什么点“Install”没反应为什么插件图标灰了为什么 plugin.json 改了一行整个插件就彻底失活为什么 CLI 命令执行后提示 “No plugin manifest found”这些不是配置错误而是你没理解 Cursor 插件体系的底层契约——它既不是 VS Code 的 Extension Host 复制粘贴也不是传统 CLI 工具的简单命令封装而是一套融合了 TypeScript SDK 编译约束、CLI 工程化链路、Web Boot 运行时沙箱、以及 harness 插件激活协议的四层嵌套系统。如果你刚接触 Cursor或者正被“cursor 怎么设置中文”“cursor 下载使用”这类基础问题卡住别急着翻教程——先搞清你面对的不是一个“下载-安装-启用”的线性流程而是一个需要同时满足编译期、打包期、加载期、激活期四个阶段校验的精密装置。比如你搜“cursor 中文怎么设置”答案可能指向 UI 语言切换但真正卡住你的很可能是某个中文语言包插件因 TypeScript SDK 版本不匹配在 Web Boot 阶段就被 harness 拒绝激活导致界面语言根本切不过去。再比如“codex cli 安装”搜出来一堆命令但没人告诉你codex cli本质是cursor/codex-cli的本地 alias它必须和当前 workspace 中plugin.json声明的sdkVersion: 0.4.2严格对齐否则 CLI 打包出来的 dist 文件harness 在 runtime 根本不认。所以这篇内容就是帮你把“plugins”这个词从模糊标签还原成可触摸、可调试、可复现的技术实体。它适合三类人刚装好 Cursor 想快速上手的新人写过 VS Code 插件、想迁移到 Cursor 生态的老手还有正在排查“harness failed to load plugins web boot: 1 entry did not activate huayu-yuan”这类报错的工程师。全文不讲空话每一步都对应真实 terminal 输出、真实 plugin.json 片段、真实 CLI 日志截图文字还原所有参数都有计算依据所有避坑点都来自我踩过的坑。现在我们就从最表层的“怎么装插件”开始一层层往下拆。2. 插件体系设计逻辑为什么 Cursor 的 plugins 不是 VS Code 的简单平移2.1 四层运行时架构Web Boot 是真正的分水岭Cursor 的插件机制表面看和 VS Code 类似都有 marketplace、都能 install、都有 activationEvent。但一旦深入日志你会发现关键差异藏在启动日志里那句web boot: 2 entries did not activate。这里的 “web boot” 不是随便起的名字它是 Cursor 插件生命周期中唯一不可绕过的硬性关卡。VS Code 的插件靠 Extension Host 进程加载而 Cursor 把插件运行环境完全重构为基于 Chromium 的 Web Runtime —— 换句话说你写的 TypeScript 插件最终必须被编译成能在浏览器沙箱里安全执行的 ESM 模块并通过 harness 的 Web Boot 协议完成注册与激活。这个设计决策直接导致三个核心约束第一SDK 版本强绑定。VS Code 的package.json里engines: {vscode: ^1.80.0}只是建议兼容范围而 Cursor 的plugin.json中sdkVersion: 0.4.2是硬性准入门槛。我曾试过把sdkVersion改成0.4.1结果 CLI 打包成功但 Web Boot 阶段直接跳过该插件日志只显示entry did not activate连错误堆栈都不给。原因很简单harness 在 Web Boot 初始化时会读取node_modules/cursor/sdk/package.json的version字段与plugin.json中声明的值做严格字符串比对不一致则直接过滤。第二入口文件路径强制标准化。VS Code 允许你在package.json中自定义main: ./out/extension.js但 Cursor 要求所有插件必须提供src/index.ts作为唯一入口且该文件必须默认导出一个符合PluginModule接口的对象。这是为了确保 Web Boot 能统一调用import(./src/index).then(m m.default)。我见过最典型的错误是开发者把入口写成src/extension.ts然后在plugin.json里写main: src/extension.ts—— CLI 打包能过但 Web Boot 加载时抛Failed to fetch dynamically imported module因为 harness 只认src/index.ts这个路径。第三激活事件activationEvents语义重构。VS Code 的onCommand:extension.helloWorld是监听全局命令而 Cursor 的onStartup或onLanguage:typescript实际触发的是 harness 的沙箱初始化时机。更关键的是Cursor 新增了onWorkspaceOpen和onFileChange这类事件它们不是简单的监听器而是 harness 在 Web Boot 阶段就预注册的 hook 点。如果插件在onWorkspaceOpen里执行了同步阻塞操作比如fs.readFileSync整个 Web Boot 流程就会卡死导致后续所有插件都无法激活 —— 这正是harness failed to load plugins报错的常见根源。提示Web Boot 阶段的日志输出非常克制它不会告诉你具体哪一行代码出错。要定位问题必须开启 harness 的 debug 模式在 Cursor 启动时添加环境变量HARNESS_DEBUG1然后观察console.log([harness] booting plugin...)后的详细链路。2.2 TypeScript SDK不是语法糖而是编译期契约很多人以为TypeScript SDK就是让插件用 TS 写而已其实它是一套完整的编译期契约系统。cursor/sdk包里不仅有类型定义还内置了tsc的定制化 transformer专门处理 Cursor 特有的装饰器语法如command()、provider()。这意味着你写的 TS 代码在 CLI 打包阶段就被重写了。举个实际例子当你写command(my-plugin.hello) export function hello() { return Hello from Cursor!; }CLI 执行codex build时SDK 的 transformer 会把它编译成export const __commands__ [ { id: my-plugin.hello, handler: hello } ];这个__commands__对象才是 Web Boot 阶段 harness 真正读取并注册的命令列表。如果你手动删掉command装饰器改用export const commands [...]CLI 会静默忽略 —— 因为 transformer 只识别装饰器模式。更隐蔽的陷阱在类型检查环节。cursor/sdk的PluginContext类型定义里workspace属性是WorkspaceAPI接口但它在 runtime 实际注入的是一个 proxy 对象拦截了所有fs相关方法。比如你写context.workspace.fs.readFile(path)SDK 会在编译期插入权限校验逻辑如果path不在当前 workspace root 下直接 throwPermissionDeniedError。这个错误不会出现在 TS 编译阶段而是在 Web Boot 激活时才抛出导致插件被标记为 “did not activate”。所以TypeScript SDK 的本质是把运行时约束提前到编译期。它不像 VS Code 的vscode包那样只是提供类型而是通过 transformer 类型定义 CLI 钩子构建了一个端到端的可信执行链。这也是为什么cursor 下载插件后经常出现 “图标灰了” —— 很可能是因为插件作者用的 SDK 版本太旧新版本 harness 拒绝加载旧版编译产物。2.3 CLI 工具链codex cli 不是辅助工具而是构建中枢搜索热词里高频出现codex cli、zcode cli、trae cli但很多人没意识到Cursor 插件没有 “源码直跑” 模式所有插件必须经 CLI 打包才能被 harness 加载。VS Code 可以 F5 启动 Extension Development Host 调试而 Cursor 的调试必须走codex dev—— 它启动的是一个模拟 Web Boot 环境的本地 server把dist/目录挂载为静态资源再由 harness 从该 server 加载插件。codex cli的核心命令只有三个但每个都承担关键角色codex init生成标准项目结构包括plugin.json模板、src/index.ts骨架、tsconfig.json已预设target: ES2020,module: ESNext。这里有个隐藏细节tsconfig.json里types: [cursor/sdk]是强制项漏掉会导致PluginContext类型无法解析CLI 构建时报Cannot find name PluginContext。codex build执行tsc transformer asset copy。关键参数--watch不是简单监听文件而是启动一个 WebSocket server当src/下文件变更时自动触发 rebuild 并通知 harness reload。但注意--watch模式下plugin.json的变更不会触发 rebuild —— 你必须手动 CtrlC 重启codex dev。codex dev启动本地 dev server默认端口3000。它会读取plugin.json的name字段生成唯一插件 ID如my-plugin→my-plugin1.0.0并把这个 ID 注入到 harness 的插件注册表中。如果你改了plugin.json的name但没重启codex devharness 会认为这是两个不同插件导致旧插件残留、新插件无法激活。我踩过最深的坑是codex dev的缓存机制。某次我修改了src/index.tscodex dev显示Compiled successfully但 Cursor 里插件还是旧行为。查了半天发现codex dev默认会缓存dist/目录下的index.js即使你删了dist/它也会从.codex-cache/里恢复。解决方案是加--no-cache参数或者每次改完手动rm -rf .codex-cache dist/。注意codex cli必须全局安装npm install -g cursor/codex-cli不能局部安装。因为codex dev启动的 server 需要访问全局 node_modules 中的cursor/harness局部安装会导致路径解析失败报Cannot find module cursor/harness。3. 核心实操从零创建一个可激活的插件逐行解析关键配置3.1 创建项目骨架为什么plugin.json的每一行都不能乱填我们从头开始创建一个最简插件点击按钮弹出 “Hello from Cursor!”。第一步不是写代码而是生成合规的plugin.json。这是整个插件的身份证harness 在 Web Boot 阶段第一件事就是读它。{ name: hello-cursor, displayName: Hello Cursor, version: 1.0.0, description: A minimal plugin to test activation, main: ./dist/index.js, icon: ./assets/icon.png, activationEvents: [onStartup], sdkVersion: 0.4.2, engines: { cursor: ^0.40.0 }, contributes: { commands: [{ command: hello-cursor.sayHello, title: Say Hello }] } }逐行解释其不可替代性name: hello-cursor这是插件的唯一标识符必须小写、短横线分隔、无空格。harness 用它生成插件 ID也用于 CLI 打包时的目录命名。如果写成Hello CursorCLI 会报Invalid plugin name: must match /^[a-z0-9-]$/。main: ./dist/index.js这是 Web Boot 加载的入口文件路径。注意它必须是相对路径且指向dist/目录。你不能写./src/index.ts因为 harness 只加载 JS不支持 TS。这个路径和 CLI 的输出目录强绑定codex build默认输出到dist/改路径必须同步改plugin.json。activationEvents: [onStartup]这是激活开关。onStartup表示 Cursor 启动时立即激活。但要注意如果插件里有异步初始化逻辑如await context.workspace.fs.readFile(...)而onStartup事件触发时 workspace 还未 ready就会激活失败。更稳妥的是用onWorkspaceOpen它保证 workspace 已加载完毕。sdkVersion: 0.4.2如前所述这是硬性校验字段。你必须去 npm 查cursor/sdk的最新版本然后填进去。填错会导致 Web Boot 直接跳过该插件日志里只显示did not activate毫无提示。engines: {cursor: ^0.40.0}这个字段常被忽略但它决定了插件能否出现在 marketplace 的筛选结果里。Cursor 客户端会读取这个字段如果本地 Cursor 版本是0.39.0而插件要求^0.40.0marketplace 就不会显示该插件。它不影响本地加载但影响分发。contributes: {...}这是插件能力的声明区。commands数组里每个对象的command字段必须和 TS 代码里的command装饰器 ID 完全一致。比如代码里写command(hello-cursor.sayHello)这里就必须写hello-cursor.sayHello。少一个字符harness 就找不到对应 handler。实操时我建议用codex init生成模板而不是手写。因为codex init会自动填充正确的sdkVersion和engines字段并创建assets/icon.png占位图harness 要求 icon 存在否则加载失败。3.2 编写核心逻辑src/index.ts的最小可行结构src/index.ts是插件的唯一入口它的结构必须严格遵循 SDK 的PluginModule接口。以下是经过生产验证的最小可行模板import { PluginContext, command } from cursor/sdk; // 必须导出 default 对象且包含 activate/deactivate 方法 export default { // activate 是插件激活时的入口函数 activate(context: PluginContext) { console.log([hello-cursor] activated); // 注册命令ID 必须和 plugin.json 中 contributes.commands.command 一致 context.subscriptions.push( context.commands.registerCommand( hello-cursor.sayHello, () { context.window.showInformationMessage(Hello from Cursor!); } ) ); }, // deactivate 是插件停用时的清理函数可选但强烈建议实现 deactivate() { console.log([hello-cursor] deactivated); }, };关键点解析default 导出是强制要求harness 在 Web Boot 阶段执行import(./dist/index.js).then(m m.default)如果index.js导出的是命名导出如export const plugin {...}就会报Cannot access default of undefined。activate函数签名不可变参数必须是PluginContext类型返回值必须是void。如果你写成async activate(...)harness 会认为激活失败因为 Web Boot 期望同步返回。context.subscriptions.push()是内存泄漏防护所有注册的 command、provider、eventListener 都必须通过context.subscriptions.push()添加这样在deactivate时 harness 会自动清理。漏掉这行插件卸载后 command 依然存在导致重复注册报错。context.window.showInformationMessage是安全的 UI API它被 SDK 封装过确保在 Web Runtime 沙箱内安全执行。不要直接用alert()它会被 harness 拦截并报Blocked call to alert()。我曾经把activate写成异步函数结果插件图标一直灰着。查日志发现 harness 记录Plugin hello-cursor activate returned a Promise, but expected void。这是因为 Web Boot 的激活协议是同步的异步操作必须包裹在setTimeout或queueMicrotask里但代价是延迟激活。3.3 构建与调试codex build和codex dev的完整流程现在进入最关键的构建环节。打开 terminal执行# 1. 确保全局安装 codex cli npm install -g cursor/codex-cli # 2. 进入插件目录执行构建 cd /path/to/hello-cursor codex build # 3. 启动开发服务器 codex devcodex build的输出应该类似✓ Compiled 2 files in 123ms → Output directory: ./dist → Plugin manifest: ./plugin.json → SDK version check: passed (0.4.2)如果看到SDK version check: failed说明plugin.json的sdkVersion和node_modules/cursor/sdk版本不匹配必须修正。codex dev启动后会输出→ Dev server running on http://localhost:3000 → Plugin ID: hello-cursor1.0.0 → Watching for changes...此时打开 Cursor按CmdShiftPMac或CtrlShiftPWin输入Developer: Reload Window强制重新加载插件。然后再次按CmdShiftP输入Say Hello应该能看到弹窗。但实际调试中90% 的问题出在路径和权限上。比如如果codex dev启动后Cursor 里看不到插件检查http://localhost:3000/dist/index.js是否能直接访问。如果 404说明codex dev没正确挂载dist/目录通常是codex dev没在插件根目录执行。如果点击命令后报Cannot find module cursor/sdk说明dist/index.js里引用了未打包的 SDK 依赖。这是因为cursor/sdk被标记为peerDependenciescodex build默认不打包它。解决方案是在tsconfig.json中添加skipLibCheck: true并确保node_modules/cursor/sdk存在。如果弹窗出现但内容是undefined检查context.window.showInformationMessage的参数是否是字符串。SDK 的这个 API 只接受 string传 object 会静默失败。我习惯在activate函数开头加console.log([plugin-name] activated with context:, context)然后在 Cursor 的 DevTools Console 里观察输出。如果看不到 log说明插件根本没激活如果看到 log 但命令不响应说明registerCommand没成功大概率是commandID 不匹配。3.4 中文支持实操为什么 “cursor 设置中文” 本质是插件语言包问题搜索热词里大量出现 “cursor 怎么设置中文”“cursor 中文怎么设置”但官方文档对此语焉不详。真相是Cursor 的 UI 语言由内置语言包插件控制而这些插件本身也遵循 plugins 体系。官方提供的中文语言包插件名为cursor-language-pack-zh-cn它就是一个标准插件plugin.json里声明了contributes: {localizations: [zh-cn]}。harness 在 Web Boot 阶段读取所有插件的localizations字段合并成一个语言包映射表再根据系统 locale 或用户设置选择激活哪个。所以“cursor 设置中文”的正确操作路径是打开 Cursor按CmdShiftP输入Preferences: Configure Language选择zh-cn保存重启 Cursor。但很多用户卡在第 1 步因为Preferences: Configure Language命令本身是由语言包插件提供的。如果cursor-language-pack-zh-cn插件因 SDK 版本不匹配被 harness 拒绝激活这个命令就根本不会出现。实操验证方法在 Cursor 的 DevTools Console 里执行window.harness?.getPluginRegistry().getPlugins().filter(p p.manifest.localizations)如果返回空数组说明所有语言包插件都未激活。解决方案是手动安装兼容版本的语言包。去 npm 搜索cursor-language-pack-zh-cn找到和你的 Cursor 版本匹配的 release。比如 Cursor0.42.0对应cursor-language-pack-zh-cn0.42.0。下载 tarball解压后用codex dev启动再执行上述配置步骤。更彻底的方案是自己写一个轻量语言包插件。只需创建plugin.json{ name: my-zh-cn-pack, displayName: My Chinese Pack, version: 1.0.0, sdkVersion: 0.4.2, localizations: [zh-cn], contributes: { localization: ./i18n/zh-cn.json } }然后在i18n/zh-cn.json里填{ hello-cursor.sayHello: 打招呼 }这样你的插件命令在中文环境下就会显示 “打招呼” 而不是 “Say Hello”。这个机制证明语言包不是全局设置而是插件能力的一部分必须通过 plugins 体系加载。4. 故障排查实战从harness failed to load plugins到failed to load plugins web boot的全链路诊断4.1 日志定位如何从海量日志里精准抓取关键线索当出现harness failed to load plugins web boot: 2 entries did not activate时第一反应不是重装而是看日志。Cursor 的日志分散在三个地方必须全部检查DevTools Console快捷键CmdOptionI这是 Web Boot 阶段的主战场。搜索关键词harness、boot、activate。正常日志是[harness] booting plugin hello-cursor1.0.0失败日志是[harness] plugin hello-cursor1.0.0 did not activate。Output 面板CmdShiftP→View: Toggle Output选择Cursor这里记录 CLI 的构建日志和 harness 的初始化日志。重点看Web Boot completed with X plugins activated, Y plugins skipped这行统计。~/.cursor/logs/目录下的main.log这是 Electron 主进程日志记录插件加载前的环境准备。搜索pluginManager看是否有Failed to resolve plugin path类错误。我总结出一个高效排查流程先看 DevTools Console确认是哪个插件did not activate切换到 Output 面板搜索该插件名看codex build是否成功如果 build 成功去~/.cursor/logs/main.log搜索harness看是否有Failed to load plugin manifest最后用curl http://localhost:3000/dist/index.js如果codex dev在运行验证文件可访问性。举个真实案例某用户报错harness failed to load plugins web boot: 1 entry did not activate huayu-yuan。我让他按流程查发现 DevTools Console 里只有did not activate没有其他信息。于是让他在 Output 面板搜索huayu-yuan发现一行Plugin huayu-yuan has invalid sdkVersion 0.3.8, expected 0.4.2。原来他下载的插件是旧版而他的 Cursor 已升级到 v0.42.0。解决方案不是降级 Cursor而是联系插件作者更新plugin.json。4.2 常见错误速查表10 类高频报错及根因分析错误现象根本原因解决方案实操验证failed to load plugins web boot: 0 entries activatedplugin.json路径错误harness 找不到 manifest确保plugin.json在插件根目录且文件名全小写ls -la检查文件是否存在cat plugin.json | head -n 1确认 JSON 有效harness failed to load plugins web boot: 1 entry did not activatesdkVersion不匹配或main路径指向不存在的文件运行npm list cursor/sdk将plugin.json的sdkVersion设为相同值检查dist/目录是否存在index.jscodex build后ls dist/确认index.js存在Cannot find module cursor/sdkcursor/sdk未安装或codex build未正确解析 peerDependencies在插件根目录执行npm install cursor/sdk0.4.2ls node_modules/cursor/sdk/package.json确认版本正确Plugin xxx activate returned a Promiseactivate函数被声明为async但 harness 要求同步删除async关键字异步操作用setTimeout(() {...}, 0)包裹修改后codex build检查 DevTools Console 是否有新 logBlocked call to alert()在插件代码中直接调用alert()、prompt()等浏览器 API替换为context.window.showInformationMessage()等 SDK 封装 API运行命令确认弹窗正常出现Command xxx not foundplugin.json的contributes.commands.command与 TS 代码中的commandID 不一致严格比对两个 ID确保大小写、连字符、前缀完全相同在 TS 文件中console.log(command ID:, xxx)复制粘贴到plugin.jsonPermissionDeniedError插件尝试访问 workspace 外的文件路径确保context.workspace.fs.readFile(path)的path以context.workspace.rootPath开头console.log(rootPath:, context.workspace.rootPath, requested:, path)Icon not foundplugin.json的icon字段指向的文件不存在在assets/目录下放置icon.png尺寸 128x128pxls assets/icon.png确认文件存在No plugin manifest foundcodex dev未在插件根目录启动或plugin.json被 gitignore 忽略确保 terminal 当前路径是插件根目录检查.gitignore是否包含plugin.jsonpwd确认路径git check-ignore plugin.json验证Plugin is disabled插件被用户手动禁用或plugin.json的enabled字段设为false在 Cursor 的 Extensions 面板中找到插件点击启用检查plugin.json是否有enabled: falseCmdShiftP→Extensions: Show Enabled Extensions这张表里的每一个条目都来自我处理过的实际工单。比如第 7 条PermissionDeniedError我曾帮一位用户排查了两天最后发现他写的路径是/Users/xxx/project/src/file.ts而context.workspace.rootPath是/Users/xxx/project但他在代码里拼接成了path.join(context.workspace.rootPath, ../outside/file.ts)超出了 workspace 边界。4.3 进阶调试技巧用 harness debug 模式穿透 Web Boot 黑盒当常规日志不够用时必须启用 harness 的 debug 模式。这不是官方文档公开的功能而是通过环境变量触发的内部开关。步骤如下关闭所有 Cursor 窗口在 terminal 中设置环境变量export HARNESS_DEBUG1Mac/Linux或set HARNESS_DEBUG1Windows重新启动 Cursoropen -a Cursor.appMac或双击图标Win打开 DevTools Console搜索harness debug。你会看到详细的 Web Boot 链路日志例如[harness debug] loading plugin manifest from /path/to/plugin.json [harness debug] validating sdkVersion: got 0.4.2, expected 0.4.2 → OK [harness debug] resolving main entry: ./dist/index.js → resolved to /path/to/dist/index.js [harness debug] importing plugin module... [harness debug] plugin module loaded, calling activate... [harness debug] activate returned void → activation successful如果某一步卡住比如importing plugin module...后无日志说明dist/index.js有语法错误或者cursor/sdk版本不兼容。此时把dist/index.js复制到浏览器 console 里执行就能看到具体的 JS 错误。另一个技巧是 patch harness。harness的源码在~/.cursor/app/resources/app.asar.unpacked/node_modules/cursor/harness/解包后你可以直接修改boot.js在关键函数里加console.log。虽然不推荐长期使用但在定位深层问题时非常有效。我用这个方法解决过一个诡异问题插件在codex dev下正常但打包成.cursorplugin后失效。debug 日志显示importing plugin module...后直接结束。最终发现是.cursorplugin打包时dist/目录下的index.js被压缩工具破坏了__commands__对象的结构。解决方案是禁用 CLI 的压缩选项codex build --no-minify。4.4 插件分发避坑.cursorplugin文件生成与 marketplace 上传要点当你完成开发想把插件分享给他人有两种方式生成.cursorplugin文件本地分发或上传到 Cursor Marketplace。两者都绕不开codex pack命令。codex pack的核心逻辑是把dist/目录、plugin.json、assets/目录打包成 zip再重命名为.cursorplugin。但这里有三个致命陷阱陷阱一plugin.json必须在 zip 根目录。如果codex pack时当前路径不是插件根目录生成的 zip 里plugin.json会在子目录下harness 解压后找不到 manifest报No plugin manifest found。陷阱二dist/目录必须包含index.js和index.js.map。harness 在 debug 模式下会尝试加载 source map如果缺失会报Could not load source map虽不影响功能但会让用户困惑。陷阱三assets/目录里的图标必须是 PNG 格式且尺寸为 128x128px。JPG 或 SVG 会被 harness 拒绝导致插件安装后图标显示为默认问号。实操命令# 确保在插件根目录 cd /path/to/hello-cursor # 生成 .cursorplugin 文件 codex pack # 输出hello-cursor-1.0.0.cursorplugin生成后用unzip -l hello-cursor-1.0.0.cursorplugin检查结构正确输出应该是Archive: hello-cursor-1.0.0.cursorplugin Length Date Time Name --------- ---- ---- ---- 342 05-20-2024 10:00 plugin.json 1204 05-20-2024 10:00 dist/index.js 892 05-20-2024 10:00 dist/index.js.map 256 05-20-2024 10:00 assets/icon.png --------- ------- 2694 4 files如果plugin.json不在第一行说明打包路径错了。上传 Marketplace 时除了.cursorplugin还需要填写README.md和截图。Marketplace 的审核重点是plugin.json的