opencode-cursor（npm 包名@rama_nigg/open-cursor）是一个 OpenCode 插件，通过本地 OpenAI 兼容的 HTTP 代理，把你的 Cursor 订阅模型接入 OpenCode。本文面向想参与开发或深入理解它的新手，完整讲解如何用Bun完成构建、测试与 npm 发布三大流程。🚀

项目概览：先认识代码结构

open-cursor 使用 TypeScript 编写，核心是协议翻译：在 OpenCode 与 Cursor（cursor-agentCLI / Cursor SDK）之间转换提示词、流式响应、思考（thinking）与工具调用。主要目录如下：

TypeScript 配置启用了strict模式并输出到dist/，可参考 tsconfig.json。

环境准备：克隆仓库并安装依赖

开始开发前，确认已安装以下工具：

• Git
• Bun（构建与测试运行器，本项目的主力工具）
• Node.js 20+（若用 API key 走 Cursor SDK，建议 22.13+）
• cursor-agentCLI（本地端到端联调时需要）

克隆仓库并安装依赖：

git clone https://gitcode.com/gh_mirrors/op/opencode-cursor cd opencode-cursor bun install

如何用 Bun 构建插件：一条命令产出 dist

构建脚本定义在 package.json 中，核心是一条bun build命令：

bun run build

它会把 6 个入口编译到dist/，产物与用途如下：

💡 注意：plugin-entry.js刻意只暴露默认插件导出，需要库能力的调用方应走./lib子路径。

本地调试：watch 模式 + 软链安装

修改 TypeScript 代码时，用 watch 模式持续重建：

bun run dev

watcher 只重建产物、不会重启 OpenCode。建议保持"显式重启"的习惯，避免旧的子进程让你误判当前运行的是哪份代码。

仓库还提供了 scripts/install-plugin.sh 一键脚本：安装依赖 → 构建 → 在~/.config/opencode/plugin/cursor-acp.js创建指向dist/plugin-entry.js的软链。因为是软链安装，重新构建后重启 OpenCode 即可生效，无需重复安装。最后用下面命令验证插件已加载：

opencode models | grep cursor-acp

测试指南：从单文件单测到 CI 全量套件

项目使用Bun 内置的测试运行器，无需额外框架。推荐的开发节奏是：先跑覆盖改动的最小测试，发布前再跑 CI 标准套件。

# 构建后跑单个测试文件，迭代最快 bun run build bun test tests/unit/proxy/session-resume.test.ts

常用测试命令一览：

改动边界时的分层测试策略

涉及流式或工具的改动，应从最小层开始验证，自底向上逐层推进：

stream parser → provider boundary 转换 → proxy 集成 → OpenCode 循环集成

解析器测试要能在不启动代理的情况下证明事件处理正确；集成测试则负责证明层间契约，而不必重复每个解析器用例。另外两条纪律值得记住：

• 不要把真实凭据或依赖特定账号的模型名写进提交测试，用 tests/fixtures/ 下的 fixture 做确定性覆盖；
• 需要运行时诊断时，可对单次请求开启调试日志：

CURSOR_ACP_LOG_LEVEL=debug CURSOR_ACP_LOG_CONSOLE=1 \ opencode run "reply with ok" --model cursor-acp/auto

发布到 npm：tag 驱动的完整流程

open-cursor 的发布是tag 驱动的：合并到main不会自动发包，只有推送v*标签才会触发发布。详细规则见 docs/PUBLISHING.md 与 docs-site/content/docs/development/releasing.mdx。

1. 升版前校验

bun install bun run build bun run test:ci:unit bun run test:ci:integration npm pack --dry-run # 检查包内文件清单 npm view @rama_nigg/open-cursor version # 确认目标版本未被占用

检查 dry-run 清单：包内应包含构建产物、源码以及package.json中声明的两个 runner 脚本（sdk-runner.mjs、cursor-agent-runner.mjs）。

2. 升版并打标签

npm version patch # 按需换成 minor / major git add package.json package-lock.json git commit --no-verify -m "chore: bump version to X.Y.Z" git push origin main git tag vX.Y.Z git push origin vX.Y.Z

推送v*标签后，发布工作流会自动执行：校验 tag 与package.json版本一致 → Bun 安装 → 构建并跑标准单元套件 →npm pack --dry-run→ 通过 npm trusted publishing 公开发布 → 创建 GitHub Release。该工作流也可手动触发，默认是 dry run，正式发布需将dry_run设为false。

3. 验证发布结果

npm view @rama_nigg/open-cursor version npm install -g @rama_nigg/open-cursor@latest open-cursor doctor

⚠️ 只有当注册表返回新版本号后，才算发布完成。

开发者的日常清单

参与贡献时，先找到"拥有该改动的层"，避免协议翻译、执行与兼容修复互相渗透：

提交前的最终检查（与 docs-site/content/docs/development/contributing.mdx 保持一致）：

bun run build bun run test:ci:unit bun run test:ci:integration

涉及导出、入口点或包文件变化时，额外执行npm pack --dry-run。配置变量有变化时，记得同步更新文档站点中的 Configuration 参考页。📝

延伸阅读

• 构建与安装：docs-site/content/docs/development/building.mdx
• 测试策略：docs-site/content/docs/development/testing.mdx
• 贡献规范：docs-site/content/docs/development/contributing.mdx
• 发布文档：docs/PUBLISHING.md、docs/RELEASE_NOTES.md
• 用户使用说明：README.md

掌握"构建 → 分层测试 → tag 发布"这条主线后，你就可以在 Bun 之上流畅地开发、验证并交付 open-cursor 的每一个版本了。