dsh-cursor-dev 0.0.0-stage → 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dclef
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,264 @@
-# Temporary Holding Version
+# dsh-cursor-dev
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**让 DSH 中支持工具调用的父模型，把任务交给本机 Cursor CLI 执行，再接收结果、审查修改并继续工作。**
+
+父模型与 Cursor 使用的模型分别选择：例如父模型用 DeepSeek，Cursor 用 Auto；也可以让其他已接入 DSH 的模型派发同样的任务。
+
+[中文](#中文) · [English](#english) · [安装与首次使用](docs/INSTALL.md)
+
+![Cursor 面板：额度、模型与会话](screenshots/panel-zh.png)
+
+## 中文
+
+### 工作方式
+
+```mermaid
+flowchart LR
+    U[用户] --> P[DSH 父模型]
+    P -->|任务、参考文件、验收标准| T[cursor_code]
+    T -->|ACP| C[本机 Cursor CLI]
+    C --> W[工作区文件与命令]
+    C -->|执行报告| T
+    T -->|答复、步骤、文件变更| P
+    P -->|审查后的结果| U
+```
+
+- **父模型**理解需求、拆解任务、调用工具、审查结果。它的模型供应商和 API 配置由 DSH 管理。
+- **Cursor CLI**使用自己的登录账号和可用模型执行任务，包括读取文件、修改代码、运行命令。
+- **插件**启动或恢复 Cursor 会话，传入任务，记录执行过程，并把报告返回原来的父代理。`cursor_code` 的执行过程还会镜像到可点击的 DSH 子会话。
+
+父模型不必是 Cursor 提供的模型。前提是它已接入 DSH、支持工具调用，并且当前会话允许使用插件的工具。这里的模型兼容性指 **DSH 内的父模型**；其他聊天应用需要另行接入，这个包没有提供通用 MCP 服务。
+
+### 安装
+
+完整步骤、升级说明和排错见 **[安装与首次使用](docs/INSTALL.md)**。
+
+1. 安装当前版 Cursor CLI，运行 `agent login`，再用 `agent status --format json` 检查登录。
+2. 在 DSH 插件管理中安装本插件。公开仓库的安装来源为：
+
+   ```text
+   git+https://github.com/Dclef/dsh-cursor-dev.git
+   ```
+
+   已配置 DSH 命令行的用户也可以在所用 profile 下执行：
+
+   ```sh
+   dsh plugin add "git+https://github.com/Dclef/dsh-cursor-dev.git"
+   ```
+
+   `0.11.0` 起也已发布到 npm 公共源，可以改用包名安装：
+
+   ```sh
+   dsh plugin add dsh-cursor-dev
+   ```
+
+3. 按 DSH 提示完成加载；涉及后台代码更新时重启 DSH，然后刷新页面。在 Cursor 面板中选择模型并保存。
+4. 明确告诉父模型使用 `cursor_code`，或者用下面的斜杠命令派发第一个任务。
+
+**版本说明（2026-10-17 核对）：** `0.11.0` 已推送到公开仓库的 `main`，适配 DSH `0.2.1-rc.2`：插件改用新的外部子智能体契约（`startActivation`、必须返回未被占用的子会话 id、External 行由宿主写入），在包顶层声明 `engines.dsh: ^0.2.0-rc.1`，并清理了 DSH 0.2.1 已删除的工具配置项。插件市场（dshmarket）已收录本插件（目录条目合并于 2026-10-17），可以直接在市场里找到并安装；`0.11.0` 也已发布到 npm 公共源（包名 `dsh-cursor-dev`），按包名安装不再返回 404，目录下一次探测后市场卡片会显示版本和 `DSH ^0.2.0-rc.1` 宿主要求。要跟进后续改动请用 Git 来源；`.tgz` 是某一刻的固定快照。详见[安装来源与版本](docs/INSTALL.md#2-选择安装来源)。
+
+运行要求：DSH 包声明 `^0.2.0-rc.1`（已在 `0.2.1-rc.2` 上验证）；Node.js `^22.19.0 || >=24.0.0`；已登录且可访问服务的 Cursor CLI。原生子智能体功能需要 DSH 的 `subagents`、`agents` 服务，后台任务还需要对应任务服务，建议使用当前 DSH 桌面版。CLI 安装方法见 [Cursor 官方文档](https://cursor.com/docs/cli)。
+
+### 三个入口
+
+| 入口 | 用途 | 结果如何回来 |
+| --- | --- | --- |
+| `cursor_code` | 父模型派发完整任务，控制目录、模式、模型、会话与报告 | 工具结果回到调用它的父模型，包含答复、步骤和检测到的文件变更 |
+| `/cursor-subagent 任务内容` | 用户直接派发一次任务；可选前缀 `-m 模型` | 完成或失败后，插件把摘要交给原父代理继续处理 |
+| `cursor_subagent` | 当前源码新增的 DSH 原生一次性子智能体工具，可后台运行 | 使用 DSH 标准结果及后台任务机制；DSH 0.2.1 起这次运行在父会话里显示为一行 External 任务，可点击的镜像子会话只由 `cursor_code` 创建 |
+
+例如，在一个空测试工作区发送：
+
+```text
+/cursor-subagent 创建 cursor-cli-check.txt，内容为 cursor-cli-ok，然后读取它确认内容。只修改这个文件，最后汇报结果。
+```
+
+或者直接对父模型说：
+
+> 请使用 cursor_code 修复这个问题。先让 Cursor 读取相关文件，完成后检查返回的修改和测试结果，再向我汇报。
+
+安装工具后，是否自动调用仍由父模型和会话指令决定。希望默认委派开发任务时，可以把下面的内容加入父代理的自定义指令：
+
+```text
+涉及代码实现、重构、修复或批量修改时，优先使用 cursor_code。
+在 task 中说明完整目标，在 contextFiles 中列出需要先读的文件，
+在 acceptance 中写清约束与验收要求。使用面板默认模型，除非用户要求切换。
+收到结果后检查文件变更和验证记录；必要时继续派发修正。
+同一任务使用相同 sessionLabel，并以 continueSession:true 续聊。
+不同任务或项目使用不同 sessionLabel。没有修改需求的问题可直接回答。
+```
+
+### 给父模型的调用示例
+
+第一次调用 `cursor_code`：
+
+```json
+{
+  "task": "修复登录表单的空密码校验，沿用项目现有交互风格。",
+  "contextFiles": ["src/login.ts", "test/login.test.ts"],
+  "acceptance": "不改变公开接口；补充有意义的回归用例并运行相关测试。",
+  "sessionLabel": "login-validation",
+  "mode": "agent"
+}
+```
+
+收到结果后，仍由同一个父代理调用：
+
+```json
+{
+  "task": "继续处理刚才的任务：检查纯空格密码的边界情况，必要时修正并验证。",
+  "sessionLabel": "login-validation",
+  "continueSession": true
+}
+```
+
+示例中的文件路径需要换成实际项目路径。Cursor 接收任务文本、参考文件提示和其已有的 Cursor 会话历史，不会自动读取整段父对话，所以父模型应把必要背景写进任务。
+
+| 参数 | 说明 |
+| --- | --- |
+| `task` | 必填；完整任务目标 |
+| `contextFiles` / `acceptance` | 参考文件列表、约束与验收标准 |
+| `workspaceRoot` | 可选绝对路径；默认使用当前 DSH 会话工作区 |
+| `model` | 可选 Cursor 模型；省略时使用面板选择及配置回退；面板锁定可覆盖此参数 |
+| `mode` | `agent` 执行修改，`plan` 只读规划，`ask` 只读问答 |
+| `sessionLabel` | 同一父会话中的任务标签，默认 `default`；不同任务建议分开命名 |
+| `continueSession` | 复用当前会话执行后续任务；进程已退出时尝试从 Cursor 存储恢复 |
+| `resetSession` | 清除该标签的插件映射并重新开始；不删除 Cursor 自己的历史文件 |
+| `report` | `summary`（默认）或 `detailed` |
+| `timeoutSeconds` | 默认 1800 秒，最大 7200 秒 |
+
+结果包括成功状态、答复、会话标识、实际模型、执行步骤、预览和检测到的文件变更。当前源码还返回 `modelSource` 与 `requestedModel`，帮助判断模型选择来自面板锁定、调用参数还是默认配置。文件扫描有范围和数量限制，报告不代替父代理对实际工作区的最终检查。
+
+### 模型选择与会话
+
+- 父模型和 Cursor 模型独立配置。可用的 Cursor 模型由该账号的实时列表决定。
+- 默认未锁定时，优先级为：调用的 `model` → 面板保存的模型 → 插件 `model` 配置 → CLI 默认值。
+- 当前源码增加了“锁定面板模型”：保存后，面板选择优先于调用参数。选 Auto 并锁定，可防止父模型显式传入其他模型覆盖它。`auto` 和 `default[]` 表示同一个 Auto 选择。
+- 保存的默认值与正在运行的模型分别显示；新选择在后续运行时应用，不会中途切换已经开始的任务。
+- 会话按 **父代理 ID + `sessionLabel`** 记录。换一个父会话或标签，不会自动接上另一份会话。
+- 改模型可能新起 CLI 进程，并尝试重载已保存的 Cursor 对话。`continueSession:false` 不应被当作清空历史的开关；需要全新上下文时使用新标签或 `resetSession:true`。
+- 重启后的续聊依赖 Cursor 历史及插件映射仍存在；加载失败时会记录原因并回退到新会话。可检查报告中的 `reloaded`。
+- Cursor 的模型选择是 CLI 全局状态，插件串行执行 Cursor 任务。不同标签隔离会话上下文，但不会自动隔离共用工作区的文件。
+
+### 原生子智能体支持范围
+
+当前源码注册 DSH 后端 `cursor`。有对应服务时，`cursor_code` 接入 DSH 的运行开始、结束与取消机制；bundle 同时配置标准工具 `cursor_subagent`，不修改已有通用 `subagent` 工具的默认后端。
+
+执行仍由外部 Cursor CLI 完成，DSH 中的子会话负责展示过程。标准入口支持一次性前台或后台任务，后台任务可通过 DSH 的 `job_output` / `job_kill` 查看或取消。
+
+目前支持 `cursor_code` 的显式续聊；**尚不支持通过 `send_message` 向 Cursor 投递持久消息，也没有把 Cursor 接成 Agent Teams 常驻队友**。精简 profile 缺少原生子智能体服务时，`cursor_code` 可以使用原有执行路径；镜像、面板和命令分别依赖对应的宿主服务。
+
+### 面板、配置和数据
+
+从 DSH 的 Cursor 插件入口打开面板，也可以访问当前 DSH 地址下的 `/plugins/dsh-cursor-dev/`。例如，DSH 运行在 `http://127.0.0.1:19387` 时，面板地址为 `http://127.0.0.1:19387/plugins/dsh-cursor-dev/`；其他用户应使用自己的地址和端口。
+
+面板包含安装/登录状态、账号额度、模型和模式设置、活动与历史会话。点击会话可查看镜像记录。新版本页面可能与上面的截图不同。
+
+| 插件配置 | 默认值 | 用途 |
+| --- | --- | --- |
+| `model` | 空字符串 | 面板未设置时的 Cursor 模型 |
+| `maxLiveSessions` | `3` | 最多保留的 CLI 进程数，任务仍然串行 |
+| `sessionIdleMinutes` | `15` | 空闲进程回收时间 |
+| `maxScanFiles` | `20000` | 工作区变更扫描的文件数量上限 |
+| `toolName` | `cursor_code` | 编码工具的注册名 |
+| `usageUi` | `true` | 是否挂载状态、额度和面板 HTTP 路由 |
+| `usageBaseUrl` | `https://api2.cursor.sh` | Cursor 额度 API 地址 |
+| `maxChildDepth` | `1` | Cursor 子会话允许达到的深度上限，调用方深度必须小于该值 |
+
+插件自动探测 CLI 的 PATH 和已知安装目录。探测失败时，可在插件配置里设置 `command` 指向可启动的二进制、安装根目录、`agent.cmd`，或 `"node.exe" "index.js"`；非空时只使用该路径，不再回退到自动探测。安装排错以[指南](docs/INSTALL.md#6-常见问题)为准。
+
+### 代理设置
+
+面板的「子智能体模型」卡片里有**代理**输入框，未设置时默认为空。
+
+| 取值 | 含义 |
+| --- | --- |
+| 留空（默认） | 自动探测：先看 `HTTPS_PROXY` 等环境变量，再看 Windows「Internet 选项」里的代理 |
+| `none` | 直连，不用代理 |
+| `http://127.0.0.1:7890` | 显式指定代理，优先于环境变量和注册表 |
+
+**为什么需要它：** Cursor CLI 只读 `HTTPS_PROXY` / `HTTP_PROXY` / `https_proxy` / `http_proxy`——不读注册表，也不读 `ALL_PROXY`。所以一台只把代理写在「Internet 选项」里的机器，插件启动的 CLI 子进程会直连 Cursor，而直连只会拿到模型目录里的**一小部分**：本机实测 `agent --list-models` 为 **31 个**（走代理 **265 个**），ACP 会话清单为 **10 个**（走代理 **46 个**）。这就是「有些模型看不到」的全部原因。
+
+留空即自动探测，所以正常情况下不需要配置任何东西；插件会把探测到的地址写进子进程环境（`HTTPS_PROXY`、`HTTP_PROXY` 及小写形式），并在模型卡片的「可选模型」那一行末尾显示**子进程出口**。面板保存后立刻生效，不必重启应用；如果填的值解析不了，那一行会直接说明。
+
+模型卡片下方还有可搜索的模型浏览器：点一行设为面板模型，右边的开关决定它是否出现在上方下拉框里。关掉的模型只是藏起来（写入 `disabledModels`），点「保存」后生效，随时可以再打开——这样在完整目录有上百个模型时也能只留下写业务常用的几条。
+
+`maxChildDepth` 限制的是**谁能启动 Cursor 子会话**：深度为 `0` 的顶层智能体是正常调用方，深度 `1` 的子智能体再调用就会被拒绝（默认上限 `1`，即只允许父智能体创建子智能体）。拒绝发生在创建任何进程或子会话之前，`cursor_code` 立即返回 `sessionKey: "depth-refused"`，`cursor_subagent` 抛出同类错误，错误信息里带有当前深度和上限。宿主本身对 `subagent` / `subagent_fork` 的深度限制（面板「子智能体 → 运行限制 → 最大递归深度」）仍然生效；`cursor` provider 声明 `depthLimit: false`，无法接收数值型 `maxDepth`，所以这道限制由本插件自己执行。把 `maxChildDepth` 设为 `0` 可以完全禁止子会话，设为 `2` 或更大则允许更深一层。镜像历史（面板里的记录）不受此限制，仍可正常打开查看。
+
+插件设置与会话映射优先写入环境变量 `DSH_CURSOR_DEV_DATA` 指定的目录；否则使用 `%LOCALAPPDATA%/dsh-cursor-dev`；没有该环境变量时使用 DSH 提供的 `baseDir` 下的 `.data`（再无 `baseDir` 时回退到进程当前目录）。Cursor 登录和原始会话由 Cursor 自己保存。面板写操作包含同源检查，HTTP 可访问范围由 DSH 的监听配置决定。
+
+### 开发与验证
+
+```sh
+npm install
+node --test --test-force-exit --test-skip-pattern="the child agent really edits a file|a bad model is rejected|the real Cursor account returns live quota data" "test/**/*.test.mjs"
+```
+
+完整测试命令为 `npm test`，共 213 项；上面那条命令跳过其中三个真实 CLI/账号测试，剩下 210 项离线测试必须全绿。真实测试需要 Cursor 登录和网络，执行任务会使用该账号额度。当前实现已通过 210 项离线测试，并完成两轮真实 Auto 调用、文件修改和上下文续接验证。打包使用 `npm pack` 或 `pnpm pack`，发布前按[分发检查](docs/INSTALL.md#7-维护者分发前检查)核对安装包和版本。
+
+## English
+
+**Use Cursor CLI as an execution agent for a tool-capable parent model in DSH. Results return to the same parent for review and follow-up.** The parent model and Cursor's model are configured independently. A DeepSeek parent can delegate to Cursor Auto, for example; the parent does not need to be a model offered by Cursor.
+
+### Install and try it
+
+See the [installation guide](docs/INSTALL.md) for detailed setup and troubleshooting.
+
+1. Install the current [Cursor CLI](https://cursor.com/docs/cli), run `agent login`, and check `agent status --format json`.
+2. Install the plugin through DSH's plugin manager using `git+https://github.com/Dclef/dsh-cursor-dev.git`. With the DSH CLI configured for your intended profile, use:
+
+   ```sh
+   dsh plugin add "git+https://github.com/Dclef/dsh-cursor-dev.git"
+   ```
+
+   From `0.11.0` on the package is also published to the public npm registry, so the bare name works:
+
+   ```sh
+   dsh plugin add dsh-cursor-dev
+   ```
+
+3. Restart DSH when backend changes require it, then refresh the page. Open the Cursor panel under `/plugins/dsh-cursor-dev/`, select a model and save it.
+4. Ask the parent to use `cursor_code`, or send `/cursor-subagent` followed by a complete task. The command dispatches directly and hands a completion or failure summary back to the original parent.
+
+As checked on **2026-10-17**, version `0.11.0` is pushed to `main` on the public repository and adapts the plugin to DSH `0.2.1-rc.2`: it follows the new external-subagent contract (`startActivation`, a child id the host has not registered yet, and the `External` catalog row written by the host), declares `engines.dsh: ^0.2.0-rc.1` at the package top level, and drops the tool-config keys that DSH 0.2.1 removed. The dsh-market catalog already lists this plugin (entry merged 2026-10-17), so it can be installed from the market; version `0.11.0` is also published to the public npm registry as `dsh-cursor-dev`, so a bare package-name installation works and the market card shows the version and the `DSH ^0.2.0-rc.1` host requirement after the catalog's next probe. Use the Git source to follow later changes; a `.tgz` is a fixed snapshot.
+
+Requirements: DSH metadata declares `^0.2.0-rc.1` (verified against `0.2.1-rc.2`); Node.js `^22.19.0 || >=24.0.0`; an authenticated Cursor CLI account with service access. Native dispatch additionally needs DSH's `subagents` and `agents` services, and background runs need the host's job services. A current DSH desktop installation is recommended.
+
+### Parent-to-child contract
+
+- `cursor_code` takes a complete `task`, optional `contextFiles` and `acceptance`, an absolute `workspaceRoot`, and optional model, mode, session and report settings. It returns the final reply, steps and detected file changes to its caller.
+- The child receives the delegated task and its own Cursor history, not the whole parent conversation. Include the context it needs.
+- Use the same `sessionLabel` and `continueSession: true` for follow-ups from the same parent. Use a new label or `resetSession: true` to start without the previous mapping. `continueSession: false` alone does not guarantee an empty persistent history.
+- A model change may start another CLI process and reload the saved Cursor conversation. Recovery depends on the saved records still being available; load failure falls back to a new session.
+- Cursor runs are serialized because its model selection is global. Labels isolate conversation context, not files in a shared workspace.
+- The parent must support tool calling and have the tool enabled. Installing this plugin does not force every parent to delegate automatically. Other chat applications require a separate integration; this package is not a general MCP server.
+
+The default model order is call argument → saved panel choice → plugin configuration → CLI default. In the current source, locking the panel choice overrides a per-call model argument. Auto and `default[]` are the same choice. The returned `modelSource` and `requestedModel` explain the selection.
+
+### Native execution and limits
+
+The current source registers a native DSH provider named `cursor` and a standard one-shot tool named `cursor_subagent`. Rich `cursor_code` calls also use the native lifecycle when those host services exist. The existing generic `subagent` backend remains configured as before.
+
+Cursor executes externally. From DSH 0.2.1 on, the host writes a single non-interactive `External` row for a `cursor_subagent` run; the clickable mirrored child conversation is created by `cursor_code`, which starts the provider directly. Standard background runs use DSH's job result and cancellation tools. Persistent mailbox continuation through `send_message`, and Cursor as a resident Agent Teams teammate, are not implemented. Use `cursor_code` with `continueSession` for explicit follow-ups.
+
+The parent remains responsible for reviewing the actual changes and verification evidence. File reports have scan limits and are not a substitute for final workspace checks. Cursor model availability and usage depend on the Cursor account; the parent model uses its separate DSH provider configuration.
+
+`maxChildDepth` (default `1`) caps who may start a Cursor child session. A top-level agent at depth `0` is the intended caller; a subagent at depth `1` that calls `cursor_code` or `cursor_subagent` is refused before any process, child session, or reset is created — `cursor_code` returns `sessionKey: "depth-refused"` and the error names both the current depth and the cap. This exists because the `cursor` provider declares `depthLimit: false` and cannot accept a numeric `maxDepth` from the host's `tool-subagent`, so the plugin enforces the limit itself. Set it to `0` to forbid Cursor children entirely, or higher to allow deeper nesting. The host's own delegation limit for `subagent` / `subagent_fork` (panel → Subagents → Run limits → maximum recursion depth) still applies independently. Opening a mirrored child conversation in the panel is a read-only record and is not affected.
+
+### Proxy
+
+The **子智能体模型** card carries a **proxy** box, empty by default.
+
+| Value | Meaning |
+| --- | --- |
+| empty (default) | detect it: `HTTPS_PROXY` and friends first, then the Windows Internet Settings proxy |
+| `none` | never proxy |
+| `http://127.0.0.1:7890` | that proxy, ahead of both of the above |
+
+Why it exists: the Cursor CLI reads `HTTPS_PROXY` / `HTTP_PROXY` / `https_proxy` / `http_proxy` and nothing else — not the Windows registry, and not `ALL_PROXY`. On a machine whose only proxy lives in Internet Settings, the CLI child therefore reaches Cursor directly, and the direct route publishes only a fraction of the catalogue: measured on this machine, `agent --list-models` answers **31** models directly and **265** through the proxy, while the ACP roster the picker actually uses goes from **10** to **46**. That is the whole of the "some models are missing" symptom.
+
+Leaving the box empty already fixes it, so no configuration is normally needed: the plugin resolves the route, writes `HTTPS_PROXY`/`HTTP_PROXY` (and the lowercase spellings) into every child process it starts, and shows the result as **子进程出口** at the end of the *available models* line. Saving takes effect on the next spawn rather than the next restart, and a value that cannot be parsed is reported on that same line instead of being silently ignored.
+
+## License
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+# Register the Cursor developer subagent plugin. It talks the Agent Client
+# Protocol to the Cursor CLI directly: the host half serves the dashboard as
+# plain HTML, and the browser half puts that page in a Sidebar tab.
+- insert:
+    - id: dsh-cursor-dev
+      name: dsh-cursor-dev
+    - id: tool-cursor-subagent
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: cursor
+        toolName: cursor_subagent
+        maxDepth: provider-managed

package/docs/INSTALL.md

@@ -0,0 +1,219 @@
+# 安装与首次使用
+
+[返回 README](../README.md)
+
+本指南面向希望让 DSH 的父模型调用本机 Cursor CLI 的用户。安装完成后的流程是：**父模型派任务 → Cursor 执行 → 插件返回报告 → 父模型审查和继续处理**。
+
+## 1. 准备 DSH 和 Cursor CLI
+
+需要：
+
+- 可正常对话的 DSH，以及一个支持工具调用的父模型。
+- 插件使用的 Node.js 满足 `^22.19.0 || >=24.0.0`。桌面版应检查其自带运行时，终端里的 `node --version` 不一定是桌面程序使用的版本。
+- 当前版 Cursor CLI，已完成登录，并有执行任务所需的账号权限、额度和网络连接。
+- 原生子智能体入口需要 DSH 的 `subagents`、`agents` 服务；后台运行还需要宿主任务服务。包声明的 DSH 版本为 `^0.2.0-rc.1`（已在 `0.2.1-rc.2` 上验证），建议使用当前桌面版及其标准 profile。
+
+父模型的 API 配置与 Cursor 登录分别管理。插件使用本机 CLI 的登录状态，无需再向插件填写一份 Cursor API Key。
+
+Windows，在 PowerShell 中按 [Cursor 官方安装说明](https://cursor.com/docs/cli)安装：
+
+```powershell
+irm 'https://cursor.com/install?win32=true' | iex
+```
+
+macOS / Linux：
+
+```sh
+curl https://cursor.com/install -fsS | bash
+```
+
+安装完成后，在能够找到 `agent` 命令的终端执行：
+
+```sh
+agent login
+agent status --format json
+```
+
+状态应包含 `"isAuthenticated": true`。如果刚安装后终端找不到 `agent`，重新打开终端再检查。DSH 在启动时探测 CLI，安装 CLI 或改变 PATH 后也需要重启 DSH。
+
+## 2. 选择安装来源
+
+**发布状态（2026-10-17 核对）：** 公共 GitHub 仓库存在，`0.11.0` 已推送到 `main`（适配 DSH `0.2.1-rc.2` 的外部子智能体契约、顶层 `engines.dsh`、面板模型锁定、父级专属的 `maxChildDepth` 递归限制，以及本指南都在其中）。插件市场（dshmarket）的目录条目已于 2026-10-17 合并，可以直接在市场里找到本插件；`0.11.0` 也已发布到 npm 公共源（包名 `dsh-cursor-dev`），按包名安装不再返回 404，目录下一次探测后市场会显示版本和 `DSH ^0.2.0-rc.1` 宿主要求。
+
+| 你要安装的内容 | 安装来源 |
+| --- | --- |
+| 插件市场里的本插件 | 市场条目解析为 `github:Dclef/dsh-cursor-dev`，安装后会跟随仓库默认分支 |
+| npm 公共源上的已发布版本 | `dsh-cursor-dev`（`0.11.0` 起可用，按包内 `files` 白名单安装） |
+| 公开仓库的当前版本（推荐） | `git+https://github.com/Dclef/dsh-cursor-dev.git` |
+| 你本地的源码目录 | 该目录的绝对路径，例如 `D:/plugins/dsh-cursor-dev` |
+| 维护者提供的源码快照或发布包 | `.tgz` 文件的绝对路径，例如 `D:/Downloads/dsh-cursor-dev-0.11.0.tgz` |
+
+表中本地路径是示例，需要换成实际位置。npm 来源取 registry 上发布的最新版本；Git 来源会取得仓库默认分支的最新提交；`.tgz` 是某一刻的固定快照——要跟进后续改动就用 Git 来源。
+
+### 桌面用户：通过插件管理安装
+
+1. 打开当前 DSH 的插件管理安装入口。
+2. 输入上述 Git 地址，或者源码目录 / 安装包的**绝对路径**。浏览器界面不接受 `./dsh-cursor-dev` 这种相对路径。
+3. 检查识别到的包名为 `dsh-cursor-dev`，完成安装并启用。
+4. 按提示应用配置。安装或升级后台代码后完整重启一次 DSH，再刷新页面。
+
+插件的 bundle 会声明所需的插件配置；当前源码还包含标准工具 `cursor_subagent` 的配置。普通安装不需要复制维护者的整个 profile，也不需要手工填写维护者电脑上的路径。
+
+### 已配置 DSH CLI 的用户
+
+在你实际使用的 DSH profile 下执行，避免安装到了另一套 profile：
+
+```sh
+dsh plugin add "git+https://github.com/Dclef/dsh-cursor-dev.git"
+```
+
+npm 上已发布的版本可以按包名安装：
+
+```sh
+dsh plugin add dsh-cursor-dev
+```
+
+本地源码安装，例如 Windows：
+
+```powershell
+dsh plugin add "D:/plugins/dsh-cursor-dev"
+```
+
+或者在 macOS / Linux：
+
+```sh
+dsh plugin add "/home/you/plugins/dsh-cursor-dev"
+```
+
+安装收到的包：
+
+```powershell
+dsh plugin add "D:/Downloads/dsh-cursor-dev-0.11.0.tgz"
+```
+
+终端没有 `dsh` 命令时，使用桌面插件管理即可。不要把在任意项目目录执行 `npm install` 当成已经在 DSH 当前 profile 中启用插件。
+
+## 3. 打开面板并保存模型
+
+从 DSH 的 Cursor 插件入口打开面板，或者访问 **当前 DSH 地址**下的 `/plugins/dsh-cursor-dev/`。
+
+例如 DSH 的地址是 `http://127.0.0.1:19387`，则面板是：
+
+```text
+http://127.0.0.1:19387/plugins/dsh-cursor-dev/
+```
+
+端口和主机名应以你自己的 DSH 为准。面板应能显示 CLI 安装和登录状态；登录正常后可以查看该账号的模型列表和额度信息。
+
+在包含本轮修改的版本中：
+
+1. 选择想让 Cursor 使用的模型，例如 **Auto**。
+2. 如果希望父模型不能通过调用参数覆盖它，勾选 **锁定面板模型**。
+3. 点击保存。确认页面显示的是已保存选择与锁定状态。
+
+`auto` 与 `default[]` 都表示 Auto。面板保存的选择与当前已启动任务的模型不是同一项状态；新选择在后续运行时应用。锁定只决定选用哪个模型，不增加账号额度或模型访问权限。
+
+### 模型列表不全时先看代理
+
+同一张卡片上有 **代理** 输入框，留空即为自动探测，正常情况不需要填。它决定的是**插件启动的 CLI 子进程**走哪条网络出口。
+
+Cursor CLI 只读 `HTTPS_PROXY` / `HTTP_PROXY`（以及小写形式），不读注册表，也不读 `ALL_PROXY`。代理只写在 Windows「Internet 选项」里的机器，子进程会直连 Cursor，而直连只返回模型目录的一部分——本机实测 `agent --list-models` 为 31 个（走代理 265 个），面板真正使用的 ACP 清单为 10 个（走代理 46 个）。
+
+自检步骤：
+
+1. 打开 `http://<你的 DSH 地址>/plugins/dsh-cursor-dev/`。
+2. 看「子智能体模型」卡片：**可选模型** 那一行末尾会显示 **子进程出口**，例如 `http://127.0.0.1:7890 (registry:Internet Settings)`。
+3. 如果显示 `direct (no proxy configured)`，而你的机器确实有代理，就在 **代理** 框里填上地址（如 `http://127.0.0.1:7890`）并点保存。保存后立即生效，不需要重启应用；面板会自动重新读取模型列表。
+4. 想强制直连时填 `none`。
+
+也可以在终端里直接对照，两个数字应当与面板一致：
+
+```powershell
+agent --list-models | Measure-Object -Line                       # 直连
+$env:HTTPS_PROXY='http://127.0.0.1:7890'; agent --list-models | Measure-Object -Line
+```
+
+升级后仍看不到锁定选项时，先确认安装的代码确实包含该功能，再完整重启 DSH。仅刷新浏览器不会重新加载已缓存的后台 JavaScript。旧版进程可能在刷新设置时丢弃新字段，因此应在新版进程启动后再保存锁定设置。
+
+## 4. 做一次完整验证
+
+在一个空的测试工作区开始，向 DSH 发送：
+
+```text
+/cursor-subagent 创建 cursor-cli-check.txt，内容为 cursor-cli-ok，然后读取它确认内容。只修改这个文件，最后汇报结果。
+```
+
+观察以下结果：
+
+- Cursor 实际执行了任务，工作区出现指定文件且内容正确。
+- 能打开对应的子会话查看过程；这需要宿主的会话服务。
+- 任务完成后，父代理收到 Cursor 的结果并继续回复。
+
+再通过父模型验证工具调用：
+
+```text
+请使用 cursor_code，sessionLabel 设为 install-check。
+读取 cursor-cli-check.txt，给它追加一行 parent-child-return-ok，
+读取确认后返回结果。请检查 Cursor 返回的文件变更，再向我汇报。
+```
+
+需要验证续聊时，仍在同一个父会话发送：
+
+```text
+请再次使用 cursor_code，sessionLabel 仍为 install-check，
+continueSession 设为 true。让 Cursor 说明上一轮做了什么，再核对文件内容。
+```
+
+父模型应能调用工具并读取返回值；Cursor 应能读取前一轮的会话上下文。不同父会话的同名标签不是同一个会话。是否真正修改成功应以文件和验证记录为准，不能只看模型说“完成了”。
+
+## 5. 如何让不同父模型使用 Cursor
+
+在 DSH 切换父模型后，只要新模型支持工具调用、当前会话启用了 `cursor_code`，它就能使用同样的接口。插件不要求父模型与 Cursor 属于同一个供应商。
+
+例如：
+
+```text
+父模型：DSH 中配置的 DeepSeek / GPT / Claude / 其他支持工具的模型
+任务：调用 cursor_code 并传入 task、contextFiles、acceptance
+执行模型：Cursor 账号中选择的 Auto 或其他可用模型
+返回：工具报告交回调用它的父代理，再由父代理审查和回复用户
+```
+
+具体可用的父模型由 DSH 接入决定，具体可用的子模型由 Cursor 账号决定。这不意味着上述每个模型版本都经过本插件逐个实测。
+
+希望默认把开发任务交给 Cursor，可以采用 [README 中的父代理指令](../README.md#三个入口)。没有这些指令时，父模型可能自行完成任务；手动使用 `/cursor-subagent` 可以直接派发。
+
+标准工具 `cursor_subagent` 用于当前源码提供的原生一次性派发与后台任务。需要指定文件、模型、独立标签和续聊时使用 `cursor_code`。后台任务通过 DSH 的 `job_output` / `job_kill` 查看和取消。现在的续聊接口是 `continueSession`，没有实现 Cursor 的 `send_message` 持久收件箱。
+
+## 6. 常见问题
+
+| 现象 | 检查与处理 |
+| --- | --- |
+| 按包名安装返回 404 | `0.11.0` 起已发布到 npm 公共源；仍 404 时确认 registry 指向公共源且包名拼写为 `dsh-cursor-dev`，或改用插件市场、上面的 Git 来源、已取得的源码目录或安装包 |
+| DSH 报告找不到 Cursor CLI | 检查 `agent status --format json`；确认 CLI 位于 DSH 可见的 PATH 或常见安装目录，然后重启 DSH。仍找不到时，在插件配置里设置 `command` 为可启动二进制、安装根目录、`agent.cmd`，或 `"node.exe" "index.js"`（非空时只走该路径） |
+| 未登录或账号不可用 | 在运行 DSH 的同一操作系统用户下执行 `agent login`，检查账号和网络状态 |
+| 面板选了 Auto，实际仍是其他模型 | 当前任务不会中途切换；新版请保存“锁定面板模型”。查看返回的 `modelSource` 与 `requestedModel`，确认是否有显式调用参数 |
+| 显示 usage limit | 检查 Cursor 账号额度和模型可用性；更换父模型不会改变 Cursor 账号额度 |
+| 父模型没有调用插件 | 确认插件已启用、工具允许使用且父模型支持工具调用；明确要求使用 `cursor_code` 或直接用斜杠命令 |
+| 有 `cursor_code`，没有 `cursor_subagent` | 确认所装版本包含原生接入、bundle 配置已应用，以及当前 profile 提供子智能体和任务服务；升级后重启 |
+| DSH 升到 0.2.1 后 `cursor_subagent` 不再有可点击的镜像子会话 | 0.2.1 起宿主只用一行 External 任务表示外部子智能体，本插件的镜像因此只保留在 `cursor_code` 路径；运行结果、取消和后台机制不变 |
+| 更新后页面还是旧的 | 检查更新的是当前 profile 中实际加载的包，再重启 DSH 并刷新浏览器；只修改另一份源码不会自动更新所有安装副本 |
+| 续聊没有原来的内容 | 确认父会话、`sessionLabel` 和工作区；检查是否重置过映射、删除过 Cursor 记录，或发生了加载失败回退 |
+| 想彻底开始新任务 | 使用新 `sessionLabel`，或对原标签设置 `resetSession:true`；不要只依赖 `continueSession:false` 清空历史 |
+| 提交几个任务但只运行一个 | 插件为避免 Cursor 的全局模型状态互相干扰，串行执行任务；后台派发也不会取消这个限制 |
+| 旧会话报工具生命周期日志损坏 | 更新镜像写入代码可防止新增同类错误；已经损坏的旧日志仍需要备份后单独修复，升级不会自动改写它们 |
+
+CLI 模型切换与任务执行使用同一个全局锁。进程可以缓存和回收，会话本身则通过 Cursor 持久存储恢复；“新起进程”不等于“全新历史”。
+
+## 7. 维护者分发前检查
+
+修改文档或本地源码不会自动发布给其他用户。分发新的功能前：
+
+1. 核对 [package.json](../package.json) 的版本与兼容性声明，为正式发布更新版本。
+2. 运行适当的测试；离线命令见 [README](../README.md#开发与验证)。完整 `npm test` 会包含需要真实账号的 CLI 测试。
+3. 在源码目录运行 `npm pack` 或 `pnpm pack`，检查包中包括 `lib/`、`cordis.patch.yml`、README、本文及截图。
+4. 使用独立的 DSH profile 验证安装包：安装、登录检测、父模型派发、结果返回、续聊和取消。
+5. 将确认过的改动推送并打 tag，或分发检查过的 `.tgz` 包。GitHub 安装需要代码已经推送；npm 包名安装需要实际完成 npm 发布。
+6. 在发布说明中明确新增能力、需要重启，以及旧配置的迁移步骤；发布后更新本文的来源与版本说明。
+
+安装包通过文件白名单收录内容，不应包含本机 profile、登录信息、会话日志、探测脚本或依赖目录。正式发布与本地测试快照应有清晰的版本区分。