# 小工具 CLI

依据 [小工具Cli接口文档](https://docs.xiaohongshu.com/doc/b42e1b887841b869f74d10ba4e848d79) 及其 Edith 配置实现。接口核对日期：2026-10-21；文档快照 hash：`54375b7456a1ce5ab6fd8589208438e0`。

## 安装和登录

本仓库的 npm 包同时提供 `redskillhub-upload` 和 `redapp` 两个入口。在仓库根目录运行：

```bash
npm install
node cli/redapp/index.mjs --help
```

需要全局命令时，在仓库根目录执行 `npm install -g .`。下文使用安装后的 `redapp`；未安装时可替换为 `node cli/redapp/index.mjs`。

```bash
redapp login
redapp whoami
```

鉴权直接复用现有 Skill CLI：同一登录、扫码提示、凭证文件、scope、自动续期、Bearer 请求头和 prod/beta 隔离逻辑。已经使用 `redskillhub-upload login` 登录过的账号无需再登录。`redapp login --cancel` 取消等待中的授权，`redapp logout` 删除当前环境的共享凭证，也会影响 Skill CLI。

所有接口命令支持 `--env prod|beta`（默认 prod）、`--api-base <URL>` 和 `--agent`。环境域名和 `SKILLHUB_UPLOAD_API_BASE` 的优先级与 Skill CLI 一致；beta 默认 `https://edith-qinweiheng.sl.beta.xiaohongshu.com`。若部署使用其他网关，显式传入后端确认的 `--api-base`；不要混用环境凭证。

除上传外，小工具接口都要求服务端分配的 `source`。通过 `--source` 或环境变量设置：

```bash
export REDAPP_SOURCE='填写服务端分配的来源'
```

文档中的 `cowork` 只是示例，并不代表当前账号已获分配。Edith 入参映射中的 `userId` 来自 `context:c_current_user_id`；CLI 不接受伪造用户 ID，也不读取浏览器 Cookie。

## 本地调试：dev

依据 [小工具模拟器 npm 接入指南](https://docs.xiaohongshu.com/doc/39ecf168ce62eed3ffe16f8c32d3a2ad)（2026-10-22，hash `f89e6505c9efb748e1aa12f7f9161f9d`），使用 `@skillbuilder/miniapp-simulator/workbench/server`。CLI 根据 `--env` 选择地址，并显式调用 `startWorkbenchServer({ rootDir, remote: { serviceUrl } })`，覆盖 SDK 的默认地址。此参数已核对当前固定版本 npm 包的类型声明和服务端实现（2026-10-26）。

需要 **Node.js 20+**；其他发布命令仍支持 Node.js 18。在静态产物目录启动，或明确传入目录：

```bash
redapp dev --dir "./dist" --agent
redapp dev --dir "./dist" --no-open --env beta --agent
redapp dev --help --agent
```

- `--dir` 默认当前目录，根目录需包含 index.html，或只有一个 .html 文件。传入已构建的产物，不传 ZIP；含 node_modules 或 .git 的项目根目录会被拒绝。CLI 不负责 Vue/React 构建，不要把凭证、源码等无关文件放进静态目录。
- 首次执行通过 npm 安装公开包 `@skillbuilder/miniapp-simulator@0.2.0`。不强制指定 registry：未配置时使用 npm 默认官方源 `https://registry.npmjs.org/`，支持 `npm_config_registry`、用户级 `~/.npmrc`（包括 `@skillbuilder:registry`）以及 `npm_config_userconfig`。安装在独立缓存目录执行，不自动读取调用目录的项目 `.npmrc`；临时换源可用 `npm_config_registry=https://你的镜像地址/ redapp dev --dir "./dist" --env beta`，已有 scope 专属源仍按 npm 规则生效。SDK 与 npm 下载缓存都放在 `~/.skillhub-upload/simulator/`，可通过 `SKILLHUB_UPLOAD_HOME` 改根目录；不改当前项目 package.json，也不让其他 CLI 命令依赖模拟器包。安装禁用 lifecycle scripts，后续复用该版本缓存，换源不会强制重新安装已有 SDK。
- 默认打开浏览器；`--no-open` 只打印 URL。返回 `RESULT_JSON` 的 `status=ready` 和 `data.url` 表示本地服务已启动，进程继续运行；Agent 应保留该进程会话，使用实际返回地址。Ctrl+C 或 SIGTERM 会调用 SDK close，关闭服务与监听；关闭失败返回非零退出码。
- 固定监听 `127.0.0.1`、随机端口。`--env prod` 或省略 `--env` 时连接 `https://miniapp-sandbox.xiaohongshu.com/simulator/`；`--env beta` 时连接 `https://miniapp-sandbox.beta.xiaohongshu.com/simulator/`。ready 输出中的 `data.environment` 为实际选用的 `prod` 或 `beta`。beta 域名需要具备相应网络访问条件，外网调试使用默认 prod。模拟器服务不是 Edith 网关，不支持 `--api-base`、`--source`、`--host`、`--port`、`--entry`，也不使用发布 token。`SKILLHUB_UPLOAD_API_BASE` 不影响 dev。
- HTML/JS/CSS 修改会自动重载；只改图片、字体、音频、JSON 时在工作台点“重新运行”。工作台依赖远程模拟器网络，外链资源可能受 CSP 限制。本地服务启动不等于远端渲染验证通过；Windows/Linux 的真实使用仍需各平台验收。

`dev` 不上传、不送审，不需要 dry-run/confirm，也不能替代发布流程要求的手机扫码预览。浏览器无法自动打开时会保留服务并打印手动访问地址；安装失败先核对网络、npm registry 配置及目标版本是否可用，不能用发布登录修复。`DEV_SDK_INVALID` 时按错误中的路径检查该版本缓存，必要时移走损坏目录再启动；不要清除发布凭证。

## 查询

```bash
redapp config
redapp list --page-num 1 --page-size 20
redapp status --app-id '<小工具ID>'
redapp history --app-id '<小工具ID>'
```

`config` 返回 `categories` 和 `authorizations`；提交时使用其中的 `code`。
`list` 每次查询一页，返回 `apps`、`total`；继续查询时递增 `--page-num`。
`status` 返回小工具当前命中的版本、展示状态、驳回原因。详情接口不支持指定版本号，不提供下载代码包能力。

两种状态含义不同，输出保留原值并补充中文标签：

| 数值 | 展示状态 `status` | 历史版本审核状态 `auditStatus` |
| --- | --- | --- |
| -1 | 未知 | 历史版本 |
| 0 | 未发布 | 未知 |
| 1 | 审核中 | 审核中 |
| 2 | 已发布 | 审核通过 |
| 3 | 未通过 | 审核驳回 |
| 4 | 已下架 | 创作者撤回 |

## 上传 ZIP、图标、封面

准备根目录含 `index.html` 的 ZIP，例如在构建产物目录执行 `zip -r ../app.zip .`。不要把整个构建目录再套一层放入 ZIP。

每个写入操作分两步：先检查 dry-run 输出，再复制对应的 `plan.planHash` 确认执行：

```bash
redapp upload --file './app.zip' --type pkg --dry-run
redapp upload --file './app.zip' --type pkg --confirm '<上一步的planHash>'

redapp upload --file './icon.png' --type image --dry-run
redapp upload --file './icon.png' --type image --confirm '<图标的planHash>'

redapp upload --file './cover.png' --type image --dry-run
redapp upload --file './cover.png' --type image --confirm '<封面的planHash>'
```

成功输出 `data.fileId`、`data.md5`、`data.sha256`、`data.size`。记录 ZIP 的 fileId 和 md5，以及两张图片的 fileId，供送审或预览使用。

上传复用 `/api/sns/v2/red_skill/upload/permit` 和仓库的 COS/ROS 上传实现；ZIP 场景为 `spectrum/red_app`，图片场景为 `spectrum/red_skill_tool_image`。这两个 scene 来自创服平台现有上传配置。不会调用文档中已划掉的 URL 文件转存 RPC。

本地限制：单文件非空且不超过 10 MiB；ZIP 根目录必须有 `index.html`，解压大小不超过 30 MiB，并拒绝损坏包、重复路径、越界路径和符号链接；图片支持 PNG、JPEG、GIF、WebP。服务端上传策略可能进一步限制大小、格式及图像尺寸。本地检查通过不等于服务端接收成功。

## 创建和送审新版本

保存 `submit.json`，替换下面的 fileId、MD5 和类目编码：

```json
{
  "appName": "我的小工具",
  "slogan": "一句话简介",
  "iconFileId": "图标上传返回的fileId",
  "coverFileId": "封面上传返回的fileId",
  "version": "1.0.0",
  "pkgFileId": "ZIP上传返回的fileId",
  "md5": "替换为ZIP上传返回的32位md5",
  "categories": ["替换为config返回的类目code"],
  "authorizations": []
}
```

```bash
redapp submit --file './submit.json' --dry-run
redapp submit --file './submit.json' --confirm '<planHash>'
```

第一次创建不填 `appId`；追加新版本时添加已有 `appId`，并修改 `version` 为未使用过的三段式版本号。`categories` 当前只能包含一个编码。`authorizations` 可为空数组；需要权限时使用 `config` 返回的权限编码。确认提交时会再次查询配置并校验编码。

成功的顶层 `status: submitted` 表示服务端已接收送审；不表示审核通过或已发布。使用 `redapp status --app-id '<返回的appId>'` 查询后续状态。

## 修改基础信息

保存 `edit.json`，只包含目标 `appId` 和待修改字段。`appName`、`slogan`、`iconFileId`、`coverFileId` 至少提供一项，省略的字段保留原值。传入值必须是非空白字符串，不能用 null 或空串清除资料。名称和简介各最多 14 个字符，CLI 会在 dry-run 和实际请求前校验（按 JavaScript `.length` / UTF-16 计数）。

例如只修改简介：

```json
{
  "appId": "REPLACE_WITH_EXISTING_APP_ID",
  "slogan": "寻找画面中的不同"
}
```

替换真实 appId 后执行：

```bash
redapp edit --source thirdAgent --env beta --file './edit.json' --dry-run --agent
```

核对计划并取得用户授权后，使用同一文件和真实 planHash 执行：

```bash
redapp edit --source thirdAgent --env beta --file './edit.json' --confirm 'REPLACE_WITH_DRY_RUN_PLAN_HASH' --agent
```

只改名称不需要获取或上传图标。查询结果中的 `description` 对应写入字段 `slogan`；`iconUrl/coverUrl` 是展示 URL，不能作为 fileId。更换图片时使用上传回执中的 fileId。改基础信息仍进入审核流程，执行后用 status 核对；修改代码包使用 submit 新版本。

局部编辑需配套部署后端 `validateBaseInfo` 修复；旧服务若仍拒绝缺省字段，应更新后端，不能猜测 fileId 或自动重试。

## 手机预览

保存 `preview.json`：

```json
{
  "pkgFileId": "ZIP上传返回的fileId",
  "md5": "替换为ZIP上传返回的32位md5",
  "appName": "预览小工具",
  "version": "1.0.0"
}
```

`pkgFileId` 和 `md5` 必填；`appName`、`iconFileId`、`version` 可选。

```bash
redapp preview --file './preview.json' --dry-run
redapp preview --file './preview.json' --confirm '<planHash>' --qr-out './preview.png'
```

返回 `previewUrl` 和预览 `appId`。指定 `--qr-out` 会生成 PNG 二维码，输出绝对路径 `qrCodePath`，不会覆盖已有文件。如果远端预览创建成功而本地二维码写入失败，结果保留预览链接并附上 `qrError`，无需重复创建预览。

## 确认、错误与自动化

- dry-run 只检查本地输入并生成计划，不登录、不请求接口、不上传。先登录再 dry-run 可以把计划绑定到账号。
- 确认哈希绑定命令、账号、环境、网关和完整输入；上传另绑定文件内容哈希。上述任一项变化都要重新 dry-run。JSON 字段顺序变化不影响哈希。
- 计划不是服务端幂等键，不要把同一个确认命令盲目重复执行。CLI 不自动重试写入。
- `OUTCOME_UNKNOWN` 表示写请求发生网络错误、服务端 5xx/408 或响应不可解析。先查询列表、状态和历史版本确认结果。首次创建可能没有拿到 appId，此时从列表查找；预览结果未知时需人工核对后决定是否重建。
- `AUTH_REQUIRED` 表示 401/403。检查当前环境的登录和服务端 scope/路由授权；本地 token 有效不保证小工具接口已授权。不会退回 Cookie 鉴权。
- `API_REJECTED` 是服务端明确拒绝；`INVALID_ARGS` 是本地参数错误；`LOCAL_VALIDATION_FAILED` 是本地文件检查失败。错误退出码非零。
- 输出沿用 `RESULT_JSON:<json>`；登录交互使用 `PROMPT:<json>`，上传进度使用 `UPLOAD_PROGRESS:<number>`。调用程序应按行前缀解析。

## 接口映射与验证范围

| 命令 | HTTP 接口（前缀 `/api/sns/v2/creator/red_app/third`） | Edith API ID |
| --- | --- | --- |
| config | GET `/config` | 53537 |
| list | GET `/list`，分页字段 `page_num/page_size` | 53566 |
| status | GET `/detail`，字段 `appId` | 53556 |
| history | GET `/history_version`，字段 `appId` | 53573 |
| submit | POST `/save` | 53555 |
| edit | POST `/base/save` | 53572 |
| preview | POST `/preview_code` | 53570 |

上传授权参考文档中的 Edith API 42274。其余开放口令、发布笔记挂载、下载、上/下架、删除等没有在此 CLI 中扩展。

验证命令：`npm test`、`npm pack --dry-run`。自动化测试使用模拟 HTTP/COS，覆盖字段契约、确认门槛、账号隔离、共享凭证续期、文件完整性和错误处理。实际环境的 source 分配、Bearer 接受情况、上传和送审仍需线上联调确认。
