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

package/README.md

@@ -36,6 +36,8 @@ yizhuan config path
 yizhuan config show
 yizhuan execute --ability membership
 yizhuan execute --ability works --query "百家号昨天新增了哪些作品"
+yizhuan execute --ability works --params '{"mode":"comments","platform":"douyin","workId":"123456","count":20}'
+yizhuan execute --ability works --params '{"mode":"comments","platform":"douyin","title":"作品标题","count":20}'
 yizhuan execute --ability hot_topics --platform douyin
 yizhuan execute --ability hot_topics --params '{"platform":"douyin"}'
 yizhuan execute --ability accounts --params '{"mode":"public_search","platform":"toutiao","keyword":"张三"}'
@@ -72,6 +74,9 @@ yizhuan execute --ability hot_topics --params "{\"platform\":\"douyin\"}"
 ## 支持的典型能力
 
 - 作品查询：`yizhuan execute --ability works --query "AI 相关的热门作品有哪些"`
+- 作品评论：`yizhuan execute --ability works --params '{"mode":"comments","platform":"douyin","workId":"123456","count":20}'`
+- 按标题查询评论：`yizhuan execute --ability works --params '{"mode":"comments","platform":"douyin","title":"作品标题"}'`；标题必须唯一匹配，多个候选时 CLI 会要求补充条件。
+- 微信公众号/视频号评论：`yizhuan execute --ability works --params '{"mode":"comments","platform":"weixin","workId":"https://mp.weixin.qq.com/s/文章链接","count":20}'`；这两个平台的 `workId` 使用作品链接。
 - 作者查询：`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":"张三"}'`
@@ -82,6 +87,8 @@ yizhuan execute --ability hot_topics --params "{\"platform\":\"douyin\"}"
 - 竞品动态筛选：`yizhuan execute --ability radar --params '{"mode":"timeline","timeRange":"7d","platform":"baijiahao","keyword":"AI"}'`
 - 取消关注雷达作者：先查询关注列表拿到 `articleId`，再执行 `yizhuan execute --ability radar --params '{"mode":"unfollow","articleId":"205169870"}'`
 - 会员查询：`yizhuan execute --ability membership --query "我的会员什么时候到期"`
+- 内容提取：`yizhuan execute --ability content_extract --url "https://example.com/article"`
+- 易撰作品内容提取：`yizhuan execute --ability content_extract --params '{"contentId":12345}'`
 
 如果你是通过 Codex、Cursor、Claude Code 这类 Agent 使用 CLI，也可以直接用自然语言提问，例如：
 
@@ -90,3 +97,5 @@ yizhuan execute --ability hot_topics --params "{\"platform\":\"douyin\"}"
 - `查询 AI 相关的热门文章`
 - `取消关注陈某某先生`
 - `我的会员什么时候到期`
+
+纯创作请求（例如“写一篇中秋文章”）由当前 Agent 完成，不调用 `content_extract`；CLI 只提供真实内容素材，不负责生成、改写或发布。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yizhuan-cli/cli",
-  "version": "0.1.16-beta.2",
+  "version": "0.1.17-beta.0",
   "description": "易撰命令行工具，用于通过 API Key 查询易撰真实数据。",
   "private": false,
   "type": "module",

package/resources/yizhuan-cli/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: yizhuan-cli
 description: |
-  安装、配置并使用易撰 CLI（yizhuan 命令）查询真实数据的全量 Skill，处理作品、作者、全网搜索、热点、竞品动态、会员、灵感、收藏和一键检测；若已安装用户明确指定平台对应的 yizhuan-<platform> Skill，必须优先使用对应的拆分平台 Skill。业务数据禁止臆造。
+  安装、配置并使用易撰 CLI（yizhuan 命令）查询真实数据、提取文章/视频/图文内容的全量 Skill；若已安装用户明确指定平台对应的 yizhuan-<platform> Skill，必须优先使用对应的拆分平台 Skill。业务数据禁止臆造，文章创作由当前 Agent 完成。
 ---
 
 # 易撰 CLI
@@ -40,6 +40,9 @@ yizhuan doctor
 | 配置状态 | `yizhuan config show` |
 | 作品 | `yizhuan execute --ability works --query "百家号昨天新增了哪些作品"` |
 | 作品检索 | `yizhuan execute --ability works --params '{"mode":"search","keyword":"AI"}'` |
+| 作品评论（明确 ID） | `yizhuan execute --ability works --params '{"mode":"comments","platform":"douyin","workId":"123456","count":20}'` |
+| 作品评论（按标题定位） | `yizhuan execute --ability works --params '{"mode":"comments","platform":"douyin","title":"作品标题"}'` |
+| 微信公众号/视频号评论 | `yizhuan execute --ability works --params '{"mode":"comments","platform":"weixin","workId":"https://mp.weixin.qq.com/s/文章链接","count":20}'` |
 | 指定作者作品 | `yizhuan query --json '{"intent":"works_search","scope":"public","platform":"toutiao","authorName":"大名府名人","timeRange":"3d"}'` |
 | 高级作品筛选 | `yizhuan query --json '{"intent":"works_search","scope":"public","platform":"weibo","categories":["娱乐","情感"],"content_type":"video","min_views":100000,"min_comments":10000,"sort_by":"views","order":"desc"}'` |
 | 作者查询 | `yizhuan execute --ability accounts --query "张三"` |
@@ -53,10 +56,14 @@ yizhuan doctor
 | 会员 | `yizhuan execute --ability membership` |
 | 我的灵感 / 灵感库 / 收藏作品 | `yizhuan execute --ability favorites` |
 | 一键检测 | 将标题和正文写入临时 JSON 文件后执行 `yizhuan execute --ability detection --json-file <file>` |
+| 提取文章/视频/图文 | `yizhuan execute --ability content_extract --params '{"url":"https://..."}'` |
 
 ## 调用规则
 
 - 需要真实易撰数据时必须调用 CLI，不直接猜测结果。
+- 用户只说“写一篇中秋文章”等纯创作请求时，不调用 CLI，由当前 Agent 直接创作。
+- 用户要求提取文章正文、视频口播文字或图文素材时，使用 `content_extract`；来源可以是 `url` 或易撰 `contentId`。
+- 用户要求“根据易撰热门内容创作”时，先调用查询/提取能力获取真实素材，再由当前 Agent 完成创作；CLI 不生成、改写、生成标题或发布内容。
 - 一键检测的原创度检测当前只有百度引擎。展示检测结果时使用 `data.originalScore` 和 `data.originalEngine`；不得把历史兼容字段 `_360`、`sogou`、`zonghe` 展示为检测引擎或额外得分。
 - 一键检测支持 `submit`、`get` 和 `wait` 模式。`wait` 必须按照服务端 `pollAfterSeconds` 轮询；pending、failed、timeout 状态必须如实报告，成功、失败或超时后均清理包含标题和正文的临时 JSON 文件。
 - PowerShell 使用单引号包裹 JSON。终端可能改写引号时，将不含密钥的请求对象写入文件，再使用 `--json-file`。
@@ -71,6 +78,10 @@ yizhuan doctor
 - 关注公开作者时，先用 `author_search` 取得并选定完整作者资料，再调用 `accounts` 的 `mode=follow_public_author`；必须传该结果的 `platform`、`extAuthorId` 和 `nickname`。`nickname` 必须是公开搜索结果中的作者名称，绝不能将 `extAuthorId` 作为名称写入。
 - 公开作者结果中的 `workCount: 0` 可能是上游未返回作品数后的缺省值，不代表作者没有作品；是否有作品必须以 `works_search` 的结果为准。
 - 作品复合筛选优先使用统一协议 `intent=works_search`。平台使用 `platform`，分类使用 `categories`，内容类型使用 `content_type`，最低阅读/播放和评论分别使用 `min_views`、`min_comments`；需要固定顺序时显式传 `sort_by` 和 `order`。不得把作品查询改成作者、雷达或热点查询。
+- 查询作品评论使用 `works` 的 `mode=comments`。有明确平台作品 ID 时传 `platform` + `workId`；只有作品标题时传 `platform` + `title`，CLI 会先检索作品，只有标题唯一匹配且能解析平台作品 ID 才继续查询。多个候选返回 `AMBIGUOUS_WORK`，不得自行猜测。
+- 微信公众号和微信视频号评论通过登录采集机获取，平台分别传 `weixin`/`wxgzh` 和 `wxsph`/`视频号`，`workId` 必须是作品链接；这两个平台暂不支持 `cursor` 和 `parentId`。
+- 作品评论默认返回一页、最多 50 条，未传 `count` 时按 20 条处理。需要继续翻页时，必须将上一页返回的 `data.cursor` 原样传回，依据 `data.hasMore` 停止；不得把评论数 `metrics.commentCount` 当作评论正文，也不得声称结果是“最新”或“热门”。
+- 作品评论返回 `data.items[].text`、`user`、`likeCount`、`replyCount`、`ipLabel`、`createdAt` 等字段。查询评论回复时可额外传 `parentId`。评论发布、删除、点赞不属于本 Skill 能力。
 - 当前 CLI 不支持按单篇作品 URL 或平台侧 `articleId` 精确查询作品详情。用户提供作品链接或文章 ID 时，直接说明该能力暂不支持；不得将完整链接或纯文章 ID 改作 `keyword` 搜索，也不得把这种搜索返回的 `empty` 解读为全网不存在该作品。
 - 作品查询返回后必须逐项核对用户要求的分类、类型和指标阈值；低于阈值或缺少必要指标的项目不得作为符合条件的结果展示，也不得擅自放宽条件。展示总数必须使用返回的 `data.total`，不能把当前页条数当成总数。
 - 作者累计指标筛选使用 `author_query`，不得改成作品指标或擅自降低阈值。必须逐项映射用户给出的所有条件：粉丝使用 `min_follower` / `max_follower`，点赞使用 `min_total_likes` / `max_total_likes`，阅读使用 `min_total_views` / `max_total_views`，关注使用 `min_friends` / `max_friends`，作品数使用 `min_work_count` / `max_work_count`；复合条件不得遗漏任何字段。例如“百家号粉丝大于50万，点赞大于10万”必须同时传 `platform_id:2`、`min_follower:500000` 和 `min_total_likes:100000`。

package/resources/yizhuan-cli/manifest.json

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

package/src/doctor.js

@@ -210,7 +210,7 @@ export function inspectSkill(
     }
     return check('pass', 'skill', `正式 Skill ${metadata.version} 来源和摘要有效：${resolved.target}`)
   } catch (error) {
-    return check('fail', 'skill', `正式 Skill 校验失败：${error.message}`, '保留冲突内容并人工确认，或移走后重新运行 skill sync。')
+    return check('fail', 'skill', `正式 Skill 校验失败：${error.message}`, '人工确认后运行 yizhuan skill sync --repair，或移走冲突内容后重新同步。')
   }
 }
 

package/src/index.js

@@ -26,7 +26,8 @@ const ABILITIES = new Set([
   'work_query',
   'membership_info',
   'favorites_query',
-  'detection'
+  'detection',
+  'content_extract'
 ])
 
 const PARAM_FLAG_KEYS = [
@@ -43,7 +44,9 @@ const PARAM_FLAG_KEYS = [
   'authorId',
   'extAuthorId',
   'collectionType',
-  'metric'
+  'metric',
+  'url', 'contentType', 'contentId', 'content_id', 'platformCode', 'platform_code',
+  'outputFormat', 'output_format', 'includeImages', 'includeTranscriptSegments', 'source'
 ]
 
 function printHelp() {
@@ -59,17 +62,20 @@ Usage:
   yizhuan config init [--api-key-stdin] [--api-base-url <url>] [--force]
   yizhuan config path
   yizhuan config show
-  yizhuan skill sync [--global]
+  yizhuan skill sync [--global] [--host <name>] [--repair]
   yizhuan doctor [--json]
 
 Examples:
   yizhuan execute --ability works --query "百家号昨天新增了哪些作品"
+  yizhuan execute --ability works --params '{"mode":"comments","platform":"douyin","workId":"123456","count":20}'
+  yizhuan execute --ability works --params '{"mode":"comments","platform":"douyin","title":"作品标题","count":20}'
   yizhuan execute --ability hot_topics --platform douyin
   yizhuan execute --ability hot_topics --params '{"platform":"douyin"}'
   yizhuan execute --ability accounts --params '{"mode":"public_search","platform":"toutiao","keyword":"张三"}'
   yizhuan execute --ability radar --params '{"mode":"following"}'
   yizhuan execute --ability radar --mode timeline --timeRange 7d
   yizhuan execute --ability detection --json-file detection.json
+  yizhuan execute --ability content_extract --url "https://example.com/article"
   yizhuan execute --ability radar --params '{"mode":"unfollow","articleId":"205169870"}'
 
 Notes:
@@ -92,6 +98,7 @@ Abilities:
   public_author_search  作者全网搜索，兼容低层能力
   public_work_search    作品全网搜索，兼容低层能力
   detection             一键检测（原创/风险）
+  content_extract       提取文章、视频和图文内容
 
 Config:
   ${CONFIG_PATH}
@@ -220,7 +227,18 @@ function readConfig() {
 
   return {
     apiBaseUrl: String(config.apiBaseUrl).replace(/\/+$/, ''),
-    apiKey: String(config.apiKey)
+    apiKey: String(config.apiKey),
+    telemetryEnabled: process.env.YIZHUAN_TELEMETRY !== '0'
+  }
+}
+
+function buildRequestHeaders(config) {
+  return {
+    authorization: config.apiKey,
+    'content-type': 'application/json',
+    'x-device-type': 'pc',
+    'x-yizhuan-cli-version': readPackageVersion(),
+    'x-yizhuan-telemetry': config.telemetryEnabled ? '1' : '0'
   }
 }
 
@@ -235,7 +253,16 @@ function stripWrappingQuotes(text) {
   return value
 }
 
-const OPAQUE_ID_KEYS = new Set(['extAuthorId', 'ext_author_id', 'author_id'])
+// Platform work IDs can exceed Number.MAX_SAFE_INTEGER (Douyin aweme IDs are
+// commonly 19 digits). Keep them opaque even when params use loose key=value
+// parsing; JSON input already preserves quoted strings.
+const OPAQUE_ID_KEYS = new Set([
+  'extAuthorId',
+  'ext_author_id',
+  'author_id',
+  'workId',
+  'work_id'
+])
 
 function coerceScalar(value, key) {
   const text = stripWrappingQuotes(value).replace(/\\_/g, '_').trim()
@@ -323,6 +350,65 @@ function assignFlagParams(params, args) {
   return params
 }
 
+const AUTHOR_RANKING_METRICS = [
+  {
+    key: 'friendsCount',
+    label: '关注数',
+    patterns: [/关注/, /friends(?:Count|_count)?/i]
+  },
+  {
+    key: 'followerCount',
+    label: '粉丝数',
+    patterns: [/粉丝/, /follower(?:Count|_count)?/i]
+  },
+  {
+    key: 'totalViews',
+    label: '阅读数',
+    patterns: [/阅读|播放/, /(?:total)?views?/i]
+  },
+  {
+    key: 'totalLikes',
+    label: '点赞数',
+    patterns: [/点赞/, /(?:total)?likes?/i]
+  }
+]
+
+function rankingMetric(query, params) {
+  const text = [
+    query,
+    params?.metric,
+    params?.sortBy,
+    params?.sort_by,
+    params?.order
+  ].filter(Boolean).join(' ')
+  if (!/(最高|最多|最大|第一|排行|排名|top)/i.test(text)) return undefined
+  return AUTHOR_RANKING_METRICS.find((metric) => metric.patterns.some((pattern) => pattern.test(text)))
+}
+
+export function annotateUnavailableAuthorRanking(result, { query, params } = {}) {
+  const metric = rankingMetric(query, params)
+  const items = result?.data?.items
+  if (!metric || !Array.isArray(items) || items.length === 0) return result
+
+  const allValuesAreZero = items.every((item) => Number(item?.[metric.key]) === 0)
+  if (!allValuesAreZero) return result
+
+  const message = `查询到的作者${metric.label}均为 0，无法据此排序或判断最高作者`
+  return {
+    ...result,
+    message: result.message || message,
+    data: {
+      ...result.data,
+      ranking: {
+        metric: metric.key,
+        status: 'unavailable',
+        reason: 'all_returned_values_zero',
+        message
+      }
+    }
+  }
+}
+
 export function buildExecuteParams(args) {
   if (args.jsonFile) {
     const conflictingKeys = ['params', 'query', ...PARAM_FLAG_KEYS].filter(
@@ -372,19 +458,16 @@ async function execute(args) {
     throw new Error(`未知 ability：${ability || ''}，请执行 yizhuan --help 查看可用能力`)
   }
 
+  const requestParams = buildExecuteParams(args)
   const config = readConfig()
   const response = await fetch(`${config.apiBaseUrl}/api/cli.execute`, {
     method: 'POST',
-    headers: {
-      authorization: config.apiKey,
-      'content-type': 'application/json',
-      'x-device-type': 'pc'
-    },
+    headers: buildRequestHeaders(config),
     body: JSON.stringify({
       json: {
         ability,
         query: typeof args.query === 'string' ? args.query : undefined,
-        params: buildExecuteParams(args)
+        params: requestParams
       }
     })
   })
@@ -395,7 +478,6 @@ async function execute(args) {
   }
 
   let result = payloadResult(JSON.parse(text))
-  const requestParams = buildExecuteParams(args)
   if (
     ability === 'detection' &&
     requestParams?.wait === true &&
@@ -412,11 +494,7 @@ async function execute(args) {
       if (Date.now() >= deadline) break
       const poll = await fetch(`${config.apiBaseUrl}/api/cli.execute`, {
         method: 'POST',
-        headers: {
-          authorization: config.apiKey,
-          'content-type': 'application/json',
-          'x-device-type': 'pc'
-        },
+        headers: buildRequestHeaders(config),
         body: JSON.stringify({
           json: { ability: 'detection', params: { mode: 'get', id: result.data.id } }
         })
@@ -426,6 +504,10 @@ async function execute(args) {
       result = payloadResult(JSON.parse(pollText))
     }
   }
+  result = annotateUnavailableAuthorRanking(result, {
+    query: typeof args.query === 'string' ? args.query : undefined,
+    params: requestParams
+  })
   console.log(JSON.stringify(result, null, 2))
 }
 
@@ -459,18 +541,16 @@ async function query(args) {
   const config = readConfig()
   const response = await fetch(`${config.apiBaseUrl}/api/agent.query`, {
     method: 'POST',
-    headers: {
-      authorization: config.apiKey,
-      'content-type': 'application/json',
-      'x-device-type': 'pc'
-    },
+    headers: buildRequestHeaders(config),
     body: JSON.stringify({ json: request })
   })
   const text = await response.text()
   if (!response.ok) throw new Error(`请求失败 HTTP ${response.status}：${text}`)
-  console.log(
-    renderQuery(JSON.parse(text).result?.data?.json ?? JSON.parse(text), args.format || 'json')
-  )
+  const result = annotateUnavailableAuthorRanking(payloadResult(JSON.parse(text)), {
+    query: request.query || request.keyword,
+    params: request
+  })
+  console.log(renderQuery(result, args.format || 'json'))
 }
 
 async function main() {
@@ -510,7 +590,7 @@ async function main() {
   }
 
   if (command === 'skill' && args._[1] === 'sync') {
-    assertCommandArgs(args, 'skill sync', new Set(['global', 'host', 'help']), 2)
+    assertCommandArgs(args, 'skill sync', new Set(['global', 'host', 'repair', 'help']), 2)
     await runSkillSync(args)
     return
   }

package/src/skill.js

@@ -90,7 +90,7 @@ export function loadOfficialSkill(resourceDir = DEFAULT_RESOURCE_DIR) {
   return { manifest, resourceDir }
 }
 
-export function readSkillMetadata(target) {
+export function readSkillMetadata(target, { allowModified = false } = {}) {
   const metadataPath = path.join(target, SKILL_METADATA_FILE)
   if (!fs.existsSync(metadataPath)) {
     throw new Error(`目标存在未受易撰管理的同名内容，已停止同步：${target}`)
@@ -111,7 +111,7 @@ export function readSkillMetadata(target) {
   }
   for (const file of metadata.files) {
     const installedPath = safeResourcePath(target, file.path)
-    if (!fs.existsSync(installedPath) || sha256File(installedPath) !== file.sha256) {
+    if (!allowModified && (!fs.existsSync(installedPath) || sha256File(installedPath) !== file.sha256)) {
       throw new Error(`已安装 Skill 包含未知修改，已停止覆盖：${file.path}`)
     }
   }
@@ -182,14 +182,15 @@ export function syncOfficialSkill(
   {
     loadBundle = loadOfficialSkill,
     installBundle = installStagedSkill,
-    now = () => new Date()
+    now = () => new Date(),
+    repair = false
   } = {}
 ) {
   const bundle = loadBundle()
   const { manifest } = bundle
   let installed
   if (fs.existsSync(resolved.target)) {
-    installed = readSkillMetadata(resolved.target)
+    installed = readSkillMetadata(resolved.target, { allowModified: repair })
     const comparison = compareVersions(installed.version, manifest.version)
     if (comparison > 0) {
       return { action: 'newer', metadata: installed, target: resolved.target }
@@ -257,11 +258,12 @@ export function resolveSkillTarget(
 
 export function printSkillSyncHelp() {
   console.log(`Usage:
-  yizhuan skill sync [--global] [--host <name>]
+  yizhuan skill sync [--global] [--host <name>] [--repair]
 
 Options:
   --global  安装到当前受支持宿主的用户级 Skill 目录
   --host    明确指定 codex、agents、trae、claude 或 cursor
+  --repair  仅覆盖带官方托管元数据但内容校验失败的 Skill
   --help    显示本帮助`)
 }
 
@@ -272,7 +274,7 @@ export async function runSkillSync(args) {
   }
 
   const resolved = resolveSkillTarget({ global: Boolean(args.global), host: args.host })
-  const result = syncOfficialSkill(resolved)
+  const result = syncOfficialSkill(resolved, { repair: Boolean(args.repair) })
   const actionText = {
     installed: '已安装',
     updated: '已更新',