@sidequest-007/dsh-atlas 1.0.0

package/README.md

@@ -0,0 +1,297 @@
+# dsh-ATLAS
+
+**English** · [简体中文](README.zh.md)
+
+A **Side Quest** project (工作室：支线任务, **Side Quest Labs**) — npm scope `@sidequest-007/*`, repository [`jameswatt139240-crypto/dsh-ATLAS`](https://github.com/jameswatt139240-crypto/dsh-ATLAS); the DSH plugin id keeps the ecosystem's unscoped `dsh-*` form.
+
+<img src="assets/diagrams/atlas-overview.svg" alt="dsh-ATLAS: one @ trigger, five built-in categories, plus a category any plugin can register" width="880">
+
+**@ Last, All Sources.** One `@` . Any plugin can register.
+
+Unified `@` mentions for the DeepSeek Harness web GUI: type `@` in the composer to reference **workspace files and folders**, **discoverable skills**, **past chats**, and **installed plugins** — and any other plugin can add its own category to the same menu.
+
+- **One `@`, every source**: five built-in categories plus every registered provider, in one list; typing letters searches all of them at once.
+- **A platform, not a picker**: third-party plugins register their own `@` category through the `ctx.atlas` seam. The menu rebuilds from the live registry on every open, so **this package never has to change for a provider** — see [Write your own `@` source](#write-your-own--source).
+- **Provenance, never content**: a committed mention injects a marker (`<workspace-reference>`, `<skill-reference>`, `<atlas-reference>`, …) and nothing else. The plugin reads directory metadata only; the agent reads the file itself, if and when it needs to.
+- **Governed by construction**: `scopes` and `testedOn` are required, a duplicate `id` throws, a version mismatch registers as `verified: false`, and every provider body is budgeted (16 KiB per reference, 48 KiB per step).
+- **`@git` ships as the worked example**: a real provider, built the way a third party would build one, in ~200 lines across its two halves.
+
+<p align="center"><img src="assets/diagrams/atlas-seam.svg" alt="The @ data-source seam: browser half lists candidates, host half resolves one reference at send, and the registry gates the declaration" width="880"></p>
+
+It extends [`dsh-at-file`](https://github.com/FSMargoo/dsh-at-file) (MIT), keeping its workspace path index, file filters, and paste protection, and adding four more categories, a category menu with shortcuts, mixed results, collapsible groups, and three model-facing query tools.
+
+> `dsh-atlas` and `dsh-at-file` both claim the composer's `@` trigger. Install **one of them**, not both.
+
+## Install
+
+Requires a DSH install (`dsh` on `PATH`) with a web profile.
+
+```sh
+# from GitHub (this repository; lib/ is committed, so no build runs)
+dsh plugin --profile web add github:jameswatt139240-crypto/dsh-ATLAS
+
+# a local clone (development)
+git clone https://github.com/jameswatt139240-crypto/dsh-ATLAS
+dsh plugin --profile web add link:/path/to/dsh-ATLAS
+
+# npm (once published; the scope is the studio's, the plugin id stays `dsh-atlas`)
+dsh plugin --profile web add @sidequest-007/dsh-atlas
+```
+
+Restart `dsh web` after installing or updating so the Host and the browser client load the same version. Then type `@` in the composer.
+
+## The five categories
+
+The menu keeps five category rows in its **bottom band** — the rows nearest the composer — so pressing `@` opens on them rather than on whatever else shares the trigger.
+
+| Category | Menu prefix | Shortcut | Candidates from | Written into the draft |
+|---|---|---|---|---|
+| File | `file:` | `F` | The session workspace index | `@src/index.ts` |
+| Folder | `folder:` | `D` | Same index | `@src/client/` |
+| Skill | `skill:` | `S` | The `ctx.skills` registry | `@skill:blender-modeling` |
+| Past chat | `chat:` | `C` | The official session-reference resolver | `@[title](dsh-session:<id>)` |
+| Plugin | `plugin:` | `P` | The official plugin inventory | `@plugin:dsh-atlas` |
+
+**One shortcut letter is a statement of intent, not a query.** Typing it shows the five categories plus a `Tab 补全 → category:` hint as the **last** row, with the highlight already on that hint; <kbd>Tab</kbd> or <kbd>Enter</kbd> then enters the `category:` prefix. **A registered source can claim a shortcut letter too**: the first letter of its id (`@git` → <kbd>G</kbd>), and only while no built-in category or earlier provider answers to that letter (the `@<id>:` prefix always works). Filtering starts on anything more specific — a first letter that is not a shortcut, or a second character (which is what the `fi`/`fo`/`sk`/`ch`/`pl` spellings are). Clicking a category row or the back row enters/returns the same way and **keeps the menu open** — that is this plugin's own override; the normal pick path closes it.
+
+**Registered sources are the sixth row and beyond.** `@git` ships built in (the workspace's changed files, with each file's diff as the referenced content), and any plugin can add its own category the same way — see [Write your own `@` source](#write-your-own--source). They appear after the five, in registration order, and disappear when the plugin that registered them is disposed. The plugin's group itself is registered with a **positive order**, so it is the last group in the menu: the bottom band belongs to this plugin, and the stock `dsh-client-ui-reference` source's file list stays above it.
+
+## Interaction
+
+- **Typing letters** searches every category at once, split into a "recently referenced" section and an "all matches" section, with a category tag on each row; the category rows stay pinned and clickable.
+- **Folders**: the `@folder:` category lists directories; picking one writes `@path/` into the draft (the trailing slash is what marks a directory, and the plugin still reads directory metadata only). Keep typing after the slash to narrow the search inside it. While filtering, the rows are ranked in **two tiers**: folders whose NAME matches first — the workspace's own, then the ones outside it — and then, in a group of their own (`路径匹配`), the folders that only their PATH matches. Folding that group is your gesture; it opens by default and shows whatever fits.
+- **A folder you name first scopes the file list**: `@e:/work/docs/ @file:` lists **that folder's own files** (one level, through the same directory listing the folder tab uses) under a group header that says which folder they came from and that it is outside the workspace, before the workspace's own matches. The scope is positional — the nearest folder reference typed before the category token — so **no connective word is needed**, and a draft with no folder reference behaves exactly as before.
+- **Grouping**: skills group by management tier (系统 / 用户 / 项目 / 自定义 / 插件) and then by domain (blender, competition, dsh, …); plugins group by npm scope (`@deepseek-ai/…` or 其他); past chats group by workspace with the sidebar's relative times and children indented under their parent. Every parent row collapses or expands instantly on click, or on <kbd>Enter</kbd> while that group header is the highlighted row. <kbd>Tab</kbd> completion, <kbd>↑</kbd><kbd>↓</kbd>, and <kbd>Esc</kbd> are the harness's own keymap. Beyond those, the plugin adds exactly three keys of its own: <kbd>Enter</kbd> on a highlighted group header folds it, the category and back rows keep the menu open when picked, and <kbd>PageUp</kbd>/<kbd>PageDown</kbd> page the list by one measured screen — those two move the highlight (or scroll the list when the highlight belongs to another source), so the focused row is always the one you can see.
+- **Long lists scroll instead of hiding rows**: a category shows at most `MAX_CANDIDATES` (20) rows, and when they do not fit the menu scrolls — PageUp/PageDown walk it a screen at a time, and the plugin re-asserts the focused row's visibility whenever the content changes (a scoped folder's listing arriving late, a group being folded). Rows are therefore never dropped merely to keep the menu short; the tiers above decide what comes first.
+- **Initial view**: `@file:` lists recently referenced files first (most recent first, persisted per workspace), then alphabetical order.
+- **Cost and staleness**: each file reference in the dock shows its approximate token cost (`≈1.2k tokens`, highlighted above 8 000); a reference whose path no longer resolves is marked **Missing**. Cost comes from the file size (~4 bytes per token) and the plugin reads entry metadata only — **never file content**.
+- **Typo tolerance**: a lightly mistyped filename (`veiw` → `view.ts`, `clinet` → `client/…`) still matches. **Exact ranking wins**: the fuzzy pass only runs when the exact ranking found nothing, and queries shorter than three characters or containing `/` stay exact.
+- **Line ranges**: type `@src/a.ts:12-40` to reference lines 12–40 of that file (a single line is `@src/a.ts:7`; a reversed `40-12` is normalized to `12-40`). Directories take no range. The Host validates syntax and path kind only and **never opens the file**, so whether the lines exist is the agent's business when it reads.
+- **Reference dock**: every reference in the draft appears above the composer; file, folder and provider rows open on click, and each row's <kbd>×</kbd> removes its token.
+- **Every draft reference the plugin can open is a link**: the test is the PLUGIN's own — the token decodes into a reference and the Host has confirmed the target exists — not whether the framework happened to decorate it. A hand-typed `@AGENTS.md` behaves exactly like one the editor recognised: the whole token is blue, a click anywhere inside it opens the reference, and the pointer turns into a hand. The colour is painted with the CSS Custom Highlight API (a Lexical text span expects exactly one text child, so wrapping any part of a token would break typing inside it) in the very colour the framework uses for its own references. A token whose target is **gone** is not left as ordinary text either: it is painted the dock's own **Missing** way — dimmed and struck through — because it is a reference that cannot open. **When** that verdict is drawn matters: only a **finished** token is judged (one followed by whitespace, or by another line, i.e. after Enter), because a token still being typed is every prefix of a path at once and `@N` is always "missing" — striking it through mid-word would judge a word the user has not written yet. A token that CAN open turns blue the moment its name is complete, exactly as the framework's own decoration does. A token whose verdict has not arrived, whose provider declared no `open`, or whose name cannot be placed claims nothing and stays ordinary text. On a browser without the highlight API nothing is painted at all — there only the part the framework itself coloured acts as a link, because nothing else is drawn as one.
+- **A reference another source inserted as a chip is clickable too**: the sidebar's file tree writes one into the draft as an atomic chip, which this client build draws in the framework's chip blue and leaves inert. Clicking one opens the file it names, and the chip then carries the plugin's link language. That source labels a chip with the file's **basename** (the full relative path lives only in the draft text), so a bare name is placed in two steps: first the plugin's own index, where a unique basename settles it; then, when the index itself is ambiguous (`index.ts` exists twice in this workspace), the **draft** — one token with that basename decides, two leave the chip inert. Only a name the index does not know at all is handed to the click's own existence check, which marks the chip stale rather than opening something wrong.
+- **References in sent messages are clickable**: a chip in a message bubble opens on click (files in the right Sidebar, the Host opener when there is none; skills through the skill source; provider items through the `open` their own provider declared). Only a chip that really opens is drawn as a link — the framework's own `--dsw-alias-link` blue with a hover underline — and a build that wires the chips itself renders `<button>`, which this plugin leaves alone. The plugin also implements the framework's `openReference` hook, so a client that activates a reference token in the composer asks its owning source to open it. The installed client activates nothing yet, so the plugin supplies that click itself, through the very action the chips run.
+- **Icons**: every row this plugin emits carries **its own** glyph — the same modern line set the reference dock uses, including per-file-type and per-language marks (TypeScript, Rust, PDF, image, archive, …) and a branch glyph for `@git`. The framework's menu row can only draw three glyphs of its own, so the plugin reserves the slot (which is what indents every name by the same amount) and draws the glyph itself, monochrome, in a fixed layer above the list: nothing is inserted into a row the framework owns, and the framework's own glyph is hidden only in the slots this layer actually covers.
+
+![The @ menu](assets/screenshots/menu-mixed.png)
+
+*The menu (scrolled to its bottom band): a mixed, tagged result list — file rows with their directory, a collapsed plugin group — above the five category rows plus `@git`, each with the plugin's own glyph. The band is the last group, nearest the composer, and the menu is registered with a positive order so the stock reference source stays above it.*
+
+![Reference dock](assets/screenshots/file-mention-composer.png)
+
+*The reference dock above the composer: one row per mention in the draft, each with its own glyph, its approximate token cost (`≈26k tokens` in red is past the 8 000 highlight) and its remove button — and every token in the draft painted as a link.*
+
+## Injected references
+
+Before each agent step, the plugin validates every reference in the draft and appends one message carrying **only the reference** — never file content. The agent reads referenced content on demand with the tools available to the session.
+
+```text
+Review @docs/spec.pdf
+Use @skill:blender-modeling
+Recall @[Payment rates](dsh-session:xxx)
+With @plugin:dsh-atlas
+Take the diff of @atlas:git/src/extract.ts
+```
+
+| Category | Injected marker | Message source |
+|---|---|---|
+| File / Folder | `<workspace-reference path="docs/spec.pdf" kind="file" />` (adds `lines="12-40"` for a range) | `at-file-mention` |
+| Skill | `<skill-reference name="blender-modeling" />` | `atlas-skill` |
+| Plugin | `<plugin-reference name="dsh-atlas" />` | `atlas-plugin` |
+| Past chat | The official `session-reference` read-only snapshot (replayable, budgeted) | `session-reference` |
+| A registered `@` source | `<atlas-reference provider="git" item="src/a.ts" scopes="process:git" verified="true">…</atlas-reference>` | `atlas-provider` |
+
+- A referenced directory injects **that directory only**; its contents are never expanded here.
+- Absolute paths and paths escaping the workspace are ignored.
+- A referenced path must still exist; unknown or out-of-workspace tokens produce no marker.
+- Skill bodies are not injected by default (see `injectSkillBody`); the agent loads them through its skill tool.
+- Past-chat snapshots are budgeted by the official implementation (64 KB per source, at most 3 references, self-reference refused).
+- An `@atlas:` reference is the one marker that carries a body. That body is the provider's own answer, never a file this plugin opened: it is bounded to 16 KiB per reference and 48 KiB per step, and an over-long body is cut and marked `truncated="true"`.
+
+## Write your own `@` source
+
+The menu is the seam's only consumer. It rebuilds its category list from the live registry on every open, so a plugin adds a `@` category by registering one — nothing in this package enumerates providers, and no rebuild of it is needed.
+
+```ts
+// Host half — what a committed reference turns into. `ctx.get('atlas')` is the seam.
+import type { AtlasProvider, AtlasSeam } from '@sidequest-007/dsh-atlas'
+
+const provider: AtlasProvider = {
+  id: 'diag',                  // becomes @atlas:diag/… in the draft
+  display: 'Diagnostics',
+  scopes: ['process:lsp'],     // what you reach for (required)
+  testedOn: ['0.1.5-rc.1'],    // DSH builds you actually ran (required)
+  async resolve(item, context) {
+    // context.cwd is the answered session's workspace; context.sessionId names it.
+    return await diagnosticsFor(context.cwd, item.id, context.signal)
+  },
+}
+
+const atlas = ctx.get('atlas') as AtlasSeam
+atlas.register(provider)       // returns a disposer
+```
+
+```ts
+// Browser half — candidates for the open menu, from your own client bundle.
+const provider: AtlasProvider = {
+  id: 'diag',
+  display: 'Diagnostics',
+  scopes: ['process:lsp'],
+  testedOn: ['0.1.5-rc.1'],
+  async list(query, context) {
+    return await askYourHost(query, context.sessionId, context.signal)  // must stay cheap
+  },
+  open(item, context) {
+    // Optional: what a click on `@atlas:diag/…` in an ALREADY SENT message does.
+    // Only you know what your item means (a file path? a URL? a record id?), so
+    // the menu never interprets it — without `open`, the chip stays inert.
+    openInYourViewer(item)
+  },
+}
+```
+
+A provider may register either half or both; `id` ties them together. What the user commits is plain text (`@atlas:diag/src/a.ts:12`), so provider content never enters the draft, and only the Host half decides what the model sees.
+
+| Rule | Why |
+|---|---|
+| Registration *is* authorization | A plugin that never registers is invisible: nothing is scanned, guessed or discovered |
+| `list` runs while the menu is open | It decides how the menu feels; cache it yourself if it is not free |
+| `resolve` runs once, at send | It may be expensive, and it receives the session's `cwd` and an `AbortSignal` |
+| `open` is optional and menu-half only | The click happens in the browser; without it the chip is inert, and never drawn as clickable |
+| `scopes` and `testedOn` are required | `register()` refuses a declaration without them |
+| `testedOn` is compared for equality | A mismatch registers as `verified: false`; an unknown running version is *never* verified |
+| `id` is unique | A duplicate throws and names the first registrant — no silent overwrite |
+| The seam bounds every body | 16 KiB per reference, 48 KiB per step; the overflow is marked, not passed on |
+| An empty body injects nothing | A provider saying "nothing to add" costs no tokens |
+
+The verdict is re-read every time the registry is read, so a provider that registers before the browser has learned the running version does not stay unverified.
+
+### What ATLAS will not carry
+
+A source passes all three, or the answer is no:
+
+| Refuse | Why |
+|---|---|
+| **What the model can already get** | `@file` and `@session` are built in; a second route to the same data is noise |
+| **What cannot be narrowed** | A whole logcat or a full database dump poisons the context; a reference is a selection |
+| **What is expensive to `resolve`** | Lazy loading is the contract, not a preference |
+
+The test: **narrowable · previewable · useful the moment it lands.**
+
+`@git` is the worked example, and it is built the way a third party would build one. See `src/git.ts` (Host: reads the change list and produces one diff, never opening a file) and `src/client/git-provider.ts` (browser: asks the Host over `atlas/gitChanges`, filters per keystroke, caps the list).
+
+## Model-facing tools
+
+Beyond the markers injected at send time, the model can query these categories on demand:
+
+| Tool | Purpose |
+|---|---|
+| `past_chats` | List past sessions by title or workspace — follow-up to an `@past chat` reference |
+| `read_past_chat` | Read one referenced session's current user/assistant surface |
+| `plugin_info` | List installed plugins and whether each is enabled, filtered by module name |
+
+## Settings
+
+Managed in **Settings → Workspace file mentions**:
+
+| Setting | Default | Meaning |
+|---|---|---|
+| Enable @ file mentions | on | Master switch; turning it off hides the `@` menu and dock and stops injecting markers |
+| Enable @Skill mentions | on | Show skills in the menu |
+| Enable @past chats mentions | on | Show past sessions in the menu |
+| Enable @plugin mentions | on | Show installed plugins in the menu |
+| Candidate limit | 50 | Maximum candidates returned per request (1–200) |
+| Ignore @ mentions in pasted text | on | `@tokens` pasted from other applications stay plain text |
+| File filters | — | Global and per-workspace rules; each rule is Exact or Regex, with its own case setting |
+
+![File mention settings](assets/screenshots/file-mention-settings.png)
+
+File filters match **basenames only** (never directory paths). Workspace rules apply alongside global rules; editing rules clears the index cache, so the next `@` uses them.
+
+## Configuration
+
+These parameters live in the profile's `cordis.patch.yml` (usually `~/.dsh/profiles/web/cordis.patch.yml`):
+
+```yaml
+- id: dsh-atlas
+  config:
+    maxIndexedFiles: 2000   # workspace index entry cap
+    ignoreDirs: []          # replaces the built-in ignore list; [] indexes every directory
+    injectSkillBody: false  # also inject the skill body when a skill is referenced
+```
+
+Omitting `ignoreDirs` keeps the built-in list (version-control directories, IDE metadata, dependency directories, caches, and build output).
+
+## Design constraints
+
+- **Paths only, never content**: the Host validates and injects paths, categories, and provenance markers. It never opens a referenced file and never lists a referenced directory.
+- **Paste protection**: external text cannot forge a reference — only `source.kind === 'user'` messages are scanned, and pasted content is marked as plain text by default.
+- **Workspace confinement**: references stay inside the session workspace; absolute paths and `..` escapes are refused.
+- **Model-visible means logged**: every injected marker carries its source and is persisted with the session log.
+- **The display slot stays out of matching**: the display slot beside the `@` menu is fully decoupled from candidate computation. It never blocks or slows a search, and it reads no session data.
+
+## Development
+
+**Prerequisite**: the dev dependencies are `link:` entries into a DSH **source checkout**, expected at `../deepseek-harness` beside this repository. Without it `pnpm install` cannot resolve them, so a plain clone is not buildable on its own (the published packages — e.g. `@deepseek-ai/dsh-client-ui-conversation@0.1.6-alpha.1` — are on npm, but this setup is pinned to the checkout on purpose: it is how the plugin is tested against the same source the Harness is built from).
+
+```sh
+git clone https://github.com/jameswatt139240-crypto/dsh-ATLAS
+git clone <dsh source checkout> ../deepseek-harness   # or repoint the links in package.json
+cd dsh-ATLAS
+pnpm install
+pnpm run check           # typecheck + tests + ad-free build + publish-surface gate
+pnpm run build           # build only (no ad panel; lib/ is committed)
+pnpm run build:ads       # build the ad-bearing variant (not for the first release)
+pnpm run verify:publish  # publish-surface gate on its own
+```
+
+`lib/` is committed, so profile installs run without a build. See [CONTRIBUTING.md](CONTRIBUTING.md) for the ladder a change has to pass.
+
+### Publishing
+
+- **The default build carries no ad.** `pnpm run build` replaces the ad panel and its
+  banner images with stubs, so neither ad code nor image bytes reach `lib/client.js`
+  (~726 KB ad-free vs ~978 KB with ads). Use `pnpm run build:ads` for a later
+  ad-bearing release.
+- **The publish-surface gate** runs automatically before `npm publish`
+  (`prepublishOnly`) and refuses: the internal plan directory (kept out of git and
+  out of the tarball), AI-assistant files
+  (`AGENTS.md`, `CLAUDE.md`, `.agents/`, `.claude/`, `.cursor/`, `skills/`),
+  TypeScript sources and tests, sourcemaps (they inline sources and local paths),
+  a bundle that still inlines an ad banner, a bundle that leaks a local machine path,
+  and any of the four places that must agree on the package name
+  (`package.json`, `dsh.plugin.json`, `cordis.patch.yml`, the client bundle id, plus
+  the invariant companion). Set `DSH_ATLAS_ALLOW_ADS=1` for a deliberate ad release.
+- **Releasing**: the tag is the decision.
+
+  ```sh
+  pnpm run check                                  # full ladder, needs ../deepseek-harness
+  git tag -a v1.0.0 -m "dsh-ATLAS 1.0.0"
+  git push origin main --tags                     # the release workflow publishes
+  ```
+
+  `.github/workflows/publish-surface.yml` runs the self-contained gate on every push:
+  it needs no registry and no DSH checkout, because it packs the committed `lib/` and
+  inspects the tarball. `.github/workflows/release.yml` publishes on a `v*` tag with
+  **trusted publishing (OIDC)** — no `NPM_TOKEN`, no OTP: GitHub mints a short-lived
+  identity (`permissions: id-token: write`) and npm verifies it against the trusted
+  publisher configured for this package. That configuration is one-time, lives at
+  `https://www.npmjs.com/package/@sidequest-007/dsh-atlas/access` → *Trusted
+  Publisher* (user `jameswatt139240-crypto`, repository `dsh-ATLAS`, workflow filename
+  `release.yml`, "publish directly" allowed), and could only be added **after** the
+  first version existed — npm attaches a trusted publisher to a package, so 1.0.0
+  itself was published interactively. The job also skips itself when the tagged
+  version is already on npm, and runs `npm publish --ignore-scripts` (the full ladder
+  needs the DSH source checkout, which CI does not have). To publish by hand instead,
+  run `npm publish --registry https://registry.npmjs.org` (a mirror such as
+  `registry.npmmirror.com` cannot accept a publish).
+
+## Compatibility
+
+The plugin satisfies both generations of the Harness Typert codec validation (the installed build checks `codec.schema.parse`; the source checkout checks `codec.create()`), and opens referenced paths through `ctx.remote.session.openWorkspacePath`.
+
+## License
+
+**MIT** (see [LICENSE](LICENSE)) — use it, modify it, ship it, sell it; keep the copyright notice with the copies you distribute. It is an OSI-approved license, so plugin markets that require one are fine with it.
+
+This project is a derivative work of [`dsh-at-file`](https://github.com/FSMargoo/dsh-at-file) (MIT). Its original copyright notice and license text are preserved in [LICENSE-ORIGINAL](LICENSE-ORIGINAL), and [NOTICE](NOTICE) maps which files came from it.

package/README.zh.md

@@ -0,0 +1,289 @@
+# dsh-ATLAS
+
+[English](README.md) · **简体中文**
+
+本项目属于 **Side Quest（支线任务）** 工作室（**Side Quest Labs**）—— npm 范围 `@sidequest-007/*`，仓库 [`jameswatt139240-crypto/dsh-ATLAS`](https://github.com/jameswatt139240-crypto/dsh-ATLAS)；**DSH 插件 id 沿用生态惯例的无 scope 形式 `dsh-*`**。
+
+<img src="assets/diagrams/atlas-overview.svg" alt="dsh-ATLAS：一个 @ 触发位、五个内置类别，以及任何插件都能注册的自己的类别" width="880">
+
+**@ Last, All Sources.** 一个 `@` 。任何插件都能注册。
+
+DeepSeek Harness Web 界面的**统一 `@` 提及**插件：在输入框输入 `@`，即可引用工作区**文件与文件夹**、可发现的 **Skill**、**过去的聊天记录**、**已安装插件** —— 而且任何其它插件都能把自己的类别加进同一个菜单。
+
+- **一个 `@`，所有来源**：五个内置类别 + 所有已注册的数据源，同一个列表；输入字母即跨类别一起搜。
+- **是平台，不是取词器**：第三方插件通过 `ctx.atlas` seam 注册自己的 `@` 类别。菜单每次打开都从**实时注册表**重建，所以**本包永远不需要为某个 provider 改代码** —— 见 [自己接一个 `@` 数据源](#自己接一个--数据源)。
+- **只给来源，不给内容**：提交的引用只注入标记（`<workspace-reference>`、`<skill-reference>`、`<atlas-reference>` …）。插件只读目录项元数据；文件内容由 agent 在需要时自己去读。
+- **治理写在代码里**：`scopes` 与 `testedOn` 必填、`id` 重复直接抛错、版本不匹配注册为 `verified: false`、provider 正文有预算（单条 16 KiB、单步 48 KiB）。
+- **`@git` 就是范例**：一个真实 provider，完全按第三方的方式实现，两个半边加起来约 200 行。
+
+<p align="center"><img src="assets/diagrams/atlas-seam.svg" alt="@ 数据源 seam：浏览器半边在菜单打开时列候选，Host 半边在发送时解析一次，注册表负责门禁" width="880"></p>
+
+它基于 [`dsh-at-file`](https://github.com/FSMargoo/dsh-at-file)（MIT）扩展而来：保留原有的工作区路径索引、文件过滤规则与粘贴保护，并新增四个类别、类别菜单与快捷键、混合结果、分组折叠，以及三个模型侧查询工具。
+
+> `dsh-atlas` 与 `dsh-at-file` 都占用输入框的 `@` 触发位。请**二选一**，不要同时安装。
+
+## 安装
+
+前置：装好 DSH（`dsh` 在 `PATH` 上）并有一个 web profile。
+
+```sh
+# 从 GitHub 装（本仓库；lib/ 已随仓库提交，安装时不会触发构建）
+dsh plugin --profile web add github:jameswatt139240-crypto/dsh-ATLAS
+
+# 本地克隆（开发）
+git clone https://github.com/jameswatt139240-crypto/dsh-ATLAS
+dsh plugin --profile web add link:/path/to/dsh-ATLAS
+
+# npm 包（发布后；scope 是工作室的，插件 id 仍是 `dsh-atlas`）
+dsh plugin --profile web add @sidequest-007/dsh-atlas
+```
+
+安装或更新后**重启 `dsh web`**，确保 Host 与浏览器客户端都加载同一版本。然后在输入框打 `@`。
+
+## 五个类别
+
+输入 `@` 后，菜单顶部是五个常驻类别行；也可以直接输入关键字跨类别混合搜索。
+
+| 类别 | 菜单前缀 | 快捷键 | 候选来源 | 选中后写入草稿 |
+|---|---|---|---|---|
+| 文件 | `file:` | `F` | 当前会话工作区索引 | `@src/index.ts` |
+| 文件夹 | `folder:` | `D` | 同上 | `@src/client/` |
+| Skill | `skill:` | `S` | `ctx.skills` 技能注册表 | `@skill:blender-modeling` |
+| 过去的聊天 | `chat:` | `C` | 官方 session-reference 解析器 | `@[标题](dsh-session:<id>)` |
+| 插件 | `plugin:` | `P` | 官方 plugin inventory | `@plugin:dsh-atlas` |
+
+**单个快捷键字母是"意图"而不是"查询"**：输入它只显示五个类别 + 一行「Tab 补全 → `类别:`」提示，且这行提示在**最下面**（高亮也已经落在它上面），按 <kbd>Tab</kbd> 或 <kbd>Enter</kbd> 即进入对应的 `类别:` 前缀。**注册的数据源也能有快捷键字母**：取 provider id 的首字母（`@git` → <kbd>G</kbd>），只有在该字母没被内置类别或更早注册的 provider 占用时才生效（`@<id>:` 前缀永远可用）。**过滤从更具体的东西开始**：不是快捷键的首字母，或第二个字符（`fi`/`fo`/`sk`/`ch`/`pl` 这类前缀本来就是两个字符）。点击类别行或「返回类别」行同样进入/返回，且**菜单保持打开**（这是本插件的两处覆写：正常 pick 路径会关闭菜单）。
+
+**第六行起是"已注册数据源"。** `@git` 已内置（工作区的变更文件，引用内容就是该文件的 diff），任何插件都能用同样的方式加自己的类别——见[自己接一个 `@` 数据源](#自己接一个--数据源)。它们排在五个类别之后、按注册顺序出现，注册它们的插件被销毁时一起消失。插件自身的分组以**正的 `order`** 注册，因此它是菜单里的**最后一个分组**：底部那条工作带归本插件，框架自带 `dsh-client-ui-reference` 数据源的文件列表留在它上面。
+
+## 交互
+
+- **直接输入字母**：跨类别混合搜索，结果按「最近引用」与「全部匹配」两段展示，每行带类别标签；五个类别行始终在**最下面的工作带**里可点选。
+- **文件夹**：`@folder:` 类别列出目录，选中后写入 `@路径/`（末尾的 `/` 才是「目录」的标记，插件依然只读目录项元数据）；在斜杠后继续输入即可在该目录内收窄搜索。过滤时结果分**两档**排序：先按**名称**命中的文件夹（工作区内的在前，工作区外的在后），再是只有**路径**命中的那些，收进它们自己的 `路径匹配` 组。那一组默认展开、装得下就显示，折叠与否是你的手势。
+- **先写的文件夹会成为后面文件列表的作用域**：`@e:/work/docs/ @file:` 会先列出**该文件夹自己的文件**（一层，走的是文件夹 tab 同一套目录列表），组标题写明它来自哪个文件夹、并标明在工作区之外，然后才是工作区里的命中项。作用域是**位置**决定的——当前 token 之前最近的那个文件夹引用——所以**不需要连接词**；草稿里没有文件夹引用时行为与以前完全一致。
+- **分组折叠**：Skill 按管理层级（系统 / 用户 / 项目 / 自定义 / 插件）再按领域分组，插件按 npm scope（`@deepseek-ai/…` 或「其他」）分组，过去的聊天按工作区分组、子会话缩进在父会话下；组标题**点击即可折叠/展开；当高亮行正是该组标题时按 <kbd>Enter</kbd> 同样折叠/展开**。<kbd>Tab</kbd> 补全、<kbd>↑</kbd><kbd>↓</kbd>、<kbd>Esc</kbd> 全部由框架自己的 keymap 提供。除此之外插件只加三个键：高亮组标题上的 <kbd>Enter</kbd> 折叠、类别行/返回行选中后保持菜单打开、以及 <kbd>PageUp</kbd>/<kbd>PageDown</kbd> 按**实测一屏**翻页——翻页移动的是高亮（高亮属于别的数据源时就只滚列表），所以"看得见的那一行"永远是你正在操作的那一行。
+- **列表长了就滚动，不再靠隐藏行数**：单个类别最多 `MAX_CANDIDATES`（20）行，装不下就由菜单滚动——<kbd>PageUp</kbd>/<kbd>PageDown</kbd> 一屏一屏走，且内容变化时（作用域目录列表后到、某组被折叠）插件会把焦点行重新拉回可视区。也就是说**不会为了菜单短一点而丢行**；谁排在前面由上面的分档决定。
+- **相对时间**：历史会话与工作区行显示「刚刚 / 5分钟 / 3小时 / 2天」等相对时间。
+- **初始视图**：`@file:` 先列出最近引用过的文件（最近的在前，按工作区持久化），其后按字母序。
+- **引用成本与失效提示**：引用栏里的每个文件引用会显示约 token 成本（如 `≈1.2k tokens`；超过 8000 token 时高亮）；若引用的路径在工作区内已不存在，会标出「已失效」。成本取自文件大小（约 4 字节 / token），插件只读目录项元数据，**不读取文件内容**。
+- **错字容错**：文件名的轻微拼写错误（如 `veiw` → `view.ts`、`clinet` → `client/…`）仍能命中。**精确匹配优先**——只要精确排序有结果，就不会混入模糊结果；长度小于 3 或含 `/` 的查询保持精确。
+- **行范围引用**：直接手打 `@src/a.ts:12-40` 即可引用该文件的第 12–40 行（单行写 `@src/a.ts:7`；倒序 `40-12` 会自动归一为 `12-40`）。目录不接受行范围。Host 只校验语法与路径类型，**不会打开文件**，因此行号是否越界由 agent 读取时判断。
+- **引用栏**：输入框上方按顺序显示当前草稿里的每个引用；文件、文件夹与 provider 行可点击打开，每行的 <kbd>×</kbd> 移除对应 token。
+- **草稿里任何能打开的 `@路径` 都是链接**：判断依据是**插件自己**——token 能解码成引用、并且宿主确认该目标存在——而不是框架有没有把它装饰成引用。所以手打的 `@AGENTS.md` 和框架认出来的 token 一样：**整条**变蓝、点任意位置都打开、鼠标变手型。上色用 CSS Custom Highlight API 逐段绘制（Lexical 的文本 span 只允许一个文本子节点，包裹尾巴会破坏输入），颜色取框架给引用用的同一个变量。**目标已不存在**的 token 也不会被当成普通文本，而是按引用栏那套「已失效」语言画成**暗色 + 删除线**——它是引用，只是打不开。**判定时机**：只有**写完的 token** 才会被判失效（后面跟着空白，或后面还有下一行＝按过回车）；正在输入的 token 不下结论——`@N` 这种中间态必然"不存在"，边打边画删除线等于替用户还没写完的词下判决。**能打开**的 token 则在名字写成的那一刻就变蓝（与框架自己的引用装饰一样即时）。引用栏还没回答、provider 没声明 `open`、或名字放不下的 token 什么都不说、保持普通文本。浏览器不支持 highlight API 时什么都不绘制，此时**只有框架自己上过色的那部分**可点（没画成链接就不表现得像链接）。
+- **草稿里由其它数据源插入的 chip 也能点**：右侧栏的文件树就是往草稿里插一条原子 chip，这个客户端把它画成框架自己的 chip 蓝、并且不接任何点击。点它即打开它命名的文件，随后 chip 会带上插件的链接语言。那个数据源给 chip 的标签是**文件名**（完整相对路径只存在于草稿文本里），所以裸文件名按两步还原：①在插件索引里找同名 basename，唯一命中即用；②索引里就有歧义（例如 `index.ts` 在工作区里有两处）时回退到**草稿**——草稿里只有一个同名 token 就用它，仍有两个则**保持不可点**。索引完全不认识的名字才原样交给点击时的存在性检查（结果是标「已失效」，而不是打开一个错的目标）。
+- **已发送消息里的引用可点**：消息气泡里的引用 chip 点击即打开（文件进右侧栏，无右栏时交宿主打开器；Skill 交给 Skill 源；provider item 交给它自己声明的 `open`）。只有真的能打开的 chip 会被画成链接（用框架自己的 `--dsw-alias-link` 蓝 + 悬停下划线），框架自己接好点击的版本会渲染 `<button>`，本插件自动让位。插件同时实现了框架的 `openReference` 钩子：客户端在草稿里激活一个引用 token 时，由拥有它的 source 打开。安装版客户端还没有接上这一步，因此这个点击同样由插件补上，走的是 chip 用的那同一个动作。
+- **图标**：本插件发出的每一行都带**自己的**图标——与引用栏同一套现代线稿，含按文件类型与语言的标记（TypeScript、Rust、PDF、图片、压缩包…），`@git` 用分支图标。框架的菜单行只会画它自己的三种字形，所以插件**预定那个图标槽**（这决定了所有名字缩进一致），再由自己在列表上方的一层固定层里、用单色线条画出图标：不往框架拥有的行里插任何东西，框架自己的字形也只在被这一层真正覆盖的槽里隐藏。
+
+![@ 菜单](assets/screenshots/menu-mixed.png)
+
+*菜单（滚到最底部的工作带）：上面是带类别标签的混合结果列表——文件行带所在目录、还有折叠的插件分组——最下面是五个类别加 `@git`，每行都是插件自己画的图标。工作带是最后一组、离输入框最近；本插件的分组用正序注册，所以框架自带的数据源仍在它上方。*
+
+![引用栏](assets/screenshots/file-mention-composer.png)
+
+*输入框上方的引用栏：草稿里每个引用一行，各带自己的图标、≈token 成本（红色的 `≈26k tokens` 是超过 8 000 的高亮）与移除按钮——草稿里的每个 token 同时都被画成链接。*
+
+## 注入语义
+
+每次 agent 开始处理前，插件会校验草稿中的每个引用，并追加一条**只含引用信息、不含文件内容**的消息。文件内容始终由 agent 使用当前会话的工具按需读取。
+
+```text
+看下 @docs/spec.pdf
+用 @skill:blender-modeling
+回忆 @[付款费率](dsh-session:xxx)
+配合 @plugin:dsh-atlas
+取出 @atlas:git/src/extract.ts 的 diff
+```
+
+| 类别 | 注入的标记 | 消息来源 |
+|---|---|---|
+| 文件 / 文件夹 | `<workspace-reference path="docs/spec.pdf" kind="file" />`（带行范围时追加 `lines="12-40"`） | `at-file-mention` |
+| Skill | `<skill-reference name="blender-modeling" />` | `atlas-skill` |
+| 插件 | `<plugin-reference name="dsh-atlas" />` | `atlas-plugin` |
+| 过去的聊天 | 官方 `session-reference` 只读快照（可回放、带预算） | `session-reference` |
+| 已注册的 `@` 数据源 | `<atlas-reference provider="git" item="src/a.ts" scopes="process:git" verified="true">…</atlas-reference>` | `atlas-provider` |
+
+- 引用目录时**只注入该目录**，不展开其中的内容；需要时由 agent 自行列出。
+- 绝对路径与越出工作区的路径会被忽略。
+- 引用的文件必须仍然存在；不存在或越界的 token 不会产生标记。
+- Skill 正文默认不注入（见 `injectSkillBody`），由 agent 的技能工具按需加载。
+- 历史会话快照由官方实现负责预算与上限（单源 64 KB、最多 3 个、拒绝自引用）。
+- `@atlas:` 是唯一带正文的标记。正文完全来自 provider 自己的回答，不是本插件打开的任何文件：单条上限 16 KiB、单步合计 48 KiB，超长部分被截断并标记 `truncated="true"`。
+
+## 自己接一个 `@` 数据源
+
+菜单是这个 seam 唯一的消费方。它每次打开都从实时注册表重建类别行，所以插件只要注册一条声明就多出一个 `@` 类别——本包里没有任何 provider 清单，也不需要重新构建它。
+
+```ts
+// Host 半边：已提交的引用最终变成什么。`ctx.get('atlas')` 就是 seam。
+import type { AtlasProvider, AtlasSeam } from '@sidequest-007/dsh-atlas'
+
+const provider: AtlasProvider = {
+  id: 'diag',                  // 草稿里就是 @atlas:diag/…
+  display: 'Diagnostics',
+  scopes: ['process:lsp'],     // 你会碰什么（必填）
+  testedOn: ['0.1.5-rc.1'],    // 你真正跑过的 DSH 版本（必填）
+  async resolve(item, context) {
+    // context.cwd 是被回答会话的工作区；context.sessionId 是它的身份。
+    return await diagnosticsFor(context.cwd, item.id, context.signal)
+  },
+}
+
+const atlas = ctx.get('atlas') as AtlasSeam
+atlas.register(provider)       // 返回一个 disposer
+```
+
+```ts
+// 浏览器半边：菜单打开时的候选，来自你自己的客户端 bundle。
+const provider: AtlasProvider = {
+  id: 'diag',
+  display: 'Diagnostics',
+  scopes: ['process:lsp'],
+  testedOn: ['0.1.5-rc.1'],
+  async list(query, context) {
+    return await askYourHost(query, context.sessionId, context.signal)  // 必须便宜
+  },
+  open(item, context) {
+    // 可选：用户在**已发送**的消息里点 `@atlas:diag/…` 时做什么。
+    // 你的 item 是什么意思只有你知道（文件路径？URL？记录 id？），
+    // 所以菜单永远不会替你解释它——没写 open，那颗 chip 保持不可点。
+    openInYourViewer(item)
+  },
+}
+```
+
+一个 provider 可以只注册其中半边，也可以两半都注册，`id` 把两半绑在一起。用户提交进草稿的是纯文本（`@atlas:diag/src/a.ts:12`），所以 provider 的内容永远不会进入草稿；模型看到什么，只由 Host 半边的 `resolve` 决定。
+
+| 规则 | 原因 |
+|---|---|
+| 注册**就是**授权 | 没注册的插件在这里不可见：不扫描、不猜测、不发现 |
+| `list` 在菜单打开期间跑 | 它决定手感；不便宜就自己缓存 |
+| `resolve` 每次发送只跑一次 | 可以贵，并且会拿到会话的 `cwd` 与 `AbortSignal` |
+| `open` 可选，且只属于菜单半边 | 点的动作发生在浏览器里；没声明 `open` 的 provider，chip 不可点（也不会画成可点） |
+| `scopes` 与 `testedOn` 必填 | 缺少任一项，`register()` 直接拒绝 |
+| `testedOn` 按相等比较 | 不匹配则以 `verified: false` 注册；运行版本未知时**永远**不算已验证 |
+| `id` 唯一 | 重复会抛错并指名先注册者，不静默覆盖 |
+| 正文由 seam 统一限量 | 单条 16 KiB、单步 48 KiB；超出部分被标记，不会被放行 |
+| 空正文不注入任何东西 | provider 说"没什么可加"就不该花 token |
+
+版本裁决在每次读注册表时重新判定，所以"比浏览器拿到运行版本更早注册"的 provider 不会永久停留在未验证。
+
+### 三类不接
+
+三条全中才接，否则不接：
+
+| 不接 | 理由 |
+|---|---|
+| **模型自己能拿到的** | `@file` / `@session` 官方已内置；同一份数据的第二条路只是噪音 |
+| **不可窄选的** | 全量 logcat 或整个数据库 dump 会污染上下文；引用必须是一次选择 |
+| **`resolve` 贵的** | 懒加载是契约，不是偏好 |
+
+判定标准：**可窄选 · 可预览 · 注入即有用。**
+
+`@git` 就是照这个标准写出来的范例，且完全按第三方的方式实现：`src/git.ts`（Host：读变更列表、产出单个文件的 diff，全程不打开任何文件）与 `src/client/git-provider.ts`（浏览器：通过 `atlas/gitChanges` 向 Host 要数据，逐键筛选、限量）。
+
+## 模型侧工具
+
+除了发送时注入的标记，模型还可以在需要时主动查询这些类别：
+
+| 工具 | 用途 |
+|---|---|
+| `past_chats` | 按标题或工作区列出历史会话，用于 `@过去的聊天` 之后的追问 |
+| `read_past_chat` | 读取某个已引用会话的当前用户/助手消息面 |
+| `plugin_info` | 列出已安装插件及其启用状态，可按模块名过滤 |
+
+## 设置
+
+在 **设置 → 工作区文件提及** 中管理：
+
+| 设置项 | 默认 | 说明 |
+|---|---|---|
+| 启用 @ 文件提及 | 开 | 总开关；关闭后隐藏 `@` 菜单与引用栏，并停止注入标记 |
+| 启用 @Skill 提及 | 开 | 是否在菜单中显示 Skill |
+| 启用 @过去的聊天 提及 | 开 | 是否在菜单中显示历史会话 |
+| 启用 @插件 提及 | 开 | 是否在菜单中显示已安装插件 |
+| 候选数量上限 | 50 | 每次请求返回的候选条目上限（1–200） |
+| 忽略粘贴文本中的 @ | 开 | 从其他应用粘贴的 `@内容` 保持普通文本，不触发引用 |
+| 文件过滤 | — | 全局与工作区两套规则；每条可选 Exact / Regex 与是否区分大小写 |
+
+![文件提及设置](assets/screenshots/file-mention-settings.png)
+
+文件过滤只匹配**文件名**（不含目录路径）。工作区规则与全局规则同时生效；修改规则会清除索引缓存，下一次输入 `@` 即生效。
+
+## 配置
+
+以下参数在所选 profile 的 `cordis.patch.yml` 中配置（常用路径 `~/.dsh/profiles/web/cordis.patch.yml`）：
+
+```yaml
+- id: dsh-atlas
+  config:
+    maxIndexedFiles: 2000   # 工作区索引条目上限
+    ignoreDirs: []          # 替换内置忽略目录列表；留空数组表示索引所有目录
+    injectSkillBody: false  # 引用 Skill 时是否连同正文一起注入
+```
+
+`ignoreDirs` 省略时使用内置列表（版本控制目录、IDE 元数据、依赖目录、缓存与构建产物等）。
+
+## 设计约束
+
+- **只传路径，不读内容**：Host 端只校验并注入路径、类别与来源标记，从不打开引用的文件，也从不列出目录内容。
+- **粘贴保护**：外部文本无法伪造引用——只有 `source.kind === 'user'` 的消息才会被扫描，且粘贴内容默认被标记为普通文本。
+- **工作区边界**：引用被限制在当前会话的工作区内；绝对路径与 `..` 逃逸会被拒绝。
+- **模型可见即可回放**：注入的标记都带来源，随会话日志持久化。
+- **展示位不参与匹配**：`@` 菜单旁的展示位与候选计算完全解耦，不会阻塞或影响搜索；它不读取任何会话数据。
+
+## 开发
+
+**前置条件**：devDependencies 是指向 DSH **源码检出**的 `link:` 条目，默认期望在本仓库同级目录 `../deepseek-harness`。没有它 `pnpm install` 无法解析依赖，因此**单纯 clone 本仓库不能直接构建**（这些包在 npm 上也有，例如 `@deepseek-ai/dsh-client-ui-conversation@0.1.6-alpha.1`；这里刻意指向检出，是为了让插件始终对着与 Harness 构建同源的代码做测试）。
+
+```sh
+git clone https://github.com/jameswatt139240-crypto/dsh-ATLAS
+git clone <DSH 源码检出> ../deepseek-harness   # 或者改 package.json 里的 link 指向你的路径
+cd dsh-ATLAS
+pnpm install
+pnpm run check           # typecheck + 测试 + 无广告构建 + 发布面门禁
+pnpm run build           # 仅构建（默认不含广告面板）
+pnpm run build:ads       # 构建含广告面板的版本（不用于首次发布）
+pnpm run verify:publish  # 单独运行发布面门禁
+```
+
+`lib/` 中的构建产物会提交到仓库，因此从 profile 安装时不需要执行构建脚本。改动需要过的检查见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+### 发布
+
+- **默认构建不含广告**：`pnpm run build` 会把广告面板与横幅图片一并替换为桩，因此
+  `lib/client.js` 里既没有广告代码也没有图片字节（无广告约 726 KB，含广告约 978 KB）。
+  后续要出带广告的版本，使用 `pnpm run build:ads`。
+- **发布面门禁**在 `npm publish` 前自动运行（`prepublishOnly`），拒绝以下内容进入 npm 包：
+  内部计划目录（既不进 git 也不进 tarball）、AI 助手说明文件（`AGENTS.md`、`CLAUDE.md`、`.agents/`、`.claude/`、
+  `.cursor/`、`skills/`）、TypeScript 源码与测试、sourcemap（内联源码与本机路径）、
+  仍然内联广告图的构建产物、泄漏本机路径的产物，以及**四处包名不一致**
+  （`package.json`、`dsh.plugin.json`、`cordis.patch.yml`、客户端 bundle id，外加 invariant 伴生包）。
+  确需发布广告版本时设置 `DSH_ATLAS_ALLOW_ADS=1`。
+- **发版**：tag 就是发布决定。
+
+  ```sh
+  pnpm run check                                  # 完整梯子，需要 ../deepseek-harness
+  git tag -a v1.0.0 -m "dsh-ATLAS 1.0.0"
+  git push origin main --tags                     # release workflow 自动发布
+  ```
+
+  `.github/workflows/publish-surface.yml` 在每次 push 上跑**自足**门禁（不需要 registry、也不需要 DSH 检出，
+  它只是把已提交的 `lib/` 打成 tarball 再检查）；`.github/workflows/release.yml` 在 `v*` tag 上用
+  **可信发布（OIDC / Trusted Publishing）**：**既不要 `NPM_TOKEN` 也不要 OTP** —— GitHub 用
+  `permissions: id-token: write` 签发一次性身份，npm 按该包配置的 trusted publisher 校验后授权发布。
+  这项配置是一次性的，位置在 `https://www.npmjs.com/package/@sidequest-007/dsh-atlas/access` →
+  *Trusted Publisher*（user `jameswatt139240-crypto`、repository `dsh-ATLAS`、workflow 文件名 `release.yml`、
+  勾选"允许直接 publish"），而且**只能在包已存在之后添加** —— trusted publisher 是挂在包上的，所以 1.0.0 本身
+  是交互式发布的。该 job 还会在"该版本已在 npm 上"时自动跳过，并以 `--ignore-scripts` 发布（完整梯子依赖
+  DSH 源码检出，CI 里没有）。若要手动发布：`npm publish --registry https://registry.npmjs.org`
+  （镜像如 `registry.npmmirror.com` 不能接收发布）。
+
+## 兼容性
+
+插件同时兼容两代 Harness 的 Typert codec 校验（安装版校验 `codec.schema.parse`，源码检出校验 `codec.create()`），并在运行时通过 `ctx.remote.session.openWorkspacePath` 打开引用路径。
+
+## License
+
+**MIT**（见 [LICENSE](LICENSE)）——随便用、改、发、卖，只要在你分发出去的副本里保留版权声明。它也是 OSI 认可的开源许可，要求开源许可的插件市场不会卡它。
+
+本项目是 [`dsh-at-file`](https://github.com/FSMargoo/dsh-at-file)（MIT）的衍生作品：上游的版权声明与许可原文保留在 [LICENSE-ORIGINAL](LICENSE-ORIGINAL)，哪些文件来自上游见 [NOTICE](NOTICE)。