dingtalk-pingo 0.1.0 → 0.2.0

package/README.md

@@ -77,7 +77,11 @@ chmod 600 ~/.pingo/config.yaml
 device:
   id: work-mac
   name: Work Mac
-  icon: "🏢"
+  icon: "🏢"                        # shown in Markdown/text messages
+  avatar: "https://example.com/work-mac.png"   # optional, card messages only (http(s) URL)
+
+card:
+  templateId: "<your card template id>"   # optional; enables card messages (see "Card messages")
 
 dingtalk:
   clientId: <your AppKey>
@@ -87,7 +91,7 @@ dingtalk:
 
 message:
   defaultType: info
-  preferredFormat: markdown        # markdown | text
+  preferredFormat: card            # card | markdown | text (default: card if card.templateId is set, else markdown)
   fallbackFormat: text
   timeoutMs: 10000
 
@@ -99,7 +103,8 @@ templates:                          # optional: override the built-in templates
 Credentials can also come from environment variables, which take
 precedence over the file: `DINGTALK_CLIENT_ID`, `DINGTALK_CLIENT_SECRET`,
 `DINGTALK_ROBOT_CODE`, `DINGTALK_USER_ID`, plus `PINGO_DEVICE_ID`,
-`PINGO_DEVICE_NAME`, `PINGO_DEVICE_ICON` for device identity. This is
+`PINGO_DEVICE_NAME`, `PINGO_DEVICE_ICON`, `PINGO_DEVICE_AVATAR` for device
+identity and `PINGO_CARD_TEMPLATE_ID` for the card template. This is
 useful in CI or containers where you don't want a config file at all.
 
 If you run multiple machines against the same robot (e.g. a work laptop
@@ -124,10 +129,90 @@ pingo send --type warning --action-required --message "Please review the token p
 pingo send --markdown ./report.md --type success     # body from a Markdown file
 pingo send --message "preview this" --dry-run         # preview only, no credentials needed
 pingo send --message "x" --json                       # machine-readable output
+
+pingo send --title "Checkout page" --message "After the fix" --image ./shot.png
+pingo send --message "Repro recording" --video ./repro.mp4
+pingo send --message "PR is ready" --link "Open PR=https://github.com/org/repo/pull/1"
+pingo update <cardId> --type success --title "Tests passing" --message "195/195"
 ```
 
 Run `pingo --help` for the full option list.
 
+## Card messages
+
+With a card template configured, every message is a DingTalk card whose
+header shows the sender — the machine's avatar and name, plus the agent and
+project — so messages from several machines sharing one robot are easy to
+tell apart. Below the header come the title, the Markdown body, any images
+and optional link buttons.
+
+To enable cards:
+
+1. Grant your app the **`Card.Instance.Write`** permission in the DingTalk
+   developer console.
+2. Create a message card template in the card editor at
+   <https://open-dev.dingtalk.com/fe/card>, linked to your app. There is no
+   public API for creating templates; it is done in the web editor. Lay it out
+   as "avatar + sender name" on the first row, the title below, then a
+   Markdown/rich-text block and a button group. Bind these variables (names and
+   types must match exactly):
+
+   - `avatar` — plain text (image URL)
+   - `senderName` — plain text
+   - `title` — plain text
+   - `content` — rich text (Markdown)
+   - `btns` — button group
+   - optional: `date` — plain text (shown when `--date` is used)
+   - optional: `chart` — chart variable (shown when `--chart` is used)
+
+3. Publish the template, then set `card.templateId` (and optionally
+   `device.avatar`) in `~/.pingo/config.yaml`.
+
+Card-only options:
+
+- `--date "<text>"` fills the `date` variable (Pingo does not format it).
+- `--chart <file.json>` fills the `chart` variable. The file holds a chart
+  object: `type` is `lineChart`, `histogram` or `pieChart`, `data` is a
+  non-empty array, `config` is optional. See DingTalk's
+  [chart variable](https://open.dingtalk.com/document/isvapp/chart-variable)
+  protocol. Example: `{"type":"lineChart","data":[{"x":"N0","type":"line","y":48}]}`.
+- Both are rejected with `--format markdown|text`, and both work with
+  `pingo update`.
+- Tables: put a Markdown table in `--message`/`--markdown`. It renders only if
+  the template's `content` component uses DingTalk's newer Markdown variable;
+  the older one has no table support.
+
+Templates belong to your own DingTalk app; Pingo does not ship one. If the
+card is rejected (wrong template ID, missing permission), Pingo falls back to
+a Markdown message and says why in its output. Timeouts are never retried or
+downgraded, to avoid duplicate messages.
+
+`pingo send --json` returns a `cardId` for card messages. `pingo update
+<cardId>` changes that card in place: `--type`/`--title` regenerate the title;
+`--message`/`--markdown`/`--image`/`--action-required` replace the whole body
+(pass the full text); `--agent`/`--project` update the sender line; `--link`
+replaces the buttons. Unspecified fields are left as they were. An update never
+falls back to sending a new message.
+
+## Sending images and videos
+
+- `--image <file>`: png, jpg, gif or bmp; up to 5 per message, 10 MiB each;
+  the file content must match the extension. In a card, images appear inside
+  the card; in Markdown/text messages they follow as separate image messages.
+- `--video <file.mp4>`: one mp4 per message, up to 19 MiB (DingTalk's upload
+  limit is just under 20 MiB). It is sent as a separate video message right
+  after the main message. The duration is read from the mp4 itself.
+- `--cover <image>`: video cover. Without it, Pingo grabs a frame with `ffmpeg`
+  if it is installed (optional, not a dependency); otherwise it generates a
+  plain gradient cover whose colour is derived from `device.id`.
+- `--image` / `--video` always come with `--message` or `--markdown`.
+- Files are uploaded to DingTalk's media service before anything is sent; if an
+  upload fails, nothing is sent. If a later part of a multi-part send fails,
+  the output lists what was and was not delivered, and nothing is resent.
+
+Screenshots and screen recordings can capture more than intended — check them
+for secrets or private data before sending.
+
 ## AI agent skills
 
 The package ships two [Agent Skills](https://developers.openai.com/codex/skills/create-skill)
@@ -205,13 +290,12 @@ updated `dist/pingo.js` — `npm run check:dist` verifies they match, and
 
 ## Status
 
-This is an early release: the CLI, configuration, templates, and
-single-recipient text/Markdown sending are implemented and covered by
-unit tests, plus manual verification against a live DingTalk robot. The
-`pingo` and `pingo-follow` skills and `pingo skills install` are
-implemented and covered by unit tests; how reliably each AI tool follows
-`pingo-follow` has not been verified end to end yet (see below).
-Image/screenshot sending is not implemented yet.
+Version 0.2 adds card messages, in-place card updates, images, mp4 videos and
+link buttons. Text/Markdown sending, cards, card updates, image upload and
+sending, and video sending were each verified against a live DingTalk robot;
+everything is covered by unit tests. How reliably each AI tool follows
+`pingo-follow` has not been verified end to end yet (see below). File
+attachments are not supported.
 
 ## Known limitations
 
@@ -242,6 +326,11 @@ Image/screenshot sending is not implemented yet.
   globally installed package. After changing Node version or moving the
   global `node_modules` directory, re-run `pingo skills install` to
   repair them.
-- **No image sending yet.** The `pingo` skill tells the agent to send a
-  text description instead and to say plainly that the image was not
-  sent.
+- **Cards and notifications.** Whether updating a card in place re-notifies
+  the phone, and what the chat list shows as the preview of a card message,
+  are not yet verified; `pingo-follow` therefore sends approval requests and
+  final reports as new messages.
+- **Card body limit.** The card body uses the same conservative 8000-byte local
+  limit as Markdown; DingTalk's real limit for cards has not been measured.
+- **Videos.** Only mp4 has been tested. Videos are never embedded in cards.
+- **No file attachments** yet.