yuanflow-cli

YuanFlow 的 npm 包，包含两个命令入口：

• yuanflow-cli：社媒 API 转 CLI，覆盖完整 registry、快捷命令、schema、dry-run 和 agent-json 输出。
• yuanflow-skill：把 YuanFlow-skill 注入到本机支持的 AI Agent skills 目录。

安装

需要 Node.js 20 或更高版本。

npm install -g yuanflow-cli

安装后可用：

yuanflow-cli --help
yuanflow-skill list-agents

API CLI

yuanflow-cli config set-token <你的令牌>
yuanflow-cli config set-base-url https://open.yuanchuangai.com
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 works detail --platform douyin --target "https://v.douyin.com/xxx/" --format agent-json
yuanflow-cli works download --platform douyin --target "https://v.douyin.com/xxx/" --region CN --format agent-json
yuanflow-cli search content --platform xiaohongshu --keyword "美妆" --format agent-json
yuanflow-cli search users --platform instagram --keyword "nasa" --format agent-json
yuanflow-cli douyin web get-sec-user-id --url "https://v.douyin.com/xxx/" --format agent-json
yuanflow-cli douyin user-profile <sec_user_id> --format agent-json
yuanflow-cli douyin user-posts <sec_user_id> --count 20 --cursor 0 --format agent-json
yuanflow-cli knowledge docs --format agent-json
yuanflow-cli knowledge entry --output-format short_video_script --domain 自媒体运营 --content-goal "写一个创业者短视频选题" --target-audience 创业者 --format agent-json
yuanflow-cli oss signed-url --key path/to/file.png --ttl-seconds 1800 --format agent-json
yuanflow-cli browser profile-path --platform douyin --account main --format agent-json
yuanflow-cli browser task-plan --platform xiaohongshu --task publish --account main --format agent-json
yuanflow-cli list douyin

环境变量：

YUANCHUANG_API_TOKEN=<你的令牌>

token 优先级：--token > YUANCHUANG_API_TOKEN > 本地 config.token。独立 CLI 用户可以使用环境变量或 config set-token；在 YuanFlow 主程序内使用时，token 由主程序认证系统注入，不需要手动配置。

作品评论采集

评论采集统一走 comments collect，用于把 Agent 的自然语言需求稳定映射到平台评论接口：

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 查看某个评论采集命令的参数、接口路径和返回说明。

综合作品工具

四类综合工具统一走受控命令，适合 Agent 通过自然语言稳定调用：

yuanflow-cli works detail --platform douyin --target "https://v.douyin.com/xxx/" --format agent-json
yuanflow-cli works download --platform youtube --target "dQw4w9WgXcQ" --format agent-json
yuanflow-cli search content --platform xiaohongshu --keyword "美妆" --format agent-json
yuanflow-cli search users --platform instagram --keyword "nasa" --format agent-json

命令 key：

• works.<platform>.detail：单作品详情。
• works.<platform>.download：播放/下载地址候选或视频流信息。
• search.<platform>.content：内容、作品、笔记、文章、帖子搜索。
• search.<platform>.users：账号、用户、作者、频道搜索。

Agent 不确定参数时先执行 commands list，再用 schema works.douyin.detail 或 schema search.xiaohongshu.content 查看参数。--dry-run 可预览请求映射，不发起真实接口请求，也不要求 token。

帐号监控

帐号监控 随 npm 包安装到 Skill bundle，用于把帐号搜索、主页资料、主页作品、历史快照和变化对比串成稳定流程。

抖音完整链路：

yuanflow-cli douyin web get-sec-user-id --url "https://v.douyin.com/xxx/" --format agent-json
yuanflow-cli search users --platform douyin --keyword "<sec_user_id>" --format agent-json
yuanflow-cli douyin user-profile <sec_user_id> --format agent-json
yuanflow-cli douyin user-posts <sec_user_id> --count 20 --cursor 0 --format agent-json

如果主页作品数据缺少播放、点赞、评论、转发、收藏等统计，再用：

yuanflow-cli works detail --platform douyin --target "<aweme_id 或 share_url>" --format agent-json

快照默认保存到 YuanFlow 数据目录下的 runtime_tools/account-monitor/snapshots。

自媒体知识库

知识库能力独立于社媒 /social 接口，走 Yuan API 的 /api/knowledge-base/docs 和 /atomic/agent-rules/navigate：

yuanflow-cli knowledge docs --format agent-json
yuanflow-cli knowledge entry --output-format short_video_script --domain 自媒体运营 --content-goal "写一个创业者短视频选题" --target-audience 创业者 --format agent-json
yuanflow-cli knowledge rules --pack-code topic_pain_point_pack --output-format short_video_script --content-goal "写一个创业者短视频选题" --target-audience 创业者 --format agent-json
yuanflow-cli knowledge rule-detail --rule-code some_rule_code --output-format short_video_script --content-goal "写一个创业者短视频选题" --target-audience 创业者 --format agent-json

Agent 应先查看 knowledge docs，再把用户需求整理成 task_frame，按接口返回的 next_actions 渐进查询。v2 接口不要求 task_intent；旧字段仅保留兼容。packs、rules 的 data 可能直接是数组，Agent 不应假设固定对象结构，应优先读取 next_actions 继续下钻。

knowledge entry、knowledge packs、knowledge evaluate 会按规则库实际校验要求本地检查 task_frame.domain 和 task_frame.content_goal，CLI 调用时必须传 --domain 和 --content-goal，或通过 --task-frame-file 提供同名字段。rules 和 rule-detail 用于按已选包/规则继续下钻，仍必须分别传 --pack-code 或 --rule-code。

业务创作类 Skill

以下业务 Skill 随 npm 包一起安装，统一流程是：先检查 个人创作库 是否有对应历史参考记录，再调用 自媒体知识库 按 next_actions 分层查询方法摘要，最后结合用户要求输出结果。输出后会询问用户是否满意、是否记录到个人创作库，并询问是否需要生成 HTML 可视化汇总。

• IP运营：个人或品牌 IP 的内容运营节奏、栏目组合、互动策略和增长路径。
• 直播话术生成：直播开场、留人、转场、成交、互动和控场话术。
• 帐号定位：账号人设、内容边界、目标受众、价值主张和栏目方向。
• 选题策划：选题池、系列选题、热点选题和选题优先级排序。
• 文案创作：小红书、公众号、朋友圈、短视频口播、直播预告、海报和转化型文案。
• 视频投流策略：短视频、图文视频或内容素材的投流目标、人群、预算、素材分层和测试节奏。
• 直播投流策略：直播预热、直播引流、直播成交和直播间投放的人群、预算、素材、节奏和复盘策略。

OSS 原子能力

OSS 能力独立封装为 oss 命令，用于临时上传、签名链接和对象复制：

yuanflow-cli oss temp-upload --file ./cover.png --content-type image/png --format agent-json
yuanflow-cli oss signed-url --key path/to/file.png --ttl-seconds 1800 --method GET --format agent-json
yuanflow-cli oss copy --source-key temp/cover.png --target-key final/cover.png --format agent-json

上传本地文件前必须确认用户授权，不能上传密钥、cookie、账号凭据或隐私文件。

自媒体浏览器自动化

browser 命令是自媒体平台专用浏览器自动化协议，用于账号登录态隔离、Cookie/profile 本地保存、账号页面采集、作品发布前检查和发布流程规划。它不用于普通网页搜索、通用浏览、截图或 CDP 连接。

如果要做发布类任务，先优先用用户电脑里已有的 Chrome，第二优先用 Edge。两个都没有时，再提示用户安装给浏览器自动化用的 Chromium。不要把这件事说得太技术化，直接告诉用户“需要一个能给自动化程序用的浏览器”就够了。

如果 Chromium 连续下载 3 次还是失败，就停止继续重试，明确告诉用户可能是网络、权限、下载源不可用或安全软件拦截，并引导用户手动下载和安装后再继续。

当前命令只返回受控路径、任务计划和 dry-run 预检结果，不直接暴露裸 Playwright 或 Chrome 调试能力：

yuanflow-cli browser profile-path --platform douyin --account main --format agent-json
yuanflow-cli browser session-init --platform xiaohongshu --account main --format agent-json
yuanflow-cli browser cookie-policy --platform douyin --account main --format agent-json
yuanflow-cli browser task-plan --platform douyin --task publish --account main --format agent-json
yuanflow-cli browser dry-run --platform xiaohongshu --task publish --account main --file ./post.mp4 --title "标题" --caption "正文" --cover ./cover.png --format agent-json

支持平台：douyin、xiaohongshu、weibo、bilibili、tiktok、youtube、twitter。

固定边界：

• Cookie、localStorage、sessionStorage 和 profile 只保存在本地受控目录，不输出、不上传。
• 扫码、验证码、人机验证、平台风控必须暂停并让用户手动处理。
• 最终发布、删除、修改账号资料等线上状态变更前必须获得用户确认。
• 普通网页浏览请使用 YuanFlow 通用浏览器能力，不使用本命令。

音视频在线转文字

音视频在线转文字 随 npm 包安装到 Skill bundle，用于通过 YuanFlow 在线 ASR 接口把音频或视频转成干净文本。视频输入需要先用 ffmpeg 分离音频，再上传 OSS。

固定链路：

1. 判断用户提交的是音频还是视频。
2. 视频先抽取为音频，音频上传前改成英文文件名。
3. 使用 yuanflow-cli oss temp-upload 上传音频。
4. ASR 请求必须优先使用 OSS 返回的 data.signed_url 作为 metadata.audio_url，不要优先使用裸域名 data.url。
5. 调用 POST https://open.yuanchuangai.com/v1/audio/transcriptions，模型 doubao-asr，response_format=json。
6. 默认只返回响应里的 text 干净文本；用户要求时间戳时再检查响应结构，不编造时间戳。

请求体示例：

{
  "model": "doubao-asr",
  "response_format": "json",
  "metadata": {
    "audio_url": "<OSS signed_url>"
  }
}

生图技能

生图技能 随 npm 包安装到 Skill bundle。YuanFlow 主程序内优先使用受控工具 yuanflow_image_request，自动注入当前用户 token 并缓存返回图片。

• 生成图片：/v1/images/generations，主模型 gpt-image-2-c，备用模型 gpt-image-2，请求体使用 prompt。
• 编辑图片：/v1/images/edits，必须使用 multipart/form-data 上传本地图片文件。
• gpt-image-2-c 通常返回 URL，gpt-image-2 通常返回 b64_json；两种返回都应缓存后再展示。
• 中文用户或中文任务默认使用中文语境生图；如果画面必须出现文字，提示词应明确要求清晰简体中文。正文配图优先要求无文字、无字母、无 Logo、无水印，避免生成英文占位内容。
• 生成图片必填参数：prompt。可选参数：size（默认 1024x1024）、quality（默认 standard）、style（默认 vivid）、n（默认 1，范围 1~10）、response_format（默认 url）。
• 编辑图片除 prompt 外还必须上传本地图片文件，Skill 内使用 image_path 表示本地文件路径，实际请求以 multipart/form-data 的 image 字段上传。

HTML 报告生成

HTML报告生成 随 npm 包安装到 Skill bundle，用于把自媒体分析、数据复盘、文案方案、账号监控、知识梳理和执行计划生成可直接打开的单页 HTML 报告。

• 内置 9 种报告形态：洞察简报、数据仪表盘、深度报告、横向对比、卡片集合、流程步骤、时间线、行动看板、知识地图。
• 正式模板默认使用米色留白风格，模板位于 HTML报告生成/templates/warm-beige/。
• 蓝白、黑金、黑白红、柔和科技作为扩展主题逻辑保留在 HTML报告生成/references/theme-system.md。
• 模板和引用文档跟随 Skill 目录一起安装，不需要用户单独复制资源文件。

Skill 安装器

yuanflow-skill list-agents
yuanflow-skill list-skills
yuanflow-skill install
yuanflow-skill install --agent codex,cursor
yuanflow-skill install --project
yuanflow-skill install --dry-run
yuanflow-skill uninstall --agent codex

安装器会自动发现 YuanFlow-skill 根目录和一级子目录中的 SKILL.md，并以 yuanflow-skill bundle 形式注入到目标 Agent。

开发检查

npm test
npm run pack:check
npm run release:check