dsh-cursor-integration

🧩 DSH Cursor Integration

通过 Cursor 官方 SDK 在 DSH 中使用模型，提供多账号管理、用量统计、会话恢复和 SSH 工具协作。

功能

• 账号池：根据模型类别和用量选择账号，也可以在输入区手动切换。
• 用量统计：查看每个账号的 Cursor 模型、其它模型和个人按需占比，支持批量查询和汇总。
• 会话恢复：保存已完成轮次的检查点，重启后尝试恢复原 Agent。
• 工具调用：由 DSH 审批和执行，对重复 SDK 调用复用原结果。
• 网络配置：支持 Cursor 专用代理、模型线路检测和优先线路展示。
• 状态展示：在输入区查看本地上下文估算、检查点恢复和压缩记录。

当前版本为 0.1.7，包含 78 项回归测试。

安装

需要 Node.js 24.9 或以上、DSH LLM 接口 0.2.1-rc.3 或以上，以及拥有相应模型权限的 Cursor API Key。当前使用 @cursor/sdk@1.0.40。

1. 从 GitHub Releases 下载 .tgz 安装包，再在 DSH 插件管理器中填写它的本机绝对路径。
2. 打开设置中的 Cursor 集成，保存账号名称和 API Key。
3. 获取模型目录，添加需要的型号并保存。
4. 按需设置代理地址和用量刷新间隔。

图片能力需要明确声明。未声明的型号按文字处理，确认支持图片后可在设置中启用。

配置

- id: cursor-integration
  name: dsh-cursor-integration
  config:
    proxyUrl: http://127.0.0.1:7890
    providers:
      cursor:
        apiKeyEnv: CURSOR_API_KEY
        usageRefreshMinutes: 5
        models:
          - id: your-model-id
            name: Your model
            inputModalities:
              - text
              - image

模型 ID 与参数以账号目录为准。contextWindow 的单位为 Token，应填写后端实际支持的容量。API Key 存入 DSH 凭据服务，配置中填写的是凭据引用。

proxyUrl 填写 HTTP 或混合代理地址，端口以本机配置为准。代理按请求作用域处理 Cursor 域名的 fetch、HTTPS 和 HTTP/2 调用，覆盖 cursor.com、cursor.sh、cursorapi.com 及其子域名。

账号选择

Cursor 模型和第三方模型分别按对应的额度类别排序。优先使用套餐额度尚未用满、占用比例更低的账号。

套餐额度用完后，个人按需调度使用账期进度作为软上限。当前账号低于软上限时继续使用，达到后优先选择个人按需占比更低的账号。

今日软上限 = 本账期已过天数 ÷ 本账期总天数 × 100%

月份长度参与计算。当前实现固定以每月 23 日为重置日，其他账期需要调整调度实现。

用量和选用结果在后台维护，默认每 5 分钟刷新，可配置为 1～1440 分钟。发送消息时读取已有快照；启动缓存尚未就绪时沿用已保存的默认账号，缺少模型目录时仍可能发起查询。

手动切换对新请求生效，工具结果续接使用原账号。总体用量在金额和限额完整时按金额加权，数据不完整时显示已有比例的平均值。

上下文与压缩

Cursor 会话默认隐藏 DSH 原生上下文入口，在输入区保留本地估算和占用明细。点击「圆环＋上下文＋百分比」展开浮窗；三个用量入口也可直接查看缓存明细，点击外部或按 Esc 关闭。

本地估算统计 DSH 可见的系统提示词、工具定义和对话消息。Cursor SDK 的内部提示与隐藏历史可能采用不同口径，因此本地估算可能与 SDK usage 或原生圆环读数不同。

自动压缩由 DSH 的 @deepseek-ai/dsh-compaction-basic 管理。例如设置 thresholdRatio: 0.7 后，在约 70% 的估算压力下检查摘要需求，工具输出裁剪可能先降低压力。状态行读取实际的摘要和裁剪事件。

SDK 没有公开硬输出 Token 上限。摘要请求中的 maxTokens 转为提示指导，最终缩短效果由 DSH 检查。

工作方式

普通追问尽量复用 Agent 并追加新消息，需要重建时才组装完整历史。恢复检查点前会核对账号、模型、工具配置、工作区和历史指纹，匹配失败时从 DSH 历史重建。

一轮完成后立即保存完成标记，文件锁控制检查点领取。恢复遇到 429 或暂时性网络故障时，会保留尚未发送新消息的检查点，供下次重试。

工具桥接通过 SDK 调用 ID、工具名和参数识别重复交付。等待中的重复调用共享结果，已完成的调用返回原结果；同一 ID 携带不同参数会报告冲突。结果随当前 Agent 释放而清理，不同 ID 的调用独立处理。

在 SSH 工作区中，项目文件和命令交给远端工具。当前 SDK 运行生成的本地工具输出，通过受路径限制的本地读取提供给模型。

flowchart TD
    A[DSH 收到消息] --> B[读取账号池结果并选择线路]
    B --> C{会话能否复用或恢复}
    C -->|可以| D[恢复原 Agent 并追加新消息]
    C -->|需要重建| E[按需组装 DSH 历史]
    D --> F[Cursor 官方 SDK]
    E --> F
    F --> G{返回内容}
    G -->|文字与思考| H[流式显示]
    G -->|工具调用| I[校验参数并识别重复交付]
    I --> J[DSH 审批与执行]
    J --> F
    H --> K[正常结束后保存检查点]

本地数据

数据目录为 ~/.dsh/storages/dsh-cursor-integration/。检查点包含对话和工具输出，应作为本地聊天数据管理。

启动时及每 6 小时后台清理空闲检查点，默认保留 7 天、最多 32 份，SDK 状态文件总量目标为 1 GiB。正在使用的数据跳过清理，占用可能暂时高于目标。

从现有本地版迁移

旧包与本项目都注册 DSH 的 cursor 提供方，同一个 profile 应只启用其中一个。

1. 完全退出 DSH，备份 profile 配置。
2. 安装本项目，禁用旧 cursor-provider 条目。
3. 将旧条目 config 下的 proxyUrl 和 providers 内容复制到新 cursor-integration 条目。同机保留原 credential-ref 即可沿用已保存的密钥。
4. 新集成从 DSH 历史建立会话后，保存自己的检查点。

新机器需要自行填写密钥。账号、用量缓存、聊天和检查点由各机器本地管理。

开发

npm ci --legacy-peer-deps
npm run build
npm test
npm pack

package-lock.json 锁定依赖，构建生成 DSH ModuleLoader 可加载的 src/client.js。

测试使用模拟 SDK，覆盖账号、图片声明、参数校验、重复调用、取消、代理、历史裁剪、摘要请求和进程直接退出后的检查点恢复。公开发布前还需在目标 DSH 桌面版本中验证配置页和真实工具调用。

许可证

MIT。@cursor/sdk、DSH、Ajv、Zod、Undici 等依赖按各自许可证使用，浏览器 bundle 保留构建工具生成的依赖声明。