@peng272/dsh-wechat-ilink 0.0.0-stage → 0.7.1

package/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+All notable changes to **dsh-wechat-ilink** are recorded here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **Note on versions.** `0.1.0` → `0.6.4` are the *same* number series used during
+> development; the first public release is simply `0.6.4`. Keeping one continuous
+> series is deliberate — if the repository restarted at `0.1.0` while the working
+> copies were already at `0.6.x`, an internal build and a published build could
+> carry the same number and be told apart only by guesswork.
+>
+> The pre-release entries are kept because the bug sequence is the most useful
+> documentation this project has: every one of them was an assumed DSH contract
+> that turned out to be wrong.
+
+## [0.7.1]
+
+### Fixed
+
+- **A fresh conversation could never start.** Every turn passed
+  `--session-id <sessionId>`, but `dsh --profile headless --session-id` requires
+  that session to already exist. On a new install the recorded id
+  (`wechat-clawbot`) does not exist yet, so **every** inbound message failed with
+
+  ```
+  dsh: session "wechat-clawbot" does not exist; omit --session-id to start a new Session
+  ```
+
+  and produced no reply. The first turn now omits the flag (which creates the
+  session), the id the driver reports is persisted to `<stateDir>/session.json`,
+  and later turns resume it. A recorded session that has since disappeared is
+  detected and transparently restarted.
+
+  Found by reading the channel log of a live install; the failure was silent from
+  WeChat's side (the message simply got no answer).
+
+- Driver-level failures emitted as a `{"type":"error"}` frame are now surfaced in
+  the log instead of being reported only as `reason=incomplete`.
+
+### Changed
+
+- The package is published as **`@peng272/dsh-wechat-ilink`**. The bare name
+  `dsh-wechat-ilink` belongs to another maintainer and cannot be updated from
+  this account.
+## [0.7.0]
+
+A reimplementation of the channel internals. The **runtime identities are
+unchanged**, so an existing install upgrades in place.
+
+### Upgrade behaviour (verified)
+
+| Thing | Result |
+| --- | --- |
+| Bundle row `id` | unchanged — `wechat-clawbot` |
+| Config keys and defaults | unchanged — the same schema validates your existing row |
+| Bound account | **kept** — read from `<DSH_HOME>/clawbot/accounts.json` |
+| `get_updates_buf` cursor | **kept** — read from `accounts/<id>.sync.json` |
+| Bound WeChat user | **kept** — `accounts/<id>.json` → `userId` |
+| Durable log | same file, same line format (`<stateDir>/channel.log`) |
+| CLI binary | unchanged — `dsh-wechat-ilink` |
+
+**No re-scan and no config edit are required.**
+
+### Added
+
+- **Single-instance guard.** Two pollers on one bot steal messages from each
+  other, silently. A lock file (`<stateDir>/bridge.lock`) records the holder's
+  pid; a fresh instance refuses to poll while that pid is alive, and takes over
+  when it is genuinely gone. `0.6.x` had no such guard, so a bridge left over
+  from a previous run (for example an orphaned child after a supervisor stop)
+  could keep polling alongside a new instance.
+
+- **Durable log is now written directly by the channel**, independently of DSH's
+  own logging, so a failure is diagnosable after the fact even when the plugin
+  runs headless.
+
+- **Session-expiry re-login.** `errcode -14` now starts a QR re-bind instead of
+  only being logged.
+
+### Changed
+
+- **The conversation is driven through a `dsh --profile headless --json`
+  child process** instead of an in-process `agents.create()` handle. One process
+  per message, in exchange for not depending on the in-process agent path at all.
+  Consequence: this plugin no longer declares `inject`, so it cannot be blocked
+  from activating by a missing service.
+
+- **QR codes are rendered by this package** (`lib/qr.js`, byte mode, versions
+  1–10, ECC L/M, own PNG encoder). The `qrcode-terminal` runtime dependency is
+  gone; `login` renders in the terminal *and* writes `login-qr.png`.
+
+- **The channel no longer carries credentials in the profile config.** They live
+  only in `<DSH_HOME>/clawbot/`, as before. A config-supplied `token` is no
+  longer read.
+
+### Not carried over from 0.6.5 — read this before upgrading
+
+These config keys are still **accepted and validated** (so a 0.6.x row keeps
+loading), but they currently have no effect, and the channel says so in the log
+at startup:
+
+- `typing` / `typingKeepaliveMs` — the "typing…" indicator is not implemented.
+- `acceptImages` — inbound images are not handed to the model; image messages are
+  ignored (a log line is written).
+
+Also not yet reimplemented:
+
+- TypeScript declarations (`.d.ts`) — the package is plain ESM JavaScript.
+- `selfTestOnStart` runs a single synthetic turn through the same headless path,
+  which is a weaker check than the 0.6.x in-process self-test.
+
+`allowedUserIds` keeps its 0.6.x meaning: when empty, only the account that
+scanned the QR code may drive the agent.

package/README.md

@@ -1,3 +1,149 @@
-# Temporary Holding Version
+# dsh-wechat-ilink
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+WeChat ClawBot (Tencent iLink) channel for **DeepSeek Harness** 0.2.0-rc.2 —
+talk to DSH from your WeChat chat window.
+
+```
+WeChat ──→ iLink gateway ──→ outbound long poll ──→ DSH session ──→ reply ──→ WeChat
+                              (no public IP, no domain, no port forwarding)
+```
+
+## Install
+
+```powershell
+dsh plugin --profile <profile> add dsh-wechat-ilink
+```
+
+The bundle inserts one row (`wechat-clawbot`) and its patch carries the default
+config. Nothing else is required: on first start, with no account bound, the
+channel requests a login QR code and prints it — scan it with WeChat and confirm
+on the phone. The credential is stored under `<DSH_HOME>/clawbot/` and reused on
+every later start.
+
+### Upgrading from 0.6.x
+
+Nothing to do. The runtime identities are unchanged, so an in-place upgrade keeps
+your config, your bound account, and your message cursor. See
+[CHANGELOG.md](CHANGELOG.md) for the one list that matters: which config keys are
+currently accepted-but-inert (`typing`, `acceptImages`).
+
+## CLI
+
+```powershell
+dsh-wechat-ilink login     # scan a QR code to bind a WeChat account
+dsh-wechat-ilink status    # binding state and cursor
+dsh-wechat-ilink logs [n]  # durable log tail
+dsh-wechat-ilink logout    # unbind all accounts
+```
+
+Runs standalone — no DSH runtime needed. Equivalent long form:
+`node lib/cli.js status`.
+
+## Configuration
+
+```yaml
+- id: wechat-clawbot
+  name: 'dsh-wechat-ilink'
+  config:
+    enabled: true
+    sessionId: 'wechat-clawbot'
+    cwd: 'C:\path\to\your\workspace'
+    allowedUserIds: []
+    typing: true
+    typingKeepaliveMs: 5000
+    maxMessageChars: 2000
+    acceptImages: true
+    progressNotice: true
+    turnTimeoutMs: 300000
+    selfTestOnStart: false
+    selfTestDelayMs: 3000
+    logLevel: info
+```
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Master switch. `false` loads the bundle without connecting. |
+| `sessionId` | `wechat-clawbot` | The DSH session the conversation is bound to; reused across restarts. |
+| `cwd` | workspace default | Working directory for the bound session. |
+| `provider` / `model` / `reasoningEffort` | DSH default | Accepted; currently the headless profile decides the route. |
+| `allowedUserIds` | `[]` | Extra WeChat ids allowed to drive the agent. **Empty means only the account that scanned the QR may talk to the bot.** |
+| `typing` / `typingKeepaliveMs` | `true` / `5000` | Accepted but **not implemented in 0.7.0**. |
+| `maxMessageChars` | `2000` | Outbound chunk size in characters. |
+| `acceptImages` | `true` | Accepted but **not implemented in 0.7.0**; image messages are ignored. |
+| `progressNotice` | `true` | Send a short "received, working on it" notice while a turn runs. |
+| `turnTimeoutMs` | `300000` | Abort a turn that runs longer than this. |
+| `selfTestOnStart` | `false` | Run one synthetic turn at startup and log the outcome. |
+| `logLevel` | `info` | `silent` \| `error` \| `info` \| `debug`. `debug` logs inbound text. |
+
+Extensions beyond the 0.6.x schema: `baseUrl`, `stateDir`, `outgoingMaxPerSec`,
+`outgoingBurst`, `disableBridge`.
+
+## Where state lives
+
+```
+<DSH_HOME>/clawbot/
+  accounts.json                    index of bound account ids
+  accounts/<accountId>.json        token, baseUrl, bound userId
+  accounts/<accountId>.sync.json   get_updates_buf cursor
+  channel.log                      durable log
+  bridge.lock                      single-instance guard
+  login-qr.png                     last rendered login QR (transient)
+```
+
+`DSH_HOME` defaults to `%USERPROFILE%\.dsh`.
+
+## Design notes
+
+### Single-instance guard
+
+**Two pollers on one bot steal messages from each other, silently.** The channel
+takes a lock at `<stateDir>/bridge.lock` recording the holder's pid:
+
+- holder **alive** → this instance refuses to poll and logs the holder's pid;
+- holder **gone** → stale lock, this instance takes over.
+
+The failure this prevents is real: a bridge is typically a supervisor chain
+(`scheduled task → .cmd → node`), and stopping the supervisor kills the outer
+layers while the `node` grandchild survives as an orphan and keeps polling. A
+fresh start then runs alongside it.
+
+Shutdown removes only its own lock, so a successor's lock is never deleted.
+
+### Conversation driving
+
+Each message runs `dsh --profile headless --json --session-id <id> "<prompt>"`
+and parses the NDJSON it emits (`session` / `final` / `status.turn_end`).
+`--session-id` gives the thread continuity.
+
+One process per message, in exchange for not touching the in-process agent path
+at all — which also means this plugin declares no `inject` and cannot be blocked
+from activating by a missing service.
+
+### QR rendering
+
+The gateway returns only a **login URL**, never an image:
+
+```
+https://liteapp.weixin.qq.com/q/xxxx?qrcode=<32 hex>&bot_type=3
+```
+
+`lib/qr.js` renders it in-package: byte mode, versions 1–10, ECC L/M, its own PNG
+encoder (1-bit greyscale, `zlib`), and a half-block terminal renderer. No runtime
+dependency on a QR library, and no third-party service ever receives the login
+credential.
+
+**Rendering failure never blocks login** — the raw URL is always printed.
+
+## Known limits
+
+- The gateway throttles sends: roughly 5–6 messages in a burst earns `ret=-2` for
+  about an hour, and **retrying during the penalty makes it worse**. The channel
+  paces outbound sends (`outgoingMaxPerSec`, default 0.5/s) and chunks long
+  replies to stay under it. Re-scanning resets the penalty but changes the bot
+  identity.
+- Config is read at startup: restart the bridge after editing the profile patch.
+- `typing` and `acceptImages` are accepted but inert in 0.7.0.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,51 @@
+# dsh-wechat-ilink bundle layer for DeepSeek Harness 0.2.0-rc.2.
+#
+# A profile composes its entry list from: each bundle patch in
+# `dsh.profile.bundles` order over an EMPTY root, then the profile's own
+# cordis.patch.yml, then $DSH_HOME/cordis.patch.yml, then --patch overlays.
+#
+# `insert` WITHOUT an `id` appends rows to the root entry list.
+# `name` is a module specifier resolved from the profile dir. This file is
+# consumed from inside the package, so the bare package name resolves via the
+# profile's node_modules.
+#
+# Row id and every config key below are the 0.6.x contract, kept verbatim so an
+# existing profile keeps working across the upgrade without edits.
+- insert:
+    - id: wechat-clawbot
+      name: '@peng272/dsh-wechat-ilink'
+      config:
+        # Master switch. Set false to load the bundle without connecting.
+        enabled: true
+        # The DSH session this WeChat conversation is bound to. Reused across
+        # restarts so the thread keeps its context.
+        sessionId: 'wechat-clawbot'
+        # Working directory for the bound session. Leave empty to inherit the
+        # workspace default (which is what you normally want).
+        # cwd: 'C:\\path\\to\\your\\workspace'
+        # Pin the model for WeChat turns. Leave empty to follow DSH's default.
+        # provider: deepseek-account
+        # model: deepseek-flash
+        # reasoningEffort: off
+        # Extra WeChat user ids allowed to drive the agent. When empty, only the
+        # account that scanned the QR code may talk to the bot.
+        allowedUserIds: []
+        # Show "typing…" in WeChat while a turn runs.
+        typing: true
+        typingKeepaliveMs: 5000
+        # Outbound message chunk size (characters).
+        maxMessageChars: 2000
+        # Hand inbound images to the model as image blocks.
+        acceptImages: true
+        # Send a short "received, working on it" notice while a turn runs.
+        progressNotice: true
+        # Abort a turn that runs longer than this.
+        turnTimeoutMs: 300000
+        # Startup self-test: run ONE synthetic turn through the DSH agent path
+        # and log the outcome, so the bridge is verified without needing an
+        # inbound WeChat message.
+        selfTestOnStart: true
+        selfTestDelayMs: 3000
+        # 'silent' | 'error' | 'info' | 'debug'
+        # 'debug' is worth using while diagnosing: it logs the inbound text.
+        logLevel: info

package/lib/accounts.js

@@ -0,0 +1,145 @@
+/**
+ * Credential and cursor persistence for the WeChat ClawBot channel.
+ *
+ * State lives under `<DSH_HOME>/clawbot/`:
+ *   accounts.json                    — index of bound account ids
+ *   accounts/<accountId>.json        — bot token, base url, bound user id
+ *   accounts/<accountId>.sync.json   — opaque `get_updates_buf` cursor
+ *
+ * Credentials are written with mode 0600 where the platform supports it.
+ *
+ * NOTE: this layout is a STABLE RUNTIME IDENTITY. It is deliberately byte- and
+ * path-compatible with the 0.6.x series so an upgrade keeps the bound account,
+ * the cursor, and the user's conversation. Do not rename or relocate it.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+/** Resolve the channel state directory (respects `DSH_HOME`). */
+export function resolveStateDir(env = process.env) {
+  const home = env.DSH_HOME?.trim() || path.join(env.USERPROFILE ?? env.HOME ?? '.', '.dsh')
+  return path.join(home, 'clawbot')
+}
+
+export class AccountStore {
+  #dir
+  #accountsDir
+
+  constructor(stateDir) {
+    this.#dir = stateDir ?? resolveStateDir()
+    this.#accountsDir = path.join(this.#dir, 'accounts')
+  }
+
+  get dir() {
+    return this.#dir
+  }
+
+  #indexPath() {
+    return path.join(this.#dir, 'accounts.json')
+  }
+
+  #accountPath(accountId) {
+    return path.join(this.#accountsDir, `${accountId}.json`)
+  }
+
+  #syncPath(accountId) {
+    return path.join(this.#accountsDir, `${accountId}.sync.json`)
+  }
+
+  /** All bound account ids, oldest first. */
+  listAccountIds() {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(this.#indexPath(), 'utf-8'))
+      if (!Array.isArray(parsed)) return []
+      return parsed.filter((id) => typeof id === 'string' && id.trim() !== '')
+    } catch {
+      return []
+    }
+  }
+
+  registerAccountId(accountId) {
+    fs.mkdirSync(this.#dir, { recursive: true })
+    const existing = this.listAccountIds()
+    if (existing.includes(accountId)) return
+    fs.writeFileSync(this.#indexPath(), JSON.stringify([...existing, accountId], null, 2), 'utf-8')
+  }
+
+  unregisterAccountId(accountId) {
+    const existing = this.listAccountIds()
+    const updated = existing.filter((id) => id !== accountId)
+    if (updated.length !== existing.length) {
+      fs.mkdirSync(this.#dir, { recursive: true })
+      fs.writeFileSync(this.#indexPath(), JSON.stringify(updated, null, 2), 'utf-8')
+    }
+  }
+
+  load(accountId) {
+    try {
+      return JSON.parse(fs.readFileSync(this.#accountPath(accountId), 'utf-8'))
+    } catch {
+      return null
+    }
+  }
+
+  /** Persist credentials, merging into any existing record. */
+  save(accountId, update) {
+    fs.mkdirSync(this.#accountsDir, { recursive: true })
+    const existing = this.load(accountId) ?? {}
+    const token = update.token?.trim() || existing.token
+    const baseUrl = update.baseUrl?.trim() || existing.baseUrl
+    const userId =
+      update.userId !== undefined ? update.userId.trim() || undefined : existing.userId?.trim() || undefined
+    const data = {
+      ...(token ? { token, savedAt: new Date().toISOString() } : {}),
+      ...(baseUrl ? { baseUrl } : {}),
+      ...(userId ? { userId } : {}),
+    }
+    const file = this.#accountPath(accountId)
+    fs.writeFileSync(file, JSON.stringify(data, null, 2), 'utf-8')
+    try {
+      fs.chmodSync(file, 0o600)
+    } catch {
+      // Best effort; Windows ACLs do not map onto POSIX modes.
+    }
+  }
+
+  /** Remove credentials and cursors for one account. */
+  clear(accountId) {
+    for (const file of [this.#accountPath(accountId), this.#syncPath(accountId)]) {
+      try {
+        fs.unlinkSync(file)
+      } catch {
+        // Already gone.
+      }
+    }
+    this.unregisterAccountId(accountId)
+  }
+
+  loadSyncBuf(accountId) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(this.#syncPath(accountId), 'utf-8'))
+      return typeof parsed.get_updates_buf === 'string' ? parsed.get_updates_buf : ''
+    } catch {
+      return ''
+    }
+  }
+
+  saveSyncBuf(accountId, getUpdatesBuf) {
+    fs.mkdirSync(this.#accountsDir, { recursive: true })
+    const file = this.#syncPath(accountId)
+    fs.writeFileSync(file, JSON.stringify({ get_updates_buf: getUpdatesBuf }, null, 2), 'utf-8')
+    try {
+      fs.chmodSync(file, 0o600)
+    } catch {
+      // Best effort.
+    }
+  }
+
+  clearSyncBuf(accountId) {
+    try {
+      fs.unlinkSync(this.#syncPath(accountId))
+    } catch {
+      // Already gone.
+    }
+  }
+}

package/lib/cli.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * `dsh-wechat-ilink` CLI — QR binding and diagnostics.
+ *
+ *   dsh-wechat-ilink login     scan a QR code to bind a WeChat account
+ *   dsh-wechat-ilink status    show binding state and cursor
+ *   dsh-wechat-ilink logs [n]  print the channel's durable log tail
+ *   dsh-wechat-ilink logout    unbind all accounts
+ *
+ * Equivalent long form, if you prefer not to rely on the bin shim:
+ *
+ *   node lib/cli.js login
+ *
+ * Runs standalone (no DSH runtime needed): it only touches the iLink protocol
+ * layer and the on-disk credential store.
+ */
+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 { redactToken, readLogTail } from './support.js'
+
+const CHANNEL_VERSION = '2.4.9'
+
+function makeRuntime() {
+  const store = new AccountStore(resolveStateDir())
+  const client = new ILinkClient({
+    baseUrl: DEFAULT_BASE_URL,
+    channelVersion: CHANNEL_VERSION,
+    botAgent: 'DSH-ClawBot/0.1.0',
+    appId: 'bot',
+  })
+  return { store, client, login: new QrLoginManager({ store, client }) }
+}
+
+function out(line = '') {
+  process.stdout.write(`${line}\n`)
+}
+
+async function cmdLogin() {
+  const { store, login } = makeRuntime()
+  out('正在向微信申请登录二维码…')
+  const ticket = await login.start()
+
+  out('\n请用手机微信扫描下面的二维码（微信 → 扫一扫）：\n')
+  try {
+    const { art } = renderQrPng(ticket.url)
+    out(art)
+  } catch (error) {
+    out(`（二维码渲染失败：${error?.message ?? error}）`)
+  }
+  out(`\n二维码链接：${ticket.url}`)
+  out('\n等待扫码确认…（Ctrl+C 取消）')
+
+  for (;;) {
+    const outcome = await login.poll({ ticketId: ticket.id })
+    switch (outcome.status) {
+      case 'confirmed': {
+        out('\n✅ 绑定成功！')
+        out(`   账号   ${outcome.accountId}`)
+        out(`   凭据   ${store.dir}`)
+        out('\n重启 DSH（或在 DSH 里重新加载插件）后即可在微信里发消息。')
+        return 0
+      }
+      case 'scaned':
+        out('   已扫码，请在手机上点击确认…')
+        break
+      case 'expired':
+        out('\n❌ 二维码已过期，请重新运行 login。')
+        return 1
+      default:
+        break
+    }
+    await new Promise((r) => setTimeout(r, 2000))
+  }
+}
+
+async function cmdStatus() {
+  const { store } = makeRuntime()
+  const ids = store.listAccountIds()
+  out(`状态目录  ${store.dir}`)
+  if (ids.length === 0) {
+    out('绑定账号  （无）')
+    out('\n还没有绑定微信账号。运行：dsh-wechat-ilink login')
+    return 0
+  }
+  out(`绑定账号  ${ids.length} 个`)
+  for (const id of ids) {
+    const record = store.load(id)
+    const cursor = store.loadSyncBuf(id)
+    out('')
+    out(`  accountId   ${id}`)
+    out(`  token       ${redactToken(record?.token)}`)
+    out(`  baseUrl     ${record?.baseUrl ?? '(默认)'}`)
+    out(`  userId      ${record?.userId ?? '(未知，等对方先发一条消息)'}`)
+    out(`  savedAt     ${record?.savedAt ?? '(未知)'}`)
+    out(`  cursor      ${cursor ? `${cursor.length} 字符` : '（空）'}`)
+  }
+  return 0
+}
+
+function cmdLogs(args) {
+  const n = Number(args[0])
+  const lines = Number.isFinite(n) && n > 0 ? n : 40
+  const file = path.join(resolveStateDir(), 'channel.log')
+  if (!fs.existsSync(file)) {
+    out(`没有日志文件：${file}`)
+    out('（插件还没运行过，或用了自定义 stateDir）')
+    return 0
+  }
+  out(`--- ${file} （末 ${lines} 行） ---`)
+  for (const line of readLogTail(file, lines)) out(line)
+  return 0
+}
+
+function cmdLogout() {
+  const { store } = makeRuntime()
+  const ids = store.listAccountIds()
+  if (ids.length === 0) {
+    out('没有已绑定的账号。')
+    return 0
+  }
+  for (const id of ids) {
+    store.clear(id)
+    out(`已解除绑定：${id}`)
+  }
+  out('\n凭据与游标已删除。下次启动 DSH 时会重新要求扫码。')
+  return 0
+}
+
+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    解除全部绑定')
+  return 0
+}
+
+const [command, ...rest] = process.argv.slice(2)
+let code
+try {
+  switch (command) {
+    case 'login':
+      code = await cmdLogin()
+      break
+    case 'status':
+      code = await cmdStatus()
+      break
+    case 'logs':
+      code = cmdLogs(rest)
+      break
+    case 'logout':
+      code = cmdLogout()
+      break
+    default:
+      code = usage()
+  }
+} catch (error) {
+  process.stderr.write(`dsh-wechat-ilink: ${error?.message ?? error}\n`)
+  code = 1
+}
+process.exit(code)