@yizhuan-cli/cli 0.1.17-beta.0 → 0.1.17-beta.2

package/README.md

@@ -99,3 +99,9 @@ yizhuan execute --ability hot_topics --params "{\"platform\":\"douyin\"}"
 - `我的会员什么时候到期`
 
 纯创作请求（例如“写一篇中秋文章”）由当前 Agent 完成，不调用 `content_extract`；CLI 只提供真实内容素材，不负责生成、改写或发布。
+
+## 使用统计
+
+仅采集业务调用元数据，不采集问题、关键词、URL、正文或返回内容。
+调用方可设置 `YIZHUAN_TRIGGER=user_initiated` 表示用户当前提问或手动触发（含 AI 代执行），设置 `YIZHUAN_TRIGGER=automated` 表示定时或无人值守任务。
+未设置时归为 `unknown`，不会猜测来源。检测轮询不计活跃。通过 `YIZHUAN_TELEMETRY=0` 可关闭使用埋点。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yizhuan-cli/cli",
-  "version": "0.1.17-beta.0",
+  "version": "0.1.17-beta.2",
   "description": "易撰命令行工具，用于通过 API Key 查询易撰真实数据。",
   "private": false,
   "type": "module",
@@ -12,6 +12,7 @@
     "src/config.js",
     "src/skill.js",
     "src/doctor.js",
+    "src/usage.js",
     "resources",
     "README.md"
   ],

package/resources/yizhuan-cli/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: yizhuan-cli
 description: |
-  安装、配置并使用易撰 CLI（yizhuan 命令）查询真实数据、提取文章/视频/图文内容的全量 Skill；若已安装用户明确指定平台对应的 yizhuan-<platform> Skill，必须优先使用对应的拆分平台 Skill。业务数据禁止臆造，文章创作由当前 Agent 完成。
+  安装、配置并使用易撰 CLI（yizhuan 命令）查询真实数据、提取文章/视频/图文内容的全量 Skill；若已安装用户明确指定平台对应的易撰平台 Skill，必须优先使用对应的拆分平台 Skill。业务数据禁止臆造，文章创作由当前 Agent 完成。
 ---
 
 # 易撰 CLI
@@ -94,3 +94,43 @@ yizhuan doctor
 - 取消关注前先查询关注列表，使用匹配项的 `articleId`，不得因结果不符合预期自行取消。
 - `unsupported` 表示当前口径不支持，`empty` 表示没有匹配数据；如实转述，不编造补充结果。
 - CLI 报错时保留脱敏后的错误信息，引导检查 `yizhuan doctor`，不得输出完整 Key。
+
+## CLI 调用来源
+
+在每次 `execute` 或 `query` 业务调用前，根据本次任务的触发原因设置进程环境变量 `YIZHUAN_TRIGGER`：
+
+- `user_initiated`：用户当前提问、手动指令及为完成该请求而执行的分页、后续能力调用。AI 代用户执行仍属于主动使用。
+- `automated`：定时执行、无人值守批处理、后台监控或自动唤醒。用户曾要求建立定时任务，不代表每次定时运行都是主动使用。
+- `unknown`：无法确定触发原因；不得默认标为主动，也不得仅因使用 AI 工具就标为自动。
+
+每次按当前触发原因显式覆盖，避免继承上一任务的来源。来源只通过子进程环境传递，不写入业务 JSON、API Key 配置或系统全局环境。调用结束后恢复原环境；一个任务中的分页保持同一来源，CLI 内置检测轮询由 CLI/服务端自动排除，不手工伪造 `polling`。
+
+Bash/zsh 的单次主动查询示例（自动任务把值改为 `automated`）：
+
+```bash
+YIZHUAN_TRIGGER=user_initiated yizhuan query --json-file request.json
+```
+
+PowerShell 示例，使用当前任务选择的来源并恢复原值：
+
+```powershell
+$cliPreviousTrigger = $env:YIZHUAN_TRIGGER
+try {
+  $env:YIZHUAN_TRIGGER = 'user_initiated'
+  yizhuan query --json-file request.json
+} finally {
+  $env:YIZHUAN_TRIGGER = $cliPreviousTrigger
+}
+```
+
+只有元数据参与使用统计，不额外上传用户问题、关键词、链接或正文。尊重用户现有的 `YIZHUAN_TELEMETRY=0` 设置，不启用或覆盖它。安装、配置、doctor、help 和 version 不作为业务使用；来源设置无需额外询问用户。来源标签不是触发新业务调用或定时任务的授权。
+
+## 任务关联与中文功能统计
+
+使用支持任务关联的新版本 CLI 时，每次明确用户目标或自动任务运行生成一个随机 UUID 作为 taskId。同一目标内的 execute/query 共用 `--task-id`，新的独立目标更换 ID；不要把整个聊天会话当作一次任务。使用 `yizhuan task start --task-id <uuid>` 建立任务，任务结束使用 `yizhuan task finish --task-id <uuid> --status completed|failed|cancelled`。自由任务不必声明目标路径；已明确固定流程时，可在 start 使用 `--goal-feature-ids works_search,content_extract,content_detection` 声明内部功能标识。
+
+每次业务操作生成独立 UUID 并传入 `--operation-id`；同一操作的技术重试复用该 ID，用户重新执行则换 ID。仅在后一步实际使用了前一步的输出时，传入 `--parent-operation-ids <前序操作UUID,...>`；不能仅因先后执行就声明连接。串行任务可传 `--sequence 0`、`--sequence 1` 等顺序，并行步骤不要伪造成串行顺序。分页通常是新的业务查询操作，CLI 内置检测轮询自动复用操作标识且不重复计数。
+
+也可通过当前任务子进程的 `YIZHUAN_TASK_ID`、`YIZHUAN_OPERATION_ID`、`YIZHUAN_PARENT_OPERATION_IDS`、`YIZHUAN_SEQUENCE` 传递；调用结束恢复旧值，避免继承到新任务。关联标识只能是随机 UUID，不包含用户提问、关键词或任何业务内容。关闭 telemetry 时不要额外执行统计任务 start/finish；旧版本 CLI 不支持这些参数时正常使用业务命令，关联标为未知，不捏造路径。
+
+统计和用户解释统一使用“作品查询”“作者查询”“内容提取”“一键检测”等中文功能名称。命令名和内部标识只用于实现，不作为面向用户的功能名称。

package/resources/yizhuan-cli/manifest.json

@@ -1,14 +1,14 @@
 {
   "schemaVersion": 1,
   "name": "yizhuan-cli",
-  "version": "0.1.16",
-  "compatibleCliVersion": "0.1.16",
-  "source": "npm:@yizhuan-cli/cli@0.1.16",
+  "version": "0.1.17-beta.2",
+  "compatibleCliVersion": "0.1.17-beta.2",
+  "source": "npm:@yizhuan-cli/cli@0.1.17-beta.2",
   "digestAlgorithm": "sha256",
   "files": [
     {
       "path": "SKILL.md",
-      "sha256": "b58b68be1bd53fb3c9c572e8ccefcf000ad837c4f54d5269959d23f2c12150d4"
+      "sha256": "c19151583a93ae02008f1ff30b13d1ae2ed71ec143f9ef7b0ed47ac2648a18e6"
     }
   ]
 }

package/src/index.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url'
 import { getConfigPath, maskApiKey, runConfigInit } from './config.js'
 import { runSkillSync } from './skill.js'
 import { runDoctor } from './doctor.js'
+import { USAGE_FLAGS, usageHeaders, runUsageTask } from './usage.js'
 
 const CLI_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 const PACKAGE_PATH = path.join(CLI_DIR, 'package.json')
@@ -64,6 +65,8 @@ Usage:
   yizhuan config show
   yizhuan skill sync [--global] [--host <name>] [--repair]
   yizhuan doctor [--json]
+  yizhuan task start [--task-id <uuid>] [--goal-feature-ids <功能标识列表>]
+  yizhuan task finish --task-id <uuid> [--status completed|failed|cancelled]
 
 Examples:
   yizhuan execute --ability works --query "百家号昨天新增了哪些作品"
@@ -103,6 +106,12 @@ Abilities:
 Config:
   ${CONFIG_PATH}
   可通过环境变量 YIZHUAN_CONFIG_PATH 指定独立配置文件
+  YIZHUAN_TRIGGER=user_initiated 标识用户主动请求，automated 标识自动任务；未设置为 unknown
+  YIZHUAN_TELEMETRY=0 关闭使用元数据埋点
+  YIZHUAN_TASK_ID=<uuid> 关联同一次用户任务，新的目标使用新 ID
+  YIZHUAN_OPERATION_ID=<uuid> 标识一次操作，技术重试复用，新操作更换
+  YIZHUAN_PARENT_OPERATION_IDS=<uuid,...> 声明实际使用的前序输出，不能只按时间猜测
+  YIZHUAN_SEQUENCE=<整数> 声明任务顺序；也支持 --task-id / --operation-id / --parent-operation-ids / --sequence
 `)
 }
 
@@ -238,6 +247,8 @@ function buildRequestHeaders(config) {
     'content-type': 'application/json',
     'x-device-type': 'pc',
     'x-yizhuan-cli-version': readPackageVersion(),
+    'x-yizhuan-trigger': ['user_initiated', 'automated'].includes(process.env.YIZHUAN_TRIGGER)
+      ? process.env.YIZHUAN_TRIGGER : 'unknown',
     'x-yizhuan-telemetry': config.telemetryEnabled ? '1' : '0'
   }
 }
@@ -451,7 +462,7 @@ async function execute(args) {
   assertCommandArgs(
     args,
     'execute',
-    new Set(['ability', 'query', 'params', 'jsonFile', ...PARAM_FLAG_KEYS])
+    new Set(['ability', 'query', 'params', 'jsonFile', ...PARAM_FLAG_KEYS, ...USAGE_FLAGS])
   )
   const ability = args.ability
   if (!ABILITIES.has(ability)) {
@@ -460,9 +471,10 @@ async function execute(args) {
 
   const requestParams = buildExecuteParams(args)
   const config = readConfig()
+  const requestHeaders = { ...buildRequestHeaders(config), ...usageHeaders(args) }
   const response = await fetch(`${config.apiBaseUrl}/api/cli.execute`, {
     method: 'POST',
-    headers: buildRequestHeaders(config),
+    headers: requestHeaders,
     body: JSON.stringify({
       json: {
         ability,
@@ -494,7 +506,7 @@ async function execute(args) {
       if (Date.now() >= deadline) break
       const poll = await fetch(`${config.apiBaseUrl}/api/cli.execute`, {
         method: 'POST',
-        headers: buildRequestHeaders(config),
+        headers: { ...requestHeaders, 'x-yizhuan-trigger': 'polling' },
         body: JSON.stringify({
           json: { ability: 'detection', params: { mode: 'get', id: result.data.id } }
         })
@@ -530,7 +542,7 @@ function renderQuery(payload, format) {
 }
 
 async function query(args) {
-  assertCommandArgs(args, 'query', new Set(['json', 'jsonFile', 'params', 'format']))
+  assertCommandArgs(args, 'query', new Set(['json', 'jsonFile', 'params', 'format', ...USAGE_FLAGS]))
   const jsonText = args.jsonFile
     ? fs.readFileSync(path.resolve(String(args.jsonFile)), 'utf8')
     : args.json === '-'
@@ -541,7 +553,7 @@ async function query(args) {
   const config = readConfig()
   const response = await fetch(`${config.apiBaseUrl}/api/agent.query`, {
     method: 'POST',
-    headers: buildRequestHeaders(config),
+    headers: { ...buildRequestHeaders(config), ...usageHeaders(args) },
     body: JSON.stringify({ json: request })
   })
   const text = await response.text()
@@ -606,6 +618,12 @@ async function main() {
     await execute(args)
     return
   }
+  if (command === 'task') {
+    assertCommandArgs(args, 'task', new Set(['taskId', 'status', 'goalFeatureIds']), 2)
+    const config = readConfig()
+    await runUsageTask(args, config, buildRequestHeaders(config))
+    return
+  }
   if (command === 'query') {
     await query(args)
     return

package/src/usage.js

@@ -0,0 +1,60 @@
+import { randomUUID } from 'node:crypto'
+
+export const USAGE_FLAGS = ['taskId', 'operationId', 'parentOperationIds', 'sequence']
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+export function usageHeaders(args = {}, env = process.env) {
+  const values = {
+    taskId: args.taskId ?? env.YIZHUAN_TASK_ID,
+    operationId: args.operationId ?? env.YIZHUAN_OPERATION_ID ?? randomUUID(),
+    parentOperationIds: args.parentOperationIds ?? env.YIZHUAN_PARENT_OPERATION_IDS,
+    sequence: args.sequence ?? env.YIZHUAN_SEQUENCE
+  }
+  for (const field of ['taskId', 'operationId'])
+    if (values[field] !== undefined && !uuid.test(String(values[field])))
+      throw new Error(`${field} 必须是 UUID，不能使用用户提问或业务内容`)
+  const parents = values.parentOperationIds
+    ? String(values.parentOperationIds).split(',').filter(Boolean)
+    : []
+  if (parents.length > 20 || parents.some((id) => !uuid.test(id)))
+    throw new Error('parentOperationIds 必须是最多20个逗号分隔的 UUID')
+  if (parents.length && !values.taskId) throw new Error('关联前序操作必须同时提供 taskId')
+  if (
+    values.sequence !== undefined &&
+    (!/^\d+$/.test(String(values.sequence)) || Number(values.sequence) > 1000000)
+  )
+    throw new Error('sequence 必须是0到1000000之间的整数')
+  return {
+    'x-yizhuan-operation-id': String(values.operationId),
+    ...(values.taskId ? { 'x-yizhuan-task-id': String(values.taskId) } : {}),
+    ...(parents.length
+      ? { 'x-yizhuan-parent-operation-ids': [...new Set(parents)].join(',') }
+      : {}),
+    ...(values.sequence !== undefined ? { 'x-yizhuan-sequence': String(values.sequence) } : {})
+  }
+}
+
+export async function runUsageTask(args, config, headers) {
+  const action = args._[1]
+  const taskId =
+    args.taskId ?? process.env.YIZHUAN_TASK_ID ?? (action === 'start' ? randomUUID() : undefined)
+  if (!taskId || !uuid.test(taskId))
+    throw new Error('需要 UUID 格式的 --task-id 或 YIZHUAN_TASK_ID')
+  if (!['start', 'finish'].includes(action)) throw new Error('task 支持 start 或 finish')
+  const status = args.status ?? 'completed'
+  if (action === 'finish' && !['completed', 'failed', 'cancelled'].includes(status))
+    throw new Error('status 支持 completed、failed、cancelled')
+  const goalFeatureIds = args.goalFeatureIds ? String(args.goalFeatureIds).split(',') : undefined
+  const response = await fetch(
+    `${config.apiBaseUrl}/api/cli.${action === 'start' ? 'startUsageTask' : 'finishUsageTask'}`,
+    {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        json: action === 'start' ? { taskId, goalFeatureIds } : { taskId, status }
+      })
+    }
+  )
+  const payload = await response.json()
+  if (!response.ok) throw new Error(`任务统计请求失败 HTTP ${response.status}`)
+  console.log(JSON.stringify({ taskId, ...(payload.result?.data?.json ?? payload) }, null, 2))
+}