@yixiaoermail/cli 3.1.1 → 3.1.2

package/bin/ensure-executable.js

@@ -0,0 +1,25 @@
+const fs = require("node:fs");
+const os = require("node:os");
+
+function shouldEnsureExecutable(platform) {
+  return platform !== "win32";
+}
+
+function ensureExecutable(binaryPath) {
+  if (!shouldEnsureExecutable(os.platform())) {
+    return;
+  }
+
+  const stat = fs.statSync(binaryPath);
+  const executeBits = 0o111;
+  if ((stat.mode & executeBits) === executeBits) {
+    return;
+  }
+
+  fs.chmodSync(binaryPath, stat.mode | 0o755);
+}
+
+module.exports = {
+  ensureExecutable,
+  shouldEnsureExecutable
+};

package/bin/postinstall.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+const { ensureExecutable } = require("./ensure-executable");
+const { resolveBinaryPath } = require("./resolve-binary");
+
+try {
+  const binaryPath = resolveBinaryPath(__dirname, process.platform, process.arch);
+  if (!binaryPath) {
+    process.exit(0);
+  }
+
+  ensureExecutable(binaryPath);
+} catch (error) {
+  console.error(
+    `[yxer] postinstall failed to ensure executable permission: ${error.message}`
+  );
+  process.exit(0);
+}

package/bin/resolve-binary.js

@@ -0,0 +1,36 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+function getBinaryFilename(platform = os.platform(), arch = os.arch()) {
+  const key = `${platform}/${arch}`;
+  const binaries = {
+    "win32/x64": "yxer-windows-amd64.exe",
+    "win32/arm64": "yxer-windows-arm64.exe",
+    "darwin/x64": "yxer-darwin-amd64",
+    "darwin/arm64": "yxer-darwin-arm64",
+    "linux/x64": "yxer-linux-amd64",
+    "linux/arm64": "yxer-linux-arm64"
+  };
+
+  return binaries[key] || null;
+}
+
+function resolveBinaryPath(baseDir = __dirname, platform = os.platform(), arch = os.arch()) {
+  const filename = getBinaryFilename(platform, arch);
+  if (!filename) {
+    return null;
+  }
+
+  const binaryPath = path.join(baseDir, "..", "dist", filename);
+  if (!fs.existsSync(binaryPath)) {
+    return null;
+  }
+
+  return binaryPath;
+}
+
+module.exports = {
+  getBinaryFilename,
+  resolveBinaryPath
+};

package/bin/yxer.js

@@ -2,24 +2,14 @@
 
 const { spawnSync } = require("node:child_process");
 const fs = require("node:fs");
-const os = require("node:os");
-const path = require("node:path");
+const { ensureExecutable } = require("./ensure-executable");
+const { getBinaryFilename, resolveBinaryPath } = require("./resolve-binary");
 
 function resolveBinary() {
-  const platform = os.platform();
-  const arch = os.arch();
+  const platform = process.platform;
+  const arch = process.arch;
   const key = `${platform}/${arch}`;
-
-  const binaries = {
-    "win32/x64": "yxer-windows-amd64.exe",
-    "win32/arm64": "yxer-windows-arm64.exe",
-    "darwin/x64": "yxer-darwin-amd64",
-    "darwin/arm64": "yxer-darwin-arm64",
-    "linux/x64": "yxer-linux-amd64",
-    "linux/arm64": "yxer-linux-arm64"
-  };
-
-  const filename = binaries[key];
+  const filename = getBinaryFilename(platform, arch);
   if (!filename) {
     console.error(
       JSON.stringify({
@@ -34,8 +24,8 @@ function resolveBinary() {
     process.exit(1);
   }
 
-  const binaryPath = path.join(__dirname, "..", "dist", filename);
-  if (!fs.existsSync(binaryPath)) {
+  const binaryPath = resolveBinaryPath(__dirname, platform, arch);
+  if (!binaryPath || !fs.existsSync(binaryPath)) {
     console.error(
       JSON.stringify({
         error: {
@@ -54,6 +44,7 @@ function resolveBinary() {
 }
 
 const binary = resolveBinary();
+ensureExecutable(binary);
 const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
 
 if (result.error) {

package/package.json

@@ -1,13 +1,19 @@
 {
     "name":  "@yixiaoermail/cli",
-    "version":  "3.1.1",
+    "version":  "3.1.2",
     "description":  "Yixiaoer CLI packaged for npm global installation",
     "bin":  {
                 "yxer":  "bin/yxer.js"
             },
+    "scripts":  {
+                    "postinstall":  "node bin/postinstall.js",
+                    "test":  "node --test test/*.test.js"
+                },
     "files":  [
                   "bin",
                   "dist",
+                  "references",
+                  "schemas",
                   "skills",
                   "README.md"
               ],

package/references/cli/command-reference.md

@@ -0,0 +1,234 @@
+# yxer CLI 命令参考
+
+`yxer` 是本技能唯一执行入口。Agent 和用户都应直接使用它。
+
+## 命令分组
+
+### 环境与版本
+
+```bash
+yxer --version
+yxer doctor
+yxer update [--check] [--global]
+```
+
+### 本地配置
+
+```bash
+yxer config get
+yxer config set-local-client-id <clientId>
+```
+
+### Skill 安装与同步
+
+```bash
+yxer skill show
+yxer skill sync [--global]
+```
+
+### 账号与资源
+
+```bash
+yxer accounts list [platform] [--name 关键词] [--status 1] [--page 1] [--size 20] [--all] [--json]
+yxer upload --file <file_path> [--bucket cloud-publish|material-library] [--dry-run]
+yxer upload --url <resource_url> [--bucket cloud-publish|material-library] [--dry-run]
+```
+
+### 发布与校验
+
+```bash
+yxer validate <platform> <type> <payload.json> [--publish-channel cloud|local] [--client-id <clientId>]
+yxer publish <type> <platform> <payload.json> [clientId] [--dry-run]
+```
+
+### 草稿与素材库
+
+```bash
+yxer draft save <payload.json> [--dry-run]
+yxer material create <payload.json> [--dry-run]
+yxer material add --file <文件路径或URL> [--thumb <缩略图路径或URL>] [--type image|video|file] [--dry-run]
+```
+
+### 查询类能力
+
+```bash
+yxer query categories <account_id> [--type video|article]
+yxer query locations <account_id> [--query 关键词] [--type 0|1|2|3] [--next-page TOKEN]
+yxer query music <account_id> [--query 关键词] [--category-id ID] [--category-name 名称] [--next-page TOKEN]
+yxer query music-categories <account_id>
+yxer query goods <account_id> [--query 关键词] [--next-page TOKEN]
+yxer query collections <account_id> [--type video|article]
+yxer query miniapps <account_id> [--query 关键词]
+yxer query syncapps <account_id>
+yxer query games <account_id> [--query 关键词]
+yxer query hot-events <account_id> [--type video|article]
+yxer query groups <account_id>
+yxer query activities <account_id> [--type video|article] [--category-id ID] [--query 关键词]
+yxer query challenges <account_id> [--query 关键词] [--type video] [--next-page TOKEN]
+yxer query records [--platform P] [--limit N] [--status S] [--json]
+yxer query details <task_set_id>
+yxer query account-overviews --platform P [--name 关键词] [--group 分组] [--login-status 1] [--member-id ID] [--page 1] [--size 10]
+yxer query content-overviews [--platform P] [--account-id ID] [--publish-user-id ID] [--type video|article|miniVideo|dynamic] [--title 关键词] [--publish-start-time 毫秒] [--publish-end-time 毫秒] [--page 1] [--size 10]
+yxer query proxies [--size 9999]
+yxer query proxy-areas
+yxer update-account <account_id> [--proxy-id ID] [--kuaidaili-area CODE] [--remark 文本] [--group ID] --dry-run
+yxer update-account <account_id> [--proxy-id ID] [--kuaidaili-area CODE] [--remark 文本] [--group ID]
+yxer prepare <platform> <type>
+yxer schema fields <platform> <type>
+yxer schema get <platform> <type>
+```
+
+兼容说明：
+
+- 推荐新入口：`yxer query ...`
+- 旧入口如 `yxer categories ...`、`yxer records list ...` 仍可用，但后续文档统一以 `query` 入口为准
+
+## 基本约束
+
+- 发布类型统一使用：`video`、`imageText`、`article`
+- 单次 `yxer publish` 只处理一个平台
+- `publish` 仅支持 `payload.json` 模式
+- 发布前必须先执行 `yxer prepare <platform> <type>` 和 `yxer schema fields <platform> <type>`；`schema fields` 默认返回扁平路径清单，只有需要完整 payload 骨架时再执行 `yxer schema get <platform> <type>`
+- `payload.json` 只支持标准 `publishArgs` 结构，所有平台统一
+- CLI 会根据 `publishArgs` 自动补齐最外层 `cover`、`coverKey`、`desc`、`isDraft`、`isAppContent`
+- 云发布是默认模式
+- 本机发布时必须提供 `clientId`
+- `yxer validate`、`yxer publish --dry-run`、`yxer publish` 使用同一套发布通道解析逻辑
+- 本机发布可通过三种方式提供 `clientId`：
+  - 第四个位置参数：`yxer publish <type> <platform> <payload.json> <clientId>`
+  - flags：`yxer publish <type> <platform> <payload.json> --publish-channel local --client-id <clientId>`
+  - 预设默认值：`yxer config set-local-client-id <clientId>` 后，再执行 `--publish-channel local`
+- 本机发布校验时，推荐在 `validate` 阶段就显式传入 `--publish-channel local`；若未显式传入但 payload 中已写 `publishChannel=local`，CLI 也会尝试从默认配置读取 `clientId`
+- `yxer draft save` 只处理蚁小二内部草稿，不等同于平台草稿箱
+- `yxer material create` 只做素材登记，前提是资源已经通过 `yxer upload --bucket material-library` 上传
+- 推荐优先使用 `yxer material add --file ...`，由 CLI 自动完成上传和素材登记
+- 查询类操作可以直接执行
+- 发布类操作必须遵守“查账号 -> prepare/schema -> 上传资源 -> 查询复杂对象 -> 填 payload -> validate -> publish”顺序
+- 所有请求字段都必须来自 schema、平台文档或 CLI 返回结果；严禁虚构字段、乱猜枚举、手写 `raw` 对象或编造资源元数据
+
+## 快速示例
+
+### 环境检查
+
+```bash
+yxer doctor
+yxer config get
+```
+
+### 查询账号
+
+```bash
+yxer accounts list 抖音 --json
+yxer accounts list 抖音 --page 2 --size 20 --json
+yxer accounts list 小红书 --all --status 1 --json
+yxer accounts list 小红书 --status 1
+```
+
+说明：
+
+- `accounts list` 默认查询第 `1` 页、每页 `20` 条
+- 显式传 `--page`、`--size` 可控制单页查询范围
+- 传 `--all` 时，CLI 才会根据远端返回的分页信号继续翻页汇总后续账号
+- 不会用“当前页已满”来猜测下一页是否存在
+
+### 上传资源
+
+```bash
+yxer upload --file .\cover.jpg --dry-run
+yxer upload --file .\video.mp4
+yxer upload --url https://example.com/demo.jpg
+```
+
+## 推荐发布流程
+
+### 标准 payload 结构
+
+```json
+{
+  "action": "publish",
+  "publishType": "imageText",
+  "platforms": ["小红书"],
+  "publishChannel": "cloud",
+  "publishArgs": {
+    "accountForms": [
+      {
+        "platformAccountId": "<platformAccountId>",
+        "contentPublishForm": {
+          "formType": "task"
+        }
+      }
+    ]
+  }
+}
+```
+
+约束：
+
+- 顶层必须有 `publishArgs`
+- 账号列表必须放在 `publishArgs.accountForms[]`
+- 平台业务字段必须放在 `publishArgs.accountForms[].contentPublishForm`
+- 不再支持顶层 `accountForms`
+- 不再支持直接提交内层业务表单 JSON
+
+### 获取表单字段与 schema
+
+```bash
+yxer prepare 小红书 imageText
+yxer schema fields 小红书 imageText
+yxer schema get 小红书 imageText
+```
+
+### 校验与预览发布
+
+```bash
+yxer validate 小红书 imageText .\payload.json
+yxer publish imageText 小红书 .\payload.json --dry-run
+```
+
+### 本机发布校验
+
+```bash
+yxer validate 抖音 video .\payload.json --publish-channel local --client-id <clientId>
+yxer publish video 抖音 .\payload.json --publish-channel local --client-id <clientId> --dry-run
+```
+
+### 正式发布
+
+```bash
+yxer publish imageText 小红书 .\payload.json
+```
+
+### 本机发布
+
+```bash
+yxer publish video 抖音 .\payload.json --publish-channel local --client-id <clientId>
+```
+
+## 常见工作流入口
+
+- 通用规则：`references/workflows/common-rules.md`
+- 图文发布：`references/workflows/publish-imageText.md`
+- 视频发布：`references/workflows/publish-video.md`
+- 文章发布：`references/workflows/publish-article.md`
+
+## 发布通道约定
+
+- 用户未指定“本机发布 / 本地发布 / 客户端发布”时，Agent 应默认使用云发布。
+- 用户明确要求本机发布，或说明要走本机客户端/本机网络时，Agent 必须显式传 `--publish-channel local`，不要只在说明文字里表达。
+- 若云发布返回“账号代理不存在”等代理相关错误，可建议切换到本机发布。
+- 若本机发布返回“客户端不在线”或“获取在线设备列表失败”，可建议用户启动蚁小二客户端，或改回云发布。
+
+## 输出约定
+
+- 默认输出适合人读
+- 加 `--json` 时输出结构化结果，适合 Agent 二次处理
+- 成功输出格式：`ok/action/version/data`
+- 失败输出格式：`ok/version/error`
+- 错误通过统一错误 envelope 输出
+- `yxer doctor` 可能返回 `_notice.skills`，提示当前 AI skill 与 CLI 版本不同步
+- `yxer update` 当前会同步 AI skill，并给出 CLI 本体更新指引
+
+## 入口约束
+
+- 仓库已移除旧 Node 入口，不再提供脚本兼容通道
+- 未完成 CLI 化的能力只保留文档提示，不代表存在其他可执行入口

package/references/cli/skill-install.md

@@ -0,0 +1,76 @@
+# 技能安装与同步
+
+本项目按“CLI 先安装，Skill 再安装”的方式给 AI agent 提供能力。
+
+## 目标
+
+- `yxer` CLI：唯一执行入口，负责真正调用蚁小二 API
+- `skills/yixiaoer/SKILL.md`：给 AI agent 的共享规则、能力索引和命令探索说明
+- `skills/yixiaoer/references/domains/`：给 AI agent 的任务分域入口
+- `README.md`：给仓库维护者的入口说明
+
+也就是说，Skill 不负责执行，它只负责告诉 Agent 何时调用什么 `yxer` 命令。
+
+## 推荐安装流程
+
+1. 安装或编译 `yxer` CLI。
+2. 运行 `yxer skill show`，拿到当前技能包目录。
+3. 用 skills 工具安装技能：
+
+```bash
+npx skills add "<repo>/skills/yixiaoer" -y
+```
+
+如需全局安装：
+
+```bash
+npx skills add "<repo>/skills/yixiaoer" -g -y
+```
+
+也可以直接让 CLI 代为同步并写入版本戳：
+
+```bash
+yxer skill sync
+yxer skill sync --global
+```
+
+如需统一执行“检查状态 + 同步 skill + 查看 CLI 更新指引”，可运行：
+
+```bash
+yxer update
+yxer update --check
+```
+
+如果 CLI 是通过 npm 安装的，推荐优先使用下面的方式升级 CLI 本体，再同步 skill：
+
+```powershell
+npm install -g @yixiaoermail/cli@latest
+yxer --version
+yxer skill sync
+```
+
+如需全局 skill：
+
+```powershell
+yxer skill sync --global
+```
+
+本次版本更新内容统一查看仓库根目录的 `CHANGELOG.md`。
+
+## 何时需要重新同步
+
+- `yxer --version` 升级后
+- `skills/yixiaoer/SKILL.md` 更新后
+- `skills/yixiaoer/references/domains/` 更新后
+- `references/workflows/` 或 `references/cli/` 中影响 Agent 行为的文档更新后
+
+## 漂移检查
+
+- `yxer skill show` 会显示当前 `skills.stamp` 状态
+- `yxer doctor` 会在 `_notice.skills` 中提示是否需要重新同步
+
+## 设计原则
+
+- 技能负责“让 Agent 先路由到正确 domain，再正确使用 CLI”
+- CLI 负责“把事情真正做完”
+- 不再保留默认 Node 脚本执行入口

package/references/legacy/capabilities.md

@@ -0,0 +1,32 @@
+# 未 CLI 化能力索引
+
+本页用于标记当前 `yxer` CLI 尚未覆盖、或仅部分覆盖的能力。它不是兼容入口说明，也不代表仓库内存在其他可执行主流程。
+
+## 使用规则
+
+1. 如果能力已经有正式 `yxer` 命令，优先直接调用现有命令。
+2. 如果能力只有“部分覆盖”，优先使用现有命令完成已支持部分，剩余字段仅把对应文档当参考。
+3. 如果能力仍“未覆盖”，应优先补成新的 `yxer` 子命令，而不是寻找旧脚本或新增脚本入口。
+
+## 能力状态表
+
+| 能力 | 当前状态 | 推荐/现有命令 | 参考文档 |
+| --- | --- | --- | --- |
+| 蚁小二内部草稿保存 | 已覆盖 | `yxer draft save <payload.json>` | `skills/yixiaoer/references/save-draft.md` |
+| 平台草稿发布 | 部分覆盖 | `yxer publish <type> <platform> <payload.json>` | `skills/yixiaoer/references/save-draft.md` |
+| 素材库登记 | 已覆盖 | `yxer material create <payload.json>` | `skills/yixiaoer/references/material-resource.md` |
+| 素材上传并登记一体化 | 已覆盖 | `yxer material add --file <文件路径或URL>` | `skills/yixiaoer/references/material-resource.md` |
+| 账号数据概览 | 已覆盖 | `yxer query account-overviews --platform P [--name 关键词] [--group 分组] [--login-status 1] [--member-id ID]` | `skills/yixiaoer/references/get-account-overviews.md` |
+| 作品数据概览 | 已覆盖 | `yxer query content-overviews [--platform P] [--account-id ID] [--type video|article|miniVideo|dynamic]` | `skills/yixiaoer/references/get-content-overviews.md` |
+| 征文活动 | 已覆盖 | `yxer query activities <account_id> [--type video|article] [--category-id ID] [--query 关键词]` | `skills/yixiaoer/references/get-publish-activities.md` |
+| 小程序列表 | 已覆盖 | `yxer query miniapps <account_id> [--query 关键词]` | `skills/yixiaoer/references/get-miniapps.md` |
+| 同步发布应用 | 已覆盖 | `yxer query syncapps <account_id>` | `skills/yixiaoer/references/get-sync-apps.md` |
+| 热点列表 | 已覆盖 | `yxer query hot-events <account_id>` | `skills/yixiaoer/references/get-hot-events.md` |
+| 群聊列表 | 已覆盖 | `yxer query groups <account_id>` | `skills/yixiaoer/references/get-groups.md` |
+| 音乐分类 | 已覆盖 | `yxer query music-categories <account_id>` | `skills/yixiaoer/references/get-music-categories.md` |
+| 游戏挂载 | 已覆盖 | `yxer query games <account_id> [--query 关键词]` | `skills/yixiaoer/references/get-games.md` |
+| 代理管理 | 已覆盖 | `yxer query proxies` / `yxer query proxy-areas` / `yxer update-account <account_id> ... --dry-run` | `skills/yixiaoer/references/proxy-management.md` |
+
+## 推荐迁移顺序
+
+当前遗留表中的 CLI 化项目均已覆盖；后续若旧 skill 文档新增能力，应继续按本表补充状态。

package/references/platforms/index.md

@@ -0,0 +1,20 @@
+# 平台参考索引
+
+平台字段和差异说明已收敛到 `skills/yixiaoer/references/platforms/`。根目录索引只作为仓库维护入口，避免 Agent 在多套路径之间摇摆。
+
+## 通用索引
+
+- 图文：`skills/yixiaoer/references/platforms/imageText/index.md`
+- 视频：`skills/yixiaoer/references/platforms/video/index.md`
+- 文章：`skills/yixiaoer/references/platforms/article/index.md`
+
+## 使用原则
+
+1. 先走工作流和 `yxer` CLI。
+2. 只有在构造平台特有字段时，才继续查具体平台文档。
+3. 如果字段来源可以由 `yxer query categories`、`yxer query locations`、`yxer query music` 等命令获得，优先用命令，不要手写对象。
+
+## 维护约束
+
+- Agent 运行时应优先读取 skill 包内部的 `skills/yixiaoer/references/platforms/`
+- 根目录文档用于仓库维护和交叉索引，不再作为 skill 主入口

package/references/workflows/account-selection.md

@@ -0,0 +1,38 @@
+# 账号选择工作流
+
+> 适用范围：任何需要确定 `platform`、`platformAccountId` 或确认账号状态的任务，包括发布、草稿、素材、排查。
+
+## 何时读取
+
+- 用户只说“帮我发”但没给账号
+- 用户给了平台，但没给账号名或账号 ID
+- 用户给了多个候选账号，需要 Agent 选一个
+- 用户要排查“为什么这个账号发不出去”
+
+## 标准步骤
+
+1. 先确定任务平台；平台不明确时，不进入 payload 阶段。
+2. 执行 `yxer accounts list [platform] [--name 关键词] [--json]`。
+3. 优先筛出 `status=1` 的账号。
+4. 结合用户给的账号名、昵称关键词或已有 `platformAccountId` 定位目标账号。
+5. 将选中的 `platformAccountId` 填入 `publishArgs.accountForms[].platformAccountId`。
+
+## 选择规则
+
+- 只有一个 `status=1` 的候选账号：自动选中，并明确告知用户。
+- 有多个 `status=1` 候选账号：列出差异，让用户选择，不要擅自猜测。
+- 没有 `status=1` 账号：停止后续执行，提示用户检查账号登录状态、Cookie 或客户端在线状态。
+- 用户直接给了 `platformAccountId`：仍建议执行 `accounts list` 做存在性确认。
+
+## 推荐命令
+
+```bash
+yxer accounts list 抖音 --json
+yxer accounts list 小红书 --name 关键词 --status 1 --json
+```
+
+## 严禁行为
+
+- 未确认账号有效就填写 `platformAccountId`
+- 多个候选账号时默认取第一个
+- 把账号昵称直接当成 `platformAccountId`