dsh-open-in-ide 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 harrithy
+
+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,252 @@
-# Temporary Holding Version
+# dsh-open-in-ide
 
-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.
+**English** | [中文](README.zh.md)
+
+Open file references from the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+chat in your IDE — **Visual Studio Code by default**, or any detected VS Code
+family / JetBrains IDE — positioned at the referenced line, instead of the in-app
+document preview.
+
+A DeepSeek Harness plugin (bundle + browser half). Tested with DeepSeek Harness
+`0.2.1-rc.2` (Desktop / Web profile).
+
+Supported editors, detected on the machine hosting the Harness:
+
+* **VS Code family** (`--goto <path>:<line>:<column>`): Visual Studio Code,
+  VS Code Insiders, Cursor, Windsurf.
+* **JetBrains family** (`--line <line> <path>`): IntelliJ IDEA, PyCharm, WebStorm,
+  GoLand, CLion, PhpStorm, Rider, RubyMine, DataGrip, RustRover.
+
+## Where to find it
+
+After installing the bundle, reload the Harness page once.
+
+### 1. Enable it — Settings → Plugins → Installed plugins (已安装插件)
+
+![The plugin listed on the Plugins page](docs/plugins-installed.png)
+
+The bundle appears as **“Open File Links in Your IDE”** (Chinese UI:
+“在 IDE 中打开文件链接”) with its on/off switch.
+
+### 2. Choose your IDE — Settings → General → “IDE for file links” (打开文件的 IDE)
+
+![The IDE selector in General settings](docs/settings-general.png)
+
+The row lists only the IDEs detected on the machine hosting the Harness;
+**Visual Studio Code is the default**, and the first detected IDE is used when
+VS Code is not installed.
+
+## Features
+
+* **Plain click** on a file-reference chip in an assistant message opens that
+  file in the selected IDE at the referenced line.
+* **The file's project opens with it.** For the VS Code family the host finds the
+  nearest project root (`.git`/`.hg`, else `package.json`, `Cargo.toml`,
+  `pom.xml`, …) and passes it as a folder argument, so VS Code opens or reuses
+  the **project window** instead of dropping a loose file into the most recently
+  used window. A file without any project marker opens as before.
+* After opening, the editor window is **brought to the foreground** (and restored
+  if it was minimized). Windows uses a small Win32 helper to defeat the
+  background-process foreground lock; macOS activates via `osascript`; Linux
+  tries `wmctrl`/`xdotool`.
+* **Two editor families**: VS Code / VS Code Insiders / Cursor / Windsurf are
+  launched with `--goto`; JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm,
+  GoLand, CLion, PhpStorm, Rider, RubyMine, DataGrip, RustRover) with
+  `--line <line> <path>`. The browser only names an editor id from a fixed set.
+* **Settings → General → “IDE for file links”** lists only the IDEs the host can
+  actually launch, detected by scanning known install locations and `PATH` on
+  every request. The default is Visual Studio Code; when it is not installed the
+  first detected IDE is used, and a saved choice that is no longer installed is
+  reconciled the same way.
+* Clicking a **directory** reference opens it as a workspace folder.
+* **Alt / Shift / Ctrl + click** keeps the shipped in-app preview.
+* A toast names the target and the IDE, including failures (missing file,
+  uninstalled editor, launch error).
+* No build step, no dependencies, no telemetry. The browser half ships as the
+  package's `./client` export; the host half only uses Node built-ins.
+
+## Requirements
+
+* A DeepSeek Harness Web GUI (Desktop or a `web` profile). The host composition
+  must provide `webServer`, `connection`, `subprocess`, `fs`, and `sessions`;
+  the desktop and web profiles do.
+* At least one supported IDE:
+  * **VS Code family**: Visual Studio Code, VS Code Insiders, Cursor, Windsurf.
+  * **JetBrains family**: IntelliJ IDEA, PyCharm, WebStorm, GoLand, CLion,
+    PhpStorm, Rider, RubyMine, DataGrip, RustRover.
+* Compatibility note: the browser half keys off the shipped chat's
+  file-reference chip markup (`_fileMention_*` buttons with the authored path in
+  `title`). A future Harness UI change may need an update here; pin or report
+  the Harness version when filing an issue.
+
+## Install
+
+The plugin is a standard DSH bundle, installed through the Plugin Manager
+(Settings → Plugins) or the `plugin_manager` tool. A local directory install
+links the checkout, so later edits apply live.
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/harrithy/dsh-open-in-ide.git
+   ```
+
+2. Install the bundle from that directory. In the Harness, either use
+   **Settings → Plugins → install**, or ask the agent to run the
+   `plugin_manager` tool with `action: install_bundle` and this absolute
+   directory as `target`. A `link:` install from the profile's package manager
+   works too:
+
+   ```bash
+   dsh plugin --profile <profile> add link:/path/to/dsh-open-in-ide
+   ```
+
+3. **Reload the Harness page** (`F5`). The bundle `dsh-open-in-ide` and row
+   `open-in-ide` appear in Plugin Manager, and a new row appears in
+   Settings → General (see [Where to find it](#where-to-find-it)).
+
+## Auto update
+
+When the plugin is installed from a **git checkout** (a `link:` install, as
+described above), it can update itself while Harness keeps running:
+
+* The page checks the configured repository once per load (`updateCheck`,
+  default on), and the **Settings → General → “Plugin updates”** row has a
+  check button at any time.
+* When the remote has new commits the row shows the new version and an
+  **Update** button. Updating runs `git pull --ff-only` in the checkout and then
+  asks HMR to reload the plugin in place — no Harness restart.
+* The updater only trusts the configured `updateRepository` origin. It refuses
+  a dirty working tree, a foreign origin, and non-fast-forward histories.
+* Installs that are not git checkouts (tarball, registry copy) are reported as
+  such; update those through the Plugin Manager.
+
+This needs `git` on `PATH` and network access to the repository.
+
+## Usage
+
+* Click a file reference such as `src/app.ts:42` in an answer. The file opens in
+  the selected IDE at line 42.
+* Choose the IDE in **Settings → General → “IDE for file links”**. The row lists
+  the IDEs detected on the machine hosting the Harness.
+* The choice is stored in the browser (`localStorage`, key
+  `dsh.open-in-ide.editor`); the legacy key of the plugin's former name is read
+  once for migration.
+* Line/column come from a `:42` / `:42:7` suffix in the chip label. The harness
+  exposes only the path as a DOM attribute, so the label is the line channel.
+  Absolute and workspace-relative paths are both accepted; relative paths
+  resolve against the Session's workspace directory on the host.
+* The column (when present) is only forwarded to VS Code-family launchers;
+  JetBrains launchers receive the line only.
+* Directories open as workspace folders.
+
+## Configuration
+
+The row config lives in `cordis.patch.yml`; override it in the profile's own
+`cordis.patch.yml` to tune behavior (the user patch layer survives plugin
+updates):
+
+```yaml
+- id: open-in-ide
+  config:
+    command: 'C:\Users\me\AppData\Local\Programs\Microsoft VS Code\bin\code.cmd'
+    reuseWindow: true
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `command` | `''` | Explicit editor CLI: a bare PATH name (`code`) or an absolute path (`...\bin\code.cmd`). When set it wins over the Settings selector; empty keeps the selector authoritative. |
+| `commandKind` | `vscode` | Launcher contract used for a configured `command`: `vscode` (`--goto`) or `jetbrains` (`--line`). Ignored while `command` is empty. |
+| `editor` | `vscode` | Fallback IDE when a request carries no selection: any supported id, e.g. `vscode`, `cursor`, `idea`, `pycharm`, `webstorm`. |
+| `reuseWindow` | `false` | Add `--reuse-window` so the file opens in the most recent window (VS Code family only). VS Code already routes files into a window that has the containing folder open. |
+| `openProjectFolder` | `true` | Pass the file's project root as a folder argument so VS Code opens or reuses the project window (VS Code family only). Set `false` to let VS Code decide. |
+| `projectMarkers` | built-in list | Override the project-root markers: file or directory names without separators, e.g. `['.git', 'package.json', 'Cargo.toml']`. |
+| `focusWindow` | `true` | Bring the editor window to the foreground after opening it (restore if minimized). Disable to let the OS decide. |
+| `focusDelayMs` | `350` | Delay before the first foreground attempt; when a cold-started editor has no window yet the plugin retries a few times. |
+| `updateCheck` | `true` | Check the repository for a newer version once per page load. The settings row's check button works regardless. |
+| `updateRepository` | this GitHub URL | Repository the updater is allowed to pull from; a different origin is refused. |
+| `updateDirectory` | plugin directory | Checkout directory to update (defaults to the directory this plugin was loaded from). |
+| `extraArgs` | `[]` | Extra arguments placed before the target arguments, e.g. `["-n"]`. |
+| `launchWatchMs` | `2000` | Early-failure watch window for the detached launcher; a launcher still running when it closes counts as launched. |
+
+## Detection and launch resolution
+
+The host serves two routes, both fenced by the composition's connection trust
+checks (Host/Origin fence plus browser authentication):
+
+* `GET /open-in-ide/editors` — probes each supported editor id on every request
+  (cheap existence checks plus in-process `PATH` lookups) and answers which ones
+  this host can launch.
+* `POST /open-in-ide/open` — validates `{ sessionId, path, line, column,
+  editor }`, resolves the path in the Session's workspace, then launches the
+  selected editor detached with the family's contract and a credential-scrubbed
+  environment.
+
+Detection order:
+
+* **Windows**:
+  * VS Code family: known install roots under `%LOCALAPPDATA%` / `%ProgramFiles%`,
+    then the IDE's CLI name on `PATH`. A machine where Cursor registered itself
+    as `code` still resolves the `vscode` id to the real VS Code install,
+    because known roots are tried before `PATH`.
+  * JetBrains: Toolbox launcher scripts
+    (`%LOCALAPPDATA%\JetBrains\Toolbox\scripts\<cli>.cmd`), Toolbox apps
+    (`…\Toolbox\apps\<app>\ch-<n>\<version>\bin\<exe>`), standalone installs
+    (`%ProgramFiles%\JetBrains\<Product 2024.x>\bin\<exe>`), then the CLI name
+    on `PATH`.
+* **macOS**: VS Code family uses the `.app` bundle's
+  `Contents/Resources/app/bin/<cli>`; JetBrains uses
+  `<App>.app/Contents/MacOS/<cli>`. Both fall back to `PATH`.
+* **Linux**: known install paths (`/opt/...`, `/usr/bin/...`, snap paths) and the
+  JetBrains Toolbox scripts directory under `~/.local/share/JetBrains`, then
+  `PATH`.
+
+The browser never sends a command line: it names an editor id from a fixed set,
+and the host resolves it to an executable it verified.
+
+## Limits
+
+* Only the shipped Markdown file-reference chips are redirected. Tool-call card
+  file names, delivered-file cards, and the document preview keep their own
+  openers.
+* Supported editors and their launcher contracts: VS Code family
+  (`--goto <path>:<line>:<col>`) and the JetBrains family
+  (`--line <line> <path>`). A custom `command` must accept the contract named by
+  `commandKind`.
+* Detection covers the editor ids listed above. A portable build not on `PATH`,
+  or an editor outside those families, needs `command`.
+* The column (when present) is only forwarded to the VS Code family; JetBrains
+  launchers receive the line only.
+* Window raising is best-effort: Windows uses a Win32 helper (an unusual
+  foreground policy or security tool can still refuse the change), while macOS
+  and Linux depend on `osascript` / `wmctrl` / `xdotool` being available.
+* Project-folder injection is heuristic and VS Code-family only: it walks up to
+  the nearest `.git`/`.hg` or manifest marker. JetBrains IDEs keep their own
+  project management and receive only the file/line; no folder is passed.
+* Self-update only works for git checkouts whose origin matches
+  `updateRepository`, and requires `git` plus network access. Local uncommitted
+  changes block it on purpose; commit or stash them first.
+* Line/column come from the visible chip label; when a link's label does not
+  repeat the line, the file opens without a line target.
+* The editor choice is per browser (`localStorage`); another browser or origin
+  keeps its own choice.
+
+## Development
+
+```text
+index.js               Host half: detection + open routes, launch logic
+client.js              Browser half: settings row, click bridge, toasts
+cordis.patch.yml       Bundle row declaration + defaults
+locale/{en,zh}.json    Plugin Manager title/description
+icon.svg               Plugin artwork
+docs/                  Screenshots used by this README
+```
+
+There is no build step: `index.js` is loaded by the Loader, `client.js` is served
+to the browser as the package's `./client` export. A local directory install is
+linked into the profile, so editing either file takes effect through HMR (client
+immediately; host after the plugin row reloads).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/README.zh.md

@@ -0,0 +1,219 @@
+# dsh-open-in-ide
+
+[English](README.md) | **中文**
+
+点击 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 对话中
+回答里的文件引用，用你选择的 IDE（**默认 Visual Studio Code**，也支持 VS Code
+家族与 JetBrains 系列）打开对应文件并定位到引用的行，替代内置的文档预览。
+
+一个 DeepSeek Harness 插件（bundle + 浏览器半）。已在 DeepSeek Harness
+`0.2.1-rc.2`（桌面版 / Web profile）上测试。
+
+支持的编辑器（在宿主机器上自动检测）：
+
+* **VS Code 家族**（`--goto <path>:<line>:<column>`）：Visual Studio Code、
+  VS Code Insiders、Cursor、Windsurf。
+* **JetBrains 家族**（`--line <line> <path>`）：IntelliJ IDEA、PyCharm、
+  WebStorm、GoLand、CLion、PhpStorm、Rider、RubyMine、DataGrip、RustRover。
+
+## 在界面中的位置
+
+安装 bundle 后，刷新一次 Harness 页面。
+
+### 1. 启用插件 —— 设置 → 插件 → 已安装插件
+
+![插件管理页中的插件](docs/plugins-installed.png)
+
+插件在已安装列表中显示为 **「在 IDE 中打开文件链接」**，右侧开关用于启用/停用。
+
+### 2. 选择 IDE —— 设置 → 通用设置 →「打开文件的 IDE」
+
+![通用设置中的 IDE 选择器](docs/settings-general.png)
+
+下拉只列出本机检测到的 IDE；**默认 Visual Studio Code**，未安装 VS Code 时使用
+扫描到的第一个。已保存的选择如果后来被卸载，也会自动回退到 VS Code 或第一个
+检测到的 IDE。
+
+## 功能
+
+* **单击**回答中的文件引用 chip，用所选 IDE 打开对应文件并定位到引用的行。
+* **连同项目一起打开**：VS Code 家族会沿路径向上找项目根（`.git`/`.hg`，否则
+  `package.json`、`Cargo.toml`、`pom.xml` 等标记），把项目目录作为文件夹参数传
+  给 CLI，于是 VS Code 会**打开或复用项目窗口**，而不是把文件变成散落标签塞进最近
+  使用的窗口。没有任何项目标记的文件仍按原方式打开。
+* 打开后会把 IDE 窗口**提到最前**（窗口最小化时先恢复）。Windows 通过一个小型
+  Win32 助手绕过“后台进程无前台权限”的限制；macOS 用 `osascript` 激活应用；
+  Linux 尝试 `wmctrl` / `xdotool`。
+* **两个编辑器家族**：VS Code / Insiders / Cursor / Windsurf 用 `--goto` 启动；
+  JetBrains（IntelliJ IDEA、PyCharm、WebStorm、GoLand、CLion、PhpStorm、Rider、
+  RubyMine、DataGrip、RustRover）用 `--line <行> <路径>` 启动。浏览器只发送固定
+  集合里的编辑器 id。
+* **设置 → 通用设置 →「打开文件的 IDE」**只列出宿主真正能启动的 IDE（每次请求
+  都会扫描已知安装位置和 `PATH`）。默认 VS Code；没有 VS Code 则用扫描到的第一
+  个；已保存的选择失效时同样自动回退。
+* 点击**目录**引用会在 IDE 中打开该文件夹。
+* **Alt / Shift / Ctrl + 单击**保留内置预览（侧栏文档预览）。
+* 顶部 toast 提示目标与 IDE，失败时给出原因（文件不存在、IDE 未安装、启动失败）。
+* 无构建步骤、无依赖、无遥测。浏览器半以包的 `./client` 导出提供，宿主半只使用
+  Node 内置模块。
+
+## 环境要求
+
+* 一个 DeepSeek Harness Web GUI（桌面版或 `web` profile）。宿主组合需要提供
+  `webServer`、`connection`、`subprocess`、`fs`、`sessions` 服务；桌面版与 web
+  profile 都满足。
+* 至少安装一款受支持的 IDE：
+  * **VS Code 家族**：Visual Studio Code、VS Code Insiders、Cursor、Windsurf。
+  * **JetBrains 家族**：IntelliJ IDEA、PyCharm、WebStorm、GoLand、CLion、
+    PhpStorm、Rider、RubyMine、DataGrip、RustRover。
+* 兼容性说明：浏览器半依赖当前聊天 UI 的文件引用 chip 结构（`_fileMention_*`
+  按钮，作者路径在 `title` 属性里）。Harness 未来的 UI 改动可能需要适配；提
+  issue 时请附上 Harness 版本。
+
+## 安装
+
+本插件是标准 DSH bundle，通过 Plugin Manager（设置 → 插件）或 `plugin_manager`
+工具安装。本地目录安装会把源码目录链接进 profile，改代码即时生效。
+
+1. 克隆仓库：
+
+   ```bash
+   git clone https://github.com/harrithy/dsh-open-in-ide.git
+   ```
+
+2. 从这个目录安装 bundle。可在 Harness 中打开 **设置 → 插件 → 安装**，或让
+   agent 用 `plugin_manager` 工具执行 `action: install_bundle`，`target` 填这个
+   目录的绝对路径。也可以用 profile 的包管理器做 `link:` 安装：
+
+   ```bash
+   dsh plugin --profile <profile> add link:/path/to/dsh-open-in-ide
+   ```
+
+3. **刷新 Harness 页面**（F5）。Plugin Manager 中会出现 bundle `dsh-open-in-ide`
+   和行 `open-in-ide`，通用设置里会出现新的一行（见[在界面中的位置](#在界面中的位置)）。
+
+## 自动更新
+
+当插件是从 **git checkout**（`link:` 安装，见上面的安装步骤）安装时，可以在 Harness
+运行期间自行更新：
+
+* 页面每次加载会检查一次配置的仓库（`updateCheck`，默认开启）；**设置 → 通用设置
+  →「插件更新」** 一行也可以随时手动检查。
+* 远端有新提交时，该行会显示新版本和「更新」按钮。更新会在 checkout 里执行
+  `git pull --ff-only`，然后通过 HMR 就地重载插件，**不需要重启 Harness**。
+* 更新器只信任配置的 `updateRepository` origin；本地有未提交改动、origin 不匹配、
+  或无法快进的历史都会被拒绝。
+* 非 git checkout（tarball、包管理器安装）会如实提示，请通过插件管理器更新。
+
+需要 `PATH` 上有 `git`，并且能访问该仓库。
+
+## 使用
+
+* 点击回答里的文件引用（如 `src/app.ts:42`），文件会在所选 IDE 中打开并定位到
+  第 42 行。
+* 在 **设置 → 通用设置 →「打开文件的 IDE」** 中选择 IDE；下拉只列出宿主检测到
+  的 IDE。
+* 选择保存在浏览器（`localStorage`，键 `dsh.open-in-ide.editor`）；插件改名前的
+  旧键会被读取一次以完成迁移。
+* 行号/列号取自 chip 文字末尾的 `:42` / `:42:7`。Harness 只把路径暴露在 DOM 的
+  `title` 属性中，所以链接文字是行号的通道。绝对路径和相对工作区的路径都支持，
+  相对路径由宿主按 Session 的工作目录解析。
+* 列号只会传给 VS Code 家族启动器；JetBrains 启动器只接收行号。
+* 目录引用会作为工作区文件夹打开。
+
+## 配置
+
+行配置在 `cordis.patch.yml` 中；在 profile 自己的 `cordis.patch.yml` 里覆盖即可
+（用户 patch 层在插件升级后仍保留）：
+
+```yaml
+- id: open-in-ide
+  config:
+    command: 'C:\Users\me\AppData\Local\Programs\Microsoft VS Code\bin\code.cmd'
+    reuseWindow: true
+```
+
+| 字段 | 默认 | 含义 |
+|---|---|---|
+| `command` | `''` | 显式指定编辑器 CLI：PATH 名（`code`）或绝对路径（`...\bin\code.cmd`）。设置后优先于设置页选择；留空则设置页选择生效。 |
+| `commandKind` | `vscode` | 配置了 `command` 时使用的启动约定：`vscode`（`--goto`）或 `jetbrains`（`--line`）。`command` 为空时忽略。 |
+| `editor` | `vscode` | 请求未携带选择时的回退 IDE：任意受支持的 id，如 `vscode`、`cursor`、`idea`、`pycharm`、`webstorm`。 |
+| `reuseWindow` | `false` | 追加 `--reuse-window`，在最近窗口打开（仅 VS Code 家族）。VS Code 本身会把文件路由到已打开该目录的窗口。 |
+| `openProjectFolder` | `true` | 把文件所属项目根作为文件夹参数传入，让 VS Code 打开/复用项目窗口（仅 VS Code 家族）。设为 false 交给 VS Code 决定。 |
+| `projectMarkers` | 内置列表 | 覆盖项目根标记：不带路径分隔符的文件/目录名，例如 `['.git', 'package.json', 'Cargo.toml']`。 |
+| `focusWindow` | `true` | 打开后把 IDE 窗口提到最前（最小化时先恢复）。设为 false 则交给系统决定。 |
+| `focusDelayMs` | `350` | 首次置前尝试的延迟；冷启动的编辑器窗口还没出现时会自动重试几次。 |
+| `updateCheck` | `true` | 每次页面加载检查一次仓库新版本；设置行里的检查按钮不受此开关影响。 |
+| `updateRepository` | 本仓库 GitHub 地址 | 更新器允许 pull 的仓库；origin 不同会被拒绝。 |
+| `updateDirectory` | 插件所在目录 | 要更新的 checkout 目录（默认就是加载本插件的目录）。 |
+| `extraArgs` | `[]` | 放在目标参数之前的额外参数，例如 `["-n"]`。 |
+| `launchWatchMs` | `2000` | 分离启动器的早期失败观察窗口；窗口结束时仍在运行的启动器视为启动成功。 |
+
+## 检测与启动解析
+
+宿主提供两个路由，均先经过组合的 connection 信任检查（Host/Origin 防跨站 + 浏览器
+认证）：
+
+* `GET /open-in-ide/editors` —— 每次请求都探测支持的编辑器 id（路径存在性检查 +
+  进程内 `PATH` 解析），返回本机能启动哪些。
+* `POST /open-in-ide/open` —— 校验 `{ sessionId, path, line, column, editor }`，
+  按 Session 工作目录解析路径，然后按家族约定分离启动所选编辑器，子进程使用凭据
+  清理后的环境。
+
+检测顺序：
+
+* **Windows**：
+  * VS Code 家族：`%LOCALAPPDATA%` / `%ProgramFiles%` 下的已知安装目录，然后是
+    `PATH` 上的 CLI 名。即使 Cursor 把 `code` 注册成自己的命令，`vscode` id 仍会
+    解析到真正的 VS Code 安装，因为已知目录先于 `PATH` 尝试。
+  * JetBrains：Toolbox 启动脚本
+    （`%LOCALAPPDATA%\JetBrains\Toolbox\scripts\<cli>.cmd`）、Toolbox 应用目录
+    （`…\Toolbox\apps\<app>\ch-<n>\<version>\bin\<exe>`）、独立安装
+    （`%ProgramFiles%\JetBrains\<Product 2024.x>\bin\<exe>`），最后是 `PATH`
+    上的 CLI 名。
+* **macOS**：VS Code 家族用 `.app` 内的
+  `Contents/Resources/app/bin/<cli>`；JetBrains 用 `<App>.app/Contents/MacOS/<cli>`；
+  两者都回退到 `PATH`。
+* **Linux**：常见安装路径（`/opt/...`、`/usr/bin/...`、snap 路径）和
+  `~/.local/share/JetBrains` 下的 Toolbox 脚本目录，最后是 `PATH`。
+
+浏览器从不发送命令行：它只发送固定集合里的编辑器 id，宿主把它解析为自己验证过的
+可执行文件。
+
+## 限制
+
+* 只重定向内置 Markdown 文件引用 chip。工具调用卡片里的文件名、交付文件卡片和
+  文档预览保持各自的打开方式。
+* 支持的编辑器与启动约定：VS Code 家族（`--goto <path>:<line>:<col>`）与
+  JetBrains 家族（`--line <行> <路径>`）。自定义 `command` 必须接受
+  `commandKind` 指定的约定。
+* 检测覆盖上面列出的编辑器 id；不在 `PATH` 上的便携版或列表之外的编辑器需要
+  `command`。
+* 列号只会传给 VS Code 家族；JetBrains 启动器只接收行号。
+* 置前是尽力而为：Windows 通过 Win32 助手实现（极特殊的前台策略或安全软件仍可能
+  拒绝），macOS/Linux 依赖 `osascript` / `wmctrl` / `xdotool` 是否可用。
+* 项目文件夹注入是启发式且仅用于 VS Code 家族：向上找最近的 `.git`/`.hg` 或
+  manifest 标记。JetBrains 保持自己的项目管理，只接收文件/行号，不传文件夹。
+* 自动更新仅适用于 origin 与 `updateRepository` 一致的 git checkout，且需要
+  `git` 和网络；本地有未提交改动时会故意拒绝，先提交或暂存。
+* 行号/列号来自可见的 chip 文字；链接文字没有行号时只打开文件、不定位。
+* 编辑器选择按浏览器保存（`localStorage`）；不同浏览器或 origin 各自独立。
+
+## 开发
+
+```text
+index.js               宿主半：检测 + 打开路由、启动逻辑
+client.js              浏览器半：设置行、点击桥、toast
+cordis.patch.yml       bundle 行声明 + 默认配置
+locale/{en,zh}.json    Plugin Manager 标题/描述
+icon.svg               插件图标
+docs/                  本 README 使用的截图
+```
+
+没有构建步骤：`index.js` 由 Loader 加载，`client.js` 作为包的 `./client` 导出
+提供给浏览器。本地目录安装会链接进 profile，因此修改文件可通过 HMR 生效（浏览器
+半立即生效；宿主半在插件行重载后生效）。
+
+## 许可证
+
+MIT，见 [LICENSE](LICENSE)。