dsh-cursor-dev 0.12.0 → 0.12.2

package/README.md

@@ -55,7 +55,7 @@ flowchart LR
 3. 按 DSH 提示完成加载；涉及后台代码更新时重启 DSH，然后刷新页面。在 Cursor 面板中选择模型并保存。
 4. 明确告诉父模型使用 `cursor_code`，或者用下面的斜杠命令派发第一个任务。
 
-**版本说明（2026-10-18 核对）：** `0.12.0` 已推送到公开仓库的 `main`，沿用 `0.11.1` 的 DSH `0.2.1-rc.2` 契约（外部子智能体契约、顶层 `engines.dsh: >=0.2.1-rc.2 <0.3.0-0`），并重做了面板的历史会话卡：列表收进限高滚动框、点标题即可整段折叠（选择记在浏览器本地），每行新增两段式**删除**，经新增的 `api/forget` 路由一并清掉索引记录、轨迹和镜像子会话。插件市场（dshmarket）已收录本插件（目录条目合并于 2026-10-17），可以直接在市场里找到并安装；npm 公共源上当前可安装的版本仍是 `0.11.1`（`0.12.0` 尚未发布，要这版删除/折叠功能请用 Git 来源）。要跟进后续改动请用 Git 来源；`.tgz` 是某一刻的固定快照。详见[安装来源与版本](docs/INSTALL.md#2-选择安装来源)。
+**版本说明（0.12.2）：** 本版加入额度耗尽保护：调用 `cursor_code` 或通过原生子智能体派发之前先检查 Cursor 用量，总、Auto、API 三个额度都到上限时直接拒绝并说明原因，不再把任务派出去后中途失败；用量接口暂时取不到时不拦截调用。`cursor_subagent` 现在也会生成可点击的对话子会话，面板里点运行中或已完成的行都能查看过程，不再报「没有可恢复的会话」。面板重排为额度四张卡片置顶、代理输入框移到模型选择上方、模型目录与来源说明折叠收起。DSH 兼容性仍为 `>=0.2.1-rc.2 <0.3.0-0`。插件市场已收录本插件，卡片版本随目录探测更新；npm 包名为 `dsh-cursor-dev`，实际已发布版本以 npm 的 `latest` 标签为准。要跟进后续改动请用 Git 来源；`.tgz` 是某一刻的固定快照。详见[安装来源与版本](docs/INSTALL.md#2-选择安装来源)。
 
 运行要求：DSH `>=0.2.1-rc.2 <0.3.0-0`（已在 `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)。
 
@@ -65,7 +65,7 @@ flowchart LR
 | --- | --- | --- |
 | `cursor_code` | 父模型派发完整任务，控制目录、模式、模型、会话与报告 | 工具结果回到调用它的父模型，包含答复、步骤和检测到的文件变更 |
 | `/cursor-subagent 任务内容` | 用户直接派发一次任务；可选前缀 `-m 模型` | 完成或失败后，插件把摘要交给原父代理继续处理 |
-| `cursor_subagent` | 当前源码新增的 DSH 原生一次性子智能体工具，可后台运行 | 使用 DSH 标准结果及后台任务机制；DSH 0.2.1 起这次运行在父会话里显示为一行 External 任务，可点击的镜像子会话只由 `cursor_code` 创建 |
+| `cursor_subagent` | 当前源码新增的 DSH 原生一次性子智能体工具，可后台运行 | 使用 DSH 标准结果及后台任务机制；父会话保留一行 External 任务，Cursor 面板里的会话行可直接打开实时镜像子对话 |
 
 例如，在一个空测试工作区发送：
 
@@ -169,17 +169,17 @@ flowchart LR
 
 ### 代理设置
 
-面板的「子智能体模型」卡片里有**代理**输入框，未设置时默认为空。
+面板的「子智能体模型」卡片里有**代理**输入框，未设置时默认为 `none`（直连）。
 
 | 取值 | 含义 |
 | --- | --- |
-| 留空（默认） | 自动探测：先看 `HTTPS_PROXY` 等环境变量，再看 Windows「Internet 选项」里的代理 |
-| `none` | 直连，不用代理 |
+| `none`（默认） | 直连，并从 CLI 子进程环境中移除继承的代理地址变量 |
+| 留空 | 自动探测：先看 `HTTPS_PROXY` 等环境变量，再看 Windows「Internet 选项」里的代理 |
 | `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` 及小写形式），并在模型卡片的「可选模型」那一行末尾显示**子进程出口**。面板保存后立刻生效，不必重启应用；如果填的值解析不了，那一行会直接说明。
+需要系统代理时，主动清空输入框并保存；插件会把探测到的地址写进子进程环境（`HTTPS_PROXY`、`HTTP_PROXY` 及小写形式），并在模型卡片的「可选模型」那一行末尾显示**子进程出口**。升级时已保存的空值仍表示自动探测，不会被改成 `none`。面板保存后对后续启动的子进程生效，不必重启应用；如果填的值解析不了，那一行会直接说明。
 
 模型卡片下方还有可搜索的模型浏览器：点一行设为面板模型，右边的开关决定它是否出现在上方下拉框里。关掉的模型只是藏起来（写入 `disabledModels`），点「保存」后生效，随时可以再打开——这样在完整目录有上百个模型时也能只留下写业务常用的几条。
 
@@ -194,7 +194,7 @@ 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`，共 216 项；上面那条命令跳过其中三个真实 CLI/账号测试，剩下 213 项离线测试必须全绿。真实测试需要 Cursor 登录和网络，执行任务会使用该账号额度。当前实现已通过 213 项离线测试，并完成两轮真实 Auto 调用、文件修改和上下文续接验证。打包使用 `npm pack` 或 `pnpm pack`，发布前按[分发检查](docs/INSTALL.md#7-维护者分发前检查)核对安装包和版本。
+完整测试命令为 `npm test`。上面的命令跳过三个真实 CLI/账号测试，不派发真实编码任务；其余 smoke 测试仍包含只读额度 HTTP 检查，因此并非完全离线。真实编码测试需要 Cursor 登录和网络，执行任务会使用该账号额度。Windows 下的 Keychain 测试因需要 POSIX shell 而跳过，不能据此认定 macOS 已验证；企业证书环境可使用 Node.js 的 `--use-system-ca`。打包使用 `npm pack` 或 `pnpm pack`，发布前按[分发检查](docs/INSTALL.md#7-维护者分发前检查)核对安装包和版本。
 
 ## English
 
@@ -220,7 +220,7 @@ See the [installation guide](docs/INSTALL.md) for detailed setup and troubleshoo
 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. The history list keeps one row per run forever, so it sits in a height-capped scroll box and folds away when you click its heading (the choice is remembered); a row's **Delete** link clears that run's index record, journal and mirrored child — the same chain `resetSession` uses — and arms on the first click so the irreversible second click is deliberate.
 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-18**, version `0.12.0` is pushed to `main` on the public repository and keeps the DSH `0.2.1-rc.2` contract from `0.11.1` (the external-subagent contract and `engines.dsh: >=0.2.1-rc.2 <0.3.0-0` at the package top level), and reworks the panel's history card: the list sits in a height-capped scroll box, folds away from its heading (remembered per browser), and each row gains a two-click **Delete** that clears the index record, journal and mirrored child through a new `api/forget` route. The dsh-market catalog already lists this plugin (entry merged 2026-10-17), so it can be installed from the market; `0.11.1` is the version currently on the public npm registry as `dsh-cursor-dev` (`0.12.0` is not published yet, so use the Git source for the fold/delete work). Use the Git source to follow later changes; a `.tgz` is a fixed snapshot.
+Version `0.12.2` adds quota exhaustion protection: before `cursor_code` or a native subagent call starts, the plugin reads Cursor usage and refuses the call, explaining why, when the total, Auto and API buckets are all at their limit — instead of dispatching a run that later fails mid-way. A usage lookup that cannot be completed never blocks a call. `cursor_subagent` now also creates a clickable transcript child, so rows for running and finished runs open in the panel instead of reporting that no durable conversation exists. The panel puts the four quota cards first, moves the proxy input above the model picker, and folds the model catalogue and the source/egress notes. DSH compatibility remains `>=0.2.1-rc.2 <0.3.0-0`. The dsh-market catalog already lists this plugin and updates its displayed version on subsequent probes. The public npm package is `dsh-cursor-dev`; its `latest` tag identifies the published version. Use the Git source to follow later changes; a `.tgz` is a fixed snapshot.
 
 Requirements: DSH `>=0.2.1-rc.2 <0.3.0-0` (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.
 
@@ -239,7 +239,7 @@ The default model order is call argument → saved panel choice → plugin confi
 
 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.
+Cursor executes externally. From DSH 0.2.1 on, the host writes a single non-interactive `External` row for a `cursor_subagent` run. Both entrances also create a real transcript child that the Cursor panel opens while the first turn is running. The native service keeps its own lifecycle id; the separate transcript child does not add a duplicate catalog row. 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.
 

package/docs/INSTALL.md

@@ -38,15 +38,15 @@ agent status --format json
 
 ## 2. 选择安装来源
 
-**发布状态（2026-10-18 核对）：** 公共 GitHub 仓库存在，`0.12.0` 已推送到 `main`（沿用 `0.11.1` 的 DSH `0.2.1-rc.2` 外部子智能体契约与顶层 `engines.dsh: >=0.2.1-rc.2 <0.3.0-0`，并重做历史会话卡：限高滚动、可折叠、每行可删除）。插件市场（dshmarket）的目录条目已于 2026-10-17 合并，可以直接在市场里找到本插件；npm 公共源上当前为 `0.11.1`，`0.12.0` 尚未发布——要用折叠与删除功能请装 Git 来源，市场卡片的版本号要等发布后才会更新。
+**当前源码版本：** `0.12.2`，新增额度耗尽保护（三个额度都到上限时提前拒绝，用量取不到时不拦截），`cursor_subagent` 生成的子会话可在面板点开查看轨迹，面板重排为额度置顶、代理输入框在模型选择上方。DSH 兼容性保持 `>=0.2.1-rc.2 <0.3.0-0`。npm 包名为 `dsh-cursor-dev`，实际已发布版本以 npm 的 `latest` 标签为准。插件市场已收录本插件，卡片版本随目录探测更新。
 
 | 你要安装的内容 | 安装来源 |
 | --- | --- |
 | 插件市场里的本插件 | 市场条目解析为 `github:Dclef/dsh-cursor-dev`，安装后会跟随仓库默认分支 |
-| npm 公共源上的已发布版本 | `dsh-cursor-dev`（`0.11.0` 起可用，按包内 `files` 白名单安装，当前为 `0.11.1`；`0.12.0` 尚未发布） |
+| npm 公共源上的已发布版本 | `dsh-cursor-dev`（`0.11.0` 起可用，按包内 `files` 白名单安装，版本以 npm 的 `latest` 标签为准） |
 | 公开仓库的当前版本（推荐） | `git+https://github.com/Dclef/dsh-cursor-dev.git` |
 | 你本地的源码目录 | 该目录的绝对路径，例如 `D:/plugins/dsh-cursor-dev` |
-| 维护者提供的源码快照或发布包 | `.tgz` 文件的绝对路径，例如 `D:/Downloads/dsh-cursor-dev-0.12.0.tgz` |
+| 维护者提供的源码快照或发布包 | `.tgz` 文件的绝对路径，例如 `D:/Downloads/dsh-cursor-dev-0.12.2.tgz` |
 
 表中本地路径是示例，需要换成实际位置。npm 来源取 registry 上发布的最新版本；Git 来源会取得仓库默认分支的最新提交；`.tgz` 是某一刻的固定快照——要跟进后续改动就用 Git 来源。
 
@@ -88,7 +88,7 @@ dsh plugin add "/home/you/plugins/dsh-cursor-dev"
 安装收到的包：
 
 ```powershell
-dsh plugin add "D:/Downloads/dsh-cursor-dev-0.12.0.tgz"
+dsh plugin add "D:/Downloads/dsh-cursor-dev-0.12.2.tgz"
 ```
 
 终端没有 `dsh` 命令时，使用桌面插件管理即可。不要把在任意项目目录执行 `npm install` 当成已经在 DSH 当前 profile 中启用插件。
@@ -121,7 +121,7 @@ http://127.0.0.1:19387/plugins/dsh-cursor-dev/
 
 ### 模型列表不全时先看代理
 
-同一张卡片上有 **代理** 输入框，留空即为自动探测，正常情况不需要填。它决定的是**插件启动的 CLI 子进程**走哪条网络出口。
+同一张卡片上有 **代理** 输入框，默认值为 `none`（直连）；主动留空表示自动探测系统代理，填写 URL 表示显式代理。它决定的是**插件启动的 CLI 子进程**走哪条网络出口。升级时已保存的空值仍表示系统代理，不会被覆盖。
 
 Cursor CLI 只读 `HTTPS_PROXY` / `HTTP_PROXY`（以及小写形式），不读注册表，也不读 `ALL_PROXY`。代理只写在 Windows「Internet 选项」里的机器，子进程会直连 Cursor，而直连只返回模型目录的一部分——本机实测 `agent --list-models` 为 31 个（走代理 265 个），面板真正使用的 ACP 清单为 10 个（走代理 46 个）。
 
@@ -129,8 +129,8 @@ Cursor CLI 只读 `HTTPS_PROXY` / `HTTP_PROXY`（以及小写形式），不读
 
 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`。
+3. 如果显示 `direct (no proxy configured)`，而你想使用系统代理，清空 **代理** 框并保存；也可以填上地址（如 `http://127.0.0.1:7890`）使用显式代理。保存后对后续启动的子进程生效，不需要重启应用；面板会自动重新读取模型列表。
+4. 想强制直连时填 `none`，插件会从 CLI 子进程环境中移除继承的代理地址变量。
 
 也可以在终端里直接对照，两个数字应当与面板一致：
 
@@ -195,14 +195,14 @@ continueSession 设为 true。让 Cursor 说明上一轮做了什么，再核对
 
 | 现象 | 检查与处理 |
 | --- | --- |
-| 按包名安装返回 404 | `0.11.0` 起已发布到 npm 公共源（当前 `0.11.1`）；仍 404 时确认 registry 指向公共源且包名拼写为 `dsh-cursor-dev`，或改用插件市场、上面的 Git 来源、已取得的源码目录或安装包 |
+| 按包名安装返回 404 | 确认 registry 指向 npm 公共源且包名拼写为 `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` 路径；运行结果、取消和后台机制不变 |
+| 点击运行中的 `cursor_subagent` 会话只显示运行轨迹 | 更新插件后台并重启 DSH；新版从首轮运行时即建立镜像，在 Cursor 面板中点击会话键即可打开子对话。宿主仍保留一行 External 任务；旧版本留下的已完成记录可在历史会话中读回 |
 | 更新后页面还是旧的 | 检查更新的是当前 profile 中实际加载的包，再重启 DSH 并刷新浏览器；只修改另一份源码不会自动更新所有安装副本 |
 | 续聊没有原来的内容 | 确认父会话、`sessionLabel` 和工作区；检查是否重置过映射、删除过 Cursor 记录，或发生了加载失败回退 |
 | 想彻底开始新任务 | 使用新 `sessionLabel`，或对原标签设置 `resetSession:true`；不要只依赖 `continueSession:false` 清空历史 |
@@ -216,7 +216,7 @@ CLI 模型切换与任务执行使用同一个全局锁。进程可以缓存和
 修改文档或本地源码不会自动发布给其他用户。分发新的功能前：
 
 1. 核对 [package.json](../package.json) 的版本与兼容性声明，为正式发布更新版本。
-2. 运行适当的测试；离线命令见 [README](../README.md#开发与验证)。完整 `npm test` 会包含需要真实账号的 CLI 测试。
+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 发布。

package/docs/skill-drafts/subagent-model-routing/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: subagent-model-routing
+description: 调用 subagent、选择子智能体模型或排查 provider/model/reasoning_effort 路由错误时使用；默认省略路由字段，指定前查询目录，禁止空字符串与猜测路由。
+---
+
+# 子智能体模型路由与参数校验
+
+## 适用范围
+
+调用 `subagent`、选择子智能体的提供方、模型或推理等级，或排查以下错误时使用：
+
+- `Error: child LLM \`provider\` must be non-empty`
+- 子智能体模型路由不被当前 Session 允许
+- provider 与 model 不成对，或推理等级无效
+
+本技能只约束子智能体模型参数。用户明确指定专家、专家团或其他工具时，遵守对应工具的要求。
+
+## 调用规则
+
+1. **使用默认模型时，省略 provider、model、reasoning_effort 三个键。** 不用空字符串、空白字符串、null 或猜测值表示默认。
+2. **显式指定模型前，先调用 list_subagent_models。** 先查提供方，再按需查模型及其推理等级。使用返回的 ID，不从父会话模型、自身模型身份或显示名称推断。
+3. **provider 和 model 必须成对且非空。** 只有一个字段时，先补齐可验证的信息；本意为默认时，删除全部路由字段。
+4. **reasoning_effort 只使用目标模型公布的有效值。** 不要求固定等级时省略；不要硬套父模型等级。
+5. **目录与当前 Session 的允许路由分别校验。** 目录存在不保证当前会话允许。如果路由被拒绝，不猜另一个提供方、不反复碰撞。默认模型满足用户要求时，删除全部路由字段重试一次；用户锁定模型时，说明具体限制，不擅自替换。
+6. **不同工具的模型接口不能混用。** subagent 的路由、cursor_code 的 Cursor 模型、cursor_subagent 的默认配置和专家工具的专家名称不是同一接口。subagent_fork 不接受这些模型覆盖字段。
+7. **只发送实际需要的受支持字段。** 不为填满对象而给可选字段补空字符串。若调用层强制要求这些字段，检查正确调用方式；仍无法表达省略时报告接口限制，不伪造 ID。
+
+## 发送前检查
+
+- 默认调用：三个可选键都不存在。
+- 指定调用：provider/model 是已查证、成对的非空 ID。
+- reasoning_effort 若存在，与目标模型匹配。
+- prompt 是完整、可独立执行的任务说明；cwd 是实际工作区。
+- 没有把父会话或其他工具的模型名称当作已验证路由。
+
+## 默认调用示例
+
+```json
+{
+  "cwd": "E:/example/project",
+  "description": "核对额度显示逻辑",
+  "prompt": "只读检查当前工作区的额度规范化和显示逻辑，给出字段语义与最小修复建议，不修改文件。"
+}
+```
+
+指定模型时，查询目录后把返回的 provider/model 成对加入。仅在需要固定、且已确认有效时加入 reasoning_effort。本技能不保存固定提供方、模型或等级示例值，以免以后照抄失效。
+
+禁止发送：
+
+```json
+{
+  "provider": "",
+  "model": "",
+  "reasoning_effort": ""
+}
+```
+
+## 失败后的处理
+
+- provider must be non-empty：检查是否把可选字段传成空字符串；默认分支删除三个键，再调用一次。
+- provider/model 不成对：查询目录并补齐，或切回省略全部路由字段的默认分支。
+- 路由不允许：按会话权限限制处理，不通过改拼写绕过。
+- 推理等级无效：查询目标模型详情；不需要固定时省略。
+- 参数校验失败时，子智能体没有启动。只有成功结果包含子智能体 ID，才记为已启动；交付前必须收集实际结果。
+
+修正参数后继续用户已授权的原任务；不要将工具参数错误归因于用户项目或账户额度。

package/lib/index.js

@@ -26,6 +26,7 @@ import { registerCursorCommand } from './command.js';
 import { createMirrorHub } from './mirror.js';
 import { createRouteFence } from './fence.js';
 import { UsageClient, registerUsageRoutes } from './usage.js';
+import { CursorQuotaGuard } from './quota-guard.js';
 import { effectiveModel, readSettings, registerSettingsRoutes, resolveModelSelection } from './settings.js';
 import { createNativeCursorBridge } from './native-provider.js';
 import { describeProxy, proxySettingIsDirect, resolveChildProxy, withProxyEnvironment } from './proxy.js';
@@ -174,6 +175,8 @@ export function apply(ctx, config) {
     // transcript Cursor actually produced. `bind` learns the `agents` service
     // from a context that declared the dependency, because reading it off this
     // fiber answers `undefined` while the agent loop is still activating.
+    const usage = new UsageClient({ baseUrl: config.usageBaseUrl });
+    const quotaGuard = new CursorQuotaGuard(usage);
     const mirrors = createMirrorHub({ logger, maxChildDepth: config.maxChildDepth });
     const pool = resolved === undefined
         ? new UnavailablePool()
@@ -195,6 +198,7 @@ export function apply(ctx, config) {
         index,
         logger,
         mirrors,
+        quotaGuard,
         maxScanFiles: config.maxScanFiles,
         maxChildDepth: config.maxChildDepth,
         unavailable,
@@ -207,7 +211,7 @@ export function apply(ctx, config) {
         resolveDefaultMode: () => readSettings(dataDir).mode,
     });
 
-    const native = createNativeCursorBridge({ execute: rawTool.execute, mirrors, maxChildDepth: config.maxChildDepth });
+    const native = createNativeCursorBridge({ execute: rawTool.execute, mirrors, quotaGuard, maxChildDepth: config.maxChildDepth });
     const tool = { ...rawTool, execute: (args, exec) => native.execute(args, exec) };
     const disposeTool = ctx.tools.register({ ...tool, name: config.toolName });
 
@@ -256,6 +260,8 @@ export function apply(ctx, config) {
         dataDir,
         logger,
         mirrors,
+        usage,
+        quotaGuard,
         // The status route asks the CLI whether the account is signed in, which
         // means spawning it — same environment the ACP child gets.
         env: childEnvironment,
@@ -304,9 +310,9 @@ function mountHttpSurfaces(ctx, config, deps) {
             // the dashboard RPC itself and serves both a JSON view and a
             // self-contained HTML dashboard.
             if (config.usageUi === true) {
-                const usage = new UsageClient({ baseUrl: config.usageBaseUrl });
                 disposers.push(registerUsageRoutes(webCtx, {
-                    usage,
+                    usage: deps.usage,
+                    quotaGuard: deps.quotaGuard,
                     pool: deps.pool,
                     journal: deps.journal,
                     index: deps.index,

package/lib/native-provider.js

@@ -5,6 +5,7 @@ import { isAbsolute } from 'node:path';
 import { stat } from 'node:fs/promises';
 import { renderCursorReport } from './tool.js';
 import { resolveChildDepth } from './mirror.js';
+import { quotaBlockedMessage } from './quota-guard.js';
 
 export const CURSOR_PROVIDER = 'cursor';
 
@@ -33,7 +34,7 @@ function failure(error, cancelled = false) {
 
 /** Generic native calls use the panel settings and get their own conversation.
  * The cursor_code adapter supplies provider-private arguments for rich controls. */
-export function createCursorProvider({ execute, mirrors, maxChildDepth }) {
+export function createCursorProvider({ execute, mirrors, quotaGuard, maxChildDepth }) {
     const active = new Set();
     let closed = false;
     return {
@@ -52,15 +53,17 @@ export function createCursorProvider({ execute, mirrors, maxChildDepth }) {
                 throw new Error('cursor: native prompts must contain text blocks only');
             const task = request.prompt.map(block => block.text).join('\n\n').trim();
             if (!task) throw new Error('cursor: native prompt must not be empty');
+            const quotaStatus = await quotaGuard?.check?.();
+            if (quotaStatus?.blocked === true)
+                throw new Error(quotaBlockedMessage(quotaStatus));
             const originalParent = request.parent;
             // The recursion budget is the plugin's own now that the host leaves it
             // to the provider (`maxDepth: provider-managed`); refuse before any
             // process, child row, or lifecycle event exists.
             if (typeof maxChildDepth === 'number') resolveChildDepth(originalParent, maxChildDepth);
-            // dsh >= 0.2.1 starts native providers through the subagents service.
-            // That service only accepts an unregistered child id and models such a
-            // child as an external row without a local transcript, so the mirror
-            // belongs to the cursor_code bridge, which starts the provider directly.
+            // Keep the service's external lifecycle id separate from the local
+            // transcript child. The mirror is opened explicitly by the panel
+            // and does not publish another catalog row.
             const viaService = request.cursor === undefined;
             const args = request.cursor?.args ?? { task, sessionLabel: `native-${randomUUID()}` };
             const requestedCwd = typeof request.cwd === 'string' && request.cwd !== ''
@@ -82,15 +85,14 @@ export function createCursorProvider({ execute, mirrors, maxChildDepth }) {
             let settled = false;
             let disposal;
             const cursorLifecycle = {
-                descriptor: request.descriptor,
+                // The service descriptor belongs to its external row.
+                descriptor: viaService ? undefined : request.descriptor,
                 label: request.label,
                 acquired(session) { leasedSession = session; },
-                ...(viaService ? { mirror: false } : {
-                    opened(entry, key) {
-                        opened = { entry, key };
-                        ready.resolve();
-                    },
-                }),
+                opened(entry, key) {
+                    opened = { entry, key };
+                    ready.resolve();
+                },
             };
             const execution = Promise.resolve().then(() => execute({ ...args, workspaceRoot: cwd }, {
                 agent: originalParent,
@@ -125,8 +127,8 @@ export function createCursorProvider({ execute, mirrors, maxChildDepth }) {
                 }
             })().finally(() => active.delete(dispose));
             active.add(dispose);
-            // The service owns the child row for external runs; hand it a fresh id
-            // and let it observe `result`, without waiting for a mirror child.
+            // Publish the external lifecycle immediately, including while queued.
+            // Its id stays distinct from the panel's real transcript child.
             if (viaService)
                 return { id: `cursor-${randomUUID()}`, result, cursorReport, dispose };
             try {
@@ -168,13 +170,13 @@ function announceMirror(parent, child, label) {
 }
 
 /** Late-bound native service; absence preserves the existing standalone tool. */
-export function createNativeCursorBridge({ execute, mirrors, maxChildDepth }) {
+export function createNativeCursorBridge({ execute, mirrors, quotaGuard, maxChildDepth }) {
     let binding;
     return {
         bind(ctx) {
             const runtime = ctx.get?.('subagents');
             if (typeof runtime?.registerProvider !== 'function') return;
-            const provider = createCursorProvider({ execute, mirrors, maxChildDepth });
+            const provider = createCursorProvider({ execute, mirrors, quotaGuard, maxChildDepth });
             const unregister = runtime.registerProvider(provider);
             const current = { runtime, provider };
             binding = current;

package/lib/proxy.js

@@ -371,15 +371,16 @@ export function proxyEnvironment(proxy) {
 /**
  * `env` with the proxy variables merged in.
  *
- * A direct connection returns the caller's own object untouched, so a machine
- * with no proxy spawns children with exactly the environment it always had.
+ * A direct connection removes inherited proxy variables without changing the
+ * caller's environment.
  *
  * @param env - the environment to start from.
  * @param proxy - a resolved proxy, or undefined for a direct connection.
  */
 export function withProxyEnvironment(env, proxy) {
     const additions = proxyEnvironment(proxy);
-    if (Object.keys(additions).length === 0) return env;
+    if (Object.keys(additions).length === 0)
+        return Object.fromEntries(Object.entries(env).filter(([key]) => !PROXY_ENV_KEYS.includes(key)));
     return { ...env, ...additions };
 }
 
@@ -389,11 +390,8 @@ export function withProxyEnvironment(env, proxy) {
  * The panel's `proxy` setting drives this, and its three kinds of answer mean
  * genuinely different things:
  *
- *   - `''` (the default) is AUTO: ask the machine. This is what makes the full
- *     model catalogue appear without anyone configuring anything, and it is why
- *     the default is not "direct".
- *   - `none` (also `direct`, `off`, `no`) is the escape hatch for a machine
- *     whose registry proxy is stale or wrong.
+ *   - `none` (the default; also `direct`, `off`, `no`) connects directly.
+ *   - `''` is AUTO: ask the environment, then the machine.
  *   - anything else is taken literally as a proxy endpoint, in every shape
  *     {@link parseProxy} accepts.
  *
@@ -402,7 +400,7 @@ export function withProxyEnvironment(env, proxy) {
  * @returns the resolved proxy, or undefined for a direct connection.
  */
 export async function resolveChildProxy(configured, options = {}) {
-    const value = typeof configured === 'string' ? configured.trim() : '';
+    const value = typeof configured === 'string' ? configured.trim() : 'none';
     if (DIRECT_PROXY_VALUES.has(value.toLowerCase())) return undefined;
     if (value.length === 0) return await readSystemProxy(options);
 

package/lib/quota-guard.js

@@ -0,0 +1,113 @@
+const RECHECK_MS = 30_000;
+
+const QUOTA_ERROR = /\b(?:resource[_ -]?exhausted|insufficient[_ -]?quota|quota[_ -]?exceeded|credit[_ -]?balance[_ -]?exhausted)\b|\b(?:insufficient|out of|no remaining|zero|empty|exhausted|depleted)\b.{0,50}\b(?:cursor\s+)?(?:usage|quota|credits?|balance)\b|\b(?:cursor\s+)?(?:usage|quota|credits?|balance)\b.{0,50}\b(?:exhausted|depleted|used up|is empty|limit (?:has been )?reached|limit exceeded|insufficient)\b|\b(?:you(?:'ve| have) hit your usage limit|usage limit has been reached|no usage credits remaining)\b/i;
+
+/** Only the explicit upstream bucket percentages can establish global exhaustion. */
+export function usageQuotaExhausted(usage) {
+    const percentages = ['total', 'auto', 'api'].map(name => usage?.[name]?.percentUsed);
+    return percentages.every(value => typeof value === 'number' && Number.isFinite(value) && value >= 100);
+}
+
+/** Inspect an actual Cursor/ACP failure, never the dashboard's advisory prose. */
+export function cursorQuotaFailure(error) {
+    const code = error?.code;
+    if (code === 8 || /^(?:RESOURCE_EXHAUSTED|INSUFFICIENT_QUOTA|QUOTA_EXCEEDED|CREDIT_BALANCE_EXHAUSTED)$/i.test(String(code ?? '')))
+        return true;
+    const parts = [error?.name, error?.message, error?.data?.message, error?.cause?.message];
+    if (typeof error === 'string') parts.push(error);
+    try {
+        if (error !== null && typeof error === 'object') parts.push(JSON.stringify(error));
+    }
+    catch { /* An unstringifiable error can still match its message/code. */ }
+    return QUOTA_ERROR.test(parts.filter(value => typeof value === 'string').join(' '));
+}
+
+export function quotaBlockedMessage(state) {
+    return state?.source === 'cursor-error'
+        ? 'CURSOR_QUOTA_EXHAUSTED: Cursor reported that its usage is exhausted. New Cursor child-agent runs are paused until a successful quota refresh confirms capacity has returned.'
+        : 'CURSOR_QUOTA_EXHAUSTED: Cursor reports that all usage buckets are exhausted. No child agent was started. Check the quota panel and retry after a successful refresh confirms capacity has returned.';
+}
+
+/** Shared gate for native subagent starts and direct cursor_code calls. */
+export class CursorQuotaGuard {
+    #usage;
+    #now;
+    #recheckMs;
+    #state = { blocked: false, source: 'unknown' };
+    #lastCheckAt = 0;
+    #revision = 0;
+    #inflight;
+
+    constructor(usage, options = {}) {
+        this.#usage = usage;
+        this.#now = options.now ?? Date.now;
+        this.#recheckMs = options.recheckMs ?? RECHECK_MS;
+    }
+
+    snapshot() {
+        return { ...this.#state };
+    }
+
+    async check() {
+        const now = this.#now();
+        if (this.#state.blocked && now - this.#lastCheckAt < this.#recheckMs)
+            return this.snapshot();
+        if (this.#inflight !== undefined)
+            return this.#inflight;
+
+        const revision = this.#revision;
+        this.#inflight = (async () => {
+            let snapshot;
+            try {
+                snapshot = await this.#usage?.get?.({ force: this.#state.blocked });
+            }
+            catch {
+                snapshot = undefined;
+            }
+            this.#lastCheckAt = this.#now();
+            if (revision !== this.#revision && this.#state.blocked)
+                return this.snapshot();
+            return this.observeUsage(snapshot);
+        })().finally(() => { this.#inflight = undefined; });
+        return this.#inflight;
+    }
+
+    observeUsage(snapshot) {
+        if (snapshot?.ok !== true) {
+            if (!this.#state.blocked)
+                this.#state = { blocked: false, source: 'unknown' };
+            return this.snapshot();
+        }
+        const fetchedAt = snapshot.fetchedAt;
+        if (this.#state.blocked
+            && (!Number.isFinite(fetchedAt) || fetchedAt <= this.#state.since))
+            return this.snapshot();
+        this.#lastCheckAt = this.#now();
+        if (usageQuotaExhausted(snapshot.usage)) {
+            this.#state = {
+                blocked: true,
+                source: 'usage',
+                reason: 'all-usage-buckets-exhausted',
+                since: Number.isFinite(fetchedAt) ? fetchedAt : this.#now(),
+            };
+        }
+        else {
+            this.#state = { blocked: false, source: 'usage' };
+        }
+        return this.snapshot();
+    }
+
+    observeFailure(error) {
+        if (!cursorQuotaFailure(error))
+            return this.snapshot();
+        this.#revision += 1;
+        this.#lastCheckAt = this.#now();
+        this.#state = {
+            blocked: true,
+            source: 'cursor-error',
+            reason: 'cursor-reported-exhaustion',
+            since: this.#lastCheckAt,
+        };
+        return this.snapshot();
+    }
+}

package/lib/session-pool.js

@@ -57,6 +57,7 @@ export class SessionPool {
     /** Tail of the FIFO queue that serializes every Cursor turn. */
     #gate = Promise.resolve();
     #lockDepth = 0;
+    #activeKey;
 
     /**
      * @param config - plugin config (maxLiveSessions, sessionIdleMinutes, spawn/env).
@@ -99,6 +100,7 @@ export class SessionPool {
             modelChoice: entry.modelChoice,
             mode: entry.session.modes?.currentModeId,
             turns: entry.turns.length,
+            running: entry.key === this.#activeKey,
             reloaded: entry.reloaded,
             idleMs: Date.now() - entry.lastUsed,
             alive: entry.session.alive,
@@ -357,6 +359,7 @@ export class SessionPool {
      */
     async run(options, body) {
         const release = await this.#enter(options.signal);
+        this.#activeKey = options.key;
         try {
             options.signal?.throwIfAborted();
             const lease = await this.#acquire(options, options.signal);
@@ -373,6 +376,7 @@ export class SessionPool {
             }
         }
         finally {
+            this.#activeKey = undefined;
             release();
         }
     }

package/lib/settings.js

@@ -57,11 +57,7 @@ export function emptySettings() {
         modelPolicy: 'per-call',
         mode: '',
         language: '',
-        // Empty means "ask the machine", which on Windows finds the registry
-        // proxy. That default is the whole point: the child CLI does not read
-        // the registry itself, so without this it lists only the models the
-        // direct route publishes.
-        proxy: '',
+        proxy: 'none',
         // Models the operator switched off in the picker. A DENY list, not an
         // allow list, so a catalogue that gains entries keeps showing them: an
         // empty list means "everything the CLI knows about" and a fresh install
@@ -577,16 +573,16 @@ const MAX_PROXY_CHARS = 200;
 /**
  * Coerce the `proxy` setting.
  *
- * `''` means auto-detect and is the default; `none` means never proxy; anything
+ * `none` is the default and means never proxy; `''` means auto-detect; anything
  * else is an endpoint. Only the shape of the value is checked here — whether it
  * parses is `resolveChildProxy`'s job, and it can report that failure without
  * the settings file having to be valid first. An over-long value is dropped
  * rather than truncated, because half a URL is worse than none.
  */
 function proxySetting(value) {
-    if (typeof value !== 'string') return '';
+    if (typeof value !== 'string') return 'none';
     const text = value.trim();
-    return text.length > MAX_PROXY_CHARS ? '' : text;
+    return text.length > MAX_PROXY_CHARS ? 'none' : text;
 }
 
 /** Longest model id accepted in the picker's deny list; ids are short by nature. */