@yixiaoermail/cli 3.1.0

package/skills/yixiaoer/references/cli/command-reference.md

@@ -0,0 +1,212 @@
+# 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] [--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]
+yxer query music <account_id> [--query 关键词]
+yxer query goods <account_id> [--query 关键词]
+yxer query collections <account_id> [--type video|article]
+yxer query challenges <account_id> [--query 关键词] [--type video]
+yxer query records [--platform P] [--limit N] [--status S] [--json]
+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 小红书 --status 1
+```
+
+### 上传资源
+
+```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>
+```
+
+## 常见工作流入口
+
+- 共享规则：`../yixiaoer-shared.md`
+- 通用规则：`../workflows/common-rules.md`
+- 图文发布：`../workflows/publish-imageText.md`
+- 视频发布：`../workflows/publish-video.md`
+- 文章发布：`../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/skills/yixiaoer/references/cli/skill-install.md

@@ -0,0 +1,65 @@
+# 技能安装与同步
+
+本项目按“CLI 先安装，Skill 再安装”的方式给 AI agent 提供能力。
+
+## 目标
+
+- `yxer` CLI：唯一执行入口，负责真正调用蚁小二 API
+- `SKILL.md`：给 AI agent 的规则、工作流、命令选择说明
+- `README.md`：给仓库维护者的入口说明
+
+也就是说，Skill 不负责执行，它只负责告诉 Agent 何时调用什么 `yxer` 命令。
+
+## 推荐安装流程
+
+1. 安装或编译 `yxer` CLI。
+2. 如果 CLI 来自 npm 成品包，优先直接执行：
+
+```bash
+yxer skill sync
+yxer skill sync --global
+```
+
+3. 如果需要手动查看技能包位置或走回退安装，再运行 `yxer skill show`，拿到当前技能包目录。
+4. 用 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
+```
+
+## 何时需要重新同步
+
+- `yxer --version` 升级后
+- 当前 skill 包中的 `SKILL.md` 更新后
+- `skills/yixiaoer/references/` 中影响 Agent 行为的文档更新后
+
+## 漂移检查
+
+- `yxer skill show` 会显示当前 `skills.stamp` 状态
+- `yxer doctor` 会在 `_notice.skills` 中提示是否需要重新同步
+
+## 设计原则
+
+- 技能负责“让 Agent 会用 CLI”
+- CLI 负责“把事情真正做完”
+- 不再保留默认 Node 脚本执行入口

package/skills/yixiaoer/references/cli-install-uninstall.md

@@ -0,0 +1,196 @@
+# CLI 与 Skill 安装卸载说明
+
+本文档覆盖 `yxer` CLI 的下载/安装、升级、卸载，以及 `yixiaoer` skill 的安装和卸载。
+
+## 1. 环境要求
+
+- Go `1.25.0` 或更高
+- Node.js
+- `npx`
+
+## 2. CLI 下载与安装
+
+当前仓库没有内置“自动下载最新版 CLI”的能力，推荐以下两种获取方式。
+
+### 方式 A：从源码构建
+
+```bash
+git clone <repo>
+cd yixiaoer-skill
+go build -o bin/yxer.exe .
+```
+
+构建完成后，可执行文件位于：
+
+```text
+bin\yxer.exe
+```
+
+### 方式 B：使用发布人员提供的制品包
+
+如果团队已经产出上线包，直接获取其中的 `yxer.exe` 即可，无需本地重新构建。
+
+建议将 `yxer.exe` 放到固定目录，例如：
+
+```text
+C:\tools\yxer\yxer.exe
+```
+
+如需全局直接执行，可把所在目录加入 `PATH`。
+
+## 3. CLI 安装后初始化
+
+```bash
+yxer --version
+yxer config init --api-key <apiKey>
+yxer doctor
+```
+
+如需要同时把蚁小二作为链接应用启用：
+
+```bash
+yxer config init --api-key <apiKey>
+```
+
+## 4. Skill 安装
+
+先确认 skill 包位置：
+
+```bash
+yxer skill show
+```
+
+如果 CLI 通过 npm 成品包装好且技能文件随包分发，优先直接同步：
+
+```bash
+yxer skill sync
+yxer skill sync --global
+```
+
+本地安装：
+
+```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
+```
+
+## 5. 升级方式
+
+### 升级 CLI
+
+当前仓库推荐重新构建或重新分发新版二进制：
+
+```bash
+git pull
+go build -o bin/yxer.exe .
+```
+
+### 升级 Skill
+
+CLI 升级后，必须同步 skill：
+
+```bash
+yxer skill sync
+```
+
+检查状态：
+
+```bash
+yxer update --check
+yxer doctor
+```
+
+## 6. CLI 卸载
+
+### 标准卸载
+
+如果 `yxer.exe` 是单独分发的二进制，删除可执行文件并移除 `PATH` 即可。
+
+例如：
+
+- 删除 `C:\tools\yxer\yxer.exe`
+- 从系统环境变量中移除 `C:\tools\yxer`
+
+### 配置清理
+
+如需要彻底清理本地配置，可删除以下目录中的配置文件：
+
+```text
+%USERPROFILE%\.yxer\config.json
+%USERPROFILE%\.yxer\skills.stamp
+```
+
+说明：
+
+- `config.json` 保存 `apiKey`、本机发布 `clientId` 和 linked app 状态
+- `skills.stamp` 用于记录本地 skill 同步版本
+
+### 源码构建场景
+
+如果 CLI 是在仓库内构建的，可删除构建产物：
+
+```text
+<repo>\bin\yxer.exe
+```
+
+## 7. Skill 卸载
+
+### 推荐做法
+
+优先使用你当前 `skills` 工具所提供的卸载命令卸载 `yixiaoer` skill。
+
+由于不同宿主环境里的 `skills` 工具版本可能不完全一致，建议先查看帮助：
+
+```bash
+npx skills --help
+```
+
+然后按工具实际支持的删除命令执行。
+
+### 手动卸载
+
+如果当前环境没有统一的 skill 删除命令，可以直接删除已安装的 `yixiaoer` skill 目录，并清理版本戳：
+
+```text
+删除已安装的 yixiaoer 技能目录
+删除 %USERPROFILE%\.yxer\skills.stamp
+```
+
+如果你不确定技能安装到了哪里，先执行：
+
+```bash
+yxer skill show
+```
+
+再根据宿主工具实际安装位置清理。
+
+## 8. 卸载后的验证
+
+CLI 卸载后，以下命令应不可再执行：
+
+```bash
+yxer --version
+```
+
+Skill 卸载后，建议确认：
+
+- AI 宿主中不再能读取 `yixiaoer` skill
+- `%USERPROFILE%\.yxer\skills.stamp` 已删除或不再指向旧版本
+
+## 9. 常见建议
+
+- 升级时优先“先替换 CLI，再同步 skill”
+- 卸载时优先“先卸载 skill，再删除 CLI”
+- 如果只是停用能力而不是彻底卸载，保留 `config.json` 会更方便后续恢复

package/skills/yixiaoer/references/domains/accounts-and-env.md

@@ -0,0 +1,37 @@
+# 账号、环境与 Skill 同步
+
+适用范围：用户要检查环境、初始化配置、查询账号、查看 skill 安装状态。
+
+**CRITICAL - 用户只要说“先看看环境/账号/同步状态”，就先停在本域，不要提前进入发布、草稿或素材主流程。**
+
+## 优先读取
+
+1. [`../yixiaoer-shared.md`](../yixiaoer-shared.md)
+2. [`../workflows/account-selection.md`](../workflows/account-selection.md)
+
+## 常用命令
+
+```bash
+yxer doctor
+yxer config get
+yxer config init --api-key <apiKey>
+yxer config set-local-client-id <clientId>
+yxer accounts list [platform] [--name 关键词] [--status 1] [--page 1] [--size 20] [--all] [--json]
+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 毫秒]
+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 skill show
+yxer skill sync [--global]
+```
+
+## 规则
+
+- 首次使用、环境不明、或失败排查后，先 `yxer doctor`
+- `doctor` 失败时先修环境，不继续业务流程
+- 涉及本机发布前的 `clientId` 判断时，先查询现有配置和账号列表
+- `yxer accounts list` 默认查第 `1` 页、每页 `20` 条；传 `--page`、`--size` 可控制单页范围，传 `--all` 时才继续翻页
+- `yxer update-account` 是写操作，正式执行前必须先用同一参数执行 `--dry-run`
+- 命中多个账号时，结构化列出候选并让用户确认；只有一个可用账号时可自动选中并说明
+- 用户明确说“先不要发布，只查环境/账号”时，完成本域后直接停下，不擅自继续发布流程

package/skills/yixiaoer/references/domains/draft-and-material.md

@@ -0,0 +1,29 @@
+# 草稿与素材库
+
+适用范围：用户要保存草稿、登记素材、上传素材到素材库，或先存资源再继续发布。
+
+**CRITICAL - 用户说“草稿”时，MUST 先区分蚁小二草稿、平台草稿、还是仅上传素材；禁止自行猜测。**
+
+## 读取顺序
+
+1. 草稿任务：[`../workflows/draft-workflow.md`](../workflows/draft-workflow.md)
+2. 素材任务：[`../workflows/material-workflow.md`](../workflows/material-workflow.md)
+3. 若随后要直接发布，再切回 [`./publish.md`](./publish.md)
+
+## 常用命令
+
+```bash
+yxer draft save <payload.json> [--dry-run]
+yxer material add --file <文件路径或URL> [--thumb <缩略图路径或URL>] [--type image|video|file] [--dry-run]
+yxer upload --file <file_path> --bucket material-library
+yxer upload --url <resource_url> --bucket material-library
+yxer material create <payload.json> [--dry-run]
+```
+
+## 决策规则
+
+- 用户只说“保存草稿”时，先区分蚁小二草稿和平台草稿，不要自行猜测
+- 用户只想把资源放进素材库时，优先 `material add`
+- 用户已有上传结果，只差登记素材时，再用 `material create`
+- 素材任务不自动进入发布主流程；只有用户明确要“上传后马上发布”时，再切回发布域
+- 用户明确说“先存一下，别发”时，停在本域，不擅自回切发布域

package/skills/yixiaoer/references/domains/install-and-sync.md

@@ -0,0 +1,37 @@
+# 安装、升级与同步
+
+适用范围：用户要安装 skill、重新同步、升级 CLI、查看宿主如何接入该技能。
+
+**CRITICAL - 用户意图是安装、升级或同步时，先完成本域动作，不要跳到发布流程里“顺手再发一次”验证。**
+
+## 优先读取
+
+1. [`../cli/skill-install.md`](../cli/skill-install.md)
+2. [`../cli-install-uninstall.md`](../cli-install-uninstall.md)
+
+## 常用命令
+
+```bash
+yxer skill show
+yxer skill sync
+yxer skill sync --global
+yxer --version
+yxer doctor
+```
+
+## 安装命令
+
+```bash
+yxer skill sync
+yxer skill sync --global
+npx skills add "<repo>\\skills\\yixiaoer" -y
+npx skills add "<repo>\\skills\\yixiaoer" -g -y
+```
+
+## 规则
+
+- 如果 CLI 来自 npm 成品包，优先使用 `yxer skill sync`，让本地随包 skill 直接同步到宿主
+- `yxer --version` 升级后，应提示重新同步 skill
+- `SKILL.md` 或 `references/` 中影响 Agent 行为的文档更新后，应提示重新同步
+- `yxer doctor` 返回 `_notice.skills` 时，优先执行 `yxer skill sync`
+- 用户明确说“只想同步 skill / 看安装方法”时，完成本域说明后直接停下

package/skills/yixiaoer/references/domains/publish.md

@@ -0,0 +1,75 @@
+# 发布与 Payload
+
+适用范围：用户要发布视频、图文、文章，或要修订发布 payload、解释字段归属、确认发布通道。
+
+**CRITICAL - 只要用户意图落在本域，MUST 先读取下方 workflow，再决定是否执行任何 `prepare`、字段查询、`validate` 或 `publish`。**
+**BLOCKING REQUIREMENT - 未完成 `doctor`、账号确认、`prepare`、`schema fields`、`validate`、`publish --dry-run` 前，绝对禁止正式 `publish`。**
+
+## 读取顺序
+
+1. [`../workflows/common-rules.md`](../workflows/common-rules.md)
+2. [`../workflows/account-selection.md`](../workflows/account-selection.md)
+3. [`../workflows/local-vs-cloud.md`](../workflows/local-vs-cloud.md)
+4. [`../workflows/payload-sourcing.md`](../workflows/payload-sourcing.md)
+5. 按类型继续读取：
+   - 图文：[`../workflows/publish-imageText.md`](../workflows/publish-imageText.md)
+   - 视频：[`../workflows/publish-video.md`](../workflows/publish-video.md)
+   - 文章：[`../workflows/publish-article.md`](../workflows/publish-article.md)
+
+## 意图路由
+
+- 用户只说“帮我发一下”“发个抖音/小红书”“发视频/图文/文章”时，直接进入本域，并继续按类型读取 workflow。
+- 用户明确说“先别发，只生成 payload”“帮我修 payload”时，仍进入本域，但最终动作只停留在 payload 修订或 `validate` / `publish --dry-run`。
+- 用户明确说“查为什么发失败了”“解释报错”时，先切 [`./troubleshooting.md`](./troubleshooting.md)，不要直接重试正式发布。
+- 用户明确说“上传素材后马上发”时，先完成素材流程，再回切本域继续执行发布主流程。
+
+## 平台差异入口
+
+- 总索引：[`../platforms/index.md`](../platforms/index.md)
+- 视频平台：[`../platforms/video/index.md`](../platforms/video/index.md)
+- 图文平台：[`../platforms/imageText/index.md`](../platforms/imageText/index.md)
+- 文章平台：[`../platforms/article/index.md`](../platforms/article/index.md)
+
+只有在 `prepare` / `schema get` 之后，且当前 workflow 无法回答平台差异时，才继续读取具体平台文档。
+
+## 强制门禁
+
+- 未执行 `yxer doctor` 不进入发布流程
+- 未确认 `accounts list` 中账号 `status=1` 不继续
+- 未执行 `prepare` / `schema fields` 不组装 payload；只有需要 payload 骨架时再补 `schema get`
+- 未先 `validate` 与 `publish --dry-run` 不执行正式 `publish`
+
+## 常用命令
+
+```bash
+yxer accounts list [platform] [--name 关键词] [--status 1] [--json]
+yxer prepare <platform> <type>
+yxer schema get <platform> <type>
+yxer upload --file <file_path>
+yxer upload --url <resource_url>
+yxer query categories <account_id> [--type video|article]
+yxer query locations <account_id> [--query 关键词] [--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 validate <platform> <type> <payload.json> [--publish-channel cloud|local] [--client-id <clientId>]
+yxer publish <type> <platform> <payload.json> [--publish-channel cloud|local] [--client-id <clientId>] --dry-run
+yxer publish <type> <platform> <payload.json> [--publish-channel cloud|local] [--client-id <clientId>]
+```
+
+## 决策提示
+
+- 用户只说“帮我发”时，默认云发布；明确说“本机发布”“客户端发布”时切到本机通道。
+- 用户要“只生成 payload”时，仍要先走 `prepare` / `schema get` 和字段查询纪律。
+- 用户要填分类、位置、音乐、合集、话题、商品时，先查询，再回填完整对象。
+- 用户要挂载小程序或选择同步发布应用时，先执行 `yxer query miniapps` / `yxer query syncapps`，再把 CLI 返回对象完整回填到 payload。
+- 用户要挂载游戏、绑定热点或选择群聊时，先执行 `yxer query games` / `yxer query hot-events` / `yxer query groups`，再把 CLI 返回对象完整回填到 payload。
+- 用户要按音乐分类找配乐或参加平台活动时，先执行 `yxer query music-categories` / `yxer query activities`，再把 CLI 返回对象完整回填到 payload。

package/skills/yixiaoer/references/domains/troubleshooting.md

@@ -0,0 +1,30 @@
+# 记录与排查
+
+适用范围：用户要查看发布记录、排查失败、解释为什么 `validate` 或 `publish` 报错。
+
+**CRITICAL - 进入本域后，先定位失败阶段，再决定回退到哪一步；不要把“正式重试发布”当成第一反应。**
+
+## 优先读取
+
+1. [`../workflows/publish-troubleshooting.md`](../workflows/publish-troubleshooting.md)
+2. 必要时回读：
+   - [`../workflows/common-rules.md`](../workflows/common-rules.md)
+   - [`../workflows/local-vs-cloud.md`](../workflows/local-vs-cloud.md)
+   - [`./publish.md`](./publish.md)
+
+## 常用命令
+
+```bash
+yxer query records [--platform P] [--limit N] [--status S] [--json]
+yxer validate <platform> <type> <payload.json> [--publish-channel cloud|local] [--client-id <clientId>]
+yxer publish <type> <platform> <payload.json> [--publish-channel cloud|local] [--client-id <clientId>] --dry-run
+yxer doctor
+```
+
+## 排查规则
+
+- 先给出错误阶段和错误摘要，再决定回到哪一步修复
+- `validate` 失败时，优先回查 `prepare`、`schema get` 和字段来源
+- 云发布报代理问题时，可建议改本机发布
+- 本机发布报客户端不在线时，提示用户启动并登录客户端，或改回云发布
+- 用户只说“解释下这条报错”时，可先停留在本域做解释和修复建议，不擅自触发新的发布写操作