@hyprnos/dsh-remote-plugin 0.0.0-stage → 0.8.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (210) hide show
  1. package/README.en.md +61 -0
  2. package/README.md +60 -2
  3. package/apk/dsh-remote.apk +0 -0
  4. package/approval-summary.mjs +115 -0
  5. package/client.js +197 -0
  6. package/cordis.patch.yml +5 -0
  7. package/doctor-skill.mjs +99 -0
  8. package/doctor-target.mjs +24 -0
  9. package/file-delivery.mjs +84 -0
  10. package/gateway-stats.cjs +501 -0
  11. package/gateway.cjs +8451 -0
  12. package/index.mjs +1784 -0
  13. package/insights.mjs +111 -0
  14. package/market.mjs +86 -0
  15. package/package.json +71 -4
  16. package/peak-reminders.mjs +50 -0
  17. package/plugin-center.mjs +777 -0
  18. package/plugin-transaction.mjs +300 -0
  19. package/public/activity.js +188 -0
  20. package/public/admin.html +820 -0
  21. package/public/admin.js +1167 -0
  22. package/public/announcement-forms.js +89 -0
  23. package/public/announcements.json +464 -0
  24. package/public/app.js +8826 -0
  25. package/public/approval-records.js +301 -0
  26. package/public/approval-summary.js +78 -0
  27. package/public/build.json +5 -0
  28. package/public/cache-upgrade.js +51 -0
  29. package/public/chat-copy.js +59 -0
  30. package/public/chat-files.js +87 -0
  31. package/public/desktop/desktop.css +816 -0
  32. package/public/desktop/desktop.html +871 -0
  33. package/public/desktop/desktop.js +4548 -0
  34. package/public/desktop/i18n.js +85 -0
  35. package/public/diagnostics.js +203 -0
  36. package/public/doctor-entry.js +94 -0
  37. package/public/doctor.css +205 -0
  38. package/public/doctor.js +769 -0
  39. package/public/donate.png +0 -0
  40. package/public/e2ee-transport.js +219 -0
  41. package/public/extensions.css +109 -0
  42. package/public/extensions.js +215 -0
  43. package/public/file-inbox.css +66 -0
  44. package/public/file-inbox.js +289 -0
  45. package/public/genui.css +8 -0
  46. package/public/genui.js +254 -0
  47. package/public/history.js +304 -0
  48. package/public/i18n.js +57 -0
  49. package/public/icon.svg +12 -0
  50. package/public/image-cache.js +141 -0
  51. package/public/image-preview.js +290 -0
  52. package/public/index.html +1548 -0
  53. package/public/insights.css +28 -0
  54. package/public/insights.js +290 -0
  55. package/public/jsqr.min.js +10104 -0
  56. package/public/lan-discovery.js +94 -0
  57. package/public/link-check.js +109 -0
  58. package/public/manifest.webmanifest +16 -0
  59. package/public/md.js +333 -0
  60. package/public/morphicons-init.js +41 -0
  61. package/public/motion.js +557 -0
  62. package/public/network.js +100 -0
  63. package/public/onboarding.css +36 -0
  64. package/public/onboarding.js +253 -0
  65. package/public/operations.js +141 -0
  66. package/public/permission-presets.js +159 -0
  67. package/public/plugin-center.css +120 -0
  68. package/public/plugin-center.js +666 -0
  69. package/public/plugin-icon.svg +5 -0
  70. package/public/plugin.html +68 -0
  71. package/public/plugin.js +211 -0
  72. package/public/qrcode.min.js +2297 -0
  73. package/public/relay-autopair.js +251 -0
  74. package/public/relay-devices.js +80 -0
  75. package/public/relay-settings.css +24 -0
  76. package/public/relay-settings.js +194 -0
  77. package/public/remote-state.js +27 -0
  78. package/public/remote-ui.css +148 -0
  79. package/public/remote-ui.js +243 -0
  80. package/public/session-deck.css +79 -0
  81. package/public/session-deck.js +180 -0
  82. package/public/session-presets.js +47 -0
  83. package/public/setup.css +18 -0
  84. package/public/setup.js +213 -0
  85. package/public/sha256.js +119 -0
  86. package/public/skills.css +81 -0
  87. package/public/skills.js +202 -0
  88. package/public/skins/blue-fish/DESIGN.md +24 -0
  89. package/public/skins/blue-fish/face.png +0 -0
  90. package/public/skins/blue-fish/icon-blush.png +0 -0
  91. package/public/skins/blue-fish/icon-sleep.png +0 -0
  92. package/public/skins/blue-fish/icon-smile.png +0 -0
  93. package/public/skins/blue-fish/icon-star.png +0 -0
  94. package/public/skins/blue-fish/icon-wink.png +0 -0
  95. package/public/skins/blue-fish/icon.png +0 -0
  96. package/public/skins/blue-fish/mascot.png +0 -0
  97. package/public/skins/blue-fish/pattern.png +0 -0
  98. package/public/skins/blue-fish/preview.html +12 -0
  99. package/public/skins/blue-fish/skin.css +122 -0
  100. package/public/skins/blue-fish/sparkles.svg +18 -0
  101. package/public/skins/bocchi/DESIGN.md +99 -0
  102. package/public/skins/bocchi/face.png +0 -0
  103. package/public/skins/bocchi/grain.png +0 -0
  104. package/public/skins/bocchi/icon-blush.png +0 -0
  105. package/public/skins/bocchi/icon-sleep.png +0 -0
  106. package/public/skins/bocchi/icon-smile.png +0 -0
  107. package/public/skins/bocchi/icon-star.png +0 -0
  108. package/public/skins/bocchi/icon-wink.png +0 -0
  109. package/public/skins/bocchi/icon.png +0 -0
  110. package/public/skins/bocchi/pattern-soft.png +0 -0
  111. package/public/skins/bocchi/pattern.png +0 -0
  112. package/public/skins/bocchi/preview.html +55 -0
  113. package/public/skins/bocchi/skin.css +233 -0
  114. package/public/skins/bocchi/stage-bg.png +0 -0
  115. package/public/skins/bocchi/stage-soft.png +0 -0
  116. package/public/skins/bocchi/stand.png +0 -0
  117. package/public/skins/bocchi/sticker-guitar.png +0 -0
  118. package/public/skins/kessoku/DESIGN.md +38 -0
  119. package/public/skins/kessoku/grain.png +0 -0
  120. package/public/skins/kessoku/skin.css +212 -0
  121. package/public/skins/kita/SOURCES.json +51 -0
  122. package/public/skins/kita/face.png +0 -0
  123. package/public/skins/kita/icon-live.png +0 -0
  124. package/public/skins/kita/icon-reddress.png +0 -0
  125. package/public/skins/kita/icon-seifuku.png +0 -0
  126. package/public/skins/kita/pattern.png +0 -0
  127. package/public/skins/kita/preview.html +56 -0
  128. package/public/skins/kita/skin.css +26 -0
  129. package/public/skins/kita/stand.png +0 -0
  130. package/public/skins/kita/sticker-live.png +0 -0
  131. package/public/skins/nijika/SOURCES.json +51 -0
  132. package/public/skins/nijika/face.png +0 -0
  133. package/public/skins/nijika/icon-live.png +0 -0
  134. package/public/skins/nijika/icon-reddress.png +0 -0
  135. package/public/skins/nijika/icon-seifuku.png +0 -0
  136. package/public/skins/nijika/pattern.png +0 -0
  137. package/public/skins/nijika/preview.html +56 -0
  138. package/public/skins/nijika/skin.css +25 -0
  139. package/public/skins/nijika/stand.png +0 -0
  140. package/public/skins/nijika/sticker-live.png +0 -0
  141. package/public/skins/penguin/DESIGN.md +33 -0
  142. package/public/skins/penguin/SOURCES.json +22 -0
  143. package/public/skins/penguin/aic-blueprint.svg +24 -0
  144. package/public/skins/penguin/endfield-triangles.svg +4 -0
  145. package/public/skins/penguin/face.png +0 -0
  146. package/public/skins/penguin/icon-blush.png +0 -0
  147. package/public/skins/penguin/icon-dizzy.png +0 -0
  148. package/public/skins/penguin/icon-laugh.png +0 -0
  149. package/public/skins/penguin/icon-sleep.png +0 -0
  150. package/public/skins/penguin/icon-smile.png +0 -0
  151. package/public/skins/penguin/icon-star.png +0 -0
  152. package/public/skins/penguin/icon-wink.png +0 -0
  153. package/public/skins/penguin/icon.png +0 -0
  154. package/public/skins/penguin/mascot.png +0 -0
  155. package/public/skins/penguin/pattern-night.png +0 -0
  156. package/public/skins/penguin/pattern.png +0 -0
  157. package/public/skins/penguin/preview.html +12 -0
  158. package/public/skins/penguin/skin.css +212 -0
  159. package/public/skins/ryo/SOURCES.json +51 -0
  160. package/public/skins/ryo/face.png +0 -0
  161. package/public/skins/ryo/icon-live.png +0 -0
  162. package/public/skins/ryo/icon-reddress.png +0 -0
  163. package/public/skins/ryo/icon-seifuku.png +0 -0
  164. package/public/skins/ryo/pattern.png +0 -0
  165. package/public/skins/ryo/preview.html +56 -0
  166. package/public/skins/ryo/skin.css +25 -0
  167. package/public/skins/ryo/stand.png +0 -0
  168. package/public/skins/ryo/sticker-live.png +0 -0
  169. package/public/sponsor-entry.js +21 -0
  170. package/public/styles.css +1494 -0
  171. package/public/subagents.css +61 -0
  172. package/public/subagents.js +275 -0
  173. package/public/task-board.js +109 -0
  174. package/public/teams.js +98 -0
  175. package/public/theme-picker.css +58 -0
  176. package/public/theme-vars.css +1044 -0
  177. package/public/theme.js +166 -0
  178. package/public/transcribe-core.js +74 -0
  179. package/public/turn-results.js +121 -0
  180. package/public/update.json +49 -0
  181. package/public/vendor/gsap/NOTICE.md +10 -0
  182. package/public/vendor/gsap/gsap.min.js +11 -0
  183. package/public/vendor/morphicons/LICENSE +21 -0
  184. package/public/vendor/morphicons/README.md +10 -0
  185. package/public/vendor/morphicons/controller-CXZuwJ_M.js +152 -0
  186. package/public/vendor/morphicons/dom.js +206 -0
  187. package/public/vendor/morphicons/element.js +261 -0
  188. package/public/vendor/morphicons/normalize-CYnN3Npw.js +540 -0
  189. package/public/vendor/morphicons/spring-CFHloqPP.js +623 -0
  190. package/public/version.json +3 -0
  191. package/public/voice-input.js +739 -0
  192. package/public/workflow.css +365 -0
  193. package/public/workflow.js +409 -0
  194. package/session-file.mjs +39 -0
  195. package/skills/dsh-remote-doctor/SKILL.md +186 -0
  196. package/skills/dsh-remote-doctor/references/wiki/README.md +40 -0
  197. package/skills/dsh-remote-doctor/references/wiki/ai-guide.md +61 -0
  198. package/skills/dsh-remote-doctor/references/wiki/connection.md +76 -0
  199. package/skills/dsh-remote-doctor/references/wiki/errors.md +26 -0
  200. package/skills/dsh-remote-doctor/references/wiki/evidence.md +44 -0
  201. package/skills/dsh-remote-doctor/references/wiki/files.md +31 -0
  202. package/skills/dsh-remote-doctor/references/wiki/maintenance.md +30 -0
  203. package/skills/dsh-remote-doctor/references/wiki/notifications.md +33 -0
  204. package/skills/dsh-remote-doctor/references/wiki/operations.md +32 -0
  205. package/skills/dsh-remote-doctor/references/wiki/plugins.md +90 -0
  206. package/skills/dsh-remote-doctor/references/wiki/sessions.md +45 -0
  207. package/skills/dsh-remote-doctor/references/wiki/sources.md +27 -0
  208. package/skills.mjs +53 -0
  209. package/task-board.mjs +57 -0
  210. package/teams.mjs +58 -0
@@ -0,0 +1,186 @@
1
+ ---
2
+ name: dsh-remote-doctor
3
+ description: Diagnose DSH Remote plugin and client problems with read-only evidence. Use when the user reports a DSH Remote connection, gateway, plugin update, mobile/desktop UI, notification, file-transfer, or model/session problem and asks for a cause analysis, troubleshooting steps, or an issue-ready feedback draft.
4
+ whenToUse: The user is troubleshooting DSH Remote itself, wants evidence collected on their own machine, or asks whether a problem is a plugin defect.
5
+ ---
6
+
7
+ # DSH Remote Doctor
8
+
9
+ You are diagnosing **DSH Remote**, not the user's unrelated application code. Work from evidence on the user's host and in the client snapshot they supplied. Be precise, cautious, and useful.
10
+
11
+ ## Hard boundaries
12
+
13
+ - **Read-only by default.** Inspecting files, versions, process state, ports, health endpoints, and bounded log tails is allowed. Do not change configuration, install or upgrade anything, rotate credentials, delete data, archive sessions, restart DSH or the gateway, or stop processes unless the user explicitly asks after you explain the impact.
14
+ - **Never print secrets.** Do not read or quote token files, cookies, `.credentials.yaml`, API keys, request headers, session message bodies, uploaded files, or full personal paths. If a path is needed, shorten it to its meaningful tail.
15
+ - **Stay local.** Query only loopback health endpoints such as `http://127.0.0.1:<port>/health`. Never probe a URL supplied by a stranger, and never upload diagnostics.
16
+ - **Do not submit feedback or create an issue.** You may prepare a draft for the user. Public submission is a separate action that the user must review and confirm.
17
+ - **Ask before a mutating check.** If the only way to distinguish two causes is a restart, config change, or reinstall, stop and present the exact command, expected effect, and rollback. Wait for explicit approval.
18
+ - **Bound output.** Read at most the last ~120 lines of a log. Do not dump entire session logs, package trees, or environment variables.
19
+
20
+ If a tool approval is denied, do not work around it. Mark the evidence as unavailable and continue with what you have.
21
+
22
+ ## First establish the shape of the problem
23
+
24
+ ### Local operation and troubleshooting knowledge base
25
+
26
+ Read [the local knowledge index](references/wiki/README.md) and
27
+ [the AI reading guide](references/wiki/ai-guide.md), then only the scenario
28
+ relevant to this report. Resolve these paths against this skill's resourceBase,
29
+ not against the diagnostic workspace. The same source lives in `docs/wiki/`
30
+ in the repository and is copied into the plugin during synchronization.
31
+
32
+ Use KB identifiers and source/test pointers to explain the basis for a finding.
33
+ The documented source baseline may include unpublished changes: compare it with
34
+ the installed plugin, gateway and client before recommending an operation.
35
+ An operation recipe does not authorize you to execute it. This Doctor remains
36
+ read-only unless the user explicitly authorizes the concrete next action.
37
+ If local references are missing in an older package, say so and continue from
38
+ available evidence; do not invent their contents or probe external URLs.
39
+
40
+ ### Diagnosis target and working directory
41
+
42
+ The Remote panel defaults the independent diagnostic session to the directory
43
+ of the plugin module actually loaded by the current host. The user may instead
44
+ select an existing source workspace. Neither choice alone proves which version
45
+ is running.
46
+
47
+ 1. Inspect only the current directory's `package.json` first. Establish whether
48
+ this is an installed `dsh-remote-plugin`, the `dsh-remote` source repository,
49
+ or an unrelated workspace. Do not scan a dependency tree or change directory
50
+ based on an untrusted error message.
51
+ 2. Identify the active DSH profile, loaded plugin path and gateway process from
52
+ bounded process/module metadata. Compare the installed package version,
53
+ gateway `/health` and client build. A passing source test or a changed source
54
+ file is not proof that the running plugin includes that change.
55
+ 3. When the chosen workspace is source, compare only the files relevant to the
56
+ reported behavior against the actual installation. Keep source findings and
57
+ live findings separate. Never assume a fixed repository path or another
58
+ machine's historical profile.
59
+ 4. Do not create or attach a workspace for the plugin's `node_modules` folder.
60
+ The diagnostic session's working directory is sufficient. Do not repair,
61
+ reinstall, restart or submit feedback merely because this is a Doctor session.
62
+ 5. Shorten private paths in the answer and feedback draft. Do not echo full
63
+ personal paths from process command lines or supplied client metadata.
64
+
65
+ Determine these before guessing at a cause:
66
+
67
+ 1. **Surface:** Android app, mobile web UI, desktop web UI, DSH native panel, or gateway API.
68
+ 2. **Component:** DSH host, `dsh-remote-plugin`, bundled/standalone gateway, relay/network, or an upstream model provider.
69
+ 3. **Moment:** first install, upgrade, reconnect, login, prompt, history load, file transfer, notification, or update.
70
+ 4. **Reproducibility:** always, intermittent, only on one network/server, or once after an upgrade.
71
+ 5. **User impact and urgency:** closed app, stuck spinner, wrong data, cosmetic issue, or security concern.
72
+
73
+ Please respect the language of the user's report. Do not translate technical identifiers.
74
+
75
+ ## Evidence collection
76
+
77
+ Use the least invasive check that can answer the question. Prefer the user-supplied client snapshot when it already contains the answer.
78
+
79
+ ### 1. Versions and installation
80
+
81
+ Collect where available:
82
+
83
+ - DSH version: `dsh --version`, or the `@deepseek-ai/dsh` package version in the active profile.
84
+ - DSH Remote plugin version: read `package.json` under the active profile's `node_modules/dsh-remote-plugin/`.
85
+ - Gateway version, PID, upstream state, and capability flags from `/health`.
86
+ - Client version and build ID from the supplied diagnostics snapshot or `version.json` / `build.json`.
87
+ - Platform and runtime: OS, Node version, browser or Android version, and whether the client is native or web.
88
+
89
+ A version mismatch between client, plugin, and gateway is a common and testable cause. Do not call it a defect until the observed failure is linked to the mismatch.
90
+
91
+ ### 2. Gateway and DSH reachability
92
+
93
+ Discover the configured port in this order:
94
+
95
+ 1. `DSH_REMOTE_GATEWAY_PORT` environment variable.
96
+ 2. `~/.dsh-remote/gateway-port` (Windows: `%USERPROFILE%\.dsh-remote\gateway-port`).
97
+ 3. Default `8787`.
98
+
99
+ Then check only loopback:
100
+
101
+ ```text
102
+ curl -sS --max-time 3 http://127.0.0.1:<port>/health
103
+ ```
104
+
105
+ Useful facts include `ok`, `version`, `pid`, `upstream`, `upstreamOk`, `upstreamReachable`, `upstreamStatus`, `events`, `runtime`, and declared `capabilities`.
106
+
107
+ Interpretation boundaries:
108
+
109
+ - `upstreamReachable: false` points at DSH or network reachability, not automatically at the gateway.
110
+ - Gateway running with `upstreamOk: false` is **degraded**, not proof that the gateway should be restarted.
111
+ - Missing capabilities on an old gateway can explain a client feature being hidden or rejected.
112
+ - A public listen address does not prove the phone can reach it; check firewall, VPN, and LAN address separately.
113
+
114
+ ### 3. Plugin and gateway logs
115
+
116
+ Look for recent, relevant entries in:
117
+
118
+ - `~/.dsh-remote/plugin-gateway.log`
119
+ - Any profile/DSH host log the user points to.
120
+ - Process or service status, without changing it.
121
+
122
+ Search around the failure timestamp and quote only the minimal lines that support a conclusion. Never paste an entire log. Logs may contain local paths; shorten them in the feedback draft.
123
+
124
+ ### 4. Client diagnostics
125
+
126
+ If the user attached a sanitized operation summary, use it to identify:
127
+
128
+ - failing RPC method and phase
129
+ - history load/cache/render sequence
130
+ - WebSocket close code or polling fallback
131
+ - auth/timeout/network category
132
+ - client error location
133
+
134
+ Do not treat a missing event as evidence of absence. These logs are bounded and intentionally omit message bodies.
135
+
136
+ ### 5. Symptom-specific checks
137
+
138
+ Choose only the branches relevant to the report:
139
+
140
+ - **Cannot connect / 401:** verify the same gateway origin and token were used, the client clock is sane, and the gateway is alive. Never echo the token. The plugin's authenticated upstream cookie is internal; do not inspect its contents.
141
+ - **WebSocket fails / polling works:** check `/health.events`, close codes, proxy/VPN behavior, and whether both mux and host are affected. Fallback to polling is a designed degradation, not necessarily the root cause.
142
+ - **History missing or duplicated:** distinguish cold persistence reads, projection migration, cache fallback, and client rendering. Check whether reconnects/history pages show the same `seq` values.
143
+ - **Plugin update/install failure:** inspect the operation phase and the plugin transaction's bounded output. A snapshot, approval, or pnpm stage failure is not the same as a download failure. Do not modify the profile.
144
+ - **App/UI missing after upgrade:** compare client build, gateway build, cached assets, and service worker/browser cache. Verify whether the old UI is still being served.
145
+ - **File transfer:** separate gateway filesystem permissions, path validation, size limits, and interrupted upload/download. Do not read unrelated files.
146
+ - **Notifications:** confirm the plugin rule source is available and the native client has permission. A missing rule is not a delivery bug.
147
+ - **Model/session errors:** preserve the provider error category, timeout, and whether history/streaming still works. Do not expose credentials or conversation text.
148
+
149
+ ### 6. Reproduce safely
150
+
151
+ Prefer a non-destructive reproduction: reload the page, reconnect the client, open an existing session, or request `/health` again. State the step count and expected/actual result. Do not create throwaway sessions, prompts, files, or issue comments without permission; each may consume quota or create public content.
152
+
153
+ ## Reasoning rules
154
+
155
+ Classify every finding into one of these buckets:
156
+
157
+ - **Confirmed:** directly supported by a version, status field, log line, or reproducible client action.
158
+ - **Likely:** supported by evidence but one alternative remains.
159
+ - **Needs verification:** a hypothesis that requires a user action or more data.
160
+ - **Not a defect:** expected degradation, unsupported old version, invalid configuration, or environmental limitation.
161
+ - **Unknown:** tools or logs were unavailable.
162
+
163
+ Do not turn correlation into causation. Do not promise a fix. If the evidence is insufficient, say exactly what single check would distinguish the top two explanations.
164
+
165
+ ## Output format
166
+
167
+ Keep the diagnosis readable. Unless the user asks for more detail, use:
168
+
169
+ 1. **结论摘要** — one short paragraph and at most three bullets.
170
+ 2. **已确认的证据** — bounded quotes or values with timestamps where possible.
171
+ 3. **可能原因** — ordered, each with confidence and the evidence for it.
172
+ 4. **建议处理** — safe user actions first; label any mutating step `需你确认`.
173
+ 5. **仍需验证** — the smallest next check and what result would change the conclusion.
174
+ 6. **反馈草稿** — a ready-to-review Markdown draft, in a fenced block, with:
175
+ - proposed title (`[Bug] ...`)
176
+ - DSH Remote / plugin / gateway / DSH versions
177
+ - environment and client surface
178
+ - problem description and reproduction steps
179
+ - expected vs actual behavior
180
+ - sanitized evidence
181
+ - attempts already made
182
+ - suspected cause and open questions
183
+
184
+ The draft is for the user to review. It must not contain tokens, cookies, conversation content, full personal paths, or personal contact details. End by reminding the user that the Remote feedback panel can copy the draft or open a prefilled GitHub issue, and that they must review it before submitting.
185
+
186
+ If the user's report does not point to a DSH Remote defect, say so plainly and suggest the appropriate upstream or environmental next step instead of inventing a plugin bug.
@@ -0,0 +1,40 @@
1
+ # DSH Remote 操作与排障知识库
2
+
3
+ 这是供用户和用户的 AI 共同使用的 Wiki 式入口。先按操作或症状找文章,再按证据判断原因。正文保存在仓库内,与代码一起审阅;插件包也携带同一份知识库,断网时可查。
4
+
5
+ 核对基线:2026-10-23,Remote 源码 `0.8.0-rc.9`,包含尚未发布的正式版准备与实验性插件折叠改动。真实 DSH 联调记录包含 `0.2.1-rc.2`,不是全部旧版和未来版本的兼容承诺。不同版本的实际界面、capability、安装包和运行状态优先于这里的基线。
6
+
7
+ ## 我要操作
8
+
9
+ | 任务 | 入口 |
10
+ | --- | --- |
11
+ | 连接主机、选工作区、发送、审批、文件、通知 | [日常操作手册](operations.md) |
12
+ | 安装、更新、停用、卸载插件,查看实验性插件 | [插件管理与升级](plugins.md) |
13
+ | 查看历史、思考、插队、分支与子智能体 | [会话、历史与发送结果](sessions.md) |
14
+ | 上传、续传、下载,检查允许目录 | [文件传输](files.md) |
15
+ | 开启后台通知与峰谷提醒 | [通知与后台](notifications.md) |
16
+
17
+ ## 我遇到问题
18
+
19
+ | 症状或检索词 | 文章与编号 |
20
+ | --- | --- |
21
+ | 网关待启动、拒绝连接、端口占用、upstream、401 | [连接与网关](connection.md):KB-CONN-01~04 |
22
+ | 本机正常手机打不开、VPN、Tailscale、中转 HOST_OFFLINE | [连接与网关](connection.md):KB-CONN-03、05 |
23
+ | 加载中、历史非零却空白、迁移、fallback、instruction-hint | [会话与历史](sessions.md):KB-SESSION-01、02 |
24
+ | 发送结果未知、重复消息、插队没有马上中断 | [会话与历史](sessions.md):KB-SESSION-03、04 |
25
+ | 插件只读、列表漏显、更新卡住、pnpm 发布时间限制 | [插件管理](plugins.md):KB-PLUGIN-01~04 |
26
+ | 适配诊断、任务看板、费用余额、团队计划审查与交付警告 | [插件适配数据](plugins.md):KB-PLUGIN-02、05 |
27
+ | 403、路径不在允许范围、409、422、上传中断 | [文件传输](files.md):KB-FILE-01、02 |
28
+ | 息屏断连、没有审批通知、峰谷规则不可用 | [通知与后台](notifications.md):KB-NOTIFY-01、02 |
29
+ | 找到错误码但不知道归谁处理 | [错误与状态索引](errors.md) |
30
+
31
+ ## 给 AI 与维护者
32
+
33
+ - [AI 阅读与执行指引](ai-guide.md):先确认版本与实际目标,区分操作请求和排障请求。
34
+ - [证据采集与反馈模板](evidence.md):最小、脱敏、可复核,不上传原始会话。
35
+ - [源码与验证依据](sources.md):每类结论对应实现、回归测试和专题文档。
36
+ - [维护约定](maintenance.md):新问题如何入库、适用版本与证据如何更新。
37
+
38
+ 仓库入口是 `docs/wiki/README.md`;已安装插件中的离线入口是 `skills/dsh-remote-doctor/references/wiki/README.md`。后者由 `npm run sync-plugin` 生成,不能直接修改。根 `llms.txt` 提供给外部 AI 的简短索引。
39
+
40
+ 历史 issue 已关闭、测试通过、构建成功或公告写了“修复”,都不自动证明用户当前主机已安装修复或原设备已经验收。先读 [AI 指引](ai-guide.md)。
@@ -0,0 +1,61 @@
1
+ # 给用户 AI 的阅读与执行指引
2
+
3
+ [知识库首页](README.md)
4
+
5
+ ## 先确认任务和目标
6
+
7
+ 1. 用户是在问“怎么用”,还是授权进行某项操作,还是要求诊断故障?讲解操作步骤不等于授权你执行安装、重启、发送消息或删除。
8
+ 2. 确认问题属于 Android、手机浏览器、桌面 Web、DSH 插件面板、独立网关还是中转;不要把多个端当成同一进程。
9
+ 3. 核对实际 DSH profile、已加载插件、网关 `/health`、客户端版本与 buildId。源码、安装目录和正在运行的进程是三份证据。
10
+ 4. 只读当前相关文档与有限日志,不全盘搜索用户的会话、文件和凭据。不假设用户目录、DSH 端口或仓库路径。
11
+
12
+ 如果从源码仓库开始,先读取根 `package.json` 和相关实现;从安装包开始,先读取插件自己的 `package.json` 与本地知识库。本文中的仓库路径只是定位索引,不是用户电脑上可照抄的绝对路径。
13
+
14
+ ## 按最短路径阅读
15
+
16
+ | 用户意图 | 首先阅读 | 然后检查 |
17
+ | --- | --- | --- |
18
+ | 单纯操作 | [日常操作](operations.md) | 该端是否有入口、该主机是否提供能力 |
19
+ | 连接或网关故障 | [连接](connection.md) | 回环 health → DSH 上游 → mux/host → 手机网络 |
20
+ | 历史或发送异常 | [会话](sessions.md) | 读失败、渲染失败、迁移失败、写操作回执分别判断 |
21
+ | 插件安装/升级 | [插件](plugins.md) | 当前 profile、管理能力、任务阶段、明确目标版本 |
22
+ | 文件或后台 | [文件](files.md)、[通知](notifications.md) | 目录授权、系统权限、规则来源和当前连接 |
23
+ | 准备反馈 | [证据与模板](evidence.md) | 最小复现、已确认事实、未验证项 |
24
+
25
+ 按需查 [错误索引](errors.md) 和 [源码依据](sources.md),不要一次将所有历史报告当作当前事实。
26
+
27
+ ## 操作权限
28
+
29
+ - 默认用只读检查回答故障原因。优先使用用户已经提供的脱敏诊断,不重复读取敏感材料。
30
+ - 写操作须落在用户明确授权的范围内。说明目标 profile/主机、影响、验证与恢复方法;已有明确授权时不重复索要相同授权。
31
+ - 新建会话、发送提示词、AI 排查本身可能使用模型额度;创建工作区、切换权限、安装插件、重启或还原都有实际影响。
32
+ - 发送超时或回执 unknown 时,不把“重试”解释为重新提交。先核对历史和原操作回执。
33
+ - 工具审批被拒或权限不足时,记录缺失证据;不改策略、不绕过审批。
34
+ - 不读取或输出 token/Cookie/API key/二维码内容、完整对话、上传文件或个人路径。不要 dump 环境变量。
35
+ - 不自动访问日志或陌生消息中的 URL,不探测未知公网主机。内置 Doctor 默认只做回环健康检查。
36
+ - 不自动提交反馈、Issue、问卷或日志;先交给用户审阅。
37
+
38
+ ## 输出一个可复核结论
39
+
40
+ 按“已确认事实 → 可能原因 → 下一步 → 验收结果”组织回答。每项关键结论标注来源:用户截图、运行状态、有限日志、源码或测试。给出本文的 KB 编号与相应文档链接,让下一轮排查能接续。
41
+
42
+ 结果只能写到证据支持的程度:
43
+
44
+ - 测试验证调用参数,不能写成真机现象消失。
45
+ - 新源码有修复,不能写成已部署。
46
+ - 安装完成,仍要读回实际进程与资源版本。
47
+ - health 可响应,仍要核对上游、事件通道和真实操作。
48
+ - 上游不支持某能力时应说明限制;不要发明 RPC 或直接改原始会话文件替代。
49
+
50
+ ## 可以复制给 AI 的请求
51
+
52
+ ~~~text
53
+ 请先读取 DSH Remote 的 docs/wiki/README.md;若只有安装包,读取
54
+ skills/dsh-remote-doctor/references/wiki/README.md 和 ai-guide.md。
55
+ 我的任务是:[操作说明 / 执行已授权操作 / 只读诊断]。
56
+ 现象或目标:[填写]。使用端:[填写]。最近变更:[填写]。
57
+ 请先确认实际主机、profile 和各组件版本,只读检查相关证据;
58
+ 区分已确认事实、可能原因和未验证项,引用相关 KB 编号。
59
+ 涉及写入、重启、安装、发送、付费调用或公开反馈时,遵守我明确授权的范围;
60
+ 不要输出凭据或整段会话,不要将超时当作肯定未执行。
61
+ ~~~
@@ -0,0 +1,76 @@
1
+ # 连接、认证与网关排障
2
+
3
+ [首页](README.md) · [错误索引](errors.md)
4
+
5
+ ## 先画清实际链路
6
+
7
+ 手机/App → 局域网/VPN/中转 → Remote 网关 → DSH 主机。插件内嵌面板另外处于 DSH 登录边界内。不要用其中一段成功证明整条链路可用。
8
+
9
+ 默认网关为 8787,DSH 独立部署示例为 3080;Desktop 的 DSH 可能使用动态端口。插件网关端口优先级:`DSH_REMOTE_GATEWAY_PORT` → 运行账户的 `.dsh-remote/gateway-port` → 8787。独立网关使用 `PORT`。以实际配置为准。
10
+
11
+ 在主机做有限的只读检查(将示例端口改为已确认的本机端口):
12
+
13
+ ~~~powershell
14
+ $health = Invoke-RestMethod -Uri 'http://127.0.0.1:8787/health' -TimeoutSec 3
15
+ $health | Select-Object ok, version, pid, status, upstreamOk, upstreamReachable, upstreamStatus
16
+ $health.events | Select-Object mux, host
17
+ Get-NetTCPConnection -LocalPort 8787 -State Listen
18
+ ~~~
19
+
20
+ ~~~sh
21
+ curl -sS --max-time 3 http://127.0.0.1:8787/health
22
+ ~~~
23
+
24
+ 保留 health 给本地分析,公开反馈前再脱敏地址、路径和错误文本。不要追加读取令牌文件、Cookie 或全部环境变量。没有事件字段的旧版本标为未知。
25
+
26
+ ## KB-CONN-01:网关待启动、拒绝连接或端口占用
27
+
28
+ **先看:** 运行账户/profile、端口是否监听、监听者身份、插件网关日志最后约 120 行;同时核对启停意图。
29
+
30
+ **判断:** 无监听通常在启动链路;有其他监听者是占用;有 Remote health 但面板认为未启动,还需检查管理认证与运行版本。不能只凭 PID 存在判定它是 supervisor。
31
+
32
+ **下一步:** 优先由用户在插件面板启动或调整端口;变更环境变量通常需要重启相关进程。重启/结束进程必须有明确授权和实例归属。
33
+
34
+ **验收:** 端口由正确实例监听,health 版本吻合,上游与双事件通道恢复;再从原客户端连接。`SUPERVISOR_*` 诊断见 [错误索引](errors.md)。
35
+
36
+ ## KB-CONN-02:ok:true 但 degraded、upstream 不通
37
+
38
+ **先看:** `upstreamReachable/upstreamOk/upstreamStatus`、实际 DSH 地址、登录状态、DSH 进程,以及 mux/host 各自状态。默认探测 DSH 根路径 `/`。
39
+
40
+ **判断:** `ok:true` 只说明网关响应。401 可能说明 HTTP 可达但认证未就绪;Desktop 重启换端口、登录 Cookie 尚未兑换、DSH 本身阻塞需要分别查证。上游临时不可达不应触发网关重启风暴。DSH 桌面版重启会换一个回环端口:插件优先让**运行中的网关原地切换上游**(`POST /admin/api/upstream`,仅接受回环地址),因此中转控制通道与公网入口保持在线,手机通常在数秒内重新看到 DSH;只有网关版本/解释器变化或热切换失败时才回退到重启网关。
41
+
42
+ **下一步:** 在主机确认 DSH 正常响应,再核对插件记录的 upstream;不要自行把不存在的 `/healthz` 当作重启条件。
43
+
44
+ **验收:** 正确上游可响应且认证满足当前接口,目标会话可读取,mux/host 恢复或明确使用轮询。
45
+
46
+ ## KB-CONN-03:主机正常,手机打不开或切网后断线
47
+
48
+ **先看:** 手机实际使用的地址、同一部手机在 Wi-Fi/蜂窝及 VPN 开/关下的对照,DNS 与实际网络路径。手机的 localhost 指向手机自己。
49
+
50
+ **判断:** 仅某一网络失败优先查网络、VPN、AP 隔离、防火墙和地址族;不能直接归因于云端。纯 IPv6 DDNS 还需确认网关监听 IPv6。
51
+
52
+ **下一步:** 由用户在已知地址上做最小对照。插件支持 `DSH_REMOTE_GATEWAY_HOST` → `HOST` → `.dsh-remote/gateway-host` → `0.0.0.0`;需要 IPv6 可配置 `::`,但改监听、防火墙与公网暴露属于配置变更。
53
+
54
+ **验收:** 原失败网络下可进入同一主机、读取同一会话;网络恢复后历史/事件继续,不重复发送消息。
55
+
56
+ ## KB-CONN-04:401、反复登录或实时更新失败
57
+
58
+ **先看:** 分清 DSH/反向代理登录、Remote 主令牌与独立设备密钥;只确认当前设备配对状态,不读取凭据内容。检查 mux、host、WS ticket 和反向代理 Upgrade。
59
+
60
+ **判断:** 登录 HTML、代理超时、设备撤销与 token 失效不是同一种错误。单通道降级轮询是设计行为;不能靠“WS connected”断言历史完整。
61
+
62
+ **下一步:** 需要时由用户重新配对或在原 DSH 登录入口恢复登录;不把公开 health 当作强杀/轮换凭据依据。客户端不发送应用层心跳,网关使用 WebSocket Ping/Pong。
63
+
64
+ **验收:** 对应认证入口成功,目标接口返回预期数据;检查两条事件流或轮询的实际增量。
65
+
66
+ **写回执:** 发送、创建等写操作在支持 `operations` 的网关上使用持久回执;结果未知时不自动重发。切换连接(地址或令牌变化)后,旧连接的未确认回执仍会显示在“审批与操作回执”和首页提示中,但只有切回原连接才能查询;1006 重连本身不改变回执归属。仓库另有写回执可见性说明 `docs/write-receipt-visibility.md`。
67
+
68
+ ## KB-CONN-05:中转 HOST_OFFLINE
69
+
70
+ **先看:** 当前中转配置、主机网关是否已连接正确中转、设备身份与主机归属;再做 KB-CONN-03 的同手机网络对照。
71
+
72
+ **判断:** 云端入口可打开,只证明入口响应;`HOST_OFFLINE` 不能唯一定位为防火墙、主机关闭或 DNS 故障。
73
+
74
+ **下一步:** 对照网关、中转与手机三侧同一时间的有限状态。不要因一端报错就重装云服务或更换凭据。
75
+
76
+ **验收:** 相同主机通过原网络可访问且可读会话;长连接与中转在线状态分别核对。自建部署的详细环境准备在仓库 `docs/self-hosted-relay.md`。
@@ -0,0 +1,26 @@
1
+ # 错误码与状态索引
2
+
3
+ [首页](README.md)
4
+
5
+ 相同 HTTP 状态可以来自不同层。先记下发生阶段、端点类别和组件版本,再查本表;表内不是完整错误枚举。
6
+
7
+ | 原文/状态/检索词 | 解释边界 | 下一篇 |
8
+ | --- | --- | --- |
9
+ | `ok:true`、`ready`、`degraded` | 网关响应与就绪程度;上游、事件通道分别核对 | [连接](connection.md) KB-CONN-02 |
10
+ | `EADDRINUSE`、`PORT_IN_USE` | 监听冲突,需要确认占用者身份 | [连接](connection.md) KB-CONN-01 |
11
+ | `SUPERVISOR_ALREADY_RUNNING`、`supervisor already running` | 当前互斥/兼容旧租约的判断;PID 存活本身不够 | [连接](connection.md) KB-CONN-01 |
12
+ | `SUPERVISOR_IDENTITY_UNAVAILABLE` | 无法核实旧 supervisor 身份,保守拒绝接管;可能是进程查询权限 | [连接](connection.md) KB-CONN-01 |
13
+ | `SUPERVISOR_ENDPOINT_TOO_LONG`、`EINVAL`、`ENAMETOOLONG` | macOS 等文件 socket 的路径/监听诊断;不等于端口占用 | [连接](connection.md) KB-CONN-01 |
14
+ | 401、登录 HTML、Unauthorized | 先区分 DSH/代理登录与 Remote 设备认证 | [连接](connection.md) KB-CONN-04 |
15
+ | `HOST_OFFLINE` | 中转视角的主机离线状态;不能唯一定位根因 | [连接](connection.md) KB-CONN-05 |
16
+ | mux/host 重连、WS 失败、轮询中 | 一条/两条事件通道退化;HTTP 可用不证明实时可用 | [连接](connection.md) KB-CONN-04 |
17
+ | `session/migration-required`、`cannot safely transform unclassified message source` | 上游旧会话迁移限制,Remote 侧隔离与提示 | [会话](sessions.md) KB-SESSION-02 |
18
+ | `permission: cannot restore preset "auto" without its active integration` | DSH 恢复 Auto 权限事实时缺当前有效集成;核对错误所属会话 | [会话](sessions.md) KB-SESSION-04 |
19
+ | accepted / rejected / pending / unknown | 分别核对操作阶段;未知不等于未执行 | [会话](sessions.md) KB-SESSION-03 |
20
+ | `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` | 发布时间策略可能被锁文件中其他依赖触发 | [插件](plugins.md) KB-PLUGIN-03 |
21
+ | `EPERM`、快照路径越界、任务锁 | 要结合任务阶段,不能统称网络失败或随意删锁 | [插件](plugins.md) KB-PLUGIN-03 |
22
+ | 文件 403、路径不在允许范围 | 授权根、账户、真实路径和保护目录 | [文件](files.md) KB-FILE-01 |
23
+ | 上传 409/422、offset、SHA-256 | 冲突、续传或校验等,具体以响应固定错误为准 | [文件](files.md) KB-FILE-02 |
24
+ | 通知 unknown、规则不可用/过期 | 先区分规则来源和 Android 投递 | [通知](notifications.md) |
25
+
26
+ 历史 issue #19 对应旧租约/PID 复用,#20 对应 macOS socket 过长,#21 对应大量会话主动观察,#18 仍包含上游迁移限制。这里是检索线索;关闭 issue 不代表当前机器已验证恢复。版本、实际安装与运行证据要求见 [AI 指引](ai-guide.md)。
@@ -0,0 +1,44 @@
1
+ # 证据采集与反馈模板
2
+
3
+ [首页](README.md) · [AI 指引](ai-guide.md)
4
+
5
+ ## 最小证据包
6
+
7
+ | 项目 | 建议记录 | 不应分享 |
8
+ | --- | --- | --- |
9
+ | 版本 | DSH、已安装插件、运行网关、App/WebUI 与 buildId | 不用源码版本替代运行版本 |
10
+ | 目标 | 系统、使用端、profile 名称、安装方式 | 完整个人路径、账号或公网地址 |
11
+ | 时间 | 问题发生时间和时区、最近升级/切网动作 | 整段历史轨迹 |
12
+ | 状态 | health 关键字段、双事件通道、HTTP 状态与固定错误码 | token、Cookie、认证头、二维码 |
13
+ | 操作 | 目标类型、失败阶段、回执/任务的脱敏关联信息 | 消息正文、工具输入、上传文件 |
14
+ | 对照 | 同手机不同网络、正常/坏会话、重启前后 | 未经授权创建任务或调用模型的结果 |
15
+ | 日志 | 相关日志末尾约 120 行内的必要片段,先脱敏 | 整个会话日志、配置文件、环境变量 |
16
+
17
+ “更多 → 关于与维护 → 本地操作日志”记录有限的操作阶段与匿名关联信息,可复制/导出。Android 使用系统文件选择器。它不包含所有后端错误;历史日志没保存的细节无法事后还原。即使应用已经过滤字段,分享前仍需用户审阅。
18
+
19
+ ## 诊断记录模板
20
+
21
+ ~~~text
22
+ 标题:[Bug/使用问题] 现象
23
+ 相关条目:KB-...
24
+ 发生时间与时区:
25
+ DSH / 已安装插件 / 运行网关 / 客户端版本与 buildId:
26
+ 系统、使用端、安装方式、profile 名称:
27
+ 最近变更:
28
+
29
+ 最小复现步骤:
30
+ 1.
31
+ 2.
32
+
33
+ 预期:
34
+ 实际:
35
+ 是否每次发生、影响一个还是全部会话/主机:
36
+
37
+ 已确认事实(每项标明截图/状态字段/有限日志/源码):
38
+ 可能原因:
39
+ 尚未执行或无法取得的检查:
40
+ 已经尝试的动作及结果:
41
+ 下一步最小检查、影响与验收条件:
42
+ ~~~
43
+
44
+ AI 可以整理这份草稿,但不自动上传日志或提交 Issue。用户确认公开内容后再自行提交;先排除已知限制、配置问题与上游错误,避免把所有失败都归为 Remote 缺陷。
@@ -0,0 +1,31 @@
1
+ # 文件传输与目录范围
2
+
3
+ [首页](README.md) · [错误索引](errors.md)
4
+
5
+ 文件页传输通过网关文件接口与主机账户权限工作。聊天图片发给模型是另一路能力,不能用文件上传成功证明模型读到了图片或文件。
6
+
7
+ ## KB-FILE-01:403、路径不在允许范围、Windows 盘符不可见
8
+
9
+ **先看:** 当前主机/工作区、路径所属平台、显式允许根、文件真实路径、运行账户权限;区分 401 认证错误和 403 范围拒绝。
10
+
11
+ - `DSH_REMOTE_FS_ROOT` 多根在 Windows 使用 `;`,Linux/macOS 使用 `:`。不要按冒号拆开 Windows 盘符。
12
+ - Windows 默认范围包含当前用户目录与启动时可用的非 C 盘盘符;新挂载磁盘可能需要重启网关后重新发现,UNC 共享需显式授权。
13
+ - Windows 默认范围不会因工作区登记而开放 C 盘其他受限目录;junction/符号链接必须通过真实路径边界检查。
14
+ - Linux/macOS 的默认用户目录与经过 DSH 验证的工作区、显式根规则见当前网关实现。`DSH_REMOTE_FS_ROOT` 不是 DSH 所有工具的沙箱。
15
+ - 凭据目录/文件另有保护;范围允许不等于可以下载主机 token 或 Cookie。
16
+
17
+ **下一步:** 先检查目标是否合法、是否选错主机。确需新增授权时说明准确目录、影响和重启条件,由用户授权后修改;不要开放整盘或关闭真实路径检查作为默认修复。
18
+
19
+ **验收:** 在预期目录可列出/下载测试目标;越界与受保护文件仍被拒绝。不要读取用户无关文件做验证。
20
+
21
+ ## KB-FILE-02:同名冲突、续传失败、409/422、上传中切主机
22
+
23
+ **先看:** 客户端提示、原上传任务、目标路径、大小、已有偏移与校验状态。409/422 的具体原因以接口错误与操作阶段为准,不能只看 HTTP 码猜测。
24
+
25
+ **判断:** 目标已存在、并发占用、偏移不符、SHA-256 不符、连接切换是不同分支。最大文件大小受 `DSH_REMOTE_FS_MAX_UPLOAD` 及账户/磁盘约束,当前默认 2 GiB。
26
+
27
+ **下一步:** 再次确认覆盖行为;按原任务恢复或在明确取消后重来,不把上传到 A 的迟到结果算作 B 的成功。只有用户授权后才创建测试文件或清理未完成上传。
28
+
29
+ **验收:** 正确主机与目标目录出现预期文件,大小/校验一致;中断不留下被误认为完整的文件;未经确认不覆盖已有文件。
30
+
31
+ 源码:`gateway.js`(插件为 `gateway.cjs`)、`public/app.js`、`public/chat-files.js`。回归入口与专题见 [源码依据](sources.md)。
@@ -0,0 +1,30 @@
1
+ # 知识库维护约定
2
+
3
+ [首页](README.md)
4
+
5
+ ## 一份正文,多个入口
6
+
7
+ - `docs/wiki/` 是知识库正文源,根 `llms.txt` 是简短 AI 索引;README、文档首页和排障入口只链接到这里。
8
+ - `npm run sync-plugin` 将正文复制到插件的 `skills/dsh-remote-doctor/references/wiki/`。这是构建副本,不直接编辑;插件既有 skills 分发范围会携带它。
9
+ - 本轮不创建或发布外部 GitHub Wiki。以后需要网页/Wiki 展示时,从同一来源生成,并解决链接与版本对应;不手工维护两套正文。
10
+ - 旧专题报告保留原结果与日期。不要把一次旧测试“通过”批量替换为新版本已验收。
11
+
12
+ ## 新条目的最低内容
13
+
14
+ 每个问题使用稳定编号,例如 KB-CONN-01;标题包含用户会搜的原词。写清:
15
+
16
+ 1. 现象与影响范围。
17
+ 2. 适用端、版本/能力与核对日期;区分仅源码、已发布、实装和实机。
18
+ 3. 第一轮只读取什么、哪些字段能区分原因。
19
+ 4. 每个分支的下一步、动作影响与授权要求。
20
+ 5. 验收结果,以及仍未知时如何退出/反馈。
21
+ 6. 源码/测试/专题依据,附上脱敏后的典型错误,不贴用户日志。
22
+
23
+ 常见操作使用“目标 → 入口 → 前提 → 完成后核对”;不要把后端内部术语直接当成用户步骤。安全边界有变化时,同时更新 AI 指引和内置 Doctor。
24
+
25
+ ## 更新与检查
26
+
27
+ - 修改实际行为时更新对应页、首页检索表和错误索引;本次新增实验性插件折叠、发布计数等尚未分发的行为,应明确标为源码基线。
28
+ - 运行文档链接/打包副本检查,并检查内置 Doctor 的相对链接能在安装包内定位。
29
+ - 改同步脚本或技能内容后运行相关回归及 `npm run sync-plugin`,确认 npm 包确实包含离线文档;无需仅为 Markdown 改动重建 APK。
30
+ - 只有用户明确要求发布时,才执行远端 Wiki 同步、提交、push、发布或替换线上资产。
@@ -0,0 +1,33 @@
1
+ # 通知、后台与峰谷提醒
2
+
3
+ [首页](README.md) · [日常操作](operations.md)
4
+
5
+ 本页主要针对 Android。手机 Web 不能假装具备 Android 原生桥;HarmonyOS 有独立代理提醒/长时任务实现,能力和系统限制不同。
6
+
7
+ ## KB-NOTIFY-01:前台正常,息屏后无通知或掉线
8
+
9
+ **先看:** “更多 → 通知与后台”中的后台轮询、审批/提问开关、服务状态;Android 系统通知许可与通知渠道、厂商电池策略、网络及配对状态。只读检查,不直接改变省电策略。
10
+
11
+ 0.8.2-rc.1 可分别测试审批、本轮结束、执行失败的实际通知渠道。任务结果走「任务结果提醒」,与安静的后台常驻通知分开;设置页会显示被关闭的系统/渠道状态。初始空闲、历史回放和目标清除不作为新任务完成补发,点击真实结果应进入对应主机和会话。
12
+
13
+ 0.8.2-rc.2 修复双通道乱序重复提醒和批量补拉已处理审批的短暂提醒;测试通知被系统拒绝时返回失败。仅以界面“已提交”不能判定用户已收到:还需在通知栏实际看到,并分别核对声音、振动和息屏投递。
14
+
15
+ **判断:** 已允许通知不等于后台服务运行;前台收到了事件不等于息屏后系统继续调度。Doze、厂商省电与前台服务时限都会影响投递,不能承诺永久连接。
16
+
17
+ **下一步:** 使用本地操作日志的后台快照核对最后成功时间与失败类别。请用户比较前台/息屏、相同网络下的表现,再决定是否调整系统设置;不要因一次延迟就改云端或重装服务。
18
+
19
+ **验收:** 在用户授权的可控任务中,原问题条件下收到一次通知;请求处理后不重复提醒,点击进入正确主机与会话。通知验证涉及创建任务/审批时,事先说明影响。
20
+
21
+ ## KB-NOTIFY-02:峰谷状态未知、提醒未送达或重复
22
+
23
+ **先看:** 主机 `dsh-cost-meter` 是否提供提醒规则、插件提醒是否启用、手机开关与系统许可、时间表是否新鲜。
24
+
25
+ **判断:** 规则由费用插件拥有,Remote Android 是接收与投递端。它每约 5 分钟同步时间表、每约 30 秒核对有效缓存;过期/插件不可用时停用,短时断网不意味着立即删除有效缓存。不能在手机端自建固定峰谷时刻替代上游规则。
26
+
27
+ **下一步:** 在 DSH 费用设置核对时间窗、提前量、提醒方向与生效日期,再核对手机缓存时间与当前连接。切主机/凭据后旧来源不应继续投递。
28
+
29
+ **验收:** 受控变化点只投递一次,内容时间与费用插件一致;重启去重、有效期和限时补发符合规则。界面显示状态或 JVM 策略测试通过,不能代替 Android 真机通知验收。
30
+
31
+ **其他平台:** HarmonyOS 的代理提醒/长时任务可能被系统拒绝或取消,进程内回退无法保证冻结后执行。相关目录内规则与工程文档优先,不能照抄 Android 设置路径。
32
+
33
+ 依据:`packages/plugin/peak-reminders.mjs`、Android `PeakReminderService` / `PeakReminderPolicy` / `RemotePollService`,以及仓库 `docs/peak-reminders-and-issue18.md`。
@@ -0,0 +1,32 @@
1
+ # 日常操作手册
2
+
3
+ [首页](README.md) · [AI 指引](ai-guide.md)
4
+
5
+ 适用本库的源码基线;Android 和手机 Web 共用主要界面,桌面 Web 也有“会话、文件、更多”。HarmonyOS 是独立客户端,不能照搬所有入口。
6
+
7
+ | 想做什么 | 操作路径 | 完成后核对 | 影响与条件 |
8
+ | --- | --- | --- | --- |
9
+ | 添加手机连接 | DSH 插件面板“添加手机”,手机扫码或填写主机地址与配对信息 | 当前主机名称与连接状态,进入工作区/会话 | 配对信息敏感;手机不要填写 localhost |
10
+ | 检查连接 | 更多中的连接/服务器设置,或管理页连接诊断 | health、上游、mux/host 分开看 | 只读检查,参见 [连接](connection.md) |
11
+ | 选工作区 | 会话页选择工作区;新会话时核对名称和路径 | 新会话属于所选主机、工作区 | 新建会话有写入;不要用空参数猜 cwd |
12
+ | 正常发送 | 会话内输入后点击发送 | 等待 accepted 或查看原操作回执 | 可能调用模型;unknown 不能再次盲发 |
13
+ | 插队发送 | 启用长按插队设置,繁忙时按当前按钮提示操作 | DSH 是否接受插队,后续历史/队列 | 接受不代表当前工具立即被中断,见 [会话](sessions.md) |
14
+ | 查看审批 | 当前会话待办;更多 → 审批与操作回执 | 会话、工具、原因和最终结果 | 允许/拒绝是写操作;记录不包含所有自动放行调用 |
15
+ | 切换权限 | 当前会话的权限模式菜单 | 主机公布选项、当前模式、命令终态 | Auto review 是实验能力,有风险确认;仅影响该会话 |
16
+ | 创建分支 | 已完成回合的结果栏选择分支 | 跳到新分支会话,历史边界正确 | 创建会话;分支成功不会自动发送下一条消息 |
17
+ | 看子智能体 | 会话顶栏“子代理”,展开层级并选择节点 | 直接父会话、状态、只读记录 | 依赖 DSH 目录能力;第三方团队不等于内置子代理 |
18
+ | 管理插件 | 更多 → 主机插件 | 当前 profile、任务阶段、待重启状态 | 操作区分管理权限,见 [插件](plugins.md) |
19
+ | 文件传输 | 文件页选择主机/工作区及目录,再上传或下载 | 目标路径、大小及传输结果 | 需允许根和主机账户权限,见 [文件](files.md) |
20
+ | 开启通知 | 更多 → 通知与后台,按需开启轮询、审批/提问及峰谷提醒 | 系统通知许可、服务状态、主机规则 | 依赖 Android 权限与省电策略,见 [通知](notifications.md) |
21
+ | AI 排查 | 插件/控制台/连接诊断/手机首页的“AI 排查问题” | 目标目录、独立诊断会话与结论 | 打开面板不调用模型,开始诊断后使用主机模型额度 |
22
+ | 导出诊断 | 更多 → 关于与维护 → 本地操作日志 | 导出的脱敏 JSON;用户审阅后分享 | 无需反馈或主机在线;清除记录是单独操作 |
23
+
24
+ ## 常见误解
25
+
26
+ - “已安装”“配置启用”“组件正在运行”不是同一个状态。插件配置启停通常需要重启 DSH。
27
+ - 费用、套餐、技能中心等页面依赖对应主机插件。缺失时显示不可用,不应显示为零或假装安装成功。
28
+ - 图片附件发给模型,与上传文件到主机目录,是不同操作。
29
+ - 归档不是永久删除。上游没有删除能力时,不能直接删会话文件作为替代。
30
+ - UI 上有按钮不代表当前主机支持完整动作;先看 capability、主机返回和最终回执。
31
+
32
+ 实现与验证入口见 [源码依据](sources.md)。更完整的逐步界面说明在仓库 `docs/usage.md`、`docs/onboarding-guided-practice.md`。