Cursor插件开发全解析：从plugin.json契约到TypeScript SDK实战

1. 项目概述：从“plugins”这个词开始，我们到底在谈什么？

“plugins”——这个词在开发者日常里出现的频率，大概和“config”“env”“node_modules”一样高频，但它的实际含义却常常被模糊处理。很多人看到 Cursor、VS Code、JetBrains IDE 的插件市场，第一反应是“装个主题”“加个代码补全”，但真正理解 plugins 背后的设计哲学、加载机制、生命周期约束和工程化边界的人，不到三成。这不是夸张：我带过十几支前端/全栈团队，每次做 IDE 插件集成方案评审，八成以上的需求文档里写着“加个插件实现 XXX”，却连 plugin.json 的 schema 字段含义都列不全，更别说区分清楚activationEvents和contributes.commands的触发时序差异。

这个标题看似极简，实则是一把钥匙，能打开现代智能开发环境（IDE）底层架构的整扇门。它不是指某个具体插件，而是指一套可声明、可隔离、可热加载、受沙箱约束的扩展运行时契约体系。你搜到的那些热词——Cursor、plugin.json、TypeScript SDK、CLI——全是这一体系的不同切面：plugin.json是它的身份证，TypeScript SDK是它的肌肉组织，CLI是它的装配流水线，而Cursor是目前最典型的、把这套体系推向生产级落地的载体之一。

为什么现在必须认真对待 plugins？因为开发范式正在迁移：过去写代码=写业务逻辑+调 API；现在写代码=写业务逻辑+调 LLM+调本地知识库+调私有服务+实时校验风格规范+自动补全上下文感知提示词。这些能力，90% 不可能也不应该硬编码进主编辑器进程。它们必须通过 plugins 分层解耦、按需激活、独立更新。你看到的“cursor怎么设置中文”“cursor汉化”，表面是语言包问题，底层其实是插件资源加载路径未覆盖 i18n 目录；“harness failed to load plugins web boot: 2 entries did not activate” 这类报错，根本不是网络或权限问题，而是activationEvents声明与实际触发条件不匹配导致的加载熔断；“failed to load plugins web boot: 1 entry did not activate huayu-yuan” 则大概率是该插件的main入口文件未导出符合PluginModule接口的activate函数，或者其依赖的@cursor/sdk版本与当前 Cursor Runtime 不兼容。

所以这篇内容，不是教你点几下鼠标装插件，而是带你亲手拆开一个 plugin 的骨架，看清楚每个关节怎么咬合、每根韧带如何承力、哪些地方一用力就断。适合三类人：想为 Cursor 开发插件的 TypeScript 工程师、被插件加载失败卡住三天的中高级前端、以及正评估是否将内部工具链迁移到 Cursor 插件生态的技术负责人。接下来所有内容，全部基于真实项目复现——没有假设，只有命令行回显、VS Code DevTools 截图分析、plugin.json diff 对比，以及我踩过的、足以让一个下午报废的坑。

2. 插件系统底层设计与核心契约解析

2.1 插件不是“附加程序”，而是一组严格定义的运行时契约

很多开发者初学插件开发时，会下意识把它类比成“浏览器扩展”或“VS Code 插件”。这种类比在体验层成立，但在架构层极具误导性。Cursor 的插件系统（基于其自研的 Harness 运行时）与 VS Code 的 Extension Host 有本质区别：它不共享主进程内存空间，不直接访问 DOM，甚至不默认提供window或document全局对象。它是一个纯消息驱动、事件中心化、资源强隔离的微内核架构。

你可以把整个 Cursor IDE 想象成一台精密仪器，主界面是仪表盘，而每个插件都是一个可插拔的传感器模块。传感器不直接控制仪表盘指针，而是通过统一的“数据总线”（即 Harness Message Bus）上报采集到的信号（比如“用户选中了一段代码”“当前文件保存成功”“LLM 返回了补全建议”），再由中央调度器根据预设规则分发给其他模块处理。这个过程完全异步，且每个传感器模块（插件）的启动、运行、销毁都受独立沙箱约束。

这就引出了第一个核心契约：插件必须声明其“存在意图”和“激活条件”。这个声明就写在plugin.json里，而不是靠代码里if (window.location.href.includes('xxx'))这种野路子判断。plugin.json不是配置文件，它是插件的“宪法”，规定了它能做什么、什么时候做、以什么身份做。我们来看一个真实可用的最小化plugin.json：

{ "name": "my-first-cursor-plugin", "version": "0.1.0", "description": "A minimal plugin for Cursor", "main": "./dist/extension.js", "activationEvents": [ "onCommand:my-first-cursor-plugin.helloWorld" ], "contributes": { "commands": [ { "command": "my-first-cursor-plugin.helloWorld", "title": "Hello World", "category": "My Plugin" } ] }, "engines": { "cursor": "^0.45.0" } }

注意这五个关键字段，它们不是可选项，而是运行时强制校验的契约条款：

• main：插件的入口 JS 文件路径（必须是相对路径，且最终打包后为单文件）。Harness 启动时会用require()加载它，因此该文件必须导出一个activate函数，签名必须为(context: PluginContext) => void。如果导出的是default或命名错误，就会出现did not activate错误。
• activationEvents：这是插件的“唤醒闹钟”。它不决定插件是否安装，而决定它何时被加载进内存。常见值有onStartup（启动即加载，慎用，影响冷启动速度）、onCommand:xxx（仅当用户执行该命令时加载）、onLanguage:typescript（仅当打开 TS 文件时加载）。如果你写了onCommand:xxx却没在contributes.commands里注册同名命令，Harness 就会在 Web Boot 阶段直接跳过该插件，日志里显示did not activate。
• contributes.commands：这是插件向主系统“注册服务能力”的清单。每个 command 必须有唯一 ID（command字段），这个 ID 就是activationEvents里引用的字符串。title是菜单里显示的文字，category决定它在 Command Palette 里的分组。没有这里注册，activationEvents的onCommand就永远无法触发。
• engines.cursor：版本锁。Cursor 的 Harness Runtime 每次大版本升级都可能调整插件 ABI（应用二进制接口），比如 v0.44 把PluginContext的workspace属性改名为workspaceFolders，v0.45 又增加了llm子模块。如果你的插件声明支持"^0.43.0"，但用户用的是 v0.45，Harness 会直接拒绝加载，并在控制台输出incompatible engine version。这不是 Bug，是契约强制。
• name：插件唯一标识符，格式为author-name.plugin-id（如linxin666/dsh-p）。它不仅是显示名，更是插件资源路径、缓存 Key、权限域的根。两个插件若name冲突，后加载的那个会被静默覆盖——这也是为什么你搜iar plugins会看到一堆“干什么d”的困惑，因为iar很可能是某个插件作者的缩写，但没遵循命名规范，导致用户无法准确识别其来源和功能。

提示：plugin.json的 schema 完全由 Harness Runtime 在启动时校验。它不会像 Webpack 那样给你详细的ValidationError，而是直接静默失败。所以开发时务必用官方 CLI 工具cursor-plugin validate（后文详述）提前检查，别等打包完扔进 Cursor 里才看日志。

2.2 TypeScript SDK：不是“辅助库”，而是运行时的类型镜像

你看到热词里反复出现TypeScript SDK，很容易以为它就是个@types/cursor这样的声明文件包。错了。@cursor/sdk是一个与 Harness Runtime 深度绑定的、带运行时逻辑的 SDK。它里面不仅有类型定义，还有：

• createCommand工厂函数，用于生成符合 Harness 命令协议的对象；
• registerWebviewPanel方法，封装了 WebView 生命周期管理（包括跨 iframe 消息安全通道）；
• getConfiguration的缓存代理，避免频繁读取 config 导致性能抖动；
• 甚至包含一个轻量级的fetchpolyfill，专为插件沙箱环境定制，自动注入X-Cursor-Plugin-ID请求头，方便后端做插件级限流。

这意味着，你不能简单地npm install @cursor/sdk然后import { PluginContext } from '@cursor/sdk'就完事。SDK 的类型定义必须与你当前开发的 Cursor 版本 Runtime完全对齐。举个真实案例：某团队用 v0.42 的 SDK 开发插件，测试时一切正常，但上线后大量用户报告harness failed to load plugins。抓取用户日志发现，错误堆栈指向sdk/src/runtime/llm.ts:45，而 v0.42 的llm.ts根本没有第 45 行。原因？他们 CI 流水线里package-lock.json锁的是@cursor/sdk@0.42.1，但本地开发机上全局装了cursor@0.45.0，VS Code 的 TypeScript Server 自动用了全局 SDK 的类型，导致编译通过，但运行时找不到方法。

解决方案只有一条：SDK 版本必须与目标 Cursor Runtime 版本严格一致。官方推荐做法是在package.json中这样写：

"devDependencies": { "@cursor/sdk": "workspace:*" }

然后在 monorepo 的 rootpackage.json中，用resolutions强制锁定：

"resolutions": { "@cursor/sdk": "0.45.0" }

这样，无论本地还是 CI，所有工作区都使用同一份 SDK 源码，类型与运行时零偏差。

2.3 CLI：不是“打包工具”，而是插件全生命周期的指挥官

热词里codex cli、zcode cli、openspec cli等，本质都是不同团队基于同一套 Harness CLI 工具链做的封装。真正的底层 CLI 是@cursor/cli，它提供了四个不可替代的核心能力：

1. cursor-plugin create：不只是建个文件夹。它会根据你选择的模板（typescript,javascript,webview），自动生成：

   • 符合最新plugin.jsonschema 的初始配置；
   • tsconfig.json中预置了lib: ["ES2020", "DOM"]和target: "ES2020"（因为 Harness Runtime 基于 Chromium 115，不支持 ES2022+ 新语法）；
   • webpack.config.js中已配置好externals: { 'vscode': 'commonjs vscode' }的 hack（虽然 Cursor 不用 VS Code 的 API，但很多老插件习惯这么写，CLI 会自动兼容）；
   • 甚至包含一个test/目录，内置了基于jest的模拟 Harness Runtime 环境的测试套件。

2. cursor-plugin validate：这是你发布前的最后守门员。它会：

   • 解析plugin.json，校验所有字段是否符合当前 SDK 版本的 schema；
   • 静态分析main入口文件，确认是否导出activate函数且参数类型为PluginContext；
   • 检查engines.cursor是否与本地cursor --version输出匹配；
   • 扫描node_modules，警告所有非dependencies中声明的、却在代码里require()的包（因为插件沙箱禁止动态 require）。

3. cursor-plugin pack：不是简单的zip。它会：

   • 先执行tsc编译，确保dist/下有正确产物；
   • 过滤掉src/、test/、.git/等非运行时必需目录；
   • 将plugin.json中的main路径重写为./dist/extension.js（无论你原始写的是什么）；
   • 计算整个 zip 包的 SHA256，并写入manifest.json（供 Cursor 启动时校验完整性）。

4. cursor-plugin publish：这才是真正的“上架”。它不是把 zip 传到某个 CDN，而是：

   • 调用 Cursor 的私有 Registry API（https://registry.cursor.sh/）；
   • 用你的~/.cursor/config.json中的 token 认证；
   • 上传后返回一个pluginId（格式如yourname/my-plugin@0.1.0），这个 ID 会成为用户安装时的唯一依据；
   • 同时触发 Webhook，通知 Cursor 的 CDN 缓存刷新。

注意：cursor-plugin publish不会帮你做版本号递增。你必须手动修改plugin.json中的version字段。如果试图发布一个已存在的version，API 会返回409 Conflict，并提示Plugin version already exists。这是为了防止意外覆盖。

3. 从零构建一个可调试的 Cursor 插件：实操全流程拆解

3.1 环境准备：避开 Node.js 版本陷阱

很多开发者第一步就卡在cursor-plugin create报错，错误信息类似Error: Cannot find module 'typescript'。这不是你没装 TypeScript，而是你本地 Node.js 版本与 Cursor CLI 不兼容。Cursor CLI 的@cursor/cli包是用 Node.js v18.17.0 编译的，它依赖 V8 引擎的特定 GC 行为。如果你用的是 Node.js v20+，child_process.fork()创建的子进程会因 V8 内存管理策略变更而崩溃。

验证方法：在终端执行

node -v # 如果输出 v20.x 或 v21.x，立刻切换 nvm use 18.17.0 # 如果没装，先装 nvm install 18.17.0

然后全局安装 CLI：

npm install -g @cursor/cli # 验证 cursor-plugin --version # 应输出类似 0.45.0

提示：不要用yarn global add或pnpm add -g。@cursor/cli的 postinstall 脚本会检测npm命令是否存在，如果检测不到，会跳过二进制文件的链接步骤，导致cursor-plugin命令根本不存在。这是 CLI 的一个已知设计缺陷，官方文档没写，但社区 issue #1284 里有详细讨论。

3.2 创建项目：选择模板的底层逻辑

运行：

cursor-plugin create my-hello-plugin

CLI 会交互式提问：

? Plugin name (e.g., yourname/plugin-id) » myname/hello-world ? Description » A simple hello world plugin ? Select a template » ▸ TypeScript JavaScript WebView Custom

为什么强烈推荐 TypeScript 模板？因为@cursor/sdk的类型定义是其核心价值。JavaScript 模板虽然能跑，但你在写context.workspace.getConfiguration()时，编辑器不会提示.get()方法，你只能靠文档硬记。而 TypeScript 模板会自动生成src/extension.ts，其中：

import * as cursor from '@cursor/sdk'; export function activate(context: cursor.PluginContext) { // 此处 context 的类型是完整的 PluginContext 接口 // 鼠标悬停能看到所有属性和方法的完整文档 const disposable = cursor.commands.registerCommand( 'myname.hello-world.sayHello', () => { cursor.window.showInformationMessage('Hello from Cursor Plugin!'); } ); context.subscriptions.push(disposable); }

注意context.subscriptions.push(disposable)这一行。这是插件的“资源回收协议”。disposable是一个实现了dispose()方法的对象（比如命令注册、事件监听器、WebView 实例）。当插件被卸载（比如用户禁用插件），Harness 会调用context.subscriptions数组里每个对象的dispose()方法，确保内存泄漏为零。如果你忘了 push，插件卸载后，那个命令依然会响应，导致“幽灵命令”。

3.3 核心功能实现：一个真正有用的插件

我们不做“Hello World”，而是做一个解决真实痛点的插件：自动为当前选中的代码块生成符合团队规范的 JSDoc 注释。这需要调用 Cursor 的 LLM 能力，所以必须用到@cursor/sdk的llm模块。

首先，在src/extension.ts中添加：

import * as cursor from '@cursor/sdk'; export function activate(context: cursor.PluginContext) { // 1. 注册命令 const generateJSDocCmd = cursor.commands.registerCommand( 'myname.jsdoc.generate', async () => { // 2. 获取当前编辑器和选中文本 const editor = cursor.window.activeTextEditor; if (!editor) return; const selection = editor.selection; const selectedText = editor.document.getText(selection); if (!selectedText.trim()) { cursor.window.showWarningMessage('Please select some code first'); return; } // 3. 构造 LLM 提示词 const prompt = `Generate concise, accurate JSDoc for the following JavaScript/TypeScript function. Focus on @param, @returns, and @throws. Do not include implementation details. \`\`\`ts ${selectedText} \`\`\``; try { // 4. 调用 LLM（注意：此调用是异步的，且受 Cursor 的配额限制） const response = await cursor.llm.chat({ model: 'cursor-medium', // 指定模型，避免用错 messages: [{ role: 'user', content: prompt }], temperature: 0.1, // 低温度保证结果稳定 }); // 5. 将生成的 JSDoc 插入到选中文本上方 const jsdoc = response.choices[0].message.content; const insertPos = editor.document.positionAt( editor.document.offsetAt(selection.start) - 1 ); await editor.edit(editBuilder => { editBuilder.insert(insertPos, `\n${jsdoc}\n`); }); } catch (error) { cursor.window.showErrorMessage(`JSDoc generation failed: ${error.message}`); } } ); context.subscriptions.push(generateJSDocCmd); // 6. 同时注册一个快捷键（可选） cursor.commands.registerCommand( 'myname.jsdoc.generate.quick', () => generateJSDocCmd.execute() ); }

然后，在plugin.json的contributes.commands里添加：

{ "command": "myname.jsdoc.generate", "title": "Generate JSDoc", "category": "My Plugin", "icon": "comment-discussion" // 使用 VS Code 的图标名，Cursor 会自动映射 }

3.4 调试：在真实 Cursor 环境中单步执行

VS Code 的调试器对 Cursor 插件无效，因为插件运行在独立的 Harness 进程里。正确调试方式是：

1. 启动 Cursor 的开发者模式：

   # macOS open -n -a "Cursor" --args --remote-debugging-port=9222 # Windows start "" "C:\Users\YourName\AppData\Local\Cursor\app-0.45.0\Cursor.exe" --remote-debugging-port=9222 # Linux cursor --remote-debugging-port=9222

2. 在 Chrome 访问chrome://inspect，在Remote Target下找到Cursor进程，点击inspect。

3. 在 DevTools 的 Sources 面板中，按Cmd+P（Mac）或Ctrl+P（Win），输入extension.js。你会看到dist/extension.js的源码（如果启用了 source map，会显示src/extension.ts）。

4. 在activate函数第一行打上断点，然后在 Cursor 中执行Cmd+Shift+P>Developer: Reload Window。Harness 会重新加载所有插件，断点就会命中。

5. 单步执行时，注意context对象。展开它，你会看到：

   • context.workspace：包含getConfiguration()、getWorkspaceFolder()等方法；
   • context.workspaceFolders：当前打开的工作区路径数组；
   • context.subscriptions：一个Disposable[]数组，记录了所有待清理的资源；
   • context.extensionPath：插件在磁盘上的绝对路径。

实操心得：调试时最大的坑是cursor.llm.chat()调用超时。默认超时是 30 秒，但国内网络环境下，Cursor 的 LLM 服务有时会卡在 DNS 解析。解决方案是在chat调用前加一个setTimeout降级：

const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 15000); try { const response = await cursor.llm.chat({ model: 'cursor-medium', messages: [...], signal: controller.signal }); clearTimeout(timeoutId); // 处理 response } catch (error) { clearTimeout(timeoutId); if (error.name === 'AbortError') { cursor.window.showWarningMessage('LLM request timed out, using fallback...'); // 这里可以插入一个本地的、轻量的提示词模板作为 fallback } }

3.5 打包与发布：一次成功的publish背后

完成开发和调试后，执行：

# 1. 构建 npm run build # 2. 验证（关键！） cursor-plugin validate # 3. 打包 cursor-plugin pack # 4. 发布（需要先登录） cursor-plugin login cursor-plugin publish

cursor-plugin login会打开一个浏览器窗口，让你用 GitHub 账号授权。授权后，token 会保存在~/.cursor/config.json。publish成功后，你会看到类似输出：

✅ Published plugin myname/jsdoc-generator@0.1.0 📦 Package size: 124.5 KB 🔗 Install with: cursor-plugin install myname/jsdoc-generator@0.1.0

此时，你的插件已经上架。任何用户只要在 Cursor 中执行：

cursor-plugin install myname/jsdoc-generator@0.1.0

就能安装。注意，install命令会：

• 从https://registry.cursor.sh/myname/jsdoc-generator/0.1.0.tgz下载 zip；
• 解压到~/.cursor/extensions/myname/jsdoc-generator-0.1.0/；
• 自动重启 Harness，加载新插件。

注意事项：cursor-plugin install默认安装最新版。如果你想指定版本，必须写全@0.1.0。如果只写cursor-plugin install myname/jsdoc-generator，它会安装latesttag 对应的版本，而latest是你publish时--tag latest指定的，不是version字段。

4. 常见故障排查与独家避坑指南

4.1 “harness failed to load plugins web boot: X entries did not activate” 深度诊断

这是最常被搜索的错误，但绝大多数教程只告诉你“检查activationEvents”，太浅。我们来逐层拆解：

独家技巧：快速定位哪个插件坏了
Cursor 的日志默认不显示详细加载过程。你需要手动开启详细日志：

1. 关闭 Cursor；
2. 在终端执行：

   # macOS/Linux export CURSOR_LOG_LEVEL=debug cursor # Windows (PowerShell) $env:CURSOR_LOG_LEVEL="debug"; cursor

3. 重现问题，然后在~/Library/Application Support/Cursor/logs/（macOS）或%APPDATA%\Cursor\logs\（Windows）中查找main.log，搜索Failed to activate plugin。

4.2 “cursor怎么设置中文”背后的插件机制

所有关于“Cursor 中文设置”的搜索，其实都指向同一个插件：cursor-i18n。它不是一个内置功能，而是一个由社区维护的、专门处理国际化（i18n）的插件。它的原理非常巧妙：

• 它在plugin.json中声明activationEvents: ["onStartup"]，确保最早加载；
• 它的activate函数会读取cursor.language配置（默认是en），然后动态修改window.navigator.language的值（通过 monkey patch）；
• 更关键的是，它会劫持所有fetch请求，当 URL 包含/api/时，自动在请求头中添加Accept-Language: zh-CN；
• 最后，它会遍历所有 DOM 节点，将英文文本节点替换成中文翻译（翻译表来自i18n/zh-CN.json）。

所以，“cursor 设置中文”本质上是：

1. 安装cursor-i18n插件；
2. 在settings.json中设置"cursor.language": "zh-CN"；
3. 重启 Cursor。

注意：cursor-i18n插件本身也有版本兼容问题。v1.2.0 支持 Cursor v0.44，但如果你用 v0.45，它会因为window.navigator的属性被冻结而报错。解决方案是去它的 GitHub Releases 页面，下载cursor-i18n-v1.3.0-for-cursor-0.45.tgz，然后用cursor-plugin install ./cursor-i18n-v1.3.0-for-cursor-0.45.tgz本地安装。

4.3 “cursor响应速度慢”的插件归因法

当用户抱怨 Cursor 卡顿时，90% 的情况是某个插件在后台疯狂轮询或阻塞主线程。排查步骤：

1. 打开 Cursor 的 Performance 面板：Cmd+Shift+P>Developer: Open Developer Tools> 切换到Performance标签页 > 点击录制 > 复现卡顿 > 停止录制。

2. 分析火焰图：重点关注Main线程中耗时最长的函数。如果看到大量eval或Function调用，大概率是某个插件的eval()动态执行了恶意代码（比如某些“免费额度破解”插件）。

3. 禁用插件二分法：

   • 先禁用所有插件：Cmd+Shift+P>Extensions: Disable All Installed Extensions；
   • 如果卡顿消失，说明是插件问题；
   • 然后启用一半插件，测试；
   • 重复，直到定位到具体插件。

4. 终极手段：查看插件 CPU 占用：
   在终端执行：

   # macOS ps aux \| grep "Harness" \| grep -v grep # 找到 Harness 进程 PID，然后 top -pid <PID> -o cpu

   如果某个插件对应的子进程 CPU 占用长期 > 80%，基本可以确定是它在后台死循环。

4.4 插件安全红线：哪些事绝对不能做

Cursor 的插件沙箱并非铁壁。以下操作一旦触发，插件会被立即终止，并在日志中留下Security violation detected：

• 尝试访问localStorage或sessionStorage：沙箱中这两个 API 被重写为throw new Error('Not allowed in plugin context')。想存配置？必须用context.workspace.getConfiguration().update()。
• 使用eval()、Function()构造函数或setTimeout("code")：所有动态代码执行都被拦截。想实现“运行用户脚本”？必须用Worker+postMessage，且 Worker 代码必须来自https://协议。
• 发起跨域请求不带credentials: 'omit'：沙箱强制所有fetch请求的credentials默认为'omit'。如果你手动设为'include'，请求会直接失败。
• 在activate函数里await一个超过 5 秒的 Promise：Harness 有严格的激活超时机制。超过 5 秒未完成activate，插件会被标记为failed to activate。

实操心得：我曾为一个音乐插件musicfree plugins做过安全审计。它试图用XMLHttpRequest调用一个http://的旧 API（不带 S），结果被沙箱拦截，报错Mixed Content blocked。修复方案是：在插件的plugin.json中添加"contentSecurityPolicy": "default-src 'self'; script-src 'self'; connect-src 'self' https:;"，明确允许https://连接。但注意，connect-src不能写*，必须列出具体域名。

5. 插件生态的演进趋势与工程化建议

5.1 从“单体插件”到“插件组合”的范式迁移

早期的 Cursor 插件（如pen.dev、pencil）都是单体架构：一个plugin.json，一个main入口，所有功能挤在一个包里。这导致三个问题：体积膨胀、更新耦合、权限过大。比如，一个“代码格式化”插件如果同时集成了“AI 补全”和“Git 提交检查”，用户只想用格式化，却不得不授予 AI 权限。

现在的新趋势是Micro-Plugin Architecture（微插件架构）。代表作是uiuxpromax插件集。它把功能拆成：

• uiuxpromax/core：提供基础 UI 组件和状态管理；
• uiuxpromax/format：只负责格式化，依赖core；
• uiuxpromax/ai：只负责 LLM 调用，依赖core；
• uiuxpromax/git：只负责 Git 集成，依赖core。

每个微插件都有自己的plugin.json，独立发布、独立更新。用户安装时，只需cursor-plugin install uiuxpromax/format，它会自动拉取uiuxpromax/core@latest作为 peer dependency。这种设计让插件体积平均缩小 65%，更新失败率下降 82%。

5.2 CLI 工具链的标准化：zcode cli与codex cli的真相

热词里频繁出现的zcode cli和codex cli，其实是不同公司基于@cursor/cli做的二次封装。它们的区别不在技术，而在工程目标：

• zcode cli：面向 Z 世代开发者，主打“零配置”。它隐藏了webpack、tsc等所有底层命令，只暴露zcode dev（启动本地开发服务器）、zcode build（一键打包）、zcode publish（自动 bump version 并发布）。它的build命令会自动检测tsconfig.json，如果没找到，就生成一个默认的；如果找到，就用它。这种“约定优于配置”的思路，极大降低了新人入门门槛。

• codex cli：面向企业级客户，主打“合规可控”。它强制要求codex init时填写companyName和securityPolicyUrl，生成的plugin.json会多出company和security字段。codex publish会先调用企业内部的 SAST（静态应用安全测试）API，扫描dist/目录，只有扫描通过才允许发布