dsh-cursor-dev 0.12.0 → 0.12.1

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.1）：** 本版新增 macOS Keychain 登录凭据读取，修正 CLI 子进程的代理默认值和直连时的环境变量继承：未配置时为 `none`（直连），主动留空时使用系统代理，填写 URL 时使用显式代理。已有空值配置保持系统代理语义，面板仍使用原来的输入框，没有 UI 改版。macOS Keychain 路径尚未实机验证。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)。
 
@@ -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.1` adds macOS Keychain credential lookup and fixes the child CLI's proxy defaults and inherited environment: a missing setting means `none` (direct), an explicitly empty value follows the system proxy, and a URL selects an explicit proxy. Existing empty settings keep their meaning. The panel still uses the same text input; this is not a UI redesign. The macOS Keychain path has not been verified on a real Mac. 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.
 

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.1`，新增 macOS Keychain 登录凭据读取，并修正 CLI 子进程的默认直连与代理环境变量继承；面板没有 UI 改版。macOS Keychain 路径尚未实机验证。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.1.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.1.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,7 +195,7 @@ 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`，确认是否有显式调用参数 |
@@ -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/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/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. */

package/lib/usage.js

@@ -12,6 +12,7 @@
  * is created, and the token is never logged, echoed, or returned over HTTP.
  */
 import { readFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { proxyAwareFetch, readSystemProxy, describeProxy } from './proxy.js';
@@ -36,8 +37,59 @@ const REQUEST_TIMEOUT_MS = 15_000;
 const RESTORE_TIMEOUT_MS = 60_000;
 
 /**
- * Cursor's own auth store. The CLI keeps the tokens here rather than under
- * `~/.cursor`, which is what makes this discoverable at all.
+ * The macOS Keychain account the Cursor CLI stores its login under.
+ *
+ * The CLI's credential store is not one file across platforms: on macOS it
+ * keeps the login in the login Keychain as generic-password items named
+ * `cursor-access-token`, `cursor-refresh-token` and `cursor-api-key`, all under
+ * the account `cursor-user`. Windows and Linux write the same domain
+ * ("cursor") to `auth.json` inside the per-user config directory instead. Both
+ * stores are tried below, because the store is a user-visible CLI setting
+ * (`AGENT_CLI_CREDENTIAL_STORE=file` opts a macOS install into the file), and
+ * the earlier builds of this plugin only knew the file spelling.
+ */
+const KEYCHAIN_ACCOUNT = 'cursor-user';
+const KEYCHAIN_ACCESS_TOKEN_SERVICE = 'cursor-access-token';
+
+/**
+ * Every `auth.json` location the CLI may have written, in lookup order.
+ *
+ * The CLI's file credential store (`../cli-credentials` in the CLI bundle) names
+ * the file after its credential-store domain: `%APPDATA%\Cursor\auth.json` on
+ * Windows (that platform title-cases the domain), `$XDG_CONFIG_HOME/cursor/auth.json`
+ * on Linux, and `~/.cursor/auth.json` when the macOS CLI is forced onto the file
+ * store. `~/.config/Cursor` is the spelling earlier builds of this plugin
+ * assumed, so it stays in the list for machines whose token was already put
+ * there. {@link authFilePath} keeps returning that historical single answer.
+ */
+export function authFileCandidates(env = process.env) {
+    const paths = [];
+    const add = value => {
+        if (typeof value === 'string' && value !== '' && !paths.includes(value))
+            paths.push(value);
+    };
+    const appData = typeof env.APPDATA === 'string' ? env.APPDATA.trim() : '';
+    if (appData !== '')
+        add(join(appData, 'Cursor', 'auth.json'));
+    const xdg = typeof env.XDG_CONFIG_HOME === 'string' ? env.XDG_CONFIG_HOME.trim() : '';
+    if (xdg !== '')
+        add(join(xdg, 'cursor', 'auth.json'));
+    // Honouring HOME through the injected environment keeps the "env is the
+    // only input" contract the rest of this section promises (and lets a test
+    // point the reader at a throw-away directory).
+    const home = typeof env.HOME === 'string' && env.HOME.trim() !== '' ? env.HOME.trim() : homedir();
+    add(join(home, '.cursor', 'auth.json'));
+    add(join(home, '.config', 'cursor', 'auth.json'));
+    add(join(home, '.config', 'Cursor', 'auth.json'));
+    return paths;
+}
+
+/**
+ * The file the plugin has always named for the token.
+ *
+ * Kept as the historical public answer ("where is the token") for callers and
+ * error messages; the reader itself walks {@link authFileCandidates}, because
+ * the real store is Keychain on macOS.
  */
 export function authFilePath(env = process.env) {
     const appData = env.APPDATA;
@@ -46,33 +98,139 @@ export function authFilePath(env = process.env) {
     return join(homedir(), '.config', 'Cursor', 'auth.json');
 }
 
+/**
+ * Read one generic password out of the macOS login Keychain.
+ *
+ * The CLI itself reads these items with `/usr/bin/security` — that is exactly
+ * what its own keychain credential store does — so using the same tool keeps
+ * this out-of-band read on the code path Cursor's login already relies on: no
+ * native binding, no extra dependency, and the same failure modes when the
+ * keychain is locked or the item is missing. `-g` prints the secret to stderr
+ * as either `password: 0x<hex>` or, on newer macOS releases, as
+ * `password: "<text>"`; both shapes are decoded here. The value is returned to
+ * the caller and never logged.
+ *
+ * @param service - keychain item service name (e.g. `cursor-access-token`).
+ * @param account - keychain item account; the CLI always uses `cursor-user`.
+ * @param options - `securityPath` and `timeoutMs` exist for tests.
+ */
+async function keychainPassword(service, account = KEYCHAIN_ACCOUNT, options = {}) {
+    const executable = options.securityPath ?? '/usr/bin/security';
+    const timeout = options.timeoutMs ?? 5000;
+    return await new Promise(resolve => {
+        try {
+            execFile(executable, ['find-generic-password', '-a', account, '-s', service, '-g'], { timeout, windowsHide: true }, (error, stdout, stderr) => {
+                if (error !== null) {
+                    // A locked keychain asks the user for approval through a GUI
+                    // dialog; the timeout is what stops that from hanging a panel
+                    // refresh, and the error must say so instead of claiming the
+                    // item does not exist.
+                    const reason = error.killed === true
+                        ? `the keychain read timed out after ${timeout}ms (is the login keychain locked?)`
+                        : error.message;
+                    resolve({ ok: false, error: `no keychain item "${service}" for "${account}": ${reason}` });
+                    return;
+                }
+                const text = `${stdout ?? ''}\n${stderr ?? ''}`;
+                const hex = /^password: 0x([0-9a-fA-F]+)$/m.exec(text);
+                const quoted = /^password: "(.*)"$/m.exec(text);
+                let password;
+                if (hex !== null)
+                    password = Buffer.from(hex[1], 'hex').toString('utf8');
+                else if (quoted !== null)
+                    password = quoted[1].replace(/\\"/g, '"');
+                if (typeof password !== 'string' || password === '') {
+                    resolve({ ok: false, error: `cannot parse the keychain answer for "${service}"` });
+                    return;
+                }
+                resolve({ ok: true, password });
+            });
+        }
+        catch (error) {
+            resolve({ ok: false, error: `cannot run ${executable}: ${errorText(error)}` });
+        }
+    });
+}
+
 /**
  * Read the access token the CLI is already signed in with.
  *
+ * Every store the CLI may have used is tried, in the order the CLI itself
+ * prefers on this platform: an explicit `CURSOR_AUTH_TOKEN` first (the CLI
+ * accepts the same variable), then the macOS Keychain, then the file stores.
+ * `AGENT_CLI_CREDENTIAL_STORE` is honoured so a CLI deliberately running on the
+ * file store, or on the memory-only store, is not shadowed by a stale item.
  * The token is deliberately returned to the caller and never logged.
  *
  * @param env - environment source (injectable for tests).
+ * @param options - `platform`, `securityPath` and `timeoutMs` exist for tests.
  */
-export async function readAccessToken(env = process.env) {
-    const path = authFilePath(env);
-    let raw;
-    try {
-        raw = await readFile(path, 'utf8');
-    }
-    catch (error) {
-        return { ok: false, path, error: `cannot read ${path}: ${errorText(error)}` };
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (error) {
-        return { ok: false, path, error: `cannot parse ${path}: ${errorText(error)}` };
+export async function readAccessToken(env = process.env, options = {}) {
+    const explicit = typeof env.CURSOR_AUTH_TOKEN === 'string' ? env.CURSOR_AUTH_TOKEN.trim() : '';
+    if (explicit !== '')
+        return { ok: true, path: 'CURSOR_AUTH_TOKEN', token: explicit };
+
+    const platform = options.platform ?? process.platform;
+    const store = typeof env.AGENT_CLI_CREDENTIAL_STORE === 'string' ? env.AGENT_CLI_CREDENTIAL_STORE.trim() : '';
+    const filePaths = authFileCandidates(env);
+    const attempted = [];
+
+    // `memory` keeps the login in the CLI process only; nothing else can read
+    // it, so only the environment variable above could have answered.
+    if (store !== 'memory') {
+        if (platform === 'darwin' && store !== 'file') {
+            const keychain = await keychainPassword(KEYCHAIN_ACCESS_TOKEN_SERVICE, KEYCHAIN_ACCOUNT, {
+                securityPath: options.securityPath,
+                timeoutMs: options.timeoutMs,
+            });
+            if (keychain.ok === true)
+                return { ok: true, path: `macOS keychain: ${KEYCHAIN_ACCESS_TOKEN_SERVICE} (${KEYCHAIN_ACCOUNT})`, token: keychain.password };
+            attempted.push(keychain.error);
+        }
+        for (const path of filePaths) {
+            let raw;
+            try {
+                raw = await readFile(path, 'utf8');
+            }
+            catch (error) {
+                attempted.push(`cannot read ${path}: ${errorText(error)}`);
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (error) {
+                attempted.push(`cannot parse ${path}: ${errorText(error)}`);
+                continue;
+            }
+            const token = parsed?.accessToken;
+            if (typeof token !== 'string' || token === '') {
+                attempted.push(`${path} has no accessToken field`);
+                continue;
+            }
+            return { ok: true, path, token };
+        }
     }
-    const token = parsed?.accessToken;
-    if (typeof token !== 'string' || token === '')
-        return { ok: false, path, error: `${path} has no accessToken field` };
-    return { ok: true, path, token };
+
+    const path = authFilePath(env);
+    const stores = [];
+    if (platform === 'darwin' && store !== 'file')
+        stores.push(`macOS keychain "${KEYCHAIN_ACCESS_TOKEN_SERVICE}"`);
+    stores.push(...filePaths);
+    // "Missing" is the normal signed-out state and repeating one ENOENT per
+    // candidate would bury the actionable sentence; a corrupt file or a locked
+    // keychain is worth quoting because it needs a different fix.
+    const failures = attempted.filter(reason => !/ENOENT|not be found|ItemNotFound/i.test(reason));
+    const parts = [store === 'memory'
+        ? `the Cursor CLI runs with AGENT_CLI_CREDENTIAL_STORE=memory, so its login is not readable by another process`
+        : `no Cursor login found (tried: ${stores.join(', ')})`];
+    if (store !== 'memory')
+        parts.push(`sign the CLI in with "agent login"`);
+    parts.push(`set CURSOR_AUTH_TOKEN to supply a token explicitly`);
+    if (failures.length > 0)
+        parts.push(`failures: ${failures.slice(0, 2).join('; ')}`);
+    return { ok: false, path, error: parts.join('; ') };
 }
 
 /**

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-cursor-dev",
   "displayName": "Cursor 子智能体",
   "description": "把 Cursor CLI 当作子编码智能体来写业务代码：cursor_code 每次运行都在 DSH 里开一个真实的、可点开的子会话，cursor_subagent 则显示为宿主写入的 External 记录；可按任务选模型、会话在 DSH 重启后仍能续聊、返回逐步工具时间线与真实文件 diff，并自带额度/模型/会话面板。",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "license": "MIT",
   "type": "module",
   "main": "lib/index.js",