@peng272/dsh-wechat-ilink 0.7.2 → 0.9.0

package/CHANGELOG.md

@@ -15,7 +15,78 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > documentation this project has: every one of them was an assumed DSH contract
 > that turned out to be wrong.
 
-## [0.7.2]
+## [0.9.0]
+
+### Added
+
+- **`dsh-wechat-ilink share <path>` — deliver a file as a link.** The file is
+  published into a share directory and a plain text message carrying an
+  unguessable download URL is sent to the bound user.
+
+### Why not an attachment
+
+  0.8.0 tried to send media items. They do not work, and the measurements are
+  unambiguous:
+
+  | Path | Gateway | CDN | Chat |
+  | --- | --- | --- | --- |
+  | `media_type: 1` (image) | issues an upload URL | **HTTP 400 `x-error-code -5102031`** | — |
+  | `media_type: 3` (file) | issues an upload URL | HTTP 200 + `x-encrypted-param` | **nothing appears** |
+  | text | — | — | arrives |
+
+  `sendmessage` returns a `message_id` for file items, so the gateway accepts
+  them; the ClawBot chat UI simply does not render attachment messages. Two
+  variants were tested against a live chat and neither appeared: an image item
+  over a file-type upload (to isolate the renderer), and a file item carrying
+  `create_time_ms` + `is_completed` (to rule out missing fields).
+
+  Text is the only channel proven to arrive, so a file becomes a link.
+  `send` is kept for completeness but is documented as not rendering.
+
+- **`dsh-wechat-ilink serve [port]`** — the LAN share server (default port
+  8791). It serves only the share directory, requires the token embedded in
+  every URL, refuses traversal outside the share directory, and is intended to
+  run under a scheduled task.
+## [0.8.0]
+
+### Added
+
+- **Outbound media: the channel can now send a file into the WeChat chat.**
+  `dsh-wechat-ilink send <path>` uploads a local file and delivers it to the
+  bound user. Images travel as image items (rendered inline) and everything else
+  as a file item (a downloadable attachment).
+
+  The protocol was already documented inside the 0.6.x sources — `getuploadurl`
+  -> AES-128-ECB -> CDN upload -> `x-encrypted-param` -> media item — but
+  `CdnClient.upload()` was never wired to anything, so neither series could
+  actually send media. It is implemented now in `lib/cdn.js`, and the upload
+  request parameters come from the 0.6.x `GetUploadUrlReq` type.
+
+- The channel persists the newest `context_token` to `<stateDir>/outbound.json`
+  as inbound messages arrive. The gateway requires it on every send, and without
+  it a shell command started later has nothing to send with.
+
+### Note
+
+- Sending media is subject to the same gateway throttling as text, and a file is
+  far heavier than a message. Large files may be rejected by the gateway; treat
+  a failure as a normal outcome and fall back to a link.
+
+- **Images are sent as files, not inline.** The image path (`media_type: 1`) is
+  not usable from this client: the gateway issues an upload URL for it, but the
+  CDN then answers
+
+  ```
+  HTTP 400   x-error-code: -5102031
+  ```
+
+  for bytes that the *same* request uploads successfully as `media_type: 3`.
+  `GetUploadUrlReq` carries `thumb_rawsize` / `thumb_rawfilemd5` and
+  `GetUploadUrlResp` carries `thumb_upload_param`, so the image path evidently
+  expects thumbnail metadata this client does not produce (resizing needs an
+  image codec). Pictures therefore arrive as downloadable attachments rather
+  than rendering inline. Verified with both a 382-byte and a 494-byte PNG, and
+  against a 5712-byte document that uploaded fine.## [0.7.2]
 
 ### Fixed
 

package/lib/cdn.js

@@ -0,0 +1,218 @@
+/**
+ * WeChat CDN media transport.
+ *
+ * Outbound: `ilink/bot/getuploadurl` -> AES-128-ECB encrypt -> POST the
+ * ciphertext to the CDN -> use the `x-encrypted-param` response header as
+ * `encrypt_query_param` in the sent message item.
+ *
+ * Inbound: GET `/download?encrypted_query_param=...` -> AES-128-ECB decrypt.
+ *
+ * `aes_key` on the wire has two encodings; inbound decoding must accept both.
+ */
+import crypto from 'node:crypto'
+
+export const CDN_BASE_URL = 'https://novac2c.cdn.weixin.qq.com/c2c'
+
+/** Message item types (subset used here). */
+export const MessageItemType = { TEXT: 1, IMAGE: 2, VOICE: 3, FILE: 4 }
+
+/** Requested upload kind. */
+export const UploadMediaType = { IMAGE: 1, VIDEO: 2, FILE: 3, VOICE: 4 }
+
+/** Ciphertext length after PKCS7 padding. */
+export function encryptedSize(plaintextSize) {
+  return Math.ceil((plaintextSize + 1) / 16) * 16
+}
+
+/** Random 16-byte key, hex encoded (32 chars). */
+export function randomAesKeyHex() {
+  return crypto.randomBytes(16).toString('hex')
+}
+
+/** Random 16-byte file key, hex encoded. */
+export function randomFileKey() {
+  return crypto.randomBytes(16).toString('hex')
+}
+
+export function md5Hex(data) {
+  return crypto.createHash('md5').update(data).digest('hex')
+}
+
+export function encryptAesEcb(plaintext, key) {
+  const cipher = crypto.createCipheriv('aes-128-ecb', key, null)
+  return Buffer.concat([cipher.update(plaintext), cipher.final()])
+}
+
+export function decryptAesEcb(ciphertext, key) {
+  const decipher = crypto.createDecipheriv('aes-128-ecb', key, null)
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()])
+}
+
+/**
+ * Decode a wire `aes_key` into a raw 16-byte key.
+ *
+ * Accepts both encodings seen in the wild:
+ *   A. base64(raw 16 bytes)
+ *   B. base64(32-char hex string)
+ */
+export function decodeAesKey(aesKey) {
+  if (!aesKey) return null
+  const trimmed = String(aesKey).trim()
+  try {
+    const a = Buffer.from(trimmed, 'base64')
+    if (a.length === 16) return a
+    if (a.length === 32 && /^[0-9a-fA-F]{32}$/.test(a.toString('utf-8'))) {
+      return Buffer.from(a.toString('utf-8'), 'hex')
+    }
+  } catch {
+    /* fall through */
+  }
+  // Bare hex (32 chars) — as used by `image_item.aeskey`.
+  if (/^[0-9a-fA-F]{32}$/.test(trimmed)) return Buffer.from(trimmed, 'hex')
+  return null
+}
+
+/** Encode a raw 16-byte key the way official clients do for outbound media. */
+export function encodeAesKeyForWire(keyHex) {
+  return Buffer.from(keyHex, 'utf-8').toString('base64')
+}
+
+/** Identify an image type from its magic bytes; null when it is not an image. */
+export function sniffImageMediaType(bytes) {
+  if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+    return 'image/png'
+  }
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg'
+  if (
+    bytes.length >= 12 &&
+    bytes.subarray(0, 4).toString('ascii') === 'RIFF' &&
+    bytes.subarray(8, 12).toString('ascii') === 'WEBP'
+  ) {
+    return 'image/webp'
+  }
+  if (bytes.length >= 6 && bytes.subarray(0, 6).toString('ascii').startsWith('GIF8')) return 'image/gif'
+  if (bytes.length >= 12 && bytes.subarray(4, 12).toString('ascii').startsWith('ftyp')) return 'image/heic'
+  return null
+}
+
+/** Wire format of a CDN media reference. */
+export function cdnMedia(encryptQueryParam, keyHex) {
+  return {
+    encrypt_query_param: encryptQueryParam,
+    aes_key: encodeAesKeyForWire(keyHex),
+    encrypt_type: 0,
+  }
+}
+
+/**
+ * Build the outbound message item for an uploaded media object.
+ *
+ * @param {Buffer} plaintext the exact bytes that were encrypted
+ * @param {{mediaType: 1|2|3|4, encryptQueryParam: string, keyHex: string, fileName?: string}} uploaded
+ */
+export function buildMediaItem(plaintext, uploaded) {
+  const media = cdnMedia(uploaded.encryptQueryParam, uploaded.keyHex)
+  if (uploaded.mediaType === UploadMediaType.IMAGE) {
+    return {
+      type: MessageItemType.IMAGE,
+      image_item: {
+        media,
+        // Raw 32-char hex is preferred over media.aes_key for images.
+        aeskey: uploaded.keyHex,
+        mid_size: plaintext.length,
+      },
+    }
+  }
+  return {
+    type: MessageItemType.FILE,
+    file_item: {
+      media,
+      file_name: uploaded.fileName || 'file',
+      md5: md5Hex(plaintext),
+      // Plaintext size, as a string.
+      len: String(plaintext.length),
+    },
+  }
+}
+
+export class CdnClient {
+  #cdnBaseUrl
+  #fetch
+
+  constructor(opts = {}) {
+    this.#cdnBaseUrl = opts.cdnBaseUrl?.trim() || CDN_BASE_URL
+    this.#fetch = opts.fetchImpl ?? globalThis.fetch
+  }
+
+  /**
+   * Upload ciphertext to the CDN and return the `x-encrypted-param` value.
+   * `uploadFullUrl` (when the server provided one) takes precedence.
+   */
+  async upload(params) {
+    const url = params.uploadFullUrl?.trim()
+      ? params.uploadFullUrl.trim()
+      : (() => {
+          const base = this.#cdnBaseUrl.endsWith('/') ? this.#cdnBaseUrl : `${this.#cdnBaseUrl}/`
+          const u = new URL('upload', base)
+          u.searchParams.set('encrypted_query_param', params.encryptedQueryParam ?? '')
+          u.searchParams.set('filekey', params.fileKey)
+          return u.toString()
+        })()
+    const res = await this.#fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/octet-stream' },
+      body: new Uint8Array(params.ciphertext),
+      ...(params.signal ? { signal: params.signal } : {}),
+    })
+    if (!res.ok) {
+      const detail = res.headers.get('x-error-message') ?? ''
+      throw new Error(`CDN upload HTTP ${res.status}${detail ? `: ${detail}` : ''}`)
+    }
+    const param = res.headers.get('x-encrypted-param')
+    if (!param) throw new Error('CDN upload succeeded but returned no x-encrypted-param header')
+    return param
+  }
+
+  /** Download and AES-128-ECB decrypt one CDN object. */
+  async download(params) {
+    const url = params.fullUrl?.trim()
+      ? params.fullUrl.trim()
+      : (() => {
+          const base = this.#cdnBaseUrl.endsWith('/') ? this.#cdnBaseUrl : `${this.#cdnBaseUrl}/`
+          const u = new URL('download', base)
+          u.searchParams.set('encrypted_query_param', params.encryptQueryParam ?? '')
+          return u.toString()
+        })()
+    const res = await this.#fetch(url, { ...(params.signal ? { signal: params.signal } : {}) })
+    if (!res.ok) throw new Error(`CDN download HTTP ${res.status}`)
+    const ciphertext = Buffer.from(await res.arrayBuffer())
+    const key = decodeAesKey(params.aesKeyHex)
+    if (!key) throw new Error('CDN download: could not decode aes_key')
+    return decryptAesEcb(ciphertext, key)
+  }
+
+  /**
+   * Full outbound pipeline: encrypt, upload, and return everything the message
+   * item needs.
+   *
+   * @param {{plaintext: Buffer, fileKey: string, uploadParam: string, uploadFullUrl?: string, mediaType: number, signal?: AbortSignal}} params
+   * @returns {Promise<{encryptQueryParam: string, aesKeyHex: string, fileKey: string, cipherSize: number}>}
+   */
+  async uploadEncrypted(params) {
+    const keyHex = randomAesKeyHex()
+    const ciphertext = encryptAesEcb(params.plaintext, Buffer.from(keyHex, 'hex'))
+    const encryptQueryParam = await this.upload({
+      ...(params.uploadFullUrl ? { uploadFullUrl: params.uploadFullUrl } : {}),
+      encryptedQueryParam: params.uploadParam,
+      fileKey: params.fileKey,
+      ciphertext,
+      ...(params.signal ? { signal: params.signal } : {}),
+    })
+    return {
+      encryptQueryParam,
+      aesKeyHex: keyHex,
+      fileKey: params.fileKey,
+      cipherSize: ciphertext.length,
+    }
+  }
+}

package/lib/cli.js

@@ -18,8 +18,9 @@ import fs from 'node:fs'
 import path from 'node:path'
 
 import { AccountStore, resolveStateDir } from './accounts.js'
-import { ILinkClient, QrLoginManager, DEFAULT_BASE_URL, renderQrPng } from './ilink.js'
+import { ILinkClient, QrLoginManager, DEFAULT_BASE_URL, renderQrPng, sendLocalFile } from './ilink.js'
 import { redactToken, readLogTail } from './support.js'
+import { DEFAULT_PORT, publishFile, shareUrl, startShareServer, lanAddress } from './share.js'
 
 const CHANNEL_VERSION = '2.4.9'
 
@@ -129,14 +130,163 @@ function cmdLogout() {
   return 0
 }
 
+/**
+ * Send one local file to the bound WeChat user.
+ *
+ * This is the entry point the agent itself uses: it runs in its own shell, so a
+ * plain command is all it needs to hand a file back over the chat.
+ */
+async function cmdSend(args) {
+  const target = args[0]
+  if (!target) {
+    out('用法: dsh-wechat-ilink send <文件路径>')
+    out('     把本机的一个文件发送给已绑定的微信用户。')
+    return 1
+  }
+  const abs = path.resolve(target)
+  if (!fs.existsSync(abs)) {
+    out(`文件不存在: ${abs}`)
+    return 1
+  }
+  if (!fs.statSync(abs).isFile()) {
+    out(`不是文件（目录暂不支持）: ${abs}`)
+    return 1
+  }
+
+  const { store, client } = makeRuntime()
+  const ids = store.listAccountIds()
+  if (ids.length === 0) {
+    out('还没有绑定微信账号。先运行: dsh-wechat-ilink login')
+    return 1
+  }
+  const account = store.load(ids[0])
+  if (!account?.token) {
+    out('账号记录里没有 token，请重新 login。')
+    return 1
+  }
+
+  // The gateway requires the newest `context_token`, which only arrives with an
+  // inbound message; the channel persists it for exactly this use.
+  const inboundFile = path.join(store.dir, 'outbound.json')
+  if (!fs.existsSync(inboundFile)) {
+    out('还拿不到 context_token —— 请先在微信里给机器人发一条消息，再重试。')
+    return 1
+  }
+  const inbound = JSON.parse(fs.readFileSync(inboundFile, 'utf-8'))
+  if (!inbound?.userId || !inbound?.contextToken) {
+    out(`${inboundFile} 里缺少 userId / contextToken，请先在微信里发一条消息。`)
+    return 1
+  }
+
+  const size = fs.statSync(abs).size
+  out(`发送中  ${path.basename(abs)}  (${size} 字节)  →  ${inbound.userId}`)
+  try {
+    const result = await sendLocalFile({
+      client,
+      token: account.token,
+      toUserId: inbound.userId,
+      contextToken: inbound.contextToken,
+      filePath: abs,
+    })
+    out(`✅ 已发送  类型=${result.kind}  文件名=${result.fileName}  字节=${result.bytes}`)
+    return 0
+  } catch (error) {
+    out(`❌ 发送失败: ${error?.message ?? error}`)
+    return 1
+  }
+}
+
+/**
+ * Publish a file into the share directory and send the download link as text.
+ *
+ * This is the route that actually reaches the phone: text always renders, media
+ * items never do (see lib/share.js for the measurements).
+ */
+async function cmdShare(args) {
+  const target = args[0]
+  if (!target) {
+    out('用法: dsh-wechat-ilink share <文件路径> [端口]')
+    out('     把文件发布成一条链接并发送给已绑定的微信用户。')
+    return 1
+  }
+  const abs = path.resolve(target)
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+    out(`文件不存在或不是文件: ${abs}`)
+    return 1
+  }
+
+  const { store, client } = makeRuntime()
+  const ids = store.listAccountIds()
+  if (ids.length === 0) {
+    out('还没有绑定微信账号。先运行: dsh-wechat-ilink login')
+    return 1
+  }
+  const account = store.load(ids[0])
+  const inboundFile = path.join(store.dir, 'outbound.json')
+  if (!fs.existsSync(inboundFile)) {
+    out('还拿不到 context_token —— 请先在微信里给机器人发一条消息，再重试。')
+    return 1
+  }
+  const inbound = JSON.parse(fs.readFileSync(inboundFile, 'utf-8'))
+  if (!inbound?.userId || !inbound?.contextToken) {
+    out(`${inboundFile} 里缺少 userId / contextToken。`)
+    return 1
+  }
+
+  const shareDir = resolveShareDir()
+  const port = Number(args[1]) || DEFAULT_PORT
+  const published = publishFile(shareDir, abs)
+  const url = shareUrl(shareDir, published.storedName, port)
+
+  out(`已发布  ${published.originalName}  (${published.bytes} 字节)`)
+  out(`存放于  ${shareDir}`)
+  out(`链接    ${url}`)
+  if (!lanAddress()) out('⚠️ 本机没有局域网 IPv4 地址，手机可能访问不到这个链接。')
+
+  const res = await client.sendText(
+    account.token,
+    inbound.userId,
+    `📎 ${published.originalName}（${published.bytes} 字节）\n在手机上点开下载：\n${url}`,
+    inbound.contextToken,
+  )
+  if (res?.message_id) {
+    out(`✅ 链接消息已发送  message_id=${res.message_id}`)
+    out('   （请确认手机收到；若打不开，通常是手机不在同一 Wi-Fi）')
+    return 0
+  }
+  out(`⚠️ 发送返回: ${JSON.stringify(res)}`)
+  return 1
+}
+
+/** Run the LAN share server in the foreground. */
+function cmdServe(args) {
+  const port = Number(args[0]) || DEFAULT_PORT
+  const shareDir = resolveShareDir()
+  const server = startShareServer({ shareDir, port, log: (m) => out(`[${new Date().toISOString()}] ${m}`) })
+  server.on('error', (error) => {
+    out(`❌ 共享服务启动失败: ${error?.message ?? error}`)
+    process.exit(1)
+  })
+  // Keep the process alive.
+  return new Promise(() => {})
+}
+
+/** Share directory: next to the credentials, overridable for tests. */
+function resolveShareDir() {
+  return process.env.DSH_WECHAT_SHARE_DIR?.trim() || path.join(resolveStateDir(), 'share')
+}
+
 function usage() {
   out('dsh-wechat-ilink — 微信 ClawBot 通道')
   out('')
   out('用法：')
-  out('  dsh-wechat-ilink login     扫码绑定一个微信账号')
-  out('  dsh-wechat-ilink status    显示绑定状态与游标')
-  out('  dsh-wechat-ilink logs [n]  打印通道日志尾部')
-  out('  dsh-wechat-ilink logout    解除全部绑定')
+  out('  dsh-wechat-ilink login         扫码绑定一个微信账号')
+  out('  dsh-wechat-ilink status        显示绑定状态与游标')
+  out('  dsh-wechat-ilink share <路径>  把本机文件发布成一条可点击的下载链接（推荐）')
+  out('  dsh-wechat-ilink send <路径>   以附件形式发送（实测微信 ClawBot 不显示附件）')
+  out('  dsh-wechat-ilink serve [端口]  启动局域网文件共享服务（供 share 使用）')
+  out('  dsh-wechat-ilink logs [n]      打印通道日志尾部')
+  out('  dsh-wechat-ilink logout        解除全部绑定')
   return 0
 }
 
@@ -150,6 +300,15 @@ try {
     case 'status':
       code = await cmdStatus()
       break
+    case 'send':
+      code = await cmdSend(rest)
+      break
+    case 'share':
+      code = await cmdShare(rest)
+      break
+    case 'serve':
+      code = await cmdServe(rest)
+      break
     case 'logs':
       code = cmdLogs(rest)
       break

package/lib/ilink.js

@@ -7,8 +7,19 @@
  *   POST /ilink/bot/get_bot_qrcode    start a QR login
  *   GET  /ilink/bot/get_qrcode_status poll that login
  */
+import fs from 'node:fs'
+import path from 'node:path'
 import { randomUUID } from 'node:crypto'
 import { encodeQr, qrToPng, qrToTerminal } from './qr.js'
+import {
+  CdnClient,
+  UploadMediaType,
+  buildMediaItem,
+  encryptedSize,
+  md5Hex,
+  randomFileKey,
+  sniffImageMediaType,
+} from './cdn.js'
 
 export const DEFAULT_BASE_URL = 'https://ilinkai.weixin.qq.com'
 /** Long-poll window the gateway honours; the client timeout sits above it. */
@@ -101,6 +112,37 @@ export class ILinkClient {
     )
   }
 
+  /**
+   * Send one message carrying a caller-built `item_list` entry.
+   *
+   * `sendText` is the text-only special case of this; media items (image/file)
+   * go through exactly the same envelope.
+   */
+  async sendItem(token, toUserId, item, contextToken, signal) {
+    if (!contextToken) throw new Error('context_token is required for send')
+    return this.post(
+      'ilink/bot/sendmessage',
+      {
+        msg: {
+          from_user_id: '',
+          to_user_id: toUserId,
+          client_id: randomUUID(),
+          message_type: 2,
+          message_state: 2,
+          context_token: contextToken,
+          item_list: [item],
+        },
+        base_info: this.baseInfo(),
+      },
+      { token, timeoutMs: 30000, signal },
+    )
+  }
+
+  /** Request a pre-signed CDN upload URL for outbound media. */
+  async getUploadUrl(token, req, signal) {
+    return this.post('ilink/bot/getuploadurl', { ...req, base_info: this.baseInfo() }, { token, timeoutMs: 30000, signal })
+  }
+
   async requestQrCode() {
     return this.post('ilink/bot/get_bot_qrcode?bot_type=3', { local_token_list: [] }, { timeoutMs: 20000 })
   }
@@ -162,3 +204,88 @@ export function renderQrPng(url, { scale = 8, margin = 4 } = {}) {
   const qr = encodeQr(url, { ecc: 'M' })
   return { png: qrToPng(qr.modules, { scale, margin }), art: qrToTerminal(qr.modules, { margin: 2 }), meta: qr }
 }
+
+/**
+ * Send one local file to a WeChat user.
+ *
+ * Images travel as image items (the chat renders them inline); anything else
+ * travels as a file item (the chat shows a downloadable attachment). The
+ * protocol is identical for both:
+ *
+ *   1. `ilink/bot/getuploadurl` -> pre-signed CDN upload parameter
+ *   2. AES-128-ECB encrypt the bytes with a fresh random key
+ *   3. POST the ciphertext to the CDN -> `x-encrypted-param`
+ *   4. `ilink/bot/sendmessage` with the media item
+ *
+ * @returns {Promise<{fileName: string, bytes: number, kind: 'image'|'file', messageId?: string}>}
+ */
+export async function sendLocalFile({
+  client,
+  cdn = new CdnClient(),
+  token,
+  toUserId,
+  contextToken,
+  filePath,
+  signal,
+}) {
+  if (!contextToken) throw new Error('no context_token yet; the user must send a message first')
+  const plaintext = fs.readFileSync(filePath)
+  const fileName = path.basename(filePath)
+  const isImage = Boolean(sniffImageMediaType(plaintext))
+
+  // Everything travels as a file item, images included.
+  //
+  // The image path (media_type=1) is NOT usable from this client shape: the
+  // gateway issues an upload URL for it, but the CDN then rejects the upload with
+  //   HTTP 400  x-error-code: -5102031
+  // Measured against the same bytes uploaded as media_type=3, which returns 200.
+  // `GetUploadUrlReq` carries `thumb_rawsize` / `thumb_rawfilemd5` and
+  // `GetUploadUrlResp` carries `thumb_upload_param`, so the image path evidently
+  // expects thumbnail metadata this client does not produce (resizing needs an
+  // image codec). Sending images as files is the honest fallback: the recipient
+  // still receives the picture, as a downloadable attachment rather than inline.
+  const mediaType = UploadMediaType.FILE
+  const fileKey = randomFileKey()
+
+  const up = await client.getUploadUrl(
+    token,
+    {
+      filekey: fileKey,
+      media_type: mediaType,
+      to_user_id: toUserId,
+      rawsize: plaintext.length,
+      rawfilemd5: md5Hex(plaintext),
+      filesize: encryptedSize(plaintext.length),
+    },
+    signal,
+  )
+  const ret = Number(up?.ret)
+  if (Number.isFinite(ret) && ret !== 0) {
+    throw new Error(`getuploadurl declined ret=${ret} errcode=${up?.errcode} errmsg=${up?.errmsg}`)
+  }
+  if (!up?.upload_param && !up?.upload_full_url) throw new Error('getuploadurl returned no upload_param')
+
+  const uploaded = await cdn.uploadEncrypted({
+    plaintext,
+    fileKey,
+    uploadParam: up.upload_param,
+    ...(up.upload_full_url ? { uploadFullUrl: up.upload_full_url } : {}),
+    mediaType,
+    ...(signal ? { signal } : {}),
+  })
+
+  const item = buildMediaItem(plaintext, {
+    mediaType,
+    encryptQueryParam: uploaded.encryptQueryParam,
+    keyHex: uploaded.aesKeyHex,
+    fileName,
+  })
+
+  const res = await client.sendItem(token, toUserId, item, contextToken, signal)
+  const sendRet = Number(res?.ret)
+  if (Number.isFinite(sendRet) && sendRet !== 0) {
+    throw new Error(`sendmessage declined ret=${sendRet} errcode=${res?.errcode} errmsg=${res?.errmsg}`)
+  }
+
+  return { fileName, bytes: plaintext.length, kind: isImage ? 'image' : 'file', messageId: res?.message_id }
+}

package/lib/index.js

@@ -209,6 +209,23 @@ export function apply(ctx, rawConfig) {
   const limiter = new RateLimiter(config.outgoingMaxPerSec ?? 0.5, config.outgoingBurst ?? 1)
   let lastContextToken = ''
 
+  // The gateway's `context_token` only arrives with an inbound message, and it is
+  // required for every outbound send. Persisting the newest one lets the CLI
+  // (and therefore the agent's own shell) send media without holding live state.
+  const outboundFile = path.join(stateDir, 'outbound.json')
+  function persistOutbound(userId, contextToken) {
+    try {
+      fs.mkdirSync(stateDir, { recursive: true })
+      fs.writeFileSync(
+        outboundFile,
+        JSON.stringify({ userId, contextToken, at: new Date().toISOString() }, null, 2),
+        'utf-8',
+      )
+    } catch (error) {
+      log('error', `could not persist outbound context: ${error?.message ?? error}`)
+    }
+  }
+
   async function sendText(toUserId, text) {
     if (!lastContextToken) {
       log('error', `no context_token yet for ${toUserId}; they must send a message first`)
@@ -341,7 +358,10 @@ export function apply(ctx, rawConfig) {
     if (!from) return
 
     const token = String(msg?.context_token || '').trim()
-    if (token) lastContextToken = token
+    if (token) {
+      lastContextToken = token
+      persistOutbound(from, token)
+    }
 
     // A sender is allowed when explicitly listed, otherwise only the account
     // that scanned the QR may drive the agent.

package/lib/share.js

@@ -0,0 +1,173 @@
+/**
+ * LAN file share for the WeChat channel.
+ *
+ * Why this exists: the WeChat ClawBot chat UI does not render attachment
+ * messages. Measured behaviour —
+ *   - uploads of `media_type: 3` succeed and `sendmessage` returns a
+ *     `message_id`, yet nothing appears in the chat;
+ *   - uploads of `media_type: 1` are rejected outright by the CDN
+ *     (`HTTP 400 x-error-code -5102031`).
+ * Text, by contrast, always arrives. So instead of fighting the media format,
+ * a file becomes a plain text message containing a link the phone can open.
+ *
+ * The share directory holds only files deliberately published through
+ * `dsh-wechat-ilink share`, and every URL carries an unguessable token, so the
+ * port being reachable on the LAN does not expose the rest of the machine.
+ */
+import fs from 'node:fs'
+import http from 'node:http'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+export const DEFAULT_PORT = 8791
+
+/** First non-loopback IPv4 address, or null when there is none. */
+export function lanAddress() {
+  const ifaces = os.networkInterfaces()
+  for (const list of Object.values(ifaces)) {
+    for (const entry of list ?? []) {
+      if (entry.family === 'IPv4' && !entry.internal) return entry.address
+    }
+  }
+  return null
+}
+
+/** Read the share token, creating it on first use. */
+export function ensureToken(shareDir) {
+  fs.mkdirSync(shareDir, { recursive: true })
+  const file = path.join(shareDir, '.token')
+  try {
+    const existing = fs.readFileSync(file, 'utf-8').trim()
+    if (existing) return existing
+  } catch {
+    /* create below */
+  }
+  const token = crypto.randomBytes(16).toString('hex')
+  fs.writeFileSync(file, token, 'utf-8')
+  return token
+}
+
+/**
+ * Publish one local file into the share directory.
+ *
+ * The stored name carries a short random prefix so a link cannot be guessed from
+ * the original file name alone.
+ *
+ * @returns {{storedName: string, bytes: number, originalName: string}}
+ */
+export function publishFile(shareDir, sourcePath) {
+  fs.mkdirSync(shareDir, { recursive: true })
+  const originalName = path.basename(sourcePath)
+  const safe = originalName.replace(/[^\w.\-\u4e00-\u9fa5]+/g, '_').slice(0, 80) || 'file'
+  const storedName = `${crypto.randomBytes(4).toString('hex')}-${safe}`
+  fs.copyFileSync(sourcePath, path.join(shareDir, storedName))
+  return { storedName, bytes: fs.statSync(sourcePath).size, originalName }
+}
+
+/** Build the URL a phone can open. */
+export function shareUrl(shareDir, storedName, port = DEFAULT_PORT) {
+  const token = ensureToken(shareDir)
+  const host = lanAddress() ?? '127.0.0.1'
+  return `http://${host}:${port}/f/${token}/${encodeURIComponent(storedName)}`
+}
+
+function escapeHtml(text) {
+  return String(text).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c])
+}
+
+const MIME = {
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/markdown; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.pdf': 'application/pdf',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.zip': 'application/zip',
+  '.csv': 'text/csv; charset=utf-8',
+  '.log': 'text/plain; charset=utf-8',
+}
+
+/**
+ * Start the share server.
+ *
+ * @param {{shareDir: string, port?: number, log?: (m: string) => void}} options
+ * @returns {import('node:http').Server}
+ */
+export function startShareServer({ shareDir, port = DEFAULT_PORT, log = () => {} }) {
+  const token = ensureToken(shareDir)
+
+  const server = http.createServer((req, res) => {
+    let url
+    try {
+      url = new URL(req.url ?? '/', 'http://localhost')
+    } catch {
+      res.writeHead(400).end('bad request')
+      return
+    }
+    const parts = url.pathname.split('/').filter(Boolean)
+    // /f/<token>/<name>  and  /f/<token>/  (index)
+    if (parts[0] !== 'f' || parts[1] !== token) {
+      log(`denied ${req.method} ${url.pathname} from ${req.socket.remoteAddress}`)
+      res.writeHead(404).end('not found')
+      return
+    }
+
+    if (parts.length === 2) {
+      let entries = []
+      try {
+        entries = fs.readdirSync(shareDir).filter((n) => !n.startsWith('.'))
+      } catch {
+        /* empty */
+      }
+      const items = entries
+        .map((n) => {
+          const st = fs.statSync(path.join(shareDir, n))
+          return `<li><a href="/f/${token}/${encodeURIComponent(n)}">${escapeHtml(n)}</a> <small>${st.size} B</small></li>`
+        })
+        .join('')
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+      res.end(`<!doctype html><meta name="viewport" content="width=device-width,initial-scale=1"><h3>共享文件</h3><ul>${items || '<li>（空）</li>'}</ul>`)
+      log(`index served (${entries.length} file(s))`)
+      return
+    }
+
+    const name = decodeURIComponent(parts.slice(2).join('/'))
+    // Never let a crafted name escape the share directory.
+    const resolved = path.resolve(shareDir, name)
+    if (!resolved.startsWith(path.resolve(shareDir) + path.sep)) {
+      log(`escape attempt blocked: ${name}`)
+      res.writeHead(403).end('forbidden')
+      return
+    }
+    let st
+    try {
+      st = fs.statSync(resolved)
+    } catch {
+      res.writeHead(404).end('not found')
+      return
+    }
+    if (!st.isFile()) {
+      res.writeHead(404).end('not found')
+      return
+    }
+
+    log(`served ${name} (${st.size} B) to ${req.socket.remoteAddress}`)
+    res.writeHead(200, {
+      'Content-Type': MIME[path.extname(resolved).toLowerCase()] ?? 'application/octet-stream',
+      'Content-Length': st.size,
+      'Content-Disposition': `attachment; filename*=UTF-8''${encodeURIComponent(path.basename(resolved))}`,
+    })
+    fs.createReadStream(resolved).pipe(res)
+  })
+
+  server.listen(port, '0.0.0.0', () => {
+    log(`share server listening on 0.0.0.0:${port}  dir=${shareDir}`)
+    log(`phone URL base: http://${lanAddress() ?? '<no-lan-ip>'}:${port}/f/${token}/`)
+  })
+
+  return server
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peng272/dsh-wechat-ilink",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "description": "WeChat ClawBot (Tencent iLink) channel for DeepSeek Harness 0.2.0-rc.2 — talk to DSH from WeChat.",
   "type": "module",
   "main": "lib/index.js",
@@ -10,6 +10,8 @@
   "exports": {
     ".": "./lib/index.js",
     "./schema": "./lib/schema.js",
+    "./cdn": "./lib/cdn.js",
+    "./share": "./lib/share.js",
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json"
   },