dsh-market-watching 0.1.0 → 0.2.2

package/README.en.md

@@ -3,6 +3,8 @@
 A market card for the DSH sidebar: crypto, A-shares / HK / US equities, global indices, CME futures continuous contracts, FX and spot metals — live prices, daily change, plus position P&L against your own cost basis. Pick the symbols, their order and the refresh cadence in **DSH Settings**. **No login, no API key.** The UI copy follows the DSH interface language (English / Chinese).
 
 <p align="center">
+  <img src="icon.svg" alt="dsh-market-watching" width="72" height="72">
+  <br>
   <a href="README.md"><img src="docs/badges/lang-zh-switch.svg" alt="简体中文" height="20"></a>
   &nbsp;
   <img src="docs/badges/lang-en-current.svg" alt="English" height="20">
@@ -65,29 +67,23 @@ All of these are public quote endpoints — no account, no token, no auth. Every
 
 ## Install
 
-The plugin is wired in through the profile, in two edits:
+Use the DSH plugin command. It forwards its arguments verbatim to pnpm inside the profile directory, so one line does the whole install.
 
-1. Add to `dependencies` in `%USERPROFILE%\.dsh\profiles\desktop\package.json`:
+Desktop (`desktop` profile):
 
-   ```json
-   "dsh-market-watching": "file:E:/LLm/Project/dsh-market-watching"
-   ```
+```powershell
+dsh plugin --profile desktop add dsh-market-watching
+```
 
-2. Append to the `dsh.profile.bundles` array in the same `package.json`:
+Web (`web` profile):
 
-   ```json
-   "dsh-market-watching"
-   ```
+```powershell
+dsh plugin --profile web add dsh-market-watching
+```
 
-3. Link the package into the profile's `node_modules` (a Windows junction is enough):
+Restart the process afterwards: close and reopen the DeepSeek Harness desktop app (the host half `index.js` is only assembled at process start), or restart `dsh web` for the web profile. The client half `client.js` is injected when the page loads, so a refresh picks it up.
 
-   ```powershell
-   New-Item -ItemType Junction `
-     -Path "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-market-watching" `
-     -Target "E:\LLm\Project\dsh-market-watching"
-   ```
 
-4. **Restart the DeepSeek Harness desktop app.** The host half (`index.js`) is only assembled at process start; the client half (`client.js`) is injected when the page loads.
 
 ## Usage
 
@@ -142,12 +138,15 @@ The `config` block in `cordis.patch.yml` overrides these defaults (a profile pat
 | `/api/market.ticker` | GET / POST | Quote snapshot for the current watchlist; `?refresh=1` bypasses the cache |
 | `/api/market.settings` | GET / POST | Read and write settings |
 | `/api/market.resolve` | POST | Code resolution and validation (returns candidates and official names) |
+| `/api/market.notice` | GET / POST | Whether the thank-you card is due (GET) and what the operator chose (POST `thanks` / `issue` / `later`) |
 
 Settings persist to `$DSH_HOME/dsh-market-watching.json` (default `%USERPROFILE%\.dsh\dsh-market-watching.json`). The plugin used to be called `dsh-plugin-market-ticker`; its old file `dsh-market-ticker.json` is adopted automatically on first start and left in place.
 
+The card keeps its own counter in `$DSH_HOME/dsh-market-watching.notice.json` rather than inside the settings document: settings are normalized on every read and write, so an unknown field would be dropped the moment the watchlist is saved.
+
 ## How it works
 
-- **Host side** (`index.js`): `inject = ['connection']`, and `ctx.connection.fetch.register` installs three exact routes. Inside, instruments are grouped by market: equities / indices / FX merge into one East Money `ulist` batch (40 secids per batch), crypto goes to Gate pair by pair, spot metals merge into one Sina batch. A `cacheMs` cache and `inflight` de-duplication sit in front, and when every upstream fails the response is `degraded: true` with the previous quotes from `lastGood` (`stale: true`), so the card never goes blank. Position maths runs on the host: `positionPnl(entry, price)` yields the percentage (long `(price - cost) / cost`, inverted for shorts) and `positionAmount(entry, qty, price)` yields the cash amount (price delta × quantity, inverted for shorts), shipped as `pnlPercent` / `pnlAmount`; the client only renders them. Error responses carry a `code` (`badJson` / `writeFailed` / `unknownCode` / `noQuote`) next to `message`, so the client can re-render the text in the current language.
+- **Host side** (`index.js`): `inject = ['connection']`, and `ctx.connection.fetch.register` installs four exact routes. Inside, instruments are grouped by market: equities / indices / FX merge into one East Money `ulist` batch (40 secids per batch), crypto goes to Gate pair by pair, spot metals merge into one Sina batch. A `cacheMs` cache and `inflight` de-duplication sit in front, and when every upstream fails the response is `degraded: true` with the previous quotes from `lastGood` (`stale: true`), so the card never goes blank. Position maths runs on the host: `positionPnl(entry, price)` yields the percentage (long `(price - cost) / cost`, inverted for shorts) and `positionAmount(entry, qty, price)` yields the cash amount (price delta × quantity, inverted for shorts), shipped as `pnlPercent` / `pnlAmount`; the client only renders them. Error responses carry a `code` (`badJson` / `writeFailed` / `unknownCode` / `noQuote`) next to `message`, so the client can re-render the text in the current language.
 - **Client side** (`client.js`): `inject = ['slots', 'locale']`, registering `sidebar.footer.action` (the card), `settings.section` (the settings page) and `settings.section.icon` (the nav icon). Styling uses `--dsw-alias-*` theme tokens only, so it follows light and dark themes.
 
 ## Language
@@ -175,7 +174,7 @@ node scripts/probe-ticker.mjs # hit the ticker route once, print real quotes and
 
 ## Troubleshooting
 
-- **No card in the sidebar**: first check whether the master switch in settings is off; then that at least one instrument exists; then that `%USERPROFILE%\.dsh\profiles\desktop\node_modules\dsh-market-watching` exists as a junction pointing at the source directory; finally restart the desktop app.
+- **No card in the sidebar**: first check whether the master switch in settings is off; then that at least one instrument exists; then that the package is installed in the current profile (`dsh plugin --profile desktop why dsh-market-watching`); finally restart the process.
 - **Card shows `--`**: upstreams are unreachable. Check that the machine can reach `push2.eastmoney.com`, `api.gateio.ws` and `hq.sinajs.cn` directly; behind a proxy, put the proxy address in `config.proxy` (the Sina path then uses the same client, so if it is blocked, drop the proxy or go direct).
 - **A symbol is rejected**: the host could not get a quote for that code. Try another form (market prefix for A-shares, a full secid for indices).
 - **All copy is English**: interface language follows DSH — switch it to Chinese in DSH's own language setting. Takes effect immediately, no restart.
@@ -183,7 +182,11 @@ node scripts/probe-ticker.mjs # hit the ticker route once, print real quotes and
 
 ## Uninstall
 
-Remove the two edits from the profile `package.json`, delete the junction, restart the desktop app. The settings file `%USERPROFILE%\.dsh\dsh-market-watching.json` can go too.
+```powershell
+dsh plugin --profile desktop remove dsh-market-watching
+```
+
+For the web profile, swap `--profile desktop` for `--profile web`. Restart the process afterwards. The settings file `%USERPROFILE%\.dsh\dsh-market-watching.json` can stay (it is reused on reinstall) or be deleted.
 
 ## License
 

package/README.md

@@ -3,6 +3,8 @@
 DSH 侧栏行情卡片：加密货币、A股 / 港股 / 美股、国际指数、CME 期货连续合约、外汇、现货金银，实时价格与涨跌幅一览，还能按自己填的成本价算持仓盈亏。标的、顺序、刷新节奏全在 **DSH 设置页**里定，**无需登录、无需 API Key**，界面文案跟随 DSH 的界面语言（中文 / 英文）。
 
 <p align="center">
+  <img src="icon.svg" alt="dsh-market-watching" width="72" height="72">
+  <br>
   <img src="docs/badges/lang-zh-current.svg" alt="简体中文" height="20">
   &nbsp;
   <a href="README.en.md"><img src="docs/badges/lang-en-switch.svg" alt="English" height="20"></a>
@@ -78,29 +80,21 @@ English:
 
 ## 安装
 
-插件通过 profile 装配，两步：
+用 DSH 自带的插件命令，一条就够——它把参数原样转发给 profile 目录里的 pnpm。
 
-1. 在 `%USERPROFILE%\.dsh\profiles\desktop\package.json` 的 `dependencies` 增加：
+桌面版（`desktop` profile）：
 
-   ```json
-   "dsh-market-watching": "file:E:/LLm/Project/dsh-market-watching"
-   ```
-
-2. 同一个 `package.json` 的 `dsh.profile.bundles` 数组末尾增加：
-
-   ```json
-   "dsh-market-watching"
-   ```
+```powershell
+dsh plugin --profile desktop add dsh-market-watching
+```
 
-3. 在 profile 目录下建立包链接（Windows 用 junction 即可）：
+Web 版（`web` profile）：
 
-   ```powershell
-   New-Item -ItemType Junction `
-     -Path "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-market-watching" `
-     -Target "E:\LLm\Project\dsh-market-watching"
-   ```
+```powershell
+dsh plugin --profile web add dsh-market-watching
+```
 
-4. **重启 DeepSeek Harness 桌面应用**。宿主插件（`index.js`）只在进程启动时装配；客户端 `client.js` 由页面加载时注入。
+装完重启对应进程才算数：桌面版关掉重开 DeepSeek Harness（宿主 `index.js` 只在进程启动时装配），Web 版重启 `dsh web`。客户端 `client.js` 是页面加载时注入的，刷新一次就换。
 
 ## 使用
 
@@ -155,12 +149,15 @@ English:
 | `/api/market.ticker` | GET / POST | 当前标的的报价快照；`?refresh=1` 强制绕过缓存 |
 | `/api/market.settings` | GET / POST | 读写设置 |
 | `/api/market.resolve` | POST | 代码解析与校验（返回候选与官方名称） |
+| `/api/market.notice` | GET / POST | 是否该弹出道谢卡片（GET），以及记录用户的选择（POST `thanks` / `issue` / `later`） |
 
 设置落盘在 `$DSH_HOME/dsh-market-watching.json`（默认 `%USERPROFILE%\.dsh\dsh-market-watching.json`）。插件改名前叫 `dsh-plugin-market-ticker`，旧文件 `dsh-market-ticker.json` 会在首次启动时被自动接管，原文件保留不删。
 
+道谢卡片的计数单独落在 `$DSH_HOME/dsh-market-watching.notice.json`，不写进设置文件：设置每次读写都会被规范化，未知字段留不住，用户一存自选就会把计数洗掉。
+
 ## 工作方式
 
-- **宿主侧**（`index.js`）：`inject = ['connection']`，用 `ctx.connection.fetch.register` 注册三条精确路由。内部把标的按市场分组，股票/指数/外汇合并成一次东财 `ulist` 批量请求（每批 40 个 secid），加密逐个走 Gate，现货金属合并成一次新浪批次请求。带 `cacheMs` 缓存与 `inflight` 去重，上游整体失败时返回 `degraded: true` 并沿用 `lastGood` 里的上一次报价（`stale: true`），不会把卡片打空。持仓盈亏由宿主算：`positionPnl(entry, price)` 出百分比（多头 `(现价-成本)/成本`，空头取反），`positionAmount(entry, qty, price)` 出金额（价格差 × 数量，空头取反），分别以 `pnlPercent` / `pnlAmount` 下发，客户端只负责显示。错误响应除 `message` 外还带 `code`（`badJson` / `writeFailed` / `unknownCode` / `noQuote`），供客户端按当前语言重新渲染。
+- **宿主侧**（`index.js`）：`inject = ['connection']`，用 `ctx.connection.fetch.register` 注册四条精确路由。内部把标的按市场分组，股票/指数/外汇合并成一次东财 `ulist` 批量请求（每批 40 个 secid），加密逐个走 Gate，现货金属合并成一次新浪批次请求。带 `cacheMs` 缓存与 `inflight` 去重，上游整体失败时返回 `degraded: true` 并沿用 `lastGood` 里的上一次报价（`stale: true`），不会把卡片打空。持仓盈亏由宿主算：`positionPnl(entry, price)` 出百分比（多头 `(现价-成本)/成本`，空头取反），`positionAmount(entry, qty, price)` 出金额（价格差 × 数量，空头取反），分别以 `pnlPercent` / `pnlAmount` 下发，客户端只负责显示。错误响应除 `message` 外还带 `code`（`badJson` / `writeFailed` / `unknownCode` / `noQuote`），供客户端按当前语言重新渲染。
 - **客户端侧**（`client.js`）：`inject = ['slots', 'locale']`，注册 `sidebar.footer.action`（卡片）、`settings.section`（设置页）、`settings.section.icon`（导航图标）。样式只用 `--dsw-alias-*` 主题 token，跟随深浅色主题。
 
 ## 语言
@@ -188,7 +185,7 @@ node scripts/probe-ticker.mjs # 打一次 ticker 路由，打印真实报价与
 
 ## 故障排查
 
-- **侧栏没有卡片**：先看设置里的总开关是不是被关了；再确认至少有一个标的；再确认 `%USERPROFILE%\.dsh\profiles\desktop\node_modules\dsh-market-watching` 这个 junction 存在且指向源码目录；最后重启桌面应用。
+- **侧栏没有卡片**：先看设置里的总开关是不是被关了；再确认至少有一个标的；再确认包装进了当前 profile（`dsh plugin --profile desktop why dsh-market-watching`）；最后重启对应进程。
 - **卡片显示 `--`**：上游不通。检查网络能否直连 `push2.eastmoney.com`、`api.gateio.ws` 与 `hq.sinajs.cn`；若走代理，在 `config.proxy` 填上代理地址（新浪那一路在配置代理后也走同一客户端，若被拦就把代理关掉或改用直连）。
 - **添加标的被拒**：说明宿主用报价接口探测不到该代码，换个写法（A 股带市场前缀、指数写完整 secid）。
 - **文案全是英文**：界面语言跟着 DSH 走，去 DSH 自己的语言设置里切成中文即可，改完即时生效，不用重启。
@@ -196,7 +193,11 @@ node scripts/probe-ticker.mjs # 打一次 ticker 路由，打印真实报价与
 
 ## 卸载
 
-删掉 profile `package.json` 里加的两处、删除 junction、重启桌面应用。设置文件 `%USERPROFILE%\.dsh\dsh-market-watching.json` 可一并删除。
+```powershell
+dsh plugin --profile desktop remove dsh-market-watching
+```
+
+Web 版就把 `--profile desktop` 换成 `--profile web`。卸完重启对应进程。设置文件 `%USERPROFILE%\.dsh\dsh-market-watching.json` 可以留着（重装后接着用），也可以直接删。
 
 ## License
 

package/client.js

@@ -27,6 +27,9 @@ window.__ModuleLoader__.load({
     const SETTINGS_ENDPOINT = '/api/market.settings'
     const RESOLVE_ENDPOINT = '/api/market.resolve'
 
+    /** Route that decides whether the post-install thank-you card is due. */
+    const NOTICE_ENDPOINT = '/api/market.notice'
+
     /** Slot ids, spelled exactly as the UI packages declare them. */
     const SIDEBAR_SLOT = 'sidebar.footer.action'
     const SETTINGS_SLOT = 'settings.section'
@@ -35,6 +38,22 @@ window.__ModuleLoader__.load({
     const CARD_ID = 'market-watching'
     const SETTINGS_ID = 'market-watching-settings'
     const STYLE_ID = 'dsh-market-watching-style'
+    const THANKS_ID = 'market-watching-thanks'
+
+    /** Where a reader can complain about a price or ask for a market. */
+    const REPO_URL = 'https://github.com/Leni-More/dsh-market-watching'
+    const ISSUES_URL = `${REPO_URL}/issues`
+
+    /**
+     * The card waits for the shell to settle before it appears: long enough that
+     * it never races the sidebar's first paint, short enough to still feel like
+     * a greeting rather than a delayed pop-up.
+     */
+    const THANKS_DELAY_MS = 2400
+
+    /** While the operator is typing, the card keeps its distance and tries again. */
+    const THANKS_IDLE_MS = 800
+    const THANKS_IDLE_TRIES = 12
 
     /** Locale namespace this plugin owns; `apply` registers the dictionaries below. */
     const LOCALE_NAMESPACE = 'marketTicker'
@@ -80,7 +99,7 @@ window.__ModuleLoader__.load({
         'page.subtitle': '侧边栏底部显示的价格、涨跌幅与盈亏。标的、顺序与刷新间隔都在这里决定，改动立即生效。',
         'page.loading': '正在读取自选列表…',
         'page.failed': '读取自选列表失败，请重开设置页。',
-        'page.footer': '数据来自东方财富与 Gate.io 的公开接口，无需账号与密钥；网络不通时卡片保留上一次报价并淡化显示。',
+        'page.footer': '数据来自东方财富与 Gate.io 的公开接口，无需账号与密钥；不同平台可能存在一定价差，可以根据实际的价差来调整成本价。',
         'panel.master': '总开关',
         'panel.masterHint': '关闭后侧边栏不再显示卡片，也不再请求行情',
         'panel.add': '添加标的',
@@ -135,6 +154,14 @@ window.__ModuleLoader__.load({
         'error.unknownCode': '认不出这个代码，换成 600519 / hk00700 / AAPL / USTEC / EURUSD / XAUUSD / BTC 试试。',
         'error.noQuote': '上游这会儿没有这个标的的报价。',
         'hint.setPriceFirst': '先在输入框填成本价，再点确定，然后就能切换买入/做空',
+        'thanks.title': '谢谢你把它留在侧边栏',
+        'thanks.body': '很开心它可以帮上你。功能优化，或者你想增加新的标的，可以随时提出来。要是它确实帮上了忙，去仓库点个 Star 就是最好的谢礼。',
+        'thanks.wish': '祝你持仓大赚，住上大平层，开上帕拉梅拉，享受苹果人生。',
+        'thanks.star': '点个 Star',
+        'thanks.ack': '知道了',
+        'thanks.close': '关闭',
+        'thanks.note': '有更好的建议？',
+        'thanks.repo': '去提一条',
       },
       en: {
         'market.crypto': 'Crypto',
@@ -168,7 +195,7 @@ window.__ModuleLoader__.load({
         'page.subtitle': 'Price, change and P&L at the bottom of the sidebar. Symbols, order and refresh rate are all decided here, and every change applies at once.',
         'page.loading': 'Reading the watchlist…',
         'page.failed': 'Could not read the watchlist. Reopen Settings.',
-        'page.footer': 'Quotes come from the public East Money and Gate.io endpoints — no account, no API key. When a network call fails the card keeps the last quote and fades it.',
+        'page.footer': 'The data comes from the public endpoints of East Money and Gate.io, with no account or API key required. Price differences may exist across platforms, so the cost price can be adjusted based on the actual price difference.',
         'panel.master': 'Master switch',
         'panel.masterHint': 'When off the sidebar card disappears and no quotes are fetched',
         'panel.add': 'Add a symbol',
@@ -223,6 +250,14 @@ window.__ModuleLoader__.load({
         'error.unknownCode': 'Unrecognised code. Try 600519 / hk00700 / AAPL / USTEC / EURUSD / XAUUSD / BTC.',
         'error.noQuote': 'The upstream has no quote for this symbol right now.',
         'hint.setPriceFirst': 'Type a cost and press Save first, then the long/short switch works',
+        'thanks.title': 'Thank you for keeping it in the sidebar',
+        'thanks.body': 'Glad it could help. If you’d like feature improvements or want to add new tickers, feel free to reach out anytime. If it really did help, dropping a Star on the repo is the best thank-you.',
+        'thanks.wish': 'Wishing you big gains on your holdings, a fancy penthouse, a Panamera, and the Apple life.',
+        'thanks.star': 'Drop a Star',
+        'thanks.ack': 'Got it',
+        'thanks.close': 'Close',
+        'thanks.note': 'Any better suggestions?',
+        'thanks.repo': 'Open an issue',
       },
     }
 
@@ -485,6 +520,17 @@ window.__ModuleLoader__.load({
   letter-spacing: 0.02em;
 }
 
+/* Brand mark: gives the card a face of its own before the title, and stays put when the
+   rail collapses the header to bare numbers and strips the written title away. */
+.dmt-brand {
+  display: inline-flex;
+  align-items: center;
+  flex: none;
+  color: #22c55e;
+}
+
+.dmt-brand > svg { display: block; }
+
 .dmt-mark {
   display: inline-block;
   width: 5px;
@@ -890,6 +936,162 @@ window.__ModuleLoader__.load({
 
 .dmt-toggle[data-on="1"] { background: var(--dsw-alias-brand-primary, #4d7cfe); border-color: transparent; }
 .dmt-toggle[data-on="1"]::after { transform: translateX(18px); background: #fff; }
+
+/* ------------------------------------------------------------------ *
+ * thank-you card
+ * ------------------------------------------------------------------ */
+
+.dmt-thanks-layer {
+  position: fixed;
+  inset: 0;
+  z-index: 200;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 20px;
+  background: rgba(16, 16, 20, 0.4);
+  animation: dmt-thanks-fade 200ms ease-out;
+}
+
+.dmt-thanks {
+  position: relative;
+  box-sizing: border-box;
+  width: min(384px, 100%);
+  padding: 24px 24px 18px;
+  border: 1px solid var(--dsw-alias-border-l1, rgba(128, 128, 128, 0.22));
+  border-radius: 14px;
+  background: var(--dsw-alias-bg-layer-2, #1c1c20);
+  color: var(--dsw-alias-label-primary, #f2f2f5);
+  box-shadow: 0 20px 52px rgba(0, 0, 0, 0.32);
+  font-size: 13px;
+  line-height: 1.62;
+  animation: dmt-thanks-rise 240ms cubic-bezier(0.2, 0.7, 0.3, 1);
+}
+
+.dmt-thanks:focus { outline: none; }
+
+.dmt-thanks-close {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 26px;
+  padding: 0;
+  border: none;
+  border-radius: 7px;
+  background: transparent;
+  color: var(--dsw-alias-label-tertiary, rgba(160, 160, 170, 0.9));
+  font-size: 17px;
+  line-height: 1;
+  cursor: pointer;
+}
+
+.dmt-thanks-close:hover {
+  background: var(--dsw-alias-bg-layer-1, rgba(128, 128, 128, 0.12));
+  color: var(--dsw-alias-label-primary, #f2f2f5);
+}
+
+.dmt-thanks-title {
+  margin: 0 22px 8px 0;
+  font-size: 15px;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+}
+
+.dmt-thanks-body {
+  margin: 0;
+  color: var(--dsw-alias-label-secondary, rgba(210, 210, 218, 0.92));
+}
+
+.dmt-thanks-wish {
+  margin: 10px 0 0;
+  color: var(--dsw-alias-state-success-primary, #30a46c);
+  font-weight: 600;
+}
+
+.dmt-thanks-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-top: 18px;
+}
+
+.dmt-thanks-cta,
+.dmt-thanks-ack {
+  appearance: none;
+  box-sizing: border-box;
+  padding: 7px 14px;
+  border-radius: 8px;
+  font: inherit;
+  font-weight: 600;
+  text-decoration: none;
+  cursor: pointer;
+  transition: background 120ms ease, border-color 120ms ease;
+}
+
+/* The ask is the one bright thing in the card: amber rather than the shell's blue, so it
+   reads as an invitation instead of another system button. Dark ink keeps it legible. */
+.dmt-thanks-cta {
+  border: 1px solid #F0B429;
+  background: #FFC93C;
+  color: #2B2000;
+  box-shadow: 0 6px 16px -10px rgba(255, 201, 60, 0.9);
+}
+
+.dmt-thanks-cta:hover {
+  background: #FFD75E;
+  border-color: #F7C948;
+  color: #2B2000;
+}
+
+.dmt-thanks-ack {
+  border: 1px solid var(--dsw-alias-border-l1, rgba(128, 128, 128, 0.28));
+  background: transparent;
+  color: var(--dsw-alias-label-primary, #f2f2f5);
+}
+
+.dmt-thanks-ack:hover { background: var(--dsw-alias-bg-layer-1, rgba(128, 128, 128, 0.12)); }
+
+.dmt-thanks-cta:focus-visible,
+.dmt-thanks-ack:focus-visible,
+.dmt-thanks-close:focus-visible,
+.dmt-thanks-link:focus-visible {
+  outline: 2px solid var(--dsw-alias-brand-primary, #4d7cfe);
+  outline-offset: 2px;
+}
+
+.dmt-thanks-foot {
+  margin: 14px 0 0;
+  padding-top: 10px;
+  border-top: 1px solid var(--dsw-alias-border-l1, rgba(128, 128, 128, 0.16));
+  color: var(--dsw-alias-label-tertiary, rgba(160, 160, 170, 0.9));
+  font-size: 12px;
+}
+
+.dmt-thanks-link {
+  color: var(--dsw-alias-brand-primary, #4d7cfe);
+  text-decoration: none;
+}
+
+.dmt-thanks-link:hover { text-decoration: underline; }
+
+@keyframes dmt-thanks-fade {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+@keyframes dmt-thanks-rise {
+  from { opacity: 0; transform: translateY(10px) scale(0.985); }
+  to { opacity: 1; transform: translateY(0) scale(1); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .dmt-thanks-layer,
+  .dmt-thanks { animation: none; }
+}
 `
 
     /** Inject the stylesheet once per document. */
@@ -1053,6 +1255,7 @@ window.__ModuleLoader__.load({
           h(
             'div',
             { className: 'dmt-head' },
+            h('span', { className: 'dmt-brand', 'aria-hidden': 'true' }, h(BrandMark, { size: 14 })),
             h('span', {
               className: 'dmt-mark',
               'data-stale': stale ? '1' : '0',
@@ -1698,6 +1901,248 @@ window.__ModuleLoader__.load({
       )
     }
 
+    /**
+     * Brand mark for the card header: the same rising line as the settings glyph, but
+     * filled so it still reads at 14px against the sidebar. Colour comes from CSS, so
+     * the mark can be darkened without editing the shape.
+     */
+    function BrandMark(props) {
+      const size = typeof props?.size === 'number' ? props.size : 14
+      return h(
+        'svg',
+        { width: size, height: size, viewBox: '0 0 24 24', fill: 'none', 'aria-hidden': 'true' },
+        h('rect', { width: 24, height: 24, rx: 6, fill: 'currentColor' }),
+        h('path', {
+          d: 'M5.4 15.6 9.5 11.5l2.9 2.9 6-6',
+          stroke: '#FFFFFF',
+          strokeWidth: 2.1,
+          strokeLinecap: 'round',
+          strokeLinejoin: 'round',
+        }),
+        h('path', {
+          d: 'M14.7 8.4h3.7v3.7',
+          stroke: '#FFFFFF',
+          strokeWidth: 2.1,
+          strokeLinecap: 'round',
+          strokeLinejoin: 'round',
+        }),
+      )
+    }
+
+    /* ---------------------------------------------------------------------- *
+     * thank-you card
+     * ---------------------------------------------------------------------- */
+
+    /**
+     * True while the operator is typing somewhere, so the card never takes the
+     * caret out of a cost box that is half filled.
+     * @returns whether an editable element has focus.
+     */
+    function isEditing() {
+      const active = document.activeElement
+      if (active === null || active === undefined) return false
+      const tag = String(active.tagName ?? '').toLowerCase()
+      if (tag === 'input' || tag === 'textarea' || tag === 'select') return true
+      return active.isContentEditable === true
+    }
+
+    /**
+     * Ask the host whether the card is due. A host that cannot answer is a host
+     * that shows nothing: this surface must never get in the way of the card.
+     * @returns the decision payload, or undefined when the route did not answer.
+     */
+    async function fetchThanks() {
+      try {
+        const body = await requestJson(NOTICE_ENDPOINT)
+        return typeof body?.show === 'boolean' ? body : undefined
+      } catch {
+        return undefined
+      }
+    }
+
+    /**
+     * Record one answer. `keepalive` matters for the issue link: the click also
+     * opens a new tab, and the request has to survive that navigation.
+     * @param action - `thanks`, `issue` or `later`.
+     */
+    function answerThanks(action) {
+      void fetch(apiUrl(NOTICE_ENDPOINT), {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ action }),
+        keepalive: true,
+      }).catch(() => {})
+    }
+
+    /**
+     * Build the card as plain DOM instead of a React tree: it lives directly on
+     * `document.body`, outlives every panel switch, and must not depend on which
+     * renderer version the shell happens to ship.
+     * @param onClose - called with the action the operator chose.
+     * @returns the layer plus the two hooks `mountThanks` needs.
+     */
+    function buildThanks(onClose) {
+      const titleId = `${THANKS_ID}-title`
+      const bodyId = `${THANKS_ID}-body`
+
+      const layer = document.createElement('div')
+      layer.className = 'dmt-thanks-layer'
+
+      const card = document.createElement('div')
+      card.className = 'dmt-thanks'
+      card.id = THANKS_ID
+      card.tabIndex = -1
+      card.setAttribute('role', 'dialog')
+      card.setAttribute('aria-modal', 'true')
+      card.setAttribute('aria-labelledby', titleId)
+      card.setAttribute('aria-describedby', bodyId)
+
+      const close = document.createElement('button')
+      close.type = 'button'
+      close.className = 'dmt-thanks-close'
+      close.textContent = '×'
+      close.addEventListener('click', () => onClose('later'))
+
+      const title = document.createElement('h2')
+      title.className = 'dmt-thanks-title'
+      title.id = titleId
+
+      const body = document.createElement('p')
+      body.className = 'dmt-thanks-body'
+      body.id = bodyId
+
+      const wish = document.createElement('p')
+      wish.className = 'dmt-thanks-wish'
+
+      const actions = document.createElement('div')
+      actions.className = 'dmt-thanks-actions'
+
+      const cta = document.createElement('a')
+      cta.className = 'dmt-thanks-cta'
+      // The star lives on the repo landing page; no deep link into the widget needed.
+      cta.href = REPO_URL
+      cta.target = '_blank'
+      cta.rel = 'noopener noreferrer'
+      // Starring or saying thanks both mean "this landed" — neither should be asked twice.
+      cta.addEventListener('click', () => onClose('thanks'))
+
+      const ack = document.createElement('button')
+      ack.type = 'button'
+      ack.className = 'dmt-thanks-ack'
+      ack.addEventListener('click', () => onClose('thanks'))
+
+      const foot = document.createElement('p')
+      foot.className = 'dmt-thanks-foot'
+
+      const note = document.createTextNode('')
+      const feedback = document.createElement('a')
+      feedback.className = 'dmt-thanks-link'
+      feedback.href = ISSUES_URL
+      feedback.target = '_blank'
+      feedback.rel = 'noopener noreferrer'
+
+      actions.appendChild(cta)
+      actions.appendChild(ack)
+      foot.appendChild(note)
+      foot.appendChild(document.createTextNode(' '))
+      foot.appendChild(feedback)
+      card.appendChild(close)
+      card.appendChild(title)
+      card.appendChild(body)
+      card.appendChild(wish)
+      card.appendChild(actions)
+      card.appendChild(foot)
+      layer.appendChild(card)
+
+      // Clicking the dimmed area, and only it, counts as "later".
+      layer.addEventListener('click', (event) => { if (event.target === layer) onClose('later') })
+      layer.addEventListener('keydown', (event) => {
+        if (event.key !== 'Escape') return
+        event.preventDefault()
+        onClose('later')
+      })
+
+      /** Repaint every label, so a language switch reaches the open card too. */
+      const copy = () => {
+        close.setAttribute('aria-label', t('thanks.close'))
+        title.textContent = t('thanks.title')
+        body.textContent = t('thanks.body')
+        wish.textContent = t('thanks.wish')
+        cta.textContent = t('thanks.star')
+        ack.textContent = t('thanks.ack')
+        note.textContent = t('thanks.note')
+        feedback.textContent = t('thanks.repo')
+      }
+      copy()
+
+      return { layer, card, copy }
+    }
+
+    /**
+     * Show the thank-you card once, when the host says it is due.
+     *
+     * Everything that decides whether it appears lives on the host: the show
+     * budget, the cooldown and the final answer all survive a restart, which a
+     * browser flag could not, because the desktop shell binds a new port each
+     * launch and takes `localStorage` with it.
+     */
+    function mountThanks() {
+      const host = typeof document === 'undefined' ? undefined : document.body
+      // Test harnesses load this module without a DOM; there is nothing to
+      // attach a floating card to, and nothing to prove by trying.
+      if (host === undefined || host === null || typeof host.appendChild !== 'function') return
+      if (typeof window === 'undefined' || typeof window.setTimeout !== 'function') return
+
+      /** The layer on screen, or null. */
+      let layer = null
+      /** Element that held focus before the card took it. */
+      let previous = null
+      let unsubscribe = null
+      let tries = 0
+
+      const dismiss = (action) => {
+        if (layer === null) return
+        const node = layer
+        layer = null
+        node.remove()
+        if (unsubscribe !== null) {
+          unsubscribe()
+          unsubscribe = null
+        }
+        answerThanks(action)
+        if (previous !== null && typeof previous.focus === 'function') previous.focus()
+        previous = null
+      }
+
+      const reveal = () => {
+        const built = buildThanks(dismiss)
+        layer = built.layer
+        previous = document.activeElement
+        document.body.appendChild(layer)
+        built.card.focus()
+        if (localeService !== null && typeof localeService.subscribe === 'function') {
+          unsubscribe = localeService.subscribe(built.copy)
+        }
+      }
+
+      const attempt = async () => {
+        if (layer !== null || document.hidden === true) return
+        if (isEditing()) {
+          // Give the operator room to finish the sentence; past the budget the
+          // card is simply skipped for this page load.
+          if (tries >= THANKS_IDLE_TRIES) return
+          tries += 1
+          window.setTimeout(() => { void attempt() }, THANKS_IDLE_MS)
+          return
+        }
+        const decision = await fetchThanks()
+        if (decision?.show !== true || layer !== null || document.hidden === true) return
+        reveal()
+      }
+
+      window.setTimeout(() => { void attempt() }, THANKS_DELAY_MS)
+    }
+
     /**
      * Register the dictionaries, then both surfaces. `slots` and `locale` are the two
      * services these components need, so they are the only ones injected — injecting
@@ -1733,6 +2178,14 @@ window.__ModuleLoader__.load({
         { name: SETTINGS_ICON_SLOT, id: SETTINGS_ID },
         MarketIcon,
       ))
+
+      try {
+        mountThanks()
+      } catch (error) {
+        // A greeting is not worth a broken sidebar: the card may be absent, the
+        // quote card and the editor must still mount.
+        console.warn('[market-watching] thank-you card skipped', error)
+      }
     }
 
     const inject = ['slots', 'locale']

package/icon.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" role="img" aria-label="dsh-market-watching">
+  <defs>
+    <linearGradient id="dmt-icon-fill" x1="0" y1="24" x2="24" y2="0" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#0E9F6E"/>
+      <stop offset="1" stop-color="#34D399"/>
+    </linearGradient>
+  </defs>
+  <rect width="24" height="24" rx="6" fill="url(#dmt-icon-fill)"/>
+  <path d="M5.4 15.6 9.5 11.5l2.9 2.9 6-6" fill="none" stroke="#FFFFFF" stroke-width="2.1" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M14.7 8.4h3.7v3.7" fill="none" stroke="#FFFFFF" stroke-width="2.1" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/index.js

@@ -37,6 +37,9 @@ export const SETTINGS_PATH = '/api/market.settings'
 /** Route that validates one operator-typed code before it joins the watchlist. */
 export const RESOLVE_PATH = '/api/market.resolve'
 
+/** Route that decides whether the post-install thank-you card is due. */
+export const NOTICE_PATH = '/api/market.notice'
+
 /** Connection owns the `/api` channel; its exact Fetch registry carries these routes. */
 export const inject = ['connection']
 
@@ -54,6 +57,39 @@ const LEGACY_SETTINGS_FILENAME = 'dsh-market-ticker.json'
 /** Bumped only when the stored shape changes incompatibly. */
 const SETTINGS_VERSION = 1
 
+/**
+ * Thank-you card bookkeeping.
+ *
+ * This lives beside the settings document rather than inside it: settings are
+ * normalized on every read and write, so an unknown field would be dropped the
+ * moment the operator saved the watchlist.
+ */
+const NOTICE_FILENAME = 'dsh-market-watching.notice.json'
+
+/** Bumped only when the stored notice shape changes incompatibly. */
+const NOTICE_VERSION = 1
+
+/** How many times one installation may ever see the card. */
+const NOTICE_MAX_SHOWS = 3
+
+/** Quiet window after a "later", so the card never becomes a nag. */
+const NOTICE_COOLDOWN_MS = 7 * 24 * 60 * 60 * 1000
+
+/**
+ * The browser asks once per page load; a reload storm must not burn through the
+ * show budget, so two answers inside this window are served from memory.
+ */
+const NOTICE_THROTTLE_MS = 30 * 1000
+
+/** An answer body is a single short action, never a payload. */
+const NOTICE_MAX_BODY = 2048
+
+/** Answers that mean "do not ask again", as opposed to "not now". */
+const NOTICE_FINAL = new Set(['thanks', 'issue'])
+
+/** Every answer the card can send back. */
+const NOTICE_ACTIONS = new Set(['thanks', 'issue', 'later'])
+
 /**
  * Upper bound on the watchlist. The sidebar card is the constraint, not the
  * upstreams: sixteen rows already overflow a short window.
@@ -531,6 +567,78 @@ function writeSettings(path, settings, log) {
   }
 }
 
+/* -------------------------------------------------------------------------- *
+ * thank-you card
+ * -------------------------------------------------------------------------- */
+
+/**
+ * Shape written before anything has been shown, so the first decision is a
+ * plain `shows === 0` read instead of a special case.
+ * @returns a fresh notice document.
+ */
+function emptyNotice() {
+  return { version: NOTICE_VERSION, shows: 0, lastAt: 0, closed: null }
+}
+
+/**
+ * Read the notice document, tolerating anything on disk.
+ *
+ * The card is decoration: a corrupt or hand-edited file must degrade to "ask
+ * once more", never to a crash on startup.
+ * @param path - absolute path of the document.
+ * @param log - warning sink for an unreadable file.
+ * @returns always a complete notice document.
+ */
+function readNotice(path, log) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    const shows = Number.isInteger(parsed?.shows) && parsed.shows >= 0 ? Math.min(parsed.shows, NOTICE_MAX_SHOWS) : 0
+    const lastAt = Number.isFinite(parsed?.lastAt) && parsed.lastAt >= 0 ? parsed.lastAt : 0
+    const closed = NOTICE_FINAL.has(parsed?.closed) ? parsed.closed : null
+    return { version: NOTICE_VERSION, shows, lastAt, closed }
+  } catch (error) {
+    if (error.code !== 'ENOENT') log.warn(`${LOG_PREFIX} ignoring ${path}: ${String(error.message ?? error)}`)
+    return emptyNotice()
+  }
+}
+
+/**
+ * Persist the notice document atomically, matching the settings writer.
+ * @param path - absolute path of the document.
+ * @param notice - already-normalized notice document.
+ * @param log - warning sink for a failed write.
+ * @returns true when the document reached disk.
+ */
+function writeNotice(path, notice, log) {
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    const staged = `${path}.tmp`
+    writeFileSync(staged, `${JSON.stringify(notice, null, 2)}\n`)
+    renameSync(staged, path)
+    return true
+  } catch (error) {
+    log.warn(`${LOG_PREFIX} cannot write ${path}: ${String(error.message ?? error)}`)
+    return false
+  }
+}
+
+/**
+ * Decide whether the card is due, and say why.
+ *
+ * The order matters: a closed card stays closed whatever the counters say, and
+ * a spent show budget outranks the cooldown so the reason reported to the
+ * browser is the one that will not change on the next reload.
+ * @param notice - stored notice document.
+ * @param now - clock, injected for tests.
+ * @returns `{ show, reason }` with a stable reason string.
+ */
+export function noticeDecision(notice, now = Date.now()) {
+  if (notice?.closed === 'thanks' || notice?.closed === 'issue') return { show: false, reason: 'answered' }
+  if ((notice?.shows ?? 0) >= NOTICE_MAX_SHOWS) return { show: false, reason: 'capped' }
+  if (notice?.lastAt > 0 && now - notice.lastAt < NOTICE_COOLDOWN_MS) return { show: false, reason: 'cooling' }
+  return { show: true, reason: (notice?.shows ?? 0) === 0 ? 'first' : 'again' }
+}
+
 /* -------------------------------------------------------------------------- *
  * upstream
  * -------------------------------------------------------------------------- */
@@ -742,6 +850,11 @@ export function apply(ctx, config = {}) {
   const cacheMs = Number.isFinite(config.cacheMs) && config.cacheMs >= 0 ? config.cacheMs : DEFAULTS.cacheMs
   const settingsPath = join(harnessHome(), SETTINGS_FILENAME)
   const legacySettingsPath = join(harnessHome(), LEGACY_SETTINGS_FILENAME)
+  const noticePath = join(harnessHome(), NOTICE_FILENAME)
+
+  let notice = readNotice(noticePath, log)
+  /** Last decision served, so reloads inside the throttle window cannot spend two shows. */
+  let noticeAnswer
 
   let settings = readSettings(settingsPath, log)
   if (!existsSync(settingsPath) && existsSync(legacySettingsPath)) {
@@ -981,4 +1094,69 @@ export function apply(ctx, config = {}) {
       return jsonResponse({ ok: false, code: 'noQuote', message: '上游没有这个标的的报价' }, 404)
     },
   })
+
+  /**
+   * The thank-you card. GET answers whether it is due and counts the showing;
+   * POST records what the operator did with it.
+   *
+   * The host owns both halves on purpose: `localStorage` is origin-scoped, and
+   * the desktop shell binds a fresh loopback port on every launch, so a browser
+   * flag would bring the card back on each restart.
+   */
+  ctx.connection.fetch.register({
+    path: NOTICE_PATH,
+    methods: ['GET', 'POST'],
+    requestBody: 'buffered',
+    fetch: async (request) => {
+      if (request.method !== 'POST') {
+        const now = Date.now()
+        if (noticeAnswer !== undefined && now - noticeAnswer.at < NOTICE_THROTTLE_MS) {
+          return jsonResponse(noticeAnswer.body)
+        }
+        const decision = noticeDecision(notice, now)
+        let body
+        if (decision.show) {
+          notice = { ...notice, shows: notice.shows + 1, lastAt: now }
+          writeNotice(noticePath, notice, log)
+          body = { ok: true, show: true, reason: decision.reason, shows: notice.shows }
+        } else {
+          body = { ok: true, show: false, reason: decision.reason, shows: notice.shows }
+        }
+        noticeAnswer = { at: now, body }
+        return jsonResponse(body)
+      }
+
+      // The body is one short action, so it is read as text and bounded before parsing.
+      let text
+      try {
+        text = await request.text()
+      } catch {
+        return jsonResponse({ ok: false, code: 'badJson', message: '请求体不是合法的 JSON' }, 400)
+      }
+      if (text.length > NOTICE_MAX_BODY) {
+        return jsonResponse({ ok: false, code: 'tooLarge', message: '请求体过大' }, 413)
+      }
+      let body
+      try {
+        body = JSON.parse(text)
+      } catch {
+        return jsonResponse({ ok: false, code: 'badJson', message: '请求体不是合法的 JSON' }, 400)
+      }
+      const action = typeof body?.action === 'string' ? body.action : ''
+      if (!NOTICE_ACTIONS.has(action)) {
+        return jsonResponse({ ok: false, code: 'badAction', message: 'action 必须是 thanks / issue / later' }, 400)
+      }
+
+      // "thanks" and "issue" close the card for good; "later" only restarts the cooldown.
+      notice = action === 'later'
+        ? { ...notice, lastAt: Date.now() }
+        : { ...notice, closed: action }
+      if (!writeNotice(noticePath, notice, log)) {
+        return jsonResponse({ ok: false, code: 'writeFailed', message: '状态写入失败，请检查 DSH_HOME 权限' }, 500)
+      }
+      // The cached answer would still say `show: true`, so it is dropped here.
+      noticeAnswer = undefined
+      return jsonResponse({ ok: true, closed: notice.closed })
+    },
+  })
 }

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "dsh-market-watching",
-  "version": "0.1.0",
-  "description": "DSH 侧栏行情卡片：加密货币、A股/港股/美股、外汇的实时价格与涨幅，可设置买入/做空价格与数量，实时显示持仓盈亏金额；标的在 DSH 设置页里自选，无需登录。",
+  "version": "0.2.2",
+  "description": "DSH 侧栏行情卡片：加密货币、A股/港股/美股、黄金、外汇、指数的实时价格与涨幅，可设置买入/做空价格与数量，实时显示持仓盈亏金额；标的在 DSH 设置页里自选，无需登录。",
+  "icon": "./icon.svg",
   "keywords": [
     "dsh",
     "dsh-plugin",
@@ -34,6 +35,7 @@
     "index.js",
     "http.mjs",
     "client.js",
+    "icon.svg",
     "cordis.patch.yml",
     "README.md",
     "README.en.md",