dsh-mobile 0.6.6 → 0.6.7

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 Notable changes are recorded here. GitHub Releases provide the downloadable packages and generated commit notes.
 
+## 0.6.7 - 2026-10-14
+
+- Add optional `cpolarSubdomain` and `cpolarRegion` profile settings for a reserved cpolar address. Omitted or blank values keep provider defaults; only the validated HTTPS origin reported by cpolar is used. Existing pairing and authorization checks are unchanged. [Configuration guide](docs/CPOLAR_SUBDOMAIN.en.md).
+- Include complete profile override examples and regressions for configuration-to-process arguments, invalid settings and provider startup failures. This feature does not require an Android App update.
+- Improve narrow-screen sidebar interaction and scrolling with larger panel/footer content. Keep the Workspace list usable and footer actions reachable without enabling the shell overlay as a full-page click target.
+- Load mobile customizations only on their authenticated Gateway entry, including the stock diagnostic page. Add deduplicated Chinese, English and Italian failure/recovery messages, pause unauthorized extension streams, and retain loaded styles and page state through temporary failures without weakening authentication.
+- Ignore a cancelled manifest request before it can clear newer extensions. Preserve the existing custom-file and extension size limits, and keep preview Back handling separate from Gateway API loading.
+- Clarify `/mobile` and both READMEs: detected files are not proof of page activation; ordinary DSH login or phone-sized preview does not establish mobile pairing. Thanks @Dantezcx for the detailed reports in [#209](https://github.com/saya-ch/dsh-mobile/issues/209) and [#210](https://github.com/saya-ch/dsh-mobile/issues/210).
+- Thanks @GavinQiEr for the request in [#207](https://github.com/saya-ch/dsh-mobile/issues/207) and implementation in [#208](https://github.com/saya-ch/dsh-mobile/pull/208); the original author commit is retained alongside maintainer corrections.
+
 ## Unreleased Android changes
 
 - Prefer the system Photo Picker on Android 13+ for supported image requests, with document selection for other requests or an unavailable picker. Preserve multi-selection, MIME filtering and selected URI results without adding storage permission or forcing a vendor gallery.

package/CONTRIBUTORS.md

@@ -4,6 +4,12 @@ GitHub 的 [Contributors 图表](https://github.com/saya-ch/dsh-mobile/graphs/co
 
 GitHub's Contributors graph counts commits on the default branch; issue reports and PR proposals cannot be manually added to it. This page credits community members by how they contributed, through 2026-10-14. The repository maintainer and automated dependency updates remain visible in GitHub's history.
 
+## 0.6.7 代码贡献 / Code contributions in 0.6.7
+
+[@GavinQiEr](https://github.com/GavinQiEr) 在 [#207](https://github.com/saya-ch/dsh-mobile/issues/207) 提出 cpolar 固定子域名支持，并在 [#208](https://github.com/saya-ch/dsh-mobile/pull/208) 提供配置、启动参数和文档实现。[#211](https://github.com/saya-ch/dsh-mobile/pull/211) 的整合保留原作者提交 [`8dd7574`](https://github.com/saya-ch/dsh-mobile/commit/8dd75749d3823aecafdb6f5d9faccf674577e7b1)，并追加维护者修正，纳入 0.6.7。
+
+[@GavinQiEr](https://github.com/GavinQiEr) requested reserved cpolar subdomains in [#207](https://github.com/saya-ch/dsh-mobile/issues/207) and implemented the configuration, process arguments and guides in [#208](https://github.com/saya-ch/dsh-mobile/pull/208). Integration [#211](https://github.com/saya-ch/dsh-mobile/pull/211) retains author commit [`8dd7574`](https://github.com/saya-ch/dsh-mobile/commit/8dd75749d3823aecafdb6f5d9faccf674577e7b1) alongside maintainer corrections for 0.6.7.
+
 ## 0.6.4 代码贡献 / Code contributions in 0.6.4
 
 [@abworks-dev](https://github.com/abworks-dev) 的 [#200](https://github.com/saya-ch/dsh-mobile/pull/200) 提供窄屏输入栏包装层与按钮点击区域的尺寸修正及回归测试，代码已随 0.6.4 发布；随后以合并提交 [`71754e5`](https://github.com/saya-ch/dsh-mobile/commit/71754e5191d3e9eadfedad16982e144491272f26) 保留原作者提交 [`03604ae`](https://github.com/saya-ch/dsh-mobile/commit/03604ae7623ceb42090ff4c4ed0e84d4aff7144a)。这次历史补全不改变已发布的功能或标签。
@@ -58,6 +64,8 @@ GitHub's Contributors graph counts commits on the default branch; issue reports
 
 ## 问题反馈与建议 / Issue reports and ideas
 
+感谢 [@Dantezcx](https://github.com/Dantezcx) 在 [#209](https://github.com/saya-ch/dsh-mobile/issues/209) 和 [#210](https://github.com/saya-ch/dsh-mobile/issues/210) 提供侧栏命中、短屏布局和定制资源加载的详细诊断。 / Thanks [@Dantezcx](https://github.com/Dantezcx) for the detailed sidebar hit-testing, short-viewport and customization-loading diagnostics in [#209](https://github.com/saya-ch/dsh-mobile/issues/209) and [#210](https://github.com/saya-ch/dsh-mobile/issues/210).
+
 感谢 [@xhwxt](https://github.com/xhwxt) 在 [#203](https://github.com/saya-ch/dsh-mobile/pull/203) 中提出文档选择器改进方案，以及 [@Void-LifeStream](https://github.com/Void-LifeStream) 在 [#205](https://github.com/saya-ch/dsh-mobile/issues/205) 中提供附件选择与回传问题的详细反馈。
 
 Thanks [@xhwxt](https://github.com/xhwxt) for the document-picker proposal in [#203](https://github.com/saya-ch/dsh-mobile/pull/203), and [@Void-LifeStream](https://github.com/Void-LifeStream) for the detailed attachment-selection and delivery report in [#205](https://github.com/saya-ch/dsh-mobile/issues/205).

package/README.en.md

@@ -31,7 +31,7 @@
 
 > DSH Mobile is a DeepSeek Harness community plugin; the native app supports Android only.
 >
-> **Current stable release: 0.6.6**. Fix captured images not reaching the DSH attachment draft, and improve cancellation and late-result handling in browser file selection. [Changelog](CHANGELOG.md) · [Release downloads](https://github.com/saya-ch/dsh-mobile/releases/tag/v0.6.6).
+> **Current stable release: 0.6.7**. Add reserved cpolar subdomain configuration, improve narrow-screen sidebar and overlay interaction, and clarify mobile customization ownership, failures and recovery. [Changelog](CHANGELOG.md) · [Release downloads](https://github.com/saya-ch/dsh-mobile/releases/tag/v0.6.7).
 >
 > **Version policy**: since plugin **0.6.2**, the Android app and plugin use independent version numbers and releases. Their numbers do not need to match, and a plugin update does not imply an app update. [Compatibility notes](#compatibility).
 
@@ -212,7 +212,9 @@ It can also drive computer capabilities the phone can use, like reading the mach
 /mobile give the phone a cyberpunk-style computer monitor panel that shows live CPU, memory, and disk usage
 ```
 
-Two kinds of changes are supported: the phone UI itself (theme, layout, buttons), and computer capabilities the phone can use (browsing computer files, running programs on the computer). `/mobile` hands the request to the DSH agent, which edits files under the local DSH configuration directory (`$DSH_HOME/mobile-access/`); the phone client applies them automatically. UI changes live in `mobile.css`/`mobile.js`. Computer capabilities come from extensions under `extensions/`, whose `host.mjs` runs with the local user's privileges on the computer. DeepSeek Harness source is not modified.
+Two kinds of changes are supported: the phone UI itself (theme, layout, buttons), and computer capabilities the phone can use (browsing computer files, running programs on the computer). `/mobile` hands the request to the DSH agent, which edits files under the local DSH configuration directory (`$DSH_HOME/mobile-access/`); paired mobile pages automatically check and apply them. UI changes live in `mobile.css`/`mobile.js`. Computer capabilities come from extensions under `extensions/`, whose `host.mjs` runs with the local user's privileges on the computer. DeepSeek Harness source is not modified.
+
+Open customizations through the **Mobile Access pairing entry**. Opening an ordinary DSH page or selecting a phone-sized browser viewport is not mobile pairing, and a file's presence does not establish that the current page loaded it. If extension requests return `401`, check the entry and pairing state; do not enable anonymous access or share Cookies or Tokens.
 
 Extension manifests, scripts, styles, and assets are revisioned. When the plugin observes a `/mobile` or extension-file change, it notifies authenticated phones to refresh immediately; 45-second visible and 5-minute hidden checks remain only as recovery fallbacks. A failed Host staging pass keeps the current version; if the Host has changed but the new phone UI cannot activate, that extension closes and retries instead of mixing generations.
 
@@ -321,7 +323,7 @@ Selection priority is device choice → computer defaults → plugin configurati
 | Android app | Everyday use | Separate Local and Remote entries at first pairing; LAN discovery, system trust for public remote certificates, and app-pinned CA for the self-signed FRP entry |
 | Mobile browser | Temporary or cross-platform | Open the HTTPS origin shown by Mobile Access; a private LAN certificate may need confirmation, while a public remote certificate should not warn |
 
-The Android app is a thin Kotlin WebView shell and contains no frontend copy; mobile browsers load the same page. Developers can append `?frontend=stock` to an authenticated mobile URL to compare the stock layout. This diagnostic entry bypasses mobile enhancements and module selection; some API operations may be rejected, so it does not replace normal mobile access. See [skins and mobile layout](docs/SKIN_COMPATIBILITY.en.md).
+The Android app is a thin Kotlin WebView shell and contains no frontend copy; mobile browsers load the same page. Developers can append `?frontend=stock` to an authenticated mobile URL to diagnose boot and layout behavior. This entry skips dedicated mobile boot rewriting and module selection, but installed client adaptation and authenticated customizations may still apply. It is not a plugin-free control; some API operations may be rejected, so it does not replace normal mobile access. See [skins and mobile layout](docs/SKIN_COMPATIBILITY.en.md).
 
 In 0.5.5, the dedicated mobile page synchronously loads the authenticated, same-origin `/mobile-access/compat.js` before the first DSH boot script. This bundled core-js compatibility layer supplies `Iterator` / Iterator helpers to WebViews that lack them, preventing the startup error `Iterator is not defined`. It uses feature detection to preserve or repair native helpers, needs no CDN, and does not weaken CSP. The desktop and `?frontend=stock` pages do not load this gateway script.
 

package/README.md

@@ -31,7 +31,7 @@
 
 > DSH Mobile 是 DeepSeek Harness 社区插件，原生 App 仅支持 Android。
 >
-> **当前正式版本：0.6.6**。修复拍照图片无法进入 DSH 附件草稿的问题，改善浏览器文件选择的取消与迟到结果处理。[更新记录](CHANGELOG.md) · [版本下载](https://github.com/saya-ch/dsh-mobile/releases/tag/v0.6.6)。
+> **当前正式版本：0.6.7**。支持 cpolar 预留子域名配置，改善窄屏侧栏与浮层交互，并补全移动定制的入口识别、失败提示和恢复处理。[更新记录](CHANGELOG.md) · [版本下载](https://github.com/saya-ch/dsh-mobile/releases/tag/v0.6.7)。
 >
 > **版本说明**：自插件 **0.6.2** 起，Android App 与插件独立编号、独立发布，版本号无需一致；插件升级不代表 App 需要同步升级。[兼容说明](#兼容性)。
 
@@ -212,7 +212,9 @@ Tailscale Funnel 覆盖范围广，但在中国大陆网络下可能不稳定。
 /mobile 为手机端添加赛博朋克风格的电脑监控面板，实时显示电脑的 CPU、内存和磁盘占用
 ```
 
-`/mobile` 把需求交给 DSH 对话中的 agent，由它直接修改本机 `$DSH_HOME/mobile-access/` 下的文件，保存后手机端自动生效。改动分两类：界面和交互在 `mobile.css`/`mobile.js`；需要电脑能力时用 `extensions/` 下的扩展，其 `host.mjs` 以本机用户权限在电脑上运行。不修改 DeepSeek Harness 源码。
+`/mobile` 把需求交给 DSH 对话中的 agent，由它直接修改本机 `$DSH_HOME/mobile-access/` 下的文件，已配对的移动页面会自动检查并应用。改动分两类：界面和交互在 `mobile.css`/`mobile.js`；需要电脑能力时用 `extensions/` 下的扩展，其 `host.mjs` 以本机用户权限在电脑上运行。不修改 DeepSeek Harness 源码。
+
+定制需要从 **移动访问的配对入口**进入。直接打开普通 DSH 网页或调整浏览器为手机视口，不等于完成移动配对；文件存在也不代表当前页面已加载。若扩展接口返回 `401`，先核对入口与配对状态，不要开放匿名访问或公开 Cookie、Token。
 
 扩展清单及其脚本、样式和资源按版本标识刷新。插件监听到 `/mobile` 或扩展文件变化后，会通过已认证连接通知手机立即更新；页面可见时每 45 秒、隐藏时每 5 分钟的检查只作为断线兜底。Host 暂存失败会继续使用现有版本；若 Host 已更新但新手机界面激活失败，则关闭该扩展并自动重试，避免混用新旧能力。
 
@@ -321,7 +323,7 @@ excludedClientModules:
 | Android App | 日常使用 | 首次配对时分别提供局域网与远程入口；局域网自动发现，公开远程证书由系统验证，自签 FRP 入口由 App 固定 CA |
 | 手机浏览器 | 临时或跨平台访问 | 打开“移动访问”卡片显示的 HTTPS 地址；局域网私有证书可能需要手动确认，公开远程证书不应出现警告 |
 
-Android App 只是 Kotlin WebView 薄壳，不内置另一份网页；手机浏览器访问的是同一页面。开发者可在已认证移动地址后追加 `?frontend=stock` 对照原生布局；该诊断入口绕过移动增强和模块选择，部分 API 操作可能被拒绝，不能代替正常移动入口。详见[皮肤与移动布局](docs/SKIN_COMPATIBILITY.md)。
+Android App 只是 Kotlin WebView 薄壳，不内置另一份网页；手机浏览器访问的是同一页面。开发者可在已认证移动地址后追加 `?frontend=stock` 诊断启动与布局行为；该入口跳过专用移动启动改写和模块选择，但仍可能加载客户端移动适配及已认证定制，并非不含插件的对照页。部分 API 操作可能被拒绝，不能代替正常移动入口。详见[皮肤与移动布局](docs/SKIN_COMPATIBILITY.md)。
 
 0.5.5 的专用移动页面会在 DSH 的第一个启动脚本之前，同步加载经网关鉴权的同源 `/mobile-access/compat.js`，为缺少 `Iterator` / Iterator helpers 的 WebView 提供随插件打包的 core-js 兼容实现，避免启动时出现 `Iterator is not defined`。兼容层按能力检测保留或修正原生 helper，不依赖 CDN，也不会放宽 CSP；桌面页面与 `?frontend=stock` 页面不会加载这个网关脚本。
 

package/docs/CPOLAR_SUBDOMAIN.en.md

@@ -0,0 +1,81 @@
+# cpolar reserved subdomain
+
+[中文指南](CPOLAR_SUBDOMAIN.md)
+
+> Requires plugin **0.6.7 or later**; versions through 0.6.6 do not read these two settings. No Android App update is required.
+
+cpolar assigns a temporary public address by default. Reserving a subdomain lets an account request a fixed address, reducing bookmark updates and re-pairing after tunnel restarts. A fixed address does not keep the tunnel permanently online or remove re-pairing requirements after credentials expire or a device is revoked.
+
+The public entry still reaches the DSH Mobile Gateway with HTTPS, device pairing and authorization checks; it does not expose the ordinary DSH WebServer directly.
+
+## Prerequisites
+
+1. Check that your cpolar plan supports reserving a secondary subdomain. The [official tutorial](https://www.cpolar.com/blog/cpolar-quick-start-tutorial-raspberry-pi-series) uses Basic plans or above; your account dashboard is the authority for current eligibility, available regions and naming rules.
+2. Reserve a name under **Reserved → Reserve a secondary subdomain** in the [cpolar dashboard](https://dashboard.cpolar.com), and record the selected region.
+3. Install the component and save the Authtoken under **Mobile access → Remote → cpolar** in DSH.
+
+The region must match the reservation. The official command example uses `cn_vip`, but do not copy it for a reservation in another region; confirm other identifiers against cpolar's current instructions. This guide does not maintain a fixed region or domain-suffix mapping.
+
+## Configuration
+
+> The panel has no subdomain or region fields yet. Edit the current DSH profile's `cordis.patch.yml` after making a backup; do not edit generated `cordis.yml` or the plugin-managed `cpolar.yml`.
+
+Find the current profile directory, for example `$DSH_HOME/profiles/<profile>/cordis.patch.yml`. Update the existing `mobile-access` configuration override. If none exists, add the override below to a profile that already loads the DSH Mobile bundle. **Do not create a second `mobile-access` instance or copy the bundle's `insert` list again.**
+
+The DSH loader replaces an entry's entire `config`, rather than merging individual keys. Do not paste an override containing only the subdomain and region. This example includes every configuration field from this repository's standard bundle, followed by the two new settings; **it is only suitable for a standard installation without custom configuration for this entry**:
+
+```yaml
+- id: mobile-access
+  name: dsh-mobile
+  config:
+    setupFile: !!js dshHomePath('mobile-access/setup.json')
+    stateFile: !!js dshHomePath('mobile-access/devices.json')
+    controlFile: !!js dshHomePath('mobile-access/control.json')
+    customCssFile: !!js dshHomePath('mobile-access/mobile.css')
+    customScriptFile: !!js dshHomePath('mobile-access/mobile.js')
+    initiallyEnabled: false
+    listenHost: 127.0.0.1
+    listenPort: 3443
+    allowedCidrs: [127.0.0.0/8]
+    tls:
+      mode: disabled
+    cpolarSubdomain: your-reserved-name
+    cpolarRegion: cn_vip
+```
+
+If you already customize paths, listeners, TLS or other settings, **keep your current complete `config` and add only these two fields inside it**. Replacing it with the example can change data locations or access settings. Do not add the Authtoken here; save it through the panel as before.
+
+| Field | Value |
+| --- | --- |
+| `cpolarSubdomain` | The reserved name itself, not a full domain, HTTPS address or path. Omitted, empty or whitespace-only values do not request a fixed name. |
+| `cpolarRegion` | The region identifier matching your reservation; `cn_vip` above is only an official example. Omitted, empty or whitespace-only values do not send a region argument, leaving routing to cpolar; specify the matching region for a fixed reservation. |
+
+Leading and trailing whitespace is removed. The plugin only bounds the requested name's syntax: it starts with a letter or digit, contains letters, digits, `.`, `_`, `-`, and is at most 63 characters long. This is not a DNS-label specification or a guarantee of server acceptance. The account, region and cpolar's actual rules determine whether the reservation is valid. The [official subdomain instructions](https://www.cpolar.com/docs#configure-secondary-subdomain) and tutorial describe the `-subdomain` and `-region` arguments.
+
+After checking that no tasks are running, quit DSH completely and reopen it, then connect under **Mobile access → Remote → cpolar**. Use the actual HTTPS address shown by the panel; do not construct a domain suffix yourself.
+
+## Verification and pairing
+
+1. Compare the public hostname displayed by the panel with your account's reservation.
+2. From the external network used by the phone, open `https://<hostname-shown-by-the-panel>/mobile-access/health`, check the HTTPS certificate and confirm a `{"ok":true}` response. This is a basic connectivity check; an HTTP `401`, `301`, or an accessible webpage alone does not identify your DSH gateway.
+3. When the target computer needs confirmation, compare the `instanceId` returned by that address's `/mobile-access/discovery` with the local gateway's value. Do not publish full discovery responses, pairing codes or credentials.
+4. Choose **Remote** in the Android App and connect using the remote pairing QR code generated by the panel. Check that workspaces and conversations load and real-time connections work; the panel's connection diagnostics can also help. No model request is needed to check connectivity.
+
+Existing pairings are bound to an exact HTTPS Origin. Switching from a temporary address to a fixed address requires pairing once more. Afterwards the record remains usable while the address stays unchanged and authorization remains valid. A fixed domain does not prevent Token expiry, device revocation, certificate problems or provider outages.
+
+## Troubleshooting
+
+| Symptom | Checks and action |
+| --- | --- |
+| A temporary address is still displayed | Confirm that plugin 0.6.7 or later is running, the fields are inside the existing `mobile-access` entry's complete `config`, and DSH has fully restarted. Then check the account reservation and region; local configuration alone is not success. |
+| The plugin reports `cpolar subdomain is invalid` | Check the request syntax and 63-character limit above, using only the reserved name. Passing local syntax checks still does not ensure cpolar accepts it. |
+| The plugin reports `cpolar region is invalid` | The format starts with a lowercase letter, followed only by lowercase letters, digits or underscores, up to 32 characters. Also confirm the identifier is valid for the account reservation. |
+| cpolar rejects the name or fails to start | Check the current plan, account, reserved name and region; inspect the error and follow cpolar's current instructions. The plugin does not treat the requested value as a successfully returned public address. |
+| Health responds but workspaces do not load | Check pairing authorization and the actual WebSocket connection using connection diagnostics; a successful health request does not establish a working session. |
+| Data or listeners changed after editing | Check for omitted fields from the original complete `config`; restore the original paths and access settings from your backup. Do not delete pairing files. |
+
+## Security boundaries
+
+- These settings only append `-subdomain` and `-region` arguments to `cpolar http`; gateway pairing, TLS and device authorization are unchanged.
+- The plugin still uses only the public address actually reported by cpolar and validated by the plugin; the entered name does not become a trusted Origin on its own.
+- The Authtoken retains its existing private storage. The reserved name appears in the public domain and is not secret, but do not publish it together with Tokens, Cookies or pairing QR codes.

package/docs/CPOLAR_SUBDOMAIN.md

@@ -0,0 +1,81 @@
+# cpolar 固定子域名
+
+[English guide](CPOLAR_SUBDOMAIN.en.md)
+
+> 需要插件 **0.6.7 或更新版本**；0.6.6 及之前版本尚不读取这两个配置项。此功能不要求更新 Android App。
+
+cpolar 默认分配临时公网地址。账号预留子域名后，可请求使用固定地址，减少重启隧道后更新书签或重新配对的次数。固定地址不意味着隧道永远在线，也不取消设备凭据过期或撤销后的重新配对要求。
+
+公网入口仍由 DSH Mobile Gateway 处理，沿用 HTTPS、设备配对和授权检查；不是直接开放 DSH 的普通 WebServer。
+
+## 前置条件
+
+1. 确认 cpolar 套餐支持保留二级子域名。[官方教程](https://www.cpolar.com/blog/cpolar-quick-start-tutorial-raspberry-pi-series)以基础套餐及以上为例；当前资格、可用地区及命名规则以你的账号控制台为准。
+2. 在 [cpolar 控制台](https://dashboard.cpolar.com)的 **预留 → 保留二级子域名** 中保留名字，记录对应地区。
+3. 在 DSH **移动访问 → 远程 → cpolar** 中安装组件并保存 Authtoken。
+
+地区必须与预留记录一致。官方命令示例使用 `cn_vip`，但不要将它照抄到其他地区的预留记录；其他地区的配置值请按 cpolar 当前说明确认。本指南不提供固定地区或域名后缀对照表。
+
+## 配置
+
+> 面板暂时没有子域名和地区输入框，需要编辑当前 DSH profile 的 `cordis.patch.yml`。先备份；不要改生成的 `cordis.yml` 或插件管理的 `cpolar.yml`。
+
+找到当前 profile 目录，例如 `$DSH_HOME/profiles/<profile>/cordis.patch.yml`。修改已有的 `mobile-access` 配置覆盖条目；没有时，可在已加载 DSH Mobile bundle 的 profile 中添加下面的覆盖。**不要新增第二个 `mobile-access` 实例，也不要重新复制 bundle 的 `insert` 列表。**
+
+DSH 加载器会整体替换条目的 `config`，不是逐键合并。因此不能只粘贴子域名和地区两个字段。下面展示本仓库标准 bundle 的全部配置，再追加两个设置；**仅适用于尚未自定义该条目的标准安装**：
+
+```yaml
+- id: mobile-access
+  name: dsh-mobile
+  config:
+    setupFile: !!js dshHomePath('mobile-access/setup.json')
+    stateFile: !!js dshHomePath('mobile-access/devices.json')
+    controlFile: !!js dshHomePath('mobile-access/control.json')
+    customCssFile: !!js dshHomePath('mobile-access/mobile.css')
+    customScriptFile: !!js dshHomePath('mobile-access/mobile.js')
+    initiallyEnabled: false
+    listenHost: 127.0.0.1
+    listenPort: 3443
+    allowedCidrs: [127.0.0.0/8]
+    tls:
+      mode: disabled
+    cpolarSubdomain: your-reserved-name
+    cpolarRegion: cn_vip
+```
+
+已有自定义路径、监听、TLS 或其他设置时，**保留你当前的完整 `config`，只在其中添加这两个字段**；不要用示例覆盖它，否则可能改变数据位置或访问设置。无需在配置中填写 Authtoken，它仍通过面板保存。
+
+| 字段 | 填写内容 |
+| --- | --- |
+| `cpolarSubdomain` | 控制台预留的名字本身，不是完整域名、HTTPS 地址或路径。省略、空字符串或纯空白表示不请求固定名字。 |
+| `cpolarRegion` | 与预留记录匹配的地区标识；上例 `cn_vip` 只是官方示例。省略、空字符串或纯空白时不传地区参数，由 cpolar 决定线路；固定名字建议填写匹配地区。 |
+
+配置值会去除首尾空白。插件的名字检查仅限制请求格式：以字母或数字开头，只含字母、数字、`.`、`_`、`-`，长度不超过 63 字符；这不是 DNS 标签规范，也不代表 cpolar 服务端会接受。预留是否有效仍取决于账号、地区和 cpolar 的实际规则。[官方子域名配置说明](https://www.cpolar.com/docs#configure-secondary-subdomain)与教程说明了 `-subdomain`、`-region` 参数。
+
+确认没有正在运行的任务后，完整退出并重开 DSH，再在 **移动访问 → 远程 → cpolar** 中连接。连接后使用面板实际显示的 HTTPS 地址，不要自行拼接域名后缀。
+
+## 验证与配对
+
+1. 核对面板显示的公网主机名与账号预留记录一致。
+2. 从手机实际使用的外网打开 `https://<面板显示的主机名>/mobile-access/health`，检查 HTTPS 证书并确认响应为 `{"ok":true}`。这是基础连通性检查；单独的 HTTP `401`、`301` 或“网页能打开”不能证明请求到达你的 DSH。
+3. 若需确认目标电脑，比较该地址 `/mobile-access/discovery` 返回的 `instanceId` 与本机网关的值；不要公开完整 discovery 响应、配对码或凭据。
+4. 在 Android App 选择 **远程访问**，使用面板生成的远程配对二维码连接，确认工作区和会话可以读取、实时连接正常；也可查看面板的连接诊断。不需要发送模型请求来验证连通性。
+
+已有配对记录绑定精确 HTTPS Origin。由临时地址换成固定地址时，需要重新配对一次；以后地址保持不变且授权仍有效时可继续使用原记录。固定域名不会阻止 Token 过期、设备撤销、证书问题或提供方故障。
+
+## 常见问题
+
+| 现象 | 检查与处理 |
+| --- | --- |
+| 仍显示临时地址 | 确认插件为 0.6.7 或更新版本、字段位于已有 `mobile-access` 的完整 `config` 中，并已完整重启。再核对账号预留和地区，不要仅凭本地字段存在判断成功。 |
+| 插件报 `cpolar subdomain is invalid` | 检查前述请求格式和 63 字符上限，只填预留名字；符合本地格式仍可能被 cpolar 拒绝。 |
+| 插件报 `cpolar region is invalid` | 地区格式为小写字母开头，后续仅小写字母、数字或下划线，最多 32 字符；再按账号预留记录确认它确实有效。 |
+| cpolar 拒绝固定名字或无法启动 | 核对当前套餐、账号、预留名字和地区；查看错误信息并按 cpolar 当前说明处理。插件不会把请求值当成成功返回的公网地址。 |
+| 健康检查正常但工作区加载失败 | 继续检查配对授权和实际 WebSocket 连接，使用连接诊断；健康接口成功不等于完整会话可用。 |
+| 改配置后数据或监听异常 | 检查是否遗漏了原有完整 `config`，从备份恢复原路径与访问设置；不要删除配对文件。 |
+
+## 安全边界
+
+- 这两个设置只追加 `cpolar http` 的 `-subdomain` 与 `-region` 参数，不改变网关配对、TLS 或设备授权逻辑。
+- 插件仍只使用 cpolar 实际报告并校验通过的公网地址，不会把填写的名字直接当成可信 Origin。
+- Authtoken 保持原有私有存储方式；预留名字会出现在公网域名中，不是秘密，但不要连同 Token、Cookie 或配对二维码公开。

package/docs/README.md

@@ -8,6 +8,7 @@
 | --- | --- | --- |
 | 使用 Android App、了解返回键、权限与升级 | [App 手册](../apps/mobile/README.zh-CN.md) | [Android app](../apps/mobile/README.md) |
 | 使用固定 Cloudflare 域名，而非临时随机地址 | [命名隧道](CLOUDFLARE_TUNNEL.md) | [Named tunnel](CLOUDFLARE_TUNNEL.en.md) |
+| 请求 cpolar 账号已预留的固定子域名（0.6.7 起） | [固定子域名](CPOLAR_SUBDOMAIN.md) | [Reserved subdomain](CPOLAR_SUBDOMAIN.en.md) |
 | 在已有 VPS 上新部署 FRP 与 HTTPS 入口 | [自建 FRP](SELF_HOSTED_FRP.md) | [Self-hosted FRP](SELF_HOSTED_FRP.en.md) |
 | 复用已经运行的 frps，不自动修改服务器 | [接入既有 frps](ATTACH_EXISTING_FRPS.md) | [Existing frps](ATTACH_EXISTING_FRPS.en.md) |
 | 复用 Lucky、Nginx 或 Caddy 的公开 HTTPS 入口 | [自有反向代理](SELF_HOSTED_ORIGIN.md) | [Own reverse proxy](SELF_HOSTED_ORIGIN.en.md) |

package/docs/SKIN_COMPATIBILITY.en.md

@@ -14,7 +14,7 @@ If saving reports a dependency conflict, retain the required module or also dese
 
 - Identify the running plugin, App and skin versions; plugin and App versions need not match.
 - Omit the skin only on this device, reopen manually and compare the conversation, composer and sidebar. Recovery points to styles or mounting, not necessarily a network or pairing failure.
-- First compare the normal computer layout. Developers can also open `/?frontend=stock` on the authenticated mobile Origin for layout diagnosis. Gateway authentication and HTTPS checks remain, but mobile enhancements and module selection are bypassed; some API operations may be rejected. It is not a replacement for the normal mobile entry.
+- First compare the normal computer layout. Developers can also open `/?frontend=stock` on the authenticated mobile Origin to diagnose boot and layout behavior. Gateway authentication and HTTPS checks remain; this entry skips dedicated mobile boot rewriting and module selection, but installed client adaptation and authenticated customizations may still apply. It is not a plugin-free control; some API operations may be rejected, so it does not replace normal mobile access.
 - When stock has a background but mobile does not, inspect the skin's mounting container and fallback for other layouts. WebSocket approval, APK reinstallation or making every container transparent cannot guarantee a fix.
 - A see-through sidebar, unreadable text shadows and an empty trace need separate diagnosis, not a single missing-background explanation. For an empty trace, inspect the first client exception, actual layout dimensions and whether its module loaded. A static screenshot does not distinguish rendering failure, occlusion and connection failure.
 

package/docs/SKIN_COMPATIBILITY.md

@@ -14,7 +14,7 @@ DSH Mobile 在已认证的移动页面中使用专用根布局，继续渲染 DS
 
 - 先核对正在运行的插件、App 和皮肤版本；插件与 App 版本不必相同。
 - 只在本设备不加载皮肤，手动重新打开后比较会话、输入栏和侧栏。恢复正常说明需要检查双方样式与挂载位置，不表示网络或配对失效。
-- 先与电脑上的原生布局对照。开发者还可在已认证移动 Origin 打开 `/?frontend=stock` 作布局诊断；它保留 Gateway 认证与 HTTPS 检查，但绕过移动增强和模块选择，部分 API 操作可能被拒绝，不能代替正常移动入口。
+- 先与电脑上的原生布局对照。开发者还可在已认证移动 Origin 打开 `/?frontend=stock` 作启动与布局诊断；它保留 Gateway 认证与 HTTPS 检查，跳过专用移动启动改写和模块选择，但仍可能加载客户端移动适配及已认证定制，并非不含插件的对照页。部分 API 操作可能被拒绝，不能代替正常移动入口。
 - 若原生布局有背景而移动布局没有，检查皮肤背景的挂载容器及其对非原生布局的回退逻辑；单纯放行 WebSocket、重装 APK 或把全部容器设为透明不能保证修复。
 - 侧栏透底、文字阴影难读和轨迹空白应分别排查，不能都归为“少了一张背景图”。轨迹空白时还需检查首个客户端异常、实际布局尺寸和是否加载了相应模块；仅从静态截图不能判断是渲染异常、遮挡还是连接问题。
 

package/lib/cli.js

@@ -603,6 +603,8 @@ Object.freeze({
 	assetBytes: 33554432,
 	assetDepth: 8
 });
+//#endregion
+//#region src/extensions.ts
 /** A controlled business failure returned by an extension action or route. */
 var MobileExtensionError = class extends Error {
 	code;