yixiaoer-cli

蚁小二 yxer CLI 与 AI Skill 配套仓库。

🚀 新功能（2026-06-02）：

• ✨ 智能字段分组 - schema fields 现在按必填/可选/复杂字段分组展示
• 🔍 智能错误分析 - validate 失败时自动分析原因并给出修复建议
• 📚 5分钟快速开始 - 查看 skills/yixiaoer/QUICKSTART.md
• 💡 自动查询提示 - 复杂字段自动提示对应的查询命令

详见 CHANGELOG.md

---

仓库入口按当前项目的使用对象分层组织：

• README.md 面向人类用户和维护者，负责安装、快速开始和常用命令。
• skills/yixiaoer/SKILL.md 面向 AI agent，负责共享规则、能力索引和命令探索。
• skills/yixiaoer/references/ 是引用主源，放任务分域、工作流、平台文档和命令参考。
• 根目录 references/ 仅作为打包时的输出目录，内容来源于 skills/yixiaoer/references/。

命令树设计标准与演进建议见 skills/yixiaoer/references/cli/command-design.md。

运行时统一通过 yxer 执行，不再假设存在旧 Node 脚本入口。

安装与快速开始

环境要求

• Go 1.25.0 或更高
• Node.js 和 npx

快速开始（npm 安装，推荐）

如果你已经把 yxer 发布到了 npm，推荐优先使用全局安装：

npm install -g @yixiaoermail/cli@latest
yxer --version
yxer update

npm 包现在采用轻量安装器模式：

• npm 包本身只包含启动器、skill 源文档、schema 和 references 打包输出
• 安装阶段会按当前系统下载匹配的 yxer 二进制归档
• 如果 postinstall 被跳过，首次运行 yxer 时也会自动补装二进制

如需使用私有镜像或自建发布源，可在安装前设置：

$env:YXER_DOWNLOAD_BASE_URL = "https://mirror.example.cn/yxer/releases/v3.2.24"
npm install -g @yixiaoermail/cli@latest

如需全局同步 skill：

yxer skill sync --global

升级后建议再执行一次：

yxer doctor

本次版本修改内容请查看 CHANGELOG.md。

从源码构建

在仓库根目录执行：

go build -o bin/yxer.exe .

也可以直接使用项目里的 Makefile：

make build

构建完成后，可执行文件位于：

bin/yxer.exe

设置为全局命令

安装成功后，建议把 yxer.exe 所在目录加入系统 PATH，这样后续就可以在任意目录直接执行 yxer。

Windows PowerShell 示例：

$yxerBin = (Resolve-Path .\bin).Path
[Environment]::SetEnvironmentVariable(
  "Path",
  $env:Path + ";" + $yxerBin,
  "User"
)

执行完成后，请重新打开一个新的终端窗口，再运行 yxer --version 验证全局命令是否生效。

验证安装

bin/yxer.exe --version
bin/yxer.exe config init --api-key 
bin/yxer.exe doctor

如果你已经把 bin/ 加入了 PATH，也可以直接执行：

yxer --version
yxer doctor

3 分钟开始

1. 检查本地环境

yxer config init --api-key 
yxer doctor

2. 查看当前配置

yxer config get

如需连接本地或测试环境，可在当前终端设置 API 地址；末尾的 / 会自动去除：

$env:YIXIAOER_API_URL = "http://127.0.0.1:8083/api/"
yxer config get

3. 查询可用账号

yxer accounts list 抖音 --json

4. 预览一次发布请求

yxer publish video 抖音 .\payload.json --dry-run

发布前建议先获取表单字段和前置数据，再填写 payload.json：

yxer prepare 抖音 video
yxer schema fields 抖音 video
yxer schema get 抖音 video
yxer validate 抖音 video .\payload.json
yxer publish video 抖音 .\payload.json --dry-run

payload.json 必须使用统一标准结构，所有平台都一样：

{
  "action": "publish",
  "publishType": "video",
  "platforms": ["抖音"],
  "publishChannel": "cloud",
  "publishArgs": {
    "accountForms": [
      {
        "platformAccountId": "",
        "contentPublishForm": {
          "formType": "task"
        }
      }
    ]
  }
}

说明：

• 顶层必须包含 publishArgs
• accountForms 必须放在 publishArgs.accountForms
• 平台差异字段默认放在 publishArgs.accountForms[].contentPublishForm
• 共享资源字段可直接放在 publishArgs 下，与 accountForms 同级，例如 video、images、cover、coverKey、content
• 文章正文推荐写在 publishArgs.content；CLI 会在缺失时自动补齐到 publishArgs.accountForms[].contentPublishForm.content
• 不再支持顶层直接放 accountForms
• 不再支持把 title、description、visibleType 等内层字段直接写在 payload 顶层

如需本机发布，校验阶段也建议显式带上发布通道，保证 validate、--dry-run 和正式发布使用同一套模式解析：

yxer validate 抖音 video .\payload.json --publish-channel local --client-id 
yxer publish video 抖音 .\payload.json --publish-channel local --client-id  --dry-run
yxer publish video 抖音 .\payload.json --publish-channel local --client-id 

升级

如果 CLI 是通过 npm 安装的，推荐按下面顺序升级：

yxer update

如需全局 skill：

yxer update --global

只检查当前状态而不执行同步，可运行：

yxer update --check

执行“检查状态 + 同步 skill + 查看升级指引”：

yxer update

本次版本更新内容统一记录在 CHANGELOG.md。

AI Skill 安装

本项目采用“CLI 先安装，Skill 再安装”的方式。

如果要接入 SkillHub / skills 市场，建议使用独立的 bootstrap skill：

• SkillHub 安装入口：skills/yixiaoer-bootstrap
• 正式业务 skill：skills/yixiaoer
• 推荐职责划分：
  • bootstrap skill 只负责安装 @yixiaoermail/cli、执行 yxer skill sync --global、引导 config init
  • 正式 skill 负责发布、查询、校验、草稿、素材、排障

如果 CLI 是通过 npm 成品包安装的，推荐优先使用：

yxer skill sync
yxer skill sync --global

npm 包会内置 skills/yixiaoer，skill sync 会直接使用本地随包分发的 skill 源文件，不依赖 GitHub 仓库地址。

生成 npm 成品包

如需产出可通过 npm install -g 安装的 CLI 成品包，可在仓库根目录执行：

.\scripts\build-npm-package.ps1

没有 tag 环境变量时，本地构建读取仓库内部版本，并校验以下两个版本源保持一致：

• internal/domain/response.go
• skills/yixiaoer/SKILL.md

本地构建如需显式传版本号，也必须与内部版本一致：

.\scripts\build-npm-package.ps1 -Version 3.2.24

该脚本会：

• 先运行 go test ./...
• 交叉编译 windows/darwin/linux 的 amd64/arm64 二进制
• 生成 release 压缩包与 checksums.txt 到 out\release\
• 生成轻量 npm 发布包到 out\npm\

生成完成后，可用下列命令验证 tarball：

npm install -g .\out\npm\.tgz
yxer --version
yxer skill sync

发布到火山引擎 TOS 时，需在桶内 yxer/releases/v/ 上传：

• yxer-cli--windows-amd64.zip
• yxer-cli--windows-arm64.zip
• yxer-cli--darwin-amd64.tar.gz
• yxer-cli--darwin-arm64.tar.gz
• yxer-cli--linux-amd64.tar.gz
• yxer-cli--linux-arm64.tar.gz
• checksums.txt

1. 准备新版本并推送源码

更新 internal/domain/response.go 和 skills/yixiaoer/SKILL.md 中的版本号，确保二者一致。使用从未发布过的新版本号，然后提交并推送源码：

$releaseVersion = "3.2.27" # 替换为新的、未发布过的版本号
$branch = "main"           # 替换为实际发版分支
git add internal/domain/response.go skills/yixiaoer/SKILL.md
git commit -m "release: v$releaseVersion"
git push origin $branch

# 在推送的提交上创建并推送版本 tag
git tag "v$releaseVersion"
git push origin "v$releaseVersion"

推送 tag 只用于标记源码版本，不会触发 GitHub 构建或发布。确认本机检出的源码就是该 tag 对应的提交，再继续操作。

2. 准备本机工具和凭据

本机需要安装 Go、Node.js/npm、AWS CLI 和 curl.exe，并确保它们在 PATH 中。本地发布时，分别把 TOS Access Key ID、Secret Access Key 和 npm 发布 token 填入 .local-release/TOS_ACCESS_KEY_ID.txt、.local-release/TOS_SECRET_ACCESS_KEY.txt、.local-release/NPM_TOKEN.txt。每个文件只写一行原始值，不要加变量名、引号或空格。该目录已加入 .gitignore；文件仍是明文，请只在受信任的本机保存，不要发送或提交密钥。对应的环境变量优先于文件；npm token 文件未填写时，也可以使用已有的 npm 登录配置。若使用登录配置，先确认当前账号：

npm login --registry https://registry.npmjs.org
npm whoami --registry https://registry.npmjs.org

使用 NPM_TOKEN.txt 时无需运行 npm login；发布脚本会通过仅作用于 registry.npmjs.org 的临时 npm 配置读取该 token，并在发布前检查身份。

3. 本机构建并预览

在仓库根目录执行：

.\scripts\publish-release.ps1 -DryRun

脚本会运行构建测试、交叉编译六个平台、生成 npm tarball、校验成品，并预览 TOS 上传和 npm 发布。此步骤不会上传 TOS 或发布 npm，但会在本机生成或更新 out\release 和 out\npm。检查版本、TOS 目标路径和包名无误后再继续。

4. 上传 TOS 并发布 npm

.\scripts\publish-release.ps1 -Execute

脚本会先检查 npm 登录状态和版本是否已发布，再并发上传归档到 TOS，从包内配置的下载地址读取归档并校验 SHA-256，全部通过后才发布 npm。默认目标是上海地域的 yixiaoer-lite-asserts 桶、对象前缀 yxer/releases 和 https://tos-s3-cn-shanghai.volces.com；下载根地址默认取 npm/package.json 中的 TOS 公共域名 yixiaoer-lite-asserts.tos-cn-shanghai.volces.com。可通过参数或环境变量 TOS_BUCKET、TOS_REGION、TOS_S3_ENDPOINT、TOS_OBJECT_PREFIX、YXER_DOWNLOAD_ROOT_URL 覆盖。TOS 凭据仅需目标桶前缀的上传权限。

5. 确认发布结果

npm view @yixiaoermail/cli version
npm install -g "@yixiaoermail/cli@$releaseVersion"
yxer --version

已发布到 npm 的同名同版本包不能再次发布。GitHub 只保存源码和 tag，不负责构建、打包、上传或 npm 发布。

查看当前技能包位置

yxer skill show

安装 skill

npx skills add "\\skills\\yixiaoer" -y

如需全局安装：

npx skills add "\\skills\\yixiaoer" -g -y

使用 CLI 同步 skill

yxer skill sync
yxer skill sync --global

建议在以下场景重新同步：

• yxer --version 升级后
• skills/yixiaoer/SKILL.md 更新后
• skills/yixiaoer/references/domains/ 更新后
• skills/yixiaoer/references/workflows/ 或 skills/yixiaoer/references/cli/ 更新后

面向 AI Agent

如果你是把本仓库接给 AI agent、Codex 或其他命令式助手使用，不要只按一个线性发布流程读取；应先读技能入口，再进入对应 domain 文档，再下钻到 workflow 或平台文档。

统一入口

1. skills/yixiaoer/SKILL.md
2. 再按任务类型继续读取下列 domain 节点

任务路由

• 发布任务：
  • skills/yixiaoer/references/domains/publish.md
  • 继续进入 skills/yixiaoer/references/workflows/common-rules.md、skills/yixiaoer/references/workflows/account-selection.md、skills/yixiaoer/references/workflows/local-vs-cloud.md、skills/yixiaoer/references/workflows/payload-sourcing.md
  • 再按类型进入 publish-video.md、publish-imageText.md、publish-article.md
• 草稿或素材任务：
  • skills/yixiaoer/references/domains/draft-and-material.md
• 发布失败排查 / 历史记录：
  • skills/yixiaoer/references/domains/troubleshooting.md
• 只查账号、环境、skill 同步：
  • skills/yixiaoer/references/domains/accounts-and-env.md
• 安装、升级、分发：
  • skills/yixiaoer/references/domains/install-and-sync.md
• 需要平台差异时，再查：
  • skills/yixiaoer/references/platforms/

推荐约束：

• 优先调用 yxer CLI，通过 prepare / schema fields 了解字段；schema fields 默认返回更紧凑的扁平路径视图，只有需要完整 payload 骨架时再看 schema get
• payload.json 必须使用标准 envelope：action/publishType/platforms/publishArgs
• 账号选择、通道判断、payload 来源、失败排查都应走对应 workflow，不要混写在一个大 prompt 里
• 复杂对象通过查询命令获取，不手写 raw
• 本机发布显式传 --publish-channel local 和 --client-id

常用命令

环境和配置

yxer doctor
yxer config get
yxer config init --api-key 
yxer config set-local-client-id 

账号和资源

yxer accounts list [platform] [--name 关键词] [--status 1] [--json]
yxer accounts update  [--proxy-id ID] [--kuaidaili-area CODE] [--remark 文本] [--group ID] [--dry-run]
yxer upload --file  [--bucket cloud-publish|material-library] [--dry-run]
yxer upload --url  [--bucket cloud-publish|material-library] [--dry-run]
yxer material list [--name ] [--type image|video|file] [--page 1] [--size 100]
yxer material move  --group-id  [--dry-run]
yxer material move-by-name  --group-id  [--dry-run]
yxer material groups [--page 1] [--size 50]

草稿与 DOCX 导入

yxer draft save  [--dry-run]
yxer draft import  --cover  --account-id  [--author 蚁小二] [--original-author ] [--draft-id ] [--dry-run]

微信公众号 DOCX 导入会提取正文内嵌图片并改写为蚁小二稳定 URL；封面必须传入宽度大于高度的横版图片，默认不声明原创，也不会自动裁剪竖版封面。

发布和校验

yxer prepare  
yxer schema fields  
yxer schema get  
yxer validate    [--publish-channel cloud|local] [--client-id ] [--content-file ]
yxer publish    [--publish-channel cloud|local] [--client-id ] [--content-file ] [--dry-run]
yxer publish delete preview 
yxer publish delete from-record  --index N [--dry-run]
yxer publish delete  [--dry-run]

推荐的发布类型只有三种：

• video
• imageText
• article

查询类能力

yxer query categories  [--type video|article]
yxer query locations  [--query 关键词]
yxer query music  [--query 关键词]
yxer query goods  [--query 关键词]
yxer query taobao-guanghe-goods-tabs  --type video|imageText
yxer query taobao-guanghe-goods  --type video|imageText --source SOURCE [--filter-value VALUE] [--second-filter-value VALUE] [--query 关键词] [--next-page TOKEN]
yxer query collections  [--type video|article]
yxer query friends  [--red-id 小红书号] [--query 关键词]
yxer query challenges  [--query 关键词] [--type video]
yxer query records [--platform P] [--limit N] [--status S] [--json]
yxer query account-increments --start-date YYYY-MM-DD --end-date YYYY-MM-DD

account-increments 支持 --group-id 按账号分组、--platform 按平台和 --account-name 按账号名称筛选，同时返回增量数据、dmMessageStats 私信收发统计和 managedAccounts 管理账号详情。私信总计和逐日趋势均按增量账号列表统计；data.accounts 还带每个增量账号的 dmInCount、dmOutCount 和状态。

说明：

• 查询类能力统一使用 yxer query ... 入口，不再保留旧的一层查询命令。

使用说明

默认发布通道

• 用户未明确指定时，默认走云发布。
• 用户明确要求“本机发布 / 本地发布 / 客户端发布”时，必须走本机发布。
• 本机发布必须提供 clientId，可通过 yxer config set-local-client-id 预设。
• validate、publish --dry-run、publish 会共用同一套发布通道解析规则；若已预设默认 clientId，可在本机发布时只传 --publish-channel local。
• publish --dry-run 不创建发布任务；它返回最终请求预览，并在有 API key 的云发布场景执行账号/代理 preflight。local dry-run 不检测客户端在线状态。

推荐任务分流

• 用户要“发布”：先走 skills/yixiaoer/references/domains/publish.md，再进具体 workflow
• 用户要“保存草稿”或“素材库”：先走 skills/yixiaoer/references/domains/draft-and-material.md
• 用户要“查账号”或“看环境”：先走 skills/yixiaoer/references/domains/accounts-and-env.md
• 用户要“修 payload”：先走 skills/yixiaoer/references/domains/publish.md，再下钻 payload-sourcing
• 用户要“排查发布失败”或“看历史记录”：先走 skills/yixiaoer/references/domains/troubleshooting.md

推荐发布顺序

已有完整标准 payload.json 时，发布类任务按这个快速路径执行：

1. yxer validate
2. yxer publish --dry-run
3. 用户授权后 yxer publish

缺账号、字段、资源或动态对象时，先按这个组装路径补齐：

1. yxer doctor
2. yxer accounts list
3. yxer prepare
4. yxer schema fields（必要时再补 yxer schema get）
5. yxer upload
6. 查询分类、位置、音乐等复杂对象
7. 填写 payload.json
8. yxer validate
9. yxer publish --dry-run
10. 用户授权后 yxer publish

上面这 10 步只适用于“从零组装发布 payload”；草稿、素材库、排查等任务不要强行套这条主流程。

Skill 与 CLI 的分工

• README.md：给人看，负责安装和上手。
• skills/yixiaoer/SKILL.md：给 agent 看，负责共享规则和能力索引。
• skills/yixiaoer/references/domains/：给 agent 做任务分流。
• yxer CLI：真正执行账号查询、资源上传、校验和发布。

输出示例

成功输出

{
  "ok": true,
  "action": "doctor",
  "version": "3.1.1",
  "data": {
    "configPath": "C:\\Users\\\\AppData\\Roaming\\yxer\\config.json",
    "apiUrl": "https://www.yixiaoer.cn/api",
    "apiKeyPresent": true
  },
  "_notice": {
    "skills": {
      "current": "3.1.1",
      "target": "3.1.1"
    }
  }
}

失败输出

{
  "ok": false,
  "version": "3.1.1",
  "error": {
    "type": "validation_error",
    "code": "YIXIAOER_USAGE_ERR",
    "message": "clientId must not be empty",
    "hint": "请传入有效的本机发布 clientId。",
    "retryable": false
  }
}

说明：

• stdout 始终输出 JSON 数据
• stderr 只输出诊断、警告、提示和结构化错误
• 成功输出使用 ok/action/version/data
• 失败输出使用 ok/version/error

常见问题

1. doctor 提示 skill 版本不同步

先执行：

yxer update

如果用户明确只想单独同步 skill，也可以：

yxer skill sync
yxer skill sync --global

2. 云发布失败，提示账号代理不存在

• 先检查账号代理配置
• 如需快速绕过云端代理问题，可改用本机发布
• 本机发布前先确认已经配置 clientId
• CLI 默认只返回本机发布 nextCommand，不会自动切换通道；--auto-fallback-local 只适合用户明确授权自动回退的场景。

3. 本机发布失败，提示客户端不在线

• 启动并登录蚁小二客户端
• 重新执行本机发布
• 如果当前不方便保持客户端在线，可改回云发布

4. 用户只说“保存草稿”怎么处理

不要默认。需要先区分：

• 蚁小二草稿
• 平台草稿箱

对应入口：

• 蚁小二草稿：skills/yixiaoer/references/workflows/draft-workflow.md
• 发布失败排查：skills/yixiaoer/references/workflows/publish-troubleshooting.md
• 通道判断：skills/yixiaoer/references/workflows/local-vs-cloud.md
• payload 修订：skills/yixiaoer/references/workflows/payload-sourcing.md

目录结构

README.md
cmd/
internal/
schemas/
skills/
  yixiaoer/
    SKILL.md
      references/  # 打包时从 skills/yixiaoer/references/ 复制
      domains/
      platforms/
references/  # 打包输出，不作为主维护源
tests/
scripts/

文档索引

• 技能入口：skills/yixiaoer/SKILL.md
• 任务分域：skills/yixiaoer/references/domains/
• 命令参考：skills/yixiaoer/references/cli/command-reference.md
• 安装、升级与同步：skills/yixiaoer/references/domains/install-and-sync.md
• 上线流程：skills/yixiaoer/references/go-live-process.md
• 关键词文档：skills/yixiaoer/references/keyword-reference.md
• 使用流程文档：skills/yixiaoer/references/usage-workflow.md
• 工作流正文：skills/yixiaoer/references/workflows/
• 平台文档：skills/yixiaoer/references/platforms/
• 平台文档维护规范：skills/yixiaoer/references/platform-doc-maintenance.md