@doubleelec/dsh-workspace-explorer 0.7.1-fork.4

package/docs/awesome-submission.yml

@@ -0,0 +1,23 @@
+# awesome-dsh-plugin 提交草稿 / Submission draft (not part of this repo's runtime)
+#
+# 达标后(≥10 commits + 维护者答复 dsh.bundle 问题),把下面内容粘贴到 awesome 仓库:
+#   data/plugins/Jiyr0119__dsh-workspace-explorer.yml
+# 并把 screenshots 列表合并进 awesome 仓库的 data/screenshots.json(以仓库 URL 为 key)。
+#
+# Paste into the awesome repo when eligible:
+#   data/plugins/Jiyr0119__dsh-workspace-explorer.yml
+# and merge the screenshots list into data/screenshots.json keyed by the repo URL.
+
+url: https://github.com/Jiyr0119/dsh-workspace-explorer
+name: Jiyr0119/dsh-workspace-explorer
+category: ui
+description:
+  en: Workspace file-tree panel for the DSH web UI, with click or drag-to-composer file references.
+  zh: 为 DSH Web UI 提供工作区文件树面板,点击或拖拽文件引用到输入框。
+
+# data/screenshots.json 条目(1-8 张,GitHub 托管)/ entry for data/screenshots.json
+# "https://github.com/Jiyr0119/dsh-workspace-explorer": [
+#   "https://raw.githubusercontent.com/Jiyr0119/dsh-workspace-explorer/main/assets/screenshots/panel.png",
+#   "https://raw.githubusercontent.com/Jiyr0119/dsh-workspace-explorer/main/assets/screenshots/tree.png",
+#   "https://raw.githubusercontent.com/Jiyr0119/dsh-workspace-explorer/main/assets/screenshots/insert.png"
+# ]

package/docs/experience.md

@@ -0,0 +1,252 @@
+# DSH 插件开发经验与 awesome-dsh-plugin 提交流程 / Dev Experience & awesome Submission
+
+> 本文档沉淀本仓库开发过程中验证过的经验(截至 v0.4.0),供后续迭代、新插件开发、提交 awesome 时直接复用。
+> This doc captures validated experience up to v0.4.0 for future iterations, new DSH plugins, and awesome-dsh-plugin submission.
+
+---
+
+## 一、DSH 插件形态:原生 npm 包 / Plugin shape
+
+本插件为原生单包:`dsh plugin --profile web add @doubleelec/dsh-workspace-explorer@latest`,持久安装,重启保留,支持 dsh-market 一键安装。(历史上的动态粘贴版已在 v0.7.2 移除,不再维护。)
+
+## 二、原生包架构(三件套)/ Native package architecture
+
+```
+src/index.ts           → lib/index.js   (Host: webServer 路由)
+src/client/index.tsx   → lib/client.js  (浏览器:__ModuleLoader__ bundle)
+dsh.plugin.json        (id / main / client.main)
+cordis.patch.yml       (composition 行)
+```
+
+### 1. Host 半 — webServer 路由(不需要上游 PR)
+
+```ts
+import type { WebServer } from '@deepseek-ai/dsh-host-webserver'
+
+export function apply(ctx: { webServer: WebServer }) {
+  ctx.webServer.register({
+    kind: 'exact' as const,          // 'exact' | 'prefix'
+    path: '/dsh-we/api/list',
+    handler: async (req, res) => {
+      // req: { url?, method?, headers, [Symbol.asyncIterator]() }
+      // res: { statusCode, writeHead(status, headers?), end(body?) }
+      res.statusCode = 200
+      res.writeHead(200, { 'content-type': 'application/json' })
+      res.end(JSON.stringify(payload))
+    },
+  })
+}
+```
+
+要点:
+- 第三方包可直接 `ctx.webServer.register` 注册 HTTP 路由,不需要改 DSH 核心(已由 `omdsh-dev/DSH-better-sidebar` 与本项目验证)。
+- `@deepseek-ai/cordis`(npm 版)缺少 `webServer` 成员声明,需要自己在源码里 `declare module 'cordis'` 增强。
+- Host 不要碰浏览器 API;文件系统用 `node:fs/promises`。
+
+### 2. 浏览器半 — tsdown 打包成模块加载器闭包
+
+- 产物必须形如:
+
+```js
+window.__ModuleLoader__.load({ id: '@jiyr0119/dsh-workspace-explorer', factory: (require) => {
+  var module = { exports: {} }; var exports = module.exports;
+  // ...bundle...
+  return module.exports;
+}})
+```
+
+- **client bundle 的 `id` 必须等于 npm 包名(含 scope)** —— client-modules 按包名键控,不一致会导致面板不挂载。tsdown.config.ts 里写死 `ID = '@jiyr0119/dsh-workspace-explorer'`(不要用 `pkg.name` 动态拼)。
+- 打包工具链:**tsdown `^0.22` + lightningcss `^1.32`**。tsdown 0.6.x 与 rolldown 不兼容(FATAL `transformPlugin`),务必用新版本。
+- externals:`react` / `react-dom` / `@deepseek-ai/cordis` / `dsh-client-*` 等平台模块全部外置,不打进 bundle。
+- CSS Modules 用 lightningcss 内联(哈希类名 + `<style data-plugin>` 注入),样式零额外请求。
+- 动态插件迁移到原生时,面板 JSX 基本可整份移植,只改 i18n / slots 的取用方式。
+
+### 3. 装配文件
+
+- `dsh.plugin.json`:
+
+```json
+{
+  "id": "dsh-workspace-explorer",
+  "version": "0.4.0",
+  "main": "./lib/index.js",
+  "client": { "main": "./lib/client.js" }
+}
+```
+
+- `cordis.patch.yml`:往 composition 插入一行。**作用域包名必须加引号**,否则 `dsh web` 启动解析补丁崩溃:
+
+```yaml
+- insert:
+    - id: workspace-explorer
+      name: '@jiyr0119/dsh-workspace-explorer'
+```
+
+- package.json 里 `dsh.bundle.patch` 指向 `./cordis.patch.yml`,`dsh.plugin` 填插件元数据。
+
+### 4. 依赖版本(血泪教训)
+
+- 用 **rc.6 家族**:`@deepseek-ai/dsh-client-*` / `dsh-host-webserver` / `dsh-invariants` 均为 `^0.1.0-rc.6`;`@deepseek-ai/cordis ^4.0.1`;`cordis ^4.0.0-rc.7`。
+- **rc.1 家族在 npm 上装不上**(缺 `@deepseek-ai/dsh-paths`,eresolve E404)——不要用。
+
+## 三、发布前必做验证(缺一不可)/ Mandatory pre-publish checks
+
+> 真实安装踩过的坑(0.3.0–0.4.0 三轮):
+> ① `cordis.patch.yml` 作用域包名未加引号 → `dsh web` 启动崩溃(`bad indentation of a mapping entry`;`@` 不能作 YAML 裸标量起始);
+> ② `webServer.register` 传入**数组** → 路由全部静默失效(数组被塞进前缀表 key=undefined,`/dsh-we/api/*` 全未注册,浏览器 `fetch().json()` 报 `Unexpected end of JSON input`);
+> ③ 侧边栏旧入口按钮残留:新版本改用会话头部图标后,旧 `sidebar.footer.action` 按钮仍显示——用**空占位注册**(注册一个空组件)顶掉旧按钮,保证唯一入口。
+> **register 一次只能注册一个路由,必须逐个调用,不能传数组。**
+
+```bash
+# 1) 构建
+npm run build
+
+# 2) 补丁解析回归:临时 profile 装一次,跑组合解析
+dsh plugin --profile preflight add -w "file:$(pwd)"
+dsh --profile preflight --dump-config >/dev/null && echo OK
+rm -rf "$HOME/.dsh/profiles/preflight"
+
+# 3) Host 路由功能验证:真实 webServer 服务 + 全部 /dsh-we/api/* 路由
+#    (仓库 .wecheck 系列临时脚本:list / config / peek / bad-rel 校验)
+
+# 4) 真实挂载确认(浏览器):装进真实 web profile 并重启 dsh web
+#    dsh plugin --profile web add -w @jiyr0119/dsh-workspace-explorer@latest
+#    重启后会话头部出现 📁 文件按钮,面板可展开目录 / 拖拽插入 / 设置生效
+```
+
+注意:现代 pnpm(9/10)在 workspace root 直接 `add` 会报 `ERR_PNPM_ADDING_TO_ROOT`,命令必须带 `-w`。
+
+### UI 定位经验(v0.4.0 弹窗化)
+
+- 面板不占用壳的 details 列:不要调 `layout.openDetails/closeDetails` 抢占壳的「工具调用详情」;自己用 `shell.overlay` + 绝对定位浮层。
+- 弹窗位置**实时测量**:锚在会话头部底部与 composer 顶部之间,窗口缩放/布局变化时跟随,绝不遮挡输入框。
+- 动画尊重 `prefers-reduced-motion`(用户关动画时不要强制播放)。
+- `DockBridge` 等输入桥要对 `useInput` 等外部 prop 做空值守卫,避免壳未注入时崩溃。
+
+## 四、npm 发布 / npm publish
+
+```bash
+npm run build
+npm publish            # 账号开 2FA 时,需输入一次性验证码(OTP)
+```
+
+- `prepublishOnly: npm run build` 会自动重新构建,无需手动先跑。
+- 账号开启 2FA 后 `npm publish` 会要求 OTP(30 秒过期,不适合转交别人代跑)。
+- 版本号保持三处同步:`package.json` / `dsh.plugin.json` / `manifest.json`(CHANGELOG 同步记)。
+
+## 五、GitHub 提交身份 / Commit identity
+
+- GitHub 仓库:作者名 `Jiyr0119`,邮箱 `jiyr0119@gmail.com`(仓库级 `git config` 强制;公司环境用 `~/.gitconfig` 的 `includeIf "gitdir:~/workspaceforme/"` 自动切换)。
+- 不要用公司邮箱/真名提交 GitHub 公开仓库。
+- 若历史里混入错误身份,可用 `git filter-branch --env-filter` 重写 + `--tag-name-filter cat` + force push(注意 SHAs 全变,协作者需 reset)。
+
+## 六、awesome-dsh-plugin 提交流程 / Submission workflow
+
+> ⚠️ **仓库关系(重要,别再搞错)**:真正的上游是 **`awesome-dsh-plugin/awesome-dsh-plugin`**(官方组织,源仓库)。`omdsh-dev/awesome-dsh-plugin` **本身也是一个 fork**(parent 指向官方仓库),不是上游!提交 PR 一律走官方仓库;本地 clone 只认官方 upstream + 自己的 fork `Jiyr0119/awesome-dsh-plugin`。**判断"上游是什么"要用 `gh api repos/<repo> --jq .parent` 核实,别凭 README 或直觉。**
+> ⚠️ **流程(2026-08-17 核实,别再被带偏)**:canonical 上游**没有重构**——README 仍由 **`data/plugins/*.yml` + `node scripts/generate-readme.mjs` 生成**,**禁止手改 README**。PR check 的 CI 步骤 `READMEs match data/plugins` 会校验一致性,手改 README 直接 CI 失败(`generate-readme.mjs --check` 不通过)。
+> ⚠️ **"直接改 README"的教训**:曾把 omdsh-dev fork 的某次重构状态误当成 canonical 现状,按"直接改 README"提了 PR #1359 → CI 失败被关闭。**任何"上游重构"的说法都要在 canonical 仓库上亲自验证**(`git ls-tree upstream/main scripts/` 看有没有 generate-readme.mjs)。
+> ✅ **已收录**:PR **#1158**(2026-08-16,双语)已合并,条目 + 3 张截图在官方仓库。v0.4.0 描述更新走 **PR #1362**(2026-08-17,双语,CI 全绿 CLEAN)。
+
+### 1. 门槛要求(贡献指南)
+
+- 仓库的 `package.json` 声明 **`dsh.bundle`**(`dsh.bundle.patch` → `cordis.patch.yml`),只声明 `dsh.client` 会被拒。
+- 仓库有真实可用的代码、活跃维护;添加 `dsh-plugin` topic;repo 年龄 ≥ 1 天、commits ≥ 10。
+- 描述只说功能,不带营销词(superlatives)。
+
+### 2. 正确流程(先 issue,后 PR)/ The right workflow
+
+**canonical 维护者习惯:先提一个双语 issue 讨论(如 #1142 / #1361),按维护者建议再提双语 PR(#1158 / #1362)。不要跳过 issue 直接提 PR。**
+
+```bash
+# 0) 准备:clone 自己的 fork,加官方 upstream(别加 omdsh-dev!)
+gh repo clone Jiyr0119/awesome-dsh-plugin && cd awesome-dsh-plugin
+git remote add upstream https://github.com/awesome-dsh-plugin/awesome-dsh-plugin.git
+
+# 1) 双语 issue(中英对照,描述改动意图 + 拟更新文案)
+gh issue create --repo awesome-dsh-plugin/awesome-dsh-plugin --title "..." --body-file issue.md
+
+# 2) 从 canonical 最新 tip 建分支(fork 的 main 可能因 shallow clone 历史不相关)
+git fetch upstream main
+git checkout -b feat/xxx upstream/main
+
+# 3) 改 YAML 数据源(README 勿手改!)
+#    data/plugins/Jiyr0119__dsh-workspace-explorer.yml  → description.en / description.zh
+
+# 4) 重新生成 README + 本地跑全部 PR check 步骤
+npm ci
+node scripts/generate-readme.mjs          # 重新生成两个 README
+node scripts/generate-readme.mjs --check  # 校验通过
+npx awesome-lint                          # 应 exit 0(存量 warning 可忽略)
+node scripts/build-site.mjs               # 应 exit 0
+
+# 5) 提交(README.md + README.zh.md + YAML 一起)→ push → 双语 PR
+git add README.md README.zh.md data/plugins/Jiyr0119__dsh-workspace-explorer.yml
+git commit -m "Update ... description to v0.4.0"
+git push origin feat/xxx
+gh pr create --repo awesome-dsh-plugin/awesome-dsh-plugin --base main --head Jiyr0119:feat/xxx \
+  --title "更新 ... 描述至 v0.4.0 / Update ... description to v0.4.0" --body-file pr.md
+
+# 6) 等 CI(~1 分钟内),确认 check SUCCESS + mergeState CLEAN
+gh pr view <num> --repo awesome-dsh-plugin/awesome-dsh-plugin --json statusCheckRollup,mergeStateStatus
+```
+
+### 3. YAML 条目格式
+
+```yaml
+url: https://github.com/Jiyr0119/dsh-workspace-explorer
+name: Jiyr0119/dsh-workspace-explorer
+category: ui
+description:
+  en: 'Standalone workspace file-tree panel for the DSH web UI: ...; single-purpose, zero-config, one-command install.'
+  zh: '独立单功能的工作区文件树面板：...；零配置，一条命令即装即用。'
+```
+
+- 描述以句号结尾;含 `: `(英文冒号+空格)必须加引号;避免裸 `[file: ...]`(awesome-lint no-undefined-references,需转义 `\[file: ...\]`)。
+- 截图在 `data/screenshots.json`(key = 仓库 URL,值 = raw.githubusercontent 图片数组,已收录 3 张)。
+
+### 4. 差异化定位(单插件 vs 全家桶)/ Product positioning
+
+awesome 里大量 UI 插件是**一整套工作台**(如 `omdsh-dev/DSH-better-sidebar`:文件编辑 + 终端 + Git + 子代理全家桶,还有配套的 workspace-search / media-preview 等子插件)。本插件定位要突出**单插件、即插即用**:
+
+- **独立单插件**:只做「工作区文件树 + 引用插入」一件事,不捆绑终端/Git/子代理等,不抢占壳的 details 列与工具详情。
+- **即插即用**:`dsh plugin add` 一条命令装完即用,零配置、无构建、不依赖其他插件;原生包自带 host 路由 + 浏览器 bundle。
+- 描述用「standalone / single-purpose / zero-config / one-command」这类事实词,和 better-sidebar 的「full sidebar workbench」形成对比。
+
+### 5. 合并冲突与查重
+
+- 合并冲突时:README 是生成的,冲突通常出现在 YAML 或 README 的相邻条目行——取 theirs(其他条目优先),把自己的行补回去,重新 `generate-readme.mjs`。
+- 提交前用 `gh search prs --repo awesome-dsh-plugin/awesome-dsh-plugin "owner名"` 查是否已有条目/PR,别重复新增(已有条目应走**更新描述**而非新增一行)。
+
+### 6. 收录 ≠ 浏览器自动生效
+
+- dsh-market(DSH 内商店)自动同步 awesome 列表;但**商店收录不代表插件装完就有 UI** —— 0.2.0 原生化之前,商店安装只有 host 端、没有浏览器面板。README 要诚实写明当前安装方式的效果。
+
+---
+
+## 七、i18n(原生包)/ Localization
+
+```ts
+import { useLocale } from '@deepseek-ai/dsh-client-locale'
+const { t } = useLocale('dsh-workspace-explorer')   // 命名空间唯一,避免与官方冲突
+```
+
+- DSH 只支持 zh / en 两个 locale;词典用 `locale.register(ns, locale, dict)` 注册、`locale.bind(ns)` 取稳定 `t()`。
+- 插件 UI 文本全部走 t(),不允许硬编码中文/英文。
+
+## 八、动态插件版本的经验(迁移前形态)/ Dynamic plugin lessons
+
+- TDZ:`addWorkspace` 等函数声明必须放在引用它的代码**之前**,否则 `Cannot access before initialization`(浏览器直接挂)。
+- 预览图标 click 与拖拽冲突(行可拖拽会吞 click):改用 `onMouseDown` + `preventDefault` + `stopPropagation` 打开预览,键盘 `P` 也能开。
+- 面板过高挡住输入框:`height: min(640px, calc(100dvh - 110px))`,并设最小高度。
+- `slots.inject` 类型:组件类型收不严时,把 inject 函数签名放宽为返回 `unknown`。
+
+## 九、版本演进时间线(v0.2.0 → v0.4.0)/ Release timeline
+
+- **v0.2.0** — 原生单包重构:Host `src/index.ts`(webServer `/dsh-we/api/list` + `/peek`)+ 浏览器 `src/client/index.tsx`(dsh.plugin.json client.main + `__ModuleLoader__`)。
+- **v0.3.0** — 顶部 Tab(文件/设置)+ 设置页(隐藏噪声目录/显示大小/引用格式/预览行数/面板宽度),设置镜像进 DSH 设置壳;Host 加 `/dsh-we/api/config`。
+- **v0.3.1** — 修复 `cordis.patch.yml` 作用域包名未加引号导致的 `dsh web` 启动崩溃。
+- **v0.3.2** — 修复 `webServer.register` 传数组导致路由静默失效;面板改为右上角 dock 式(可拖宽 280–640px)。
+- **v0.4.0** — 面板从 details 列抽屉改为**浮动弹窗**,入口移到会话头部文件树图标;位置实时测量在 header 与 composer 之间;空占位顶掉旧侧边栏按钮;不占用壳的 details 列。
+- **v0.5.0** — **M1 读路径完成**:多选批量插入(Shift/⌘ + 底部操作条)、目录拖拽插入限层紧凑目录树(`/dsh-we/api/tree`)、分页全量预览(peek 支持 offset/limit/whole,≤4MB 整读精确行数、大文件块扫描、二进制 8KB 嗅探);动态版同步(`ws-tree.tree` RPC,>8MB 走 tooLarge 降级)。
+- **v0.5.1** — 会话头部入口升级为**「功能名称 + 图标」胶囊**(对标 DSH 原生 Session log 下载按钮:描边圆角、名称 + 13px 文件夹图标、激活态高亮);原生 + 动态双份同步,新增 `drawer.label` 词典键;演示页重构为当前产品形态并重录 GIF(多选/目录拖拽/分页预览/设置)。
+- **npm 版本同步**:每版同步更新 `package.json` / `dsh.plugin.json` / `manifest.json` / `CHANGELOG.md` 四处。

package/docs/install.md

@@ -0,0 +1,26 @@
+# 安装指南
+
+唯一安装方式:原生安装(`dsh plugin add` / 商店)。
+
+```bash
+dsh plugin --profile web add -w @doubleelec/dsh-workspace-explorer@latest
+```
+
+npm 包同时提供原生 Host 半区(`lib/index.js`,webServer JSON 路由 `/dsh-we/api/list|peek|tree|config|write`)和浏览器 bundle(`lib/client.js` 经 `dsh.plugin.json`),一条命令装好后会话头部即出现「工作区文件」胶囊按钮,无需任何构建或配置。
+
+安装完成后重启或硬刷新 `dsh web`。若 profile 的 `node_modules` 尚未初始化,先 `pnpm install`。
+
+> ⚠️ **常见误解**:插件市场收录 ≠ 插件自动出现在用户浏览器。收录 = 用户能浏览条目 + 执行安装命令。**原生安装(v0.4.0+)已验证 `dsh plugin add` 干净安装、无启动报错**;注意现代 pnpm 需在命令加 `-w`(或在 profile 的 `.npmrc` 写 `ignore-workspace-root-check=true`)。
+
+## 发布到 GitHub
+
+```bash
+cd dsh-workspace-explorer
+git init
+git add .
+git commit -m "init: dsh-workspace-explorer"
+git remote add origin https://github.com/<your-org>/dsh-workspace-explorer.git
+git push -u origin main
+```
+
+建议在仓库描述里带上 `deepseek-harness`、`cordis`、`plugin` 等关键词,方便检索。

package/docs/local-debugging.md

@@ -0,0 +1,197 @@
+# DSH 插件本地调试指南
+
+## 启动本地 DSH 开发环境（端口 3090）
+
+```bash
+# 方式一：使用 dsh web dev（推荐，已配置 alias）
+dsh web dev
+
+# 方式二：直接指定 profile 和端口
+dsh --profile dev --port 3090
+```
+
+启动后访问 http://127.0.0.1:3090
+
+> **注意：** 3080 是正式版（npm 安装的插件），3090 是开发版（本地链接的插件），两者完全隔离，互不影响。
+
+---
+
+## 将本地插件链接到 3090 环境
+
+### 1. 编辑 dev profile 的 package.json
+
+```bash
+vim ~/.dsh/profiles/dev/package.json
+```
+
+添加插件依赖和 bundles 配置：
+
+```json
+{
+  "name": "dsh-profile-dev",
+  "private": true,
+  "dependencies": {
+    "@jiyr0119/dsh-workspace-explorer": "file:/Users/jonathan/workspaceforme/dsh-workspace-explorer",
+    "dshmarket": "^1.15.0"
+  },
+  "dsh": {
+    "profile": {
+      "bundles": [
+        "@deepseek-ai/dsh-base",
+        "@deepseek-ai/dsh-web-app",
+        "dshmarket",
+        "@jiyr0119/dsh-workspace-explorer"
+      ]
+    }
+  }
+}
+```
+
+### 2. 安装依赖
+
+```bash
+cd ~/.dsh/profiles/dev
+pnpm install
+```
+
+### 3. 用 symlink 替换 npm 版本（关键步骤）
+
+```bash
+# 删除 pnpm 安装的版本
+rm -rf ~/.dsh/profiles/dev/node_modules/@jiyr0119/dsh-workspace-explorer
+
+# 创建 symlink 指向本地项目
+ln -s /Users/jonathan/workspaceforme/dsh-workspace-explorer ~/.dsh/profiles/dev/node_modules/@jiyr0119/dsh-workspace-explorer
+```
+
+### 4. 验证链接
+
+```bash
+ls -la ~/.dsh/profiles/dev/node_modules/@jiyr0119/dsh-workspace-explorer
+# 应该显示 → /Users/jonathan/workspaceforme/dsh-workspace-explorer
+```
+
+---
+
+## 开发工作流
+
+```
+修改代码 → npm run build → 刷新浏览器（不需要重启 DSH）
+```
+
+1. 在本地项目目录修改代码
+2. 执行 `npm run build` 构建
+3. 刷新 http://127.0.0.1:3090 即可看到变化
+
+**注意：** symlink 方式下，DSH 直接读取 `lib/` 目录的构建产物，所以只需要 build，不需要重启服务。
+
+---
+
+## 快捷脚本
+
+### 添加新插件
+
+```bash
+~/.dsh/profiles/dev/add-plugin.sh @jiyr0119/my-plugin ~/workspaceforme/my-plugin
+```
+
+### 移除插件
+
+```bash
+~/.dsh/profiles/dev/rm-plugin.sh @jiyr0119/my-plugin
+```
+
+---
+
+## 发布新版本
+
+```bash
+# 1. 升级版本号
+# package.json 和 dsh.plugin.json 中的 version 同步修改
+
+# 2. 运行测试
+npm test
+
+# 3. 登录 npm（如果未登录）
+npm login
+
+# 4. 发布
+npm publish
+```
+
+---
+
+## 常见问题
+
+### Q: 刷新后插件没有加载？
+
+检查 symlink 是否存在：
+```bash
+ls -la ~/.dsh/profiles/dev/node_modules/@jiyr0119/dsh-workspace-explorer
+```
+
+如果不存在，重新执行步骤 3 创建 symlink。
+
+### Q: 修改代码后刷新没有变化？
+
+确保已执行 `npm run build`。symlink 只是链接目录，不会自动构建。
+
+### Q: 3090 端口被占用？
+
+```bash
+# 查找占用端口的进程
+lsof -nP -iTCP:3090 -sTCP:LISTEN
+
+# 终止进程
+kill <PID>
+```
+
+### Q: 想用 npm 注册的正式版本测试？
+
+```bash
+# 删除 symlink，重新安装 npm 版本
+rm ~/.dsh/profiles/dev/node_modules/@jiyr0119/dsh-workspace-explorer
+cd ~/.dsh/profiles/dev
+pnpm install
+```
+
+---
+
+## 目录结构
+
+```
+~/.dsh/profiles/
+├── web/                          # 正式版（3080）
+│   ├── package.json              # npm 安装的插件
+│   ├── node_modules/
+│   └── cordis.patch.yml
+│
+└── dev/                          # 开发版（3090）
+    ├── package.json              # file: 依赖
+    ├── node_modules/
+    │   └── @jiyr0119/
+    │       └── dsh-workspace-explorer → /path/to/local/project  (symlink)
+    ├── add-plugin.sh             # 添加插件脚本
+    ├── rm-plugin.sh              # 移除插件脚本
+    └── cordis.patch.yml
+
+/path/to/local/project/
+├── src/                          # 源码
+├── lib/                          # 构建产物（DSH 实际加载的）
+├── dsh.plugin.json               # 插件配置
+└── package.json
+```
+
+---
+
+## ⚠️ 重要提醒
+
+**不要用 `file:` 依赖 + `pnpm install` 的方式！**
+
+pnpm 的 `file:` 依赖会在 store 里创建副本，rebuild 后不会自动更新。必须：
+
+1. `pnpm install` 安装依赖
+2. **删除** pnpm 安装的版本
+3. **手动创建** 直接指向本地目录的 symlink
+
+这样 rebuild 后只需要刷新浏览器，不需要重启服务。

package/docs/publish.md

@@ -0,0 +1,47 @@
+# 发布到 npm / Publishing to npm
+
+> 本仓库用国内镜像做日常依赖安装,但**发布必须走官方源**(镜像站只读,不接受 publish)。所有 npm 发布命令显式带 `--registry=https://registry.npmjs.org/`,不要写进 `.npmrc`,免得日常安装也被拖慢。
+
+## 首次发布前准备
+
+1. 注册 npm 账号:https://www.npmjs.com/signup(验邮箱)
+2. 本包 scope 为个人用户名,无需建组织:`@doubleelec/dsh-workspace-explorer`
+3. 开 2FA(发布强制要求):头像 → Account Settings → Two-Factor Authentication
+
+## 发布流程
+
+```powershell
+cd D:\Users\Elec\Documents\dsh-plugins-workspace
+
+# 1) 登录(走官方源;2FA 要输 OTP)
+npm login --registry=https://registry.npmjs.org/
+
+# 2) 版本号三处同步(package.json / dsh.plugin.json / manifest.json),
+#    CHANGELOG 定版,构建验证
+npm run build
+npm run typecheck
+
+# 3) 发布 —— 版本号含 `-fork`(semver 预发布),必须显式指定 dist-tag,
+#    否则 npm 报错 "You must specify a tag using --tag"
+npm publish --registry=https://registry.npmjs.org/ --tag fork
+
+# 4) 验证
+npm view @doubleelec/dsh-workspace-explorer version --registry=https://registry.npmjs.org/
+```
+
+说明:
+
+- `--tag fork`:预发布版本不会污染 `latest` 标签;用户安装用 `dsh plugin add @doubleelec/dsh-workspace-explorer@fork` 或显式版本号。正式版去掉 `-fork` 后缀后可正常发 `latest`。
+- `prepublishOnly` 会自动再构建一次,构建产物抖动(CSS 类名哈希顺序)属正常,提交即可。
+- 发错 72 小时内可撤回:`npm unpublish @doubleelec/dsh-workspace-explorer@<version> --registry=https://registry.npmjs.org/`。
+- 包内容清单:`lib/` + `dsh.plugin.json` + `manifest.json` + docs(见 `package.json` 的 `files` 字段)。
+
+## 发布到 GitHub
+
+源码推送正常走 `git push elec main`(见仓库既有流程);npm 发完后打 tag:
+
+```powershell
+git tag v0.7.1-fork.4
+# (用存量凭证推送,见既有发布流程)
+git push elec v0.7.1-fork.4
+```

package/docs/verify-native.md

@@ -0,0 +1,51 @@
+# 原生挂载验证手册 / Native Mount Verification (v0.2.0)
+
+目标:验证 `dsh plugin add` / market 一键安装后,**浏览器面板真实出现**。
+
+## 前置
+
+- 已构建:`lib/index.js`(host)+ `lib/client.js`(browser,`__ModuleLoader__` id = `@jiyr0119/dsh-workspace-explorer`)
+- 打包:`npm pack` → `@jiyr0119-dsh-workspace-explorer-0.2.0.tgz`(示例已生成在 `/tmp/`)
+
+## 步骤
+
+```bash
+# 1. 装进 web profile(pnpm 需可用)
+cd ~/.dsh/profiles/web
+pnpm add /tmp/jiyr0119-dsh-workspace-explorer-0.2.0.tgz
+
+# 2. 追加插件行到组合(先备份 cordis.yml)
+cp cordis.yml cordis.yml.bak
+# 在 cordis.yml 末尾追加(若该文件是补丁式,改用 dsh plugin add 自动写入):
+#   - id: workspace-explorer
+#     name: @jiyr0119/dsh-workspace-explorer
+
+# 3. 重启 dsh web(⚠️ 会中断当前 DSH 会话)
+#    (重新执行你平时的启动命令,如 pnpm dev / dsh web)
+```
+
+> 若 `dsh plugin --profile web add` 支持本地路径,可直接:
+> `dsh plugin --profile web add /tmp/jiyr0119-dsh-workspace-explorer-0.2.0.tgz`
+
+## 验证清单
+
+- [ ] 侧边栏底部出现 📁「文件」按钮,点击后**右侧面板出现**
+- [ ] 目录树加载(list 路由)→ 展开目录 → 点击文件插入 `[file: …]` 引用
+- [ ] 拖拽文件到输入框插入引用;拖拽提示正常
+- [ ] 搜索过滤、👁 预览(peek 路由)、中英切换正常
+- [ ] 硬刷新(Cmd/Ctrl+Shift+R)后面板仍在(client 改动无需重启 host)
+
+## 回滚
+
+```bash
+cd ~/.dsh/profiles/web
+git checkout cordis.yml        # 或 cp cordis.yml.bak cordis.yml
+pnpm remove @jiyr0119/dsh-workspace-explorer
+# 重启 dsh web
+```
+
+## 已知待确认点
+
+- profile 当前无 node_modules(从未装过插件):`pnpm add` 会拉取依赖,确认 pnpm 可用
+- host 半区注入 `webServer` 的准确性:若挂载报 `service "webServer" is not declared`,说明该 DSH 版本服务名不同,需按当时版本调整(见 `src/index.ts` 的 `inject`)
+- `/dsh-we/api/*` 路由无信任围栏(首版从简),后续按 better-sidebar 的 trust-fence 模式补充

package/dsh.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "dsh-external/elec-workspace-explorer",
+  "version": "0.7.1-fork.4",
+  "main": "./lib/index.js",
+  "description": "工作区文件资源管理器:右侧面板展示目录树,点击/拖拽插入文件引用,含搜索/预览/国际化。Workspace file explorer panel with click/drag references, search, preview, i18n.",
+  "engines": {
+    "dsh": ">=0.1.1"
+  },
+  "contributes": {
+    "tools": [],
+    "skills": []
+  },
+  "client": {
+    "main": "./lib/client.js"
+  }
+}