dsh-artifact-linker 0.0.0-stage → 0.2.5

package/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+## 0.2.0 — 2026-10-27
+
+### 用户实测反馈驱动的重写
+
+三条反馈，全部照办：
+
+1. 「这插件不对劲不是我想要的效果，我希望打开的方式是从对话中的名称可以直接点击或者右键方式打开而不是悬浮球」
+2. 「悬浮球你做的也有问题很多不是产物被你识别了」
+3. 「而且切换窗口刷新很慢」
+
+### 删掉的东西（v0.1 的设计错误）
+
+- **整个悬浮球 + 产物面板**：右下角 `📎 N` 胶囊、清单面板、状态点、刷新/清缓存按钮 —— 全删
+- **全量 TreeWalker 扫描**：不再遍历文档文本节点
+- **MutationObserver**：不再监听 DOM 变化
+- **setInterval 定时刷新 / 300ms 防抖扫描**：不再有任何常驻定时器
+- 体积：832 行 / 36KB → 368 行 / 15.8KB（顺带缓解 `dsh-experimental-inspector` 的 source-frame 字节上限）
+
+### 新增的交互
+
+| 操作 | 效果 |
+|---|---|
+| 左键点产物名 | 在资源管理器里揭示并选中 |
+| 右键点产物名 | 自建菜单：揭示 / 默认程序打开 / 复制完整路径 |
+| 悬停命中 | 鼠标变手型（唯一视觉提示，mousemove 150ms 节流） |
+| 非产物处右键 | 完全放行，宿主原生菜单照常 |
+| 解析不到 | 静默放行或一次性提示，绝不假装成功 |
+
+### 修掉的真 bug ①：面板里全是「未解析」
+
+**根因**：客户端调 `/resolve` 没传 `base`，宿主就固定用 `process.cwd()`。那是 DSH 宿主进程的工作目录，**不是会话 workspace** → 相对路径和裸文件名全部解析失败。
+
+**修法**：新增 `candidateBases()` —— 宿主自己列出所有可能是 workspace 的目录：
+
+```
+process.cwd()
+~/.dsh/*/workspace
+~/.dsh/profiles/*/workspace
+```
+
+再由 `resolveAcross()` 逐个当 base 试，命中即返回。`/info` 现在也返回 `bases` 数组，排查时可以直接看宿主认为的候选目录。
+
+**实测 12/12**：`测试报告-2026.pdf`、`对比图.tif`、`中文名称-测试.zip`、`数据汇总表.xlsx`、`运行日志.log`、`路径 带空格.pdf` 全部解析到真实绝对路径。
+
+### 修掉的真 bug ②：Fluent 多级扩展名被截断
+
+`fluid.cas.h5` 以前被截成 `fluid.cas` → 撞一个不存在的文件 → 点了没反应。正则尾部加 `(?:\.[A-Za-z0-9]{1,6})*` 吃掉多级尾巴。
+
+### 探针（全部落盘可复跑，位置：`.dsh\backups\artifact-linker-probes\`）
+
+| 探针 | 覆盖 | 结果 |
+|---|---|---|
+| `probe-v2.mjs` | 识别层实跑 14 正例 + 7 反例 + 9 条禁止 + 11 条必须 + 体积红线 | 45/0 |
+| `probe-client-materialize.mjs` | cordis 客户端契约（有 apply / 不碰 document / 单例守卫 / dispose 清场） | 13/0 |
+| `probe-host-apply.mjs` | 宿主 apply 契约（6 路由 / prompt 段 / 403 / disposer） | 21/0 |
+| `verify-resolve.mjs` | 真实文件解析 12 项 | 12/0 |
+
+探针刻意放在包外：包内每多一个文件，`dsh-experimental-inspector` 采集的源码量就更大，撑爆 source-frame 上限会让 **host exit 1**。
+
+### 已知边界（不是 bug）
+
+- 只认白名单扩展名，**刻意不含 exe/msi/dll**：正文里这些多半是命令输出，不是要打开的产物
+- 只在**点击瞬间**判定，不做任何预扫描 → 尚未渲染出来的内容点不到（但也不会误报）
+- `Ctrl/Shift/Alt + 左键` 一律放行给宿主，方便你选中文字
+
+## 0.1.0 — 2026-10-27
+
+首个可运行版本。
+
+### 宿主端
+
+- 新增常驻 system-prompt 段 `artifact-path-rules`（order 200，约 600 字符）：要求模型把产物写成完整绝对路径、给用户看的正文只写文件名、不确定时先核实再写、绝不编造路径、路径含空格或中文用反引号包裹。
+- 新增 6 条回环路由（全部 `127.0.0.1` 限定，外部来源 403）：
+  - `GET /info` — 插件身份、版本、workspace、三个开关的实际生效值
+  - `GET /resolve?p=` — 路径解析，三源兜底（绝对 → workspace 相对 → 裸文件名递归搜索）
+  - `GET /stat?p=` — 批量 stat，10 秒 TTL 缓存
+  - `GET /flush-cache` — 清空路径解析与 stat 缓存
+  - `GET /reveal?p=` — 在资源管理器揭示并选中
+  - `GET /open?p=` — 用系统默认关联程序打开
+- `reveal` / `open` 走 `execFile(cmd, args)` 参数数组，不经 shell，路径中的 `& | ; %VAR%` 均为字面量。
+- 跨平台：Windows `explorer.exe /select,`、macOS `open -R`、Linux `xdg-open`（揭示退化为打开父目录）。
+
+### 客户端端
+
+- 新增 `__ModuleLoader__.load` bundle（id = `dsh-artifact-linker`，与包名一致）。
+- **全程只读正文，不修改任何 DOM 节点、不添加属性、不重挂 React 节点。** 可点性由 document 捕获期 `click` + `caretRangeFromPoint` 反查光标所在词实现，节点被 React 重渲染换掉也不会失效。
+- 修饰键分流：左键揭示并选中 / Ctrl·Shift·Cmd 系统程序打开 / Alt 复制路径。
+- 新增右下角浮动胶囊 `📎 N`（Shadow DOM 挂 `body`，不主动 `focus()`，`mousedown` 在 document 捕获期截断以避免宿主 `closeOutside` 关掉面板）。
+- 产物清单：状态点（存在 / 已不存在 / 未确认）、大小、相对修改时间、每行 `📍 ↗ ⧉` 三按钮、刷新 / 清缓存 / 清空。
+- 明暗主题跟随：读取 `body` 背景亮度判定，仅在切换时重设 CSS 变量，不逐帧读样式。
+- **URL 排除**：渲染后的链接文本节点本身就是 `https://x.com/a.png`，里面那个 `a.png` 会被文件名正则误命中、被当成 workspace 产物。现在每段文本先算出所有 URL 区间，命中落进去一律丢弃（扫描与点击反查两条路径都做了）。
+- 单例守卫 `window.__dshArtifactLinkerV1`：热重载前先 `dispose()` 旧实例，`dispose()` 摘净全部监听器、定时器、观察者与 DOM。**热重载清理不掉「修复前加载的旧实例」，改完必须完全重启 DSH。**
+- 附 `scripts/probe-regex.mjs` 探针回归：从真实源码切出识别段，跑 14 条识别/排除断言 + 10 条源码静态断言（不出现 iframe、不构造绝对 URL 去 fetch、有单例守卫、dispose 摘净监听、不修改正文 DOM、不接管 markdown 图片、mousedown 闸门在 document 捕获期、浮层不主动 focus、bundle id 一致）。`node --check` 只查语法，这些边界只有探针能兜住。
+
+### 已知边界
+
+- 不接管 markdown 图片与链接语法（改写成芯片会导致图不显示）。
+- 扩展名走白名单，不做「看起来像路径就标成产物」的猜测；`exe/lock` 之类故意不在白名单里。
+- 裸文件名在 workspace 内搜到多个同名文件时返回候选，不自动选择。
+- `allowOutside` 默认 `true`（产物大多在 E:/D: 项目盘，不在 workspace 内）；多用户环境建议改 `false`，否则等于允许「模型给个路径就打开任意文件」。
+
+### 交付前按官方 14 条硬规则自查修正（未发布即改，同属 0.1.0）
+
+- **硬规则 #6（peer range 在安装时被强制校验）**：`@deepseek-ai/dsh` 由 `>=0.1.7-rc.1` 改为 `>=0.2.1-rc.3`。semver 规定 prerelease 版本只匹配「major.minor.patch 相同、且 range 内带 prerelease 比较器」的范围，原范围对运行时 `0.2.1-rc.3` 实测为 **false** —— 不改这一条，`dsh plugin add` 会直接拒绝安装。`engines.dsh` 同步。
+- **硬规则 #13（样式必须走 `--dsw-alias-*` 主题令牌）**：12 处自造颜色变量改为三层链 `var(--dsw-alias-*, var(--alXxx, <硬编码>))`，取 `bg-layer-2` / `label-primary` / `border-l2` / `interactive-bg-hover`（均在 app.asar 内实测存在，命中 120~566 次）。自算明暗降为第二层兜底。
+- **硬规则 #5（tunable 不许硬编码）**：`STAT_TTL_MS` → `statTtlMs`、裸名反查深度 `2` → `searchMaxDepth`、铁律文本 → `rulesText`，三者均可由 `cordis.patch.yml` 覆盖（`searchMaxDepth` 硬上限 8 层，防止 `/resolve` 退化成全盘扫描）。
+- **硬规则 #8（双语文档成对）**：`README.md` 改为英文主文档，新增 `README.zh.md` 中文完整版，两者顶部互链；`files` 白名单同步。
+- 未采用的项：硬规则 #13 的「render React in a slot」—— 本插件不注册 slot，用 `document.body` + Shadow DOM 承载悬浮胶囊（与 `dsh-todo-float-ball` 同构），因为它的可点性挂在正文文本节点上、不能放进某个 slot 里。硬规则 #12「不要手写 profile package.json」—— 本机既有装机方式即手写 `dependencies` 一行 + `link:` 依赖，已在 README 标注。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 loyalchiiina
+
+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,136 @@
-# Temporary Holding Version
+# dsh-artifact-linker
 
-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.
+**Every artifact your agent delivers is one click away — no more "copy the path → open Explorer → paste into the address bar → Enter".**
+**让 DSH 交付的每一个产物，都能点一下就到位 —— 不用再「复制路径 → 打开文件管理器 → 贴到地址栏 → 回车」。**
+
+**English** · [简体中文](README.zh.md) · [Interaction](#interaction) · [Install](#install) · [Config](#config) · [Boundaries](#what-it-does-not-do) · [Troubleshooting](#troubleshooting)
+
+---
+
+## The problem
+
+DSH already previews images, code, PDFs and Office files in the sidebar. But **scripts, Fluent exports, packed archives, temporary dumps** have no previewer — all you get in the transcript is a bare file name, so opening one costs four mechanical steps:
+
+1. Select and copy the path (assuming the model even printed one)
+2. Open File Explorer
+3. Paste into the address bar
+4. Press Enter
+
+Worse: the model often prints a **relative path or just a file name**, so step 1 fails outright and you have to go hunting for the file first.
+
+This plugin removes all four steps **and** removes the root cause.
+
+## What it does
+
+Two halves, one contract.
+
+| Half | Responsibility |
+| --- | --- |
+| **Host** (`lib/index.js`) | Registers a **resident system-prompt section** so "declare artifacts with full absolute paths" holds in *every* session and *every* preset — no skill needs to be loaded. Exposes six loopback-only routes for path resolution, `stat`, reveal and open. |
+| **Client** (`lib/client.js`) | Turns artifact names in the transcript into clickable targets: left click reveals, right click opens a menu. **No resident UI, no scanning, no timers.** |
+
+The host half closes the loop: even when the model only says `result.h5`, the route layer resolves it against the session workspace, then falls back to a shallow recursive basename search, and returns the real absolute path.
+
+## Interaction
+
+Click behaviour is decided by the modifier key — no menu, no first-time setup:
+
+| Action | Result |
+| --- | --- |
+| **Left click** on a file name / path | Reveal in File Explorer *with the file selected* |
+| **Ctrl / Shift / Cmd + click** | Open with the system's default application |
+| **Alt + click** | Copy the full absolute path to the clipboard |
+
+### Interactions (v0.2 — no floating pill any more)
+
+| Action | Result |
+|---|---|
+| **Left click** an artifact name | Reveals and selects the file in Explorer |
+| **Right click** an artifact name | Inline menu: `📍 reveal` / `↗ open with default app` / `⧉ copy absolute path` |
+| **Hover** an artifact name | Cursor turns into a pointer (the only visual hint) |
+| Right click on **non-artifact** text | Fully passed through — the host's native menu appears as usual |
+| File missing / unresolvable | Silent pass-through or a one-shot toast. **Never pretends to succeed.** |
+
+The following describes the removed v0.1 design:
+
+The panel refreshes on its own; there are also explicit refresh / flush-cache / clear / close controls.
+
+## How paths resolve
+
+A single path may arrive in three shapes, tried in order:
+
+1. **Absolute** — used as-is (`E:\project\out\case.h5`, `\\nas\share\a.zip`). Both drive letters and UNC are recognised.
+2. **Relative** — joined against the session workspace (`out\case.h5` → `<workspace>\out\case.h5`).
+3. **Bare file name** — a shallow recursive basename search under the workspace (depth 2 by default), used only when exactly one match is found. Multiple matches are surfaced as candidates instead of guessing.
+
+Results are cached with a 10 s TTL so that repeated queries from DOM re-renders do not hammer the disk, while a just-deleted file still flips to "gone" quickly.
+
+## Install
+
+```bash
+# 1. Drop the package into DSH's local plugin directory
+#    Windows: %USERPROFILE%\.dsh\local-plugins\dsh-artifact-linker
+
+# 2. Declare the dependency in your profile's package.json
+#    %USERPROFILE%\.dsh\profiles\<profile>\package.json  →  dependencies
+#      "dsh-artifact-linker": "link:C:/Users/<you>/.dsh/local-plugins/dsh-artifact-linker"
+
+# 3. Fully restart DSH — client bundles are NOT reloaded by Ctrl+R
+```
+
+> The host half needs `webServer` and `systemPrompt`; the client half is a `__ModuleLoader__` bundle. Peers declare `@deepseek-ai/dsh >=0.2.1-rc.3` — the installer compares the runtime version against that range and refuses a mismatch.
+
+## Config
+
+All tunables live in `cordis.patch.yml` (or the profile-level patch). Changing them requires a restart.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `injectRules` | `true` | Register the resident prompt section |
+| `clientChips` | `true` | Client capsule + click takeover. `false` = pure injection mode |
+| `allowOutside` | `true` | Allow resolving paths outside the workspace |
+| `statTtlMs` | `10000` | Host-side `stat` cache lifetime |
+| `searchMaxDepth` | `2` (max 8) | Recursion depth for bare-filename lookup |
+| `rulesText` | built-in 6 lines | Replace the injected rules wholesale (array or multi-line string) |
+
+On `allowOutside`: artifacts almost always live on a project drive (`E:\`, `D:\`) rather than inside the DSH workspace, so a strict default would make the plugin useless on first run. **Set it to `false` when shipping to other people** — that is the gate which stops this plugin from becoming "the model names any path and your machine opens it".
+
+## What it does NOT do
+
+- **Never modifies a single DOM node.** React owns the transcript; mutating its nodes causes blank renders on re-render. Clickability comes from a capture-phase `click` listener plus `caretRangeFromPoint` to work out which word was hit.
+- **Never takes over markdown image or link syntax.** Rewriting `![](path)` into a chip would break the image.
+- **Never writes a file, never phones home.** Zero telemetry. The only `spawn` calls are the explicit `/reveal` and `/open` routes, using `execFile` with an argument array (no shell, no injection surface), guarded by a loopback-origin check.
+- **Never renames or moves anything.** Read-only by construction.
+- **Does not unify with the official `present` card.** If an artifact was already delivered as a card, the injected rules tell the model not to repeat it.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| Nothing clickable | Was DSH **fully restarted**? `dsh.client` bundles do not hot-reload |
+| Capsule missing | `clientChips` is `true`; the loader reports `loaded without registering` if the bundle id mismatches `package.json` |
+| Click does nothing | File may have been deleted — the capsule marks it `gone` |
+| "outside workspace" | Either set `allowOutside: true`, or the path really is outside the project |
+| Injection not working | `injectRules` is `true`; look for the host log `artifact path rules registered` |
+| Theme colours look off | The plugin prefers `--dsw-alias-*` tokens, then self-detected light/dark, then hardcoded fallbacks |
+
+## Layout
+
+```
+dsh-artifact-linker/
+├── package.json          # dsh.bundle + dsh.client, peer >=0.2.1-rc.3
+├── cordis.patch.yml      # the patch entry (never duplicate this id)
+├── lib/
+│   ├── index.js          # host: prompt section + 6 loopback routes
+│   └── client.js         # client: __ModuleLoader__ bundle, read-only DOM
+├── locale/{zh,en}.json   # meta.title / meta.description
+├── icon.svg
+├── scripts/probe-regex.mjs
+├── README.md / README.zh.md
+├── CHANGELOG.md
+└── LICENSE
+```
+
+## License
+
+MIT © loyalchiiina

package/README.zh.md

@@ -0,0 +1,185 @@
+# dsh-artifact-linker · 产物路径联动器
+
+> 让 DSH 交付的每一个产物，都能**点一下就到位**——不用再「复制路径 → 打开文件管理器 → 贴到地址栏 → 回车」。
+
+[English](README.md) · **简体中文** · [安装](#安装) · [交互](#交互) · [配置](#配置) · [边界](#它不做什么) · [排查](#排查)
+
+---
+
+## 它解决什么
+
+DSH 里预览器已经能开图片、代码、pdf、office。但**插件、脚本、Fluent 出图、打包产物、临时导出**这些文件，正文里只给一个名字，想打开它得走完四步机械劳动：
+
+```
+看到 "结果.xlsx" → 复制路径 → Win+E → 地址栏输入 → 回车 → 在一堆同级文件里找那一个
+```
+
+`dsh-artifact-linker` 把这条路压成 **0 步**：正文里的文件名本身就是入口。
+
+它做两件互相咬合的事：
+
+| 半边 | 做什么 |
+|---|---|
+| **宿主（提示词层）** | 常驻注入一条「产物路径铁律」，要求模型把产物写成**完整绝对路径**、而给用户看的正文**只写文件名**——路径有据可查，正文又不被长串路径污染 |
+| **客户端（渲染层）** | 正文里的产物名变成可点目标：左键揭示、右键菜单。**零常驻 UI、零扫描、零定时器** |
+
+第 1 条管「模型把路径写对」，第 2 条管「用户点得动」。缺前者，路径经常是猜的、点开是死链；缺后者，路径再对也要人去复制。
+
+---
+
+## 交互
+
+正文里点一个文件名（或绝对路径）：
+
+| 操作 | 结果 |
+|---|---|
+| **左键** | 在系统资源管理器里**揭示并选中**该文件（不是打开它，是把它亮在你面前） |
+| **Ctrl / Shift / Cmd + 左键** | 用系统默认关联程序打开（Excel、PS、播放器……） |
+| **Alt + 左键** | 复制完整绝对路径到剪贴板 |
+
+### 三种交互（v0.2 起不再有浮球）
+
+正文里出现产物名时：
+
+| 操作 | 效果 |
+|---|---|
+| **左键**点产物名 | 在资源管理器里揭示并选中该文件 |
+| **右键**点产物名 | 本插件菜单：`📍 揭示` / `↗ 默认程序打开` / `⧉ 复制完整路径` |
+| **悬停**在产物名上 | 鼠标变手型（唯一的视觉提示） |
+| 在**非产物**文字上右键 | 完全放行，宿主原生菜单照常出现 |
+| 文件不存在 / 解析不到 | 静默放行或一次性提示，**绝不假装成功** |
+
+以下为 v0.1 的历史设计（已移除）：
+
+- 点击展开清单，按发现时间倒序，每行给出：类型图标 · 文件名 · 状态点 · 完整路径 · 大小 · 修改时间；
+- 状态点：🟢 存在 / 🔴 已不存在（划掉） / ⚪ 尚未确认；
+- 每行右侧三个按钮：`📍` 揭示 · `↗` 打开 · `⧉` 复制；
+- 顶部：`刷新`（重查状态）· `清缓存`（清宿主 stat 缓存）· `清空`（只清面板清单，**不动任何文件**）。
+
+同一文件名出现多次只记一条（按次数累计），清单上限 200 条，超出后按发现顺序淘汰最旧。
+
+---
+
+## 路径怎么解析（三源兜底）
+
+模型嘴里的话不可全信，插件按顺序试：
+
+1. **`/workspace/<...>`** —— DSH 工作区的虚拟根，映射到真实 workspace 目录；
+2. **原生绝对路径** —— `E:\proj\out\a.xlsx` 直接用；
+3. **workspace 内的相对路径** —— 以 workspace 为基准拼接；
+4. **裸文件名** —— 在 workspace 内递归搜同名文件（跳过 `node_modules/.git/dist/build/` 等），按「最近修改优先」+「目录深度浅优先」排序：
+   - 命中 **1 个** → 直接用；
+   - 命中 **多个** → 返回候选列表交给用户，**绝不猜**（猜错比不猜更糟）；
+   - 命中 **0 个** → 若 `allowOutside: true`，再在磁盘上按名字做一次浅层搜索。
+
+结果一律带 10 秒 TTL 缓存，避免重复 stat 打满磁盘。
+
+---
+
+## 安装
+
+```bash
+# 1. 放进 DSH 的本地插件目录
+#    Windows: %USERPROFILE%\.dsh\local-plugins\dsh-artifact-linker
+
+# 2. profile 里声明依赖（<profile> 换成 desktop / web / xiufu）
+#    在 %USERPROFILE%\.dsh\profiles\<profile>\package.json 的 dependencies 里加：
+#      "dsh-artifact-linker": "file:~/.dsh/local-plugins/dsh-artifact-linker"
+
+# 3. 完全重启 DSH（客户端 bundle 不随 Ctrl+R 重载）
+```
+
+> ⚠️ **`file:` 依赖的坑**：`file:` / `link:` 指向会在 profile 重装依赖时把目录内容**按快照恢复**，本地改动可能被回滚。长期使用建议 `npm pack` 成 tarball 后用 `file:` 指向 tgz，或直接发到 npm。
+
+装好后确认：
+
+```
+GET http://127.0.0.1:<port>/dsh-artifact-linker/info
+```
+
+正常应返回插件名、版本、`workspace`、以及 `injectRules / clientChips / allowOutside` 三个开关的**实际生效值**（这一条是排障时唯一可信的地方——别信 README，信 `/info`）。
+
+---
+
+## 配置
+
+在 profile 的 `cordis.patch.yml` 里给本插件条目加 `config`（**不要在 profile 里手写第二段 `insert`**，同一 entry id 插两行会 `duplicate loader entry id`）：
+
+```yaml
+- id: dsh-artifact-linker
+  name: dsh-artifact-linker
+  config:
+    injectRules: true    # 常驻 prompt 铁律
+    clientChips: true    # 是否接管正文点击（false = 只留提示词注入，不动鼠标）
+    allowOutside: true   # 是否允许解析 workspace 之外的路径
+```
+
+| 开关 | 默认 | 置 false / true 的效果 |
+|---|---|---|
+| `injectRules` | `true` | `false` = 不注入 prompt 段，模型不再被要求输出绝对路径 |
+| `clientChips` | `true` | `false` = 纯注入模式，不接管任何鼠标事件 |
+| `allowOutside` | `true` | `false` = 只允许打开 workspace 内的文件 |
+
+**`allowOutside` 要特别说一句**：产物经常落在项目盘（`E:\…`、`D:\…`）而不是 DSH 的 workspace 里，所以默认放开。但它同时是安全闸——挡的是「模型说个 `C:\Windows\System32\xxx.exe` 就帮你点开」这类情况。**自己一个人用保持 `true` 更顺手；给别人用、或者接入不可信模型，改成 `false`。**
+
+---
+
+## 它不做什么
+
+这几条是**刻意**的，不是没做完：
+
+1. **不改任何 DOM 节点**。正文由 React 渲染，给文本包一层 `<span>` 就是移动 React 的节点，重渲染时整段白屏。本插件全程只读，可点性是「捕获期 click + 光标位置反查」实现的。
+2. **不接管 markdown 图片与链接语法**。`![](path)` 一旦被改写成芯片，图就不显示了。
+3. **不联网、零遥测**。全部路由只在 `127.0.0.1` 回环可用，外部来源一律 403。
+4. **不 spawn shell**。`reveal`/`open` 走 `execFile(cmd, args)` 参数数组，路径里的 `& | ; %VAR%` 全是字面量，没有命令注入面。
+5. **不猜多候选路径**。搜到多个同名文件时把选择权还给人。
+6. **不保证文件存在**。库里的文件随时可能被删、被移走、被别的进程占用——所以每次打开前都重新 stat，点开发现没了就明说「已不存在」，不会装作没事。
+
+---
+
+## 排查
+
+| 症状 | 原因与处置 |
+|---|---|
+| 正文文件名不可点 | ① `clientChips` 被置 false；② 扩展名不在白名单（本插件只认已知产物扩展名，避免把 `C:\Windows` 之类误标成产物）；③ 客户端 bundle 没重载——**Ctrl+R 不重载客户端 bundle，必须完全重启 DSH** |
+| 点开提示「解析不到绝对路径」 | 裸文件名不在 workspace 内，且 `allowOutside: false`。先确认文件真实路径，再决定是否放宽 |
+| 点开提示「文件已不存在」 | 路径是真的，文件被删/移了。清单里该行会打上删除线 |
+| 点产物名没反应 | ① 文件不在候选 base 下（访问宿主 `/info` 看 `bases`）；② 扩展名不在白名单（`lib/client.js` 的 `EXT`）；③ 直接看 `/resolve?p=<名字>` 返回的 `reason` |
+| 右键没出本插件菜单 | 该处文字没解析成文件（同上）；**对非产物右键本来就不接管**，出的是宿主原生菜单 |
+| 日志里出现 N 份相同输出 | 热重载堆叠了多个实例。**Ctrl+R 无效，必须完全重启 DSH**；同时确认 `window.__dshArtifactLinkerV1.dispose()` 守卫在 |
+
+---
+
+## 目录
+
+```
+dsh-artifact-linker/
+├── package.json          # dsh.bundle + dsh.client（两个都要，缺 bundle 装不上）
+├── cordis.patch.yml      # 插件注册补丁（entry id = 包名，唯一）
+├── lib/
+│   ├── index.js          # 宿主：prompt 段 + 6 条回环路由 + 三源路径解析
+│   └── client.js         # 客户端：__ModuleLoader__.load bundle（id 必须 = 包名）
+├── locale/{zh,en}.json
+├── icon.svg
+├── README.md · CHANGELOG.md · LICENSE
+```
+
+---
+
+<a id="english-summary"></a>
+## English summary
+
+`dsh-artifact-linker` turns every delivered artifact into a one-click target, so you never copy a path into Explorer again.
+
+- **Host half** injects a resident system-prompt rule: always emit **absolute** artifact paths in tooling, but only the **file name** in user-facing prose.
+- **Client half** makes those names clickable — **left click** reveals and selects the file in Explorer, **right click** opens a small menu (reveal / open with default app / copy absolute path). Hovering turns the cursor into a pointer. No floating UI, no document scanning, no timers.
+- Bare file names are resolved with a three-tier fallback (native absolute → workspace-relative → recursive same-name search). Ambiguous matches are surfaced as candidates rather than guessed.
+- All routes are loopback-only, telemetry-free, and spawn nothing through a shell. The client never mutates React-rendered DOM.
+
+MIT licensed.
+
+---
+
+## License
+
+MIT © loyalchiiina

package/cordis.patch.yml

@@ -0,0 +1,52 @@
+# dsh-artifact-linker — 产物路径联动器（双端插件）
+#
+# ── 宿主半边（lib/index.js）──────────────────────────────────────────────────
+#   1. 注册一条常驻 system-prompt 段（ctx.systemPrompt.section，order 200），
+#      让「产物一律输出完整绝对路径」在**每个会话／每个预设**生效，不依赖任何
+#      技能被加载（技能按需加载，prompt 段常驻）；
+#   2. 注册 6 条回环路由：
+#        /info          插件身份 + workspace 信息 + 各开关实际取值
+#        /resolve       {原样路径 | 相对路径 | 裸文件名} → 绝对路径（三源兜底）
+#        /stat          批量 stat + 10s TTL 缓存
+#        /flush-cache   清空宿主端路径解析与 stat 缓存
+#        /reveal        在系统资源管理器里揭示并选中该文件
+#        /open          用系统默认关联程序打开该文件
+#   3. 不写任何文件、不联网（零遥测）；唯一会 spawn 的是 reveal/open 两条
+#      显式路由，且走 execFile 参数数组（不经 shell，无命令注入面），
+#      并带 loopback 来源校验。
+#
+# ── 客户端半边（lib/client.js）──────────────────────────────────────────────
+#   **全程只读正文，一个 DOM 节点都不改、一条属性都不加**（改 React 管理的节点
+#   会在重渲染时白屏，这是本插件刻意规避的第一号风险）。可点性靠：
+#     · document 捕获期 click + caretRangeFromPoint 反查「用户点中了哪个词」，
+#       正则命中产物名/路径即拦截，按修饰键分流；
+#     · 右下角浮动胶囊「📎 N」把本会话检测到的产物聚成清单（Shadow DOM 挂 body）。
+#   修饰键分流：左键 = 资源管理器揭示并选中 / Ctrl·Shift·Cmd = 系统默认程序打开 /
+#               Alt = 复制完整路径。清单每行另有 📍 ↗ ⧉ 三个按钮。
+#   markdown 图片与链接语法一律不接管（避免把图改成芯片导致图不显示）。
+#
+# ── 开关（改完重启 DSH 生效）───────────────────────────────────────────────
+#   injectRules  (默认 true)  常驻 prompt 段：要求模型输出产物绝对路径、正文只写文件名
+#   clientChips  (默认 true)  客户端胶囊与点击接管；置 false 则纯注入模式（只剩 prompt 铁律）
+#   allowOutside (默认 true)  是否允许解析 workspace 之外的路径。产物几乎总在项目盘
+#                             （E:/D:）而不是 DSH workspace 里，所以默认放开。
+#                             **多用户/给别人用时改 false**——那是防止本插件变成
+#                             「模型说个路径就帮你打开任意文件」的安全闸。
+#   statTtlMs    (默认 10000) 宿主端 stat 缓存毫秒数。调小 = 更快反映「文件刚被删」，
+#                             调大 = DOM 重渲染反复问同一路径时更省 IO
+#   searchMaxDepth (默认 2，硬上限 8) 裸文件名反查的递归深度。调大能找回埋得更深的同名
+#                             文件，但 /resolve 的目录遍历成本随之上升
+#   rulesText    (默认内置 6 条) 整体替换注入的铁律文本，可写数组或一个多行字符串。
+#                             想追加自己的规矩（例：「交付前先确认文件字节数非 0」）就写这里
+#                             —— 官方硬规则 #5 要求所有 tunable 必须能在 cordis.yml 改，
+#                             故上述全部可在 profile 的 cordis.patch.yml 里覆盖。
+#
+# 🔴 绝不要再在 profile 的 cordis.patch.yml 里手写同一段 insert —— 同一 entry id
+#    插两行会触发 duplicate loader entry id，插件市场更新时被差回滚。
+- insert:
+    - id: dsh-artifact-linker
+      name: dsh-artifact-linker
+      config:
+        injectRules: true
+        clientChips: true
+        allowOutside: true

package/icon.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Artifact Linker">
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#4f8cff"/>
+      <stop offset="1" stop-color="#7a5cf0"/>
+    </linearGradient>
+  </defs>
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="url(#g)"/>
+  <path d="M24 40 L40 24" stroke="#fff" stroke-width="4" stroke-linecap="round" opacity=".9"/>
+  <circle cx="21" cy="43" r="7" fill="none" stroke="#fff" stroke-width="4"/>
+  <circle cx="43" cy="21" r="7" fill="none" stroke="#fff" stroke-width="4"/>
+</svg>