@blod-nm/1kuan-act-01-cli 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blod-nm/1kuan-act-01-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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,12 +3,14 @@
  */
 
 import { parseArgs } from 'node:util'
-import { configPath, loadConfig, saveConfig, decodeConfigString, encryptConfig } from './store.js'
+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 { 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)
 
@@ -20,8 +22,9 @@ 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 <口令>]  导入配置串(加密串需口令;自动识别 三种格式)
   mcp                            启动 MCP 服务(stdio;接入 Claude 等 AI 客户端)
+  skill                          输出 agent 技能文档(--install <dir> 写入)
   balance                        account balance
   redpacket create               create a record(pre-flight balance check, atomic deduct)
   redpacket check                validate params(side-effect free)
@@ -180,7 +183,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)')
@@ -190,10 +199,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
         }
@@ -306,6 +315,37 @@ function normalizeFromValues(values) {
   })
 }
 
+/* ---------- skill ---------- */
+
+async function cmdSkill(argv) {
+  const { values, positionals } = parseArgs({
+    strict: false,
+    allowPositionals: true,
+    args: argv,
+    options: { install: { type: 'string' } },
+  })
+  const sub = positionals[0] ?? SKILL_NAME
+  if (sub !== SKILL_NAME) {
+    const err = new Error(`未知 skill: ${sub}(可用: ${SKILL_NAME})`)
+    err.exitCode = 2
+    throw err
+  }
+
+  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)
+    console.log(`SKILL.md 已写入: ${file}`)
+    console.error('hint: 把该目录加入你的 agent 技能路径')
+    return 0
+  }
+
+  console.log(SKILL_MD)
+  return 0
+}
+
 /* ---------- redpacket check(零副作用参数校验) ---------- */
 
 async function cmdCheck(argv) {
@@ -486,6 +526,7 @@ export async function main(argv) {
     if (cmd === 'config') return await cmdConfig(argv.slice(1))
     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 === '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

@@ -0,0 +1,85 @@
+/**
+ * 内置 agent skill:给 AI 客户端的完整操作技能文档。
+ * act-01 skill          → 打印 SKILL.md(agent 抓 stdout 即可)
+ * act-01 skill --install <dir> → 写入 <dir>/SKILL.md
+ */
+
+const B = '`' // 模板串内的反引号统一用变量拼接,避免转义地狱
+
+const BODY = [
+  '---',
+  'name: act-01-ops',
+  'description: act-01 运营操作技能——通过 act-01 CLI / MCP 工具安全地创建 packet、查询余额。资金操作,遵守三道闸门。',
+  '---',
+  '',
+  '# act-01 运营操作',
+  '',
+  '通过云开发网关调用预置数据库函数(原子操作)。',
+  '',
+  '## 运行方式(二选一)',
+  '',
+  '- 已全局安装:' + B + 'act-01 <命令>' + B,
+  '- 未安装:每条命令前加 ' + B + 'npx -y @blod-nm/1kuan-act-01-cli' + B + ',如 ' + B + 'npx -y @blod-nm/1kuan-act-01-cli balance' + B,
+  '',
+  '所有命令零依赖,Node >= 18。',
+  '',
+  '## 工具面',
+  '',
+  '| 途径 | 命令 / MCP 工具 | 副作用 |',
+  '|---|---|---|',
+  '| 参数校验 | ' + B + 'act-01 redpacket check <flags>' + B + ' / ' + B + 'redpacket_check' + B + ' | 零副作用,优先用 |',
+  '| 余额查询 | ' + B + 'act-01 balance' + B + ' / ' + B + 'balance' + B + ' | 只读 |',
+  '| 创建 packet | ' + B + 'act-01 redpacket create <flags>' + B + ' / ' + B + 'redpacket_create' + B + ' | **有副作用:账户原子扣减** |',
+  '',
+  '## create 参数规格',
+  '',
+  '| 参数 | 规则 |',
+  '|---|---|',
+  '| mode | random(随机)/ equal(均分) |',
+  '| total_points | 正整数(内部单位,不换算) |',
+  '| count | 正整数(份数) |',
+  '| per_user_limit | 正整数,≤ count |',
+  '| min_points / max_points(仅 random) | max ≥ min;total ∈ [min×count, max×count];total % count === 0 |',
+  '| share_title / note | 可选,≤60 / ≤20 字 |',
+  '| require_group | 布尔,默认 false |',
+  '',
+  'equal 模式自动 min = floor(total/count),max = ceil(total/count)。',
+  '',
+  '## 安全三道闸门',
+  '',
+  '1. **CLI 预检**:balance < total_points 时直接拒绝(不触数据库写)',
+  '2. **确认卡**:执行前列出全部参数,等用户确认',
+  '3. **库函数原子扣减**:并发/余额竞争由数据库兜底,不会扣穿',
+  '',
+  '## Agent 行为规则',
+  '',
+  '1. **先 check 后 create**:参数没把握时,先调 redpacket_check,拿到校验报告再执行',
+  '2. **create 前必须向用户确认参数**(mode/total/count/区间/群归属),MCP 客户端会弹审批',
+  '3. **结果转述只给摘要**:packet_no、余额变化;不要猜测或编造未返回的字段',
+  '4. **失败处理**:错误信息是人话(余额不足/区间错误/整除错误),原样转告用户并给出修正建议;不要重试同参数的 create',
+  '5. **金额单位**:内部整数单位,不要做 ×100 或 ÷100 的换算,除非用户明确要求',
+  '',
+  '## 失败速查',
+  '',
+  '| 错误里含 | 含义 | 修正 |',
+  '|---|---|---|',
+  '| 必须是正整数 | 参数 ≤0 或非整数 | 传正整数(内部积分单位,不换算) |',
+  '| 不能超过份数 | per_user_limit > count | 降低 per_user_limit |',
+  '| 不能小于份数 | equal 模式 total < count | 提高 total |',
+  '| 可分配区间 | total 不在 min×count ~ max×count | 调 min/max 或 total |',
+  '| 整除 | random 模式 total % count ≠ 0 | 调 total 或 count |',
+  '| 无法识别的配置串 | 配置串前缀/内容不对 | 用配套网页重新生成配置串 |',
+  '| 余额不足 / insufficient | 账户余额 < total | 先充值或调低 total |',
+  '',
+  '## 配置前置',
+  '',
+  '目标机器需要云开发配置(envId + apiKey)。没有配置文件时,让用户用配套网页',
+  '(config-helper.html)生成加密配置串,然后:',
+  '',
+  B + 'act-01 config import "配置串"' + B + '(会提示输入生成时的口令)',
+  '',
+].join('\n')
+
+export const SKILL_MD = BODY
+
+export const SKILL_NAME = 'act-01-ops'

package/src/tcb.js

@@ -3,13 +3,15 @@
  *
  * 端点:POST https://{envId}.api.tcloudbasegateway.com/v1/rdb/exec-pgsql
  * 鉴权:Authorization: Bearer <apiKey>
- * 请求体:{ sql } —— exec-pgsql 只收一整条 SQL(无 parameters 通道),
+ * 请求体:{ sql, role } —— exec-pgsql 只收一整条 SQL(无 parameters 通道),
  *         $1..$11 由客户端绑定成带类型的字面量(文本单引号翻倍,数值/布尔直书)。
+ * 角色:固定 cloudbase_postgres(管理可读写)——网关默认是只读,不显式升权写语句会被 42501 拒。
  */
 
 import { loadConfig } from './store.js'
 
 export const GATEWAY_DOMAIN = 'api.tcloudbasegateway.com'
+export const PG_ROLE = 'cloudbase_postgres'
 
 export function resolveApikey(config, flagValue) {
   const raw = flagValue ?? process.env.ACT01_API_KEY ?? config.apiKey
@@ -44,7 +46,7 @@ export async function execPgsql(config, apikey, sql) {
         'Content-Type': 'application/json',
         Authorization: `Bearer ${apikey}`,
       },
-      body: JSON.stringify({ sql }),
+      body: JSON.stringify({ sql, role: PG_ROLE }),
     })
   } catch (err) {
     throw new Error(`网关连接失败:${err instanceof Error ? err.message : String(err)}`)

package/src/version.js

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