dsh-dingtalk 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stardustlc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,129 @@
+# dsh-dingtalk
+
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
+DeepSeek Harness DingTalk group robot notification plugin: lets the agent **push Markdown / plain-text messages to a DingTalk group one-way**. Pure plugin implementation, zero core changes, works out of the box.
+
+Pure Node implementation, **cross-platform** (one codebase for Windows / macOS / Linux), depends only on `node:crypto` and the built-in `fetch` — no runtime dependencies, no native binaries.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `dingtalk_notify` | Send a **Markdown** message to the configured DingTalk group (`title` heading + `text` Markdown body) |
+| `dingtalk_text` | Send a **plain-text** message to the configured DingTalk group (`content`) |
+
+Example:
+
+> Send a message to the DingTalk group: title "Build complete", body "Pipeline #123 passed ✅".
+
+## Compatibility
+
+Verified against `@deepseek-ai/dsh@0.1.1-rc.2` on 2026-08-26. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+
+## Installation
+
+```sh
+dsh plugin --profile web add dsh-dingtalk
+```
+
+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.
+
+## Uninstall
+
+```bash
+dsh plugin --profile web remove dsh-dingtalk
+```
+
+Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
+
+
+## Step 1: Get the webhook and signing secret
+
+Use DingTalk's **custom robot** method — **no enterprise app or admin permission needed**:
+
+1. Open the target DingTalk group → **Group settings** → **Smart group assistant** → **Add robot** → **Custom (connect a custom service via Webhook)**
+2. The robot name is arbitrary; under **Security settings, check "Sign" (加签)**, then finish
+3. Copy two things:
+   - **Webhook URL**: like `https://oapi.dingtalk.com/robot/send?access_token=xxxx`
+   - **Signing secret (secret)**: like `SECxxxx` (only appears after checking "Sign")
+
+> 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").
+
+## Configuration
+
+In your profile's `cordis.patch.yml` (under `$DSH_HOME/profiles/<name>/`), override the `tool-dingtalk` line, then restart:
+
+```yaml
+- id: tool-dingtalk
+  config:
+    webhook: https://oapi.dingtalk.com/robot/send?access_token=你的token
+    secret: SEC你的加签密钥        # 可选，但强烈建议；也可用环境变量 DSH_DINGTALK_SECRET
+```
+
+### Full configuration
+
+| Field | Default | Description |
+|---|---|---|
+| `webhook` | required | Full webhook URL of the robot (`?access_token=...`) |
+| `secret` | empty | Signing secret; when omitted, falls back to the `DSH_DINGTALK_SECRET` env var. Empty = no signing |
+| `timeoutMs` | `10000` | Request timeout in milliseconds (1000–60000) |
+
+### Store the secret in an environment variable
+
+If you don't want to write the secret into YAML, write only `webhook` and set an environment variable:
+
+```sh
+# Windows PowerShell
+$env:DSH_DINGTALK_SECRET = "SEC你的加签密钥"
+# 或系统环境变量里加一条 DSH_DINGTALK_SECRET
+```
+
+An explicit `secret` in YAML takes precedence over the environment variable.
+
+## Security notes
+
+- **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.
+- This plugin is **one-way notification only** (agent → DingTalk group); it never reads messages from the group and has no two-way bot capability.
+- 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.
+
+## Signing algorithm (matches the official one)
+
+When a `secret` is present, the request URL appends `timestamp` (millisecond timestamp) and `sign`:
+
+```text
+stringToSign = timestamp + "
+" + secret
+sign = urlencode(base64(HmacSHA256(secret, stringToSign)))
+```
+
+Identical to this plugin's `computeDingTalkSign`, equivalent to `urllib.parse.quote_plus(base64(...))` in the official Python example.
+
+## Known limitations
+
+- **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.
+- **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.
+- **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+.
+- **Message types**: currently only Markdown (`dingtalk_notify`) and plain text (`dingtalk_text`); image / Link / FeedCard / ActionCard etc. come later.
+- **Markdown rendering**: DingTalk robot Markdown syntax differs slightly from standard Markdown (e.g., headings, links); write according to DingTalk's syntax.
+
+## Error code reference
+
+| errcode | Meaning | Suggestion |
+|---|---|---|
+| `0` | Success | — |
+| `310000` | Signing validation failed (see the keyword note above) | Check that `secret` is correct and matches the robot's "Sign" setting |
+| `120001` | `access_token` expired | Re-copy the webhook URL from the DingTalk group and overwrite `webhook` |
+| other | Server error | Check the returned `errmsg` |
+
+## Development
+
+```sh
+pnpm install
+pnpm run build   # tsc → lib/
+pnpm test        # 构建 + node --test（加签算法/配置解析/客户端封装/注册与中文报错）
+```
+
+## License
+
+MIT. This is a community plugin, not affiliated with DeepSeek or DingTalk; `@deepseek-ai/*` is an officially reserved namespace.

package/README.md

@@ -1,5 +1,14 @@
+[English](README.en.md)
+
 # dsh-dingtalk
 
+> **让 agent 在钉钉群里说话**：Markdown / 纯文本通知，加签安全，零依赖。
+
+![npm version](https://img.shields.io/npm/v/dsh-dingtalk?label=npm&color=blue) ![npm downloads](https://img.shields.io/npm/dm/dsh-dingtalk) ![license](https://img.shields.io/npm/l/dsh-dingtalk) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-dingtalk?style=social)
+
+[![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
+
+
 DeepSeek Harness 钉钉群机器人通知插件：让 agent 能**单向推送 Markdown / 纯文本消息到钉钉群**。纯插件实现，零核心改动，安装即可用。
 
 纯 Node 实现，**全平台通用**（Windows / macOS / Linux 同一份代码），只依赖 `node:crypto` 与内置 `fetch`，无运行时依赖、无原生二进制。
@@ -15,6 +24,10 @@ DeepSeek Harness 钉钉群机器人通知插件：让 agent 能**单向推送 Ma
 
 > 帮我给钉钉群发一条消息：标题「构建完成」，正文「流水线 #123 已通过 ✅」。
 
+## 兼容性
+
+在 `@deepseek-ai/dsh@0.1.1-rc.2` 上验证（2026-08-26）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+
 ## 安装
 
 ```sh
@@ -23,6 +36,15 @@ dsh plugin --profile web add dsh-dingtalk
 
 装好后重启 `dsh web`。插件自带空配置，**不会弄崩启动**；配置前调用任何 `dingtalk_*` 工具都会返回明确的中文配置提示。
 
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-dingtalk
+```
+
+卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中覆盖的插件行。
+
+
 ## 第一步：拿到 webhook 与加签密钥
 
 用钉钉【自定义机器人】方式，**不需要企业应用、不需要管理员权限**：
@@ -84,7 +106,7 @@ sign = urlencode(base64(HmacSHA256(secret, stringToSign)))
 
 与本插件 `computeDingTalkSign` 一致，等价于官方 Python 示例的 `urllib.parse.quote_plus(base64(...))`。
 
-## 已知限制（v0.1）
+## 已知限制
 
 - **仅单向通知**：不支持企业自建应用、不支持接收群消息 / 双向机器人（@机器人 回复等），这些是 v0.2+ 的方向。
 - **不支持自定义关键词校验的自动规避**：如果机器人在钉钉侧勾选了「自定义关键词」，消息必须包含关键词，否则钉钉返回错误（errcode 310000 也可能因此出现）。本插件把 310000 归因于加签，请同时检查关键词设置。
@@ -112,3 +134,9 @@ pnpm test        # 构建 + node --test（加签算法/配置解析/客户端封
 ## 协议
 
 MIT。这是一个社区插件，与 DeepSeek 官方及钉钉官方无关；`@deepseek-ai/*` 为官方保留命名空间。
+
+## 相关插件
+
+- [dsh-calendar](https://github.com/STARDUSTLC666/dsh-calendar) — CalDAV 日历五件套
+- [dsh-dingtalk](https://github.com/STARDUSTLC666/dsh-dingtalk) — 钉钉群通知（零依赖）
+- [dsh-email](https://github.com/STARDUSTLC666/dsh-email) — 邮件六件套 + Web 设置页

package/lib/index.js

@@ -100,6 +100,39 @@ export function apply(ctx, config = {}) {
             return { ok: true, msgtype: 'text', title: '', errcode: result.errcode, errmsg: result.errmsg };
         },
     });
+    ctx.tools.register({
+        name: 'dingtalk_health',
+        description: 'dsh-dingtalk 自检：检查钉钉机器人 webhook 与加签密钥（secret）配置是否就绪（不发送任何消息）。遇到问题时先运行本工具定位。',
+        parameters: compileParameters({}),
+        output: {
+            schema: { type: 'object', additionalProperties: true },
+            render: (_args, value) => {
+                const rec = (value ?? {});
+                const rawChecks = Array.isArray(rec.checks) ? rec.checks : [];
+                const lines = ['dsh-dingtalk 自检' + (rec.ok === true ? '：正常。' : '：发现问题。')];
+                for (const item of rawChecks) {
+                    const c = (item ?? {});
+                    lines.push('- ' + String(c.name) + '：' + (c.ok === true ? '✅ ' + String(c.detail ?? '') : '❌ ' + String(c.detail ?? '')));
+                }
+                return oneText(lines.join('\n'));
+            },
+        },
+        async execute() {
+            const checks = [];
+            let ok = true;
+            try {
+                const resolved = resolveDingTalkConfig(config);
+                checks.push({ name: 'webhook', ok: true, detail: '已配置' });
+                const secret = resolved.secret;
+                checks.push({ name: '加签密钥', ok: true, detail: typeof secret === 'string' && secret !== '' ? '已配置（加签模式）' : '未配置（关键词/白名单模式）' });
+            }
+            catch (error) {
+                ok = false;
+                checks.push({ name: 'webhook', ok: false, detail: error instanceof Error ? error.message : String(error) });
+            }
+            return { ok, plugin: 'dsh-dingtalk', checks };
+        },
+    });
 }
 export { resolveDingTalkConfig, DINGTALK_SECRET_ENV, DEFAULT_TIMEOUT_MS, clampInt } from './config.js';
 export { DingTalkClient, DingTalkError, dingTalkErrorMessage } from './client.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-dingtalk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "钉钉群机器人单向通知工具（DeepSeek Harness 插件）：agent 推送 Markdown / 纯文本消息到钉钉群，支持加签安全模式。",
   "type": "module",
   "main": "lib/index.js",
@@ -17,11 +17,11 @@
   "files": [
     "lib",
     "cordis.patch.yml",
-    "README.md"
+    "README.md",
+    "README.en.md"
   ],
   "scripts": {
     "build": "tsc",
-    "prepare": "tsc",
     "prepublishOnly": "pnpm run build",
     "test": "pnpm run build && node --test \"test/*.test.mjs\""
   },
@@ -33,11 +33,11 @@
     "dingtalk-robot",
     "webhook"
   ],
-  "author": "dsh-community",
+  "author": "stardustlc",
   "license": "MIT",
   "packageManager": "pnpm@11.7.0",
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "dsh": {
     "bundle": {
@@ -49,7 +49,7 @@
     "typescript": "^5.7.3"
   },
   "repository": {
-    "url": "https://github.com/STARDUSTLC666/dsh-dingtalk",
+    "url": "git+https://github.com/STARDUSTLC666/dsh-dingtalk.git",
     "type": "git"
   },
   "bugs": {