dsh-links-panel 0.0.0-stage → 0.77.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The dsh-links-panel authors
+
+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,161 @@
-# Temporary Holding Version
+# dsh-links-panel
 
-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.
+A **Reference Links** tab for the right sidebar of [DeepSeek Harness](https://github.com/brickhu/dsh-plugins) (DSH).
+It collects every URL that appears in the current conversation into one list — with pins,
+turn counts, real site icons, manual renaming, hiding, search and a keyboard shortcut —
+so you never have to scroll back through a long chat to find that link again.
+
+- Design notes: [DESIGN.md](DESIGN.md)
+- 中文说明: [README.zh.md](README.zh.md)
+- Requires DSH `>=0.2.1-rc.3 <0.3.0` (declared in `package.json` → `engines.dsh`)
+- No build step: the client half is a self-contained lazy-CJS bundle
+
+---
+
+## What it does
+
+| Capability | Behaviour |
+|---|---|
+| **Collect** | Every `http(s)` URL from user and assistant messages (plain URLs and Markdown links), plus the titles/URLs carried by successful `web_search` / `web_fetch` results. |
+| **Ignore noise** | URLs that only appear in `bash`, `read`, `edit`, `write`, `grep`… results, or in tool *arguments*, are never collected. Static assets, private hosts, IP literals, placeholder domains and API endpoints are filtered out. |
+| **Live** | The panel is event-driven: a new `web_fetch` result appends its URL while the agent is still streaming, and a background tracker keeps collecting even when the tab is closed. |
+| **Titles** | Titles come **only from the conversation** — Markdown labels, `web_search` result titles, the page title line inside a successful `web_fetch` result — or from your own rename. Otherwise the URL itself is shown. No remote title probing ever happens. |
+| **Turns** | Each row shows how many **turns** mentioned the URL. Click the badge to open a dialog listing every turn, with relative timestamps (`5d ago`, `just now`) and “click to view” on hover, jumping straight to that turn. |
+| **Pins** | Pin links to a separate “Pinned” section at the top. Pins are global and survive restarts. |
+| **Hidden** | Hide a single link or the whole host (`a.baidu.com`, never `baidu.com`). Hidden links stay expandable and restorable. |
+| **Icons** | A global favicon library keyed by host / registrable domain. Hosts without an entry are probed **one host at a time** through the Host process, then cached forever. Deterministic hash icons are the final fallback, and monochrome icons are inverted when they would disappear on the current light/dark theme. |
+| **Search** | Search title or domain. While searching, grouping and collapsible sections are replaced by a flat list headed `Search results (N)`. |
+| **Keyboard** | `⌘⇧L` on macOS, `Ctrl+Shift+L` elsewhere. The shortcut works from the conversation and is displayed on the guide card. |
+
+## Installation
+
+### From npm (recommended)
+
+1. Open DSH → right sidebar → **Plugins**.
+2. Install the bundle by name: `dsh-links-panel` (or `npm:dsh-links-panel`).
+3. Select the bundle for your profile and restart DSH.
+4. Open a conversation, expand the right sidebar, click **+** → **Reference Links**.
+
+### Local development / linking this repository
+
+The desktop profile lives at `~/.dsh/profiles/<profile>` (default `desktop`) and is owned
+by the Electron app, so use the bundled installer instead of editing it by hand:
+
+```bash
+# from the repository root
+node references/scripts/install.mjs              # symlink + dependency + bundle patch
+node references/scripts/install.mjs --uninstall  # restore the pre-install profile
+```
+
+The script backs up `package.json`, `pnpm-lock.yaml` and `cordis.patch.yml` to
+`~/.dsh/profiles/desktop/.dsh-links-backup/` on first install; re-running it only
+updates the symlink (useful after moving the repository).
+
+### Restarting
+
+DSH loads plugin halves at app launch and caches the client bundle. After changing this
+plugin **quit the app completely** (`Cmd+Q`, the Dock icon must disappear) and start it
+again. The build stamp in the panel footer (e.g. `v0.77.0`) tells you which build is
+actually running.
+
+## Using the panel
+
+- **Sections** — `Pinned (N)`, `All links (N)`, `Hidden (N)`. Section headers are
+  collapsible; hover a header for the chevron. Counts are omitted while searching.
+- **Rows** — click opens the link in the built-in browser, `⌘`/`Ctrl`+click in the system
+  browser. Long titles are truncated with a gradient mask and shown in full by a marquee
+  on hover.
+- **Row menu (⋮)** — `Copy link` · `Open in built-in browser` · `Open in system browser` ·
+  `Edit title…` · `Hide this link` · `Hide all from <host>` · `Pin this link`.
+- **Edit title…** — inline dialog with `Leave empty to restore the automatic title`;
+  custom titles persist and win over conversation titles.
+- **Footer** — live status, collected link count, `Rescan` (rebuilds this conversation's
+  list from history; pins and the global icon library are kept) and the build stamp.
+  The footer is hidden when the conversation has no links yet; the empty state then shows
+  a centred explanation and its own `Rescan` button.
+- **Empty/hidden states** are fully localized (English / 中文 follow the Harness language).
+
+## Architecture
+
+```
+references/
+  package.json             # dsh.bundle.patch + dsh.client(platform: web), engines.dsh
+  cordis.patch.yml         # Loader insert: id dsh-links, name dsh-links-panel
+  lib/index.js             # Host half: favicon route, serialized outbound requests
+  lib/client.js            # Browser half: tab type, scanning, aggregation, render
+  scripts/install.mjs      # install / uninstall into a DSH profile
+  test/run.mjs             # offline tests (VM + fake React, no DSH required)
+  locale/                  # en/zh manifests for the DSH plugin page
+```
+
+### Host half (`lib/index.js`)
+
+- Registers `GET /dsh-links/favicon?url=…`, which fetches a favicon through
+  `curl` (respecting the desktop system proxy) and returns it as a data URL
+  (64 KB cap; PNG / GIF / JPEG / WebP / ICO / SVG sniffing).
+- Every outbound request is serialized through one promise chain — the plugin never
+  issues parallel network requests.
+
+### Browser half (`lib/client.js`)
+
+- Lazy-CJS module: `window.__ModuleLoader__.load({ id, factory })`, only `react` is
+  required, so the bundle is self-contained.
+- Scans the session event stream (`assistant/message`, `user/message`, and results of
+  web-facing tools only), aggregates rows per seq with a cache, and merges newest titles.
+- Registers the sidebar tab, the guide entry, the pane title and the shortcut.
+- Runs a background tracker over the sessions service so rows keep accumulating while
+  the panel is closed.
+
+## Data stored in the browser
+
+| Key | Contents |
+|---|---|
+| `dsh-links.links.v3:<sessionId>` | Per-conversation rows + scan cursor |
+| `dsh-links.pinned.v1` | Pinned URLs |
+| `dsh-links.customtitles.v1` | User-renamed titles (URL → title) |
+| `dsh-links.favicons.v1` | Global favicon library (host/domain → data URL) |
+| `dsh-links.blocked-hosts.v1` | Globally hidden hosts |
+| `dsh-links.ignored.v1:<sessionId>` | Per-conversation hidden links |
+
+Everything is defensive: storage failures (private mode, quota) only disable persistence,
+never the panel.
+
+## Development
+
+```bash
+node test/run.mjs     # offline test suite (no DSH needed)
+```
+
+The tests cover URL normalization and filtering, event extraction (including tool-result
+titles), aggregation/turn counting, per-seq caching, tab registration, rendering,
+Markdown export, hide/restore semantics, localization dictionaries and the Host half's
+helpers.
+
+To iterate on the UI, link the repository with `scripts/install.mjs`, edit
+`lib/client.js`, then fully restart DSH and confirm the footer build stamp.
+
+## Limitations
+
+- Titles are only as good as the conversation: a bare URL that was never fetched,
+  labelled or renamed shows as the URL.
+- `web_fetch` refuses binary content (`application/pdf` and friends), so PDF links never
+  receive a page title from the fetch pipeline.
+- No remote title scraping and no LLM calls — by design.
+- Icons are fetched once per host and cached; a site that changes its favicon keeps the
+  cached one until the browser storage is cleared.
+
+## Publishing
+
+```bash
+cd references
+npm pack --dry-run      # inspect the package contents
+npm version patch       # or minor / major
+npm publish --access public
+```
+
+Keep `exports` (`"."`, `"./client"`, `"./locale/*.json"`, `"./icon"`, `"./package.json"`),
+`dsh.bundle.patch`, `dsh.client.inject`, `files` and `engines.dsh` intact.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/README.zh.md

@@ -0,0 +1,153 @@
+# dsh-links-panel
+
+DSH 右栏「链接」面板：把当前对话里出现过的全部 http(s) URL 汇总成清单，**按根域名
+分节**，行内显示站点图标 + 页面标题（取不到标题时直接显示 URL）、出现次数；分类
+（资料 / 代码 / 工具 / 媒体，一条链接可带多个）作为筛选标签切换；支持搜索、排序、在右栏浏览器打开、
+回到对话原文、复制成 Markdown 引用清单、忽略噪音链接。
+
+- 设计说明：[DESIGN.md](DESIGN.md)
+- 运行版本：DeepSeek Harness 桌面版 **0.2.1-rc.3**（`package.json` 的 `engines.dsh`）
+- 没有构建步骤；host 半只做一件事：替浏览器读页面标题（跨域限制）
+
+## 结构
+
+```
+references/                 # 本插件工程（宏仓库里的一个子目录）
+  package.json              # dsh.bundle.patch + dsh.client(platform:web)
+  cordis.patch.yml          # - insert: id: dsh-links, name: 'dsh-links-panel'
+  lib/index.js              # host 半：GET /dsh-links/meta，用 ctx.web 解析页面 <title>
+  lib/client.js             # 浏览器半：lazy-CJS bundle，列表 / 分组 / 标题 / 操作
+  scripts/install.mjs       # 装/卸到 ~/.dsh/profiles/<profile>
+  test/run.mjs              # 离线测试（VM + 假 React，不需要 DSH 在跑）
+  DESIGN.md                 # 产品设计
+```
+
+`lib/client.js` 用 lazy-CJS 格式加载，执行时只注册工厂：
+
+```js
+window.__ModuleLoader__.load({
+  id: 'dsh-links-panel',
+  factory: (require) => { /* ... */ return { apply, inject } },
+})
+```
+
+`require` 只能取平台基线模块（这里只用 `react`），所以 bundle 必须自包含。
+
+## 安装（本机 Desktop profile）
+
+桌面版的 profile 在 `~/.dsh/profiles/desktop`，由 Electron 独占管理，`dsh` CLI
+不能直接操作。用仓库里的脚本做和插件管理器等价的三处写入：
+
+```bash
+# 在仓库根目录
+node references/scripts/install.mjs              # 建立软链 + 写 dependency + 选入 bundle
+node references/scripts/install.mjs --uninstall  # 恢复安装前的 profile 文件
+```
+
+也可以进插件目录后 `node scripts/install.mjs`。脚本会把 `package.json` /
+`pnpm-lock.yaml` / `cordis.patch.yml` 首次安装前备份到
+`~/.dsh/profiles/desktop/.dsh-links-backup/`，`--uninstall` 时还原；重复安装只会更新
+软链指向（换仓库位置后重跑一次即可）。
+
+生效方式：
+
+- 桌面版启用了 HMR 时，profile manifest 变化会触发重组，右栏「+」里直接出现
+  「链接」，无需重启；
+- 若没有生效，重启 DeepSeek Harness（重启后会话历史仍在）。
+
+## 使用
+
+1. 打开一个会话，展开右栏（会话头部右上角的展开按钮）。
+2. 右栏顶部「+」→ guide 页 → **链接**。
+3. 点一行在右栏浏览器打开；`Cmd+点击` 走系统浏览器；`⌖` 回到对话原文。
+
+清单操作：
+
+- **标题**：以页面 `<title>` 为准（Host 抓取）；抓不到就用足够的捕获标题兜底，再没有
+  就整行显示 URL。打不开的页面（404/410、域名失效、超时、403、非 HTML）不进列表。
+- **行菜单**：点行尾 `⋮` →「在右栏打开 / 在系统浏览器打开 / 复制链接 / 定位到对话
+  原文 / 忽略这条链接 / 忽略 example.com」。点行本身等于「在右栏打开」。
+- **排列**：列表是平的（无分节头），同一根域名（`docs.acme.dev` 归到 `acme.dev`）的行相邻排列。
+- **标签**：`资料 / 代码 / 工具 / 媒体`，一个链接可以同时有多个（CodePen = 代码 + 工具、
+  Figma = 工具 + 媒体、`.ipynb` = 资料 + 代码）；行尾色点表示标签，顶部 chips 按标签筛选。
+  「被引用」筛选已移除。
+- **复制**：底部「复制」把当前筛选结果复制成 Markdown（按三类分组），可直接粘进
+  笔记或分享。
+- **忽略**：被忽略的条目在底部「已忽略 N」里可以逐条恢复。忽略表按会话存在
+  `localStorage`。
+
+面板底部出现「加载更早」，说明当前只统计了已加载的最近一窗历史，点一下会
+翻一页并自动重扫。
+
+## 解码约定（给维护者）
+
+- URL 语法与截断：`URL_RE` + `trimTrailing`（处理 markdown `](…)`、句末标点、
+  中文标点、不平衡右括号）。
+- 归一化：去 `www.` / 追踪参数 / 锚点 / 尾斜杠，host 小写、路径保大小写。
+- 跳过私网与本地地址；纯数字 host（如 `http://127` 的缩写）也丢弃。
+- 静态资源（`.png/.svg/.ico/.jpg/.webp/.woff/.ttf/.css/.map` 等）不算参考，直接丢弃。
+- 只接受合法主机名，最后一节须像 TLD（字母 ≥2 或 `xn--`）；`https://x$`、`https://a.b`、`https://foo.1` 直接排除。
+- 不接受 IP 字面量（v4/v6，公网也排除）。
+- 排除占位域名：注册域名首段是 `acme`/`example`/`foo`/`bar`/`baz`/`qux`/`demo`/`sample`/`placeholder`/`dummy`/`test`（含 `sub.acme.co.uk`、`foo.com`）。
+- 排除 API / fetch 端点：`api.*`、首段 `api`/`graphql`/`rest`/`rpc`/`openapi`/`swagger`/`jsapi`/`fetch`、`/v2/` 版本路径、`.json`/`.jsonl`/`.ndjson` 数据文件。
+- 不可达的行不展示：Host 探测 404/410 或 DNS/连接失败即隐藏；403、超时、5xx 保留（浏览器可能能打开）。
+- 跳过保留域名：`example.com/.net/.org` 及其子域，`.example/.test/.invalid/.localhost` 后缀。
+- 事件抽取按类型分支；工具名要从 `data.message.toolCallId`（或
+  `data.message.source.callId`）反查 `tool/call` 表，`web_search` 只收 `Sources:`
+  之后，`web_fetch` 只收首行 `Fetched <url>`，避免把抓回整页的导航链接算成参考。
+- 窗口条目类型是 `'event'`（另有 `'transient'` 临时行）；抽取结果按 `seq` 缓存，
+  `tool/result` 在工具名未知前不缓存，等 call 进窗口后重算一次。
+- 标题与图标：每次 tab 重新可见就用 `IntersectionObserver` 触发一轮刷新（Host 路由带 `refresh=1`，绕过缓存），图标优先取页面 `<link rel="icon">`，回退 `/favicon.ico`、再回退字母块；刷新期间保留旧值、失败不覆盖。
+- 标题：以页面 `<title>` 为准；捕获文本只在足够像标题时兜底（CJK ≥2 字 / 含空格
+  且 ≥4 字 / ≥8 字），否则显示 URL。可用性：Host 返回 `dead`（404/410、DNS、拒绝
+  连接）或 `ok:false`（超时、403、非 HTML）的行不展示。标题抓取走 host 路由
+  `GET /dsh-links/meta`（`ctx.web.fetch` + `<title>` 解析），客户端每次挂载最多问
+  24 个、每批 8 个，结果记 `localStorage`（`dsh-links.titles.v1`）。
+- 根域名：`rootDomain` 去 `www.` 后取后两段，内置 `co.uk` / `com.cn` 等少量多段后缀表。
+- 忽略表：`hostIgnored` 做"裸域名覆盖子域名"，`withIgnore` 加宽时吸收被覆盖的窄
+  条目，`restoreOne` 恢复单行时给同域兄弟补 link 级条目；写 `localStorage` 全部包
+  try/catch。
+- Markdown 导出：`markdownOf` 只做纯字符串拼装，标题里的 `[` `]` 会被去掉，避免
+  破坏链接语法。
+
+## 测试
+
+```bash
+node test/run.mjs
+```
+
+断言覆盖：URL 归一化/去重、三类判定、围栏代码、两类工具结果（含 callId 位置）、
+事件聚合与计数、per-seq 缓存、tab 注册参数、首屏渲染与行渲染、Markdown 导出与转义、
+忽略表增删（含子域名覆盖、幂等、单行恢复）、标题接受规则，以及 host 半的 `<title>`
+解析、实体解码、URL 校验与批量请求解析。
+
+## 发布（npm）
+
+这个插件是一个普通的 DSH bundle 包，发布就是打出 npm 包：
+
+```bash
+cd references
+npm pack --dry-run     # 先确认打包内容（会列出 files 里的全部文件）
+npm version patch      # 或 minor / major
+npm publish --access public
+```
+
+发布前检查：
+
+- `package.json` 里不要有 `private: true`（已移除），`name` 用 `dsh-links-panel`；
+- `exports` 必须保留 `"."`、`"./client"`、`"./locale/*.json"`、`"./icon"`、`"./package.json"`；
+- `dsh.bundle.patch` 指向 `cordis.patch.yml`，里面的 `name` 与包名一致；
+- `files` 覆盖运行时全部文件（lib、cordis.patch.yml、locale、icon、README、LICENSE）；
+- `engines.dsh` 与你验证过的 Harness 版本一致；`dsh.client.inject` 声明 UI 依赖。
+
+用户安装：
+
+1. 打开 DSH 右栏 → **Plugins** 页 → 安装 bundle，填包名 `dsh-links-panel`（或 `npm:...` / 本地目录）；
+2. 或者在某个 profile 目录里执行 `dsh plugin --profile desktop add dsh-links-panel`，再在 Plugins 页选中该 bundle；
+3. 重启后打开会话，右栏出现「应用链接 / Reference Links」tab。
+
+本地开发安装（当前仓库目录直接链接进 desktop profile）：
+
+```bash
+node references/scripts/install.mjs
+```

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# 以 bundle 形式把这个插件插进 profile 的 Loader 树：
+# 一条 insert 让 host 侧加载 lib/index.js、client 侧加载 lib/client.js。
+- insert:
+    - id: dsh-links
+      name: 'dsh-links-panel'

package/icon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 48 48">
+	<path d="M0 0h48v48H0z" fill="none" />
+	<path fill="#1976D2" d="M38 13h-3c-5.5 0-10 4.5-10 10s4.5 10 10 10h3c5.5 0 10-4.5 10-10s-4.5-10-10-10m0 16h-3c-3.3 0-6-2.7-6-6s2.7-6 6-6h3c3.3 0 6 2.7 6 6s-2.7 6-6 6M13 13h-3C4.5 13 0 17.5 0 23s4.5 10 10 10h3c5.5 0 10-4.5 10-10s-4.5-10-10-10m0 16h-3c-3.3 0-6-2.7-6-6s2.7-6 6-6h3c3.3 0 6 2.7 6 6s-2.7 6-6 6" />
+	<path fill="#42A5F5" d="M33 21H15c-1.1 0-2 .9-2 2s.9 2 2 2h18c1.1 0 2-.9 2-2s-.9-2-2-2" />
+</svg>