baixing-agent-cli 使用说明（Agent）
百姓网 HTTP API 的薄 CLI，入口命令为 baixing（npm 包名 baixing-agent-cli）。若环境中还有 PHP 站内 CLI（如 cli.php），与本 npm 包无关——本包只调对外 HTTP 接口。
前置条件
- Node.js 18+（
fetch、crypto.randomUUID）
安装
唯一对外安装方式：从 npm 安装（勿假定存在私有源码仓库）。
全局安装后命令名为 baixing：
npm install -g baixing-agent-cli
baixing --help
不需要全局安装时可用 npx（同样调用 baixing）：
npx baixing-agent-cli --help
Agent 必须遵守的契约
调用形式
baixing [全局选项] <子命令> [子命令选项] [子命令参数]
- 全局选项：
-v/--verbose（调试信息打到 stderr，不改变 stdout JSON）。 - API 根 URL：内置默认
https://www.baixing.com。一般用法不要要求用户设置环境变量；仅在对接镜像/预发等场景才需要BX_API_BASE_URL或init --base-url。优先级：环境变量BX_API_BASE_URL> 配置文件baseUrl> 默认。
stdout / stderr
| 流 | 用途 |
|---|---|
| stdout | 成功时的主结果：init 成功时为一行 uuid；其余成功子命令多为 格式化 JSON（JSON.stringify(..., null, 2)），可对整段 stdout JSON.parse。post --dry-run 亦为 JSON（含 _baseUrl）。 |
| stderr | 人类可读提示与错误；-v 时含 HTTP 方法与大致 URL。不要把 stderr 当 API 响应解析。 |
建议：成功路径只解析 stdout；失败时读 stderr 文本。
退出码
| 码 | 含义 |
|---|---|
| 0 | 成功（含「已有 uuid 未 force 仍打印已有 uuid」）。 |
| 1 | 失败：参数、网络、非 2xx、JSON 解析失败，或业务 JSON 中 code !== 0。 |
必须用退出码判断成败，不能仅凭 stdout 是否非空。
稳定性与容错
- 优先使用长选项（如
--dry-run、--base-url）作为稳定契约。 - 响应 JSON 结构由服务端决定；解析时应容错未知字段。
推荐自动化流程
baixing init（覆盖旧 uuid：baixing init --force）；从 stdout 取 uuid 或依赖写入后的配置。baixing post -t "<标题>" -c "<正文>"；对接前可用baixing post ... --dry-run。baixing posts或baixing posts --uuid <id>。baixing search <关键词...>（多词空格分隔；整句含空格时对参数加引号）。- 从
search/posts的data.items[].adId取 ID，执行baixing detail <adId>。
多进程/多租户：为不同进程设置不同 BX_CONFIG_PATH，避免互相覆盖 uuid 配置。
子命令速查
| 子命令 | 作用 | 要点 |
|---|---|---|
init | 生成 UUID v4 写入配置 | --base-url 可选（默认即生产根 URL）；--force；已有 uuid 且无 -f 时 stderr 提示、stdout 仍为 uuid、退出 0 |
post | POST /neo/fabu/neoPost | -t、-c 必填；--uuid、--dry-run |
posts | GET /neo/queryByUuid | --uuid、-p/--page、-s/--size（页码从 1） |
search | GET /neo/search | 关键词为参数；无关键词则退出 1 |
detail | GET /neo/detail/<adId> | adId 为非空数字串，来自列表里的 adId |
环境变量
| 变量 | 说明 |
|---|---|
BX_API_BASE_URL | 可选。未设置时使用默认 https://www.baixing.com。只有需要指向非生产根地址时才设置；设置后覆盖配置文件里的 baseUrl。Agent 默认流程中不应向用户索要此项。 |
BX_CONFIG_PATH | 可选（多实例/CI 时用）。配置文件绝对路径；未设置时默认 ~/.config/baixing-agent/config.json（Windows 路径见 npm 包 README）。 |
完整文档
选项表、边界行为与发布说明见 reference.md。