dsh-plugin-dingtalk-bridge 0.3.8 → 0.4.0

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.
package/README.md CHANGED
@@ -27,6 +27,8 @@
27
27
  - **彩色插件图标**:侧边栏与面板标题使用 3D 机器人图标,宿主提供 `GET /icon` 路由,加载失败时回退单色 SVG。
28
28
  - **授权与去重**:默认 `loginMode=loopback`(浏览器授权,**不需要授权码**);`loginReset=true` 时重新授权会先 `dws auth logout --yes` 退出旧组织,只保留本次登录的组织;也支持手动「退出」。
29
29
  - **dws 自动检测 / 安装 / 更新**:插件启动时只做检测,不会偷偷装东西。如果这台机器没有 `dws`,面板顶部会出现一条提示,点 **安装 dws** 即自动安装:有 npm 时执行 `npm install -g dingtalk-workspace-cli`(含 npm 12 会拦掉的 `install.js` 准备步骤),**没有 npm 时直接下载 npm 包 tarball 解压到插件数据目录**(自带纯 Node 解压器,不依赖系统 tar),两条路径都会自动定位 `vendor/dws.exe`。已装的话点 **检查更新** 能看到最新版本,再点 **更新到 vX** 升级。收件箱提示卡与设置页按钮都能触发,npm 源可用 `dwsRegistry` 换成国内镜像。
30
+ - **安装进度可见**:安装时卡片会显示 **五步清单**(读取版本信息 → 下载安装包 → 解压 → 准备可执行文件 → 校验版本),每步带 ✓/◐/○ 与耗时,下载实时显示 MB 与百分比,标题还带「已用时 Ns」;同一版本重复安装直接命中 `dws-cache` 缓存。
31
+ - **「没登录」不等于「dws 坏了」**:dws 可用但还没登录时,面板显示黄点「未登录钉钉 · 点右上角「钉钉授权」」,授权入口照常可用(0.4.0 修掉了旧版 `dws not ready` 死循环)。
30
32
  - **演练模式**:`dryRun=true` 时只预览将发送的内容(`dws --dry-run`),不真正发到钉钉,适合先试跑。
31
33
  - **持久化与自愈**:状态存在 `<DSH_HOME>/integrations/dingtalk-bridge/state.json`(tmp + rename 原子写,mode 0600),图片在 `.../media/`;早于 2020 年或超前一天的时间戳重置为当前时间,旧版 `confirmation_required` 失败记录自动清掉。
32
34
 
@@ -54,11 +56,37 @@
54
56
 
55
57
  ## 前置要求
56
58
 
57
- - DSH `>= 0.2.1-rc.3 < 0.3.0-0`,Node `>= 22.19.0`。
58
- - 本机已安装并登录钉钉工作台 CLI:`dws --version` 能输出版本号(当前验证版本 `1.0.68`)。
59
+ - DSH `>= 0.2.1-rc.3 < 0.3.0-0`,Node `>= 22.19.0`(DSH 自带的 Node 就够用)。
60
+ - **不需要预装 dws**:插件会检测环境,没有 `dws` 时点「安装 dws」即可自动安装(有 npm 走全局安装,**没有 npm 也能装**——直接下载 npm 包解压,并借用 DSH 自带的 Node)。
59
61
  - 首次使用需要一次钉钉授权(面板右上角 **钉钉授权**)。
60
62
 
61
- ## 安装(三步)
63
+ ## 安装(推荐:一句话 / 插件市场)
64
+
65
+ 插件已发布到 npm:`dsh-plugin-dingtalk-bridge`。装法从简到繁三种,任选一种:
66
+
67
+ **方式一 · 让 DSH 自己装(推荐)**
68
+
69
+ 在 DSH 对话框里直接说:
70
+
71
+ > 安装 npm 插件 `dsh-plugin-dingtalk-bridge`,装好后重启
72
+
73
+ 助手会调用 `plugin_manager` 以 npm 包名安装到当前 profile,完成后重启 DSH 即可。
74
+
75
+ **方式二 · 插件市场**
76
+
77
+ DSH → 插件市场(Open Plugin Market)→ 搜索 `dsh-plugin-dingtalk-bridge` 或「钉钉消息自动化」→ 安装 → 重启 DSH。
78
+ (收录申请审核中,暂时搜不到就用方式一。)
79
+
80
+ **方式三 · 手动装 npm 包**
81
+
82
+ ```bash
83
+ npm i -g dsh-plugin-dingtalk-bridge@0.4.0 # 或装到 profile 的 dependencies 里
84
+ ```
85
+
86
+ 然后在 DSH profile 的 `package.json` 的 `dsh.profile.bundles` 里加入 `"dsh-plugin-dingtalk-bridge"`,执行 `pnpm install`,重启 DSH。
87
+
88
+ <details>
89
+ <summary>开发者:从源码目录安装(改代码即时生效)</summary>
62
90
 
63
91
  1. 把插件目录放进本机任意位置,例如 `E:/project/deepseek-tool/dsh-plugin-dingtalk`。
64
92
  2. 在 DSH profile 的 `package.json` 里加 **link 依赖**(不要用 `file:`,`file:` 会复制一份,改源码不生效):
@@ -78,11 +106,16 @@
78
106
 
79
107
  3. 在该 profile 目录执行 `pnpm install --prefer-offline`,然后**重启 DSH**。
80
108
 
109
+ > 注意:npm 版与源码 `link:` 版共用同一个 loader id(`dingtalk-bridge`),**不要同时装**。从源码版切到 npm 版时,先删掉 `link:` 依赖再装。
110
+
111
+ </details>
112
+
81
113
  ## 验证是否装好
82
114
 
83
115
  - 侧边栏出现「钉钉消息」图标,点开后是「钉钉消息自动化」面板。
84
116
  - 设置 → 插件 → 钉钉消息自动化 能看到配置卡片;面板右上角点 **钉钉授权** 能弹出授权框。
85
- - 设置页 **宿主版本** 应与界面版本一致(当前 `0.3.2`);不一致说明宿主代码没重载,重启 DSH。
117
+ - 设置页 **宿主版本** 应与界面版本一致(当前 `0.3.9`);不一致说明宿主代码没重载,重启 DSH。
118
+ - 没装 dws 的机器会看到「未检测到 dws 命令」提示卡,点 **安装 dws** 即可。
86
119
 
87
120
  ## 配置项
88
121
 
package/client.js CHANGED
@@ -24,7 +24,7 @@ window.__ModuleLoader__.load({
24
24
  const POLL_MS = 5000
25
25
  const SOFT_POLL_MS = 30000
26
26
  // 与 package.json 的 version 保持一致:宿主上报的 build 前缀对不上,说明 DSH 还在跑旧宿主代码。
27
- const CLIENT_BUILD = '0.3.8'
27
+ const CLIENT_BUILD = '0.4.0'
28
28
  // 源码仓库(GitHub):Star 与 Issue 入口都指向这里
29
29
  const REPO_URL = 'https://github.com/gcggcg/dsh-plugin-dingtalk-bridge'
30
30
  const ISSUES_URL = `${REPO_URL}/issues`
@@ -171,6 +171,13 @@ window.__ModuleLoader__.load({
171
171
  .dsh-dt-install-log summary{cursor:pointer;color:${C.brand}}
172
172
  .dsh-dt-install-log pre{margin:6px 0 0;padding:8px 10px;border-radius:8px;background:${C.layer2};
173
173
  border:1px solid ${C.border1};font-size:11.5px;line-height:1.5;max-height:180px;overflow:auto;white-space:pre-wrap}
174
+ .dsh-dt-steps{margin-top:8px;display:flex;flex-direction:column;gap:3px;font-size:12px;line-height:1.55}
175
+ .dsh-dt-step{display:flex;align-items:baseline;gap:7px;min-width:0}
176
+ .dsh-dt-stepmark{width:12px;flex:none;text-align:center;font-weight:600}
177
+ .dsh-dt-step[data-step="running"] .dsh-dt-stepmark{animation:dsh-dt-pulse 1.1s ease-in-out infinite}
178
+ .dsh-dt-steplabel{flex:none}
179
+ .dsh-dt-stepdetail{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;opacity:.8}
180
+ .dsh-dt-stepms{flex:none;opacity:.6;font-variant-numeric:tabular-nums}
174
181
  .dsh-dt-listbox{margin:0 20px 16px;border:1px solid ${C.border1};border-radius:14px;background:${C.layer1};
175
182
  box-shadow:0 1px 2px rgba(16,24,40,.04);display:flex;flex-direction:column;
176
183
  height:calc(100vh - 330px);min-height:340px;max-height:900px;overflow:hidden}
@@ -1148,7 +1155,20 @@ window.__ModuleLoader__.load({
1148
1155
  const expiredNote = expired > 0 ? ` · ${expired} 个组织登录已过期,建议重新授权` : ''
1149
1156
  if (!state || !state.enabled) return { dot: 'error', text: '插件已禁用', detail: '在设置 → 插件中启用后可用' }
1150
1157
  if (!state.tool || !state.tool.ok) {
1151
- return { dot: 'error', text: 'dws 未就绪', detail: state.tool && state.tool.error ? state.tool.error : '请检查 dws 是否已安装并登录' }
1158
+ return {
1159
+ dot: 'error',
1160
+ text: 'dws 未就绪',
1161
+ detail: state.tool && state.tool.error ? state.tool.error : '请先在下方提示卡里点「安装 dws」',
1162
+ }
1163
+ }
1164
+ const profileCount = Array.isArray(state.profiles) ? state.profiles.length : 0
1165
+ if (profileCount === 0) {
1166
+ // dws 能用但还没登录钉钉:这不是故障,引导去授权,别显示成「dws 未就绪」。
1167
+ return {
1168
+ dot: 'connecting',
1169
+ text: '未登录钉钉',
1170
+ detail: state.loginNotice || '点右上角「钉钉授权」,扫码或登录后即可开始接收私信与群 @',
1171
+ }
1152
1172
  }
1153
1173
  if (online.length > 0) {
1154
1174
  return {
@@ -1323,16 +1343,29 @@ window.__ModuleLoader__.load({
1323
1343
  const latest = String(install.latestVersion || '')
1324
1344
  const updateAvailable = Boolean(status === 'ready' && latest && current && latest !== current)
1325
1345
  const ready = Boolean(tool.ok)
1326
- if (ready && !updateAvailable) return null
1346
+ const steps = Array.isArray(install.steps) ? install.steps : []
1347
+ const running = steps.some((step) => step.status === 'running')
1348
+ const startedAt = Number(install.startedAt) || 0
1349
+ // 安装中每秒刷新一次「已用时」,用户能直观看到还在动。
1350
+ const [, tickNow] = useState(Date.now())
1351
+ useEffect(() => {
1352
+ if (!running) return undefined
1353
+ const timer = setInterval(() => tickNow(Date.now()), 1000)
1354
+ return () => clearInterval(timer)
1355
+ }, [running])
1356
+ if (ready && !updateAvailable && steps.length === 0) return null
1327
1357
 
1328
1358
  const source = String(install.source || '配置的 npm 源')
1329
1359
  const busy = props.busy || ''
1330
1360
  const installing = status === 'installing' || busy === 'install-dws' || busy === 'update-dws'
1331
1361
  const failed = status === 'error'
1332
1362
  const tone = failed ? C.error : installing ? C.brand : C.warn
1363
+ const elapsed = startedAt > 0 ? Math.max(0, Math.round((Date.now() - startedAt) / 1000)) : 0
1364
+ const currentStep = steps.find((step) => step.status === 'running')
1365
+ const doneCount = steps.filter((step) => step.status === 'done').length
1333
1366
 
1334
1367
  const headline = installing
1335
- ? `正在安装 dws${install.targetVersion ? ` v${install.targetVersion}` : ''}…`
1368
+ ? `正在安装 dws${install.targetVersion ? ` v${install.targetVersion}` : ''}${currentStep ? ` · ${currentStep.label}` : ''}`
1336
1369
  : failed
1337
1370
  ? 'dws 安装 / 更新失败'
1338
1371
  : ready
@@ -1340,13 +1373,49 @@ window.__ModuleLoader__.load({
1340
1373
  : '未检测到 dws 命令'
1341
1374
 
1342
1375
  const body = installing
1343
- ? '安装过程通常需要 10~60 秒,完成后会自动重新检测并开始接收消息。'
1376
+ ? `第 ${Math.min(doneCount + 1, steps.length || 1)}/${steps.length || 1} 步${currentStep && currentStep.detail ? ` · ${currentStep.detail}` : ''} · 已用时 ${elapsed}s。装完会自动重新检测并开始接收消息。`
1344
1377
  : failed
1345
1378
  ? String(install.log || tool.error || '安装失败,请查看下面的日志。').slice(0, 600)
1346
1379
  : ready
1347
1380
  ? `更新后会重启监听,登录状态不受影响。安装来源:${source}`
1348
1381
  : `这个插件通过 dws CLI 收发钉钉消息。点「安装 dws」会自动安装 dingtalk-workspace-cli(来源:${source}):有 npm 时走全局安装,没有 npm 时直接下载安装包解压到插件数据目录,全程无需你手动配置。`
1349
1382
 
1383
+ const stepIcon = (stepStatus) =>
1384
+ stepStatus === 'done' ? '✓' : stepStatus === 'running' ? '◐' : stepStatus === 'error' ? '✗' : stepStatus === 'skipped' ? '–' : '○'
1385
+
1386
+ const stepList =
1387
+ steps.length === 0
1388
+ ? null
1389
+ : h(
1390
+ 'div',
1391
+ { className: 'dsh-dt-steps' },
1392
+ steps.map((step) =>
1393
+ h(
1394
+ 'div',
1395
+ {
1396
+ key: step.key,
1397
+ className: 'dsh-dt-step',
1398
+ 'data-step': step.status,
1399
+ style: {
1400
+ color:
1401
+ step.status === 'error'
1402
+ ? C.error
1403
+ : step.status === 'running'
1404
+ ? C.brand
1405
+ : step.status === 'done'
1406
+ ? C.text
1407
+ : C.sub,
1408
+ opacity: step.status === 'pending' || step.status === 'skipped' ? 0.6 : 1,
1409
+ },
1410
+ },
1411
+ h('span', { className: 'dsh-dt-stepmark' }, stepIcon(step.status)),
1412
+ h('span', { className: 'dsh-dt-steplabel' }, step.label),
1413
+ step.detail ? h('span', { className: 'dsh-dt-stepdetail' }, step.detail) : null,
1414
+ step.ms > 0 ? h('span', { className: 'dsh-dt-stepms' }, `${(step.ms / 1000).toFixed(1)}s`) : null,
1415
+ ),
1416
+ ),
1417
+ )
1418
+
1350
1419
  return h(
1351
1420
  'div',
1352
1421
  { className: 'dsh-dt-install', 'data-tone': failed ? 'error' : installing ? 'busy' : 'warn' },
@@ -1356,6 +1425,7 @@ window.__ModuleLoader__.load({
1356
1425
  { style: { minWidth: 0, flex: 1 } },
1357
1426
  h('div', { className: 'dsh-dt-install-title' }, headline),
1358
1427
  h('div', { className: 'dsh-dt-install-body' }, body),
1428
+ stepList,
1359
1429
  failed && install.log && install.log.length > 600
1360
1430
  ? h('details', { className: 'dsh-dt-install-log' }, h('summary', null, '查看完整日志'), h('pre', null, install.log))
1361
1431
  : null,
Binary file
@@ -43,35 +43,69 @@
43
43
 
44
44
  ### 1.1 前置检查
45
45
 
46
- 在终端依次确认三件事,全部通过再安装插件。
46
+ 插件已发布到 npm(`dsh-plugin-dingtalk-bridge`),**普通使用只需要三件事**:
47
+
48
+ | 检查项 | 要求 | 不满足怎么办 |
49
+ | --- | --- | --- |
50
+ | DSH 版本 | `>= 0.2.1-rc.3 < 0.3.0-0` | 升级 DSH |
51
+ | Node | `>= 22.19.0`(DSH 自带的就够) | 一般无需单独安装 |
52
+ | dws | **可以不装** | 装好插件后在面板里点 **安装 dws**,插件会自动装(没有 npm 也能装) |
53
+
54
+ 也就是说,**不需要事先在终端里 `npm i -g dingtalk-workspace-cli`,也不需要自己配 `dwsPath`**。只有想手动排障时,才需要下面这些命令:
47
55
 
48
56
  ```bash
49
57
  # 1) Node 版本(要求 >= 22.19.0)
50
58
  node -v
51
59
 
52
- # 2) dws 是否可用(要求已 npm i -g dingtalk-workspace-cli)
60
+ # 2) dws 是否可用(插件会自动安装,这里只是自查)
53
61
  dws --version
54
62
 
55
- # 3) 是否已有可用登录态
63
+ # 3) 是否已有可用登录态(没有就在面板里点「钉钉授权」)
56
64
  dws profile list -f json
57
65
  ```
58
66
 
59
- `dws profile list -f json` 会输出 `currentProfile` 与 `profiles` 数组;每个 profile 形如 `corpId:userId`,并带 `corpName`、`userName`、`status` 字段。**至少要有一个 `status` 为 `active` 的组织**。
67
+ `dws profile list -f json` 会输出 `currentProfile` 与 `profiles` 数组;每个 profile 形如 `corpId:userId`,并带 `corpName`、`userName`、`status` 字段。
68
+
69
+ 若没有任何 profile,可以直接在面板里点 **钉钉授权**(推荐,默认 `loginMode=loopback`,弹框自动打开浏览器授权页,本机 `127.0.0.1:<port>/callback` 回调,**不需要授权码、不显示二维码**;远程环境把 `loginMode` 改成 `device` 才显示二维码 + 授权码)。详见 [第 8 节](#8-钉钉授权登录)。
60
70
 
61
- 若没有任何 profile:
71
+ 也可以在终端手动授权:
62
72
 
63
73
  ```bash
64
- # 本机浏览器授权(推荐,桌面环境):自动打开授权页,扫码或账号密码登录即可,不需要授权码
74
+ # 本机浏览器授权(推荐,桌面环境)
65
75
  dws auth login --no-browser --yes
66
76
 
67
77
  # 设备流授权:终端打印授权码 + 链接,适合没有图形界面的远程环境
68
78
  dws auth login --device --no-browser
69
79
  ```
70
80
 
71
- > 也可以先装好插件,再在收件箱面板右上角点 **钉钉授权** 完成同样的授权:默认 `loginMode=loopback`,弹框会自动打开浏览器授权页(本机 `127.0.0.1:<port>/callback` 回调),**全程不需要授权码、不显示二维码**;远程环境把 `loginMode` 改成 `device` 才会显示二维码 + 授权码。详见 [第 8 节](#8-钉钉授权登录)。
72
-
73
81
  ### 1.2 安装插件
74
82
 
83
+ 三种装法,从简到繁任选一种,**都不需要手工改配置文件**。
84
+
85
+ #### 方式一 · 让 DSH 自己装(推荐)
86
+
87
+ 在 DSH 对话框里直接说:
88
+
89
+ > 安装 npm 插件 `dsh-plugin-dingtalk-bridge`,装好后重启
90
+
91
+ 助手会用 `plugin_manager` 把 npm 包装进当前 profile,然后重启 DSH 即可。
92
+
93
+ #### 方式二 · 插件市场
94
+
95
+ DSH → **插件市场**(Open Plugin Market)→ 搜索 `dsh-plugin-dingtalk-bridge` 或「钉钉消息自动化」→ **安装** → 重启 DSH。
96
+ (收录申请审核中,暂时搜不到就用方式一。)
97
+
98
+ #### 方式三 · 手动装 npm 包
99
+
100
+ ```bash
101
+ npm i -g dsh-plugin-dingtalk-bridge@0.4.0
102
+ ```
103
+
104
+ 或者把 `"dsh-plugin-dingtalk-bridge": "^0.4.0"` 加进 DSH profile 的 `dependencies`、并把包名追加到 `dsh.profile.bundles`,然后 `pnpm install`,最后**完全退出 DSH 再启动**。
105
+
106
+ <details>
107
+ <summary><b>开发者:从源码目录安装(改代码即时生效)</b></summary>
108
+
75
109
  1. **放好目录**。把插件目录放到任意位置(示例:`E:/project/deepseek-tool/dsh-plugin-dingtalk`)。
76
110
  2. **登记到 DSH profile**。编辑 `<DSH_HOME>/profiles/<profile>/package.json`:
77
111
  - `dependencies` 里加 **`link:`** 依赖;
@@ -100,14 +134,12 @@ dws auth login --device --no-browser
100
134
  >
101
135
  > 两种协议都要**重启 DSH**(完全退出进程再启动),仅刷新页面不够。
102
136
 
103
- 3. **安装依赖**:在 profile 目录执行
137
+ 3. **安装依赖**:在 profile 目录执行 `pnpm install`。
138
+ 4. **重启 DSH**:完全退出 DSH 再启动,改动才会生效(仅刷新页面不够)。
104
139
 
105
- ```bash
106
- pnpm install
107
- ```
140
+ > npm 版与源码 `link:` 版共用同一个 loader id(`dingtalk-bridge`),**不要同时装**;从源码版切到 npm 版时先删掉 `link:` 依赖。
108
141
 
109
- 4. **重启 DSH**:完全退出 DSH 再启动,改动才会生效(仅刷新页面不够)。
110
- 5. **完成授权**:打开收件箱面板,点右上角 **钉钉授权**,弹框会自动打开浏览器授权页,扫码或账号密码登录即可完成(默认 loopback,不需要授权码,详见 [第 8 节](#8-钉钉授权登录))。已经有 `dws auth login` 登录态的可跳过这一步。
142
+ </details>
111
143
 
112
144
  ### 1.3 确认插件已加载
113
145
 
@@ -125,7 +157,8 @@ dws auth login --device --no-browser
125
157
  | 状态文案 | 含义 | 处理 |
126
158
  | --- | --- | --- |
127
159
  | **插件已禁用** | `enabled` 为 `false` | 到「设置 → 插件」启用后重启 DSH |
128
- | **dws 未就绪** | `dws --version` 失败,或没有登录态(详情为 dws 返回的错误与「尚未登录钉钉」提示) | 未登录先点 **钉钉授权**([第 8 节](#8-钉钉授权登录));其余见 [10.1](#101-顶部显示dws-未就绪) |
160
+ | **dws 未就绪** | `dws --version` 跑不起来(命令不存在或报错) | 面板顶部会有「未检测到 dws 命令」提示卡,先点 **安装 dws**;其余见 [10.1](#101-顶部显示dws-未就绪) |
161
+ | **未登录钉钉** | dws 可用,但还没有登录组织(新机器首次使用就是这样) | 点右上角 **钉钉授权**,扫码或登录即可([第 8 节](#8-钉钉授权登录));此时授权入口**是可用的**,见 [10.1.2](#1012-点钉钉授权提示-dws-not-ready040-已修) |
129
162
  | **正在连接钉钉…** | 监听进程已启动、还没就绪 | 等几秒;长期停留见 [10.2](#102-顶部显示监听异常或一直正在连接钉钉) |
130
163
  | **监听异常** | 监听进程报错或已退出 | 点右上角 **重启监听**;仍有问题见 [10.2](#102-顶部显示监听异常或一直正在连接钉钉) |
131
164
 
@@ -137,7 +170,7 @@ dws auth login --device --no-browser
137
170
  2. 首次打开时列表可能是三块灰色骨架屏,表示正在拉取状态;服务连不上会显示 **无法连接插件服务**。
138
171
  3. 如果顶部显示 **dws 未就绪**、右上角 **钉钉授权** 是蓝色主按钮,先点它完成授权([第 8 节](#8-钉钉授权登录)):弹框会说明「在浏览器里完成一次授权」并自动打开授权页,扫码或账号密码登录即可(默认 loopback,不用授权码);授权成功后弹框自动关闭,状态变成 **实时监听中 · N 个组织**。
139
172
  4. 空收件箱显示 **还没有收到消息**,说明为:*保持页面打开即可。当有人给你发钉钉私信或在群里 @ 你时,消息会实时出现在这里。*
140
- 5. 建议先点右上角 **使用说明** 看一遍内置的六条速查(接收 / 消息源 / 自动回复开关 / 阴影建议 / 快捷键 / 发送通道),再按第 2 节熟悉布局。
173
+ 5. 建议先点右上角 **使用说明** 看一遍内置速查(授权 / 接收 / 消息源 / 自动回复开关 / 阈值 / 匹配度 / 图片 / 上下文 / 阴影建议 / 快捷键 / 发送通道 / dws 环境等),再按第 2 节熟悉布局。
141
174
 
142
175
  ---
143
176
 
@@ -1335,13 +1368,23 @@ dws 版本 1.0.68
1335
1368
  | 情形 | 面板表现 | 点哪里 |
1336
1369
  | --- | --- | --- |
1337
1370
  | 本机没有 `dws` 命令 | 提示卡「未检测到 dws 命令」,附当前 `dwsPath` 与 npm 源 | **安装 dws** → 有 npm 走全局安装,没有 npm 直接下载安装包解压 |
1338
- | 正在安装 | 提示卡变蓝色「正在安装 dws vX…」 | 等 10~120 秒(免 npm 方式要下整包),装完自动重新检测并开始接收 |
1371
+ | 正在安装 | 提示卡变蓝色,标题带当前步骤,正文「第 3/5 步 · 已解压 1850 个文件 · 已用时 23s」,下面是 **五步清单**(读取版本信息 → 下载安装包 → 解压 → 准备可执行文件 → 校验版本),每一步有 ✓ / ◐ / ○ 与各自耗时 | 不用点,看着进度走完即可;装完自动重新检测并开始接收 |
1339
1372
  | 装完仍不可用 | 提示卡变红色「dws 安装 / 更新失败」+ 折叠日志 | 展开 **查看完整日志**,多数是网络 / 权限问题 |
1340
1373
  | 已安装,npm 上有新版 | 提示卡「发现新版本 dws vY(当前 vX)」 | **更新到 vY**(会先弹确认框,更新后重启监听,登录态不受影响) |
1341
1374
  | 已是最新 | 提示卡不显示 | 想手动再查一次就去设置页点 **检查 dws 更新** |
1342
1375
 
1343
1376
  ![dws 未安装时的提示卡](images/dws-install.png)
1344
1377
 
1378
+ **安装过程是可见的(0.4.0 起)**:界面会实时显示走到第几步、每步在做什么、已经用了多少秒,不会出现「点了没反应、不知道卡在哪」的情况。各步含义:
1379
+
1380
+ | 步骤 | 在做什么 | 典型耗时 |
1381
+ | --- | --- | --- |
1382
+ | 读取版本信息 | 请求 `<dwsRegistry>/dingtalk-workspace-cli/latest` 拿版本号与包地址 | < 1s |
1383
+ | 下载安装包 | 下载约 30 MB 的 tarball,**实时显示已下载 MB 与百分比**;同一个版本第二次装会直接命中本地缓存 `<数据目录>/dws-cache/*.tgz` | 10~120s(取决于网速;命中缓存 < 1s) |
1384
+ | 解压安装包 | 纯 Node 解压器把 tar.gz 摊开,实时显示「已解压 N 个文件」 | 3~20s |
1385
+ | 准备 dws 可执行文件 | 跑包内 `install.js`,把当前平台的二进制解压到 `vendor/` | 2~15s |
1386
+ | 校验 dws 版本 | `dws --version` 读出版本号,写回 `dwsPath` 并开始监听 | < 1s |
1387
+
1345
1388
  **两处都能装**:收件箱顶部的提示卡,以及 **设置 → 插件配置 → 底部按钮区**(「安装 dws」「检查 dws 更新」「更新到 vX」)。没装 dws 时点「钉钉授权」不会再去执行命令报错,而是直接提示「请先安装 dws」。
1346
1389
 
1347
1390
  实现要点(便于排障时对照):
@@ -1394,6 +1437,22 @@ dws profile list -f json # 查看当前组织与 status(只有 active 会
1394
1437
 
1395
1438
  > 登录态已过期(`status` 不是 `active`)的组织不再被监听,面板会提示「· N 个组织登录已过期,建议重新授权」。
1396
1439
 
1440
+ ### 10.1.2 点「钉钉授权」提示 `dws not ready`(0.4.0 已修)
1441
+
1442
+ **现象**:新机器上 dws 明明装好了(设置页「dws 版本 1.0.68」「dws 安装状态 已就绪」),点「钉钉授权」却弹「连接提示:dws not ready」,怎么点都进不去授权页。
1443
+
1444
+ **原因**:旧版把「还没登录钉钉」和「dws 不可用」混成了同一个 `tool.ok=false`。新机器首次使用必然没有登录组织 → 插件认为 dws 不可用 → 授权入口被自己的前置检查挡住 → 死循环。
1445
+
1446
+ **现在(0.4.0 起)**:
1447
+
1448
+ | 状态 | 面板显示 | 能否点授权 |
1449
+ | --- | --- | --- |
1450
+ | dws 命令不可用 | 红点「dws 未就绪 · <具体错误>」 | 不能(会提示先点「安装 dws」) |
1451
+ | dws 可用、还没登录 | 黄点「**未登录钉钉** · 点右上角「钉钉授权」…」 | **能**,点开就是授权页 |
1452
+ | dws 可用、已登录 | 绿点「实时监听中 · N 个组织」 | 能(按钮变「重新授权」) |
1453
+
1454
+ 如果你还在旧版本:重启 DSH 升级到 0.4.0 即可;临时绕过办法是先用命令行登录一次(`dws auth login --no-browser --yes`),有了登录组织后授权入口就能用了。
1455
+
1397
1456
  ### 10.2 顶部显示「监听异常」或一直「正在连接钉钉…」
1398
1457
 
1399
1458
  先点面板右上角 **重启监听**(等价于重跑 `dws --version` + 重建全部监听)。仍然不行时在终端核对订阅状态:
@@ -1834,7 +1893,8 @@ dws chat +messages-send --as user --group cidAbCdEf123456= --text "收到,下
1834
1893
  | `build` | string | 宿主代码编译标记(如 `0.2.9-20261117T0940`),设置页「宿主版本」显示它;与界面版本不一致时面板头部会多一个 **宿主待重启** 徽标 |
1835
1894
  | `requests` | `Array<{ at, method, path, status, detail }>` | 最近 8 条 API 请求,便于排查写操作被拦、阈值没保存之类的问题 |
1836
1895
  | `lastError` | string | 最近一次失败请求的摘要,如 `POST /api/dingtalk-bridge/action → 403` |
1837
- | `install` | object | dws 安装 / 更新状态:`status`(`unknown`/`missing`/`installing`/`ready`/`error`)、`mode`(`npm` 或 `tarball`)、`currentVersion`、`latestVersion`、`updateAvailable`、`targetVersion`、`source`(npm 源)、`log`(失败日志尾部)、`latestError`、`checkedAt`。见 [10.0](#100-dws-没安装--想升级036-起支持免-npm) |
1896
+ | `install` | object | dws 安装 / 更新状态:`status`(`unknown`/`missing`/`installing`/`ready`/`error`)、`mode`(`npm` 或 `tarball`)、`currentVersion`、`latestVersion`、`updateAvailable`、`targetVersion`、`source`(npm 源)、`log`(失败日志尾部)、`latestError`、`steps`(`[{ key, label, status, detail, ms }]`,`status` 为 `pending`/`running`/`done`/`error`/`skipped`)、`startedAt`/`finishedAt`(毫秒时间戳,界面据此算「已用时」)、`checkedAt`。见 [10.0](#100-dws-没安装--想升级036-起支持免-npm) |
1897
+ | `loginNotice` | string | 「还没登录钉钉」的提示文案(与 `tool.ok` 分开:没登录不是 dws 故障)。为空表示已有可用登录组织。见 [10.1.2](#1012-点钉钉授权提示-dws-not-ready040-已修) |
1838
1898
 
1839
1899
  ### 12.3 关键常量
1840
1900
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-dingtalk-bridge",
3
- "version": "0.3.8",
3
+ "version": "0.4.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "钉钉私信 / 群 @ 消息实时接收、按发送人记录来源、AI 建议回复与自动回复插件",
@@ -49,13 +49,14 @@ function safeRelativePath(raw) {
49
49
  * npm 包里的顶层目录通常是 `package/`,这里会把 `package/` 前缀剥掉,
50
50
  * 让调用方拿到 `<destDir>/package.json`、`<destDir>/install.js` 这样的结构。
51
51
  */
52
- export async function extractTarGz(buffer, destDir) {
52
+ export async function extractTarGz(buffer, destDir, onProgress) {
53
53
  const tar = gunzipSync(buffer)
54
54
  let offset = 0
55
55
  let pendingPath = ''
56
56
  let pendingLink = ''
57
57
  let longName = ''
58
58
  const written = []
59
+ const report = typeof onProgress === 'function' ? onProgress : null
59
60
 
60
61
  while (offset + BLOCK <= tar.length) {
61
62
  const header = tar.subarray(offset, offset + BLOCK)
@@ -106,6 +107,7 @@ export async function extractTarGz(buffer, destDir) {
106
107
  const mode = readOctal(header, 100, 8)
107
108
  await writeFile(target, data, { mode: mode > 0 ? mode : 0o644 })
108
109
  written.push(withoutPackage)
110
+ if (report && written.length % 50 === 0) report(written.length)
109
111
  }
110
112
 
111
113
  return written
@@ -21,7 +21,7 @@ import { buildSuggestPrompt, generateSuggestion, formatClock } from './suggest.j
21
21
 
22
22
  export const ROUTE_PREFIX = '/api/dingtalk-bridge'
23
23
  /** 每次改动宿主行为就换个标记:界面与 http-debug.log 都会带上,用来确认「跑的是新代码」。 */
24
- export const HOST_BUILD = '0.3.8-20261117T1545'
24
+ export const HOST_BUILD = '0.4.0-20261117T1645'
25
25
 
26
26
  /** 私信(单聊)全部消息。 */
27
27
  const O2O_KEY = 'user_im_message_receive_o2o_all'
@@ -371,6 +371,8 @@ export class DingTalkBridgeService {
371
371
  selfName: '',
372
372
  currentProfile: '',
373
373
  profiles: [],
374
+ // 「还没登录钉钉」的提示。和 tool.ok 分开:没登录不是 dws 坏了。
375
+ loginNotice: '',
374
376
  }
375
377
 
376
378
  this.tool = { ok: false, version: '', error: '', checkedAt: 0 }
@@ -385,9 +387,14 @@ export class DingTalkBridgeService {
385
387
  source: '',
386
388
  log: '',
387
389
  latestError: '',
390
+ // 安装步骤(进度):[{ key, label, status, detail, ms }]
391
+ steps: [],
392
+ startedAt: 0,
393
+ finishedAt: 0,
388
394
  checkedAt: 0,
389
395
  }
390
396
  this.installPromise = null
397
+ this.stepClock = new Map()
391
398
  this.login = { status: 'idle', code: '', url: '', qr: '', startedAt: 0, error: '', message: '' }
392
399
  this.loginChild = null
393
400
  this.listeners = new Map()
@@ -525,6 +532,41 @@ export class DingTalkBridgeService {
525
532
  return this.install
526
533
  }
527
534
 
535
+ /** 开始一次安装:把步骤清单重置为 pending,并记下开始时间(界面据此显示进度与耗时)。 */
536
+ beginInstallSteps(steps) {
537
+ this.stepClock = new Map()
538
+ this.setInstall({
539
+ steps: steps.map(([key, label]) => ({ key, label, status: 'pending', detail: '', ms: 0 })),
540
+ startedAt: Date.now(),
541
+ finishedAt: 0,
542
+ })
543
+ }
544
+
545
+ /** 更新某个安装步骤的状态;running / done / error 会记下该步骤耗时。 */
546
+ markStep(key, status, detail = '') {
547
+ const now = Date.now()
548
+ if (status === 'running' && !this.stepClock.has(key)) this.stepClock.set(key, now)
549
+ const startedAt = this.stepClock.get(key) ?? 0
550
+ const steps = (this.install.steps ?? []).map((step) => {
551
+ if (step.key !== key) return step
552
+ const next = { ...step, status }
553
+ if (detail !== '') next.detail = detail
554
+ if ((status === 'done' || status === 'error') && startedAt > 0) next.ms = now - startedAt
555
+ return next
556
+ })
557
+ this.setInstall({ steps })
558
+ }
559
+
560
+ /** 安装结束:没走到的步骤标成 skipped,失败的当前步标成 error,并记下结束时间。 */
561
+ finishInstallSteps(ok) {
562
+ const steps = (this.install.steps ?? []).map((step) => {
563
+ if (step.status === 'done' || step.status === 'error' || step.status === 'skipped') return step
564
+ if (step.status === 'running') return { ...step, status: ok ? 'done' : 'error' }
565
+ return { ...step, status: 'skipped' }
566
+ })
567
+ this.setInstall({ steps, finishedAt: Date.now() })
568
+ }
569
+
528
570
  /**
529
571
  * 查 npm 上 dingtalk-workspace-cli 的最新版本(只查不装)。
530
572
  * 换源时也走这里,所以界面上「检查更新」按钮可以随时点。
@@ -641,6 +683,11 @@ export class DingTalkBridgeService {
641
683
  return this.installFromTarball(target)
642
684
  }
643
685
 
686
+ this.beginInstallSteps([
687
+ ['npm', 'npm 全局安装'],
688
+ ['prepare', '准备 dws 可执行文件'],
689
+ ['verify', '校验 dws 版本'],
690
+ ])
644
691
  this.setInstall({
645
692
  status: 'installing',
646
693
  mode: 'npm',
@@ -650,10 +697,12 @@ export class DingTalkBridgeService {
650
697
  })
651
698
 
652
699
  const args = buildInstallArgs({ target, registry })
700
+ this.markStep('npm', 'running', 'npm 正在下载并写入全局目录…')
653
701
  const result = await runDws(npm, args, { timeoutMs: INSTALL_TIMEOUT })
654
702
  const output = `${result.stdout}\n${result.stderr}`.trim()
655
703
  if (result.code !== 0) {
656
704
  // npm 装失败(权限、网络、被拦的 postinstall…)同样退到免 npm 方式,别让用户卡住。
705
+ this.markStep('npm', 'error', `npm 退出码 ${result.code}`)
657
706
  this.setInstall({
658
707
  status: 'installing',
659
708
  mode: 'tarball',
@@ -661,22 +710,30 @@ export class DingTalkBridgeService {
661
710
  })
662
711
  return this.installFromTarball(target)
663
712
  }
713
+ this.markStep('npm', 'done', 'npm 安装完成')
664
714
 
665
715
  const root = await this.npmGlobalRoot(npm)
666
716
  const pkgDir = join(root || join(dirname(process.execPath), 'node_modules'), DWS_PACKAGE)
717
+ this.markStep('prepare', 'running', '正在执行包内 install.js(解压平台二进制)…')
667
718
  const postinstallLog = await this.preparePackage(pkgDir)
668
719
  const vendor = join(pkgDir, 'vendor', process.platform === 'win32' ? 'dws.exe' : 'dws')
669
720
  const installed = await runDws(vendor, ['--version'], { timeoutMs: 20_000 })
670
721
  if (installed.code === 0) this.config.dwsPath = vendor
722
+ this.markStep('prepare', 'done', postinstallLog.split('\n').filter(Boolean).at(-1) || '平台二进制已就绪')
671
723
 
724
+ this.markStep('verify', 'running', '正在校验 dws --version…')
672
725
  await this.checkTool()
673
726
  if (!this.tool.ok) {
727
+ this.markStep('verify', 'error', this.tool.error)
728
+ this.finishInstallSteps(false)
674
729
  this.setInstall({
675
730
  status: 'error',
676
731
  log: `${output.slice(-INSTALL_LOG_LIMIT)}\n\n${postinstallLog}\n\n安装完成但 dws 仍不可用:${this.tool.error}`.trim(),
677
732
  })
678
733
  return { ok: false, error: this.tool.error }
679
734
  }
735
+ this.markStep('verify', 'done', `dws v${this.tool.version}`)
736
+ this.finishInstallSteps(true)
680
737
 
681
738
  this.setInstall({
682
739
  status: 'ready',
@@ -718,7 +775,16 @@ export class DingTalkBridgeService {
718
775
  const registry = this.registry().replace(/\/+$/, '')
719
776
  const wanted = String(target ?? '').replace(/^v/, '').trim()
720
777
  const metaUrl = wanted === '' ? `${registry}/${DWS_PACKAGE}/latest` : `${registry}/${DWS_PACKAGE}/${wanted}`
778
+ this.beginInstallSteps([
779
+ ['resolve', '读取版本信息'],
780
+ ['download', '下载安装包'],
781
+ ['extract', '解压安装包'],
782
+ ['prepare', '准备 dws 可执行文件'],
783
+ ['verify', '校验 dws 版本'],
784
+ ])
785
+ this.setInstall({ status: 'installing', mode: 'tarball', source: registry, targetVersion: wanted })
721
786
  try {
787
+ this.markStep('resolve', 'running', '正在查询 npm 上的版本信息…')
722
788
  const metaResponse = await fetch(metaUrl, {
723
789
  headers: { accept: 'application/json' },
724
790
  signal: AbortSignal.timeout(20_000),
@@ -728,23 +794,35 @@ export class DingTalkBridgeService {
728
794
  const url = tarballUrl(meta, DWS_PACKAGE)
729
795
  const version = String(meta?.version ?? wanted ?? '')
730
796
  if (url === '') throw new Error('版本信息里没有安装包地址')
797
+ this.markStep('resolve', 'done', `v${version}`)
731
798
 
732
- const response = await fetch(url, { signal: AbortSignal.timeout(180_000) })
733
- if (!response.ok) throw new Error(`下载安装包失败(HTTP ${response.status})`)
734
- const buffer = Buffer.from(await response.arrayBuffer())
799
+ const buffer = await this.fetchTarball(url, version)
735
800
 
801
+ this.markStep('extract', 'running', '正在解压…')
736
802
  const pkgDir = this.runtimePackageDir()
737
803
  await rm(pkgDir, { recursive: true, force: true })
738
804
  await mkdir(pkgDir, { recursive: true })
739
- const files = await extractTarGz(buffer, pkgDir)
805
+ let lastReport = 0
806
+ const files = await extractTarGz(buffer, pkgDir, (count) => {
807
+ const now = Date.now()
808
+ if (now - lastReport < 300) return
809
+ lastReport = now
810
+ this.markStep('extract', 'running', `已解压 ${count} 个文件`)
811
+ })
812
+ this.markStep('extract', 'done', `${files.length} 个文件`)
740
813
 
814
+ this.markStep('prepare', 'running', '正在执行 install.js(解压平台二进制)…')
741
815
  const postinstallLog = await this.preparePackage(pkgDir)
742
816
  const vendor = join(pkgDir, 'vendor', process.platform === 'win32' ? 'dws.exe' : 'dws')
743
817
  const probe = await runDws(vendor, ['--version'], { timeoutMs: 20_000 })
744
818
  if (probe.code === 0) this.config.dwsPath = vendor
819
+ this.markStep('prepare', 'done', '平台二进制已就绪')
745
820
 
821
+ this.markStep('verify', 'running', '正在校验 dws --version…')
746
822
  await this.checkTool()
747
823
  if (!this.tool.ok) {
824
+ this.markStep('verify', 'error', this.tool.error)
825
+ this.finishInstallSteps(false)
748
826
  this.setInstall({
749
827
  status: 'error',
750
828
  mode: 'tarball',
@@ -752,6 +830,8 @@ export class DingTalkBridgeService {
752
830
  })
753
831
  return { ok: false, error: this.tool.error }
754
832
  }
833
+ this.markStep('verify', 'done', `dws v${this.tool.version}`)
834
+ this.finishInstallSteps(true)
755
835
 
756
836
  this.setInstall({
757
837
  status: 'ready',
@@ -766,6 +846,7 @@ export class DingTalkBridgeService {
766
846
  return { ok: true, version: this.tool.version, mode: 'tarball' }
767
847
  } catch (error) {
768
848
  const message = String(error?.message || error)
849
+ this.finishInstallSteps(false)
769
850
  this.setInstall({
770
851
  status: 'error',
771
852
  mode: 'tarball',
@@ -775,6 +856,60 @@ export class DingTalkBridgeService {
775
856
  }
776
857
  }
777
858
 
859
+ /** 下载 tarball:优先用本地缓存(<dataDir>/dws-cache),否则带进度下载后写入缓存。 */
860
+ async fetchTarball(url, version) {
861
+ const cacheDir = join(this.dataDir(), 'dws-cache')
862
+ const cachePath = join(cacheDir, `${DWS_PACKAGE}-${version || 'latest'}.tgz`)
863
+ try {
864
+ const cached = await readFile(cachePath)
865
+ if (cached.length > 1024) {
866
+ this.markStep('download', 'done', `使用本地缓存(${(cached.length / 1048576).toFixed(1)} MB)`)
867
+ return cached
868
+ }
869
+ } catch {
870
+ // 没有缓存就正常下载。
871
+ }
872
+
873
+ this.markStep('download', 'running', '正在连接 npm 源…')
874
+ const response = await fetch(url, { signal: AbortSignal.timeout(180_000) })
875
+ if (!response.ok) throw new Error(`下载安装包失败(HTTP ${response.status})`)
876
+ const total = Number(response.headers.get('content-length') ?? 0)
877
+ const chunks = []
878
+ let received = 0
879
+ let lastReport = 0
880
+ if (response.body && typeof response.body.getReader === 'function') {
881
+ const reader = response.body.getReader()
882
+ for (;;) {
883
+ const { done, value } = await reader.read()
884
+ if (done) break
885
+ if (!value) continue
886
+ chunks.push(Buffer.from(value))
887
+ received += value.length
888
+ const now = Date.now()
889
+ if (now - lastReport > 300) {
890
+ lastReport = now
891
+ const mb = (received / 1048576).toFixed(1)
892
+ const percent = total > 0 ? ` · ${Math.round((received / total) * 100)}%` : ''
893
+ this.markStep('download', 'running', `已下载 ${mb} MB${percent}`)
894
+ }
895
+ }
896
+ } else {
897
+ const whole = Buffer.from(await response.arrayBuffer())
898
+ chunks.push(whole)
899
+ received = whole.length
900
+ }
901
+ const buffer = Buffer.concat(chunks)
902
+ if (buffer.length === 0) throw new Error('下载到的安装包是空的')
903
+ this.markStep('download', 'done', `${(buffer.length / 1048576).toFixed(1)} MB`)
904
+ try {
905
+ await mkdir(cacheDir, { recursive: true })
906
+ await writeFile(cachePath, buffer)
907
+ } catch {
908
+ // 缓存写不进去不影响安装。
909
+ }
910
+ return buffer
911
+ }
912
+
778
913
  /** 「更新 dws」:先查最新版,再按版本号安装。 */
779
914
  async updateDws() {
780
915
  const latest = await this.checkLatestDws()
@@ -835,15 +970,17 @@ export class DingTalkBridgeService {
835
970
  this.state.selfName = current?.userName || this.state.selfName || ''
836
971
 
837
972
  if (profiles.length === 0) {
838
- this.tool = {
839
- ok: false,
840
- version: this.tool.version,
841
- error: result.code === 0 ? '未找到已登录的钉钉组织,请点击右上角「钉钉授权」登录' : describeFailure(result),
842
- checkedAt: Date.now(),
973
+ // 注意:这里**不能**把 tool.ok 置 false。tool.ok 只表示「dws 二进制能不能用」,
974
+ // 「还没登录钉钉」是另一种状态——否则 startLogin() 的前置检查会认为 dws 不可用,
975
+ // 用户就永远点不动「钉钉授权」(新机器上首次授权必然如此)。
976
+ this.state.loginNotice =
977
+ result.code === 0 ? '未找到已登录的钉钉组织,请点击右上角「钉钉授权」登录' : describeFailure(result)
978
+ } else {
979
+ this.state.loginNotice = ''
980
+ if (!this.tool.ok) {
981
+ // 重新授权成功后要把「dws 未就绪」的旧结论翻回来,否则面板一直显示错误态。
982
+ this.tool = { ok: true, version: this.tool.version, error: '', checkedAt: Date.now() }
843
983
  }
844
- } else if (!this.tool.ok) {
845
- // 重新授权成功后要把「dws 未就绪」的旧结论翻回来,否则面板一直显示错误态。
846
- this.tool = { ok: true, version: this.tool.version, error: '', checkedAt: Date.now() }
847
984
  }
848
985
 
849
986
  return profiles
@@ -2547,6 +2684,7 @@ export class DingTalkBridgeService {
2547
2684
  status: item.status,
2548
2685
  })),
2549
2686
  loginReset: this.config.loginReset,
2687
+ loginNotice: String(this.state.loginNotice ?? ''),
2550
2688
  autoReply: this.state.autoReply,
2551
2689
  autoReplyAt: Number(this.state.autoReplyAt) || 0,
2552
2690
  autoSuggest: this.config.autoSuggest,