yuanflow-cli 0.1.3 → 0.1.5

package/README.md

@@ -29,15 +29,40 @@ yuanflow-cli douyin video-detail "https://v.douyin.com/xxx/" --format agent-json
 yuanflow-cli shortcuts douyin
 yuanflow-cli commands list
 yuanflow-cli schema douyin.video-detail
+yuanflow-cli schema comments.douyin.comments
+yuanflow-cli comments collect --platform douyin --target "https://v.douyin.com/xxx/" --format agent-json
 yuanflow-cli list douyin
 ```
 
 环境变量：
 
 ```bash
-YUANFLOW_TOKEN=<你的令牌>
+YUANCHUANG_API_TOKEN=<你的令牌>
 ```
 
+token 优先级：`--token` > `YUANCHUANG_API_TOKEN` > 本地 `config.token`。独立 CLI 用户可以使用环境变量或 `config set-token`；在 YuanFlow 主程序内使用时，token 由主程序认证系统注入，不需要手动配置。
+
+### 作品评论采集
+
+评论采集统一走 `comments collect`，用于把 Agent 的自然语言需求稳定映射到平台评论接口：
+
+```bash
+yuanflow-cli comments collect --platform douyin --target "https://v.douyin.com/xxx/" --format agent-json
+yuanflow-cli comments collect --platform xiaohongshu --target note_id --action replies --comment-id root_comment_id --format agent-json
+yuanflow-cli comments collect --platform youtube --target video_id --action comments --dry-run --format agent-json
+```
+
+常用参数：
+
+- `--platform`：平台标识，如 `douyin`、`xiaohongshu`、`bilibili`、`wechat_mp`、`tiktok`、`instagram`、`kuaishou`、`reddit`、`twitter`、`weibo`、`youtube`、`zhihu`。
+- `--action`：评论类型，默认 `comments`，可选 `replies`、`post_comments`、`post_replies`。
+- `--target`：作品、文章、帖子、视频或回答 ID，也可以传支持的平台链接。
+- `--comment-id`：采集二级评论或评论回复时使用。
+- `--prefer fallback`：使用备用接口。
+- `--dry-run`：只预览请求映射，不发起真实接口请求，也不要求 token。
+
+Agent 可以先用 `yuanflow-cli commands list` 查看全部命令，再用 `yuanflow-cli schema comments.douyin.comments` 查看某个评论采集命令的参数、接口路径和返回说明。
+
 ## Skill 安装器
 
 ```bash

package/lib/skill-installer/agents.cjs

@@ -22,8 +22,15 @@ function defaultExists(targetPath) {
   return fs.existsSync(targetPath);
 }
 
+function joinTargetPath(baseDir, ...segments) {
+  if (typeof baseDir === 'string' && baseDir.startsWith('/')) {
+    return path.posix.join(baseDir, ...segments);
+  }
+  return path.join(baseDir, ...segments);
+}
+
 function getConfigHome(homeDir, env) {
-  return (env && env.XDG_CONFIG_HOME) || path.join(homeDir, '.config');
+  return (env && env.XDG_CONFIG_HOME) || joinTargetPath(homeDir, '.config');
 }
 
 function getCanonicalSkillsDir({
@@ -37,117 +44,117 @@ function getCanonicalSkillsDir({
 
 function buildAgentDefinitions({ homeDir = os.homedir(), env = process.env } = {}) {
   const configHome = getConfigHome(homeDir, env);
-  const codexHome = (env.CODEX_HOME || '').trim() || path.join(homeDir, '.codex');
-  const claudeHome = (env.CLAUDE_CONFIG_DIR || '').trim() || path.join(homeDir, '.claude');
+  const codexHome = (env.CODEX_HOME || '').trim() || joinTargetPath(homeDir, '.codex');
+  const claudeHome = (env.CLAUDE_CONFIG_DIR || '').trim() || joinTargetPath(homeDir, '.claude');
 
   return {
     codex: {
       name: 'codex',
       displayName: 'Codex',
       projectSkillsDir: '.agents/skills',
-      globalSkillsDir: path.join(codexHome, 'skills'),
+      globalSkillsDir: joinTargetPath(codexHome, 'skills'),
       markers: [codexHome],
     },
     'claude-code': {
       name: 'claude-code',
       displayName: 'Claude Code',
       projectSkillsDir: '.claude/skills',
-      globalSkillsDir: path.join(claudeHome, 'skills'),
+      globalSkillsDir: joinTargetPath(claudeHome, 'skills'),
       markers: [claudeHome],
     },
     cursor: {
       name: 'cursor',
       displayName: 'Cursor',
       projectSkillsDir: '.agents/skills',
-      globalSkillsDir: path.join(homeDir, '.cursor', 'skills'),
-      markers: [path.join(homeDir, '.cursor')],
+      globalSkillsDir: joinTargetPath(homeDir, '.cursor', 'skills'),
+      markers: [joinTargetPath(homeDir, '.cursor')],
     },
     trae: {
       name: 'trae',
       displayName: 'Trae',
       projectSkillsDir: '.trae/skills',
-      globalSkillsDir: path.join(homeDir, '.trae', 'skills'),
-      markers: [path.join(homeDir, '.trae')],
+      globalSkillsDir: joinTargetPath(homeDir, '.trae', 'skills'),
+      markers: [joinTargetPath(homeDir, '.trae')],
     },
     opencode: {
       name: 'opencode',
       displayName: 'OpenCode',
       projectSkillsDir: '.agents/skills',
-      globalSkillsDir: path.join(configHome, 'opencode', 'skills'),
-      markers: [path.join(configHome, 'opencode')],
+      globalSkillsDir: joinTargetPath(configHome, 'opencode', 'skills'),
+      markers: [joinTargetPath(configHome, 'opencode')],
     },
     'github-copilot': {
       name: 'github-copilot',
       displayName: 'GitHub Copilot',
       projectSkillsDir: '.agents/skills',
-      globalSkillsDir: path.join(homeDir, '.copilot', 'skills'),
-      markers: [path.join(homeDir, '.copilot')],
+      globalSkillsDir: joinTargetPath(homeDir, '.copilot', 'skills'),
+      markers: [joinTargetPath(homeDir, '.copilot')],
     },
     'gemini-cli': {
       name: 'gemini-cli',
       displayName: 'Gemini CLI',
       projectSkillsDir: '.agents/skills',
-      globalSkillsDir: path.join(homeDir, '.gemini', 'skills'),
-      markers: [path.join(homeDir, '.gemini')],
+      globalSkillsDir: joinTargetPath(homeDir, '.gemini', 'skills'),
+      markers: [joinTargetPath(homeDir, '.gemini')],
     },
     'kimi-cli': {
       name: 'kimi-cli',
       displayName: 'Kimi Code CLI',
       projectSkillsDir: '.agents/skills',
-      globalSkillsDir: path.join(configHome, 'agents', 'skills'),
-      markers: [path.join(homeDir, '.kimi')],
+      globalSkillsDir: joinTargetPath(configHome, 'agents', 'skills'),
+      markers: [joinTargetPath(homeDir, '.kimi')],
     },
     windsurf: {
       name: 'windsurf',
       displayName: 'Windsurf',
       projectSkillsDir: '.windsurf/skills',
-      globalSkillsDir: path.join(homeDir, '.codeium', 'windsurf', 'skills'),
-      markers: [path.join(homeDir, '.codeium', 'windsurf')],
+      globalSkillsDir: joinTargetPath(homeDir, '.codeium', 'windsurf', 'skills'),
+      markers: [joinTargetPath(homeDir, '.codeium', 'windsurf')],
     },
     openclaw: {
       name: 'openclaw',
       displayName: 'OpenClaw',
       projectSkillsDir: 'skills',
-      globalSkillsDir: path.join(homeDir, '.openclaw', 'skills'),
+      globalSkillsDir: joinTargetPath(homeDir, '.openclaw', 'skills'),
       markers: [
-        path.join(homeDir, '.openclaw'),
-        path.join(homeDir, '.clawdbot'),
-        path.join(homeDir, '.moltbot'),
+        joinTargetPath(homeDir, '.openclaw'),
+        joinTargetPath(homeDir, '.clawdbot'),
+        joinTargetPath(homeDir, '.moltbot'),
       ],
       resolveGlobalSkillsDir(currentHomeDir, exists = defaultExists) {
-        if (exists(path.join(currentHomeDir, '.openclaw'))) {
-          return path.join(currentHomeDir, '.openclaw', 'skills');
+        if (exists(joinTargetPath(currentHomeDir, '.openclaw'))) {
+          return joinTargetPath(currentHomeDir, '.openclaw', 'skills');
         }
-        if (exists(path.join(currentHomeDir, '.clawdbot'))) {
-          return path.join(currentHomeDir, '.clawdbot', 'skills');
+        if (exists(joinTargetPath(currentHomeDir, '.clawdbot'))) {
+          return joinTargetPath(currentHomeDir, '.clawdbot', 'skills');
         }
-        if (exists(path.join(currentHomeDir, '.moltbot'))) {
-          return path.join(currentHomeDir, '.moltbot', 'skills');
+        if (exists(joinTargetPath(currentHomeDir, '.moltbot'))) {
+          return joinTargetPath(currentHomeDir, '.moltbot', 'skills');
         }
 
-        return path.join(currentHomeDir, '.openclaw', 'skills');
+        return joinTargetPath(currentHomeDir, '.openclaw', 'skills');
       },
     },
     'trae-cn': {
       name: 'trae-cn',
       displayName: 'Trae CN',
       projectSkillsDir: '.trae/skills',
-      globalSkillsDir: path.join(homeDir, '.trae-cn', 'skills'),
-      markers: [path.join(homeDir, '.trae-cn')],
+      globalSkillsDir: joinTargetPath(homeDir, '.trae-cn', 'skills'),
+      markers: [joinTargetPath(homeDir, '.trae-cn')],
     },
     qoder: {
       name: 'qoder',
       displayName: 'Qoder',
       projectSkillsDir: '.qoder/skills',
-      globalSkillsDir: path.join(homeDir, '.qoder', 'skills'),
-      markers: [path.join(homeDir, '.qoder')],
+      globalSkillsDir: joinTargetPath(homeDir, '.qoder', 'skills'),
+      markers: [joinTargetPath(homeDir, '.qoder')],
     },
     'qwen-code': {
       name: 'qwen-code',
       displayName: 'Qwen Code',
       projectSkillsDir: '.qwen/skills',
-      globalSkillsDir: path.join(homeDir, '.qwen', 'skills'),
-      markers: [path.join(homeDir, '.qwen')],
+      globalSkillsDir: joinTargetPath(homeDir, '.qwen', 'skills'),
+      markers: [joinTargetPath(homeDir, '.qwen')],
     },
   };
 }

package/lib/skill-installer/repo-source.cjs

@@ -104,6 +104,14 @@ function resolveLocalSkillRoot(packageRoot) {
 }
 
 async function prepareSkillSource({ packageRoot }) {
+  const localRoot = resolveLocalSkillRoot(packageRoot);
+  if (localRoot) {
+    return {
+      sourceRoot: localRoot,
+      cleanup() {},
+    };
+  }
+
   const repoConfig = readRepositoryConfig(packageRoot);
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'yuanflow-skill-'));
   const archiveFile = path.join(tempRoot, `${repoConfig.repo}-${repoConfig.ref}.tar.gz`);
@@ -131,15 +139,6 @@ async function prepareSkillSource({ packageRoot }) {
       cloneRepository({ repoConfig, targetDir: cloneDir });
       sourceRoot = resolveRepositoryRoot(cloneDir);
     } catch (gitError) {
-      const localRoot = resolveLocalSkillRoot(packageRoot);
-      if (localRoot) {
-        fs.rmSync(tempRoot, { recursive: true, force: true });
-        return {
-          sourceRoot: localRoot,
-          cleanup() {},
-        };
-      }
-
       const archiveMessage = archiveError instanceof Error ? archiveError.message : String(archiveError);
       const gitMessage = gitError instanceof Error ? gitError.message : String(gitError);
       throw new Error(`下载 skill 仓库失败。archive: ${archiveMessage}; git: ${gitMessage}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuanflow-cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "YuanFlow API CLI and skill installer for supported AI coding agents.",
   "type": "module",
   "license": "MIT",

package/skills/yuanflow-skill/SKILL.md

@@ -9,10 +9,21 @@ description: Use when the user asks about social-media API workflows, platform d
 
 ## 当前发布范围
 
-当前 skill 目录只包含：
+当前 skill 目录包含：
 
 - 根目录这一份 `SKILL.md`
 - `yuanflow-cli/`
+- `作品评论采集/`
+
+## 环境判断
+
+执行本 Skill 前，先判断当前运行环境：
+
+1. 如果当前 Agent 可用 YuanFlow 内置工具，例如 `yuanflow_cli_call` 或 `yuanflow_gateway_request`，优先使用 YuanFlow 内置工具。不要要求用户安装 npm，也不要要求用户配置 token。
+2. 如果当前不在 YuanFlow 内，且本地可执行 `yuanflow-cli --help`，使用本地 CLI。
+3. 如果当前不在 YuanFlow 内，且本地没有 `yuanflow-cli`，再提示用户安装 `npm install -g yuanflow-cli`。
+
+不要在回复、日志或文件中暴露 token。
 
 ## 分流规则
 
@@ -38,6 +49,18 @@ description: Use when the user asks about social-media API workflows, platform d
 
 - `yuanflow-cli`
 
+### 2. 走 `作品评论采集`
+
+遇到下面这些需求，优先进入这个子 Skill：
+
+- 采集、抓取、导出或分析作品评论。
+- 获取评论回复、二级评论、楼中楼、子评论。
+- 用户给出抖音、小红书、B站、微信公众号、微信视频号、TikTok、Instagram、快手、Reddit、Twitter/X、微博、YouTube、知乎链接或 ID，并明确要评论数据。
+
+子 Skill 名称：
+
+- `作品评论采集`
+
 ## 多需求时怎么处理
 
 如果用户一次提了多段流程，不要强行塞进一个子 Skill，按阶段拆开：

package/skills/yuanflow-skill/yuanflow-cli/SKILL.md

@@ -17,7 +17,19 @@ description: Use when the user needs atomic API calls for social-media platforms
 - 用户要用 CLI 调接口并保存 JSON
 - 用户要让 Agent 稳定解析调用结果
 
-## 安装和更新
+## 调用方式选择
+
+优先级如下：
+
+1. YuanFlow 内置工具：如果当前工具列表里存在 `yuanflow_cli_call`，使用它调用社媒接口。
+2. YuanFlow 网关工具：如果只有 `yuanflow_gateway_request`，可用它访问受控服务接口。
+3. 本地 CLI：如果当前环境可执行 `yuanflow-cli --help`，使用本地 CLI。
+4. 安装提示：只有以上都不可用时，才提示用户安装 `npm install -g yuanflow-cli`。
+
+在 YuanFlow 主程序内，不要提示用户配置 token；token 由主程序 KEY 认证注入。
+在外部 Agent 环境中，使用环境变量 `YUANCHUANG_API_TOKEN`，也可以使用本地 `config set-token`。
+
+## 外部 Agent 安装和更新
 
 要求 Node.js 20 或更高版本。
 
@@ -44,7 +56,13 @@ npm view yuanflow-cli version
 yuanflow-cli --help
 ```
 
-## 配置
+## 外部 Agent 配置
+
+独立 CLI 使用时，可以通过环境变量或本地 config 保存 token。token 优先级是：`--token` > `YUANCHUANG_API_TOKEN` > 本地 `config.token`。
+
+```powershell
+$env:YUANCHUANG_API_TOKEN="<你的令牌>"
+```
 
 保存 Yuan API 令牌和服务地址：
 
@@ -63,13 +81,13 @@ yuanflow-cli douyin video-detail "https://v.douyin.com/xxx/" --token <你的令
 或用环境变量：
 
 ```powershell
-$env:YUANFLOW_TOKEN="<你的令牌>"
+$env:YUANCHUANG_API_TOKEN="<你的令牌>"
 yuanflow-cli douyin hot-search
 ```
 
 ## Agent 调用规则
 
-给 AI Agent 使用时，先查命令和 schema，再调用接口。
+给 AI Agent 使用时，先查命令和 schema，再调用接口。YuanFlow 内置环境下，优先调用 `yuanflow_cli_call`；外部 Agent 环境下，优先调用 `yuanflow-cli`。
 
 ```powershell
 yuanflow-cli commands list
@@ -114,9 +132,10 @@ yuanflow-cli schema douyin.video-detail
 yuanflow-cli shortcuts
 yuanflow-cli shortcuts douyin
 yuanflow-cli list douyin
-yuanflow-cli commands list
-yuanflow-cli commands describe xiaohongshu.search-notes
-yuanflow-cli schema xiaohongshu.search-notes
+  yuanflow-cli commands list
+  yuanflow-cli commands describe xiaohongshu.search-notes
+  yuanflow-cli schema xiaohongshu.search-notes
+  yuanflow-cli comments collect --platform douyin --target "https://v.douyin.com/xxx/" --format agent-json
 ```
 
 当前 registry 覆盖的平台包括：
@@ -156,6 +175,43 @@ yuanflow-cli bilibili video-detail "https://www.bilibili.com/video/BVxxx" -o bil
 | 作品评论 | `yuanflow-cli douyin comments <aweme_id> --count 20 --cursor 0 --format agent-json` |
 | 抖音热榜 | `yuanflow-cli douyin hot-search --format agent-json` |
 
+### 作品评论采集统一入口
+
+评论采集优先使用统一入口：
+
+```powershell
+yuanflow-cli comments collect --platform douyin --target "https://v.douyin.com/xxx/" --format agent-json
+```
+
+常用参数：
+
+- `--platform`：平台，如 `douyin`、`xiaohongshu`、`bilibili`、`wechat_mp`、`wechat_channels`、`tiktok`、`instagram`、`kuaishou`、`reddit`、`twitter`、`weibo`、`youtube`、`zhihu`。
+- `--action`：`comments` 一级评论，`replies` 评论回复；YouTube 社区帖子使用 `post_comments` 或 `post_replies`。
+- `--target`：作品链接、文章链接、视频 ID、笔记 ID、BV 号等。
+- `--comment-id`：采集回复时的父评论 ID。
+- `--cursor`：翻页游标。
+- `--count`：返回数量。
+- `--page`：B站页码。
+- `--prefer fallback`：主接口失败时切换备用接口。
+- `--extra`：JSON 字符串，用于公众号 `content_id` 等补充参数。
+
+在 YuanFlow 主程序内，用 `yuanflow_cli_call` 调用时传参数数组：
+
+```json
+{
+  "args": [
+    "comments",
+    "collect",
+    "--platform",
+    "douyin",
+    "--target",
+    "https://v.douyin.com/xxx/",
+    "--format",
+    "agent-json"
+  ]
+}
+```
+
 ### 小红书
 
 | 需求 | 命令 |
@@ -205,3 +261,4 @@ yuanflow-cli bilibili video-detail "https://www.bilibili.com/video/BVxxx" -o bil
 - 调真实接口前，先用 `--dry-run` 核对 URL、method、headers 和 body。
 - Agent 自动处理结果时，统一加 `--format agent-json`。
 - 不要把 token 写进文档、日志或最终回复。
+- 不要要求用户提供或粘贴 token。

package/skills/yuanflow-skill//344/275/234/345/223/201/350/257/204/350/256/272/351/207/207/351/233/206/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: 作品评论采集
+description: Use when the user needs to collect, export, inspect, or continue comment and reply data for Douyin, Xiaohongshu, Bilibili, WeChat MP, WeChat Channels, TikTok, Instagram, Kuaishou, Reddit, Twitter/X, Weibo, YouTube, or Zhihu posts.
+builtin_skill_version: 1.0.0
+tags:
+  - 自媒体
+  - 评论采集
+  - 抖音
+  - 小红书
+  - B站
+  - 微信公众号
+  - 微信视频号
+  - TikTok
+  - Instagram
+  - 快手
+  - Reddit
+  - Twitter
+  - 微博
+  - YouTube
+  - 知乎
+emoji: 💬
+---
+
+# 作品评论采集
+
+本技能把用户的评论采集需求稳定映射到 `yuanflow-cli comments collect`。在 YuanFlow 主程序内，优先使用受控工具 `yuanflow_cli_call`；它会由主程序认证系统注入 `YUANCHUANG_API_TOKEN`，不要让用户粘贴 KEY，不要在回复、日志或文件里暴露 token。
+
+## 什么时候使用
+
+用户出现以下意图时使用：
+
+- 采集、抓取、获取、导出某个作品、文章、帖子、回答的评论。
+- 获取某条评论下的回复、二级评论、楼中楼、子评论。
+- 用户给出抖音、小红书、B站、微信公众号文章、微信视频号、TikTok、Instagram、快手、Reddit、Twitter/X、微博、YouTube、知乎链接或 ID，并要求看评论数据。
+
+不要用于发评论、回复评论、点赞评论、绕过平台限制、批量抓取或未授权数据访问。作品详情、作品下载、用户主页、综合搜索应交给 `yuanflow-cli` 其它命令。
+
+## 调用优先级
+
+1. YuanFlow 主程序内：调用 `yuanflow_cli_call`，参数数组从 `comments collect` 开始。
+2. 外部 Agent 且本机有 CLI：执行 `yuanflow-cli comments collect ...`。
+3. 外部 Agent 且没有 CLI：再提示用户安装 `npm install -g yuanflow-cli`。
+
+YuanFlow 内置调用示例：
+
+```json
+{
+  "args": [
+    "comments",
+    "collect",
+    "--platform",
+    "douyin",
+    "--target",
+    "https://v.douyin.com/xxx/",
+    "--format",
+    "agent-json"
+  ]
+}
+```
+
+外部 CLI 示例：
+
+```powershell
+yuanflow-cli comments collect --platform douyin --target "https://v.douyin.com/xxx/" --format agent-json
+```
+
+## 先查命令和 schema
+
+不确定参数时先查，不要猜：
+
+```json
+{"args":["commands","list"]}
+{"args":["schema","comments.douyin.comments"]}
+```
+
+命令 key 格式是：
+
+```text
+comments.<platform>.<action>
+```
+
+例如 `comments.douyin.comments`、`comments.xiaohongshu.replies`、`comments.youtube.post_comments`。
+
+## 参数规则
+
+通用参数：
+
+- `--platform`：平台标识。
+- `--action`：`comments` 一级评论；`replies` 评论回复；YouTube 社区帖子用 `post_comments` 或 `post_replies`。默认 `comments`。
+- `--target`：作品、文章、帖子或回答 ID，也可以传支持的平台链接。
+- `--comment-id`：多数平台采集回复时必填。
+- `--cursor`：翻页游标，必须来自上一次响应，不要编造。
+- `--count`：返回数量，仅平台支持时传。
+- `--page`：B站页码。
+- `--prefer fallback`：主接口失败或用户要求备用接口时使用。
+- `--extra`：JSON 字符串补充参数，例如微信公众号回复需要 `content_id`。
+- `--format agent-json`：Agent 调用时必须加，便于稳定解析。
+
+## 平台识别
+
+| 平台参数 | 用户常见说法 | 链接或 ID 标识 |
+|---|---|---|
+| `douyin` | 抖音、Douyin | `douyin.com`、`iesdouyin.com`、`v.douyin.com`、`aweme_id` |
+| `xiaohongshu` | 小红书、XHS | `xiaohongshu.com`、`xhslink.com`、`note_id` |
+| `bilibili` | B站、哔哩哔哩 | `bilibili.com`、`b23.tv`、`BV` 号 |
+| `wechat_mp` | 微信公众号、公众号文章 | `mp.weixin.qq.com/s/` |
+| `wechat_channels` | 微信视频号、视频号 | 视频号视频 ID、视频号详情里的 `id` |
+| `tiktok` | TikTok | `tiktok.com`、`vm.tiktok.com`、`aweme_id` |
+| `instagram` | Instagram、ins | `instagram.com/p/`、`instagram.com/reel/`、shortcode、media_id |
+| `kuaishou` | 快手 | `kuaishou.com/short-video/`、`photo_id` |
+| `reddit` | Reddit | `reddit.com/r/.../comments/`、`t3_` 帖子 ID |
+| `twitter` | Twitter、X | `twitter.com`、`x.com`、推文数字 ID |
+| `weibo` | 微博 | `weibo.com`、微博 `id`、`mid` |
+| `youtube` | YouTube、油管 | `youtube.com/watch?v=`、`youtu.be/`、视频 ID、社区帖子 ID |
+| `zhihu` | 知乎 | 知乎回答 ID、评论 ID |
+
+如果短链文本无法判断平台，先按域名判断；仍无法判断就追问平台。
+
+## 接口映射
+
+Agent 不需要直接拼接口地址，只需要选对 `platform`、`action` 和参数。
+
+| 平台 | action | 首选能力 | 主要参数 | 备用能力 |
+|---|---|---|---|---|
+| 抖音 | `comments` | 抖音作品一级评论 | `aweme_id`、`cursor`、`count` | 支持 |
+| 抖音 | `replies` | 抖音评论回复 | `item_id`、`comment_id`、`cursor`、`count` | 支持 |
+| 小红书 | `comments` | 小红书笔记一级评论 | `note_id`、`cursor` | 支持 |
+| 小红书 | `replies` | 小红书笔记二级评论 | `note_id`、`comment_id`、`cursor`、`count` | 支持 |
+| B站 | `comments` | B站视频一级评论 | `bv_id`、`page` | 支持 |
+| B站 | `replies` | B站评论回复 | `bv_id`、`comment_id`、`page` | 暂无 |
+| 微信公众号 | `comments` | 公众号文章一级评论 | `url`、`comment_id`、`cursor` | 暂无 |
+| 微信公众号 | `replies` | 公众号文章评论回复 | `url`、`comment_id`、`extra.content_id`、`cursor` | 暂无 |
+| 微信视频号 | `comments` | 视频号一级评论 | `id`、`cursor` | 暂无 |
+| 微信视频号 | `replies` | 视频号评论回复 | `id`、`comment_id`、`cursor` | 暂无 |
+| TikTok | `comments` | TikTok 作品一级评论 | `aweme_id`、`cursor`、`count` | 支持 |
+| TikTok | `replies` | TikTok 评论回复 | `item_id`、`comment_id`、`cursor`、`count` | 支持 |
+| Instagram | `comments` | Instagram 帖子一级评论 | `code_or_url`、`cursor` | 支持 |
+| Instagram | `replies` | Instagram 评论回复 | `code_or_url`、`comment_id`、`cursor` | 支持 |
+| 快手 | `comments` | 快手作品一级评论 | `photo_id`、`cursor` | 支持 |
+| 快手 | `replies` | 快手作品二级评论 | `photo_id`、`comment_id`、`cursor` | 暂无 |
+| Reddit | `comments` | Reddit 帖子一级评论 | `post_id`、`cursor` | 暂无 |
+| Reddit | `replies` | Reddit 评论回复 | `post_id`、`cursor` | 暂无 |
+| Twitter/X | `comments` | 推文评论 | `tweet_id`、`cursor` | 支持 |
+| 微博 | `comments` | 微博一级评论 | `id`、`count`、`cursor` | 支持 |
+| 微博 | `replies` | 微博子评论 | `id`、`count`、`cursor` | 暂无 |
+| YouTube | `comments` | 视频一级评论 | `video_id`、`cursor` | 支持 |
+| YouTube | `replies` | 视频二级评论 | `continuation_token` | 支持 |
+| YouTube | `post_comments` | 社区帖子一级评论 | `post_id`、`cursor` | 暂无 |
+| YouTube | `post_replies` | 社区帖子评论回复 | `continuation_token` | 暂无 |
+| 知乎 | `comments` | 回答评论区 | `answer_id`、`count`、`cursor` | 暂无 |
+| 知乎 | `replies` | 子评论区 | `comment_id`、`count`、`cursor` | 暂无 |
+
+## 输出要求
+
+成功后用中文简短说明：
+
+- 调用了哪个平台和评论类型。
+- 使用首选能力还是备用能力。
+- 如果响应里有评论数量、下一页游标或 continuation token，要提示用户。
+- 用户要求导出时，再整理为表格、JSON 或文件。
+
+失败时按 `agent-json` 的 `error.code` 和 `error.message` 解释。常见处理：
+
+- `TOKEN_MISSING`：提示先完成 YuanFlow KEY 认证或外部 CLI 环境变量配置。
+- `BAD_ARGUMENT`：检查平台、action、target、comment-id、cursor。
+- `AUTH_INVALID`：认证无效或权限不足。
+- `UPSTREAM_ERROR`、`NETWORK_ERROR`：说明上游或网络失败，可稍后重试，或在有备用能力的平台加 `--prefer fallback`。
+
+不要展示完整 Authorization 请求头、token、cookie 或敏感账号信息。

package/src/agent-protocol.js

@@ -1,5 +1,6 @@
 import { listEndpoints } from './registry.js';
 import { listShortcuts } from './shortcuts.js';
+import { listCommentCommands } from './comment-collector.js';
 
 const ERROR_MAP = [
   {
@@ -81,7 +82,8 @@ export function getCommandName(platform, command) {
 export function buildCommandRegistry() {
   const shortcuts = listShortcuts().map((shortcut) => shortcutToCommand(shortcut));
   const endpoints = listEndpoints().map((endpoint) => endpointToCommand(endpoint));
-  return [...shortcuts, ...endpoints].sort((left, right) =>
+  const commentCommands = listCommentCommands();
+  return [...shortcuts, ...endpoints, ...commentCommands].sort((left, right) =>
     left.key.localeCompare(right.key),
   );
 }

package/src/cli.js

@@ -16,6 +16,7 @@ import {
   isAgentJsonFormat,
 } from './agent-protocol.js';
 import { findShortcut, listShortcuts } from './shortcuts.js';
+import { collectComments } from './comment-collector.js';
 
 export async function main(argv) {
   const args = argv.slice(2);
@@ -46,6 +47,11 @@ export async function main(argv) {
     return;
   }
 
+  if (command === 'comments') {
+    await handleComments(rest);
+    return;
+  }
+
   if (command === 'schema') {
     await handleSchema(rest);
     return;
@@ -210,6 +216,33 @@ async function handleCall(args) {
   });
 }
 
+async function handleComments(args) {
+  const { positionals, options } = parseOptions(args);
+  const [action = 'collect'] = positionals;
+  if (action !== 'collect') {
+    throw new Error('未知 comments 命令。用法：yuanflow-cli comments collect --platform douyin --target <作品链接或ID>');
+  }
+  const platform = options.named?.platform;
+  const target = options.named?.target || positionals[1];
+  if (!platform) {
+    throw new Error('缺少 --platform，例如 douyin、xiaohongshu、bilibili。');
+  }
+  if (!target) {
+    throw new Error('缺少 --target 或目标位置参数。');
+  }
+  const result = await collectComments({
+    platform,
+    action: options.named?.action || 'comments',
+    target,
+    prefer: options.named?.prefer || 'primary',
+    options,
+  });
+  await outputResult(result, options, {
+    command: 'comments collect',
+    meta: { endpoint: result.endpoint.path, kind: 'comment-collector' },
+  });
+}
+
 async function handleGeneratedCommand(platform, args) {
   if (!getPlatforms().includes(platform)) {
     throw new Error(`未知平台：${platform}。可用平台：${getPlatforms().join(', ')}`);
@@ -363,10 +396,13 @@ function printHelp() {
   yuanflow-cli shortcuts douyin
   yuanflow-cli commands list
   yuanflow-cli schema douyin.video-detail
+  yuanflow-cli comments collect --platform douyin --target "https://v.douyin.com/xxx/" --dry-run
   yuanflow-cli list douyin
 
 说明：
   所有请求都会调用 Yuan API 的 /social/*path，并使用 Authorization: Bearer <token>。
+  token 优先级：--token > YUANCHUANG_API_TOKEN > 本地 config.token。
+  YuanFlow 主程序内使用时，token 由主程序认证系统注入，不需要手动配置。
   AI Agent 推荐使用 --format agent-json 获取稳定 JSON 外壳。
 `);
 }