dsh-dingtalk 0.3.7 → 0.3.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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,10 @@
1
1
  # 更新记录
2
2
 
3
+ ## 0.3.8 (2026-11-03)
4
+
5
+ - health 校验 webhook 形状并显示 secret 来源,仍不触网。
6
+ - Health validates webhook shape and shows where the secret comes from without sending messages.
7
+
3
8
  ## 0.3.7 (2026-10-30)
4
9
 
5
10
  - 重整中英文首页:用途、三步流程图、安装入口与操作示例;详细配置与边界集中到完整说明。
package/docs/USAGE.en.md CHANGED
@@ -119,6 +119,19 @@ pnpm run build # tsc → lib/
119
119
  pnpm test # 构建 + node --test(加签算法/配置解析/客户端封装/注册与中文报错)
120
120
  ```
121
121
 
122
+ ## Troubleshooting
123
+
124
+ Run `dingtalk_health` first: it validates the webhook shape and signing config locally (no messages, no network calls).
125
+
126
+ | Symptom | Usual cause | What to do |
127
+ | :-- | :-- | :-- |
128
+ | `dsh-dingtalk 未配置:webhook …` | No webhook configured | Override the `tool-dingtalk` row in the profile's `cordis.patch.yml` with the full URL, then restart |
129
+ | Health reports a missing `access_token` or a non-DingTalk host | URL copied incompletely or from elsewhere | Re-copy the full webhook from the DingTalk group's custom robot settings |
130
+ | Response `310000` | Sign mismatch, or the robot also enforces a keyword | Check `secret` (prefer the `DSH_DINGTALK_SECRET` env var); in keyword mode the message must contain the keyword |
131
+ | Response `120001` | `access_token` expired or reset | Re-copy the robot webhook and update the config |
132
+ | Request times out | Slow network or proxy | Check the group first to see whether the message arrived before resending; raise `timeoutMs` if needed |
133
+ | Message arrives but renders badly | Markdown dialect or length limits | Simplify the body; DingTalk caps a single message, so split long content |
134
+
122
135
  ## License
123
136
 
124
137
  MIT. This is a community plugin, not affiliated with DeepSeek or DingTalk; `@deepseek-ai/*` is an officially reserved namespace.
package/docs/USAGE.md CHANGED
@@ -102,6 +102,19 @@ sign = urlencode(base64(HmacSHA256(secret, stringToSign)))
102
102
  - **消息类型**:目前只支持 Markdown(`dingtalk_notify`)与纯文本(`dingtalk_text`)两种;图片/Link/FeedCard/ActionCard 等类型后续再加。
103
103
  - **Markdown 渲染**:钉钉机器人 Markdown 语法与标准 Markdown 略有差异(如标题、链接),请按钉钉语法书写。
104
104
 
105
+ ## 故障排查
106
+
107
+ 先运行 `dingtalk_health`:它只在本地校验 webhook 形态与加签配置(不发消息、不触网)。
108
+
109
+ | 现象 | 常见原因 | 处理 |
110
+ | :-- | :-- | :-- |
111
+ | `dsh-dingtalk 未配置:webhook …` | 没填 webhook | 在 profile 的 `cordis.patch.yml` 覆盖 `tool-dingtalk` 行,填完整地址后重启 |
112
+ | 自检提示 `缺少 access_token` / `主机不是 oapi.dingtalk.com` | 地址复制不全,或粘贴了别的 URL | 从钉钉群「自定义机器人」设置里重新复制完整 webhook |
113
+ | 返回 `310000` | 加签不匹配,或机器人同时启用了「自定义关键词」 | 核对 `secret`(建议环境变量 `DSH_DINGTALK_SECRET`);关键词模式要保证消息包含关键词 |
114
+ | 返回 `120001` | access_token 失效或被重置 | 重新复制机器人 webhook 覆盖配置 |
115
+ | 请求超时 | 网络慢或代理问题 | 先核对群消息是否已收到,再决定是否重发;必要时调大 `timeoutMs` |
116
+ | 消息发出但排版不对 | Markdown 语法或长度限制 | 精简正文;钉钉单条消息有长度上限,过长请分段发送 |
117
+
105
118
  ## 错误码速查
106
119
 
107
120
  | errcode | 含义 | 建议 |
package/lib/config.d.ts CHANGED
@@ -18,4 +18,11 @@ export interface ResolvedDingTalkConfig {
18
18
  * 只解析、不失败:secret 可选,未配置加签则不加签。
19
19
  */
20
20
  export declare function resolveDingTalkConfig(config: DingTalkConfig | undefined): ResolvedDingTalkConfig;
21
+ /**
22
+ * 校验 webhook 形态(纯本地判断,不发网络请求)。
23
+ *
24
+ * 只判空会把「粘错 token」「少了 access_token」「用了 http」当成已配置,
25
+ * 直到真正发送失败才暴露;这里按钉钉机器人地址的真实结构逐项给出原因。
26
+ */
27
+ export declare function describeWebhookProblem(webhook: string): string | undefined;
21
28
  export declare function clampInt(value: unknown, fallback: number, min: number, max: number): number;
package/lib/config.js CHANGED
@@ -17,6 +17,33 @@ export function resolveDingTalkConfig(config) {
17
17
  timeoutMs: clampInt(raw.timeoutMs, DEFAULT_TIMEOUT_MS, 1000, 60000),
18
18
  };
19
19
  }
20
+ /**
21
+ * 校验 webhook 形态(纯本地判断,不发网络请求)。
22
+ *
23
+ * 只判空会把「粘错 token」「少了 access_token」「用了 http」当成已配置,
24
+ * 直到真正发送失败才暴露;这里按钉钉机器人地址的真实结构逐项给出原因。
25
+ */
26
+ export function describeWebhookProblem(webhook) {
27
+ if (webhook === '')
28
+ return '未配置 webhook';
29
+ let url;
30
+ try {
31
+ url = new URL(webhook);
32
+ }
33
+ catch {
34
+ return 'webhook 不是合法 URL(应形如 https://oapi.dingtalk.com/robot/send?access_token=...)';
35
+ }
36
+ if (url.protocol !== 'https:')
37
+ return 'webhook 必须使用 https(当前 ' + url.protocol + '//)';
38
+ if (!/^(?:[a-z0-9-]+\.)*oapi\.dingtalk\.com$/i.test(url.hostname))
39
+ return 'webhook 主机不是 oapi.dingtalk.com(当前 ' + url.hostname + ')';
40
+ if (url.pathname !== '/robot/send')
41
+ return 'webhook 路径应为 /robot/send(当前 ' + url.pathname + ')';
42
+ const token = url.searchParams.get('access_token');
43
+ if (token === null || token.trim() === '')
44
+ return 'webhook 缺少 access_token 参数';
45
+ return undefined;
46
+ }
20
47
  export function clampInt(value, fallback, min, max) {
21
48
  const n = typeof value === 'number' ? Math.trunc(value) : fallback;
22
49
  if (!Number.isFinite(n))
package/lib/index.d.ts CHANGED
@@ -3,7 +3,7 @@ export declare const name = "tool-dingtalk";
3
3
  export declare const inject: string[];
4
4
  export type Config = DingTalkConfig;
5
5
  export declare function apply(ctx: any, config?: Config): void;
6
- export { resolveDingTalkConfig, DINGTALK_SECRET_ENV, DEFAULT_TIMEOUT_MS, clampInt } from './config.js';
6
+ export { resolveDingTalkConfig, describeWebhookProblem, DINGTALK_SECRET_ENV, DEFAULT_TIMEOUT_MS, clampInt } from './config.js';
7
7
  export { DingTalkClient, DingTalkError, dingTalkErrorMessage } from './client.js';
8
8
  export type { FetchLike, FetchLikeResponse, DingTalkClientOptions } from './client.js';
9
9
  export { computeDingTalkSign, signedUrl, dingTalkTimestamp } from './sign.js';
package/lib/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { registerUpdates } from '@stardustlc/dsh-updates';
2
- import { resolveDingTalkConfig } from './config.js';
2
+ import { describeWebhookProblem, resolveDingTalkConfig, DINGTALK_SECRET_ENV } from './config.js';
3
3
  import { DingTalkClient } from './client.js';
4
4
  export const name = 'tool-dingtalk';
5
5
  export const inject = ['tools'];
@@ -41,11 +41,15 @@ function executionSignal(exec) {
41
41
  const signal = exec?.signal;
42
42
  return signal instanceof AbortSignal ? signal : undefined;
43
43
  }
44
+ /**
45
+ * 成功回执只留用户需要的信息:发到哪、发了什么标题。
46
+ * 原来把 errcode=0 / errmsg=ok 也摆出来,属于协议噪声;错误路径由 client 抛中文指引。
47
+ */
44
48
  function renderNotify(value) {
45
49
  if (value.msgtype === 'markdown') {
46
- return oneText('已通过钉钉机器人发送 Markdown 消息(标题「' + value.title + '」),钉钉返回 errcode=' + value.errcode + ',errmsg=' + value.errmsg);
50
+ return oneText('已发送 Markdown 消息到钉钉群(标题「' + value.title + '」)。如需核对,请查看群消息。');
47
51
  }
48
- return oneText('已通过钉钉机器人发送文本消息,钉钉返回 errcode=' + value.errcode + ',errmsg=' + value.errmsg);
52
+ return oneText('已发送文本消息到钉钉群。如需核对,请查看群消息。');
49
53
  }
50
54
  export function apply(ctx, config = {}) {
51
55
  registerUpdates(ctx, { name: "dsh-dingtalk" });
@@ -82,9 +86,9 @@ export function apply(ctx, config = {}) {
82
86
  async execute(rawArgs, exec) {
83
87
  const args = rawArgs;
84
88
  if (typeof args.title !== 'string' || args.title.trim() === '')
85
- throw new Error('title 不能为空');
89
+ throw new Error('title 不能为空:请提供显示在钉钉卡片顶部的消息标题。');
86
90
  if (typeof args.text !== 'string' || args.text.trim() === '')
87
- throw new Error('text 不能为空');
91
+ throw new Error('text 不能为空:请提供 Markdown 正文(钉钉单条消息有长度上限,过长请分段发送)。');
88
92
  const result = await getClient().sendMarkdown(args.title, args.text, executionSignal(exec));
89
93
  return { ok: true, msgtype: 'markdown', title: args.title, errcode: result.errcode, errmsg: result.errmsg };
90
94
  },
@@ -103,7 +107,7 @@ export function apply(ctx, config = {}) {
103
107
  async execute(rawArgs, exec) {
104
108
  const args = rawArgs;
105
109
  if (typeof args.content !== 'string' || args.content.trim() === '')
106
- throw new Error('content 不能为空');
110
+ throw new Error('content 不能为空:请提供要发送的纯文本内容。');
107
111
  const result = await getClient().sendText(args.content, executionSignal(exec));
108
112
  return { ok: true, msgtype: 'text', title: '', errcode: result.errcode, errmsg: result.errmsg };
109
113
  },
@@ -122,26 +126,46 @@ export function apply(ctx, config = {}) {
122
126
  const c = (item ?? {});
123
127
  lines.push('- ' + String(c.name) + ':' + (c.ok === true ? '✅ ' + String(c.detail ?? '') : '❌ ' + String(c.detail ?? '')));
124
128
  }
129
+ if (rec.ok !== true) {
130
+ lines.push('', '下一步:');
131
+ lines.push(' · 在 profile 的 cordis.patch.yml 里覆盖 tool-dingtalk 行,填完整 webhook(含 access_token);secret 建议放环境变量 DSH_DINGTALK_SECRET,改完重启 DSH。');
132
+ lines.push(' · 发送失败时先看错误里的钉钉 errcode:310000 是加签不匹配,120001 是 token 失效,按提示改配置后重新运行 dingtalk_health。');
133
+ }
125
134
  return oneText(lines.join('\n'));
126
135
  },
127
136
  },
128
137
  async execute() {
129
138
  const checks = [];
130
139
  let ok = true;
140
+ // 自检只做本地校验:既不发消息,也不触网,避免「自检」把告警群刷屏。
141
+ const webhook = typeof config?.webhook === 'string' ? config.webhook.trim() : '';
142
+ const webhookProblem = describeWebhookProblem(webhook);
143
+ if (webhookProblem === undefined) {
144
+ checks.push({ name: 'webhook', ok: true, detail: '已配置(https://oapi.dingtalk.com/robot/send?access_token=***)' });
145
+ }
146
+ else {
147
+ ok = false;
148
+ checks.push({ name: 'webhook', ok: false, detail: webhookProblem + ':请从钉钉群「自定义机器人」设置里复制完整地址,填到 tool-dingtalk 行的 webhook 后重启' });
149
+ }
150
+ const configuredSecret = typeof config?.secret === 'string' ? config.secret.trim() : '';
151
+ const envSecret = (process.env[DINGTALK_SECRET_ENV] ?? '').trim();
152
+ if (configuredSecret !== '')
153
+ checks.push({ name: '加签密钥', ok: true, detail: '已配置(加签模式,来源:配置里的 secret)' });
154
+ else if (envSecret !== '')
155
+ checks.push({ name: '加签密钥', ok: true, detail: '已配置(加签模式,来源:环境变量 ' + DINGTALK_SECRET_ENV + ')' });
156
+ else
157
+ checks.push({ name: '加签密钥', ok: true, detail: '未配置(关键词/IP 白名单模式;若机器人开启加签,发送会返回 310000)' });
131
158
  try {
132
159
  const resolved = resolveDingTalkConfig(config);
133
- checks.push({ name: 'webhook', ok: true, detail: '已配置' });
134
- const secret = resolved.secret;
135
- checks.push({ name: '加签密钥', ok: true, detail: typeof secret === 'string' && secret !== '' ? '已配置(加签模式)' : '未配置(关键词/白名单模式)' });
160
+ checks.push({ name: '请求超时', ok: true, detail: resolved.timeoutMs + 'ms(1000-60000,可用 timeoutMs 调整)' });
136
161
  }
137
- catch (error) {
138
- ok = false;
139
- checks.push({ name: 'webhook', ok: false, detail: error instanceof Error ? error.message : String(error) });
162
+ catch {
163
+ checks.push({ name: '请求超时', ok: true, detail: '默认 10000ms(webhook 未就绪时不做完整解析)' });
140
164
  }
141
165
  return { ok, plugin: 'dsh-dingtalk', checks };
142
166
  },
143
167
  });
144
168
  }
145
- export { resolveDingTalkConfig, DINGTALK_SECRET_ENV, DEFAULT_TIMEOUT_MS, clampInt } from './config.js';
169
+ export { resolveDingTalkConfig, describeWebhookProblem, DINGTALK_SECRET_ENV, DEFAULT_TIMEOUT_MS, clampInt } from './config.js';
146
170
  export { DingTalkClient, DingTalkError, dingTalkErrorMessage } from './client.js';
147
171
  export { computeDingTalkSign, signedUrl, dingTalkTimestamp } from './sign.js';
@@ -437,7 +437,7 @@ function __stardustUpdatesClient(ctx, React, require, shared) {
437
437
  }
438
438
 
439
439
  /* STARDUSTLC_UPDATE_CLIENT_BODY_START */
440
- window.__ModuleLoader__.load(__stardustUpdatesWrap({id:"dsh-dingtalk",factory:require=>({apply(){}})},{"name":"dsh-dingtalk","version":"0.1.0","hasWorkbench":false,"packageVersion":"0.3.7","label":"钉钉","labelEn":"DingTalk","suiteComponent":true}));
440
+ window.__ModuleLoader__.load(__stardustUpdatesWrap({id:"dsh-dingtalk",factory:require=>({apply(){}})},{"name":"dsh-dingtalk","version":"0.1.0","hasWorkbench":false,"packageVersion":"0.3.8","label":"钉钉","labelEn":"DingTalk","suiteComponent":true}));
441
441
 
442
442
  /* STARDUSTLC_UPDATE_CLIENT_BODY_END */
443
443
  })();
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "dsh-dingtalk",
3
- "version": "0.3.7",
4
- "description": "把 DSH 的任务结果送到钉钉群。 需要自己的群机器人 webhook 欢迎提交 issues 和 PR。",
3
+ "version": "0.3.8",
4
+ "description": "DSH 钉钉通知:向自定义群机器人发送文本或 Markdown,支持签名配置与自检。欢迎提交 issues 和 PR。",
5
5
  "type": "module",
6
6
  "main": "lib/index.js",
7
7
  "types": "lib/index.d.ts",
@@ -29,8 +29,8 @@
29
29
  ],
30
30
  "scripts": {
31
31
  "build": "tsc && node scripts/build-updates.mjs",
32
- "prepublishOnly": "pnpm run build",
33
- "test": "pnpm run build && node --test \"test/*.test.mjs\""
32
+ "prepublishOnly": "npm run build",
33
+ "test": "npm run build && node --test \"test/*.test.mjs\""
34
34
  },
35
35
  "keywords": [
36
36
  "dsh-plugin",