📝 docs: 说明仓库结构与维护者命令，记录 v1.0.7

README.md

@@ -59,10 +59,10 @@ DeepSeek Harness（DSH）插件：会话**需要你注意**时提醒你——窗
 在 DSH 的 **插件 → 添加插件** 的上方输入框里填：
 
 ```text
-https://gitea.iwake.top/dsh-plugin/session-notify.git#v1.0.6
+https://gitea.iwake.top/dsh-plugin/session-notify.git#v1.0.7
 ```
 
-`#` 后面跟标签或提交，用来锁定版本；不写则取默认分支。跟随 1.x 最新版可以写 `#semver:^1.0.6`。仓库是公开的，不需要凭据，也不用改「安装源」。
+`#` 后面跟标签或提交，用来锁定版本；不写则取默认分支。跟随 1.x 最新版可以写 `#semver:^1.0.7`。仓库是公开的，不需要凭据，也不用改「安装源」。
 
 ### 本地路径安装
 
@@ -74,8 +74,9 @@ D:\DeepSeek Harness Plugins\dsh-session-notify
 
 ### 安装之后
 
-- 装好**刷新页面**即生效；本插件没有第三方依赖，也不需要 pnpm 下载或构建步骤。
+- 装好**刷新页面**即生效；仓库里已经带好构建产物，所以**既不需要 pnpm 下载，也不需要构建**，本插件运行时没有第三方依赖。
 - 卸载：在插件页里移除 `@dsh-plugin/session-notify`。
+- 上面这两条说的都是**使用者**。要改插件本身，只需要一个 `pnpm install`（唯一依赖是打包用的 esbuild），见下面的[仓库结构](#仓库结构)。
 
 ## 提醒规则
 
@@ -100,6 +101,32 @@ D:\DeepSeek Harness Plugins\dsh-session-notify
 
 需要 **DeepSeek Harness 0.2.0-rc.2 或更高**。
 
+## 仓库结构
+
+给要改这个插件本身的人；只是使用它的话，这一节不需要看。
+
+| 路径 | 是什么 |
+| --- | --- |
+| `src/client/` | 浏览器半的全部源码：`core/`（观察、投递、系统通知通道、补发、弹窗栈、开关与动作）、`ui/`（弹窗、开关行、插件页、观察器、图标、样式、hooks）、`i18n/`（中英文字典与翻译器）、`platform.js`（窗口可见性、通知权限、图标、平台提示）、`plugin.js`（组合根：建 store、装配模块、注册 slot） |
+| `client.js` | **构建产物**：`src/client/**` 打包成一个自包含单文件，由 DSH 的客户端模块系统加载。它提交进仓库——这正是安装免构建的原因 |
+| `index.js` / `main.js` | 宿主半（目前是空壳），以及给按 `main` 解析的加载器用的同义入口 |
+| `cordis.patch.yml`、`icon.svg`、`locale/` | 组合包 patch、图标、插件展示用的标题与简介 |
+| `scripts/build-client.mjs` | 构建脚本：打包，并校验产物仍然满足注册契约 |
+| `tests/` | `node --test`：纯函数单测、组件渲染测试（含轻弹窗与插件页）、产物冒烟、以及产物与源码是否一致 |
+
+**为什么必须是单个文件**：DSH 的客户端模块系统只把**一个自包含 bundle** 交给插件（`window.__ModuleLoader__.load({ id, factory })`），factory 里的 `require` 只能解析 `react` 这类平台模块，**不能** require 同一个包里的相对文件。所以源码拆成模块之后，必须再打包回单文件——官方客户端插件（例如 `dsh-experimental-client-ui-voice-input`）也是这个形态：`src/**` 源码 + 构建出的客户端 bundle。
+
+维护者命令：
+
+```bash
+pnpm install     # 只装 esbuild 一个 devDependency
+pnpm run build   # 从 src/client 重新生成 client.js —— 改完源码必须跑
+pnpm test        # node --test
+```
+
+- **不要直接改 `client.js`**：它每次构建都会被覆盖；改完 `src/` 忘记重新构建，`tests/bundle.test.js` 会直接报「产物已过期」。
+- 改完产物后，正在运行的 DSH 里要在插件页把这一行**停用再启用**（或重启 DSH）：宿主对客户端 bundle 有缓存，只刷新页面不一定重新读取它。
+
 ## License
 
 [MIT](LICENSE)