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 +5 -0
- package/docs/USAGE.en.md +13 -0
- package/docs/USAGE.md +13 -0
- package/lib/config.d.ts +7 -0
- package/lib/config.js +27 -0
- package/lib/index.d.ts +1 -1
- package/lib/index.js +37 -13
- package/lib/update-client.js +1 -1
- package/package.json +4 -4
package/CHANGELOG.md
CHANGED
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('
|
|
50
|
+
return oneText('已发送 Markdown 消息到钉钉群(标题「' + value.title + '」)。如需核对,请查看群消息。');
|
|
47
51
|
}
|
|
48
|
-
return oneText('
|
|
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: '
|
|
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
|
|
138
|
-
ok
|
|
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';
|
package/lib/update-client.js
CHANGED
|
@@ -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.
|
|
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.
|
|
4
|
-
"description": "
|
|
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": "
|
|
33
|
-
"test": "
|
|
32
|
+
"prepublishOnly": "npm run build",
|
|
33
|
+
"test": "npm run build && node --test \"test/*.test.mjs\""
|
|
34
34
|
},
|
|
35
35
|
"keywords": [
|
|
36
36
|
"dsh-plugin",
|