dsh-dingtalk 0.3.14 → 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/CHANGELOG.md CHANGED
@@ -1,5 +1,10 @@
1
1
  # 更新记录
2
2
 
3
+ ## 0.4.0 (2026-11-18)
4
+
5
+ - 新增零外部依赖的宿主原生 `Config` 设置表单声明(`webhook` 与 `secret` 自动脱敏且修改即热生效无需重启),优化首次未配置提示,并补齐面向日常场景的三步使用流程与可复制话术。
6
+ - Export a zero-dependency native DSH `Config` schema with secret masking and live `volatile` reload for `webhook`, `secret`, and `timeoutMs`, alongside clearer first-run setup hints and human-first workflow docs.
7
+
3
8
  ## 0.3.14 (2026-11-18)
4
9
 
5
10
  - 更新区底部新增克制、无打扰的 GitHub 点赞与问题反馈快捷链接,并完善中英文检索关键词。
package/README.en.md CHANGED
@@ -2,13 +2,13 @@
2
2
 
3
3
  # DingTalk
4
4
 
5
- **Send DSH task results to your DingTalk group.**
5
+ **Send DSH task results straight to your DingTalk group.**
6
6
 
7
- DingTalk custom webhook notification plugin for DeepSeek Harness (`>=0.2.2-rc.3`): sends plain-text and Markdown messages with HMAC-SHA256 signing, secret redaction, health checks, and Cordis hot-reload cleanup.
7
+ DingTalk custom webhook notification plugin for DeepSeek Harness (`>=0.2.2-rc.3`): sends plain-text and Markdown messages with native live Settings forms, secret masking, HMAC-SHA256 signing, and offline health checks.
8
8
 
9
9
  [![npm](https://img.shields.io/npm/v/dsh-dingtalk)](https://www.npmjs.com/package/dsh-dingtalk) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-dingtalk-downloads.svg)](https://www.npmjs.com/package/dsh-dingtalk) [![total downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-dingtalk-total-downloads.svg)](https://www.npmjs.com/package/dsh-dingtalk)
10
10
 
11
- **[Install](#install) · [Workflow](#start-using-it) · [Full guide](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/REFERENCE.en.md)**
11
+ **[Install](#install) · [Get Started in 3 Steps](#get-started-in-3-steps) · [Full Guide](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/USAGE.en.md)**
12
12
 
13
13
  <picture>
14
14
  <source media="(prefers-color-scheme: dark) and (max-width: 640px)" srcset="https://raw.githubusercontent.com/STARDUSTLC666/dsh-dingtalk/main/docs/assets/intro/workflow-en-mobile-dark.svg">
@@ -17,52 +17,55 @@ DingTalk custom webhook notification plugin for DeepSeek Harness (`>=0.2.2-rc.3`
17
17
  <img src="https://raw.githubusercontent.com/STARDUSTLC666/dsh-dingtalk/main/docs/assets/intro/workflow-en-light.svg" alt="Send DSH task results to your DingTalk group. · workflow illustration" width="100%">
18
18
  </picture>
19
19
 
20
- ## Features
21
-
22
- - Send plain-text or Markdown notifications.
23
- - Use signing with your own robot configuration.
24
- - Check configuration and test before sending real notices.
25
-
26
20
  ## Install
27
21
 
28
- Open **Plugins** in the DSH desktop app and install `dsh-dingtalk`. If the CLI is available:
22
+ Open **Plugins** in the DSH desktop app and install `dsh-dingtalk`, or use the CLI:
29
23
 
30
24
  ```bash
31
25
  dsh plugin --profile desktop add dsh-dingtalk
32
26
  ```
33
27
 
34
- For the web profile, replace `desktop` with `web`. Restart that DSH profile after installation. The package’s DSH requirement is `>=0.2.2-rc.3`.
35
-
36
- ## Start using it
28
+ For the web profile, replace `desktop` with `web`. Restart DSH once after installing. Requires DSH `>=0.2.2-rc.3`.
37
29
 
38
- 1. Create a custom robot in your DingTalk group and obtain its webhook and signing secret.
39
- 2. Enter the configuration in DSH plugin settings and run the configuration check.
40
- 3. Verify a simple notification in your own test group before preparing the real message.
41
- 4. Provide the content and target group, confirm sending, then check the text or Markdown in DingTalk.
30
+ <a id="start-using-it"></a>
31
+ ## Get Started in 3 Steps
42
32
 
43
- Example request:
33
+ 1. **Create a group webhook robot**: In your DingTalk group, open **Group Settings → Smart Group Assistant → Add Robot → Custom**, enable **Sign (加签)**, and copy the **Webhook URL** and **`SEC...` signing secret**.
34
+ 2. **Fill in DSH Settings (applies live)**: Open **DSH Settings → Plugins → DingTalk (`dsh-dingtalk`)**, paste `webhook` and `secret` (credentials are masked and take effect immediately without restarting; `DSH_DINGTALK_SECRET` env var is also supported).
35
+ 3. **Run a silent check, then notify**: Ask the assistant to check your DingTalk configuration locally before posting build summaries or task alerts to your group.
44
36
 
45
- > Check my DingTalk robot configuration and prepare a task-complete notice for review before sending.
37
+ ## Copy-Ready Prompts for Everyday Work
46
38
 
47
- ## Before you start
39
+ - **Silent first-run check (sends zero messages)**
40
+ > Check whether my DingTalk robot configuration is ready without sending any message to the group.
41
+ - **Formatted Markdown summary after a task (review before sending)**
42
+ > Turn the build and test results into a concise Markdown DingTalk notice. Show me the title and body first, and send only after I confirm.
43
+ - **Quick plain-text heads-up**
44
+ > Send a plain-text DingTalk notice: Staging will be under maintenance at 22:00 tonight for 15 minutes; please pause merges.
48
45
 
49
- Requires your own group robot webhook. Verify delivery in a test group first.
46
+ ## Quick Troubleshooting Checklist
50
47
 
51
- Configuration, detailed tools and troubleshooting: [full reference](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/REFERENCE.en.md).
48
+ | Symptom | Likely Cause | Fix |
49
+ | :--- | :--- | :--- |
50
+ | `dsh-dingtalk 未配置` or missing `access_token` | `webhook` is blank or truncated | Paste the full Webhook URL in **DSH Settings → Plugins → DingTalk** (applies immediately) |
51
+ | DingTalk error `310000` | Signing `secret` mismatch, or "Custom keywords" is also enabled on the robot | Verify the `SEC...` secret; if keywords are enabled on DingTalk, include the keyword in the message |
52
+ | DingTalk error `120001` | Robot `access_token` expired or was reset | Copy the refreshed Webhook URL from DingTalk group settings and save |
53
+ | Request timeout | Slow network; delivery is uncertain | **Check the DingTalk group first** before resending to avoid duplicate alerts |
52
54
 
53
55
  ## Plugin updates
54
56
 
55
- Check updates at the bottom of the workbench or native plugin details. Automatic checks are on by default; **automatic installation is off**. You choose whether to install and when to restart. Suite-managed components update with their bundle. [Update behavior](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/REFERENCE.en.md).
57
+ Check updates at the bottom of native plugin details. Automatic checks are on by default; **automatic installation is off**. Suite-managed components update with their bundle.
56
58
 
57
59
  ## Documentation
58
60
 
59
- - [Full usage, configuration and limits](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/REFERENCE.en.md)
61
+ - [Usage guide and configuration reference](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/USAGE.en.md)
62
+ - [Full reference](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/REFERENCE.en.md)
60
63
  - [Release notes](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/CHANGELOG.md)
61
64
  - [Validation scope and history](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/VALIDATION.md)
62
65
 
63
66
  ## Feedback and contributions
64
67
 
65
- If the plugin helps, a Star makes it easier for others to discover. Report problems or suggest improvements in [Issues](https://github.com/STARDUSTLC666/dsh-dingtalk/issues); code and documentation [PRs](https://github.com/STARDUSTLC666/dsh-dingtalk/pulls) are welcome. Include versions and reproduction steps, and remove credentials from reports.
68
+ If the plugin helps, a Star makes it easier for others to discover. Report issues in [Issues](https://github.com/STARDUSTLC666/dsh-dingtalk/issues) or open [PRs](https://github.com/STARDUSTLC666/dsh-dingtalk/pulls) (please strip credentials).
66
69
 
67
70
  ## License
68
71
 
package/README.md CHANGED
@@ -4,11 +4,11 @@
4
4
 
5
5
  **把 DSH 的任务结果送到钉钉群。**
6
6
 
7
- DeepSeek Harness(`>=0.2.2-rc.3`)钉钉群通知插件:面向自定义群机器人发送纯文本与 Markdown 消息,内置 HMAC-SHA256 加签校验、凭证脱敏、配置自检与 Cordis 热重载工具注销。
7
+ DeepSeek Harness(`>=0.2.2-rc.3`)钉钉群通知插件:面向自定义群机器人发送纯文本与 Markdown 消息,支持原生设置表单与热生效、HMAC-SHA256 加签校验、凭证脱敏与本地配置自检。
8
8
 
9
9
  [![npm](https://img.shields.io/npm/v/dsh-dingtalk)](https://www.npmjs.com/package/dsh-dingtalk) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-dingtalk-downloads.svg)](https://www.npmjs.com/package/dsh-dingtalk) [![total downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-dingtalk-total-downloads.svg)](https://www.npmjs.com/package/dsh-dingtalk)
10
10
 
11
- **[安装使用](#安装) · [使用流程](#开始使用) · [完整说明](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/REFERENCE.zh.md)**
11
+ **[安装使用](#安装) · [最快 3 步用起来](#最快-3-步用起来) · [完整说明](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/USAGE.md)**
12
12
 
13
13
  <picture>
14
14
  <source media="(prefers-color-scheme: dark) and (max-width: 640px)" srcset="https://raw.githubusercontent.com/STARDUSTLC666/dsh-dingtalk/main/docs/assets/intro/workflow-zh-mobile-dark.svg">
@@ -17,52 +17,55 @@ DeepSeek Harness(`>=0.2.2-rc.3`)钉钉群通知插件:面向自定义群
17
17
  <img src="https://raw.githubusercontent.com/STARDUSTLC666/dsh-dingtalk/main/docs/assets/intro/workflow-zh-light.svg" alt="把 DSH 的任务结果送到钉钉群。 · 流程示意" width="100%">
18
18
  </picture>
19
19
 
20
- ## 功能
21
-
22
- - 发送纯文本或 Markdown 通知。
23
- - 按自己的机器人配置使用加签。
24
- - 先自检和测试,再用于正式通知。
25
-
26
20
  ## 安装
27
21
 
28
- 在 DSH 桌面版「插件」面板安装 `dsh-dingtalk`。已配置命令行时也可使用:
22
+ 在 DSH 桌面版「插件」面板搜索安装 `dsh-dingtalk`,或使用命令行:
29
23
 
30
24
  ```bash
31
25
  dsh plugin --profile desktop add dsh-dingtalk
32
26
  ```
33
27
 
34
- 网页版把 `desktop` 改为 `web`;安装后重启对应的 DSH。宿主要求以包声明 `>=0.2.2-rc.3` 为准。
35
-
36
- ## 开始使用
28
+ 网页版将 `desktop` 改为 `web`;安装后重启一次 DSH。宿主要求 `>=0.2.2-rc.3`。
37
29
 
38
- 1. 在自己的钉钉群创建自定义机器人,取得 webhook 和加签密钥。
39
- 2. 在 DSH 插件设置中填写配置,先执行配置自检。
40
- 3. 在自己的测试群确认一条简单通知能送达,再准备正式消息。
41
- 4. 给助手消息内容和目标群,确认后发送,并在钉钉检查收到的文本或 Markdown。
30
+ <a id="开始使用"></a>
31
+ ## 最快 3 步用起来
42
32
 
43
- 可以这样说:
33
+ 1. **建群机器人拿地址**:在目标钉钉群打开「群设置 → 智能群助手 → 添加机器人 → 自定义」,勾选「加签」,复制 **Webhook 地址**与 **SEC 加签密钥**。
34
+ 2. **填进原生设置(保存即生效)**:打开 DSH「**设置 → 插件 → 钉钉(dsh-dingtalk)**」,填入 `webhook` 与 `secret`(凭据自动脱敏,保存后无需重启;也支持环境变量 `DSH_DINGTALK_SECRET`)。
35
+ 3. **先自检再发正式群**:在对话里让助手先做一次无打扰本地自检,确认无误后再把构建报告、巡检结果或日报发进群。
44
36
 
45
- > 先检查钉钉机器人配置,准备一条任务完成通知,发送前让我核对正文。
37
+ ## 平时怎么对助手说(可直接复制的自然语言示例)
46
38
 
47
- ## 开始前要知道
39
+ - **首次自检(不发群消息、不刷屏)**
40
+ > 帮我检查一下钉钉机器人配置有没有填好,不要往群里发消息。
41
+ - **任务跑完后发排版卡片(发送前人工过目)**
42
+ > 把刚才构建和测试的结果整理成一条简明 Markdown 钉钉通知,先给我看一眼标题和正文,我确认后再发出。
43
+ - **快速发一句纯文本提醒**
44
+ > 给钉钉群发一条纯文本提醒:今晚 22:00 预发布环境维护 15 分钟,请暂停合并。
48
45
 
49
- 需要自己的群机器人 webhook;请先在测试群确认消息能送达。
46
+ ## 常见卡点自检
50
47
 
51
- 配置、完整工具与排错见[详细使用说明](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/REFERENCE.zh.md)。
48
+ | 遇到的现象 | 10 秒定位原因 | 怎么修 |
49
+ | :--- | :--- | :--- |
50
+ | 提示 `dsh-dingtalk 未配置` 或缺 `access_token` | 还没填 `webhook`,或复制漏了 `?access_token=...` | 打开 DSH「设置 → 插件 → 钉钉」粘贴完整 Webhook,保存立即生效 |
51
+ | 钉钉返回 `310000` | `secret` 加签密钥填错,或机器人额外勾选了「自定义关键词」 | 核对 `SEC...` 密钥;若开了关键词,正文或标题需包含该关键词 |
52
+ | 钉钉返回 `120001` | 群机器人的 `access_token` 已重置或失效 | 在钉钉群重新复制最新 Webhook 替换保存 |
53
+ | 提示请求超时 | 网络抖动,尚不确定钉钉是否已收到 | **先看一眼群消息是否已到**,确认没收到再让助手重发,避免重复刷屏 |
52
54
 
53
55
  ## 插件更新
54
56
 
55
- 在工作台或原生插件详情页底部检查更新。默认自动检查,**默认不自动安装**;是否安装、何时重启由你决定。Suite 管理的组件随整包更新。[查看更新规则](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/REFERENCE.zh.md)。
57
+ 在原生插件详情页底部检查更新。默认自动检查,**默认不自动安装**;是否安装、何时重启由你决定。Suite 管理的组件随整包更新。
56
58
 
57
59
  ## 文档
58
60
 
59
- - [详细使用、配置与边界](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/REFERENCE.zh.md)
61
+ - [使用说明与参数参考](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/USAGE.md)
62
+ - [详细参考说明](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/REFERENCE.zh.md)
60
63
  - [更新记录](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/CHANGELOG.md)
61
64
  - [验证范围与历史](https://github.com/STARDUSTLC666/dsh-dingtalk/blob/main/docs/VALIDATION.md)
62
65
 
63
66
  ## 反馈与贡献
64
67
 
65
- 如果插件帮到了你,欢迎 Star,让更多人发现它。问题和建议请提交 [Issues](https://github.com/STARDUSTLC666/dsh-dingtalk/issues),也欢迎代码与文档 [PR](https://github.com/STARDUSTLC666/dsh-dingtalk/pulls)。反馈时附上版本与复现步骤,并移除凭据。
68
+ 如果插件帮到了你,欢迎 Star。问题和建议请提交 [Issues](https://github.com/STARDUSTLC666/dsh-dingtalk/issues),也欢迎 [PR](https://github.com/STARDUSTLC666/dsh-dingtalk/pulls)(反馈时请移除凭据)。
66
69
 
67
70
  ## License
68
71
 
package/docs/USAGE.en.md CHANGED
@@ -1,137 +1,116 @@
1
- # dsh-dingtalk usage guide
1
+ # dsh-dingtalk Usage Guide
2
2
 
3
3
  [Overview](../README.en.md) · [Changelog](../CHANGELOG.md) · [Validation](VALIDATION.md)
4
4
 
5
- ## Cancellation and delivery
5
+ ## Get Started in 3 Steps
6
6
 
7
- Cancellation aborts the HTTP wait, including response-body reads. A timeout does not prove the message was not received: check the group before retrying. The plugin never retries automatically and redacts robot credentials/signatures from errors.
7
+ ### Step 1: Create a Custom Robot in Your DingTalk Group
8
8
 
9
- ## Tools
9
+ Use DingTalk's **Custom Webhook Robot** — **no enterprise app or admin approval needed**:
10
10
 
11
- | Tool | Purpose |
12
- |---|---|
13
- | `dingtalk_notify` | Send a **Markdown** message to the configured DingTalk group (`title` heading + `text` Markdown body) |
14
- | `dingtalk_text` | Send a **plain-text** message to the configured DingTalk group (`content`) |
11
+ 1. Open your DingTalk group → **Group Settings** → **Smart Group Assistant** → **Add Robot** → **Custom (Webhook)**.
12
+ 2. Name the robot and check **Sign (加签)** under Security Settings (checking only "Sign" avoids unexpected keyword rejections).
13
+ 3. Copy both values:
14
+ - **Webhook URL**: `https://oapi.dingtalk.com/robot/send?access_token=xxxx`
15
+ - **Signing secret (`secret`)**: `SECxxxx`
15
16
 
16
- Example:
17
+ ### Step 2: Configure in DSH (Choose Either Option)
17
18
 
18
- > Send a message to the DingTalk group: title "Build complete", body "Pipeline #123 passed ✅".
19
+ **Option A (Recommended): Native DSH Settings Form (Live Apply, No Restart)**
19
20
 
20
- ## Installation
21
+ Open **DSH → Settings → Plugins → DingTalk (`dsh-dingtalk`)**:
22
+ - Paste the full robot URL into `webhook`.
23
+ - Paste your `SEC...` signing key into `secret` (both fields use native secret masking so credentials are never echoed in plaintext).
21
24
 
22
- ```sh
23
- dsh plugin --profile web add dsh-dingtalk
24
- ```
25
-
26
- After installing, restart `dsh web`. The plugin ships with an empty config and **won't crash startup**; calling any `dingtalk_*` tool before configuration returns a clear Chinese configuration hint.
25
+ **Option B: Environment Variable or `cordis.patch.yml` (CLI / Headless Setups)**
27
26
 
28
- ## Uninstall
29
-
30
- ```bash
31
- dsh plugin --profile web remove dsh-dingtalk
27
+ ```powershell
28
+ # Windows PowerShell (recommended for keeping secrets out of files)
29
+ $env:DSH_DINGTALK_SECRET = "SEC_YOUR_SIGNING_SECRET"
32
30
  ```
33
31
 
34
- Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
35
-
36
- ## Step 1: Get the webhook and signing secret
37
-
38
- Use DingTalk's **custom robot** method — **no enterprise app or admin permission needed**:
39
-
40
- 1. Open the target DingTalk group → **Group settings** → **Smart group assistant** → **Add robot** → **Custom (connect a custom service via Webhook)**
41
- 2. The robot name is arbitrary; under **Security settings, check "Sign" (加签)**, then finish
42
- 3. Copy two things:
43
- - **Webhook URL**: like `https://oapi.dingtalk.com/robot/send?access_token=xxxx`
44
- - **Signing secret (secret)**: like `SECxxxx` (only appears after checking "Sign")
45
-
46
- > For security settings it's recommended to check only "Sign". If you also check "Custom keywords", the robot validates whether the message contains the keyword — that's DingTalk server-side behavior, not handled by this plugin (see "Known limitations").
47
-
48
- ## Configuration
49
-
50
- In your profile's `cordis.patch.yml` (under `$DSH_HOME/profiles/<name>/`), override the `tool-dingtalk` line, then restart:
32
+ Or override `tool-dingtalk` in `$DSH_HOME/profiles/<name>/cordis.patch.yml`:
51
33
 
52
34
  ```yaml
53
35
  - id: tool-dingtalk
54
36
  config:
55
- webhook: https://oapi.dingtalk.com/robot/send?access_token=你的token
56
- secret: SEC你的加签密钥 # 可选,但强烈建议;也可用环境变量 DSH_DINGTALK_SECRET
37
+ webhook: https://oapi.dingtalk.com/robot/send?access_token=YOUR_TOKEN
38
+ secret: SEC_YOUR_SIGNING_SECRET # optional; falls back to DSH_DINGTALK_SECRET
39
+ timeoutMs: 10000 # optional; timeout in ms (1000–60000)
57
40
  ```
58
41
 
59
- ### Full configuration
42
+ ### Step 3: Run a Silent Self-Check Before Sending
60
43
 
61
- | Field | Default | Description |
62
- |---|---|---|
63
- | `webhook` | required | Full webhook URL of the robot (`?access_token=...`) |
64
- | `secret` | empty | Signing secret; when omitted, falls back to the `DSH_DINGTALK_SECRET` env var. Empty = no signing |
65
- | `timeoutMs` | `10000` | Request timeout in milliseconds (1000–60000) |
44
+ The plugin ships with an empty config and never crashes startup. Ask the assistant to run a quick offline check first (zero network traffic, zero group noise), then start sending real notifications.
66
45
 
67
- ### Store the secret in an environment variable
46
+ ---
68
47
 
69
- If you don't want to write the secret into YAML, write only `webhook` and set an environment variable:
48
+ ## Copy-Ready Prompts for Everyday Work
70
49
 
71
- ```sh
72
- # Windows PowerShell
73
- $env:DSH_DINGTALK_SECRET = "SEC你的加签密钥"
74
- # 或系统环境变量里加一条 DSH_DINGTALK_SECRET
75
- ```
50
+ - **Silent first-run health check**
51
+ > Run a DingTalk health check and confirm my webhook and signing secret are ready without sending a message.
52
+ - **Send a structured Markdown report after a task**
53
+ > After running the test suite, send a Markdown summary to our DingTalk group titled "Regression Report" with pass counts, failures, and next steps.
54
+ - **Draft first, confirm before posting to an important group**
55
+ > Draft a release announcement for our DingTalk group. Show me the title and Markdown body here first, and wait for my confirmation before sending.
56
+ - **Quick plain-text alert**
57
+ > Send a plain-text message to DingTalk: Daily health check finished; all services are green.
76
58
 
77
- An explicit `secret` in YAML takes precedence over the environment variable.
59
+ ---
78
60
 
79
- ## Security notes
61
+ ## Quick Troubleshooting Checklist
80
62
 
81
- - **The webhook is the key to group notifications**: anyone who knows it can post to the group. Don't commit `cordis.patch.yml` to any Git repo; for the `secret`, prefer the `DSH_DINGTALK_SECRET` env var.
82
- - This plugin is **one-way notification only** (agent → DingTalk group); it never reads messages from the group and has no two-way bot capability.
83
- - This plugin performs no outbound telemetry; the `secret` is used in memory only to compute an HMAC signature, which is appended to the URL and sent to DingTalk's official endpoint.
63
+ Ask the assistant to run `dingtalk_health` first (validates URL structure and secret source locally without touching the network):
84
64
 
85
- ## Signing algorithm (matches the official one)
65
+ | Symptom | Usual Cause | Quick Fix |
66
+ | :--- | :--- | :--- |
67
+ | `dsh-dingtalk 未配置:webhook …` | `webhook` is still empty | Paste the full Webhook URL in **DSH Settings → Plugins → DingTalk** and save (applies live) |
68
+ | Health check reports missing `access_token` or wrong host | Incomplete URL pasted | Re-copy the full `https://oapi.dingtalk.com/robot/send?access_token=...` URL from DingTalk |
69
+ | DingTalk returns `310000` | Signing `secret` mismatch, or "Custom keywords" is also checked | Verify `SEC...` secret; if keywords are enabled on DingTalk, include the keyword in the message |
70
+ | DingTalk returns `120001` | `access_token` expired or reset | Copy the updated Webhook URL from DingTalk robot settings |
71
+ | Request times out | Slow network or proxy; remote receipt is uncertain | **Check the DingTalk group history first** before resending; raise `timeoutMs` if needed |
72
+ | Formatting looks off | DingTalk Markdown subset or message size limit | Stick to standard headings, lists, bold, and links; split very long messages |
86
73
 
87
- When a `secret` is present, the request URL appends `timestamp` (millisecond timestamp) and `sign`:
74
+ ---
88
75
 
89
- ```text
90
- stringToSign = timestamp + "
91
- " + secret
92
- sign = urlencode(base64(HmacSHA256(secret, stringToSign)))
93
- ```
76
+ ## Configuration & Tool Reference
94
77
 
95
- Identical to this plugin's `computeDingTalkSign`, equivalent to `urllib.parse.quote_plus(base64(...))` in the official Python example.
78
+ ### Configuration Fields
96
79
 
97
- ## Known limitations
80
+ | Field | Default | Description |
81
+ | :--- | :--- | :--- |
82
+ | `webhook` | required | Full DingTalk custom robot Webhook URL (`?access_token=...`), secret-masked & live-updated |
83
+ | `secret` | empty | HMAC-SHA256 signing secret (`SEC...`); falls back to `DSH_DINGTALK_SECRET` env var |
84
+ | `timeoutMs` | `10000` | Request timeout in milliseconds (`1000`–`60000`) |
98
85
 
99
- - **One-way notification only**: no support for enterprise self-built apps, no receiving group messages / two-way bots (@robot replies, etc.); these are v0.2+ directions.
100
- - **No automatic workaround for custom keyword validation**: if the robot checks "Custom keywords" on DingTalk's side, messages must contain the keyword or DingTalk returns an error (errcode 310000 can also appear for this reason). This plugin attributes 310000 to signing; please also check the keyword setting.
101
- - **No settings page**: v0.1 is a "node half-body"; configuration only via `cordis.patch.yml` (+ env var). A Web settings page is planned for v0.2+.
102
- - **Message types**: currently only Markdown (`dingtalk_notify`) and plain text (`dingtalk_text`); image / Link / FeedCard / ActionCard etc. come later.
103
- - **Markdown rendering**: DingTalk robot Markdown syntax differs slightly from standard Markdown (e.g., headings, links); write according to DingTalk's syntax.
86
+ ### Registered Tools
104
87
 
105
- ## Error code reference
88
+ | Tool | Purpose | Notes |
89
+ | :--- | :--- | :--- |
90
+ | `dingtalk_notify` | Send a **Markdown** card message | Args: `title` (card header), `text` (Markdown body) |
91
+ | `dingtalk_text` | Send a **plain-text** message | Args: `content` (text body) |
92
+ | `dingtalk_health` | Offline configuration check | Verifies `webhook` shape, signing mode, and timeout without network calls |
106
93
 
107
- | errcode | Meaning | Suggestion |
108
- |---|---|---|
109
- | `0` | Success | — |
110
- | `310000` | Signing validation failed (see the keyword note above) | Check that `secret` is correct and matches the robot's "Sign" setting |
111
- | `120001` | `access_token` expired | Re-copy the webhook URL from the DingTalk group and overwrite `webhook` |
112
- | other | Server error | Check the returned `errmsg` |
94
+ ### Safety, Cancellation & Delivery Guarantees
113
95
 
114
- ## Development
96
+ - **One-way & redacted**: Posts outbound notifications only (never reads group messages) and redacts `webhook`, `access_token`, `secret`, and `sign` from all error messages.
97
+ - **Cancellation without auto-retry**: Aborting a turn immediately cancels the in-flight HTTP request and body read. Timeouts never auto-retry so groups are never spammed.
98
+ - **Official signing**: Computes `urlencode(base64(HmacSHA256(secret, timestamp + "\n" + secret)))` matching DingTalk's official specification.
115
99
 
116
- ```sh
117
- pnpm install
118
- pnpm run build # tsc → lib/
119
- pnpm test # 构建 + node --test(加签算法/配置解析/客户端封装/注册与中文报错)
120
- ```
100
+ ## Install, Uninstall & Development
121
101
 
122
- ## Troubleshooting
102
+ ```bash
103
+ # Install (use desktop instead of web for DSH Desktop)
104
+ dsh plugin --profile web add dsh-dingtalk
123
105
 
124
- Run `dingtalk_health` first: it validates the webhook shape and signing config locally (no messages, no network calls).
106
+ # Uninstall
107
+ dsh plugin --profile web remove dsh-dingtalk
125
108
 
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 |
109
+ # Build & run offline tests
110
+ pnpm install
111
+ pnpm test
112
+ ```
134
113
 
135
114
  ## License
136
115
 
137
- MIT. This is a community plugin, not affiliated with DeepSeek or DingTalk; `@deepseek-ai/*` is an officially reserved namespace.
116
+ MIT. Community plugin, not affiliated with DeepSeek or DingTalk; `@deepseek-ai/*` is an officially reserved namespace.