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

package/README.md

@@ -30,15 +30,27 @@ act-01 config import "act01w.v1.xxxx"   # prompts for the passphrase used at gen
 
 Transfer strings are AES-256-GCM encrypted; the passphrase never travels with the string.
 
+## One-shot setup
+
+```bash
+ACT01_EXPORT_PASS="<passphrase>" act-01 setup --install ~/.claude/skills "<config-string>"
+```
+
+Installs the skill doc, imports the config, and prints the balance in one command
+(passphrase via env; config string also accepted on stdin or `ACT01_IMPORT_STRING`).
+`--install <dir>` writes `<dir>/act-01-ops/SKILL.md`.
+
 ## Operations
 
 ```bash
-act-01 create --mode random --total 10000 --count 50 --per-user 2 --min 100 --max 500
+act-01 redpacket check  --mode random --total 10000 --count 50 --per-user 2 --min 100 --max 500
+act-01 redpacket create --mode random --total 10000 --count 50 --per-user 2 --min 100 --max 500 --yes
 ```
 
 - Amounts are integer units, no conversion
 - Pre-flight balance check runs before execution; insufficient balance is rejected locally
 - 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
 
 ## MCP (AI client integration)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blod-nm/1kuan-act-01-cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "description": "Internal operations CLI: invoke preset database functions via a gateway. Zero dependencies, MCP (stdio) support.",
   "license": "MIT",

package/src/main.js

@@ -3,6 +3,8 @@
  */
 
 import { parseArgs } from 'node:util'
+import { mkdirSync, writeFileSync } from 'node:fs'
+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'
@@ -10,7 +12,6 @@ import { buildCreateSql, confirmSummary, normalizeCreateRedpacket } from './redp
 import { SKILL_MD, SKILL_NAME } from './skill.js'
 import { startMcp } from './mcp.js'
 
-const VERSION = '0.1.0'
 
 const USAGE = `act-01 —— operations CLI(invoke preset database functions)
 
@@ -22,9 +23,10 @@ const USAGE = `act-01 —— operations CLI(invoke preset database functions)
   config set apiKey              写入 API Key(值走 stdin;不放命令行)
   config test                    连接测试(SELECT 1,验证 envId/apiKey)
   config export                  导出加密配置串(口令交互输入或 ACT01_EXPORT_PASS)
-  config import <串|--stdin>      导入配置串(自动识别 加密/明文/网页格式)
+  config import <串|--stdin> [--pass <口令>]  导入配置串(加密串需口令;自动识别 三种格式)
+  setup <串|--stdin> [--install <技能根目录>]  一条命令:装技能 + 导配置 + 查余额
   mcp                            启动 MCP 服务(stdio;接入 Claude 等 AI 客户端)
-  skill                          输出 agent 技能文档(--install <dir> 写入)
+  skill                          输出 agent 技能文档(--install <技能根目录> 装成 <root>/act-01-ops/SKILL.md)
   balance                        account balance
   redpacket create               create a record(pre-flight balance check, atomic deduct)
   redpacket check                validate params(side-effect free)
@@ -150,6 +152,23 @@ async function cmdConfig(argv) {
     throw err
   }
 
+  if (sub === 'test') {
+    const config = loadConfig()
+    const apikey = resolveApikey(config, undefined)
+    if (!config.envId || !apikey) {
+      const err = new Error('配置不完整:先 config set envId 和 apiKey')
+      err.exitCode = 2
+      throw err
+    }
+    const r = await execPgsql(config, apikey, 'SELECT 1 AS ok')
+    if (!r.ok) {
+      console.error(`error: 连接测试失败 (${r.message})`)
+      return 1
+    }
+    console.log('连接测试通过(SELECT 1)')
+    return 0
+  }
+
   if (sub === 'export') {
     const config = loadConfig()
     if (!config.envId || !config.apiKey) {
@@ -183,7 +202,13 @@ async function cmdConfig(argv) {
   }
 
   if (sub === 'import') {
-    let body = positionals[1]
+    const { values: importValues, positionals: importPositionals } = parseArgs({
+      strict: false,
+      allowPositionals: true,
+      args: argv,
+      options: { pass: { type: 'string' }, json: { type: 'boolean', short: 'j' } },
+    })
+    let body = importPositionals[1]
     if (!body && !process.stdin.isTTY) body = await readStdinText()
     if (!body) {
       const err = new Error('config import 需要 <配置串>(位置参数或 stdin)')
@@ -193,10 +218,10 @@ async function cmdConfig(argv) {
     const decoded = decodeConfigString(body)
     let cfg = decoded.config
     if (decoded.encrypted) {
-      let passphrase = process.env.ACT01_EXPORT_PASS
+      let passphrase = str(importValues, 'pass') ?? process.env.ACT01_EXPORT_PASS
       if (!passphrase) {
         if (!process.stdin.isTTY) {
-          const err = new Error('加密串需要口令:脚本里用 ACT01_EXPORT_PASS 传入')
+          const err = new Error('加密串需要口令:用 --pass <口令> 或 ACT01_EXPORT_PASS 传入')
           err.exitCode = 2
           throw err
         }
@@ -311,6 +336,15 @@ function normalizeFromValues(values) {
 
 /* ---------- skill ---------- */
 
+/** 把 SKILL.md 装到 <root>/<SKILL_NAME>/SKILL.md(目录式,匹配主流 agent 技能布局) */
+function installSkill(root) {
+  const dir = join(expandPath(root), SKILL_NAME)
+  mkdirSync(dir, { recursive: true, mode: 0o755 })
+  const file = join(dir, 'SKILL.md')
+  writeFileSync(file, SKILL_MD)
+  return file
+}
+
 async function cmdSkill(argv) {
   const { values, positionals } = parseArgs({
     strict: false,
@@ -326,13 +360,9 @@ async function cmdSkill(argv) {
   }
 
   if (values.install) {
-    const { mkdirSync, writeFileSync } = await import('node:fs')
-    const dir = expandPath(values.install)
-    mkdirSync(dir, { recursive: true, mode: 0o755 })
-    const file = join(dir, 'SKILL.md')
-    writeFileSync(file, SKILL_MD)
+    const file = installSkill(values.install)
     console.log(`SKILL.md 已写入: ${file}`)
-    console.error('hint: 把该目录加入你的 agent 技能路径')
+    console.error(`hint: 已装成 <技能根目录>/${SKILL_NAME}/SKILL.md;根目录指你的 agent 扫描的那个 skills 目录`)
     return 0
   }
 
@@ -340,6 +370,72 @@ async function cmdSkill(argv) {
   return 0
 }
 
+/* ---------- setup(一条命令:装技能 + 导配置 + 查余额) ---------- */
+
+/** 解析配置串(明文/加密)、写盘;返回 { envId, apiKey } */
+function importConfig(body, passFlag) {
+  const decoded = decodeConfigString(body)
+  let cfg = decoded.config
+  if (decoded.encrypted) {
+    const pass = passFlag ?? process.env.ACT01_EXPORT_PASS
+    if (!pass) {
+      const err = new Error('加密串需要口令:用 ACT01_EXPORT_PASS 环境变量或 --pass 传入')
+      err.exitCode = 2
+      throw err
+    }
+    cfg = decoded.decode(pass)
+  }
+  if (!cfg.envId || !cfg.apiKey) {
+    const err = new Error('配置串内容不完整(缺 envId 或 apiKey)')
+    err.exitCode = 2
+    throw err
+  }
+  saveConfig({ envId: cfg.envId, apiKey: cfg.apiKey })
+  return cfg
+}
+
+async function cmdSetup(argv) {
+  const { values, positionals } = parseArgs({
+    strict: false,
+    allowPositionals: true,
+    args: argv,
+    options: { install: { type: 'string' }, pass: { type: 'string' }, json: { type: 'boolean', short: 'j' } },
+  })
+
+  let body = positionals[0] ?? process.env.ACT01_IMPORT_STRING
+  if (!body && !process.stdin.isTTY) body = await readStdinText()
+  if (!body) {
+    const err = new Error('setup 需要 <配置串>(位置参数 / stdin / ACT01_IMPORT_STRING)')
+    err.exitCode = 2
+    throw err
+  }
+
+  const cfg = importConfig(body, str(values, 'pass'))
+  const skillPath = values.install ? installSkill(values.install) : null
+
+  const account = await execPgsql(cfg, resolveApikey(cfg, undefined), ACCOUNT_SQL)
+  const wallet =
+    account.ok && account.rows?.[0]?.data?.wallet && typeof account.rows[0].data.wallet === 'object'
+      ? account.rows[0].data.wallet
+      : {}
+  const points = account.ok ? Number(wallet.points || 0) : null
+  const label = account.ok ? String(wallet.label || 'account') : null
+
+  if (values.json === true) {
+    printJson({ ok: account.ok, envId: cfg.envId, apiKeySet: true, skillPath, balance: points, account: label, error: account.ok ? null : account.message })
+  } else {
+    console.log('setup 完成:')
+    console.log(skillPath ? `  技能: SKILL.md → ${skillPath}` : '  技能: (未装;加 --install <技能根目录>)')
+    console.log(`  配置: envId ${cfg.envId},apiKey 已打码写入 0600`)
+    if (account.ok) console.log(`  余额: ${points}(${label})`)
+    else {
+      console.error(`  余额: 查询失败 (${account.message})`)
+      return 1
+    }
+  }
+  return 0
+}
+
 /* ---------- redpacket check(零副作用参数校验) ---------- */
 
 async function cmdCheck(argv) {
@@ -521,6 +617,7 @@ export async function main(argv) {
     if (cmd === 'balance') return await cmdBalance(argv.slice(1))
     if (cmd === 'mcp') return await startMcp()
     if (cmd === 'skill') return await cmdSkill(argv.slice(1))
+    if (cmd === 'setup') return await cmdSetup(argv.slice(1))
     if (cmd === 'redpacket') {
       const sub = argv[1]
       if (sub === 'create') return await cmdCreate(argv.slice(2))

package/src/mcp.js

@@ -11,11 +11,12 @@
  * 纪律: MCP 模式下 stdout 只输出 JSON-RPC 报文,任何日志走 stderr。
  */
 
+import { VERSION } from './version.js'
 import { loadConfig } from './store.js'
 import { resolveApikey, execPgsql, gatewayBase } from './tcb.js'
 import { normalizeCreateRedpacket, buildCreateSql } from './redpacket.js'
 
-const SERVER_INFO = { name: 'act-01', version: '0.1.0' }
+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']
 const LATEST = '2025-11-25'
 

package/src/redpacket.js

@@ -23,14 +23,14 @@ function optionalText(value, label, maxLen) {
 export function normalizeCreateRedpacket(body) {
   const mode = String(body.mode ?? '')
   if (mode !== 'random' && mode !== 'equal')
-    throw new ValidationError('type must be random or equal')
+    throw new ValidationError('红包类型必须是 random 或 equal')
 
   const totalPoints = positiveInteger(body.total_points, '总金额')
   const count = positiveInteger(body.count, '份数')
   const perUserLimit = positiveInteger(body.per_user_limit, '每人领取次数')
-  if (perUserLimit > count) throw new ValidationError('per-user limit cannot exceed count')
+  if (perUserLimit > count) throw new ValidationError('每人领取次数不能超过份数')
   if (mode === 'equal' && totalPoints < count)
-    throw new ValidationError('total must be at least count')
+    throw new ValidationError('均分总额不能小于份数')
 
   const shareTitle = optionalText(body.share_title, '分享标题', 60)
   const shareCover = optionalText(body.share_cover, '分享封面', 500)
@@ -58,9 +58,9 @@ export function normalizeCreateRedpacket(body) {
   const maxPoints = positiveInteger(body.max_points, '单份最大金额')
   if (maxPoints < minPoints) throw new ValidationError('单份最大金额不能小于最小金额')
   if (totalPoints < minPoints * count || totalPoints > maxPoints * count)
-    throw new ValidationError('total is outside the min..max × count range')
+    throw new ValidationError('总额不在可分配区间内(需介于 单份最小×份数 ~ 单份最大×份数)')
   if (totalPoints % count !== 0)
-    throw new ValidationError('total must be divisible by count')
+    throw new ValidationError('总额需能被份数整除(random 模式)')
 
   return { mode, totalPoints, count, perUserLimit, minPoints, maxPoints, shareTitle, shareCover, note, requireGroup }
 }

package/src/skill.js

@@ -23,6 +23,11 @@ const BODY = [
   '',
   '所有命令零依赖,Node >= 18。',
   '',
+  '## 一条命令装好(推荐)',
+  '',
+  B + 'act-01 setup "<配置串>" --install <技能根目录>' + B + ' —— 一次完成:装技能 + 导配置 + 查余额,',
+  '口令走 ' + B + 'ACT01_EXPORT_PASS' + B + ' 环境变量;配置串也可走 stdin 或 ' + B + 'ACT01_IMPORT_STRING' + B + '。',
+  '',
   '## 工具面',
   '',
   '| 途径 | 命令 / MCP 工具 | 副作用 |',
@@ -54,19 +59,21 @@ const BODY = [
   '## Agent 行为规则',
   '',
   '1. **先 check 后 create**:参数没把握时,先调 redpacket_check,拿到校验报告再执行',
-  '2. **create 前必须向用户确认参数**(mode/total/count/区间/群归属),MCP 客户端会弹审批',
+  '2. **create 前必须向用户确认参数**(mode/total/count/区间/群归属);确认后执行时,**非交互(非 TTY)必须带 --yes**,否则 CLI 会拒绝(MCP 客户端则弹审批)',
   '3. **结果转述只给摘要**:packet_no、余额变化;不要猜测或编造未返回的字段',
   '4. **失败处理**:错误信息是人话(余额不足/区间错误/整除错误),原样转告用户并给出修正建议;不要重试同参数的 create',
   '5. **金额单位**:内部整数单位,不要做 ×100 或 ÷100 的换算,除非用户明确要求',
   '',
   '## 失败速查',
   '',
-  '| 错误含 | 含义 | 修正 |',
+  '| 错误里含 | 含义 | 修正 |',
   '|---|---|---|',
-  '| 可分配区间 | total 不在 min×count ~ max×count | 调整 min/max 或 total |',
-  '| 整除 | total % count ≠ 0(random) | 调整 total 或 count |',
+  '| 必须是正整数 | 参数 ≤0 或非整数 | 传正整数(内部积分单位,不换算) |',
   '| 不能超过份数 | per_user_limit > count | 降低 per_user_limit |',
-  '| at least count | equal 模式 total < count | 提高 total |',
+  '| 不能小于份数 | equal 模式 total < count | 提高 total |',
+  '| 可分配区间 | total 不在 min×count ~ max×count | 调 min/max 或 total |',
+  '| 整除 | random 模式 total % count ≠ 0 | 调 total 或 count |',
+  '| 无法识别的配置串 | 配置串前缀/内容不对 | 用配套网页重新生成配置串 |',
   '| 余额不足 / insufficient | 账户余额 < total | 先充值或调低 total |',
   '',
   '## 配置前置',

package/src/version.js

@@ -0,0 +1,6 @@
+/**
+ * 版本号单一来源。main.js / mcp.js 共用,发布时只改这里 + package.json
+ * (test/version.test.js 会断言两者一致,防止再漏升)。
+ */
+
+export const VERSION = '0.1.4'