redskillhub-upload 1.0.0-alpha.2 → 1.0.0-alpha.3

package/README.md

@@ -25,10 +25,12 @@ All paths and hosts are centralized in `cli/config.mjs` (`PATHS` + `DEFAULT_API_
 | `OAS_ACCESS_TOKEN` | `/api/sns/v1/oauth2/access_token` | `DEFAULT_OAS_BASE` | 用授权码换取 access_token |
 | `OAS_REFRESH_TOKEN` | `/api/sns/v1/oauth2/refresh_token` | `DEFAULT_OAS_BASE` | 用 refresh_token 续期 access_token |
 
-- `DEFAULT_API_BASE` = `https://edith-skillhub.sl.beta.xiaohongshu.com` — 业务接口
-- `DEFAULT_OAS_BASE` = `https://openaccount.beta.xiaohongshu.com` — OAuth2 开放平台接口
+- `DEFAULT_API_BASE` = `https://edith.xiaohongshu.com` — 生产业务接口
+- `BETA_API_BASE` = `https://edith.beta.xiaohongshu.com` — beta 业务接口
+- `DEFAULT_OAS_BASE` = `https://openaccount.xiaohongshu.com` — OAuth2 开放平台接口
+- 所有命令都支持 `--env prod|beta`，默认 `prod`；`--env beta` 时业务接口使用 `BETA_API_BASE`
 - 业务接口 host 可通过 `--api-base` 参数或 `SKILLHUB_UPLOAD_API_BASE` 环境变量覆盖
-- OAS 换 token 如需 confidential client 凭证，通过 `SKILLHUB_UPLOAD_APP_SECRET` 注入；不要写入仓库或命令行参数
+- OAS 换 token 默认使用内置应用凭证；可通过 `SKILLHUB_UPLOAD_APP_SECRET` 覆盖
 
 ## Auth Flow
 
@@ -40,6 +42,8 @@ All paths and hosts are centralized in `cli/config.mjs` (`PATHS` + `DEFAULT_API_
 
 `login` / `whoami` 仍保留用于手动登录和状态诊断。
 
+设备码响应中的 `authorize_common_url` 专用于生成二维码，`authorize_h5_url` 专用于返回可点击/复制的授权链接；Agent 模式会同时输出二维码图片路径和 H5 链接。
+
 ## Local Dry Run
 
 ```bash
@@ -53,14 +57,23 @@ Dry-run examples may use numeric tag IDs because the backend contract accepts `c
 ## Commands
 
 ```bash
-redskillhub-upload login
-redskillhub-upload login --agent
-redskillhub-upload login --cancel
-redskillhub-upload publish /absolute/path/to/skill
-redskillhub-upload publish /absolute/path/to/skill --agent
-redskillhub-upload publish /absolute/path/to/skill.zip --agent
-redskillhub-upload whoami
-redskillhub-upload logout
+redskillhub-upload login --env prod
+redskillhub-upload login --agent --env prod
+redskillhub-upload login --cancel --env prod
+redskillhub-upload publish /absolute/path/to/skill --env prod
+redskillhub-upload publish /absolute/path/to/skill --agent --env prod
+redskillhub-upload publish /absolute/path/to/skill.zip --agent --env prod
+redskillhub-upload whoami --env prod
+redskillhub-upload logout --env prod
+```
+
+所有命令默认使用生产环境。验证 beta 环境时在命令末尾追加 `--env beta`，例如：
+
+```bash
+redskillhub-upload login --agent --env beta
+redskillhub-upload publish /absolute/path/to/skill --agent --env beta
+redskillhub-upload whoami --env beta
+redskillhub-upload logout --env beta
 ```
 
 ## Agent Protocol

package/cli/auth-prompt.mjs

@@ -11,22 +11,34 @@ export async function renderDeviceAuthPrompt(payload, options = {}) {
     stream = process.stdout,
     qrCode = QRCode
   } = options;
+  const authorizeCommonUrl = payload.authorizeCommonUrl || payload.authorizeUrl || '';
+  const authorizeH5Url = payload.authorizeH5Url || payload.authorizeUrl || '';
+  if (!authorizeCommonUrl || !authorizeH5Url) {
+    throw new Error('授权响应缺少 authorize_common_url 或 authorize_h5_url');
+  }
+  const promptPayload = {
+    ...payload,
+    authorizeCommonUrl,
+    authorizeH5Url,
+    // 保留 authorizeUrl 作为 Agent 协议的 H5 链接兼容字段。
+    authorizeUrl: authorizeH5Url
+  };
 
   if (agent) {
     const qrCodePath = getAuthQrPath(env);
     await fs.mkdir(path.dirname(qrCodePath), { recursive: true, mode: 0o700 });
-    await qrCode.toFile(qrCodePath, payload.authorizeUrl, {
+    await qrCode.toFile(qrCodePath, authorizeCommonUrl, {
       type: 'png',
       width: 512,
       margin: 2,
       errorCorrectionLevel: 'M'
     });
     await fs.chmod(qrCodePath, 0o600);
-    writePrompt({ ...payload, qrCodePath }, stream);
+    writePrompt({ ...promptPayload, qrCodePath }, stream);
     return;
   }
 
-  const qr = await qrCode.toString(payload.authorizeUrl, {
+  const qr = await qrCode.toString(authorizeCommonUrl, {
     type: 'terminal',
     small: true,
     errorCorrectionLevel: 'M'
@@ -34,8 +46,7 @@ export async function renderDeviceAuthPrompt(payload, options = {}) {
   const minutes = Math.max(1, Math.ceil(Number(payload.expiresInSeconds || 0) / 60));
   stream.write(`${qr}\n`);
   stream.write(`${payload.message}\n`);
-  stream.write(`授权链接：${payload.authorizeUrl}\n`);
+  stream.write(`授权链接：${authorizeH5Url}\n`);
   stream.write(`授权码：${payload.userCode}\n`);
   stream.write(`有效期：${minutes} 分钟\n`);
 }
-

package/cli/auth.mjs

@@ -4,6 +4,7 @@ import path from 'node:path';
 import {
   DEFAULT_API_BASE,
   DEFAULT_APP_ID,
+  DEFAULT_APP_SECRET,
   DEFAULT_OAS_BASE,
   DEFAULT_SCOPE,
   DEFAULT_SCOPES,
@@ -108,7 +109,10 @@ function unwrapResponseBody(body) {
 }
 
 function resolveAppSecret(flags = {}, env = process.env) {
-  return flags.appSecret || flags['app-secret'] || env.SKILLHUB_UPLOAD_APP_SECRET || '';
+  return flags.appSecret
+    || flags['app-secret']
+    || env.SKILLHUB_UPLOAD_APP_SECRET
+    || DEFAULT_APP_SECRET;
 }
 
 function buildTokenRequestBody(fields = {}) {
@@ -160,10 +164,19 @@ function assertTokenResponseAccepted(body, errorCode, fallbackMessage) {
 
 function normalizeDeviceCodePayload(body) {
   const data = unwrapResponseBody(body);
+  const legacyAuthorizeUrl = data.authorizeUrl || data.authorize_url || '';
+  const authorizeCommonUrl = data.authorizeCommonUrl
+    || data.authorize_common_url
+    || legacyAuthorizeUrl;
+  const authorizeH5Url = data.authorizeH5Url
+    || data.authorize_h5_url
+    || legacyAuthorizeUrl;
   return {
     deviceCode: data.deviceCode || data.device_code || '',
     userCode: data.userCode || data.user_code || '',
-    authorizeUrl: data.authorizeUrl || data.authorize_url || '',
+    authorizeCommonUrl,
+    authorizeH5Url,
+    authorizeUrl: authorizeH5Url,
     expiresInSeconds: data.expiresInSeconds || data.expires_in_seconds,
     pollIntervalSeconds: data.pollIntervalSeconds || data.poll_interval_seconds
   };
@@ -363,7 +376,7 @@ export async function login({
     }
   }
 
-  const apiBase = resolveApiBase(flags);
+  const apiBase = resolveApiBase(flags, env);
 
   // 从磁盘恢复未完成的授权状态，避免进程重启后要求用户重新授权
   let pending = await readPendingAuth(env, now);
@@ -372,7 +385,8 @@ export async function login({
     codeVerifier = pending.codeVerifier;
     await renderDeviceAuthPrompt({
       type: 'auth_device_code',
-      authorizeUrl: pending.authorizeUrl,
+      authorizeCommonUrl: pending.authorizeCommonUrl || pending.authorizeUrl,
+      authorizeH5Url: pending.authorizeH5Url || pending.authorizeUrl,
       userCode: pending.userCode,
       expiresInSeconds: Math.round((pending.expiresAtMs - now()) / 1000),
       message: '检测到未完成的授权，继续等待中（无需重新打开授权链接）'
@@ -384,7 +398,9 @@ export async function login({
     await writePendingAuth(env, {
       deviceCode: device.deviceCode,
       codeVerifier: pkce.codeVerifier,
-      authorizeUrl: device.authorizeUrl,
+      authorizeCommonUrl: device.authorizeCommonUrl,
+      authorizeH5Url: device.authorizeH5Url,
+      authorizeUrl: device.authorizeH5Url,
       userCode: device.userCode,
       pollIntervalSeconds: device.pollIntervalSeconds || 5,
       expiresAtMs: now() + (device.expiresInSeconds || 600) * 1000
@@ -392,7 +408,8 @@ export async function login({
     pending = await readPendingAuth(env, now);
     await renderDeviceAuthPrompt({
       type: 'auth_device_code',
-      authorizeUrl: device.authorizeUrl,
+      authorizeCommonUrl: device.authorizeCommonUrl,
+      authorizeH5Url: device.authorizeH5Url,
       userCode: device.userCode,
       expiresInSeconds: device.expiresInSeconds || 600,
       message: '请用手机自带浏览器打开授权链接，页面会自动跳转至小红书 App 授权；授权页输入授权码后 CLI 会自动轮询'

package/cli/config.mjs

@@ -2,11 +2,13 @@ import os from 'node:os';
 import path from 'node:path';
 
 export const DEFAULT_API_BASE = 'https://edith.xiaohongshu.com';
+export const BETA_API_BASE = 'https://edith.beta.xiaohongshu.com';
 export const DEFAULT_OAS_BASE = 'https://openaccount.xiaohongshu.com';
 export const DEFAULT_APP_ID = 'xhsyfHfmZQAQ24o';
+export const DEFAULT_APP_SECRET = 'skHlFZ8BTk2bVmsSt1aYjv1NxcJjuOwhSev4oraniDa6eyn8L9oqBWvCtsEBnmCmWG';
 export const DEFAULT_SCOPES = ['base_info', 'skill_publish'];
 export const DEFAULT_SCOPE = DEFAULT_SCOPES.join(',');
-
+ 
 export const PATHS = {
   UPLOAD_TOKEN: '/api/sns/v2/red_skill/upload/permit',
   SUBMIT_SKILL_VERSION: '/api/sns/v1/creator/red_skill/cli_submit_skill_version',
@@ -46,6 +48,16 @@ export function getAuthQrPath(env = process.env) {
   return path.join(getHomeDir(env), 'auth-qr.png');
 }
 
-export function resolveApiBase(flags = {}) {
-  return flags.apiBase || process.env.SKILLHUB_UPLOAD_API_BASE || DEFAULT_API_BASE;
+export function resolveApiEnvironment(flags = {}) {
+  const value = String(flags.env || 'prod').trim().toLowerCase();
+  if (value !== 'prod' && value !== 'beta') {
+    throw new TypeError(`--env 仅支持 prod 或 beta，当前值：${flags.env}`);
+  }
+  return value;
+}
+
+export function resolveApiBase(flags = {}, env = process.env) {
+  if (flags.apiBase) return flags.apiBase;
+  if (env.SKILLHUB_UPLOAD_API_BASE) return env.SKILLHUB_UPLOAD_API_BASE;
+  return resolveApiEnvironment(flags) === 'beta' ? BETA_API_BASE : DEFAULT_API_BASE;
 }

package/cli/fetch.mjs

@@ -1,9 +1,9 @@
 import http from 'node:http';
 import https from 'node:https';
 import tls from 'node:tls';
-import { DEFAULT_API_BASE } from './config.mjs';
+import { BETA_API_BASE } from './config.mjs';
 
-const DEFAULT_API_HOST = new URL(DEFAULT_API_BASE).hostname;
+const BETA_API_HOST = new URL(BETA_API_BASE).hostname;
 const BETA_WILDCARD_SAN = 'DNS:*.beta.xiaohongshu.com';
 
 function resolveUrl(input) {
@@ -24,7 +24,7 @@ export function isDefaultBetaApiAltNameError(input, error) {
   try {
     const url = resolveUrl(input);
     return url.protocol === 'https:'
-      && url.hostname === DEFAULT_API_HOST
+      && url.hostname === BETA_API_HOST
       && resolveErrorCode(error) === 'ERR_TLS_CERT_ALTNAME_INVALID';
   } catch {
     return false;
@@ -37,7 +37,7 @@ export function checkDefaultBetaApiServerIdentity(host, cert) {
     return undefined;
   }
   if (
-    host === DEFAULT_API_HOST
+    host === BETA_API_HOST
     && error.code === 'ERR_TLS_CERT_ALTNAME_INVALID'
     && String(cert?.subjectaltname || '').includes(BETA_WILDCARD_SAN)
   ) {
@@ -87,7 +87,7 @@ export function nodeRequestFetch(input, init = {}) {
     method: init.method || 'GET',
     headers: normalizeHeaders(init.headers)
   };
-  if (url.protocol === 'https:' && url.hostname === DEFAULT_API_HOST) {
+  if (url.protocol === 'https:' && url.hostname === BETA_API_HOST) {
     options.checkServerIdentity = checkDefaultBetaApiServerIdentity;
   }
 

package/cli/index.mjs

@@ -12,7 +12,7 @@ import {
 } from './submit.mjs';
 import { uploadBundle } from './upload.mjs';
 import { askAgent, confirmAgent, createPromptSession } from './prompt.mjs';
-import { TOKEN_REFRESH_BUFFER_MS } from './config.mjs';
+import { TOKEN_REFRESH_BUFFER_MS, resolveApiEnvironment } from './config.mjs';
 import { loadContentTags } from './tags.mjs';
 
 function normalizeFlagName(name) {
@@ -186,6 +186,11 @@ export async function main(argv = process.argv.slice(2), env = process.env, io =
       ExitCodes.INVALID_ARGS
     );
   }
+  try {
+    resolveApiEnvironment(flags);
+  } catch (error) {
+    throw new SkillhubUploadError('INVALID_ARGS', error.message, ExitCodes.INVALID_ARGS);
+  }
   if (command === 'whoami') {
     const { readCredentials, maskCredentials } = await import('./auth.mjs');
     writeResult({ status: 'ok', command, credentials: maskCredentials(await readCredentials(env)) }, out);
@@ -278,12 +283,14 @@ export async function main(argv = process.argv.slice(2), env = process.env, io =
         fetchImpl: io.fetchImpl,
         cosFactory: io.cosFactory,
         uploadFileImpl: io.uploadFileImpl,
-        progressStream: io.progressStream || out
+        progressStream: io.progressStream || out,
+        env
       });
       const submitted = await submitSkillVersion(attachUploadResult(confirmedPayload, upload), {
         flags: publishFlags,
         accessToken: credentials.accessToken,
-        fetchImpl: io.fetchImpl
+        fetchImpl: io.fetchImpl,
+        env
       });
       writeResult({ status: 'submitted', response: submitted }, out);
       return;

package/cli/submit.mjs

@@ -200,7 +200,7 @@ function isRejectedBody(body) {
 }
 
 export async function submitSkillVersion(payload, options = {}) {
-  const apiBase = options.apiBase || resolveApiBase(options.flags || {});
+  const apiBase = options.apiBase || resolveApiBase(options.flags || {}, options.env || process.env);
   const fetchImpl = options.fetchImpl || compatibleFetch;
   const sensitiveValues = collectSensitiveValues(payload, options.accessToken);
   let response;

package/cli/tags.mjs

@@ -53,9 +53,10 @@ export async function fetchContentTags({
   fetchImpl = compatibleFetch,
   apiBase,
   signal,
-  flags = {}
+  flags = {},
+  env = process.env
 } = {}) {
-  const base = apiBase || resolveApiBase(flags);
+  const base = apiBase || resolveApiBase(flags, env);
   const url = `${base}${PATHS.QUERY_CONTENT_TAG_CONFIG}?material_id=${CONTENT_TAG_MATERIAL_ID}&module_id=${CONTENT_TAG_MODULE_ID}`;
   const response = await fetchImpl(url, { method: 'GET', signal });
   if (!response.ok) {
@@ -130,7 +131,7 @@ export async function loadContentTags({
 
   const { signal, cancel } = withTimeout(timeoutMs);
   try {
-    const tags = await fetchContentTags({ fetchImpl, flags, signal });
+    const tags = await fetchContentTags({ fetchImpl, flags, env, signal });
     cancel();
     await writeCachedContentTags(cachePath, tags, nowMs);
     return tags;

package/cli/upload.mjs

@@ -176,7 +176,7 @@ export async function uploadBundle(bundle, options = {}) {
     };
   }
 
-  const apiBase = options.apiBase || resolveApiBase(options.flags || {});
+  const apiBase = options.apiBase || resolveApiBase(options.flags || {}, options.env || process.env);
   const token = await requestUploadToken({
     apiBase,
     accessToken: options.accessToken,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redskillhub-upload",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "type": "module",
   "publishConfig": {
     "access": "public",

package/skill/SKILL.md

@@ -1,21 +1,37 @@
 ---
 name: redskillhub-upload
-description: 当用户要求按照 upload.md 将本地 Skill 上传到小红书 SkillHub 时使用。通过 Red Skill Upload CLI 完成授权、打包、上传和提交确认。
+description: 当用户要求安装或更新 redskillhub-upload、按照 upload.md 将本地 Skill 上传到小红书 SkillHub，或要求检查 CLI 版本、登录授权、取消登录时使用。固定使用 1.0 版本线中补丁号 z 最新的 CLI，完成安装更新、二维码授权、打包、上传、确认和提交。
 ---
 
 # redskillhub-upload
 
-## 触发
+## 运行环境
 
-当用户说“按照 https://redskill.xiaohongshu.net/upload.md 把 <skill-name-or-path> 上传到小红书 SkillHub”或提出等价上传请求时，读取 upload.md 指令，并使用本 skill 驱动 `redskillhub-upload` CLI。
+所有 CLI 命令都必须显式带上同一个环境参数：生产环境用 `--env prod`（也是 CLI 默认值），测试环境用 `--env beta`。用户未指定时选择 `prod`；用户明确说 beta、测试环境或联调环境时选择 `beta`。确定后记为 `<ENV>`，本次流程中的标签、dry-run、真实 publish、login、whoami、logout 和取消等待命令均追加 `--env <ENV>`，不得混用。beta 业务接口由 CLI 自动选择 `https://edith.beta.xiaohongshu.com`，Agent 不自行传 `--api-base`。
+
+## CLI 版本门禁
+
+在执行任何 `redskillhub-upload` 命令前，先从本 Skill 目录执行：
+
+```bash
+node <SKILL_DIR>/scripts/ensure-cli.mjs --env <ENV>
+```
+
+`<SKILL_DIR>` 是包含本文件的目录，执行前替换为其绝对路径。
+
+脚本固定 `x=1`、`y=0`，查询 npm 后选择最大的兼容版本：存在正式版时只选最大的 `1.0.z`；尚无正式版时才选择同一版本线的最新预发布版。脚本会检查全局安装状态，按需安装或升级，并用 `redskillhub-upload whoami --env <ENV>` 验证命令。
+
+- 读取 `CLI_VERSION_JSON`；`status=current|installed|updated` 才继续。
+- `status=error` 时如实告诉用户并停止，不得改用其他 major/minor、不得静默安装本地源码、不得使用 `sudo`。
+- 不要在 Agent 中重写版本比较逻辑；以 `scripts/ensure-cli.mjs` 为唯一实现。
 
 ## 目标流程
 
 1. 回复用户：收到。我会在电脑上读取 upload.md 说明，检查 Red Skill CLI 和本地 Skill。
-2. 确认 CLI 可用：优先使用当前仓库的 `tools/redskillhub-upload`，或确认 `redskillhub-upload` 已在 PATH 中。不可用时先说明缺少 CLI。
+2. 执行「CLI 版本门禁」，确保 PATH 中的 `redskillhub-upload` 是允许版本线内的最新包。
 3. 查找用户给出的本地 Skill 目录或 `.zip` 源包。用户只给名称时，先在当前工作区和常见目录查找唯一匹配目录；找不到或多匹配时询问用户绝对路径。zip 只能作为 CLI 输入源包，不能由 agent 解压或代替 CLI 重新打包。
 4. 直接执行下面的「publish 子流程」，不要预先调用 `whoami` 或 `login`。真实 `publish` 会自动复用或刷新已有凭证；首次登录或 refresh token 失效时，会在同一进程中输出授权 `PROMPT`，授权成功后原地继续发布。
-5. 遇到授权 `PROMPT` 且存在 `prompt.qrCodePath` 时，先把本地 PNG 作为二维码图片展示或发送给用户，再把授权链接和 `XXXX-XXXX` 用户授权码转成聊天消息。二维码图片不计入下方文字模板；授权文字必须照抄模板，只替换 `<AUTH_URL>`、`<USER_CODE>`、`<MINUTES>`，不增删措辞。
+5. 遇到授权 `PROMPT` 时，必须同时返回二维码图片和链接：把 `prompt.qrCodePath` 的本地 PNG 展示或发送给用户；文字链接使用 `prompt.authorizeH5Url`（兼容字段 `prompt.authorizeUrl` 也是同一 H5 URL）。二维码由 CLI 使用接口的 `authorize_common_url` 生成，Agent 不得自行换字段或重新编码。二维码图片不计入下方文字模板；授权文字必须照抄模板，只替换 `<AUTH_URL>`、`<USER_CODE>`、`<MINUTES>`，不增删措辞。
 
 ````markdown
 请用手机自带浏览器打开下面的授权链接，打开后会自动跳转到小红书 App 完成授权：
@@ -31,7 +47,7 @@ description: 当用户要求按照 upload.md 将本地 Skill 上传到小红书
 ````
 
 6. 正常情况下等待 CLI 轮询完成并在同一 `publish` 进程中自动继续。用户回复”好了”只是兜底唤醒：仅当 CLI 轮询已完成但 agent 没有恢复时使用；进程中断或状态丢失时，重新执行原 `publish` 命令，CLI 会自动从磁盘恢复未完成的授权状态，无需用户重新打开授权链接。
-   用户明确要求取消登录等待时，执行 `redskillhub-upload login --cancel`；不要仅终止当前 shell，因为取消命令还会清理待授权状态和二维码。
+   用户明确要求取消登录等待时，执行 `redskillhub-upload login --cancel --env <ENV>`；不要仅终止当前 shell，因为取消命令还会清理待授权状态和二维码。
 7. 所有发布字段值取自用户当前会话答复，不要从 SKILL.md / 目录名 / 文件结构 / 上下文对话推断。
 8. publish 子流程结束后，把 `RESULT_JSON` 的成功结果、失败原因或取消状态如实转述给用户。
 
@@ -44,10 +60,10 @@ description: 当用户要求按照 upload.md 将本地 Skill 上传到小红书
 (a) 先拉一次实时标签列表，命令：
 
 ```bash
-node -e "import('./cli/tags.mjs').then(({loadContentTags}) => loadContentTags().then(t => console.log(JSON.stringify(t.map(x => x.name)))))"
+node -e "import('./cli/tags.mjs').then(({loadContentTags}) => loadContentTags({flags:{env:'<ENV>'}}).then(t => console.log(JSON.stringify(t.map(x => x.name)))))"
 ```
 
-（如果跑的是 PATH 上的 `redskillhub-upload` 而非仓库源码，没有 tags.mjs 入口，就直接 curl `https://edith-skillhub.sl.beta.xiaohongshu.com/api/sns/v1/activity_platform/config/query_config?material_id=750&module_id=811` 取 `data[].tagName`。两条路只能挑一条，**不要硬编码标签清单**。）
+（如果跑的是 PATH 上的 `redskillhub-upload` 而非仓库源码，没有 tags.mjs 入口，可使用与 `<ENV>` 对应的业务 host 请求 `/api/sns/v1/activity_platform/config/query_config?material_id=750&module_id=811` 取 `data[].tagName`。两条路只能挑一条，**不要硬编码标签清单**。）
 
 (b) 用 AskUserQuestion 一次发两题：
 
@@ -60,7 +76,7 @@ node -e "import('./cli/tags.mjs').then(({loadContentTags}) => loadContentTags().
 
 ```bash
 redskillhub-upload publish <absolute-path> --dry-run --agent \
-  --source <original|repost> --tag <中文标签名[,中文标签名...]> [--repost-source <来源名>]
+  --source <original|repost> --tag <中文标签名[,中文标签名...]> [--repost-source <来源名>] --env <ENV>
 ```
 
 读 `RESULT_JSON.payload`，把关键字段摘出来给用户看：`name`、Skill ID（payload 字段 `skill_identifier`）、`version`、`description`、`original`、`repost_source`、`content_tag_ids`。标签字段展示**中文名列表**，不要只甩 `tagId`。
@@ -76,7 +92,7 @@ redskillhub-upload publish <absolute-path> --dry-run --agent \
 
 ```bash
 printf 'submit\n' | redskillhub-upload publish <absolute-path> --agent \
-  --source <original|repost> --tag <中文标签名[,中文标签名...]> [--repost-source <来源名>]
+  --source <original|repost> --tag <中文标签名[,中文标签名...]> [--repost-source <来源名>] --env <ENV>
 ```
 
 不要带 `--yes`，让 CLI 进 confirm 阶段；`submit\n` 从 stdin 推给它即可。用户说「取消 / cancel」就把第二条命令换成 `printf 'cancel\n' | ...`。用户回复「好了」不能当成提交触发词。
@@ -93,16 +109,16 @@ printf 'submit\n' | redskillhub-upload publish <absolute-path> --agent \
 上传入口接受本地 skill 目录或 `.zip` 源包；zip 必须由 CLI 在本地解包、过滤、校验并重新生成上传包，不能由 agent 直接上传或改包。
 
 ```bash
-redskillhub-upload publish /absolute/path/to/skill --agent
-redskillhub-upload publish /absolute/path/to/skill.zip --agent
+redskillhub-upload publish /absolute/path/to/skill --agent --env <ENV>
+redskillhub-upload publish /absolute/path/to/skill.zip --agent --env <ENV>
 ```
 
-`redskillhub-upload whoami`、`redskillhub-upload login --agent`、`redskillhub-upload login --cancel` 仅用于诊断、显式预登录或取消等待，不属于标准发布前置步骤。
+`redskillhub-upload whoami --env <ENV>`、`redskillhub-upload login --agent --env <ENV>`、`redskillhub-upload login --cancel --env <ENV>` 仅用于诊断、显式预登录或取消等待，不属于标准发布前置步骤。
 
 本地验证可使用 dry-run。标签可直接传一个或多个中文名（CLI 内部完成 name→id 映射，多个用逗号分隔），也允许调试时传数字 id：
 
 ```bash
-node cli/index.mjs publish test/fixtures/minimal-skill --dry-run --agent --source original --tag 效率工具,内容创作 --yes
+node cli/index.mjs publish test/fixtures/minimal-skill --dry-run --agent --source original --tag 效率工具,内容创作 --yes --env beta
 # 或调试用：--tag-id 1001,1002
 ```
 

package/skill/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Red SkillHub 上传"
+  short_description: "安装最新兼容 CLI 并发布本地 Skill 到 SkillHub"
+  default_prompt: "使用 $redskillhub-upload 检查并安装 1.0 版本线的最新 CLI，然后将我指定的本地 Skill 发布到小红书 SkillHub。"

package/skill/scripts/ensure-cli.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_NAME = 'redskillhub-upload';
+const COMMAND_NAME = 'redskillhub-upload';
+const REGISTRY = 'https://registry.npmjs.org/';
+const REQUIRED_MAJOR = 1;
+const REQUIRED_MINOR = 0;
+
+function parseVersion(version) {
+  const match = String(version).match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  if (!match) return null;
+  return {
+    raw: version,
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] || ''
+  };
+}
+
+function comparePrerelease(a, b) {
+  if (!a && !b) return 0;
+  if (!a) return 1;
+  if (!b) return -1;
+  const left = a.split('.');
+  const right = b.split('.');
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    if (left[index] === undefined) return -1;
+    if (right[index] === undefined) return 1;
+    const leftNumber = /^\d+$/.test(left[index]) ? Number(left[index]) : null;
+    const rightNumber = /^\d+$/.test(right[index]) ? Number(right[index]) : null;
+    if (leftNumber !== null && rightNumber !== null && leftNumber !== rightNumber) {
+      return leftNumber - rightNumber;
+    }
+    if (leftNumber !== null && rightNumber === null) return -1;
+    if (leftNumber === null && rightNumber !== null) return 1;
+    const compared = left[index].localeCompare(right[index]);
+    if (compared) return compared;
+  }
+  return 0;
+}
+
+function compareVersions(a, b) {
+  if (a.patch !== b.patch) return a.patch - b.patch;
+  return comparePrerelease(a.prerelease, b.prerelease);
+}
+
+export function selectLatestCompatibleVersion(versions, options = {}) {
+  const major = options.major ?? REQUIRED_MAJOR;
+  const minor = options.minor ?? REQUIRED_MINOR;
+  const compatible = versions
+    .map(parseVersion)
+    .filter((version) => version && version.major === major && version.minor === minor);
+  if (!compatible.length) {
+    throw new Error(`npm 中没有找到 ${major}.${minor} 版本线的 ${PACKAGE_NAME}`);
+  }
+  const stable = compatible.filter((version) => !version.prerelease);
+  const candidates = stable.length ? stable : compatible;
+  candidates.sort(compareVersions);
+  return candidates.at(-1).raw;
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    stdio: options.capture ? 'pipe' : 'inherit'
+  });
+  if (result.error) throw result.error;
+  if (!options.allowFailure && result.status !== 0) {
+    const detail = options.capture ? String(result.stderr || result.stdout || '').trim() : '';
+    throw new Error(`${command} 执行失败${detail ? `：${detail}` : ''}`);
+  }
+  return result;
+}
+
+function queryVersions() {
+  const result = run('npm', [
+    'view',
+    PACKAGE_NAME,
+    'versions',
+    '--json',
+    `--registry=${REGISTRY}`
+  ], { capture: true });
+  const versions = JSON.parse(result.stdout);
+  return Array.isArray(versions) ? versions : [versions];
+}
+
+function readInstalledVersion() {
+  const result = run('npm', [
+    'list',
+    '--global',
+    PACKAGE_NAME,
+    '--depth=0',
+    '--json'
+  ], { capture: true, allowFailure: true });
+  try {
+    return JSON.parse(result.stdout)?.dependencies?.[PACKAGE_NAME]?.version || '';
+  } catch {
+    return '';
+  }
+}
+
+function installVersion(version) {
+  run('npm', [
+    'install',
+    '--global',
+    `${PACKAGE_NAME}@${version}`,
+    `--registry=${REGISTRY}`
+  ]);
+}
+
+export function normalizeCliEnvironment(value = 'prod') {
+  const envName = String(value).trim().toLowerCase();
+  if (envName !== 'prod' && envName !== 'beta') {
+    throw new Error(`--env 仅支持 prod 或 beta，当前值：${value}`);
+  }
+  return envName;
+}
+
+export function ensureCli(options = {}) {
+  const envName = normalizeCliEnvironment(options.env);
+  const latestVersion = selectLatestCompatibleVersion(queryVersions());
+  const previousVersion = readInstalledVersion();
+  let status = 'current';
+  if (previousVersion !== latestVersion) {
+    installVersion(latestVersion);
+    status = previousVersion ? 'updated' : 'installed';
+  }
+  const installedVersion = readInstalledVersion();
+  if (installedVersion !== latestVersion) {
+    throw new Error(`版本校验失败：期望 ${latestVersion}，实际 ${installedVersion || '未安装'}`);
+  }
+  run(COMMAND_NAME, ['whoami', '--env', envName]);
+  return { status, previousVersion: previousVersion || null, version: installedVersion };
+}
+
+function readEnvironmentArg(argv) {
+  const index = argv.indexOf('--env');
+  if (index === -1) return 'prod';
+  return argv[index + 1];
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  try {
+    process.stdout.write(`CLI_VERSION_JSON:${JSON.stringify(ensureCli({
+      env: readEnvironmentArg(process.argv.slice(2))
+    }))}\n`);
+  } catch (error) {
+    process.stderr.write(`CLI_VERSION_JSON:${JSON.stringify({
+      status: 'error',
+      message: error?.message || String(error)
+    })}\n`);
+    process.exit(1);
+  }
+}