dsh-pocket 1.0.0 → 1.0.2

package/LICENSE

@@ -1,21 +1,344 @@
-MIT License
-
-Copyright (c) 2026 shaobeichen
-
-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.
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+ 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+ freedom to share and change it.  By contrast, the GNU General Public
+ License is intended to guarantee your freedom to share and change free
+ software--to make sure the software is free for all its users.  This
+ General Public License applies to most of the Free Software
+ Foundation's software and to any other program whose authors commit to
+ using it.  (Some other Free Software Foundation software is covered by
+ the GNU Lesser General Public License instead.)  You can apply it to
+ your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+ price.  Our General Public Licenses are designed to make sure that you
+ have the freedom to distribute copies of free software (and charge for
+ this service if you wish), that you receive source code or can get it
+ if you want it, that you can change the software or use pieces of it
+ in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+ anyone to deny you these rights or to ask you to surrender the rights.
+ These restrictions translate to certain responsibilities for you if you
+ distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+ gratis or for a fee, you must give the recipients all the rights that
+ you have.  You must make sure that they, too, receive or can get the
+ source code.  And you must show them these terms so they know their
+ rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+ (2) offer you this license which gives you legal permission to copy,
+ distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+ that everyone understands that there is no warranty for this free
+ software.  If the software is modified by someone else and passed on, we
+ want its recipients to know that what they have is not the original, so
+ that any problems introduced by others will not reflect on the original
+ authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+ patents.  We wish to avoid the danger that redistributors of a free
+ program will individually obtain patent licenses, in effect making the
+ program proprietary.  To prevent this, we have made it clear that any
+ patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+ modification follow.
+
+                    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+ a notice placed by the copyright holder saying it may be distributed
+ under the terms of this General Public License.  The "Program", below,
+ refers to any such program or work, and a "work based on the Program"
+ means either the Program or any derivative work under copyright law:
+ that is to say, a work containing the Program or a portion of it,
+ either verbatim or with modifications and/or translated into another
+ language.  (Hereinafter, translation is included without limitation in
+ the term "modification".)  Each licensee is addressed as "you".
+
+ Activities other than copying, distribution and modification are not
+ covered by this License; they are outside its scope.  The act of
+ running the Program is not restricted, and the output from the Program
+ is covered only if its contents constitute a work based on the
+ Program (independent of having been made by running the Program).
+ Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+ source code as you receive it, in any medium, provided that you
+ conspicuously and appropriately publish on each copy an appropriate
+ copyright notice and disclaimer of warranty; keep intact all the
+ notices that refer to this License and to the absence of any warranty;
+ and give any other recipients of the Program a copy of this License
+ along with the Program.
+
+ You may charge a fee for the physical act of transferring a copy, and
+ you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+ of it, thus forming a work based on the Program, and copy and
+ distribute such modifications or work under the terms of Section 1
+ above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a notice
+    that there is no warranty (or else, saying that you provide a
+    warranty) and that users may redistribute the program under these
+    conditions, and telling the user how to view a copy of this License.
+    (Exception: if the Program itself is interactive but does not
+    normally print such an announcement, your work based on the Program
+    is not required to print an announcement.)
+
+ These requirements apply to the modified work as a whole.  If
+ identifiable sections of that work are not derived from the Program,
+ and can be reasonably considered independent and separate works in
+ themselves, then this License, and its terms, do not apply to those
+ sections when you distribute them as separate works.  But when you
+ distribute the same sections as part of a whole which is a work based
+ on the Program, the distribution of the whole must be on the terms of
+ this License, whose permissions for other licensees extend to the
+ entire whole, and thus to each and every part regardless of who wrote it.
+
+ Thus, it is not the intent of this section to claim rights or contest
+ your rights to work written entirely by you; rather, the intent is to
+ exercise the right to control the distribution of derivative or
+ collective works based on the Program.
+
+ In addition, mere aggregation of another work not based on the Program
+ with the Program (or with a work based on the Program) on a volume of
+ a storage or distribution medium does not bring the other work under
+ the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+ under Section 2) in object code or executable form under the terms of
+ Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange;
+    or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your cost
+    of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such an
+    offer, in accord with Subsection b above.)
+
+ The source code for a work means the preferred form of the work for
+ making modifications to it.  For an executable work, complete source
+ code means all the source code for all modules it contains, plus any
+ associated interface definition files, plus the scripts used to
+ control compilation and installation of the executable.  However, as a
+ special exception, the source code distributed need not include
+ anything that is normally distributed (in either source or binary
+ form) with the major components (compiler, kernel, and so on) of the
+ operating system on which the executable runs, unless that component
+ itself accompanies the executable.
+
+ If distribution of executable or object code is made by offering
+ access to copy from a designated place, then offering equivalent
+ access to copy the source code from the same place counts as
+ distribution of the source code, even though third parties are not
+ compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+ except as expressly provided under this License.  Any attempt
+ otherwise to copy, modify, sublicense or distribute the Program is
+ void, and will automatically terminate your rights under this License.
+ However, parties who have received copies, or rights, from you under
+ this License will not have their licenses terminated so long as such
+ parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+ signed it.  However, nothing else grants you permission to modify or
+ distribute the Program or its derivative works.  These actions are
+ prohibited by law if you do not accept this License.  Therefore, by
+ modifying or distributing the Program (or any work based on the
+ Program), you indicate your acceptance of this License to do so, and
+ all its terms and conditions for copying, distributing or modifying
+ the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+ Program), the recipient automatically receives a license from the
+ original licensor to copy, distribute or modify the Program subject to
+ these terms and conditions.  You may not impose any further
+ restrictions on the recipients' exercise of the rights granted herein.
+ You are not responsible for enforcing compliance by third parties to
+ this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+ infringement or for any other reason (not limited to patent issues),
+ conditions are imposed on you (whether by court order, agreement or
+ otherwise) that contradict the conditions of this License, they do not
+ excuse you from the conditions of this License.  If you cannot
+ distribute so as to satisfy simultaneously your obligations under this
+ License and any other pertinent obligations, then as a consequence you
+ may not distribute the Program at all.  For example, if a patent
+ license would not permit royalty-free redistribution of the Program by
+ all those who receive copies directly or indirectly through you, then
+ the only way you could satisfy both it and this License would be to
+ refrain entirely from distribution of the Program.
+
+ If any portion of this section is held invalid or unenforceable under
+ any particular circumstance, the balance of the section is intended to
+ apply and the section as a whole is intended to apply in other
+ circumstances.
+
+ It is not the purpose of this section to induce you to infringe any
+ patents or other property right claims or to contest validity of any
+ such claims; this section has the sole purpose of protecting the
+ integrity of the free software distribution system, which is
+ implemented by public license practices.  Many people have made
+ generous contributions to the wide range of software distributed
+ through that system in reliance on consistent application of that
+ system; it is up to the author/donor to decide if he or she is willing
+ to distribute software through any other system and a licensee cannot
+ impose that choice.
+
+ This section is intended to make thoroughly clear what is believed to
+ be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+ certain countries either by patents or by copyrighted interfaces, the
+ original copyright holder who places this Program under this License
+ may add an explicit geographical distribution limitation excluding
+ those countries, so that distribution is permitted only in or among
+ countries not thus excluded.  In such case, this License incorporates
+ the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new
+ versions of the General Public License from time to time.  Such new
+ versions will be similar in spirit to the present version, but may
+ differ in detail to address new problems or concerns.
+
+ Each version is given a distinguishing version number.  If the Program
+ specifies a version number of this License which applies to it and
+ "any later version", you have the option of following the terms and
+ conditions either of that version or of any later version published by
+ the Free Software Foundation.  If the Program does not specify a
+ version number of this License, you may choose any version ever
+ published by the Free Software Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+ programs whose distribution conditions are different, write to the
+ author to ask for permission.  For software which is copyrighted by the
+ Free Software Foundation, write to the Free Software Foundation; we
+ sometimes make exceptions for this.  Our decision will be guided by the
+ two goals of preserving the free status of all derivatives of our free
+ software and of promoting the sharing and reuse of software generally.
+
+                            NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
+ WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+ EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+ OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND,
+ EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+ PROGRAM IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME
+ THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+ WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+ AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
+ FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+ CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+ PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+ RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+ FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF
+ SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+ DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+ possible use to the public, the best way to achieve this is to make it
+ free software which everyone can redistribute and change under these
+ terms.
+
+  To do so, attach the following notices to the program.  It is safest
+ to attach them to the start of each source file to most effectively
+ convey the exclusion of warranty; and each file should have at least
+ the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
+
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Ty Coon>, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications
+with the library.  If this is what you want to do, use the GNU Lesser
+General Public License instead of this License.

package/README.en.md

@@ -0,0 +1,122 @@
+<p align="center">
+  <img src="docs/banner.jpg" alt="DSH Pocket" width="100%">
+</p>
+
+# DSH Pocket
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-pocket"><img alt="npm" src="https://img.shields.io/npm/v/dsh-pocket?color=4d6bfe&label=npm"></a>
+  <a href="https://www.npmjs.com/package/dsh-pocket"><img alt="downloads" src="https://img.shields.io/npm/dm/dsh-pocket?color=4d6bfe"></a>
+  <a href="https://github.com/shaobeichen/dsh-pocket/actions"><img alt="CI" src="https://github.com/shaobeichen/dsh-pocket/actions/workflows/npm-publish.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-GPL--2.0-red.svg"></a>
+  <a href="https://github.com/shaobeichen/dsh-pocket/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/shaobeichen/dsh-pocket"></a>
+</p>
+
+> Put **DeepSeek Harness in your pocket**: one package, one settings tab — scan a QR code and your phone shows exactly what's on your computer screen, live, from anywhere.
+>
+> [English](README.en.md) | [中文](README.md)
+
+## What is this
+
+`dsh web` only allows local access by default (`127.0.0.1:3080`). DSH Pocket puts a **header-rewriting proxy** in front of it and hands you QR codes right in the DSH web settings page:
+
+```
+Phone ──scan──> dsh-pocket proxy ──> dsh web :3080
+                 (rewrites Host/Origin to loopback; passes DSH's trust fence)
+```
+
+## ✨ Features
+
+| Feature | Description |
+|---|---|
+| 📶 LAN QR access | Works out of the box: Settings → Plugins → Phone access — scan the LAN QR on the same Wi-Fi |
+| 🌐 Public QR (from anywhere) | Click "Enable anywhere" → cloudflared tunnel → scan the public QR over 4G / any network |
+| ⚡ Real-time sync | Streaming output passes through WebSocket untouched — what the computer renders, the phone renders live; fully interactive both ways |
+| 📱 Mobile-adaptive layout | Narrow screens get a drawer layout automatically (ported from dsh-web-mobile, MIT): sidebar drawer, full-width conversation, safe-area insets, touch optimizations |
+| 🧩 Zero-dependency install | One npm package, one settings tab — no core/adapter split, no account, no server |
+| 🔒 URL is the key | No public URL exposure in LAN mode; public URL rotates on every restart |
+| 🔔 Web Push | Phone notifications when a task finishes or fails (even with the page closed); requires the HTTPS public tunnel or localhost |
+
+## 🚀 Usage
+
+```sh
+# 1. Install the plugin (everything in one package)
+dsh plugin --profile web add dsh-pocket -w
+
+# 2. Restart dsh web
+npx @deepseek-ai/dsh web
+```
+
+### LAN (same Wi-Fi)
+
+Settings → Plugins → **Phone access** → scan the "📶 LAN" QR code → the phone opens the exact same DSH, in real time.
+
+### Public (from anywhere)
+
+On the same page click "**Enable anywhere**" → wait for the tunnel (first run downloads cloudflared) → scan the "🌐 Public" QR code → works from outside (4G / office network).
+
+> Upgrading: `dsh plugin --profile web update dsh-pocket --latest -w` (`--latest` is required across major versions — a `^0.x` range won't auto-jump to 1.x).
+
+## 🧭 How it works
+
+DSH's `/api` browser-trust fence only accepts loopback or `--trusted-host` authorities (and the official build refuses `0.0.0.0` binding to avoid exposing remote code execution to the network). Pocket rewrites every inbound request's `Host` / `Origin` to `127.0.0.1:<dsh-port>`, so the fence always sees loopback — **no dsh configuration changes needed**. The proxy auto-starts with the plugin; the public tunnel is on demand (cloudflared forced to HTTP/2 over TCP 443 to bypass blocked QUIC/UDP).
+
+## ⚠️ Security (read first)
+
+- **DSH can execute code on your computer.** The QR code / URL is the key — **never share it with anyone**.
+- The public URL is randomly assigned by cloudflared and **changes on every restart** (old links die automatically — a natural key rotation).
+- LAN mode exposes nothing publicly; only devices on the same network can reach it.
+- Built for personal use; access tokens for multi-device/sharing are planned.
+
+## ⚠️ Public tunnel troubleshooting (read first)
+
+**Symptom**: after clicking "Enable anywhere", the public URL shows `error 1033` (Tunnel error) on the phone.
+
+**Most common cause: a local proxy/VPN (Clash, Surge, v2ray, sing-box, etc., especially in TUN mode).**
+Such tools take over all traffic and often cut cloudflared's tunnel-edge connections
+(`*.argotunnel.com`, Cloudflare edge IPs), so the tunnel registers but the data plane never connects.
+
+**Fix (any one of)**:
+
+1. Temporarily **fully quit the proxy** (not just close the window: quit Clash from the menu-bar icon; if a
+   background service is installed, stop it in the service manager and confirm with `ps aux | grep clash`), then retry.
+2. Add **DIRECT rules** to the proxy for the tunnel domains and Cloudflare edge (Clash example):
+   ```yaml
+   - DOMAIN-SUFFIX,argotunnel.com,DIRECT
+   - DOMAIN-SUFFIX,trycloudflare.com,DIRECT
+   - IP-CIDR,198.41.192.0/24,DIRECT,no-resolve
+   ```
+3. If the network really can't reach the tunnel, use **LAN mode**: turn on the phone hotspot → connect the computer to it → scan the LAN QR. Same experience, from anywhere.
+
+**Other causes**: corporate firewalls / campus networks blocking outbound — ask IT to allow it, or use a hotspot.
+
+## 🗂 Architecture (single package)
+
+| File | Purpose |
+|---|---|
+| `lib/index.js` | Plugin entry: auto-start proxy + register RPC (`inject: connection, webServer`) |
+| `lib/service.mjs` | Service: proxy lifecycle, public tunnel, status snapshot (with QR data URLs) |
+| `lib/proxy.mjs` | Header-rewriting reverse proxy: Host/Origin → loopback, HTTP + WebSocket passthrough + polyfill injection |
+| `lib/tunnel.mjs` | cloudflared quick tunnel: download/extract/start/parse public URL (HTTP/2) |
+| `lib/web-rpc.js` | Loopback RPC: `pocket.status` / `tunnel.start` / `tunnel.stop` |
+| `client/` | "Phone access" settings tab + mobile adaptation (dsh-web-mobile port) |
+| `bin/dsh-pocket.mjs` | CLI: LAN/public modes, prints URL + QR |
+
+## 🛠 Development
+
+```sh
+npm install
+node client/build.mjs   # rebuild after editing client/
+npm test                # proxy rewrite / WS passthrough / tunnel / service / RPC (7 tests)
+```
+
+## 🤝 Credits
+
+- Mobile adaptation ported from [mexiaosqwq/dsh-web-mobile](https://github.com/mexiaosqwq/dsh-web-mobile) (MIT)
+- Public tunnel powered by [cloudflared](https://github.com/cloudflare/cloudflared)
+
+## 📄 License
+
+[GPL-2.0](LICENSE) — copyleft: free to use, modify, and redistribute, but **derivatives must stay GPL** and keep the copyright notice; commercial use included.
+
+> Note: the mobile-adaptation portion is ported from [dsh-web-mobile](https://github.com/mexiaosqwq/dsh-web-mobile) (MIT, GPL-compatible); its copyright notice stays in `client/mobile/LICENSE.dsh-web-mobile`.

package/README.md

@@ -1,8 +1,20 @@
+<p align="center">
+  <img src="docs/banner.jpg" alt="DSH Pocket" width="100%">
+</p>
+
 # DSH Pocket
 
-把 **DeepSeek Harness 装进你的口袋**：一个包、一个设置页，手机扫二维码就实时看到电脑上的同一个界面——人在外面也能用。
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-pocket"><img alt="npm" src="https://img.shields.io/npm/v/dsh-pocket?color=4d6bfe&label=npm"></a>
+  <a href="https://www.npmjs.com/package/dsh-pocket"><img alt="downloads" src="https://img.shields.io/npm/dm/dsh-pocket?color=4d6bfe"></a>
+  <a href="https://github.com/shaobeichen/dsh-pocket/actions"><img alt="CI" src="https://github.com/shaobeichen/dsh-pocket/actions/workflows/npm-publish.yml/badge.svg"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-GPL--2.0-red.svg"></a>
+  <a href="https://github.com/shaobeichen/dsh-pocket/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/shaobeichen/dsh-pocket"></a>
+</p>
 
-> EN: Put DeepSeek Harness in your pocket. One package, one settings tab — scan a QR code and your phone shows exactly what's on your computer screen, live, anywhere.
+> 把 **DeepSeek Harness 装进你的口袋**：一个包、一个设置页，手机扫二维码就实时看到电脑上的同一个界面——人在外面也能用。
+>
+> [English](README.en.md) | [中文](README.md)
 
 ## 这是什么
 
@@ -13,28 +25,49 @@
                 （改写 Host/Origin 为 loopback，DSH 信任栅栏放行）
 ```
 
-- **局域网**：装好插件，设置 → 插件 → **手机访问**，打开就有一个局域网二维码——手机连同一 WiFi 扫码即用
-- **公网**：同一页点「**开启公网访问**」，出第二个二维码——人在外面（4G/公司网）也能访问
-- **实时同步**：DSH 的流式输出走 WebSocket，代理原样透传——**电脑上看到什么，手机上就是什么**
+## ✨ 特性
+
+| 特性 | 说明 |
+|---|---|
+| 📶 局域网扫码 | 装好即用：设置 → 插件 → 手机访问，打开就有局域网二维码，手机连同一 WiFi 扫码即开 |
+| 🌐 公网扫码（人在外面） | 点「开启公网访问」→ cloudflared 隧道 → 出公网二维码，4G/任何网络都能访问 |
+| ⚡ 实时同步 | 流式输出走 WebSocket 全透传——**电脑上在输出，手机上同步在滚**，可双向操作 |
+| 📱 移动端适配 | 窄屏自动变抽屉布局（移植 dsh-web-mobile，MIT）：侧栏抽屉、会话全宽、状态栏安全区、触控优化 |
+| 🧩 零依赖安装 | 一个 npm 包、一个设置页，没有核心/适配器要分开装；无需账号、无需服务器 |
+| 🔒 URL 即钥匙 | 无公网 URL 暴露给第三方（局域网模式）；公网 URL 每次重启自动换新 |
+| 🔔 Web Push 通知 | agent 跑完/出错 → 手机推送通知（即使没开页面）；需 HTTPS 公网路径或 localhost |
 
-## 安装
+## 🚀 怎么用
 
 ```sh
+# 1. 装插件（一个包全都有）
 dsh plugin --profile web add dsh-pocket -w
+
+# 2. 重启 dsh web
+npx @deepseek-ai/dsh web
 ```
 
-重启 `dsh web` → 设置 → 插件 → **手机访问**。**就这一个包，没有核心/适配器要分开装。**
+### 局域网（同一 WiFi）
+
+设置 → 插件 → **手机访问** → 手机扫「📶 局域网」二维码 → 打开的就是电脑上的 DSH，实时同步。
+
+### 公网（人在外面）
+
+同一页点「**开启公网访问**」→ 等隧道建立（首次会下载 cloudflared）→ 手机扫「🌐 公网」二维码 → 人在外面（4G/公司网）也能访问。
+
+> 更新到新版本：`dsh plugin --profile web update dsh-pocket --latest -w`（跨大版本时 `--latest` 是必须的，`^0.x` 范围不会自动升到 1.x）。
+
+## 🧭 原理
+
+DSH 的 `/api` 浏览器信任栅栏只认 loopback 或 `--trusted-host`（官方还禁了 `0.0.0.0` 绑定，防止把远程执行代码暴露给网络）。Pocket 把入站请求的 `Host` / `Origin` 统一改写成 `127.0.0.1:<dsh端口>`，栅栏永远看到 loopback——**不需要改 dsh 的任何配置**。代理随插件自动启动，公网隧道按需开启（cloudflared 强制走 HTTP/2/TCP 443，绕开被网络屏蔽的 QUIC/UDP）。
 
 ## ⚠️ 安全（必读）
 
 - **DSH 能执行你电脑上的代码**。二维码/URL 就是钥匙，**请勿把二维码或 URL 发给任何人**
-- 公网 URL 由 cloudflared 随机分配，**每次重启 dsh web 会变化**（旧链接自动失效，相当于天然轮换）
+- 公网 URL 由 cloudflared 随机分配，**每次重启会变化**（旧链接自动失效，相当于天然轮换）
+- 局域网模式不暴露公网，只有同一网络内的设备能访问
 - 适合个人自用；多设备/分享场景后续会加访问令牌
 
-## 原理
-
-DSH 的 `/api` 浏览器信任栅栏只认 loopback 或 `--trusted-host`（官方还禁了 `0.0.0.0` 绑定，防止把远程执行代码暴露给网络）。Pocket 把入站请求的 `Host` / `Origin` 统一改写成 `127.0.0.1:<dsh端口>`，栅栏永远看到 loopback——**不需要改 dsh 的任何配置**。代理随插件自动启动，公网隧道按需开启（首次自动下载 cloudflared）。
-
 ## ⚠️ 公网隧道常见问题（必读）
 
 **现象**：点「开启公网访问」后，手机上打开公网地址报 `error 1033`（Tunnel error）。
@@ -58,25 +91,33 @@ DSH 的 `/api` 浏览器信任栅栏只认 loopback 或 `--trusted-host`（官
 
 **其他可能**：企业防火墙/校园网拦截出站；此时请让 IT 放行或改用热点。
 
-## 架构（单包）
+## 🗂 架构（单包）
 
 | 文件 | 说明 |
 |---|---|
 | `lib/index.js` | 插件入口：自动起代理 + 注册 RPC（`inject: connection, webServer`） |
 | `lib/service.mjs` | 服务：代理生命周期、公网隧道、状态快照（含二维码 data URL） |
-| `lib/proxy.mjs` | 改头反向代理：Host/Origin → loopback，HTTP + WebSocket 全透传 |
-| `lib/tunnel.mjs` | cloudflared 快速隧道：下载/启动/解析公网 URL |
+| `lib/proxy.mjs` | 改头反向代理：Host/Origin → loopback，HTTP + WebSocket 全透传 + polyfill 注入 |
+| `lib/tunnel.mjs` | cloudflared 快速隧道：下载/解压/启动/解析公网 URL（HTTP/2） |
 | `lib/web-rpc.js` | loopback RPC：`pocket.status` / `tunnel.start` / `tunnel.stop` |
-| `client/` | 设置页「手机访问」标签（React，esbuild 打包） |
+| `client/` | 设置页「手机访问」+ 移动端适配（dsh-web-mobile 移植） |
+| `bin/dsh-pocket.mjs` | CLI：局域网/公网模式，打印 URL + 二维码 |
 
-## 开发
+## 🛠 开发
 
 ```sh
 npm install
-node client/build.mjs   # 改 client/index.jsx 后重新打包
-npm test                # 代理改写 + WS 透传 + 服务 + RPC（5 个测试）
+node client/build.mjs   # 改 client/ 后重新打包
+npm test                # 代理改写 / WS 透传 / 隧道 / 服务 / RPC（7 测试）
 ```
 
-## License
+## 🤝 致谢
+
+- 移动端适配移植自 [mexiaosqwq/dsh-web-mobile](https://github.com/mexiaosqwq/dsh-web-mobile)（MIT）
+- 公网隧道基于 [cloudflared](https://github.com/cloudflare/cloudflared)
+
+## 📄 License
+
+[GPL-2.0](LICENSE) —— 自由软件许可：可自由使用、修改、分发，但**修改版必须同样以 GPL 开源**并保留版权声明；商用同样适用。
 
-MIT
+> 说明：移动端适配部分移植自 [dsh-web-mobile](https://github.com/mexiaosqwq/dsh-web-mobile)（MIT 许可，兼容 GPL），其版权声明保留在 `client/mobile/LICENSE.dsh-web-mobile`。

package/client/api.js

@@ -5,6 +5,10 @@ export const POCKET_ENDPOINTS = Object.freeze({
   status: 'pocket.status',
   tunnelStart: 'tunnel.start',
   tunnelStop: 'tunnel.stop',
+  pushVapidKey: 'push.vapidKey',
+  pushSubscribe: 'push.subscribe',
+  pushUnsubscribe: 'push.unsubscribe',
+  pushStatus: 'push.status',
 });
 
 /** 浏览器可见的状态字段（无敏感信息；含二维码 data URL）。 */

package/client/client.js

@@ -37,7 +37,11 @@ var POCKET_RPC_CHANNEL = "/dsh-pocket";
 var POCKET_ENDPOINTS = Object.freeze({
   status: "pocket.status",
   tunnelStart: "tunnel.start",
-  tunnelStop: "tunnel.stop"
+  tunnelStop: "tunnel.stop",
+  pushVapidKey: "push.vapidKey",
+  pushSubscribe: "push.subscribe",
+  pushUnsubscribe: "push.unsubscribe",
+  pushStatus: "push.status"
 });
 function redactStatus(s) {
   return {
@@ -1241,6 +1245,32 @@ function mobileApply(ctx) {
 // client/index.jsx
 var name = "dsh-pocket";
 var inject = ["slots", "connection", "layout", "locale", "sessionLogDownload"];
+async function setupPush(rpcCall) {
+  try {
+    if (!("serviceWorker" in navigator) || !("PushManager" in window)) return "unsupported";
+    if (!window.isSecureContext) return "insecure";
+    const reg = await navigator.serviceWorker.register("/pocket-sw.js");
+    const vapid = await rpcCall(POCKET_ENDPOINTS.pushVapidKey, {});
+    if (!vapid?.ok) return "host-error";
+    let sub = await reg.pushManager.getSubscription();
+    if (!sub) {
+      sub = await reg.pushManager.subscribe({
+        userVisibleOnly: true,
+        applicationServerKey: urlBase64ToUint8Array(vapid.value.publicKey)
+      });
+    }
+    const res = await rpcCall(POCKET_ENDPOINTS.pushSubscribe, { subscription: sub.toJSON() });
+    return res?.ok ? "on" : "host-error";
+  } catch {
+    return "error";
+  }
+}
+function urlBase64ToUint8Array(base64url) {
+  const pad = "=".repeat((4 - base64url.length % 4) % 4);
+  const b64 = (base64url + pad).replace(/-/g, "+").replace(/_/g, "/");
+  const raw = atob(b64);
+  return Uint8Array.from(raw, (c) => c.charCodeAt(0));
+}
 var styles = {
   card: { background: "var(--dsw-alias-bg-layer-1,#fff)", border: "1px solid var(--dsw-alias-border-l2,#e5e7eb)", borderRadius: 12, padding: "14px 16px", maxWidth: 480 },
   block: { borderTop: "1px solid var(--dsw-alias-border-l2,#e5e7eb)", marginTop: 12, paddingTop: 12 },
@@ -1255,6 +1285,7 @@ function PocketSettingsTab({ rpcCall }) {
   const [status, setStatus] = (0, import_react2.useState)(null);
   const [busy, setBusy] = (0, import_react2.useState)(false);
   const [error, setError] = (0, import_react2.useState)(null);
+  const [pushState, setPushState] = (0, import_react2.useState)("checking");
   const call = async (endpoint, payload) => {
     const res = await rpcCall(endpoint, payload);
     if (!res?.ok) throw new Error(res?.error?.message ?? "RPC failed");
@@ -1271,6 +1302,9 @@ function PocketSettingsTab({ rpcCall }) {
     const t = setInterval(load, 3e3);
     return () => clearInterval(t);
   }, []);
+  (0, import_react2.useEffect)(() => {
+    setupPush(rpcCall).then(setPushState);
+  }, []);
   const startTunnel = async () => {
     setBusy(true);
     setError(null);
@@ -1331,6 +1365,17 @@ function PocketSettingsTab({ rpcCall }) {
         (0, import_react2.createElement)("div", { style: styles.warn, marginTop: 8 }, "\u26A0\uFE0F DSH \u80FD\u6267\u884C\u7535\u8111\u4EE3\u7801\uFF1A\u4E8C\u7EF4\u7801/URL \u5C31\u662F\u94A5\u5319\uFF0C\u8BF7\u52FF\u53D1\u7ED9\u522B\u4EBA")
       )
     ),
+    // Web Push 状态
+    (0, import_react2.createElement)(
+      "div",
+      { style: styles.block },
+      (0, import_react2.createElement)("div", { style: { fontWeight: 600, fontSize: 13 } }, "\u{1F514} \u63A8\u9001\u901A\u77E5 | Push notifications"),
+      (0, import_react2.createElement)(
+        "div",
+        { style: styles.muted },
+        pushState === "on" ? "\u5DF2\u5F00\u542F\uFF1Aagent \u8DD1\u5B8C/\u51FA\u9519\u65F6\u624B\u673A\u6536\u5230\u901A\u77E5 | on: notified when tasks finish or fail" : pushState === "unsupported" ? "\u5F53\u524D\u6D4F\u89C8\u5668\u4E0D\u652F\u6301\u63A8\u9001 | this browser does not support push" : pushState === "insecure" ? "\u9700\u8981 HTTPS\uFF08\u516C\u7F51\u96A7\u9053\uFF09\u6216 localhost \u624D\u80FD\u5F00\u542F\u63A8\u9001 | push needs HTTPS (public tunnel) or localhost" : pushState === "checking" ? "\u68C0\u67E5\u4E2D\u2026 | checking\u2026" : "\u63A8\u9001\u672A\u5F00\u542F | push not enabled"
+      )
+    ),
     error ? (0, import_react2.createElement)("div", { style: { color: "var(--dsw-alias-state-error-primary,#dc2626)", fontSize: 12, marginTop: 8 } }, `\u274C ${error}`) : null
   );
 }

package/client/index.jsx

@@ -1,6 +1,7 @@
 // dsh-pocket 网页客户端：
-//   1. 设置页签「手机访问」（局域网/公网二维码）
+//   1. 设置页签「手机访问」（局域网/公网二维码 + Web Push 状态）
 //   2. 移动端适配（移植自 MIT 项目 dsh-web-mobile，见 client/mobile/LICENSE.dsh-web-mobile）
+//   3. Web Push：注册 Service Worker + 订阅推送（agent 跑完/出错 → 手机通知）
 //
 // 手机扫码打开的就是电脑上的 dsh web，实时同步；窄屏自动变成抽屉布局。
 
@@ -12,6 +13,36 @@ import { mobileApply } from './mobile/mobile-apply.tsx';
 const name = 'dsh-pocket';
 const inject = ['slots', 'connection', 'layout', 'locale', 'sessionLogDownload'];
 
+/** Web Push：注册 SW + 订阅（仅安全上下文可用：HTTPS 公网 / localhost）。 */
+async function setupPush(rpcCall) {
+  try {
+    if (!('serviceWorker' in navigator) || !('PushManager' in window)) return 'unsupported';
+    if (!window.isSecureContext) return 'insecure'; // http://LAN-IP 无 Push API
+    const reg = await navigator.serviceWorker.register('/pocket-sw.js');
+    const vapid = await rpcCall(POCKET_ENDPOINTS.pushVapidKey, {});
+    if (!vapid?.ok) return 'host-error';
+    let sub = await reg.pushManager.getSubscription();
+    if (!sub) {
+      sub = await reg.pushManager.subscribe({
+        userVisibleOnly: true,
+        applicationServerKey: urlBase64ToUint8Array(vapid.value.publicKey),
+      });
+    }
+    const res = await rpcCall(POCKET_ENDPOINTS.pushSubscribe, { subscription: sub.toJSON() });
+    return res?.ok ? 'on' : 'host-error';
+  } catch {
+    return 'error';
+  }
+}
+
+/** VAPID 公钥（base64url）→ Uint8Array（pushManager.subscribe 需要）。 */
+function urlBase64ToUint8Array(base64url) {
+  const pad = '='.repeat((4 - (base64url.length % 4)) % 4);
+  const b64 = (base64url + pad).replace(/-/g, '+').replace(/_/g, '/');
+  const raw = atob(b64);
+  return Uint8Array.from(raw, (c) => c.charCodeAt(0));
+}
+
 const styles = {
   card: { background: 'var(--dsw-alias-bg-layer-1,#fff)', border: '1px solid var(--dsw-alias-border-l2,#e5e7eb)', borderRadius: 12, padding: '14px 16px', maxWidth: 480 },
   block: { borderTop: '1px solid var(--dsw-alias-border-l2,#e5e7eb)', marginTop: 12, paddingTop: 12 },
@@ -27,6 +58,7 @@ function PocketSettingsTab({ rpcCall }) {
   const [status, setStatus] = useState(null);
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState(null);
+  const [pushState, setPushState] = useState('checking'); // checking|on|unsupported|insecure|off
 
   const call = async (endpoint, payload) => {
     const res = await rpcCall(endpoint, payload);
@@ -44,6 +76,11 @@ function PocketSettingsTab({ rpcCall }) {
     return () => clearInterval(t);
   }, []);
 
+  // Web Push 订阅（只跑一次）
+  useEffect(() => {
+    setupPush(rpcCall).then(setPushState);
+  }, []);
+
   const startTunnel = async () => {
     setBusy(true);
     setError(null);
@@ -97,6 +134,17 @@ function PocketSettingsTab({ rpcCall }) {
         ),
     ),
 
+    // Web Push 状态
+    h('div', { style: styles.block },
+      h('div', { style: { fontWeight: 600, fontSize: 13 } }, '🔔 推送通知 | Push notifications'),
+      h('div', { style: styles.muted },
+        pushState === 'on' ? '已开启：agent 跑完/出错时手机收到通知 | on: notified when tasks finish or fail'
+        : pushState === 'unsupported' ? '当前浏览器不支持推送 | this browser does not support push'
+        : pushState === 'insecure' ? '需要 HTTPS（公网隧道）或 localhost 才能开启推送 | push needs HTTPS (public tunnel) or localhost'
+        : pushState === 'checking' ? '检查中… | checking…'
+        : '推送未开启 | push not enabled'),
+    ),
+
     error ? h('div', { style: { color: 'var(--dsw-alias-state-error-primary,#dc2626)', fontSize: 12, marginTop: 8 } }, `❌ ${error}`) : null,
   );
 }

package/lib/index.js

@@ -3,14 +3,27 @@
 // 设置页「设置 → 插件 → 手机访问」：
 //   - 局域网二维码：自动显示（代理随插件启动）
 //   - 公网二维码：点「开启公网」→ cloudflared 隧道 → 扫码即用，人在外面也能访问
+//   - Web Push：agent 跑完/出错 → 手机推送通知（需 HTTPS 公网路径或 localhost）
 // 手机看到的界面 = 电脑上的 dsh web，实时同步（WebSocket 透传）。
 
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
 import { createPocketService } from './service.mjs';
 import { installPocketRpc } from './web-rpc.js';
+import { createPushService } from './push.mjs';
 
 const name = 'dsh-pocket';
 const inject = ['connection', 'webServer'];
 
+// 服务 worker 源码（同源提供：/pocket-sw.js）
+const SW_SOURCE = new URL('./pocket-sw.js', import.meta.url);
+let swCache = null;
+async function swScript() {
+  if (!swCache) swCache = await readFile(fileURLToPath(SW_SOURCE), 'utf8');
+  return swCache;
+}
+
 export function apply(ctx, config = {}, internals = {}) {
   const logger = ctx.logger?.(name) ?? console;
   const dshPort = internals.dshPort ?? ctx.webServer?.port;
@@ -25,7 +38,52 @@ export function apply(ctx, config = {}, internals = {}) {
     internals,
   });
 
-  const disposeRpc = installPocketRpc(ctx, { service, log: logger });
+  // Web Push 服务（web-push 库；测试可注入 stub）
+  const pushPromise = internals.pushPromise ?? createPushService({ internals });
+  pushPromise.catch((err) => logger.error('dsh-pocket: push service init failed | 推送服务初始化失败: %s', err?.message ?? err));
+
+  const disposers = [];
+  const disposeRpc = installPocketRpc(ctx, {
+    service,
+    push: internals.push ?? { vapidPublicKey: () => '', count: () => 0, subscribe: async () => false, unsubscribe: async () => false },
+    log: logger,
+  });
+  disposers.push(disposeRpc);
+
+  // 同源提供 Service Worker（Web Push 必需）
+  try {
+    const removeSw = ctx.webServer.register({
+      kind: 'exact',
+      path: '/pocket-sw.js',
+      handler: async (req, res) => {
+        res.writeHead(200, { 'content-type': 'application/javascript', 'cache-control': 'no-cache' });
+        res.end(await swScript());
+      },
+    });
+    disposers.push(removeSw);
+  } catch (err) {
+    logger.error('dsh-pocket: sw route register failed | SW 路由注册失败: %s', err?.message ?? err);
+  }
+
+  // Agent 回合结束/出错 → 推送通知（有订阅才发）
+  const onSessionEvent = (session, event) => {
+    if (event?.type !== 'turn/end') return;
+    const reason = event?.data?.reason ?? event?.reason;
+    if (!reason) return;
+    void pushPromise.then(async (push) => {
+      try {
+        if (reason.kind === 'error') {
+          await push.notify({ title: '❌ 任务失败 | Task failed', body: String(reason.error?.message ?? '').slice(0, 120) || 'Agent 执行出错', url: '/' });
+        } else if (reason.kind === 'completed') {
+          await push.notify({ title: '✅ 任务完成 | Task done', body: 'Agent 已完成任务，点开查看结果', url: '/' });
+        }
+      } catch (err) {
+        logger.error('dsh-pocket: push send failed | 推送发送失败: %s', err?.message ?? err);
+      }
+    });
+  };
+  const offSession = ctx.on('session/event', onSessionEvent);
+  disposers.push(offSession);
 
   // 代理随插件自动启动（局域网二维码开箱即用，零配置）
   void service.startProxy().then((proxy) => {
@@ -35,9 +93,9 @@ export function apply(ctx, config = {}, internals = {}) {
   });
 
   ctx.effect(() => async () => {
-    disposeRpc();
+    for (const d of disposers.reverse()) { try { d(); } catch { /* 忽略 */ } }
     await service.dispose();
-  }, 'dsh-pocket: stop proxy and tunnel');
+  }, 'dsh-pocket: stop proxy, tunnel and push');
 }
 
 export { name, inject };

package/lib/pocket-sw.js

@@ -0,0 +1,32 @@
+// dsh-pocket Service Worker（经 webServer 同源提供：/pocket-sw.js）
+// 职责：接收推送 → 显示通知；点击通知 → 聚焦/打开 DSH 页面。
+const ICON = '/favicon.svg';
+
+self.addEventListener('push', (event) => {
+  let data = {};
+  try {
+    data = event.data ? event.data.json() : {};
+  } catch { /* 非 JSON 载荷忽略 */ }
+  event.waitUntil(
+    self.registration.showNotification(data.title || 'DSH Pocket', {
+      body: data.body || '',
+      icon: ICON,
+      badge: ICON,
+      tag: data.tag || 'dsh-pocket',
+      data: { url: data.url || '/' },
+    }),
+  );
+});
+
+self.addEventListener('notificationclick', (event) => {
+  event.notification.close();
+  const url = event.notification.data?.url || '/';
+  event.waitUntil(
+    self.clients.matchAll({ type: 'window', includeUncontrolled: true }).then((windowClients) => {
+      for (const client of windowClients) {
+        if ('focus' in client) return client.focus();
+      }
+      return self.clients.openWindow(url);
+    }),
+  );
+});

package/lib/push.mjs

@@ -0,0 +1,122 @@
+// dsh-pocket Web Push 服务（Agent 跑完/出错 → 手机推送通知，即使没开页面）
+//
+// 原理：浏览器 Push API（Service Worker + pushManager.subscribe）把订阅
+// 交给我们，我们在 dsh web 进程内用 web-push（VAPID 认证 + RFC 8030 协议）
+// 直接推送到浏览器厂商的推送服务（Chrome→FCM / Firefox→Mozilla / Safari→APNs）。
+// 免费、无需第三方账号；VAPID 密钥与订阅存本机。
+//
+// ⚠️ 硬性前提：Web Push 只在**安全上下文**可用（HTTPS 或 localhost）。
+//    - 公网隧道 https://xxx.trycloudflare.com ✅（人在外面的主场景）
+//    - 桌面 localhost:3080 ✅
+//    - 局域网 http://192.168.x.x ❌（明文 HTTP 没有 Push API）
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+const DATA_REL = join('dsh-pocket', 'push');
+const VAPID_FILE = 'vapid.json';
+const SUBS_FILE = 'subscriptions.json';
+
+function defaultWebPush() {
+  // 动态 require（web-push 是 CJS）
+  return require('web-push');
+}
+
+/**
+ * 创建推送服务。
+ * @param {object} opts
+ * @param {string} [opts.home]      $DSH_HOME（默认 ~/.dsh）
+ * @param {object} [opts.webpush]   web-push 库（测试注入 stub）
+ * @param {string} [opts.subject]   VAPID subject（mailto:）
+ * @param {object} [opts.internals] 测试注入：mkdir/write/read
+ * @returns {Promise<PushService>}
+ */
+export async function createPushService({
+  home,
+  webpush = defaultWebPush(),
+  subject = 'mailto:shaobeichen@outlook.com',
+  internals = {},
+} = {}) {
+  const dshHome = home ?? process.env.DSH_HOME ?? join(homedir(), '.dsh');
+  const dir = join(dshHome, DATA_REL);
+  const vapidPath = join(dir, VAPID_FILE);
+  const subsPath = join(dir, SUBS_FILE);
+  const mkdirFn = internals.mkdir ?? mkdir;
+  const read = internals.read ?? readFile;
+  const write = internals.write ?? writeFile;
+
+  await mkdirFn(dir, { recursive: true });
+
+  // VAPID 密钥：生成一次，持久化
+  let vapid;
+  try {
+    vapid = JSON.parse(await read(vapidPath, 'utf8'));
+  } catch {
+    vapid = webpush.generateVAPIDKeys();
+    await write(vapidPath, JSON.stringify(vapid, null, 2) + '\n', { mode: 0o600 });
+  }
+  webpush.setVapidDetails(subject, vapid.publicKey, vapid.privateKey);
+
+  // 订阅集合：endpoint → subscription
+  let subs = new Map();
+  try {
+    for (const s of JSON.parse(await read(subsPath, 'utf8')) ?? []) {
+      if (s?.endpoint) subs.set(s.endpoint, s);
+    }
+  } catch { /* 空开始 */ }
+
+  const persist = async () => {
+    await write(subsPath, JSON.stringify([...subs.values()], null, 2) + '\n', { mode: 0o600 });
+  };
+
+  return {
+    vapidPublicKey: () => vapid.publicKey,
+    count: () => subs.size,
+
+    /** 记录浏览器订阅。 */
+    async subscribe(subscription) {
+      if (!subscription?.endpoint || !subscription?.keys) return false;
+      subs.set(subscription.endpoint, subscription);
+      await persist();
+      return true;
+    },
+
+    /** 按 endpoint 取消订阅。 */
+    async unsubscribe(endpoint) {
+      const removed = subs.delete(endpoint);
+      if (removed) await persist();
+      return removed;
+    },
+
+    /**
+     * 推送通知到所有订阅；失效订阅自动清理。
+     * @param {object} opts
+     * @param {string} opts.title
+     * @param {string} [opts.body]
+     * @param {string} [opts.url]     点击通知打开的地址（默认 /）
+     * @param {object} [opts.data]     额外载荷
+     */
+    async notify({ title, body = '', url = '/', data = {} }) {
+      if (subs.size === 0) return 0;
+      const payload = JSON.stringify({ title, body, url, ...data });
+      let sent = 0;
+      for (const [endpoint, sub] of [...subs.entries()]) {
+        try {
+          await webpush.sendNotification(sub, payload, { TTL: 600 });
+          sent += 1;
+        } catch (err) {
+          // 410 Gone / 404 = 订阅失效，清理
+          const code = err?.statusCode;
+          if (code === 410 || code === 404) {
+            subs.delete(endpoint);
+            await persist();
+          }
+        }
+      }
+      return sent;
+    },
+
+    async dispose() { /* 无长连接需要清理 */ },
+  };
+}

package/lib/web-rpc.js

@@ -17,12 +17,12 @@ function fail(code, message) {
 }
 
 /** 注册 /dsh-pocket 逻辑通道（仅本机 loopback 可调）。 */
-export function installPocketRpc(ctx, { service, log = console }) {
+export function installPocketRpc(ctx, { service, push, log = console }) {
   if (!ctx?.connection?.rpc?.handle) {
     log.warn?.('dsh-pocket: DSH Host Connection RPC unavailable — settings tab disabled | 无 Connection RPC，设置页不可用');
     return () => {};
   }
-  return ctx.connection.rpc.handle(POCKET_RPC_CHANNEL, async (endpoint, _payload = {}, signal) => {
+  return ctx.connection.rpc.handle(POCKET_RPC_CHANNEL, async (endpoint, payload = {}, signal) => {
     if (signal?.aborted) return fail('cancelled', 'The request was cancelled.');
 
     try {
@@ -37,10 +37,24 @@ export function installPocketRpc(ctx, { service, log = console }) {
         service.stopTunnel();
         return ok(redactStatus(await service.status()));
       }
+      if (endpoint === POCKET_ENDPOINTS.pushVapidKey) {
+        return ok({ publicKey: push.vapidPublicKey() });
+      }
+      if (endpoint === POCKET_ENDPOINTS.pushSubscribe) {
+        const added = await push.subscribe(payload?.subscription);
+        return ok({ subscribed: added, count: push.count() });
+      }
+      if (endpoint === POCKET_ENDPOINTS.pushUnsubscribe) {
+        const removed = await push.unsubscribe(payload?.endpoint);
+        return ok({ removed, count: push.count() });
+      }
+      if (endpoint === POCKET_ENDPOINTS.pushStatus) {
+        return ok({ enabled: push.count() > 0, count: push.count() });
+      }
       return fail('bad-request', `Unknown endpoint: ${endpoint}`);
     } catch (err) {
       log.error?.('dsh-pocket: rpc %s failed | RPC 失败: %s', endpoint, err?.message ?? err);
-      return fail('internal', err?.message ?? String(err));
+      return fail('bad-request', err?.message ?? String(err));
     }
   }, { authority: 'loopback' });
 }

package/package.json

@@ -27,7 +27,8 @@
   },
   "dependencies": {
     "qrcode": "^1.5.4",
-    "qrcode-terminal": "^0.12.0"
+    "qrcode-terminal": "^0.12.0",
+    "web-push": "^3.6.7"
   },
   "devDependencies": {
     "esbuild": "^0.25.9",
@@ -39,7 +40,7 @@
   "engines": {
     "node": ">=22"
   },
-  "license": "MIT",
+  "license": "GPL-2.0",
   "keywords": [
     "deepseek-harness",
     "dsh",
@@ -76,5 +77,5 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "version": "1.0.0"
+  "version": "1.0.2"
 }