redskillhub-upload 1.0.0-alpha.4 → 1.0.0-alpha.5

package/README.md

@@ -2,6 +2,8 @@
 
 Node.js CLI for uploading local Skills to 小红书 SkillHub.
 
+支持 macOS 和 Windows（PowerShell / cmd）。要求 Node.js 18 或更高版本；包含空格或中文的本地路径应使用双引号包裹。
+
 Install from the public npm registry:
 
 ```bash
@@ -29,6 +31,7 @@ All paths and hosts are centralized in `cli/config.mjs` (`PATHS` + `DEFAULT_API_
 - `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`
+- prod 沿用 `~/.skillhub-upload`，beta 使用 `~/.skillhub-upload/beta`，凭证、待授权、二维码、标签缓存和临时包相互隔离
 - 业务接口 host 可通过 `--api-base` 参数或 `SKILLHUB_UPLOAD_API_BASE` 环境变量覆盖
 - OAS 换 token 默认使用内置应用凭证；可通过 `SKILLHUB_UPLOAD_APP_SECRET` 覆盖
 
@@ -60,9 +63,10 @@ Dry-run examples may use numeric tag IDs because the backend contract accepts `c
 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 tags --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
 ```
@@ -71,11 +75,19 @@ redskillhub-upload logout --env prod
 
 ```bash
 redskillhub-upload login --agent --env beta
-redskillhub-upload publish /absolute/path/to/skill --agent --env beta
+redskillhub-upload tags --env beta
+redskillhub-upload publish "/absolute/path/to/skill" --agent --env beta
 redskillhub-upload whoami --env beta
 redskillhub-upload logout --env beta
 ```
 
+Windows 路径示例：
+
+```powershell
+redskillhub-upload publish "C:\Users\name\path\to\skill" --agent --env prod
+node -e "process.stdout.write('submit\n')" | redskillhub-upload publish "C:\Users\name\path\to\skill" --agent --source original --tag "效率工具" --env prod
+```
+
 ## Agent Protocol
 
 See `docs/protocol.md` for the line protocol:

package/cli/auth-prompt.mjs

@@ -8,6 +8,7 @@ export async function renderDeviceAuthPrompt(payload, options = {}) {
   const {
     agent = false,
     env = process.env,
+    flags = {},
     stream = process.stdout,
     qrCode = QRCode
   } = options;
@@ -25,7 +26,7 @@ export async function renderDeviceAuthPrompt(payload, options = {}) {
   };
 
   if (agent) {
-    const qrCodePath = getAuthQrPath(env);
+    const qrCodePath = getAuthQrPath(env, flags);
     await fs.mkdir(path.dirname(qrCodePath), { recursive: true, mode: 0o700 });
     await qrCode.toFile(qrCodePath, authorizeCommonUrl, {
       type: 'png',

package/cli/auth.mjs

@@ -12,7 +12,7 @@ import {
   TOKEN_REFRESH_BUFFER_MS,
   getAuthQrPath,
   getCredentialsPath,
-  getHomeDir,
+  getEnvironmentHomeDir,
   getPendingAuthPath,
   resolveApiBase
 } from './config.mjs';
@@ -46,9 +46,9 @@ function canRefreshCredentials(credentials, nowMs = Date.now()) {
   return Number.isFinite(refreshExpireTimeMs) && refreshExpireTimeMs > nowMs + TOKEN_REFRESH_BUFFER_MS;
 }
 
-export async function readCredentials(env = process.env) {
+export async function readCredentials(env = process.env, flags = {}) {
   try {
-    const file = getCredentialsPath(env);
+    const file = getCredentialsPath(env, flags);
     await fs.chmod(file, 0o600).catch(() => {});
     return JSON.parse(await fs.readFile(file, 'utf8'));
   } catch (error) {
@@ -57,9 +57,9 @@ export async function readCredentials(env = process.env) {
   }
 }
 
-export async function writeCredentials(credentials, env = process.env) {
-  const home = getHomeDir(env);
-  const file = getCredentialsPath(env);
+export async function writeCredentials(credentials, env = process.env, flags = {}) {
+  const home = getEnvironmentHomeDir(env, flags);
+  const file = getCredentialsPath(env, flags);
   const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
   await fs.mkdir(home, { recursive: true, mode: 0o700 });
   try {
@@ -73,8 +73,8 @@ export async function writeCredentials(credentials, env = process.env) {
   }
 }
 
-export async function removeCredentials(env = process.env) {
-  await fs.rm(getCredentialsPath(env), { force: true });
+export async function removeCredentials(env = process.env, flags = {}) {
+  await fs.rm(getCredentialsPath(env, flags), { force: true });
 }
 
 export function maskCredentials(credentials) {
@@ -306,9 +306,9 @@ function buildCredentialsFromToken(token, nowMs, errorCode) {
   return credentials;
 }
 
-async function readPendingAuth(env, now) {
+async function readPendingAuth(env, flags, now) {
   try {
-    const raw = JSON.parse(await fs.readFile(getPendingAuthPath(env), 'utf8'));
+    const raw = JSON.parse(await fs.readFile(getPendingAuthPath(env, flags), 'utf8'));
     if (raw?.expiresAtMs && raw.expiresAtMs > now() && raw.deviceCode && raw.codeVerifier) {
       return raw;
     }
@@ -318,26 +318,26 @@ async function readPendingAuth(env, now) {
   return null;
 }
 
-async function writePendingAuth(env, state) {
-  const file = getPendingAuthPath(env);
+async function writePendingAuth(env, flags, state) {
+  const file = getPendingAuthPath(env, flags);
   await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
   await fs.writeFile(file, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
 }
 
-async function clearPendingAuth(env) {
-  await fs.rm(getPendingAuthPath(env), { force: true });
-  await fs.rm(getAuthQrPath(env), { force: true });
+async function clearPendingAuth(env, flags) {
+  await fs.rm(getPendingAuthPath(env, flags), { force: true });
+  await fs.rm(getAuthQrPath(env, flags), { force: true });
 }
 
-export async function cancelLogin(env = process.env) {
+export async function cancelLogin(env = process.env, flags = {}) {
   let hadPending = true;
   try {
-    await fs.access(getPendingAuthPath(env));
+    await fs.access(getPendingAuthPath(env, flags));
   } catch (error) {
     if (error.code !== 'ENOENT') throw error;
     hadPending = false;
   }
-  await clearPendingAuth(env);
+  await clearPendingAuth(env, flags);
   return { hadPending };
 }
 
@@ -349,7 +349,7 @@ export async function login({
   now = () => Date.now(),
   promptStream = process.stdout
 } = {}) {
-  const cachedCredentials = await readCredentials(env);
+  const cachedCredentials = await readCredentials(env, flags);
   if (isValidCredentials(cachedCredentials, now())) {
     return maskCredentials(cachedCredentials);
   }
@@ -365,8 +365,8 @@ export async function login({
         tokenUrl: flags.tokenUrl || `${DEFAULT_OAS_BASE}${PATHS.OAS_REFRESH_TOKEN}`,
         fetchImpl
       });
-      await writeCredentials(buildCredentialsFromToken(token, now(), 'OAS_TOKEN_REFRESH_INVALID_RESPONSE'), env);
-      return maskCredentials(await readCredentials(env));
+      await writeCredentials(buildCredentialsFromToken(token, now(), 'OAS_TOKEN_REFRESH_INVALID_RESPONSE'), env, flags);
+      return maskCredentials(await readCredentials(env, flags));
     } catch (error) {
       if (error instanceof SkillhubUploadError) {
         // 刷新失败，降级走设备码
@@ -379,7 +379,7 @@ export async function login({
   const apiBase = resolveApiBase(flags, env);
 
   // 从磁盘恢复未完成的授权状态，避免进程重启后要求用户重新授权
-  let pending = await readPendingAuth(env, now);
+  let pending = await readPendingAuth(env, flags, now);
   let codeVerifier;
   if (pending) {
     codeVerifier = pending.codeVerifier;
@@ -390,12 +390,12 @@ export async function login({
       userCode: pending.userCode,
       expiresInSeconds: Math.round((pending.expiresAtMs - now()) / 1000),
       message: '检测到未完成的授权，继续等待中（无需重新打开授权链接）'
-    }, { agent: Boolean(flags.agent), env, stream: promptStream });
+    }, { agent: Boolean(flags.agent), env, flags, stream: promptStream });
   } else {
     const pkce = await createPkcePair();
     codeVerifier = pkce.codeVerifier;
     const device = await requestDeviceCode({ apiBase, pkce, fetchImpl });
-    await writePendingAuth(env, {
+    await writePendingAuth(env, flags, {
       deviceCode: device.deviceCode,
       codeVerifier: pkce.codeVerifier,
       authorizeCommonUrl: device.authorizeCommonUrl,
@@ -405,7 +405,7 @@ export async function login({
       pollIntervalSeconds: device.pollIntervalSeconds || 5,
       expiresAtMs: now() + (device.expiresInSeconds || 600) * 1000
     });
-    pending = await readPendingAuth(env, now);
+    pending = await readPendingAuth(env, flags, now);
     await renderDeviceAuthPrompt({
       type: 'auth_device_code',
       authorizeCommonUrl: device.authorizeCommonUrl,
@@ -413,7 +413,7 @@ export async function login({
       userCode: device.userCode,
       expiresInSeconds: device.expiresInSeconds || 600,
       message: '请用手机自带浏览器打开授权链接，页面会自动跳转至小红书 App 授权；授权页输入授权码后 CLI 会自动轮询'
-    }, { agent: Boolean(flags.agent), env, stream: promptStream });
+    }, { agent: Boolean(flags.agent), env, flags, stream: promptStream });
   }
 
   const deadline = pending.expiresAtMs;
@@ -422,7 +422,7 @@ export async function login({
     while (now() < deadline) {
       await sleep((pending.pollIntervalSeconds || 5) * 1000);
       // 这里只检测跨进程取消，不把自然过期误判为取消。
-      const activePending = await readPendingAuth(env, () => 0);
+      const activePending = await readPendingAuth(env, flags, () => 0);
       if (!activePending || activePending.deviceCode !== pending.deviceCode) {
         throw new SkillhubUploadError(
           'AUTH_CANCELLED',
@@ -437,21 +437,21 @@ export async function login({
         break;
       }
       if (authStatus === 'expired') {
-        await clearPendingAuth(env);
+        await clearPendingAuth(env, flags);
         throw new SkillhubUploadError('AUTH_TIMEOUT', '授权超时，请重新发起', ExitCodes.AUTH);
       }
       if (authStatus === 'cancelled' || authStatus === 'denied' || authStatus === 'rejected') {
-        await clearPendingAuth(env);
+        await clearPendingAuth(env, flags);
         throw new SkillhubUploadError('AUTH_DENIED', '用户拒绝授权', ExitCodes.AUTH);
       }
     }
     if (!authorizationCode) {
-      await clearPendingAuth(env);
+      await clearPendingAuth(env, flags);
       throw new SkillhubUploadError('AUTH_TIMEOUT', '授权超时，请重新发起', ExitCodes.AUTH);
     }
   } catch (error) {
     if (!(error instanceof SkillhubUploadError)) {
-      await clearPendingAuth(env);
+      await clearPendingAuth(env, flags);
     }
     throw error;
   }
@@ -464,7 +464,7 @@ export async function login({
     tokenUrl: flags.tokenUrl || `${DEFAULT_OAS_BASE}${PATHS.OAS_ACCESS_TOKEN}`,
     fetchImpl
   });
-  await writeCredentials(buildCredentialsFromToken(token, now(), 'OAS_TOKEN_EXCHANGE_INVALID_RESPONSE'), env);
-  await clearPendingAuth(env);
-  return maskCredentials(await readCredentials(env));
+  await writeCredentials(buildCredentialsFromToken(token, now(), 'OAS_TOKEN_EXCHANGE_INVALID_RESPONSE'), env, flags);
+  await clearPendingAuth(env, flags);
+  return maskCredentials(await readCredentials(env, flags));
 }

package/cli/config.mjs

@@ -28,24 +28,29 @@ export function getHomeDir(env = process.env) {
   return env.SKILLHUB_UPLOAD_HOME || path.join(os.homedir(), '.skillhub-upload');
 }
 
-export function getCredentialsPath(env = process.env) {
-  return path.join(getHomeDir(env), 'credentials.json');
+export function getEnvironmentHomeDir(env = process.env, flags = {}) {
+  const home = getHomeDir(env);
+  return resolveApiEnvironment(flags) === 'beta' ? path.join(home, 'beta') : home;
 }
 
-export function getTmpDir(env = process.env) {
-  return path.join(getHomeDir(env), 'tmp');
+export function getCredentialsPath(env = process.env, flags = {}) {
+  return path.join(getEnvironmentHomeDir(env, flags), 'credentials.json');
 }
 
-export function getContentTagCachePath(env = process.env) {
-  return path.join(getHomeDir(env), 'content-tags.json');
+export function getTmpDir(env = process.env, flags = {}) {
+  return path.join(getEnvironmentHomeDir(env, flags), 'tmp');
 }
 
-export function getPendingAuthPath(env = process.env) {
-  return path.join(getHomeDir(env), 'pending-auth.json');
+export function getContentTagCachePath(env = process.env, flags = {}) {
+  return path.join(getEnvironmentHomeDir(env, flags), 'content-tags.json');
 }
 
-export function getAuthQrPath(env = process.env) {
-  return path.join(getHomeDir(env), 'auth-qr.png');
+export function getPendingAuthPath(env = process.env, flags = {}) {
+  return path.join(getEnvironmentHomeDir(env, flags), 'pending-auth.json');
+}
+
+export function getAuthQrPath(env = process.env, flags = {}) {
+  return path.join(getEnvironmentHomeDir(env, flags), 'auth-qr.png');
 }
 
 export function resolveApiEnvironment(flags = {}) {

package/cli/index.mjs

@@ -93,7 +93,7 @@ export async function ensurePublishCredentials({
   readCredentials,
   login
 }) {
-  let credentials = await readCredentials(env);
+  let credentials = await readCredentials(env, flags);
   try {
     assertUsableCredentials(credentials, nowMs);
     return credentials;
@@ -111,7 +111,7 @@ export async function ensurePublishCredentials({
     now: io.now,
     promptStream: io.out || process.stdout
   });
-  credentials = await readCredentials(env);
+  credentials = await readCredentials(env, flags);
   assertUsableCredentials(credentials, io.now ? io.now() : nowMs);
   return credentials;
 }
@@ -182,7 +182,7 @@ export async function main(argv = process.argv.slice(2), env = process.env, io =
   if (!command) {
     throw new SkillhubUploadError(
       'INVALID_ARGS',
-      '请指定要执行的操作：login、publish、whoami 或 logout',
+      '请指定要执行的操作：login、publish、tags、whoami 或 logout',
       ExitCodes.INVALID_ARGS
     );
   }
@@ -193,19 +193,29 @@ export async function main(argv = process.argv.slice(2), env = process.env, io =
   }
   if (command === 'whoami') {
     const { readCredentials, maskCredentials } = await import('./auth.mjs');
-    writeResult({ status: 'ok', command, credentials: maskCredentials(await readCredentials(env)) }, out);
+    writeResult({ status: 'ok', command, credentials: maskCredentials(await readCredentials(env, flags)) }, out);
     return;
   }
   if (command === 'logout') {
     const { removeCredentials } = await import('./auth.mjs');
-    await removeCredentials(env);
+    await removeCredentials(env, flags);
     writeResult({ status: 'ok', command }, out);
     return;
   }
+  if (command === 'tags') {
+    const tags = await loadContentTags({
+      fetchImpl: io.fetchImpl,
+      env,
+      now: io.now,
+      flags
+    });
+    writeResult({ status: 'ok', command, tags }, out);
+    return;
+  }
   if (command === 'login') {
     if (flags.cancel) {
       const { cancelLogin } = await import('./auth.mjs');
-      const cancelled = await cancelLogin(env);
+      const cancelled = await cancelLogin(env, flags);
       writeResult({ status: 'cancelled', command, ...cancelled }, out);
       return;
     }
@@ -240,7 +250,7 @@ export async function main(argv = process.argv.slice(2), env = process.env, io =
       });
     }
 
-    const bundle = await prepareBundle(pathArg, { env });
+    const bundle = await prepareBundle(pathArg, { env, flags });
     const bundleMetadata = {
       bundleSha256: bundle.bundleSha256,
       bundleSizeBytes: bundle.bundleSizeBytes
@@ -298,7 +308,7 @@ export async function main(argv = process.argv.slice(2), env = process.env, io =
       promptSession.close();
     }
   }
-  throw new SkillhubUploadError('INVALID_ARGS', `不支持的操作：${command}，可用操作：login、publish、whoami、logout`, ExitCodes.INVALID_ARGS);
+  throw new SkillhubUploadError('INVALID_ARGS', `不支持的操作：${command}，可用操作：login、publish、tags、whoami、logout`, ExitCodes.INVALID_ARGS);
 }
 
 function isMainModule() {

package/cli/pack.mjs

@@ -267,8 +267,8 @@ function isAllowedExtension(file) {
   return ALLOWED_EXTENSIONS.has(path.extname(file).toLowerCase());
 }
 
-async function createTempZipPath(env) {
-  const dir = await fs.mkdtemp(path.join(getTmpDir(env), `bundle-${process.pid}-`));
+async function createTempZipPath(env, flags) {
+  const dir = await fs.mkdtemp(path.join(getTmpDir(env, flags), `bundle-${process.pid}-`));
   return path.join(dir, `${crypto.randomUUID()}.zip`);
 }
 
@@ -441,14 +441,14 @@ async function prepareZipSource(inputPath) {
   };
 }
 
-async function buildBundle(source, env) {
+async function buildBundle(source, env, flags) {
   const parsed = parseSkillMarkdown(source.markdown);
   const zip = new AdmZip();
   for (const file of source.files) {
     zip.addFile(file.entryName, file.data);
   }
 
-  const zipPath = await createTempZipPath(env);
+  const zipPath = await createTempZipPath(env, flags);
   zip.writeZip(zipPath);
   const zipStat = await fs.stat(zipPath);
 
@@ -468,6 +468,7 @@ async function buildBundle(source, env) {
 
 export async function prepareBundle(inputPath, options = {}) {
   const env = options.env || process.env;
+  const flags = options.flags || {};
   const stat = await fs.lstat(inputPath).catch(() => null);
   if (!stat) {
     throw new SkillhubUploadError('LOCAL_VALIDATION_FAILED', `路径不存在：${inputPath}，请输入正确的 skill 目录或 zip 文件`, ExitCodes.LOCAL_VALIDATION);
@@ -475,7 +476,7 @@ export async function prepareBundle(inputPath, options = {}) {
   if (stat.isSymbolicLink()) {
     throw new SkillhubUploadError('LOCAL_VALIDATION_FAILED', '输入路径是符号链接，请输入真实的 skill 目录或 zip 文件', ExitCodes.LOCAL_VALIDATION);
   }
-  await fs.mkdir(getTmpDir(env), { recursive: true, mode: 0o700 });
+  await fs.mkdir(getTmpDir(env, flags), { recursive: true, mode: 0o700 });
 
   let source;
   if (stat.isDirectory()) {
@@ -490,5 +491,5 @@ export async function prepareBundle(inputPath, options = {}) {
     );
   }
 
-  return await buildBundle(source, env);
+  return await buildBundle(source, env, flags);
 }

package/cli/tags.mjs

@@ -7,7 +7,7 @@ import {
   CONTENT_TAG_MODULE_ID,
   PATHS,
   getContentTagCachePath,
-  getHomeDir,
+  getEnvironmentHomeDir,
   resolveApiBase
 } from './config.mjs';
 import { compatibleFetch } from './fetch.mjs';
@@ -122,7 +122,7 @@ export async function loadContentTags({
   if (env.SKILLHUB_UPLOAD_SKIP_REMOTE_TAGS === '1') {
     return FALLBACK_CONTENT_TAGS.map((tag) => ({ ...tag }));
   }
-  const cachePath = getContentTagCachePath(env);
+  const cachePath = getContentTagCachePath(env, flags);
   const nowMs = typeof now === 'function' ? now() : Number(now) || Date.now();
   const cached = await readCachedContentTags(cachePath);
   if (cached && nowMs - cached.fetchedAtMs < cacheTtlMs) {
@@ -145,6 +145,6 @@ export async function loadContentTags({
   }
 }
 
-export function getContentTagsHomeDir(env = process.env) {
-  return getHomeDir(env);
+export function getContentTagsHomeDir(env = process.env, flags = {}) {
+  return getEnvironmentHomeDir(env, flags);
 }

package/package.json

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

package/skill/SKILL.md

@@ -9,12 +9,28 @@ description: 当用户要求安装或更新 redskillhub-upload、按照 upload.m
 
 所有 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 按环境隔离本地状态：prod 保留在 `~/.skillhub-upload`，beta 存放在其 `beta` 子目录。凭证、待授权状态、二维码、标签缓存和临时包不会跨环境复用。设置 `SKILLHUB_UPLOAD_HOME` 时，该路径作为环境目录的共同根目录。
+
+## 操作系统兼容
+
+本 Skill 必须同时支持 macOS 和 Windows。执行前通过 Node.js 判断系统，不依赖 `uname`：
+
+```bash
+node -p "process.platform"
+```
+
+- 输出 `darwin`：按 macOS 处理，路径形如 `/Users/name/path/to/skill`。
+- 输出 `win32`：按 Windows 处理，优先使用 PowerShell，路径形如 `C:\Users\name\path\to\skill`。
+- 所有传给 CLI 的本地路径都使用双引号包裹，兼容空格和中文。
+- 命令必须写成单行，不使用 Bash 的 `\` 续行、`printf`、`export`，也不使用 PowerShell 反引号续行或 `$env:`。
+- 需要向 stdin 写入确认值时，统一使用 `node -e "process.stdout.write('submit\n')"` 或 `node -e "process.stdout.write('cancel\n')"`，不要按系统拼两套管道命令。
+
 ## CLI 版本门禁
 
 在执行任何 `redskillhub-upload` 命令前，先从本 Skill 目录执行：
 
 ```bash
-node <SKILL_DIR>/scripts/ensure-cli.mjs --env <ENV>
+node "<SKILL_DIR>/scripts/ensure-cli.mjs" --env <ENV>
 ```
 
 `<SKILL_DIR>` 是包含本文件的目录，执行前替换为其绝对路径。
@@ -53,17 +69,17 @@ node <SKILL_DIR>/scripts/ensure-cli.mjs --env <ENV>
 
 ## publish 子流程
 
-固定 4 步，按顺序执行；步骤 1 用 AskUserQuestion 一次性收齐参数，步骤 2-3 把参数全部以 CLI flag 传入，避开 stdin piping。
+固定 4 步，按顺序执行；步骤 1 用 AskUserQuestion 一次性收齐参数，步骤 2 把参数全部以 CLI flag 传入，步骤 3 仅通过跨平台 Node 管道写入提交或取消指令。
 
 ### Step 1 — 一次性收齐 publish 参数
 
-(a) 先拉一次实时标签列表，命令：
+(a) 通过已安装的 CLI 拉一次当前环境标签列表，命令：
 
 ```bash
-node -e "import('./cli/tags.mjs').then(({loadContentTags}) => loadContentTags({flags:{env:'<ENV>'}}).then(t => console.log(JSON.stringify(t.map(x => x.name)))))"
+redskillhub-upload tags --env <ENV>
 ```
 
-（如果跑的是 PATH 上的 `redskillhub-upload` 而非仓库源码，没有 tags.mjs 入口，可使用与 `<ENV>` 对应的业务 host 请求 `/api/sns/v1/activity_platform/config/query_config?material_id=750&module_id=811` 取 `data[].tagName`。两条路只能挑一条，**不要硬编码标签清单**。）
+读取 `RESULT_JSON.tags` 中的 `name` 和 `tagId`。命令失败时如实报告并停止，不直接 curl 内部接口、不导入仓库源码，也**不硬编码标签清单**。
 
 (b) 用 AskUserQuestion 一次发两题：
 
@@ -75,8 +91,7 @@ node -e "import('./cli/tags.mjs').then(({loadContentTags}) => loadContentTags({f
 ### Step 2 — dry-run 出待提交载荷给用户审阅
 
 ```bash
-redskillhub-upload publish <absolute-path> --dry-run --agent \
-  --source <original|repost> --tag <中文标签名[,中文标签名...]> [--repost-source <来源名>] --env <ENV>
+redskillhub-upload publish "<absolute-path>" --dry-run --agent --source <original-or-repost> --tag "<中文标签名[,中文标签名...]>" [--repost-source "<来源名>"] --env <ENV>
 ```
 
 读 `RESULT_JSON.payload`，把关键字段摘出来给用户看：`name`、Skill ID（payload 字段 `skill_identifier`）、`version`、`description`、`original`、`repost_source`、`content_tag_ids`。标签字段展示**中文名列表**，不要只甩 `tagId`。
@@ -91,11 +106,10 @@ redskillhub-upload publish <absolute-path> --dry-run --agent \
 ### Step 3 — 用户明确说「提交 / 确认 / submit」后真实提交
 
 ```bash
-printf 'submit\n' | redskillhub-upload publish <absolute-path> --agent \
-  --source <original|repost> --tag <中文标签名[,中文标签名...]> [--repost-source <来源名>] --env <ENV>
+node -e "process.stdout.write('submit\n')" | redskillhub-upload publish "<absolute-path>" --agent --source <original-or-repost> --tag "<中文标签名[,中文标签名...]>" [--repost-source "<来源名>"] --env <ENV>
 ```
 
-不要带 `--yes`，让 CLI 进 confirm 阶段；`submit\n` 从 stdin 推给它即可。用户说「取消 / cancel」就把第二条命令换成 `printf 'cancel\n' | ...`。用户回复「好了」不能当成提交触发词。
+不要带 `--yes`，让 CLI 进 confirm 阶段；`submit\n` 从 stdin 推给它即可。用户说「取消 / cancel」就把输入命令换成 `node -e "process.stdout.write('cancel\n')"`。用户回复「好了」不能当成提交触发词。
 
 该命令会自动检查并恢复登录：凭证有效时直接发布，access token 过期时尝试静默刷新，必须重新授权时输出设备码 `PROMPT`；授权成功后仍由当前进程继续上传和提交，不要另起 `login` 命令。
 
@@ -109,8 +123,8 @@ printf 'submit\n' | redskillhub-upload publish <absolute-path> --agent \
 上传入口接受本地 skill 目录或 `.zip` 源包；zip 必须由 CLI 在本地解包、过滤、校验并重新生成上传包，不能由 agent 直接上传或改包。
 
 ```bash
-redskillhub-upload publish /absolute/path/to/skill --agent --env <ENV>
-redskillhub-upload publish /absolute/path/to/skill.zip --agent --env <ENV>
+redskillhub-upload publish "<absolute-path-to-skill>" --agent --env <ENV>
+redskillhub-upload publish "<absolute-path-to-skill.zip>" --agent --env <ENV>
 ```
 
 `redskillhub-upload whoami --env <ENV>`、`redskillhub-upload login --agent --env <ENV>`、`redskillhub-upload login --cancel --env <ENV>` 仅用于诊断、显式预登录或取消等待，不属于标准发布前置步骤。
@@ -118,7 +132,7 @@ redskillhub-upload publish /absolute/path/to/skill.zip --agent --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 --env beta
+node cli/index.mjs publish "test/fixtures/minimal-skill" --dry-run --agent --source original --tag "效率工具,内容创作" --yes --env beta
 # 或调试用：--tag-id 1001,1002
 ```
 

package/skill/scripts/ensure-cli.mjs

@@ -64,10 +64,16 @@ export function selectLatestCompatibleVersion(versions, options = {}) {
   return candidates.at(-1).raw;
 }
 
+export function shouldUseSystemShell(platform = process.platform) {
+  return platform === 'win32';
+}
+
 function run(command, args, options = {}) {
   const result = spawnSync(command, args, {
     encoding: 'utf8',
-    stdio: options.capture ? 'pipe' : 'inherit'
+    stdio: options.capture ? 'pipe' : 'inherit',
+    // npm 与全局 CLI 在 Windows 上是 .cmd shim，需要通过系统 shell 启动。
+    shell: shouldUseSystemShell(options.platform)
   });
   if (result.error) throw result.error;
   if (!options.allowFailure && result.status !== 0) {