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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blod-nm/1kuan-act-01-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Internal operations CLI: invoke preset database functions via a gateway. Zero dependencies, MCP (stdio) support.",
   "license": "MIT",
@@ -37,4 +37,4 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   }
-}
+}

package/src/main.js

@@ -3,9 +3,11 @@
  */
 
 import { parseArgs } from 'node:util'
-import { configPath, loadConfig, saveConfig, decodeConfigString, encryptConfig } from './store.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'
@@ -22,6 +24,7 @@ const USAGE = `act-01 —— operations CLI(invoke preset database functions)
   config export                  导出加密配置串(口令交互输入或 ACT01_EXPORT_PASS)
   config import <串|--stdin>      导入配置串(自动识别 加密/明文/网页格式)
   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)
@@ -306,6 +309,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 +520,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/skill.js

@@ -0,0 +1,83 @@
+/**
+ * 内置 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 的换算,除非用户明确要求',
+  '',
+  '## 失败速查',
+  '',
+  '| 错误含 | 含义 | 修正 |',
+  '|---|---|---|',
+  '| 可分配区间 | total 不在 min×count ~ max×count | 调整 min/max 或 total |',
+  '| 整除 | total % count ≠ 0(random) | 调整 total 或 count |',
+  '| 不能超过份数 | per_user_limit > count | 降低 per_user_limit |',
+  '| at least count | equal 模式 total < count | 提高 total |',
+  '| 余额不足 / 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)}`)