@yizhuan-cli/cli 0.1.5-beta.0 → 0.1.5

package/README.md

@@ -4,14 +4,16 @@
 
 ## 安装
 
+需要 Node.js 22 或更高版本。
+
 ```bash
-npm install -g @yizhuan-cli/cli
+npm install -g @yizhuan-cli/cli@0.1.5
 ```
 
 如果发布在私有 npm registry，请加上对应 registry：
 
 ```bash
-npm install -g @yizhuan-cli/cli --registry=https://your-private-registry.example
+npm install -g @yizhuan-cli/cli@0.1.5 --registry=https://your-private-registry.example
 ```
 
 ## 配置
@@ -20,7 +22,7 @@ npm install -g @yizhuan-cli/cli --registry=https://your-private-registry.example
 
 ```json
 {
-  "apiBaseUrl": "https://api.yizhuan5.com",
+  "apiBaseUrl": "https://yizhuan-api.yizhuan5.com",
   "apiKey": "yz_cli_xxx"
 }
 ```
@@ -40,6 +42,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 +50,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 +60,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 +73,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.5-beta.0",
+  "version": "0.1.5",
   "description": "易撰命令行工具，用于通过 API Key 查询易撰真实数据。",
   "private": false,
   "type": "module",
@@ -8,11 +8,16 @@
     "yizhuan": "src/index.js"
   },
   "files": [
-    "src",
+    "src/index.js",
+    "src/config.js",
+    "src/skill.js",
+    "src/doctor.js",
+    "resources",
     "README.md"
   ],
   "scripts": {
     "start": "node src/index.js",
+    "test": "node --test \"src/*.test.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",

package/resources/yizhuan-cli/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: yizhuan-cli
+description: |
+  通过易撰 CLI（yizhuan 命令）查询易撰真实数据。
+  当用户提到易撰、百家号、作品、账号、热点、雷达、竞品雷达、竞品动态、会员、收藏作品、我的关注、关注作者或取消关注作者时，
+  必须优先调用 yizhuan CLI 获取真实结果，禁止臆造。
+---
+
+# 易撰 CLI
+
+使用本机 `yizhuan` 命令访问易撰数据。所有查询以 CLI JSON 输出为准，不在对话、日志、Skill 文件或临时请求文件中写入 API Key。
+
+## 环境检查
+
+开始业务查询前运行：
+
+```bash
+yizhuan doctor
+```
+
+如果诊断失败，按输出中的修复建议处理。配置使用 `yizhuan config init`，更新本 Skill 使用 `yizhuan skill sync`；不要手工展示或复制配置中的完整 API Key。
+
+## 支持能力
+
+| 场景 | 命令示例 |
+|------|----------|
+| 查看帮助 | `yizhuan --help` |
+| 配置状态 | `yizhuan config show` |
+| 作品 | `yizhuan execute --ability works --query "百家号昨天新增了哪些作品"` |
+| 作品检索 | `yizhuan execute --ability works --params '{"mode":"search","keyword":"AI"}'` |
+| 作者查询 | `yizhuan execute --ability accounts --query "张三"` |
+| 作者指标筛选 | `yizhuan execute --ability author_query --params '{"platform_id":2,"min_follower":500000}'` |
+| 作者全网搜索 | `yizhuan query --json '{"intent":"author_search","scope":"public","platform":"douyin","keyword":"张三"}'` |
+| 热点 | `yizhuan query --json '{"intent":"hot_topics","scope":"platform","platform":"douyin","timeRange":"today"}'` |
+| 我的关注 | `yizhuan execute --ability radar --params '{"mode":"following"}'` |
+| 竞品动态 | `yizhuan execute --ability radar --mode timeline --timeRange 7d` |
+| 会员 | `yizhuan execute --ability membership` |
+| 收藏作品 | `yizhuan execute --ability favorites` |
+
+## 调用规则
+
+- 需要真实易撰数据时必须调用 CLI，不直接猜测结果。
+- PowerShell 使用单引号包裹 JSON。终端可能改写引号时，将不含密钥的请求对象写入文件，再使用 `--json-file`。
+- `execute --json-file` 是完整参数对象的唯一输入源，不与 `--params`、`--query` 或独立参数混用。
+- 热点查询使用 `query` 统一协议并明确 `platform`；缺少平台时先澄清，不默认猜测。
+- 全网作者搜索使用 `intent=author_search`、`scope=public`，并提供 `platform` 和 `keyword`。
+- 作者累计指标筛选使用 `author_query`，不得改成作品指标或擅自降低阈值。
+- “我的关注作者”使用 `radar` 且 `mode=following`，不是作品收藏。
+- 竞品动态使用 `radar` 且 `mode=timeline`；未给时间范围时使用 `timeRange=7d`。
+- 关注或取消关注属于写操作，必须来自用户明确指令；执行前核对昵称、平台和标识，不批量猜测目标。
+- 取消关注前先查询关注列表，使用匹配项的 `articleId`，不得因结果不符合预期自行取消。
+- `unsupported` 表示当前口径不支持，`empty` 表示没有匹配数据；如实转述，不编造补充结果。
+- CLI 报错时保留脱敏后的错误信息，引导检查 `yizhuan doctor`，不得输出完整 Key。

package/resources/yizhuan-cli/manifest.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": 1,
+  "name": "yizhuan-cli",
+  "version": "0.1.5",
+  "compatibleCliVersion": "0.1.5",
+  "source": "npm:@yizhuan-cli/cli@0.1.5",
+  "digestAlgorithm": "sha256",
+  "files": [
+    {
+      "path": "SKILL.md",
+      "sha256": "e165b200713dffc6a2c6b4c8efb25774edd73a6d3590ebec255c4903a2da5ec3"
+    }
+  ]
+}

package/src/config.js

@@ -0,0 +1,203 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { Writable } from 'node:stream'
+import { createInterface } from 'node:readline/promises'
+
+export const DEFAULT_API_BASE_URL = 'https://yizhuan-api.yizhuan5.com'
+export const CLI_TOOLS_URL = 'https://www.yizhuan5.com/app/cli-tools'
+
+export function getConfigPath() {
+  return process.env.YIZHUAN_CONFIG_PATH || path.join(os.homedir(), '.config', 'yizhuan', 'config.json')
+}
+
+export function maskApiKey(apiKey) {
+  const value = String(apiKey)
+  if (value.length <= 12) return '***'
+  return `${value.slice(0, 11)}...${value.slice(-4)}`
+}
+
+export function validateApiKey(apiKey) {
+  const value = String(apiKey || '').trim()
+  if (!value) {
+    throw new Error(`未提供 API Key。请访问 ${CLI_TOOLS_URL} 创建，然后使用隐藏输入或 --api-key-stdin。`)
+  }
+  if (!/^yz_cli_[A-Za-z0-9_-]{16,}$/.test(value)) {
+    throw new Error('API Key 格式无效，应为以 yz_cli_ 开头的易撰 CLI Key。')
+  }
+  return value
+}
+
+export function validateApiBaseUrl(apiBaseUrl) {
+  const value = String(apiBaseUrl || '').trim().replace(/\/+$/, '')
+  let url
+  try {
+    url = new URL(value)
+  } catch {
+    throw new Error('API 地址无效，请提供完整 URL。')
+  }
+
+  const isLoopback = ['localhost', '127.0.0.1', '::1'].includes(url.hostname)
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopback)) {
+    throw new Error('API 地址必须使用 HTTPS；仅显式配置的本机地址允许 HTTP。')
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new Error('API 地址不能包含凭据、查询参数或片段。')
+  }
+  return value
+}
+
+function readExistingConfig(configPath) {
+  if (!fs.existsSync(configPath)) return null
+  let parsed
+  try {
+    parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'))
+  } catch {
+    throw new Error(`已有配置无法解析，已保留原文件：${configPath}`)
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`已有配置格式无效，已保留原文件：${configPath}`)
+  }
+  return parsed
+}
+
+export function writeConfigAtomic(configPath, config) {
+  const directory = path.dirname(configPath)
+  const temporaryPath = path.join(
+    directory,
+    `.${path.basename(configPath)}.${process.pid}.${Date.now()}.tmp`
+  )
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 })
+
+  let descriptor
+  try {
+    descriptor = fs.openSync(temporaryPath, 'wx', 0o600)
+    fs.writeFileSync(descriptor, `${JSON.stringify(config, null, 2)}\n`, 'utf8')
+    fs.fsyncSync(descriptor)
+    fs.closeSync(descriptor)
+    descriptor = undefined
+    fs.renameSync(temporaryPath, configPath)
+    try {
+      fs.chmodSync(configPath, 0o600)
+    } catch {
+      // Windows ACLs are not represented by POSIX mode bits.
+    }
+  } catch (error) {
+    if (descriptor !== undefined) fs.closeSync(descriptor)
+    try {
+      fs.unlinkSync(temporaryPath)
+    } catch {
+      // The temporary file may not have been created.
+    }
+    throw new Error(`配置写入失败，原配置保持不变：${error.message}`)
+  }
+}
+
+export async function readHiddenInput(
+  prompt,
+  { input = process.stdin, output = process.stderr } = {}
+) {
+  if (!input.isTTY || !output.isTTY) {
+    throw new Error(
+      `当前终端不支持隐藏输入，请访问 ${CLI_TOOLS_URL} 创建 Key，并使用 --api-key-stdin 安全传入；不要在 Agent 对话中展示 Key。`
+    )
+  }
+
+  let muted = false
+  const hiddenOutput = new Writable({
+    write(chunk, encoding, callback) {
+      if (!muted) output.write(chunk, encoding)
+      callback()
+    }
+  })
+  hiddenOutput.isTTY = true
+  hiddenOutput.columns = output.columns
+
+  const readline = createInterface({ input, output: hiddenOutput, terminal: true })
+  try {
+    hiddenOutput.write(prompt)
+    muted = true
+    const value = await readline.question('')
+    muted = false
+    hiddenOutput.write('\n')
+    return value.trim()
+  } finally {
+    readline.close()
+  }
+}
+
+export async function readApiKeyInput(
+  args,
+  {
+    readStdin = () => fs.readFileSync(0, 'utf8'),
+    readHidden = () => readHiddenInput('API Key: '),
+    warn = (message) => console.error(message)
+  } = {}
+) {
+  if (args.apiKey && args.apiKeyStdin) {
+    throw new Error('--api-key 与 --api-key-stdin 不能同时使用。')
+  }
+  if (args.apiKey === true) {
+    throw new Error('--api-key 必须提供值。')
+  }
+  if (args.apiKey) {
+    warn('警告：--api-key 的值可能保留在 Shell 历史中；自动化请优先使用 --api-key-stdin。')
+    return String(args.apiKey).trim()
+  }
+  if (args.apiKeyStdin) {
+    return String(readStdin()).trim()
+  }
+  return readHidden()
+}
+
+export function printConfigInitHelp() {
+  console.log(`Usage:
+  yizhuan config init [options]
+
+Options:
+  --api-base-url <url>  API 地址，默认 ${DEFAULT_API_BASE_URL}
+  --api-key-stdin       从标准输入读取 API Key（推荐用于自动化）
+  --api-key <key>       从参数读取 API Key（可能保留在 Shell 历史中）
+  --force               覆盖已有配置
+  --help                显示本帮助
+
+未持有 API Key：${CLI_TOOLS_URL}`)
+}
+
+export async function runConfigInit(
+  args,
+  {
+    configPath = getConfigPath(),
+    readApiKey = readApiKeyInput,
+    writeConfig = writeConfigAtomic,
+    log = (message) => console.log(message)
+  } = {}
+) {
+  if (args.help) {
+    printConfigInitHelp()
+    return
+  }
+
+  const existingConfig = readExistingConfig(configPath)
+  if (existingConfig && !args.force) {
+    throw new Error(`配置已存在，未做修改：${configPath}。确认覆盖后请使用 --force。`)
+  }
+  if (args.apiBaseUrl === true) {
+    throw new Error('--api-base-url 必须提供值。')
+  }
+
+  const apiKey = validateApiKey(await readApiKey(args))
+  const apiBaseUrl = validateApiBaseUrl(
+    args.apiBaseUrl || existingConfig?.apiBaseUrl || DEFAULT_API_BASE_URL
+  )
+  const config = {
+    ...(existingConfig || {}),
+    apiBaseUrl,
+    apiKey
+  }
+
+  writeConfig(configPath, config)
+  log(`配置已写入：${configPath}`)
+  log(`API 地址：${apiBaseUrl}`)
+  log(`API Key：${maskApiKey(apiKey)}`)
+}

package/src/doctor.js

@@ -0,0 +1,278 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { DEFAULT_API_BASE_URL, getConfigPath, validateApiBaseUrl, validateApiKey } from './config.js'
+import {
+  compareVersions,
+  loadOfficialSkill,
+  readSkillMetadata,
+  resolveSkillTarget
+} from './skill.js'
+
+const STATUS_LABELS = {
+  pass: 'PASS',
+  warn: 'WARN',
+  fail: 'FAIL'
+}
+
+const CLI_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const PACKAGE_PATH = path.join(CLI_DIR, 'package.json')
+
+export function redactDiagnosticText(value) {
+  return String(value).replace(/yz_cli_[A-Za-z0-9_-]+/g, 'yz_cli_***')
+}
+
+function check(status, id, message, remediation) {
+  return {
+    id,
+    status,
+    message: redactDiagnosticText(message),
+    ...(remediation ? { remediation: redactDiagnosticText(remediation) } : {})
+  }
+}
+
+export function inspectLocalEnvironment(
+  {
+    configPath = getConfigPath(),
+    nodeVersion = process.versions.node,
+    platform = process.platform
+  } = {},
+  {
+    packageJson = JSON.parse(fs.readFileSync(PACKAGE_PATH, 'utf8')),
+    exists = fs.existsSync,
+    readFile = fs.readFileSync,
+    stat = fs.statSync,
+    access = fs.accessSync
+  } = {}
+) {
+  const checks = []
+  const minimumNode = String(packageJson.engines?.node || '').match(/>=\s*(\d+)/)?.[1]
+  const nodeSupported = minimumNode && compareVersions(nodeVersion, `${minimumNode}.0.0`) >= 0
+  checks.push(nodeSupported
+    ? check('pass', 'node', `Node.js ${nodeVersion} 满足 >=${minimumNode}`)
+    : check('fail', 'node', `Node.js ${nodeVersion} 不满足 ${packageJson.engines?.node || '版本要求'}`, `安装 Node.js ${minimumNode || 22} 或更高版本。`))
+
+  checks.push(packageJson.version === '0.1.5'
+    ? check('pass', 'cli_version', `CLI ${packageJson.version}`)
+    : check('fail', 'cli_version', `CLI 版本为 ${packageJson.version}，预期 0.1.5`, '安装 @yizhuan-cli/cli@0.1.5。'))
+
+  if (!exists(configPath)) {
+    checks.push(check('fail', 'config', `配置不存在：${configPath}`, '运行 yizhuan config init。'))
+    checks.push(check('fail', 'api_url', '无法检查 API 地址。', '先完成配置初始化。'))
+    checks.push(check('fail', 'config_permissions', '无法检查配置权限。', '先完成配置初始化。'))
+    return { checks, config: null }
+  }
+
+  let config
+  try {
+    config = JSON.parse(readFile(configPath, 'utf8'))
+    validateApiKey(config.apiKey)
+    checks.push(check('pass', 'config', `配置可解析且字段完整：${configPath}`))
+  } catch (error) {
+    checks.push(check('fail', 'config', `配置无效：${error.message}`, '运行 yizhuan config init --force。'))
+    checks.push(check('fail', 'api_url', '无法检查 API 地址。', '修复配置后重试。'))
+    config = null
+  }
+
+  if (config) {
+    try {
+      const apiBaseUrl = validateApiBaseUrl(config.apiBaseUrl)
+      checks.push(apiBaseUrl === DEFAULT_API_BASE_URL
+        ? check('pass', 'api_url', `正式 API 地址：${apiBaseUrl}`)
+        : check('warn', 'api_url', `使用显式自定义 API 地址：${apiBaseUrl}`, '确认该地址属于当前测试或开发环境。'))
+    } catch (error) {
+      checks.push(check('fail', 'api_url', `API 地址无效：${error.message}`, '重新运行 config init 并提供有效地址。'))
+    }
+  }
+
+  try {
+    access(configPath, fs.constants.R_OK | fs.constants.W_OK)
+    if (platform === 'win32') {
+      checks.push(check('warn', 'config_permissions', '配置文件可读写；Windows ACL 需由系统策略最终确认。', '确保仅当前用户可读取配置文件。'))
+    } else {
+      const exposedBits = stat(configPath).mode & 0o077
+      checks.push(exposedBits === 0
+        ? check('pass', 'config_permissions', '配置权限限制为当前用户。')
+        : check('fail', 'config_permissions', `配置权限过宽（mode ${exposedBits.toString(8)}）。`, `运行 chmod 600 "${configPath}"。`))
+    }
+  } catch (error) {
+    checks.push(check('fail', 'config_permissions', `配置权限检查失败：${error.message}`, '修复文件所有者或读写权限。'))
+  }
+
+  return { checks, config }
+}
+
+export async function inspectApi(
+  config,
+  { fetchImpl = fetch, timeoutMs = 8000 } = {}
+) {
+  let response
+  try {
+    response = await fetchImpl(`${String(config.apiBaseUrl).replace(/\/+$/, '')}/api/cli.execute`, {
+      method: 'POST',
+      headers: {
+        authorization: config.apiKey,
+        'content-type': 'application/json',
+        'x-device-type': 'pc'
+      },
+      body: JSON.stringify({ json: { ability: 'membership_info' } }),
+      signal: AbortSignal.timeout(timeoutMs)
+    })
+  } catch (error) {
+    return [
+      check('fail', 'api_connectivity', `API 无法连接：${error.message}`, '检查网络、代理和 API 地址。'),
+      check('fail', 'api_auth', '未执行 API Key 鉴权。', '恢复 API 连通性后重试。'),
+      check('fail', 'membership_read', '未读取会员状态。', '恢复 API 连通性后重试。')
+    ]
+  }
+
+  const connectivity = check('pass', 'api_connectivity', `API 已响应 HTTP ${response.status}`)
+  const responseText = await response.text()
+  if (!response.ok) {
+    const expired = /expired|过期/i.test(responseText)
+    const authFailure = response.status === 401 || response.status === 403
+    return [
+      connectivity,
+      check(
+        'fail',
+        'api_auth',
+        authFailure ? `API Key ${expired ? '已过期' : '无效或无权限'}。` : `鉴权请求返回 HTTP ${response.status}。`,
+        '在 Web CLI 工具页创建有效 Key，并运行 config init --force。'
+      ),
+      check('fail', 'membership_read', '未读取会员状态。', '修复鉴权后重试。')
+    ]
+  }
+
+  let payload
+  try {
+    payload = JSON.parse(responseText)
+  } catch {
+    return [
+      connectivity,
+      check('fail', 'api_auth', 'API 响应不是有效 JSON。', '确认 API 地址指向兼容的易撰服务。'),
+      check('fail', 'membership_read', '未读取会员状态。', '确认服务端已部署 CLI 接口。')
+    ]
+  }
+
+  const data = payload.result?.data?.json ?? payload
+  const membership = data?.data ?? data
+  if (!membership || (membership.isVip === undefined && membership.expiryDate === undefined)) {
+    return [
+      connectivity,
+      check('pass', 'api_auth', 'API Key 鉴权通过。'),
+      check('fail', 'membership_read', '会员状态响应缺少预期字段。', '确认服务端版本与 CLI 兼容。')
+    ]
+  }
+
+  return [
+    connectivity,
+    check('pass', 'api_auth', 'API Key 鉴权通过。'),
+    check('pass', 'membership_read', `会员状态可读（isVip=${Boolean(membership.isVip)}）。`)
+  ]
+}
+
+export function inspectSkill(
+  args,
+  {
+    exists = fs.existsSync,
+    resolveTarget = resolveSkillTarget,
+    readMetadata = readSkillMetadata,
+    loadBundle = loadOfficialSkill
+  } = {}
+) {
+  let resolved
+  try {
+    resolved = resolveTarget({ global: Boolean(args.global), host: args.host })
+  } catch (error) {
+    return check('warn', 'skill', `无法确定正式 Skill 位置：${error.message}`, '使用 doctor --host <name> 明确宿主。')
+  }
+  if (!exists(resolved.target)) {
+    return check('warn', 'skill', `正式 Skill 未安装：${resolved.target}`, `运行 yizhuan skill sync${args.global ? ' --global' : ''}。`)
+  }
+
+  try {
+    const metadata = readMetadata(resolved.target)
+    const { manifest } = loadBundle()
+    const comparison = compareVersions(metadata.version, manifest.version)
+    if (comparison < 0) {
+      return check('warn', 'skill', `正式 Skill ${metadata.version} 已过期，当前为 ${manifest.version}。`, `运行 yizhuan skill sync${args.global ? ' --global' : ''}。`)
+    }
+    if (comparison > 0 || metadata.source !== manifest.source) {
+      return check('warn', 'skill', `正式 Skill ${metadata.version} 与当前 CLI 来源不一致。`, '安装固定 CLI 版本后重新同步 Skill。')
+    }
+    return check('pass', 'skill', `正式 Skill ${metadata.version} 来源和摘要有效：${resolved.target}`)
+  } catch (error) {
+    return check('fail', 'skill', `正式 Skill 校验失败：${error.message}`, '保留冲突内容并人工确认，或移走后重新运行 skill sync。')
+  }
+}
+
+export async function runDoctorChecks(args, dependencies = {}) {
+  const local = inspectLocalEnvironment(
+    { configPath: dependencies.configPath, platform: dependencies.platform, nodeVersion: dependencies.nodeVersion },
+    dependencies
+  )
+  const checks = [...local.checks]
+  const apiUrlCheck = checks.find((item) => item.id === 'api_url')
+  if (local.config && apiUrlCheck?.status !== 'fail') {
+    checks.push(...await inspectApi(local.config, dependencies))
+  } else {
+    checks.push(
+      check('fail', 'api_connectivity', '未执行 API 连通性检查。', '先修复本地配置。'),
+      check('fail', 'api_auth', '未执行 API Key 鉴权。', '先修复本地配置。'),
+      check('fail', 'membership_read', '未读取会员状态。', '先修复本地配置。')
+    )
+  }
+  checks.push(inspectSkill(args, dependencies))
+  return checks
+}
+
+export function summarizeDoctorChecks(checks) {
+  if (checks.some((check) => check.status === 'fail')) return 'fail'
+  if (checks.some((check) => check.status === 'warn')) return 'warn'
+  return 'pass'
+}
+
+export function buildDoctorReport(checks) {
+  return {
+    status: summarizeDoctorChecks(checks),
+    checks
+  }
+}
+
+export function formatDoctorReport(report) {
+  const lines = report.checks.flatMap((check) => {
+    const result = [`[${STATUS_LABELS[check.status]}] ${check.id}: ${check.message}`]
+    if (check.remediation) result.push(`       修复：${check.remediation}`)
+    return result
+  })
+  lines.push(`诊断结果：${STATUS_LABELS[report.status]}`)
+  return lines.join('\n')
+}
+
+export function printDoctorHelp() {
+  console.log(`Usage:
+  yizhuan doctor [--json] [--global] [--host <name>]
+
+Options:
+  --json    输出稳定 JSON 结果
+  --global  检查用户级正式 Skill
+  --host    明确指定 codex、agents、claude 或 cursor
+  --help    显示本帮助`)
+}
+
+export async function runDoctor(
+  args,
+  {
+    runChecks = runDoctorChecks,
+    log = (message) => console.log(message)
+  } = {}
+) {
+  if (args.help) {
+    printDoctorHelp()
+    return { status: 'pass', checks: [] }
+  }
+
+  const report = buildDoctorReport(await runChecks(args))
+  log(args.json ? JSON.stringify(report, null, 2) : formatDoctorReport(report))
+  return report
+}

package/src/index.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 import fs from 'node:fs'
-import os from 'node:os'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { getConfigPath, maskApiKey, runConfigInit } from './config.js'
+import { runSkillSync } from './skill.js'
+import { runDoctor } from './doctor.js'
 
 const CLI_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const PACKAGE_PATH = path.join(CLI_DIR, 'package.json')
-const CONFIG_PATH = process.env.YIZHUAN_CONFIG_PATH || path.join(os.homedir(), '.config', 'yizhuan', 'config.json')
+const CONFIG_PATH = getConfigPath()
 const ABILITIES = new Set([
   'works',
   'accounts',
@@ -48,11 +50,15 @@ 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 init [--api-key-stdin] [--api-base-url <url>] [--force]
   yizhuan config path
   yizhuan config show
+  yizhuan skill sync [--global]
+  yizhuan doctor [--json]
 
 Examples:
   yizhuan execute --ability works --query "百家号昨天新增了哪些作品"
@@ -65,7 +71,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
 
@@ -131,7 +138,7 @@ function readFlagValue(argv, startIndex, key) {
   let raw = argv[index]
   if (raw == null) return { value: true, nextIndex: startIndex - 1 }
 
-  if (key === 'params' && /[{\[]/.test(raw)) {
+  if ((key === 'params' || key === 'json') && /[{\[]/.test(raw)) {
     let joined = raw
     while (!isBalancedJsonLike(joined) && index + 1 < argv.length && !String(argv[index + 1]).startsWith('--')) {
       index += 1
@@ -155,13 +162,13 @@ export function parseArgs(argv) {
     const body = value.slice(2)
     const eqIndex = body.indexOf('=')
     if (eqIndex > 0) {
-      const key = body.slice(0, eqIndex)
+      const key = body.slice(0, eqIndex).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())
       const raw = body.slice(eqIndex + 1)
       args[key] = raw
       continue
     }
 
-    const key = body
+    const key = body.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())
     const next = argv[index + 1]
     if (!next || next.startsWith('--')) {
       args[key] = true
@@ -287,6 +294,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 +317,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 +380,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 === '-'
@@ -372,9 +417,28 @@ async function main() {
     return
   }
 
+  if (command === 'config' && args._[1] === 'init') {
+    assertCommandArgs(args, 'config init', new Set(['apiBaseUrl', 'apiKey', 'apiKeyStdin', 'force', 'help']), 2)
+    await runConfigInit(args)
+    return
+  }
+
   if (command === 'config' && args._[1] === 'show') {
     const config = readConfig()
-    console.log(JSON.stringify({ ...config, apiKey: `${config.apiKey.slice(0, 18)}...` }, null, 2))
+    console.log(JSON.stringify({ ...config, apiKey: maskApiKey(config.apiKey) }, null, 2))
+    return
+  }
+
+  if (command === 'skill' && args._[1] === 'sync') {
+    assertCommandArgs(args, 'skill sync', new Set(['global', 'host', 'help']), 2)
+    await runSkillSync(args)
+    return
+  }
+
+  if (command === 'doctor') {
+    assertCommandArgs(args, 'doctor', new Set(['json', 'global', 'host', 'help']))
+    const report = await runDoctor(args)
+    if (report.status === 'fail') process.exitCode = 1
     return
   }
 

package/src/skill.js

@@ -0,0 +1,282 @@
+import fs from 'node:fs'
+import crypto from 'node:crypto'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const OFFICIAL_SKILL_NAME = 'yizhuan-cli'
+export const SKILL_METADATA_FILE = '.yizhuan-sync.json'
+export const SKILL_MANAGER = '@yizhuan-cli/cli'
+
+const CLI_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const DEFAULT_RESOURCE_DIR = path.join(CLI_DIR, 'resources', OFFICIAL_SKILL_NAME)
+
+const HOSTS = {
+  codex: { directory: '.codex', configEnv: 'CODEX_HOME' },
+  agents: { directory: '.agents' },
+  claude: { directory: '.claude', configEnv: 'CLAUDE_CONFIG_DIR' },
+  cursor: { directory: '.cursor', configEnv: 'CURSOR_CONFIG_DIR' }
+}
+
+function assertHost(host) {
+  if (!HOSTS[host]) {
+    throw new Error(`不支持的 Skill 宿主：${host}。可选值：${Object.keys(HOSTS).join(', ')}`)
+  }
+  return host
+}
+
+export function sha256File(filePath) {
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex')
+}
+
+function parseVersion(version) {
+  const matched = String(version).match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/)
+  if (!matched) throw new Error(`版本格式无效：${version}`)
+  return {
+    numbers: matched.slice(1, 4).map(Number),
+    prerelease: matched[4]
+  }
+}
+
+export function compareVersions(left, right) {
+  const a = parseVersion(left)
+  const b = parseVersion(right)
+  for (let index = 0; index < 3; index += 1) {
+    if (a.numbers[index] !== b.numbers[index]) return a.numbers[index] - b.numbers[index]
+  }
+  if (a.prerelease === b.prerelease) return 0
+  if (!a.prerelease) return 1
+  if (!b.prerelease) return -1
+  return a.prerelease.localeCompare(b.prerelease, 'en', { numeric: true })
+}
+
+function safeResourcePath(resourceDir, relativePath) {
+  if (!relativePath || path.isAbsolute(relativePath)) throw new Error('Skill manifest 包含非法文件路径。')
+  const resolved = path.resolve(resourceDir, relativePath)
+  if (!resolved.startsWith(`${path.resolve(resourceDir)}${path.sep}`)) {
+    throw new Error('Skill manifest 文件路径越界。')
+  }
+  return resolved
+}
+
+export function loadOfficialSkill(resourceDir = DEFAULT_RESOURCE_DIR) {
+  const manifestPath = path.join(resourceDir, 'manifest.json')
+  let manifest
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+  } catch (error) {
+    throw new Error(`无法读取正式 Skill manifest：${error.message}`)
+  }
+
+  if (
+    manifest.schemaVersion !== 1 ||
+    manifest.name !== OFFICIAL_SKILL_NAME ||
+    manifest.digestAlgorithm !== 'sha256' ||
+    manifest.source !== `npm:@yizhuan-cli/cli@${manifest.version}` ||
+    manifest.compatibleCliVersion !== manifest.version ||
+    !Array.isArray(manifest.files) ||
+    manifest.files.length === 0
+  ) {
+    throw new Error('正式 Skill manifest 格式或来源无效。')
+  }
+
+  for (const file of manifest.files) {
+    const sourcePath = safeResourcePath(resourceDir, file.path)
+    if (!/^[a-f0-9]{64}$/.test(file.sha256) || sha256File(sourcePath) !== file.sha256) {
+      throw new Error(`正式 Skill 内容校验失败：${file.path}`)
+    }
+  }
+  return { manifest, resourceDir }
+}
+
+export function readSkillMetadata(target) {
+  const metadataPath = path.join(target, SKILL_METADATA_FILE)
+  if (!fs.existsSync(metadataPath)) {
+    throw new Error(`目标存在未受易撰管理的同名内容，已停止同步：${target}`)
+  }
+  let metadata
+  try {
+    metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'))
+  } catch {
+    throw new Error(`同步元数据无法解析，已停止覆盖：${metadataPath}`)
+  }
+  if (
+    metadata.managedBy !== SKILL_MANAGER ||
+    metadata.name !== OFFICIAL_SKILL_NAME ||
+    !/^npm:@yizhuan-cli\/cli@/.test(metadata.source) ||
+    !Array.isArray(metadata.files)
+  ) {
+    throw new Error(`同步元数据来源不可信，已停止覆盖：${metadataPath}`)
+  }
+  for (const file of metadata.files) {
+    const installedPath = safeResourcePath(target, file.path)
+    if (!fs.existsSync(installedPath) || sha256File(installedPath) !== file.sha256) {
+      throw new Error(`已安装 Skill 包含未知修改，已停止覆盖：${file.path}`)
+    }
+  }
+  return metadata
+}
+
+function installStagedSkill(resolved, bundle, now) {
+  const { target } = resolved
+  const { manifest, resourceDir } = bundle
+  const parent = path.dirname(target)
+  const suffix = `${process.pid}.${now.getTime()}`
+  const staging = path.join(parent, `.${OFFICIAL_SKILL_NAME}.${suffix}.tmp`)
+  const backup = path.join(parent, `.${OFFICIAL_SKILL_NAME}.${suffix}.bak`)
+  fs.mkdirSync(parent, { recursive: true })
+
+  try {
+    fs.mkdirSync(staging, { mode: 0o700 })
+    for (const file of manifest.files) {
+      const sourcePath = safeResourcePath(resourceDir, file.path)
+      const destinationPath = safeResourcePath(staging, file.path)
+      fs.mkdirSync(path.dirname(destinationPath), { recursive: true })
+      fs.copyFileSync(sourcePath, destinationPath)
+      if (sha256File(destinationPath) !== file.sha256) {
+        throw new Error(`临时 Skill 内容校验失败：${file.path}`)
+      }
+    }
+
+    const metadata = {
+      schemaVersion: 1,
+      managedBy: SKILL_MANAGER,
+      name: manifest.name,
+      version: manifest.version,
+      compatibleCliVersion: manifest.compatibleCliVersion,
+      source: manifest.source,
+      digestAlgorithm: manifest.digestAlgorithm,
+      files: manifest.files,
+      host: resolved.host,
+      scope: resolved.scope,
+      syncedAt: now.toISOString()
+    }
+    fs.writeFileSync(path.join(staging, SKILL_METADATA_FILE), `${JSON.stringify(metadata, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600
+    })
+
+    if (!fs.existsSync(target)) {
+      fs.renameSync(staging, target)
+      return metadata
+    }
+
+    fs.renameSync(target, backup)
+    try {
+      fs.renameSync(staging, target)
+    } catch (error) {
+      fs.renameSync(backup, target)
+      throw error
+    }
+    fs.rmSync(backup, { recursive: true, force: true })
+    return metadata
+  } catch (error) {
+    fs.rmSync(staging, { recursive: true, force: true })
+    throw new Error(`Skill 原子更新失败，原目录保持不变：${error.message}`)
+  }
+}
+
+export function syncOfficialSkill(
+  resolved,
+  {
+    loadBundle = loadOfficialSkill,
+    installBundle = installStagedSkill,
+    now = () => new Date()
+  } = {}
+) {
+  const bundle = loadBundle()
+  const { manifest } = bundle
+  let installed
+  if (fs.existsSync(resolved.target)) {
+    installed = readSkillMetadata(resolved.target)
+    const comparison = compareVersions(installed.version, manifest.version)
+    if (comparison > 0) {
+      return { action: 'newer', metadata: installed, target: resolved.target }
+    }
+    if (comparison === 0) {
+      const matches = manifest.files.every((file) =>
+        fs.existsSync(safeResourcePath(resolved.target, file.path)) &&
+        sha256File(safeResourcePath(resolved.target, file.path)) === file.sha256
+      )
+      if (matches) return { action: 'current', metadata: installed, target: resolved.target }
+    }
+  }
+
+  const metadata = installBundle(resolved, bundle, now())
+  return { action: installed ? 'updated' : 'installed', metadata, target: resolved.target }
+}
+
+export function resolveSkillTarget(
+  { global = false, host },
+  {
+    cwd = process.cwd(),
+    home = os.homedir(),
+    env = process.env,
+    exists = fs.existsSync,
+    pathApi = path
+  } = {}
+) {
+  const requestedHost = host || env.YIZHUAN_SKILL_HOST
+  let selectedHost = requestedHost ? assertHost(String(requestedHost).toLowerCase()) : undefined
+
+  if (!selectedHost) {
+    const environmentHosts = Object.entries(HOSTS).filter(
+      ([, config]) => config.configEnv && env[config.configEnv]
+    )
+    if (environmentHosts.length === 1) {
+      selectedHost = environmentHosts[0][0]
+    } else if (environmentHosts.length > 1) {
+      throw new Error('检测到多个宿主环境，请使用 --host codex|agents|claude|cursor 明确指定。')
+    } else {
+      const root = global ? home : cwd
+      const directoryHosts = Object.entries(HOSTS).filter(([, config]) =>
+        exists(pathApi.join(root, config.directory))
+      )
+      if (!global && directoryHosts.length > 0) {
+        selectedHost = directoryHosts[0][0]
+      } else if (directoryHosts.length === 1) {
+        selectedHost = directoryHosts[0][0]
+      } else {
+        const reason = directoryHosts.length ? '检测到多个全局宿主' : '未检测到受支持宿主'
+        throw new Error(`${reason}，请使用 --host codex|agents|claude|cursor 明确指定。`)
+      }
+    }
+  }
+
+  const config = HOSTS[selectedHost]
+  const configuredRoot = global && config.configEnv ? env[config.configEnv] : undefined
+  const hostRoot = configuredRoot || pathApi.join(global ? home : cwd, config.directory)
+  return {
+    host: selectedHost,
+    scope: global ? 'global' : 'project',
+    root: pathApi.join(hostRoot, 'skills'),
+    target: pathApi.join(hostRoot, 'skills', OFFICIAL_SKILL_NAME)
+  }
+}
+
+export function printSkillSyncHelp() {
+  console.log(`Usage:
+  yizhuan skill sync [--global] [--host <name>]
+
+Options:
+  --global  安装到当前受支持宿主的用户级 Skill 目录
+  --host    明确指定 codex、agents、claude 或 cursor
+  --help    显示本帮助`)
+}
+
+export async function runSkillSync(args) {
+  if (args.help) {
+    printSkillSyncHelp()
+    return
+  }
+
+  const resolved = resolveSkillTarget({ global: Boolean(args.global), host: args.host })
+  const result = syncOfficialSkill(resolved)
+  const actionText = {
+    installed: '已安装',
+    updated: '已更新',
+    current: '无需更新',
+    newer: '已安装版本较新，未降级'
+  }[result.action]
+  console.log(`${actionText}正式 Skill ${result.metadata.version}：${result.target}`)
+}

package/src/params.test.js

@@ -1,54 +0,0 @@
-import test from 'node:test'
-import assert from 'node:assert/strict'
-import { buildExecuteParams, parseArgs, parseParams } from './index.js'
-
-test('parseParams accepts standard JSON', () => {
-  assert.deepEqual(parseParams('{"platform":"douyin"}'), { platform: 'douyin' })
-})
-
-test('parseParams repairs PowerShell-mangled escaped JSON fragments', () => {
-  assert.deepEqual(parseParams('{\\platform\\:\\douyin\\}'), { platform: 'douyin' })
-  assert.deepEqual(parseParams('{"platform":"douyin"}'.replaceAll('"', '\\"')), {
-    platform: 'douyin'
-  })
-})
-
-test('parseParams accepts key=value and loose objects', () => {
-  assert.deepEqual(parseParams('platform=douyin'), { platform: 'douyin' })
-  assert.deepEqual(parseParams('{platform:douyin,mode:list}'), {
-    platform: 'douyin',
-    mode: 'list'
-  })
-})
-
-test('buildExecuteParams merges top-level flags', () => {
-  assert.deepEqual(
-    buildExecuteParams({
-      params: '{"mode":"timeline"}',
-      platform: 'douyin',
-      timeRange: '7d'
-    }),
-    {
-      mode: 'timeline',
-      platform: 'douyin',
-      timeRange: '7d'
-    }
-  )
-})
-
-test('buildExecuteParams prefers explicit params keys over flags', () => {
-  assert.deepEqual(
-    buildExecuteParams({
-      params: 'platform=weibo',
-      platform: 'douyin'
-    }),
-    { platform: 'weibo' }
-  )
-})
-
-test('parseArgs preserves query JSON supplied after --json', () => {
-  assert.deepEqual(
-    parseArgs(['query', '--json', '{"intent":"author_search","platform":"douyin"}']),
-    { _: ['query'], json: '{"intent":"author_search","platform":"douyin"}' }
-  )
-})

package/src/version.test.js

@@ -1,22 +0,0 @@
-import assert from 'node:assert/strict'
-import { execFileSync } from 'node:child_process'
-import fs from 'node:fs'
-import path from 'node:path'
-import test from 'node:test'
-import { fileURLToPath } from 'node:url'
-
-const CLI_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
-const ENTRY_PATH = path.join(CLI_DIR, 'src', 'index.js')
-const PACKAGE_PATH = path.join(CLI_DIR, 'package.json')
-const expectedVersion = JSON.parse(fs.readFileSync(PACKAGE_PATH, 'utf8')).version
-
-for (const flag of ['--version', '-v']) {
-  test(`${flag} prints the package version`, () => {
-    const output = execFileSync(process.execPath, [ENTRY_PATH, flag], {
-      encoding: 'utf8'
-    }).trim()
-
-    assert.equal(output, expectedVersion)
-    assert.notEqual(output, '')
-  })
-}