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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yizhuan-cli/cli",
-  "version": "0.1.17-beta.1",
+  "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

@@ -124,3 +124,13 @@ try {
 ```
 
 只有元数据参与使用统计，不额外上传用户问题、关键词、链接或正文。尊重用户现有的 `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.17-beta.1",
-  "compatibleCliVersion": "0.1.17-beta.1",
-  "source": "npm:@yizhuan-cli/cli@0.1.17-beta.1",
+  "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": "f5d8858b7377e3afabc394bf2aab72ffce7b7cee60864d0d97d86549d68fd70b"
+      "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 "百家号昨天新增了哪些作品"
@@ -105,6 +108,10 @@ Config:
   可通过环境变量 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
 `)
 }
 
@@ -455,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)) {
@@ -464,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,
@@ -498,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), 'x-yizhuan-trigger': 'polling' },
+        headers: { ...requestHeaders, 'x-yizhuan-trigger': 'polling' },
         body: JSON.stringify({
           json: { ability: 'detection', params: { mode: 'get', id: result.data.id } }
         })
@@ -534,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 === '-'
@@ -545,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()
@@ -610,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))
+}