@blod-nm/1kuan-act-01-cli 0.1.4 → 0.2.0

package/README.md

@@ -22,7 +22,7 @@ act-01 config test
 
 Stored at `~/.config/act-01/config.json` (0600, atomic write). `apiKey` can also come from the `ACT01_API_KEY` environment variable. Never pass it as a CLI argument.
 
-No local config? Generate a transfer string with the bundled [config helper](./config-helper.html) (runs locally in the browser), then:
+No local config? Ask the team for a `config-helper.html` (a single local HTML page) to generate a transfer string, then:
 
 ```bash
 act-01 config import "act01w.v1.xxxx"   # prompts for the passphrase used at generation
@@ -52,6 +52,11 @@ act-01 redpacket create --mode random --total 10000 --count 50 --per-user 2 --mi
 - Interactive confirm card lists every parameter before the atomic database function call
 - `create` is non-interactive only with `--yes` (otherwise it asks for confirmation)
 - `--dry-run` prints the function call without executing; `--json` for machine output
+- After a successful create the CLI renders a scannable QR on **stderr** (`--qr ansi|off`, default `ansi`);
+  `--qr-out <file.svg>` writes it to a file. The encoded content is
+  `mp://pages/act-01/open/index?packet_no=<no>`, so scanning it inside the wx mini program
+  (我的 → 常用 → 扫码支付) opens the claim page directly — no domain or WeChat link rule needed
+- `--json` includes `packetNo` and `qr: { content, format, path }`
 
 ## MCP (AI client integration)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blod-nm/1kuan-act-01-cli",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "type": "module",
   "description": "Internal operations CLI: invoke preset database functions via a gateway. Zero dependencies, MCP (stdio) support.",
   "license": "MIT",
@@ -14,7 +14,6 @@
   "files": [
     "bin",
     "src",
-    "config-helper.html",
     "README.md"
   ],
   "scripts": {
@@ -26,7 +25,7 @@
     "build:all": "bun run build:js && bun run build:bin:all"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=18.3"
   },
   "keywords": [
     "cli",

package/src/main.js

@@ -8,7 +8,8 @@ import { VERSION } from './version.js'
 import { join } from 'node:path'
 import { configPath, expandPath, loadConfig, saveConfig, decodeConfigString, encryptConfig } from './store.js'
 import { ACCOUNT_SQL, execPgsql, resolveApikey, gatewayBase } from './tcb.js'
-import { buildCreateSql, confirmSummary, normalizeCreateRedpacket } from './redpacket.js'
+import { buildCreateSql, claimTarget, confirmSummary, normalizeCreateRedpacket } from './redpacket.js'
+import { encode, renderAnsi, renderSvg } from './qr.js'
 import { SKILL_MD, SKILL_NAME } from './skill.js'
 import { startMcp } from './mcp.js'
 
@@ -39,6 +40,8 @@ const USAGE = `act-01 —— operations CLI(invoke preset database functions)
       --require-group               群专属
       --dry-run                     只打印库函数调用,不执行
       --yes                         跳过确认
+      --qr ansi|svg|off             创建成功后输出二维码(ansi 打到 stderr;svg 需配 --qr-out)
+      --qr-out <文件>               二维码写入文件(.svg 矢量 / 其它字符画)
 
 apiKey 等同数据库管理员:支持 ACT01_API_KEY 环境变量,永远不要放在命令行参数里。
 
@@ -67,6 +70,16 @@ async function readStdinText() {
   return Buffer.concat(chunks).toString('utf8').trim()
 }
 
+/** 网关可能把 jsonb 当字符串回,统一解析一次 */
+function parseJsonResult(value) {
+  if (typeof value !== 'string') return value
+  try {
+    return JSON.parse(value)
+  } catch {
+    return value
+  }
+}
+
 function printJson(value) {
   console.log(JSON.stringify(value, null, process.stdout.isTTY ? 2 : undefined))
 }
@@ -265,12 +278,31 @@ const CREATE_FLAGS = {
   'share-cover': { type: 'string' },
   note: { type: 'string' },
   'require-group': { type: 'boolean' },
+  qr: { type: 'string' },
+  'qr-out': { type: 'string' },
 }
 
 function parseCreateValues(argv) {
   return parseArgs({ strict: false, allowPositionals: true, args: argv, options: CREATE_FLAGS }).values
 }
 
+/** --qr / --qr-out 的组合校验放在任何副作用之前 */
+function resolveQrOptions(values) {
+  const mode = str(values, 'qr') ?? 'ansi'
+  const out = str(values, 'qr-out')
+  if (mode !== 'ansi' && mode !== 'svg' && mode !== 'off') {
+    const err = new Error('--qr 只支持 ansi / svg / off')
+    err.exitCode = 2
+    throw err
+  }
+  if (mode === 'svg' && !out) {
+    const err = new Error('--qr svg 需要配 --qr-out <文件>')
+    err.exitCode = 2
+    throw err
+  }
+  return { mode, out }
+}
+
 function findMissing(values) {
   const missing = []
   if (!str(values, 'mode')) missing.push('--mode random|equal')
@@ -459,6 +491,7 @@ async function cmdCheck(argv) {
 
 async function cmdCreate(argv) {
   const values = parseCreateValues(argv)
+  const qrOptions = resolveQrOptions(values)
   const interactive = process.stdin.isTTY === true
 
   // 向导补齐仅限"真命令行直跑"(bin 入口打 ACT01_CLI_INVOKED 标记);
@@ -546,19 +579,62 @@ async function cmdCreate(argv) {
     return 1
   }
 
-  const result = r.rows?.[0]?.result
+  const result = parseJsonResult(r.rows?.[0]?.result)
+  const packet = result && typeof result === 'object' && result.packet && typeof result.packet === 'object'
+    ? (result.packet.data && typeof result.packet.data === 'object' ? result.packet.data : result.packet)
+    : null
+  const packetNo = String(packet?.packet_no || '').trim()
+  const balanceAfter = balance - input.totalPoints
+
+  // 二维码:内容走小程序 goto 协议,扫到直接进领红包页(不依赖域名/微信后台规则)
+  const qrMode = qrOptions.mode
+  const qrOut = qrOptions.out
+  const qrContent = packetNo ? claimTarget(packetNo) : ''
+  let qr = null
+  let qrPath = null
+  if (qrContent) {
+    try {
+      qr = encode(qrContent)
+    } catch (error) {
+      console.error(`warn: 二维码生成失败 (${error.message});红包已创建`)
+    }
+  }
+  if (qr && qrOut) {
+    const target = expandPath(qrOut)
+    const text = /\.svg$/i.test(target) ? renderSvg(qr) : renderAnsi(qr, { color: false })
+    try {
+      writeFileSync(target, `${text}\n`)
+      qrPath = target
+    } catch (error) {
+      console.error(`warn: 二维码写入失败 (${error.message});红包已创建`)
+    }
+  }
+
   if (values.json === true) {
-    printJson({ ok: true, result, balanceBefore: balance, balanceAfter: balance - input.totalPoints })
+    printJson({
+      ok: true,
+      packetNo: packetNo || null,
+      result,
+      balanceBefore: balance,
+      balanceAfter,
+      qr: qrContent ? { content: qrContent, format: qrMode, path: qrPath } : null,
+    })
   } else {
-    printTable(
-      ['RESULT', '余额变化'],
-      [[
-        typeof result === 'string' ? result : JSON.stringify(result),
-        `${balance} → ${balance - input.totalPoints}`,
-      ]],
-    )
-    console.error('hint: deducted; recall is not supported — lifecycle is TTL-driven')
+    console.log(`红包编号     ${packetNo || '(未返回)'}`)
+    if (packet) {
+      const modeText = packet.mode === 'equal' ? '均分' : '随机'
+      console.log(`红包         ${modeText} · ${packet.total_points} 积分 / ${packet.count} 份 · ${packet.status || 'active'}`)
+    }
+    console.log(`余额变化     ${balance} → ${balanceAfter}`)
+    if (qrContent) console.log(`二维码内容   ${qrContent}`)
+    if (!packetNo) console.log(`结果         ${typeof result === 'string' ? result : JSON.stringify(result)}`)
+  }
+
+  if (qr && qrMode === 'ansi' && !qrPath) {
+    process.stderr.write(`${renderAnsi(qr, { color: process.env.NO_COLOR === undefined })}\n`)
   }
+  if (qrPath) console.error(`二维码已写入: ${qrPath}`)
+  console.error('hint: deducted; recall is not supported — lifecycle is TTL-driven')
   return 0
 }
 

package/src/mcp.js

@@ -14,7 +14,7 @@
 import { VERSION } from './version.js'
 import { loadConfig } from './store.js'
 import { resolveApikey, execPgsql, gatewayBase } from './tcb.js'
-import { normalizeCreateRedpacket, buildCreateSql } from './redpacket.js'
+import { normalizeCreateRedpacket, buildCreateSql, claimTarget } from './redpacket.js'
 
 const SERVER_INFO = { name: 'act-01', version: VERSION }
 const SUPPORTED = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05', '2024-10-07']
@@ -80,6 +80,22 @@ function needConfig() {
   return { config, apikey }
 }
 
+/** jsonb 可能被网关当字符串回;顺手带回小程序扫码入口(mp://) */
+function withClaimTarget(raw) {
+  let result = raw
+  if (typeof raw === 'string') {
+    try {
+      result = JSON.parse(raw)
+    } catch {
+      result = raw
+    }
+  }
+  if (!result || typeof result !== 'object') return result
+
+  const packetNo = String(result.packet?.data?.packet_no || result.packet?.packet_no || '').trim()
+  return packetNo ? { ...result, qr: { content: claimTarget(packetNo) } } : result
+}
+
 async function callTool(name, args) {
   if (name === 'redpacket_create' || name === 'redpacket_check') {
     const checkOnly = name === 'redpacket_check'
@@ -100,7 +116,7 @@ async function callTool(name, args) {
       err.gateway = true
       throw err
     }
-    return r.rows?.[0]?.result ?? r.raw
+    return withClaimTarget(r.rows?.[0]?.result ?? r.raw)
   }
 
   if (name === 'balance') {

package/src/qr.js

@@ -0,0 +1,449 @@
+/**
+  qr.js — 二维码编码与渲染(能力型,零依赖)
+
+  取用:
+    import { encode, renderAnsi, renderSvg } from './qr.js'
+    const qr = encode('mp://pages/act-01/open/index?packet_no=2000000001')
+    process.stderr.write(renderAnsi(qr) + '\n')
+
+  口径:
+    byte 模式 / 纠错 M / version 1..10 自适应 / 8 种 mask 按标准罚分选最优
+    只覆盖本 CLI 需要的长度(≤213 字节);超出直接抛错,不静默截断
+    ANSI 用 ▀ 半块 + 真彩(白底黑块);color=false 时退成 ██/空格(可写文件)
+*/
+
+const EC_M = 0 // 纠错等级 M 的 format 位
+const BLOCKS = {
+  1: [1, 26, 16],
+  2: [1, 44, 28],
+  3: [1, 70, 44],
+  4: [2, 50, 32],
+  5: [2, 67, 43],
+  6: [4, 43, 27],
+  7: [4, 49, 31],
+  8: [2, 60, 38, 2, 61, 39],
+  9: [3, 58, 36, 2, 59, 37],
+  10: [4, 69, 43, 1, 70, 44],
+}
+const ALIGN = {
+  1: [], 2: [6, 18], 3: [6, 22], 4: [6, 26], 5: [6, 30],
+  6: [6, 34], 7: [6, 22, 38], 8: [6, 24, 42], 9: [6, 26, 46], 10: [6, 28, 50],
+}
+const MAX_VERSION = 10
+
+/* ---------- GF(256) + Reed-Solomon ---------- */
+
+const EXP = new Uint8Array(512)
+const LOG = new Uint8Array(256)
+{
+  let x = 1
+  for (let i = 0; i < 255; i += 1) {
+    EXP[i] = x
+    LOG[x] = i
+    x <<= 1
+    if (x & 0x100) x ^= 0x11d
+  }
+  for (let i = 255; i < 512; i += 1) EXP[i] = EXP[i - 255]
+}
+
+const mul = (a, b) => (a === 0 || b === 0 ? 0 : EXP[LOG[a] + LOG[b]])
+
+const generatorCache = new Map()
+const generator = (degree) => {
+  if (generatorCache.has(degree)) return generatorCache.get(degree)
+  let poly = [1]
+  for (let i = 0; i < degree; i += 1) {
+    const next = new Array(poly.length + 1).fill(0)
+    for (let j = 0; j < poly.length; j += 1) {
+      next[j] ^= poly[j]
+      next[j + 1] ^= mul(poly[j], EXP[i])
+    }
+    poly = next
+  }
+  generatorCache.set(degree, poly)
+  return poly
+}
+
+const remainder = (data, gen) => {
+  const ecc = new Uint8Array(gen.length - 1)
+  for (const byte of data) {
+    const factor = byte ^ ecc[0]
+    ecc.copyWithin(0, 1)
+    ecc[ecc.length - 1] = 0
+    for (let i = 0; i < ecc.length; i += 1) ecc[i] ^= mul(gen[i + 1], factor)
+  }
+  return ecc
+}
+
+/* ---------- 数据编码 ---------- */
+
+const countBits = (version) => (version <= 9 ? 8 : 16)
+const dataCodewords = (version) => {
+  const g = BLOCKS[version]
+  let total = 0
+  for (let i = 0; i < g.length; i += 3) total += g[i] * g[i + 2]
+  return total
+}
+const maxBytes = (version) => Math.floor((dataCodewords(version) * 8 - 4 - countBits(version)) / 8)
+
+const pickVersion = (length) => {
+  for (let v = 1; v <= MAX_VERSION; v += 1) if (maxBytes(v) >= length) return v
+  return 0
+}
+
+const buildDataBytes = (bytes, version) => {
+  const bits = []
+  const push = (value, len) => {
+    for (let i = len - 1; i >= 0; i -= 1) bits.push((value >>> i) & 1)
+  }
+  push(0b0100, 4)
+  push(bytes.length, countBits(version))
+  for (const byte of bytes) push(byte, 8)
+
+  const capacity = dataCodewords(version) * 8
+  push(0, Math.min(4, capacity - bits.length))
+  while (bits.length % 8 !== 0) bits.push(0)
+
+  const out = []
+  for (let i = 0; i < bits.length; i += 8) {
+    let byte = 0
+    for (let j = 0; j < 8; j += 1) byte = (byte << 1) | bits[i + j]
+    out.push(byte)
+  }
+  for (let pad = 0xec; out.length < dataCodewords(version); pad ^= 0xec ^ 0x11) out.push(pad)
+  return Uint8Array.from(out)
+}
+
+const buildCodewords = (bytes, version) => {
+  const data = buildDataBytes(bytes, version)
+  const table = BLOCKS[version]
+  const blocks = []
+  let offset = 0
+  for (let i = 0; i < table.length; i += 3) {
+    const count = table[i]
+    const ecLen = table[i + 1] - table[i + 2]
+    const dataLen = table[i + 2]
+    const gen = generator(ecLen)
+    for (let n = 0; n < count; n += 1) {
+      const chunk = data.slice(offset, offset + dataLen)
+      offset += dataLen
+      blocks.push({ data: chunk, ec: remainder(chunk, gen) })
+    }
+  }
+
+  const out = []
+  const maxData = Math.max(...blocks.map((block) => block.data.length))
+  for (let i = 0; i < maxData; i += 1) {
+    for (const block of blocks) if (i < block.data.length) out.push(block.data[i])
+  }
+  const ecLen = blocks[0].ec.length
+  for (let i = 0; i < ecLen; i += 1) for (const block of blocks) out.push(block.ec[i])
+  return Uint8Array.from(out)
+}
+
+/* ---------- 矩阵 ---------- */
+
+const bitAt = (value, index) => ((value >>> index) & 1) === 1
+
+const formatBits = (mask) => {
+  const data = (EC_M << 3) | mask
+  let rem = data
+  for (let i = 0; i < 10; i += 1) rem = (rem << 1) ^ ((rem >>> 9) * 0x537)
+  return ((data << 10) | rem) ^ 0x5412
+}
+
+const versionBits = (version) => {
+  let rem = version
+  for (let i = 0; i < 12; i += 1) rem = (rem << 1) ^ ((rem >>> 11) * 0x1f25)
+  return (version << 12) | rem
+}
+
+const blank = (version) => {
+  const size = version * 4 + 17
+  return {
+    size,
+    modules: Array.from({ length: size }, () => new Array(size).fill(false)),
+    isFunction: Array.from({ length: size }, () => new Array(size).fill(false)),
+  }
+}
+
+const drawBase = (version) => {
+  const state = blank(version)
+  const { size, modules, isFunction } = state
+  const set = (row, col, dark) => {
+    modules[row][col] = dark
+    isFunction[row][col] = true
+  }
+
+  const finder = (row0, col0) => {
+    for (let dr = -1; dr <= 7; dr += 1) {
+      for (let dc = -1; dc <= 7; dc += 1) {
+        const row = row0 + dr
+        const col = col0 + dc
+        if (row < 0 || row >= size || col < 0 || col >= size) continue
+        const dark =
+          (dr >= 0 && dr <= 6 && (dc === 0 || dc === 6)) ||
+          (dc >= 0 && dc <= 6 && (dr === 0 || dr === 6)) ||
+          (dr >= 2 && dr <= 4 && dc >= 2 && dc <= 4)
+        set(row, col, dark)
+      }
+    }
+  }
+  finder(0, 0)
+  finder(0, size - 7)
+  finder(size - 7, 0)
+
+  for (let i = 8; i < size - 8; i += 1) {
+    const dark = i % 2 === 0
+    set(6, i, dark)
+    set(i, 6, dark)
+  }
+
+  const positions = ALIGN[version]
+  // 只跳过与三个定位图形重叠的中心(6,6)/(6,size-7)/(size-7,6);
+  // 落在 timing 行/列上的校正图形要画,并覆盖对应 timing 模块
+  const onFinder = (row, col) =>
+    (row === 6 && col === 6) ||
+    (row === 6 && col === size - 7) ||
+    (row === size - 7 && col === 6)
+  for (const row of positions) {
+    for (const col of positions) {
+      if (onFinder(row, col)) continue
+      for (let dr = -2; dr <= 2; dr += 1) {
+        for (let dc = -2; dc <= 2; dc += 1) {
+          set(row + dr, col + dc, Math.max(Math.abs(dr), Math.abs(dc)) !== 1)
+        }
+      }
+    }
+  }
+
+  set(size - 8, 8, true)
+  drawFormat(state, 0)
+  if (version >= 7) {
+    const bits = versionBits(version)
+    for (let i = 0; i < 18; i += 1) {
+      const dark = bitAt(bits, i)
+      const a = size - 11 + (i % 3)
+      const b = Math.floor(i / 3)
+      set(b, a, dark)
+      set(a, b, dark)
+    }
+  }
+  return state
+}
+
+function drawFormat(state, mask) {
+  const { size, modules, isFunction } = state
+  const set = (row, col, dark) => {
+    modules[row][col] = dark
+    isFunction[row][col] = true
+  }
+  const bits = formatBits(mask)
+  for (let i = 0; i <= 5; i += 1) set(i, 8, bitAt(bits, i))
+  set(7, 8, bitAt(bits, 6))
+  set(8, 8, bitAt(bits, 7))
+  set(8, 7, bitAt(bits, 8))
+  for (let i = 9; i < 15; i += 1) set(8, 14 - i, bitAt(bits, i))
+  for (let i = 0; i < 8; i += 1) set(8, size - 1 - i, bitAt(bits, i))
+  for (let i = 8; i < 15; i += 1) set(size - 15 + i, 8, bitAt(bits, i))
+  set(size - 8, 8, true)
+}
+
+const placeData = (state, codewords) => {
+  const { size, modules, isFunction } = state
+  const total = codewords.length * 8
+  let index = 0
+  for (let right = size - 1; right >= 1; right -= 2) {
+    if (right === 6) right = 5
+    const upward = ((right + 1) & 2) === 0
+    for (let vert = 0; vert < size; vert += 1) {
+      for (let j = 0; j < 2; j += 1) {
+        const col = right - j
+        const row = upward ? size - 1 - vert : vert
+        if (isFunction[row][col] || index >= total) continue
+        modules[row][col] = bitAt(codewords[index >>> 3], 7 - (index & 7))
+        index += 1
+      }
+    }
+  }
+}
+
+const maskHit = (mask, row, col) => {
+  switch (mask) {
+    case 0: return (row + col) % 2 === 0
+    case 1: return row % 2 === 0
+    case 2: return col % 3 === 0
+    case 3: return (row + col) % 3 === 0
+    case 4: return (Math.floor(row / 2) + Math.floor(col / 3)) % 2 === 0
+    case 5: return ((row * col) % 2) + ((row * col) % 3) === 0
+    case 6: return (((row * col) % 2) + ((row * col) % 3)) % 2 === 0
+    default: return (((row + col) % 2) + ((row * col) % 3)) % 2 === 0
+  }
+}
+
+const cloneModules = (modules) => modules.map((row) => row.slice())
+
+const applyMask = (modules, isFunction, mask) => {
+  const size = modules.length
+  for (let row = 0; row < size; row += 1) {
+    for (let col = 0; col < size; col += 1) {
+      if (!isFunction[row][col] && maskHit(mask, row, col)) modules[row][col] = !modules[row][col]
+    }
+  }
+}
+
+const PATTERNS = [
+  [1, 0, 1, 1, 1, 0, 1, 0, 0, 0, 0],
+  [0, 0, 0, 0, 1, 0, 1, 1, 1, 0, 1],
+]
+
+const penalty = (modules) => {
+  const size = modules.length
+  let score = 0
+
+  const runScore = (get) => {
+    for (let a = 0; a < size; a += 1) {
+      let color = get(a, 0)
+      let run = 1
+      for (let b = 1; b < size; b += 1) {
+        const next = get(a, b)
+        if (next === color) run += 1
+        else {
+          if (run >= 5) score += 3 + (run - 5)
+          color = next
+          run = 1
+        }
+      }
+      if (run >= 5) score += 3 + (run - 5)
+    }
+  }
+  runScore((row, col) => modules[row][col])
+  runScore((col, row) => modules[row][col])
+
+  for (let row = 0; row < size - 1; row += 1) {
+    for (let col = 0; col < size - 1; col += 1) {
+      const color = modules[row][col]
+      if (color === modules[row][col + 1] && color === modules[row + 1][col] && color === modules[row + 1][col + 1]) score += 3
+    }
+  }
+
+  for (let row = 0; row < size; row += 1) {
+    for (let col = 0; col <= size - 11; col += 1) {
+      for (const pattern of PATTERNS) {
+        let hit = true
+        for (let k = 0; k < 11; k += 1) {
+          if (modules[row][col + k] !== Boolean(pattern[k])) { hit = false; break }
+        }
+        if (hit) score += 40
+      }
+    }
+  }
+  for (let col = 0; col < size; col += 1) {
+    for (let row = 0; row <= size - 11; row += 1) {
+      for (const pattern of PATTERNS) {
+        let hit = true
+        for (let k = 0; k < 11; k += 1) {
+          if (modules[row + k][col] !== Boolean(pattern[k])) { hit = false; break }
+        }
+        if (hit) score += 40
+      }
+    }
+  }
+
+  let dark = 0
+  for (const row of modules) for (const cell of row) if (cell) dark += 1
+  const total = size * size
+  score += Math.floor(Math.abs((dark * 100) / total - 50) / 5) * 10
+  return score
+}
+
+export function encode(text, options = {}) {
+  const content = String(text ?? '')
+  if (!content) throw new Error('二维码内容为空')
+  const bytes = new TextEncoder().encode(content)
+
+  const version = Number(options.version) || pickVersion(bytes.length)
+  if (!version) throw new Error(`内容过长: ${bytes.length} 字节(上限 ${maxBytes(MAX_VERSION)})`)
+  if (!BLOCKS[version]) throw new Error(`不支持的二维码版本: ${version}`)
+  if (bytes.length > maxBytes(version))
+    throw new Error(`内容过长: ${bytes.length} 字节(上限 ${maxBytes(version)})`)
+
+  const state = drawBase(version)
+  placeData(state, buildCodewords(bytes, version))
+
+  const masks = options.mask === undefined ? [0, 1, 2, 3, 4, 5, 6, 7] : [Number(options.mask)]
+  let best = null
+  for (const mask of masks) {
+    const modules = cloneModules(state.modules)
+    applyMask(modules, state.isFunction, mask)
+    drawFormat({ size: state.size, modules, isFunction: state.isFunction }, mask)
+    const score = penalty(modules)
+    if (!best || score < best.score) best = { mask, score, modules }
+  }
+
+  return { version, size: state.size, mask: best.mask, modules: best.modules }
+}
+
+/* ---------- 渲染 ---------- */
+
+const cellAt = (modules, size, quiet, row, col) => {
+  const r = row - quiet
+  const c = col - quiet
+  return r >= 0 && r < size && c >= 0 && c < size ? modules[r][c] : false
+}
+
+export function renderAnsi(qr, options = {}) {
+  const color = options.color !== false
+  const quiet = options.quiet === undefined ? 4 : Number(options.quiet)
+  const { modules, size } = qr
+  const span = size + quiet * 2
+  const lines = []
+
+  if (!color) {
+    for (let row = 0; row < span; row += 1) {
+      let line = ''
+      for (let col = 0; col < span; col += 1) line += cellAt(modules, size, quiet, row, col) ? '██' : '  '
+      lines.push(line)
+    }
+    return lines.join('\n')
+  }
+
+  for (let row = 0; row < span; row += 2) {
+    let line = ''
+    let fg = ''
+    let bg = ''
+    for (let col = 0; col < span; col += 1) {
+      const top = cellAt(modules, size, quiet, row, col)
+      const bottom = cellAt(modules, size, quiet, row + 1, col)
+      const nextFg = top ? '0;0;0' : '255;255;255'
+      const nextBg = bottom ? '0;0;0' : '255;255;255'
+      if (nextFg !== fg || nextBg !== bg) {
+        line += `\x1b[38;2;${nextFg}m\x1b[48;2;${nextBg}m`
+        fg = nextFg
+        bg = nextBg
+      }
+      line += '▀'
+    }
+    lines.push(`${line}\x1b[0m`)
+  }
+  return lines.join('\n')
+}
+
+export function renderSvg(qr, options = {}) {
+  const quiet = options.quiet === undefined ? 4 : Number(options.quiet)
+  const scale = options.scale === undefined ? 8 : Number(options.scale)
+  const { modules, size } = qr
+  const span = size + quiet * 2
+  let path = ''
+  for (let row = 0; row < size; row += 1) {
+    for (let col = 0; col < size; col += 1) {
+      if (modules[row][col]) path += `M${col + quiet} ${row + quiet}h1v1h-1z`
+    }
+  }
+  return [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${span * scale}" height="${span * scale}" viewBox="0 0 ${span} ${span}" shape-rendering="crispEdges">`,
+    `<rect width="${span}" height="${span}" fill="#fff"/>`,
+    `<path d="${path}" fill="#000"/>`,
+    '</svg>',
+  ].join('\n')
+}

package/src/redpacket.js

@@ -107,6 +107,11 @@ export function buildCreateSql(input) {
   return sql
 }
 
+/** 红包领取入口:小程序 goto 协议,扫到后直接 navigateTo 打开页 */
+export function claimTarget(packetNo) {
+  return `mp://pages/act-01/open/index?packet_no=${encodeURIComponent(String(packetNo || '').trim())}`
+}
+
 /** 确认卡摘要(提交前逐项列出) */
 export function confirmSummary(input) {
   const lines = [

package/src/skill.js

@@ -56,11 +56,23 @@ const BODY = [
   '2. **确认卡**:执行前列出全部参数,等用户确认',
   '3. **库函数原子扣减**:并发/余额竞争由数据库兜底,不会扣穿',
   '',
+  '## 日常最快路径(一句大白话 → 一次确认 → 执行)',
+  '',
+  '1. ' + B + 'act-01 redpacket check <flags>' + B + ' 拿校验结果(零副作用)',
+  '2. 把校验结果逐项复述给用户,等确认',
+  '3. 确认后执行:' + B + 'act-01 redpacket create <flags> --yes' + B + '(非交互必须带 ' + B + '--yes' + B + ')',
+  '4. 把红包编号、余额变化和二维码一起给用户(stderr 默认打印终端二维码)',
+  '',
+  '余额为 0 属正常:create 会被预检拦下,先让用户到运营台充值。',
+  '',
+  '> 更轻的日常形态(可选):' + B + 'act-01 mcp' + B + ' 接入支持 MCP 的客户端后,参数规格在工具 schema 里,',
+  '> 不必读本文档;客户端审批弹窗即"确认卡"。',
+  '',
   '## Agent 行为规则',
   '',
   '1. **先 check 后 create**:参数没把握时,先调 redpacket_check,拿到校验报告再执行',
   '2. **create 前必须向用户确认参数**(mode/total/count/区间/群归属);确认后执行时,**非交互(非 TTY)必须带 --yes**,否则 CLI 会拒绝(MCP 客户端则弹审批)',
-  '3. **结果转述只给摘要**:packet_no、余额变化;不要猜测或编造未返回的字段',
+  '3. **结果转述只给摘要**:packet_no、余额变化、二维码内容(create 默认在 stderr 打印二维码,用 1010「我的 → 常用 → 扫码支付」扫);不要猜测或编造未返回的字段',
   '4. **失败处理**:错误信息是人话(余额不足/区间错误/整除错误),原样转告用户并给出修正建议;不要重试同参数的 create',
   '5. **金额单位**:内部整数单位,不要做 ×100 或 ÷100 的换算,除非用户明确要求',
   '',
@@ -78,10 +90,10 @@ const BODY = [
   '',
   '## 配置前置',
   '',
-  '目标机器需要云开发配置(envId + apiKey)。没有配置文件时,让用户用配套网页',
-  '(config-helper.html)生成加密配置串,然后:',
+  '目标机器需要云开发配置(envId + apiKey)。没有配置时,让用户给你一条加密配置串',
+  '(团队用生成页产出),一条命令装好:',
   '',
-  B + 'act-01 config import "配置串"' + B + '(会提示输入生成时的口令)',
+  B + 'ACT01_EXPORT_PASS="<口令>" act-01 setup --install <技能根目录> "<配置串>"' + B,
   '',
 ].join('\n')
 

package/src/version.js

@@ -3,4 +3,4 @@
  * (test/version.test.js 会断言两者一致,防止再漏升)。
  */
 
-export const VERSION = '0.1.4'
+export const VERSION = '0.2.0'

package/config-helper.html

@@ -1,220 +0,0 @@
-<!doctype html>
-<html lang="zh-CN">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>act-01 配置串生成器</title>
-<style>
-  :root { color-scheme: light dark; }
-  * { box-sizing: border-box; }
-  body {
-    margin: 0; padding: 24px;
-    font: 15px/1.65 -apple-system, 'PingFang SC', 'Microsoft YaHei', system-ui, sans-serif;
-    background: light-dark(#f6f4ef, #17151f); color: light-dark(#262233, #e8e5f0);
-    font-variant-numeric: tabular-nums; -webkit-font-smoothing: antialiased;
-  }
-  .wrap { max-width: 640px; margin: 0 auto; display: grid; gap: 20px; }
-  h1 { font-size: 20px; margin: 0 0 4px; letter-spacing: -0.01em; }
-  .sub { color: light-dark(#7a7490, #9a94b0); font-size: 13px; margin: 0; }
-  .card {
-    border: 2px solid light-dark(#413a5e, #cbc5e0); border-radius: 16px;
-    padding: 20px; background: light-dark(#fffdf8, #201d2b);
-    box-shadow: 5px 5px 0 light-dark(#413a5e, #0c0a12);
-  }
-  .card h2 { font-size: 15px; margin: 0 0 12px; }
-  label { display: block; font-size: 13px; font-weight: 600; margin: 0 0 4px; }
-  label .opt { font-weight: 400; opacity: .65; }
-  input[type=text], input[type=password] {
-    width: 100%; padding: 9px 12px; font: inherit; font-size: 14px;
-    border: 2px solid light-dark(#413a5e, #cbc5e0); border-radius: 10px;
-    background: light-dark(#fff, #262233); color: inherit; margin-bottom: 12px;
-  }
-  input:focus { outline: 2px solid light-dark(#7c5cff, #a78bfa); outline-offset: 1px; }
-  button {
-    padding: 9px 18px; font: inherit; font-size: 14px; font-weight: 600;
-    border: 2px solid light-dark(#413a5e, #cbc5e0); border-radius: 999px;
-    background: light-dark(#7c5cff, #a78bfa); color: light-dark(#fff, #1a1526);
-    box-shadow: 3px 3px 0 light-dark(#413a5e, #0c0a12); cursor: pointer;
-    transition: transform 120ms cubic-bezier(0.34,1.56,0.64,1), box-shadow 120ms;
-  }
-  button:active { transform: translate(2px,2px); box-shadow: 1px 1px 0 light-dark(#413a5e, #0c0a12); }
-  button.ghost { background: transparent; color: inherit; }
-  .out {
-    font-family: ui-monospace, 'SF Mono', Menlo, monospace; font-size: 12px;
-    word-break: break-all; padding: 10px 12px; border-radius: 10px;
-    background: light-dark(#fff, #262233);
-    border: 2px solid light-dark(#413a5e, #cbc5e0); min-height: 42px; white-space: pre-wrap;
-  }
-  .row { display: flex; gap: 10px; align-items: center; }
-  .row input { flex: 1; margin-bottom: 0; }
-  .hint { font-size: 12px; opacity: .65; margin: 6px 0 0; }
-  .err { color: light-dark(#c2334d, #ff8fa3); font-size: 13px; margin: 8px 0 0; }
-  .ok { color: light-dark(#0a7d55, #4ade80); font-size: 13px; margin: 8px 0 0; }
-  code {
-    font-family: ui-monospace, Menlo, monospace; font-size: 12px;
-    background: light-dark(#efece3, #262233); padding: 2px 6px; border-radius: 6px;
-  }
-  .toggle { display: flex; gap: 14px; font-size: 13px; margin-bottom: 12px; }
-</style>
-</head>
-<body>
-<div class="wrap">
-  <header>
-    <h1>🔑 act-01 配置串生成器</h1>
-    <p class="sub">填入云开发原始配置 → 生成加密传递串。全本地计算,无网络请求,无任何存储。</p>
-  </header>
-
-  <div class="card">
-    <h2>① 填入原始配置</h2>
-    <label>envId(环境 ID)</label>
-    <input id="envId" type="text" placeholder="cloud1-xxxxxx" autocomplete="off">
-
-    <label>apiKey(腾讯云开发 API Key,需管理员权限)</label>
-    <input id="apiKey" type="password" placeholder="act- 开头或平台管理生成" autocomplete="off">
-
-    <label>口令 <span class="opt">— 加密用,导入端必须输入同一个;不含在配置串里</span></label>
-    <div class="row">
-      <input id="pass" type="password" placeholder="自己定一个,别用弱口令" autocomplete="new-password">
-      <button class="ghost" id="genPass">随机生成</button>
-    </div>
-
-    <div class="toggle">
-      <label style="margin:0;font-weight:400"><input type="radio" name="mode" value="enc" checked> 加密串(需口令解密,推荐)</label>
-      <label style="margin:0;font-weight:400"><input type="radio" name="mode" value="plain"> 明文串(便捷,可读)</label>
-    </div>
-
-    <button id="gen">生成配置串</button>
-    <p class="err" id="err" hidden></p>
-  </div>
-
-  <div class="card" id="outCard" hidden>
-    <h2>② 配置串(复制发出去)</h2>
-    <div class="out" id="out"></div>
-    <div class="row" style="margin-top:10px">
-      <button id="copy">复制</button>
-      <span class="hint" style="align-self:center">目标机器执行:<code>act-01 config import --stdin &lt; 串文件</code>(口令会提示输入)</span>
-    </div>
-  </div>
-
-  <div class="card">
-    <h2>③ 校验(可选)</h2>
-    <label>粘贴配置串</label>
-    <input id="vStr" type="text" autocomplete="off" class="mono-out">
-    <label>口令</label>
-    <input id="vPass" type="password" autocomplete="off">
-    <button class="ghost" id="verify">解密校验</button>
-    <p class="err" id="vErr" hidden></p>
-    <p class="ok" id="vOk" hidden></p>
-  </div>
-</div>
-
-<script>
-const $ = (id) => document.getElementById(id)
-const enc = new TextEncoder()
-
-function b64url(bytes) {
-  let bin = ''
-  for (const b of bytes) bin += String.fromCharCode(b)
-  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
-}
-
-function b64urlDecode(text) {
-  const bin = atob(text.replace(/-/g, '+').replace(/_/g, '/'))
-  return Uint8Array.from(bin, (c) => c.charCodeAt(0))
-}
-
-async function deriveKey(pass, salt) {
-  const km = await crypto.subtle.importKey('raw', enc.encode(pass), 'PBKDF2', false, ['deriveKey'])
-  return crypto.subtle.deriveKey(
-    { name: 'PBKDF2', salt, iterations: 310_000, hash: 'SHA-256' },
-    km, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt'],
-  )
-}
-
-async function encryptWeb(obj, pass) {
-  const salt = crypto.getRandomValues(new Uint8Array(16))
-  const iv = crypto.getRandomValues(new Uint8Array(12))
-  const key = await deriveKey(pass, salt)
-  const ct = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, enc.encode(JSON.stringify(obj))))
-  const packed = new Uint8Array(salt.length + iv.length + ct.length)
-  packed.set(salt, 0); packed.set(iv, salt.length); packed.set(ct, salt.length + iv.length)
-  return 'act01w.v1.' + b64url(packed)
-}
-
-async function decryptWeb(str, pass) {
-  const body = str.trim()
-  const data = b64urlDecode(body.slice(body.indexOf('.') + 1))
-  if (data.length < 44) throw new Error('配置串过短或已损坏')
-  const salt = data.slice(0, 16)
-  const iv = data.slice(16, 28)
-  const rest = data.slice(28)
-  const key = await deriveKey(pass, salt)
-  const pt = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, rest.slice(0, rest.length - 16))
-  return JSON.parse(new TextDecoder().decode(pt))
-}
-
-function collect() {
-  const envId = $('envId').value.trim()
-  const apiKey = $('apiKey').value.trim()
-  const pass = $('pass').value
-  if (!envId) throw new Error('envId 未填写')
-  if (!apiKey) throw new Error('apiKey 未填写')
-  if ($('pass').value && pass.length < 8) throw new Error('口令至少 8 位')
-  return { config: { envId, apiKey }, pass }
-}
-
-function showErr(id, msg) {
-  const el = $(id); el.hidden = !msg; el.textContent = msg || ''
-}
-
-$('genPass').addEventListener('click', () => {
-  const bytes = crypto.getRandomValues(new Uint8Array(18))
-  let bin = ''; for (const b of bytes) bin += String.fromCharCode(b)
-  $('pass').value = btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
-})
-
-$('gen').addEventListener('click', async () => {
-  showErr('err', '')
-  $('outCard').hidden = true
-  try {
-    const { config, pass } = collect()
-    const mode = document.querySelector('input[name=mode]:checked').value
-    let out
-    if (mode === 'enc') {
-      if (!pass) throw new Error('加密模式需要口令')
-      out = await encryptWeb(config, pass)
-    } else {
-      out = 'act01plain.' + b64url(enc.encode(JSON.stringify(config)))
-    }
-    $('out').textContent = out
-    $('outCard').hidden = false
-  } catch (e) {
-    showErr('err', e.message)
-  }
-})
-
-$('copy').addEventListener('click', async () => {
-  await navigator.clipboard.writeText($('out').textContent)
-  $('copy').textContent = '已复制 ✓'
-  setTimeout(() => ($('copy').textContent = '复制'), 1200)
-})
-
-$('verify').addEventListener('click', async () => {
-  showErr('vErr', ''); $('vOk').hidden = true
-  try {
-    const str = $('vStr').value.trim()
-    const pass = $('vPass').value
-    let cfg
-    if (str.startsWith('act01w.v1.')) cfg = await decryptWeb(str, pass)
-    else if (str.startsWith('act01.v1.')) throw new Error('这是 CLI scrypt 格式串,请用 act-01 CLI 解')
-    else if (str.startsWith('act01plain.')) cfg = JSON.parse(atob(str.slice('act01plain.'.length).replace(/-/g,'+').replace(/_/g,'/')))
-    else throw new Error('无法识别的串格式')
-    $('vOk').hidden = false
-    $('vOk').textContent = `✓ 解密成功:envId=${cfg.envId},apiKey=${cfg.apiKey.slice(0, 6)}…(不回显全文)`
-  } catch (e) {
-    showErr('vErr', e.message)
-  }
-})
-</script>
-</body>
-</html>