@yizhuan-cli/cli 0.1.6-beta.0 → 0.1.7-beta.0

package/README.md

@@ -40,6 +40,7 @@ yizhuan execute --ability accounts --params '{"mode":"public_search","platform":
 yizhuan execute --ability radar --params '{"mode":"following"}'
 yizhuan execute --ability radar --mode timeline --timeRange 7d
 yizhuan execute --ability radar --params '{"mode":"unfollow","articleId":"205169870"}'
+yizhuan execute --ability radar --json-file params.json
 ```
 
 ### PowerShell 参数说明
@@ -47,8 +48,8 @@ yizhuan execute --ability radar --params '{"mode":"unfollow","articleId":"205169
 PowerShell 对 JSON 双引号转义不友好。推荐以下写法：
 
 ```powershell
-# 最稳妥：独立参数
-yizhuan execute --ability hot_topics --platform douyin
+# Agent 和跨 Shell 最稳妥：参数文件是唯一输入源
+yizhuan execute --ability hot_topics --json-file params.json
 
 # 单引号包 JSON
 yizhuan execute --ability hot_topics --params '{"platform":"douyin"}'
@@ -57,6 +58,8 @@ yizhuan execute --ability hot_topics --params '{"platform":"douyin"}'
 yizhuan execute --ability hot_topics --params platform=douyin
 ```
 
+`execute --json-file` 不能与 `--params`、`--query` 或独立参数混用。CLI 会拒绝未知参数和游离的 `key=value`，避免参数丢失后执行默认能力。
+
 请避免 bash 风格的：
 
 ```powershell
@@ -68,6 +71,7 @@ yizhuan execute --ability hot_topics --params "{\"platform\":\"douyin\"}"
 
 - 作品查询：`yizhuan execute --ability works --query "AI 相关的热门作品有哪些"`
 - 作者查询：`yizhuan execute --ability accounts --query "查询张三这个作者"`
+- 作者指标筛选：`yizhuan execute --ability author_query --params '{"platform_id":2,"min_follower":500000,"min_total_likes":100000}'`
 - 作者全网搜索：`yizhuan execute --ability accounts --params '{"mode":"public_search","platform":"toutiao","keyword":"张三"}'`
 - 关注全网作者：`yizhuan execute --ability accounts --params '{"mode":"follow_public_author","platform":"toutiao","keyword":"张三","extAuthorId":"author-1"}'`
 - 热点查询：`yizhuan execute --ability hot_topics --platform douyin`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yizhuan-cli/cli",
-  "version": "0.1.6-beta.0",
+  "version": "0.1.7-beta.0",
   "description": "易撰命令行工具，用于通过 API Key 查询易撰真实数据。",
   "private": false,
   "type": "module",
@@ -11,6 +11,13 @@
     "src",
     "README.md"
   ],
+  "scripts": {
+    "start": "node src/index.js",
+    "pack:dry-run": "npm pack --dry-run",
+    "smoke": "node src/index.js --help && node --test src/version.test.js",
+    "test:params": "node --test src/params.test.js",
+    "test:version": "node --test src/version.test.js"
+  },
   "engines": {
     "node": ">=22"
   },
@@ -22,12 +29,5 @@
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "start": "node src/index.js",
-    "pack:dry-run": "npm pack --dry-run",
-    "smoke": "node src/index.js --help && node --test src/version.test.js",
-    "test:params": "node --test src/params.test.js",
-    "test:version": "node --test src/version.test.js"
   }
-}
+}

package/src/index.js

@@ -48,7 +48,8 @@ function printHelp() {
 Usage:
   yizhuan --help
   yizhuan --version
-  yizhuan execute --ability <ability> [--query <text>] [--params <json>] [--platform <name>]
+  yizhuan execute --ability <ability> [--query <text>] [--params <json>]
+  yizhuan execute --ability <ability> --json-file <params-file>
   yizhuan query --json '<request JSON>' [--format json|table|markdown]
   yizhuan query --json-file <path> [--format json|table|markdown]
   yizhuan config path
@@ -65,7 +66,8 @@ Examples:
 
 Notes:
   - PowerShell 推荐优先使用 --platform / --mode 等独立参数，或单引号 JSON：--params '{"platform":"douyin"}'
-  - 所有 Shell 都可用 --json-file request.json，避免 JSON 引号被终端改写
+  - Agent 和所有 Shell 推荐使用 execute --json-file params.json，避免 JSON 引号被终端改写
+  - --json-file 是唯一参数源，不能与 --params、--query 或独立参数混用
   - bash/zsh 也可用：--params '{"platform":"douyin"}' 或 --platform douyin
   - 兼容 key=value：--params platform=douyin
 
@@ -287,6 +289,22 @@ function assignFlagParams(params, args) {
 }
 
 export function buildExecuteParams(args) {
+  if (args.jsonFile) {
+    const conflictingKeys = ['params', 'query', ...PARAM_FLAG_KEYS].filter(
+      (key) => args[key] != null && args[key] !== false
+    )
+    if (conflictingKeys.length > 0) {
+      throw new Error(
+        `execute --json-file 不能与其他参数输入混用：${conflictingKeys.map((key) => `--${key}`).join(', ')}`
+      )
+    }
+
+    const jsonText = fs.readFileSync(path.resolve(String(args.jsonFile)), 'utf8')
+    const fileParams = parseParams(jsonText)
+    if (!fileParams) throw new Error('execute --json-file 必须包含 JSON 参数对象')
+    return fileParams
+  }
+
   const params = {
     ...(parseParams(args.params) || {})
   }
@@ -294,7 +312,28 @@ export function buildExecuteParams(args) {
   return Object.keys(params).length > 0 ? params : undefined
 }
 
+export function assertCommandArgs(args, command, allowedFlags, positionalCount = 1) {
+  const extraPositionals = args._.slice(positionalCount)
+  if (extraPositionals.length > 0) {
+    throw new Error(
+      `${command} 存在未识别的位置参数：${extraPositionals.join(' ')}。多个参数必须写入同一个 JSON 对象`
+    )
+  }
+
+  const unknownFlags = Object.keys(args).filter(
+    (key) => key !== '_' && !allowedFlags.has(key)
+  )
+  if (unknownFlags.length > 0) {
+    throw new Error(`${command} 存在未知参数：${unknownFlags.map((key) => `--${key}`).join(', ')}`)
+  }
+}
+
 async function execute(args) {
+  assertCommandArgs(
+    args,
+    'execute',
+    new Set(['ability', 'query', 'params', 'jsonFile', ...PARAM_FLAG_KEYS])
+  )
   const ability = args.ability
   if (!ABILITIES.has(ability)) {
     throw new Error(`未知 ability：${ability || ''}，请执行 yizhuan --help 查看可用能力`)
@@ -336,6 +375,7 @@ function renderQuery(payload, format) {
 }
 
 async function query(args) {
+  assertCommandArgs(args, 'query', new Set(['json', 'jsonFile', 'params', 'format']))
   const jsonText = args.jsonFile
     ? fs.readFileSync(path.resolve(String(args.jsonFile)), 'utf8')
     : args.json === '-'

package/src/params.test.js

@@ -1,6 +1,8 @@
 import test from 'node:test'
 import assert from 'node:assert/strict'
-import { buildExecuteParams, parseArgs, parseParams } from './index.js'
+import { rmSync, writeFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { assertCommandArgs, buildExecuteParams, parseArgs, parseParams } from './index.js'
 
 test('parseParams accepts standard JSON', () => {
   assert.deepEqual(parseParams('{"platform":"douyin"}'), { platform: 'douyin' })
@@ -46,6 +48,36 @@ test('buildExecuteParams prefers explicit params keys over flags', () => {
   )
 })
 
+test('buildExecuteParams reads execute params from --json-file', (t) => {
+  const fixture = new URL(`./params-${process.pid}-${Date.now()}.json`, import.meta.url)
+  t.after(() => rmSync(fixture))
+  writeFileSync(
+    fixture,
+    JSON.stringify({
+      mode: 'follow',
+      platform: 'baijiahao',
+      extAuthorId: '1659153597622724'
+    })
+  )
+
+  assert.deepEqual(buildExecuteParams({ jsonFile: fileURLToPath(fixture) }), {
+    mode: 'follow',
+    platform: 'baijiahao',
+    extAuthorId: '1659153597622724'
+  })
+})
+
+test('buildExecuteParams rejects mixed --json-file and flag inputs', (t) => {
+  const fixture = new URL(`./params-${process.pid}-${Date.now()}.json`, import.meta.url)
+  t.after(() => rmSync(fixture))
+  writeFileSync(fixture, '{"mode":"following"}')
+
+  assert.throws(
+    () => buildExecuteParams({ jsonFile: fileURLToPath(fixture), mode: 'follow' }),
+    /不能与其他参数输入混用/
+  )
+})
+
 test('parseArgs preserves query JSON supplied after --json', () => {
   assert.deepEqual(
     parseArgs(['query', '--json', '{"intent":"author_search","platform":"douyin"}']),
@@ -66,3 +98,19 @@ test('parseArgs preserves query JSON split into multiple argv fragments', () =>
     { _: ['query'], json: '{"intent":"author_search","platform":"douyin"}' }
   )
 })
+
+test('assertCommandArgs rejects extra key=value positionals', () => {
+  const args = parseArgs([
+    'execute',
+    '--ability',
+    'radar',
+    '--params',
+    'mode=follow',
+    'platform=baijiahao'
+  ])
+
+  assert.throws(
+    () => assertCommandArgs(args, 'execute', new Set(['ability', 'params'])),
+    /未识别的位置参数/
+  )
+})