dsh-reference-anything 0.2.5 → 0.3.1

package/NOTICE.md

@@ -17,38 +17,9 @@ the MIT License. The adapted source paths are:
 OpenCLI is not redistributed by this package. It is an external runtime
 dependency licensed under Apache-2.0.
 
-## dsh-at-file
+## DeepSeek Harness reference services
 
-Portions of the workspace file/folder autocomplete, path ranking, and
-existence-only reference implementation are adapted from `dsh-at-file`:
-
-- Upstream repository: https://github.com/omdsh-dev/dsh-at-file
-- Upstream revision: `898369ece56ae6ec41afd8e014f187bb5b723409`
-- Upstream license: MIT
-
-Copyright (c) 2026 dsh-at-file contributors
-
-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.
-
-## DeepSeek Harness session reference
-
-Cross-session candidate listing, canonical `dsh-session:` references, and
-immutable snapshot preparation use the official DeepSeek Harness package
-`@deepseek-ai/dsh-session-reference`. That package remains an external/package
-dependency and is used under the DeepSeek Harness project's MIT license.
+File candidate formatting and cross-session candidate types use the official
+DeepSeek Harness packages `@deepseek-ai/dsh-file-reference` and
+`@deepseek-ai/dsh-session-reference`. Those packages remain external package
+dependencies and are used under the DeepSeek Harness project's MIT license.

package/README.md

@@ -6,19 +6,20 @@
 
 <h1>dsh-reference-anything</h1>
 
-One `@` to reference them all.
+One `@` for them all.
 
-**English** · [简体中文](./README_zh-CN.md) · [News](#news) · [Roadmap](#roadmap) · [Installation](#installation) · [Usage](#usage) · [Report Bug][github-issues-link]
+**English** · [简体中文](./README_zh-CN.md) · [📰 News](#-news) · [🧭 Roadmap](#-roadmap) · [📦 Installation](#-installation) · [🚀 Usage](#-usage) · [🐛 Report Bug][github-issues-link]
 
 <!-- SHIELD GROUP -->
 
-[![][github-version-shield]][github-releases-link]
+[![][github-version-shield]][github-version-link]
 [![][typescript-shield]][typescript-link]
 [![][dsh-plugin-shield]][repository-link]<br/>
 [![][github-stars-shield]][github-stars-link]
 [![][github-forks-shield]][github-forks-link]
 [![][github-issues-shield]][github-issues-link]
-[![][github-license-shield]][github-license-link]
+[![][github-license-shield]][github-license-link]<br/>
+![awesome · DSH plugin](https://awesome-dsh-plugin.com/badge.svg)
 
 </div>
 
@@ -28,30 +29,64 @@ One `@` to reference them all.
 
 </div>
 
-Within a unified `@` menu of DeepSeek Harness (DSH), reference commands, Skills, workspace files/folders, DSH sessions, and historical conversations from ChatGPT, Claude, Gemini, DeepSeek, Grok, and Kimi.
+**Reference Anything is an enhancement for the DeepSeek Harness (DSH) `@` menu.** It brings multiple reference sources into one searchable menu, so you can mention the context you need without switching tools or copying content manually.
+
+After typing `@`, you can browse and click items in the menu with your mouse, or use the keyboard to enter text, search, and narrow down the results.
+
+Use one `@` menu to reference:
+
+- DSH commands and Skills
+- Workspace files and folders
+- DSH session history
+- Historical conversations from ChatGPT, Claude, Gemini, DeepSeek, Grok, and Kimi
+
+Beyond extending what `@` can reference, Reference Anything also enhances the `@` menu itself:
+
+- Customize visible groups: enable or hide `Commands`, `Skills`, files, DSH sessions, and external conversations, then arrange them in any order
+- Customize result counts: set each group's collapsed row count and hard candidate cap independently
+- Choose how to browse: expand or collapse individual groups, or use DSH's native scrolling list
+- Enhanced visual icons: distinguish reference sources with type icons and platform logos, making menu items easier to identify
+
+<table>
+  <tr>
+    <th width="50%">Native DSH display</th>
+    <th width="50%">Reference Anything icon enhancements</th>
+  </tr>
+  <tr>
+    <td width="50%"><img src="./images/at-files-native-comparison.png" alt="Native DSH file list" width="100%" /></td>
+    <td width="50%"><img src="./images/at-files-enhanced-comparison.png" alt="Reference Anything file-type icon enhancements" width="100%" /></td>
+  </tr>
+</table>
+
+Type `@`, search across enabled sources, and insert the selected reference into the current task. Each source keeps its own access and loading behavior: files use DSH's permission-constrained tools, DSH sessions use the native session-reference protocol, and external conversation bodies are read on demand.
 
 This plugin uses OpenCLI to access historical conversations through AI chat sessions that are already logged in. By default, only conversation titles are stored locally, and the agent fetches remote content on demand. An optional offline-mirror mode stores the latest complete conversation bodies locally.
 
+> [!IMPORTANT]
+> This version targets DSH `0.1.0-rc.8` or newer. It uses the native `@` trigger menu, official file/session Remotes, and the native Composer reference renderer.
+
 > [!NOTE]
 > DSH is currently in Beta, so its underlying capabilities and interfaces may change as it evolves. This plugin will adapt alongside those changes. Because of some current DSH limitations, parts of the implementation may not yet be ideal; we will continue to follow DSH updates and improve the plugin over time. See the relevant sections below for specific limitations and usage notes.
 
-## News
+## 📰 News
 
+- **2026-08-20 · v0.3.0** — Completed the native DSH `@` integration: five independently configurable sources, official file/session Remotes, native Composer references with source logos, in-place expand/collapse and sync actions, and a one-click switch between Reference Anything and the official DSH `@` list. The legacy `dsh-file:` protocol and custom Composer interaction layer were removed.
 - **2026-08-19 · v0.2.4** — Added automatic version checks and in-settings updates, Pill/Raw text input rendering modes, and reusable background browser sessions for more reliable OpenCLI synchronization and input interactions.
 - **2026-08-18 · v0.2.0** — A redesigned Reference Anything settings page with local session statistics, paginated management, Provider/Profile selection, and sync status checks.
 - **2026-08-18** — Introduced on-demand read protocol: references default to safe pointers, and the agent reads the body and attachments only after authorization.
 - **2026-08-17** — Unified ChatGPT, Claude, Gemini, DeepSeek, Grok, and Kimi under the DSH `@` menu.
 
-## Roadmap
+## 🧭 Roadmap
 
-- [ ] Support referencing historical conversations from other local agents
+- [ ] Support referencing historical conversations from other local agents (in progress)
+- [ ] Support referencing files from cloud drives and performing operations on them (in progress)
 - [ ] Support more keyword matching rules, including blacklists and whitelists, especially for file search
 - [ ] Support more AI conversation platforms
 - [ ] Provide a quieter AI conversation synchronization mechanism
 - [ ] Support referencing applications or browser windows currently open on the computer
 - [ ] More ideas are welcome in Issues
 
-## Installation
+## 📦 Installation
 
 Prerequisites:
 
@@ -83,60 +118,57 @@ opencli daemon restart
 
 Replace `C:/path/to/dsh-reference-anything` with the repository location. Browser extensions cannot be silently installed from a webpage; confirm the installation in the Chrome Web Store, or download an extension package from [OpenCLI Releases](https://github.com/jackwener/opencli/releases) and use “Load unpacked.” If the browser blocks the store popup, the settings page keeps a normal fallback link. When multiple browser profiles are connected, select and apply one directly in the failed check. Global npm installation remains subject to OS permissions; failures retain their original diagnostic in the settings page.
 
-## Usage
+## 🚀 Usage
+
+Reference Anything registers five sources in the native DSH `@` menu rather than introducing a separate search interface. Settings let you choose which groups appear, their order, their collapsed row count, their hard candidate cap, and whether groups use plugin-owned collapse actions or the native scrolling list. A separate one-click control switches the visible picker back to DSH's official file/session list without stopping the plugin, synchronization service, local data, or model-facing tools; the same control restores the Reference Anything picker at any time.
 
 1. Open `Settings → Reference Anything` in DSH Web.
 2. Under **Availability check**, confirm that OpenCLI, Browser Bridge, the browser extension, and the conversation adapter are ready.
 3. Under **External conversation sync settings**, choose a connected browser Profile, history storage mode, and sync mode. Then click **Sync enabled sources now**, or sync an individual Provider from its card.
-4. Type `@` in the input box and choose from the `Files and folders`, `DSH sessions`, or `External conversations` groups.
+4. Type `@` in the input box and choose from the `Commands`, `Skills`, `Files and folders`, `DSH sessions`, or `External conversations` groups.
 5. Type a keyword to filter candidates, for example `@cache-design`.
 
-The default **Read bodies on demand** mode stores only the title index locally and uses the browser when an agent reads a reference. Choose **Store full bodies locally** for offline reading and full-text search; this mode keeps only the latest version of each conversation. The settings page also lets you enable or disable each `@` group, reorder groups, set their maximum result counts (six per group by default), and switch between Pill and Raw text input rendering. The plugin checks npm for updates when it loads; restart DSH after installing an update from the settings page.
+The default **Read bodies on demand** mode stores only the title index locally and uses the browser when an agent calls `reference_read`. Choose **Store full bodies locally** for offline reading and full-text search; this mode keeps only the latest version of each conversation. The Composer uses native DSH reference occurrences for files, DSH sessions, and external conversations; Reference Anything adds source-specific logos without replacing native wrapping, caret, selection, deletion, draft, clipboard, or serialization behavior. The plugin checks npm for updates when it loads; restart DSH after installing an update from the settings page.
 
 > [!WARNING]
-> To protect your account and conversation data, external conversations are imported and synchronized through OpenCLI using your existing logged-in browser session. A browser window may temporarily open during use or synchronization, and it may display OpenCLI debugging information. This is expected—please do not be alarmed or close the window manually; wait for the operation to finish.
+> To protect your account and conversation data, external conversations are imported and synchronized through OpenCLI using your existing logged-in browser session. A browser window may temporarily open during use or synchronization. In most cases, leave it open in the background: the plugin will reuse it without interrupting your work. The window may also display OpenCLI debugging information. This is expected—please do not be alarmed or close it manually; wait for the operation to finish. Due to current OpenCLI limitations, we temporarily use slower serial synchronization to reduce how often browser windows open. Once the upstream OpenCLI repository is updated, we will switch to faster parallel synchronization.
 
-### Search
+### 🧩 One `@` menu, multiple sources
 
-The `@` menu contains five groups: `Commands`, `Skills`, `Files and folders`, `DSH sessions`, and `External conversations`. The first two appear only when `@` is at the beginning of the draft. Each group shows up to six results by default. Under `Settings → Reference Anything → General`, you can enable or disable groups, reorder them, and set each limit from 1 to 50.
+The `@` menu contains five groups: `Commands`, `Skills`, `Files and folders`, `DSH sessions`, and `External conversations`. Each group shows six rows before its expand action by default and accepts a separate hard candidate cap from 1 to 50. In collapse mode, each expand action reveals five more rows and updates the mounted menu without jumping back to the top; collapse restores the configured compact count. The external-conversation group keeps its sync action first and updates that row and the visible results in place while synchronization runs and completes. Under `Settings → Reference Anything → General`, you can enable or disable groups, reorder them, and choose **Collapse / expand** or **Native DSH scrolling**.
 
-#### @Commands — DSH native commands
+#### ⌨️ @Commands — DSH native commands
 
-Available only at the start of the draft. To browse all commands, use `@commands` or the native DSH `/` panel.
+To browse commands, use `@commands`; selecting one hands `/command` back to DSH's native slash pipeline.
 
 <p align="center"><img src="./images/at-commands.png" alt="Browse DSH commands from the @ menu" width="800" /></p>
 
-#### @Skills — DSH skill library
+#### 🛠️ @Skills — DSH skill library
 
-Available only at the start of the draft. To browse all skills, use `@skills:` or the native DSH `/` panel.
+To browse skills, use `@skills:`; selecting one inserts `/skill` for DSH's native skill handling.
 
 <p align="center"><img src="./images/at-skills.png" alt="Browse DSH skills from the @ menu" width="800" /></p>
 
-#### @Files and folders — workspace files and directories
+#### 📁 @Files and folders — workspace files and directories
 
-Type `@files:` in the input box to browse all files and folders in the workspace. Search supports fuzzy matching on titles, so both `@cachedes` and `@cache-design` can match “Cache design notes.”
+Type `@files:` in the input box to browse files and folders through DSH's official file-reference Remote.
 
 <p align="center"><img src="./images/at-files.png" alt="Browse workspace files and folders from the @ menu" width="800" /></p>
 
-Features:
-- Quick reference to workspace files with automatic workspace-boundary validation
-- File references only write a validated path and type marker into the model context; file content is not preloaded
-- If the model needs file content, it must use the existing permission-constrained file tools
+**Features:**
+- Uses the official `@path` / `@"path with spaces"` grammar and canonical file candidate service
+- Files become native atomic references; selecting a directory keeps the path editable and continues completion
+- The plugin no longer creates or parses a custom `dsh-file:` scheme
 
-#### @DSH sessions — DSH session history
+#### 💬 @DSH sessions — DSH session history
 
-Type `@sessions:` to browse locally synced DSH sessions. Sessions are ranked by match quality, with recency as fallback ordering.
+Type `@sessions:` to browse DSH sessions through the official session-reference Remote.
 
 <p align="center"><img src="./images/at-sessions.png" alt="Browse DSH sessions from the @ menu" width="800" /></p>
 
-Search capabilities:
-- **Title match:** fuzzy search on session titles
-- **Content search:** when title matches are insufficient, the synced session body is searched; matching excerpts are shown in the candidate row for UI display only and are not injected into model context
-- Auto-generated generic titles such as “New chat” can also be found via body keywords
+Selected sessions use DSH's canonical `dsh-session:` mention and native session appearance. Snapshot preparation and resolution remain owned by DSH rather than this plugin.
 
-Full browsing is available on the settings page’s paginated list. Session references follow the official `dsh-session:` protocol and immutable snapshot semantics.
-
-#### @External conversations — external conversation platforms
+#### 🌐 @External conversations — external conversation platforms
 
 Supports historical conversations from ChatGPT, Claude, Gemini, DeepSeek, Grok, and Kimi.
 
@@ -153,24 +185,21 @@ Supports historical conversations from ChatGPT, Claude, Gemini, DeepSeek, Grok,
 - **Provider and account isolation:** history is maintained separately by Provider and account scope
 - `@` search uses the account scope cached by the latest sync and never probes the browser; after a sync observes an account switch, it exposes only that account while older rows remain available in conversation management for cleanup
 
-**Reference display:** after selection, the draft shows a removable reference chip:
+**Reference display:** after selection, the draft shows a native removable DSH reference with the Provider logo. Its stable serialized form is:
 ```text
-@[ChatGPT · Conversation title](dsh-ref:<opaque-base64url>)
+@[ChatGPT·Conversation title](dsh-ref:<opaque-base64url>)
 ```
 
 Opening the source URL happens only in the UI; the URL is never injected into model context. The initial reference contains only a safe pointer; if the model needs the body, it calls `reference_read` on demand.
 
-> [!NOTE]
-> Due to DSH's current underlying length limit for References, external-conversation references temporarily use a compatibility layer implemented by this plugin instead of relying entirely on DSH's native reference presentation. As a result, some interactions may behave differently or encounter issues in certain scenarios. We have raised this limitation in DSH Discussions; when a future DSH release provides the necessary support, we will update the plugin promptly and migrate to a more native implementation.
-
 ---
 
 **General notes:**
 - Use `:` or `/` as the separator instead of a space: the `@` candidate token ends at a space, so `@chatgpt keyword` closes the menu as soon as you press the space. For multi-word searches, write `@cachedesign` or `@cache-design`.
 - Without a type prefix, all groups are searched at once.
-- For full browsing across groups: sessions are listed on the settings page, while commands and skills use the native `/` panel.
+- Commands and Skills are handed back to DSH's native slash-command handling after selection; the native `/` panel remains available.
 
-## How External Conversation References Work
+## 🔄 How External Conversation References Work
 
 ```text
 DSH Web @Conversations
@@ -184,7 +213,7 @@ ChatGPT / Claude / Gemini / DeepSeek / Grok / Kimi
 
 This does not include the legacy standalone DeepSeek CDP / `--remote-debugging-port` collector. All six platforms use the OpenCLI Provider adapter path, avoiding duplicate browser-reading implementations.
 
-### Model-facing Protocol
+### 🤖 Model-facing Protocol
 
 A reference produces an untrusted-data envelope alongside the current user request. The initial envelope contains only pointers and never the conversation body:
 
@@ -220,7 +249,7 @@ A reference produces an untrusted-data envelope alongside the current user reque
 - Sync stores attachment metadata and same-origin locators, not temporary signed URLs. Attachments are classified as `image` or `file`; empty URLs and site-root paths are not marked as available.
 - Unreadable attachments add a model-facing notice such as `[User attached 1 image; image contents were not included]` without altering the original conversation text.
 
-### Sync and Storage
+### 💾 Sync and Storage
 
 The `reference_anything` storage domain contains:
 
@@ -234,12 +263,12 @@ Remote records are marked `remoteMissing` only after a full remote pagination pa
 
 In `metadata-only` mode, the current browser account is checked inside the same detail operation that reads a referenced body; reads are rejected when it does not match the account scope cached by sync. Conversation management includes bulk actions for records marked `remoteMissing` and for local chats owned by non-current accounts of providers whose current account is known.
 
-## Acknowledgements
+## 🙏 Acknowledgements
 
-- Workspace file/folder autocomplete, path ordering, and existence-only reference handling include portions adapted from [omdsh-dev/dsh-at-file](https://github.com/omdsh-dev/dsh-at-file).
-- Cross-session DSH candidates, canonical `dsh-session:` references, and immutable snapshot support use the official `@deepseek-ai/dsh-session-reference` package.
+- File candidates and mention formatting use the official `@deepseek-ai/dsh-file-reference` package and DSH Remote.
+- Cross-session candidates and canonical `dsh-session:` mentions use the official `@deepseek-ai/dsh-session-reference` package and DSH Remote.
 
-## Sources and License
+## 📄 Sources and License
 
 This project is licensed under the [MIT License](./LICENSE). Third-party copyright notices, license texts, porting sources, and pinned upstream commits are documented in [NOTICE.md](./NOTICE.md). OpenCLI is an external Apache-2.0 dependency and is not bundled with this plugin.
 
@@ -249,8 +278,8 @@ This project is licensed under the [MIT License](./LICENSE). Third-party copyrig
 [typescript-link]: https://www.typescriptlang.org/
 [typescript-shield]: https://img.shields.io/badge/TypeScript-3178C6?labelColor=black&logo=typescript&logoColor=white&style=flat-square
 [dsh-plugin-shield]: https://img.shields.io/badge/DSH-plugin-ffffff?labelColor=black&style=flat-square
-[github-version-shield]: https://img.shields.io/github/package-json/v/Chael-Chael/dsh-reference-anything?color=369eff&label=version&labelColor=black&style=flat-square
-[github-releases-link]: https://github.com/Chael-Chael/dsh-reference-anything/releases
+[github-version-shield]: https://img.shields.io/github/package-json/v/Chael-Chael/dsh-reference-anything/main?color=369eff&label=version&labelColor=black&style=flat-square
+[github-version-link]: https://github.com/Chael-Chael/dsh-reference-anything/blob/main/package.json
 [github-stars-link]: https://github.com/Chael-Chael/dsh-reference-anything/stargazers
 [github-stars-shield]: https://img.shields.io/github/stars/Chael-Chael/dsh-reference-anything?color=ffcb47&labelColor=black&style=flat-square
 [github-forks-link]: https://github.com/Chael-Chael/dsh-reference-anything/forks

package/cordis.patch.yml

@@ -1,31 +1,29 @@
 # dsh-reference-anything — the layer this bundle contributes.
 #
 # A patch REPLACES a row's whole `config` rather than merging keys, so when you
-# override one of these in your profile's cordis.patch.yml, restate every key
-# the row needs.
-- insert:
-    # The harness's own cross-session resolver. It ships with dsh but no shipped
-    # composition mounts it, so `dsh-session:` mentions resolve to nothing until
-    # something does. Mounting it here is what makes the mention expander below
-    # able to serve both schemes.
-    - id: session-reference
-      name: '@deepseek-ai/dsh-session-reference'
-
-    # The registry every source registers into.
+# override one of these in your profile's cordis.patch.yml, restate every key
+# the row needs.
+- id: ui-reference
+  # Reference Anything re-registers Files and DSH sessions as two independent
+  # sources over the same official Remotes.  Disabling only this Client source
+  # keeps the official file/session services and canonical mention semantics.
+  disabled: true
+
+- insert:
+    # The registry every source registers into.
     - id: references
       name: 'dsh-reference-anything'
       config:
         listLimit: 20
 
-    # Expands `@[label](dsh-ref:…)` and `dsh-session:` mentions in a user's
-    # prompt into untrusted background, on every surface. It grants the agent
-    # the exact reference URI but does not fetch a transcript; the agent calls
-    # reference_read only when the current task needs one.
-    - id: reference-mention
-      name: 'dsh-reference-anything/reference'
-      config:
-        maxReferences: 3
-        serveSessionScheme: true
+    # Expands plugin-owned `@[label](dsh-ref:…)` mentions into untrusted
+    # metadata on every surface. Native file and `dsh-session:` references stay
+    # with DSH's official services. External transcripts are not prefetched;
+    # the agent calls reference_read only when the current task needs one.
+    - id: reference-mention
+      name: 'dsh-reference-anything/reference'
+      config:
+        maxReferences: 3
 
     # Lets the model go looking on its own, and page backwards through a
     # conversation it has only seen the end of.