@xmanrui/dsh-im 1.0.2 → 1.1.0

package/plugin-src/client/channels/weixin/styles.js

@@ -77,10 +77,6 @@ const CSS = String.raw`
 .dxw-accountIdentity h3 { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 15px; }
 .dxw-accountIdentity p { color: var(--dsw-alias-label-secondary, #646a73); font: 12px ui-monospace, SFMono-Regular, monospace; margin-top: 4px; }
 .dxw-health { display: inline-flex; align-items: center; gap: 7px; color: var(--dsw-alias-label-secondary, #646a73); font-size: 12px; white-space: nowrap; }
-.dxw-metrics { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 12px; margin: 20px 0; }
-.dxw-metric { padding: 12px 14px; border-radius: 9px; background: var(--dsw-alias-interactive-bg-hover, #f7f8fa); }
-.dxw-metric dt { color: var(--dsw-alias-label-tertiary, #8f959e); font-size: 11px; }
-.dxw-metric dd { overflow: hidden; margin: 5px 0 0; font-size: 13px; text-overflow: ellipsis; white-space: nowrap; }
 .dxw-accountFooter { display: flex; align-items: center; justify-content: space-between; gap: 15px; padding-top: 16px; border-top: 1px solid var(--dsw-alias-border-l1, #eef0f3); }
 .dxw-accountFooter .dxw-actions { flex: none; flex-wrap: nowrap; gap: 8px; margin-top: 0; }
 .dxw-accountFooter .dxw-button { flex: none; white-space: nowrap; }
@@ -99,7 +95,6 @@ const CSS = String.raw`
   .dxw-logo { display: none; }
   .dxw-qrLayout { grid-template-columns: minmax(0, 1fr); justify-items: center; }
   .dxw-qrCopy { width: 100%; }
-  .dxw-metrics { grid-template-columns: minmax(0, 1fr); }
   .dxw-cardBody { padding: 20px; }
 }
 @media (prefers-reduced-motion: reduce) {

package/plugin-src/client/channels/whatsapp/index.js

@@ -10,6 +10,7 @@ import {
   EMPTY_AGENT_PRESET_CATALOG,
 } from '../../agent-preset.js';
 import { useWorkspaceSnapshotFence } from '../../workspace-snapshot-fence.js';
+import { BotStatusMeta, ChannelListHeading } from '../../channel-card-meta.js';
 import { installDingtalkStyles } from '../dingtalk/styles.js';
 import {
   WHATSAPP_ENDPOINTS,
@@ -197,15 +198,14 @@ export function WhatsappAccountCard({
           }, h(WhatsappLogoGlyph, { size: 29 })),
           h('div', { className: 'dim-botName' },
             h('h3', null, account.bot.name), h('p', null, account.bot.idMasked))),
-        h('div', { className: 'ddt-health dim-botHealth' },
-          h('span', { className: 'ddt-dot dim-healthDot', 'data-tone': tone }),
-          h('span', null, stateLabel))),
-      h('dl', { className: 'ddt-metrics dim-botMetrics' },
-        h('div', { className: 'ddt-metric dim-botMetric' },
-          h('dt', null, '消息通道'),
-          h('dd', null, account.connected ? 'WhatsApp Web' : '离线')),
-        h('div', { className: 'ddt-metric dim-botMetric' },
-          h('dt', null, '最近检查'), h('dd', null, checkedTime(account.health.lastCheckedAt)))),
+        h(BotStatusMeta, {
+          className: 'ddt-health',
+          dotClassName: 'ddt-dot',
+          tone,
+          stateLabel,
+          lastCheckedAt: account.health.lastCheckedAt,
+          formatCheckedTime: checkedTime,
+        })),
       h(WorkspaceEditor, {
         workspace: account.workspace,
         disabled: Boolean(busy),
@@ -217,18 +217,19 @@ export function WhatsappAccountCard({
         onSave: onAgentPresetSave,
       }),
       h('div', { className: 'ddt-accountFooter dim-cardFooter' },
-        summary ? h('div', { className: 'ddt-summary dim-cardSummary' }, summary) : null,
-        testNotice ? h('div', {
-          className: 'ddt-summary dim-cardSummary',
-          role: 'status',
-        }, testNotice) : null,
-        h('div', { className: 'ddt-actions dim-cardActions' },
-          h(Button, {
-            className: 'dim-cardAction', onClick: onReconnect, disabled: Boolean(busy),
-          }, busy === 'reconnect' ? '检查中…' : account.connected ? '检查连接' : '重试连接'),
-          h(Button, {
-            className: 'dim-cardAction', kind: 'danger', onClick: onRequestRemove, disabled: Boolean(busy),
-          }, '移除接入')))),
+        h('div', { className: 'dim-cardFooterLayout' },
+          h('div', { className: 'ddt-actions dim-cardActions' },
+            h(Button, {
+              className: 'dim-cardAction', onClick: onReconnect, disabled: Boolean(busy),
+            }, busy === 'reconnect' ? '检查中…' : account.connected ? '检查连接' : '重试连接'),
+            h(Button, {
+              className: 'dim-cardAction', kind: 'danger', onClick: onRequestRemove, disabled: Boolean(busy),
+            }, '移除接入')),
+          summary ? h('div', { className: 'ddt-summary dim-cardSummary' }, summary) : null,
+          testNotice ? h('div', {
+            className: 'ddt-summary dim-cardFeedback',
+            role: 'status',
+          }, testNotice) : null))),
     removing ? h(RemoveConfirmation, {
       account,
       busy: busy === 'delete',
@@ -439,8 +440,11 @@ export function WhatsappSettingsTab({ rpcCall }) {
 
   const botList = model.bots.length > 0
     ? h('section', { className: 'dim-listSection' },
-        h('div', { className: 'ddt-listHeading dim-listHeading' },
-          h('h3', null, '已接入的 WhatsApp 机器人')),
+        h(ChannelListHeading, {
+          className: 'ddt-listHeading',
+          title: '已接入的 WhatsApp 机器人',
+          connectionLabel: 'WhatsApp Web',
+        }),
         h('ul', { className: 'ddt-list dim-botList' }, model.bots.map((account) =>
           h('li', { key: account.botId }, h(WhatsappAccountCard, {
             account,

package/plugin-src/client/i18n.js

@@ -107,6 +107,7 @@ const EN = Object.freeze({
   '离线': 'Offline',
   '已断开': 'Disconnected',
   '消息通道': 'Message channel',
+  '查看消息通道说明': 'View message channel details',
   '最近检查': 'Last checked',
   '当前工作区': 'Current workspace',
   '选择目录': 'Choose folder',
@@ -136,6 +137,7 @@ const EN = Object.freeze({
   '工作区路径必须指向一个目录。': 'The workspace path must point to a directory.',
   '找不到要修改的机器人。': 'The bot could not be found.',
   'Agent Preset': 'Agent Preset',
+  '查看 Agent Preset 说明': 'View Agent Preset help',
   '跟随 Host 默认': 'Follow the Host default',
   '（已不可用）': ' (unavailable)',
   '只影响新建会话；若当前聊天已有会话，先发送 /new，再发送普通消息生效。': 'This affects only new sessions. If the current chat already has a session, send /new, then send a regular message to apply it.',

package/plugin-src/client/styles.js

@@ -87,6 +87,14 @@ const CSS = String.raw`
 .dim-panel .dim-listSection { display: flex; flex-direction: column; gap: 0; }
 .dim-panel .dim-listHeading { min-height: 0; display: flex; align-items: center; justify-content: space-between; gap: 16px; margin: 0 0 6px; padding: 0; }
 .dim-panel .dim-listHeading h3 { margin: 0; color: var(--dsw-alias-label-primary, #1f2329); font-size: 14px; line-height: normal; font-weight: 650; }
+.dim-panel .dim-listTitle { min-width: 0; display: inline-flex; align-items: center; gap: 6px; }
+.dim-panel .dim-channelHelp { position: relative; display: inline-flex; flex: none; }
+.dim-panel .dim-channelHelpButton { width: 17px; height: 17px; display: grid; place-items: center; padding: 0; border: 1px solid color-mix(in srgb, #1677ff 28%, var(--dsw-alias-border-l2, #dfe1e5)); border-radius: 50%; color: #1677ff; background: var(--dsw-alias-bg-layer-1, #fff); font: inherit; font-size: 11px; line-height: 1; font-weight: 700; cursor: help; transition: border-color .15s ease, color .15s ease, background .15s ease, box-shadow .15s ease; }
+.dim-panel .dim-channelHelpButton:hover { border-color: #1677ff; color: #0f5fce; background: color-mix(in srgb, #1677ff 8%, var(--dsw-alias-bg-layer-1, #fff)); }
+.dim-panel .dim-channelHelpButton:focus-visible { outline: none; border-color: #1677ff; box-shadow: 0 0 0 3px color-mix(in srgb, #1677ff 16%, transparent); }
+.dim-panel .dim-channelTooltip { position: absolute; top: calc(100% + 7px); left: 0; z-index: 30; width: max-content; max-width: min(280px, calc(100vw - 48px)); display: flex; align-items: baseline; gap: 5px; padding: 8px 10px; border: 1px solid var(--dsw-alias-border-l2, #dfe1e5); border-radius: 8px; color: var(--dsw-alias-label-secondary, #646a73); background: var(--dsw-alias-bg-layer-3, #fff); box-shadow: 0 10px 28px rgb(31 35 41 / 16%); font-size: 11px; line-height: 16px; font-weight: 400; white-space: normal; opacity: 0; visibility: hidden; transform: translateY(-3px); pointer-events: none; transition: opacity .15s ease, transform .15s ease, visibility .15s ease; }
+.dim-panel .dim-channelTooltip strong { color: var(--dsw-alias-label-primary, #1f2329); font-weight: 600; white-space: nowrap; }
+.dim-panel .dim-channelHelp:hover .dim-channelTooltip, .dim-panel .dim-channelHelp:focus-within .dim-channelTooltip { opacity: 1; visibility: visible; transform: translateY(0); }
 .dim-panel .dim-botList { display: grid; gap: 8px; margin: 0; padding: 0; list-style: none; }
 .dim-panel .dim-loadingView { padding: 38px; color: var(--dsw-alias-label-secondary, #646a73); text-align: center; }
 .dim-panel .dim-loadingView h3 { margin: 0 0 7px; color: var(--dsw-alias-label-primary, #1f2329); font-size: 17px; line-height: normal; font-weight: 650; }
@@ -143,13 +151,18 @@ const CSS = String.raw`
 .dim-panel .dim-workspaceEdit:disabled { cursor: not-allowed; opacity: .55; }
 .dim-panel .dim-workspacePath { min-width: 0; max-width: 100%; grid-column: 1 / -1; grid-row: 2; display: block; overflow-x: auto; overflow-y: hidden; color: var(--dsw-alias-label-primary, #1f2329); font: 12px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace; white-space: nowrap; }
 .dim-panel .dim-preset { min-width: 0; display: grid; grid-template-columns: minmax(0, 1fr) max-content; align-items: center; column-gap: 10px; row-gap: 4px; margin-top: 6px; padding: 6px 10px; border: 1px solid var(--dsw-alias-border-l1, #eef0f3); border-radius: 9px; background: var(--dsw-alias-bg-module-platform, #f7f8fa); }
-.dim-panel .dim-presetHeader { display: contents; color: var(--dsw-alias-label-secondary, #646a73); font-size: 12px; line-height: normal; }
-.dim-panel .dim-presetHeader > span { grid-column: 1; grid-row: 1; white-space: nowrap; }
+.dim-panel .dim-presetHeader { position: relative; min-width: 0; grid-column: 1 / -1; grid-row: 1; display: flex; align-items: center; justify-content: space-between; gap: 10px; color: var(--dsw-alias-label-secondary, #646a73); font-size: 12px; line-height: normal; }
+.dim-panel .dim-presetTitle { min-width: 0; display: inline-flex; align-items: center; gap: 5px; white-space: nowrap; }
+.dim-panel .dim-presetHelp { display: inline-flex; align-items: center; flex: none; }
+.dim-panel .dim-presetHelpButton { width: 17px; height: 17px; display: grid; place-items: center; padding: 0; border: 1px solid color-mix(in srgb, #1677ff 28%, var(--dsw-alias-border-l2, #dfe1e5)); border-radius: 50%; color: #1677ff; background: var(--dsw-alias-bg-layer-1, #fff); font: inherit; font-size: 11px; line-height: 1; font-weight: 700; cursor: help; transition: border-color .15s ease, color .15s ease, background .15s ease, box-shadow .15s ease; }
+.dim-panel .dim-presetHelpButton:hover { border-color: #1677ff; color: #0f5fce; background: color-mix(in srgb, #1677ff 8%, var(--dsw-alias-bg-layer-1, #fff)); }
+.dim-panel .dim-presetHelpButton:focus-visible { outline: none; border-color: #1677ff; box-shadow: 0 0 0 3px color-mix(in srgb, #1677ff 16%, transparent); }
+.dim-panel .dim-presetTooltip { position: absolute; top: calc(100% + 7px); left: 0; z-index: 30; width: min(320px, 100%); padding: 9px 10px; border: 1px solid var(--dsw-alias-border-l2, #dfe1e5); border-radius: 8px; color: var(--dsw-alias-label-primary, #1f2329); background: var(--dsw-alias-bg-layer-3, #fff); box-shadow: 0 10px 28px rgb(31 35 41 / 16%); font-size: 11px; line-height: 16px; font-weight: 400; overflow-wrap: anywhere; white-space: normal; opacity: 0; visibility: hidden; transform: translateY(-3px); pointer-events: none; transition: opacity .15s ease, transform .15s ease, visibility .15s ease; }
+.dim-panel .dim-presetHelp:hover .dim-presetTooltip, .dim-panel .dim-presetHelp:focus-within .dim-presetTooltip { opacity: 1; visibility: visible; transform: translateY(0); }
 .dim-panel .dim-presetStatus { grid-column: 2; grid-row: 1; color: var(--dsw-alias-label-tertiary, #8f959e); font-size: 12px; white-space: nowrap; }
 .dim-panel .dim-presetSelect { min-width: 0; max-width: 100%; grid-column: 1 / -1; grid-row: 2; height: 30px; padding: 0 8px; border: 1px solid var(--dsw-alias-border-l2, #dfe1e5); border-radius: 7px; color: var(--dsw-alias-label-primary, #1f2329); background: var(--dsw-alias-bg-layer-1, #fff); font: inherit; font-size: 12px; }
 .dim-panel .dim-presetSelect:disabled { cursor: not-allowed; opacity: .55; }
-.dim-panel .dim-presetHelp { grid-column: 1 / -1; grid-row: 3; color: var(--dsw-alias-label-tertiary, #8f959e); font-size: 11px; line-height: 1.4; }
-.dim-panel .dim-presetError { grid-column: 1 / -1; grid-row: 4; margin: 0; color: var(--dsw-alias-state-error-primary, #d54941); font-size: 12px; line-height: 1.4; }
+.dim-panel .dim-presetError { grid-column: 1 / -1; grid-row: 3; margin: 0; color: var(--dsw-alias-state-error-primary, #d54941); font-size: 12px; line-height: 1.4; }
 .dim-directoryPickerBackdrop { --dim-blue: var(--dsw-alias-state-business-primary, #3370ff); --dim-blue-soft: color-mix(in srgb, var(--dim-blue) 9%, transparent); position: fixed; inset: 0; z-index: 1000; display: grid; place-items: center; padding: 24px; background: rgb(15 17 21 / 42%); backdrop-filter: blur(3px); }
 .dim-directoryPickerBackdrop, .dim-directoryPickerBackdrop *, .dim-directoryPickerBackdrop *::before, .dim-directoryPickerBackdrop *::after { box-sizing: border-box; }
 .dim-directoryPicker { width: min(720px, 100%); height: min(620px, calc(100vh - 48px)); min-height: 420px; display: grid; grid-template-rows: auto minmax(0, 1fr) auto; overflow: hidden; border: 1px solid var(--dsw-alias-border-l2, #dfe1e5); border-radius: 18px; outline: none; color: var(--dsw-alias-label-primary, #1f2329); background: var(--dsw-alias-bg-layer-1, #fff); box-shadow: 0 24px 72px rgb(15 17 21 / 24%); }
@@ -192,6 +205,9 @@ const CSS = String.raw`
 .dim-directoryPickerActions button:hover:not(:disabled) { filter: brightness(.97); }
 .dim-directoryPickerActions button:disabled { cursor: not-allowed; opacity: .52; }
 .dim-panel .dim-cardSummary { min-width: 0; color: var(--dsw-alias-label-secondary, #646a73); font: inherit; font-size: 12px; font-weight: 400; line-height: normal; }
+.dim-panel .dim-cardFooterLayout { min-width: 0; width: 100%; display: flex; flex-direction: column; align-items: stretch; gap: 9px; }
+.dim-panel .dim-cardFooterLayout > .dim-cardActions { align-self: flex-end; }
+.dim-panel .dim-cardFeedback { width: 100%; padding: 8px 10px; border-radius: 8px; color: var(--dsw-alias-label-secondary, #646a73); background: var(--dsw-alias-bg-module-platform, #f7f8fa); font: inherit; font-size: 12px; font-weight: 400; line-height: 18px; overflow-wrap: anywhere; white-space: normal; }
 .dim-panel .dim-cardActions { flex: none; display: flex; align-items: center; flex-wrap: nowrap; gap: 8px; margin: 0 0 0 auto; }
 .dim-panel .dim-cardActions .dim-cardAction { flex: none; min-height: 32px; padding: 0 11px; border: 1px solid var(--dsw-alias-border-l2, #dfe1e5); border-radius: 8px; color: var(--dsw-alias-label-primary, #1f2329); background: var(--dsw-alias-bg-layer-1, #fff); font: inherit; font-size: 13px; font-weight: 560; line-height: normal; white-space: nowrap; }
 .dim-panel .dim-cardActions .dim-cardAction:hover:not(:disabled) { border-color: #aeb3bb; background: var(--dsw-alias-interactive-bg-hover, #f7f8fa); }
@@ -206,15 +222,13 @@ const CSS = String.raw`
 .dim-panel .dim-botName { min-width: 0; }
 .dim-panel .dim-botName h3 { overflow: hidden; margin: 0; color: var(--dsw-alias-label-primary, #1f2329); font-size: 15px; font-weight: 650; line-height: normal; text-overflow: ellipsis; white-space: nowrap; }
 .dim-panel .dim-botName p { overflow: hidden; margin: 4px 0 0; color: var(--dsw-alias-label-secondary, #646a73); font: 12px ui-monospace, SFMono-Regular, monospace; line-height: normal; text-overflow: ellipsis; white-space: nowrap; }
+.dim-panel .dim-botHealthGroup { flex: none; display: grid; justify-items: end; gap: 5px; }
 .dim-panel .dim-botCard .dim-botHealth { flex: none; min-height: 0; display: inline-flex; align-items: center; gap: 7px; padding: 0; border: 0; border-radius: 0; color: var(--dsw-alias-label-secondary, #646a73); background: transparent; font: inherit; font-size: 12px; font-weight: 400; line-height: normal; white-space: nowrap; }
+.dim-panel .dim-lastChecked { display: inline-flex; align-items: baseline; gap: 4px; color: var(--dsw-alias-label-tertiary, #8f959e); font: inherit; font-size: 11px; font-weight: 400; line-height: normal; white-space: nowrap; }
 .dim-panel .dim-botCard .dim-healthDot { flex: none; width: 8px; height: 8px; border-radius: 50%; background: #aeb3bb; box-shadow: none; }
 .dim-panel .dim-botCard .dim-healthDot[data-tone="success"] { background: var(--dsw-alias-state-success-primary, #20a162); box-shadow: 0 0 0 3px color-mix(in srgb, var(--dsw-alias-state-success-primary, #20a162) 14%, transparent); }
 .dim-panel .dim-botCard .dim-healthDot[data-tone="warning"] { background: var(--dsw-alias-state-warn-primary, #d97706); }
 .dim-panel .dim-botCard .dim-healthDot[data-tone="error"] { background: var(--dsw-alias-state-error-primary, #d54941); }
-.dim-panel .dim-botMetrics { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 8px; margin: 6px 0; }
-.dim-panel .dim-botMetric { min-width: 0; padding: 6px 8px; border: 0; border-radius: 9px; background: var(--dsw-alias-interactive-bg-hover, #f7f8fa); }
-.dim-panel .dim-botMetric dt { margin: 0; color: var(--dsw-alias-label-tertiary, #8f959e); font-size: 11px; font-weight: 400; line-height: normal; }
-.dim-panel .dim-botMetric dd { overflow: hidden; margin: 3px 0 0; color: var(--dsw-alias-label-primary, #1f2329); font-size: 12px; font-weight: 400; line-height: normal; text-overflow: ellipsis; white-space: nowrap; }
 .dim-panel .dim-botCard .dim-cardFooter { margin-top: 0; }
 .dim-panel .ddt-headingCopy { display: none; }
 .dim-panel .ddt-qrFrame, .dim-panel .ddt-countdown { width: min(270px, 100%); }
@@ -245,6 +259,7 @@ const CSS = String.raw`
 }
 @media (max-width: 720px) {
   .dim-panel .dim-botCardTop { flex-direction: column; align-items: stretch; }
+  .dim-panel .dim-botHealthGroup { justify-items: start; }
 }
 @media (max-width: 560px) {
   .dim-title { flex-direction: column; gap: 10px; }

package/plugin-src/host/index.mjs

@@ -8,9 +8,15 @@ import { apply as applyTelegram } from './channels/telegram/index.mjs';
 import { apply as applyWecom } from './channels/wecom/index.mjs';
 import { apply as applyWeixin } from './channels/weixin/index.mjs';
 import { apply as applyWhatsapp } from './channels/whatsapp/index.mjs';
+import { installOutboundArtifactTool } from '../../src/channels/shared/semantic/artifact.mjs';
 
 export const name = 'dsh-im-host';
-export const inject = ['connection', 'credentials', 'webServer', 'typertGateway'];
+export const inject = [
+  'connection',
+  'credentials',
+  'webServer',
+  'typertGateway',
+];
 
 function channelConfig(config, name) {
   const channel = config[name] ?? {};
@@ -34,6 +40,13 @@ export function createImHostPlugin(internals = {}) {
     name,
     inject,
     async apply(ctx, config = {}) {
+      if (typeof ctx?.inject === 'function') {
+        ctx.inject(['tools', 'systemPrompt'], (artifactCtx) => {
+          installOutboundArtifactTool(artifactCtx);
+        });
+      } else {
+        installOutboundArtifactTool(ctx);
+      }
       await startFeishu(ctx, channelConfig(config, 'feishu'));
       await startWeixin(ctx, channelConfig(config, 'weixin'));
       await startDingtalk(ctx, channelConfig(config, 'dingtalk'));

package/src/channels/dingtalk/dingtalk-api.mjs

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { extname } from 'node:path';
 
 import { fetchImageBuffer, ImagePromptError } from '../shared/image-prompt.mjs';
 
@@ -25,8 +26,67 @@ function nonEmptyString(value) {
 }
 
 function safeProviderCode(value) {
-  const code = nonEmptyString(value);
-  return code && /^[A-Za-z0-9_.:-]{1,160}$/.test(code) ? code : undefined;
+  const code = value === undefined || value === null ? null : String(value).trim();
+  return code && /^-?[A-Za-z0-9_.:-]{1,160}$/.test(code) ? code : undefined;
+}
+
+function preserveArtifactMetadata(target, source) {
+  if (Number.isInteger(source?.status)) target.status = source.status;
+  if (source?.providerCode !== undefined) target.providerCode = source.providerCode;
+  return target;
+}
+
+function dingtalkArtifactError(cause, { fallback = 'artifact-provider-rejected' } = {}) {
+  if (cause?.code?.startsWith?.('artifact-')) return cause;
+  const status = Number(cause?.status);
+  const providerCode = safeProviderCode(cause?.providerCode);
+  const providerText = providerCode ?? '';
+  let code = fallback;
+  let message = 'DingTalk could not prepare the file for delivery.';
+  if (status === 401 || status === 403 || providerCode === '401' || providerCode === '403'
+    || /(?:permission|forbidden|unauthor|access.?denied|\.auth(?:\.|$))/i.test(providerText)) {
+    code = 'artifact-permission-required';
+    message = 'DingTalk denied permission to send the file.';
+  } else if (status === 413 || providerCode === '413'
+    || /(?:too.?large|size.?limit)/i.test(providerText)) {
+    code = 'artifact-too-large';
+    message = 'The file exceeds DingTalk\'s size limit.';
+  } else if (status === 429 || providerCode === '429'
+    || /(?:rate.?limit|too.?many|throttl)/i.test(providerText)) {
+    code = 'artifact-rate-limited';
+    message = 'DingTalk rate-limited file delivery.';
+  } else if (fallback === 'artifact-provider-rejected') {
+    message = 'DingTalk rejected the file message.';
+  }
+  const error = new Error(message, { cause });
+  error.code = code;
+  return preserveArtifactMetadata(error, cause);
+}
+
+function uncertainDingtalkDelivery(cause) {
+  const error = new Error('DingTalk file delivery result is uncertain', { cause });
+  error.code = 'artifact-delivery-uncertain';
+  return preserveArtifactMetadata(error, cause);
+}
+
+function rejectedProviderResponse(value) {
+  if (!value || typeof value !== 'object') return null;
+  for (const field of ['errcode', 'code']) {
+    if (value[field] !== undefined && value[field] !== 0 && value[field] !== '0') {
+      return safeProviderCode(value[field]) ?? 'rejected';
+    }
+  }
+  return null;
+}
+
+function classifyDingtalkFinalDeliveryError(error, signal) {
+  if (signal?.aborted) throw abortError(signal);
+  const status = Number(error?.status);
+  if (error?.code === 'network-error' || error?.code === 'timeout'
+    || error?.code === 'invalid-response' || (status >= 500 && status < 600)) {
+    return uncertainDingtalkDelivery(error);
+  }
+  return dingtalkArtifactError(error);
 }
 
 function secureDingtalkDownloadUrl(value) {
@@ -174,6 +234,74 @@ async function requestJson(fetchImpl, url, {
   }
 }
 
+async function requestMultipart(fetchImpl, url, { body, signal, timeoutMs = 60_000 } = {}) {
+  const controller = new AbortController();
+  let timedOut = false;
+  const onAbort = () => controller.abort(signal?.reason);
+  if (signal?.aborted) throw abortError(signal);
+  signal?.addEventListener('abort', onAbort, { once: true });
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+  try {
+    const response = await fetchImpl(url, {
+      method: 'POST',
+      body,
+      signal: controller.signal,
+      redirect: 'error',
+    });
+    let value;
+    let parseError;
+    try {
+      value = await response.json();
+    } catch (error) {
+      parseError = error;
+    }
+    if (!response.ok) {
+      throw new DingtalkApiError(
+        'http-error',
+        `钉钉服务请求失败（HTTP ${response.status}）。`,
+        { status: response.status, providerCode: safeProviderCode(value?.code ?? value?.errcode) },
+      );
+    }
+    if (parseError) {
+      throw new DingtalkApiError(
+        'invalid-response',
+        '钉钉服务返回了无法解析的响应。',
+        { cause: parseError },
+      );
+    }
+    return value;
+  } catch (error) {
+    if (signal?.aborted) throw abortError(signal);
+    if (timedOut) throw new DingtalkApiError('timeout', '钉钉服务请求超时。', { cause: error });
+    if (error instanceof DingtalkApiError) throw error;
+    throw new DingtalkApiError('network-error', '暂时无法完成钉钉文件上传请求。', { cause: error });
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener('abort', onAbort);
+  }
+}
+
+function normalizeFileTarget(target) {
+  const robotCode = nonEmptyString(target?.robotCode);
+  if (!robotCode) throw new TypeError('DingTalk robotCode is required');
+  if (target?.type === 'group') {
+    const openConversationId = nonEmptyString(target.openConversationId);
+    if (openConversationId) return { type: 'group', robotCode, openConversationId };
+  }
+  if (target?.type === 'user') {
+    const userId = nonEmptyString(target.userId);
+    if (userId) return { type: 'user', robotCode, userId };
+  }
+  throw new TypeError('DingTalk file target is invalid');
+}
+
+function dingtalkFileType(fileName) {
+  return extname(fileName).slice(1).toLowerCase();
+}
+
 function normalizeCardTarget(target) {
   if (target?.type === 'user') {
     const userId = nonEmptyString(target.userId);
@@ -648,6 +776,91 @@ export function createDingtalkApi({
       return true;
     },
 
+    async sendFile({ clientId, clientSecret, target, file, signal }) {
+      if (!file || typeof file !== 'object'
+        || typeof file.fileName !== 'string' || !file.fileName
+        || !Buffer.isBuffer(file.bytes)) {
+        throw new TypeError('A DingTalk file is required');
+      }
+      const normalizedTarget = normalizeFileTarget(target);
+      const fileType = dingtalkFileType(file.fileName);
+      let token;
+      try {
+        token = await accessToken({ clientId, clientSecret, signal });
+      } catch (error) {
+        if (signal?.aborted) throw abortError(signal);
+        const status = Number(error?.status);
+        const fallback = error?.code === 'http-error' && status >= 400 && status < 500
+          ? 'artifact-provider-rejected'
+          : 'artifact-provider-failed';
+        throw dingtalkArtifactError(error, { fallback });
+      }
+      const uploadUrl = new URL('media/upload', DINGTALK_REGISTRATION_BASE_URL);
+      uploadUrl.searchParams.set('access_token', token);
+      uploadUrl.searchParams.set('type', 'file');
+      const form = new FormData();
+      form.append(
+        'media',
+        new Blob([file.bytes], { type: file.mediaType ?? 'application/octet-stream' }),
+        file.fileName,
+      );
+      let uploaded;
+      try {
+        uploaded = await requestMultipart(fetchImpl, uploadUrl, { body: form, signal });
+      } catch (error) {
+        if (signal?.aborted) throw abortError(signal);
+        const status = Number(error?.status);
+        const fallback = error?.code === 'http-error' && status >= 400 && status < 500
+          ? 'artifact-provider-rejected'
+          : 'artifact-provider-failed';
+        throw dingtalkArtifactError(error, { fallback });
+      }
+      const uploadRejection = rejectedProviderResponse(uploaded);
+      if (uploadRejection || !nonEmptyString(uploaded?.media_id)) {
+        throw dingtalkArtifactError(new DingtalkApiError(
+          'upload-rejected',
+          '钉钉服务拒绝了文件上传。',
+          { providerCode: uploadRejection ?? 'missing-media-id' },
+        ));
+      }
+      signal?.throwIfAborted();
+      const messageBody = {
+        robotCode: normalizedTarget.robotCode,
+        msgKey: 'sampleFile',
+        msgParam: JSON.stringify({
+          mediaId: uploaded.media_id,
+          fileName: file.fileName,
+          fileType,
+        }),
+        ...(normalizedTarget.type === 'group'
+          ? { openConversationId: normalizedTarget.openConversationId }
+          : { userIds: [normalizedTarget.userId] }),
+      };
+      const pathname = normalizedTarget.type === 'group'
+        ? 'v1.0/robot/groupMessages/send'
+        : 'v1.0/robot/oToMessages/batchSend';
+      let response;
+      try {
+        response = await requestJson(fetchImpl, endpoint(apiBase, pathname), {
+          body: messageBody,
+          headers: { 'x-acs-dingtalk-access-token': token },
+          signal,
+          action: '文件消息发送',
+        });
+      } catch (error) {
+        throw classifyDingtalkFinalDeliveryError(error, signal);
+      }
+      const sendRejection = rejectedProviderResponse(response);
+      if (sendRejection) {
+        throw dingtalkArtifactError(new DingtalkApiError(
+          'send-rejected',
+          '钉钉服务拒绝了文件消息。',
+          { providerCode: sendRejection },
+        ));
+      }
+      return response;
+    },
+
     clearAccessToken(clientId) {
       const appKey = nonEmptyString(clientId);
       if (appKey) tokenCache.delete(appKey);